agentfootprint 2.11.1 → 2.11.2

package/dist/types/core/agent/AgentBuilder.d.ts

@@ -0,0 +1,348 @@
+/**
+ * AgentBuilder — fluent builder for Agent. Extracted from Agent.ts in
+ * v2.11.2 as part of the core/agent decomposition. Same surface, same
+ * behavior; just lives in its own file for readability.
+ *
+ * Re-exported by Agent.ts so external consumers importing
+ * `AgentBuilder` from `'../core/Agent.js'` continue to work.
+ */
+import { type OutputSchemaOptions, type OutputSchemaParser } from '../outputSchema.js';
+import { type OutputFallbackOptions } from '../outputFallback.js';
+import type { CachePolicy } from '../../cache/types.js';
+import type { Injection } from '../../lib/injection-engine/types.js';
+import type { MemoryDefinition } from '../../memory/define.types.js';
+import type { Tool } from '../tools.js';
+import type { ToolProvider } from '../../tool-providers/types.js';
+import { Agent } from '../Agent.js';
+import type { AgentOptions } from './types.js';
+/**
+ * Fluent builder. `tool()` accepts any Tool<TArgs, TResult> and registers
+ * it by its schema.name. Duplicate names throw at build time.
+ */
+export declare class AgentBuilder {
+    private readonly opts;
+    private systemPromptValue;
+    /**
+     * Cache policy for the base system prompt. Set via the optional
+     * 2nd argument to `.system(text, { cache })`. Default `'always'` —
+     * the base prompt is stable per-turn and an ideal cache anchor.
+     */
+    private systemPromptCachePolicy;
+    /**
+     * Global cache kill switch. Set via `Agent.create({ caching: 'off' })`
+     * (handled in `AgentOptions` propagation). Defaults to `false`
+     * (caching enabled). When `true`, the CacheGate decider routes to
+     * `'no-markers'` every iteration regardless of other rules.
+     */
+    private cachingDisabledValue;
+    /**
+     * Optional explicit CacheStrategy override. Default: undefined,
+     * which means the agent auto-resolves from
+     * `getDefaultCacheStrategy(provider.name)` at construction. Power
+     * users override here for custom backends or test mocks.
+     */
+    private cacheStrategyOverride?;
+    private readonly registry;
+    private readonly injectionList;
+    private readonly memoryList;
+    /**
+     * Optional terminal contract — see `outputSchema()`. Stored on the
+     * builder, propagated to the Agent at `.build()` time.
+     */
+    private outputSchemaParser?;
+    /** 3-tier output fallback chain — set via `.outputFallback({...})`.
+     *  Optional; absent = current throw-on-validation-failure behavior. */
+    private outputFallbackCfg?;
+    /**
+     * Optional `ToolProvider` set via `.toolProvider()`. Propagated to
+     * the Agent's Tools slot subflow + tool-call dispatcher; consulted
+     * per iteration so dynamic chains (`gatedTools`, `skillScopedTools`)
+     * react to current activation state.
+     */
+    private toolProviderRef?;
+    /**
+     * Optional override for `AgentOptions.maxIterations`. When set via
+     * the `.maxIterations()` builder method, takes precedence over the
+     * value passed to `Agent.create({ maxIterations })`.
+     */
+    private maxIterationsOverride?;
+    /**
+     * Recorders collected via `.recorder()`. Attached to the built Agent
+     * before `build()` returns (each via `agent.attach(rec)`).
+     */
+    private readonly recorderList;
+    private appNameValue;
+    private commentaryOverrides;
+    private thinkingOverrides;
+    constructor(opts: AgentOptions);
+    /**
+     * Set the base system prompt.
+     *
+     * @param prompt - The system prompt text. Stable per-turn.
+     * @param options - Optional config. `cache` controls how the
+     *   CacheDecision subflow treats this prompt block:
+     *   - `'always'` (default) — cache the base prompt as a stable
+     *     prefix anchor. Highest cache-hit rate; recommended for
+     *     production agents whose system prompt rarely changes.
+     *   - `'never'` — skip caching. Use if the prompt contains volatile
+     *     content (timestamps, per-request user IDs).
+     *   - `'while-active'` — semantically equivalent to `'always'` for
+     *     the base prompt (it's always active by definition).
+     *   - `{ until }` — conditional invalidation (e.g., flush after iter 5).
+     */
+    system(prompt: string, options?: {
+        readonly cache?: CachePolicy;
+    }): this;
+    tool<TArgs, TResult>(tool: Tool<TArgs, TResult>): this;
+    /**
+     * Register many tools at once. Convenience for tool sources that
+     * return a list (e.g., `await mcpClient(...).tools()`). Each tool
+     * is registered via `.tool()` so duplicate-name validation still
+     * fires per-entry.
+     */
+    tools(tools: ReadonlyArray<Tool>): this;
+    /**
+     * Wire a chainable `ToolProvider` (from `agentfootprint/tool-providers`)
+     * as the agent's per-iteration tool source.
+     *
+     * The provider is consulted EVERY iteration via `provider.list(ctx)`
+     * with `ctx = { iteration, activeSkillId, identity }`. Tools the
+     * provider emits flow into the Tools slot alongside any static
+     * tools registered via `.tool()` / `.tools()`. The tool-call
+     * dispatcher also consults the provider so dynamic chains
+     * (`gatedTools`, `skillScopedTools`) dispatch correctly when their
+     * visible-set changes mid-turn.
+     *
+     * Throws if called more than once on the same builder (avoids
+     * silent override surprises).
+     *
+     * @example  Permission-gated baseline
+     *   import { gatedTools, staticTools } from 'agentfootprint/tool-providers';
+     *   import { PermissionPolicy } from 'agentfootprint/security';
+     *
+     *   const policy = PermissionPolicy.fromRoles({
+     *     readonly: ['lookup', 'list_skills', 'read_skill'],
+     *     admin:    ['lookup', 'list_skills', 'read_skill', 'delete'],
+     *   }, 'readonly');
+     *
+     *   const provider = gatedTools(
+     *     staticTools(allTools),
+     *     (toolName) => policy.isAllowed(toolName),
+     *   );
+     *
+     *   const agent = Agent.create({ provider: llm, model })
+     *     .system('You answer.')
+     *     .toolProvider(provider)
+     *     .build();
+     */
+    toolProvider(provider: ToolProvider): this;
+    /**
+     * Override the ReAct iteration cap set via `Agent.create({
+     * maxIterations })`. Convenience for builder-style code that prefers
+     * fluent setters over constructor opts. Last call wins.
+     *
+     * Throws if `n` is not a positive integer or exceeds the hard cap
+     * (`clampIterations`'s upper bound).
+     */
+    maxIterations(n: number): this;
+    /**
+     * Attach a footprintjs `CombinedRecorder` to the built Agent. Wired
+     * via `agent.attach(rec)` immediately after construction, so the
+     * recorder sees every event from the very first run.
+     *
+     * Equivalent to calling `agent.attach(rec)` post-build; the builder
+     * method is a convenience for codebases that prefer fully-fluent
+     * agent assembly. Multiple recorders are supported (each gets its
+     * own `attach()` call).
+     */
+    recorder(rec: import('footprintjs').CombinedRecorder): this;
+    /**
+     * Set the agent's display name — substituted as `{{appName}}` in
+     * commentary + thinking templates. Same place to brand a tenant
+     * ("Acme Bot"), distinguish multi-agent roles ("Triage" vs
+     * "Reviewer"), or localize ("Asistente"). Default: `'Chatbot'`.
+     */
+    appName(name: string): this;
+    /**
+     * Override agentfootprint's bundled commentary templates. Spread on
+     * top of `defaultCommentaryTemplates`; missing keys fall back. Same
+     * `Record<string, string>` shape with `{{vars}}` substitution as
+     * the bundled defaults — see `defaultCommentaryTemplates` for the
+     * full key list.
+     *
+     * Use cases: i18n (`'agent.turn_start': 'El usuario...'`), brand
+     * voice ("You: {{userPrompt}}"), per-tenant customization.
+     */
+    commentaryTemplates(templates: Readonly<Record<string, string>>): this;
+    /**
+     * Override agentfootprint's bundled thinking templates. Same
+     * contract shape as commentary; different vocabulary — first-person
+     * status the chat bubble shows mid-call. Per-tool overrides go via
+     * `tool.<toolName>` keys (e.g., `'tool.weather': 'Looking up the
+     * weather…'`). See `defaultThinkingTemplates` for the full key list.
+     */
+    thinkingTemplates(templates: Readonly<Record<string, string>>): this;
+    /**
+     * Register any `Injection`. Use this for power-user / custom flavors;
+     * for built-in flavors use the typed sugar (`.skill`, `.steering`,
+     * `.instruction`, `.fact`).
+     */
+    injection(injection: Injection): this;
+    /**
+     * Register a Skill — LLM-activated, system-prompt + tools.
+     * Auto-attaches the `read_skill` activation tool to the agent.
+     * Skill stays active for the rest of the turn once activated.
+     */
+    skill(injection: Injection): this;
+    /**
+     * Bulk-register every Skill in a `SkillRegistry`. Use for shared
+     * skill catalogs across multiple Agents — register skills once on
+     * the registry; attach the same registry to every consumer Agent.
+     *
+     * @example
+     *   const registry = new SkillRegistry();
+     *   registry.register(billingSkill).register(refundSkill);
+     *   const supportAgent = Agent.create({ provider }).skills(registry).build();
+     *   const escalationAgent = Agent.create({ provider }).skills(registry).build();
+     */
+    skills(registry: {
+        list(): readonly Injection[];
+    }): this;
+    /**
+     * Register a Steering doc — always-on system-prompt rule.
+     * Use for invariant guidance: output format, persona, safety policies.
+     */
+    steering(injection: Injection): this;
+    /**
+     * Register an Instruction — rule-based system-prompt guidance.
+     * Predicate runs each iteration. Use for context-dependent rules
+     * including the "Dynamic ReAct" `on-tool-return` pattern.
+     */
+    instruction(injection: Injection): this;
+    /**
+     * Bulk-register many instructions at once. Convenience for consumer
+     * code that organizes its instruction set in a flat array (`const
+     * instructions = [outputFormat, dataRouting, ...]`). Each element
+     * is registered via `.instruction()` so duplicate-id checks still
+     * fire per-entry.
+     */
+    instructions(injections: ReadonlyArray<Injection>): this;
+    /**
+     * Register a Fact — developer-supplied data the LLM should see.
+     * User profile, env info, computed summary, current time, …
+     * Distinct from Skills (LLM-activated guidance) and Steering
+     * (always-on rules) in INTENT — the engine treats them all alike.
+     */
+    fact(injection: Injection): this;
+    /**
+     * Register a Memory subsystem — load/persist conversation context,
+     * facts, narrative beats, or causal snapshots across runs.
+     *
+     * The `MemoryDefinition` is produced by `defineMemory({ type, strategy,
+     * store })`. Multiple memories layer cleanly via per-id scope keys
+     * (`memoryInjection_${id}`):
+     *
+     * ```ts
+     * Agent.create({ provider })
+     *   .memory(defineMemory({ id: 'short', type: MEMORY_TYPES.EPISODIC,
+     *                          strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 },
+     *                          store }))
+     *   .memory(defineMemory({ id: 'facts', type: MEMORY_TYPES.SEMANTIC,
+     *                          strategy: { kind: MEMORY_STRATEGIES.EXTRACT,
+     *                                      extractor: 'pattern' }, store }))
+     *   .build();
+     * ```
+     *
+     * The READ subflow runs at the configured `timing` (default
+     * `MEMORY_TIMING.TURN_START`) and writes its formatted output to the
+     * `memoryInjection_${id}` scope key for the slot subflows to consume.
+     */
+    memory(definition: MemoryDefinition): this;
+    /**
+     * Register a RAG retriever — semantic search over a vector-indexed
+     * corpus. Identical plumbing to `.memory()` (RAG resolves to a
+     * `MemoryDefinition` produced by `defineRAG()`); this alias exists
+     * so the consumer's intent reads clearly:
+     *
+     * ```ts
+     * agent
+     *   .memory(shortTermConversation)   // remembers what the USER said
+     *   .rag(productDocs)                // retrieves what the CORPUS says
+     *   .build();
+     * ```
+     *
+     * Both end up as memory subflows, but the alias separates "user
+     * conversation memory" from "document corpus retrieval" in code
+     * intent, ids, and Lens chips.
+     */
+    rag(definition: MemoryDefinition): this;
+    /**
+     * Declarative terminal contract. The agent's final answer must be
+     * JSON matching `parser`. Auto-injects a system-prompt instruction
+     * telling the LLM the shape, and exposes `agent.runTyped()` /
+     * `agent.parseOutput()` for parse + validate at the call site.
+     *
+     * The `parser` is duck-typed: any object with a `parse(unknown): T`
+     * method works (Zod, Valibot, ArkType, hand-written). The optional
+     * `description` field on the parser drives the auto-generated
+     * instruction; consumers can also override via `opts.instruction`.
+     *
+     * Throws if called more than once on the same builder (avoids
+     * silent override surprises).
+     *
+     * @param parser  Validation strategy that throws on shape failure.
+     * @param opts    Optional `{ name, instruction }` to customize.
+     *
+     * @example
+     *   import { z } from 'zod';
+     *   const Output = z.object({
+     *     status: z.enum(['ok', 'err']),
+     *     items: z.array(z.string()),
+     *   }).describe('A status enum + an array of strings.');
+     *
+     *   const agent = Agent.create({...})
+     *     .outputSchema(Output)
+     *     .build();
+     *
+     *   const typed = await agent.runTyped({ message: '...' });
+     *   typed.status; // narrowed to 'ok' | 'err'
+     */
+    outputSchema<T>(parser: OutputSchemaParser<T>, opts?: OutputSchemaOptions): this;
+    /**
+     * 3-tier degradation for output-schema validation failures. Pairs
+     * with `.outputSchema()` — calling `.outputFallback()` without an
+     * `outputSchema` first throws (the fallback has nothing to validate).
+     *
+     * Three tiers:
+     *
+     *   1. **Primary** — LLM emitted schema-valid JSON. Caller gets it.
+     *   2. **Fallback** — `OutputSchemaError` thrown. The async
+     *      `fallback(error, raw)` runs; its return is re-validated.
+     *   3. **Canned** — static safety-net value. NEVER throws when set.
+     *
+     * `canned` is validated against the schema at builder time —
+     * fail-fast on misconfig (a `canned` that doesn't validate would
+     * defeat the fail-open guarantee).
+     *
+     * Two typed events fire on tier transitions for observability:
+     *   - `agentfootprint.resilience.output_fallback_triggered`
+     *   - `agentfootprint.resilience.output_canned_used`
+     *
+     * @example
+     * ```ts
+     * import { z } from 'zod';
+     * const Refund = z.object({ amount: z.number(), reason: z.string() });
+     *
+     * const agent = Agent.create({...})
+     *   .outputSchema(Refund)
+     *   .outputFallback({
+     *     fallback: async (err, raw) => ({ amount: 0, reason: 'manual review' }),
+     *     canned:   { amount: 0, reason: 'unable to process' },
+     *   })
+     *   .build();
+     * ```
+     */
+    outputFallback<T>(options: OutputFallbackOptions<T>): this;
+    build(): Agent;
+}
+//# sourceMappingURL=AgentBuilder.d.ts.map

