toolroll 0.9.103 → 0.9.105

package/dist/sandbox-runtime.js

@@ -1,18 +1,3 @@
-/**
- * The sandbox engine: Anthropic's sandbox-runtime (`@anthropic-ai/sandbox-runtime`, pinned in package.json). Every
- * macOS Seatbelt profile and every Linux bubblewrap + seccomp invocation a fenced launch runs under is generated by
- * its own code, per launch, from a small static config (read denies with exact re-allows, write roots with denies
- * inside them, mach services, the run's proxy). Toolroll adds only what that config says (agent-fence.ts srtTermsOf),
- * plus, on macOS, a few static rules of its own appended to the end of the profile (seatbeltRulesFor: a terminal of the
- * launch's own and no other, no keystrokes pushed into a terminal, a check's Chromium service, the keychain's services
- * only for builds); the rest of the rules, their baseline and their limits are the runtime's.
- *
- * macOS: its profile builder runs in this process (it is synchronous), with this process's working folder set to the
- * launch's for the call, because the runtime anchors its mandatory write denies (.git/hooks, .vscode, shell profiles)
- * at the working folder. Linux: its builder is asynchronous, anchored at the working folder too, and leaves mount
- * points to clean up after the command, so each Linux launch runs through a small helper process
- * (sandbox-launch.ts) that changes into the launch's folder, asks the runtime for the command, runs it and cleans up.
- */
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -21,7 +6,6 @@ import { fileURLToPath } from "node:url";
 import { wrapCommandWithSandboxMacOS } from "@anthropic-ai/sandbox-runtime/dist/sandbox/macos-sandbox-utils.js";
 import { checkLinuxDependencies, getLinuxDependencyStatus } from "@anthropic-ai/sandbox-runtime/dist/sandbox/linux-sandbox-utils.js";
 const require = createRequire(import.meta.url);
