bare-agent 0.34.0 → 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.34.0 | 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,7 +829,9 @@ 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.
+**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.
 

package/package.json

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

package/src/provider-anthropic.d.ts

@@ -33,9 +33,13 @@ export type AnthropicOptions = {
      */
     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 })`.
+     * - 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 */
@@ -51,7 +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'`) 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} [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 {
     /**
@@ -67,11 +72,12 @@ export class AnthropicProvider {
     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, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
+     * @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.
      */
@@ -101,8 +107,9 @@ export 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: Record<string, any>, timeoutMs?: number): Promise<any>;
+    _request(body: Record<string, any>, timeoutMs?: number, deadlineMs?: number): Promise<any>;
     _warnedInsecure: boolean | undefined;
 }

package/src/provider-anthropic.js

@@ -5,7 +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');
+const { resolveTimeoutMs, applyRequestBounds } = require('./provider-http');
 
 /** @param {string} hostname @returns {boolean} */
 function isLoopbackHost(hostname) {
@@ -28,7 +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'`) 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} [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 {
@@ -56,13 +57,15 @@ class AnthropicProvider {
     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, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
+   * @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.
    */
@@ -147,8 +150,9 @@ class AnthropicProvider {
     // 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, timeoutMs),
+      request: () => this._request(body, timeoutMs, deadlineMs),
       hadTemperature: () => body.temperature != null,
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -281,9 +285,10 @@ 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, timeoutMs = 0) {
+  _request(body, timeoutMs = 0, deadlineMs = 0) {
     return new Promise((resolve, reject) => {
       const payload = JSON.stringify(body);
       const url = new URL(this.baseUrl + '/messages');
@@ -320,7 +325,7 @@ class AnthropicProvider {
           }
         });
       });
-      applyRequestTimeout(req, timeoutMs, 'AnthropicProvider');
+      applyRequestBounds(req, { timeoutMs, deadlineMs }, 'AnthropicProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-gemini.d.ts

@@ -20,9 +20,13 @@ export type GeminiOptions = {
      */
     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 })`.
+     * - 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
@@ -30,7 +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'`) 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} [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
@@ -47,11 +52,12 @@ export class GeminiProvider {
     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, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
+     * @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.
      */
@@ -73,8 +79,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.
+     * @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>, timeoutMs?: number): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number, deadlineMs?: number): Promise<any>;
     _warnedInsecure: boolean | undefined;
 }

package/src/provider-gemini.js

@@ -5,7 +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');
+const { resolveTimeoutMs, applyRequestBounds } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -24,7 +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'`) 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} [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 })`.
  */
 
 /**
@@ -43,13 +44,15 @@ class GeminiProvider {
     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, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
+   * @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.
    */
@@ -112,8 +115,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 deadlineMs = resolveTimeoutMs(this.deadlineMs, options.deadlineMs, 0, 'deadlineMs');
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request(`/models/${this.model}:generateContent`, body, timeoutMs),
+      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(),
@@ -180,9 +184,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.
+   * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body, timeoutMs = 0) {
+  _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;
@@ -219,7 +224,7 @@ class GeminiProvider {
           }
         });
       });
-      applyRequestTimeout(req, timeoutMs, 'GeminiProvider');
+      applyRequestBounds(req, { timeoutMs, deadlineMs }, 'GeminiProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-http.d.ts

@@ -8,18 +8,31 @@
  */
 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).
+ * 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): number;
+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
@@ -32,3 +45,36 @@ export function resolveTimeoutMs(instanceTimeout: number | undefined | null, cal
  * @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

@@ -1,6 +1,6 @@
 'use strict';
 
-const { TimeoutError } = require('./errors');
+const { TimeoutError, ValidationError } = require('./errors');
 
 /**
  * BA-18 — shared request-timeout helper for the http(s)-based providers (Anthropic, OpenAI,
@@ -18,24 +18,41 @@ const { TimeoutError } = require('./errors');
 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).
+ * 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) {
+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 DEFAULT_TIMEOUT_MS;    // absent on both → finite default
+  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 DEFAULT_TIMEOUT_MS; // NaN / negative / garbage → SAFE default, never a silent disable
-  return n;                                      // finite positive 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`
+  );
 }
 
 /**
@@ -52,8 +69,58 @@ function resolveTimeoutMs(instanceTimeout, callTimeout) {
 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`));
+    // `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' } }
+    ));
   });
 }
 
-module.exports = { DEFAULT_TIMEOUT_MS, resolveTimeoutMs, applyRequestTimeout };
+/**
+ * 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

@@ -6,9 +6,13 @@ export type OllamaOptions = {
     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.)
+     * - 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 */
@@ -18,7 +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'`) 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} [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 {
     /**
@@ -29,11 +34,12 @@ export class OllamaProvider {
     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`, `timeoutMs` — a per-call override of the constructor's `timeoutMs`; see BA-18).
+     * @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.
      */
@@ -45,7 +51,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.
+     * @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>, timeoutMs?: number): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number, deadlineMs?: number): Promise<any>;
 }

