jev-gateway 0.1.0

package/dist/adapters/messages.js

@@ -0,0 +1,135 @@
+import { randomBytes } from "node:crypto";
+import { textOf, truncate } from "../state.js";
+import { sse } from "./adapter.js";
+const isClientTool = (tool) => tool.type === undefined || tool.type === "custom";
+function toTools(raw) {
+    return raw
+        .filter((tool) => typeof tool?.name === "string")
+        .map((tool) => isClientTool(tool)
+        ? { kind: "function", name: tool.name, description: tool.description, parameters: tool.input_schema }
+        : { kind: "hosted", name: tool.name, description: tool.description ?? `Anthropic's built-in ${tool.name} tool.` });
+}
+function toInput(req, maxMessageChars) {
+    if (!Array.isArray(req.messages))
+        return { skip: "no_messages" };
+    const clip = (value) => truncate(textOf(value), maxMessageChars);
+    const toolNameById = new Map();
+    const turns = [];
+    for (const message of req.messages) {
+        if (typeof message.content === "string") {
+            turns.push({ role: message.role, text: clip(message.content) });
+            continue;
+        }
+        // One message can interleave prose, tool calls and tool results; Jev reads them as separate turns.
+        const text = [];
+        const flushText = () => {
+            if (text.length)
+                turns.push({ role: message.role, text: clip(text.splice(0)) });
+        };
+        for (const block of message.content ?? []) {
+            if (block.type === "tool_use" || block.type === "server_tool_use") {
+                flushText();
+                if (block.id && block.name)
+                    toolNameById.set(block.id, block.name);
+                turns.push({
+                    role: "assistant",
+                    tool_calls: [{ tool: block.name ?? "unknown", arguments: clip(JSON.stringify(block.input ?? {})) }],
+                });
+            }
+            else if (block.type === "tool_result" || block.type.endsWith("_tool_result")) {
+                flushText();
+                turns.push({
+                    role: "tool_result",
+                    tool: toolNameById.get(block.tool_use_id ?? "") ?? "unknown",
+                    content: clip(block.content),
+                });
+            }
+            else if (block.type !== "thinking" && block.type !== "redacted_thinking") {
+                text.push(block);
+            }
+        }
+        flushText();
+    }
+    const choice = req.tool_choice?.type ?? "auto";
+    const thinking = req.thinking?.type !== undefined && req.thinking.type !== "disabled";
+    // Two reasons not to touch tool_choice: the API rejects a forced tool while extended thinking
+    // is on, and any tool_choice change invalidates the cached conversation — which an agent like
+    // Claude Code re-reads on every turn. A trailing hint does neither.
+    const cached = JSON.stringify(req.messages).includes('"cache_control"') || "cache_control" in req;
+    return {
+        system: textOf(req.system),
+        turns,
+        tools: toTools(Array.isArray(req.tools) ? req.tools : []),
+        toolChoice: choice === "auto" ? "auto" : choice === "any" ? "required" : "decided",
+        steer: thinking || cached ? "hint" : "tool_choice",
+    };
+}
+/**
+ * Suggest Jev's pick in a block appended after everything the client sent. Cache breakpoints sit
+ * on the client's own blocks, so the cached prefix stays byte-identical to what the client will
+ * resend next turn; the wording leaves the model free to disagree.
+ */
+function withHint(req, tool) {
+    const messages = req.messages ?? [];
+    const last = messages.at(-1);
+    if (last?.role !== "user")
+        return req;
+    const hint = {
+        type: "text",
+        text: `<system-reminder>A tool-routing model suggests the "${tool}" tool is the most relevant next step. ` +
+            "Ignore this if it does not fit what the user actually asked for.</system-reminder>",
+    };
+    const content = typeof last.content === "string" ? [{ type: "text", text: last.content }] : last.content;
+    return { ...req, messages: [...messages.slice(0, -1), { ...last, content: [...content, hint] }] };
+}
+function apply(req, decision, argsModel) {
+    if (decision.mode === "hint")
+        return withHint(req, decision.tool);
+    const parallel = req.tool_choice?.disable_parallel_tool_use === undefined
+        ? {}
+        : { disable_parallel_tool_use: req.tool_choice.disable_parallel_tool_use };
+    if (decision.mode === "forced") {
+        return { ...req, model: argsModel ?? req.model, tool_choice: { type: "tool", name: decision.tool, ...parallel } };
+    }
+    if (decision.mode === "none")
+        return { ...req, tool_choice: { type: "none" } };
+    return req;
+}
+const hex = (bytes) => randomBytes(bytes).toString("hex");
+function build(req, call) {
+    const block = { type: "tool_use", id: `toolu_jev_${hex(12)}`, name: call.tool, input: call.args };
+    const usage = {
+        input_tokens: call.inputTokens,
+        cache_creation_input_tokens: 0,
+        cache_read_input_tokens: 0,
+        output_tokens: 0,
+    };
+    const message = {
+        id: `msg_jev_${hex(12)}`,
+        type: "message",
+        role: "assistant",
+        model: req.model ?? "jev-gateway",
+        content: [block],
+        stop_reason: "tool_use",
+        stop_sequence: null,
+        usage,
+    };
+    return { block, message, usage };
+}
+function directJson(req, call) {
+    return build(req, call).message;
+}
+/** The event sequence Claude itself streams for a single tool call. */
+function directStream(req, call) {
+    const { block, message, usage } = build(req, call);
+    const events = [
+        { type: "message_start", message: { ...message, content: [], stop_reason: null } },
+        { type: "content_block_start", index: 0, content_block: { ...block, input: {} } },
+        { type: "content_block_delta", index: 0, delta: { type: "input_json_delta", partial_json: JSON.stringify(call.args) } },
+        { type: "content_block_stop", index: 0 },
+        { type: "message_delta", delta: { stop_reason: "tool_use", stop_sequence: null }, usage: { output_tokens: usage.output_tokens } },
+        { type: "message_stop" },
+    ];
+    return sse(events.map((event) => ({ event: event.type, data: JSON.stringify(event) })));
+}
+export const messagesAdapter = { toInput, apply, directJson, directStream };

