feat(ai): add xAI subscription OAuth

[mwijanarko1]

Description

Prime Agent exposes xAI only through XAI_API_KEY, so users with a SuperGrok or X Premium subscription cannot authenticate from /login without separate API billing.

This adds xAI as a built-in OAuth provider using the RFC 8628 device-code flow already accepted upstream in earendil-works/pi#6651, including the prefilled verification URL behavior from earendil-works/pi#6734. The port targets Prime Agent's existing utils/oauth registry rather than copying Pi's newer provider architecture.

The flow validates browser-bound URLs as HTTPS, waits for the server polling interval, handles authorization_pending, slow_down, denial, expiry, and cancellation, preserves unrotated refresh tokens, and refreshes before token expiry. Grok 4.5 becomes the xAI default and is routed through /responses with the supported low/medium/high reasoning levels and encrypted reasoning continuity. Other xAI models retain their existing transport, and XAI_API_KEY remains available alongside subscription login.

Closes #678.

Steps to Reproduce Bug and Validate Solution

Reproduce

1. Start Prime Agent without XAI_API_KEY.
2. Run /login.
3. Observe that xAI is offered only as an API-key provider; there is no SuperGrok/X Premium subscription option.

Validate

1. Run /login and select xAI (Grok/X subscription).
2. Open the displayed HTTPS verification link and approve the device code.
3. Confirm the OAuth credential is stored under the existing xai auth key and can refresh automatically.
4. Send a prompt with the default Grok 4.5 model and confirm it uses https://api.x.ai/v1/responses.
5. Confirm xAI remains listed separately as an API-key option.

PR Checklist

• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All relevant new and existing tests passed.
• My code follows the code style of this project.
• I ran lint checks with no new errors or warnings.
• I checked for other open pull requests for the same change.

Does This Introduce a Breaking Change?

• Yes
• No

Testing

• OS/environment: macOS, Node.js 26.5.0
• Commands/checks:
  • cd packages/ai && npx tsx ../../node_modules/vitest/dist/cli.js --run test/xai-oauth.test.ts test/xai-responses.test.ts
  • cd packages/coding-agent && npx tsx ../../node_modules/vitest/dist/cli.js --run test/model-resolver.test.ts test/oauth-selector.test.ts
  • npm run check
• Results: 20 AI tests passed across OAuth and Responses routing; 60 coding-agent tests passed across model resolution and OAuth selection; formatting, type checking, installer rendering, and browser smoke checks passed.
• Live validation: A locally stored Grok CLI OAuth bearer successfully completed POST https://api.x.ai/v1/responses with Grok 4.5, including reasoning.summary: "auto" and encrypted reasoning content; no token material was logged.
• Scenarios covered: exact device and token request forms, delayed polling, pending responses, RFC 8628-compliant slow-down backoff, default interval handling, prefilled verification URLs, unsafe URL rejection, denial, device-code expiry, cancellation, refresh rotation/preservation, default expiry, malformed token responses, upstream error details, built-in registration, coexistence with API-key login, Grok 4.5 model routing, supported reasoning levels, bearer/session headers, cache compatibility, and encrypted reasoning continuity.

Other Information or Known Dependencies

This is intentionally scoped to authentication and avoids the unrelated Ollama Cloud and generated model-catalog changes currently combined in #652. It uses xAI's public Grok CLI OAuth client contract, matching the implementation accepted by Pi upstream.

---

Note

Medium Risk
Touches authentication and default model/API routing for xAI; OAuth and token refresh are security-sensitive but well-tested and scoped.

Overview
Adds SuperGrok / X Premium sign-in via RFC 8628 device-code OAuth (loginXai, registry entry, token refresh, cancellation, HTTPS-only verification URLs, and RFC-correct slow_down polling). XAI_API_KEY API billing remains; stored OAuth credentials take precedence after /login.

Grok 4.5 is now the default xAI model and uses the OpenAI Responses API (/responses) with low/medium/high reasoning and reasoning.encrypted_content on xAI requests; other Grok models stay on completions.

Docs, changelogs, coding-agent provider docs, and tests cover OAuth, model routing, and login selector behavior.

^{Reviewed by Cursor Bugbot for commit db04718. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add xAI subscription OAuth with device-code flow and route grok-4.5 via Responses API

• Implements device-code OAuth login and token refresh for xAI in xai.ts, registered as a built-in provider so getOAuthProvider("xai") works out of the box.
• Routes grok-4.5 through the OpenAI Responses API (instead of Completions) with reasoning.encrypted_content always included and a thinking level map that suppresses explicit effort for off/minimal modes.
• Auth failures on xAI Responses requests now surface a specific message prompting re-login or updating XAI_API_KEY.
• Changes the default xAI model in the coding agent from grok-4.20-0309-reasoning to grok-4.5.
• Behavioral Change: existing xAI users without an explicit model selection will now use grok-4.5 via the Responses API rather than the previous default via Completions.

^{Macroscope summarized dfeb0a7.}

[ss251]

Independent reproduction of the core mechanism, for reviewer confidence (2026-08-07, different machine/account, SuperGrok Heavy, XAI_API_KEY unset): a subscription session token issued to the official Grok CLI completes POST https://api.x.ai/v1/responses with grok-4.5, HTTP 200, real token usage accounting. So the endpoint/auth premise of this PR is not single-source — it reproduces.

Two observations from that testing, posted in more detail on #678:

1. There are two working rails, and they serve different model variants. The same subscription token also works against https://cli-chat-proxy.grok.com/v1/responses (the endpoint xAI's own bundled ~/.grok/README.md documents for auth.json token reuse, with grok-cli client headers) — but the proxy serves grok-4.5-build, the CLI-tuned variant, while api.x.ai serves plain grok-4.5. Nothing wrong with this PR's choice of api.x.ai; just flagging that the variants differ in case coding-tuned behavior is ever the expectation.

2. Shape trade-off, in this PR's favor. The alternative shape — delegating credentials entirely to the user's existing grok login by reading ~/.grok/auth.json at request time — has a smaller trust surface (the harness never acquires or refreshes xAI credentials), but inherits the CLI session token's ~weekly expiry with no refresh path, degrading to "re-run grok login every few days". The device flow with refresh implemented here is the better product experience, and its client contract matches what the Grok CLI itself uses. The read-only auth.json approach remains viable as a zero-code models.json recipe for released versions (details on /login has no xAI (Grok/X subscription) option — vendored packages/ai predates upstream's xAI OAuth #678).

One suggestion regardless of shape: whatever error surfaces when the stored token is expired/revoked, make it actionable (name the provider and the fix) rather than a raw HTTP 401 — subscription users will hit it on a schedule, unlike API-key users.

[mwijanarko1]

Thanks @ss251. I checked the current earendil-works/pi xAI integration first. It uses the same device flow and proactive refresh, but it does not special-case this recovery path: failed refreshes retain the provider-prefixed HTTP error, while a rejected Responses request is surfaced through the generic authentication formatter.

Fixed in dfeb0a7d:

• xAI Responses authentication failures now say to run /login and sign in to xAI again, or update XAI_API_KEY for API billing.
• Revoked/invalid refresh-token failures now retain the upstream xAI error details and append the /login recovery step.
• Added a focused HTTP 401 regression test and tightened the existing revoked-refresh assertion.

Verification:

• packages/ai: xAI OAuth + Responses tests, 21/21 passed.
• npm run check: Biome, TypeScript, installer render, and browser smoke checks passed.