@zanii/blackbox 0.21.1 → 0.22.0

package/dist/actions/index.d.ts

@@ -0,0 +1,29 @@
+import { type Bodies, type Call } from "../reconcile/record.ts";
+export interface Reasoning {
+    /** `text` (the model's own words), `summary` (the provider's), `encrypted` (there, unreadable) or `none`. */
+    kind: "text" | "summary" | "encrypted" | "none";
+    text: string | null;
+}
+export interface Action {
+    seq: number;
+    request_seq: number;
+    model: string | null;
+    tool: string;
+    id: string | null;
+    args: unknown;
+    reasoning: Reasoning;
+    /** What the model wrote before the action, in the same answer. */
+    said: string | null;
+}
+/** The tool calls each model answer asked for, in order. Each takes the reasoning and text that came
+ *  before it in the same answer, since the action before it; one with none of its own (a second call
+ *  in a row) takes the answer's latest. */
+export declare function actionsFromCalls(calls: readonly Call[]): Action[];
+/** The actions in a verified record, each with the reasoning before it (spec/replay.md §6). */
+export declare function actionsOf(lines: readonly string[], bodies: Bodies): Action[];
+/** The actions for a reader: the first `limit`, each reasoning and `said` cut to `textMax` characters. */
+export declare function actionsPage(actions: readonly Action[], limit?: number, textMax?: number): {
+    total: number;
+    capped: boolean;
+    actions: Action[];
+};

package/dist/actions/index.js

@@ -0,0 +1,114 @@
+// Each action an agent took, with the reasoning the model gave before it (spec/replay.md §6): the
+// thinking (Anthropic `thinking`, Gemini thoughts, a Chat Completions `reasoning_content`), the
+// provider's reasoning summary (OpenAI Responses), or a note that it was there but encrypted. Pure;
+// mirrors sdks/python/src/zanii_blackbox/actions.py; pinned by spec/vectors/actions.json.
+import { callsOf } from "../reconcile/record.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Text parts win over a summary, either over encrypted. */
+function reasoningOf(parts) {
+    for (const kind of ["text", "summary"]) {
+        const texts = parts.filter(([k, t]) => k === kind && t).map(([, t]) => t);
+        if (texts.length)
+            return { kind, text: texts.join("\n\n") };
+    }
+    if (parts.some(([k]) => k === "encrypted"))
+        return { kind: "encrypted", text: null };
+    return { kind: "none", text: null };
+}
+const action = (c, tool, id, args, why, said) => ({
+    seq: c.endSeq,
+    request_seq: c.requestSeq,
+    model: c.model,
+    tool,
+    id: typeof id === "string" ? id : null,
+    args: args ?? {},
+    reasoning: reasoningOf(why),
+    said: said.filter(Boolean).join("\n\n") || null,
+});
+/** The tool calls each model answer asked for, in order. Each takes the reasoning and text that came
+ *  before it in the same answer, since the action before it; one with none of its own (a second call
+ *  in a row) takes the answer's latest. */
+export function actionsFromCalls(calls) {
+    const out = [];
+    for (const c of [...calls].sort((a, b) => a.endSeq - b.endSeq)) {
+        let why = c.reasoning ? [["text", c.reasoning]] : [];
+        let said = [];
+        let last = [[], []];
+        for (const [, b] of [...c.blocks.entries()].sort(([x], [y]) => x - y)) {
+            if (b.type === "thinking")
+                why.push(typeof b.thinking === "string" && b.thinking ? ["text", b.thinking] : ["encrypted", ""]);
+            else if (b.type === "redacted_thinking")
+                why.push(["encrypted", ""]);
+            else if (b.type === "text" && typeof b.text === "string")
+                said.push(b.text);
+            else if (b.type === "tool_use" && typeof b.name === "string") {
+                if (why.length || said.length)
+                    last = [why, said];
+                out.push(action(c, b.name, b.id, b.input, ...last));
+                why = [];
+                said = [];
+            }
+        }
+        for (const item of c.items) {
+            const t = item.type;
+            if (t === "reasoning") {
+                const texts = (Array.isArray(item.summary) ? item.summary : [])
+                    .filter(isObj)
+                    .map((s) => String(s.text ?? ""));
+                const own = (Array.isArray(item.content) ? item.content : [])
+                    .filter(isObj)
+                    .map((s) => String(s.text ?? ""));
+                if (own.some(Boolean))
+                    why.push(...own.map((x) => ["text", x]));
+                else if (texts.some(Boolean))
+                    why.push(...texts.map((x) => ["summary", x]));
+                else
+                    why.push(["encrypted", ""]);
+            }
+            else if (t === "message") {
+                for (const s of Array.isArray(item.content) ? item.content : [])
+                    if (isObj(s) && typeof s.text === "string")
+                        said.push(s.text);
+            }
+            else if ((t === "function_call" || t === "custom_tool_call") &&
+                typeof item.name === "string") {
+                let args = t === "function_call" ? item.arguments : item.input;
+                if (typeof args === "string" && t === "function_call") {
+                    try {
+                        args = JSON.parse(args);
+                    }
+                    catch { }
+                }
+                if (why.length || said.length)
+                    last = [why, said];
+                out.push(action(c, item.name, item.call_id, args, ...last));
+                why = [];
+                said = [];
+            }
+        }
+    }
+    return out;
+}
+/** The actions in a verified record, each with the reasoning before it (spec/replay.md §6). */
+export function actionsOf(lines, bodies) {
+    return actionsFromCalls(callsOf(lines, bodies));
+}
+/** Cut to `most` code points (as Python counts them), then `…`. */
+function cut(text, most) {
+    if (text === null)
+        return null;
+    const points = Array.from(text);
+    return points.length <= most ? text : `${points.slice(0, most).join("")}…`;
+}
+/** The actions for a reader: the first `limit`, each reasoning and `said` cut to `textMax` characters. */
+export function actionsPage(actions, limit = 1000, textMax = 8000) {
+    return {
+        total: actions.length,
+        capped: actions.length > limit,
+        actions: actions.slice(0, limit).map((a) => ({
+            ...a,
+            reasoning: { ...a.reasoning, text: cut(a.reasoning.text, textMax) },
+            said: cut(a.said, textMax),
+        })),
+    };
+}

