agentfootprint 9.112.2 → 9.113.0

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

@@ -10,7 +10,10 @@
  *     payload so footprintjs captures a checkpoint.
  *   • `resume` runs after the consumer supplies the human's answer.
  *     Treats that answer as the paused tool's result, appends to
- *     history, then continues the ReAct iteration loop.
+ *     history, then continues the ReAct iteration loop. Calls the model
+ *     batched AFTER the paused one were never dispatched; every resume
+ *     path settles them with one fixed sentence each, a bracket and a
+ *     count, and runs none of them ("── The batch settlement (9.113.0)").
  *
  * Dispatch resolution order (9.92.0 — DISPATCH FOLLOWS THE OFFER):
  *   0. A name on THIS epoch's wire resolves to the party whose contract the
@@ -71,7 +74,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildToolCallsHandler = exports.composeReadSkillRefusal = exports.unknownToolResult = exports.notServedResult = exports.atMountedCursor = void 0;
+exports.buildToolCallsHandler = exports.producerCorpusOf = exports.notDispatchedResult = exports.pausedBatchOf = exports.composeReadSkillRefusal = exports.unknownToolResult = exports.notServedResult = exports.atMountedCursor = void 0;
 const codeRunnerTool_js_1 = require("../../codeRunnerTool.js");
 const footprintjs_1 = require("footprintjs");
 const types_js_1 = require("../../../adapters/types.js");
@@ -101,6 +104,7 @@ const reserved_js_1 = require("../findings/reserved.js");
 const offer_js_1 = require("../findings/offer.js");
 const ledger_js_2 = require("../findings/ledger.js");
 const contingent_js_1 = require("../findings/contingent.js");
+const unsettled_js_1 = require("../findings/unsettled.js");
 const evidenceIndex_js_1 = require("../evidence/evidenceIndex.js");
 const repeatedCall_js_1 = require("../repeatedCall.js");
 const toolArgsValidation_js_1 = require("../toolArgsValidation.js");