package/dist/types/core/agent/AgentBuilder.d.ts.map

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

package/dist/types/core/agent/buildAgentChart.d.ts

@@ -0,0 +1,74 @@
+/**
+ * buildAgentChart — assemble the agent's full footprintjs FlowChart
+ * from stage functions + slot subflows + memory wiring.
+ *
+ * This is the "chart composition" that used to live inline in
+ * `Agent.buildChart()`. Extracted for v2.11.2 so:
+ *
+ *   1. Agent.ts focuses on Agent class lifecycle (constructor, run,
+ *      attach, getSpec) instead of chart wiring details.
+ *   2. The reliability gate chart (v2.11.x) wires into ONE focused
+ *      file rather than surgically into Agent.ts's 250-line composition
+ *      block.
+ *   3. The composition is independently readable + reviewable —
+ *      consumers building custom agent shapes have a reference.
+ *
+ * Chart shape:
+ *
+ *     Seed
+ *       → [memory READ subflows for each .memory()]
+ *       → InjectionEngine (subflow)
+ *       → SystemPrompt (slot subflow)
+ *       → Messages (slot subflow)
+ *       → Tools (slot subflow)
+ *       → CacheDecision (subflow)
+ *       → UpdateSkillHistory
+ *       → CacheGate (decider) → ApplyMarkers / SkipCaching
+ *       → IterationStart
+ *       → CallLLM
+ *       → Route (decider) → tool-calls (pausable) / final (subflow)
+ *                                                        |
+ *                          ┌────── PrepareFinal           ▼
+ *                          ├──── [memory WRITE subflows]
+ *                          └──── BreakFinal ($break)
+ *       loopTo(InjectionEngine)
+ *
+ * (When v2.11.x reliability is configured, the reliability gate chart
+ * mounts as a subflow between IterationStart and CallLLM with a
+ * TranslateFailFast stage after it. Lands in the next commit.)
+ */
+import type { FlowChart } from 'footprintjs';
+import type { CachePolicy } from '../../cache/types.js';
+import type { MemoryDefinition } from '../../memory/define.types.js';
+/**
+ * Stage handlers + slot subflows the chart composer needs. Mostly
+ * passed through verbatim from Agent.buildChart() — the chart shape
+ * is identical to what was inline before.
+ */
+export interface AgentChartDeps {
+    /** Memory READ/WRITE pipeline definitions (one per `.memory()`). */
+    readonly memories: readonly MemoryDefinition[];
+    /** Cache policy for the system-prompt slot, threaded into
+     *  CacheDecision's inputMapper so its decision rules can match. */
+    readonly systemPromptCachePolicy: CachePolicy;
+    /** Hard ReAct iteration cap, threaded into CacheDecision's
+     *  inputMapper for max-iteration policies. */
+    readonly maxIterations: number;
+    readonly seed: (scope: never) => void;
+    readonly iterationStart: (scope: never) => void;
+    readonly callLLM: (scope: never) => Promise<void>;
+    readonly routeDecider: (scope: never) => 'tool-calls' | 'final';
+    readonly toolCallsHandler: import('footprintjs').PausableHandler<never>;
+    readonly injectionEngineSubflow: FlowChart;
+    readonly systemPromptSubflow: FlowChart;
+    readonly messagesSubflow: FlowChart;
+    readonly toolsSubflow: FlowChart;
+    readonly cacheDecisionSubflow: FlowChart;
+    readonly updateSkillHistoryStage: (scope: never) => void;
+    readonly cacheGateDecide: (scope: never) => unknown;
+}
+/**
+ * Build the agent's complete FlowChart from the supplied deps.
+ */
+export declare function buildAgentChart(deps: AgentChartDeps): FlowChart;
+//# sourceMappingURL=buildAgentChart.d.ts.map

