agentfootprint 9.92.1 → 9.94.0

package/CHANGELOG.md

@@ -7,6 +7,204 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.94.0] - 2026-09-11
+
+**An optional family is loaded when its option is enabled, never before.** What
+`import { Agent, defineTool } from 'agentfootprint'` costs a browser consumer
+is the library's DEFAULT graph, not its whole surface — and for four releases
+it was not: the docs site's demo chunk grew 394 → 421 KB gzip across 9.61,
+9.78, 9.88 and 9.92 for families the demo never calls, and two publishes
+(9.87.0, 9.92.0) were lost to that ceiling. Measured on this commit, same
+webpack build: the demo chunk 421.3 → 382.4 KB gzip (−38.9 KB, 16 → 15 async
+assets; the library's own chunk 199.6 → 171.4 KB), and a plain esbuild bundle
+of the root import 219.3 → 199.7 KB gzip (−19.6 KB, 717.7 → 658.2 KB minified).
+Two root causes, both in the library, so every consumer gets the same cut. A
+minor rather than a patch because a public provider's `list()` changes shape on
+one iteration (below), and because every bundled consumer's output changes.
+
+### Changed
+
+- **`.selfExplain()` mounts the trace toolpack lazily.** The toolpack —
+  eleven tools over a finished trace, at 47 KB minified the largest single
+  module in the package — was on the default graph because `AgentBuilder`
+  imported it for `TRACE_TOOL_NAMES`, the list of names it reserves at
+  `build()`, and `buildSelfExplainToolProvider` composed the pack eagerly.
+  WHY: an agent that never calls `.selfExplain()` was shipping the debugger;
+  one that does was shipping it before a single turn had run. Now the names
+  live in `lib/trace-toolpack/traceToolNames.ts` (with
+  `NO_COMPLETED_RUN_MESSAGE`, the other fact needed before the pack exists —
+  both still re-exported from their old modules), and the inline provider
+  reaches the pack through `import()` on the first iteration the self-explain
+  skill is ACTIVE: not at `build()`, not on a turn where nobody asked why,
+  never for an agent without the option. A bundler splits it into its own
+  chunk; Node loads it through the same `require`, one microtask later. The
+  one visible change: on an active iteration the inline provider's `list(ctx)`
+  answers a `Promise<Tool[]>` where it answered an array — the shape
+  `ToolProvider.list` has always allowed and the composed provider already
+  used; the idle iteration is still a synchronous `[]`, so the tools slot's
+  fast path is untouched. Provider id, the reserved-name refusal, delegate
+  mode and every trace tool are unchanged.
+  `test/lib/trace-toolpack/lazyMount.test.ts` pins load-when-active (the
+  module is evaluated exactly once, on that iteration), end-to-end answering
+  through the lazy path, and cold-mount = warm-mount on the recorded events,
+  catalogs and answers.
+  ```ts
+  const agent = Agent.create({ provider, model }).tool(lookup).selfExplain().build();
+  await agent.run({ message: 'Refund order A-1001?' });   // pack not loaded
+  await agent.run({ message: 'Why did you approve it?' }); // loads on the iteration read_skill opened it
+  ```
+- **The ESM build now carries `sideEffects`.** A bundler reads that flag from
+  the CLOSEST package.json to the module it is deciding about, and
+  `dist/esm/package.json` — written at postbuild to mark the build
+  `type:module` — was a bare `{"type":"module"}`. WHY: the root's honest
+  `sideEffects` list therefore never reached a single ESM module; webpack,
+  Vite and esbuild had to presume every file under `dist/esm` might run
+  something at load, keep each one a barrel named, and could only strip the
+  pure declarations inside — which is also why a dynamic `import()` of a
+  module a barrel re-exports (the toolpack, through the `/observe` door the
+  lens imports) never split into its own chunk. `scripts/postbuild-esm.mjs`
+  now copies the root list across, rebased (`scripts/lib/esmSideEffects.mjs`;
+  `test/esm-packaging.test.ts` pins the shipped file against the same rule).
+  The list was widened only where it is TRUE: `./dist/index.js` /
+  `./dist/esm/index.js` (the root entry imports the three cache strategies for
+  their `registerCacheStrategy` calls) and `**/lib/injection-engine/index.js`
+  (the barrel imports `devWarnHost` to bind footprintjs's dev flag) — a barrel
+  marked side-effect-free is a barrel a bundler may skip, imports and all.
+  `test/lib/trace-toolpack/browserGraph.test.ts` proves at the code-split
+  graph that the toolpack is off the root entry's sync closure, still
+  reachable behind a `dynamic-import` edge, statically present on `/observe`
+  by design, and that every registration survives (the three strategies on
+  the root entry, the dev-warn host on `/context`). footprintjs's own
+  `dist/esm/package.json` has carried its flag all along; this follows it.
+
+### Docs
+
+- `docs-next/scripts/check-site-budget.mjs`: the LAW above the demo ceiling
+  (an optional family loads when its option is enabled; the demo bundle
+  measures the default graph), the two families this release could not move
+  and why — the integrity checks run inside synchronous stage helpers and one
+  (`wireViolationsOf`) is unconditional; the observability recorders sit
+  behind `enable.flowchart()` / `enable.localObservability()`, which return
+  synchronously — and the ceiling LOWERED 429.4 → 390.0 KB (~2% over 382.4).
+  `DOCS_WEBPACK_STATS=1` on the docs build writes per-module webpack stats and
+  `docs-next/scripts/demo-chunk-modules.mjs` names what the demo chunk
+  carries, so the next raise is argued per module, not per ceiling.
+- README "Tree-shakeable & ESM-first" and docs/debug/self-explain: the rule,
+  the example, the fences.
+
+## [9.93.0] - 2026-09-11
+
+**The receipt says which strategy, and what the window dropped.** Four of the
+seven standing recorded-not-built entries close, one is verified rather than
+rebuilt, and one is assessed and half-built. Every item below is a behaviour
+change to a shipped record — a new receipt key on every minting chart, a gap
+that stops firing on three of them, a field that starts being written — which
+is why this is a minor and not a patch. Nothing that had no name collision, no
+window and no cache strategy records a different byte except the one new key.
+
+### Added
+
+- **`Receipt.cache.strategy: string | null`** — WHICH cache strategy the
+  request went through (its registry `providerName`; `'*'` is the built-in
+  pass-through every agent runs), or `null` where none stood between assembly
+  and the port. WHY: `cache.transform: 'unchanged'` is the honest verdict both
+  when a strategy returned what it was given and when there was no strategy at
+  all, so the served view had no way to know a rewrite was impossible and
+  raised `cache-transform` on every view — including `LLMCall` and the two
+  message-API charts, where a reader was told what a cache strategy may have
+  done beside a call none could touch (entry 8). No fourth `transform` value
+  was added; the fact is its own field, minted by the one owner
+  (`buildReceipt` refuses to mint without it). A receipt from before this
+  release has no key, and a reader treats that as "cannot say", never as
+  `null`.
+  ```ts
+  receiptAt(agent.getSnapshot()!, 1)!.cache.strategy;   // '*'  — an agent on the mock provider
+  receiptAt(llmCall.getSnapshot()!, 1)!.cache.strategy; // null — nothing between assembly and the port
+  ```
+- **`Receipt.omittedForAttention` is written** — by the agent chart's window
+  stage, for every turn it evicts for budget at an iteration's head. WHY: the
+  field was declared in 9.88.0 for "why did the model not know that?" and
+  excused as "no chart in this library supplies it" (entry 9) — a measurement
+  that had looked at the slots, which drop nothing, and not at the window,
+  which does (`context.evicted`, `reason: 'budget'`), and never wrote it. The
+  window hands what left to the call-llm mint on an in-memory handle
+  (`window/evictedTurns.ts`), the seam the compaction meter already crosses —
+  never a scope read, which on every windowless run would be a tracked read of
+  an absent key and a phantom context source per loop. Each hash is the
+  evicted turn's own `messages.entries[].hash`, so a drop on epoch k's receipt
+  pairs with the turn as an earlier receipt served it — the pairing law,
+  driven on a real sliding window. Absent now means nothing was dropped before
+  that call. The field left `UNGAPPED_FIELDS` and is named by
+  `no-receipt-on-chart`, the one gap that can lose it. An agent without a
+  window hands both stages the deps they always had.
+  ```ts
+  const agent = Agent.create({ provider, model }).system('bot').tool(lookup)
+    .window(slidingWindow({ keepRecentTurns: 1 })).build();
+  await agent.run({ message: 'go' });
+  receiptAt(agent.getSnapshot()!, 3)!.omittedForAttention; // { count: 2, hashes: [...] } — the pair that left at this head
+  ```
+
+### Changed
+
+- **`cache-transform` is raised only where a rewrite was possible** — where
+  the receipt names a strategy, or where no receipt can say (a receipt-less
+  view, a pre-9.93.0 receipt, a refused shape). WHY: entry 8 — a sentence
+  about what a strategy may have done was printed where none could run. Only a
+  receipt that SAYS `null` lifts it; absence still raises, so this is not the
+  inference-from-absence the entry refused. Measured: `LLMCall` and both
+  message-API charts with a run id now read `['provider-defaults']`; the
+  receipt-less message-API view still reads
+  `['no-receipt-on-chart', 'cache-transform']`, honestly. The printed sentence
+  is unchanged and every clause of it still holds where it prints.
+  ```ts
+  servedAt(llmCall.getSnapshot()!, 1)!.gaps.map((g) => g.gap); // ['provider-defaults'] (was ['cache-transform', 'provider-defaults'])
+  ```
+- **`cache-transform` names `tools.forced`, `tools.withheld` and
+  `cache.strategy`** — fourteen fields, the whole request the strategy holds
+  (`params` alone stays off, read past it). WHY: entry 7 — both `tools`
+  fields are written from assembly's own decision and never from
+  `preparedRequest`, so a strategy that drops the forced answer tool from
+  `request.tools` leaves a receipt whose `tools.forced` names a tool the port
+  never carried, and the gap did not warn. Driven: an unforcing strategy on a
+  `'tool-forced'` agent — wire has no tool and no forcing, receipt says
+  `tools.forced: 'respond_with_schema'` and `params.toolChoice` absent, the
+  gap names the half that describes the decision. Reading them off the
+  prepared request instead was NOT done: that would describe a different fact
+  under the same name.
+- **The receipt-conformance law checks the cache verdict outright where no
+  strategy ran** — `transform: 'unchanged'`, `transformHash: null`,
+  `markersApplied: []`, and no `cache-transform` excuse; where one ran, the gap
+  must excuse the unrebuildable fields as before.
+- **Byte-identity references regenerated** (`test/core/tools/reference/`),
+  with the whole delta against the 9.92.1 set on record in the test's header:
+  the new `cache.strategy` key on every minting fixture, the gap's longer
+  field list on every agent view, and the gap leaving the three no-strategy
+  views. No message, tool or other key moved on any fixture.
+
+### Verified
+
+- **Recorded-not-built entries 4 and 5 hold under the 9.92.0 law** and are
+  marked built (verified 2026-09-11 against the 9.92.1 `dist`, before any edit
+  of this release). `.selfExplain()`'s `run_overview` against an always-visible
+  skill, a never-activated scoped skill and a stepped skill: dispatch follows
+  the offer on every epoch (the never-activated skill no longer answers the
+  framework's own contract — the framework does), `tools.shadowed` names the
+  wire's party and never `provider(skill-scoped:self-explain)`, and the losing
+  claim is named by `tools.claim_swallowed` on every epoch it lost. The
+  reservation this entry names is deliberately untouched; the measured output
+  is pasted on the entries and pinned as `offer-and-answer.test.ts` §7.
+
+### Assessed
+
+- **Entry 10 ("an assertion can be weaker than its clause") is split, and the
+  mechanical half is built.** Every clause in `gap-sentences.test.ts` declares
+  the fields it is about; a seam hands its assertion a view or receipt with
+  one declared field altered, then removed; a contract requires the assertion
+  to fail under at least one. The first run found one insensitivity and it is
+  fixed. What remains is the quantifier half — a clause about "every field" or
+  "both chart shapes" asserted on fewer runs — which needs per-clause hand
+  work and is named on the entry rather than faked by a mechanism.
+
 ## [9.92.1] - 2026-09-11
 
 ### Fixed

package/README.md

@@ -975,8 +975,9 @@ Import one thing, ship one thing. agentfootprint is built so your bundle grows o
 - **Per-file modules + honest `sideEffects`.** The dist is emitted file-by-file (never pre-bundled), so bundlers drop every export you don't touch. A small `import { defineTool }` doesn't pull in the Agent runtime, injection engine, memory stores, or LLM providers.
 - **Ten doors, named for what you're doing.** `agentfootprint` · `/providers` (plug in a backend) · `/memory` (state that outlives a turn) · `/observe` (everything that watches) · `/context` (how context gets assembled) · `/resilience` (when the call fails) · `/security` (who may do what) · `/hosting` (behind a wire) · `/events` (the typed wire vocabulary) · `/cache` (prompt caching). 8.0.0 consolidated 26 internals-named subpaths into these; every old path still resolves for all of 8.x.
 - **Lazy peer-deps.** Heavyweight integrations load their SDK **only when you instantiate them** — importing agentfootprint never bundles `@anthropic-ai/sdk`, `ioredis`, the AWS SDKs, or the MCP SDK unless you actually use that adapter.
+- **Optional families load when their option is enabled, never before.** What `import { Agent, defineTool }` costs is the library's *default graph*, not its whole surface. `.selfExplain()`'s trace toolpack — eleven tools over a finished trace, the largest single module in the package — is reached through a dynamic `import()` on the first iteration the self-explain skill is active; an agent that never enables it never ships it, and a bundler splits it into its own chunk. (A door that exists to hand you the debugger, `/observe`, carries it eagerly on purpose.)
 
-**Proven, not promised.** A CI smoke test bundles a minimal `import { defineTool }` and asserts the Agent runtime, injection engine, memory stores, and providers are pruned; a second test loads the main barrel and every subpath as true ESM and verifies the lazy-adapter loader works under ESM (`createRequire`, not a bare `require`). See [`test/esm-packaging.test.ts`](test/esm-packaging.test.ts).
+**Proven, not promised.** A CI smoke test bundles a minimal `import { defineTool }` and asserts the Agent runtime, injection engine, memory stores, and providers are pruned; a second test loads the main barrel and every subpath as true ESM and verifies the lazy-adapter loader works under ESM (`createRequire`, not a bare `require`). See [`test/esm-packaging.test.ts`](test/esm-packaging.test.ts). A third walks the code-split graph of the root entry and fails if the trace toolpack ever returns to its sync closure — [`test/lib/trace-toolpack/browserGraph.test.ts`](test/lib/trace-toolpack/browserGraph.test.ts); the docs site's own demo chunk is ratcheted against the same default graph in [`docs-next/scripts/check-site-budget.mjs`](docs-next/scripts/check-site-budget.mjs).
 
 ---
 

package/dist/core/Agent.js

@@ -50,6 +50,7 @@ const ReliabilityRecorder_js_1 = require("../recorders/core/ReliabilityRecorder.
 const ResilienceRecorder_js_1 = require("../recorders/core/ResilienceRecorder.js");
 const CheckInRecorder_js_1 = require("../recorders/core/CheckInRecorder.js");
 const CompactionMeter_js_1 = require("../recorders/core/CompactionMeter.js");
+const evictedTurns_js_1 = require("./agent/window/evictedTurns.js");
 const durabilityBarrier_js_1 = require("./durabilityBarrier.js");
 const toolSessions_js_1 = require("./toolSessions.js");
 const eventMeta_js_1 = require("../bridge/eventMeta.js");
@@ -264,6 +265,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
     /** The instrument the window stage reads mid-run (adapter-reported usage +
      *  per-message provenance). Only ever created alongside a strategy. */
     compactionMeterHandle;
+    /** The window stage's seam to the receipt (9.93.0): what left the window at
+     *  this iteration's head, read by the call-llm mint in the same iteration.
+     *  Only ever created alongside a strategy, like the meter. */
+    evictedTurnsHandle;
     /** Snapshot read-tracking policy (#18/#14) — forwarded to the internal
      *  executor. Agent default is `'summary'` (cheap markers), NOT
      *  footprintjs's `'full'`. See AgentOptions.readTracking. */
@@ -612,6 +617,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         if (windowStrategy !== undefined) {
             this.windowStrategy = windowStrategy;
             this.compactionMeterHandle = (0, CompactionMeter_js_1.compactionMeter)();
+            this.evictedTurnsHandle = (0, evictedTurns_js_1.createEvictedTurnsHandle)();
         }
         // The two governance chains. Empty arrays (not undefined) so every read
         // site is a plain `.length > 0` test rather than an optional dance.
@@ -2221,6 +2227,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // `conversationId` is deliberately not carried: it is a thread, not a
         // person, and `sessionId` beside it is the fact the transport delivered.
         const actor = runOptions?.identity ?? this.lastRunIdentity;
+        // A fresh run starts with no evictions filed — the previous run's last
+        // visit must not be read as this run's (`window/evictedTurns.ts`).
+        this.evictedTurnsHandle?.clear();
         this.currentRunContext = {
             runStartMs: Date.now(),
             runId: (0, RunnerBase_js_1.makeRunId)(),
@@ -3253,6 +3262,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // …and its off switch. Value-conditional, so an agent on the default
             // hands `callLLM` exactly the dep bag it always did.
             ...(this.recordReceiptValue === false && { recordReceipt: false }),
+            // …and the window's evictions for `omittedForAttention` (9.93.0) — only
+            // an agent with a window strategy has any, and only it hands the seam.
+            ...(this.evictedTurnsHandle !== undefined && { evictedTurns: this.evictedTurnsHandle }),
             provider,
             model,
             ...(temperature !== undefined && { temperature }),
@@ -3327,6 +3339,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 run: (0, window_js_1.buildWindowStage)({
                     strategy: this.windowStrategy,
                     meter: this.compactionMeterHandle,
+                    ...(this.evictedTurnsHandle !== undefined && {
+                        evictedTurns: this.evictedTurnsHandle,
+                    }),
                     agentModel: model,
                     providerName: provider.name,
                     getRunId: () => this.currentRunContext?.runId,