@zanii/blackbox 0.19.0 → 0.20.1

package/dist/analysis/faults.js

@@ -232,6 +232,21 @@ export const FAULTS = {
         en: "A tool's definition changed mid-session",
         ar: "تغيّر تعريف أداة أثناء الجلسة",
     },
+    PROMPT_CHANGED: {
+        fault: "BBX-7405",
+        en: "The system prompt changed since the last run",
+        ar: "تغيّرت تعليمات النظام منذ التشغيل السابق",
+    },
+    SELF_CHANGE: {
+        fault: "BBX-7406",
+        en: "The agent changed itself",
+        ar: "غيّر الوكيل نفسه",
+    },
+    SELF_CHANGE_UNAPPROVED: {
+        fault: "BBX-7407",
+        en: "The agent gave itself more power without approval",
+        ar: "منح الوكيل نفسه صلاحيات أكبر دون موافقة",
+    },
     USER_DOWNVOTE: {
         fault: "BBX-4601",
         en: "The person served said an answer was wrong",

package/dist/analysis/index.d.ts

@@ -103,3 +103,4 @@ export declare function verifyRegression(events: Ev[]): Finding[];
 /** Stage 2 R4, judged at close: a run labelled (or claimed) a success that its own record contradicts:
  * a check's last result failed, or the last tool call failed with nothing succeeding after it. */
 export declare function falseSuccess(events: Ev[], now: number): Finding[];
+export { type Lessons, lessons, POWER_KINDS, promptChanged, SELF_CHANGE_KINDS, selfChanges, systemPromptHash, } from "./learning.ts";

package/dist/analysis/index.js

@@ -16,6 +16,7 @@ import { groundingFindings, judgeFindings } from "./grounding.js";
 import { toolHallucinations } from "./hallucination.js";
 import { injectionFindings } from "./injection.js";
 import { flightPlan } from "./landing.js";
+import { promptChanged, selfChanges } from "./learning.js";
 import { memoryFindings } from "./memory.js";
 export { detectorAccuracy, wilsonLow } from "./accuracy.js";
 export { answerClaims, answerCredential, verifyAnswerCredential, } from "./credential.js";
@@ -60,6 +61,8 @@ export function analyze(lines, options) {
         ...toolDrifted(events),
         ...secretSent(events),
         ...userDownvotes(events),
+        ...selfChanges(events),
+        ...promptChanged(events),
         ...injectionFindings(lines, options.bodies),
         ...verifyRegression(events),
         ...falseSuccess(events, now),
@@ -583,3 +586,4 @@ export function falseSuccess(events, now) {
             : "The agent claimed it was done, but its last tool call failed and nothing succeeded after it.");
     return [];
 }
+export { lessons, POWER_KINDS, promptChanged, SELF_CHANGE_KINDS, selfChanges, systemPromptHash, } from "./learning.js";

package/dist/analysis/learning.d.ts

@@ -0,0 +1,54 @@
+import type { Summary } from "../fleet/index.ts";
+import type { Ev, Finding } from "./index.ts";
+/** What a self-change may be about. Anything else is recorded as `other`. */
+export declare const SELF_CHANGE_KINDS: readonly ["prompt", "tool", "policy", "memory", "model", "other"];
+/** Changes that give the agent more power: each needs an approved approval first. */
+export declare const POWER_KINDS: readonly string[];
+/**
+ * The fingerprint of a model request's system prompt: `sha256:` + hex over the canonical JSON of
+ * every system part it carries (Anthropic `system`, OpenAI Responses `instructions`, the `system` and
+ * `developer` messages of Chat Completions or Responses `input`, Gemini `systemInstruction`), or
+ * null when it has none.
+ */
+export declare function systemPromptHash(body: unknown): string | null;
+/**
+ * spec/findings.md §1c: each self-change the agent reported (`self_change`) is SELF_CHANGE; one
+ * that gives it more power (a tool, a policy or a model) with no approval approved before it is
+ * SELF_CHANGE_UNAPPROVED.
+ */
+export declare function selfChanges(events: Ev[]): Finding[];
+/**
+ * spec/findings.md §1c: the gateway stamps a request's system prompt fingerprint and, on the
+ * session's first one, the fingerprint the previous session with this label began with. A
+ * difference is PROMPT_CHANGED: advisory when the agent declared a prompt self-change before it,
+ * caution when nothing did.
+ */
+export declare function promptChanged(events: Ev[]): Finding[];
+export interface Lessons {
+    label: string | null;
+    sessions: number;
+    outcomes: {
+        success: number;
+        failure: number;
+        abandoned: number;
+        unknown: number;
+    };
+    codes: Array<{
+        code: string;
+        title: string | null;
+        sessions: number;
+        failed_sessions: number;
+        findings: number;
+        last_seen: string;
+    }>;
+    claims_failed_sessions: number;
+    blocked_sessions: number;
+    brief: string;
+}
+/**
+ * spec/fleet.md §8: what earlier runs of one agent (its label) hit, from their summaries, newest
+ * first: outcomes, the finding codes by how many runs they were in and how many of those failed,
+ * the runs whose completion claim the record contradicted, and a short brief an agent can put in its
+ * own prompt. Codes and counts only, never content.
+ */
+export declare function lessons(summaries: readonly Summary[], label: string | null): Lessons;

package/dist/analysis/learning.js

@@ -0,0 +1,191 @@
+// The learning loop (spec/fleet.md §8, spec/findings.md §1c): what earlier runs of an agent hit,
+// for it to read before a run, and the record of any change an agent makes to itself. The agent
+// reads lessons; it never writes to the evidence. Mirrors analysis/learning.py.
+import { createHash } from "node:crypto";
+import { canonical } from "../reconcile/shared.js";
+import { FAULTS } from "./faults.js";
+/** What a self-change may be about. Anything else is recorded as `other`. */
+export const SELF_CHANGE_KINDS = ["prompt", "tool", "policy", "memory", "model", "other"];
+/** Changes that give the agent more power: each needs an approved approval first. */
+export const POWER_KINDS = ["tool", "policy", "model"];
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The fingerprint of a model request's system prompt: `sha256:` + hex over the canonical JSON of
+ * every system part it carries (Anthropic `system`, OpenAI Responses `instructions`, the `system` and
+ * `developer` messages of Chat Completions or Responses `input`, Gemini `systemInstruction`), or
+ * null when it has none.
+ */
+export function systemPromptHash(body) {
+    if (!isObj(body))
+        return null;
+    const parts = [];
+    if (body.system !== undefined)
+        parts.push(["system", body.system]);
+    if (typeof body.instructions === "string")
+        parts.push(["instructions", body.instructions]);
+    for (const key of ["messages", "input"])
+        if (Array.isArray(body[key]))
+            for (const m of body[key])
+                if (isObj(m) && (m.role === "system" || m.role === "developer"))
+                    parts.push([m.role, m.content ?? null]);
+    if ("systemInstruction" in body || "system_instruction" in body)
+        parts.push([
+            "systemInstruction",
+            "systemInstruction" in body ? body.systemInstruction : body.system_instruction,
+        ]);
+    if (!parts.length)
+        return null;
+    return `sha256:${createHash("sha256").update(canonical(parts)).digest("hex")}`;
+}
+/**
+ * spec/findings.md §1c: each self-change the agent reported (`self_change`) is SELF_CHANGE; one
+ * that gives it more power (a tool, a policy or a model) with no approval approved before it is
+ * SELF_CHANGE_UNAPPROVED.
+ */
+export function selfChanges(events) {
+    const out = [];
+    const approved = new Map();
+    for (const e of events)
+        if (e.kind === "control" && e.meta.action === "approval" && e.meta.decision === "approve")
+            if (typeof e.meta.approval_id === "string" && !approved.has(e.meta.approval_id))
+                approved.set(e.meta.approval_id, e.seq);
+    for (const e of events) {
+        if (e.kind !== "sdk.event" || e.meta.type !== "self_change")
+            continue;
+        const d = e.data ?? {};
+        const kind = typeof d.kind === "string" && d.kind ? d.kind : "other";
+        out.push({
+            code: "SELF_CHANGE",
+            source: "detectors",
+            severity: "advisory",
+            ref: { seq: e.seq, kind },
+            detail: "The agent reported a change to itself.",
+        });
+        if (!POWER_KINDS.includes(kind))
+            continue;
+        const id = typeof d.approval_id === "string" ? d.approval_id : null;
+        const at = id === null ? undefined : approved.get(id);
+        if (at !== undefined && at < e.seq)
+            continue;
+        out.push({
+            code: "SELF_CHANGE_UNAPPROVED",
+            source: "detectors",
+            severity: "warning",
+            ref: { seq: e.seq, kind, ...(id ? { approval_id: id } : {}) },
+            detail: "The agent gave itself more power (a tool, a policy or a model) with no approval approved before it.",
+        });
+    }
+    return out;
+}
+/**
+ * spec/findings.md §1c: the gateway stamps a request's system prompt fingerprint and, on the
+ * session's first one, the fingerprint the previous session with this label began with. A
+ * difference is PROMPT_CHANGED: advisory when the agent declared a prompt self-change before it,
+ * caution when nothing did.
+ */
+export function promptChanged(events) {
+    for (const e of events) {
+        const { system_sha256: after, system_sha256_prev: before } = e.meta;
+        if (e.kind !== "llm.request" || typeof after !== "string" || typeof before !== "string")
+            continue;
+        if (after === before)
+            return [];
+        const declared = events.some((s) => s.seq < e.seq &&
+            s.kind === "sdk.event" &&
+            s.meta.type === "self_change" &&
+            s.data?.kind === "prompt");
+        return [
+            {
+                code: "PROMPT_CHANGED",
+                source: "detectors",
+                severity: declared ? "advisory" : "caution",
+                ref: { seq: e.seq, before, after, declared },
+                detail: declared
+                    ? "The system prompt differs from the one the last run of this agent began with; the agent declared the change."
+                    : "The system prompt differs from the one the last run of this agent began with, and nothing declared the change.",
+            },
+        ];
+    }
+    return [];
+}
+/** At most this many codes in a lesson: the ones seen in the most runs. */
+const TOP = 10;
+/**
+ * spec/fleet.md §8: what earlier runs of one agent (its label) hit, from their summaries, newest
+ * first: outcomes, the finding codes by how many runs they were in and how many of those failed,
+ * the runs whose completion claim the record contradicted, and a short brief an agent can put in its
+ * own prompt. Codes and counts only, never content.
+ */
+export function lessons(summaries, label) {
+    const outcomes = { success: 0, failure: 0, abandoned: 0, unknown: 0 };
+    const codes = new Map();
+    let claimsFailed = 0;
+    let blocked = 0;
+    for (const s of summaries) {
+        const o = s.outcome;
+        const failed = o === "failure";
+        if (o === "success" || o === "failure" || o === "abandoned")
+            outcomes[o]++;
+        else
+            outcomes.unknown++;
+        if ((s.claims?.failed ?? 0) > 0)
+            claimsFailed++;
+        if (s.blocked_by)
+            blocked++;
+        for (const [code, n] of Object.entries(s.finding_codes ?? {})) {
+            const c = codes.get(code) ?? { sessions: 0, failed_sessions: 0, findings: 0, last_seen: "" };
+            c.sessions++;
+            if (failed)
+                c.failed_sessions++;
+            c.findings += n;
+            if (s.started_at > c.last_seen)
+                c.last_seen = s.started_at;
+            codes.set(code, c);
+        }
+    }
+    const top = [...codes.entries()]
+        .sort((a, b) => b[1].sessions - a[1].sessions || (a[0] < b[0] ? -1 : 1))
+        .slice(0, TOP)
+        .map(([code, c]) => ({
+        code,
+        title: FAULTS[code]?.en ?? null,
+        ...c,
+    }));
+    const n = summaries.length;
+    const name = label === null ? "this agent" : `"${label}"`;
+    let brief;
+    if (n === 0)
+        brief = `No earlier runs of ${name} on record.`;
+    else {
+        const parts = [`Lessons from the last ${n} run${n === 1 ? "" : "s"} of ${name}:`];
+        const counts = [`${outcomes.success} succeeded`, `${outcomes.failure} failed`];
+        if (outcomes.abandoned)
+            counts.push(`${outcomes.abandoned} abandoned`);
+        if (outcomes.unknown)
+            counts.push(`${outcomes.unknown} without an outcome`);
+        parts.push(`${counts.join(", ")}.`);
+        if (top.length)
+            parts.push(`Problems seen: ${top
+                .slice(0, 5)
+                .map((c) => `${c.code}${c.title ? ` (${c.title.toLowerCase()})` : ""} in ${c.sessions} run${c.sessions === 1 ? "" : "s"}${c.failed_sessions ? (c.sessions === 1 ? ", which failed" : `, ${c.failed_sessions} of them failed`) : ""}`)
+                .join("; ")}.`);
+        else
+            parts.push("No problems were found in them.");
+        if (claimsFailed)
+            parts.push(`${claimsFailed} run${claimsFailed === 1 ? "" : "s"} claimed to be done and the record disagreed.`);
+        if (blocked)
+            parts.push(`${blocked} run${blocked === 1 ? " was" : "s were"} stopped by the gateway.`);
+        if (top.length || claimsFailed)
+            parts.push("Avoid repeating these.");
+        brief = parts.join(" ");
+    }
+    return {
+        label,
+        sessions: n,
+        outcomes,
+        codes: top,
+        claims_failed_sessions: claimsFailed,
+        blocked_sessions: blocked,
+        brief,
+    };
+}

package/dist/analysis/taxonomy.js

@@ -56,6 +56,8 @@ export const TAXONOMY = {
     TOOL_CHANGED: { owasp: ["ASI04"], atlas: ["AML.T0110.002"] },
     TOOL_DRIFTED: { owasp: ["ASI04"], atlas: ["AML.T0110.002"] },
     PROMPT_INJECTION: { owasp: ["ASI01"], atlas: ["AML.T0051"] },
+    PROMPT_CHANGED: { owasp: ["ASI04"] },
+    SELF_CHANGE_UNAPPROVED: { owasp: ["ASI10"] },
     SECRET_SENT: { owasp: ["ASI03"], atlas: ["AML.T0057"] },
     TOOL_OUTPUT_MISMATCH: { owasp: ["ASI04", "ASI06"], atlas: ["AML.T0110.002", "AML.T0099"] },
     TOOL_WITNESS_INVALID: { owasp: ["ASI04"], atlas: ["AML.T0110.002"] },

package/dist/cost/index.js

@@ -127,7 +127,11 @@ export function tokensOf(usage) {
             cache_write: written,
         }, { input_audio: audioIn, output_audio: audioOut });
     }
