@iislee/opencodex 2.11.0 → 2.31.0

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

@@ -7,8 +7,11 @@ 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;
 }
@@ -53,6 +56,7 @@ function mintCanonicalId(type: RepairableItemType, scope: string, outputIndex: n
 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 ?? []),
@@ -61,6 +65,7 @@ function createRepairState(config: ResponsesItemIdRepairConfig, budget?: Transla
       message: new Map<number, string>(),
       reasoning: new Map<number, string>(),
     },
+    rawIds: new Map<string, string>(),
     scope: randomUUID().replace(/-/g, ""),
     budget,
   };
@@ -85,12 +90,19 @@ function rememberMappedId(
   if (!rawId) return null;
   const mapped = state.placeholders[type].has(rawId)
     ? mintCanonicalId(type, state.scope, outputIndex)
-    : state.repairMissingTerminalIds
-      ? rawId
-      : null;
+    : 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;
 }
 
@@ -114,11 +126,24 @@ function rewriteItemIdField(
 ): { 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 };
-  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 };
 }
 
@@ -219,6 +244,29 @@ export function relaySseWithResponsesItemIdRepair(
 
 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);
+}

package/src/server/responses-reasoning-summary-rewrite.ts

@@ -0,0 +1,178 @@
+import type { SsePayloadRewrite } from "./sse-payload-rewrite";
+
+/**
+ * Route content-channel reasoning from native-Responses upstreams through the
+ * expandable summary channel (issue #45).
+ *
+ * Codex renders the expandable reasoning trace from the Responses reasoning
+ * item's `summary[]` channel. DeepSeek's native `/responses` endpoint emits
+ * raw thinking on the content channel instead (`response.reasoning_text.delta`
+ * plus items with `content: [{type: "reasoning_text", text}]` and an empty
+ * `summary`), so routed DeepSeek turns showed the "Worked for Xs" timer with
+ * nothing to expand. Native OpenAI upstreams already emit summary-channel
+ * events; this rewrite is a no-op for them (no reasoning_text events to
+ * rewrite) and only engages when the upstream produces content-channel
+ * reasoning.
+ *
+ * Replay compatibility: Codex echoes the reasoning item it received back into
+ * the next request's input. DeepSeek's Responses API accepts summary-shaped
+ * reasoning input items (verified live), so the rewrite round-trips.
+ */
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function reasoningTextOf(item: Record<string, unknown>): string {
+  if (!Array.isArray(item.content)) return "";
+  return item.content
+    .filter((part): part is Record<string, unknown> => isPlainObject(part) && part.type === "reasoning_text")
+    .map(part => (typeof part.text === "string" ? part.text : ""))
+    .join("");
+}
+
+/** Move a reasoning item's content channel into the summary channel. */
+function reasoningItemToSummaryShape(item: Record<string, unknown>): Record<string, unknown> {
+  if (item.type !== "reasoning") return item;
+  // `encrypted_content` is opaque, state-bearing provider data, so the entire item must retain its
+  // upstream shape unless that backend has an explicit replay contract permitting a rewrite. This
+  // defensively protects content-channel backends that do issue blobs when the client replays the
+  // stored item. The delta rewrite can still provide the expandable trace for the live turn.
+  // DeepSeek — the provider this rewrite was verified against — is `statelessResponses` and issues
+  // no blob, so it is unaffected.
+  if (typeof item.encrypted_content === "string" && item.encrypted_content.length > 0) return item;
+  const text = reasoningTextOf(item);
+  // Items that already use the summary channel (or carry no content text at
+  // all) are left untouched: rewriting them could clear a valid summary.
+  if (text.length === 0) return item;
+  const next: Record<string, unknown> = { ...item };
+  delete next.content;
+  next.summary = [{ type: "summary_text", text }];
+  return next;
+}
+
+/**
+ * Rewrite one parsed SSE payload in place of the content channel, or return
+ * `null` when nothing changed (caller keeps the original payload).
+ */
+function rewritePayload(payload: Record<string, unknown>): Record<string, unknown> | null {
+  switch (payload.type) {
+    case "response.reasoning_text.delta": {
+      const next: Record<string, unknown> = {
+        type: "response.reasoning_summary_text.delta",
+        item_id: payload.item_id,
+        output_index: payload.output_index,
+        summary_index: 0,
+        delta: payload.delta,
+      };
+      if (payload.sequence_number !== undefined) next.sequence_number = payload.sequence_number;
+      return next;
+    }
+    case "response.reasoning_text.done": {
+      const next: Record<string, unknown> = {
+        type: "response.reasoning_summary_text.done",
+        item_id: payload.item_id,
+        output_index: payload.output_index,
+        summary_index: 0,
+        text: payload.text,
+      };
+      if (payload.sequence_number !== undefined) next.sequence_number = payload.sequence_number;
+      return next;
+    }
+    default: {
+      let changed = false;
+      const next: Record<string, unknown> = { ...payload };
+      if (isPlainObject(next.item) && next.item.type === "reasoning") {
+        const rewritten = reasoningItemToSummaryShape(next.item);
+        if (rewritten !== next.item) {
+          next.item = rewritten;
+          changed = true;
+        }
+      }
+      // SSE event shape: {type: "response.completed", response: {output}}.
+      const response = isPlainObject(next.response) ? { ...next.response } : null;
+      if (response && Array.isArray(response.output)) {
+        const output = response.output.map(item => {
+          if (!isPlainObject(item) || item.type !== "reasoning") return item;
+          const rewritten = reasoningItemToSummaryShape(item);
+          if (rewritten !== item) changed = true;
+          return rewritten;
+        });
+        if (changed) {
+          response.output = output;
+          next.response = response;
+        }
+      }
+      // Bare response document shape (non-streaming passthrough):
+      // {object: "response", output: [...]}.
+      if (Array.isArray(next.output)) {
+        const output = next.output.map(item => {
+          if (!isPlainObject(item) || item.type !== "reasoning") return item;
+          const rewritten = reasoningItemToSummaryShape(item);
+          if (rewritten !== item) changed = true;
+          return rewritten;
+        });
+        if (changed) next.output = output;
+      }
+      return changed ? next : null;
+    }
+  }
+}
+
+/** Payload rewrite for passthrough relays whose upstream emits content-channel reasoning. */
+export function createReasoningSummaryChannelPayloadRewrite(): SsePayloadRewrite {
+  return (payload: string): string => {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(payload);
+    } catch {
+      return payload;
+    }
+    if (!isPlainObject(parsed)) return payload;
+    const rewritten = rewritePayload(parsed);
+    return rewritten !== null ? JSON.stringify(rewritten) : payload;
+  };
+}
+
+/**
+ * Object-level variant for the non-streaming passthrough: the bounded-JSON
+ * relay bypasses the SSE payload rewrite, so reasoning items inside a full
+ * Responses JSON document need the same normalization before plain JSON
+ * serialization or forced JSON-to-SSE reframing. Returns the same reference
+ * when nothing changed.
+ */
+export function rewriteReasoningSummaryInJson(value: unknown): unknown {
+  if (!isPlainObject(value)) return value;
+  const rewritten = rewritePayload(value);
+  return rewritten !== null ? rewritten : value;
+}
+
+/** String-level variant of {@link rewriteReasoningSummaryInJson}. */
+export function rewriteReasoningSummaryInJsonString(json: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return json;
+  }
+  const rewritten = rewriteReasoningSummaryInJson(parsed);
+  return rewritten === parsed ? json : JSON.stringify(rewritten);
+}
+
+/**
+ * True when a routed native-Responses provider emits content-channel reasoning
+ * (raw `reasoning_text`) instead of the summary channel. DeepSeek's
+ * `/responses` endpoint is the current example: it ships raw thinking with an
+ * empty `summary` and keeps `preserveReasoningContentModels` so multi-turn
+ * replays round-trip.
+ */
+export function routeUsesContentChannelReasoning(
+  provider: { statelessResponses?: boolean; preserveReasoningContentModels?: string[] },
+  modelId: string,
+): boolean {
+  if (provider.statelessResponses === true) return true;
+  const preserved = provider.preserveReasoningContentModels;
+  const normalizedModelId = modelId.toLowerCase();
+  return Array.isArray(preserved)
+    && preserved.some(id => id.toLowerCase() === normalizedModelId);
+}