agentfootprint 1.22.0 → 2.0.1

package/dist/lib/loop/buildAgentLoop.js

@@ -1,632 +0,0 @@
-"use strict";
-/**
- * Loop assembler — builds the full agent ReAct loop flowchart.
- *
- * Mounts the three API slots as subflows, then wires CallLLM → ParseResponse →
- * RouteResponse (decider) with branches for tool execution and finalization.
- *
- * Supports two loop patterns (AgentPattern enum):
- *
- * Regular ReAct (default): loopTo('call-llm')
- *   Seed → [sf-system-prompt] → [sf-messages] → [sf-tools]
- *     → AssemblePrompt → CallLLM → ParseResponse
- *     → RouteResponse(decider) → [CommitMemory?] → loopTo('call-llm')
- *   Slots resolve ONCE before the loop.
- *
- * Dynamic ReAct: loopTo('sf-instructions-to-llm' or 'sf-system-prompt')
- *   Same flowchart, but loop jumps back to InstructionsToLLM (when configured)
- *   or SystemPrompt. All slots re-evaluate each iteration.
- *   Uses arrayMerge: ArrayMergeMode.Replace on Messages/Tools outputMappers
- *   so arrays are overwritten (not concatenated) on each iteration.
- *
- * Design choices:
- *   - Seed stage initializes loopCount + maxIterations + messages
- *   - Slot subflows use arrayMerge: Replace to avoid stale array accumulation
- *   - Each slot is ALWAYS a subflow — zero overhead, free drill-down + narrative
- *   - RouteResponse is a proper decider — visible in flowchart as diamond with branches
- *   - Tool execution is a subflow — enables drill-down in BTS
- *   - Chart is self-contained — no wrapping needed
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildAgentLoop = exports.SUBFLOW_MESSAGE_KEY = void 0;
-const footprintjs_1 = require("footprintjs");
-const advanced_1 = require("footprintjs/advanced");
-const messages_1 = require("../../types/messages");
-const system_prompt_1 = require("../slots/system-prompt");
-const messages_2 = require("../slots/messages");
-const tools_1 = require("../slots/tools");
-const callLLMStage_1 = require("../call/callLLMStage");
-const streamingCallLLMStage_1 = require("../call/streamingCallLLMStage");
-const parseResponseStage_1 = require("../call/parseResponseStage");
-const toolExecutionSubflow_1 = require("../call/toolExecutionSubflow");
-const content_1 = require("../../types/content");
-const memory_1 = require("../../memory");
-const mountMemoryPipeline_1 = require("../../memory/wire/mountMemoryPipeline");
-const types_1 = require("./types");
-const instructions_1 = require("../instructions");
-const messages_3 = require("../../types/messages");
-// ── Default Agent Routing ─────────────────────────────────────────────────────
-/**
- * Default routing for the Agent loop: tool-calls | final.
- *
- * Expressed as a RoutingConfig so buildAgentLoop has ONE code path
- * for both Agent and Swarm routing.
- *
- * The `final` branch is a SUBFLOW that owns its own post-work:
- * Finalize → (optional commit / memory-write) → Break. This keeps
- * branch-specific work inside the branch — no post-decider trailing
- * stages gated on flags. Tool-calls is a separate branch with its own
- * subflow.
- */
-function defaultAgentRouting(toolExecutionSubflow, finalBranchSubflow) {
-    return {
-        deciderName: 'RouteResponse',
-        deciderId: 'route-response',
-        deciderDescription: 'Route to tool execution or finalization based on LLM response',
-        // Filter-form decide() — captures structured evidence
-        // `{ key: 'hasToolCalls', op: 'eq', threshold: true, actual: ..., result: ... }`
-        // on FlowRecorder.onDecision (and the commit log's decision record),
-        // which is what explainability consumers query post-hoc.
-        //
-        // ParseResponse lifts `parsedResponse.hasToolCalls` to the flat
-        // `scope.hasToolCalls` field so we can use filter form — v1 filter
-        // DSL is flat-keys-only, no nested access.
-        //
-        // Returns the full DecisionResult (NOT `.branch`): DeciderHandler
-        // recognizes the DECISION_RESULT symbol brand and extracts evidence.
-        // Returning a bare string would drop the evidence entirely.
-        decider: (scope) => (0, footprintjs_1.decide)(scope, [
-            {
-                when: { hasToolCalls: { eq: true } },
-                then: 'tool-calls',
-                label: 'LLM requested tool calls — execute them',
-            },
-        ], 'final'),
-        branches: [
-            {
-                id: 'tool-calls',
-                kind: 'subflow',
-                chart: toolExecutionSubflow,
-                name: 'ExecuteTools',
-                mount: {
-                    inputMapper: (parent) => ({
-                        parsedResponse: parent.parsedResponse,
-                        currentMessages: parent.messages,
-                        currentLoopCount: parent.loopCount,
-                        maxIterations: parent.maxIterations,
-                        ...(parent.decision ? { currentDecision: parent.decision } : {}),
-                    }),
-                    outputMapper: (sfOutput) => ({
-                        messages: sfOutput.toolResultMessages,
-                        loopCount: sfOutput.updatedLoopCount,
-                        ...(sfOutput.updatedDecision ? { decision: sfOutput.updatedDecision } : {}),
-                    }),
-                },
-            },
-            {
-                id: 'final',
-                kind: 'subflow',
-                chart: finalBranchSubflow,
-                name: 'Finalize',
-                mount: {
-                    inputMapper: (parent) => ({
-                        messages: parent.messages,
-                        maxIterations: parent.maxIterations,
-                        maxIterationsReached: parent.maxIterationsReached,
-                        identity: parent.identity,
-                        turnNumber: parent.turnNumber,
-                        contextTokensRemaining: parent.contextTokensRemaining,
-                    }),
-                    outputMapper: (sf) => ({
-                        result: sf.result,
-                    }),
-                    // Inner Break at end of subflow → parent $break, ending the loop.
-                    propagateBreak: true,
-                },
-            },
-        ],
-        defaultBranch: 'final',
-    };
-}
-/**
- * Build the `final` branch subflow. This subflow runs exclusively on
- * the final branch — tool-calls iterations never enter it — so its
- * stages run only once per `.run()` and are unconditional. Structure:
- *
- *   Finalize → [PackageForWrite + sf-memory-write]? → Break
- *
- * Finalize writes `result`. The optional middle stages persist the turn
- * when `memoryPipeline.write` is configured. Break terminates the loop;
- * the subflow mount's `propagateBreak: true` lifts it into the parent.
- */
-function buildFinalBranchSubflow(config) {
-    let b = (0, footprintjs_1.flowChart)('Finalize', finalizeStage, 'finalize', undefined, 'Extract final answer from last assistant message');
-    if (config.memoryPipeline?.write) {
-        b = b.addFunction('PackageForWrite', (scope) => {
-            const msgs = scope.messages ?? [];
-            scope.newMessages = msgs.filter((m) => m.role !== 'system');
-        }, 'package-for-write', 'Package messages for the memory write subflow');
-        // Delegates to the `mountMemoryWrite` wire helper — defaults match
-        // the scope field names used above (identity/turnNumber/contextTokensRemaining/newMessages).
-        b = (0, mountMemoryPipeline_1.mountMemoryWrite)(b, { pipeline: config.memoryPipeline });
-    }
-    b = b.addFunction('Break', (scope) => scope.$break(), 'break', 'Terminate the agent loop');
-    return b.build();
-}
-/**
- * Finalize stage — write the final answer into scope.result.
- *
- * Pure data work: extracts text from the last assistant message and
- * writes `result`. No loop control — the final-branch subflow's Break
- * stage owns termination.
- *
- * Also emits `agentfootprint.agent.turn_complete` on the emit channel,
- * mirroring the existing `agentfootprint.llm.request/response` events
- * emitted by CallLLM. Gives external consumers a structured turn-end
- * signal with the reason (natural vs forced) and iteration count.
- */
-const finalizeStage = (scope) => {
-    const messages = scope.messages ?? [];
-    const lastAsst = (0, memory_1.lastAssistantMessage)(messages);
-    const lastAsstText = lastAsst ? (0, content_1.getTextContent)(lastAsst.content) : '';
-    const exhausted = scope.maxIterationsReached === true;
-    if (exhausted) {
-        const maxIter = scope.maxIterations ?? 10;
-        scope.result =
-            lastAsstText ||
-                `Agent stopped after ${maxIter} iterations without a final answer. The LLM may be stuck in a tool-error retry loop — check the execution trace.`;
-    }
-    else {
-        scope.result = lastAsstText;
-    }
-    scope.$emit('agentfootprint.agent.turn_complete', {
-        iterations: scope.loopCount ?? 0,
-        reason: exhausted ? 'max_iterations' : 'final',
-        resultLength: (scope.result ?? '').length,
-    });
-};
-/**
- * Well-known scope key for the user message in subflow mode.
- * Parent charts must set this key in their inputMapper:
- * `inputMapper: (p) => ({ message: p.userMessage })`
- */
-exports.SUBFLOW_MESSAGE_KEY = 'message';
-function buildAgentLoop(config, seed, options) {
-    validateConfig(config);
-    const maxIterations = config.maxIterations ?? 10;
-    const seedMessages = seed?.messages ?? [];
-    const existingMessages = seed?.existingMessages ?? [];
-    const subflowMode = seed?.subflowMode ?? false;
-    // Build slot subflows
-    const systemPromptSubflow = (0, system_prompt_1.buildSystemPromptSubflow)(config.systemPrompt);
-    const messagesSubflow = (0, messages_2.buildMessagesSubflow)(config.messages);
-    const toolsSubflow = (0, tools_1.buildToolsSubflow)(config.tools);
-    // Build instruction config from registry — collect tools that have instructions
-    // Apply agent-level overrides if provided
-    const instructionsByToolId = new Map();
-    for (const tool of config.registry.all()) {
-        const instructed = tool;
-        if (instructed.instructions?.length) {
-            const override = config.instructionOverrides?.get(tool.id);
-            if (override) {
-                instructionsByToolId.set(tool.id, (0, instructions_1.applyInstructionOverrides)(instructed.instructions, override));
-            }
-            else {
-                instructionsByToolId.set(tool.id, instructed.instructions);
-            }
-        }
-    }
-    // Instruction tool registration is done by AgentRunner constructor (not here).
-    // decideFunctions are pre-computed and passed via config.decideFunctions.
-    const hasAgentInstructions = config.agentInstructions && config.agentInstructions.length > 0;
-    // Build a fresh local map: start from pre-computed agent-level functions, add per-tool ones.
-    // Uses a local copy — never mutates the cached config.decideFunctions.
-    const decideFunctions = new Map(config.decideFunctions ?? []);
-    for (const [, instructions] of instructionsByToolId) {
-        for (const instr of instructions) {
-            if (instr.decide && !decideFunctions.has(instr.id)) {
-                decideFunctions.set(instr.id, instr.decide);
-            }
-        }
-    }
-    // Strict follow-up tracking is now OWNED BY THE CALLER. buildAgentLoop
-    // doesn't buffer state between runs — consumers (AgentRunner) implement
-    // `config.onInstructionsFired` to track strict firings in their own
-    // per-run state. This lets the chart be built ONCE and reused across
-    // many `.run()` calls without state leaking between turns.
-    const onInstructionsFired = config.onInstructionsFired;
-    // Build call stages. Stream lifecycle events flow through the emit
-    // channel (see callLLMStage / streamingCallLLMStage) — no closure
-    // capture of per-run stream handlers. AgentRunner attaches a
-    // StreamEventRecorder per-run to forward emits to the user callback.
-    const callLLM = config.streaming
-        ? (0, streamingCallLLMStage_1.createStreamingCallLLMStage)(config.provider, {
-            responseFormat: config.responseFormat,
-        })
-        : (0, callLLMStage_1.createCallLLMStage)(config.provider, {
-            responseFormat: config.responseFormat,
-        });
-    const toolExecutionSubflow = (0, toolExecutionSubflow_1.buildToolExecutionSubflow)({
-        registry: config.registry,
-        toolProvider: config.toolProvider,
-        parallel: config.parallelTools === true,
-        ...(config.maxIdenticalFailures !== undefined && {
-            maxIdenticalFailures: config.maxIdenticalFailures,
-        }),
-        // Always pass instruction config — even without build-time instructions,
-        // tool handlers can return runtime instructions/followUps. The
-        // `onStreamEvent` inside is populated by toolExecutionSubflow's own
-        // stage wrapper as a scope-emit adapter.
-        instructionConfig: {
-            instructionsByToolId,
-            onInstructionsFired,
-            decideFunctions: decideFunctions.size > 0 ? decideFunctions : undefined,
-            agentResponseRules: hasAgentInstructions
-                ? config.agentInstructions.flatMap((i) => i.onToolResult ?? [])
-                : undefined,
-        },
-    });
-    // Two distinct Seed stage implementations — no runtime boolean.
-    // The flowchart is built differently for standalone vs subflow composition.
-    //
-    // Per-run data (the user's message, accumulated conversation history)
-    // flows in through `scope.$getArgs()` — NOT through closure captures of
-    // `seedMessages` / `existingMessages`. This lets AgentRunner build the
-    // chart ONCE at construction and pass new inputs via `run({ input })`
-    // every turn, instead of rebuilding the whole chart per call.
-    //
-    // Back-compat: if `seed.messages` / `seed.existingMessages` are
-    // provided AND args don't override, the closure values are still used
-    // so existing single-shot tests keep working.
-    const initialDecision = config.initialDecision ?? {};
-    const seedStandalone = (scope) => {
-        const args = scope.$getArgs() ?? {};
-        const argUserMessage = args['seed:userMessage'];
-        const argExisting = args['seed:existingMessages'];
-        const argMessages = args['seed:messages'];
-        // Carry-over decision scope from the caller's previous run. When the
-        // agent is reused across multiple `.run()` calls (multi-turn chat),
-        // decision fields written by tools on turn N should still be visible
-        // on turn N+1 — otherwise skill-gated tool visibility (autoActivate)
-        // resets between turns and the LLM silently loses its active skill.
-        // See AgentRunner.lastDecision for the capture side.
-        const argSeedDecision = args['seed:initialDecision'];
-        const effectiveExisting = argExisting ?? existingMessages;
-        const effectiveIncoming = argMessages !== undefined
-            ? argMessages
-            : argUserMessage !== undefined
-                ? argUserMessage
-                    ? [(0, messages_1.userMessage)(argUserMessage)]
-                    : []
-                : seedMessages;
-        scope.messages = [...effectiveExisting, ...effectiveIncoming];
-        scope.loopCount = 0;
-        scope.maxIterations = maxIterations;
-        if (hasAgentInstructions) {
-            scope.decision = { ...(argSeedDecision ?? initialDecision) };
-        }
-    };
-    const seedSubflow = (scope) => {
-        // In subflow mode the parent's inputMapper pipes the user turn
-        // through `scope.message` — that's the contract for mounting agent
-        // loops inside other flowcharts (FlowChart/Conditional/Swarm specs).
-        const msg = scope.message ?? '';
-        scope.messages = msg ? [(0, messages_1.userMessage)(msg)] : [];
-        scope.loopCount = 0;
-        scope.maxIterations = maxIterations;
-        if (hasAgentInstructions) {
-            scope.decision = { ...initialDecision };
-        }
-    };
-    const seedStage = subflowMode ? seedSubflow : seedStandalone;
-    let builder = (0, footprintjs_1.flowChart)('Seed', seedStage, 'seed', undefined, 'Initialize agent loop state');
-    // ── Memory pipeline: read-side mount ────────────────────────
-    //
-    // Mounted BEFORE the loop body so both Regular (`call-llm`) and
-    // Dynamic (`sf-system-prompt` / `sf-instructions-to-llm`) loop targets
-    // skip over it on re-entry. Memory context is a per-TURN concern —
-    // the store doesn't change mid-turn, so re-reading on every iteration
-    // is pure waste. Runs exactly once per `.run()`.
-    //
-    // A small MemorySeed stage runs first to copy identity / turnNumber /
-    // contextTokensRemaining from `scope.$getArgs()` into scope state.
-    // The subflow itself reads from parent scope via inputMapper, loads
-    // relevant entries from the store, picks what fits the budget, and
-    // writes `memoryInjection` (system messages) back for AssemblePrompt
-    // to prepend.
-    if (config.memoryPipeline) {
-        const memoryPipeline = config.memoryPipeline;
-        builder = builder.addFunction('MemorySeed', (scope) => {
-            const args = scope.$getArgs() ?? {};
-            const identity = args['memory:identity'];
-            const turnNumber = args['memory:turnNumber'];
-            const budget = args['memory:contextTokensRemaining'];
-            if (!identity && isDevMode()) {
-                console.warn('[agentfootprint] .memoryPipeline() used without identity — falling back to ' +
-                    '{ conversationId: "default" }. Pass `run(msg, { identity: { conversationId, ... } })` ' +
-                    'to scope memory per user / session.');
-            }
-            scope.identity = identity ?? { conversationId: 'default' };
-            scope.turnNumber = turnNumber ?? 1;
-            scope.contextTokensRemaining = budget ?? 4000;
-        }, 'memory-seed', 'Seed memory identity / turn / budget from run() args');
-        // Delegates to the `mountMemoryRead` wire helper — defaults match
-        // what we'd inline (identity/turnNumber/contextTokensRemaining/newMessages →
-        // sf-memory-read, outputs `memoryInjection`). Keeps the helper and
-        // the agent loop in lockstep and avoids maintaining two copies.
-        builder = (0, mountMemoryPipeline_1.mountMemoryRead)(builder, { pipeline: memoryPipeline });
-    }
-    // Mount InstructionsToLLM subflow BEFORE the 3 API slots (only when instructions registered).
-    //
-    // arrayMerge: Replace is REQUIRED here — without it, Dynamic ReAct loops
-    // concatenate promptInjections/toolInjections across iterations. That
-    // both (a) inflates the system prompt on every turn and (b) sends the
-    // same tool names twice to Anthropic on iteration 2+, which rejects with
-    // "tools: Tool names must be unique." sf-messages and sf-tools below
-    // already have this flag for the same reason.
-    if (hasAgentInstructions) {
-        const instructionsSubflow = (0, instructions_1.buildInstructionsToLLMSubflow)(config.agentInstructions);
-        builder = builder.addSubFlowChartNext('sf-instructions-to-llm', instructionsSubflow, 'InstructionsToLLM', {
-            inputMapper: (parent) => ({
-                decision: parent.decision,
-            }),
-            outputMapper: (sf) => ({
-                promptInjections: sf.promptInjections,
-                toolInjections: sf.toolInjections,
-                responseRules: sf.responseRules,
-                matchedInstructions: sf.matchedInstructions,
-            }),
-            arrayMerge: advanced_1.ArrayMergeMode.Replace,
-        });
-    }
-    // Mount SystemPrompt subflow
-    builder = builder.addSubFlowChartNext('sf-system-prompt', systemPromptSubflow, 'SystemPrompt', {
-        inputMapper: (parent) => ({
-            messages: parent.messages,
-            loopCount: parent.loopCount,
-            ...(parent.promptInjections ? { promptInjections: parent.promptInjections } : {}),
-        }),
-        outputMapper: (sfOutput) => ({
-            systemPrompt: sfOutput.systemPrompt,
-        }),
-    });
-    // Mount Messages subflow
-    // Mount Messages subflow — arrayMerge: 'replace' so messages are overwritten
-    // (not concatenated) on each Dynamic ReAct iteration.
-    builder = builder.addSubFlowChartNext('sf-messages', messagesSubflow, 'Messages', {
-        inputMapper: (parent) => ({
-            currentMessages: parent.messages ?? [],
-            loopCount: parent.loopCount ?? 0,
-        }),
-        outputMapper: (sfOutput) => ({
-            messages: sfOutput.memory_preparedMessages,
-            memory_preparedMessages: sfOutput.memory_preparedMessages,
-        }),
-        arrayMerge: advanced_1.ArrayMergeMode.Replace,
-    });
-    // Mount Tools subflow — arrayMerge: 'replace' so toolDescriptions is overwritten
-    // each iteration (not concatenated). Essential for Dynamic mode where tools change.
-    builder = builder.addSubFlowChartNext('sf-tools', toolsSubflow, 'Tools', {
-        inputMapper: (parent) => ({
-            messages: parent.messages,
-            loopCount: parent.loopCount,
-            ...(parent.toolInjections ? { toolInjections: parent.toolInjections } : {}),
-        }),
-        outputMapper: (sfOutput) => ({
-            toolDescriptions: sfOutput.toolDescriptions,
-        }),
-        arrayMerge: advanced_1.ArrayMergeMode.Replace,
-    });
-    const assemblePromptStage = (scope) => {
-        const messages = scope.messages ?? [];
-        const sysPrompt = scope.systemPrompt;
-        const injection = scope.memoryInjection ?? [];
-        // Build the final prompt: system prompt → memory injection → user
-        // messages. Memory comes AFTER the system prompt (role instructions)
-        // but BEFORE the ongoing dialogue, matching the conceptual ordering
-        // "your role, what you know from before, what the user just said."
-        const nonSystem = messages.filter((m) => m.role !== 'system');
-        const prefix = [];
-        if (sysPrompt)
-            prefix.push((0, messages_1.systemMessage)(sysPrompt));
-        prefix.push(...injection);
-        scope.messages = [...prefix, ...nonSystem];
-    };
-    // AssemblePrompt: prepend system message + memory injection
-    builder = builder.addFunction('AssemblePrompt', assemblePromptStage, 'assemble-prompt', 'Prepend system prompt + memory injection to messages before LLM call');
-    // CallLLM → ParseResponse → Routing(decider)
-    //   Routing is pluggable via config.routing (RoutingConfig).
-    //   Default: RouteResponse → {tool-calls | final}
-    //   Swarm:   RouteSpecialist → {specialist-A | ... | swarm-tools | final}
-    //
-    // Add CallLLM — streaming or non-streaming
-    if (config.streaming) {
-        builder = builder.addStreamingFunction('CallLLM', callLLM, 'call-llm', 'llm-stream', 'Send messages + tools to LLM provider (streaming)');
-    }
-    else {
-        builder = builder.addFunction('CallLLM', callLLM, 'call-llm', 'Send messages + tools to LLM provider');
-    }
-    builder = builder.addFunction('ParseResponse', parseResponseStage_1.parseResponseStage, 'parse-response', 'Parse LLM response into structured result');
-    // ── Routing — one code path for both Agent and Swarm ──
-    // Priority: explicit config.routing (Swarm) > routeExtensions (user .route()) > default
-    const finalBranchSubflow = buildFinalBranchSubflow(config);
-    const routing = config.routing
-        ? config.routing
-        : config.routeExtensions && config.routeExtensions.length > 0
-            ? extendDefaultRouting(defaultAgentRouting(toolExecutionSubflow, finalBranchSubflow), config.routeExtensions)
-            : defaultAgentRouting(toolExecutionSubflow, finalBranchSubflow);
-    // Validate branches
-    if (routing.branches.length === 0) {
-        throw new Error('RoutingConfig must have at least one branch.');
-    }
-    const branchIds = new Set(routing.branches.map((b) => b.id));
-    if (branchIds.size !== routing.branches.length) {
-        throw new Error('RoutingConfig has duplicate branch IDs.');
-    }
-    if (!branchIds.has(routing.defaultBranch)) {
-        throw new Error(`RoutingConfig.defaultBranch '${routing.defaultBranch}' does not match any branch ID: [${[
-            ...branchIds,
-        ].join(', ')}]`);
-    }
-    // Wrap decider with structural maxIterations guard — no custom routing
-    // can bypass this. If loopCount >= maxIterations, force-route to the
-    // defaultBranch and set `maxIterationsReached` so the default branch
-    // (Finalize, Swarm's fallback, user-supplied terminal, etc.) can
-    // surface the fact that this was a forced termination.
-    const safeDecider = (scope, breakFn, streamCb) => {
-        const loopCount = scope.loopCount ?? 0;
-        const maxIter = scope.maxIterations ?? 10;
-        if (loopCount >= maxIter) {
-            scope.maxIterationsReached = true;
-            return routing.defaultBranch;
-        }
-        return routing.decider(scope, breakFn, streamCb);
-    };
-    let decider = builder.addDeciderFunction(routing.deciderName, safeDecider, routing.deciderId, routing.deciderDescription);
-    for (const branch of routing.branches) {
-        switch (branch.kind) {
-            case 'subflow':
-                decider = decider.addSubFlowChartBranch(branch.id, branch.chart, branch.name ?? branch.id, branch.mount);
-                break;
-            case 'lazy-subflow':
-                decider = decider.addLazySubFlowChartBranch(branch.id, branch.factory, branch.name ?? branch.id, branch.mount);
-                break;
-            case 'fn':
-                decider = decider.addFunctionBranch(branch.id, branch.name ?? branch.id, branch.fn, branch.description);
-                break;
-        }
-    }
-    builder = decider.setDefault(routing.defaultBranch).end();
-    // No post-decider memory stages: the final branch subflow owns
-    // finalize + commit/memory-write + break. Tool-calls branch falls
-    // through to loopTo below and iterates cleanly.
-    // Loop target depends on pattern:
-    //   Regular (default): loop to CallLLM — slots resolve once
-    //   Dynamic: loop to InstructionsToLLM (if mounted) or SystemPrompt
-    //     — instructions + all slots re-evaluate each iteration
-    const dynamicTarget = hasAgentInstructions ? 'sf-instructions-to-llm' : 'sf-system-prompt';
-    const loopTarget = config.pattern === types_1.AgentPattern.Dynamic ? dynamicTarget : 'call-llm';
-    builder = builder.loopTo(loopTarget);
-    if (options?.captureSpec) {
-        const spec = builder.toSpec();
-        return { chart: builder.build(), spec };
-    }
-    return { chart: builder.build() };
-}
-exports.buildAgentLoop = buildAgentLoop;
-/**
- * Wrap a base RoutingConfig with user-defined extensions.
- *
- * User extensions run BEFORE the base decider. First matching `when` predicate wins.
- * If no extension matches, base routing applies. Runners are mounted as subflows
- * when they expose `.toFlowChart()`; otherwise they are wrapped with runnerAsStage.
- */
-function extendDefaultRouting(base, extensions) {
-    // Each user branch is a TERMINAL fn stage: run the runner, write the content as the
-    // agent's final result, and break the loop. We don't mount as a subflow because we
-    // need terminate semantics in the parent loop — a subflow would return control to
-    // the decider and keep looping. Drill-down via runner.toFlowChart() is a future
-    // enhancement; for Phase 1 we optimize for correctness and simplicity.
-    const userBranches = extensions.map((ext, idx) => {
-        const id = ext.id ?? `route-${idx}`;
-        return {
-            id,
-            kind: 'fn',
-            fn: createRouteExtensionStage(ext.runner),
-            name: id,
-            description: `User routing branch '${id}'`,
-        };
-    });
-    const extendedBranches = [...userBranches, ...base.branches];
-    return {
-        deciderName: base.deciderName,
-        deciderId: base.deciderId,
-        deciderDescription: base.deciderDescription,
-        decider: (scope, breakFn, streamCb) => {
-            // User predicates evaluated first — first match wins.
-            for (let i = 0; i < extensions.length; i++) {
-                try {
-                    if (extensions[i].when(scope)) {
-                        return userBranches[i].id;
-                    }
-                }
-                catch (err) {
-                    // Predicate errors fall through to base routing (fail-open).
-                    // Warn in dev so the silent skip is visible — matches the
-                    // library-wide "silent skips must surface in dev" rule.
-                    if (isDevMode()) {
-                        console.warn(`[agentfootprint] .route() branch '${userBranches[i].id}' predicate threw — ` +
-                            `falling through to default routing.`, err);
-                    }
-                }
-            }
-            return base.decider(scope, breakFn, streamCb);
-        },
-        branches: extendedBranches,
-        defaultBranch: base.defaultBranch,
-    };
-}
-/**
- * Build a terminal stage fn that invokes a user-provided runner, writes its content
- * as the agent's final answer, and breaks the loop.
- *
- * Called when a user `.route()` branch predicate fires. The runner receives the last
- * user message as input; its output content becomes the agent's assistant response.
- */
-function createRouteExtensionStage(runner) {
-    return async (scope) => {
-        const messages = scope.messages ?? [];
-        const lastUser = [...messages].reverse().find((m) => m.role === 'user');
-        const input = typeof lastUser?.content === 'string'
-            ? lastUser.content
-            : Array.isArray(lastUser?.content)
-                ? lastUser.content
-                    .map((b) => (typeof b?.text === 'string' ? b.text : ''))
-                    .filter(Boolean)
-                    .join('\n')
-                : '';
-        const env = scope.$getEnv();
-        const signal = env?.signal;
-        const timeoutMs = env?.timeoutMs;
-        const output = await runner.run(input, { signal, timeoutMs });
-        const content = typeof output?.content === 'string' ? output.content : '';
-        // Append the runner's answer as an assistant message so downstream
-        // observers (narrative, recorders) see a coherent conversation.
-        scope.messages = [...messages, (0, messages_3.assistantMessage)(content)];
-        scope.result = content;
-        scope.$break();
-    };
-}
-/**
- * Validate the AgentLoopConfig at build time.
- */
-const isDevMode = () => typeof process !== 'undefined' && process.env?.['NODE_ENV'] !== 'production';
-function validateConfig(config) {
-    if (!config.provider) {
-        throw new Error('AgentLoopConfig: provider is required');
-    }
-    if (!config.systemPrompt) {
-        throw new Error('AgentLoopConfig: systemPrompt config is required');
-    }
-    if (!config.messages) {
-        throw new Error('AgentLoopConfig: messages config is required');
-    }
-    if (!config.tools) {
-        throw new Error('AgentLoopConfig: tools config is required');
-    }
-    if (!config.registry) {
-        throw new Error('AgentLoopConfig: registry is required');
-    }
-    if (config.maxIterations !== undefined && config.maxIterations < 0) {
-        throw new Error('AgentLoopConfig: maxIterations must be non-negative');
-    }
-    // Dev-mode warning: agentInstructions with activeWhen predicates but no initialDecision
-    if (isDevMode() && config.agentInstructions?.length && !config.initialDecision) {
-        const hasConditional = config.agentInstructions.some((i) => i.activeWhen);
-        if (hasConditional) {
-            console.warn('[agentfootprint] agentInstructions with activeWhen predicates provided but no initialDecision. ' +
-                'Decision scope will be {}, so conditional instructions may never fire.');
-        }
-    }
-}
-//# sourceMappingURL=buildAgentLoop.js.map