@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
344 lines (323 loc) • 15.9 kB
text/typescript
/**
* 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/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);
}