agentfootprint 1.23.0 → 2.0.1

package/dist/esm/types/content.js

@@ -1,82 +0,0 @@
-/**
- * Multi-modal content blocks for LLM messages.
- * Provider-agnostic — adapters translate to/from provider formats (Anthropic, OpenAI, etc.).
- *
- * Design: discriminated union on `type` field, like Anthropic's API.
- * Every message's `content` is `string | ContentBlock[]` — string for backward compat,
- * ContentBlock[] for multi-modal (images, tool use, structured results).
- */
-// ── Factory Functions ───────────────────────────────────────
-export function textBlock(text) {
-    return { type: 'text', text };
-}
-export function imageBlock(source) {
-    return { type: 'image', source };
-}
-export function base64Image(mediaType, data) {
-    return { type: 'image', source: { type: 'base64', mediaType, data } };
-}
-export function urlImage(url) {
-    return { type: 'image', source: { type: 'url', url } };
-}
-export function toolUseBlock(id, name, input) {
-    return { type: 'tool_use', id, name, input };
-}
-export function toolResultBlock(toolUseId, content, isError) {
-    return { type: 'tool_result', toolUseId, content, isError };
-}
-// ── ToolCall ↔ ToolUseBlock Conversion ──────────────────────
-/**
- * Convert a legacy ToolCall (from AssistantMessage.toolCalls) to a ToolUseBlock.
- * Bridges the two representations: ToolCall uses `arguments`, ToolUseBlock uses `input`.
- */
-export function toolCallToBlock(call) {
-    return { type: 'tool_use', id: call.id, name: call.name, input: call.arguments };
-}
-/**
- * Convert a ToolUseBlock to a legacy ToolCall format.
- * Bridges the two representations: ToolUseBlock uses `input`, ToolCall uses `arguments`.
- */
-export function blockToToolCall(block) {
-    return { id: block.id, name: block.name, arguments: block.input };
-}
-// ── Content Helpers ─────────────────────────────────────────
-/**
- * Extract text from message content, regardless of form.
- * - string → returned as-is
- * - ContentBlock[] → concatenates all TextBlock.text values
- *
- * Use this instead of `msg.content.length` or string operations on content.
- */
-export function getTextContent(content) {
-    if (typeof content === 'string')
-        return content;
-    return content
-        .filter((block) => block.type === 'text')
-        .map((block) => block.text)
-        .join('');
-}
-/**
- * Get the character length of message content (for budget calculations).
- * Handles both string and ContentBlock[] forms.
- */
-export function contentLength(content) {
-    return getTextContent(content).length;
-}
-/**
- * Check if content contains any tool use blocks.
- */
-export function hasToolUseBlocks(content) {
-    if (typeof content === 'string')
-        return false;
-    return content.some((block) => block.type === 'tool_use');
-}
-/**
- * Extract tool use blocks from content.
- */
-export function getToolUseBlocks(content) {
-    if (typeof content === 'string')
-        return [];
-    return content.filter((block) => block.type === 'tool_use');
-}
-//# sourceMappingURL=content.js.map

package/dist/esm/types/content.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"content.js","sourceRoot":"","sources":["../../../src/types/content.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuEH,+DAA+D;AAE/D,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAmB;IAC5C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,IAAY;IACzD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,EAAU,EACV,IAAY,EACZ,KAA8B;IAE9B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,SAAiB,EACjB,OAAgC,EAChC,OAAiB;IAEjB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9D,CAAC;AAED,+DAA+D;AAE/D;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAI/B;IACC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;AACnF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB;IAKjD,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;AACpE,CAAC;AAED,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAuB;IACpD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,KAAK,EAAsB,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC;SAC5D,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAuB;IACnD,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAuB;IACtD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9C,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAuB;IACtD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAC3C,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAyB,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AACrF,CAAC"}

package/dist/esm/types/errors.js

@@ -1,74 +0,0 @@
-/**
- * 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.
- */
-export 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);
-    }
-}
-function isRetryable(code) {
-    return code === 'rate_limit' || code === 'server' || code === 'timeout' || code === 'network';
-}
-/** Classify an HTTP status code into an LLMErrorCode. */
-export 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';
-}
-/** Wrap an unknown SDK error into an LLMError. */
-export 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 });
-}
-//# sourceMappingURL=errors.js.map

