@zanii/blackbox 0.3.0 → 0.4.0

package/dist/policy/zanii.js

@@ -0,0 +1,87 @@
+// Zanii's policy format, in and out (spec/policy.md §8). A rule that can't be said the same way on
+// the other side is skipped and named, never loosened: dropping a condition would widen what a rule
+// denies or allows. Pure; mirrors sdks/python/src/zanii_blackbox/policy_zanii.py; pinned by
+// spec/vectors/policy-zanii.json.
+const EFFECTS = new Set(["deny", "allow", "require_approval"]);
+const idOf = (raw, n) => {
+    const s = String(raw ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+    return s || `rule-${n + 1}`;
+};
+/** A Zanii target as a Blackbox tool pattern, or null (`mcp.<server>.<tool>`, `mcp.<server>.*`, `*`). */
+function toolOf(target) {
+    if (target === "*" || target === "mcp.*")
+        return target === "*" ? "*" : "mcp__*";
+    const m = /^mcp\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_.*-]+)$/.exec(target);
+    return m ? `mcp__${m[1]}__${m[2]}` : null;
+}
+/** A Blackbox tool pattern as a Zanii target, or null (a bare tool name matches any server). */
+function targetOf(tool) {
+    if (tool === "*")
+        return "*";
+    if (tool === "mcp__*")
+        return "mcp.*";
+    const m = /^mcp__([A-Za-z0-9_-]+?)__(.+)$/.exec(tool);
+    return m ? `mcp.${m[1]}.${m[2]}` : null;
+}
+/** Zanii → Blackbox: `{policy: {version: 1, rules}, skipped}`. */
+export function fromZaniiPolicy(z) {
+    const p = (z ?? {});
+    const rules = [];
+    const skipped = [];
+    const list = Array.isArray(p.rules) ? p.rules : [];
+    for (const [n, r] of list.entries()) {
+        const id = idOf(r.id, n);
+        const skip = (reason) => skipped.push({ id, reason });
+        if (!EFFECTS.has(String(r.effect)))
+            skip(`effect ${String(r.effect)}`);
+        else if (r.where !== undefined)
+            skip("conditions on the payload (where) have no exact Blackbox form");
+        else if (r.rateLimit !== undefined)
+            skip("rate limits are not tool policy (use the session limits)");
+        else {
+            const targets = Array.isArray(r.targets) ? r.targets.map(String) : ["*"];
+            const tools = targets.map(toolOf);
+            const bad = targets.filter((_, i) => tools[i] === null);
+            if (bad.length)
+                skip(`not an MCP tool target: ${bad.join(", ")}`);
+            else
+                for (const [i, tool] of tools.entries())
+                    rules.push({
+                        id: tools.length > 1 ? `${id}-${i + 1}`.slice(0, 64) : id,
+                        tool: tool,
+                        action: String(r.effect),
+                    });
+        }
+    }
+    if (p.default === "deny")
+        rules.push({ id: "zanii-default", tool: "*", action: "deny" });
+    return { policy: { version: 1, rules }, skipped };
+}
+/** Blackbox → Zanii: `{policy: {default: "allow", rules}, skipped}`. */
+export function toZaniiPolicy(ours) {
+    const p = (ours ?? {});
+    const rules = [];
+    const skipped = [];
+    for (const r of (Array.isArray(p.rules) ? p.rules : [])) {
+        const id = String(r.id);
+        const extra = ["args_match", "hints", "environment"].filter((k) => r[k] !== undefined);
+        if (r.audit === true)
+            skipped.push({ id, reason: "an audit-only rule decides nothing" });
+        else if (r.action === "require_proof")
+            skipped.push({ id, reason: "Zanii has no require_proof effect" });
+        else if (extra.length)
+            skipped.push({ id, reason: `${extra.join(", ")} have no Zanii form` });
+        else {
+            const target = targetOf(String(r.tool));
+            if (target === null)
+                skipped.push({ id, reason: `a bare tool name matches any server: ${String(r.tool)}` });
+            else
+                rules.push({ id, effect: String(r.action), targets: [target] });
+        }
+    }
+    return { policy: { default: "allow", rules }, skipped };
+}

