@zanii/blackbox 0.20.1 → 0.21.0

package/dist/analysis/index.d.ts

@@ -103,4 +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";
+export { type Growth, growth, isoWeek, type Lessons, lessons, POWER_KINDS, promptChanged, SELF_CHANGE_KINDS, selfChanges, systemPromptHash, toolsHash, } from "./learning.ts";

package/dist/analysis/index.js

@@ -586,4 +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";
+export { growth, isoWeek, lessons, POWER_KINDS, promptChanged, SELF_CHANGE_KINDS, selfChanges, systemPromptHash, toolsHash, } from "./learning.js";

package/dist/analysis/learning.d.ts

@@ -52,3 +52,62 @@ export interface Lessons {
  * own prompt. Codes and counts only, never content.
  */
 export declare function lessons(summaries: readonly Summary[], label: string | null): Lessons;
+/**
+ * spec/fleet.md §9: the fingerprint of a model request's tool definitions: `sha256:` + hex over the
+ * canonical JSON of the sorted list of each tool's canonical JSON (so their order doesn't matter;
+ * Anthropic's `cache_control` on a tool is left out, it moves without changing the tool), from
+ * `tools` (Anthropic, OpenAI, Gemini) or Bedrock's `toolConfig.tools`. Null when there are none.
+ */
+export declare function toolsHash(body: unknown): string | null;
+/** The ISO week of a UTC timestamp: `2026-W41`. */
+export declare function isoWeek(ts: string): string;
+export interface Growth {
+    label: string | null;
+    sessions: number;
+    autonomy: Array<{
+        week: string;
+        sessions: number;
+        success: number;
+        failed: number;
+        autonomous: number;
+        autonomy_ppm: number;
+        failure_ppm: number;
+    }>;
+    versions: Array<{
+        id: string;
+        prompt: string | null;
+        tools: string | null;
+        model: string | null;
+        changed: string[];
+        sessions: number;
+        first_seen: string;
+        last_seen: string;
+        success_ppm: number;
+        spend_per_run_micro_usd: number;
+        human_steps: number;
+        declared: boolean;
+    }>;
+    versions_total: number;
+    learned: Array<{
+        session_id: string;
+        seq: number;
+        at: string;
+        kind: string;
+        approval_id: string | null;
+        approved: number;
+        corrected: number;
+        unknown: number;
+        checked: boolean;
+    }>;
+    hints: string[];
+}
+/**
+ * spec/fleet.md §9: how one agent (its label) grows, from its closed sessions' summaries, newest
+ * first. Autonomy per ISO week (a run done alone is a success with no human step, shown next to the
+ * failed runs, so an agent that stops asking and fails doesn't look better); its versions (the
+ * gateway's prompt and tools fingerprints and the model) with what changed and how each did; and
+ * the learned log, each self-change with the approvals it names checked against the window's.
+ */
+export declare function growth(summaries: readonly Summary[], label: string | null, options?: {
+    weeks?: number;
+}): Growth;

package/dist/analysis/learning.js

@@ -189,3 +189,142 @@ export function lessons(summaries, label) {
         brief,
     };
 }
