@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/reconcile/record.js

@@ -0,0 +1,225 @@
+// What the record says happened (spec/reconcile.md §2): one Call per llm.request, with the response
+// rebuilt from its chunks. Mirrors sdks/python/src/zanii_blackbox/reconcile/record.py.
+const decoder = new TextDecoder();
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The calls in a verified record, in request order. */
+export function callsOf(lines, bodies) {
+    const events = lines.map((l) => JSON.parse(l));
+    const calls = new Map();
+    const chunks = new Map();
+    // ponytail: records from before request_seq existed (pre-Stage 2.1) attach to the latest request,
+    // which is right unless streams interleaved.
+    let latest = null;
+    const text = (hash) => {
+        const b = bodies(hash);
+        return b === undefined ? "" : decoder.decode(b);
+    };
+    for (const e of events) {
+        const meta = e.meta;
+        if (e.kind === "llm.request") {
+            latest = e.seq;
+            const request = parseJson(text(e.body_hash));
+            calls.set(e.seq, {
+                requestSeq: e.seq,
+                endSeq: e.seq,
+                path: typeof meta.path === "string" ? meta.path : "",
+                headers: isObj(meta.headers) ? meta.headers : {},
+                request: isObj(request) ? request : null,
+                complete: false,
+                status: null,
+                redacted: meta.redacted !== undefined,
+                requestRedacted: meta.redacted !== undefined,
+                messageId: null,
+                responseId: null,
+                model: null,
+                usage: null,
+                provider: typeof meta.provider === "string" ? meta.provider : null,
+                serviceTier: null,
+                reportedMicroUsd: null,
+                blocks: new Map(),
+                items: [],
+            });
+            chunks.set(e.seq, []);
+            continue;
+        }
+        if (e.kind !== "llm.chunk" && e.kind !== "llm.response" && e.kind !== "llm.incomplete")
+            continue;
+        const owner = typeof meta.request_seq === "number" ? meta.request_seq : latest;
+        const call = owner === null ? undefined : calls.get(owner);
+        if (!call)
+            continue;
+        if (meta.redacted !== undefined)
+            call.redacted = true;
+        if (e.kind === "llm.chunk") {
+            chunks.get(call.requestSeq)?.push(text(e.body_hash));
+            continue;
+        }
+        call.endSeq = e.seq;
+        call.complete = e.kind === "llm.response";
+        call.status = typeof meta.status === "number" ? meta.status : null;
+        if (typeof meta.message_id === "string")
+            call.messageId = meta.message_id;
+        if (typeof meta.response_id === "string")
+            call.responseId = meta.response_id;
+        if (typeof meta.model === "string")
+            call.model = meta.model;
+        if (isObj(meta.usage))
+            call.usage = meta.usage;
+        if (typeof meta.service_tier === "string")
+            call.serviceTier = meta.service_tier;
+        if (Number.isSafeInteger(meta.reported_cost_micro_usd))
+            call.reportedMicroUsd = meta.reported_cost_micro_usd;
+        rebuild(call, (chunks.get(call.requestSeq) ?? []).join(""));
+    }
+    return [...calls.values()];
+}
+/** The workspace receipts in a record (spec/reconcile.md §7), in seq order. */
+export function receiptsOf(lines) {
+    const out = [];
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind !== "workspace.receipt")
+            continue;
+        const m = e.meta;
+        if ((m.phase !== "pre" && m.phase !== "post") || typeof m.tool_use_id !== "string")
+            continue;
+        out.push({
+            seq: e.seq,
+            phase: m.phase,
+            toolUseId: m.tool_use_id,
+            agentSession: typeof m.agent_session === "string" ? m.agent_session : null,
+            tree: typeof m.tree === "string" ? m.tree : null,
+        });
+    }
+    return out;
+}
+/** Rebuilds the response content from its bytes: an SSE stream, or one JSON body. */
+function rebuild(call, body) {
+    const trimmed = body.trimStart();
+    if (trimmed.startsWith("{")) {
+        const json = parseJson(trimmed);
+        if (!isObj(json))
+            return;
+        if (Array.isArray(json.content)) {
+            if (typeof json.id === "string")
+                call.messageId ??= json.id;
+            json.content.forEach((b, i) => {
+                if (isObj(b) && typeof b.type === "string")
+                    call.blocks.set(i, b);
+            });
+        }
+        if (Array.isArray(json.output)) {
+            if (typeof json.id === "string")
+                call.responseId ??= json.id;
+            call.items = json.output.filter(isObj);
+        }
+        if (Array.isArray(json.choices)) {
+            if (typeof json.id === "string")
+                call.messageId ??= json.id;
+            const message = json.choices.find(isObj)?.message;
+            if (isObj(message))
+                chatBlocks(call, message.content, message.tool_calls);
+        }
+        return;
+    }
+    const partial = new Map();
+    // Chat Completions streams: text and tool-call deltas, gathered then mapped onto blocks.
+    let chatText = null;
+    const chatCalls = new Map();
+    for (const line of body.split(/\r?\n/)) {
+        if (!line.startsWith("data:"))
+            continue;
+        const event = parseJson(line.slice(5).trim());
+        if (!isObj(event))
+            continue;
+        const type = event.type;
+        if (Array.isArray(event.choices)) {
+            if (typeof event.id === "string")
+                call.messageId ??= event.id;
+            const delta = event.choices.find(isObj)?.delta;
+            if (!isObj(delta))
+                continue;
+            if (typeof delta.content === "string")
+                chatText = (chatText ?? "") + delta.content;
+            for (const tc of Array.isArray(delta.tool_calls) ? delta.tool_calls.filter(isObj) : []) {
+                const k = typeof tc.index === "number" ? tc.index : 0;
+                const acc = chatCalls.get(k) ?? { arguments: "" };
+                const fn = isObj(tc.function) ? tc.function : {};
+                if (typeof tc.id === "string")
+                    acc.id = tc.id;
+                if (typeof fn.name === "string")
+                    acc.name = (acc.name ?? "") + fn.name;
+                if (typeof fn.arguments === "string")
+                    acc.arguments += fn.arguments;
+                chatCalls.set(k, acc);
+            }
+            continue;
+        }
+        if (type === "message_start" && isObj(event.message) && typeof event.message.id === "string")
+            call.messageId ??= event.message.id;
+        else if (type === "content_block_start" &&
+            typeof event.index === "number" &&
+            isObj(event.content_block))
+            call.blocks.set(event.index, { ...event.content_block });
+        else if (type === "content_block_delta" &&
+            typeof event.index === "number" &&
+            isObj(event.delta)) {
+            const block = call.blocks.get(event.index);
+            const d = event.delta;
+            if (!block)
+                continue;
+            if (d.type === "text_delta" && typeof d.text === "string")
+                block.text = (block.text ?? "") + d.text;
+            else if (d.type === "thinking_delta" && typeof d.thinking === "string")
+                block.thinking = (block.thinking ?? "") + d.thinking;
+            else if (d.type === "input_json_delta" && typeof d.partial_json === "string")
+                partial.set(event.index, (partial.get(event.index) ?? "") + d.partial_json);
+        }
+        else if (type === "content_block_stop" && typeof event.index === "number") {
+            const block = call.blocks.get(event.index);
+            const json = partial.get(event.index);
+            if (block && json !== undefined && json !== "")
+                block.input = parseJson(json);
+        }
+        else if (type === "response.output_item.done" && isObj(event.item))
+            call.items.push(event.item);
+        else if ((type === "response.created" || type === "response.completed") &&
+            isObj(event.response) &&
+            typeof event.response.id === "string")
+            call.responseId ??= event.response.id;
+    }
+    if (chatText !== null || chatCalls.size > 0)
+        chatBlocks(call, chatText, [...chatCalls.entries()]
+            .sort(([a], [b]) => a - b)
+            .map(([, c]) => ({ id: c.id, function: { name: c.name, arguments: c.arguments } })));
+}
+/**
+ * spec/reconcile.md §2: a Chat Completions message as content blocks, so every reader of blocks sees
+ * its text and tool calls: a text block (when there's text), then one tool_use per tool call, its
+ * arguments parsed from their JSON string.
+ */
+function chatBlocks(call, content, toolCalls) {
+    let i = 0;
+    if (typeof content === "string" && content !== "")
+        call.blocks.set(i++, { type: "text", text: content });
+    for (const tc of Array.isArray(toolCalls) ? toolCalls.filter(isObj) : []) {
+        const fn = isObj(tc.function) ? tc.function : {};
+        if (typeof fn.name !== "string")
+            continue;
+        const args = typeof fn.arguments === "string" ? parseJson(fn.arguments || "{}") : fn.arguments;
+        call.blocks.set(i++, {
+            type: "tool_use",
+            name: fn.name,
+            input: args ?? {},
+            ...(typeof tc.id === "string" ? { id: tc.id } : {}),
+        });
+    }
+}

