@bitkyc08/opencodex 2.27.0 → 2.28.0

package/src/providers/fastwire.ts

@@ -7,7 +7,7 @@ import type {
 } from "../types";
 import { MODEL_ADAPTER_OVERRIDE_ALLOWED } from "../types";
 import { sanitizeLogMetadataString } from "../lib/redact";
-import type { InboundWire, ModelWireDefault } from "./registry";
+import type { InboundWire, ModelWireDefault, ProviderAuthKind } from "./registry";
 
 const SERVICE_TIER_ADAPTERS = new Set(["openai-chat", "openai-responses"]);
 const FAST_WIRE_ADAPTERS: Readonly<Record<FastWire["kind"], ReadonlySet<string>>> = {
@@ -31,6 +31,7 @@ export type FastPolicyAuthTransport =
 
 export interface FastPolicyAuthority {
   readonly providerAdapter: string;
+  readonly providerAuthMode?: ProviderAuthKind;
   readonly fastWireDeclaration: FastWire | null | undefined;
   readonly modelWireOverrideAllowed: boolean;
   readonly authTransport: FastPolicyAuthTransport;
@@ -114,21 +115,33 @@ function registryDefaultForModel(
   defaults: Readonly<Record<string, ModelWireDefault>>,
   modelId: string,
   inbound: InboundWire,
-): string | undefined {
+  authMode: ProviderAuthKind | undefined,
+): { adapter: string; forwardCallerServiceTier?: boolean } | undefined {
   const normalizedModelId = modelId.trim().toLowerCase();
   if (!Object.hasOwn(defaults, normalizedModelId)) return undefined;
   const declared = defaults[normalizedModelId];
   if (declared === undefined) return undefined;
-  if (typeof declared !== "string" && !declared.inbound.includes(inbound)) return undefined;
+  if (typeof declared !== "string") {
+    if (!declared.inbound.includes(inbound)) return undefined;
+    if (declared.authModes && (authMode === undefined || !declared.authModes.includes(authMode))) {
+      return undefined;
+    }
+  }
   const wire = typeof declared === "string" ? declared : declared.wire;
-  return MODEL_ADAPTER_OVERRIDE_ALLOWED.has(wire) ? wire : undefined;
+  if (!MODEL_ADAPTER_OVERRIDE_ALLOWED.has(wire)) return undefined;
+  return {
+    adapter: wire,
+    ...(typeof declared !== "string" && declared.forwardCallerServiceTier !== undefined
+      ? { forwardCallerServiceTier: declared.forwardCallerServiceTier }
+      : {}),
+  };
 }
 
 function resolvePolicyAdapter(
   authority: FastPolicyAuthority,
   modelId: string,
   inbound: InboundWire,
-): { adapter: string; hardPinned: boolean } {
+): { adapter: string; hardPinned: boolean; forwardCallerServiceTier?: boolean } {
   // Hard pins and configured overrides deliberately use the same exact-key semantics as
   // resolveWireProtocolOverride(). Registry defaults alone normalize ids at their boundary.
   const hardPin = Object.hasOwn(authority.hardPins, modelId)
@@ -143,8 +156,21 @@ function resolvePolicyAdapter(
       return { adapter: configured, hardPinned: false };
     }
     if (MODEL_ADAPTER_OVERRIDE_ALLOWED.has(authority.providerAdapter)) {
-      const registryDefault = registryDefaultForModel(authority.registryWireDefaults, modelId, inbound);
-      if (registryDefault !== undefined) return { adapter: registryDefault, hardPinned: false };
+      const registryDefault = registryDefaultForModel(
+        authority.registryWireDefaults,
+        modelId,
+        inbound,
+        authority.providerAuthMode,
+      );
+      if (registryDefault !== undefined) {
+        return {
+          adapter: registryDefault.adapter,
+          hardPinned: false,
+          ...(registryDefault.forwardCallerServiceTier !== undefined
+            ? { forwardCallerServiceTier: registryDefault.forwardCallerServiceTier }
+            : {}),
+        };
+      }
     }
   }
   return { adapter: authority.providerAdapter, hardPinned: false };
@@ -155,7 +181,11 @@ export function resolveFastPolicy(
   modelId: string,
   inbound: InboundWire = "responses",
 ): ResolvedFastPolicy {
-  const { adapter, hardPinned } = resolvePolicyAdapter(authority, modelId, inbound);
+  const { adapter, hardPinned, forwardCallerServiceTier } = resolvePolicyAdapter(
+    authority,
+    modelId,
+    inbound,
+  );
   const exactCapability = exactModelValue(authority.capability.models, modelId);
   const capability = authority.capability.provider === false
     ? false
@@ -173,6 +203,7 @@ export function resolveFastPolicy(
   // tier still needs the final wire's forwarding permission.
   const forwardCallerTier = capability !== false
     && callerWireAvailable
+    && forwardCallerServiceTier !== false
     && (adapter !== "openai-chat" || authority.capability.chatServiceTier === true);
 
   let eligibility: ResolvedFastPolicy["eligibility"];

package/src/providers/quota.ts

@@ -13,7 +13,7 @@ import { getAccountCredential, getAccountSet, getCredential } from "../oauth/sto
 import { antigravityUserAgent } from "../adapters/client-fingerprint";
 import { apiKeyPoolEntryId } from "./api-keys";
 import { XAI_GROK_CLIENT_VERSION, XAI_GROK_COMPATIBILITY } from "./xai-transport";
-import { getProviderRegistryEntry, providerCodexAccountMode } from "./registry";
+import { getProviderRegistryEntry, providerCodexAccountMode, registryEntryForProviderDestination } from "./registry";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "./openai-tiers";
 import {
@@ -2084,7 +2084,14 @@ async function maybeFetchProviderQuota(
       && isCanonicalCommandCodeBaseUrl(provider.baseUrl)) {
       return fetchCommandCodeQuota(name, provider);
     }
-    if ((provider.authMode ?? "key") === "key" && name === "opencode-go") {
+    // Identify OpenCode Go by where it routes, not by what the row is called. Multi-account
+    // setups keep the same destination under names like `opencode-go-2` (#1924), and those rows
+    // silently had no quota panel and no `ocx provider quota --json` report while the literal
+    // name was the gate. `registryEntryForProviderDestination` is the existing predicate for
+    // exactly this question: normalized endpoint + adapter + key auth, so a canonical URL behind
+    // a different adapter is still not OpenCode Go. The defensive URL check inside
+    // `fetchOpenCodeGoQuota` stays — sending a key anywhere must not depend on this gate.
+    if ((provider.authMode ?? "key") === "key" && registryEntryForProviderDestination(provider)?.id === "opencode-go") {
       return fetchOpenCodeGoQuota(name, provider);
     }
     if ((provider.authMode ?? "key") === "key" && isCanonicalA6apiBaseUrl(provider.baseUrl)) {

package/src/providers/registry.ts

@@ -31,9 +31,15 @@ export type InboundWire = "responses" | "chat" | "anthropic";
 
 /**
  * A per-model wire default: a bare string applies to every inbound, while the object
- * form applies only to the listed inbound protocols.
+ * form may scope the default to listed inbound protocols and authentication modes.
  */
-export type ModelWireDefault = string | { wire: string; inbound: readonly InboundWire[] };
+export type ModelWireDefault = string | {
+  wire: string;
+  inbound: readonly InboundWire[];
+  authModes?: readonly ProviderAuthKind[];
+  /** Whether this registry-selected route may relay a caller-owned service_tier. */
+  forwardCallerServiceTier?: boolean;
+};
 
 export interface ResponsesTerminalRepairPolicy {
   /** Quiet time after a structurally complete output graph before synthesizing completion. */
@@ -1017,6 +1023,24 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     // grok-4.5; the reasoning ladder does not — 4.6 adds the documented xhigh rung.
     models: ["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"],
     defaultModel: "grok-4.5",
+    // The current Grok CLI catalog declares both subscription models as native Responses
+    // backends. Keep API-key and translated Chat/Anthropic callers on their existing wire;
+    // Codex Responses traffic can relay xAI's SSE as it arrives instead of waiting for the
+    // Chat Completions compatibility stream to flush at the end of a reasoning turn.
+    modelWireDefaults: {
+      "grok-4.6": {
+        wire: "openai-responses",
+        inbound: ["responses"],
+        authModes: ["oauth"],
+        forwardCallerServiceTier: false,
+      },
+      "grok-4.5": {
+        wire: "openai-responses",
+        inbound: ["responses"],
+        authModes: ["oauth"],
+        forwardCallerServiceTier: false,
+      },
+    },
     // Vision lineup per docs.x.ai model-capabilities/images/understanding: the grok-4.x chat
     // models accept image input (JPEG/PNG, URL or base64). Without this the catalog leaves
     // inputModalities undefined, and deriveComboCatalogModel defaults an undefined member to
@@ -1083,6 +1107,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     adapter: "anthropic",
     baseUrl: "https://api.anthropic.com",
     authKind: "oauth",
+    allowBaseUrlOverride: true,
     featured: true,
     oauthId: "anthropic",
     jawcodeBundle: "anthropic",
@@ -1496,7 +1521,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
   // 2026-07-10: defaultModel is frozen pending Vertex-specific Tier-2 evidence; Gemini API
   // evidence from ai.google.dev does not establish Vertex publisher availability.
   { id: "google-vertex", label: "Google Vertex AI", adapter: "google", baseUrl: "https://aiplatform.googleapis.com", authKind: "key", dashboardUrl: "https://console.cloud.google.com/vertex-ai", defaultModel: "gemini-3-pro", googleMode: "vertex", jawcodeBundle: "google", extraMetadataAliases: ["gemini-vertex"] },
-  { id: "google-antigravity", label: "Google Antigravity", adapter: "google", baseUrl: "https://daily-cloudcode-pa.googleapis.com", authKind: "oauth", dashboardUrl: "https://antigravity.google", models: ANTIGRAVITY_MODELS, liveModels: true, defaultModel: "gemini-3.7-flash", modelContextWindows: ANTIGRAVITY_MODEL_CONTEXT_WINDOWS, modelInputModalities: ANTIGRAVITY_MODEL_INPUT_MODALITIES, modelReasoningEfforts: ANTIGRAVITY_MODEL_EFFORTS, googleMode: "cloud-code-assist", jawcodeBundle: "google", extraMetadataAliases: ["antigravity", "gemini-antigravity"] },
+  { id: "google-antigravity", label: "Google Antigravity", adapter: "google", baseUrl: "https://daily-cloudcode-pa.googleapis.com", authKind: "oauth", allowBaseUrlOverride: true, dashboardUrl: "https://antigravity.google", models: ANTIGRAVITY_MODELS, liveModels: true, defaultModel: "gemini-3.7-flash", modelContextWindows: ANTIGRAVITY_MODEL_CONTEXT_WINDOWS, modelInputModalities: ANTIGRAVITY_MODEL_INPUT_MODALITIES, modelReasoningEfforts: ANTIGRAVITY_MODEL_EFFORTS, googleMode: "cloud-code-assist", jawcodeBundle: "google", extraMetadataAliases: ["antigravity", "gemini-antigravity"] },
   { id: "azure-openai", label: "Azure OpenAI", adapter: "azure-openai", baseUrl: "https://{resource}.openai.azure.com/openai", authKind: "key", featured: true, dashboardUrl: "https://portal.azure.com" },
   { id: "ollama", label: "Ollama (local)", adapter: "openai-chat", baseUrl: "http://localhost:11434/v1", authKind: "local", allowPrivateNetworkByDefault: true, allowBaseUrlOverride: true, featured: true, note: "Local — key usually blank" },
   { id: "vllm", label: "vLLM (local)", adapter: "openai-chat", baseUrl: "http://localhost:8000/v1", authKind: "local", allowPrivateNetworkByDefault: true, allowBaseUrlOverride: true, featured: true, note: "Local — key usually blank" },
@@ -2435,6 +2460,16 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     note: "No key needed — public desktop tier. OpenCode currently advertises about 200 Big Pickle/free-model requests per 5 hours. The same Zen gateway can also short-window rate-limit free models at roughly 15-20 requests/minute, and may return generic 429s without Retry-After (opencodex synthesizes backoff only when that header is omitted). Free models are discovered live from Zen. Data use: per OpenCode's Zen docs (https://opencode.ai/docs/zen/), prompts sent to free models may be retained and used for training/improvement — do not send confidential material through this provider.",
     dashboardUrl: "https://opencode.ai",
     staticHeaders: {
+      // Zen answers a bare runtime User-Agent (Bun/x.y.z) more aggressively than a client
+      // that identifies itself, which is what the 429 in #2067 traced to. The value is
+      // deliberately unversioned: a pinned "opencode-cli/<version>" is a claim about an
+      // install we do not have and goes stale on the vendor's schedule, not ours.
+      // Corroboration, not authority: OmniRoute — an independent open-source broker against
+      // the same Zen upstream — defaults to exactly this pair (userAgent "opencode", client
+      // "desktop") in open-sse/executors/opencode.ts, and got there by RETREATING from its
+      // own earlier "opencode-cli/1.0.0" pin. An operator can still override either value
+      // through the provider headers API; user headers win case-insensitively at route time.
+      "User-Agent": "opencode",
       "x-opencode-client": "desktop",
     },
     modelReasoningEfforts: Object.fromEntries(OPENCODE_FREE_DEEPSEEK_MODELS.map(id => [id, deepseekThinkingEffortsFor(id)])),
@@ -2591,6 +2626,36 @@ export function getProviderRegistryEntry(id: string): ProviderRegistryEntry | un
   return PROVIDER_REGISTRY.find(entry => entry.id === id);
 }
 
+/**
+ * Merge a registry row's `staticHeaders` beneath a provider's own headers.
+ *
+ * The field is documented as "merged into every upstream request for this provider", but that
+ * was only ever true for a freshly seeded config: `providerConfigSeed` copies the block once
+ * (`derive.ts`), `enrichProviderFromCatalog` fills it only when the whole block is absent, and
+ * nothing merged it at request time. So an install that predates a header — or that saved any
+ * header of its own — never received the new one, which is exactly what #2067 would have
+ * shipped for every existing opencode-free user.
+ *
+ * The comparison is case-insensitive on purpose. HTTP header names are case-insensitive, but a
+ * plain object spread is not: merging a registry `User-Agent` over a user's `user-agent`
+ * produces two entries that `Headers` serializes as one comma-joined value
+ * ("opencode, custom-agent"), which is a corrupted request rather than an override. The user's
+ * spelling and value both win; the registry only fills names the user has not spoken for.
+ */
+export function mergeRegistryStaticHeaders(
+  staticHeaders: Record<string, string> | undefined,
+  userHeaders: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!staticHeaders) return userHeaders;
+  if (!userHeaders) return { ...staticHeaders };
+  const claimed = new Set(Object.keys(userHeaders).map(name => name.toLowerCase()));
+  const merged: Record<string, string> = { ...userHeaders };
+  for (const [name, value] of Object.entries(staticHeaders)) {
+    if (!claimed.has(name.toLowerCase())) merged[name] = value;
+  }
+  return merged;
+}
+
 /** Whether this registry row's per-model service-tier evidence applies to one configured target. */
 export function registryModelServiceTierCapabilityApplies(
   entry: Pick<ProviderRegistryEntry, "modelServiceTierCapabilityBaseUrlGuard">,
@@ -2679,8 +2744,12 @@ export function providerModelWireDefault(
   if (!entry?.modelWireDefaults || !providerMatchesRegistryTransport(id, provider)) return undefined;
   const declared = entry.modelWireDefaults[modelId.trim().toLowerCase()];
   if (declared === undefined) return undefined;
-  // A bare string applies to every inbound; the object form only to the listed ones.
-  if (typeof declared !== "string" && !declared.inbound.includes(inbound)) return undefined;
+  // A bare string applies to every inbound/auth mode; the object form may narrow either.
+  if (typeof declared !== "string") {
+    if (!declared.inbound.includes(inbound)) return undefined;
+    const authMode = provider.authMode ?? entry.authKind;
+    if (declared.authModes && !declared.authModes.includes(authMode)) return undefined;
+  }
   const wire = typeof declared === "string" ? declared : declared.wire;
   return wire !== undefined && allowedWires.has(wire) ? wire : undefined;
 }

package/src/providers/service-tier.ts

@@ -45,7 +45,16 @@ function cloneRegistryWireDefaults(
   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]) });
+      : 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);
 }
@@ -68,6 +77,7 @@ function buildFastPolicyAuthority(
   const providerCapability = capabilityProvider.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 },
@@ -241,13 +251,11 @@ export function serviceTierSupportFromPolicy(
 ): boolean | undefined {
   if (policy.eligibility === "eligible") return true;
   if (policy.eligibility === "unclassified") {
-    // B1 regression guard: an unclassified chat-wire route whose final adapter will not
-    // forward any tier cannot serialize service_tier, so projecting "unknown" would let
-    // require.serviceTier: "unsupported" routing stop matching groq/ollama-class providers
-    // that main projected as false. Chat + no forwarding stays a definitive false; a
-    // chat route with chatServiceTier: true (forwarding allowed) keeps the historical
-    // unknown, as does every unclassified Responses-wire route.
-    if (policy.adapter === "openai-chat" && !policy.forwardCallerTier) return false;
+    // 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/responses/parser.ts

@@ -20,6 +20,7 @@ import { previousResponseReplayPrefixLength } from "./state";
 import { decodeReasoningEnvelope } from "./reasoning-envelope";
 import { extractHostedWebSearch, WEB_SEARCH_TOOL_NAME } from "../web-search/synthetic-tool";
 import { extractHostedImageGeneration, IMAGE_GEN_TOOL_NAME } from "../images/synthetic-tool";
+import { toolSearchDescription, toolSearchParameters } from "./tool-search-compat";
 
 function isObj(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -214,15 +215,8 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
       // Expose as a function so chat models can call it; the bridge relays it as a tool_search_call.
       out.push({
         name: "tool_search",
-        description: (t.description as string) ?? "Search for additional tools to load for the next turn.",
-        parameters: (isObj(t.parameters) ? t.parameters : {
-          type: "object",
-          properties: {
-            query: { type: "string", description: "Search query for tools to load." },
-            limit: { type: "number", description: "Maximum number of tools to return." },
-          },
-          required: ["query"],
-        }) as Record<string, unknown>,
+        description: toolSearchDescription(t),
+        parameters: normalizeParameters(toolSearchParameters(t)),
         toolSearch: true,
       });
     }

package/src/responses/tool-search-compat.ts

@@ -0,0 +1,301 @@
+export const TOOL_SEARCH_FUNCTION_NAME = "tool_search";
+export const TOOL_SEARCH_DEFAULT_DESCRIPTION = "Search for additional tools to load for the next turn.";
+const TOOL_SEARCH_WIRE_ALIAS_PREFIX = "opencodex_tool_search";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function toolSearchDescription(tool: unknown): string {
+  return isPlainObject(tool) && typeof tool.description === "string"
+    ? tool.description
+    : TOOL_SEARCH_DEFAULT_DESCRIPTION;
+}
+
+export function toolSearchParameters(tool: unknown): Record<string, unknown> {
+  if (isPlainObject(tool) && isPlainObject(tool.parameters)) return tool.parameters;
+  // Fresh per parse/build: downstream normalizers are allowed to clone or extend schemas, and a
+  // shared mutable default would couple otherwise unrelated requests.
+  return {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query for tools to load." },
+      limit: { type: "number", description: "Maximum number of tools to return." },
+    },
+    required: ["query"],
+  };
+}
+
+function collectToolDeclarationNames(tools: unknown[], names: Set<string>, namespace?: string): void {
+  for (const tool of tools) {
+    if (!isPlainObject(tool) || tool.type === "tool_search") continue;
+    if (tool.type === "function" && isPlainObject(tool.function) && typeof tool.function.name === "string") {
+      names.add(tool.function.name);
+    }
+    if (typeof tool.name === "string") {
+      names.add(tool.name);
+      if (namespace) names.add(`${namespace}__${tool.name}`);
+    }
+    if (tool.type === "namespace" && Array.isArray(tool.tools)) {
+      collectToolDeclarationNames(tool.tools, names, typeof tool.name === "string" ? tool.name : undefined);
+    }
+  }
+}
+
+function declaredToolNames(body: Record<string, unknown>): Set<string> {
+  const names = new Set<string>();
+  if (Array.isArray(body.tools)) collectToolDeclarationNames(body.tools, names);
+  if (Array.isArray(body.input)) {
+    for (const item of body.input) {
+      if (isPlainObject(item) && item.type === "additional_tools" && Array.isArray(item.tools)) {
+        collectToolDeclarationNames(item.tools, names);
+      }
+    }
+  }
+  return names;
+}
+
+function hasToolSearchDeclaration(tools: unknown[]): boolean {
+  return tools.some(tool => isPlainObject(tool) && tool.type === "tool_search");
+}
+
+function chooseToolSearchWireName(usedNames: ReadonlySet<string>): string {
+  if (!usedNames.has(TOOL_SEARCH_FUNCTION_NAME)) return TOOL_SEARCH_FUNCTION_NAME;
+  if (!usedNames.has(TOOL_SEARCH_WIRE_ALIAS_PREFIX)) return TOOL_SEARCH_WIRE_ALIAS_PREFIX;
+  for (let suffix = 2; ; suffix++) {
+    const candidate = `${TOOL_SEARCH_WIRE_ALIAS_PREFIX}_${suffix}`;
+    if (!usedNames.has(candidate)) return candidate;
+  }
+}
+
+function rewriteToolList(tools: unknown[], wireName: string): { tools: unknown[]; changed: boolean } {
+  let changed = false;
+  const rewritten = tools.map(tool => {
+    if (!isPlainObject(tool) || tool.type !== "tool_search") return tool;
+    const {
+      execution: _execution,
+      defer_loading: _deferLoading,
+      ...rest
+    } = tool;
+    changed = true;
+    return {
+      ...rest,
+      type: "function",
+      name: wireName,
+      description: toolSearchDescription(tool),
+      parameters: toolSearchParameters(tool),
+    };
+  });
+  return changed ? { tools: rewritten, changed: true } : { tools, changed: false };
+}
+
+function rewriteToolChoice(choice: unknown, wireName: string): unknown {
+  if (!isPlainObject(choice)) return choice;
+  if (choice.type === "tool_search") {
+    return { type: "function", name: wireName };
+  }
+  if (choice.type !== "allowed_tools" || !Array.isArray(choice.tools)) return choice;
+  let changed = false;
+  const tools = choice.tools.map(tool => {
+    if (!isPlainObject(tool) || tool.type !== "tool_search") return tool;
+    changed = true;
+    return { type: "function", name: wireName };
+  });
+  return changed ? { ...choice, tools } : choice;
+}
+
+function toolChoiceAllowsPrivateSearch(choice: unknown): boolean {
+  if (choice === undefined || choice === null || choice === "auto" || choice === "required") return true;
+  if (choice === "none") return false;
+  if (!isPlainObject(choice)) return true;
+  if (choice.type === "tool_search") return true;
+  if (choice.type === "allowed_tools" && Array.isArray(choice.tools)) {
+    return choice.tools.some(tool => isPlainObject(tool) && tool.type === "tool_search");
+  }
+  // A forced ordinary function named `tool_search` is distinct from the private tool kind.
+  return false;
+}
+
+function upstreamToolSearchItemId(id: unknown): unknown {
+  if (typeof id !== "string") return id;
+  return id.startsWith("tsc_") ? `fc_${id.slice(4)}` : id;
+}
+
+function toolSearchArgumentsText(value: unknown): string {
+  if (typeof value === "string") return value;
+  return JSON.stringify(isPlainObject(value) ? value : {});
+}
+
+function toolSearchOutputText(value: Record<string, unknown>): string {
+  const payload: Record<string, unknown> = {
+    tools: Array.isArray(value.tools) ? value.tools : [],
+  };
+  if (typeof value.status === "string") payload.status = value.status;
+  return JSON.stringify(payload);
+}
+
+function rewriteHistoryItem(item: Record<string, unknown>, wireName: string): Record<string, unknown> {
+  if (item.type === "tool_search_call") {
+    const {
+      execution: _execution,
+      arguments: argumentsValue,
+      id,
+      ...rest
+    } = item;
+    return {
+      ...rest,
+      type: "function_call",
+      ...(id === undefined ? {} : { id: upstreamToolSearchItemId(id) }),
+      name: wireName,
+      arguments: toolSearchArgumentsText(argumentsValue),
+    };
+  }
+  if (item.type === "tool_search_output") {
+    const {
+      execution: _execution,
+      id: _id,
+      tools: _tools,
+      status: _status,
+      ...rest
+    } = item;
+    return {
+      ...rest,
+      type: "function_call_output",
+      output: toolSearchOutputText(item),
+    };
+  }
+  return item;
+}
+
+/**
+ * Third-party Responses gateways generally implement the public function-tool schema, not Codex's
+ * private client-executed `tool_search` declaration. Lower only request catalogs sent to a
+ * noncanonical upstream; the caller-facing response is restored separately.
+ */
+export function rewriteRoutedToolSearchForUpstream(body: unknown): {
+  body: unknown;
+  names: Set<string>;
+} {
+  const names = new Set<string>();
+  if (!isPlainObject(body)) return { body, names };
+
+  const topLevelSearch = Array.isArray(body.tools) && hasToolSearchDeclaration(body.tools);
+  const inputItems = Array.isArray(body.input) ? body.input : [];
+  const additionalSearch = inputItems.some(item =>
+    isPlainObject(item)
+    && item.type === "additional_tools"
+    && Array.isArray(item.tools)
+    && hasToolSearchDeclaration(item.tools));
+  const historySearch = inputItems.some(item =>
+    isPlainObject(item)
+    && (item.type === "tool_search_call" || item.type === "tool_search_output"));
+  if (!topLevelSearch && !additionalSearch && !historySearch) return { body, names };
+
+  const wireName = chooseToolSearchWireName(declaredToolNames(body));
+  const declarationChanged = topLevelSearch || additionalSearch;
+
+  let tools = body.tools;
+  if (Array.isArray(tools)) {
+    const result = rewriteToolList(tools, wireName);
+    tools = result.tools;
+  }
+
+  let input = body.input;
+  let historyLowered = false;
+  if (Array.isArray(input)) {
+    input = input.map(item => {
+      if (!isPlainObject(item)) return item;
+      if (item.type === "additional_tools" && Array.isArray(item.tools)) {
+        const result = rewriteToolList(item.tools, wireName);
+        return result.changed ? { ...item, tools: result.tools } : item;
+      }
+      const rewritten = rewriteHistoryItem(item, wireName);
+      if (rewritten !== item) historyLowered = true;
+      return rewritten;
+    });
+  }
+
+  // A turn can replay `tool_search_call` history WITHOUT re-declaring the tool — Codex normally
+  // sends the declaration, but a history-only body is legal. The history is lowered to
+  // `function_call` either way, so restoration has to be armed on that too: leaving `names`
+  // empty there would hand the client a public `function_call` for what it issued as a private
+  // search call, and the round trip would silently stop matching.
+  if ((declarationChanged || historyLowered) && toolChoiceAllowsPrivateSearch(body.tool_choice)) {
+    names.add(wireName);
+  }
+  const toolChoice = declarationChanged ? rewriteToolChoice(body.tool_choice, wireName) : body.tool_choice;
+  return {
+    body: {
+      ...body,
+      ...(tools !== body.tools ? { tools } : {}),
+      ...(input !== body.input ? { input } : {}),
+      ...(toolChoice !== body.tool_choice ? { tool_choice: toolChoice } : {}),
+    },
+    names,
+  };
+}
+
+export function toolSearchItemId(id: unknown): unknown {
+  if (typeof id !== "string") return id;
+  return id.startsWith("fc_") ? `tsc_${id.slice(3)}` : id;
+}
+
+function toolSearchArguments(value: unknown): Record<string, unknown> {
+  if (isPlainObject(value)) return value;
+  if (typeof value !== "string" || value.length === 0) return {};
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return isPlainObject(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function restoreRoutedToolSearchCalls(
+  value: unknown,
+  names: ReadonlySet<string>,
+): { value: unknown; changed: boolean } {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const restored = value.map(entry => {
+      const result = restoreRoutedToolSearchCalls(entry, names);
+      changed ||= result.changed;
+      return result.value;
+    });
+    return changed ? { value: restored, changed: true } : { value, changed: false };
+  }
+  if (!isPlainObject(value)) return { value, changed: false };
+
+  let changed = false;
+  const restored: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const result = restoreRoutedToolSearchCalls(entry, names);
+    restored[key] = result.value;
+    changed ||= result.changed;
+  }
+
+  if (value.type === "function_call" && typeof value.name === "string" && names.has(value.name)) {
+    restored.type = "tool_search_call";
+    restored.id = toolSearchItemId(value.id);
+    restored.execution = "client";
+    restored.arguments = toolSearchArguments(value.arguments);
+    delete restored.name;
+    changed = true;
+  }
+  return changed ? { value: restored, changed: true } : { value, changed: false };
+}
+
+export function restoreRoutedToolSearchCallsInJson(
+  text: string,
+  names: ReadonlySet<string>,
+): string {
+  if (names.size === 0) return text;
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const restored = restoreRoutedToolSearchCalls(payload, names);
+  return restored.changed ? JSON.stringify(restored.value) : text;
+}

package/src/router.ts

@@ -14,6 +14,7 @@ import { assertProviderDestinationAllowed } from "./lib/destination-policy";
 import { redactSecretString, redactUrlForLog } from "./lib/redact";
 import {
   PROVIDER_REGISTRY,
+  mergeRegistryStaticHeaders,
   providerCodexAccountMode,
   registryModelServiceTierCapabilityApplies,
 } from "./providers/registry";
@@ -296,6 +297,11 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ? mergePositiveNumberCaps(registryEntry.modelContextWindows, provider.modelContextWindows)
     : mergeRecordFill(registryEntry.modelContextWindows, provider.modelContextWindows);
   const modelInputModalities = mergeRecordFill(registryEntry.modelInputModalities, provider.modelInputModalities);
+  // Registry static headers are documented as applying to every upstream request, so they are
+  // filled at resolve time rather than only at seed time: a config written before a header
+  // existed, or one carrying any header of its own, would otherwise never receive it. User
+  // headers win, matched case-insensitively so an override replaces rather than duplicates.
+  const headers = mergeRegistryStaticHeaders(registryEntry.staticHeaders, provider.headers);
   const modelMaxInputTokens = providerName === OPENAI_API_PROVIDER_ID
     ? mergePositiveNumberCaps(registryEntry.modelMaxInputTokens, provider.modelMaxInputTokens)
     : mergeRecordFill(registryEntry.modelMaxInputTokens, provider.modelMaxInputTokens);
@@ -372,6 +378,7 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     authMode: canonicalAuthMode,
     apiKey: resolvedApiKey,
     ...(staticModelCatalog ? { liveModels: false } : {}),
+    ...(headers ? { headers } : {}),
     // Backfill the Google wire mode + Vertex project/location from the registry when the user
     // config omits them, so a minimal `google-vertex`/`google-antigravity` entry still routes
     // through the correct branch (CCA/Vertex) instead of falling back to AI Studio.