@zanii/blackbox 0.5.0 → 0.7.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.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.
+- Fewer false alarms: an ISO date-time (`2026-10-03T09:30:00+04:00`) in a tool's arguments is a date, not an invented number, and an MCP call carrying out the model's own tool call isn't flagged a second time for the same value.
+
 ## New in 0.5.0
 
 - Held streams: open a session with `holdStreams: true` (or set `BLACKBOX_HOLD_STREAMS=all` on the gateway) and a risky streamed answer waits for a person, as a non-streamed one does. The client gets keep-alives, then the whole stream, or one error in the provider's own format.

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/analysis/hallucination.js

@@ -114,6 +114,7 @@ export function normaliseValue(s) {
         .replace(/[\s\-_./()+:,]/g, "");
 }
 const DATE = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$|^[0-9]{2}-[0-9]{2}-[0-9]{4}$/;
+const DATE_TIME = /(?<![0-9])[0-9]{4}-[0-9]{2}-[0-9]{2}(?:[T ][0-9]{2}:[0-9]{2}(?::[0-9]{2}(?:\.[0-9]+)?)?(?:Z|[+-][0-9]{2}:?[0-9]{2})?)?(?![0-9])/g;
 const VALUE_KINDS = [
     ["email", /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g],
     ["iban", /\b[A-Z]{2}[0-9]{2}(?:[ ]?[A-Z0-9]){11,30}\b/g],
@@ -124,6 +125,12 @@ const VALUE_KINDS = [
 /** The identifying values in a string (Western digits) and where they are, skipping `taken` spans. */
 export function identifierSpans(s, taken = []) {
     const out = [];
+    // a date or an ISO 8601 date-time (2026-10-03T00:00:00+04:00) is a date, not part of a number
+    for (const m of s.matchAll(DATE_TIME)) {
+        const at = m.index ?? 0;
+        if (!taken.some(([a, b]) => at < b && at + m[0].length > a))
+            taken.push([at, at + m[0].length]);
+    }
     for (const [kind, re] of VALUE_KINDS)
         for (const m of s.matchAll(re)) {
             const at = m.index ?? 0;
@@ -245,9 +252,14 @@ export function toolHallucinations(lines, bodies) {
     let request = "";
     let toolText = "";
     let sawModel = false;
-    for (const t of modelCalls)
+    // §8: what the model asked for is where an agent's MCP call got its values; the model's call is
+    // checked above, so the MCP call it led to isn't flagged a second time for the same act
+    const modelArgs = new Map();
+    for (const t of modelCalls) {
         if (!called.has(t.tool))
             called.set(t.tool, t.seq);
+        modelArgs.set(t.seq, `${modelArgs.get(t.seq) ?? ""}\n${normaliseValue(canonical(t.args ?? {}))}`);
+    }
     for (const e of events) {
         const m = e.meta;
         const text = () => {
@@ -258,6 +270,9 @@ export function toolHallucinations(lines, bodies) {
             sawModel = true;
             request = normaliseValue(text());
         }
+        else if (e.kind === "llm.response" && modelArgs.has(e.seq)) {
+            toolText += modelArgs.get(e.seq);
+        }
         else if (e.kind === "tool.result" && typeof m.server === "string" && isObj(m.tool_defs)) {
             const tools = rpcOf(bodies(e.body_hash))?.result;
             const schemas = new Map();

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

@@ -58,6 +58,32 @@ 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: 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);
+    try {
+        const r = await send("GET", options.url, `/v1/sessions/${id}/state`, token);
+        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 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) {
     const log = options.logger ?? (() => { });
@@ -95,7 +121,8 @@ export async function session(options) {
             token = String(r.json.token);
             return new BlackboxSession(options, id, token, true, true);
         }
-        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)}`);
@@ -134,16 +161,20 @@ 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;
         this.enabled = enabled;
-        const dir = options.spoolDir ?? process.env.BLACKBOX_SPOOL_DIR ?? join(tmpdir(), "zanii-blackbox-spool");
+        const dir = spoolDirOf(options);
         this.spool = join(dir, `${id}.jsonl`);
         this.ackFile = join(dir, `${id}.ack`);
         if (!enabled)
@@ -199,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
@@ -672,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.5.0";
+export declare const VERSION = "0.7.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.5.0";
+export const VERSION = "0.7.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.5.0",
+  "version": "0.7.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",