agentfootprint 1.0.0

package/dist/types/scope/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Typed state interfaces for TypedScope<T> in agentfootprint patterns.
+ *
+ * These replace the AgentScope static helpers + AGENT_PATHS string constants.
+ * Each pattern has its own state interface — subflows use narrower slices.
+ *
+ * Usage:
+ *   flowChart<AgentLoopState>('Seed', (scope) => {
+ *     scope.messages = [userMessage('hello')];  // typed write
+ *     scope.loopCount = 0;                       // typed write
+ *   })
+ */
+import type { Message, AdapterResult, LLMResponse, LLMToolDescription, ToolCall, RetrievalResult, AgentResultEntry } from '../types';
+import type { LLMInstruction } from '../lib/instructions/types';
+export interface ParsedResponse {
+    readonly hasToolCalls: boolean;
+    readonly toolCalls: ToolCall[];
+    readonly content: string;
+}
+/** Minimal state shared by all patterns that call an LLM. */
+export interface BaseLLMState {
+    messages: Message[];
+    toolDescriptions?: LLMToolDescription[];
+    adapterResult?: AdapterResult;
+    adapterRawResponse?: LLMResponse;
+    parsedResponse?: ParsedResponse;
+    result?: string;
+    [key: string]: unknown;
+}
+/**
+ * Well-known scope keys for the agent loop.
+ * Used by grounding helpers, narrative renderer, and suppression lists.
+ * Single source of truth — no magic strings.
+ */
+export declare enum AgentScopeKey {
+    Messages = "messages",
+    SystemPrompt = "systemPrompt",
+    ToolDescriptions = "toolDescriptions",
+    ParsedResponse = "parsedResponse",
+    Result = "result",
+    LoopCount = "loopCount",
+    ToolResultMessages = "toolResultMessages",
+    Decision = "decision",
+    MatchedInstructions = "matchedInstructions",
+    PromptInjections = "promptInjections",
+    ToolInjections = "toolInjections",
+    ResponseRules = "responseRules"
+}
+/** Full state for the agent loop flowchart (buildAgentLoop). */
+export interface AgentLoopState {
+    /** Conversation message history. */
+    messages: Message[];
+    /** Resolved system prompt text. */
+    systemPrompt: string;
+    /** Available tool descriptions for the LLM. */
+    toolDescriptions: LLMToolDescription[];
+    /** Normalized LLM response (discriminated union: final | tools | error). */
+    adapterResult: AdapterResult;
+    /** Raw LLM response for recorders. */
+    adapterRawResponse: LLMResponse;
+    /** Structured parse of LLM response. */
+    parsedResponse: ParsedResponse;
+    /** Current loop iteration count. */
+    loopCount: number;
+    /** Max loop iterations allowed. */
+    maxIterations: number;
+    /** Final answer text (set when turn finalizes). */
+    result: string;
+    /** Prepared messages after strategy applied (Messages slot output). */
+    memory_preparedMessages: Message[];
+    /** Raw history loaded from ConversationStore. */
+    memory_storedHistory: Message[];
+    /** Flag: HandleResponse sets true when finalizing; CommitMemory reads. */
+    memory_shouldCommit: boolean;
+    /** Tool resolution summary (e.g. "3 tools: calculator, datetime, search"). */
+    resolvedTools: string;
+    /** System prompt summary (e.g. '38 chars: "You are a helpful..."'). */
+    promptSummary: string;
+    /** LLM call summary (e.g. "claude-sonnet-4 (127in / 45out)"). */
+    llmCall: string;
+    /** Response type summary (e.g. "tool_calls: [calculator]" or "final: ..."). */
+    responseType: string;
+    /** Decision scope — developer-defined state driving instruction activation. */
+    decision?: Record<string, unknown>;
+    /** Prompt injections from matched instructions (Position 1). */
+    promptInjections?: string[];
+    /** Tool description injections from matched instructions (Position 2). */
+    toolInjections?: LLMToolDescription[];
+    /** Tool-result rules from matched instructions (Position 3). */
+    responseRules?: LLMInstruction[];
+    /** Narrative: which instructions matched this iteration. */
+    matchedInstructions?: string;
+    /** User message injected by parent in subflow mode. */
+    message: string;
+}
+/** State for the SystemPrompt slot subflow. */
+export interface SystemPromptSubflowState {
+    messages: Message[];
+    loopCount: number;
+    systemPrompt: string;
+    promptSummary: string;
+    promptDecision?: string;
+    /** Prompt injections from InstructionsToLLM (merged after base prompt). */
+    promptInjections?: string[];
+}
+/** State for the Tools slot subflow. */
+export interface ToolsSubflowState {
+    messages: Message[];
+    loopCount: number;
+    toolDescriptions: LLMToolDescription[];
+    resolvedTools: string;
+    toolDecision?: string;
+    /** Tool description injections from InstructionsToLLM (merged after base tools). */
+    toolInjections?: LLMToolDescription[];
+}
+/** State for the Messages slot subflow (in-memory path). */
+export interface MessagesSubflowState {
+    /** Current messages passed from parent via inputMapper. */
+    currentMessages: Message[];
+    loopCount: number;
+    memory_preparedMessages: Message[];
+    memory_storedHistory: Message[];
+}
+/** State for the InstructionsToLLM subflow. */
+export interface InstructionsToLLMState {
+    /** Current decision scope values (from parent via inputMapper). */
+    decision: Record<string, unknown>;
+    /** Output: prompt text fragments to merge into system prompt. */
+    promptInjections: string[];
+    /** Output: tool descriptions to merge into tools list (handler stripped). */
+    toolInjections: LLMToolDescription[];
+    /** Output: tool-result rules for tool execution. */
+    responseRules: LLMInstruction[];
+    /** Output: IDs of instructions that matched (narrative enrichment). */
+    matchedInstructions: string;
+}
+/** State for RAG pattern flowcharts. */
+export interface RAGState extends BaseLLMState {
+    systemPrompt: string;
+    retrievalQuery: string;
+    retrievalResult: RetrievalResult;
+    contextWindow: string;
+    result: string;
+}
+/** State for multi-agent pipeline flowcharts. */
+export interface MultiAgentState {
+    pipelineInput: string;
+    agentResults: AgentResultEntry[];
+    result: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/scope/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/scope/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAMD,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,gBAAgB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACxC,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,kBAAkB,CAAC,EAAE,WAAW,CAAC;IACjC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID;;;;GAIG;AACH,oBAAY,aAAa;IAEvB,QAAQ,aAAa;IACrB,YAAY,iBAAiB;IAC7B,gBAAgB,qBAAqB;IACrC,cAAc,mBAAmB;IACjC,MAAM,WAAW;IACjB,SAAS,cAAc;IAGvB,kBAAkB,uBAAuB;IAGzC,QAAQ,aAAa;IACrB,mBAAmB,wBAAwB;IAC3C,gBAAgB,qBAAqB;IACrC,cAAc,mBAAmB;IACjC,aAAa,kBAAkB;CAChC;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;IACvC,4EAA4E;IAC5E,aAAa,EAAE,aAAa,CAAC;IAC7B,sCAAsC;IACtC,kBAAkB,EAAE,WAAW,CAAC;IAChC,wCAAwC;IACxC,cAAc,EAAE,cAAc,CAAC;IAC/B,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IAGf,uEAAuE;IACvE,uBAAuB,EAAE,OAAO,EAAE,CAAC;IACnC,iDAAiD;IACjD,oBAAoB,EAAE,OAAO,EAAE,CAAC;IAChC,0EAA0E;IAC1E,mBAAmB,EAAE,OAAO,CAAC;IAG7B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IAGrB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,0EAA0E;IAC1E,cAAc,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACtC,gEAAgE;IAChE,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC;IACjC,4DAA4D;IAC5D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAG7B,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,+CAA+C;AAC/C,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,cAAc,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACvC;AAED,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,eAAe,EAAE,OAAO,EAAE,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,EAAE,OAAO,EAAE,CAAC;IACnC,oBAAoB,EAAE,OAAO,EAAE,CAAC;CACjC;AAED,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,6EAA6E;IAC7E,cAAc,EAAE,kBAAkB,EAAE,CAAC;IACrC,oDAAoD;IACpD,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,uEAAuE;IACvE,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAID,wCAAwC;AACxC,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,eAAe,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/types/security.barrel.d.ts

@@ -0,0 +1,17 @@
+/**
+ * agentfootprint/security — Make agents safe.
+ *
+ * Tool gating hides tools from the LLM. Permission policies control access.
+ * Two layers: resolve-time filtering (LLM never sees blocked tools) + execute-time rejection.
+ *
+ * @example
+ * ```typescript
+ * import { gatedTools, PermissionPolicy } from 'agentfootprint/security';
+ *
+ * const policy = PermissionPolicy.fromRoles({ user: ['search'], admin: ['search', 'delete'] }, 'user');
+ * const agent = Agent.create({ provider }).toolProvider(gatedTools(tools, policy.checker())).build();
+ * ```
+ */
+export { gatedTools, PermissionPolicy } from './providers';
+export type { PermissionChecker, GatedToolsOptions, PermissionPolicyOptions, PermissionChangeEvent } from './providers';
+//# sourceMappingURL=security.barrel.d.ts.map

package/dist/types/security.barrel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.barrel.d.ts","sourceRoot":"","sources":["../../src/security.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/stages/augmentPrompt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * AugmentPrompt stage — injects retrieved context into messages before LLM call.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { RAGState } from '../scope/types';
+export declare function augmentPromptStage(scope: TypedScope<RAGState>): void;
+//# sourceMappingURL=augmentPrompt.d.ts.map

package/dist/types/stages/augmentPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"augmentPrompt.d.ts","sourceRoot":"","sources":["../../../src/stages/augmentPrompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CA0BpE"}

package/dist/types/stages/callLLM.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CallLLM stage — sends messages to LLM via adapter, writes AdapterResult to scope.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { LLMProvider } from '../types';
+import type { BaseLLMState } from '../scope/types';
+export declare function createCallLLMStage(provider: LLMProvider): (scope: TypedScope<BaseLLMState>) => Promise<void>;
+//# sourceMappingURL=callLLM.d.ts.map

package/dist/types/stages/callLLM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callLLM.d.ts","sourceRoot":"","sources":["../../../src/stages/callLLM.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,WACjC,WAAW,YAAY,CAAC,mBAU9C"}

package/dist/types/stages/commitMemory.d.ts

@@ -0,0 +1,51 @@
+/**
+ * CommitMemory stage — persist conversation history after the turn completes.
+ *
+ * Behavior:
+ *   - Reads `memory_shouldCommit` flag set by HandleResponse when the turn finalizes.
+ *   - If true: fires `store.save(conversationId, messages)` as a non-blocking Promise
+ *     (fire-and-forget), then calls scope.$break() so the loop ends.
+ *   - If false (tool-call turn still in progress): no-op — loop continues normally.
+ *
+ * Fire-and-forget rationale:
+ *   The caller receives the agent result immediately, without waiting for the DB write
+ *   to complete. This matches the design goal of LangGraph vs agentfootprint: LangGraph
+ *   blocks on its checkpointer; agentfootprint commits in parallel. Save errors are
+ *   caught internally and surfaced via the provided `onSaveError` callback (if any).
+ *
+ *   Dev-mode: if `onSaveError` is omitted and save() fails, a console.warn is emitted in
+ *   non-production environments so silent storage failures surface during development.
+ *
+ * Placement in the chart:
+ *   CommitMemory is placed BEFORE `loopTo('call-llm')`. On tool-call turns it
+ *   passes through (shouldCommit=false). On final turns it saves + breaks.
+ *   This means every loop pass checks whether the turn is done.
+ *
+ * Example:
+ *   SeedScope → PrepareMemory → ... → HandleResponse → CommitMemory → loopTo(CallLLM)
+ */
+import type { TypedScope } from 'footprintjs';
+import type { ConversationStore } from '../adapters/memory/types';
+import type { AgentLoopState } from '../scope/types';
+export interface CommitMemoryConfig {
+    readonly store: ConversationStore;
+    readonly conversationId: string;
+    /**
+     * Called when the fire-and-forget save() rejects.
+     * Optional — if omitted, save errors are silently swallowed in production.
+     * In non-production environments a console.warn is emitted automatically.
+     * Use this to surface storage errors in telemetry/logging.
+     */
+    readonly onSaveError?: (error: unknown) => void;
+}
+/**
+ * Build the CommitMemory stage function.
+ *
+ * Usage:
+ * ```typescript
+ * .addFunction('CommitMemory', createCommitMemoryStage(config), 'commit-memory')
+ * .loopTo('call-llm')
+ * ```
+ */
+export declare function createCommitMemoryStage(config: CommitMemoryConfig): (scope: TypedScope<AgentLoopState>) => Promise<void>;
+//# sourceMappingURL=commitMemory.d.ts.map

package/dist/types/stages/commitMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commitMemory.d.ts","sourceRoot":"","sources":["../../../src/stages/commitMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAID;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,WAC3C,WAAW,cAAc,CAAC,mBA+DhD"}

package/dist/types/stages/finalize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Finalize stage — extract the final response from conversation.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { BaseLLMState } from '../scope/types';
+export declare function finalizeStage(scope: TypedScope<BaseLLMState>): void;
+//# sourceMappingURL=finalize.d.ts.map

package/dist/types/stages/finalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize.d.ts","sourceRoot":"","sources":["../../../src/stages/finalize.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC,GAAG,IAAI,CAMnE"}

package/dist/types/stages/helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared helpers for agent stages.
+ */
+import type { LLMResponse, AdapterResult, ToolCall } from '../types';
+import type { ToolRegistry } from '../tools';
+import type { Message } from '../types';
+/**
+ * Normalize an LLMResponse into an AdapterResult discriminated union.
+ * Shared by callLLM stage and createAdapterSubflow.
+ */
+export declare function normalizeAdapterResponse(response: LLMResponse): AdapterResult;
+/**
+ * Execute tool calls and append results to conversation messages.
+ * Returns the updated messages array.
+ */
+export declare function executeToolCalls(toolCalls: ToolCall[], registry: ToolRegistry, messages: Message[]): Promise<Message[]>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/types/stages/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/stages/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAErE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGxC;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,WAAW,GAAG,aAAa,CAgB7E;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,QAAQ,EAAE,EACrB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,OAAO,EAAE,GAClB,OAAO,CAAC,OAAO,EAAE,CAAC,CA4BpB"}

package/dist/types/stages/index.d.ts

@@ -0,0 +1,10 @@
+export { createCommitMemoryStage } from './commitMemory';
+export type { CommitMemoryConfig } from './commitMemory';
+export { createCallLLMStage } from './callLLM';
+export { parseResponseStage } from './parseResponse';
+export { finalizeStage } from './finalize';
+export { normalizeAdapterResponse, executeToolCalls } from './helpers';
+export { createRetrieveStage } from './retrieve';
+export { augmentPromptStage } from './augmentPrompt';
+export { runnerAsStage } from './runnerAsStage';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/stages/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stages/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types/stages/parseResponse.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ParseResponse stage — extract ParsedResponse from AdapterResult.
+ * Also appends assistant message to conversation history.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { BaseLLMState } from '../scope/types';
+export declare function parseResponseStage(scope: TypedScope<BaseLLMState>): void;
+//# sourceMappingURL=parseResponse.d.ts.map

package/dist/types/stages/parseResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseResponse.d.ts","sourceRoot":"","sources":["../../../src/stages/parseResponse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC,GAAG,IAAI,CAyBxE"}

package/dist/types/stages/retrieve.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Retrieve stage — calls retriever provider, writes RetrievalResult to scope.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { RetrieverProvider, RetrieveOptions } from '../types';
+import type { RAGState } from '../scope/types';
+export declare function createRetrieveStage(retriever: RetrieverProvider, options?: RetrieveOptions): (scope: TypedScope<RAGState>) => Promise<void>;
+//# sourceMappingURL=retrieve.d.ts.map

package/dist/types/stages/retrieve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../../../src/stages/retrieve.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,eAAe,WACpE,WAAW,QAAQ,CAAC,mBAc1C"}

package/dist/types/stages/runnerAsStage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * runnerAsStage — wraps any RunnerLike as a flowchart stage function.
+ *
+ * This is the core primitive for multi-agent composition. Any runner
+ * (Agent, RAG, LLMCall, or user-built) can become a stage in a pipeline.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentStageConfig } from '../types';
+import type { MultiAgentState } from '../scope/types';
+/**
+ * Creates a stage function that executes a runner and writes its result to scope.
+ *
+ * Default behavior:
+ * - Input: reads previous agent's output (or pipelineInput for first agent)
+ * - Output: writes to 'result' and records agent entry in agentResults
+ */
+export declare function runnerAsStage(config: AgentStageConfig): (scope: TypedScope<MultiAgentState>) => Promise<void>;
+//# sourceMappingURL=runnerAsStage.d.ts.map