package/dist/types/core/agent/buildAgentChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAQrE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAE/C;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAE9C;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,GAAG,OAAO,CAAC;IAChE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAGxE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,CAAC;IAC3C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IAGjC,QAAQ,CAAC,oBAAoB,EAAE,SAAS,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACzD,QAAQ,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CACrD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CA+N/D"}

package/dist/types/core/agent/buildToolRegistry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * buildToolRegistry — pure function that composes the agent's
+ * augmented tool registry from three sources:
+ *
+ *   1. **Static registry** — tools registered via `.tool()`. Always
+ *      visible to the LLM; always executable.
+ *   2. **`read_skill`** — auto-attached when ≥1 Skill is registered.
+ *      Activation tool for LLM-guided Skills.
+ *   3. **Skill-supplied tools** (`Skill.inject.tools[]`) — visible
+ *      only when the Skill is active (filtered by tools-slot subflow);
+ *      MUST always be in the executor registry so when the LLM calls
+ *      one, the tool-calls handler can dispatch.
+ *
+ * Tool-name uniqueness is enforced across all three sources at build
+ * time. The LLM only sees `tool.schema.name` (no ids), so names ARE
+ * the runtime dispatch key — collisions break the LLM's ability to
+ * call the right tool. Throw early instead of subtly shadowing.
+ *
+ * **Block C runtime — `autoActivate: 'currentSkill'` semantics:**
+ * When a skill's `defineSkill({ autoActivate: 'currentSkill' })` is
+ * set, its tools are EXCLUDED from the static registry. They flow
+ * into the LLM's tool list ONLY through `dynamicSchemas` (the
+ * buildToolsSlot path that reads activeInjections), which means
+ * they're visible ONLY on iterations after the skill is activated by
+ * `read_skill('id')`. Without this, the LLM sees every skill's tools
+ * on every iteration and the per-skill-narrowing autoActivate
+ * promised in `defineSkill` doesn't actually narrow anything. Skills
+ * WITHOUT autoActivate keep the v2.4 behavior (tools always visible)
+ * for back-compat.
+ *
+ * **autoActivate dispatch invariant:** autoActivate skill tools live
+ * OUTSIDE the LLM-visible registry (so they don't pollute the
+ * per-iteration tool list before the skill activates), but they MUST
+ * still be findable by the dispatch handler — the LLM calls them by
+ * name once the skill is active, and dispatch looks up by name. We
+ * add them to the dispatch map (`registryByName`) so `lookupTool`
+ * resolves correctly.
+ */
+import type { Injection } from '../../lib/injection-engine/types.js';
+import type { LLMToolSchema } from '../../adapters/types.js';
+import type { Tool, ToolRegistryEntry } from '../tools.js';
+export interface ToolRegistryArtifacts {
+    /** All tools the LLM sees in the static portion of its tool list
+     *  (registry + read_skill + non-autoActivate skill tools). */
+    readonly augmentedRegistry: readonly ToolRegistryEntry[];
+    /** Dispatch map by name — used by the tool-calls handler at run
+     *  time to resolve a tool the LLM called. INCLUDES autoActivate
+     *  skill tools (which aren't in `augmentedRegistry`) so dispatch
+     *  works once the skill is active. */
+    readonly registryByName: ReadonlyMap<string, Tool>;
+    /** Static tool schemas for the LLM call. Mirrors `augmentedRegistry`
+     *  shape; passed to `buildToolsSlot` + the seed stage as the
+     *  per-iteration default before the dynamic tools slot has run. */
+    readonly toolSchemas: readonly LLMToolSchema[];
+}
+/**
+ * Compose the augmented tool registry from the static `.tool()`
+ * registry + the agent's injections (skills only). Throws on tool-
+ * name collisions across sources.
+ */
+export declare function buildToolRegistry(registry: readonly ToolRegistryEntry[], injections: readonly Injection[]): ToolRegistryArtifacts;
+//# sourceMappingURL=buildToolRegistry.d.ts.map

