agentfootprint 2.4.0 → 2.5.1

package/dist/esm/core/Agent.js

@@ -14,6 +14,13 @@
  *            agentfootprint.context.* (via ContextRecorder)
  */
 import { FlowChartExecutor, flowChart, } from 'footprintjs';
+// ArrayMergeMode lives on footprintjs's `advanced` subpath, not its
+// main barrel. Used to set `arrayMerge: Replace` on subflow output
+// mapping for the Tools slot — the slot's deduped tool list must
+// REPLACE the parent's `dynamicToolSchemas` rather than concatenate
+// with it (default behavior re-introduces duplicate tool names that
+// LLM providers reject).
+import { ArrayMergeMode } from 'footprintjs/advanced';
 import { isPauseRequest } from './pause.js';
 import { emitCostTick } from './cost.js';
 import { STAGE_IDS, SUBFLOW_IDS } from '../conventions.js';
@@ -35,8 +42,10 @@ import { buildSystemPromptSlot } from './slots/buildSystemPromptSlot.js';
 import { buildMessagesSlot } from './slots/buildMessagesSlot.js';
 import { buildToolsSlot } from './slots/buildToolsSlot.js';
 import { buildInjectionEngineSubflow } from '../lib/injection-engine/buildInjectionEngineSubflow.js';
+import { buildReadSkillTool } from '../lib/injection-engine/skillTools.js';
+import { defineInstruction } from '../lib/injection-engine/factories/defineInstruction.js';
+import { applyOutputSchema, buildDefaultInstruction, } from './outputSchema.js';
 import { RunnerBase, makeRunId } from './RunnerBase.js';
