@sagentlab/navarch-runtime 0.1.92 → 0.1.93

package/README.md

@@ -9,6 +9,16 @@ environment, outside the coding agent's OS sandbox, with a fresh browser
 context for desktop and touch-enabled mobile captures. It neither uses the
 operator's browser profile nor executes agent-provided scripts.
 
+The same server offers interactive `local_browser_open`, `local_browser_click`,
+`local_browser_fill`, `local_browser_press`, `local_browser_snapshot`, and
+`local_browser_screenshot` tools for walking through a service the agent starts
+on this machine. That browser is limited to loopback (`localhost`,
+`*.localhost`, `127.0.0.0/8`, `::1`). Every request, WebSocket, or navigation
+to any other host is aborted and listed in the tool result. The agent's own
+sandbox can already reach these services, so the tools add a browser without
+adding network reach. Each lease gets one tab at a time, a fresh context per
+viewport, and at most 300 actions.
+
 Install the runtime's pinned browser once on the agent host (and after a
 Playwright version update):
 
@@ -36,9 +46,13 @@ lifetime, so restart the agent after fixing the browser to re-probe.
 `navarch-runtime doctor` runs the same check.
 
 Codex's macOS seatbelt denies Chromium's Mach port registration
-(`bootstrap_check_in ... MachPortRendezvousServer: Permission denied`), so a
-sandboxed Codex machine on macOS does not take browser tasks. Run those with
-another agent such as Claude Code, or use Docker mode. Docker mode is not
+(`bootstrap_check_in ... MachPortRendezvousServer: Permission denied`), and
+`--single-process` crashes once a second page opens. When Node runs in the
+sandbox and only Chromium fails, the probe still passes, with that reason. Codex
+sessions then browse local services through the `local_browser_*` tools above,
+and the session prompt tells them to. With an operator `NAVARCH_MCP_CONFIG_PATH`
+those tools are absent, so the machine does not take browser tasks; run those
+with another agent such as Claude Code, or use Docker mode. Docker mode is not
 probed because its image supplies the browser. Set `NAVARCH_BROWSER_PROBE=off`
 to trust the configured capability list without a check.
 

package/dist/browser-evidence.cjs

@@ -13,6 +13,7 @@ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const playwright_1 = require("playwright");
 const zod_1 = require("zod");
+const local_browser_cjs_1 = require("./local-browser.cjs");
 const node_child_process_1 = require("node:child_process");
 const node_util_1 = require("node:util");
 const node_path_1 = __importDefault(require("node:path"));
