agentfootprint 9.51.0 → 9.53.0

package/AGENTS.md

@@ -217,6 +217,26 @@ const weather = defineTool({
 
 Tool-name uniqueness is validated at `agent.build()` time across `.tool()` registrations AND every Skill's `inject.tools[]`.
 
+A long-running tool can say where it is, mid-call, with `ctx.progress(payload)` —
+each call files one `agentfootprint.stream.tool_progress` event between that
+call's `tool_start` and `tool_end`, so a forty-second walk reads as "hop 3 of 12"
+instead of silence:
+
+```typescript
+execute: async (args, ctx) => {
+  for (const [i, hop] of hops.entries()) {
+    await visit(hop);
+    ctx.progress({ done: i + 1, total: hops.length });   // telemetry, never the model's to read
+  }
+  return summarize(hops);
+},
+```
+
+The framework stamps `toolCallId` / `toolName` / `iteration`; `payload` is yours,
+forwarded verbatim (it must survive `structuredClone`). Always present, never
+throws, never blocks — with nothing listening it is a no-op, and a tool that
+never calls it emits exactly what it emitted before.
+
 ### Context Engineering — 4 typed factories
 
 All four return an `Injection` evaluated by the same engine; all emit the same `agentfootprint.context.injected` event with `source` discriminating the flavor.
@@ -504,7 +524,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 — 100 typed events across 22 domains
+### Observability — 102 typed events across 22 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/CLAUDE.md

@@ -17,6 +17,9 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 
 | If you are about to build… | It is | Where | Since |
 |---|---|---|---|
+| a tool returning numbers WITH the caveats that make them honest — interval/aggregation grain, is-it-a-counter, when the world was measured, which ground was NOT covered — as typed data the model reads compactly and the record keeps whole | `semantic()` + `tools.semantics_declared` (model sees `semanticsForModel` projection; `coverage` field absorbed by the coverage()/absent() channel) | `src/lib/semantics/` | 9.53.0 |
+| a build gate that refuses a triage/inventory tool that forgot its caveats, by tool name and field name | `checkSemantics` + `defineTool({ resultClass })` + bin `agentfootprint-check-semantics` | `src/lib/semantics/check.ts` | 9.53.0 |
+| report progress from inside a tool — "hop 3 of 12 done", said mid-call while a long-running `execute` is still working (the record was otherwise atomic: tool_start, silence, tool_end) | `ctx.progress` + `agentfootprint.stream.tool_progress` | `src/core/tools.ts` | 9.52.0 |
 | declaring which skills connect — the SkillMap as one named thing (the agent that mounts it is the SkillWalker; there is deliberately no walker class) | `defineSkillMap` + `SkillMap` (permanent reference-equal aliases of `skillGraph`/`SkillGraph`) | `src/lib/injection-engine/skillGraph.ts` | 9.51.0 |
 | guarding a skill transition on state or a tool result's fields — a route condition as DATA (comparable, drawable, evidence-recorded), not an opaque predicate | `guard:` + `compileGuard` + `guard-unsatisfiable` | `src/lib/injection-engine/skillGuard.ts` | 9.51.0 |
 | seeing the skill map in a recording — the author's nodes + edges (guards included) as DATA, never parsed from prose or inferred from fired hops | `skill.graph_declared` + `buildSkillGraphDeclared` | `src/core/agent/skillGraphDeclared.ts` | 9.50.0 |
@@ -88,7 +91,7 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - $break is the only clean-stop channel; structured fail context rides scope fields (`policyHalt*`, `reliabilityFail*`), decoded post-run by `Agent.finalizeResult` (Agent.ts:884) into typed errors.
 
 ## Extension points
-- **Tool**: `defineTool` (core/tools.ts:155); shape `Tool = {schema, needs?, execute(args, ctx)}` (:23). Register `AgentBuilder.tool()` (AgentBuilder.ts:184); merged with auto `read_skill` in buildToolRegistry (:65; same-reference skill tools dedupe, any other name collision THROWS at build). Chart-as-tool: `flowchartAsTool` (core/flowchartAsTool.ts:203). MCP: `mcpClient(...).tools()`.
+- **Tool**: `defineTool` (core/tools.ts:155); shape `Tool = {schema, needs?, execute(args, ctx)}` (:23). `ctx.progress(payload)` (9.52.0) is the tool's OWN emit door — a `Pick<ToolExecutionContext,'progress'>` closure (`toolProgress`, stages/toolCalls.ts, spread at BOTH dispatch sites beside `toolArtifacts`/`sessionContext`) that typedEmits `stream.tool_progress` mid-stage; framework stamps toolCallId/toolName/iteration, author owns `payload` only. ALWAYS present and never fatal (try/catch + dev warn) — the streamless doors (`mcpServe`, traceToolpack `OFFLINE_CONTEXT`) supply the no-op, which is the whole list of places a new required ctx field must also land. Register `AgentBuilder.tool()` (AgentBuilder.ts:184); merged with auto `read_skill` in buildToolRegistry (:65; same-reference skill tools dedupe, any other name collision THROWS at build). Chart-as-tool: `flowchartAsTool` (core/flowchartAsTool.ts:203). MCP: `mcpClient(...).tools()`.
 - **ToolProvider** (per-iteration visibility): `list(ctx): Tool[]` (tool-providers/types.ts:121); max ONE per agent (AgentBuilder.ts:238 throws on second); combinators staticTools/gatedTools/skillScopedTools chain decorator-style.
 - **LLM provider**: `LLMProvider = {name, complete, stream?}` (adapters/types.ts:230) passed as `AgentOptions.provider`. `provider.name` keys THREE auto-resolutions: cache strategy (cache/strategyRegistry.ts:40), thinking handler (thinking/registry.ts:43), Lens labels.
 - **Recorder, 3 layers**: (1) raw footprintjs CombinedRecorder via `agent.attach()` (RunnerBase.ts:474 — NOT idempotent); (2) typed stream `agent.on(type|'*')`; (3) new built-in = factory taking `{dispatcher, getRunContext}`, registered in the attach block inside `Agent.run()` (Agent.ts:807-845), barreled in src/observe.ts.
@@ -126,7 +129,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/** → 100 typed events across 22 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/** → 102 typed events across 22 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).
@@ -143,6 +146,7 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - **Skill visibility** (9.11.0) → the async half rides the tools slot's Discover stage (the ONE awaitable stage there) into a closure-shared `hiddenSkillIds`, read by the sync Compose stage — the `providerToolCache` pattern exactly. `readSkillFor` now takes `{currentSkillId?, hiddenSkillIds?}`; `ReadSkillOffer.grantable` became OPTIONAL (no graph ⇒ plain filtered catalog) and `hiddenIds` removes rows from BOTH sections. The ENUM stays the full catalog (8.5.0's law — narrowing it turns a policy refusal into a generic schema error that `toolArgValidation` raises before any gate). `skill:<id>` targets have ONE owner: `security/skillTarget.ts`.
 - **Tool-result cap** (9.11.0) → `core/agent/toolResultCap.ts` + `ToolCallsHandlerDeps.maxToolResultChars` + the `capResults` closure applied at all FIVE `tool_end`-emitting dispatch paths in toolCalls.ts (execute, ask-resume, check-in decision, credential-consent resume, pauseHere answer). Both channels are measured separately — `result` (the event) and `modelResult` (history) — because a middleware may have already shrunk one. A new dispatch path MUST call `capResults` or it silently escapes the ceiling.
 - **Refusing result ceiling** (9.20.0) → the PER-TOOL sibling of the cap with the OPPOSITE overflow answer: `Tool.resultCeiling {maxChars, narrowBy?}` (type + `assertResultCeiling` in core/tools.ts; measurement + refusal sentence in `core/agent/resultCeiling.ts`) REFUSES — "No data was returned" + how to narrow — never truncates (truncation reads as complete data ⇒ fabrication). Applied by the `refuseOverCeiling` closure at BOTH execute boundaries (batch loop + `resolveCredentialAndExecute`, covering all four resume paths; the pauseHere answer is a HUMAN's value, deliberately not measured), at the moment the handler's return lands — BEFORE gates/after-tool chain (read_skill-gate precedent). The payload enters NO channel; the record keeps `tools.result_refused {sizeChars, maxChars, narrowBy?, declaredStatus?}`; delivered status = `'invalid'` (routes via `onToolStatus`); an envelope's DECLARED effects are still judged (the effects channel didn't overflow) but its status is overridden; `ceilingRefused` blocks step-pointer advance on every path. Zero-cost: no `resultCeiling` ⇒ one undefined check, byte-identical.
+- **Semantic tool results** (9.53.0) → ONE vocabulary leaf `lib/semantics/types.ts` (the toolOutcome precedent; type-only imports of coverage types — absorbed, never duplicated) + ONE rule set `semanticIssues` serving three doors: `semantic()` mint refusals, `readSemantics` strict recognition (any fault ⇒ data path byte-for-byte + dev warn — never half-applied), and `checkSemantics` findings (same codes). Dispatch wiring is the coverage/ceiling radius verbatim: `declareSemantics` closure at BOTH execute boundaries in toolCalls.ts, ordered declareCoverage → declareSemantics → refuseOverCeiling — the coverage funnel (`readCoverageResult`) grew a semantic arm so the envelope's `coverage` field flows the coverage() channel with zero boundary edits, the FULL envelope rides `tools.semantics_declared` (structuredClone-detached) BEFORE the ceiling (caveats survive an oversized refusal), and the ceiling measures the PROJECTION (`semanticsForModel`: drops marker/render/coverage-detail, composes `not_covered` FROM coverage) because that is what the model reads. `Tool.resultClass` ('triage'|'inventory', closed) validated at defineTool (`assertResultClass`, the assertResultCeiling law) and consumed ONLY by the gate. Gate = tool-lint humble-shell verbatim: core in lib/semantics/{check,format,cli}.ts, bin `agentfootprint-check-semantics.mjs`, exit 0/1/2, judges SAMPLE results (mock returns) — never executes tools. Deliberately UNCHANGED: no new scope key (the envelope is per-attempt ⇒ event channel; coverage rows reuse `coverageDeclared`), no status word, no gate flag, pause-answer paths not recognized (human values are not envelopes).
 - **Conjunction matcher** (9.20.0) → `SkillMatch` gains `{all: [...]}` (AND of the SYNC arms only), all inside skillMatch.ts: `compileAllArm` (ONE compilation → AND predicate + flat `{kind:'all', parts}` data; intent member = teaching refusal naming the separate-rule alternative; nested `all` FLATTENED — associativity, the drop-stateful-flags normalize-to-truth precedent; empty refused), `compareWithAll` (shadows-ONLY via `partCoversProvably` part coverage — identical regex / keyword superset; plain-earlier-covers-a-part shadows a later all; NO overlap claims — a conjunction can be unsatisfiable and the specific-first layout is a design), `rawCaption` recursion (parts joined ` AND `, escaped once). Checkup/provenance/toMermaid see through it with zero changes of their own (parts are guaranteed leaves). NOTE `rawCaption` is now the EXPORTED `plainMatchCaption` (one grammar, two consumers: the mermaid label escapes it; skillExamples quotes it in prose).
 - **Examples on start rules** (SG-G) → `examples?: readonly string[]` on `SkillEntryOptions` + BOTH `SkillStartRule` arms + `EntryDecl`; ALL the logic in skillExamples.ts (validate at the ONE funnel `builder.entry` — the config form translates through it): FOUR codes on `GraphProblemCode` proved by RUNNING the compiled predicates on a cold-start context, in declaration order. **TWO START LAWS, and the check-up may not pick one**: the declaration-order cold walk (unconditional entries claim) vs the turn-start cascade's tier-1 `firstRuleMatch` (CONDITIONAL entries only) — mounted by `.classify()` AND by `continuity: 'conversation'`, an AGENT-MOUNT option invisible at graph build. They differ in exactly one place (whether a default claims), so both are computed and an ERROR is asserted only where they AGREE: `example-shadowed-by-earlier` ERROR (earlier CONDITIONAL claimant, or both laws putting the turn elsewhere) vs `example-shadowed-by-default` WARNING (earlier UNCONDITIONAL claimant — both readings named; erroring here contradicted the live router, which routes that turn to the later rule under `continuity:'conversation'`). SEVERITY FOLLOWS PROVABILITY on `example-misses-own-rule`: ERROR for a data `match` (reads `userMessage` only ⇒ no-match holds under every context) or a THROW (turn 1 really hands it that context); WARNING for an opaque `when` (may be gated on `ctx.history.length > 0` and claim on a later turn — history survives a run, the cursor does not). Every message NAMES the judged context (iteration 1 / phrase / empty history / no cursor) and `describeCondition` has an UNCONDITIONAL arm — printing "its `when` predicate" for an entry that declares none was a message describing a graph nobody wrote. `example-unclaimed` WARNING. Ordering checks gated on the SAME `!exclusiveEntries || hasClassifier` premise as the pairwise rule checks; self-match is order-independent and always runs. `GraphCheckup` gains `notes?` (the boundary sentence — rendered by formatCheckup as `[note]`, carried through the deferred-body-contract filter) and `GraphProblem` gains `example?`. TIER LAW: tier-2 `match:{intent,examples}` examples are SCORING material (run time); rule-level `examples` are TEST material (build time only) — both lists on one rule is a teaching refusal, as are an empty/blank list and examples on an UNCONDITIONAL entry (it claims everything, so they would prove nothing). Zero-cost when unused: one `Array.some`, no notes key, byte-identical skills/edges/events.
 

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

@@ -193,6 +193,23 @@ const calculator = defineTool({
 });
 ```
 
+### A long tool that says where it is
+
+```typescript
+execute: async (args, ctx) => {
+  for (const [i, hop] of hops.entries()) {
+    await visit(hop);
+    ctx.progress({ done: i + 1, total: hops.length });   // → stream.tool_progress
+  }
+  return summarize(hops);
+},
+```
+
+`ctx.progress` is always present, never throws, never blocks, and never reaches
+the model — the framework stamps `toolCallId` / `toolName` / `iteration`, you own
+`payload`. `agent.on('agentfootprint.stream.*')` and `toSSE(agent)` carry it with
+no extra wiring.
+
 ### When a tool finds nothing, and what a clean result does not cover
 
 ```typescript
@@ -235,7 +252,7 @@ const agent = Agent.create({ provider, model })
 agent.on('agentfootprint.context.evaluated', (e) => console.log(e.payload.activeIds));
 ```
 
-**100 typed events across 22 domains.** Two subscription shapes and no third:
+**102 typed events across 22 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/bin/agentfootprint-check-semantics.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * agentfootprint-check-semantics — CI gate for semantic tool results
+ * (9.53.0). Humble shell: all behavior lives in src/lib/semantics/cli.ts
+ * (unit-tested there); this wrapper only resolves the built module and maps
+ * the returned code onto process.exitCode.
+ *
+ *   npx agentfootprint-check-semantics semantics-catalog.json
+ *   npx agentfootprint-check-semantics semantics-catalog.json --strict
+ *
+ * Guide: docs-next/content/docs/build/semantic-results.mdx
+ */
+const { runCheckSemanticsCli } = await import('../dist/esm/lib/semantics/cli.js');
+process.exitCode = await runCheckSemanticsCli(process.argv.slice(2));

package/dist/core/agent/coverage/read.js

@@ -17,6 +17,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readCoverageResult = void 0;
+const envelope_js_1 = require("../../../lib/semantics/envelope.js");
 const absent_js_1 = require("./absent.js");
 const ledger_js_1 = require("./ledger.js");
 const ABSENT_STATUS = 'absent';
@@ -38,6 +39,18 @@ function readCoverageResult(value) {
             ],
         };
     }
