UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

291 lines (268 loc) • 13 kB
import type { OcxMessagePhase } from "../types"; import { Buffer } from "node:buffer"; import type { TranslatorBudget } from "../lib/translator-budget"; import type { SseBlockRewrite } from "./sse-payload-rewrite"; import { replaceSseDataPayload, sseDataPayload } from "./sse-payload-rewrite"; /** * Opt-in per-provider phase inference for Responses passthrough streams. * * OpenAI models annotate assistant messages with a commentary/final_answer * phase; the Codex desktop UI collapses commentary into progress rows and * only fully renders the final answer. Third-party gateways forward plain * Responses items without that field, so every narration chunk renders * expanded. The wire has no phase field, so phase is inferred from what * follows each completed message, mirroring the openai-chat bridge strategy: * a message followed by tool-call work is commentary; a message at turn end * is the final answer. Messages already carrying commentary or final_answer * are left untouched and forwarded without buffering; a null or unknown phase * is inferred like a missing one. Each rewritten message stays * buffered until the next protocol event (SSE keepalives keep it pending). * Live text deltas are not buffered, but message completion waits for that * event. Snapshots reuse each item decision when their phase is absent, * matched by item id or, when either side lacks an id, by output index; * terminal snapshot tool work also proves continuation when item events were * omitted. Explicit snapshot phases take precedence; failed snapshots are untouched. */ const TERMINAL_EVENT_TYPES = new Set([ "response.completed", "response.incomplete", "response.failed", ]); const TOOL_CALL_ITEM_TYPES = new Set([ "function_call", "custom_tool_call", "local_shell_call", "shell_call", "apply_patch_call", "mcp_call", "tool_search_call", "web_search_call", ]); function isPlainObject(value: unknown): value is Record<string, unknown> { return !!value && typeof value === "object" && !Array.isArray(value); } /** Only these two values are decisions; null or unknown phases count as missing. */ function isMessagePhase(value: unknown): value is OcxMessagePhase { return value === "commentary" || value === "final_answer"; } function isToolCallItem(item: unknown): boolean { if (!isPlainObject(item)) return false; const type = item.type; return typeof type === "string" && (TOOL_CALL_ITEM_TYPES.has(type) // Unknown hosted/extension call shapes still prove the turn continued. || (type.endsWith("_call") && !type.endsWith("_call_output"))); } function parseDataPayload(block: string): Record<string, unknown> | null { const payload = sseDataPayload(block); if (payload === null) return null; try { const parsed = JSON.parse(payload) as unknown; return isPlainObject(parsed) ? parsed : null; } catch { return null; } } function isDoneSentinel(block: string): boolean { return sseDataPayload(block)?.trim() === "[DONE]"; } function isMessageDoneBlock(block: string): boolean { const parsed = parseDataPayload(block); return parsed?.type === "response.output_item.done" && isPlainObject(parsed.item) && parsed.item.type === "message"; } function withMessagePhase(block: string, phase: OcxMessagePhase): string { const parsed = parseDataPayload(block); if (!parsed || parsed.type !== "response.output_item.done") return block; if (!isPlainObject(parsed.item) || isMessagePhase(parsed.item.phase)) return block; const patched = { ...parsed, item: { ...parsed.item, phase } }; return replaceSseDataPayload(block, JSON.stringify(patched)); } /** One per-item decision, findable by item id and by output index. */ interface PhaseDecision { readonly id: string | null; readonly index: number | null; readonly phase: OcxMessagePhase; } interface PhaseDecisions { readonly byId: ReadonlyMap<string, PhaseDecision>; readonly byIndex: ReadonlyMap<number, PhaseDecision>; } function outputIndexOf(value: unknown): number | null { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null; } /** * The phase already emitted on the wire for the snapshot item at `position`. * An id match wins. A position match is used only when the event or the * snapshot item lacks an id, so two different ids never share a decision. */ function decidedPhase(decisions: PhaseDecisions, id: string | null, position: number): OcxMessagePhase | undefined { const byId = id !== null ? decisions.byId.get(id) : undefined; if (byId) return byId.phase; const byIndex = decisions.byIndex.get(position); return byIndex && (byIndex.id === null || id === null) ? byIndex.phase : undefined; } function snapshotPhase(output: unknown[], position: number, lastToolIndex: number): OcxMessagePhase { if (position < 0 || position >= output.length) return "final_answer"; const item = output[position]; if (!isPlainObject(item) || item.type !== "message") return "final_answer"; if (isMessagePhase(item.phase)) return item.phase; return position < lastToolIndex ? "commentary" : "final_answer"; } function withSnapshotPhases(block: string, decisions: PhaseDecisions, lastToolIndex: number): string { const parsed = parseDataPayload(block); if (!parsed) return block; const response = parsed.response; if (!isPlainObject(response) || !Array.isArray(response.output)) return block; const sourceOutput = response.output; let changed = false; const output = response.output.map((item: unknown, position: number) => { if (isPlainObject(item) && item.type === "message" && !isMessagePhase(item.phase)) { // Mirror the decision already emitted for this item on the wire, so // clients reconciling the final snapshot never re-expand a message // whose output_item.done said commentary. Otherwise, use following // snapshot tool work as continuation evidence; no work means final. const id = typeof item.id === "string" ? item.id : null; const phase = decidedPhase(decisions, id, position) ?? snapshotPhase(sourceOutput, position, lastToolIndex); changed = true; return { ...item, phase }; } return item; }); if (!changed) return block; const patched = { ...parsed, response: { ...response, output } }; return replaceSseDataPayload(block, JSON.stringify(patched)); } export function createResponsesPhaseInferenceBlockRewrite(budget: TranslatorBudget): SseBlockRewrite { // At most one message-done block is held at a time; the next block decides // its phase and is then processed itself. Malformed blocks pass through // without consuming the pending decision. Per-item decisions fill missing // snapshot phases. Both pending blocks and decisions share the request // retention budget and are released at a terminal event or teardown. let pending: string | null = null; let pendingBytes = 0; let decisionBytes = 0; const byId = new Map<string, PhaseDecision>(); const byIndex = new Map<number, PhaseDecision>(); const decisions: PhaseDecisions = { byId, byIndex }; const scope = { kind: "retained_collectors" as const }; const clearState = (): void => { budget.releaseRetained(pendingBytes + decisionBytes, scope); pending = null; pendingBytes = 0; decisionBytes = 0; byId.clear(); byIndex.clear(); }; const decisionSize = (decision: PhaseDecision): number => Buffer.byteLength(JSON.stringify([decision.id, decision.index, decision.phase])); const rememberPhase = (item: unknown, outputIndex: unknown, phase: OcxMessagePhase): void => { const id = isPlainObject(item) && typeof item.id === "string" ? item.id : null; const index = outputIndexOf(outputIndex); if (id === null && index === null) return; const next: PhaseDecision = { id, index, phase }; const replaced = new Set<PhaseDecision>(); const previousById = id !== null ? byId.get(id) : undefined; const previousByIndex = index !== null ? byIndex.get(index) : undefined; if (previousById) replaced.add(previousById); if (previousByIndex) replaced.add(previousByIndex); let delta = decisionSize(next); for (const previous of replaced) delta -= decisionSize(previous); // Charge before mutating, so a budget rejection leaves state consistent. if (delta > 0) budget.chargeRetained(delta, scope); else if (delta < 0) budget.releaseRetained(-delta, scope); for (const previous of replaced) { if (previous.id !== null && byId.get(previous.id) === previous) byId.delete(previous.id); if (previous.index !== null && byIndex.get(previous.index) === previous) byIndex.delete(previous.index); } if (id !== null) byId.set(id, next); if (index !== null) byIndex.set(index, next); decisionBytes += delta; }; const releasePending = (phase: OcxMessagePhase): readonly string[] => { if (pending === null) return []; const block = pending; const parsed = parseDataPayload(block); rememberPhase(parsed?.item, parsed?.output_index, phase); const patched = withMessagePhase(block, phase); budget.releaseRetained(pendingBytes, scope); pending = null; pendingBytes = 0; return [patched]; }; const rewrite = (block: string): readonly string[] => { const parsed = parseDataPayload(block); const type = typeof parsed?.type === "string" ? parsed.type : null; if (TERMINAL_EVENT_TYPES.has(type!)) { // A terminal snapshot can reveal tool work omitted from item events. // Use that continuation evidence before committing a pending phase. const output = isPlainObject(parsed?.response) && Array.isArray(parsed.response.output) ? parsed.response.output : []; // Any later tool proves continuation; one reverse scan suffices for every message. const lastToolIndex = type === "response.failed" ? -1 : output.findLastIndex(isToolCallItem); const held = pending === null ? null : parseDataPayload(pending); const heldItem = held?.item; const id = isPlainObject(heldItem) && typeof heldItem.id === "string" ? heldItem.id : null; const matched = id !== null ? output.findIndex(item => isPlainObject(item) && item.id === id) : -1; const index = outputIndexOf(held?.output_index); const indexed = index === null ? undefined : output[index]; const position = matched >= 0 ? matched : index !== null && (id === null || (isPlainObject(indexed) && typeof indexed.id !== "string")) ? index : -1; const released = releasePending(type === "response.failed" ? "final_answer" : snapshotPhase(output, position, lastToolIndex)); const snapshot = type === "response.failed" ? block : withSnapshotPhases(block, decisions, lastToolIndex); clearState(); return [...released, snapshot]; } if (type === "response.output_item.done" && isMessageDoneBlock(block)) { const item = parsed?.item; if (isPlainObject(item) && isMessagePhase(item.phase)) { // An explicit upstream phase needs no inference: forward immediately // instead of buffering a message that an abnormal teardown would // otherwise drop before it was ever emitted. const released = releasePending("commentary"); rememberPhase(item, parsed?.output_index, item.phase); return [...released, block]; } // A following message done means the turn continued past the buffered // one (a phase change or a guarded continuation): commentary. Buffer // the current block for classification by whatever comes next. const released = releasePending("commentary"); const bytes = Buffer.byteLength(block); budget.chargeRetained(bytes, scope); pending = block; pendingBytes = bytes; return released; } if (type === null) { // Comment keepalives and other non-JSON data blocks carry no // classification evidence in either direction, so a still-buffered // message stays pending across them. The [DONE] sentinel closes the // stream cleanly, which proves the buffered message was the turn's // final answer. if (isDoneSentinel(block)) { const released = releasePending("final_answer"); clearState(); return [...released, block]; } return [block]; } // Any other protocol event after a completed message proves the turn // continued past it (tool calls, reasoning, a new item): commentary. return [...releasePending("commentary"), block]; }; return Object.assign((block: string): readonly string[] => { try { return rewrite(block); } catch (error) { clearState(); throw error; } }, { dispose: () => { // Relay teardown after a terminal event leaves nothing pending. An // abnormal teardown before classification drops the retained block, // since the stream is failing anyway and no phase was ever proven. clearState(); }, }); }