@@ -46,7 +47,8 @@ const captureShape = {
 exports.captureSchema = zod_1.z.object(captureShape);
 /** Runs in the supervisor, outside the coding agent's OS sandbox. Fresh
  * contexts have no user cookies, arbitrary script execution, or file access.
- * Only the narrow capture operation is exposed to the lease. */
+ * The lease gets the narrow capture operation plus the loopback-only
+ * local_browser_* tools (local-browser.cts). */
 async function startBrowserEvidence(options) {
     const token = (0, node_crypto_1.randomBytes)(32).toString("hex");
     const fetchImpl = options.fetchImpl ?? fetch;
@@ -57,6 +59,10 @@ async function startBrowserEvidence(options) {
     let browser;
     let activeCapture;
     let attempts = 0;
+    const localBrowser = (0, local_browser_cjs_1.createLocalBrowser)({
+        launch: options.launch ?? launchCaptureBrowser,
+        isActive: () => !closed && options.isActive(),
+    });
     const assertActive = () => {
         if (closed || !options.isActive())
             throw new Error("Browser evidence lease is no longer active.");
@@ -204,6 +210,7 @@ async function startBrowserEvidence(options) {
                 return { isError: true, content: [{ type: "text", text: String(error) }] };
             }
         });
+        (0, local_browser_cjs_1.registerLocalBrowserTools)(server, localBrowser);
         res.on("close", () => { void transport.close(); void server.close(); });
         try {
             await server.connect(transport);
@@ -253,6 +260,7 @@ async function startBrowserEvidence(options) {
             const stopped = new Promise((resolve) => http.close(() => resolve()));
             http.closeAllConnections();
             await browser?.close().catch(() => undefined);
+            await localBrowser.close();
             await activeCapture?.catch(() => undefined);
             await stopped;
         },

package/dist/browser-probe.cjs

@@ -74,8 +74,19 @@ async function probeBrowserCapability(config, deps = {}) {
     const platform = deps.platform ?? process.platform;
     if (codexSandboxNeedsProbe(config, platform)) {
         const sandboxFailure = await probeCodexSandbox(config, deps);
+        if (sandboxFailure?.browserOnly && !config.mcpConfigPath) {
+            // Node runs in the sandbox, so the agent can start its services there;
+            // only Chromium cannot. Sessions get the supervisor's local_browser_*
+            // tools (local-browser.cts) instead, which reach the same loopback.
+            return {
+                status: "passed",
+                reason: truncate(`Headless Chromium cannot start inside the Codex sandbox (${sandboxFailure.detail}); ` +
+                    "Codex sessions browse local services through Navarch's local_browser tools, which run outside it."),
+                checked_at: now().toISOString(),
+            };
+        }
         if (sandboxFailure) {
-            return { status: "failed", reason: truncate(sandboxFailure), checked_at: now().toISOString() };
+            return { status: "failed", reason: truncate(sandboxFailure.reason), checked_at: now().toISOString() };
         }
     }
     return { status: "passed", checked_at: now().toISOString() };
@@ -215,8 +226,9 @@ async function probeCodexSandbox(config, deps) {
             // sandbox view: a path outside the granted read roots, not an old CLI.
             const hidden = /bwrap: execvp .*No such file or directory/.test(output);
             const opensslConfig = /OpenSSL configuration error/.test(output);
-            return ("Could not verify a browser inside the Codex sandbox: `codex sandbox` did not run the probe " +
-                `(${result.timedOut ? "timed out" : output.trim() ? summarizeLaunchFailure(output) : `exit ${result.code}`}). ` +
+            const detail = result.timedOut ? "timed out" : output.trim() ? summarizeLaunchFailure(output) : `exit ${result.code}`;
+            const reason = ("Could not verify a browser inside the Codex sandbox: `codex sandbox` did not run the probe " +
+                `(${detail}). ` +
                 (hidden
                     ? "The sandbox cannot see that executable; add its install directory to NAVARCH_GUARD_EXTRA_ROOTS, " +
                         "or run browser tasks with another agent."
@@ -224,19 +236,22 @@ async function probeCodexSandbox(config, deps) {
                         ? "Node cannot read its OpenSSL config inside the sandbox, so Codex sessions cannot run node either; " +
                             "update the Navarch runtime, or add that file's directory to NAVARCH_GUARD_EXTRA_ROOTS."
                         : "Update the Codex CLI, or run browser tasks with another agent."));
+            return { reason, detail, browserOnly: false };
         }
         const detail = result.timedOut ? "the launch timed out." : summarizeLaunchFailure(output);
         const machPort = /bootstrap_check_in|MachPortRendezvous|mach_port_rendezvous/i.test(output);
-        return (`Headless Chromium cannot start inside the Codex sandbox: ${detail} ` +
+        const reason = (`Headless Chromium cannot start inside the Codex sandbox: ${detail} ` +
             (machPort
                 ? "Codex's macOS sandbox denies Chromium's Mach port registration. "
                 : "") +
             "Run browser tasks with another agent (for example Claude Code), use NAVARCH_SANDBOX_MODE=docker, " +
             "or run Codex without its sandbox.");
+        return { reason, detail, browserOnly: true };
     }
     catch (error) {
         log.warn(`codex sandbox browser probe could not run: ${String(error)}`);
-        return `Could not verify a browser inside the Codex sandbox: ${summarizeLaunchFailure(String(error))}`;
+        const detail = summarizeLaunchFailure(String(error));
+        return { reason: `Could not verify a browser inside the Codex sandbox: ${detail}`, detail, browserOnly: false };
     }
     finally {
         await node_fs_1.promises.rm(probeRoot, { recursive: true, force: true }).catch(() => undefined);

package/dist/cli.cjs

@@ -248,7 +248,7 @@ async function startCommand(flags) {
         log.warn(`not advertising browser-use: ${browserProbe.reason}`);
     }
     else if (browserProbe.status === "passed") {
-        log.info("browser probe passed; advertising browser-use");
+        log.info(`browser probe passed; advertising browser-use${browserProbe.reason ? ` (${browserProbe.reason})` : ""}`);
     }
     const config = {
         ...configuredConfig,

package/dist/local-browser.cjs

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localBrowserShapes = void 0;
+exports.isLoopbackUrl = isLoopbackUrl;
+exports.createLocalBrowser = createLocalBrowser;
+exports.registerLocalBrowserTools = registerLocalBrowserTools;
+const node_net_1 = require("node:net");
+const playwright_1 = require("playwright");
+const zod_1 = require("zod");
+/**
+ * Interactive browser for services the agent starts on this machine.
+ *
+ * Codex's macOS seatbelt denies Chromium's Mach port registration
+ * (`bootstrap_check_in ... MachPortRendezvousServer: Permission denied`), so
+ * no browser can start inside a Codex session there, and `--single-process`
+ * crashes as soon as a second page opens. This Chromium runs in the
+ * supervisor instead, next to capture_visual_evidence, and is limited to
+ * loopback: the agent's own sandbox can already reach localhost, so these
+ * tools add a browser without adding network reach. Every request, WebSocket,
+ * and navigation to any other host is aborted and reported back.
+ */
+const MAX_ACTIONS = 300;
+const ACTION_TIMEOUT_MS = 10_000;
+const NAVIGATION_TIMEOUT_MS = 30_000;
+const MAX_SNAPSHOT_CHARS = 12_000;
+const MAX_LOG_LINES = 15;
+/** http(s)/ws(s) on localhost, *.localhost, 127.0.0.0/8, or ::1, without embedded credentials. */
+function isLoopbackUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (!["http:", "https:", "ws:", "wss:"].includes(url.protocol) || url.username || url.password)
+        return false;
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    if ((0, node_net_1.isIP)(host) === 4)
+        return host.split(".")[0] === "127";
+    return host === "::1";
+}
+const loopbackUrl = zod_1.z.string().refine(isLoopbackUrl, "Only services on this machine are reachable: use http://localhost:<port> or http://127.0.0.1:<port>.");
+const selector = zod_1.z.string().min(1).max(500).describe("Playwright selector, e.g. `text=Sign in`, `role=button[name=\"Save\"]`, or CSS.");
+exports.localBrowserShapes = {
+    open: {
+        url: loopbackUrl,
+        viewport: zod_1.z.enum(["desktop", "mobile"]).default("desktop"),
+    },
+    click: { selector },
+    fill: { selector, value: zod_1.z.string().max(10_000) },
+    press: {
+        key: zod_1.z.string().min(1).max(50).describe("Key or chord, e.g. `Enter`, `Tab`, `Control+A`."),
+        selector: selector.optional(),
+    },
+    snapshot: {},
+    screenshot: { full_page: zod_1.z.boolean().default(false) },
+};
+function createLocalBrowser(options) {
+    let browser;
+    let context;
+    let page;
+    let viewport;
+    let actions = 0;
+    let closed = false;
+    let creatingPage = false;
+    let queue = Promise.resolve();
+    let notes = [];
+    const blocked = new Set();
+    const logs = [];
+    const log = (line) => {
+        logs.push(line.slice(0, 500));
+        if (logs.length > MAX_LOG_LINES)
+            logs.shift();
+    };
+    const block = (url) => {
+        try {
+            blocked.add(new URL(url).origin);
+        }
+        catch {
+            blocked.add(url.slice(0, 100));
+        }
+    };
+    function track(next) {
+        page = next;
+        next.on("console", (message) => {
+            if (["error", "warning"].includes(message.type()))
+                log(`console.${message.type()}: ${message.text()}`);
+        });
+        next.on("pageerror", (error) => log(`pageerror: ${error.message}`));
+    }
+    async function ensureContext(wanted) {
+        if (context && viewport === wanted)
+            return context;
+        await context?.close().catch(() => undefined);
+        context = undefined;
+        page = undefined;
+        try {
+            browser ??= await options.launch();
+        }
+        catch {
+            throw new Error("The local browser could not start. On the agent host run `navarch-runtime browser-install`.");
+        }
+        const created = await browser.newContext({
+            ...(wanted === "mobile" ? playwright_1.devices["iPhone 13"] : { viewport: { width: 1440, height: 900 } }),
+            acceptDownloads: false,
+            // Service workers would answer fetches before the route below sees them.
+            serviceWorkers: "block",
+        });
+        await created.route("**/*", (route) => {
+            const url = route.request().url();
+            if (isLoopbackUrl(url))
+                return route.continue();
+            block(url);
+            return route.abort("blockedbyclient");
+        });
+        await created.routeWebSocket(() => true, (socket) => {
+            if (isLoopbackUrl(socket.url()))
+                return socket.connectToServer();
+            block(socket.url());
+            return socket.close({ code: 1008, reason: "Only loopback services are reachable." });
+        });
+        created.on("page", (opened) => {
+            if (creatingPage || opened === page)
+                return;
+            track(opened);
+            notes.push("A new tab opened; it is now the active page.");
+        });
+        context = created;
+        viewport = wanted;
+        return created;
+    }
+    function currentPage() {
+        if (!page || page.isClosed())
+            throw new Error("No page is open. Call local_browser_open first.");
+        return page;
+    }
+    async function snapshot(heading) {
+        const active = currentPage();
+        let tree;
+        try {
+            tree = await active.locator("body").ariaSnapshot({ timeout: 5_000 });
+        }
+        catch (error) {
+            tree = `(accessibility snapshot unavailable: ${String(error).split("\n")[0]})`;
+        }
+        if (tree.length > MAX_SNAPSHOT_CHARS)
+            tree = `${tree.slice(0, MAX_SNAPSHOT_CHARS)}\n… (truncated)`;
+        const lines = [
+            ...(heading ? [heading] : []),
+            ...notes,
+            ...(active.url().startsWith("chrome-error://")
+                ? ["The last navigation failed or tried to leave this machine and was blocked. Use local_browser_open to continue."]
+                : []),
+            `URL: ${active.url()}`,
+            `Title: ${await active.title().catch(() => "")}`,
+            `Viewport: ${viewport}`,
+            ...(logs.length ? ["Recent console/page errors:", ...logs.map((line) => `  ${line}`)] : []),
+            ...(blocked.size
+                ? [`Blocked non-loopback requests (this browser reaches only this machine): ${[...blocked].slice(-10).join(", ")}`]
+                : []),
+            "",
+            tree,
+        ];
+        notes = [];
+        return [{ type: "text", text: lines.join("\n") }];
+    }
+    /** Runs tool calls one at a time; a lease ending stops further use. */
+    function run(action) {
+        const next = queue.then(async () => {
+            if (closed || !options.isActive())
+                throw new Error("The local browser lease is no longer active.");
+            if (++actions > MAX_ACTIONS)
+                throw new Error(`This lease reached its ${MAX_ACTIONS} local browser actions.`);
+            return action();
+        });
+        queue = next.catch(() => undefined);
+        return next;
+    }
+    async function settle(active) {
+        await active.waitForLoadState("load", { timeout: 5_000 }).catch(() => undefined);
+    }
+    return {
+        open(args) {
+            return run(async () => {
+                if (!isLoopbackUrl(args.url))
+                    throw new Error("Only loopback URLs are reachable.");
+                const created = await ensureContext(args.viewport ?? "desktop");
+                if (!page || page.isClosed()) {
+                    creatingPage = true;
+                    try {
+                        track(await created.newPage());
+                    }
+                    finally {
+                        creatingPage = false;
+                    }
+                }
+                const response = await currentPage().goto(args.url, { waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS });
+                return snapshot(`HTTP ${response?.status() ?? "(no response)"}`);
+            });
+        },
+        click(args) {
+            return run(async () => {
+                const active = currentPage();
+                await active.locator(args.selector).first().click({ timeout: ACTION_TIMEOUT_MS });
+                await settle(active);
+                return snapshot();
+            });
+        },
+        fill(args) {
+            return run(async () => {
+                await currentPage().locator(args.selector).first().fill(args.value, { timeout: ACTION_TIMEOUT_MS });
+                return snapshot();
+            });
+        },
+        press(args) {
+            return run(async () => {
+                const active = currentPage();
+                if (args.selector)
+                    await active.locator(args.selector).first().press(args.key, { timeout: ACTION_TIMEOUT_MS });
+                else
+                    await active.keyboard.press(args.key);
+                await settle(active);
+                return snapshot();
+            });
+        },
+        snapshot() {
+            return run(() => snapshot());
+        },
+        screenshot(args) {
+            return run(async () => {
+                const bytes = await currentPage().screenshot({ type: "png", fullPage: args.full_page ?? false, timeout: ACTION_TIMEOUT_MS });
+                return [
+                    { type: "text", text: `Screenshot of ${currentPage().url()} (${viewport}). Not uploaded; use capture_visual_evidence for PR evidence.` },
+                    { type: "image", data: bytes.toString("base64"), mimeType: "image/png" },
+                ];
+            });
+        },
+        async close() {
+            closed = true;
+            await queue.catch(() => undefined);
+            await context?.close().catch(() => undefined);
+            await browser?.close().catch(() => undefined);
+            browser = undefined;
+            context = undefined;
+            page = undefined;
+        },
+    };
+}
+const toolResult = (call) => call().then((content) => ({ content }), (error) => ({ isError: true, content: [{ type: "text", text: String(error) }] }));
+/** Registers the local_browser_* tools on a lease's navarch-browser MCP server. */
+function registerLocalBrowserTools(server, browser) {
+    server.registerTool("local_browser_open", {
+        description: "Open a page served on this machine (http://localhost:<port> or 127.0.0.1) in Navarch's browser, which runs outside the coding-agent sandbox. Start your dev server first. Reuses one tab; switching viewport starts a fresh session. Returns the page's accessibility snapshot, console errors, and any blocked non-loopback requests.",
+        inputSchema: exports.localBrowserShapes.open,
+    }, (args) => toolResult(() => browser.open(args)));
+    server.registerTool("local_browser_click", {
+        description: "Click the first element matching a Playwright selector on the open local page, then return the updated snapshot.",
+        inputSchema: exports.localBrowserShapes.click,
+    }, (args) => toolResult(() => browser.click(args)));
+    server.registerTool("local_browser_fill", {
+        description: "Replace the value of an input, textarea, or contenteditable on the open local page, then return the snapshot.",
+        inputSchema: exports.localBrowserShapes.fill,
+    }, (args) => toolResult(() => browser.fill(args)));
+    server.registerTool("local_browser_press", {
+        description: "Press a key (optionally focused on a selector) on the open local page, then return the snapshot.",
+        inputSchema: exports.localBrowserShapes.press,
+    }, (args) => toolResult(() => browser.press(args)));
+    server.registerTool("local_browser_snapshot", {
+        description: "Return the open local page's URL, title, accessibility snapshot, console errors, and blocked requests.",
+        inputSchema: exports.localBrowserShapes.snapshot,
+    }, () => toolResult(() => browser.snapshot()));
+    server.registerTool("local_browser_screenshot", {
+        description: "Return a PNG of the open local page for inspection. Not uploaded as evidence.",
+        inputSchema: exports.localBrowserShapes.screenshot,
+    }, (args) => toolResult(() => browser.screenshot(args)));
+}

package/dist/session.cjs

@@ -459,7 +459,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             const mcp = JSON.parse(await node_fs_1.promises.readFile(mcpConfigPath, "utf8"));
             mcp.mcpServers.navarch_browser = browserEvidence.config;
             await node_fs_1.promises.writeFile(mcpConfigPath, JSON.stringify(mcp), { mode: 0o600 });
-            promptText += "\n\nNavarch supplies capture_visual_evidence through navarch_browser. Use it first for desktop/mobile screenshots of the verified preview URL and source commit. It runs outside the coding-agent sandbox, uploads images as task artifacts, and the runtime attaches them to the delivery PR before completion. Inspect the returned images before accepting the UI. Do not use GitHub's upload UI or add capture tools to the target repository. If the base commit has no runnable UI, report before evidence as not applicable with the base SHA and reason; still capture the current head. Authentication or interactive walkthroughs may require the existing browser tools.\n";
+            promptText += "\n\nNavarch supplies capture_visual_evidence through navarch_browser. Use it first for desktop/mobile screenshots of the verified preview URL and source commit. It runs outside the coding-agent sandbox, uploads images as task artifacts, and the runtime attaches them to the delivery PR before completion. Inspect the returned images before accepting the UI. Do not use GitHub's upload UI or add capture tools to the target repository. If the base commit has no runnable UI, report before evidence as not applicable with the base SHA and reason; still capture the current head. For interactive walkthroughs of a service you start on this machine, use navarch_browser's local_browser_open, local_browser_click, local_browser_fill, local_browser_press, local_browser_snapshot, and local_browser_screenshot with http://localhost:<port> or http://127.0.0.1:<port>. That browser also runs outside the sandbox and reaches only this machine's loopback services; prefer it over launching Chromium yourself, which Codex's macOS sandbox kills at startup.\n";
         }
         if (gitWorktree.hostedCheckpointRestoreFailure) {
             log.warn(`hosted checkpoint for ${leaseId} could not be restored: ` +

package/dist/worktree-guard.cjs

@@ -291,6 +291,13 @@ function codexWorktreeGuardArgs(options, platform = process.platform) {
         [node_path_1.default.resolve(options.repositoryPath)]: "write",
         [sessionGhConfigDir(options.workDir)]: "read",
     };
+    // Codex protects a linked worktree's gitdir with a more specific read-only
+    // rule. A write grant on the bare repository alone does not override it:
+    // fetch/checkout/commit fail on FETCH_HEAD, HEAD.lock, or index.lock. Grant
+    // the runtime-created gitdir explicitly, without reopening session metadata.
+    const gitdir = linkedWorktreeGitDir(options.worktreePath, options.repositoryPath);
+    if (gitdir)
+        filesystem[gitdir] = "write";
     const overlapsWorkspace = (root) => isPathInside(root, workspaceRoot) || (linux && isPathInside(workspaceRoot, root));
     const readRoots = [
         ...codexToolReadRoots(process.env, platform),
@@ -333,6 +340,36 @@ function codexWorktreeGuardArgs(options, platform = process.platform) {
         `permissions.${CODEX_GUARD_PROFILE}.network.domains=${tomlInlineTable(CODEX_GITHUB_NETWORK_DOMAINS)}`,
     ];
 }
+function linkedWorktreeGitDir(worktreePath, repositoryPath) {
+    let dotGit;
+    try {
+        dotGit = (0, node_fs_1.readFileSync)(node_path_1.default.join(worktreePath, ".git"), "utf8");
+    }
+    catch (error) {
+        // A regular checkout has a .git directory; tests may use virtual paths.
+        const code = error.code;
+        if (code === "ENOENT" || code === "EISDIR")
+            return undefined;
+        throw error;
+    }
+    const match = /^gitdir: (.+)\s*$/m.exec(dotGit);
+    if (!match)
+        return undefined;
+    const canonical = (root) => {
+        try {
+            return (0, node_fs_1.realpathSync)(root);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return node_path_1.default.resolve(root);
+            throw error;
+        }
+    };
+    const gitdir = canonical(node_path_1.default.resolve(worktreePath, match[1].trim()));
+    const repository = canonical(repositoryPath);
+    // Never turn a pointer outside the runtime's repository into a new grant.
+    return gitdir !== repository && isPathInside(gitdir, repository) ? gitdir : undefined;
+}
 /**
  * Mounts only the current session roots into Gemini CLI's native sandbox.
  * Gemini mounts cwd itself; explicit same-path mounts keep the shared gitdir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.92",
+  "version": "0.1.93",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",