@zanii/blackbox 0.0.0-stage → 0.1.0

package/dist/hooks/langgraph-checkpoint.js

@@ -0,0 +1,73 @@
+// A LangGraph.js checkpointer that records what it saves (spec/sdk.md §5.3, ideas R1, R2).
+// Mirrors hooks/langgraph_checkpoint.py.
+//
+//   const app = graph.compile({ checkpointer: blackboxCheckpointer(new MemorySaver(), session) });
+//
+// Every `put` is a `checkpoint.put` event and every `putWrites` a `checkpoint.writes` event: ids,
+// the step, the source and channel names, never the values. The wrapper is the inner saver with
+// two methods replaced (its prototype is the inner one, so `instanceof BaseCheckpointSaver` still
+// holds): the SDK needs no LangGraph dependency.
+import { stableEventId } from "../session/index.js";
+import { neverThrow } from "./shared.js";
+export function blackboxCheckpointer(inner, session) {
+    const emit = (type, name, data, key) => neverThrow(() => session.event(type, name, data, {
+        eventId: stableEventId("checkpoint", type, ...key),
+    }));
+    const where = (config) => {
+        const c = config?.configurable ?? {};
+        return Object.fromEntries(["thread_id", "checkpoint_ns", "checkpoint_id"]
+            .filter((k) => c[k] !== undefined && c[k] !== null)
+            .map((k) => [k, String(c[k])]));
+    };
+    // Every method runs on the inner saver itself, so its own state stays its own.
+    const wrapped = Object.create(inner);
+    let p = inner;
+    while (p && p !== Object.prototype) {
+        for (const name of Object.getOwnPropertyNames(p)) {
+            const v = inner[name];
+            if (name !== "constructor" &&
+                typeof v === "function" &&
+                !(name in wrapped && Object.hasOwn(wrapped, name)))
+                Object.defineProperty(wrapped, name, {
+                    value: v.bind(inner),
+                    writable: true,
+                    configurable: true,
+                });
+        }
+        p = Object.getPrototypeOf(p);
+    }
+    wrapped.put = async (config, checkpoint, metadata, versions) => {
+        const out = await inner.put(config, checkpoint, metadata, versions);
+        const w = where(config);
+        const m = (metadata ?? {});
+        const data = {
+            thread_id: w.thread_id ?? "",
+            checkpoint_ns: w.checkpoint_ns ?? "",
+            checkpoint_id: String(checkpoint?.id ?? ""),
+            ...(w.checkpoint_id ? { parent_checkpoint_id: w.checkpoint_id } : {}),
+            ...(Number.isSafeInteger(m.step) ? { step: m.step } : {}),
+            ...(m.source ? { source: String(m.source) } : {}),
+            channels: Object.keys(versions ?? {}).sort(),
+        };
+        emit("checkpoint.put", data.source, data, [
+            data.thread_id,
+            data.checkpoint_ns,
+            data.checkpoint_id,
+        ]);
+        return out;
+    };
+    wrapped.putWrites = async (config, writes, taskId) => {
+        await inner.putWrites(config, writes, taskId);
+        const w = where(config);
+        const channels = writes.map(([c]) => String(c));
+        emit("checkpoint.writes", undefined, {
+            ...w,
+            task_id: taskId,
+            channels,
+            error: channels.includes("__error__"),
+            interrupt: channels.includes("__interrupt__"),
+            resume: channels.includes("__resume__"),
+        }, [w.thread_id ?? "", w.checkpoint_id ?? "", taskId, ...channels]);
+    };
+    return wrapped;
+}

package/dist/hooks/memory.d.ts

@@ -0,0 +1,17 @@
+export interface MemorySink {
+    memoryWrite(memoryId: string, summary?: string): void;
+    memoryRead(memoryIds: string[], query?: string): void;
+    memoryRevoke(memoryId: string, reason?: string): void;
+}
+export interface MemoryMethod {
+    /** The store's method name. */
+    method: string;
+    /** The memory ids a call touched, from its result and arguments. */
+    ids?: (result: unknown, args: unknown[]) => string[];
+}
+export interface TrackMemoryOptions {
+    write?: MemoryMethod;
+    read?: MemoryMethod;
+    revoke?: MemoryMethod;
+}
+export declare function trackMemory<T extends object>(store: T, sink: MemorySink, options?: TrackMemoryOptions): T;

