[Feature]: FastWire — generalize Fast mode across providers (umbrella)

[olddonkey]

Area

Multiple areas

What are you trying to accomplish?

Use Codex Fast mode against any provider whose API offers an accelerated processing tier — with the catalog only advertising Fast where the route can actually honor it, the wire request using each provider's own dialect, and usage/cost reporting reflecting what each attempt actually did.

This is the umbrella tracking issue for FastWire, the design that generalizes Fast mode across providers. It sequences the refactor phases and links the per-provider delivery units (starting with #1875 for xAI). The design went through a five-round adversarial review against the current code and was accepted as the implementation basis.

What prevents this today?

Fast mode is currently a single-dialect feature, with three hardwired assumptions:

• The only wire shape OpenCodex can emit is service_tier: "priority", and only on the two OpenAI adapters (openai-chat, openai-responses). Anthropic's speed: "fast" + beta header, Groq's service_tier: "performance", and Azure's deployment-scoped priority cannot be expressed at all.
• The catalog Fast blurb is the OpenAI one ("1.5x speed, increased usage") for every provider, even where the provider's actual terms differ (xAI Priority Processing bills at 2× the standard token price).
• chatServiceTier couples chat serialization into capability resolution (serviceTierSupportForModel() inlines canSerializeServiceTierForChatModel()), so one flag simultaneously influences catalog publication, routing-profile require.serviceTier eligibility, compatibility fingerprints, injection, and the gate.

Additionally, cost attribution reads top-level request fields rather than per-attempt outcomes, which mis-prices combo/fallback attempts, and there is no way to express "this provider's fast tier exists but is entitlement-gated" without either lying in the catalog or blocking the capability entirely.

What should OpenCodex do?

Separate three concerns that are currently entangled (existing config field names unchanged):

1. FastCapability — may this provider/model/auth route offer Fast at all? Existing tri-state fields: supportsServiceTier (provider-level, false is fail-closed), modelSupportsServiceTier (exact-match), auth-mode overlay.
2. CallerTierForward — may caller-supplied foreign tiers (flex, unknown strings) be forwarded? This becomes chatServiceTier's sole duty after migration.
3. FastWire — how does canonical Fast serialize on this route? A new registry descriptor: kind: "service-tier" | "anthropic-speed", a canonicalToWire map, foreignCallerTiers: "verbatim" | "drop", optional betas.

Key behaviors:

• The Codex-side contract never changes. The catalog always publishes service_tiers: [{id: "priority", name: "Fast"}]; the internal canonical tier stays "priority"; translation to the provider dialect happens only at the final serialization step.
• FastPolicyAuthority + one pure resolver. Catalog flights capture an immutable authority before takeoff (declaration tri-state fastWire: FastWire | null | undefined, precomputed modelWireOverrideAllowed covering the canonical-OpenAI-forward wire-override guard, auth transport, capability maps, model adapters, hard pins, route pins). resolveFastPolicy(authority, modelId, inbound) is shared by catalog and runtime. capability (pure tri-state) stays separate from eligibility (eligible | capability-unsupported | unclassified | wire-unavailable | pin-unavailable); catalog, routing, and injection consume only eligibility === "eligible".
• The outbound decision honors the existing three-state contract. support === false: fail-closed strip. support === undefined: full passthrough — fastMode does not intervene, no translation, no injection (today's behavior, preserved). Only support === true ∧ fastWire ≠ null enters the force-fast / force-default / inherit state machine.
• Billing truth moves per attempt. Each attempt records an AttemptTierOutcome (canonical tier, wire kind/value, fastOutcome: not-requested | applied | downgraded | unknown, confirmation, response echo). Pricing becomes an explicit (provider, model, tierBand) matrix; a missing cell with no per-entry priceRelation: "gte-standard" evidence yields cost unavailable ("unpriced-tier") rather than a guessed multiplier.
• Fast is a routing preference, not a requirement. A route that cannot express Fast strips it and records fastOutcome: "downgraded"; it never filters candidates.

Provider defaults (registry):

Provider	fastWire	capability default
OpenAI / ChatGPT	derived default (service-tier / priority)	true (status quo)
xAI (API key)	service-tier / priority	key-auth overlay true — #1875, held until pricing verified
Azure OpenAI	service-tier / priority	undefined (never false); per-deployment exact-model opt-in
OpenRouter	service-tier / priority	provider undefined; verified slugs exact-true, each with an atomic route pin (final only ⊆ pin ∧ allow_fallbacks: false; conflict downgrades Fast instead of overriding user routing)
Groq	service-tier / performance	false; enterprise users opt in explicitly
Cerebras	service-tier / priority	false; dedicated-endpoint users opt in
Anthropic	anthropic-speed / fast + betas	undefined; verified in Phase C
Google	explicit null	deferred — no Interactions wire path yet
Kimi / MiniMax -highspeed	excluded	separate model IDs, not a request tier; the Fast toggle must never silently swap models

Delivery phases:

• A0 — characterization only (zero production changes): lock the current three-state fastMode contract, the support undefined × fastMode × caller {priority, fast, flex} matrix, exact-model foreign-tier forwarding, requestedServiceTier recording timing, routing-profile require.serviceTier evidence, fingerprint projection, raw-body observation points, catalog byte goldens, and the two known bugs below as current behavior.
• A1 — pure refactor (zero outbound-wire bytes, zero catalog bytes): FastWire / FastPolicyAuthority / ResolvedFastPolicy / tier-decision state machine land; kind→adapter table contains only the existing two adapters; inbound normalization produces internal markers only.
• B0 — observability (zero upstream-wire change; intentional new logging): per-attempt outcomes, callerServiceTier raw evidence, value-aware gate, fingerprint projection, dashboard per-attempt display.
• B1 — capability semantic migration (one complete delivery): fastCapabilityForModel() replaces the resolver's inline chat-serializer coupling. Three precisely-scoped behavior changes: (a) provider-true ∧ chat adapter ∧ chatServiceTier ≠ true ∧ no exact-true → injection starts working; (b) caller "fast" on supported routes → serialized as the canonical translation; (c) exact-true ∧ chatServiceTier ≠ true ∧ caller foreign tier → dropped instead of forwarded.
• Bug fixes (independent units): native chat path ignores model-level false; chat→responses converter drops service_tier.
• B2 — xAI ([Feature]: enable xAI API-key Priority Processing in Codex Fast mode #1875): capability + catalog description + pricing-matrix entry in one merge unit.
• B2+ — OpenRouter / Azure OpenAI / Groq / Cerebras: one unit each.
• C — anthropic-speed wire kind, after live verification on both auth entries.

Out of scope: Google Interactions API, requirement-mode routing, multi-tier UI beyond Fast, model-swap "highspeed" variants.

Example usage or interface

A Groq enterprise user with Performance-tier entitlement opts in with one line:

{
  "providers": {
    "groq": { "supportsServiceTier": true }
  },
  "fastMode": true
}

Because the registry already declares Groq's wire shape (canonicalToWire: { priority: "performance" }), the effective Chat Completions body becomes:

{
  "model": "llama-3.3-70b-versatile",
  "service_tier": "performance"
}

while the Codex catalog row advertises the same priority/Fast tier it does everywhere else, and the usage log records wireValue: "performance" with canonical "priority". On an Anthropic route (Phase C), the same Fast selection would instead produce "speed": "fast" plus the documented beta header, and never a service_tier field.

Alternatives or workarounds

• Keep adding per-provider booleans to the current supportsServiceTier/chatServiceTier machinery. Rejected: it cannot express non-OpenAI dialects (Anthropic, Groq values), keeps the capability/serialization coupling, and forces every entitlement-gated provider into "lie in the catalog or block entirely".
• Users can already hand-declare modelSupportsServiceTier/chatServiceTier on custom providers, but that only works for OpenAI-dialect upstreams and silently mis-prices attempts because cost reads top-level request fields.
• Treating "fast" model variants (Kimi/MiniMax -highspeed) as the Fast toggle. Rejected: that silently swaps model IDs and billing; those stay separate catalog models.

Additional context

• Capability framework lineage: [Feature]: expose speed/service-tier capabilities for eligible custom providers and routed models #1436, fix(openai-chat): forward caller-selected service tier #1512, feat: land four rebuilt heavy drafts (service tiers, request pacing, native chat, empty-completion guard) #1752.
• xAI delivery unit: [Feature]: enable xAI API-key Priority Processing in Codex Fast mode #1875 (implementation branch exists, held unmerged until the pricing-matrix entry and catalog description land in the same unit).
• History: Phase 90 deliberately stripped inherited Fast metadata from every routed provider pending per-transport verification; FastWire restores it only where the final transport is verified, and makes the verification unit (shape vs. capability vs. pricing) explicit.
• Design provenance: five review rounds against the live code preceded this issue; the review-driven corrections (three-state passthrough preservation, per-attempt billing, atomic OpenRouter pins, modelWireOverrideAllowed) are folded into the text above.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.

[coderabbitai]

🔗 Related PRs

#652 - feat(providers): add bounded model discovery contract [merged]
#746 - fix(providers): route GitHub Copilot Responses-only models off chat completions [open]
#860 - fix(responses): gate service tiers by provider capability [open]
#889 - fix(providers): Copilot mixed-wire routing, DeepSeek service_tier + reasoning replay, Claude 4.6/4.7 1M windows [open]
#892 - fix: bound the six remaining retained-state leaks (#820 wave 2) [merged]
#1512 - fix(openai-chat): forward caller-selected service tier [merged]
#1606 - docs(devlog): routed tool-discovery profile plan with landing verification [open]
#1752 - feat: land four rebuilt heavy drafts (service tiers, request pacing, native chat, empty-completion guard) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Issue reopened

The report now contains the information required by the automated check. Thanks for updating it.