agentfootprint 9.100.0 → 9.102.0

package/dist/core/Agent.js

@@ -142,6 +142,36 @@ const registry_js_1 = require("../thinking/registry.js");
 // Public types (AgentOptions, AgentInput, AgentOutput) extracted to
 // ./agent/types.ts and re-exported above (v2.11.1).
 // AgentState extracted to ./agent/types.ts (v2.11.1).
+/**
+ * The ledger-fact hold's default ceiling (9.102.0): how many fact turns the
+ * window holds beyond `keepRecentTurns` when `.findings()` and a window
+ * strategy are both configured and nobody named a number. Resolved in the
+ * constructor, ONCE, and threaded to `buildWindowStage` as a plain number —
+ * the stage applies no default of its own (absent = unarmed = no hold), so a
+ * reader has one place to look. `window/options.ts ·
+ * DEFAULT_KEEP_LAST_TOOL_RESULTS` is the pin's twin of this constant.
+ */
+const DEFAULT_KEEP_LEDGER_FACTS = 4;
+/**
+ * Validate the `keepLedgerFacts` dial — `window/options.ts ·
+ * requireKeepLastToolResults`'s twin: the same rule, the same moment.
+ * Refused at construction, never mid-run.
+ */
+function requireKeepLedgerFacts(value, label) {
+    if (value === false)
+        return;
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${label}: keepLedgerFacts must be a whole number >= 0, or false, got ` +
+            `${String(value)}. It is how many fact turns the window holds beyond ` +
+            `keepRecentTurns under .findings(); 0 and false both switch the hold off.`);
+    }
+}
+/** `false` → `0`; a number as named; nothing named → the default. */
+function resolveKeepLedgerFacts(named) {
+    if (named === false)
+        return 0;
+    return named ?? DEFAULT_KEEP_LEDGER_FACTS;
+}
 class Agent extends RunnerBase_js_1.RunnerBase {
     name;
     id;
@@ -244,6 +274,17 @@ class Agent extends RunnerBase_js_1.RunnerBase {
     contextBudget;
     permissionChecker;
     toolArgValidation;
+    /** See AgentOptions.findings (9.101.0). Set by `.findings()` and undefined
+     *  on every other agent — the one value every findings gate below is
+     *  conditioned on, so an unarmed agent hands each stage exactly the deps
+     *  it always did. `serve` is threaded to seed (the run constant
+     *  `findingsServe`) and to call-llm (`findingsServe` in its deps) on an
+     *  armed agent only. `keepLedgerFacts` is resolved once, here in the
+     *  constructor (this door over `AgentOptions.keepLedgerFacts`), into the
+     *  `keepLedgerFacts` field below and threaded to the window stage on an
+     *  armed agent with a window, where `stages/window.ts · buildWindowStage`
+     *  spends it as the `'ledger-fact'` pin ceiling. */
+    findingsOptions;
     /** The opt-in tool-result ceiling in characters (9.11.0). Absent → results
      *  are never measured. See {@link AgentOptions.maxToolResultChars}. */
     maxToolResultChars;
@@ -306,6 +347,13 @@ class Agent extends RunnerBase_js_1.RunnerBase {
     /** The last-tool-result pin (9.57.0) — set only when the operator named a
      *  value other than the default 2. See AgentOptions.keepLastToolResults. */
     keepLastToolResults;
+    /** The ledger-fact hold's ceiling (9.102.0), RESOLVED — set exactly when
+     *  `.findings()` is on: `findings({ keepLedgerFacts })` over
+     *  `AgentOptions.keepLedgerFacts`, `false` → `0`, nothing named →
+     *  `DEFAULT_KEEP_LEDGER_FACTS`. Undefined on every unarmed agent, so the
+     *  thread into the window stage reads as the decision it is. See
+     *  AgentOptions.keepLedgerFacts. */
+    keepLedgerFacts;
     /** See AgentOptions.integrityPosture (9.60.0). Default 'observe'. */
     integrityPosture = 'observe';
     /**
@@ -427,6 +475,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
      *  destroyed by the act of continuing, which is the one thing retention
      *  exists to prevent. Cleared on first read, exactly like the history. */
     pendingResumeFolded;
+    /** Its sibling for the findings ledger (9.101.0) — the model's standings
+     *  on results this process never saw, carried by the checkpoint and
+     *  restored as a stored record. Cleared on first read, like the history. */
+    pendingResumeFindingsLedger;
     /** The last completed run's final answer — see `checkpoint()` for why it is
      *  kept here rather than read back from the recording. Undefined after a run
      *  that failed or paused. */
@@ -605,6 +657,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             this.permissionChecker = opts.permissionChecker;
         if (opts.toolArgValidation !== undefined)
             this.toolArgValidation = opts.toolArgValidation;
+        if (opts.findings !== undefined)
+            this.findingsOptions = opts.findings;
         // The tool-result ceiling (9.11.0). Refused HERE, naming the value, rather
         // than at the first tool call of the first run — a dial that cannot cap
         // anything is a configuration mistake, not a runtime condition.
@@ -672,6 +726,35 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             (0, options_js_1.requireKeepLastToolResults)(opts.keepLastToolResults, 'Agent');
             this.keepLastToolResults = opts.keepLastToolResults;
         }
+        // Its content-aware sibling (9.102.0). The top-level door is refused
+        // HERE, whether or not `.findings()` is on — a dial that is silently
+        // ignored is a configuration mistake, not a runtime condition (the
+        // `.findings()` door was refused by the builder). The value is resolved
+        // ONCE, under the arm only: the `.findings()` door wins when both are
+        // given, `false` is `0`, nothing named is the default. Without
+        // `.findings()` there is no ledger to hold facts from, so the option is
+        // accepted and does nothing — the keepLastToolResults-without-a-window
+        // precedent.
+        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.
+            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').");
+            }
+            this.keepLedgerFacts = resolveKeepLedgerFacts(this.findingsOptions.keepLedgerFacts ?? opts.keepLedgerFacts);
+        }
         // Refused at construction, never mid-run — a misspelled posture that was
         // ignored would leave the liveness theorems switched off in an agent
         // that believes they are on (the concurrency-mode precedent).
@@ -1356,7 +1439,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 this.conversationOwner(), 
                 // …and the same graph cursor (SG-C), from the same snapshot reader —
                 // one reader, two carriers, so neither can lose what the other keeps.
-                this.continuityCursorOf(this.getLastSnapshot()?.sharedState), this.evidenceRecoveryOf(this.getLastSnapshot()?.sharedState));
+                this.continuityCursorOf(this.getLastSnapshot()?.sharedState), this.evidenceRecoveryOf(this.getLastSnapshot()?.sharedState), 
+                // …and the findings ledger (9.101.0), from the same snapshot reader
+                // `checkpoint()` uses — one reader, two carriers.
+                this.findingsLedgerOf(this.getLastSnapshot()?.sharedState));
                 throw new runCheckpoint_js_1.RunCheckpointError(cause, checkpoint);
             }
             throw cause;
@@ -1377,6 +1463,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // nobody asked it to. One run, one continuation.
             this.pendingResumeHistory = undefined;
             this.pendingResumeFolded = undefined;
+            this.pendingResumeFindingsLedger = undefined;
             this.pendingResumeSkillCursor = undefined;
             this.pendingEvidenceRecovery = undefined;
         }
@@ -1783,6 +1870,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         const owner = this.conversationOwner();
         const skillCursor = this.continuityCursorOf(state);
         const evidenceRecovery = this.evidenceRecoveryOf(state);
+        const findingsLedger = this.findingsLedgerOf(state);
         return {
             version: 1,
             runId: this.currentRunContext.runId,
@@ -1802,6 +1890,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // exact byte shape.
             ...(skillCursor !== undefined && { skillCursor }),
             ...(evidenceRecovery !== undefined && { evidenceRecovery }),
+            // The model's standings (9.101.0) — absent unless the run recorded any,
+            // by the `folded` rule: an optional key, never a format change.
+            ...(findingsLedger !== undefined && { findingsLedger }),
         };
     }
     /** Both checkpoint doors keep the repair budget separately from conversation text. */
@@ -1855,6 +1946,20 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             return undefined;
         return structuredClone(spans);
     }
+    /**
+     * The findings ledger for a checkpoint (9.101.0) — `foldedSpansOf`'s twin:
+     * one reader for `checkpoint()` and the crash carrier, `undefined` when the
+     * run recorded no rows (so the key stays absent), and a detached copy
+     * otherwise, never a reference into the live heap.
+     *
+     * @internal
+     */
+    findingsLedgerOf(state) {
+        const ledger = state?.findingsLedger;
+        if (ledger === undefined || ledger.length === 0)
+            return undefined;
+        return structuredClone(ledger);
+    }
     /**
      * The two owner facts every conversation carrier stamps — who the run was
      * for, and which agent ran it (9.2.0).
@@ -1901,6 +2006,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // and `undefined` is the right answer there — it means "this conversation
         // recorded no folds", which is exactly true.
         this.pendingResumeFolded = cp.folded;
+        // The findings ledger beside it (9.101.0). Stashed whether or not THIS
+        // agent is armed: seed restores it only under `.findings()` (the deps
+        // gate), and an unarmed continuation consumes and ignores it — exactly
+        // like a `folded` field on an agent that never folds.
+        this.pendingResumeFindingsLedger = cp.findingsLedger;
         // The conversation's skill cursor (SG-C). Stashed unconditionally —
         // whether it is HONORED is seed's `restoreSkillCursor` gate, which reads
         // the mounted graph's `continuity` declaration; a checkpoint written by a
@@ -2460,6 +2570,19 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 getRunContext: getRunCtx,
             }));
         }
+        // Same wiring for `agentfootprint.findings.*` (9.101.0) — the ledger's two
+        // events, filed by `recordFindings` on scope. Attached only under
+        // `.findings()`: an unarmed agent gains no bridge, no listener and no
+        // per-event work, and `agent.on('agentfootprint.findings.*')` can only
+        // ever fire on an agent that could have filed a row.
+        if (this.findingsOptions !== undefined) {
+            attachObserver(new EmitBridge_js_1.EmitBridge({
+                id: 'agentfootprint.findings-bridge',
+                prefix: 'agentfootprint.findings.',
+                dispatcher,
+                getRunContext: getRunCtx,
+            }));
+        }
         for (const r of this.attachedRecorders) {
             // A recorder's OWN `delivery` field is more specific than the
             // agent-level default — footprintjs's options bag would override the
@@ -2797,6 +2920,34 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         const state = this.getLastSnapshot()?.sharedState;
         return state?.unsupportedValues;
     }
+    /**
+     * The last run's findings ledger (9.101.0) — the model's OWN standings on
+     * its tool results, as `.findings()` recorded them: `basis` rows (what a
+     * call was for, declared before it ran), `standing` rows (`fact` with the
+     * assertions stood on, `open`, `ruled-out`, `noise` — the LAST row per
+     * `toolCallId` is the current reading; earlier ones are quotable history)
+     * and `conflict` rows (two stood-on readings that disagree, witnesses by
+     * identity). Undefined when the agent has no `.findings()` OR the model
+     * declared nothing — never an empty array standing in for "no findings",
+     * and an id with no standing row is undeclared, never `open`.
+     *
+     * Detached from the execution record (`structuredClone`), so a caller may
+     * keep or mutate it without touching the run's state.
+     *
+     * @example
+     * ```ts
+     * await agent.run({ message: 'which port is down?' });
+     * const current = new Map<string, string>();
+     * for (const row of agent.findings() ?? []) {
+     *   if (row.kind === 'standing') current.set(row.toolCallId, row.standing);
+     * }
+     * ```
+     */
+    findings() {
+        const ledger = this.getLastSnapshot()?.sharedState
+            ?.findingsLedger;
+        return ledger === undefined ? undefined : structuredClone(ledger);
+    }
     /** The last run's answer checks, detached from its execution record.
      * Undefined means no terminal validation ran, never an implicit pass. */
     answerValidation() {
@@ -3049,6 +3200,20 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 this.pendingResumeFolded = undefined;
                 return f;
             },
+            // The findings ledger (9.101.0): the arm, the serve mode it puts on the
+            // record (the `forcedOutputToolName` precedent — a build-time constant
+            // the rebuild reads instead of the receipt), and the continued
+            // conversation's rows, all under the one gate — an unarmed agent hands
+            // seed exactly the deps object it always did.
+            ...(this.findingsOptions !== undefined && {
+                findings: true,
+                findingsServe: this.findingsOptions.serve ?? 'ledger-and-facts',
+                consumePendingResumeFindingsLedger: () => {
+                    const l = this.pendingResumeFindingsLedger;
+                    this.pendingResumeFindingsLedger = undefined;
+                    return l;
+                },
+            }),
             // The conversation's inherited skill cursor (SG-C). Consumed (cleared)
             // on every run; HONORED only when the mounted graph declared
             // `continuity: 'conversation'` — the same one-option-one-behavior gate
@@ -3109,6 +3274,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // name uniqueness; produces the dispatch map.
         const { registryByName, toolSchemas, toolDeclaringSkills, toolClaimants } = (0, buildToolRegistry_js_1.buildToolRegistry)(registry, this.injections, {
             hasArtifactStore: artifactStore !== undefined,
+            // The reserved-argument refusal (9.101.0) — only when the ledger is
+            // armed may a registry tool's own `_findings` be refused.
+            ...(this.findingsOptions !== undefined && { findings: true }),
         });
         // A statically registered tool that declares `wants` on an agent with no
         // store is configuration that lies: every call would be refused at
@@ -3371,6 +3539,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ...(budget?.tools !== undefined && { budgetCap: budget.tools }),
             // Steps (9.18.0): per-step narrowing + banner + the skip_step offer.
             ...(stepPlanFor !== undefined && { stepPlanFor }),
+            // The findings ledger (9.101.0): the ONE decoration site is inside this
+            // slot; the gate rides in value-conditionally.
+            ...(this.findingsOptions !== undefined && { findings: true }),
         });
         // callLLM extracted to ./agent/stages/callLLM.ts (v2.11.2). Same
         // late-binding pattern as seed for toolSchemas (computed below).
@@ -3379,6 +3550,18 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 this.evidenceGate.posture !== 'assist' && {
                 hasEvidenceRecovery: true,
             }),
+            // The findings ledger (9.101.0): the choice seam and `postValidate`
+            // read peeled args / content under `findings`; the SERVING (step 3) —
+            // the ledger piece after the recovery piece, the wire-only collapse of
+            // judged results — rides `hasFindingsLedger` with its mode, the same
+            // value seed records as the run constant `findingsServe`. One gate,
+            // the `hasEvidenceRecovery` grammar: an unarmed agent hands the stage
+            // exactly the deps it always did and reads no new key.
+            ...(this.findingsOptions !== undefined && {
+                findings: true,
+                hasFindingsLedger: true,
+                findingsServe: this.findingsOptions.serve ?? 'ledger-and-facts',
+            }),
             ...(this.answerValidationConfig !== undefined && { suppressDraftTokens: true }),
             // The receipt's salt (9.88.0) — read per call, like seed's own accessor.
             getRunId: () => this.currentRunContext?.runId,
@@ -3474,6 +3657,16 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                     ...(this.keepLastToolResults !== undefined && {
                         keepLastToolResults: this.keepLastToolResults,
                     }),
+                    // The findings ledger (9.102.0): the arm and the RESOLVED
+                    // ledger-fact ceiling, together or not at all. `keepLedgerFacts`
+                    // is set exactly when `.findings()` is on, so an unarmed agent
+                    // hands the stage exactly the deps object it always did; an
+                    // armed agent with no window strategy threads nothing, because
+                    // this whole stage does not exist for it.
+                    ...(this.keepLedgerFacts !== undefined && {
+                        hasFindingsLedger: true,
+                        keepLedgerFacts: this.keepLedgerFacts,
+                    }),
                     ...(pricingTable !== undefined && { pricingTable }),
                     ...(costBudget !== undefined && { costBudget }),
                 }),
@@ -3513,7 +3706,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // exactly the arguments it always did — and `buildRouteDeciderStage`'s
         // no-judge fast path still returns the very function reference every
         // pre-9.83.0 chart was given.
-        this.noticePriorTurnEvidence && this.evidenceGate !== undefined ? true : undefined);
+        this.noticePriorTurnEvidence && this.evidenceGate !== undefined ? true : undefined, 
+        // THE ANSWER TURN'S STANDINGS (9.101.0) — the same value-conditional
+        // trailing positional, for the same reason: an unarmed agent hands the
+        // builder exactly the arguments it always did.
+        this.findingsOptions !== undefined ? true : undefined);
         const routeDecider = this.answerValidationConfig === undefined
             ? baseRouteDecider
             : (0, answerValidation_js_1.withAnswerValidation)(baseRouteDecider, this.answerValidationConfig, this.outputSchemaParser, artifactStore, () => this.consentOutstanding.size > 0);
@@ -3529,6 +3726,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // contract to read it (9.61.0) — value-conditional, so every other
             // agent commits exactly what it always did.
             ...(this.claimContract !== undefined && { collectClaimFacts: true }),
+            // The findings ledger (9.101.0) — the peel, the basis row and the
+            // previous batch's standings all live in this handler under this gate.
+            ...(this.findingsOptions !== undefined && { findings: true }),
             // THE WRITE SEAM (9.77.0) — `empty-lookup`. Handed the SAME harvested
             // map callLLM reads at the choice seam, so the two stages agree by
             // construction about which calls are armed. Value-conditional on both
@@ -3719,6 +3919,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // Escalation (9.19.0): the grouped chart threads `skillEscalated`
             // across the sf-llm-call boundary only when the policy exists.
             ...(this.skillBrains?.escalation !== undefined && { hasEscalation: true }),
+            // The findings ledger (9.102.0): both charts compute the OFFER on the
+            // Tools branch's mount only under the arm — the same value-conditional
+            // grammar as the slot's `findings` and callLLM's `hasFindingsLedger`,
+            // so the three can never disagree about whether the ledger is armed.
+            ...(this.findingsOptions !== undefined && { hasFindingsLedger: true }),
             // `.limitsTravelWithTheAnswer()` (this release) — 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