bare-agent 0.33.1 → 0.35.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.35.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,10 @@ 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'`, `context.bound: 'idle'`, `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.
+
+**Total call-duration deadline (BA-19, v0.35.0):** `timeoutMs` bounds socket *inactivity*, and `req.setTimeout` resets on any activity by design — so a "zombie stream" that trickles a byte forever (bytes arriving, the response never completing) never trips it and hangs the caller for hours (an adopter saw one `generate()` run **274 min** and end in `ECONNRESET`, not a `TimeoutError`: the reset proves bytes *were* flowing, so the idle timer never fired). The four http(s) providers now also accept a `deadlineMs` option — an absolute, **non-resetting** wall-clock ceiling on the whole request. **Disabled by default** (a deliberately long single call — large `maxTokens`, slow model — is legitimate; a default here would kill it), overridable per call via `generate(..., { deadlineMs })`, `0`/`Infinity` disable. An *unset* deadline resolves to disabled, but an *explicitly-set* garbage value (`NaN`, a non-numeric string) throws a `ValidationError` at resolve time rather than silently disabling the bound and running unbounded — unlike `timeoutMs`, the deadline has no safe default to fall back to, so a config mistake must surface loudly. On trip, `generate()` rejects with a **terminal** `TimeoutError` distinguishable from the idle trip: `code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false` — a deadline is a hard ceiling meant to STOP, so it is *not* auto-retried (retrying would re-spend up to another full `deadlineMs`); a consumer that wants retry opts in via `retryOn`. When both are armed and `timeoutMs < deadlineMs`, a silent socket trips the idle bound first; only a still-active-but-never-completing stream reaches the deadline. The idle bound (BA-18) and the deadline (BA-19) are two independent failure modes — a silent socket vs a zombie stream.
+
 **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.35.0",
   "files": [
     "index.js",
     "index.d.ts",

package/src/provider-anthropic.d.ts

@@ -32,6 +32,14 @@ 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'`, `context.bound: 'idle'`) 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;
+    /**
+     * - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever (a "zombie stream") never trips it and hangs the caller for hours. This is an absolute, non-resetting wall-clock ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false` — a hard ceiling meant to STOP, not re-spend). DISABLED by default (a deliberately long single call is legitimate); `0`/`Infinity` disable. When both are set with `timeoutMs < deadlineMs`, a silent socket trips the idle bound first. Overridable per call via `generate(..., { deadlineMs })`.
+     */
+    deadlineMs?: number | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -47,6 +55,8 @@ 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'`, `context.bound: 'idle'`) 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 })`.
+ * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever (a "zombie stream") never trips it and hangs the caller for hours. This is an absolute, non-resetting wall-clock ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false` — a hard ceiling meant to STOP, not re-spend). DISABLED by default (a deliberately long single call is legitimate); `0`/`Infinity` disable. When both are set with `timeoutMs < deadlineMs`, a silent socket trips the idle bound first. Overridable per call via `generate(..., { deadlineMs })`.
  */
 export class AnthropicProvider {
     /**
@@ -61,11 +71,13 @@ export class AnthropicProvider {
     cacheMessages: boolean;
     thinking: any;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
+    deadlineMs: 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; deadlineMs — a per-call override of the constructor's `deadlineMs`, see BA-19).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[AnthropicProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
@@ -94,8 +106,10 @@ 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.
+     * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(body: Record<string, any>): Promise<any>;
+    _request(body: Record<string, any>, timeoutMs?: number, deadlineMs?: 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, applyRequestBounds } = require('./provider-http');
 
 /** @param {string} hostname @returns {boolean} */
 function isLoopbackHost(hostname) {
@@ -27,6 +28,8 @@ 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'`, `context.bound: 'idle'`) 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 })`.
+ * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever (a "zombie stream") never trips it and hangs the caller for hours. This is an absolute, non-resetting wall-clock ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false` — a hard ceiling meant to STOP, not re-spend). DISABLED by default (a deliberately long single call is legitimate); `0`/`Infinity` disable. When both are set with `timeoutMs < deadlineMs`, a silent socket trips the idle bound first. Overridable per call via `generate(..., { deadlineMs })`.
  */
 
 class AnthropicProvider {
@@ -52,13 +55,17 @@ 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;
+    // BA-19: total call-duration deadline (ms). Resolved at call time (default 0 = disabled).
+    this.deadlineMs = options.deadlineMs;
   }
 
   /**
    * 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; deadlineMs — a per-call override of the constructor's `deadlineMs`, see BA-19).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[AnthropicProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
@@ -142,8 +149,10 @@ 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 deadlineMs = resolveTimeoutMs(this.deadlineMs, options.deadlineMs, 0, 'deadlineMs');
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request(body),
+      request: () => this._request(body, timeoutMs, deadlineMs),
       hadTemperature: () => body.temperature != null,
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -275,9 +284,11 @@ class AnthropicProvider {
 
   /**
    * @param {Record<string, any>} body
+   * @param {number} [timeoutMs=0] - Idle-socket timeout (ms); 0 disables. See BA-18 / provider-http.
+   * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(body) {
+  _request(body, timeoutMs = 0, deadlineMs = 0) {
     return new Promise((resolve, reject) => {
       const payload = JSON.stringify(body);
       const url = new URL(this.baseUrl + '/messages');
@@ -314,6 +325,7 @@ class AnthropicProvider {
           }
         });
       });
+      applyRequestBounds(req, { timeoutMs, deadlineMs }, 'AnthropicProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-gemini.d.ts

@@ -19,6 +19,14 @@ 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'`, `context.bound: 'idle'`) 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;
+    /**
+     * - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever never trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via `generate(..., { deadlineMs })`.
+     */
+    deadlineMs?: number | undefined;
 };
 /**
  * @typedef {object} GeminiOptions
@@ -26,6 +34,8 @@ 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'`, `context.bound: 'idle'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+ * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever never trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via `generate(..., { deadlineMs })`.
  */
 /**
  * Google Gemini provider (native `generateContent` API, NOT the OpenAI-compat endpoint — that endpoint
@@ -41,11 +51,13 @@ export class GeminiProvider {
     model: string;
     baseUrl: string;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
+    deadlineMs: 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; deadlineMs — a per-call override of the constructor's `deadlineMs`, see BA-19).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[GeminiProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
@@ -66,8 +78,10 @@ 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.
+     * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(path: string, body: Record<string, any>): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number, deadlineMs?: 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, applyRequestBounds } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -23,6 +24,8 @@ 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'`, `context.bound: 'idle'`) instead of hanging until the OS TCP timeout (~2h). `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+ * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever never trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via `generate(..., { deadlineMs })`.
  */
 
 /**
@@ -39,13 +42,17 @@ 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;
+    // BA-19: total call-duration deadline (ms). Resolved at call time (default 0 = disabled).
+    this.deadlineMs = options.deadlineMs;
   }
 
   /**
    * 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; deadlineMs — a per-call override of the constructor's `deadlineMs`, see BA-19).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[GeminiProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
@@ -107,8 +114,10 @@ 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 deadlineMs = resolveTimeoutMs(this.deadlineMs, options.deadlineMs, 0, 'deadlineMs');
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request(`/models/${this.model}:generateContent`, body),
+      request: () => this._request(`/models/${this.model}:generateContent`, body, timeoutMs, deadlineMs),
       hadTemperature: () => body.generationConfig?.temperature != null,
       stripTemperature: () => { if (body.generationConfig) delete body.generationConfig.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -174,9 +183,11 @@ 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.
+   * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body) {
+  _request(path, body, timeoutMs = 0, deadlineMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.baseUrl + path);
       const transport = url.protocol === 'https:' ? https : http;
@@ -213,6 +224,7 @@ class GeminiProvider {
           }
         });
       });
+      applyRequestBounds(req, { timeoutMs, deadlineMs }, 'GeminiProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-http.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 an effective timeout-shaped ms bound. 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. The explicit opt-out idiom is `0` or `Infinity` → returns 0 (no bound). When the knob is
+ * UNSET on both, returns `defaultMs` (the idle bound's 10 min, or 0/disabled for the deadline).
+ *
+ * The disable-edge (finding-3, and the BA-4/5/6 optimistic-rounding family) is the load-bearing part:
+ * a config MISTAKE — a NaN / negative / non-numeric value the caller EXPLICITLY set (e.g.
+ * `Number(process.env.X)` on an unset var, or a string `'30s'`) — must never SILENTLY remove a bound
+ * the caller evidently tried to set. Two cases, decided by whether the knob has a safe default:
+ *   - `defaultMs > 0` (the BA-18 idle bound): fail SAFE to that real default (a garbage idle value
+ *     keeps the 10-min safety net — byte-identical to the shipped BA-18 behaviour).
+ *   - `defaultMs === 0` (the BA-19 deadline, disabled-by-design): there is NO safe bound to fall back
+ *     to, so silently returning 0 would reintroduce the very hang the deadline exists to prevent
+ *     (BA-19 review finding 1). Fail LOUD instead — throw a {@link ValidationError} so the config
+ *     mistake surfaces immediately, rather than running unbounded for hours.
+ * NOTE: an UNSET deadline (null/undefined) is legitimate and still returns 0 — only an explicitly-set
+ * garbage value throws.
+ * @param {number|undefined|null} instanceTimeout
+ * @param {number|undefined|null} [callTimeout]
+ * @param {number} [defaultMs=DEFAULT_TIMEOUT_MS] - value returned when the knob is unset (or garbage, if >0)
+ * @param {string} [name='timeoutMs'] - knob name for the throw message
+ * @returns {number} a finite positive ms bound, or 0 to disable
+ * @throws {ValidationError} when the value is explicitly set but garbage AND `defaultMs` is 0 (no safe fallback)
+ */
+export function resolveTimeoutMs(instanceTimeout: number | undefined | null, callTimeout?: number | undefined | null, defaultMs?: number, name?: string): 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;
+/**
+ * BA-19 — bound an in-flight ClientRequest on TOTAL call duration, beside {@link applyRequestTimeout}.
+ * The idle bound (`req.setTimeout`) resets on ANY socket activity, so a response that trickles a byte
+ * forever (a "zombie stream") never trips it — bytes keep arriving while the response never completes,
+ * and the call hangs until the OS TCP timeout (~4.5h observed). This adds an absolute, non-resetting
+ * wall-clock ceiling: a plain `setTimeout` that destroys the request whether or not the socket is
+ * active. On trip, the request is destroyed with a TERMINAL {@link TimeoutError} — distinct
+ * `code: 'EDEADLINE'` and `context.bound: 'deadline'` (so a consumer routing governance stops vs
+ * transport casualties can tell which timer fired), and `retryable: false` because a deadline is a
+ * HARD ceiling the caller set to STOP: auto-retrying would re-spend up to another full `deadlineMs`
+ * of tokens/budget. Disabled-by-design (a deliberately long single call is legitimate); a
+ * `deadlineMs` of 0 is a no-op. When both bounds are armed and `timeoutMs < deadlineMs`, a silent
+ * socket trips the idle bound first; only a still-active-but-never-completing stream reaches the
+ * deadline. The timer is unref'd (never keeps the event loop alive) and cleared when the request
+ * closes (no dangling handle, no late destroy of a settled request).
+ * @param {import('http').ClientRequest} req
+ * @param {number} deadlineMs - resolved bound; 0 disables
+ * @param {string} providerName - for the error message (e.g. 'AnthropicProvider')
+ */
+export function applyRequestDeadline(req: import("http").ClientRequest, deadlineMs: number, providerName: string): void;
+/**
+ * Wire ALL request bounds onto a ClientRequest in one call — the single seam each provider's
+ * `_request` uses, so the idle (BA-18) + deadline (BA-19) wiring is not copy-pasted at four call
+ * sites (BA-19 review finding 2). A future third bound is added HERE once, not at every provider.
+ * Each individual bound is a no-op when its ms value is 0/absent, so an unset knob costs nothing.
+ * @param {import('http').ClientRequest} req
+ * @param {{ timeoutMs?: number, deadlineMs?: number }} bounds - resolved ms bounds; 0/absent disables each
+ * @param {string} providerName - for error messages (e.g. 'AnthropicProvider')
+ */
+export function applyRequestBounds(req: import("http").ClientRequest, bounds: {
+    timeoutMs?: number;
+    deadlineMs?: number;
+}, providerName: string): void;

