@zanii/blackbox 0.22.0 → 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/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[];

package/dist/analysis/guard.js

@@ -0,0 +1,240 @@
+// spec/guard.md: the inline guard. Decides on a tool call before the gateway forwards it (an MCP
+// tools/call) or before it accepts the tool's result back (a model's tool_use): canary tools and
+// tokens, tool pinning, exfiltration sequences, holds on high-risk calls after untrusted content.
+// Pure: the caller keeps the state and passes the clock. Ported from @zanii/guard (the rules and
+// their names), with Blackbox's own injection rules (analysis/injection.ts). Mirrors
+// analysis/guard.py; pinned by spec/vectors/guard.json.
+import { injectionRule } from "./injection.js";
+const LISTS = [
+    "canary_tools",
+    "canary_tokens",
+    "untrusted_sources",
+    "sensitive",
+    "egress",
+    "high_risk",
+];
+const MODES = ["off", "monitor", "enforce"];
+/** The strictest of several modes (off < monitor < enforce); unknown values count as off. */
+export function guardMode(...modes) {
+    let best = 0;
+    for (const m of modes)
+        best = Math.max(best, MODES.indexOf(m));
+    return MODES[best];
+}
+/** spec/guard.md §1: a guard file, checked; throws on anything wrong. */
+export function loadGuardConfig(doc) {
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        throw new Error("guard: the file must be a JSON object");
+    const d = doc;
+    if (d.version !== 1)
+        throw new Error("guard: version must be 1");
+    for (const k of Object.keys(d))
+        if (k !== "version" &&
+            k !== "exfil_window_seconds" &&
+            !LISTS.includes(k))
+            throw new Error(`guard: unknown field ${k}`);
+    const out = { exfil_window_seconds: 600 };
+    for (const k of LISTS) {
+        const v = d[k] ?? [];
+        const re = k === "canary_tokens" ? /^[A-Za-z0-9_.:-]{12,128}$/ : /^[^\s]{1,256}$/;
+        if (!Array.isArray(v) || v.length > 100 || !v.every((x) => typeof x === "string" && re.test(x)))
+            throw new Error(k === "canary_tokens"
+                ? "guard: canary_tokens must be at most 100 strings of 12-128 letters, digits or _.:-"
+                : `guard: ${k} must be at most 100 tool patterns of 1-256 characters, no spaces`);
+        out[k] = v;
+    }
+    const w = d.exfil_window_seconds;
+    if (w !== undefined) {
+        if (!Number.isSafeInteger(w) || w < 1 || w > 86_400)
+            throw new Error("guard: exfil_window_seconds must be an integer 1-86400");
+        out.exfil_window_seconds = w;
+    }
+    return out;
+}
+/** A session's state before anything was seen. */
+export function guardState() {
+    return { taint: null, sensitive: null, pins: {}, changed: [] };
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const glob = (p) => new RegExp(`^${p.split("*").map(escapeRe).join(".*")}$`);
+const matches = (patterns, names) => patterns.some((p) => {
+    const re = glob(p);
+    return names.some((n) => re.test(n));
+});
+/** Every string in a JSON value, depth first, in key order, one per line. */
+function textOf(v) {
+    const out = [];
+    const walk = (x) => {
+        if (typeof x === "string")
+            out.push(x);
+        else if (Array.isArray(x))
+            for (const y of x)
+                walk(y);
+        else if (x && typeof x === "object")
+            for (const y of Object.values(x))
+                walk(y);
+    };
+    walk(v);
+    return out.join("\n");
+}
+/** spec/guard.md §2: the decision on one call, and the state after it. */
+export function guardCheck(config, state, call) {
+    const tool = call.names[0] ?? "";
+    const findings = [];
+    let verdict = "allow";
+    const add = (f, v) => {
+        findings.push(f);
+        if (v === "block" || (v === "hold" && verdict === "allow"))
+            verdict = v;
+    };
+    const text = textOf(call.args);
+    if (matches(config.canary_tools, call.names))
+        add({
+            rule: "canary-tool",
+            severity: "critical",
+            asi: "ASI10",
+            detail: `${tool} is a canary no legitimate run calls`,
+        }, "block");
+    if (config.canary_tokens.some((t) => text.includes(t)))
+        add({
+            rule: "canary-token",
+            severity: "critical",
+            asi: "ASI02",
+            detail: `a planted canary token is leaving through ${tool}`,
+        }, "block");
+    if (state.changed.includes(tool))
+        add({
+            rule: "tool-changed",
+            severity: "high",
+            asi: "ASI04",
+            detail: `${tool} changed since it was first listed in this session`,
+        }, "block");
+    const s = state.sensitive;
+    if (s &&
+        matches(config.egress, call.names) &&
+        call.at_ms - s.at_ms <= config.exfil_window_seconds * 1000)
+        add({
+            rule: "exfil-sequence",
+            severity: "high",
+            asi: "ASI02",
+            detail: `egress through ${tool} right after reading ${s.tool}`,
+        }, "block");
+    if (injectionRule(text) !== null)
+        add({
+            rule: "injection-in-args",
+            severity: "high",
+            asi: "ASI01",
+            detail: `the arguments to ${tool} carry instructions aimed at an agent`,
+        }, "hold");
+    const t = state.taint;
+    if (t && matches(config.high_risk, call.names))
+        add({
+            rule: "tainted-high-risk",
+            severity: t.markers > 0 ? "high" : "medium",
+            asi: "ASI01",
+            detail: `a high-risk call after reading untrusted content from ${t.source}${t.markers > 0 ? " that contained injection attempts" : ""}`,
+        }, "hold");
+    const next = matches(config.sensitive, call.names)
+        ? { ...state, sensitive: { tool, at_ms: call.at_ms } }
+        : state;
+    return { verdict, findings, state: next };
+}
+/** spec/guard.md §3: a tool's result coming back. From an untrusted source, it taints the session. */
+export function guardObserve(config, state, result) {
+    if (!matches(config.untrusted_sources, result.names))
+        return state;
+    const marked = injectionRule(textOf(result.content)) !== null ? 1 : 0;
+    return {
+        ...state,
+        taint: { source: result.names[0] ?? "", markers: (state.taint?.markers ?? 0) + marked },
+    };
+}
+/** 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 function guardPin(state, defs) {
+    const pins = { ...state.pins };
+    const changed = [];
+    for (const [name, hash] of Object.entries(defs)) {
+        const pin = pins[name];
+        if (pin === undefined)
+            pins[name] = hash;
+        else if (pin !== hash && !state.changed.includes(name))
+            changed.push(name);
+    }
+    return { state: { ...state, pins, changed: [...state.changed, ...changed] }, changed };
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const parsed = (v) => {
+    if (typeof v !== "string")
+        return v ?? {};
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return v;
+    }
+};
+/**
+ * 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 function guardToolResults(body) {
+    if (!isObj(body))
+        return [];
+    const out = [];
+    const calls = new Map();
+    const messages = body.messages;
+    if (Array.isArray(messages) && messages.length) {
+        let i = messages.length - 1;
+        while (i > 0 && messages[i]?.role === "tool")
+            i -= 1;
+        for (const m of messages.slice(0, i + 1).filter(isObj)) {
+            if (m.role !== "assistant")
+                continue;
+            if (Array.isArray(m.content))
+                for (const b of m.content.filter(isObj))
+                    if (b.type === "tool_use" && typeof b.id === "string" && typeof b.name === "string")
+                        calls.set(b.id, { name: b.name, args: b.input ?? {} });
+            if (Array.isArray(m.tool_calls))
+                for (const c of m.tool_calls.filter(isObj)) {
+                    const f = isObj(c.function) ? c.function : {};
+                    if (typeof c.id === "string" && typeof f.name === "string")
+                        calls.set(c.id, { name: f.name, args: parsed(f.arguments) });
+                }
+        }
+        const take = (id, content) => {
+            const c = typeof id === "string" ? calls.get(id) : undefined;
+            if (c)
+                out.push({ id: id, name: c.name, args: c.args, content: content ?? null });
+        };
+        for (const m of messages.slice(i).filter(isObj)) {
+            if (m.role === "tool")
+                take(m.tool_call_id, m.content);
+            else if (m.role === "user" && Array.isArray(m.content))
+                for (const b of m.content.filter(isObj))
+                    if (b.type === "tool_result")
+                        take(b.tool_use_id, b.content);
+        }
+        return out;
+    }
+    const input = body.input;
+    if (!Array.isArray(input) || input.length === 0)
+        return out;
+    let i = input.length - 1;
+    while (i > 0 && input[i]?.type === "function_call_output")
+        i -= 1;
+    for (const item of input.slice(0, i + 1).filter(isObj))
+        if (item.type === "function_call" &&
+            typeof item.call_id === "string" &&
+            typeof item.name === "string")
+            calls.set(item.call_id, { name: item.name, args: parsed(item.arguments) });
+    for (const item of input.slice(i).filter(isObj)) {
+        if (item.type !== "function_call_output" || typeof item.call_id !== "string")
+            continue;
+        const c = calls.get(item.call_id);
+        if (c)
+            out.push({ id: item.call_id, name: c.name, args: c.args, content: item.output ?? null });
+    }
+    return out;
+}

package/dist/analysis/hallucination.js

@@ -3,7 +3,7 @@
 // right after an error; quoting a tool it never called. Pure functions over the record, no model.
 // Mirrors sdks/python/src/zanii_blackbox/analysis/hallucination.py; pinned by
 // spec/vectors/hallucination.json.
-import { callsOf } from "../reconcile/record.js";
+import { callsOf, envelopesOf } from "../reconcile/record.js";
 import { canonical, isObj } from "../reconcile/shared.js";
 import { toolCallsOf, toolResultsOf } from "./detectors.js";
 const decoder = new TextDecoder();
@@ -217,7 +217,7 @@ export function toolHallucinations(lines, bodies) {
     const calls = callsOf(lines, bodies);
     const modelCalls = toolCallsOf(calls);
     const results = toolResultsOf(calls, lines);
-    const events = lines.map((l) => JSON.parse(l));
+    const events = envelopesOf(lines);
     const out = [];
     const push = (at, finding) => out.push({ ...finding, at });
     // the model side: each tool call against the request that produced it

package/dist/analysis/index.d.ts

@@ -20,6 +20,10 @@ export interface Finding {
         [key: string]: string | number | boolean;
     };
     detail?: string;
+    /** The numbers behind it (integers), recorded with it but not part of its identity. */
+    figures?: {
+        [key: string]: number;
+    };
 }
 export interface AnalyzeOptions {
     /** Body bytes by hash (SDK events carry their ids in the body; requests and responses are bodies). */
@@ -47,8 +51,22 @@ export interface Ev extends Envelope {
         [key: string]: Json;
     };
 }
