agentfootprint 9.90.0 → 9.92.1

package/AGENTS.md

@@ -544,7 +544,7 @@ files `agentfootprint.tools.coverage_declared`; with
 to the final answer, which is how a limit survives a model that would rather not
 mention it.
 
-### Observability — 109 typed events across 24 domains
+### Observability — 111 typed events across 24 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/CHANGELOG.md

@@ -7,6 +7,219 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.92.1] - 2026-09-11
+
+### Fixed
+
+- **9.92.0 never reached npm; this release is the same code.** Its publish job
+  failed the docs site's deferred-demo gzip ceiling by 0.4 KB (421.0 KB against
+  420.6 KB): the interactive demo bundles the library itself, and 9.92.0's
+  tool-resolution family rides the same main-entry graph as the receipt family
+  did in 9.88.0. The ceiling is re-baselined ~2% over the measurement with the
+  reasoning beside the number, and the docs-truth report regenerated. No
+  library code changes between 9.92.0 and 9.92.1. This is the fourth raise of
+  that ceiling for a family the demo never calls; the dynamic-import fix named
+  in 9.61.0 is the next move rather than a fifth raise.
+
+## [9.92.0] - 2026-09-11
+
+**The offer and the answer are one party.** At every LLM call the model is
+OFFERED a list of tool contracts (the wire; the receipt hashes each one), and
+when it calls a name something ANSWERS. Until this release those two halves
+could come from different parties for one name: the tools slot merges
+`[static, provider, skill, step]` first-occurrence-wins, while dispatch
+consulted the build-time registry first — so a provider's contract on the wire
+was answered by a skill's `execute` (an INACTIVE skill's, even), a provider's
+`skip_step` by the framework's (which then advanced the procedure on a call the
+model made against somebody else's contract), and the report that exists for
+this seam walked `activeInjections` and named the provider on epochs whose wire
+carried the skill's contract. A claimant that lost both the wire and the
+dispatch was simply dead, 22 rows of it in the divergence walk's baseline, with
+nothing on the record. `docs/design/2026-09-the-offer-and-the-answer.md` states
+the law; recorded-not-built entries 1, 2 and 3, the `claim-swallowed` bullet
+under entry 1 and the 9.91.0 tools-slot follow-up are marked built.
+
+**The law:** for every tool name on a call, exactly one party owns the OFFER and
+the same party owns the ANSWER — or the record names the disagreement. Three
+consequences, one example each:
+
+- **Dispatch follows the offer.** `buildToolsSlot.ts` · `mergeWire` is the one
+  pass that produces the wire AND the record of who won each name
+  (`ServedToolParties`, closure-shared like `ProviderToolCache`, never scope
+  state); `toolCalls.ts` · `lookupTool` reads it first. A provider and a
+  never-activated scoped skill both claiming `shared_tool`: the wire carries
+  the provider's contract, the provider's tool answers, and the skill's
+  `execute` answers no call while the provider holds the name — nor after the
+  provider withdraws it, because the skill's contract was never what the
+  model read: that call is REFUSED as a recorded tool result (`toolCalls.ts`
+  · `notServedResult`). A name NOT on this epoch's wire — a held-out step
+  tool, a parked map's tool, a scoped tool named from a restored transcript —
+  still dispatches (the capability law's held-out clause, `epoch-laws.test.ts`
+  1(a)–(e)), but only to the party the model LAST read the name under
+  (`ServedToolParties.lastServed`) or the name's only holder when it was never
+  served; every such dispatch is on the record as the new
+  `agentfootprint.tools.answered_off_wire` (`{ toolName, toolCallId,
+  iteration, answeredBy, answeredById? }`). A pause that re-dispatches on
+  resume (a middleware ask, a check-in, a credential consent) carries the
+  served party on its checkpoint (`pausedToolParty`, pause-path-only), so a
+  resume in a FRESH Agent instance — empty closure, no Compose — cannot fall
+  back to the build-time map's first holder either.
+- **The report's subject is the wire.** `agentfootprint.tools.shadowed` now
+  fires once per contested name per iteration when two contracts COMPETED for
+  the wire, and `schemaFrom`/`dispatchTo` both name the wire's party — they
+  agree by construction. A stepped skill and a provider sharing a name draw
+  `skill 'desk-stepped'` in both halves on every epoch, never `'provider'`.
+  The vocabulary gained `'framework'` (`ToolNameChannel`), so an auto-attach
+  is named as itself.
+- **A dead claim is reported.** New `agentfootprint.tools.claim_swallowed`
+  (`ToolsClaimSwallowedPayload`: `{ toolName, iteration, lostBy, lostById?,
+  wonBy, wonById? }`, names only) fires once per iteration for every party
+  whose claim to a name is held by somebody else — whether its contract
+  competed (an active skill against a provider) or never reached the merge
+  (the same skill while inactive; a provider tool whose name a static
+  `.tool()` owns; the framework's `skip_step` between tenures). Identity is by
+  IMPLEMENTATION: two skills sharing one `Tool` reference (documented-legal)
+  are one claim and draw nothing. Now 111 typed events across 24 domains.
+
+**`skip_step` is a claimant like any other** (`buildToolRegistry.ts` ·
+`toolClaimants`, the registry's new list of every build-time claimant per
+name — a list, not a winner). Its schema still merges last, so it rides the
+wire only when nobody else put the name forward; when a provider serves
+`skip_step`, the provider's tool answers and the step bookkeeping keys on the
+framework's own instance having answered (`toolCalls.ts` ·
+`frameworkSkipStepAnswered`) — the procedure does not advance. The build-time
+refusals (a static `.tool()` or a skill tool named `skip_step`/`present`) stand.
+
+**`buildAgentMessageApiChart` hands the model the declared tool set on every
+turn.** Its tools-slot mount now says `arrayMerge: ArrayMergeMode.Replace`, as
+the agent charts always did; turn 2 no longer serves `['weather','weather']`.
+
+**Byte-identity for every run with no name collision.**
+`test/core/tools/byte-identity.test.ts` drives fifteen collision-free shapes
+(both agent react modes, a skill-graph hop, a stepped skill, a parked map, the
+wrap-up, a tool-forced output, three provider shapes, two skills sharing one
+`Tool` reference, `LLMCall`, both message-API charts) and compares `commitLog`
+and `servedAt(k)` against references under `test/core/tools/reference/`
+generated on the 9.91.0 tree. All fifteen are identical; the
+receipt-conformance suite is unchanged and green on all four chart shapes.
+
+**The divergence walk, re-recorded — and widened.** Every `contract-swap`
+row (12) and every `report-misattributed` row (10) is GONE and ratcheted so
+it cannot reopen quietly; the `claim-swallowed` family is 35 rows, every one
+carrying what `tools.claim_swallowed` said about it. The walk gained the
+cross-epoch × collision cases it never had (walk D: a provider withdrawing a
+name an inactive skill also holds; a fresh-instance resume of a provider's
+call) and a kind for the held-out dispatch the law keeps, `answered-off-wire`
+(4 rows, each carrying the event). The harness moved to
+`test/core/agent/toolDivergenceWalk.harness.ts` so the reproductions in
+`test/core/tools/offer-and-answer.test.ts` — the entries' own, verbatim, each
+red on 9.91.0, plus the review's own shapes — drive the same configurations.
+
+**Consumer-facing changes, stated plainly.** (1) A provider tool that shares a
+name with a skill tool now RUNS where the skill's used to — the contract the
+model read is the one that answers. (2) `tools.shadowed` fires on
+configurations that were silent (a provider against a static `.tool()` or a
+framework auto-attach) and no longer names `'provider'` as `schemaFrom` where
+the wire carried the skill's contract; `dispatchTo` now equals `schemaFrom`.
+(3) Two new events, `tools.claim_swallowed` and `tools.answered_off_wire`.
+(4) A call to a name that left the wire, whose last-served party can no longer
+answer, is refused with a recorded result where it used to be answered by
+whichever party the build-time map held first; the same sentence answers a
+provider-served call resumed in a fresh instance (where it used to read
+`Unknown tool`). (5) Two stale comments in `buildToolsSlot.ts` and
+`buildToolRegistry.ts` corrected in the same diff; `Agent.ts`'s "fresh chart
+per run()" comment corrected — the chart is built once at construction.
+
+## [9.91.0] - 2026-09-10
+
+**Every chart that serves a model now mints a receipt.** A receipt is the proof
+of what the model was actually handed, minted at the call and committed in the
+bundle the call already writes — and until this release exactly ONE stage minted
+one. Three other charts in this library handed a model a request and left
+`no-receipt-on-chart` on every view they produced, so a reader of an `LLMCall`
+or messageAPI recording could only ever see Reconstructed, never Verified.
+
+Two reasons were on the record for that. **Neither survived.** The first — that
+`Receipt.cache.transform` has no honest value on a chart running no cache
+strategy — was already refuted in 9.88.0 and left refuted in the source: an
+`Agent` with a pass-through strategy records `'unchanged'` today, and the value
+is true for the same reason where no strategy exists at all, because *the
+request that went out IS the request that was assembled*. **No fourth enum value
+was added.** The second — the salt — never applied to `LLMCall`, which owns its
+executor and mints a run id exactly as `Agent` does. It DOES apply to the two
+messageAPI charts, and that was verified rather than assumed: footprintjs stamps
+`TraversalContext.runId` on recorder events, not on a stage's scope; there is no
+`$runId` on `ScopeFacade`; `ExecutionEnv` is a fixed type carrying `traceId` and
+no run id. A chart builder run on somebody else's executor genuinely cannot
+invent the value — so it is a dep, and a chart given none mints NOTHING rather
+than salting every hash with an empty string.
+
+### Added
+
+- **`LLMCall` mints a receipt** (`LLMCall.ts` · `callLLM`), salted with the run
+  id `createExecutor` already mints per run — read at CALL time, not closed over
+  at build time, so the second run of the same `LLMCall` is not salted with the
+  first run's value. `servedAt` on an `LLMCall` recording now carries
+  `basis.model`, `params` and the cache verdict, and stops raising
+  `no-receipt-on-chart`.
+- **`LLMCallOptions.recordReceipt`** — the twin of `AgentOptions.recordReceipt`,
+  same field, same contract, default ON. `false` declines the mint (one
+  commit-log value and a SHA-256 per piece, per message, per tool schema);
+  `servedAt` still rebuilds the view and declares the missing witness.
+- **`MessageApiChartDeps.getRunId` / `AgentMessageApiChartDeps.getRunId`** —
+  supply the run id and the chart mints on every turn; omit it and it mints
+  none. `src/core/agent/messageApiReceipt.ts` owns that rule for both charts,
+  because the two are deliberate twins and a mint written out in each is two
+  chances to disagree about what the model was handed.
+- **`receipt.ts` · `receiptPieces`** — the injection-record → receipt-piece map,
+  which was about to have four copies. One owner, calling the same
+  `contributingPieces` the system-prompt join calls, so a piece cannot be on the
+  receipt and absent from the string.
+
+### Fixed
+
+- **`servedAt` reported an EMPTY tool list on a call that served tools.**
+  `servedView.ts` · `viewOf` read the served list from `dynamicToolSchemas`
+  alone. The agent charts map the tools slot's output onto that key at the mount
+  boundary; the messageAPI charts carry it out under the slot's own name — so a
+  `buildAgentMessageApiChart` view said `tools.names: []` about a call that
+  served one. An empty list is not an omission, it is a DENIAL, and it went
+  unnoticed for as long as no receipt existed to contradict it. The read is now
+  a fallback chain (the agent key first, so no agent recording changes), the
+  same shape the conversation has had since 9.88.0. Red before, on
+  `test/lib/time-travel/receipt-conformance.test.ts` · *the tool the model was
+  served is hashed by the receipt AND rebuilt from the log*.
+
+### Changed
+
+- **`SERVED_GAPS['no-receipt-on-chart']` is unchanged, and still true.** Its
+  printed sentence never named a chart, so nothing in it went false; the
+  MECHANISM comment beside it now names the shapes that still reach it — a
+  messageAPI chart handed no run id, a run that declined with `recordReceipt:
+  false`, a recording made before 9.88.0, and a consumer's own `call-llm` stage,
+  which this library does not mint for. The cause `'no-receipt-committed'` is
+  still driven by a REAL run in both walks; the driver moved from an `LLMCall`
+  (which now mints) to a messageAPI chart with no run id.
+- **The composed request is assembled once per chart.** Each of the three
+  charts now builds ONE `LLMRequest` object and both sends it and fingerprints
+  it, and each routes its conversation through `stripFrameworkFields` — the
+  third rule of the one assembly — so the mint and the rebuild cannot drift.
+  Every other byte those charts commit is unchanged: measured by dumping each
+  chart's commit log, its per-bundle keys and its final state before and after,
+  and diffing (identical apart from the new `receipt` key).
+
+### Docs
+
+- `src/lib/time-travel/README.md` — a "Which charts mint a receipt" table (chart
+  → mints? → the salt) with the builder example, and every measurement that
+  named an `LLMCall` view as receipt-less retaken on the shape that still is.
+- `docs-next` `debug/time-travel.mdx` — the same section for the site. No new
+  route.
+- `docs/design/2026-09-recorded-not-built.md` — entry 8's reproduction retaken
+  (it still stands; only its driver moved) and an appendix marking the standing
+  no-mint fact BUILT in 9.91.0, with the reasons that died and the one that
+  survives.
+
 ## [9.90.0] - 2026-09-10
 
 **The recording carries its own milestones.** Until now a stored run could not