package/dist/admission/index.d.ts

@@ -0,0 +1,30 @@
+export declare const REGISTER_TYPE = "blackbox.service-register";
+export declare const ACCREDITATION_TYPE = "blackbox.accreditation";
+export declare const SERVICE_ID: RegExp;
+type Doc = Record<string, unknown>;
+export interface ServiceRow {
+    id: string;
+    name: string;
+    name_ar?: string;
+    tier: number;
+}
+/** `sha256:` + hex of the RFC 8785 JSON of the whole signed document. */
+export declare const docHash: (doc: Doc) => string;
+/** §1: null when the register is well formed and signed by one of `signers`, else why not. */
+export declare function checkRegister(doc: unknown, signers: readonly string[]): string | null;
+/** §1: a service's tier and its row; an unknown service (or none) gets `default_tier`. */
+export declare function serviceTier(register: Doc, serviceId: string | null | undefined): {
+    tier: number;
+    service: ServiceRow | null;
+};
+export type AccreditationRefusal = "malformed" | "unsigned" | "wrong_issuer" | "revoked" | "not_yet" | "expired" | "wrong_vendor" | "agent_not_listed" | "tier_too_high";
+/** §2: null when `cert` lets this vendor's agent open a session for a service of `tier` now, else
+ *  the reason. */
+export declare function checkAccreditation(cert: unknown, issuers: readonly string[], opts: {
+    now: string;
+    vendor?: string | null;
+    agentId?: string | null;
+    tier?: number | null;
+    revoked?: readonly string[];
+}): AccreditationRefusal | null;
+export {};

