@iislee/opencodex 2.11.0 → 2.35.0

package/src/server/responses/responses-field-backfill.ts

@@ -0,0 +1,343 @@
+/**
+ * Stateless SSE block rewrite that backfills the `annotations` field on
+ * `output_text` content parts in Responses SSE events.
+ *
+ * The Responses API spec defines `annotations` as a required field on
+ * `OutputTextContent` (it is `Vec<Annotation>`, not `Option<Vec>`). Some
+ * upstream relays omit it when there are no annotations, which is technically
+ * spec-non-compliant. Strict deserializers — any client that follows the
+ * schema without `#[serde(default)]` on that field — fail with
+ * `missing field `annotations`` when the field is absent.
+ *
+ * This rewrite scans every SSE event for output_text content parts — whether
+ * they appear in item.content[], part, or response.output[].content[] — and
+ * adds annotations: [] if missing.
+ *
+ * Stateless: no retained buffers, no lifecycle tracking, no fail-closed.
+ * Existing values are always authoritative; only absent fields are added.
+ * The field is always valid on the wire, so adding it when absent is safe
+ * for all clients including Codex CLI/App.
+ */
+
+import {
+  replaceSseDataPayload,
+  sseDataPayload,
+  type SseBlockRewrite,
+} from "../sse-payload-rewrite";
+import { isCompactionItemType } from "../../responses/compaction";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Wire prefixes for Responses output item ids, matching OpenAI's id shapes. */
+const ITEM_ID_PREFIXES: Readonly<Record<string, string>> = {
+  message: "msg_",
+  reasoning: "rs_",
+  function_call: "fc_",
+  custom_tool_call: "ctc_",
+  // A routed tool_search lowering is restored to `tool_search_call` without an id, so this
+  // backfill is what names it. The generic `item_` fallback is not merely cosmetic here:
+  // `stripInvalidItemIds` in the Responses adapter deletes any id whose prefix does not match
+  // the type, so an `item_`-named tool_search_call silently loses its id on the NEXT turn and
+  // the client sees an item it cannot correlate. The prefixes here must stay a superset of the
+  // ones that serializer enforces.
+  tool_search_call: "tsc_",
+  web_search_call: "ws_",
+  file_search_call: "fs_",
+  code_interpreter_call: "ci_",
+  computer_call: "cc_",
+  // The Responses wire type is `image_generation_call`; `image_gen_call` is kept only so a
+  // relay that emits the short spelling is not silently demoted to the generic `item_`.
+  image_generation_call: "ig_",
+  image_gen_call: "ig_",
+};
+
+/**
+ * Backfill a required id on an output item when absent. Strict Responses
+ * decoders (e.g. grok-build serde types) fail with "missing field id" when a
+ * message or reasoning item has no id, which some upstream relays omit. The
+ * generated id is deterministic per (type, output index) so it stays stable
+ * across streaming events that reference the same item.
+ */
+function backfillItemId(item: Record<string, unknown>, slot: ItemIdSlot): Record<string, unknown> {
+  if (typeof item.id === "string" && item.id.length > 0) return item;
+  const type = typeof item.type === "string" ? item.type : "";
+  const prefix = Object.prototype.hasOwnProperty.call(ITEM_ID_PREFIXES, type) ? ITEM_ID_PREFIXES[type] : "item_";
+  return { ...item, id: prefix + "ocx_" + (slot.kind === "index" ? String(slot.index) : "fallback_" + slot.ordinal) };
+}
+
+/**
+ * Which namespace a synthesized id comes from.
+ *
+ * Keeping the fallback counter in the SAME numeric namespace as real output indexes only
+ * pushed the collision out of reach rather than removing it: a response whose real index
+ * happened to be 1_000_001 would produce the same id as the first malformed-index fallback,
+ * and a duplicate id is exactly what this backfill exists to prevent. The namespaces are now
+ * lexically disjoint, so no index value can ever collide with a fallback.
+ */
+type ItemIdSlot = { kind: "index"; index: number } | { kind: "fallback"; ordinal: number };
+
+/**
+ * Monotonic ordinal for an event whose `output_index` is absent or malformed.
+ *
+ * Process-global rather than per-response because this module is stateless by design and the
+ * value only has to be unique, not meaningful. It carries its own `fallback_` namespace, so
+ * uniqueness no longer depends on a real index never reaching some arbitrary ceiling.
+ */
+let syntheticItemOrdinal = 0;
+function nextSyntheticItemSlot(): ItemIdSlot {
+  syntheticItemOrdinal += 1;
+  return { kind: "fallback", ordinal: syntheticItemOrdinal };
+}
+
+/**
+ * Backfill `status` on a message output item if missing.
+ *
+ * The Responses API spec defines `status` as a required field on
+ * `OutputMessage`. Some upstream relays omit it, which causes strict
+ * deserializers (e.g. grok-build's serde types) to fail with
+ * `missing field 'status'`. Only message items carry this field in the
+ * Responses schema; reasoning, function_call, and other item types do not.
+ *
+ * The value is inferred from the event context: `output_item.added` and
+ * `response.created` / `response.in_progress` mean the message is still
+ * being generated (`in_progress`); `output_item.done` and
+ * `response.completed` / `response.incomplete` mean the message is
+ * finalized (`completed` / `incomplete` respectively).
+ *
+ * Returns the same object reference if no change is needed.
+ */
+function backfillItemStatus(item: Record<string, unknown>, inferredStatus: string): Record<string, unknown> {
+  if (item.type !== "message") return item;
+  if ("status" in item) return item;
+  return { ...item, status: inferredStatus };
+}
+
+/**
+ * Backfill annotations: [] on an output_text content part if missing.
+ * Returns the same object reference if no change is needed.
+ */
+function backfillOutputTextPart(part: Record<string, unknown>): Record<string, unknown> {
+  if (part.type !== "output_text") return part;
+  // Only add annotations when the key is entirely absent — preserve any
+  // existing value (even null or a malformed type) so we never overwrite
+  // what the upstream actually sent.
+  if ("annotations" in part) return part;
+  return { ...part, annotations: [] };
+}
+
+/**
+ * Walk a content array and backfill output_text parts.
+ * Returns the same array reference if nothing changed.
+ */
+function backfillContentArray(content: unknown): unknown {
+  if (!Array.isArray(content)) return content;
+  let changed = false;
+  const repaired = content.map((part) => {
+    if (!isPlainObject(part)) return part;
+    const next = backfillOutputTextPart(part);
+    if (next !== part) changed = true;
+    return next;
+  });
+  return changed ? repaired : content;
+}
+
+/**
+ * Walk an output item and backfill output_text parts in its content.
+ * Also backfills a missing required id and status on the item itself.
+ * Returns the same object reference if nothing changed.
+ */
+function backfillOutputItem(item: unknown, slot: ItemIdSlot, inferredStatus: string): unknown {
+  if (!isPlainObject(item)) return item;
+  // The compact wire family is the `/v1/responses/compact` format, not a Responses output item.
+  // Those items have no `id` in that contract, so synthesizing one changes a response body the
+  // client compares exactly — and the client replays the item on every later turn, where the
+  // minting backend rejects it as modified. The backfill exists to satisfy strict Responses
+  // decoders; a shape those decoders never see is outside its remit.
+  if (isCompactionItemType(item.type)) return item;
+  const content = item.content;
+  const repaired = backfillContentArray(content);
+  const withId = backfillItemId(item, slot);
+  const withStatus = backfillItemStatus(withId, inferredStatus);
+  if (repaired === content && withStatus === item) return item;
+  return { ...withStatus, ...(repaired === content ? {} : { content: repaired }) };
+}
+
+/**
+ * Walk a response object's output[] and backfill output_text parts.
+ *
+ * `inferredItemStatus` is the status to backfill on message items that lack
+ * one — derived from the event type so `output_item.added` / `response.created`
+ * gets `in_progress` while `output_item.done` / `response.completed` gets
+ * `completed`.
+ *
+ * Deliberately does NOT backfill `created_at`. #2639 proposed it for the same
+ * strict-decoder reason as `status`, but the proxy also relays some upstream
+ * responses verbatim, and `tests/server-combo-failover-e2e.test.ts` asserts a
+ * combo backup response is returned byte-exact. Injecting a field the upstream
+ * never sent breaks that contract. Both cannot hold for the same body, so the
+ * `created_at` half needs its own decision about which contract yields; it is
+ * not a detail to slip in beside `status`.
+ *
+ * Returns the same object reference if nothing changed.
+ */
+function backfillResponseOutput(response: unknown, inferredItemStatus: string): unknown {
+  if (!isPlainObject(response)) return response;
+  const output = response.output;
+  if (!Array.isArray(output)) return response;
+  let changed = false;
+  const repaired = output.map((item, idx) => {
+    if (!isPlainObject(item)) return item;
+    const next = backfillOutputItem(item, { kind: "index", index: idx }, inferredItemStatus);
+    if (next !== item) changed = true;
+    return next;
+  });
+  return changed ? { ...response, output: repaired } : response;
+}
+
+/**
+ * Infer the status to backfill on a message item from the event type.
+ *
+ * `output_item.added` means the item is still being generated (`in_progress`);
+ * `output_item.done` means it is finalized (`completed`). Response-level events
+ * infer from the response's own status field — which is authoritative when present.
+ * If the response status is also absent, the event type itself determines the phase:
+ * `response.created` / `response.in_progress` → `in_progress`,
+ * `response.completed` → `completed`, `response.incomplete` → `incomplete`.
+ */
+function inferredStatusForEventType(eventType: string): string {
+  if (eventType === "response.output_item.added") return "in_progress";
+  if (eventType === "response.output_item.done") return "completed";
+  if (eventType === "response.created" || eventType === "response.in_progress") return "in_progress";
+  // `queued` is a real Responses lifecycle status: the response exists but has not
+  // started generating. Without this row it falls through to the `completed`
+  // default below, which would mark an unstarted message as finished.
+  if (eventType === "response.queued") return "in_progress";
+  if (eventType === "response.incomplete" || eventType === "response.failed") return "incomplete";
+  return "completed";
+}
+
+/**
+ * Map a response-level lifecycle status to a valid OutputMessage status.
+ *
+ * `OutputMessage.status` accepts only `in_progress`, `completed`, or
+ * `incomplete`. Response-level statuses like `failed` or `cancelled` have no
+ * direct message-level equivalent, but `incomplete` is the correct semantic
+ * mapping: the message did not finish generating. Writing `completed` would
+ * assert something the upstream never claimed — a client branching on
+ * `status === "completed"` would treat a truncated message as whole.
+ */
+function messageStatusFromResponseStatus(status: string): string | null {
+  if (status === "in_progress" || status === "completed" || status === "incomplete") return status;
+  // A queued response has not begun generating, so its message items are
+  // in_progress — never completed. Returning null here would fall back to the
+  // event-type inference, whose default is `completed`.
+  if (status === "queued") return "in_progress";
+  if (status === "failed" || status === "cancelled") return "incomplete";
+  return null;
+}
+
+/**
+ * Statelessly rewrite one SSE event: backfill annotations
+ * on any output_text content part found in the event payload.
+ */
+function rewriteEvent(event: Record<string, unknown>): Record<string, unknown> {
+  const type = typeof event.type === "string" ? event.type : "";
+  const inferredItemStatus = inferredStatusForEventType(type);
+  let next = event;
+  let changed = false;
+
+  // output_item.added / output_item.done: item.content[] -> output_text parts
+  if ((type === "response.output_item.added" || type === "response.output_item.done")
+    && isPlainObject(event.item)) {
+    const rawIndex = event.output_index;
+    // A malformed or absent `output_index` must not collapse to 0: two such events would then
+    // both synthesize `msg_ocx_0`, and duplicate ids are the very thing this backfill exists to
+    // prevent. Fall back to a per-process counter so the synthesized id stays unique. Position
+    // is not recoverable in that case, but a unique id is what strict decoders require, and a
+    // well-formed stream still gets the stable index-derived id.
+    const item = typeof rawIndex === "number" && Number.isInteger(rawIndex) && rawIndex >= 0
+      ? backfillOutputItem(event.item, { kind: "index", index: rawIndex }, inferredItemStatus)
+      : backfillOutputItem(event.item, nextSyntheticItemSlot(), inferredItemStatus);
+    if (item !== event.item) {
+      next = { ...next, item };
+      changed = true;
+    }
+  }
+
+  // content_part.added / content_part.done: part -> output_text
+  if ((type === "response.content_part.added" || type === "response.content_part.done")
+    && isPlainObject(event.part)) {
+    const part = backfillOutputTextPart(event.part);
+    if (part !== event.part) {
+      next = { ...next, part };
+      changed = true;
+    }
+  }
+
+  // response.created / in_progress / completed / incomplete / failed:
+  // response.output[].content[] -> output_text parts
+  if (isPlainObject(event.response)) {
+    // For response-level events, prefer the response's own status when it is a valid
+    // OutputMessage status. Response lifecycle statuses like "failed" or "cancelled"
+    // have no message-level equivalent — fall back to the event-type inference instead.
+    const responseStatus = typeof event.response.status === "string"
+      ? messageStatusFromResponseStatus(event.response.status) ?? inferredItemStatus
+      : inferredItemStatus;
+    const response = backfillResponseOutput(event.response, responseStatus);
+    if (response !== event.response) {
+      next = { ...next, response };
+      changed = true;
+    }
+  }
+
+  return changed ? next : event;
+}
+
+/**
+ * Create a stateless SSE block rewrite that backfills annotations and
+ * message status on output_text content parts and message items.
+ * Unconditional: both are required canonical Responses fields, so adding
+ * them when absent is safe for all clients.
+ */
+export function createResponsesFieldBackfillBlockRewrite(): SseBlockRewrite {
+  const rewrite: SseBlockRewrite = (block: string): readonly string[] => {
+    const payload = sseDataPayload(block);
+    if (payload === null) return [block];
+    let event: unknown;
+    try {
+      event = JSON.parse(payload);
+    } catch {
+      return [block];
+    }
+    if (!isPlainObject(event)) return [block];
+    const rewritten = rewriteEvent(event);
+    if (rewritten === event) return [block];
+    return [replaceSseDataPayload(block, JSON.stringify(rewritten))];
+  };
+  return rewrite;
+}
+
+/**
+ * Backfill annotations on a non-streaming Responses JSON
+ * object. Mirrors the SSE block rewrite for the bounded-JSON passthrough
+ * path. Returns the original string if no change is needed.
+ */
+export function backfillResponsesFieldsJson(payload: string): string {
+  let response: unknown;
+  try {
+    response = JSON.parse(payload);
+  } catch {
+    return payload;
+  }
+  if (!isPlainObject(response)) return payload;
+  // For a non-streaming response, derive the item status from the response's own
+  // status field when it is a valid OutputMessage status; fall back to "completed".
+  const inferredItemStatus = typeof response.status === "string"
+    ? messageStatusFromResponseStatus(response.status) ?? "completed"
+    : "completed";
+  const repaired = backfillResponseOutput(response, inferredItemStatus);
+  if (repaired === response) return payload;
+  return JSON.stringify(repaired);
+}

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

