@iislee/opencodex 2.11.0 → 2.35.0

package/src/responses/parser.ts

@@ -9,23 +9,43 @@ import type {
   OcxThinkingContent,
   OcxTool,
   OcxToolCall,
+  OcxReasoningReplayScopeRef,
 } from "../types";
-import { namespacedToolName } from "../types";
+import { createToolChoiceResolver, namespacedToolName } from "../types";
 import { responsesRequestSchema } from "./schema";
-import { compactionItemToText } from "./compaction";
+import { providerMetadataFromResponsesFunctionCall } from "./provider-opaque-metadata";
+import { lookupReplayThoughtSignature } from "./thought-signature-replay";
+import { compactionItemToText, isCompactionItemType } from "./compaction";
 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);
 }
 
+/**
+ * Wrap a remembered proxy-side signature as provider metadata for a replayed tool call.
+ *
+ * The scope is REQUIRED for a hit. `parseRequest` runs before the route and account are
+ * chosen, so a caller that has not yet bound a replay scope gets nothing rather than a
+ * signature belonging to some other thread that happened to reuse the same `call_id`.
+ */
+function replayThoughtSignatureMetadata(
+  callId: string,
+  scope: OcxReasoningReplayScopeRef | undefined,
+): { google: { thoughtSignature: string } } | undefined {
+  const signature = lookupReplayThoughtSignature(callId, scope);
+  return signature ? { google: { thoughtSignature: signature } } : undefined;
+}
+
 type InputBlock =
   | { type: "input_text"; text: string }
   | { type: "text"; text: string }
   | { type: "input_image"; image_url?: string; file_id?: string; detail?: string }
+  | { type: "input_video"; video_url?: string }
   | { type: "input_file"; file_id?: string; filename?: string; file_data?: string };
 
 /** A usable reference string, or undefined. Empty strings and non-strings are not references. */
@@ -61,6 +81,9 @@ function inputContentParts(blocks: unknown): string | OcxContentPart[] {
       }
       // No usable reference: omit the block. A "[image: ?]" marker would claim an attachment
       // the request never carried, which is worse than dropping malformed input.
+    } else if (block.type === "input_video") {
+      const videoUrl = nonEmptyString(block.video_url);
+      if (videoUrl) parts.push({ type: "video", videoUrl });
     } else if (block.type === "input_file") {
       const b = block as { file_id?: string; filename?: string; file_data?: string };
       const fileId = nonEmptyString(b.file_id);
@@ -151,43 +174,53 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
     if (namespace) tool.namespace = namespace;
     out.push(tool);
   };