-/** The engine and its exact version, as the console and the words say it. */
 export const SANDBOX_RUNTIME = (() => {
     const name = "@anthropic-ai/sandbox-runtime";
     try {
@@ -32,13 +16,9 @@ export const SANDBOX_RUNTIME = (() => {
         return { name, version: "unknown" };
     }
 })();
-/** "Anthropic's sandbox-runtime 0.0.79": how every surface names the engine. */
 export const sandboxRuntimeWords = () => `Anthropic's sandbox-runtime ${SANDBOX_RUNTIME.version}`;
 const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
-/** A deny-by-default profile, as the runtime's are: inside another sandbox one can't be applied (an allow-by-default one
- * still can, so it proves nothing). */
 export const SEATBELT_PROBE = "(version 1)(deny default)(allow process-exec)(allow process-fork)(allow file-read*)(allow sysctl-read)(allow mach-lookup)";
-/** Why the runtime can't sandbox here, or null when it can (checked before every launch; nothing runs bare). */
 export function sandboxRuntimeProblem(platform = process.platform) {
     if (platform === "darwin") {
         if (!existsSync(SANDBOX_EXEC))
@@ -52,7 +32,6 @@ export function sandboxRuntimeProblem(platform = process.platform) {
             return checked.errors.join("; ");
         if (!getLinuxDependencyStatus().hasSeccompApply)
             return "the sandbox runtime's seccomp helper isn't available for this processor";
-        // The runtime finds nested protected names (a subfolder's .git/hooks, .vscode, shell profiles) with ripgrep.
         if (spawnSync("rg", ["--version"], { timeout: 5_000, stdio: "ignore" }).status !== 0)
             return "ripgrep (rg) is not installed";
         const probe = spawnSync("bwrap", ["--ro-bind", "/", "/", "--unshare-pid", "--unshare-user", "--proc", "/proc", "--new-session", "--", "true"], { timeout: 5_000, stdio: "ignore" });
@@ -60,14 +39,9 @@ export function sandboxRuntimeProblem(platform = process.platform) {
     }
     return `the sandbox runtime has no sandbox for ${platform}`;
 }
-/** POSIX shell words. */
 export function shellQuote(words) {
     return words.map(word => /^[A-Za-z0-9_@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`).join(" ");
 }
-/**
- * The runtime sets a sandboxed command's TMPDIR itself (to $CLAUDE_CODE_TMPDIR of the process asking, or /tmp/claude):
- * the launch's own temp folder when it has one, so it keeps it; otherwise /tmp/claude, made if missing.
- */
 export function withRuntimeTemp(temp, make) {
     const before = { code: process.env["CLAUDE_CODE_TMPDIR"], old: process.env["CLAUDE_TMPDIR"] };
     delete process.env["CLAUDE_TMPDIR"];
@@ -78,7 +52,7 @@ export function withRuntimeTemp(temp, make) {
         try {
             mkdirSync("/tmp/claude", { recursive: true, mode: 0o700 });
         }
-        catch { /* someone else's: writes there fail */ }
+        catch { }
     }
     try {
         return make();
@@ -92,59 +66,26 @@ export function withRuntimeTemp(temp, make) {
             process.env["CLAUDE_TMPDIR"] = before.old;
     }
 }
-/**
- * Toolroll's own Seatbelt rules, appended to the end of the runtime's profile (Seatbelt takes the last rule that
- * matches). Static: constants here, never made from a launch's data.
- *
- * Terminals: a pseudo-terminal of the launch's own (node-pty, `script`, a test that drives a shell), and no other. The
- * runtime's `allowPty` opens reads and writes on every /dev/ttys device, the operator's own open terminals among them,
- * and its baseline already reads them (a read steals what is typed there). macOS marks a terminal the sandboxed process
- * made with the `com.apple.sandbox.pty` extension (for that terminal only: a device number used again later outside is
- * not covered), so only those are opened by name. A terminal handed down open (a live terminal's own) stays usable.
- */
 export const SEATBELT_PTY = [
     "; Toolroll: a pseudo-terminal the launch made itself",
     "(allow pseudo-tty)",
     "(allow file-read* file-write* file-ioctl (literal \"/dev/ptmx\"))",
     "(allow file-read* file-write* file-ioctl (require-all (regex #\"^/dev/ttys[0-9]+$\") (extension \"com.apple.sandbox.pty\")))",
 ].join("\n");
-/** Last in every profile: no other terminal opened by name, and no keystrokes pushed into any terminal (TIOCSTI,
- * _IOW('t', 114, char)), its own controlling terminal included. */
 export const SEATBELT_NO_OTHER_TERMINAL = [
     "; Toolroll: no other terminal, and nothing typed into one",
     "(deny file-read-data file-write* (require-all (regex #\"^/dev/ttys[0-9]+$\") (require-not (extension \"com.apple.sandbox.pty\"))))",
     "(deny file-ioctl (ioctl-command 2147578994))",
 ].join("\n");
-/**
- * Last in every launch's profile but a build agent's: the keychain's services. The runtime's
- * baseline lets every sandboxed process ask securityd, so it reads the login keychain's items whose access list lets
- * any program read them (anthropics/sandbox-runtime#755). Build agents keep it (Claude Code signs in from the keychain).
- */
 export const SEATBELT_NO_KEYCHAIN = [
     "; Toolroll: no keychain",
     "(deny mach-lookup (with no-report) (global-name \"com.apple.SecurityServer\") (global-name \"com.apple.securityd.xpc\"))",
 ].join("\n");
-/**
- * First after the profile's default deny: a mach service lookup the profile doesn't allow is still denied, unreported.
- * On macOS 26.5 a reported mach-lookup denial now and then never answers: bootstrap_look_up blocks in launchd for good
- * (seen as npm stuck in Node's DNS setup, dns_configuration_copy → com.apple.SystemConfiguration.DNSConfiguration, about
- * 1 launch in 70 under load; never with the report off). Every allow after it still wins, so what is reachable is the
- * same; only the report goes.
- */
 export const SEATBELT_QUIET_MACH_DENY = "(deny mach-lookup (with no-report))";
-/**
- * Chromium, a project check's launch only: Playwright's default browser (its Chromium headless shell) registers its
- * port rendezvous service as org.chromium.Chromium.MachPortRendezvousServer.<its pid> at start, and its helpers look
- * it up. Exactly that name. Chromium takes the prefix from its bundle id with no switch or variable to change it, and
- * Seatbelt can't tie the pid to the caller, so the residual (another pid's name registered or looked up) is written
- * up in SECURITY.md. Chrome for Testing (`channel: "chromium"`, headed runs) gets nothing: such a check runs Not
- * sandboxed.
- */
 export const SEATBELT_CHROMIUM = [
     "; Toolroll: the Chromium headless shell port rendezvous service",
     "(allow mach-register mach-lookup (global-name-regex #\"^org\\.chromium\\.Chromium\\.MachPortRendezvousServer\\.[0-9]+$\"))",
 ].join("\n");
-/** Whether a read deny covers the launch's own terminal devices (/dev/ptmx, /dev/ttys*): then it gets none. */
 function deniesTerminals(deny) {
     const glob = deny.search(/[*?[]/);
     const path = (glob < 0 ? deny : deny.slice(0, glob)).replace(/\/+$/, "");
@@ -153,20 +94,15 @@ function deniesTerminals(deny) {
         return devices.some(device => device.startsWith(path));
     return path === "" || path === "/dev" || devices.includes(path) || /^\/dev\/ttys[0-9]*$/.test(path);
 }
-/** Toolroll's rules for a launch's terms, in order: its own terminal (unless its read denies cover the devices), a
- * check's Chromium service, then the denies that must come last. */
 export function seatbeltRulesFor(terms) {
     const denied = [...terms.readConfig.denyOnly, ...terms.readConfig.literalDenyOnly ?? []].some(one => deniesTerminals(typeof one === "string" ? one : String(one)));
     return [...denied ? [] : [SEATBELT_PTY], ...terms.browser === true ? [SEATBELT_CHROMIUM] : [], SEATBELT_NO_OTHER_TERMINAL,
         ...terms.keychain === true ? [] : [SEATBELT_NO_KEYCHAIN]].join("\n");
 }
 const BARE_WORD = /^[A-Za-z0-9_./:@+,-][A-Za-z0-9_./:=@+,-]*$/;
-/** The runtime's own quoting (its utils/shell-quote.js): a word bare when nothing in it is special, otherwise in single
- * quotes with a quote inside as '"'"'. */
 export function srtQuote(words) {
     return words.map(word => word === "" ? "''" : BARE_WORD.test(word) ? word : `'${word.replace(/'/g, `'"'"'`)}'`).join(" ");
 }
-/** The words of a line srtQuote made, or null for any other line (an operator, a second command, other quoting). */
 export function srtWords(line) {
     const words = [];
     let at = 0;
@@ -204,12 +140,6 @@ export function srtWords(line) {
     return words.length > 0 && srtQuote(words) === line ? words : null;
 }
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
-/**
- * `command` (the runtime's macOS invocation) with `rules` appended to its profile, made again from its words. The
- * runtime's invocation is exactly `env [-u NAME]… [NAME=value]… /usr/bin/sandbox-exec -p <profile> <shell> -c
- * <command>`, each word quoted its way, and `<command>` is `expected` when given. Any other line (an operator, a word
- * before `env` or after the command, another program) is refused, so the launch doesn't run.
- */
 export function withSeatbeltRules(command, rules, expected) {
     if (rules.includes("'"))
         throw new Error("a Seatbelt rule Toolroll adds can't hold a quote");
@@ -234,7 +164,6 @@ export function withSeatbeltRules(command, rules, expected) {
     const profile = words[exec + 2];
     if (!profile.startsWith("(version 1)\n(deny default"))
         throw shape();
-    // Where the default deny's line ends (the profile's end when it is the last line).
     const lineEnd = profile.indexOf("\n", "(version 1)\n".length);
     const opening = lineEnd < 0 ? profile.length : lineEnd;
     if (!/^\/[A-Za-z0-9_./-]+$/.test(words[exec + 3]))
@@ -244,7 +173,6 @@ export function withSeatbeltRules(command, rules, expected) {
     const quiet = `${profile.slice(0, opening)}\n${SEATBELT_QUIET_MACH_DENY}${profile.slice(opening)}`;
     return srtQuote([...words.slice(0, exec + 2), `${quiet}\n${rules}\n`, ...words.slice(exec + 3)]);
 }
-/** The runtime's macOS invocation for `file args` run from `cwd`: a command line for /bin/sh. */
 export function srtMacosCommand(file, args, terms, cwd = process.cwd(), temp) {
     const network = terms.network;
     const params = {
@@ -261,7 +189,6 @@ export function srtMacosCommand(file, args, terms, cwd = process.cwd(), temp) {
         readConfig: terms.readConfig,
         writeConfig: terms.writeConfig,
     };
-    // The runtime anchors its mandatory write denies at this process's working folder: the launch's, for this call.
     const before = process.cwd();
     process.chdir(cwd);
     let command;
@@ -273,27 +200,13 @@ export function srtMacosCommand(file, args, terms, cwd = process.cwd(), temp) {
     }
     return withSeatbeltRules(command, seatbeltRulesFor(terms), params.command);
 }
-/**
- * macOS: what every sandboxed launch runs first, outside the sandbox, before it execs the runtime's command: a session of
- * its own (setsid, syscall 147), so no terminal of whoever started Toolroll is its controlling terminal to reach. A
- * launch that is a session leader already (a live terminal's program, its own terminal made for it) keeps that one; any
- * other that still has a controlling terminal (getsid, syscall 310) is refused. Perl with -t reads neither PERL5OPT nor
- * PERL5LIB, and -X keeps its taint warnings off the launch's output.
- */
 export const DETACH = ["-t", "-X", "-e",
     'syscall(147) != -1 or syscall(310, 0) == $$ or !open(my $t, "<", "/dev/tty") or die "toolroll: the sandboxed launch kept a terminal\\n"; exec { $ARGV[0] } @ARGV; die "toolroll: the sandbox could not start: $!\\n";'];
-/** The Linux helper (sandbox-launch.ts) and the environment variable its launch is handed in. */
 export const SANDBOX_LAUNCH_SPEC = "TOOLROLL_SANDBOX_LAUNCH";
 export const sandboxLaunchHelper = () => {
     const beside = fileURLToPath(new URL("./sandbox-launch.js", import.meta.url));
-    // Run from the sources (the test suite), the built helper is the package's own.
     return existsSync(beside) ? beside : fileURLToPath(new URL("../dist/sandbox-launch.js", import.meta.url));
 };
-/**
- * `file args` inside the runtime's sandbox, as a spawn: on macOS `/bin/sh -c <its command>` in a session of its own
- * (DETACH); on Linux the helper,
- * handed the launch in its environment (never its arguments, which other users can list).
- */
 export function srtSpawn(file, args, terms, cwd = process.cwd(), temp, platform = process.platform) {
     if (platform === "darwin") {
         const command = srtMacosCommand(file, args, terms, cwd, temp);

package/dist/scan.js

@@ -1,19 +1,5 @@
-/**
- * Finding git repositories on disk.
- *
- * This is the first thing Toolroll does and the only thing it does before
- * the operator has configured anything, so it has to be fast, total, and
- * strictly read-only. It reads directory entries. It never opens a file, never
- * follows a symlink, and never descends into a repository it has found.
- */
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
-/**
- * Directories that hold other people's code, build output, or caches. Skipping
- * these is most of the difference between a scan that takes a second and one
- * that takes a minute — a single checkout's `node_modules` can hold thousands
- * of vendored repositories, none of which are yours.
- */
 export const DEFAULT_SKIP = new Set([
     "node_modules",
     "vendor",
@@ -33,13 +19,6 @@ export const DEFAULT_SKIP = new Set([
 ]);
 export const DEFAULT_MAX_DEPTH = 6;
 const GIT_DIR = ".git";
-/**
- * Every repository at or below `roots`, sorted and deduplicated.
- *
- * Unreadable directories are skipped rather than raised: a scan of a home
- * directory will always meet something it cannot open, and that must not be
- * the reason the operator sees nothing.
- */
 export async function findRepos(roots, options = {}) {
     const { maxDepth = DEFAULT_MAX_DEPTH, skip = DEFAULT_SKIP, includeHidden = false } = options;
     const found = new Set();
@@ -74,15 +53,9 @@ async function readEntries(path) {
         return await readdir(path, { withFileTypes: true });
     }
     catch {
-        // Missing, unreadable, or not a directory. All three mean "nothing here".
         return null;
     }
 }
-/**
- * Symlinks are never followed. A link pointing at an ancestor would otherwise
- * make the walk unbounded, and one pointing outside the scanned roots would
- * quietly widen the scan past what the operator asked for.
- */
 function isDescendable(entry, options) {
     if (entry.isSymbolicLink() || !entry.isDirectory())
         return false;