Add xAI (Grok) as a first-class provider — API key + OAuth paths

[Hmbown]

Summary

CodeWhale has no xAI / Grok provider. The only grok reference in-tree is a model-family heuristic (crates/agent/src/lib.rs) that categorizes a model named grok-* for accounting — it does not connect CodeWhale to x.ai. Users can currently reach x.ai only via the Custom OpenAI-compatible provider with a hand-set API key, or via OpenRouter.

xAI now exposes two distinct authentication paths, and we should support both:

Path	Auth	Endpoint	Billing
API key	static Bearer token from console.x.ai	https://api.x.ai/v1	pay-per-use credits
OAuth 2.0 device code	account login against accounts.x.ai / auth.x.ai	OpenAI-compatible	SuperGrok / X Premium+ subscription

The API-key path is OpenAI Chat Completions–compatible and is the lower-risk first step. The OAuth path is the better experience (no key to manage, uses an existing subscription) and is well-suited to a TUI via the device-code flow (print URL + code → user approves in any browser → poll → done; no loopback HTTP listener required, which is ideal for SSH/remote/headless).

Reference for the OAuth/device-code path and current xAI model lineup: pi-xai-oauth and the Hermes Agent xAI Grok OAuth guide. Both confirm accounts.x.ai as the OAuth authority and document auto-reuse of the official Grok CLI token file (~/.grok/auth.json).

API-key provider (low effort, ship first)

Add a ProviderKind::Xai variant + a provider! macro entry + a ProvidersToml field + a registry slot, consistent with how the existing 31 providers are wired in crates/config/src/provider.rs and crates/config/src/provider_kind.rs.

Proposed metadata:

• id / key: xai
• display name: xAI
• base URL: https://api.x.ai/v1
• env vars: XAI_API_KEY
• default model: grok-4.5 (500K context) — see current catalog notes below
• wire format: ChatCompletions
• auth: Bearer token via existing Authorization: Bearer <key> path (crates/tui/src/client.rs)

Acceptance:

• [providers.xai] works with api_key set, env var, or keyring.
• grok-* models appear in /model and route through the xAI base URL.
• The existing ModelFamily::Grok heuristic continues to classify these for accounting.

OAuth path (follow-up, real work)

CodeWhale already has two bespoke OAuth integrations to model after — OpenAI Codex/ChatGPT (crates/tui/src/oauth.rs) and Moonshot Kimi (crates/tui/src/config.rs) — but there is no generic OAuth framework: each hardcodes its own client_id and token endpoint, and both follow a "delegate the login to an external CLI, then load + refresh the token file" pattern.

Two realistic routes for xAI OAuth:

• (a) Delegate-login pattern — detect and read ~/.grok/auth.json from the official Grok CLI, then load + refresh. Lowest effort, consistent with Codex/Kimi. Mirrors what pi-xai-oauth does (auto-detects ~/.grok/auth.json).
• (b) Native device-code flow — implement the accounts.x.ai device-code request + poll + token store + refresh directly. More work (no shared OAuth abstraction exists yet), but the device-code pattern is a clean fit for a terminal app and avoids depending on the Grok CLI being installed.

Either way, token redaction already knows about access_token / refresh_token / client_secret (crates/config/src/lib.rs) and the secrets crate handles 0600 file storage.

Acceptance:

• auth_mode = "oauth" (or similar) for [providers.xai] triggers the token path instead of api_key.
• Device-code login prints a verification URL + code for the user to open.
• Tokens are stored 0600 and refreshed before expiry (JWT exp + margin, matching the Codex approach).
• Remote/headless fallback: if localhost callbacks are unavailable, the TUI accepts a pasted redirect URL (the same UX pi-xai-oauth documents for VPN/Docker/SSH).

Caveat

xAI has been observed to return HTTP 403 to some SuperGrok tiers on the OAuth API surface even when the subscription is active (see OmniRoute feature request). OAuth should be offered alongside the API-key path, not as a replacement for it. The API-key path is the reliable one today.

Current xAI model catalog (as of Jul 2026, for the model list)