package/dist/adapters/responses.js

@@ -0,0 +1,184 @@
+import { randomBytes } from "node:crypto";
+import { textOf, truncate } from "../state.js";
+import { sse } from "./adapter.js";
+const HOSTED_DESCRIPTIONS = {
+    web_search: "Search the web for up-to-date information the assistant does not already have.",
+    web_search_preview: "Search the web for up-to-date information the assistant does not already have.",
+    local_shell: "Run a shell command on the user's machine.",
+    image_generation: "Generate an image.",
+    code_interpreter: "Run Python code in a sandbox.",
+    file_search: "Search the user's uploaded files.",
+};
+/** The namespace whose tools are addressed by bare name, as top-level tools are. */
+const DEFAULT_NAMESPACE = "functions";
+const qualified = (namespace, name) => namespace && namespace !== DEFAULT_NAMESPACE ? `${namespace}.${name}` : name;
+const inputItems = (req) => typeof req.input === "string" ? [{ role: "user", content: req.input }] : Array.isArray(req.input) ? req.input : [];
+/**
+ * Tools come from two places. Classic requests list them in `tools`; "responses-lite" ones
+ * (what Codex sends for its newer models) leave `tools` out entirely and declare them in
+ * `additional_tools` input items, grouped into namespaces.
+ */
+function declaredTools(req) {
+    const declared = Array.isArray(req.tools) ? [...req.tools] : [];
+    for (const item of inputItems(req)) {
+        if (item.type === "additional_tools" && Array.isArray(item.tools))
+            declared.push(...item.tools);
+    }
+    return declared;
+}
+function toTools(raw) {
+    const tools = new Map();
+    const add = (tool, namespace) => {
+        if (tool.type === "namespace") {
+            for (const nested of Array.isArray(tool.tools) ? tool.tools : [])
+                add(nested, tool);
+        }
+        else if ((tool.type === "function" || tool.type === "custom") && tool.name) {
+            const name = qualified(namespace?.name, tool.name);
+            const group = name === tool.name ? undefined : namespace?.description?.trim();
+            tools.set(name, {
+                kind: tool.type,
+                name,
+                description: group ? `[${group}] ${tool.description ?? ""}`.trim() : tool.description,
+                parameters: tool.type === "function" ? tool.parameters : undefined,
+                ...(name === tool.name ? {} : { namespace: namespace?.name }),
+            });
+        }
+        else if (tool.type && !tools.has(tool.type)) {
+            tools.set(tool.type, {
+                kind: "hosted",
+                name: tool.type,
+                description: HOSTED_DESCRIPTIONS[tool.type] ?? tool.description ?? `The built-in ${tool.type} tool.`,
+            });
+        }
+    };
+    for (const tool of raw)
+        add(tool);
+    return [...tools.values()];
+}
+function toInput(req, maxMessageChars) {
+    // With server-side history the router would be judging a conversation it cannot see.
+    if (req.previous_response_id)
+        return { skip: "previous_response_id" };
+    const items = inputItems(req);
+    const clip = (value) => truncate(typeof value === "string" ? value : textOf(value), maxMessageChars);
+    const toolNameByCallId = new Map();
+    const system = typeof req.instructions === "string" && req.instructions ? [req.instructions] : [];
+    const turns = [];
+    for (const item of items) {
+        const type = item.type ?? (item.role ? "message" : undefined);
+        if (type === "message") {
+            const text = clip(item.content);
+            if (item.role === "system" || item.role === "developer") {
+                if (text)
+                    system.push(text);
+            }
+            else {
+                turns.push({ role: item.role ?? "user", text });
+            }
+        }
+        else if (type === "function_call" || type === "custom_tool_call") {
+            const name = qualified(item.namespace, item.name ?? "unknown");
+            if (item.call_id)
+                toolNameByCallId.set(item.call_id, name);
+            turns.push({
+                role: "assistant",
+                tool_calls: [{ tool: name, arguments: clip(item.arguments ?? item.input ?? "") }],
+            });
+        }
+        else if (type === "local_shell_call") {
+            if (item.call_id)
+                toolNameByCallId.set(item.call_id, "local_shell");
+            turns.push({
+                role: "assistant",
+                tool_calls: [{ tool: "local_shell", arguments: clip((item.action?.command ?? []).join(" ")) }],
+            });
+        }
+        else if (type?.endsWith("_call_output")) {
+            turns.push({
+                role: "tool_result",
+                tool: toolNameByCallId.get(item.call_id ?? "") ?? "unknown",
+                content: clip(item.output),
+            });
+        }
+        // Reasoning items (encrypted), item references and hosted-tool traces carry nothing Jev can read.
+    }
+    const choice = req.tool_choice ?? "auto";
+    return {
+        system: system.join("\n\n"),
+        turns,
+        tools: toTools(declaredTools(req)),
+        toolChoice: choice === "auto" || choice === "required" ? choice : "decided",
+    };
+}
+function apply(req, decision, argsModel) {
+    if (decision.mode === "forced") {
+        return {
+            ...req,
+            model: argsModel ?? req.model,
+            tool_choice: { type: decision.kind === "custom" ? "custom" : "function", name: decision.tool },
+        };
+    }
+    if (decision.mode === "none")
+        return { ...req, tool_choice: "none" };
+    return req;
+}
+const hex = (bytes) => randomBytes(bytes).toString("hex");
+function build(req, call) {
+    const item = {
+        type: "function_call",
+        id: `fc_${hex(16)}`,
+        call_id: `call_${hex(12)}`,
+        name: call.tool,
+        arguments: JSON.stringify(call.args),
+        status: "completed",
+    };
+    const response = {
+        id: `resp_jev_${hex(16)}`,
+        object: "response",
+        created_at: Math.floor(Date.now() / 1000),
+        status: "completed",
+        error: null,
+        incomplete_details: null,
+        instructions: null,
+        model: req.model ?? "jev-gateway",
+        output: [item],
+        parallel_tool_calls: req.parallel_tool_calls ?? true,
+        previous_response_id: null,
+        store: false,
+        tool_choice: req.tool_choice ?? "auto",
+        tools: req.tools ?? [],
+        metadata: {},
+        usage: {
+            input_tokens: call.inputTokens,
+            input_tokens_details: { cached_tokens: 0 },
+            output_tokens: 0,
+            output_tokens_details: { reasoning_tokens: 0 },
+            total_tokens: call.inputTokens,
+        },
+    };
+    return { item, response };
+}
+function directJson(req, call) {
+    return build(req, call).response;
+}
+/** The event sequence an LLM-produced function call would stream. */
+function directStream(req, call) {
+    const { item, response } = build(req, call);
+    const pending = { ...response, status: "in_progress", output: [], usage: null };
+    const at = { item_id: item.id, output_index: 0 };
+    const events = [
+        { type: "response.created", response: pending },
+        { type: "response.in_progress", response: pending },
+        { type: "response.output_item.added", output_index: 0, item: { ...item, arguments: "", status: "in_progress" } },
+        { type: "response.function_call_arguments.delta", ...at, delta: item.arguments },
+        { type: "response.function_call_arguments.done", ...at, arguments: item.arguments },
+        { type: "response.output_item.done", output_index: 0, item },
+        { type: "response.completed", response },
+    ];
+    return sse(events.map((event, sequence_number) => ({
+        event: event.type,
+        data: JSON.stringify({ ...event, sequence_number }),
+    })));
+}
+export const responsesAdapter = { toInput, apply, directJson, directStream };

