@zanii/blackbox 0.3.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 The TypeScript SDK for [Zanii Blackbox](https://zanii.agency), the flight recorder for AI agents.
 
-Blackbox records every model call and tool call your agent makes, from a gateway that runs outside the agent's process. The records are hash-chained, so an edit or a deletion shows, and anchored as receipts that anyone can verify offline. This SDK is optional. It adds what only the agent knows (steps, its own tools, its checks, the outcome) as a second, independent record, and it reads and verifies what the gateway recorded.
+Blackbox records every model call and tool call your agent makes, for any industry and any organisation, from a gateway that runs outside the agent's process. The records are hash-chained, so an edit or a deletion shows, and anchored as receipts that anyone can verify offline. This SDK is optional. It adds what only the agent knows (steps, its own tools, its checks, the outcome) as a second, independent record, and it reads and verifies what the gateway recorded.
 
 ```sh
 npm install @zanii/blackbox
@@ -65,6 +65,36 @@ await s.close("success");
 - **It stays out of the way.** Recording is non-blocking with bounded memory. A recorded call costs about 0.3 ms (measured over 20,000 calls on a laptop); shipping happens in the background.
 - **It has no other runtime dependencies** besides the Zanii core libraries.
 
+## Hallucination controls
+
+The gateway checks every record, with no model needed: an invented tool or ID, arguments a tool's schema refuses, "done" right after an error, and amounts, doses, dates and IDs in answers that nothing the agent was given holds. With your organisation's own **reference packs** (prices, fees, rules, limits) it also catches answers that contradict them, and your own grounding model and judge can plug in. A risky answer can be held for a person before your customer sees it.
+
+From the SDK, pin what the agent read, then check an answer's signed credential anywhere:
+
+```ts
+import { verifyAnswerCredential, verifyCertificate } from "@zanii/blackbox";
+
+s.retrieved([{ id: "returns-policy", version: "2026-10", content: policyText }]); // hashed here, never sent
+
+// later, from GET /v1/sessions/:id/answers/:seq/credential and the session's record:
+verifyCertificate(credential).ok;                       // signed by the gateway
+verifyAnswerCredential(credential, lines, bodies, packs); // { ok, problems }: the record backs every claim
+```
+
+The same checks run offline as pure functions: `toolHallucinations`, `groundingFindings`, `factsIn`, `loadReferencePacks`, `answerRisk`, `detectorAccuracy`.
+
+## New in 0.5.0
+
+- Held streams: open a session with `holdStreams: true` (or set `BLACKBOX_HOLD_STREAMS=all` on the gateway) and a risky streamed answer waits for a person, as a non-streamed one does. The client gets keep-alives, then the whole stream, or one error in the provider's own format.
+- `session.checkAnswer(seq?)`: what in an answer would hold it (`{seq, risks, hold}`), for an app that streams by itself.
+
+## New in 0.4.0
+
+- Hallucination controls: the checks above, reference packs, answer credentials (`answerClaims`, `answerCredential`, `verifyAnswerCredential`), `session.retrieved()`, accuracy from people's labels (`detectorAccuracy`, Wilson bounds), the grounding and judge contracts, `answerRisk` for held answers.
+- Keyed redaction tokens (`tokenFor`, `resolveTokens`).
+- Evidence for payments, health and public services (`payment`, `healthAccess`, `decision` and their verifiers); provable agent memory (`memoryChain`); record badges, agent CVs, SLAs, ledger co-signing and the post-quantum binding.
+- Compliance reports in Arabic, and the hallucination-controls report (`hallucinationFacts`).
+
 ## Frameworks
 
 | Framework | Use |

package/dist/a2a/index.d.ts

@@ -47,4 +47,31 @@ type Jwk = {
  * least one signature verifies.
  */
 export declare function verifyAgentCard(card: unknown, keys: readonly Jwk[]): AgentCardReport;
+/**
+ * spec/a2a.md §3a (L3): the card as the gateway serves it, so a client that follows it stays on the
+ * record: every JSON-RPC interface points at `gatewayUrl`, other bindings (which the gateway can't
+ * capture) are dropped, and the publisher's signatures, which no longer hold, are replaced by the
+ * gateway's own EdDSA signature (kid: its did:key).
+ */
+export declare function rewriteAgentCard(card: Record<string, unknown>, o: {
+    gatewayUrl: string;
+    signer: {
+        kid: string;
+        seed: Uint8Array;
+    };
+}): Record<string, unknown>;
+/** The JWK of a gateway's Ed25519 did:key, to check a card it rewrote with verifyAgentCard. */
+export declare function gatewayCardKey(did: string): Jwk;
+/** The A2A method and task a REST call is, or undefined for a path that isn't one of A2A's. */
+export declare function a2aRestMethod(httpMethod: string, path: string): {
+    method: string;
+    taskId?: string;
+} | undefined;
+/** §2a: a REST call's meta: the same fields as a JSON-RPC call's, with `binding: "http+json"`. */
+export declare function a2aRestRequestMeta(httpMethod: string, path: string, body: Uint8Array, headers?: {
+    version?: string | null;
+    extensions?: string | null;
+}): Meta;
+/** §2a: a REST answer's meta (a bare Task, a `{task | message}`, or one SSE event's StreamResponse). */
+export declare function a2aRestResponseMeta(bytes: Uint8Array, contentType: string | undefined): Meta;
 export {};

package/dist/a2a/index.js

@@ -3,7 +3,8 @@
 // an Agent Card's JWS signatures (A2A §8.4: detached, over the JCS card without `signatures`).
 // Mirrors sdks/python/src/zanii_blackbox/a2a.py.
 import { createHash, createPublicKey, verify } from "node:crypto";
-import { canonicalBytes } from "@zanii/core";
+import { canonicalBytes, publicKeyFromDid } from "@zanii/core";
+import { ed25519Sign } from "../transparency/index.js";
 import { assertSafeIntegers } from "../verify/envelope.js";
 /** v0.3 method names → v1.0 (A2A §9.4). */
 const LEGACY = {
@@ -200,3 +201,105 @@ export function verifyAgentCard(card, keys) {
             : "no signature is by a trusted key");
     return report;
 }
+const JSONRPC = (t) => typeof t === "string" && t.toUpperCase().replace(/[-_]/g, "") === "JSONRPC";
+/**
+ * spec/a2a.md §3a (L3): the card as the gateway serves it, so a client that follows it stays on the
+ * record: every JSON-RPC interface points at `gatewayUrl`, other bindings (which the gateway can't
+ * capture) are dropped, and the publisher's signatures, which no longer hold, are replaced by the
+ * gateway's own EdDSA signature (kid: its did:key).
+ */
+export function rewriteAgentCard(card, o) {
+    const { signatures: _drop, ...rest } = card;
+    const out = { ...rest };
+    if (Array.isArray(card.supportedInterfaces))
+        out.supportedInterfaces = card.supportedInterfaces
+            .filter((i) => i && typeof i === "object" && JSONRPC(i.protocolBinding ?? i.transport))
+            .map((i) => ({ ...i, url: o.gatewayUrl }));
+    if (typeof card.url === "string")
+        out.url = o.gatewayUrl;
+    if (card.preferredTransport !== undefined)
+        out.preferredTransport = "JSONRPC";
+    if (Array.isArray(card.additionalInterfaces))
+        out.additionalInterfaces = card.additionalInterfaces
+            .filter((i) => i && typeof i === "object" && JSONRPC(i.transport ?? i.protocolBinding))
+            .map((i) => ({ ...i, url: o.gatewayUrl }));
+    const header = b64u(new TextEncoder().encode(JSON.stringify({ alg: "EdDSA", kid: o.signer.kid, typ: "JOSE" })));
+    const input = new TextEncoder().encode(`${header}.${agentCardPayload(out)}`);
+    const signature = b64u(ed25519Sign(o.signer.seed, input));
+    return { ...out, signatures: [{ protected: header, signature }] };
+}
+/** The JWK of a gateway's Ed25519 did:key, to check a card it rewrote with verifyAgentCard. */
+export function gatewayCardKey(did) {
+    const pub = publicKeyFromDid(did);
+    if (!pub)
+        throw new Error("not an Ed25519 did:key");
+    return { kty: "OKP", crv: "Ed25519", x: b64u(pub), kid: did };
+}
+// ---------------------------------------------------------------- the HTTP+JSON binding (§2a, L8)
+/** A2A §11's REST routes, by HTTP method and path (after the agent's base, an optional `/v1`). */
+const REST = [
+    ["POST", /^\/message:send$/, "SendMessage"],
+    ["POST", /^\/message:stream$/, "SendStreamingMessage"],
+    ["GET", /^\/tasks$/, "ListTasks"],
+    ["GET", /^\/tasks\/([^/:]+)$/, "GetTask"],
+    ["POST", /^\/tasks\/([^/:]+):cancel$/, "CancelTask"],
+    ["GET", /^\/tasks\/([^/:]+):subscribe$/, "SubscribeToTask"],
+    ["POST", /^\/tasks\/([^/:]+):subscribe$/, "SubscribeToTask"],
+    ["POST", /^\/tasks\/([^/:]+)\/pushNotificationConfigs$/, "CreateTaskPushNotificationConfig"],
+    ["GET", /^\/tasks\/([^/:]+)\/pushNotificationConfigs$/, "ListTaskPushNotificationConfigs"],
+    ["GET", /^\/tasks\/([^/:]+)\/pushNotificationConfigs\/[^/]+$/, "GetTaskPushNotificationConfig"],
+    [
+        "DELETE",
+        /^\/tasks\/([^/:]+)\/pushNotificationConfigs\/[^/]+$/,
+        "DeleteTaskPushNotificationConfig",
+    ],
+    ["GET", /^\/extendedAgentCard$/, "GetExtendedAgentCard"],
+];
+/** The A2A method and task a REST call is, or undefined for a path that isn't one of A2A's. */
+export function a2aRestMethod(httpMethod, path) {
+    const p = (path.split("?")[0] ?? "").replace(/^\/v1(?=\/)/, "");
+    for (const [verb, re, method] of REST) {
+        if (verb !== httpMethod.toUpperCase())
+            continue;
+        const m = re.exec(p);
+        if (m)
+            return m[1] ? { method, taskId: decodeURIComponent(m[1]) } : { method };
+    }
+    return undefined;
+}
+/** §2a: a REST call's meta: the same fields as a JSON-RPC call's, with `binding: "http+json"`. */
+export function a2aRestRequestMeta(httpMethod, path, body, headers = {}) {
+    const r = a2aRestMethod(httpMethod, path);
+    let params = {};
+    try {
+        params = obj(JSON.parse(Buffer.from(body).toString("utf8")));
+    }
+    catch { }
+    if (r?.taskId !== undefined)
+        params = { ...params, id: r.taskId };
+    const rpc = r ? { method: r.method, params } : { params };
+    return {
+        ...a2aRequestMeta(new TextEncoder().encode(JSON.stringify(rpc)), headers),
+        binding: "http+json",
+    };
+}
+/** §2a: a REST answer's meta (a bare Task, a `{task | message}`, or one SSE event's StreamResponse). */
+export function a2aRestResponseMeta(bytes, contentType) {
+    let text = Buffer.from(bytes).toString("utf8");
+    if (contentType?.includes("text/event-stream"))
+        text = text
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith("data:"))
+            .map((l) => l.slice(5).trim())
+            .join("\n");
+    let value;
+    try {
+        value = obj(JSON.parse(text));
+    }
+    catch {
+        return {};
+    }
+    const oneOf = ["task", "message", "statusUpdate", "artifactUpdate"].some((k) => k in value);
+    const result = oneOf ? value : "id" in value && "status" in value ? { task: value } : value;
+    return responseOf({ result });
+}

package/dist/agents/index.d.ts

@@ -8,6 +8,14 @@ export declare function memoryXray(lines: readonly string[], bodies: Bodies, rev
         seq: number;
         memory_id: string;
     }[];
+    chain?: {
+        ok: boolean;
+        length: number;
+        broken: Array<{
+            seq: number;
+            reason: string;
+        }>;
+    };
 };
 /** spec/agents.md §3. */
 export declare function causality(records: ReadonlyArray<readonly string[]>): {

package/dist/analysis/accuracy.d.ts

@@ -0,0 +1,24 @@
+export type Label = {
+    code: string;
+    verdict: "right" | "wrong" | "missed";
+};
+export interface Accuracy {
+    code: string;
+    right: number;
+    wrong: number;
+    missed: number;
+    /** right / (right + wrong): how often a finding was real. null with no right or wrong labels. */
+    precision: number | null;
+    /** right / (right + missed): how often a real case was found. null with neither. */
+    recall: number | null;
+    /** The Wilson 95% lower bounds of the two. */
+    precision_low: number | null;
+    recall_low: number | null;
+}
+/** The Wilson score interval's lower bound for `k` of `n`, at 95%; null when n = 0. */
+export declare function wilsonLow(k: number, n: number): number | null;
+/** §12: each code's accuracy, by code, and all codes together. */
+export declare function detectorAccuracy(labels: readonly Label[]): {
+    codes: Accuracy[];
+    overall: Accuracy;
+};

package/dist/analysis/accuracy.js

@@ -0,0 +1,45 @@
+// How right each check is (spec/findings.md §12, H5): people mark findings right or wrong, and
+// report hallucinations no check caught; from those labels, each code's precision and recall, with
+// a 95% lower bound an auditor can quote. Mirrors sdks/python/src/zanii_blackbox/analysis/
+// accuracy.py; pinned by spec/vectors/accuracy.json.
+const Z = 1.96;
+const round4 = (x) => Math.floor(x * 10_000 + 0.5) / 10_000;
+/** The Wilson score interval's lower bound for `k` of `n`, at 95%; null when n = 0. */
+export function wilsonLow(k, n) {
+    if (n === 0)
+        return null;
+    const p = k / n;
+    const z2 = Z * Z;
+    const centre = p + z2 / (2 * n);
+    const spread = Z * Math.sqrt((p * (1 - p)) / n + z2 / (4 * n * n));
+    return round4(Math.max(0, (centre - spread) / (1 + z2 / n)));
+}
+function row(code, right, wrong, missed) {
+    const judged = right + wrong;
+    const real = right + missed;
+    return {
+        code,
+        right,
+        wrong,
+        missed,
+        precision: judged ? round4(right / judged) : null,
+        recall: real ? round4(right / real) : null,
+        precision_low: wilsonLow(right, judged),
+        recall_low: wilsonLow(right, real),
+    };
+}
+/** §12: each code's accuracy, by code, and all codes together. */
+export function detectorAccuracy(labels) {
+    const counts = new Map();
+    for (const l of labels) {
+        const c = counts.get(l.code) ?? { right: 0, wrong: 0, missed: 0 };
+        c[l.verdict]++;
+        counts.set(l.code, c);
+    }
+    const codes = [...counts.keys()].sort().map((code) => {
+        const c = counts.get(code);
+        return row(code, c.right, c.wrong, c.missed);
+    });
+    const sum = (k) => codes.reduce((n, c) => n + c[k], 0);
+    return { codes, overall: row("*", sum("right"), sum("wrong"), sum("missed")) };
+}

package/dist/analysis/credential.d.ts

@@ -0,0 +1,101 @@
+import type { Bodies } from "../reconcile/record.ts";
+import { type ReferencePack } from "./reference.ts";
+export interface ClaimEntry {
+    index: number;
+    kind: string;
+    value_sha256: string;
+    status: "grounded" | "ungrounded" | "contradicted";
+    via: "pack" | "exact";
+    evidence: Array<{
+        seq: number;
+        line_hash: string;
+    }>;
+    pack?: {
+        id: string;
+        version: string;
+        hash: string;
+        fact: string;
+    };
+}
+export interface AnswerClaims {
+    seq: number;
+    line_hash: string;
+    text_sha256: string;
+    claims: ClaimEntry[];
+    service?: {
+        seq: number;
+        line_hash: string;
+        outage: true;
+    } | {
+        seq: number;
+        line_hash: string;
+        model?: string;
+        version?: string;
+        claims: Array<{
+            index: number;
+            status: string;
+            text_sha256: string;
+            score?: number;
+        }>;
+    };
+    sources: Array<{
+        seq: number;
+        id: string;
+        uri?: string;
+        version?: string;
+        sha256: string;
+    }>;
+}
+/** spec/findings.md §11: the claims of every final answer on a record. */
+export declare function answerClaims(lines: readonly string[], bodies: Bodies, packs?: readonly ReferencePack[]): AnswerClaims[];
+/** spec/findings.md §11: the credential for one answer, unsigned; null when `seq` isn't a final
+ * answer. The server signs it (`signCertificate`). */
+export declare function answerCredential(lines: readonly string[], bodies: Bodies, seq: number, o: {
+    sessionId: string;
+    packs?: readonly ReferencePack[];
+}): {
+    v: number;
+    type: string;
+    session_id: string;
+    answer: {
+        seq: number;
+        line_hash: string;
+        text_sha256: string;
+    };
+    claims: ClaimEntry[];
+    service?: {
+        seq: number;
+        line_hash: string;
+        outage: true;
+    } | {
+        seq: number;
+        line_hash: string;
+        model?: string;
+        version?: string;
+        claims: Array<{
+            index: number;
+            status: string;
+            text_sha256: string;
+            score?: number;
+        }>;
+    };
+    sources: {
+        seq: number;
+        id: string;
+        uri?: string;
+        version?: string;
+        sha256: string;
+    }[];
+    packs: {
+        id: string;
+        version: string;
+        hash: string;
+    }[];
+    issued_at: string;
+} | null;
+/** §11: a credential checked against the record it names: recomputed, then compared field by field
+ * (the signature is `verifyCertificate`'s job). */
+export declare function verifyAnswerCredential(credential: Record<string, unknown>, lines: readonly string[], bodies: Bodies, packs?: readonly ReferencePack[]): {
+    ok: boolean;
+    problems: string[];
+};

package/dist/analysis/credential.js

@@ -0,0 +1,142 @@
+// The claim record and answer credentials (spec/findings.md §11, H3): for each final answer, every
+// fact in it, how it was checked (a pack, the record, the grounding service) and the record lines
+// that hold its evidence; and a credential for one answer that anyone holding the record can check.
+// Mirrors sdks/python/src/zanii_blackbox/analysis/credential.py; pinned by
+// spec/vectors/credential.json.
+import { createHash } from "node:crypto";
+import { canonical } from "../reconcile/shared.js";
+import { hashLine } from "../verify/envelope.js";
+import { answersOf, factsIn, parseGroundingAnswer } from "./grounding.js";
+import { checkAgainstPacks } from "./reference.js";
+const sha = (s) => `sha256:${createHash("sha256").update(s).digest("hex")}`;
+const decoder = new TextDecoder();
+/** spec/findings.md §11: the claims of every final answer on a record. */
+export function answerClaims(lines, bodies, packs = []) {
+    const hashes = new Map();
+    const verdicts = new Map();
+    const retrieved = [];
+    for (const l of lines) {
+        const e = JSON.parse(l);
+        hashes.set(e.seq, hashLine(l));
+        if (e.kind === "control" &&
+            e.meta.action === "grounding" &&
+            typeof e.meta.answer_seq === "number")
+            verdicts.set(e.meta.answer_seq, e); // the latest verdict for an answer is its verdict
+        if (e.kind === "sdk.event" && e.meta.type === "retrieved") {
+            const b = bodies(e.body_hash);
+            try {
+                const d = b ? JSON.parse(decoder.decode(b)) : {};
+                if (Array.isArray(d.docs))
+                    retrieved.push({ seq: e.seq, docs: d.docs });
+            }
+            catch { }
+        }
+    }
+    const at = (seq) => ({ seq, line_hash: hashes.get(seq) });
+    return answersOf(lines, bodies).map((a) => {
+        const claims = factsIn(a.text).map((f, index) => {
+            const base = { index, kind: f.kind, value_sha256: sha(f.value) };
+            const said = checkAgainstPacks(a.text, f, packs);
+            if (said) {
+                const pack = {
+                    id: said.pack.id,
+                    version: said.pack.version,
+                    hash: said.pack.hash,
+                    fact: said.fact.id,
+                };
+                return { ...base, status: said.status, via: "pack", evidence: [], pack };
+            }
+            const seqs = a.evidence.support(f);
+            return seqs
+                ? { ...base, status: "grounded", via: "exact", evidence: seqs.map(at) }
+                : { ...base, status: "ungrounded", via: "exact", evidence: [] };
+        });
+        const v = verdicts.get(a.seq);
+        let service;
+        if (v?.meta.outage === true)
+            service = { ...at(v.seq), outage: true };
+        else if (v) {
+            const b = bodies(v.body_hash);
+            let parsed = null;
+            try {
+                parsed = b ? parseGroundingAnswer(JSON.parse(decoder.decode(b))) : null;
+            }
+            catch { }
+            if (parsed)
+                service = {
+                    ...at(v.seq),
+                    ...(parsed.model ? { model: parsed.model } : {}),
+                    ...(parsed.version ? { version: parsed.version } : {}),
+                    claims: parsed.claims.map((c, index) => ({
+                        index,
+                        status: c.status,
+                        text_sha256: sha(c.text),
+                        ...(c.score !== undefined ? { score: c.score } : {}),
+                    })),
+                };
+        }
+        const sources = retrieved
+            .filter((r) => r.seq < a.seq)
+            .flatMap((r) => r.docs.flatMap((d) => {
+            const o = d;
+            if (typeof o.id !== "string" || typeof o.sha256 !== "string")
+                return [];
+            return [
+                {
+                    seq: r.seq,
+                    id: o.id,
+                    ...(typeof o.uri === "string" ? { uri: o.uri } : {}),
+                    ...(typeof o.version === "string" ? { version: o.version } : {}),
+                    sha256: o.sha256,
+                },
+            ];
+        }));
+        return {
+            ...at(a.seq),
+            text_sha256: sha(a.text),
+            claims,
+            ...(service ? { service } : {}),
+            sources,
+        };
+    });
+}
+/** spec/findings.md §11: the credential for one answer, unsigned; null when `seq` isn't a final
+ * answer. The server signs it (`signCertificate`). */
+export function answerCredential(lines, bodies, seq, o) {
+    const packs = o.packs ?? [];
+    const entry = answerClaims(lines, bodies, packs).find((x) => x.seq === seq);
+    if (!entry)
+        return null;
+    const ts = lines.map((l) => JSON.parse(l)).find((e) => e.seq === seq)?.ts;
+    return {
+        v: 1,
+        type: "answer_credential",
+        session_id: o.sessionId,
+        answer: { seq: entry.seq, line_hash: entry.line_hash, text_sha256: entry.text_sha256 },
+        claims: entry.claims,
+        ...(entry.service ? { service: entry.service } : {}),
+        sources: entry.sources,
+        packs: packs.map((p) => ({ id: p.id, version: p.version, hash: p.hash })),
+        issued_at: ts,
+    };
+}
+/** §11: a credential checked against the record it names: recomputed, then compared field by field
+ * (the signature is `verifyCertificate`'s job). */
+export function verifyAnswerCredential(credential, lines, bodies, packs = []) {
+    const answer = credential.answer;
+    if (typeof answer?.seq !== "number" || typeof credential.session_id !== "string")
+        return { ok: false, problems: ["malformed"] };
+    const again = answerCredential(lines, bodies, answer.seq, {
+        sessionId: credential.session_id,
+        packs,
+    });
+    if (!again)
+        return { ok: false, problems: ["the record has no such answer"] };
+    const problems = [];
+    const fields = new Set([...Object.keys(again), ...Object.keys(credential)]);
+    fields.delete("signed");
+    for (const k of [...fields].sort())
+        if (canonical(again[k] ?? null) !== canonical(credential[k] ?? null))
+            problems.push(`${k} differs from the record`);
+    return { ok: problems.length === 0, problems };
+}