@zanii/blackbox 0.15.1 → 0.16.1

package/dist/fleet/insights.d.ts

@@ -0,0 +1,82 @@
+import type { Summary } from "./index.ts";
+declare const SEVERITIES: readonly ["warning", "caution", "advisory"];
+type Severities = Record<(typeof SEVERITIES)[number], number>;
+export declare const CONTEXT_MAX = 600;
+export interface Counts {
+    sessions: number;
+    closed: number;
+    success: number;
+    failure: number;
+    abandoned: number;
+    spend_micro_usd: number;
+    findings: Severities;
+    blocked: number;
+}
+export interface Issue {
+    code: string;
+    severity: string | null;
+    sessions: number;
+    findings: number;
+    failed: number;
+    spend_micro_usd: number;
+    first_seen: string;
+    last_seen: string;
+    example: {
+        session_id: string;
+        seq: number;
+    } | null;
+    days: number[];
+}
+export interface Group {
+    key: string;
+    sessions: number;
+    success: number;
+    failure: number;
+    spend_micro_usd: number;
+    findings: number;
+    warnings: number;
+}
+export interface Insights {
+    from: string;
+    to: string;
+    days: Array<{
+        day: string;
+        cost_per_success_micro_usd: number | null;
+    } & Counts>;
+    issues: Issue[];
+    by: {
+        tenant: Group[];
+        environment: Group[];
+        agent: Group[];
+        tool: Group[];
+    };
+    totals: Counts & {
+        cost_per_success_micro_usd: number | null;
+    };
+}
+type SummaryIn = Partial<Summary> & {
+    session_id: string;
+    started_at: string;
+    environment?: string;
+};
+/** spec/insights.md §1: days, issues, the fleet by group and the totals of a window's sessions. */
+export declare function insights(summaries: readonly SummaryIn[], window: {
+    from: string;
+    to: string;
+}): Insights;
+/**
+ * spec/insights.md §3: the record as one line per event, metadata only, at most 600 events. With
+ * `body` (a body by its hash), a verify event also says `ok=true` or `ok=false`.
+ */
+export declare function copilotContext(lines: readonly string[], body?: (hash: string) => Uint8Array | null | undefined): string;
+/** spec/insights.md §3: the system prompt and the user turn for the investigator's model. */
+export declare function copilotPrompt(question: string, context: string, lang?: string): {
+    system: string;
+    user: string;
+};
+/** spec/insights.md §3: the answer, and the cited seqs that are events of the record. */
+export declare function parseCopilotAnswer(text: string, count: number): {
+    answer: string;
+    cites: number[];
+};
+export {};

package/dist/fleet/insights.js

