@zanii/blackbox 0.21.2 → 0.23.0

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

@@ -0,0 +1,26 @@
+import type { Json } from "../verify/envelope.ts";
+type Meta = {
+    [key: string]: Json;
+};
+/** The server's request methods and the event kind each is recorded as. */
+export declare const SERVER_REQUESTS: Readonly<Record<string, ServerRequestKind>>;
+export type ServerRequestKind = "tool.sampling" | "tool.elicitation" | "tool.roots";
+/** A JSON-RPC id as recorded: a string of at most 256 characters, or a safe integer. */
+export declare function rpcIdOf(id: unknown): string | number | undefined;
+/** The field names that ask for a credential: the name, lowercased with everything but letters
+ * and digits removed, contains one of the credential words, or is `pin`. In the order given. */
+export declare function secretFields(names: readonly string[]): string[];
+/**
+ * A server → client message that is one of the server's requests: its kind and `meta`, or null
+ * for anything else (a notification, a response, another method, a batch, a request without a
+ * usable id).
+ */
+export declare function serverRequestMeta(message: unknown): {
+    kind: ServerRequestKind;
+    meta: Meta;
+} | null;
+/** The client's reply to a server request of `method`: its `meta` (spec/mcp.md §6). */
+export declare function serverReplyMeta(method: string, message: unknown): Meta;
+/** Whether a client → server message is a reply (a JSON-RPC response) rather than a request. */
+export declare function isRpcResponse(message: unknown): boolean;
+export {};

package/dist/mcp-requests/index.js

