agentfootprint 1.0.0

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

@@ -0,0 +1,10 @@
+export { createCallLLMStage } from './callLLMStage';
+export { createStreamingCallLLMStage } from './streamingCallLLMStage';
+export { parseResponseStage } from './parseResponseStage';
+export { createHandleResponseStage } from './handleResponseStage';
+export type { HandleResponseOptions } from './handleResponseStage';
+export { buildToolExecutionSubflow } from './toolExecutionSubflow';
+export type { ToolExecutionSubflowConfig, ToolExecutionSubflowState } from './toolExecutionSubflow';
+export { normalizeAdapterResponse, executeToolCalls } from './helpers';
+export type { CallLLMConfig } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/call/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACnE,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACpG,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACvE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/types/lib/call/parseResponseStage.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ParseResponse stage — extract ParsedResponse from AdapterResult.
+ *
+ * Also appends the assistant message to conversation history.
+ *
+ * Reads from scope:
+ *   - adapterResult (set by CallLLM)
+ *
+ * Writes to scope:
+ *   - parsedResponse (hasToolCalls, toolCalls[], content)
+ *   - messages (appends assistant message)
+ *   - responseType (narrative summary of the response)
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentLoopState } from '../../scope/types';
+/**
+ * ParseResponse stage function.
+ * Stateless — no factory needed.
+ */
+export declare function parseResponseStage(scope: TypedScope<AgentLoopState>): void;
+//# sourceMappingURL=parseResponseStage.d.ts.map

package/dist/types/lib/call/parseResponseStage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseResponseStage.d.ts","sourceRoot":"","sources":["../../../../src/lib/call/parseResponseStage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,CAAC,cAAc,CAAC,GAAG,IAAI,CAmC1E"}

package/dist/types/lib/call/streamingCallLLMStage.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Streaming CallLLM stage — bridges LLMProvider.chatStream() with footprintjs StreamCallback
+ * and emits AgentStreamEvents for consumer visibility.
+ *
+ * Events emitted:
+ *   - llm_start { iteration } — before the LLM call
+ *   - token { content } — each text chunk from the LLM
+ *   - thinking { content } — extended thinking blocks (Anthropic)
+ *   - llm_end { iteration, toolCallCount, content, model, latencyMs } — after LLM completes
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentLoopState } from '../../scope/types';
+import type { LLMProvider, ResponseFormat } from '../../types';
+import type { AgentStreamEventHandler } from '../../streaming';
+export interface StreamingCallLLMStageOptions {
+    onStreamEvent?: AgentStreamEventHandler;
+    responseFormat?: ResponseFormat;
+}
+/**
+ * Create a streaming-capable CallLLM stage function.
+ */
+export declare function createStreamingCallLLMStage(provider: LLMProvider, optionsOrHandler?: StreamingCallLLMStageOptions | AgentStreamEventHandler): (scope: TypedScope<AgentLoopState>, _breakFn: () => void, streamCallback?: (token: string) => void) => Promise<void>;
+//# sourceMappingURL=streamingCallLLMStage.d.ts.map

package/dist/types/lib/call/streamingCallLLMStage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamingCallLLMStage.d.ts","sourceRoot":"","sources":["../../../../src/lib/call/streamingCallLLMStage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAA+B,cAAc,EAAY,MAAM,aAAa,CAAC;AACtG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAG/D,MAAM,WAAW,4BAA4B;IAC3C,aAAa,CAAC,EAAE,uBAAuB,CAAC;IACxC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,WAAW,EACrB,gBAAgB,CAAC,EAAE,4BAA4B,GAAG,uBAAuB,WAUhE,WAAW,cAAc,CAAC,YACvB,MAAM,IAAI,mBACH,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,mBA0F3C"}

