@zanii/blackbox 0.21.2 → 0.23.0

package/dist/cli.js

@@ -5,7 +5,7 @@ import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseCommand } from "./attest/index.js";
-import { serveMcp } from "./mcp-server/index.js";
+import { serveMcp, serveMcpHttp } from "./mcp-server/index.js";
 import { mcpWrap } from "./mcp-wrap/index.js";
 import { RecordNotVerified, reconcile } from "./reconcile/index.js";
 import { session } from "./session/index.js";
@@ -28,6 +28,11 @@ const USAGE = `usage (spec/cli.md):
   blackbox replay <session_id> [--fork] [--fork-after N] [--label L] [--drill <drill.json>]
   blackbox scenario save <session_id> [--out <file>]
   blackbox scenario run <scenario.json>... -- <agent command>   (1 when an incident's findings recur)
+  blackbox eval dataset create <name> [<cases.jsonl> | <scenario.json>]... [--label L [--outcome O] [--limit N]] [--scorer <json>]
+  blackbox eval dataset list | blackbox eval dataset get <dataset_id>
+  blackbox eval run <dataset_id> [--name N] -- <agent command>   (1 when any case fails)
+  blackbox eval run <dataset_id> [--name N] <case_id>=<session_id>...   (scores recorded sessions)
+  blackbox eval compare <run_a> <run_b>   (1 when b is worse than a)
   blackbox tail <session_id> [--after-seq N]
   blackbox close <session_id> [--outcome success|failure|abandoned] [--note <text>]
   blackbox resume <session_id> [--token <resume token>] [--note <text>] [--force]   (a paused session needs no token)
@@ -43,6 +48,7 @@ const USAGE = `usage (spec/cli.md):
   blackbox investigate <bundle.json> [--bodies <dir>] [--directives <file>] [--identity <file>] [--proofs] [--out <prefix>]
   blackbox evidence-pack <bundle.json> [--proofs] [--identity <file>] [--lang en|ar|both] [--out <prefix>]
   blackbox sign-constitution <draft.json> --identity <owner.json> [--out <file>]
+  blackbox sign <draft.json> --identity <owner.json> [--out <file>]   (a service register or an accreditation)
   blackbox policy-from-zanii <zanii-policy.json> [--out <file>]
   blackbox policy-to-zanii <policy.json> [--out <file>]
   blackbox statement --provider anthropic|openai --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--out <file>]
