@wacry/codeks-bridge 0.0.0-stage → 0.0.3

package/dist/adapter-options.d.ts

@@ -0,0 +1,5 @@
+import type { AdapterId, ClaudeMessagesOptions, ResolvedModel } from "./types.ts";
+/** Validate bridge-owned settings; native options stay open to upstream extensions. */
+export declare function validateAdapterConfig(value: unknown, location: string, adapter?: AdapterId): void;
+/** Model leaves override connection leaves; neither is part of state provenance. */
+export declare function resolveClaudeOptions(route: Pick<ResolvedModel, "upstream" | "config">): ClaudeMessagesOptions;

package/dist/adapter-options.js

@@ -0,0 +1,41 @@
+import { BridgeError } from "./errors.js";
+function object(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/** Validate bridge-owned settings; native options stay open to upstream extensions. */
+export function validateAdapterConfig(value, location, adapter) {
+    if (value === undefined)
+        return;
+    function fail(message) {
+        throw new BridgeError(`Invalid configuration: ${location}.adapters: ${message}`);
+    }
+    if (!object(value))
+        fail("must be an object");
+    for (const [name, settings] of Object.entries(value)) {
+        if (name !== "claude-messages")
+            fail(`unknown adapter settings ${name}`);
+        if (adapter !== undefined && name !== adapter)
+            fail(`${name} does not match the model adapter ${adapter}`);
+        if (!object(settings))
+            fail(`${name} must be an object`);
+        for (const field of Object.keys(settings)) {
+            if (field !== "tool_updates" && field !== "thinking_mismatch")
+                fail(`unknown ${name} setting ${field}`);
+        }
+        if (settings.tool_updates !== undefined && !["inline", "top_level"].includes(settings.tool_updates)) {
+            fail(`${name}.tool_updates must be inline or top_level`);
+        }
+        if (settings.thinking_mismatch !== undefined && !["drop_block", "error", "upstream_default"].includes(settings.thinking_mismatch)) {
+            fail(`${name}.thinking_mismatch must be drop_block, error, or upstream_default`);
+        }
+    }
+}
+/** Model leaves override connection leaves; neither is part of state provenance. */
+export function resolveClaudeOptions(route) {
+    const upstream = route.upstream.adapters?.["claude-messages"];
+    const model = route.config.adapters?.["claude-messages"];
+    return {
+        tool_updates: model?.tool_updates ?? upstream?.tool_updates ?? "inline",
+        thinking_mismatch: model?.thinking_mismatch ?? upstream?.thinking_mismatch ?? "drop_block",
+    };
+}

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+import type { Api, UpstreamConfig } from "./types.ts";
+export declare function upstreamHeaders(config: UpstreamConfig, api: Api, signal: AbortSignal, clientHeaders?: Headers): Promise<Headers>;

package/dist/auth.js

@@ -0,0 +1,42 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { BridgeError } from "./errors.js";
+import { forwardRequestHeaders } from "./headers.js";
+const execute = promisify(execFile);
+export async function upstreamHeaders(config, api, signal, clientHeaders) {
+    const headers = forwardRequestHeaders(clientHeaders, config.auth_header);
+    for (const [name, value] of Object.entries(config.headers ?? {}))
+        headers.set(name, value);
+    if (!headers.has("content-type"))
+        headers.set("content-type", "application/json");
+    if (api === "anthropic" && !headers.has("anthropic-version"))
+        headers.set("anthropic-version", "2023-06-01");
+    let credential;
+    if (config.api_key_env) {
+        credential = process.env[config.api_key_env]?.trim();
+        if (!credential)
+            throw new BridgeError(`Missing credential environment variable: ${config.api_key_env}`);
+    }
+    else if (config.api_key_command) {
+        const [command, ...args] = config.api_key_command;
+        try {
+            const result = await execute(command, args, { encoding: "utf8", timeout: 30_000, maxBuffer: 64 * 1024, signal });
+            credential = result.stdout.trim();
+        }
+        catch {
+            if (signal.aborted)
+                throw signal.reason;
+            // execFile errors include stdout/stderr. Never forward those to a client.
+            throw new BridgeError("Credential command failed");
+        }
+        if (!credential)
+            throw new BridgeError("Credential command returned an empty credential");
+    }
+    if (credential) {
+        if (/[\r\n]/.test(credential))
+            throw new BridgeError("Credential must be a single line");
+        const header = config.auth_header ?? (api === "anthropic" ? "x-api-key" : "authorization");
+        headers.set(header, header.toLowerCase() === "authorization" ? `Bearer ${credential}` : credential);
+    }
+    return headers;
+}

package/dist/backends/anthropic-tools.d.ts

@@ -0,0 +1,13 @@
+import { type ToolSet } from "../tools.ts";
+import type { ResponsesRequest } from "../types.ts";
+export interface AnthropicToolDefinition {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+/** Keep later definitions at their original conversation boundary. */
+export declare function buildAnthropicTools(request: ResponsesRequest, mode: "inline" | "top_level"): {
+    tools: ToolSet;
+    definitions: AnthropicToolDefinition[];
+    input: ResponsesRequest["input"];
+};

package/dist/backends/anthropic-tools.js

@@ -0,0 +1,41 @@
+import { BridgeError } from "../errors.js";
+import { buildToolSet, normalizeToolDeclarations } from "../tools.js";
+function definition(tool) {
+    return { name: tool.flatName, description: tool.description, input_schema: tool.parameters };
+}
+/** Keep later definitions at their original conversation boundary. */
+export function buildAnthropicTools(request, mode) {
+    if (mode === "top_level") {
+        const normalized = normalizeToolDeclarations(request);
+        const tools = buildToolSet(normalized.tools);
+        return { tools, definitions: tools.entries.map(definition), input: normalized.input };
+    }
+    const tools = buildToolSet(request.tools);
+    const initial = new Map(tools.entries.map((tool) => [tool.flatName, definition(tool)]));
+    if (!Array.isArray(request.input)) {
+        return { tools, definitions: [...initial.values()], input: request.input };
+    }
+    const input = [];
+    let prefix = true;
+    for (const item of request.input) {
+        if (item?.type === "additional_tools") {
+            if (!Array.isArray(item.tools))
+                throw new BridgeError("additional_tools requires a tools array.");
+            const definitions = tools.add(item.tools).map(definition);
+            if (prefix) {
+                for (const tool of definitions)
+                    initial.set(tool.name, tool);
+            }
+            else if (definitions.length) {
+                input.push({ ...item, tools: definitions });
+            }
+        }
+        else {
+            input.push(item);
+            if (!item || !["system", "developer"].includes(item.role) ||
+                (item.type !== undefined && item.type !== "message"))
+                prefix = false;
+        }
+    }
+    return { tools, definitions: [...initial.values()], input };
+}

package/dist/backends/anthropic.d.ts

@@ -0,0 +1,9 @@
+import type { ToolSet } from "../tools.ts";
+import type { Backend, BackendContext } from "../types.ts";
+/** Convert only request-owned copies; stored history remains unchanged. */
+export declare function buildAnthropicRequest(context: BackendContext): {
+    body: Record<string, any>;
+    tools: ToolSet;
+    betas: string[];
+};
+export declare const runAnthropic: Backend;

package/dist/backends/anthropic.js

@@ -0,0 +1,356 @@
+import { encodeReasoning } from "../carrier.js";
+import { resolveClaudeOptions } from "../adapter-options.js";
+import { BridgeError, upstreamError } from "../errors.js";
+import { prepareHistory } from "../history.js";
+import { reasoningEffort, reasoningSummaryRequested } from "../profiles.js";
+import { parseJsonSse } from "../sse.js";
+import { safeCallId } from "../tools.js";
+import { upstreamFetch } from "../upstream.js";
+import { buildAnthropicTools } from "./anthropic-tools.js";
+const THINKING_BINDING_BETA = "thinking-binding-controls-2026-08-01";
+const INLINE_TOOLS_BETA = "inline-tools-2026-09-15";
+function contentBlocks(content) {
+    if (typeof content === "string")
+        return content ? [{ type: "text", text: content }] : [];
+    if (!Array.isArray(content))
+        throw new BridgeError("Messages content must be text or an array.");
+    return content.flatMap((part) => {
+        if (["input_text", "output_text", "text"].includes(part.type)) {
+            return part.text ? [{ type: "text", text: part.text }] : [];
+        }
+        if (part.type === "input_image" || part.type === "image_url") {
+            const url = typeof part.image_url === "string" ? part.image_url : part.image_url?.url;
+            if (typeof url !== "string")
+                throw new BridgeError("An image needs an image_url.");
+            const data = /^data:(image\/(?:jpeg|png|gif|webp));base64,([\s\S]+)$/.exec(url);
+            if (data)
+                return [{ type: "image", source: { type: "base64", media_type: data[1], data: data[2] } }];
+            if (/^https?:\/\//.test(url))
+                return [{ type: "image", source: { type: "url", url } }];
+            throw new BridgeError("Messages images must use an HTTP URL or a JPEG, PNG, GIF, or WebP base64 data URL.");
+        }
+        if (part.type === "refusal")
+            return [{ type: "text", text: String(part.refusal ?? "") }];
+        throw new BridgeError(`Unsupported Messages content type: ${String(part.type)}.`);
+    });
+}
+function parseArguments(value) {
+    let parsed;
+    try {
+        parsed = typeof value === "string" ? JSON.parse(value) : value;
+    }
+    catch {
+        throw new BridgeError("A tool call contains invalid JSON arguments.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new BridgeError("Messages tool arguments must be an object.");
+    }
+    return parsed;
+}
+function toolChoice(value, tools) {
+    if (value === undefined)
+        return undefined;
+    if (value === "auto")
+        return { type: "auto" };
+    if (value === "none")
+        return { type: "none" };
+    if (value === "required")
+        return { type: "any" };
+    if (value && ["function", "custom"].includes(value.type) && typeof value.name === "string") {
+        const selected = tools.get(value.namespace, value.name);
+        if (!selected || selected.kind !== value.type) {
+            throw new BridgeError("The selected tool is not available on the Messages backend.");
+        }
+        return { type: "tool", name: selected.flatName };
+    }
+    throw new BridgeError("Unsupported Messages tool_choice.");
+}
+/** Convert only request-owned copies; stored history remains unchanged. */
+export function buildAnthropicRequest(context) {
+    const { route } = context;
+    const request = context.request;
+    const settings = resolveClaudeOptions(route);
+    const { tools, definitions, input } = buildAnthropicTools(request, settings.tool_updates);
+    const system = request.instructions ? [{ type: "text", text: request.instructions }] : [];
+    const messages = [];
+    let additions = [];
+    let hasInlineTools = false;
+    const continueAssistant = () => {
+        const tail = messages.at(-1);
+        if (tail?.role === "assistant" && !tail.content.some(block => block.type === "tool_use")) {
+            messages.push({ role: "user", content: [{ type: "text", text: "Continue." }] });
+        }
+    };
+    const flushAdditions = () => {
+        if (!additions.length)
+            return;
+        // A persisted declaration also anchors this boundary on later replays.
+        continueAssistant();
+        if (messages.at(-1)?.role !== "user") {
+            throw new BridgeError("Inline tool declarations require a user or completed tool-result boundary.");
+        }
+        messages.push({ role: "system", content: additions });
+        additions = [];
+        hasInlineTools = true;
+    };
+    const append = (role, blocks) => {
+        if (!blocks.length)
+            return;
+        // Several reminders/results may share a user turn. Tool declarations take
+        // effect after that complete boundary, before the next assistant step.
+        if (role === "assistant")
+            flushAdditions();
+        const last = messages.at(-1);
+        if (last?.role === role)
+            last.content.push(...blocks);
+        else
+            messages.push({ role, content: blocks });
+    };
+    for (const item of prepareHistory(input, route)) {
+        if (item.type === "additional_tools") {
+            additions.push(...item.tools.map((definition) => ({
+                type: "tool_addition", tool: { type: "tool_definition", definition },
+            })));
+        }
+        else if (item.type === "bridge_reasoning") {
+            const block = item.state.data;
+            if (!block || !["thinking", "redacted_thinking"].includes(block.type)) {
+                throw new BridgeError("Invalid Messages reasoning carrier.");
+            }
+            append("assistant", [block]);
+        }
+        else if (item.type === "function_call" || item.type === "custom_tool_call") {
+            append("assistant", [{
+                    type: "tool_use", id: safeCallId(item.call_id), name: tools.flatFor(item.namespace, item.name),
+                    input: item.type === "custom_tool_call" ? { input: item.input } : parseArguments(item.arguments),
+                }]);
+        }
+        else if (item.type === "function_call_output" || item.type === "custom_tool_call_output") {
+            const content = contentBlocks(item.output);
+            append("user", [{ type: "tool_result", tool_use_id: safeCallId(item.call_id), ...(content.length ? { content } : {}) }]);
+        }
+        else if (item.type === "message" || item.role) {
+            const blocks = contentBlocks(item.content);
+            if (item.role === "developer" || item.role === "system") {
+                if (blocks.some((block) => block.type !== "text"))
+                    throw new BridgeError("System messages must contain text.");
+                if (!messages.length)
+                    system.push(...blocks);
+                // Inline system roles have placement restrictions that arbitrary Responses
+                // history cannot satisfy. Keep reminders in order without rewriting a
+                // signed assistant prefix or moving new instructions to the beginning.
+                else
+                    append("user", [{ type: "text", text: `<system-reminder>\n${blocks.map((block) => block.text).join("\n\n")}\n</system-reminder>` }]);
+            }
+            else if (item.role === "assistant" || item.role === "user") {
+                append(item.role, blocks);
+            }
+            else
+                throw new BridgeError(`Unsupported Messages role: ${String(item.role)}.`);
+        }
+        else
+            throw new BridgeError(`Unsupported Messages history item: ${String(item.type)}.`);
+    }
+    // A failed response can leave a complete thinking/text item in codeks history.
+    // Claude requires a user boundary to resume. Do not mask a missing tool result.
+    continueAssistant();
+    flushAdditions();
+    // Keep stable prefixes at 1h. The one-off compaction suffix uses 5m.
+    const cache = (block, ttl = "1h") => {
+        if (block)
+            block.cache_control = { type: "ephemeral", ttl };
+    };
+    cache(definitions.at(-1));
+    cache(system.at(-1));
+    const userMessages = messages.filter((message) => message.role === "user");
+    for (const message of userMessages.slice(-2)) {
+        cache(message.content.at(-1), context.compacting && message === userMessages.at(-1) ? "5m" : "1h");
+    }
+    const effort = reasoningEffort(route, request.reasoning?.effort);
+    const body = {
+        thinking: effort === "none" ? { type: "disabled" } : {
+            type: "adaptive", display: reasoningSummaryRequested(request) ? "summarized" : "omitted",
+        },
+        ...(effort !== "none" ? { output_config: { effort } } : {}),
+        max_tokens: request.max_output_tokens ?? route.profile.max_output_tokens,
+    };
+    for (const name of ["temperature", "top_p"]) {
+        if (request[name] !== undefined)
+            body[name] = request[name];
+    }
+    let choice = toolChoice(request.tool_choice, tools);
+    if (tools.entries.length && typeof request.parallel_tool_calls === "boolean" && choice?.type !== "none") {
+        choice = { ...(choice ?? { type: "auto" }), disable_parallel_tool_use: !request.parallel_tool_calls };
+    }
+    if (choice)
+        body.tool_choice = choice;
+    const format = request.text?.format;
+    if (format !== undefined && format.type !== "text") {
+        if (format.type !== "json_schema")
+            throw new BridgeError(`Messages does not support text format ${String(format.type)}.`);
+        body.output_config = { ...body.output_config, format: { type: "json_schema", schema: format.schema } };
+    }
+    Object.assign(body, route.upstream.options, route.config.options, {
+        model: route.config.model, messages, stream: true,
+    });
+    // Native options remain authoritative. Modes such as between_tools do not
+    // support binding controls; do not change the caller's chosen thinking mode.
+    if (["adaptive", "enabled"].includes(body.thinking?.type) &&
+        settings.thinking_mismatch !== "upstream_default") {
+        body.thinking = {
+            ...body.thinking,
+            block_binding: {
+                prefix_mismatch_behavior: settings.thinking_mismatch,
+                ...body.thinking.block_binding,
+            },
+        };
+    }
+    if (system.length)
+        body.system = system;
+    else
+        delete body.system;
+    if (definitions.length)
+        body.tools = definitions;
+    else
+        delete body.tools;
+    if (context.compacting) {
+        if (body.output_config) {
+            body.output_config = { ...body.output_config };
+            delete body.output_config.format;
+        }
+    }
+    return { body, tools, betas: [THINKING_BINDING_BETA, ...(hasInlineTools ? [INLINE_TOOLS_BETA] : [])] };
+}
+function tokenCount(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new BridgeError("Messages stream has invalid or missing token usage.", "upstream_error", 502);
+    }
+    return value;
+}
+function validateUsage(value, required) {
+    for (const field of required)
+        tokenCount(value?.[field]);
+    for (const field of ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"]) {
+        if (value?.[field] !== undefined)
+            tokenCount(value[field]);
+    }
+    if (value?.output_tokens_details?.thinking_tokens !== undefined)
+        tokenCount(value.output_tokens_details.thinking_tokens);
+}
+export const runAnthropic = async (context, writer) => {
+    const { body, tools, betas } = buildAnthropicRequest(context);
+    const response = await upstreamFetch(context.route, "/messages", body, context.signal, context.requestHeaders, { "anthropic-beta": betas });
+    context.onAccepted?.(response.headers);
+    if (!response.body)
+        throw new BridgeError("Messages returned an empty stream.", "upstream_error", 502);
+    const blocks = new Map();
+    let rawUsage = {};
+    let started = false;
+    let finalUsage = false;
+    let stopReason;
+    let stopped = false;
+    for await (const { json: event } of parseJsonSse(response.body)) {
+        if (event.type === "error")
+            throw upstreamError(undefined, event, response.headers);
+        if (event.type === "ping") {
+            writer.keepalive();
+            continue;
+        }
+        if (event.type === "message_start") {
+            validateUsage(event.message?.usage, ["input_tokens", "output_tokens"]);
+            started = true;
+            rawUsage = { ...rawUsage, ...event.message?.usage };
+        }
+        else if (event.type === "content_block_start") {
+            const value = { ...event.content_block };
+            if (!["text", "thinking", "redacted_thinking", "tool_use"].includes(value.type)) {
+                throw new BridgeError(`Unsupported Messages output block: ${String(value.type)}.`);
+            }
+            blocks.set(event.index, { value, json: "" });
+            if (value.type === "text" && value.text)
+                writer.textDelta(value.text);
+            if (value.type === "thinking")
+                writer.reasoningDelta(value.thinking ?? "");
+        }
+        else if (event.type === "content_block_delta") {
+            const block = blocks.get(event.index);
+            if (!block)
+                throw new BridgeError("Messages sent a delta before its block.", "upstream_error", 502);
+            const delta = event.delta;
+            if (delta.type === "text_delta") {
+                block.value.text = (block.value.text ?? "") + delta.text;
+                writer.textDelta(delta.text);
+            }
+            else if (delta.type === "thinking_delta") {
+                block.value.thinking = (block.value.thinking ?? "") + delta.thinking;
+                writer.reasoningDelta(delta.thinking);
+            }
+            else if (delta.type === "signature_delta") {
+                block.value.signature = (block.value.signature ?? "") + delta.signature;
+            }
+            else if (delta.type === "input_json_delta")
+                block.json += delta.partial_json;
+            else if (delta.type !== "citations_delta")
+                throw new BridgeError(`Unsupported Messages delta: ${String(delta.type)}.`);
+        }
+        else if (event.type === "content_block_stop") {
+            const block = blocks.get(event.index);
+            if (!block)
+                throw new BridgeError("Messages stopped an unknown block.", "upstream_error", 502);
+            if (block.value.type === "thinking" || block.value.type === "redacted_thinking") {
+                writer.endReasoning(encodeReasoning({ source: context.route.origin, format: context.route.profile.reasoning_format, data: block.value }));
+            }
+            else if (block.value.type === "tool_use") {
+                if (block.json)
+                    block.value.input = parseArguments(block.json);
+                const call = block.value;
+                const tool = tools.resolve(call.name);
+                if (!tool)
+                    throw new BridgeError(`Messages called an unknown tool: ${String(call.name)}.`);
+                if (tool.kind === "custom") {
+                    if (typeof call.input?.input !== "string")
+                        throw new BridgeError("A custom tool call needs a string input.");
+                    writer.addCustomToolCall({ call_id: call.id, name: tool.name, namespace: tool.namespace, input: call.input.input });
+                }
+                else
+                    writer.addFunctionCall({ call_id: call.id, name: tool.name, namespace: tool.namespace, arguments: JSON.stringify(call.input ?? {}) });
+            }
+            else if (block.value.type === "text")
+                writer.closeMessage();
+            blocks.delete(event.index);
+        }
+        else if (event.type === "message_delta") {
+            stopReason = event.delta?.stop_reason ?? stopReason;
+            validateUsage(event.usage, ["output_tokens"]);
+            finalUsage = true;
+            rawUsage = { ...rawUsage, ...event.usage };
+        }
+        else if (event.type === "message_stop")
+            stopped = true;
+    }
+    if (!started || !stopped || blocks.size || !stopReason) {
+        throw new BridgeError("Messages stream ended before the message was complete.", "upstream_error", 502);
+    }
+    if (stopReason === "model_context_window_exceeded") {
+        throw new BridgeError("Messages reached the model context window before completing the response.", "context_length_exceeded");
+    }
+    if (stopReason === "max_tokens" || stopReason === "refusal") {
+        throw new BridgeError(stopReason === "max_tokens" ? "Messages reached max_tokens before completing the response." : "Messages refused the request.");
+    }
+    if (!["end_turn", "stop_sequence", "tool_use", "pause_turn"].includes(stopReason)) {
+        throw new BridgeError(`Unsupported Messages stop reason: ${stopReason}.`);
+    }
+    if (!finalUsage)
+        throw new BridgeError("Messages stream ended without final token usage.", "upstream_error", 502);
+    const usage = {
+        input_tokens: tokenCount(rawUsage.input_tokens + (rawUsage.cache_read_input_tokens ?? 0) + (rawUsage.cache_creation_input_tokens ?? 0)),
+        cached_tokens: rawUsage.cache_read_input_tokens ?? 0,
+        cache_write_tokens: rawUsage.cache_creation_input_tokens ?? 0,
+        output_tokens: tokenCount(rawUsage.output_tokens),
+        ...(rawUsage.output_tokens_details?.thinking_tokens != null ? { reasoning_tokens: rawUsage.output_tokens_details.thinking_tokens } : {}),
+    };
+    return {
+        usage,
+        endTurn: stopReason !== "tool_use" && stopReason !== "pause_turn",
+    };
+};

package/dist/backends/chat.d.ts

@@ -0,0 +1,16 @@
+import { BridgeError } from "../errors.ts";
+import type { ToolSet } from "../tools.ts";
+import type { BackendContext, BackendResult } from "../types.ts";
+import type { ResponseWriter, Usage } from "../writer.ts";
+/** A wire dialect supplies only the parts that differ from Chat Completions. */
+export interface ChatDialect {
+    reasoningField: string;
+    requestParameters(context: BackendContext): Record<string, unknown>;
+    readUsage(value: any): Usage;
+    failureReason(reason: string): BridgeError | undefined;
+}
+export declare function buildChatRequest(context: BackendContext, dialect: ChatDialect): {
+    body: Record<string, any>;
+    tools: ToolSet;
+};
+export declare function runChat(context: BackendContext, writer: ResponseWriter, dialect: ChatDialect): Promise<BackendResult>;