fix(xai): stream OAuth Grok through Responses

[olddonkey]

Summary

• Route native Codex Responses traffic for OAuth-backed xai/grok-4.5 and xai/grok-4.6 through the Responses backend declared by the official Grok CLI model catalog.
• Add authentication-mode scoping to registry wire defaults so API-key xAI requests, translated Chat/Anthropic callers, other Grok models, and explicit adapter overrides keep their existing Chat wire.
• Extend the existing one-shot xAI OAuth 401 refresh/replay contract to native Responses passthrough requests without changing credential storage or logging.
• Add regression coverage for routing boundaries, Fast-policy capture, OAuth replay, and relaying the first native Responses delta before upstream completion; document the mixed-wire contract in structure/04_transports-and-sidecars.md.

The previous xAI OAuth preset intentionally followed the older Grok CLI Chat Completions contract. The current official model catalog reports api_backend: "responses" for Grok 4.5 and 4.6, while OpenCodex still selected its provider-wide openai-chat adapter. That compatibility drift could leave Codex waiting until the reasoning turn was effectively complete before seeing output.

Security boundary: this reuses the existing generation-checked, singleflight OAuth refresh and permits only one pre-stream replay. It does not add credential persistence, forwarding destinations, request-body logging, or new OAuth scopes. Because it touches the OAuth replay path, it still requires explicit maintainer security review before merge.

Verification

At commit 3c5a34f73, based directly on upstream/dev commit 63bfd149d:

• bun run typecheck
• bun run test — 13,404 pass / 10 skip / 0 fail
• bun run privacy:scan
• git diff --check upstream/dev...HEAD
• Focused regression: the xAI OAuth request uses /responses, preserves Responses request fields, and delivers the first SSE text delta while upstream completion is still blocked.
• Five authenticated Grok 4.6 canaries through the local proxy — 5/5 completed and all selected openai-responses.

Live canary latency is not a controlled benchmark: TTFT was 0.656s, 0.598s, 77.824s, 0.733s, and 31.169s. Three calls streamed promptly; two retained xAI-side long-tail latency. The deterministic regression therefore asserts the proxy property this PR owns—first-delta relay before completion—rather than claiming that it removes upstream generation variance.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. (structure/04_transports-and-sidecars.md documents the routing and replay boundaries; there is no new user configuration.)
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (Author review found no new persistence, logging, scope, or destination; explicit maintainer security approval remains required before merge.)

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features

  • Added native Responses API support for OAuth-authenticated xAI Grok 4.5 and 4.6 models.
  • Added automatic OAuth credential refresh and one-time retry when Responses requests receive an authorization failure.
  • Preserved Chat API routing for API-key authentication, unsupported models, translated requests, and explicit overrides.

• Bug Fixes

  • Improved authentication-aware protocol selection and error handling during OAuth recovery.
  • Added streaming support validation for native xAI Responses requests.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1dec2cc7-7b9e-404c-8c27-62a6d3e9ff54

📥 Commits

Reviewing files that changed from the base of the PR and between 63bfd14 and 3c5a34f.

📒 Files selected for processing (9)

• src/providers/fastwire.ts
• src/providers/registry.ts
• src/providers/service-tier.ts
• src/server/responses/core.ts
• structure/04_transports-and-sidecars.md
• tests/adapter-resolve.test.ts
• tests/fastwire-policy.test.ts
• tests/server-xai-oauth-401-replay.test.ts
• tests/server-xai-responses-streaming.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds authentication-scoped xAI wire defaults for Grok 4.5 and 4.6. OAuth requests use native Responses passthrough. Native Responses OAuth requests now refresh credentials and replay once after a pre-stream 401.

Changes

xAI authentication-aware wire selection

Layer / File(s)	Summary
Authentication-aware registry defaults src/providers/registry.ts, src/providers/service-tier.ts	ModelWireDefault supports optional authModes. xAI defines OAuth-only Responses defaults for grok-4.6 and grok-4.5. Cloned declarations preserve frozen authentication-mode arrays. Provider authority snapshots record the effective authentication mode.
FastWire resolution and routing coverage src/providers/fastwire.ts, tests/adapter-resolve.test.ts, tests/fastwire-policy.test.ts	FastWire filters defaults by inbound wire and authentication mode. OAuth Grok subscription models select openai-responses; key authentication, translated callers, unsupported models, and explicit Chat overrides select openai-chat.
Routing documentation structure/04-transports-and-sidecars.md	The documented routing rules include inbound protocol and authentication scoping for xAI wire defaults.

Native Responses OAuth recovery

Layer / File(s)	Summary
Pre-stream 401 refresh and replay src/server/responses/core.ts	Native Responses OAuth providers force-refresh credentials after a pre-stream 401, rebuild provider and request state, re-resolve the adapter and replay scope, then retry once. Refresh, rebuild, wire-change, and transport failures use the specified error handling.
Responses replay and streaming tests tests/server-xai-oauth-401-replay.test.ts, tests/server-xai-responses-streaming.test.ts	Replay tests now use the Responses endpoint and schema. Streaming tests verify SSE forwarding, request fields, authentication headers, early deltas, and completion events.
Recovery documentation structure/04-transports-and-sidecars.md	The documented Grok OAuth recovery path covers native Responses passthrough and one generation-checked replay.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: 🔵 Low · up to 3c5a3

This change extends OAuth authentication replay to native Responses streaming requests; the stated checks are complete, but merge should wait for the required maintainer security approval because retry behavior is security-sensitive.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ResponsesCore
  participant OAuthProvider
  participant xAIResponses
  Client->>ResponsesCore: Send native Responses request
  ResponsesCore->>xAIResponses: Forward request
  xAIResponses-->>ResponsesCore: Pre-stream 401
  ResponsesCore->>OAuthProvider: Force-refresh OAuth credential
  OAuthProvider-->>ResponsesCore: Refreshed credential
  ResponsesCore->>xAIResponses: Replay rebuilt request once
  xAIResponses-->>Client: Responses stream

Loading

Possibly related PRs

• lidge-jun/opencodex#1893: Directly related FastWire and registry extension for authentication-aware wire resolution.
• lidge-jun/opencodex#1956: Directly related provider-authority and Responses adapter behavior.
• lidge-jun/opencodex#302: Related Kiro OAuth 401 replay behavior.

Suggested labels: proxy

Suggested reviewers: lidge-jun, ingwannu

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: routing OAuth-backed Grok streaming through the Responses API.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

✅ READY

• all PR quality gates passed; the review readiness checklist is complete.

Review readiness checklist

• ✅ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request is already Ready for Review.
The review-ready label marks this PR as ready; review automation runs independently.
Maintainers: @lidge-jun @Ingwannu @Wibias