package/src/provider-ollama.js

@@ -4,7 +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');
+const { resolveTimeoutMs, applyRequestBounds } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -15,7 +15,8 @@ const { resolveTimeoutMs, applyRequestTimeout } = require('./provider-http');
  * @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.)
+ * @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 {
@@ -29,13 +30,15 @@ class OllamaProvider {
     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`, `timeoutMs` — a per-call override of the constructor's `timeoutMs`; see BA-18).
+   * @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.
    */
@@ -69,8 +72,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 deadlineMs = resolveTimeoutMs(this.deadlineMs, options.deadlineMs, 0, 'deadlineMs');
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request('/api/chat', body, timeoutMs),
+      request: () => this._request('/api/chat', body, timeoutMs, deadlineMs),
       hadTemperature: () => body.options?.temperature != null,
       stripTemperature: () => { if (body.options) delete body.options.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -116,9 +120,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.
+   * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body, timeoutMs = 0) {
+  _request(path, body, timeoutMs = 0, deadlineMs = 0) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.url + path);
       const payload = JSON.stringify(body);
@@ -147,7 +152,7 @@ class OllamaProvider {
           }
         });
       });
-      applyRequestTimeout(req, timeoutMs, 'OllamaProvider');
+      applyRequestBounds(req, { timeoutMs, deadlineMs }, 'OllamaProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();

package/src/provider-openai.d.ts

@@ -17,10 +17,19 @@ export type OpenAIOptions = {
     /**
      * - 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 })`.
+     * (`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
@@ -34,8 +43,14 @@ export type OpenAIOptions = {
  *   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 })`.
+ *   (`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 {
     /**
@@ -47,11 +62,12 @@ export class OpenAIProvider {
     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, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
+     * @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.
      */
@@ -73,8 +89,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.
+     * @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>, timeoutMs?: number): Promise<any>;
+    _request(path: string, body: Record<string, any>, timeoutMs?: number, deadlineMs?: number): Promise<any>;
     _warnedInsecure: boolean | undefined;
 }

package/src/provider-openai.js

@@ -5,7 +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');
+const { resolveTimeoutMs, applyRequestBounds } = require('./provider-http');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -30,8 +30,14 @@ function isLoopbackHost(hostname) {
  *   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 })`.
+ *   (`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 {
@@ -45,13 +51,15 @@ class OpenAIProvider {
     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, timeoutMs — a per-call override of the constructor's `timeoutMs`; see BA-18).
+   * @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.
    */
@@ -73,8 +81,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 deadlineMs = resolveTimeoutMs(this.deadlineMs, options.deadlineMs, 0, 'deadlineMs');
     const { data, temperatureDropped } = await requestWithTemperatureFallback({
-      request: () => this._request('/chat/completions', body, timeoutMs),
+      request: () => this._request('/chat/completions', body, timeoutMs, deadlineMs),
       hadTemperature: () => body.temperature != null,
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
@@ -133,9 +142,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.
+   * @param {number} [deadlineMs=0] - Total call-duration deadline (ms); 0 disables. See BA-19 / provider-http.
    * @returns {Promise<any>}
    */
-  _request(path, body, timeoutMs = 0) {
+  _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;
@@ -177,7 +187,7 @@ class OpenAIProvider {
           }
         });
       });
-      applyRequestTimeout(req, timeoutMs, 'OpenAIProvider');
+      applyRequestBounds(req, { timeoutMs, deadlineMs }, 'OpenAIProvider');
       req.on('error', reject);
       req.write(payload);
       req.end();