bare-agent 0.26.0 → 0.27.0

package/src/provider-stop-reason.js

@@ -0,0 +1,148 @@
+/**
+ * BA-6 — normalize each provider's native finish-reason field to one neutral vocabulary.
+ *
+ * Every provider tells you WHY generation ended. Before this, bare-agent read the field on none of
+ * them (`grep -rn 'stop_reason\|finish_reason\|done_reason' src/` → zero hits), so a round the API
+ * CUT OFF at the token cap was indistinguishable from one the model chose to end — the Loop's rule is
+ * "no tool calls ⇒ final answer", and a truncation has no tool calls, so it returned as a clean finish
+ * with `error: null`. A truncation was laundered into a completion.
+ *
+ * The neutral vocabulary (what the Loop is allowed to reason about):
+ *
+ *   'end_turn'         the model finished of its own accord — the ONLY clean finish
+ *   'max_tokens'       CUT OFF at the output cap. NOT a finish. Load-bearing (see below).
+ *   'tool_use'         stopped to call a tool, and the call is COMPLETE
+ *   'stop_sequence'    hit a caller-supplied stop string — a legitimate finish
+ *   'refusal'          declined on safety grounds (Anthropic `refusal`, OpenAI `content_filter`, …)
+ *   'pause_turn'       server-side tool loop paused; the caller is expected to RESUME, not to error
+ *   'context_exceeded' ran out of CONTEXT WINDOW (distinct from running out of output budget)
+ *   null               provider didn't say / we don't recognize it
+ *
+ * `null` is the safe default and it is deliberate: an unmapped or absent value reproduces the
+ * pre-BA-6 behavior exactly. A wrong guess therefore degrades to the status quo rather than inventing
+ * a false truncation error on a healthy run. Unknown-but-present values pass through verbatim (a
+ * caller can still see them) but the Loop only ever ACTS on the values above.
+ *
+ * ── Why 'max_tokens' vs 'tool_use' is the load-bearing distinction (measured, not assumed) ──
+ *
+ * `poc/ba6-stop-reason-mapping.mjs`, real API, claude-sonnet-5 + gpt-4o-mini:
+ *
+ *   a COMPLETE tool call ALWAYS arrives tagged 'tool_use' — never 'max_tokens'.
+ *
+ * Anthropic returned `stop_reason: "tool_use"` with intact arguments even at a tight 1024-token cap;
+ * OpenAI refuses outright (HTTP 400) rather than emit a tool call it could not finish. Neither ever
+ * handed back a COMPLETE tool call tagged as truncated.
+ *
+ * The converse is the dangerous case, and it is not hypothetical — it is the BA-4 file-zeroing bug one
+ * layer up: a round tagged 'max_tokens' that CARRIES a tool call carries a tool call that was cut off
+ * mid-generation, whose arguments are missing keys. That is precisely how a `claude-haiku-4-5` worker
+ * emptied a 1789-line file — it hit the output cap mid-`shell_write`, the `content` argument never
+ * arrived, and the truncated call was executed as if whole. So the Loop must NEVER execute the tool
+ * calls of a 'max_tokens' round. Refusing costs nothing legitimate (complete calls come back
+ * 'tool_use') and closes the data-loss path at the protocol layer, for every tool, not just
+ * `shell_write`.
+ */
+
+/** Anthropic `stop_reason` → neutral. */
+const ANTHROPIC = {
+  end_turn: 'end_turn',
+  max_tokens: 'max_tokens',
+  tool_use: 'tool_use',
+  stop_sequence: 'stop_sequence',
+  refusal: 'refusal',
+  pause_turn: 'pause_turn',
+  model_context_window_exceeded: 'context_exceeded',
+};
+
+/** OpenAI (and OpenAI-compatible) `finish_reason` → neutral. */
+const OPENAI = {
+  stop: 'end_turn',
+  length: 'max_tokens',
+  tool_calls: 'tool_use',
+  function_call: 'tool_use',
+  content_filter: 'refusal',
+};
+
+/**
+ * Gemini `finishReason` → neutral. Gemini does NOT tag a function call specially — a complete tool call
+ * comes back as `STOP` with a `functionCall` part (measured live) — so there is no `tool_use` row here
+ * by design. `normalizeStopReason` derives it from `hasToolCalls` instead; see the note there.
+ */
+const GEMINI = {
+  STOP: 'end_turn',
+  MAX_TOKENS: 'max_tokens',
+  SAFETY: 'refusal',
+  RECITATION: 'refusal',
+  BLOCKLIST: 'refusal',
+  PROHIBITED_CONTENT: 'refusal',
+  SPII: 'refusal',
+};
+
+/**
+ * Ollama `done_reason` → neutral. `load`/`unload` are lifecycle values, not completions — they map to
+ * null (unknown) rather than being forced into the vocabulary.
+ */
+const OLLAMA = {
+  stop: 'end_turn',
+  length: 'max_tokens',
+};
+
+const TABLES = {
+  anthropic: ANTHROPIC,
+  openai: OPENAI,
+  gemini: GEMINI,
+  ollama: OLLAMA,
+};
+
+/**
+ * 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`.
+ */
+function normalizeStopReason(raw, provider, ctx = {}) {
+  if (typeof raw !== 'string' || raw === '') return null;
+  const table = TABLES[provider];
+  if (!table) return raw;
+  // An unrecognized-but-present value passes through: the caller can still SEE it, and the Loop only
+  // acts on the known vocabulary — so a new upstream value can never be mistaken for a truncation.
+  const mapped = table[raw] || raw;
+
+  // GEMINI AND OLLAMA HAVE NO `tool_use` FINISH REASON (both measured live: Gemini returns
+  // `finishReason: STOP` and Ollama `done_reason: 'stop'` on a round that emitted a complete function
+  // call). Reported verbatim, a round that stopped TO CALL A TOOL would come back as `end_turn` — "the
+  // model finished of its own accord" — on 2 of 5 providers and `tool_use` on the other 3.
+  //
+  // That is the BA-6 defect class in miniature: a round that is NOT a finish, reporting as a finish.
+  // An adopter branching on `stopReason === 'end_turn'` would be right on Anthropic/OpenAI and wrong
+  // on Gemini/Ollama. So derive it from what the round CARRIED — the model did stop to call a tool,
+  // and that is a report, not an invention.
+  //
+  // Narrow on purpose: only ever promotes `end_turn` → `tool_use`. It cannot touch `max_tokens` (a
+  // truncated round carrying a half-generated call must stay TRUNCATED — that is BA-4's mechanism),
+  // nor `refusal`/`pause_turn`/`context_exceeded`, nor an unrecognized passthrough value.
+  if (mapped === 'end_turn' && ctx.hasToolCalls === true) return 'tool_use';
+  return mapped;
+}
+
+/**
+ * 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}
+ */
+function isTruncated(stopReason) {
+  return stopReason === 'max_tokens';
+}
+
+module.exports = { normalizeStopReason, isTruncated };