@@ -0,0 +1,154 @@
+// MCP server-to-client requests (spec/mcp.md §6): `sampling/createMessage`, `elicitation/create` and
+// `roots/list`, and the client's replies, as their own event kinds. Pure functions, pinned by
+// spec/vectors/mcp-requests.json. Mirrors sdks/python/src/zanii_blackbox/mcp_requests.py.
+/** The server's request methods and the event kind each is recorded as. */
+export const SERVER_REQUESTS = {
+    "sampling/createMessage": "tool.sampling",
+    "elicitation/create": "tool.elicitation",
+    "roots/list": "tool.roots",
+};
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : {};
+const str = (v, max) => (typeof v === "string" && v.length <= max ? v : undefined);
+const count = (v) => (Array.isArray(v) ? v.length : undefined);
+const nonNegative = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0 ? v : undefined;
+const put = (meta, key, value) => {
+    if (value !== undefined)
+        meta[key] = value;
+};
+const keys = (v) => {
+    const o = obj(v);
+    return Object.keys(o)
+        .slice(0, 50)
+        .map((k) => k.slice(0, 64));
+};
+/** A JSON-RPC id as recorded: a string of at most 256 characters, or a safe integer. */
+export function rpcIdOf(id) {
+    if (typeof id === "string" && id.length <= 256)
+        return id;
+    if (typeof id === "number" && Number.isSafeInteger(id))
+        return id;
+    return undefined;
+}
+// ponytail: a name list, not a classifier; a field named for a credential is what a phishing
+// elicitation asks for. Extend the list when a real one slips through.
+const SECRET_NAMES = [
+    "password",
+    "passwd",
+    "passphrase",
+    "secret",
+    "token",
+    "apikey",
+    "accesskey",
+    "privatekey",
+    "credential",
+    "otp",
+    "totp",
+    "mfacode",
+    "pincode",
+    "cvv",
+    "cvc",
+    "cardnumber",
+    "iban",
+    "ssn",
+    "seedphrase",
+    "mnemonic",
+];
+/** The field names that ask for a credential: the name, lowercased with everything but letters
+ * and digits removed, contains one of the credential words, or is `pin`. In the order given. */
+export function secretFields(names) {
+    return names.filter((n) => {
+        const plain = n.toLowerCase().replace(/[^a-z0-9]/g, "");
+        return plain === "pin" || SECRET_NAMES.some((w) => plain.includes(w));
+    });
+}
+/**
+ * A server → client message that is one of the server's requests: its kind and `meta`, or null
+ * for anything else (a notification, a response, another method, a batch, a request without a
+ * usable id).
+ */
+export function serverRequestMeta(message) {
+    const m = obj(message);
+    const method = typeof m.method === "string" ? m.method : "";
+    const kind = Object.hasOwn(SERVER_REQUESTS, method) ? SERVER_REQUESTS[method] : undefined;
+    const id = rpcIdOf(m.id);
+    if (!kind || id === undefined)
+        return null;
+    const p = obj(m.params);
+    const meta = { phase: "request", method, rpc_id: id };
+    if (kind === "tool.sampling") {
+        put(meta, "max_tokens", nonNegative(p.maxTokens));
+        put(meta, "messages", count(p.messages));
+        const include = str(p.includeContext, 32);
+        if (include === "none" || include === "thisServer" || include === "allServers")
+            meta.include_context = include;
+        const hints = obj(p.modelPreferences).hints;
+        if (Array.isArray(hints)) {
+            const names = hints
+                .map((h) => str(obj(h).name, 128))
+                .filter((n) => n !== undefined)
+                .slice(0, 8);
+            if (names.length)
+                meta.model_hints = names;
+        }
+    }
+    else if (kind === "tool.elicitation") {
+        put(meta, "mode", str(p.mode, 32));
+        const fields = keys(obj(p.requestedSchema).properties);
+        if (fields.length)
+            meta.fields = fields;
+        const secret = secretFields(fields);
+        if (secret.length)
+            meta.secret_fields = secret;
+    }
+    return { kind, meta };
+}
+/** Flattens a usage object into integer fields (`{a: {b: 1}}` → `{a_b: 1}`), at most 64. */
+function flatUsage(usage) {
+    const out = {};
+    const walk = (o, prefix, depth) => {
+        for (const [k, v] of Object.entries(o)) {
+            if (Object.keys(out).length >= 64)
+                return;
+            const key = (prefix + k).slice(0, 128);
+            if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0)
+                out[key] = v;
+            else if (depth < 3 && typeof v === "object" && v !== null && !Array.isArray(v))
+                walk(v, `${key}_`, depth + 1);
+        }
+    };
+    walk(obj(usage), "", 0);
+    return Object.keys(out).length ? out : undefined;
+}
+/** The client's reply to a server request of `method`: its `meta` (spec/mcp.md §6). */
+export function serverReplyMeta(method, message) {
+    const m = obj(message);
+    const meta = { phase: "reply", method };
+    put(meta, "rpc_id", rpcIdOf(m.id));
+    const code = obj(m.error).code;
+    if (typeof code === "number" && Number.isSafeInteger(code))
+        meta.rpc_error = code;
+    if (!("result" in m))
+        return meta;
+    const r = obj(m.result);
+    if (method === "sampling/createMessage") {
+        put(meta, "model", str(r.model, 256));
+        put(meta, "stop_reason", str(r.stopReason, 64));
+        put(meta, "usage", flatUsage(r.usage));
+    }
+    else if (method === "elicitation/create") {
+        const action = str(r.action, 16);
+        if (action === "accept" || action === "decline" || action === "cancel")
+            meta.action = action;
+        const fields = keys(r.content);
+        if (fields.length)
+            meta.fields = fields;
+    }
+    else if (method === "roots/list")
+        put(meta, "roots", count(r.roots));
+    return meta;
+}
+/** Whether a client → server message is a reply (a JSON-RPC response) rather than a request. */
+export function isRpcResponse(message) {
+    const m = obj(message);
+    return "id" in m && !("method" in m) && ("result" in m || "error" in m);
+}

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