@@ -117,7 +117,7 @@ export function analyzeTerminalTurn(parsed: OcxParsedRequest, events: readonly A
   return { decision: "continue", reason: "suspicious_no_tool", assistantText: text, userText, hasToolCall };
 }
 
-function assistantMessageFromEvents(events: readonly AdapterEvent[]): OcxAssistantMessage | undefined {
+function assistantMessageFromEvents(events: readonly AdapterEvent[], timestamp: number): OcxAssistantMessage | undefined {
   let text = "";
   let thinking = "";
   let signature: string | undefined;
@@ -134,14 +134,18 @@ function assistantMessageFromEvents(events: readonly AdapterEvent[]): OcxAssista
   }
   if (text) content.push({ type: "text", text });
   if (content.length === 0) return undefined;
-  return { role: "assistant", content, timestamp: Date.now() };
+  return { role: "assistant", content, timestamp };
 }
 
 export function buildContinuationRequest(parsed: OcxParsedRequest, events: readonly AdapterEvent[]): OcxParsedRequest {
   const messages = [...parsed.context.messages];
-  const assistant = assistantMessageFromEvents(events);
+  // One clock read for the whole rebuild. Two Date.now() calls could straddle a millisecond
+  // boundary, which made the retained-heartbeat contract test fail intermittently in CI on a
+  // 1ms skew between the assistant message and the nudge that follows it.
+  const timestamp = Date.now();
+  const assistant = assistantMessageFromEvents(events, timestamp);
   if (assistant) messages.push(assistant);
-  messages.push({ role: "developer", content: TERMINAL_GUARD_NUDGE, timestamp: Date.now() });
+  messages.push({ role: "developer", content: TERMINAL_GUARD_NUDGE, timestamp });
   return { ...parsed, context: { ...parsed.context, messages } };
 }
 
