agentfootprint 13.0.0 → 14.0.0

package/dist/esm/core/agent/stages/toolCalls/batch/inputResolutions.d.ts

@@ -0,0 +1,6 @@
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../../../types.js';
+import type { InputsDispatch } from '../contracts/inputsDispatch.js';
+import type { DispatchCall } from '../contracts/batchCall.js';
+/** Read this iteration's fills and consume only the already-used kept answers. */
+export declare function readBatchResolutions(scope: TypedScope<AgentState>, inputs: InputsDispatch | undefined, iteration: number, toolCalls: readonly Pick<DispatchCall, 'id' | 'name'>[], findingsRefusals: readonly unknown[]): ReadonlyMap<string, import("../../../arguments/resolve.js").ArgumentResolution> | undefined;

package/dist/esm/core/agent/stages/toolCalls/batch/inputResolutions.js

@@ -0,0 +1,18 @@
+/** Read this iteration's fills and consume only the already-used kept answers. */
+export function readBatchResolutions(scope, inputs, iteration, toolCalls, findingsRefusals) {
+    // THE INPUTS LAYER'S RESOLUTIONS for this batch — read only under the
+    // arm, and only the entries resolved for THIS iteration.
+    let resolutions = inputs?.resolutionsFor(scope, iteration);
+    if (resolutions !== undefined && findingsRefusals.some((item) => item !== undefined)) {
+        const refusedIds = new Set(toolCalls.filter((_, index) => findingsRefusals[index] !== undefined).map((tc) => tc.id));
+        resolutions = new Map([...resolutions].filter(([id]) => !refusedIds.has(id)));
+    }
+    // A fill the layer took from an answer this turn KEPT (a call of the
+    // batch that asked could not finish) is that answer's one use — dropped
+    // before anything else (`arguments/dispatch.ts` · `dropUsedKept`).
+    if (inputs !== undefined && resolutions !== undefined) {
+        inputs.dropUsedKept(scope, resolutions, toolCalls);
+    }
+    return resolutions;
+}
+//# sourceMappingURL=inputResolutions.js.map

package/dist/esm/core/agent/stages/toolCalls/batch/inputResolutions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputResolutions.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/batch/inputResolutions.ts"],"names":[],"mappings":"AAKA,kFAAkF;AAClF,MAAM,UAAU,oBAAoB,CAClC,KAA6B,EAC7B,MAAkC,EAClC,SAAiB,EACjB,SAAuD,EACvD,gBAAoC;IAEpC,sEAAsE;IACtE,yDAAyD;IACzD,IAAI,WAAW,GAAG,MAAM,EAAE,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC3D,IAAI,WAAW,KAAK,SAAS,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,EAAE,CAAC;QACrF,MAAM,UAAU,GAAG,IAAI,GAAG,CACxB,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CACzF,CAAC;QACF,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IACD,qEAAqE;IACrE,wEAAwE;IACxE,mEAAmE;IACnE,IAAI,MAAM,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QACtD,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/esm/core/agent/stages/toolCalls/batch/paused.d.ts

@@ -0,0 +1,65 @@
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../../../types.js';
+import type { LLMMessage } from '../../../../../provider-contract/types.js';
+/**
+ * The args a `pauseHere` / `askHuman` call was running with, read back on the
+ * far side of the pause (8.13.0).
+ *
+ * Normally `scope.pausedToolArgs`: written at pause time from `callArgs`, so it
+ * is the post-transform args `ToolResultContext.args` promises.
+ *
+ * A checkpoint written BEFORE 8.13.0 does not carry the field — a real case
+ * during a rolling deploy. Those args are recovered from the assistant turn in
+ * `history` by `toolCallId`: real values the model proposed, identical to the
+ * running args unless a before-tool middleware transformed them, and that one
+ * difference is not recoverable from a checkpoint that never recorded it.
+ *
+ * `{}` is the last resort and only when the turn is gone (a window strategy
+ * folded it away). It is returned rather than skipping the after-tool moment,
+ * because a rule that never runs is the bug this release is fixing — but it is
+ * genuinely "we do not know", never a claim that the tool ran with none.
+ *
+ * `peel` (9.101.0, `.findings()`): the history fallback recovers the
+ * EMISSION — `toolCalls[].args` keep the reserved `_findings` argument by
+ * design — so under the arm it is peeled here exactly as the dispatch loop
+ * peeled it; `pausedToolArgs` was set from `callArgs` and is already peeled.
+ */
+export declare function argsForPausedCall(scope: TypedScope<AgentState>, toolCallId: string, peel?: boolean): Readonly<Record<string, unknown>>;
+/** One call the model proposed on an assistant turn (`LLMMessage.toolCalls`). */
+export type ProposedCall = NonNullable<LLMMessage['toolCalls']>[number];
+/**
+ * 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.
+ */
+export declare function pausedBatchOf(history: readonly LLMMessage[], pausedToolCallId: string): {
+    readonly size: number;
+    readonly undispatched: readonly ProposedCall[];
+};

