agentfootprint 13.0.0 → 14.0.0

package/dist/esm/core/agent/stages/toolCalls/contracts/access.d.ts

@@ -0,0 +1,110 @@
+import type { PermissionChecker } from '../../../../../provider-contract/types.js';
+import type { CredentialProvider } from '../../../../../identity/types.js';
+import type { RequestContext } from '../../../../../identity/requestContext.js';
+import type { ToolArgValidationMode } from '../../../../../tools/toolArgsValidation.js';
+import type { ResolvedCheckInConfig } from '../../../../checkin.js';
+import type { ToolMiddleware } from '../../../middleware/types.js';
+import type { AnsweredAsk } from '../../../../../tools/inputRequest.js';
+import type { DecisionLedger } from '../../../../consentRequest.js';
+import type { AuthorizationRequiredMode } from '../../../../../identity/consent.js';
+/** The access dependencies of the existing tool-call stage. */
+export interface ToolAccessPort {
+    /** Optional permission gate. When present, every tool dispatch
+     *  awaits `check({capability: 'tool_call', ...})` BEFORE executing.
+     *  Throwing checkers are treated as deny-by-default. */
+    readonly permissionChecker?: PermissionChecker;
+    /** Optional credential provider (declare-and-push). When present, a tool's
+     *  declared `needs` is resolved BEFORE execute and injected as `ctx.credential`;
+     *  `ctx.credentials` exposes it for the pull escape hatch. */
+    readonly credentialProvider?: CredentialProvider;
+    /**
+     * The incoming request a call made in `scope` serves — the agent's own run's
+     * for its own scopes, the run a composition's link names on a mount, and
+     * `undefined` where no run carries one. Every credential call made in that
+     * scope (declared `needs`, the pull path, inner `ctx.tools` calls) carries
+     * it as `CredentialRequest.request` and nothing else (`bindRequest`), so a
+     * request-sourced credential can never serve another run. Absent → no call
+     * carries a request.
+     */
+    readonly currentRequest?: (scope: object) => RequestContext | undefined;
+    /** Tool-args validation mode (#9). Default 'enforce': LLM-produced args
+     *  are checked against the tool's `inputSchema` BEFORE dispatch; a
+     *  mismatch rejects the call with a model-visible retry message.
+     *  'warn' emits the event but executes anyway; 'off' skips validation. */
+    readonly toolArgValidation?: ToolArgValidationMode;
+    /**
+     * Check-in config (evidence-carrying human consent). Resolved from the Agent
+     * builder (`.checkIn({...})`) — defaults to `standard` evidence + the
+     * deterministic lexical scorer, so a tool that declares `checkIn` works even
+     * without `.checkIn()`. Undefined only when the handler is built outside an
+     * Agent (no check-in). The gate fires ONLY for tools that declared `checkIn`.
+     */
+    readonly checkIn?: ResolvedCheckInConfig;
+    /**
+     * The tool-dispatch governance chain (`.toolMiddleware(...)`), in
+     * declaration order. Walked AFTER the permission gate — so an existing
+     * `PermissionChecker` still decides first and a denial there means no
+     * middleware runs at all — and BEFORE arg validation, so validation judges
+     * the args that will actually be sent rather than the ones the model
+     * proposed. Empty / undefined → not walked, no ledger key, no events.
+     */
+    readonly toolMiddleware?: readonly ToolMiddleware[];
+    /**
+     * The typed ask this run's resume answered, or `undefined` — for
+     * a fresh run, and for a resume of any other pause kind. An accessor for
+     * the reason `currentRun` is one. Read at a `requestInput` raise: the same
+     * declaration `id` raised again is a RE-ASK, stamped `repeat` on the
+     * awaiting-input shape (`inputRequest.ts` · `repeatOf`).
+     *
+     * @internal
+     */
+    readonly answeredAsk?: () => AnsweredAsk | undefined;
+    /**
+     * Where answered consent requests are spent (`AgentOptions.decisionLedger`),
+     * so one decision runs one call. Undefined → this process's ledger, shared by
+     * every agent that names none (`processDecisionLedger`).
+     */
+    readonly decisionLedger?: DecisionLedger;
+    /**
+     * What to do when a tool's DECLARED credential needs 3LO consent (8.6.0).
+     * Default `'pause'`. See `AgentOptions.onAuthorizationRequired`.
+     */
+    readonly onAuthorizationRequired?: AuthorizationRequiredMode;
+    /**
+     * Side channel for the `'tell-model'` consent record — the ONLY route the
+     * authorization URL takes out of this handler in that mode.
+     *
+     * It is a callback rather than a scope key on purpose. A tracked write lands
+     * in the commit log, which is the snapshot, the narrative and every
+     * recording; writing the URL there would rebuild the exact leak 8.6.0
+     * removes. This hands it to a private field on the Agent instead, where it
+     * lives for the length of the run and leaves only as
+     * `CredentialConsentRequiredError`.
+     *
+     * @internal
+     */
+    readonly reportConsentOutstanding?: (record: {
+        readonly service: string;
+        readonly authorizationUrl: string;
+        readonly sessionId: string;
+        readonly tool: string;
+        readonly iteration: number;
+    }) => void;
+    /**
+     * Clears an outstanding consent record for `service` — called whenever a
+     * credential for it is successfully ISSUED. Without this, a run that was
+     * blocked, resumed, and then succeeded would still raise at the end: the
+     * record is about work that has since been done.
+     *
+     * @internal
+     */
+    readonly clearConsentOutstanding?: (service: string) => void;
+    /**
+     * The host's own context for the inputs layer's batch ask
+     * (`AgentOptions.argumentAskContext`) — called when an ask is built, its
+     * object spread into the ask's `context` beside the library's reserved key
+     * (`arguments/ask.ts` · `judgeAskContextHook`). Present only when the agent
+     * configured one; read only when an ask is raised.
+     */
+    readonly argumentAskContext?: () => unknown;
+}

