agentfootprint 1.22.0 → 2.0.1

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

@@ -0,0 +1,127 @@
+/**
+ * BedrockProvider — wraps AWS Bedrock's Converse API as an `LLMProvider`.
+ *
+ * Pattern: Adapter (GoF) + Ports-and-Adapters (Cockburn 2005).
+ * Role:    Outer ring — translates `LLMRequest`/`LLMResponse` to/from
+ *          AWS Bedrock's model-agnostic Converse / ConverseStream APIs.
+ *          Works with ANY Bedrock-hosted model (Claude, Llama, Mistral,
+ *          Titan, Mixtral, ...) without format-specific code.
+ * Emits:   N/A.
+ *
+ * Requires: `npm install @aws-sdk/client-bedrock-runtime`
+ *
+ * ─── 7-panel design review (2026-04-28) ─────────────────────────────
+ *
+ *   LLM-AI system design   ✓ Converse API is model-agnostic — one
+ *                            adapter covers every Bedrock-hosted
+ *                            model. tool_use / tool_result blocks
+ *                            map cleanly to toolCalls.
+ *   Performance            ✓ Single SDK send() per `complete()`;
+ *                            ConverseStream for `stream()` yields
+ *                            deltas natively.
+ *   Scalability            ✓ Stateless adapter. AWS SDK handles
+ *                            credential refresh + region routing.
+ *   Research alignment     ✓ Mirrors v1 BedrockAdapter (origin/main
+ *                            `c6e11d0`). Maps same field renames
+ *                            (toolUseId, inputSchema.json, etc.).
+ *   Flexibility            ✓ `region` + `client` injectable. Model
+ *                            id passes through for fine-grained
+ *                            routing (cross-region inference profiles
+ *                            work as-is).
+ *   Abstraction-modular    ✓ Separate converters mirror the
+ *                            Anthropic/OpenAI adapters. Easy to keep
+ *                            in lockstep when LLMMessage evolves.
+ *   Software engineering   ✓ Duck-typed SDK shape. Errors wrapped
+ *                            with provider tag. Tests cover the
+ *                            7-pattern matrix.
+ *
+ * ─── Limitations ────────────────────────────────────────────────────
+ *
+ * • Multi-modal NOT supported  (text content only).
+ * • Guardrail integration NOT exposed yet — pass via the SDK client
+ *   directly if needed.
+ *
+ * ─── 7-pattern test coverage ────────────────────────────────────────
+ *
+ *   See `test/adapters/unit/BedrockProvider.test.ts`.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+interface BedrockClient {
+    send(command: unknown): Promise<unknown>;
+}
+interface BedrockConverseCommand {
+    modelId: string;
+    messages: BedrockMessage[];
+    system?: Array<{
+        text: string;
+    }>;
+    toolConfig?: {
+        tools: BedrockTool[];
+    };
+    inferenceConfig?: {
+        maxTokens?: number;
+        temperature?: number;
+        stopSequences?: string[];
+    };
+}
+interface BedrockMessage {
+    role: 'user' | 'assistant';
+    content: BedrockContentBlock[];
+}
+type BedrockContentBlock = {
+    text: string;
+} | {
+    toolUse: {
+        toolUseId: string;
+        name: string;
+        input: Record<string, unknown>;
+    };
+} | {
+    toolResult: {
+        toolUseId: string;
+        content: Array<{
+            text: string;
+        }>;
+        status?: 'success' | 'error';
+    };
+};
+interface BedrockTool {
+    toolSpec: {
+        name: string;
+        description: string;
+        inputSchema: {
+            json: Record<string, unknown>;
+        };
+    };
+}
+export interface BedrockProviderOptions {
+    /** AWS region (e.g., 'us-east-1'). Defaults to AWS SDK auto-detect. */
+    readonly region?: string;
+    /**
+     * Default model id (e.g., `anthropic.claude-sonnet-4-5-20250929-v1:0`).
+     * Used when `LLMRequest.model` is the shorthand `'bedrock'`.
+     */
+    readonly defaultModel?: string;
+    /** Default max tokens when not in the request. Default 4096. */
+    readonly defaultMaxTokens?: number;
+    /** @internal Pre-built client for testing. */
+    readonly _client?: BedrockClient;
+    /**
+     * @internal Test override for the SDK's command constructors. Real
+     * use goes through the dynamic `require('@aws-sdk/client-bedrock-runtime')`.
+     */
+    readonly _commands?: {
+        readonly Converse: new (input: BedrockConverseCommand) => unknown;
+        readonly ConverseStream: new (input: BedrockConverseCommand) => unknown;
+    };
+}
+export declare function bedrock(options?: BedrockProviderOptions): LLMProvider;
+export declare class BedrockProvider implements LLMProvider {
+    readonly name = "bedrock";
+    private readonly inner;
+    constructor(options?: BedrockProviderOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+}
+export {};
+//# sourceMappingURL=BedrockProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BedrockProvider.d.ts","sourceRoot":"","sources":["../../../../src/adapters/llm/BedrockProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,WAAW,EACX,UAAU,EACV,WAAW,EAEZ,MAAM,aAAa,CAAC;AAIrB,UAAU,aAAa;IACrB,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,UAAU,sBAAsB;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,WAAW,EAAE,CAAA;KAAE,CAAC;IACtC,eAAe,CAAC,EAAE;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;CACH;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED,KAAK,mBAAmB,GACpB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;CAAE,GAChF;IACE,UAAU,EAAE;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjC,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;KAC9B,CAAC;CACH,CAAC;AAEN,UAAU,WAAW;IACnB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC;KAChD,CAAC;CACH;AAkCD,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,QAAQ,EAAE,KAAK,KAAK,EAAE,sBAAsB,KAAK,OAAO,CAAC;QAClE,QAAQ,CAAC,cAAc,EAAE,KAAK,KAAK,EAAE,sBAAsB,KAAK,OAAO,CAAC;KACzE,CAAC;CACH;AAED,wBAAgB,OAAO,CAAC,OAAO,GAAE,sBAA2B,GAAG,WAAW,CA2EzE;AAED,qBAAa,eAAgB,YAAW,WAAW;IACjD,QAAQ,CAAC,IAAI,aAAa;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAExB,OAAO,GAAE,sBAA2B;IAIhD,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAI/C,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,aAAa,CAAC,QAAQ,CAAC;CAIjD"}

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

@@ -0,0 +1,72 @@
+/**
+ * BrowserAnthropicProvider — fetch-based Anthropic adapter for browsers.
+ *
+ * Pattern: Adapter (GoF). Zero peer dependencies — uses global `fetch`.
+ * Role:    Outer ring. Same `LLMProvider` contract as `AnthropicProvider`,
+ *          but skips `@anthropic-ai/sdk` (which doesn't bundle cleanly
+ *          for browser). Aimed at playgrounds / prototypes where the
+ *          user supplies their own key.
+ * Emits:   N/A.
+ *
+ * Anthropic requires the `anthropic-dangerous-direct-browser-access: true`
+ * header for direct browser-to-API calls. This is intentional — production
+ * apps should proxy through a backend.
+ *
+ * ─── 7-panel design review (2026-04-28) ─────────────────────────────
+ *
+ *   LLM-AI system design   ✓ Same message + tool conversion as the
+ *                            Node `AnthropicProvider`. Native tool_use
+ *                            blocks; `LLMMessage.toolCalls` round-trip.
+ *   Performance            ✓ One fetch() per `complete()`. Stream
+ *                            uses native `ReadableStream` via SSE
+ *                            parsing — no buffering past one chunk.
+ *   Scalability            ✓ Stateless. Multiple agents share one
+ *                            provider; browser fetch handles
+ *                            concurrent requests fine.
+ *   Research alignment     ✓ Mirrors v1 BrowserAnthropicAdapter
+ *                            (origin/main `c6e11d0`). Same headers,
+ *                            same SSE event shape.
+ *   Flexibility            ✓ `apiUrl` override for proxy/edge
+ *                            deployments. Custom `fetch` injection
+ *                            for tests + workers.
+ *   Abstraction-modular    ✓ Re-uses `toAnthropicMessages` /
+ *                            `fromAnthropicResponse` semantics from
+ *                            the Node adapter (small duplication kept
+ *                            local — both files stay readable).
+ *   Software engineering   ✓ Zero peer deps (browser fetch is
+ *                            ambient). Errors wrapped with status
+ *                            for `withRetry` policy hooks. SSE parser
+ *                            handles partial chunks.
+ *
+ * ─── Limitations ────────────────────────────────────────────────────
+ *
+ * • Multi-modal NOT .
+ * • Browser CORS — works because Anthropic explicitly allows the
+ *   dangerous-direct header. Future API changes could require a proxy.
+ *
+ * ─── 7-pattern test coverage ────────────────────────────────────────
+ *
+ *   See `test/adapters/unit/BrowserAnthropicProvider.test.ts`.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+export interface BrowserAnthropicProviderOptions {
+    /** API key. REQUIRED — browser providers don't read env vars. */
+    readonly apiKey: string;
+    /** Default model when `LLMRequest.model` is `'anthropic'`. */
+    readonly defaultModel?: string;
+    /** Default max tokens. Default 4096. */
+    readonly defaultMaxTokens?: number;
+    /** Override the API URL (proxies, edge deployments, mocks). */
+    readonly apiUrl?: string;
+    /** @internal Custom fetch implementation for tests / workers. */
+    readonly _fetch?: typeof fetch;
+}
+export declare function browserAnthropic(options: BrowserAnthropicProviderOptions): LLMProvider;
+export declare class BrowserAnthropicProvider implements LLMProvider {
+    readonly name = "browser-anthropic";
+    private readonly inner;
+    constructor(options: BrowserAnthropicProviderOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+}
+//# sourceMappingURL=BrowserAnthropicProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserAnthropicProvider.d.ts","sourceRoot":"","sources":["../../../../src/adapters/llm/BrowserAnthropicProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,WAAW,EACX,UAAU,EACV,WAAW,EAEZ,MAAM,aAAa,CAAC;AA6CrB,MAAM,WAAW,+BAA+B;IAC9C,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,CAAC;CAChC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,+BAA+B,GAAG,WAAW,CAuGtF;AAED,qBAAa,wBAAyB,YAAW,WAAW;IAC1D,QAAQ,CAAC,IAAI,uBAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAExB,OAAO,EAAE,+BAA+B;IAIpD,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAI/C,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,aAAa,CAAC,QAAQ,CAAC;CAIjD"}

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

@@ -0,0 +1,52 @@
+/**
+ * BrowserOpenAIProvider — fetch-based OpenAI adapter for browsers.
+ *
+ * Pattern: Adapter (GoF). Zero peer dependencies — uses global `fetch`.
+ * Role:    Outer ring. Same `LLMProvider` contract as `OpenAIProvider`
+ *          but skips the `openai` SDK. For prototypes / playgrounds.
+ *          Production apps should proxy through a backend.
+ * Emits:   N/A.
+ *
+ * Also works with OpenAI-compatible endpoints (Ollama, Together, vLLM)
+ * via `apiUrl`.
+ *
+ * ─── 7-panel review ─────────────────────────────────────────────────
+ *
+ *   Same posture as `BrowserAnthropicProvider`: native fetch, SSE
+ *   parser, stateless, error-wrapped, message-conversion mirrors the
+ *   Node `OpenAIProvider`. See that adapter's review for full rubric.
+ *
+ * ─── Limitations ────────────────────────────────────────────────────
+ *
+ * • Multi-modal NOT .
+ * • CORS depends on the endpoint — OpenAI requires the user-supplied
+ *   key in the Authorization header, which they'll do explicitly.
+ *
+ * ─── 7-pattern test coverage ────────────────────────────────────────
+ *
+ *   See `test/adapters/unit/BrowserOpenAIProvider.test.ts`.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+export interface BrowserOpenAIProviderOptions {
+    /** API key. REQUIRED. */
+    readonly apiKey: string;
+    /** Default model when `LLMRequest.model` is `'openai'`. */
+    readonly defaultModel?: string;
+    /** Default max tokens. */
+    readonly defaultMaxTokens?: number;
+    /** Override the API URL (Ollama, Together, vLLM, OpenAI proxies). */
+    readonly apiUrl?: string;
+    /** Optional `Organization` header. */
+    readonly organization?: string;
+    /** @internal Custom fetch implementation for tests. */
+    readonly _fetch?: typeof fetch;
+}
+export declare function browserOpenai(options: BrowserOpenAIProviderOptions): LLMProvider;
+export declare class BrowserOpenAIProvider implements LLMProvider {
+    readonly name = "browser-openai";
+    private readonly inner;
+    constructor(options: BrowserOpenAIProviderOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+}
+//# sourceMappingURL=BrowserOpenAIProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserOpenAIProvider.d.ts","sourceRoot":"","sources":["../../../../src/adapters/llm/BrowserOpenAIProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,WAAW,EACX,UAAU,EACV,WAAW,EAEZ,MAAM,aAAa,CAAC;AAsErB,MAAM,WAAW,4BAA4B;IAC3C,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,0BAA0B;IAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,CAAC;CAChC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,4BAA4B,GAAG,WAAW,CAyGhF;AAED,qBAAa,qBAAsB,YAAW,WAAW;IACvD,QAAQ,CAAC,IAAI,oBAAoB;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAExB,OAAO,EAAE,4BAA4B;IAIjD,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAI/C,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,aAAa,CAAC,QAAQ,CAAC;CAIjD"}

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

@@ -0,0 +1,109 @@
+/**
+ * MockProvider — deterministic LLMProvider for tests + examples.
+ *
+ * Pattern: Adapter (GoF, Design Patterns ch. 4).
+ * Role:    Ports-and-Adapters outer ring (Cockburn, 2005) — implements the
+ *          LLMProvider port without calling out to a real LLM service.
+ * Emits:   N/A (adapters don't emit; recorders observe them).
+ *
+ * Two modes, same provider:
+ *   • DEFAULT (no latency options)  — instant `complete()`, no streaming.
+ *     Use in unit tests; behavior unchanged from earlier revisions.
+ *   • REALISTIC (`thinkingMs` set)  — randomised "thinking" latency before
+ *     the response, plus a `stream()` implementation that emits the
+ *     content word-by-word with `chunkDelayMs` between chunks. Lets
+ *     consumers SEE the run unfold (pauses, streaming tokens, tool
+ *     dispatch) instead of having every step finish in microseconds.
+ *
+ * Realistic mode is the right default for the playground / Lens demos:
+ * a real OpenAI / Anthropic call takes 3–8 s, so the UX you build for
+ * that timing is what matters. Use `MockProvider.realistic()` for the
+ * common 3–8 s thinking + 30–80 ms per word streaming preset.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+/** Either a fixed value (in ms) or a random `[min, max]` range (inclusive). */
+export type LatencyMs = number | readonly [number, number];
+export interface MockProviderOptions {
+    readonly name?: string;
+    /** Fixed response content. Overrides `respond` when set. */
+    readonly reply?: string;
+    /**
+     * Build the response from the request. Returns either a plain
+     * string (renders as content with no tool calls) or a partial
+     * `LLMResponse` so consumers can simulate tool calls + multi-turn
+     * loops without needing a separate `scripted()` helper.
+     *
+     * Default: echoes the last user message.
+     */
+    readonly respond?: (req: LLMRequest) => string | Partial<LLMResponse>;
+    /**
+     * Simulated wall-clock delay per request (ms).
+     * Pass a single number for a fixed delay or a `[min, max]` tuple for
+     * a uniformly random delay (e.g. `[3000, 8000]` for "real LLM"
+     * thinking time). Default 0 (instant).
+     *
+     * Aliased via `delayMs` for backward compatibility.
+     */
+    readonly thinkingMs?: LatencyMs;
+    /** Alias for `thinkingMs`. Kept for back-compat with prior revisions. */
+    readonly delayMs?: LatencyMs;
+    /**
+     * For `stream()`: delay between successive chunks (ms). Pass a
+     * single number for a fixed delay or a `[min, max]` tuple for a
+     * uniformly random delay per chunk (e.g. `[30, 80]` for typing-like
+     * cadence). Default 30ms.
+     *
+     * Has no effect on `complete()`.
+     */
+    readonly chunkDelayMs?: LatencyMs;
+    /** Fixed stop reason to return. Default 'stop'. */
+    readonly stopReason?: string;
+    /** Override usage counts returned. Default: chars/4 heuristic. */
+    readonly usage?: Readonly<{
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    }>;
+}
+export declare class MockProvider implements LLMProvider {
+    readonly name: string;
+    private readonly reply?;
+    private readonly respond;
+    private readonly thinkingMs;
+    private readonly chunkDelayMs;
+    private readonly stopReason;
+    private readonly usageOverride;
+    constructor(options?: MockProviderOptions);
+    /**
+     * Convenience factory for the playground / Lens demo defaults: a
+     * real-feel mock with 3–8 s of "thinking" before the response and
+     * 30–80 ms per streamed word. Lets users observe pause/resume,
+     * streaming, and tool dispatch happening live without hitting a
+     * paid API.
+     */
+    static realistic(options?: MockProviderOptions): MockProvider;
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    /**
+     * Streaming mode — emits the response content word-by-word so
+     * consumers (Lens commentary, chat UIs) can render tokens as they
+     * arrive. Tool calls land all at once on the final chunk because
+     * that is how real providers (OpenAI, Anthropic) deliver them too.
+     */
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+    private buildResponse;
+}
+/**
+ * Lowercase factory for `MockProvider` — matches the v1 `mock()` import
+ * shape so docs and quick-starts stay copy-pasteable. Equivalent to
+ * `new MockProvider(options)`.
+ *
+ * @example
+ *   import { Agent, mock, defineTool } from 'agentfootprint';
+ *
+ *   const agent = Agent.create({ provider: mock({ reply: 'hello' }) })
+ *     .tool(defineTool({ name: 'echo', ... }))
+ *     .build();
+ */
+export declare function mock(options?: MockProviderOptions): MockProvider;
+//# sourceMappingURL=MockProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MockProvider.d.ts","sourceRoot":"","sources":["../../../../src/adapters/llm/MockProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAElF,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACtE;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ;AAED,qBAAa,YAAa,YAAW,WAAW;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqD;IAC7E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAY;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAY;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;gBAEjD,OAAO,GAAE,mBAAwB;IAgB7C;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY;IAQ3D,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAKrD;;;;;OAKG;IACI,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,aAAa,CAAC,QAAQ,CAAC;IAqBvD,OAAO,CAAC,aAAa;CAuBtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAEpE"}

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

@@ -0,0 +1,181 @@
+/**
+ * OpenAIProvider — wraps the `openai` SDK as an `LLMProvider`.
+ *
+ * Pattern: Adapter (GoF) + Ports-and-Adapters (Cockburn 2005).
+ * Role:    Outer ring — translates `LLMRequest`/`LLMResponse` to/from
+ *          OpenAI's Chat Completions API. Knows nothing about agents,
+ *          recorders, or compositions.
+ * Emits:   N/A.
+ *
+ * ─── 7-panel design review (2026-04-28) ─────────────────────────────
+ *
+ *   LLM-AI system design   ✓ Native function-calling. messages map
+ *                            1:1 to OpenAI shape (system/user/assistant/tool
+ *                            roles match) — minimal translation.
+ *   Performance            ✓ Single SDK call per `complete()`. Stream
+ *                            uses native SSE; deltas yielded as they
+ *                            arrive.
+ *   Scalability            ✓ Stateless; concurrent runs share one
+ *                            provider freely.
+ *   Research alignment     ✓ Mirrors v1 OpenAIAdapter conversion logic
+ *                            (origin/main `c6e11d0`); same usage
+ *                            normalization (prompt_tokens/completion_tokens
+ *                            → input/output).
+ *   Flexibility            ✓ `baseURL` enables OpenAI-compatible APIs
+ *                            (Ollama, Together, Groq, vLLM, LM Studio)
+ *                            without a separate adapter — see `ollama()`
+ *                            convenience factory below.
+ *   Abstraction-modular    ✓ Two converters (`toOpenAIMessages`,
+ *                            `fromOpenAIResponse`) isolate the
+ *                            shape-shifting; `complete()` and
+ *                            `stream()` reuse them.
+ *   Software engineering   ✓ Duck-typed SDK. Errors wrapped with
+ *                            provider tag. JSON-parsed tool args fall
+ *                            back to `{}` on malformed strings.
+ *
+ * ─── Limitations ────────────────────────────────────────────────────
+ *
+ * • Multi-modal NOT supported  (`LLMMessage.content` is
+ *   `string`). May extend in a future release.
+ * • `responseFormat` (JSON-mode) NOT exposed  — pass schema
+ *   instructions via `systemPrompt` for now.
+ *
+ * ─── 7-pattern test coverage ────────────────────────────────────────
+ *
+ *   See `test/adapters/unit/OpenAIProvider.test.ts`.
+ */
+import type { LLMChunk, LLMProvider, LLMRequest, LLMResponse } from '../types.js';
+interface OpenAIClient {
+    chat: {
+        completions: {
+            create(params: OpenAICreateParams): Promise<OpenAIChatCompletion> | AsyncIterable<OpenAIStreamChunk>;
+        };
+    };
+}
+interface OpenAICreateParams {
+    model: string;
+    messages: OpenAIMessage[];
+    tools?: OpenAITool[];
+    max_tokens?: number;
+    temperature?: number;
+    stop?: string[];
+    stream?: boolean;
+}
+interface OpenAIMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: OpenAIToolCall[];
+    tool_call_id?: string;
+}
+interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface OpenAIChatCompletion {
+    id: string;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: 'assistant';
+            content: string | null;
+            tool_calls?: OpenAIToolCall[];
+        };
+        finish_reason: 'stop' | 'tool_calls' | 'length' | 'content_filter' | string;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+}
+interface OpenAIStreamChunk {
+    id: string;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: string;
+            content?: string | null;
+            tool_calls?: Array<{
+                index: number;
+                id?: string;
+                type?: string;
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }>;
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+}
+export interface OpenAIProviderOptions {
+    /** API key. Defaults to `OPENAI_API_KEY` env var. */
+    readonly apiKey?: string;
+    /** Base URL — set for OpenAI-compatible APIs (Ollama, Together, vLLM). */
+    readonly baseURL?: string;
+    /**
+     * Default model used when `LLMRequest.model` is `'openai'` (the
+     * shorthand). Full model ids pass through unchanged.
+     */
+    readonly defaultModel?: string;
+    /** Default max tokens when the request doesn't set it. Optional. */
+    readonly defaultMaxTokens?: number;
+    /** @internal Pre-built client for testing. Skips SDK import. */
+    readonly _client?: OpenAIClient;
+}
+/**
+ * Build an `LLMProvider` backed by OpenAI's Chat Completions API.
+ *
+ * @example
+ *   import { Agent } from 'agentfootprint';
+ *   import { openai } from 'agentfootprint/providers';
+ *
+ *   const agent = Agent.create({
+ *     provider: openai({ defaultModel: 'gpt-4o' }),
+ *     model: 'openai',
+ *   })
+ *     .tool(searchTool)
+ *     .build();
+ */
+export declare function openai(options?: OpenAIProviderOptions): LLMProvider;
+/**
+ * Class form for consumers who prefer `new OpenAIProvider(...)`.
+ */
+export declare class OpenAIProvider implements LLMProvider {
+    readonly name = "openai";
+    private readonly inner;
+    constructor(options?: OpenAIProviderOptions);
+    complete(req: LLMRequest): Promise<LLMResponse>;
+    stream(req: LLMRequest): AsyncIterable<LLMChunk>;
+}
+/**
+ * Convenience factory for Ollama (OpenAI-compatible endpoint).
+ *
+ * @example
+ *   import { ollama } from 'agentfootprint/providers';
+ *
+ *   const provider = ollama({ defaultModel: 'llama3.2' });
+ *   // Talks to http://localhost:11434/v1 by default.
+ */
+export declare function ollama(options?: OpenAIProviderOptions & {
+    readonly host?: string;
+}): LLMProvider;
+export {};
+//# sourceMappingURL=OpenAIProvider.d.ts.map

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

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

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

