agentfootprint 9.119.0 → 9.121.0

package/AGENTS.md

@@ -259,8 +259,9 @@ delivered status `'absent'` (route it with `onToolStatus: 'absent'`) and grounds
 COVERAGE in the evidence gate — so an id the model invented does not become grounded by one
 lookup that found nothing. It is never an error: nothing retries it, nothing refuses it, no
 `error: true`. Add `.limitsTravelWithTheAnswer()` on the agent and the framework APPENDS the
-run's declared coverage to the final answer string (not to streamed tokens; it breaks
-`runTyped()`'s JSON), so the model cannot drop what it never wrote.
+run's declared coverage to the final answer string (not to streamed tokens), so the model
+cannot drop what it never wrote. With `.outputSchema()` nothing is appended — the JSON stays
+parseable by `runTyped()` and the same limits come back as data: `agent.answerCoverage()`.
 
 ## Observing a run
 

package/CAPABILITIES.md

@@ -64,10 +64,12 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | a model head-mathing a total from tool-result numbers while a compute tool sits unused on the wire — a LATE line each iteration naming the staged refs and the `wants` tool that spends them (recency working FOR the instruction), plus the revise correction naming the same route | `nudge: true` (default off) + `stagedRefsNudgeLine` + `findStagedRefs` + `grounding_nudged` | `src/core/agent/stagedRefs.ts` | 9.75.0 |
 | a tool answering "I looked and found nothing", routably | `absent` + `looked_for` + `checked`/`not_checked`/`cannot_cover` + `tryInstead` (delivered status `'absent'`, routable by `onToolStatus`) | `src/core/agent/coverage/absent.ts` | 9.43.0 |
 | stating what a clean answer does NOT rule out | `coverage` + the declaration `{ checked, not_checked?, cannot_cover? }` | `src/core/agent/coverage/ledger.ts` | 9.43.0 |
+| a TYPED answer (`.outputSchema()`) carrying the limits its tools declared WITHOUT breaking its JSON — the same limits `.limitsTravelWithTheAnswer()` appends to a prose answer, as data beside it (checked / not checked / cannot cover, duplicates said once, every entry kept); `runTyped()` parses the model's answer untouched | `agent.answerCoverage()` + `turn_end.answerCoverage` + `AgentState.answerCoverage` (with `.outputSchema()` + `.limitsTravelWithTheAnswer()`; absent when no tool declared a limit) | `src/core/agent/stages/answerCoverage.ts` | 9.121.0 |
 | a person-readable short form of a coverage item, and whether an unchecked item is about EXISTENCE (does the thing asked about exist at all) or SCOPE (outside what the tool reaches) — on the record for a report, never in the model's request, never evidence. `short`: at most 80 chars, one line, never longer than `what`. `kind`: 'existence' or 'scope', on notChecked and cannotCover only. Refused at `absent()` and `coverage()`, read-never-repaired on a foreign envelope; carried by `tools.absent`, `tools.coverage_declared` and `coverageDeclared`; stripped from every served envelope, with `tool_end.modelResult` stamped where it differs | `CoverageItem` + `absent` + `coverage` | `src/core/agent/coverage/` | 9.116.0 |
 | a skill's plain name for a person ("array estate report" for `array-inventory`) on the recording, without changing what the model reads or what a graph draws — at most 60 chars, one line of plain visible text, not the id; carried as `skill.graph_declared` `nodes[].title` on a skill-graph agent, absent when not declared | `defineSkill` + `title` | `src/lib/injection-engine/factories/defineSkill.ts` | 9.116.0 |
 | how many of an answer's values the evidence check actually LOOKED UP — `candidates` also counts values the person's message or the app's instructions already held, which are never looked up; found plus not found, before the 12-value slice, on every `evidence_checked` | `lookedUp` + `EvidenceVerdict` | `src/core/agent/evidence/` | 9.116.0 |
 | explaining ONE answer to a person in plain words — what was asked, how it was routed, what each tool checked and did not check, what it found, how sure, and anything wrong — every line from the record by a fixed versioned template (never a model), each with its template id and who vouches for it (person / library / tool / model / app), "not recorded" instead of a guess, own-run events only, three checks with the ones that could not run said aloud | `accountForAnswer` + `AnswerAccount` | `src/lib/answer-account/` | 9.116.0 |