package/dist/esm/core/agent/stages/toolCalls/batch/paused.js

@@ -0,0 +1,88 @@
+import { splitFindings } from '../../../findings/reserved.js';
+/**
+ * The args a `pauseHere` / `askHuman` call was running with, read back on the
+ * far side of the pause (8.13.0).
+ *
+ * Normally `scope.pausedToolArgs`: written at pause time from `callArgs`, so it
+ * is the post-transform args `ToolResultContext.args` promises.
+ *
+ * A checkpoint written BEFORE 8.13.0 does not carry the field — a real case
+ * during a rolling deploy. Those args are recovered from the assistant turn in
+ * `history` by `toolCallId`: real values the model proposed, identical to the
+ * running args unless a before-tool middleware transformed them, and that one
+ * difference is not recoverable from a checkpoint that never recorded it.
+ *
+ * `{}` is the last resort and only when the turn is gone (a window strategy
+ * folded it away). It is returned rather than skipping the after-tool moment,
+ * because a rule that never runs is the bug this release is fixing — but it is
+ * genuinely "we do not know", never a claim that the tool ran with none.
+ *
+ * `peel` (9.101.0, `.findings()`): the history fallback recovers the
+ * EMISSION — `toolCalls[].args` keep the reserved `_findings` argument by
+ * design — so under the arm it is peeled here exactly as the dispatch loop
+ * peeled it; `pausedToolArgs` was set from `callArgs` and is already peeled.
+ */
+export function argsForPausedCall(scope, toolCallId, peel = false) {
+    const carried = scope.pausedToolArgs;
+    if (carried !== undefined)
+        return { ...carried };
+    for (const message of scope.history) {
+        for (const call of message.toolCalls ?? []) {
+            if (call.id === toolCallId) {
+                const recovered = { ...call.args };
+                return peel ? splitFindings(recovered).args : recovered;
+            }
+        }
+    }
+    return {};
+}
+/**
+ * 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.
+ */
+export 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: [] };
+}
+//# sourceMappingURL=paused.js.map

package/dist/esm/core/agent/stages/toolCalls/batch/paused.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paused.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/batch/paused.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAK9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA6B,EAC7B,UAAkB,EAClB,IAAI,GAAG,KAAK;IAEZ,MAAM,OAAO,GAAG,KAAK,CAAC,cAA+D,CAAC;IACtF,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IACjD,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,OAAgC,EAAE,CAAC;QAC7D,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;YAC3C,IAAI,IAAI,CAAC,EAAE,KAAK,UAAU,EAAE,CAAC;gBAC3B,MAAM,SAAS,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;gBACnC,OAAO,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,aAAa,CAC3B,OAA8B,EAC9B,gBAAwB;IAExB,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,OAAO,EAAE,IAAI,KAAK,WAAW;YAAE,SAAS;QAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,gBAAgB,CAAC,CAAC;QACtE,IAAI,EAAE,GAAG,CAAC;YAAE,SAAS;QACrB,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAC/E,CAAC;QACF,OAAO;YACL,IAAI,EAAE,QAAQ,CAAC,MAAM;YACrB,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SAC9E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;AACvC,CAAC"}

package/dist/esm/core/agent/stages/toolCalls/batch/refusal.d.ts

@@ -0,0 +1,5 @@
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../../../types.js';
+import type { ToolBatchFailure } from '../../toolCallShape.js';
+/** Malformed protocol IDs cannot acquire fabricated tool-result correlations. */
+export declare function refuseToolBatch(scope: TypedScope<AgentState>, reason: ToolBatchFailure): void;

package/dist/esm/core/agent/stages/toolCalls/batch/refusal.js

@@ -0,0 +1,32 @@
+import { TOOL_BATCH_FRAME_PREFIX } from '../../../../../lib/saidByPerson.js';
+import { typedEmit } from '../../../../../recorders/core/typedEmit.js';
+/** Malformed protocol IDs cannot acquire fabricated tool-result correlations. */
+export function refuseToolBatch(scope, reason) {
+    const iteration = scope.iteration;
+    const history = [...scope.history];
+    const text = scope.llmLatestContent;
+    // A blank model response supplies no assistant wire turn. Keep the fixed
+    // framework notice explicit, so Bedrock never receives adjacent user turns.
+    history.push({
+        role: 'assistant',
+        content: text ||
+            `${TOOL_BATCH_FRAME_PREFIX} — framework notice: the proposed calls could not be dispatched.]`,
+    });
+    history.push({
+        role: 'user',
+        content: `${TOOL_BATCH_FRAME_PREFIX} — framework feedback, not a person's words or evidence. ` +
+            `The entire proposed batch was refused before dispatch (${reason}); no tools ran. ` +
+            'Submit at most 1024 calls with nonempty unique IDs and nonempty tool names, each at most 1024 characters.]',
+    });
+    scope.history = history;
+    scope.toolResults = [];
+    scope.lastToolResult = undefined;
+    typedEmit(scope, 'agentfootprint.agent.iteration_end', {
+        turnIndex: 0,
+        iterIndex: iteration,
+        toolCallCount: 0,
+        history,
+    });
+    scope.iteration = iteration + 1;
+}
+//# sourceMappingURL=refusal.js.map

