agentfootprint 1.0.0

package/dist/types/core/providers.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Provider interfaces — active strategies that shape what the LLM sees.
+ *
+ * Every provider resolves a value AND explains its decision via SlotDecision<T>.
+ * The decision (chosen + rationale) appears in the narrative — making every
+ * strategy choice explainable.
+ *
+ * @example
+ * ```typescript
+ * // Static provider — always returns the same value
+ * { value: 'You are helpful.', chosen: 'static' }
+ *
+ * // Dynamic provider — changes based on conversation state
+ * { value: [...adminTools], chosen: 'elevated', rationale: 'identity verified' }
+ * ```
+ */
+import type { Message, ToolCall } from '../types/messages';
+import type { LLMToolDescription } from '../types/llm';
+/**
+ * Every slot resolver returns a value AND a decision explanation.
+ *
+ * - `value`: the resolved output (tools, prompt, messages)
+ * - `chosen`: label for what was selected — shown in narrative
+ * - `rationale`: why this choice was made — shown in narrative
+ *
+ * The narrative renders: `"Chose {chosen} ({rationale})"`
+ *
+ * @example
+ * ```typescript
+ * // Simple static decision
+ * { value: 'You are helpful.', chosen: 'static' }
+ *
+ * // Dynamic decision based on conversation state
+ * {
+ *   value: [...basicTools, ...adminTools],
+ *   chosen: 'elevated',
+ *   rationale: 'identity verified in previous turn',
+ * }
+ *
+ * // Message strategy decision
+ * {
+ *   value: keptMessages,
+ *   chosen: 'sliding-window',
+ *   rationale: 'kept 12 of 45 messages',
+ * }
+ * ```
+ */
+export interface SlotDecision<T> {
+    /** The resolved value. */
+    readonly value: T;
+    /** What was chosen — shown as decision label in narrative. */
+    readonly chosen: string;
+    /** Why this was chosen — shown as rationale in narrative. Optional for static providers. */
+    readonly rationale?: string;
+}
+export interface PromptContext {
+    /** Current user message. */
+    readonly message: string;
+    /** Which turn number this is (0-indexed). */
+    readonly turnNumber: number;
+    /** Full conversation history (for adaptive prompts). */
+    readonly history: Message[];
+    /** AbortSignal for cancellation (async prompt providers should respect this). */
+    readonly signal?: AbortSignal;
+}
+export interface MessageContext {
+    /** Current user message being processed. */
+    readonly message: string;
+    /** Which turn number this is. */
+    readonly turnNumber: number;
+    /** Current loop iteration within a turn (for tool loops). */
+    readonly loopIteration: number;
+    /** AbortSignal for cancellation. */
+    readonly signal?: AbortSignal;
+}
+export interface ToolContext {
+    /** Current user message. */
+    readonly message: string;
+    /** Which turn number this is. */
+    readonly turnNumber: number;
+    /** Current loop iteration within a turn. */
+    readonly loopIteration: number;
+    /** Messages so far (for context-dependent tool resolution). */
+    readonly messages: Message[];
+    /** AbortSignal for cancellation (dynamic tool resolution may need this). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Resolves the system prompt for a given turn.
+ *
+ * Returns `SlotDecision<string>` — the prompt text + why this prompt was chosen.
+ * Static providers return `chosen: 'static'`. Dynamic providers explain the reason.
+ *
+ * @example
+ * ```typescript
+ * const dynamicPrompt: PromptProvider = {
+ *   resolve: (ctx) => {
+ *     const hasFlaggedOrder = ctx.history.some(m => m.content?.includes('flagged'));
+ *     if (hasFlaggedOrder) {
+ *       return { value: escalationPrompt, chosen: 'escalation', rationale: 'flagged order detected' };
+ *     }
+ *     return { value: basicPrompt, chosen: 'standard' };
+ *   },
+ * };
+ * ```
+ */
+export interface PromptProvider {
+    resolve(context: PromptContext): SlotDecision<string> | Promise<SlotDecision<string>>;
+}
+/**
+ * Prepares the message array sent to the LLM each turn.
+ *
+ * Returns `SlotDecision<Message[]>` — the prepared messages + strategy label.
+ *
+ * @example
+ * ```typescript
+ * const strategy: MessageStrategy = {
+ *   prepare: (history, ctx) => {
+ *     if (history.length > 50) {
+ *       const kept = history.slice(-20);
+ *       return { value: kept, chosen: 'truncated', rationale: `kept 20 of ${history.length}` };
+ *     }
+ *     return { value: history, chosen: 'full', rationale: `${history.length} messages` };
+ *   },
+ * };
+ * ```
+ */
+export interface MessageStrategy {
+    prepare(history: Message[], context: MessageContext): SlotDecision<Message[]> | Promise<SlotDecision<Message[]>>;
+}
+/**
+ * Resolves available tools and optionally executes tool calls.
+ *
+ * Returns `SlotDecision<LLMToolDescription[]>` — the tool set + decision.
+ *
+ * @example
+ * ```typescript
+ * const dynamicTools: ToolProvider = {
+ *   resolve: (ctx) => {
+ *     const verified = ctx.messages.some(m =>
+ *       m.role === 'tool' && m.content.includes('"verified":true'));
+ *     if (verified) {
+ *       return { value: [...basic, ...admin], chosen: 'elevated', rationale: 'identity verified' };
+ *     }
+ *     return { value: basic, chosen: 'basic', rationale: 'standard access' };
+ *   },
+ * };
+ * ```
+ */
+export interface ToolProvider {
+    /** Which tools to offer the LLM this turn. */
+    resolve(context: ToolContext): SlotDecision<LLMToolDescription[]> | Promise<SlotDecision<LLMToolDescription[]>>;
+    /** Execute a tool call. Optional — if omitted, core loop uses ToolDefinition.handler directly. */
+    execute?(call: ToolCall, signal?: AbortSignal): Promise<ToolExecutionResult>;
+}
+export interface ToolExecutionResult {
+    readonly content: string;
+    readonly error?: boolean;
+}
+//# sourceMappingURL=providers.d.ts.map

package/dist/types/core/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/core/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAMvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;CACvF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,YAAY,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;CAClH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,YAAY,CAAC,kBAAkB,EAAE,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;IAChH,kGAAkG;IAClG,OAAO,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC9E;AAID,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B"}

package/dist/types/core/recorders.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Recorder interface — passive observers that watch but don't shape behavior.
+ * Like Recorder/FlowRecorder in footprintjs.
+ */
+import type { LLMResponse, TokenUsage } from '../types/llm';
+import type { ToolExecutionResult } from './providers';
+/**
+ * Observes agent execution events without changing behavior.
+ * Metrics, cost tracking, quality evaluation — all implement this.
+ *
+ * All hooks are optional. Implement only what you need.
+ * Like footprintjs FlowRecorder: `{ id, optional hooks }`.
+ */
+export interface AgentRecorder {
+    readonly id: string;
+    onTurnStart?(event: TurnStartEvent): void;
+    onLLMCall?(event: LLMCallEvent): void;
+    onToolCall?(event: ToolCallEvent): void;
+    onTurnComplete?(event: TurnCompleteEvent): void;
+    onError?(event: AgentErrorEvent): void;
+    clear?(): void;
+}
+export interface TurnStartEvent {
+    readonly turnNumber: number;
+    readonly message: string;
+}
+export interface LLMCallEvent {
+    readonly model?: string;
+    readonly usage?: TokenUsage;
+    readonly latencyMs: number;
+    readonly turnNumber: number;
+    readonly loopIteration: number;
+    readonly finishReason?: LLMResponse['finishReason'];
+}
+export interface ToolCallEvent {
+    readonly toolName: string;
+    readonly args: Record<string, unknown>;
+    readonly result: ToolExecutionResult;
+    readonly latencyMs: number;
+}
+export interface TurnCompleteEvent {
+    readonly turnNumber: number;
+    readonly messageCount: number;
+    readonly totalLoopIterations: number;
+    readonly content: string;
+}
+/** Phase of agent execution where an event occurred. */
+export type AgentPhase = 'prompt' | 'llm' | 'tool' | 'message';
+export interface AgentErrorEvent {
+    readonly phase: AgentPhase;
+    readonly error: unknown;
+    readonly turnNumber: number;
+}
+//# sourceMappingURL=recorders.d.ts.map

package/dist/types/core/recorders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorders.d.ts","sourceRoot":"","sources":["../../../src/core/recorders.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIvD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C,SAAS,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACtC,UAAU,CAAC,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC,cAAc,CAAC,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAChD,OAAO,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACvC,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAID,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B"}

package/dist/types/errors.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Normalized error types for LLM provider errors.
+ *
+ * All adapters wrap SDK-specific errors into LLMError so that
+ * compositions (withRetry, withFallback, withCircuitBreaker)
+ * can make uniform decisions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapSDKError = exports.classifyStatusCode = exports.LLMError = void 0;
+class LLMError extends Error {
+    code;
+    provider;
+    statusCode;
+    retryable;
+    cause;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'LLMError';
+        this.code = opts.code;
+        this.provider = opts.provider;
+        this.statusCode = opts.statusCode;
+        this.cause = opts.cause;
+        this.retryable = isRetryable(opts.code);
+    }
+}
+exports.LLMError = LLMError;
+function isRetryable(code) {
+    return code === 'rate_limit' || code === 'server' || code === 'timeout' || code === 'network';
+}
+/** Classify an HTTP status code into an LLMErrorCode. */
+function classifyStatusCode(status) {
+    if (status === 401 || status === 403)
+        return 'auth';
+    if (status === 429)
+        return 'rate_limit';
+    if (status === 400)
+        return 'invalid_request';
+    if (status === 413 || status === 422)
+        return 'context_length';
+    if (status >= 500)
+        return 'server';
+    return 'unknown';
+}
+exports.classifyStatusCode = classifyStatusCode;
+/** Wrap an unknown SDK error into an LLMError. */
+function wrapSDKError(err, provider) {
+    if (err instanceof LLMError)
+        return err;
+    const error = err instanceof Error ? err : new Error(String(err));
+    const message = error.message;
+    // AbortError from signal
+    if (error.name === 'AbortError' || message.includes('aborted')) {
+        return new LLMError({ message, code: 'aborted', provider, cause: error });
+    }
+    // Timeout
+    if (message.includes('timeout') || message.includes('ETIMEDOUT')) {
+        return new LLMError({ message, code: 'timeout', provider, cause: error });
+    }
+    // Network
+    if (message.includes('ECONNREFUSED') ||
+        message.includes('ENOTFOUND') ||
+        message.includes('fetch failed')) {
+        return new LLMError({ message, code: 'network', provider, cause: error });
+    }
+    // HTTP status code from SDK errors (Anthropic and OpenAI both expose .status)
+    const statusCode = err.status;
+    if (statusCode) {
+        return new LLMError({
+            message,
+            code: classifyStatusCode(statusCode),
+            provider,
+            statusCode,
+            cause: error,
+        });
+    }
+    return new LLMError({ message, code: 'unknown', provider, cause: error });
+}
+exports.wrapSDKError = wrapSDKError;
+//# sourceMappingURL=errors.js.map