@@ -0,0 +1,57 @@
+/**
+ * createProvider — by-name factory for any built-in LLMProvider.
+ *
+ * Pattern: Abstract Factory (GoF) over the concrete provider factories.
+ * Role:    Convenience entry point. Useful for config-driven setups
+ *          where the provider is chosen at runtime (env var, feature
+ *          flag, tenant preference).
+ * Emits:   N/A.
+ *
+ * @example
+ *   const provider = createProvider({
+ *     kind: process.env.LLM_PROVIDER ?? 'mock',
+ *     apiKey: process.env.LLM_API_KEY,
+ *     defaultModel: process.env.LLM_MODEL,
+ *   });
+ *
+ * For provider-specific options (Bedrock region, Ollama host, Browser
+ * apiUrl, etc.) construct the underlying factory directly — this
+ * helper deliberately exposes only the common subset.
+ */
+import type { LLMProvider } from '../types.js';
+import { type MockProviderOptions } from './MockProvider.js';
+import { type AnthropicProviderOptions } from './AnthropicProvider.js';
+import { type OpenAIProviderOptions } from './OpenAIProvider.js';
+import { type BedrockProviderOptions } from './BedrockProvider.js';
+import { type BrowserAnthropicProviderOptions } from './BrowserAnthropicProvider.js';
+import { type BrowserOpenAIProviderOptions } from './BrowserOpenAIProvider.js';
+/** Built-in provider kinds. Custom providers don't go through this factory. */
+export type ProviderKind = 'mock' | 'anthropic' | 'openai' | 'ollama' | 'bedrock' | 'browser-anthropic' | 'browser-openai';
+/**
+ * Common subset of options accepted across all built-in providers.
+ * Provider-specific keys (region for Bedrock, host for Ollama,
+ * organization for OpenAI, apiUrl for browser) are passed through
+ * verbatim — TypeScript narrows by `kind`.
+ */
+export type CreateProviderOptions = ({
+    readonly kind: 'mock';
+} & MockProviderOptions) | ({
+    readonly kind: 'anthropic';
+} & AnthropicProviderOptions) | ({
+    readonly kind: 'openai';
+} & OpenAIProviderOptions) | ({
+    readonly kind: 'ollama';
+} & OpenAIProviderOptions & {
+    readonly host?: string;
+}) | ({
+    readonly kind: 'bedrock';
+} & BedrockProviderOptions) | ({
+    readonly kind: 'browser-anthropic';
+} & BrowserAnthropicProviderOptions) | ({
+    readonly kind: 'browser-openai';
+} & BrowserOpenAIProviderOptions);
+/**
+ * Build any built-in LLMProvider from a tagged options object.
+ */
+export declare function createProvider(options: CreateProviderOptions): LLMProvider;
+//# sourceMappingURL=createProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createProvider.d.ts","sourceRoot":"","sources":["../../../../src/adapters/llm/createProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAQ,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAa,KAAK,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAW,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAiB,KAAK,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAE9F,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,mBAAmB,GACnB,gBAAgB,CAAC;AAErB;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAC7B,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,mBAAmB,CAAC,GACjD,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAAG,wBAAwB,CAAC,GAC3D,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,qBAAqB,CAAC,GACrD,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,qBAAqB,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAClF,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG,sBAAsB,CAAC,GACvD,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAAG,+BAA+B,CAAC,GAC1E,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAAG,4BAA4B,CAAC,CAAC;AAEzE;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,WAAW,CAwB1E"}