@juspay/neurolink 12.36.0 → 12.37.0

package/dist/proxy/codexToAnthropicFallback.js

@@ -0,0 +1,408 @@
+/**
+ * Drives the Anthropic -> Codex response/stream codec against a real upstream
+ * `Response`. Mirrors `codexFallback.ts`, inverted: named after its own
+ * upstream, an Anthropic-shape engine, by the same convention `codexFallback.ts`
+ * is named after Codex.
+ *
+ * Scope: translation and the pre-commit/post-commit boundary only. Engine
+ * selection, OAuth/account selection, retry/cooldown policy and analytics
+ * recording are owned by sibling modules and are not this module's concern —
+ * it does not touch `src/lib/server/routes/codexProxyRoutes.ts`.
+ *
+ * SSE parsing note: this direction reads Anthropic-shaped SSE bytes, the same
+ * wire shape `preflightAnthropicStream` already buffers before this module
+ * ever sees the stream. Rather than duplicating `codexFallback.ts`'s
+ * carry/searchFrom scanner (built for the differently-shaped native Codex
+ * event vocabulary), this module reuses `extractSSEEvents` — the incremental
+ * Anthropic-SSE parser `preflightAnthropicStream` itself is built on — so the
+ * preflight-buffered chunks and the live remainder are parsed by the exact
+ * same code path. The carry/searchFrom scanner extraction into a shared
+ * `sseFrameScanner.ts` remains an explicitly-deferred follow-up either way.
+ */
+import { preflightAnthropicStream } from "./streamOutcome.js";
+import { extractSSEEvents } from "./sseInterceptor.js";
+import { CodexResponsesStreamSerializer, serializeCodexResponse, } from "./codexResponsesFormat.js";
+import { CODEX_STREAM_MAX_TOOL_CALLS, CODEX_STREAM_SIZE_CEILING_BYTES, } from "./streamLimits.js";
+/** Empty by default so an existing caller (no `toolKindByName` argument) keeps
+ *  treating every tool_use block as a `function` call, unchanged. */
+const NO_TOOL_KINDS = new Map();
+/** A non-2xx reply (either path) or a non-JSON reply (non-streaming path) from
+ *  the Anthropic-shape upstream, raised before any Codex frame is sent. */
+export class AnthropicFallbackResponseError extends Error {
+    status;
+    responseBody;
+    constructor(status, responseBody) {
+        super(`Anthropic fallback request returned HTTP ${status}`);
+        this.name = "AnthropicFallbackResponseError";
+        this.status = status;
+        this.responseBody = responseBody;
+    }
+}
+/** A pre-commit or post-commit failure while translating the Anthropic SSE
+ *  stream, or a well-formed non-streaming reply this module refuses to
+ *  translate (tool calls over `streamLimits.ts`'s count or size ceiling). */
+export class AnthropicFallbackStreamError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.name = "AnthropicFallbackStreamError";
+        this.status = status;
+        this.code = code;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isTokenCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function nonNegativeNumber(value) {
+    return isTokenCount(value) ? value : 0;
+}
+function optionalNumber(value) {
+    return isTokenCount(value) ? value : undefined;
+}
+/** Caps how much unparsed Anthropic SSE text this module will buffer — now
+ *  centralized in streamLimits.ts alongside the same ceiling `codexFallback.ts`
+ *  applies on the reverse direction, instead of a second local constant. */
+const MAX_BUFFER_CHARS = CODEX_STREAM_SIZE_CEILING_BYTES;
+/**
+ * The streaming driver's per-turn tool-call ceilings. `open` and `addArgs`
+ * return the `emitFailure` arguments to end the turn with once a call would
+ * pass the count limit or its accumulated argument text the size limit.
+ */
+function createToolCallCeilings() {
+    let opened = 0;
+    let argsLength = 0;
+    return {
+        open() {
+            if (opened >= CODEX_STREAM_MAX_TOOL_CALLS) {
+                return [
+                    502,
+                    "Anthropic fallback stream exceeded the tool-call limit",
+                    "too_many_tool_calls",
+                ];
+            }
+            opened++;
+            argsLength = 0;
+            return undefined;
+        },
+        addArgs(fragment) {
+            argsLength += fragment.length;
+            return argsLength > CODEX_STREAM_SIZE_CEILING_BYTES
+                ? [
+                    502,
+                    "Anthropic fallback tool arguments exceeded the size limit",
+                    "tool_arguments_too_large",
+                ]
+                : undefined;
+        },
+    };
+}
+/**
+ * Consume a fully-buffered, non-streaming Anthropic-shape response and
+ * translate it into one Codex Responses envelope.
+ *
+ * No `message_start`/`message_delta` split here: a single JSON object
+ * carries the whole turn's usage at once (confirmed against this repo's own
+ * `settleFromResponseUsage`, which reads a non-streaming Anthropic body the
+ * same way), so the translation delegates straight to `serializeCodexResponse`.
+ */
+export async function consumeAnthropicFallbackResponse(response, model, toolKindByName = NO_TOOL_KINDS) {
+    if (!response.ok) {
+        throw new AnthropicFallbackResponseError(response.status, await response.text().catch(() => ""));
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const text = await response.text().catch(() => "");
+    if (!contentType.toLowerCase().includes("application/json")) {
+        throw new AnthropicFallbackResponseError(response.status, text);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new AnthropicFallbackResponseError(response.status, text);
+    }
+    if (!isRecord(parsed) ||
+        parsed.type !== "message" ||
+        !Array.isArray(parsed.content) ||
+        !isRecord(parsed.usage)) {
+        throw new AnthropicFallbackResponseError(response.status, text);
+    }
+    const toolUses = parsed.content.filter((block) => isRecord(block) && block.type === "tool_use");
+    if (toolUses.length > CODEX_STREAM_MAX_TOOL_CALLS) {
+        throw new AnthropicFallbackStreamError(502, "Anthropic fallback response exceeded the tool-call limit", "too_many_tool_calls");
+    }
+    if (toolUses.some((block) => JSON.stringify(block.input ?? {}).length >
+        CODEX_STREAM_SIZE_CEILING_BYTES)) {
+        throw new AnthropicFallbackStreamError(502, "Anthropic fallback tool arguments exceeded the size limit", "tool_arguments_too_large");
+    }
+    // The same number checks the streaming path applies to message_start, so a
+    // malformed count becomes 0 (or is omitted) rather than reaching the totals.
+    const usage = parsed.usage;
+    const cacheCreate = optionalNumber(usage.cache_creation_input_tokens);
+    const cacheRead = optionalNumber(usage.cache_read_input_tokens);
+    const result = {
+        ...parsed,
+        usage: {
+            input_tokens: nonNegativeNumber(usage.input_tokens),
+            output_tokens: nonNegativeNumber(usage.output_tokens),
+            ...(cacheCreate === undefined
+                ? {}
+                : { cache_creation_input_tokens: cacheCreate }),
+            ...(cacheRead === undefined
+                ? {}
+                : { cache_read_input_tokens: cacheRead }),
+        },
+    };
+    return serializeCodexResponse(result, model, toolKindByName);
+}
+/**
+ * Translate an Anthropic SSE stream into Codex-shape SSE frames as events
+ * arrive. The caller owns error framing downstream and must never retry
+ * after any frame has been emitted (mirrors `codexFallback.ts`'s own
+ * discipline, `:715-718`).
+ */
+export async function createAnthropicFallbackStream(response, model, toolKindByName = NO_TOOL_KINDS) {
+    if (!response.ok) {
+        throw new AnthropicFallbackResponseError(response.status, await response.text().catch(() => ""));
+    }
+    if (!response.body) {
+        throw new AnthropicFallbackStreamError(502, "Anthropic fallback returned an empty stream", "empty_response");
+    }
+    const reader = response.body.getReader();
+    let cancellation;
+    const cancel = (reason) => {
+        cancellation ??= reader
+            .cancel(reason)
+            .catch(() => undefined)
+            .finally(() => reader.releaseLock());
+        return cancellation;
+    };
+    const preflight = await preflightAnthropicStream(reader);
+    if (preflight.kind !== "ready") {
+        // Pre-commit: nothing Codex-shaped sent yet. Release the reader and its
+        // admission lease before throwing, so a caller that tries the next
+        // engine is not blocked by a lease this hop still held.
+        await cancel();
+        if (preflight.kind === "sse_error") {
+            throw new AnthropicFallbackStreamError(502, preflight.message, preflight.errorType);
+        }
+        if (preflight.kind === "transport_error") {
+            throw new AnthropicFallbackStreamError(502, "Anthropic fallback transport failed before any content", "transport_error");
+        }
+        throw new AnthropicFallbackStreamError(502, "Anthropic fallback stream ended before any content", "empty_response");
+    }
+    const serializer = new CodexResponsesStreamSerializer(model, toolKindByName);
+    async function* frames() {
+        yield* serializer.start();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let capturedInput = 0;
+        let capturedOutput = 0;
+        let capturedCacheCreate;
+        let capturedCacheRead;
+        let capturedStopReason = null;
+        // input_json_delta also streams for server_tool_use blocks, which have no
+        // Codex function_call to feed; only a tool_use block's fragments count.
+        let currentBlockType;
+        const ceilings = createToolCallCeilings();
+        /** One parsed Anthropic SSE event -> zero or more Codex frames, or the
+         *  terminal envelope once `message_stop` (or a failure) is reached. */
+        function* processEvent(type, payload) {
+            switch (type) {
+                case "message_start": {
+                    const message = payload.message;
+                    const usage = isRecord(message) ? message.usage : undefined;
+                    if (isRecord(usage)) {
+                        capturedInput = nonNegativeNumber(usage.input_tokens);
+                        capturedCacheCreate = optionalNumber(usage.cache_creation_input_tokens);
+                        capturedCacheRead = optionalNumber(usage.cache_read_input_tokens);
+                    }
+                    return undefined;
+                }
+                case "content_block_start": {
+                    const block = payload.content_block;
+                    currentBlockType =
+                        isRecord(block) && typeof block.type === "string"
+                            ? block.type
+                            : undefined;
+                    if (isRecord(block) && block.type === "tool_use") {
+                        const overLimit = ceilings.open();
+                        if (overLimit) {
+                            return yield* serializer.emitFailure(...overLimit);
+                        }
+                        const id = typeof block.id === "string" ? block.id : "";
+                        const name = typeof block.name === "string" ? block.name : "";
+                        yield* serializer.openToolCall(id, name);
+                    }
+                    // "text" opens lazily on its first delta; "thinking" is dropped by
+                    // design (ClaudeThinkingBlock carries no signature to preserve).
+                    return undefined;
+                }
+                case "content_block_delta": {
+                    const delta = payload.delta;
+                    if (!isRecord(delta)) {
+                        return undefined;
+                    }
+                    if (delta.type === "text_delta" && typeof delta.text === "string") {
+                        yield* serializer.pushDelta(delta.text);
+                    }
+                    else if (delta.type === "input_json_delta" &&
+                        currentBlockType === "tool_use" &&
+                        typeof delta.partial_json === "string") {
+                        // Checked before the fragment is forwarded: the call closes
+                        // incomplete, never completed with its arguments cut mid-object.
+                        const overLimit = ceilings.addArgs(delta.partial_json);
+                        if (overLimit) {
+                            return yield* serializer.emitFailure(...overLimit);
+                        }
+                        yield* serializer.pushToolCallArgsDelta(delta.partial_json);
+                    }
+                    // thinking_delta: zero frames.
+                    return undefined;
+                }
+                case "content_block_stop": {
+                    currentBlockType = undefined;
+                    try {
+                        yield* serializer.closeToolCall();
+                    }
+                    catch {
+                        // Malformed tool-call JSON: a named, handled case — never a
+                        // fallthrough exception. No function_call_arguments.done was
+                        // emitted, since closeToolCall throws before reaching it.
+                        return yield* serializer.emitFailure(502, "Anthropic fallback tool arguments were not valid JSON", "invalid_tool_arguments");
+                    }
+                    yield* serializer.closeTextBlock();
+                    return undefined;
+                }
+                case "message_delta": {
+                    const delta = payload.delta;
+                    if (isRecord(delta)) {
+                        capturedStopReason =
+                            typeof delta.stop_reason === "string" ? delta.stop_reason : null;
+                    }
+                    const usage = payload.usage;
+                    // Only output_tokens is read here — never input/cache fields.
+                    // message_delta carries only the running output total; reading
+                    // cache fields from it would zero cache accounting on every
+                    // response (that was the original design draft's Blocker).
+                    if (isRecord(usage) && usage.output_tokens !== undefined) {
+                        capturedOutput = nonNegativeNumber(usage.output_tokens);
+                    }
+                    return undefined;
+                }
+                case "message_stop":
+                    return yield* serializer.finish(capturedStopReason, {
+                        input_tokens: capturedInput,
+                        output_tokens: capturedOutput,
+                        ...(capturedCacheCreate === undefined
+                            ? {}
+                            : { cache_creation_input_tokens: capturedCacheCreate }),
+                        ...(capturedCacheRead === undefined
+                            ? {}
+                            : { cache_read_input_tokens: capturedCacheRead }),
+                    });
+                case "error": {
+                    // A mid-stream upstream error ends the turn: without this case it
+                    // would fall to default and the client would wait on a stream that
+                    // never terminates.
+                    const error = payload.error;
+                    const code = isRecord(error) && typeof error.type === "string"
+                        ? error.type
+                        : "upstream_error";
+                    const message = isRecord(error) && typeof error.message === "string"
+                        ? error.message
+                        : "Anthropic fallback stream reported an error";
+                    return yield* serializer.emitFailure(502, message, code);
+                }
+                // "ping" and any other event type this repo does not name are
+                // consumed and produce zero Codex-shape frames.
+                default:
+                    return undefined;
+            }
+        }
+        function* consumeEvents(events) {
+            for (const raw of events) {
+                let payload;
+                try {
+                    payload = JSON.parse(raw.data);
+                }
+                catch {
+                    // A single malformed Anthropic frame is skipped defensively rather
+                    // than failing the whole turn over one unparsable event.
+                    continue;
+                }
+                if (!isRecord(payload)) {
+                    continue;
+                }
+                const type = typeof payload.type === "string" ? payload.type : raw.event;
+                if (!type) {
+                    continue;
+                }
+                // After response.created has gone out, any serializer throw must still
+                // end the turn with response.failed; emitFailure closes an open item
+                // as incomplete without re-validating it.
+                let result;
+                try {
+                    result = yield* processEvent(type, payload);
+                }
+                catch {
+                    return yield* serializer.emitFailure(502, "Anthropic fallback stream could not be translated", "translation_error");
+                }
+                if (result) {
+                    return result;
+                }
+            }
+            return undefined;
+        }
+        try {
+            // Preflight's buffered chunks run THROUGH the interpreter first — never
+            // replayed raw, unlike the Claude-facing route where upstream shape
+            // already equals client shape.
+            for (const chunk of preflight.chunks) {
+                buffer += decoder.decode(chunk, { stream: true });
+            }
+            let parsed = extractSSEEvents(buffer);
+            buffer = parsed.remainder;
+            let result = yield* consumeEvents(parsed.events);
+            if (result) {
+                return result;
+            }
+            while (true) {
+                let chunk;
+                try {
+                    chunk = await reader.read();
+                }
+                catch {
+                    // Post-commit (response.created already flushed): a silent swap is
+                    // impossible, so this closes the open item incomplete and emits a
+                    // single response.failed rather than throwing.
+                    return yield* serializer.emitFailure(502, "Anthropic fallback stream failed while reading", "upstream_read_error");
+                }
+                buffer += chunk.done
+                    ? decoder.decode()
+                    : decoder.decode(chunk.value, { stream: true });
+                if (buffer.length > MAX_BUFFER_CHARS) {
+                    return yield* serializer.emitFailure(502, "Anthropic fallback translation exceeded the stream limit", "stream_too_large");
+                }
+                parsed = extractSSEEvents(buffer);
+                buffer = parsed.remainder;
+                result = yield* consumeEvents(parsed.events);
+                if (result) {
+                    return result;
+                }
+                if (chunk.done) {
+                    break;
+                }
+            }
+            return yield* serializer.emitFailure(502, "Anthropic fallback stream ended before message_stop", "incomplete_stream");
+        }
+        finally {
+            await cancel();
+        }
+    }
+    return { frames: frames(), cancel };
+}

package/dist/proxy/proxyTracer.d.ts

@@ -127,6 +127,27 @@ export declare function recordFallbackAttempt(attrs: {
     errorMessage?: string;
     durationMs: number;
 }): void;
+/**
+ * Records one Codex-outbound tool-declaration schema degradation (a
+ * `$ref`/`$defs` flatten that hit a circular reference, a dropped `strict`
+ * flag, or a custom grammar tool wrapped into a one-string schema). `reason`
+ * is a short, stable label — never the schema or tool-name text itself, so a
+ * call site cannot accidentally leak request payload into a metric label.
+ */
+export declare function recordCodexOutboundSchemaDegraded(attrs: {
+    toolName: string;
+    reason: string;
+}): void;
+/**
+ * Records one Codex-outbound request field dropped during translation
+ * because this repo has no faithful Claude-request representation for it
+ * (e.g. a malformed `function_call.arguments` string wrapped instead of
+ * parsed). Mirrors `recordCodexOutboundSchemaDegraded`'s label discipline.
+ */
+export declare function recordCodexOutboundUnsupportedField(attrs: {
+    field: string;
+    reason: string;
+}): void;
 /** Reset leg-health state between tests. */
 export declare const __fallbackLegHealthTestHooks: {
     threshold: number;

package/dist/proxy/proxyTracer.js

@@ -102,6 +102,14 @@ function getProxyMetrics() {
             description: "Total failed fallback provider responses",
             unit: "{failure}",
         }),
+        schemaDegradedTotal: meter.createCounter("proxy_codex_outbound_schema_degraded_total", {
+            description: "Total Codex-outbound tool declarations whose JSON Schema needed flattening or lost a feature on the way to a Claude tool",
+            unit: "{tool}",
+        }),
+        unsupportedFieldTotal: meter.createCounter("proxy_codex_outbound_unsupported_field_total", {
+            description: "Total Codex-outbound request fields this repo cannot faithfully represent in the Claude request, dropped rather than failing the translation",
+            unit: "{field}",
+        }),
     };
     _metrics = createdMetrics;
     return createdMetrics;