+  const pushCustom = (t: Record<string, unknown>, namespace?: string) => {
+    // Freeform custom tools are lowered to a single string `input` because chat models cannot
+    // emit Responses grammar payloads directly. Keep tool-specific input guidance scoped to the
+    // tool that owns it: leaking apply_patch syntax into `exec` or another freeform tool teaches
+    // routed models that the nested helper name is itself a callable top-level tool.
+    const inputDescription = t.name === "apply_patch"
+      ? "Raw tool input. For apply_patch, begin exactly with `*** Begin Patch` (no trailing `***`), then use its standard patch envelope."
+      : "Raw freeform input for this tool.";
+    const tool: OcxTool = {
+      name: t.name as string,
+      description: (t.description as string) ?? "",
+      parameters: { type: "object", properties: { input: { type: "string", description: inputDescription } }, required: ["input"] },
+      freeform: true,
+    };
+    if (namespace) tool.namespace = namespace;
+    out.push(tool);
+  };
   for (const t of tools) {
     if (!isObj(t)) continue;
+    if (t.type === "function" && isObj(t.function) && typeof t.function.name === "string" && t.function.name.length > 0) {
+      pushFn(t.function as Record<string, unknown>);
+      continue;
+    }
     if (t.type === "function" && typeof t.name === "string") {
       pushFn(t);
     } else if (t.type === "namespace" && Array.isArray(t.tools)) {
-      // MCP tools arrive grouped under a namespace tool; flatten the inner function tools so
-      // chat-completions models receive them (round-trip restores the namespace in the bridge).
-      const ns = typeof t.name === "string" ? t.name : undefined;
+      // Codex 0.147 groups its ordinary client tools under the reserved `functions` namespace,
+      // including freeform custom tools such as code-mode `exec`. Those children are still
+      // top-level Responses tools, so flatten them without a namespace. Other namespace groups
+      // are MCP-style and keep their namespace for round-trip routing.
+      const builtinFunctions = t.name === "functions";
+      const ns = typeof t.name === "string" && !builtinFunctions ? t.name : undefined;
       for (const inner of t.tools as unknown[]) {
         if (isObj(inner) && inner.type === "function" && typeof inner.name === "string") pushFn(inner, ns);
+        else if (isObj(inner) && inner.type === "custom" && typeof inner.name === "string") pushCustom(inner, ns);
       }
     }
     else if (t.type === "custom" && typeof t.name === "string") {
-      // Freeform custom tool (e.g. apply_patch). Chat models can't emit a lark grammar, so expose a
-      // function with a single string `input` carrying the raw tool body; the bridge relays the model's
-      // call back as a custom_tool_call (Codex's freeform handler rejects a function_call → fatal abort).
-      out.push({
-        name: t.name,
-        description: (t.description as string) ?? "",
-        parameters: { type: "object", properties: { input: { type: "string", description: "Raw tool input. For apply_patch, begin exactly with `*** Begin Patch` (no trailing `***`), then use its standard patch envelope." } }, required: ["input"] },
-        freeform: true,
-      });
+      pushCustom(t);
     }
     else if (t.type === "tool_search") {
       // Client-executed tool discovery — the gateway to deferred tools (subagents, extra MCP tools).
       // 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,
       });
     }
@@ -263,9 +296,70 @@ function findToolById(messages: OcxMessage[], callId: string): { name: string; n
   return { name: "" };
 }
 
+/**
+ * Attach pending reasoning to the assistant turn that owns the given call id.
+ * Reconstructed histories (resume/retry/synthetic) can order a `reasoning`
+ * item AFTER the `function_call` it belongs to; without this, the pending
+ * buffer is cleared at the tool output and the turn serializes without
+ * `reasoning_content`, which DeepSeek thinking mode rejects with HTTP 400
+ * (issue #950).
+ */
+function attachPendingReasoningToCallOwner(
+  messages: OcxMessage[],
+  callId: string,
+  pendingReasoning: Array<{ part: OcxThinkingContent; envelopeSigned: boolean }>,
+): void {
+  if (pendingReasoning.length === 0 || !callId) return;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.role !== "assistant") continue;
+    for (const part of m.content) {
+      if (part.type === "toolCall" && part.id === callId) {
+        // Prepend so thinking still precedes tool_use for adapters that require
+        // that ordering (Anthropic-style replay).
+        m.content = [...pendingReasoning.map(entry => entry.part), ...m.content];
+        return;
+      }
+    }
+  }
+}
+
 const REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