package/dist/admission/index.js

@@ -0,0 +1,106 @@
+// Who and what may open a session (spec/admission.md): the signed service risk register (each
+// service's tier: 1 allowed, 2 a person approves each action, 3 off limits) and a vendor's signed
+// accreditation. Both are signed like certificates (spec/fleet.md §5) and checked offline. Pure;
+// mirrors sdks/python/src/zanii_blackbox/admission.py; pinned by spec/vectors/admission.json.
+import { createHash } from "node:crypto";
+import { verifyCertificate } from "../fleet/index.js";
+import { canonical } from "../reconcile/shared.js";
+export const REGISTER_TYPE = "blackbox.service-register";
+export const ACCREDITATION_TYPE = "blackbox.accreditation";
+export const SERVICE_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const VENDOR_ID = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const AGENT_ID = /^(?:[A-Za-z0-9._:@/-]{1,128}|\*)$/;
+const MAX_SERVICES = 10_000;
+const UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$/;
+/** `sha256:` + hex of the RFC 8785 JSON of the whole signed document. */
+export const docHash = (doc) => `sha256:${createHash("sha256").update(canonical(doc)).digest("hex")}`;
+const isTier = (x) => Number.isInteger(x) && x >= 1 && x <= 3;
+const when = (x) => {
+    if (typeof x !== "string" || !UTC.test(x))
+        return null;
+    const t = Date.parse(x);
+    return Number.isNaN(t) ? null : t;
+};
+const isObject = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+/** §1: null when the register is well formed and signed by one of `signers`, else why not. */
+export function checkRegister(doc, signers) {
+    if (!isObject(doc))
+        return "the register must be a JSON object";
+    if (doc.v !== 1 || doc.type !== REGISTER_TYPE)
+        return `not a ${REGISTER_TYPE} v1`;
+    if (typeof doc.name !== "string" || !doc.name)
+        return "name is required";
+    if (!isTier(doc.default_tier))
+        return "default_tier must be 1, 2 or 3";
+    const services = doc.services;
+    if (!Array.isArray(services) || services.length > MAX_SERVICES)
+        return `services must be a list of at most ${MAX_SERVICES}`;
+    const seen = new Set();
+    for (const [i, s] of services.entries()) {
+        if (!isObject(s))
+            return `services[${i}] must be an object`;
+        if (typeof s.id !== "string" || !SERVICE_ID.test(s.id))
+            return `services[${i}].id must be 1-64 of a-z 0-9 . _ - (like visa-renewal)`;
+        if (seen.has(s.id))
+            return `services[${i}].id ${s.id} is listed twice`;
+        seen.add(s.id);
+        if (typeof s.name !== "string" || !s.name)
+            return `services[${i}].name is required`;
+        if (!isTier(s.tier))
+            return `services[${i}].tier must be 1, 2 or 3`;
+    }
+    const v = verifyCertificate(doc);
+    if (!v.ok)
+        return `the register's signature doesn't verify (${v.reason})`;
+    if (!signers.includes(v.by))
+        return `the register is signed by ${v.by}, who isn't a trusted signer`;
+    return null;
+}
+/** §1: a service's tier and its row; an unknown service (or none) gets `default_tier`. */
+export function serviceTier(register, serviceId) {
+    const found = register.services.find((s) => s.id === serviceId);
+    return found
+        ? { tier: found.tier, service: found }
+        : { tier: register.default_tier, service: null };
+}
+/** §2: null when `cert` lets this vendor's agent open a session for a service of `tier` now, else
+ *  the reason. */
+export function checkAccreditation(cert, issuers, opts) {
+    if (!isObject(cert))
+        return "malformed";
+    const agents = cert.agents;
+    const issued = when(cert.issued_at);
+    const expires = when(cert.expires_at);
+    const at = when(opts.now);
+    if (cert.v !== 1 ||
+        cert.type !== ACCREDITATION_TYPE ||
+        typeof cert.vendor !== "string" ||
+        !VENDOR_ID.test(cert.vendor) ||
+        !Array.isArray(agents) ||
+        !agents.length ||
+        !agents.every((a) => typeof a === "string" && AGENT_ID.test(a)) ||
+        (cert.max_tier !== 1 && cert.max_tier !== 2) ||
+        issued === null ||
+        expires === null ||
+        at === null)
+        return "malformed";
+    const v = verifyCertificate(cert);
+    if (!v.ok)
+        return "unsigned";
+    if (!issuers.includes(v.by))
+        return "wrong_issuer";
+    if ((opts.revoked ?? []).includes(docHash(cert)))
+        return "revoked";
+    if (at < issued)
+        return "not_yet";
+    if (at >= expires)
+        return "expired";
+    if (opts.vendor != null && cert.vendor !== opts.vendor)
+        return "wrong_vendor";
+    const listed = agents;
+    if (!listed.includes("*") && (opts.agentId == null || !listed.includes(opts.agentId)))
+        return "agent_not_listed";
+    if (opts.tier != null && opts.tier > cert.max_tier)
+        return "tier_too_high";
+    return null;
+}

