agentfootprint 6.45.0 → 7.0.0

package/AGENTS.md

@@ -484,6 +484,10 @@ live deep-Proxy) into `typedEmit`; use the plain local value (`typedEmit`
 dev-warns on unclonable payloads). Bench:
 `examples/features/21-deferred-observers.ts`.
 
+### Self-explain — `.selfExplain()` (the agent answers "why?" about its own last run)
+
+One builder call mounts ONE skill that, when the user asks a why-question, unlocks the 5 trace tools (`run_overview` / `trace_node` / `who_wrote` / `get_value` / `trace_slice`) for that iteration ONLY — bound LATE to the agent's PREVIOUS COMPLETED run (captured at `onRunEnd`/`onRunFailed`, so it can never serve an in-flight run; a failed run still explains "why did you fail?"). `delegate: { provider, model }` runs the trace-walk on a cheaper model via one `explain_run` tool. Requires `reactMode: 'dynamic'`/`'dynamic-grouped'` (classic caches the tools slot → throws at build); reserved tool-name clash also throws. Differs from **Causal memory**: `.selfExplain()` = THIS conversation's last run, in-memory, drill-by-id; Causal = any past run, persisted, recalled by similarity — reach for selfExplain on same-conversation follow-ups, Causal for cross-session. Note: Causal *similarity* recall needs a store with `search()` (only `InMemoryStore` today; Redis/AgentCore lack it). Full guide: docs `debug/self-explain`.
+
 ## Anti-Patterns — Don't
 
 - ❌ **Don't ship a `ReflexionAgent` class.** Compose `Sequence(Agent, critique-LLM, Agent)`.

package/CLAUDE.md

@@ -549,6 +549,10 @@ live deep-Proxy) into `typedEmit`; use the plain local value (`typedEmit`
 dev-warns on unclonable payloads). Bench:
 `examples/features/21-deferred-observers.ts`.
 
+### Self-explain — `.selfExplain()` (the agent answers "why?" about its own last run)
+
+One builder call mounts ONE skill that, when the user asks a why-question, unlocks the 5 trace tools (`run_overview` / `trace_node` / `who_wrote` / `get_value` / `trace_slice`) for that iteration ONLY — bound LATE to the agent's PREVIOUS COMPLETED run (captured at `onRunEnd`/`onRunFailed`, so it can never serve an in-flight run; a failed run still explains "why did you fail?"). `delegate: { provider, model }` runs the trace-walk on a cheaper model via one `explain_run` tool. Requires `reactMode: 'dynamic'`/`'dynamic-grouped'` (classic caches the tools slot → throws at build); reserved tool-name clash also throws. Differs from **Causal memory**: `.selfExplain()` = THIS conversation's last run, in-memory, drill-by-id; Causal = any past run, persisted, recalled by similarity — reach for selfExplain on same-conversation follow-ups, Causal for cross-session. Note: Causal *similarity* recall needs a store with `search()` (only `InMemoryStore` today; Redis/AgentCore lack it). Full guide: docs `debug/self-explain`.
+
 ## Anti-Patterns — Don't
 
 - ❌ **Don't ship a `ReflexionAgent` class.** Compose `Sequence(Agent, critique-LLM, Agent)`.

package/README.md

@@ -7,10 +7,15 @@
 </p>
 
 <p align="center">
-  The explainable agent framework: every read, write, decision, and tool call becomes
+  The explainable AI agent framework for TypeScript: every read, write, decision, and tool call becomes
   <strong>connected evidence</strong> as your agent runs. When something goes wrong, you don't grep logs — you ask.
 </p>
 
+<p align="center">
+  <strong>Build</strong> agents — skills, steering, RAG, memory, control flow — and <strong>debug</strong> them like nothing else.<br/>
+  <em>Why</em> is a query, not a guess.
+</p>
+
 <p align="center">
   <a href="https://footprintjs.github.io/agentThinkingUI/">
     <img src="docs/assets/hero-atui.png" alt="An agent run replayed in AgentThinkingUI — the LLM 'brain' calls the Flight-search tool, the step inspector shows the tool's raw output and the brain's reasoning about it, and the timeline scrubs every step of the run." width="100%">
