agentfootprint 1.0.0

package/dist/types/lib/loop/types.d.ts

@@ -0,0 +1,248 @@
+/**
+ * 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').
+ */
+import type { FlowChart } from 'footprintjs';
+import type { StageFunction, SubflowMountOptions } from 'footprintjs/advanced';
+import type { LLMProvider, ResponseFormat } from '../../types';
+import type { ToolProvider } from '../../core';
+import type { ToolRegistry } from '../../tools';
+import type { Message } from '../../types/messages';
+import type { CommitMemoryConfig } from '../../stages/commitMemory';
+import type { SystemPromptSlotConfig } from '../slots/system-prompt';
+import type { MessagesSlotConfig } from '../slots/messages';
+import type { ToolsSlotConfig } from '../slots/tools';
+import type { ResolvedInstruction, InstructionOverride, AgentInstruction } from '../instructions';
+import type { DecideFn } from '../call/helpers';
+import type { AgentStreamEventHandler } from '../../streaming';
+/**
+ * A single branch in a RoutingConfig — what happens for a given decider return value.
+ *
+ * Discriminated union ensures every branch has exactly one handler.
+ */
+export type RoutingBranch = {
+    readonly id: string;
+    readonly kind: 'subflow';
+    readonly chart: FlowChart;
+    readonly name?: string;
+    readonly mount?: SubflowMountOptions;
+} | {
+    readonly id: string;
+    readonly kind: 'lazy-subflow';
+    readonly factory: () => FlowChart;
+    readonly name?: string;
+    readonly mount?: SubflowMountOptions;
+} | {
+    readonly id: string;
+    readonly kind: 'fn';
+    readonly fn: StageFunction;
+    readonly name?: string;
+    readonly description?: string;
+};
+/**
+ * RoutingConfig — controls what happens after ParseResponse in the agent loop.
+ *
+ * The default agent loop uses `tool-calls | final` routing. Swarm uses
+ * `specialist-A | specialist-B | swarm-tools | final`. Both are expressed
+ * as RoutingConfig — one code path, zero forks in buildAgentLoop.
+ *
+ * **Ordering invariant:** The decider runs AFTER ParseResponse commits.
+ * Scope contains `parsedResponse` with tool calls and response content.
+ *
+ * @internal Not exported from the public API. Consumer-facing builders
+ * (Agent, Swarm) construct RoutingConfig internally.
+ */
+export interface RoutingConfig {
+    /** Name for the decider stage (e.g., 'RouteResponse', 'RouteSpecialist'). */
+    readonly deciderName: string;
+    /** Stable ID for the decider node. */
+    readonly deciderId: string;
+    /** Description shown in narrative. */
+    readonly deciderDescription?: string;
+    /**
+     * Decider function — called after ParseResponse commits.
+     * Returns a branch ID string that matches one of the branches.
+     *
+     * Receives the scope (with parsedResponse, loopCount, etc.) and must return
+     * a string matching one of the branch IDs. maxIterations enforcement is
+     * handled structurally by buildAgentLoop — the decider does not need to check it.
+     */
+    readonly decider: (scope: any, breakFn: () => void, streamCb?: unknown) => string | Promise<string>;
+    /** Branch definitions — each maps to a subflow or inline function.
+     *  Order matters: branches are added to the decider in array order. */
+    readonly branches: readonly RoutingBranch[];
+    /** Default branch when decider returns an unknown key or maxIterations is reached.
+     *  This branch MUST call $break() or breakFn() to terminate the loop. */
+    readonly defaultBranch: string;
+}
+/**
+ * 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 declare enum 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)
+     *         ↑                                         |
+     *         └─────────────────────────────────────────┘
+     * ```
+     */
+    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)
+     *  ↑                                                  |
+     *  └──────────────────────────────────────────────────┘
+     * ```
+     */
+    Dynamic = "dynamic"
+}
+/**
+ * Full configuration for building an agent loop.
+ */
+export interface AgentLoopConfig {
+    /** LLM provider for the CallLLM stage. */
+    readonly provider: LLMProvider;
+    /** SystemPrompt slot configuration. */
+    readonly systemPrompt: SystemPromptSlotConfig;
+    /** Messages slot configuration. */
+    readonly messages: MessagesSlotConfig;
+    /** Tools slot configuration. */
+    readonly tools: ToolsSlotConfig;
+    /** Tool registry for executing tool calls in the tool-calls branch. */
+    readonly registry: ToolRegistry;
+    /**
+     * Optional ToolProvider for remote tool execution (MCP, A2A).
+     * When present, tool execution tries provider.execute() before registry fallback.
+     */
+    readonly toolProvider?: ToolProvider;
+    /** Max loop iterations before force-finalize. Default: 10. */
+    readonly maxIterations?: number;
+    /**
+     * Loop pattern — controls where the loop jumps back to after tool execution.
+     *
+     * - `AgentPattern.Regular` (default): loops to CallLLM — slots resolve once
+     * - `AgentPattern.Dynamic`: loops to SystemPrompt — all slots re-evaluate each iteration
+     *
+     * @default AgentPattern.Regular
+     */
+    readonly pattern?: AgentPattern;
+    /**
+     * When true, the Finalize branch sets `memory_shouldCommit` flag instead of
+     * calling $break() directly. Only use when a CommitMemory stage is mounted
+     * after the RouteResponse decider — without it, the loop will not terminate
+     * until maxIterations is reached.
+     *
+     * Auto-enabled when `commitMemory` is provided.
+     */
+    readonly useCommitFlag?: boolean;
+    /**
+     * When provided, mounts a CommitMemory stage after the RouteResponse decider.
+     * Automatically enables `useCommitFlag`.
+     */
+    readonly commitMemory?: CommitMemoryConfig;
+    /**
+     * Callback when LLM instructions fire during tool execution.
+     * Used to connect InstructionRecorder to the instruction pipeline.
+     */
+    readonly onInstructionsFired?: (toolId: string, fired: ResolvedInstruction[]) => void;
+    /** Agent-level instruction overrides keyed by tool ID. */
+    readonly instructionOverrides?: ReadonlyMap<string, InstructionOverride>;
+    /**
+     * Agent-level instructions evaluated by the InstructionsToLLM subflow.
+     * When provided, the subflow is mounted BEFORE the 3 API slots.
+     * Instructions inject into system prompt, tools, and tool-result processing
+     * based on the current Decision Scope state.
+     */
+    readonly agentInstructions?: readonly AgentInstruction[];
+    /**
+     * Initial Decision Scope values. Written to `scope.decision` in the Seed stage.
+     * Tool handlers update these values; InstructionsToLLM reads them to evaluate
+     * `activeWhen` predicates.
+     */
+    readonly initialDecision?: Readonly<Record<string, unknown>>;
+    /**
+     * Pre-computed decide() functions keyed by instruction rule ID.
+     * Built once in AgentRunner constructor, passed through to avoid
+     * recomputing on every run(). Functions can't travel through scope
+     * (stripped on write), so they're captured as a closure map.
+     */
+    readonly decideFunctions?: ReadonlyMap<string, DecideFn>;
+    /** Stream event handler for consumer-facing lifecycle events. */
+    readonly onStreamEvent?: AgentStreamEventHandler;
+    /** When true, CallLLM uses addStreamingFunction for token-by-token output. */
+    readonly streaming?: boolean;
+    /** Structured output format — passed to LLM provider as responseFormat option. */
+    readonly responseFormat?: ResponseFormat;
+    /**
+     * Custom routing strategy — replaces the default RouteResponse decider.
+     *
+     * When provided, buildAgentLoop uses this RoutingConfig instead of the
+     * default `tool-calls | final` routing. Used by Swarm to route to
+     * specialist subflows.
+     *
+     * When omitted, the default agent routing is used automatically.
+     *
+     * @internal Consumers use Agent/Swarm builders, not this field directly.
+     */
+    readonly routing?: RoutingConfig;
+}
+/**
+ * Options for seeding the loop with initial state.
+ */
+export interface AgentLoopSeedOptions {
+    /** Initial messages (e.g., [userMessage('hello')]). */
+    readonly messages: Message[];
+    /** Existing conversation history to prepend. Default: []. */
+    readonly existingMessages?: Message[];
+    /**
+     * When true, Seed stage reads `message` (string) from scope instead of
+     * using baked-in messages. Use this for subflow composition — the parent
+     * chart's inputMapper sets `message` in the subflow's scope.
+     */
+    readonly subflowMode?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/loop/types.d.ts.map

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

package/dist/types/lib/narrative/agentRenderer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+import type { NarrativeRenderer } from 'footprintjs/recorders';
+export interface AgentRendererOptions {
+    /**
+     * When true, shows full values instead of truncated previews.
+     * System prompts, tool results, LLM outputs, and parsed responses
+     * are shown in full for debugging and grounding analysis.
+     * @default false
+     */
+    verbose?: boolean;
+}
+/**
+ * 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 declare function createAgentRenderer(options?: AgentRendererOptions): NarrativeRenderer;
+//# sourceMappingURL=agentRenderer.d.ts.map

package/dist/types/lib/narrative/agentRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentRenderer.d.ts","sourceRoot":"","sources":["../../../../src/lib/narrative/agentRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAUlB,MAAM,uBAAuB,CAAC;AAqE/B,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA4ID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,iBAAiB,CAsFrF"}

package/dist/types/lib/narrative/groundingHelpers.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 type { CombinedNarrativeEntry } from 'footprintjs';
+/** A tool result that serves as a grounding source (source of truth). */
+export interface GroundingSource {
+    /** Stage that produced this source. */
+    readonly stageName: string;
+    /** Stage ID for UI sync. */
+    readonly stageId?: string;
+    /** Subflow ID (e.g., 'tool-calls' for ExecuteTools). */
+    readonly subflowId?: string;
+    /** Raw tool result content string. */
+    readonly content: string;
+    /** Parsed content (JSON-parsed if possible, raw string otherwise). */
+    readonly parsed: unknown;
+}
+/** An LLM output claim to verify against sources. */
+export interface LLMClaim {
+    /** Stage that produced this claim. */
+    readonly stageName: string;
+    readonly stageId?: string;
+    /** The full LLM output text. */
+    readonly content: string;
+    /** Whether this is the final answer ('result') or intermediate ('parsedResponse'). */
+    readonly type: 'final' | 'intermediate';
+}
+/** Full LLM context snapshot for a single turn. */
+export interface LLMContextSnapshot {
+    /** System prompt (full, un-truncated). */
+    readonly systemPrompt?: string;
+    /** Tool descriptions sent to the LLM. */
+    readonly toolDescriptions?: Array<{
+        name: string;
+        description: string;
+        inputSchema: unknown;
+    }>;
+    /** Tool results (sources of truth). */
+    readonly sources: GroundingSource[];
+    /** LLM claims (outputs to verify). */
+    readonly claims: LLMClaim[];
+    /** Decision scope values (last observed). */
+    readonly decision?: Record<string, unknown>;
+}
+/**
+ * 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 declare function getGroundingSources(entries: CombinedNarrativeEntry[]): GroundingSource[];
+/**
+ * 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 declare function getLLMClaims(entries: CombinedNarrativeEntry[]): LLMClaim[];
+/**
+ * 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 declare function getFullLLMContext(entries: CombinedNarrativeEntry[]): LLMContextSnapshot;
+//# sourceMappingURL=groundingHelpers.d.ts.map

package/dist/types/lib/narrative/groundingHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groundingHelpers.d.ts","sourceRoot":"","sources":["../../../../src/lib/narrative/groundingHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAK1D,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,qDAAqD;AACrD,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;CACzC;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC/F,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,CAAC;IACpC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,sBAAsB,EAAE,GAAG,eAAe,EAAE,CAyBxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,sBAAsB,EAAE,GAAG,QAAQ,EAAE,CAgC1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,sBAAsB,EAAE,GAAG,kBAAkB,CA4BvF"}

package/dist/types/lib/narrative/index.d.ts

@@ -0,0 +1,5 @@
+export { createAgentRenderer } from './agentRenderer.js';
+export type { AgentRendererOptions } from './agentRenderer.js';
+export { getGroundingSources, getLLMClaims, getFullLLMContext } from './groundingHelpers.js';
+export type { GroundingSource, LLMClaim, LLMContextSnapshot } from './groundingHelpers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/narrative/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/narrative/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types/lib/slots/helpers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared helpers for slot subflows.
+ */
+import type { Message } from '../../types/messages';
+/**
+ * Find the last user message in the history by iterating backward.
+ * O(1) allocation — no array copy.
+ */
+export declare function findLastUserMessage(messages: Message[]): Message | 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 declare function extractTextContent(message: Message): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/types/lib/slots/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/lib/slots/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,SAAS,CAK5E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE3D"}

package/dist/types/lib/slots/index.d.ts

@@ -0,0 +1,7 @@
+export { buildSystemPromptSubflow } from './system-prompt';
+export type { SystemPromptSlotConfig } from './system-prompt';
+export { buildMessagesSubflow } from './messages';
+export type { MessagesSlotConfig } from './messages';
+export { buildToolsSubflow } from './tools';
+export type { ToolsSlotConfig } from './tools';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/slots/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/slots/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,YAAY,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}

package/dist/types/lib/slots/messages/buildMessagesSubflow.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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]
+ */
+import type { FlowChart } from 'footprintjs';
+import type { MessagesSlotConfig } from './types';
+/**
+ * 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,
+ *   }),
+ * })
+ * ```
+ */
+export declare function buildMessagesSubflow(config: MessagesSlotConfig): FlowChart;
+//# sourceMappingURL=buildMessagesSubflow.d.ts.map

