Skip to content

Commit 7ca00ff

Browse files
authored
feat(xai): classify Grok OAuth service tier per model and relay the tier echo (#4431)
* docs(devlog): plan xAI Grok OAuth fast-tier lane (probe evidence + decision table) * docs(devlog): fold audit blockers into the xai oauth fast plan (scope honesty, revert residue, direct chat relay probe) * feat(xai): classify Grok OAuth service tier per model and relay the tier echo Live-probed 2026-09-13 on the Grok subscription gateway: grok-4.6, 4.5, 4.3, 4.20-0309-reasoning/non-reasoning, grok-build-0.1 and grok-composer-2.5-fast accept service_tier "priority" over Grok OAuth and echo it, matching the API-key Priority Processing contract. The registry entry classifies exactly that set (modelSupportsServiceTier + chatServiceTier), so the OAuth lane resolves Fast-eligible: --fast rows publish, fastMode can force the tier, and a caller-sent tier forwards on either wire. grok-4.20-multi-agent-0309 is excluded — the gateway answers service_tier "default" when sent priority — and keeps its caller-tier pin. Also relay the upstream service_tier echo to Chat Completions clients on the non-stream, stream, and folded delivery shapes, matching what the Responses lane already relayed for responses-wire upstreams. Probe evidence + decision table: devlog/_fin/260913_xai_oauth_fast/ * test(xai): update catalog and streaming pins for the classified OAuth fast lane * docs(xai): address review: update all src/chat structure owners and split the key/OAuth Fast scope sentence * fix(chat): relay the tier echo on the live Responses-SSE translator; address CodeRabbit findings
1 parent dcd13b4 commit 7ca00ff

16 files changed

Lines changed: 407 additions & 34 deletions

File tree

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# xAI Grok OAuth fast tier (service_tier: "priority") — plan
2+
3+
## Loop spec (HOTL wp1)
4+
5+
- 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.
6+
- 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.
7+
- Budget: unlimited read-only subagents on xai/grok-4.6 (user-granted); probe calls already completed.
8+
- 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.
9+
- Certification: hosted exact-head CI only. Full local suite and local typecheck NOT RUN (standing rule); focused tests below are development feedback, not certification.
10+
11+
## Context
12+
13+
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.
14+
15+
## Decision table
16+
17+
- 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).
18+
- 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.
19+
- 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).
20+
- 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).
21+
- 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.
22+
- 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.
23+
- 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).
24+
- D7 Evidence: probe matrix recorded in 020_probe-evidence.md; PR Verification cites it (summarized, no secrets).
25+
- 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.
26+
- 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.
27+
28+
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.
29+
30+
## File change map
31+
32+
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.
33+
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).
34+
3. Tests (D5 files above).
35+
4. structure/providers/xai-grok.md — lane classification + probe date.
36+
5. devlog: this unit moves to devlog/_fin/260913_xai_oauth_fast/ in the same PR after merge evidence exists.
37+
38+
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.
39+
40+
## Accept criteria (activation in parentheses)
41+
42+
- C1 fastPolicyForModel(xai-oauth, grok-4.6, "xai", "responses").eligibility === "eligible" (unit test constructs the xai provider with authMode oauth).
43+
- C2 grok-4.20-multi-agent-0309 stays unclassified: capability undefined, no --fast row (unit test + catalog listing test).
44+
- 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).
45+
- C4 --fast rows publish for the 7 models on the catalog listing (catalogFastRowEligible path; test feeds an oauth xai config).
46+
- 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.
47+
- 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.
48+
- 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.
49+
50+
## Verifiers (run pre-plan, exit 0, reads-target noted)
51+
52+
- `bun test tests/providers/xai/xai-transport.test.ts` — exit 0, 47 tests; imports getProviderRegistryEntry (reads registry.ts).
53+
- `bun test tests/service/service-tier-capability.test.ts` — exit 0, 35 tests; imports fastPolicyForModel/enrichProviderFromRegistry (reads service-tier.ts/derive.ts).
54+
- `bun test tests/routing/fastwire-policy.test.ts` — exit 0, 236 tests; imports resolveFastPolicy (reads fastwire.ts + registry wire defaults).
55+
- `bun test tests/providers/fast-row-ingress.test.ts` — exit 0, 9 tests; parseSyntheticRowId ingress (reads fast-row.ts).
56+
- `bun test tests/codex-integration/fast-row.test.ts` — exit 0, 38 tests; fast-row grammar/listing.
57+
- Hosted PR CI — certification gate (typecheck + full suite on 3 OS).
58+
59+
## Enforcement/bypass note (PLAN-BYPASS-NAMED-01)
60+
61+
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.
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Live probe evidence — xAI Grok OAuth service_tier "priority" (2026-09-13, KST)
2+
3+
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.
4+
5+
## Matrix (Responses inbound)
6+
7+
| Model | HTTP | Upstream adapter | service_tier sent | service_tier echoed (ocx telemetry) | ocx fastOutcome/confirmation | Client body echo |
8+
|---|---|---|---|---|---|---|
9+
| grok-4.6 | 200 | openai-responses | priority | priority | applied/confirmed | yes |
10+
| grok-4.5 | 200 | openai-responses | priority | priority | applied/confirmed | yes |
11+
| grok-4.3 | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
12+
| grok-4.20-0309-reasoning | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
13+
| grok-4.20-0309-non-reasoning | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
14+
| grok-build-0.1 | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
15+
| grok-composer-2.5-fast | 200 | openai-chat | priority | priority | applied/confirmed | NO (relay gap) |
16+
| grok-4.20-multi-agent-0309 | 200 | openai-responses | priority | default | downgraded/downgraded | "default" |
17+
18+
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).
19+
20+
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.
21+
22+
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.
23+
24+
## Findings
25+
26+
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).
27+
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.
28+
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.
29+
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‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -381,11 +381,19 @@ need to rediscover. Every legacy variant id keeps routing unchanged.
381381