package/dist/types/lib/call/toolExecutionSubflow.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Tool Execution Subflow — executes tool calls as a visible subflow.
+ *
+ * Replaces inline executeToolCalls() in HandleResponse with a proper subflow
+ * that appears in the flowchart and narrative. Enables:
+ *   - BTS drill-down into tool execution
+ *   - Per-tool visibility in narrative
+ *   - Future: parallel fork stages for individual tool calls
+ *
+ * The subflow has a single stage (ExecuteToolCalls) that runs all tools
+ * sequentially and appends results to messages.
+ *
+ * Config (registry, toolProvider) is closed over at build time — not
+ * passed through inputMapper.
+ */
+import type { FlowChart } from 'footprintjs';
+import type { Message } from '../../types';
+import type { ToolRegistry } from '../../tools';
+import type { ToolProvider } from '../../core';
+import type { InstructionConfig } from './helpers';
+import type { ParsedResponse } from '../../scope/types';
+/** State for the tool execution subflow.
+ *
+ * Uses prefixed input keys (currentMessages, currentLoopCount) to avoid
+ * read-only input conflict — subflow inputs from inputMapper are frozen.
+ *
+ * Output keys:
+ * - `toolResultMessages`: DELTA only (new tool result messages), not the full array.
+ *   footprintjs's applyOutputMapping uses array concat for arrays, so the parent's
+ *   outputMapper maps this to `messages` and the concat correctly appends the delta.
+ * - `updatedLoopCount`: incremented loop count (scalar → replaced).
+ */
+export interface ToolExecutionSubflowState {
+    /** Input: parsed response with tool calls (read-only from inputMapper). */
+    parsedResponse: ParsedResponse;
+    /** Input: current conversation messages (read-only from inputMapper). */
+    currentMessages: Message[];
+    /** Input: current loop iteration (read-only from inputMapper). */
+    currentLoopCount: number;
+    /** Input: max iterations allowed (read-only from inputMapper). */
+    maxIterations: number;
+    /** Output: NEW tool result messages only (delta for array concat). */
+    toolResultMessages: Message[];
+    /** Output: incremented loop count. */
+    updatedLoopCount: number;
+    /** Input: current Decision Scope (read-only from inputMapper). */
+    currentDecision?: Record<string, unknown>;
+    /** Output: updated Decision Scope after decide() mutations. */
+    updatedDecision?: Record<string, unknown>;
+    /** @internal Set when ask_human tool fires — used for pause detection. */
+    askHumanPause?: {
+        question: string;
+        toolCallId: string;
+    };
+}
+export interface ToolExecutionSubflowConfig {
+    readonly registry: ToolRegistry;
+    readonly toolProvider?: ToolProvider;
+    /** Instruction processing config — when provided, instructions are evaluated after each tool call. */
+    readonly instructionConfig?: InstructionConfig;
+}
+/**
+ * Build the tool execution subflow.
+ *
+ * Registry and toolProvider are closed over — they don't travel
+ * through inputMapper. Only scope state (parsedResponse, messages,
+ * loopCount) is mapped.
+ */
+export declare function buildToolExecutionSubflow(config: ToolExecutionSubflowConfig): FlowChart;
+//# sourceMappingURL=toolExecutionSubflow.d.ts.map

package/dist/types/lib/call/toolExecutionSubflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolExecutionSubflow.d.ts","sourceRoot":"","sources":["../../../../src/lib/call/toolExecutionSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKxD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,cAAc,EAAE,cAAc,CAAC;IAC/B,yEAAyE;IACzE,eAAe,EAAE,OAAO,EAAE,CAAC;IAC3B,kEAAkE;IAClE,gBAAgB,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,kBAAkB,EAAE,OAAO,EAAE,CAAC;IAC9B,sCAAsC;IACtC,gBAAgB,EAAE,MAAM,CAAC;IAEzB,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,aAAa,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAID,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,sGAAsG;IACtG,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD;AAID;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,0BAA0B,GACjC,SAAS,CAuFX"}

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

