@zanii/blackbox 0.6.0 → 0.8.0

package/README.md

@@ -83,6 +83,16 @@ verifyAnswerCredential(credential, lines, bodies, packs); // { ok, problems }: t
 
 The same checks run offline as pure functions: `toolHallucinations`, `groundingFindings`, `factsIn`, `loadReferencePacks`, `answerRisk`, `detectorAccuracy`.
 
+## New in 0.8.0
+
+- `blackbox drain --close` (and `drainSpools({close: true})` / `drain_spools(close=True)`): after shipping what a stopped agent left behind, each session is closed as `abandoned`.
+- Works with gateway v0.10: alerts signed as Standard Webhooks, tenant keys that expire, more identity-provider algorithms (PS256, ES384, EdDSA).
+
+## New in 0.7.0
+
+- Any number of serverless functions or workers can write one session at the same moment: a joined session sends its events unnumbered, each with an id, and a v0.9+ gateway numbers them in arrival order (a resend adds nothing).
+- The repeat-call detector counts within one turn: a chat assistant or support bot asked for the same lookup in separate messages isn't stopped as a loop. A real loop inside one task still is.
+
 ## New in 0.6.0
 
 - Serverless: a session joined with its id and token in a fresh function (Vercel, Lambda, Cloud Run) numbers its events from the server's `sdk_next`, so none are lost. Join in each invocation and flush before returning.

package/dist/analysis/detectors.js

@@ -135,27 +135,78 @@ function changedSegment(before, after) {
     return b.length >= a.length ? "none" : a[b.length][0];
 }
 const f = (code, severity, ref, detail) => ({ code, source: "detectors", severity, ref, detail });