package/dist/esm/core/agent/stages/toolCalls/contracts/access.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=access.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/access.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/artifacts.d.ts

@@ -0,0 +1,26 @@
+import type { ArtifactStore } from '../../../../../artifacts/types.js';
+import type { ArtifactPlacement } from '../../../../../artifacts/placement.js';
+/** The artifacts dependencies of the existing tool-call stage. */
+export interface ToolArtifactsPort {
+    /**
+     * The claim-check store (9.21.0). When present, every dispatch binds it to
+     * the run's scope (`scope.runIdentity` — the tuple memory scopes on) as
+     * `ctx.artifacts`, with `origin` stamped from the run's own facts and every
+     * mint/resolve/sweep/refusal emitted as `agentfootprint.artifacts.*`.
+     * Undefined — the default — and `ctx.artifacts` is the fail-closed teacher:
+     * byte-identical behavior and events (zero-cost-when-unused).
+     */
+    readonly artifactStore?: ArtifactStore;
+    /**
+     * The placement threshold (9.22.0) — the operator's ref-ing dial. When set
+     * (only ever beside `artifactStore`; the Agent option's shape enforces it),
+     * every finalized tool result on every dispatch path is measured, and one
+     * whose text exceeds `maxInlineChars` is checked into the store (under the
+     * tool's declared `resultKind`, or `tool-result/<toolName>` when it
+     * declares none) with the model reading the claim ticket
+     * instead. Judged AFTER the tool's own `resultCeiling` and the after-tool
+     * chain, BEFORE the `maxToolResultChars` truncation net. Undefined — the
+     * default — and results are never measured against it (zero-cost).
+     */
+    readonly placement?: ArtifactPlacement;
+}

package/dist/esm/core/agent/stages/toolCalls/contracts/artifacts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=artifacts.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/artifacts.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/batchCall.d.ts

