@bitkyc08/opencodex 2.41.0 → 2.43.0-preview.20260906

package/src/adapters/kiro.ts

@@ -5,6 +5,7 @@ import { resolveKiroApiRegion, resolveKiroRequestProfile } from "../oauth/kiro";
 import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/kiro-models";
 import { modelRecordValue } from "../reasoning-effort";
 import { parseKiroEvent } from "./kiro-events";
+import { calibrateKiroEstimate, recordKiroCalibration, rekeyKiroCalibration } from "./kiro-calibration";
 import {
   classifyKiroEventError,
   classifyKiroHttpError,
@@ -186,6 +187,85 @@ function estimateKiroTokens(text: string, modelId?: string): number {
   return estimateTokens(text, modelId ? `kiro/${modelId}` : "kiro");
 }
 
+/** Hangul/Han/kana ranges, matching the shared estimator's own CJK classification. */
+function kiroCjkCount(text: string): number {
+  let cjk = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (
+      (c >= 0xac00 && c <= 0xd7a3) || (c >= 0x1100 && c <= 0x11ff) || (c >= 0x3130 && c <= 0x318f)
+      || (c >= 0x4e00 && c <= 0x9fff) || (c >= 0x3400 && c <= 0x4dbf) || (c >= 0x3040 && c <= 0x30ff)
+    ) cjk++;
+  }
+  return cjk;
+}
+
+/**
+ * Token estimate for walked payload text, with the wire expansion applied to the Latin portion
+ * only. Splitting here rather than inside the shared estimator keeps that module pure and
+ * provider-neutral: the expansion is a fact about Kiro's wire, not about tokenization.
+ */
+function estimateKiroWireTokens(text: string, modelId: string): number {
+  if (!text) return 0;
+  const cjk = kiroCjkCount(text);
+  if (cjk === 0) return Math.ceil(estimateKiroTokens(text, modelId) * KIRO_LATIN_WIRE_EXPANSION);
+  const latinTokens = estimateKiroTokens("x".repeat(text.length - cjk), modelId);
+  const cjkTokens = estimateKiroTokens("\uac00".repeat(cjk), modelId);
+  return Math.ceil(latinTokens * KIRO_LATIN_WIRE_EXPANSION + cjkTokens);
+}
+
+/**
+ * Structural cost of one conversation entry, in tokens.
+ *
+ * The walker below concatenates message TEXT, but the wire carries JSON: per-entry keys
+ * (`userInputMessage`, `content`, `modelId`, `origin`) and role framing. That is charged
+ * upstream and is invisible to a text-only count, so without it a long conversation drifts
+ * further below the real charge with every turn added — an error proportional to entry COUNT,
+ * which no per-character ratio can recover.
+ *
+ * Regressing serialized bodies against what the walker counts, over eleven payload sizes from
+ * 3 to 701 entries:
+ *
+ *     bodyBytes = 1.0422 * walkedChars + 66.7 * entries + 68
+ *
+ * 66.7 bytes at the measured 2.433 bytes per charged token is 27.4 tokens per entry. The
+ * earlier value of 12 was a conservative hand-fit taken before that regression existed, and
+ * being less than half the real cost is precisely why the estimate decayed with conversation
+ * length: an under-charge of ~15 tokens per entry is invisible across four messages and
+ * dominant across seven hundred.
+ *
+ * Cross-checked against 4,090 recorded requests, where real traffic averages 1,310 bytes per
+ * message: 66.7 bytes is 5% of that, so this term charges framing and is not quietly absorbing
+ * message content.
+ */
+const KIRO_ENTRY_FRAMING_TOKENS = 27;
+
+/**
+ * Multiplier reconciling the LATIN text estimate with what the wire charges for that same text.
+ *
+ * The shared estimator counts Latin text at 2.8 chars/token, while the wire charges 2.433 bytes
+ * per token at 1.0422 bytes per walked character — an effective 2.334 chars/token, and
+ * 2.8 / 2.334 = 1.199.
+ *
+ * The evidence that the split between this term and `KIRO_ENTRY_FRAMING_TOKENS` is right is its
+ * stability: holding framing at 27, the multiplier the charge implies stays within 1.189-1.209
+ * across a 230x range of conversation sizes. A mis-specified split drifts with size, and the
+ * earlier 1.12/12 pair did — its accuracy fell from 0.92 at four messages to 0.87 at seven
+ * hundred.
+ *
+ * LATIN ONLY, deliberately. 2.433 bytes/token is a property of this traffic mix, which is Latin
+ * and code. A Hangul character is three UTF-8 bytes but roughly one token, so its bytes-per-token
+ * is entirely different and a Latin-derived byte rate says nothing about it. Scaling CJK by this
+ * factor bills Hangul at 1.25 chars/token, against recorded ground truth that already places the
+ * shared 1.5 ratio at 0.90 of the authoritative count — an over-charge that would compact Korean
+ * threads early.
+ *
+ * This is NOT JSON escaping, despite what an earlier version of this comment claimed. Measured
+ * directly, `JSON.stringify` expands prose by 1.012 (Latin) to 1.019 (Korean), nowhere near 1.2.
+ * Escaping is real but small, and is already inside the byte measurement this factor comes from.
+ */
+const KIRO_LATIN_WIRE_EXPANSION = 1.2;
+
 function estimateKiroPayloadInputTokens(payload: Record<string, unknown>, modelId: string): number {
   const conversationState = (payload as {
     conversationState?: {
@@ -216,7 +296,9 @@ function estimateKiroPayloadInputTokens(payload: Record<string, unknown>, modelI
       if (assistant.toolUses?.length) parts.push(serializeForUsage(assistant.toolUses));
     }
   }
-  return estimateKiroTokens(parts.join("\n"), modelId) + imageTokens;
+  return estimateKiroWireTokens(parts.join("\n"), modelId)
+    + imageTokens
+    + entries.length * KIRO_ENTRY_FRAMING_TOKENS;
 }
 
 function shouldCountStablePromptOverhead(parsed: OcxParsedRequest): boolean {
@@ -990,6 +1072,11 @@ async function* parseKiroAttempt(
   // the attempt boundary. Anything the inner parser leaves behind is flushed before the terminal.
   const deferred: AdapterEvent[] = [];
   const retention = createKiroAttemptRetention(budget);
+  // Shared box: the inner parser stages its calibration observation here on the completion path,
+  // and this wrapper decides whether the attempt was terminal enough to commit it. A box rather
+  // than a return field because the completion path has a dozen terminal returns and threading a
+  // field through every one of them is exactly the kind of edit that misses one.
+  const attemptCalibration: { value?: { conversationId: string; estimated: number; charged: number } } = {};
   const attempt = parseKiroAttemptEvents(
     response,
     budget,
@@ -1001,12 +1088,22 @@ async function* parseKiroAttempt(
     conversationId,
     deferred,
     retention,
+    attemptCalibration,
     contextInputEstimate,
     priorEmittedOutput,
   );
   let handedOff = false;
   try {
     const result = yield* attempt;
+    // A staged observation only counts when this attempt is the LAST one for the user turn. An
+    // attempt that asks for the bounded fallback streams again against a rebuilt payload, so
+    // committing here would move the factor twice for one turn and score the second observation
+    // against a payload the first had already inflated.
+    const staged = attemptCalibration.value;
+    attemptCalibration.value = undefined;
+    if (staged && !result.needsFallback) {
+      recordKiroCalibration(staged.conversationId, staged.estimated, staged.charged);
+    }
     for (const event of deferred.splice(0)) {
       try { yield event; } finally { retention.releaseEvent(event); }
     }
@@ -1028,10 +1125,13 @@ async function* parseKiroAttemptEvents(
   conversationId: string | undefined,
   deferred: AdapterEvent[],
   retention: KiroAttemptRetention,
+  attemptCalibration: { value?: { conversationId: string; estimated: number; charged: number } },
   contextInputEstimate?: number,
   priorEmittedOutput = false,
 ): AsyncGenerator<AdapterEvent, KiroAttemptParseResult> {
   const emptyResult = (): KiroAttemptParseResult => ({ assistantText: "", sawReasoning: false });
+  // Every early return below is a failure path that stages nothing; only the completion path
+  // writes `attemptCalibration`, and the wrapper decides whether to commit it.
   if (!response.body) {
     return {
       ...emptyResult(),
@@ -1346,7 +1446,13 @@ async function* parseKiroAttemptEvents(
           if (ev.stopReason !== undefined) stopReason = ev.stopReason;
           break;
         case "message_metadata":
-          if (isValidKiroConversationId(ev.conversationId)) returnedConversationId = ev.conversationId;
+          if (isValidKiroConversationId(ev.conversationId)) {
+            // Kiro can answer under a different conversation id than the request was built with.
+            // Carry the calibration entry across so the record below finds its own raw estimate
+            // instead of silently falling back to the already-corrected value.
+            rekeyKiroCalibration(returnedConversationId, ev.conversationId);
+            returnedConversationId = ev.conversationId;
+          }
           break;
         case "content":
           if (ev.modelId) {
@@ -1475,6 +1581,29 @@ async function* parseKiroAttemptEvents(
         ...(contextWindowState.value ? { upstreamContextWindow: contextWindowState.value } : {}),
       });
     }
+    // Upstream just told us what this payload cost. The ratio between that and our pre-request
+    // estimate is this conversation's own measured error, and it is the only feedback the
+    // estimator ever receives.
+    //
+    // Staged, not recorded. An attempt that sets `needsFallback` is not over: the adapter rebuilds
+    // the payload and streams a second time for the SAME user turn. Learning here would apply the
+    // fresh factor to that rebuild and then learn again from it, so one turn would move the factor
+    // twice and the second observation would score a payload the first had already inflated. Only
+    // the outer parser knows whether an attempt is terminal, so it commits.
+    //
+    // Subtract the output first. `contextUsageTotalFloor` is the absolute context size AFTER the
+    // response (`OcxUsage.contextTotalTokens`, types/request.ts), while `contextInputEstimate`
+    // covers the request payload alone. Dividing one by the other would charge generated tokens to
+    // prompt-tokenization error, so a short prompt answered at length would learn a large factor
+    // and inflate every later request in that conversation — the premature compaction this work
+    // exists to prevent.
+    const chargedTotal = contextUsageTotalFloor();
+    if (chargedTotal !== undefined && contextInputEstimate !== undefined) {
+      const chargedInput = chargedTotal - finalUsage.outputTokens;
+      if (chargedInput > 0 && returnedConversationId) {
+        attemptCalibration.value = { conversationId: returnedConversationId, estimated: contextInputEstimate, charged: chargedInput };
+      }
+    }
     // Native stop metadata proves that this inference ended, but it does not prove that ordinary
     // text is a final answer. Kiro has emitted END_TURN for progress prose, so tool-enabled turns
     // still require the private completion call to distinguish commentary from completion (#531).
@@ -1934,7 +2063,10 @@ export function createKiroAdapter(provider: OcxProviderConfig): ProviderAdapter
     if (profileArn) headers["x-amzn-kiro-profile-arn"] = profileArn;
     const built = buildKiroPayload(parsed, profileArn, forcedCompletionMode, wireClient);
     await normalizeKiroImages(built.payload);
-    const contextInputEstimate = estimateKiroPayloadInputTokens(built.payload, parsed.modelId);
+    // Apply what earlier turns of THIS conversation measured. An unseen conversation is
+    // unchanged, so a first turn behaves exactly as it would without calibration.
+    const rawContextInputEstimate = estimateKiroPayloadInputTokens(built.payload, parsed.modelId);
+    const contextInputEstimate = calibrateKiroEstimate(built.conversationId, rawContextInputEstimate);
     const body = JSON.stringify(built.payload);
     debugProviderDiagnostic("kiro", "request", {
       region,

package/src/adapters/openai-responses.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import type { IncomingMeta, ProviderAdapter } from "./base";
 import { namespacedToolName, type AdapterEvent, type OcxParsedRequest, type OcxProviderConfig, type OcxUsage, type TierDecision } from "../types";
 import { catalogModelSupportsReasoningSummaries } from "../codex/catalog";
+import { applyCodexRoutingHint, CODEX_RESPONSES_LITE_HEADER, CODEX_ROUTING_HINT_HEADER } from "../codex/forward-transport-headers";
 import { COMPACT_PROMPT, compactionItemToText, decodeCompactionSummary, isCompactionItemType } from "../responses/compaction";
 import { collectResponsesToolGroups } from "../responses/tool-groups";
 import { isHostedToolUnsupportedForModel } from "../responses/hosted-tool-policy";
@@ -20,6 +21,7 @@ import { rewriteRoutedCustomToolsForUpstream } from "../responses/custom-tool-co
 import { rewriteRoutedToolSearchForUpstream } from "../responses/tool-search-compat";
 import { rewriteRoutedNamespaceToolsForUpstream } from "../responses/namespace-tool-compat";
 import { openaiResponsesUrl } from "./openai-responses-url";
+import { normalizeResponsesCodeMode } from "./responses-code-mode";
 import { injectXaiResponsesXSearch, normalizeXaiResponsesWebSearch } from "./xai-web-search";
 import { EMPTY_TOOL_OUTPUT_ANNOTATION, isWhitespaceOnlyTextPartArray } from "./empty-tool-output-annotation";
 import {
@@ -51,6 +53,7 @@ export const FORWARD_HEADERS = [
   "x-oai-attestation",
   "x-openai-subagent",
   "x-responsesapi-include-timing-metrics",
+  CODEX_RESPONSES_LITE_HEADER,
 ];
 
 /**
@@ -187,7 +190,7 @@ const CANONICAL_ONLY_TOOL_FIELDS: readonly { field: string; toolTypes?: Readonly
   // OWNERSHIP: official OpenAI API-key traffic and unclassified gateways ACCEPT this field, so
   // it is only stripped when the provider capability denies it (supportsOpenAiWebSearchToolFields
   // === false), matching stripOpenAiOnlyWebSearchFields; see
-  // tests/responses-routed-web-search-fields.test.ts.
+  // tests/responses/responses-routed-web-search-fields.test.ts.
   { field: "external_web_access", toolTypes: new Set(["web_search", "web_search_preview"]), capabilityGated: true },
   // Deferred-discovery marker. `activateDeferredTool` clears it only for tools a `tool_search_output`
   // already loaded, so a still-deferred declaration — including one promoted out of a namespace
@@ -906,6 +909,61 @@ function toolOutputText(output: unknown): string {
   }).filter(Boolean).join("\n");
 }
 
+/** True when an output can be losslessly represented as user-message content. */
+function isRepairableToolOutput(output: unknown): output is string | Record<string, unknown>[] {
+  if (typeof output === "string") return true;
+  if (!Array.isArray(output)) return false;
+  return output.every(part => {
+    if (!isPlainObject(part)) return false;
+    if (typeof part.type !== "string") return false;
+    if (["output_text", "text", "input_text"].includes(part.type)) {
+      return typeof part.text === "string";
+    }
+    if (part.type === "refusal") return typeof part.refusal === "string";
+    if (part.type === "encrypted_content") return typeof part.encrypted_content === "string";
+    if (part.type !== "input_image") return false;
+    const imageUrl = part.image_url;
+    const fileId = part.file_id;
+    const imageUrlIsString = typeof imageUrl === "string";
+    const fileIdIsString = typeof fileId === "string";
+    const hasUsableSource = (imageUrlIsString && imageUrl.length > 0)
+      || (fileIdIsString && fileId.length > 0);
+    const validSource = hasUsableSource
+      && (part.image_url === undefined || imageUrlIsString)
+      && (part.file_id === undefined || fileIdIsString);
+    const validDetail = part.detail === undefined
+      || (typeof part.detail === "string"
+        && ["auto", "low", "high", "original"].includes(part.detail));
+    return validSource && validDetail;
+  });
+}
+
+/** Convert orphaned tool output to user-message content without discarding valid images. */
+function orphanedToolOutputContent(output: unknown, callId = ""): Record<string, unknown>[] {
+  const marker = `[tool output for ${callId || "unknown call"}]`;
+  if (typeof output !== "string" && !Array.isArray(output)) {
+    return [{ type: "input_text", text: marker }];
+  }
+  if (!Array.isArray(output)) {
+    return [{ type: "input_text", text: `${marker}\n${toolOutputText(output)}` }];
+  }
+
+  const content: Record<string, unknown>[] = [{ type: "input_text", text: marker }];
+  for (const part of output) {
+    if (!isPlainObject(part)) continue;
+    if (part.type === "input_image") {
+      content.push(part);
+    } else if (part.type === "encrypted_content" && typeof part.encrypted_content === "string") {
+      content.push({ type: "input_text", text: "[encrypted content omitted]" });
+    } else if (typeof part.text === "string") {
+      content.push({ type: "input_text", text: part.text });
+    } else if (part.type === "refusal" && typeof part.refusal === "string") {
+      content.push({ type: "input_text", text: `[refusal] ${part.refusal}` });
+    }
+  }
+  return content;
+}
+
 /** True when a Responses tool output item is present but carries no usable content. */
 function isToolOutputEmpty(output: unknown): boolean {
   if (typeof output === "string") return output.trim() === "";
@@ -940,6 +998,32 @@ function annotateEmptyResponsesToolOutputs(body: unknown, enabled: boolean): unk
   return changed ? { ...body, input } : body;
 }
 
+/**
+ * Preserve the text of structurally invalid tool-output items before they reach a strict
+ * Responses parser. Stateful destinations may legitimately receive an output whose matching
+ * call lives behind `previous_response_id`, so ordinary orphan repair cannot run universally.
+ * A missing or empty `call_id`, however, cannot identify stored state on any destination.
+ */
+function repairUnidentifiedToolOutputItems(body: unknown): unknown {
+  if (!isPlainObject(body) || !Array.isArray(body.input)) return body;
+  let changed = false;
+  const input = body.input.map(item => {
+    if (!isPlainObject(item)
+      || (item.type !== "function_call_output" && item.type !== "custom_tool_call_output")
+      || (typeof item.call_id === "string" && item.call_id.length > 0)) {
+      return item;
+    }
+    if (!isRepairableToolOutput(item.output)) return item;
+    changed = true;
+    return {
+      type: "message",
+      role: "user",
+      content: orphanedToolOutputContent(item.output),
+    };
+  });
+  return changed ? { ...body, input } : body;
+}
+
 /**
  * Repair a forward-mode input array whose continuation context was lost. When the replay
  * expansion misses (proxy restart, unrecorded prior turn), previous_response_id is stripped
@@ -1060,12 +1144,17 @@ function repairOrphanedInputItems(body: unknown, dropReasoning: boolean, synthes
       flushPendingSyntheticOutputs();
       const callId = typeof item.call_id === "string" ? item.call_id : "";
       const paired = isFnOutput ? functionCallIds.has(callId) : customCallIds.has(callId);
-      if (!paired) {
+      const usableOutput = isRepairableToolOutput(item.output);
+      // A known orphan call is still useful as a labeled user message even when its output is
+      // incomplete. With no call id and no output, preserve the invalid item so validation fails
+      // closed rather than pretending any tool result exists.
+      const knownNullOutput = callId.length > 0 && item.output == null;
+      if (!paired && (knownNullOutput || usableOutput)) {
         changed = true;
         repaired.push({
           type: "message",
           role: "user",
-          content: [{ type: "input_text", text: `[tool output for ${callId || "unknown call"}]\n${toolOutputText(item.output)}` }],
+          content: orphanedToolOutputContent(item.output, callId),
         });
         continue;
       }
@@ -1893,14 +1982,67 @@ function normalizeImageGenClientTools(body: unknown): unknown {
  * carries a tool the upstream model 400s on. No-op (returns the original reference) when nothing
  * matches, keeping the common path allocation-free.
  */
-function stripUnsupportedHostedTools(body: unknown): unknown {
-  if (!isPlainObject(body) || !Array.isArray(body.tools)) return body;
+function stripUnsupportedHostedTools(body: unknown, provider: Pick<OcxProviderConfig, "baseUrl">): unknown {
+  if (!isPlainObject(body)) return body;
   const model = typeof body.model === "string" ? body.model : "";
-  const tools = body.tools.filter(t => {
-    const type = isPlainObject(t) && typeof t.type === "string" ? t.type : undefined;
-    return !type || !isHostedToolUnsupportedForModel(model, type);
-  });
-  return tools.length === body.tools.length ? body : { ...body, tools };
+  const filterTools = (tools: unknown[]): unknown[] => {
+    const filtered = tools.filter(t => {
+      const type = isPlainObject(t) && typeof t.type === "string" ? t.type : undefined;
+      return !type || !isHostedToolUnsupportedForModel(model, type, provider.baseUrl);
+    });
+    return filtered.length === tools.length ? tools : filtered;
+  };
+
+  let next: Record<string, unknown> = body;
+  let changed = false;
+  if (Array.isArray(body.tools)) {
+    const tools = filterTools(body.tools);
+    if (tools !== body.tools) {
+      next = { ...next, tools };
+      changed = true;
+    }
+  }
+  if (Array.isArray(body.input)) {
+    let inputChanged = false;
+    const input = body.input.map(item => {
+      if (!isPlainObject(item) || item.type !== "additional_tools" || !Array.isArray(item.tools)) return item;
+      const tools = filterTools(item.tools);
+      if (tools === item.tools) return item;
+      inputChanged = true;
+      return { ...item, tools };
+    });
+    if (inputChanged) {
+      next = { ...next, input };
+      changed = true;
+    }
+  }
+
+  const toolChoice = next.tool_choice;
+  if (isPlainObject(toolChoice) && toolChoice.type === "allowed_tools" && Array.isArray(toolChoice.tools)) {
+    const tools = filterTools(toolChoice.tools);
+    if (tools !== toolChoice.tools) {
+      next = { ...next, tool_choice: tools.length > 0 ? { ...toolChoice, tools } : "none" };
+      changed = true;
+    }
+  } else if (
+    isPlainObject(toolChoice)
+    && typeof toolChoice.type === "string"
+    && isHostedToolUnsupportedForModel(model, toolChoice.type, provider.baseUrl)
+  ) {
+    next = { ...next, tool_choice: "none" };
+    changed = true;
+  } else if (changed && toolChoice === "required") {
+    const hasDeclaredTools = (Array.isArray(next.tools) && next.tools.length > 0)
+      || (Array.isArray(next.input) && next.input.some(item =>
+        isPlainObject(item)
+        && item.type === "additional_tools"
+        && Array.isArray(item.tools)
+        && item.tools.length > 0));
+    if (!hasDeclaredTools) {
+      next = { ...next, tool_choice: "none" };
+    }
+  }
+  return changed ? next : body;
 }
 
 /**
@@ -1966,10 +2108,10 @@ export function stripOpenAiOnlyWebSearchFields(body: unknown): unknown {
 }
 
 /**
- * Muse Spark ids whose Responses gateway refuses `search_content_types` on a plain
+ * Muse Spark ids whose Responses gateway refuses provider-specific fields on a plain
  * `web_search` tool. Membership, not equality: 1.3 shipped 2026-09-02 as the
  * same-shaped successor to 1.2 on the same Zen wire, and an equality check would
- * have let a Codex-emitted `web_search` + `search_content_types` body reach the
+ * have let a Codex-emitted `web_search` body reach the
  * gateway and come back 400 for every request the moment 1.3 was selected.
  */
 const MUSE_SPARK_WEB_SEARCH_STRICT_MODELS = new Set([
@@ -1977,26 +2119,51 @@ const MUSE_SPARK_WEB_SEARCH_STRICT_MODELS = new Set([
   "muse-spark-1.2-contributor",
 ]);
 
+const MUSE_SPARK_WEB_SEARCH_STRICT_RESPONSE_URLS = new Set([
+  "https://opencode.ai/zen/v1/responses",
+  "https://opencode.ai/zen/go/v1/responses",
+]);
+
+const MUSE_SPARK_UNSUPPORTED_WEB_SEARCH_FIELDS = [
+  "search_content_types",
+  "indexed_web_access",
+] as const;
+
 /**
- * OpenCode Zen / Go Muse Spark Responses gateway refuses `search_content_types`
- * on a plain `web_search` tool (400) but accepts it on `web_search_preview`; a
- * plain `web_search` is also accepted. Probed directly against the gateway on
- * 2026-08-26: `web_search` + `search_content_types` -> 400, `web_search_preview`
- * + `search_content_types` -> 200, plain `web_search` -> 200. Luna accepts every
- * shape, so this is Muse-only. Drop only the field the gateway refuses while
- * keeping the tool type and every other accepted option intact.
+ * OpenCode Zen / Go Muse Spark Responses gateway refuses a short list of Codex
+ * `web_search` fields. `web_search_preview` keeps its accepted shape, and Luna
+ * remains untouched. Match the exact effective request URL; malformed, credentialed,
+ * or parameterized destinations keep their original body instead of assuming this
+ * gateway contract. Keep the rejected names together so a newly identified field is
+ * a one-line compatibility update rather than another bespoke rewrite.
  */
-function stripMuseSparkUnsupportedWebSearchFields(body: unknown, modelId: unknown): unknown {
+function stripMuseSparkUnsupportedWebSearchFields(
+  body: unknown,
+  modelId: unknown,
+  responseUrl: string,
+): unknown {
   if (!isPlainObject(body)) return body;
   if (typeof modelId !== "string") return body;
   if (!MUSE_SPARK_WEB_SEARCH_STRICT_MODELS.has(modelId.trim().toLowerCase())) return body;
+  let destination: string;
+  try {
+    const url = new URL(responseUrl);
+    if (url.username || url.password || url.search || url.hash) return body;
+    destination = `${url.origin.toLowerCase()}${url.pathname.replace(/\/+$/, "")}`;
+  } catch {
+    return body;
+  }
+  if (!MUSE_SPARK_WEB_SEARCH_STRICT_RESPONSE_URLS.has(destination)) return body;
 
   const rewriteTools = (tools: unknown[]): { tools: unknown[]; changed: boolean } => {
     let changed = false;
     const rewritten = tools.map(tool => {
       if (!isPlainObject(tool) || tool.type !== "web_search") return tool;
-      if (!Object.hasOwn(tool, "search_content_types")) return tool;
-      const { search_content_types: _dropped, ...rest } = tool;
+      if (!MUSE_SPARK_UNSUPPORTED_WEB_SEARCH_FIELDS.some(field => Object.hasOwn(tool, field))) {
+        return tool;
+      }
+      const rest = { ...tool };
+      for (const field of MUSE_SPARK_UNSUPPORTED_WEB_SEARCH_FIELDS) delete rest[field];
       changed = true;
       return rest;
     });
@@ -2075,11 +2242,26 @@ function usageFromResponsesPayload(payload: unknown): OcxUsage | undefined {
   const usage = payload.usage;
   const inputTokens = typeof usage.input_tokens === "number" ? usage.input_tokens : 0;
   const outputTokens = typeof usage.output_tokens === "number" ? usage.output_tokens : 0;
-  if (inputTokens === 0 && outputTokens === 0) return undefined;
+  // openai/codex#41980: the raw usage object is wire data a rebuilt response.completed must keep —
+  // unknown keys (subscription metadata, future counters) ride along even when the token counts
+  // themselves are zero or absent (metadata-only usage).
+  const knownKeys = new Set(["input_tokens", "output_tokens", "total_tokens", "input_tokens_details", "output_tokens_details"]);
+  const hasExtras = Object.keys(usage).some(key => !knownKeys.has(key))
+    || (isPlainObject(usage.input_tokens_details)
+      && Object.keys(usage.input_tokens_details).some(key => key !== "cached_tokens" && key !== "cache_write_tokens"))
+    || (isPlainObject(usage.output_tokens_details)
+      && Object.keys(usage.output_tokens_details).some(key => key !== "reasoning_tokens"));
+  if (inputTokens === 0 && outputTokens === 0 && !hasExtras) return undefined;
+  const inputDetails = isPlainObject(usage.input_tokens_details) ? usage.input_tokens_details : undefined;
+  const outputDetails = isPlainObject(usage.output_tokens_details) ? usage.output_tokens_details : undefined;
   return {
     inputTokens,
     outputTokens,
     ...(typeof usage.total_tokens === "number" ? { totalTokens: usage.total_tokens } : {}),
+    ...(typeof inputDetails?.cached_tokens === "number" ? { cachedInputTokens: inputDetails.cached_tokens } : {}),
+    ...(typeof inputDetails?.cache_write_tokens === "number" ? { cacheCreationInputTokens: inputDetails.cache_write_tokens } : {}),
+    ...(typeof outputDetails?.reasoning_tokens === "number" ? { reasoningOutputTokens: outputDetails.reasoning_tokens } : {}),
+    ...(hasExtras ? { rawUsage: { ...usage } } : {}),
   };
 }
 
@@ -2137,7 +2319,14 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         if (mayForwardCallerCredentials) {
           for (const h of FORWARD_HEADERS) {
             const v = incoming?.headers.get(h);
-            if (v) headers[h] = v;                                      // …so forwarded auth always wins.
+            if (v) {
+              if (h === CODEX_RESPONSES_LITE_HEADER) {
+                for (const name of Object.keys(headers)) {
+                  if (name.toLowerCase() === h) delete headers[name];
+                }
+              }
+              headers[h] = v; // …so genuine forwarded fields win.
+            }
           }
         }
         const override = runtimeProvider._codexAccountOverride;
@@ -2250,18 +2439,22 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         if (provider.supportsOpenAiWebSearchToolFields === false) {
           outBody = stripOpenAiOnlyWebSearchFields(outBody);
         }
-        outBody = stripMuseSparkUnsupportedWebSearchFields(outBody, parsed.modelId);
+        outBody = stripMuseSparkUnsupportedWebSearchFields(outBody, parsed.modelId, url);
         // Last, so promoted namespace children are also cleared of Codex-private fields.
         outBody = stripCanonicalOnlyToolFields(outBody, provider.supportsOpenAiWebSearchToolFields === false);
       }
       // Same predicate as the routedCompaction gate in handleResponses(): an authMode check would
       // let a noncanonical custom forward provider skip this rewrite while the server still routes
       // it as a summarizer turn (#422). The compaction body build removes the tool surface and must
-      // therefore be the last routed transform: anything before it may depend on the declarations;
-      // anything after it cannot.
+      // therefore be the last routed transform that may depend on those declarations. Structural
+      // sanitizers below can still run after it.
+      outBody = normalizeResponsesCodeMode(outBody, parsed, provider);
       if (parsed._compactionRequest === true && !isCanonicalOpenAiForwardProvider(provider)) {
         outBody = buildRoutedCompactionBody(outBody);
       }
+      // Run after routed compaction so nested input_image parts are replaced before a malformed
+      // tool output is flattened to text and can no longer be inspected structurally.
+      outBody = repairUnidentifiedToolOutputItems(outBody);
       const threadServingIdentityChanged = parsed._stripReasoningEncryptedContent === true;
       const sanitizedBody = normalizeToolSchemas(
         stripSparkCompatibility(
@@ -2281,6 +2474,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
                       stripEncryptedContent: threadServingIdentityChanged,
                     },
                   ),
+                  provider,
                 ),
               ),
             ),
@@ -2297,6 +2491,17 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         provider,
         parsed.modelId,
       );
+      if (isCanonicalOpenAiForwardProvider(provider)) {
+        const routingHeaders = new Headers(headers);
+        applyCodexRoutingHint(routingHeaders, finalBody);
+        // Static headers may use mixed casing. Remove every stale spelling
+        // without normalizing unrelated headers returned by this adapter.
+        for (const name of Object.keys(headers)) {
+          if (name.toLowerCase() === CODEX_ROUTING_HINT_HEADER) delete headers[name];
+        }
+        const hint = routingHeaders.get(CODEX_ROUTING_HINT_HEADER);
+        if (hint !== null) headers[CODEX_ROUTING_HINT_HEADER] = hint;
+      }
       const actualServiceTier = isPlainObject(finalBody) && typeof finalBody.service_tier === "string"
         ? finalBody.service_tier
         : null;
@@ -2391,7 +2596,26 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
               reservation.commitRetained();
               budget.releaseRetained(previousBytes, { kind: "retained_collectors" });
             }
-            usage = usageFromResponsesPayload(payload.response);
+            {
+              const nextUsage = usageFromResponsesPayload(payload.response);
+              // The attached raw usage object can be event-sized (unknown keys carry arbitrary
+              // values); it stays reachable until the terminal yields, so charge it like the
+              // adjacent retained collectors or it would defeat the per-request memory cap.
+              const previousRawBytes = usage?.rawUsage === undefined ? 0
+                : budgetEncoder.encode(JSON.stringify(usage.rawUsage)).byteLength;
+              const nextRawBytes = nextUsage?.rawUsage === undefined ? 0
+                : budgetEncoder.encode(JSON.stringify(nextUsage.rawUsage)).byteLength;
+              if (nextRawBytes > 0) {
+                const reservation = budget.reserveTransient(nextRawBytes, { kind: "retained_collectors" });
+                usage = nextUsage;
+                reservation.commitRetained();
+              } else {
+                usage = nextUsage;
+              }
+              if (previousRawBytes > 0) {
+                budget.releaseRetained(previousRawBytes, { kind: "retained_collectors" });
+              }
+            }
             break;
         }
       }
@@ -2399,7 +2623,13 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       // completed snapshot so text is never double-counted.
       const text = snapshot || doneText || deltas;
       if (text) yield { type: "text_delta", text };
-      budget.releaseRetained(budgetEncoder.encode(deltas).byteLength + budgetEncoder.encode(doneText).byteLength + budgetEncoder.encode(snapshot).byteLength, { kind: "retained_collectors" });
+      budget.releaseRetained(
+        budgetEncoder.encode(deltas).byteLength
+          + budgetEncoder.encode(doneText).byteLength
+          + budgetEncoder.encode(snapshot).byteLength
+          + (usage?.rawUsage === undefined ? 0 : budgetEncoder.encode(JSON.stringify(usage.rawUsage)).byteLength),
+        { kind: "retained_collectors" },
+      );
       yield {
         type: "done",
         ...(usage ? { usage } : {}),