package/CLAUDE.md

@@ -154,7 +154,7 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - **Embedder fingerprint** (8.9.0) → `Embedder.id` (optional; every shipped embedder sets one, and NONE include dims — the store appends `@<dims>` itself, so an id carrying its own size double-stamps) + `indexDocuments` defaulting `embedderId` to it + `SqliteVectorStore.reconcileFingerprint` (the only comparison site). Rule: dimensions ALWAYS decide, model ids decide only when BOTH sides named themselves — refusing on an absent name would block the majority of callers who never pass `embedderId`.
 - **Retrieval record** (8.8.0) → FOUR stages write one object in sequence: `loadRelevant` (candidates+scores+threshold verdicts) → `pickByBudget` (re-marks admitted→over-budget/over-max-entries) → `formatDefault` (`promptFragment` + `promptPosition`) → the read mount's outputMapper lifts it to root as `retrievalEvidence_<id>`. `memoryRecallInjections` then splits ONE recall into one ActiveInjection PER CHUNK — guarded by a byte-equality check (`fragments.join('\n\n') === systemContent`) that falls back to the single injection rather than change the prompt. `rank` (score order) and `promptPosition` (picker order) are DIFFERENT and both load-bearing: joining fragments in rank order reproduces the right bytes in a sequence the model never saw.
 - **AgentState** → all 8 stages/ files, both builders' mappers, memory-wire STRING-TYPED keys ('runIdentity'/'turnNumber'/… buildAgentChart.ts:177-180 — not refactor-safe), finalizeResult's `reliabilityFail*`/`policyHalt*` reads (rename silently kills the typed errors).