+    // A semantic envelope's `coverage` field (9.53.0) is ABSORBED here — the
+    // one recognizer funnel — so the boundary a semantic tool declared flows
+    // through the exact channel `coverage()` uses (the `tools.coverage_declared`
+    // event, tracked state, the final-answer limits block) with zero extra
+    // wiring at any dispatch door. A semantic envelope without `coverage`
+    // declares no boundary, exactly like a bare result.
+    const sem = (0, envelope_js_1.readSemantics)(value);
+    if (sem !== undefined) {
+        if (sem.coverage === undefined)
+            return undefined;
+        return { declared: [{ kind: 'ledger', coverage: (0, envelope_js_1.coverageOfSemantics)(sem) }] };
+    }
     const covered = (0, ledger_js_1.readCoverageLedger)(value);
     if (covered === undefined)
         return undefined;

package/dist/core/agent/coverage/read.js.map

@@ -1 +1 @@
-{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../../src/core/agent/coverage/read.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAGH,2CAA6D;AAC7D,2CAAmE;AA6BnE,MAAM,aAAa,GAAqB,QAAQ,CAAC;AAEjD;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,MAAM,OAAO,GAAG,IAAA,uBAAW,EAAC,KAAK,CAAC,CAAC;IACnC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAA,6BAAiB,EAAC,OAAO,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE;aACzF;SACF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,8BAAkB,EAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,QAAQ,GAAoB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAA,4BAAgB,EAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5F,MAAM,KAAK,GAAG,IAAA,uBAAW,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC7C,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,IAAA,6BAAiB,EAAC,KAAK,CAAC;QAClC,SAAS,EAAE,KAAK,CAAC,UAAU;KAC5B,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAC7C,CAAC;AArBD,gDAqBC"}
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../../src/core/agent/coverage/read.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAGH,oEAAwF;AACxF,2CAA6D;AAC7D,2CAAmE;AA6BnE,MAAM,aAAa,GAAqB,QAAQ,CAAC;AAEjD;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,MAAM,OAAO,GAAG,IAAA,uBAAW,EAAC,KAAK,CAAC,CAAC;IACnC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAA,6BAAiB,EAAC,OAAO,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE;aACzF;SACF,CAAC;IACJ,CAAC;IACD,yEAAyE;IACzE,yEAAyE;IACzE,6EAA6E;IAC7E,uEAAuE;IACvE,sEAAsE;IACtE,oDAAoD;IACpD,MAAM,GAAG,GAAG,IAAA,2BAAa,EAAC,KAAK,CAAC,CAAC;IACjC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACjD,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAA,iCAAmB,EAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;IAChF,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,8BAAkB,EAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,QAAQ,GAAoB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAA,4BAAgB,EAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5F,MAAM,KAAK,GAAG,IAAA,uBAAW,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC7C,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,IAAA,6BAAiB,EAAC,KAAK,CAAC;QAClC,SAAS,EAAE,KAAK,CAAC,UAAU;KAC5B,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAC7C,CAAC;AAhCD,gDAgCC"}

package/dist/core/agent/stages/toolCalls.js

@@ -69,6 +69,7 @@ const validators_js_1 = require("../validators.js");
 const toolResultCap_js_1 = require("../toolResultCap.js");
 const resultCeiling_js_1 = require("../resultCeiling.js");
 const skillSteps_js_1 = require("../../../lib/injection-engine/skillSteps.js");
+const envelope_js_1 = require("../../../lib/semantics/envelope.js");
 const index_js_1 = require("../coverage/index.js");
 const toolEffects_js_1 = require("../toolEffects.js");
 /** Declaration order preserved, ids de-duplicated — the shape the gate's re-prompt
@@ -381,6 +382,66 @@ function buildToolCallsHandler(deps) {
         scope.coverageDeclared = [...(scope.coverageDeclared ?? []), ...rows];
         return reading.status;
     };
+    /**
+     * The semantic envelope (9.53.0) — recognized at the SAME execute
+     * boundaries as coverage and the ceiling (one implementation, every door),
+     * AFTER `declareCoverage` (which absorbs the envelope's `coverage` field
+     * through the one coverage funnel) and BEFORE `refuseOverCeiling` (so the
+     * FULL envelope — grain, provenance, render, coverage — is on the record
+     * even when the content is refused as oversized: a caveat that died with
+     * an oversized result would be the silence the envelope exists to break).
+     *
+     * Returns the MODEL's view — the compact rendering-free projection
+     * (`semanticsForModel`: data + grain + provenance + composed `not_covered`
+     * + non-null clarify + the static note; never the marker, `render`, or the
+     * three-list coverage detail) — or `undefined` for every non-envelope
+     * value, which keeps today's path byte for byte. The full envelope rides
+     * the typed `tools.semantics_declared` event, so recordings and UIs get
+     * everything the model was spared.
+     *
+     * A value CARRYING the marker that this library cannot honor stays DATA
+     * (never half-applied — the recognition strictness law) and is dev-warned
+     * here naming its first fault; `check:semantics` names them all at build
+     * time.
+     */
+    const declareSemantics = (scope, call, value) => {
+        const sem = (0, envelope_js_1.readSemantics)(value);
+        if (sem === undefined) {
+            const faults = (0, envelope_js_1.explainSemantics)(value);
+            if (faults !== undefined && faults.length > 0 && (0, footprintjs_1.isDevMode)()) {
+                // eslint-disable-next-line no-console
+                console.warn(`agentfootprint semantics: tool '${call.toolName}' returned a value carrying ` +
+                    `af_semantics that was NOT recognized (treated as plain data): ` +
+                    `${faults[0].message} (field: ${faults[0].field})` +
+                    (faults.length > 1 ? ` — and ${faults.length - 1} more; run check:semantics.` : ''));
+            }
+            return undefined;
+        }
+        // Detached plain data for the record — the event must not hold a live
+        // reference into a value the tool still owns. An envelope that cannot
+        // survive structuredClone cannot ride the record (or a checkpoint), so
+        // it is declined here — data path, dev-warned — rather than half-filed.
+        let detached;
+        try {
+            detached = structuredClone(sem);
+        }
+        catch {
+            if ((0, footprintjs_1.isDevMode)()) {
+                // eslint-disable-next-line no-console
+                console.warn(`agentfootprint semantics: tool '${call.toolName}' returned a semantic envelope ` +
+                    `that does not survive structuredClone (a function or live handle in a fact row?) ` +
+                    `— treated as plain data. Envelope values must be plain data.`);
+            }
+            return undefined;
+        }
+        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.tools.semantics_declared', {
+            toolName: call.toolName,
+            toolCallId: call.toolCallId,
+            iteration: call.iteration,
+            semantics: detached,
+        });
+        return (0, envelope_js_1.semanticsForModel)(sem);
+    };
     // ── Step-procedure boundary (9.18.0) — ONE implementation, five sites ──
     // The batch loop and the four resume paths all finalize results; each
     // calls these where its result becomes final, so a pointer can never miss
