bare-agent 0.26.0 → 0.27.0

package/src/provider-anthropic.d.ts

@@ -15,9 +15,19 @@ export type AnthropicOptions = {
      */
     baseUrl?: string | undefined;
     /**
-     * - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`.
+     * - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`. NOTE: on its own this rarely helps a tool loop — Anthropic's minimum cacheable prefix is 1024–4096 tokens (model-dependent) and a typical system persona is a few hundred, so it silently never caches. The transcript is where a tool loop's tokens actually live — see `cacheMessages`.
      */
     cacheSystem?: boolean | undefined;
+    /**
+     * - Opt-in TRANSCRIPT caching (BA-1): roll a `cache_control` breakpoint onto the last content block of the last message, so Anthropic caches the whole conversation prefix and the loop stops re-buying it at full price every round. In a tool loop the transcript IS the tool results (file bodies from `shell_read`) and it always ENDS on one, which `_toAnthropicMessage` rebuilds from scratch — so no caller-side seam (`assemble` included) can reach it, and this has to live in the provider. Measured on `claude-sonnet-5` with a ~15k-token tool-result transcript (`poc/ba1-message-caching.mjs`): steady state **$0.0753 → $0.0110 per round, 6.8x cheaper**; round 1 pays a 1.25x cache WRITE once. Off by default — it changes the wire format, so adopters opt in. Overridable per call via `generate(..., { cacheMessages })`. **Interaction:** a destructive `trim`/stash fold that rewrites the transcript PREFIX invalidates the cache (the prefix is the cache key), so a fold must keep the head stable or you re-pay the write premium every round for nothing.
+     */
+    cacheMessages?: boolean | undefined;
+    /**
+     * - Opt-in extended thinking (BA-7), forwarded to `body.thinking` VERBATIM and unvalidated — e.g. `{ type: 'adaptive' }`, or `{ type: 'adaptive', display: 'summarized' }` to surface the reasoning (the default `display` is `'omitted'`). Deliberately opaque: this parameter has already broken once (`budget_tokens` was removed and now 400s on `claude-sonnet-5` / Opus 4.7+), and a library that reshapes it would need a release every time the API moves. Overridable per call via `generate(..., { thinking })`; pass `null` there to suppress an instance default.
+     *
+     * **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.
+     */
+    thinking?: any;
     /**
      * - 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).
      */
@@ -31,7 +41,11 @@ export type AnthropicOptions = {
  * @property {string} [apiKey] - Anthropic API key (required).
  * @property {string} [model='claude-haiku-4-5-20251001'] - Model ID.
  * @property {string} [baseUrl='https://api.anthropic.com/v1'] - API base (override for proxies/gateways; the request posts to `${baseUrl}/messages`).
- * @property {boolean} [cacheSystem=false] - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`.
+ * @property {boolean} [cacheSystem=false] - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`. NOTE: on its own this rarely helps a tool loop — Anthropic's minimum cacheable prefix is 1024–4096 tokens (model-dependent) and a typical system persona is a few hundred, so it silently never caches. The transcript is where a tool loop's tokens actually live — see `cacheMessages`.
+ * @property {boolean} [cacheMessages=false] - Opt-in TRANSCRIPT caching (BA-1): roll a `cache_control` breakpoint onto the last content block of the last message, so Anthropic caches the whole conversation prefix and the loop stops re-buying it at full price every round. In a tool loop the transcript IS the tool results (file bodies from `shell_read`) and it always ENDS on one, which `_toAnthropicMessage` rebuilds from scratch — so no caller-side seam (`assemble` included) can reach it, and this has to live in the provider. Measured on `claude-sonnet-5` with a ~15k-token tool-result transcript (`poc/ba1-message-caching.mjs`): steady state **$0.0753 → $0.0110 per round, 6.8x cheaper**; round 1 pays a 1.25x cache WRITE once. Off by default — it changes the wire format, so adopters opt in. Overridable per call via `generate(..., { cacheMessages })`. **Interaction:** a destructive `trim`/stash fold that rewrites the transcript PREFIX invalidates the cache (the prefix is the cache key), so a fold must keep the head stable or you re-pay the write premium every round for nothing.
+ * @property {any} [thinking] - Opt-in extended thinking (BA-7), forwarded to `body.thinking` VERBATIM and unvalidated — e.g. `{ type: 'adaptive' }`, or `{ type: 'adaptive', display: 'summarized' }` to surface the reasoning (the default `display` is `'omitted'`). Deliberately opaque: this parameter has already broken once (`budget_tokens` was removed and now 400s on `claude-sonnet-5` / Opus 4.7+), and a library that reshapes it would need a release every time the API moves. Overridable per call via `generate(..., { thinking })`; pass `null` there to suppress an instance default.
+ *
+ *   **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).
  */
 export class AnthropicProvider {
@@ -44,6 +58,8 @@ export class AnthropicProvider {
     model: string;
     baseUrl: string;
     cacheSystem: boolean;
+    cacheMessages: boolean;
+    thinking: any;
     exposeErrorBody: boolean;
     /**
      * Generate a response from the Anthropic API.
@@ -57,6 +73,20 @@ export class AnthropicProvider {
     /** One-time warning that this model rejected `temperature` and the request was retried without it (BA-10). */
     _warnTemperatureDropped(): void;
     _warnedTempDropped: boolean | undefined;
+    /**
+     * BA-7: the provider-native blocks to replay at the FRONT of an assistant turn's content, or `[]`.
+     *
+     * Only ever returns blocks this model itself produced. The tag carries `this.model` (the CONFIGURED
+     * id, not the response's resolved one — those can differ by date suffix, and a mismatch there would
+     * silently disable preservation, which is the very bug class BA-7 exists to close).
+     *
+     * Front, because Anthropic requires `thinking` to lead the content array — the verbatim order we
+     * measured a successful round-trip on (`poc/ba7-thinking-contract.mjs`, R3).
+     *
+     * @param {Message} msg
+     * @returns {any[]}
+     */
+    _nativeBlocks(msg: Message): any[];
     /**
      * @param {Message} msg
      * @returns {any}

package/src/provider-anthropic.js

@@ -4,6 +4,7 @@ const https = require('https');
 const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
+const { normalizeStopReason } = require('./provider-stop-reason');
 
 /** @param {string} hostname @returns {boolean} */
 function isLoopbackHost(hostname) {
@@ -20,7 +21,11 @@ function isLoopbackHost(hostname) {
  * @property {string} [apiKey] - Anthropic API key (required).
  * @property {string} [model='claude-haiku-4-5-20251001'] - Model ID.
  * @property {string} [baseUrl='https://api.anthropic.com/v1'] - API base (override for proxies/gateways; the request posts to `${baseUrl}/messages`).
- * @property {boolean} [cacheSystem=false] - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`.
+ * @property {boolean} [cacheSystem=false] - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`. NOTE: on its own this rarely helps a tool loop — Anthropic's minimum cacheable prefix is 1024–4096 tokens (model-dependent) and a typical system persona is a few hundred, so it silently never caches. The transcript is where a tool loop's tokens actually live — see `cacheMessages`.
+ * @property {boolean} [cacheMessages=false] - Opt-in TRANSCRIPT caching (BA-1): roll a `cache_control` breakpoint onto the last content block of the last message, so Anthropic caches the whole conversation prefix and the loop stops re-buying it at full price every round. In a tool loop the transcript IS the tool results (file bodies from `shell_read`) and it always ENDS on one, which `_toAnthropicMessage` rebuilds from scratch — so no caller-side seam (`assemble` included) can reach it, and this has to live in the provider. Measured on `claude-sonnet-5` with a ~15k-token tool-result transcript (`poc/ba1-message-caching.mjs`): steady state **$0.0753 → $0.0110 per round, 6.8x cheaper**; round 1 pays a 1.25x cache WRITE once. Off by default — it changes the wire format, so adopters opt in. Overridable per call via `generate(..., { cacheMessages })`. **Interaction:** a destructive `trim`/stash fold that rewrites the transcript PREFIX invalidates the cache (the prefix is the cache key), so a fold must keep the head stable or you re-pay the write premium every round for nothing.
+ * @property {any} [thinking] - Opt-in extended thinking (BA-7), forwarded to `body.thinking` VERBATIM and unvalidated — e.g. `{ type: 'adaptive' }`, or `{ type: 'adaptive', display: 'summarized' }` to surface the reasoning (the default `display` is `'omitted'`). Deliberately opaque: this parameter has already broken once (`budget_tokens` was removed and now 400s on `claude-sonnet-5` / Opus 4.7+), and a library that reshapes it would need a release every time the API moves. Overridable per call via `generate(..., { thinking })`; pass `null` there to suppress an instance default.
+ *
+ *   **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).
  */
 
@@ -38,6 +43,13 @@ class AnthropicProvider {
     // Anthropic caches it (unlike OpenAI/Gemini, Anthropic does NOT auto-cache — without this its
     // cache_read/cache_creation tiers are always 0). Default off keeps requests byte-identical to before.
     this.cacheSystem = options.cacheSystem === true;
+    this.cacheMessages = options.cacheMessages === true;
+    // BA-7: forwarded to `body.thinking` VERBATIM — deliberately unvalidated and un-reshaped. This
+    // parameter has already broken once (`budget_tokens` was removed and now 400s on sonnet-5 /
+    // Opus 4.7+; `{type:'adaptive'}` replaced it). A library that parses it would have to ship a
+    // release every time Anthropic moves; passing it through means the caller can always express
+    // the current API. Omit it to keep today's body byte-identical.
+    this.thinking = options.thinking != null ? options.thinking : null;
     // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
     this.exposeErrorBody = options.exposeErrorBody === true;
   }
@@ -76,6 +88,33 @@ class AnthropicProvider {
       system = [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
     }
 
+    // BA-1: roll a cache breakpoint onto the LAST content block of the LAST message. Anthropic caches the
+    // whole prefix up to the mark, and rolling it forward each round keeps the GROWING transcript cached
+    // — otherwise a tool loop re-buys its entire history at full input price, every single round.
+    //
+    // This MUST live here, not in a caller-side seam: in a tool loop the transcript IS the tool results,
+    // it always ENDS on one, and `_toAnthropicMessage` rebuilds `role:'tool'` messages into fresh
+    // `tool_result` blocks — discarding anything a caller attached. There is no other reachable seam.
+    //
+    // Copy-on-write, deliberately: a caller's `content` array is passed through by reference, so marking
+    // it in place would mutate the caller's own message objects and leave a stale breakpoint behind on
+    // every later round (Anthropic allows at most 4, and a stray one silently shifts the cache key).
+    const cacheMessages = options.cacheMessages != null ? options.cacheMessages === true : this.cacheMessages;
+    if (cacheMessages && msgs.length > 0) {
+      const i = msgs.length - 1;
+      const last = msgs[i];
+      if (Array.isArray(last.content) && last.content.length > 0) {
+        const blocks = last.content.slice();
+        blocks[blocks.length - 1] = { ...blocks[blocks.length - 1], cache_control: { type: 'ephemeral' } };
+        msgs[i] = { ...last, content: blocks };
+      } else if (typeof last.content === 'string' && last.content.length > 0) {
+        msgs[i] = { ...last, content: [{ type: 'text', text: last.content, cache_control: { type: 'ephemeral' } }] };
+      }
+      // An empty-content message gets no mark — there is no block to hang it on, and a synthesized empty
+      // one would be a wire error. Under the cache minimum (1024–4096 tok, model-dependent) Anthropic
+      // silently doesn't cache: harmless, just no saving. Never an error.
+    }
+
     /** @type {Record<string, any>} */
     const body = {
       model: this.model,
@@ -84,6 +123,14 @@ class AnthropicProvider {
       ...(system && { system }),
       ...(options.temperature != null && { temperature: options.temperature }),
     };
+
+    // BA-7 (b). Measured caveat, and it matters: on `claude-sonnet-5` adaptive thinking is ALREADY
+    // the default — sending this changed the thinking rate not at all (2/10 vs 3/10 rounds,
+    // `poc/ba7-adaptive-default.mjs`). So this option does NOT "turn thinking on"; it lets you pin
+    // the mode and reach `display`/`effort`. The fix that actually mattered is the preservation
+    // above, which applies whether or not you ever set this.
+    const thinking = options.thinking !== undefined ? options.thinking : this.thinking;
+    if (thinking) body.thinking = thinking;
     if (tools.length > 0) {
       body.tools = tools.map(t => ({
         name: t.name,
@@ -105,17 +152,34 @@ class AnthropicProvider {
     let text = '';
     /** @type {import('../types').ToolCall[]} */
     const toolCalls = [];
+    // BA-7: everything that is NOT text/tool_use is a block our normalized {text, toolCalls} shape
+    // cannot express — today that means `thinking` and `redacted_thinking`. We used to drop these on
+    // the floor. Anthropic's contract is that they are echoed back UNCHANGED (signature included) when
+    // continuing a tool-use conversation, so they are collected OPAQUELY here: whatever the block is,
+    // we keep its bytes. Deliberately not a `block.type === 'thinking'` check — a future block type
+    // would be silently dropped again, which is the exact bug being fixed.
+    /** @type {any[]} */
+    const nativeBlocks = [];
     for (const block of data.content) {
       if (block.type === 'text') text += block.text;
-      if (block.type === 'tool_use') {
-        toolCalls.push({ id: block.id, name: block.name, arguments: block.input });
-      }
+      else if (block.type === 'tool_use') toolCalls.push({ id: block.id, name: block.name, arguments: block.input });
+      else nativeBlocks.push(block);
     }
 
     return {
       text,
       toolCalls,
       model: data.model || this.model,
+      // BA-6: why generation ended. `max_tokens` here means the API CUT THIS ROUND OFF — the Loop must
+      // not read it as a finished turn, and must not execute any tool call it carries (a complete call
+      // arrives as `tool_use`; one riding a `max_tokens` round was cut off mid-generation).
+      stopReason: normalizeStopReason(data.stop_reason, 'anthropic', { hasToolCalls: toolCalls.length > 0 }),
+      // BA-7: the opaque blocks, tagged so they can only ever be replayed to the model that signed
+      // them. A thinking `signature` is model-bound; on a mismatch we drop them and degrade to the
+      // pre-BA-7 behavior (a lossy request that still succeeds) rather than risk a 400.
+      ...(nativeBlocks.length > 0 && {
+        providerBlocks: { provider: 'anthropic', model: this.model, blocks: nativeBlocks },
+      }),
       // Anthropic's `input_tokens` is ALREADY the uncached remainder (cached tokens are reported
       // separately, not folded in — verified live), so no subtraction here, unlike OpenAI/Gemini.
       usage: {
@@ -135,6 +199,29 @@ class AnthropicProvider {
     console.warn(`[AnthropicProvider] '${this.model}' rejected a non-default 'temperature' (unsupported/deprecated) — retrying without it. Further drops from this provider instance are silent.`);
   }
 
+  /**
+   * BA-7: the provider-native blocks to replay at the FRONT of an assistant turn's content, or `[]`.
+   *
+   * Only ever returns blocks this model itself produced. The tag carries `this.model` (the CONFIGURED
+   * id, not the response's resolved one — those can differ by date suffix, and a mismatch there would
+   * silently disable preservation, which is the very bug class BA-7 exists to close).
+   *
+   * Front, because Anthropic requires `thinking` to lead the content array — the verbatim order we
+   * measured a successful round-trip on (`poc/ba7-thinking-contract.mjs`, R3).
+   *
+   * @param {Message} msg
+   * @returns {any[]}
+   */
+  _nativeBlocks(msg) {
+    const pb = /** @type {any} */ (msg).providerBlocks;
+    if (!pb || pb.provider !== 'anthropic' || !Array.isArray(pb.blocks) || pb.blocks.length === 0) return [];
+    // A thinking signature is bound to the model that issued it. Swap models mid-transcript and these
+    // blocks are not ours to replay: drop them (lossy but valid) rather than send a signature this
+    // model will reject.
+    if (pb.model !== this.model) return [];
+    return pb.blocks;
+  }
+
   /**
    * @param {Message} msg
    * @returns {any}
@@ -155,6 +242,11 @@ class AnthropicProvider {
     if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
       /** @type {any[]} */
       const content = [];
+      // BA-7: thinking blocks lead, then text, then tool_use — this is THE turn the contract is about
+      // (continuing a tool-use conversation). Note the normalized `content`/`tool_calls` stay the
+      // source of truth: we replay only the opaque blocks, never a cached copy of the text, so a
+      // `trim`/`assemble` seam that rewrites this message is not silently undone.
+      content.push(...this._nativeBlocks(msg));
       if (msg.content) content.push({ type: 'text', text: msg.content });
       for (const tc of msg.tool_calls) {
         content.push({
@@ -168,6 +260,16 @@ class AnthropicProvider {
       }
       return { role: 'assistant', content };
     }
+    // A tool-call-free assistant turn can still carry thinking (a final answer, or an earlier turn a
+    // caller replays into a fresh run). Same rule: native blocks lead.
+    if (msg.role === 'assistant') {
+      const native = this._nativeBlocks(msg);
+      if (native.length > 0) {
+        const content = [...native];
+        if (msg.content) content.push({ type: 'text', text: msg.content });
+        return { role: 'assistant', content };
+      }
+    }
     return { role: msg.role, content: msg.content };
   }
 

package/src/provider-clipipe.js

@@ -165,39 +165,65 @@ class CLIPipeProvider {
 
       let stdout = '';
       let stderr = '';
-      let killed = false;
 
-      child.stdout.on('data', d => { stdout += d; this.onChunk?.(d.toString()); });
-      child.stderr.on('data', d => { stderr += d; });
-
-      child.on('error', err => {
-        reject(new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${err.message}`, /** @type {any} */ ({ status: 0 })));
-      });
+      // Settle exactly once, no matter which combination of events fires. 'close' can be
+      // withheld indefinitely when the CLI spawns a grandchild that inherits its stdio pipes
+      // (the child exits, but the pipes stay open) — observed live as a generate() promise
+      // that never settled. Every path below funnels through settle().
+      let settled = false;
+      /** @type {NodeJS.Timeout[]} */
+      const timers = [];
+      const later = (fn, ms) => { timers.push(setTimeout(fn, ms)); };
+      const settle = (/** @type {Error|null} */ err, text = '') => {
+        if (settled) return;
+        settled = true;
+        for (const t of timers) clearTimeout(t);
+        if (err) reject(err); else resolve(text);
+      };
 
-      child.on('close', code => {
-        if (killed) return; // timeout already rejected
+      const finish = (/** @type {number|null} */ code) => {
         if (code !== 0) {
-          return reject(new ProviderError(`[CLIPipeProvider] process exited with code ${code}: ${stderr.trim()}`, /** @type {any} */ ({ status: code })));
+          // The claude CLI reports errors on STDOUT (a JSON envelope) with stderr often
+          // empty — fall back to a stdout tail so the operator never sees a blank reason.
+          const detail = stderr.trim() || (stdout.trim() ? `(stderr empty) stdout: ${stdout.trim().slice(-400)}` : '');
+          return settle(new ProviderError(`[CLIPipeProvider] process exited with code ${code}: ${detail}`, /** @type {any} */ ({ status: code })));
         }
         const text = stdout.trim();
         if (!text) {
-          return reject(new ProviderError('[CLIPipeProvider] process produced no output', /** @type {any} */ ({ status: 0 })));
+          return settle(new ProviderError('[CLIPipeProvider] process produced no output', /** @type {any} */ ({ status: 0 })));
+        }
+        settle(null, text);
+      };
+
+      child.stdout.on('data', d => {
+        stdout += d;
+        try {
+          this.onChunk?.(d.toString());
+        } catch (err) {
+          // an observer callback must fail the call loudly, never crash the host process
+          settle(new ProviderError(`[CLIPipeProvider] onChunk callback threw: ${/** @type {Error} */ (err).message}`, /** @type {any} */ ({ status: 0 })));
         }
-        resolve(text);
+      });
+      child.stderr.on('data', d => { stderr += d; });
+
+      child.on('error', err => {
+        settle(new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${err.message}`, /** @type {any} */ ({ status: 0 })));
       });
 
-      // Timeout handling
-      const timer = setTimeout(() => {
-        killed = true;
+      // Primary completion path: all stdio drained.
+      child.on('close', code => finish(code));
+
+      // Fallback: the process exited but 'close' is being held open by inherited pipes.
+      // Give real drainage a short grace, then finish with what has arrived — a bounded
+      // wait, never a hang.
+      child.on('exit', code => later(() => finish(code), 2000));
+
+      later(() => {
         child.kill('SIGTERM');
-        setTimeout(() => {
-          try { child.kill('SIGKILL'); } catch (_) {}
-        }, 1000);
-        reject(new ProviderError(`[CLIPipeProvider] timed out after ${this.timeout}ms`, /** @type {any} */ ({ status: 0 })));
+        setTimeout(() => { try { child.kill('SIGKILL'); } catch (_) {} }, 1000).unref?.();
+        settle(new ProviderError(`[CLIPipeProvider] timed out after ${this.timeout}ms`, /** @type {any} */ ({ status: 0 })));
       }, this.timeout);
 
-      child.on('close', () => clearTimeout(timer));
-
       // Write prompt to stdin — catch errors silently (process may exit early)
       child.stdin.on('error', () => {});
       child.stdin.end(prompt);

package/src/provider-gemini.js

@@ -4,6 +4,7 @@ const https = require('https');
 const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
+const { normalizeStopReason } = require('./provider-stop-reason');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -130,6 +131,15 @@ class GeminiProvider {
       text,
       toolCalls,
       model: data.modelVersion || this.model,
+      // BA-6: `MAX_TOKENS` ⇒ cut off at the output cap. VERIFIED LIVE on `gemini-2.5-flash`
+      // (`poc/ba6-stop-reason-gemini-ollama.mjs`): STOP→end_turn, MAX_TOKENS→max_tokens. An unrecognized
+      // value still falls through to `null` (today's behavior), never to a false truncation.
+      //
+      // Gemini has NO tool_use finish reason — a complete function call comes back as `STOP` (measured).
+      // `hasToolCalls` lets the normalizer report the round for what it was: a round that stopped to CALL
+      // A TOOL, not one the model chose to end. Without it, `stopReason` would say `end_turn` here and
+      // `tool_use` on Anthropic/OpenAI for the identical event.
+      stopReason: normalizeStopReason(data.candidates?.[0]?.finishReason, 'gemini', { hasToolCalls: toolCalls.length > 0 }),
       usage: this._normalizeUsage(data.usageMetadata),
       ...(temperatureDropped && { temperatureDropped: true }),
     };

package/src/provider-ollama.d.ts

@@ -27,7 +27,7 @@ export class OllamaProvider {
      * 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).
+     * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
      */

package/src/provider-ollama.js

@@ -3,6 +3,7 @@
 const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
+const { normalizeStopReason } = require('./provider-stop-reason');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -30,17 +31,29 @@ class OllamaProvider {
    * 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).
+   * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
    */
   async generate(messages, tools = [], options = {}) {
+    // Ollama nests generation params under `options` (its `num_predict` is the output cap — the
+    // equivalent of `max_tokens` everywhere else).
+    //
+    // `maxTokens` was NOT forwarded here before, while every other provider honoured it — so a caller
+    // capping output on Ollama was silently ignored and generated unbounded. Found by the BA-6 map
+    // probe: a 16-token cap produced `done_reason: 'stop'` because nothing ever truncated. The map was
+    // right; the cap never reached the wire.
+    /** @type {Record<string, any>} */
+    const genOptions = {
+      ...(options.temperature != null && { temperature: options.temperature }),
+      ...(options.maxTokens != null && { num_predict: options.maxTokens }),
+    };
     /** @type {Record<string, any>} */
     const body = {
       model: this.model,
       messages,
       stream: false,
-      ...(options.temperature != null && { options: { temperature: options.temperature } }),
+      ...(Object.keys(genOptions).length > 0 && { options: genOptions }),
     };
     if (tools.length > 0) {
       body.tools = tools.map(t => ({
@@ -59,16 +72,26 @@ class OllamaProvider {
     });
     const msg = data.message || {};
 
+    /** @type {import('../types').ToolCall[]} */
+    const toolCalls = (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
+      id: tc.id || `call_${Date.now()}`,
+      name: tc.function.name,
+      arguments: typeof tc.function.arguments === 'string'
+        ? JSON.parse(tc.function.arguments)
+        : tc.function.arguments,
+    }));
+
     return {
       text: msg.content || '',
-      toolCalls: (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
-        id: tc.id || `call_${Date.now()}`,
-        name: tc.function.name,
-        arguments: typeof tc.function.arguments === 'string'
-          ? JSON.parse(tc.function.arguments)
-          : tc.function.arguments,
-      })),
+      toolCalls,
       model: data.model || this.model,
+      // BA-6: `length` ⇒ cut off at num_predict. VERIFIED LIVE on qwen2.5:0.5b
+      // (`poc/ba6-stop-reason-gemini-ollama.mjs`): stop→end_turn, length→max_tokens. Lifecycle values
+      // (`load`/`unload`) stay deliberately unmapped rather than forced into the vocabulary.
+      //
+      // Like Gemini, Ollama has NO tool_use done_reason — a complete tool call returns `stop` (measured).
+      // `hasToolCalls` lets the normalizer say so, instead of reporting a tool round as a clean finish.
+      stopReason: normalizeStopReason(data.done_reason, 'ollama', { hasToolCalls: toolCalls.length > 0 }),
       usage: {
         inputTokens: data.prompt_eval_count || 0,
         outputTokens: data.eval_count || 0,

package/src/provider-openai.js

@@ -4,6 +4,7 @@ const https = require('https');
 const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
+const { normalizeStopReason } = require('./provider-stop-reason');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -73,14 +74,22 @@ class OpenAIProvider {
     const choice = data.choices[0];
     const msg = choice.message;
 
+    /** @type {import('../types').ToolCall[]} */
+    const toolCalls = (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: JSON.parse(tc.function.arguments),
+    }));
+
     return {
       text: msg.content || '',
-      toolCalls: (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
-        id: tc.id,
-        name: tc.function.name,
-        arguments: JSON.parse(tc.function.arguments),
-      })),
+      toolCalls,
       model: data.model || this.model,
+      // BA-6: `length` ⇒ cut off at the output cap (normalized to 'max_tokens'). Note OpenAI refuses to
+      // emit a tool call it cannot finish — it 400s instead — so a truncated round here carries no
+      // tool calls at all; the Loop's refusal to execute them is a no-op on this provider, and a
+      // load-bearing guard on Anthropic, which DOES emit the cut-off call.
+      stopReason: normalizeStopReason(choice?.finish_reason, 'openai', { hasToolCalls: toolCalls.length > 0 }),
       usage: this._normalizeUsage(data.usage),
       ...(temperatureDropped && { temperatureDropped: true }),
     };

package/src/provider-stop-reason.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Map a provider's native finish-reason value onto the neutral vocabulary.
+ *
+ * @param {string|null|undefined} raw - the provider's native value (`stop_reason` / `finish_reason` /
+ *   `finishReason` / `done_reason`). Absent or non-string ⇒ `null` (pre-BA-6 behavior).
+ * @param {'anthropic'|'openai'|'gemini'|'ollama'} provider - which table to read.
+ * @param {{hasToolCalls?: boolean}} [ctx] - what the round actually CARRIED. See below: two providers
+ *   cannot express "stopped to call a tool" in their finish-reason field at all, so the round's own
+ *   content is the only place that fact exists.
+ * @returns {string|null} a neutral value, an unrecognized value passed through verbatim, or `null`.
+ */
+export function normalizeStopReason(raw: string | null | undefined, provider: "anthropic" | "openai" | "gemini" | "ollama", ctx?: {
+    hasToolCalls?: boolean;
+}): string | null;
+/**
+ * Did this round get CUT OFF at the output-token cap?
+ *
+ * The one predicate the Loop acts on. Deliberately narrow: `context_exceeded`, `refusal` and
+ * `pause_turn` are all "not a normal finish" but they are NOT output-cap truncations and must not be
+ * folded in here — `pause_turn` in particular is a RESUMABLE state, and erroring on it would break
+ * server-side tool flows that are working exactly as designed.
+ *
+ * @param {string|null|undefined} stopReason - a NEUTRAL value (post-{@link normalizeStopReason}).
+ * @returns {boolean}
+ */
+export function isTruncated(stopReason: string | null | undefined): boolean;