package/src/recurse-synthesize.js

@@ -62,8 +62,17 @@ async function mergeReduce(task, results, opts) {
   if (typeof out.error === 'string' && out.error.startsWith('halt:')) {
     throw new HaltError('[synthesize] merge halted by governance', { rule: out.error.slice('halt:'.length) });
   }
-  // A non-halt fault (e.g. provider error) is non-fatal here — fall back to the lossless concat rather than
-  // losing the partials entirely. recurse still reports honest completeness via its own paths.
+  // A non-halt fault (e.g. provider error, deny short-circuit, the hard round limit) is non-fatal here — fall
+  // back to the LOSSLESS concat rather than losing the partials entirely. recurse still reports honest
+  // completeness via its own paths.
+  //
+  // Branch on `out.error`, NOT on the falsiness of `out.text` (BA-5). Since the Loop now preserves the text a
+  // bounded run produced, a faulted merge returns its PARTIAL, aborted prose — so `out.text || concat` would
+  // silently ship that fragment as the synthesized answer and every child result would be lost. Proven
+  // reachable: the merge Loop registers no tools, so a hallucinated tool call is fed back as
+  // `[Loop] Unknown tool` and the round loop CONTINUES — round 1 emits prose, round 2 dies, and the fallback
+  // never fires. `error` is the sole success signal; text-falsiness never was one.
+  if (out.error) return concatReduce(results);
   return out.text || concatReduce(results);
 }
 

package/tools/shell.d.ts

@@ -77,12 +77,23 @@ declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flag
  * writes through the shell is impractical: redirection is a shell metachar that an argv/bash allowlist denies).
  * Creates parent directories. Caps size as a sanity ceiling. NO shell — so it gates cleanly through bareguard's
  * fs primitive when the adopter translates `shell_write` → `{ type:'write', path }` (see createShellTools doc).
