@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/session/index.js

@@ -0,0 +1,681 @@
+// SDK sessions (spec/sdk.md): a local spool with sdk_seq (T1.1), shipped in the background, and the
+// never-crash contract (T1.7). Mirrors sdks/python/src/zanii_blackbox/session.py.
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, closeSync, existsSync, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, truncateSync, writeFileSync, } from "node:fs";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { attest, isReadOnly } from "../attest/index.js";
+/** spec/data.md §6: a direct HTTPS request to `url` (default https://example.com). Never throws. */
+export async function checkEgress(options = {}) {
+    const url = options.url ?? "https://example.com";
+    try {
+        await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(options.timeoutMs ?? 5000) });
+        return { url, open: true };
+    }
+    catch {
+        return { url, open: false };
+    }
+}
+const TYPE = /^[a-z][a-z0-9_.]{0,63}$/;
+/** N4 (idea R6): a caller's logical id for an event, so a re-sent one is recorded as a duplicate. */
+const EVENT_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+/** N4 (idea R6): the same parts always give the same event id (sha256, 128 bits). */
+export function stableEventId(...parts) {
+    return `evt_${createHash("sha256").update(parts.join("\u001f")).digest("hex").slice(0, 32)}`;
+}
+const MAX_DATA = 64 * 1024;
+/** Audit S20: how much of an over-long event's data is kept, in code points of its JSON. */
+const PREVIEW = 4096;
+const BATCH = 500;
+const READ_CHUNK = 4 * 1024 * 1024;
+const LOCK_WAIT_MS = 2_000;
+const LOCK_STALE_MS = 10_000;
+/** Opens (or joins) a session. Never throws: on failure it returns a disabled session and logs why. */
+export async function session(options) {
+    const log = options.logger ?? (() => { });
+    let id = options.sessionId;
+    let token = options.token;
+    try {
+        if (!id || !token) {
+            const key = options.adminKey ?? options.apiKey;
+            if (!key)
+                throw new Error("pass sessionId + token, or adminKey to open a session");
+            const o = options;
+            // Audit K10: one key for every attempt, so a retry after a lost answer can't open a second.
+            const idempotencyKey = randomUUID();
+            const r = await openWithRetry(options.url, key, idempotencyKey, {
+                ...(o.label ? { label: o.label } : {}),
+                ...(o.mode ? { mode: o.mode } : {}),
+                ...(o.flightPlan ? { flight_plan: o.flightPlan } : {}),
+                ...(o.policy ? { policy: o.policy } : {}),
+                ...(o.budgetUsd !== undefined ? { budget_usd: o.budgetUsd } : {}),
+                ...(o.maxLlmCalls !== undefined ? { max_llm_calls: o.maxLlmCalls } : {}),
+                ...(o.parent ? { parent: o.parent } : {}),
+                ...(o.handoff ? { handoff: o.handoff } : {}),
+                ...(o.replay ? { replay: o.replay } : {}),
+                ...(o.tenant ? { tenant: o.tenant } : {}),
+                ...(o.authority ? { authority: o.authority } : {}),
+                ...(o.preflight ? { preflight: o.preflight } : {}),
+                ...(o.drill ? { drill: o.drill } : {}),
+                sdk: true, // this SDK will report the session's model calls (L2.3.2)
+            });
+            if (r.status !== 201)
+                throw new Error(`opening a session: the gateway answered ${r.status}${typeof r.json.error === "string" ? ` (${r.json.error})` : ""}`);
+            id = String(r.json.session_id);
+            token = String(r.json.token);
+            return new BlackboxSession(options, id, token, true, true);
+        }
+        return new BlackboxSession(options, id, token);
+    }
+    catch (error) {
+        log(`blackbox: session disabled: ${message(error)}`);
+        return BlackboxSession.disabled(options, message(error));
+    }
+}
+export class BlackboxSession {
+    stats = { recorded: 0, acked: 0, errors: 0, dropped: 0 };
+    enabled;
+    spool;
+    ackFile;
+    nextSeq = 0;
+    ack = { next: 0, offset: 0, gen: 0 };
+    /** The spool's size after our own last change; anything else means another process wrote. */
+    knownSize = -1;
+    shipping = null;
+    retryAt = 0;
+    backoff = 500;
+    timers = [];
+    closed = false;
+    landings = 0;
+    /** A session that records nothing. `reason`, when opening failed, goes to `stats.lastError` (audit K1). */
+    static disabled(options, reason) {
+        const s = new BlackboxSession(options, "", "", false);
+        if (reason !== undefined) {
+            s.stats.errors++;
+            const kind = reason.startsWith("opening a session: the gateway answered")
+                ? "rejected"
+                : "network";
+            s.stats.lastError = { kind, message: reason, at: new Date().toISOString() };
+        }
+        return s;
+    }
+    options;
+    id;
+    token;
+    constructor(options, id, token, enabled = true, 
+    /** Audit K5: this SDK opened the session, so only it knows the token: keep it by the spool. */
+    keepToken = false) {
+        this.options = options;
+        this.id = id;
+        this.token = token;
+        this.enabled = enabled;
+        const dir = options.spoolDir ?? process.env.BLACKBOX_SPOOL_DIR ?? join(tmpdir(), "zanii-blackbox-spool");
+        this.spool = join(dir, `${id}.jsonl`);
+        this.ackFile = join(dir, `${id}.ack`);
+        if (!enabled)
+            return;
+        this.guard(() => {
+            mkdirSync(dir, { recursive: true });
+            if (keepToken)
+                writeFileSync(join(dir, `${id}.token`), token, { mode: 0o600 });
+            // Resume: number after the last line, ship from the last acknowledged offset.
+            this.withLock(() => {
+                if (existsSync(this.spool))
+                    repairTornLine(this.spool);
+                this.knownSize = -1; // force a refresh from the files
+            });
+            this.stats.recorded = this.nextSeq;
+            this.stats.acked = this.ack.next;
+        });
+        const flush = setInterval(() => void this.tick(), options.flushMs ?? 500);
+        flush.unref();
+        this.timers.push(flush);
+        const beat = options.heartbeatMs ?? 10_000;
+        if (beat > 0) {
+            const t = setInterval(() => void this.heartbeat(), beat);
+            t.unref();
+            this.timers.push(t);
+        }
+    }
+    // ------------------------------------------------------------ recording (never throws, never blocks on the network)
+    event(type, name, data, options = {}) {
+        if (!this.enabled || this.closed)
+            return;
+        this.guard(() => {
+            const eventId = options.eventId;
+            if (!TYPE.test(type) ||
+                (name !== undefined && name.length > 256) ||
+                (eventId !== undefined && !EVENT_ID.test(eventId))) {
+                this.stats.dropped++;
+                this.fail("invalid", `event dropped (invalid type or name): ${type}`);
+                return;
+            }
+            const json = data === undefined ? "" : JSON.stringify(data);
+            const bytes = Buffer.byteLength(json);
+            // Audit S20: over 64 KB, kept cut short rather than lost. The gateway counts UTF-8 bytes too.
+            const kept = bytes > MAX_DATA
+                ? { truncated: bytes, preview: Array.from(json).slice(0, PREVIEW).join("") }
+                : data;
+            if (kept !== data)
+                this.log(`blackbox: event data over 64 KB (${bytes} bytes) kept truncated`);
+            try {
+                // Under the spool lock: another process of the same session may have written (L2.2.2).
+                this.withLock(() => {
+                    const line = JSON.stringify({
+                        sdk_seq: this.nextSeq,
+                        type,
+                        ...(name === undefined ? {} : { name }),
+                        ...(eventId === undefined ? {} : { event_id: eventId }),
+                        ts: new Date().toISOString(),
+                        ...(kept === undefined ? {} : { data: kept }),
+                    });
+                    appendFileSync(this.spool, `${line}\n`);
+                    this.nextSeq++;
+                    this.knownSize = statSync(this.spool).size;
+                });
+            }
+            catch (error) {
+                this.stats.dropped++;
+                throw error;
+            }
+            this.stats.recorded++;
+        });
+    }
+    step(name, data) {
+        this.event("step", name, data);
+    }
+    toolCall(name, args) {
+        this.event("tool.call", name, args === undefined ? undefined : { args });
+    }
+    toolResult(name, result) {
+        this.event("tool.result", name, result);
+    }
+    /** spec/data.md §7: a subject's consent for a purpose. The subject is fingerprinted at capture,
+     *  so it must be an identifier the deployment knows (an e-mail, an Emirates ID, a pack's own). */
+    consent(subject, purpose, granted) {
+        this.event("consent", granted ? "granted" : "withdrawn", { subject, purpose });
+    }
+    /** spec/data.md §6: tries the internet directly, outside the gateway, and records the answer.
+     *  `open: true` means the gateway isn't the only way out (EGRESS_OPEN). */
+    async egressCheck(options = {}) {
+        const result = await checkEgress(options);
+        this.event("egress_check", result.open ? "open" : "closed", { url: result.url });
+        return result;
+    }
+    llmCall(ids) {
+        this.event("llm.call", ids.provider, { ...ids });
+    }
+    note(text) {
+        this.event("note", undefined, { text });
+    }
+    /** Files the flight plan (spec/findings.md §5), unless one was filed when the session opened. */
+    flightPlan(plan) {
+        this.event("flight_plan", undefined, plan);
+    }
+    /** A completion claim; the server judges it against the recorded tool calls. */
+    claim(summary, asserts) {
+        this.event("claim", undefined, { summary, ...(asserts ? { asserts } : {}) });
+    }
+    /** N2 (idea C10): claims it's done and reads the gateway's verdict, so a failed check goes back
+     * to the model as feedback, a bounded number of times. Never throws. */
+    async land(summary, asserts, options = {}) {
+        this.landings++;
+        const attemptsLeft = Math.max(0, (options.maxAttempts ?? 3) - this.landings);
+        const error = (why) => {
+            this.fail("network", `landing: ${why}`);
+            return { landed: false, verdict: "error", feedback: [why], attemptsLeft };
+        };
+        if (!this.enabled)
+            return { landed: false, verdict: "error", feedback: [], attemptsLeft };
+        try {
+            this.claim(summary, asserts);
+            if (!(await this.flush({ timeoutMs: 10_000 })))
+                return error("the claim wasn't shipped");
+            const r = await send("GET", this.options.url, `/v1/sessions/${this.id}/landing`, this.token);
+            const claims = (r.json.claims ?? []);
+            const last = claims.at(-1);
+            if (r.status !== 200 || !last)
+                return error(`the gateway answered ${r.status}`);
+            const verdict = last.verdict;
+            const feedback = last.criteria
+                .filter((c) => c.result !== "pass")
+                .map((c) => `${c.criterion} ${JSON.stringify(c.predicate)}: ${c.result}${c.gap ? ` (${c.gap})` : ""}`);
+            if (verdict === "unverified" && feedback.length === 0)
+                feedback.push("nothing to check");
+            return { landed: verdict === "satisfied", verdict, feedback, attemptsLeft };
+        }
+        catch (e) {
+            return error(message(e));
+        }
+    }
+    /** N4 (idea R8): the context the model sees changed (summarised, trimmed, a tool result moved
+     * aside), so a replay knows what the model saw. */
+    contextChange(change) {
+        this.event("context.change", change.kind, { ...change });
+    }
+    /** Stage 2 R3: the result of one of the customer's own checks (tests, a schema, a policy, a
+     * partial goal), mid-run or at the end. A pass then a fail is VERIFY_REGRESSION; a success whose last
+     * check failed is FALSE_SUCCESS (spec/findings.md §6). */
+    verify(check, ok, detail) {
+        this.event("verify", check, { ok, ...(detail ? { detail: detail.slice(0, 500) } : {}) });
+    }
+    /** N4 (idea R10): one more attempt at a model or tool call. */
+    retry(kind, target, info) {
+        this.event("retry", target, {
+            kind,
+            attempt: info.attempt,
+            ...(info.error === undefined ? {} : { error: info.error.slice(0, 500) }),
+            ...(info.delayMs === undefined ? {} : { delay_ms: info.delayMs }),
+        });
+    }
+    /** N4 (idea R10): a call moved to another model or provider. */
+    fallback(from, to, reason) {
+        this.event("fallback", to, { from, to, ...(reason ? { reason: reason.slice(0, 500) } : {}) });
+    }
+    /** N4 (idea R5): how the run is configured: LangGraph's `durability` (sync, async, exit), retry,
+     * timeout and cache policies. */
+    runConfig(config) {
+        this.event("run.config", undefined, { ...config });
+    }
+    /** The agent reports something it almost got wrong (spec/fleet.md §3): a NEAR_MISS finding. */
+    nearMiss(description) {
+        this.event("near_miss", undefined, { description });
+    }
+    /** spec/attestation.md: re-runs a read-only command and records whether the output matches. */
+    attest(argv, claimed, cwd, claimedExit) {
+        if (!isReadOnly(argv))
+            return undefined;
+        const result = attest(argv, claimed, cwd, claimedExit);
+        this.event("attestation", argv[0], { ...result });
+        return result;
+    }
+    /** spec/agents.md §1: the agent's memory store wrote, revoked or returned memories. */
+    memoryWrite(memoryId, summary) {
+        this.event("memory.write", undefined, { memory_id: memoryId, ...(summary ? { summary } : {}) });
+    }
+    memoryRevoke(memoryId, reason) {
+        this.event("memory.revoke", undefined, { memory_id: memoryId, ...(reason ? { reason } : {}) });
+    }
+    memoryRead(memoryIds, query) {
+        this.event("memory.read", undefined, { memory_ids: memoryIds, ...(query ? { query } : {}) });
+    }
+    // ------------------------------------------------------------ shipping
+    /** Ships what's pending now. Resolves true when everything recorded is acknowledged. With
+     * `timeoutMs` (audit S24) it keeps trying until then, and never waits longer. */
+    async flush(options = {}) {
+        if (!this.enabled)
+            return false;
+        if (options.timeoutMs === undefined) {
+            this.retryAt = 0;
+            await this.tick();
+            return this.ack.next >= this.nextSeq;
+        }
+        const deadline = Date.now() + options.timeoutMs;
+        for (;;) {
+            this.retryAt = 0;
+            let timer;
+            const late = new Promise((r) => {
+                timer = setTimeout(r, Math.max(0, deadline - Date.now()));
+            });
+            await Promise.race([this.tick(), late]);
+            clearTimeout(timer);
+            if (this.ack.next >= this.nextSeq || Date.now() >= deadline)
+                break;
+            await sleep(Math.min(250, Math.max(0, deadline - Date.now())));
+        }
+        const done = this.ack.next >= this.nextSeq;
+        if (!done)
+            this.fail("network", `flush timed out after ${options.timeoutMs} ms`);
+        return done;
+    }
+    /** Audit S17: the gateway's view of this session (blocked? findings?), or null if it can't be
+     * read. Lets an agent react to its own block before its next model call. Never throws. */
+    async state() {
+        if (!this.enabled)
+            return null;
+        try {
+            const r = await send("GET", this.options.url, `/v1/sessions/${this.id}/state`, this.token);
+            if (r.status === 200)
+                return r.json;
+            this.fail("rejected", `reading the session state: the gateway answered ${r.status}`);
+        }
+        catch (error) {
+            this.fail("network", `reading the session state: ${message(error)}`);
+        }
+        return null;
+    }
+    /** spec/approvals.md §2: asks a second person before running one of the agent's own risky tools,
+     * and waits (polling) for the answer. Never throws. Only `"approved"` means go ahead; anything
+     * else (`rejected`, `timeout`, or `error` when the gateway can't be asked) means don't. */
+    async requestApproval(tool, options = {}) {
+        return this.ask("approvals", { tool, ...(options.args ? { args: options.args } : {}) }, options);
+    }
+    /** N2 (idea C2): asks a person to let this session use a gateway tool its policy denies (the
+     * denial's `requires.tool`, e.g. `mcp__files__delete`). A yes is a standing grant for the
+     * session: retry the call. Answers like `requestApproval`. Never throws. */
+    async requestPermission(tool, options = {}) {
+        return this.ask("permissions", { tool }, options);
+    }
+    async ask(route, body, options) {
+        if (!this.enabled)
+            return "error";
+        try {
+            const r = await post(this.options.url, `/v1/sessions/${this.id}/${route}`, this.token, {
+                ...body,
+                ...(options.reason ? { reason: options.reason } : {}),
+            });
+            const id = r.json.approval_id;
+            if (r.status !== 201 || typeof id !== "string") {
+                this.fail("rejected", `asking for an approval: the gateway answered ${r.status}`);
+                return "error";
+            }
+            const deadline = Date.now() + (options.timeoutMs ?? 310_000);
+            while (Date.now() < deadline) {
+                const s = await send("GET", this.options.url, `/v1/sessions/${this.id}/approvals/${id}`, this.token);
+                const status = s.json.status;
+                if (status === "approved" || status === "rejected" || status === "timeout")
+                    return status;
+                await sleep(options.pollMs ?? 1_000);
+            }
+            return "timeout";
+        }
+        catch (error) {
+            this.fail("network", `asking for an approval: ${message(error)}`);
+            return "error";
+        }
+    }
+    /** Audit S8: `await using s = await session(…)` closes the session when the scope ends. */
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    /** Drains the spool (up to closeTimeoutMs), then closes the gateway session. Never throws.
+     * `outcome` labels the run for the waste ledger (spec/cost.md §5); `note` says why (audit S7).
+     * Audit K9: true only when the gateway closed it (or it was closed already); otherwise
+     * `stats.lastError` says why. */
+    async close(outcome, note) {
+        if (!this.enabled || this.closed)
+            return false;
+        this.closed = true;
+        for (const t of this.timers)
+            clearInterval(t);
+        if (!(await this.flush({ timeoutMs: this.options.closeTimeoutMs ?? 5_000 })))
+            this.log(`blackbox: ${this.nextSeq - this.ack.next} event(s) left in the spool: ship them with \`blackbox drain\``);
+        try {
+            const r = await post(this.options.url, `/v1/sessions/${this.id}/close`, this.token, {
+                ...(outcome ? { outcome } : {}),
+                ...(note ? { note } : {}),
+            });
+            if (r.status === 200 || r.status === 409) {
+                if (this.ack.next >= this.nextSeq)
+                    this.forgetToken();
+                return true;
+            }
+            this.stats.errors++;
+            this.fail("rejected", `closing the session: the gateway answered ${r.status}`);
+        }
+        catch (error) {
+            this.stats.errors++;
+            this.fail("network", `closing the session failed: ${message(error)}`);
+        }
+        return false;
+    }
+    /** Stops shipping and heartbeats without closing the gateway session (for `drain`). */
+    stop() {
+        this.closed = true;
+        for (const t of this.timers)
+            clearInterval(t);
+    }
+    /** The kept token (K5) is no longer needed once everything is shipped and the session closed. */
+    forgetToken() {
+        try {
+            rmSync(this.spool.replace(/\.jsonl$/, ".token"), { force: true });
+        }
+        catch { }
+    }
+    tick() {
+        if (this.shipping)
+            return this.shipping;
+        if (Date.now() < this.retryAt || this.ack.next >= this.nextSeq)
+            return Promise.resolve();
+        this.shipping = this.ship()
+            .catch((error) => {
+            this.stats.errors++;
+            this.backoff = Math.min(this.backoff * 2, 30_000);
+            this.retryAt = Date.now() + this.backoff * (0.5 + Math.random() / 2);
+            this.fail(error instanceof Rejected ? "rejected" : "network", `shipping failed, retrying: ${message(error)}`);
+        })
+            .finally(() => {
+            this.shipping = null;
+        });
+        return this.shipping;
+    }
+    async ship() {
+        const lines = [];
+        let from = { offset: 0, gen: 0 };
+        this.withLock(() => {
+            from = { offset: this.ack.offset, gen: this.ack.gen ?? 0 };
+            const fd = openSync(this.spool, "r+");
+            try {
+                fsyncSync(fd); // everything recorded so far reaches the disk before it's sent
+                const size = fstatSync(fd).size;
+                const buffer = Buffer.alloc(Math.max(0, Math.min(READ_CHUNK, size - from.offset)));
+                readSync(fd, buffer, 0, buffer.length, from.offset);
+                let start = 0;
+                for (let i = buffer.indexOf(0x0a); i >= 0 && lines.length < BATCH; i = buffer.indexOf(0x0a, start)) {
+                    lines.push({ text: buffer.subarray(start, i).toString("utf8"), bytes: i + 1 - start });
+                    start = i + 1;
+                }
+            }
+            finally {
+                closeSync(fd);
+            }
+        });
+        if (lines.length === 0)
+            return;
+        const events = lines.map((l) => JSON.parse(l.text));
+        const r = await post(this.options.url, `/v1/sessions/${this.id}/sdk-events`, this.token, {
+            events,
+        });
+        const next = typeof r.json.next === "number" ? r.json.next : null;
+        if (next === null)
+            throw new Rejected(r.status);
+        this.withLock(() => {
+            // Another process may have acknowledged or compacted meanwhile: then our offsets are stale.
+            if ((this.ack.gen ?? 0) === from.gen &&
+                this.ack.offset === from.offset &&
+                next > this.ack.next) {
+                // Advance past every sent line the server now has (sdk_seq < next).
+                let offset = from.offset;
+                for (const [i, e] of events.entries())
+                    if (e.sdk_seq < next)
+                        offset += lines[i]?.bytes ?? 0;
+                this.ack = { next, offset, gen: from.gen };
+                writeFileSync(this.ackFile, JSON.stringify(this.ack));
+            }
+            this.compact();
+        });
+        this.stats.acked = this.ack.next;
+        if (r.status !== 200)
+            throw new Rejected(r.status);
+        this.backoff = 500;
+    }
+    /** L2.2.3: once everything is acknowledged and enough is behind, empty the spool. The ack is
+     * written first: a crash in between only resends acknowledged lines, which the server ignores. */
+    compact() {
+        if (this.ack.next < this.nextSeq ||
+            this.ack.offset < (this.options.compactBytes ?? 1024 * 1024))
+            return;
+        this.ack = { next: this.ack.next, offset: 0, gen: (this.ack.gen ?? 0) + 1 };
+        writeFileSync(this.ackFile, JSON.stringify(this.ack));
+        truncateSync(this.spool, 0);
+        this.knownSize = 0;
+    }
+    /** Runs `fn` holding the session's spool lock (a lock file), after catching up with any other
+     * process's writes. A stale lock (a crashed holder) is broken after LOCK_STALE_MS. */
+    withLock(fn) {
+        const lock = `${this.spool}.lock`;
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        for (;;) {
+            try {
+                closeSync(openSync(lock, "wx"));
+                break;
+            }
+            catch (error) {
+                // Windows reports a lock file that's being deleted as EPERM / EACCES / EBUSY: also "held".
+                const code = error.code ?? "";
+                if (!["EEXIST", "EPERM", "EACCES", "EBUSY"].includes(code))
+                    throw error;
+                try {
+                    if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS)
+                        rmSync(lock, { force: true });
+                }
+                catch { }
+                if (Date.now() > deadline)
+                    throw new Error("the spool is locked by another process");
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+            }
+        }
+        try {
+            this.refresh();
+            fn();
+        }
+        finally {
+            rmSync(lock, { force: true });
+        }
+    }
+    /** Catches up with the files if another process changed them since our own last change. */
+    refresh() {
+        const size = existsSync(this.spool) ? statSync(this.spool).size : 0;
+        if (size === this.knownSize)
+            return;
+        if (existsSync(this.ackFile))
+            this.ack = JSON.parse(readFileSync(this.ackFile, "utf8"));
+        this.nextSeq = existsSync(this.spool) ? nextSeqOf(this.spool, this.ack.next) : this.ack.next;
+        this.knownSize = size;
+    }
+    async heartbeat() {
+        try {
+            const r = await post(this.options.url, `/v1/sessions/${this.id}/heartbeat`, this.token, {});
+            if (r.status >= 300) {
+                this.stats.errors++;
+                this.fail("rejected", `the heartbeat: the gateway answered ${r.status}`);
+            }
+        }
+        catch {
+            this.stats.errors++;
+        }
+    }
+    guard(fn) {
+        try {
+            fn();
+        }
+        catch (error) {
+            this.stats.errors++;
+            this.fail("disk", message(error));
+        }
+    }
+    /** Records the latest failure (audit S23) and logs it. */
+    fail(kind, text) {
+        this.stats.lastError = { kind, message: text, at: new Date().toISOString() };
+        this.log(`blackbox: ${text}`);
+    }
+    log(text) {
+        try {
+            this.options.logger?.(text);
+        }
+        catch { }
+    }
+}
+// ---------------------------------------------------------------- helpers
+/** Cuts off a torn last line (a crash mid-write; never shipped). */
+function repairTornLine(file) {
+    const bytes = readFileSync(file);
+    const end = bytes.lastIndexOf(0x0a) + 1;
+    if (end < bytes.length)
+        truncateSync(file, end);
+}
+/** The next sdk_seq: after the spool's last complete line, or `fallback` (the acknowledged next)
+ * when the spool is empty, e.g. just compacted. Reads only the tail. */
+function nextSeqOf(file, fallback) {
+    const fd = openSync(file, "r");
+    try {
+        const size = fstatSync(fd).size;
+        const n = Math.min(size, 128 * 1024);
+        const tail = Buffer.alloc(n);
+        readSync(fd, tail, 0, n, size - n);
+        const end = tail.lastIndexOf(0x0a);
+        if (end < 0)
+            return fallback;
+        const start = tail.lastIndexOf(0x0a, end - 1) + 1;
+        const seq = JSON.parse(tail.subarray(start, end).toString("utf8"))
+            .sdk_seq;
+        return Math.max(seq + 1, fallback);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const message = (e) => (e instanceof Error ? e.message : String(e));
+/** The gateway answered, but with an error (audit S23: `rejected`, not `network`). */
+class Rejected extends Error {
+    constructor(status) {
+        super(`the gateway answered ${status}`);
+    }
+}
+function post(base, path, bearer, body, headers = {}) {
+    return send("POST", base, path, bearer, body, headers);
+}
+/** Audit K10: opening is retried on a network error, a 429 or a 503 (up to 3 tries, backing off,
+ *  honouring Retry-After), with the same Idempotency-Key, so the gateway opens it at most once. */
+async function openWithRetry(base, key, idempotencyKey, body) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            const r = await post(base, "/v1/sessions", key, body, { "idempotency-key": idempotencyKey });
+            if ((r.status !== 429 && r.status !== 503) || attempt >= 3)
+                return r;
+            const after = Number(r.headers["retry-after"]);
+            await sleep(Math.min(5_000, after > 0 ? after * 1000 : 250 * 2 ** attempt));
+        }
+        catch (error) {
+            if (attempt >= 3)
+                throw error;
+            await sleep(250 * 2 ** attempt);
+        }
+    }
+}
+function send(method, base, path, bearer, body, headers = {}) {
+    return new Promise((resolve, reject) => {
+        const url = new URL(`${base.replace(/\/$/, "")}${path}`);
+        const data = body === undefined ? "" : JSON.stringify(body);
+        const req = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
+            method,
+            timeout: 10_000,
+            headers: {
+                authorization: `Bearer ${bearer}`,
+                ...headers,
+                ...(body === undefined
+                    ? {}
+                    : { "content-type": "application/json", "content-length": Buffer.byteLength(data) }),
+            },
+        });
+        req.on("response", (res) => {
+            const parts = [];
+            res.on("data", (d) => parts.push(d));
+            res.on("end", () => {
+                let json = {};
+                try {
+                    json = JSON.parse(Buffer.concat(parts).toString() || "{}");
+                }
+                catch { }
+                resolve({ status: res.statusCode ?? 0, json, headers: res.headers });
+            });
+            res.on("error", reject);
+        });
+        req.on("timeout", () => req.destroy(new Error("timed out")));
+        req.on("error", reject);
+        req.end(data);
+    });
+}