@yansigit/opencodex 2.31.0

package/src/providers/service-tier.ts

@@ -0,0 +1,277 @@
+import type { OcxProviderConfig } from "../types";
+import { captureWireAdapterHardPins } from "../types";
+import { isCanonicalOpenAiForwardProvider } from "./openai-tiers";
+import {
+  getProviderRegistryEntry,
+  providerMatchesRegistryTransport,
+  registryModelServiceTierCapabilityApplies,
+  type InboundWire,
+  type ModelWireDefault,
+} from "./registry";
+import {
+  cloneFastWire,
+  resolveFastPolicy,
+  resolveProviderAuthTransport,
+  type FastPolicyAuthority,
+  type ResolvedFastPolicy,
+} from "./fastwire";
+
+/** OpenAI-compatible adapters that can carry the standard `service_tier` field. */
+export const SERVICE_TIER_ADAPTERS = new Set(["openai-chat", "openai-responses"]);
+
+/** @deprecated A1 evolves this snapshot into the complete FastPolicyAuthority. */
+export type CapturedServiceTierAdapterAuthority = FastPolicyAuthority;
+
+const capturedFastPolicyAuthorities = new WeakMap<object, FastPolicyAuthority>();
+
+type ServiceTierCapabilityProvider = Pick<
+  OcxProviderConfig,
+  | "adapter"
+  | "supportsServiceTier"
+  | "modelSupportsServiceTier"
+  | "modelAdapters"
+  | "baseUrl"
+  | "authMode"
+  | "apiKeyTransport"
+  | "chatServiceTier"
+  | "fastWire"
+>;
+
+function cloneRegistryWireDefaults(
+  defaults: Readonly<Record<string, ModelWireDefault>> | undefined,
+): Readonly<Record<string, ModelWireDefault>> {
+  if (!defaults) return Object.freeze({});
+  const clone: Record<string, ModelWireDefault> = {};
+  for (const [modelId, declaration] of Object.entries(defaults)) {
+    clone[modelId.trim().toLowerCase()] = typeof declaration === "string"
+      ? declaration
+      : Object.freeze({
+          wire: declaration.wire,
+          inbound: Object.freeze([...declaration.inbound]),
+          ...(declaration.authModes
+            ? { authModes: Object.freeze([...declaration.authModes]) }
+            : {}),
+          ...(declaration.forwardCallerServiceTier !== undefined
+            ? { forwardCallerServiceTier: declaration.forwardCallerServiceTier }
+            : {}),
+        });
+  }
+  return Object.freeze(clone);
+}
+
+/**
+ * Capture every registry-owned input before an asynchronous catalog flight begins.
+ * The resolver itself is pure and never reads the live provider registry.
+ */
+function buildFastPolicyAuthority(
+  providerName: string,
+  provider: ServiceTierCapabilityProvider,
+  registryTransportMatch: boolean,
+  capabilityProvider: ServiceTierCapabilityProvider = provider,
+): FastPolicyAuthority {
+  const registry = registryTransportMatch ? getProviderRegistryEntry(providerName) : undefined;
+  const authTransport = resolveProviderAuthTransport(
+    provider.adapter,
+    provider.authMode ?? registry?.authKind ?? "key",
+    provider.apiKeyTransport,
+  );
+  const keyAuthDefaults = registry?.allowKeyAuthOverride === true
+    && (authTransport === "authorization_bearer" || authTransport === "x_api_key")
+    ? registry.keyAuthServiceTier
+    : undefined;
+  const registryModelCapabilities = registry
+    && registryModelServiceTierCapabilityApplies(registry, capabilityProvider)
+    ? registry.modelSupportsServiceTier
+    : undefined;
+  const providerCapability = capabilityProvider.supportsServiceTier
+    ?? keyAuthDefaults?.supportsServiceTier
+    ?? registry?.supportsServiceTier;
+  const authority: FastPolicyAuthority = Object.freeze({
+    providerAdapter: provider.adapter,
+    providerAuthMode: provider.authMode ?? registry?.authKind ?? "key",
+    fastWireDeclaration: cloneFastWire(
+      provider.fastWire !== undefined ? provider.fastWire : registry?.fastWire,
+      { freeze: true },
+    ),
+    ...(registry?.fastTierDescription !== undefined
+      ? { fastTierDescription: registry.fastTierDescription }
+      : {}),
+    modelWireOverrideAllowed: !isCanonicalOpenAiForwardProvider(provider as OcxProviderConfig),
+    authTransport,
+    capability: Object.freeze({
+      ...(providerCapability !== undefined ? { provider: providerCapability } : {}),
+      models: Object.freeze({
+        ...(registryModelCapabilities ?? {}),
+        ...(keyAuthDefaults?.modelSupportsServiceTier ?? {}),
+        ...(capabilityProvider.modelSupportsServiceTier ?? {}),
+      }),
+      ...(provider.chatServiceTier !== undefined
+        ? { chatServiceTier: provider.chatServiceTier }
+        : keyAuthDefaults?.chatServiceTier !== undefined
+          ? { chatServiceTier: keyAuthDefaults.chatServiceTier }
+          : {}),
+    }),
+    modelAdapters: Object.freeze({ ...(provider.modelAdapters ?? {}) }),
+    hardPins: captureWireAdapterHardPins(providerName),
+    registryWireDefaults: cloneRegistryWireDefaults(registry?.modelWireDefaults),
+  });
+  return authority;
+}
+
+export function captureFastPolicyAuthority(
+  providerName: string,
+  provider: ServiceTierCapabilityProvider,
+  registryTransportMatch: boolean,
+  capabilityProvider: ServiceTierCapabilityProvider = provider,
+): FastPolicyAuthority {
+  const authority = buildFastPolicyAuthority(
+    providerName,
+    provider,
+    registryTransportMatch,
+    capabilityProvider,
+  );
+  if (Object.isFrozen(provider)) capturedFastPolicyAuthorities.set(provider, authority);
+  return authority;
+}
+
+/** @deprecated Use captureFastPolicyAuthority. The legacy inbound argument is now snapshot data. */
+export function captureServiceTierAdapterAuthority(
+  providerName: string,
+  provider: ServiceTierCapabilityProvider,
+  registryTransportMatch: boolean,
+  _inbound: InboundWire = "responses",
+): FastPolicyAuthority {
+  return captureFastPolicyAuthority(providerName, provider, registryTransportMatch);
+}
+
+function authorityForProvider(
+  provider: ServiceTierCapabilityProvider,
+  providerName?: string,
+  capabilityProvider?: ServiceTierCapabilityProvider,
+): FastPolicyAuthority {
+  // Preserve the legacy no-name short circuit: serviceTierSupportForModel() used the
+  // provider adapter directly when no provider identity was available, so no configured
+  // override, hard pin, or registry default may participate on this path in A1.
+  if (providerName === undefined) {
+    const authority = buildFastPolicyAuthority("", provider, false, capabilityProvider ?? provider);
+    return Object.freeze({
+      ...authority,
+      modelAdapters: Object.freeze({}),
+      hardPins: Object.freeze({}),
+      registryWireDefaults: Object.freeze({}),
+    });
+  }
+  const captured = capabilityProvider === undefined && Object.isFrozen(provider)
+    ? capturedFastPolicyAuthorities.get(provider)
+    : undefined;
+  if (captured) return captured;
+  const registryTransportMatch = providerMatchesRegistryTransport(providerName, provider);
+  const authority = buildFastPolicyAuthority(
+    providerName,
+    provider,
+    registryTransportMatch,
+    capabilityProvider ?? provider,
+  );
+  // Frozen provider snapshots cannot drift, so repeated catalog/runtime projections may safely
+  // reuse the registry lookup and detached declaration maps. Mutable configs still rebuild.
+  if (Object.isFrozen(provider)) capturedFastPolicyAuthorities.set(provider, authority);
+  return authority;
+}
+
+/** Resolve the pure Fast policy for a provider/model pair. */
+export function fastPolicyForModel(
+  provider: ServiceTierCapabilityProvider,
+  modelId: string,
+  providerName?: string,
+  inbound: InboundWire = "responses",
+  capabilityProvider?: ServiceTierCapabilityProvider,
+): ResolvedFastPolicy {
+  return resolveFastPolicy(
+    authorityForProvider(provider, providerName, capabilityProvider),
+    modelId,
+    inbound,
+  );
+}
+
+/**
+ * Resolve the declared provider/model capability without applying wire availability.
+ * Kept as a public compatibility helper for callers that need the pure tri-state.
+ */
+export function supportsServiceTierForModel(
+  provider: Pick<OcxProviderConfig, "supportsServiceTier" | "modelSupportsServiceTier">,
+  modelId: string,
+): boolean | undefined {
+  const authority: FastPolicyAuthority = {
+    providerAdapter: "openai-responses",
+    fastWireDeclaration: undefined,
+    modelWireOverrideAllowed: true,
+    authTransport: "authorization_bearer",
+    capability: {
+      ...(provider.supportsServiceTier !== undefined ? { provider: provider.supportsServiceTier } : {}),
+      models: provider.modelSupportsServiceTier ?? {},
+    },
+    modelAdapters: {},
+    hardPins: {},
+    registryWireDefaults: {},
+  };
+  return resolveFastPolicy(authority, modelId).capability;
+}
+
+/** Whether a Chat route may forward an arbitrary caller tier rather than canonical Fast. */
+export function canForwardForeignServiceTierForChatModel(
+  provider: Pick<OcxProviderConfig, "supportsServiceTier" | "modelSupportsServiceTier" | "chatServiceTier">,
+  modelId: string,
+): boolean {
+  const capability = supportsServiceTierForModel(provider, modelId);
+  return capability !== false && provider.chatServiceTier === true;
+}
+
+/** Final adapter selected by the Fast policy's four-level wire resolver. */
+export function serviceTierAdapterForModel(
+  providerName: string,
+  provider: ServiceTierCapabilityProvider,
+  modelId: string,
+  inbound: InboundWire = "responses",
+): string {
+  return fastPolicyForModel(provider, modelId, providerName, inbound).adapter;
+}
+
+/** Whether the final provider/model pair can publish/send OpenAI service tiers. */
+export function canForwardServiceTierForModel(
+  provider: ServiceTierCapabilityProvider,
+  modelId: string,
+  providerName?: string,
+  inbound: InboundWire = "responses",
+): boolean {
+  return serviceTierSupportForModel(provider, modelId, providerName, inbound) === true;
+}
+
+/**
+ * Compatibility projection for catalog, routing, and fingerprint consumers. The new
+ * resolver carries richer eligibility internally while preserving the old tri-state bytes.
+ */
+export function serviceTierSupportForModel(
+  provider: ServiceTierCapabilityProvider,
+  modelId: string,
+  providerName?: string,
+  inbound: InboundWire = "responses",
+): boolean | undefined {
+  const policy = fastPolicyForModel(provider, modelId, providerName, inbound);
+  return serviceTierSupportFromPolicy(policy);
+}
+
+/** Compatibility projection shared by catalog, routing, and request logging. */
+export function serviceTierSupportFromPolicy(
+  policy: Pick<ResolvedFastPolicy, "eligibility" | "adapter" | "forwardCallerTier">,
+): boolean | undefined {
+  if (policy.eligibility === "eligible") return true;
+  if (policy.eligibility === "unclassified") {
+    // An unclassified route that cannot forward a caller tier has definitive negative
+    // evidence even when its adapter can normally serialize service_tier. This covers both
+    // Chat routes without chatServiceTier and a registry default that explicitly closes a
+    // subscription gateway. Generic unclassified Responses routes still project unknown.
+    if (!policy.forwardCallerTier) return false;
+    return undefined;
+  }
+  return false;
+}

