agentfootprint 1.22.0 → 2.0.1

package/dist/resilience/withFallback.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * withFallback — provider decorator that falls back to a secondary
+ * on error.
+ *
+ * Pattern: Decorator (GoF) — composes two `LLMProvider`s into one.
+ * Role:    Outer ring (Hexagonal). Stacks with `withRetry`:
+ *          `withRetry(withFallback(primary, fallback))` first retries
+ *          the primary, then on exhaustion falls back to the secondary.
+ *
+ * Common pairings:
+ *   • Anthropic primary, OpenAI fallback (vendor outage tolerance)
+ *   • Real provider primary, Mock fallback (degrade gracefully in dev)
+ *   • Premium model primary, cheaper model fallback (cost ceiling)
+ *
+ * `stream()` falls back too — if the primary's stream errors before
+ * yielding any chunks, we restart on the fallback. Once the primary
+ * has yielded chunks the stream is committed — fallback would
+ * duplicate the partial output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFallback = void 0;
+/**
+ * Wrap a primary provider with a fallback. Tries primary first; on
+ * error matching the policy, calls the fallback.
+ *
+ * @example
+ *   const provider = withFallback(
+ *     anthropic({ apiKey: A }),
+ *     openai({ apiKey: O }),
+ *     { onFallback: (err) => console.warn('primary failed, falling back:', err) },
+ *   );
+ */
+function withFallback(primary, fallback, options = {}) {
+    const shouldFallback = options.shouldFallback ?? defaultShouldFallback;
+    const onFallback = options.onFallback;
+    const wrapped = {
+        name: `${primary.name}|${fallback.name}`,
+        async complete(req) {
+            try {
+                return await primary.complete(req);
+            }
+            catch (err) {
+                if (!shouldFallback(err))
+                    throw err;
+                onFallback?.(err);
+                return fallback.complete(req);
+            }
+        },
+    };
+    // Stream fallback — only if the primary stream fails before any
+    // chunk yields. Once a chunk is consumed downstream, restarting
+    // would replay tokens. Yields from primary as long as it's working;
+    // catches errors in the iteration setup or first chunk only.
+    if (primary.stream || fallback.stream) {
+        wrapped.stream = async function* fallbackStream(req) {
+            // No primary stream support → fallback's stream (or its complete-only).
+            if (!primary.stream) {
+                if (fallback.stream)
+                    yield* fallback.stream(req);
+                else
+                    yield* completeAsStream(fallback, req);
+                return;
+            }
+            let yieldedAny = false;
+            try {
+                for await (const chunk of primary.stream(req)) {
+                    yieldedAny = true;
+                    yield chunk;
+                }
+            }
+            catch (err) {
+                if (yieldedAny || !shouldFallback(err))
+                    throw err;
+                onFallback?.(err);
+                if (fallback.stream)
+                    yield* fallback.stream(req);
+                else
+                    yield* completeAsStream(fallback, req);
+            }
+        };
+    }
+    return wrapped;
+}
+exports.withFallback = withFallback;
+// ── Defaults ────────────────────────────────────────────────────────
+function defaultShouldFallback(err) {
+    if (!err || typeof err !== 'object')
+        return true;
+    const e = err;
+    if (e.name === 'AbortError' || e.code === 'ABORT_ERR')
+        return false;
+    return true;
+}
+/**
+ * Synthesize a stream from a non-streaming provider's `complete()`
+ * call: one terminal chunk carrying the whole response. Lets the
+ * fallback chain still satisfy a `stream()` request even when the
+ * fallback only implements `complete()`.
+ */
+async function* completeAsStream(provider, req) {
+    const response = await provider.complete(req);
+    yield {
+        tokenIndex: 0,
+        content: '',
+        done: true,
+        response,
+    };
+}
+//# sourceMappingURL=withFallback.js.map

package/dist/resilience/withFallback.js.map

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