package/dist/types/stages/runnerAsStage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerAsStage.d.ts","sourceRoot":"","sources":["../../../src/stages/runnerAsStage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,UAAU,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,WAC/B,WAAW,eAAe,CAAC,KAAG,QAAQ,IAAI,CAAC,CAsCjE"}

package/dist/types/stream.barrel.d.ts

@@ -0,0 +1,19 @@
+/**
+ * agentfootprint/stream — See agents work in real-time.
+ *
+ * 9-event discriminated union for CLI/web/mobile consumers.
+ * SSEFormatter for Server-Sent Events.
+ *
+ * @example
+ * ```typescript
+ * import { SSEFormatter } from 'agentfootprint/stream';
+ * import type { AgentStreamEvent } from 'agentfootprint/stream';
+ *
+ * await agent.run('hello', {
+ *   onEvent: (e: AgentStreamEvent) => res.write(SSEFormatter.format(e)),
+ * });
+ * ```
+ */
+export { StreamEmitter, SSEFormatter } from './streaming';
+export type { AgentStreamEvent, AgentStreamEventHandler, StreamEvent, StreamEventHandler } from './streaming';
+//# sourceMappingURL=stream.barrel.d.ts.map

package/dist/types/stream.barrel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.barrel.d.ts","sourceRoot":"","sources":["../../src/stream.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/streaming/StreamEmitter.d.ts

