@yansigit/opencodex 2.31.0

package/src/reasoning-effort.ts

@@ -0,0 +1,183 @@
+import type { OcxProviderConfig } from "./types";
+import { modelInList } from "./types";
+
+// Descriptions mirror the upstream bundled models.json canonical wording (openai/codex PR #31684).
+export const CODEX_REASONING_LEVELS: { effort: string; description: string }[] = [
+  { effort: "low", description: "Fast responses with lighter reasoning" },
+  { effort: "medium", description: "Balances speed and reasoning depth for everyday tasks" },
+  { effort: "high", description: "Greater reasoning depth for complex problems" },
+  { effort: "xhigh", description: "Extra high reasoning depth for complex problems" },
+  { effort: "max", description: "Maximum reasoning depth for the hardest problems" },
+  { effort: "ultra", description: "Maximum reasoning with automatic task delegation" },
+];
+
+const CODEX_REASONING_ORDER = CODEX_REASONING_LEVELS.map(l => l.effort);
+const CODEX_REASONING_SET = new Set(CODEX_REASONING_ORDER);
+
+/** True when `effort` is a member of the Codex reasoning ladder (low..ultra). */
+export function isCodexReasoningEffort(effort: string): boolean {
+  return CODEX_REASONING_SET.has(effort);
+}
+
+/**
+ * True for ladder members plus the `none`/`minimal` sentinels. Both are valid declared
+ * efforts (OpenAI accepts `minimal`; Codex validates `none` against
+ * `supported_reasoning_levels` for no-reasoning subagent spawns, #883/#962) but are NOT
+ * part of the low..ultra ladder: they never appear in default ladders, ranks, or clamps
+ * (`minimal` is mapped to `low` on the wire by requestToCodexEffort).
+ */
+export function isDeclaredReasoningEffort(effort: string): boolean {
+  return effort === "none" || effort === "minimal" || CODEX_REASONING_SET.has(effort);
+}
+
+/**
+ * Reorder any declared subset (low..ultra, plus the optional `none`/`minimal` sentinels
+ * first, in that order) into canonical order and drop duplicates. Catalog
+ * `supported_reasoning_levels` follow the input order and the fallback default picks the
+ * first entry, so a caller-chosen order would otherwise leak into the catalog.
+ */
+export function canonicalizeReasoningEfforts(values: readonly string[]): string[] {
+  const seen = new Set(values);
+  const ordered = CODEX_REASONING_ORDER.filter(effort => seen.has(effort));
+  const sentinels = ["none", "minimal"].filter(effort => seen.has(effort));
+  return [...sentinels, ...ordered];
+}
+
+/**
+ * Reasoning ladder accepted for the OpenAI vision sidecar. `ultra` is deliberately excluded:
+ * the vision describer is a single helper call, and `ultra` would be collapsed to `max` by the
+ * upstream client boundary anyway.
+ */
+export const VISION_REASONING_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+export type VisionReasoningEffort = typeof VISION_REASONING_EFFORTS[number];
+
+/** True when `effort` is one of the vision sidecar's supported Responses reasoning levels. */
+export function isVisionReasoningEffort(effort: unknown): effort is VisionReasoningEffort {
+  return typeof effort === "string" && (VISION_REASONING_EFFORTS as readonly string[]).includes(effort);
+}
+
+/**
+ * Normalize a persisted/configured vision reasoning value. Invalid values (hand-edited config,
+ * stale files) degrade to `undefined` so the caller falls back to the documented default instead
+ * of forwarding an upstream-rejected effort.
+ */
+export function sanitizeVisionReasoning(effort: unknown): VisionReasoningEffort | undefined {
+  return isVisionReasoningEffort(effort) ? effort : undefined;
+}
+
+/** Position of `effort` in the Codex ladder (low=0 .. ultra=5), or -1 when not a ladder member. */
+export function codexEffortRank(effort: string): number {
+  return CODEX_REASONING_ORDER.indexOf(effort);
+}
+
+export function modelRecordValue<T>(record: Record<string, T> | undefined, modelId: string): T | undefined {
+  if (!record) return undefined;
+  if (Object.prototype.hasOwnProperty.call(record, modelId)) return record[modelId];
+  const colon = modelId.indexOf(":");
+  if (colon > 0) {
+    const family = modelId.slice(0, colon);
+    if (Object.prototype.hasOwnProperty.call(record, family)) return record[family];
+  }
+  const folded = modelId.toLowerCase();
+  for (const [key, value] of Object.entries(record)) {
+    if (key.toLowerCase() === folded) return value;
+  }
+  return undefined;
+}
+
+export function sanitizeCodexReasoningEfforts(efforts: readonly string[] | undefined): string[] | undefined {
+  if (efforts === undefined) return undefined;
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const effort of efforts) {
+    // `none`/`minimal` are valid declared sentinels, kept and sorted first (rank -1); they
+    // never appear in the default ladder.
+    if ((effort !== "none" && effort !== "minimal" && !CODEX_REASONING_SET.has(effort)) || seen.has(effort)) continue;
+    seen.add(effort);
+    out.push(effort);
+  }
+  return out.sort((a, b) => CODEX_REASONING_ORDER.indexOf(a) - CODEX_REASONING_ORDER.indexOf(b));
+}
+
+/**
+ * Provider/model configured reasoning levels for the Codex catalog. `undefined` means “no override”,
+ * while an empty array means “intentionally expose no effort control for this model”.
+ */
+export function configuredReasoningEfforts(provider: OcxProviderConfig, modelId: string): string[] | undefined {
+  if (modelInList(provider.noReasoningModels, modelId)) return [];
+  const modelEfforts = modelRecordValue(provider.modelReasoningEfforts, modelId);
+  if (modelEfforts !== undefined) return healMappedTiers(provider, modelId, sanitizeCodexReasoningEfforts(modelEfforts) ?? []);
+  if (provider.reasoningEfforts !== undefined) return healMappedTiers(provider, modelId, sanitizeCodexReasoningEfforts(provider.reasoningEfforts) ?? []);
+  return undefined;
+}
+
+/**
+ * Stale-ladder self-heal: a registry wire map is authoritative evidence of the upstream tiers
+ * it can emit. Merge Codex-native map values into an older persisted ladder so newly documented
+ * tiers appear without rewriting the user's config. Non-Codex values such as enabled/disabled
+ * and Kimi's none sentinel are ignored here; they remain request-only wire aliases.
+ */
+function healMappedTiers(provider: OcxProviderConfig, modelId: string, efforts: string[]): string[] {
+  if (efforts.length === 0) return efforts;
+  const wireMap = reasoningEffortMapFor(provider, modelId);
+  if (!wireMap) return efforts;
+  const mappedTiers = Object.values(wireMap).filter(isCodexReasoningEffort);
+  if (mappedTiers.length === 0) return efforts;
+  return sanitizeCodexReasoningEfforts([...efforts, ...mappedTiers]) ?? efforts;
+}
+
+function requestToCodexEffort(requested: string): string | undefined {
+  if (requested === "none") return undefined;
+  if (requested === "minimal") return "low";
+  return CODEX_REASONING_SET.has(requested) ? requested : undefined;
+}
+
+function clampToSupportedCodexEffort(requested: string, supported: readonly string[]): string | undefined {
+  if (supported.length === 0) return undefined;
+  const codex = requestToCodexEffort(requested);
+  if (!codex) return undefined;
+  if (supported.includes(codex)) return codex;
+
+  const requestedRank = CODEX_REASONING_ORDER.indexOf(codex);
+  let best = supported[0];
+  let bestRank = CODEX_REASONING_ORDER.indexOf(best);
+  for (const effort of supported) {
+    const rank = CODEX_REASONING_ORDER.indexOf(effort);
+    if (rank <= requestedRank && rank >= bestRank) {
+      best = effort;
+      bestRank = rank;
+    }
+  }
+  // If every supported tier is above the requested tier, choose the lowest supported tier.
+  return best;
+}
+
+export function reasoningEffortMapFor(provider: OcxProviderConfig, modelId: string): Record<string, string> | undefined {
+  return modelRecordValue(provider.modelReasoningEffortMap, modelId) ?? provider.reasoningEffortMap;
+}
+
+/**
+ * Translate Codex's reasoning label into the provider's real wire value. Prefer identity labels
+ * (`xhigh` stays `xhigh`, `max` stays `max`); provider maps are only for real upstream aliases.
+ */
+export function mapReasoningEffort(provider: OcxProviderConfig, modelId: string, requested: string | undefined): string | undefined {
+  if (!requested) return undefined;
+  if (modelInList(provider.noReasoningModels, modelId)) return undefined;
+
+  // Upstream codex-rs converts ultra -> max before ANY provider request (core/src/client.rs
+  // `reasoning_effort_for_request`), so "ultra" must never influence the provider wire — not even
+  // through a raw alias. Apply the boundary before alias/clamp resolution.
+  const boundary = requested === "ultra" ? "max" : requested;
+
+  const wireMap = reasoningEffortMapFor(provider, modelId);
+  if (wireMap && Object.prototype.hasOwnProperty.call(wireMap, boundary)) return wireMap[boundary];
+
+  const supported = configuredReasoningEfforts(provider, modelId);
+  const codexEffort = supported !== undefined ? clampToSupportedCodexEffort(boundary, supported) : requestToCodexEffort(boundary);
+  if (!codexEffort) return undefined;
+
+  // Belt for the odd config where the supported ladder is ultra-only and the clamp lands on it.
+  const wire = codexEffort === "ultra" ? "max" : codexEffort;
+  if (wireMap && Object.prototype.hasOwnProperty.call(wireMap, wire)) return wireMap[wire];
+  return wire;
+}