@@ -50,7 +56,7 @@ const USAGE = `usage (spec/cli.md):
   blackbox statement --provider custom --connector <file> --from <d> --to <d> [--out <file>]
   blackbox preflight --require <items> [--optional <items>]
   blackbox --version
-  blackbox mcp   (an MCP server on stdio: spec/mcp-server.md)
+  blackbox mcp [--http [host:]port]   (an MCP server on stdio, or Streamable HTTP: spec/mcp-server.md)
   blackbox mcp-wrap --server <name> -- <command> [args...]
   blackbox reconcile --harness claude-code|codex --bundle <bundle.json> --bodies <dir> [--agent-session <id>]... [--require-receipts] <path>
   blackbox reconcile-system --connector <connector.json> --log <export.csv|jsonl> [--pack <pack.json>] <session_id>
@@ -99,6 +105,8 @@ async function main(argv) {
         return replayCommand(rest);
     if (command === "scenario")
         return scenarioCommand(rest);
+    if (command === "eval")
+        return evalCommand(rest);
     if (command === "analyze")
         return analyzeCommand(rest);
     if (command === "verify-certificate")
@@ -111,6 +119,8 @@ async function main(argv) {
         return evidencePackCommand(rest);
     if (command === "sign-constitution")
         return signConstitutionCommand(rest);
+    if (command === "sign")
+        return signCommand(rest);
     if (command === "policy-from-zanii" || command === "policy-to-zanii")
         return policyZaniiCommand(command, rest);
     if (command === "statement")
@@ -393,17 +403,33 @@ function mcpCommand(rest) {
     const url = process.env.BLACKBOX_URL?.replace(/\/+$/, "");
     // audit, also found: a tenant's key (read-only works) instead of the operator's
     const key = process.env.BLACKBOX_API_KEY || process.env.BLACKBOX_ADMIN_KEY;
-    if (rest.length > 0 || !url || !key) {
-        process.stderr.write(`${USAGE}\n(mcp: BLACKBOX_URL and BLACKBOX_API_KEY or BLACKBOX_ADMIN_KEY must be set)\n`);
-        return 2;
-    }
-    return serveMcp(async (path) => {
+    const reader = (k) => async (path) => {
         const res = await fetch(`${url}${path}`, {
-            headers: { authorization: `Bearer ${key}` },
+            headers: { authorization: `Bearer ${k}` },
             signal: AbortSignal.timeout(30_000),
         });
         return { status: res.status, text: await res.text() };
-    });
+    };
+    // spec/mcp-server.md: `--http [host:]port` serves Streamable HTTP; each caller brings its own key
+    if (rest[0] === "--http") {
+        const m = /^(?:(.+):)?(\d{1,5})$/.exec(rest[1] ?? "");
+        const port = Number(m?.[2]);
+        if (rest.length !== 2 || !m || port > 65535 || !url) {
+            process.stderr.write(`${USAGE}\n(mcp --http [host:]port: BLACKBOX_URL must be set)\n`);
+            return 2;
+        }
+        const host = (m[1] ?? "127.0.0.1").replace(/^\[(.*)\]$/, "$1");
+        return serveMcpHttp(reader, {
+            host,
+            port,
+            onListening: (at) => process.stderr.write(`blackbox mcp: serving ${at}\n`),
+        });
+    }
+    if (rest.length > 0 || !url || !key) {
+        process.stderr.write(`${USAGE}\n(mcp: BLACKBOX_URL and BLACKBOX_API_KEY or BLACKBOX_ADMIN_KEY must be set)\n`);
+        return 2;
+    }
+    return serveMcp(reader(key));
 }
 class ServerError extends Error {
 }
@@ -689,16 +715,32 @@ async function scenarioRun(file, command) {
     const label = `regression: ${scenario.label || source}`.slice(0, 200);
     const opened = (await (await admin("/v1/sessions", { label, replay: { of: source, fork: true } })).json());
     const sid = String(opened.session_id);
-    const token = String(opened.token);
+    const code = await runAgent(command, sid, String(opened.token), { BLACKBOX_SCENARIO: file });
+    const after = (await (await admin(`/v1/sessions/${sid}/scenario`)).json());
+    const got = (after?.expect?.finding_codes ?? {});
+    const recurred = Object.fromEntries(Object.keys(before).flatMap((c) => (got[c] ? [[c, got[c]]] : [])));
+    return {
+        scenario: file,
+        source,
+        session_id: sid,
+        exit_code: code,
+        ok: code === 0 && Object.keys(recurred).length === 0,
+        recurred,
+        new: Object.fromEntries(Object.entries(got).filter(([c]) => !(c in before))),
+    };
+}
+/** Runs the agent once in a session (no shell), its output on stderr so stdout stays the results,
+ * then closes the session: `success` when it exited 0. Returns its exit code. */
+async function runAgent(command, sid, token, extra) {
     const url = String(process.env.BLACKBOX_URL).replace(/\/+$/, "");
     const run = spawnSync(command[0], command.slice(1), {
-        stdio: ["inherit", 2, "inherit"], // the agent prints to stderr: stdout is the results
+        stdio: ["inherit", 2, "inherit"],
         env: {
             ...process.env,
             BLACKBOX_SESSION_ID: sid,
             BLACKBOX_TOKEN: token,
-            BLACKBOX_SCENARIO: file,
-            // the official clients read these: an agent that doesn't set its own goes through the fork
+            ...extra,
+            // the official clients read these: an agent that doesn't set its own goes through Blackbox
             ANTHROPIC_BASE_URL: `${url}/anthropic`,
             ANTHROPIC_API_KEY: token,
             OPENAI_BASE_URL: `${url}/openai/v1`,
@@ -709,18 +751,127 @@ async function scenarioRun(file, command) {
         process.stderr.write(`blackbox: can't run ${command[0]}: ${run.error.message}\n`);
     const code = run.error ? 127 : (run.status ?? 1);
     await admin(`/v1/sessions/${sid}/close`, { outcome: code === 0 ? "success" : "failure" });