@@ -478,6 +482,130 @@ function argsForPausedCall(scope, toolCallId, peel = false) {
 function appendBatchResult(scope, entry) {
     scope.toolResults = [...(scope.toolResults ?? []), entry];
 }
+/**
+ * THE PAUSED BATCH (9.113.0) — the turn that proposed the paused call, and
+ * the calls on it that a pause left un-dispatched.
+ *
+ * The batch loop in `execute` dispatches a turn's calls one at a time, in the
+ * order the model proposed them, and every pause RETURNS from inside it: the
+ * checkpoint is taken on call k, and calls k+1..N were never reached — no
+ * gate judged them, no tool ran, no bracket opened. The resume paths used to
+ * answer call k and stop, so the next request carried N `tool_use` blocks and
+ * fewer `tool_result`s (a provider builds results only from `role: 'tool'`
+ * messages), and `iteration_end` counted one call.
+ *
+ * READ FROM `history`, NEVER CARRIED. Every pause site commits
+ * `scope.history = newHistory` before it returns, so the assistant turn that
+ * proposed the batch is on the checkpoint — and it is the very message a
+ * provider turns into the `tool_use` blocks the settlement must answer. It is
+ * therefore the one owner of "which calls does the next request carry", and
+ * the checkpoint gains no key: a checkpoint written before this release
+ * settles the same way. The window never removes the turn holding the paused
+ * call (`../window/turns.ts` · `refusalFor`, its `paused-tool` arm).
+ *
+ * The LATEST turn proposing the id is the paused one — the pause site commits
+ * that turn last, and a provider may reuse an id across turns. No such turn:
+ * `size: 0` and nothing to settle, the only answer a missing turn supports.
+ *
+ * A call after the paused one that history ALREADY answers — a `role: 'tool'`
+ * message for its id after that turn — is not un-dispatched, whoever wrote
+ * the answer. No library door writes one before the resume; a checkpoint is
+ * data, though, and an app may have patched results into a stored one.
+ * Settling such a call again would put a second result for its id on the
+ * next request, a shape a provider rejects.
+ */
+function pausedBatchOf(history, pausedToolCallId) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        const message = history[i];
+        if (message?.role !== 'assistant')
+            continue;
+        const proposed = message.toolCalls ?? [];
+        const at = proposed.findIndex((call) => call.id === pausedToolCallId);
+        if (at < 0)
+            continue;
+        const answered = new Set(history.slice(i + 1).flatMap((m) => (m.role === 'tool' ? [m.toolCallId] : [])));
+        return {
+            size: proposed.length,
+            undispatched: proposed.slice(at + 1).filter((call) => !answered.has(call.id)),
+        };
+    }
+    return { size: 0, undispatched: [] };
+}
+exports.pausedBatchOf = pausedBatchOf;
+// LENS · tool-result · persistent-history
+// reads: toolName ← the un-dispatched call on the paused turn (`pausedBatchOf`); paused ← scope.pausedToolName + scope.pausedToolCallId, the checkpoint's own carriers
+// law: may omit, never deny; every clause anchored to the call it was composed on; names no destination.
+/**
+ * What a call the paused batch never dispatched gets back (9.113.0) — ONE
+ * fixed sentence, on all four resume paths.
+ *
+ * Every clause is a past fact about one finished event, anchored by name: the
+ * call this result answers ("that call"), the call the run paused on (by id
+ * and by tool), and the resume. It names no destination. The design page's draft
+ * (`docs/design/2026-09-honest-answer-ledger.md`, § 5.5, "The batch
+ * settlement") ended "propose it again if still needed" — an instruction about a LATER call,
+ * re-read on every call after this one, the tool-less wrap-up included.
+ * Whether the call is still needed is the model's to judge from the facts;
+ * the surfaces recomposed per request (the tool list, the system prompt) own
+ * the present tense. Precedents: the 9.86.1 resumed-call refusal in this file
+ * ("was not executed on that call, and the resumed dispatch had no second
+ * checkpoint…") and `../selfCallNotice.ts` · `selfCallNotice`.
+ *
+ * "The run paused ON call …", never "call … paused the run": on two of the
+ * four doors the pause was a gate's, not the call's — a middleware's `ask`, a
+ * credential's consent need — and on all four the run paused AT that call.
+ *
+ * The sentence is for the MODEL. The same fact as data rides the settled
+ * message as `LLMMessage.notDispatched` and both of its brackets as
+ * `notDispatched` (`notDispatchedMarker`), and a reader asking "did this call
+ * run?" reads that — never this text.
+ *
+ * Exported for the producer registry (`test/modelFacingSurfaces.test.ts`).
+ */
+function notDispatchedResult(toolName, paused) {
+    return (`Tool '${toolName}' was not executed on that call: the run paused on call ` +
+        `'${paused.toolCallId}' to '${paused.toolName}', earlier in the same batch, and resumed ` +
+        `without executing the calls that followed it in that batch.`);
+}
+exports.notDispatchedResult = notDispatchedResult;
+/**
+ * The same fact as DATA (9.113.0) — the ONE composer of the settlement's
+ * marker, `{ pausedCall: { toolCallId, toolName } }`. The settled call's
+ * history message (`LLMMessage.notDispatched`) and both of its brackets
+ * (`ToolStartPayload.notDispatched`, `ToolEndPayload.notDispatched`) each take
+ * a fresh copy from here, so the three carriers can never disagree and no
+ * reader holds an object another reader holds.
+ */
+function notDispatchedMarker(paused) {
+    return { pausedCall: { toolCallId: paused.toolCallId, toolName: paused.toolName } };
+}
+/**
+ * The empty-lookup check's PRODUCER CORPUS (9.77.0) — every `role: 'tool'`
+ * RESULT in `history` from a tool the judged one names in `argumentsFrom`,
+ * as the run served it. The caller hands the history the judged call was
+ * served (the call itself is pushed after it), so a producer called earlier in
+ * the same batch is already in it — which is right: the model can only have
+ * taken a value from a result it had already been served.
+ *
+ * A message the batch settlement wrote (9.113.0) is no result: its ground
+ * never ran, so it produced nothing to take a value from. Read off the marker
+ * (`../findings/offer.ts` · `isResultMessage`), never the sentence.
+ *
+ * Exported for its unit test (`test/integrity/emptyLookup.test.ts`).
+ */
+function producerCorpusOf(history, argumentsFrom) {
+    const produced = [];
+    for (const message of history) {
+        if (!(0, offer_js_1.isResultMessage)(message))
+            continue;
+        const name = message.toolName;
+        if (typeof name !== 'string' || !argumentsFrom.includes(name))
+            continue;
+        produced.push({ toolName: name, text: message.content });
+    }
+    return produced;
+}
+exports.producerCorpusOf = producerCorpusOf;
 /**
  * The judge's turn on ONE landed result (9.104.0) — called at the five
  * places a result joins the batch (the execute loop and the four resume
@@ -740,6 +868,13 @@ function buildToolCallsHandler(deps) {
                     checked,
                     ...(notChecked.length > 0 && { notChecked }),
                     ...(cannotCover.length > 0 && { cannotCover }),
+                    // The suggestion, as declared (9.113.0): the sentence, and the
+                    // typed tool as a copy (`tryInsteadToolOfAbsence`). The EVENT only:
+                    // it is advice about a call not yet made, not ground the answer
+                    // stands on, so the tracked row below and the block composed from
+                    // it never carry it.
+                    ...(facts.tryInstead !== undefined && { tryInstead: facts.tryInstead }),
+                    ...(facts.tryInsteadTool !== undefined && { tryInsteadTool: facts.tryInsteadTool }),
                 });
             }
             else {
@@ -807,20 +942,9 @@ function buildToolCallsHandler(deps) {
             ledger?.note('empty-lookup', 'write', 'not-applicable');
             return;
         }
-        // The producer corpus: every earlier `role: 'tool'` message from a tool
-        // THIS tool declares as one of its grounds. `history` here excludes the
-        // call being judged (it is pushed after), and a producer called earlier
-        // in the same batch is already in it — which is right: the model can only
-        // have taken a value from a result it had already been served.
-        const produced = [];
-        for (const message of history) {
-            if (message.role !== 'tool')
-                continue;
-            const name = message.toolName;
-            if (typeof name !== 'string' || !argumentsFrom.includes(name))
-                continue;
-            produced.push({ toolName: name, text: message.content });
-        }
+        // The producer corpus: the earlier RESULTS from a tool THIS tool declares
+        // as one of its grounds — never a settled message (`producerCorpusOf`).
+        const produced = producerCorpusOf(history, argumentsFrom);
         const { findings, disposition } = (0, check_js_1.emptyLookupOf)({
             toolName: call.toolName,
             toolCallId: call.toolCallId,
@@ -2029,6 +2153,68 @@ function buildToolCallsHandler(deps) {
         (0, ledger_js_1.recordDecisions)(scope, verdict.decisions);
         return verdict.kind === 'deny' ? verdict.reason : verdict.result;
     };
+    const settleBatch = (answered, paused) => {
+        const batch = pausedBatchOf(answered, paused.toolCallId);
+        if (batch.undispatched.length === 0)
+            return { history: answered, settled: [], size: batch.size, paused };
+        const settled = batch.undispatched.map((call) => ({
+            call,
+            result: notDispatchedResult(call.name, paused),
+        }));
+        return {
+            history: [
+                ...answered,
+                ...settled.map(({ call, result }) => ({
+                    role: 'tool',
+                    content: result,
+                    toolCallId: call.id,
+                    toolName: call.name,
+                    notDispatched: notDispatchedMarker(paused),
+                })),
+            ],
+            settled,
+            size: batch.size,
+            paused,
+        };
+    };
+    /**
+     * Each settled sibling's bracket, after the paused call's own `tool_end` —
+     * the ONE site that stamps `notDispatched` on the stream: `tool_start` with
+     * the args the call would have run with (the batch loop's peel, so
+     * `_findings` never shows on a bracket), then `tool_end` carrying the
+     * sentence and `durationMs: 0`. Both carry the marker the history message
+     * carries (`notDispatchedMarker`), and no other bracket in the library ever
+     * does.
+     *
+     * No `error`. It says a call FAILED — the tool threw, or the call itself
+     * could not run as written (an args rejection, a `wants` block, a consent
+     * the tool needed and did not get, an unknown name). A settled call did not
+     * fail: the library decided not to dispatch it, as it does for a call a
+     * permission policy denies or halts, and those brackets carry no `error`
+     * either. Stamped here, it would register a tool failure in every
+     * error-rate reader (a span status, a dashboard, an alert) on every
+     * mid-batch pause, and say a second, false thing beside the marker, which
+     * is the one owner of why there is no result (`src/core/README.md` · "One
+     * owner of 'never dispatched' — in history and on the stream", the reader
+     * table). No `status` either: that field is the TOOL's own word.
+     */
+    const bracketSettled = (scope, settlement) => {
+        for (const { call, result } of settlement.settled) {
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.stream.tool_start', {
+                toolName: call.name,
+                toolCallId: call.id,
+                args: peelCall(call).args,
+                parallelCount: settlement.size,
+                notDispatched: notDispatchedMarker(settlement.paused),
+            });
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.stream.tool_end', {
+                toolCallId: call.id,
+                result,
+                durationMs: 0,
+                notDispatched: notDispatchedMarker(settlement.paused),
+            });
+        }
+    };
     // Resolve a tool's declared credential (declare-and-push) and execute it,
     // emitting the same credential.* events as the main loop. Used by the
     // check-in RESUME path when a human APPROVES — the tool never ran at pause