+/**
+ * spec/fleet.md §9: the fingerprint of a model request's tool definitions: `sha256:` + hex over the
+ * canonical JSON of the sorted list of each tool's canonical JSON (so their order doesn't matter;
+ * Anthropic's `cache_control` on a tool is left out, it moves without changing the tool), from
+ * `tools` (Anthropic, OpenAI, Gemini) or Bedrock's `toolConfig.tools`. Null when there are none.
+ */
+export function toolsHash(body) {
+    if (!isObj(body))
+        return null;
+    const list = Array.isArray(body.tools)
+        ? body.tools
+        : isObj(body.toolConfig) && Array.isArray(body.toolConfig.tools)
+            ? body.toolConfig.tools
+            : [];
+    if (!list.length)
+        return null;
+    const parts = list
+        .map((t) => canonical(isObj(t) ? Object.fromEntries(Object.entries(t).filter(([k]) => k !== "cache_control")) : t))
+        .sort();
+    return `sha256:${createHash("sha256").update(canonical(parts)).digest("hex")}`;
+}
+/** The ISO week of a UTC timestamp: `2026-W41`. */
+export function isoWeek(ts) {
+    const d = new Date(Date.UTC(Number(ts.slice(0, 4)), Number(ts.slice(5, 7)) - 1, Number(ts.slice(8, 10))));
+    d.setUTCDate(d.getUTCDate() + 4 - (d.getUTCDay() || 7)); // the week's Thursday names its year
+    const year = d.getUTCFullYear();
+    const week = Math.floor((d.getTime() - Date.UTC(year, 0, 1)) / 86_400_000 / 7) + 1;
+    return `${year}-W${String(week).padStart(2, "0")}`;
+}
+const ppm = (n, d) => (d ? Math.floor((n * 1_000_000) / d) : 0);
+const VERSIONS = 20;
+const LEARNED = 50;
+/**
+ * spec/fleet.md §9: how one agent (its label) grows, from its closed sessions' summaries, newest
+ * first. Autonomy per ISO week (a run done alone is a success with no human step, shown next to the
+ * failed runs, so an agent that stops asking and fails doesn't look better); its versions (the
+ * gateway's prompt and tools fingerprints and the model) with what changed and how each did; and
+ * the learned log, each self-change with the approvals it names checked against the window's.
+ */
+export function growth(summaries, label, options = {}) {
+    const weeks = options.weeks ?? 12;
+    const runs = summaries.filter((s) => s.closed && s.label === label);
+    const byWeek = new Map();
+    for (const s of runs) {
+        const week = isoWeek(s.started_at);
+        const w = byWeek.get(week) ?? {
+            week,
+            sessions: 0,
+            success: 0,
+            failed: 0,
+            autonomous: 0,
+            autonomy_ppm: 0,
+            failure_ppm: 0,
+        };
+        w.sessions++;
+        if (s.outcome === "success") {
+            w.success++;
+            if (!s.human_steps)
+                w.autonomous++;
+        }
+        else if (s.outcome === "failure" || s.outcome === "abandoned")
+            w.failed++;
+        byWeek.set(week, w);
+    }
+    const autonomy = [...byWeek.values()]
+        .sort((a, b) => (a.week < b.week ? -1 : 1))
+        .slice(-weeks)
+        .map((w) => ({
+        ...w,
+        autonomy_ppm: ppm(w.autonomous, w.sessions),
+        failure_ppm: ppm(w.failed, w.sessions),
+    }));
+    const groups = new Map();
+    for (const s of runs)
+        if (s.version)
+            groups.set(s.version.id, [...(groups.get(s.version.id) ?? []), s]);
+    const all = [...groups.values()]
+        .map((ss) => {
+        const v = ss[0]?.version;
+        const starts = ss.map((s) => s.started_at).sort();
+        return {
+            id: v.id,
+            prompt: v.prompt,
+            tools: v.tools,
+            model: v.model,
+            changed: [],
+            sessions: ss.length,
+            first_seen: starts[0],
+            last_seen: starts[starts.length - 1],
+            success_ppm: ppm(ss.filter((s) => s.outcome === "success").length, ss.length),
+            spend_per_run_micro_usd: Math.floor(ss.reduce((n, s) => n + s.spend_micro_usd, 0) / ss.length),
+            human_steps: ss.reduce((n, s) => n + (s.human_steps ?? 0), 0),
+            declared: ss.some((s) => (s.self_changes?.length ?? 0) > 0),
+        };
+    })
+        .sort((a, b) => a.first_seen < b.first_seen ? -1 : a.first_seen > b.first_seen ? 1 : a.id < b.id ? -1 : 1);
+    for (let i = 1; i < all.length; i++) {
+        const [p, v] = [all[i - 1], all[i]];
+        v.changed = ["prompt", "tools", "model"].filter((k) => p[k] !== v[k]);
+    }
+    const decided = new Map();
+    for (const s of runs)
+        for (const [id, d] of Object.entries(s.approvals ?? {}))
+            decided.set(id, d);
+    const learned = [];
+    for (const s of runs)
+        for (const c of [...(s.self_changes ?? [])].reverse()) {
+            if (learned.length === LEARNED)
+                break;
+            const found = c.taught_by.map((id) => decided.get(id));
+            const approved = found.filter((d) => d === "approve").length;
+            const corrected = found.filter((d) => d === "reject").length;
+            const unknown = found.length - approved - corrected;
+            learned.push({
+                session_id: s.session_id,
+                seq: c.seq,
+                at: c.at,
+                kind: c.kind,
+                approval_id: c.approval_id,
+                approved,
+                corrected,
+                unknown,
+                checked: found.length > 0 && unknown === 0,
+            });
+        }
+    const hints = [];
+    // a prompt that embeds the date or a request id is a new version every run
+    if (runs.length >= 10 && all.length * 2 > runs.length)
+        hints.push("many_versions");
+    return {
+        label,
+        sessions: runs.length,
+        autonomy,
+        versions: all.slice(-VERSIONS),
+        versions_total: all.length,
+        learned,
+        hints,
+    };
+}

