bare-agent 0.33.1 → 0.34.0

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.33.1 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
+> v0.34.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -829,6 +829,8 @@ All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model?, cos
 
 **Error body (v0.11.0):** on an HTTP error the OpenAI/Anthropic/Ollama providers throw a `ProviderError` whose `message` carries the upstream error string. The full parsed response is **not** attached to `err.body` by default (so an unexpected field can't leak through logs that dump the error object). Pass `{ exposeErrorBody: true }` to attach it for debugging.
 
+**Request/idle timeout (BA-18, v0.34.0):** the four http(s) providers (Anthropic, OpenAI, Gemini, Ollama) accept a `timeoutMs` option — constructor default **600000 (10 min)**, overridable per call via `generate(..., { timeoutMs })`, and `0`/`Infinity` disables it. Before this they wired only `req.on('error')`, so a socket the server silently dropped — or a response that never starts — hung `generate()` until the OS TCP timeout (~2h): a hang, not an error, so retry/casualty policy above it never fired. `timeoutMs` bounds on socket **inactivity** (`req.setTimeout`), so a slow-but-streaming response is not killed — only a silent/never-answering socket trips it; the 10-min default clears any single non-streaming completion (TTFB ≈ generation time). On trip, `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`, `retryable: true`). **Retry is caller-side and already wired:** `new Loop({ provider, retry: new Retry() })` wraps `provider.generate`, and `DEFAULT_RETRY_ON` classifies `ETIMEDOUT` (and `ECONNRESET`/`ENOTFOUND`/429/5xx) as transient — so a wired `Retry` retries a timed-out request and rethrows under `retryOn: () => false`, with no extra wiring (`run-plan`'s `stepRetry` is a second consumer of the same seam). CLIPipe already bounded its child process (`timeout`, default 30000 for one-shot) and is unchanged.
+
 **Plaintext-key warning (Unreleased):** the OpenAI provider's `baseUrl` accepts `http://` (for local/OpenAI-compatible endpoints), but a `Bearer` key sent over plaintext http to a **non-loopback** host is exposed on the wire. The provider now warns once when that happens. Loopback hosts (`localhost`/`127.0.0.0/8`/`::1` — local proxies, Ollama-style endpoints) stay silent, since that's the legitimate keyless-local case. The header is **not** stripped (some local proxies want a key), so use `https` for any remote endpoint, or drop `apiKey` when the local endpoint needs none.
 
 **Cost estimation:** Loop automatically estimates USD cost per run based on model and token usage. The `cost` field appears in every `loop.run()` result and in `loop:done` stream events. Pricing covers OpenAI and Anthropic models; unknown models use a default average. To adjust rates, edit `COST_PER_1K` at the top of `src/loop.js`. The model is resolved as `result.model || provider.model` (v0.16.1+) — providers now echo the model in their `generate()` result, so cost accounting holds even when `provider.model` is absent or varies per response, e.g. behind `FallbackProvider` or `CircuitBreaker.wrapProvider` (the wrapper also preserves `model`/`name` passthrough props). Wire `onLlmResult` (via `wireGate`) and a `budget.maxCostUsd` cap then halts on token-heavy workloads too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "files": [
     "index.js",
     "index.d.ts",

package/src/provider-anthropic.d.ts

@@ -32,6 +32,10 @@ export type AnthropicOptions = {
      * - 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;
+    /**
+     * - BA-18: request/idle timeout in ms. A silent or never-answering socket (dropped by the server, or a response that never starts) was otherwise bounded only by the OS TCP timeout (~2h) — a hang, not an error, so every retry policy above it was inert. Bounds on socket INACTIVITY (the timer resets on activity, so a slow-but-streaming response is not killed); on trip, `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) that a wired `Retry` (`Loop({ retry })`) retries. Default 10 min sits above any single non-streaming completion; `0` or `Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+     */
+    timeoutMs?: number | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -47,6 +51,7 @@ export type AnthropicOptions = {
  *
  *   **MEASURED CAVEAT — this option does not "turn thinking on".** On `claude-sonnet-5` adaptive thinking is ALREADY the default: sending this changed the observed thinking rate not at all (2/10 rounds with it vs 3/10 without — `poc/ba7-adaptive-default.mjs`). Its real use is pinning the mode and reaching `display`/`effort`. The change that mattered is that thinking blocks are now PRESERVED and replayed (see `Message.providerBlocks`), which happens whether or not you ever set this.
  * @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).
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. A silent or never-answering socket (dropped by the server, or a response that never starts) was otherwise bounded only by the OS TCP timeout (~2h) — a hang, not an error, so every retry policy above it was inert. Bounds on socket INACTIVITY (the timer resets on activity, so a slow-but-streaming response is not killed); on trip, `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) that a wired `Retry` (`Loop({ retry })`) retries. Default 10 min sits above any single non-streaming completion; `0` or `Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 export class AnthropicProvider {
     /**
@@ -61,11 +66,12 @@ export class AnthropicProvider {
     cacheMessages: boolean;
     thinking: any;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
     /**
      * 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).
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, system, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[AnthropicProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
@@ -94,8 +100,9 @@ export class AnthropicProvider {
     _toAnthropicMessage(msg: Message): any;
     /**
      * @param {Record<string, any>} body
+     * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(body: Record<string, any>): Promise<any>;
+    _request(body: Record<string, any>, timeoutMs?: number): Promise<any>;
     _warnedInsecure: boolean | undefined;
 }

package/src/provider-anthropic.js

@@ -5,6 +5,7 @@ const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
+const { resolveTimeoutMs, applyRequestTimeout } = require('./provider-http');
 
 /** @param {string} hostname @returns {boolean} */
 function isLoopbackHost(hostname) {
@@ -27,6 +28,7 @@ function isLoopbackHost(hostname) {
  *
  *   **MEASURED CAVEAT — this option does not "turn thinking on".** On `claude-sonnet-5` adaptive thinking is ALREADY the default: sending this changed the observed thinking rate not at all (2/10 rounds with it vs 3/10 without — `poc/ba7-adaptive-default.mjs`). Its real use is pinning the mode and reaching `display`/`effort`. The change that mattered is that thinking blocks are now PRESERVED and replayed (see `Message.providerBlocks`), which happens whether or not you ever set this.
  * @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).
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. A silent or never-answering socket (dropped by the server, or a response that never starts) was otherwise bounded only by the OS TCP timeout (~2h) — a hang, not an error, so every retry policy above it was inert. Bounds on socket INACTIVITY (the timer resets on activity, so a slow-but-streaming response is not killed); on trip, `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) that a wired `Retry` (`Loop({ retry })`) retries. Default 10 min sits above any single non-streaming completion; `0` or `Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 
 class AnthropicProvider {
@@ -52,13 +54,15 @@ class AnthropicProvider {
     this.thinking = options.thinking != null ? options.thinking : null;
     // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
     this.exposeErrorBody = options.exposeErrorBody === true;
+    // BA-18: request/idle timeout (ms). Resolved at call time (default 600000; 0/Infinity disable).
+    this.timeoutMs = options.timeoutMs;
   }
 
   /**
    * 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).
+   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, system, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[AnthropicProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
@@ -142,8 +146,9 @@ class AnthropicProvider {
     // BA-10: some models (e.g. claude-sonnet-5) reject a non-default `temperature` with a 400 — drop it
     // and retry once rather than let the whole call fail. `temperatureDropped` flows back so an upstream
     // receipt (recurse's refineLeaf) can report the effective temperature, not the one the model ignored.
+    const timeoutMs = resolveTimeoutMs(this.timeoutMs, options.timeoutMs);
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request(body),
+      request: () => this._request(body, timeoutMs),
       hadTemperature: () => body.temperature != null,
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -275,9 +280,10 @@ class AnthropicProvider {
 
   /**
    * @param {Record<string, any>} body
+   * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(body) {
+  _request(body, timeoutMs = 0) {
     return new Promise((resolve, reject) => {
       const payload = JSON.stringify(body);
       const url = new URL(this.baseUrl + '/messages');
@@ -314,6 +320,7 @@ class AnthropicProvider {
           }
         });
       });
+      applyRequestTimeout(req, timeoutMs, 'AnthropicProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-gemini.d.ts

@@ -19,6 +19,10 @@ export type GeminiOptions = {
      * - Attach the full upstream response to `err.body` on HTTP errors (off by default; `err.message` still carries the API error).
      */
     exposeErrorBody?: boolean | undefined;
+    /**
+     * - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+     */
+    timeoutMs?: number | undefined;
 };
 /**
  * @typedef {object} GeminiOptions
@@ -26,6 +30,7 @@ export type GeminiOptions = {
  * @property {string} [model='gemini-2.5-flash'] - Model ID.
  * @property {string} [baseUrl='https://generativelanguage.googleapis.com/v1beta'] - API base (override for proxies; posts to `${baseUrl}/models/${model}:generateContent`).
  * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default; `err.message` still carries the API error).
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 /**
  * Google Gemini provider (native `generateContent` API, NOT the OpenAI-compat endpoint — that endpoint
@@ -41,11 +46,12 @@ export class GeminiProvider {
     model: string;
     baseUrl: string;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
     /**
      * Generate a response from the Gemini API.
      * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
-     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[GeminiProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
@@ -66,8 +72,9 @@ export class GeminiProvider {
     /**
      * @param {string} path
      * @param {Record<string, any>} body
+     * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(path: string, body: Record<string, any>): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number): Promise<any>;
     _warnedInsecure: boolean | undefined;
 }

package/src/provider-gemini.js

@@ -5,6 +5,7 @@ const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
+const { resolveTimeoutMs, applyRequestTimeout } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -23,6 +24,7 @@ function isLoopbackHost(hostname) {
  * @property {string} [model='gemini-2.5-flash'] - Model ID.
  * @property {string} [baseUrl='https://generativelanguage.googleapis.com/v1beta'] - API base (override for proxies; posts to `${baseUrl}/models/${model}:generateContent`).
  * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default; `err.message` still carries the API error).
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 
 /**
@@ -39,13 +41,15 @@ class GeminiProvider {
     this.model = options.model || 'gemini-2.5-flash';
     this.baseUrl = options.baseUrl || 'https://generativelanguage.googleapis.com/v1beta';
     this.exposeErrorBody = options.exposeErrorBody === true;
+    // BA-18: request/idle timeout (ms). Resolved at call time (default 600000; 0/Infinity disable).
+    this.timeoutMs = options.timeoutMs;
   }
 
   /**
    * Generate a response from the Gemini API.
    * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
-   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[GeminiProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
@@ -107,8 +111,9 @@ class GeminiProvider {
 
     // BA-10: graceful degrade if a model rejects a non-default `temperature` (Gemini nests it under
     // generationConfig). Keyed off the API error text, so dormant on models that accept temperature.
+    const timeoutMs = resolveTimeoutMs(this.timeoutMs, options.timeoutMs);
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request(`/models/${this.model}:generateContent`, body),
+      request: () => this._request(`/models/${this.model}:generateContent`, body, timeoutMs),
       hadTemperature: () => body.generationConfig?.temperature != null,
       stripTemperature: () => { if (body.generationConfig) delete body.generationConfig.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -174,9 +179,10 @@ class GeminiProvider {
   /**
    * @param {string} path
    * @param {Record<string, any>} body
+   * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body) {
+  _request(path, body, timeoutMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.baseUrl + path);
       const transport = url.protocol === 'https:' ? https : http;
@@ -213,6 +219,7 @@ class GeminiProvider {
           }
         });
       });
+      applyRequestTimeout(req, timeoutMs, 'GeminiProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-http.d.ts

@@ -0,0 +1,34 @@
+/**
+ * BA-18 — shared request-timeout helper for the http(s)-based providers (Anthropic, OpenAI,
+ * Gemini, Ollama). They all build a `http.ClientRequest` with only `req.on('error')` wired, so a
+ * socket the server silently dropped — or a response that never starts — was bounded only by the
+ * OS TCP timeout (~2h on Linux). That presents to the caller as a hang, not a failure, so every
+ * retry/casualty policy above it is inert. This adds a finite, configurable idle bound in one
+ * place so the four providers cannot drift.
+ */
+export const DEFAULT_TIMEOUT_MS: 600000;
+/**
+ * Resolve the effective timeout in ms. A per-call value overrides the instance default, but `null`
+ * and `undefined` BOTH mean "inherit" — so a per-call `null` never shadows an instance-level
+ * disable (finding-2). The explicit opt-out idiom is `0` or `Infinity` → returns 0 (no bound, the
+ * pre-BA-18 behaviour). A NaN / negative / otherwise non-finite value is treated as a caller
+ * MISTAKE and falls back to {@link DEFAULT_TIMEOUT_MS}: it must never silently disable the safety
+ * bound, which would round optimistically back toward the ~2h hang BA-18 exists to prevent
+ * (finding-3; the disable-edge bug class).
+ * @param {number|undefined|null} instanceTimeout
+ * @param {number|undefined|null} [callTimeout]
+ * @returns {number} a finite positive ms bound, or 0 to disable
+ */
+export function resolveTimeoutMs(instanceTimeout: number | undefined | null, callTimeout?: number | undefined | null): number;
+/**
+ * Bound an in-flight ClientRequest on socket INACTIVITY. On timeout, destroy the request with a
+ * retryable {@link TimeoutError} (`code: 'ETIMEDOUT'`) — `DEFAULT_RETRY_ON` classifies that as
+ * transient, and the provider's own `req.on('error', reject)` turns it into a rejected promise, so
+ * the caller regains control instead of hanging. Idle semantics (via `req.setTimeout`): the timer
+ * resets on any socket activity, so a slow-but-streaming response is NOT killed — only a silent or
+ * never-answering socket trips it. A `timeoutMs` of 0 is a no-op (bound disabled).
+ * @param {import('http').ClientRequest} req
+ * @param {number} timeoutMs - resolved bound; 0 disables
+ * @param {string} providerName - for the error message (e.g. 'AnthropicProvider')
+ */
+export function applyRequestTimeout(req: import("http").ClientRequest, timeoutMs: number, providerName: string): void;

package/src/provider-http.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { TimeoutError } = require('./errors');
+
+/**
+ * BA-18 — shared request-timeout helper for the http(s)-based providers (Anthropic, OpenAI,
+ * Gemini, Ollama). They all build a `http.ClientRequest` with only `req.on('error')` wired, so a
+ * socket the server silently dropped — or a response that never starts — was bounded only by the
+ * OS TCP timeout (~2h on Linux). That presents to the caller as a hang, not a failure, so every
+ * retry/casualty policy above it is inert. This adds a finite, configurable idle bound in one
+ * place so the four providers cannot drift.
+ */
+
+// 10 minutes: safely above any single non-streaming completion (a big reasoning response is a few
+// minutes at most), well below the ~2h OS TCP default. These requests are non-streaming, so a legit
+// slow completion can have no socket activity until the whole body arrives (TTFB ≈ generation time)
+// — the default must clear that, not a typical round-trip.
+const DEFAULT_TIMEOUT_MS = 600000;
+
+/**
+ * Resolve the effective timeout in ms. A per-call value overrides the instance default, but `null`
+ * and `undefined` BOTH mean "inherit" — so a per-call `null` never shadows an instance-level
+ * disable (finding-2). The explicit opt-out idiom is `0` or `Infinity` → returns 0 (no bound, the
+ * pre-BA-18 behaviour). A NaN / negative / otherwise non-finite value is treated as a caller
+ * MISTAKE and falls back to {@link DEFAULT_TIMEOUT_MS}: it must never silently disable the safety
+ * bound, which would round optimistically back toward the ~2h hang BA-18 exists to prevent
+ * (finding-3; the disable-edge bug class).
+ * @param {number|undefined|null} instanceTimeout
+ * @param {number|undefined|null} [callTimeout]
+ * @returns {number} a finite positive ms bound, or 0 to disable
+ */
+function resolveTimeoutMs(instanceTimeout, callTimeout) {
+  const raw = callTimeout != null ? callTimeout : instanceTimeout; // null/undefined per-call → inherit
+  if (raw == null) return DEFAULT_TIMEOUT_MS;    // absent on both → finite default
+  const n = Number(raw);
+  if (n === 0 || n === Infinity) return 0;       // the explicit opt-out idiom → no bound
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_TIMEOUT_MS; // NaN / negative / garbage → SAFE default, never a silent disable
+  return n;                                      // finite positive bound
+}
+
+/**
+ * Bound an in-flight ClientRequest on socket INACTIVITY. On timeout, destroy the request with a
+ * retryable {@link TimeoutError} (`code: 'ETIMEDOUT'`) — `DEFAULT_RETRY_ON` classifies that as
+ * transient, and the provider's own `req.on('error', reject)` turns it into a rejected promise, so
+ * the caller regains control instead of hanging. Idle semantics (via `req.setTimeout`): the timer
+ * resets on any socket activity, so a slow-but-streaming response is NOT killed — only a silent or
+ * never-answering socket trips it. A `timeoutMs` of 0 is a no-op (bound disabled).
+ * @param {import('http').ClientRequest} req
+ * @param {number} timeoutMs - resolved bound; 0 disables
+ * @param {string} providerName - for the error message (e.g. 'AnthropicProvider')
+ */
+function applyRequestTimeout(req, timeoutMs, providerName) {
+  if (!(timeoutMs > 0)) return;
+  req.setTimeout(timeoutMs, () => {
+    req.destroy(new TimeoutError(`[${providerName}] request timed out after ${timeoutMs}ms of socket inactivity`));
+  });
+}
+
+module.exports = { DEFAULT_TIMEOUT_MS, resolveTimeoutMs, applyRequestTimeout };

package/src/provider-ollama.d.ts

@@ -5,6 +5,10 @@ export type OllamaOptions = {
     model?: string | undefined;
     url?: string | undefined;
     exposeErrorBody?: boolean | undefined;
+    /**
+     * - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout. `0`/`Infinity` disables it. Overridable per call via `generate(..., { timeoutMs })`. (A local Ollama that is loading a large model cold can be slow to first byte — raise this or disable it for very large local models.)
+     */
+    timeoutMs?: number | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -14,6 +18,7 @@ export type OllamaOptions = {
  * @property {string} [model='llama3.2']
  * @property {string} [url='http://localhost:11434']
  * @property {boolean} [exposeErrorBody=false]
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout. `0`/`Infinity` disables it. Overridable per call via `generate(..., { timeoutMs })`. (A local Ollama that is loading a large model cold can be slow to first byte — raise this or disable it for very large local models.)
  */
 export class OllamaProvider {
     /**
@@ -23,11 +28,12 @@ export class OllamaProvider {
     model: string;
     url: string;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
     /**
      * 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`, `maxTokens`).
+     * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`, `timeoutMs` — a per-call override of the constructor's `timeoutMs`; see BA-18).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
      */
@@ -38,7 +44,8 @@ export class OllamaProvider {
     /**
      * @param {string} path
      * @param {Record<string, any>} body
+     * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(path: string, body: Record<string, any>): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number): Promise<any>;
 }

package/src/provider-ollama.js

@@ -4,6 +4,7 @@ const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
+const { resolveTimeoutMs, applyRequestTimeout } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -14,6 +15,7 @@ const { normalizeStopReason } = require('./provider-stop-reason');
  * @property {string} [model='llama3.2']
  * @property {string} [url='http://localhost:11434']
  * @property {boolean} [exposeErrorBody=false]
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout. `0`/`Infinity` disables it. Overridable per call via `generate(..., { timeoutMs })`. (A local Ollama that is loading a large model cold can be slow to first byte — raise this or disable it for very large local models.)
  */
 
 class OllamaProvider {
@@ -25,13 +27,15 @@ class OllamaProvider {
     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;
+    // BA-18: request/idle timeout (ms). Resolved at call time (default 600000; 0/Infinity disable).
+    this.timeoutMs = options.timeoutMs;
   }
 
   /**
    * 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`, `maxTokens`).
+   * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`, `timeoutMs` — a per-call override of the constructor's `timeoutMs`; see BA-18).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
    */
@@ -64,8 +68,9 @@ class OllamaProvider {
 
     // BA-10: graceful degrade if a model rejects a non-default `temperature` (Ollama nests it under
     // `options`). Keyed off the API error text, so dormant on models that accept temperature.
+    const timeoutMs = resolveTimeoutMs(this.timeoutMs, options.timeoutMs);
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request('/api/chat', body),
+      request: () => this._request('/api/chat', body, timeoutMs),
       hadTemperature: () => body.options?.temperature != null,
       stripTemperature: () => { if (body.options) delete body.options.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -110,9 +115,10 @@ class OllamaProvider {
   /**
    * @param {string} path
    * @param {Record<string, any>} body
+   * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body) {
+  _request(path, body, timeoutMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.url + path);
       const payload = JSON.stringify(body);
@@ -141,6 +147,7 @@ class OllamaProvider {
           }
         });
       });
+      applyRequestTimeout(req, timeoutMs, 'OllamaProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-openai.d.ts

@@ -14,6 +14,13 @@ export type OpenAIOptions = {
      * debugging only.
      */
     exposeErrorBody?: boolean | undefined;
+    /**
+     * - BA-18: request/idle timeout in ms. Bounds a silent or
+     * never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError`
+     * (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity`
+     * disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+     */
+    timeoutMs?: number | undefined;
 };
 /**
  * @typedef {object} OpenAIOptions
@@ -25,6 +32,10 @@ export type OpenAIOptions = {
  *   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.
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or
+ *   never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError`
+ *   (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity`
+ *   disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 export class OpenAIProvider {
     /**
@@ -35,11 +46,12 @@ export class OpenAIProvider {
     model: string;
     baseUrl: string;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
     /**
      * 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).
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
@@ -60,8 +72,9 @@ export class OpenAIProvider {
     /**
      * @param {string} path
      * @param {Record<string, any>} body
+     * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(path: string, body: Record<string, any>): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number): Promise<any>;
     _warnedInsecure: boolean | undefined;
 }

package/src/provider-openai.js

@@ -5,6 +5,7 @@ const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
+const { resolveTimeoutMs, applyRequestTimeout } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -27,6 +28,10 @@ function isLoopbackHost(hostname) {
  *   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.
+ * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or
+ *   never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError`
+ *   (`code: 'ETIMEDOUT'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity`
+ *   disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
  */
 
 class OpenAIProvider {
@@ -38,13 +43,15 @@ class OpenAIProvider {
     this.model = options.model || 'gpt-4o-mini';
     this.baseUrl = options.baseUrl || 'https://api.openai.com/v1';
     this.exposeErrorBody = options.exposeErrorBody === true;
+    // BA-18: request/idle timeout (ms). Resolved at call time (default 600000; 0/Infinity disable).
+    this.timeoutMs = options.timeoutMs;
   }
 
   /**
    * 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).
+   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
@@ -65,8 +72,9 @@ class OpenAIProvider {
 
     // BA-10: newer models (o1/gpt-5-class) reject a non-default `temperature` with a 400 — drop it and
     // retry once. `temperatureDropped` flows back so an upstream receipt can report the effective value.
+    const timeoutMs = resolveTimeoutMs(this.timeoutMs, options.timeoutMs);
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request('/chat/completions', body),
+      request: () => this._request('/chat/completions', body, timeoutMs),
       hadTemperature: () => body.temperature != null,
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -124,9 +132,10 @@ class OpenAIProvider {
   /**
    * @param {string} path
    * @param {Record<string, any>} body
+   * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body) {
+  _request(path, body, timeoutMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.baseUrl + path);
       const transport = url.protocol === 'https:' ? https : http;
@@ -168,6 +177,7 @@ class OpenAIProvider {
           }
         });
       });
+      applyRequestTimeout(req, timeoutMs, 'OpenAIProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();