@@ -2354,15 +2540,24 @@ function buildToolCallsHandler(deps) {
             // came from (9.102.0; before, only the last batch resolved and an
             // offered older id filed as `unknownId`). Read through the same
             // per-call peel the loop below applies (a tool that owns the name
-            // declares nothing). Gated: unarmed, not one line runs.
+            // declares nothing). A ruled-out standing whose result THIS door
+            // recorded as an absence (`declareCoverage`'s rows on
+            // `coverageDeclared`, never a second reading of a return) AND the
+            // model was served as one (the served string — the door records the
+            // return before the after-tool chain, the ceiling and placement act,
+            // so a denied, refused or ticketed result files nothing) gets its
+            // `unsettled-by-absence` row immediately after it, in the same write,
+            // worded from what was served (9.113.0, `findings/unsettled.ts`; the
+            // key is read only for such a standing); the standing rows pass
+            // through untouched. Gated: unarmed, not one line runs.
             if (deps.findings === true) {
                 const known = (0, offer_js_1.knownResults)([...(scope.history ?? [])], [...(scope.toolResults ?? [])]);
-                (0, ledger_js_2.recordFindings)(scope, toolCalls.flatMap((tc) => {
+                (0, ledger_js_2.recordFindings)(scope, (0, unsettled_js_1.withUnsettledRows)(toolCalls.flatMap((tc) => {
                     const declared = peelCall(tc).findings;
                     return declared?.previous !== undefined
                         ? (0, ledger_js_2.standingRowsFrom)(known, declared, { toolCallId: tc.id }, iteration)
                         : [];
-                }));
+                }), known, () => [...(scope.coverageDeclared ?? [])]));
             }
             scope.toolResults = [];
             // ── THE TOWERS AT DISPATCH (9.110.0) — one corpus per batch ────────
@@ -3934,10 +4129,13 @@ function buildToolCallsHandler(deps) {
                     askResultStr += applyToolEffects(scope, { toolName, toolCallId, iteration }, resumeEnvelope, askTransition);
                     emitTransitionConflict(scope, iteration, askTransition);
                 }
-                const askHistory = [
+                // The batch settlement (9.113.0): the answered call's result, then the
+                // siblings the pause left un-dispatched, each settled — never run.
+                const askSettlement = settleBatch([
                     ...scope.history,
                     { role: 'tool', content: askResultStr, toolCallId, toolName },
-                ];
+                ], { toolName, toolCallId });
+                const askHistory = askSettlement.history;
                 scope.history = askHistory;
                 scope.lastToolResult = {
                     toolName,
@@ -3958,10 +4156,14 @@ function buildToolCallsHandler(deps) {
                     ...(error === true && { error: true }),
                     ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
                 });
+                bracketSettled(scope, askSettlement);
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
                     iterIndex: iteration,
-                    toolCallCount: 1,
+                    // The brackets THIS leg closed: the answered call's, plus one per
+                    // settled sibling. The calls before the paused one closed theirs on
+                    // the leg that paused, which ended in a checkpoint, not here.
+                    toolCallCount: 1 + askSettlement.settled.length,
                     history: askHistory,
                 });
                 scope.iteration = iteration + 1;