@@ -0,0 +1,8 @@
+import type { LLMMessage } from '../../../../../provider-contract/types.js';
+/** The existing materialized tool proposal, passed between synchronous batch operations. */
+export interface DispatchCall {
+    readonly id: string;
+    readonly name: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly argumentsFailure?: LLMMessage['toolArgumentsFailure'];
+}

package/dist/esm/core/agent/stages/toolCalls/contracts/batchCall.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=batchCall.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/batchCall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batchCall.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/batchCall.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/callCells.d.ts

@@ -0,0 +1,43 @@
+import type { ReadToolResultEnvelope, ToolResultStatus } from '../../../../../semantics/toolEffects.js';
+import type { ToolArgs } from '../../../../../tools/runChain.js';
+import type { CodeRunFacts } from '../../../../codeRunnerTool.js';
+import type { NegativeDispatch } from '../../../negativeClaims/capture.js';
+/** Invocation-local phase cells; never checkpoint state or a run registry. */
+export interface CallResultCell {
+    result: unknown;
+    error: boolean | undefined;
+    toolEnvelope: ReadToolResultEnvelope | undefined;
+    toolStatus: ToolResultStatus | undefined;
+}
+export interface CallArguments {
+    callArgs: ToolArgs;
+    chainedArgs: ToolArgs;
+}
+export interface CallExecution {
+    denied: boolean;
+    executed: boolean;
+    submittedProgram: unknown;
+    executeThrew: boolean;
+    ranCode: CodeRunFacts | undefined;
+    withheldOverCeiling: boolean;
+    negativeDispatch: NegativeDispatch | undefined;
+    ceilingRefused: boolean;
+    haltContext: {
+        reason: string;
+        tellLLM: string;
+        checkerId?: string;
+    } | undefined;
+}
+export interface CallArgumentGate {
+    argsRejected: boolean;
+}
+export interface CallConsentGate {
+    checkInRefused: boolean;
+}
+export interface CallSkillRoute {
+    skillRejected: boolean;
+    skillHop: boolean;
+}
+export interface CallDelivery {
+    resultStr: string;
+}

package/dist/esm/core/agent/stages/toolCalls/contracts/callCells.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=callCells.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/callCells.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callCells.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/callCells.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/callFacts.d.ts

@@ -0,0 +1,50 @@
+import type { CodeRunFacts } from '../../../../codeRunnerTool.js';
+import type { PendingToolTransition } from '../../../../../injection-engine/leases.js';
+import type { LLMMessage } from '../../../../../provider-contract/types.js';
+import type { ProposedCall } from '../batch/paused.js';
+import type { ToolResolution } from '../../toolResolver.js';
+/** What a resumed call's `execute` saw — read by its script row (`deps.scriptRecord`). */
+export interface ResumedCallFacts {
+    /** Set once `execute` was about to be handed the call (the program values below were read then). */
+    entered?: true;
+    /** The declared argument's value as the model proposed it — read before `execute`. */
+    proposed?: unknown;
+    /** The declared argument's value handed to `execute` — read just before it ran. */
+    submitted?: unknown;
+    /** The runner's facts, when the tool filed them. */
+    codeRun?: CodeRunFacts;
+    /** The tool's own `resultCeiling` refused the result. */
+    overCeiling?: true;
+    /** `execute` was entered and threw. */
+    threw?: true;
+}
+/** The batch's transition bookkeeping: first ACCEPTED proposal wins the
+ *  one `pendingToolTransition` slot (committed at acceptance, so a pause
+ *  mid-batch never drops an accepted move); later proposals to OTHER
+ *  targets are suppressed + collected for the batch-end `route_conflict`
+ *  aggregate. */
+export interface TransitionBatchState {
+    winner?: PendingToolTransition;
+    losers: Array<{
+        toolCallId?: string;
+        toolName: string;
+        target: string;
+    }>;
+}
+export interface BatchSettlement {
+    /** What the resume leg commits and reports on `iteration_end`. */
+    readonly history: LLMMessage[];
+    /** The settled siblings, in call order, each with the sentence it got. */
+    readonly settled: readonly {
+        readonly call: ProposedCall;
+        readonly result: string;
+    }[];
+    /** How many calls the paused turn proposed — the batch loop's `parallelCount`. */
+    readonly size: number;
+    /** The call the run paused on — what every marker of this settlement names. */
+    readonly paused: {
+        readonly toolName: string;
+        readonly toolCallId: string;
+    };
+}
+export type Resolution = ToolResolution;

