agentfootprint 2.11.1 → 2.11.2

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

@@ -0,0 +1,223 @@
+/**
+ * buildAgentChart — assemble the agent's full footprintjs FlowChart
+ * from stage functions + slot subflows + memory wiring.
+ *
+ * This is the "chart composition" that used to live inline in
+ * `Agent.buildChart()`. Extracted for v2.11.2 so:
+ *
+ *   1. Agent.ts focuses on Agent class lifecycle (constructor, run,
+ *      attach, getSpec) instead of chart wiring details.
+ *   2. The reliability gate chart (v2.11.x) wires into ONE focused
+ *      file rather than surgically into Agent.ts's 250-line composition
+ *      block.
+ *   3. The composition is independently readable + reviewable —
+ *      consumers building custom agent shapes have a reference.
+ *
+ * Chart shape:
+ *
+ *     Seed
+ *       → [memory READ subflows for each .memory()]
+ *       → InjectionEngine (subflow)
+ *       → SystemPrompt (slot subflow)
+ *       → Messages (slot subflow)
+ *       → Tools (slot subflow)
+ *       → CacheDecision (subflow)
+ *       → UpdateSkillHistory
+ *       → CacheGate (decider) → ApplyMarkers / SkipCaching
+ *       → IterationStart
+ *       → CallLLM
+ *       → Route (decider) → tool-calls (pausable) / final (subflow)
+ *                                                        |
+ *                          ┌────── PrepareFinal           ▼
+ *                          ├──── [memory WRITE subflows]
+ *                          └──── BreakFinal ($break)
+ *       loopTo(InjectionEngine)
+ *
+ * (When v2.11.x reliability is configured, the reliability gate chart
+ * mounts as a subflow between IterationStart and CallLLM with a
+ * TranslateFailFast stage after it. Lands in the next commit.)
+ */
+import { ArrayMergeMode } from 'footprintjs/advanced';
+import { flowChart } from 'footprintjs';
+import { STAGE_IDS, SUBFLOW_IDS } from '../../conventions.js';
+import { memoryInjectionKey } from '../../memory/define.types.js';
+import { unwrapMemoryFlowChart } from '../../memory/define.js';
+import { mountMemoryRead, mountMemoryWrite } from '../../memory/wire/mountMemoryPipeline.js';
+import { breakFinalStage } from './stages/breakFinal.js';
+import { prepareFinalStage } from './stages/prepareFinal.js';
+/**
+ * Build the agent's complete FlowChart from the supplied deps.
+ */
+export function buildAgentChart(deps) {
+    // ── Final-branch subflow ─────────────────────────────────────
+    // Split so memory-write subflows can mount BETWEEN setting
+    // finalContent and breaking the ReAct loop. PrepareFinal captures
+    // the turn payload; BreakFinal terminates the loop.
+    let finalBranchBuilder = flowChart('PrepareFinal', prepareFinalStage, 'prepare-final', undefined, 'Capture turn payload (finalContent + newMessages)');
+    for (const m of deps.memories) {
+        if (m.write) {
+            finalBranchBuilder = mountMemoryWrite(finalBranchBuilder, {
+                pipeline: {
+                    read: unwrapMemoryFlowChart(m.read),
+                    write: unwrapMemoryFlowChart(m.write),
+                },
+                identityKey: 'runIdentity',
+                turnNumberKey: 'turnNumber',
+                contextTokensKey: 'contextTokensRemaining',
+                newMessagesKey: 'newMessages',
+                writeSubflowId: `sf-memory-write-${m.id}`,
+            });
+        }
+    }
+    const finalBranchChart = finalBranchBuilder
+        .addFunction('BreakFinal', breakFinalStage, 'break-final', 'Terminate the ReAct loop')
+        .build();
+    // ── Main chart ──────────────────────────────────────────────
+    // Description prefix `Agent:` is a taxonomy marker — consumers
+    // (Lens + FlowchartRecorder) detect Agent-primitive subflows via
+    // this prefix and flag them as true agent boundaries (separate
+    // from LLMCall subflows which use `LLMCall:` prefix).
+    let builder = flowChart('Seed', deps.seed, STAGE_IDS.SEED, undefined, 'Agent: ReAct loop');
+    // Memory READ subflows — mounted between Seed and InjectionEngine
+    // for TURN_START timing (default). Each memory writes to its own
+    // scope key (`memoryInjection_${id}`) so multiple `.memory()`
+    // registrations layer without colliding.
+    for (const m of deps.memories) {
+        builder = mountMemoryRead(builder, {
+            pipeline: {
+                read: unwrapMemoryFlowChart(m.read),
+                ...(m.write !== undefined && { write: unwrapMemoryFlowChart(m.write) }),
+            },
+            identityKey: 'runIdentity',
+            turnNumberKey: 'turnNumber',
+            contextTokensKey: 'contextTokensRemaining',
+            injectionKey: memoryInjectionKey(m.id),
+            readSubflowId: `sf-memory-read-${m.id}`,
+        });
+    }
+    builder = builder
+        // Injection Engine — evaluates every Injection's trigger once
+        // per iteration; writes activeInjections[] to parent scope for
+        // the slot subflows to consume. Skipped if no injections were
+        // registered (no observable difference, just one more no-op
+        // subflow boundary).
+        .addSubFlowChartNext(SUBFLOW_IDS.INJECTION_ENGINE, deps.injectionEngineSubflow, 'Injection Engine', {
+        inputMapper: (parent) => ({
+            iteration: parent.iteration,
+            userMessage: parent.userMessage,
+            history: parent.history,
+            lastToolResult: parent.lastToolResult,
+            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.
+        arrayMerge: ArrayMergeMode.Replace,
+    })
+        .addSubFlowChartNext(SUBFLOW_IDS.SYSTEM_PROMPT, deps.systemPromptSubflow, 'System Prompt', {
+        inputMapper: (parent) => ({
+            userMessage: parent.userMessage,
+            iteration: parent.iteration,
+            activeInjections: parent.activeInjections,
+        }),
+        outputMapper: (sf) => ({ systemPromptInjections: sf.systemPromptInjections }),
+        arrayMerge: ArrayMergeMode.Replace,
+    })
+        .addSubFlowChartNext(SUBFLOW_IDS.MESSAGES, deps.messagesSubflow, 'Messages', {
+        inputMapper: (parent) => ({
+            messages: parent.history,
+            iteration: parent.iteration,
+            activeInjections: parent.activeInjections,
+        }),
+        outputMapper: (sf) => ({ messagesInjections: sf.messagesInjections }),
+        arrayMerge: ArrayMergeMode.Replace,
+    })
+        .addSubFlowChartNext(SUBFLOW_IDS.TOOLS, deps.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,
+            // Pass merged tool schemas (registry + injection-supplied)
+            // back up so callLLM uses the right list for THIS iteration.
+            dynamicToolSchemas: sf.toolSchemas,
+        }),
+        // Same array-concat hazard as InjectionEngine — replace, don't
+        // concatenate. Without Replace the deduped tool list re-acquires
+        // duplicates that providers reject.
+        arrayMerge: ArrayMergeMode.Replace,
+    })
+        // ── Cache layer (v2.6) ─────────────────────────────────────
+        .addSubFlowChartNext(SUBFLOW_IDS.CACHE_DECISION, deps.cacheDecisionSubflow, 'CacheDecision', {
+        inputMapper: (parent) => ({
+            activeInjections: parent.activeInjections ?? [],
+            iteration: parent.iteration ?? 1,
+            maxIterations: parent.maxIterations ?? deps.maxIterations,
+            userMessage: parent.userMessage ?? '',
+            ...(parent.lastToolResult !== undefined && {
+                lastToolName: parent.lastToolResult?.toolName,
+            }),
+            cumulativeInputTokens: parent.totalInputTokens ?? 0,
+            systemPromptCachePolicy: deps.systemPromptCachePolicy,
+            cachingDisabled: parent.cachingDisabled ?? false,
+        }),
+        outputMapper: (sf) => ({ cacheMarkers: sf.cacheMarkers }),
+        arrayMerge: ArrayMergeMode.Replace,
+    })
+        .addFunction('UpdateSkillHistory', deps.updateSkillHistoryStage, STAGE_IDS.UPDATE_SKILL_HISTORY, 'Update skill-history rolling window for CacheGate churn detection')
+        .addDeciderFunction('CacheGate', deps.cacheGateDecide, STAGE_IDS.CACHE_GATE, 'Gate cache-marker application: kill switch / hit-rate / skill-churn')
+        .addFunctionBranch(STAGE_IDS.APPLY_MARKERS, 'ApplyMarkers', 
+    // Pass-through stage — markers stay in scope as-is.
+    // BuildLLMRequest (Phase 7+) reads them on the next stage.
+    () => undefined, 'Proceed with cache markers from CacheDecision')
+        .addFunctionBranch(STAGE_IDS.SKIP_CACHING, 'SkipCaching', 
+    // Clear markers so BuildLLMRequest sees an empty list and
+    // makes the request unmodified.
+    (scope) => {
+        scope.cacheMarkers = [];
+    }, 'Skip caching this iteration')
+        .end()
+        .addFunction('IterationStart', deps.iterationStart, 'iteration-start', 'Iteration begin marker')
+        .addFunction('CallLLM', deps.callLLM, STAGE_IDS.CALL_LLM, 'LLM invocation')
+        .addDeciderFunction('Route', deps.routeDecider, SUBFLOW_IDS.ROUTE, 'ReAct routing')
+        .addPausableFunctionBranch('tool-calls', 'ToolCalls', deps.toolCallsHandler, 'Tool execution (pausable via pauseHere)')
+        .addSubFlowChartBranch('final', finalBranchChart, 'Final', {
+        // Pass through the read-only state the sub-chart needs;
+        // OMIT keys the sub-chart writes (finalContent, newMessages)
+        // — passing those via inputMapper would freeze them as args.
+        inputMapper: (parent) => {
+            const { finalContent: _f, newMessages: _nm, ...rest } = parent;
+            void _f;
+            void _nm;
+            return rest;
+        },
+        outputMapper: (sf) => ({
+            finalContent: sf.finalContent,
+        }),
+        // BreakFinal's $break() must reach the outer loopTo so the
+        // ReAct iteration terminates; without this the inner break
+        // only exits the sub-chart and the outer loop continues.
+        propagateBreak: true,
+    })
+        .setDefault('final')
+        .end()
+        // 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 — quietly breaking the framework's "Dynamic ReAct" claim.
+        .loopTo(SUBFLOW_IDS.INJECTION_ENGINE);
+    return builder.build();
+}
+//# sourceMappingURL=buildAgentChart.js.map

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

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

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