@@ -65,159 +70,6 @@ structured so context is **evidence** — every injection, read, write, decision
 tool call recorded *connected*, the moment it happens. Not logs you grep. Evidence
 you ask.
 
-## How — we abstract context engineering
-
-Every piece of context enters the LLM through one of **3 slots** (`system` ·
-`messages` · `tools`), under one of **4 triggers** — skills, steering, RAG, facts,
-memory, guardrails are all the same move: `Injection = slot × trigger × cache`.
-
-**Because the framework owns that injection point, every piece of context is born
-tracked.** Tracking isn't an add-on you wire up — it's a consequence of the
-abstraction. [The full model ↓](#the-model--what-we-abstract)
-
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="docs/assets/hero-light.svg">
-    <img alt="agentfootprint mascot composing context flavors (Skills, Steering, Guardrails, RAG, Tool APIs, Memory) into three structured LLM slots (system, messages, tools) — the central abstraction, visualized." src="docs/assets/hero-light.svg" width="100%"/>
-  </picture>
-</p>
-
-## What tracking buys you
-
-**See it in 30 seconds** — four questions logs can't answer, each answered by code in this repo from a real run:
-
-```text
-Q: Why did the model pick refund_full instead of refund_partial?
-A: margin 0.02 — ⚠ NARROW: the two tool descriptions read nearly identical
-   (toolChoiceRecorder — and the catalog lint flags the pair before you ever run)
-
-Q: Why was this loan declined?
-A: decision ← [control: "DTI above the 0.43 affordability ceiling"] ← dti 0.52 ← monthlyDebt / income
-   (decide() evidence + the causal slice — every hop is a real recorded edge)
-
-Q: Which piece of context made the answer wrong?
-A: CAUSAL: ablating fact 'vip-override' flipped the outcome in 3/3 seeded reruns
-   (localizeContextBug — ranked proxies, counterfactual proof)
-
-Q: Prove nobody edited this run's record.
-A: verifyAuditBundle → valid: false, brokenAt: #16 — the tampered record, named
-   (hash-chained audit export, offline verification)
-```
-
-And you don't have to read the trace yourself — **we provide the tools for an LLM to track it for you**: the trace toolpack let a debugger model find a planted bug while reading **9.5% of the trace** ([guide](docs/guides/trace-debugging.md)).
-
-**And all this watching costs the run nothing.** Your agent *is* the event loop: a stage runs on the call stack and feeds its trace events into a queue; in the idle beat the dispatcher delivers them to your listeners and files them in trace memory — **one beat behind**, never blocking the hot path:
-
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/event-loop-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="docs/assets/event-loop-light.svg">
-    <img alt="Your agent is the event loop — animated. Left: your agent code (Context, Call LLM, Tool Calls) looping turn after turn. Right: the JS event loop drawn as two bold curved arrows with a traveling cursor and two stops — the call stack, where each stage runs as a frame and feeds four trace events (structure, data, control, emit) into the trace queue at the loop's center; and idle time, where the dispatcher flies the queued events into TRACE MEMORY and every listener (onStageAdded, onCommit, onDecision, onEmit) receives every event, one beat behind. Grey is JavaScript's own machinery, green is footprintjs, colors are your code and its trace." src="docs/assets/event-loop-light.svg" width="100%"/>
-  </picture>
-</p>
-
-## One contextual error, walked end to end
-
-The third question above, in full — every value below is the captured output of
-[`examples/observability/05-context-bisect.ts`](examples/observability/05-context-bisect.ts)
-and [`06-backtrack-trace.ts`](examples/observability/06-backtrack-trace.ts), runnable offline.
-
-**The bug.** A refunds agent carries a poisoned customer-profile fact. It answers:
-
-> *"Refund APPROVED: Dana Reyes holds VIP tier override status, so the 47-day-old
-> order qualifies for a refund beyond the 30-day window."*
-
-The policy says 30 days. The logs look fine — the model was *given* bad context,
-and classical logging has no row for that.
-
-**The walk.** Because context here is state, the decision backtracks like a
-variable: who read it, who wrote it, who let it in, where it was born —
-
-```text
-ANSWER   "Refund APPROVED…"                                   ← the bug
-READ     call-llm#40 assembled the system prompt              ← exactly what the model saw
-LANDED   context#6 wrote systemPromptInjections               ← who mutated state
-ALLOWED  trigger { kind: 'always' } — active every iteration  ← why it was let in
-BORN     defineFact('vip-override-fact')                      ← who wrote it
-```
-
-That chain gives the **complete, provable candidate set** — every piece of
-context that demonstrably reached the call, and nothing else. Influence scoring
-then *ranks* inside it (the two facts sit 0.01 apart — proxies can't separate
-them), and counterfactual **ablation proves**: removing `vip-override-fact`
-flips APPROVED → DECLINED in **3/3 seeded reruns**; the benign style fact and
-the lookup tool come back not-confirmed, 0/3. Scores are proxies; only the
-ablation verdict makes a causal claim — the report says so itself.
-
-**And when the proxy *can't* rank — it says so.** Output-similarity scoring is
-structurally blind to **absence/crowding** bugs (a key instruction truncated out
-of the window, context diluted by filler): the culprit doesn't resemble the
-answer, so it ranks low under an innocent. `rankingConfidence` is the honesty
-marker for that — when no source clearly wins, it returns a **shortlist to
-confirm by ablation** instead of a confident, wrong #1:
-
-```typescript
-import { rankingConfidence, ratioStrategy } from 'agentfootprint/observe';
-
-const c = rankingConfidence(scores); // over a scoreInfluence() result
-if (!c.clearWinner) ablate(c.shortlist); // too flat to trust → escalate to truth
-// decisiveness rule is pluggable: marginStrategy (default) · ratioStrategy
-// (scale-invariant) · bring-your-own. See docs/guides/ranking-confidence.md
-```
-
-**Three interfaces, one for each shape of the bug** — ship-a-default, bring-your-own:
-
-| interface | finds the culprit when it is… | confirm by |
-|---|---|---|
-| **influence ranking** (`scoreInfluence` + `rankingConfidence`) | **present** — orders suspects, says when it can't | — |
-| **ablation** (`localizeContextBug`) | **present** — *remove* it, see the outcome flip | removal |
-| **missing-context finder** (`findDroppedContext`) | **absent** — available but never reached the model (`available − sent`) | restoration |
-
-The third closes the gap the first two are blind to — a key instruction truncated
-out of the window has nothing to ablate. `findDroppedContext` is a cheap, exact id
-diff (no embeddings, no LLM); confirm by *restoration* — add the dropped unit back,
-see if the outcome flips. [Guide](docs/guides/missing-context.md) ·
-[example](examples/observability/10-missing-context.ts).
-
-**The same walk, visual.** One call serializes the report for
-[AgentThinkingUI](https://github.com/footprintjs/agentThinkingUI)'s
-`<BacktrackView>` — the "why?" board, triggerable from **any** decision point
-(final answer, a mid-loop tool choice, a deterministic `decide()` rule):
-
-```typescript
-import { localizeContextBug, toBacktrackTrace } from 'agentfootprint/observe';
-
-const report = await localizeContextBug({ artifacts, embedder, atStep, rerun });
-const trace = toBacktrackTrace(report, {
-  claim: 'The agent approved a refund 47 days past the 30-day window — why?',
-  answer: { text: buggyAnswer, label: 'the wrong answer' },
-});
-// <BacktrackView trace={trace}/> — or <BacktrackOverlay/> from any decision point
-```
-
-<img alt="The BacktrackView board: the wrong answer, the suspects with influence meters, the CAUSAL 3/3 ablation stamp on the planted fact, and the chain-of-custody rewind showing the exact system prompt the model saw with the culprit sentence highlighted." src="docs/assets/backtrack-board.png" width="100%"/>
-<p align="center">
-  <sub><a href="https://footprintjs.github.io/agentThinkingUI/demo/backtrack.html"><b>▶ Try the why-board live</b></a> — or run <a href="examples/observability/06-backtrack-trace.ts"><code>examples/observability/06-backtrack-trace.ts</code></a> offline.</sub>
-</p>
-
-The rewind pane at the bottom is the killer view: **the exact system prompt the
-model saw**, with the culprit sentence highlighted — recorded state, not a
-reconstruction. And the same chain feeds the machine door: every id on the
-board is a `runtimeStageId` a debugger LLM can drill with the
-[trace toolpack](docs/guides/trace-debugging.md), token-cheaply.
-
----
-
-## Pick your door
-
-| 🔧 Building an agent? | 🐛 Agent misbehaving? | 🏛️ Need audit / compliance? |
-|---|---|---|
-| Typed agents with skills, steering, RAG, memory, guardrails — and the trace for free. | Lint your tool catalog in 5 minutes — works on **any** framework's tool list (plain JSON / MCP / OpenAI / Anthropic shapes). Then causal slices, context bisection, and the debugger-LLM toolpack. | Hash-chained, tamper-evident run records with an offline verifier — record-keeping in the EU-AI-Act shape. |
-| [→ Quick start](#quick-start--runs-offline-no-api-key) · [→ Build ↓](#-build--design-your-agent-or-system-of-agents) | [→ Debug ↓](#-debug--see-what-your-agent-did) · [→ Tool-catalog lint](docs/guides/tool-catalog-lint.md) · [→ Trace debugging](docs/guides/trace-debugging.md) | [→ Audit ↓](#-audit--prove-what-happened) · [→ Security guide](docs/guides/security.md) |
-
----
-
 ## Quick start — runs offline, no API key
 
 ```bash
@@ -309,15 +161,127 @@ The fourth primitive is `Loop` — `Loop.repeat(agent).until(guard).times(5)`, w
 
 ---
 
-## The model — what we abstract
+## How — we abstract context engineering
 
+Skills, steering, RAG, facts, memory, guardrails — every name for context does one thing: it injects into one of three LLM slots. So we abstracted the injection itself.
 
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/hero-light.svg">
+    <img alt="agentfootprint mascot composing context flavors (Skills, Steering, Guardrails, RAG, Tool APIs, Memory) into three structured LLM slots (system, messages, tools) — the central abstraction, visualized." src="docs/assets/hero-light.svg" width="100%"/>
+  </picture>
+</p>
+<p align="center">
+  <sub><em>One primitive: <code>Injection = slot × trigger × cache</code>. Because the framework owns this point, every piece of context is <b>born tracked</b> — observability isn't wired up, it's a consequence of the abstraction. <a href="#the-model--what-we-abstract">The full model ↓</a></em></sub>
+</p>
 
-When you build an Agentic Application, you collect domain-specific data and instructions, then wire them up based on what your system receives.
+## What tracking buys you
 
-That data and those instructions wear many names — **Skills · Steering · Guardrails · RAG · Tool APIs · Memory** — with more on the way. But they all do the same thing: they **inject into one of three slots** in the LLM call (`system`, `messages`, `tools`).
+**See it in 30 seconds** — four questions logs can't answer, each answered by code in this repo from a real run:
 
-So we abstracted the injection itself.
+```text
+Q: Why did the model pick refund_full instead of refund_partial?
+A: margin 0.02 — ⚠ NARROW: the two tool descriptions read nearly identical
+   (toolChoiceRecorder — and the catalog lint flags the pair before you ever run)
+
+Q: Why was this loan declined?
+A: decision ← [control: "DTI above the 0.43 affordability ceiling"] ← dti 0.52 ← monthlyDebt / income
+   (decide() evidence + the causal slice — every hop is a real recorded edge)
+
+Q: Which piece of context made the answer wrong?
+A: CAUSAL: ablating fact 'vip-override' flipped the outcome in 3/3 seeded reruns
+   (localizeContextBug — ranked proxies, counterfactual proof)
+
+Q: Prove nobody edited this run's record.
+A: verifyAuditBundle → valid: false, brokenAt: #16 — the tampered record, named
+   (hash-chained audit export, offline verification)
+```
+
+And you don't have to read the trace yourself — the trace toolpack lets a debugger model do it: in one run it found a planted bug while reading **9.5% of the trace** ([guide](docs/guides/trace-debugging.md)).
+
+And the watching costs the run nothing:
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/event-loop-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/event-loop-light.svg">
+    <img alt="Your agent is the event loop — animated. Left: your agent code (Context, Call LLM, Tool Calls) looping turn after turn. Right: the JS event loop drawn as two bold curved arrows with a traveling cursor and two stops — the call stack, where each stage runs as a frame and feeds four trace events (structure, data, control, emit) into the trace queue at the loop's center; and idle time, where the dispatcher flies the queued events into TRACE MEMORY and every listener (onStageAdded, onCommit, onDecision, onEmit) receives every event, one beat behind. Grey is JavaScript's own machinery, green is footprintjs, colors are your code and its trace." src="docs/assets/event-loop-light.svg" width="100%"/>
+  </picture>
+</p>
+<p align="center">
+  <sub><em>Your agent <b>is</b> the event loop: each stage feeds its trace events into a queue on the call stack; the dispatcher delivers them to your listeners in the idle beat — <b>one beat behind</b>, never on the hot path.</em></sub>
+</p>
+
+## One contextual error, walked end to end
+
+The third question above, in full — every value below is the captured output of
+[`examples/observability/05-context-bisect.ts`](examples/observability/05-context-bisect.ts)
+and [`06-backtrack-trace.ts`](examples/observability/06-backtrack-trace.ts), runnable offline.
+
+**The bug.** A refunds agent carries a poisoned customer-profile fact. It answers:
+
+> *"Refund APPROVED: Dana Reyes holds VIP tier override status, so the 47-day-old
+> order qualifies for a refund beyond the 30-day window."*
+
+The policy says 30 days. The logs look fine — the model was *given* bad context,
+and classical logging has no row for that.
+
+**The walk.** Because context here is state, the decision backtracks like a
+variable: who read it, who wrote it, who let it in, where it was born —
+
+```text
+ANSWER   "Refund APPROVED…"                                   ← the bug
+READ     call-llm#40 assembled the system prompt              ← exactly what the model saw
+LANDED   context#6 wrote systemPromptInjections               ← who mutated state
+ALLOWED  trigger { kind: 'always' } — active every iteration  ← why it was let in
+BORN     defineFact('vip-override-fact')                      ← who wrote it
+```
+
+That chain is the **provable candidate set** — everything that demonstrably reached
+the call, nothing else. Influence scoring then *ranks* inside it, and counterfactual
+**ablation proves**: removing `vip-override-fact` flips APPROVED → DECLINED in
+**3/3 seeded reruns** (the benign fact and the lookup tool: 0/3). Scores are proxies;
+only ablation makes the causal claim.
+
+**Three interfaces, one per shape of bug** — ship-a-default, bring-your-own:
+
+| interface | finds the culprit when it is… | confirm by |
+|---|---|---|
+| **influence ranking** (`scoreInfluence` + `rankingConfidence`) | **present** — orders suspects, says when it can't rank | — |
+| **ablation** (`localizeContextBug`) | **present** — *remove* it, see the outcome flip | removal |
+| **missing-context finder** (`findDroppedContext`) | **absent** — available but never reached the model (`available − sent`) | restoration |
+
+The third closes a gap the first two are blind to: a key instruction truncated out of
+the window has nothing to ablate, so you confirm by *restoration*. And when scoring is
+too flat to trust, `rankingConfidence` returns a shortlist to confirm rather than a
+confident, wrong #1. Guides: [ranking-confidence](docs/guides/ranking-confidence.md) ·
+[missing-context](docs/guides/missing-context.md).
+
+**The same walk, visual.** `toBacktrackTrace()` serializes the report into
+[AgentThinkingUI](https://github.com/footprintjs/agentThinkingUI)'s `<BacktrackView>`
+— the "why?" board, triggerable from any decision point (final answer, a mid-loop tool
+choice, a deterministic `decide()` rule):
+
+<img alt="The BacktrackView board: the wrong answer, the suspects with influence meters, the CAUSAL 3/3 ablation stamp on the planted fact, and the chain-of-custody rewind showing the exact system prompt the model saw with the culprit sentence highlighted." src="docs/assets/backtrack-board.png" width="100%"/>
+<p align="center">
+  <sub><em>The wrong answer, suspects with influence meters, the <b>CAUSAL 3/3</b> ablation stamp on the planted fact, and the rewind showing the <b>exact system prompt the model saw</b> with the culprit highlighted — recorded state, not a reconstruction. Every id is a <code>runtimeStageId</code> a debugger LLM can drill via the <a href="docs/guides/trace-debugging.md">trace toolpack</a>. <a href="https://footprintjs.github.io/agentThinkingUI/demo/backtrack.html"><b>▶ Try it live</b></a> · run <a href="examples/observability/06-backtrack-trace.ts"><code>06-backtrack-trace.ts</code></a> offline.</em></sub>
+</p>
+
+---
+
+## Pick your door
+
+| 🔧 Building an agent? | 🐛 Agent misbehaving? | 🏛️ Need audit / compliance? |
+|---|---|---|
+| Typed agents with skills, steering, RAG, memory, guardrails — and the trace for free. | Lint your tool catalog in 5 minutes — works on **any** framework's tool list (plain JSON / MCP / OpenAI / Anthropic shapes). Then causal slices, context bisection, and the debugger-LLM toolpack. | Hash-chained, tamper-evident run records with an offline verifier — record-keeping in the EU-AI-Act shape. |
+| [→ Quick start](#quick-start--runs-offline-no-api-key) · [→ Build ↓](#-build--design-your-agent-or-system-of-agents) | [→ Debug ↓](#-debug--see-what-your-agent-did) · [→ Tool-catalog lint](docs/guides/tool-catalog-lint.md) · [→ Trace debugging](docs/guides/trace-debugging.md) | [→ Audit ↓](#-audit--prove-what-happened) · [→ Security guide](docs/guides/security.md) |
+
+---
+
+## The model — what we abstract
+
+You collect domain-specific data and instructions — **Skills · Steering · Guardrails · RAG · Tool APIs · Memory**, with more on the way. They all do one thing: **inject into one of three slots** (`system`, `messages`, `tools`). So we abstracted the injection itself.
 
 <p align="center">
   <picture>
@@ -491,8 +455,9 @@ const reflexion = Loop.create()
     <img alt="Classic ReAct vs Dynamic ReAct loop topology — same 5 stages (SystemPrompt, Messages, Tools, CallLLM, Route → ExecuteTools/Finalize), but the loop edge differs: Classic returns to CallLLM only (slots frozen at 12 tools every iteration), Dynamic returns to SystemPrompt (slots recompose, tools shrink from 1 to 5 as skills activate)." src="docs/assets/dynamic-vs-classic-light.svg" width="100%"/>
   </picture>
 </p>
-
-**Same five stages on both sides. Only one thing differs — where the loop returns.** Classic ReAct loops back to `CallLLM` and slots stay frozen. Dynamic ReAct (agentfootprint) loops back to `SystemPrompt`, so injections that fired on the previous tool result recompose the next prompt. Per-iteration recomposition is also the structural prerequisite for the cache layer.
+<p align="center">
+  <sub><em>Same five stages; only the loop edge differs. Classic returns to <code>CallLLM</code> with slots frozen; Dynamic (agentfootprint) returns to <code>SystemPrompt</code>, so injections recompose the next prompt — also the prerequisite for per-iteration caching.</em></sub>
+</p>
 
 | Iteration | Classic ReAct | Dynamic ReAct (agentfootprint) |
 |---|---|---|
@@ -521,8 +486,6 @@ const research = Loop.create()
   .build();
 ```
 
-Same `.create().method().build()` shape as the four rows above — just composed.
-
 ### Named patterns — also compositions of the same 4
 
 <p align="center">
@@ -563,11 +526,11 @@ Because we own the loop, every decision and execution is captured during travers
 
 The same trace serves three downstream consumers — no extra instrumentation:
 
-1. **Audit / compliance.** Six months later, *"why was loan #42 rejected?"* answers from the chain (`creditScore=580 < 620 ∧ dti=0.6 > 0.43 → riskTier=high → REJECTED`). No LLM call. GDPR Art. 22, ECOA, and EU AI Act adverse-action notices write themselves from the captured decision evidence.
-
-2. **Cheap-model triage.** A Sonnet trace becomes good *input* for Haiku to answer follow-ups. ~200 tokens at any model ($0.25/1M) vs ~2,500 tokens at a reasoning model ($15/1M). Memoization for agent thinking — no agent rerun.
-
-3. **Training data — the substrate is already there.** Every successful chain is a labeled trajectory. SFT pairs (`{prompt, completion}`) fall out of the snapshot's history field; the export wrapper is roadmap work tracked in [GitHub issues](https://github.com/footprintjs/agentfootprint/issues). DPO and process-RL need additional collection layers (preference feedback, per-step reward annotation) that don't ship today.
+| Consumer | What the trace gives you |
+|---|---|
+| **Audit / compliance** | Six months later, *"why was loan #42 rejected?"* answers from the chain (`creditScore=580 < 620 ∧ dti=0.6 > 0.43 → riskTier=high → REJECTED`) — no LLM call. GDPR Art. 22 / ECOA / EU AI Act adverse-action notices write themselves from the captured decision evidence. |
+| **Cheap-model triage** | A Sonnet trace is good *input* for Haiku to answer follow-ups: ~200 tokens ($0.25/1M) vs ~2,500 at a reasoning model ($15/1M). Memoized thinking — no agent rerun. |
+| **Training data** | Every successful chain is a labeled trajectory; SFT pairs fall out of the snapshot's history field. (The export wrapper, DPO, and process-RL need extra collection layers — [roadmap](https://github.com/footprintjs/agentfootprint/issues).) |
 
 Four views, one trace — pick by question:
 
@@ -650,6 +613,10 @@ undocumented optional params). The runtime counterpart, `toolChoiceRecorder`
 the same geometry and flags narrow margins and proxy disagreements — lazily,
 off the hot path.
 
+agentfootprint owns the *detection* — the scores, the ties, the recorded
+margins; you own the *policy* — the threshold, the embedder, the rewrite. We
+map; you decide.
+
 > 📖 **[Tool-catalog lint guide](docs/guides/tool-catalog-lint.md)** — 5 minutes
 > from a tools.json to a gated CI check ·
 > [`examples/observability/02`](examples/observability/02-lint-confusable-catalog.ts) ·
@@ -700,6 +667,11 @@ The flowchart, recorders, and tests don't change between dev and prod.
 
 ## What ships today
 
+<details>
+<summary><b>Full capability list</b> — core · 7 providers · memory + adapters · operability · debugging &amp; compliance · tooling</summary>
+
+<br/>
+
 **Core**
 - 2 primitives — `LLMCall`, `Agent` (the ReAct loop)
 - 4 control flows — `Sequence`, `Parallel`, `Conditional`, `Loop`
@@ -743,6 +715,8 @@ The flowchart, recorders, and tests don't change between dev and prod.
 - **Lens** · **Explainable Trace** — two visual replays of the causal trace (separate `agentfootprint-lens` package)
 - AI-coding-tool support — Claude Code · Cursor · Windsurf · Cline · Kiro · Copilot
 
+</details>
+
 > 📖 [Agent API reference](https://footprintjs.github.io/agentfootprint/api/agent/) · [CHANGELOG](./CHANGELOG.md)
 
 ---

package/ai-instructions/claude-code/SKILL.md

@@ -211,6 +211,17 @@ const causal = defineMemory({
 
 agent.memory(shortTerm).memory(facts).memory(causal);
 
+// `.selfExplain()` — the IN-CONVERSATION cousin of Causal: the agent answers a
+// follow-up "why did you do that?" about its OWN previous completed run, no store
+// needed. One builder call mounts a skill; the 5 trace tools (run_overview/
+// trace_node/who_wrote/get_value/trace_slice) appear ONLY on the iteration the user
+// asks "why", bound to the last completed run (never in-flight; a failed run still
+// explains). delegate:{provider,model} runs the trace-walk on a cheaper model.
+// Needs reactMode 'dynamic' (default). Causal = ANY past run, persisted, by similarity;
+// selfExplain = THIS conversation's last run, in-memory. (Causal similarity recall
+// needs a search()-capable store — only InMemoryStore today.) Docs: debug/self-explain.
+Agent.create({ provider, model }).system('...').tool(lookupOrder).selfExplain().build();
+
 // Multi-tenant identity — plumbs through agent.run:
 await agent.run({
   message: '...',

package/dist/adapters/llm/BrowserOpenAIProvider.js

@@ -177,7 +177,7 @@ const AZURE_BROWSER_SHORTHANDS = new Set([
  * proxy) or a backend. Same trade-off as `browserOpenai`.
  *
  * @example
- *   import { browserAzureOpenai } from 'agentfootprint';
+ *   import { browserAzureOpenai } from 'agentfootprint/llm-providers';
  *   const provider = browserAzureOpenai({
  *     endpoint: 'https://my-co.openai.azure.com',
  *     apiKey: userKey, apiVersion: '2024-12-01-preview', deployment: 'gpt-4o-128k',

package/dist/adapters/llm/MockProvider.js

@@ -157,7 +157,8 @@ exports.MockProvider = MockProvider;
  * `new MockProvider(options)`.
  *
  * @example
- *   import { Agent, mock, defineTool } from 'agentfootprint';
+ *   import { Agent, defineTool } from 'agentfootprint'
+import { mock } from 'agentfootprint/llm-providers';
  *
  *   const agent = Agent.create({ provider: mock({ reply: 'hello' }) })
  *     .tool(defineTool({ name: 'echo', ... }))

package/dist/adapters/llm/MockProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"MockProvider.js","sourceRoot":"","sources":["../../../src/adapters/llm/MockProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"MockProvider.js","sourceRoot":"","sources":["../../../src/adapters/llm/MockProvider.ts"],"names":[],"mappings":"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"}

package/dist/debug/finders.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * agentfootprint/debug/finders — context-error finder strategies.
+ *
+ * Collapsed home for what was the 3-level-deep
+ * `agentfootprint/observability/contextError/finders` path. Same
+ * tree-shakeable, re-export-only barrel — one finder = one file = one
+ * named export — now under the Debug category where it belongs.
+ *
+ * The old `agentfootprint/observability/contextError/finders` path is kept
+ * (deprecated) for one transition version.
+ */
+__exportStar(require("../observability/contextError/finders/index.js"), exports);
+//# sourceMappingURL=finders.js.map

package/dist/debug/finders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finders.js","sourceRoot":"","sources":["../../src/debug/finders.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;;GAUG;AACH,iFAA+D"}