@zanii/blackbox 0.21.2 → 0.23.0

package/dist/policy/index.js

@@ -1,7 +1,7 @@
 // Tool policy (spec/policy.md): rules checked in order, the first match decides. Mirrors policy.py.
 import { createHash } from "node:crypto";
 import { hasEvidence } from "../data/index.js";
-import { callsOf } from "../reconcile/record.js";
+import { callsOf, envelopesOf } from "../reconcile/record.js";
 import { canonical } from "../reconcile/shared.js";
 import { checkCompensations } from "../undo/index.js";
 /** spec/api.md: a session's environment, e.g. `production`, `staging`, `dev`. */
@@ -276,8 +276,7 @@ function unproven(lines, bodies, compiled) {
         ref: { seq, rule: rule.id, tool },
         detail: `${tool} ran under policy ${rule.id}, and its result carries no witness${rule.field ? ` or ${rule.field}` : ""}.`,
     });
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         const m = e.meta;
         if (e.kind === "tool.call" && typeof m.tool === "string" && m.via !== "broker") {
             if (m.policy?.action === "deny")
@@ -325,10 +324,10 @@ function unproven(lines, bodies, compiled) {
  * spec/policy.md §2 as findings: POLICY_DENIED for MCP calls the gateway refused (tool.call meta.policy),
  * POLICY_VIOLATION for tools a model response asked for that a deny rule matches.
  */
+const SERVER_REQUEST_KINDS = new Set(["tool.sampling", "tool.elicitation", "tool.roots"]);
 export function policyFindings(lines, bodies, compiled) {
     const out = [];
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         const p = e.meta.policy;
         if (e.kind === "tool.call" && p?.action === "deny" && typeof p.rule === "string")
             out.push({
@@ -338,6 +337,15 @@ export function policyFindings(lines, bodies, compiled) {
                 ref: { rule: p.rule, seq: e.seq },
                 detail: `The gateway refused ${String(e.meta.tool ?? "a tool call")} (policy ${p.rule}).`,
             });
+        // spec/mcp.md §6: a server's request (sampling, elicitation, roots) the gateway refused
+        if (SERVER_REQUEST_KINDS.has(e.kind) && p?.action === "deny" && typeof p.rule === "string")
+            out.push({
+                code: "POLICY_DENIED",
+                source: "policy",
+                severity: "advisory",
+                ref: { rule: p.rule, seq: e.seq },
+                detail: `The gateway refused the MCP server's ${String(e.meta.method ?? "request")} (policy ${p.rule}).`,
+            });
         const hits = e.kind === "tool.call" ? e.meta.policy_audit : undefined;
         for (const a of Array.isArray(hits) ? hits : [])
             if (typeof a.rule === "string" && a.would !== "allow")

package/dist/realtime/index.d.ts

@@ -0,0 +1,33 @@
+import type { Json } from "../verify/envelope.ts";
+type Meta = {
+    [key: string]: Json;
+};
+type Obj = Record<string, unknown>;
+/** The realtime protocols: OpenAI Realtime (and Azure's), Gemini Live (and Vertex's), and Bedrock's
+ *  bidirectional stream (Nova Sonic, spec/providers.md §8). */
+export type RealtimeFormat = "openai" | "gemini" | "bedrock";
+export interface RealtimeFrame {
+    /** The event's `meta` (spec/providers.md §7), without `request_seq`. */
+    meta: Meta;
+    /** Whether the frame's bytes are kept as the event's body. A frame carrying audio, an image or
+     *  other non-JSON bytes is recorded by size and hash only. */
+    keep: boolean;
+    /** The session's model after this frame. */
+    model: string | null;
+}
+/**
+ * One WebSocket frame of a realtime session (spec/providers.md §7). `binary` says the frame was a
+ * binary one (Gemini Live sends its JSON that way); `model` is the session's model so far.
+ */
+export declare function realtimeFrame(format: RealtimeFormat, frame: Uint8Array, binary: boolean, model: string | null): RealtimeFrame;
+/** The model a realtime connection names in its URL: OpenAI's `?model=`, Azure's `?deployment=`. */
+export declare function realtimeModelFromPath(path: string): string | null;
+/** A realtime session's usage reports (spec/providers.md §7), in record order, each with the
+ *  configured provider its connection went to: what the cost report and the spend check price. */
+export declare function realtimeUsage(lines: readonly string[]): Array<{
+    seq: number;
+    model: string | null;
+    usage: Obj;
+    provider: string | null;
+}>;
+export {};

package/dist/realtime/index.js

@@ -0,0 +1,204 @@
+// Realtime and voice sessions over WebSocket (spec/providers.md §7): what each frame is recorded
+// with. Pure functions, pinned by spec/vectors/realtime.json. Mirrors
+// sdks/python/src/zanii_blackbox/realtime.py.
+import { createHash } from "node:crypto";
+import { envelopesOf } from "../reconcile/record.js";
+// The top-level keys of a Gemini Live message, client and server, in the order they name a type.
+const GEMINI_TYPES = [
+    "setup",
+    "clientContent",
+    "realtimeInput",
+    "toolResponse",
+    "setupComplete",
+    "serverContent",
+    "toolCall",
+    "toolCallCancellation",
+    "goAway",
+    "sessionResumptionUpdate",
+    "usageMetadata",
+];
+const B64 = /^[A-Za-z0-9+/]*={0,2}$/;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max ? v : undefined;
+/** The bytes a base64 media string stands for: decoded when it is valid base64, else its text. */
+function mediaBytes(s) {
+    return s.length % 4 === 0 && B64.test(s) ? Buffer.from(s, "base64") : Buffer.from(s, "utf8");
+}
+/** Every media string in a message, in document order: OpenAI's `audio` fields and the `delta` of
+ *  an `*audio.delta` event; Gemini's blobs (an object with string `data` and `mimeType`). */
+function mediaOf(format, message) {
+    const found = [];
+    if (format === "bedrock") {
+        // spec/providers.md §8: Nova Sonic's audioInput / audioOutput carry base64 `content`
+        if (isObj(message.event))
+            for (const [name, body] of Object.entries(message.event))
+                if (name.startsWith("audio") && isObj(body) && typeof body.content === "string")
+                    found.push(body.content);
+        return found;
+    }
+    const walk = (v, depth) => {
+        if (depth > 8)
+            return;
+        if (Array.isArray(v)) {
+            for (const item of v)
+                walk(item, depth + 1);
+            return;
+        }
+        if (!isObj(v))
+            return;
+        if (format === "gemini" && typeof v.data === "string" && typeof v.mimeType === "string") {
+            found.push(v.data);
+            return;
+        }
+        for (const [k, x] of Object.entries(v)) {
+            if (format === "openai" && k === "audio" && typeof x === "string")
+                found.push(x);
+            else
+                walk(x, depth + 1);
+        }
+    };
+    if (format === "openai" &&
+        typeof message.type === "string" &&
+        message.type.endsWith("audio.delta") &&
+        typeof message.delta === "string")
+        found.push(message.delta);
+    walk(message, 0);
+    return found;
+}
+/** Flattened integer usage (spec/api.md §3); Gemini's per-modality lists become `<name>_AUDIO`. */
+function flatUsage(usage) {
+    if (!isObj(usage))
+        return undefined;
+    const out = {};
+    const walk = (o, prefix) => {
+        for (const [k, v] of Object.entries(o)) {
+            if (typeof v === "number" && Number.isSafeInteger(v))
+                out[prefix + k] = v;
+            else if (isObj(v))
+                walk(v, `${prefix}${k}_`);
+            else if (Array.isArray(v))
+                for (const item of v)
+                    if (isObj(item) &&
+                        typeof item.modality === "string" &&
+                        /^[A-Z_]{1,32}$/.test(item.modality) &&
+                        Number.isSafeInteger(item.tokenCount))
+                        out[`${prefix}${k}_${item.modality}`] = item.tokenCount;
+        }
+    };
+    walk(usage, "");
+    return Object.keys(out).length ? out : undefined;
+}
+/** A model name as priced: Gemini's `models/<id>` (or Vertex's full resource name) as `<id>`. */
+function modelName(v) {
+    const s = str(v, 256);
+    if (s === undefined)
+        return undefined;
+    const i = s.lastIndexOf("models/");
+    return i === -1 ? s : str(s.slice(i + "models/".length), 256);
+}
+/**
+ * One WebSocket frame of a realtime session (spec/providers.md §7). `binary` says the frame was a
+ * binary one (Gemini Live sends its JSON that way); `model` is the session's model so far.
+ */
+export function realtimeFrame(format, frame, binary, model) {
+    const bytes = Buffer.from(frame);
+    const meta = { bytes: bytes.length };
+    if (binary)
+        meta.binary = true;
+    let message;
+    try {
+        message = JSON.parse(bytes.toString("utf8"));
+    }
+    catch { }
+    if (!isObj(message)) {
+        if (!binary)
+            return { meta, keep: true, model };
+        meta.media = {
+            bytes: bytes.length,
+            sha256: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+        };
+        return { meta, keep: false, model };
+    }
+    let next = model;
+    if (format === "openai") {
+        const type = str(message.type, 64);
+        if (type)
+            meta.type = type;
+        if (type === "session.created" || type === "session.updated")
+            next = modelName(isObj(message.session) ? message.session.model : undefined) ?? next;
+        if (type === "response.done" && isObj(message.response)) {
+            const r = message.response;
+            const id = str(r.id, 256);
+            if (id)
+                meta.response_id = id;
+            const status = str(r.status, 64);
+            if (status)
+                meta.response_status = status;
+            const usage = flatUsage(r.usage);
+            if (usage)
+                meta.usage = usage;
+        }
+    }
+    else if (format === "bedrock") {
+        // spec/providers.md §8: {"event": {"<name>": {...}}}; usageEvent's delta is this report's
+        if (isObj(message.event)) {
+            const type = str(Object.keys(message.event)[0], 64);
+            if (type)
+                meta.type = type;
+            const u = message.event.usageEvent;
+            const details = isObj(u) ? u.details : undefined;
+            const usage = flatUsage(isObj(details) ? details.delta : undefined);
+            if (usage)
+                meta.usage = usage;
+        }
+    }
+    else {
+        const type = GEMINI_TYPES.find((k) => k in message);
+        if (type)
+            meta.type = type;
+        if (isObj(message.setup))
+            next = modelName(message.setup.model) ?? next;
+        const usage = flatUsage(message.usageMetadata);
+        if (usage)
+            meta.usage = usage;
+    }
+    if (meta.usage !== undefined && next !== null)
+        meta.model = next;
+    const media = mediaOf(format, message);
+    if (media.length === 0)
+        return { meta, keep: true, model: next };
+    const hash = createHash("sha256");
+    let size = 0;
+    for (const m of media) {
+        const b = mediaBytes(m);
+        size += b.length;
+        hash.update(b);
+    }
+    meta.media = { bytes: size, sha256: `sha256:${hash.digest("hex")}` };
+    return { meta, keep: false, model: next };
+}
+/** The model a realtime connection names in its URL: OpenAI's `?model=`, Azure's `?deployment=`. */
+export function realtimeModelFromPath(path) {
+    const q = new URLSearchParams(path.split("?")[1] ?? "");
+    const m = q.get("model") ?? q.get("deployment");
+    return m !== null && m.length > 0 && m.length <= 256 ? m : null;
+}
+/** A realtime session's usage reports (spec/providers.md §7), in record order, each with the
+ *  configured provider its connection went to: what the cost report and the spend check price. */
+export function realtimeUsage(lines) {
+    const providers = new Map();
+    const out = [];
+    for (const e of envelopesOf(lines)) {
+        if (e.kind === "llm.request" && typeof e.meta.provider === "string")
+            providers.set(e.seq, e.meta.provider);
+        if (e.kind !== "llm.realtime.server" || !isObj(e.meta.usage))
+            continue;
+        out.push({
+            seq: e.seq,
+            model: typeof e.meta.model === "string" ? e.meta.model : null,
+            usage: e.meta.usage,
+            provider: providers.get(e.meta.request_seq) ?? null,
+        });
+    }
+    return out;
+}

package/dist/reconcile/record.d.ts

@@ -1,3 +1,4 @@
+import type { Envelope } from "../verify/index.ts";
 export type Obj = Record<string, unknown>;
 export interface Block {
     type: string;
@@ -35,9 +36,22 @@ export interface Call {
     blocks: Map<number, Block>;
     /** OpenAI Responses output items, in order. */
     items: Obj[];
+    /** A Chat Completions message's own reasoning (`reasoning_content` or `reasoning`), when given. */
+    reasoning?: string;
 }
 export type Bodies = (hash: string) => Uint8Array | undefined;
 export declare function parseJson(text: string): unknown;
+/** Marks an append-only array of lines as one record that only grows (an analysis checkpoint). */
+export declare function trackRecord(lines: readonly string[]): void;
+/** The record's events, parsed: once per line for a tracked record (frozen), else now. */
+export declare function envelopesOf<T = Envelope>(lines: readonly string[]): readonly T[];
+/** A named fold's state on a tracked record (created by `init`); undefined for an untracked one. */
+export declare function foldState<T>(lines: readonly string[], name: string, init: () => T): T | undefined;
+/**
+ * Findings that each depend on one event alone (and the bodies): on a tracked record each event is
+ * judged once, and the findings so far are kept; otherwise every event is judged now.
+ */
+export declare function perEvent<T>(lines: readonly string[], name: string, bodies: Bodies, judge: (e: Envelope) => T[]): T[];
 /** The calls in a verified record, in request order. */
 export declare function callsOf(lines: readonly string[], bodies: Bodies): Call[];
 export interface Receipt {

package/dist/reconcile/record.js

@@ -10,82 +10,131 @@ export function parseJson(text) {
         return undefined;
     }
 }
+const folds = new WeakMap();
+/** Marks an append-only array of lines as one record that only grows (an analysis checkpoint). */
+export function trackRecord(lines) {
+    if (!folds.has(lines))
+        folds.set(lines, { events: [], more: new Map() });
+}
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreeze(v);
+    }
+    return value;
+}
+/** The record's events, parsed: once per line for a tracked record (frozen), else now. */
+export function envelopesOf(lines) {
+    const f = folds.get(lines);
+    if (!f)
+        return lines.map((l) => JSON.parse(l));
+    while (f.events.length < lines.length)
+        f.events.push(deepFreeze(JSON.parse(lines[f.events.length])));
+    return f.events;
+}
+/** A named fold's state on a tracked record (created by `init`); undefined for an untracked one. */
+export function foldState(lines, name, init) {
+    const f = folds.get(lines);
+    if (!f)
+        return undefined;
+    if (!f.more.has(name))
+        f.more.set(name, init());
+    return f.more.get(name);
+}
+/**
+ * Findings that each depend on one event alone (and the bodies): on a tracked record each event is
+ * judged once, and the findings so far are kept; otherwise every event is judged now.
+ */
+export function perEvent(lines, name, bodies, judge) {
+    const events = envelopesOf(lines);
+    const s = foldState(lines, name, () => ({ bodies, done: 0, out: [] }));
+    if (!s || s.bodies !== bodies)
+        return events.flatMap(judge);
+    for (; s.done < events.length; s.done++)
+        s.out.push(...judge(events[s.done]));
+    return [...s.out];
+}
 /** The calls in a verified record, in request order. */
 export function callsOf(lines, bodies) {
-    const events = lines.map((l) => JSON.parse(l));
-    const calls = new Map();
-    const chunks = new Map();
-    // ponytail: records from before request_seq existed (pre-Stage 2.1) attach to the latest request,
-    // which is right unless streams interleaved.
-    let latest = null;
+    const events = envelopesOf(lines);
+    const f = folds.get(lines);
+    let s = f?.calls?.bodies === bodies ? f.calls.state : undefined;
+    if (!s) {
+        s = { done: 0, calls: new Map(), chunks: new Map(), latest: null };
+        if (f)
+            f.calls = { bodies, state: s };
+    }
+    for (; s.done < events.length; s.done++)
+        stepCalls(s, events[s.done], bodies);
+    return [...s.calls.values()];
+}
+function stepCalls(s, e, bodies) {
+    const { calls, chunks } = s;
     const text = (hash) => {
         const b = bodies(hash);
         return b === undefined ? "" : decoder.decode(b);
     };
-    for (const e of events) {
-        const meta = e.meta;
-        if (e.kind === "llm.request") {
-            latest = e.seq;
-            const request = parseJson(text(e.body_hash));
-            calls.set(e.seq, {
-                requestSeq: e.seq,
-                endSeq: e.seq,
-                path: typeof meta.path === "string" ? meta.path : "",
-                headers: isObj(meta.headers) ? meta.headers : {},
-                request: isObj(request) ? request : null,
-                complete: false,
-                status: null,
-                redacted: meta.redacted !== undefined,
-                requestRedacted: meta.redacted !== undefined,
-                messageId: null,
-                responseId: null,
-                model: null,
-                usage: null,
-                provider: typeof meta.provider === "string" ? meta.provider : null,
-                serviceTier: null,
-                reportedMicroUsd: null,
-                blocks: new Map(),
-                items: [],
-            });
-            chunks.set(e.seq, []);
-            continue;
-        }
-        if (e.kind !== "llm.chunk" && e.kind !== "llm.response" && e.kind !== "llm.incomplete")
-            continue;
-        const owner = typeof meta.request_seq === "number" ? meta.request_seq : latest;
-        const call = owner === null ? undefined : calls.get(owner);
-        if (!call)
-            continue;
-        if (meta.redacted !== undefined)
-            call.redacted = true;
-        if (e.kind === "llm.chunk") {
-            chunks.get(call.requestSeq)?.push(text(e.body_hash));
-            continue;
-        }
-        call.endSeq = e.seq;
-        call.complete = e.kind === "llm.response";
-        call.status = typeof meta.status === "number" ? meta.status : null;
-        if (typeof meta.message_id === "string")
-            call.messageId = meta.message_id;
-        if (typeof meta.response_id === "string")
-            call.responseId = meta.response_id;
-        if (typeof meta.model === "string")
-            call.model = meta.model;
-        if (isObj(meta.usage))
-            call.usage = meta.usage;
-        if (typeof meta.service_tier === "string")
-            call.serviceTier = meta.service_tier;
-        if (Number.isSafeInteger(meta.reported_cost_micro_usd))
-            call.reportedMicroUsd = meta.reported_cost_micro_usd;
-        rebuild(call, (chunks.get(call.requestSeq) ?? []).join(""));
+    const meta = e.meta;
+    if (e.kind === "llm.request") {
+        s.latest = e.seq;
+        const request = parseJson(text(e.body_hash));
+        calls.set(e.seq, {
+            requestSeq: e.seq,
+            endSeq: e.seq,
+            path: typeof meta.path === "string" ? meta.path : "",
+            headers: isObj(meta.headers) ? meta.headers : {},
+            request: isObj(request) ? request : null,
+            complete: false,
+            status: null,
+            redacted: meta.redacted !== undefined,
+            requestRedacted: meta.redacted !== undefined,
+            messageId: null,
+            responseId: null,
+            model: null,
+            usage: null,
+            provider: typeof meta.provider === "string" ? meta.provider : null,
+            serviceTier: null,
+            reportedMicroUsd: null,
+            blocks: new Map(),
+            items: [],
+        });
+        chunks.set(e.seq, []);
+        return;
     }
-    return [...calls.values()];
+    if (e.kind !== "llm.chunk" && e.kind !== "llm.response" && e.kind !== "llm.incomplete")
+        return;
+    const owner = typeof meta.request_seq === "number" ? meta.request_seq : s.latest;
+    const call = owner === null ? undefined : calls.get(owner);
+    if (!call)
+        return;
+    if (meta.redacted !== undefined)
+        call.redacted = true;
+    if (e.kind === "llm.chunk") {
+        chunks.get(call.requestSeq)?.push(text(e.body_hash));
+        return;
+    }
+    call.endSeq = e.seq;
+    call.complete = e.kind === "llm.response";
+    call.status = typeof meta.status === "number" ? meta.status : null;
+    if (typeof meta.message_id === "string")
+        call.messageId = meta.message_id;
+    if (typeof meta.response_id === "string")
+        call.responseId = meta.response_id;
+    if (typeof meta.model === "string")
+        call.model = meta.model;
+    if (isObj(meta.usage))
+        call.usage = meta.usage;
+    if (typeof meta.service_tier === "string")
+        call.serviceTier = meta.service_tier;
+    if (Number.isSafeInteger(meta.reported_cost_micro_usd))
+        call.reportedMicroUsd = meta.reported_cost_micro_usd;
+    rebuild(call, (chunks.get(call.requestSeq) ?? []).join(""));
 }
 /** The workspace receipts in a record (spec/reconcile.md §7), in seq order. */
 export function receiptsOf(lines) {
     const out = [];
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         if (e.kind !== "workspace.receipt")
             continue;
         const m = e.meta;
@@ -125,9 +174,13 @@ function rebuild(call, body) {
             if (typeof json.id === "string")
                 call.messageId ??= json.id;
             const message = json.choices.find(isObj)?.message;
-            if (isObj(message))
+            if (isObj(message)) {
                 chatBlocks(call, message.content, message.tool_calls);
+                chatReasoning(call, message);
+            }
         }
+        if (Array.isArray(json.candidates))
+            geminiParts(call, json);
         return;
     }
     const partial = new Map();
@@ -141,6 +194,10 @@ function rebuild(call, body) {
         if (!isObj(event))
             continue;
         const type = event.type;
+        if (Array.isArray(event.candidates)) {
+            geminiParts(call, event);
+            continue;
+        }
         if (Array.isArray(event.choices)) {
             if (typeof event.id === "string")
                 call.messageId ??= event.id;
@@ -149,6 +206,7 @@ function rebuild(call, body) {
                 continue;
             if (typeof delta.content === "string")
                 chatText = (chatText ?? "") + delta.content;
+            chatReasoning(call, delta);
             for (const tc of Array.isArray(delta.tool_calls) ? delta.tool_calls.filter(isObj) : []) {
                 const k = typeof tc.index === "number" ? tc.index : 0;
                 const acc = chatCalls.get(k) ?? { arguments: "" };
@@ -210,6 +268,43 @@ function rebuild(call, body) {
  * its text and tool calls: a text block (when there's text), then one tool_use per tool call, its
  * arguments parsed from their JSON string.
  */
+/** spec/reconcile.md §2: a Chat Completions message's (or a stream delta's) own reasoning. */
+function chatReasoning(call, m) {
+    for (const key of ["reasoning_content", "reasoning"]) {
+        const v = m[key];
+        if (typeof v === "string" && v) {
+            call.reasoning = (call.reasoning ?? "") + v;
+            return;
+        }
+    }
+}
+/** spec/reconcile.md §2: Gemini's parts (a whole answer, or one streamed chunk) as blocks: its
+ *  thoughts as thinking, its text as text, each functionCall as a tool_use. */
+function geminiParts(call, event) {
+    if (typeof event.responseId === "string")
+        call.messageId ??= event.responseId;
+    const first = event.candidates.find(isObj) ?? {};
+    const content = first.content;
+    const parts = isObj(content) && Array.isArray(content.parts) ? content.parts.filter(isObj) : [];
+    for (const p of parts) {
+        const fc = p.functionCall;
+        if (isObj(fc) && typeof fc.name === "string") {
+            const block = { type: "tool_use", name: fc.name, input: fc.args ?? {} };
+            if (typeof fc.id === "string")
+                block.id = fc.id;
+            call.blocks.set(call.blocks.size, block);
+            continue;
+        }
+        if (typeof p.text !== "string")
+            continue;
+        const kind = p.thought === true ? "thinking" : "text";
+        const last = call.blocks.get(call.blocks.size - 1);
+        if (last && last.type === kind)
+            last[kind] = (last[kind] ?? "") + p.text; // a streamed chunk
+        else
+            call.blocks.set(call.blocks.size, { type: kind, [kind]: p.text });
+    }
+}
 function chatBlocks(call, content, toolCalls) {
     let i = 0;
     if (typeof content === "string" && content !== "")

package/dist/session/index.d.ts

@@ -1,5 +1,6 @@
 import { type Lessons } from "../analysis/learning.ts";
 import { type Attestation } from "../attest/index.ts";
+import { type ClearanceAnswer, type Notam, type Procedure } from "../aviation/index.ts";
 import { buildPayment, type screenCounterparty } from "../finance/index.ts";
 export interface SessionOptions {
     /** The gateway, e.g. http://127.0.0.1:8787 */
@@ -314,6 +315,27 @@ export declare class BlackboxSession {
     }): void;
     /** The agent reports something it almost got wrong (spec/fleet.md §3): a NEAR_MISS finding. */
     nearMiss(description: string): void;
+    /** spec/aviation.md §6: a voluntary, non-punitive safety report ("I nearly..."): a
+     * SAFETY_REPORT finding that never blocks. `category`: near_miss, hazard, procedure, tooling or
+     * other (the default). */
+    safetyReport(description: string, options?: {
+        category?: string;
+    }): void;
+    /** spec/aviation.md §10: the agent declares distress (it's stuck, unsure, or about to do harm): a
+     * MAYDAY warning, routed to a person at once. Shipped now, not with the next batch. */
+    mayday(reason: string, options?: {
+        kind?: "stuck" | "unsure" | "harm";
+    }): void;
+    /** spec/aviation.md §10: urgency short of distress: a PAN_PAN caution, shipped now. */
+    panPan(reason: string, options?: {
+        kind?: "stuck" | "unsure" | "harm";
+    }): void;
+    private distress;
+    /** spec/aviation.md §8: the agent reports running a QRH procedure (`started`, `completed`). */
+    procedure(code: string, status: "started" | "completed"): void;
+    /** spec/aviation.md §9: the run passes its commit point (V1): past it, with the gateway's
+     * BLACKBOX_COMMIT_POINT on, a non-critical finding doesn't stop it. Only the first counts. */
+    commitPoint(note?: string): void;
     /** spec/attestation.md: re-runs a read-only command and records whether the output matches. */
     attest(argv: string[], claimed: string, cwd?: string, claimedExit?: number): Attestation | undefined;
     /**
@@ -377,6 +399,23 @@ export declare class BlackboxSession {
     lessons(options?: {
         limit?: number;
     }): Promise<Lessons | null>;
+    /** One of this session's gateway routes: the answer on 200 or 201, else null. Never throws. */
+    private route;
+    /** spec/aviation.md §1-§2: asks for a clearance on a shared resource before changing it. The
+     * answer is `granted` (with its `clearance_id`) or `hold` (wait `retry_after_s`, then ask again).
+     * `null` when the gateway can't be asked. */
+    clearance(resource: string, options?: {
+        mode?: "exclusive" | "shared";
+        ttlS?: number;
+    }): Promise<ClearanceAnswer | null>;
+    /** spec/aviation.md §1: gives a clearance back. True when the gateway released it. */
+    releaseClearance(clearanceId: string): Promise<boolean>;
+    /** spec/aviation.md §8: the quick reference handbook's procedures for this session's
+     * findings. The gateway records that the agent read them. `null` when it can't be asked. */
+    qrh(): Promise<Procedure[] | null>;
+    /** spec/aviation.md §3: the operator's notices in force now, to read before a run. The gateway
+     * records that the agent read them. `null` when it can't be asked. */
+    notams(): Promise<Notam[] | null>;
     /**
      * spec/findings.md §1c: the agent changed itself (its prompt, a tool, its policy, its memory, its
      * model). Only hashes of `before` and `after` are sent, never the content. A change that gives
@@ -393,6 +432,10 @@ export declare class BlackboxSession {
         /** A Zanii Evolve certificate's digest behind the change (spec/fleet.md §9). */
         certificate?: string;
     }): void;
+    /** spec/evals.md §4: the version of a registered prompt this run uses, for when the gateway
+     * can't tell it from the system prompt's hash (the prompt is assembled per run). A bad name or
+     * version is dropped. */
+    promptVersion(name: string, version: number): void;
     /** 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. */