package/dist/types/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAaH,MAAa,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAe;IACnB,QAAQ,CAAS;IACjB,UAAU,CAAU;IACpB,SAAS,CAAU;IACnB,KAAK,CAAS;IAEvB,YAAY,IAMX;QACC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;CACF;AAtBD,4BAsBC;AAED,SAAS,WAAW,CAAC,IAAkB;IACrC,OAAO,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,CAAC;AAChG,CAAC;AAED,yDAAyD;AACzD,SAAgB,kBAAkB,CAAC,MAAc;IAC/C,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,MAAM,CAAC;IACpD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,YAAY,CAAC;IACxC,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,iBAAiB,CAAC;IAC7C,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,gBAAgB,CAAC;IAC9D,IAAI,MAAM,IAAI,GAAG;QAAE,OAAO,QAAQ,CAAC;IACnC,OAAO,SAAS,CAAC;AACnB,CAAC;AAPD,gDAOC;AAED,kDAAkD;AAClD,SAAgB,YAAY,CAAC,GAAY,EAAE,QAAgB;IACzD,IAAI,GAAG,YAAY,QAAQ;QAAE,OAAO,GAAG,CAAC;IAExC,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAE9B,yBAAyB;IACzB,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/D,OAAO,IAAI,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,UAAU;IACV,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACjE,OAAO,IAAI,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,UAAU;IACV,IACE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;QAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EAChC,CAAC;QACD,OAAO,IAAI,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,8EAA8E;IAC9E,MAAM,UAAU,GAAI,GAA2B,CAAC,MAAM,CAAC;IACvD,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,IAAI,QAAQ,CAAC;YAClB,OAAO;YACP,IAAI,EAAE,kBAAkB,CAAC,UAAU,CAAC;YACpC,QAAQ;YACR,UAAU;YACV,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAC5E,CAAC;AAtCD,oCAsCC"}

