agentfootprint 1.23.0 → 2.1.0

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

@@ -1,168 +0,0 @@
-/**
- * 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;
-    /**
-     * Optional decision-scope update surfaced by the inner tool via
-     * `ToolResult.decisionUpdate`. Built-in ToolProviders (staticTools,
-     * gatedTools, compositeTools, agentAsTool) pass this through from
-     * the inner handler; the tool-execution stage merges it into the
-     * agent's decision scope. Parallel with `ToolResult.decisionUpdate`.
-     */
-    readonly decisionUpdate?: Record<string, unknown>;
-}
-//# sourceMappingURL=providers.d.ts.map

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

@@ -1 +0,0 @@
-{"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,CACL,OAAO,EAAE,OAAO,EAAE,EAClB,OAAO,EAAE,cAAc,GACtB,YAAY,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,CACL,OAAO,EAAE,WAAW,GACnB,YAAY,CAAC,kBAAkB,EAAE,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;IACpF,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;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnD"}

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

@@ -1,70 +0,0 @@
-/**
- * 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'];
-    /** Unique per-execution-step identifier from footprintjs traversal. */
-    readonly runtimeStageId: string;
-    /** System prompt the LLM received (for evaluation context). */
-    readonly systemPrompt?: string;
-    /** Tool descriptions sent to the LLM (for tool selection evaluation). */
-    readonly toolDescriptions?: ReadonlyArray<{
-        name: string;
-        description: string;
-    }>;
-    /** Messages sent to the LLM (for context evaluation). */
-    readonly messages?: ReadonlyArray<{
-        role: string;
-        content: unknown;
-    }>;
-}
-export interface ToolCallEvent {
-    readonly toolName: string;
-    readonly args: Record<string, unknown>;
-    readonly result: ToolExecutionResult;
-    readonly latencyMs: number;
-    /** Unique per-execution-step identifier from footprintjs traversal. */
-    readonly runtimeStageId: string;
-}
-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

