@zanii/blackbox 0.21.2 → 0.23.0

package/README.md

@@ -156,6 +156,7 @@ The same checks run offline as pure functions: `toolHallucinations`, `groundingF
 | OpenAI Agents SDK | `attachBlackbox(runner, s)` |
 | Claude Agent SDK | `blackboxAgentHooks(s)` |
 | Vercel AI SDK | `blackboxMiddleware(s)` |
+| Mastra | `exporters: [blackboxMastraExporter(s)]` in its observability config, and `blackboxMiddleware(s, { toolCalls: false })` on the agent's model for the model-call ids |
 | Provider clients | `wrapAnthropic`, `wrapOpenAI`, `wrapGemini`, `wrapBedrock` link each call to the gateway's record |
 
 ## Command line

package/dist/actions/index.d.ts

@@ -0,0 +1,29 @@
+import { type Bodies, type Call } from "../reconcile/record.ts";
+export interface Reasoning {
+    /** `text` (the model's own words), `summary` (the provider's), `encrypted` (there, unreadable) or `none`. */
+    kind: "text" | "summary" | "encrypted" | "none";
+    text: string | null;
+}
+export interface Action {
+    seq: number;
+    request_seq: number;
+    model: string | null;
+    tool: string;
+    id: string | null;
+    args: unknown;
+    reasoning: Reasoning;
+    /** What the model wrote before the action, in the same answer. */
+    said: string | null;
+}
+/** The tool calls each model answer asked for, in order. Each takes the reasoning and text that came
+ *  before it in the same answer, since the action before it; one with none of its own (a second call
+ *  in a row) takes the answer's latest. */
+export declare function actionsFromCalls(calls: readonly Call[]): Action[];
+/** The actions in a verified record, each with the reasoning before it (spec/replay.md §6). */
+export declare function actionsOf(lines: readonly string[], bodies: Bodies): Action[];
+/** The actions for a reader: the first `limit`, each reasoning and `said` cut to `textMax` characters. */
+export declare function actionsPage(actions: readonly Action[], limit?: number, textMax?: number): {
+    total: number;
+    capped: boolean;
+    actions: Action[];
+};

package/dist/actions/index.js

@@ -0,0 +1,114 @@
+// Each action an agent took, with the reasoning the model gave before it (spec/replay.md §6): the
+// thinking (Anthropic `thinking`, Gemini thoughts, a Chat Completions `reasoning_content`), the
+// provider's reasoning summary (OpenAI Responses), or a note that it was there but encrypted. Pure;
+// mirrors sdks/python/src/zanii_blackbox/actions.py; pinned by spec/vectors/actions.json.
+import { callsOf } from "../reconcile/record.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Text parts win over a summary, either over encrypted. */
+function reasoningOf(parts) {
+    for (const kind of ["text", "summary"]) {
+        const texts = parts.filter(([k, t]) => k === kind && t).map(([, t]) => t);
+        if (texts.length)
+            return { kind, text: texts.join("\n\n") };
+    }
+    if (parts.some(([k]) => k === "encrypted"))
+        return { kind: "encrypted", text: null };
+    return { kind: "none", text: null };
+}
+const action = (c, tool, id, args, why, said) => ({
+    seq: c.endSeq,
+    request_seq: c.requestSeq,
+    model: c.model,
+    tool,
+    id: typeof id === "string" ? id : null,
+    args: args ?? {},
+    reasoning: reasoningOf(why),
+    said: said.filter(Boolean).join("\n\n") || null,
+});
+/** The tool calls each model answer asked for, in order. Each takes the reasoning and text that came
+ *  before it in the same answer, since the action before it; one with none of its own (a second call
+ *  in a row) takes the answer's latest. */
+export function actionsFromCalls(calls) {
+    const out = [];
+    for (const c of [...calls].sort((a, b) => a.endSeq - b.endSeq)) {
+        let why = c.reasoning ? [["text", c.reasoning]] : [];
+        let said = [];
+        let last = [[], []];
+        for (const [, b] of [...c.blocks.entries()].sort(([x], [y]) => x - y)) {
+            if (b.type === "thinking")
+                why.push(typeof b.thinking === "string" && b.thinking ? ["text", b.thinking] : ["encrypted", ""]);
+            else if (b.type === "redacted_thinking")
+                why.push(["encrypted", ""]);
+            else if (b.type === "text" && typeof b.text === "string")
+                said.push(b.text);
+            else if (b.type === "tool_use" && typeof b.name === "string") {
+                if (why.length || said.length)
+                    last = [why, said];
+                out.push(action(c, b.name, b.id, b.input, ...last));
+                why = [];
+                said = [];
+            }
+        }
+        for (const item of c.items) {
+            const t = item.type;
+            if (t === "reasoning") {
+                const texts = (Array.isArray(item.summary) ? item.summary : [])
+                    .filter(isObj)
+                    .map((s) => String(s.text ?? ""));
+                const own = (Array.isArray(item.content) ? item.content : [])
+                    .filter(isObj)
+                    .map((s) => String(s.text ?? ""));
+                if (own.some(Boolean))
+                    why.push(...own.map((x) => ["text", x]));
+                else if (texts.some(Boolean))
+                    why.push(...texts.map((x) => ["summary", x]));
+                else
+                    why.push(["encrypted", ""]);
+            }
+            else if (t === "message") {
+                for (const s of Array.isArray(item.content) ? item.content : [])
+                    if (isObj(s) && typeof s.text === "string")
+                        said.push(s.text);
+            }
+            else if ((t === "function_call" || t === "custom_tool_call") &&
+                typeof item.name === "string") {
+                let args = t === "function_call" ? item.arguments : item.input;
+                if (typeof args === "string" && t === "function_call") {
+                    try {
+                        args = JSON.parse(args);
+                    }
+                    catch { }
+                }
+                if (why.length || said.length)
+                    last = [why, said];
+                out.push(action(c, item.name, item.call_id, args, ...last));
+                why = [];
+                said = [];
+            }
+        }
+    }
+    return out;
+}
+/** The actions in a verified record, each with the reasoning before it (spec/replay.md §6). */
+export function actionsOf(lines, bodies) {
+    return actionsFromCalls(callsOf(lines, bodies));
+}
+/** Cut to `most` code points (as Python counts them), then `…`. */
+function cut(text, most) {
+    if (text === null)
+        return null;
+    const points = Array.from(text);
+    return points.length <= most ? text : `${points.slice(0, most).join("")}…`;
+}
+/** The actions for a reader: the first `limit`, each reasoning and `said` cut to `textMax` characters. */
+export function actionsPage(actions, limit = 1000, textMax = 8000) {
+    return {
+        total: actions.length,
+        capped: actions.length > limit,
+        actions: actions.slice(0, limit).map((a) => ({
+            ...a,
+            reasoning: { ...a.reasoning, text: cut(a.reasoning.text, textMax) },
+            said: cut(a.said, textMax),
+        })),
+    };
+}

package/dist/admission/index.d.ts

@@ -0,0 +1,30 @@
+export declare const REGISTER_TYPE = "blackbox.service-register";
+export declare const ACCREDITATION_TYPE = "blackbox.accreditation";
+export declare const SERVICE_ID: RegExp;
+type Doc = Record<string, unknown>;
+export interface ServiceRow {
+    id: string;
+    name: string;
+    name_ar?: string;
+    tier: number;
+}
+/** `sha256:` + hex of the RFC 8785 JSON of the whole signed document. */
+export declare const docHash: (doc: Doc) => string;
+/** §1: null when the register is well formed and signed by one of `signers`, else why not. */
+export declare function checkRegister(doc: unknown, signers: readonly string[]): string | null;
+/** §1: a service's tier and its row; an unknown service (or none) gets `default_tier`. */
+export declare function serviceTier(register: Doc, serviceId: string | null | undefined): {
+    tier: number;
+    service: ServiceRow | null;
+};
+export type AccreditationRefusal = "malformed" | "unsigned" | "wrong_issuer" | "revoked" | "not_yet" | "expired" | "wrong_vendor" | "agent_not_listed" | "tier_too_high";
+/** §2: null when `cert` lets this vendor's agent open a session for a service of `tier` now, else
+ *  the reason. */
+export declare function checkAccreditation(cert: unknown, issuers: readonly string[], opts: {
+    now: string;
+    vendor?: string | null;
+    agentId?: string | null;
+    tier?: number | null;
+    revoked?: readonly string[];
+}): AccreditationRefusal | null;
+export {};

package/dist/admission/index.js

@@ -0,0 +1,106 @@
+// Who and what may open a session (spec/admission.md): the signed service risk register (each
+// service's tier: 1 allowed, 2 a person approves each action, 3 off limits) and a vendor's signed
+// accreditation. Both are signed like certificates (spec/fleet.md §5) and checked offline. Pure;
+// mirrors sdks/python/src/zanii_blackbox/admission.py; pinned by spec/vectors/admission.json.
+import { createHash } from "node:crypto";
+import { verifyCertificate } from "../fleet/index.js";
+import { canonical } from "../reconcile/shared.js";
+export const REGISTER_TYPE = "blackbox.service-register";
+export const ACCREDITATION_TYPE = "blackbox.accreditation";
+export const SERVICE_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const VENDOR_ID = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const AGENT_ID = /^(?:[A-Za-z0-9._:@/-]{1,128}|\*)$/;
+const MAX_SERVICES = 10_000;
+const UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$/;
+/** `sha256:` + hex of the RFC 8785 JSON of the whole signed document. */
+export const docHash = (doc) => `sha256:${createHash("sha256").update(canonical(doc)).digest("hex")}`;
+const isTier = (x) => Number.isInteger(x) && x >= 1 && x <= 3;
+const when = (x) => {
+    if (typeof x !== "string" || !UTC.test(x))
+        return null;
+    const t = Date.parse(x);
+    return Number.isNaN(t) ? null : t;
+};
+const isObject = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+/** §1: null when the register is well formed and signed by one of `signers`, else why not. */
+export function checkRegister(doc, signers) {
+    if (!isObject(doc))
+        return "the register must be a JSON object";
+    if (doc.v !== 1 || doc.type !== REGISTER_TYPE)
+        return `not a ${REGISTER_TYPE} v1`;
+    if (typeof doc.name !== "string" || !doc.name)
+        return "name is required";
+    if (!isTier(doc.default_tier))
+        return "default_tier must be 1, 2 or 3";
+    const services = doc.services;
+    if (!Array.isArray(services) || services.length > MAX_SERVICES)
+        return `services must be a list of at most ${MAX_SERVICES}`;
+    const seen = new Set();
+    for (const [i, s] of services.entries()) {
+        if (!isObject(s))
+            return `services[${i}] must be an object`;
+        if (typeof s.id !== "string" || !SERVICE_ID.test(s.id))
+            return `services[${i}].id must be 1-64 of a-z 0-9 . _ - (like visa-renewal)`;
+        if (seen.has(s.id))
+            return `services[${i}].id ${s.id} is listed twice`;
+        seen.add(s.id);
+        if (typeof s.name !== "string" || !s.name)
+            return `services[${i}].name is required`;
+        if (!isTier(s.tier))
+            return `services[${i}].tier must be 1, 2 or 3`;
+    }
+    const v = verifyCertificate(doc);
+    if (!v.ok)
+        return `the register's signature doesn't verify (${v.reason})`;
+    if (!signers.includes(v.by))
+        return `the register is signed by ${v.by}, who isn't a trusted signer`;
+    return null;
+}
+/** §1: a service's tier and its row; an unknown service (or none) gets `default_tier`. */
+export function serviceTier(register, serviceId) {
+    const found = register.services.find((s) => s.id === serviceId);
+    return found
+        ? { tier: found.tier, service: found }
+        : { tier: register.default_tier, service: null };
+}
+/** §2: null when `cert` lets this vendor's agent open a session for a service of `tier` now, else
+ *  the reason. */
+export function checkAccreditation(cert, issuers, opts) {
+    if (!isObject(cert))
+        return "malformed";
+    const agents = cert.agents;
+    const issued = when(cert.issued_at);
+    const expires = when(cert.expires_at);
+    const at = when(opts.now);
+    if (cert.v !== 1 ||
+        cert.type !== ACCREDITATION_TYPE ||
+        typeof cert.vendor !== "string" ||
+        !VENDOR_ID.test(cert.vendor) ||
+        !Array.isArray(agents) ||
+        !agents.length ||
+        !agents.every((a) => typeof a === "string" && AGENT_ID.test(a)) ||
+        (cert.max_tier !== 1 && cert.max_tier !== 2) ||
+        issued === null ||
+        expires === null ||
+        at === null)
+        return "malformed";
+    const v = verifyCertificate(cert);
+    if (!v.ok)
+        return "unsigned";
+    if (!issuers.includes(v.by))
+        return "wrong_issuer";
+    if ((opts.revoked ?? []).includes(docHash(cert)))
+        return "revoked";
+    if (at < issued)
+        return "not_yet";
+    if (at >= expires)
+        return "expired";
+    if (opts.vendor != null && cert.vendor !== opts.vendor)
+        return "wrong_vendor";
+    const listed = agents;
+    if (!listed.includes("*") && (opts.agentId == null || !listed.includes(opts.agentId)))
+        return "agent_not_listed";
+    if (opts.tier != null && opts.tier > cert.max_tier)
+        return "tier_too_high";
+    return null;
+}