package/dist/reconcile/shared.d.ts

@@ -0,0 +1,65 @@
+import type { Obj } from "./record.ts";
+export type Harness = "claude-code" | "codex";
+export type FindingCode = "MISSING_LOCAL" | "ALTERED" | "EXTRA_LOCAL" | "LOCAL_GAP" | "RECEIPT_MISSING" | "UNATTRIBUTED_CHANGE";
+export interface Finding {
+    code: FindingCode;
+    ref: Record<string, string | number>;
+    gateway_seq?: number;
+    local?: {
+        file: string;
+        line: number;
+    };
+}
+export interface Report {
+    v: 1;
+    harness: Harness;
+    ok: boolean;
+    record: {
+        session_id: string;
+        events: number;
+        calls: number;
+        calls_expected: number;
+        calls_not_expected: number;
+    };
+    local: {
+        files: number;
+        records: number;
+        agent_sessions: string[];
+    };
+    matched: {
+        calls: number;
+        tool_results: number;
+    };
+    findings: Finding[];
+    /** Claude Code, when workspace receipts are required (spec/reconcile.md §7). */
+    workspace?: {
+        receipts: number;
+        changed_by: string[];
+    };
+    notes: string[];
+    warnings: string[];
+}
+export interface LocalRecord {
+    file: string;
+    line: number;
+    json: Obj;
+}
+export interface LocalLog {
+    files: string[];
+    records: LocalRecord[];
+    /** Offloaded tool outputs (Claude Code `tool-results/`), as text. */
+    offloaded: Set<string>;
+    warnings: string[];
+}
+export declare const isObj: (v: unknown) => v is Obj;
+/** Keys sorted, no whitespace. */
+export declare function canonical(value: unknown): string;
+/** Text of a string or of a list of content blocks. */
+export declare function normText(content: unknown): string;
+/**
+ * Reads the local log. A missing path is an empty log. For a Claude Code session file, its
+ * `<id>/subagents/*.jsonl` and `<id>/tool-results/*` are read too.
+ */
+export declare function loadLocal(path: string, harness: Harness): LocalLog;
+/** "unknown record type" warnings, one per type, with a count. */
+export declare function unknownTypes(records: LocalRecord[], known: ReadonlySet<string>): string[];