package/src/responses/compaction.ts

@@ -0,0 +1,142 @@
+/**
+ * Remote compaction v2 support for ROUTED providers.
+ *
+ * Codex decides "this provider supports remote compaction" by provider name (built-in `OpenAI`),
+ * and Design B points that provider at this proxy — so Codex sends remote compaction v2 requests
+ * for EVERY routed model. The request is a normal /responses call whose input ends with
+ * `{"type":"compaction_trigger"}`; codex-rs `collect_compaction_output` then requires the stream
+ * to carry EXACTLY ONE `{"type":"compaction","encrypted_content":...}` output item
+ * (compact_remote_v2.rs) or it fatals with "expected exactly one compaction output item".
+ *
+ * Routed models cannot produce OpenAI's encrypted blob, so the proxy runs the model as a plain
+ * summarizer and wraps the summary text in a transparent envelope: `ocx1:` + base64(utf8 summary).
+ * Codex stores the item and replays it in later input; the parser decodes our envelope back into
+ * plain text for routed models. Real OpenAI-encrypted blobs (no `ocx1:` prefix) are opaque —
+ * routed models get a short "history was compacted" note instead.
+ */
+
+export const OCX_COMPACTION_PREFIX = "ocx1:";
+
+/** Mirrors codex-rs core/templates/compact/prompt.md (the local-compaction instruction). */
+export const COMPACT_PROMPT = `You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
+
+Include:
+- Current progress and key decisions made
+- Important context, constraints, or user preferences
+- What remains to be done (clear next steps)
+- Any critical data, examples, or references needed to continue
+
+Be concise, structured, and focused on helping the next LLM seamlessly continue the work.`;
+
+/** Mirrors codex-rs core/templates/compact/summary_prefix.md (framing for a replayed summary). */
+export const SUMMARY_PREFIX = "Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. Use this to build on the work that has already been done and avoid duplicating work. Here is the summary produced by the other language model, use the information in this summary to assist with your own analysis:";
+
+export const OPAQUE_COMPACTION_NOTE = "[earlier conversation was compacted; the summary is stored in a format this model cannot read]";
+
+/**
+ * Item types in the compact wire family. Each carries an `encrypted_content` blob the client
+ * replays verbatim on every later turn, and the minting backend verifies it is unmodified.
+ *
+ * Keep this the only enumeration: a copy that listed just `compaction` let the response-side
+ * field backfill synthesize ids into the other two, which the client then replayed as "modified
+ * from the compact response".
+ */
+const COMPACTION_ITEM_TYPES: ReadonlySet<string> = new Set([
+  "compaction",
+  "compaction_summary",
+  "context_compaction",
+]);
+
+export function isCompactionItemType(type: unknown): boolean {
+  return typeof type === "string" && COMPACTION_ITEM_TYPES.has(type);
+}
+
+export function encodeCompactionSummary(summary: string): string {
+  return OCX_COMPACTION_PREFIX + Buffer.from(summary, "utf-8").toString("base64");
+}
+
+/** Decode an `ocx1:` envelope; returns null for real (OpenAI-encrypted) blobs or garbage. */
+export function decodeCompactionSummary(encryptedContent: string): string | null {
+  if (!encryptedContent.startsWith(OCX_COMPACTION_PREFIX)) return null;
+  try {
+    return Buffer.from(encryptedContent.slice(OCX_COMPACTION_PREFIX.length), "base64").toString("utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Render a replayed compaction item as plain user-visible text for a routed model. */
+export function compactionItemToText(encryptedContent: string | undefined): string {
+  const decoded = typeof encryptedContent === "string" ? decodeCompactionSummary(encryptedContent) : null;
+  return decoded ? `${SUMMARY_PREFIX}\n\n${decoded}` : OPAQUE_COMPACTION_NOTE;
+}
+
+/**
+ * Remote compaction v1 (`POST /responses/compact`, unary) — codex-rs installs the returned
+ * `{"output":[ResponseItem...]}` as the REPLACEMENT history (compact_remote.rs
+ * process_compacted_history). Mirror codex-rs local `build_compacted_history`: recent real user
+ * messages within a token budget, then one user message `SUMMARY_PREFIX\n<summary>`. Plain user
+ * message items parse as real user messages on the codex side (event_mapping parse_user_message);
+ * contextual wrappers are filtered there, and v2-style `compaction` items are NOT expected here.
+ */
+
+/** codex-rs compact.rs COMPACT_USER_MESSAGE_MAX_TOKENS = 20k tokens (~4 chars/token). */
+const COMPACT_V1_RETAINED_CHAR_BUDGET = 20_000 * 4;
+
+/** Extract plain-text user messages from a Responses `input` array (for v1 compact retention). */
+export function extractCompactUserMessages(input: unknown): string[] {
+  if (!Array.isArray(input)) return [];
+  const out: string[] = [];
+  for (const item of input) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const rec = item as { type?: string; role?: string; content?: unknown };
+    if (rec.type !== undefined && rec.type !== "message") continue;
+    if (rec.role !== "user") continue;
+    let text = "";
+    if (typeof rec.content === "string") text = rec.content;
+    else if (Array.isArray(rec.content)) {
+      text = rec.content
+        .map(b => {
+          if (!b || typeof b !== "object") return "";
+          const block = b as { type?: string; text?: string };
+          return (block.type === "input_text" || block.type === "text") && typeof block.text === "string" ? block.text : "";
+        })
+        .join("");
+    }
+    if (text.trim().length > 0) out.push(text);
+  }
+  return out;
+}
+
+function compactUserMessageItem(text: string): Record<string, unknown> {
+  return { type: "message", role: "user", content: [{ type: "input_text", text }] };
+}
+
+/** Build the v1 compact `output` array: retained recent user messages + the summary message. */
+export function buildCompactV1Output(userMessages: string[], summary: string): Record<string, unknown>[] {
+  const selected: string[] = [];
+  let remaining = COMPACT_V1_RETAINED_CHAR_BUDGET;
+  for (let i = userMessages.length - 1; i >= 0 && remaining > 0; i--) {
+    const msg = userMessages[i];
+    if (msg.length <= remaining) {
+      selected.push(msg);
+      remaining -= msg.length;
+    } else {
+      // Budget partially covers this older message: keep its tail (most recent context) and stop.
+      let tailStart = msg.length - remaining;
+      // Never start the retained tail on a lone LOW surrogate: the pair's
+      // other half would be lost and encoding substitutes U+FFFD.
+      if (tailStart > 0 && tailStart < msg.length) {
+        const first = msg.charCodeAt(tailStart);
+        if (first >= 0xdc00 && first <= 0xdfff) tailStart += 1;
+      }
+      selected.push(msg.slice(tailStart));
+      break;
+    }
+  }
+  selected.reverse();
+  // codex-rs compact.rs uses "{SUMMARY_PREFIX}\n{summary}" (single newline) and detects stored
+  // summaries by that exact prefix — keep the same shape.
+  const summaryText = summary.trim().length > 0 ? `${SUMMARY_PREFIX}\n${summary}` : "(no summary available)";
+  return [...selected.map(compactUserMessageItem), compactUserMessageItem(summaryText)];
+}

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

@@ -0,0 +1,266 @@
+import { namespacedToolName } from "../types";
+import { collectResponsesToolGroups } from "./tool-groups";
+
+const ROUTED_CUSTOM_TOOL_PASSTHROUGH = new Set(["apply_patch"]);
+const BUILTIN_FUNCTIONS_NAMESPACE = "functions";
+
+function routedCustomToolPassesThrough(
+  name: string,
+  supportsResponsesCustomTools: boolean | undefined,
+): boolean {
+  return supportsResponsesCustomTools !== false && ROUTED_CUSTOM_TOOL_PASSTHROUGH.has(name);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function customToolInput(argumentsText: unknown): string {
+  if (typeof argumentsText !== "string") return "";
+  try {
+    const parsed = JSON.parse(argumentsText) as unknown;
+    if (isPlainObject(parsed) && typeof parsed.input === "string") return parsed.input;
+  } catch { /* malformed arguments stay visible to the client */ }
+  return argumentsText;
+}
+
+function customToolWireName(namespace: string | undefined, name: string): string {
+  return namespace === BUILTIN_FUNCTIONS_NAMESPACE ? name : namespacedToolName(namespace, name);
+}
+
+/** Final upstream identity of a call, including a namespace restored by an earlier rewrite. */
+export function routedCustomToolWireName(value: unknown): string | undefined {
+  if (!isPlainObject(value) || typeof value.name !== "string") return undefined;
+  return customToolWireName(
+    typeof value.namespace === "string" ? value.namespace : undefined,
+    value.name,
+  );
+}
+
+/**
+ * Names of converted custom declarations after namespace lowering. Restoration uses these exact
+ * wire identities so same-named function and custom children in different namespaces stay distinct.
+ */
+function collectRoutedCustomToolWireNames(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): Set<string> {
+  const names = new Set<string>();
+  const groups = collectResponsesToolGroups(body);
+  const bareWireNames = new Set<string>();
+  for (const group of groups) {
+    for (const tool of group) {
+      if (
+        isPlainObject(tool)
+        && tool.type !== "namespace"
+        && typeof tool.name === "string"
+      ) bareWireNames.add(tool.name);
+    }
+  }
+
+  for (const group of groups) {
+    for (const tool of group) {
+      if (!isPlainObject(tool)) continue;
+      if (
+        tool.type === "custom"
+        && typeof tool.name === "string"
+        && !routedCustomToolPassesThrough(tool.name, supportsResponsesCustomTools)
+      ) {
+        names.add(tool.name);
+        continue;
+      }
+      if (tool.type !== "namespace" || typeof tool.name !== "string" || !Array.isArray(tool.tools)) {
+        continue;
+      }
+      for (const child of tool.tools) {
+        if (
+          isPlainObject(child)
+          && child.type === "custom"
+          && typeof child.name === "string"
+          && !routedCustomToolPassesThrough(child.name, supportsResponsesCustomTools)
+          && !(tool.name === BUILTIN_FUNCTIONS_NAMESPACE && bareWireNames.has(child.name))
+        ) names.add(customToolWireName(tool.name, child.name));
+      }
+    }
+  }
+  return names;
+}
+
+export function customToolItemId(id: unknown): unknown {
+  if (typeof id !== "string") return id;
+  return id.startsWith("fc_") ? `ctc_${id.slice(3)}` : id;
+}
+
+export function collectRoutedCustomToolNames(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): Set<string> {
+  const names = new Set<string>();
+  const visit = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const entry of value) visit(entry);
+      return;
+    }
+    if (!isPlainObject(value)) return;
+    if (
+      value.type === "custom"
+      && typeof value.name === "string"
+      && !routedCustomToolPassesThrough(value.name, supportsResponsesCustomTools)
+    ) {
+      names.add(value.name);
+    }
+    for (const entry of Object.values(value)) visit(entry);
+  };
+  visit(body);
+  return names;
+}
+
+function collectConvertedCallIds(value: unknown, names: ReadonlySet<string>, out: Set<string>): void {
+  if (Array.isArray(value)) {
+    for (const entry of value) collectConvertedCallIds(entry, names, out);
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  if (
+    (value.type === "custom_tool_call" || value.type === "function_call")
+    && typeof value.name === "string"
+    && names.has(value.name)
+    && typeof value.call_id === "string"
+  ) {
+    out.add(value.call_id);
+  }
+  for (const entry of Object.values(value)) collectConvertedCallIds(entry, names, out);
+}
+
+function rewriteForUpstream(
+  value: unknown,
+  names: ReadonlySet<string>,
+  callIds: ReadonlySet<string>,
+): unknown {
+  if (Array.isArray(value)) return value.map(entry => rewriteForUpstream(entry, names, callIds));
+  if (!isPlainObject(value)) return value;
+
+  if (value.type === "custom" && typeof value.name === "string" && names.has(value.name)) {
+    const { format: _format, ...rest } = value;
+    const isDefinition = typeof value.description === "string"
+      || isPlainObject(value.format)
+      || isPlainObject(value.parameters);
+    if (!isDefinition) return { ...rest, type: "function" };
+    const inputDescription = value.name === "exec"
+      ? "JavaScript source for unified exec. Use await tools.exec_command(...) for shell commands and text(...) to return textual output; do not provide a bare shell command."
+      : "Raw input for this client-executed custom tool.";
+    return {
+      ...rest,
+      type: "function",
+      parameters: {
+        type: "object",
+        properties: {
+          input: {
+            type: "string",
+            description: inputDescription,
+          },
+        },
+        required: ["input"],
+        additionalProperties: false,
+      },
+    };
+  }
+
+  if (
+    value.type === "custom_tool_call"
+    && typeof value.name === "string"
+    && names.has(value.name)
+  ) {
+    const { input, id: _id, ...rest } = value;
+    return {
+      ...rest,
+      type: "function_call",
+      arguments: JSON.stringify({ input: typeof input === "string" ? input : "" }),
+    };
+  }
+
+  if (
+    value.type === "custom_tool_call_output"
+    && typeof value.call_id === "string"
+    && callIds.has(value.call_id)
+  ) {
+    return { ...value, type: "function_call_output" };
+  }
+
+  let changed = false;
+  const next: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const rewritten = rewriteForUpstream(entry, names, callIds);
+    next[key] = rewritten;
+    changed ||= rewritten !== entry;
+  }
+  return changed ? next : value;
+}
+
+export function rewriteRoutedCustomToolsForUpstream(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): {
+  body: unknown;
+  names: Set<string>;
+} {
+  const conversionNames = collectRoutedCustomToolNames(body, supportsResponsesCustomTools);
+  const names = collectRoutedCustomToolWireNames(body, supportsResponsesCustomTools);
+  if (conversionNames.size === 0) return { body, names };
+  const callIds = new Set<string>();
+  collectConvertedCallIds(body, conversionNames, callIds);
+  return { body: rewriteForUpstream(body, conversionNames, callIds), names };
+}
+
+export function restoreRoutedCustomCalls(
+  value: unknown,
+  names: ReadonlySet<string>,
+): { value: unknown; changed: boolean } {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const restored = value.map(entry => {
+      const result = restoreRoutedCustomCalls(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 = restoreRoutedCustomCalls(entry, names);
+    restored[key] = result.value;
+    changed ||= result.changed;
+  }
+
+  const wireName = routedCustomToolWireName(value);
+  if (value.type === "function_call" && wireName !== undefined && names.has(wireName)) {
+    restored.type = "custom_tool_call";
+    restored.id = customToolItemId(value.id);
+    restored.input = customToolInput(value.arguments);
+    delete restored.arguments;
+    changed = true;
+  }
+  return changed ? { value: restored, changed: true } : { value, changed: false };
+}
+
+export function restoreRoutedCustomCallsInJson(
+  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 = restoreRoutedCustomCalls(payload, names);
+  return restored.changed ? JSON.stringify(restored.value) : text;
+}
+
+export function unwrapRoutedCustomToolArguments(argumentsText: unknown): string {
+  return customToolInput(argumentsText);
+}

package/src/responses/hosted-tool-policy.ts

@@ -0,0 +1,9 @@
+/** Hosted tools rejected by specific native model slugs. */
+const UNSUPPORTED_HOSTED_TOOLS: ReadonlyArray<{ match: (model: string) => boolean; tools: ReadonlySet<string> }> = [
+  { match: model => model.includes("codex-spark"), tools: new Set(["image_generation", "tool_search"]) },
+];
+
+/** True when forwarding this hosted tool to the model would be rejected upstream. */
+export function isHostedToolUnsupportedForModel(modelId: string, tool: string): boolean {
+  return UNSUPPORTED_HOSTED_TOOLS.some(entry => entry.match(modelId) && entry.tools.has(tool));
+}