package/dist/types/core/agent/buildToolRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildToolRegistry.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildToolRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC;kEAC8D;IAC9D,QAAQ,CAAC,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACzD;;;0CAGsC;IACtC,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnD;;uEAEmE;IACnE,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,qBAAqB,CA4EvB"}

package/dist/types/core/agent/stages/breakFinal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * breakFinal — terminal stage of the agent's "Final" branch subflow.
+ *
+ * Fires after the (optional) memory-write subflows have persisted the
+ * (user, assistant) pair. `$break()` stops execution before the outer
+ * loopTo can re-enter the ReAct loop, ending the iteration cleanly.
+ * Returns `scope.finalContent` so the parent's `outputMapper` can
+ * surface it as the agent's response.
+ *
+ * Mounted in the final-branch subflow (built in `buildAgentChart`) as
+ * the LAST stage. The parent agent chart mounts the final-branch
+ * subflow under the Route decider's `'final'` branch with
+ * `propagateBreak: true`, so this $break terminates the outer ReAct
+ * loop too.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../types.js';
+/**
+ * Pure stage function — no dependencies, no closure over Agent state.
+ * Exported as a const, not a factory, since there's nothing to inject.
+ */
+export declare const breakFinalStage: (scope: TypedScope<AgentState>) => string;
+//# sourceMappingURL=breakFinal.d.ts.map

