@iislee/opencodex 2.11.0

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

@@ -0,0 +1,230 @@
+import type {
+  AdapterEvent,
+  OcxAssistantContentPart,
+  OcxAssistantMessage,
+  OcxParsedRequest,
+  OcxUsage,
+} from "../../types";
+
+const ACTIONABLE_REQUEST_RE = /(?:\b(?:add|change|check|continue|create|debug|delete|deploy|edit|execute|fix|implement|inspect|keep going|modify|patch|proceed|refactor|remove|review|run|test|update|write)\b|继续|接着|往下|升级|修改|改(?:一下|下)?|修复|实现|添加|新增|删除|重构|更新|运行|执行|检查|查看|排查|调试|创建|写入|提交|推送|部署|看下|改成|修一下)/iu;
+const PLAN_ONLY_REQUEST_RE = /(?:暂时不要(?:调用|使用)工具|不要调用工具|不用执行|只回复(?:计划|方案)|(?:只|先|给|说|写|出|来)(?:我)?(?:一个|个|一下|份)?[^。！？\n]{0,8}?(?:计划|方案|草案|提案|思路)|(?:计划|方案|草案|提案|思路)(?:就(?:行|好|可以)|即可)|\b(?:just give|provide)\s+(?:me\s+)?(?:a\s+)?plan\b|\b(?:do not|don't)\s+(?:use|call)\s+tools?\b|\b(?:write|draft|outline|propose|give|provide|create|make|share|suggest|sketch)\s+(?:me\s+)?(?:a\s+|an\s+|the\s+|your\s+)?(?:(?:brief|concise|short|detailed|high[-\s]?level|rough|quick|step[-\s]?by[-\s]?step|implementation|migration|refactor(?:ing)?|design|technical)\s+)*(?:plan|proposal|draft|outline|approach|strategy|design\s+doc)\b)/iu;
+const PLAN_INTENT_RE = /(?:\b(?:i(?:'|’)m going to|i will|i(?:'|’)ll|let me|next i)\b|我(?:先|会|将|接下来)|下一步)/iu;
+const PLAN_OR_COMPLETION_RE = /(?:\b(?:i(?:'|’)m going to|i will|i(?:'|’)ll|let me|next i|i(?:'|’)ve (?:already )?(?:added|applied|changed|completed|fixed|implemented|modified|updated))\b|\b(?:done|completed|fixed|implemented|updated|applied)\b|我(?:先|会|将|接下来)|下一步|已(?:经)?(?:修改|修复|完成|应用|更新|实现|处理)|完成了|已经好了)/iu;
+const WAITING_FOR_USER_RE = /(?:[?？]\s*$|需要我|请(?:确认|选择|提供)|是否|要不要|可以吗|\b(?:do you want|should i|which file|please confirm|please provide)\b)/iu;
+const EXPLICIT_CONTINUE_RE = /^(?:继续|接着|往下|go on|continue|proceed|keep going)\s*[.!。！]?$/iu;
+const MAX_ANNOUNCEMENT_CHARS = 280;
+
+export const TERMINAL_GUARD_NUDGE =
+  "你刚才只描述了计划，没有执行任何工具。不要再次解释计划，现在立即调用必要工具执行用户任务。" +
+  "只有工具返回后才总结；如果确实无法执行，请明确说明阻塞原因。";
+
+export type TerminalGuardDecision = "pass" | "continue" | "ambiguous";
+
+export interface TerminalTurnAnalysis {
+  decision: TerminalGuardDecision;
+  reason: "normal" | "waiting_for_user" | "no_tools" | "no_actionable_request" | "no_execution_claim" | "recent_tool_activity" | "substantive_answer" | "suspicious_no_tool";
+  assistantText: string;
+  userText: string;
+  hasToolCall: boolean;
+}
+
+function messageText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return "";
+  return value
+    .filter((part): part is { type?: unknown; text?: unknown } => !!part && typeof part === "object")
+    .filter(part => part.type === "text" && typeof part.text === "string")
+    .map(part => part.text as string)
+    .join("");
+}
+
+function latestUserText(parsed: OcxParsedRequest): string {
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "user") return messageText(message.content);
+  }
+  return "";
+}
+
+function recentTurnHasToolActivity(parsed: OcxParsedRequest): boolean {
+  let latestUserIndex = -1;
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    if (parsed.context.messages[i]?.role === "user") {
+      latestUserIndex = i;
+      break;
+    }
+  }
+  if (latestUserIndex < 0) return false;
+  let lastAssistant: OcxAssistantMessage | undefined;
+  for (let i = latestUserIndex - 1; i >= 0; i -= 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "assistant") {
+      lastAssistant = message;
+      break;
+    }
+  }
+  if (lastAssistant?.role === "assistant") {
+    const hasToolCall = lastAssistant.content.some(part => part.type === "toolCall");
+    const text = lastAssistant.content
+      .filter(part => part.type === "text")
+      .map(part => part.text)
+      .join("");
+    if (!hasToolCall && PLAN_INTENT_RE.test(text)) return false;
+  }
+  for (let i = latestUserIndex - 1; i >= 0 && parsed.context.messages[i]?.role !== "user"; i -= 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "toolResult") return true;
+    if (message.role === "assistant" && message.content.some(part => part.type === "toolCall")) return true;
+  }
+  return false;
+}
+
+function assistantText(events: readonly AdapterEvent[]): string {
+  return events
+    .filter((event): event is Extract<AdapterEvent, { type: "text_delta" }> => event.type === "text_delta")
+    .map(event => event.text)
+    .join("");
+}
+
+export function analyzeTerminalTurn(parsed: OcxParsedRequest, events: readonly AdapterEvent[]): TerminalTurnAnalysis {
+  const userText = latestUserText(parsed);
+  const text = assistantText(events);
+  const hasToolCall = events.some(event => event.type === "tool_call_start");
+  if (hasToolCall) {
+    return { decision: "pass", reason: "normal", assistantText: text, userText, hasToolCall };
+  }
+  if (!parsed.context.tools || parsed.context.tools.length === 0 || parsed.options.toolChoice === "none") {
+    return { decision: "pass", reason: "no_tools", assistantText: text, userText, hasToolCall };
+  }
+  if (!ACTIONABLE_REQUEST_RE.test(userText)) {
+    return { decision: "pass", reason: "no_actionable_request", assistantText: text, userText, hasToolCall };
+  }
+  if (PLAN_ONLY_REQUEST_RE.test(userText)) {
+    return { decision: "pass", reason: "no_actionable_request", assistantText: text, userText, hasToolCall };
+  }
+  if (EXPLICIT_CONTINUE_RE.test(userText) && recentTurnHasToolActivity(parsed)) {
+    return { decision: "pass", reason: "recent_tool_activity", assistantText: text, userText, hasToolCall };
+  }
+  if (WAITING_FOR_USER_RE.test(text)) {
+    return { decision: "pass", reason: "waiting_for_user", assistantText: text, userText, hasToolCall };
+  }
+  if (text.trim().length > MAX_ANNOUNCEMENT_CHARS) {
+    return { decision: "pass", reason: "substantive_answer", assistantText: text, userText, hasToolCall };
+  }
+  if (!PLAN_OR_COMPLETION_RE.test(text)) {
+    return { decision: "ambiguous", reason: "no_execution_claim", assistantText: text, userText, hasToolCall };
+  }
+  return { decision: "continue", reason: "suspicious_no_tool", assistantText: text, userText, hasToolCall };
+}
+
+function assistantMessageFromEvents(events: readonly AdapterEvent[]): OcxAssistantMessage | undefined {
+  let text = "";
+  let thinking = "";
+  let signature: string | undefined;
+  const redacted: string[] = [];
+  for (const event of events) {
+    if (event.type === "text_delta") text += event.text;
+    else if (event.type === "thinking_delta") thinking += event.thinking;
+    else if (event.type === "thinking_signature") signature = event.signature;
+    else if (event.type === "redacted_thinking") redacted.push(event.data);
+  }
+  const content: OcxAssistantContentPart[] = [];
+  if (thinking || signature || redacted.length > 0) {
+    content.push({ type: "thinking", thinking, ...(signature ? { signature } : {}), ...(redacted.length > 0 ? { redacted } : {}) });
+  }
+  if (text) content.push({ type: "text", text });
+  if (content.length === 0) return undefined;
+  return { role: "assistant", content, timestamp: Date.now() };
+}
+
+export function buildContinuationRequest(parsed: OcxParsedRequest, events: readonly AdapterEvent[]): OcxParsedRequest {
+  const messages = [...parsed.context.messages];
+  const assistant = assistantMessageFromEvents(events);
+  if (assistant) messages.push(assistant);
+  messages.push({ role: "developer", content: TERMINAL_GUARD_NUDGE, timestamp: Date.now() });
+  return { ...parsed, context: { ...parsed.context, messages } };
+}
+
+export interface GuardedEventStreamOptions {
+  parsed: OcxParsedRequest;
+  firstEvents: AsyncIterable<AdapterEvent>;
+  continuation: (parsed: OcxParsedRequest) => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>;
+  adapterName?: string;
+  maxAutoContinuations?: number;
+}
+
+function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
+  if (!first) return second;
+  if (!second) return first;
+  const sumOptional = (key: keyof OcxUsage): number | undefined => {
+    const left = first[key];
+    const right = second[key];
+    return typeof left === "number" || typeof right === "number"
+      ? (typeof left === "number" ? left : 0) + (typeof right === "number" ? right : 0)
+      : undefined;
+  };
+  const cachedInputTokens = sumOptional("cachedInputTokens");
+  const cacheReadInputTokens = sumOptional("cacheReadInputTokens");
+  const cacheCreationInputTokens = sumOptional("cacheCreationInputTokens");
+  const reasoningOutputTokens = sumOptional("reasoningOutputTokens");
+  const inputTokens = first.inputTokens + second.inputTokens;
+  const outputTokens = first.outputTokens + second.outputTokens;
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: inputTokens + outputTokens,
+    ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+    ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+    ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+    ...(reasoningOutputTokens !== undefined ? { reasoningOutputTokens } : {}),
+    ...(first.estimated || second.estimated ? { estimated: true } : {}),
+  };
+}
+
+/** Preserve normal terminals, but withhold one suspicious no-tool terminal for a bounded re-ask. */
+export async function* guardTerminalEventStream(options: GuardedEventStreamOptions): AsyncGenerator<AdapterEvent> {
+  const maxContinuations = Math.max(0, Math.min(2, Math.floor(options.maxAutoContinuations ?? 1)));
+  let parsed = options.parsed;
+  let continuations = 0;
+  let accumulatedUsage: OcxUsage | undefined;
+  let source: AsyncIterable<AdapterEvent> = options.firstEvents;
+
+  while (true) {
+    const seen: AdapterEvent[] = [];
+    let terminalSeen = false;
+    for await (const event of source) {
+      if (event.type === "done") {
+        terminalSeen = true;
+        const analysis = options.adapterName === "anthropic"
+          ? analyzeTerminalTurn(parsed, seen)
+          : { decision: "pass" as const };
+        const normalStop = event.stopReason !== "max_tokens" && event.stopReason !== "content_filter";
+        if (normalStop && analysis.decision === "continue" && continuations < maxContinuations) {
+          accumulatedUsage = mergeUsage(accumulatedUsage, event.usage);
+          continuations += 1;
+          parsed = buildContinuationRequest(parsed, seen);
+          yield { type: "assistant_boundary" };
+          try {
+            source = await options.continuation(parsed);
+          } catch (error) {
+            yield { type: "error", message: error instanceof Error ? error.message : String(error) };
+            return;
+          }
+          break;
+        }
+        const usage = mergeUsage(accumulatedUsage, event.usage);
+        yield usage ? { ...event, usage } : event;
+        return;
+      }
+      if (event.type === "incomplete" || event.type === "error") {
+        terminalSeen = true;
+        const usage = mergeUsage(accumulatedUsage, event.usage);
+        yield usage ? { ...event, usage } : event;
+        return;
+      }
+      seen.push(event);
+      yield event;
+    }
+    if (!terminalSeen) return;
+  }
+}

