@zanii/blackbox 0.4.0 → 0.6.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.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.
+- `session.checkAnswer(seq?)`: what in an answer would hold it (`{seq, risks, hold}`), for an app that streams by itself.
+
 ## New in 0.4.0
 
 - Hallucination controls: the checks above, reference packs, answer credentials (`answerClaims`, `answerCredential`, `verifyAnswerCredential`), `session.retrieved()`, accuracy from people's labels (`detectorAccuracy`, Wilson bounds), the grounding and judge contracts, `answerRisk` for held answers.

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/index.d.ts

@@ -61,7 +61,7 @@ export { cassette, requestKey, type Take } from "./replay/index.ts";
 export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.ts";
 export { checkSearch, type SearchMatch, type SearchQuery, searchEvents } from "./search/index.ts";
 export { type DrainResult, drainSpools } from "./session/drain.ts";
-export { BlackboxSession, checkEgress, type EgressCheck, type FlightPlan, type LlmCallIds, type SessionError, type SessionOptions, type SessionState, type SessionStats, session, stableEventId, } from "./session/index.ts";
+export { type AnswerCheck, BlackboxSession, checkEgress, type EgressCheck, type FlightPlan, type LlmCallIds, type SessionError, type SessionOptions, type SessionState, type SessionStats, session, stableEventId, } from "./session/index.ts";
 export { assembleSla, assessCompliance, buildSlaBody, signSla, slaHash, verifySla, } from "./sla/index.ts";
 export { assembleSuccession, buildSuccessionBody, type Succession, type SuccessionBody, type SuccessionReason, signSuccession, successionHash, verifyLineage, verifySuccession, } from "./succession/index.ts";
 export { type TimestampReport, timestampRequest, verifyTimestamp, } from "./timestamp/index.ts";

package/dist/session/index.d.ts

@@ -36,6 +36,9 @@ export interface SessionOptions {
     authority?: "agent" | "supervised";
     /** spec/api.md: where it runs (`production`, `staging`, …); policy rules can match it. */
     environment?: string;
+    /** spec/findings.md §13.1: hold this session's streamed answers until they're checked (`true`),
+     * or never (`false`); unset follows the server's BLACKBOX_HOLD_STREAMS. */
+    holdStreams?: boolean;
     /** spec/preflight.md: the equipment the run needs. A no-go returns a disabled session (and
      * `stats.lastError` says why); optional items that are down show in `state().degraded`. */
     preflight?: {
@@ -98,6 +101,16 @@ export interface LandingResult {
     /** How many more tries `maxAttempts` allows; at 0, stop and report. */
     attemptsLeft: number;
 }
+/** spec/findings.md §13.1: what would hold an answer, from `checkAnswer()`. */
+export interface AnswerCheck {
+    seq: number;
+    risks: Array<{
+        index: number;
+        kind: string;
+        status: "contradicted" | "ungrounded";
+    }>;
+    hold: boolean;
+}
 export interface SessionState {
     session_id: string;
     closed: boolean;
@@ -333,6 +346,10 @@ export declare class BlackboxSession {
     /** 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. */
     state(): Promise<SessionState | null>;
+    /** spec/findings.md §13.1: what in an answer (the latest, or the one at `seq`) would hold it,
+     * for an app that streams the answer by itself: `{seq, risks, hold}`. `hold` says whether the
+     * server would hold it. `null` when there's no answer yet or the gateway can't be asked. */
+    checkAnswer(seq?: number): Promise<AnswerCheck | 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. */

package/dist/session/index.js

@@ -58,6 +58,25 @@ 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) {
+    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) {
+            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
+    }
+}
 /** 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 ?? (() => { });
@@ -84,6 +103,7 @@ export async function session(options) {
                 ...(o.tenant ? { tenant: o.tenant } : {}),
                 ...(o.authority ? { authority: o.authority } : {}),
                 ...(o.environment ? { environment: o.environment } : {}),
+                ...(o.holdStreams !== undefined ? { hold_streams: o.holdStreams } : {}),
                 ...(o.preflight ? { preflight: await withEgress(o.preflight) } : {}),
                 ...(o.drill ? { drill: o.drill } : {}),
                 sdk: true, // this SDK will report the session's model calls (L2.3.2)
@@ -94,6 +114,7 @@ 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);
     }
     catch (error) {
@@ -142,7 +163,7 @@ export class BlackboxSession {
         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)
@@ -521,6 +542,25 @@ export class BlackboxSession {
         }
         return null;
     }
+    /** spec/findings.md §13.1: what in an answer (the latest, or the one at `seq`) would hold it,
+     * for an app that streams the answer by itself: `{seq, risks, hold}`. `hold` says whether the
+     * server would hold it. `null` when there's no answer yet or the gateway can't be asked. */
+    async checkAnswer(seq) {
+        if (!this.enabled)
+            return null;
+        const at = seq === undefined ? "latest" : String(seq);
+        try {
+            const r = await send("GET", this.options.url, `/v1/sessions/${this.id}/answers/${at}/risk`, this.token);
+            if (r.status === 200)
+                return r.json;
+            if (r.status !== 404)
+                this.fail("rejected", `checking the answer: the gateway answered ${r.status}`);
+        }
+        catch (error) {
+            this.fail("network", `checking the answer: ${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. */

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.6.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.4.0";
+export const VERSION = "0.6.0";

package/package.json

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