feat(xai): classify Grok OAuth service tier per model and relay the tier echo

devlog/_fin/260913_xai_oauth_fast/010_plan.md

@@ -0,0 +1,61 @@
+# xAI Grok OAuth fast tier (service_tier: "priority") — plan
+
+## Loop spec (HOTL wp1)
+
+- Tool/credential scope: local proxy management (ocx CLI, /api/providers/reload probe only, already applied), GitHub via gh/MCP for this PR only. No other accounts, no release/deploy, no service restart.
+- Write scope: branch codex/xai-oauth-fast-tier in this worktree; the live ~/.opencodex config keeps the probe override (modelSupportsServiceTier for the 7 honored models) — user asked to keep working models enabled; PR + merge to dev per MAINTAINERS.md self-integration policy.
+- Budget: unlimited read-only subagents on xai/grok-4.6 (user-granted); probe calls already completed.
+- Wall-clock: bounded by hosted CI; if CI cannot reach a terminal state within ~90 minutes of the final push, report BUDGET_EXHAUSTED rather than DONE.
+- Certification: hosted exact-head CI only. Full local suite and local typecheck NOT RUN (standing rule); focused tests below are development feedback, not certification.
+
+## Context
+
+xAI documents Priority Processing: `service_tier: "priority"` on /v1/responses and /v1/chat/completions, echoed in the response, billed 2x on API keys. hermes-agent#89440 verified it live on SuperGrok Heavy OAuth; there is no grok-*-fast slug. ocx's xai registry entry declares keyAuthServiceTier (API-key lane only) and deliberately leaves OAuth unclassified (src/providers/registry.ts:1367-1376), with modelWireDefaults pinning forwardCallerServiceTier:false on grok-4.6/4.5 OAuth. That classification is now stale: the live probe (020_probe-evidence.md) shows the user's own Grok OAuth account accepts and honors priority on 7 of 8 catalog models.
+
+## Decision table
+
+- D1 Include set: grok-4.6, grok-4.5, grok-4.3, grok-4.20-0309-reasoning, grok-4.20-0309-non-reasoning, grok-build-0.1, grok-composer-2.5-fast. Exclude grok-4.20-multi-agent-0309 — upstream consistently answers service_tier "default" when sent priority (ocx log: fastOutcome downgraded, confirmation downgraded).
+- D2 Registry shape: xai entry gains `modelSupportsServiceTier: {<7 ids>: true}` (OpenRouter precedent: provider stays unclassified, per-slug map, tests/service/service-tier-capability.test.ts) and `chatServiceTier: true`. No provider-wide supportsServiceTier; future/undiscovered ids stay unclassified. enrichProviderFromRegistry backfills both into saved configs at load (tests/service/service-tier-capability.test.ts:46-57), so existing installs get the lane without config edits; explicit config still wins.
+- D2a (audit fold, scope honesty): `chatServiceTier: true` is provider-wide for the caller-forwarding gate (service-tier.ts:106-110 reads provider config first), so caller-sent tiers also forward verbatim on UNCLASSIFIED xai chat-wire models (future liveModels ids), not just the 7. Accepted: this matches the established unclassified-route forwarding contract pinned at tests/service/service-tier-capability.test.ts:444, `--fast` publication and proxy-owned fast injection stay capability-scoped per D2, and the probe showed the gateway accepts the field on every current model. Key-auth lane unchanged (backfilled true shadows the identical keyAuthServiceTier value).
+- D3 Caller-tier parity: remove `forwardCallerServiceTier: false` from the grok-4.6/4.5 modelWireDefaults (rationale "unclassified route" is stale once D2 lands) so a caller-sent service_tier:"priority" on the OAuth responses lane forwards — the Codex fast-toggle path OpenAI native models already use. Chat-wire models forward caller tiers via the new chatServiceTier:true (fastwire.ts forwardCallerTier chain).
+- D4 Echo relay: today the upstream service_tier echo reaches attempt telemetry but not the client on chat-wire paths (probe: 4.3/4.20/build/composer client bodies lack the field; 4.6/4.5 responses-wire bodies carry it). SHIPPED (b): the chat-inbound relay on every Chat Completions delivery shape — `responsesJsonToChatCompletion` (src/chat/outbound.ts:887), `collectChatCompletion` (src/chat/outbound.ts:969, 1095), `jsonCompletionSse` (src/server/chat-native-sse.ts:64-103), and the live Responses-SSE translator `responsesSseToChatCompletionsSse` (src/chat/outbound.ts:374, 541). SPLIT per the sizing rule: (a) the responses-lane assembly for chat-wire upstreams (adapter-event → bridge plumbing across the shared adapter contract) stays a follow-up in this unit; those turns keep the echo in attempt telemetry only.
+- D5 Tests: registry pins in tests/providers/xai/xai-transport.test.ts; policy/backfill in tests/service/service-tier-capability.test.ts; fast-row publication/routing in tests/codex-integration/fast-row*.test.ts or tests/providers/fast-row-ingress.test.ts; relay tests beside the touched relay code.
+- D6 Docs/SoT: structure/providers/xai-grok.md owns the xai provider surface — update it (structure/AGENTS.md ownership rule). docs-site configuration/providers docs only if they contradict the new lane (check at B).
+- D7 Evidence: probe matrix recorded in 020_probe-evidence.md; PR Verification cites it (summarized, no secrets).
+- D8 Failure semantics: no new recovery code. If upstream later rejects or downgrades priority, existing tierOutcome records fastOutcome/confirmation (downgrade path proven live by multi-agent) — documented in the PR, no silent fallback added.
+- D9 (audit fold, revert residue): enrich backfill is fill-only in memory, but a config save while this change is live persists chatServiceTier:true and the 7-id map as EXPLICIT values, which then win every later merge — a revert commit cannot clear installs that saved in between. Accepted residue, recorded in the PR: the lane is upstream-verified behavior (not a hazard), the operator removal path is deleting the two keys, and the probe install (020 §4) deliberately keeps exactly this state at user request. No migration code.
+
+Architect consultation gap: the native spawn schema in this session has no architect role (registered in cxc config but native type rejected; registration requires a Codex restart, which would abandon this session's goal). Main wrote this plan from direct source reads; the A phase uses an independent reviewer subagent (role registered, xai/grok-4.6). Recorded per delegation contract; completion claims carry this note.
+
+## File change map
+
+1. src/providers/registry.ts — xai entry: add modelSupportsServiceTier (7 ids), chatServiceTier: true; drop forwardCallerServiceTier:false on grok-4.6/4.5; refresh the two stale comments (keyAuthServiceTier "OAuth unclassified", modelWireDefaults caller-tier note). No multi-agent entry.
+2. Relay (D4, shipped): src/chat/outbound.ts:887, 969, 1095 and src/server/chat-native-sse.ts:64-103 (chat-inbound relay on all delivery shapes). Follow-up: adapter-event → bridge plumbing for the responses lane (audit note: no adapter event/result carries service_tier today — openai-chat.ts:1778-1781, 2080-2082 observe it into attempt telemetry only; AdapterTierMetadata is telemetry per src/adapters/base.ts:118).
+3. Tests (D5 files above).
+4. structure/providers/xai-grok.md — lane classification + probe date.
+5. devlog: this unit moves to devlog/_fin/260913_xai_oauth_fast/ in the same PR after merge evidence exists.
+
+IN scope: the 7 models, both wires' caller-tier forwarding, echo relay, tests, xai-grok.md. OUT: multi-agent and future ids, provider-wide declarations, fastMode defaults (unchanged; operators opt in), recovery code, GUI changes, releases.
+
+## Accept criteria (activation in parentheses)
+
+- C1 fastPolicyForModel(xai-oauth, grok-4.6, "xai", "responses").eligibility === "eligible" (unit test constructs the xai provider with authMode oauth).
+- C2 grok-4.20-multi-agent-0309 stays unclassified: capability undefined, no --fast row (unit test + catalog listing test).
+- C3 caller service_tier:"priority" on the OAuth responses lane for grok-4.6 reaches the wire (policy test: before D3 the pin dropped it — activate by asserting forwardCallerTier true and decideTier output).
+- C4 --fast rows publish for the 7 models on the catalog listing (catalogFastRowEligible path; test feeds an oauth xai config).
+- C5 enrichProviderFromRegistry backfills chatServiceTier/modelSupportsServiceTier into a saved xai config missing them; explicit config values win (NEW capability tests — derive.ts:523 and derive.ts:552 via applyServiceTierModelDefaults:390-397 have no existing coverage for these two fields; do not lean on test:46-57). Existing pins that FLIP and must be rewritten, called out in the PR: tests/service/service-tier-capability.test.ts:108-160 and 424-445.
+- C6 relay: a chat-upstream response carrying service_tier surfaces it in the chat-inbound client body on every delivery shape — tests/responses/chat-json-sse-fallback.test.ts:256-342 (JSON body, synthesized SSE, folded stream, endpoint, live SSE translator). The responses-lane half moved to the follow-up per D4.
+- C7 PR template complete; hosted CI green on the exact head with no cancelled/skipped required jobs counted; merged to dev with maintainer decision recorded.
+
+## Verifiers (run pre-plan, exit 0, reads-target noted)
+
+- `bun test tests/providers/xai/xai-transport.test.ts` — exit 0, 47 tests; imports getProviderRegistryEntry (reads registry.ts).
+- `bun test tests/service/service-tier-capability.test.ts` — exit 0, 35 tests; imports fastPolicyForModel/enrichProviderFromRegistry (reads service-tier.ts/derive.ts).
+- `bun test tests/routing/fastwire-policy.test.ts` — exit 0, 236 tests; imports resolveFastPolicy (reads fastwire.ts + registry wire defaults).
+- `bun test tests/providers/fast-row-ingress.test.ts` — exit 0, 9 tests; parseSyntheticRowId ingress (reads fast-row.ts).
+- `bun test tests/codex-integration/fast-row.test.ts` — exit 0, 38 tests; fast-row grammar/listing.
+- Hosted PR CI — certification gate (typecheck + full suite on 3 OS).
+
+## Enforcement/bypass note (PLAN-BYPASS-NAMED-01)
+
+This PR adds capability classification, not enforcement: it enables a wire field xAI already accepts. Bypass/residual: an operator can force supportsServiceTier for any model via config today (that is how the probe ran) — accepted, documented behavior; the registry change only makes the probed set native. Final layer: hosted CI + review on the PR. No bypass claim is made for upstream honesty: a silent upstream downgrade is observable via tierOutcome.confirmation in request logs, not prevented.

devlog/_fin/260913_xai_oauth_fast/020_probe-evidence.md

@@ -0,0 +1,29 @@
+# Live probe evidence — xAI Grok OAuth service_tier "priority" (2026-09-13, KST)
+
+Mechanics: temporary `providers.xai.modelSupportsServiceTier` override in ~/.opencodex/config.json + POST /api/providers/reload (local one-shot capability, same path ocx's OAuth login uses). Probes: POST /v1/responses and /v1/chat/completions on the running proxy (127.0.0.1:10100, ocx 2.53.0) with model `xai/<id>--fast`. Every attempt logged credentialSource "grok-oauth", account of97b31. No API key involved.
+
+## Matrix (Responses inbound)
+
+| Model | HTTP | Upstream adapter | service_tier sent | service_tier echoed (ocx telemetry) | ocx fastOutcome/confirmation | Client body echo |
+|---|---|---|---|---|---|---|
+| grok-4.6 | 200 | openai-responses | priority | priority | applied/confirmed | yes |
+| grok-4.5 | 200 | openai-responses | priority | priority | applied/confirmed | yes |
+| grok-4.3 | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
+| grok-4.20-0309-reasoning | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
+| grok-4.20-0309-non-reasoning | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
+| grok-build-0.1 | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
+| grok-composer-2.5-fast | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
+| grok-4.20-multi-agent-0309 | 200 | openai-responses | priority | default | downgraded/downgraded | "default" |
+
+Request-id tails (ocx logs, 2026-09-13 00:4x KST): fb8c252e (4.20-non-reasoning), ffc1ac24 + f3bcff76 (multi-agent downgrades), 30869a34 + 1e2591ba (build), edc0cd22 + b2ba02e8 (composer), 6ff095a8 (4.6), 8fd2f267 (4.5), db85c0e5 (4.3, full entry captured), bf503c88 (4.20-reasoning), 54edc3de (4.20-non-reasoning r2).
+
+Chat inbound (/v1/chat/completions, --fast): grok-4.6 and grok-4.5 both 200 (chatcmpl-95b4236e…, chatcmpl-cb33c39d…). These two probes say nothing about the openai-chat wire — this install pins grok-4.6/4.5 to openai-responses via config modelAdapters. The chat-upstream echo evidence comes from the openai-chat rows above (4.3, 4.20, build, composer), and hermes-agent#89440 independently reports the echo on native chat completions over SuperGrok Heavy OAuth.
+
+Chat inbound direct relay probe (audit round 2): `xai/grok-4.3--fast` over /v1/chat/completions (openai-chat upstream, no modelAdapters override) — client body keys are exactly choices/created/id/model/object/usage with NO service_tier, while ocx telemetry for the same turn (request …6838b50b) records wireValue "priority", fastOutcome applied, confirmation confirmed, responseServiceTier "priority". The chat-inbound relay gap is therefore direct evidence, not code inference.
+
+## Findings
+
+1. The user's Grok OAuth (subscription) gateway accepts service_tier "priority" on every probed model — zero 400s, zero "Argument not supported" (the stale rejection hermes#28490 worked around).
+2. Priority is honored (echoed priority) on 7 of 8 models. grok-4.20-multi-agent-0309 accepts the field but the gateway answers "default" — a live downgrade, excluded from the change.
+3. Relay gap: for chat-wire models the echo reaches ocx attempt telemetry (tierOutcome.responseServiceTier "priority") but not the client body — 4.6/4.5 on the responses wire relay it, the chat-wire responses-lane and chat-inbound assemblies do not. D4 in 010_plan.md.
+4. Post-probe live state (kept at user request): config override trimmed to the 7 honored models and reloaded; multi-agent re-disabled in the catalog; the 7 models left enabled with --fast rows live on the running proxy. Backup at ~/.opencodex/config.json.probe-bak.

docs-site/src/content/docs/reference/configuration/providers.md

@@ -381,11 +381,19 @@ need to rediscover. Every legacy variant id keeps routing unchanged.
 
 ### xAI Priority Processing
 
-The built-in `xai` preset advertises and injects Fast only when its effective transport uses
-`authMode: "key"`. API-key mode targets `https://api.x.ai/v1` through the `openai-chat` adapter and
-sends `service_tier: "priority"` through Chat Completions. `ocx login xai`
-instead stores OAuth credentials for the separate Grok CLI subscription-gateway flow, so OAuth
-remains unclassified: its catalog rows do not advertise Fast and the proxy does not inject a tier.
+The built-in `xai` preset supports Fast on both of its transports, with different scope.
+API-key mode targets `https://api.x.ai/v1`; routes resolved to `openai-chat` send
+`service_tier: "priority"` through Chat Completions, while model defaults and overrides can
+select the `openai-responses` transport instead. `ocx login xai`
+instead stores OAuth credentials for the Grok subscription gateway
+(`https://cli-chat-proxy.grok.com/v1`; these credentials refresh automatically), where Fast
+is classified per model (live-probed 2026-09-13): grok-4.6, grok-4.5, grok-4.3, grok-4.20-0309-reasoning,
+grok-4.20-0309-non-reasoning, grok-build-0.1, and grok-composer-2.5-fast accept
+`service_tier: "priority"` over Grok OAuth and echo it, so those rows advertise Fast, accept
+`--fast` selectors, and forward a caller-sent tier on either wire. grok-4.20-multi-agent-0309
+is excluded: the gateway answers `service_tier: "default"` when sent `priority`, so it stays
+unclassified and its caller tier is not forwarded. Unlisted models stay unclassified on both
+transports.
 
 xAI charges Priority Processing at 2× the standard token price for input, output, cached, and
 reasoning tokens; cache discounts are applied before the multiplier. Cost estimates use that premium

src/chat/outbound.ts

@@ -182,6 +182,10 @@ export function responsesSseToChatCompletionsSse(
   let cancelled = false;
   let started = false;
   let sawToolUse = false;
+  // The upstream response-level service-tier echo (xAI Priority Processing, OpenAI
+  // fast tier), captured from any response event and stamped on every emitted chunk,
+  // matching how the source annotates its own streamed chat chunks.
+  let serviceTier: string | undefined;
   const id = completionId();
   const created = Math.floor(Date.now() / 1000);
   // tool call_id -> streaming index (OpenAI requires stable indices per tool call)
@@ -366,6 +370,9 @@ export function responsesSseToChatCompletionsSse(
   };
       const emit = (payload: Rec | "[DONE]") => {
         if (failed) return;
+        if (serviceTier !== undefined && isRec(payload) && Array.isArray(payload.choices)) {
+          payload.service_tier = serviceTier;
+        }
         if (terminalBatch) {
           const serialized = dataFrame(payload);
           const stringReservation = translatorBudget.reserveTransient(Buffer.byteLength(serialized), { kind: "live_transient" });
@@ -530,6 +537,9 @@ export function responsesSseToChatCompletionsSse(
       };
 
       const handleFrame = (eventName: string, data: Rec) => {
+        if (isRec(data.response) && typeof data.response.service_tier === "string") {
+          serviceTier = data.response.service_tier;
+        }
         switch (eventName) {
           case "response.created":
           case "response.heartbeat":
@@ -871,6 +881,10 @@ export function responsesJsonToChatCompletion(json: unknown, model: string, tran
       logprobs: null,
     }],
     usage: chatCompletionsUsage(body.usage),
+    // Relay the upstream service-tier echo (xAI Priority Processing, OpenAI fast tier)
+    // so a Chat Completions caller can confirm the tier the turn actually used, the
+    // same field the Responses lane already relays for responses-wire upstreams.
+    ...(typeof body.service_tier === "string" ? { service_tier: body.service_tier } : {}),
   };
 }
 
@@ -891,6 +905,7 @@ export async function collectChatCompletion(
   const callScope = (index: number) => `chat_collect_${index}`;
   let finishReason = "stop";
   let usage: unknown;
+  let serviceTier: unknown;
   const replaceRetained = (previous: string, next: string, kind: "live_transient" | "retained_collectors") => {
     const reservation = translatorBudget.reserveTransient(Buffer.byteLength(next), { kind });
     reservation.commitRetained();
@@ -951,6 +966,7 @@ export async function collectChatCompletion(
             throw streamError;
           }
           if (parsed.usage) usage = parsed.usage;
+          if (typeof parsed.service_tier === "string") serviceTier = parsed.service_tier;
           const choices = Array.isArray(parsed.choices) ? parsed.choices : [];
           const choice = isRec(choices[0]) ? choices[0] : null;
           if (!choice) continue;
@@ -1076,5 +1092,6 @@ export async function collectChatCompletion(
       logprobs: null,
     }],
     usage: usage && isRec(usage) ? usage : chatCompletionsUsage(undefined),
+    ...(typeof serviceTier === "string" ? { service_tier: serviceTier } : {}),
   };
 }