-- **events/** → 109 typed events across 24 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
+- **events/** → 111 typed events across 24 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
 - **Run-configuration manifest (9.41.0)** → `agentfootprint.agent.run_configured`, the JOIN KEY that turns N runs into N labelled ARMS: one event naming the adapters/strategies in play (provider+model, reactMode, each memory's declared strategy/retrieval/embedder, window, graph posture+classifier, evidence posture, artifacts-present). Composed by the PURE `core/agent/runManifest.ts`, dispatched from `Agent.emitRunManifest()` at the END of `createExecutor` — the ONE funnel `run()` AND `resume()` share, both of which mint a fresh runId. Direct `dispatcher.dispatch` with a STATED pseudo-stage (`run-configured#0`), the `emitToolSessionReport` precedent — there is no stage yet, and `minimalMeta()` would make the one joinable-by-design event unjoinable. TWO laws, both tested: NAMES ONLY (a store is reported PRESENT and unnamed rather than identified by a directory/endpoint — `MemoryStore` and `ArtifactStore` declare no id), and ABSENT means "not configured", never a guessed `'default'`. Graph presence is read off `skillGraphNextSkill`, NOT `skillGraphCascade` (a 9.16-style mount sets no cascade and would read as "no graph"). `MemoryDefinition` gained `strategy`/`retrieval`/`embedderId` for it — declared names the compiled pipeline had closed over, the `store`-in-the-open precedent.
 - **adapters/types.ts LLMMessage/LLMRequest** → 62 importers: tool_use round-trip (toolCalls.ts:115-135), wire assembly (callLLM.ts:150-160), providers, cache strategies, security/extractSequence, reliability loop.
 - **Cache** → strategy registration is a MODULE SIDE EFFECT (src/index.ts:15-17); an entry point skipping that import silently falls back to NoOp. Resolved once per Agent at construction (Agent.ts:347).

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

@@ -252,7 +252,7 @@ const agent = Agent.create({ provider, model })
 agent.on('agentfootprint.context.evaluated', (e) => console.log(e.payload.activeIds));
 ```
 
-**109 typed events across 24 domains.** Two subscription shapes and no third:
+**111 typed events across 24 domains.** Two subscription shapes and no third:
 `'*'` (every event) and `'agentfootprint.<domain>.*'` (one domain). **`'agentfootprint.*'`
 is not a pattern** — TypeScript rejects it, and at runtime it would match nothing.
 

package/dist/core/Agent.js

@@ -2980,7 +2980,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // auto-attached `present` tool when a store is attached, 9.22.0) +
         // skill-supplied tools (with autoActivate scoping); validates
         // name uniqueness; produces the dispatch map.
-        const { registryByName, toolSchemas, toolDeclaringSkills } = (0, buildToolRegistry_js_1.buildToolRegistry)(registry, this.injections, {
+        const { registryByName, toolSchemas, toolDeclaringSkills, toolClaimants } = (0, buildToolRegistry_js_1.buildToolRegistry)(registry, this.injections, {
             hasArtifactStore: artifactStore !== undefined,
         });
         // A statically registered tool that declares `wants` on an agent with no
@@ -3137,13 +3137,25 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         const messagesSubflow = (0, buildMessagesSlot_js_1.buildMessagesSlot)({
             ...(budget?.messages !== undefined && { budgetCap: budget.messages }),
         });
-        // Per-run cache shared between buildToolsSlot (writer, each
-        // iteration) and buildToolCallsHandler (reader, same iteration).
-        // Holds the resolved Tool[] from `provider.list(ctx)` so dispatch
-        // doesn't re-invoke `list()` — vital for async network providers.
-        // A fresh chart (and thus fresh cache) is built per `agent.run()`,
-        // so concurrent runs don't share state.
+        // Cache shared between buildToolsSlot (writer, each iteration) and
+        // buildToolCallsHandler (reader, same iteration). Holds the resolved
+        // Tool[] from `provider.list(ctx)` so dispatch doesn't re-invoke `list()`
+        // — vital for async network providers.
+        //
+        // LIFETIME, stated correctly (9.92.0): the chart is built ONCE, at
+        // construction (`initChart`), and reused by every `run()` and `resume()`
+        // of this Agent — so this cache and the record below outlive a run. They
+        // are safe because one Agent runs one turn at a time and the slot
+        // overwrites them every iteration before dispatch reads them. What that
+        // does NOT cover is a resume in a FRESH instance, whose closure is empty
+        // and whose Compose never re-runs before the resumed dispatch — which is
+        // why the pause paths carry `pausedToolParty` on the checkpoint.
         const providerToolCache = { current: [] };
+        // Who put each name on the wire (9.92.0) — the same closure-shared shape,
+        // written by the tools slot's merge and read by dispatch so the party
+        // whose contract the model read is the party that answers. `lastServed`
+        // is the run's memory of the same fact, for a name that left the wire.
+        const servedTools = { current: new Map(), lastServed: new Map() };
         const readSkillFor = this.readSkillOfferFor();
         // Per-role skill visibility. The RESOLVER is handed to the tools slot, which
         // is the fact's one owner: it resolves the ids once per iteration and
@@ -3225,6 +3237,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             integrityLedger: this.integrityLedgerHolder,
             ...(this.externalToolProvider && { toolProvider: this.externalToolProvider }),
             ...(this.externalToolProvider && { providerToolCache }),
+            toolClaimants,
+            servedTools,
             ...(readSkillFor && { readSkillFor }),
             ...(hiddenSkillIds && { hiddenSkillIds }),
             ...(budget?.tools !== undefined && { budgetCap: budget.tools }),
@@ -3397,6 +3411,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             }),
             ...(this.externalToolProvider && { externalToolProvider: this.externalToolProvider }),
             ...(this.externalToolProvider && { providerToolCache }),
+            servedTools,
+            toolClaimants,
             ...(permissionChecker && { permissionChecker }),
             ...(credentialProvider && { credentialProvider }),
             // The claim-check store (9.21.0). Absent → not one new line runs in