package/dist/pq/index.d.ts

@@ -0,0 +1,23 @@
+type Obj = Record<string, unknown>;
+export declare const PQ_ALG = "ML-DSA-65";
+/** The ML-DSA-65 seed for a gateway identity: HMAC-SHA256(its Ed25519 key, a fixed label). */
+export declare const pqSeedOf: (identityPrivateKey: Uint8Array) => Uint8Array;
+/** The raw ML-DSA-65 public key (1952 bytes) for a 32-byte seed. */
+export declare const pqPublicKey: (seed: Uint8Array) => Uint8Array;
+/** Whether this runtime has ML-DSA-65 (Node ≥ 24.6 with OpenSSL ≥ 3.5). */
+export declare function pqAvailable(): boolean;
+/** Zanii's pq.binding: both keys sign the same body, so holding one key can't forge it. */
+export declare function bindPqKey(o: {
+    did: string;
+    ts: string;
+    edPrivateKey: Uint8Array;
+    pqSeed: Uint8Array;
+}): Obj;
+/** Zanii's check: the structure, and BOTH signatures over the same body. */
+export declare function verifyPqBinding(binding: unknown): {
+    ok: boolean;
+    reasons: string[];
+};
+/** Zanii's transition payload, recorded UNSALTED: the binding as compact JSON. */
+export declare function pqTransitionPayload(binding: Obj): string;
+export {};

package/dist/pq/index.js

