agentfootprint 9.74.0 → 9.76.0

package/dist/types/core/runbook/types.d.ts

@@ -0,0 +1,197 @@
+/**
+ * runbook/types — the vocabulary of the runbook bridge.
+ *
+ * Pattern: one options bag, four concerns (declarations, procedure, evidence
+ *          policy, walk policy) + one envelope type split into a MANDATORY
+ *          SPINE and an OPTIONAL projection. Pure data, no behavior.
+ * Role:    core/ layer. `runbookAsTool.ts` consumes; consumers read the
+ *          envelope types when they assert on results.
+ * Emits:   N/A.
+ *
+ * The SPINE / PROJECTION split is load-bearing honesty, not taste: the spine
+ * (coverage, provenance, rule version, the recorded walk) is what EVERY
+ * runbook ships whatever its shape, so an answer can never arrive without its
+ * boundary; the verdict/rowset projection is one shape of answer (a triage),
+ * selected by `resultKind: 'verdict/*'` — an action-taking runbook ships the
+ * spine plus its own `report` payload and no rowset. The spine's wire shape
+ * is explicitly PROVISIONAL until a second, differently-shaped consumer has
+ * shipped through it.
+ */
+import type { CombinedRecorder, FlowChart, RedactionPolicy } from 'footprintjs';
+import type { CoverageItem } from '../agent/coverage/types.js';
+import type { ToolDispatch, ToolOwner, ToolResultCeiling } from '../tools.js';
+import type { ToolResultClass } from '../../lib/semantics/types.js';
+import type { ToolWants } from '../../artifacts/wants.js';
+/**
+ * The procedure: a factory invoked PER CALL with the run's own tool dispatch
+ * (`ctx.tools`), returning a FRESH chart whose stages close over it.
+ *
+ * Per call for two reasons that are really one: a chart shared between two
+ * runs is a chart whose closures belong to whichever run built it last, and
+ * the dispatch only exists at execute time — so the factory is both the
+ * fresh-chart law and the delivery mechanism.
+ *
+ * It is ALSO invoked once at definition time, with a probe dispatch whose
+ * `has` answers false and whose `call` refuses — to read the chart's declared
+ * contract (input schema, the named decider's branches). Stage bodies do not
+ * run at build, so a well-formed factory pays nothing; a factory with side
+ * effects at build time is a factory that lies about being a declaration.
+ */
+export type RunbookProcedure = (tools: ToolDispatch) => FlowChart;
+/** Rule provenance — threaded bridge → envelope → coverage sentence, so an
+ *  answer produced under one reading of the rules can be told apart from an
+ *  answer produced under the next. */
+export interface RunbookRules {
+    /** The rule set's name ('health-signal'). Non-empty. */
+    readonly name: string;
+    /** Its version stamp ('v1'). Non-empty; bump when the READING changes,
+     *  never for wording. */
+    readonly version: string;
+}
+/** The verdict/rowset projection's dials. */
+export interface RunbookVerdictsOptions {
+    /**
+     * The decider stage (by id or name) whose declared branch labels generate
+     * `verdict_meanings`. Branch descriptions come from the chart's own
+     * structure when the decider is statically declared; rule labels observed
+     * in this run's decide() evidence refine them (and are the only source
+     * when the decider lives inside a dynamically generated fan-out branch,
+     * where build-time structure cannot see it).
+     */
+    readonly decider: string;
+    /** Cap on `verdicts` rows AND the rendered table — ONE number for both
+     *  halves (a longer list beside a shorter table is an invitation to retype
+     *  identifiers). Default 50. */
+    readonly maxRows?: number;
+}
+/** The walk policy. */
+export interface RunbookWalkOptions {
+    /** Row cap on the minted walk (default 500). When the full walk does not
+     *  fit, the CONTROL FLOW survives — see `walk.ts` for the projection law. */
+    readonly cap?: number;
+}
+/** Everything `runbookAsTool` accepts. Smallest legal call:
+ *  `{ name, description, procedure }` — and it still yields the spine. */
+export interface RunbookAsToolOptions {
+    /** Tool name the LLM dispatches by. */
+    readonly name: string;
+    /** REQUIRED — a description-less tool is invisible to the model. */
+    readonly description: string;
+    /** The procedure factory — see {@link RunbookProcedure}. */
+    readonly procedure: RunbookProcedure;
+    /** Selects the envelope projection (`'verdict/*'` gets the rowset) AND is
+     *  the artifact kind a placed result is minted under. */
+    readonly resultKind?: string;
+    readonly resultClass?: ToolResultClass;
+    readonly owner?: ToolOwner;
+    readonly resultCeiling?: ToolResultCeiling;
+    readonly wants?: ToolWants;
+    readonly argumentsFrom?: readonly string[];
+    /** The named ingredient tools the procedure calls through `ctx.tools` —
+     *  drift-checked at agent build. */
+    readonly composedOf?: readonly string[];
+    /** Explicit input schema wins; otherwise the chart's `.contract()` input
+     *  is lifted when it is a plain JSON-Schema object (a parseable schema —
+     *  zod et al. — cannot be serialized for the model and falls back to the
+     *  empty-object default). */
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+    /** Rule provenance — see {@link RunbookRules}. */
+    readonly rules?: RunbookRules;
+    /** The verdict projection's dials — see {@link RunbookVerdictsOptions}. */
+    readonly verdicts?: RunbookVerdictsOptions;
+    /** The walk policy — see {@link RunbookWalkOptions}. */
+    readonly walk?: RunbookWalkOptions;
+    /** Observers attached to each invocation's fresh inner executor. */
+    readonly recorders?: ReadonlyArray<CombinedRecorder>;
+    /** Keep each invocation's inner record for `inspect_tool_run` descent. */
+    readonly keepRecord?: boolean;
+    /** Bounded LRU size for kept records (requires `keepRecord: true`). */
+    readonly keepRecordLimit?: number;
+    /** Redaction policy for the inner run (commit-time scrub). */
+    readonly redact?: RedactionPolicy;
+}
+/**
+ * The recorded-walk descriptor — ALWAYS on the spine. The walk itself ships
+ * as an artifact ticket (`ref`), never as bytes in the envelope; with no
+ * store attached (or a failed mint) the descriptor still states its
+ * counters and the `note` names why there is no ticket — a missing walk must
+ * never be mistaken for a short run.
+ */
+export interface WalkDescriptor {
+    /** The claim-ticket ref of the minted walk artifact. Absent when no store
+     *  is attached or the mint failed — `note` says which. */
+    readonly ref?: string;
+    /** The artifact kind (`'recording/chart-walk'`). Present with `ref`. */
+    readonly kind?: string;
+    /** Rows in the minted artifact. */
+    readonly rows: number;
+    /** Total execution steps the narrative recorder counted — spans isolated
+     *  subflow logs, which the root commit log cannot. */
+    readonly steps_executed: number;
+    /** `'full'` — every narrative entry fit under the cap; `'control-flow'` —
+     *  it did not, and the stages/forks/subflows/decisions survived while the
+     *  per-key reads and writes were dropped. */
+    readonly projection: 'full' | 'control-flow';
+    readonly shown: number;
+    readonly total: number;
+    readonly complete: boolean;
+    /**
+     * WHICH SEGMENT of the run this walk covers. `'full'` for an un-gated run
+     * (all of phase 1). When approval gates land, a resumed run's recorders
+     * start empty on the fresh executor — its walk will say `'post-resume'`
+     * and its counters will count only that segment; the discriminant ships
+     * NOW so the wire does not break then.
+     */
+    readonly walk_segment: 'full' | 'pre-pause' | 'post-resume';
+    /** The human sentence: what the walk is, and (when projected) what the
+     *  control-flow projection kept and dropped, or why there is no ticket. */
+    readonly note: string;
+}
+/** One verdict row, as the chart wrote it. The bridge reads rows from the
+ *  final state's `verdicts` key and requires only `verdict`; every other
+ *  column is the app's own vocabulary. */
+export interface VerdictRow {
+    readonly verdict: string;
+    readonly [column: string]: unknown;
+}
+/** The mandatory-spine + optional-projection envelope every runbook returns
+ *  (unless an inner absence passed through — then the answer IS that absence,
+ *  verbatim). Recognized by the framework's coverage funnel at the dispatch
+ *  boundary like any `coverage()` ledger. */
+export interface RunbookEnvelope {
+    readonly af_coverage: {
+        readonly checked?: readonly CoverageItem[];
+        readonly not_checked?: readonly CoverageItem[];
+        readonly cannot_cover?: readonly CoverageItem[];
+        /** The static coverage law sentence (the `coverage()` note). */
+        readonly note: string;
+        /** The run's own sentence — names the rule set and version. */
+        readonly sentence: string;
+    };
+    readonly result: {
+        /** Re-emitted FIRST: the carried inner provenance stamp (if any inner
+         *  tool declared one — a LOCAL SEED confession survives composition)
+         *  plus this call's own `{tool, toolCallId}`. */
+        readonly af_provenance: Readonly<Record<string, unknown>>;
+        /** `rules.version`, or the honest `'undeclared'` when no rules were
+         *  declared — the field never silently vanishes. */
+        readonly rule_version: string;
+        /** The recorded walk — always present. */
+        readonly walk: WalkDescriptor;
+        readonly verdicts?: readonly VerdictRow[];
+        readonly rows_shown?: number;
+        readonly rows_total?: number;
+        readonly rows_complete?: boolean;
+        /** Pre-rendered markdown table over the SAME rows as `verdicts`. */
+        readonly table?: string;
+        /** The render law, stated to the model. Present with `table`. */
+        readonly render_note?: string;
+        /** branch → meaning, GENERATED from the decider's declared branches and
+         *  the rule labels this run's evidence carried — never hand-restated. */
+        readonly verdict_meanings?: Readonly<Record<string, string>>;
+        /** Everything the chart put in its `report` state key — the app's own
+         *  result fields, spread here verbatim (spine keys win). */
+        readonly [appField: string]: unknown;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/core/runbook/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/runbook/types.ts"],"names":[],"mappings":"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"}

package/dist/types/core/runbook/verdicts.d.ts

@@ -0,0 +1,79 @@
+/**
+ * runbook/verdicts — the OPTIONAL verdict/rowset projection.
+ *
+ * Pattern: pure selection + rendering over the run's final state, plus one
+ *          tiny recorder that harvests decide() evidence for generated
+ *          meanings. Selected by `resultKind: 'verdict/*'`; a runbook of any
+ *          other kind never sees this module.
+ * Role:    core/runbook.
+ * Emits:   N/A.
+ *
+ * THE ONE-NUMBER LAW: the rendered table and the structured `verdicts` list
+ * show the SAME rows under the SAME cap. A rendered table beside a longer
+ * structured list is an invitation that gets accepted — rows come back
+ * retyped with subtly wrong identifiers.
+ *
+ * GENERATED MEANINGS, never hand-restated: `verdict_meanings` is composed
+ * from (a) the named decider's declared branches in the chart's own structure
+ * (branch description, falling back to branch name), overlaid by (b) the rule
+ * LABELS this run's decide() evidence carried — the rule speaking for itself.
+ * A decider inside a dynamically generated fan-out branch is invisible to (a)
+ * by construction (the branch chart does not exist at build time); (b) still
+ * covers every verdict an executed rule produced.
+ */
+import type { CombinedRecorder } from 'footprintjs';
+import type { FlowChart } from 'footprintjs';
+import type { VerdictRow } from './types.js';
+/** Default cap on `verdicts` rows and the rendered table. */
+export declare const DEFAULT_MAX_ROWS = 50;
+/** The render law, stated to the model beside every table. */
+export declare const VERDICT_RENDER_NOTE: string;
+/** The reserved verdict word for "no classification was reached" — rows
+ *  carrying it are counted into the coverage ledger as not-checked ground
+ *  (the three-outcome honesty: reached, reached-and-clear, DECLINED). */
+export declare const DECLINED_VERDICT = "declined";
+/** Read the rowset off the final state's `verdicts` key — an array of bags
+ *  each carrying a string `verdict`. Anything else reads as "no rowset". */
+export declare function verdictRowsOf(state: Readonly<Record<string, unknown>>): VerdictRow[];
+/**
+ * Render the shown rows as one markdown table. Columns are the FIRST row's
+ * own keys in declaration order — the chart writes its rows, so the chart
+ * owns the column vocabulary; the bridge only renders it.
+ */
+export declare function renderVerdictTable(rows: readonly VerdictRow[]): string;
+/** The two spellings of the configured decider, once the static walk has
+ *  (maybe) resolved it — flow events report the decider by name. */
+export interface DeciderIdentity {
+    readonly spellings: ReadonlySet<string>;
+    /** branch → declared meaning, from the chart's own structure. */
+    readonly declared: ReadonlyMap<string, string>;
+}
+/**
+ * Find the named decider in the chart's static structure (root graph plus
+ * statically declared subflows) and read its branches. Loop-ref stubs are
+ * skipped FIRST — they deliberately violate node-id uniqueness.
+ */
+export declare function resolveDecider(chart: FlowChart, decider: string): DeciderIdentity;
+/** The evidence harvest: rule labels observed in this run, branch → label. */
+export interface MeaningsHarvest {
+    readonly recorder: CombinedRecorder;
+    readonly observed: ReadonlyMap<string, string>;
+}
+/**
+ * A tiny flow recorder capturing the named decider's decide() evidence as it
+ * fires — collected DURING the traversal, never reconstructed after. Rule
+ * labels are harvested for every rule the evidence lists (matched or not):
+ * a rule that was evaluated has spoken its label, whichever branch won.
+ *
+ * A decider inside a subflow (including a generated fan-out branch) reports
+ * itself PATH-PREFIXED (`per-subject~0/Protection posture`), so the match is
+ * on the LAST `/`-segment — the same last-delimiter reading every upstream
+ * parser of these paths uses, which is what keeps the generated-branch
+ * marker opaque here.
+ */
+export declare function meaningsRecorder(identity: DeciderIdentity): MeaningsHarvest;
+/** Compose the final meanings: declared branches first, observed rule labels
+ *  winning where both speak (the rule is the sharper sentence). Undefined
+ *  when neither source produced anything — absent, never `{}`. */
+export declare function composeMeanings(identity: DeciderIdentity, observed: ReadonlyMap<string, string>): Record<string, string> | undefined;
+//# sourceMappingURL=verdicts.d.ts.map

package/dist/types/core/runbook/verdicts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdicts.d.ts","sourceRoot":"","sources":["../../../../src/core/runbook/verdicts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,QAGoB,CAAC;AAErD;;yEAEyE;AACzE,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAE3C;4EAC4E;AAC5E,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,UAAU,EAAE,CAUpF;AAWD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAStE;AAgBD;oEACoE;AACpE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,CAyBjF;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CAkB3E;AAED;;kEAEkE;AAClE,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAKpC"}

package/dist/types/core/runbook/walk.d.ts

@@ -0,0 +1,73 @@
+/**
+ * runbook/walk — the recorded walk: projection law, counters, mint.
+ *
+ * Pattern: pure projection (`projectWalk`) + one guarded side effect
+ *          (`mintWalk`, which files the artifact and NEVER fails the answer).
+ * Role:    core/runbook. The walk is not a debugging extra — a procedure that
+ *          cannot show how it reached a verdict is a procedure somebody has
+ *          to take on trust.
+ * Emits:   nothing (the artifact capability emits its own `artifacts.*`).
+ *
+ * THE CAP LAW, and why a head slice is the wrong cap: in a chart walk the
+ * per-key reads and writes come FIRST and the decisions come LAST, so a
+ * naive head slice over a fleet sweep keeps four hundred writes and drops
+ * every decision — a walk with the walking taken out. When the whole thing
+ * does not fit, the CONTROL FLOW survives (stages, forks, subflows, and
+ * every `condition` entry carrying its decide() evidence) and the projection
+ * is DECLARED, so a reader knows which of the two they are holding.
+ */
+import type { ToolExecutionContext } from '../tools.js';
+import type { WalkDescriptor } from './types.js';
+/** The default row cap — a readable artifact, not an archive. The count is
+ *  always reported, so a truncated walk says it is truncated instead of
+ *  looking like a short run. */
+export declare const DEFAULT_WALK_CAP = 500;
+/** A narrative entry as this module reads it. `rawValue` is deliberately NOT
+ *  in the list: it is a LIVE reference into engine memory and has no business
+ *  in a value checked into an artifact store. */
+export interface NarrativeEntryView {
+    readonly type: string;
+    readonly text: string;
+    readonly depth: number;
+    readonly stageName?: string;
+    readonly stageId?: string;
+    readonly runtimeStageId?: string;
+    readonly subflowId?: string;
+}
+/** One walk row — plain data by construction (every field projected). */
+export interface WalkRow {
+    readonly step: number;
+    readonly type: string;
+    readonly depth: number;
+    readonly stage: string | null;
+    readonly stage_id: string | null;
+    readonly runtime_stage_id: string | null;
+    readonly subflow: string | null;
+    readonly text: string;
+}
+/** The pure projection result — rows plus truthful counters. */
+export interface ProjectedWalk {
+    readonly rows: readonly WalkRow[];
+    readonly projection: 'full' | 'control-flow';
+    readonly shown: number;
+    readonly total: number;
+    readonly complete: boolean;
+}
+/** Apply the cap law. Counters are about the WHOLE narrative (`total`), so a
+ *  projected walk cannot read as a short run. */
+export declare function projectWalk(entries: readonly NarrativeEntryView[], cap: number): ProjectedWalk;
+/** What the mint needs from the call. */
+export interface WalkMintFacts {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly runId?: string;
+    readonly stepsExecuted: number;
+}
+/**
+ * File the walk and build the descriptor. THE SPINE ALWAYS GETS A
+ * DESCRIPTOR: with no store attached, or when the mint fails, the counters
+ * still travel and the note names why there is no ticket — a failed mint
+ * costs the TICKET, never the answer and never the counts.
+ */
+export declare function mintWalk(ctx: ToolExecutionContext, projected: ProjectedWalk, facts: WalkMintFacts): Promise<WalkDescriptor>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/types/core/runbook/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../../../src/core/runbook/walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;gCAEgC;AAChC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;iDAEiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,yEAAyE;AACzE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAeD;iDACiD;AACjD,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAY9F;AAgBD,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,oBAAoB,EACzB,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,cAAc,CAAC,CA4CzB"}

package/dist/types/core/tools.d.ts

@@ -208,6 +208,41 @@ export interface Tool<TArgs = Record<string, unknown>, TResult = unknown> {
      * tool is never that check's subject, byte-identical.
      */
     readonly argumentsFrom?: readonly string[];
+    /**
+     * THE NAMED INGREDIENT TOOLS THIS TOOL IS COMPOSED OF (9.76.0) — the
+     * registered tools its body calls through the run's own dispatch
+     * (`ctx.tools`), declared by the author, never inferred.
+     *
+     * Consumer-side readers, which is what earns it a place here (the
+     * `resultKind` / `argumentsFrom` law — a declaration rails read, nothing
+     * that governs execution): the agent-build drift gate asserts every named
+     * ingredient is a registered tool, so a runbook whose inventory tool was
+     * renamed fails the BUILD by name instead of failing its first run; and it
+     * joins the MCP `_meta` declaration list so a composed tool served over the
+     * wire says what it is made of.
+     *
+     * Checked at AGENT BUILD, not at definition — the ingredients need not
+     * exist before this tool is defined, and the catalog is only complete once
+     * every `.tool()` registration has landed. Tools delivered by a
+     * `ToolProvider` are invisible to the check (there is no build-time list);
+     * with a provider configured the gate warns instead of refusing.
+     * Omitted → nothing is checked, byte-identical.
+     */
+    readonly composedOf?: readonly string[];
+    /**
+     * WHETHER THIS TOOL'S PROCEDURE CAN RAISE AN APPROVAL GATE (9.76.0) — a
+     * mid-run pause that asks a human before continuing. Declared, never
+     * inferred (the `capabilities` law): the framework cannot see through a
+     * tool boundary into an inner chart that gates.
+     *
+     * Consumer-side readers: composition-time checks that must refuse a gating
+     * tool where a pause cannot be resumed (a fan-out branch — the runbook
+     * grammar's compiler is the named reader). It does not govern execution;
+     * the runtime pause refusal remains the backstop for a tool that omits it.
+     * `false` is a declaration too ("this procedure never gates"), distinct
+     * from saying nothing. Omitted → byte-identical.
+     */
+    readonly gates?: boolean;
     /**
      * FINGERPRINT THE REPEATED-CALL LEDGER ON ARGUMENTS ALONE (9.62.0) —
      * `'arguments'` tells `core/agent/repeatedCall.ts` that this tool's own
@@ -349,6 +384,67 @@ export declare function assertToolOwner(toolName: string, owner: ToolOwner | und
  * on a declaration a remote server sent.
  */
 export declare function assertArgumentsFrom(toolName: string, argumentsFrom: readonly string[] | undefined): void;
+/**
+ * Refuse a `composedOf` list that could never be drift-checked, at definition
+ * time — the {@link assertArgumentsFrom} law applied to composition: the
+ * agent-build gate joins on these names, and a blank one — or a tool composed
+ * of itself — would join the wrong subjects or none. The REGISTRATION check
+ * (is every named ingredient actually registered?) deliberately does NOT
+ * happen here: the ingredients need not exist before this tool is defined,
+ * and only the agent build sees the complete catalog.
+ */
+export declare function assertComposedOf(toolName: string, composedOf: readonly string[] | undefined): void;
+/**
+ * Refuse a `gates` declaration that is not a boolean, at definition time.
+ * Trivial for anyone the compiler vets; load-bearing at the MCP ingest
+ * boundary, where a foreign server can put anything under the key and a
+ * truthy string would silently declare a gate nobody wrote.
+ */
+export declare function assertGates(toolName: string, gates: boolean | undefined): void;
+/** Options for one {@link ToolDispatch.call}. */
+export interface ToolDispatchCallOptions {
+    /** Abort signal for the inner call. Defaults to the outer call's own. */
+    readonly signal?: AbortSignal;
+    /**
+     * Declare an inner ABSENCE survivable (9.76.0). By default a dispatch
+     * consumer that composes answers (runbookAsTool) propagates an inner
+     * `absent()` as its own answer — "the inventory found nothing" IS the
+     * runbook's result, and pretending to a verdict over it would be the
+     * confident-partial-answer failure. Pass `true` when the caller can carry
+     * on without this source and will state the gap itself (usually as a
+     * coverage entry). The raw dispatch delivered on `ctx.tools` returns every
+     * result untouched either way — the propagation policy belongs to the
+     * consumer that wraps it.
+     */
+    readonly allowAbsent?: boolean;
+}
+/**
+ * The run's own tool dispatch, delivered at execute time as `ctx.tools`
+ * (9.76.0) — how one tool's body calls ANOTHER registered tool through the
+ * same map the model dispatches by, instead of importing its module and
+ * building a second query stack.
+ *
+ * What it sees: the agent's static catalog (`.tool()` registrations plus
+ * skill-carried tools) — the same dispatch map the tool-calls handler uses.
+ * Tools delivered by a `ToolProvider` are NOT visible (there is no build-time
+ * list), a stated caveat, not an accident.
+ *
+ * What an inner call gets: the outer call's own facts (credentials, signal,
+ * progress) with `hasArtifacts: false` — an inner tool must not mint claim
+ * tickets competing with the composed answer's own — and a derived
+ * `toolCallId` naming the outer call it belongs to. A declared `needs` is
+ * resolved before the inner execute (fail-closed: a service that requires
+ * interactive consent refuses by name — an inner call cannot pause).
+ */
+export interface ToolDispatch {
+    /** Is this name in the dispatch map? Provider-delivered tools answer false. */
+    has(name: string): boolean;
+    /**
+     * Execute a registered tool and return its result exactly as returned —
+     * a coverage envelope arrives as the envelope, an absence as the absence.
+     */
+    call(name: string, args: unknown, opts?: ToolDispatchCallOptions): Promise<unknown>;
+}
 /** Runtime context passed to tool.execute(). */
 export interface ToolExecutionContext {
     /** Unique id of THIS tool invocation (matches stream.tool_start.toolCallId). */
@@ -392,6 +488,15 @@ export interface ToolExecutionContext {
     /** The credential resolved for this tool's declared `needs` (declare-and-push).
      *  Present only when the tool declared a need and it resolved successfully. */
     readonly credential?: Credential;
+    /**
+     * The run's own tool dispatch (9.76.0) — see {@link ToolDispatch}. Present
+     * on the agent's dispatch paths; ABSENT at doors with no dispatch map
+     * (`mcpServe`, the offline trace context, a hand-built context in a test).
+     * Absent and empty are different facts: branch on the absence rather than
+     * optional-chaining past it, and prefer a fail-closed refusal (the
+     * `credentials` law) when your tool cannot work without it.
+     */
+    readonly tools?: ToolDispatch;
     /**
      * Report progress from INSIDE a long-running tool — "hop 3 of 12 done", said
      * mid-`execute`, while the call is still running.
@@ -575,6 +680,13 @@ export interface DefineToolOptions<TArgs, TResult> {
     readonly owner?: ToolOwner;
     /** The declared argument grounds — see {@link Tool.argumentsFrom}. */
     readonly argumentsFrom?: readonly string[];
+    /** The named ingredient tools this tool calls through `ctx.tools` — see
+     *  {@link Tool.composedOf}. Drift-checked at agent build, when the catalog
+     *  is complete. Omitted → nothing checked, byte-identical. */
+    readonly composedOf?: readonly string[];
+    /** Whether this tool's procedure can raise an approval gate — see
+     *  {@link Tool.gates}. Omitted → nothing declared, byte-identical. */
+    readonly gates?: boolean;
     /** Fingerprint the repeated-call ledger on arguments alone, ignoring this
      *  tool's own result — see {@link Tool.repeatedWhen}. Omitted →
      *  byte-identical (the ledger keeps comparing results, as always). */

package/dist/types/core/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"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"}

package/dist/types/events/payloads.d.ts

@@ -1791,6 +1791,45 @@ export interface AgentEvidenceCheckedPayload {
      *  tool result. The gate then records its verdict WITHOUT acting on it —
      *  a partial corpus can call a grounded value fabricated. */
     readonly evidenceTruncated?: boolean;
+    /**
+     * On `action: 'revision-asked'` only, and only when the turn held placed
+     * artifact tickets a served `wants` tool can spend: the refs the
+     * correction NAMED as the route to a grounded number. Absent otherwise —
+     * including for every agent without a `wants`-declaring tool.
+     */
+    readonly stagedRefs?: readonly {
+        readonly ref: string;
+        readonly kind: string;
+    }[];
+    /** The spender tools the correction named, beside {@link stagedRefs}. */
+    readonly spenderTools?: readonly string[];
+}
+/**
+ * The staged-refs nudge fired (`.namesAndNumbersFromEvidence({ nudge: true })`)
+ * — one per iteration whose request gained the late line naming staged
+ * artifact refs and the `wants` tool that spends them.
+ *
+ * The line itself is request-only (never history), so this event is the ONE
+ * record that it existed: which refs, which spenders, which iteration. A run
+ * where the nudge never armed emits none of these.
+ */
+export interface AgentGroundingNudgedPayload {
+    /** The ReAct iteration whose request carried the line. */
+    readonly iteration: number;
+    /** The staged refs the line named — `ref` verbatim, `kind` as minted
+     *  (`Tool.resultKind` / `tool-result/<toolName>`). Capped; see
+     *  {@link refsOmitted}. */
+    readonly refs: readonly {
+        readonly ref: string;
+        readonly kind: string;
+    }[];
+    /** Matched refs beyond the cap, stated rather than silently dropped.
+     *  Absent when every match was named. */
+    readonly refsOmitted?: number;
+    /** The spender tools named, by their registered names — the tools whose
+     *  declared `wants` matched a staged ref's kind, exact-string, never by
+     *  tool name. */
+    readonly tools: readonly string[];
 }
 /**
  * The model this run STARTS with, and what may replace it mid-run.