@zanii/blackbox 0.4.0 → 0.5.0

package/README.md

@@ -83,6 +83,11 @@ 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.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/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

@@ -84,6 +84,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)
@@ -521,6 +522,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.5.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.5.0";

package/package.json

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