feat(openab-agent): xAI subscription login (SuperGrok / X Premium) via device-code OAuth

[chaodu-agent]

What problem does this solve?

openab-agent supports subscription sign-in for Codex (ChatGPT) and Anthropic (Claude Pro/Max), but xAI users currently need to provision and rotate an XAI_API_KEY even when they already pay for a SuperGrok or X Premium subscription. openab-agent also runs in headless environments such as ECS Fargate and Kubernetes, where a PKCE loopback redirect is not practical. This PR adds a device-code login that can be completed through kubectl exec or ecs execute-command.

Closes #1423

Discord discussion: Not applicable. This implementation follows the research and rationale captured in issue #1423.

Review Contract

The reference implementation and acceptance contract for this PR is Pi's native xAI OAuth provider (Pi #6651), not the separate official Grok Build CLI SessionToken proxy contract.

• OAuth device-flow access tokens are sent as Authorization: Bearer <token> to the OpenAI-compatible https://api.x.ai/v1/chat/completions endpoint. This matches Pi's toAuth() behavior, which returns the OAuth access token as the API key.
• The xAI device endpoints and core scope follow Pi: openid profile email offline_access grok-cli:access api:access.
• cli-chat-proxy.grok.com, X-XAI-Token-Auth, x-grok-model-override, and x-grok-client-version are not part of this PR. Those belong to the official Grok Build SessionToken and CLI compatibility path, which is a separate integration contract.
• Review should therefore validate direct xAI API OAuth behavior against Pi's contract. Grok Build SessionToken compatibility would require separate credential-kind routing and proxy-specific headers.

Goal

A user with a SuperGrok or X Premium subscription can run openab-agent auth xai-device, approve the login on any browser-equipped device, and then use Grok models through openab-agent (ACP sessions, model switching, and MCP sampling) with automatic token refresh and no XAI_API_KEY.

Non-goals

• xAI is not added to credential auto-detection. It must be selected explicitly through OPENAB_AGENT_PROVIDER=xai or grok, or through an xai/ or grok/ model prefix. Existing Anthropic-to-Codex fallback behavior remains unchanged.
• No Responses API routing or reasoning-effort levels are added for grok-4.5. Pi routes that model through Responses for reasoning levels, but Chat Completions serves it and is the path used by xAI's quickstart.
• Streaming remains disabled (stream: false), matching the existing OpenAiProvider batch-parse behavior and openab-agent's streaming: false ACP capability.
• The Codex device flow is not migrated to the new RFC 8628 driver because OpenAI's device_auth_id protocol is not RFC 8628.

Accepted Residual Risks

• Shared public client ID. The default client ID is the official Grok CLI public client ID and is the established ecosystem convention used by OpenClaw, Hermes Agent, LiteLLM, Warp, Cherry Studio, and Pi. xAI could rotate or restrict it. OPENAB_AGENT_XAI_CLIENT_ID can override it without a code change; recovery is to log in again with the new ID.
• No live-server integration test. The device-flow network path is exercised only against the real authorization server, as with the existing Codex and Anthropic flows. Parsing and classification logic is extracted into pure functions with unit tests that pin the wire contract.
• Static model list. grok-4.5, grok-4.3, and grok-build-0.1 mirror Pi's trimmed built-in list and may become stale. Any model ID can still be set explicitly through environment variables or configuration; the list only feeds the ACP model picker.

Acceptance Criteria

• XaiVendor resolves under the xai-oauth namespace with a device-code grant, form-encoded token requests, no loopback redirect, and the documented scope. Covered by xai_vendor_descriptor_pins_wire_contract, vendor_for_resolves_xai, and xai_vendor_is_not_a_pkce_vendor.
• Device-authorization parsing enforces HTTPS-only verification URIs, including verification_uri_complete, accepts interval: 0 and a missing expires_in, and fails on missing device_code or user_code. Covered by parse_device_authorization_* and validate_https_url_accepts_https_only.
• Token polling classifies authorization_pending, slow_down with and without a replacement interval, access_denied and authorization_denied, expired_token, and unknown errors as terminal. Covered by classify_device_poll_error_dispositions.
• Token responses without expires_in default to 3600 seconds, and a login response without refresh_token fails loudly. Covered by token_store_from_payload_defaults_expires_in. Refresh-time no-rotation continues to use the existing generic refresh_token() fallback.
• Transcript-to-Chat-Completions conversion keeps tool messages adjacent to their assistant tool_calls message and stringifies arguments. xai/ and grok/ model references also parse. Covered by test_xai_chat_messages_* and test_model_ref_parses_xai_and_grok_prefixes.
• cargo fmt was applied; cargo clippy --all-targets introduces no new warnings versus main (10 to 10); cargo test is green with 230 passed, 0 failed, and 15 new tests.

