# pi-xai-supergrok

An OAuth provider extension for [pi](https://github.com/earendil-works/pi-mono) that lets you use your **SuperGrok** (grok.com) or **X Premium+** subscription with pi — no `XAI_API_KEY` required. You log in once through the browser (or a device code), and pi refreshes the token automatically.

It registers a provider called **`supergrok`**. Models are **discovered live** from `GET https://api.x.ai/v1/models` whenever credentials are available, so new `grok-*` ids appear without editing the extension. A static fallback catalog is used when discovery can't run (pre-login, offline, 403, …).

> **Unofficial.** Not affiliated with xAI. Reuses the public Grok-CLI OAuth `client_id` (a public client, not a secret) because xAI only accepts loopback OAuth from allowlisted clients. The consent screen may say "Grok Build" / "Grok CLI".

## Requirements

- [pi](https://github.com/earendil-works/pi-mono) installed
- An active **SuperGrok** subscription on your xAI account, **or** an **X Premium+** subscription on the X account you sign in with

> ⚠️ xAI may return **HTTP 403** for some SuperGrok tiers even after a successful browser login. In that case use an API key with pi's built-in `xai` provider (`export XAI_API_KEY=xai-...`).

## Install

```bash
# from npm (after publish)
pi install npm:pi-xai-supergrok

# from git
pi install git:github.com/preinpost/pi-xai-supergrok

# from a local checkout
pi install /path/to/pi-xai-supergrok

# one-shot without writing settings
pi -e npm:pi-xai-supergrok
```

> **Security:** pi packages run with full system access. Review the source before installing third-party packages.

Then restart pi (or start a new session). Confirm the provider is loaded:

```bash
pi --list-models | grep supergrok
```

## Usage

Inside pi:

```
/login supergrok
```

Pick a login method:

- **Browser (this machine)** — opens `accounts.x.ai` and captures the code on `http://127.0.0.1:56121/callback`. Best on your own laptop/desktop.
- **Device code** — for headless / SSH / container hosts. pi prints a URL and a short code; open the URL on any device, enter the code, approve. Only enter the code on an official xAI page.

After login, select a `grok-*` model and chat. Credentials are stored in `~/.pi/agent/auth.json` and refreshed in the background.

### Refresh the model list

Models are re-fetched automatically after a successful login. To force a re-discovery later:

```
/supergrok-refresh-models
```

## How it works

| Item | Value |
|---|---|
| Provider id | `supergrok` |
| Auth | OAuth 2.0 + PKCE (authorization-code with loopback, or RFC 8628 device code) |
| client_id | public Grok-CLI client (not a secret) |
| API base | `https://api.x.ai/v1` (OpenAI-compatible → `openai-completions`) |
| Model source | live `GET /v1/models` (chat models only), else static fallback |

### Model discovery

On extension load the factory (async):

1. Resolves a bearer token from `XAI_API_KEY`, or from `~/.pi/agent/auth.json` → `supergrok.access` (if not expired).
2. Calls `GET https://api.x.ai/v1/models`.
3. Keeps chat/completion models (drops `grok-imagine-*` image/video generators).
4. Maps xAI price fields into pi's `$/MTok` cost shape.
5. Infers reasoning / vision support from the model id and price fields.

If no token is available or the request fails, the built-in fallback list is registered instead. After `/login supergrok` the live catalog is re-fetched and the provider is re-registered so the new models show up without restarting pi.

### Env-var fallback

The provider also honors `XAI_API_KEY`. If it's set, you can use `supergrok` models without OAuth at all, and discovery uses the same key.

## Uninstall

```bash
pi remove npm:pi-xai-supergrok
# or
pi remove git:github.com/preinpost/pi-xai-supergrok
```

## Package layout

```
pi-xai-supergrok/
  index.ts            # extension entry (async factory)
  provider.ts         # registerProvider wiring
  oauth.ts            # PKCE browser + device-code + refresh
  models.ts           # live /v1/models discovery
  fallback-models.ts  # offline / pre-login catalog
  constants.ts        # endpoints, client_id, scopes
  package.json        # pi.extensions manifest
```

## License

MIT