+| how far an answer STANDS — known · consistent with the record · not sure (with the reasons) · ask · not assessed — folded from the run's COMMITTED record (never from the model's confidence, never from events, never "known" from silence: only a passed enforce answer check supports it); each reason names the row it rests on, `checked` counts what ran, this turn only; a pause of any kind reads `ask` from the recording alone, a run with no answer has no standing; one emptiness reader shared with the answer account (`coverage/emptiness.ts`: a `coverage()` envelope read through, a described result counted, an undeclared empty rowset said aloud) | `assessAnswer` + `AnswerAssessment` (on the observe door), `agent.assessment()` | `src/core/agent/assessment/` | 9.120.0 |
 | serving that explanation to a browser without the recording: one opt-in wire op returns the account plus allow-listed "show me" leaves, owner-only on the `artifact-get` path, lane-free, cached and single-flight, a stated size ceiling, and a swept record answering "not available" even when cached | `standingAgent({ answerAccounts })` + `{ op: 'answer-account', ref }` + `answerAccountPointerKey` | `src/hosting/answerAccounts.ts` | 9.116.0 |
 | bounding what one session can ask of the artifact door at once: `artifact-head`, `artifact-get` and `answer-account` counted together per session, after the ownership check, refused 429 by name while every other session is served | `standingAgent({ artifactOpsPerSession })` + `ArtifactOpsBusyError` | `src/hosting/standingAgent.ts` | 9.116.0 |
 | minting one of those shapes from a tool that is NOT JavaScript — the canonical note sentences and reserved marker keys as DATA, so a Python/Go/Rust sidecar reads a file instead of regex-scraping `dist/esm` (which a consumer really did) | `canonical-notes.json` at the package root + the `./canonical-notes.json` exports entry, GENERATED from the built barrel by `scripts/gen-canonical-notes.mjs` | `scripts/gen-canonical-notes.mjs` | 9.70.0 |

package/README.md

@@ -117,7 +117,7 @@ Whatever a tool returns is what the model reads next. When that value has limits
 | `coverage(value, { … })` | any other value that has limits | your value, with what was and was not checked | `tools.coverage_declared` |
 | `absent({ … })` | nothing matched | what was looked for, where, and that a retry returns the same | `tools.absent` |
 