Model ID	Context	Notes
grok-4.5	500K	flagship, reasoning low/med/high (default high), text+image
grok-4.3	1M	full reasoning, long context
grok-build	512K	coding model (Grok CLI OAuth endpoint)
grok-composer-2.5-fast	200K	coding model (Grok CLI OAuth endpoint)
grok-4.20-0309-reasoning	2M	auto reasoning
grok-4.20-0309-non-reasoning	2M	fast responses

Pricing reference: grok-4.5 at $2/$6 per 1M input/output, $0.50 cache read.

Proposed scope for this issue

1. Ship the API-key provider first (low risk, works immediately).
2. Add xAI models to the catalog.
3. OAuth as a follow-up: start with the delegate-login pattern (read ~/.grok/auth.json), then consider a native device-code flow.

[Hmbown]

Update: the API-key provider slice landed on main via PR #4266, merge commit 4406c8bea2d6c2d87596cecf81ca93abeb983136.

Landed scope:

• ProviderKind::Xai / ApiProvider::Xai with aliases xai, x-ai, x_ai, grok.
• [providers.xai], XAI_API_KEY, XAI_BASE_URL, XAI_MODEL, keyring/env lookup, and default route https://api.x.ai/v1 + grok-4.5.
• Grok model catalog/completion entries and preservation of ModelFamily::Grok classification.
• Docs and config.example.toml coverage for the API-key path.

Verification:

• Local: cargo fmt --all -- --check, git diff --check, python3 scripts/check-provider-registry.py, focused config/secrets/tui/agent tests, cargo check -p codewhale-cli --locked, cargo check -p codewhale-tui --locked, co-author trailer guard.
• CI on feat(provider): add xAI API-key route (#4257) #4266: all checks green, including lint, CodeQL, macOS/Windows test jobs, and mobile runtime smoke.

Leaving this issue open intentionally: xAI OAuth/device-code support is still follow-up work and was not claimed by #4266.

[Hmbown]

Status audit (origin/main) — leaving OPEN

Tree: origin/main @ d429405f4f70740fea5600a45d9d2648103b7548

✅ API-key path landed (#4266)

Merge: PR #4266 → 4406c8bea2d6c2d87596cecf81ca93abeb983136 (feat commit 266ede2a6324058766137b8c3aab239f7a6634b3).

Evidence on main:

• ProviderKind::Xai — crates/config/src/provider_kind.rs:109
• provider! slot + env XAI_API_KEY — crates/config/src/provider.rs:621–628 (DEFAULT_XAI_BASE_URL / DEFAULT_XAI_MODEL)
• Config field — crates/config/src/lib.rs:180 (providers.xai)
• Secrets env aliases — crates/secrets/src/lib.rs:881 (xai/x-ai/x_ai/grok → XAI_API_KEY)
• Model catalog (agent) — crates/agent/src/lib.rs:875+ (grok-4.5, grok-4.3, grok-build, …)
• Docs — docs/PROVIDERS.md:282 documents API-key route and explicitly notes OAuth as follow-up

❌ OAuth / device-code path still missing

Issue scope step 3 (OAuth) is not on main:

• No auth_mode = "oauth" path for [providers.xai]
• No accounts.x.ai / device-code flow / ~/.grok/auth.json delegate-login integration in code (docs still say “OAuth/device-code support remains follow-up work”)

Leaving OPEN until the OAuth path lands (or the issue is explicitly rescoped to API-key-only).

[Hmbown]

Operator disposition (v0.8.68 wave)

API-key path: done on main via PR #4266 (4406c8bea) — ProviderKind::Xai, XAI_API_KEY, catalog, docs.

OAuth / device-code residual: still not on main (no auth_mode = oauth for xAI, no accounts.x.ai device-code, no ~/.grok/auth.json delegate). Size estimate L (bespoke OAuth, mirror Codex/Kimi patterns).

Release decision for this wave: keep issue OPEN for OAuth follow-up; do not block v0.8.68 tag on OAuth. Ship API-key as the supported xAI path for 0.8.68 unless Hunter prioritizes OAuth.

Next code slice when prioritized: device-code flow (TUI-friendly) + optional Grok CLI token reuse.