@@ -0,0 +1,111 @@
+/**
+ * buildToolRegistry — pure function that composes the agent's
+ * augmented tool registry from three sources:
+ *
+ *   1. **Static registry** — tools registered via `.tool()`. Always
+ *      visible to the LLM; always executable.
+ *   2. **`read_skill`** — auto-attached when ≥1 Skill is registered.
+ *      Activation tool for LLM-guided Skills.
+ *   3. **Skill-supplied tools** (`Skill.inject.tools[]`) — visible
+ *      only when the Skill is active (filtered by tools-slot subflow);
+ *      MUST always be in the executor registry so when the LLM calls
+ *      one, the tool-calls handler can dispatch.
+ *
+ * Tool-name uniqueness is enforced across all three sources at build
+ * time. The LLM only sees `tool.schema.name` (no ids), so names ARE
+ * the runtime dispatch key — collisions break the LLM's ability to
+ * call the right tool. Throw early instead of subtly shadowing.
+ *
+ * **Block C runtime — `autoActivate: 'currentSkill'` semantics:**
+ * When a skill's `defineSkill({ autoActivate: 'currentSkill' })` is
+ * set, its tools are EXCLUDED from the static registry. They flow
+ * into the LLM's tool list ONLY through `dynamicSchemas` (the
+ * buildToolsSlot path that reads activeInjections), which means
+ * they're visible ONLY on iterations after the skill is activated by
+ * `read_skill('id')`. Without this, the LLM sees every skill's tools
+ * on every iteration and the per-skill-narrowing autoActivate
+ * promised in `defineSkill` doesn't actually narrow anything. Skills
+ * WITHOUT autoActivate keep the v2.4 behavior (tools always visible)
+ * for back-compat.
+ *
+ * **autoActivate dispatch invariant:** autoActivate skill tools live
+ * OUTSIDE the LLM-visible registry (so they don't pollute the
+ * per-iteration tool list before the skill activates), but they MUST
+ * still be findable by the dispatch handler — the LLM calls them by
+ * name once the skill is active, and dispatch looks up by name. We
+ * add them to the dispatch map (`registryByName`) so `lookupTool`
+ * resolves correctly.
+ */
+import { buildReadSkillTool } from '../../lib/injection-engine/skillTools.js';
+/**
+ * Compose the augmented tool registry from the static `.tool()`
+ * registry + the agent's injections (skills only). Throws on tool-
+ * name collisions across sources.
+ */
+export function buildToolRegistry(registry, injections) {
+    const skills = 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.
+    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) {
+            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 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,
+    ];
+    // Final cross-source name-uniqueness check: static .tool() vs
+    // read_skill vs (deduped) skill tools. Catches collisions BETWEEN
+    // sources (e.g., a static .tool('foo') colliding with a Skill's foo).
+    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 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]));
+    // autoActivate skill tools live outside augmentedRegistry but MUST
+    // be findable by name at dispatch time. Add them to the dispatch
+    // map so `lookupTool` resolves correctly when the skill activates.
+    for (const [name, tool] of sharedSkillTools.entries()) {
+        if (!registryByName.has(name)) {
+            registryByName.set(name, tool);
+        }
+    }
+    const toolSchemas = augmentedRegistry.map((e) => e.tool.schema);
+    return { augmentedRegistry, registryByName, toolSchemas };
+}
+//# sourceMappingURL=buildToolRegistry.js.map

