@zanii/blackbox 0.21.2 → 0.23.0

package/dist/session/index.js

@@ -9,6 +9,7 @@ import { join } from "node:path";
 import { SELF_CHANGE_KINDS } from "../analysis/learning.js";
 import { argsHash } from "../approvals/index.js";
 import { attest, isReadOnly, parseCommand } from "../attest/index.js";
+import { SAFETY_CATEGORIES, } from "../aviation/index.js";
 import { buildPayment, ftaPayload, screeningPayload, } from "../finance/index.js";
 import { certificateOf, taughtBy } from "../fleet/index.js";
 import { decisionPayload } from "../gov/index.js";
@@ -459,6 +460,38 @@ export class BlackboxSession {
     nearMiss(description) {
         this.event("near_miss", undefined, { description });
     }
+    /** spec/aviation.md §6: a voluntary, non-punitive safety report ("I nearly..."): a
+     * SAFETY_REPORT finding that never blocks. `category`: near_miss, hazard, procedure, tooling or
+     * other (the default). */
+    safetyReport(description, options = {}) {
+        const category = SAFETY_CATEGORIES.includes(options.category ?? "")
+            ? options.category
+            : "other";
+        this.event("safety_report", category, { category, description: description.slice(0, 4000) });
+    }
+    /** spec/aviation.md §10: the agent declares distress (it's stuck, unsure, or about to do harm): a
+     * MAYDAY warning, routed to a person at once. Shipped now, not with the next batch. */
+    mayday(reason, options = {}) {
+        this.distress("mayday", reason, options.kind);
+    }
+    /** spec/aviation.md §10: urgency short of distress: a PAN_PAN caution, shipped now. */
+    panPan(reason, options = {}) {
+        this.distress("pan_pan", reason, options.kind);
+    }
+    distress(type, reason, kind) {
+        const k = kind === "stuck" || kind === "harm" ? kind : "unsure";
+        this.event(type, k, { kind: k, reason: reason.slice(0, 500) });
+        void this.flush().catch(() => { });
+    }
+    /** spec/aviation.md §8: the agent reports running a QRH procedure (`started`, `completed`). */
+    procedure(code, status) {
+        this.event("procedure", code.slice(0, 64), { code: code.slice(0, 64), status });
+    }
+    /** spec/aviation.md §9: the run passes its commit point (V1): past it, with the gateway's
+     * BLACKBOX_COMMIT_POINT on, a non-critical finding doesn't stop it. Only the first counts. */
+    commitPoint(note) {
+        this.event("commit_point", undefined, note ? { note: note.slice(0, 500) } : {});
+    }
     /** spec/attestation.md: re-runs a read-only command and records whether the output matches. */
     attest(argv, claimed, cwd, claimedExit) {
         if (!isReadOnly(argv))
@@ -618,6 +651,48 @@ export class BlackboxSession {
         }
         return null;
     }
+    /** One of this session's gateway routes: the answer on 200 or 201, else null. Never throws. */
+    async route(method, path, what, body) {
+        if (!this.enabled)
+            return null;
+        try {
+            const r = await send(method, this.options.url, `/v1/sessions/${this.id}/${path}`, this.token, body);
+            if (r.status === 200 || r.status === 201)
+                return r.json;
+            this.fail("rejected", `${what}: the gateway answered ${r.status}`);
+        }
+        catch (error) {
+            this.fail("network", `${what}: ${message(error)}`);
+        }
+        return null;
+    }
+    /** spec/aviation.md §1-§2: asks for a clearance on a shared resource before changing it. The
+     * answer is `granted` (with its `clearance_id`) or `hold` (wait `retry_after_s`, then ask again).
+     * `null` when the gateway can't be asked. */
+    async clearance(resource, options = {}) {
+        return (await this.route("POST", "clearances", "asking for a clearance", {
+            resource,
+            ...(options.mode ? { mode: options.mode } : {}),
+            ...(options.ttlS !== undefined ? { ttl_s: options.ttlS } : {}),
+        }));
+    }
+    /** spec/aviation.md §1: gives a clearance back. True when the gateway released it. */
+    async releaseClearance(clearanceId) {
+        const path = `clearances/${encodeURIComponent(clearanceId)}`;
+        return (await this.route("DELETE", path, "releasing a clearance")) !== null;
+    }
+    /** spec/aviation.md §8: the quick reference handbook's procedures for this session's
+     * findings. The gateway records that the agent read them. `null` when it can't be asked. */
+    async qrh() {
+        const r = await this.route("GET", "qrh", "reading the handbook");
+        return r ? r.procedures : null;
+    }
+    /** spec/aviation.md §3: the operator's notices in force now, to read before a run. The gateway
+     * records that the agent read them. `null` when it can't be asked. */
+    async notams() {
+        const r = await this.route("GET", "notams", "reading the notams");
+        return r ? r.notams : null;
+    }
     /**
      * spec/findings.md §1c: the agent changed itself (its prompt, a tool, its policy, its memory, its
      * model). Only hashes of `before` and `after` are sent, never the content. A change that gives
@@ -640,6 +715,14 @@ export class BlackboxSession {
                 : {}),
         });
     }
+    /** spec/evals.md §4: the version of a registered prompt this run uses, for when the gateway
+     * can't tell it from the system prompt's hash (the prompt is assembled per run). A bad name or
+     * version is dropped. */
+    promptVersion(name, version) {
+        if (!/^[A-Za-z0-9._-]{1,128}$/.test(name) || !Number.isSafeInteger(version) || version < 1)
+            return;
+        this.event("prompt_version", name, { name, version });
+    }
     /** spec/findings.md §13.1: what in an answer (the latest, or the one at `seq`) would hold it,
      * for an app that streams the answer by itself: `{seq, risks, hold}`. `hold` says whether the
      * server would hold it. `null` when there's no answer yet or the gateway can't be asked. */

package/dist/undo/index.js

@@ -1,6 +1,7 @@
 // Undo (spec/undo.md): the completed risky actions of a session, newest first, each with the call
 // that reverses it. Pure; mirrors sdks/python/src/zanii_blackbox/undo.py; pinned by
 // spec/vectors/undo.json.
+import { envelopesOf } from "../reconcile/record.js";
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const glob = (pattern) => new RegExp(`^${pattern.split("*").map(escapeRe).join(".*")}$`);
 const REDACTED = /\[REDACTED:[a-z_]+\]/;
@@ -40,7 +41,7 @@ function resolve(value, args, result) {
 }
 /** Completed, successful tool calls (not policy-denied, not undos), and the seqs already undone. */
 function callsOf(lines, bodies) {
-    const events = lines.map((l) => JSON.parse(l));
+    const events = envelopesOf(lines);
     const calls = [];
     const undone = new Set();
     const results = new Map();
@@ -144,8 +145,7 @@ export function undoPlan(lines, bodies, compensations) {
 /** spec/undo.md §3: an undo that the gateway ran and that failed. */
 export function undoFindings(lines, bodies) {
     const out = [];
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         if (e.kind !== "tool.result" || typeof e.meta.undo_of !== "number")
             continue;
         const res = bodyJson(bodies, e.body_hash);

package/dist/verify/anchor.d.ts

@@ -35,11 +35,15 @@ export interface BundleReport {
         ok: boolean;
         message?: string;
     };
-    /** One entry per anchor when proofs were checked; null when they weren't. */
+    /**
+     * One entry per anchor when proofs were checked; null when they weren't. `legacy`: the receipt
+     * predates JCS payloads (no `payload_encoding`, Zanii SDKs before 0.25.1).
+     */
     proofs: Array<{
         receipt_hash: string;
         ok: boolean;
         problems: string[];
+        legacy: boolean;
     }> | null;
 }
 /**

package/dist/verify/anchor.js

@@ -1,5 +1,5 @@
 // Anchors and audit bundles (spec/anchoring.md). Mirrors sdks/python/src/zanii_blackbox/verify/anchor.py.
-import { canonicalBytes } from "@zanii/core";
+import { canonicalBytes, verifyPayloadLegacy } from "@zanii/core";
 import { fetchAndVerifyProof, verifyPayload } from "@zanii/sdk";
 import { verifyChain } from "./chain.js";
 export const ANCHOR_TARGET = "blackbox.anchor";
@@ -43,6 +43,7 @@ export async function verifyBundle(bundle, options = {}) {
         proofs = [];
         for (const a of bundle.anchors) {
             const problems = [];
+            let legacy = false;
             if (!bundle.ledger_url)
                 problems.push("no ledger_url in the bundle");
             else {
@@ -60,12 +61,20 @@ export async function verifyBundle(bundle, options = {}) {
                         problems.push("receipt was not signed by the pinned gateway identity");
                     if (r.target !== ANCHOR_TARGET)
                         problems.push(`receipt target is ${r.target}, not ${ANCHOR_TARGET}`);
-                    if (!verifyPayload(anchorPayloadBytes(bundle.session.session_id, a.count, a.head), a.nonce, r.payload_hash)) {
-                        problems.push("receipt payload does not commit to this (count, head)");
+                    const sid = bundle.session.session_id;
+                    let committed;
+                    if (r.payload_encoding === "jcs")
+                        committed = verifyPayload(anchorPayloadBytes(sid, a.count, a.head), a.nonce, r.payload_hash);
+                    else {
+                        // recorded before JCS payloads: try each older SDK's encoding
+                        legacy = true;
+                        committed = verifyPayloadLegacy(anchorPayload(sid, a.count, a.head), a.nonce, r.payload_hash).ok;
                     }
+                    if (!committed)
+                        problems.push("receipt payload does not commit to this (count, head)");
                 }
             }
-            proofs.push({ receipt_hash: a.receipt_hash, ok: problems.length === 0, problems });
+            proofs.push({ receipt_hash: a.receipt_hash, ok: problems.length === 0, problems, legacy });
         }
     }
     return {

package/dist/verify/chain.d.ts

@@ -23,5 +23,9 @@ export interface VerifyOptions {
         count: number;
         head: string;
     }>;
+    /** A continuation (spec/tower.md §3): the first line's seq, and the event_hash it follows.
+     *  Anchors need the whole chain. */
+    startSeq?: number;
+    startPrev?: string;
 }
 export declare function verifyChain(lines: readonly string[], options?: VerifyOptions): VerifyResult;

package/dist/verify/chain.js

@@ -7,7 +7,8 @@ const SESSION = /^ses_[A-Za-z0-9]{16,64}$/;
 const TS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$/;
 const KINDS = new Set(EVENT_KINDS);
 export function verifyChain(lines, options = {}) {
-    let prev = GENESIS;
+    let prev = options.startPrev ?? GENESIS;
+    const start = options.startSeq ?? 0;
     const hashes = [];
     let session = options.sessionId;
     const fail = (code, index, message) => ({
@@ -34,8 +35,8 @@ export function verifyChain(lines, options = {}) {
         session ??= env.session_id;
         if (env.session_id !== session)
             return fail("WRONG_SESSION", i, `session_id ${env.session_id} ≠ ${session}`);
-        if (env.seq !== i)
-            return fail("SEQ_GAP", i, `expected seq ${i}, found ${env.seq}`);
+        if (env.seq !== start + i)
+            return fail("SEQ_GAP", i, `expected seq ${start + i}, found ${env.seq}`);
         if (env.prev !== prev)
             return fail("BROKEN_LINK", i, "prev does not match the previous event_hash");
         const body = options.body?.(env.body_hash);

package/dist/verify/envelope.d.ts

@@ -1,5 +1,5 @@
 export declare const GENESIS = "genesis";
-export declare const EVENT_KINDS: readonly ["session.open", "session.close", "session.lost_contact", "llm.request", "llm.chunk", "llm.response", "llm.incomplete", "tool.call", "tool.result", "tool.notification", "workspace.receipt", "sdk.event", "control", "outcome", "finding", "capture.gap"];
+export declare const EVENT_KINDS: readonly ["session.open", "session.close", "session.lost_contact", "llm.request", "llm.chunk", "llm.response", "llm.incomplete", "llm.realtime.client", "llm.realtime.server", "tool.call", "tool.result", "tool.notification", "tool.sampling", "tool.elicitation", "tool.roots", "workspace.receipt", "sdk.event", "control", "outcome", "finding", "capture.gap"];
 export type EventKind = (typeof EVENT_KINDS)[number];
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;

package/dist/verify/envelope.js

@@ -10,9 +10,14 @@ export const EVENT_KINDS = [
     "llm.chunk",
     "llm.response",
     "llm.incomplete",
+    "llm.realtime.client",
+    "llm.realtime.server",
     "tool.call",
     "tool.result",
     "tool.notification",
+    "tool.sampling",
+    "tool.elicitation",
+    "tool.roots",
     "workspace.receipt",
     "sdk.event",
     "control",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.21.2";
+export declare const VERSION = "0.23.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The SDK version, on its own so the CLI can print it without loading the whole SDK.
-export const VERSION = "0.21.2";
+export const VERSION = "0.23.0";

package/dist/walls/index.js

@@ -1,6 +1,7 @@
 // Zanii's UAE vertical walls (spec/governance.md §5): the table from spec/walls/v1.json, embedded
 // (a test checks it matches), and the output check. Mirrors sdks/python/src/zanii_blackbox/walls.py.
 import { jcsHash } from "@zanii/core";
+import { envelopesOf } from "../reconcile/record.js";
 export const WALLS = {
     "sca-trading": {
         id: "sca-trading",
@@ -90,8 +91,7 @@ export function wallFindings(lines, bodies, wallIds) {
         return out;
     // a response's bytes are its chunks' bodies, joined in order (spec/api.md: llm.chunk)
     const chunks = new Map();
-    for (const l of lines) {
-        const e = JSON.parse(l);
+    for (const e of envelopesOf(lines)) {
         if (e.kind === "llm.chunk") {
             const body = bodies(e.body_hash);
             const list = chunks.get(e.meta.request_seq) ?? [];

package/dist/warehouse/index.d.ts

@@ -0,0 +1,62 @@
+export declare const WAREHOUSE_TABLES: readonly ["sessions", "events", "findings", "costs"];
+export type WarehouseTable = (typeof WAREHOUSE_TABLES)[number];
+export type WarehouseRow = Record<string, string | number | boolean | null>;
+export interface WarehouseSession {
+    id: string;
+    tenant_id: string;
+    label: string | null;
+    created_at: string;
+    closed_at: string;
+}
+/** The part of a cost report (spec/cost.md) the rows use. */
+export interface WarehouseCost {
+    total_micro_usd: number;
+    calls_priced: number;
+    calls_unpriced: number;
+    calls: Array<{
+        seq: number;
+        model: string | null;
+        tokens: {
+            input: number;
+            output: number;
+            cache_read: number;
+            cache_write: number;
+        };
+        micro_usd: number | null;
+    }>;
+}
+/** spec/warehouse.md §2: the session's rows per table. `bodies` (hash → text) only when the
+ *  tenant opted in (§4); then every event row has `body`. */
+export declare function warehouseRows(input: {
+    session: WarehouseSession;
+    lines: readonly string[];
+    cost: WarehouseCost;
+    bodies?: Record<string, string | null> | null;
+}): Record<WarehouseTable, WarehouseRow[]>;
+/** spec/warehouse.md §3: batches of at most `maxRows` rows and `maxBytes` bytes of JSON (a row
+ *  bigger than that goes alone). */
+export declare function warehouseBatches(rows: readonly WarehouseRow[], maxRows?: number, maxBytes?: number): WarehouseRow[][];
+export type WarehouseDestination = {
+    type: "clickhouse";
+    database: string;
+} | {
+    type: "bigquery";
+    project: string;
+    dataset: string;
+} | {
+    type: "snowflake";
+    database: string;
+    schema: string;
+    warehouse: string;
+    role?: string;
+};
+export interface WarehouseRequest {
+    /** The path and query, after the destination's base URL. */
+    path: string;
+    headers: Record<string, string>;
+    body: string;
+}
+/** spec/warehouse.md §3: a UUID from the batch key, so a retry is the same Snowflake request. */
+export declare function warehouseRequestId(key: string): string;
+/** spec/warehouse.md §3: one batch as the destination takes it, without credentials. */
+export declare function warehouseRequest(dest: WarehouseDestination, table: WarehouseTable, rows: readonly WarehouseRow[], key: string): WarehouseRequest;

package/dist/warehouse/index.js

@@ -0,0 +1,142 @@
+// Warehouse export (spec/warehouse.md): a closed session's rows for the four tables, cut into
+// batches, and each batch as a ClickHouse, BigQuery or Snowflake request. Pure: the server adds the
+// base URL and the credentials and sends it. Mirrors sdks/python/src/zanii_blackbox/warehouse.py;
+// pinned by spec/vectors/warehouse.json.
+import { createHash } from "node:crypto";
+import { canonical } from "../reconcile/shared.js";
+export const WAREHOUSE_TABLES = ["sessions", "events", "findings", "costs"];
+/** spec/warehouse.md §2: the session's rows per table. `bodies` (hash → text) only when the
+ *  tenant opted in (§4); then every event row has `body`. */
+export function warehouseRows(input) {
+    const { session: s, cost } = input;
+    const bodies = input.bodies ?? null;
+    const base = { tenant_id: s.tenant_id, session_id: s.id };
+    const events = [];
+    const findings = [];
+    for (const line of input.lines) {
+        const e = JSON.parse(line);
+        const meta = e.meta ?? {};
+        events.push({
+            insert_id: `${s.id}:${e.seq}`,
+            ...base,
+            seq: e.seq,
+            ts: e.ts,
+            kind: e.kind,
+            body_hash: e.body_hash ?? null,
+            meta: canonical(meta),
+            ...(bodies ? { body: (e.body_hash && bodies[e.body_hash]) ?? null } : {}),
+        });
+        if (e.kind === "finding")
+            findings.push({
+                insert_id: `${s.id}:${e.seq}`,
+                ...base,
+                seq: e.seq,
+                ts: e.ts,
+                code: typeof meta.code === "string" ? meta.code : "",
+                source: typeof meta.source === "string" ? meta.source : "",
+                severity: typeof meta.severity === "string" ? meta.severity : "",
+                ref: canonical(meta.ref ?? {}),
+                detail: typeof meta.detail === "string" ? meta.detail : null,
+                accepted: meta.accepted !== undefined && meta.accepted !== null,
+            });
+    }
+    const costs = cost.calls.map((c) => ({
+        insert_id: `${s.id}:${c.seq}`,
+        ...base,
+        seq: c.seq,
+        model: c.model,
+        input_tokens: c.tokens.input,
+        output_tokens: c.tokens.output,
+        cache_read_tokens: c.tokens.cache_read,
+        cache_write_tokens: c.tokens.cache_write,
+        micro_usd: c.micro_usd,
+    }));
+    return {
+        sessions: [
+            {
+                insert_id: s.id,
+                ...base,
+                label: s.label,
+                created_at: s.created_at,
+                closed_at: s.closed_at,
+                events: input.lines.length,
+                findings: findings.length,
+                cost_micro_usd: cost.total_micro_usd,
+                calls_priced: cost.calls_priced,
+                calls_unpriced: cost.calls_unpriced,
+            },
+        ],
+        events,
+        findings,
+        costs,
+    };
+}
+/** spec/warehouse.md §3: batches of at most `maxRows` rows and `maxBytes` bytes of JSON (a row
+ *  bigger than that goes alone). */
+export function warehouseBatches(rows, maxRows = 500, maxBytes = 5_000_000) {
+    const out = [];
+    let batch = [];
+    let bytes = 0;
+    for (const row of rows) {
+        const size = Buffer.byteLength(JSON.stringify(row));
+        if (batch.length > 0 && (batch.length >= maxRows || bytes + size > maxBytes)) {
+            out.push(batch);
+            batch = [];
+            bytes = 0;
+        }
+        batch.push(row);
+        bytes += size;
+    }
+    if (batch.length > 0)
+        out.push(batch);
+    return out;
+}
+/** spec/warehouse.md §3: a UUID from the batch key, so a retry is the same Snowflake request. */
+export function warehouseRequestId(key) {
+    const h = createHash("sha256").update(key).digest("hex");
+    const variant = ((Number.parseInt(h[16], 16) & 3) | 8).toString(16);
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-5${h.slice(13, 16)}-${variant}${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+/** spec/warehouse.md §3: one batch as the destination takes it, without credentials. */
+export function warehouseRequest(dest, table, rows, key) {
+    const name = `blackbox_${table}`;
+    if (dest.type === "clickhouse") {
+        const query = encodeURIComponent(`INSERT INTO ${dest.database}.${name} FORMAT JSONEachRow`);
+        return {
+            path: `/?query=${query}&insert_deduplication_token=${encodeURIComponent(key)}`,
+            headers: { "content-type": "application/x-ndjson" },
+            body: rows.map((r) => `${JSON.stringify(r)}\n`).join(""),
+        };
+    }
+    if (dest.type === "bigquery")
+        return {
+            path: `/bigquery/v2/projects/${encodeURIComponent(dest.project)}/datasets/${encodeURIComponent(dest.dataset)}/tables/${name}/insertAll`,
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                kind: "bigquery#tableDataInsertAllRequest",
+                skipInvalidRows: false,
+                ignoreUnknownValues: false,
+                rows: rows.map((r) => ({ insertId: r.insert_id, json: r })),
+            }),
+        };
+    const values = rows.map(() => "(?)").join(", ");
+    const bindings = {};
+    rows.forEach((r, i) => {
+        bindings[String(i + 1)] = { type: "TEXT", value: JSON.stringify(r) };
+    });
+    return {
+        path: `/api/v2/statements?requestId=${warehouseRequestId(key)}&retry=true`,
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({
+            statement: `MERGE INTO ${name} t USING (SELECT PARSE_JSON(column1) AS r FROM VALUES ${values}) s` +
+                " ON t.insert_id = s.r:insert_id::STRING WHEN NOT MATCHED THEN" +
+                " INSERT (insert_id, record) VALUES (s.r:insert_id::STRING, s.r)",
+            timeout: 60,
+            database: dest.database,
+            schema: dest.schema,
+            warehouse: dest.warehouse,
+            ...(dest.role ? { role: dest.role } : {}),
+            bindings,
+        }),
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.21.2",
+  "version": "0.23.0",
   "description": "The flight recorder for AI agents: sessions, a zero-loss spool, framework hooks, approvals, and offline verification of the gateway's hash-chained record.",
   "keywords": [
     "ai-agents",
@@ -40,14 +40,17 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@zanii/core": "^0.5.1",
-    "@zanii/sdk": "^0.5.1"
+    "@zanii/core": "^0.5.6",
+    "@zanii/sdk": "^0.5.4"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.283",
     "@langchain/core": "1.2.13",
     "@langchain/langgraph": "1.4.18",
+    "@mastra/core": "1.78.0",
+    "@mastra/observability": "1.20.1",
     "@openai/agents": "0.18.0",
+    "ai": "6.0.283",
     "langchain": "1.5.14",
     "zod": "^4.6.5"
   },