bare-agent 0.26.2 → 0.27.0

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;
 }