bare-agent 0.42.0 → 0.43.0

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.42.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.16.0` optional peer for governance) | Apache 2.0
+> v0.43.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.42.0",
+  "version": "0.43.0",
   "files": [
     "index.js",
     "index.d.ts",

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, model: 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, malformedToolCall?: {name: string|undefined, error: string}, 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
@@ -199,6 +199,10 @@ export class Loop {
         model: string | null;
         msgs: Message[];
         metrics: RunMetrics;
+        malformedToolCall?: {
+            name: string | undefined;
+            error: string;
+        };
         temperatureDropped?: boolean;
     }>;
     _warnedTruncated: boolean | undefined;
@@ -228,7 +232,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, model: 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, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
      */
     chat(text: string, tools?: ToolDef[], options?: Record<string, any>): Promise<{
         text: string;
@@ -240,6 +244,10 @@ export class Loop {
         model: string | null;
         msgs: Message[];
         metrics: RunMetrics;
+        malformedToolCall?: {
+            name: string | undefined;
+            error: string;
+        };
         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, model: 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, malformedToolCall?: {name: string|undefined, error: string}, 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
@@ -547,6 +547,14 @@ class Loop {
     // 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-27: the most recent round's malformed-tool-call marker, or null. A model can emit a tool call
+    // whose arguments are syntactically-broken JSON; the provider returns NO usable tool calls plus this
+    // marker (rather than throwing and losing the billed round). Surfaced on the run's return like
+    // lastStopReason, so a Loop caller (e.g. the bareloop adopter — which reads run(), not generate())
+    // can tell "the model sent a broken call" apart from "the model sent no call at all" — both present
+    // as `toolCalls: []`. Reset each completed round; a malformed round always terminates the run (no
+    // usable call to continue with), so it can only be non-null on the round that returns.
+    let lastMalformedToolCall = 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.
@@ -583,7 +591,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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: stuckTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
       return null;
     };
@@ -830,7 +838,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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       lastUsage = result.usage || lastUsage;
@@ -843,6 +851,9 @@ class Loop {
       // 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;
+      // BA-27: capture (and reset) this round's malformed-tool-call marker for surfacing on the return.
+      lastMalformedToolCall = (result.malformedToolCall && typeof result.malformedToolCall === 'object')
+        ? result.malformedToolCall : null;
       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
@@ -927,7 +938,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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: session.error, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // BA-13: classify this round's terminal signal against the neutral stop-reason vocabulary. BA-6
@@ -992,7 +1003,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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: errorTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // No tool calls — LLM gave a final text response
@@ -1012,7 +1023,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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // Execute tool calls
@@ -1121,7 +1132,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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+              return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
             }
             continue;
           }
@@ -1195,7 +1206,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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
       }
       throw err;
     }
@@ -1225,20 +1236,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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+            return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+      return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(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, model: lastModel, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+    return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, stopReason: lastStopReason, model: lastModel, msgs, metrics: finalizeMetrics(), ...(lastMalformedToolCall && { malformedToolCall: lastMalformedToolCall }), ...(temperatureDropped && { temperatureDropped: true }) };
   }
 
   /**
@@ -1311,7 +1322,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, model: 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, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
    */
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });

package/src/provider-ollama.js

@@ -6,6 +6,7 @@ const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
 const { resolveTimeoutMs, applyRequestBounds, guardResponseSettles } = require('./provider-http');
 const { hasUsageSignal } = require('./provider-usage');
+const { parseToolCalls } = require('./provider-toolcalls');
 
 // BA-24: raw Ollama usage fields. Any present (even 0) ⇒ a usage signal; none ⇒ null (unpriceable).
 const OLLAMA_USAGE_KEYS = ['prompt_eval_count', 'eval_count'];
@@ -85,8 +86,11 @@ class OllamaProvider {
     });
     const msg = data.message || {};
 
-    /** @type {import('../types').ToolCall[]} */
-    const toolCalls = (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
+    // BA-27: Ollama returns `function.arguments` as an OBJECT for well-formed calls, but some builds
+    // pass it through as a model-generated STRING — a malformed one must not throw here (the round
+    // already billed; a throw loses usage + hangs metering). Mirror the OpenAI path: no usable calls
+    // + a marker, never repair. The object case is untouched (JSON.parse only runs on a string).
+    const { toolCalls, malformedToolCall } = parseToolCalls(msg.tool_calls, (/** @type {any} */ tc) => ({
       id: tc.id || `call_${Date.now()}`,
       name: tc.function.name,
       arguments: typeof tc.function.arguments === 'string'
@@ -97,6 +101,7 @@ class OllamaProvider {
     return {
       text: msg.content || '',
       toolCalls,
+      ...(malformedToolCall && { malformedToolCall }),
       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

package/src/provider-openai.js

@@ -7,6 +7,7 @@ const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
 const { resolveTimeoutMs, applyRequestBounds, guardResponseSettles } = require('./provider-http');
 const { hasUsageSignal } = require('./provider-usage');
+const { parseToolCalls } = require('./provider-toolcalls');
 
 // BA-24: raw OpenAI usage fields. Any present (even 0) ⇒ a usage signal; none ⇒ null (unpriceable).
 const OPENAI_USAGE_KEYS = ['prompt_tokens', 'completion_tokens', 'prompt_tokens_details'];
@@ -30,7 +31,13 @@ function toOpenAIToolChoice(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)}`);
+  let describedChoice;
+  try {
+    describedChoice = JSON.stringify(choice);
+  } catch {
+    describedChoice = '<unserializable>';
+  }
+  throw new ProviderError(`[OpenAIProvider] invalid toolChoice: expected 'auto', 'required', or { name }, got ${describedChoice}`);
 }
 
 /** @param {string} hostname @returns {boolean} */