package/dist/esm/core/agent/stages/toolCalls/contracts/callFacts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=callFacts.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/callFacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callFacts.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/callFacts.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/catalog.d.ts

@@ -0,0 +1,56 @@
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../../../types.js';
+import type { Tool } from '../../../../../tools/tools.js';
+import type { ToolProvider } from '../../../../../tools/toolProvider.js';
+import type { ProviderToolCache, ServedToolParties } from '../../../../slots/buildToolsSlot.js';
+import type { ToolClaim } from '../../../buildToolRegistry.js';
+/** The catalog dependencies of the existing tool-call stage. */
+export interface ToolCatalogPort {
+    /** Current executable catalog for both pausable resume and interrupt replay. */
+    readonly prepareProviderTools?: (scope: TypedScope<AgentState>) => Promise<void> | undefined;
+    /** Map from tool name → Tool instance, built from the augmented
+     *  registry (static .tool() entries + read_skill if any skills +
+     *  shared skill tools). The dispatch primary lookup. */
+    readonly registryByName: ReadonlyMap<string, Tool>;
+    /** Optional external `.toolProvider()` for per-iteration dynamic
+     *  tools (skill-scoped, multi-tenant, etc.). Consulted only when
+     *  the static registry doesn't have the tool. */
+    readonly externalToolProvider?: ToolProvider;
+    /**
+     * Cache populated by `buildToolsSlot` after each `provider.list(ctx)`
+     * call this iteration. Read here to avoid a second `list()` call
+     * (vital for async / network-backed providers). Same closure shared
+     * within one chart build.
+     */
+    readonly providerToolCache?: ProviderToolCache;
+    /**
+     * Who put each name on this epoch's wire (9.92.0) — the tools slot's own
+     * record of its merge, shared by reference like `providerToolCache`. The
+     * first thing `lookupTool` consults, so the party whose contract the model
+     * read is the party that answers. Absent (a chart without the slot's
+     * record) → resolution order 1 alone, exactly as before 9.92.0.
+     */
+    readonly servedTools?: ServedToolParties;
+    /**
+     * Every build-time claimant per tool name (9.92.0) — `buildToolRegistry`'s
+     * `toolClaimants`. Read for one thing: which party a registry-routed tool
+     * belongs to, so an off-wire dispatch can be REPORTED with its answering
+     * party (`tools.answered_off_wire`). Absent → `'registry'`.
+     */
+    readonly toolClaimants?: ReadonlyMap<string, readonly ToolClaim[]>;
+    /**
+     * WHICH SKILLS DECLARE EACH TOOL NAME (9.86.0) — tool name → the ids of the
+     * skills whose `inject.tools` carry it, from `buildToolRegistry`, the one
+     * place that already walks every skill's tool array.
+     *
+     * Read by `dispatchRoster` and by nothing else: a role that may not see a
+     * skill may not be told the names of the tools that skill brought. A name is
+     * unnameable only when EVERY declaring skill is hidden, so a tool two skills
+     * share survives one of them being hidden.
+     *
+     * Absent for an agent with no skill-carried tools — the map is built only
+     * when at least one skill declares one — and then the roster is the raw
+     * dispatch set, exactly as it was.
+     */
+    readonly toolDeclaringSkills?: ReadonlyMap<string, readonly string[]>;
+}

package/dist/esm/core/agent/stages/toolCalls/contracts/catalog.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=catalog.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/catalog.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/dispatchBatch.d.ts