@@ -153,6 +157,16 @@ export interface GuardedEventStreamOptions {
   maxAutoContinuations?: number;
 }
 
+/**
+ * Events that are useful to the downstream stream consumer but carry no state used by the
+ * terminal-continuation decision or its rebuilt request. Keep them out of the retained event
+ * list so adapter liveness markers and arbitrarily large tool-argument fragments cannot make
+ * the guard's per-turn memory grow without adding any continuation semantics.
+ */
+export function isTerminalGuardPassthroughOnly(event: AdapterEvent): boolean {
+  return event.type === "heartbeat" || event.type === "tool_call_delta";
+}
+
 function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
   if (!first) return second;
   if (!second) return first;
@@ -193,9 +207,16 @@ export async function* guardTerminalEventStream(options: GuardedEventStreamOptio
     const seen: AdapterEvent[] = [];
     let terminalSeen = false;
     for await (const event of source) {
+      // Liveness markers and tool argument fragments are passed through to the bridge, but
+      // neither analyzeTerminalTurn nor buildContinuationRequest consumes them. Retaining the
+      // fragments would duplicate arbitrarily large argument payloads in `seen` for no effect.
+      if (isTerminalGuardPassthroughOnly(event)) {
+        yield event;
+        continue;
+      }
       if (event.type === "done") {
         terminalSeen = true;
-        const analysis = options.adapterName === "anthropic"
+        const analysis = (options.adapterName === "anthropic" || options.adapterName === "openai-chat")
           ? analyzeTerminalTurn(parsed, seen)
           : { decision: "pass" as const };
         const normalStop = event.stopReason !== "max_tokens" && event.stopReason !== "content_filter";

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

@@ -5,7 +5,12 @@
  * #553 looking for an adapter URL bug that does not exist. Name the likely cause and the
  * command that settles it.
  */
+import { RequestPacingQueueOverloadError } from "../../providers/request-pacing";
+
 export function describeUpstreamConnectFailure(err: unknown, connectMs: number): string {
+  // Local pacing admission is not a transport failure. Let the outer response boundary
+  // preserve its retryable 429 identity instead of laundering it into a 502.
+  if (err instanceof RequestPacingQueueOverloadError) throw err;
   if (err instanceof Error && err.name === "TimeoutError") {
     return `Provider connect timeout after ${connectMs}ms`;
   }