package/src/providers/slug-codec.ts

@@ -0,0 +1,103 @@
+/**
+ * Codex-facing slug codec for routed models whose NATIVE ids contain "/".
+ *
+ * Codex's models-manager resolves per-model metadata (effort ladder, context window,
+ * capabilities — "tagging") with an exact one-slash rule: the namespaced-suffix lookup
+ * (codex-rs models-manager/src/manager.rs, `find_model_by_namespaced_suffix`) splits
+ * once on "/" and rejects the lookup when the remainder still contains "/". Providers
+ * whose native ids are themselves namespaced (zenmux `moonshotai/kimi-k3-free`,
+ * openrouter `anthropic/...`, nvidia `moonshotai/...`, together, fireworks, …) would
+ * otherwise produce two-slash Codex slugs that silently fall back to default metadata.
+ *
+ * Contract:
+ * - Codex-facing surfaces (catalog entries, picker lists, Codex-bound config picks)
+ *   use `routedSlug(provider, id)` — inner slashes become "-".
+ * - Internal state (upstream requests, logs, usage, jawcode metadata, combo keys)
+ *   keeps the native id. Decoding is an EXACT bijective lookup against the provider's
+ *   known native ids — never a blind "-" → "/" replace — with three ordered rules:
+ *   native exact match (back-compat with raw full-slash selectors) > unique alias
+ *   match > pass-through unchanged (honest upstream error).
+ * - Config comparisons are tolerant via `slugEquals`/`slugsEquivalent` so legacy raw
+ *   values keep working regardless of which form was stored.
+ */
+
+/** Separator standing in for "/" inside the model-id portion of a Codex-facing slug. */
+export const SLUG_ALIAS_SEPARATOR = "-";
+
+/** Native model id -> Codex-facing alias id. No-op for ids without "/". */
+export function encodeRoutedModelId(id: string): string {
+  return id.includes("/") ? id.replaceAll("/", SLUG_ALIAS_SEPARATOR) : id;
+}
+
+/**
+ * True when `modelId` shares a Codex-facing encoded form with a different known id.
+ * That collision is what makes `provider/openai-gpt-5.5` decode to native `openai-gpt-5.5`
+ * while a custom `openai/gpt-5.5` row is still visible.
+ */
+export function encodedModelIdCollides(modelId: string, knownIds: Iterable<string>): boolean {
+  const encoded = encodeRoutedModelId(modelId);
+  for (const id of knownIds) {
+    if (id === modelId) continue;
+    if (encodeRoutedModelId(id) === encoded) return true;
+  }
+  return false;
+}
+
+/** Codex-facing routed slug: exactly one "/" — `<provider>/<encoded id>`. */
+export function routedSlug(provider: string, id: string): string {
+  return `${provider}/${encodeRoutedModelId(id)}`;
+}
+
+/**
+ * Map a Codex-supplied model id back to the provider's native id.
+ * `knownIds` is the provider's known native ids (config ∪ registry ∪ live cache).
+ */
+export function decodeRoutedModelId(requested: string, knownIds: Iterable<string>): string {
+  let aliasMatch: string | undefined;
+  for (const id of knownIds) {
+    if (id === requested) return requested; // native exact (raw selector back-compat)
+    if (id.includes("/") && encodeRoutedModelId(id) === requested) {
+      // Ambiguous alias (e.g. both `a/b` and `a-b` exist): refuse to guess.
+      if (aliasMatch !== undefined && aliasMatch !== id) return requested;
+      aliasMatch = id;
+    }
+  }
+  return aliasMatch ?? requested;
+}
+
+/**
+ * Decode a Codex-facing id, but fail when a custom slash id and another known id
+ * share the same encoded form. Write-time checks cannot cover a later live cache.
+ */
+export function decodeRoutedModelIdOrThrow(requested: string, knownIds: Iterable<string>): string {
+  const ids = [...knownIds];
+  const encodedRequested = encodeRoutedModelId(requested);
+  const matches = new Set<string>();
+  for (const id of ids) {
+    if (id === requested || encodeRoutedModelId(id) === encodedRequested) matches.add(id);
+  }
+  if (matches.size > 1) throw new Error(`ambiguous model id "${requested}"`);
+  return decodeRoutedModelId(requested, ids);
+}
+
+/** Does a stored config slug name this routed model, in either raw or encoded form? */
+export function slugEquals(stored: string, provider: string, id: string): boolean {
+  return stored === `${provider}/${id}` || stored === routedSlug(provider, id);
+}
+
+/** Stable key for the exact equivalence relation used by catalog/config slug matching. */
+export function slugEquivalenceKey(slug: string): string {
+  const slash = slug.indexOf("/");
+  return slash <= 0
+    ? JSON.stringify(["exact", slug])
+    : JSON.stringify([
+      "routed",
+      slug.slice(0, slash),
+      encodeRoutedModelId(slug.slice(slash + 1)),
+    ]);
+}
+
+/** Equivalence between two routed slugs regardless of raw/encoded mix. */
+export function slugsEquivalent(a: string, b: string): boolean {
+  return a === b || slugEquivalenceKey(a) === slugEquivalenceKey(b);
+}