@@ -0,0 +1,17 @@
+import type { buildDispatchContext } from '../batch/dispatchContext.js';
+import type { buildFindingsAdmission } from '../batch/findingsAdmission.js';
+import type { InputsDispatch } from './inputsDispatch.js';
+import type { DispatchCall } from './batchCall.js';
+type BatchContext = ReturnType<ReturnType<typeof buildDispatchContext>['prepareDispatchContext']>;
+type BatchAdmission = ReturnType<ReturnType<typeof buildFindingsAdmission>['admitFindingsBatch']>;
+/** Runtime references for ONE batch; never stored in scope, a checkpoint, or a run registry. */
+export type DispatchBatchFrame = Readonly<BatchContext & {
+    toolCalls: readonly DispatchCall[];
+    iteration: number;
+    findingsRefusals: BatchAdmission['findingsRefusals'];
+    inputs: InputsDispatch | undefined;
+    resolutions: ReturnType<InputsDispatch['resolutionsFor']> | undefined;
+    askedLayer: InputsDispatch | undefined;
+    oneQuestionAsked: boolean;
+}>;
+export {};

package/dist/esm/core/agent/stages/toolCalls/contracts/dispatchBatch.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dispatchBatch.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/dispatchBatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatchBatch.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/dispatchBatch.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/dispatchCall.d.ts

@@ -0,0 +1,14 @@
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../../../types.js';
+import type { DispatchCall } from './batchCall.js';
+import type { DispatchBatchFrame } from './dispatchBatch.js';
+/** Only the native handler translates these local completion facts into its existing return. */
+export type DispatchCallOutcome = {
+    readonly kind: 'landed';
+} | {
+    readonly kind: 'halted';
+} | {
+    readonly kind: 'paused';
+    readonly pause: unknown;
+};
+export type DispatchCallRunner = (scope: TypedScope<AgentState>, tc: DispatchCall, callIndex: number, batch: DispatchBatchFrame) => Promise<DispatchCallOutcome>;

package/dist/esm/core/agent/stages/toolCalls/contracts/dispatchCall.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dispatchCall.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/dispatchCall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatchCall.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/dispatchCall.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/evidence.d.ts