package/dist/app.js

@@ -0,0 +1,176 @@
+import { timingSafeEqual } from "node:crypto";
+import { brotliDecompressSync, gunzipSync, inflateSync, zstdDecompressSync } from "node:zlib";
+import { Hono } from "hono";
+import { chatAdapter } from "./adapters/chat.js";
+import { messagesAdapter } from "./adapters/messages.js";
+import { responsesAdapter } from "./adapters/responses.js";
+import { redactHeaders, summarizeResponse } from "./debug.js";
+import { decide } from "./decide.js";
+import { forward } from "./upstream.js";
+const safeEqual = (a, b) => {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+};
+const DECODERS = {
+    zstd: zstdDecompressSync,
+    gzip: gunzipSync,
+    br: brotliDecompressSync,
+    deflate: inflateSync,
+};
+/** Parse a JSON body, undoing request compression (Codex sends zstd). Undefined if unreadable. */
+function parseBody(bytes, encoding) {
+    try {
+        const decoder = encoding ? DECODERS[encoding.trim().toLowerCase()] : undefined;
+        if (encoding && !decoder)
+            return undefined;
+        const parsed = JSON.parse(Buffer.from(decoder ? decoder(bytes) : bytes).toString("utf8"));
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function decisionHeaders(decision) {
+    const headers = { "x-jev-gateway-mode": decision.mode };
+    if (decision.mode === "passthrough")
+        headers["x-jev-gateway-reason"] = decision.reason.slice(0, 120);
+    if (decision.mode === "forced" || decision.mode === "direct" || decision.mode === "hint") {
+        headers["x-jev-gateway-tool"] = decision.tool;
+    }
+    if (decision.jev) {
+        headers["x-jev-gateway-confidence"] = decision.jev.confidence.toFixed(3);
+        headers["x-jev-gateway-latency-ms"] = String(decision.jev.latencyMs);
+    }
+    return headers;
+}
+export function createApp({ config, askJev, fetch: fetchImpl = fetch, log = () => { }, dump }) {
+    const app = new Hono();
+    /**
+     * Error bodies are the only documentation an undocumented backend offers, and a finished
+     * stream's usage is the only way to see what a rewrite did to the prompt cache: keep both.
+     * Reads a clone in the background, so the client's stream is never delayed.
+     */
+    const dumpResponse = (kind, response, extra = {}) => {
+        if (!dump)
+            return;
+        const failed = response.status >= 400;
+        const copy = response.clone();
+        void (async () => {
+            let text = "";
+            try {
+                // Codex hangs up the moment it has `response.completed`, which aborts the upstream read
+                // mid-stream: whatever arrived until then is the response.
+                for await (const chunk of copy.body?.pipeThrough(new TextDecoderStream()) ?? [])
+                    text += chunk;
+            }
+            catch { }
+            dump(failed ? kind : "response", {
+                status: response.status,
+                ...extra,
+                ...(failed ? { body: text.slice(0, 20_000) } : summarizeResponse(text)),
+            });
+        })();
+    };
+    /** The decision, plus how many tools the adapter found — they aren't always in `req.tools`. */
+    const decideFor = async (adapter, req) => {
+        const input = adapter.toInput(req, config.maxMessageChars);
+        if ("skip" in input)
+            return { decision: { mode: "passthrough", reason: input.skip }, tools: undefined };
+        return { decision: await decide(input, config, askJev), tools: input.tools.length };
+    };
+    const route = (adapter) => async (c) => {
+        const bytes = new Uint8Array(await c.req.arrayBuffer());
+        // Unreadable bodies are not ours to judge: upstream produces its own error for them.
+        const req = parseBody(bytes, c.req.header("content-encoding"));
+        dump?.("request", {
+            method: c.req.method,
+            path: c.req.path,
+            headers: redactHeaders(c.req.raw.headers),
+            body: req ?? `[unparseable, ${bytes.length} bytes]`,
+        });
+        let decision;
+        let tools;
+        if (!req)
+            decision = { mode: "passthrough", reason: "unparseable_body" };
+        else if (c.req.header("x-jev-gateway") === "off")
+            decision = { mode: "passthrough", reason: "disabled_by_header" };
+        else
+            ({ decision, tools } = await decideFor(adapter, req));
+        const entry = { event: "route", path: c.req.path, model: req?.model, tools: tools ?? req?.tools?.length ?? 0 };
+        if (req && decision.mode === "direct") {
+            log({ ...entry, ...decision });
+            const call = { tool: decision.tool, args: decision.args, inputTokens: decision.jev?.inputTokens ?? 0 };
+            const headers = decisionHeaders(decision);
+            return req.stream
+                ? c.body(adapter.directStream(req, call), 200, {
+                    ...headers,
+                    "content-type": "text/event-stream",
+                    "cache-control": "no-cache",
+                })
+                : c.json(adapter.directJson(req, call), 200, headers);
+        }
+        if (req && decision.mode !== "passthrough") {
+            const rewritten = adapter.apply(req, decision, config.argsModel);
+            const body = JSON.stringify(rewritten);
+            const response = await forward(c.req.raw, config, fetchImpl, { body, responseHeaders: decisionHeaders(decision) });
+            const sent = { mode: decision.mode, model: rewritten.model, tool_choice: rewritten.tool_choice };
+            dumpResponse("rejected", response, { sent });
+            if (response.status !== 400 && response.status !== 422) {
+                log({ ...entry, ...decision, status: response.status });
+                return response;
+            }
+            // The upstream refused the rewritten request (some backends only accept tool_choice
+            // "auto"): the router must never be the reason a request fails, so replay the original.
+            await response.body?.cancel();
+            decision = { mode: "passthrough", reason: `upstream_rejected_${decision.mode}`, jev: decision.jev };
+        }
+        const response = await forward(c.req.raw, config, fetchImpl, {
+            body: bytes,
+            responseHeaders: decisionHeaders(decision),
+        });
+        log({ ...entry, ...decision, status: response.status });
+        dumpResponse("upstream-error", response);
+        return response;
+    };
+    app.get("/health", (c) => c.json({ status: "ok", upstream: config.upstreamBaseUrl }));
+    app.use("*", async (c, next) => {
+        if (!config.routerApiKey)
+            return next();
+        const presented = c.req.header("authorization")?.replace(/^Bearer\s+/i, "") ?? "";
+        if (safeEqual(presented, config.routerApiKey))
+            return next();
+        return c.json({ error: { message: "Invalid jev-gateway API key", type: "invalid_api_key" } }, 401);
+    });
+    /**
+     * Dry run: what would the router do with this body? Calls Jev, never upstream.
+     * Accepts any routed wire format; `?format=chat|responses|messages` overrides the guess.
+     */
+    app.post("/router/decide", async (c) => {
+        const req = parseBody(new Uint8Array(await c.req.arrayBuffer()), undefined);
+        if (!req)
+            return c.json({ error: { message: "Body must be a JSON object", type: "invalid_request_error" } }, 400);
+        const adapters = { chat: chatAdapter, responses: responsesAdapter, messages: messagesAdapter };
+        // Chat Completions and Anthropic Messages both use `messages`; only Anthropic has a top-level
+        // `system` or tools described by `input_schema`.
+        const tools = Array.isArray(req.tools) ? req.tools : [];
+        const guess = !("messages" in req)
+            ? "responses"
+            : "system" in req || tools.some((tool) => "input_schema" in tool)
+                ? "messages"
+                : "chat";
+        const format = (c.req.query("format") ?? guess);
+        const adapter = (adapters[format] ?? adapters[guess]);
+        return c.json((await decideFor(adapter, req)).decision);
+    });
+    app.post("/v1/chat/completions", route(chatAdapter));
+    app.post("/v1/responses", route(responsesAdapter));
+    app.post("/v1/messages", route(messagesAdapter));
+    // Everything else (models, embeddings, …) is proxied untouched.
+    app.all("/v1/*", async (c) => {
+        const response = await forward(c.req.raw, config, fetchImpl);
+        dump?.("other", { method: c.req.method, path: c.req.path, headers: redactHeaders(c.req.raw.headers), status: response.status });
+        return response;
+    });
+    return app;
+}

package/dist/config.js

@@ -0,0 +1,45 @@
+const str = (env, key) => {
+    const value = env[key]?.trim();
+    return value ? value : undefined;
+};
+const num = (env, key, fallback) => {
+    const raw = str(env, key);
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        throw new Error(`${key} must be a number, got "${raw}"`);
+    return value;
+};
+const bool = (env, key, fallback) => {
+    const raw = str(env, key)?.toLowerCase();
+    if (raw === undefined)
+        return fallback;
+    return raw === "1" || raw === "true" || raw === "yes";
+};
+export function loadConfig(env = process.env) {
+    const onNone = str(env, "JEV_ON_NONE") ?? "force_none";
+    if (onNone !== "force_none" && onNone !== "passthrough") {
+        throw new Error(`JEV_ON_NONE must be "force_none" or "passthrough", got "${onNone}"`);
+    }
+    const config = {
+        port: num(env, "PORT", 8787),
+        upstreamBaseUrl: (str(env, "UPSTREAM_BASE_URL") ?? "https://api.openai.com/v1").replace(/\/+$/, ""),
+        upstreamApiKey: str(env, "UPSTREAM_API_KEY"),
+        routerApiKey: str(env, "ROUTER_API_KEY"),
+        argsModel: str(env, "ARGS_MODEL"),
+        jevModel: str(env, "JEV_MODEL") ?? "jev-latest",
+        jevTimeoutMs: num(env, "JEV_TIMEOUT_MS", 4000),
+        minConfidence: num(env, "JEV_MIN_CONFIDENCE", 0.7),
+        argMinCertainty: num(env, "JEV_ARG_MIN_CERTAINTY", 0.8),
+        onNone,
+        directCalls: bool(env, "JEV_DIRECT_CALLS", true),
+        maxStateChars: num(env, "JEV_MAX_STATE_CHARS", 60_000),
+        maxMessageChars: num(env, "JEV_MAX_MESSAGE_CHARS", 4_000),
+        debugDumpDir: str(env, "JEV_DEBUG_DUMP_DIR"),
+    };
+    if (config.routerApiKey && !config.upstreamApiKey) {
+        throw new Error("ROUTER_API_KEY requires UPSTREAM_API_KEY (the client key is not valid upstream)");
+    }
+    return config;
+}

package/dist/debug.js

@@ -0,0 +1,84 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Opt-in wire dumps (`JEV_DEBUG_DUMP_DIR`): what a client *really* sends is the only reliable
+ * spec for backends like ChatGPT's, which are undocumented. Dumps hold the whole conversation,
+ * so they are never on by default and credentials never reach the disk.
+ */
+// Anything that authenticates or identifies the account. Matched loosely on purpose: a header
+// redacted by mistake costs nothing, one leaked by mistake is a credential on disk.
+const SECRET_HEADER = /auth|cookie|token|secret|key|account|session|signature/i;
+export function redactHeaders(headers) {
+    const out = {};
+    headers.forEach((value, name) => {
+        out[name] = SECRET_HEADER.test(name) ? `[redacted, ${value.length} chars]` : value;
+    });
+    return out;
+}
+// A stream can end without completing; clients (Codex: "Reconnecting…") treat that as a failure.
+const TERMINAL = new Set(["response.completed", "response.incomplete", "response.failed"]);
+/** What a Responses reply (SSE or JSON) says about itself: enough to see cache hits and tool calls. */
+export function summarizeResponse(text) {
+    let done;
+    let ending;
+    // "responses-lite" streams leave `response.output` empty; the items only appear as events.
+    const streamed = [];
+    const parse = (json) => {
+        try {
+            const event = JSON.parse(json);
+            if (event.type === "response.output_item.done" && event.item)
+                streamed.push(event.item);
+            else if (event.type && TERMINAL.has(event.type))
+                [ending, done] = [event.type, event.response];
+            else if (!event.type)
+                done = event;
+        }
+        catch {
+            // A chunk cut short by the client hanging up.
+        }
+    };
+    if (text.trimStart().startsWith("{"))
+        parse(text);
+    else
+        for (const line of text.split("\n"))
+            if (line.startsWith("data:"))
+                parse(line.slice(5));
+    if (!done)
+        return { unparsed: text.slice(-2_000) };
+    const { attribution: _perItem, ...usage } = (done.usage ?? {});
+    const output = streamed.length ? streamed : Array.isArray(done.output) ? done.output : [];
+    return {
+        ...(ending && ending !== "response.completed"
+            ? { ending, incomplete_details: done.incomplete_details, error: done.error }
+            : {}),
+        model: done.model,
+        tool_choice: done.tool_choice,
+        usage,
+        // Runs of one item type collapse to a count: a derailed reply can hold a hundred of them.
+        output: output.reduce((runs, { type, name, namespace }) => {
+            const last = runs.at(-1);
+            if (last && last.type === type && last.name === name)
+                last.count = (last.count ?? 1) + 1;
+            else
+                runs.push({ type, name, namespace });
+            return runs;
+        }, []),
+    };
+}
+/** Writes `<dir>/<start>-<seq>-<kind>.json`, never throwing; undefined (off) without a directory. */
+export function createDump(dir) {
+    if (!dir)
+        return undefined;
+    const startedAt = Date.now();
+    let sequence = 0;
+    return (kind, data) => {
+        try {
+            mkdirSync(dir, { recursive: true });
+            const name = `${startedAt}-${String(++sequence).padStart(4, "0")}-${kind}.json`;
+            writeFileSync(join(dir, name), JSON.stringify(data, null, 2), { mode: 0o600 });
+        }
+        catch {
+            // Debugging aid only: a full disk must not break routing.
+        }
+    };
+}