package/dist/hooks/memory.js

@@ -0,0 +1,64 @@
+// Audit S10: a memory store, wrapped so its writes, reads and deletes are recorded for the Memory
+// X-ray (spec/agents.md §1) without wiring memoryWrite / memoryRead / memoryRevoke by hand.
+// Duck-typed; the defaults fit mem0-shaped stores (add / search / delete, `{results: [{id, memory}]}`).
+// Mirrors sdks/python/src/zanii_blackbox/hooks/memory.py.
+//
+//   const memory = trackMemory(new Memory(), session);
+//   await memory.add(messages, { userId });   // → memory.write, one per memory id
+import { neverThrow } from "./shared.js";
+/** Items with an `id`: an array, `{results: [...]}`, or one item. */
+function itemsOf(result) {
+    if (Array.isArray(result))
+        return result;
+    const r = result;
+    if (r && Array.isArray(r.results))
+        return r.results;
+    if (r && typeof r === "object" && typeof r.id === "string")
+        return [r];
+    return [];
+}
+const idsOf = (result) => itemsOf(result)
+    .map((i) => i.id)
+    .filter((id) => typeof id === "string");
+const DEFAULTS = {
+    write: { method: "add", ids: idsOf },
+    read: { method: "search", ids: idsOf },
+    // delete(memoryId): the id is the argument
+    revoke: { method: "delete", ids: (_r, args) => (typeof args[0] === "string" ? [args[0]] : []) },
+};
+export function trackMemory(store, sink, options = {}) {
+    const kinds = {
+        write: { ...DEFAULTS.write, ...options.write },
+        read: { ...DEFAULTS.read, ...options.read },
+        revoke: { ...DEFAULTS.revoke, ...options.revoke },
+    };
+    const record = (kind, result, args) => neverThrow(() => {
+        const ids = (kinds[kind].ids ?? idsOf)(result, args);
+        if (kind === "read") {
+            sink.memoryRead(ids, typeof args[0] === "string" ? args[0] : undefined);
+            return;
+        }
+        const summaries = new Map(itemsOf(result).map((i) => [i.id, typeof i.memory === "string" ? i.memory : undefined]));
+        for (const id of ids)
+            if (kind === "write")
+                sink.memoryWrite(id, summaries.get(id)?.slice(0, 200));
+            else
+                sink.memoryRevoke(id);
+    });
+    return new Proxy(store, {
+        get(obj, prop, receiver) {
+            const value = Reflect.get(obj, prop, receiver);
+            const kind = Object.keys(kinds).find((k) => kinds[k].method === prop);
+            if (!kind || typeof value !== "function")
+                return value;
+            return (...args) => {
+                const result = value.apply(obj, args);
+                if (typeof result?.then === "function")
+                    result.then((r) => record(kind, r, args), () => { });
+                else
+                    record(kind, result, args);
+                return result;
+            };
+        },
+    });
+}

package/dist/hooks/openai-agents.d.ts

@@ -0,0 +1,6 @@
+import { type EventSink } from "./shared.ts";
+interface HookEmitter {
+    on(event: any, listener: any): unknown;
+}
+export declare function attachBlackbox(runner: HookEmitter, session: EventSink): void;
+export {};

package/dist/hooks/openai-agents.js