package/dist/analysis/accepted.d.ts

@@ -0,0 +1,26 @@
+export interface AcceptedEntry {
+    code: string;
+    ref?: {
+        [key: string]: string | number | boolean;
+    };
+    label?: string;
+    agent?: string;
+    reason: string;
+    by: string;
+    expires_at?: string;
+}
+/** Why a list of accepted findings is invalid, or undefined. */
+export declare function checkAcceptedFindings(list: unknown): string | undefined;
+/** The list's identity, recorded with every finding it accepts: sha256 over {v: 1, accepted}. */
+export declare function acceptedHash(list: readonly AcceptedEntry[]): string;
+/** The index of the first entry that accepts this finding, or -1. `now` is an ISO timestamp. */
+export declare function acceptedMatch(list: readonly AcceptedEntry[], finding: {
+    code: string;
+    ref: {
+        [key: string]: unknown;
+    };
+}, context: {
+    label: string | null;
+    agent: string | null;
+    now: string;
+}): number;

package/dist/analysis/accepted.js

@@ -0,0 +1,61 @@
+// Accepted findings (spec/control.md §4b): a tenant's list of known, accepted findings. A finding
+// that matches is still recorded, marked accepted, and raises no alert and no block. Mirrors
+// analysis/accepted.py; pinned by spec/vectors/accepted-findings.json.
+import { createHash } from "node:crypto";
+import { canonical, isObj } from "../reconcile/shared.js";
+const CODE = /^[A-Z0-9_]{1,64}\*?$/;
+const UTC = /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/;
+const FIELDS = ["code", "ref", "label", "agent", "reason", "by", "expires_at"];
+const text = (v, max) => typeof v === "string" && v.length > 0 && Array.from(v).length <= max;
+/** Why a list of accepted findings is invalid, or undefined. */
+export function checkAcceptedFindings(list) {
+    if (!Array.isArray(list) || list.length > 200)
+        return "accepted must be a list of at most 200 entries";
+    for (const [i, e] of list.entries()) {
+        const at = `accepted[${i}]`;
+        if (!isObj(e))
+            return `${at} must be an object`;
+        const extra = Object.keys(e).filter((k) => !FIELDS.includes(k));
+        if (extra.length)
+            return `${at} has unknown fields: ${extra.sort().join(", ")}`;
+        if (typeof e.code !== "string" || !CODE.test(e.code))
+            return `${at}.code must be a finding code, optionally ending in *`;
+        if (e.ref !== undefined &&
+            !(isObj(e.ref) &&
+                Object.keys(e.ref).length <= 20 &&
+                Object.values(e.ref).every((v) => typeof v === "boolean" ||
+                    (typeof v === "number" && Number.isSafeInteger(v)) ||
+                    (typeof v === "string" && Array.from(v).length <= 256))))
+            return `${at}.ref must be an object of at most 20 strings, integers or booleans`;
+        for (const k of ["label", "agent"])
+            if (e[k] !== undefined && !text(e[k], 128))
+                return `${at}.${k} must be 1-128 characters`;
+        if (!text(e.reason, 500))
+            return `${at}.reason must be 1-500 characters`;
+        if (!text(e.by, 128))
+            return `${at}.by must be 1-128 characters`;
+        if (e.expires_at !== undefined &&
+            !(typeof e.expires_at === "string" &&
+                UTC.test(e.expires_at) &&
+                !Number.isNaN(Date.parse(e.expires_at))))
+            return `${at}.expires_at must be a UTC timestamp like 2026-12-31T00:00:00Z`;
+    }
+    return undefined;
+}
+/** The list's identity, recorded with every finding it accepts: sha256 over {v: 1, accepted}. */
+export function acceptedHash(list) {
+    return `sha256:${createHash("sha256")
+        .update(canonical({ v: 1, accepted: list }))
+        .digest("hex")}`;
+}
+/** The index of the first entry that accepts this finding, or -1. `now` is an ISO timestamp. */
+export function acceptedMatch(list, finding, context) {
+    const now = Date.parse(context.now);
+    return list.findIndex((e) => (e.code.endsWith("*")
+        ? finding.code.startsWith(e.code.slice(0, -1))
+        : finding.code === e.code) &&
+        Object.entries(e.ref ?? {}).every(([k, v]) => Object.hasOwn(finding.ref, k) && finding.ref[k] === v) &&
+        (e.label === undefined || e.label === context.label) &&
+        (e.agent === undefined || e.agent === context.agent) &&
+        (e.expires_at === undefined || now < Date.parse(e.expires_at)));
+}

