@wacry/codeks-bridge 0.0.0-stage → 0.0.3

package/dist/tools.js

@@ -0,0 +1,193 @@
+// Tool definitions for upstreams that only know plain functions.
+//
+// codeks sends three kinds of client tools: `function`, `custom` (freeform
+// input, optionally constrained by a Lark or regex grammar) and `namespace`
+// (a group of functions). The shared Messages/Chat mapping uses names matching
+// [a-zA-Z0-9_-]{1,64}, the smaller Chat limit. See docs/tools.md.
+import { createHash } from "node:crypto";
+import { BridgeError } from "./errors.js";
+export const MAX_TOOL_NAME = 64;
+function sanitize(name) {
+    const cleaned = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return cleaned === "" ? "tool" : cleaned;
+}
+function shorten(name, limit) {
+    if (name.length <= limit)
+        return name;
+    // Same idea as codeks for long MCP tool names: keep a readable prefix and
+    // add a short hash so that different long names stay different.
+    const hash = createHash("sha1").update(name).digest("hex").slice(0, 8);
+    return `${name.slice(0, limit - 9)}_${hash}`;
+}
+/** Joins a namespace and a tool name the way codeks names MCP tools. */
+export function baseFlatName(namespace, name) {
+    let joined = name;
+    if (namespace)
+        joined = namespace.endsWith("_") ? `${namespace}${name}` : `${namespace}__${name}`;
+    return shorten(sanitize(joined), MAX_TOOL_NAME);
+}
+function identity(namespace, name) {
+    return `${namespace === "functions" ? "" : namespace ?? ""}\u0000${name}`;
+}
+/** Extracts Lite declarations for APIs whose tools live outside the conversation. */
+export function normalizeToolDeclarations(request) {
+    if (!Array.isArray(request.input))
+        return request;
+    const tools = [...(request.tools ?? [])];
+    const input = request.input.filter((item) => {
+        if (item?.type !== "additional_tools")
+            return true;
+        if (!Array.isArray(item.tools))
+            throw new BridgeError("additional_tools requires a tools array.");
+        tools.push(...item.tools);
+        return false;
+    });
+    return { ...request, input, tools };
+}
+const SCHEMA_CHILD_MAPS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"];
+const SCHEMA_CHILD_LISTS = ["anyOf", "oneOf", "allOf", "prefixItems"];
+const SCHEMA_CHILD_ONE = ["items", "additionalProperties", "not", "if", "then", "else", "contains", "propertyNames"];
+/** Removes keywords that only the OpenAI Responses API understands. */
+export function cleanSchema(schema) {
+    if (Array.isArray(schema))
+        return schema.map(cleanSchema);
+    if (!schema || typeof schema !== "object")
+        return schema;
+    const out = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "encrypted" && typeof value === "boolean")
+            continue;
+        if (SCHEMA_CHILD_MAPS.includes(key) && value && typeof value === "object" && !Array.isArray(value)) {
+            const mapped = {};
+            for (const [k, v] of Object.entries(value))
+                mapped[k] = cleanSchema(v);
+            out[key] = mapped;
+        }
+        else if (SCHEMA_CHILD_LISTS.includes(key) && Array.isArray(value)) {
+            out[key] = value.map(cleanSchema);
+        }
+        else if (SCHEMA_CHILD_ONE.includes(key)) {
+            out[key] = cleanSchema(value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function objectSchema(parameters) {
+    if (parameters == null)
+        return { type: "object", properties: {} };
+    const cleaned = cleanSchema(parameters);
+    if (cleaned && typeof cleaned === "object" && !Array.isArray(cleaned)) {
+        return { type: "object", ...cleaned };
+    }
+    throw new BridgeError("Function tool parameters must be a JSON Schema object.");
+}
+/** Describes a custom tool's input format in words, for function-only upstreams. */
+export function customToolDescription(description, format) {
+    const parts = [description.trim()];
+    parts.push("Pass the whole tool input as the string field `input`.");
+    if (format && format.type === "grammar" && typeof format.definition === "string") {
+        const syntax = String(format.syntax ?? "lark");
+        if (syntax === "regex") {
+            parts.push(`The \`input\` string must match this regular expression:\n\n\`\`\`\n${format.definition}\n\`\`\``);
+        }
+        else {
+            parts.push(`The \`input\` string must match this ${syntax === "lark" ? "Lark" : syntax} grammar:\n\n\`\`\`${syntax}\n${format.definition}\n\`\`\``);
+        }
+    }
+    return parts.filter((p) => p !== "").join("\n\n");
+}
+const CUSTOM_PARAMETERS = {
+    type: "object",
+    properties: { input: { type: "string", description: "The raw tool input." } },
+    required: ["input"],
+    additionalProperties: false,
+};
+export function buildToolSet(tools) {
+    const entries = [];
+    const byFlat = new Map();
+    const byIdentity = new Map();
+    const add = (entry) => {
+        const id = identity(entry.namespace, entry.name);
+        const previous = byIdentity.get(id);
+        if (previous) {
+            // Lite updates contain only changed members. Replace that definition
+            // without losing siblings or changing its established upstream name.
+            Object.assign(previous, entry);
+            return previous;
+        }
+        let flatName = baseFlatName(entry.namespace, entry.name);
+        // Add a suffix only when two different tools would get the same name.
+        for (let n = 2; byFlat.has(flatName); n++) {
+            const suffix = `_${n}`;
+            flatName = baseFlatName(entry.namespace, entry.name).slice(0, MAX_TOOL_NAME - suffix.length) + suffix;
+        }
+        const full = { ...entry, flatName };
+        entries.push(full);
+        byFlat.set(flatName, full);
+        byIdentity.set(id, full);
+        return full;
+    };
+    const visit = (tool, namespace) => {
+        if (!tool || typeof tool !== "object")
+            return [];
+        if (tool.type === "function") {
+            return [add({
+                    kind: "function",
+                    name: String(tool.name),
+                    namespace,
+                    description: String(tool.description ?? ""),
+                    parameters: objectSchema(tool.parameters),
+                })];
+        }
+        else if (tool.type === "custom") {
+            return [add({
+                    kind: "custom",
+                    name: String(tool.name),
+                    namespace,
+                    description: customToolDescription(String(tool.description ?? ""), tool.format),
+                    parameters: CUSTOM_PARAMETERS,
+                })];
+        }
+        else if (tool.type === "namespace" && Array.isArray(tool.tools)) {
+            return tool.tools.flatMap((inner) => visit(inner, String(tool.name)));
+        }
+        // Hosted tools (web_search, image_generation, tool_search, ...) have no
+        // equivalent on these upstreams and are left out.
+        return [];
+    };
+    const addTools = (declarations) => {
+        const changed = new Map();
+        for (const declaration of declarations) {
+            for (const entry of visit(declaration, undefined))
+                changed.set(entry.flatName, entry);
+        }
+        // Later updates may mutate the registry's current definition. Earlier
+        // inline definitions must retain the exact payload used at that point.
+        return structuredClone([...changed.values()]);
+    };
+    addTools(tools ?? []);
+    return {
+        entries,
+        add: addTools,
+        byFlat,
+        flatFor(namespace, name) {
+            return byIdentity.get(identity(namespace, name))?.flatName ?? baseFlatName(namespace, name);
+        },
+        get(namespace, name) {
+            return byIdentity.get(identity(namespace, name));
+        },
+        resolve(flatName) {
+            return byFlat.get(flatName);
+        },
+    };
+}
+/** Upstream tool call ids must match [a-zA-Z0-9_-]{1,64} on some APIs. */
+export function safeCallId(id) {
+    if (/^[a-zA-Z0-9_-]{1,64}$/.test(id))
+        return id;
+    const hash = createHash("sha1").update(id).digest("hex").slice(0, 8);
+    return `${sanitize(id).slice(0, 55)}_${hash}`;
+}

package/dist/types.d.ts

@@ -0,0 +1,125 @@
+import type { ResponseWriter, Usage } from "./writer.ts";
+export type Api = "responses" | "anthropic" | "chat";
+export type AdapterId = "gpt-responses" | "claude-messages" | "deepseek-chat";
+export interface ClaudeMessagesOptions {
+    tool_updates: "inline" | "top_level";
+    thinking_mismatch: "drop_block" | "error" | "upstream_default";
+}
+/** Bridge behavior, distinct from native request-body options. */
+export interface AdapterConfig {
+    "claude-messages"?: Partial<ClaudeMessagesOptions>;
+}
+export interface UpstreamConfig {
+    base_url: string;
+    api_key_env?: string;
+    /** An argv array. The command writes a short-lived credential to stdout. */
+    api_key_command?: string[];
+    auth_header?: string;
+    stream_idle_timeout_ms?: number;
+    headers?: Record<string, string>;
+    options?: Record<string, unknown>;
+    adapters?: AdapterConfig;
+}
+export interface ModelConfig {
+    upstream: string;
+    model: string;
+    catalog: string;
+    /** Include this alias in the client catalog. Defaults to true. */
+    expose?: boolean;
+    context_window?: number;
+    max_output_tokens?: number;
+    input_modalities?: ("text" | "image")[];
+    reasoning?: {
+        default_effort?: string;
+        effort_map?: Record<string, string>;
+    };
+    replay?: {
+        reasoning_from?: string[];
+        native_compaction_from?: string[];
+    };
+    compaction?: {
+        mode?: "summary" | "native";
+        model?: string;
+        native_replay?: boolean;
+    };
+    options?: Record<string, unknown>;
+    adapters?: AdapterConfig;
+}
+export interface BridgeConfig {
+    host?: string;
+    port?: number;
+    token_env?: string;
+    compaction_cache_dir?: string;
+    /** Debug capture for the /inspect/ page. */
+    inspect?: {
+        capture?: boolean;
+        max_mib?: number;
+    };
+    upstreams: Record<string, UpstreamConfig>;
+    models: Record<string, ModelConfig>;
+}
+export interface ModelProfile {
+    model_info: Record<string, any>;
+    max_output_tokens?: number;
+    id: AdapterId;
+    api: Api;
+    reasoning_format: string;
+    native_compaction_format?: string;
+    default_effort: string;
+    multi_agent_effort?: string;
+    effort_map: Record<string, string>;
+    input_modalities: ("text" | "image")[];
+}
+export interface StateOrigin {
+    /** Stable source fingerprint, independent of aliases and replay policy. */
+    id: string;
+    connection: string;
+    model: string;
+    adapter: AdapterId;
+}
+export interface ResolvedModel {
+    slug: string;
+    config: ModelConfig;
+    upstream: UpstreamConfig;
+    profile: ModelProfile;
+    origin: StateOrigin;
+    replay: {
+        reasoning: ReadonlySet<string>;
+        native_compaction: ReadonlySet<string>;
+    };
+    compaction: {
+        mode: "summary" | "native";
+        native_replay: boolean;
+    };
+}
+export interface ResponsesRequest {
+    model: string;
+    input?: string | Record<string, any>[];
+    instructions?: string;
+    tools?: any[];
+    tool_choice?: any;
+    reasoning?: {
+        effort?: string;
+        summary?: string;
+        [key: string]: unknown;
+    };
+    stream?: boolean;
+    [key: string]: any;
+}
+export interface BackendContext {
+    request: ResponsesRequest;
+    route: ResolvedModel;
+    signal: AbortSignal;
+    /** Client metadata; transport framing and credentials are replaced upstream. */
+    requestHeaders?: Headers;
+    compacting?: boolean;
+    /** Transport mode received from the client, including tool-free Lite requests. */
+    responsesLite?: boolean;
+    /** Called after the upstream accepts the HTTP request, before consuming its body. */
+    onAccepted?: (headers?: Headers) => void;
+}
+export interface BackendResult {
+    usage: Usage;
+    endTurn?: boolean;
+}
+export type Backend = (context: BackendContext, writer: ResponseWriter) => Promise<BackendResult>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/upstream.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedModel } from "./types.ts";
+/** base_url includes any API version prefix; path is appended, never resolved from /. */
+export declare function upstreamFetch(route: ResolvedModel, path: string, body: unknown, signal: AbortSignal, requestHeaders?: Headers, protocolHeaders?: Record<string, string | string[]>): Promise<Response>;

package/dist/upstream.js

@@ -0,0 +1,89 @@
+import { upstreamHeaders } from "./auth.js";
+import { BridgeError, transportError, upstreamError, UpstreamHttpError } from "./errors.js";
+import { captureUpstream } from "./inspect/capture.js";
+/** base_url includes any API version prefix; path is appended, never resolved from /. */
+export async function upstreamFetch(route, path, body, signal, requestHeaders, protocolHeaders) {
+    const url = route.upstream.base_url.replace(/\/+$/, "") + "/" + path.replace(/^\/+/, "");
+    const headers = await upstreamHeaders(route.upstream, route.profile.api, signal, requestHeaders);
+    for (const [name, value] of Object.entries(protocolHeaders ?? {})) {
+        // A protocol may require additional comma-separated feature flags without
+        // replacing the endpoint's configured flags. Scalar headers still replace.
+        headers.set(name, Array.isArray(value)
+            ? [...new Set([...(headers.get(name)?.split(",") ?? []), ...value].map(v => v.trim()).filter(Boolean))].join(",")
+            : value);
+    }
+    const payload = JSON.stringify(body);
+    const call = captureUpstream(url, headers, payload);
+    const idle = new AbortController();
+    const combined = AbortSignal.any([signal, idle.signal]);
+    const timeoutMs = route.upstream.stream_idle_timeout_ms ?? 300_000;
+    let timer;
+    const reset = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => idle.abort(new BridgeError("Upstream stream timed out", "stream_error", 504)), timeoutMs).unref();
+    };
+    reset();
+    let response;
+    try {
+        response = await fetch(url, { method: "POST", headers, body: payload, signal: combined, redirect: "error" });
+    }
+    catch (error) {
+        clearTimeout(timer);
+        call?.failed(combined.aborted ? combined.reason : error);
+        if (combined.aborted)
+            throw combined.reason;
+        throw transportError(error);
+    }
+    // Downstream keepalives do not count as upstream progress. Time out both the
+    // wait for headers and an idle response body, including a stalled error body.
+    call?.received(response);
+    if (response.body) {
+        const reader = response.body.getReader();
+        response = new Response(new ReadableStream({
+            async pull(controller) {
+                try {
+                    const chunk = await reader.read();
+                    if (chunk.done) {
+                        clearTimeout(timer);
+                        call?.done("complete");
+                        controller.close();
+                    }
+                    else {
+                        reset();
+                        call?.chunk(chunk.value);
+                        controller.enqueue(chunk.value);
+                    }
+                }
+                catch (error) {
+                    clearTimeout(timer);
+                    const cause = combined.aborted ? combined.reason : transportError(error);
+                    call?.done("error", cause);
+                    controller.error(cause);
+                }
+            },
+            async cancel(reason) {
+                clearTimeout(timer);
+                call?.done("unread");
+                await reader.cancel(reason);
+            },
+        }), { status: response.status, statusText: response.statusText, headers: response.headers });
+    }
+    else {
+        clearTimeout(timer);
+        call?.done("complete");
+    }
+    if (!response.ok) {
+        const text = await response.text();
+        if (combined.aborted)
+            throw combined.reason;
+        if (route.profile.api === "responses")
+            throw new UpstreamHttpError(response.status, text, response.headers);
+        let payload = text;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch { /* Non-JSON error bodies are still useful diagnostics. */ }
+        throw upstreamError(response.status, payload, response.headers);
+    }
+    return response;
+}

