@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/mcp-server/index.d.ts

@@ -0,0 +1,85 @@
+/** GETs a gateway path; the CLI supplies it with BLACKBOX_URL + the key. */
+export type Get = (path: string) => Promise<{
+    status: number;
+    text: string;
+}>;
+export declare const TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+            };
+        };
+        required?: never;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            session_id: {
+                type: string;
+                description: string;
+            };
+            limit?: never;
+            lang: {
+                type: string;
+                enum: string[];
+                default: string;
+            };
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {};
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            session_id: {
+                type: string;
+                description: string;
+            };
+            after_seq: {
+                type: string;
+                minimum: number;
+                default: number;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+            };
+        };
+        required: string[];
+    };
+})[];
+type Result = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: boolean;
+};
+/** One tools/call. Never throws: failures are `isError` results. */
+export declare function callTool(get: Get, name: unknown, args: unknown): Promise<Result>;
+/** Answers one JSON-RPC line; undefined for a notification. */
+export declare function handleLine(get: Get, line: string): Promise<object | undefined>;
+/** Serves stdin → stdout until stdin closes; one request at a time, in order. */
+export declare function serveMcp(get: Get): Promise<number>;
+export {};

package/dist/mcp-server/index.js

@@ -0,0 +1,216 @@
+// The Blackbox MCP server (spec/mcp-server.md): read-only tools over the gateway's API, on stdio.
+// Mirrors sdks/python/src/zanii_blackbox/mcp_server.py.
+import { createInterface } from "node:readline";
+const SESSION_ID = /^ses_[A-Za-z0-9]{16,64}$/;
+const sid = {
+    type: "object",
+    properties: { session_id: { type: "string", description: "A session id (ses_…)" } },
+    required: ["session_id"],
+};
+const none = { type: "object", properties: {} };
+export const TOOLS = [
+    {
+        name: "list_sessions",
+        description: "The newest agent sessions the flight recorder holds.",
+        inputSchema: {
+            type: "object",
+            properties: { limit: { type: "integer", minimum: 1, maximum: 200, default: 20 } },
+        },
+    },
+    {
+        name: "session_summary",
+        description: "A session's handoff brief: objective, status, calls, tools, spend, findings, claims.",
+        inputSchema: sid,
+    },
+    {
+        name: "verify_session",
+        description: "Whether a session's record verifies: the hash chain, its anchors, its final count.",
+        inputSchema: sid,
+    },
+    {
+        name: "incident_report",
+        description: "A session's incident report in Markdown, in English or Arabic.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...sid.properties,
+                lang: { type: "string", enum: ["en", "ar"], default: "en" },
+            },
+            required: ["session_id"],
+        },
+    },
+    {
+        name: "fleet",
+        description: "The open sessions right now: the fleet radar.",
+        inputSchema: none,
+    },
+    {
+        name: "collisions",
+        description: "Resources that two or more open sessions are changing at once.",
+        inputSchema: none,
+    },
+    {
+        name: "logbook",
+        description: "Per agent label: outcomes, warnings, near misses, exceedances, spend.",
+        inputSchema: none,
+    },
+    // audit, also found: more of the read API, for an assistant helping with an incident
+    {
+        name: "session_findings",
+        description: "A session's findings: fault codes, severities, where in the record.",
+        inputSchema: sid,
+    },
+    {
+        name: "session_cost",
+        description: "A session's cost, call by call, in micro-USD and AED.",
+        inputSchema: sid,
+    },
+    {
+        name: "session_state",
+        description: "A session right now: open or closed, blocked or not, who has the controls.",
+        inputSchema: sid,
+    },
+    {
+        name: "session_events",
+        description: "A session's recorded events (NDJSON), from after_seq, at most limit of them.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...sid.properties,
+                after_seq: { type: "integer", minimum: -1, default: -1 },
+                limit: { type: "integer", minimum: 1, maximum: 1000, default: 200 },
+            },
+            required: ["session_id"],
+        },
+    },
+    {
+        name: "weather",
+        description: "Each provider and model's error rate and latency over the last minutes.",
+        inputSchema: none,
+    },
+];
+const text = (t, isError = false) => ({
+    content: [{ type: "text", text: t }],
+    isError,
+});
+/** One tools/call. Never throws: failures are `isError` results. */
+export async function callTool(get, name, args) {
+    const a = (typeof args === "object" && args !== null ? args : {});
+    const id = a.session_id;
+    const needsId = [
+        "session_summary",
+        "verify_session",
+        "incident_report",
+        "session_findings",
+        "session_cost",
+        "session_state",
+        "session_events",
+    ].includes(String(name));
+    if (needsId && !(typeof id === "string" && SESSION_ID.test(id)))
+        return text("session_id must be a session id (ses_…)", true);
+    let path;
+    if (name === "list_sessions") {
+        const limit = a.limit ?? 20;
+        if (!(Number.isSafeInteger(limit) && limit >= 1 && limit <= 200))
+            return text("limit must be an integer 1-200", true);
+        path = `/v1/sessions?limit=${limit}`;
+    }
+    else if (name === "session_summary")
+        path = `/v1/sessions/${id}/summary`;
+    else if (name === "verify_session")
+        path = `/v1/sessions/${id}`;
+    else if (name === "incident_report") {
+        const lang = a.lang ?? "en";
+        if (lang !== "en" && lang !== "ar")
+            return text("lang must be en or ar", true);
+        path = `/v1/sessions/${id}/incident?lang=${lang}`;
+    }
+    else if (name === "fleet")
+        path = "/v1/fleet";
+    else if (name === "collisions")
+        path = "/v1/fleet/collisions";
+    else if (name === "logbook")
+        path = "/v1/logbook";
+    else if (name === "session_findings")
+        path = `/v1/sessions/${id}/findings`;
+    else if (name === "session_cost")
+        path = `/v1/sessions/${id}/cost`;
+    else if (name === "session_state")
+        path = `/v1/sessions/${id}/state`;
+    else if (name === "session_events") {
+        const after = a.after_seq ?? -1;
+        const limit = a.limit ?? 200;
+        if (!(Number.isSafeInteger(after) && after >= -1))
+            return text("after_seq must be an integer >= -1", true);
+        if (!(Number.isSafeInteger(limit) && limit >= 1 && limit <= 1000))
+            return text("limit must be an integer 1-1000", true);
+        path = `/v1/sessions/${id}/events?after_seq=${after}&limit=${limit}`;
+    }
+    else if (name === "weather")
+        path = "/v1/weather";
+    else
+        return text(`unknown tool: ${String(name)}`, true);
+    let res;
+    try {
+        res = await get(path);
+    }
+    catch (error) {
+        return text(error instanceof Error ? error.message : String(error), true);
+    }
+    if (res.status < 200 || res.status > 299)
+        return text(`HTTP ${res.status}: ${res.text}`, true);
+    if (name === "incident_report" || name === "session_events")
+        return text(res.text);
+    const doc = JSON.parse(res.text);
+    const out = name === "verify_session"
+        ? {
+            session_id: doc.session_id,
+            events: doc.events,
+            verification: doc.verification,
+            anchor_status: doc.anchor_status,
+        }
+        : doc;
+    return text(JSON.stringify(out, null, 2));
+}
+/** Answers one JSON-RPC line; undefined for a notification. */
+export async function handleLine(get, line) {
+    let msg;
+    try {
+        msg = JSON.parse(line);
+    }
+    catch {
+        return { jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } };
+    }
+    if (typeof msg !== "object" || msg === null || !("id" in msg))
+        return undefined;
+    const reply = (result) => ({ jsonrpc: "2.0", id: msg.id, result });
+    if (msg.method === "initialize")
+        return reply({
+            protocolVersion: "2025-06-18",
+            capabilities: { tools: {} },
+            serverInfo: { name: "zanii-blackbox", version: "1" },
+        });
+    if (msg.method === "ping")
+        return reply({});
+    if (msg.method === "tools/list")
+        return reply({ tools: TOOLS });
+    if (msg.method === "tools/call")
+        return reply(await callTool(get, msg.params?.name, msg.params?.arguments));
+    return {
+        jsonrpc: "2.0",
+        id: msg.id,
+        error: { code: -32601, message: `method not found: ${String(msg.method)}` },
+    };
+}
+/** Serves stdin → stdout until stdin closes; one request at a time, in order. */
+export async function serveMcp(get) {
+    const lines = createInterface({ input: process.stdin, crlfDelay: Number.POSITIVE_INFINITY });
+    for await (const line of lines) {
+        if (line.trim() === "")
+            continue;
+        const out = await handleLine(get, line);
+        if (out)
+            process.stdout.write(`${JSON.stringify(out)}\n`);
+    }
+    return 0;
+}