-/** Parses the lines once, attaching SDK event bodies. */
+/** Parses the lines once, attaching SDK event bodies. On a tracked record (`Analyzer`), only the
+ * lines added since the last call are read. */
 export declare function eventsOf(lines: readonly string[], bodies: AnalyzeOptions["bodies"]): Ev[];
+/**
+ * spec/findings.md §14 (G33): the analyses over one session's growing record. Each `findings` call
+ * reads only the lines added since the last one (each line is parsed once, the calls are rebuilt
+ * from the new events only) and gives exactly what `analyze` gives over the whole record.
+ */
+export declare class Analyzer {
+    readonly lines: string[];
+    readonly bodies: AnalyzeOptions["bodies"];
+    constructor(bodies: AnalyzeOptions["bodies"]);
+    /** Appends the record's new lines (in seq order; a record only grows). */
+    push(lines: Iterable<string>): void;
+    findings(options: Omit<AnalyzeOptions, "bodies">): Finding[];
+}
 /** Every analysis, in spec order. */
 export declare function analyze(lines: readonly string[], options: AnalyzeOptions): Finding[];
 /**
@@ -94,6 +112,8 @@ export declare function toolDrifted(events: Ev[]): Finding[];
  * the call went to an MCP tool. A request refused for it (`outbound_blocked`) sent nothing.
  */
 export declare function secretSent(events: Ev[]): Finding[];
+/** spec/mcp.md §6: an MCP server asked the user for a credential through `elicitation/create`. */
+export declare function elicitationSecret(events: Ev[]): Finding[];
 /** spec/findings.md §12b: a person the agent served said an answer was wrong (👎), once per answer. */
 export declare function userDownvotes(events: Ev[]): Finding[];
 /** N6 (idea S3): the gateway refused a request that carried the session's own token. */