382382
### xAI Priority Processing
383383

384-
The built-in `xai` preset advertises and injects Fast only when its effective transport uses
385-
`authMode: "key"`. API-key mode targets `https://api.x.ai/v1` through the `openai-chat` adapter and
386-
sends `service_tier: "priority"` through Chat Completions. `ocx login xai`
387-
instead stores OAuth credentials for the separate Grok CLI subscription-gateway flow, so OAuth
388-
remains unclassified: its catalog rows do not advertise Fast and the proxy does not inject a tier.
384+
The built-in `xai` preset supports Fast on both of its transports, with different scope.
385+
API-key mode targets `https://api.x.ai/v1`; routes resolved to `openai-chat` send
386+
`service_tier: "priority"` through Chat Completions, while model defaults and overrides can
387+
select the `openai-responses` transport instead. `ocx login xai`
388+
instead stores OAuth credentials for the Grok subscription gateway
389+
(`https://cli-chat-proxy.grok.com/v1`; these credentials refresh automatically), where Fast
390+
is classified per model (live-probed 2026-09-13): grok-4.6, grok-4.5, grok-4.3, grok-4.20-0309-reasoning,
391+
grok-4.20-0309-non-reasoning, grok-build-0.1, and grok-composer-2.5-fast accept
392+
`service_tier: "priority"` over Grok OAuth and echo it, so those rows advertise Fast, accept
393+
`--fast` selectors, and forward a caller-sent tier on either wire. grok-4.20-multi-agent-0309
394+
is excluded: the gateway answers `service_tier: "default"` when sent `priority`, so it stays
395+
unclassified and its caller tier is not forwarded. Unlisted models stay unclassified on both
396+
transports.
389397

390398
xAI charges Priority Processing at 2× the standard token price for input, output, cached, and
391399
reasoning tokens; cache discounts are applied before the multiplier. Cost estimates use that premium

‎src/chat/outbound.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,10 @@ export function responsesSseToChatCompletionsSse(
182182
let cancelled = false;
183183
let started = false;
184184
let sawToolUse = false;
185+
// The upstream response-level service-tier echo (xAI Priority Processing, OpenAI
186+
// fast tier), captured from any response event and stamped on every emitted chunk,
187+
// matching how the source annotates its own streamed chat chunks.
188+
let serviceTier: string | undefined;
185189
const id = completionId();
186190
const created = Math.floor(Date.now() / 1000);
187191
// tool call_id -> streaming index (OpenAI requires stable indices per tool call)
@@ -366,6 +370,9 @@ export function responsesSseToChatCompletionsSse(
366370
};
367371
const emit = (payload: Rec | "[DONE]") => {
368372
if (failed) return;
373+
if (serviceTier !== undefined && isRec(payload) && Array.isArray(payload.choices)) {
374+
payload.service_tier = serviceTier;
375+
}
369376
if (terminalBatch) {
370377
const serialized = dataFrame(payload);
371378
const stringReservation = translatorBudget.reserveTransient(Buffer.byteLength(serialized), { kind: "live_transient" });
@@ -530,6 +537,9 @@ export function responsesSseToChatCompletionsSse(
530537
};
531538

532539
const handleFrame = (eventName: string, data: Rec) => {
540+
if (isRec(data.response) && typeof data.response.service_tier === "string") {
541+
serviceTier = data.response.service_tier;
542+
}
533543
switch (eventName) {
534544
case "response.created":
535545
case "response.heartbeat":
@@ -871,6 +881,10 @@ export function responsesJsonToChatCompletion(json: unknown, model: string, tran
871881
logprobs: null,
872882
}],
873883
usage: chatCompletionsUsage(body.usage),
884+
// Relay the upstream service-tier echo (xAI Priority Processing, OpenAI fast tier)
885+
// so a Chat Completions caller can confirm the tier the turn actually used, the
886+
// same field the Responses lane already relays for responses-wire upstreams.
887+
...(typeof body.service_tier === "string" ? { service_tier: body.service_tier } : {}),
874888
};
875889
}
876890

@@ -891,6 +905,7 @@ export async function collectChatCompletion(
891905
const callScope = (index: number) => `chat_collect_${index}`;
892906
let finishReason = "stop";
893907
let usage: unknown;
908+
let serviceTier: unknown;
894909
const replaceRetained = (previous: string, next: string, kind: "live_transient" | "retained_collectors") => {
895910
const reservation = translatorBudget.reserveTransient(Buffer.byteLength(next), { kind });
896911
reservation.commitRetained();
@@ -951,6 +966,7 @@ export async function collectChatCompletion(
951966
throw streamError;
952967
}
953968
if (parsed.usage) usage = parsed.usage;
969+
if (typeof parsed.service_tier === "string") serviceTier = parsed.service_tier;
954970
const choices = Array.isArray(parsed.choices) ? parsed.choices : [];
955971
const choice = isRec(choices[0]) ? choices[0] : null;
956972
if (!choice) continue;
@@ -1076,5 +1092,6 @@ export async function collectChatCompletion(
10761092
logprobs: null,
10771093
}],
10781094
usage: usage && isRec(usage) ? usage : chatCompletionsUsage(undefined),
1095+
...(typeof serviceTier === "string" ? { service_tier: serviceTier } : {}),
10791096
};
10801097
}

0 commit comments

Comments
 (0)