@@ -0,0 +1,211 @@
+import type { Classifier } from '../../../../../classify/types.js';
+import type { ResolvedEvidenceGate } from '../../../evidence/types.js';
+import type { ToolResultColumns } from '../../../../../integrity/column-types/types.js';
+import type { ColumnCheckMode } from '../../../../../integrity/column-types/check.js';
+import type { ReadRunTime } from '../../../../../time/clock.js';
+import type { ZoneName } from '../../../../../time/zone.js';
+import type { TimePolicy } from '../../../../../time/resolveRecord.js';
+import type { TimeAskMessages } from '../../../../../time/ask.js';
+/** The evidence dependencies of the existing tool-call stage. */
+export interface ToolEvidencePort {
+    /**
+     * True when the agent declared a `.claims()` contract (9.61.0). The claim
+     * ledger accumulates ONLY then: an agent whose tools return semantic
+     * envelopes but who declared no contract has nothing that would ever read
+     * those rows, and writing them would be committed state — and a growing
+     * checkpoint — bought for nobody.
+     */
+    readonly collectClaimFacts?: boolean;
+    /**
+     * THE FINDINGS LEDGER IS ARMED (9.101.0, `.findings()`) — present only
+     * then, only ever `true`. Three things happen in `execute` and nowhere
+     * else, each gated on this: the previous batch's STANDINGS are read off
+     * every call's `_findings.previous` before `toolResults` is reset; the
+     * reserved argument is PEELED off each call's args as the first read of
+     * `tc.args` in the loop (`peelCall` — unless the tool answering the name
+     * owns the property, when the value is the author's argument), so
+     * `callArgs` — middleware, validation, check-in evidence, wants,
+     * credentials, execute, the pause and halt carriers — never sees the
+     * model's declaration; and a BASIS row is filed the moment a call
+     * declares one, before `tool_start` and before any pause `return`. The
+     * resume doors file nothing (the pre-pause commit already has the row).
+     * History keeps `toolCalls[].args` verbatim: the emission. Absent — the
+     * default — and not one of those lines runs.
+     */
+    readonly findings?: true;
+    /**
+     * THE SCRIPT RECORD IS ARMED — `.namesAndNumbersFromEvidence({ code:
+     * 'match' })` or `.scriptTravelsWithTheAnswer()`; present only then, only
+     * ever `true`. Each call of a tool that declares `Tool.script` files ONE
+     * `script` row (`../../../scripts/rows.ts`) where the call settles — every
+     * `tool_end`-emitting path and the batch settlement — and a `submitted`
+     * row, without its text, where it pauses: the program SUBMITTED to the
+     * tool (the arguments handed to `execute`, after any before-tool
+     * middleware) and the label its execution record earns
+     * (`../../../scripts/label.ts`). Never evidence, never on an event. Absent — the
+     * default — and not one line of it runs, and no tool is asked for its
+     * declaration.
+     */
+    readonly scriptRecord?: true;
+    /**
+     * THE INPUTS LAYER IS MOUNTED (honesty layer 2) — present only then, only
+     * ever `true`. Under it, the batch loop reads `argumentResolutions` (what
+     * `sf-inputs` resolved for THIS batch — entries stamped with another
+     * iteration are ignored) and, per call, applies the entry AFTER
+     * `tool_start` (which keeps the model's proposal) and BEFORE the permission
+     * check: a fill builds a fresh `{ ...args, ...fills }` that permission,
+     * middleware, validation, check-in, credentials and execute all see, and a
+     * refused entry lands in the argument-refusal shape — after permission and
+     * BEFORE the middleware chain, so no middleware asks about a call that will
+     * not run (the ask-resume door re-applies it). A call that ran on a filled
+     * value gets the layer's past-tense note after the tool's own bytes — one
+     * clause per fill it really ran with — and its history message carries
+     * `toolChars`. ABSENT, a call whose tool declares argument rules is REFUSED
+     * (fail closed — a ToolProvider served it and the build could not see it),
+     * at the same place and at the same door, with one warning naming
+     * `.inputsLayer()`; every other call runs exactly as it always did.
+     */
+    readonly inputsLayer?: true;
+    /**
+     * DECLARED SOURCES ARE ARMED (honesty layer 2, `.findings({ argumentSources:
+     * true })` or `.inputsLayer({ argumentSources: true })`) — present only
+     * then, only ever `true`, and only beside `inputsLayer`. The per-call peel
+     * reads `_findings.from` exactly as the inputs layer read it
+     * (`findings/reserved.ts` · `splitFindings`'s arms), so a `from`-only
+     * declaration is readable and — beside `findings` — a dropped `from` entry
+     * is counted on the call's basis row. WITHOUT `findings` the peel takes the
+     * argument off a RULED tool's calls only (the only ones it was planted on)
+     * and files no basis row: the layer put the count on the call's first
+     * argument row. An answered note gains the clause that a later call may cite
+     * the answer. The checks themselves ran in the layer, before this stage;
+     * nothing else here reads `from`.
+     */
+    readonly argumentSources?: true;
+    /**
+     * The results layer is mounted (honesty layer 3, step 7b) — a registered
+     * tool declares a `ToolPeriod`, or the agent was built with
+     * `.resultsLayer()`. Present: dispatch stamps the batch with the iteration
+     * that ran it (`AgentState.toolResultsIteration`, how the layer tells a
+     * batch from a re-entry), and the one ledger writer stamps the turn.
+     * Absent: a result that declares a `period` is still recorded (the tool's
+     * declaration rides `coverageDeclared` and the events either way), and a
+     * dev warning says, once per tool, that no verdict will be filed for it.
+     */
+    readonly resultsLayer?: true;
+    /**
+     * `.negativeClaims()` is armed: a
+     * composed absence's `tools.absent` carries `lookedForRef` in place of
+     * `lookedFor`. Composed values ride no event in any mode; unarmed,
+     * `lookedFor` is today's bytes. Absent → unarmed.
+     *
+     * @internal
+     */
+    readonly negativeClaimsArmed?: boolean;
+    /**
+     * THE ANSWER LAYER IS ARMED (honesty layer 4, `.answerLayer()`) — the ONE
+     * thing it changes here is the turn stamp: while any honesty layer is armed
+     * the one writer stamps every row it files with the conversation turn
+     * (adopted Q6), so the rows this handler files (basis, standing, judgment,
+     * contingent) carry `turn`. Absent → the rows are filed as they always were.
+     */
+    readonly answerLayer?: true;
+    /**
+     * THE JUDGE (9.104.0, `.findings({ judge })`) — present only with the arm
+     * and only when a classifier was configured. After every landed result is
+     * committed to `toolResults` — the execute loop and the four resume doors
+     * alike — `findings/judge.ts · judgeResult` spends one classifier call and
+     * files a `JudgmentRow` (or a `JudgmentErrorRow`) BEFORE the next model
+     * call, so the record carries the second source's reading beside the
+     * model's before anything is served; nothing is served from it in this
+     * release. Only a result the TOOL produced is judged — a denial, a halt,
+     * a fail-closed refusal or a declined check-in is the library's sentence
+     * about a call that never ran, never evidence (`judgeLanded`). Absent —
+     * the default — and not one line runs.
+     */
+    readonly findingsJudge?: Classifier;
+    /**
+     * THE TOWERS AT DISPATCH (9.110.0, `.findings()` beside
+     * `.namesAndNumbersFromEvidence()`) — the resolved evidence gate, present
+     * ONLY when both doors are armed. Under it, once per batch and only when
+     * the ledger's fold holds a set-aside standing (`open`, `noise`,
+     * `ruled-out`), the batch's evidence corpus is built from the history this
+     * call was served (`evidence/evidenceIndex.ts · evidenceFromHistory` —
+     * the same fold the route decider asks at the answer, one stage earlier)
+     * and every call's peeled arguments are read for DATA values the corpus
+     * holds (`findings/contingent.ts · groundedArgumentValues`); a value whose
+     * every carrier the model itself set aside files a `ContingentRow` through
+     * the one writer, after the call's basis row and before `tool_start`.
+     * Absent — the default, and every agent with one door or neither — and not
+     * one line runs.
+     */
+    readonly evidenceGate?: ResolvedEvidenceGate;
+    /**
+     * THE WRITE SEAM (9.77.0, `empty-lookup`) — the declared argument-ground
+     * edges (`Tool.argumentsFrom`) by tool name, present ONLY when the operator
+     * turned `AgentOptions.noticeEmptyLookups` on AND at least one tool declares
+     * one. Absent — the default — and not one line of the check runs.
+     *
+     * The same harvested map `callLLM` reads for the choice seam, and passed
+     * rather than re-derived from `registryByName` on purpose: the two stages
+     * must agree, by construction, about which calls are armed. Deriving it here
+     * would arm `ToolProvider`-delivered tools that the choice seam structurally
+     * cannot see, and the two seams' ledger rows would then disagree about the
+     * same run.
+     */
+    readonly emptyLookupGrounding?: ReadonlyMap<string, readonly string[]>;
+    /**
+     * THE WRITE SEAM'S other check (9.78.0, the COLUMN-TYPE CONTRACT) — each
+     * declaring tool's `Tool.resultColumns` by tool name, present ONLY when the
+     * operator's `checkColumnTypes` dial is off `'off'` AND at least one tool
+     * declares columns. Absent — the default — and not one line of the check
+     * runs.
+     *
+     * Harvested in `Agent.buildChart` from the same catalog the other seams
+     * read, and passed rather than re-derived here for the `emptyLookupGrounding`
+     * reason: the stage that files the "nothing to judge this response"
+     * not-applicable row and the stage that judges must agree, by construction,
+     * about which tools are armed.
+     */
+    readonly columnDeclarations?: ReadonlyMap<string, ToolResultColumns>;
+    /** What the boundary does with a column finding — `'warn'` files and changes
+     *  nothing, `'enforce'` refuses the rows. Present with
+     *  {@link ToolCallsDeps.columnDeclarations} or not at all. */
+    readonly columnCheckMode?: ColumnCheckMode;
+    /**
+     * The per-run disposition ledger, by REFERENCE (9.60.0) — the same holder
+     * `callLLM` and the tools slot are handed, shared through the build closure
+     * and never scope state. Read by the write-seam check only; a handler built
+     * without it simply files no rows.
+     */
+    readonly integrityLedger?: {
+        current: import('../../../../../integrity/disposition/ledger.js').DispositionLedger | undefined;
+    };
+    /**
+     * THE TIME LAYER (`.time()`) — present only then. Each dispatched call files
+     * one `call` row with `dispatchedAt` (the wall clock, just before the tool
+     * runs: a tool evaluates a look-back against its own clock at dispatch,
+     * which after a pause is later than the turn's `now`). `takePassedOnResume`
+     * hands over the `time` the current resume passed, as read, ONCE (a second
+     * call answers `undefined`) — the first ToolCalls pass of the resumed leg
+     * compares it with the turn's kept clock and files `clock-on-resume` when
+     * they differ; the kept clock is never replaced. A call whose tool's period
+     * declares forms is handed `ctx.time` (read off its `call-window` row), and
+     * the batch ask judges a period answer against the tool's facts at the
+     * turn's clock (`appZone`: the app's `.time({ zone })`).
+     *
+     * @internal
+     */
+    readonly time?: {
+        readonly takePassedOnResume: (scope: object) => ReadRunTime | undefined;
+        readonly appZone?: ZoneName;
+        /**
+         * Present exactly under `.time({ reader })` (step T6b): the batch ask asks
+         * a period left out while the turn's one mention is open as THAT
+         * mention's window — the lazy word-driven ask (`../../argumentAsk.ts` · `windowPlanOf`).
+         */
+        readonly reader?: {
+            readonly policy: TimePolicy;
+            readonly messages?: Partial<TimeAskMessages>;
+        };
+    };
+}