@@ -0,0 +1,40 @@
+// OpenAI Agents SDK (JS) run hooks (spec/sdk.md §5). Mirrors hooks/openai_agents.py.
+//
+//   const runner = new Runner();  attachBlackbox(runner, session);  await runner.run(agent, "…");
+//
+// The JS SDK's hooks are events on the Runner (agent / handoff / tool); it has no model-call event,
+// so model-call ids come from the gateway alone here.
+import { neverThrow } from "./shared.js";
+const nameOf = (x) => String(x?.name ?? "agent").slice(0, 256);
+/** Audit K23: the SDK turns a tool's exception into this answer (its default error function), so a
+ *  tool that failed isn't recorded as a success. */
+const TOOL_ERROR = "An error occurred while running the tool.";
+const failed = (result) => typeof result === "string" && result.startsWith(TOOL_ERROR);
+export function attachBlackbox(runner, session) {
+    const on = (event, listener) => runner.on(event, ((...args) => neverThrow(() => listener(...args))));
+    on("agent_start", (_context, agent) => session.event("step", nameOf(agent), {}));
+    on("agent_handoff", (_context, from, to) => session.event("step", nameOf(to), { handoff_from: nameOf(from) }));
+    on("agent_tool_start", (_context, agent, tool, details) => {
+        const call = details
+            ?.toolCall;
+        let args = call?.arguments;
+        try {
+            args = typeof args === "string" ? JSON.parse(args) : args;
+        }
+        catch { }
+        session.event("tool.call", nameOf(tool), {
+            agent: nameOf(agent),
+            ...(call?.callId ? { call_id: call.callId } : {}),
+            ...(args === undefined ? {} : { args }),
+        });
+    });
+    on("agent_tool_end", (_context, agent, tool, result, details) => {
+        const callId = details?.toolCall?.callId;
+        session.event("tool.result", nameOf(tool), {
+            ok: !failed(result),
+            agent: nameOf(agent),
+            ...(callId ? { call_id: callId } : {}),
+            ...(failed(result) ? { error: String(result).slice(0, 500) } : {}),
+        });
+    });
+}

package/dist/hooks/protect.d.ts

@@ -0,0 +1,7 @@
+export declare const MANAGED_START = "<!-- blackbox:managed:start -->";
+export declare const MANAGED_END = "<!-- blackbox:managed:end -->";
+/** The managed block (markers included), or null when the text has none. */
+export declare function managedBlock(text: string): string | null;
+/** Why this file tool call must not run, or null. `current` is the file's text now (null when
+ * it doesn't exist). Tools: write_file {content}, edit_file {old_string, new_string}, delete. */
+export declare function protectedEdit(current: string | null, tool: string, args: Record<string, unknown>): string | null;

package/dist/hooks/protect.js

@@ -0,0 +1,39 @@
+// Protected regions (spec/sdk.md §5.2, idea S5): a machine-managed block in a file the agent may
+// edit (an AGENTS.md, a memory file), between `<!-- blackbox:managed:start -->` and
+// `<!-- blackbox:managed:end -->`. A write, edit or delete that would change or remove it is
+// refused before the tool runs. Mirrors protect.py.
+export const MANAGED_START = "<!-- blackbox:managed:start -->";
+export const MANAGED_END = "<!-- blackbox:managed:end -->";
+/** The managed block (markers included), or null when the text has none. */
+export function managedBlock(text) {
+    const i = text.indexOf(MANAGED_START);
+    const j = i < 0 ? -1 : text.indexOf(MANAGED_END, i);
+    return i < 0 || j < 0 ? null : text.slice(i, j + MANAGED_END.length);
+}
+const str = (v) => (typeof v === "string" ? v : undefined);
+/** Why this file tool call must not run, or null. `current` is the file's text now (null when
+ * it doesn't exist). Tools: write_file {content}, edit_file {old_string, new_string}, delete. */
+export function protectedEdit(current, tool, args) {
+    const block = current === null ? null : managedBlock(current);
+    if (block === null)
+        return null;
+    const path = str(args.file_path) ?? str(args.path) ?? "the file";
+    const refuse = `blackbox: ${path} has a machine-managed block (between the blackbox:managed markers) that can't be changed or removed. The edit wasn't applied.`;
+    if (tool === "delete" || tool === "delete_file" || tool === "rm")
+        return `${refuse}`;
+    if (tool === "write_file") {
+        const content = str(args.content) ?? "";
+        return managedBlock(content) === block ? null : refuse;
+    }
+    if (tool === "edit_file") {
+        const oldText = str(args.old_string);
+        const newText = str(args.new_string) ?? "";
+        if (oldText === undefined || !current.includes(oldText))
+            return null; // the tool fails itself
+        const after = args.replace_all === true
+            ? current.split(oldText).join(newText)
+            : current.replace(oldText, () => newText);
+        return managedBlock(after) === block ? null : refuse;
+    }
+    return null;
+}

package/dist/hooks/providers.d.ts

