@yansigit/opencodex 2.31.0

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

@@ -0,0 +1,60 @@
+/**
+ * Anthropic extended-thinking signature round-trip through Codex's `encrypted_content` slot.
+ *
+ * Anthropic requires the previous assistant turn's `thinking`/`redacted_thinking` blocks to be
+ * replayed VERBATIM (with their signatures) while extended thinking is enabled; a signature-less
+ * replay 400s ("Expected `thinking` or `redacted_thinking`, but found `tool_use`"). Codex round-trips
+ * whatever `encrypted_content` a reasoning output item carries (include: reasoning.encrypted_content
+ * is set whenever reasoning is on — codex-rs client.rs), so the proxy smuggles the real Anthropic
+ * signature (and any redacted blocks) inside a transparent `ocxr1:` + base64(JSON) envelope.
+ *
+ * Native OpenAI-encrypted blobs (no ocxr1 prefix) are left untouched by the decoder, and the
+ * passthrough scrub strips ocxr1 envelopes before native forwarding.
+ */
+
+export const OCX_REASONING_PREFIX = "ocxr1:";
+
+export interface ReasoningEnvelope {
+  /** Anthropic thinking-block signature (signature_delta), if captured. */
+  sig?: string;
+  /** Raw redacted_thinking block data payloads, order preserved. */
+  red?: string[];
+  /**
+   * Hidden thinking text (hideThinkingSummary providers): the signature signs this exact text,
+   * 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 {
+  return OCX_REASONING_PREFIX + Buffer.from(JSON.stringify(envelope), "utf-8").toString("base64");
+}
+
+/** Decode an ocxr1 envelope; returns null for native (OpenAI-encrypted) blobs or garbage. */
+export function decodeReasoningEnvelope(encryptedContent: string): ReasoningEnvelope | null {
+  if (!encryptedContent.startsWith(OCX_REASONING_PREFIX)) return null;
+  try {
+    const parsed: unknown = JSON.parse(Buffer.from(encryptedContent.slice(OCX_REASONING_PREFIX.length), "base64").toString("utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const obj = parsed as { sig?: unknown; red?: unknown };
+    const envelope: ReasoningEnvelope = {};
+    if (typeof obj.sig === "string") envelope.sig = obj.sig;
+    if (Array.isArray(obj.red)) {
+      const red = obj.red.filter((r): r is string => typeof r === "string");
+      if (red.length > 0) envelope.red = red;
+    }
+    const txt = (parsed as { txt?: unknown }).txt;
+    if (typeof txt === "string" && txt.length > 0) envelope.txt = txt;
+    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;
+  }
+}

package/src/responses/reasoning-replay-cache.ts

@@ -0,0 +1,426 @@
+/**
+ * In-process fallback store pairing raw reasoning text with the tool call it
+ * preceded (issue #950).
+ *
+ * DeepSeek thinking mode requires the assistant's original `reasoning_content`
+ * to be replayed on every continuation of a tool-call turn. The bridge records
+ * the raw reasoning here when it closes a reasoning block and a tool call
+ * follows; the openai-chat adapter re-attaches it when a `tool_calls`
+ * assistant message is about to serialize without thinking parts (compacted
+ * history, lost assistant turn, orphan-repaired tool results).
+ *
+ * Entries require a conversation identity in addition to the call id:
+ * provider-generated ids like `call_1` are not globally unique, so an
+ * unscoped process-wide key would let one conversation's reasoning bleed into
+ * another when ids collide (CodeRabbit P1 on #971).
+ *
+ * Privacy: entries hold reasoning text in memory only — never logged,
+ * serialized, or exported. Bounded by entry count, total bytes, and TTL, so a
+ * long-lived proxy cannot grow without limit.
+ */
+
+import { createHash, createHmac, randomBytes } from "node:crypto";
+import type {
+  OcxProviderConfig,
+  OcxReasoningReplayIdentity,
+  OcxReasoningReplayScopeRef,
+} from "../types";
+
+const MAX_ENTRIES = 64;
+const MAX_TOTAL_BYTES = 256 * 1024;
+const TTL_MS = 60 * 60 * 1000;
+const replayIdentityKey = randomBytes(32);
+const CREDENTIAL_HEADER_NAMES = new Set([
+  "authorization",
+  "api-key",
+  "chatgpt-account-id",
+  "cookie",
+  "openai-organization",
+  "openai-project",
+  "proxy-authorization",
+  "x-api-key",
+  "x-api-token",
+  "x-auth-token",
+  "x-goog-api-key",
+  "x-openai-organization",
+  "x-openai-project",
+]);
+
+interface CacheEntry {
+  text: string;
+  bytes: number;
+  at: number;
+}
+
+interface ServingIdentityEntry {
+  identity: string;
+  bytes: number;
+  at: number;
+}
+
+const entries = new Map<string, CacheEntry>();
+const servingIdentities = new Map<string, ServingIdentityEntry>();
+let totalBytes = 0;
+let servingIdentityTotalBytes = 0;
+let clockForTests: (() => number) | null = null;
+
+const now = (): number => clockForTests?.() ?? Date.now();
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+type ReasoningReplayIdentityTuple = readonly [string, string, string, string, string];
+
+function tupleForIdentity(
+  identity: Readonly<OcxReasoningReplayIdentity> | undefined,
+): ReasoningReplayIdentityTuple | undefined {
+  if (
+    !nonEmpty(identity?.providerName)
+    || !nonEmpty(identity?.providerDestinationIdentity)
+    || !nonEmpty(identity?.adapterName)
+    || !nonEmpty(identity?.modelId)
+    || !nonEmpty(identity?.credentialIdentity)
+  ) return undefined;
+  return [
+    identity.providerName,
+    identity.providerDestinationIdentity,
+    identity.adapterName,
+    identity.modelId,
+    identity.credentialIdentity,
+  ];
+}
+
+function tupleForServingIdentity(
+  identity: Readonly<OcxReasoningReplayIdentity> | undefined,
+): ReasoningReplayIdentityTuple | undefined {
+  if (
+    !nonEmpty(identity?.providerName)
+    || !nonEmpty(identity?.providerDestinationDurableIdentity)
+    || !nonEmpty(identity?.adapterName)
+    || !nonEmpty(identity?.modelId)
+    || !nonEmpty(identity?.credentialDurableIdentity)
+  ) return undefined;
+  return [
+    identity.providerName,
+    identity.providerDestinationDurableIdentity,
+    identity.adapterName,
+    identity.modelId,
+    identity.credentialDurableIdentity,
+  ];
+}
+
+function keyFor(callId: string, scope: OcxReasoningReplayScopeRef | undefined): string | undefined {
+  const identity = tupleForIdentity(scope?.current);
+  if (!nonEmpty(callId) || !nonEmpty(scope?.clientThreadId) || !identity) return undefined;
+  return JSON.stringify([
+    scope.clientThreadId,
+    ...identity,
+    callId,
+  ]);
+}
+
+function deleteServingIdentity(threadId: string): void {
+  const entry = servingIdentities.get(threadId);
+  if (!entry) return;
+  servingIdentities.delete(threadId);
+  servingIdentityTotalBytes -= entry.bytes;
+}
+
+function sweepExpiredServingIdentities(at: number): void {
+  for (const [threadId, entry] of servingIdentities) {
+    if (at - entry.at >= TTL_MS) deleteServingIdentity(threadId);
+  }
+}
+
+function servingIdentityFor(
+  scope: OcxReasoningReplayScopeRef | undefined,
+): { threadId: string; identity: string } | undefined {
+  const threadId = scope?.clientThreadId;
+  const identityTuple = tupleForServingIdentity(scope?.current);
+  if (!nonEmpty(threadId) || !identityTuple) return undefined;
+  return { threadId, identity: JSON.stringify(identityTuple) };
+}
+
+/**
+ * Compare this request's route with the last successfully serving route for its client thread.
+ * A live mismatch means replayed opaque reasoning was minted by another backend and must not be
+ * forwarded to this one. Comparison deliberately does not refresh or replace the recorded route:
+ * a failed candidate request did not serve the thread.
+ *
+ * Serving provenance uses restart-stable destination and credential dimensions so token
+ * generations and other volatile credential material cannot create false route changes. Missing
+ * durable identity, expired, or evicted state is deliberately unknown rather than a mismatch.
+ * This store is process-local, so a backend switch spanning a proxy restart is not detected.
+ */
+export function reasoningReplayServingIdentityChanged(
+  scope: OcxReasoningReplayScopeRef | undefined,
+): boolean {
+  const current = servingIdentityFor(scope);
+  if (!current) return false;
+  const at = now();
+  sweepExpiredServingIdentities(at);
+  const previous = servingIdentities.get(current.threadId);
+  return previous !== undefined && previous.identity !== current.identity;
+}
+
+/** Record the route only after it has successfully served the client thread. */
+export function commitReasoningReplayServingIdentity(
+  scope: OcxReasoningReplayScopeRef | undefined,
+): void {
+  const current = servingIdentityFor(scope);
+  if (!current) return;
+  const at = now();
+  sweepExpiredServingIdentities(at);
+  const previous = servingIdentities.get(current.threadId);
+  const { threadId, identity } = current;
+  const bytes = Buffer.byteLength(JSON.stringify([threadId, identity]), "utf8");
+  if (bytes > MAX_TOTAL_BYTES) {
+    deleteServingIdentity(threadId);
+    return;
+  }
+
+  if (previous) deleteServingIdentity(threadId);
+  servingIdentities.set(threadId, { identity, bytes, at });
+  servingIdentityTotalBytes += bytes;
+  while (
+    (servingIdentityTotalBytes > MAX_TOTAL_BYTES || servingIdentities.size > MAX_ENTRIES)
+    && servingIdentities.size > 1
+  ) {
+    let oldestThreadId: string | undefined;
+    let oldestAt = Infinity;
+    for (const [candidateThreadId, entry] of servingIdentities) {
+      if (entry.at < oldestAt) {
+        oldestAt = entry.at;
+        oldestThreadId = candidateThreadId;
+      }
+    }
+    if (oldestThreadId === undefined) break;
+    deleteServingIdentity(oldestThreadId);
+  }
+}
+
+function processLocalIdentity(domain: string, material: string): string {
+  return createHmac("sha256", replayIdentityKey)
+    .update(domain)
+    .update("\0")
+    .update(material)
+    .digest("hex");
+}
+
+function credentialHeaderOverrides(headers: Record<string, string> | undefined): [string, string][] {
+  return Object.entries(headers ?? {})
+    .filter(([name, value]) => CREDENTIAL_HEADER_NAMES.has(name.trim().toLowerCase()) && nonEmpty(value))
+    .map(([name, value]) => [name.trim().toLowerCase(), value] as [string, string])
+    .sort(([leftName, leftValue], [rightName, rightValue]) => (
+      leftName.localeCompare(rightName) || leftValue.localeCompare(rightValue)
+    ));
+}
+
+/** Produce a non-reversible process-local identity for an exact upstream destination. */
+export function reasoningReplayDestinationIdentity(baseUrl: string | undefined): string | undefined {
+  if (!nonEmpty(baseUrl)) return undefined;
+  const canonical = baseUrl.trim().replace(/\/+$/, "");
+  return `destination:${processLocalIdentity("destination", canonical)}`;
+}
+
+/**
+ * The same destination identity, but stable across restarts.
+ *
+ * The process-local form above is keyed by `randomBytes(32)` minted at module load, which
+ * is correct for an in-memory cache and fatal for a durable one: every key would change on
+ * restart and the store would silently stop matching anything. A plain digest of the same
+ * canonical URL is equally non-reversible for this purpose — the input is a configured
+ * endpoint, not a secret — and needs no persisted salt or new on-disk state.
+ */
+export function durableReplayDestinationIdentity(baseUrl: string | undefined): string | undefined {
+  if (!nonEmpty(baseUrl)) return undefined;
+  const canonical = baseUrl.trim().replace(/\/+$/, "");
+  return `destination:${createHash("sha256").update("destination\0").update(canonical).digest("hex")}`;
+}
+
+/**
+ * Restart-stable credential identity for the DURABLE thought-signature store (#1926).
+ *
+ * Unlike the destination, credential material may be secret (an API key), so a plain
+ * unsalted digest would turn the store file into an offline verifier for candidate keys.
+ * The identity is therefore an HMAC under a random salt persisted NEXT TO the store: the
+ * salt is not a secret escrow (it holds no credential material) but it makes every digest
+ * useless outside this installation. Full 256-bit output — no truncation.
+ *
+ * OAuth accounts use the persisted account-slot id (not the rotating token/generation):
+ * relinking a slot to a different upstream account keeps the id, but the upstream then
+ * validates signatures against the new credential and rejects stale ones — the same
+ * fail-closed backstop the destination identity relies on. Credential-scoped header
+ * overrides participate so two provider entries sharing one key but different
+ * authorization headers stay distinct, mirroring the process-local identity.
+ */
+export function durableReplayCredentialIdentity(
+  kind: "key" | "oauth" | "codex",
+  material: string | undefined,
+  headers: Record<string, string> | undefined,
+  salt: Buffer | undefined,
+): string | undefined {
+  if (!nonEmpty(material) || !salt || salt.length < 16) return undefined;
+  const overrides = credentialHeaderOverrides(headers);
+  return `credential:${createHmac("sha256", salt)
+    .update(`credential\0${kind}\0`)
+    .update(JSON.stringify([material, overrides]))
+    .digest("hex")}`;
+}
+
+/** Produce a non-reversible process-local identity for credential material. */
+export function reasoningReplayCredentialIdentity(
+  kind: "key" | "oauth" | "codex",
+  material: string | undefined,
+  headers?: Record<string, string>,
+): string | undefined {
+  if (!nonEmpty(material)) return undefined;
+  const overrides = credentialHeaderOverrides(headers);
+  return `${kind}:${processLocalIdentity(`credential:${kind}`, JSON.stringify([material, overrides]))}`;
+}
+
+/** Bind Codex forwarding to the effective bearer/account and selected physical pool slot. */
+export function reasoningReplayCodexCredentialIdentity(args: {
+  authorization?: string | null;
+  chatgptAccountId?: string | null;
+  accountId?: string | null;
+  credentialGeneration?: number | string | null;
+  writerGeneration?: number | string | null;
+  headers?: Record<string, string>;
+}): string | undefined {
+  const configuredAuthorization = credentialHeaderOverrides(args.headers)
+    .find(([name]) => name === "authorization")?.[1];
+  const authorization = nonEmpty(args.authorization) ? args.authorization : configuredAuthorization;
+  if (!authorization) return undefined;
+  const material = JSON.stringify([
+    authorization,
+    nonEmpty(args.chatgptAccountId) ? args.chatgptAccountId : "",
+    nonEmpty(args.accountId) ? args.accountId : "",
+    args.credentialGeneration === null || args.credentialGeneration === undefined
+      ? ""
+      : String(args.credentialGeneration),
+    args.writerGeneration === null || args.writerGeneration === undefined
+      ? ""
+      : String(args.writerGeneration),
+  ]);
+  return reasoningReplayCredentialIdentity("codex", material, args.headers);
+}
+
+/** Bind OAuth replay to one persisted credential slot and exact token generation. */
+export function reasoningReplayOAuthCredentialIdentity(
+  snapshot: Readonly<{ accountId: string; generation: string }> | undefined,
+  headers?: Record<string, string>,
+): string | undefined {
+  if (!snapshot || !nonEmpty(snapshot.accountId) || !nonEmpty(snapshot.generation)) return undefined;
+  return reasoningReplayCredentialIdentity(
+    "oauth",
+    `${snapshot.accountId}\0${snapshot.generation}`,
+    headers,
+  );
+}
+
+/** Bind key-auth provider material without putting raw secrets in the replay key. */
+export function reasoningReplayKeyCredentialIdentity(
+  provider: Pick<OcxProviderConfig, "apiKey" | "headers">,
+): string | undefined {
+  const apiKey = nonEmpty(provider.apiKey) ? provider.apiKey : undefined;
+  // Public/static headers do not establish a physical credential boundary.
+  // Header-only/key-optional providers therefore fail closed for replay.
+  if (!apiKey) return undefined;
+  return reasoningReplayCredentialIdentity("key", apiKey, provider.headers);
+}
+
+/** Replace only the holder snapshot so parsed-request copies observe rotations. */
+export function bindReasoningReplayScope(
+  scope: OcxReasoningReplayScopeRef | undefined,
+  identity: OcxReasoningReplayIdentity | undefined,
+): void {
+  if (!scope) return;
+  if (!identity || !keyFor("binding-check", { ...scope, current: identity })) {
+    delete scope.current;
+    return;
+  }
+  scope.current = { ...identity };
+}
+
+/**
+ * Record the raw reasoning text that preceded the given tool call.
+ *
+ * Expired entries are swept on insert so the TTL bound holds even when a call
+ * id is never read again.
+ */
+export function rememberReasoningForCall(
+  callId: string,
+  text: string,
+  scope?: OcxReasoningReplayScopeRef,
+): void {
+  // Never fall back to a process-wide namespace. Call ids are supplied by
+  // clients/providers and are therefore neither unique nor trustworthy; an
+  // unscoped entry could be recovered by an unrelated request that reuses the
+  // same id.
+  // Empty provider deltas are absence of new reasoning, not a request to erase a candidate.
+  const key = keyFor(callId, scope);
+  if (!key || typeof text !== "string" || text.length === 0) return;
+  const bytes = Buffer.byteLength(text, "utf8");
+  // A single entry larger than the whole budget would immediately evict itself.
+  if (bytes > MAX_TOTAL_BYTES) return;
+  const at = now();
+  // Delete every due entry first so expired reasoning cannot linger until a
+  // later peek or capacity eviction.
+  for (const [key, entry] of entries) {
+    if (at - entry.at >= TTL_MS) {
+      entries.delete(key);
+      totalBytes -= entry.bytes;
+    }
+  }
+  const previous = entries.get(key);
+  if (previous) totalBytes -= previous.bytes;
+  entries.set(key, { text, bytes, at });
+  totalBytes += bytes;
+  // Evict oldest-first until both caps hold (never evict the entry just written
+  // while it is the only one — the loop guards on size > 1).
+  while ((totalBytes > MAX_TOTAL_BYTES || entries.size > MAX_ENTRIES) && entries.size > 1) {
+    let oldestKey: string | undefined;
+    let oldestAt = Infinity;
+    for (const [candidateKey, entry] of entries) {
+      if (entry.at < oldestAt) {
+        oldestAt = entry.at;
+        oldestKey = candidateKey;
+      }
+    }
+    if (oldestKey === undefined) break;
+    const evicted = entries.get(oldestKey)!;
+    totalBytes -= evicted.bytes;
+    entries.delete(oldestKey);
+  }
+}
+
+/**
+ * Read the recorded reasoning for a call id without removing it: retries after
+ * a failed continuation reuse the same fallback.
+ */
+export function peekReasoningForCall(
+  callId: string,
+  scope?: OcxReasoningReplayScopeRef,
+): string | undefined {
+  const key = keyFor(callId, scope);
+  if (!key) return undefined;
+  const entry = entries.get(key);
+  if (!entry) return undefined;
+  if (now() - entry.at >= TTL_MS) {
+    entries.delete(key);
+    totalBytes -= entry.bytes;
+    return undefined;
+  }
+  return entry.text;
+}
+
+/** Test-only: reset the cache and optionally pin the clock. */
+export function clearReasoningReplayCacheForTests(clock?: (() => number) | null): void {
+  entries.clear();
+  servingIdentities.clear();
+  totalBytes = 0;
+  servingIdentityTotalBytes = 0;
+  clockForTests = clock ?? null;
+}