@@ -125,11 +132,27 @@ class OpenAIProvider {
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
     });
+    // BA-27: a successful 200 whose body carries no `choices` (some OpenAI-compat servers return a
+    // 4xx-shaped error object with HTTP 200) reached `data.choices[0]` as a bare TypeError with no
+    // context. Throw a ProviderError carrying the first ~300 bytes of the body so it can be told apart.
+    if (!Array.isArray(data.choices) || data.choices.length === 0) {
+      // The `context.bound:'no-choices'` marker ALWAYS distinguishes a 4xx-in-200 from other failures.
+      // The raw body snippet is gated behind `exposeErrorBody` (default off) like every other error path
+      // here — an unexpected field in a compat server's error body must not leak into logs/audit rows
+      // (err.message flows into Loop.run().error) unless the caller opts in.
+      throw new ProviderError(
+        `[OpenAIProvider] response has no choices` +
+          (this.exposeErrorBody ? `: ${JSON.stringify(data).slice(0, 300)}` : ''),
+        /** @type {any} */ ({ context: { bound: 'no-choices' }, body: this.exposeErrorBody ? data : undefined })
+      );
+    }
     const choice = data.choices[0];
     const msg = choice.message;
 
-    /** @type {import('../types').ToolCall[]} */
-    const toolCalls = (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
+    // BA-27: `function.arguments` is a model-generated JSON STRING — a malformed one (extra brace,
+    // truncated object) must NOT throw here (the round already billed; a throw loses usage + hangs
+    // metering). parseToolCalls returns no usable calls + a marker; usage/model still flow below.
+    const { toolCalls, malformedToolCall } = parseToolCalls(msg.tool_calls, (/** @type {any} */ tc) => ({
       id: tc.id,
       name: tc.function.name,
       arguments: JSON.parse(tc.function.arguments),
@@ -138,6 +161,7 @@ class OpenAIProvider {
     return {
       text: msg.content || '',
       toolCalls,
+      ...(malformedToolCall && { malformedToolCall }),
       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

package/src/provider-toolcalls.d.ts

@@ -0,0 +1,29 @@
+export type ToolCall = import("../types").ToolCall;
+/** @typedef {import('../types').ToolCall} ToolCall */
+/**
+ * BA-27 — parse a round's raw tool calls into the neutral {@link ToolCall} shape WITHOUT throwing on
+ * malformed arguments.
+ *
+ * OpenAI-compatible providers return `function.arguments` as a JSON STRING the model generated, so a
+ * model that emits syntactically-broken JSON (an extra brace, a truncated object — seen live on
+ * deepseek-flash and other compat servers) makes a bare `JSON.parse` throw a `SyntaxError`. That throw
+ * lands AFTER the HTTP round already succeeded and `usage` came back, so it loses the billed round and
+ * hangs any metering, and no caller can tell "the model emitted bad arguments" from a transport fault.
+ *
+ * Instead: on the FIRST unparseable call, return NO usable tool calls (`toolCalls: []`) plus a marker
+ * `{ name, error }`. The caller treats it as "no usable tool call" and retries; usage/model still flow
+ * so the round is metered. We NEVER repair the JSON — a guessed brace could execute the wrong action.
+ * All-or-nothing (mirrors BA-4's refusal to execute a truncated round's calls): a partial set risks
+ * running half a decomposed intent, so one bad call voids the whole round's calls.
+ *
+ * @param {any[]} rawToolCalls - provider-native tool-call entries (may be undefined/empty)
+ * @param {(tc: any) => ToolCall} mapOne - maps one raw entry to a ToolCall; MAY throw on bad arguments
+ * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string } }}
+ */
+export function parseToolCalls(rawToolCalls: any[], mapOne: (tc: any) => ToolCall): {
+    toolCalls: ToolCall[];
+    malformedToolCall?: {
+        name: string | undefined;
+        error: string;
+    };
+};

package/src/provider-toolcalls.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/** @typedef {import('../types').ToolCall} ToolCall */
+
+/**
+ * BA-27 — parse a round's raw tool calls into the neutral {@link ToolCall} shape WITHOUT throwing on
+ * malformed arguments.
+ *
+ * OpenAI-compatible providers return `function.arguments` as a JSON STRING the model generated, so a
+ * model that emits syntactically-broken JSON (an extra brace, a truncated object — seen live on
+ * deepseek-flash and other compat servers) makes a bare `JSON.parse` throw a `SyntaxError`. That throw
+ * lands AFTER the HTTP round already succeeded and `usage` came back, so it loses the billed round and
+ * hangs any metering, and no caller can tell "the model emitted bad arguments" from a transport fault.
+ *
+ * Instead: on the FIRST unparseable call, return NO usable tool calls (`toolCalls: []`) plus a marker
+ * `{ name, error }`. The caller treats it as "no usable tool call" and retries; usage/model still flow
+ * so the round is metered. We NEVER repair the JSON — a guessed brace could execute the wrong action.
+ * All-or-nothing (mirrors BA-4's refusal to execute a truncated round's calls): a partial set risks
+ * running half a decomposed intent, so one bad call voids the whole round's calls.
+ *
+ * @param {any[]} rawToolCalls - provider-native tool-call entries (may be undefined/empty)
+ * @param {(tc: any) => ToolCall} mapOne - maps one raw entry to a ToolCall; MAY throw on bad arguments
+ * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string } }}
+ */
+function parseToolCalls(rawToolCalls, mapOne) {
+  const raw = rawToolCalls || [];
+  /** @type {ToolCall[]} */
+  const toolCalls = [];
+  for (const tc of raw) {
+    try {
+      toolCalls.push(mapOne(tc));
+    } catch (e) {
+      return {
+        toolCalls: [],
+        malformedToolCall: {
+          name: tc && tc.function ? tc.function.name : undefined,
+          error: e instanceof Error ? e.message : String(e),
+        },
+      };
+    }
+  }
+  return { toolCalls };
+}
+
+module.exports = { parseToolCalls };

package/types/index.d.ts

@@ -134,6 +134,16 @@ export interface GenerateResult {
    * temperature, not the one requested — callers reporting an effective temperature must honor this.
    */
   temperatureDropped?: boolean;
+  /**
+   * BA-27 — present ONLY when the model emitted a tool call whose `function.arguments` was
+   * syntactically-broken JSON (an extra brace, a truncated object). The billed round already
+   * succeeded, so rather than throw (which loses the round's usage and hangs metering), the provider
+   * returns NO usable tool calls (`toolCalls: []`) plus this marker. A caller treats it as "no usable
+   * tool call" and retries; `usage`/`model` still flow so the round is metered. The JSON is NEVER
+   * repaired. Absent on a clean round. OpenAI-compatible + Ollama string-arguments only; Anthropic
+   * arrives pre-parsed and cannot hit this.
+   */
+  malformedToolCall?: { name: string | undefined; error: string };
   /**
    * BA-7 — provider-native content blocks the normalized `{text, toolCalls}` shape cannot express
    * (Anthropic `thinking` / `redacted_thinking`), captured opaquely so the Loop can put them on the