package/dist/reconcile/shared.js

@@ -0,0 +1,113 @@
+// Types and helpers both harnesses share (spec/reconcile.md). Mirrors reconcile/shared.py.
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, sep } from "node:path";
+export const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Keys sorted, no whitespace. */
+export function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (isObj(value))
+        return `{${Object.keys(value)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+            .join(",")}}`;
+    return JSON.stringify(value) ?? "null";
+}
+/** Text of a string or of a list of content blocks. */
+export function normText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return canonical(content);
+    return content
+        .map((b) => {
+        if (!isObj(b))
+            return "";
+        if (b.type === "text")
+            return typeof b.text === "string" ? b.text : "";
+        if (b.type === "image") {
+            const data = isObj(b.source) && typeof b.source.data === "string" ? b.source.data : "";
+            return `[image:${createHash("sha256").update(data).digest("hex")}]`;
+        }
+        return `[${String(b.type)}]`;
+    })
+        .join("");
+}
+/**
+ * Reads the local log. A missing path is an empty log. For a Claude Code session file, its
+ * `<id>/subagents/*.jsonl` and `<id>/tool-results/*` are read too.
+ */
+export function loadLocal(path, harness) {
+    const log = { files: [], records: [], offloaded: new Set(), warnings: [] };
+    if (!existsSync(path))
+        return log;
+    let base;
+    const jsonl = [];
+    const offloaded = [];
+    if (statSync(path).isDirectory()) {
+        base = path;
+        for (const f of walk(path)) {
+            if (f.endsWith(".jsonl"))
+                jsonl.push(f);
+            else if (harness === "claude-code" && f.split(sep).includes("tool-results"))
+                offloaded.push(f);
+        }
+    }
+    else {
+        base = dirname(path);
+        jsonl.push(path);
+        const sessionDir = join(base, basename(path, ".jsonl"));
+        if (harness === "claude-code" && existsSync(sessionDir))
+            for (const f of walk(sessionDir)) {
+                if (f.endsWith(".jsonl") && f.split(sep).includes("subagents"))
+                    jsonl.push(f);
+                else if (f.split(sep).includes("tool-results"))
+                    offloaded.push(f);
+            }
+    }
+    const rel = (f) => relative(base, f).split(sep).join("/");
+    for (const f of offloaded)
+        log.offloaded.add(readFileSync(f, "utf8"));
+    const files = jsonl
+        .map((f) => ({ f, r: rel(f) }))
+        .sort((a, b) => (a.r < b.r ? -1 : a.r > b.r ? 1 : 0));
+    for (const { f, r } of files) {
+        log.files.push(r);
+        readFileSync(f, "utf8")
+            .split("\n")
+            .forEach((line, i) => {
+            if (line.trim() === "")
+                return;
+            try {
+                const json = JSON.parse(line);
+                if (isObj(json))
+                    log.records.push({ file: r, line: i + 1, json });
+                else
+                    log.warnings.push(`${r}:${i + 1}: not a JSON object`);
+            }
+            catch {
+                log.warnings.push(`${r}:${i + 1}: not JSON`);
+            }
+        });
+    }
+    return log;
+}
+function walk(dir) {
+    return readdirSync(dir).flatMap((name) => {
+        const p = join(dir, name);
+        return statSync(p).isDirectory() ? walk(p) : [p];
+    });
+}
+/** "unknown record type" warnings, one per type, with a count. */
+export function unknownTypes(records, known) {
+    const counts = new Map();
+    for (const r of records) {
+        const t = typeof r.json.type === "string" ? r.json.type : "(none)";
+        if (!known.has(t))
+            counts.set(t, (counts.get(t) ?? 0) + 1);
+    }
+    return [...counts]
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([t, n]) => `unknown record type "${t}" (${n})`);
+}

