@yansigit/opencodex 2.31.0

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,272 @@
+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 repairInvalidIds: boolean;
+  readonly placeholders: Record<RepairableItemType, ReadonlySet<string>>;
+  readonly outputIds: Record<RepairableItemType, Map<number, string>>;
+  /** JSON [outputIndex, rawId] -> canonical id, for exact item_id rewrites on part/delta events. */
+  readonly rawIds: Map<string, 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,
+    repairInvalidIds: config.repairInvalidIds === true,
+    placeholders: {
+      message: new Set(config.message ?? []),
+      reasoning: new Set(config.reasoning ?? []),
+    },
+    outputIds: {
+      message: new Map<number, string>(),
+      reasoning: new Map<number, string>(),
+    },
+    rawIds: new Map<string, 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.repairInvalidIds && !rawId.startsWith(REPAIRABLE_PREFIXES[type])
+      // An existing id without the canonical msg_/rs_ prefix (bare UUIDs from
+      // DeepSeek's Responses route) leaves Codex stuck on Thinking (#938).
+      ? 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);
+  // Keyed by (index, rawId): an upstream that reuses one placeholder id across
+  // several items must not collapse them into the last item's canonical id.
+  if (rawId !== mapped) state.rawIds.set(JSON.stringify([outputIndex, rawId]), 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 currentId = typeof event.item_id === "string" ? event.item_id : undefined;
+  // content_part.* events are shared between message and reasoning items (DeepSeek's
+  // streamed reasoning wraps its text in content parts), so the static event-type map
+  // can point at the wrong id table. The rewrite is therefore exact-only when the
+  // event carries an item_id: it fires when (output_index, item_id) names an id the
+  // item stream already repaired, and otherwise leaves the event alone — an unknown
+  // id belongs to an item this repair never touched (function_call, already-canonical
+  // ids), and guessing by index could borrow a sibling item's identity. The index
+  // table serves only events with NO item_id, where repairMissingTerminalIds
+  // explicitly opts into the positional guess (the pre-existing contract).
+  if (currentId !== undefined) {
+    const mapped = state.rawIds.get(JSON.stringify([outputIndex, currentId]));
+    if (!mapped || currentId === mapped) return { event, changed: false };
+    return { event: { ...event, item_id: mapped }, changed: true };
+  }
+  if (!state.repairMissingTerminalIds) return { event, changed: false };
+  const mapped = state.outputIds[eventType].get(outputIndex);
+  if (!mapped) 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?.repairInvalidIds === true
+    || (config?.message?.length ?? 0) > 0
+    || (config?.reasoning?.length ?? 0) > 0;
+}
+
+/**
+ * Client-facing id normalization for a WHOLE bounded-JSON Responses object.
+ *
+ * The bounded-JSON policy (#875) answers a streaming client by synthesizing SSE
+ * from a completed JSON body, and reframes the same body into events for WS
+ * turns. Neither path goes through the SSE relay, so neither picks up the SSE
+ * item-id rewrite — a provider that needs id repair would get it on a streaming
+ * response and silently lose it the moment the reliability policy switched the
+ * upstream to bounded JSON. This applies the same rewrite to the object so all
+ * three paths agree. Raw recorded state is untouched: recording happens before
+ * any normalization.
+ */
+export function repairResponsesJsonItemIds(
+  response: Record<string, unknown>,
+  config: ResponsesItemIdRepairConfig,
+  budget?: TranslatorBudget,
+): Record<string, unknown> {
+  const state = createRepairState(config, budget);
+  const rewritten = rewriteResponseSnapshot(state, response);
+  return rewritten.changed ? rewritten.response : response;
+}

