bare-agent 0.46.6 → 0.48.0

package/src/provider-openai.js

@@ -72,6 +72,11 @@ function isLoopbackHost(hostname) {
  *   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.
+ * @property {boolean} [exposeMalformedArgs=false] - BA-27 follow-up: when a tool call's `function.arguments`
+ *   JSON fails to parse, also attach the raw string (verbatim, capped at 500 chars, `rawTruncated:true`
+ *   when longer) to `malformedToolCall.rawArguments`. Off by default, independent of `exposeErrorBody` —
+ *   the raw blob is model-generated, not an upstream error body, but the same "don't leak an unbounded
+ *   unexpected string into logs by default" reasoning applies. See `src/provider-toolcalls.js`.
  */
 
 class OpenAIProvider {
@@ -93,6 +98,8 @@ class OpenAIProvider {
     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;
+    // BA-27 follow-up: expose the raw malformed tool-call arguments string. Off by default.
+    this.exposeMalformedArgs = options.exposeMalformedArgs === true;
   }
 
   /**
@@ -161,7 +168,7 @@ class OpenAIProvider {
       id: tc.id,
       name: tc.function.name,
       arguments: JSON.parse(tc.function.arguments),
-    }));
+    }), { exposeMalformedArgs: this.exposeMalformedArgs });
 
     return {
       text: msg.content || '',

package/src/provider-toolcalls.d.ts

@@ -1,5 +1,4 @@
 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.
@@ -16,14 +15,27 @@ export type ToolCall = import("../types").ToolCall;
  * 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.
  *
+ * `opts.exposeMalformedArgs` (default off, mirrors `exposeErrorBody`): when on, the marker also
+ * carries `rawArguments` — the raw `function.arguments` VERBATIM, capped at 500 chars (`rawTruncated:
+ * true` added only when it was longer). Non-string raw arguments (e.g. Ollama's well-formed object
+ * case reaching this catch some other way) are never exposed — only a string is a model-generated
+ * blob worth surfacing for debugging; an object was already structurally valid before whatever else
+ * threw. Off by default for the same reason as `exposeErrorBody`: an arbitrary model-generated string
+ * landing in a log/audit row unbounded is its own leak surface.
+ *
  * @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 } }}
+ * @param {{ exposeMalformedArgs?: boolean }} [opts]
+ * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true } }}
  */
-export function parseToolCalls(rawToolCalls: any[], mapOne: (tc: any) => ToolCall): {
+export function parseToolCalls(rawToolCalls: any[], mapOne: (tc: any) => ToolCall, opts?: {
+    exposeMalformedArgs?: boolean;
+}): {
     toolCalls: ToolCall[];
     malformedToolCall?: {
         name: string | undefined;
         error: string;
+        rawArguments?: string;
+        rawTruncated?: true;
     };
 };

package/src/provider-toolcalls.js

@@ -2,6 +2,11 @@
 
 /** @typedef {import('../types').ToolCall} ToolCall */
 
+// Raw-arguments exposure cap. Matches the sibling opt-in error-body exposure pattern
+// (`exposeErrorBody`) elsewhere in the providers: off by default, and even when on, bounded —
+// an arbitrarily long model-generated string reaching a log/receipt unbounded is its own risk.
+const RAW_ARGUMENTS_MAX_CHARS = 500;
+
 /**
  * BA-27 — parse a round's raw tool calls into the neutral {@link ToolCall} shape WITHOUT throwing on
  * malformed arguments.
@@ -18,11 +23,20 @@
  * 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.
  *
+ * `opts.exposeMalformedArgs` (default off, mirrors `exposeErrorBody`): when on, the marker also
+ * carries `rawArguments` — the raw `function.arguments` VERBATIM, capped at 500 chars (`rawTruncated:
+ * true` added only when it was longer). Non-string raw arguments (e.g. Ollama's well-formed object
+ * case reaching this catch some other way) are never exposed — only a string is a model-generated
+ * blob worth surfacing for debugging; an object was already structurally valid before whatever else
+ * threw. Off by default for the same reason as `exposeErrorBody`: an arbitrary model-generated string
+ * landing in a log/audit row unbounded is its own leak surface.
+ *
  * @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 } }}
+ * @param {{ exposeMalformedArgs?: boolean }} [opts]
+ * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true } }}
  */
-function parseToolCalls(rawToolCalls, mapOne) {
+function parseToolCalls(rawToolCalls, mapOne, opts = {}) {
   const raw = rawToolCalls || [];
   /** @type {ToolCall[]} */
   const toolCalls = [];
@@ -30,13 +44,19 @@ function parseToolCalls(rawToolCalls, mapOne) {
     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),
-        },
+      /** @type {{ name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true }} */
+      const malformedToolCall = {
+        name: tc && tc.function ? tc.function.name : undefined,
+        error: e instanceof Error ? e.message : String(e),
       };
+      if (opts.exposeMalformedArgs) {
+        const rawArgs = tc && tc.function ? tc.function.arguments : undefined;
+        if (typeof rawArgs === 'string') {
+          malformedToolCall.rawArguments = rawArgs.slice(0, RAW_ARGUMENTS_MAX_CHARS);
+          if (rawArgs.length > RAW_ARGUMENTS_MAX_CHARS) malformedToolCall.rawTruncated = true;
+        }
+      }
+      return { toolCalls: [], malformedToolCall };
     }
   }
   return { toolCalls };

package/src/retry.d.ts

@@ -23,7 +23,7 @@ export type RetryOptions = {
 export class Retry {
     /**
      * @param {RetryOptions} [options={}]
-     * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam Loop and runPlan wrap providers with
+     * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam that Loop and runPlan wrap around providers
      * @fails rethrows the last error once attempts are exhausted; by default only transient errors (429/5xx/ECONNRESET/ETIMEDOUT) are retried.
      * @example
      *   const retry = new Retry({ maxAttempts: 3, jitter: true });

package/src/retry.js

@@ -25,7 +25,7 @@ const DEFAULT_RETRY_ON = (err) => {
 class Retry {
   /**
    * @param {RetryOptions} [options={}]
-   * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam Loop and runPlan wrap providers with
+   * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam that Loop and runPlan wrap around providers
    * @fails rethrows the last error once attempts are exhausted; by default only transient errors (429/5xx/ECONNRESET/ETIMEDOUT) are retried.
    * @example
    *   const retry = new Retry({ maxAttempts: 3, jitter: true });

package/src/tools.d.ts

@@ -1,9 +1,10 @@
 import { createBrowsingTools } from "../tools/browse";
 import { createMobileTools } from "../tools/mobile";
 import { createShellTools } from "../tools/shell";
+import { resolveToolPath } from "../tools/shell";
 import { createSpawnTool } from "../tools/spawn";
 import { spawnChild } from "../tools/spawn";
 import { createDeferTool } from "../tools/defer";
 import { readQueue as readDeferQueue } from "../tools/defer";
 import { liteCtxMcpBridgeConfig } from "../tools/litectx-mcp";
-export { createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, spawnChild, createDeferTool, readDeferQueue, liteCtxMcpBridgeConfig };
+export { createBrowsingTools, createMobileTools, createShellTools, resolveToolPath, createSpawnTool, spawnChild, createDeferTool, readDeferQueue, liteCtxMcpBridgeConfig };

package/src/tools.js

@@ -2,7 +2,7 @@
 
 const { createBrowsingTools } = require('../tools/browse');
 const { createMobileTools } = require('../tools/mobile');
-const { createShellTools } = require('../tools/shell');
+const { createShellTools, resolveToolPath } = require('../tools/shell');
 const { createSpawnTool, spawnChild } = require('../tools/spawn');
 const { createDeferTool, readQueue: readDeferQueue } = require('../tools/defer');
 const { liteCtxMcpBridgeConfig } = require('../tools/litectx-mcp');
@@ -11,6 +11,7 @@ module.exports = {
   createBrowsingTools,
   createMobileTools,
   createShellTools,
+  resolveToolPath,
   createSpawnTool,
   spawnChild,
   createDeferTool,

package/tools/shell.d.ts

@@ -3,9 +3,13 @@ declare namespace _exports {
 }
 declare namespace _exports {
     export { createShellTools };
+    export { resolveToolPath };
     export { _grepCore };
     export { writeFile as _writeFile };
     export { editFile as _editFile };
+    export { openFile as _openFile };
+    export { assertDirStillMatchesHandle as _assertDirStillMatchesHandle };
+    export { expandHome as _expandHome };
 }
 export = _exports;
 type GrepArgs = {
@@ -20,6 +24,12 @@ type GrepArgs = {
      * past `looksCatastrophic` can no longer hang the host event loop.
      */
     timeout?: number | undefined;
+    /**
+     * - When true, refuses a symlinked ROOT path (thrown, loud)
+     * and skips (silently, like any other read error) a file that is or becomes a symlink during the
+     * walk. Threaded into `workerData` so the worker thread's file reads honor it too.
+     */
+    noFollowSymlinks?: boolean | undefined;
 };
 type RunArgvArgs = {
     argv: string[];
@@ -37,19 +47,60 @@ type ExecCommandArgs = {
 };
 type ToolDef = import("../types").ToolDef;
 /**
- * Create the three shell tools. No options — configuration is per-call via tool args,
- * gating is the caller's responsibility via `new Loop({ policy })`.
+ * Create the six shell tools. Configuration is mostly per-call via tool args; gating is the
+ * caller's responsibility via `new Loop({ policy })`.
  *
+ * @param {{noFollowSymlinks?: boolean}} [options] - `noFollowSymlinks` (default `false`, byte-
+ *   identical to the pre-existing behavior when omitted): when `true`, `shell_read`, `shell_write`,
+ *   `shell_edit`, and `shell_grep` refuse to open a path whose FINAL path component is a symlink
+ *   (file, dir, or dangling) — THROWN, `err.code:'ELOOP'`, never a silently-followed link. Scope is
+ *   the final component ONLY — a symlinked PARENT directory is NOT refused (bareguard's own
+ *   resolved-path containment check for that is planned for an upcoming release, not yet published;
+ *   until then the gate matches paths lexically, so a symlinked parent dir is not contained there
+ *   either — see the top-of-file CAVEAT). The `cwd` option of `shell_run`/`shell_exec` is a separate,
+ *   NARROWER gap: it only gets `~` expansion, never this flag or `resolveToolPath`'s full
+ *   canonicalization, so a symlinked `cwd` is always followed. On Windows (`fs.constants.O_NOFOLLOW`
+ *   is undefined there) the guard falls back to a non-atomic `fs.lstat`-then-open check — a symlink
+ *   planted in the gap between the two calls slips through; this is a documented platform limitation,
+ *   not a bug. Set per `createShellTools()` instance, not module-global — safe to mix a
+ *   `noFollowSymlinks:true` toolset for one agent alongside a default toolset for another in the same
+ *   process.
  * @returns {{tools: ToolDef[]}}
  * @when you want to give an agent shell/file tools (read, grep, write, edit, run, exec) — cross-platform, pure Node, zero deps
- * @fails never throws at creation; gating is the caller's via Loop({ policy }) and fs.writeScope, and shell_edit refuses a non-unique anchor as a tool result (file untouched).
+ * @fails never throws at creation; gating is the caller's via Loop({ policy }) and fs.writeScope, shell_edit refuses a non-unique anchor as a tool result (file untouched), and with noFollowSymlinks:true the four file tools throw ELOOP on a symlinked final path component.
  * @example
  *   const { tools } = createShellTools();
  *   const loop = new Loop({ provider, tools, policy });
+ *   const { tools: safeTools } = createShellTools({ noFollowSymlinks: true });
  */
-declare function createShellTools(): {
+declare function createShellTools(options?: {
+    noFollowSymlinks?: boolean;
+}): {
     tools: ToolDef[];
 };
+/**
+ * THE canonicalizer every shell file tool uses before opening a path — and the same canonicalization
+ * an adopter should apply before `gate.check` so the string it judges is the string that gets opened
+ * (see the top-of-file CAVEAT). Expands `~`/`~/…` via `os.homedir()` (throwing rather than silently
+ * degrading — see `expandHome`), then resolves against `process.cwd()` — matching how bareguard's own
+ * config-side path handling expects `~` and relative paths to be canonicalized before it judges them.
+ *
+ * Idempotent: `resolveToolPath(resolveToolPath(p)) === resolveToolPath(p)` — an already-absolute,
+ * already-`~`-free path passed back in is returned unchanged (`path.resolve` on an absolute path is
+ * a no-op; there is no `~` left to expand).
+ * REJECTS a non-string or empty `p` outright (thrown, before any expansion/resolution runs) —
+ * every file tool routes through this function, so a model-authored call that omits `path` or sends
+ * `""` must not silently resolve to `process.cwd()` (an assumed default a gate would judge and a tool
+ * would then read/list, for input that named no path at all). The rejection message names only the
+ * TYPE/category of the bad value (`describeBadPath`), never the value itself.
+ * @param {string} p
+ * @returns {string}
+ * @when you gate shell file tools — canonicalize the tool's path once with this, put it in the action you pass to `gate.check`, so the gate judges exactly the path the tool opens
+ * @fails throws on a non-string or empty path, and on a `~` path when no home directory can be determined — never turns `~/x` into `/x` or an empty path into cwd
+ * @example
+ *   const resolved = resolveToolPath('~/notes.txt');
+ */
+declare function resolveToolPath(p: string): string;
 /**
  * @typedef {object} GrepArgs
  * @property {string} pattern
@@ -60,6 +111,9 @@ declare function createShellTools(): {
  * @property {number} [timeout] - Hard wall-clock ceiling in ms (default 5000). The match runs in a
  *   worker thread; on overrun the worker is terminated and the call rejects, so a pattern that slips
  *   past `looksCatastrophic` can no longer hang the host event loop.
+ * @property {boolean} [noFollowSymlinks] - When true, refuses a symlinked ROOT path (thrown, loud)
+ *   and skips (silently, like any other read error) a file that is or becomes a symlink during the
+ *   walk. Threaded into `workerData` so the worker thread's file reads honor it too.
  */
 /**
  * The actual search: walk, skip binaries, regex-test each line. Runs in a worker thread (see
@@ -69,7 +123,7 @@ declare function createShellTools(): {
  * guarantee; a grounded bypass like `(a|a|a)*` passes it yet backtracks exponentially).
  * @param {GrepArgs} args
  */
-declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags }: GrepArgs): Promise<{
+declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags, noFollowSymlinks }: GrepArgs): Promise<{
     hits: {
         file: string;
         line: number;
@@ -95,6 +149,7 @@ declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flag
  * 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
+ * @param {{noFollowSymlinks?: boolean}} [options]
  * @returns {Promise<string>}
  */
 declare function writeFile({ path: rawPath, content, append, maxBytes }: {
@@ -102,6 +157,8 @@ declare function writeFile({ path: rawPath, content, append, maxBytes }: {
     content: string;
     append?: boolean;
     maxBytes?: number;
+}, options?: {
+    noFollowSymlinks?: boolean;
 }): Promise<string>;
 /**
  * Anchored exact-string replace (BA-13) — the surgical counterpart to the whole-file `shell_write`.
@@ -117,7 +174,9 @@ declare function writeFile({ path: rawPath, content, append, maxBytes }: {
  *     guard, so a model that repeats the byte-identical wrong anchor is bounded only by maxTurns/budget, not
  *     short-circuited. A widened anchor is a different call and recovers naturally; the exact-repeat spin is
  *     the rare degenerate case. This matches the ask's "refusal, not a throw" contract.)
- *   - fs-layer errors (missing file, a directory) and BA-4 param-guard violations THROW at the tool boundary.
+ *   - fs-layer errors (missing file, a directory), BA-4 param-guard violations, and a SOURCE file larger
+ *     than the `maxBytes` cap (read bounded via `readBounded`, never fully loaded to find out) THROW at
+ *     the tool boundary, before any edit is computed — no change made.
  *
  * BA-4 param guards (guarded from birth this time — cf. `shell_write` zeroing files on an absent arg):
  * `oldText` a required NON-EMPTY string, `newText` a required string — both THROW when absent/wrong-type (an
@@ -133,6 +192,7 @@ declare function writeFile({ path: rawPath, content, append, maxBytes }: {
  * `newText` and would corrupt any edit whose replacement contains a `$`. We index + slice, so every byte of
  * `newText` lands verbatim.
  * @param {{path: string, oldText: string, newText: string, maxBytes?: number}} args
+ * @param {{noFollowSymlinks?: boolean}} [options]
  * @returns {Promise<string>}
  */
 declare function editFile({ path: rawPath, oldText, newText, maxBytes }: {
@@ -140,4 +200,74 @@ declare function editFile({ path: rawPath, oldText, newText, maxBytes }: {
     oldText: string;
     newText: string;
     maxBytes?: number;
+}, options?: {
+    noFollowSymlinks?: boolean;
 }): Promise<string>;
+/**
+ * ONE shared open path for every file-open site in this module (`shell_read`, `shell_write`,
+ * `shell_edit`, and `shell_grep`'s root check + per-file reads). With `noFollowSymlinks` off this
+ * is a plain `fs.open` — the caller's `flags` decide read/write/create semantics, byte-identical to
+ * this module's pre-existing behavior. With it on, refuses to follow a symlink at the FINAL path
+ * component (opt-in — never covers a symlinked PARENT directory; see the top-of-file CAVEAT for
+ * bareguard's resolved-path containment side of that, upcoming but not yet published).
+ *
+ * Two implementations when the flag is on, selected by whether the platform exposes `O_NOFOLLOW`
+ * (present on linux/macOS, `undefined` on Windows):
+ *   - Native: pass `O_NOFOLLOW` straight to the kernel via `fs.open`. Atomic — there is no window
+ *     between checking and opening. A symlink at the final component (file, dir, or DANGLING)
+ *     makes the open fail with `ELOOP` before anything is created or read, which we translate to
+ *     `symlinkRefusalError`. Any other error (ENOENT, EACCES, …) passes through unchanged.
+ *   - Fallback (`O_NOFOLLOW` undefined): `fs.lstat` the path first and refuse if it is a symlink,
+ *     then `fs.open` normally. This is NOT atomic — a symlink planted between the `lstat` and the
+ *     `open` slips through (TOCTOU) — documented as a known Windows limitation, not a bug: Windows
+ *     has no `O_NOFOLLOW`-equivalent open flag reachable from Node. `lstat` throwing `ENOENT` means
+ *     "nothing there yet," which is fine for a write/create call — the open below still runs and
+ *     either creates the file or throws its own ENOENT for a read.
+ * @param {string} toolName
+ * @param {string} resolvedPath
+ * @param {number} flags
+ * @param {number} [mode]
+ * @param {{noFollowSymlinks?: boolean, constants?: {O_NOFOLLOW?: number}}} [options] - `constants` is
+ *   an injectable override, used by tests to force the Windows fallback branch on a non-Windows CI
+ *   box without monkeypatching `fs.constants` globally.
+ */
+declare function openFile(toolName: string, resolvedPath: string, flags: number, mode?: number, options?: {
+    noFollowSymlinks?: boolean;
+    constants?: {
+        O_NOFOLLOW?: number;
+    };
+}): Promise<fs.FileHandle>;
+/**
+ * Narrows (does not close) the directory-listing race: after opening a directory by FD we still
+ * have to list it by PATH — Node's `fs/promises` exposes no `fdopendir` — so a directory or symlink
+ * swapped in at that path between the open and the `readdir` could make us list a DIFFERENT
+ * directory's NAMES. This never leaks file CONTENTS (every content read in this module goes through
+ * the already-open fd, never re-opened by path), only which names are reported for a listing.
+ *
+ * Re-`lstat`s the path right after the read and refuses (throws, `ELOOP`) unless its `dev`+`ino`
+ * still match the handle that was opened — catching both a swap-to-a-symlink (whose own inode won't
+ * match the real directory's) and a swap-to-a-different-real-directory (a different inode).
+ *
+ * RESIDUAL, documented not closed: a swap-and-swap-back that lands back on the original dev+ino
+ * before this check runs is undetectable — any check that must re-consult the path shares this
+ * limit. Only called when `noFollowSymlinks` is on; the recheck is inert otherwise.
+ * @param {string} toolName
+ * @param {string} resolvedPath
+ * @param {import('node:fs').Stats} handleStat
+ */
+declare function assertDirStillMatchesHandle(toolName: string, resolvedPath: string, handleStat: import("node:fs").Stats): Promise<void>;
+/**
+ * Expand a leading `~`/`~/…` to the real home directory via `os.homedir()` — matching how bareguard's
+ * own config-side `~` expansion works, so the SAME string means the same absolute path on both sides
+ * of a gate check. Throws a clear error rather than ever silently degrading `~/x` to `/x`:
+ * the previous `process.env.HOME || process.env.USERPROFILE || ''` fallback did exactly that when
+ * `HOME` was unset or empty — a `~`-rooted path would resolve to the FILESYSTEM ROOT, not "no home,"
+ * an under-modeled-boundary bug (an ambiguous case rounding toward "works" instead of surfacing).
+ * @param {string} p
+ * @param {() => string} [homedirFn] - Injectable override, used ONLY by tests to force the
+ *   empty/throwing-homedir case deterministically, without monkeypatching `os.homedir` globally
+ *   (which would affect every other test in this process). Production call sites never pass this.
+ * @returns {string}
+ */
+declare function expandHome(p: string, homedirFn?: () => string): string;
+import fs = require("node:fs/promises");