+/** spec/findings.md §4: what the person has said in a model request (Anthropic, Chat Completions,
+ * Responses): how many messages, and the newest. Tool results aren't the person speaking. */
+function humanTail(request) {
+    const raw = request?.messages ?? request?.input;
+    const list = Array.isArray(raw)
+        ? raw
+        : typeof raw === "string"
+            ? [{ role: "user", content: raw }]
+            : [];
+    let count = 0;
+    let last = "";
+    for (const m of list) {
+        if (!isObj(m) || m.role !== "user")
+            continue;
+        const c = m.content;
+        if (Array.isArray(c)) {
+            const blocks = c.filter(isObj);
+            if (blocks.some((b) => b.type === "tool_result"))
+                continue;
+            last = blocks
+                .map((b) => (typeof b.text === "string" ? b.text : ""))
+                .filter(Boolean)
+                .join("\n");
+        }
+        else
+            last = typeof c === "string" ? c : "";
+        count++;
+    }
+    return `${count}\n${last}`;
+}
+/** §4: each tool call's turn. A turn starts when the person says something new (a new message,
+ * or different newest words); a client resending the same request is still the same turn. */
+function turnsOf(calls, tools) {
+    const byEnd = new Map();
+    let turn = -1;
+    let previous = null;
+    for (const c of calls) {
+        const tail = humanTail(c.request);
+        if (tail !== previous)
+            turn++;
+        previous = tail;
+        byEnd.set(c.endSeq, Math.max(turn, 0));
+    }
+    return tools.map((t) => byEnd.get(t.seq) ?? 0);
+}
 export function detectors(lines, options) {
     const calls = callsOf(lines, options.bodies);
     const byEnd = [...calls].sort((a, b) => a.endSeq - b.endSeq);
     const tools = toolCallsOf(calls);
     const results = toolResultsOf(calls, lines);
     const keys = tools.map((t) => `${t.tool}\n${t.fp}`);
+    const turn = turnsOf(calls, tools);
     const first = lines[0] ? JSON.parse(lines[0]) : null;
     const open = first?.kind === "session.open" ? first.meta : {};
     const out = [];
-    // D1: the 3rd / 5th occurrence of the same call within the last 20 tool calls.
+    // D1: the 3rd / 5th occurrence of the same call within the last 20 tool calls of one turn: the
+    // same lookup asked for again in a person's next message isn't a loop.
     const d1 = new Set();
     const repeat = [];
+    let turnStart = 0;
     keys.forEach((key, i) => {
-        const count = keys.slice(Math.max(0, i - WINDOW + 1), i + 1).filter((k) => k === key).length;
+        if (i > 0 && turn[i] !== turn[i - 1])
+            turnStart = i;
+        const from = Math.max(turnStart, i - WINDOW + 1);
+        const count = keys.slice(from, i + 1).filter((k) => k === key).length;
         repeat.push(count >= 2);
         for (const [at, severity] of [
             [3, "caution"],
             [5, "warning"],
         ])
-            if (count === at && !d1.has(`${key}\n${at}`)) {
-                d1.add(`${key}\n${at}`);
+            if (count === at && !d1.has(`${turn[i]}\n${key}\n${at}`)) {
+                d1.add(`${turn[i]}\n${key}\n${at}`);
                 const t = tools[i];
                 out.push(f("D1_REPEAT_CALL", severity, { tool: t.tool, fingerprint: t.fp, count: at }, `The same ${t.tool} call ${at} times in the last ${WINDOW} tool calls.`));
             }
@@ -165,7 +216,7 @@ export function detectors(lines, options) {
     for (let i = 0; i < keys.length;) {
         let found = 0;
         for (let n = 2; n <= 4 && !found; n++) {
-            if (i + 3 * n > keys.length)
+            if (i + 3 * n > keys.length || turn[i] !== turn[i + 3 * n - 1])
                 break;
             const gram = keys.slice(i, i + n);
             if (new Set(gram).size === 1)

package/dist/cli.js

@@ -33,7 +33,8 @@ const USAGE = `usage (spec/cli.md):
   blackbox erase <session_id>
   blackbox approvals <session_id>
   blackbox decide <session_id> <approval_id> approve|reject [--note <text>]
-  blackbox drain [--spool-dir <dir>]   (ships what a stopped agent left in its spool)
+  blackbox drain [--spool-dir <dir>] [--close]   (ships what a stopped agent left in its spool;
+                                                 --close then closes each session as abandoned)
   blackbox analyze <bundle.json> [--bodies <dir>] [--prices <file>]
   blackbox verify-certificate <certificate.json> [--did <did:key:…>]
   blackbox investigate <bundle.json> [--bodies <dir>] [--directives <file>] [--identity <file>] [--proofs] [--out <prefix>]
@@ -1102,7 +1103,7 @@ async function tailCommand(rest) {
 }
 /** Audit K5: ships what stopped agents left in the spool (BLACKBOX_URL; no key: the kept tokens). */
 async function drainCommand(rest) {
-    const { flags, positional } = parse(rest, []);
+    const { flags, positional } = parse(rest, ["--close"]);
     const url = process.env.BLACKBOX_URL;
     if (positional.length || !url)
         return usage();
@@ -1110,6 +1111,7 @@ async function drainCommand(rest) {
     const results = await drainSpools({
         url,
         ...(flags["spool-dir"] ? { spoolDir: flags["spool-dir"] } : {}),
+        ...(flags.close ? { close: true } : {}),
     });
     process.stdout.write(`${JSON.stringify({ ok: results.every((r) => r.shipped), sessions: results })}\n`);
     return results.every((r) => r.shipped) ? 0 : 2;

package/dist/session/drain.d.ts

@@ -3,6 +3,8 @@ export interface DrainResult {
     shipped: boolean;
     /** Events the gateway still doesn't have (0 when shipped). */
     left: number;
+    /** With `close`: whether the session was closed. */
+    closed?: boolean;
 }
 /** Only for agents that have stopped: a running agent ships its own spool. Never throws. */
 export declare function drainSpools(options: {
@@ -10,4 +12,6 @@ export declare function drainSpools(options: {
     spoolDir?: string;
     timeoutMs?: number;
     logger?: (message: string) => void;
+    /** LA.5: close each session once shipped, as `abandoned`. */
+    close?: boolean;
 }): Promise<DrainResult[]>;

package/dist/session/drain.js

@@ -1,7 +1,7 @@
 // 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).
+// reads each one and ships what the gateway hasn't acknowledged. With `close` (LA.5) each shipped
+// session is then closed as `abandoned`, with its own token; without it an operator closes it.
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -26,10 +26,18 @@ export async function drainSpools(options) {
         }, id, token);
         const shipped = await s.flush({ timeoutMs: options.timeoutMs ?? 30_000 });
         const left = s.stats.recorded - s.stats.acked;
+        const closed = shipped && options.close
+            ? await s.close("abandoned", "the agent stopped; its spool was drained")
+            : undefined;
         s.stop();
         if (shipped)
             rmSync(join(dir, file), { force: true });
-        out.push({ session_id: id, shipped, left: shipped ? 0 : Math.max(0, left) });
+        out.push({
+            session_id: id,
+            shipped,
+            left: shipped ? 0 : Math.max(0, left),
+            ...(closed === undefined ? {} : { closed }),
+        });
     }
     return out;
 }

package/dist/session/index.d.ts

@@ -167,11 +167,14 @@ export declare class BlackboxSession {
     /** A session that records nothing. `reason`, when opening failed, goes to `stats.lastError` (audit K1). */
     static disabled(options: SessionOptions, reason?: string): BlackboxSession;
     private readonly options;
+    private readonly serverNumbering;
     readonly id: string;
     readonly token: string;
     constructor(options: SessionOptions, id: string, token: string, enabled?: boolean, 
     /** Audit K5: this SDK opened the session, so only it knows the token: keep it by the spool. */
-    keepToken?: boolean);
+    keepToken?: boolean, 
+    /** spec/sdk.md §1: events go unnumbered, each with an event_id; the server numbers them. */
+    serverNumbering?: boolean);
     event(type: string, name?: string, data?: Record<string, unknown>, options?: {
         eventId?: string;
         /** spec/sdk.md §1.1: an image the event's body is (see `screen`). */

package/dist/session/index.js

@@ -59,23 +59,30 @@ export function imageType(image) {
 const LOCK_WAIT_MS = 2_000;
 const LOCK_STALE_MS = 10_000;
 const spoolDirOf = (options) => options.spoolDir ?? process.env.BLACKBOX_SPOOL_DIR ?? join(tmpdir(), "zanii-blackbox-spool");
-/** spec/sdk.md §1: a session joined without its spool (a new process, a serverless function)
- * numbers its events from the server's `next`; from 0, they'd be skipped as already recorded. */
-async function startAtServerNext(options, id, token) {
+/** spec/sdk.md §1: joining a session another process may write to (a serverless function, a
+ * second worker). When the server numbers events itself, this SDK sends them unnumbered with an
+ * event_id, so two writers never collide: true then. Otherwise, without a spool, it numbers from
+ * the server's `next` (from 0, its events would be skipped as already recorded). */
+async function joinSession(options, id, token) {
     const dir = spoolDirOf(options);
-    if (existsSync(join(dir, `${id}.jsonl`)) || existsSync(join(dir, `${id}.ack`)))
-        return;
     try {
         const r = await send("GET", options.url, `/v1/sessions/${id}/state`, token);
-        const n = r.status === 200 ? r.json.sdk_next : undefined;
-        if (typeof n === "number" && Number.isInteger(n) && n > 0) {
+        if (r.status !== 200)
+            return false;
+        const numbering = r.json.sdk_numbering;
+        if (Array.isArray(numbering) && numbering.includes("server"))
+            return true;
+        const n = r.json.sdk_next;
+        const have = existsSync(join(dir, `${id}.jsonl`)) || existsSync(join(dir, `${id}.ack`));
+        if (typeof n === "number" && Number.isInteger(n) && n > 0 && !have) {
             mkdirSync(dir, { recursive: true });
             writeFileSync(join(dir, `${id}.ack`), JSON.stringify({ next: n, offset: 0, gen: 0 }));
         }
     }
     catch {
-        // offline: the spool keeps the events, numbered from 0
+        // offline: the spool keeps the events, numbered locally
     }
+    return false;
 }
 /** Opens (or joins) a session. Never throws: on failure it returns a disabled session and logs why. */
 export async function session(options) {
@@ -114,8 +121,8 @@ export async function session(options) {
             token = String(r.json.token);
             return new BlackboxSession(options, id, token, true, true);
         }
-        await startAtServerNext(options, id, token);
-        return new BlackboxSession(options, id, token);
+        const serverNumbering = await joinSession(options, id, token);
+        return new BlackboxSession(options, id, token, true, false, serverNumbering);
     }
     catch (error) {
         log(`blackbox: session disabled: ${message(error)}`);
@@ -154,11 +161,15 @@ export class BlackboxSession {
         return s;
     }
     options;
+    serverNumbering;
     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) {
+    keepToken = false, 
+    /** spec/sdk.md §1: events go unnumbered, each with an event_id; the server numbers them. */
+    serverNumbering = false) {
+        this.serverNumbering = serverNumbering;
         this.options = options;
         this.id = id;
         this.token = token;
@@ -219,7 +230,11 @@ export class BlackboxSession {
                         sdk_seq: this.nextSeq,
                         type,
                         ...(name === undefined ? {} : { name }),
-                        ...(eventId === undefined ? {} : { event_id: eventId }),
+                        ...(eventId !== undefined
+                            ? { event_id: eventId }
+                            : this.serverNumbering
+                                ? { event_id: `evt_${randomUUID().replaceAll("-", "")}` } // a resend is harmless
+                                : {}),
                         ts: new Date().toISOString(),
                         ...(kept === undefined ? {} : { data: kept }),
                         ...(options.attachment
@@ -692,18 +707,34 @@ export class BlackboxSession {
         });
         if (lines.length === 0)
             return;
-        const events = lines.map((l) => JSON.parse(l.text));
+        let events = lines.map((l) => JSON.parse(l.text));
+        // spec/sdk.md §1: lines with an event_id go unnumbered; a line without one (left in the spool
+        // by a run that numbered its own) goes numbered, as it was written. Never mixed in one batch.
+        const withId = (e) => e.event_id !== undefined;
+        const unnumbered = this.serverNumbering && withId(events[0]);
+        const cut = events.findIndex((e) => withId(e) !== withId(events[0]));
+        if (cut > 0) {
+            lines.splice(cut);
+            events = events.slice(0, cut);
+        }
+        const sent = unnumbered ? events.map(({ sdk_seq: _, ...rest }) => rest) : events;
         const r = await post(this.options.url, `/v1/sessions/${this.id}/sdk-events`, this.token, {
-            events,
+            events: sent,
         });
         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) {
+            const fresh = (this.ack.gen ?? 0) === from.gen && this.ack.offset === from.offset;
+            if (fresh && unnumbered && r.status === 200) {
+                // spec/sdk.md §1: the server numbered them; every line sent is recorded (or was)
+                const done = Math.max(...events.map((e) => e.sdk_seq)) + 1;
+                const offset = from.offset + lines.reduce((n, l) => n + l.bytes, 0);
+                this.ack = { next: done, offset, gen: from.gen };
+                writeFileSync(this.ackFile, JSON.stringify(this.ack));
+            }
+            else if (fresh && !unnumbered && 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())

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.8.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The SDK version, on its own so the CLI can print it without loading the whole SDK.
-export const VERSION = "0.6.0";
+export const VERSION = "0.8.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The flight recorder for AI agents: sessions, a zero-loss spool, framework hooks, approvals, and offline verification of the gateway's hash-chained record.",
   "keywords": [
     "ai-agents",