@iislee/opencodex 2.11.0 → 2.35.0

package/src/responses/thought-signature-replay.ts

@@ -0,0 +1,364 @@
+/**
+ * Server-side thought-signature replay store (issue #1735 follow-up).
+ *
+ * Gemini issues a thoughtSignature on the function-call part of a response and requires it
+ * back when the same call is replayed in a later request. The Responses wire carries the
+ * signature in extra_content.google.thought_signature, and a conforming client echoes it on
+ * the replay. Real clients (codex-rs 0.144.x, Codex desktop) do NOT echo extra_content:
+ * they replay history as bare function_call / custom_tool_call items keyed by call_id.
+ * Without the signature Gemini rejects the replayed part with
+ * "Function call is missing a thought_signature in functionCall parts".
+ *
+ * This module is the proxy-side fallback: remember the signature we handed out and re-attach
+ * it on replay even when the client never echoes it. Values stay opaque (never parsed or
+ * re-encoded) and are bounded like the wire metadata.
+ *
+ * SCOPE: a client-visible `call_id` is NOT unique across conversations, accounts, providers
+ * or models. Keying on it alone let one thread's signature overwrite another's, and let a
+ * lookup hand a signature from a different account's turn to the current one. The key is the
+ * same identity the in-process reasoning cache already uses — thread plus exact provider
+ * destination, adapter, model and credential — so a signature can only ever be replayed into
+ * the turn that produced it.
+ */
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { atomicWriteFileAsync, getConfigDir } from "../config";
+import type { OcxProviderOpaqueToolCallMetadata, OcxReasoningReplayScopeRef } from "../types";
+import { isCarryableSignature, responsesExtraContentFromProviderMetadata } from "./provider-opaque-metadata";
+
+const STORE_FILE_NAME = "thought-signature-replay.json";
+const SALT_FILE_NAME = "thought-signature-replay.salt";
+/**
+ * Bumped whenever `keyFor` changes shape. v3 added the durable destination identity; v4
+ * added the salted durable credential identity (#1926), so a v3 file's keys can never
+ * match and are dropped on load instead of aging out invisibly. v3 rows carried no
+ * credential information, so they are not upgradable — the next Gemini turn re-accumulates
+ * its signatures (bounded, best-effort loss identical to the pre-store status quo).
+ */
+const STORE_VERSION = 4;
+
+/** Bound on remembered entries; real signatures are a few hundred bytes, so this stays small. */
+const MAX_ENTRIES = 16_384;
+/**
+ * Total bytes of remembered signature material.
+ *
+ * An entry count alone is not a memory bound: a single signature may be 64KiB, so 16,384
+ * entries is a ~1GiB ceiling. This is the bound that actually holds.
+ */
+const MAX_TOTAL_BYTES = 32 * 1024 * 1024;
+/** A signature is needed for the immediate next turn; a long TTL also covers resumed threads. */
+const TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+type StoredEntry = { sig: string; savedAt: number };
+
+/** Outcome of a remember attempt. `conflict` is a real signal, not a no-op. */
+export type ThoughtSignatureRememberResult =
+  | "stored"
+  | "already-equal"
+  | "conflict"
+  | "unscoped"
+  | "ignored";
+
+let entries = new Map<string, StoredEntry>();
+let totalBytes = 0;
+let loaded = false;
+let persistChain: Promise<void> = Promise.resolve();
+
+function storePath(): string {
+  return join(getConfigDir(), STORE_FILE_NAME);
+}
+
+function saltPath(): string {
+  return join(getConfigDir(), SALT_FILE_NAME);
+}
+
+let cachedSalt: Buffer | undefined;
+let saltLoaded = false;
+
+/**
+ * Installation-local salt for the durable credential identity (#1926). Created once and
+ * persisted beside the store; losing it invalidates every stored key (the entries then
+ * never match and age out), which is safe — signatures re-accumulate per turn.
+ */
+export function thoughtSignatureReplaySalt(): Buffer | undefined {
+  if (saltLoaded) return cachedSalt;
+  saltLoaded = true;
+  try {
+    const raw = readFileSync(saltPath());
+    if (raw.length >= 16) {
+      // Re-assert owner-only permissions on every load: a pre-existing file may have
+      // been created before this guard or loosened by external tooling.
+      try { chmodSync(saltPath(), 0o600); } catch { /* best effort on exotic filesystems */ }
+      cachedSalt = raw;
+      return cachedSalt;
+    }
+  } catch {
+    // fall through to mint
+  }
+  try {
+    const minted = randomBytes(32);
+    writeFileSync(saltPath(), minted, { mode: 0o600 });
+    cachedSalt = minted;
+  } catch {
+    // Unwritable config dir: no durable credential identity this process; the durable
+    // store fails closed (keyFor returns undefined) rather than keying under a shared id.
+    cachedSalt = undefined;
+  }
+  return cachedSalt;
+}
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Durable key for one call, or `undefined` when the scope is incomplete.
+ *
+ * Incomplete scope means "do not remember" rather than "remember globally": a partially
+ * identified entry is exactly the cross-thread collision this store exists to prevent.
+ * The reasoning cache's identities are process-local HMACs, so this key deliberately uses
+ * only the stable, non-secret fields that survive a restart.
+ */
+function keyFor(callId: string, scope: OcxReasoningReplayScopeRef | undefined): string | undefined {
+  const identity = scope?.current;
+  if (
+    !nonEmpty(callId)
+    || !nonEmpty(scope?.clientThreadId)
+    || !nonEmpty(identity?.providerName)
+    || !nonEmpty(identity?.adapterName)
+    || !nonEmpty(identity?.modelId)
+    // v4 (#1926): a missing durable credential identity means we cannot isolate this
+    // entry per credential across restarts. Refusing the key is the fail-closed choice —
+    // "credential:unknown" would let two different credentials share one durable slot.
+    || !nonEmpty(identity?.credentialDurableIdentity)
+  ) return undefined;
+  return JSON.stringify([
+    scope.clientThreadId,
+    identity.providerName,
+    // Destination, unlike the credential identity, has a restart-stable form: it is a
+    // configured endpoint rather than a secret, so a plain digest works where the
+    // reasoning cache's randomBytes-keyed HMAC cannot. Without it, one provider NAME
+    // serving two endpoints shares signatures across both.
+    identity.providerDestinationDurableIdentity ?? "destination:unknown",
+    identity.credentialDurableIdentity,
+    identity.adapterName,
+    identity.modelId,
+    callId,
+  ]);
+}
+
+function load(): void {
+  if (loaded) return;
+  loaded = true;
+  let raw: string;
+  try {
+    raw = readFileSync(storePath(), "utf8");
+  } catch {
+    return; // First run or unreadable file: start empty.
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || !Array.isArray((parsed as { entries?: unknown }).entries)) {
+      return;
+    }
+    // The version was written but never read, so a key-shape change could not be
+    // announced — old entries simply went dead and aged out on TTL, which is silent and
+    // indistinguishable from a store that is not working. Reading it makes a shape change
+    // an explicit drop: entries keyed by an older scheme are discarded on load rather than
+    // lingering as permanent misses.
+    if ((parsed as { version?: unknown }).version !== STORE_VERSION) return;
+    const nowMs = Date.now();
+    for (const entry of (parsed as { entries: unknown[] }).entries) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const { key, sig, savedAt } = entry as { key?: unknown; sig?: unknown; savedAt?: unknown };
+      if (typeof key !== "string" || typeof sig !== "string" || typeof savedAt !== "number") continue;
+      if (savedAt <= nowMs - TTL_MS) continue;
+      if (!isCarryableSignature(sig)) continue;
+      entries.set(key, { sig, savedAt });
+      totalBytes += sig.length;
+    }
+  } catch {
+    // Corrupt store: ignore it; a later remember() rewrites a clean snapshot.
+  }
+  // A loaded snapshot can already exceed the bounds if they were lowered, so enforce them
+  // here rather than waiting for the next write.
+  prune(Date.now());
+}
+
+function prune(nowMs: number): void {
+  for (const [key, entry] of entries) {
+    if (nowMs - entry.savedAt > TTL_MS) {
+      entries.delete(key);
+      totalBytes -= entry.sig.length;
+    }
+  }
+  if (entries.size <= MAX_ENTRIES && totalBytes <= MAX_TOTAL_BYTES) return;
+  const sorted = [...entries.entries()].sort((a, b) => a[1].savedAt - b[1].savedAt);
+  for (const [key, entry] of sorted) {
+    if (entries.size <= MAX_ENTRIES && totalBytes <= MAX_TOTAL_BYTES) break;
+    entries.delete(key);
+    totalBytes -= entry.sig.length;
+  }
+}
+
+function persist(): Promise<void> {
+  persistChain = persistChain
+    .then(async () => {
+      const snapshot = JSON.stringify({
+        version: STORE_VERSION,
+        entries: [...entries].map(([key, entry]) => ({ key, sig: entry.sig, savedAt: entry.savedAt })),
+      });
+      await atomicWriteFileAsync(storePath(), snapshot);
+    })
+    .catch(() => {
+      // Best-effort persistence: the in-memory store still serves the running process.
+    });
+  return persistChain;
+}
+
+/**
+ * Record the signature that left the proxy on a function-call response item.
+ *
+ * Returns the outcome so a caller can await durability before exposing the item, and so a
+ * genuine conflict is observable instead of silently overwriting. A different signature under
+ * the SAME complete key means two different upstream turns claimed one identity: that is a
+ * corruption signal, and keeping the first value is the fail-closed choice.
+ */
+export function rememberThoughtSignatureForReplay(
+  callId: string,
+  signature: string,
+  scope: OcxReasoningReplayScopeRef | undefined,
+): { result: ThoughtSignatureRememberResult; durable: Promise<void> } {
+  if (!callId || !isCarryableSignature(signature)) {
+    return { result: "ignored", durable: Promise.resolve() };
+  }
+  const key = keyFor(callId, scope);
+  if (key === undefined) return { result: "unscoped", durable: Promise.resolve() };
+  load();
+  const existing = entries.get(key);
+  if (existing) {
+    if (existing.sig === signature) return { result: "already-equal", durable: Promise.resolve() };
+    return { result: "conflict", durable: Promise.resolve() };
+  }
+  entries.set(key, { sig: signature, savedAt: Date.now() });
+  totalBytes += signature.length;
+  prune(Date.now());
+  return { result: "stored", durable: persist() };
+}
+
+/**
+ * Serialize provider metadata onto an outbound Responses function_call item AND remember the
+ * signature server-side, so a client that replays the call without echoing extra_content can
+ * still be served from the store.
+ */
+export function rememberAndSerializeExtraContent(
+  callId: string,
+  metadata: OcxProviderOpaqueToolCallMetadata | undefined,
+  scope: OcxReasoningReplayScopeRef | undefined,
+): {
+  extra?: { extra_content: { google: { thought_signature: string } } };
+  durable: Promise<void>;
+} {
+  const extra = responsesExtraContentFromProviderMetadata(metadata);
+  if (!extra) return { durable: Promise.resolve() };
+  const { durable } = rememberThoughtSignatureForReplay(
+    callId,
+    extra.extra_content.google.thought_signature,
+    scope,
+  );
+  return { extra, durable };
+}
+
+/**
+ * Remember the signature without serializing it onto the item. Used for freeform tools, whose
+ * Responses items are custom_tool_call blocks that cannot carry extra_content — the signature
+ * still must be stored so the replayed call (which comes back as custom_tool_call and never
+ * echoes metadata) can be re-signed server-side.
+ */
+export function rememberExtraContentForReplay(
+  callId: string,
+  metadata: OcxProviderOpaqueToolCallMetadata | undefined,
+  scope: OcxReasoningReplayScopeRef | undefined,
+): Promise<void> {
+  const extra = responsesExtraContentFromProviderMetadata(metadata);
+  if (!extra) return Promise.resolve();
+  return rememberThoughtSignatureForReplay(
+    callId,
+    extra.extra_content.google.thought_signature,
+    scope,
+  ).durable;
+}
+
+/** Look up a signature previously handed out for this call in THIS scope, if still fresh. */
+export function lookupReplayThoughtSignature(
+  callId: string,
+  scope: OcxReasoningReplayScopeRef | undefined,
+): string | undefined {
+  const key = keyFor(callId, scope);
+  if (key === undefined) return undefined;
+  load();
+  const entry = entries.get(key);
+  if (!entry) return undefined;
+  if (Date.now() - entry.savedAt > TTL_MS) {
+    entries.delete(key);
+    totalBytes -= entry.sig.length;
+    return undefined;
+  }
+  return entry.sig;
+}
+
+/** Drop a remembered signature for a specific callId and scope (e.g. when upstream rejects it). */
+export function forgetThoughtSignatureForReplay(
+  callId: string,
+  scope: OcxReasoningReplayScopeRef | undefined,
+): boolean {
+  const key = keyFor(callId, scope);
+  if (key === undefined) return false;
+  load();
+  const entry = entries.get(key);
+  if (!entry) return false;
+  entries.delete(key);
+  totalBytes -= entry.sig.length;
+  prune(Date.now());
+  void persist();
+  return true;
+}
+
+/** Test seams: clear in-memory state and the loaded flag without touching the file. */
+export function resetThoughtSignatureReplayForTests(): void {
+  entries = new Map();
+  totalBytes = 0;
+  loaded = false;
+  persistChain = Promise.resolve();
+  cachedSalt = undefined;
+  saltLoaded = false;
+}
+
+export function thoughtSignatureReplayCountForTests(): number {
+  return entries.size;
+}
+
+/** Test seam: resolve after the queued snapshot write settles. */
+export function flushThoughtSignatureReplayForTests(): Promise<void> {
+  return persistChain;
+}
+
+/**
+ * Bounded commit barrier (#1926 gap 2). All durable writes serialize onto
+ * `persistChain`, so awaiting it (with a cap) before a turn's terminal frame becomes
+ * externally visible bounds the restart window in which a handed-out signature could
+ * be lost. Bounded BEST EFFORT: on timeout the turn proceeds — availability wins, and
+ * the miss cost is one turn's re-accumulation (the pre-store status quo). The
+ * in-memory map is updated synchronously at remember() time, so within one process
+ * lifetime replay never races this barrier at all.
+ */
+export function awaitThoughtSignatureDurability(capMs = 250): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const cap = new Promise<void>(resolve => {
+    timer = setTimeout(resolve, capMs);
+  });
+  return Promise.race([persistChain, cap]).then(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  });
+}

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;
+}