@@ -0,0 +1,17 @@
+/**
+ * Call module types.
+ *
+ * The call module contains the three stages that happen AFTER the three API slots:
+ *   CallLLM → ParseResponse → HandleResponse
+ *
+ * These stages consume what the slots wrote to scope and produce the LLM result.
+ */
+import type { LLMProvider } from '../../types';
+/**
+ * Config for CallLLM stage.
+ */
+export interface CallLLMConfig {
+    /** The LLM provider to call (Anthropic, OpenAI, mock, etc.). */
+    readonly provider: LLMProvider;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/call/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC"}

package/dist/types/lib/concepts/Agent.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Agent — re-exports builder and runner from split files.
+ * Preserves backward compatibility for imports.
+ */
+export { Agent } from './AgentBuilder';
+export type { AgentOptions } from './AgentBuilder';
+export { AgentRunner } from './AgentRunner';
+export type { AgentRunnerOptions } from './AgentRunner';
+//# sourceMappingURL=Agent.d.ts.map

package/dist/types/lib/concepts/Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../../src/lib/concepts/Agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/types/lib/concepts/AgentBuilder.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Agent builder — fluent API for configuring an agent.
+ *
+ * Usage:
+ *   const agent = Agent.create({ provider })
+ *     .system('You are helpful.')
+ *     .tool(searchTool)
+ *     .build();
+ */
+import type { ToolDefinition, LLMProvider } from '../../types';
+import type { ModelConfig } from '../../models';
+import type { MemoryConfig } from '../../adapters/memory/types';
+import type { AgentRecorder, PromptProvider, ToolProvider } from '../../core';
+import type { InstructionOverride, AgentInstruction } from '../instructions';
+import { AgentPattern } from '../loop';
+import { AgentRunner } from './AgentRunner';
+export interface AgentOptions {
+    /** LLMProvider instance or ModelConfig from anthropic()/openai()/bedrock()/ollama(). */
+    readonly provider: LLMProvider | ModelConfig;
+    readonly name?: string;
+}
+export declare class Agent {
+    private readonly provider;
+    private readonly agentName;
+    private systemPromptText?;
+    private customPromptProvider?;
+    private readonly registry;
+    private customToolProvider?;
+    private maxIter;
+    private readonly recorders;
+    private memoryConfig?;
+    private agentPattern;
+    private readonly overrides;
+    private readonly agentInstructions;
+    private initialDecisionScope?;
+    private enableStreaming;
+    private enableVerboseNarrative;
+    private outputResponseFormat?;
+    private constructor();
+    /**
+     * Create an agent builder.
+     *
+     * Accepts either an LLMProvider or a ModelConfig from factory functions:
+     * ```ts
+     * // With ModelConfig (auto-resolved)
+     * Agent.create({ provider: anthropic('claude-sonnet-4-20250514') })
+     *
+     * // With LLMProvider (direct)
+     * Agent.create({ provider: new AnthropicAdapter({ model: '...' }) })
+     * ```
+     */
+    static create(options: AgentOptions): Agent;
+    /** Set system prompt (static — same every iteration). */
+    system(prompt: string): this;
+    /**
+     * Set a custom prompt provider (dynamic — can change each iteration).
+     * Overrides `.system()`.
+     */
+    promptProvider(provider: PromptProvider): this;
+    /** Register a tool. */
+    tool(toolDef: ToolDefinition): this;
+    /** Register multiple tools. */
+    tools(toolDefs: ToolDefinition[]): this;
+    /**
+     * Set a custom tool provider (dynamic — can change each iteration).
+     * Overrides `.tool()` / `.tools()`.
+     */
+    toolProvider(provider: ToolProvider): this;
+    /** Set max ReAct loop iterations. */
+    maxIterations(n: number): this;
+    /** Enable streaming — tokens emitted incrementally via onToken callback. */
+    streaming(enabled?: boolean): this;
+    /**
+     * Enable verbose narrative — full values, no truncation.
+     * Shows complete system prompts, tool results, and LLM outputs in the narrative.
+     * Enables grounding analysis via getGroundingSources() / getLLMClaims().
+     */
+    verbose(enabled?: boolean): this;
+    /**
+     * Request structured JSON output matching a schema.
+     * Accepts JSON Schema or Zod schema (auto-converted).
+     *
+     * @param schema - JSON Schema object or Zod schema
+     * @param options - Optional: name for the schema, injection position for non-native providers
+     *
+     * @example
+     * ```ts
+     * // JSON Schema
+     * agent.outputSchema({ type: 'object', properties: { city: { type: 'string' } } })
+     *
+     * // Zod schema
+     * agent.outputSchema(z.object({ city: z.string() }))
+     *
+     * // Inject in user message (recency window) instead of system prompt
+     * agent.outputSchema(z.object({ city: z.string() }), { injection: 'user' })
+     * ```
+     */
+    outputSchema(schema: Record<string, unknown>, options?: {
+        name?: string;
+        injection?: 'system' | 'user';
+    }): this;
+    /**
+     * Set the agent loop pattern.
+     * - `AgentPattern.Regular` (default): slots resolve once
+     * - `AgentPattern.Dynamic`: all slots re-evaluate each iteration
+     */
+    pattern(p: AgentPattern): this;
+    /**
+     * Override instructions on a shared tool without modifying the tool definition.
+     */
+    instructionOverride(toolId: string, override: InstructionOverride): this;
+    /**
+     * Register an agent-level instruction.
+     * Instructions inject into system prompt, tools, and tool-result processing
+     * based on the Decision Scope state.
+     *
+     * @example
+     * ```typescript
+     * Agent.create({ provider })
+     *   .instruction(defineInstruction({
+     *     id: 'refund',
+     *     activeWhen: (d) => d.orderStatus === 'denied',
+     *     prompt: 'Be empathetic.',
+     *   }))
+     *   .build();
+     * ```
+     */
+    instruction(instr: AgentInstruction<any>): this;
+    /** Register multiple agent-level instructions. */
+    instructions(instrs: AgentInstruction<any>[]): this;
+    /**
+     * Set the initial Decision Scope values.
+     * Tool handlers update these values; InstructionsToLLM reads them
+     * to evaluate `activeWhen` predicates.
+     *
+     * @example
+     * ```typescript
+     * Agent.create({ provider })
+     *   .decision<MyDecision>({ orderStatus: null, riskLevel: 'unknown' })
+     *   .instruction(refundInstruction)
+     *   .build();
+     * ```
+     */
+    decision<T extends Record<string, unknown> = Record<string, unknown>>(scope: T): this;
+    /** Enable persistent conversation memory. */
+    memory(config: MemoryConfig): this;
+    /** Attach an AgentRecorder to observe execution events. */
+    recorder(rec: AgentRecorder): this;
+    /** Build the agent and return a runner. */
+    build(): AgentRunner;
+}
+//# sourceMappingURL=AgentBuilder.d.ts.map

package/dist/types/lib/concepts/AgentBuilder.d.ts.map

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

package/dist/types/lib/concepts/AgentRunner.d.ts

@@ -0,0 +1,100 @@
+/**
+ * AgentRunner — executes the agent loop, manages conversation state.
+ *
+ * Created by Agent.build(). Not instantiated directly.
+ */
+import type { FlowChart as FlowChartType } from 'footprintjs';
+import { AgentPattern } from '../loop';
+import type { InstructionOverride, AgentInstruction } from '../instructions';
+import type { AgentStreamEventHandler } from '../../streaming';
+import { ToolRegistry } from '../../tools';
+import type { LLMProvider, AgentResult, Message, ResponseFormat } from '../../types';
+import type { MemoryConfig } from '../../adapters/memory/types';
+import type { AgentRecorder, PromptProvider, ToolProvider } from '../../core';
+/** Options for constructing an AgentRunner. Created by Agent.build(). */
+export interface AgentRunnerOptions {
+    readonly provider: LLMProvider;
+    readonly name: string;
+    readonly systemPromptText?: string;
+    readonly registry: ToolRegistry;
+    readonly maxIterations?: number;
+    readonly recorders?: AgentRecorder[];
+    readonly memoryConfig?: MemoryConfig;
+    readonly pattern?: AgentPattern;
+    readonly promptProvider?: PromptProvider;
+    readonly toolProvider?: ToolProvider;
+    readonly instructionOverrides?: ReadonlyMap<string, InstructionOverride>;
+    readonly agentInstructions?: readonly AgentInstruction[];
+    readonly initialDecision?: Readonly<Record<string, unknown>>;
+    readonly streaming?: boolean;
+    /** When true, narrative shows full values (no truncation). */
+    readonly verboseNarrative?: boolean;
+    /** Structured output format — passed through to LLM provider. */
+    readonly responseFormat?: ResponseFormat;
+}
+export declare class AgentRunner {
+    private static _autoExecCounter;
+    private readonly provider;
+    readonly name: string;
+    private readonly systemPromptText?;
+    private readonly registry;
+    private readonly maxIter;
+    private readonly recorders;
+    private readonly memoryConfig?;
+    private readonly agentPattern;
+    private readonly customPromptProvider?;
+    private readonly customToolProvider?;
+    private readonly instructionOverrides?;
+    private readonly agentInstructions?;
+    private readonly initialDecision?;
+    private readonly streamingEnabled;
+    private readonly responseFormat?;
+    private readonly cachedDecideFunctions?;
+    private conversationHistory;
+    private lastExecutor?;
+    private lastSpec?;
+    private readonly verboseNarrative;
+    private narrativeRenderer;
+    private readonly pendingFollowUps;
+    constructor(options: AgentRunnerOptions);
+    /** Expose the agent's internal flowChart for subflow composition. */
+    toFlowChart(): FlowChartType;
+    /** Run the agent with a user message. */
+    run(message: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+        /** Full event stream — tool lifecycle, LLM lifecycle, tokens. */
+        onEvent?: AgentStreamEventHandler;
+        /** @deprecated Use onEvent instead. Ignored if onEvent is also provided. */
+        onToken?: (token: string) => void;
+    }): Promise<AgentResult>;
+    /**
+     * Resume a paused agent (after ask_human tool).
+     *
+     * Provides the human's response, which becomes the tool result for ask_human.
+     * The agent loop continues from where it paused.
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.run('Process my refund');
+     * if (result.paused) {
+     *   const final = await agent.resume('Yes, order ORD-123');
+     * }
+     * ```
+     *
+     * Note: `onEvent` streaming is not yet supported on `resume()`.
+     * The resumed turn completes without emitting AgentStreamEvents.
+     * Use `result.content` and `agent.getNarrative()` for post-resume data.
+     */
+    resume(humanResponse: string): Promise<AgentResult>;
+    /** Extract AgentResult from executor state — shared by run() and resume(). */
+    private buildResult;
+    getNarrative(): string[];
+    getNarrativeEntries(): import("footprintjs").CombinedNarrativeEntry[];
+    getSnapshot(): import("footprintjs").RuntimeSnapshot | undefined;
+    getSpec(): unknown;
+    getMessages(): Message[];
+    resetConversation(): void;
+    private buildConfig;
+}
+//# sourceMappingURL=AgentRunner.d.ts.map