package/dist/cli.js

@@ -43,6 +43,7 @@ const USAGE = `usage (spec/cli.md):
   blackbox investigate <bundle.json> [--bodies <dir>] [--directives <file>] [--identity <file>] [--proofs] [--out <prefix>]
   blackbox evidence-pack <bundle.json> [--proofs] [--identity <file>] [--lang en|ar|both] [--out <prefix>]
   blackbox sign-constitution <draft.json> --identity <owner.json> [--out <file>]
+  blackbox sign <draft.json> --identity <owner.json> [--out <file>]   (a service register or an accreditation)
   blackbox policy-from-zanii <zanii-policy.json> [--out <file>]
   blackbox policy-to-zanii <policy.json> [--out <file>]
   blackbox statement --provider anthropic|openai --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--out <file>]
@@ -111,6 +112,8 @@ async function main(argv) {
         return evidencePackCommand(rest);
     if (command === "sign-constitution")
         return signConstitutionCommand(rest);
+    if (command === "sign")
+        return signCommand(rest);
     if (command === "policy-from-zanii" || command === "policy-to-zanii")
         return policyZaniiCommand(command, rest);
     if (command === "statement")
@@ -863,6 +866,30 @@ async function signConstitutionCommand(rest) {
         return 2;
     }
 }
+/** spec/admission.md §3: signs a draft (a service register, an accreditation) as the identity. */
+async function signCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    if (positional.length !== 1 || !flags.identity)
+        return usage();
+    const { signCertificate } = await import("./fleet/index.js");
+    const { docHash } = await import("./admission/index.js");
+    try {
+        const draft = JSON.parse(readFileSync(positional[0], "utf8"));
+        if (!draft || typeof draft !== "object" || Array.isArray(draft))
+            throw new Error("the draft must be a JSON object");
+        const { signed: _old, ...rest_ } = draft;
+        const identity = await readIdentity(flags.identity);
+        const doc = signCertificate(rest_, identity.did, identity.seed);
+        const out = flags.out || "signed.json";
+        writeFileSync(out, `${JSON.stringify(doc, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ok: true, file: out, sha256: docHash(doc), by: identity.did })}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: error.message })}\n`);
+        return 2;
+    }
+}
 /** spec/investigations.md §7: the court evidence pack, `<prefix>.json` (signed) and `<prefix>.md`. */
 async function evidencePackCommand(rest) {
     const { flags, positional } = parse(rest, ["--proofs"]);

package/dist/cost/index.d.ts

@@ -17,6 +17,9 @@ export interface ModelPrice {
     /** Audio in and out (else `input` / `output`). */
     input_audio?: number;
     output_audio?: number;
+    /** Image tokens in and out (else `input` / `output`): OpenAI's and Gemini's image models. */
+    input_image?: number;
+    output_image?: number;
     /** µUSD per 1,000 web-search requests (Anthropic's server tool); absent: not priced. */
     web_search_per_1k?: number;
     /** Prices once the call's prompt is over `above` tokens (Gemini's >200k tier), highest first. */
@@ -56,6 +59,8 @@ export interface Tokens {
     cache_write_1h?: number;
     input_audio?: number;
     output_audio?: number;
+    input_image?: number;
+    output_image?: number;
 }
 export interface CallCost {
     seq: number;
@@ -74,6 +79,8 @@ export interface CallCost {
     /** spec/cost.md §1a: the uplift applied, when one matched. */
     uplift_percent?: number;
     source?: "reported";
+    /** The answer carried no usage (`usage_missing`): unpriced, never counted as free. */
+    no_usage?: true;
 }
 export interface CostReport {
     v: 1;

package/dist/cost/index.js

@@ -2,12 +2,20 @@
 // Mirrors sdks/python/src/zanii_blackbox/cost.py.
 import { createHash } from "node:crypto";
 const CLASSES = ["input", "output", "cache_read", "cache_write"];
-const EXTRA = ["cache_write_1h", "input_audio", "output_audio"];
+const EXTRA = [
+    "cache_write_1h",
+    "input_audio",
+    "output_audio",
+    "input_image",
+    "output_image",
+];
 const OPTIONAL_PRICES = [
     "context_window",
     "cache_write_1h",
     "input_audio",
     "output_audio",
+    "input_image",
+    "output_image",
     "web_search_per_1k",
 ];
 /** Parses and checks a price table; its sha256 is of the exact file bytes. */
@@ -99,12 +107,20 @@ export function tokensOf(usage) {
         const cached = n("cachedContentTokenCount");
         const audioIn = n("promptTokensDetails_AUDIO");
         const audioOut = n("candidatesTokensDetails_AUDIO");
+        const imageIn = n("promptTokensDetails_IMAGE");
+        const imageOut = n("candidatesTokensDetails_IMAGE");
         return extras({
-            input: Math.max(0, n("promptTokenCount") - cached - audioIn) + n("toolUsePromptTokenCount"),
-            output: Math.max(0, n("candidatesTokenCount") - audioOut) + n("thoughtsTokenCount"),
+            input: Math.max(0, n("promptTokenCount") - cached - audioIn - imageIn) +
+                n("toolUsePromptTokenCount"),
+            output: Math.max(0, n("candidatesTokenCount") - audioOut - imageOut) + n("thoughtsTokenCount"),
             cache_read: cached,
             cache_write: 0,
-        }, { input_audio: audioIn, output_audio: audioOut });
+        }, {
+            input_audio: audioIn,
+            output_audio: audioOut,
+            input_image: imageIn,
+            output_image: imageOut,
+        });
     }
     if ("inputTokens" in usage)
         // Bedrock Converse (spec/providers.md §5)
@@ -130,18 +146,28 @@ export function tokensOf(usage) {
     // Anthropic's cache names are its own: they win over the Responses shape, since Anthropic also
     // sends output_tokens_details (thinking_tokens) since Claude Sonnet 5
     const anthropicCache = "cache_read_input_tokens" in usage || "cache_creation_input_tokens" in usage;
+    // OpenAI's transcriptions write input_token_details (singular); its images, image_tokens
     if (!anthropicCache &&
-        Object.keys(usage).some((k) => k.startsWith("input_tokens_details_") || k.startsWith("output_tokens_details_"))) {
+        Object.keys(usage).some((k) => k.startsWith("input_tokens_details_") ||
+            k.startsWith("output_tokens_details_") ||
+            k.startsWith("input_token_details_"))) {
         const cached = n("input_tokens_details_cached_tokens");
         const written = n("input_tokens_details_cache_write_tokens");
-        const audioIn = n("input_tokens_details_audio_tokens");
+        const audioIn = n("input_tokens_details_audio_tokens") + n("input_token_details_audio_tokens");
         const audioOut = n("output_tokens_details_audio_tokens");
+        const imageIn = n("input_tokens_details_image_tokens");
+        const imageOut = n("output_tokens_details_image_tokens");
         return extras({
-            input: Math.max(0, n("input_tokens") - cached - written - audioIn),
-            output: Math.max(0, n("output_tokens") - audioOut),
+            input: Math.max(0, n("input_tokens") - cached - written - audioIn - imageIn),
+            output: Math.max(0, n("output_tokens") - audioOut - imageOut),
             cache_read: cached,
             cache_write: written,
-        }, { input_audio: audioIn, output_audio: audioOut });
+        }, {
+            input_audio: audioIn,
+            output_audio: audioOut,
+            input_image: imageIn,
+            output_image: imageOut,
+        });
     }
     // Anthropic: cache_creation_input_tokens is both lifetimes; the 1-hour part is priced apart
     const hour = n("cache_creation_ephemeral_1h_input_tokens");
@@ -167,7 +193,12 @@ export function requestsOf(usage) {
 }
 /** A call's prompt, in tokens: what a context tier is decided on. */
 export function promptTokens(t) {
-    return t.input + t.cache_read + t.cache_write + (t.cache_write_1h ?? 0) + (t.input_audio ?? 0);
+    return (t.input +
+        t.cache_read +
+        t.cache_write +
+        (t.cache_write_1h ?? 0) +
+        (t.input_audio ?? 0) +
+        (t.input_image ?? 0));
 }
 /** The prices a call pays: a context tier when its prompt is over one, then its service tier. */
 export function effectivePrice(price, tokens, serviceTier) {
@@ -203,6 +234,8 @@ export function callMicroUsd(tokens, price, requests) {
     sum += (tokens.cache_write_1h ?? 0) * (price.cache_write_1h ?? price.cache_write);
     sum += (tokens.input_audio ?? 0) * (price.input_audio ?? price.input);
     sum += (tokens.output_audio ?? 0) * (price.output_audio ?? price.output);
+    sum += (tokens.input_image ?? 0) * (price.input_image ?? price.input);
+    sum += (tokens.output_image ?? 0) * (price.output_image ?? price.output);
     sum += (requests?.web_search ?? 0) * (price.web_search_per_1k ?? 0) * 1000;
     if (!Number.isSafeInteger(sum))
         throw new RangeError("cost overflow: tokens × price beyond 2^53");
@@ -288,9 +321,19 @@ export function sessionCost(lines, prices) {
         if (replayed.has(e.meta.request_seq))
             continue;
         const usage = e.meta.usage;
-        if (typeof usage !== "object" || usage === null)
-            continue;
         const model = typeof e.meta.model === "string" ? e.meta.model : null;
+        if (typeof usage !== "object" || usage === null) {
+            // an answer that said nothing of what it cost is unpriced, never silently free
+            if (e.meta.usage_missing === true)
+                calls.push({
+                    seq: e.seq,
+                    model,
+                    tokens: { input: 0, output: 0, cache_read: 0, cache_write: 0 },
+                    micro_usd: null,
+                    no_usage: true,
+                });
+            continue;
+        }
         const priced = priceCall({
             model,
             usage: usage,

package/dist/evidence/index.d.ts

@@ -1,3 +1,4 @@
+import type { actionsPage } from "../actions/index.ts";
 import type { Bundle, BundleReport } from "../verify/index.ts";
 type Text = {
     en: string;
@@ -7,7 +8,10 @@ export interface EvidencePackOptions {
     generated_at: string;
     bundle_sha256: string;
     proofs: "checked" | "not_checked";
+    /** §7a: an `actionsPage`, when the bodies are at hand: each action with the reasoning before it. */
+    actions?: ActionsPage;
 }
+type ActionsPage = ReturnType<typeof actionsPage>;
 /** spec/investigations.md §7. */
 export declare function evidencePack(bundle: Bundle, report: BundleReport, opts: EvidencePackOptions): {
     v: 1;
@@ -53,6 +57,11 @@ export declare function evidencePack(bundle: Bundle, report: BundleReport, opts:
     reproduce: string[];
     generated_at: string;
     bundle_sha256: string;
+    actions?: {
+        total: number;
+        capped: boolean;
+        actions: import("../actions/index.ts").Action[];
+    };
 };
 export type EvidencePack = ReturnType<typeof evidencePack>;
 /** The Markdown copy (spec/investigations.md §7): `en`, `ar` or `both`. */

package/dist/evidence/index.js

@@ -97,6 +97,7 @@ export function evidencePack(bundle, report, opts) {
         reproduce: REPRODUCE,
         generated_at: opts.generated_at,
         bundle_sha256: opts.bundle_sha256,
+        ...(opts.actions ? { actions: opts.actions } : {}),
     };
 }
 // U+2067 … U+2069 isolate the Arabic paragraphs, so they read right to left in any viewer.
@@ -147,5 +148,54 @@ export function renderEvidencePack(pack, lang = "both") {
         ...pack.reproduce,
         "```",
         "",