package/src/provider-http.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const { TimeoutError, ValidationError } = 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 an effective timeout-shaped ms bound. 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. The explicit opt-out idiom is `0` or `Infinity` → returns 0 (no bound). When the knob is
+ * UNSET on both, returns `defaultMs` (the idle bound's 10 min, or 0/disabled for the deadline).
+ *
+ * The disable-edge (finding-3, and the BA-4/5/6 optimistic-rounding family) is the load-bearing part:
+ * a config MISTAKE — a NaN / negative / non-numeric value the caller EXPLICITLY set (e.g.
+ * `Number(process.env.X)` on an unset var, or a string `'30s'`) — must never SILENTLY remove a bound
+ * the caller evidently tried to set. Two cases, decided by whether the knob has a safe default:
+ *   - `defaultMs > 0` (the BA-18 idle bound): fail SAFE to that real default (a garbage idle value
+ *     keeps the 10-min safety net — byte-identical to the shipped BA-18 behaviour).
+ *   - `defaultMs === 0` (the BA-19 deadline, disabled-by-design): there is NO safe bound to fall back
+ *     to, so silently returning 0 would reintroduce the very hang the deadline exists to prevent
+ *     (BA-19 review finding 1). Fail LOUD instead — throw a {@link ValidationError} so the config
+ *     mistake surfaces immediately, rather than running unbounded for hours.
+ * NOTE: an UNSET deadline (null/undefined) is legitimate and still returns 0 — only an explicitly-set
+ * garbage value throws.
+ * @param {number|undefined|null} instanceTimeout
+ * @param {number|undefined|null} [callTimeout]
+ * @param {number} [defaultMs=DEFAULT_TIMEOUT_MS] - value returned when the knob is unset (or garbage, if >0)
+ * @param {string} [name='timeoutMs'] - knob name for the throw message
+ * @returns {number} a finite positive ms bound, or 0 to disable
+ * @throws {ValidationError} when the value is explicitly set but garbage AND `defaultMs` is 0 (no safe fallback)
+ */
+function resolveTimeoutMs(instanceTimeout, callTimeout, defaultMs = DEFAULT_TIMEOUT_MS, name = 'timeoutMs') {
+  const raw = callTimeout != null ? callTimeout : instanceTimeout; // null/undefined per-call → inherit
+  if (raw == null) return defaultMs;             // absent on both → the knob's own default (0 = disabled)
+  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 n;     // finite positive bound
+  // Explicitly set but garbage. Never SILENTLY disable a bound the caller tried to set.
+  if (defaultMs > 0) return defaultMs;           // a real default exists → fail safe to it (BA-18)
+  throw new ValidationError(
+    `[provider-http] invalid ${name}: ${String(raw).slice(0, 40)} — expected a positive number, 0, or Infinity`
+  );
+}
+
+/**
+ * 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, () => {
+    // `context.bound: 'idle'` mirrors the deadline trip's discriminator (BA-19) so a consumer can
+    // switch on one uniform field to tell which timer spoke, not just on the `code`.
+    req.destroy(new TimeoutError(
+      `[${providerName}] request timed out after ${timeoutMs}ms of socket inactivity`,
+      { context: { bound: 'idle' } }
+    ));
+  });
+}
+
+/**
+ * BA-19 — bound an in-flight ClientRequest on TOTAL call duration, beside {@link applyRequestTimeout}.
+ * The idle bound (`req.setTimeout`) resets on ANY socket activity, so a response that trickles a byte
+ * forever (a "zombie stream") never trips it — bytes keep arriving while the response never completes,
+ * and the call hangs until the OS TCP timeout (~4.5h observed). This adds an absolute, non-resetting
+ * wall-clock ceiling: a plain `setTimeout` that destroys the request whether or not the socket is
+ * active. On trip, the request is destroyed with a TERMINAL {@link TimeoutError} — distinct
+ * `code: 'EDEADLINE'` and `context.bound: 'deadline'` (so a consumer routing governance stops vs
+ * transport casualties can tell which timer fired), and `retryable: false` because a deadline is a
+ * HARD ceiling the caller set to STOP: auto-retrying would re-spend up to another full `deadlineMs`
+ * of tokens/budget. Disabled-by-design (a deliberately long single call is legitimate); a
+ * `deadlineMs` of 0 is a no-op. When both bounds are armed and `timeoutMs < deadlineMs`, a silent
+ * socket trips the idle bound first; only a still-active-but-never-completing stream reaches the
+ * deadline. The timer is unref'd (never keeps the event loop alive) and cleared when the request
+ * closes (no dangling handle, no late destroy of a settled request).
+ * @param {import('http').ClientRequest} req
+ * @param {number} deadlineMs - resolved bound; 0 disables
+ * @param {string} providerName - for the error message (e.g. 'AnthropicProvider')
+ */
+function applyRequestDeadline(req, deadlineMs, providerName) {
+  if (!(deadlineMs > 0)) return;
+  const timer = setTimeout(() => {
+    req.destroy(new TimeoutError(
+      `[${providerName}] request exceeded its total deadline of ${deadlineMs}ms`,
+      { code: 'EDEADLINE', retryable: false, context: { bound: 'deadline' } }
+    ));
+  }, deadlineMs);
+  if (timer.unref) timer.unref();
+  req.once('close', () => clearTimeout(timer));
+}
+
+/**
+ * Wire ALL request bounds onto a ClientRequest in one call — the single seam each provider's
+ * `_request` uses, so the idle (BA-18) + deadline (BA-19) wiring is not copy-pasted at four call
+ * sites (BA-19 review finding 2). A future third bound is added HERE once, not at every provider.
+ * Each individual bound is a no-op when its ms value is 0/absent, so an unset knob costs nothing.
+ * @param {import('http').ClientRequest} req
+ * @param {{ timeoutMs?: number, deadlineMs?: number }} bounds - resolved ms bounds; 0/absent disables each
+ * @param {string} providerName - for error messages (e.g. 'AnthropicProvider')
+ */
+function applyRequestBounds(req, bounds, providerName) {
+  applyRequestTimeout(req, (bounds && bounds.timeoutMs) || 0, providerName);
+  applyRequestDeadline(req, (bounds && bounds.deadlineMs) || 0, providerName);
+}
+
+module.exports = { DEFAULT_TIMEOUT_MS, resolveTimeoutMs, applyRequestTimeout, applyRequestDeadline, applyRequestBounds };

package/src/provider-ollama.d.ts

@@ -5,6 +5,14 @@ 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'`, `context.bound: 'idle'`) 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;
+    /**
+     * - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever never trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via `generate(..., { deadlineMs })`. (A cold large-model load is a legitimate long single call — leave this disabled or set it generously for such models.)
+     */
+    deadlineMs?: number | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -14,6 +22,8 @@ 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'`, `context.bound: 'idle'`) 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.)
+ * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever never trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via `generate(..., { deadlineMs })`. (A cold large-model load is a legitimate long single call — leave this disabled or set it generously for such models.)
  */
 export class OllamaProvider {
     /**
@@ -23,11 +33,13 @@ export class OllamaProvider {
     model: string;
     url: string;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
+    deadlineMs: 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; `deadlineMs` — a per-call override of the constructor's `deadlineMs`, see BA-19).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
      */
@@ -38,7 +50,9 @@ 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.
+     * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(path: string, body: Record<string, any>): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number, deadlineMs?: 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, applyRequestBounds } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -14,6 +15,8 @@ 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'`, `context.bound: 'idle'`) 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.)
+ * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever never trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via `generate(..., { deadlineMs })`. (A cold large-model load is a legitimate long single call — leave this disabled or set it generously for such models.)
  */
 
 class OllamaProvider {
@@ -25,13 +28,17 @@ 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;
+    // BA-19: total call-duration deadline (ms). Resolved at call time (default 0 = disabled).
+    this.deadlineMs = options.deadlineMs;
   }
 
   /**
    * 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; `deadlineMs` — a per-call override of the constructor's `deadlineMs`, see BA-19).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
    */
@@ -64,8 +71,10 @@ 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 deadlineMs = resolveTimeoutMs(this.deadlineMs, options.deadlineMs, 0, 'deadlineMs');
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request('/api/chat', body),
+      request: () => this._request('/api/chat', body, timeoutMs, deadlineMs),
       hadTemperature: () => body.options?.temperature != null,
       stripTemperature: () => { if (body.options) delete body.options.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -110,9 +119,11 @@ 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.
+   * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body) {
+  _request(path, body, timeoutMs = 0, deadlineMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.url + path);
       const payload = JSON.stringify(body);
@@ -141,6 +152,7 @@ class OllamaProvider {
           }
         });
       });