-export function parseRequest(body: unknown): OcxParsedRequest {
+/**
+ * Namespace a custom tool was declared under, by its bare name.
+ *
+ * A `custom_tool_call` echoed back by the client carries only the bare name — the bridge
+ * emits `{"type":"custom_tool_call","name":"exec"}` even when the tool was declared as
+ * `mcp__functions__exec`. Without this lookup the namespace is lost on the return trip,
+ * and the adapters replay history through `namespacedToolName(namespace, name)`, which
+ * then produces a bare `exec` the provider may not have. Ordinary `function_call` items
+ * do not need this: they carry `namespace` on the wire.
+ */
+function customToolNamespaces(tools: unknown): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!Array.isArray(tools)) return out;
+  for (const spec of tools) {
+    if (!isObj(spec) || spec.type !== "namespace" || !Array.isArray(spec.tools)) continue;
+    const namespace = typeof spec.name === "string" ? spec.name : undefined;
+    // Codex 0.147 groups ordinary client tools under the reserved `functions` namespace and
+    // buildTools deliberately flattens those without a namespace. Mirror that here, or the
+    // reconstruction would invent a namespace the request never advertised.
+    if (!namespace || namespace === "functions") continue;
+    for (const inner of spec.tools) {
+      if (!isObj(inner) || inner.type !== "custom" || typeof inner.name !== "string") continue;
+      // Ambiguous bare names are already rejected upstream, so first declaration wins.
+      if (!out.has(inner.name)) out.set(inner.name, namespace);
+    }
+  }
+  return out;
+}
+
+export function parseRequest(
+  body: unknown,
+  parseOptions?: { replayCacheScope?: OcxReasoningReplayScopeRef },
+): OcxParsedRequest {
+  const replayCacheScope = parseOptions?.replayCacheScope;
   const replayedInputPrefixLength = previousResponseReplayPrefixLength(body);
   const parsed = responsesRequestSchema.safeParse(body);
   if (!parsed.success) {
@@ -274,6 +368,9 @@ export function parseRequest(body: unknown): OcxParsedRequest {
   const data = parsed.data;
   const now = Date.now();
   const messages: OcxMessage[] = [];
+  // Built before the item loop: a custom_tool_call echoed back in `input` needs the
+  // namespace from the request's own tool catalog to survive the round trip.
+  const customToolNamespacesByName = customToolNamespaces(data.tools);
   const systemPrompt: string[] = [];
   // Responses reasoning siblings belong to the following assistant, including across call items.
   // Keep them off the message list until that assistant arrives; turn boundaries clear the array.
@@ -296,17 +393,33 @@ export function parseRequest(body: unknown): OcxParsedRequest {
   // synthetic `{type:"compaction"}` output item (src/responses/compaction.ts). Flagged for the server.
   let compactionRequest = false;
   let contextCompactionBoundary = false;
+  let continuationConversationMessageIndex: number | undefined;
 
   if (typeof data.instructions === "string" && data.instructions.length > 0) {
     systemPrompt.push(data.instructions);
   }
 
   if (typeof data.input === "string") {
+    if (data.previous_response_id) continuationConversationMessageIndex = messages.length;
     messages.push({ role: "user", content: data.input, timestamp: now });
   } else if (data.input) {
     for (let inputIndex = 0; inputIndex < data.input.length; inputIndex++) {
       const item = data.input[inputIndex];
       const effectiveType = (item as { type?: string }).type ?? ("role" in item ? "message" : undefined);
+      const itemRole = (item as { role?: string }).role;
+      // Raw protocol items do not map one-to-one onto context messages. Capture the boundary while
+      // both representations are available so later metadata can stay before conversation in both.
+      if (
+        data.previous_response_id
+        && inputIndex >= replayedInputPrefixLength
+        && continuationConversationMessageIndex === undefined
+        && (
+          effectiveType === "agent_message"
+          || (effectiveType === "message" && (itemRole === "user" || itemRole === "assistant"))
+        )
+      ) {
+        continuationConversationMessageIndex = messages.length;
+      }
 
       if (effectiveType === "compaction_trigger") {
         compactionRequest = true;
@@ -325,7 +438,7 @@ export function parseRequest(body: unknown): OcxParsedRequest {
         continue;
       }
 
-      if (effectiveType === "compaction" || effectiveType === "compaction_summary" || effectiveType === "context_compaction") {
+      if (isCompactionItemType(effectiveType)) {
         // A stored summary from a previous compaction. Decode our ocx1 envelope into plain text so
         // the routed model keeps the compacted context; real OpenAI-encrypted blobs degrade to a note.
         // `context_compaction` (encrypted_content optional) is codex-rs's local-compaction marker;
@@ -416,6 +529,18 @@ export function parseRequest(body: unknown): OcxParsedRequest {
           : null;
         const thinkingText = envelope?.txt || text;
 
+        // Kiro reasoning round-trip: a krc-only item carries nothing renderable — it is provider
+        // state for the assistant turn that ALREADY closed, because Kiro emits its
+        // reasoningContentEvent at the END of a turn (after content AND tool calls, verified
+        // against kiro-cli 2.14.1/2.16.0). Folding it into the FOLLOWING turn like ordinary
+        // reasoning would attach turn N's blob to turn N+1, so attach it backwards instead. With
+        // no assistant turn to own it the blob is dropped rather than mis-paired.
+        if (envelope?.krc && thinkingText.length === 0) {
+          const previous = messages[messages.length - 1];
+          if (previous?.role === "assistant") previous.kiroRedactedReasoning = envelope.krc;
+          continue;
+        }
+
         // Native/non-ocxr1 encrypted-only reasoning is opaque here. Do not create a detached
         // assistant turn or invent replayable plaintext/signatures from the encrypted payload.
         if (thinkingText.length > 0) {
@@ -442,7 +567,7 @@ export function parseRequest(body: unknown): OcxParsedRequest {
       }
 
       if (effectiveType === "function_call") {
-        const call = item as { id?: string; call_id: string; name: string; arguments?: string; namespace?: string };
+        const call = item as { id?: string; call_id: string; name: string; arguments?: string; namespace?: string; extra_content?: unknown };
         // Tolerate empty/non-JSON arguments (e.g. a no-arg tool call serialized as "") instead of
         // throwing — a single poisoned history item would otherwise 400 every subsequent turn.
         let args: Record<string, unknown> = {};
@@ -463,16 +588,32 @@ export function parseRequest(body: unknown): OcxParsedRequest {
           type: "toolCall", id: call.call_id, name: call.name, arguments: args,
           ...(call.namespace ? { namespace: call.namespace } : {}),
         };
+        // Provider-opaque metadata (e.g. a Gemini thought signature) travels with the call so a
+        // history-replayed or previous_response_id turn rebuilds the same signed part instead of
+        // depending on the same-process replay cache (issue #1735). Real clients do not echo
+        // extra_content on replay, so fall back to the proxy-side store keyed by call_id.
+        const providerMetadata = providerMetadataFromResponsesFunctionCall(call)
+          ?? (typeof call.call_id === "string"
+            ? replayThoughtSignatureMetadata(call.call_id, replayCacheScope)
+            : undefined);
+        if (providerMetadata) toolCall.providerMetadata = providerMetadata;
         assistantHolderWithReasoning().content.push(toolCall);
         continue;
       }
 
       if (effectiveType === "custom_tool_call") {
         const call = item as { id?: string; call_id: string; name: string; input: string };
+        const remembered = typeof call.call_id === "string" ? replayThoughtSignatureMetadata(call.call_id, replayCacheScope) : undefined;
+        // Reconstruct the namespace the request declared this tool under. The wire item
+        // carries only the bare name, so without this the round trip loses it and adapters
+        // replay the call as an unnamespaced tool the provider may not expose.
+        const customNamespace = customToolNamespacesByName.get(call.name);
         const toolCall: OcxToolCall = {
           type: "toolCall", id: call.call_id, name: call.name,
           arguments: { input: call.input ?? "" },
           customWireName: call.name,
+          ...(customNamespace ? { namespace: customNamespace } : {}),
+          ...(remembered ? { providerMetadata: remembered } : {}),
         };
         assistantHolderWithReasoning().content.push(toolCall);
         continue;
@@ -485,9 +626,11 @@ export function parseRequest(body: unknown): OcxParsedRequest {
         const callId = call.call_id ?? call.id;
         if (callId) {
           const command = Array.isArray(call.action?.command) ? call.action.command : [];
+          const remembered = replayThoughtSignatureMetadata(callId, replayCacheScope);
           assistantHolderWithReasoning().content.push({
             type: "toolCall", id: callId, name: "shell",
             arguments: command.length > 0 ? { command } : {},
+            ...(remembered ? { providerMetadata: remembered } : {}),
           });
         }
         continue;
@@ -506,9 +649,11 @@ export function parseRequest(body: unknown): OcxParsedRequest {
         // history stays complete (otherwise the model re-issues tool_search forever).
         const call = item as { id?: string; call_id?: string; arguments?: unknown };
         const callId = call.call_id ?? call.id ?? "";
+        const remembered = callId ? replayThoughtSignatureMetadata(callId, replayCacheScope) : undefined;
         assistantHolderWithReasoning().content.push({
           type: "toolCall", id: callId, name: "tool_search",
           arguments: isObj(call.arguments) ? call.arguments : {},
+          ...(remembered ? { providerMetadata: remembered } : {}),
         });
         continue;
       }
@@ -545,8 +690,9 @@ export function parseRequest(body: unknown): OcxParsedRequest {
       }
 
       if (effectiveType === "function_call_output") {
-        pendingReasoning.length = 0;
         const output = item as { call_id: string; output?: string | unknown[] };
+        attachPendingReasoningToCallOwner(messages, output.call_id, pendingReasoning);
+        pendingReasoning.length = 0;
         const toolInfo = findToolById(messages, output.call_id);
         messages.push({
           role: "toolResult", toolCallId: output.call_id,
@@ -558,8 +704,9 @@ export function parseRequest(body: unknown): OcxParsedRequest {
       }
 
       if (effectiveType === "custom_tool_call_output") {
-        pendingReasoning.length = 0;
         const output = item as { call_id: string; output: string | unknown[] };
+        attachPendingReasoningToCallOwner(messages, output.call_id, pendingReasoning);
+        pendingReasoning.length = 0;
         const toolInfo = findToolById(messages, output.call_id);
         messages.push({
           role: "toolResult", toolCallId: output.call_id,
@@ -572,10 +719,22 @@ export function parseRequest(body: unknown): OcxParsedRequest {
       }
     }
   }
+  if (data.previous_response_id && continuationConversationMessageIndex === undefined) {
+    continuationConversationMessageIndex = messages.length;
+  }
 
   const declaredTools = buildTools(data.tools as unknown[] | undefined) ?? [];
   const loadedTools = buildTools(loadedToolSpecs) ?? [];
   const loadedToolNames = new Set(loadedTools.map(t => namespacedToolName(t.namespace, t.name)));
+  const wireOwners = new Map<string, OcxTool>();
+  for (const tool of [...declaredTools, ...loadedTools]) {
+    const wireName = namespacedToolName(tool.namespace, tool.name);
+    const previous = wireOwners.get(wireName);
+    if (previous && (previous.namespace !== tool.namespace || previous.name !== tool.name || previous.freeform !== tool.freeform || previous.toolSearch !== tool.toolSearch)) {
+      throw new Error(`ambiguous tool catalog: multiple logical tools map to wire name ${wireName}`);
+    }
+    wireOwners.set(wireName, tool);
+  }
   const seenTools = new Set<string>();
   const mergedTools = [...declaredTools, ...loadedTools]
     .filter(t => {
@@ -601,6 +760,15 @@ export function parseRequest(body: unknown): OcxParsedRequest {
     options.stopSequences = typeof data.stop === "string" ? [data.stop] : data.stop;
   }
   const tc = mapToolChoice(data.tool_choice);
+  if (tc && typeof tc === "object") {
+    const selectors = "allowedTools" in tc ? tc.allowedTools : [tc.name];
+    const resolver = createToolChoiceResolver(mergedTools);
+    for (const selector of selectors) {
+      if (resolver.candidateCount(selector) > 1) {
+        throw new Error(`ambiguous tool_choice name: ${selector}`);
+      }
+    }
+  }
   if (tc !== undefined) options.toolChoice = tc;
   if (data.parallel_tool_calls !== undefined) options.parallelToolCalls = data.parallel_tool_calls;
   // Upstream codex-rs converts "ultra" to "max" at the inference boundary (core/src/client.rs
@@ -626,9 +794,12 @@ export function parseRequest(body: unknown): OcxParsedRequest {
     ...(data.tools as unknown[] ?? []),
     ...loadedToolSpecs,
   ]);
-  // Detect structured-output mode (Responses `text.format`) so the web-search sidecar can render its
-  // tool_result as JSON rather than prose that could corrupt the model's schema-constrained answer.
-  const structuredOutput = detectStructuredOutput(data.text);
+  // Capture structured-output mode (Responses `text.format`): the format object rides
+  // options.textFormat for adapters whose wire has an equivalent (openai-chat response_format),
+  // while the `_structuredOutput` flag keeps the web-search sidecar rendering its tool_result
+  // as JSON rather than prose that could corrupt the model's schema-constrained answer.
+  const textFormat = parseTextFormat(data.text);
+  if (textFormat) options.textFormat = textFormat;
 
   return {
     modelId: data.model,
@@ -638,19 +809,35 @@ export function parseRequest(body: unknown): OcxParsedRequest {
     options,
     _rawBody: body,
     ...(replayedInputPrefixLength > 0 ? { _replayPrefixLen: replayedInputPrefixLength } : {}),
+    ...(continuationConversationMessageIndex !== undefined
+      ? { _continuationConversationMessageIndex: continuationConversationMessageIndex }
+      : {}),
     ...(webSearch ? { _webSearch: webSearch } : {}),
     ...(imageGen ? { _imageGeneration: imageGen } : {}),
-    ...(structuredOutput ? { _structuredOutput: true } : {}),
+    ...(textFormat ? { _structuredOutput: true } : {}),
     ...(compactionRequest ? { _compactionRequest: true } : {}),
     ...(contextCompactionBoundary ? { _contextCompactionBoundary: true } : {}),
   };
 }
 
-/** True when the Responses `text.format` requests structured output (json_schema or json_object). */
-function detectStructuredOutput(text: unknown): boolean {
-  if (!isObj(text)) return false;
+/**
+ * The Responses `text.format` object when it requests structured output (json_schema or
+ * json_object), undefined otherwise. Acceptance is identical to the boolean detector this
+ * replaces; unknown or malformed formats are ignored, never rejected, so the native
+ * passthrough keeps forwarding whatever the caller sent via `_rawBody`.
+ */
+function parseTextFormat(text: unknown): OcxRequestOptions["textFormat"] {
+  if (!isObj(text)) return undefined;
   const format = (text as { format?: unknown }).format;
-  if (!isObj(format)) return false;
-  const t = (format as { type?: unknown }).type;
-  return t === "json_schema" || t === "json_object";
+  if (!isObj(format)) return undefined;
+  const f = format as { type?: unknown; name?: unknown; description?: unknown; schema?: unknown; strict?: unknown };
+  if (f.type === "json_object") return { type: "json_object" };
+  if (f.type !== "json_schema") return undefined;
+  return {
+    type: "json_schema",
+    ...(typeof f.name === "string" ? { name: f.name } : {}),
+    ...(typeof f.description === "string" ? { description: f.description } : {}),
+    ...(isObj(f.schema) ? { schema: f.schema as Record<string, unknown> } : {}),
+    ...(typeof f.strict === "boolean" ? { strict: f.strict } : {}),
+  };
 }

package/src/responses/provider-continuation.ts

@@ -0,0 +1,98 @@
+import type {
+  OcxProviderContinuationOwner,
+  OcxReasoningReplayIdentity,
+} from "../types";
+
+const bounded = (value: unknown, max: number): value is string =>
+  typeof value === "string" && value.length > 0 && value.length <= max;
+
+const isPlainRecord = (value: unknown): value is Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+const defineOwn = (target: Record<string, unknown>, key: string, value: unknown): void => {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  });
+};
+
+/** Recursively merge provider-owned plain objects; arrays and scalar values replace prior state. */
+export function mergeProviderContinuationPayload(
+  inherited: Readonly<Record<string, unknown>>,
+  emitted: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(inherited)) defineOwn(merged, key, value);
+  for (const [key, value] of Object.entries(emitted)) {
+    const prior = Object.hasOwn(merged, key) ? merged[key] : undefined;
+    defineOwn(
+      merged,
+      key,
+      isPlainRecord(prior) && isPlainRecord(value)
+        ? mergeProviderContinuationPayload(prior, value)
+        : value,
+    );
+  }
+  return merged;
+}
+
+/** Validate proxy-authored continuation ownership before trusting persisted state. */
+export function isValidProviderContinuationOwner(
+  value: unknown,
+): value is OcxProviderContinuationOwner {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const owner = value as Record<string, unknown>;
+  return owner.version === 1
+    && bounded(owner.providerName, 256)
+    && typeof owner.providerDestinationIdentity === "string"
+    && /^destination:[0-9a-f]{64}$/.test(owner.providerDestinationIdentity)
+    && bounded(owner.adapterName, 128)
+    && bounded(owner.modelId, 512)
+    && typeof owner.credentialIdentity === "string"
+    && /^(key|oauth|codex):[0-9a-f]{64}$/.test(owner.credentialIdentity);
+}
+
+/** Reuse the exact process-local route identity already established for reasoning replay. */
+export function providerContinuationOwnerFromReplayIdentity(
+  identity: Readonly<OcxReasoningReplayIdentity> | undefined,
+): OcxProviderContinuationOwner | undefined {
+  if (!identity) return undefined;
+  const owner: OcxProviderContinuationOwner = {
+    version: 1,
+    providerName: identity.providerName,
+    providerDestinationIdentity: identity.providerDestinationIdentity,
+    adapterName: identity.adapterName,
+    modelId: identity.modelId,
+    credentialIdentity: identity.credentialIdentity,
+  };
+  return isValidProviderContinuationOwner(owner) ? owner : undefined;
+}
+
+export function sameProviderContinuationOwner(
+  left: OcxProviderContinuationOwner,
+  right: OcxProviderContinuationOwner,
+): boolean {
+  return left.version === right.version
+    && left.providerName === right.providerName
+    && left.providerDestinationIdentity === right.providerDestinationIdentity
+    && left.adapterName === right.adapterName
+    && left.modelId === right.modelId
+    && left.credentialIdentity === right.credentialIdentity;
+}
+
+/** Cursor hashes this non-secret namespace with the client thread id. */
+export function providerContinuationRouteScope(owner: OcxProviderContinuationOwner): string {
+  return JSON.stringify([
+    "provider-continuation-v1",
+    owner.providerName,
+    owner.providerDestinationIdentity,
+    owner.adapterName,
+    owner.modelId,
+    owner.credentialIdentity,
+  ]);
+}

package/src/responses/provider-opaque-metadata.ts

@@ -0,0 +1,73 @@
+/**
+ * Provider-opaque tool-call metadata across the Responses boundary (issue #1735).
+ *
+ * Gemini issues a `thoughtSignature` on the exact part that carries a function call, and the
+ * next request is only valid if that signature comes back on the part rebuilt from that same
+ * call. Every synthetic loop in this proxy (web search, images, continuation replay) tears a
+ * tool call down into id/name/arguments and builds a fresh one, which silently dropped the
+ * signature and left only the same-process replay cache to paper over it. History replay and
+ * `previous_response_id` had no cache to fall back on.
+ *
+ * This module is the single seam where that metadata crosses into and out of the Responses
+ * wire, so a loop that rebuilds a call only has to carry one field instead of knowing about
+ * any provider. Values are treated as opaque: never parsed, merged, re-encoded, or synthesized.
+ */
+import type { OcxProviderOpaqueToolCallMetadata } from "../types";
+
+/** Wire shape: `extra_content.google.thought_signature` on a Responses function_call item. */
+interface ResponsesExtraContent {
+  google?: { thought_signature?: unknown };
+}
+
+function isObj(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Same ceiling the Antigravity replay cache already enforces on a stored signature. An opaque
+ * token this large is not a real signature, and accepting it would let a caller push unbounded
+ * state through history replay.
+ */
+const MAX_SIGNATURE_BYTES = 64 * 1024;
+
+export function isCarryableSignature(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0) return false;
+  // Cheap length pre-check: UTF-8 is at most 3 bytes per UTF-16 code unit for the BMP, so this
+  // skips the encode for the overwhelmingly common short case.
+  if (value.length <= MAX_SIGNATURE_BYTES / 3) return true;
+  return Buffer.byteLength(value, "utf8") <= MAX_SIGNATURE_BYTES;
+}
+
+/** Read provider metadata off an inbound Responses function_call item. */
+export function providerMetadataFromResponsesFunctionCall(
+  item: { extra_content?: unknown } | undefined,
+): OcxProviderOpaqueToolCallMetadata | undefined {
+  const extra = item?.extra_content;
+  if (!isObj(extra)) return undefined;
+  const google = (extra as ResponsesExtraContent).google;
+  if (!isObj(google)) return undefined;
+  const signature = google.thought_signature;
+  if (!isCarryableSignature(signature)) return undefined;
+  return { google: { thoughtSignature: signature } };
+}
+
+/** Serialize provider metadata onto an outbound Responses function_call item. */
+export function responsesExtraContentFromProviderMetadata(
+  metadata: OcxProviderOpaqueToolCallMetadata | undefined,
+): { extra_content: { google: { thought_signature: string } } } | undefined {
+  const signature = metadata?.google?.thoughtSignature;
+  if (!isCarryableSignature(signature)) return undefined;
+  return { extra_content: { google: { thought_signature: signature } } };
+}
+
+/**
+ * Copy metadata for a rebuilt tool call. A signature belongs to one specific part, so a loop
+ * that fans one model response into several calls must copy per call and never share or merge.
+ */
+export function cloneProviderOpaqueToolCallMetadata(
+  metadata: OcxProviderOpaqueToolCallMetadata | undefined,
+): OcxProviderOpaqueToolCallMetadata | undefined {
+  const signature = metadata?.google?.thoughtSignature;
+  if (!isCarryableSignature(signature)) return undefined;
+  return { google: { thoughtSignature: signature } };
+}

package/src/responses/reasoning-envelope.ts

@@ -24,6 +24,12 @@ export interface ReasoningEnvelope {
    * so replay needs it even though the visible summary was suppressed.
    */
   txt?: string;
+  /**
+   * Kiro `reasoningContentEvent.redactedContent`: a KMS-encrypted reasoning blob that is opaque to
+   * the proxy. Kiro's own CLI replays it on the matching `assistantResponseMessage` to preserve
+   * model reasoning across turns, so it round-trips here the same way a signature does.
+   */
+  krc?: string;
 }
 
 export function encodeReasoningEnvelope(envelope: ReasoningEnvelope): string {
@@ -45,7 +51,9 @@ export function decodeReasoningEnvelope(encryptedContent: string): ReasoningEnve
     }
     const txt = (parsed as { txt?: unknown }).txt;
     if (typeof txt === "string" && txt.length > 0) envelope.txt = txt;
-    return envelope.sig || envelope.red || envelope.txt ? envelope : null;
+    const krc = (parsed as { krc?: unknown }).krc;
+    if (typeof krc === "string" && krc.length > 0) envelope.krc = krc;
+    return envelope.sig || envelope.red || envelope.txt || envelope.krc ? envelope : null;
   } catch {
     return null;
   }