agentfootprint 10.8.1 → 10.10.0

package/CAPABILITIES.md

@@ -35,6 +35,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | replaying Anthropic thinking in its original content order; refusing known unsafe active-tool replay, observing each permitted completed-turn omission before sending, and retaining that decision across checkpoints | `LLMMessage.replay` + `UnsafeThinkingReplayError` + `LLMCallHooks.onReplayPrepared` + `agentfootprint.agent.thinking_omitted` | `src/adapters/llm/anthropicThinkingReplay.ts` | 10.1.0 |
 | keeping personal data out of an agent's saved records — snapshot, narrative, every event, recordings, bug reports, answer accounts, the exporters — while the model, the tools and the caller keep the real values; the library's own list of the names the conversation travels under (proven per feature), joined with the fields your tools name; it reaches compositions (members' policies adopted) and runs a tool starts (`ctx.redact`), and readers of the record say "kept out", never "not recorded" or "no tool ran" | `Agent.create({ redact })` (a footprintjs `RedactionPolicy`) + `conversationRedaction` + `ToolExecutionContext.redact` | `src/redaction/` | 9.140.0 |
 | prompt caching that keeps hitting behind `withRetry`, `withFallback` or your own provider wrapper — the cache strategy chosen from what the adapter DECLARES (explicit breakpoints / automatic / none), never from its name, plus a moving breakpoint on the conversation tail so each call reads back what the last one sent | `LLMProvider.promptCaching` (`PromptCaching`) + `cacheStrategyFor` + `BreakpointCacheStrategy` / `AutomaticCacheStrategy` / `NoOpCacheStrategy` | `src/cache/cacheStrategyFor.ts` | 9.138.0 |
+| findings with stable tool contracts and immutable instructions, bounded late DATA outside cached history, unchanged citation admission, and call-scoped saved/resumed layout evidence | `.findings({ maxContextBytes })` + `findingsContext` + `servedAt` / `findings-layout` | `src/core/agent/findings/context.ts` | 10.10.0 |
 | Bedrock Converse prompt caching for exact verified models and geography profiles, field/TTL restrictions and four-checkpoint limit; cache read/write counts on both transports; model-aware capabilities through resilience decorators; one build warning and fixed run metadata when requested caching is unavailable; the meter accepts real engine events from `.watch()` | `bedrock` + `BedrockProvider` | `src/adapters/llm/BedrockProvider.ts` | 10.8.0 |
 | reading a static or model-aware prompt-cache capability before inspecting its mode, with unknown models failing closed | `promptCachingFor` | `src/cache/cacheStrategyFor.ts` | 10.8.0 |
 | asking a model to think in the shape THAT model takes — budget tokens on Claude 4.6 and earlier, adaptive on 4.7 and later (and on any id the table does not know), a build-time refusal for a model that cannot think; one table per wire, an adapter option for an id the table cannot read, forwarded by every wrapper, answered per side by `withFallback` | `.thinking({ budget })` + `LLMProvider.thinkingMode` + the adapters' `thinkingMode` option + `ThinkingMode` + `UnsupportedThinkingError` | `src/adapters/llm/anthropicModels.ts` | 9.141.0 |
@@ -95,6 +96,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | a value that must say how it knows itself — an unknown count that can never render as zero | `Claim<T>` (`known`/`unknown`/`notApplicable`) | `src/lib/claim/claim.ts` | 9.58.0 |
 | asking a debugging model "what did this run contradict itself about, and why?" — the Context Integrity findings, joined to the step that filed them | `find_context_errors` | `src/trace-toolpack/traceToolpack.ts` | 9.61.0 |
 | reading abnormal nodes, recorded dependency roots and downstream impact with bounded public Foottrace queries, scoped proof IDs and explicit unknown coverage; optional host-authorized storage graph, including inner tool and subflow questions | `attention_list` / `root_cause` / `impact` + `TraceToolpackArtifacts.cause` + `TraceToolpackOptions.cause` | `src/trace-toolpack/causeTools.ts` | 10.7.0 |
+| admitting a completed native root-log capture for read-only cause tools without a custom graph; partial, legacy, child and resumed coverage stays uncertain with fixed reasons | `assessCapture` | `src/trace-toolpack/causeCapture.ts` | 10.10.0 |
 | the model inventing an id or a reading that no tool ever returned — a deterministic fabrication detector on the final answer, with a posture for how hard it pushes back | `.namesAndNumbersFromEvidence()` + `posture` (`'assist'` record+flag, the default / `'guard'` one revision then ship flagged / `'rails'` refuse instead) + `shapes` + `exempt` + `minDigits` (default 4) + `nudge` (default off) | `src/core/agent/evidence/` | 9.35.0 |
 | plain decimal readings honestly rounded at the written precision (opt-in; one carried number only, no new unitless arithmetic), and exactly-two numeric range endpoints checked after declared ID shapes; short bare endpoints retain minDigits | `AgentBuilder.namesAndNumbersFromEvidence` + `NamesAndNumbersOptions` + `EvidenceVerdict` + `ComputedFigure` | `src/core/agent/evidence/` | 10.8.0 |
 | counting a HUMAN-VERIFIED value as ground for the choice-seam check — the person clicked a row, the app verified the cells against the artifact, and the id the model takes from that selection is not fabricated; the source label travels onto the record | `externalGrounds` + `ExternalGround` + `external_ground_used` | `src/integrity/unsupported-argument/check.ts` | 9.72.0 |
@@ -139,6 +141,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | scoping a skill's tools so they reach the model only while it is active | `toolsFromActiveSkill` + a no-arg posture (default off) + the stamp `autoActivate: 'currentSkill'` (a default, never an override) | `src/core/agent/toolsFromActiveSkill.ts` | 9.36.0 |
 | subscribing to every event in one domain at once | `DomainWildcard` | `src/events/dispatcher.ts` | 9.4.0 |
 | pausing a run for a person and resuming it later | `checkInApproved` / `checkInDeclined` (`{ by, note?, value? }`; a decline is NOT an abort — the model gets a "declined by human" tool result and adapts in-loop) | `src/core/checkin.ts` | 7.5.0 |
+| refusing unserved, ambiguous, malformed or known not-dispatched findings citations before host callbacks and tool execution, with request-local accepted-attempt evidence, bounded diagnostics and JSON-answer admission; no additional model call or cache-layout change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `captureFindingsRequest` + `findingsReferenceRefusal` (internal; enabled by `.findings()`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `src/core/agent/findings/admission.ts`                  | 10.9.0                          |
 | a SECOND source judging every tool result — a calibrated classifier asked what a result is worth for the declared proposition (never why the tool was called), its distribution and cost on the record beside the model's own standing, never merged, never served in its place (policy A) | `.findings({ judge })` + `Classifier` / `typesafe` / `mockClassifier` (`agentfootprint/classify`) + `JudgmentRow` / `JudgmentErrorRow` + `classifierScorer` (the scored entry choice, `agentfootprint/skill-graph`) | `src/classify/` | 9.104.0 |
 | a classifier's reading of WHICH TOOL beside every model call — the ranking, the pick and the cost on the record before the call, the model's call and the agreement after it; optionally the served list narrowed to the top-N plus the doors, on the committed record the receipt hashes and the served view rebuilds; a miss recorded and the full wire served next call, never a refusal, never an override | `.toolChoice({ classifier, serve, alwaysServe })` + `ToolChoiceRow` + `ToolChoiceOutcomeRow` + `ToolChoiceErrorRow` + `ALWAYS_SERVED_TOOLS` + `recordToolChoice` + `narrowServed` (events `agentfootprint.tool_choice.*`, bench `npm run bench:tool-choice`) | `src/core/agent/toolChoice/` | 9.105.0 |
 | a MAP of the domain the model can reason over when a result holds nothing — what each term IS (meaning, unit), how terms RELATE, which SOURCE holds a term (with the author's coverage sentence) and which registered TOOL reads it from there; declared once, validated against the tool registry at build, on the record as one run constant, served as one request-only system piece per call, never a fetch path and never inferred from | `defineOntology` + `.ontology(map)` (`AgentOptions.ontology`) + `AgentState.ontology` + `ontologyPiece` / `ONTOLOGY_INSTRUCTION` (`agentfootprint/ontology`) + `agentfootprint.ontology.served` | `src/ontology/` | 9.106.0 |

package/dist/core/Agent.js

@@ -1,19 +1,4 @@
 "use strict";
-/**
- * Agent — ReAct primitive (LLM + tools + iteration loop).
- *
- * Pattern: Builder (GoF) → produces a Runner backed by a footprintjs FlowChart.
- * Role:    Layer-5 primitive (core/). Assembles the 3-slot context
- *          pipeline + callLLM + route decider + tool-calls subflow +
- *          loopTo. Composition nestable anywhere that accepts a Runner.
- * Emits:   Via internal recorders:
- *            agentfootprint.agent.turn_start / turn_end
- *            agentfootprint.agent.iteration_start / iteration_end
- *            agentfootprint.agent.route_decided
- *            agentfootprint.stream.llm_start / llm_end
- *            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);
@@ -39,6 +24,22 @@ var __importStar = (this && this.__importStar) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = exports.AgentBuilder = void 0;
+const context_js_1 = require("./agent/findings/context.js");
+/**
+ * Agent — ReAct primitive (LLM + tools + iteration loop).
+ *
+ * Pattern: Builder (GoF) → produces a Runner backed by a footprintjs FlowChart.
+ * Role:    Layer-5 primitive (core/). Assembles the 3-slot context
+ *          pipeline + callLLM + route decider + tool-calls subflow +
+ *          loopTo. Composition nestable anywhere that accepts a Runner.
+ * Emits:   Via internal recorders:
+ *            agentfootprint.agent.turn_start / turn_end
+ *            agentfootprint.agent.iteration_start / iteration_end
+ *            agentfootprint.agent.route_decided
+ *            agentfootprint.stream.llm_start / llm_end
+ *            agentfootprint.stream.tool_start / tool_end
+ *            agentfootprint.context.* (via ContextRecorder)
+ */
 const footprintjs_1 = require("footprintjs");
 const types_js_1 = require("../reliability/types.js");
 const extractSequence_js_1 = require("../security/extractSequence.js");
@@ -867,7 +868,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         if (opts.toolArgValidation !== undefined)
             this.toolArgValidation = opts.toolArgValidation;
         if (opts.findings !== undefined)
-            this.findingsOptions = opts.findings;
+            this.findingsOptions = {
+                ...opts.findings,
+                maxContextBytes: (0, context_js_1.findingsContextBytes)(opts.findings.maxContextBytes),
+            };
         // The inputs layer's door (honesty layer 2): `true`, or `{ argumentSources }`
         // — either form mounts the layer; the object form may also arm declared
         // sources without the findings ledger.
@@ -1003,20 +1007,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         if (opts.keepLedgerFacts !== undefined)
             requireKeepLedgerFacts(opts.keepLedgerFacts, 'Agent');
         if (this.findingsOptions !== undefined) {
-            // The ledger needs the tools slot recomposed every call: from the second
-            // call on, the served `_findings` property binds the ids the model may
-            // name (`findings/offer.ts · offeredResultIds`, bound at the Tools
-            // mount) — and on a hosted model that binding is what makes a standing
-            // resolve at all (docs/design/2026-09-findings-ledger-real-model.md).
-            // `reactMode: 'classic'` selects the Tools branch on turn 1 only, so an
-            // armed classic agent would serve the offer-less base on every call and
-            // file every standing as `unknownId`. Refused loud, here at build, the
-            // `AgentBuilder.selfExplain` twin — never a silent degrade.
+            // Keep the supported findings execution modes explicit. This change
+            // restores prefix caching; it does not add findings support to classic.
             if (this.reactMode === 'classic') {
-                throw new Error("Agent: .findings() requires per-iteration slot recomposition — reactMode 'classic' " +
-                    'caches the tools slot on turn 1, so the ids the model may name (bound into every ' +
-                    'served tool schema from the second call on) would never reach it and every standing ' +
-                    "would file as unknownId. Use the default 'dynamic' mode (or 'dynamic-grouped').");
+                throw new Error("Agent: .findings() is supported in 'dynamic' and 'dynamic-grouped' modes only; reactMode 'classic' is not supported.");
             }
             this.keepLedgerFacts = resolveKeepLedgerFacts(this.findingsOptions.keepLedgerFacts ?? opts.keepLedgerFacts);
         }
@@ -3937,7 +3931,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // Message-boundary refusal (7.18+) — a `messageMiddleware` returned
         // `deny`; a refusal must never be mistaken for an answer: at 'input' no
         // model was asked, and at 'output' the middleware declined to release it.
-        if (this.messageMiddleware.length > 0) {
+        if (this.messageMiddleware.length > 0 || this.findingsOptions !== undefined) {
             const denied = state;
             if (denied.messageDeniedReason !== undefined) {
                 return {
@@ -4204,6 +4198,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ...(this.findingsOptions !== undefined && {
                 findings: true,
                 findingsServe: this.findingsOptions.serve ?? 'ledger-and-facts',
+                findingsContextBytes: this.findingsOptions.maxContextBytes,
                 // The answer-turn ask (9.103.0): VALUE-conditional inside the arm —
                 // the default `'none'` threads nothing and writes no key.
                 ...(this.findingsOptions.answerAsk === 'quote-facts' && {
@@ -4706,6 +4701,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 findings: true,
                 hasFindingsLedger: true,
                 findingsServe: this.findingsOptions.serve ?? 'ledger-and-facts',
+                findingsContextBytes: this.findingsOptions.maxContextBytes,
                 // The answer-turn ask (9.103.0): the same value seed records, so the
                 // wire and the rebuild append it from one fact; absent on `'none'`.
                 ...(this.findingsOptions.answerAsk === 'quote-facts' && {
@@ -5220,6 +5216,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // the chain's rewrites (a rewritten fill is not what the call ran with).
             ...(inputsArmed && {
                 inputsLayer: {
+                    ...(this.findingsOptions !== undefined && { findings: true }),
                     toolOf: (toolName) => resolveForLayer(toolName).tool,
                     ...(this.toolMiddleware.length > 0 && { rewrites: true }),
                     // The time layer (step T5a): a tool whose period declares forms is filled from the