package/dist/types/lib/concepts/AgentRunner.d.ts.map

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

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

@@ -0,0 +1,3 @@
+export { Agent, AgentRunner } from './Agent';
+export type { AgentOptions } from './Agent';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/concepts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}

package/dist/types/lib/instructions/InstructionRecorder.d.ts

@@ -0,0 +1,85 @@
+/**
+ * InstructionRecorder — tracks which LLM instructions fired and follow-up usage.
+ *
+ * Implements AgentRecorder so it plugs into the standard `.recorder()` API.
+ * Records per-tool instruction firings and follow-up accuracy for evaluation.
+ *
+ * @example
+ * ```typescript
+ * import { Agent, InstructionRecorder } from 'agentfootprint';
+ *
+ * const recorder = new InstructionRecorder();
+ * const agent = Agent.create({ provider })
+ *   .recorder(recorder)
+ *   .build();
+ *
+ * await agent.run('Check my order');
+ *
+ * console.log(recorder.getSummary());
+ * // {
+ * //   totalFired: 2,
+ * //   totalFollowUpsOffered: 1,
+ * //   byTool: {
+ * //     check_order: {
+ * //       instructions: { 'cancelled': { fired: 1, safety: false } },
+ * //       followUps: { 'get_trace': { offered: 1 } },
+ * //     }
+ * //   }
+ * // }
+ * ```
+ */
+import type { AgentRecorder } from '../../core';
+import type { ResolvedInstruction } from './evaluator';
+export interface InstructionFiring {
+    /** Number of times this instruction fired. */
+    readonly fired: number;
+    /** Whether this is a safety instruction. */
+    readonly safety: boolean;
+}
+export interface FollowUpOffering {
+    /** Number of times this follow-up was offered. */
+    readonly offered: number;
+    /** Target tool ID. */
+    readonly toolId: string;
+}
+export interface ToolInstructionStats {
+    /** Instructions that fired for this tool, keyed by instruction ID. */
+    readonly instructions: Record<string, InstructionFiring>;
+    /** Follow-ups offered for this tool, keyed by follow-up toolId. */
+    readonly followUps: Record<string, FollowUpOffering>;
+}
+export interface InstructionSummary {
+    /** Total instructions fired across all tools. */
+    readonly totalFired: number;
+    /** Total follow-ups offered across all tools. */
+    readonly totalFollowUpsOffered: number;
+    /** Per-tool breakdown. */
+    readonly byTool: Record<string, ToolInstructionStats>;
+}
+export declare class InstructionRecorder implements AgentRecorder {
+    readonly id: string;
+    private firings;
+    private followUps;
+    constructor(id?: string);
+    /**
+     * Record instructions that fired for a tool invocation.
+     *
+     * Called by the agent loop after processInstructions() completes.
+     * Not an AgentRecorder hook — this is a dedicated method because
+     * instruction events don't map to the standard onLLMCall/onToolCall events.
+     */
+    recordFirings(toolId: string, fired: ResolvedInstruction[]): void;
+    /** Get summary of all instruction firings and follow-up offerings. */
+    getSummary(): InstructionSummary;
+    /** Get firing count for a specific instruction on a specific tool. */
+    getFiringCount(toolId: string, instructionId: string): number;
+    /** Get all instruction IDs that fired for a tool. */
+    getFiredInstructionIds(toolId: string): string[];
+    /** Serialize for inclusion in executor.getSnapshot().recorders. */
+    toSnapshot(): {
+        name: string;
+        data: unknown;
+    };
+    clear(): void;
+}
+//# sourceMappingURL=InstructionRecorder.d.ts.map

package/dist/types/lib/instructions/InstructionRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstructionRecorder.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/InstructionRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIvD,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzD,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACvD;AAID,qBAAa,mBAAoB,YAAW,aAAa;IACvD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,OAAO,CAAsE;IACrF,OAAO,CAAC,SAAS,CAAqE;gBAE1E,EAAE,SAAyB;IAIvC;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,GAAG,IAAI;IA2BjE,sEAAsE;IACtE,UAAU,IAAI,kBAAkB;IAkChC,sEAAsE;IACtE,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IAI7D,qDAAqD;IACrD,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAKhD,mEAAmE;IACnE,UAAU,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE;IAI7C,KAAK,IAAI,IAAI;CAId"}