-    const after = (await (await admin(`/v1/sessions/${sid}/scenario`)).json());
-    const got = (after?.expect?.finding_codes ?? {});
-    const recurred = Object.fromEntries(Object.keys(before).flatMap((c) => (got[c] ? [[c, got[c]]] : [])));
-    return {
-        scenario: file,
-        source,
-        session_id: sid,
-        exit_code: code,
-        ok: code === 0 && Object.keys(recurred).length === 0,
-        recurred,
-        new: Object.fromEntries(Object.entries(got).filter(([c]) => !(c in before))),
+    return code;
+}
+/** spec/evals.md §6: datasets, eval runs (the agent run against each case, or recorded sessions
+ * scored), and two runs compared. */
+async function evalCommand(rest) {
+    const at = rest.indexOf("--");
+    const command = at === -1 ? [] : rest.slice(at + 1);
+    const { flags, positional } = parse(at === -1 ? rest : rest.slice(0, at), []);
+    const [what, ...args] = positional;
+    const enc = encodeURIComponent;
+    if (what === "dataset" && !command.length) {
+        const [verb, ...more] = args;
+        if (verb === "list" && !more.length)
+            return printJson("/v1/evals/datasets");
+        if (verb === "get" && more.length === 1)
+            return printJson(`/v1/evals/datasets/${enc(more[0])}`);
+        if (verb !== "create" || !more.length || (more.length === 1 && !flags.label))
+            return usage();
+        const [name, ...files] = more;
+        const { parseCasesJsonl } = await import("./evals/index.js");
+        const body = { name };
+        const cases = [];
+        const scenarios = [];
+        for (const f of files) {
+            let text;
+            try {
+                text = readFileSync(f, "utf8");
+            }
+            catch (error) {
+                throw new ServerError(`${f}: ${error instanceof Error ? error.message : error}`);
+            }
+            let one;
+            try {
+                one = JSON.parse(text);
+            }
+            catch { }
+            if (one?.v === 1 && typeof one.source === "string" && one.expect !== undefined) {
+                scenarios.push(one);
+                continue;
+            }
+            const got = parseCasesJsonl(text);
+            if (typeof got === "string")
+                throw new ServerError(`${f}: ${got}`);
+            cases.push(...got);
+        }
+        if (cases.length)
+            body.cases = cases;
+        if (scenarios.length)
+            body.from_scenarios = scenarios;
+        if (flags.limit !== undefined && !/^\d+$/.test(flags.limit))
+            return usage();
+        if (flags.label)
+            body.from_sessions = {
+                label: flags.label,
+                ...(flags.outcome ? { outcome: flags.outcome } : {}),
+                ...(flags.limit ? { limit: Number(flags.limit) } : {}),
+            };
+        if (flags.scorer !== undefined)
+            try {
+                body.scorer = JSON.parse(flags.scorer);
+            }
+            catch {
+                return usage();
+            }
+        const made = await (await admin("/v1/evals/datasets", body)).json();
+        process.stdout.write(`${JSON.stringify(made)}\n`);
+        return 0;
+    }
+    if (what === "compare" && args.length === 2 && !command.length) {
+        const [a, b] = args;
+        const doc = await adminJson(`/v1/evals/compare?a=${enc(a)}&b=${enc(b)}`);
+        process.stdout.write(`${JSON.stringify(doc)}\n`);
+        return doc.verdict === "worse" ? 1 : 0;
+    }
+    if (what !== "run" || args.length < 1)
+        return usage();
+    const [id, ...pairs] = args;
+    if (command.length ? pairs.length > 0 : pairs.length === 0)
+        return usage();
+    const sessions = [];
+    for (const p of pairs) {
+        const m = /^([^=]+)=(ses_[A-Za-z0-9]{16,64})$/.exec(p);
+        if (!m)
+            return usage();
+        sessions.push({ case: m[1], session_id: m[2] });
+    }
+    const ds = await adminJson(`/v1/evals/datasets/${enc(id)}`);
+    for (const c of command.length ? ds.cases : []) {
+        // a case made from a recorded run replays it, going live where the agent now differs
+        const of = typeof c.input?.replay_of === "string" ? c.input.replay_of : null;
+        const opened = (await (await admin("/v1/sessions", {
+            label: `eval: ${ds.name}`.slice(0, 128),
+            ...(of ? { replay: { of, fork: true } } : {}),
+        })).json());
+        const sid = String(opened.session_id);
+        await runAgent(command, sid, String(opened.token), {
+            BLACKBOX_EVAL_DATASET: String(ds.id),
+            BLACKBOX_EVAL_CASE: String(c.id),
+            BLACKBOX_EVAL_INPUT: JSON.stringify(c.input),
+        });
+        sessions.push({ case: String(c.id), session_id: sid });
+    }
+    const body = { dataset: ds.id, ...(flags.name ? { name: flags.name } : {}), sessions };
+    const run = (await (await admin("/v1/evals/runs", body)).json());
+    const s = run.summary;
+    const line = {
+        run: run.id,
+        dataset: ds.id,
+        name: run.name,
+        total: s.total,
+        passed: s.passed,
+        failed: s.failed,
+        outages: s.outages,
+        pass_ppm: s.pass_ppm,
+        pass_low_ppm: s.pass_low_ppm,
+        pass_high_ppm: s.pass_high_ppm,
+        cost_micro_usd: s.cost_micro_usd,
+        failing: run.results.filter((r) => !r.pass).map((r) => r.case),
     };
+    process.stdout.write(`${JSON.stringify(line)}\n`);
+    return s.failed ? 1 : 0;
 }
 /** Audit S12: an exported bundle, analysed offline: it must verify first, then the summary, the
  * findings it recorded, and the findings this SDK's analyses find in it now. */