package/dist/replay/index.d.ts

@@ -0,0 +1,11 @@
+/** `rk:` + sha256 over the canonical key fields of a JSON request; of the raw bytes otherwise. */
+export declare function requestKey(body: Uint8Array): string;
+export interface Take {
+    request_seq: number;
+    key: string;
+    status: number;
+    content_type: string;
+    body: Uint8Array;
+}
+/** Every completed model call, in request order: its key and the exact response bytes recorded. */
+export declare function cassette(lines: readonly string[], bodies: (hash: string) => Uint8Array | undefined): Take[];

package/dist/replay/index.js

@@ -0,0 +1,64 @@
+// Replay (spec/replay.md): a recorded session as a cassette of model calls the gateway can serve
+// again, and the key that says whether a new request is the same call. Mirrors replay.py.
+import { createHash } from "node:crypto";
+import { canonical } from "../reconcile/shared.js";
+/** The fields that make two requests the same call; everything else (metadata, stream flags) is noise. */
+const KEY_FIELDS = ["model", "system", "instructions", "messages", "input", "tools"];
+/** `rk:` + sha256 over the canonical key fields of a JSON request; of the raw bytes otherwise. */
+export function requestKey(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(body));
+    }
+    catch {
+        parsed = undefined;
+    }
+    const h = createHash("sha256");
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        const o = parsed;
+        h.update(canonical(Object.fromEntries(KEY_FIELDS.filter((k) => k in o).map((k) => [k, o[k]]))));
+    }
+    else
+        h.update(body);
+    return `rk:${h.digest("hex")}`;
+}
+/** Every completed model call, in request order: its key and the exact response bytes recorded. */
+export function cassette(lines, bodies) {
+    const events = lines.map((l) => JSON.parse(l));
+    const chunks = new Map();
+    const done = new Map();
+    let last;
+    for (const e of events) {
+        if (e.kind === "llm.request")
+            last = e.seq;
+        // Records made before request_seq (Stage 2.1): an unlinked event belongs to the latest request.
+        const rs = typeof e.meta.request_seq === "number" ? e.meta.request_seq : last;
+        if (rs === undefined)
+            continue;
+        if (e.kind === "llm.chunk") {
+            const list = chunks.get(rs) ?? [];
+            list.push(bodies(e.body_hash) ?? new Uint8Array());
+            chunks.set(rs, list);
+        }
+        else if (e.kind === "llm.response" && typeof e.meta.status === "number")
+            done.set(rs, e.meta.status);
+    }
+    const takes = [];
+    for (const e of events) {
+        const status = done.get(e.seq);
+        if (e.kind !== "llm.request" || status === undefined)
+            continue;
+        const body = Buffer.concat(chunks.get(e.seq) ?? []);
+        const head = body.subarray(0, 16).toString("utf8").trimStart();
+        takes.push({
+            request_seq: e.seq,
+            key: requestKey(bodies(e.body_hash) ?? new Uint8Array()),
+            status,
+            content_type: head.startsWith("event:") || head.startsWith("data:")
+                ? "text/event-stream"
+                : "application/json",
+            body: new Uint8Array(body),
+        });
+    }
+    return takes;
+}