@@ -80,6 +80,18 @@ type Result = {
 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>;
+/** Answers one parsed JSON-RPC message; undefined for a notification. */
+export declare function handleMessage(get: Get, parsed: unknown): Promise<object | undefined>;
 /** Serves stdin → stdout until stdin closes; one request at a time, in order. */
 export declare function serveMcp(get: Get): Promise<number>;
+/**
+ * spec/mcp-server.md §HTTP: the same server over MCP Streamable HTTP, at `/mcp`. Each POST is
+ * answered on its own, so requests run concurrently. The caller's bearer key (an admin or tenant
+ * key of the Blackbox server) is the key every tool call reads with: the server holds none.
+ */
+export declare function serveMcpHttp(getFor: (key: string) => Get, options: {
+    host: string;
+    port: number;
+    onListening?: (url: string) => void;
+}): Promise<number>;
 export {};

package/dist/mcp-server/index.js

@@ -1,5 +1,7 @@
-// The Blackbox MCP server (spec/mcp-server.md): read-only tools over the gateway's API, on stdio.
+// The Blackbox MCP server (spec/mcp-server.md): read-only tools over the gateway's API, on stdio or
+// Streamable HTTP.
 // Mirrors sdks/python/src/zanii_blackbox/mcp_server.py.
+import { createServer } from "node:http";
 import { createInterface } from "node:readline";
 const SESSION_ID = /^ses_[A-Za-z0-9]{16,64}$/;
 const sid = {
@@ -172,6 +174,7 @@ export async function callTool(get, name, args) {
         : doc;
     return text(JSON.stringify(out, null, 2));
 }
+const PARSE_ERROR = { jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } };
 /** Answers one JSON-RPC line; undefined for a notification. */
 export async function handleLine(get, line) {
     let msg;
@@ -179,8 +182,13 @@ export async function handleLine(get, line) {
         msg = JSON.parse(line);
     }
     catch {
-        return { jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } };
+        return PARSE_ERROR;
     }
+    return handleMessage(get, msg);
+}
+/** Answers one parsed JSON-RPC message; undefined for a notification. */
+export async function handleMessage(get, parsed) {
+    const msg = parsed;
     if (typeof msg !== "object" || msg === null || !("id" in msg))
         return undefined;
     const reply = (result) => ({ jsonrpc: "2.0", id: msg.id, result });
@@ -214,3 +222,77 @@ export async function serveMcp(get) {
     }
     return 0;
 }
