@sagentlab/navarch-runtime 0.1.91 → 0.1.93

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/prompt.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderPrompt = renderPrompt;
 exports.renderGuidanceCorrectionPrompt = renderGuidanceCorrectionPrompt;
+exports.renderCompletionRemediationPrompt = renderCompletionRemediationPrompt;
 exports.renderHostedCheckpointNote = renderHostedCheckpointNote;
 const CODE_GRAPH_GUIDANCE = "For JS/TS dependency inspection, the runtime provides `navarch-runtime code-graph --query <symbol-or-file> --mode search|callers|callees|impact --commit HEAD`. If the runtime is not on PATH, use its installed entry point; do not install another copy mid-task. Results describe committed source and include commit/freshness warnings; inspect current files for uncommitted changes and unresolved dependencies.";
 const PROCESS_GUIDANCE = "Process management: this host may run other agent sessions. Keep the PID or tool handle of each preview server you start and stop only that owned process. Never use broad process-name or command-line matching (pkill, killall) to clean up servers: the agent launcher carries the task prompt in its arguments and can match those patterns, terminating your own session. Use a different port when a port is occupied by a process you do not own. Keep scratch files in the current worktree; paths in previous transcripts belong to earlier sessions.";
@@ -74,6 +75,40 @@ function renderGuidanceCorrectionPrompt(originalPrompt, guidance) {
         "",
     ].join("\n");
 }
+/** Keeps a long previous report from crowding the brief out of the prompt. */
+const REMEDIATION_REPORT_LIMIT = 8_000;
+/**
+ * Builds the turn that follows a remediable completion rejection (for example
+ * `verification_verdict_invalid` or `pr_required`). Each turn is a fresh agent
+ * invocation with no memory of the last one, so the rejection alone gave the
+ * agent nothing to act on: a verifier answered BLOCKED because it had "no
+ * acceptance criteria or task to verify". The turn therefore carries the full
+ * task brief, the rejection, and the previous turn's report.
+ */
+function renderCompletionRemediationPrompt(args) {
+    const report = args.previousReport.trim();
+    const clipped = report.length > REMEDIATION_REPORT_LIMIT
+        ? `${report.slice(0, REMEDIATION_REPORT_LIMIT)}\n\n[... truncated]`
+        : report;
+    return [
+        args.originalPrompt.trim(),
+        "",
+        "## Completion was rejected",
+        "",
+        "Your previous turn on this task finished, but the Navarch control plane rejected its completion:",
+        "",
+        ...args.rejection.trim().split("\n").map((line) => `> ${line}`),
+        "",
+        `This is correction turn ${args.attempt} of ${args.maxAttempts}. The task above is unchanged, and you are in the`,
+        "same worktree, so earlier edits, commits, and branches are still here. Reuse the work and findings from",
+        "the previous turn instead of starting over, fix what the rejection names, and finish the task.",
+        "Your final report replaces the previous one, so restate it in full in the required format.",
+        ...(clipped
+            ? ["", "### Previous turn's final report", "", clipped]
+            : []),
+        "",
+    ].join("\n");
+}
 /**
  * Tells the agent its worktree starts from a hosted attempt's checkpoint
  * (GitWorktree.restoredHostedCheckpoint), mirroring the hosted side's own

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: ` +
@@ -523,10 +523,12 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             activeAbortController = new AbortController();
             if (leaseLost || deps.shutdownSignal?.aborted)
                 activeAbortController.abort();
-            const runPrompt = nextPrompt ??
-                (deliveredGuidance.length > (bundle.guidance?.length ?? 0)
-                    ? (0, prompt_cjs_1.renderGuidanceCorrectionPrompt)(promptText, deliveredGuidance)
-                    : promptText);
+            // The task brief plus any mid-flight guidance. Correction turns build on
+            // this rather than on the previous turn's prompt so they never nest.
+            const briefPrompt = deliveredGuidance.length > (bundle.guidance?.length ?? 0)
+                ? (0, prompt_cjs_1.renderGuidanceCorrectionPrompt)(promptText, deliveredGuidance)
+                : promptText;
+            const runPrompt = nextPrompt ?? briefPrompt;
             nextPrompt = null;
             await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), runPrompt, "utf8");
             adapterStarted = true;
@@ -780,7 +782,15 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 if (remediable && completionRemediationRetries < COMPLETION_REMEDIATION_RETRIES) {
                     completionRemediationRetries += 1;
                     log.warn(`completion for ${leaseId} needs more work; restarting agent turn ${completionRemediationRetries}/${COMPLETION_REMEDIATION_RETRIES} in the same worktree.`);
-                    nextPrompt = redactedRejection;
+                    // A new turn is a fresh agent invocation: the rejection alone would
+                    // reach an agent that has never seen the task.
+                    nextPrompt = (0, prompt_cjs_1.renderCompletionRemediationPrompt)({
+                        originalPrompt: briefPrompt,
+                        rejection: redactedRejection,
+                        previousReport: redactedReport,
+                        attempt: completionRemediationRetries,
+                        maxAttempts: COMPLETION_REMEDIATION_RETRIES,
+                    });
                     continue;
                 }
                 if (remediable) {

package/dist/update-coordinator.cjs

@@ -53,11 +53,12 @@ class RuntimeUpdateCoordinator {
         void this.applyRestart(directive);
     }
     async applyRestart(directive) {
-        const { heartbeat, claimLoop, capacity } = this.options;
+        const { heartbeat, claimLoop, conversationLoop, capacity } = this.options;
         try {
             heartbeat.setUpdateState("draining");
             log.info(`remote restart ${directive.command_id} received; draining active sessions`);
             await claimLoop.drain();
+            await conversationLoop?.drain();
             await capacity.waitForIdle();
             log.info(`remote restart ${directive.command_id} ready; handing off to supervisor`);
             (this.options.requestRestart ?? ((code) => process.exit(code)))(supervisor_cjs_1.REMOTE_RESTART_EXIT_CODE);
@@ -67,6 +68,7 @@ class RuntimeUpdateCoordinator {
             log.error(`remote restart failed: ${message}`);
             heartbeat.setUpdateState("failed", message.slice(0, 500));
             claimLoop.start();
+            conversationLoop?.start();
             this.restartInProgress = null;
         }
     }
@@ -74,7 +76,7 @@ class RuntimeUpdateCoordinator {
         return (this.options.now ?? Date.now)();
     }
     async apply(directive) {
-        const { config, heartbeat, claimLoop, capacity } = this.options;
+        const { config, heartbeat, claimLoop, conversationLoop, capacity } = this.options;
         try {
             heartbeat.setUpdateState("staging");
             log.info(`staging runtime ${directive.target_version}`);
@@ -82,6 +84,7 @@ class RuntimeUpdateCoordinator {
             heartbeat.setUpdateState("draining");
             log.info("runtime update staged; draining active sessions before restart");
             await claimLoop.drain();
+            await conversationLoop?.drain();
             await capacity.waitForIdle();
             await (0, update_installer_cjs_1.writePendingUpdate)(config.configDir, staged, directive.rollout_id);
             log.info(`runtime ${directive.target_version} ready; handing off to supervisor`);
@@ -96,6 +99,7 @@ class RuntimeUpdateCoordinator {
             log.error(`runtime update failed: ${message} (retrying ${directive.target_version} in ${Math.round(delayMs / 1000)}s)`);
             heartbeat.setUpdateState("failed", message.slice(0, 500));
             claimLoop.start();
+            conversationLoop?.start();
             this.targetInProgress = null;
         }
     }

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.91",
+  "version": "0.1.93",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",