@@ -0,0 +1,307 @@
+// Insights and the investigator (spec/insights.md): pure functions over what the gateway keeps.
+// `insights` sums session summaries into trends, recurring issues and the fleet by group;
+// `copilotContext`, `copilotPrompt` and `parseCopilotAnswer` are the investigator's record, request
+// and answer. Mirrors sdks/python/src/zanii_blackbox/insights.py; pinned by spec/vectors/insights.json.
+const SEVERITIES = ["warning", "caution", "advisory"];
+const TRAILING_DATE = /\s+\d{4}-\d{2}-\d{2}$/;
+const GROUP_MAX = 50;
+export const CONTEXT_MAX = 600;
+const HEAD = 50;
+const TAIL = 100;
+const VALUE_MAX = 120;
+const divHalfUp = (a, b) => Math.floor((2 * a + b) / (2 * b));
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function daysOf(from, to) {
+    const out = [];
+    const d = new Date(`${from}T00:00:00Z`);
+    const stop = new Date(`${to}T00:00:00Z`);
+    while (d < stop) {
+        out.push(d.toISOString().slice(0, 10));
+        d.setUTCDate(d.getUTCDate() + 1);
+    }
+    return out;
+}
+const emptyCounts = () => ({
+    sessions: 0,
+    closed: 0,
+    success: 0,
+    failure: 0,
+    abandoned: 0,
+    spend_micro_usd: 0,
+    findings: { warning: 0, caution: 0, advisory: 0 },
+    blocked: 0,
+});
+function count(c, s) {
+    c.sessions += 1;
+    c.closed += s.closed ? 1 : 0;
+    if (s.outcome === "success" || s.outcome === "failure" || s.outcome === "abandoned")
+        c[s.outcome] += 1;
+    c.spend_micro_usd += Number(s.spend_micro_usd ?? 0);
+    for (const sev of SEVERITIES)
+        c.findings[sev] += Number(s.findings?.[sev] ?? 0);
+    c.blocked += s.blocked_by ? 1 : 0;
+}
+const perSuccess = (c) => (c.success ? divHalfUp(c.spend_micro_usd, c.success) : null);
+const agentOf = (label) => (typeof label === "string" ? label.replace(TRAILING_DATE, "").trim() : "") || "(none)";
+/** spec/insights.md §1: days, issues, the fleet by group and the totals of a window's sessions. */
+export function insights(summaries, window) {
+    const days = daysOf(window.from, window.to);
+    const index = new Map(days.map((d, i) => [d, i]));
+    const picked = summaries
+        .filter((s) => index.has(String(s.started_at ?? "").slice(0, 10)))
+        .sort((a, b) => cmp(String(a.started_at), String(b.started_at)) ||
+        cmp(String(a.session_id), String(b.session_id)));
+    const perDay = days.map(emptyCounts);
+    const totals = emptyCounts();
+    const issues = new Map();
+    const groups = {
+        tenant: new Map(),
+        environment: new Map(),
+        agent: new Map(),
+        tool: new Map(),
+    };
+    for (const s of picked) {
+        const at = index.get(s.started_at.slice(0, 10));
+        count(perDay[at], s);
+        count(totals, s);
+        const spend = Number(s.spend_micro_usd ?? 0);
+        const last = s.last_event_at || s.started_at;
+        for (const [code, n] of Object.entries(s.finding_codes ?? {})) {
+            let i = issues.get(code);
+            if (!i) {
+                i = {
+                    code,
+                    severity: null,
+                    sessions: 0,
+                    findings: 0,
+                    failed: 0,
+                    spend_micro_usd: 0,
+                    first_seen: s.started_at,
+                    last_seen: last,
+                    example: null,
+                    days: days.map(() => 0),
+                };
+                issues.set(code, i);
+            }
+            i.sessions += 1;
+            i.findings += Number(n);
+            i.failed += s.outcome === "failure" ? 1 : 0;
+            i.spend_micro_usd += spend;
+            if (s.started_at < i.first_seen)
+                i.first_seen = s.started_at;
+            if (last > i.last_seen)
+                i.last_seen = last;
+            i.days[at] = i.days[at] + 1;
+        }
+        for (const f of s.latest_findings ?? []) {
+            const i = issues.get(String(f.code));
+            if (i) {
+                i.severity = f.severity ?? null;
+                i.example = { session_id: s.session_id, seq: f.seq };
+            }
+        }
+        const found = s.findings ?? { warning: 0, caution: 0, advisory: 0 };
+        const nFound = SEVERITIES.reduce((a, sev) => a + Number(found[sev] ?? 0), 0);
+        const keys = {
+            tenant: [s.tenant || "default"],
+            environment: [s.environment || "(none)"],
+            agent: [agentOf(s.label)],
+            tool: Object.keys(s.tools ?? {}).sort(cmp),
+        };
+        for (const [name, values] of Object.entries(keys)) {
+            for (const key of values) {
+                let g = groups[name].get(key);
+                if (!g) {
+                    g = {
+                        key,
+                        sessions: 0,
+                        success: 0,
+                        failure: 0,
+                        spend_micro_usd: 0,
+                        findings: 0,
+                        warnings: 0,
+                    };
+                    groups[name].set(key, g);
+                }
+                g.sessions += 1;
+                g.success += s.outcome === "success" ? 1 : 0;
+                g.failure += s.outcome === "failure" ? 1 : 0;
+                g.spend_micro_usd += spend;
+                g.findings += nFound;
+                g.warnings += Number(found.warning ?? 0);
+            }
+        }
+    }
+    const ordered = (m) => [...m.values()]
+        .sort((a, b) => b.spend_micro_usd - a.spend_micro_usd || cmp(a.key, b.key))
+        .slice(0, GROUP_MAX);
+    return {
+        from: window.from,
+        to: window.to,
+        days: days.map((day, i) => {
+            const c = perDay[i];
+            return { day, ...c, cost_per_success_micro_usd: perSuccess(c) };
+        }),
+        issues: [...issues.values()].sort((a, b) => b.sessions - a.sessions || b.findings - a.findings || cmp(a.code, b.code)),
+        by: {
+            tenant: ordered(groups.tenant),
+            environment: ordered(groups.environment),
+            agent: ordered(groups.agent),
+            tool: ordered(groups.tool),
+        },
+        totals: { ...totals, cost_per_success_micro_usd: perSuccess(totals) },
+    };
+}
+// ------------------------------------------------------------------ the investigator
+const DETAILS = {
+    "session.open": ["label", "mode", "environment"],
+    "llm.request": ["provider"],
+    "llm.response": ["model", "status", "stop_reason", "finish_reason", "response_status"],
+    "llm.incomplete": ["model", "status", "reason"],
+    "tool.call": ["tool", "method"],
+    "tool.result": ["tool", "method"],
+    "sdk.event": ["type", "name"],
+    finding: ["code", "severity"],
+    control: ["action", "code", "by"],
+    outcome: ["outcome", "by", "note"],
+    "session.lost_contact": ["silent_ms"],
+    "capture.gap": ["missed"],
+};
+function value(v) {
+    if (typeof v === "number")
+        return Number.isSafeInteger(v) ? String(v) : null;
+    if (typeof v !== "string")
+        return null;
+    // spaces, tabs and newlines only (Unicode whitespace differs by language); by code point
+    const short = Array.from(v.replace(/[ \t\n\r]+/g, " ").replace(/^ +| +$/g, ""))
+        .slice(0, VALUE_MAX)
+        .join("");
+    return JSON.stringify(short);
+}
+const isMoment = (e) => {
+    const status = e.meta?.status;
+    return (e.kind === "finding" ||
+        e.kind === "control" ||
+        e.kind === "outcome" ||
+        e.kind === "session.lost_contact" ||
+        e.kind === "capture.gap" ||
+        e.kind === "llm.incomplete" ||
+        (e.kind === "llm.response" && Number.isInteger(status) && status >= 400));
+};
+function evenly(items, n) {
+    if (n <= 0 || items.length === 0)
+        return [];
+    if (n >= items.length)
+        return [...items];
+    return Array.from({ length: n }, (_, i) => items[Math.floor((i * items.length) / n)]);
+}
+/** A verify event's pass or fail, from its body: the one value read from a body. Never `detail`. */
+function verifyOk(e, body) {
+    const meta = (e.meta ?? {});
+    if (!body || e.kind !== "sdk.event" || meta.type !== "verify")
+        return null;
+    const raw = body(String(e.body_hash));
+    if (!raw || raw.length === 0)
+        return null; // erased, or never sent
+    try {
+        const doc = JSON.parse(new TextDecoder().decode(raw));
+        const ok = doc && typeof doc === "object" && !Array.isArray(doc) ? doc.ok : null;
+        return typeof ok === "boolean" ? ok : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * spec/insights.md §3: the record as one line per event, metadata only, at most 600 events. With
+ * `body` (a body by its hash), a verify event also says `ok=true` or `ok=false`.
+ */
+export function copilotContext(lines, body) {
+    const events = lines.map((l) => JSON.parse(l));
+    const n = events.length;
+    let shown;
+    if (n > CONTEXT_MAX) {
+        const base = new Set();
+        for (let i = 0; i < Math.min(HEAD, n); i++)
+            base.add(i);
+        for (let i = Math.max(0, n - TAIL); i < n; i++)
+            base.add(i);
+        const moments = events
+            .map((e, i) => (isMoment(e) && !base.has(i) ? i : -1))
+            .filter((i) => i >= 0);
+        const room = CONTEXT_MAX - base.size;
+        const keep = new Set(base);
+        if (moments.length >= room)
+            for (const i of evenly(moments, room))
+                keep.add(i);
+        else {
+            const m = new Set(moments);
+            for (const i of moments)
+                keep.add(i);
+            const rest = [];
+            for (let i = 0; i < n; i++)
+                if (!base.has(i) && !m.has(i))
+                    rest.push(i);
+            for (const i of evenly(rest, room - moments.length))
+                keep.add(i);
+        }
+        shown = [...keep].sort((a, b) => a - b);
+    }
+    else
+        shown = events.map((_, i) => i);
+    const first = events[0] ?? {};
+    const head = `Session ${first.session_id ?? ""}: ${n} events`;
+    const out = [head + (shown.length < n ? ` (${n - shown.length} not shown)` : "")];
+    for (const i of shown) {
+        const e = events[i];
+        const meta = (e.meta ?? {});
+        const parts = [`#${e.seq}`, String(e.ts), String(e.kind)];
+        for (const k of DETAILS[String(e.kind)] ?? []) {
+            const v = value(meta[k]);
+            if (v !== null)
+                parts.push(`${k}=${v}`);
+        }
+        const ok = verifyOk(e, body);
+        if (ok !== null)
+            parts.push(`ok=${ok}`);
+        out.push(parts.join(" "));
+    }
+    return out.join("\n");
+}
+const SYSTEM = "You are an investigator reading one AI agent's flight record from Zanii Blackbox. The record " +
+    "below is one line per event: #seq, time, kind, then its metadata; ok=true or ok=false on a " +
+    "verify event is the result of the agent's own check. Answer the question only " +
+    "from the record. Cite the event numbers your answer rests on. If the record doesn't say, say " +
+    "so. Be brief and concrete. Answer with JSON only: " +
+    '{"answer": "<your answer>", "cites": [<seq>, ...]}';
+/** spec/insights.md §3: the system prompt and the user turn for the investigator's model. */
+export function copilotPrompt(question, context, lang = "en") {
+    return {
+        system: SYSTEM + (lang === "ar" ? " Write the answer in Arabic." : ""),
+        user: `${context}\n\nQuestion: ${question}`,
+    };
+}
+/** spec/insights.md §3: the answer, and the cited seqs that are events of the record. */
+export function parseCopilotAnswer(text, count) {
+    const raw = text.trim();
+    const a = raw.indexOf("{");
+    const b = raw.lastIndexOf("}");
+    let got = null;
+    if (a >= 0 && b > a) {
+        try {
+            got = JSON.parse(raw.slice(a, b + 1));
+        }
+        catch {
+            got = null;
+        }
+    }
+    const doc = got;
+    if (!doc || typeof doc !== "object" || Array.isArray(doc) || typeof doc.answer !== "string")
+        return { answer: raw, cites: [] };
+    const cites = Array.isArray(doc.cites)
+        ? [
+            ...new Set(doc.cites.filter((c) => Number.isInteger(c) && c >= 0 && c < count)),
+        ].sort((x, y) => x - y)
+        : [];
+    return { answer: doc.answer.trim(), cites: cites.slice(0, 20) };
+}

package/dist/index.d.ts

@@ -30,6 +30,7 @@ export { type EvidencePack, type EvidencePackOptions, evidencePack, renderEviden
 export { buildEquivocationProof, compareViews, cosignLedgerSth, verifyEquivocationProof, verifyLedgerCosignature, } from "./federation/index.ts";
 export { buildOwnerAttestation, buildPayment, CURRENCIES, FTA_WALL_ID, financeFindings, formatMoney, ftaPayload, parseMoney, paymentsOf, screenCounterparty, screeningPayload, verifyOwnerAttestation, verifyOwnerBinding, } from "./finance/index.ts";
 export { aggregateFindings, airworthiness, type Collision, collisions, didFromSeed, type FindingGroup, incidentReport, logbook, type Summary, sessionSummary, signatureOf, signatures, signCertificate, verifyCertificate, } from "./fleet/index.ts";
+export { copilotContext, copilotPrompt, type Insights, insights, parseCopilotAnswer, } from "./fleet/insights.ts";
 export { type AppealItem, type AppealPack, appealPack, decisionPayload, GOV_DECISION_KINDS, renderAppealPack, ruleConsistency, signSubjectClaim, subjectTag, verifyDecision, verifyFactors, verifySubjectClaim, } from "./gov/index.ts";
 export { accessPayload, breakGlass, checkEpisodeTag, clinicianConfirmation, type EpisodeItem, episodeSeed, episodesPack, episodeTag, healthFindings, protocolTrail, recommendationHash, recommendationPayload, verifyCommitment, verifyHealthSignature, } from "./health/index.ts";
 export { attachBlackbox, BlackboxAgentHooks, BlackboxCallbackHandler, type BlackboxCallbacks, blackboxAgentHooks, blackboxCallbacks, blackboxMiddleware, type EventSink, llmIds, llmIdsOf, trackMemory, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI, } from "./hooks/index.ts";

package/dist/index.js

@@ -32,6 +32,7 @@ export { evidencePack, renderEvidencePack, } from "./evidence/index.js";
 export { buildEquivocationProof, compareViews, cosignLedgerSth, verifyEquivocationProof, verifyLedgerCosignature, } from "./federation/index.js";
 export { buildOwnerAttestation, buildPayment, CURRENCIES, FTA_WALL_ID, financeFindings, formatMoney, ftaPayload, parseMoney, paymentsOf, screenCounterparty, screeningPayload, verifyOwnerAttestation, verifyOwnerBinding, } from "./finance/index.js";
 export { aggregateFindings, airworthiness, collisions, didFromSeed, incidentReport, logbook, sessionSummary, signatureOf, signatures, signCertificate, verifyCertificate, } from "./fleet/index.js";
+export { copilotContext, copilotPrompt, insights, parseCopilotAnswer, } from "./fleet/insights.js";
 export { appealPack, decisionPayload, GOV_DECISION_KINDS, renderAppealPack, ruleConsistency, signSubjectClaim, subjectTag, verifyDecision, verifyFactors, verifySubjectClaim, } from "./gov/index.js";
 export { accessPayload, breakGlass, checkEpisodeTag, clinicianConfirmation, episodeSeed, episodesPack, episodeTag, healthFindings, protocolTrail, recommendationHash, recommendationPayload, verifyCommitment, verifyHealthSignature, } from "./health/index.js";
 export { attachBlackbox, BlackboxAgentHooks, BlackboxCallbackHandler, blackboxAgentHooks, blackboxCallbacks, blackboxMiddleware, llmIds, llmIdsOf, trackMemory, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI, } from "./hooks/index.js";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.15.1";
+export declare const VERSION = "0.16.1";

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.15.1";
+export const VERSION = "0.16.1";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "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",