@@ -0,0 +1,16 @@
+import { type EventSink } from "./shared.ts";
+/** The ids a provider's response (or its first stream event) carries, as `llmCall` takes them:
+ * Anthropic, OpenAI and OpenAI-compatible APIs (by `object`), Gemini and Vertex (`responseId`), and
+ * Bedrock (the AWS SDK's `$metadata.requestId`) (audit K4). */
+export declare function llmIdsOf(response: unknown): Record<string, string>;
+/** `client.messages.create` and `.stream` report each model call to the session. */
+export declare function wrapAnthropic<T extends object>(client: T, sink: EventSink): T;
+/** `client.chat.completions.create` / `.stream` and `client.responses.create` / `.stream` report
+ * each model call. */
+export declare function wrapOpenAI<T extends object>(client: T, sink: EventSink): T;
+/** Audit K4: Google's `@google/genai` client (Gemini, and Vertex AI with `vertexai: true`):
+ * `models.generateContent` and `models.generateContentStream` report each model call. */
+export declare function wrapGemini<T extends object>(client: T, sink: EventSink): T;
+/** Audit K4: the AWS SDK's `BedrockRuntimeClient`: every `send(command)` (Converse, ConverseStream,
+ * InvokeModel, …) reports its request id, which the gateway records from `x-amzn-requestid`. */
+export declare function wrapBedrock<T extends object>(client: T, sink: EventSink): T;

package/dist/hooks/providers.js

