toolroll 0.9.69 → 0.9.70

package/dist/sandbox-runtime.js

@@ -0,0 +1,140 @@
+/**
+ * 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);
+ * the rules themselves, their baseline and their limits are the sandbox 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";
+import { dirname, join } from "node:path";
+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 {
+        const manifest = JSON.parse(readFileSync(join(dirname(require.resolve(name)), "..", "package.json"), "utf8"));
+        return { name, version: typeof manifest.version === "string" ? manifest.version : "unknown" };
+    }
+    catch {
+        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))
+            return "this Mac has no sandbox-exec";
+        const probe = spawnSync(SANDBOX_EXEC, ["-p", SEATBELT_PROBE, "/usr/bin/true"], { timeout: 5_000, stdio: "ignore" });
+        return probe.status === 0 ? null : "sandbox-exec can't start a sandbox here (is this already inside one?)";
+    }
+    if (platform === "linux") {
+        const checked = checkLinuxDependencies();
+        if (checked.errors.length > 0)
+            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" });
+        return probe.status === 0 ? null : "bubblewrap can't start a sandbox here (unprivileged user namespaces may be off)";
+    }
+    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"];
+    if (temp !== undefined && temp !== "")
+        process.env["CLAUDE_CODE_TMPDIR"] = temp;
+    else {
+        delete process.env["CLAUDE_CODE_TMPDIR"];
+        try {
+            mkdirSync("/tmp/claude", { recursive: true, mode: 0o700 });
+        }
+        catch { /* someone else's: writes there fail */ }
+    }
+    try {
+        return make();
+    }
+    finally {
+        if (before.code === undefined)
+            delete process.env["CLAUDE_CODE_TMPDIR"];
+        else
+            process.env["CLAUDE_CODE_TMPDIR"] = before.code;
+        if (before.old !== undefined)
+            process.env["CLAUDE_TMPDIR"] = before.old;
+    }
+}
+/** 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 = {
+        command: shellQuote([file, ...args]),
+        needsNetworkRestriction: network.kind === "proxy",
+        ...(network.kind === "proxy" ? {
+            httpProxyPort: network.httpPort,
+            ...(network.socksPort === undefined ? {} : { socksProxyPort: network.socksPort }),
+            ...(network.token === undefined ? {} : { proxyAuthToken: network.token }),
+            allowLocalBinding: network.localServices,
+            ...(network.unixSockets.length === 0 ? {} : { allowUnixSockets: network.unixSockets }),
+        } : {}),
+        ...(terms.allowMachLookup.length === 0 ? {} : { allowMachLookup: terms.allowMachLookup }),
+        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);
+    try {
+        return withRuntimeTemp(temp, () => wrapCommandWithSandboxMacOS(params));
+    }
+    finally {
+        process.chdir(before);
+    }
+}
+/** 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>`; 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);
+        if (!command.includes(SANDBOX_EXEC))
+            throw new Error("the sandbox runtime returned the command unsandboxed");
+        return { file: "/bin/sh", args: ["-c", command], env: {} };
+    }
+    const spec = { file, args: [...args], cwd, terms, ...(temp === undefined ? {} : { temp }) };
+    return { file: process.execPath, args: [sandboxLaunchHelper()], env: { [SANDBOX_LAUNCH_SPEC]: JSON.stringify(spec) } };
+}

package/dist/scope.d.ts

@@ -81,6 +81,13 @@ export type ClaudeProfile = {
     writes?: WritesMode;
     /** How far its checks reach beyond the check fence (check-access.ts), sealed when wider than sandboxed; absent: sandboxed. */
     checkAccess?: Exclude<CheckAccess, "sandboxed">;