@@ -0,0 +1,93 @@
+import type { AgentPhase } from '../core';
+/**
+ * AgentStreamEvent — real-time events emitted during agent execution.
+ *
+ * The framework emits these. The consumer renders them (CLI, web, mobile).
+ * Events fire regardless of streaming mode — only `token` and `thinking`
+ * require `.streaming(true)`. Tool and turn lifecycle events always fire.
+ *
+ * @example
+ * ```typescript
+ * agent.run('hello', {
+ *   onEvent: (event) => {
+ *     switch (event.type) {
+ *       case 'token': process.stdout.write(event.content); break;
+ *       case 'tool_start': console.log(`Running ${event.toolName}...`); break;
+ *       case 'tool_end': console.log(`Done (${event.latencyMs}ms)`); break;
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export type AgentStreamEvent = {
+    type: 'turn_start';
+    userMessage: string;
+} | {
+    type: 'llm_start';
+    iteration: number;
+} | {
+    type: 'thinking';
+    content: string;
+} | {
+    type: 'token';
+    content: string;
+} | {
+    type: 'llm_end';
+    iteration: number;
+    toolCallCount: number;
+    content: string;
+    model?: string;
+    latencyMs: number;
+} | {
+    type: 'tool_start';
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'tool_end';
+    toolName: string;
+    toolCallId: string;
+    /** Raw tool result — may contain PII. Apply your own redaction before logging/displaying. */
+    result: string;
+    error?: boolean;
+    latencyMs: number;
+} | {
+    type: 'turn_end';
+    content: string;
+    iterations: number;
+    paused?: boolean;
+} | {
+    type: 'error';
+    phase: AgentPhase;
+    message: string;
+};
+export type AgentStreamEventHandler = (event: AgentStreamEvent) => void;
+/**
+ * StreamEmitter — dispatches AgentStreamEvents to consumers.
+ *
+ * Error isolation: handler errors are swallowed — never break the agent pipeline.
+ * This is the correct behavior for a push-to-consumer system (same as RecorderBridge).
+ */
+export declare class StreamEmitter {
+    private handlers;
+    on(handler: AgentStreamEventHandler): () => void;
+    emit(event: AgentStreamEvent): void;
+}
+/**
+ * SSEFormatter — converts AgentStreamEvent to Server-Sent Events text.
+ *
+ * @example
+ * ```typescript
+ * res.write(SSEFormatter.format({ type: 'token', content: 'Hello' }));
+ * // event: token\ndata: {"type":"token","content":"Hello"}\n\n
+ * ```
+ */
+export declare class SSEFormatter {
+    static format(event: AgentStreamEvent): string;
+    static formatAll(events: AgentStreamEvent[]): string;
+}
+/** @deprecated Use AgentStreamEvent instead. */
+export type StreamEvent = AgentStreamEvent;
+/** @deprecated Use AgentStreamEventHandler instead. */
+export type StreamEventHandler = AgentStreamEventHandler;
+//# sourceMappingURL=StreamEmitter.d.ts.map