package/dist/types/executor/agentLoop.d.ts

@@ -0,0 +1,37 @@
+/**
+ * agentLoop — the core execution engine.
+ *
+ * Takes an AgentLoopConfig (providers + recorders + options) and executes
+ * a single turn of the agent loop:
+ *   1. Resolve system prompt (PromptProvider)
+ *   2. Prepare messages (MessageStrategy)
+ *   3. Call LLM
+ *   4. If tool calls → execute tools → loop to step 3
+ *   5. If final response → return result
+ *
+ * Built on footprintjs flowchart (SeedScope → Prompt → LLM → Parse → Handle → loop).
+ * All observation happens through AgentRecorders attached to the config.
+ *
+ * Usage:
+ *   const result = await agentLoop(config, 'Hello', { signal, timeoutMs });
+ */
+import type { AgentLoopConfig } from '../core';
+import type { Message } from '../types/messages';
+export interface AgentLoopOptions {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    /** Existing conversation history (for multi-turn). */
+    readonly history?: Message[];
+    /** Turn number (for multi-turn tracking). */
+    readonly turnNumber?: number;
+}
+export interface AgentLoopResult {
+    /** Final text content from the agent. */
+    readonly content: string;
+    /** Full message history after this turn. */
+    readonly messages: Message[];
+    /** Number of LLM calls in this turn (1 = no tool loops). */
+    readonly loopIterations: number;
+}
+export declare function agentLoop(config: AgentLoopConfig, message: string, options?: AgentLoopOptions): Promise<AgentLoopResult>;
+//# sourceMappingURL=agentLoop.d.ts.map

