[Feat] Add xAI Grok subscription OAuth

[pridemusvaire]

Summary

Adds SuperGrok / eligible X Premium+ as a first-class inference path in Roomote, next to the existing xAI API key (BYOK) path.

Operators can connect a Grok subscription with device-code OAuth, run xai/* models on that subscription, see usage bars in Models settings, and still keep or remove a separate XAI_API_KEY without breaking the other path.

What operators get

Surface	Behavior
Settings → Models	Separate catalog row xAI (Grok subscription) (xai-subscription, OAuth). Connect / reconnect / disconnect. Usage bars under the row when billing data is available. Existing xAI row stays API-key only (XAI_API_KEY).
Setup / onboarding	On the shared xAI surface: enter an API key and/or Connect Grok subscription. Continue works when either path is satisfied.
Runtime	xai/* models work with SuperGrok alone, API key alone, or both. When both are configured, subscription is preferred.
Docs	Models + env-var docs describe the dual path.

Connect copy is provider-specific (Connect Grok subscription, not ChatGPT).

How it works

Catalog split (same pattern as OpenAI API key vs ChatGPT subscription)

Catalog id	Auth	Role
xai	API key	BYOK via XAI_API_KEY
xai-subscription	OAuth	SuperGrok / eligible X Premium+ device-code flow

SuperGrok still serves xai/* model ids. When only the subscription is connected, setup/auto-add treat the xai catalog surface as available so models stay listed. Deleting the API key while SuperGrok remains strips only key env vars and does not remove xai/* models.

Control plane

• Device-code OAuth (public Grok CLI client id) → encrypted XAI_SUBSCRIPTION_OAUTH secret.
• Pending device state in a separate secret so cancel/restart cannot attach the wrong account.
• Concurrency: claim-before-HTTP on start, generation-scoped poll, dual advisory locks (device + refresh), CAS write-back on refresh, disconnect takes both locks so in-flight poll/refresh cannot resurrect credentials.
• Public status / poll / getFreshXaiAccessToken never return refresh tokens to callers.
• Transient refresh failures keep the connection; hard failures surface reconnect UI.

Inference

• Gateway authStrategy: 'xai-oauth': OAuth bearer first, then XAI_API_KEY, fail closed if neither.
• Worker sandbox gets R_INFERENCE_GATEWAY_XAI so OpenCode rebases xai onto the gateway without shipping tokens into the sandbox.
• Control-plane / non-gateway OpenCode paths inject a fresh SuperGrok access token as the API-key shaped credential when needed.

Usage bars

• Soft-fail fetch of the unofficial Grok CLI billing proxy (cli-chat-proxy.grok.com).
• Parses the live format=credits payload (config.creditUsagePercent, productUsage, { val } wrappers, period end) plus older synthetic shapes.
• Settings render included usage, per-product windows (e.g. GrokBuild / Api), and prepaid credits when present. Missing data = no bar, no error toast.

Hardening included (review + live test follow-ups)

• Device-flow races: poll cancel/reopen, claim before device-code HTTP, disconnect vs poll persist, disconnect vs refresh.
• Dual-path delete / connected-provider count / setup query for xai-subscription.
• OAuth dialog labels and onboarding dual-path Connect button (no ChatGPT copy for SuperGrok).
• Live billing parser so usage bars match real SuperGrok accounts.

Test plan

• Device-code start/poll success and failure; encrypted status (no tokens); refresh safety margin / CAS; disconnect under locks
• Gateway: OAuth preferred, API-key fallback, disconnected fail-closed
• Catalog/status: xaiSubscriptionConnected / xaiApiKeyConnected; SuperGrok contributes xai for models when key is absent
• Settings + setup dual-path UI (connect label, dual connected, errored reconnect, setup Continue on subscription-only)
• Usage parser/fetcher for live Grok billing shape
• Delete API key while SuperGrok remains; auto-add models alias
• Pre-push: oxlint, types, residual lint, knip
• Manual device-code connect + usage bars on VPS (roomote.fleetcast.co)

[roomote-roomote]

1 issue outstanding. See task

• apps/web/src/components/settings/XaiConnectDialog.tsx:97: The generation check cannot cancel a pollDeviceAuth request already in flight. That command persists a successful exchange before returning, so after cancel/reopen the old request can complete after the new flow and overwrite its subscription. Cancel or serialize the pending request, or make the server persist only the currently active device flow.
• packages/db/src/lib/xai-subscription.ts:500: Concurrent startXaiDeviceAuth calls register the pending flow only after their independent device-code HTTP requests resolve. If a later start returns first, it records its code; then an earlier, slower start records its stale code and invalidates the later dialog without the user restarting. Serialize starts or reserve a generation before the HTTP request and conditionally persist only the latest start.
• packages/db/src/lib/xai-subscription.ts:338: disconnectXaiSubscription now acquires the device-flow advisory lock before deleting both records, so an in-flight poll cannot reconnect after disconnect.
• packages/db/src/lib/xai-subscription.ts:426: Refreshes and successful device-code polls now take both advisory locks and fence writes by the original refresh token, so a reconnect cannot be overwritten by a stale refresh.
• packages/types/src/model-provider-config.ts:1180: getDisplayModelProviderId now remaps xai/ models to the Grok subscription when it is the sole xAI connection, and the launch and settings selectors receive both subscription and API-key state.
• packages/db/src/lib/__tests__/subscription-provider-usage.test.ts:464: xaiRecord.expires is set exactly at the one-hour refresh safety boundary. By the time the test calls getFreshXaiAccessToken, it is already inside the safety window, so the helper performs a second secret read that this mock does not provide and both new xAI usage tests throw instead of exercising their assertions. Set the fixture expiry safely beyond the margin or provide the refresh-path reads.
• .gitleaks.toml:9: This config is auto-discovered by Gitleaks, and without [extend] useDefault = true it replaces the built-in rules rather than extending them. The new global allowlist therefore loads alongside zero secret-detection rules, effectively disabling the repository's Gitleaks scan. Add the default extension before the allowlist.

_{Reviewed a69e298}

[pridemusvaire]

Addressed the outstanding review finding on XaiConnectDialog poll races:

Server-side fix in packages/db/src/lib/xai-subscription.ts:

• startXaiDeviceAuth registers the current device code as the only active pending flow
• pollXaiDeviceAuth only persists tokens when the polled code still matches that active flow (re-checked under lock after the token exchange)
• A cancelled/restarted dialog that starts a newer code cannot be overwritten by an older in-flight poll

Covered with unit tests for superseded codes and mid-flight restart races.

[mrubens]

Excited for this! Let me know if/when it’s ready for me to review.

[pridemusvaire]

Hey @mrubens , just finished testing on my VM , it's ready, Grok 4.5 is magic the speed is 💯

[mrubens]

Hi @pridemusvaire, I took a quick look and had a couple suggestions to make this more consistent with the other subscription providers:

1. Could you make xAI (Grok subscription) its own provider instead of coupling it with xAI API?
2. Could you add a usage bar for the sub on /settings/models so people can easily see how much they have left?

Thanks!

[pridemusvaire]

Hi @pridemusvaire, I took a quick look and had a couple suggestions to make this more consistent with the other subscription providers:

1. Could you make xAI (Grok subscription) its own provider instead of coupling it with xAI API?
2. Could you add a usage bar for the sub on /settings/models so people can easily see how much they have left?

Thanks!

Hey @mrubens , sure let me update, thanks 🙏

[pridemusvaire]

hey @mrubens , sorted now thanks, I will submit another PR to add the Z.AI usage bar too

[mrubens]

Hi @pridemusvaire — thanks for the updates, the separate provider + JSON billing endpoints came out great. I pushed three commits to your branch to keep things moving (hope that's okay, maintainer edits were enabled):

• 594c912 — merged develop to resolve conflicts with your Z.AI usage PR (feat: Z.AI usage bars in Models settings #797) that landed there; the usage module now carries both the xAI and Z.AI fetchers side by side.
• 8d5cd71 — addressed the remaining review item: xai/ models now group under the Grok subscription entry in the launch model select and Models settings role selectors when the subscription is the only xAI connection, mirroring how ChatGPT/OpenAI grouping works.
• b4a9ddd — trimmed the usage row to a single aggregate bar. Since the plans share one pool across products, the per-product entries rendered as duplicate-looking bars when one product dominates, and Credits: 0 left read like an error in the common idle state — the balance now only shows when positive (the state where usage continues on metered spend). Your captured live payload stayed as the test fixture.

Everything's green locally and the PR shows mergeable again. I think this is ready to land once CI agrees — thanks again for driving this!

[pridemusvaire]

hey @mrubens , sounds good , thanks for the review