Follow-ups

• Optionally route grok-4.5 through the Responses API with reasoning-effort levels, as in Pi #6651.
• Consider adding xAI to the auto-detection chain after the integration is field-proven.
• Migrate the PKCE and refresh engine to oauth2::BasicClient as described in the existing ADR Section 4.2. This PR does not change that work.

At a glance

openab-agent auth xai-device
        |
        v
XaiVendor (OAuthVendor descriptor, namespace xai-oauth)
        |
        v
login_device_code_flow (generic RFC 8628 driver in auth.rs)
  +-- POST auth.x.ai/oauth2/device/code (client_id, scope, referrer=openab)
  +-- print user_code and an HTTPS-validated verification link
  +-- poll auth.x.ai/oauth2/token (pending / slow_down / denied / expired)
        |
        v
auth.json { "xai-oauth": TokenStore }
  +-- shared refresh driver (flock, refresh-token rotation safety, expiry skew)
        |
        v
XaiProvider (llm.rs) -- Bearer access token --> api.x.ai/v1/chat/completions
        |
        v
ACP sessions / model switching / MCP sampling (acp.rs wiring)

Prior art and industry research

• OpenClaw: extensions/xai/xai-oauth.ts uses the RFC 8628 device flow against auth.x.ai with the same Grok CLI public client ID and scope, and uses the access token directly as the API key.
• Hermes Agent: hermes_cli/auth.py and the xAI Grok OAuth guide use the same device-code flow with background refresh and explicitly target SuperGrok and X Premium subscriptions without XAI_API_KEY.
• Pi: earendil-works/pi#6651 added xAI device OAuth and was merged on 2026-07-16. Pi #6734 added a prefilled verification_uri_complete link, a SuperGrok login label, and a trimmed model list; this PR mirrors those details. Pi's handling of refresh without rotation, absent expires_in, interval: 0, and non-HTTPS verification URIs is replicated here with unit tests.
• The default client ID also appears in xai-org/grok-build and hundreds of public repositories such as LiteLLM, Warp, and Cherry Studio. Reuse is the ecosystem convention because xAI does not offer public OAuth client registration.

Proposed solution

Land xAI as the first AuthGrant::DeviceCode-primary vendor on the existing OAuthVendor descriptor surface (ADR Section 5.1), which was explicitly earmarked for Grok:

1. auth.rs - Add the XaiVendor descriptor and a generic login_device_code_flow, the standards-compliant counterpart to login_pkce_flow. Two descriptor hooks, device_authorization_url() and extra_device_params(), have backward-compatible defaults for xAI's referrer tag. Parsing and poll-error classification are pure functions (parse_device_authorization, validate_https_url, and classify_device_poll_error) so edge cases are unit-testable without a live authorization server. Storage, locking, and refresh reuse the existing shared driver; refresh_token() already keeps the previous refresh token when the authorization server omits a replacement and defaults a missing expires_in.
2. llm.rs - Add XaiProvider, which speaks OpenAI-compatible Chat Completions at api.x.ai/v1 and sends the per-call refreshed OAuth token as a Bearer token. Response parsing reuses parse_openai_response and the existing Chat Completions path. The provider also uses the same 429/529 backoff and 401 force-refresh retry loop as OpenAiProvider.
3. main.rs and acp.rs - Add the auth xai-device subcommand and wire stored xai-oauth credentials into session creation, model switching, and model listing.

Why this approach?