package/dist/types/lib/slots/messages/buildMessagesSubflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildMessagesSubflow.d.ts","sourceRoot":"","sources":["../../../../../src/lib/slots/messages/buildMessagesSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAMzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAmBlD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAY1E"}

package/dist/types/lib/slots/messages/index.d.ts

@@ -0,0 +1,3 @@
+export { buildMessagesSubflow } from './buildMessagesSubflow';
+export type { MessagesSlotConfig } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/slots/messages/index.d.ts.map

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

package/dist/types/lib/slots/messages/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Messages slot types.
+ *
+ * The Messages slot prepares the conversation history before each LLM call.
+ * Always mounted as a subflow — config determines internal stages:
+ *   - Simple (no store): 1 stage [ApplyStrategy]
+ *   - Persistent (with store): 3 stages [LoadHistory → ApplyStrategy → TrackPrepared]
+ */
+import type { MessageStrategy } from '../../../core';
+import type { ConversationStore } from '../../../adapters/memory/types';
+/**
+ * Config for the Messages slot subflow.
+ *
+ * Two modes:
+ *   - In-memory: provide `strategy` only. History comes from scope (set by SeedScope).
+ *   - Persistent: provide `strategy` + `store` + `conversationId`. History loaded from store.
+ */
+export interface MessagesSlotConfig {
+    /** The message strategy (slidingWindow, charBudget, fullHistory, etc.). */
+    readonly strategy: MessageStrategy;
+    /** Optional conversation store for persistent history. */
+    readonly store?: ConversationStore;
+    /** Required when store is provided. Identifies the conversation. */
+    readonly conversationId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/slots/messages/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/lib/slots/messages/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC"}

package/dist/types/lib/slots/system-prompt/buildSystemPromptSubflow.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SystemPrompt slot — builds a subflow that resolves the system prompt.
+ *
+ * Always a subflow (never a plain stage) because:
+ *   - Subflow with 1 stage = zero overhead, but gives drill-down + narrative for free
+ *   - Config determines internal stages (1 for static, 3+ for RAG-augmented)
+ *   - Parent chart never changes when strategy complexity grows
+ *
+ * The subflow writes the resolved prompt to scope.systemPrompt.
+ * Providers are trusted — they receive raw message history and their output is
+ * stored as-is. Sanitization is the provider's responsibility.
+ *
+ * Flowchart:
+ *   [ResolvePrompt]  (single stage for simple providers)
+ */
+import type { FlowChart } from 'footprintjs';
+import type { SystemPromptSlotConfig } from './types';
+/**
+ * Build the SystemPrompt slot subflow from config.
+ *
+ * Returns a FlowChart that can be mounted with addSubFlowChartNext:
+ * ```typescript
+ * builder.addSubFlowChartNext('sf-system-prompt', buildSystemPromptSubflow(config), 'SystemPrompt', { ... })
+ * ```
+ */
+export declare function buildSystemPromptSubflow(config: SystemPromptSlotConfig): FlowChart;
+//# sourceMappingURL=buildSystemPromptSubflow.d.ts.map

package/dist/types/lib/slots/system-prompt/buildSystemPromptSubflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildSystemPromptSubflow.d.ts","sourceRoot":"","sources":["../../../../../src/lib/slots/system-prompt/buildSystemPromptSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAIzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAoBtD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,sBAAsB,GAAG,SAAS,CAgClF"}

package/dist/types/lib/slots/system-prompt/index.d.ts

@@ -0,0 +1,3 @@
+export { buildSystemPromptSubflow } from './buildSystemPromptSubflow';
+export type { SystemPromptSlotConfig } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/slots/system-prompt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/lib/slots/system-prompt/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,YAAY,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC"}

package/dist/types/lib/slots/system-prompt/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SystemPrompt slot types.
+ *
+ * The SystemPrompt slot resolves the system prompt string before each LLM call.
+ * It is always mounted as a subflow — even for a static string, the subflow
+ * has one stage. Config determines what stages go inside.
+ */
+import type { PromptProvider } from '../../../core';
+/**
+ * Config for the SystemPrompt slot subflow.
+ * Passed to buildSystemPromptSubflow() to create the subflow.
+ */
+export interface SystemPromptSlotConfig {
+    /** The prompt provider strategy (static, template, composite, skill-based, etc.). */
+    readonly provider: PromptProvider;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/slots/system-prompt/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/lib/slots/system-prompt/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC"}

package/dist/types/lib/slots/tools/buildToolsSubflow.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tools slot — builds a subflow that resolves available tools.
+ *
+ * Always a subflow because:
+ *   - Config determines complexity: 1 stage (static) or 2+ (gated/dynamic)
+ *   - Parent chart never changes when tool resolution grows
+ *   - BehindTheScenes shows exactly which tools were resolved and why
+ *
+ * Providers are trusted — their output is stored as-is.
+ * Providers receive raw message history for context-dependent resolution.
+ *
+ * Flowchart:
+ *   [ResolveTools]  (single stage — ToolProvider.resolve() handles all complexity)
+ */
+import type { FlowChart } from 'footprintjs';
+import type { ToolsSlotConfig } from './types';
+/**
+ * Build the Tools slot subflow from config.
+ *
+ * Returns a FlowChart mountable with addSubFlowChartNext.
+ */
+export declare function buildToolsSubflow(config: ToolsSlotConfig): FlowChart;
+//# sourceMappingURL=buildToolsSubflow.d.ts.map

package/dist/types/lib/slots/tools/buildToolsSubflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildToolsSubflow.d.ts","sourceRoot":"","sources":["../../../../../src/lib/slots/tools/buildToolsSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAIzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAqB/C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAsCpE"}

package/dist/types/lib/slots/tools/index.d.ts

@@ -0,0 +1,3 @@
+export { buildToolsSubflow } from './buildToolsSubflow';
+export type { ToolsSlotConfig } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/slots/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/lib/slots/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}