bare-agent 0.11.0 → 0.12.0

package/src/planner.d.ts

@@ -0,0 +1,62 @@
+export type Provider = import("../types").Provider;
+export type Step = {
+    /**
+     * - Unique step identifier.
+     */
+    id: string;
+    /**
+     * - Description of the step to execute.
+     */
+    action: string;
+    /**
+     * - Ids of steps that must complete first.
+     */
+    dependsOn: string[];
+    /**
+     * - Lifecycle status (e.g. 'pending').
+     */
+    status: string;
+};
+export type PlannerOptions = {
+    /**
+     * - LLM provider (must implement generate()).
+     */
+    provider: Provider;
+    /**
+     * - Custom planning prompt override.
+     */
+    prompt?: string | undefined;
+    /**
+     * - Cache time-to-live in ms. 0 disables caching.
+     */
+    cacheTTL?: number | undefined;
+};
+export class Planner {
+    /**
+     * @param {PlannerOptions} options
+     * @throws {Error} `[Planner] requires a provider` — when options.provider is missing.
+     */
+    constructor(options?: PlannerOptions);
+    provider: import("../types").Provider;
+    prompt: string;
+    _cacheTTL: number;
+    _cache: Map<any, any>;
+    /**
+     * Generate a step DAG from a goal.
+     * @param {string} goal - The user's goal to decompose.
+     * @param {{info?: string}} [context={}] - Optional context with info field.
+     * @returns {Promise<Step[]>}
+     * @throws {Error} `[Planner] could not parse plan` — when LLM output is not parseable JSON.
+     * @throws {Error} `[Planner] expected JSON array` — when parsed result is not an array.
+     * @throws {Error} `[Planner] step missing id or action` — when a step lacks required fields.
+     */
+    plan(goal: string, context?: {
+        info?: string;
+    }): Promise<Step[]>;
+    clearCache(): void;
+    /**
+     * @param {string} text - Raw LLM output to parse into steps.
+     * @returns {Step[]}
+     */
+    _parse(text: string): Step[];
+}

package/src/planner.js

@@ -1,5 +1,22 @@
 'use strict';
 
