@foldrun/core 0.2.0

package/dist/src/translator.js

@@ -0,0 +1,986 @@
+// The runtime's own translator: Anthropic Messages in, Chat Completions or
+// Responses out.
+//
+// The Agent SDK speaks one wire format. Most of the providers people bring
+// keys for speak another — OpenAI's Chat Completions, which OpenAI, Gemini,
+// xAI, Groq, Mistral, Hugging Face, Cloudflare and every local runtime all
+// implement. Rather than teach the runtime a second format, or install a
+// gateway beside it, this listens on localhost inside the run sandbox,
+// presents an Anthropic endpoint to the SDK, and rewrites each request and
+// each streamed reply between the two shapes. It exists only for the
+// duration of a step, holds only that step's key, and dies with it.
+//
+// `format: responses` is the third shape: OpenAI's newer Responses API,
+// which OpenAI recommends for new work and almost nobody else implements.
+// Same translator, same server, a second pair of mappings — chosen per
+// provider block, never guessed. It carries one thing Chat Completions
+// cannot: a document block crosses as an input_file, so a PDF an agent
+// reads reaches the model instead of being dropped.
+//
+// It is deliberately small. It translates what the SDK actually sends — a
+// system prompt, text and image blocks, tools with JSON schemas, tool calls
+// and their results, streaming — and drops what a Chat-Completions endpoint
+// has no word for (cache_control, top_k, server-side tools, thinking on
+// endpoints that lack reasoning_effort). Anything dropped is said once in
+// the run trace. The translation is pure functions over JSON so the tests
+// can drive every mapping without a network; the server around them is a
+// few dozen lines.
+import http from "node:http";
+import crypto from "node:crypto";
+import { PROTECTED_PARAMS } from "./providers.js";
+import { viaEgress } from "./egress.js";
+function dropped() {
+    const seen = new Set();
+    return {
+        add: (w) => void seen.add(w),
+        lines: () => [...seen].map((w) => `translator: dropped ${w} — the endpoint has no equivalent`),
+    };
+}
+// ------------------------------------------------------- request mapping
+/**
+ * The SDK's `metadata.user_id` is a long composite string; OpenAI's own
+ * endpoint caps `safety_identifier` (Responses) at 64 characters and
+ * rejects the request outright — a gateway in front of it did not, which is
+ * how this shipped untested. A stable digest keeps the identity property
+ * (same user, same id) inside the limit. Applied to Chat Completions' `user`
+ * too, for the same reason.
+ */
+function stableId(id) {
+    return id.length <= 64 ? id : crypto.createHash("sha256").update(id).digest("hex").slice(0, 64);
+}
+/**
+ * Whether a model is one OpenAI's own endpoint refuses a reasoning-effort
+ * parameter for ("Unsupported parameter: 'reasoning.effort'" on gpt-4o-mini).
+ * A gateway in front of it ignored the field, which is how the preset's
+ * reasoningEffort shipped untested against the origin. The families that do
+ * not reason are the ones named — anything else (o-series, gpt-5, grok,
+ * gemini, deepseek-r, qwen thinking) keeps getting the knob, because on a
+ * gateway the id alone cannot say and an ignored field costs nothing.
+ */
+export function modelRejectsReasoning(model) {
+    const id = String(model).split("/").pop()?.toLowerCase() ?? "";
+    return /^(gpt-3|gpt-4|chatgpt|gpt-5-chat|davinci|babbage)/.test(id);
+}
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((b) => b && typeof b === "object" && b.type === "text")
+        .map((b) => String(b.text ?? ""))
+        .join("\n");
+}
+function imagePart(block) {
+    const src = block.source;
+    if (!src)
+        return null;
+    if (src.type === "base64" && typeof src.data === "string") {
+        return { type: "image_url", image_url: { url: `data:${String(src.media_type ?? "image/png")};base64,${src.data}` } };
+    }
+    if (src.type === "url" && typeof src.url === "string")
+        return { type: "image_url", image_url: { url: src.url } };
+    return null;
+}
+/**
+ * An Anthropic Messages request as a Chat Completions request. Pure.
+ *
+ * Message order matters to the other side: a tool result must directly
+ * follow the assistant turn that called the tool. Anthropic puts results
+ * inside the next user message, so those blocks become `tool` messages
+ * first and whatever else the user said follows as a user message.
+ */
+export function toChatCompletions(req, opts, drop = dropped()) {
+    const out = { model: req.model, stream: opts.stream };
+    const messages = [];
+    const system = textOf(req.system);
+    if (system)
+        messages.push({ role: "system", content: system });
+    for (const m of (Array.isArray(req.messages) ? req.messages : [])) {
+        const content = m.content;
+        if (m.role === "assistant") {
+            const text = textOf(content);
+            const toolCalls = [];
+            for (const b of Array.isArray(content) ? content : []) {
+                if (b.type === "tool_use") {
+                    toolCalls.push({
+                        id: String(b.id),
+                        type: "function",
+                        function: { name: String(b.name), arguments: JSON.stringify(b.input ?? {}) },
+                    });
+                }
+                else if (b.type === "thinking" || b.type === "redacted_thinking") {
+                    drop.add("thinking blocks in the transcript");
+                }
+            }
+            const msg = { role: "assistant" };
+            if (text)
+                msg.content = text;
+            else if (!toolCalls.length)
+                msg.content = "";
+            if (toolCalls.length)
+                msg.tool_calls = toolCalls;
+            messages.push(msg);
+            continue;
+        }
+        // user
+        if (typeof content === "string") {
+            messages.push({ role: "user", content });
+            continue;
+        }
+        const parts = [];
+        for (const b of Array.isArray(content) ? content : []) {
+            if (b.type === "tool_result") {
+                const inner = b.content;
+                const text = typeof inner === "string" ? inner : textOf(inner);
+                messages.push({
+                    role: "tool",
+                    tool_call_id: String(b.tool_use_id),
+                    content: text || (b.is_error ? "error" : "ok"),
+                });
+                if (Array.isArray(inner) && inner.some((x) => x.type === "image"))
+                    drop.add("images inside tool results");
+            }
+            else if (b.type === "text") {
+                parts.push({ type: "text", text: String(b.text ?? "") });
+            }
+            else if (b.type === "image") {
+                const p = imagePart(b);
+                if (p)
+                    parts.push(p);
+            }
+            else if (b.type === "document") {
+                drop.add("document blocks");
+            }
+        }
+        if (parts.length) {
+            // A single text part reads as a plain string on every endpoint;
+            // a list is only needed when an image is among them.
+            messages.push({
+                role: "user",
+                content: parts.length === 1 && parts[0].type === "text" ? parts[0].text : parts,
+            });
+        }
+    }
+    out.messages = messages;
+    const tools = [];
+    for (const t of (Array.isArray(req.tools) ? req.tools : [])) {
+        if (t.type && t.type !== "custom") {
+            drop.add(`server-side tool ${String(t.type)}`);
+            continue;
+        }
+        tools.push({
+            type: "function",
+            function: {
+                name: String(t.name),
+                ...(t.description ? { description: String(t.description) } : {}),
+                parameters: t.input_schema ?? { type: "object", properties: {} },
+            },
+        });
+    }
+    if (tools.length)
+        out.tools = tools;
+    const tc = req.tool_choice;
+    if (tc && tools.length) {
+        if (tc.type === "auto")
+            out.tool_choice = "auto";
+        else if (tc.type === "any")
+            out.tool_choice = "required";
+        else if (tc.type === "none")
+            out.tool_choice = "none";
+        else if (tc.type === "tool" && tc.name)
+            out.tool_choice = { type: "function", function: { name: String(tc.name) } };
+        if (tc.disable_parallel_tool_use === true)
+            out.parallel_tool_calls = false;
+    }
+    if (typeof req.max_tokens === "number")
+        out[opts.maxTokensParam ?? "max_tokens"] = req.max_tokens;
+    if (typeof req.temperature === "number")
+        out.temperature = req.temperature;
+    if (typeof req.top_p === "number")
+        out.top_p = req.top_p;
+    if (req.top_k !== undefined)
+        drop.add("top_k");
+    if (Array.isArray(req.stop_sequences) && req.stop_sequences.length)
+        out.stop = req.stop_sequences;
+    const meta = req.metadata;
+    if (meta && typeof meta.user_id === "string")
+        out.user = stableId(meta.user_id);
+    if (opts.stream)
+        out.stream_options = { include_usage: true };
+    // Thinking: budget → effort where the endpoint has the word, dropped
+    // where it does not. `effort` spelled directly is honoured the same way.
+    const thinking = req.thinking;
+    const effortWord = typeof req.effort === "string" ? req.effort : req.output_config?.effort;
+    let effort = null;
+    if (typeof effortWord === "string")
+        effort = { low: "low", medium: "medium", high: "high", xhigh: "high", max: "high" }[effortWord] ?? null;
+    else if (thinking && thinking.type === "enabled") {
+        const b = Number(thinking.budget_tokens) || 0;
+        effort = b <= 2048 ? "low" : b <= 8192 ? "medium" : "high";
+    }
+    else if (thinking && thinking.type === "adaptive")
+        effort = "medium";
+    if (effort) {
+        if (opts.reasoningEffort && !modelRejectsReasoning(String(req.model)))
+            out.reasoning_effort = effort;
+        else
+            drop.add(opts.reasoningEffort ? "thinking / effort (this model does not reason)" : "thinking / effort");
+    }
+    // The author's own fields, last, so the file wins over anything decided
+    // above — including a `reasoning_effort` they would rather set by hand.
+    // `null` removes a field the translation would otherwise have sent, which
+    // is the only way to say "do not send temperature at all" to an endpoint
+    // that rejects it. Structural keys were dropped at parse time.
+    for (const [key, value] of Object.entries(opts.params ?? {})) {
+        if (PROTECTED_PARAMS.includes(key))
+            continue;
+        if (value === null)
+            delete out[key];
+        else
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * An Anthropic Messages request as a Responses request. Pure.
+ *
+ * The Responses shape is flatter than Chat Completions: the system prompt
+ * is `instructions`, a tool call and its result are top-level items rather
+ * than an assistant field and a `tool` role, and a document is an input
+ * file the model reads itself. Order is preserved as written: a
+ * function_call item, then its function_call_output, then whatever else the
+ * user said.
+ */
+export function toResponses(req, opts, drop = dropped()) {
+    const out = { model: req.model, stream: opts.stream, store: false };
+    const system = textOf(req.system);
+    if (system)
+        out.instructions = system;
+    const input = [];
+    for (const m of (Array.isArray(req.messages) ? req.messages : [])) {
+        const content = m.content;
+        if (m.role === "assistant") {
+            const text = textOf(content);
+            if (text)
+                input.push({ role: "assistant", content: [{ type: "output_text", text }] });
+            for (const b of Array.isArray(content) ? content : []) {
+                if (b.type === "tool_use") {
+                    input.push({ type: "function_call", call_id: String(b.id), name: String(b.name), arguments: JSON.stringify(b.input ?? {}) });
+                }
+                else if (b.type === "thinking" || b.type === "redacted_thinking") {
+                    drop.add("thinking blocks in the transcript");
+                }
+            }
+            continue;
+        }
+        if (typeof content === "string") {
+            input.push({ role: "user", content });
+            continue;
+        }
+        const parts = [];
+        for (const b of Array.isArray(content) ? content : []) {
+            if (b.type === "tool_result") {
+                const inner = b.content;
+                const text = typeof inner === "string" ? inner : textOf(inner);
+                input.push({ type: "function_call_output", call_id: String(b.tool_use_id), output: text || (b.is_error ? "error" : "ok") });
+                if (Array.isArray(inner) && inner.some((x) => x.type === "image"))
+                    drop.add("images inside tool results");
+            }
+            else if (b.type === "text") {
+                parts.push({ type: "input_text", text: String(b.text ?? "") });
+            }
+            else if (b.type === "image") {
+                const src = b.source;
+                if (src?.type === "base64" && typeof src.data === "string") {
+                    parts.push({ type: "input_image", image_url: `data:${String(src.media_type ?? "image/png")};base64,${src.data}`, detail: "auto" });
+                }
+                else if (src?.type === "url" && typeof src.url === "string") {
+                    parts.push({ type: "input_image", image_url: src.url, detail: "auto" });
+                }
+            }
+            else if (b.type === "document") {
+                // The one thing this shape can say that Chat Completions cannot.
+                const src = b.source;
+                const title = typeof b.title === "string" ? b.title : "document.pdf";
+                if (src?.type === "base64" && typeof src.data === "string") {
+                    parts.push({ type: "input_file", filename: title, file_data: `data:${String(src.media_type ?? "application/pdf")};base64,${src.data}` });
+                }
+                else if (src?.type === "url" && typeof src.url === "string") {
+                    parts.push({ type: "input_file", file_url: src.url });
+                }
+                else if (src?.type === "text" && typeof src.data === "string") {
+                    parts.push({ type: "input_text", text: src.data });
+                }
+                else {
+                    drop.add("document blocks of that source type");
+                }
+            }
+        }
+        if (parts.length)
+            input.push({ role: "user", content: parts });
+    }
+    out.input = input;
+    const tools = [];
+    for (const t of (Array.isArray(req.tools) ? req.tools : [])) {
+        if (t.type && t.type !== "custom") {
+            drop.add(`server-side tool ${String(t.type)}`);
+            continue;
+        }
+        tools.push({
+            type: "function",
+            name: String(t.name),
+            ...(t.description ? { description: String(t.description) } : {}),
+            parameters: t.input_schema ?? { type: "object", properties: {} },
+            strict: false,
+        });
+    }
+    if (tools.length)
+        out.tools = tools;
+    const tc = req.tool_choice;
+    if (tc && tools.length) {
+        if (tc.type === "auto")
+            out.tool_choice = "auto";
+        else if (tc.type === "any")
+            out.tool_choice = "required";
+        else if (tc.type === "none")
+            out.tool_choice = "none";
+        else if (tc.type === "tool" && tc.name)
+            out.tool_choice = { type: "function", name: String(tc.name) };
+        if (tc.disable_parallel_tool_use === true)
+            out.parallel_tool_calls = false;
+    }
+    if (typeof req.max_tokens === "number")
+        out.max_output_tokens = req.max_tokens;
+    if (typeof req.temperature === "number")
+        out.temperature = req.temperature;
+    if (typeof req.top_p === "number")
+        out.top_p = req.top_p;
+    if (req.top_k !== undefined)
+        drop.add("top_k");
+    if (Array.isArray(req.stop_sequences) && req.stop_sequences.length)
+        drop.add("stop_sequences");
+    const meta = req.metadata;
+    if (meta && typeof meta.user_id === "string")
+        out.safety_identifier = stableId(meta.user_id);
+    const thinking = req.thinking;
+    const effortWord = typeof req.effort === "string" ? req.effort : req.output_config?.effort;
+    let effort = null;
+    if (typeof effortWord === "string")
+        effort = { low: "low", medium: "medium", high: "high", xhigh: "high", max: "high" }[effortWord] ?? null;
+    else if (thinking && thinking.type === "enabled") {
+        const b = Number(thinking.budget_tokens) || 0;
+        effort = b <= 2048 ? "low" : b <= 8192 ? "medium" : "high";
+    }
+    else if (thinking && thinking.type === "adaptive")
+        effort = "medium";
+    if (effort) {
+        if (opts.reasoningEffort !== false && !modelRejectsReasoning(String(req.model)))
+            out.reasoning = { effort };
+        else
+            drop.add(opts.reasoningEffort !== false ? "thinking / effort (this model does not reason)" : "thinking / effort");
+    }
+    for (const [key, value] of Object.entries(opts.params ?? {})) {
+        if (PROTECTED_PARAMS.includes(key))
+            continue;
+        if (value === null)
+            delete out[key];
+        else
+            out[key] = value;
+    }
+    return out;
+}
+// ------------------------------------------------------- response mapping
+function stopReason(finish) {
+    switch (finish) {
+        case "tool_calls":
+        case "function_call":
+            return "tool_use";
+        case "length":
+            return "max_tokens";
+        default:
+            return "end_turn";
+    }
+}
+function parseArgs(raw) {
+    if (typeof raw !== "string" || !raw.trim())
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return { _unparsed: raw };
+    }
+}
+/** A finished Chat Completion as an Anthropic message. Pure. */
+export function fromChatCompletion(res, requestedModel) {
+    const choice = (res.choices ?? [])[0] ?? {};
+    const msg = choice.message ?? {};
+    const content = [];
+    const text = typeof msg.content === "string" ? msg.content : textOf(msg.content);
+    if (text)
+        content.push({ type: "text", text });
+    for (const tc of (Array.isArray(msg.tool_calls) ? msg.tool_calls : [])) {
+        const fn = tc.function ?? {};
+        content.push({
+            type: "tool_use",
+            id: String(tc.id ?? `call_${crypto.randomBytes(6).toString("hex")}`),
+            name: String(fn.name ?? ""),
+            input: parseArgs(fn.arguments),
+        });
+    }
+    const usage = res.usage ?? {};
+    return {
+        id: String(res.id ?? `msg_${crypto.randomBytes(8).toString("hex")}`),
+        type: "message",
+        role: "assistant",
+        model: String(res.model ?? requestedModel),
+        content,
+        stop_reason: stopReason(choice.finish_reason),
+        stop_sequence: null,
+        usage: {
+            input_tokens: Number(usage.prompt_tokens ?? 0),
+            output_tokens: Number(usage.completion_tokens ?? 0),
+        },
+    };
+}
+/**
+ * The streaming half: Chat-Completions chunks in, Anthropic SSE events out.
+ * A state machine because the two streams disagree about structure — one
+ * is a flat sequence of deltas, the other is blocks with explicit starts and
+ * stops — and a tool call's arguments arrive as fragments that the other
+ * side wants as `input_json_delta`s inside one open block.
+ */
+export class StreamTranslator {
+    started = false;
+    nextIndex = 0;
+    textIndex = null;
+    /** Chat-Completions tool index → Anthropic block index. */
+    tools = new Map();
+    finish = null;
+    usage = null;
+    id = `msg_${crypto.randomBytes(8).toString("hex")}`;
+    model;
+    constructor(model) {
+        this.model = model;
+    }
+    event(name, data) {
+        return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
+    }
+    start(chunk) {
+        if (this.started)
+            return [];
+        this.started = true;
+        if (typeof chunk.id === "string")
+            this.id = chunk.id;
+        return [
+            this.event("message_start", {
+                type: "message_start",
+                message: {
+                    id: this.id,
+                    type: "message",
+                    role: "assistant",
+                    model: String(chunk.model ?? this.model),
+                    content: [],
+                    stop_reason: null,
+                    stop_sequence: null,
+                    usage: { input_tokens: 0, output_tokens: 0 },
+                },
+            }),
+        ];
+    }
+    closeText() {
+        if (this.textIndex === null)
+            return [];
+        const i = this.textIndex;
+        this.textIndex = null;
+        return [this.event("content_block_stop", { type: "content_block_stop", index: i })];
+    }
+    /** One parsed chunk in, zero or more SSE events out. */
+    feed(chunk) {
+        const out = this.start(chunk);
+        const u = chunk.usage;
+        if (u && (u.prompt_tokens !== undefined || u.completion_tokens !== undefined)) {
+            this.usage = { input: Number(u.prompt_tokens ?? 0), output: Number(u.completion_tokens ?? 0) };
+        }
+        const choice = (chunk.choices ?? [])[0];
+        if (!choice)
+            return out;
+        if (choice.finish_reason)
+            this.finish = choice.finish_reason;
+        const delta = choice.delta ?? {};
+        const text = typeof delta.content === "string" ? delta.content : "";
+        if (text) {
+            if (this.textIndex === null) {
+                this.textIndex = this.nextIndex++;
+                out.push(this.event("content_block_start", {
+                    type: "content_block_start",
+                    index: this.textIndex,
+                    content_block: { type: "text", text: "" },
+                }));
+            }
+            out.push(this.event("content_block_delta", {
+                type: "content_block_delta",
+                index: this.textIndex,
+                delta: { type: "text_delta", text },
+            }));
+        }
+        for (const [n, tc] of (Array.isArray(delta.tool_calls) ? delta.tool_calls : []).entries()) {
+            const idx = typeof tc.index === "number" ? tc.index : this.tools.size + n;
+            const fn = tc.function ?? {};
+            let entry = this.tools.get(idx);
+            if (!entry) {
+                // A new call: text stops here (a block is one thing), the tool
+                // block opens with the id and name the first fragment carries.
+                out.push(...this.closeText());
+                entry = { block: this.nextIndex++, argsSeen: false };
+                this.tools.set(idx, entry);
+                out.push(this.event("content_block_start", {
+                    type: "content_block_start",
+                    index: entry.block,
+                    content_block: {
+                        type: "tool_use",
+                        id: String(tc.id ?? `call_${crypto.randomBytes(6).toString("hex")}`),
+                        name: String(fn.name ?? ""),
+                        input: {},
+                    },
+                }));
+            }
+            const args = typeof fn.arguments === "string" ? fn.arguments : "";
+            if (args) {
+                entry.argsSeen = true;
+                out.push(this.event("content_block_delta", {
+                    type: "content_block_delta",
+                    index: entry.block,
+                    delta: { type: "input_json_delta", partial_json: args },
+                }));
+            }
+        }
+        return out;
+    }
+    /** The stream ended: close what is open, say why, and stop. */
+    finishStream() {
+        const out = this.start({});
+        out.push(...this.closeText());
+        for (const entry of this.tools.values()) {
+            // Anthropic expects the concatenated partial_json to parse; a call
+            // that streamed no arguments at all needs an explicit empty object.
+            if (!entry.argsSeen) {
+                out.push(this.event("content_block_delta", {
+                    type: "content_block_delta",
+                    index: entry.block,
+                    delta: { type: "input_json_delta", partial_json: "{}" },
+                }));
+            }
+            out.push(this.event("content_block_stop", { type: "content_block_stop", index: entry.block }));
+        }
+        const reason = this.tools.size && this.finish !== "length" ? "tool_use" : stopReason(this.finish);
+        out.push(this.event("message_delta", {
+            type: "message_delta",
+            delta: { stop_reason: reason, stop_sequence: null },
+            usage: { input_tokens: this.usage?.input ?? 0, output_tokens: this.usage?.output ?? 0 },
+        }));
+        out.push(this.event("message_stop", { type: "message_stop" }));
+        return out;
+    }
+}
+/** A finished Response as an Anthropic message. Pure. */
+export function fromResponses(res, requestedModel) {
+    const content = [];
+    for (const item of (Array.isArray(res.output) ? res.output : [])) {
+        if (item.type === "message") {
+            const text = (Array.isArray(item.content) ? item.content : [])
+                .map((c) => (c.type === "output_text" ? String(c.text ?? "") : c.type === "refusal" ? String(c.refusal ?? "") : ""))
+                .join("");
+            if (text)
+                content.push({ type: "text", text });
+        }
+        else if (item.type === "function_call") {
+            content.push({
+                type: "tool_use",
+                id: String(item.call_id ?? item.id ?? `call_${crypto.randomBytes(6).toString("hex")}`),
+                name: String(item.name ?? ""),
+                input: parseArgs(item.arguments),
+            });
+        }
+        // reasoning items and server-tool calls have no Anthropic block here
+    }
+    const usage = res.usage ?? {};
+    const incomplete = res.incomplete_details?.reason;
+    const stop = content.some((c) => c.type === "tool_use") ? "tool_use" : incomplete === "max_output_tokens" ? "max_tokens" : "end_turn";
+    return {
+        id: String(res.id ?? `msg_${crypto.randomBytes(8).toString("hex")}`),
+        type: "message",
+        role: "assistant",
+        model: String(res.model ?? requestedModel),
+        content,
+        stop_reason: stop,
+        stop_sequence: null,
+        usage: {
+            input_tokens: Number(usage.input_tokens ?? 0),
+            output_tokens: Number(usage.output_tokens ?? 0),
+        },
+    };
+}
+/**
+ * The Responses stream as Anthropic SSE. Simpler than the Chat-Completions
+ * machine because the other side already speaks in items: an output item
+ * is added, its text or arguments arrive as deltas, it is done. Each item
+ * becomes one Anthropic block; `response.completed` carries the usage and
+ * the reason.
+ */
+export class ResponsesStreamTranslator {
+    started = false;
+    nextIndex = 0;
+    /** Responses output_index → Anthropic block index and kind. */
+    blocks = new Map();
+    usage = null;
+    incomplete = null;
+    sawTool = false;
+    id = `msg_${crypto.randomBytes(8).toString("hex")}`;
+    model;
+    constructor(model) {
+        this.model = model;
+    }
+    event(name, data) {
+        return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
+    }
+    start(response) {
+        if (this.started)
+            return [];
+        this.started = true;
+        if (response && typeof response.id === "string")
+            this.id = response.id;
+        return [
+            this.event("message_start", {
+                type: "message_start",
+                message: {
+                    id: this.id,
+                    type: "message",
+                    role: "assistant",
+                    model: String(response?.model ?? this.model),
+                    content: [],
+                    stop_reason: null,
+                    stop_sequence: null,
+                    usage: { input_tokens: 0, output_tokens: 0 },
+                },
+            }),
+        ];
+    }
+    /** One parsed event in, zero or more SSE events out. */
+    feed(ev) {
+        const type = String(ev.type ?? "");
+        const out = this.start(ev.response);
+        if (type === "response.output_item.added") {
+            const item = ev.item ?? {};
+            const idx = Number(ev.output_index ?? this.blocks.size);
+            if (item.type === "message") {
+                const block = this.nextIndex++;
+                this.blocks.set(idx, { block, kind: "text", argsSeen: false });
+                out.push(this.event("content_block_start", { type: "content_block_start", index: block, content_block: { type: "text", text: "" } }));
+            }
+            else if (item.type === "function_call") {
+                const block = this.nextIndex++;
+                this.blocks.set(idx, { block, kind: "tool", argsSeen: false });
+                this.sawTool = true;
+                out.push(this.event("content_block_start", {
+                    type: "content_block_start",
+                    index: block,
+                    content_block: {
+                        type: "tool_use",
+                        id: String(item.call_id ?? item.id ?? `call_${crypto.randomBytes(6).toString("hex")}`),
+                        name: String(item.name ?? ""),
+                        input: {},
+                    },
+                }));
+            }
+            return out;
+        }
+        if (type === "response.output_text.delta" || type === "response.refusal.delta") {
+            const entry = this.blocks.get(Number(ev.output_index));
+            const text = String(ev.delta ?? "");
+            if (entry && entry.kind === "text" && text) {
+                out.push(this.event("content_block_delta", { type: "content_block_delta", index: entry.block, delta: { type: "text_delta", text } }));
+            }
+            return out;
+        }
+        if (type === "response.function_call_arguments.delta") {
+            const entry = this.blocks.get(Number(ev.output_index));
+            const args = String(ev.delta ?? "");
+            if (entry && entry.kind === "tool" && args) {
+                entry.argsSeen = true;
+                out.push(this.event("content_block_delta", { type: "content_block_delta", index: entry.block, delta: { type: "input_json_delta", partial_json: args } }));
+            }
+            return out;
+        }
+        if (type === "response.output_item.done") {
+            const entry = this.blocks.get(Number(ev.output_index));
+            if (entry) {
+                if (entry.kind === "tool" && !entry.argsSeen) {
+                    // The arguments may have come whole on the done item rather than
+                    // as deltas; Anthropic wants them as json deltas inside the block.
+                    const item = ev.item ?? {};
+                    const args = typeof item.arguments === "string" && item.arguments.trim() ? item.arguments : "{}";
+                    out.push(this.event("content_block_delta", { type: "content_block_delta", index: entry.block, delta: { type: "input_json_delta", partial_json: args } }));
+                    entry.argsSeen = true;
+                }
+                out.push(this.event("content_block_stop", { type: "content_block_stop", index: entry.block }));
+                this.blocks.delete(Number(ev.output_index));
+            }
+            return out;
+        }
+        if (type === "response.completed" || type === "response.incomplete" || type === "response.failed") {
+            const r = ev.response ?? {};
+            const u = r.usage;
+            if (u)
+                this.usage = { input: Number(u.input_tokens ?? 0), output: Number(u.output_tokens ?? 0) };
+            const reason = r.incomplete_details?.reason;
+            if (typeof reason === "string")
+                this.incomplete = reason;
+            return out;
+        }
+        return out;
+    }
+    /** The stream ended: close what is still open, say why, and stop. */
+    finishStream() {
+        const out = this.start();
+        for (const entry of this.blocks.values()) {
+            if (entry.kind === "tool") {
+                if (!entry.argsSeen)
+                    out.push(this.event("content_block_delta", { type: "content_block_delta", index: entry.block, delta: { type: "input_json_delta", partial_json: "{}" } }));
+            }
+            out.push(this.event("content_block_stop", { type: "content_block_stop", index: entry.block }));
+        }
+        const reason = this.sawTool && this.incomplete !== "max_output_tokens" ? "tool_use" : this.incomplete === "max_output_tokens" ? "max_tokens" : "end_turn";
+        out.push(this.event("message_delta", {
+            type: "message_delta",
+            delta: { stop_reason: reason, stop_sequence: null },
+            usage: { input_tokens: this.usage?.input ?? 0, output_tokens: this.usage?.output ?? 0 },
+        }));
+        out.push(this.event("message_stop", { type: "message_stop" }));
+        return out;
+    }
+}
+// ---------------------------------------------------------------- errors
+function errorType(status) {
+    if (status === 400)
+        return "invalid_request_error";
+    if (status === 401)
+        return "authentication_error";
+    if (status === 403)
+        return "permission_error";
+    if (status === 404)
+        return "not_found_error";
+    if (status === 429)
+        return "rate_limit_error";
+    if (status === 529)
+        return "overloaded_error";
+    return "api_error";
+}
+function errorBody(status, message) {
+    return JSON.stringify({ type: "error", error: { type: errorType(status), message } });
+}
+/** The provider's own words for what went wrong, whatever shape it used. */
+function upstreamMessage(text, status) {
+    try {
+        const parsed = JSON.parse(text);
+        const err = parsed.error;
+        if (typeof err === "string")
+            return err;
+        if (err && typeof err.message === "string")
+            return err.message;
+        if (typeof parsed.message === "string")
+            return parsed.message;
+    }
+    catch {
+        // not JSON — the text is the message
+    }
+    return text.slice(0, 500) || `upstream returned HTTP ${status}`;
+}
+// ---------------------------------------------------------------- server
+/**
+ * Start the translator for one step. Binds an ephemeral port on loopback,
+ * mints the key the SDK will present, and returns the env that points the
+ * SDK at it. Close it when the step is over.
+ */
+export async function startTranslator(spec) {
+    const key = `fr-${crypto.randomBytes(16).toString("hex")}`;
+    const log = [];
+    const base = spec.upstreamBase.replace(/\/+$/, "");
+    const label = spec.label ?? base;
+    const server = http.createServer(async (req, res) => {
+        const started = Date.now();
+        const send = (status, body, type = "application/json") => {
+            res.writeHead(status, { "content-type": type });
+            res.end(body);
+        };
+        try {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            const presented = req.headers["x-api-key"] ?? (req.headers.authorization ?? "").replace(/^Bearer\s+/i, "");
+            const ok = typeof presented === "string" && presented.length === key.length && crypto.timingSafeEqual(Buffer.from(presented), Buffer.from(key));
+            if (!ok)
+                return send(401, errorBody(401, "translator: wrong key for this step"));
+            const raw = await new Promise((resolve, reject) => {
+                let body = "";
+                req.on("data", (c) => (body += c.toString()));
+                req.on("end", () => resolve(body));
+                req.on("error", reject);
+            });
+            if (req.method === "POST" && url.pathname === "/v1/messages/count_tokens") {
+                // No endpoint on the other side counts for us; four characters a
+                // token is the estimate every tokenizer lands near for English.
+                const chars = raw.length;
+                return send(200, JSON.stringify({ input_tokens: Math.ceil(chars / 4) }));
+            }
+            if (req.method !== "POST" || url.pathname !== "/v1/messages") {
+                return send(404, errorBody(404, `translator: no ${req.method} ${url.pathname} — only POST /v1/messages`));
+            }
+            let body;
+            try {
+                body = JSON.parse(raw);
+            }
+            catch {
+                return send(400, errorBody(400, "translator: request body is not JSON"));
+            }
+            const stream = body.stream === true;
+            const drop = dropped();
+            const responses = spec.wire === "responses";
+            const outbound = responses
+                ? toResponses(body, { reasoningEffort: spec.reasoningEffort, params: spec.params, stream }, drop)
+                : toChatCompletions(body, { maxTokensParam: spec.maxTokensParam, reasoningEffort: spec.reasoningEffort, params: spec.params, stream }, drop);
+            for (const line of drop.lines())
+                if (!log.includes(line))
+                    log.push(line);
+            let upstream;
+            try {
+                upstream = await fetch(viaEgress(spec.egress, `${base}${responses ? "/responses" : "/chat/completions"}`), {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${spec.upstreamKey}`,
+                        ...(spec.headers ?? {}),
+                    },
+                    body: JSON.stringify(outbound),
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                log.push(`POST ${label} → unreachable: ${message}`);
+                return send(502, errorBody(502, `translator: could not reach ${label}: ${message}`));
+            }
+            if (!upstream.ok) {
+                const text = await upstream.text();
+                const message = upstreamMessage(text, upstream.status);
+                log.push(`POST ${label} → ${upstream.status} (${Date.now() - started}ms): ${message.slice(0, 160)}`);
+                // The status crosses unchanged, so a 401 or 429 from the provider
+                // reads as one to the SDK — and to the fallback decision upstream.
+                return send(upstream.status, errorBody(upstream.status, message));
+            }
+            const model = String(body.model ?? "");
+            if (!stream) {
+                const text = await upstream.text();
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    return send(502, errorBody(502, `translator: ${label} answered with something that is not JSON`));
+                }
+                log.push(`POST ${label} → 200 (${Date.now() - started}ms, ${model})`);
+                return send(200, JSON.stringify(responses ? fromResponses(parsed, model) : fromChatCompletion(parsed, model)));
+            }
+            res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+            const machine = responses ? new ResponsesStreamTranslator(model) : new StreamTranslator(model);
+            const reader = upstream.body?.getReader();
+            if (!reader) {
+                for (const e of machine.finishStream())
+                    res.write(e);
+                return res.end();
+            }
+            const decoder = new TextDecoder();
+            let buffer = "";
+            let chunks = 0;
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let nl;
+                while ((nl = buffer.indexOf("\n")) !== -1) {
+                    const line = buffer.slice(0, nl).trim();
+                    buffer = buffer.slice(nl + 1);
+                    if (!line.startsWith("data:"))
+                        continue;
+                    const data = line.slice(5).trim();
+                    if (data === "[DONE]")
+                        continue;
+                    try {
+                        chunks++;
+                        for (const e of machine.feed(JSON.parse(data)))
+                            res.write(e);
+                    }
+                    catch {
+                        // a malformed chunk is skipped, not fatal — the stream goes on
+                    }
+                }
+            }
+            for (const e of machine.finishStream())
+                res.write(e);
+            res.end();
+            log.push(`POST ${label} → 200 (stream, ${chunks} chunks, ${Date.now() - started}ms, ${model})`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log.push(`translator error: ${message}`);
+            if (!res.headersSent)
+                send(500, errorBody(500, `translator: ${message}`));
+            else
+                res.end();
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : 0;
+    const baseUrl = `http://127.0.0.1:${port}`;
+    return {
+        port,
+        key,
+        baseUrl,
+        env: {
+            ANTHROPIC_BASE_URL: baseUrl,
+            // The SDK sends ANTHROPIC_API_KEY as x-api-key, which is what the
+            // server above checks; the bearer slot is blanked so the SDK cannot
+            // fall back to Anthropic's own endpoint with a stale credential.
+            ANTHROPIC_API_KEY: key,
+            ANTHROPIC_AUTH_TOKEN: "",
+            CLAUDE_CODE_OAUTH_TOKEN: "",
+        },
+        drainLog: () => log.splice(0, log.length),
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections?.();
+            server.close(() => resolve());
+        }),
+    };
+}
+/**
+ * What a provider block needs from the translator, or null when the block
+ * speaks Anthropic and needs none. Values only — this crosses into the run
+ * container as JSON.
+ */
+export function translatorSpecFor(spec) {
+    if (spec.format !== "openai" && spec.format !== "responses")
+        return null;
+    return {
+        wire: spec.format === "responses" ? "responses" : "chat",
+        upstreamBase: spec.baseUrl,
+        upstreamKey: spec.token,
+        headers: spec.headers,
+        params: spec.params,
+        maxTokensParam: spec.maxTokensParam,
+        reasoningEffort: spec.reasoningEffort,
+        label: spec.name ? `${spec.name} (${spec.baseUrl})` : spec.baseUrl,
+    };
+}