+    /** The fence policy it was sealed under (agent-fence.ts FencePolicy): 2 from 0.9.70 (the home folder read as in
+     * Anthropic's sandbox runtime, less `readDeny`); absent on approvals sealed before, which keep v1's home denies. */
+    fencePolicy?: 2;
+    /** What its builds and checks may not read (project-sandbox.ts), sealed when the project lists any. */
+    readDeny?: string[];
+    /** macOS services its builds may also reach (project-sandbox.ts), sealed when the project lists any. */
+    machLookup?: string[];
 };
 export type CodexShapedProfile = {
     provider: "codex" | "openrouter";
@@ -103,6 +110,13 @@ export type CodexShapedProfile = {
     writes?: WritesMode;
     /** How far its checks reach beyond the check fence (check-access.ts), sealed when wider than sandboxed; absent: sandboxed. */
     checkAccess?: Exclude<CheckAccess, "sandboxed">;
+    /** The fence policy it was sealed under (agent-fence.ts FencePolicy): 2 from 0.9.70 (the home folder read as in
+     * Anthropic's sandbox runtime, less `readDeny`); absent on approvals sealed before, which keep v1's home denies. */
+    fencePolicy?: 2;
+    /** What its builds and checks may not read (project-sandbox.ts), sealed when the project lists any. */
+    readDeny?: string[];
+    /** macOS services its builds may also reach (project-sandbox.ts), sealed when the project lists any. */
+    machLookup?: string[];
 };
 export type GeminiProfile = {
     provider: "gemini";
@@ -127,6 +141,13 @@ export type GeminiProfile = {
     writes?: WritesMode;
     /** How far its checks reach beyond the check fence (check-access.ts), sealed when wider than sandboxed; absent: sandboxed. */
     checkAccess?: Exclude<CheckAccess, "sandboxed">;
+    /** The fence policy it was sealed under (agent-fence.ts FencePolicy): 2 from 0.9.70 (the home folder read as in
+     * Anthropic's sandbox runtime, less `readDeny`); absent on approvals sealed before, which keep v1's home denies. */
+    fencePolicy?: 2;
+    /** What its builds and checks may not read (project-sandbox.ts), sealed when the project lists any. */
+    readDeny?: string[];
+    /** macOS services its builds may also reach (project-sandbox.ts), sealed when the project lists any. */
+    machLookup?: string[];
 };
 /**
  * An agent over the Agent Client Protocol (acp-agents.ts, docs/plans/acp-adapter.md).
@@ -152,6 +173,13 @@ export type AcpProfile = {
     writes?: WritesMode;
     /** How far its checks reach beyond the check fence (check-access.ts), sealed when wider than sandboxed; absent: sandboxed. */
     checkAccess?: Exclude<CheckAccess, "sandboxed">;
+    /** The fence policy it was sealed under (agent-fence.ts FencePolicy): 2 from 0.9.70 (the home folder read as in
+     * Anthropic's sandbox runtime, less `readDeny`); absent on approvals sealed before, which keep v1's home denies. */
+    fencePolicy?: 2;
+    /** What its builds and checks may not read (project-sandbox.ts), sealed when the project lists any. */
+    readDeny?: string[];
+    /** macOS services its builds may also reach (project-sandbox.ts), sealed when the project lists any. */
+    machLookup?: string[];
 };
 export type ExecutionProfile = ClaudeProfile | CodexShapedProfile | GeminiProfile | AcpProfile;
 /** Whether a profile's clock is a no-progress window (an ACP profile has both clocks; its overall one is a deadline). */

package/dist/scope.js

@@ -42,6 +42,7 @@ import { createHash, randomBytes, scryptSync, timingSafeEqual } from "node:crypt
 import { networkFromValue, networkWords } from "./egress.js";
 import { isWritesMode, writesWords } from "./writes-mode.js";
 import { checkAccessWords, isCheckAccess } from "./check-access.js";
+import { MAX_MACH_LOOKUP, MAX_READ_DENY, sandboxTermsWords, validMachLookup, validReadDeny } from "./project-sandbox.js";
 import { z } from "zod";
 import {} from "./contracts/acceptance-terms.js";
 import { parseContract } from "./contracts/contract.js";
@@ -360,9 +361,26 @@ export function profileFromJson(json) {
     if (sealedAccess !== undefined && (sealedAccess === "sandboxed" || !isCheckAccess(sealedAccess)))
         return null;
     const checkAccess = sealedAccess;
-    const withNetwork = { ...(network === undefined ? {} : { network }), ...(writes === undefined ? {} : { writes }), ...(checkAccess === undefined ? {} : { checkAccess }) };
+    // Sandbox parity (v133): the policy version is exactly 2 when present; the lists, when present, are non-empty, sorted,
+    // distinct and valid (project-sandbox.ts), as only this code writes them.
+    const policy = p["fencePolicy"];
+    if (policy !== undefined && policy !== 2)
+        return null;
+    const sealedList = (key, valid, max) => {
+        const list = p[key];
+        if (list === undefined)
+            return undefined;
+        return Array.isArray(list) && list.length > 0 && list.length <= max && list.every(one => typeof one === "string" && valid(one))
+            && list.every((one, at) => at === 0 || list[at - 1] < one) ? [...list] : null;
+    };
+    const readDeny = sealedList("readDeny", validReadDeny, MAX_READ_DENY);
+    const machLookup = sealedList("machLookup", validMachLookup, MAX_MACH_LOOKUP);
+    if (readDeny === null || machLookup === null)
+        return null;
+    const withNetwork = { ...(network === undefined ? {} : { network }), ...(writes === undefined ? {} : { writes }), ...(checkAccess === undefined ? {} : { checkAccess }),
+        ...(policy === undefined ? {} : { fencePolicy: 2 }), ...(readDeny === undefined ? {} : { readDeny }), ...(machLookup === undefined ? {} : { machLookup }) };
     if (p["provider"] === "claude") {
-        if (exactKeys(p, [...PROVIDER_KEYS, "permissionArgv"], ["timeoutKind", "network", "writes", "checkAccess"]) &&
+        if (exactKeys(p, [...PROVIDER_KEYS, "permissionArgv"], ["timeoutKind", "network", "writes", "checkAccess", "fencePolicy", "readDeny", "machLookup"]) &&
             str(p["model"]) &&
             (p["permissionArgv"] === "auto" || p["permissionArgv"] === "acceptEdits" || p["permissionArgv"] === "bypassPermissions") &&
             num(p["maxTurns"]) && num(p["repairMaxTurns"]) &&
@@ -384,7 +402,7 @@ export function profileFromJson(json) {
         return null;
     }
     if (p["provider"] === "codex" || p["provider"] === "openrouter") {
-        if (exactKeys(p, [...PROVIDER_KEYS, "sandboxMode"], ["timeoutKind", "network", "writes", "checkAccess"]) &&
+        if (exactKeys(p, [...PROVIDER_KEYS, "sandboxMode"], ["timeoutKind", "network", "writes", "checkAccess", "fencePolicy", "readDeny", "machLookup"]) &&
             str(p["model"]) &&
             (p["sandboxMode"] === "workspace-write" || p["sandboxMode"] === "danger-full-access") &&
             p["maxTurns"] === "unsupported" && p["repairMaxTurns"] === "unsupported" &&
@@ -406,7 +424,7 @@ export function profileFromJson(json) {
         return null;
     }
     if (p["provider"] === "gemini") {
-        if (exactKeys(p, [...PROVIDER_KEYS, "approvalArgv"], ["timeoutKind", "network", "writes", "checkAccess"]) &&
+        if (exactKeys(p, [...PROVIDER_KEYS, "approvalArgv"], ["timeoutKind", "network", "writes", "checkAccess", "fencePolicy", "readDeny", "machLookup"]) &&
             str(p["model"]) &&
             (p["approvalArgv"] === "auto_edit" || p["approvalArgv"] === "yolo") &&
             p["maxTurns"] === "unsupported" && p["repairMaxTurns"] === "unsupported" &&
@@ -428,7 +446,7 @@ export function profileFromJson(json) {
         return null;
     }
     if (typeof p["provider"] === "string" && isAcpProvider(p["provider"])) {
-        if (exactKeys(p, [...PROVIDER_KEYS, "permission", "idleTimeoutSeconds", "repairIdleTimeoutSeconds"], ["network", "writes", "checkAccess"]) &&
+        if (exactKeys(p, [...PROVIDER_KEYS, "permission", "idleTimeoutSeconds", "repairIdleTimeoutSeconds"], ["network", "writes", "checkAccess", "fencePolicy", "readDeny", "machLookup"]) &&
             str(p["model"]) &&
             p["permission"] === "full" &&
             p["maxTurns"] === "unsupported" && p["repairMaxTurns"] === "unsupported" &&
@@ -1278,6 +1296,8 @@ export function describeScope(scope, readiness = NO_READINESS) {
         ...(scope.profile === null || scope.profile === undefined ? [] : [`  network      ${networkWords(scope.profile.network ?? null).replace(/^Network: /, "")}`]),
         ...(scope.profile === null || scope.profile === undefined ? [] : [`  writes       ${writesWords(scope.profile.writes)}`]),
         ...(scope.profile?.checkAccess === undefined ? [] : [`  checks       ${checkAccessWords(scope.profile.checkAccess)}`]),
+        // Its sandbox terms (project-sandbox.ts), part of what the yes agrees to: what it reads, and any widening.
+        ...(scope.profile === null || scope.profile === undefined ? [] : ((terms) => [`  reads        ${terms.reads}`, ...(terms.mach === null ? [] : [`  services     ${terms.mach}`])])(sandboxTermsWords(scope.profile))),
         `  reference    ${scope.digest}`,
         `  approved     ${describeApproval(approval)}`,
     ];

package/dist/scout-browser-lock.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The scout browser helper's pinned install (scout-browser.ts ensureScoutBrowserHelper): its manifest and lockfile,
+ * generated once with `npm install --package-lock-only --registry https://registry.npmjs.org/` for @playwright/mcp
+ * 0.0.82. `npm ci` installs exactly this tree and refuses any tarball whose sha512 differs. Changing a version here is
+ * a supply-chain change: regenerate both and review the diff.
+ */
+export declare const SCOUT_BROWSER_MANIFEST: {
+    readonly name: "toolroll-scout-browser";
+    readonly private: true;
+    readonly dependencies: {
+        readonly "@playwright/mcp": "0.0.82";
+    };
+};
+export declare const SCOUT_BROWSER_LOCK: {
+    readonly name: "toolroll-scout-browser";
+    readonly lockfileVersion: 3;
+    readonly requires: true;
+    readonly packages: {
+        readonly "": {
+            readonly name: "toolroll-scout-browser";
+            readonly dependencies: {
+                readonly "@playwright/mcp": "0.0.82";
+            };
+        };
+        readonly "node_modules/@playwright/mcp": {
+            readonly version: "0.0.82";
+            readonly resolved: "https://registry.npmjs.org/@playwright/mcp/-/mcp-0.0.82.tgz";
+            readonly integrity: "sha512-OCqftfb8H4dnqm/njbTBRk3seUvUPttOlJUxCtEzXGETYOlRH5Qt3bbXIjmZIuWAxD9RF+yg1ASrPeXvm0y5cA==";
+            readonly license: "Apache-2.0";
+            readonly dependencies: {
+                readonly playwright: "1.64.0-alpha-1789764292000";
+                readonly "playwright-core": "1.64.0-alpha-1789764292000";
+            };
+            readonly bin: {
+                readonly "playwright-mcp": "cli.js";
+            };
+            readonly engines: {
+                readonly node: ">=18";
+            };
+        };
+        readonly "node_modules/playwright": {
+            readonly version: "1.64.0-alpha-1789764292000";
+            readonly resolved: "https://registry.npmjs.org/playwright/-/playwright-1.64.0-alpha-1789764292000.tgz";
+            readonly integrity: "sha512-3Ngs4ERGdC912uW3srEDtNVey4u1wSaQ/EFcKhxMpz0by0K6nidaJgM087pLpJc1osytiVnL7ack5gvgPArPNw==";
+            readonly license: "Apache-2.0";
+            readonly dependencies: {
+                readonly "playwright-core": "1.64.0-alpha-1789764292000";
+            };
+            readonly bin: {
+                readonly playwright: "cli.js";
+            };
+            readonly engines: {
+                readonly node: ">=20";
+            };
+        };
+        readonly "node_modules/playwright-core": {
+            readonly version: "1.64.0-alpha-1789764292000";
+            readonly resolved: "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.0-alpha-1789764292000.tgz";
+            readonly integrity: "sha512-ZgRaybFv4rRy7QMGnYprEGFdNJnvapNqcaER2w96bDQA+40BWIle1el1Yh9KHD3E6XYmieMB+r+UxFTCauTGGQ==";
+            readonly license: "Apache-2.0";
+            readonly bin: {
+                readonly "playwright-core": "cli.js";
+            };
+            readonly engines: {
+                readonly node: ">=20";
+            };
+        };
+    };
+};

package/dist/scout-browser-lock.js

@@ -0,0 +1,69 @@
+/**
+ * The scout browser helper's pinned install (scout-browser.ts ensureScoutBrowserHelper): its manifest and lockfile,
+ * generated once with `npm install --package-lock-only --registry https://registry.npmjs.org/` for @playwright/mcp
+ * 0.0.82. `npm ci` installs exactly this tree and refuses any tarball whose sha512 differs. Changing a version here is
+ * a supply-chain change: regenerate both and review the diff.
+ */
+export const SCOUT_BROWSER_MANIFEST = {
+    "name": "toolroll-scout-browser",
+    "private": true,
+    "dependencies": {
+        "@playwright/mcp": "0.0.82"
+    }
+};
+export const SCOUT_BROWSER_LOCK = {
+    "name": "toolroll-scout-browser",
+    "lockfileVersion": 3,
+    "requires": true,
+    "packages": {
+        "": {
+            "name": "toolroll-scout-browser",
+            "dependencies": {
+                "@playwright/mcp": "0.0.82"
+            }
+        },
+        "node_modules/@playwright/mcp": {
+            "version": "0.0.82",
+            "resolved": "https://registry.npmjs.org/@playwright/mcp/-/mcp-0.0.82.tgz",
+            "integrity": "sha512-OCqftfb8H4dnqm/njbTBRk3seUvUPttOlJUxCtEzXGETYOlRH5Qt3bbXIjmZIuWAxD9RF+yg1ASrPeXvm0y5cA==",
+            "license": "Apache-2.0",
+            "dependencies": {
+                "playwright": "1.64.0-alpha-1789764292000",
+                "playwright-core": "1.64.0-alpha-1789764292000"
+            },
+            "bin": {
+                "playwright-mcp": "cli.js"
+            },
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/playwright": {
+            "version": "1.64.0-alpha-1789764292000",
+            "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.0-alpha-1789764292000.tgz",
+            "integrity": "sha512-3Ngs4ERGdC912uW3srEDtNVey4u1wSaQ/EFcKhxMpz0by0K6nidaJgM087pLpJc1osytiVnL7ack5gvgPArPNw==",
+            "license": "Apache-2.0",
+            "dependencies": {
+                "playwright-core": "1.64.0-alpha-1789764292000"
+            },
+            "bin": {
+                "playwright": "cli.js"
+            },
+            "engines": {
+                "node": ">=20"
+            }
+        },
+        "node_modules/playwright-core": {
+            "version": "1.64.0-alpha-1789764292000",
+            "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.0-alpha-1789764292000.tgz",
+            "integrity": "sha512-ZgRaybFv4rRy7QMGnYprEGFdNJnvapNqcaER2w96bDQA+40BWIle1el1Yh9KHD3E6XYmieMB+r+UxFTCauTGGQ==",
+            "license": "Apache-2.0",
+            "bin": {
+                "playwright-core": "cli.js"
+            },
+            "engines": {
+                "node": ">=20"
+            }
+        }
+    }
+};

package/dist/scout-browser.d.ts

@@ -17,6 +17,12 @@ export type BrowserStarter = (launch: BrowserLaunch, options: BrowserOptions) =>
 export type BrowserOptions = {
     /** The browser tool's environment: the scout's own, its proxy settings included. */
     env: Record<string, string | undefined>;
+    /** Toolroll's helpers folder (in its state folder) the pinned browser is installed in, and the scout's proxy: the
+     * launch contract's trusted inputs, from the plane, never from the launch. */
+    contract?: {
+        helpers: string;
+        proxy: string;
+    };
     /** Where it saves screenshots (its `--output-dir`), also its working folder. */
     folder: string;
     /** The whole start and check, from spawn to screenshot (review 828: at most 60 seconds). */
@@ -24,7 +30,8 @@ export type BrowserOptions = {
 };
 /** The public page the check opens through the scout's proxy. */
 export declare const PREFLIGHT_PAGE = "https://example.com/";
-/** How a scout gets its browser: started for real, or, for a test's stub agent, a placeholder that starts nothing. */
+/** How a scout gets its browser: started for real under its launch contract, or, for a test's stub agent, a placeholder
+ * that starts nothing. */
 export declare function starterFor(agentInjected: boolean): BrowserStarter;
 /** Start the browser tool outside the fence and check it opens a public page and saves a screenshot. */
 export declare function startScoutBrowser(launch: BrowserLaunch, options: BrowserOptions): Promise<BrowserStart>;
@@ -46,3 +53,55 @@ export type McpSession = {
 };
 /** A client of the browser's HTTP transport, as the scout's own is: every step answers by `deadline`, or says why not. */
 export declare function openSession(url: string, deadline: number, late: string): McpSession;
+/** The pinned browser tool, installed once into Toolroll's helpers folder. */
+export declare const SCOUT_BROWSER_PACKAGE = "@playwright/mcp@0.0.82";
+/** The names of the worker's environment the browser tool gets: an allowlist, never a denylist. */
+export declare const SCOUT_BROWSER_ENV: readonly string[];
+/** What the run records of the exception it ran under. */
+export declare const SCOUT_BROWSER_CONTAINMENT = "Chrome's sandbox";
+/** Where the pinned browser lives under `helpers`. */
+export declare function scoutBrowserHelper(helpers: string): {
+    folder: string;
+    cli: string;
+    browsers: string;
+};
+/** The scout's browser tool: the pinned helper, run by Toolroll's own Node, headless, on its bundled Chrome. */
+export declare function scoutBrowserTool(helpers: string): BrowserLaunch;
+/**
+ * Why a browser launch breaks its contract, or null when it holds. Every input it trusts is the plane's: the helpers
+ * folder and the proxy come from `options.contract`, never from the launch. The executable must be Toolroll's own
+ * Node; the script the pinned helper's, inside a private helpers folder; the arguments exactly the expected ones (no
+ * way to switch Chrome's sandbox off, point at another browser or executable, or drop the proxy); the working folder
+ * the image folder; the environment only allowlisted names.
+ */
+export declare function browserContractProblem(launch: BrowserLaunch, options: BrowserOptions): string | null;
+/** The pinned lockfile's digest, recorded when the helper is installed and checked before every use. */
+export declare const SCOUT_BROWSER_LOCK_DIGEST: string;
+/** The npm of the Node running Toolroll (`lib/node_modules/npm/bin/npm-cli.js` beside it), run by that Node by path:
+ * never an `npm` found on PATH. Null where this Node has none beside it (a bundled runtime). */
+export declare function ownNpm(execPath?: string): string | null;
+/**
+ * Install the pinned browser into the helpers folder once. The worker runs this outside every fence, so nothing a build
+ * could have written may steer it: npm is Toolroll's own Node's, run by path; HOME is the staging folder and the user
+ * and global npm configurations are an empty file there (no ~/.npmrc, no global npmrc, no registry, script or Node
+ * option from either); the registry is pinned; install scripts never run; `npm ci` installs exactly the pinned lockfile
+ * (scout-browser-lock.ts) and refuses a tarball whose integrity differs; the installed versions are checked against it
+ * before ready.json is written. The npm cache and Chrome for Testing stay in the folder, never in the user's caches.
+ * Residual: Chrome for Testing comes from Playwright's own download over HTTPS, without a pinned hash.
+ */
+export declare function ensureScoutBrowserHelper(helpers: string, timeoutMs?: number): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** How the helper's npm runs in `staging`: Toolroll's own npm by path, with its home, user and global configuration
+ * the staging folder's own empty ones, the registry and cache pinned; the environment only these names. */
+export declare function helperNpm(staging: string, npm: string): {
+    env: Record<string, string>;
+    args: string[];
+};
+/** What of an installed tree differs from the pinned lockfile (a package missing or at another version), or null. */
+export declare function lockDrift(folder: string): string | null;
+/** The production starter: the pinned helper in place, then the launch held to its contract, then started. */
+export declare function startContractedBrowser(launch: BrowserLaunch, options: BrowserOptions): Promise<BrowserStart>;