@@ -733,6 +794,50 @@ function buildToolCallsHandler(deps) {
             },
         };
     };
+    /**
+     * `ctx.progress` for one dispatch (9.52.0) — the tool's mid-call report.
+     *
+     * The whole feature is this closure. A tool call is atomic on the record
+     * (`tool_start`, then silence for as long as the handler runs, then
+     * `tool_end`), and a twelve-hop walk spends forty seconds there with nothing
+     * to show. `progress` breaks the silence over the channel already built for
+     * it: `typedEmit` mid-stage, so each report carries the real
+     * `runtimeStageId`, rides the `agentfootprint.stream.` prefix the EmitBridge
+     * already forwards, and lands in recordings with the rest of the run.
+     *
+     * The three identity facts are stamped HERE, from the dispatch this closure
+     * was built for — the tool sends only its own payload. A report that could
+     * name its own `toolCallId` could name somebody else's, and a correlation id
+     * a consumer cannot trust is worse than none.
+     *
+     * NEVER fatal: an emit that throws (a recorder that dies at the wrong moment,
+     * a scope past its stage) must not fail a tool call that is otherwise
+     * succeeding — telemetry is not the work. Named in dev mode rather than
+     * swallowed, and once per tool: a twelve-hop walk whose channel is broken
+     * would otherwise print twelve identical warnings per call.
+     */
+    const progressWarned = new Set();
+    const toolProgress = (scope, call) => ({
+        progress: (payload) => {
+            try {
+                (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.stream.tool_progress', {
+                    toolCallId: call.toolCallId,
+                    toolName: call.toolName,
+                    iteration: call.iteration,
+                    payload,
+                });
+            }
+            catch (err) {
+                if ((0, footprintjs_1.isDevMode)() && !progressWarned.has(call.toolName)) {
+                    progressWarned.add(call.toolName);
+                    // eslint-disable-next-line no-console
+                    console.warn(`[agentfootprint] tool '${call.toolName}': ctx.progress could not file a report ` +
+                        `(${err instanceof Error ? err.message : String(err)}). The call itself is ` +
+                        'unaffected — progress is telemetry, and a dropped report never fails a tool.');
+                }
+            }
+        },
+    });
     /**
      * `ctx.artifacts` + `ctx.hasArtifacts` for one dispatch — the claim-check
      * capability, shaped exactly like `ctx.credentials` (9.21.0).
@@ -1240,7 +1345,9 @@ function buildToolCallsHandler(deps) {
             }
         }
         try {
-            const result = await tool.execute(args, {
+            // `let`, not `const`: the semantic projection below replaces the value
+            // on the non-envelope path exactly as the batch loop does.
+            let result = await tool.execute(args, {
                 toolCallId,
                 iteration,
                 ...(env.signal && { signal: env.signal }),
@@ -1249,6 +1356,7 @@ function buildToolCallsHandler(deps) {
                 ...(resolvedCredential && { credential: resolvedCredential }),
                 ...toolArtifacts(scope, toolName, toolCallId),
                 ...(wantedMeta !== undefined && { wanted: wantedMeta }),
+                ...toolProgress(scope, { toolName, toolCallId, iteration }),
                 ...sessionContext(scope, toolName, toolCallId),
             });
             await endCall(toolCallId);
@@ -1265,6 +1373,12 @@ function buildToolCallsHandler(deps) {
                 // and wins over the envelope's only when the envelope declared none.
                 const coverageStatus = declareCoverage(scope, { toolName, toolCallId, iteration }, envelope.content);
                 const declaredStatus = envelope.status ?? coverageStatus;
+                // The semantic envelope (9.53.0), on the unwrapped content — the
+                // effects+semantics composition point: full envelope to the record,
+                // projection to the model. BEFORE the ceiling, which must measure
+                // what the model will actually read.
+                const semanticView = declareSemantics(scope, { toolName, toolCallId, iteration }, envelope.content);
+                const content = semanticView ?? envelope.content;
                 // The tool's own ceiling (9.20.0) measures the CONTENT — the channel
                 // that can overflow a context window. The DECLARED effects are small
                 // validated data and are still judged by the caller: a tool that
@@ -1272,7 +1386,7 @@ function buildToolCallsHandler(deps) {
                 // transition. The delivered status becomes 'invalid' (the declared
                 // status described a result the model never received — the
                 // `result_refused` event keeps what was declared).
-                const refusal = refuseOverCeiling(scope, { toolName, toolCallId, iteration }, tool, envelope.content, declaredStatus);
+                const refusal = refuseOverCeiling(scope, { toolName, toolCallId, iteration }, tool, content, declaredStatus);
                 if (refusal !== undefined) {
                     return {
                         result: refusal,
@@ -1282,12 +1396,23 @@ function buildToolCallsHandler(deps) {
                     };
                 }
                 return {
-                    result: envelope.content,
+                    result: content,
                     executed: true,
-                    envelope: declaredStatus === envelope.status ? envelope : { ...envelope, status: declaredStatus },
+                    envelope: declaredStatus === envelope.status && semanticView === undefined
+                        ? envelope
+                        : {
+                            ...envelope,
+                            content,
+                            ...(declaredStatus !== undefined && { status: declaredStatus }),
+                        },
                 };
             }
             const coverageStatus = declareCoverage(scope, { toolName, toolCallId, iteration }, result);
+            // The semantic envelope (9.53.0) on this path's own execute boundary —
+            // a resumed call's envelope is judged exactly as an inline one's.
+            const semanticView = declareSemantics(scope, { toolName, toolCallId, iteration }, result);
+            if (semanticView !== undefined)
+                result = semanticView;
             const refusal = refuseOverCeiling(scope, { toolName, toolCallId, iteration }, tool, result, coverageStatus);
             if (refusal !== undefined) {
                 // Synthesized empty-effects envelope: the resume paths read the
@@ -1955,6 +2080,7 @@ function buildToolCallsHandler(deps) {
                                 ...(resolvedCredential && { credential: resolvedCredential }),
                                 ...toolArtifacts(scope, tc.name, tc.id),
                                 ...(wantedMeta !== undefined && { wanted: wantedMeta }),
+                                ...toolProgress(scope, { toolName: tc.name, toolCallId: tc.id, iteration }),
                                 ...sessionContext(scope, tc.name, tc.id),
                             });
                             // A code-runner tool leaves the SHAPE of what it just ran, keyed by
@@ -2000,6 +2126,17 @@ function buildToolCallsHandler(deps) {
                             const coverageStatus = declareCoverage(scope, { toolName: tc.name, toolCallId: tc.id, iteration }, result);
                             if (toolStatus === undefined)
                                 toolStatus = coverageStatus;
+                            // The semantic envelope (9.53.0), on the unwrapped content and
+                            // AFTER coverage (whose funnel absorbs the envelope's own
+                            // `coverage` field), BEFORE the ceiling (which must measure
+                            // what the model will actually read, and must not silently
+                            // delete grain/provenance — they are already on the record by
+                            // the time it fires). Everything downstream — governance, the
+                            // cap, history, `tool_end` — sees the compact projection; the
+                            // full envelope rides `tools.semantics_declared`.
+                            const semanticView = declareSemantics(scope, { toolName: tc.name, toolCallId: tc.id, iteration }, result);
+                            if (semanticView !== undefined)
+                                result = semanticView;
                             // The tool's own refusing ceiling (9.20.0) — at the execute
                             // boundary, BEFORE the gates and the after-tool chain, so
                             // governance and the agent-level cap compose over what the