@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/fleet/index.js

@@ -0,0 +1,454 @@
+// Fleet operations (spec/fleet.md): the session summary, the incident report (EN / AR), the logbook.
+// Mirrors sdks/python/src/zanii_blackbox/fleet.py.
+import { createHash, createPrivateKey, createPublicKey, sign as signBytes, verify as verifyBytes, } from "node:crypto";
+import { didFromPublicKey, publicKeyFromDid } from "@zanii/core";
+import { toolCallsOf } from "../analysis/detectors.js";
+import { FAULTS } from "../analysis/faults.js";
+import { eventsOf } from "../analysis/index.js";
+import { landing } from "../analysis/landing.js";
+import { formatAed, sessionCost, toAedFils } from "../cost/index.js";
+import { callsOf } from "../reconcile/record.js";
+import { canonical } from "../reconcile/shared.js";
+const sorted = (m) => Object.fromEntries(Object.keys(m)
+    .sort()
+    .map((k) => [k, m[k]]));
+export function sessionSummary(lines, bodies, prices) {
+    const events = lines.map((l) => JSON.parse(l));
+    const first = events[0];
+    const last = events[events.length - 1];
+    const plan = first.meta.flight_plan;
+    const tools = {};
+    let toolCalls = 0;
+    for (const t of toolCallsOf(callsOf(lines, bodies))) {
+        tools[t.tool] = (tools[t.tool] ?? 0) + 1;
+        toolCalls++;
+    }
+    const findings = { advisory: 0, caution: 0, warning: 0 };
+    const found = [];
+    const codes = {};
+    let outcome = null;
+    let blockedBy = null;
+    let nearMisses = 0;
+    for (const e of events) {
+        if (e.kind === "tool.call" &&
+            e.meta.method === "tools/call" &&
+            typeof e.meta.tool === "string") {
+            tools[e.meta.tool] = (tools[e.meta.tool] ?? 0) + 1;
+            toolCalls++;
+        }
+        else if (e.kind === "finding") {
+            const sev = e.meta.severity;
+            if (sev in findings)
+                findings[sev]++;
+            codes[String(e.meta.code)] = (codes[String(e.meta.code)] ?? 0) + 1;
+            found.push({
+                seq: e.seq,
+                code: String(e.meta.code),
+                fault: typeof e.meta.fault === "string" ? e.meta.fault : null,
+                severity: String(e.meta.severity),
+            });
+        }
+        else if (e.kind === "outcome" && typeof e.meta.outcome === "string")
+            outcome = e.meta.outcome;
+        else if (e.kind === "control" && e.meta.action === "block")
+            blockedBy = String(e.meta.code);
+        else if (e.kind === "control" && e.meta.action === "resume")
+            blockedBy = null;
+        else if (e.kind === "sdk.event" && e.meta.type === "near_miss")
+            nearMisses++;
+    }
+    const claims = { satisfied: 0, failed: 0, unverified: 0 };
+    for (const c of landing(eventsOf(lines, bodies), lines, bodies).claims)
+        claims[c.verdict]++;
+    return {
+        session_id: first.session_id,
+        label: typeof first.meta.label === "string" ? first.meta.label : null,
+        tenant: typeof first.meta.tenant === "string" ? first.meta.tenant : null,
+        objective: typeof plan?.objective === "string" ? plan.objective : null,
+        started_at: first.ts,
+        last_event_at: last.ts,
+        closed: last.kind === "session.close",
+        outcome,
+        events: events.length,
+        model_calls: events.filter((e) => e.kind === "llm.request").length,
+        tool_calls: toolCalls,
+        tools: sorted(tools),
+        spend_micro_usd: sessionCost(lines, prices).total_micro_usd,
+        findings,
+        finding_codes: sorted(codes),
+        latest_findings: found.slice(-5),
+        claims,
+        blocked_by: blockedBy,
+        near_misses: nearMisses,
+    };
+}
+const T = {
+    en: {
+        title: "Incident report",
+        session: "Session",
+        started: "Started",
+        last: "Last event",
+        status: "Status",
+        objective: "Objective",
+        spend: "Spend",
+        blocked: "Blocked by",
+        open: "Open",
+        closed: "Closed",
+        none: "none",
+        happened: "What happened",
+        calls: (m, t) => `${m} model calls, ${t} tool calls.`,
+        top: "Tools used",
+        findings: "Findings",
+        noFindings: "No findings.",
+        head: "| Seq | Fault | Level | What |",
+        level: { advisory: "Advisory", caution: "Caution", warning: "Warning" },
+    },
+    ar: {
+        title: "تقرير حادثة",
+        session: "الجلسة",
+        started: "البداية",
+        last: "آخر حدث",
+        status: "الحالة",
+        objective: "الهدف",
+        spend: "الإنفاق",
+        blocked: "موقوفة بسبب",
+        open: "مفتوحة",
+        closed: "مغلقة",
+        none: "لا شيء",
+        happened: "ما الذي حدث",
+        calls: (m, t) => `${m} استدعاءات للنموذج، ${t} استدعاءات للأدوات.`,
+        top: "الأدوات المستخدمة",
+        findings: "الملاحظات",
+        noFindings: "لا توجد ملاحظات.",
+        head: "| التسلسل | رمز العطل | المستوى | الوصف |",
+        level: { advisory: "إرشادي", caution: "تنبيه", warning: "تحذير" },
+    },
+};
+/** The incident report (spec/fleet.md §2) in Markdown, in English or Arabic. */
+export function incidentReport(lines, bodies, prices, lang) {
+    const t = T[lang];
+    const s = sessionSummary(lines, bodies, prices);
+    const status = s.blocked_by
+        ? `${t.blocked} ${s.blocked_by}`
+        : s.closed
+            ? `${t.closed}${s.outcome ? ` (${s.outcome})` : ""}`
+            : t.open;
+    // Integer arithmetic, so both SDKs print the same digits.
+    const usd = `$${Math.floor(s.spend_micro_usd / 1_000_000)}.${String(s.spend_micro_usd % 1_000_000).padStart(6, "0")}`;
+    const all = lines
+        .map((l) => JSON.parse(l))
+        .filter((e) => e.kind === "finding")
+        .map((e) => {
+        const code = String(e.meta.code);
+        const f = FAULTS[code];
+        const what = f ? (lang === "ar" ? f.ar : f.en) : code;
+        return `| ${e.seq} | ${f?.fault ?? "—"} | ${t.level[String(e.meta.severity)] ?? String(e.meta.severity)} | ${what} (\`${code}\`) |`;
+    });
+    const tools = Object.entries(s.tools)
+        .map(([k, v]) => `${k} × ${v}`)
+        .join(", ");
+    const out = [
+        `# ${t.title}: ${s.label ?? s.session_id}`,
+        "",
+        "| | |",
+        "|---|---|",
+        `| ${t.session} | \`${s.session_id}\` |`,
+        `| ${t.started} | ${s.started_at} |`,
+        `| ${t.last} | ${s.last_event_at} |`,
+        `| ${t.status} | ${status} |`,
+        `| ${t.objective} | ${s.objective ?? t.none} |`,
+        `| ${t.spend} | ${usd} · ${formatAed(toAedFils(s.spend_micro_usd))} |`,
+        "",
+        `## ${t.happened}`,
+        "",
+        t.calls(s.model_calls, s.tool_calls),
+        ...(tools ? ["", `${t.top}: ${tools}`] : []),
+        "",
+        `## ${t.findings}`,
+        "",
+        ...(all.length === 0 ? [t.noFindings] : [t.head, "|---|---|---|---|", ...all]),
+    ];
+    const body = `${out.join("\n")}\n`;
+    return lang === "ar" ? `<div dir="rtl" lang="ar">\n\n${body}\n</div>\n` : body;
+}
+/** Per agent label (spec/fleet.md §2): outcomes, warnings, near misses, exceedances by code (FOQA),
+ * spend, cost per success. */
+export function logbook(summaries) {
+    const by = new Map();
+    for (const s of summaries) {
+        const k = s.label ?? "(no label)";
+        by.set(k, [...(by.get(k) ?? []), s]);
+    }
+    return {
+        labels: [...by.keys()].sort().map((label) => {
+            const ss = by.get(label);
+            const outcomes = { success: 0, failure: 0, abandoned: 0, unlabelled: 0 };
+            for (const s of ss)
+                outcomes[s.outcome in outcomes
+                    ? s.outcome
+                    : "unlabelled"]++;
+            const spend = ss.reduce((n, s) => n + s.spend_micro_usd, 0);
+            const labelled = ss
+                .filter((s) => s.outcome !== null)
+                .reduce((n, s) => n + s.spend_micro_usd, 0);
+            const wins = outcomes.success;
+            const exceedances = {};
+            for (const s of ss)
+                for (const [k, v] of Object.entries(s.finding_codes))
+                    exceedances[k] = (exceedances[k] ?? 0) + v;
+            return {
+                label,
+                sessions: ss.length,
+                outcomes,
+                findings_warning: ss.reduce((n, s) => n + s.findings.warning, 0),
+                near_misses: ss.reduce((n, s) => n + s.near_misses, 0),
+                exceedances: sorted(exceedances),
+                spend_micro_usd: spend,
+                cost_per_success_micro_usd: wins
+                    ? Math.floor((labelled + Math.floor(wins / 2)) / wins)
+                    : null,
+            };
+        }),
+    };
+}
+/** Tool names that change what they touch (spec/fleet.md §4): a lower-case substring match. */
+const CHANGES = [
+    "write",
+    "edit",
+    "delete",
+    "remove",
+    "create",
+    "update",
+    "deploy",
+    "move",
+    "rename",
+    "patch",
+    "apply",
+    "put",
+    "insert",
+    "drop",
+    "upload",
+    "commit",
+    "push",
+    "merge",
+];
+const RESOURCE_KEYS = ["path", "file_path", "notebook_path", "url", "resource"];
+/** An MCP tools/call body's `params.arguments`. */
+function mcpArgs(body) {
+    try {
+        const rpc = JSON.parse(new TextDecoder().decode(body ?? new Uint8Array()));
+        return rpc?.params?.arguments;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The resource a changing tool call touches, or undefined. */
+function resourceOf(tool, args) {
+    const name = tool.toLowerCase();
+    if (!CHANGES.some((w) => name.includes(w)))
+        return undefined;
+    if (typeof args !== "object" || args === null || Array.isArray(args))
+        return undefined;
+    for (const k of RESOURCE_KEYS) {
+        const v = args[k];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    return undefined;
+}
+/** Changes to the same resource from two or more sessions (A7), by resource; each session's first change. */
+export function collisions(records) {
+    const by = new Map();
+    const touch = (resource, session_id, tool, seq) => {
+        const m = by.get(resource) ?? new Map();
+        by.set(resource, m);
+        if (!m.has(session_id))
+            m.set(session_id, { session_id, tool, seq });
+    };
+    for (const r of records) {
+        if (r.lines.length === 0)
+            continue;
+        const sid = JSON.parse(r.lines[0]).session_id;
+        const touches = [];
+        for (const t of toolCallsOf(callsOf(r.lines, r.bodies))) {
+            const res = resourceOf(t.tool, t.args);
+            if (res !== undefined)
+                touches.push({ seq: t.seq, tool: t.tool, resource: res });
+        }
+        for (const line of r.lines) {
+            const e = JSON.parse(line);
+            if (e.kind !== "tool.call" ||
+                e.meta.method !== "tools/call" ||
+                typeof e.meta.tool !== "string")
+                continue;
+            const res = resourceOf(e.meta.tool, mcpArgs(r.bodies(e.body_hash)));
+            if (res !== undefined)
+                touches.push({ seq: e.seq, tool: e.meta.tool, resource: res });
+        }
+        for (const t of touches.sort((a, b) => a.seq - b.seq))
+            touch(t.resource, sid, t.tool, t.seq);
+    }
+    return [...by.keys()]
+        .sort()
+        .map((resource) => ({
+        resource,
+        sessions: [...(by.get(resource)?.values() ?? [])].sort((a, b) => a.session_id < b.session_id ? -1 : a.session_id > b.session_id ? 1 : 0),
+    }))
+        .filter((c) => c.sessions.length > 1);
+}
+export const DEFAULT_AIRWORTHINESS = {
+    window: 20,
+    min_sessions: 5,
+    min_success_ppm: 900_000,
+    max_warnings: 0,
+};
+/** Is this agent (label) fit to fly? (spec/fleet.md §5). `summaries` newest first. */
+export function airworthiness(label, summaries, criteria = DEFAULT_AIRWORTHINESS) {
+    const judged = summaries
+        .filter((s) => s.closed && (s.label ?? "(no label)") === label)
+        .slice(0, criteria.window);
+    const successes = judged.filter((s) => s.outcome === "success").length;
+    const warnings = judged.reduce((n, s) => n + s.findings.warning, 0);
+    const rate = judged.length ? Math.floor((successes * 1_000_000) / judged.length) : 0;
+    const reasons = [];
+    if (judged.length < criteria.min_sessions)
+        reasons.push(`${judged.length} closed sessions, fewer than ${criteria.min_sessions}`);
+    else {
+        if (rate < criteria.min_success_ppm)
+            reasons.push(`success rate ${rate} ppm, below ${criteria.min_success_ppm}`);
+        if (warnings > criteria.max_warnings)
+            reasons.push(`${warnings} warnings, more than ${criteria.max_warnings}`);
+    }
+    return {
+        v: 1,
+        label,
+        criteria,
+        sessions: judged.map((s) => s.session_id),
+        successes,
+        success_ppm: rate,
+        warnings,
+        near_misses: judged.reduce((n, s) => n + s.near_misses, 0),
+        verdict: judged.length < criteria.min_sessions
+            ? "insufficient_data"
+            : reasons.length
+                ? "not_airworthy"
+                : "airworthy",
+        reasons,
+    };
+}
+const NOT_FAILURES = new Set(["NEAR_MISS", "PRECOG_RISK"]);
+/** spec/signatures.md §1: the failure pattern and its id, or null. */
+export function signatureOf(summary) {
+    const pattern = Object.keys(summary.finding_codes)
+        .filter((c) => !NOT_FAILURES.has(c))
+        .sort();
+    if (pattern.length === 0)
+        return null;
+    const hex = createHash("sha256").update(pattern.join("+"), "utf8").digest("hex");
+    return { signature: `sig_${hex.slice(0, 16)}`, pattern };
+}
+/** spec/signatures.md §2: groups seen at k or more distinct tenants; counts only. */
+export function signatures(items, k = 3) {
+    const by = new Map();
+    for (const { tenant, summary } of items) {
+        const sig = signatureOf(summary);
+        if (!sig)
+            continue;
+        const g = by.get(sig.signature) ?? {
+            pattern: sig.pattern,
+            tenants: new Set(),
+            sessions: 0,
+            failures: 0,
+        };
+        g.tenants.add(tenant);
+        g.sessions++;
+        if (summary.outcome === "failure" || summary.outcome === "abandoned")
+            g.failures++;
+        by.set(sig.signature, g);
+    }
+    return [...by.entries()]
+        .filter(([, g]) => g.tenants.size >= k)
+        .map(([signature, g]) => ({
+        signature,
+        pattern: g.pattern,
+        tenants: g.tenants.size,
+        sessions: g.sessions,
+        failures: g.failures,
+        failure_ppm: Math.floor((g.failures * 1_000_000) / g.sessions),
+    }))
+        .sort((a, b) => b.tenants - a.tenants ||
+        b.sessions - a.sessions ||
+        (a.signature < b.signature ? -1 : a.signature > b.signature ? 1 : 0));
+}
+// ---------------------------------------------------------------- signed certificates (spec/fleet.md §5, L6.1.6)
+const PKCS8_ED25519 = Buffer.from("302e020100300506032b657004220420", "hex");
+const SPKI_ED25519 = Buffer.from("302a300506032b6570032100", "hex");
+const unsigned = (cert) => Buffer.from(canonical(Object.fromEntries(Object.entries(cert).filter(([k]) => k !== "signed"))));
+/** The did:key of an Ed25519 identity, from its 32-byte seed. */
+export function didFromSeed(seed) {
+    const key = createPrivateKey({
+        key: Buffer.concat([PKCS8_ED25519, Buffer.from(seed)]),
+        format: "der",
+        type: "pkcs8",
+    });
+    const x = createPublicKey(key).export({ format: "jwk" }).x;
+    return didFromPublicKey(new Uint8Array(Buffer.from(x, "base64url")));
+}
+/** Signs a certificate with an Ed25519 identity (the 32-byte seed): adds `signed: {by, sig}`. */
+export function signCertificate(cert, did, seed) {
+    const key = createPrivateKey({
+        key: Buffer.concat([PKCS8_ED25519, Buffer.from(seed)]),
+        format: "der",
+        type: "pkcs8",
+    });
+    const sig = signBytes(null, unsigned(cert), key).toString("hex");
+    return { ...cert, signed: { by: did, sig: `ed25519:${sig}` } };
+}
+/** Checks a signed certificate offline, from the signer's did:key alone. */
+export function verifyCertificate(cert, expectedDid) {
+    const s = cert.signed;
+    if (!s || typeof s.by !== "string" || typeof s.sig !== "string")
+        return { ok: false, by: null, reason: "unsigned" };
+    if (expectedDid && s.by !== expectedDid)
+        return { ok: false, by: s.by, reason: "wrong_signer" };
+    const pub = publicKeyFromDid(s.by);
+    const m = /^ed25519:([0-9a-f]{128})$/.exec(s.sig);
+    if (!pub || !m)
+        return { ok: false, by: s.by, reason: "malformed" };
+    const key = createPublicKey({
+        key: Buffer.concat([SPKI_ED25519, Buffer.from(pub)]),
+        format: "der",
+        type: "spki",
+    });
+    const ok = verifyBytes(null, unsigned(cert), key, Buffer.from(m[1], "hex"));
+    return ok ? { ok: true, by: s.by } : { ok: false, by: s.by, reason: "bad_signature" };
+}
+/** The record's findings grouped by code: how many, and when first and last, in first-seen order. */
+export function aggregateFindings(lines) {
+    const by = new Map();
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind !== "finding")
+            continue;
+        const code = String(e.meta.code);
+        const g = by.get(code);
+        if (g) {
+            g.count++;
+            g.last_seq = e.seq;
+            g.last_at = e.ts;
+        }
+        else
+            by.set(code, {
+                code,
+                fault: typeof e.meta.fault === "string" ? e.meta.fault : null,
+                severity: String(e.meta.severity),
+                count: 1,
+                first_seq: e.seq,
+                last_seq: e.seq,
+                first_at: e.ts,
+                last_at: e.ts,
+            });
+    }
+    return [...by.values()];
+}

package/dist/hooks/ai-sdk.d.ts

@@ -0,0 +1,42 @@
+import { type EventSink } from "./shared.ts";
+interface ModelInfo {
+    provider?: string;
+    modelId?: string;
+}
+type Part = {
+    type?: string;
+    id?: string;
+    modelId?: string;
+    toolCallId?: string;
+    toolName?: string;
+    input?: unknown;
+};
+/** For `wrapLanguageModel({ model, middleware })`: every generate and stream is observed; what the
+ *  model returns reaches the app unchanged. */
+export declare function blackboxMiddleware(sink: EventSink): {
+    wrapGenerate({ doGenerate, model, }: {
+        doGenerate: () => Promise<{
+            content?: Part[];
+            response?: {
+                id?: string;
+                modelId?: string;
+            };
+        }>;
+        model?: ModelInfo;
+    }): Promise<{
+        content?: Part[];
+        response?: {
+            id?: string;
+            modelId?: string;
+        };
+    }>;
+    wrapStream({ doStream, model, }: {
+        doStream: () => Promise<{
+            stream: ReadableStream<Part>;
+        }>;
+        model?: ModelInfo;
+    }): Promise<{
+        stream: ReadableStream<Part>;
+    }>;
+};
+export {};

package/dist/hooks/ai-sdk.js

@@ -0,0 +1,62 @@
+// Vercel AI SDK (audit K19, spec/sdk.md §5): a language-model middleware that reports each model
+// call's ids (for the dual witness) and the tool calls the model asks for. Duck-typed on the
+// middleware shape of AI SDK 5: no dependency on `ai`.
+//
+//   import { wrapLanguageModel } from "ai";
+//   const model = wrapLanguageModel({ model: anthropic("claude-sonnet-4-5"), middleware: blackboxMiddleware(session) });
+import { llmIds, neverThrow, providerOf } from "./shared.js";
+/** The model call's ids: the provider's response id, under the key the gateway records it by. */
+function reportCall(sink, model, id, modelId) {
+    const provider = providerOf(id) ?? model?.provider?.split(".")[0];
+    if (!provider || !id)
+        return;
+    sink.event("llm.call", provider, {
+        provider,
+        ...llmIds(id, undefined, modelId ?? model?.modelId),
+    });
+}
+function reportTool(sink, p) {
+    if (p.type !== "tool-call" || !p.toolName)
+        return;
+    let args = p.input;
+    try {
+        args = typeof args === "string" ? JSON.parse(args) : args;
+    }
+    catch { }
+    sink.event("tool.call", p.toolName, {
+        ...(p.toolCallId ? { call_id: p.toolCallId } : {}),
+        ...(args === undefined ? {} : { args }),
+    });
+}
+/** For `wrapLanguageModel({ model, middleware })`: every generate and stream is observed; what the
+ *  model returns reaches the app unchanged. */
+export function blackboxMiddleware(sink) {
+    return {
+        async wrapGenerate({ doGenerate, model, }) {
+            const result = await doGenerate();
+            neverThrow(() => {
+                reportCall(sink, model, result.response?.id, result.response?.modelId);
+                for (const p of result.content ?? [])
+                    reportTool(sink, p);
+            });
+            return result;
+        },
+        async wrapStream({ doStream, model, }) {
+            const { stream, ...rest } = await doStream();
+            let reported = false;
+            const observed = stream.pipeThrough(new TransformStream({
+                transform(chunk, controller) {
+                    neverThrow(() => {
+                        if (!reported && chunk.type === "response-metadata" && chunk.id) {
+                            reported = true;
+                            reportCall(sink, model, chunk.id, chunk.modelId);
+                        }
+                        reportTool(sink, chunk);
+                    });
+                    controller.enqueue(chunk);
+                },
+            }));
+            return { stream: observed, ...rest };
+        },
+    };
+}

package/dist/hooks/claude-agent-sdk.d.ts

@@ -0,0 +1,14 @@
+import { type EventSink } from "./shared.ts";
+type Callback = (input: unknown, toolUseId: string | undefined, options: unknown) => Promise<object>;
+export interface BlackboxAgentHooks {
+    /** Pass as `options.hooks`. */
+    hooks: Record<"PreToolUse" | "PostToolUse" | "PostToolUseFailure", Array<{
+        hooks: Callback[];
+    }>>;
+    /** Call with every message `query()` yields; reports each model call's id once. */
+    observe(message: unknown): void;
+}
+export declare function blackboxAgentHooks(session: EventSink): BlackboxAgentHooks;
+/** Audit S6: the Python SDK's name, so docs and examples can be written once. Called, not `new`ed. */
+export declare const BlackboxAgentHooks: typeof blackboxAgentHooks;
+export {};

package/dist/hooks/claude-agent-sdk.js

@@ -0,0 +1,70 @@
+// Claude Agent SDK hooks (spec/sdk.md §5). Mirrors hooks/claude_agent_sdk.py.
+//
+//   const bbx = blackboxAgentHooks(session);
+//   for await (const message of query({ prompt, options: { hooks: bbx.hooks, env } })) {
+//     bbx.observe(message);
+//     …
+//   }
+//
+// Tool calls come from the SDK's PreToolUse / PostToolUse / PostToolUseFailure hooks; model calls
+// from the assistant messages `query()` yields (the Agent SDK has no model-call hook). Structural
+// types only, so the Agent SDK stays an optional dependency.
+import { neverThrow } from "./shared.js";
+const MAX_ERROR = 500;
+export function blackboxAgentHooks(session) {
+    const seen = new Set();
+    const hook = (fn) => async (input) => {
+        neverThrow(() => fn((input ?? {})));
+        return {}; // no decision: the hook only records
+    };
+    const common = (i) => ({
+        ...(i.tool_use_id ? { tool_use_id: i.tool_use_id } : {}),
+        ...(i.agent_id ? { agent_id: i.agent_id } : {}),
+    });
+    const name = (i) => String(i.tool_name ?? "tool").slice(0, 256);
+    return {
+        hooks: {
+            PreToolUse: [
+                {
+                    hooks: [
+                        hook((i) => session.event("tool.call", name(i), {
+                            ...common(i),
+                            ...(i.tool_input === undefined ? {} : { args: i.tool_input }),
+                        })),
+                    ],
+                },
+            ],
+            PostToolUse: [
+                { hooks: [hook((i) => session.event("tool.result", name(i), { ok: true, ...common(i) }))] },
+            ],
+            PostToolUseFailure: [
+                {
+                    hooks: [
+                        hook((i) => session.event("tool.result", name(i), {
+                            ok: false,
+                            ...common(i),
+                            error: String(i.error ?? "").slice(0, MAX_ERROR),
+                        })),
+                    ],
+                },
+            ],
+        },
+        observe(message) {
+            neverThrow(() => {
+                const m = message;
+                const id = m?.type === "assistant" ? m.message?.id : undefined;
+                // One API response can arrive as several assistant messages (one per content block).
+                if (typeof id !== "string" || seen.has(id))
+                    return;
+                seen.add(id);
+                session.event("llm.call", "anthropic", {
+                    provider: "anthropic",
+                    message_id: id,
+                    ...(typeof m.message?.model === "string" ? { model: m.message.model } : {}),
+                });
+            });
+        },
+    };
+}
+/** Audit S6: the Python SDK's name, so docs and examples can be written once. Called, not `new`ed. */
+export const BlackboxAgentHooks = blackboxAgentHooks;

package/dist/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { blackboxMiddleware } from "./ai-sdk.ts";
+export { BlackboxAgentHooks, blackboxAgentHooks } from "./claude-agent-sdk.ts";
+export { BlackboxCallbackHandler, type BlackboxCallbacks, blackboxCallbacks } from "./langchain.ts";
+export { type MemorySink, type TrackMemoryOptions, trackMemory } from "./memory.ts";
+export { attachBlackbox } from "./openai-agents.ts";
+export { llmIdsOf, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI } from "./providers.ts";
+export { type EventSink, llmIds } from "./shared.ts";

package/dist/hooks/index.js

@@ -0,0 +1,10 @@
+// Framework hooks (spec/sdk.md §5): framework callbacks → SDK session events. Agent-asserted structure
+// only; every callback is wrapped so a hook can never break the framework. Mirrors
+// sdks/python/src/zanii_blackbox/hooks/.
+export { blackboxMiddleware } from "./ai-sdk.js";
+export { BlackboxAgentHooks, blackboxAgentHooks } from "./claude-agent-sdk.js";
+export { BlackboxCallbackHandler, blackboxCallbacks } from "./langchain.js";
+export { trackMemory } from "./memory.js";
+export { attachBlackbox } from "./openai-agents.js";
+export { llmIdsOf, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI } from "./providers.js";
+export { llmIds } from "./shared.js";