@zanii/blackbox 0.0.0-stage → 0.1.0

package/dist/investigate/index.js

@@ -0,0 +1,119 @@
+// Investigations (spec/investigations.md): the independent investigator's report and its reading
+// copy. Pure; mirrors sdks/python/src/zanii_blackbox/investigate.py; pinned by
+// spec/vectors/investigations.json.
+import { faultOf } from "../analysis/faults.js";
+import { authorityTimeline } from "../authority/index.js";
+import { drillReport } from "../drills/index.js";
+import { signatureOf } from "../fleet/index.js";
+/** spec/investigations.md §1. */
+export function investigation(lines, opts) {
+    const { summary, models } = opts;
+    const authority = authorityTimeline(lines);
+    const spanAt = (seq) => authority.find((s) => seq >= s.from_seq && (s.to_seq === null || seq <= s.to_seq));
+    const findings = lines
+        .map((l) => JSON.parse(l))
+        .filter((e) => e.kind === "finding")
+        .map((e) => {
+        const code = String(e.meta.code);
+        const ref = e.meta.ref;
+        const span = spanAt(typeof ref?.seq === "number" ? ref.seq : e.seq);
+        return {
+            seq: e.seq,
+            code,
+            fault: faultOf(code).fault,
+            severity: String(e.meta.severity),
+            source: String(e.meta.source),
+            in_control: span?.mode ?? null,
+            in_control_by: span?.by ?? null,
+            weather: e.meta.weather ?? null,
+        };
+    });
+    const signature = signatureOf(summary)?.signature;
+    const matches = (d) => d.signature === signature &&
+        ("model" in d.applies_to
+            ? models.includes(d.applies_to.model)
+            : Object.hasOwn(summary.tools, d.applies_to.tool));
+    const drill = drillReport(lines);
+    return {
+        kind: "blackbox.investigation",
+        v: 1,
+        session_id: summary.session_id,
+        label: summary.label,
+        started_at: summary.started_at,
+        last_event_at: summary.last_event_at,
+        events: summary.events,
+        outcome: summary.outcome,
+        authority,
+        findings,
+        directives: opts.directives
+            ? opts.directives.filter(matches).map((d) => ({
+                id: d.id,
+                applies_to: d.applies_to,
+                pattern: d.pattern,
+                affected_ppm: d.affected_ppm,
+            }))
+            : null,
+        drill: drill.drill ? drill : null,
+    };
+}
+const cell = (v) => v === null || v === undefined || v === ""
+    ? "—"
+    : String(v)
+        .replace(/\r\n|\r|\n/g, " ")
+        .replace(/\|/g, "\\|");
+const row = (cells) => `| ${cells.map(cell).join(" | ")} |`;
+const head = (names) => [row(names), `|${names.map(() => "---|").join("")}`];
+/** spec/investigations.md §3: the reading copy. The signed JSON is the report; this isn't. */
+export function renderInvestigation(r) {
+    const out = [`# Investigation: ${r.session_id}`, "", ...head(["Fact", "Value"])];
+    const v = r.verification;
+    out.push(row(["Label", r.label]), row(["Started", r.started_at]), row(["Last event", r.last_event_at]), row(["Events", r.events]), row(["Outcome", r.outcome]), row([
+        "Record verified",
+        v === undefined
+            ? "not checked"
+            : `${v.ok ? "yes" : "NO"} (identity ${v.identity ? "ok" : "not ok"}, ledger proofs ${v.proofs.replace("_", " ")})`,
+    ]), row(["Bundle SHA-256", r.bundle_sha256]), row(["Investigator", r.signed ? r.signed.by : "unsigned"]), row(["Investigated at", r.investigated_at]));
+    if (v && !v.ok)
+        out.push("", "**The record does not verify. Everything below may have been altered.**");
+    out.push("", "## Who had the controls", "");
+    if (r.authority.length === 0)
+        out.push("No authority recorded.");
+    else {
+        out.push(...head(["From seq", "To seq", "Mode", "By", "Reason"]));
+        for (const s of r.authority)
+            out.push(row([s.from_seq, s.to_seq ?? "end", s.mode, s.by, s.reason]));
+    }
+    out.push("", "## Findings", "");
+    if (r.findings.length === 0)
+        out.push("None recorded.");
+    else {
+        out.push(...head(["Seq", "Code", "Fault", "Severity", "In control", "Weather"]));
+        for (const f of r.findings) {
+            const weather = Array.isArray(f.weather)
+                ? f.weather
+                    .map((w) => `${w.model}: ${w.status}`)
+                    .join(", ")
+                : null;
+            const control = f.in_control === null ? null : `${f.in_control} (${f.in_control_by ?? "—"})`;
+            out.push(row([f.seq, f.code, f.fault, f.severity, control, weather]));
+        }
+    }
+    out.push("", "## Matching directives", "");
+    if (r.directives === null)
+        out.push("No directives were given.");
+    else if (r.directives.length === 0)
+        out.push("None matched.");
+    else {
+        out.push(...head(["Directive", "Applies to", "Pattern", "Affected (ppm)"]));
+        for (const d of r.directives) {
+            const to = "model" in d.applies_to ? `model ${d.applies_to.model}` : `tool ${d.applies_to.tool}`;
+            out.push(row([d.id, to, d.pattern.join(", "), d.affected_ppm]));
+        }
+    }
+    if (r.drill) {
+        const d = r.drill;
+        out.push("", "## Drill", "", `This session was a drill: ${d.planned.length} faults planned, ${d.injected.length} injected (${d.injected.map((i) => i.kind).join(", ") || "none"}).`, `Recovered: ${d.recovered ? "yes" : "no"}. Findings after the first fault: ${d.findings_after.join(", ") || "none"}.`);
+    }
+    out.push("", "## What this report proves", "", "If the record verifies, these events are the ones the gateway recorded, in this order, and unchanged since. Its chain is intact and its anchors are signed by the pinned identity; with ledger proofs checked, they were also on the ledger at the times shown.", "It does not prove what the agent intended, or that the providers and tools behaved as their answers say. It also can't show what happened outside the gateway.", "The signature shows who wrote this report. Check it with `blackbox verify-certificate <report>.json --did <investigator>`.", "");
+    return out.join("\n");
+}

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, '""')}"`;
+}