package/src/server/responses/upstream-error.ts

@@ -0,0 +1,48 @@
+/**
+ * Upstream connection failures share one message shape across the three catch sites in
+ * core.ts. A TLS certificate/hostname mismatch deserves its own wording: the generic
+ * "Provider unreachable" reads as if opencodex built a wrong endpoint, which sent issue
+ * #553 looking for an adapter URL bug that does not exist. Name the likely cause and the
+ * command that settles it.
+ */
+export function describeUpstreamConnectFailure(err: unknown, connectMs: number): string {
+  if (err instanceof Error && err.name === "TimeoutError") {
+    return `Provider connect timeout after ${connectMs}ms`;
+  }
+  const detail = err instanceof Error ? err.message : String(err);
+  const code = err instanceof Error ? (err as { code?: unknown }).code : undefined;
+  // `code` is the reliable signal. The message fallback is anchored to the head because Bun
+  // renders this rejection as `ERR_TLS_CERT_ALTNAME_INVALID fetching "<url>"`; matching the
+  // bare substring anywhere would also fire on text that merely quotes the code back at us.
+  // Only transport failures reach these call sites, so that is defensive rather than load-bearing.
+  if (code === "ERR_TLS_CERT_ALTNAME_INVALID" || detail.startsWith("ERR_TLS_CERT_ALTNAME_INVALID")) {
+    const host = extractHostname(detail);
+    const target = host ?? "the provider host";
+    const probe = host ?? "<host>";
+    return `Provider TLS certificate does not match ${target}: ${redactUrlUserinfo(detail)}. `
+      + "opencodex did not rewrite this hostname — a certificate that does not cover it normally "
+      + "means TLS interception (corporate proxy, VPN, or local MITM tooling) or a poisoned DNS "
+      + `answer. Check with: openssl s_client -connect ${probe}:443 -servername ${probe} `
+      + "</dev/null | openssl x509 -noout -subject -ext subjectAltName";
+  }
+  return `Provider unreachable: ${redactUrlUserinfo(detail)}`;
+}
+
+/**
+ * A provider base URL may carry credentials as userinfo (`https://user:token@host/`), and the
+ * runtime error echoes the URL it was fetching. Strip it before the message reaches a client
+ * or a log line.
+ */
+function redactUrlUserinfo(detail: string): string {
+  return detail.replace(/(https?:\/\/)[^/\s"'@]*@/g, "$1<redacted>@");
+}
+
+function extractHostname(detail: string): string | null {
+  const match = detail.match(/https?:\/\/([^/\s"']+)/);
+  if (!match?.[1]) return null;
+  try {
+    return new URL(`https://${match[1]}`).hostname || null;
+  } catch {
+    return null;
+  }
+}

package/src/server/responses-image-gen-repair.ts

@@ -0,0 +1,132 @@
+import { collectResponsesToolGroups } from "../responses/tool-groups";
+import { relaySseWithPayloadRewrite, type SsePayloadRewrite } from "./sse-payload-rewrite";
+import type { TranslatorBudget } from "../lib/translator-budget";
+
+interface NamespacedTool {
+  namespace: string;
+  name: string;
+}
+
+const IMAGE_GEN_NAMESPACE = "image_gen";
+const IMAGE_GEN_DOTTED_PREFIX = `${IMAGE_GEN_NAMESPACE}.`;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Restrict the generic bridge map to Codex's standalone image namespace and accept the dotted
+ * alias emitted by earlier compatibility attempts. Legacy flat dotted declarations are recovered
+ * from the raw request because the generic parser does not assign them a namespace. Exact declared
+ * names avoid splitting arbitrary double-underscore function names that belong to unrelated tools.
+ */
+export function imageGenToolCallAliases(
+  toolNsMap: ReadonlyMap<string, NamespacedTool>,
+  requestBody?: unknown,
+  translatorBudget?: TranslatorBudget,
+): Map<string, NamespacedTool> {
+  const aliases = new Map<string, NamespacedTool>();
+  const retainAlias = (key: string, tool: NamespacedTool) => {
+    if (aliases.has(key)) {
+      aliases.set(key, tool);
+      return;
+    }
+    translatorBudget?.chargeRetained(
+      Buffer.byteLength(key) + Buffer.byteLength(tool.namespace) + Buffer.byteLength(tool.name),
+      { kind: "request_copies" },
+    );
+    aliases.set(key, tool);
+  };
+  for (const [wireName, tool] of toolNsMap) {
+    if (tool.namespace !== IMAGE_GEN_NAMESPACE) continue;
+    retainAlias(wireName, tool);
+    retainAlias(`${tool.namespace}.${tool.name}`, tool);
+  }
+  for (const group of collectResponsesToolGroups(requestBody)) {
+    for (const tool of group) {
+      if (
+        !isPlainObject(tool)
+        || tool.type !== "function"
+        || typeof tool.name !== "string"
+        || !tool.name.startsWith(IMAGE_GEN_DOTTED_PREFIX)
+        || tool.name.length === IMAGE_GEN_DOTTED_PREFIX.length
+      ) continue;
+      const localName = tool.name.slice(IMAGE_GEN_DOTTED_PREFIX.length);
+      const target = { namespace: IMAGE_GEN_NAMESPACE, name: localName };
+      retainAlias(`${IMAGE_GEN_NAMESPACE}__${localName}`, target);
+      retainAlias(tool.name, target);
+    }
+  }
+  return aliases;
+}
+
+/** Recursively restore only exact image-gen function-call aliases in a parsed Responses payload. */
+function restoreImageGenCalls(
+  value: unknown,
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): { value: unknown; changed: boolean } {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const restored = value.map(entry => {
+      const result = restoreImageGenCalls(entry, aliases);
+      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 = restoreImageGenCalls(entry, aliases);
+    restored[key] = result.value;
+    changed ||= result.changed;
+  }
+
+  const name = typeof value.name === "string" ? value.name : undefined;
+  const target = value.type === "function_call" && name ? aliases.get(name) : undefined;
+  if (target) {
+    restored.name = target.name;
+    restored.namespace = target.namespace;
+    changed = true;
+  }
+  return changed ? { value: restored, changed: true } : { value, changed: false };
+}
+
+/** Restore image-gen function calls in a non-streaming Responses JSON document. */
+export function restoreImageGenCallsInJson(
+  text: string,
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): string {
+  if (aliases.size === 0) return text;
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const restored = restoreImageGenCalls(payload, aliases);
+  return restored.changed ? JSON.stringify(restored.value) : text;
+}
+
+/** Payload rewrite for composition with other client-facing SSE transforms. */
+export function createImageGenCallRestoreRewrite(
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): SsePayloadRewrite | undefined {
+  if (aliases.size === 0) return undefined;
+  return (payload) => restoreImageGenCallsInJson(payload, aliases);
+}
+
+/**
+ * Restore upstream-safe image-gen aliases only on the client-facing SSE branch. The inspection and
+ * continuation-cache branch must retain raw upstream names so a replay can be sent back unchanged.
+ */
+export function relaySseWithImageGenCallRestore(
+  body: ReadableStream<Uint8Array>,
+  aliases: ReadonlyMap<string, NamespacedTool>,
+  translatorBudget: TranslatorBudget,
+): ReadableStream<Uint8Array> {
+  const rewrite = createImageGenCallRestoreRewrite(aliases);
+  return rewrite ? relaySseWithPayloadRewrite(body, rewrite, translatorBudget) : body;
+}

package/src/server/responses-item-id-repair.ts

@@ -0,0 +1,224 @@
+import { randomUUID } from "node:crypto";
+import type { ResponsesItemIdRepairConfig } from "../types";
+import { relaySseWithPayloadRewrite, type SsePayloadRewrite } from "./sse-payload-rewrite";
+import type { TranslatorBudget } from "../lib/translator-budget";
+
+type RepairableItemType = "message" | "reasoning";
+
+interface ResponsesItemIdRepairState {
+  readonly repairMissingTerminalIds: boolean;
+  readonly placeholders: Record<RepairableItemType, ReadonlySet<string>>;
+  readonly outputIds: Record<RepairableItemType, Map<number, string>>;
+  readonly scope: string;
+  readonly budget?: TranslatorBudget;
+}
+
+const REPAIRABLE_PREFIXES: Record<RepairableItemType, string> = {
+  message: "msg_",
+  reasoning: "rs_",
+};
+
+const ITEM_ID_EVENT_TYPES: Readonly<Record<string, RepairableItemType>> = {
+  "response.content_part.added": "message",
+  "response.content_part.done": "message",
+  "response.output_text.annotation.added": "message",
+  "response.output_text.delta": "message",
+  "response.output_text.done": "message",
+  "response.refusal.delta": "message",
+  "response.refusal.done": "message",
+  "response.reasoning_summary_part.added": "reasoning",
+  "response.reasoning_summary_part.done": "reasoning",
+  "response.reasoning_summary_text.delta": "reasoning",
+  "response.reasoning_summary_text.done": "reasoning",
+  "response.reasoning_text.delta": "reasoning",
+  "response.reasoning_text.done": "reasoning",
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function asOutputIndex(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+function repairableItemType(item: Record<string, unknown>): RepairableItemType | null {
+  return item.type === "message" || item.type === "reasoning" ? item.type : null;
+}
+
+function mintCanonicalId(type: RepairableItemType, scope: string, outputIndex: number): string {
+  return `${REPAIRABLE_PREFIXES[type]}ocx_${scope}_${outputIndex}`;
+}
+
+function createRepairState(config: ResponsesItemIdRepairConfig, budget?: TranslatorBudget): ResponsesItemIdRepairState {
+  const state = {
+    repairMissingTerminalIds: config.repairMissingTerminalIds === true,
+    placeholders: {
+      message: new Set(config.message ?? []),
+      reasoning: new Set(config.reasoning ?? []),
+    },
+    outputIds: {
+      message: new Map<number, string>(),
+      reasoning: new Map<number, string>(),
+    },
+    scope: randomUUID().replace(/-/g, ""),
+    budget,
+  };
+  budget?.chargeRetained(new TextEncoder().encode(JSON.stringify({
+    message: [...state.placeholders.message],
+    reasoning: [...state.placeholders.reasoning],
+    scope: state.scope,
+  })).byteLength, { kind: "item_ids" });
+  return state;
+}
+
+function rememberMappedId(
+  state: ResponsesItemIdRepairState,
+  outputIndex: number,
+  item: Record<string, unknown>,
+): string | null {
+  const type = repairableItemType(item);
+  if (!type) return null;
+  const existing = state.outputIds[type].get(outputIndex);
+  if (existing) return existing;
+  const rawId = typeof item.id === "string" ? item.id : undefined;
+  if (!rawId) return null;
+  const mapped = state.placeholders[type].has(rawId)
+    ? mintCanonicalId(type, state.scope, outputIndex)
+    : state.repairMissingTerminalIds
+      ? rawId
+      : null;
+  if (!mapped) return null;
+  state.budget?.chargeRetained(new TextEncoder().encode(JSON.stringify([outputIndex, rawId, mapped])).byteLength, { kind: "item_ids" });
+  state.outputIds[type].set(outputIndex, mapped);
+  return mapped;
+}
+
+function rewriteOutputItem(
+  state: ResponsesItemIdRepairState,
+  outputIndex: number,
+  item: Record<string, unknown>,
+): { item: Record<string, unknown>; changed: boolean } {
+  const mapped = rememberMappedId(state, outputIndex, item);
+  if (!mapped) return { item, changed: false };
+  const currentId = typeof item.id === "string" ? item.id : undefined;
+  if (currentId === mapped) return { item, changed: false };
+  if (currentId === undefined && !state.repairMissingTerminalIds) return { item, changed: false };
+  return { item: { ...item, id: mapped }, changed: true };
+}
+
+function rewriteItemIdField(
+  state: ResponsesItemIdRepairState,
+  event: Record<string, unknown>,
+  outputIndex: number,
+): { event: Record<string, unknown>; changed: boolean } {
+  const eventType = typeof event.type === "string" ? ITEM_ID_EVENT_TYPES[event.type] : undefined;
+  if (!eventType) return { event, changed: false };
+  const mapped = state.outputIds[eventType].get(outputIndex);
+  if (!mapped) return { event, changed: false };
+  const currentId = typeof event.item_id === "string" ? event.item_id : undefined;
+  if (currentId === mapped) return { event, changed: false };
+  if (currentId === undefined && !state.repairMissingTerminalIds) return { event, changed: false };
+  return { event: { ...event, item_id: mapped }, changed: true };
+}
+
+function rewriteResponseSnapshot(
+  state: ResponsesItemIdRepairState,
+  response: Record<string, unknown>,
+): { response: Record<string, unknown>; changed: boolean } {
+  if (!Array.isArray(response.output)) return { response, changed: false };
+  let changed = false;
+  const output = response.output.map((item, outputIndex) => {
+    if (!isPlainObject(item)) return item;
+    const rewritten = rewriteOutputItem(state, outputIndex, item);
+    changed = changed || rewritten.changed;
+    return rewritten.item;
+  });
+  return changed ? { response: { ...response, output }, changed: true } : { response, changed: false };
+}
+
+function repairEventPayload(
+  payload: string,
+  state: ResponsesItemIdRepairState,
+): string {
+  let event: unknown;
+  try {
+    event = JSON.parse(payload);
+  } catch {
+    return payload;
+  }
+  if (!isPlainObject(event)) return payload;
+
+  let changed = false;
+  let nextEvent = event;
+  const outputIndex = asOutputIndex(event.output_index);
+  if (outputIndex !== null && isPlainObject(event.item)) {
+    const rewritten = rewriteOutputItem(state, outputIndex, event.item);
+    if (rewritten.changed) {
+      nextEvent = { ...nextEvent, item: rewritten.item };
+      changed = true;
+    }
+  }
+  if (outputIndex !== null) {
+    const rewritten = rewriteItemIdField(state, nextEvent, outputIndex);
+    if (rewritten.changed) {
+      nextEvent = rewritten.event;
+      changed = true;
+    }
+  }
+  if (isPlainObject(event.response)) {
+    const rewritten = rewriteResponseSnapshot(state, event.response);
+    if (rewritten.changed) {
+      nextEvent = { ...nextEvent, response: rewritten.response };
+      changed = true;
+    }
+  }
+  if (!changed) return payload;
+  const rewritten = JSON.stringify(nextEvent);
+  const bytes = new TextEncoder().encode(rewritten).byteLength;
+  const reservation = state.budget?.reserveTransient(bytes, { kind: "item_ids" });
+  reservation?.commitRetained();
+  if (state.budget) queueMicrotask(() => state.budget?.releaseRetained(bytes, { kind: "item_ids" }));
+  return rewritten;
+}
+
+/**
+ * [Decision Log]
+ * - 목적과 의도: 일부 openai-responses 호환 게이트웨이가 재사용/누락하는 message·reasoning item id를
+ *   downstream SSE에서만 선택적으로 보정해 Codex Desktop 카드 상관관계를 안정화한다.
+ * - 기존 구현 및 제약 조건: 기본 passthrough는 바이트 단위 그대로 relay되고, local replay 상태는 raw
+ *   upstream 응답을 기억한다. function_call id / call_id는 upstream 의미가 있으므로 절대 바꾸면 안 된다.
+ * - 검토한 주요 대안: 모든 passthrough SSE를 항상 재작성하기, raw inspect 분기까지 함께 재작성하기,
+ *   function_call 포함 전체 item id를 정규화하기.
+ * - 선택한 방식: provider-local opt-in 설정이 있을 때만 client-facing SSE 분기에 한정해 exact
+ *   message/reasoning placeholder id와 missing terminal id를 item type + output_index 기준으로 보정하고,
+ *   event-level item_id는 명시적인 message/reasoning lifecycle allowlist에서만 바꾼다.
+ * - 다른 대안 대신 이 방식을 선택한 이유: disabled-by-default byte-for-byte passthrough를 유지하면서,
+ *   previous_response_id replay는 raw upstream snapshot을 계속 사용해 synthetic id가 upstream으로
+ *   역류하지 않게 막을 수 있다.
+ * - 장점, 단점 및 영향: 기본 경로는 변하지 않는다. malformed stream이 output_index를 다른 item
+ *   type에 재사용해도 function_call id/call_id는 보존된다. opt-in 게이트웨이는 sequential streams에서도
+ *   고유한 canonical id를 얻지만, 보정이 필요한 경우에만 JS stream 재작성 비용을 지불한다.
+ */
+/** Stateful payload rewrite for composition with other client-facing SSE transforms. */
+export function createResponsesItemIdPayloadRewrite(
+  config: ResponsesItemIdRepairConfig,
+  budget?: TranslatorBudget,
+): SsePayloadRewrite {
+  const state = createRepairState(config, budget);
+  return (payload) => repairEventPayload(payload, state);
+}
+
+export function relaySseWithResponsesItemIdRepair(
+  body: ReadableStream<Uint8Array>,
+  config: ResponsesItemIdRepairConfig,
+  budget: TranslatorBudget,
+): ReadableStream<Uint8Array> {
+  return relaySseWithPayloadRewrite(body, createResponsesItemIdPayloadRewrite(config, budget), budget);
+}
+
+export function hasResponsesItemIdRepair(config: ResponsesItemIdRepairConfig | undefined): boolean {
+  return config?.repairMissingTerminalIds === true
+    || (config?.message?.length ?? 0) > 0
+    || (config?.reasoning?.length ?? 0) > 0;
+}

package/src/server/responses.ts

@@ -0,0 +1,9 @@
+// AUTO-SPLIT facade: original responses.ts body moved into ./responses/* modules.
+// Public surface preserved exactly; importers keep using "src/server/responses".
+export { buildToolBridgeMaps, isV1CollabSurface, collabSurface, multiAgentGuidanceText, V2_GUIDANCE_CHAR_BUDGET, injectDeveloperMessage } from "./responses/collaboration";
+export type { MultiAgentGuidanceOptions, MultiAgentGuidanceDeps } from "./responses/collaboration";
+export { hasUnreadableEncryptedAgentTask, sanitizeEncryptedContentInPlace } from "./responses/encrypted-payload";
+export { COMPACT_RESPONSE_MAX_BYTES, bufferCompactResponse, handleResponsesCompact } from "./responses/compact";
+export { disableResponsesRequestTimeout, safeHostLabel, fetchWithHeaderTimeout } from "./responses/fetch-helpers";
+export { sidecarOutcomeRecorder, isShadowSourceModel, codexLogAccountId, usesCodexForwardPoolAuth, codexForwardTerminalOutcomeRecorder, decodeRequestErrorResponse, buildComboChildHeaders, handleResponses, linkAbortSignal } from "./responses/core";
+export { adapterNeedsForcedContinuation } from "./responses/core";