agentfootprint 9.74.0 → 9.76.0

package/dist/esm/core/runbook/types.js

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/core/runbook/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/runbook/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

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

@@ -0,0 +1,78 @@
+/**
+ * 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;

package/dist/esm/core/runbook/verdicts.js

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ */
+/** Default cap on `verdicts` rows and the rendered table. */
+export const DEFAULT_MAX_ROWS = 50;
+/** The render law, stated to the model beside every table. */
+export const VERDICT_RENDER_NOTE = 'table is PRE-RENDERED over the same rows as `verdicts` — output it VERBATIM. Never ' +
+    'retype an identifier from `verdicts`; a transcribed name that looks right and matches ' +
+    'nothing is the failure this note exists to stop.';
+/** 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 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 function verdictRowsOf(state) {
+    const raw = state.verdicts;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((row) => row !== null &&
+        typeof row === 'object' &&
+        !Array.isArray(row) &&
+        typeof row.verdict === 'string');
+}
+/** The one place a `—` is written for a value the source did not report — a
+ *  blank cell reads as a zero; a dash reads as "not reported". */
+function cell(value) {
+    if (value === null || value === undefined || value === '')
+        return '—';
+    if (value === true)
+        return 'yes';
+    if (value === false)
+        return 'no';
+    return String(value).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+/**
+ * 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 function renderVerdictTable(rows) {
+    if (rows.length === 0)
+        return 'No rows in the projected set.';
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const columns = Object.keys(rows[0]);
+    const head = `| ${columns.join(' | ')} |\n|${columns.map(() => '---').join('|')}|\n`;
+    return (head +
+        rows.map((row) => `| ${columns.map((column) => cell(row[column])).join(' | ')} |`).join('\n'));
+}
+/**
+ * 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 function resolveDecider(chart, decider) {
+    const spellings = new Set([decider]);
+    const declared = new Map();
+    const visited = new Set();
+    const walk = (node) => {
+        if (node === undefined || node.isLoopRef === true || visited.has(node))
+            return;
+        visited.add(node);
+        if ((node.id === decider || node.name === decider) && (node.children?.length ?? 0) > 0) {
+            if (node.id !== undefined)
+                spellings.add(node.id);
+            if (node.name !== undefined)
+                spellings.add(node.name);
+            for (const child of node.children ?? []) {
+                const branch = child.branchId ?? child.id;
+                if (branch === undefined)
+                    continue;
+                const meaning = child.description ?? child.name;
+                if (meaning !== undefined && !declared.has(branch))
+                    declared.set(branch, meaning);
+            }
+        }
+        for (const child of node.children ?? [])
+            walk(child);
+        walk(node.next);
+    };
+    walk(chart.root);
+    for (const subflow of Object.values(chart.subflows ?? {})) {
+        walk(subflow.root);
+    }
+    return { spellings, declared };
+}
+/**
+ * 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 function meaningsRecorder(identity) {
+    const observed = new Map();
+    const lastSegment = (path) => path.slice(path.lastIndexOf('/') + 1);
+    const recorder = {
+        id: 'runbook-verdict-meanings',
+        onDecision(event) {
+            if (!identity.spellings.has(lastSegment(event.decider)))
+                return;
+            const evidence = event.evidence;
+            for (const rule of evidence?.rules ?? []) {
+                if (typeof rule.branch === 'string' && typeof rule.label === 'string') {
+                    observed.set(rule.branch, rule.label);
+                }
+            }
+        },
+    };
+    return { recorder, observed };
+}
+/** 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 function composeMeanings(identity, observed) {
+    const meanings = {};
+    for (const [branch, meaning] of identity.declared)
+        meanings[branch] = meaning;
+    for (const [branch, label] of observed)
+        meanings[branch] = label;
+    return Object.keys(meanings).length > 0 ? meanings : undefined;
+}
+//# sourceMappingURL=verdicts.js.map

package/dist/esm/core/runbook/verdicts.js.map

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

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

@@ -0,0 +1,72 @@
+/**
+ * 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>;

package/dist/esm/core/runbook/walk.js

@@ -0,0 +1,110 @@
+/**
+ * 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 { CHART_WALK_ARTIFACT_KIND, chartWalkPutInput } from '../../artifacts/recordingArtifact.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 const DEFAULT_WALK_CAP = 500;
+function toWalkRow(entry, step) {
+    return {
+        step,
+        type: entry.type,
+        depth: entry.depth,
+        stage: entry.stageName ?? null,
+        stage_id: entry.stageId ?? null,
+        runtime_stage_id: entry.runtimeStageId ?? null,
+        subflow: entry.subflowId ?? null,
+        text: entry.text,
+    };
+}
+/** Apply the cap law. Counters are about the WHOLE narrative (`total`), so a
+ *  projected walk cannot read as a short run. */
+export function projectWalk(entries, cap) {
+    const full = entries.length <= cap;
+    const projection = full ? 'full' : 'control-flow';
+    const chosen = full ? entries : entries.filter((entry) => entry.type !== 'step');
+    const rows = chosen.slice(0, cap).map(toWalkRow);
+    return {
+        rows,
+        projection,
+        shown: rows.length,
+        total: entries.length,
+        complete: rows.length === entries.length,
+    };
+}
+/** The descriptor's standing sentence, plus the projection clause when the
+ *  control flow is what survived. */
+function walkNote(projection) {
+    return ("The chart's own walk, one row per execution step. The `condition` rows carry the " +
+        'rule that matched, the values it compared and the branch it chose — that is where a ' +
+        'verdict can be checked rather than taken on trust.' +
+        (projection === 'control-flow'
+            ? ' This one is the CONTROL-FLOW projection: the walk did not fit, so the stages, ' +
+                'forks, subflows and decisions are here and the per-key reads and writes are not.'
+            : ''));
+}
+/**
+ * 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 async function mintWalk(ctx, projected, facts) {
+    const base = {
+        rows: projected.rows.length,
+        steps_executed: facts.stepsExecuted,
+        projection: projected.projection,
+        shown: projected.shown,
+        total: projected.total,
+        complete: projected.complete,
+        walk_segment: 'full',
+    };
+    if (!ctx.hasArtifacts || projected.rows.length === 0) {
+        return {
+            ...base,
+            note: projected.rows.length === 0
+                ? 'The run produced no narrative entries, so there was no walk to file.'
+                : walkNote(projected.projection) +
+                    ' No artifact store is attached to this run, so the walk was recorded but not ' +
+                    'filed — the counters above are still the truth about it.',
+        };
+    }
+    try {
+        const meta = await ctx.artifacts.put(chartWalkPutInput([...projected.rows], {
+            toolName: facts.toolName,
+            toolCallId: facts.toolCallId,
+            ...(facts.runId !== undefined && { runId: facts.runId }),
+        }));
+        return {
+            ref: meta.ref,
+            kind: CHART_WALK_ARTIFACT_KIND,
+            ...base,
+            note: walkNote(projected.projection),
+        };
+    }
+    catch (err) {
+        return {
+            ...base,
+            note: walkNote(projected.projection) +
+                ` The walk could not be filed (${err instanceof Error ? err.message : String(err)}) — ` +
+                'the mint failure cost the ticket, never the answer.',
+        };
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/esm/core/runbook/walk.js.map

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

package/dist/esm/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). */