@@ -863,6 +1014,30 @@ async function signConstitutionCommand(rest) {
         return 2;
     }
 }
+/** spec/admission.md §3: signs a draft (a service register, an accreditation) as the identity. */
+async function signCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    if (positional.length !== 1 || !flags.identity)
+        return usage();
+    const { signCertificate } = await import("./fleet/index.js");
+    const { docHash } = await import("./admission/index.js");
+    try {
+        const draft = JSON.parse(readFileSync(positional[0], "utf8"));
+        if (!draft || typeof draft !== "object" || Array.isArray(draft))
+            throw new Error("the draft must be a JSON object");
+        const { signed: _old, ...rest_ } = draft;
+        const identity = await readIdentity(flags.identity);
+        const doc = signCertificate(rest_, identity.did, identity.seed);
+        const out = flags.out || "signed.json";
+        writeFileSync(out, `${JSON.stringify(doc, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ok: true, file: out, sha256: docHash(doc), by: identity.did })}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: error.message })}\n`);
+        return 2;
+    }
+}
 /** spec/investigations.md §7: the court evidence pack, `<prefix>.json` (signed) and `<prefix>.md`. */
 async function evidencePackCommand(rest) {
     const { flags, positional } = parse(rest, ["--proofs"]);

package/dist/compliance/index.d.ts

@@ -43,6 +43,8 @@ export declare function complianceReport(frameworkId: string, framework: Framewo
     notes: string;
     notes_ar?: string;
 }, lang?: "en" | "ar"): Report;