package/dist/replay/repair.d.ts

@@ -0,0 +1,10 @@
+type Msg = Record<string, unknown>;
+export declare const ORPHAN_TEXT = "blackbox: this call didn't finish (the run stopped mid-call). Check what it did before calling it again.";
+/** The messages with an error result for every tool call that has none, and the ids it repaired.
+ * OpenAI / LangChain style (`tool_calls` + `tool_call_id` messages) and Anthropic style
+ * (`tool_use` blocks + `tool_result` blocks in the next user message). The input isn't changed. */
+export declare function repairToolCalls(messages: readonly Msg[]): {
+    messages: Msg[];
+    repaired: string[];
+};
+export {};

package/dist/replay/repair.js

@@ -0,0 +1,62 @@
+// Repairing orphaned tool calls (spec/replay.md §5, idea R9): a run that crashed mid-call left a
+// tool call with no result, and a provider refuses a history like that. Before a fork or a resume,
+// each one gets an error result that says so. Mirrors repair.py.
+export const ORPHAN_TEXT = "blackbox: this call didn't finish (the run stopped mid-call). Check what it did before calling it again.";
+const isAi = (m) => m.role === "assistant" || m.type === "ai";
+const isTool = (m) => m?.role === "tool" || m?.type === "tool";
+const blocks = (m) => Array.isArray(m?.content) ? m.content : [];
+/** The messages with an error result for every tool call that has none, and the ids it repaired.
+ * OpenAI / LangChain style (`tool_calls` + `tool_call_id` messages) and Anthropic style
+ * (`tool_use` blocks + `tool_result` blocks in the next user message). The input isn't changed. */
+export function repairToolCalls(messages) {
+    const answered = new Set();
+    for (const m of messages) {
+        if (isTool(m) && typeof m.tool_call_id === "string")
+            answered.add(m.tool_call_id);
+        for (const b of blocks(m))
+            if (b?.type === "tool_result" && typeof b.tool_use_id === "string")
+                answered.add(b.tool_use_id);
+    }
+    const out = [];
+    const repaired = [];
+    let i = 0;
+    while (i < messages.length) {
+        const m = messages[i++];
+        out.push(m);
+        if (!isAi(m))
+            continue;
+        while (isTool(messages[i]))
+            out.push(messages[i++]); // this turn's own results first
+        const calls = Array.isArray(m.tool_calls) ? m.tool_calls : [];
+        for (const c of calls)
+            if (typeof c?.id === "string" && !answered.has(c.id)) {
+                repaired.push(c.id);
+                out.push({
+                    ...(m.type === "ai" ? { type: "tool" } : { role: "tool" }),
+                    tool_call_id: c.id,
+                    content: ORPHAN_TEXT,
+                });
+            }
+        const unanswered = blocks(m)
+            .filter((b) => b?.type === "tool_use" && typeof b.id === "string" && !answered.has(b.id))
+            .map((b) => b.id);
+        if (unanswered.length === 0)
+            continue;
+        repaired.push(...unanswered);
+        const results = unanswered.map((id) => ({
+            type: "tool_result",
+            tool_use_id: id,
+            is_error: true,
+            content: ORPHAN_TEXT,
+        }));
+        const next = messages[i];
+        if (next?.role === "user") {
+            const content = typeof next.content === "string" ? [{ type: "text", text: next.content }] : blocks(next);
+            out.push({ ...next, content: [...results, ...content] });
+            i++;
+        }
+        else
+            out.push({ role: "user", content: results });
+    }
+    return { messages: out, repaired };
+}