-import { defineTool } from './tools.js';
 export class Agent extends RunnerBase {
     name;
     id;
@@ -71,6 +80,21 @@ export class Agent extends RunnerBase {
         runId: 'pending',
         compositionPath: [],
     };
+    /**
+     * Reference to the most recent executor. Set on every `createExecutor()`
+     * call (i.e., every `run()` and `resume()`); read by `getLastSnapshot()`
+     * / `getLastNarrativeEntries()` so post-run UIs (Lens Trace tab,
+     * ExplainableShell) can pull execution state without intercepting the
+     * call. `undefined` until the first run.
+     */
+    lastExecutor;
+    /**
+     * Reference to the FlowChart compiled for the most recent run. Cached
+     * here rather than recomputed via `buildChart()` so `getSpec()` returns
+     * the SAME spec the executor traced — important when the spec is used
+     * to reconcile `getLastSnapshot()` for ExplainableShell.
+     */
+    lastFlowChart;
     /**
      * Memory subsystems registered via `.memory()`. Each definition mounts
      * its `read` subflow before the InjectionEngine on every turn; per-id
@@ -78,7 +102,24 @@ export class Agent extends RunnerBase {
      * collision-free.
      */
     memories;
-    constructor(opts, systemPromptValue, registry, voice, injections = [], memories = []) {
+    /**
+     * Optional terminal contract. Set via the builder's `.outputSchema()`.
+     * When present, `agent.runTyped()` parses + validates the final
+     * answer against this parser. `agent.run()` keeps returning the
+     * raw string; consumers opt into typed mode explicitly.
+     */
+    outputSchemaParser;
+    /**
+     * Optional `ToolProvider` set via the builder's `.toolProvider()`.
+     * When present, the Tools slot subflow consults it per iteration
+     * (Block A5 follow-up) — the provider's tools land alongside any
+     * tools registered statically via `.tool()` / `.tools()`. The
+     * tool-call dispatcher also consults it for per-iteration execute
+     * lookup so dynamic chains (`gatedTools`, `skillScopedTools`)
+     * dispatch correctly when their visible-set changes mid-turn.
+     */
+    externalToolProvider;
+    constructor(opts, systemPromptValue, registry, voice, injections = [], memories = [], outputSchemaParser, toolProvider) {
         super();
         this.provider = opts.provider;
         this.name = opts.name ?? 'Agent';
@@ -91,6 +132,8 @@ export class Agent extends RunnerBase {
         this.registry = registry;
         this.injections = injections;
         this.memories = memories;
+        this.outputSchemaParser = outputSchemaParser;
+        this.externalToolProvider = toolProvider;
         // Eager validation: tool names must be unique across .tool() +
         // every Skill.inject.tools — the LLM dispatches by name. Runs in
         // constructor so `Agent.build()` throws immediately on collision,
@@ -115,6 +158,77 @@ export class Agent extends RunnerBase {
     toFlowChart() {
         return this.buildChart();
     }
+    /**
+     * The footprintjs `RuntimeSnapshot` from the most recent `run()` /
+     * `resume()`. Feeds Lens's Trace tab (ExplainableShell `runtimeSnapshot`
+     * prop) so consumers can scrub the execution timeline post-run without
+     * threading a recorder through the call site.
+     *
+     * Returns `undefined` before the first run completes. Returns the
+     * snapshot of the most recent run on every call after — including
+     * across multiple turns of the same Agent instance.
+     */
+    getLastSnapshot() {
+        return this.lastExecutor?.getSnapshot();
+    }
+    /**
+     * Structured narrative entries from the most recent run. Pairs with
+     * `getLastSnapshot()` for ExplainableShell's `narrativeEntries` prop.
+     * Empty array (not `undefined`) when no run has completed — matches
+     * the prop's expected shape so consumers can wire it directly without
+     * a defensive guard.
+     */
+    getLastNarrativeEntries() {
+        return this.lastExecutor?.getNarrativeEntries() ?? [];
+    }
+    /**
+     * The FlowChart compiled for the most recent run (or a freshly-built
+     * one if no run has happened yet). Feeds ExplainableShell's `spec`
+     * prop. Returning the cached chart matters: the spec must match what
+     * `getLastSnapshot()` traced, otherwise the Trace view's stage tree
+     * desyncs from the snapshot's runtime tree.
+     */
+    getSpec() {
+        return this.lastFlowChart ?? this.buildChart();
+    }
+    /**
+     * Parse + validate a raw agent answer against the agent's
+     * `outputSchema` parser. Throws `OutputSchemaError` on JSON parse
+     * or schema validation failure (the rawOutput is preserved on the
+     * error for triage). Throws a plain `Error` if the agent has no
+     * outputSchema set.
+     *
+     * Use this when you need to keep `agent.run()` returning the raw
+     * string for logging/observability and validate at a different
+     * layer; otherwise prefer `agent.runTyped()`.
+     */
+    parseOutput(raw) {
+        if (!this.outputSchemaParser) {
+            throw new Error(`Agent.parseOutput: this agent has no outputSchema. Use ` +
+                `Agent.create({...}).outputSchema(parser).build() to enable typed output.`);
+        }
+        return applyOutputSchema(raw, this.outputSchemaParser);
+    }
+    /**
+     * Run the agent and return the schema-validated typed output.
+     * Convenience over `parseOutput(await agent.run({...}))`.
+     *
+     * Throws `OutputSchemaError` on parse / validation failure.
+     * Throws if the agent has no outputSchema set or if the run
+     * pauses (use `run()` directly when pauses are expected).
+     */
+    async runTyped(input, options) {
+        if (!this.outputSchemaParser) {
+            throw new Error(`Agent.runTyped: this agent has no outputSchema. Use ` +
+                `Agent.create({...}).outputSchema(parser).build() to enable typed output.`);
+        }
+        const out = await this.run(input, options);
+        if (typeof out !== 'string') {
+            throw new Error('Agent.runTyped: run paused — typed mode does not support pauses. ' +
+                'Use agent.run() + agent.parseOutput(...) after resume.');
+        }
+        return this.parseOutput(out);
+    }
     async run(input, options) {
         const executor = this.createExecutor();
         const result = await executor.run({
@@ -144,6 +258,12 @@ export class Agent extends RunnerBase {
         };
         const chart = this.buildChart();
         const executor = new FlowChartExecutor(chart);
+        // Enable structured narrative so `getLastNarrativeEntries()` can
+        // hand a populated array to consumer Trace views (ExplainableShell).
+        // Cheap when no consumer reads it; the recorder accumulates only.
+        executor.enableNarrative();
+        this.lastExecutor = executor;
+        this.lastFlowChart = chart;
         const dispatcher = this.getDispatcher();
         const getRunCtx = () => this.currentRunContext;
         executor.attachCombinedRecorder(new ContextRecorder({ dispatcher, getRunContext: getRunCtx }));
@@ -249,31 +369,86 @@ export class Agent extends RunnerBase {
         // ability to call the right tool. Throw early instead of subtly
         // shadowing.
         const skills = this.injections.filter((i) => i.flavor === 'skill');
+        // Collect skill tools, deduping by name when the SAME Tool reference
+        // is shared across skills. Different Tool implementations under the
+        // same name throws (already validated upstream by
+        // validateToolNameUniqueness) — we keep the runtime check as
+        // belt-and-suspenders.
+        //
+        // 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.
         const skillToolEntries = [];
+        const sharedSkillTools = new Map();
         for (const skill of skills) {
+            const meta = skill.metadata;
+            const isAutoActivate = meta?.autoActivate === 'currentSkill';
             const toolsFromSkill = skill.inject.tools ?? [];
             for (const tool of toolsFromSkill) {
-                skillToolEntries.push({ name: tool.schema.name, tool });
+                const name = tool.schema.name;
+                const existing = sharedSkillTools.get(name);
+                if (existing) {
+                    if (existing !== tool) {
+                        throw new Error(`Agent: tool name '${name}' is declared by multiple skills with different ` +
+                            `Tool implementations. Skills MAY share the SAME Tool reference; they may ` +
+                            `NOT register different functions under the same name.`);
+                    }
+                    continue; // dedupe — same reference already added
+                }
+                sharedSkillTools.set(name, tool);
+                // autoActivate skills: their tools come ONLY through
+                // dynamicSchemas (buildToolsSlot.ts pulls them from
+                // activeInjections.inject.tools when the skill is active).
+                // Don't pre-load them in the static registry.
+                if (isAutoActivate)
+                    continue;
+                skillToolEntries.push({ name, tool });
             }
         }
+        // buildReadSkillTool returns undefined when skills is empty; the
+        // length check below short-circuits so the non-null assertion is safe.
         const readSkillEntries = skills.length > 0 ? [{ name: 'read_skill', tool: buildReadSkillTool(skills) }] : [];
         const augmentedRegistry = [
             ...registry,
             ...readSkillEntries,
             ...skillToolEntries,
         ];
-        // Validate: tool names must be unique across registry + skills.
-        // The LLM dispatches by name; collisions silently shadow.
+        // Final cross-source name-uniqueness check: static .tool() vs
+        // read_skill vs (deduped) skill tools. After the dedupe above this
+        // catches collisions BETWEEN sources (e.g., a static .tool('foo')
+        // colliding with a Skill's foo) which are real bugs.
         const seenNames = new Set();
         for (const entry of augmentedRegistry) {
             if (seenNames.has(entry.name)) {
                 throw new Error(`Agent: duplicate tool name '${entry.name}'. Tool names must be unique ` +
-                    `across .tool() registrations and all Skills' inject.tools (the LLM ` +
-                    `dispatches by name; collisions break tool routing).`);
+                    `across .tool() registrations and Skills' inject.tools (after deduping ` +
+                    `same-reference shares across skills). The LLM dispatches by name; ` +
+                    `collisions break tool routing.`);
             }
             seenNames.add(entry.name);
         }
         const registryByName = new Map(augmentedRegistry.map((e) => [e.name, e.tool]));
+        // Block C runtime — 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. Add them to the
+        // dispatch map so `lookupTool` resolves correctly. Using the Map
+        // backing the static registryByName means autoActivate tools share
+        // the same `.execute` wiring as normal tools — no special path.
+        for (const [name, tool] of sharedSkillTools.entries()) {
+            if (!registryByName.has(name)) {
+                registryByName.set(name, tool);
+            }
+        }
         const toolSchemas = augmentedRegistry.map((e) => e.tool.schema);
         const injectionEngineSubflow = buildInjectionEngineSubflow({
             injections: this.injections,
@@ -283,7 +458,10 @@ export class Agent extends RunnerBase {
             reason: 'Agent.system()',
         });
         const messagesSubflow = buildMessagesSlot();
-        const toolsSubflow = buildToolsSlot({ tools: toolSchemas });
+        const toolsSubflow = buildToolsSlot({
+            tools: toolSchemas,
+            ...(this.externalToolProvider && { toolProvider: this.externalToolProvider }),
+        });
         const iterationStart = (scope) => {
             typedEmit(scope, 'agentfootprint.agent.iteration_start', {
                 turnIndex: 0,
@@ -292,19 +470,22 @@ export class Agent extends RunnerBase {
         };
         const callLLM = async (scope) => {
             const systemPromptInjections = scope.systemPromptInjections ?? [];
-            const messagesInjections = scope.messagesInjections ?? [];
+            // `scope.messagesInjections` is read by ContextRecorder for
+            // observability; the LLM-wire path now reads scope.history
+            // directly (see below for rationale).
             const iteration = scope.iteration;
             const systemPrompt = systemPromptInjections
                 .map((r) => r.rawContent ?? '')
                 .filter((s) => s.length > 0)
                 .join('\n\n');
-            const messages = messagesInjections
-                .map((r) => ({
-                role: r.asRole ?? 'user',
-                content: r.rawContent ?? r.contentSummary,
-                ...(r.sourceId !== undefined && { toolCallId: r.sourceId }),
-            }))
-                .filter((m) => m.content.length > 0);
+            // Read the LLM message stream from `scope.history` directly.
+            // The `messagesInjections` projection is for observability
+            // (ContextRecorder, Lens) — it flattens InjectionRecords for
+            // event reporting and doesn't carry the full LLM-protocol
+            // shape (assistant `toolCalls[]`, etc.). For Anthropic's API
+            // contract we need the original LLMMessage with `toolCalls`
+            // intact so tool_use → tool_result correlation survives.
+            const messages = scope.history ?? [];
             typedEmit(scope, 'agentfootprint.stream.llm_start', {
                 iteration,
                 provider: provider.name,
@@ -423,8 +604,32 @@ export class Agent extends RunnerBase {
                         ...(toolCalls.length > 0 && { toolCalls }),
                     });
                 }
+                // Resolve a tool by name, consulting the external ToolProvider
+                // if one was wired via `.toolProvider()` and the static
+                // registry doesn't carry the tool. The provider sees the same
+                // ctx the Tools slot used, so dispatch + visibility stay
+                // consistent within the iteration.
+                const externalToolProvider = this.externalToolProvider;
+                const lookupTool = (toolName) => {
+                    const fromRegistry = registryByName.get(toolName);
+                    if (fromRegistry)
+                        return fromRegistry;
+                    if (!externalToolProvider)
+                        return undefined;
+                    const activatedIds = scope.activatedInjectionIds ?? [];
+                    const identity = scope.runIdentity;
+                    const ctx = {
+                        iteration: scope.iteration,
+                        ...(activatedIds.length > 0 && {
+                            activeSkillId: activatedIds[activatedIds.length - 1],
+                        }),
+                        ...(identity && { identity }),
+                    };
+                    const visible = externalToolProvider.list(ctx);
+                    return visible.find((t) => t.schema.name === toolName);
+                };
                 for (const tc of toolCalls) {
-                    const tool = registryByName.get(tc.name);
+                    const tool = lookupTool(tc.name);
                     typedEmit(scope, 'agentfootprint.stream.tool_start', {
                         toolName: tc.name,
                         toolCallId: tc.id,
@@ -680,6 +885,22 @@ export class Agent extends RunnerBase {
                 activatedInjectionIds: parent.activatedInjectionIds ?? [],
             }),
             outputMapper: (sf) => ({ activeInjections: sf.activeInjections }),
+            // CRITICAL: footprintjs's default `applyOutputMapping`
+            // CONCATENATES arrays from subflow output with the parent's
+            // existing array values. Without `Replace`, the parent's
+            // `activeInjections` from iter N gets CONCATENATED with the
+            // subflow's iter N+1 fresh evaluation — producing
+            // 8 → 16 → 24 → 32 cumulative injections per turn instead of
+            // the intended ~8-per-iter.
+            //
+            // The slot subflows below (SystemPrompt, Messages, Tools) all
+            // read `activeInjections` and render every entry, so without
+            // Replace the system prompt grows linearly with iteration
+            // count. This was the root-cause of Dynamic-mode costing
+            // ~2x more input tokens than Classic in the v2.5.0 Neo
+            // benchmarks — the InjectionEngine's intended per-iter
+            // recomposition wasn't happening; it was per-iter ACCUMULATION.
+            arrayMerge: ArrayMergeMode.Replace,
         })
             .addSubFlowChartNext(SUBFLOW_IDS.SYSTEM_PROMPT, systemPromptSubflow, 'System Prompt', {
             inputMapper: (parent) => ({
@@ -688,6 +909,11 @@ export class Agent extends RunnerBase {
                 activeInjections: parent.activeInjections,
             }),
             outputMapper: (sf) => ({ systemPromptInjections: sf.systemPromptInjections }),
+            // See Tools-subflow comment below — same array-concat hazard.
+            // Without Replace, iter N+1's systemPromptInjections gets
+            // CONCATENATED with iter N's, multiplying the system prompt
+            // each iteration.
+            arrayMerge: ArrayMergeMode.Replace,
         })
             .addSubFlowChartNext(SUBFLOW_IDS.MESSAGES, messagesSubflow, 'Messages', {
             inputMapper: (parent) => ({
@@ -696,11 +922,26 @@ export class Agent extends RunnerBase {
                 activeInjections: parent.activeInjections,
             }),
             outputMapper: (sf) => ({ messagesInjections: sf.messagesInjections }),
+            // Same array-concat hazard. messagesInjections is consumer-
+            // facing observability metadata (ContextRecorder, Lens) — must
+            // reflect THIS iteration's history, not be appended to last
+            // iteration's. CallLLM no longer reads this for the wire
+            // request (uses scope.history directly), so the LLM-protocol
+            // bug is fixed independently — but consumers of the
+            // messagesInjections stream still expect the per-iteration
+            // semantics.
+            arrayMerge: ArrayMergeMode.Replace,
         })
             .addSubFlowChartNext(SUBFLOW_IDS.TOOLS, toolsSubflow, 'Tools', {
             inputMapper: (parent) => ({
                 iteration: parent.iteration,
                 activeInjections: parent.activeInjections,
+                // The slot subflow reads these to build the per-iteration
+                // ToolDispatchContext when an external `.toolProvider()` is
+                // configured. Without them the provider sees activeSkillId
+                // = undefined every iteration, breaking skillScopedTools etc.
+                activatedInjectionIds: parent.activatedInjectionIds,
+                runIdentity: parent.runIdentity,
             }),
             outputMapper: (sf) => ({
                 toolsInjections: sf.toolsInjections,
@@ -708,6 +949,16 @@ export class Agent extends RunnerBase {
                 // back up so callLLM uses the right list for THIS iteration.
                 dynamicToolSchemas: sf.toolSchemas,
             }),
+            // CRITICAL: footprintjs's default `applyOutputMapping`
+            // CONCATENATES arrays from subflow output with the parent's
+            // existing array values. Without `Replace`, the parent's
+            // `dynamicToolSchemas` (carrying the iter N value) gets
+            // concatenated with the slot's iter N+1 deduped list,
+            // re-introducing duplicate tool names that Anthropic's API
+            // rejects with "tools: Tool names must be unique." The slot's
+            // toolSchemas IS the authoritative list — replace, don't
+            // concatenate.
+            arrayMerge: ArrayMergeMode.Replace,
         })
             .addFunction('IterationStart', iterationStart, 'iteration-start', 'Iteration begin marker')
             .addFunction('CallLLM', callLLM, STAGE_IDS.CALL_LLM, 'LLM invocation')
@@ -733,7 +984,18 @@ export class Agent extends RunnerBase {
         })
             .setDefault('final')
             .end()
-            .loopTo(SUBFLOW_IDS.MESSAGES);
+            // Dynamic ReAct: loop back to the InjectionEngine so EVERY iteration
+            // re-evaluates triggers (rule predicates, on-tool-return, llm-activated)
+            // against the freshest context (the just-appended tool result).
+            // Without this, the InjectionEngine runs ONCE per turn and:
+            //   - on-tool-return predicates never fire on iter 2+
+            //   - read_skill('X') activations are never picked up next iteration
+            //   - autoActivate per-skill tool gating is structurally impossible
+            //   - tools / system-prompt slots stay frozen at iter 1 content
+            // The v2.4 default of loopTo(MESSAGES) bypassed all four — quietly
+            // breaking the framework's "Dynamic ReAct" claim. v2.5 restores the
+            // v1 behavior that documents promise.
+            .loopTo(SUBFLOW_IDS.INJECTION_ENGINE);
         return builder.build();
     }
 }
@@ -747,6 +1009,29 @@ export class AgentBuilder {
     registry = [];
     injectionList = [];
     memoryList = [];
+    /**
+     * Optional terminal contract — see `outputSchema()`. Stored on the
+     * builder, propagated to the Agent at `.build()` time.
+     */
+    outputSchemaParser;
+    /**
+     * 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.
+     */
+    toolProviderRef;
+    /**
+     * Optional override for `AgentOptions.maxIterations`. When set via
+     * the `.maxIterations()` builder method, takes precedence over the
+     * value passed to `Agent.create({ maxIterations })`.
+     */
+    maxIterationsOverride;
+    /**
+     * Recorders collected via `.recorder()`. Attached to the built Agent
+     * before `build()` returns (each via `agent.attach(rec)`).
+     */
+    recorderList = [];
     // Voice config — defaults until the consumer calls .appName() /
     // .commentaryTemplates() / .thinkingTemplates(). Stored as plain
     // dicts (Record<string, string>) so the builder doesn't depend on
@@ -781,6 +1066,76 @@ export class AgentBuilder {
             this.tool(t);
         return 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) {
+        if (this.toolProviderRef) {
+            throw new Error('AgentBuilder.toolProvider: already set. Each agent has at most one external ToolProvider.');
+        }
+        this.toolProviderRef = provider;
+        return 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) {
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new Error(`AgentBuilder.maxIterations: expected a positive integer, got ${n}.`);
+        }
+        this.maxIterationsOverride = n;
+        return 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) {
+        this.recorderList.push(rec);
+        return this;
+    }
     /**
      * Set the agent's display name — substituted as `{{appName}}` in
      * commentary + thinking templates. Same place to brand a tenant
@@ -872,6 +1227,18 @@ export class AgentBuilder {
     instruction(injection) {
         return this.injection(injection);
     }
+    /**
+     * 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) {
+        for (const i of injections)
+            this.instruction(i);
+        return this;
+    }
     /**
      * Register a Fact — developer-supplied data the LLM should see.
      * User profile, env info, computed summary, current time, …
@@ -932,6 +1299,53 @@ export class AgentBuilder {
     rag(definition) {
         return this.memory(definition);
     }
+    /**
+     * 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(parser, opts) {
+        if (this.outputSchemaParser) {
+            throw new Error('AgentBuilder.outputSchema: already set. Each agent has at most one terminal contract.');
+        }
+        this.outputSchemaParser = parser;
+        const instructionText = opts?.instruction ?? buildDefaultInstruction(parser);
+        const id = opts?.name ?? 'output-schema';
+        // Always-on system-slot instruction. Activates every iteration so
+        // long runs keep the contract present (recency-first redundancy).
+        this.injectionList.push(defineInstruction({
+            id,
+            activeWhen: () => true,
+            prompt: instructionText,
+        }));
+        return this;
+    }
     build() {
         // Resolve the voice config: bundled defaults + consumer overrides.
         // Templates flow through the same barrel exports the rest of the
@@ -941,7 +1355,17 @@ export class AgentBuilder {
             commentaryTemplates: { ...defaultCommentaryTemplates, ...this.commentaryOverrides },
             thinkingTemplates: { ...defaultThinkingTemplates, ...this.thinkingOverrides },
         };
-        return new Agent(this.opts, this.systemPromptValue, this.registry, voice, this.injectionList, this.memoryList);
+        const opts = this.maxIterationsOverride !== undefined
+            ? { ...this.opts, maxIterations: this.maxIterationsOverride }
+            : this.opts;
+        const agent = new Agent(opts, this.systemPromptValue, this.registry, voice, this.injectionList, this.memoryList, this.outputSchemaParser, this.toolProviderRef);
+        // Attach builder-collected recorders so they receive events from
+        // the very first run. Mirrors what consumers would do post-build
+        // via `agent.attach(rec)`; the builder method is purely sugar.
+        for (const rec of this.recorderList) {
+            agent.attach(rec);
+        }
+        return agent;
     }
 }
 function validateMemoryIdUniqueness(memories) {
@@ -973,72 +1397,62 @@ function clampIterations(n) {
  * with consumer tools throw.
  */
 function validateToolNameUniqueness(registry, injections) {
-    const seen = new Set();
-    const claim = (name, sourceLabel) => {
-        if (seen.has(name)) {
-            throw new Error(`Agent: duplicate tool name '${name}' (${sourceLabel}). Tool names must be ` +
-                `unique across .tool() registrations and all Skills' inject.tools — the LLM ` +
-                `dispatches by name; collisions break tool routing.`);
+    // Static registry: unique within itself. The Agent.tool() builder
+    // method already throws on per-call duplicates; this is the
+    // belt-and-suspenders check at build time.
+    const staticNames = new Set();
+    for (const entry of registry) {
+        if (staticNames.has(entry.name)) {
+            throw new Error(`Agent: duplicate tool name '${entry.name}' in .tool() registry. ` +
+                `Tool names must be unique within the static registry.`);
         }
-        seen.add(name);
-    };
-    for (const entry of registry)
-        claim(entry.name, '.tool()');
+        staticNames.add(entry.name);
+    }
+    // `read_skill` is reserved when any Skill is registered. Collisions
+    // with consumer-supplied tools break the auto-attach path.
     const skills = injections.filter((i) => i.flavor === 'skill');
-    if (skills.length > 0)
-        claim('read_skill', 'auto-attached for Skills');
+    if (skills.length > 0 && staticNames.has('read_skill')) {
+        throw new Error(`Agent: tool name 'read_skill' is reserved when ≥1 Skill is registered. ` +
+            `Rename your custom 'read_skill' tool or unregister it.`);
+    }
+    // Per-skill check: a skill's `inject.tools` array must be internally
+    // unique (no duplicate names within the same skill — that's a
+    // skill authoring bug). Across skills, sharing a Tool reference is
+    // EXPECTED and supported — common tools (e.g., a `flogi_lookup`
+    // used by multiple investigation skills) appear in multiple skills'
+    // tool arrays. Only one skill is active at a time (or, when several
+    // are active, deduped by name + reference at runtime). Sharing the
+    // same Tool object across skills is the supported pattern; sharing
+    // a Tool NAME with a DIFFERENT execute function is the actual bug —
+    // we detect that here too.
+    const seenByName = new Map();
     for (const skill of skills) {
+        const intraSkill = new Set();
         for (const tool of skill.inject.tools ?? []) {
-            claim(tool.schema.name, `from Skill '${skill.id}'`);
+            const name = tool.schema.name;
+            if (intraSkill.has(name)) {
+                throw new Error(`Agent: skill '${skill.id}' lists tool '${name}' more than once in its ` +
+                    `inject.tools array. Each skill's tools must be unique within itself.`);
+            }
+            intraSkill.add(name);
+            // Skill tools collide with the static .tool() registry → ambiguous dispatch
+            if (staticNames.has(name)) {
+                throw new Error(`Agent: skill '${skill.id}' tool '${name}' collides with the static .tool() ` +
+                    `registry. Either rename the skill's tool or remove the static registration.`);
+            }
+            // Same name across skills with DIFFERENT Tool objects = ambiguous when
+            // both skills active. Same name + SAME Tool reference = supported sharing.
+            const prior = seenByName.get(name);
+            if (prior && prior !== tool) {
+                throw new Error(`Agent: tool name '${name}' is declared by multiple skills with different ` +
+                    `Tool implementations. Skills MAY share the SAME Tool reference across ` +
+                    `their inject.tools arrays (deduped at dispatch); they may NOT register ` +
+                    `different functions under the same name (ambiguous dispatch).`);
+            }
+            seenByName.set(name, tool);
         }
     }
 }
-/**
- * Build the auto-attached `read_skill` tool from a list of Skill
- * Injections. The LLM picks WHICH skill via the `id` argument.
- *
- * Tool execute() does the bookkeeping: appends the requested skill id
- * to `scope.activatedInjectionIds`. The next iteration's
- * InjectionEngine matches Skills with `trigger.kind: 'llm-activated'`
- * by id and includes them in the active set; slot subflows then
- * inject the body + tools.
- *
- * The tool's description lists each Skill's `id` + `description` so
- * the LLM can choose meaningfully.
- */
-function buildReadSkillTool(skills) {
-    const skillIds = skills.map((s) => s.id);
-    const skillCatalog = skills
-        .map((s) => `  - ${s.id}: ${s.description ?? '(no description)'}`)
-        .join('\n');
-    return defineTool({
-        name: 'read_skill',
-        description: `Activate a skill for the next iteration. Available skills:\n${skillCatalog}\n\n` +
-            `Pass the skill's id. The skill's body becomes part of the system prompt and any ` +
-            `gated tools become available on the next call.`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                id: {
-                    type: 'string',
-                    enum: skillIds,
-                    description: 'The skill id to activate.',
-                },
-            },
-            required: ['id'],
-        },
-        execute: ({ id }) => {
-            // Bookkeeping is handled by the Agent's tool-calls subflow,
-            // which inspects `read_skill` returns and updates
-            // `scope.activatedInjectionIds` before the next iteration.
-            // The tool itself returns a confirmation string for the LLM.
-            if (!skillIds.includes(id)) {
-                return `Unknown skill '${id}'. Available: ${skillIds.join(', ')}`;
-            }
-            return `Skill '${id}' activated for the next iteration.`;
-        },
-    });
-}
 /**
  * JSON.stringify with circular-ref protection. Tool results are untrusted —
  * a hostile/buggy tool returning a cyclic object must not crash the run.