+/** spec/compliance.md §3: each fact's Arabic label (the key follows it, so tools still match). */
+export declare const FACTS_AR: Record<string, string>;
 export declare function renderReport(r: Report): string;
 /** spec/compliance.md §1: the facts over sessions' records (the server adds verified / anchored). */
 export declare function complianceFacts(sessions: ReadonlyArray<{

package/dist/compliance/index.js

@@ -32,6 +32,28 @@ const show = (v, ar = false) => {
     }
     return String(v);
 };
+/** spec/compliance.md §3: each fact's Arabic label (the key follows it, so tools still match). */
+export const FACTS_AR = {
+    sessions: "الجلسات",
+    events: "الأحداث",
+    sessions_verified: "الجلسات التي تحققت سلاسلها",
+    sessions_anchored: "الجلسات المثبتة على السجل",
+    redactions: "الحجب",
+    findings_warning: "الملاحظات بمستوى تحذير",
+    bypasses: "تجاوزات البوابة",
+    false_claims: "الادعاءات غير الصحيحة",
+    blocks: "الإيقافات",
+    emergency_stops: "الإيقافات الطارئة",
+    resumes_with_note: "الاستئنافات المسببة",
+    outcomes: "النتائج",
+    data_region: "منطقة البيانات",
+    model_responses: "إجابات النموذج",
+    hallucination_findings: "ملاحظات الهلوسة",
+    grounding_checks: "فحوص الإسناد",
+    judge_checks: "فحوص المُقيِّم",
+    hallucination_controls: "ضوابط الهلوسة",
+    detector_accuracy: "دقة الكواشف",
+};
 export function renderReport(r) {
     const ar = r.lang === "ar";
     const out = [
@@ -47,9 +69,11 @@ export function renderReport(r) {
         const head = ar ? "| الدليل | القيمة |" : "| Evidence | Value |";
         out.push("", `## ${s.title}`, "", s.requirement, "", head, "|---|---|");
         for (const [k, v] of Object.entries(s.evidence))
-            out.push(`| ${k} | ${show(v, ar)} |`);
+            out.push(`| ${ar && FACTS_AR[k] ? `${FACTS_AR[k]} (\`${k}\`)` : k} | ${show(v, ar)} |`);
     }
-    return `${out.join("\n")}\n`;
+    const body = `${out.join("\n")}\n`;
+    // Right to left, as the incident report (spec/fleet.md §2)
+    return ar ? `<div dir="rtl" lang="ar">\n\n${body}\n</div>\n` : body;
 }
 /** spec/compliance.md §1: the facts over sessions' records (the server adds verified / anchored). */
 export function complianceFacts(sessions, dataRegion) {

package/dist/cost/batch.d.ts

@@ -0,0 +1,26 @@
+import type { Bodies } from "../reconcile/record.ts";
+import { type LoadedPrices, type Tokens } from "./index.ts";
+export interface BatchItem {
+    custom_id: string;
+    status: string;
+    model: string | null;
+    joined: boolean;
+    tokens: Tokens;
+    micro_usd: number | null;
+}
+export interface BatchEntry {
+    seq: number;
+    request_seq: number;
+    provider: string | null;
+    source_seq: number | null;
+    results: number;
+    joined: number;
+    micro_usd: number | null;
+    items: BatchItem[];
+}
+export interface BatchReport {
+    v: 1;
+    batches: BatchEntry[];
+}
+/** The session's batch results joined to their requests and priced (spec/cost.md §6). */
+export declare function batchReport(lines: readonly string[], bodies: Bodies, prices: LoadedPrices): BatchReport;

package/dist/cost/batch.js

@@ -0,0 +1,173 @@
+// Batch results joined to their requests (spec/cost.md §6, spec/providers.md §6): each results
+// download read again from its recorded chunks, its lines joined by custom_id to the call that
+// carried the batch's requests, each result priced at the batch rate.
+// Mirrors sdks/python/src/zanii_blackbox/batch.py.
+import { priceCall } from "./index.js";
+const decoder = new TextDecoder();
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const ZERO = { input: 0, output: 0, cache_read: 0, cache_write: 0 };
+function jsonLines(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const o = JSON.parse(line);
+            if (isObj(o))
+                out.push(o);
+        }
+        catch { }
+    }
+    return out;
+}
+/** One result line as {id, status, model, usage}, or null when it isn't one. */
+function resultOf(o) {
+    if (typeof o.custom_id !== "string")
+        return null;
+    if (isObj(o.result)) {
+        // Anthropic: {custom_id, result: {type, message?}}
+        const message = isObj(o.result.message) ? o.result.message : {};
+        const status = typeof o.result.type === "string" ? o.result.type : "errored";
+        return { id: o.custom_id, status, model: message.model, usage: message.usage };
+    }
+    if (!("response" in o) && !("error" in o))
+        return null;
+    // OpenAI: {custom_id, response: {status_code, body}, error}
+    const response = isObj(o.response) ? o.response : {};
+    const code = response.status_code;
+    const ok = typeof code === "number" && code >= 200 && code < 300 && o.error == null;
+    const body = isObj(response.body) ? response.body : {};
+    return {
+        id: o.custom_id,
+        status: ok ? "succeeded" : "errored",
+        model: body.model,
+        usage: body.usage,
+    };
+}
+/** Flattened integer usage, as the gateway records it (spec/api.md §3). */
+function flatten(usage) {
+    const out = {};
+    const walk = (o, prefix) => {
+        for (const [k, v] of Object.entries(o)) {
+            if (typeof v === "number" && Number.isSafeInteger(v))
+                out[prefix + k] = v;
+            else if (isObj(v))
+                walk(v, `${prefix}${k}_`);
+        }
+    };
+    if (isObj(usage))
+        walk(usage, "");
+    return out;
+}
+/** The custom_ids a batch's source call carried: Anthropic's requests[], or OpenAI's JSONL file. */
+function customIds(text) {
+    const ids = new Set();
+    let whole;
+    try {
+        whole = JSON.parse(text);
+    }
+    catch { }
+    if (isObj(whole) && Array.isArray(whole.requests)) {
+        for (const r of whole.requests)
+            if (isObj(r) && typeof r.custom_id === "string")
+                ids.add(r.custom_id);
+        return ids;
+    }
+    for (const o of jsonLines(text))
+        if (typeof o.custom_id === "string")
+            ids.add(o.custom_id);
+    return ids;
+}
+/** The session's batch results joined to their requests and priced (spec/cost.md §6). */
+export function batchReport(lines, bodies, prices) {
+    const events = lines.map((l) => JSON.parse(l));
+    const requests = new Map();
+    const answers = new Map(); // request seq → its llm.response meta
+    const chunks = new Map(); // decoded whole: a character can span chunks
+    for (const e of events) {
+        const owner = e.meta.request_seq;
+        if (e.kind === "llm.request")
+            requests.set(e.seq, e);
+        else if (e.kind === "llm.chunk" && typeof owner === "number") {
+            const list = chunks.get(owner) ?? [];
+            list.push(bodies(e.body_hash) ?? new Uint8Array());
+            chunks.set(owner, list);
+        }
+        else if (e.kind === "llm.response" && typeof owner === "number")
+            answers.set(owner, e.meta);
+    }
+    const pathOf = (seq) => {
+        const p = requests.get(seq)?.meta.path;
+        return typeof p === "string" ? p.split("?")[0] : "";
+    };
+    const postTo = (seq, tail) => requests.get(seq)?.meta.method === "POST" && tail.test(pathOf(seq));
+    /** The latest request before `before` whose answer has `field` = `value` and that passes `ok`. */
+    const answered = (field, value, before, ok) => {
+        let found = null;
+        for (const [seq, meta] of answers)
+            if (seq < before && meta[field] === value && ok(seq))
+                found = seq;
+        return found;
+    };
+    const batches = [];
+    for (const e of events) {
+        const requestSeq = e.meta.request_seq;
+        if (e.kind !== "llm.response" || !isObj(e.meta.batch) || typeof requestSeq !== "number")
+            continue;
+        const path = pathOf(requestSeq);
+        let source = null;
+        const anthropic = /\/messages\/batches\/([^/]+)\/results$/.exec(path);
+        const openai = /\/files\/([^/]+)\/content$/.exec(path);
+        if (anthropic)
+            source = answered("batch_id", anthropic[1], requestSeq, (s) => postTo(s, /\/messages\/batches$/));
+        else if (openai) {
+            const file = openai[1];
+            let input;
+            for (const [seq, meta] of answers)
+                if (seq < requestSeq && (meta.output_file_id === file || meta.error_file_id === file))
+                    input = meta.input_file_id;
+            if (typeof input === "string")
+                source = answered("file_id", input, requestSeq, (s) => postTo(s, /\/files$/));
+        }
+        const sourceRequest = source === null ? undefined : requests.get(source);
+        const sourceBody = sourceRequest ? bodies(sourceRequest.body_hash) : undefined;
+        const ids = sourceBody ? customIds(decoder.decode(sourceBody)) : new Set();
+        const p = requests.get(requestSeq)?.meta.provider;
+        const provider = typeof p === "string" ? p : null;
+        const items = [];
+        let total = 0;
+        for (const line of jsonLines(decoder.decode(Buffer.concat(chunks.get(requestSeq) ?? [])))) {
+            const r = resultOf(line);
+            if (!r)
+                continue;
+            const model = typeof r.model === "string" ? r.model : null;
+            let tokens = ZERO;
+            let micro = 0;
+            if (r.status === "succeeded") {
+                const priced = priceCall({ model, usage: flatten(r.usage), provider, batch: { requests: 1 } }, prices.table);
+                tokens = priced.tokens;
+                micro = priced.micro_usd;
+            }
+            total = total === null || micro === null ? null : total + micro;
+            items.push({
+                custom_id: r.id,
+                status: r.status,
+                model,
+                joined: ids.has(r.id),
+                tokens,
+                micro_usd: micro,
+            });
+        }
+        batches.push({
+            seq: e.seq,
+            request_seq: requestSeq,
+            provider,
+            source_seq: source,
+            results: items.length,
+            joined: items.filter((i) => i.joined).length,
+            micro_usd: total,
+            items,
+        });
+    }
+    return { v: 1, batches };
+}

package/dist/cost/index.d.ts

@@ -30,6 +30,8 @@ export interface ModelPrice {
     service_tiers?: Record<string, ClassPrices>;
     /** `deprecated` feeds the MODEL_DEPRECATED finding; `beta` is informational. */
     status?: "deprecated" | "beta";
+    /** The percent of the price a batch result pays (spec/cost.md §1); absent: no known batch rate. */
+    batch_percent?: number;
 }
 export interface PriceTable {
     version: string;
@@ -81,6 +83,14 @@ export interface CallCost {
     source?: "reported";
     /** The answer carried no usage (`usage_missing`): unpriced, never counted as free. */
     no_usage?: true;
+    /** A batch result (spec/cost.md §2): its result count, and the batch percent it was priced at. */
+    batch?: {
+        requests: number;
+        percent?: number;
+    };
+    /** spec/cost.md §2: an MCP client's answer to a server's `sampling/createMessage`, or a usage
+     *  report in a realtime session (spec/providers.md §7). */
+    via?: "mcp_sampling" | "realtime";
 }
 export interface CostReport {
     v: 1;
@@ -145,6 +155,10 @@ export declare function priceCall(call: {
     provider?: string | null;
     serviceTier?: string | null;
     reportedMicroUsd?: number | null;
+    /** A batch result (spec/cost.md §2): priced at the model's batch_percent, or not at all. */
+    batch?: {
+        requests: number;
+    };
 }, table: PriceTable): Omit<CallCost, "seq" | "model"> & {
     key: string | null;
 };
@@ -154,5 +168,12 @@ export declare function upliftPercent(table: PriceTable, provider: string | null
 /** fils at the CBUAE peg (3.6725 AED / USD), rounded half up. */
 export declare function toAedFils(microUsd: number): number;
 export declare function formatAed(fils: number): string;
+/** A results download's `meta.batch.models` (spec/providers.md §6), the well-formed entries; null
+ *  when the response isn't one. */
+export declare function batchModels(batch: unknown): Array<{
+    model: string;
+    requests: number;
+    usage: Record<string, unknown>;
+}> | null;
 /** The session's cost report from its recorded lines. */
 export declare function sessionCost(lines: readonly string[], prices: LoadedPrices): CostReport;