+/** @typedef {import('../types').Provider} Provider */
+
+/**
+ * @typedef {object} Step
+ * @property {string} id - Unique step identifier.
+ * @property {string} action - Description of the step to execute.
+ * @property {string[]} dependsOn - Ids of steps that must complete first.
+ * @property {string} status - Lifecycle status (e.g. 'pending').
+ */
+
+/**
+ * @typedef {object} PlannerOptions
+ * @property {Provider} provider - LLM provider (must implement generate()).
+ * @property {string} [prompt] - Custom planning prompt override.
+ * @property {number} [cacheTTL] - Cache time-to-live in ms. 0 disables caching.
+ */
+
 const PLAN_PROMPT = `You are a planning agent. Break the user's goal into concrete steps.
 
 Rules:
@@ -16,12 +33,10 @@ Output format:
 
 class Planner {
   /**
-   * @param {object} options
-   * @param {object} options.provider - LLM provider (must implement generate()).
-   * @param {string} [options.prompt] - Custom planning prompt override.
+   * @param {PlannerOptions} options
    * @throws {Error} `[Planner] requires a provider` — when options.provider is missing.
    */
-  constructor(options = {}) {
+  constructor(options = /** @type {PlannerOptions} */ ({})) {
     if (!options.provider) throw new Error('[Planner] requires a provider');
     this.provider = options.provider;
     this.prompt = options.prompt || PLAN_PROMPT;
@@ -32,8 +47,8 @@ class Planner {
   /**
    * Generate a step DAG from a goal.
    * @param {string} goal - The user's goal to decompose.
-   * @param {object} [context={}] - Optional context with info field.
-   * @returns {Promise<Array<{id: string, action: string, dependsOn: string[], status: string}>>}
+   * @param {{info?: string}} [context={}] - Optional context with info field.
+   * @returns {Promise<Step[]>}
    * @throws {Error} `[Planner] could not parse plan` — when LLM output is not parseable JSON.
    * @throws {Error} `[Planner] expected JSON array` — when parsed result is not an array.
    * @throws {Error} `[Planner] step missing id or action` — when a step lacks required fields.
@@ -74,6 +89,10 @@ class Planner {
     this._cache.clear();
   }
 
+  /**
+   * @param {string} text - Raw LLM output to parse into steps.
+   * @returns {Step[]}
+   */
   _parse(text) {
     // Extract JSON array from response (handle markdown code blocks)
     const cleaned = text.replace(/^```(?:json)?\s*\n?/m, '').replace(/\n?```\s*$/m, '').trim();
@@ -93,7 +112,7 @@ class Planner {
     const ids = new Set(steps.map(s => s.id));
     return steps.map(s => {
       if (!s.id || !s.action) throw new Error(`[Planner] step missing id or action: ${JSON.stringify(s)}`);
-      const deps = (s.dependsOn || []).filter(d => ids.has(d));
+      const deps = (s.dependsOn || []).filter(/** @param {string} d */ d => ids.has(d));
       return { id: s.id, action: s.action, dependsOn: deps, status: 'pending' };
     });
   }

package/src/provider-anthropic.d.ts

@@ -0,0 +1,55 @@
+export type Message = import("../types").Message;
+export type ToolDef = import("../types").ToolDef;
+export type GenerateResult = import("../types").GenerateResult;
+export type AnthropicOptions = {
+    /**
+     * - Anthropic API key (required).
+     */
+    apiKey?: string | undefined;
+    /**
+     * - Model ID.
+     */
+    model?: string | undefined;
+    /**
+     * - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
+     */
+    exposeErrorBody?: boolean | undefined;
+};
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+/**
+ * @typedef {object} AnthropicOptions
+ * @property {string} [apiKey] - Anthropic API key (required).
+ * @property {string} [model='claude-haiku-4-5-20251001'] - Model ID.
+ * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
+ */
+export class AnthropicProvider {
+    /**
+     * @param {AnthropicOptions} [options]
+     * @throws {Error} `[AnthropicProvider] requires apiKey` — when apiKey is missing.
+     */
+    constructor(options?: AnthropicOptions);
+    apiKey: string;
+    model: string;
+    exposeErrorBody: boolean;
+    /**
+     * Generate a response from the Anthropic API.
+     * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
+     * @param {ToolDef[]} [tools=[]] - Tool definitions.
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, system).
+     * @returns {Promise<GenerateResult>}
+     * @throws {Error} `[AnthropicProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
+     */
+    generate(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
+    /**
+     * @param {Message} msg
+     * @returns {any}
+     */
+    _toAnthropicMessage(msg: Message): any;
+    /**
+     * @param {Record<string, any>} body
+     * @returns {Promise<any>}
+     */
+    _request(body: Record<string, any>): Promise<any>;
+}

package/src/provider-anthropic.js

@@ -3,12 +3,20 @@
 const https = require('https');
 const { ProviderError } = require('./errors');
 
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+
+/**
+ * @typedef {object} AnthropicOptions
+ * @property {string} [apiKey] - Anthropic API key (required).
+ * @property {string} [model='claude-haiku-4-5-20251001'] - Model ID.
+ * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
+ */
+
 class AnthropicProvider {
   /**
-   * @param {object} options
-   * @param {string} options.apiKey - Anthropic API key (required).
-   * @param {string} [options.model='claude-haiku-4-5-20251001'] - Model ID.
-   * @param {boolean} [options.exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
+   * @param {AnthropicOptions} [options]
    * @throws {Error} `[AnthropicProvider] requires apiKey` — when apiKey is missing.
    */
   constructor(options = {}) {
@@ -21,15 +29,17 @@ class AnthropicProvider {
 
   /**
    * Generate a response from the Anthropic API.
-   * @param {Array<object>} messages - Conversation messages (OpenAI format, auto-converted).
-   * @param {Array<object>} [tools=[]] - Tool definitions.
-   * @param {object} [options={}] - Options (temperature, maxTokens, system).
-   * @returns {Promise<{text: string, toolCalls: Array, usage: object}>}
+   * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
+   * @param {ToolDef[]} [tools=[]] - Tool definitions.
+   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, system).
+   * @returns {Promise<GenerateResult>}
    * @throws {Error} `[AnthropicProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
   async generate(messages, tools = [], options = {}) {
     // Separate system message from conversation messages
+    /** @type {any} */
     let system;
+    /** @type {any[]} */
     const msgs = [];
     for (const m of messages) {
       if (m.role === 'system') {
@@ -42,6 +52,7 @@ class AnthropicProvider {
     // Override with options.system if provided
     if (options.system) system = options.system;
 
+    /** @type {Record<string, any>} */
     const body = {
       model: this.model,
       max_tokens: options.maxTokens || 4096,
@@ -60,6 +71,7 @@ class AnthropicProvider {
     const data = await this._request(body);
 
     let text = '';
+    /** @type {import('../types').ToolCall[]} */
     const toolCalls = [];
     for (const block of data.content) {
       if (block.type === 'text') text += block.text;
@@ -78,6 +90,10 @@ class AnthropicProvider {
     };
   }
 
+  /**
+   * @param {Message} msg
+   * @returns {any}
+   */
   _toAnthropicMessage(msg) {
     // Convert OpenAI-format tool results → Anthropic tool_result blocks
     if (msg.role === 'tool') {
@@ -91,7 +107,8 @@ class AnthropicProvider {
       };
     }
     // Convert OpenAI-format assistant tool_calls → Anthropic tool_use content blocks
-    if (msg.role === 'assistant' && msg.tool_calls?.length > 0) {
+    if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
+      /** @type {any[]} */
       const content = [];
       if (msg.content) content.push({ type: 'text', text: msg.content });
       for (const tc of msg.tool_calls) {
@@ -109,6 +126,10 @@ class AnthropicProvider {
     return { role: msg.role, content: msg.content };
   }
 
+  /**
+   * @param {Record<string, any>} body
+   * @returns {Promise<any>}
+   */
   _request(body) {
     return new Promise((resolve, reject) => {
       const payload = JSON.stringify(body);
@@ -126,10 +147,10 @@ class AnthropicProvider {
         res.on('end', () => {
           try {
             const parsed = JSON.parse(chunks);
-            if (res.statusCode >= 400) {
+            if ((res.statusCode ?? 0) >= 400) {
               return reject(new ProviderError(
                 `[AnthropicProvider] ${parsed.error?.message || `HTTP ${res.statusCode}`}`,
-                { status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined }
+                /** @type {any} */ ({ status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined })
               ));
             }
             resolve(parsed);

package/src/provider-clipipe.d.ts

@@ -0,0 +1,86 @@
+export type Message = import("../types").Message;
+export type ToolDef = import("../types").ToolDef;
+export type GenerateResult = import("../types").GenerateResult;
+export type CLIPipeOptions = {
+    /**
+     * - CLI command to spawn (required).
+     */
+    command?: string | undefined;
+    /**
+     * - Arguments to pass to the command.
+     */
+    args?: string[] | undefined;
+    /**
+     * - Working directory for the child process.
+     */
+    cwd?: string | undefined;
+    /**
+     * - Environment variables for the child process.
+     */
+    env?: Record<string, string> | undefined;
+    /**
+     * - Timeout in milliseconds.
+     */
+    timeout?: number | undefined;
+    /**
+     * - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
+     */
+    systemPromptFlag?: string | undefined;
+    /**
+     * - Called with each stdout chunk as it streams.
+     */
+    onChunk?: ((chunk: string) => void) | undefined;
+};
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+/**
+ * @typedef {object} CLIPipeOptions
+ * @property {string} [command] - CLI command to spawn (required).
+ * @property {string[]} [args=[]] - Arguments to pass to the command.
+ * @property {string} [cwd] - Working directory for the child process.
+ * @property {Record<string, string>} [env] - Environment variables for the child process.
+ * @property {number} [timeout=30000] - Timeout in milliseconds.
+ * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
+ * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
+ */
+export class CLIPipeProvider {
+    /**
+     * Provider that pipes prompts to a CLI command via stdin and reads stdout.
+     * @param {CLIPipeOptions} [options]
+     * @throws {Error} `[CLIPipeProvider] requires command` — when options.command is missing.
+     */
+    constructor(options?: CLIPipeOptions);
+    command: string;
+    args: string[];
+    cwd: string | undefined;
+    env: Record<string, string> | undefined;
+    timeout: number;
+    systemPromptFlag: string | null;
+    onChunk: ((chunk: string) => void) | null;
+    /**
+     * Generate a response by piping messages to the CLI command.
+     * @param {Message[]} messages - Conversation messages in OpenAI format.
+     * @param {ToolDef[]} [tools=[]] - Unused (CLI commands don't support tools).
+     * @param {Record<string, any>} [options={}] - Unused.
+     * @returns {Promise<GenerateResult>}
+     * @throws {Error} `[CLIPipeProvider] failed to spawn "cmd": ...` — when the command cannot be found or executed.
+     * @throws {Error} `[CLIPipeProvider] process exited with code N: ...` — on non-zero exit.
+     * @throws {Error} `[CLIPipeProvider] timed out after Nms` — when the process exceeds timeout.
+     * @throws {Error} `[CLIPipeProvider] process produced no output` — when stdout is empty.
+     */
+    generate(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
+    /**
+     * Convert OpenAI-format messages to a plain text prompt.
+     * @param {Message[]} messages
+     * @returns {string}
+     */
+    _formatPrompt(messages: Message[]): string;
+    /**
+     * Spawn the CLI process, pipe prompt to stdin, collect stdout.
+     * @param {string} prompt
+     * @param {string[]} [extraArgs=[]] - Additional args appended after this.args.
+     * @returns {Promise<string>}
+     */
+    _spawn(prompt: string, extraArgs?: string[]): Promise<string>;
+}

package/src/provider-clipipe.js

@@ -3,16 +3,25 @@
 const { spawn } = require('child_process');
 const { ProviderError } = require('./errors');
 
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+
+/**
+ * @typedef {object} CLIPipeOptions
+ * @property {string} [command] - CLI command to spawn (required).
+ * @property {string[]} [args=[]] - Arguments to pass to the command.
+ * @property {string} [cwd] - Working directory for the child process.
+ * @property {Record<string, string>} [env] - Environment variables for the child process.
+ * @property {number} [timeout=30000] - Timeout in milliseconds.
+ * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
+ * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
+ */
+
 class CLIPipeProvider {
   /**
    * Provider that pipes prompts to a CLI command via stdin and reads stdout.
-   * @param {object} options
-   * @param {string} options.command - CLI command to spawn (required).
-   * @param {string[]} [options.args=[]] - Arguments to pass to the command.
-   * @param {string} [options.cwd] - Working directory for the child process.
-   * @param {object} [options.env] - Environment variables for the child process.
-   * @param {number} [options.timeout=30000] - Timeout in milliseconds.
-   * @param {string} [options.systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
+   * @param {CLIPipeOptions} [options]
    * @throws {Error} `[CLIPipeProvider] requires command` — when options.command is missing.
    */
   constructor(options = {}) {
@@ -28,16 +37,17 @@ class CLIPipeProvider {
 
   /**
    * Generate a response by piping messages to the CLI command.
-   * @param {Array<object>} messages - Conversation messages in OpenAI format.
-   * @param {Array<object>} [tools=[]] - Unused (CLI commands don't support tools).
-   * @param {object} [options={}] - Unused.
-   * @returns {Promise<{text: string, toolCalls: Array, usage: object}>}
+   * @param {Message[]} messages - Conversation messages in OpenAI format.
+   * @param {ToolDef[]} [tools=[]] - Unused (CLI commands don't support tools).
+   * @param {Record<string, any>} [options={}] - Unused.
+   * @returns {Promise<GenerateResult>}
    * @throws {Error} `[CLIPipeProvider] failed to spawn "cmd": ...` — when the command cannot be found or executed.
    * @throws {Error} `[CLIPipeProvider] process exited with code N: ...` — on non-zero exit.
    * @throws {Error} `[CLIPipeProvider] timed out after Nms` — when the process exceeds timeout.
    * @throws {Error} `[CLIPipeProvider] process produced no output` — when stdout is empty.
    */
   async generate(messages, tools = [], options = {}) {
+    /** @type {string[]} */
     let extraArgs = [];
     let promptMessages = messages;
 
@@ -61,7 +71,7 @@ class CLIPipeProvider {
 
   /**
    * Convert OpenAI-format messages to a plain text prompt.
-   * @param {Array<object>} messages
+   * @param {Message[]} messages
    * @returns {string}
    */
   _formatPrompt(messages) {
@@ -79,11 +89,11 @@ class CLIPipeProvider {
    */
   _spawn(prompt, extraArgs = []) {
     return new Promise((resolve, reject) => {
-      const child = spawn(this.command, [...this.args, ...extraArgs], {
+      const child = spawn(this.command, [...this.args, ...extraArgs], /** @type {any} */ ({
         cwd: this.cwd,
         env: this.env,
         stdio: ['pipe', 'pipe', 'pipe'],
-      });
+      }));
 
       let stdout = '';
       let stderr = '';
@@ -93,17 +103,17 @@ class CLIPipeProvider {
       child.stderr.on('data', d => { stderr += d; });
 
       child.on('error', err => {
-        reject(new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${err.message}`, { status: 0 }));
+        reject(new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${err.message}`, /** @type {any} */ ({ status: 0 })));
       });
 
       child.on('close', code => {
         if (killed) return; // timeout already rejected
         if (code !== 0) {
-          return reject(new ProviderError(`[CLIPipeProvider] process exited with code ${code}: ${stderr.trim()}`, { status: code }));
+          return reject(new ProviderError(`[CLIPipeProvider] process exited with code ${code}: ${stderr.trim()}`, /** @type {any} */ ({ status: code })));
         }
         const text = stdout.trim();
         if (!text) {
-          return reject(new ProviderError('[CLIPipeProvider] process produced no output', { status: 0 }));
+          return reject(new ProviderError('[CLIPipeProvider] process produced no output', /** @type {any} */ ({ status: 0 })));
         }
         resolve(text);
       });
@@ -115,7 +125,7 @@ class CLIPipeProvider {
         setTimeout(() => {
           try { child.kill('SIGKILL'); } catch (_) {}
         }, 1000);
-        reject(new ProviderError(`[CLIPipeProvider] timed out after ${this.timeout}ms`, { status: 0 }));
+        reject(new ProviderError(`[CLIPipeProvider] timed out after ${this.timeout}ms`, /** @type {any} */ ({ status: 0 })));
       }, this.timeout);
 
       child.on('close', () => clearTimeout(timer));

package/src/provider-fallback.d.ts

@@ -0,0 +1,44 @@
+export type Provider = import("../types").Provider;
+export type Message = import("../types").Message;
+export type ToolDef = import("../types").ToolDef;
+export type GenerateResult = import("../types").GenerateResult;
+export type FallbackOptions = {
+    /**
+     * - Return false to stop.
+     */
+    shouldFallback?: ((error: any, index: number) => boolean) | undefined;
+    /**
+     * - Callback.
+     */
+    onFallback?: ((error: any, fromIndex: number, toIndex: number) => void) | undefined;
+};
+/** @typedef {import('../types').Provider} Provider */
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+/**
+ * @typedef {object} FallbackOptions
+ * @property {(error: any, index: number) => boolean} [shouldFallback] - Return false to stop.
+ * @property {(error: any, fromIndex: number, toIndex: number) => void} [onFallback] - Callback.
+ */
+export class FallbackProvider {
+    /**
+     * Provider that tries multiple providers in order.
+     * @param {Provider[]} providers - Ordered list of providers with generate().
+     * @param {FallbackOptions} [options={}]
+     * @throws {Error} `[FallbackProvider] requires at least one provider` — when providers is empty.
+     */
+    constructor(providers: Provider[], options?: FallbackOptions);
+    providers: import("../types").Provider[];
+    shouldFallback: (error: any, index: number) => boolean;
+    onFallback: ((error: any, fromIndex: number, toIndex: number) => void) | null;
+    /**
+     * Generate using first available provider.
+     * @param {Message[]} messages
+     * @param {ToolDef[]} [tools=[]]
+     * @param {Record<string, any>} [options={}]
+     * @returns {Promise<GenerateResult>}
+     * @throws {AggregateError} When all providers fail.
+     */
+    generate(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
+}

package/src/provider-fallback.js

@@ -1,12 +1,21 @@
 'use strict';
 
+/** @typedef {import('../types').Provider} Provider */
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+
+/**
+ * @typedef {object} FallbackOptions
+ * @property {(error: any, index: number) => boolean} [shouldFallback] - Return false to stop.
+ * @property {(error: any, fromIndex: number, toIndex: number) => void} [onFallback] - Callback.
+ */
+
 class FallbackProvider {
   /**
    * Provider that tries multiple providers in order.
-   * @param {Array<object>} providers - Ordered list of providers with generate().
-   * @param {object} [options={}]
-   * @param {function} [options.shouldFallback] - (error, index) => boolean. Return false to stop.
-   * @param {function} [options.onFallback] - (error, fromIndex, toIndex) callback.
+   * @param {Provider[]} providers - Ordered list of providers with generate().
+   * @param {FallbackOptions} [options={}]
    * @throws {Error} `[FallbackProvider] requires at least one provider` — when providers is empty.
    */
   constructor(providers, options = {}) {
@@ -20,13 +29,14 @@ class FallbackProvider {
 
   /**
    * Generate using first available provider.
-   * @param {Array<object>} messages
-   * @param {Array<object>} [tools=[]]
-   * @param {object} [options={}]
-   * @returns {Promise<{text: string, toolCalls: Array, usage: object}>}
+   * @param {Message[]} messages
+   * @param {ToolDef[]} [tools=[]]
+   * @param {Record<string, any>} [options={}]
+   * @returns {Promise<GenerateResult>}
    * @throws {AggregateError} When all providers fail.
    */
   async generate(messages, tools = [], options = {}) {
+    /** @type {any[]} */
     const errors = [];
 
     for (let i = 0; i < this.providers.length; i++) {

package/src/provider-ollama.d.ts

@@ -0,0 +1,41 @@
+export type Message = import("../types").Message;
+export type ToolDef = import("../types").ToolDef;
+export type GenerateResult = import("../types").GenerateResult;
+export type OllamaOptions = {
+    model?: string | undefined;
+    url?: string | undefined;
+    exposeErrorBody?: boolean | undefined;
+};
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+/**
+ * @typedef {object} OllamaOptions
+ * @property {string} [model='llama3.2']
+ * @property {string} [url='http://localhost:11434']
+ * @property {boolean} [exposeErrorBody=false]
+ */
+export class OllamaProvider {
+    /**
+     * @param {OllamaOptions} [options]
+     */
+    constructor(options?: OllamaOptions);
+    model: string;
+    url: string;
+    exposeErrorBody: boolean;
+    /**
+     * Generate a response from a local Ollama instance.
+     * @param {Message[]} messages - Conversation messages.
+     * @param {ToolDef[]} [tools=[]] - Tool definitions.
+     * @param {Record<string, any>} [options={}] - Options (temperature).
+     * @returns {Promise<GenerateResult>}
+     * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
+     */
+    generate(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
+    /**
+     * @param {string} path
+     * @param {Record<string, any>} body
+     * @returns {Promise<any>}
+     */
+    _request(path: string, body: Record<string, any>): Promise<any>;
+}