bare-agent 0.41.1 → 0.42.0

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.41.1 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.16.0` optional peer for governance) | Apache 2.0
+> v0.42.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.16.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/archive/usage-guide.md)
 

package/package.json

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

package/src/errors.d.ts

@@ -21,6 +21,10 @@ export type ProviderErrorOptions = {
      * - Raw response body.
      */
     body?: any;
+    /**
+     * - Override the status-derived retryability (for transport-class failures with no status).
+     */
+    retryable?: boolean | undefined;
     /**
      * - Arbitrary structured context.
      */
@@ -50,6 +54,7 @@ export type HaltErrorOptions = {
  * @typedef {object} ProviderErrorOptions
  * @property {number} [status] - HTTP status from the provider.
  * @property {any} [body] - Raw response body.
+ * @property {boolean} [retryable] - Override the status-derived retryability (for transport-class failures with no status).
  * @property {Record<string, any>} [context] - Arbitrary structured context.
  */
 /**
@@ -73,7 +78,7 @@ export class ProviderError extends BareAgentError {
      * @param {string} message
      * @param {ProviderErrorOptions} [options]
      */
-    constructor(message: string, { status, body, context }?: ProviderErrorOptions);
+    constructor(message: string, { status, body, retryable, context }?: ProviderErrorOptions);
     status: number | undefined;
     body: any;
 }

package/src/errors.js

@@ -11,6 +11,7 @@
  * @typedef {object} ProviderErrorOptions
  * @property {number} [status] - HTTP status from the provider.
  * @property {any} [body] - Raw response body.
+ * @property {boolean} [retryable] - Override the status-derived retryability (for transport-class failures with no status).
  * @property {Record<string, any>} [context] - Arbitrary structured context.
  */
 
@@ -40,9 +41,11 @@ class ProviderError extends BareAgentError {
    * @param {string} message
    * @param {ProviderErrorOptions} [options]
    */
-  constructor(message, { status, body, context = {} } = {}) {
-    const retryable = status === 429 || (status != null && status >= 500 && status <= 504);
-    super(message, { code: 'PROVIDER_ERROR', retryable, context });
+  constructor(message, { status, body, retryable, context = {} } = {}) {
+    // A transport-class failure (BA-25: socket aborted / closed before the body completed) carries no
+    // HTTP status, so the status-derived default can't classify it — an explicit `retryable` overrides.
+    const derived = status === 429 || (status != null && status >= 500 && status <= 504);
+    super(message, { code: 'PROVIDER_ERROR', retryable: retryable != null ? retryable : derived, context });
     this.status = status;
     this.body = body;
   }

package/src/loop.d.ts

@@ -161,7 +161,7 @@ export class Loop {
      *   thunk is re-evaluated each round (D4/eval-assist F2) so a tool set that grows mid-run — e.g. a skill
      *   unlocking its tools — is offered on the next round; a static array is resolved once at wire time.
      * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
      *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
      *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
      *   dangling assistant `tool_calls` from the halted round are paired with
@@ -196,10 +196,12 @@ export class Loop {
         cost: number;
         error: string | null;
         stopReason: string | null;
+        model: string | null;
         msgs: Message[];
         metrics: RunMetrics;
         temperatureDropped?: boolean;
     }>;
+    _warnedTruncated: boolean | undefined;
     /**
      * Health check — validates provider, store, and tools without throwing.
      * @param {ToolDef[]} [tools=[]] - Tool definitions to validate.
@@ -226,7 +228,7 @@ export class Loop {
      * @param {string} text - User message.
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
      * @param {Record<string, any>} [options={}] - Per-run overrides.
-     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
      */
     chat(text: string, tools?: ToolDef[], options?: Record<string, any>): Promise<{
         text: string;
@@ -235,6 +237,7 @@ export class Loop {
         cost: number;
         error: string | null;
         stopReason: string | null;
+        model: string | null;
         msgs: Message[];
         metrics: RunMetrics;
         temperatureDropped?: boolean;

package/src/loop.js

@@ -449,7 +449,7 @@ class Loop {
    *   thunk is re-evaluated each round (D4/eval-assist F2) so a tool set that grows mid-run — e.g. a skill
    *   unlocking its tools — is offered on the next round; a static array is resolved once at wire time.
    * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
    *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
    *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
    *   dangling assistant `tool_calls` from the halted round are paired with
@@ -543,6 +543,10 @@ class Loop {
     // says which kind). Stays null until the first round completes, and across a provider error / a
     // pre-round stop() it holds the last round's value (or null if none ran).
     let lastStopReason = null;
+    // ASK 3 / fwdloop F3: the resolved model id of the most recent completed round (from the provider
+    // RESPONSE, not the provider object — a wrapped/fallback provider can lose `.model`). Surfaced on
+    // every return so a caller reads which model produced the result without the onLlmResult side channel.
+    let lastModel = null;
     // BA-10: sticky across rounds — true if ANY round's `temperature` was dropped by the model (400,
     // unsupported/deprecated) and retried without it. Surfaced on the result so an upstream receipt
     // (recurse's refineLeaf) can report the EFFECTIVE temperature rather than the ignored request.
@@ -579,7 +583,7 @@ class Loop {
         sealDanglingToolCalls(msgs, `[halted:${stuckTag}]`);
         this._reportError('stuck', new Error(`tool "${tc.name}" failed ${identicalErrors} times with identical arguments`), { rule: stuckTag, attempts: identicalErrors });
         this._safeEmit({ type: 'loop:done', data: { text: lastText, stuck: true, rule: stuckTag, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: stuckTag, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: stuckTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
       return null;
     };
@@ -826,7 +830,7 @@ class Loop {
         this._reportError('provider', err, { round });
         if (this.throwOnError) throw err;
         // BA-5: a mid-run provider failure must not erase the work of the rounds that succeeded.
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       lastUsage = result.usage || lastUsage;
@@ -838,6 +842,7 @@ class Loop {
       // BA-13: capture this round's neutral stop reason for surfacing on the run's return (every exit
       // path reads lastStopReason). Non-string / absent ⇒ null (the provider's pre-BA-6 degrade).
       lastStopReason = typeof result.stopReason === 'string' ? result.stopReason : null;
+      if (typeof result.model === 'string' && result.model) lastModel = result.model;
       if (result.temperatureDropped) temperatureDropped = true;
       // Publish the latest measured usage to ctx (non-enumerable, fail-open) so a transcript-bound seam —
       // e.g. F2 stash auto-compaction — can read EXACT provider-counted `inputTokens` to gauge context
@@ -897,6 +902,10 @@ class Loop {
             // a silent guess stamped as if it were a real rate (BA-21). `pricing` keeps its two values.
             pricing: roundCost === null ? 'unpriced' : 'priced',
             rateSource, // 'provider'|'caller'|'tier'|'default'|null
+            // ASK 3 (fwdloop F4): carry the round's neutral stop reason on the metering payload so an
+            // audit row records a `max_tokens`/`refusal`/etc. terminal WITHOUT awaiting the run result —
+            // a cut reasoning round (empty text, no tool call) is otherwise indistinguishable from a refusal.
+            stopReason: typeof result.stopReason === 'string' ? result.stopReason : null,
             durationMs: Date.now() - llmStartedAt,
             ctx,
             kind: 'turn',
@@ -918,7 +927,7 @@ class Loop {
         sealDanglingToolCalls(msgs, `[halted:${session.error}]`);
         this._reportError('session', new Error(`provider session terminated: ${session.error}`), { rule: session.error, sessionTurns: session.turns ?? null });
         this._safeEmit({ type: 'loop:done', data: { text: lastText, rule: session.error, sessionTurns: session.turns ?? null, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: session.error, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: session.error, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // BA-13: classify this round's terminal signal against the neutral stop-reason vocabulary. BA-6
@@ -964,6 +973,18 @@ class Loop {
         // `error:null` + `stopReason:'refusal'` would re-breed BA-6 for these legs.
         const errorTag = terminal === 'truncated' ? 'truncated:max_tokens' : terminal;
         const dropped = (result.toolCalls || []).length;
+        // ASK 3 (fwdloop F4): a `max_tokens`/`length` round has empty text and no tool call, so it reads
+        // exactly like a refusal — fwdloop misdiagnosed a cut-mid-think drafter for an hour. Make it LOUD:
+        // a dedicated `loop:truncated` event AND one console.warn per Loop (mirrors the temperature-drop /
+        // unpriced-round precedent). The awaited result already error-tags it (BA-13); this surfaces it
+        // to a stream consumer and to the console without reading the return value.
+        if (terminal === 'truncated') {
+          this._safeEmit({ type: 'loop:truncated', data: { round, stopReason: lastStopReason, droppedToolCalls: dropped, outputTokens: lastUsage && lastUsage.outputTokens } });
+          if (!this._warnedTruncated) {
+            this._warnedTruncated = true;
+            console.warn(`[Loop] a round stopped at the output cap (stopReason='${lastStopReason}') with no completed tool call — the response was cut off (often reasoning billed as output). Raise maxTokens or lower reasoning effort. Further truncations from this Loop are silent.`);
+          }
+        }
         // Seal the transcript with the partial text only. Deliberately NOT the tool_calls: pushing a call
         // we refuse to execute would orphan it (a tool_call with no tool_result is a wire-invalid
         // transcript on Anthropic). Empty text pushes nothing — a bare empty assistant turn is also invalid.
@@ -971,7 +992,7 @@ class Loop {
           msgs.push({ role: 'assistant', content: result.text });
         }
         this._safeEmit({ type: 'loop:done', data: { text: lastText, ...(terminal === 'truncated' && { truncated: true }), terminal, stopReason: lastStopReason, droppedToolCalls: dropped, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: errorTag, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: errorTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // No tool calls — LLM gave a final text response
@@ -991,7 +1012,7 @@ class Loop {
           try { await flush(msgs, ctx); }
           catch (err) { if (err instanceof HaltError) throw err; this._reportError('trim-flush', err, { round }); }
         }
-        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // Execute tool calls
@@ -1100,7 +1121,7 @@ class Loop {
               sealDanglingToolCalls(msgs, `[halted:${denyTag}]`);
               this._reportError('denied', new Error(`policy denied ${consecutiveDenials} consecutive tool calls (${tc.name})`), { rule: denyTag, denials: consecutiveDenials });
               this._safeEmit({ type: 'loop:done', data: { text: lastText, denied: true, rule: denyTag, cost: totalCost } });
-              return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+              return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
             }
             continue;
           }
@@ -1174,7 +1195,7 @@ class Loop {
         // BA-5: the rule tag survives on `error`; so does the work. A halt is how a bounded attempt is
         // SUPPOSED to end — the caller reads `error` to know it was bounded and `text` to learn from it.
         this._safeEmit({ type: 'loop:done', data: { text: lastText, halted: true, rule, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
       throw err;
     }
@@ -1204,20 +1225,20 @@ class Loop {
             const rule = err.rule || 'unknown';
             this._reportError('halt', err, { rule, reason: err.decision?.reason ?? null });
             this._safeEmit({ type: 'loop:done', data: { text: lastText, halted: true, rule, cost: totalCost } });
-            return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+            return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
           }
           this._reportError('trim-flush', err, { phase: 'stop' });
         }
       }
       this._safeEmit({ type: 'loop:done', data: { text: lastText, stopped: true, cost: totalCost } });
-      return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+      return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
     }
 
     // Hard safety limit — should never fire under normal usage; bareguard's
     // limits.maxTurns (or the LLM's natural completion) ends the loop first.
     const warning = `[Loop] hit internal safety limit of ${HARD_ROUND_LIMIT} rounds. Wire bareguard for proper governance — see bare-agent/bareguard.`;
     this._safeEmit({ type: 'loop:done', data: { text: lastText, warning, cost: totalCost } });
-    return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+    return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
   }
 
   /**
@@ -1290,7 +1311,7 @@ class Loop {
    * @param {string} text - User message.
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
    * @param {Record<string, any>} [options={}] - Per-run overrides.
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
    */
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });

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, applyRequestBounds } = require('./provider-http');
+const { resolveTimeoutMs, applyRequestBounds, guardResponseSettles } = require('./provider-http');
 const { hasUsageSignal } = require('./provider-usage');
 
 // BA-24: the raw Anthropic usage field names. Presence of any (even value 0) means the API reported a
@@ -318,8 +318,11 @@ class AnthropicProvider {
         },
       }, (res) => {
         let chunks = '';
+        // BA-25: reject (retryable) if the body is cut after headers, so generate() always settles.
+        const { markEnded } = guardResponseSettles(res, reject, 'AnthropicProvider');
         res.on('data', d => chunks += d);
         res.on('end', () => {
+          markEnded();
           try {
             const parsed = JSON.parse(chunks);
             if ((res.statusCode ?? 0) >= 400) {

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, applyRequestBounds } = require('./provider-http');
+const { resolveTimeoutMs, applyRequestBounds, guardResponseSettles } = require('./provider-http');
 const { hasUsageSignal } = require('./provider-usage');
 
 // BA-24: raw Gemini usageMetadata fields. Any present (even 0) ⇒ a usage signal; none ⇒ null.
@@ -215,8 +215,11 @@ class GeminiProvider {
         },
       }, (res) => {
         let chunks = '';
+        // BA-25: reject (retryable) if the body is cut after headers, so generate() always settles.
+        const { markEnded } = guardResponseSettles(res, reject, 'GeminiProvider');
         res.on('data', d => (chunks += d));
         res.on('end', () => {
+          markEnded();
           try {
             const parsed = JSON.parse(chunks);
             if ((res.statusCode ?? 0) >= 400) {

package/src/provider-http.d.ts

@@ -78,3 +78,28 @@ export function applyRequestBounds(req: import("http").ClientRequest, bounds: {
     timeoutMs?: number;
     deadlineMs?: number;
 }, providerName: string): void;
+/**
+ * BA-25 — guarantee the response promise SETTLES when the body is cut after headers. The provider
+ * `_request` handlers wired only `res 'data'` + `res 'end'` (and `req 'error'`), so a socket the
+ * server aborts or closes AFTER sending headers but BEFORE 'end' fired neither resolved nor rejected:
+ * 'end' never came, and the BA-18 idle timer can't rescue it because the socket is already dead (no
+ * further activity to time out against). The process then drains with an unsettled top-level await.
+ *
+ * Three terminal response events are the miss: `res 'aborted'` (peer reset mid-body), `res 'error'`
+ * (stream error), and `res 'close'` WITHOUT a prior 'end' (clean-looking FIN before the body
+ * completed). Each rejects with a RETRYABLE transport-class `ProviderError` (no HTTP status → the
+ * status-derived retryability can't classify it, so `retryable:true` is explicit) so a wired
+ * `Retry`/one-retry ladder (which keys on `err.retryable === true`) sees it instead of hanging.
+ *
+ * Returns `markEnded` — the 'end' handler MUST call it (before its own resolve/reject) so a normal
+ * 'close' firing after 'end' does not spuriously reject an already-settled promise. Extra rejects
+ * after settle are no-ops (Promise semantics), so ordering is safe either way; `markEnded` only
+ * suppresses the benign post-'end' 'close'.
+ * @param {import('http').IncomingMessage} res
+ * @param {(err: Error) => void} reject - the _request Promise's reject
+ * @param {string} providerName - for the error message (e.g. 'OpenAIProvider')
+ * @returns {{ markEnded: () => void }}
+ */
+export function guardResponseSettles(res: import("http").IncomingMessage, reject: (err: Error) => void, providerName: string): {
+    markEnded: () => void;
+};

package/src/provider-http.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { TimeoutError, ValidationError } = require('./errors');
+const { TimeoutError, ValidationError, ProviderError } = require('./errors');
 
 /**
  * BA-18 — shared request-timeout helper for the http(s)-based providers (Anthropic, OpenAI,
@@ -123,4 +123,38 @@ function applyRequestBounds(req, bounds, providerName) {
   applyRequestDeadline(req, (bounds && bounds.deadlineMs) || 0, providerName);
 }
 
-module.exports = { DEFAULT_TIMEOUT_MS, resolveTimeoutMs, applyRequestTimeout, applyRequestDeadline, applyRequestBounds };
+/**
+ * BA-25 — guarantee the response promise SETTLES when the body is cut after headers. The provider
+ * `_request` handlers wired only `res 'data'` + `res 'end'` (and `req 'error'`), so a socket the
+ * server aborts or closes AFTER sending headers but BEFORE 'end' fired neither resolved nor rejected:
+ * 'end' never came, and the BA-18 idle timer can't rescue it because the socket is already dead (no
+ * further activity to time out against). The process then drains with an unsettled top-level await.
+ *
+ * Three terminal response events are the miss: `res 'aborted'` (peer reset mid-body), `res 'error'`
+ * (stream error), and `res 'close'` WITHOUT a prior 'end' (clean-looking FIN before the body
+ * completed). Each rejects with a RETRYABLE transport-class `ProviderError` (no HTTP status → the
+ * status-derived retryability can't classify it, so `retryable:true` is explicit) so a wired
+ * `Retry`/one-retry ladder (which keys on `err.retryable === true`) sees it instead of hanging.
+ *
+ * Returns `markEnded` — the 'end' handler MUST call it (before its own resolve/reject) so a normal
+ * 'close' firing after 'end' does not spuriously reject an already-settled promise. Extra rejects
+ * after settle are no-ops (Promise semantics), so ordering is safe either way; `markEnded` only
+ * suppresses the benign post-'end' 'close'.
+ * @param {import('http').IncomingMessage} res
+ * @param {(err: Error) => void} reject - the _request Promise's reject
+ * @param {string} providerName - for the error message (e.g. 'OpenAIProvider')
+ * @returns {{ markEnded: () => void }}
+ */
+function guardResponseSettles(res, reject, providerName) {
+  let ended = false;
+  const fail = (/** @type {string} */ event, /** @type {any} */ cause = null) => reject(new ProviderError(
+    `[${providerName}] response stream ${event} before the body completed`,
+    { retryable: true, context: { bound: 'transport', event, ...(cause && cause.code && { causeCode: cause.code }) } },
+  ));
+  res.on('aborted', () => fail('aborted'));
+  res.on('error', (e) => fail('error', e));
+  res.on('close', () => { if (!ended) fail('close'); });
+  return { markEnded: () => { ended = true; } };
+}
+
+module.exports = { DEFAULT_TIMEOUT_MS, resolveTimeoutMs, applyRequestTimeout, applyRequestDeadline, applyRequestBounds, guardResponseSettles };

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, applyRequestBounds } = require('./provider-http');
+const { resolveTimeoutMs, applyRequestBounds, guardResponseSettles } = require('./provider-http');
 const { hasUsageSignal } = require('./provider-usage');
 
 // BA-24: raw Ollama usage fields. Any present (even 0) ⇒ a usage signal; none ⇒ null (unpriceable).
@@ -141,8 +141,11 @@ class OllamaProvider {
         },
       }, (res) => {
         let chunks = '';
+        // BA-25: reject (retryable) if the body is cut after headers, so generate() always settles.
+        const { markEnded } = guardResponseSettles(res, reject, 'OllamaProvider');
         res.on('data', d => chunks += d);
         res.on('end', () => {
+          markEnded();
           try {
             const parsed = JSON.parse(chunks);
             if ((res.statusCode ?? 0) >= 400) {

package/src/provider-openai.d.ts

@@ -30,6 +30,14 @@ export type OpenAIOptions = {
      * `generate(..., { deadlineMs })`.
      */
     deadlineMs?: number | undefined;
+    /**
+     * - BA-24 (fwdloop): send the legacy `max_tokens` request
+     * key instead of `max_completion_tokens`. The default is `max_completion_tokens` because current
+     * OpenAI GPT-5 models 400 on `max_tokens` ("Unsupported parameter … Use 'max_completion_tokens'").
+     * Set `true` for an OpenAI-compatible server that only understands the legacy key (e.g. some
+     * self-hosted / proxy endpoints). No model-name sniffing — the caller declares the dialect.
+     */
+    legacyMaxTokens?: boolean | undefined;
 };
 /**
  * @typedef {object} OpenAIOptions
@@ -51,6 +59,11 @@ export type OpenAIOptions = {
  *   rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`,
  *   `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via
  *   `generate(..., { deadlineMs })`.
+ * @property {boolean} [legacyMaxTokens=false] - BA-24 (fwdloop): send the legacy `max_tokens` request
+ *   key instead of `max_completion_tokens`. The default is `max_completion_tokens` because current
+ *   OpenAI GPT-5 models 400 on `max_tokens` ("Unsupported parameter … Use 'max_completion_tokens'").
+ *   Set `true` for an OpenAI-compatible server that only understands the legacy key (e.g. some
+ *   self-hosted / proxy endpoints). No model-name sniffing — the caller declares the dialect.
  */
 export class OpenAIProvider {
     /**
@@ -63,11 +76,12 @@ export class OpenAIProvider {
     exposeErrorBody: boolean;
     timeoutMs: number | undefined;
     deadlineMs: number | undefined;
+    legacyMaxTokens: boolean;
     /**
      * Generate a response from the OpenAI API.
      * @param {Message[]} messages - Conversation messages.
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
-     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens, 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).
+     * @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; toolChoice — `'auto'` | `'required'` | `{ name }`, forwarded as OpenAI `tool_choice`, applied only when `tools` are present).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */

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, applyRequestBounds } = require('./provider-http');
+const { resolveTimeoutMs, applyRequestBounds, guardResponseSettles } = require('./provider-http');
 const { hasUsageSignal } = require('./provider-usage');
 
 // BA-24: raw OpenAI usage fields. Any present (even 0) ⇒ a usage signal; none ⇒ null (unpriceable).
@@ -16,6 +16,23 @@ const OPENAI_USAGE_KEYS = ['prompt_tokens', 'completion_tokens', 'prompt_tokens_
 /** @typedef {import('../types').ToolCall} ToolCall */
 /** @typedef {import('../types').GenerateResult} GenerateResult */
 
+/**
+ * Map a neutral `toolChoice` option to OpenAI's `tool_choice` wire shape (Ask 4, fwdloop).
+ * `'auto'`/`'required'` pass through; `{ name }` becomes `{ type:'function', function:{ name } }`.
+ * `null`/`undefined` ⇒ omit the field (the API default `auto`). An unrecognized shape throws — a
+ * silently-dropped force would read as "the model chose not to call", the exact confusion Ask 3 fixes.
+ * @param {undefined|null|'auto'|'required'|{name: string}} choice
+ * @returns {undefined|'auto'|'required'|{type:'function', function:{name:string}}}
+ */
+function toOpenAIToolChoice(choice) {
+  if (choice == null) return undefined;
+  if (choice === 'auto' || choice === 'required') return choice;
+  if (typeof choice === 'object' && typeof choice.name === 'string' && choice.name) {
+    return { type: 'function', function: { name: choice.name } };
+  }
+  throw new ProviderError(`[OpenAIProvider] invalid toolChoice: expected 'auto', 'required', or { name }, got ${JSON.stringify(choice)}`);
+}
+
 /** @param {string} hostname @returns {boolean} */
 function isLoopbackHost(hostname) {
   const h = hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
@@ -42,6 +59,11 @@ function isLoopbackHost(hostname) {
  *   rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`,
  *   `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via
  *   `generate(..., { deadlineMs })`.
+ * @property {boolean} [legacyMaxTokens=false] - BA-24 (fwdloop): send the legacy `max_tokens` request
+ *   key instead of `max_completion_tokens`. The default is `max_completion_tokens` because current
+ *   OpenAI GPT-5 models 400 on `max_tokens` ("Unsupported parameter … Use 'max_completion_tokens'").
+ *   Set `true` for an OpenAI-compatible server that only understands the legacy key (e.g. some
+ *   self-hosted / proxy endpoints). No model-name sniffing — the caller declares the dialect.
  */
 
 class OpenAIProvider {
@@ -57,29 +79,40 @@ class OpenAIProvider {
     this.timeoutMs = options.timeoutMs;
     // BA-19: total call-duration deadline (ms). Resolved at call time (default 0 = disabled).
     this.deadlineMs = options.deadlineMs;
+    // BA-24 (fwdloop): use the legacy `max_tokens` key. Default false ⇒ `max_completion_tokens` (GPT-5-safe).
+    this.legacyMaxTokens = options.legacyMaxTokens === true;
   }
 
   /**
    * 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; deadlineMs — a per-call override of the constructor's `deadlineMs`, see BA-19).
+   * @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; toolChoice — `'auto'` | `'required'` | `{ name }`, forwarded as OpenAI `tool_choice`, applied only when `tools` are present).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
   async generate(messages, tools = [], options = {}) {
+    // BA-24 (fwdloop): GPT-5 models 400 on `max_tokens` and want `max_completion_tokens`; the legacy
+    // key stays reachable via the constructor's `legacyMaxTokens` for compat servers. No model sniffing.
+    const maxTokensKey = this.legacyMaxTokens ? 'max_tokens' : 'max_completion_tokens';
     /** @type {Record<string, any>} */
     const body = {
       model: this.model,
       messages,
       ...(options.temperature != null && { temperature: options.temperature }),
-      ...(options.maxTokens && { max_tokens: options.maxTokens }),
+      ...(options.maxTokens && { [maxTokensKey]: options.maxTokens }),
     };
+    // Ask 4 (fwdloop): validate the toolChoice SHAPE unconditionally so an invalid value ALWAYS throws
+    // (a silently-dropped force is the exact confusion this surfaces) — even when tools happen to be
+    // empty. Attach it only when tools are present: OpenAI 400s on a tool_choice with no tools, so a
+    // valid choice with nothing to force is dropped (documented), while absent ⇒ the API default 'auto'.
+    const toolChoice = toOpenAIToolChoice(options.toolChoice);
     if (tools.length > 0) {
       body.tools = tools.map(t => ({
         type: 'function',
         function: { name: t.name, description: t.description, parameters: t.parameters },
       }));
+      if (toolChoice != null) body.tool_choice = toolChoice;
     }
 
     // BA-10: newer models (o1/gpt-5-class) reject a non-default `temperature` with a 400 — drop it and
@@ -178,8 +211,11 @@ class OpenAIProvider {
         },
       }, (res) => {
         let chunks = '';
+        // BA-25: reject (retryable) if the body is cut after headers, so generate() always settles.
+        const { markEnded } = guardResponseSettles(res, reject, 'OpenAIProvider');
         res.on('data', d => chunks += d);
         res.on('end', () => {
+          markEnded();
           try {
             const parsed = JSON.parse(chunks);
             if ((res.statusCode ?? 0) >= 400) {