bare-agent 0.46.5 → 0.47.0

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");