@@ -4078,10 +4280,12 @@ function buildToolCallsHandler(deps) {
                     decisionResultStr += applyToolEffects(scope, { toolName, toolCallId, iteration }, resumeEnvelope, decisionTransition);
                     emitTransitionConflict(scope, iteration, decisionTransition);
                 }
-                const decisionHistory = [
+                // The batch settlement (9.113.0) — the ask path's twin.
+                const decisionSettlement = settleBatch([
                     ...scope.history,
                     { role: 'tool', content: decisionResultStr, toolCallId, toolName },
-                ];
+                ], { toolName, toolCallId });
+                const decisionHistory = decisionSettlement.history;
                 scope.history = decisionHistory;
                 // Drives `on-tool-return` triggers, same as the execute path.
                 scope.lastToolResult = {
@@ -4103,10 +4307,12 @@ function buildToolCallsHandler(deps) {
                     ...(error === true && { error: true }),
                     ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
                 });
+                bracketSettled(scope, decisionSettlement);
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
                     iterIndex: iteration,
-                    toolCallCount: 1,
+                    // The brackets this leg closed — see the ask path's twin.
+                    toolCallCount: 1 + decisionSettlement.settled.length,
                     history: decisionHistory,
                 });
                 scope.iteration = iteration + 1;
@@ -4188,10 +4394,12 @@ function buildToolCallsHandler(deps) {
                     consentResultStr += applyToolEffects(scope, { toolName, toolCallId, iteration }, consentEnvelope, consentTransition);
                     emitTransitionConflict(scope, iteration, consentTransition);
                 }