package/dist/fleet/index.d.ts

@@ -33,7 +33,31 @@ export interface Summary {
     };
     blocked_by: string | null;
     near_misses: number;
+    /** spec/fleet.md §9: which version of the agent ran (only when it called a model) */
+    version?: {
+        id: string;
+        prompt: string | null;
+        tools: string | null;
+        model: string | null;
+    };
+    /** spec/fleet.md §9: the times a person stepped in (only when one did) */
+    human_steps?: number;
+    /** spec/fleet.md §9: the changes the agent reported to itself, the first 10 */
+    self_changes?: SelfChangeEntry[];
+    /** spec/fleet.md §9: approvals a person decided here, the first 50: id → approve | reject */
+    approvals?: Record<string, "approve" | "reject">;
+}
+export interface SelfChangeEntry {
+    seq: number;
+    at: string;
+    kind: string;
+    approval_id: string | null;
+    taught_by: string[];
 }
+/** An approval id: what a lesson may point at, and nothing else (spec/fleet.md §9). */
+export declare const APPROVAL_ID: RegExp;
+/** spec/fleet.md §9: the approval ids a self-change names as what taught it, at most 20. */
+export declare function taughtBy(v: unknown): string[];
 export declare function sessionSummary(lines: readonly string[], bodies: Bodies, prices: LoadedPrices): Summary;
 /** The incident report (spec/fleet.md §2) in Markdown, in English or Arabic. */
 export declare function incidentReport(lines: readonly string[], bodies: Bodies, prices: LoadedPrices, lang: "en" | "ar"): string;

package/dist/fleet/index.js

@@ -10,6 +10,45 @@ import { authorityTimeline } from "../authority/index.js";
 import { formatAed, sessionCost, toAedFils } from "../cost/index.js";
 import { callsOf } from "../reconcile/record.js";
 import { canonical } from "../reconcile/shared.js";
+/** An approval id: what a lesson may point at, and nothing else (spec/fleet.md §9). */
+export const APPROVAL_ID = /^apr_[0-9a-f]{18}$/;
+/** spec/fleet.md §9: the approval ids a self-change names as what taught it, at most 20. */
+export function taughtBy(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const x of v)
+        if (typeof x === "string" && APPROVAL_ID.test(x) && !out.includes(x) && out.length < 20)
+            out.push(x);
+    return out;
+}
+/** The agent's version: the first request's prompt and tools fingerprints, the first model. Only
+ * when the gateway fingerprinted that request: a version is evidence, never a guess. */
+function versionOf(events) {
+    const req = events.find((e) => e.kind === "llm.request");
+    const str = (v) => (typeof v === "string" ? v : null);
+    const prompt = str(req?.meta.system_sha256);
+    const tools = str(req?.meta.tools_sha256);
+    if (prompt === null && tools === null)
+        return undefined;
+    const model = str(events.find((e) => e.kind === "llm.response")?.meta.model);
+    const id = `ver_${createHash("sha256")
+        .update(canonical([prompt, tools, model]))
+        .digest("hex")
+        .slice(0, 12)}`;
+    return { id, prompt, tools, model };
+}
+/** A person stepping in: an approval they decided, a resume, an authority change, an `ask`. */
+function isHumanStep(e) {
+    if (e.kind !== "control")
+        return false;
+    const m = e.meta;
+    if (m.action === "approval")
+        return (m.decision === "approve" || m.decision === "reject") && m.by !== "classifier";
+    if (m.action === "policy_check")
+        return m.decision === "ask";
+    return m.action === "resume" || m.action === "authority";
+}
 const sorted = (m) => Object.fromEntries(Object.keys(m)
     .sort()
     .map((k) => [k, m[k]]));