package/dist/session/drain.d.ts

@@ -0,0 +1,13 @@
+export interface DrainResult {
+    session_id: string;
+    shipped: boolean;
+    /** Events the gateway still doesn't have (0 when shipped). */
+    left: number;
+}
+/** Only for agents that have stopped: a running agent ships its own spool. Never throws. */
+export declare function drainSpools(options: {
+    url: string;
+    spoolDir?: string;
+    timeoutMs?: number;
+    logger?: (message: string) => void;
+}): Promise<DrainResult[]>;

package/dist/session/drain.js

@@ -0,0 +1,35 @@
+// Audit K5: ships the events a stopped agent left in its spool. The SDK keeps the token of a session
+// it opened itself next to the spool (`<id>.token`, mode 0600), since only it knew the token; this
+// reads each one and ships what the gateway hasn't acknowledged. The session isn't closed: the
+// gateway already recorded the lost contact, and an operator closes it (or it lapses, spec/api.md).
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BlackboxSession } from "./index.js";
+/** Only for agents that have stopped: a running agent ships its own spool. Never throws. */
+export async function drainSpools(options) {
+    const dir = options.spoolDir ?? process.env.BLACKBOX_SPOOL_DIR ?? join(tmpdir(), "zanii-blackbox-spool");
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const file of readdirSync(dir)
+        .filter((f) => f.endsWith(".token"))
+        .sort()) {
+        const id = file.slice(0, -".token".length);
+        const token = readFileSync(join(dir, file), "utf8").trim();
+        const s = new BlackboxSession({
+            url: options.url,
+            spoolDir: dir,
+            heartbeatMs: 0,
+            flushMs: 60_000,
+            ...(options.logger ? { logger: options.logger } : {}),
+        }, id, token);
+        const shipped = await s.flush({ timeoutMs: options.timeoutMs ?? 30_000 });
+        const left = s.stats.recorded - s.stats.acked;
+        s.stop();
+        if (shipped)
+            rmSync(join(dir, file), { force: true });
+        out.push({ session_id: id, shipped, left: shipped ? 0 : Math.max(0, left) });
+    }
+    return out;
+}