@zanii/blackbox 0.2.0 → 0.4.0

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?: {
@@ -125,6 +128,8 @@ export interface LlmCallIds {
 }
 /** N4 (idea R6): the same parts always give the same event id (sha256, 128 bits). */
 export declare function stableEventId(...parts: readonly string[]): string;
+/** The image type of a screenshot, by its first bytes: PNG, JPEG or WebP. */
+export declare function imageType(image: Uint8Array): "image/png" | "image/jpeg" | "image/webp" | null;
 /** Opens (or joins) a session. Never throws: on failure it returns a disabled session and logs why. */
 export declare function session(options: SessionOptions): Promise<BlackboxSession>;
 export declare class BlackboxSession {
@@ -142,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;
@@ -152,8 +161,74 @@ export declare class BlackboxSession {
     keepToken?: boolean);
     event(type: string, name?: string, data?: Record<string, unknown>, options?: {
         eventId?: string;
+        /** spec/sdk.md §1.1: an image the event's body is (see `screen`). */
+        attachment?: {
+            contentType: string;
+            bytes: Uint8Array;
+        };
     }): 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;
@@ -193,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). */
@@ -215,8 +299,30 @@ export declare class BlackboxSession {
     nearMiss(description: string): void;
     /** spec/attestation.md: re-runs a read-only command and records whether the output matches. */
     attest(argv: string[], claimed: string, cwd?: string, claimedExit?: number): Attestation | undefined;
+    /**
+     * spec/sdk.md §1.1: a computer-use screenshot (PNG, JPEG or WebP, at most 2 MB), recorded as the
+     * body of a `screen` event, so its hash is in the chain. `action` says what the agent did or is
+     * about to do (≤ 500 characters). Mask what mustn't be kept before calling: the image isn't
+     * redacted. One that's too big or not an image is dropped, and the event says why.
+     */
+    screen(image: Uint8Array, options?: {
+        action?: string;
+        width?: number;
+        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";
@@ -30,6 +42,20 @@ const MAX_DATA = 64 * 1024;
 const PREVIEW = 4096;
 const BATCH = 500;
 const READ_CHUNK = 4 * 1024 * 1024;
+/** spec/sdk.md §1.1: a screenshot's bytes at most; base64 in its spool line, it stays under READ_CHUNK. */
+const MAX_ATTACHMENT = 2 * 1024 * 1024;
+/** The image type of a screenshot, by its first bytes: PNG, JPEG or WebP. */
+export function imageType(image) {
+    const b = Buffer.from(image.buffer, image.byteOffset, image.byteLength);
+    if (b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return "image/png";
+    if (b.subarray(0, 3).equals(Buffer.from([0xff, 0xd8, 0xff])))
+        return "image/jpeg";
+    if (b.subarray(0, 4).toString("latin1") === "RIFF" &&
+        b.subarray(8, 12).toString("latin1") === "WEBP")
+        return "image/webp";
+    return null;
+}
 const LOCK_WAIT_MS = 2_000;
 const LOCK_STALE_MS = 10_000;
 /** Opens (or joins) a session. Never throws: on failure it returns a disabled session and logs why. */
@@ -57,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)
             });
@@ -89,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);
@@ -170,6 +201,14 @@ export class BlackboxSession {
                         ...(eventId === undefined ? {} : { event_id: eventId }),
                         ts: new Date().toISOString(),
                         ...(kept === undefined ? {} : { data: kept }),
+                        ...(options.attachment
+                            ? {
+                                attachment: {
+                                    content_type: options.attachment.contentType,
+                                    data: Buffer.from(options.attachment.bytes).toString("base64"),
+                                },
+                            }
+                            : {}),
                     });
                     appendFileSync(this.spool, `${line}\n`);
                     this.nextSeq++;
@@ -186,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);
@@ -255,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). */
@@ -291,9 +428,47 @@ export class BlackboxSession {
         this.event("attestation", argv[0], { ...result });
         return result;
     }
+    /**
+     * spec/sdk.md §1.1: a computer-use screenshot (PNG, JPEG or WebP, at most 2 MB), recorded as the
+     * body of a `screen` event, so its hash is in the chain. `action` says what the agent did or is
+     * about to do (≤ 500 characters). Mask what mustn't be kept before calling: the image isn't
+     * redacted. One that's too big or not an image is dropped, and the event says why.
+     */
+    screen(image, options = {}) {
+        const data = {
+            ...(options.action ? { action: options.action.slice(0, 500) } : {}),
+            ...(Number.isSafeInteger(options.width) ? { width: options.width } : {}),
+            ...(Number.isSafeInteger(options.height) ? { height: options.height } : {}),
+        };
+        const type = imageType(image);
+        if (!type || image.length > MAX_ATTACHMENT) {
+            this.event("screen", undefined, {
+                ...data,
+                attachment_dropped: type
+                    ? `${image.length} bytes, over 2 MB`
+                    : "not a PNG, JPEG or WebP image",
+            });
+            return;
+        }
+        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 } : {}) });
@@ -350,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,
@@ -369,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. */

package/dist/sla/index.d.ts

@@ -0,0 +1,61 @@
+type Obj = Record<string, unknown>;
+type Commitments = {
+    min_actions?: number;
+    max_actions?: number;
+    max_gap_ms?: number;
+};
+/** Zanii's SLA terms. `commitments` holds at least one of min_actions, max_actions, max_gap_ms. */
+export declare function buildSlaBody(o: {
+    provider: string;
+    client: string;
+    scope: string;
+    window: {
+        start: string;
+        end: string;
+    };
+    commitments: Commitments;
+    price?: {
+        amount: string;
+        currency: string;
+    };
+    createdAt: string;
+    ref?: string;
+}): Obj;
+/** One party signs the terms. Collect the provider's and the client's. */
+export declare const signSla: (body: Obj, did: string, privateKey: Uint8Array) => {
+    did: string;
+    sig: string;
+};
+export declare const assembleSla: (body: Obj, signatures: Array<{
+    did: string;
+    sig: string;
+}>) => {
+    body: Obj;
+    signatures: {
+        did: string;
+        sig: string;
+    }[];
+};
+export declare const slaHash: (sla: Obj) => string;
+/** Zanii's check: sane terms, and BOTH provider and client signed exactly these. */
+export declare function verifySla(sla: unknown): {
+    ok: boolean;
+    reasons: string[];
+};
+/**
+ * Zanii's verdict over the provider's consecutive receipt chain for the window. Breaches:
+ * INVALID_RECEIPT, INCOMPLETE_RECORD (a seam: something recorded was left out), TOO_FEW_ACTIONS,
+ * TOO_MANY_ACTIONS, MAX_GAP_EXCEEDED. `asOf` (default the window's end) caps the trailing gap.
+ */
+export declare function assessCompliance(sla: Obj, receipts: readonly unknown[], asOf?: string): {
+    ok: boolean;
+    breaches: {
+        kind: string;
+        detail: string;
+    }[];
+    metrics: {
+        actions: number;
+        max_gap_ms: number | null;
+    };
+};
+export {};