@@ -30,7 +69,22 @@ export function sessionSummary(lines, bodies, prices) {
     let outcome = null;
     let blockedBy = null;
     let nearMisses = 0;
+    let humanSteps = 0;
+    const approvals = {};
+    let decided = 0;
     for (const e of events) {
+        if (isHumanStep(e))
+            humanSteps++;
+        if (e.kind === "control" &&
+            e.meta.action === "approval" &&
+            (e.meta.decision === "approve" || e.meta.decision === "reject") &&
+            e.meta.by !== "classifier" &&
+            typeof e.meta.approval_id === "string" &&
+            !(e.meta.approval_id in approvals) &&
+            decided < 50) {
+            approvals[e.meta.approval_id] = e.meta.decision;
+            decided++;
+        }
         if (e.kind === "tool.call" &&
             e.meta.method === "tools/call" &&
             typeof e.meta.tool === "string") {
@@ -59,8 +113,23 @@ export function sessionSummary(lines, bodies, prices) {
             nearMisses++;
     }
     const claims = { satisfied: 0, failed: 0, unverified: 0 };
-    for (const c of landing(eventsOf(lines, bodies), lines, bodies).claims)
+    const evs = eventsOf(lines, bodies);
+    for (const c of landing(evs, lines, bodies).claims)
         claims[c.verdict]++;
+    const selfChanges = evs
+        .filter((e) => e.kind === "sdk.event" && e.meta.type === "self_change")
+        .slice(0, 10)
+        .map((e) => {
+        const d = e.data ?? {};
+        return {
+            seq: e.seq,
+            at: e.ts,
+            kind: typeof d.kind === "string" && d.kind ? d.kind : "other",
+            approval_id: typeof d.approval_id === "string" ? d.approval_id : null,
+            taught_by: taughtBy(d.taught_by),
+        };
+    });
+    const version = versionOf(events);
     const inControl = authorityTimeline(lines).at(-1)?.mode ?? "agent";
     return {
         session_id: first.session_id,
@@ -89,6 +158,10 @@ export function sessionSummary(lines, bodies, prices) {
         claims,
         blocked_by: blockedBy,
         near_misses: nearMisses,
+        ...(version ? { version } : {}),
+        ...(humanSteps ? { human_steps: humanSteps } : {}),
+        ...(selfChanges.length ? { self_changes: selfChanges } : {}),
+        ...(decided ? { approvals } : {}),
     };
 }
 const T = {

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, 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 { 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, growth, HOLD_TRIGGERS, identifiersIn, isoWeek, 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, toolsHash, 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";
@@ -30,7 +30,7 @@ export { openSegments, type SealedSegment } from "./encryption/index.ts";
 export { type EvidencePack, type EvidencePackOptions, evidencePack, renderEvidencePack, } from "./evidence/index.ts";
 export { buildEquivocationProof, compareViews, cosignLedgerSth, verifyEquivocationProof, verifyLedgerCosignature, } from "./federation/index.ts";
 export { buildOwnerAttestation, buildPayment, CURRENCIES, FTA_WALL_ID, financeFindings, formatMoney, ftaPayload, parseMoney, paymentsOf, screenCounterparty, screeningPayload, verifyOwnerAttestation, verifyOwnerBinding, } from "./finance/index.ts";
-export { aggregateFindings, airworthiness, type Collision, collisions, didFromSeed, type FindingGroup, incidentReport, logbook, type Summary, sessionSummary, signatureOf, signatures, signCertificate, verifyCertificate, } from "./fleet/index.ts";
+export { APPROVAL_ID, aggregateFindings, airworthiness, type Collision, collisions, didFromSeed, type FindingGroup, incidentReport, logbook, type Summary, sessionSummary, signatureOf, signatures, signCertificate, taughtBy, verifyCertificate, } from "./fleet/index.ts";
 export { copilotContext, copilotPrompt, type Insights, insights, parseCopilotAnswer, } from "./fleet/insights.ts";
 export { type AppealItem, type AppealPack, appealPack, decisionPayload, GOV_DECISION_KINDS, renderAppealPack, ruleConsistency, signSubjectClaim, subjectTag, verifyDecision, verifyFactors, verifySubjectClaim, } from "./gov/index.ts";
 export { accessPayload, breakGlass, checkEpisodeTag, clinicianConfirmation, type EpisodeItem, episodeSeed, episodesPack, episodeTag, healthFindings, protocolTrail, recommendationHash, recommendationPayload, verifyCommitment, verifyHealthSignature, } from "./health/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, 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 { analyze, answerClaims, answerCredential, answerRisk, answersOf, answerText, canonicalNumber, checkAgainstPacks, checkFlightPlan, checkpointReplay, detectorAccuracy, dualWitness, Evidence, eventsOf, factsIn, findingKey, groundingFindings, groundingRequest, growth, HOLD_TRIGGERS, identifiersIn, isoWeek, judgeFindings, judgeRequest, landing, lessons, loadReferencePacks, modelGroundingFindings, normaliseValue, OUTCOMES, packsFor, parseGroundingAnswer, parseJudgeAnswer, promptChanged, referenceContext, rollup, schemaProblem, secretSent, selfChanges, systemPromptHash, toolDrifted, toolHallucinations, toolsHash, 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";
@@ -32,7 +32,7 @@ export { openSegments } from "./encryption/index.js";
 export { evidencePack, renderEvidencePack, } from "./evidence/index.js";
 export { buildEquivocationProof, compareViews, cosignLedgerSth, verifyEquivocationProof, verifyLedgerCosignature, } from "./federation/index.js";
 export { buildOwnerAttestation, buildPayment, CURRENCIES, FTA_WALL_ID, financeFindings, formatMoney, ftaPayload, parseMoney, paymentsOf, screenCounterparty, screeningPayload, verifyOwnerAttestation, verifyOwnerBinding, } from "./finance/index.js";
-export { aggregateFindings, airworthiness, collisions, didFromSeed, incidentReport, logbook, sessionSummary, signatureOf, signatures, signCertificate, verifyCertificate, } from "./fleet/index.js";
+export { APPROVAL_ID, aggregateFindings, airworthiness, collisions, didFromSeed, incidentReport, logbook, sessionSummary, signatureOf, signatures, signCertificate, taughtBy, verifyCertificate, } from "./fleet/index.js";
 export { copilotContext, copilotPrompt, insights, parseCopilotAnswer, } from "./fleet/insights.js";
 export { appealPack, decisionPayload, GOV_DECISION_KINDS, renderAppealPack, ruleConsistency, signSubjectClaim, subjectTag, verifyDecision, verifyFactors, verifySubjectClaim, } from "./gov/index.js";
 export { accessPayload, breakGlass, checkEpisodeTag, clinicianConfirmation, episodeSeed, episodesPack, episodeTag, healthFindings, protocolTrail, recommendationHash, recommendationPayload, verifyCommitment, verifyHealthSignature, } from "./health/index.js";

package/dist/session/index.d.ts

@@ -388,6 +388,8 @@ export declare class BlackboxSession {
         after?: string;
         reason?: string;
         approvalId?: string;
+        /** The approvals (ids) that taught it this, and nothing else: never content (fleet.md §9). */
+        taughtBy?: readonly 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

package/dist/session/index.js

@@ -10,6 +10,7 @@ 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";
+import { taughtBy } from "../fleet/index.js";
 import { decisionPayload } from "../gov/index.js";
 import { accessPayload, checkEpisodeTag, recommendationPayload, verifyHealthSignature, } from "../health/index.js";
 import { memoryEntry } from "../memory/index.js";
@@ -624,6 +625,7 @@ export class BlackboxSession {
      * pass its id), or it is SELF_CHANGE_UNAPPROVED. Never throws.
      */
     selfChange(kind, options = {}) {
+        const taught = taughtBy(options.taughtBy);
         const k = SELF_CHANGE_KINDS.includes(kind) ? kind : "other";
         const sha = (text) => `sha256:${createHash("sha256").update(text).digest("hex")}`;
         this.event("self_change", k, {
@@ -632,6 +634,7 @@ export class BlackboxSession {
             ...(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) } : {}),
+            ...(taught.length ? { taught_by: taught } : {}),
         });
     }
     /** spec/findings.md §13.1: what in an answer (the latest, or the one at `seq`) would hold it,

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.20.1";
+export declare const VERSION = "0.21.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.20.1";
+export const VERSION = "0.21.0";

package/package.json

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