@iislee/opencodex 2.11.0 → 2.31.0

package/src/server/responses-terminal-repair.ts

@@ -0,0 +1,342 @@
+import type { TranslatorBudget } from "../lib/translator-budget";
+import type { ResponsesTerminalRepairPolicy } from "../providers/registry";
+import { nextSseBlock, sseDataPayload } from "./sse-payload-rewrite";
+
+export interface ResponsesTerminalRepairScheduler {
+  nowMs(): number;
+  schedule(callback: () => void, delayMs: number): unknown;
+  cancel(handle: unknown): void;
+}
+
+const systemScheduler: ResponsesTerminalRepairScheduler = {
+  nowMs: () => Date.now(),
+  schedule(callback, delayMs) {
+    const handle = setTimeout(callback, delayMs);
+    (handle as { unref?: () => void }).unref?.();
+    return handle;
+  },
+  cancel(handle) { clearTimeout(handle as ReturnType<typeof setTimeout>); },
+};
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function outputIndex(value: unknown): number | null {
+  return Number.isInteger(value) && (value as number) >= 0 ? value as number : null;
+}
+
+function isCompleteItem(item: Record<string, unknown>): boolean {
+  if (item.status !== "completed") return false;
+  if (item.type === "reasoning") {
+    return typeof item.id === "string" && item.id.length > 0
+      && Array.isArray(item.content)
+      && item.content.every(part => isPlainRecord(part)
+        && part.type === "reasoning_text" && typeof part.text === "string");
+  }
+  if (item.type === "message") {
+    return typeof item.id === "string" && item.id.length > 0
+      && item.role === "assistant" && Array.isArray(item.content)
+      && item.content.every(part => isPlainRecord(part)
+        && part.type === "output_text" && typeof part.text === "string");
+  }
+  if (item.type === "function_call") {
+    if (typeof item.id !== "string" || item.id.length === 0) return false;
+    if (typeof item.call_id !== "string" || item.call_id.length === 0) return false;
+    if (typeof item.name !== "string" || item.name.length === 0) return false;
+    if (typeof item.arguments !== "string") return false;
+    try {
+      return isPlainRecord(JSON.parse(item.arguments));
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/**
+ * Relay a native Responses SSE body while repairing the narrow DeepSeek shape where every
+ * output item is complete but the protocol terminal is missing or indefinitely delayed.
+ */
+export function relayResponsesSseWithTerminalRepair(
+  body: ReadableStream<Uint8Array>,
+  upstream: AbortController,
+  policy: ResponsesTerminalRepairPolicy,
+  budget: TranslatorBudget,
+  scheduler: ResponsesTerminalRepairScheduler = systemScheduler,
+): ReadableStream<Uint8Array> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  const added = new Map<number, { type?: unknown; id?: unknown }>();
+  const completed = new Map<number, { item: Record<string, unknown>; bytes: number }>();
+  let created: Record<string, unknown> | null = null;
+  let createdBytes = 0;
+  let maxSequence = -1;
+  let buffer = "";
+  let bufferBytes = 0;
+  let timer: unknown;
+  let timerGeneration = 0;
+  let realTerminalSeen = false;
+  let tainted = false;
+  let disposed = false;
+  let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null;
+  let activeRead: Promise<void> | null = null;
+
+  const onUpstreamAbort = (): void => {
+    if (disposed) return;
+    dispose();
+    reader.cancel(upstream.signal.reason).catch(() => {});
+    try { controllerRef?.close(); } catch { /* already closed */ }
+  };
+
+  const releaseRetainedState = (): void => {
+    if (createdBytes > 0) budget.releaseRetained(createdBytes, { kind: "retained_collectors" });
+    createdBytes = 0;
+    for (const retained of completed.values()) {
+      budget.releaseRetained(retained.bytes, { kind: "retained_collectors" });
+    }
+    completed.clear();
+    created = null;
+  };
+
+  const releaseBuffer = (): void => {
+    if (bufferBytes > 0) budget.releaseRetained(bufferBytes, { kind: "live_transient" });
+    buffer = "";
+    bufferBytes = 0;
+  };
+
+  const cancelTimer = (): void => {
+    timerGeneration += 1;
+    if (timer !== undefined) scheduler.cancel(timer);
+    timer = undefined;
+  };
+
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    upstream.signal.removeEventListener("abort", onUpstreamAbort);
+    cancelTimer();
+    releaseRetainedState();
+    releaseBuffer();
+  };
+
+  const replaceBuffer = (next: string): void => {
+    const nextBytes = encoder.encode(next).byteLength;
+    const reservation = budget.reserveTransient(nextBytes, { kind: "live_transient" });
+    reservation.commitRetained();
+    if (bufferBytes > 0) budget.releaseRetained(bufferBytes, { kind: "live_transient" });
+    buffer = next;
+    bufferBytes = nextBytes;
+  };
+
+  const appendBuffer = (fragment: string): void => {
+    if (!fragment) return;
+    replaceBuffer(buffer + fragment);
+  };
+
+  const retainCreated = (response: Record<string, unknown>): void => {
+    const bytes = encoder.encode(JSON.stringify(response)).byteLength;
+    budget.chargeRetained(bytes, { kind: "retained_collectors" });
+    if (createdBytes > 0) budget.releaseRetained(createdBytes, { kind: "retained_collectors" });
+    created = response;
+    createdBytes = bytes;
+  };
+
+  const retainCompleted = (index: number, item: Record<string, unknown>): void => {
+    const bytes = encoder.encode(JSON.stringify(item)).byteLength;
+    budget.chargeRetained(bytes, { kind: "retained_collectors" });
+    const previous = completed.get(index);
+    if (previous) budget.releaseRetained(previous.bytes, { kind: "retained_collectors" });
+    completed.set(index, { item, bytes });
+  };
+
+  const completeCandidate = (): boolean => {
+    if (realTerminalSeen || tainted || !created || completed.size === 0 || added.size !== completed.size) return false;
+    for (const index of added.keys()) {
+      const retained = completed.get(index);
+      if (!retained || !isCompleteItem(retained.item)) return false;
+    }
+    for (const index of completed.keys()) if (!added.has(index)) return false;
+    return true;
+  };
+
+  const syntheticTerminal = (kind: "completed" | "incomplete"): Uint8Array => {
+    const output = [...completed.entries()]
+      .sort(([left], [right]) => left - right)
+      .map(([, retained]) => retained.item);
+    const response = {
+      ...(created ?? {}),
+      status: kind,
+      completed_at: Math.floor(scheduler.nowMs() / 1_000),
+      output,
+      ...(kind === "incomplete"
+        ? { incomplete_details: { reason: "missing_terminal_event" } }
+        : {}),
+    };
+    const type = `response.${kind}`;
+    return encoder.encode(`event: ${type}\ndata: ${JSON.stringify({
+      type,
+      response,
+      sequence_number: maxSequence + 1,
+    })}\n\n`);
+  };
+
+  const emitSynthetic = (
+    kind: "completed" | "incomplete",
+    controller: ReadableStreamDefaultController<Uint8Array>,
+  ): boolean => {
+    if (disposed || realTerminalSeen) return false;
+    realTerminalSeen = true;
+    cancelTimer();
+    controller.enqueue(syntheticTerminal(kind));
+    releaseRetainedState();
+    return true;
+  };
+
+  const commitSynthetic = (generation: number): void => {
+    if (disposed || realTerminalSeen || generation !== timerGeneration || !completeCandidate()) return;
+    timer = undefined;
+    try {
+      if (controllerRef && emitSynthetic("completed", controllerRef)) controllerRef.close();
+    } catch {
+      /* downstream already closed */
+    }
+    reader.cancel("Responses terminal repaired after complete output").catch(() => {});
+    dispose();
+  };
+
+  const maybeArmTimer = (): void => {
+    if (!completeCandidate()) return;
+    const generation = timerGeneration;
+    timer = scheduler.schedule(() => commitSynthetic(generation), policy.graceMs);
+  };
+
+  const inspectPayload = (payload: string | null): "done" | "ordinary" => {
+    if (payload === "[DONE]") return "done";
+    if (!payload || realTerminalSeen) return "ordinary";
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(payload);
+    } catch {
+      tainted = true;
+      return "ordinary";
+    }
+    if (!isPlainRecord(parsed)) {
+      tainted = true;
+      return "ordinary";
+    }
+    if (Number.isInteger(parsed.sequence_number)) {
+      maxSequence = Math.max(maxSequence, parsed.sequence_number as number);
+    }
+    const type = parsed.type;
+    if (type === "response.completed" || type === "response.failed" || type === "response.incomplete") {
+      realTerminalSeen = true;
+      cancelTimer();
+      releaseRetainedState();
+      return "ordinary";
+    }
+
+    cancelTimer();
+    if (type === "response.created" && isPlainRecord(parsed.response)) {
+      retainCreated(parsed.response);
+    } else if (type === "response.output_item.added") {
+      const index = outputIndex(parsed.output_index);
+      if (index === null || !isPlainRecord(parsed.item) || added.has(index) || completed.has(index)) {
+        tainted = true;
+      } else {
+        added.set(index, { type: parsed.item.type, id: parsed.item.id });
+      }
+    } else if (type === "response.output_item.done") {
+      const index = outputIndex(parsed.output_index);
+      if (index === null || !isPlainRecord(parsed.item) || !added.has(index) || completed.has(index)) {
+        tainted = true;
+      } else {
+        const opened = added.get(index)!;
+        if (opened.type !== parsed.item.type || opened.id !== parsed.item.id) tainted = true;
+        retainCompleted(index, parsed.item);
+      }
+    }
+    maybeArmTimer();
+    return "ordinary";
+  };
+
+  const emitBlocks = (
+    controller: ReadableStreamDefaultController<Uint8Array>,
+  ): { closed: boolean; emitted: boolean } => {
+    let next: ReturnType<typeof nextSseBlock>;
+    let emitted = false;
+    while ((next = nextSseBlock(buffer))) {
+      replaceBuffer(next.rest);
+      const kind = inspectPayload(sseDataPayload(next.block));
+      if (kind === "done" && !realTerminalSeen) {
+        emitSynthetic(completeCandidate() ? "completed" : "incomplete", controller);
+      }
+      controller.enqueue(encoder.encode(next.block + next.delimiter));
+      emitted = true;
+      if (kind === "done") {
+        reader.cancel("Responses stream ended with DONE").catch(() => {});
+        dispose();
+        controller.close();
+        return { closed: true, emitted };
+      }
+    }
+    return { closed: false, emitted };
+  };
+
+  const readOnce = async (controller: ReadableStreamDefaultController<Uint8Array>): Promise<void> => {
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (disposed) return;
+        if (done) {
+          appendBuffer(decoder.decode());
+          if (buffer.length > 0) {
+            // A delimiter-less suffix is not a complete SSE event. Preserve the
+            // upstream bytes for passthrough compatibility, but never let a
+            // truncated lifecycle frame establish synthetic success.
+            tainted = true;
+            controller.enqueue(encoder.encode(buffer));
+          }
+          if (!realTerminalSeen) {
+            emitSynthetic(completeCandidate() ? "completed" : "incomplete", controller);
+          }
+          releaseBuffer();
+          dispose();
+          controller.close();
+          return;
+        }
+        appendBuffer(decoder.decode(value, { stream: true }));
+        const result = emitBlocks(controller);
+        if (result.closed || result.emitted) return;
+      }
+    } catch (error) {
+      if (disposed) return;
+      dispose();
+      controller.error(error);
+    }
+  };
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controllerRef = controller;
+      if (upstream.signal.aborted) {
+        onUpstreamAbort();
+        return;
+      }
+      upstream.signal.addEventListener("abort", onUpstreamAbort, { once: true });
+    },
+    pull(controller) {
+      if (disposed) return;
+      if (!activeRead) {
+        activeRead = readOnce(controller).finally(() => { activeRead = null; });
+      }
+      return activeRead;
+    },
+    cancel(reason) {
+      dispose();
+      upstream.abort(reason);
+      return reader.cancel(reason);
+    },
+  });
+}