-Never wrap one in another. Add `.limitsTravelWithTheAnswer()` and the declared coverage is appended to the final answer — provenance and grain never are.
+Never wrap one in another. Add `.limitsTravelWithTheAnswer()` and the declared coverage is appended to the final answer — or, for a typed `.outputSchema()` answer, returned beside it as data by `agent.answerCoverage()`. Provenance and grain never are.
 
 ```typescript
 import { absent, coverage, describedResult } from 'agentfootprint';

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

@@ -259,8 +259,9 @@ delivered status `'absent'` (route it with `onToolStatus: 'absent'`) and grounds
 COVERAGE in the evidence gate — so an id the model invented does not become grounded by one
 lookup that found nothing. It is never an error: nothing retries it, nothing refuses it, no
 `error: true`. Add `.limitsTravelWithTheAnswer()` on the agent and the framework APPENDS the
-run's declared coverage to the final answer string (not to streamed tokens; it breaks
-`runTyped()`'s JSON), so the model cannot drop what it never wrote.
+run's declared coverage to the final answer string (not to streamed tokens), so the model
+cannot drop what it never wrote. With `.outputSchema()` nothing is appended — the JSON stays
+parseable by `runTyped()` and the same limits come back as data: `agent.answerCoverage()`.
 
 ## Observing a run
 

package/dist/core/Agent.js

@@ -14,6 +14,29 @@
  *            agentfootprint.stream.tool_start / tool_end
  *            agentfootprint.context.* (via ContextRecorder)
  */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = exports.AgentBuilder = void 0;
 const footprintjs_1 = require("footprintjs");
@@ -135,6 +158,7 @@ const RunnerBase_js_1 = require("./RunnerBase.js");
 const validators_js_1 = require("./agent/validators.js");
 const route_js_1 = require("./agent/stages/route.js");
 const answerValidation_js_1 = require("./agent/stages/answerValidation.js");
+const answerCoverage_js_1 = require("./agent/stages/answerCoverage.js");
 const index_js_1 = require("../answer-validation/index.js");
 const seed_js_1 = require("./agent/stages/seed.js");
 const errors_js_3 = require("./agent/middleware/errors.js");
@@ -266,10 +290,12 @@ class Agent extends RunnerBase_js_1.RunnerBase {
      */
     evidenceGate;
     /**
-     * `.limitsTravelWithTheAnswer()` (this release) — whether the run's declared
-     * coverage is folded into the final answer. False for every agent that did
-     * not ask for it; the RECORDING half of the coverage primitives does not
-     * consult it.
+     * `.limitsTravelWithTheAnswer()` — whether the run's declared coverage
+     * travels with the final answer: appended as a block to a prose answer, or,
+     * when an output schema makes the answer TYPED, committed beside it as data
+     * (`answerCoverage()`), because JSON followed by prose is not JSON. False for
+     * every agent that did not ask for it; the RECORDING half of the coverage
+     * primitives does not consult it.
      */
     limitsTravelWithTheAnswerValue = false;
     skillGraphCascade;
@@ -1310,6 +1336,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
      *
      * Throws if the agent has no outputSchema set or if the run
      * pauses (use `run()` directly when pauses are expected).
+     *
+     * With `.limitsTravelWithTheAnswer()`, nothing is appended to a typed
+     * answer: the limits its tools declared come back as data, from
+     * `agent.answerCoverage()`.
      */
     async runTyped(input, options) {
         if (!this.outputSchemaParser) {
@@ -3165,6 +3195,88 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ?.answerValidation;
         return report === undefined ? undefined : structuredClone(report);
     }
+    /**
+     * The limits of the last run's TYPED answer, as data — what its tools
+     * declared they `checked`, did not check (`notChecked`) and can never see
+     * (`cannotCover`), folded across the run: duplicates said once, every entry
+     * kept.
+     *
+     * Set when the agent has an output schema AND `.limitsTravelWithTheAnswer()`:
+     * a typed answer is JSON, and the limits block that option appends to a
+     * prose answer would stop it being JSON, so for a typed answer the limits
+     * travel beside it instead — here, on `turn_end.answerCoverage`, and in
+     * `getLastSnapshot().sharedState.answerCoverage`, one value three ways. The
+     * answer string, and so `runTyped()`, is exactly the model's.
+     *
+     * `undefined` when the run's tools declared no limits, on a prose answer
+     * (the block is in the answer string there; `sharedState.coverageDeclared`
+     * holds the raw rows either way), and before the first run. Detached from
+     * the execution record, so a caller may keep or mutate it.
+     *
+     * @example
+     * ```ts
+     * const agent = Agent.create({ provider, model })
+     *   .tool(replicationHealth) // returns coverage(verdict, { … })
+     *   .outputSchema(Verdict)
+     *   .limitsTravelWithTheAnswer()
+     *   .build();
+     *
+     * const verdict = await agent.runTyped({ message: 'is replication healthy?' });
+     * const limits = agent.answerCoverage();
+     * for (const item of limits?.cannotCover ?? []) {
+     *   console.log(`never covered: ${item.what} (${item.why})`);
+     * }
+     * ```
+     */
+    answerCoverage() {
+        const limits = this.getLastSnapshot()?.sharedState
+            ?.answerCoverage;
+        return limits === undefined ? undefined : structuredClone(limits);
+    }
+    /**
+     * How far the last run's answer stands — folded from its COMMITTED record,
+     * never from how sure the model sounded: `known` · `consistent` (checks ran,
+     * none fired — never "verified") · `not-sure` (with the reasons) · `ask` (the
+     * run paused on a question still waiting for a person) · `not-assessed`
+     * (nothing on the record could be checked).
+     *
+     * The same pure fold as `assessAnswer` on `agentfootprint/observe`, over this
+     * agent's last snapshot; it reads committed state, never events, so a later
+     * reader of the same recording folds the same standing. It resolves
+     * asynchronously because the fold is loaded through `import()` on first use —
+     * an agent that never asks does not carry it.
+     *
+     * Resolves to `undefined` when there is no answer to assess: before the first
+     * run, while a run is in flight, and after a run that threw or whose answer a
+     * rule refused (the typed error carries that verdict).
+     *
+     * `declarations` is the answer account's object, accepted as it is: the fold
+     * reads `tools[name].rowsAt`, where an object result keeps its rows.
+     *
+     * @example
+     * ```ts
+     * await agent.run({ message: 'Which ports on switch A are down?' });
+     * const a = await agent.assessment();
+     * if (a?.standing === 'not-sure') {
+     *   for (const r of a.reasons) console.log(r.reason); // e.g. 'empty-undeclared'
+     * }
+     * ```
+     */
+    async assessment(declarations) {
+        const snapshot = this.getLastSnapshot();
+        if (snapshot === undefined)
+            return undefined;
+        // Settled before the fold, which cannot tell a crash from its committed state: an answer
+        // this run RETURNED (`lastRunAnswer`, cleared at every run's start), or a pause — the fold
+        // reads that one from the committed state itself. Read BEFORE the import resolves, so a
+        // run started meanwhile cannot change which run is assessed.
+        const paused = this.lastExecutor?.isPaused() === true;
+        if (!paused && this.lastRunAnswer === undefined)
+            return undefined;
+        // Loaded on first use, off the default graph (the findings/peel.ts precedent).
+        const { assessAnswer } = await Promise.resolve().then(() => __importStar(require('./agent/assessment/assess.js')));
+        return assessAnswer({ snapshot }, declarations);
+    }
     finalizeResult(executor, result) {
         const paused = this.detectPause(executor, result);
         if (paused)
@@ -3989,6 +4101,15 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         const routeDecider = this.answerValidationConfig === undefined
             ? baseRouteDecider
             : (0, answerValidation_js_1.withAnswerValidation)(baseRouteDecider, this.answerValidationConfig, this.outputSchemaParser, artifactStore, () => this.consentOutstanding.size > 0);
+        // `.limitsTravelWithTheAnswer()` on a TYPED answer — decided once, here.
+        // An output schema makes the answer JSON, and the appended block would
+        // make it JSON followed by prose, which `runTyped()` cannot parse. So the
+        // limits travel as DATA: the Route decider's terminal decision commits the
+        // fold (`withAnswerCoverage`) and the Final branch projects it onto
+        // `turn_end`. A prose answer keeps the block; an agent that asked for
+        // neither is handed the decider it always had.
+        const limitsAsData = this.limitsTravelWithTheAnswerValue && this.outputSchemaParser !== undefined;
+        const terminalRouteDecider = limitsAsData ? (0, answerCoverage_js_1.withAnswerCoverage)(routeDecider) : routeDecider;
         // toolCallsHandler extracted to ./agent/stages/toolCalls.ts (v2.11.2).
         const toolCallsHandler = (0, toolCalls_js_1.buildToolCallsHandler)({
             registryByName,
@@ -4164,7 +4285,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             maxIterations,
             seed,
             callLLM,
-            routeDecider,
+            routeDecider: terminalRouteDecider,
             toolCallsHandler,
             // The re-ask branch — mounted only when there are retries to spend. A
             // `'tool-forced'` agent with `retries: 0` gets the constrained shape and
@@ -4219,11 +4340,14 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // The declared ontology (9.106.0): the grouped chart carries the run
             // constant across the sf-llm-call boundary, under the arm.
             ...(this.ontology !== undefined && { hasOntology: true }),
-            // `.limitsTravelWithTheAnswer()` (this release) — value-conditional, the
+            // `.limitsTravelWithTheAnswer()` — value-conditional, the
             // `resolvedModel` precedent: absent from the deps object entirely for an
             // agent that did not ask, so both builders mount the final-branch stage
-            // function they have always mounted.
-            ...(this.limitsTravelWithTheAnswerValue && { attachCoverageLimits: true }),
+            // function they have always mounted. ONE of the two, never both: a prose
+            // answer gets the appended block, a TYPED one (`limitsAsData`, above)
+            // gets the stage that appends nothing and carries the limits as data.
+            ...(this.limitsTravelWithTheAnswerValue && !limitsAsData && { attachCoverageLimits: true }),
+            ...(limitsAsData && { coverageLimitsAsData: true }),
             ...(this.answerValidationConfig !== undefined && { hasAnswerValidation: true }),
             // The out-of-budget wrap-up branch (9.56.0) — the conditional-mount law
             // above, decided once beside the Route decider that routes to it so the