+/**
+ * spec/mcp-server.md §HTTP: the same server over MCP Streamable HTTP, at `/mcp`. Each POST is
+ * answered on its own, so requests run concurrently. The caller's bearer key (an admin or tenant
+ * key of the Blackbox server) is the key every tool call reads with: the server holds none.
+ */
+export function serveMcpHttp(getFor, options) {
+    const server = createServer((req, res) => void answerHttp(getFor, req, res));
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, () => {
+            const { port } = server.address();
+            const host = options.host.includes(":") ? `[${options.host}]` : options.host;
+            options.onListening?.(`http://${host}:${port}/mcp`);
+        });
+        const stop = () => {
+            server.close(() => resolve(0));
+            server.closeAllConnections();
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+}
+const MAX_BODY = 1024 * 1024;
+const BEARER = /^Bearer ([\x21-\x7e]{1,512})$/;
+async function answerHttp(getFor, req, res) {
+    req.on("error", () => { });
+    res.on("error", () => { });
+    const send = (status, body, headers = {}) => void res
+        .writeHead(status, body ? { "content-type": "application/json", ...headers } : headers)
+        .end(body ? JSON.stringify(body) : undefined);
+    const fail = (status, message, headers = {}) => send(status, { jsonrpc: "2.0", id: null, error: { code: -32001, message } }, headers);
+    if ((req.url ?? "").split("?")[0] !== "/mcp")
+        return fail(404, "not found: the endpoint is /mcp");
+    // MCP Streamable HTTP: a browser page must not reach a local server (DNS rebinding)
+    const origin = req.headers.origin;
+    if (origin !== undefined && !sameHost(origin, req.headers.host))
+        return fail(403, "bad origin");
+    const auth = BEARER.exec(req.headers.authorization ?? "");
+    if (!auth?.[1])
+        return fail(401, "a Blackbox API key is required (Authorization: Bearer)", {
+            "www-authenticate": 'Bearer realm="blackbox"',
+        });
+    if (req.method !== "POST")
+        return fail(405, "only POST is served", { allow: "POST" });
+    const parts = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY)
+            return fail(413, "request body too large");
+        parts.push(chunk);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.concat(parts).toString("utf8"));
+    }
+    catch {
+        return send(400, PARSE_ERROR);
+    }
+    const get = getFor(auth[1]);
+    const many = Array.isArray(parsed);
+    const replies = (await Promise.all((many ? parsed : [parsed]).map((m) => handleMessage(get, m)))).filter((r) => r !== undefined);
+    if (replies.length === 0)
+        return send(202, null); // notifications only
+    send(200, many ? replies : replies[0]);
+}
+function sameHost(origin, host) {
+    try {
+        return new URL(origin).host === host;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/mcp-wrap/index.js

@@ -118,8 +118,9 @@ export async function mcpWrap(options) {
                 ? `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);
+            // spec/mcp.md §6: a server's own request refused by policy is answered to the server
             if (reply)
-                await write(stdout, reply);
+                await write(reply.toServer ? child.stdin : stdout, reply.bytes);
         });
     };
     const done = (d, source) => new Promise((resolve) => {
@@ -145,7 +146,8 @@ export async function mcpWrap(options) {
     agent.destroy();
     return code;
 }
-/** What the agent gets instead of a message that couldn't be recorded (spec/mcp.md §5). */
+/** What the agent gets instead of a message that couldn't be recorded (spec/mcp.md §5), or, for
+ * a server's own request the gateway's policy refused, what the server gets (§6). */
 function refusal(d, line, reason) {
     let message;
     try {
@@ -158,12 +160,14 @@ function refusal(d, line, reason) {
         return null;
     const isRequest = "method" in message;
     const isResponse = "result" in message || "error" in message;
-    if ((d === "client" && !isRequest) || (d === "server" && !isResponse))
+    const toServer = d === "server" && isRequest && typeof reason !== "string";
+    if (!toServer && ((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`);
+    const bytes = Buffer.from(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, error })}\n`);
+    return { bytes, toServer };
 }
 function quoteWindows(arg) {
     return /^[\w\-./:=@\\]+$/.test(arg) ? arg : `"${arg.replace(/"/g, '""')}"`;

package/dist/otlp/index.d.ts

@@ -28,6 +28,10 @@ export declare function toOtlp(lines: readonly string[], options?: {
         }[];
     }[];
 };