package/dist/mcp-wrap/index.d.ts

@@ -0,0 +1,17 @@
+import type { Readable, Writable } from "node:stream";
+export interface McpWrapOptions {
+    /** The name recorded as `meta.server`. */
+    server: string;
+    /** The real MCP server: command and arguments. */
+    command: string[];
+    /** The gateway, e.g. http://127.0.0.1:8787 */
+    gatewayUrl: string;
+    /** The session token. Never passed to the MCP server. */
+    token: string;
+    env?: NodeJS.ProcessEnv;
+    stdin?: Readable;
+    stdout?: Writable;
+    stderr?: Writable;
+}
+/** Resolves with the MCP server's exit code once both sides are done. */
+export declare function mcpWrap(options: McpWrapOptions): Promise<number>;

package/dist/mcp-wrap/index.js

@@ -0,0 +1,170 @@
+// mcp-wrap (spec/mcp.md §5): runs a local stdio MCP server and records every JSON-RPC line through
+// the gateway before relaying it. Mirrors sdks/python/src/zanii_blackbox/mcp_wrap.py.
+import { spawn } from "node:child_process";
+import { Agent as HttpAgent, request as httpRequest } from "node:http";
+import { Agent as HttpsAgent, request as httpsRequest } from "node:https";
+const NAME = /^[a-z][a-z0-9-]{0,31}$/;
+const NL = Buffer.from("\n");
+/** Resolves with the MCP server's exit code once both sides are done. */
+export async function mcpWrap(options) {
+    const { server, command, gatewayUrl, token } = options;
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    if (!NAME.test(server))
+        throw new Error(`invalid --server name "${server}"`);
+    const [file, ...args] = command;
+    if (!file)
+        throw new Error("no MCP server command given");
+    const env = { ...(options.env ?? process.env) };
+    // The MCP server is third-party code: it gets none of Blackbox's settings or secrets (the session
+    // token, an admin key, provider keys).
+    for (const k of Object.keys(env))
+        if (k.startsWith("BLACKBOX_"))
+            delete env[k];
+    // Windows can only start .cmd launchers (npx, uvx) through a shell; quote so arguments survive it.
+    const child = process.platform === "win32"
+        ? spawn([file, ...args].map(quoteWindows).join(" "), {
+            shell: true,
+            env,
+            stdio: ["pipe", "pipe", "inherit"],
+        })
+        : spawn(file, args, { env, stdio: ["pipe", "pipe", "inherit"] });
+    child.stdin.on("error", () => { }); // the server exited early; its exit code tells the story
+    const exited = new Promise((resolve) => {
+        child.on("error", (error) => {
+            stderr.write(`blackbox mcp-wrap: could not start the MCP server: ${error.message}\n`);
+            resolve(127);
+        });
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+    const base = new URL(gatewayUrl);
+    const agent = base.protocol === "https:"
+        ? new HttpsAgent({ keepAlive: true })
+        : new HttpAgent({ keepAlive: true });
+    const send = base.protocol === "https:" ? httpsRequest : httpRequest;
+    const endpoint = (d) => new URL(`${base.pathname.replace(/\/$/, "")}/v1/mcp-stdio/${server}/${d}`, base);
+    // L1.4.5: the session's mode (from the gateway's answers) and what we relayed unrecorded.
+    let mode = null;
+    let missed = 0;
+    let missedSince = "";
+    const UNREACHABLE = "the gateway could not be reached";
+    const record = (d, line) => new Promise((resolve) => {
+        const req = send(endpoint(d), {
+            method: "POST",
+            agent,
+            timeout: 30_000,
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+                "content-length": line.length,
+                ...(missed > 0
+                    ? { "x-blackbox-missed": String(missed), "x-blackbox-missed-since": missedSince }
+                    : {}),
+            },
+        });
+        req.on("response", (res) => {
+            const parts = [];
+            res.on("data", (d) => parts.push(d));
+            res.on("end", () => {
+                if (res.statusCode === 204) {
+                    const m = res.headers["x-blackbox-mode"];
+                    if (typeof m === "string")
+                        mode = m;
+                    missed = 0; // the gateway recorded the gap before this line
+                    return resolve(null);
+                }
+                // A call the gateway recorded and refused by policy: relay its JSON-RPC error (spec/policy.md §2).
+                if (res.statusCode === 403)
+                    try {
+                        const rpc = JSON.parse(Buffer.concat(parts).toString("utf8")).rpc_error;
+                        if (rpc && typeof rpc === "object")
+                            return resolve({ rpcError: rpc });
+                    }
+                    catch { }
+                resolve(`the gateway answered ${res.statusCode}`);
+            });
+        });
+        req.on("timeout", () => req.destroy(new Error("timed out")));
+        req.on("error", (error) => resolve(`${UNREACHABLE} (${error.message})`));
+        req.end(line);
+    });
+    const write = (target, data) => new Promise((resolve) => {
+        if (target.destroyed || target.writableEnded)
+            return resolve();
+        target.write(data, () => resolve());
+    });
+    // One queue for both directions: the record's order is the order lines arrived in.
+    let queue = Promise.resolve();
+    const relay = (d, line, newline) => {
+        queue = queue.then(async () => {
+            const target = d === "client" ? child.stdin : stdout;
+            const out = newline ? Buffer.concat([line, NL]) : line;
+            if (line.toString().trim() === "")
+                return write(target, out);
+            const failure = await record(d, line);
+            if (failure === null)
+                return write(target, out);
+            // An `available` session keeps working when the gateway is down; the gap is recorded later.
+            if (mode === "available" && typeof failure === "string" && failure.startsWith(UNREACHABLE)) {
+                if (missed === 0) {
+                    missedSince = new Date().toISOString();
+                    stderr.write(`blackbox mcp-wrap: ${failure}; relaying unrecorded (available session)\n`);
+                }
+                missed++;
+                return write(target, out);
+            }
+            stderr.write(typeof failure === "string"
+                ? `blackbox mcp-wrap: a ${d} message was not recorded, so not relayed: ${failure}\n`
+                : `blackbox mcp-wrap: a ${d} message was refused by the gateway's policy\n`);
+            const reply = refusal(d, line, failure);
+            if (reply)
+                await write(stdout, reply);
+        });
+    };
+    const done = (d, source) => new Promise((resolve) => {
+        let pending = Buffer.alloc(0);
+        source.on("data", (chunk) => {
+            pending = Buffer.concat([pending, chunk]);
+            for (let i = pending.indexOf(0x0a); i >= 0; i = pending.indexOf(0x0a)) {
+                relay(d, pending.subarray(0, i), true);
+                pending = pending.subarray(i + 1);
+            }
+        });
+        source.on("end", () => {
+            if (pending.length > 0)
+                relay(d, pending, false);
+            resolve();
+        });
+    });
+    void done("client", stdin).then(() => queue.then(() => child.stdin.end()));
+    await done("server", child.stdout);
+    const code = await exited;
+    await queue;
+    stdin.destroy(); // the server is gone: stop reading, or the open stdin keeps the process alive
+    agent.destroy();
+    return code;
+}
+/** What the agent gets instead of a message that couldn't be recorded (spec/mcp.md §5). */
+function refusal(d, line, reason) {
+    let message;
+    try {
+        message = JSON.parse(line.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof message !== "object" || message === null || !("id" in message))
+        return null;
+    const isRequest = "method" in message;
+    const isResponse = "result" in message || "error" in message;
+    if ((d === "client" && !isRequest) || (d === "server" && !isResponse))
+        return null;
+    const error = typeof reason === "string"
+        ? { code: -32001, message: `blackbox: not recorded, so not relayed (${reason})` }
+        : reason.rpcError;
+    return Buffer.from(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, error })}\n`);
+}
+function quoteWindows(arg) {
+    return /^[\w\-./:=@\\]+$/.test(arg) ? arg : `"${arg.replace(/"/g, '""')}"`;
+}