+      applyRequestBounds(req, { timeoutMs, deadlineMs }, 'OllamaProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-openai.d.ts

@@ -14,6 +14,22 @@ 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'`, `context.bound: 'idle'`) 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;
+    /**
+     * - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`.
+     * The idle bound resets on any socket activity, so a response that trickles a byte forever never
+     * trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()`
+     * rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`,
+     * `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via
+     * `generate(..., { deadlineMs })`.
+     */
+    deadlineMs?: number | undefined;
 };
 /**
  * @typedef {object} OpenAIOptions
@@ -25,6 +41,16 @@ 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'`, `context.bound: 'idle'`) instead of hanging until the OS TCP timeout (~2h).
+ *   `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+ * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`.
+ *   The idle bound resets on any socket activity, so a response that trickles a byte forever never
+ *   trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()`
+ *   rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`,
+ *   `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via
+ *   `generate(..., { deadlineMs })`.
  */
 export class OpenAIProvider {
     /**
@@ -35,11 +61,13 @@ export class OpenAIProvider {
     model: string;
     baseUrl: string;
     exposeErrorBody: boolean;
+    timeoutMs: number | undefined;
+    deadlineMs: 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; deadlineMs — a per-call override of the constructor's `deadlineMs`, see BA-19).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
@@ -60,8 +88,10 @@ 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.
+     * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
      * @returns {Promise<any>}
      */
-    _request(path: string, body: Record<string, any>): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number, deadlineMs?: 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, applyRequestBounds } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -27,6 +28,16 @@ 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'`, `context.bound: 'idle'`) instead of hanging until the OS TCP timeout (~2h).
+ *   `0`/`Infinity` disables it (pre-BA-18 behaviour). Overridable per call via `generate(..., { timeoutMs })`.
+ * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`.
+ *   The idle bound resets on any socket activity, so a response that trickles a byte forever never
+ *   trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()`
+ *   rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`,
+ *   `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via
+ *   `generate(..., { deadlineMs })`.
  */
 
 class OpenAIProvider {
@@ -38,13 +49,17 @@ 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;
+    // BA-19: total call-duration deadline (ms). Resolved at call time (default 0 = disabled).
+    this.deadlineMs = options.deadlineMs;
   }
 
   /**
    * 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; deadlineMs — a per-call override of the constructor's `deadlineMs`, see BA-19).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
@@ -65,8 +80,10 @@ 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 deadlineMs = resolveTimeoutMs(this.deadlineMs, options.deadlineMs, 0, 'deadlineMs');
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request('/chat/completions', body),
+      request: () => this._request('/chat/completions', body, timeoutMs, deadlineMs),
       hadTemperature: () => body.temperature != null,
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -124,9 +141,11 @@ 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.
+   * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body) {
+  _request(path, body, timeoutMs = 0, deadlineMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.baseUrl + path);
       const transport = url.protocol === 'https:' ? https : http;
@@ -168,6 +187,7 @@ class OpenAIProvider {
           }
         });
       });
+      applyRequestBounds(req, { timeoutMs, deadlineMs }, 'OpenAIProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();