+type AnyAttr = {
+    key: string;
+    value: unknown;
+};
 /** One event for `POST /v1/sessions/:id/sdk-events`, numbered by the server (spec/sdk.md §1). */
 export interface OtlpEvent {
     event_id: string;
@@ -45,4 +49,155 @@ export declare function fromOtlp(body: unknown): {
 } | {
     error: string;
 };
+/** spec/otlp.md §5: a double as integer micro-units, half up; null when it isn't a finite number
+ * or its micro-units aren't a safe integer. */
+export declare function microOf(v: unknown): number | null;
+/**
+ * spec/otlp.md §5: OTLP/JSON metrics as session events, one per data point of a GenAI metric
+ * (`gen_ai.*`) or a point with a `gen_ai.*` or `blackbox.*` attribute (the resource's count);
+ * others are skipped. Doubles become integer micro-units; the event_id is a hash of the point's
+ * identity, so a resent point adds nothing.
+ */
+export declare function fromOtlpMetrics(body: unknown): {
+    events: OtlpEvent[];
+} | {
+    error: string;
+};
+/**
+ * spec/otlp.md §5: OTLP/JSON logs as session events, one per GenAI record (an event name
+ * `gen_ai.*`, or a `gen_ai.*` or `blackbox.*` attribute, the resource's included); others are
+ * skipped. The body is recorded as `body_sha256`, and itself only with `bodies: true`.
+ */
+export declare function fromOtlpLogs(body: unknown, options?: {
+    bodies?: boolean;
+}): {
+    events: OtlpEvent[];
+} | {
+    error: string;
+};
+/**
+ * spec/otlp.md §6: a session's metrics as OTLP/JSON: token usage and call duration (the GenAI
+ * client histograms), the calls witnessed, and the priced cost in micro-USD per model from its cost
+ * report (spec/cost.md), cumulative from the session's open to its last event.
+ */
+export declare function toOtlpMetrics(lines: readonly string[], cost?: {
+    calls: ReadonlyArray<{
+        model?: string | null;
+        micro_usd: number | null;
+    }>;
+} | null): {
+    resourceMetrics: {
+        resource: {
+            attributes: Attr[];
+        };
+        scopeMetrics: {
+            scope: {
+                name: string;
+                version: string;
+            };
+            metrics: ({
+                name: string;
+                description: string;
+                unit: string;
+                histogram: {
+                    aggregationTemporality: number;
+                    dataPoints: {
+                        startTimeUnixNano: string;
+                        timeUnixNano: string;
+                        attributes: AnyAttr[];
+                        count: string;
+                        sum: number;
+                        bucketCounts: string[];
+                        explicitBounds: number[];
+                        min: number;
+                        max: number;
+                    }[];
+                };
+                sum?: never;
+            } | {
+                histogram?: never;
+                name: string;
+                description: string;
+                unit: string;
+                sum: {
+                    aggregationTemporality: number;
+                    isMonotonic: boolean;
+                    dataPoints: object[];
+                };
+            })[];
+        }[];
+    }[];
+};
+/**
+ * spec/otlp.md §6: a session's findings as OTLP/JSON logs, one record each (event name
+ * `blackbox.finding`, the code as its body), in the session's trace (the root span's ids).
+ */
+export declare function toOtlpLogs(lines: readonly string[]): {
+    resourceLogs: {
+        resource: {
+            attributes: Attr[];
+        };
+        scopeLogs: {
+            scope: {
+                name: string;
+                version: string;
+            };
+            logRecords: {
+                timeUnixNano: string;
+                severityNumber?: number;
+                severityText?: string;
+                body: {
+                    stringValue: string;
+                };
+                attributes: AnyAttr[];
+                traceId: string;
+                spanId: string;
+                eventName: string;
+            }[];
+        }[];
+    }[];
+};
+/** One request the gateway forwarded, as it measured it (spec/otlp.md §7). */
+export interface GatewayCall {
+    request_seq: number;
+    response_seq?: number;
+    provider: string;
+    model?: string;
+    status?: number;
+    /** The `llm.incomplete` reason, when the call didn't complete. */
+    reason?: string;
+    start_unix_nano: string;
+    end_unix_nano: string;
+}
+/**
+ * spec/otlp.md §7: the gateway's own spans for a session's forwarded requests, in the session's
+ * trace: each a SERVER span `forward {provider}`, child of the record's model-call span (§1, §2).
+ */
+export declare function gatewayTrace(sessionId: string, calls: readonly GatewayCall[]): {
+    resourceSpans: {
+        resource: {
+            attributes: Attr[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+                version: string;
+            };
+            spans: {
+                traceId: string;
+                spanId: string;
+                parentSpanId: string;
+                name: string;
+                kind: number;
+                startTimeUnixNano: string;
+                endTimeUnixNano: string;
+                attributes: Attr[];
+                status?: {
+                    code: number;
+                    message: string;
+                };
+            }[];
+        }[];
+    }[];
+};
 export {};