- * @param {{path: string, content?: string, append?: boolean, maxBytes?: number}} args
+ *
+ * `content` is REQUIRED and must be a string (BA-4). It used to default to `''`, which made the ordinary
+ * failure mode of a long generation — the model hits its output-token cap and the tool call arrives with
+ * `content` absent — silently truncate the target to zero bytes and report `"wrote 0 bytes"` as SUCCESS.
+ * No policy can catch that: a 0-byte write is a legal write, and bareguard's fs primitive judges
+ * `{type:'write', path}` without ever inspecting the body. It is a missing precondition in the primitive,
+ * not a governance gap. An explicit `content: ''` still empties the file — the caller meant it.
+ * `content` is typed REQUIRED so the generated `.d.ts` states the real contract — a library caller that omits
+ * it is a type error, not a runtime surprise. The guard below still runs, because the tool-execute boundary
+ * feeds this UNTRUSTED model-authored args (that is the boundary BA-4 was breached at, and where types buy
+ * nothing).
+ * @param {{path: string, content: string, append?: boolean, maxBytes?: number}} args
  * @returns {Promise<string>}
  */
 declare function writeFile({ path: rawPath, content, append, maxBytes }: {
     path: string;
-    content?: string;
+    content: string;
     append?: boolean;
     maxBytes?: number;
 }): Promise<string>;

package/tools/shell.js

@@ -90,23 +90,40 @@ async function readEntry(rawPath, maxBytes) {
  * writes through the shell is impractical: redirection is a shell metachar that an argv/bash allowlist denies).
  * Creates parent directories. Caps size as a sanity ceiling. NO shell — so it gates cleanly through bareguard's
  * fs primitive when the adopter translates `shell_write` → `{ type:'write', path }` (see createShellTools doc).
- * @param {{path: string, content?: string, append?: boolean, maxBytes?: number}} args
+ *
+ * `content` is REQUIRED and must be a string (BA-4). It used to default to `''`, which made the ordinary
+ * failure mode of a long generation — the model hits its output-token cap and the tool call arrives with
+ * `content` absent — silently truncate the target to zero bytes and report `"wrote 0 bytes"` as SUCCESS.
+ * No policy can catch that: a 0-byte write is a legal write, and bareguard's fs primitive judges
+ * `{type:'write', path}` without ever inspecting the body. It is a missing precondition in the primitive,
+ * not a governance gap. An explicit `content: ''` still empties the file — the caller meant it.
+ * `content` is typed REQUIRED so the generated `.d.ts` states the real contract — a library caller that omits
+ * it is a type error, not a runtime surprise. The guard below still runs, because the tool-execute boundary
+ * feeds this UNTRUSTED model-authored args (that is the boundary BA-4 was breached at, and where types buy
+ * nothing).
+ * @param {{path: string, content: string, append?: boolean, maxBytes?: number}} args
  * @returns {Promise<string>}
  */