package/src/providers/static-model-discovery.ts

@@ -0,0 +1,86 @@
+import type { OcxProviderConfig } from "../types";
+import {
+  getProviderRegistryEntry,
+  providerMatchesRegistryTransport,
+  type ProviderRegistryEntry,
+} from "./registry";
+
+const STATIC_MODEL_CATALOG_PROVIDER_IDS = new Set(["cline-pass", "mimo-free"]);
+
+function normalizedEndpoint(value: string): string {
+  const trimmed = value.trim();
+  try {
+    const parsed = new URL(trimmed);
+    parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+    return parsed.toString().replace(/\/$/, "");
+  } catch {
+    return trimmed.replace(/\/+$/, "");
+  }
+}
+
+function exactRegistryTransportMatch(
+  entry: ProviderRegistryEntry,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+  options: { allowLegacyMimoLocal?: boolean } = {},
+): boolean {
+  if (entry.allowBaseUrlOverride || /\{[^}]*\}/.test(entry.baseUrl)) return false;
+  if (typeof provider.baseUrl !== "string" || provider.adapter !== entry.adapter) return false;
+  const legacyMimoLocal = options.allowLegacyMimoLocal === true
+    && entry.id === "mimo-free"
+    && provider.authMode === "local";
+  if (provider.authMode !== undefined && provider.authMode !== "key" && !legacyMimoLocal) return false;
+  return normalizedEndpoint(provider.baseUrl) === normalizedEndpoint(entry.baseUrl);
+}
+
+/** Registry policy for providers whose maintained model list is authoritative. */
+export function registryEntrySupportsLiveModelDiscovery(entry: ProviderRegistryEntry): boolean {
+  return !STATIC_MODEL_CATALOG_PROVIDER_IDS.has(entry.id);
+}
+
+/**
+ * Static-catalog authority is tied to canonical provider identity and exact transport.
+ * Renamed/custom rows stay operator-owned: Cline and ClinePass intentionally share a transport,
+ * so destination matching alone cannot safely identify a renamed ClinePass configuration.
+ */
+export function staticModelCatalogEntryForProvider(
+  name: string,
+  provider: OcxProviderConfig,
+): ProviderRegistryEntry | undefined {
+  const entry = getProviderRegistryEntry(name);
+  if (!entry || !STATIC_MODEL_CATALOG_PROVIDER_IDS.has(entry.id)) return undefined;
+  return exactRegistryTransportMatch(entry, provider, { allowLegacyMimoLocal: true })
+    ? entry
+    : undefined;
+}
+
+export function providerSupportsLiveModelDiscovery(name: string, provider: OcxProviderConfig): boolean {
+  return staticModelCatalogEntryForProvider(name, provider) === undefined;
+}
+
+/**
+ * MiMo Free predates collision preservation in the registry. Keep same-named custom rows out of
+ * registry ownership without broadening the generic transport matcher to other key providers.
+ */
+export function providerMatchesRegistryTransportWithStaticGuards(
+  name: string,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+): boolean {
+  if (name !== "mimo-free") return providerMatchesRegistryTransport(name, provider);
+  const entry = getProviderRegistryEntry(name);
+  return entry !== undefined
+    && exactRegistryTransportMatch(entry, provider, { allowLegacyMimoLocal: true });
+}
+
+/** Repair only registry-owned legacy state; operator-owned model lists stay untouched. */
+export function repairStaticModelCatalogProvider(name: string, provider: OcxProviderConfig): void {
+  const entry = staticModelCatalogEntryForProvider(name, provider);
+  if (!entry) return;
+  provider.liveModels = false;
+  if (
+    name === "mimo-free"
+    && entry.id === "mimo-free"
+    && (provider.authMode === undefined || provider.authMode === "local")
+  ) {
+    provider.authMode = "key";
+  }
+}