package/dist/esm/types/errors.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,MAAM,OAAO,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;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,MAAM,UAAU,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;AAED,kDAAkD;AAClD,MAAM,UAAU,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"}

package/dist/esm/types/index.js

@@ -1,5 +0,0 @@
-export { textBlock, imageBlock, base64Image, urlImage, toolUseBlock, toolResultBlock, toolCallToBlock, blockToToolCall, getTextContent, contentLength, hasToolUseBlocks, getToolUseBlocks, } from './content';
-export { systemMessage, userMessage, assistantMessage, toolResultMessage, hasToolCalls, } from './messages';
-export { ADAPTER_PATHS } from './adapter';
-export { LLMError, classifyStatusCode, wrapSDKError } from './errors';
-//# sourceMappingURL=index.js.map

package/dist/esm/types/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAWnB,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,YAAY,CAAC;AA2BpB,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAe1C,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/esm/types/llm.js

@@ -1,6 +0,0 @@
-/**
- * Provider-agnostic LLM interface.
- * No SDK dependency — consumers implement for their provider.
- */
-export {};
-//# sourceMappingURL=llm.js.map

package/dist/esm/types/llm.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../../src/types/llm.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/esm/types/messages.js

@@ -1,24 +0,0 @@
-/**
- * Message types for LLM conversation.
- * Provider-agnostic — adapters translate to/from provider formats.
- *
- * Content can be a plain string (backward compat) or ContentBlock[]
- * for multi-modal messages (images, structured tool results, etc.).
- */
-// ── Helpers ──────────────────────────────────────────────────
-export function systemMessage(content) {
-    return { role: 'system', content };
-}
-export function userMessage(content) {
-    return { role: 'user', content };
-}
-export function assistantMessage(content, toolCalls) {
-    return { role: 'assistant', content, toolCalls };
-}
-export function toolResultMessage(content, toolCallId) {
-    return { role: 'tool', content, toolCallId };
-}
-export function hasToolCalls(msg) {
-    return msg.role === 'assistant' && Array.isArray(msg.toolCalls) && msg.toolCalls.length > 0;
-}
-//# sourceMappingURL=messages.js.map

package/dist/esm/types/messages.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/types/messages.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkCH,gEAAgE;AAEhE,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAuB;IACjD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,OAAuB,EACvB,SAAsB;IAEtB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAuB,EAAE,UAAkB;IAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9F,CAAC"}

package/dist/esm/types/multiAgent.js

@@ -1,5 +0,0 @@
-/**
- * Multi-Agent types — duck-typed interfaces for composing runners into pipelines.
- */
-export {};
-//# sourceMappingURL=multiAgent.js.map