package/dist/esm/core/agent/stages/toolCalls/batch/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/batch/refusal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAC;AAGvE,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,KAA6B,EAAE,MAAwB;IACrF,MAAM,SAAS,GAAG,KAAK,CAAC,SAAmB,CAAC;IAC5C,MAAM,OAAO,GAAiB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,KAAK,CAAC,gBAAgB,CAAC;IACpC,yEAAyE;IACzE,4EAA4E;IAC5E,OAAO,CAAC,IAAI,CAAC;QACX,IAAI,EAAE,WAAW;QACjB,OAAO,EACL,IAAI;YACJ,GAAG,uBAAuB,mEAAmE;KAChG,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CAAC;QACX,IAAI,EAAE,MAAM;QACZ,OAAO,EACL,GAAG,uBAAuB,2DAA2D;YACrF,0DAA0D,MAAM,mBAAmB;YACnF,4GAA4G;KAC/G,CAAC,CAAC;IACH,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,KAAK,CAAC,WAAW,GAAG,EAAE,CAAC;IACvB,KAAK,CAAC,cAAc,GAAG,SAAS,CAAC;IACjC,SAAS,CAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;QAChB,OAAO;KACR,CAAC,CAAC;IACH,KAAK,CAAC,SAAS,GAAG,SAAS,GAAG,CAAC,CAAC;AAClC,CAAC"}

package/dist/esm/core/agent/stages/toolCalls/batch/settle.d.ts

@@ -0,0 +1,66 @@
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../../../types.js';
+import type { ToolResultStatus } from '../../../../../semantics/toolEffects.js';
+import type { LLMMessage } from '../../../../../provider-contract/types.js';
+/**
+ * Build the pausable tool-call handler for the agent's chart.
+ */
+/**
+ * Append one landed result to the iteration's tool-result batch (9.16.0).
+ *
+ * The execute path resets `scope.toolResults` before its dispatch loop and
+ * appends per call; the four RESUME paths go through here instead — the
+ * paused iteration's partial batch (every sibling that ran before the pause)
+ * is already committed on scope, and the answered call joins it in call
+ * order rather than erasing it. Spread first: a TypedScope array read is a
+ * live proxy view, and the batch must stay plain data.
+ */
+export declare function appendBatchResult(scope: TypedScope<AgentState>, entry: {
+    toolName: string;
+    result: string;
+    toolCallId: string;
+    status?: ToolResultStatus;
+}): void;
+/**
+ * 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`).
+ */
+export declare function notDispatchedResult(toolName: string, paused: {
+    readonly toolName: string;
+    readonly toolCallId: string;
+}): string;
+/**
+ * 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.
+ */
+export declare function notDispatchedMarker(paused: {
+    readonly toolName: string;
+    readonly toolCallId: string;
+}): NonNullable<LLMMessage['notDispatched']>;

package/dist/esm/core/agent/stages/toolCalls/batch/settle.js