• Descriptor, not a fork: The OAuthVendor trait already promises that adding a vendor is a new descriptor, not a new hand-rolled flow. This PR makes the device-code axis real and removes the existing dead_code placeholders. Future device-code vendors such as Copilot or Kiro can reuse the driver.
• Chat Completions, not a bespoke client: xAI's API is OpenAI-compatible, and xAI's quickstart drives grok-4.5 through /v1/chat/completions, so the provider stays thin and reuses the existing parser and tests.
• Pure-function edge cases: Failure modes that affected other implementations, including interval: 0, absent expires_in, slow_down semantics, non-HTTPS verification URIs, and refresh without rotation, are either unit-tested here or already covered by the shared refresh driver.

Alternatives considered

• PKCE loopback flow - Rejected because openab-agent's primary deployment is headless containers with no reachable localhost redirect. Device-code is also the flow used by the Grok CLI.
• A bespoke xAI flow mirroring login_codex_device_flow - Rejected because xAI uses standard RFC 8628. A generic driver supports the next device-code vendor, while Codex remains bespoke because OpenAI's device_auth_id protocol is non-standard.
• Routing grok-4.5 through the Responses API - Deferred. Chat Completions serves grok-4.5; the Responses split mainly adds reasoning-effort levels at the cost of a second wire format.
• Registering an OpenAB OAuth client with xAI - Not currently possible because xAI has no public OAuth client registration; console.x.ai issues API keys only.

Validation

• cargo fmt - applied.
• cargo clippy --all-targets - no new warnings versus the origin/main baseline (10 pre-existing warnings remain 10).
• cargo test - 230 passed, 0 failed, with 11 ignored integration tests and 15 new tests, including descriptor, client-ID, provider-resolution, CLI, HTTPS-validation, device-authorization, polling, token-expiry, model-reference, and Chat-Completions message-mapping coverage.
• Manual testing - verified that the CLI surface builds and that auth xai-device is wired to login_xai_device_flow. A live end-to-end login was not run because it requires a SuperGrok or X Premium subscription; the wire contract is pinned by unit tests and mirrors the OpenClaw, Hermes, and Pi implementations.

[chaodu-agent]

Important

CHANGES REQUESTED ⚠️ — Mixed text/tool responses can skip tool execution, and slow_down can reduce the polling interval.

Consolidated review: #1424 (comment)

GitHub event: COMMENT — self-review delivery only; this is not an approval.

[chaodu-agent]

🟡 F1 — Execute tool calls even when the response also contains text

This new Chat Completions path can return both LlmEvent::Text and LlmEvent::ToolUse, but agent.rs:235 exits whenever text is present, so the tool calls are recorded but never executed.

Requested change: Continue the tool loop whenever any tool call exists, preserve the accompanying text, and add a regression test with both non-empty content and tool_calls.

[chaodu-agent]

🟡 F2 — Never reduce the polling interval after slow_down

Using the replacement verbatim allows a lower value to speed polling up (for example, 10 seconds becomes 3). RFC 8628 §3.5 requires the interval to increase by five seconds after slow_down.

Requested change: Make the next interval monotonic and at least poll_interval + 5 (or always add five seconds), and add a regression test for a lower supplied replacement.

[chaodu-agent]

Important

CHANGES REQUESTED ⚠️ — Configuration, cross-provider auth routing, refresh-error handling, and RFC 8628 timeout backoff still need correction.

Consolidated review: #1424 (comment)

GitHub event: COMMENT — self-review delivery only; this is not an approval.

[chaodu-agent]

🟡 F1 — Preserve the model selected from config.json

resolve_provider_choice() can select xAI from AgentConfig.model, but this constructor only checks the two environment variables before defaulting to grok-4.5. A config-only value such as xai/grok-4.3 therefore selects the right provider and silently sends the wrong model.

Requested change: Fall back to AgentConfig.model before the built-in default, parse it through ModelRef, and add a config-only regression test.

[chaodu-agent]

🟡 F2 — Make auth-mode preservation provider-specific

The ACP switch path treats any true value here as "the current session uses Anthropic OAuth". Returning true for xAI therefore makes an xAI → Anthropic switch call from_oauth_auto_with_model(), bypassing a configured ANTHROPIC_API_KEY and failing when no Anthropic OAuth token exists.

Requested change: Track provider/auth identity explicitly, or only preserve Anthropic OAuth when the current provider is Anthropic OAuth; cover xAI → Anthropic with API-key-only credentials.

