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

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):

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.