@@ -865,6 +873,43 @@ export function recordFallbackAttempt(attrs) {
         // metrics are best-effort
     }
 }
+/**
+ * Records one Codex-outbound tool-declaration schema degradation (a
+ * `$ref`/`$defs` flatten that hit a circular reference, a dropped `strict`
+ * flag, or a custom grammar tool wrapped into a one-string schema). `reason`
+ * is a short, stable label — never the schema or tool-name text itself, so a
+ * call site cannot accidentally leak request payload into a metric label.
+ */
+export function recordCodexOutboundSchemaDegraded(attrs) {
+    try {
+        const m = getProxyMetrics();
+        m.schemaDegradedTotal.add(1, {
+            toolName: attrs.toolName.slice(0, 100),
+            reason: attrs.reason.slice(0, 100),
+        });
+    }
+    catch {
+        // metrics are best-effort
+    }
+}
+/**
+ * Records one Codex-outbound request field dropped during translation
+ * because this repo has no faithful Claude-request representation for it
+ * (e.g. a malformed `function_call.arguments` string wrapped instead of
+ * parsed). Mirrors `recordCodexOutboundSchemaDegraded`'s label discipline.
+ */
+export function recordCodexOutboundUnsupportedField(attrs) {
+    try {
+        const m = getProxyMetrics();
+        m.unsupportedFieldTotal.add(1, {
+            field: attrs.field.slice(0, 100),
+            reason: attrs.reason.slice(0, 100),
+        });
+    }
+    catch {
+        // metrics are best-effort
+    }
+}
 /** Reset leg-health state between tests. */
 export const __fallbackLegHealthTestHooks = {
     threshold: DEAD_FALLBACK_LEG_THRESHOLD,

package/dist/proxy/streamLimits.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Size/count ceilings for the Codex-outbound fallback, centralized so request
+ * ingestion (`codexOutboundFallback.ts`) and response translation
+ * (`codexToAnthropicFallback.ts`) share one source instead of re-declaring the
+ * numbers `codexFallback.ts` already applies on the reverse
+ * (Claude-into-Codex) leg (`:763`, `:784`).
+ */
+/** Caps how much unparsed upstream SSE text a translator buffers, and how
+ *  long one tool call's argument, input or output text may be, mirroring
+ *  codexFallback.ts's own ceiling for the reverse leg. */
+export declare const CODEX_STREAM_SIZE_CEILING_BYTES: number;
+/** Caps how many tool calls one turn may open or replay, mirroring
+ *  codexFallback.ts's own ceiling for the reverse leg — a runaway or
+ *  adversarial upstream cannot make a translator accumulate unbounded
+ *  open-item state. */
+export declare const CODEX_STREAM_MAX_TOOL_CALLS = 4096;

package/dist/proxy/streamLimits.js

@@ -0,0 +1,16 @@
+/**
+ * Size/count ceilings for the Codex-outbound fallback, centralized so request
+ * ingestion (`codexOutboundFallback.ts`) and response translation
+ * (`codexToAnthropicFallback.ts`) share one source instead of re-declaring the
+ * numbers `codexFallback.ts` already applies on the reverse
+ * (Claude-into-Codex) leg (`:763`, `:784`).
+ */
+/** Caps how much unparsed upstream SSE text a translator buffers, and how
+ *  long one tool call's argument, input or output text may be, mirroring
+ *  codexFallback.ts's own ceiling for the reverse leg. */
+export const CODEX_STREAM_SIZE_CEILING_BYTES = 16 * 1024 * 1024;
+/** Caps how many tool calls one turn may open or replay, mirroring
+ *  codexFallback.ts's own ceiling for the reverse leg — a runaway or
+ *  adversarial upstream cannot make a translator accumulate unbounded
+ *  open-item state. */
+export const CODEX_STREAM_MAX_TOOL_CALLS = 4096;

package/dist/types/codex.d.ts

@@ -11,7 +11,7 @@
  * stored through the same AccountQuota shape as Anthropic — its primary window
  * maps onto the session fields and its secondary window onto the weekly fields.
  */
-import type { AccountCoolingReason, AccountQuota, ClaudeContentBlock, InternalResult } from "./proxy.js";
+import type { AccountCoolingReason, AccountQuota, ClaudeContentBlock, ClaudeTool, InternalResult } from "./proxy.js";
 /** Token block inside `~/.codex/auth.json`. */
 export type CodexAuthFileTokens = {
     id_token?: string;
@@ -226,6 +226,26 @@ export type CodexNativeCustomToolDeclaration = {
 };
 /** A single tool declaration, discriminated by its own `type` field. */
 export type CodexNativeToolDeclaration = CodexNativeFunctionToolDeclaration | CodexNativeCustomToolDeclaration;
+/**
+ * A declared tool's own kind, independent of its namespace. Claude's
+ * `tool_use` block carries only `name` + `input`, with no such discriminator,
+ * so response serialization threads a name -> kind map (built while flattening
+ * `additional_tools` on the request side) to decide whether a tool_use's
+ * `input` is a real JSON-Schema-shaped object (`function`) or the single
+ * grammar-constrained string a custom tool was wrapped into (`custom`).
+ */
+export type CodexNativeToolKind = "function" | "custom";
+/**
+ * One declared tool's mapping outcome inside `codexOutboundFallback.ts`:
+ * the translated Claude tool, its kind (for `toolKindByName`), and any
+ * degrade reasons collected while flattening its schema (fed to
+ * `recordCodexOutboundSchemaDegraded` in `proxyTracer.ts`).
+ */
+export type CodexOutboundToolMappingResult = {
+    tool: ClaudeTool;
+    kind: CodexNativeToolKind;
+    reasons: string[];
+};
 /** A named group of tool declarations inside one `additional_tools` item. */
 export type CodexNativeToolNamespace = {
     type: "namespace";
@@ -314,6 +334,8 @@ export type CodexNativeRequest = {
  * A `parseCodexNativeRequest`/`translateCodexRequestToClaude` failure. Never thrown.
  * `UNTRANSLATABLE_REQUEST` is a request Codex itself accepts but Anthropic would
  * reject, as opposed to one that is invalid on the Codex wire.
+ * `REQUEST_TOO_LARGE` is a tool-call history over `streamLimits.ts`'s count or
+ * size ceiling; callers map it to HTTP 413 `request_too_large`.
  */
 export type CodexTranslationError = {
     code: "MALFORMED_REQUEST";
@@ -324,9 +346,99 @@ export type CodexTranslationError = {
 } | {
     code: "UNTRANSLATABLE_REQUEST";
     message: string;
+} | {
+    code: "REQUEST_TOO_LARGE";
+    message: string;
 };
 /** One coalesced run of same-role content while flattening a native Codex `input` array. */
 export type CodexOutboundMessageGroup = {
     role: "user" | "assistant";
     blocks: ClaudeContentBlock[];
 };
+/** Lifecycle status of one item inside a Codex Responses `output[]` array. */
+export type CodexResponseItemStatus = "in_progress" | "completed" | "incomplete";
+/** Wire usage block inside a synthesized response.completed / non-stream response. */
+export type CodexResponseUsage = {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    /** Omitted entirely when neither cache field was observed on the Anthropic side. */
+    input_tokens_details?: {
+        cached_tokens?: number;
+        cache_write_tokens?: number;
+    };
+    /** Always omitted — ClaudeUsage carries no reasoning-token count to source it from. */
+    output_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+};
+/** One `output_text` content part inside a Codex `message` output item. */
+export type CodexResponseOutputTextPart = {
+    type: "output_text";
+    text: string;
+    annotations: [];
+};
+/** A synthesized assistant-text item in a Codex `response.output[]` array. */
+export type CodexResponseMessageItem = {
+    id: string;
+    type: "message";
+    role: "assistant";
+    status: CodexResponseItemStatus;
+    content: CodexResponseOutputTextPart[];
+};
+/** A synthesized tool-call item in a Codex `response.output[]` array. */
+export type CodexResponseFunctionCallItem = {
+    id: string;
+    type: "function_call";
+    status: CodexResponseItemStatus;
+    call_id: string;
+    name: string;
+    /** Concatenation of raw partial_json fragments. Valid JSON when status is
+     *  "completed"; may be a truncated, non-JSON fragment when status is
+     *  "incomplete" (closed early by a mid-stream failure). */
+    arguments: string;
+};
+/**
+ * A synthesized call to a tool the request declared `custom` (grammar-
+ * constrained), in the item shape the real backend emits for one — the shape
+ * `codexUsage.ts` reads on the native route and a Codex CLI replays in its
+ * history. `input` is the bare grammar text, never JSON.
+ */
+export type CodexResponseCustomToolCallItem = {
+    id: string;
+    type: "custom_tool_call";
+    status: CodexResponseItemStatus;
+    call_id: string;
+    name: string;
+    /** Empty when status is "incomplete" and the wrapped input never parsed. */
+    input: string;
+};
+/** One item in a Codex `response.output[]` array, discriminated by `type`. */
+export type CodexResponseItem = CodexResponseMessageItem | CodexResponseFunctionCallItem | CodexResponseCustomToolCallItem;
+/** A complete Codex Responses envelope — the non-streaming body, and the shape
+ *  carried inside a terminal `response.*` SSE event's `response` field. */
+export type CodexResponseEnvelope = {
+    id: string;
+    object: "response";
+    created_at: number;
+    status: "completed" | "incomplete" | "failed";
+    model: string;
+    output: CodexResponseItem[];
+    usage?: CodexResponseUsage;
+    incomplete_details: {
+        reason: "max_output_tokens";
+    } | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+};
+/** The Codex Responses SSE event-type vocabulary this codec emits. */
+export type CodexResponseSSEEventType = "response.created" | "response.in_progress" | "response.output_item.added" | "response.content_part.added" | "response.output_text.delta" | "response.output_text.done" | "response.content_part.done" | "response.function_call_arguments.delta" | "response.function_call_arguments.done" | "response.custom_tool_call_input.delta" | "response.custom_tool_call_input.done" | "response.output_item.done" | "response.completed" | "response.incomplete" | "response.failed";
+/** Incremental Codex-shape SSE frames and the terminal envelope they resolve to. */
+export type CodexResponseStream = {
+    frames: AsyncGenerator<string, CodexResponseEnvelope>;
+    cancel: (reason?: unknown) => Promise<void>;
+};
+/** Which output item kind (if any) `CodexResponsesStreamSerializer` currently has open. */
+export type CodexResponseOpenItemKind = "message" | "function_call" | "custom_tool_call" | null;