[chaodu-agent]

🟡 F3 — Surface reactive refresh failures

Discarding this result means invalid_grant, missing credentials, or storage failures are hidden. The loop retries with stale credentials and eventually reports only a generic xAI 401, losing the actionable re-authentication error.

Requested change: Refresh at most once, retry only after a successful refresh, propagate refresh failures, and add deterministic success/failure retry coverage.

[chaodu-agent]

🟡 F4 — Back off and retry after connection timeouts

This ? aborts an otherwise valid device authorization session on a transient token-poll timeout. RFC 8628 §3.5 requires clients to reduce polling frequency before retrying after a connection timeout and recommends exponential backoff.

Requested change: Handle timeout errors inside the poll loop, increase the interval, retry until the device-code deadline, and add a timeout/backoff regression test.

[chaodu-agent]

Important

CHANGES REQUESTED ⚠️ — Three important fixes remain around OAuth endpoint trust, cross-provider auth preference, and the xAI output-token limit.

Consolidated review: #1424 (comment)

GitHub event: COMMENT — self-review delivery only; this is not an approval.

[chaodu-agent]

🟡 F1 — Do not send the OAuth bearer to an arbitrary base URL

OPENAB_AGENT_XAI_BASE_URL is accepted verbatim, while the request path later attaches the stored xai-oauth bearer. A typo, plaintext URL, or non-xAI proxy can therefore exfiltrate a refreshable subscription credential.

Requested change: Require HTTPS plus an xAI-owned host allowlist for OAuth, or introduce a separate explicit trusted-proxy mode with clear warnings and tests.

[chaodu-agent]

🟡 F2 — Preserve auth mode per provider across round-trip switches

This check remembers only the currently active provider. An Anthropic OAuth session that switches to xAI and then back to Anthropic no longer knows its original Anthropic auth choice, so auto_with_model() can silently select ANTHROPIC_API_KEY.

Requested change: Store auth policy per provider in session state and test Anthropic OAuth → xAI → Anthropic with an API key also configured.

[chaodu-agent]

🟡 F3 — Honor the documented output-token limit

The xAI request body omits the documented OPENAB_AGENT_MAX_TOKENS value, so users relying on it for response size, latency, or spend receive the upstream default.

Requested change: Resolve and send the Chat Completions-compatible output-token field and assert it in a request-body test, or explicitly document that xAI is exempt.

[chaodu-agent]

Important

CHANGES REQUESTED ⚠️ — xAI session tokens must use the documented inference proxy, and the final-attempt 401 path must preserve a retry after refresh.

Consolidated review: #1424 (comment)

GitHub event: COMMENT — self-review delivery only; this is not an approval.

[chaodu-agent]

🔴 F1 — Route session OAuth tokens through xAI’s documented inference proxy

This default sends a refreshable device/OIDC session token to api.x.ai, but xAI’s Enterprise Deployments documentation and official Grok Build source define that host as the direct API-key path. Session tokens must use https://cli-chat-proxy.grok.com/v1; the current request also omits the required X-XAI-Token-Auth: xai-grok-cli and x-grok-model-override headers. This can make the core SuperGrok/X Premium path fail or use the wrong auth contract.

Requested change: route session credentials only through the documented proxy with its required headers/model routing, reserve api.x.ai for a distinct API-key mode, and add deterministic route/header tests.

[chaodu-agent]

🟡 F2 — Preserve a retry after successful reactive refresh

On attempt 3, this branch can refresh successfully and then continue past the end of 0..=max_retries. A sequence such as three retryable 429/529 responses followed by 401 therefore stores a fresh token but returns max retries exceeded without ever sending it.

Requested change: give the one-time 401 refresh its own retry allowance, or refresh only when another request can be made and return the actual 401 otherwise. Add a regression for the exhausted-budget sequence.

[chaodu-agent]

Author Response — Round 4

✅ F2 (🟡) — fixed in f0d096c

Rate-limit retries and the one-time 401 refresh now have independent budgets, so a 401 after three 429s still gets its post-refresh request. Regression test xai_chat_rate_limits_then_401_still_gets_refreshed_request covers exactly the requested 429×3 → 401 → refreshed request sequence against canned local servers (242 tests pass, clippy warning count unchanged vs main).