-async function writeFile({ path: rawPath, content = '', append = false, maxBytes }) {
+async function writeFile({ path: rawPath, content, append = false, maxBytes }) {
   if (typeof rawPath !== 'string' || rawPath.length === 0) {
     throw new Error('shell_write requires a non-empty "path" string');
   }
-  const text = content == null ? '' : String(content);
+  if (typeof content !== 'string') {
+    throw new Error(
+      'shell_write requires a "content" string (pass content:"" to deliberately empty the file). '
+      + `Got ${content === undefined ? 'no content argument' : `content of type ${content === null ? 'null' : typeof content}`}`
+      + ' — refusing to write, the file is unchanged. If your output was cut short, retry with the full content.',
+    );
+  }
   const cap = maxBytes || DEFAULT_WRITE_MAX_BYTES;
-  const bytes = Buffer.byteLength(text, 'utf8');
+  const bytes = Buffer.byteLength(content, 'utf8');
   if (bytes > cap) {
     throw new Error(`shell_write content is ${bytes} bytes, over the ${cap}-byte cap (pass maxBytes to raise it)`);
   }
   const resolved = path.resolve(expandHome(rawPath));
   await fs.mkdir(path.dirname(resolved), { recursive: true });
-  if (append) await fs.appendFile(resolved, text, 'utf8');
-  else await fs.writeFile(resolved, text, 'utf8');
+  if (append) await fs.appendFile(resolved, content, 'utf8');
+  else await fs.writeFile(resolved, content, 'utf8');
   return `${append ? 'appended' : 'wrote'} ${bytes} bytes to ${resolved}`;
 }
 
@@ -425,13 +442,16 @@ function createShellTools() {
         type: 'object',
         properties: {
           path: { type: 'string', description: 'Target file path. ~ expands to home. Parent dirs are created.' },
-          content: { type: 'string', description: 'The full text to write (UTF-8).' },
+          content: { type: 'string', description: 'The full text to write (UTF-8). Required — a call without it is REJECTED, not treated as an empty write. Pass "" only to deliberately empty the file.' },
           append: { type: 'boolean', description: 'Append to the file instead of overwriting it (default false).' },
           maxBytes: { type: 'integer', description: 'Reject a write larger than this many bytes (default 5242880).' },
         },
         required: ['path', 'content'],
       },
-      execute: async (/** @type {{path: string, content?: string, append?: boolean, maxBytes?: number}} */ args) => writeFile(args),
+      // The args are model-authored and UNTRUSTED — `content` may be absent (an output-token-capped
+      // generation), so the boundary type stays loose and `writeFile` enforces the contract at runtime (BA-4).
+      execute: async (/** @type {{path: string, content?: string, append?: boolean, maxBytes?: number}} */ args) =>
+        writeFile(/** @type {any} */ (args)),
     },
     {
       name: 'shell_run',

package/types/index.d.ts

@@ -80,12 +80,39 @@ export interface GenerateResult {
   usage: Usage;
   /** Model id the response was produced by; preferred over Provider.model for cost accounting. */
   model?: string | null;
+  /**
+   * Why generation ended, normalized across providers (BA-6). Before this, no provider read its native
+   * finish-reason field, so a round the API CUT OFF at the token cap was indistinguishable from one the
+   * model chose to end — and the Loop, whose rule is "no tool calls ⇒ final answer", returned the
+   * truncation as a clean finish with `error: null`.
+   *
+   * - `'end_turn'` — the model finished on its own. The only clean finish.
+   * - `'max_tokens'` — CUT OFF at the output cap. The Loop returns `error: 'truncated:max_tokens'`
+   *   (preserving the partial text) and REFUSES to execute any tool call the round carries: a complete
+   *   call always arrives as `'tool_use'`, so one riding a `'max_tokens'` round was cut off
+   *   mid-generation with arguments missing — the BA-4 file-zeroing mechanism.
+   * - `'tool_use'` — stopped to call a tool, and the call is COMPLETE.
+   * - `'stop_sequence'` / `'refusal'` / `'pause_turn'` / `'context_exceeded'` — reported, not acted on.
+   * - `null` — the provider didn't report one (e.g. CLIPipe) or the value is unrecognized. Reproduces
+   *   pre-BA-6 behavior exactly, so an unmapped provider degrades to the status quo.
+   */
+  stopReason?: string | null;
   /**
    * True when the requested `temperature` was rejected by the model (400, unsupported/deprecated) and
    * the request was retried without it (BA-10). The response was produced at the model's DEFAULT
    * temperature, not the one requested — callers reporting an effective temperature must honor this.
    */
   temperatureDropped?: boolean;
+  /**
+   * 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
+   * transcript and the provider can replay them on the next round.
+   *
+   * Present only when the response actually carried such blocks — so a provider that returns none
+   * leaves both the result and the resulting message byte-identical to pre-BA-7. See `Message.providerBlocks`
+   * for the replay contract (the provider/model tag is enforced; a signature is model-bound).
+   */
+  providerBlocks?: { provider: string; model: string; blocks: any[] };
   /**
    * Authoritative per-call cost in USD, reported by the provider itself — e.g. CLIPipeProvider
    * `parse:'claude-json'` surfacing the claude CLI's own `total_cost_usd`, a real price with no local
@@ -102,6 +129,25 @@ export interface Message {
   content?: string | null;
   tool_calls?: any[];
   tool_call_id?: string;
+  /**
+   * BA-7 — provider-native content blocks that this OpenAI-shaped message cannot express, carried
+   * verbatim so they can be replayed to the provider that issued them.
+   *
+   * Today this is Anthropic `thinking` / `redacted_thinking`. Anthropic's contract is that such
+   * blocks are echoed back UNCHANGED (`signature` included) when continuing a tool-use conversation;
+   * before BA-7 there was no field on this type that could hold one, so they were silently dropped.
+   *
+   * OPAQUE by design — the Loop never reads `blocks`, and the provider re-emits their bytes rather
+   * than re-serializing a parsed shape (a `redacted_thinking` block cannot survive a round-trip
+   * through parsed fields). The `provider`/`model` tag is enforced on replay: a thinking signature is
+   * bound to the model that produced it, so a mismatch drops the blocks and degrades to the lossy
+   * pre-BA-7 request rather than risking a 400.
+   *
+   * The normalized `content` / `tool_calls` remain the source of truth: only blocks that have no
+   * normalized representation live here, so an `assemble`/`trim` seam that rewrites this message is
+   * never silently undone by a stale cached copy of its text.
+   */
+  providerBlocks?: { provider: string; model: string; blocks: any[] };
   [key: string]: any;
 }