agentfootprint 6.44.0 → 6.45.0

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

@@ -0,0 +1,565 @@
+/**
+ * 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, InjectionContext } from '../../lib/injection-engine/types.js';
+import type { EntryScoring } from '../../lib/injection-engine/skillGraph.js';
+import type { MemoryDefinition } from '../../memory/define.types.js';
+import type { ReliabilityConfig } from '../../reliability/types.js';
+import type { ThinkingHandler } from '../../thinking/types.js';
+import type { Tool } from '../tools.js';
+import type { ToolProvider } from '../../tool-providers/types.js';
+import { type SelfExplainOptions } from '../../lib/trace-toolpack/selfExplain.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;
+    /** Captured from `.skillGraph(graph)` — the cursor resolver the Injection
+     *  Engine uses to `from`-gate route triggers. Undefined unless a graph with
+     *  route edges was mounted. */
+    private skillGraphNextSkill?;
+    /** Captured from `.skillGraph(graph)` — the reachable-set resolver the
+     *  read_skill gate uses to reject out-of-set skill jumps. Undefined → the gate
+     *  is off (plain read_skill agents are unaffected). */
+    private skillGraphReachable?;
+    /** Captured from `.skillGraph(graph)` — the relevance entry scorer
+     *  (`graph.scoreEntries`), present only with `.entryByRelevance()`. When set, the
+     *  PickEntry stage picks the starting skill by relevance once per turn. */
+    private skillGraphScoreEntries?;
+    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;
+    /**
+     * Optional rules-based reliability config (v2.11.5+). Set via
+     * `.reliability({...})`. Wraps every `CallLLM` execution in a
+     * retry/fallback/fail-fast loop driven by `preCheck` and `postDecide`
+     * rules. See `ReliabilityConfig` for the rule shape.
+     */
+    private reliabilityConfig?;
+    /**
+     * Optional ThinkingHandler (v2.14+). Three states:
+     *   - undefined (default): auto-wire by `provider.name` via
+     *     `findThinkingHandler` from the registry
+     *   - explicit handler: override the auto-wire
+     *   - explicit `null`: opt out (no thinking handler mounted at all,
+     *     even if the provider would auto-match)
+     *
+     * The framework wraps the configured handler in a real footprintjs
+     * sub-subflow at chart build time (see `buildThinkingSubflow`).
+     * Mounted as a stage AFTER CallLLM inside `sf-call-llm`. Build-time
+     * conditional — no stage when no handler resolves.
+     */
+    private thinkingHandlerValue?;
+    /**
+     * v2.14+ — request-side thinking activation. When set, every LLM
+     * call carries `LLMRequest.thinking = { budget }`, asking the
+     * provider (Anthropic) to emit reasoning blocks. Independent from
+     * `.thinkingHandler()` (response-side normalization choice).
+     */
+    private thinkingBudgetValue?;
+    private selfExplainConfig?;
+    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 `defaultStatusTemplates` 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;
+    /**
+     * Mount a declarative **skill graph** (proposal 002) — each skill carries a
+     * graph-derived trigger (entry → always/rule, deterministic route → rule /
+     * on-tool-return), so dynamic token-efficient loading becomes *declared* and
+     * *drawable*. Pure sugar over `.injection()` — `graph.toMermaid()` renders the
+     * topology.
+     *
+     * @example
+     *   const graph = skillGraph()
+     *     .entry(triage)
+     *     .route(triage, sfp, { when: (r) => r.toolName === 'get_counters' && JSON.parse(r.result).crc > 0 })
+     *     .build();
+     *   Agent.create({ provider }).skillGraph(graph).build();
+     */
+    skillGraph(graph: {
+        skills: readonly Injection[];
+        nextSkill: (ctx: InjectionContext) => string | undefined;
+        reachableSkills?: (currentSkillId?: string) => readonly string[];
+        scoreEntries?: (ctx: InjectionContext, signal?: AbortSignal) => Promise<EntryScoring>;
+    }): 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;
+    /**
+     * Wire rules-based reliability around every `CallLLM` execution.
+     * The framework wraps the LLM call in a retry/fallback/fail-fast
+     * loop driven by `preCheck` and `postDecide` rules.
+     *
+     * Decision verbs the rules can emit (see `ReliabilityDecision` for
+     * the full list):
+     *
+     *   • `continue`    — pre-check OK, proceed to the call
+     *   • `ok`          — post-call OK, commit and return
+     *   • `retry`       — re-call same provider (bumps `attempt`)
+     *   • `retry-other` — advance to next provider in `providers[]`
+     *   • `fallback`    — invoke `config.fallback(req, lastError)`
+     *   • `fail-fast`   — throw `ReliabilityFailFastError` at `agent.run()`
+     *
+     * **Streaming + reliability semantics — first-chunk arbitration:**
+     * Pre-first-chunk failures (connection/headers/breaker-open) honor
+     * the full rule set (retry, retry-other, fallback, fail-fast).
+     * Post-first-chunk failures (mid-stream) honor only `ok` and
+     * `fail-fast`; rules wanting `retry`/`retry-other`/`fallback` are
+     * escalated to fail-fast with kind `'mid-stream-not-retryable'`.
+     * This matches LangChain's `RunnableWithFallbacks` pattern and
+     * the prevailing industry default — see the streaming + reliability
+     * design memo for the full discussion.
+     *
+     * Throws if called more than once on the same builder.
+     *
+     * @example
+     *   import { Agent } from 'agentfootprint';
+     *   import { ReliabilityFailFastError } from 'agentfootprint/reliability';
+     *
+     *   const agent = Agent.create({ provider, model: 'mock' })
+     *     .system('Triage support tickets.')
+     *     .reliability({
+     *       postDecide: [
+     *         { when: (s) => s.errorKind === '5xx-transient' && s.attempt < 3,
+     *           then: 'retry', kind: 'transient-retry' },
+     *         { when: (s) => s.error !== undefined,
+     *           then: 'fail-fast', kind: 'unrecoverable' },
+     *       ],
+     *       circuitBreaker: { failureThreshold: 3 },
+     *     })
+     *     .build();
+     *
+     *   try {
+     *     await agent.run({ message: 'help' });
+     *   } catch (e) {
+     *     if (e instanceof ReliabilityFailFastError) {
+     *       console.log(e.kind, e.reason);
+     *     }
+     *   }
+     */
+    reliability(config: ReliabilityConfig): this;
+    /**
+     * Wire a thinking handler (v2.14+). Three usage patterns:
+     *
+     *   • OMITTED (default) — framework auto-wires by `provider.name` via
+     *     `findThinkingHandler` from the registry. Most consumers using
+     *     a shipped provider get thinking support for free.
+     *
+     *   • EXPLICIT handler — override the auto-wire. For custom providers
+     *     or for swapping in a custom Anthropic/OpenAI handler with
+     *     different normalization (e.g. redacting blocks before they
+     *     land).
+     *
+     *   • EXPLICIT `null` — opt out entirely. The thinking subflow is NOT
+     *     mounted even if the provider would auto-match. Use when you
+     *     want to skip thinking parsing for this agent (cost / latency /
+     *     UX reasons).
+     *
+     * Calling twice throws — same shape as `.reliability()` /
+     * `.outputSchema()` to enforce single-source intent.
+     *
+     * @example
+     *   // Default — auto-wire AnthropicThinkingHandler for anthropic provider
+     *   Agent.create({ provider: anthropic({...}), model: '...' }).build();
+     *
+     * @example
+     *   // Custom handler that redacts thinking content
+     *   Agent.create({...}).thinkingHandler(myRedactingHandler).build();
+     *
+     * @example
+     *   // Opt out of thinking parsing entirely
+     *   Agent.create({ provider: anthropic({...}), model: '...' })
+     *     .thinkingHandler(null)
+     *     .build();
+     */
+    thinkingHandler(handler: ThinkingHandler | null): this;
+    /**
+     * v2.14+ — REQUEST-side thinking activation. Tells the provider to
+     * emit reasoning blocks alongside its response.
+     *
+     * **What this does:** every LLM call carries
+     * `LLMRequest.thinking = { budget }`. The AnthropicProvider
+     * translates to `thinking: { type: 'enabled', budget_tokens: N }`
+     * on the wire. The model spends up to `budget` reasoning tokens
+     * before producing the visible response.
+     *
+     * **Distinct from `.thinkingHandler()`:**
+     *   - `.thinking({ budget })` = ASK the model to think (request side)
+     *   - `.thinkingHandler(h)`   = NORMALIZE the response (response side)
+     *
+     * Most consumers want both; auto-wired handler covers the response
+     * side automatically when `.thinking()` is set on a thinking-capable
+     * provider. Setting `.thinking()` without `.thinkingHandler(null)`
+     * is the typical happy path.
+     *
+     * **Provider compatibility:**
+     *   - Anthropic: requires claude-sonnet-4-5 / opus-4-5 (or newer).
+     *     Older models reject with HTTP 400.
+     *   - OpenAI: ignores. o1/o3 reasoning is selected at the model id
+     *     level; this field is a no-op for OpenAIProvider.
+     *
+     * **Budget guidance:** Anthropic recommends 1024-32000 reasoning
+     * tokens. `budget` MUST be less than the request's `max_tokens`
+     * (defaults to 4096 in AnthropicProvider — bump via the request
+     * `maxTokens` if budget > ~3000).
+     *
+     * Calling twice throws — same shape as `.reliability()` /
+     * `.outputSchema()`.
+     *
+     * @example
+     *   Agent.create({ provider: anthropic({...}), model: 'claude-sonnet-4-5' })
+     *     .system('You are a careful reasoning agent.')
+     *     .thinking({ budget: 5000 })   // ask Anthropic to think
+     *     .build();
+     */
+    thinking(opts: {
+        budget: number;
+    }): this;
+    /**
+     * Let this agent answer why-questions about its OWN previous completed
+     * turn, from its recorded trace. Mounts one skill: day to day the tool
+     * catalog carries only the skill's activation row; when the user asks
+     * "why did you…", the LLM activates it and that iteration alone gets
+     * the trace tools (inline mode) or a single `explain_run` tool that
+     * runs a nested trace debugger on a cheaper model (delegate mode).
+     *
+     * Evidence binds LATE — always to the previous COMPLETED run, never
+     * the in-flight one — and includes control edges (a per-run
+     * control-dependence recorder is attached automatically).
+     *
+     * @example
+     *   Agent.create({ provider, model })
+     *     .system('You are a refunds assistant.')
+     *     .tool(lookupOrder)
+     *     .selfExplain()                                 // inline, zero config
+     *     .build();
+     *
+     * @example
+     *   .selfExplain({ delegate: { provider: anthropic(), model: 'claude-haiku-4-5' } })
+     */
+    selfExplain(opts?: SelfExplainOptions): this;
+    build(): Agent;
+}

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