package/dist/types/core/agent/stages/breakFinal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakFinal.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/breakFinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,eAAe,UAAW,WAAW,UAAU,CAAC,KAAG,MAG/D,CAAC"}

package/dist/types/core/agent/stages/callLLM.d.ts

@@ -0,0 +1,54 @@
+/**
+ * callLLM — the LLM-invocation stage of the agent's chart.
+ *
+ * Reads the assembled prompt + messages from scope (populated by the
+ * upstream slot subflows: SystemPrompt, Messages, Tools, CacheDecision,
+ * CacheGate). Calls `provider.stream()` if available (token streaming
+ * with per-chunk events) else falls back to `provider.complete()`.
+ * Writes the response to scope (`llmLatestContent`, `llmLatestToolCalls`,
+ * cumulative tokens) for the downstream Route decider to read.
+ *
+ * Emits `agentfootprint.stream.llm_start` + `llm_end` brackets for
+ * observability adapters and per-chunk `stream.token` events during
+ * streaming. Emits `cost.tick` via `emitCostTick` when a `pricingTable`
+ * is configured.
+ *
+ * Factory signature so the chart-build-time provider/model/etc. deps
+ * are explicit. The `toolSchemas` value is late-bound via a getter
+ * because tool schema composition completes after the seed factory is
+ * built but before the chart actually runs.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { LLMProvider, LLMToolSchema, PricingTable } from '../../../adapters/types.js';
+import type { CacheStrategy } from '../../../cache/types.js';
+import type { AgentState } from '../types.js';
+export interface CallLLMStageDeps {
+    /** The LLM provider to invoke. */
+    readonly provider: LLMProvider;
+    /** Model identifier passed to provider.complete/stream. */
+    readonly model: string;
+    /** Optional sampling temperature. */
+    readonly temperature?: number;
+    /** Optional max output tokens. */
+    readonly maxTokens?: number;
+    /** Optional pricing adapter for cost tracking. */
+    readonly pricingTable?: PricingTable;
+    /** Optional cumulative USD cap per run. */
+    readonly costBudget?: number;
+    /** Hard ReAct iteration cap (used to compute iterationsRemaining for
+     *  the cache strategy's prepareRequest hook). */
+    readonly maxIterations: number;
+    /** Cache strategy (provider-aware; v2.6+). Pass-through if no markers. */
+    readonly cacheStrategy: CacheStrategy;
+    /** Static tool schemas, late-bound (see seed.ts for the same
+     *  pattern — toolSchemas is computed AFTER stage factories are
+     *  built). The getter resolves the eventual value at run time. */
+    readonly toolSchemas: readonly LLMToolSchema[];
+}
+/**
+ * Build the callLLM stage function. Captures the LLM provider + model
+ * config + cache strategy via the deps object; everything per-iteration
+ * comes from scope.
+ */
+export declare function buildCallLLMStage(deps: CallLLMStageDeps): (scope: TypedScope<AgentState>) => Promise<void>;
+//# sourceMappingURL=callLLM.d.ts.map