@@ -0,0 +1,149 @@
+// Audit S9 / S18: report model calls made with the official Anthropic and OpenAI clients, so the
+// dual witness (spec/findings.md §2) works without the app calling llmCall by hand. Duck-typed: no
+// dependency on either client. Mirrors sdks/python/src/zanii_blackbox/hooks/providers.py.
+//
+//   const anthropic = wrapAnthropic(new Anthropic({ baseURL: gateway }), session);
+//   const openai = wrapOpenAI(new OpenAI({ baseURL: gateway }), session);
+import { llmIds, neverThrow, providerOf } from "./shared.js";
+/** The ids a provider's response (or its first stream event) carries, as `llmCall` takes them:
+ * Anthropic, OpenAI and OpenAI-compatible APIs (by `object`), Gemini and Vertex (`responseId`), and
+ * Bedrock (the AWS SDK's `$metadata.requestId`) (audit K4). */
+export function llmIdsOf(response) {
+    const r = (response ?? {});
+    const google = r.responseId;
+    if (typeof google === "string" && ("candidates" in r || "usageMetadata" in r))
+        return {
+            provider: "gemini",
+            response_id: google,
+            ...(typeof r.modelVersion === "string" ? { model: r.modelVersion } : {}),
+        };
+    const aws = r.$metadata?.requestId;
+    if (typeof aws === "string")
+        return { provider: "bedrock", request_id: aws };
+    // A stream event: Anthropic's message_start carries `message`, OpenAI's response.* `response`.
+    const inner = (typeof r.message === "object" && r.message) ||
+        (typeof r.response === "object" && r.response) ||
+        r;
+    const o = inner;
+    const id = typeof o.id === "string" ? o.id : undefined;
+    const provider = providerOf(id, typeof o.object === "string" ? o.object : undefined);
+    if (!provider)
+        return {};
+    const requestId = typeof r._request_id === "string"
+        ? r._request_id
+        : typeof o._request_id === "string"
+            ? o._request_id
+            : undefined;
+    return {
+        provider,
+        ...llmIds(id, requestId, typeof o.model === "string" ? o.model : undefined, typeof o.object === "string" ? o.object : undefined),
+    };
+}
+/** `client.messages.create` and `.stream` report each model call to the session. */
+export function wrapAnthropic(client, sink) {
+    return wrap(client, [
+        ["messages", "create"],
+        ["messages", "stream"],
+        ["messages", "parse"],
+        // audit K18: the beta namespace (structured output, tools in preview) goes to the same API
+        ["beta", "messages", "create"],
+        ["beta", "messages", "stream"],
+        ["beta", "messages", "parse"],
+    ], sink);
+}
+/** `client.chat.completions.create` / `.stream` and `client.responses.create` / `.stream` report
+ * each model call. */
+export function wrapOpenAI(client, sink) {
+    return wrap(client, [
+        ["chat", "completions", "create"],
+        ["chat", "completions", "stream"],
+        ["responses", "create"],
+        ["responses", "stream"],
+        // audit K18: structured output and the beta namespace
+        ["chat", "completions", "parse"],
+        ["responses", "parse"],
+        ["beta", "chat", "completions", "parse"],
+        ["beta", "chat", "completions", "stream"],
+    ], sink);
+}
+/** Audit K4: Google's `@google/genai` client (Gemini, and Vertex AI with `vertexai: true`):
+ * `models.generateContent` and `models.generateContentStream` report each model call. */
+export function wrapGemini(client, sink) {
+    return wrap(client, [
+        ["models", "generateContent"],
+        ["models", "generateContentStream"],
+    ], sink);
+}
+/** Audit K4: the AWS SDK's `BedrockRuntimeClient`: every `send(command)` (Converse, ConverseStream,
+ * InvokeModel, …) reports its request id, which the gateway records from `x-amzn-requestid`. */
+export function wrapBedrock(client, sink) {
+    return wrap(client, [["send"]], sink);
+}
+/** The streaming helpers' promise of the final message, which carries the ids. */
+const FINAL = ["finalMessage", "finalChatCompletion", "finalResponse"];
+function wrap(target, paths, sink) {
+    return new Proxy(target, {
+        get(obj, prop, receiver) {
+            const value = Reflect.get(obj, prop, receiver);
+            const here = paths.filter((p) => p[0] === prop);
+            if (here.length === 0 || value === null || value === undefined)
+                return value;
+            if (here.some((p) => p.length === 1) && typeof value === "function")
+                return (...args) => {
+                    const result = value.apply(obj, args);
+                    neverThrow(() => observe(result, sink));
+                    return result; // the client's own promise, untouched (e.g. APIPromise.withResponse())
+                };
+            return typeof value === "object"
+                ? wrap(value, here.map((p) => p.slice(1)), sink)
+                : value;
+        },
+    });
+}
+function observe(result, sink) {
+    const then = result?.then;
+    if (typeof then !== "function") {
+        seen(result, sink);
+        return;
+    }
+    // Registered before the caller's own await, so a stream is patched before it's iterated.
+    result.then((r) => neverThrow(() => seen(r, sink)), () => { });
+}
+function seen(result, sink) {
+    if (result === null || typeof result !== "object")
+        return;
+    // A streaming helper (e.g. messages.stream()): whatever way the app reads it, its final message
+    // resolves once the stream ends.
+    for (const name of FINAL) {
+        const final = result[name];
+        if (typeof final === "function") {
+            final.call(result).then((m) => neverThrow(() => report(llmIdsOf(m), sink)), () => { });
+            return;
+        }
+    }
+    const iter = result[Symbol.asyncIterator];
+    if (typeof iter !== "function") {
+        report(llmIdsOf(result), sink);
+        return;
+    }
+    // A stream: the ids come with its first event that has one; the stream itself is unchanged.
+    const original = iter.bind(result);
+    let reported = false;
+    result[Symbol.asyncIterator] = async function* () {
+        for await (const event of { [Symbol.asyncIterator]: original }) {
+            if (!reported)
+                neverThrow(() => {
+                    const ids = llmIdsOf(event);
+                    if (ids.provider) {
+                        reported = true;
+                        report(ids, sink);
+                    }
+                });
+            yield event;
+        }
+    };
+}
+function report(ids, sink) {
+    if (ids.provider)
+        sink.event("llm.call", ids.provider, { ...ids });
+}

package/dist/hooks/shared.d.ts

@@ -0,0 +1,11 @@
+/** A BlackboxSession, or anything with the same `event` method. */
+export interface EventSink {
+    event(type: string, name?: string, data?: Record<string, unknown>): void;
+}
+/** Runs a hook body; a hook must never break the framework it's attached to (spec/sdk.md §4). */
+export declare function neverThrow(fn: () => void): void;
+/** A provider's response id → the key the gateway records it under (spec/findings.md §2). */
+export declare function llmIds(id: string | undefined, requestId?: string, model?: string, 
+/** An OpenAI-style `object` field: how an OpenAI-compatible API's own ids are told apart (K4). */
+object?: string): Record<string, string>;
+export declare function providerOf(id: string | undefined, object?: string): string | undefined;

package/dist/hooks/shared.js