+        ...actionsMd(pack.actions, label),
     ].join("\n");
 }
+const KIND = {
+    text: ["the model's own reasoning", "تفكير النموذج نفسه"],
+    summary: ["the provider's summary of it", "ملخّص المزوّد له"],
+    encrypted: ["recorded, but encrypted by the provider", "مسجّل لكنه مشفّر من المزوّد"],
+    none: ["none recorded", "لم يُسجَّل شيء"],
+};
+const quote = (text) => text
+    .split(/\r?\n|\r/)
+    .map((l) => `   > ${l}`)
+    .join("\n") || ">";
+/** Python's json.dumps(…, ensure_ascii=False, sort_keys=True): keys sorted, ", " and ": ". */
+function pyJson(v) {
+    if (Array.isArray(v))
+        return `[${v.map(pyJson).join(", ")}]`;
+    if (v && typeof v === "object")
+        return `{${Object.keys(v)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}: ${pyJson(v[k])}`)
+            .join(", ")}}`;
+    return JSON.stringify(v) ?? "null";
+}
+/** §7a: each action, then the reasoning recorded before it. */
+function actionsMd(page, label) {
+    if (!page)
+        return [];
+    const out = [
+        `## ${label("Actions and the reasoning before each", "الإجراءات والتفكير الذي سبق كلًّا منها")}`,
+        "",
+    ];
+    if (!page.actions.length)
+        out.push(label("No actions recorded.", "لم تُسجَّل أي إجراءات."), "");
+    page.actions.forEach((a, i) => {
+        const all = pyJson(a.args);
+        const points = Array.from(all);
+        const args = points.length <= 300 ? all : `${points.slice(0, 300).join("")}…`;
+        const [en, ar] = KIND[a.reasoning.kind] ?? KIND.none;
+        out.push(`${i + 1}. **\`${a.tool}\`** · ${label("event", "الحدث")} ${a.seq} · \`${args}\``, "", `   ${label("Reasoning", "التفكير")}: ${label(en, ar)}`, "");
+        if (a.reasoning.text)
+            out.push(quote(a.reasoning.text), "");
+        if (a.said)
+            out.push(`   ${label("It wrote", "كتب")}:`, "", quote(a.said), "");
+    });
+    if (page.capped) {
+        const n = page.actions.length;
+        out.push(label(`The first ${n} of ${page.total} actions.`, `أول ${n} من أصل ${page.total} إجراءات.`), "");
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { A2A_STREAMING, type AgentCardReport, a2aMethod, a2aRequestMeta, a2aResponseMeta, a2aRestMethod, a2aRestRequestMeta, a2aRestResponseMeta, agentCardDigest, agentCardPayload, gatewayCardKey, rewriteAgentCard, verifyAgentCard, } from "./a2a/index.ts";
+export { type Action, actionsFromCalls, actionsOf, actionsPage, type Reasoning, } from "./actions/index.ts";
+export { ACCREDITATION_TYPE, type AccreditationRefusal, checkAccreditation, checkRegister, docHash, REGISTER_TYPE, SERVICE_ID, type ServiceRow, serviceTier, } from "./admission/index.ts";
 export { causality, memoryXray } from "./agents/index.ts";
 export { type DetectorOptions, detectors, fingerprint } from "./analysis/detectors.ts";
 export { FAULTS, type Fault, faultOf } from "./analysis/faults.ts";

package/dist/index.js

@@ -1,6 +1,8 @@
 // Public API of @zanii/blackbox. Everything customers can import is re-exported here.
 // Keep this file in step with sdks/python/src/zanii_blackbox/__init__.py (the SDKs mirror each other).
 export { A2A_STREAMING, a2aMethod, a2aRequestMeta, a2aResponseMeta, a2aRestMethod, a2aRestRequestMeta, a2aRestResponseMeta, agentCardDigest, agentCardPayload, gatewayCardKey, rewriteAgentCard, verifyAgentCard, } from "./a2a/index.js";
+export { actionsFromCalls, actionsOf, actionsPage, } from "./actions/index.js";
+export { ACCREDITATION_TYPE, checkAccreditation, checkRegister, docHash, REGISTER_TYPE, SERVICE_ID, serviceTier, } from "./admission/index.js";
 export { causality, memoryXray } from "./agents/index.js";
 export { detectors, fingerprint } from "./analysis/detectors.js";
 export { FAULTS, faultOf } from "./analysis/faults.js";

package/dist/reconcile/record.d.ts

@@ -35,6 +35,8 @@ 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;

package/dist/reconcile/record.js

@@ -125,9 +125,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 +145,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 +157,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 +219,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/verify/chain.d.ts

@@ -23,5 +23,9 @@ export interface VerifyOptions {
         count: number;
         head: string;
     }>;
+    /** A continuation (spec/tower.md §3): the first line's seq, and the event_hash it follows.
+     *  Anchors need the whole chain. */
+    startSeq?: number;
+    startPrev?: string;
 }
 export declare function verifyChain(lines: readonly string[], options?: VerifyOptions): VerifyResult;