package/dist/types/streaming/StreamEmitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamEmitter.d.ts","sourceRoot":"","sources":["../../../src/streaming/StreamEmitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACjH;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC3F;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IACvD,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAExE;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAiC;IAEjD,EAAE,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAOhD,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;CASpC;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM;IAI9C,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM;CAGrD;AAGD,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,gBAAgB,CAAC;AAC3C,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,uBAAuB,CAAC"}

package/dist/types/streaming/index.d.ts

@@ -0,0 +1,3 @@
+export { StreamEmitter, SSEFormatter } from './StreamEmitter';
+export type { AgentStreamEvent, AgentStreamEventHandler, StreamEvent, StreamEventHandler } from './StreamEmitter';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/streaming/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/streaming/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types/subflows/index.d.ts

@@ -0,0 +1,3 @@
+export { createPrepareMemorySubflow } from './prepareMemory';
+export type { PrepareMemoryConfig } from './prepareMemory';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/subflows/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/subflows/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types/subflows/prepareMemory.d.ts

@@ -0,0 +1,60 @@
+/**
+ * PrepareMemory subflow — load history from store + apply MessageStrategy.
+ *
+ * Flowchart (2 stages):
+ *   LoadHistory → ApplyStrategy
+ *
+ * LoadHistory: calls store.load(conversationId), merges stored history with
+ *   the current turn's message (added by SeedScope), writes merged history
+ *   to scope as `memory_storedHistory`.
+ *
+ * ApplyStrategy: applies the configured MessageStrategy to the merged history
+ *   (trim, window, summarize). Writes prepared messages to scope as
+ *   `memory_preparedMessages`. If no strategy, passes merged history through.
+ *
+ * The subflow is mounted via addSubFlowChartNext in Agent.ts:
+ *   inputMapper  — copies current messages from parent scope into subflow
+ *   outputMapper — copies prepared messages back to parent scope's `messages`
+ *
+ * No-op behavior:
+ *   - No store:    LoadHistory writes current messages as-is (no DB hit)
+ *   - No strategy: ApplyStrategy writes merged history as-is (no trimming)
+ *   Both stages are always present in the flowchart for narrative visibility.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { ConversationStore } from '../adapters/memory/types';
+import type { MessageStrategy } from '../core/providers';
+import type { MessagesSubflowState } from '../scope/types';
+/**
+ * Subset of MemoryConfig with all fields optional for subflow flexibility.
+ *
+ * Relationship to MemoryConfig:
+ *   - MemoryConfig: `store` + `conversationId` are required — used at Agent.memory() call site.
+ *   - PrepareMemoryConfig: all optional — enables no-op path (no store, no strategy).
+ *
+ * If MemoryConfig gains new fields (e.g. ttl, namespace), mirror them here.
+ */
+export interface PrepareMemoryConfig {
+    readonly store?: ConversationStore;
+    readonly conversationId?: string;
+    readonly strategy?: MessageStrategy;
+}
+/**
+ * Build the PrepareMemory subflow.
+ *
+ * Mount this with addSubFlowChartNext after SeedScope:
+ * ```typescript
+ * .addSubFlowChartNext('sf-prepare-memory', createPrepareMemorySubflow(config), 'PrepareMemory', {
+ *   inputMapper: (parent) => ({
+ *     currentMessages: parent.messages ?? [],
+ *     loopCount: parent.loopCount ?? 0,
+ *   }),
+ *   outputMapper: (sfOutput) => ({
+ *     memory_preparedMessages: sfOutput.memory_preparedMessages,
+ *     memory_storedHistory: sfOutput.memory_storedHistory,
+ *   }),
+ * })
+ * ```
+ */
+export declare function createPrepareMemorySubflow(config: PrepareMemoryConfig): import("footprintjs").RunnableFlowChart<any, TypedScope<MessagesSubflowState>>;
+//# sourceMappingURL=prepareMemory.d.ts.map