@@ -1 +0,0 @@
-{"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;IACpD,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjF,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACvE;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;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;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

@@ -1,80 +0,0 @@
-"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

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

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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"version":3,"file":"agentLoop.d.ts","sourceRoot":"","sources":["../../../src/executor/agentLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,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,CAqI1B"}

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

@@ -1,6 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,25 +0,0 @@
-/**
- * agentfootprint/explain — Understand agent decisions.
- *
- * ExplainRecorder collects grounding data during traversal — sources (tool results),
- * claims (LLM outputs), and decisions (tool calls). No post-processing.
- *
- * @example
- * ```typescript
- * import { ExplainRecorder } from 'agentfootprint/explain';
- *
- * const explain = new ExplainRecorder();
- * agent.recorder(explain);
- * await agent.run('Check order');
- *
- * const report = explain.explain();
- * console.log(report.sources);   // what tools returned
- * console.log(report.claims);    // what the LLM said
- * console.log(report.decisions); // what the LLM chose to do
- * ```
- */
-export { createAgentRenderer } from './lib/narrative';
-export type { AgentRendererOptions } from './lib/narrative';
-export { ExplainRecorder } from './recorders/ExplainRecorder';
-export type { ToolSource, LLMClaim, AgentDecision, LLMContext, EvalIteration, Explanation, } from './recorders/ExplainRecorder';
-//# sourceMappingURL=explain.barrel.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"explain.barrel.d.ts","sourceRoot":"","sources":["../../src/explain.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,YAAY,EACV,UAAU,EACV,QAAQ,EACR,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,GACZ,MAAM,6BAA6B,CAAC"}

package/dist/types/exportTrace.d.ts

@@ -1,84 +0,0 @@
-/**
- * exportTrace — capture an agent run's full state into a portable JSON
- * blob for sharing externally (paste into a viewer, ship to support, log
- * for debugging, store in a database).
- *
- * Defaults to **redacted** output: snapshots come from
- * `getSnapshot({ redact: true })` (footprintjs 4.14+), so values for keys
- * listed in `RedactionPolicy.keys` / matching `patterns` arrive as
- * `'REDACTED'` instead of raw. The commit log is already redacted at
- * write-time. Combined with `emitPatterns` (also redacted at origin), the
- * exported trace is safe to share when the caller has configured a policy.
- *
- * **Without a redaction policy, this helper still emits a trace — but
- * `sharedState` will contain raw values.** Configure `setRedactionPolicy`
- * before calling this for any externally shared trace.
- *
- * @example
- * ```ts
- * import { Agent, exportTrace, anthropic } from 'agentfootprint';
- *
- * const agent = Agent.create({ provider: anthropic('claude-sonnet-4') })
- *   .system('You are a customer support agent.')
- *   .build();
- *
- * await agent.run('My credit card 4242-4242-4242-4242 was declined');
- *
- * // Configure policy on the underlying executor for full safety
- * // (concept-level recorder API for this is a follow-up).
- * const trace = exportTrace(agent);
- * console.log(JSON.stringify(trace, null, 2));
- * // → paste into the playground viewer, send to support, etc.
- * ```
- */
-import type { RunnerLike } from './types';
-/**
- * Schema-versioned, JSON-safe representation of a single agent run.
- *
- * Pin the consumer side to `schemaVersion: 1`. Any breaking change to the
- * shape ships as a new schema version with a clear migration note.
- */
-export interface AgentfootprintTrace {
-    /** Schema version. Always `1` in this release. */
-    readonly schemaVersion: 1;
-    /** ISO 8601 timestamp the trace was exported. */
-    readonly exportedAt: string;
-    /** True when `sharedState` came from the redacted mirror. */
-    readonly redacted: boolean;
-    /**
-     * Full execution snapshot — `sharedState`, `executionTree`, `commitLog`,
-     * `subflowResults`, and any recorder snapshots. The exact shape matches
-     * `footprintjs.RuntimeSnapshot`. May be omitted if the runner did not
-     * expose `getSnapshot()`.
-     */
-    readonly snapshot?: unknown;
-    /**
-     * Structured per-step narrative entries. Use this to render a timeline
-     * UI; each entry has a `type`, `text`, `depth`, and `runtimeStageId`.
-     * Render flat strings locally via `entries.map(e => e.text)` when needed.
-     */
-    readonly narrativeEntries?: unknown[];
-    /**
-     * Flowchart spec — node + edge metadata for rendering the topology of
-     * what ran. Stable across runs of the same agent shape.
-     */
-    readonly spec?: unknown;
-}
-export interface ExportTraceOptions {
-    /**
-     * When `true` (the default), request `getSnapshot({ redact: true })` from
-     * the runner so `sharedState` is scrubbed via the redacted-mirror feature.
-     * Set to `false` only for in-process debugging where the raw view is
-     * needed and the trace will not leave the local machine.
-     */
-    readonly redact?: boolean;
-}
-/**
- * Capture a full execution trace from any runner exposing the standard
- * introspection surface (`getSnapshot`, `getNarrative*`, `getSpec`).
- * All of those methods are optional — missing methods skip the field.
- *
- * Always returns a JSON-stringify-safe object.
- */
-export declare function exportTrace(runner: RunnerLike, options?: ExportTraceOptions): AgentfootprintTrace;
-//# sourceMappingURL=exportTrace.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"exportTrace.d.ts","sourceRoot":"","sources":["../../src/exportTrace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAaD,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,mBAAmB,CA6BjG"}

package/dist/types/index.js

@@ -1,29 +0,0 @@
-"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

@@ -1 +0,0 @@
-{"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;AA4Bd,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

@@ -1,24 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,33 +0,0 @@
-/**
- * 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 on the footprintjs emit channel:
- *   - `agentfootprint.llm.request` — outgoing LLM shape (messages/tools/etc.)
- *   - `agentfootprint.llm.response` — raw adapter response
- *   - `agentfootprint.stream.llm_start`  (full AgentStreamEvent as payload)
- *   - `agentfootprint.stream.llm_end`    (full AgentStreamEvent as payload)
- *
- * Stream events route via emit so there's zero closure capture of
- * per-run callbacks. `AgentRunner` attaches a `StreamEventRecorder`
- * that translates these emits to the caller's `{ onEvent }` callback.
- */
-import type { TypedScope } from 'footprintjs';
-import type { AgentLoopState } from '../../scope/types';
-import type { LLMProvider, ResponseFormat } from '../../types';
-export interface CallLLMStageOptions {
-    responseFormat?: ResponseFormat;
-}
-/**
- * Create the CallLLM stage function.
- */
-export declare function createCallLLMStage(provider: LLMProvider, options?: CallLLMStageOptions): (scope: TypedScope<AgentLoopState>) => Promise<void>;
-//# sourceMappingURL=callLLMStage.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"callLLMStage.d.ts","sourceRoot":"","sources":["../../../../src/lib/call/callLLMStage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;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;AAI/E,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,mBAAmB,WAMhE,WAAW,cAAc,CAAC,mBA8EhD"}