@iislee/opencodex 2.11.0 → 2.31.0

package/src/server/responses/input-admission.ts

@@ -0,0 +1,185 @@
+/**
+ * Pre-dispatch input admission (#1412).
+ *
+ * Refuses a turn whose estimated input cannot plausibly fit the model context window,
+ * BEFORE auth resolution, circuit admission, or any upstream I/O. #1412 reported ~127k of
+ * real context compounding to 1.3M-1.6M tokens and crashing the proxy; the provider would
+ * reject such a turn anyway, so paying for the round trip buys nothing.
+ *
+ * Deliberately narrow. This is not a context manager and not a compaction trigger: it
+ * catches the pathological case and stays out of the way otherwise. Every uncertainty
+ * resolves toward admitting.
+ */
+import { nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, type NativeContextLimitsInput } from "../../codex/catalog/metadata";
+import { estimateTokens } from "../../lib/token-estimate";
+import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
+import { modelRecordValue } from "../../reasoning-effort";
+import type { OcxContentPart, OcxParsedRequest, OcxProviderConfig } from "../../types";
+
+/**
+ * Multiplier applied to the ceiling before refusing.
+ *
+ * 2.5, not something tighter, because `estimateTokens` can overshoot by 1.6x on its own.
+ * `cjkRatio` samples every `stride`-th character, so a payload of fixed-width records whose
+ * length aligns with the stride samples as 100% CJK while being ~1.6% CJK, firing the
+ * 2.5-chars/token clamp instead of the 4.0 default. Measured on Bun 1.3.14: 126,046 chars,
+ * true CJK ratio 0.0161, sampled ratio 1.0, estimate inflated 1.6x. Since 4.0 / 2.5 = 1.6
+ * is that branch maximum divergence, a threshold at or under 1.6 would convert the
+ * estimator error bar into false 413s.
+ *
+ * 2.5 sits above it with room for the ~10% model-family ratio spread, and still refuses the
+ * #1412 shape (10x) four times over.
+ */
+export const ADMISSION_TOLERANCE = 2.5;
+
+/**
+ * Token cost charged for a remote image URL. The bytes are not in this request — the
+ * provider fetches them — so the URL own length is not the cost. A small flat charge
+ * acknowledges the tiles the image will occupy without pretending to know its dimensions.
+ */
+const REMOTE_IMAGE_TOKENS = 850;
+
+/** Decoded image bytes per token. Coarse tile-count proxy, not a provider formula. */
+const IMAGE_BYTES_PER_TOKEN = 750;
+
+export interface InputAdmissionResult {
+  admitted: boolean;
+  estimatedTokens: number;
+  /** Resolved ceiling, or null when nothing could be resolved (=> always admitted). */
+  ceiling: number | null;
+}
+
+function positive(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
+
+/**
+ * Charge a `data:` URL by its DECODED size rather than its character length: base64 inflates
+ * by 4/3, so charging the string would overcount by a third. A remote URL is charged flat.
+ */
+function imageTokens(imageUrl: string): number {
+  if (!imageUrl.startsWith("data:")) return REMOTE_IMAGE_TOKENS;
+  const comma = imageUrl.indexOf(",");
+  if (comma < 0) return REMOTE_IMAGE_TOKENS;
+  const payload = imageUrl.length - comma - 1;
+  if (payload <= 0) return 0;
+  const decoded = Math.floor((payload * 3) / 4);
+  return Math.max(1, Math.ceil(decoded / IMAGE_BYTES_PER_TOKEN));
+}
+
+function contentPartTokens(part: OcxContentPart, modelId: string): number {
+  return part.type === "image" ? imageTokens(part.imageUrl) : estimateTokens(part.text, modelId);
+}
+
+function contentTokens(content: string | readonly OcxContentPart[], modelId: string): number {
+  if (typeof content === "string") return estimateTokens(content, modelId);
+  let total = 0;
+  for (const part of content) total += contentPartTokens(part, modelId);
+  return total;
+}
+
+/**
+ * Estimate the input tokens of a parsed request.
+ *
+ * Walks the whole `OcxMessage` union rather than user text alone. Assistant turns carry
+ * their content as `OcxAssistantContentPart[]` — text, thinking blocks, and tool calls whose
+ * JSON arguments are frequently the largest single item in an agent conversation. A walk
+ * that counted only `{type:"text"}` would undercount exactly the turns that trigger this
+ * gate.
+ */
+export function estimateInputTokens(parsed: OcxParsedRequest, modelId: string): number {
+  const { context } = parsed;
+  let total = 0;
+
+  for (const prompt of context.systemPrompt ?? []) total += estimateTokens(prompt, modelId);
+
+  for (const message of context.messages) {
+    if (message.role === "assistant") {
+      for (const part of message.content) {
+        if (part.type === "text") total += estimateTokens(part.text, modelId);
+        else if (part.type === "thinking") total += estimateTokens(part.thinking, modelId);
+        else total += estimateTokens(part.name, modelId) + estimateTokens(JSON.stringify(part.arguments), modelId);
+      }
+      // Opaque provider blob replayed verbatim upstream, so it costs real input tokens.
+      if (message.kiroRedactedReasoning) total += estimateTokens(message.kiroRedactedReasoning, modelId);
+      continue;
+    }
+    total += contentTokens(message.content, modelId);
+  }
+
+  // Tool schemas ride every turn: name, description, and the JSON parameter schema all
+  // reach the upstream, and a large MCP catalog can dominate a short conversation.
+  for (const tool of context.tools ?? []) {
+    total += estimateTokens(tool.name, modelId)
+      + estimateTokens(tool.description, modelId)
+      + estimateTokens(JSON.stringify(tool.parameters), modelId);
+  }
+
+  return total;
+}
+
+/**
+ * Resolve the admission ceiling. Pure: no filesystem, no catalog, no registry scan.
+ *
+ * `provider` must be the ROUTED config (`route.provider`), which `routedProviderConfig`
+ * has already transport-guarded and merged. Re-deriving from `config.providers[name]` would
+ * reject a user-defined provider that merely shares a built-in name using limits that
+ * belong to a different service.
+ */
+export function resolveInputCeiling(
+  provider: OcxProviderConfig,
+  providerName: string,
+  modelId: string,
+  // Operator cap for the canonical native provider. Passed in rather than read from a
+  // config here so this stays pure: no filesystem, no catalog, no registry scan.
+  nativeContextCap?: NativeContextLimitsInput,
+): number | null {
+  // `modelRecordValue`, not a bare lookup: the catalog resolves these same two maps that
+  // way, so a `gpt-oss` entry covers `gpt-oss:120b`. Reading raw here made the gate fall
+  // back to the provider-wide window and refuse turns the model can plainly hold.
+  const configured = positive(modelRecordValue(provider.modelContextWindows, modelId))
+    ?? positive(provider.contextWindow);
+
+  // The canonical `openai` registry entry declares no context fields, so without this the
+  // gate would be inert on the default Codex route. All three clauses are load-bearing: a
+  // transport-mismatched custom provider named "openai" is preserved verbatim by routing
+  // and must not inherit built-in native limits, and a routed `provider/model` id is not a
+  // native slug. Static maps only — no catalog read.
+  const canonicalNativeBare = providerName === OPENAI_CODEX_PROVIDER_ID
+    && isCanonicalOpenAiForwardProvider(provider)
+    && !modelId.includes("/");
+  const nativeLimits = canonicalNativeBare && configured !== null
+    ? {
+        ...(typeof nativeContextCap === "number" ? { cap: nativeContextCap } : (nativeContextCap ?? {})),
+        modelWindows: { [modelId]: configured },
+      }
+    : nativeContextCap;
+  const native = canonicalNativeBare
+    ? positive(nativeOpenAiContextWindow(modelId, nativeLimits))
+    : null;
+  const nativeMaxInput = canonicalNativeBare ? positive(nativeOpenAiMaxInputTokens(modelId, nativeLimits)) : null;
+
+  const window = canonicalNativeBare ? native : configured;
+  // modelMaxInputTokens is an input-only cap, so it can only tighten the window.
+  const configuredMaxInput = positive(modelRecordValue(provider.modelMaxInputTokens, modelId));
+  const limits = [window, configuredMaxInput, nativeMaxInput].filter((v): v is number => v !== null);
+  return limits.length === 0 ? null : Math.min(...limits);
+}
+
+/**
+ * Fail-open when no ceiling is known; refuse only past `ceiling * ADMISSION_TOLERANCE`.
+ *
+ * The caller is responsible for skipping compaction turns — see the call site in core.ts.
+ */
+export function checkInputAdmission(
+  parsed: OcxParsedRequest,
+  provider: OcxProviderConfig,
+  providerName: string,
+  modelId: string,
+  nativeContextCap?: NativeContextLimitsInput,
+): InputAdmissionResult {
+  const ceiling = resolveInputCeiling(provider, providerName, modelId, nativeContextCap);
+  if (ceiling === null) return { admitted: true, estimatedTokens: 0, ceiling: null };
+  const estimatedTokens = estimateInputTokens(parsed, modelId);
+  return { admitted: estimatedTokens <= ceiling * ADMISSION_TOLERANCE, estimatedTokens, ceiling };
+}

package/src/server/responses/pacing-overload.ts

@@ -0,0 +1,13 @@
+import { formatErrorResponse } from "../../bridge";
+import { RequestPacingQueueOverloadError } from "../../providers/request-pacing";
+
+/** Convert local request-pacing admission failures into a retryable HTTP response. */
+export function requestPacingOverloadResponse(error: unknown): Response | undefined {
+  if (!(error instanceof RequestPacingQueueOverloadError)) return undefined;
+  return formatErrorResponse(
+    429,
+    "rate_limit_error",
+    error.message,
+    { retryAfter: String(error.retryAfterSeconds) },
+  );
+}

package/src/server/responses/policy-fallback.ts

@@ -0,0 +1,178 @@
+import { comboFailureDecision } from "../../combos/failover";
+import { readBoundedResponseBody } from "../../lib/bounded-body";
+import { readJsonRequestBody } from "../request-decompress";
+import { finishRequestAttempt, type RequestLogContext } from "../request-log";
+import type { OcxConfig } from "../../types";
+import type { RouteCandidateTrace, RouteDecisionTraceV1 } from "../../routing/trace";
+import { handleResponses as handleResponsesCore } from "./core";
+import { requestPacingOverloadResponse } from "./pacing-overload";
+
+type CoreHandler = typeof handleResponsesCore;
+type CoreOptions = Parameters<CoreHandler>[3];
+
+export interface PolicyFallbackDeps {
+  runCore?: CoreHandler;
+}
+
+function candidateKey(candidate: Pick<RouteCandidateTrace, "provider" | "model">): string {
+  return `${candidate.provider}\u0000${candidate.model}`;
+}
+
+/**
+ * Rank the remaining candidates from the ORIGINAL policy trace. The initial
+ * decision stays immutable; fallback execution belongs in attempts[], not in a
+ * rewritten decision trace.
+ */
+export function rankPolicyFallbackCandidates(
+  trace: RouteDecisionTraceV1,
+  tried: ReadonlySet<string>,
+): RouteCandidateTrace[] {
+  return trace.candidates
+    .map((candidate, index) => ({ candidate, index }))
+    .filter(({ candidate }) =>
+      candidate.eligible
+      && candidate.exclusions.length === 0
+      && !tried.has(candidateKey(candidate)))
+    .sort((left, right) => {
+      const scoreDelta = (right.candidate.score?.total ?? Number.NEGATIVE_INFINITY)
+        - (left.candidate.score?.total ?? Number.NEGATIVE_INFINITY);
+      return scoreDelta || left.index - right.index;
+    })
+    .map(({ candidate }) => candidate);
+}
+
+function requestWithCandidate(
+  req: Request,
+  rawBody: Record<string, unknown>,
+  candidate: Pick<RouteCandidateTrace, "provider" | "model">,
+): Request {
+  const headers = new Headers(req.headers);
+  headers.delete("content-encoding");
+  headers.delete("content-length");
+  headers.set("content-type", "application/json");
+  return new Request(req.url, {
+    method: req.method,
+    headers,
+    body: JSON.stringify({ ...rawBody, model: `${candidate.provider}/${candidate.model}` }),
+    signal: req.signal,
+  });
+}
+
+function errorCodeFromText(text: string): string | undefined {
+  if (!text) return undefined;
+  try {
+    const payload = JSON.parse(text) as { error?: { code?: unknown; type?: unknown }; code?: unknown };
+    const candidate = payload.error?.code ?? payload.error?.type ?? payload.code;
+    return typeof candidate === "string" ? candidate : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function shouldHopPolicyCandidate(response: Response, signal?: AbortSignal): Promise<boolean> {
+  if (response.status < 400 || signal?.aborted) return false;
+  try {
+    const inspected = await readBoundedResponseBody(response.clone(), { signal });
+    const text = inspected.displaySafe ? inspected.text : "";
+    return comboFailureDecision(response.status, text, { code: errorCodeFromText(text) }) === "hop";
+  } catch {
+    return false;
+  }
+}
+
+function isPolicyDecision(trace: RouteDecisionTraceV1 | undefined): trace is RouteDecisionTraceV1 {
+  return trace?.routeKind === "policy" && !!trace.profile;
+}
+
+/** Finalize the failed physical attempt so the retry receives a fresh attempt row. */
+function finishFailedPolicyAttempt(logCtx: RequestLogContext, status: number): void {
+  const attempt = logCtx.activeAttempt;
+  if (attempt) {
+    const startedAt = logCtx.activeAttemptStartedAt ?? Date.now();
+    finishRequestAttempt(attempt, status, Math.max(0, Date.now() - startedAt), attempt.usage ?? logCtx.usage);
+  }
+  delete logCtx.activeAttempt;
+  delete logCtx.activeAttemptStartedAt;
+  delete logCtx.usage;
+  delete logCtx.usageFromBridge;
+  delete logCtx.upstreamError;
+  delete logCtx.terminalHttpStatus;
+  delete logCtx.terminalErrorCode;
+  delete logCtx.terminalIncompleteReason;
+}
+
+/**
+ * Run a Responses request and, only for an explicitly selected policy profile,
+ * hop to the next eligible policy candidate after a retryable pre-success
+ * failure. The initial policy trace remains the canonical selection evidence;
+ * physical retries continue to accumulate in the existing request attempts.
+ */
+export async function handleResponsesWithPolicyFallback(
+  req: Request,
+  config: OcxConfig,
+  logCtx: RequestLogContext,
+  options: CoreOptions = {},
+  deps: PolicyFallbackDeps = {},
+): Promise<Response> {
+  const runCore = deps.runCore ?? handleResponsesCore;
+  let requestBodyReadNotified = false;
+  const coreOptions: CoreOptions = options.onRequestBodyRead
+    ? {
+      ...options,
+      onRequestBodyRead: () => {
+        if (requestBodyReadNotified) return;
+        requestBodyReadNotified = true;
+        options.onRequestBodyRead?.();
+      },
+    }
+    : options;
+  let rawBody: Record<string, unknown> | null = null;
+  try {
+    const parsed = await readJsonRequestBody(req.clone());
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) rawBody = parsed as Record<string, unknown>;
+  } catch {
+    // Core owns the client-facing parse/decompression error.
+  }
+
+  let response: Response;
+  try {
+    response = await runCore(req, config, logCtx, coreOptions);
+  } catch (error) {
+    const overload = requestPacingOverloadResponse(error);
+    if (overload) return overload;
+    throw error;
+  }
+  const initialTrace = logCtx.routeDecision;
+  const initialRequestedModel = logCtx.requestedModel;
+  if (!rawBody || !isPolicyDecision(initialTrace)) return response;
+
+  const tried = new Set<string>([
+    candidateKey({ provider: initialTrace.selected.provider, model: initialTrace.selected.model }),
+  ]);
+
+  while (await shouldHopPolicyCandidate(response, req.signal)) {
+    if (req.signal.aborted) return response;
+    const next = rankPolicyFallbackCandidates(initialTrace, tried)[0];
+    if (!next) return response;
+    tried.add(candidateKey(next));
+
+    finishFailedPolicyAttempt(logCtx, response.status);
+    const retryRequest = requestWithCandidate(req, rawBody, next);
+    try {
+      try {
+        response = await runCore(retryRequest, config, logCtx, coreOptions);
+      } catch (error) {
+        const overload = requestPacingOverloadResponse(error);
+        if (overload) return overload;
+        throw error;
+      }
+    } finally {
+      logCtx.requestedModel = initialRequestedModel;
+      logCtx.routeDecision = initialTrace;
+    }
+  }
+
+  return response;
+}
+
+export const handleResponses = handleResponsesWithPolicyFallback;

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

@@ -0,0 +1,251 @@
+/**
+ * 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 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 on the item itself.
+ * Returns the same object reference if nothing changed.
+ */
+function backfillOutputItem(item: unknown, slot: ItemIdSlot): 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);
+  if (repaired === content && withId === item) return item;
+  return { ...withId, ...(repaired === content ? {} : { content: repaired }) };
+}
+
+/**
+ * Walk a response object's output[] and backfill output_text parts.
+ * Returns the same object reference if nothing changed.
+ */
+function backfillResponseOutput(response: unknown): 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 });
+    if (next !== item) changed = true;
+    return next;
+  });
+  return changed ? { ...response, output: repaired } : response;
+}
+
+/**
+ * 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 : "";
+  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 })
+      : backfillOutputItem(event.item, nextSyntheticItemSlot());
+    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)) {
+    const response = backfillResponseOutput(event.response);
+    if (response !== event.response) {
+      next = { ...next, response };
+      changed = true;
+    }
+  }
+
+  return changed ? next : event;
+}
+
+/**
+ * Create a stateless SSE block rewrite that backfills annotations and
+ * on output_text content parts. Unconditional: the field is a required
+ * canonical Responses field, so adding it 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;
+  const repaired = backfillResponseOutput(response);
+  if (repaired === response) return payload;
+  return JSON.stringify(repaired);
+}