package/dist/verify/chain.js

@@ -7,7 +7,8 @@ const SESSION = /^ses_[A-Za-z0-9]{16,64}$/;
 const TS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$/;
 const KINDS = new Set(EVENT_KINDS);
 export function verifyChain(lines, options = {}) {
-    let prev = GENESIS;
+    let prev = options.startPrev ?? GENESIS;
+    const start = options.startSeq ?? 0;
     const hashes = [];
     let session = options.sessionId;
     const fail = (code, index, message) => ({
@@ -34,8 +35,8 @@ export function verifyChain(lines, options = {}) {
         session ??= env.session_id;
         if (env.session_id !== session)
             return fail("WRONG_SESSION", i, `session_id ${env.session_id} ≠ ${session}`);
-        if (env.seq !== i)
-            return fail("SEQ_GAP", i, `expected seq ${i}, found ${env.seq}`);
+        if (env.seq !== start + i)
+            return fail("SEQ_GAP", i, `expected seq ${start + i}, found ${env.seq}`);
         if (env.prev !== prev)
             return fail("BROKEN_LINK", i, "prev does not match the previous event_hash");
         const body = options.body?.(env.body_hash);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.21.1";
+export declare const VERSION = "0.22.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.21.1";
+export const VERSION = "0.22.0";

package/package.json

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