❌ F1 (🔴) — rejected under the Late Blocker Gate

Lineage: not NEW EVIDENCE — this is a re-raise of a claim already rejected in Round 3, where the review itself recorded: "rejected the unsupported claim that direct api.x.ai OAuth inference is categorically invalid." The frozen contract (Goal + Accepted Residual Risks) covers the direct api.x.ai OAuth path; per docs/review-contract.md, re-raising it requires concrete, reproducible evidence of a defect within the frozen scope. The cited evidence does not establish one:

1. The Enterprise Deployments page documents the grok CLI's own network requirements, not a prohibition for third-party OAuth clients. It lists api.x.ai as "Only needed when using api_key auth instead of the inference proxy" — an either/or for grok CLI deployments, not a statement that session bearers are rejected at api.x.ai.
2. The token's scope is … grok-cli:access api:access — api:access is the grant to call the API surface directly.
3. Shipped prior art pins the exact same invariant this PR implements. Hermes Agent (hermes_cli/auth.py): DEFAULT_XAI_OAUTH_BASE_URL = "https://api.x.ai/v1", with a guard documented as "Pin the inference origin to api.x.ai (or any *.x.ai subdomain)" — byte-for-byte the trust boundary added in round 3. Pi (packages/ai/src/auth/oauth/xai.ts) maps the OAuth access token to { apiKey: credential.access } against the standard xAI endpoints. The Round-2 review of this PR also performed a live device-authorization smoke against these endpoints and reported the contract assumptions confirmed.
4. cli-chat-proxy.grok.com + X-XAI-Token-Auth is grok CLI's first-party proxy protocol (session sync, settings, ZDR routing). Adopting a second, undocumented-for-third-parties wire protocol is a SCOPE EXPANSION relative to the frozen Goal ("Chat Completions at api.x.ai/v1") — recorded as a possible follow-up if field evidence ever shows session tokens being rejected at api.x.ai.

Stopping rule

The default three-stage sequence (full review → fix verification → final regression check) completed at Round 3 with all findings resolved. Round-4 F2 was accepted and fixed as a genuine ORIGINAL-scope defect; further rounds need maintainer authorization per the frozen-contract policy.

[chaodu-agent]

Note

LGTM ✅ — All actionable findings from earlier rounds are resolved or not applicable; Pi's merged implementation corroborates the direct api.x.ai/v1 OAuth contract.

Consolidated review: #1424 (comment)

GitHub event: COMMENT — self-review delivery only; this is not an approval.

[chaodu-agent]

Important

CHANGES REQUESTED ⚠️ — The exact head fails cargo fmt --check, and the PR description still advertises the removed auth xai-device command.

Consolidated review: #1424 (comment)

GitHub event: COMMENT — self-review delivery only; this is not an approval.

[chaodu-agent]

🟡 F1 — Restore rustfmt-compliant formatting

cargo fmt --check fails on this exact head because this assertion is split differently from rustfmt output. This blocks the native-agent CI job before its check, clippy, and test stages can run.

Requested change: Run cargo fmt --all, commit the formatted auth.rs, and verify that cargo fmt --check passes.

[chaodu-agent]

Important

CHANGES REQUESTED ⚠️ — The subscription OAuth token is routed through the API-key endpoint instead of xAI's official session-token inference route.

Consolidated review: #1424 (comment)

GitHub event: COMMENT — self-review delivery only; this is not an approval.

[chaodu-agent]

Important

CHANGES REQUESTED â� ï¸� â�� The Pi-native xAI contract is explicit; one exact-head cargo fmt --check failure remains.

Consolidated review: #1424 (comment)

GitHub event: COMMENT � review delivery for this PR; this is not an approval.

[chaodu-agent]

Note

LGTM ✅ — The requested head contains the rustfmt correction for the remaining prior-round gate issue, and no new blocking finding was introduced.

What This PR Does

This PR adds native xAI subscription authentication to openab-agent: users can complete a headless RFC 8628 device-code login, persist and refresh the resulting OAuth credentials, and select Grok models for ACP sessions and MCP sampling without provisioning an XAI_API_KEY.

How It Works