package/dist/money/index.d.ts

@@ -0,0 +1,114 @@
+import { type LoadedPrices } from "../cost/index.ts";
+import type { Summary } from "../fleet/index.ts";
+/** `{model: micro_usd}` over the priced calls, sorted by model. */
+export declare function modelSpend(lines: readonly string[], prices: LoadedPrices): Record<string, number>;
+export interface Statement {
+    lines: Array<{
+        model: string;
+        micro_usd: number;
+    }>;
+}
+/** Why a statement is invalid, or undefined. */
+export declare function checkStatement(s: unknown): string | undefined;
+export declare function reconcileBilling(ours: Record<string, number>, statement: Statement, tolerancePpm?: number): {
+    v: 1;
+    tolerance_ppm: number;
+    ours_micro_usd: number;
+    theirs_micro_usd: number;
+    diff_micro_usd: number;
+    ok: boolean;
+    models: {
+        model: string;
+        ours: number;
+        theirs: number;
+        diff: number;
+        status: string;
+    }[];
+};
+export interface Baseline {
+    label: string;
+    successes: number;
+    median_spend_micro_usd: number;
+    p90_spend_micro_usd: number;
+    median_model_calls: number;
+    median_tool_calls: number;
+}
+/** Per label, over successful sessions only (spec/money.md §3). */
+export declare function baselines(summaries: readonly Summary[]): {
+    labels: Baseline[];
+};
+/** Will the remaining budget reach the destination? (spec/money.md §4) */
+export declare function fuel(summary: Summary, budgetMicroUsd: number | null, baseline: Baseline | null): {
+    spent_micro_usd: number;
+    budget_micro_usd: number | null;
+    expected_total_micro_usd: number | null;
+    p90_total_micro_usd: number | null;
+    verdict: string;
+};
+export type AmountUnit = "usd" | "cents" | "micro_usd" | "aed";
+/** spec/money.md §2a-b: an exact decimal amount (string, or a JSON number's text) to integer
+ * micro-USD, rounded half up. `unit` is what the amount counts. */
+export declare function decimalToMicroUsd(value: unknown, unit: AmountUnit): number;
+/** spec/money.md §2a: Anthropic's cost report pages (grouped by description) as a statement. */
+export declare function anthropicStatement(pages: readonly unknown[]): Statement;
+/** spec/money.md §2a: OpenAI's organization costs pages (grouped by line_item) as a statement. */
+export declare function openaiStatement(pages: readonly unknown[]): Statement;
+/** spec/money.md §2b: every value at a path (`a.b[].c`, `[]` alone for a list itself). */
+export declare function resolvePath(value: unknown, path: string): unknown[];
+/** spec/money.md §2b: a CSV export with named columns as a statement. */
+export declare function csvStatement(text: string, opts: {
+    model_column: string;
+    amount_column: string;
+    unit: AmountUnit;
+    delimiter?: string;
+}): Statement;
+export interface Connector {
+    v: 1;
+    name: string;
+    request: {
+        url: string;
+        headers?: Record<string, string>;
+        method?: "GET" | "POST";
+        body?: string;
+        content_type?: string;
+    };
+    results: string;
+    model: string;
+    amount: string;
+    unit: AmountUnit;
+    currency?: {
+        path: string;
+        equals: string;
+    };
+    /** spec/money.md §2b: how responses are read; json by default. */
+    format?: "json" | "xml";
+    next?: {
+        cursor: string;
+        param: string;
+    } | {
+        page_param: string;
+        first_page?: number;
+        size_param?: string;
+        size?: number;
+    } | {
+        offset_param: string;
+        size: number;
+        size_param?: string;
+    };
+}
+/** spec/money.md §2b: why a connector file is invalid, or undefined. */
+export declare function checkConnector(value: unknown): string | undefined;
+/** spec/money.md §2b: pages from a connector's API as a statement. */
+export declare function customStatement(pages: readonly unknown[], connector: Connector): Statement;
+/** spec/money.md §2b: the query parameters for the next request, or null when there are no more. */
+export declare function pageParams(c: Connector, pages: readonly unknown[]): Array<[string, string]> | null;
+/** spec/money.md §2b: XML as `{root: [value]}`. No DTDs, so no external or expanding entities. */
+export declare function parseXml(text: string): Record<string, unknown>;
+/** spec/money.md §2b: the next request a connector makes, or null when there are no more. */
+export declare function requestFor(c: Connector, pages: readonly unknown[], from: string, to: string): {
+    method: "GET" | "POST";
+    url: string;
+    query: Array<[string, string]>;
+    body?: string;
+    content_type?: string;
+} | null;