package/dist/esm/core/agent/stages/toolCalls/contracts/evidence.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evidence.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/evidence.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/handlerDeps.d.ts

@@ -0,0 +1,11 @@
+import type { ToolCatalogPort } from './catalog.js';
+import type { ToolAccessPort } from './access.js';
+import type { ToolEvidencePort } from './evidence.js';
+import type { ToolRoutingPort } from './routing.js';
+import type { ToolResourcesPort } from './resources.js';
+import type { ToolArtifactsPort } from './artifacts.js';
+import type { ToolObservationPort } from './observation.js';
+import type { ToolResultsPort } from './results.js';
+/** The composed dependency contract consumed by the existing tool-call handler. */
+export interface ToolCallsHandlerDeps extends ToolCatalogPort, ToolAccessPort, ToolEvidencePort, ToolRoutingPort, ToolResourcesPort, ToolArtifactsPort, ToolObservationPort, ToolResultsPort {
+}

package/dist/esm/core/agent/stages/toolCalls/contracts/handlerDeps.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=handlerDeps.js.map

package/dist/esm/core/agent/stages/toolCalls/contracts/handlerDeps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlerDeps.js","sourceRoot":"","sources":["../../../../../../../src/core/agent/stages/toolCalls/contracts/handlerDeps.ts"],"names":[],"mappings":""}

package/dist/esm/core/agent/stages/toolCalls/contracts/inputsDispatch.d.ts

@@ -0,0 +1,2 @@
+/** The inputs layer's half of dispatch, once loaded. */
+export type InputsDispatch = typeof import('../../../arguments/dispatch.js');