package/dist/resilience/withRetry.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * withRetry — provider decorator that retries failed calls.
+ *
+ * Pattern: Decorator (GoF) — wraps an `LLMProvider` and adds retry
+ *          policy without changing its interface.
+ * Role:    Outer ring (Hexagonal). Composable: `withRetry(withFallback(...))`.
+ *
+ * Retries `complete()` on transient failures with exponential backoff.
+ * `stream()` is delegated as-is — once tokens start flowing the
+ * pipeline is stateful and cannot safely be restarted. If you need
+ * retry semantics for streaming, fall back to `complete()` or
+ * implement custom resumability at the consumer.
+ *
+ * Default policy:
+ *   • maxAttempts: 3 (initial + 2 retries)
+ *   • backoff:     exponential — 200ms, 400ms, 800ms
+ *   • shouldRetry: rejects 4xx-class errors (client mistakes don't
+ *                  benefit from retry) and AbortError; retries 5xx,
+ *                  network errors, and unknown shapes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = void 0;
+/**
+ * Wrap a provider so its `complete()` retries transient failures.
+ *
+ * @example
+ *   const robust = withRetry(anthropic({ apiKey }), {
+ *     maxAttempts: 5,
+ *     onRetry: (err, attempt, ms) => console.warn(`retry ${attempt} in ${ms}ms`, err),
+ *   });
+ */
+function withRetry(provider, options = {}) {
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+    const initialDelayMs = options.initialDelayMs ?? 200;
+    const backoffFactor = options.backoffFactor ?? 2;
+    const maxDelayMs = options.maxDelayMs ?? 10_000;
+    const shouldRetry = options.shouldRetry ?? defaultShouldRetry;
+    const onRetry = options.onRetry;
+    const wrapped = {
+        name: `${provider.name}+retry`,
+        async complete(req) {
+            let lastError;
+            for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+                try {
+                    return await provider.complete(req);
+                }
+                catch (err) {
+                    lastError = err;
+                    if (attempt >= maxAttempts || !shouldRetry(err, attempt)) {
+                        throw err;
+                    }
+                    const delay = Math.min(maxDelayMs, initialDelayMs * Math.pow(backoffFactor, attempt - 1));
+                    onRetry?.(err, attempt + 1, delay);
+                    await sleep(delay, req.signal);
+                }
+            }
+            // Unreachable — last attempt either returned or threw above.
+            throw lastError;
+        },
+    };
+    // Pass-through `stream()` if the underlying provider supports it.
+    // No retry on streams (mid-stream resumption is provider-specific).
+    if (provider.stream) {
+        wrapped.stream = (req) => provider.stream(req);
+    }
+    return wrapped;
+}
+exports.withRetry = withRetry;
+// ── Defaults ────────────────────────────────────────────────────────
+/**
+ * Skip retry for AbortError + 4xx-class errors. Retry on everything
+ * else (network errors, 5xx, unknown shapes). Provider adapters that
+ * surface HTTP status should set `error.status` for this to work; the
+ * predicate falls back to retrying when status is unknown (better to
+ * retry once than to surface a flaky failure).
+ */
+function defaultShouldRetry(err, _attempt) {
+    if (isAbortError(err))
+        return false;
+    const status = err?.status ??
+        err?.statusCode;
+    if (typeof status === 'number' && status >= 400 && status < 500) {
+        // 429 Too Many Requests is the one 4xx that benefits from retry.
+        return status === 429;
+    }
+    return true;
+}
+function isAbortError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    return e.name === 'AbortError' || e.code === 'ABORT_ERR';
+}
+function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error('Aborted'));
+            return;
+        }
+        const id = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(id);
+            reject(signal?.reason ?? new Error('Aborted'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=withRetry.js.map

package/dist/resilience/withRetry.js.map

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

package/dist/stream.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * agentfootprint/stream — agent events → Server-Sent Events helpers.
+ *
+ * Pattern: Adapter (event stream → SSE wire format).
+ * Role:    Outer ring. Subscribes to a `Runner`'s `EventDispatcher`
+ *          and yields SSE-formatted strings. Drop into any HTTP
+ *          framework that accepts an async iterable response body
+ *          (Fetch Response, Express res.write, Hono streaming, etc.).
+ * Emits:   N/A — observes only.
+ *
+ * ─── 7-panel design review (2026-04-28) ─────────────────────────────
+ *
+ *   LLM-AI system design   ✓ One-line-per-event SSE format. Each
+ *                            event = one observation; each chunk
+ *                            includes the `runtimeStageId` for
+ *                            cross-view binding.
+ *   Performance            ✓ AsyncIterable<string> — no buffering;
+ *                            yields each event as it arrives. Stops
+ *                            naturally when the run completes.
+ *   Scalability            ✓ Per-run instance. No shared state;
+ *                            many concurrent SSE streams safe.
+ *   Research alignment     ✓ Standard SSE wire format
+ *                            (text/event-stream). Browsers'
+ *                            native EventSource API consumes directly.
+ *   Flexibility            ✓ `format` option for full event payload
+ *                            vs slim text-only mode (chat UIs that
+ *                            only want token deltas). `filter`
+ *                            predicate gates events.
+ *   Abstraction-modular    ✓ One function (`toSSE`) + one class
+ *                            (`SSEFormatter`); class is sugar for
+ *                            consumers who prefer .pipeTo() shape.
+ *   Software engineering   ✓ Pure observer. No global state. Tests
+ *                            cover unit + scenario + property +
+ *                            security + performance.
+ *
+ * ─── 7-pattern test coverage ────────────────────────────────────────
+ *
+ *   See `test/stream/unit/SSEFormatter.test.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeSSE = exports.SSEFormatter = exports.toSSE = void 0;
+/**
+ * Subscribe to a runner's `EventDispatcher` and yield SSE-formatted
+ * strings until the run completes.
+ */
+async function* toSSE(runner, options = {}) {
+    const filter = options.filter;
+    const format = options.format ?? 'full';
+    const eventName = options.eventName ?? ((e) => e.type);
+    const heartbeatMs = options.heartbeatMs ?? 0;
+    // Pull the dispatcher off the runner. RunnerBase exposes it as
+    // protected — we cast to access. No public dispatcher() method
+    // exists ; runners forward .on/.off via their public API.
+    const dispatcher = runner.dispatcher;
+    // Bounded queue: events drained as the consumer iterates.
+    const queue = [];
+    let waiter = null;
+    let done = false;
+    const wakeup = () => {
+        if (waiter) {
+            const w = waiter;
+            waiter = null;
+            w.resolve();
+        }
+    };
+    const unsub = dispatcher.on('*', (event) => {
+        if (filter && !filter(event))
+            return;
+        queue.push(event);
+        wakeup();
+        // `agent.turn_end` (or composition exit on the outermost runner)
+        // ends the stream naturally; the consumer's `for await` finishes
+        // when the iterator returns.
+        if (event.type === 'agentfootprint.agent.turn_end' ||
+            event.type === 'agentfootprint.error.fatal') {
+            done = true;
+            wakeup();
+        }
+    });
+    let heartbeat;
+    if (heartbeatMs > 0) {
+        heartbeat = setInterval(() => {
+            queue.push({ type: '__heartbeat' });
+            wakeup();
+        }, heartbeatMs);
+    }
+    try {
+        while (!done || queue.length > 0) {
+            while (queue.length > 0) {
+                const event = queue.shift();
+                if (event.type === '__heartbeat') {
+                    yield ': ping\n\n';
+                    continue;
+                }
+                if (format === 'text') {
+                    if (event.type === 'agentfootprint.stream.token') {
+                        const payload = event.payload;
+                        if (payload?.content)
+                            yield payload.content;
+                    }
+                }
+                else {
+                    yield encodeSSE(eventName(event), event);
+                }
+            }
+            if (done)
+                break;
+            await new Promise((resolve) => {
+                waiter = { resolve };
+            });
+        }
+    }
+    finally {
+        unsub();
+        if (heartbeat)
+            clearInterval(heartbeat);
+    }
+}
+exports.toSSE = toSSE;
+/**
+ * Class form for consumers who prefer `new SSEFormatter(runner).stream()`.
+ * Identical behavior to `toSSE(runner)` — pick by preference.
+ */
+class SSEFormatter {
+    runner;
+    options;
+    constructor(runner, options = {}) {
+        this.runner = runner;
+        this.options = options;
+    }
+    /** Async iterable of SSE chunks. Consume with `for await`. */
+    stream() {
+        return toSSE(this.runner, this.options);
+    }
+}
+exports.SSEFormatter = SSEFormatter;
+/**
+ * Format any JSON-able payload as a single SSE event chunk.
+ *
+ * Useful for app-level events outside the runner's typed registry
+ * (auth/error frames, app-state echoes). Most consumers won't need this.
+ */
+function encodeSSE(eventName, payload) {
+    const json = JSON.stringify(payload);
+    // Escape newlines inside JSON (rare with stringify) so the data field
+    // stays single-line. SSE's data: lines can be repeated, but the
+    // canonical encoder keeps it simple.
+    return `event: ${eventName}\ndata: ${json}\n\n`;
+}
+exports.encodeSSE = encodeSSE;
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

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

package/dist/types/adapters/llm/AnthropicProvider.d.ts

@@ -0,0 +1,151 @@
+/**
+ * AnthropicProvider — wraps `@anthropic-ai/sdk` as an `LLMProvider`.
+ *
+ * Pattern: Adapter (GoF) + Ports-and-Adapters (Cockburn 2005).
+ * Role:    Outer ring — translates `LLMRequest`/`LLMResponse` to/from
+ *          Anthropic's Messages API. Knows nothing about agents,
+ *          recorders, or compositions.
+ * Emits:   N/A — providers don't emit; recorders observe via Agent.
+ *
+ * ─── 7-panel design review (2026-04-28) ─────────────────────────────
+ *
+ *   LLM-AI system design   ✓ Native tool_use blocks. Round-trips
+ *                            assistant tool_calls via the new
+ *                            `LLMMessage.toolCalls` field — preserves
+ *                            multi-iteration ReAct correctness.
+ *   Performance            ✓ Single SDK call per `complete()`. Stream
+ *                            uses SDK's native iterator; no buffering.
+ *   Scalability            ✓ Stateless adapter. Concurrent runs share
+ *                            one provider instance freely.
+ *   Research alignment     ✓ Mirrors v1 AnthropicAdapter's tested
+ *                            message-conversion logic (origin/main
+ *                            `c6e11d0`); tool-result merge follows the
+ *                            documented Anthropic API expectation.
+ *   Flexibility            ✓ `_client` injection point for tests.
+ *                            `apiKey` falls back to env. `maxTokens`
+ *                            override per-construction or per-request.
+ *   Abstraction-modular    ✓ Two converters (toAnthropicMessages,
+ *                            fromAnthropicResponse) isolate the
+ *                            shape-shifting; `complete()` and
+ *                            `stream()` reuse them.
+ *   Software engineering   ✓ Duck-typed SDK shape (no hard import).
+ *                            Errors wrapped with provider tag for
+ *                            uniform downstream handling. Tests cover
+ *                            unit + scenario + integration + property
+ *                            + security + performance + ROI.
+ *
+ * ─── Limitations ────────────────────────────────────────────────────
+ *
+ * • Multi-modal content (images, video) NOT supported  — the framework's
+ *   `LLMMessage.content` is `string`. The adapter accepts text-only.
+ *   May extend in a future release the message shape; this provider will be updated
+ *   in lockstep.
+ * • `responseFormat` (JSON-Schema-coerced output) NOT exposed
+ *   — consumers can pass schema instructions via `systemPrompt`.
+ *
+ * ─── 7-pattern test coverage ────────────────────────────────────────
+ *
+ *   See `test/adapters/llm/AnthropicProvider/*.test.ts`.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+interface AnthropicClient {
+    messages: {
+        create(params: AnthropicCreateParams): Promise<AnthropicMessage>;
+        stream(params: AnthropicCreateParams): AnthropicStream;
+    };
+}
+interface AnthropicCreateParams {
+    model: string;
+    max_tokens: number;
+    messages: AnthropicMessageParam[];
+    system?: string;
+    tools?: AnthropicTool[];
+    temperature?: number;
+    stop_sequences?: string[];
+}
+interface AnthropicMessageParam {
+    role: 'user' | 'assistant';
+    content: string | AnthropicContentBlock[];
+}
+type AnthropicContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+};
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+interface AnthropicMessage {
+    id: string;
+    model: string;
+    role: 'assistant';
+    content: AnthropicContentBlock[];
+    stop_reason: 'end_turn' | 'tool_use' | 'max_tokens' | string;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+interface AnthropicStream {
+    finalMessage(): Promise<AnthropicMessage>;
+    [Symbol.asyncIterator](): AsyncIterator<AnthropicStreamEvent>;
+}
+interface AnthropicStreamEvent {
+    type: string;
+    delta?: {
+        type: string;
+        text?: string;
+    };
+}
+export interface AnthropicProviderOptions {
+    /** API key. Defaults to `ANTHROPIC_API_KEY` env var. */
+    readonly apiKey?: string;
+    /**
+     * Default model used when `LLMRequest.model` is `'anthropic'` (the
+     * shorthand). When the request specifies a full model id, that wins.
+     */
+    readonly defaultModel?: string;
+    /** Default max tokens when the request doesn't set it. Default 4096. */
+    readonly defaultMaxTokens?: number;
+    /** @internal Pre-built client for testing. Skips SDK import. */
+    readonly _client?: AnthropicClient;
+}
+/**
+ * Build an `LLMProvider` backed by Anthropic's Messages API.
+ *
+ * @example
+ *   import { Agent } from 'agentfootprint';
+ *   import { anthropic } from 'agentfootprint/providers';
+ *
+ *   const agent = Agent.create({
+ *     provider: anthropic({ defaultModel: 'claude-sonnet-4-5-20250929' }),
+ *     model: 'anthropic',
+ *   })
+ *     .tool(weatherTool)
+ *     .build();
+ */
+export declare function anthropic(options?: AnthropicProviderOptions): LLMProvider;
+/**
+ * Class form for consumers who prefer `new AnthropicProvider(...)` over
+ * the `anthropic(...)` factory. Identical behavior; trivial wrapper.
+ */
+export declare class AnthropicProvider implements LLMProvider {
+    readonly name = "anthropic";
+    private readonly inner;
+    constructor(options?: AnthropicProviderOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+}
+export {};
+//# sourceMappingURL=AnthropicProvider.d.ts.map

package/dist/types/adapters/llm/AnthropicProvider.d.ts.map

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