package/dist/esm/core/agent/buildToolRegistry.js.map

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

package/dist/esm/core/agent/stages/breakFinal.js

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

package/dist/esm/core/agent/stages/breakFinal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakFinal.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/breakFinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAA6B,EAAU,EAAE;IACvE,KAAK,CAAC,MAAM,EAAE,CAAC;IACf,OAAO,KAAK,CAAC,YAAY,CAAC;AAC5B,CAAC,CAAC"}

package/dist/esm/core/agent/stages/callLLM.js

@@ -0,0 +1,125 @@
+/**
+ * callLLM — the LLM-invocation stage of the agent's chart.
+ *
+ * Reads the assembled prompt + messages from scope (populated by the
+ * upstream slot subflows: SystemPrompt, Messages, Tools, CacheDecision,
+ * CacheGate). Calls `provider.stream()` if available (token streaming
+ * with per-chunk events) else falls back to `provider.complete()`.
+ * Writes the response to scope (`llmLatestContent`, `llmLatestToolCalls`,
+ * cumulative tokens) for the downstream Route decider to read.
+ *
+ * Emits `agentfootprint.stream.llm_start` + `llm_end` brackets for
+ * observability adapters and per-chunk `stream.token` events during
+ * streaming. Emits `cost.tick` via `emitCostTick` when a `pricingTable`
+ * is configured.
+ *
+ * Factory signature so the chart-build-time provider/model/etc. deps
+ * are explicit. The `toolSchemas` value is late-bound via a getter
+ * because tool schema composition completes after the seed factory is
+ * built but before the chart actually runs.
+ */
+import { typedEmit } from '../../../recorders/core/typedEmit.js';
+import { emitCostTick } from '../../cost.js';
+/**
+ * Build the callLLM stage function. Captures the LLM provider + model
+ * config + cache strategy via the deps object; everything per-iteration
+ * comes from scope.
+ */
+export function buildCallLLMStage(deps) {
+    return async (scope) => {
+        const systemPromptInjections = scope.systemPromptInjections ?? [];
+        // `scope.messagesInjections` is read by ContextRecorder for
+        // observability; the LLM-wire path now reads scope.history directly.
+        const iteration = scope.iteration;
+        const systemPrompt = systemPromptInjections
+            .map((r) => r.rawContent ?? '')
+            .filter((s) => s.length > 0)
+            .join('\n\n');
+        // Read the LLM message stream from `scope.history` directly. The
+        // `messagesInjections` projection is for observability — 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: deps.provider.name,
+            model: deps.model,
+            systemPromptChars: systemPrompt.length,
+            messagesCount: messages.length,
+            toolsCount: deps.toolSchemas.length,
+            ...(deps.temperature !== undefined && { temperature: deps.temperature }),
+        });
+        const startMs = Date.now();
+        // Use dynamic schemas — registry tools + injection-supplied tools
+        // (Skills' `inject.tools` when their Injection is active). Falls
+        // back to the static schemas at startup before the tools slot has
+        // run for the first time.
+        const activeToolSchemas = scope.dynamicToolSchemas ?? deps.toolSchemas;
+        const baseRequest = {
+            ...(systemPrompt.length > 0 && { systemPrompt }),
+            messages,
+            ...(activeToolSchemas.length > 0 && { tools: activeToolSchemas }),
+            model: deps.model,
+            ...(deps.temperature !== undefined && { temperature: deps.temperature }),
+            ...(deps.maxTokens !== undefined && { maxTokens: deps.maxTokens }),
+        };
+        // v2.6+ — call cache strategy to attach provider-specific cache
+        // hints. CacheGate has already routed (apply-markers / no-markers)
+        // and populated scope.cacheMarkers accordingly. Strategy.prepareRequest
+        // is a pass-through for empty markers.
+        const cacheMarkers = scope.cacheMarkers ?? [];
+        const cachePrepared = await deps.cacheStrategy.prepareRequest(baseRequest, cacheMarkers, {
+            iteration,
+            iterationsRemaining: Math.max(0, deps.maxIterations - iteration),
+            recentHitRate: scope.recentHitRate,
+            cachingDisabled: scope.cachingDisabled ?? false,
+        });
+        const llmRequest = cachePrepared.request;
+        // Streaming-first: when the provider implements `stream()` we
+        // consume chunk-by-chunk so consumers see tokens as they arrive
+        // instead of waiting for the full LLM call to finish. Each
+        // non-terminal chunk fires `agentfootprint.stream.token`. The
+        // terminal chunk SHOULD carry the authoritative `LLMResponse`;
+        // when it doesn't (older providers, partial implementations) we
+        // fall back to `complete()` for the authoritative payload —
+        // keeping the ReAct loop deterministic.
+        let response;
+        if (deps.provider.stream) {
+            for await (const chunk of deps.provider.stream(llmRequest)) {
+                if (chunk.done) {
+                    if (chunk.response)
+                        response = chunk.response;
+                    break;
+                }
+                if (chunk.content.length > 0) {
+                    typedEmit(scope, 'agentfootprint.stream.token', {
+                        iteration,
+                        tokenIndex: chunk.tokenIndex,
+                        content: chunk.content,
+                    });
+                }
+            }
+        }
+        if (!response) {
+            // No `stream()` OR stream finished without a response payload.
+            response = await deps.provider.complete(llmRequest);
+        }
+        const durationMs = Date.now() - startMs;
+        scope.totalInputTokens = scope.totalInputTokens + response.usage.input;
+        scope.totalOutputTokens = scope.totalOutputTokens + response.usage.output;
+        scope.llmLatestContent = response.content;
+        scope.llmLatestToolCalls = response.toolCalls;
+        typedEmit(scope, 'agentfootprint.stream.llm_end', {
+            iteration,
+            content: response.content,
+            toolCallCount: response.toolCalls.length,
+            usage: response.usage,
+            stopReason: response.stopReason,
+            durationMs,
+        });
+        emitCostTick(scope, deps.pricingTable, deps.costBudget, deps.model, response.usage);
+    };
+}
+//# sourceMappingURL=callLLM.js.map