@@ -0,0 +1,109 @@
+/**
+ * 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:
+ *
+ *     Initialize
+ *       → [memory READ subflows for each .memory()]
+ *       → InjectionEngine (subflow)               ← loop target (tool-calls loops here)
+ *       → Context (selector, PARALLEL fan-out, failFast)
+ *             ⇉ {System Prompt ‖ Messages ‖ Tools}  (slot subflows)
+ *             → converge
+ *       → UpdateSkillHistory
+ *       → Cache (sf-cache subflow: decideCacheMarkers → CacheGate
+ *                → ApplyMarkers / SkipCaching)
+ *       → CallLLM (also emits the per-iteration iteration_start marker)
+ *       → [NormalizeThinking] (subflow, only when a ThinkingHandler resolved)
+ *       → Route (decider)
+ *             ├─ tool-calls (pausable) → loopTo(InjectionEngine)   ← branch-sourced loop
+ *             └─ final (subflow) → terminal leaf
+ *                          ┌────── PrepareFinal
+ *                          ├──── [memory WRITE subflows]
+ *                          └──── BreakFinal ($break)
+ *
+ * (When v2.11.x reliability is configured, the reliability gate chart
+ * mounts as a subflow before CallLLM with a TranslateFailFast stage
+ * after it. Lands in the next commit.)
+ */
+import type { FlowChart, StructureRecorder } 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[];
+    /** Evidence bridge (#5): `causalEvidenceRecorder().collect`, threaded into
+     *  CAUSAL memories' write mounts so snapshots persist real evidence
+     *  (decisions/toolCalls/iterations/duration/tokens) instead of zeros.
+     *  Set by the Agent when any mounted memory is CAUSAL. */
+    readonly causalEvidenceSource?: () => import('../../memory/causal/evidenceRecorder.js').RunEvidence;
+    /** 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 callLLM: (scope: never) => Promise<void>;
+    readonly routeDecider: (scope: never) => 'tool-calls' | 'final';
+    readonly toolCallsHandler: import('footprintjs').PausableHandler<never>;
+    readonly injectionEngineSubflow: FlowChart;
+    /** Relevance entry router (`entryByRelevance`) — a once-per-turn function stage
+     *  mounted before the InjectionEngine (off the ReAct loop). Present only when the
+     *  skill graph was built with a relevance scorer. */
+    readonly pickEntryStage?: (scope: never) => Promise<void>;
+    readonly systemPromptSubflow: FlowChart;
+    readonly messagesSubflow: FlowChart;
+    readonly toolsSubflow: FlowChart;
+    /**
+     * Optional thinking-normalization sub-subflow (v2.14+). Mounted as a
+     * stage AFTER CallLLM, BEFORE Route, only when a `ThinkingHandler`
+     * resolved (either auto-wired by `provider.name` or explicitly set
+     * via `.thinkingHandler()`). When undefined, the stage is NOT added —
+     * zero overhead for non-thinking agents (build-time conditional mount).
+     */
+    readonly thinkingSubflow?: FlowChart;
+    readonly updateSkillHistoryStage: (scope: never) => void;
+    /**
+     * Whether ≥1 Skill is registered. The `UpdateSkillHistory` stage (and
+     * therefore the cache's skill-churn rule) is mounted ONLY when true:
+     * with no skills the window would record "no skill" every iteration and
+     * `detectSkillChurn` could never fire, so the stage would be pure dead
+     * weight + a misleading box. Mirrors the `skills.length > 0` gate that
+     * auto-attaches `read_skill`, and the `thinkingSubflow` conditional mount.
+     */
+    readonly hasSkills: boolean;
+    /**
+     * ReAct loop semantics. `'dynamic'` (default) re-runs the InjectionEngine +
+     * all 3 slots every iteration (loop → InjectionEngine). `'classic'`
+     * engineers context ONCE (InjectionEngine + system-prompt + tools up front)
+     * and loops only the Messages slot (loop → Messages). See AgentOptions.reactMode.
+     */
+    readonly reactMode?: 'classic' | 'dynamic';
+    /** Structure recorders threaded into both `flowChart()` calls (the
+     *  main chart and the PrepareFinal sub-chart). Each recorder
+     *  observes per-node build events (`onStageAdded` /
+     *  `onSubflowMounted` / etc.) for the Agent's chart. Undefined when
+     *  the consumer didn't attach any. */
+    readonly structureRecorders?: readonly StructureRecorder[];
+}
+/**
+ * Build the agent's complete FlowChart from the supplied deps.
+ */
+export declare function buildAgentChart(deps: AgentChartDeps): FlowChart;

package/dist/esm/core/agent/buildAgentChart.js

@@ -148,8 +148,9 @@ export function buildAgentChart(deps) {
             // Skill-graph cursor as of the previous iteration — the `from`-gate the
             // route triggers compare against. Undefined on cold start / no graph.
             currentSkillId: parent.currentSkillId,
-            // Relevance entry ranking (entryByRelevance) — read by defineRelevanceHint.
+            // Relevance entry ranking (from an entry scorer) — read by defineRelevanceHint.
             entryScores: parent.entryScores,
+            entryScorer: parent.entryScorer,
         }),
         // Carry activeByslot back to parent so next turn's inputMapper can
         // feed it as priorActiveByslot (the Delta round-trip). currentSkillId is