-                const consentHistory = [
+                // The batch settlement (9.113.0) — the ask path's twin.
+                const consentSettlement = settleBatch([
                     ...scope.history,
                     { role: 'tool', content: consentResultStr, toolCallId, toolName },
-                ];
+                ], { toolName, toolCallId });
+                const consentHistory = consentSettlement.history;
                 scope.history = consentHistory;
                 scope.lastToolResult = {
                     toolName,
@@ -4212,10 +4420,12 @@ function buildToolCallsHandler(deps) {
                     ...(error === true && { error: true }),
                     ...(consentEnvelope?.status !== undefined && { status: consentEnvelope.status }),
                 });
+                bracketSettled(scope, consentSettlement);
                 (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
                     iterIndex: iteration,
-                    toolCallCount: 1,
+                    // The brackets this leg closed — see the ask path's twin.
+                    toolCallCount: 1 + consentSettlement.settled.length,
                     history: consentHistory,
                 });
                 scope.iteration = iteration + 1;
@@ -4293,7 +4503,10 @@ function buildToolCallsHandler(deps) {
             if (deps.stepPlanFor) {
                 resultStr += applyStepReturn(scope, { toolName, toolCallId, iteration });
             }
-            const newHistory = [
+            // The batch settlement (9.113.0) — the door a `requestInput` answer
+            // comes back through, and the one most likely to meet a batch: a tool
+            // that asks a person mid-lookup, batched with the lookups after it.
+            const pauseSettlement = settleBatch([
                 ...scope.history,
                 {
                     role: 'tool',
@@ -4301,7 +4514,8 @@ function buildToolCallsHandler(deps) {
                     toolCallId,
                     toolName,
                 },
-            ];
+            ], { toolName, toolCallId });
+            const newHistory = pauseSettlement.history;
             scope.history = newHistory;
             // Drives `on-tool-return` triggers, same as every other dispatch path.
             scope.lastToolResult = { toolName, result: resultStr };
@@ -4317,10 +4531,12 @@ function buildToolCallsHandler(deps) {
                 result: pauseCapped.result,
                 durationMs: Date.now() - startMs,
             });
+            bracketSettled(scope, pauseSettlement);
             (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
                 turnIndex: 0,
                 iterIndex: iteration,
-                toolCallCount: 1,
+                // The brackets this leg closed — see the ask path's twin.
+                toolCallCount: 1 + pauseSettlement.settled.length,
                 // Plain local array — see the matching note on the execute path.
                 history: newHistory,
             });