package/dist/types/core/agent/stages/callLLM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callLLM.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/callLLM.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,WAAW,EAEX,aAAa,EACb,YAAY,EACb,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;qDACiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;;sEAEkE;IAClE,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,GACrB,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAyGlD"}

package/dist/types/core/agent/stages/iterationStart.d.ts

@@ -0,0 +1,16 @@
+/**
+ * iterationStart — per-iteration marker stage.
+ *
+ * Emits `agentfootprint.agent.iteration_start` so observability adapters
+ * + recorders can bracket each ReAct iteration. Fires AFTER the slot
+ * subflows (SystemPrompt, Messages, Tools, CacheDecision, CacheGate)
+ * have produced this iteration's prompt assembly and BEFORE CallLLM.
+ *
+ * `turnIndex: 0` is intentional — the agent currently runs ONE turn per
+ * `agent.run()`. The turn index is reserved for future multi-turn
+ * orchestration; iteration index is the per-iteration counter.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../types.js';
+export declare const iterationStartStage: (scope: TypedScope<AgentState>) => void;
+//# sourceMappingURL=iterationStart.d.ts.map

package/dist/types/core/agent/stages/iterationStart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterationStart.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/iterationStart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,mBAAmB,UAAW,WAAW,UAAU,CAAC,KAAG,IAKnE,CAAC"}

package/dist/types/core/agent/stages/prepareFinal.d.ts

@@ -0,0 +1,20 @@
+/**
+ * prepareFinal — first stage of the agent's "Final" branch subflow.
+ *
+ * Captures the turn payload (`finalContent` from the LLM's latest
+ * content; `newMessages` as the `[user, assistant]` pair the memory-
+ * write subflows persist) and emits the per-turn observability
+ * brackets (`iteration_end`, `turn_end`).
+ *
+ * Mounted as the FIRST stage of the final-branch subflow built in
+ * `buildAgentChart`. Subsequent memory-write subflows mount AFTER this
+ * stage so they have `newMessages` available; `breakFinal` is the
+ * terminal stage that stops the ReAct loop.
+ *
+ * Pure function — no closure over Agent class state. Imported and
+ * passed directly to `flowChart(...)` in buildAgentChart.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../types.js';
+export declare const prepareFinalStage: (scope: TypedScope<AgentState>) => void;
+//# sourceMappingURL=prepareFinal.d.ts.map

package/dist/types/core/agent/stages/prepareFinal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareFinal.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,iBAAiB,UAAW,WAAW,UAAU,CAAC,KAAG,IAuBjE,CAAC"}

package/dist/types/core/agent/stages/route.d.ts

@@ -0,0 +1,19 @@
+/**
+ * route — decider that branches the ReAct loop into 'tool-calls' or 'final'.
+ *
+ * Runs after CallLLM. If the LLM returned tool calls AND we haven't hit
+ * `maxIterations`, route to the tool execution branch (which loops back
+ * to PromptBuilder). Otherwise route to the final-branch subflow which
+ * persists memory writes and breaks the loop.
+ *
+ * Emits `agentfootprint.agent.route_decided` with the chosen branch +
+ * a human-readable rationale (visible in narrative + observability).
+ *
+ * Pure function — no closure over Agent class state. Imported and
+ * passed directly to `addDeciderFunction(...)` in buildAgentChart.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../types.js';
+export type RouteBranch = 'tool-calls' | 'final';
+export declare const routeDeciderStage: (scope: TypedScope<AgentState>) => RouteBranch;
+//# sourceMappingURL=route.d.ts.map

package/dist/types/core/agent/stages/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;AAEjD,eAAO,MAAM,iBAAiB,UAAW,WAAW,UAAU,CAAC,KAAG,WAmBjE,CAAC"}