@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
624 lines (587 loc) • 26.1 kB
text/typescript
/**
* Provider-opt-in repair for Responses-compatible gateways that return sparse
* lifecycle snapshots (#893): field backfills for missing canonical fields,
* AND lifecycle event injection so Codex clients actually commit the turn.
*
* Field-repair semantics (snapshot fields, item/part backfills, retention
* bounds) are adopted from PR #928 (0xWinner98) with attribution. The
* lifecycle-completion layer is new: #928's exact-issue test expects no
* `output_item.done` and a terminal `output: []` — normalization without
* commitment, which the canonical bridge contract (src/bridge.ts) shows is
* not enough for Codex to commit the message.
*
* Design:
* - One stateful tracker per stream. Existing upstream values are always
* authoritative; only absent or structurally invalid fields are backfilled.
* - Event injection happens only for items PROVEN open at a terminal event
* (never for content the gateway closed itself).
* - Ambiguous, gapped, malformed, oversized, or contradictory shapes taint
* the tracker: no injections and no output reconstruction afterwards
* (fail closed; explicit `output: []` from the gateway stays authoritative).
*/
import type { TranslatorBudget } from "../lib/translator-budget";
import {
MAX_COMPLETED_OUTPUT_ITEMS,
MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES,
} from "./relay";
import { sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
import { isPlainObject, jsonBlock, type RetainedOutputItem } from "./responses-snapshot-codec";
const RESPONSE_EVENT_STATUSES: Readonly<Record<string, string>> = {
"response.created": "in_progress",
"response.in_progress": "in_progress",
"response.completed": "completed",
"response.failed": "failed",
"response.incomplete": "incomplete",
"response.queued": "queued",
};
type RequestDefaults = {
parallelToolCalls: boolean;
toolChoice: unknown;
tools: unknown[];
};
function isStructurallyValidToolChoice(value: unknown): boolean {
return (typeof value === "string" && value.trim().length > 0)
|| (isPlainObject(value) && typeof value.type === "string" && value.type.trim().length > 0);
}
function requestDefaults(requestBody: unknown): RequestDefaults {
const request = isPlainObject(requestBody) ? requestBody : {};
return {
parallelToolCalls: typeof request.parallel_tool_calls === "boolean"
? request.parallel_tool_calls
: true,
toolChoice: isStructurallyValidToolChoice(request.tool_choice) ? request.tool_choice : "auto",
tools: Array.isArray(request.tools) ? request.tools : [],
};
}
function repairOutputTextPart(part: Record<string, unknown>): Record<string, unknown> {
if (part.type !== "output_text") return part;
const needsText = typeof part.text !== "string";
const needsAnnotations = !Array.isArray(part.annotations);
if (!needsText && !needsAnnotations) return part;
return {
...part,
...(needsText ? { text: "" } : {}),
...(needsAnnotations ? { annotations: [] } : {}),
};
}
function repairSummaryPart(part: Record<string, unknown>): Record<string, unknown> {
if (part.type !== "summary_text" || typeof part.text === "string") return part;
return { ...part, text: "" };
}
function repairOutputItem(
item: Record<string, unknown>,
inferredStatus?: string,
): Record<string, unknown> {
let repaired = item;
let changed = false;
if (item.type === "reasoning") {
const rawSummary = item.summary;
const summary = Array.isArray(rawSummary)
? rawSummary.map((part) => isPlainObject(part) ? repairSummaryPart(part) : part)
: [];
changed = !Array.isArray(rawSummary)
|| summary.some((part, index) => part !== rawSummary[index]);
if (changed) repaired = { ...repaired, summary };
} else if (item.type === "message") {
const rawContent = item.content;
const content = Array.isArray(rawContent)
? rawContent.map((part) => isPlainObject(part) ? repairOutputTextPart(part) : part)
: [];
changed = !Array.isArray(rawContent)
|| content.some((part, index) => part !== rawContent[index]);
// Responses output-message roles are the literal "assistant"; input roles are invalid here.
changed = changed || item.role !== "assistant";
if (changed) repaired = { ...repaired, content, role: "assistant" };
}
if (inferredStatus && (typeof repaired.status !== "string" || repaired.status.trim().length === 0)) {
repaired = { ...repaired, status: inferredStatus };
}
return repaired;
}
function repairResponseSnapshot(
response: Record<string, unknown>,
defaultStatus: string,
defaults: RequestDefaults,
reconstructedOutput?: Record<string, unknown>[],
): Record<string, unknown> {
const repaired = { ...response };
let changed = false;
const effectiveResponseStatus = typeof response.status === "string" && response.status.trim().length > 0
? response.status
: defaultStatus;
const outputStatus = effectiveResponseStatus === "completed" || effectiveResponseStatus === "incomplete"
? effectiveResponseStatus
: undefined;
if (reconstructedOutput) {
repaired.output = reconstructedOutput;
changed = true;
} else if (Array.isArray(repaired.output)) {
const output = repaired.output.map((item) => {
if (!isPlainObject(item)) return item;
const next = repairOutputItem(item, outputStatus);
changed = changed || next !== item;
return next;
});
if (changed) repaired.output = output;
}
if (typeof repaired.parallel_tool_calls !== "boolean") {
repaired.parallel_tool_calls = defaults.parallelToolCalls;
changed = true;
}
if (!isStructurallyValidToolChoice(repaired.tool_choice)) {
repaired.tool_choice = defaults.toolChoice;
changed = true;
}
if (!Array.isArray(repaired.tools)) {
repaired.tools = defaults.tools;
changed = true;
}
if (typeof repaired.status !== "string" || repaired.status.trim().length === 0) {
repaired.status = defaultStatus;
changed = true;
}
return changed ? repaired : response;
}
type OpenItem = {
itemId: string;
outputIndex: number;
type: string;
/** Message/reasoning items get lifecycle injections; other types never do. */
injectable: boolean;
/** The gateway opened a content part explicitly (or we injected one). */
contentPartOpen: boolean;
/** The gateway sent output_text.done for this item. */
textDone: boolean;
/** The gateway sent content_part.done for this item. */
partDone: boolean;
text: string;
/** Exact UTF-8 size and boundary unit, without rescanning the accumulated text. */
textBytes: number;
lastCodeUnit: number;
item: Record<string, unknown>;
};
/** Open-item retention bounds (#893 review): aggregate, not just per-item. */
const MAX_OPEN_ITEMS = MAX_COMPLETED_OUTPUT_ITEMS;
const MAX_OPEN_ITEM_AGGREGATE_TEXT_BYTES = MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES;
/**
* Stateful block rewrite: field backfills + lifecycle completion injection.
* `budget` bounds retained completed items (reconstruction only).
*/
export function createResponsesSnapshotBlockRewrite(
requestBody?: unknown,
budget?: TranslatorBudget,
): SseBlockRewrite {
const defaults = requestDefaults(requestBody);
const openItems = new Map<number, OpenItem>();
const completedItems = new Map<number, RetainedOutputItem>();
let aggregateItemBytes = 0;
let aggregateOpenTextBytes = 0;
let tainted = false;
const releaseRetained = (): void => {
if (aggregateItemBytes > 0) {
budget?.releaseRetained(aggregateItemBytes, { kind: "retained_collectors" });
}
completedItems.clear();
openItems.clear();
aggregateItemBytes = 0;
aggregateOpenTextBytes = 0;
tainted = false;
};
const taintAndRelease = (): void => {
// Fail closed means stop RETAINING too: open state and charged collectors
// are released immediately, and no further state accumulates (#893 review).
if (aggregateItemBytes > 0) {
budget?.releaseRetained(aggregateItemBytes, { kind: "retained_collectors" });
}
completedItems.clear();
openItems.clear();
aggregateItemBytes = 0;
aggregateOpenTextBytes = 0;
tainted = true;
};
/** Drop one open item and refund its accumulated text from the aggregate. */
const closeOpenItem = (index: number): void => {
const open = openItems.get(index);
if (!open) return;
aggregateOpenTextBytes -= open.textBytes;
openItems.delete(index);
};
const retainCompletedItem = (index: number, item: Record<string, unknown>): void => {
if (tainted) return; // fail closed means stop retaining (#893 review)
const sourceBytes = Buffer.byteLength(JSON.stringify(item), "utf8");
const previous = completedItems.get(index);
if (sourceBytes > MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES) {
if (previous) {
completedItems.delete(index);
aggregateItemBytes -= previous.sourceBytes;
budget?.releaseRetained(previous.sourceBytes, { kind: "retained_collectors" });
}
taintAndRelease();
return;
}
const retainedDelta = sourceBytes - (previous?.sourceBytes ?? 0);
if (retainedDelta > 0) {
budget?.chargeRetained(retainedDelta, { kind: "retained_collectors" });
} else if (retainedDelta < 0) {
budget?.releaseRetained(-retainedDelta, { kind: "retained_collectors" });
}
completedItems.set(index, { item, sourceBytes });
aggregateItemBytes += retainedDelta;
while (completedItems.size > MAX_COMPLETED_OUTPUT_ITEMS
|| aggregateItemBytes > MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES) {
let highestIndex = -1;
for (const retainedIndex of completedItems.keys()) {
if (retainedIndex > highestIndex) highestIndex = retainedIndex;
}
const evicted = completedItems.get(highestIndex);
if (!evicted) break;
completedItems.delete(highestIndex);
aggregateItemBytes -= evicted.sourceBytes;
budget?.releaseRetained(evicted.sourceBytes, { kind: "retained_collectors" });
taintAndRelease();
return;
}
};
const completedItemSnapshot = (open: OpenItem): Record<string, unknown> => {
if (open.type === "message") {
return repairOutputItem({
...open.item,
status: "completed",
role: "assistant",
content: [{ type: "output_text", text: open.text, annotations: [] }],
}, "completed");
}
return repairOutputItem({ ...open.item, status: "completed" }, "completed");
};
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 type = typeof event.type === "string" ? event.type : "";
let nextEvent: Record<string, unknown> = event;
let changed = false;
const outputIndex = Number.isInteger(event.output_index) && (event.output_index as number) >= 0
? event.output_index as number
: undefined;
const itemId = typeof event.item_id === "string" ? event.item_id : undefined;
// --- item lifecycle tracking + field backfills -------------------------
if (type === "response.output_item.added" && isPlainObject(event.item)) {
const itemType = typeof event.item.type === "string" ? event.item.type : "";
const id = typeof event.item.id === "string" ? event.item.id : undefined;
if (outputIndex === undefined || !id) {
taintAndRelease();
} else {
if (openItems.has(outputIndex)) taintAndRelease(); // contradictory reuse of an open index
if (openItems.size >= MAX_OPEN_ITEMS) taintAndRelease(); // aggregate retention bound
// Unsupported types (function_call, …) reserve their index but are
// never injected — a sparse gateway that leaves one open blocks only
// the terminal reconstruction, not message repair (#893 review).
const injectable = itemType === "message" || itemType === "reasoning";
if (!tainted) {
openItems.set(outputIndex, {
itemId: id,
outputIndex,
type: itemType,
injectable,
contentPartOpen: false,
textDone: false,
partDone: false,
text: "",
textBytes: 0,
lastCodeUnit: -1,
item: event.item,
});
}
}
const item = repairOutputItem(event.item, "in_progress");
if (item !== event.item) {
nextEvent = { ...nextEvent, item };
changed = true;
}
}
if (type === "response.output_item.done" && !isPlainObject(event.item)) {
taintAndRelease();
}
if (type === "response.output_item.done" && isPlainObject(event.item)) {
const item = repairOutputItem(event.item, "completed");
if (item !== event.item) {
nextEvent = { ...nextEvent, item };
changed = true;
}
// Identity correlation: a done event only closes the tracked item when
// id AND type agree — a mismatched done is a contradictory stream and
// must go fail-closed rather than close/reconstruct the wrong item.
const tracked = outputIndex !== undefined ? openItems.get(outputIndex) : undefined;
const doneId = typeof event.item.id === "string" ? event.item.id : undefined;
const doneType = typeof event.item.type === "string" ? event.item.type : undefined;
if (tracked && (doneId !== tracked.itemId || doneType !== tracked.type)) {
taintAndRelease();
return [changed ? jsonBlock(nextEvent) : block];
}
if (outputIndex !== undefined && typeof item.type === "string" && item.type.trim().length > 0) {
closeOpenItem(outputIndex);
retainCompletedItem(outputIndex, item);
} else {
taintAndRelease();
}
}
if ((type === "response.content_part.added" || type === "response.content_part.done")
&& isPlainObject(event.part)) {
if (outputIndex !== undefined) {
const open = openItems.get(outputIndex);
// A PRESENT-but-mismatched item_id is contradictory lifecycle evidence,
// exactly like output_item.done and output_text.done: the stream is
// telling us our identity model for this index is wrong. Merely
// ignoring it left the item open and let the terminal fabricate a full
// closure sequence (content_part.added → output_text.done →
// content_part.done → output_item.done) on top of a stream we do not
// understand. Go fail-closed instead. An OMITTED item_id stays
// legitimate and is still correlated by output_index.
if (open && itemId !== undefined && itemId !== open.itemId) {
taintAndRelease();
return [changed ? jsonBlock(nextEvent) : block];
}
// Correlate by item_id when present: a mismatched event must not
// mutate (or suppress injections for) the tracked item (#893 review).
if (open && (itemId === undefined || itemId === open.itemId)) {
if (type === "response.content_part.added") open.contentPartOpen = true;
else open.partDone = true;
}
}
const part = repairOutputTextPart(event.part);
if (part !== event.part) {
nextEvent = { ...nextEvent, part };
changed = true;
}
}
if ((type === "response.reasoning_summary_part.added"
|| type === "response.reasoning_summary_part.done") && isPlainObject(event.part)) {
const part = repairSummaryPart(event.part);
if (part !== event.part) {
nextEvent = { ...nextEvent, part };
changed = true;
}
}
if ((type === "response.output_text.delta" || type === "response.output_text.done")
&& !Array.isArray(event.logprobs)) {
nextEvent = { ...nextEvent, logprobs: [] };
changed = true;
}
if (type === "response.output_text.delta" && typeof event.delta === "string" && outputIndex !== undefined) {
const open = openItems.get(outputIndex);
// Same identity contract as the *.done terminals: a present-but-foreign
// item_id on a tracked index means our model of this index is wrong, and
// reconstructing from the text we DID accept would ship a message the
// upstream never assembled that way.
if (open && itemId !== undefined && itemId !== open.itemId) {
taintAndRelease();
return [changed ? jsonBlock(nextEvent) : block];
}
if (open && (itemId === undefined || itemId === open.itemId)) {
let deltaBytes = Buffer.byteLength(event.delta, "utf8");
const first = event.delta.charCodeAt(0);
// Joining two isolated surrogate halves replaces two 3-byte replacements with 4 bytes.
if (open.lastCodeUnit >= 0xd800 && open.lastCodeUnit <= 0xdbff && first >= 0xdc00 && first <= 0xdfff) {
deltaBytes -= 2;
}
if (event.delta.length > 0) open.lastCodeUnit = event.delta.charCodeAt(event.delta.length - 1);
open.text += event.delta;
open.textBytes += deltaBytes;
aggregateOpenTextBytes += deltaBytes;
// Unbounded text accumulation is a retention hole (#893 review):
// overshoot per-item or aggregate caps and the stream goes fail-closed.
if (open.textBytes > MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES
|| aggregateOpenTextBytes > MAX_OPEN_ITEM_AGGREGATE_TEXT_BYTES) {
taintAndRelease();
}
}
}
if (type === "response.output_text.done") {
if (outputIndex !== undefined) {
const open = openItems.get(outputIndex);
// Identity correlation, same contract as output_item.done above: a
// text-done carrying a DIFFERENT item_id for a tracked index is a
// contradictory stream. Silently ignoring it used to leave the item
// open, so the terminal then synthesized a second output_text.done and
// output_item.done — a double close built on a stream we do not
// understand (#1025 review blocker 2). Go fail-closed instead: forward
// the block untouched and stop injecting for the rest of the stream.
if (open && itemId !== undefined && itemId !== open.itemId) {
taintAndRelease();
return [changed ? jsonBlock(nextEvent) : block];
}
if (open && (itemId === undefined || itemId === open.itemId)) {
open.textDone = true;
if (typeof event.text === "string") {
// Replacement must keep the aggregate honest and bounded, the
// same as delta accumulation (#893 review).
const previousBytes = open.textBytes;
const nextBytes = Buffer.byteLength(event.text, "utf8");
open.text = event.text;
open.textBytes = nextBytes;
open.lastCodeUnit = event.text.charCodeAt(event.text.length - 1);
aggregateOpenTextBytes += nextBytes - previousBytes;
if (nextBytes > MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES
|| aggregateOpenTextBytes > MAX_OPEN_ITEM_AGGREGATE_TEXT_BYTES) {
taintAndRelease();
}
}
}
}
if (typeof event.text !== "string") {
nextEvent = { ...nextEvent, text: "" };
changed = true;
}
}
// --- lifecycle response snapshots --------------------------------------
const responseStatus = Object.prototype.hasOwnProperty.call(RESPONSE_EVENT_STATUSES, type)
? RESPONSE_EVENT_STATUSES[type]
: undefined;
const isTerminal = type === "response.completed"
|| type === "response.failed"
|| type === "response.incomplete";
if (responseStatus && isPlainObject(event.response)) {
// Terminal output reconstruction stays in the injection layer below;
// here the snapshot only gets field backfills.
const response = repairResponseSnapshot(event.response, responseStatus, defaults);
if (response !== event.response) {
nextEvent = { ...nextEvent, response };
changed = true;
}
}
// --- lifecycle completion injection ------------------------------------
// Only response.completed justifies synthesized closing events: a failed
// or incomplete terminal must never fabricate completed output (#893 review).
const isCompletedTerminal = type === "response.completed";
const out: string[] = [];
if (!tainted) {
// A text delta for an item whose content part was never opened needs the
// opening event first, or Codex never binds the text to a committed part.
if (type === "response.output_text.delta" && outputIndex !== undefined) {
const open = openItems.get(outputIndex);
if (open && open.type === "message" && !open.contentPartOpen) {
out.push(jsonBlock({
type: "response.content_part.added",
item_id: open.itemId,
output_index: open.outputIndex,
content_index: 0,
part: { type: "output_text", text: "", annotations: [] },
}));
open.contentPartOpen = true;
}
}
if (isCompletedTerminal && openItems.size > 0) {
const closing = [...openItems.values()].sort((a, b) => a.outputIndex - b.outputIndex);
for (const open of closing) {
if (open.injectable && open.type === "message") {
if (!open.contentPartOpen) {
out.push(jsonBlock({
type: "response.content_part.added",
item_id: open.itemId,
output_index: open.outputIndex,
content_index: 0,
part: { type: "output_text", text: "", annotations: [] },
}));
open.contentPartOpen = true;
}
if (!open.textDone) {
out.push(jsonBlock({
type: "response.output_text.done",
item_id: open.itemId,
output_index: open.outputIndex,
content_index: 0,
logprobs: [],
text: open.text,
}));
open.textDone = true;
}
if (!open.partDone) {
out.push(jsonBlock({
type: "response.content_part.done",
item_id: open.itemId,
output_index: open.outputIndex,
content_index: 0,
part: { type: "output_text", text: open.text, annotations: [] },
}));
open.partDone = true;
}
}
if (!open.injectable) continue; // never fabricate completions for other types
const snapshot = completedItemSnapshot(open);
out.push(jsonBlock({
type: "response.output_item.done",
output_index: open.outputIndex,
item: snapshot,
}));
closeOpenItem(open.outputIndex);
retainCompletedItem(open.outputIndex, snapshot);
}
}
}
// Terminal output reconstruction/canonical backfill: an explicit
// `output: []` is authoritative; absent or malformed output on a
// completed terminal becomes the retained items or the canonical empty
// list (#893 review). Leftover non-injectable open items block
// reconstruction only, not the message closing above.
if (isCompletedTerminal && !tainted && isPlainObject(nextEvent.response)) {
const response = nextEvent.response;
const outputValue = (response as Record<string, unknown>).output;
const outputExplicitArray = Array.isArray(outputValue);
if (!outputExplicitArray) {
const injectableOpen = [...openItems.values()].filter(open => open.injectable);
const nonInjectableOpen = [...openItems.values()].filter(open => !open.injectable);
if (completedItems.size > 0 && injectableOpen.length === 0 && nonInjectableOpen.length === 0) {
const ordered = [...completedItems.entries()].sort(([left], [right]) => left - right);
if (ordered.every(([index], position) => index === position)) {
nextEvent = {
...nextEvent,
response: { ...response, output: ordered.map(([, retained]) => retained.item) },
};
changed = true;
} else {
// A gap means at least one completed item is missing. Never compact
// later indexes into a shorter array that only appears complete.
tainted = true;
}
} else if (completedItems.size === 0 && openItems.size === 0) {
nextEvent = { ...nextEvent, response: { ...response, output: [] } };
changed = true;
}
}
}
out.push(changed ? jsonBlock(nextEvent) : block);
if (isTerminal) releaseRetained();
return out;
};
// Relays call this on every teardown path (terminal, EOF, cancel, error):
// retained collectors and open-item state never outlive the stream.
rewrite.dispose = releaseRetained;
return rewrite;
}
/** Repair a non-streaming Responses JSON object without changing raw inspection state. */
export function repairResponsesSnapshotJson(payload: string, requestBody?: unknown): string {
let response: unknown;
try {
response = JSON.parse(payload);
} catch {
return payload;
}
if (!isPlainObject(response)) return payload;
// Canonical output for non-stream completed responses: absent or malformed
// output becomes the canonical empty list; explicit arrays stay authoritative.
if (!Array.isArray(response.output)) {
const repaired = repairResponseSnapshot({ ...response, output: [] }, "completed", requestDefaults(requestBody));
return JSON.stringify(repaired);
}
const repaired = repairResponseSnapshot(response, "completed", requestDefaults(requestBody));
return repaired === response ? payload : JSON.stringify(repaired);
}
export function hasResponsesSnapshotRepair(enabled: boolean | undefined): enabled is true {
return enabled === true;
}