package/dist/esm/core/agent/stages/callLLM.js.map

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

package/dist/esm/core/agent/stages/iterationStart.js

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

package/dist/esm/core/agent/stages/iterationStart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterationStart.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/iterationStart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAGjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACzE,SAAS,CAAC,KAAK,EAAE,sCAAsC,EAAE;QACvD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,KAAK,CAAC,SAAS;KAC3B,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/esm/core/agent/stages/prepareFinal.js

@@ -0,0 +1,41 @@
+/**
+ * prepareFinal — first stage of the agent's "Final" branch subflow.
+ *
+ * Captures the turn payload (`finalContent` from the LLM's latest
+ * content; `newMessages` as the `[user, assistant]` pair the memory-
+ * write subflows persist) and emits the per-turn observability
+ * brackets (`iteration_end`, `turn_end`).
+ *
+ * Mounted as the FIRST stage of the final-branch subflow built in
+ * `buildAgentChart`. Subsequent memory-write subflows mount AFTER this
+ * stage so they have `newMessages` available; `breakFinal` is the
+ * terminal stage that stops the ReAct loop.
+ *
+ * Pure function — no closure over Agent class state. Imported and
+ * passed directly to `flowChart(...)` in buildAgentChart.
+ */
+import { typedEmit } from '../../../recorders/core/typedEmit.js';
+export const prepareFinalStage = (scope) => {
+    const iteration = scope.iteration;
+    scope.finalContent = scope.llmLatestContent;
+    // The turn payload memory writes persist: the user's message
+    // paired with the agent's final answer.
+    scope.newMessages = [
+        { role: 'user', content: scope.userMessage },
+        { role: 'assistant', content: scope.finalContent },
+    ];
+    typedEmit(scope, 'agentfootprint.agent.iteration_end', {
+        turnIndex: 0,
+        iterIndex: iteration,
+        toolCallCount: 0,
+    });
+    typedEmit(scope, 'agentfootprint.agent.turn_end', {
+        turnIndex: 0,
+        finalContent: scope.finalContent,
+        totalInputTokens: scope.totalInputTokens,
+        totalOutputTokens: scope.totalOutputTokens,
+        iterationCount: iteration,
+        durationMs: Date.now() - scope.turnStartMs,
+    });
+};
+//# sourceMappingURL=prepareFinal.js.map