package/src/server/responses-json-events.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared bounded-JSON → Responses event sequence (#875): the same pure event
+ * list used by the WebSocket bridge (sendResponsesJsonAsEvents) and by the
+ * HTTP SSE synthesis for models whose reliability policy forces a bounded
+ * JSON upstream. One algorithm, two serializations — no duplicated drift.
+ */
+
+export type ResponsesJsonEventFrame = Record<string, unknown>;
+
+export const MAX_SYNTHESIZED_OUTPUT_ITEMS = 10_000;
+
+/**
+ * The canonical minimal sequence Codex commits: response.created (empty
+ * output, in_progress) → one response.output_item.done per output item → a
+ * status-preserving terminal (completed / failed / incomplete).
+ */
+export function responsesJsonEventSequence(
+  response: Record<string, unknown>,
+  rewritePayload?: (payload: Record<string, unknown>) => Record<string, unknown>,
+): ResponsesJsonEventFrame[] {
+  return [...iterateResponsesJsonEvents(response, rewritePayload)];
+}
+
+function* iterateResponsesJsonEvents(
+  response: Record<string, unknown>,
+  rewritePayload?: (payload: Record<string, unknown>) => Record<string, unknown>,
+): Generator<ResponsesJsonEventFrame> {
+  const rewrite = rewritePayload ?? ((payload: Record<string, unknown>) => payload);
+  const output = Array.isArray(response.output) ? response.output : [];
+  if (output.length > MAX_SYNTHESIZED_OUTPUT_ITEMS) {
+    throw new RangeError(
+      `Responses JSON output contains ${output.length} items; maximum is ${MAX_SYNTHESIZED_OUTPUT_ITEMS}`,
+    );
+  }
+  const finalStatus = response.status === "failed" || response.status === "incomplete"
+    ? response.status
+    : "completed";
+  yield rewrite({
+    type: "response.created",
+    response: { ...response, status: "in_progress", output: [] },
+  });
+  for (const [outputIndex, item] of output.entries()) {
+    yield rewrite({
+      type: "response.output_item.done",
+      output_index: outputIndex,
+      item,
+    });
+  }
+  yield rewrite({
+    type: `response.${finalStatus}`,
+    response: { ...response, status: finalStatus },
+  });
+}
+
+/**
+ * Serialize the event sequence as one SSE body with exactly one
+ * `data: [DONE]\n\n` trailer.
+ */
+export function responsesJsonToSseBody(
+  response: Record<string, unknown>,
+  rewritePayload?: (payload: Record<string, unknown>) => Record<string, unknown>,
+): string {
+  const frames = responsesJsonEventSequence(response, rewritePayload)
+    .map(frame => `data: ${JSON.stringify(frame)}\n\n`);
+  return `${frames.join("")}data: [DONE]\n\n`;
+}
+
+/** Stream synthesized SSE frames without retaining the expanded body in memory. */
+export function responsesJsonToSseStream(
+  response: Record<string, unknown>,
+  rewritePayload?: (payload: Record<string, unknown>) => Record<string, unknown>,
+): ReadableStream<Uint8Array> {
+  const output = Array.isArray(response.output) ? response.output : [];
+  if (output.length > MAX_SYNTHESIZED_OUTPUT_ITEMS) {
+    throw new RangeError(
+      `Responses JSON output contains ${output.length} items; maximum is ${MAX_SYNTHESIZED_OUTPUT_ITEMS}`,
+    );
+  }
+  const frames = iterateResponsesJsonEvents(response, rewritePayload);
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    pull(controller) {
+      const next = frames.next();
+      controller.enqueue(encoder.encode(
+        next.done ? "data: [DONE]\n\n" : `data: ${JSON.stringify(next.value)}\n\n`,
+      ));
+      if (next.done) controller.close();
+    },
+  });
+}

package/src/server/responses-model-rewrite.ts

@@ -0,0 +1,29 @@
+import type { SsePayloadRewrite } from "./sse-payload-rewrite";
+
+function rewriteResponseObjectModel(value: unknown, responseModelId: string): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const response = value as Record<string, unknown>;
+  if (typeof response.model !== "string" || response.model === responseModelId) return false;
+  response.model = responseModelId;
+  return true;
+}
+
+/** Rewrite only existing Responses model metadata; unrelated and malformed payloads stay byte-identical. */
+export function rewriteResponsesModelJson(json: string, responseModelId: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return json;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return json;
+  const record = parsed as Record<string, unknown>;
+  const rootChanged = rewriteResponseObjectModel(record, responseModelId);
+  const nestedChanged = rewriteResponseObjectModel(record.response, responseModelId);
+  const changed = rootChanged || nestedChanged;
+  return changed ? JSON.stringify(record) : json;
+}
+
+export function createResponsesModelPayloadRewrite(responseModelId: string): SsePayloadRewrite {
+  return payload => rewriteResponsesModelJson(payload, responseModelId);
+}