package/dist/analysis/detectors.js

@@ -2,7 +2,8 @@
 // any agent, instrumented or not. Mirrors sdks/python/src/zanii_blackbox/analysis/detectors.py.
 import { createHash } from "node:crypto";
 import { priceCall, priceFor, promptTokens, tokensOf } from "../cost/index.js";
-import { callsOf } from "../reconcile/record.js";
+import { realtimeUsage } from "../realtime/index.js";
+import { callsOf, envelopesOf } from "../reconcile/record.js";
 import { canonical, isObj } from "../reconcile/shared.js";
 const VOLATILE = new Set([
     "timestamp",
@@ -104,8 +105,7 @@ export function toolResultsOf(calls, lines) {
                 }
         }
     }
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         if (e.kind === "tool.result" && typeof e.meta.is_error === "boolean")
             out.push({ seq: e.seq, error: e.meta.is_error });
     }
@@ -303,9 +303,14 @@ export function detectors(lines, options) {
     if (options.prices && budget && budget > 0) {
         let micro = 0;
         const crossed = new Set();
-        for (const c of priced) {
+        // a realtime session's usage reports count too (spec/providers.md §7)
+        const spend = [
+            ...priced.map((c) => ({ seq: c.endSeq, call: { ...c, usage: c.usage } })),
+            ...realtimeUsage(lines).map((u) => ({ seq: u.seq, call: u })),
+        ].sort((a, b) => a.seq - b.seq);
+        for (const { call } of spend) {
             // the cost report's own pricing (spec/cost.md): tiers, provider scope, reported costs
-            const priced = priceCall({ ...c, usage: c.usage }, options.prices.table);
+            const priced = priceCall(call, options.prices.table);
             if (priced.micro_usd === null)
                 continue;
             micro += priced.micro_usd;
@@ -355,8 +360,7 @@ export function detectors(lines, options) {
                     out.push(f("DANGLING_TOOL_CALL", "advisory", { tool_use_id: b.id }, "A tool call's result never reached the model; the tool may have run."));
     }
     // LOST_COMMS: the session went silent (squawk 7600).
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         if (e.kind === "session.lost_contact")
             out.push(f("LOST_COMMS", "warning", { seq: e.seq }, "The agent stopped sending heartbeats: lost contact."));
     }
@@ -377,8 +381,7 @@ export function detectors(lines, options) {
 /** The latest budget and call limit a person granted (spec/approvals.md §4), if any. */
 export function grantedLimits(lines) {
     const out = {};
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         if (e.kind !== "control" || e.meta.action !== "permission")
             continue;
         if (Number.isSafeInteger(e.meta.budget_micro_usd))

package/dist/analysis/faults.js

@@ -95,6 +95,17 @@ export const FAULTS = {
         ar: "بلوغ حدّ استدعاءات النموذج",
     },
     MODEL_DEPRECATED: { fault: "BBX-3103", en: "Deprecated model", ar: "نموذج متوقّف الدعم" },
+    AGENT_SPEND: { fault: "BBX-3104", en: "Agent spend limit", ar: "حدّ إنفاق الوكيل" },
+    AGENT_CALL_LIMIT: {
+        fault: "BBX-3105",
+        en: "Agent model-call limit reached",
+        ar: "بلوغ حدّ استدعاءات النموذج للوكيل",
+    },
+    AGENT_OUTLIER: {
+        fault: "BBX-3106",
+        en: "Agent far above its peers",
+        ar: "وكيل يتجاوز أقرانه بكثير",
+    },
     PLAN_DEVIATION: {
         fault: "BBX-4101",
         en: "Deviation from the flight plan",
@@ -268,6 +279,11 @@ export const FAULTS = {
         en: "A tool's definition differs from earlier sessions",
         ar: "يختلف تعريف أداة عمّا رأته الجلسات السابقة",
     },
+    ELICITATION_SECRET: {
+        fault: "BBX-7408",
+        en: "An MCP server asked the user for a credential",
+        ar: "طلب خادم MCP من المستخدم بيانات اعتماد",
+    },
     REVOKED_MEMORY_READ: {
         fault: "BBX-7101",
         en: "A revoked memory was used",
@@ -394,6 +410,61 @@ export const FAULTS = {
         en: "The agent can reach the internet around the gateway",
         ar: "يستطيع الوكيل الوصول إلى الإنترنت متجاوزاً البوابة",
     },
+    NO_CLEARANCE: {
+        fault: "BBX-8901",
+        en: "Changed a shared resource without a clearance",
+        ar: "غيّر موردًا مشتركًا دون تصريح",
+    },
+    NOTAM_CONFLICT: {
+        fault: "BBX-8902",
+        en: "Acted against an operator notice",
+        ar: "تصرّف بخلاف إشعار من المشغّل",
+    },
+    ENVELOPE_SHAPED: {
+        fault: "BBX-8903",
+        en: "A request was shaped to fit the operator's envelope",
+        ar: "عُدّل طلب ليبقى ضمن حدود المشغّل",
+    },
+    EMERGENCY_LOCATOR: {
+        fault: "BBX-8904",
+        en: "Contact lost with an action open",
+        ar: "انقطع الاتصال وإجراء ما زال مفتوحًا",
+    },
+    SAFETY_REPORT: {
+        fault: "BBX-8905",
+        en: "Safety report from the agent",
+        ar: "بلاغ سلامة من الوكيل",
+    },
+    MAYDAY: {
+        fault: "BBX-8906",
+        en: "Mayday: the agent asks for help",
+        ar: "نداء استغاثة: الوكيل يطلب المساعدة",
+    },
+    PAN_PAN: {
+        fault: "BBX-8907",
+        en: "Pan-pan: the agent is unsure",
+        ar: "نداء عاجل: الوكيل غير متأكد",
+    },
+    UNAPPROVED_MODIFICATION: {
+        fault: "BBX-8908",
+        en: "The agent runs a configuration with no type certificate",
+        ar: "يعمل الوكيل بإعداد بلا شهادة طراز",
+    },
+    CHECK_OVERDUE: {
+        fault: "BBX-8909",
+        en: "A scheduled check is overdue",
+        ar: "فحص مجدول متأخر",
+    },
+    RATING_LAPSED: {
+        fault: "BBX-8910",
+        en: "A type rating has lapsed",
+        ar: "انتهت صلاحية تأهيل الطراز",
+    },
+    APPROVER_FATIGUE: {
+        fault: "BBX-8911",
+        en: "An approver approves everything in seconds",
+        ar: "معتمِد يوافق على كل شيء في ثوانٍ",
+    },
 };
 /** The fault for a finding code; unknown codes get a generic entry, never an exception. */
 export function faultOf(code) {

package/dist/analysis/grounding.js

@@ -3,7 +3,7 @@
 // the person's words, the system prompt, the tool results it passed back) and the tool results on
 // the record. Exact, no model, Arabic and English. Mirrors
 // sdks/python/src/zanii_blackbox/analysis/grounding.py; pinned by spec/vectors/grounding.json.
-import { callsOf } from "../reconcile/record.js";
+import { callsOf, envelopesOf } from "../reconcile/record.js";
 import { canonical } from "../reconcile/shared.js";
 import { toolCallsOf } from "./detectors.js";
 import { answerText, canonicalNumber, identifierSpans, normaliseValue, western, } from "./hallucination.js";
@@ -490,8 +490,7 @@ export function answersOf(lines, bodies) {
     // tool results on the record, by seq, to add those before each answer
     const results = [];
     // (each answer's evidence: its request, then the tool results before it, as record lines)
-    for (const l of lines) {
-        const e = JSON.parse(l);
+    for (const e of envelopesOf(lines)) {
         if (e.kind === "tool.result" || (e.kind === "sdk.event" && e.meta.type === "tool.result")) {
             const b = bodies(e.body_hash);
             results.push({ seq: e.seq, text: b ? decoder.decode(b) : "" });
@@ -584,8 +583,7 @@ export function parseGroundingAnswer(v) {
  * recorded as `control {action: "grounding", via: "model"}` with the claims as the body. */
 export function modelGroundingFindings(lines, bodies) {
     const out = [];
-    for (const l of lines) {
-        const e = JSON.parse(l);
+    for (const e of envelopesOf(lines)) {
         if (e.kind !== "control" || e.meta.action !== "grounding" || e.meta.via !== "model")
             continue;
         const seq = e.meta.answer_seq;
@@ -673,8 +671,7 @@ const STEPS = 100;
 export function judgeRequest(sessionId, answer, lines) {
     const steps = [];
     const callTools = new Map();
-    for (const l of lines) {
-        const e = JSON.parse(l);
+    for (const e of envelopesOf(lines)) {
         if (e.seq >= answer.seq)
             break;
         const m = e.meta;
@@ -735,8 +732,7 @@ export function parseJudgeAnswer(v) {
 /** §12.1: JUDGE_FAILED for each rubric step a judge failed, from its recorded verdicts. */
 export function judgeFindings(lines, bodies) {
     const out = [];
-    for (const l of lines) {
-        const e = JSON.parse(l);
+    for (const e of envelopesOf(lines)) {
         if (e.kind !== "control" || e.meta.action !== "judge" || e.meta.via !== "model")
             continue;
         const seq = e.meta.answer_seq;

package/dist/analysis/guard.d.ts

@@ -0,0 +1,72 @@
+export type GuardVerdict = "allow" | "hold" | "block";
+export type GuardMode = "off" | "monitor" | "enforce";
+export interface GuardConfig {
+    canary_tools: string[];
+    canary_tokens: string[];
+    untrusted_sources: string[];
+    sensitive: string[];
+    egress: string[];
+    high_risk: string[];
+    exfil_window_seconds: number;
+}
+export interface GuardFinding {
+    rule: string;
+    severity: "medium" | "high" | "critical";
+    /** The OWASP Top 10 for Agentic Applications entry. */
+    asi: string;
+    detail: string;
+}
+export interface GuardState {
+    taint: {
+        source: string;
+        markers: number;
+    } | null;
+    sensitive: {
+        tool: string;
+        at_ms: number;
+    } | null;
+    pins: Record<string, string>;
+    changed: string[];
+}
+/** A tool call: its names (an MCP tool has two, `mcp__<server>__<tool>` first), its arguments. */
+export interface GuardCall {
+    names: string[];
+    args: unknown;
+    at_ms: number;
+}
+/** The strictest of several modes (off < monitor < enforce); unknown values count as off. */
+export declare function guardMode(...modes: Array<string | null | undefined>): GuardMode;
+/** spec/guard.md §1: a guard file, checked; throws on anything wrong. */
+export declare function loadGuardConfig(doc: unknown): GuardConfig;
+/** A session's state before anything was seen. */
+export declare function guardState(): GuardState;
+/** spec/guard.md §2: the decision on one call, and the state after it. */
+export declare function guardCheck(config: GuardConfig, state: GuardState, call: GuardCall): {
+    verdict: GuardVerdict;
+    findings: GuardFinding[];
+    state: GuardState;
+};
+/** spec/guard.md §3: a tool's result coming back. From an untrusted source, it taints the session. */
+export declare function guardObserve(config: GuardConfig, state: GuardState, result: {
+    names: string[];
+    content: unknown;
+}): GuardState;
+/** spec/guard.md §4: a tools/list answer's definition hashes. The first one seen for each tool is its
+ * pin; a later, different one marks the tool changed for the rest of the session. */
+export declare function guardPin(state: GuardState, defs: Record<string, string>): {
+    state: GuardState;
+    changed: string[];
+};
+export interface GuardToolResult {
+    /** The model's id for the call (`tool_use_id`, `tool_call_id`, `call_id`). */
+    id: string;
+    name: string;
+    args: unknown;
+    content: unknown;
+}
+/**
+ * spec/guard.md §5: the tool results a model request's newest turn hands back, each with the call
+ * that asked for it (from the same request). Anthropic Messages, Chat Completions and Responses.
+ * A result whose call isn't in the request (a Responses `previous_response_id`) is left out.
+ */
+export declare function guardToolResults(body: unknown): GuardToolResult[];