@@ -0,0 +1,104 @@
+// Post-quantum binding of the gateway identity (spec/anchoring.md §13): Zanii's pq.binding, an
+// ML-DSA-65 key (FIPS 204) bound to a did:key and signed by both keys, and the unsalted transition
+// payload anchored to prove the binding existed before any break of Ed25519 (@zanii/pq). Needs
+// Node ≥ 24.6 for ML-DSA. Pure; mirrors sdks/python/src/zanii_blackbox/pq.py; pinned by
+// spec/vectors/pq-binding.json.
+import { createHmac, createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+import { canonicalBytes, publicKeyFromDid } from "@zanii/core";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+export const PQ_ALG = "ML-DSA-65";
+const SEED_INFO = "zanii-blackbox identity ml-dsa-65 v1";
+const PKCS8 = Buffer.from("3034020100300b060960864801650304031204228020", "hex");
+const SPKI = Buffer.from("308207b2300b0609608648016503040312038207a100", "hex");
+/** The ML-DSA-65 seed for a gateway identity: HMAC-SHA256(its Ed25519 key, a fixed label). */
+export const pqSeedOf = (identityPrivateKey) => new Uint8Array(createHmac("sha256", identityPrivateKey).update(SEED_INFO).digest());
+const privateKey = (seed) => {
+    if (seed.length !== 32)
+        throw new Error("an ML-DSA-65 seed is 32 bytes");
+    return createPrivateKey({ key: Buffer.concat([PKCS8, seed]), format: "der", type: "pkcs8" });
+};
+/** The raw ML-DSA-65 public key (1952 bytes) for a 32-byte seed. */
+export const pqPublicKey = (seed) => new Uint8Array(createPublicKey(privateKey(seed)).export({ format: "der", type: "spki" }).subarray(SPKI.length));
+/** Whether this runtime has ML-DSA-65 (Node ≥ 24.6 with OpenSSL ≥ 3.5). */
+export function pqAvailable() {
+    try {
+        pqPublicKey(new Uint8Array(32));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const validTs = (ts) => typeof ts === "string" && !Number.isNaN(Date.parse(ts));
+const hex = (b) => Buffer.from(b).toString("hex");
+/** Zanii's pq.binding: both keys sign the same body, so holding one key can't forge it. */
+export function bindPqKey(o) {
+    if (!o.did)
+        throw new Error("did is required");
+    if (!validTs(o.ts))
+        throw new Error("ts must be an ISO timestamp");
+    const unsigned = {
+        v: 1,
+        type: "pq.binding",
+        did: o.did,
+        alg: PQ_ALG,
+        pq_pub: hex(pqPublicKey(o.pqSeed)),
+        ts: o.ts,
+    };
+    const raw = canonicalBytes(unsigned);
+    return {
+        ...unsigned,
+        sig_ed: `ed25519:${hex(ed25519Sign(o.edPrivateKey, raw))}`,
+        sig_pq: `mldsa65:${hex(sign(null, raw, privateKey(o.pqSeed)))}`,
+    };
+}
+const pqVerify = (publicKey, msg, sig) => {
+    try {
+        const key = createPublicKey({
+            key: Buffer.concat([SPKI, publicKey]),
+            format: "der",
+            type: "spki",
+        });
+        return verify(null, msg, key, sig);
+    }
+    catch {
+        return false;
+    }
+};
+/** Zanii's check: the structure, and BOTH signatures over the same body. */
+export function verifyPqBinding(binding) {
+    const b = (binding ?? {});
+    const reasons = [];
+    if (b.v !== 1 || b.type !== "pq.binding")
+        reasons.push("not a pq.binding (v1)");
+    if (b.alg !== PQ_ALG)
+        reasons.push("unsupported alg (want ML-DSA-65)");
+    if (!b.did)
+        reasons.push("missing did");
+    const pqPub = typeof b.pq_pub === "string" && /^([0-9a-f]{2})+$/.test(b.pq_pub)
+        ? new Uint8Array(Buffer.from(b.pq_pub, "hex"))
+        : null;
+    if (!pqPub)
+        reasons.push("missing/invalid pq_pub");
+    if (!validTs(b.ts))
+        reasons.push("missing/invalid ts");
+    if (reasons.length > 0 || !pqPub)
+        return { ok: false, reasons };
+    const { sig_ed: sigEd, sig_pq: sigPq, ...unsigned } = b;
+    const raw = canonicalBytes(unsigned);
+    const pub = publicKeyFromDid(String(b.did));
+    const ed = typeof sigEd === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(sigEd) : null;
+    if (!pub || !ed || !ed25519Verify(pub, raw, Buffer.from(ed[1], "hex")))
+        reasons.push("Ed25519 signature does not verify against the did");
+    const pq = typeof sigPq === "string" ? /^mldsa65:((?:[0-9a-f]{2})+)$/.exec(sigPq) : null;
+    if (!pq || !pqVerify(pqPub, raw, Buffer.from(pq[1], "hex")))
+        reasons.push("ML-DSA signature does not verify against pq_pub (possession not proven)");
+    return { ok: reasons.length === 0, reasons };
+}
+/** Zanii's transition payload, recorded UNSALTED: the binding as compact JSON. */
+export function pqTransitionPayload(binding) {
+    const check = verifyPqBinding(binding);
+    if (!check.ok)
+        throw new Error(`refusing to anchor an invalid binding: ${check.reasons.join("; ")}`);
+    return JSON.stringify(binding);
+}

package/dist/search/index.d.ts

@@ -0,0 +1,23 @@
+export interface SearchQuery {
+    /** An event kind, e.g. `tool.call`, `finding`, `control`. */
+    kind?: string;
+    /** A tool's name, as called: `delete_record`, `mcp__db__delete_record`, an SDK tool. */
+    tool?: string;
+    /** A finding code, e.g. `TOOL_CHANGED`. */
+    code?: string;
+    /** A person who decided an approval or a grant: their `sub`, `email` (any case) or `name`. */
+    person?: string;
+    /** The session's environment (`session.open` meta.environment). */
+    environment?: string;
+}
+export interface SearchMatch {
+    seq: number;
+    kind: string;
+    ts: string;
+    /** What matched: the tool, the code, the person, or the kind. */
+    match: string;
+}
+/** The query's fields, checked: each a 1-256 character string; `environment` alone is allowed. */
+export declare function checkSearch(q: Record<string, unknown>): string | undefined;
+/** Every event of the record that matches all of the query's fields, in seq order. */
+export declare function searchEvents(lines: readonly string[], q: SearchQuery): SearchMatch[];

package/dist/search/index.js

@@ -0,0 +1,69 @@
+// Structured search over a session's record (spec/search.md): exact matches on what the events say
+// (a tool, a fault code, a person, an event kind, the session's environment), never text inside
+// bodies. Precise by construction, and it reads nothing that was redacted. Pure; mirrors
+// sdks/python/src/zanii_blackbox/search.py; pinned by spec/vectors/search.json.
+const DECISIONS = new Set(["approval", "approval_vote", "permission"]);
+/** The query's fields, checked: each a 1-256 character string; `environment` alone is allowed. */
+export function checkSearch(q) {
+    const fields = ["kind", "tool", "code", "person", "environment"];
+    for (const k of Object.keys(q))
+        if (!fields.includes(k))
+            return `unknown search field ${JSON.stringify(k)}`;
+    for (const k of fields) {
+        const v = q[k];
+        if (v !== undefined && (typeof v !== "string" || v.length < 1 || v.length > 256))
+            return `${k} must be 1-256 characters`;
+    }
+    return fields.some((k) => q[k] !== undefined)
+        ? undefined
+        : "give kind, tool, code, person or environment";
+}
+function toolOf(e) {
+    if (e.kind === "tool.call" && typeof e.meta.tool === "string")
+        return typeof e.meta.server === "string"
+            ? [e.meta.tool, `mcp__${e.meta.server}__${e.meta.tool}`]
+            : [e.meta.tool];
+    if (e.kind === "sdk.event" && e.meta.type === "tool.call" && typeof e.meta.name === "string")
+        return [e.meta.name];
+    return [];
+}
+function personMatch(e, who) {
+    if (e.kind !== "control" || !DECISIONS.has(String(e.meta.action)))
+        return false;
+    const p = e.meta.person;
+    if (!p)
+        return false;
+    return (p.sub === who ||
+        p.name === who ||
+        (typeof p.email === "string" && p.email.toLowerCase() === who.toLowerCase()));
+}
+/** Every event of the record that matches all of the query's fields, in seq order. */
+export function searchEvents(lines, q) {
+    const events = lines.map((l) => JSON.parse(l));
+    const open = events.find((e) => e.kind === "session.open");
+    if (q.environment !== undefined && open?.meta.environment !== q.environment)
+        return [];
+    const eventWise = q.kind !== undefined || q.tool !== undefined || q.code !== undefined || q.person !== undefined;
+    if (!eventWise)
+        return open
+            ? [{ seq: open.seq, kind: open.kind, ts: open.ts, match: q.environment }]
+            : [];
+    const out = [];
+    for (const e of events) {
+        if (q.kind !== undefined && e.kind !== q.kind)
+            continue;
+        if (q.tool !== undefined && !toolOf(e).includes(q.tool))
+            continue;
+        if (q.code !== undefined && !(e.kind === "finding" && e.meta.code === q.code))
+            continue;
+        if (q.person !== undefined && !personMatch(e, q.person))
+            continue;
+        out.push({
+            seq: e.seq,
+            kind: e.kind,
+            ts: e.ts,
+            match: q.tool ?? q.code ?? q.person ?? q.kind,
+        });
+    }
+    return out;
+}

package/dist/session/index.d.ts

@@ -1,4 +1,5 @@
 import { type Attestation } from "../attest/index.ts";
+import { buildPayment, type screenCounterparty } from "../finance/index.ts";
 export interface SessionOptions {
     /** The gateway, e.g. http://127.0.0.1:8787 */
     url: string;
@@ -33,6 +34,8 @@ export interface SessionOptions {
     tenant?: string;
     /** spec/authority.md: `supervised` from the start (risky actions wait for a second person). */
     authority?: "agent" | "supervised";
+    /** spec/api.md: where it runs (`production`, `staging`, …); policy rules can match it. */
+    environment?: string;
     /** spec/preflight.md: the equipment the run needs. A no-go returns a disabled session (and
      * `stats.lastError` says why); optional items that are down show in `state().degraded`. */
     preflight?: {
@@ -144,6 +147,10 @@ export declare class BlackboxSession {
     private timers;
     private closed;
     private landings;
+    /** spec/approvals.md §2: approved tools with arguments, until their call is reported. */
+    private approved;
+    /** spec/agents.md §4: the memory chain's tip. */
+    private memoryLast;
     /** A session that records nothing. `reason`, when opening failed, goes to `stats.lastError` (audit K1). */
     static disabled(options: SessionOptions, reason?: string): BlackboxSession;
     private readonly options;
@@ -161,6 +168,67 @@ export declare class BlackboxSession {
         };
     }): void;
     step(name: string, data?: Record<string, unknown>): void;
+    /**
+     * spec/gov.md §2: a decision about a person, under the rulebook `manifestHash`, the person named
+     * only by their subject tag. Returns the factors' nonce (keep it to disclose them in a dispute).
+     * Throws on a decision that can't be lawful evidence: no rulebook, a bad kind, no tag.
+     */
+    decision(kind: string, o: {
+        manifestHash: string;
+        outcome: Record<string, unknown>;
+        subjectTag: string;
+        factors?: Record<string, unknown>;
+        appealBy?: string;
+    }): {
+        nonce: string;
+    };
+    /** spec/health.md §2: who accessed a patient's record (an episode tag, never the seed), and why. */
+    healthAccess(o: {
+        episodeTag: string;
+        actor: string;
+        purpose: string;
+        consentRef?: string;
+        details?: Record<string, unknown>;
+    }): {
+        nonce: string;
+    };
+    /** spec/health.md §2: a model's recommendation under a protocol. `hash` is what the clinician signs. */
+    recommendation(o: {
+        episodeTag: string;
+        modelId: string;
+        manifestHash: string;
+        outcome: Record<string, unknown>;
+        runtimeHash?: string;
+        deviation?: Record<string, unknown>;
+    }): {
+        nonce: string;
+        hash: string;
+    };
+    /** spec/health.md §2: a clinician's signed confirmation (clinicianConfirmation). Throws on a bad signature. */
+    clinicianConfirmation(episodeTag: string, payload: Record<string, unknown>): void;
+    /** spec/health.md §2: an emergency access, signed by the clinician (breakGlass). Loud on purpose. */
+    breakGlass(episodeTag: string, payload: Record<string, unknown>): void;
+    private signedHealth;
+    /** spec/finance.md §2: a payment, exact (minor units), with its settlement reference. Throws on a bad amount. */
+    payment(input: Parameters<typeof buildPayment>[0]): void;
+    /** spec/finance.md §3: a counterparty screening (screenCounterparty), before paying them. */
+    screening(result: ReturnType<typeof screenCounterparty>): void;
+    /** spec/finance.md §4: a tax filing the agent prepared. It never files; a Tax Agent does. */
+    ftaPrepared(o: {
+        filingType: string;
+        period: string;
+        filingRef?: string;
+        manifestHash?: string;
+        by?: string;
+    }): void;
+    /** spec/finance.md §4: the prepared filing handed to a licensed Tax Agent. */
+    ftaHandoff(o: {
+        filingType: string;
+        period: string;
+        toTaxAgent: string;
+        filingRef?: string;
+        by?: string;
+    }): void;
     toolCall(name: string, args?: unknown): void;
     toolResult(name: string, result?: {
         ok?: boolean;
@@ -200,6 +268,15 @@ export declare class BlackboxSession {
         summary?: string;
         file_path?: string;
     }): void;
+    /** spec/findings.md §11 (H3): pin the documents the agent read, by hash; the content never leaves.
+     * Each doc is `{id, uri?, version?}` with its `content` (hashed here) or its `sha256`. */
+    retrieved(docs: ReadonlyArray<{
+        id: string;
+        uri?: string;
+        version?: string;
+        content?: string | Uint8Array;
+        sha256?: string;
+    }>): void;
     /** Stage 2 R3: the result of one of the customer's own checks (tests, a schema, a policy, a
      * partial goal), mid-run or at the end. A pass then a fail is VERIFY_REGRESSION; a success whose last
      * check failed is FALSE_SUCCESS (spec/findings.md §6). */
@@ -234,7 +311,18 @@ export declare class BlackboxSession {
         height?: number;
     }): void;
     /** spec/agents.md §1: the agent's memory store wrote, revoked or returned memories. */
-    memoryWrite(memoryId: string, summary?: string): void;
+    /** spec/agents.md §4: with `content`, the write also carries Zanii's memory entry (a salted
+     * commitment, chained after `prev`, else this session's last entry). Keep the salt it returns. */
+    memoryWrite(memoryId: string, summary?: string, opts?: {
+        content: string;
+        kind?: string;
+        prev?: Record<string, unknown>;
+        agent?: string;
+        tags?: string[];
+    }): {
+        entry: Record<string, unknown>;
+        salt: string;
+    } | undefined;
     memoryRevoke(memoryId: string, reason?: string): void;
     memoryRead(memoryIds: string[], query?: string): void;
     /** Ships what's pending now. Resolves true when everything recorded is acknowledged. With

package/dist/session/index.js

@@ -6,7 +6,19 @@ import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { argsHash } from "../approvals/index.js";
 import { attest, isReadOnly } from "../attest/index.js";
+import { buildPayment, ftaPayload, screeningPayload, } from "../finance/index.js";
+import { decisionPayload } from "../gov/index.js";
+import { accessPayload, checkEpisodeTag, recommendationPayload, verifyHealthSignature, } from "../health/index.js";
+import { memoryEntry } from "../memory/index.js";
+/** spec/preflight.md §1 (L3): with an `egress` item, the SDK checks it here, on the agent's host. */
+async function withEgress(p) {
+    if (![...(p.require ?? []), ...(p.optional ?? [])].includes("egress"))
+        return p;
+    const { url, open } = await checkEgress({ timeoutMs: 3000 });
+    return { ...p, egress: { url, open } };
+}
 /** spec/data.md §6: a direct HTTPS request to `url` (default https://example.com). Never throws. */
 export async function checkEgress(options = {}) {
     const url = options.url ?? "https://example.com";
@@ -71,7 +83,8 @@ export async function session(options) {
                 ...(o.replay ? { replay: o.replay } : {}),
                 ...(o.tenant ? { tenant: o.tenant } : {}),
                 ...(o.authority ? { authority: o.authority } : {}),
-                ...(o.preflight ? { preflight: o.preflight } : {}),
+                ...(o.environment ? { environment: o.environment } : {}),
+                ...(o.preflight ? { preflight: await withEgress(o.preflight) } : {}),
                 ...(o.drill ? { drill: o.drill } : {}),
                 sdk: true, // this SDK will report the session's model calls (L2.3.2)
             });
@@ -103,6 +116,10 @@ export class BlackboxSession {
     timers = [];
     closed = false;
     landings = 0;
+    /** spec/approvals.md §2: approved tools with arguments, until their call is reported. */
+    approved = new Map();
+    /** spec/agents.md §4: the memory chain's tip. */
+    memoryLast = null;
     /** A session that records nothing. `reason`, when opening failed, goes to `stats.lastError` (audit K1). */
     static disabled(options, reason) {
         const s = new BlackboxSession(options, "", "", false);
@@ -208,8 +225,82 @@ export class BlackboxSession {
     step(name, data) {
         this.event("step", name, data);
     }
+    /**
+     * spec/gov.md §2: a decision about a person, under the rulebook `manifestHash`, the person named
+     * only by their subject tag. Returns the factors' nonce (keep it to disclose them in a dispute).
+     * Throws on a decision that can't be lawful evidence: no rulebook, a bad kind, no tag.
+     */
+    decision(kind, o) {
+        if (!/^sha256:[0-9a-f]{64}$/.test(o.subjectTag))
+            throw new Error("subjectTag must be a subject tag (subjectTag(did, authority))");
+        const { payload, nonce } = decisionPayload({
+            kind,
+            manifestHash: o.manifestHash,
+            outcome: o.outcome,
+            ts: new Date().toISOString(),
+            ...(o.factors !== undefined ? { factors: o.factors } : {}),
+            ...(o.appealBy !== undefined ? { appealBy: o.appealBy } : {}),
+        });
+        this.event("decision", kind, { decision: payload, subject_tag: o.subjectTag });
+        return { nonce };
+    }
+    /** spec/health.md §2: who accessed a patient's record (an episode tag, never the seed), and why. */
+    healthAccess(o) {
+        const tag = checkEpisodeTag(o.episodeTag);
+        const { payload, nonce } = accessPayload({ ...o, ts: new Date().toISOString() });
+        this.event("health.access", "access", { payload, episode_tag: tag });
+        return { nonce };
+    }
+    /** spec/health.md §2: a model's recommendation under a protocol. `hash` is what the clinician signs. */
+    recommendation(o) {
+        const tag = checkEpisodeTag(o.episodeTag);
+        const { payload, nonce, hash } = recommendationPayload({ ...o, ts: new Date().toISOString() });
+        this.event("health.recommendation", "recommendation", { payload, episode_tag: tag });
+        return { nonce, hash };
+    }
+    /** spec/health.md §2: a clinician's signed confirmation (clinicianConfirmation). Throws on a bad signature. */
+    clinicianConfirmation(episodeTag, payload) {
+        this.signedHealth(episodeTag, payload, "confirmation");
+    }
+    /** spec/health.md §2: an emergency access, signed by the clinician (breakGlass). Loud on purpose. */
+    breakGlass(episodeTag, payload) {
+        this.signedHealth(episodeTag, payload, "break_glass");
+    }
+    signedHealth(episodeTag, payload, kind) {
+        const tag = checkEpisodeTag(episodeTag);
+        if (payload.kind !== kind || !verifyHealthSignature(payload, tag))
+            throw new Error(`not a ${kind} signed by the clinician it names, for this episode`);
+        this.event(`health.${kind}`, kind, { payload, episode_tag: tag });
+    }
+    /** spec/finance.md §2: a payment, exact (minor units), with its settlement reference. Throws on a bad amount. */
+    payment(input) {
+        this.event("payment", input.rail, buildPayment(input));
+    }
+    /** spec/finance.md §3: a counterparty screening (screenCounterparty), before paying them. */
+    screening(result) {
+        this.event("kya.screening", result.did, screeningPayload(result, new Date().toISOString(), this.id));
+    }
+    /** spec/finance.md §4: a tax filing the agent prepared. It never files; a Tax Agent does. */
+    ftaPrepared(o) {
+        this.event("fta.prepared", o.filingType, ftaPayload({ ...o, action: "prepared", by: o.by ?? this.id }));
+    }
+    /** spec/finance.md §4: the prepared filing handed to a licensed Tax Agent. */
+    ftaHandoff(o) {
+        this.event("fta.handoff", o.filingType, ftaPayload({ ...o, action: "handoff", by: o.by ?? this.id }));
+    }
     toolCall(name, args) {
-        this.event("tool.call", name, args === undefined ? undefined : { args });
+        // spec/approvals.md §2: the first call after an approval names it, with what it ran
+        const approvalId = this.approved.get(name);
+        if (approvalId !== undefined)
+            this.approved.delete(name);
+        this.event("tool.call", name, args === undefined && approvalId === undefined
+            ? undefined
+            : {
+                ...(args !== undefined ? { args } : {}),
+                ...(approvalId !== undefined
+                    ? { approval_id: approvalId, args_sha256: argsHash(args ?? null) }
+                    : {}),
+            });
     }
     toolResult(name, result) {
         this.event("tool.result", name, result);
@@ -277,6 +368,30 @@ export class BlackboxSession {
     contextChange(change) {
         this.event("context.change", change.kind, { ...change });
     }
+    /** spec/findings.md §11 (H3): pin the documents the agent read, by hash; the content never leaves.
+     * Each doc is `{id, uri?, version?}` with its `content` (hashed here) or its `sha256`. */
+    retrieved(docs) {
+        const out = [];
+        for (const d of docs.slice(0, 100)) {
+            if (typeof d?.id !== "string" || d.id.length < 1)
+                continue;
+            const bytes = typeof d.content === "string" ? Buffer.from(d.content) : d.content;
+            const sha256 = bytes
+                ? `sha256:${createHash("sha256").update(bytes).digest("hex")}`
+                : d.sha256;
+            if (typeof sha256 !== "string" || !/^sha256:[0-9a-f]{64}$/.test(sha256))
+                continue;
+            out.push({
+                id: d.id.slice(0, 256),
+                ...(typeof d.uri === "string" ? { uri: d.uri.slice(0, 2048) } : {}),
+                ...(typeof d.version === "string" ? { version: d.version.slice(0, 128) } : {}),
+                sha256,
+                ...(bytes ? { bytes: bytes.length } : {}),
+            });
+        }
+        if (out.length)
+            this.event("retrieved", undefined, { docs: out });
+    }
     /** Stage 2 R3: the result of one of the customer's own checks (tests, a schema, a policy, a
      * partial goal), mid-run or at the end. A pass then a fail is VERIFY_REGRESSION; a success whose last
      * check failed is FALSE_SUCCESS (spec/findings.md §6). */
@@ -338,8 +453,22 @@ export class BlackboxSession {
         this.event("screen", undefined, data, { attachment: { contentType: type, bytes: image } });
     }
     /** spec/agents.md §1: the agent's memory store wrote, revoked or returned memories. */
-    memoryWrite(memoryId, summary) {
-        this.event("memory.write", undefined, { memory_id: memoryId, ...(summary ? { summary } : {}) });
+    /** spec/agents.md §4: with `content`, the write also carries Zanii's memory entry (a salted
+     * commitment, chained after `prev`, else this session's last entry). Keep the salt it returns. */
+    memoryWrite(memoryId, summary, opts) {
+        const data = { memory_id: memoryId, ...(summary ? { summary } : {}) };
+        let made;
+        if (opts) {
+            made = memoryEntry({
+                ...opts,
+                ts: new Date().toISOString(),
+                prev: opts.prev ?? this.memoryLast,
+            });
+            this.memoryLast = made.payload;
+            data.entry = made.payload;
+        }
+        this.event("memory.write", undefined, data);
+        return made && { entry: made.payload, salt: made.salt };
     }
     memoryRevoke(memoryId, reason) {
         this.event("memory.revoke", undefined, { memory_id: memoryId, ...(reason ? { reason } : {}) });
@@ -396,17 +525,20 @@ export class BlackboxSession {
      * and waits (polling) for the answer. Never throws. Only `"approved"` means go ahead; anything
      * else (`rejected`, `timeout`, or `error` when the gateway can't be asked) means don't. */
     async requestApproval(tool, options = {}) {
-        return this.ask("approvals", { tool, ...(options.args ? { args: options.args } : {}) }, options);
+        const { status, id } = await this.ask("approvals", { tool, ...(options.args ? { args: options.args } : {}) }, options);
+        if (status === "approved" && options.args && id)
+            this.approved.set(tool, id);
+        return status;
     }
     /** N2 (idea C2): asks a person to let this session use a gateway tool its policy denies (the
      * denial's `requires.tool`, e.g. `mcp__files__delete`). A yes is a standing grant for the
      * session: retry the call. Answers like `requestApproval`. Never throws. */
     async requestPermission(tool, options = {}) {
-        return this.ask("permissions", { tool }, options);
+        return (await this.ask("permissions", { tool }, options)).status;
     }
     async ask(route, body, options) {
         if (!this.enabled)
-            return "error";
+            return { status: "error" };
         try {
             const r = await post(this.options.url, `/v1/sessions/${this.id}/${route}`, this.token, {
                 ...body,
@@ -415,21 +547,21 @@ export class BlackboxSession {
             const id = r.json.approval_id;
             if (r.status !== 201 || typeof id !== "string") {
                 this.fail("rejected", `asking for an approval: the gateway answered ${r.status}`);
-                return "error";
+                return { status: "error" };
             }
             const deadline = Date.now() + (options.timeoutMs ?? 310_000);
             while (Date.now() < deadline) {
                 const s = await send("GET", this.options.url, `/v1/sessions/${this.id}/approvals/${id}`, this.token);
                 const status = s.json.status;
                 if (status === "approved" || status === "rejected" || status === "timeout")
-                    return status;
+                    return { status, id };
                 await sleep(options.pollMs ?? 1_000);
             }
-            return "timeout";
+            return { status: "timeout", id };
         }
         catch (error) {
             this.fail("network", `asking for an approval: ${message(error)}`);
-            return "error";
+            return { status: "error" };
         }
     }
     /** Audit S8: `await using s = await session(…)` closes the session when the scope ends. */