agentfootprint 13.0.0 → 14.0.0

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

@@ -1,895 +0,0 @@
-import type { PausableHandler, TypedScope } from 'footprintjs';
-import type { LLMMessage, PermissionChecker } from '../../../provider-contract/types.js';
-import type { AgentfootprintEventType } from '../../../events/registry.js';
-import { type TurnRoute } from '../../../injection-engine/routingPolicy.js';
-import { type SkillTargetClass } from '../../../injection-engine/skillGraph.js';
-import { type SpokenIds } from '../../../lib/spokenIds.js';
-import type { ToolProvider } from '../../../tools/toolProvider.js';
-import type { CredentialProvider } from '../../../identity/types.js';
-import { type RequestContext } from '../../../identity/requestContext.js';
-import type { ArtifactStore } from '../../../artifacts/types.js';
-import { type ArtifactPlacement } from '../../../artifacts/placement.js';
-import type { AuthorizationRequiredMode } from '../../../identity/consent.js';
-import { type AnsweredAsk } from '../../../tools/inputRequest.js';
-import { type ResolvedCheckInConfig } from '../../checkin.js';
-import { type DecisionLedger } from '../../consentRequest.js';
-import type { ProviderToolCache, ServedToolParties } from '../../slots/buildToolsSlot.js';
-import type { ToolClaim } from '../buildToolRegistry.js';
-import type { Tool } from '../../../tools/tools.js';
-import type { MemoryIdentity } from '../../../memory/identity/types.js';
-import type { ToolSessionTier } from '../../../tools/toolSessions.js';
-import type { ToolMiddleware } from '../middleware/types.js';
-import type { Classifier } from '../../../classify/types.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';
-import type { ResolvedEvidenceGate } from '../evidence/types.js';
-import { type ToolArgValidationMode } from '../../../tools/toolArgsValidation.js';
-import { type StepPlanFor } from '../../../injection-engine/skillSteps.js';
-import type { ProducedResult } from '../../../integrity/empty-lookup/check.js';
-import type { ColumnCheckMode } from '../../../integrity/column-types/check.js';
-import type { ToolResultColumns } from '../../../integrity/column-types/types.js';
-import type { AgentState } from '../types.js';
-export interface ToolCallsHandlerDeps {
-    /** 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>;
-    /**
-     * 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 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;
-    /**
-     * 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;
-    };
-    /**
-     * 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[]>;
-    /** 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[]>;
-    /** 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;
-    /**
-     * 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;
-    /** 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;
-    /**
-     * The opt-in ceiling on ONE tool result, in characters (9.11.0).
-     *
-     * Undefined — the ordinary case — means results are never measured and never
-     * replaced, which is what every release before 9.11.0 did. Set, and EVERY
-     * result on EVERY dispatch path in this handler is measured against it; over
-     * the cap, the result the model reads and the result
-     * `agentfootprint.stream.tool_end` carries are both the marker. See
-     * `../toolResultCap.ts` for the shape and why it is opt-in.
-     */
-    readonly maxToolResultChars?: number;
-    /**
-     * Tell the model when it has already made this exact call and already got
-     * this exact answer (9.26.0). Threaded from `AgentOptions.repeatedCallNudge`,
-     * and only when the operator turned it OFF — `undefined` here means the
-     * default, which is on.
-     *
-     * Applied at the BATCH dispatch loop only, which is where a turn's repeats
-     * actually happen. The pause-resume paths deliver a call a PERSON answered
-     * or approved, and a note telling the model it has already done what a human
-     * just authorised would be the framework arguing with the human.
-     */
-    readonly repeatedCallNudge?: boolean;
-    /**
-     * Keep this run's tool-call ledger (`AgentState.toolCallLedger`) for an
-     * `answerValidation` check: name, call id and outcome per `stream.tool_end`
-     * bracket, at most `maxCalls`. Threaded ONLY on an agent with
-     * `answerValidation` — absent, no bracket writes anything, and the agent
-     * commits exactly the keys it always did.
-     */
-    readonly toolCallLedger?: {
-        readonly maxCalls: number;
-    };
-    /**
-     * Skill-graph read_skill GATE (`graph.reachableSkills`). When present, a
-     * `read_skill('id')` whose `id` is not reachable from the current cursor is
-     * REJECTED — the model gets a synthetic re-prompt naming the allowed ids and
-     * the cursor/activations stay unchanged, so it can't leave the graph mid-run.
-     * Undefined → no gate (plain read_skill agents append as before).
-     */
-    readonly allowedSkillIds?: (currentSkillId?: string) => readonly string[];
-    /**
-     * The OPEN skills — registered skills the graph never wires, admitted by the gate
-     * from ANY cursor (8.4.0; see `Agent.openSkillIds`). They ACTIVATE and never move
-     * the cursor: a skill the graph does not route is not a node, so it cannot be a
-     * hop. Only meaningful alongside `allowedSkillIds`.
-     */
-    readonly openSkillIds?: readonly string[];
-    /**
-     * The mount kernel's plan (9.59.0) — present only on agents built with
-     * `.maps()`. Read for exactly one thing: to tell a cursor move from a
-     * RE-ENGAGEMENT at the gate below. Everything else about engagement stays
-     * the kernel's business.
-     */
-    readonly engagementPlan?: import('../../../maps/engagement/types.js').EngagementPlan;
-    /**
-     * Is the mounted graph a decision `tree()`? Changes only the REFUSAL TEXT (8.5.0).
-     *
-     * A tree routes by predicate every iteration and has no cursor, so
-     * `reachableSkills()` is empty and every leaf pick is refused. Told with the
-     * generic message that reads "No skills are reachable from here", which is true
-     * but teaches nothing — the model would keep trying. The tree-shaped message says
-     * why the graph cannot be jumped at all, so the model stops asking and answers.
-     */
-    readonly skillGraphIsTree?: boolean;
-    /**
-     * The frozen step plans, keyed by skill id (9.18.0) — set only when ≥1
-     * registered skill declares `steps`. This stage owns the pointer's two
-     * RESULT-BOUNDARY moves, applied at EVERY site a result becomes final and
-     * is pushed (the batch loop AND all the pausable resume paths — a step
-     * whose tool paused, an `askHuman` step first among them, must advance on
-     * the resumed call exactly as it would have inline):
-     *
-     *   • ADVANCE — the finalized call is the current step's tool, ran, and
-     *     was not an error/denial/refusal → pointer + 1, `step_advanced`, and
-     *     the model-visible result gains the "now on step k+1" suffix
-     *     (composed BEFORE the history push — one past, no splicing).
-     *   • SKIP — a `skip_step` call: reason validated (empty → teaching
-     *     result, no event), `step_skipped` emitted, pointer moved or held
-     *     per the skill's declared `onSkip`, and the model-visible result is
-     *     OVERWRITTEN with the authoritative sentence (the read_skill-refusal
-     *     precedent — bookkeeping lives where the batch order lives).
-     *
-     * Postures never gate `skip_step`: skipping is judgment INSIDE a step,
-     * not routing. Undefined → no stepped skill anywhere; not one new line
-     * runs (zero-cost-when-unused).
-     */
-    readonly stepPlanFor?: StepPlanFor;
-    /**
-     * The mount's routing POSTURE beyond reachability (SG-C `strictness`).
-     * Undefined = `'assist'` = today's gate, byte-for-byte — not one new line
-     * runs. Judged AFTER reachability (an unreachable pick keeps its original
-     * teaching refusal), and only on HOPS — an OPEN skill (`.selfExplain()`,
-     * a `.skill()` beside the graph) is admitted from anywhere under every
-     * posture, so debugging never breaks:
-     *   • `'guard'` — a routing pick is admitted only while the turn's MENU is
-     *     outstanding AND names an offered id (the framework declared the
-     *     ambiguity; the model resolves exactly that). Off-menu / no-menu picks
-     *     get a teaching refusal + `skill.rejected { posture: 'guard' }`.
-     *   • `'rails'` — routing picks are refused outright: rules/scorer resolve
-     *     turn starts, declared routes handle transitions.
-     * Same graph, same trace: postures change refusal behavior only.
-     *
-     * Read only by the `read_skill` gate below, and that is the whole scope:
-     * `applyToolEffects` never consults it, because a `propose-transition`
-     * comes from a tool — the author's own code — and is admitted under every
-     * posture against reachability alone. See `SkillGraphOptions.strictness`
-     * (AgentBuilder.ts), which states the exemption for authors.
-     */
-    readonly skillStrictness?: 'guard' | 'rails';
-    /**
-     * Escalate-on-evidence (9.19.0). When declared, the two `skill.rejected`
-     * emit sites below increment a per-turn counter; at `afterRefusals` the
-     * rest of the turn flips onto the escalation brain (`scope.skillEscalated`
-     * — a committed fact callLLM's `brainFor` reads) and `skill.escalated`
-     * goes on the record ONCE. Undefined — the default — and not one new key
-     * is read or written (zero-cost-when-unused).
-     */
-    readonly escalation?: {
-        readonly afterRefusals: number;
-        /** The declared escalation brain, for the event's `to`. */
-        readonly to: {
-            readonly provider: string;
-            readonly model?: string;
-        };
-        /** Resolve the brain that WAS serving (the event's honest `from`) — the
-         *  same precedence chain callLLM applies, evaluated at the flip. */
-        readonly describeFrom: (cursor: string | undefined, resolvedModel: string | undefined) => {
-            readonly provider: string;
-            readonly model: string;
-        };
-    };
-    /**
-     * The registered injection ids a `require-instruction` tool effect may
-     * push, with the one fact its check-up needs (9.19.0): a skill whose
-     * declared body channel is `'tool-only'` cannot be pushed through the
-     * system slot — the slot suppresses it — so granting the lease would be
-     * accepted-and-silently-undelivered. Undefined → the agent registered no
-     * injections; every require-instruction is a teaching refusal.
-     */
-    readonly leaseTargets?: ReadonlyMap<string, {
-        readonly surfaceMode?: string;
-    }>;
-    /**
-     * 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 durable-write barrier (`core/durabilityBarrier.ts`). Asked ONCE per
-     * iteration, before any of this iteration's tools are dispatched: if the last
-     * iteration's state is still being written to a session store, wait for it.
-     *
-     * This is what bounds side-effect replay. Without it, iteration N's tools run
-     * while iteration N-1's write is in flight, so a crash can re-issue more than
-     * one iteration's worth of tool calls on replay and "how much re-executes?"
-     * has no answer. With it the answer is exactly one: the current iteration.
-     *
-     * Returns `undefined` when nobody installed a barrier — the ordinary case —
-     * and the dispatch loop then does not await at all, so an agent without a
-     * durable session composer is byte-identical in behaviour AND in timing.
-     *
-     * NOT a general extension point: the only installer is
-     * `agentfootprint/hosting`'s session writer, through a module-private
-     * WeakMap that appears on no barrel. See `core/durabilityBarrier.ts`.
-     *
-     * @internal
-     */
-    readonly awaitDurable?: () => Promise<void> | undefined;
-    /**
-     * The identity facts THIS run carries, for `ToolExecutionContext` (9.7.0).
-     *
-     * An ACCESSOR, for the same reason `awaitDurable` is one: the chart is built
-     * ONCE at construction and these change per run, so a captured value would be
-     * run #1's forever. Read once per dispatch loop, beside `scope.runIdentity`.
-     *
-     * `identity` here is the CALLER's explicit identity (`Agent.lastRunIdentity`),
-     * NOT `scope.runIdentity` — the latter is always populated, defaulting to
-     * `{ conversationId: '<runId>' }` (or, on a session-bound run since 9.10.0,
-     * to `{ conversationId: sessionId }`), and publishing either to a tool would
-     * present a synthesized conversation as one somebody named.
-     *
-     * @internal
-     */
-    /**
-     * Is this stage running in the agent's OWN executor? Asked of the scope
-     * (`stages/seed.ts` · `isOwnRun`): a stage in another runner's executor — a
-     * composition member — reads its run facts from `scope.memberRun`, never
-     * from {@link currentRun}, which describes the instance's own last run.
-     * Absent → the agent's own run.
-     *
-     * @internal
-     */
-    readonly isOwnRun?: (scope: object) => boolean;
-    readonly currentRun?: () => {
-        readonly runContext?: import('../../../bridge/eventMeta.js').RunContext;
-        readonly runId: string;
-        readonly sessionId?: string;
-        readonly identity?: MemoryIdentity;
-    };
-    /**
-     * 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;
-    /**
-     * 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>;
-        };
-    };
-    /**
-     * Put one artifact fact on the record for the run it BELONGS to — the door
-     * a `ctx.artifacts` fact takes when it lands after that run ended (a tool's
-     * floating upload finishing during a later run). The scope channel stamps
-     * whatever run is live at emit time; this stamps the run context the binding
-     * captured when it was built.
-     *
-     * @internal
-     */
-    readonly emitForRun?: (type: AgentfootprintEventType, payload: Record<string, unknown>, runContext: import('../../../bridge/eventMeta.js').RunContext) => void;
-    /**
-     * The runner's teardown tier, created on first use (9.7.0).
-     *
-     * An accessor for the same reason as `currentRun`, and lazy for a second one:
-     * an agent whose tools never register a cleanup must not pay for a tier, so
-     * the Agent builds one the first time a tool asks.
-     *
-     * @internal
-     */
-    readonly toolSessions?: () => ToolSessionTier;
-    /**
-     * 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;
-}
-/**
- * Is this `read_skill` target the cursor's own skill AND is that cursor
- * MOUNTED — the one owner of "this call would change nothing" (9.86.0).
- *
- * ── WHY POSITION ALONE IS NOT THE ANSWER ────────────────────────────────
- *
- * `classifySkillTarget` answers a question about POSITION: is the target where
- * the cursor stands? For most of the loop that settles it — the cursor's body
- * is in that call's system prompt and its tools are on that call's wire, so
- * asking to read it activates nothing, moves nothing and reveals nothing the
- * request did not already carry.
- *
- * A PARKED map breaks that. Parking suppresses a map's contribution and leaves
- * the cursor exactly where it was, so at a parked cursor the very same id is a
- * RE-ENGAGEMENT: the gate admits it, the map engages, and the member's body and
- * tools ride again on the next pass. That call moves something, which makes it
- * a capability, which makes it the policy's question to answer.
- *
- * The dispatch gate has known this since 9.59.0 — it tests re-engagement BEFORE
- * its self-call arm, which is this same fact written as two ordered arms. The
- * `skill_read` permission gate, 480 lines upstream, has no arms to order: it
- * asks one question and either spends the policy check or skips it, and it was
- * asking `classifySkillTarget` alone. So a role whose checker hid a skill could
- * have the model un-park and re-activate it. This function is the question that
- * gate now asks, over the parked set `parkedNow` hands both of them.
- *
- * @example
- * ```ts
- * atMountedCursor({ cursor: 'audit', target: 'audit' });                          // true  — a stay
- * atMountedCursor({ cursor: 'audit', target: 'audit', parked: new Set(['audit']) }); // false — a re-engagement
- * atMountedCursor({ cursor: 'audit', target: 'billing' });                        // false — a move
- * ```
- */
-export declare function atMountedCursor(args: {
-    /** Where the cursor stands. `undefined` = cold start (nothing is a stay). */
-    readonly cursor?: string | undefined;
-    /** The id the model asked for. */
-    readonly target: string;
-    /** Members of every map the kernel holds PARKED — `parkedMemberIds`. */
-    readonly parked?: ReadonlySet<string> | undefined;
-}): boolean;
-/**
- * What a call to a name nothing can dispatch gets back (9.86.0).
- *
- * `Unknown tool: X` was the whole sentence, on both dispatch doors, while
- * `mcpServe` — the same library, one directory away — had been answering
- * "Unknown tool 'rm_rf'. Served tools: echo, delete_account." for releases. The
- * model that mistyped a name, or named one from a restored transcript, was told
- * only that it was wrong, never what would have worked, and the cheapest repair
- * (read the roster) was the one it could not make.
- *
- * The roster is the DISPATCH set — `registryByName` plus the provider cache —
- * because that is the true statement about resolution: these are the names that
- * answered to something. It is deliberately NOT the offer: the wire is narrowed
- * by steps, parks and postures, and a held-out tool still dispatches by name, so
- * an offer-shaped list would be a different (and here, false) claim.
- *
- * ── AND IT SAYS "RESOLVED", NOT "COULD BE DISPATCHED" ───────────────────
- *
- * The first draft said "Tools that could be dispatched on that call". Two gates
- * sit between resolution and a tool running — the `tool_call` permission check
- * and the middleware chain — so a name in this map can resolve and still be
- * refused, and the sentence promised the model a dispatch the very next gate
- * would decline. Neither gate is asked here: a `PermissionChecker` is a port
- * (a hub call per name, with its own events and its own audit rows), and
- * spending a whole permission sweep to phrase an error is a cost the sentence
- * does not need. It reports what this map DID — resolve a name — and claims
- * nothing about what would have happened next.
- *
- * The roster is role-filtered before it gets here (`dispatchRoster`), so a tool
- * belonging to a skill the caller's policy hides is never named; and when the
- * filter empties a stocked roster the clause is DROPPED, because "no tool name
- * resolved" would be a denial of what the dispatch map is holding.
- *
- * Anchored past tense, like every other persistent result: "on that call" binds
- * the roster to the finished call the result answers, so a later iteration that
- * adds or drops a provider tool cannot make this sentence wrong. No exhortation
- * — the model does not need to be told to try again.
- *
- * Exported for the producer registry, and used by BOTH dispatch doors so they
- * cannot drift.
- */
-/**
- * What a call gets back when the party whose contract the model read under
- * this name cannot answer it, and no other party may (9.92.0).
- *
- * Two doors reach here. A name that LEFT the wire — the model read a
- * provider's contract on an earlier call and the provider withdrew the name —
- * whose only remaining holder is a party the model was never shown under that
- * name (a scoped skill that never activated): dispatching that holder would
- * hand the model's belief to a stranger's function, which is the silent
- * identity swap this release closed. And a resume in a fresh Agent instance
- * of a provider-served call, where the served party is on the checkpoint but
- * the provider's list has not been resolved on this instance.
- *
- * It names no roster on purpose: `unknownToolResult`'s roster is the DISPATCH
- * map, and the map here holds exactly the implementation this sentence is
- * refusing. Anchored past tense, one clause, like every persistent result.
- */
-export declare function notServedResult(toolName: string): string;
-export declare function unknownToolResult(toolName: string, dispatchable: SpokenIds): string;
-/**
- * THE ONE COMPOSER of every `read_skill` refusal (9.86.0) — reachability,
- * posture and tree, from one set of inputs.
- *
- * ── WHY ONE ─────────────────────────────────────────────────────────────
- *
- * There were two, and they disagreed. `skillRefusal` named "Reachable skills:
- * beta" from the graph's raw hop set; `postureRefusal`, forty lines below it in
- * the same gate, answered a model that took that offer up with "read_skill here
- * reaches only the open skills: gamma". Same call, same turn, opposite claims —
- * and the second one cost a refusal from the escalation budget to discover.
- * Neither had heard of the role filter, so both could name a skill the caller's
- * policy hides. One composer, handed the FILTERED sets and the posture that
- * will judge the next pick, cannot contradict itself that way.
- *
- * ── THE TENSE DISCIPLINE (the law `selfCallNotice` is written against) ──
- *
- * A tool result is composed on iteration N and re-read by the model on every
- * later call of the turn, including the tool-less wrap-up. So every clause here
- * is a PAST fact about ONE named call — the call the model made `read_skill`
- * on — anchored by the phrase "that call", never by deixis ("this turn", "the
- * call you just made") and never by a forecast ("you can call", "pick one of
- * these"). What the model may do NEXT is owned by the `read_skill` DESCRIPTION,
- * which is recomposed for every single request and may therefore speak in the
- * present. Two owners, one tense each, and they can no longer disagree.
- *
- * ── AND WHY IT NEVER NAMES A HOP THE POSTURE WOULD DECLINE ──────────────
- *
- * Under `'rails'` the model does not route at all; under `'guard'` it routes
- * only from an outstanding menu. Naming hops there is an offer the very next
- * arm of this gate refuses. So those arms name no hop: they say who DID route,
- * and (when there are any) which open skills were admitted anyway — open skills
- * never reach the posture arm, so that clause cannot be contradicted.
- *
- * ── AND WHY AN EMPTY LIST IS NEVER A DENIAL ─────────────────────────────
- *
- * Every set arrives as {@link SpokenIds}, which carries whether the UNFILTERED
- * set held anything. That is the difference between "nothing was reachable" and
- * "nothing reachable may be named", and this composer used to say the first
- * when the second was true — over a graph that was routing the cursor the whole
- * time. Where the filter empties a set, the clause is omitted. A model told the
- * map is a dead end stops asking for the door it may not be shown.
- *
- * Exported so a producer registry can list it beside the other model-facing
- * composers rather than re-deriving what it says.
- */
-export declare function composeReadSkillRefusal(args: {
-    /** The id the model asked for, verbatim. */
-    readonly requestedId: string;
-    /** Which class the target fell in — from `classifySkillTarget`, the one owner. */
-    readonly targetClass: SkillTargetClass;
-    /** Where the cursor stood when that call was made. */
-    readonly cursorId?: string;
-    /** Declared hops from that cursor, through the role filter — and carrying
-     *  whether the graph held any, so a filtered-to-empty set omits its clause
-     *  instead of denying the hops the graph is holding. */
-    readonly hops: SpokenIds;
-    /** Open skills, through the same filter. */
-    readonly openIds: SpokenIds;
-    /** The mounted graph is a decision `tree()` — no cursor to move. */
-    readonly isTree?: boolean;
-    /** The posture that declined a reachable hop, when one did (SG-C). */
-    readonly posture?: 'guard' | 'rails';
-    /** The menu that was outstanding when that call was made, through the same
-     *  filter. Present only under `'guard'` with a menu the pick missed — and
-     *  `held: true` with nothing named says a menu WAS outstanding and none of it
-     *  may be named, which is a third sentence, not the no-menu one. */
-    readonly menuOffered?: SpokenIds;
-    /** How the turn's start was resolved — `TurnRoute.by` — for the
-     *  `'guard'`-without-a-menu arm. Each value is a different past fact about
-     *  the turn, and the arm says only the one it was handed (9.86.1): it used to
-     *  append "Declared routes moved the cursor instead." to every no-menu
-     *  refusal, which is false for a cursor carried over from the previous turn
-     *  (`'continuity'`) and for a menu the model's own pick had resolved
-     *  (`'menu'`), and unprovable for `'none'`. */
-    readonly turnStartedBy?: TurnRoute['by'];
-    /** A cursor EXISTED on that call and the role filter kept its id out of the
-     *  sentence (9.86.1). `cursorId` is absent in two situations that need two
-     *  different sentences: a cold start, where "the turn's start" is the true
-     *  anchor, and a hidden cursor, where the skill is real and merely unnamed.
-     *  The description already withholds a hidden cursor's name — pinned by
-     *  `test/security/skill-visibility.test.ts` — and the refusal printed it raw. */
-    readonly cursorWithheld?: boolean;
-}): string;
-/**
- * Forget every "no judge for this period" warning issued so far — for a
- * declared period and for a declared `ToolPeriod`.
- * @internal test seam — the ledger is process-wide and warn-once.
- */
-export declare function _resetPeriodUnjudgedWarnings(): void;
-/** 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[];
-};
-/**
- * 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 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.
- *
- * Each result is read as the TOOL's own bytes (`lib/toolBytes.ts` ·
- * `toolBytesOf`): the note the inputs layer appends after a filled call's
- * result carries the value the library filled, and a value only that note
- * carries is not one the run's producer served.
- *
- * Exported for its unit test (`test/integrity/emptyLookup.test.ts`).
- */
-export declare function producerCorpusOf(history: readonly LLMMessage[], argumentsFrom: readonly string[]): ProducedResult[];
-export declare function buildToolCallsHandler(deps: ToolCallsHandlerDeps): PausableHandler<TypedScope<AgentState>>;