agentfootprint 1.0.0

package/dist/esm/lib/loop/types.js

@@ -0,0 +1,71 @@
+/**
+ * Loop assembler types.
+ *
+ * The loop assembler wires the three API slots + call stages into a
+ * looping flowchart: SystemPrompt → Messages → Tools → CallLLM →
+ * ParseResponse → RouteResponse(decider) → {tool-calls | final}
+ * → loopTo('call-llm').
+ */
+/**
+ * Agent loop patterns — determines which stages re-evaluate between iterations.
+ *
+ * The pattern controls WHERE the loop jumps back to after tool execution:
+ * - `Regular`: loops to CallLLM — slots resolve once before the loop
+ * - `Dynamic`: loops to SystemPrompt — all three API slots re-evaluate each iteration
+ *
+ * @example
+ * ```typescript
+ * import { Agent, AgentPattern } from 'agentfootprint';
+ *
+ * // Standard ReAct — fixed prompt, tools, memory (default)
+ * Agent.create({ provider }).build();
+ *
+ * // Dynamic ReAct — re-evaluate all slots each iteration
+ * Agent.create({ provider })
+ *   .pattern(AgentPattern.Dynamic)
+ *   .build();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Dynamic ReAct use case: progressive tool authorization
+ * // Turn 1: agent calls verify_identity → user is admin
+ * // Turn 2: Tools subflow re-evaluates → admin tools now available
+ * // Turn 3: agent can use admin tools that were hidden before
+ * ```
+ */
+export var AgentPattern;
+(function (AgentPattern) {
+    /**
+     * Standard ReAct loop — loops back to CallLLM.
+     *
+     * SystemPrompt, Messages, and Tools subflows resolve ONCE before the loop starts.
+     * Each iteration only re-runs: CallLLM → ParseResponse → RouteResponse → tools.
+     * Best for: most agent use cases with fixed prompt/tools/memory.
+     *
+     * ```
+     * [SystemPrompt] → [Messages] → [Tools] → AssemblePrompt
+     *   → CallLLM → Parse → Route → ExecuteTools → loopTo(CallLLM)
+     *         ↑                                         |
+     *         └─────────────────────────────────────────┘
+     * ```
+     */
+    AgentPattern["Regular"] = "regular";
+    /**
+     * Dynamic ReAct loop — loops back to SystemPrompt.
+     *
+     * All three API slots (SystemPrompt, Messages, Tools) re-evaluate each iteration.
+     * Strategies receive updated context (messages now include tool results, loopCount
+     * incremented) and can return different prompt/tools/memory based on what happened.
+     * Best for: progressive authorization, adaptive prompts, context-dependent tool sets.
+     *
+     * ```
+     * [SystemPrompt] → [Messages] → [Tools] → AssemblePrompt
+     *   → CallLLM → Parse → Route → ExecuteTools → loopTo(SystemPrompt)
+     *  ↑                                                  |
+     *  └──────────────────────────────────────────────────┘
+     * ```
+     */
+    AgentPattern["Dynamic"] = "dynamic";
+})(AgentPattern || (AgentPattern = {}));
+//# sourceMappingURL=types.js.map

package/dist/esm/lib/loop/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/loop/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAN,IAAY,YAiCX;AAjCD,WAAY,YAAY;IACtB;;;;;;;;;;;;;OAaG;IACH,mCAAmB,CAAA;IAEnB;;;;;;;;;;;;;;OAcG;IACH,mCAAmB,CAAA;AACrB,CAAC,EAjCW,YAAY,KAAZ,YAAY,QAiCvB"}

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

@@ -0,0 +1,293 @@
+/**
+ * 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.
+ */
+// ── 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() });
+ * ```
+ */
+export 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(', ')}`;
+        },
+    };
+}
+//# sourceMappingURL=agentRenderer.js.map

package/dist/esm/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/esm/lib/narrative/groundingHelpers.js

@@ -0,0 +1,136 @@
+/**
+ * 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);
+ */
+import { AgentScopeKey } from '../../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: {...} }]
+ * ```
+ */
+export function getGroundingSources(entries) {
+    const sources = [];
+    for (const entry of entries) {
+        if (entry.type !== 'step' || entry.key !== 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;
+}
+/**
+ * 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' }]
+ * ```
+ */
+export function getLLMClaims(entries) {
+    const claims = [];
+    for (const entry of entries) {
+        if (entry.type !== 'step')
+            continue;
+        if (entry.key === 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 === 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;
+}
+/**
+ * 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
+ */
+export function getFullLLMContext(entries) {
+    let systemPrompt;
+    let toolDescriptions;
+    let decision;
+    for (const entry of entries) {
+        if (entry.type !== 'step')
+            continue;
+        if (entry.key === AgentScopeKey.SystemPrompt && typeof entry.rawValue === 'string') {
+            systemPrompt = entry.rawValue;
+        }
+        if (entry.key === AgentScopeKey.ToolDescriptions && Array.isArray(entry.rawValue)) {
+            toolDescriptions = entry.rawValue;
+        }
+        if (entry.key === 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,
+    };
+}
+//# sourceMappingURL=groundingHelpers.js.map

package/dist/esm/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/esm/lib/narrative/index.js

@@ -0,0 +1,3 @@
+export { createAgentRenderer } from './agentRenderer.js';
+export { getGroundingSources, getLLMClaims, getFullLLMContext } from './groundingHelpers.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/narrative/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,23 @@
+/**
+ * Shared helpers for slot subflows.
+ */
+/**
+ * Find the last user message in the history by iterating backward.
+ * O(1) allocation — no array copy.
+ */
+export function findLastUserMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === 'user')
+            return messages[i];
+    }
+    return undefined;
+}
+/**
+ * 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.
+ */
+export function extractTextContent(message) {
+    return typeof message.content === 'string' ? message.content : '';
+}
+//# sourceMappingURL=helpers.js.map

package/dist/esm/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,MAAM,UAAU,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;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,OAAO,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC"}

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

@@ -0,0 +1,4 @@
+export { buildSystemPromptSubflow } from './system-prompt';
+export { buildMessagesSubflow } from './messages';
+export { buildToolsSubflow } from './tools';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/slots/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAG3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC"}