The implementation adds an XaiVendor to the shared OAuth descriptor surface and a reusable RFC 8628 device-code driver. XaiProvider sends refreshed OAuth bearer credentials to the Pi-native, OpenAI-compatible https://api.x.ai/v1/chat/completions contract, converts the internal transcript into Chat Completions messages, and preserves tool-call execution. ACP provider selection, model switching, model discovery, the CLI, and native-agent documentation are extended for the xai and grok aliases.

Findings

#	Severity	Finding	Location
P1	🟢	The requested head applies the rustfmt-only correction to the xAI auth test while preserving the previously reviewed device-flow, provider, refresh, routing, and regression-test fixes.	openab-agent/src/auth.rs:1719-1722

Finding Details

🟢 P1: Exact-head formatting correction is complete

The only delta from the previously reviewed 8fefcb018827e8a4ffda17fdd355200bd377b4b4 head is the rustfmt normalization of auth_subcommand_per_namespace. The exact requested SHA has no additional behavioral change, and git diff --check passes for the full PR range.

Previous Review Resolution

• The mixed text plus tool-call execution issue is resolved: the agent continues whenever tool calls are present and preserves accompanying text in the assistant message.
• Device-poll slow_down handling is monotonic, and transient token-poll transport failures back off and retry until the device-code deadline.
• Config-selected xAI models, provider-specific auth switching, sticky Anthropic OAuth preference, endpoint trust validation, and the documented output-token limit are covered by the current implementation and focused tests.
• Reactive refresh failures are surfaced, and the one-time 401 refresh has an independent retry allowance so a successful refresh is followed by a request even after rate-limit retries.
• The PR description now documents the canonical auth xai command and explicitly distinguishes the declared Pi-native direct api.x.ai OAuth contract from the separate official Grok Build SessionToken proxy contract.
• The prior exact-head formatting finding is resolved by the requested 6a4566063e5825c1a8968298ce566a62e07229c9 commit.

Addressing External Reviewer Feedback

No external reviewer feedback was present for this round. Earlier keyed review artifacts were internal consolidated reviews and their findings are accounted for in Previous Review Resolution above.

Baseline Check

• PR opened: 2026-07-18.
• Main already has: the shared OAuth vendor abstraction, a bespoke Codex device flow, and a separate official Grok ACP integration path; it does not have native xAI subscription OAuth inside openab-agent.
• Net-new value: native xAI subscription device OAuth, refreshable credentials, Grok provider/model wiring, ACP model selection, and MCP sampling integration.
• Exact reviewed head: 6a4566063e5825c1a8968298ce566a62e07229c9.
• The delta from the prior reviewed 8fefcb018827e8a4ffda17fdd355200bd377b4b4 head is one rustfmt-only change in openab-agent/src/auth.rs; git diff --check passes.
• GitHub review-contract and validation checks observed for this head are successful; other CI checks were still in progress when inspected.
• Local Rust validation could not be rerun because cargo and rustc are not installed in this environment.

What's Good (🟢)

• Vendor-specific xAI constants remain behind a focused descriptor while device polling and token persistence reuse shared infrastructure.
• Verification links are validated as HTTPS before being displayed.
• Transcript conversion preserves assistant tool calls and adjacent tool results, including mixed commentary/tool turns.
• Provider selection and auth-mode handling remain explicit, avoiding accidental xAI auto-detection.
• The exact requested head is a minimal, targeted formatting correction rather than an unrelated behavioral change.

5️⃣ Three Reasons We Might Not Need This PR

1. The official Grok client already supports headless device login and ACP — Grok-only deployments could delegate authentication and protocol drift to the vendor-maintained client.
2. Subscription entitlement remains upstream-controlled — successful device authorization does not guarantee every SuperGrok or X Premium tier can perform direct inference, and this PR has no subscribed-account end-to-end test.
3. The integration adds another provider-specific transport surface — static models, retry policy, endpoint trust, and OAuth behavior create ongoing maintenance beyond the shared descriptor itself.

[chaodu-agent]

Note

LGTM ✅ — The exact requested head contains the rustfmt correction and no new blocking finding.

Consolidated review: #1424 (comment)

GitHub event: COMMENT — self-review delivery only; this is not an approval.