bare-agent 0.10.4 → 0.12.0

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,30 +3,43 @@
 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 {AnthropicOptions} [options]
    * @throws {Error} `[AnthropicProvider] requires apiKey` — when apiKey is missing.
    */
   constructor(options = {}) {
     if (!options.apiKey) throw new Error('[AnthropicProvider] requires apiKey');
     this.apiKey = options.apiKey.trim();
     this.model = options.model || 'claude-haiku-4-5-20251001';
+    // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
+    this.exposeErrorBody = options.exposeErrorBody === true;
   }
 
   /**
    * 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') {
@@ -39,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,
@@ -57,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;
@@ -75,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') {
@@ -88,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) {
@@ -106,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);
@@ -123,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: parsed }
+                /** @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>;
+}

package/src/provider-ollama.js

@@ -3,21 +3,38 @@
 const http = require('http');
 const { ProviderError } = require('./errors');
 
+/** @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]
+ */
+
 class OllamaProvider {
+  /**
+   * @param {OllamaOptions} [options]
+   */
   constructor(options = {}) {
     this.model = options.model || 'llama3.2';
     this.url = options.url || 'http://localhost:11434';
+    // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
+    this.exposeErrorBody = options.exposeErrorBody === true;
   }
 
   /**
    * Generate a response from a local Ollama instance.
-   * @param {Array<object>} messages - Conversation messages.
-   * @param {Array<object>} [tools=[]] - Tool definitions.
-   * @param {object} [options={}] - Options (temperature).
-   * @returns {Promise<{text: string, toolCalls: Array, usage: object}>}
+   * @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.
    */
   async generate(messages, tools = [], options = {}) {
+    /** @type {Record<string, any>} */
     const body = {
       model: this.model,
       messages,
@@ -36,7 +53,7 @@ class OllamaProvider {
 
     return {
       text: msg.content || '',
-      toolCalls: (msg.tool_calls || []).map(tc => ({
+      toolCalls: (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
         id: tc.id || `call_${Date.now()}`,
         name: tc.function.name,
         arguments: typeof tc.function.arguments === 'string'
@@ -50,6 +67,11 @@ class OllamaProvider {
     };
   }
 
+  /**
+   * @param {string} path
+   * @param {Record<string, any>} body
+   * @returns {Promise<any>}
+   */
   _request(path, body) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.url + path);
@@ -67,10 +89,10 @@ class OllamaProvider {
         res.on('end', () => {
           try {
             const parsed = JSON.parse(chunks);
-            if (res.statusCode >= 400) {
+            if ((res.statusCode ?? 0) >= 400) {
               return reject(new ProviderError(
                 `[OllamaProvider] ${parsed.error || `HTTP ${res.statusCode}`}`,
-                { status: res.statusCode, body: parsed }
+                /** @type {any} */ ({ status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined })
               ));
             }
             resolve(parsed);

package/src/provider-openai.d.ts

@@ -0,0 +1,57 @@
+export type Message = import("../types").Message;
+export type ToolDef = import("../types").ToolDef;
+export type ToolCall = import("../types").ToolCall;
+export type GenerateResult = import("../types").GenerateResult;
+export type OpenAIOptions = {
+    apiKey?: string | undefined;
+    model?: string | undefined;
+    baseUrl?: string | undefined;
+    /**
+     * - Attach the full upstream
+     * response to `err.body` on HTTP errors. Off by default so an unexpected
+     * field in an error payload can't leak through logs that dump the error
+     * object; `err.message` still carries the API's error message. Turn on for
+     * debugging only.
+     */
+    exposeErrorBody?: boolean | undefined;
+};
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').ToolCall} ToolCall */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+/**
+ * @typedef {object} OpenAIOptions
+ * @property {string} [apiKey]
+ * @property {string} [model='gpt-4o-mini']
+ * @property {string} [baseUrl='https://api.openai.com/v1']
+ * @property {boolean} [exposeErrorBody=false] - Attach the full upstream
+ *   response to `err.body` on HTTP errors. Off by default so an unexpected
+ *   field in an error payload can't leak through logs that dump the error
+ *   object; `err.message` still carries the API's error message. Turn on for
+ *   debugging only.
+ */
+export class OpenAIProvider {
+    /**
+     * @param {OpenAIOptions} [options]
+     */
+    constructor(options?: OpenAIOptions);
+    apiKey: string | undefined;
+    model: string;
+    baseUrl: string;
+    exposeErrorBody: boolean;
+    /**
+     * Generate a response from the OpenAI API.
+     * @param {Message[]} messages - Conversation messages.
+     * @param {ToolDef[]} [tools=[]] - Tool definitions.
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+     * @returns {Promise<GenerateResult>}
+     * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) 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>;
+}