package/dist/esm/types/multiAgent.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"multiAgent.js","sourceRoot":"","sources":["../../../src/types/multiAgent.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/esm/types/retriever.js

@@ -1,6 +0,0 @@
-/**
- * Retriever types — the contract for retrieval providers.
- * Users implement RetrieverProvider for their vector store (Pinecone, Chroma, pg_vector, etc.).
- */
-export {};
-//# sourceMappingURL=retriever.js.map

package/dist/esm/types/retriever.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"retriever.js","sourceRoot":"","sources":["../../../src/types/retriever.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/esm/types/tools.js

@@ -1,5 +0,0 @@
-/**
- * Tool definitions for agent function calling.
- */
-export {};
-//# sourceMappingURL=tools.js.map

package/dist/esm/types/tools.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/executor/agentLoop.js

@@ -1,158 +0,0 @@
-"use strict";
-/**
- * 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 });
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.agentLoop = void 0;
-const trace_1 = require("footprintjs/trace");
-const messages_1 = require("../types/messages");
-const content_1 = require("../types/content");
-// ── Engine ───────────────────────────────────────────────────
-async function agentLoop(config, message, options = {}) {
-    const { promptProvider, messageStrategy, toolProvider, llmProvider, maxIterations, recorders } = config;
-    const signal = options.signal;
-    const turnNumber = options.turnNumber ?? 0;
-    const history = [...(options.history ?? [])];
-    // Add user message
-    history.push((0, messages_1.userMessage)(message));
-    // Notify recorders: turn start
-    const startEvent = { turnNumber, message };
-    dispatchRecorderEvent(recorders, 'onTurnStart', startEvent);
-    try {
-        // 1. Resolve system prompt
-        const promptCtx = { message, turnNumber, history, signal };
-        const systemPrompt = await promptProvider.resolve(promptCtx);
-        let loopIteration = 0;
-        const executionCounter = (0, trace_1.createExecutionCounter)();
-        let finalContent = '';
-        while (loopIteration < maxIterations) {
-            checkAborted(signal);
-            // 2. Prepare messages
-            const messageCtx = { message, turnNumber, loopIteration, signal };
-            const messageDecision = await messageStrategy.prepare(history, messageCtx);
-            const preparedMessages = messageDecision.value;
-            // 3. Call LLM
-            const toolDecision = await toolProvider.resolve({
-                message,
-                turnNumber,
-                loopIteration,
-                messages: preparedMessages,
-                signal,
-            });
-            const toolDescriptions = toolDecision.value;
-            const llmStart = Date.now();
-            const llmResponse = await llmProvider.chat(preparedMessages, {
-                tools: toolDescriptions.length > 0 ? toolDescriptions : undefined,
-                signal,
-                ...(systemPrompt ? {} : {}),
-            });
-            const llmLatency = Date.now() - llmStart;
-            // Notify recorders: LLM call
-            const llmEvent = {
-                model: undefined,
-                usage: llmResponse.usage,
-                latencyMs: llmLatency,
-                turnNumber,
-                loopIteration,
-                finishReason: llmResponse.finishReason,
-                runtimeStageId: (0, trace_1.buildRuntimeStageId)('call-llm', executionCounter.value++),
-            };
-            dispatchRecorderEvent(recorders, 'onLLMCall', llmEvent);
-            loopIteration++;
-            // Add assistant message to history
-            const assistantContent = (0, content_1.getTextContent)(llmResponse.content);
-            const assistantMsg = (0, messages_1.assistantMessage)(assistantContent, llmResponse.toolCalls);
-            history.push(assistantMsg);
-            // 4. Check for tool calls
-            if ((0, messages_1.hasToolCalls)(assistantMsg) && assistantMsg.toolCalls.length > 0) {
-                // Execute each tool call
-                for (const toolCall of assistantMsg.toolCalls) {
-                    checkAborted(signal);
-                    const toolStart = Date.now();
-                    let toolResult;
-                    if (toolProvider.execute) {
-                        toolResult = await toolProvider.execute(toolCall, signal);
-                    }
-                    else {
-                        toolResult = { content: `No executor for tool: ${toolCall.name}`, error: true };
-                    }
-                    const toolLatency = Date.now() - toolStart;
-                    // Notify recorders: tool call
-                    const toolEvent = {
-                        toolName: toolCall.name,
-                        args: toolCall.arguments,
-                        result: toolResult,
-                        latencyMs: toolLatency,
-                        runtimeStageId: (0, trace_1.buildRuntimeStageId)('execute-tools', executionCounter.value++),
-                    };
-                    dispatchRecorderEvent(recorders, 'onToolCall', toolEvent);
-                    // Add tool result to history
-                    history.push((0, messages_1.toolResultMessage)(toolResult.content, toolCall.id));
-                }
-                // Continue loop — LLM needs to process tool results
-                continue;
-            }
-            // 5. Final response — no tool calls
-            finalContent = assistantContent;
-            break;
-        }
-        // Notify recorders: turn complete
-        const completeEvent = {
-            turnNumber,
-            messageCount: history.length,
-            totalLoopIterations: loopIteration,
-            content: finalContent,
-        };
-        dispatchRecorderEvent(recorders, 'onTurnComplete', completeEvent);
-        return {
-            content: finalContent,
-            messages: history,
-            loopIterations: loopIteration,
-        };
-    }
-    catch (err) {
-        // Notify recorders: error
-        const errorEvent = {
-            phase: 'llm',
-            error: err,
-            turnNumber,
-        };
-        dispatchRecorderEvent(recorders, 'onError', errorEvent);
-        throw err;
-    }
-}
-exports.agentLoop = agentLoop;
-// ── Helpers ──────────────────────────────────────────────────
-function checkAborted(signal) {
-    if (signal?.aborted) {
-        throw signal.reason ?? new Error('Aborted');
-    }
-}
-function dispatchRecorderEvent(recorders, hook, event) {
-    for (const recorder of recorders) {
-        try {
-            const fn = recorder[hook];
-            if (typeof fn === 'function') {
-                fn.call(recorder, event);
-            }
-        }
-        catch {
-            // Error isolation
-        }
-    }
-}
-//# sourceMappingURL=agentLoop.js.map

package/dist/executor/agentLoop.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"agentLoop.js","sourceRoot":"","sources":["../../src/executor/agentLoop.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAEH,6CAAgF;AAWhF,gDAAmG;AACnG,8CAAkD;AAsBlD,gEAAgE;AAEzD,KAAK,UAAU,SAAS,CAC7B,MAAuB,EACvB,OAAe,EACf,UAA4B,EAAE;IAE9B,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,GAC5F,MAAM,CAAC;IAET,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAc,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;IAExD,mBAAmB;IACnB,OAAO,CAAC,IAAI,CAAC,IAAA,sBAAW,EAAC,OAAO,CAAC,CAAC,CAAC;IAEnC,+BAA+B;IAC/B,MAAM,UAAU,GAAmB,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IAC3D,qBAAqB,CAAC,SAAS,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;IAE5D,IAAI,CAAC;QACH,2BAA2B;QAC3B,MAAM,SAAS,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAC3D,MAAM,YAAY,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAE7D,IAAI,aAAa,GAAG,CAAC,CAAC;QACtB,MAAM,gBAAgB,GAAG,IAAA,8BAAsB,GAAE,CAAC;QAClD,IAAI,YAAY,GAAG,EAAE,CAAC;QAEtB,OAAO,aAAa,GAAG,aAAa,EAAE,CAAC;YACrC,YAAY,CAAC,MAAM,CAAC,CAAC;YAErB,sBAAsB;YACtB,MAAM,UAAU,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;YAClE,MAAM,eAAe,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAC3E,MAAM,gBAAgB,GAAG,eAAe,CAAC,KAAK,CAAC;YAE/C,cAAc;YACd,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC;gBAC9C,OAAO;gBACP,UAAU;gBACV,aAAa;gBACb,QAAQ,EAAE,gBAAgB;gBAC1B,MAAM;aACP,CAAC,CAAC;YACH,MAAM,gBAAgB,GAAG,YAAY,CAAC,KAAK,CAAC;YAE5C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC5B,MAAM,WAAW,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,gBAAgB,EAAE;gBAC3D,KAAK,EAAE,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;gBACjE,MAAM;gBACN,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC5B,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC;YAEzC,6BAA6B;YAC7B,MAAM,QAAQ,GAAiB;gBAC7B,KAAK,EAAE,SAAS;gBAChB,KAAK,EAAE,WAAW,CAAC,KAAK;gBACxB,SAAS,EAAE,UAAU;gBACrB,UAAU;gBACV,aAAa;gBACb,YAAY,EAAE,WAAW,CAAC,YAAY;gBACtC,cAAc,EAAE,IAAA,2BAAmB,EAAC,UAAU,EAAE,gBAAgB,CAAC,KAAK,EAAE,CAAC;aAC1E,CAAC;YACF,qBAAqB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;YAExD,aAAa,EAAE,CAAC;YAEhB,mCAAmC;YACnC,MAAM,gBAAgB,GAAG,IAAA,wBAAc,EAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAC7D,MAAM,YAAY,GAAG,IAAA,2BAAgB,EAAC,gBAAgB,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;YAC/E,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAE3B,0BAA0B;YAC1B,IAAI,IAAA,uBAAY,EAAC,YAAY,CAAC,IAAI,YAAY,CAAC,SAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrE,yBAAyB;gBACzB,KAAK,MAAM,QAAQ,IAAI,YAAY,CAAC,SAAU,EAAE,CAAC;oBAC/C,YAAY,CAAC,MAAM,CAAC,CAAC;oBAErB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;oBAC7B,IAAI,UAAU,CAAC;oBAEf,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC;wBACzB,UAAU,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;oBAC5D,CAAC;yBAAM,CAAC;wBACN,UAAU,GAAG,EAAE,OAAO,EAAE,yBAAyB,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;oBAClF,CAAC;oBAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;oBAE3C,8BAA8B;oBAC9B,MAAM,SAAS,GAAkB;wBAC/B,QAAQ,EAAE,QAAQ,CAAC,IAAI;wBACvB,IAAI,EAAE,QAAQ,CAAC,SAAS;wBACxB,MAAM,EAAE,UAAU;wBAClB,SAAS,EAAE,WAAW;wBACtB,cAAc,EAAE,IAAA,2BAAmB,EAAC,eAAe,EAAE,gBAAgB,CAAC,KAAK,EAAE,CAAC;qBAC/E,CAAC;oBACF,qBAAqB,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;oBAE1D,6BAA6B;oBAC7B,OAAO,CAAC,IAAI,CAAC,IAAA,4BAAiB,EAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;gBACnE,CAAC;gBAED,oDAAoD;gBACpD,SAAS;YACX,CAAC;YAED,oCAAoC;YACpC,YAAY,GAAG,gBAAgB,CAAC;YAChC,MAAM;QACR,CAAC;QAED,kCAAkC;QAClC,MAAM,aAAa,GAAsB;YACvC,UAAU;YACV,YAAY,EAAE,OAAO,CAAC,MAAM;YAC5B,mBAAmB,EAAE,aAAa;YAClC,OAAO,EAAE,YAAY;SACtB,CAAC;QACF,qBAAqB,CAAC,SAAS,EAAE,gBAAgB,EAAE,aAAa,CAAC,CAAC;QAElE,OAAO;YACL,OAAO,EAAE,YAAY;YACrB,QAAQ,EAAE,OAAO;YACjB,cAAc,EAAE,aAAa;SAC9B,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0BAA0B;QAC1B,MAAM,UAAU,GAAoB;YAClC,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,GAAG;YACV,UAAU;SACX,CAAC;QACF,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QACxD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAzID,8BAyIC;AAED,gEAAgE;AAEhE,SAAS,YAAY,CAAC,MAAoB;IACxC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAC5B,SAA0B,EAC1B,IAAyB,EACzB,KAAc;IAEd,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC1B,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;gBAC5B,EAA2B,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACrD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/executor/index.js

@@ -1,9 +0,0 @@
-"use strict";
-/**
- * executor/ — The agentLoop execution engine.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.agentLoop = void 0;
-var agentLoop_1 = require("./agentLoop");
-Object.defineProperty(exports, "agentLoop", { enumerable: true, get: function () { return agentLoop_1.agentLoop; } });
-//# sourceMappingURL=index.js.map

package/dist/executor/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,yCAAwC;AAA/B,sGAAA,SAAS,OAAA"}

package/dist/explain.barrel.js

@@ -1,29 +0,0 @@
-"use strict";
-/**
- * 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
- * ```
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExplainRecorder = exports.createAgentRenderer = void 0;
-var narrative_1 = require("./lib/narrative");
-Object.defineProperty(exports, "createAgentRenderer", { enumerable: true, get: function () { return narrative_1.createAgentRenderer; } });
-// ExplainRecorder — collect grounding data during traversal (no post-processing)
-var ExplainRecorder_1 = require("./recorders/ExplainRecorder");
-Object.defineProperty(exports, "ExplainRecorder", { enumerable: true, get: function () { return ExplainRecorder_1.ExplainRecorder; } });
-//# sourceMappingURL=explain.barrel.js.map

package/dist/explain.barrel.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"explain.barrel.js","sourceRoot":"","sources":["../src/explain.barrel.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAEH,6CAAsD;AAA7C,gHAAA,mBAAmB,OAAA;AAG5B,iFAAiF;AACjF,+DAA8D;AAArD,kHAAA,eAAe,OAAA"}

package/dist/exportTrace.js

@@ -1,75 +0,0 @@
-"use strict";
-/**
- * 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.
- * ```
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.exportTrace = void 0;
-/**
- * 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.
- */
-function exportTrace(runner, options) {
-    const redact = options?.redact !== false; // default true
-    const r = runner;
-    // `getSnapshot` may be the older 0-arg form — still safe to call with
-    // an arg (JS ignores extras), but keep our intent explicit so older
-    // overloads with strict signatures don't trip the type checker.
-    let snapshot;
-    try {
-        snapshot = r.getSnapshot?.({ redact });
-    }
-    catch {
-        // Fall back to the 0-arg form if the runner's signature rejects the
-        // options object (older custom runners). Result will be raw — caller
-        // is responsible for the safety implication when this happens.
-        try {
-            snapshot = r.getSnapshot?.();
-        }
-        catch {
-            snapshot = undefined;
-        }
-    }
-    return {
-        schemaVersion: 1,
-        exportedAt: new Date().toISOString(),
-        redacted: redact,
-        snapshot,
-        narrativeEntries: r.getNarrativeEntries?.(),
-        spec: r.getSpec?.(),
-    };
-}
-exports.exportTrace = exportTrace;
-//# sourceMappingURL=exportTrace.js.map

package/dist/exportTrace.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"exportTrace.js","sourceRoot":"","sources":["../src/exportTrace.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;AA0DH;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,MAAkB,EAAE,OAA4B;IAC1E,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,eAAe;IACzD,MAAM,CAAC,GAAG,MAA0B,CAAC;IAErC,sEAAsE;IACtE,oEAAoE;IACpE,gEAAgE;IAChE,IAAI,QAAiB,CAAC;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,qEAAqE;QACrE,+DAA+D;QAC/D,IAAI,CAAC;YACH,QAAQ,GAAI,CAAC,CAAC,WAA2C,EAAE,EAAE,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,SAAS,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,QAAQ,EAAE,MAAM;QAChB,QAAQ;QACR,gBAAgB,EAAE,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC3C,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE;KACpB,CAAC;AACJ,CAAC;AA7BD,kCA6BC"}

package/dist/instructions.barrel.js

@@ -1,30 +0,0 @@
-"use strict";
-/**
- * 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],
- * });
- * ```
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.InstructionRecorder = exports.AgentPattern = exports.quickBind = exports.follow = exports.defineInstruction = void 0;
-var instructions_1 = require("./lib/instructions");
-Object.defineProperty(exports, "defineInstruction", { enumerable: true, get: function () { return instructions_1.defineInstruction; } });
-Object.defineProperty(exports, "follow", { enumerable: true, get: function () { return instructions_1.follow; } });
-Object.defineProperty(exports, "quickBind", { enumerable: true, get: function () { return instructions_1.quickBind; } });
-var loop_1 = require("./lib/loop");
-Object.defineProperty(exports, "AgentPattern", { enumerable: true, get: function () { return loop_1.AgentPattern; } });
-var instructions_2 = require("./lib/instructions");
-Object.defineProperty(exports, "InstructionRecorder", { enumerable: true, get: function () { return instructions_2.InstructionRecorder; } });
-//# sourceMappingURL=instructions.barrel.js.map

package/dist/instructions.barrel.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"instructions.barrel.js","sourceRoot":"","sources":["../src/instructions.barrel.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAEH,mDAA0E;AAAjE,iHAAA,iBAAiB,OAAA;AAAE,sGAAA,MAAM,OAAA;AAAE,yGAAA,SAAS,OAAA;AAS7C,mCAA0C;AAAjC,oGAAA,YAAY,OAAA;AACrB,mDAAyD;AAAhD,mHAAA,mBAAmB,OAAA"}