package/src/providers/xai-responses-opt-in.ts

@@ -0,0 +1,15 @@
+import type { OcxProviderConfig } from "../types";
+
+export const XAI_RESPONSES_OPT_IN_MODELS = ["grok-4.6", "grok-4.5"] as const;
+
+export type XaiResponsesOptInState = boolean | "mixed";
+
+/** Derived dashboard/API state for the two modelAdapters entries owned by the xAI opt-in. */
+export function xaiResponsesOptInState(provider: OcxProviderConfig): XaiResponsesOptInState {
+  const enabled = XAI_RESPONSES_OPT_IN_MODELS.map(
+    model => provider.modelAdapters?.[model] === "openai-responses",
+  );
+  if (enabled.every(Boolean)) return true;
+  if (enabled.some(Boolean)) return "mixed";
+  return false;
+}

package/src/providers/xai-transport.ts

@@ -0,0 +1,148 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { OcxProviderConfig } from "../types";
+import { resolveGithubCopilotTransport } from "./github-copilot-transport";
+
+export const XAI_GROK_CLI_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+
+export const XAI_GROK_COMPATIBILITY = {
+  version: "0.2.93",
+  userAgent: "opencodex-grok/0.2.93",
+  headers: {
+    clientIdentifier: "x-grok-client-identifier",
+    clientVersion: "x-grok-client-version",
+    tokenAuth: "x-xai-token-auth",
+    authenticateResponse: "x-authenticateresponse",
+    conversationId: "x-grok-conv-id",
+    requestId: "x-grok-req-id",
+    sessionId: "x-grok-session-id",
+    userAgent: "User-Agent",
+  },
+} as const;
+
+export const XAI_GROK_CLIENT_VERSION = XAI_GROK_COMPATIBILITY.version;
+export const XAI_CONV_ID_HEADER = XAI_GROK_COMPATIBILITY.headers.conversationId;
+
+export type OcxProviderTransport = OcxProviderConfig & {
+  /** Request executor used only at runtime; never persisted. */
+  fetch?: typeof globalThis.fetch;
+};
+
+const XAI_GROK_CLI_HEADERS: Readonly<Record<string, string>> = {
+  [XAI_GROK_COMPATIBILITY.headers.clientIdentifier]: "opencodex",
+  [XAI_GROK_COMPATIBILITY.headers.clientVersion]: XAI_GROK_CLIENT_VERSION,
+  [XAI_GROK_COMPATIBILITY.headers.tokenAuth]: "xai-grok-cli",
+  [XAI_GROK_COMPATIBILITY.headers.authenticateResponse]: "authenticate-response",
+};
+
+function hasHeaderCaseInsensitive(
+  headers: Record<string, string> | undefined,
+  name: string,
+): boolean {
+  const target = name.toLowerCase();
+  return Object.keys(headers ?? {}).some(key => key.toLowerCase() === target);
+}
+
+function withoutUserOverridden(
+  defaults: Readonly<Record<string, string>>,
+  userHeaders: Record<string, string> | undefined,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(defaults).filter(([name]) => !hasHeaderCaseInsensitive(userHeaders, name)),
+  );
+}
+
+function withGeneratedRequestId(
+  init: RequestInit | undefined,
+  pinnedRequestId: string,
+  stableHeaders: Readonly<Record<string, string>>,
+): RequestInit {
+  const headers = new Headers(init?.headers);
+  for (const [name, value] of Object.entries(stableHeaders)) {
+    if (!headers.has(name)) headers.set(name, value);
+  }
+  if (!headers.has(XAI_GROK_COMPATIBILITY.headers.requestId)) {
+    headers.set(
+      XAI_GROK_COMPATIBILITY.headers.requestId,
+      pinnedRequestId,
+    );
+  }
+  return { ...init, headers };
+}
+
+function findHeaderCaseInsensitive(
+  headers: Record<string, string> | undefined,
+  name: string,
+): string | undefined {
+  const target = name.toLowerCase();
+  return Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === target)?.[1];
+}
+
+export function deriveXaiConvId(promptCacheKey: string): string {
+  return createHash("sha256").update(promptCacheKey).digest("hex").slice(0, 32);
+}
+
+/**
+ * Resolve xAI's runtime transport without mutating persisted config. Conversation/session
+ * affinity is stable for this resolved transport; request identity is pinned per resolved
+ * transport (= per logical request until key rotation), so same-target replays and transient
+ * retries carry the same id while a rotated key gets a fresh one.
+ * Agent, deployment, model-override, turn, mode, and user identity headers are intentionally
+ * omitted because opencodex has no truthful values for the official fields.
+ */
+export function resolveProviderTransport(
+  providerName: string,
+  provider: OcxProviderTransport,
+  promptCacheKey?: string,
+  apiBaseUrl?: string,
+): OcxProviderTransport {
+  if (providerName === "github-copilot") {
+    return resolveGithubCopilotTransport(provider, apiBaseUrl);
+  }
+  if (providerName !== "xai") return provider;
+
+  const cacheKey = promptCacheKey?.trim();
+  const affinity = cacheKey ? deriveXaiConvId(cacheKey) : undefined;
+  const stableDefaults: Record<string, string> = {
+    [XAI_GROK_COMPATIBILITY.headers.userAgent]: XAI_GROK_COMPATIBILITY.userAgent,
+    ...(affinity
+      ? {
+          [XAI_GROK_COMPATIBILITY.headers.conversationId]: affinity,
+          [XAI_GROK_COMPATIBILITY.headers.sessionId]: affinity,
+        }
+      : {}),
+    ...(provider.authMode === "oauth" ? XAI_GROK_CLI_HEADERS : {}),
+  };
+  const stableHeaders = {
+    ...withoutUserOverridden(stableDefaults, provider.headers),
+    ...(provider.headers ?? {}),
+  };
+  // Keep API-key provider metadata compatible with key-pool rotation; session/UA defaults
+  // remain transport-scoped and are applied by the wrapper immediately below.
+  const headers = provider.authMode === "oauth"
+    ? stableHeaders
+    : {
+        ...(affinity && !hasHeaderCaseInsensitive(provider.headers, XAI_GROK_COMPATIBILITY.headers.conversationId)
+          ? { [XAI_GROK_COMPATIBILITY.headers.conversationId]: affinity }
+          : {}),
+        ...(provider.headers ?? {}),
+      };
+  const configuredRequestId = findHeaderCaseInsensitive(
+    provider.headers,
+    XAI_GROK_COMPATIBILITY.headers.requestId,
+  );
+  // Pin the request id per resolved transport (= per logical request until key rotation):
+  // same-target 429 replays must carry the SAME x-grok-req-id as the original dispatch, and
+  // transient retries reuse one id so the upstream can dedupe them. A rotated key resolves a
+  // fresh transport, which gets its own id.
+  const requestId = configuredRequestId ?? randomUUID();
+  const baseFetch = provider.fetch ?? globalThis.fetch;
+  const attemptFetch = ((input, init) =>
+    baseFetch(input, withGeneratedRequestId(init, requestId, stableHeaders))) as typeof globalThis.fetch;
+
+  return {
+    ...provider,
+    ...(provider.authMode === "oauth" ? { baseUrl: XAI_GROK_CLI_BASE_URL } : {}),
+    headers,
+    fetch: attemptFetch,
+  };
+}