package/dist/writer.d.ts

@@ -0,0 +1,95 @@
+export interface Usage {
+    input_tokens: number;
+    cached_tokens?: number;
+    cache_write_tokens?: number;
+    output_tokens: number;
+    reasoning_tokens?: number;
+}
+export interface Sink {
+    write(chunk: string): void;
+}
+export interface FunctionCallItem {
+    call_id: string;
+    name: string;
+    namespace?: string;
+    arguments: string;
+}
+export interface CustomToolCallItem {
+    call_id: string;
+    name: string;
+    input: string;
+    namespace?: string;
+}
+type Phase = "commentary" | "partial_answer" | "final_answer";
+export declare function usageJson(usage: Usage): Record<string, unknown>;
+export declare class ResponseWriter {
+    private id;
+    private readonly sink;
+    private readonly model;
+    private readonly showSummary;
+    private seq;
+    private nextOutputIndex;
+    private readonly output;
+    private message;
+    private reasoning;
+    private pendingMessage;
+    private calls;
+    private suffix;
+    private suffixOutputStart;
+    private native;
+    private nativeEnd;
+    private started;
+    private finished;
+    constructor(sink: Sink, opts: {
+        model: string;
+        showSummary?: boolean;
+        responseId?: string;
+    });
+    get responseId(): string;
+    get nativeResponse(): Record<string, any> | undefined;
+    get outputItems(): readonly Record<string, any>[];
+    get isFinished(): boolean;
+    get hasOutput(): boolean;
+    private write;
+    private send;
+    private emit;
+    private holdSuffix;
+    private releaseSuffix;
+    private discardSuffix;
+    private responseObject;
+    start(): void;
+    /** An event that codeks ignores but that resets its stream idle timer. */
+    keepalive(): void;
+    /** Native Responses events retain their own ids, envelopes and metadata. */
+    useNativeResponses(): void;
+    nativeEvent(event: Record<string, any>): void;
+    nativeFailed(response: Record<string, any>, event?: Record<string, any>): void;
+    nativeIncomplete(response: Record<string, any>, event?: Record<string, any>): void;
+    private nativeFailure;
+    private openReasoning;
+    startReasoningSummary(summaryIndex?: number): void;
+    reasoningDelta(text: string, summaryIndex?: number): void;
+    endReasoningSummary(summaryIndex?: number, text?: string): void;
+    /** Closes the open reasoning item (opening one if needed) with its carrier. */
+    endReasoning(encryptedContent: string | undefined, summary?: Array<{
+        type: "summary_text";
+        text: string;
+    }>): void;
+    get reasoningOpen(): boolean;
+    textDelta(text: string, phase?: Phase): void;
+    /** Ends the current text block. Its done event waits until the phase is known. */
+    closeMessage(phase?: Phase): void;
+    private flushPendingMessage;
+    addFunctionCall(call: FunctionCallItem): void;
+    addCustomToolCall(call: CustomToolCallItem): void;
+    private addTool;
+    get toolCallCount(): number;
+    /** Emits a complete item as-is (added and done together). */
+    addItem(item: Record<string, unknown>): void;
+    private flushAll;
+    complete(usage: Usage | undefined, endTurn?: boolean): void;
+    /** Fails the response. Tool calls that were not emitted yet are dropped. */
+    fail(error: Record<string, unknown>): void;
+    incomplete(reason: string, usage: Usage | undefined): void;
+}
+export {};