package/dist/types/executor/agentLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentLoop.d.ts","sourceRoot":"","sources":["../../../src/executor/agentLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAS/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAMjD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAID,wBAAsB,SAAS,CAC7B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAkI1B"}

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

@@ -0,0 +1,6 @@
+/**
+ * executor/ — The agentLoop execution engine.
+ */
+export { agentLoop } from './agentLoop';
+export type { AgentLoopOptions, AgentLoopResult } from './agentLoop';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/executor/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,20 @@
+/**
+ * agentfootprint/explain — Understand agent decisions.
+ *
+ * Extract grounding sources (tool results) and LLM claims for hallucination detection.
+ * Verbose narrative mode for full values. AgentScopeKey enum for type-safe queries.
+ *
+ * @example
+ * ```typescript
+ * import { getGroundingSources, getLLMClaims } from 'agentfootprint/explain';
+ *
+ * const entries = agent.getNarrativeEntries();
+ * const sources = getGroundingSources(entries);  // what tools returned
+ * const claims = getLLMClaims(entries);           // what the LLM said
+ * ```
+ */
+export { getGroundingSources, getLLMClaims, getFullLLMContext, createAgentRenderer } from './lib/narrative';
+export type { GroundingSource, LLMClaim, LLMContextSnapshot, AgentRendererOptions } from './lib/narrative';
+export { ExplainRecorder } from './recorders/v2/ExplainRecorder';
+export type { ToolSource, AgentDecision, Explanation } from './recorders/v2/ExplainRecorder';
+//# sourceMappingURL=explain.barrel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"explain.barrel.d.ts","sourceRoot":"","sources":["../../src/explain.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC5G,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG3G,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * agentfootprint — The explainable agent framework.
+ *
+ * Core: builders, tools, providers, messages, types.
+ *
+ * Focused capabilities (also importable from subpaths):
+ *   agentfootprint/instructions  → Conditional context injection
+ *   agentfootprint/observe       → Monitor execution (recorders)
+ *   agentfootprint/resilience    → Retry, fallback, circuit breaker
+ *   agentfootprint/security      → Tool gating, permissions
+ *   agentfootprint/explain       → Narrative, grounding analysis
+ *   agentfootprint/stream        → Real-time lifecycle events
+ */
+export { Agent, AgentRunner, LLMCall, LLMCallRunner, RAG, RAGRunner, FlowChart, FlowChartRunner, Swarm, SwarmRunner, Parallel, ParallelRunner, } from './concepts';
+export { defineTool, askHuman, ToolRegistry } from './tools';
+export { mock, MockAdapter, mockRetriever, MockRetriever, createProvider } from './adapters';
+export { anthropic, openai, ollama, bedrock } from './models';
+export { AnthropicAdapter, OpenAIAdapter, BedrockAdapter } from './adapters';
+export { BrowserAnthropicAdapter, BrowserOpenAIAdapter } from './adapters';
+export { InMemoryStore } from './adapters/memory/inMemory';
+export { redisStore, dynamoStore, postgresStore } from './adapters/memory/stores';
+export type { ModelConfig } from './models';
+export type { PromptProvider, PromptContext, ToolProvider, ToolContext, ToolExecutionResult, AgentRecorder, } from './core';
+export type { ConversationStore, MemoryConfig } from './adapters/memory/types';
+export type { RedisLike, RedisStoreOptions, DynamoLike, DynamoStoreOptions, PostgresLike, PostgresStoreOptions } from './adapters/memory/stores';
+export type { ResponseFormat, LLMStreamChunk } from './types';
+export { systemMessage, userMessage, assistantMessage, toolResultMessage, textBlock, imageBlock, base64Image, urlImage, } from './types';
+export { LLMError } from './types';
+export type { Message, ToolCall, LLMProvider, LLMResponse, LLMCallOptions, TokenUsage, LLMToolDescription, ToolDefinition, ToolHandler, ToolResult, AgentResult, AgentRunOptions, RunnerLike, RetrieverProvider, RetrievalChunk, RAGResult, LLMErrorCode, } from './types';
+export type { AgentStreamEvent, AgentStreamEventHandler } from './streaming';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACL,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,cAAc,GACzB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,YAAY,EACV,cAAc,EAAE,aAAa,EAC7B,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAC9C,aAAa,GACd,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC/E,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACjJ,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9D,OAAO,EACL,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAC/D,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,GAC7C,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,YAAY,EACV,OAAO,EAAE,QAAQ,EACjB,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,kBAAkB,EACxE,cAAc,EAAE,WAAW,EAAE,UAAU,EACvC,WAAW,EAAE,eAAe,EAAE,UAAU,EACxC,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAC5C,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapSDKError = exports.classifyStatusCode = exports.LLMError = exports.ADAPTER_PATHS = exports.hasToolCalls = exports.toolResultMessage = exports.assistantMessage = exports.userMessage = exports.systemMessage = exports.getToolUseBlocks = exports.hasToolUseBlocks = exports.contentLength = exports.getTextContent = exports.blockToToolCall = exports.toolCallToBlock = exports.toolResultBlock = exports.toolUseBlock = exports.urlImage = exports.base64Image = exports.imageBlock = exports.textBlock = void 0;
+var content_1 = require("./content");
+Object.defineProperty(exports, "textBlock", { enumerable: true, get: function () { return content_1.textBlock; } });
+Object.defineProperty(exports, "imageBlock", { enumerable: true, get: function () { return content_1.imageBlock; } });
+Object.defineProperty(exports, "base64Image", { enumerable: true, get: function () { return content_1.base64Image; } });
+Object.defineProperty(exports, "urlImage", { enumerable: true, get: function () { return content_1.urlImage; } });
+Object.defineProperty(exports, "toolUseBlock", { enumerable: true, get: function () { return content_1.toolUseBlock; } });
+Object.defineProperty(exports, "toolResultBlock", { enumerable: true, get: function () { return content_1.toolResultBlock; } });
+Object.defineProperty(exports, "toolCallToBlock", { enumerable: true, get: function () { return content_1.toolCallToBlock; } });
+Object.defineProperty(exports, "blockToToolCall", { enumerable: true, get: function () { return content_1.blockToToolCall; } });
+Object.defineProperty(exports, "getTextContent", { enumerable: true, get: function () { return content_1.getTextContent; } });
+Object.defineProperty(exports, "contentLength", { enumerable: true, get: function () { return content_1.contentLength; } });
+Object.defineProperty(exports, "hasToolUseBlocks", { enumerable: true, get: function () { return content_1.hasToolUseBlocks; } });
+Object.defineProperty(exports, "getToolUseBlocks", { enumerable: true, get: function () { return content_1.getToolUseBlocks; } });
+var messages_1 = require("./messages");
+Object.defineProperty(exports, "systemMessage", { enumerable: true, get: function () { return messages_1.systemMessage; } });
+Object.defineProperty(exports, "userMessage", { enumerable: true, get: function () { return messages_1.userMessage; } });
+Object.defineProperty(exports, "assistantMessage", { enumerable: true, get: function () { return messages_1.assistantMessage; } });
+Object.defineProperty(exports, "toolResultMessage", { enumerable: true, get: function () { return messages_1.toolResultMessage; } });
+Object.defineProperty(exports, "hasToolCalls", { enumerable: true, get: function () { return messages_1.hasToolCalls; } });
+var adapter_1 = require("./adapter");
+Object.defineProperty(exports, "ADAPTER_PATHS", { enumerable: true, get: function () { return adapter_1.ADAPTER_PATHS; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "LLMError", { enumerable: true, get: function () { return errors_1.LLMError; } });
+Object.defineProperty(exports, "classifyStatusCode", { enumerable: true, get: function () { return errors_1.classifyStatusCode; } });
+Object.defineProperty(exports, "wrapSDKError", { enumerable: true, get: function () { return errors_1.wrapSDKError; } });
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;AAcA,qCAamB;AAZjB,oGAAA,SAAS,OAAA;AACT,qGAAA,UAAU,OAAA;AACV,sGAAA,WAAW,OAAA;AACX,mGAAA,QAAQ,OAAA;AACR,uGAAA,YAAY,OAAA;AACZ,0GAAA,eAAe,OAAA;AACf,0GAAA,eAAe,OAAA;AACf,0GAAA,eAAe,OAAA;AACf,yGAAA,cAAc,OAAA;AACd,wGAAA,aAAa,OAAA;AACb,2GAAA,gBAAgB,OAAA;AAChB,2GAAA,gBAAgB,OAAA;AAYlB,uCAMoB;AALlB,yGAAA,aAAa,OAAA;AACb,uGAAA,WAAW,OAAA;AACX,4GAAA,gBAAgB,OAAA;AAChB,6GAAA,iBAAiB,OAAA;AACjB,wGAAA,YAAY,OAAA;AAsBd,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AAetB,mCAAsE;AAA7D,kGAAA,QAAQ,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAAE,sGAAA,YAAY,OAAA"}

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

@@ -0,0 +1,24 @@
+/**
+ * agentfootprint/instructions — Make agents smart with conditional context injection.
+ *
+ * Define rules that inject into system prompt, tools, and tool-result recency window
+ * based on accumulated Decision Scope state.
+ *
+ * @example
+ * ```typescript
+ * import { defineInstruction, AgentPattern } from 'agentfootprint/instructions';
+ *
+ * const refund = defineInstruction({
+ *   id: 'refund-handling',
+ *   activeWhen: (d) => d.orderStatus === 'denied',
+ *   prompt: 'Be empathetic.',
+ *   tools: [processRefund],
+ * });
+ * ```
+ */
+export { defineInstruction, follow, quickBind } from './lib/instructions';
+export type { AgentInstruction, LLMInstruction, FollowUpBinding, InstructionContext, InstructionOverride, InstructedToolDefinition, } from './lib/instructions';
+export { AgentPattern } from './lib/loop';
+export { InstructionRecorder } from './lib/instructions';
+export type { InstructionSummary } from './lib/instructions';
+//# sourceMappingURL=instructions.barrel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.barrel.d.ts","sourceRoot":"","sources":["../../src/instructions.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC1E,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,29 @@
+/**
+ * CallLLM stage — sends messages + tools to the LLM provider.
+ *
+ * Reads from scope:
+ *   - messages (set by Messages slot or prior stages)
+ *   - toolDescriptions (set by Tools slot)
+ *
+ * Writes to scope:
+ *   - adapterResult (discriminated union: 'final' | 'tools' | 'error')
+ *   - adapterRawResponse (raw LLM response for recorders)
+ *   - llmCall (narrative summary of the LLM call)
+ *
+ * Emits AgentStreamEvents:
+ *   - llm_start { iteration }
+ *   - llm_end { iteration, toolCallCount, content, model, latencyMs }
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentLoopState } from '../../scope/types';
+import type { LLMProvider, ResponseFormat } from '../../types';
+import type { AgentStreamEventHandler } from '../../streaming';
+export interface CallLLMStageOptions {
+    onStreamEvent?: AgentStreamEventHandler;
+    responseFormat?: ResponseFormat;
+}
+/**
+ * Create the CallLLM stage function.
+ */
+export declare function createCallLLMStage(provider: LLMProvider, optionsOrHandler?: CallLLMStageOptions | AgentStreamEventHandler): (scope: TypedScope<AgentLoopState>) => Promise<void>;
+//# sourceMappingURL=callLLMStage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"callLLMStage.d.ts","sourceRoot":"","sources":["../../../../src/lib/call/callLLMStage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAkB,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAG/D,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,uBAAuB,CAAC;IACxC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,WAAW,EACrB,gBAAgB,CAAC,EAAE,mBAAmB,GAAG,uBAAuB,WAa3C,WAAW,cAAc,CAAC,mBAuChD"}

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

@@ -0,0 +1,35 @@
+/**
+ * HandleResponse stage — finalize the turn when no tool calls remain.
+ *
+ * @deprecated Use the RouteResponse decider pattern in buildAgentLoop instead.
+ * The loop now uses addDeciderFunction('RouteResponse') with 'tool-calls' and
+ * 'final' branches. The Finalize branch (createFinalizeStage) replaces this stage.
+ * Kept for backward compatibility with custom chart builders.
+ *
+ * Reads from scope:
+ *   - parsedResponse (set by ParseResponse)
+ *   - loopCount, maxIterations
+ *   - messages
+ *
+ * Writes to scope:
+ *   - result (final answer text)
+ *   - memory_shouldCommit (when useCommitFlag)
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentLoopState } from '../../scope/types';
+export interface HandleResponseOptions {
+    /**
+     * When true, set `memory_shouldCommit=true` instead of calling $break() directly.
+     * Use when CommitMemory stage is present — it will call $break() after saving.
+     */
+    readonly useCommitFlag?: boolean;
+}
+/**
+ * Create the HandleResponse stage function.
+ *
+ * Tool execution is handled by the upstream sf-execute-tools subflow.
+ * HandleResponse only finalizes: if no tool calls remain, extract result + break.
+ * If tools were executed (loopCount incremented by subflow), loop continues.
+ */
+export declare function createHandleResponseStage(options: HandleResponseOptions): (scope: TypedScope<AgentLoopState>) => void;
+//# sourceMappingURL=handleResponseStage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handleResponseStage.d.ts","sourceRoot":"","sources":["../../../../src/lib/call/handleResponseStage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,qBAAqB,WAEvD,WAAW,cAAc,CAAC,UAqB1C"}

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

@@ -0,0 +1,64 @@
+/**
+ * Shared helpers for call module stages.
+ */
+import type { LLMResponse, AdapterResult, ToolCall, Message } from '../../types';
+import type { ToolRegistry } from '../../tools';
+import type { ToolProvider } from '../../core';
+import type { LLMInstruction, InstructionContext, InstructionTemplate } from '../instructions';
+import type { ResolvedInstruction } from '../instructions';
+import type { AgentStreamEventHandler } from '../../streaming';
+/**
+ * Normalize an LLMResponse into an AdapterResult discriminated union.
+ */
+export declare function normalizeAdapterResponse(response: LLMResponse): AdapterResult;
+/**
+ * Optional instruction processing config for executeToolCalls.
+ * When provided, instructions are evaluated after each tool call
+ * and injected into the tool result message content.
+ */
+/** Function that mutates the Decision Scope after a tool result. */
+export type DecideFn = (decision: Record<string, unknown>, ctx: InstructionContext) => void;
+export interface InstructionConfig {
+    /** Build-time instructions keyed by tool ID. */
+    readonly instructionsByToolId: Map<string, readonly LLMInstruction[]>;
+    /** Optional custom template for formatting. */
+    readonly template?: InstructionTemplate;
+    /** Callback when instructions fire (for InstructionRecorder). */
+    readonly onInstructionsFired?: (toolId: string, fired: ResolvedInstruction[]) => void;
+    /**
+     * decide() functions keyed by instruction rule ID.
+     * Built at loop construction time from AgentInstruction.onToolResult rules + per-tool instructions.
+     * Functions can't travel through scope (stripped on write), so they're captured by closure.
+     */
+    readonly decideFunctions?: ReadonlyMap<string, DecideFn>;
+    /**
+     * Agent-level response rules captured at build time.
+     * These are the onToolResult rules from matched AgentInstructions.
+     * Captured by closure because functions (`when`, `decide`, `followUp.params`)
+     * are stripped when values pass through footprintjs scope.
+     */
+    readonly agentResponseRules?: readonly LLMInstruction[];
+    /** Stream event handler for tool lifecycle events (tool_start, tool_end). */
+    readonly onStreamEvent?: AgentStreamEventHandler;
+}
+/**
+ * Execute tool calls and append results to conversation messages.
+ *
+ * Tries ToolProvider.execute() first (for remote tools like MCP/A2A),
+ * falls back to ToolRegistry.get().handler (for local ToolDefinitions).
+ *
+ * When `instructionConfig` is provided, evaluates LLM instructions after
+ * each tool call and appends matched instruction text to the tool result
+ * message — landing in the LLM's recency window.
+ */
+/** Result of executeToolCalls — messages + optional ask_human pause info. */
+export interface ToolCallsResult {
+    messages: Message[];
+    /** When set, one of the tools was ask_human — pause with this data. */
+    askHumanPause?: {
+        question: string;
+        toolCallId: string;
+    };
+}
+export declare function executeToolCalls(toolCalls: ToolCall[], registry: ToolRegistry, messages: Message[], toolProvider?: ToolProvider, signal?: AbortSignal, instructionConfig?: InstructionConfig, decision?: Record<string, unknown>): Promise<ToolCallsResult>;
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/lib/call/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAmB,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAChH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,WAAW,GAAG,aAAa,CAgB7E;AAED;;;;GAIG;AACH,oEAAoE;AACpE,MAAM,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAE5F,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,QAAQ,CAAC,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC,CAAC;IACtE,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,IAAI,CAAC;IACtF;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzD;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACxD,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;;;;;;GASG;AACH,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,uEAAuE;IACvE,aAAa,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,QAAQ,EAAE,EACrB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,OAAO,EAAE,EACnB,YAAY,CAAC,EAAE,YAAY,EAC3B,MAAM,CAAC,EAAE,WAAW,EACpB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,eAAe,CAAC,CAuJ1B"}