-    if (Object.keys(usage).some((k) => k.startsWith("input_tokens_details_") || k.startsWith("output_tokens_details_"))) {
+    // 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;
+    if (!anthropicCache &&
+        Object.keys(usage).some((k) => k.startsWith("input_tokens_details_") || k.startsWith("output_tokens_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");

package/dist/fleet/insights.js

@@ -179,7 +179,11 @@ function value(v) {
     return JSON.stringify(short);
 }
 const isMoment = (e) => {
-    const status = e.meta?.status;
+    const meta = e.meta;
+    const status = meta?.status;
+    // an allowed policy check (one per local tool call) is routine, not a moment
+    if (e.kind === "control" && meta?.action === "policy_check" && meta.decision === "allow")
+        return false;
     return (e.kind === "finding" ||
         e.kind === "control" ||
         e.kind === "outcome" ||

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { A2A_STREAMING, type AgentCardReport, a2aMethod, a2aRequestMeta, a2aResp
 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";
-export { type Accuracy, type AnalyzeOptions, type AnswerClaims, analyze, answerClaims, answerCredential, answerRisk, answersOf, answerText, type ClaimEntry, type ClaimVerdict, type CriterionResult, canonicalNumber, checkAgainstPacks, checkFlightPlan, checkpointReplay, detectorAccuracy, dualWitness, Evidence, eventsOf, type Fact, type Finding as AnalysisFinding, factsIn, findingKey, type GroundedClaim, groundingFindings, groundingRequest, HOLD_TRIGGERS, identifiersIn, judgeFindings, judgeRequest, type Label as AccuracyLabel, type Landing, landing, loadReferencePacks, modelGroundingFindings, normaliseValue, OUTCOMES, type Outcome, type OutcomeRollup, packsFor, parseGroundingAnswer, parseJudgeAnswer, type ReferenceFact, type ReferencePack, type ReferenceVerdict, referenceContext, rollup, type Severity, schemaProblem, secretSent, toolDrifted, toolHallucinations, userDownvotes, verifyAnswerCredential, type WasteReason, type WasteReport, waste, wilsonLow, } from "./analysis/index.ts";
+export { type Accuracy, type AnalyzeOptions, type AnswerClaims, analyze, answerClaims, answerCredential, answerRisk, answersOf, answerText, type ClaimEntry, type ClaimVerdict, type CriterionResult, canonicalNumber, checkAgainstPacks, checkFlightPlan, checkpointReplay, detectorAccuracy, dualWitness, Evidence, eventsOf, type Fact, type Finding as AnalysisFinding, factsIn, findingKey, type GroundedClaim, groundingFindings, groundingRequest, HOLD_TRIGGERS, identifiersIn, judgeFindings, judgeRequest, type Label as AccuracyLabel, type Landing, landing, lessons, loadReferencePacks, modelGroundingFindings, normaliseValue, OUTCOMES, type Outcome, type OutcomeRollup, packsFor, parseGroundingAnswer, parseJudgeAnswer, promptChanged, type ReferenceFact, type ReferencePack, type ReferenceVerdict, referenceContext, rollup, type Severity, schemaProblem, secretSent, selfChanges, systemPromptHash, toolDrifted, toolHallucinations, userDownvotes, verifyAnswerCredential, type WasteReason, type WasteReport, waste, wilsonLow, } from "./analysis/index.ts";
 export { injectionFindings, injectionRule } from "./analysis/injection.ts";
 export { MITRE_ATLAS, OWASP_ASI, TAXONOMY, type Taxonomy, taxonomyOf, } from "./analysis/taxonomy.ts";
 export { type ApprovalFinding, approvalConfirmation, approvalFindings, argsHash, verifyConfirmation, } from "./approvals/index.ts";

package/dist/index.js

@@ -4,7 +4,7 @@ export { A2A_STREAMING, a2aMethod, a2aRequestMeta, a2aResponseMeta, a2aRestMetho
 export { causality, memoryXray } from "./agents/index.js";
 export { detectors, fingerprint } from "./analysis/detectors.js";
 export { FAULTS, faultOf } from "./analysis/faults.js";
-export { analyze, answerClaims, answerCredential, answerRisk, answersOf, answerText, canonicalNumber, checkAgainstPacks, checkFlightPlan, checkpointReplay, detectorAccuracy, dualWitness, Evidence, eventsOf, factsIn, findingKey, groundingFindings, groundingRequest, HOLD_TRIGGERS, identifiersIn, judgeFindings, judgeRequest, landing, loadReferencePacks, modelGroundingFindings, normaliseValue, OUTCOMES, packsFor, parseGroundingAnswer, parseJudgeAnswer, referenceContext, rollup, schemaProblem, secretSent, toolDrifted, toolHallucinations, userDownvotes, verifyAnswerCredential, waste, wilsonLow, } from "./analysis/index.js";
+export { analyze, answerClaims, answerCredential, answerRisk, answersOf, answerText, canonicalNumber, checkAgainstPacks, checkFlightPlan, checkpointReplay, detectorAccuracy, dualWitness, Evidence, eventsOf, factsIn, findingKey, groundingFindings, groundingRequest, HOLD_TRIGGERS, identifiersIn, judgeFindings, judgeRequest, landing, lessons, loadReferencePacks, modelGroundingFindings, normaliseValue, OUTCOMES, packsFor, parseGroundingAnswer, parseJudgeAnswer, promptChanged, referenceContext, rollup, schemaProblem, secretSent, selfChanges, systemPromptHash, toolDrifted, toolHallucinations, userDownvotes, verifyAnswerCredential, waste, wilsonLow, } from "./analysis/index.js";
 export { injectionFindings, injectionRule } from "./analysis/injection.js";
 export { MITRE_ATLAS, OWASP_ASI, TAXONOMY, taxonomyOf, } from "./analysis/taxonomy.js";
 export { approvalConfirmation, approvalFindings, argsHash, verifyConfirmation, } from "./approvals/index.js";

package/dist/otlp/index.js

@@ -398,7 +398,8 @@ function toOtlpV2(lines) {
         ],
     };
 }
-const LLM_OPS = new Set(["chat", "text_completion", "generate_content", "embeddings"]);
+// Spring AI says `embedding` (singular) for the semconv `embeddings`
+const LLM_OPS = new Set(["chat", "text_completion", "generate_content", "embeddings", "embedding"]);
 const MAX_SPANS = 5000;
 const MAX_DATA = 60_000;
 function anyValue(v) {
@@ -433,13 +434,20 @@ function attributes(list) {
 function spanType(a) {
     const op = a["gen_ai.operation.name"];
     const kind = a["openinference.span.kind"];
+    const spring = a["spring.ai.kind"]; // Spring AI's own span kinds
     if ((typeof op === "string" && LLM_OPS.has(op)) || kind === "LLM" || kind === "EMBEDDING")
         return "llm.call";
     if (op === "execute_tool" || kind === "TOOL")
         return "tool.call";
-    if (kind === "RETRIEVER")
+    if (kind === "RETRIEVER" || spring === "vector_store")
         return "retrieval";
-    if (op === "invoke_agent" || op === "create_agent" || kind === "AGENT" || kind === "CHAIN")
+    if (op === "invoke_agent" ||
+        op === "create_agent" ||
+        op === "framework" ||
+        kind === "AGENT" ||
+        kind === "CHAIN" ||
+        spring === "chat_client" ||
+        spring === "advisor")
         return "step";
     return "otel.span";
 }

package/dist/session/index.d.ts

@@ -1,3 +1,4 @@
+import { type Lessons } from "../analysis/learning.ts";
 import { type Attestation } from "../attest/index.ts";
 import { buildPayment, type screenCounterparty } from "../finance/index.ts";
 export interface SessionOptions {
@@ -368,6 +369,26 @@ 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/fleet.md §8: what earlier runs of this agent (this session's label) hit, to read before a
+     * run: outcomes, finding codes and a `brief` to put in the agent's own prompt. Codes and counts
+     * only. The gateway records that the agent read them. `null` when it can't be asked.
+     */
+    lessons(options?: {
+        limit?: number;
+    }): Promise<Lessons | 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
+     * more power (tool, policy, model) needs an approval approved first (`requestApproval`, then
+     * pass its id), or it is SELF_CHANGE_UNAPPROVED. Never throws.
+     */
+    selfChange(kind: string, options?: {
+        before?: string;
+        after?: string;
+        reason?: string;
+        approvalId?: string;
+    }): 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. */

package/dist/session/index.js

@@ -6,6 +6,7 @@ import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { SELF_CHANGE_KINDS } from "../analysis/learning.js";
 import { argsHash } from "../approvals/index.js";
 import { attest, isReadOnly, parseCommand } from "../attest/index.js";
 import { buildPayment, ftaPayload, screeningPayload, } from "../finance/index.js";
@@ -596,6 +597,43 @@ export class BlackboxSession {
         }
         return null;
     }
+    /**
+     * spec/fleet.md §8: what earlier runs of this agent (this session's label) hit, to read before a
+     * run: outcomes, finding codes and a `brief` to put in the agent's own prompt. Codes and counts
+     * only. The gateway records that the agent read them. `null` when it can't be asked.
+     */
+    async lessons(options = {}) {
+        if (!this.enabled)
+            return null;
+        const q = options.limit === undefined ? "" : `?limit=${Math.trunc(options.limit)}`;
+        try {
+            const r = await send("GET", this.options.url, `/v1/sessions/${this.id}/lessons${q}`, this.token);
+            if (r.status === 200)
+                return r.json;
+            this.fail("rejected", `reading the lessons: the gateway answered ${r.status}`);
+        }
+        catch (error) {
+            this.fail("network", `reading the lessons: ${message(error)}`);
+        }
+        return 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
+     * more power (tool, policy, model) needs an approval approved first (`requestApproval`, then
+     * pass its id), or it is SELF_CHANGE_UNAPPROVED. Never throws.
+     */
+    selfChange(kind, options = {}) {
+        const k = SELF_CHANGE_KINDS.includes(kind) ? kind : "other";
+        const sha = (text) => `sha256:${createHash("sha256").update(text).digest("hex")}`;
+        this.event("self_change", k, {
+            kind: k,
+            ...(options.before === undefined ? {} : { before_sha256: sha(options.before) }),
+            ...(options.after === undefined ? {} : { after_sha256: sha(options.after) }),
+            ...(options.reason ? { reason: options.reason.slice(0, 500) } : {}),
+            ...(options.approvalId ? { approval_id: options.approvalId.slice(0, 128) } : {}),
+        });
+    }
     /** 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. */

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.19.0";
+export declare const VERSION = "0.20.1";

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.19.0";
+export const VERSION = "0.20.1";

package/package.json

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