package/src/server/responses-tool-search-repair.ts

@@ -0,0 +1,267 @@
+import {
+  isTranslatorBudgetExceededError,
+  TranslatorBudgetExceededError,
+  type TranslatorBudget,
+} from "../lib/translator-budget";
+import {
+  restoreRoutedToolSearchCalls,
+} from "../responses/tool-search-compat";
+import {
+  replaceSseDataPayload,
+  sseDataPayload,
+  type SseBlockRewrite,
+} from "./sse-payload-rewrite";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+type PendingArgumentBlock = {
+  block: string;
+  itemId?: string;
+  outputIndex?: number;
+  retainedBytes: number;
+};
+
+const MAX_PENDING_ARGUMENT_FRAMES = 256;
+const MAX_PENDING_ARGUMENT_BYTES = 1024 * 1024;
+const MAX_CLASSIFIED_ITEM_IDS = 256;
+const MAX_CLASSIFIED_ITEM_ID_BYTES = 256 * 1024;
+
+class ClassifiedItemIdCountExceededError extends Error {
+  readonly code = "translation_buffer_limit";
+  readonly kind = "item_ids";
+  readonly limitItems = MAX_CLASSIFIED_ITEM_IDS;
+
+  constructor() {
+    super(`translator item_ids count exceeded ${MAX_CLASSIFIED_ITEM_IDS} items`);
+    this.name = "ClassifiedItemIdCountExceededError";
+  }
+}
+
+/**
+ * Public Responses gateways stream a lowered search as a normal function lifecycle. Codex expects
+ * only `tool_search_call` items, so classify each item before dropping its function-argument
+ * frames. Unknown early argument frames stay bounded until their item arrives.
+ */
+export function createRoutedToolSearchRestoreBlockRewrite(
+  names: ReadonlySet<string>,
+  budget?: TranslatorBudget,
+): SseBlockRewrite {
+  const routedItemIds = new Set<string>();
+  const ordinaryItemIds = new Set<string>();
+  let classifiedItemIdBytes = 0;
+  let pendingArguments: PendingArgumentBlock[] = [];
+  let pendingArgumentBytes = 0;
+  let passthrough = false;
+  let disposed = false;
+
+  const releaseAll = (): void => {
+    if (disposed) return;
+    disposed = true;
+    if (pendingArgumentBytes > 0) {
+      budget?.releaseRetained(pendingArgumentBytes, { kind: "retained_collectors" });
+    }
+    pendingArguments = [];
+    pendingArgumentBytes = 0;
+    if (classifiedItemIdBytes > 0) {
+      budget?.releaseRetained(classifiedItemIdBytes, { kind: "item_ids" });
+    }
+    classifiedItemIdBytes = 0;
+    routedItemIds.clear();
+    ordinaryItemIds.clear();
+  };
+
+  const clearOrdinaryItemIds = (): void => {
+    let releasedBytes = 0;
+    for (const itemId of ordinaryItemIds) {
+      releasedBytes += Buffer.byteLength(JSON.stringify(itemId), "utf8");
+    }
+    ordinaryItemIds.clear();
+    classifiedItemIdBytes = Math.max(0, classifiedItemIdBytes - releasedBytes);
+    if (releasedBytes > 0) budget?.releaseRetained(releasedBytes, { kind: "item_ids" });
+  };
+
+  const classifyItemId = (itemId: string, routed: boolean): void => {
+    const target = routed ? routedItemIds : ordinaryItemIds;
+    const previous = routed ? ordinaryItemIds : routedItemIds;
+    if (target.has(itemId)) return;
+    if (previous.delete(itemId)) {
+      target.add(itemId);
+      return;
+    }
+
+    if (routedItemIds.size + ordinaryItemIds.size >= MAX_CLASSIFIED_ITEM_IDS) {
+      throw new ClassifiedItemIdCountExceededError();
+    }
+    const retainedBytes = Buffer.byteLength(JSON.stringify(itemId), "utf8");
+    if (classifiedItemIdBytes + retainedBytes > MAX_CLASSIFIED_ITEM_ID_BYTES) {
+      throw new TranslatorBudgetExceededError("item_ids", MAX_CLASSIFIED_ITEM_ID_BYTES);
+    }
+    budget?.chargeRetained(retainedBytes, { kind: "item_ids" });
+    target.add(itemId);
+    classifiedItemIdBytes += retainedBytes;
+  };
+
+  const retainPending = (
+    block: string,
+    itemId: string | undefined,
+    outputIndex: number | undefined,
+  ): readonly string[] | null => {
+    const retainedBytes = Buffer.byteLength(block, "utf8");
+    const overflow = pendingArguments.length >= MAX_PENDING_ARGUMENT_FRAMES
+      || pendingArgumentBytes + retainedBytes > MAX_PENDING_ARGUMENT_BYTES;
+    if (overflow) {
+      const flushed = [...pendingArguments.map(pending => pending.block), block];
+      if (pendingArgumentBytes > 0) {
+        budget?.releaseRetained(pendingArgumentBytes, { kind: "retained_collectors" });
+      }
+      pendingArguments = [];
+      pendingArgumentBytes = 0;
+      passthrough = true;
+      // Deliberately KEEP routedItemIds. Overflow means we stop buffering UNKNOWN frames, not
+      // that we forget what we already classified: an item restored to `tool_search_call`
+      // upstream of here would otherwise start emitting `function_call_arguments.*` again and
+      // the client would see a mixed private/public lifecycle for one call.
+      clearOrdinaryItemIds();
+      return flushed;
+    }
+    if (retainedBytes > 0) {
+      try {
+        budget?.chargeRetained(retainedBytes, { kind: "retained_collectors" });
+      } catch (error) {
+        if (!isTranslatorBudgetExceededError(error)) throw error;
+        const flushed = [...pendingArguments.map(pending => pending.block), block];
+        if (pendingArgumentBytes > 0) {
+          budget?.releaseRetained(pendingArgumentBytes, { kind: "retained_collectors" });
+        }
+        pendingArguments = [];
+        pendingArgumentBytes = 0;
+        passthrough = true;
+        // Same reasoning as the frame/byte overflow above: an already-restored routed item
+        // must keep its frames suppressed even once buffering stops.
+        clearOrdinaryItemIds();
+        return flushed;
+      }
+    }
+    pendingArguments.push({ block, itemId, outputIndex, retainedBytes });
+    pendingArgumentBytes += retainedBytes;
+    return null;
+  };
+
+  const takePending = (
+    itemId: string | undefined,
+    outputIndex: number | undefined,
+  ): string[] => {
+    const matched: PendingArgumentBlock[] = [];
+    const remaining: PendingArgumentBlock[] = [];
+    for (const pending of pendingArguments) {
+      const matches = pending.itemId !== undefined
+        ? itemId !== undefined && pending.itemId === itemId
+        : outputIndex !== undefined && pending.outputIndex === outputIndex;
+      (matches ? matched : remaining).push(pending);
+    }
+    pendingArguments = remaining;
+    const retainedBytes = matched.reduce((total, pending) => total + pending.retainedBytes, 0);
+    if (retainedBytes > 0) {
+      budget?.releaseRetained(retainedBytes, { kind: "retained_collectors" });
+      pendingArgumentBytes = Math.max(0, pendingArgumentBytes - retainedBytes);
+    }
+    return matched.map(pending => {
+      if (pending.itemId !== undefined || itemId === undefined) return pending.block;
+      const payload = sseDataPayload(pending.block);
+      if (payload === null) return pending.block;
+      try {
+        const parsed: unknown = JSON.parse(payload);
+        return isPlainObject(parsed)
+          ? replaceSseDataPayload(pending.block, JSON.stringify({ ...parsed, item_id: itemId }))
+          : pending.block;
+      } catch {
+        return pending.block;
+      }
+    });
+  };
+
+  const rewrite: SseBlockRewrite = (block: string): readonly string[] => {
+    if (disposed) return [block];
+    const payload = sseDataPayload(block);
+    if (payload === null) return [block];
+    if (payload === "[DONE]") {
+      releaseAll();
+      return [block];
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(payload);
+    } catch {
+      return [block];
+    }
+    if (!isPlainObject(parsed)) return [block];
+
+    const type = typeof parsed.type === "string" ? parsed.type : "";
+    const terminal = type === "response.completed" || type === "response.failed" || type === "response.incomplete";
+    // After overflow we stop BUFFERING unknown frames, but an item already restored to
+    // `tool_search_call` must keep its public argument frames suppressed — otherwise the client
+    // receives a private item followed by `function_call_arguments.*` for the same id, which is
+    // exactly the mixed lifecycle this rewrite exists to prevent. Everything else passes through.
+    if (passthrough) {
+      if (terminal) {
+        releaseAll();
+        return [block];
+      }
+      const passthroughItemId = typeof parsed.item_id === "string" ? parsed.item_id : undefined;
+      const isArgumentEvent = type === "response.function_call_arguments.delta"
+        || type === "response.function_call_arguments.done";
+      if (isArgumentEvent && passthroughItemId && routedItemIds.has(passthroughItemId)) return [];
+      return [block];
+    }
+    const outputIndex = typeof parsed.output_index === "number"
+      && Number.isInteger(parsed.output_index)
+      && parsed.output_index >= 0
+      ? parsed.output_index
+      : undefined;
+    if (
+      (type === "response.output_item.added" || type === "response.output_item.done")
+      && isPlainObject(parsed.item)
+      && parsed.item.type === "function_call"
+      && typeof parsed.item.name === "string"
+    ) {
+      const itemId = typeof parsed.item.id === "string" ? parsed.item.id : undefined;
+      const routed = names.has(parsed.item.name);
+      if (itemId) classifyItemId(itemId, routed);
+      const pending = takePending(itemId, outputIndex);
+      const restored = routed ? restoreRoutedToolSearchCalls(parsed, names) : { value: parsed, changed: false };
+      const restoredBlock = restored.changed
+        ? replaceSseDataPayload(block, JSON.stringify(restored.value))
+        : block;
+      // Classification is retained past `output_item.done` for BOTH kinds, until the terminal
+      // event releases the bounded, budgeted state.
+      //
+      // `done` ends the item, not the id's relevance. Forgetting a ROUTED id let a trailing
+      // `function_call_arguments.*` — which some upstreams emit after done — fall through to
+      // the unknown-id branch and reach the client as a public frame for an item the client
+      // was told is a private `tool_search_call`: the mixed lifecycle this rewrite exists to
+      // prevent. Forgetting an ORDINARY id is not leak-shaped but is not free either, because
+      // the same fall-through buffers its trailing frames as unknown and delays them until an
+      // item that will never arrive. Neither id is dropped early.
+      return routed ? [restoredBlock] : [...pending, restoredBlock];
+    }
+
+    const itemId = typeof parsed.item_id === "string" ? parsed.item_id : undefined;
+    const argumentEvent = type === "response.function_call_arguments.delta"
+      || type === "response.function_call_arguments.done";
+    if (argumentEvent && (!itemId || (!routedItemIds.has(itemId) && !ordinaryItemIds.has(itemId)))) {
+      return retainPending(block, itemId, outputIndex) ?? [];
+    }
+    if (argumentEvent && itemId && routedItemIds.has(itemId)) return [];
+
+    if (!terminal) return [block];
+    const restored = restoreRoutedToolSearchCalls(parsed, names);
+    releaseAll();
+    return restored.changed
+      ? [replaceSseDataPayload(block, JSON.stringify(restored.value))]
+      : [block];
+  };
+  rewrite.dispose = releaseAll;
+  return rewrite;
+}