@@ -0,0 +1,39 @@
+// What both hook adapters share. Mirrors sdks/python/src/zanii_blackbox/hooks/shared.py.
+/** Runs a hook body; a hook must never break the framework it's attached to (spec/sdk.md §4). */
+export function neverThrow(fn) {
+    try {
+        fn();
+    }
+    catch { }
+}
+/** A provider's response id → the key the gateway records it under (spec/findings.md §2). */
+export function llmIds(id, requestId, model, 
+/** An OpenAI-style `object` field: how an OpenAI-compatible API's own ids are told apart (K4). */
+object) {
+    const ids = {};
+    if (id) {
+        if (id.startsWith("resp_") || object === "response")
+            ids.response_id = id;
+        else if (id.startsWith("chatcmpl") || object?.startsWith("chat.completion"))
+            ids.completion_id = id;
+        else
+            ids.message_id = id;
+    }
+    if (requestId)
+        ids.request_id = requestId;
+    if (model)
+        ids.model = model;
+    return ids;
+}
+export function providerOf(id, object) {
+    if (!id)
+        return undefined;
+    if (id.startsWith("msg_"))
+        return "anthropic";
+    if (id.startsWith("resp_") || id.startsWith("chatcmpl"))
+        return "openai";
+    // audit K4: an OpenAI-compatible API (vLLM, Azure, Jais, …) with ids of its own
+    if (object === "response" || object?.startsWith("chat.completion"))
+        return "openai";
+    return undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+export { causality, memoryXray } from "./agents/index.ts";
+export { type DetectorOptions, detectors, fingerprint } from "./analysis/detectors.ts";
+export { FAULTS, type Fault, faultOf } from "./analysis/faults.ts";
+export { type AnalyzeOptions, analyze, type ClaimVerdict, type CriterionResult, checkFlightPlan, checkpointReplay, dualWitness, eventsOf, type Finding as AnalysisFinding, findingKey, type Landing, landing, OUTCOMES, type Outcome, type OutcomeRollup, rollup, type Severity, type WasteReason, type WasteReport, waste, } from "./analysis/index.ts";
+export { type ApprovalFinding, approvalFindings } from "./approvals/index.ts";
+export { textWarnings } from "./approvals/warnings.ts";
+export { type Attestation, attest, isReadOnly, normalise, parseCommand } from "./attest/index.ts";
+export { type AuthorityFinding, authorityAt, authorityTimeline, automationSurprise, type Mode as AuthorityMode, type Span as AuthoritySpan, } from "./authority/index.ts";
+export { type Invoice, type InvoiceLine, invoice, loadPlans, type Plan, type Plans, renderTaxInvoice, stripeSignatureOk, type TaxInvoice, type TaxInvoiceInput, taxInvoice, } from "./billing/index.ts";
+export { BlackboxApiError, type Client, type ClientOptions, client, type SessionQuery, } from "./client/index.ts";
+export { complianceFacts, complianceReport, type Facts, type Framework, type Report as ComplianceReport, renderReport, } from "./compliance/index.ts";
+export { type CallCost, type CostReport, callMicroUsd, effectivePrice, formatAed, type LoadedPrices, loadPrices, type ModelPrice, type PriceTable, priceCall, priceFor, promptTokens, requestsOf, sessionCost, type Tokens, toAedFils, tokensOf, } from "./cost/index.ts";
+export { type Directive, type DirectiveItem, type DirectiveOptions, directives, fleetDirectives, } from "./directives/index.ts";
+export { checkDrill, drillReport, type Fault as DrillFault } from "./drills/index.ts";
+export { checkDuty, type DutyFinding, type DutyLimits, dutyFindings } from "./duty/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 { attachBlackbox, BlackboxAgentHooks, BlackboxCallbackHandler, type BlackboxCallbacks, blackboxAgentHooks, blackboxCallbacks, blackboxMiddleware, type EventSink, llmIds, llmIdsOf, trackMemory, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI, } from "./hooks/index.ts";
+export { type AgentSink, BlackboxStoppedError, blackboxAgentMiddleware, blackboxHitl, type HitlRequest, } from "./hooks/langchain-agent.ts";
+export { blackboxCheckpointer } from "./hooks/langgraph-checkpoint.ts";
+export { MANAGED_END, MANAGED_START, managedBlock, protectedEdit } from "./hooks/protect.ts";
+export { type Investigation, investigation, renderInvestigation, } from "./investigate/index.ts";
+export { type McpWrapOptions, mcpWrap } from "./mcp-wrap/index.ts";
+export { type AmountUnit, anthropicStatement, type Baseline, baselines, type Connector, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, type Statement, } from "./money/index.ts";
+export { filingPack, type OccurrenceFacts, type OccurrenceFramework, type OccurrenceReport, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.ts";
+export { ingestOcsf, type OcsfEvent, type OcsfVersion, ocsfLine, toOcsf } from "./ocsf/index.ts";
+export { toOtlp } from "./otlp/index.ts";
+export { checkPack, corePack, type PackEntry, packFrameworks } from "./packs/index.ts";
+export { type PolicyChange, type PolicyDelta, policyDelta } from "./policy/delta.ts";
+export { type Draft, type DraftGroup, policyDrafts } from "./policy/drafts.ts";
+export { audited, type CompiledPolicy, compilePolicy, type Decision, decide, loadPolicy, type Policy, policyFindings, type Rule, } from "./policy/index.ts";
+export { calibration, FEATURES, features, MIN_EACH, type PrecogModel, precogFindings, precogReport, predict, prefixOf, splitOf, TARGET, train, } from "./precog/index.ts";
+export { type InterventionEvidence, interventionEvidence, interventionGain, } from "./precog/intervention.ts";
+export { activities, buildNormal, type NormalModel, type NormalScore, normalScore, normalThreshold, } from "./precog/normal.ts";
+export { type PreflightFinding, preflightFindings } from "./preflight/index.ts";
+export { type Rating, type TypeUnratedFinding, typeRatings, typeUnrated, } from "./ratings/index.ts";
+export { type Finding, type FindingCode, type Harness, loadLocal, type ReconcileOptions, RecordNotVerified, type Report, reconcile, } from "./reconcile/index.ts";
+export { cassette, requestKey, type Take } from "./replay/index.ts";
+export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.ts";
+export { type DrainResult, drainSpools } from "./session/drain.ts";
+export { BlackboxSession, type FlightPlan, type LlmCallIds, type SessionError, type SessionOptions, type SessionState, type SessionStats, session, stableEventId, } from "./session/index.ts";
+export { type Compensation, checkCompensations, runUndo, type UndoFinding, type UndoStatus, type UndoStep, undoFindings, undoPlan, } from "./undo/index.ts";
+export * from "./verify/index.ts";
+export { VERSION } from "./version.ts";
+export { type Conditions, type Sample, weather } from "./weather/index.ts";
+export { postReceipt, receiptFor, type Tree, workspaceTree } from "./workspace-receipt/index.ts";

package/dist/index.js

@@ -0,0 +1,47 @@
+// Public API of @zanii/blackbox. Everything customers can import is re-exported here.
+// Keep this file in step with sdks/python/src/zanii_blackbox/__init__.py (the SDKs mirror each other).
+export { causality, memoryXray } from "./agents/index.js";
+export { detectors, fingerprint } from "./analysis/detectors.js";
+export { FAULTS, faultOf } from "./analysis/faults.js";
+export { analyze, checkFlightPlan, checkpointReplay, dualWitness, eventsOf, findingKey, landing, OUTCOMES, rollup, waste, } from "./analysis/index.js";
+export { approvalFindings } from "./approvals/index.js";
+export { textWarnings } from "./approvals/warnings.js";
+export { attest, isReadOnly, normalise, parseCommand } from "./attest/index.js";
+export { authorityAt, authorityTimeline, automationSurprise, } from "./authority/index.js";
+export { invoice, loadPlans, renderTaxInvoice, stripeSignatureOk, taxInvoice, } from "./billing/index.js";
+export { BlackboxApiError, client, } from "./client/index.js";
+export { complianceFacts, complianceReport, renderReport, } from "./compliance/index.js";
+export { callMicroUsd, effectivePrice, formatAed, loadPrices, priceCall, priceFor, promptTokens, requestsOf, sessionCost, toAedFils, tokensOf, } from "./cost/index.js";
+export { directives, fleetDirectives, } from "./directives/index.js";
+export { checkDrill, drillReport } from "./drills/index.js";
+export { checkDuty, dutyFindings } from "./duty/index.js";
+export { aggregateFindings, airworthiness, collisions, didFromSeed, incidentReport, logbook, sessionSummary, signatureOf, signatures, signCertificate, verifyCertificate, } from "./fleet/index.js";
+export { attachBlackbox, BlackboxAgentHooks, BlackboxCallbackHandler, blackboxAgentHooks, blackboxCallbacks, blackboxMiddleware, llmIds, llmIdsOf, trackMemory, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI, } from "./hooks/index.js";
+export { BlackboxStoppedError, blackboxAgentMiddleware, blackboxHitl, } from "./hooks/langchain-agent.js";
+export { blackboxCheckpointer } from "./hooks/langgraph-checkpoint.js";
+export { MANAGED_END, MANAGED_START, managedBlock, protectedEdit } from "./hooks/protect.js";
+export { investigation, renderInvestigation, } from "./investigate/index.js";
+export { mcpWrap } from "./mcp-wrap/index.js";
+export { anthropicStatement, baselines, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, } from "./money/index.js";
+export { filingPack, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.js";
+export { ingestOcsf, ocsfLine, toOcsf } from "./ocsf/index.js";
+export { toOtlp } from "./otlp/index.js";
+export { checkPack, corePack, packFrameworks } from "./packs/index.js";
+export { policyDelta } from "./policy/delta.js";
+export { policyDrafts } from "./policy/drafts.js";
+export { audited, compilePolicy, decide, loadPolicy, policyFindings, } from "./policy/index.js";
+export { calibration, FEATURES, features, MIN_EACH, precogFindings, precogReport, predict, prefixOf, splitOf, TARGET, train, } from "./precog/index.js";
+export { interventionEvidence, interventionGain, } from "./precog/intervention.js";
+export { activities, buildNormal, normalScore, normalThreshold, } from "./precog/normal.js";
+export { preflightFindings } from "./preflight/index.js";
+export { typeRatings, typeUnrated, } from "./ratings/index.js";
+export { loadLocal, RecordNotVerified, reconcile, } from "./reconcile/index.js";
+export { cassette, requestKey } from "./replay/index.js";
+export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.js";
+export { drainSpools } from "./session/drain.js";
+export { BlackboxSession, session, stableEventId, } from "./session/index.js";
+export { checkCompensations, runUndo, undoFindings, undoPlan, } from "./undo/index.js";
+export * from "./verify/index.js";
+export { VERSION } from "./version.js";
+export { weather } from "./weather/index.js";
+export { postReceipt, receiptFor, workspaceTree } from "./workspace-receipt/index.js";

package/dist/investigate/index.d.ts

@@ -0,0 +1,66 @@
+import { type Span } from "../authority/index.ts";
+import type { Directive } from "../directives/index.ts";
+import { type Summary } from "../fleet/index.ts";
+export interface InvestigationOptions {
+    summary: Summary;
+    models: readonly string[];
+    directives?: readonly Directive[];
+}
+/** spec/investigations.md §1. */
+export declare function investigation(lines: readonly string[], opts: InvestigationOptions): {
+    kind: "blackbox.investigation";
+    v: 1;
+    session_id: string;
+    label: string | null;
+    started_at: string;
+    last_event_at: string;
+    events: number;
+    outcome: string | null;
+    authority: Span[];
+    findings: {
+        seq: number;
+        code: string;
+        fault: string;
+        severity: string;
+        source: string;
+        in_control: import("../authority/index.ts").Mode | null;
+        in_control_by: string | null;
+        weather: {} | null;
+    }[];
+    directives: {
+        id: string;
+        applies_to: {
+            model: string;
+        } | {
+            tool: string;
+        };
+        pattern: string[];
+        affected_ppm: number;
+    }[] | null;
+    drill: {
+        drill: true;
+        planned: import("../drills/index.ts").Fault[];
+        injected: {
+            seq: number;
+            kind: string;
+        }[];
+        findings_after: string[];
+        recovered: boolean;
+        outcome: string | null;
+    } | null;
+};
+export type Investigation = ReturnType<typeof investigation> & {
+    verification?: {
+        ok: boolean;
+        identity: boolean;
+        proofs: string;
+    };
+    investigated_at?: string;
+    bundle_sha256?: string;
+    signed?: {
+        by: string;
+        sig: string;
+    };
+};
+/** spec/investigations.md §3: the reading copy. The signed JSON is the report; this isn't. */
+export declare function renderInvestigation(r: Investigation): string;