@fusionkit/model-gateway 0.1.0

package/dist/provenance.js

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+import { artifactHash, assertModelCallRecordV1, MODEL_FUSION_SCHEMA_BUNDLE_HASH, requestHash, responseHash } from "@fusionkit/protocol";
+export const MODEL_CALL_ID_HEADER = "x-velum-model-call-id";
+function asObject(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function requestMessages(body) {
+    const obj = asObject(body);
+    const messages = obj?.messages;
+    if (Array.isArray(messages)) {
+        const projected = messages
+            .map((message) => {
+            const item = asObject(message);
+            if (item === undefined)
+                return undefined;
+            const role = item?.role;
+            if (role !== "system" &&
+                role !== "user" &&
+                role !== "assistant" &&
+                role !== "tool") {
+                return undefined;
+            }
+            return {
+                role,
+                content: requestHash(item.content ?? "")
+            };
+        })
+            .filter((message) => message !== undefined);
+        if (projected.length > 0)
+            return projected;
+    }
+    return [{ role: "user", content: requestHash(body) }];
+}
+function parseJson(buffer) {
+    if (buffer === undefined || buffer.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(buffer.toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function responseText(buffer) {
+    return buffer?.toString("utf8") ?? "";
+}
+function usageFromObject(value) {
+    const obj = asObject(value);
+    const usage = asObject(obj?.usage);
+    if (usage === undefined)
+        return undefined;
+    const prompt = typeof usage.prompt_tokens === "number"
+        ? usage.prompt_tokens
+        : typeof usage.input_tokens === "number"
+            ? usage.input_tokens
+            : undefined;
+    const completion = typeof usage.completion_tokens === "number"
+        ? usage.completion_tokens
+        : typeof usage.output_tokens === "number"
+            ? usage.output_tokens
+            : undefined;
+    const total = typeof usage.total_tokens === "number"
+        ? usage.total_tokens
+        : prompt !== undefined && completion !== undefined
+            ? prompt + completion
+            : undefined;
+    if (prompt === undefined && completion === undefined && total === undefined) {
+        return undefined;
+    }
+    return {
+        ...(prompt !== undefined ? { prompt_tokens: prompt } : {}),
+        ...(completion !== undefined ? { completion_tokens: completion } : {}),
+        ...(total !== undefined ? { total_tokens: total } : {})
+    };
+}
+function usageFromSse(text) {
+    let usage;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("data:"))
+            continue;
+        const payload = trimmed.slice(5).trim();
+        if (payload === "[DONE]")
+            continue;
+        const parsed = parseJson(Buffer.from(payload));
+        const candidate = usageFromObject(parsed);
+        if (candidate !== undefined)
+            usage = candidate;
+    }
+    return usage;
+}
+function usageFromResponse(body) {
+    const parsed = parseJson(body);
+    return usageFromObject(parsed) ?? usageFromSse(responseText(body));
+}
+function observedModel(body) {
+    return stringValue(asObject(parseJson(body))?.model);
+}
+function providerRequestId(body) {
+    return stringValue(asObject(parseJson(body))?.id);
+}
+function errorKind(statusCode, error) {
+    if (statusCode === 408)
+        return "timeout";
+    if (statusCode === 429)
+        return "rate_limited";
+    if (error !== undefined)
+        return "provider_error";
+    if (statusCode >= 400)
+        return "provider_error";
+    return "none";
+}
+function statusFor(statusCode, error) {
+    return statusCode >= 200 && statusCode < 400 && error === undefined ? "succeeded" : "failed";
+}
+export function buildModelCallRecord(context, result) {
+    const usage = usageFromResponse(result.responseBody);
+    const status = statusFor(result.statusCode, result.error);
+    const metadata = {
+        dialect: context.dialect,
+        stream: context.stream,
+        http_status: result.statusCode,
+        duration_ms: result.durationMs,
+        requested_model: context.requestedModel ?? null,
+        observed_model: observedModel(result.responseBody) ?? null,
+        unknown_usage: usage === undefined,
+        unknown_cost: true
+    };
+    const error = status === "failed"
+        ? {
+            kind: errorKind(result.statusCode, result.error),
+            message: result.error instanceof Error
+                ? result.error.message
+                : result.error !== undefined
+                    ? String(result.error)
+                    : responseText(result.responseBody).slice(0, 500),
+            retryable: result.statusCode >= 500
+        }
+        : undefined;
+    const record = {
+        schema: "model-call-record.v1",
+        schema_version: "v1",
+        schema_bundle_hash: MODEL_FUSION_SCHEMA_BUNDLE_HASH,
+        producer: "handoffkit-model-gateway",
+        producer_version: "0.1.0",
+        producer_git_sha: "0".repeat(40),
+        created_at: context.startedAt,
+        call_id: context.callId,
+        endpoint_id: context.endpointId ?? context.dialect,
+        ...(providerRequestId(result.responseBody)
+            ? { provider_request_id: providerRequestId(result.responseBody) }
+            : {}),
+        model: context.model ?? context.requestedModel ?? "unknown",
+        request_hash: requestHash(context.requestBody),
+        ...(result.responseBody !== undefined
+            ? { response_hash: responseHash(responseText(result.responseBody)) }
+            : {}),
+        messages: requestMessages(context.requestBody),
+        status,
+        side_effects: "none",
+        started_at: context.startedAt,
+        finished_at: new Date(new Date(context.startedAt).getTime() + result.durationMs).toISOString(),
+        latency_ms: result.durationMs,
+        ...(usage !== undefined ? { usage } : {}),
+        ...(error !== undefined ? { error } : {}),
+        metadata
+    };
+    assertModelCallRecordV1(record);
+    return record;
+}
+export function modelCallId() {
+    return `model_call_${randomUUID()}`;
+}
+export function responseBodyHash(body) {
+    return artifactHash(body);
+}

package/dist/server.d.ts

@@ -0,0 +1,27 @@
+import type { Backend } from "./backend.js";
+import type { ProvenanceSink } from "./provenance.js";
+/**
+ * The local-model gateway HTTP server. It fronts a single OpenAI Chat
+ * Completions backend (the owned mlx fork by default) and exposes the wire
+ * dialects each agent harness needs. M1 implements the OpenAI chat surface
+ * (opencode, Cursor IDE plan panel); the Anthropic Messages and OpenAI
+ * Responses adapters return 501 until M2/M3 land.
+ */
+export type GatewayOptions = {
+    backend: Backend;
+    /** Bind host; defaults to loopback. */
+    host?: string;
+    /** Bind port; defaults to an ephemeral free port. */
+    port?: number;
+    /** When set, require this bearer token (or matching `x-api-key`). */
+    authToken?: string;
+    /** Optional observation sink for model calls. */
+    provenance?: ProvenanceSink;
+};
+export type Gateway = {
+    /** Base URL clients should target (without the `/v1` suffix). */
+    url(): string;
+    port(): number;
+    close(): Promise<void>;
+};
+export declare function startGateway(options: GatewayOptions): Promise<Gateway>;

package/dist/server.js

@@ -0,0 +1,234 @@
+import { once } from "node:events";
+import { createServer } from "node:http";
+import { anthropicModelsResponse, handleAnthropicMessages, handleCountTokens } from "./adapters/anthropic.js";
+import { effectiveModel, isStream, withDefaultModel } from "./adapters/chat.js";
+import { handleResponses } from "./adapters/responses.js";
+import { buildModelCallRecord, MODEL_CALL_ID_HEADER, modelCallId } from "./provenance.js";
+export async function startGateway(options) {
+    const host = options.host ?? "127.0.0.1";
+    const { backend, authToken, provenance } = options;
+    const server = createServer((req, res) => {
+        void handle(req, res).catch((error) => {
+            writeJson(res, 502, {
+                error: { message: errorMessage(error), type: "upstream_error" }
+            });
+        });
+    });
+    async function handle(req, res) {
+        const method = req.method ?? "GET";
+        const path = new URL(req.url ?? "/", "http://localhost").pathname;
+        if (path === "/health") {
+            writeJson(res, 200, { status: "ok" });
+            return;
+        }
+        if (authToken !== undefined && !authorized(req, authToken)) {
+            writeJson(res, 401, { error: { message: "unauthorized", type: "auth_error" } });
+            return;
+        }
+        if (method === "GET" && (path === "/v1/models" || path === "/models")) {
+            // Claude Code's discovery probe carries `anthropic-version` and expects
+            // the Anthropic-shaped model list; everyone else gets the OpenAI shape.
+            if (req.headers["anthropic-version"] !== undefined) {
+                await pipeUpstream(res, anthropicModelsResponse(backend.defaultModel));
+                return;
+            }
+            await pipeUpstream(res, await backend.models());
+            return;
+        }
+        if (method === "POST" && (path === "/v1/chat/completions" || path === "/chat/completions")) {
+            const raw = await readJson(req, res);
+            if (raw === NO_BODY)
+                return;
+            const body = withDefaultModel(raw, backend.defaultModel);
+            await handleModelCall(res, provenance, {
+                dialect: "openai-chat",
+                body,
+                defaultModel: backend.defaultModel,
+                invoke: (callId, signal) => backend.chat(body, signal, { modelCallId: callId })
+            });
+            return;
+        }
+        if (method === "POST" && path === "/v1/embeddings") {
+            const raw = await readJson(req, res);
+            if (raw === NO_BODY)
+                return;
+            await pipeUpstream(res, await backend.embeddings(withDefaultModel(raw, backend.defaultModel)));
+            return;
+        }
+        if (method === "POST" && path === "/v1/messages/count_tokens") {
+            const raw = await readJson(req, res);
+            if (raw === NO_BODY)
+                return;
+            await pipeUpstream(res, handleCountTokens(raw));
+            return;
+        }
+        if (method === "POST" && path === "/v1/messages") {
+            const raw = await readJson(req, res);
+            if (raw === NO_BODY)
+                return;
+            const body = raw;
+            await handleModelCall(res, provenance, {
+                dialect: "anthropic-messages",
+                body,
+                defaultModel: backend.defaultModel,
+                invoke: (callId, signal) => handleAnthropicMessages(backend, body, callId, signal)
+            });
+            return;
+        }
+        if (method === "POST" && path === "/v1/responses") {
+            const raw = await readJson(req, res);
+            if (raw === NO_BODY)
+                return;
+            const body = raw;
+            await handleModelCall(res, provenance, {
+                dialect: "openai-responses",
+                body,
+                defaultModel: backend.defaultModel,
+                invoke: (callId, signal) => handleResponses(backend, body, callId, signal)
+            });
+            return;
+        }
+        writeJson(res, 404, { error: { message: `no route for ${method} ${path}`, type: "not_found" } });
+    }
+    await new Promise((resolve, reject) => {
+        const onError = (error) => reject(error);
+        server.once("error", onError);
+        server.listen(options.port ?? 0, host, () => {
+            server.off("error", onError);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address !== null ? address.port : options.port ?? 0;
+    return {
+        url: () => `http://${host}:${port}`,
+        port: () => port,
+        close: async () => {
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+            });
+            // Release a backend that owns a process (e.g. the MLX server) instead of
+            // leaking it when the gateway shuts down.
+            await backend.close?.();
+        }
+    };
+}
+// ---- HTTP helpers (Node built-ins only) ----
+const NO_BODY = Symbol("no-body");
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+/**
+ * Read and parse a JSON request body. On malformed JSON, write a 400 and
+ * return the NO_BODY sentinel so the caller stops processing.
+ */
+async function readJson(req, res) {
+    const buffer = await readBody(req);
+    if (buffer.length === 0)
+        return {};
+    try {
+        return JSON.parse(buffer.toString("utf8"));
+    }
+    catch {
+        writeJson(res, 400, { error: { message: "invalid JSON body", type: "bad_request" } });
+        return NO_BODY;
+    }
+}
+function writeJson(res, status, value) {
+    const payload = Buffer.from(JSON.stringify(value), "utf8");
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.setHeader("content-length", String(payload.byteLength));
+    res.end(payload);
+    return payload;
+}
+async function handleModelCall(res, sink, route) {
+    const callId = modelCallId();
+    const started = Date.now();
+    const startedAt = new Date(started).toISOString();
+    const context = {
+        callId,
+        dialect: route.dialect,
+        requestedModel: effectiveModel(route.body, route.defaultModel),
+        model: effectiveModel(route.body, route.defaultModel),
+        stream: isStream(route.body),
+        requestBody: route.body,
+        startedAt,
+        endpointId: route.defaultModel ?? route.dialect
+    };
+    res.setHeader(MODEL_CALL_ID_HEADER, callId);
+    // Cancel upstream work if the client hangs up before we finish responding.
+    const aborter = new AbortController();
+    const onClose = () => {
+        if (!res.writableEnded)
+            aborter.abort();
+    };
+    res.once("close", onClose);
+    try {
+        const upstream = await route.invoke(callId, aborter.signal);
+        const body = await pipeUpstream(res, upstream);
+        sink?.onModelCall?.(buildModelCallRecord(context, {
+            statusCode: upstream.status,
+            responseBody: body,
+            durationMs: Date.now() - started
+        }));
+    }
+    catch (error) {
+        const statusCode = 502;
+        const payload = writeJson(res, statusCode, {
+            error: { message: errorMessage(error), type: "upstream_error" }
+        });
+        sink?.onModelCall?.(buildModelCallRecord(context, {
+            statusCode,
+            responseBody: payload,
+            durationMs: Date.now() - started,
+            error
+        }));
+    }
+    finally {
+        res.off("close", onClose);
+    }
+}
+async function pipeUpstream(res, upstream) {
+    res.statusCode = upstream.status;
+    const contentType = upstream.headers.get("content-type");
+    if (contentType !== null)
+        res.setHeader("content-type", contentType);
+    const body = upstream.body;
+    if (body === null) {
+        res.end();
+        return Buffer.alloc(0);
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value !== undefined) {
+                const chunk = Buffer.from(value);
+                chunks.push(chunk);
+                if (!res.write(chunk))
+                    await once(res, "drain");
+            }
+        }
+    }
+    finally {
+        res.end();
+    }
+    return Buffer.concat(chunks);
+}
+function authorized(req, token) {
+    const auth = req.headers.authorization;
+    if (typeof auth === "string" && auth === `Bearer ${token}`)
+        return true;
+    const apiKey = req.headers["x-api-key"];
+    return typeof apiKey === "string" && apiKey === token;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/test/acp-agent.test.d.ts

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

package/dist/test/acp-agent.test.js

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { PassThrough } from "node:stream";
+import { test } from "node:test";
+import { runAcpAgent } from "../acp-agent.js";
+async function driveAgent(runner, requests) {
+    const input = new PassThrough();
+    const output = new PassThrough();
+    let raw = "";
+    output.on("data", (chunk) => {
+        raw += chunk.toString("utf8");
+    });
+    const done = runAcpAgent({ runner, input, output });
+    for (const request of requests) {
+        input.write(`${JSON.stringify(request)}\n`);
+    }
+    input.end();
+    await done;
+    return raw
+        .split("\n")
+        .filter((line) => line.trim().length > 0)
+        .map((line) => JSON.parse(line));
+}
+test("acp agent completes initialize, session/new, and session/prompt", async () => {
+    const runner = async (input) => ({
+        finalOutput: `FUSION_OK:${input.prompt}`,
+        runId: "run_acp_1",
+        status: "succeeded",
+        evidence: ["patch_artifact", "judge_synthesis"]
+    });
+    const messages = await driveAgent(runner, [
+        { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: 1 } },
+        { jsonrpc: "2.0", id: 2, method: "session/new", params: { cwd: "/tmp", mcpServers: [] } },
+        {
+            jsonrpc: "2.0",
+            id: 3,
+            method: "session/prompt",
+            params: { sessionId: "sess_1", prompt: [{ type: "text", text: "patch the bug" }] }
+        }
+    ]);
+    const initialize = messages.find((message) => message.id === 1);
+    assert.ok(initialize?.result);
+    assert.equal(initialize.result.protocolVersion, 1);
+    const sessionNew = messages.find((message) => message.id === 2);
+    assert.equal((sessionNew?.result).sessionId, "sess_1");
+    const update = messages.find((message) => message.method === "session/update");
+    assert.ok(update);
+    const updateParams = update.params;
+    assert.match(updateParams.update.content.text, /FUSION_OK:patch the bug/);
+    const promptResult = messages.find((message) => message.id === 3);
+    const result = promptResult?.result;
+    assert.equal(result.stopReason, "end_turn");
+    assert.equal(result._meta.runId, "run_acp_1");
+});
+test("acp agent returns method-not-found for unknown methods", async () => {
+    const runner = async () => ({
+        finalOutput: "unused",
+        runId: "run",
+        status: "succeeded",
+        evidence: []
+    });
+    const messages = await driveAgent(runner, [
+        { jsonrpc: "2.0", id: 9, method: "nonsense/method", params: {} }
+    ]);
+    const error = messages.find((message) => message.id === 9);
+    assert.equal(error?.error?.code, -32601);
+});

package/dist/test/acp-registry.test.d.ts

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

package/dist/test/acp-registry.test.js

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fetchAcpRegistry, installAcpAdapters } from "../acp-registry.js";
+const FAKE_REGISTRY = {
+    agents: [
+        {
+            id: "codex-cli",
+            name: "Codex CLI",
+            version: "0.16.0",
+            description: "ACP adapter for OpenAI's coding assistant",
+            distribution: { type: "npm", package: "@zed-industries/codex-acp" }
+        },
+        {
+            id: "claude-agent",
+            name: "Claude Agent",
+            version: "0.46.0",
+            description: "ACP wrapper for Anthropic's Claude",
+            distribution: { type: "npm", package: "@agentclientprotocol/claude-agent-acp" }
+        },
+        {
+            id: "no-distribution",
+            name: "Broken",
+            version: "1.0.0"
+        }
+    ]
+};
+function fakeFetcher(payload = FAKE_REGISTRY) {
+    return async () => payload;
+}
+test("fetchAcpRegistry normalizes agent metadata", async () => {
+    const registry = await fetchAcpRegistry(fakeFetcher());
+    const ids = registry.agents.map((agent) => agent.id);
+    assert.ok(ids.includes("codex-cli"));
+    assert.ok(ids.includes("claude-agent"));
+});
+test("installAcpAdapters writes metadata for known agents", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "acp-registry-"));
+    try {
+        const installed = await installAcpAdapters({
+            agentIds: ["codex-cli", "claude-agent"],
+            installDir: dir,
+            fetcher: fakeFetcher()
+        });
+        assert.equal(installed.length, 2);
+        const codex = JSON.parse(readFileSync(join(dir, "codex-cli.json"), "utf8"));
+        assert.equal(codex.id, "codex-cli");
+        assert.equal(codex.version, "0.16.0");
+        assert.equal(codex.distribution.package, "@zed-industries/codex-acp");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("installAcpAdapters rejects unknown ids and missing distribution", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "acp-registry-"));
+    try {
+        await assert.rejects(() => installAcpAdapters({ agentIds: ["missing"], installDir: dir, fetcher: fakeFetcher() }), /no agent with id "missing"/);
+        await assert.rejects(() => installAcpAdapters({
+            agentIds: ["no-distribution"],
+            installDir: dir,
+            fetcher: fakeFetcher()
+        }), /no distribution metadata/);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

package/dist/test/anthropic.test.d.ts

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