@@ -0,0 +1,63 @@
+/**
+ * Build the pausable tool-call handler for the agent's chart.
+ */
+/**
+ * Append one landed result to the iteration's tool-result batch (9.16.0).
+ *
+ * The execute path resets `scope.toolResults` before its dispatch loop and
+ * appends per call; the four RESUME paths go through here instead — the
+ * paused iteration's partial batch (every sibling that ran before the pause)
+ * is already committed on scope, and the answered call joins it in call
+ * order rather than erasing it. Spread first: a TypedScope array read is a
+ * live proxy view, and the batch must stay plain data.
+ */
+export function appendBatchResult(scope, entry) {
+    scope.toolResults = [...(scope.toolResults ?? []), entry];
+}
+// 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`).
+ */
+export 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.`);
+}
+/**
+ * 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.
+ */
+export function notDispatchedMarker(paused) {
+    return { pausedCall: { toolCallId: paused.toolCallId, toolName: paused.toolName } };
+}
+//# sourceMappingURL=settle.js.map

package/dist/esm/core/agent/stages/toolCalls/batch/settle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/batch/settle.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA6B,EAC7B,KAA0F;IAE1F,KAAK,CAAC,WAAW,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,0CAA0C;AAC1C,uKAAuK;AACvK,yGAAyG;AACzG;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,MAAkE;IAElE,OAAO,CACL,SAAS,QAAQ,0DAA0D;QAC3E,IAAI,MAAM,CAAC,UAAU,SAAS,MAAM,CAAC,QAAQ,4CAA4C;QACzF,6DAA6D,CAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAGnC;IACC,OAAO,EAAE,UAAU,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;AACtF,CAAC"}

package/dist/esm/core/agent/stages/toolCalls/batch/settlementOperations.d.ts

@@ -0,0 +1,17 @@
+import type { buildToolResolver } from '../../toolResolver.js';
+import type { ToolCallsHandlerDeps } from '../contracts/handlerDeps.js';
+import type { ToolSettlementOperations } from '../contracts/operations/settlement.js';
+import type { ToolScriptsOperations } from '../contracts/operations/scripts.js';
+import type { ToolCatalogOperations } from '../contracts/operations/catalog.js';
+import type { ToolObservationsOperations } from '../contracts/operations/observations.js';
+interface ToolSettlementOperationsLinks {
+    readonly fileScript: ToolScriptsOperations['fileScript'];
+    readonly resolveTool: ReturnType<typeof buildToolResolver>;
+    readonly programOfCall: ToolScriptsOperations['programOfCall'];
+    readonly peelCall: ToolCatalogOperations['peelCall'];
+    readonly emitToolStart: ToolObservationsOperations['emitToolStart'];
+    readonly emitToolEnd: ToolObservationsOperations['emitToolEnd'];
+}
+/** Compose the existing settlement callbacks once for this handler. */
+export declare function buildToolSettlementOperations(deps: Pick<ToolCallsHandlerDeps, 'scriptRecord'>, links: ToolSettlementOperationsLinks): ToolSettlementOperations;
+export {};

package/dist/esm/core/agent/stages/toolCalls/batch/settlementOperations.js

@@ -0,0 +1,103 @@
+import { joinSystemPrompt } from '../../../composeRequest.js';
+import { pausedBatchOf } from './paused.js';
+import { notDispatchedResult, notDispatchedMarker } from './settle.js';
+/** Compose the existing settlement callbacks once for this handler. */
+export function buildToolSettlementOperations(deps, links) {
+    /**
+     * The conversation the check-in gate judges — the run history with a synthetic
+     * `system` frame in front of it.
+     *
+     * The system prompt is not in `scope.history` (the slots assemble it
+     * separately), so without this the evidence's `read` and the `drivers` ranking
+     * could cite the conversation but never a system RULE, and a `CheckInDemand`
+     * predicate reading `ctx.history` would be judging a different conversation
+     * than the one the run actually had.
+     *
+     * Hoisted to the handler closure because BOTH gate sites need the SAME shape:
+     * the loop's gate (which decides whether to pause) and the ask-resume gate
+     * (which decides whether that pause was owed). A predicate that answered
+     * differently on the two sides would make the refusal depend on which door the
+     * call came through, and that is not a property of the tool.
+     */
+    const historyForCheckIn = (scope, history) => {
+        const systemPrompt = joinSystemPrompt(scope.systemPromptInjections ?? []);
+        return systemPrompt ? [{ role: 'system', content: systemPrompt }, ...history] : [...history];
+    };
+    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) {
+            // Never dispatched: the program is on the record as proposed, `submitted`.
+            // Guarded here — the arguments read the scope, and an unarmed agent reads
+            // nothing new.
+            if (deps.scriptRecord === true) {
+                links.fileScript(scope, {
+                    tool: links.resolveTool(call.name).tool,
+                    toolName: call.name,
+                    toolCallId: call.id,
+                    iteration: scope.iteration,
+                    proposed: links.programOfCall(links.resolveTool(call.name).tool, links.peelCall(call).args),
+                    settlement: 'not-entered',
+                });
+            }
+            links.emitToolStart(scope, {
+                toolName: call.name,
+                toolCallId: call.id,
+                args: links.peelCall(call).args,
+                parallelCount: settlement.size,
+                notDispatched: notDispatchedMarker(settlement.paused),
+            });
+            links.emitToolEnd(scope, call.name, {
+                toolCallId: call.id,
+                result,
+                durationMs: 0,
+                notDispatched: notDispatchedMarker(settlement.paused),
+            }, false);
+        }
+    };
+    return { historyForCheckIn, settleBatch, bracketSettled };
+}
+//# sourceMappingURL=settlementOperations.js.map

package/dist/esm/core/agent/stages/toolCalls/batch/settlementOperations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlementOperations.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/batch/settlementOperations.ts"],"names":[],"mappings":"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"}