package/dist/esm/core/agent/stages/prepareFinal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareFinal.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAGjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACvE,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAClC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,gBAAgB,CAAC;IAC5C,6DAA6D;IAC7D,wCAAwC;IACxC,KAAK,CAAC,WAAW,GAAG;QAClB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE;QAC5C,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,YAAY,EAAE;KACnD,CAAC;IAEF,SAAS,CAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,SAAS,CAAC,KAAK,EAAE,+BAA+B,EAAE;QAChD,SAAS,EAAE,CAAC;QACZ,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,cAAc,EAAE,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,WAAW;KAC3C,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/esm/core/agent/stages/route.js

@@ -0,0 +1,32 @@
+/**
+ * route — decider that branches the ReAct loop into 'tool-calls' or 'final'.
+ *
+ * Runs after CallLLM. If the LLM returned tool calls AND we haven't hit
+ * `maxIterations`, route to the tool execution branch (which loops back
+ * to PromptBuilder). Otherwise route to the final-branch subflow which
+ * persists memory writes and breaks the loop.
+ *
+ * Emits `agentfootprint.agent.route_decided` with the chosen branch +
+ * a human-readable rationale (visible in narrative + observability).
+ *
+ * Pure function — no closure over Agent class state. Imported and
+ * passed directly to `addDeciderFunction(...)` in buildAgentChart.
+ */
+import { typedEmit } from '../../../recorders/core/typedEmit.js';
+export const routeDeciderStage = (scope) => {
+    const toolCalls = scope.llmLatestToolCalls;
+    const iteration = scope.iteration;
+    const chosen = toolCalls.length > 0 && iteration < scope.maxIterations ? 'tool-calls' : 'final';
+    typedEmit(scope, 'agentfootprint.agent.route_decided', {
+        turnIndex: 0,
+        iterIndex: iteration,
+        chosen,
+        rationale: chosen === 'tool-calls'
+            ? `LLM requested ${toolCalls.length} tool call(s)`
+            : iteration >= scope.maxIterations
+                ? 'maxIterations reached — forcing final'
+                : 'LLM produced no tool calls — final answer',
+    });
+    return chosen;
+};
+//# sourceMappingURL=route.js.map

package/dist/esm/core/agent/stages/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAKjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAA6B,EAAe,EAAE;IAC9E,MAAM,SAAS,GAAG,KAAK,CAAC,kBAAiD,CAAC;IAC1E,MAAM,SAAS,GAAG,KAAK,CAAC,SAAmB,CAAC;IAC5C,MAAM,MAAM,GACV,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;IAEnF,SAAS,CAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,MAAM;QACN,SAAS,EACP,MAAM,KAAK,YAAY;YACrB,CAAC,CAAC,iBAAiB,SAAS,CAAC,MAAM,eAAe;YAClD,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,aAAa;gBAClC,CAAC,CAAC,uCAAuC;gBACzC,CAAC,CAAC,2CAA2C;KAClD,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}