package/dist/types/subflows/prepareMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareMemory.d.ts","sourceRoot":"","sources":["../../../src/subflows/prepareMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,mBAAmB,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAI3D;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;CACrC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,mBAAmB,kFAkDrE"}

package/dist/types/tools/ToolRegistry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ToolRegistry — register, lookup, and format tools for LLM function calling.
+ */
+import type { ToolDefinition, LLMToolDescription } from '../types';
+export declare class ToolRegistry {
+    private readonly tools;
+    /** Register a tool. Throws if ID already registered. */
+    register(tool: ToolDefinition): this;
+    /** Get a tool by ID. */
+    get(id: string): ToolDefinition | undefined;
+    /** Check if a tool is registered. */
+    has(id: string): boolean;
+    /** Get all registered tool IDs. */
+    ids(): string[];
+    /** Get all registered tools. */
+    all(): ToolDefinition[];
+    /** Format tools for LLM function calling (OpenAI-compatible schema). */
+    formatForLLM(toolIds?: string[]): LLMToolDescription[];
+    /** Number of registered tools. */
+    get size(): number;
+}
+/**
+ * Define a tool inline. Accepts JSON Schema or Zod schema for `inputSchema`.
+ *
+ * @example JSON Schema
+ * ```typescript
+ * defineTool({
+ *   id: 'search',
+ *   description: 'Search the web',
+ *   inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+ *   handler: async ({ query }) => ({ content: `Results for: ${query}` }),
+ * });
+ * ```
+ *
+ * @example Zod schema (auto-converted, no zod dependency in core)
+ * ```typescript
+ * import { z } from 'zod';
+ * defineTool({
+ *   id: 'search',
+ *   description: 'Search the web',
+ *   inputSchema: z.object({ query: z.string().describe('Search query') }),
+ *   handler: async ({ query }) => ({ content: `Results for: ${query}` }),
+ * });
+ * ```
+ */
+export declare function defineTool(tool: ToolDefinition): ToolDefinition;
+//# sourceMappingURL=ToolRegistry.d.ts.map

package/dist/types/tools/ToolRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolRegistry.d.ts","sourceRoot":"","sources":["../../../src/tools/ToolRegistry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAGnE,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAE3D,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAQpC,wBAAwB;IACxB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI3C,qCAAqC;IACrC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,mCAAmC;IACnC,GAAG,IAAI,MAAM,EAAE;IAIf,gCAAgC;IAChC,GAAG,IAAI,cAAc,EAAE;IAIvB,wEAAwE;IACxE,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,kBAAkB,EAAE;IAgBtD,kCAAkC;IAClC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAS/D"}