agentfootprint 1.0.0

package/dist/lib/narrative/agentRenderer.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Agent NarrativeRenderer — LLM-optimized narrative for agent loop execution.
+ *
+ * Designed for LLM follow-up reasoning: the narrative answers "what happened?"
+ * so a downstream LLM can ask informed questions about the agent's execution.
+ *
+ * Key design decisions:
+ *   1. Enrichment keys (llmCall, responseType, resolvedTools, promptSummary)
+ *      are promoted — their values ARE the narrative, shown directly.
+ *   2. Internal keys (memory_*, loopCount, adapter internals) are suppressed.
+ *   3. Core keys (messages, result) get smart formatting with counts/previews.
+ *   4. Most reads are suppressed — writes tell the story, reads are noise.
+ *      Exception: `parsedResponse` reads are shown in tool execution (tool names + args).
+ *   5. Stage headers use agent terminology, not generic "The process began."
+ *   6. Subflow boundaries use slot names: "Preparing system prompt."
+ *   7. Loop/break use agent language: "Tool loop iteration N", "Agent completed."
+ *
+ * The entry types (stage, step, subflow, loop, break, error, condition, fork,
+ * selector) and stageId/subflowId fields are preserved by the recorder — the
+ * renderer only controls the text. Time-travel UI sync is unaffected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentRenderer = void 0;
+// ── Stage name → agent-specific label ────────────────────────────────────────
+const STAGE_LABELS = {
+    Seed: 'Initialized agent state',
+    ResolvePrompt: 'Resolved system prompt',
+    LoadHistory: 'Loaded conversation history',
+    ApplyStrategy: 'Applied message strategy',
+    TrackPrepared: 'Tracked prepared messages',
+    ResolveTools: 'Resolved available tools',
+    AssemblePrompt: 'Assembled final prompt',
+    CallLLM: 'Called LLM',
+    ParseResponse: 'Parsed LLM response',
+    ExecuteToolCalls: 'Executed tool calls',
+    HandleResponse: 'Processed response',
+    CommitMemory: 'Committed conversation history',
+    // Swarm-specific stages
+    RouteSpecialist: 'Route to specialist',
+    ExecuteExtraTool: 'Executed extra tool',
+    Finalize: 'Extract final answer and stop the loop',
+};
+// ── Subflow name → agent-specific entry label ────────────────────────────────
+const SUBFLOW_ENTRY_LABELS = {
+    SystemPrompt: 'Preparing system prompt',
+    Messages: 'Preparing conversation history',
+    Tools: 'Resolving available tools',
+    PrepareMemory: 'Preparing memory',
+    ExecuteTools: 'Executing tool calls',
+};
+// ── Promoted keys: pre-formatted enrichment summaries ────────────────────────
+const PROMOTED_LABELS = {
+    llmCall: 'LLM',
+    responseType: 'Response',
+    resolvedTools: 'Tools',
+    promptSummary: 'Prompt',
+    // SlotDecision labels — shown when non-static (dynamic providers explain their choice)
+    promptDecision: 'Chose',
+    toolDecision: 'Chose',
+    specialistResult: 'Specialist returned',
+};
+// ── Suppressed keys: true internals that add noise, not insight ──────────────
+//
+// Design principle: suppress ONLY implementation plumbing. If an LLM reading
+// this trace would need the value to answer a follow-up question, don't suppress.
+const SUPPRESSED_KEYS = new Set([
+    // Loop control (the loop entry itself shows iteration count)
+    'loopCount', 'maxIterations', 'updatedLoopCount',
+    // Memory internals (memory subflow stages already narrate this)
+    'memory_preparedMessages', 'memory_storedHistory', 'memory_shouldCommit',
+    // adapterResult is redundant with parsedResponse
+    'adapterResult',
+    // adapterRawResponse is now shown — contains LLM reasoning + token usage
+    // Swarm internals (the decision is shown by RouteSpecialist, not these keys)
+    'specialistMessage', 'specialistToolCallId',
+    // Subflow intermediate state
+    'currentMessages',
+    // Enrichment summaries (avoid double-reporting — the promoted labels above show these)
+    'llmCall', 'responseType', 'resolvedTools', 'promptSummary',
+]);
+const DEFAULT_LIMITS = {
+    result: 100,
+    systemPrompt: 200,
+    parsedContent: 100,
+    toolResult: 80,
+    toolArgs: 60,
+    message: 100,
+};
+const VERBOSE_LIMITS = {
+    result: Infinity,
+    systemPrompt: Infinity,
+    parsedContent: Infinity,
+    toolResult: Infinity,
+    toolArgs: Infinity,
+    message: Infinity,
+};
+function truncate(value, max) {
+    if (max === Infinity || value.length <= max)
+        return value;
+    return value.slice(0, max) + '...';
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function formatMessages(rawValue) {
+    if (!Array.isArray(rawValue))
+        return 'Messages: (empty)';
+    const messages = rawValue;
+    const count = messages.length;
+    if (count === 0)
+        return 'Messages: (empty)';
+    const roles = new Map();
+    for (const m of messages) {
+        const role = m.role ?? 'unknown';
+        roles.set(role, (roles.get(role) ?? 0) + 1);
+    }
+    const breakdown = [...roles.entries()].map(([r, n]) => `${n} ${r}`).join(', ');
+    return `Messages: ${count} (${breakdown})`;
+}
+function formatResult(rawValue, limits) {
+    if (typeof rawValue !== 'string')
+        return 'Result: (non-string)';
+    if (rawValue.length === 0)
+        return 'Result: (empty)';
+    return `Result: "${truncate(rawValue, limits.result)}"`;
+}
+function formatSystemPrompt(rawValue, limits) {
+    if (typeof rawValue !== 'string' || rawValue.length === 0)
+        return 'System prompt: (none)';
+    return `System prompt: "${truncate(rawValue, limits.systemPrompt)}"`;
+}
+function formatToolDescriptions(rawValue) {
+    if (!Array.isArray(rawValue) || rawValue.length === 0)
+        return 'Tools: (none)';
+    const names = rawValue.map((t) => t.name ?? '?').join(', ');
+    return `Tools: [${names}]`;
+}
+function formatParsedResponse(rawValue, limits) {
+    if (!rawValue || typeof rawValue !== 'object')
+        return 'Parsed: (unknown)';
+    const r = rawValue;
+    if (r.hasToolCalls && Array.isArray(r.toolCalls)) {
+        const toolSummaries = r.toolCalls.map((tc) => {
+            const name = tc.name ?? '?';
+            if (tc.arguments && Object.keys(tc.arguments).length > 0) {
+                const argsStr = JSON.stringify(tc.arguments);
+                return `${name}(${truncate(argsStr, limits.toolArgs)})`;
+            }
+            return name;
+        });
+        return `Parsed: tool_calls → [${toolSummaries.join(', ')}]`;
+    }
+    if (typeof r.content === 'string') {
+        return `Parsed: final → "${truncate(r.content, limits.parsedContent)}"`;
+    }
+    return 'Parsed: (unknown)';
+}
+function formatToolResultMessages(rawValue, limits) {
+    if (!Array.isArray(rawValue) || rawValue.length === 0)
+        return 'Tool results: (none)';
+    const results = rawValue;
+    const summaries = results.map((msg) => {
+        const content = typeof msg.content === 'string' ? msg.content : '';
+        return `"${truncate(content, limits.toolResult)}"`;
+    });
+    return `Tool results: ${summaries.join('; ')}`;
+}
+function formatAdapterRawResponse(rawValue, limits) {
+    if (!rawValue || typeof rawValue !== 'object')
+        return 'LLM response: (unknown)';
+    const r = rawValue;
+    const parts = [];
+    // Model + tokens
+    if (r.model || r.usage) {
+        const model = r.model ?? 'unknown';
+        const usage = r.usage
+            ? `${r.usage.inputTokens ?? '?'}in / ${r.usage.outputTokens ?? '?'}out`
+            : '';
+        parts.push(`LLM: ${model}${usage ? ` (${usage})` : ''}`);
+    }
+    // LLM reasoning text (the key insight — why it chose to call tools)
+    if (r.content && r.content.length > 0) {
+        parts.push(`Reasoning: "${truncate(r.content, limits.parsedContent)}"`);
+    }
+    // Tool calls summary
+    if (r.toolCalls && r.toolCalls.length > 0) {
+        const names = r.toolCalls.map((tc) => tc.name ?? '?').join(', ');
+        parts.push(`→ tool_calls: [${names}]`);
+    }
+    return parts.join('\n  ');
+}
+// ── Renderer factory ─────────────────────────────────────────────────────────
+/**
+ * Create an agent-optimized NarrativeRenderer.
+ *
+ * Usage:
+ * ```typescript
+ * import { createAgentRenderer } from 'agentfootprint';
+ *
+ * executor.enableNarrative({ renderer: createAgentRenderer() });
+ * ```
+ *
+ * Or with the narrative() factory:
+ * ```typescript
+ * import { narrative } from 'footprintjs/recorders';
+ * import { createAgentRenderer } from 'agentfootprint';
+ *
+ * const rec = narrative({ renderer: createAgentRenderer() });
+ * ```
+ */
+function createAgentRenderer(options) {
+    const limits = options?.verbose ? VERBOSE_LIMITS : DEFAULT_LIMITS;
+    return {
+        renderStage(ctx) {
+            const label = STAGE_LABELS[ctx.stageName];
+            if (label)
+                return `[${ctx.stageName}] ${label}`;
+            // Unknown stage — use description if available
+            if (ctx.description)
+                return `[${ctx.stageName}] ${ctx.description}`;
+            return `[${ctx.stageName}]`;
+        },
+        renderOp(ctx) {
+            const { key, type, rawValue, operation } = ctx;
+            // Suppress all reads — writes tell the story.
+            // parsedResponse is already shown at the ParseResponse write stage.
+            if (type === 'read')
+                return null;
+            // Suppress internal keys
+            if (SUPPRESSED_KEYS.has(key))
+                return null;
+            // Promoted keys: their value IS the narrative
+            if (PROMOTED_LABELS[key]) {
+                // Suppress when value is undefined/null (e.g., static providers don't set decision keys)
+                if (rawValue == null)
+                    return null;
+                return `${PROMOTED_LABELS[key]}: ${String(rawValue)}`;
+            }
+            // Delete operation
+            if (operation === 'delete')
+                return `Cleared ${key}`;
+            // ── Key-specific formatters (actual values for LLM context) ──
+            if (key === 'messages')
+                return formatMessages(rawValue);
+            if (key === 'result')
+                return formatResult(rawValue, limits);
+            if (key === 'systemPrompt')
+                return formatSystemPrompt(rawValue, limits);
+            if (key === 'toolDescriptions')
+                return formatToolDescriptions(rawValue);
+            if (key === 'parsedResponse')
+                return formatParsedResponse(rawValue, limits);
+            if (key === 'toolResultMessages')
+                return formatToolResultMessages(rawValue, limits);
+            if (key === 'adapterRawResponse')
+                return formatAdapterRawResponse(rawValue, limits);
+            // message (singular): user input in subflow mode
+            if (key === 'message' && typeof rawValue === 'string') {
+                return `User: "${truncate(rawValue, limits.message)}"`;
+            }
+            // Default: simple write summary
+            return `${operation === 'update' ? 'Updated' : 'Set'} ${key} = ${ctx.valueSummary}`;
+        },
+        renderSubflow(ctx) {
+            if (ctx.direction === 'exit')
+                return `Done: ${ctx.name}`;
+            return SUBFLOW_ENTRY_LABELS[ctx.name] ?? `Entering ${ctx.name}`;
+        },
+        renderLoop(ctx) {
+            return `Tool loop iteration ${ctx.iteration}: re-calling LLM`;
+        },
+        renderBreak(ctx) {
+            return `Agent completed at ${ctx.stageName}`;
+        },
+        renderError(ctx) {
+            let text = `Error at ${ctx.stageName}: ${ctx.message}`;
+            if (ctx.validationIssues)
+                text += ` (${ctx.validationIssues})`;
+            return text;
+        },
+        renderDecision(ctx) {
+            // Keep it concise — the stage header already has the description.
+            // Only add rationale if it differs from the description.
+            if (ctx.rationale && ctx.rationale !== ctx.description) {
+                return `Chose ${ctx.chosen} (${ctx.rationale})`;
+            }
+            return `Chose ${ctx.chosen}`;
+        },
+        renderFork(ctx) {
+            return `Parallel: ${ctx.children.join(', ')}`;
+        },
+        renderSelected(ctx) {
+            return `Selected ${ctx.selected.length}/${ctx.total}: ${ctx.selected.join(', ')}`;
+        },
+    };
+}
+exports.createAgentRenderer = createAgentRenderer;
+//# sourceMappingURL=agentRenderer.js.map

package/dist/lib/narrative/agentRenderer.js.map

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

package/dist/lib/narrative/groundingHelpers.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Grounding helpers — extract sources, claims, and cross-reference data
+ * from CombinedNarrativeRecorder entries.
+ *
+ * Uses the `key` field on entries (the scope key that was written) for
+ * structured data extraction. No dependency on rendered text strings or
+ * stage names — works with any NarrativeRenderer and any flowchart topology.
+ *
+ * Usage:
+ *   const entries = executor.getNarrativeEntries();
+ *   const sources = getGroundingSources(entries);
+ *   const claims = getLLMClaims(entries);
+ *   const context = getFullLLMContext(entries);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFullLLMContext = exports.getLLMClaims = exports.getGroundingSources = void 0;
+const types_1 = require("../../scope/types");
+// ── Extractors ───────────────────────────────────────────────────────────────
+/**
+ * Extract grounding sources (tool results) from narrative entries.
+ *
+ * Matches on `entry.key === 'toolResultMessages'` — the scope key written
+ * by the ExecuteToolCalls stage. Renderer-independent and topology-independent.
+ *
+ * @example
+ * ```typescript
+ * const entries = agent.getNarrativeEntries();
+ * const sources = getGroundingSources(entries);
+ * // [{ stageName: 'ExecuteToolCalls', content: '{"orderId":"ORD-1003",...}', parsed: {...} }]
+ * ```
+ */
+function getGroundingSources(entries) {
+    const sources = [];
+    for (const entry of entries) {
+        if (entry.type !== 'step' || entry.key !== types_1.AgentScopeKey.ToolResultMessages)
+            continue;
+        const messages = entry.rawValue;
+        if (!Array.isArray(messages))
+            continue;
+        for (const msg of messages) {
+            if (msg.role === 'tool' && typeof msg.content === 'string') {
+                let parsed;
+                try {
+                    parsed = JSON.parse(msg.content);
+                }
+                catch {
+                    parsed = msg.content;
+                }
+                sources.push({
+                    stageName: entry.stageName ?? 'unknown',
+                    stageId: entry.stageId,
+                    subflowId: entry.subflowId,
+                    content: msg.content,
+                    parsed,
+                });
+            }
+        }
+    }
+    return sources;
+}
+exports.getGroundingSources = getGroundingSources;
+/**
+ * Extract LLM output claims from narrative entries.
+ *
+ * Final claims from `entry.key === AgentScopeKey.Result`.
+ * Intermediate claims from `entry.key === AgentScopeKey.ParsedResponse` where content is final (not tool_calls).
+ *
+ * @example
+ * ```typescript
+ * const claims = getLLMClaims(agent.getNarrativeEntries());
+ * // [{ content: 'Your order was denied...', type: 'final' }]
+ * ```
+ */
+function getLLMClaims(entries) {
+    const claims = [];
+    for (const entry of entries) {
+        if (entry.type !== 'step')
+            continue;
+        if (entry.key === types_1.AgentScopeKey.Result) {
+            const content = entry.rawValue;
+            if (typeof content === 'string' && content.length > 0) {
+                claims.push({
+                    stageName: entry.stageName ?? 'unknown',
+                    stageId: entry.stageId,
+                    content,
+                    type: 'final',
+                });
+            }
+        }
+        if (entry.key === types_1.AgentScopeKey.ParsedResponse) {
+            const parsed = entry.rawValue;
+            if (parsed && !parsed.hasToolCalls && typeof parsed.content === 'string' && parsed.content.length > 0) {
+                claims.push({
+                    stageName: entry.stageName ?? 'unknown',
+                    stageId: entry.stageId,
+                    content: parsed.content,
+                    type: 'intermediate',
+                });
+            }
+        }
+    }
+    return claims;
+}
+exports.getLLMClaims = getLLMClaims;
+/**
+ * Build a full LLM context snapshot from narrative entries.
+ *
+ * Extracts everything the LLM saw and produced. Uses scope keys for matching:
+ * - `systemPrompt` — system prompt text (last value, may change in Dynamic mode)
+ * - `toolDescriptions` — tool descriptions sent to LLM
+ * - `toolResultMessages` — tool results (sources of truth)
+ * - `result` / `parsedResponse` — LLM outputs (claims)
+ * - `decision` — Decision Scope state
+ */
+function getFullLLMContext(entries) {
+    let systemPrompt;
+    let toolDescriptions;
+    let decision;
+    for (const entry of entries) {
+        if (entry.type !== 'step')
+            continue;
+        if (entry.key === types_1.AgentScopeKey.SystemPrompt && typeof entry.rawValue === 'string') {
+            systemPrompt = entry.rawValue;
+        }
+        if (entry.key === types_1.AgentScopeKey.ToolDescriptions && Array.isArray(entry.rawValue)) {
+            toolDescriptions = entry.rawValue;
+        }
+        if (entry.key === types_1.AgentScopeKey.Decision && entry.rawValue && typeof entry.rawValue === 'object' && !Array.isArray(entry.rawValue)) {
+            decision = entry.rawValue;
+        }
+    }
+    return {
+        systemPrompt,
+        toolDescriptions,
+        sources: getGroundingSources(entries),
+        claims: getLLMClaims(entries),
+        decision,
+    };
+}
+exports.getFullLLMContext = getFullLLMContext;
+//# sourceMappingURL=groundingHelpers.js.map

package/dist/lib/narrative/groundingHelpers.js.map

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

package/dist/lib/narrative/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFullLLMContext = exports.getLLMClaims = exports.getGroundingSources = exports.createAgentRenderer = void 0;
+var agentRenderer_js_1 = require("./agentRenderer.js");
+Object.defineProperty(exports, "createAgentRenderer", { enumerable: true, get: function () { return agentRenderer_js_1.createAgentRenderer; } });
+var groundingHelpers_js_1 = require("./groundingHelpers.js");
+Object.defineProperty(exports, "getGroundingSources", { enumerable: true, get: function () { return groundingHelpers_js_1.getGroundingSources; } });
+Object.defineProperty(exports, "getLLMClaims", { enumerable: true, get: function () { return groundingHelpers_js_1.getLLMClaims; } });
+Object.defineProperty(exports, "getFullLLMContext", { enumerable: true, get: function () { return groundingHelpers_js_1.getFullLLMContext; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/narrative/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/narrative/index.ts"],"names":[],"mappings":";;;AAAA,uDAAyD;AAAhD,uHAAA,mBAAmB,OAAA;AAG5B,6DAA6F;AAApF,0HAAA,mBAAmB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAAE,wHAAA,iBAAiB,OAAA"}

package/dist/lib/slots/helpers.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Shared helpers for slot subflows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTextContent = exports.findLastUserMessage = void 0;
+/**
+ * Find the last user message in the history by iterating backward.
+ * O(1) allocation — no array copy.
+ */
+function findLastUserMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === 'user')
+            return messages[i];
+    }
+    return undefined;
+}
+exports.findLastUserMessage = findLastUserMessage;
+/**
+ * Extract the text content from a message's content field.
+ * Returns empty string for multimodal (array) content — providers that need
+ * multimodal should read the full history/messages array directly.
+ */
+function extractTextContent(message) {
+    return typeof message.content === 'string' ? message.content : '';
+}
+exports.extractTextContent = extractTextContent;
+//# sourceMappingURL=helpers.js.map

package/dist/lib/slots/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/lib/slots/helpers.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAIH;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,QAAmB;IACrD,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AALD,kDAKC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,OAAgB;IACjD,OAAO,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC;AAFD,gDAEC"}

package/dist/lib/slots/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildToolsSubflow = exports.buildMessagesSubflow = exports.buildSystemPromptSubflow = void 0;
+var system_prompt_1 = require("./system-prompt");
+Object.defineProperty(exports, "buildSystemPromptSubflow", { enumerable: true, get: function () { return system_prompt_1.buildSystemPromptSubflow; } });
+var messages_1 = require("./messages");
+Object.defineProperty(exports, "buildMessagesSubflow", { enumerable: true, get: function () { return messages_1.buildMessagesSubflow; } });
+var tools_1 = require("./tools");
+Object.defineProperty(exports, "buildToolsSubflow", { enumerable: true, get: function () { return tools_1.buildToolsSubflow; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/slots/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/slots/index.ts"],"names":[],"mappings":";;;AAAA,iDAA2D;AAAlD,yHAAA,wBAAwB,OAAA;AAGjC,uCAAkD;AAAzC,gHAAA,oBAAoB,OAAA;AAG7B,iCAA4C;AAAnC,0GAAA,iBAAiB,OAAA"}

package/dist/lib/slots/messages/buildMessagesSubflow.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Messages slot — builds a subflow that prepares conversation history.
+ *
+ * Always a subflow because:
+ *   - Config determines complexity: 1 stage (in-memory) or 3 stages (persistent)
+ *   - Parent chart never changes when memory backend grows
+ *   - BehindTheScenes drill-down shows exactly how messages were prepared
+ *
+ * State key convention (typed via MessagesSubflowState):
+ *   Input:  `currentMessages` — set by inputMapper from parent's `messages`
+ *   Output: `memory_preparedMessages` — read by outputMapper, copied to parent's `messages`
+ *   Output: `memory_storedHistory` — (persistent only) for CommitMemory reconstruction
+ *
+ * In-memory mode (no store):
+ *   [ApplyStrategy]
+ *
+ * Persistent mode (with store):
+ *   [LoadHistory → ApplyStrategy → TrackPrepared]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMessagesSubflow = void 0;
+const footprintjs_1 = require("footprintjs");
+const helpers_1 = require("../helpers");
+/**
+ * Build a MessageContext from scope state.
+ */
+function buildMessageContext(scope, messages) {
+    const loopCount = scope.loopCount ?? 0;
+    const lastUserMsg = (0, helpers_1.findLastUserMessage)(messages);
+    const message = lastUserMsg ? (0, helpers_1.extractTextContent)(lastUserMsg) : '';
+    return {
+        message,
+        turnNumber: loopCount,
+        loopIteration: loopCount,
+        signal: scope.$getEnv()?.signal,
+    };
+}
+/**
+ * Build the Messages slot subflow from config.
+ *
+ * Mount with:
+ * ```typescript
+ * builder.addSubFlowChartNext('sf-messages', buildMessagesSubflow(config), 'Messages', {
+ *   inputMapper: (parent) => ({
+ *     currentMessages: parent.messages ?? [],
+ *     loopCount: parent.loopCount ?? 0,
+ *   }),
+ *   outputMapper: (sfOutput) => ({
+ *     memory_preparedMessages: sfOutput.memory_preparedMessages,
+ *     memory_storedHistory: sfOutput.memory_storedHistory,
+ *   }),
+ * })
+ * ```
+ */
+function buildMessagesSubflow(config) {
+    if (!config.strategy) {
+        throw new Error('MessagesSlotConfig: strategy is required');
+    }
+    if (config.store && !config.conversationId) {
+        throw new Error('MessagesSlotConfig: conversationId is required when store is provided');
+    }
+    if (config.store && config.conversationId) {
+        return buildPersistentSubflow(config.strategy, config.store, config.conversationId);
+    }
+    return buildInMemorySubflow(config.strategy);
+}
+exports.buildMessagesSubflow = buildMessagesSubflow;
+/**
+ * In-memory mode: single stage that applies strategy to currentMessages.
+ * Writes result to memory_preparedMessages (outputMapper copies to parent's messages).
+ */
+function buildInMemorySubflow(strategy) {
+    return (0, footprintjs_1.flowChart)('ApplyStrategy', async (scope) => {
+        const messages = scope.currentMessages ?? [];
+        const ctx = buildMessageContext(scope, messages);
+        const decision = await strategy.prepare(messages, ctx);
+        scope.memory_preparedMessages = decision.value;
+    }, 'apply-strategy', undefined, 'Apply message strategy to conversation history').build();
+}
+/**
+ * Persistent mode: load from store → apply strategy → track for CommitMemory.
+ * No non-null assertions — store and conversationId are guaranteed by caller.
+ */
+function buildPersistentSubflow(strategy, store, conversationId) {
+    return (0, footprintjs_1.flowChart)('LoadHistory', async (scope) => {
+        // Stage 1: Load stored history + merge with current turn messages
+        const currentMessages = scope.currentMessages ?? [];
+        const stored = (await store.load(conversationId)) ?? [];
+        const merged = stored.length > 0
+            ? [...stored, ...currentMessages]
+            : currentMessages;
+        // Track full merged history for CommitMemory reconstruction
+        scope.memory_storedHistory = merged;
+    }, 'load-history', undefined, 'Load conversation history from store')
+        .addFunction('ApplyStrategy', async (scope) => {
+        // Stage 2: Apply the message strategy (window, trim, summarize)
+        const merged = scope.memory_storedHistory ?? [];
+        const ctx = buildMessageContext(scope, merged);
+        const decision = await strategy.prepare(merged, ctx);
+        scope.memory_preparedMessages = decision.value;
+    }, 'apply-strategy', 'Apply message strategy to history')
+        .addFunction('TrackPrepared', (scope) => {
+        // Stage 3: Narrative checkpoint (values already in scope for CommitMemory)
+        const stored = scope.memory_storedHistory ?? [];
+        const prepared = scope.memory_preparedMessages ?? [];
+        void stored.length;
+        void prepared.length;
+    }, 'track-prepared', 'Track prepared messages for commit')
+        .build();
+}
+//# sourceMappingURL=buildMessagesSubflow.js.map

package/dist/lib/slots/messages/buildMessagesSubflow.js.map

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

package/dist/lib/slots/messages/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMessagesSubflow = void 0;
+var buildMessagesSubflow_1 = require("./buildMessagesSubflow");
+Object.defineProperty(exports, "buildMessagesSubflow", { enumerable: true, get: function () { return buildMessagesSubflow_1.buildMessagesSubflow; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/slots/messages/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/slots/messages/index.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA"}