@sagentlab/navarch-runtime 0.1.67 → 0.1.69

package/README.md

@@ -1,5 +1,48 @@
 # navarch-runtime
 
+## Managed visual evidence
+
+Host-mode build, verify, and QA leases requiring `browser-use` receive a
+`navarch_browser` MCP server with `capture_visual_evidence` in Codex, Claude,
+Gemini, OpenCode, and ACP sessions. It runs Chromium in the runtime process's
+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.
+
+Install the runtime's pinned browser once on the agent host (and after a
+Playwright version update):
+
+```sh
+npx @sagentlab/navarch-runtime browser-install
+```
+
+The source installer does this automatically. Linux hosts must also have
+Playwright's Chromium system libraries installed. Browser-startup failures
+are returned as capture errors; the runtime does not relax host permissions.
+Docker sessions continue to use their image's tooling, and an operator-supplied
+`NAVARCH_MCP_CONFIG_PATH` remains authoritative.
+
+Call the tool with `url`, `source_commit_sha`, and `evidence_role` (`before` or
+`after`). Optional `wait_for_selector` and `settle_ms` let a scene finish loading.
+The URL's deployed SHA must be checked by the agent: the supplied SHA is metadata,
+not platform attestation. Authenticated/interactive journeys still use their
+existing browser tools; this capture tool starts with no cookies.
+
+Each successful image is registered through lease-scoped `register_artifact`
+and uploaded to R2. The response contains durable URLs; the agent must inspect
+the images. Before session completion the runtime posts the uploaded evidence
+to the matching delivery PR using its scoped GitHub credential. A publication
+failure keeps verification blocked and preserves the uploaded artifact URLs.
+The capture endpoint binds only to loopback, requires a per-lease bearer, and
+is revoked when the lease ends. Captures are serialized and limited to ten
+attempts per lease. No app-repository capture script or GitHub browser upload
+is required.
+
+Run the real Chromium smoke test with
+`NAVARCH_TEST_REAL_BROWSER=1 npm test -- tests/browser-evidence.test.cts` from
+`runtime/`. It renders desktop/mobile PNGs through the same HTTP MCP tool while
+substituting the artifact upload destination.
+
 The machine-side half of Navarch (WP-07): registers this machine with the
 control plane, then loops claim → sandbox → agent CLI → report until you stop
 it. Plain Node/TypeScript, no Next.js coupling, and no shared app-code coupling

package/dist/api.cjs

@@ -142,8 +142,8 @@ class NavarchApiClient {
         return result;
     }
     /** Best-effort, lease-scoped activity signal for connected machines. */
-    async reportActivity(leaseId, phase) {
-        await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/activity`, { phase }, { allowEmpty: true });
+    async reportActivity(leaseId, phase, detail) {
+        await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/activity`, { phase, ...(detail ? { detail } : {}) }, { allowEmpty: true });
     }
     /** schema-design.md §7 — `POST /api/dispatch/:leaseId/complete {status, report, evidence_urls, cost}`. */
     async completeLease(leaseId, req) {

package/dist/browser-evidence.cjs

@@ -0,0 +1,240 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureSchema = void 0;
+exports.installEvidenceBrowser = installEvidenceBrowser;
+exports.startBrowserEvidence = startBrowserEvidence;
+const node_http_1 = require("node:http");
+const node_crypto_1 = require("node:crypto");
+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 node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const node_path_1 = __importDefault(require("node:path"));
+async function installEvidenceBrowser() {
+    const cli = node_path_1.default.join(node_path_1.default.dirname(require.resolve("playwright/package.json")), "cli.js");
+    await (0, node_util_1.promisify)(node_child_process_1.execFile)(process.execPath, [cli, "install", "chromium"], {
+        timeout: 180_000,
+    });
+}
+const captureShape = {
+    url: zod_1.z.string().url().refine((value) => {
+        const url = new URL(value);
+        return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
+    }, "Use an HTTP(S) preview or local app URL without embedded credentials."),
+    source_commit_sha: zod_1.z.string().regex(/^[0-9a-f]{40}$/).describe("Exact commit deployed at the URL; verify it before capturing. Agent-reported, not attested."),
+    evidence_role: zod_1.z.enum(["before", "after"]),
+    wait_for_selector: zod_1.z.string().min(1).max(500).optional(),
+    settle_ms: zod_1.z.number().int().min(0).max(5000).default(1000),
+};
+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. */
+async function startBrowserEvidence(options) {
+    const token = (0, node_crypto_1.randomBytes)(32).toString("hex");
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const evidence = [];
+    const published = new Set();
+    let busy = false;
+    let closed = false;
+    let browser;
+    let activeCapture;
+    let attempts = 0;
+    const assertActive = () => {
+        if (closed || !options.isActive())
+            throw new Error("Browser evidence lease is no longer active.");
+    };
+    async function capture(args) {
+        assertActive();
+        if (busy)
+            throw new Error("A capture is already running. Wait for it to finish.");
+        if (++attempts > 10)
+            throw new Error("This lease reached its 10 capture attempts.");
+        busy = true;
+        const captured = [];
+        const images = [];
+        try {
+            try {
+                browser = await (options.launch?.() ?? playwright_1.chromium.launch({
+                    headless: true,
+                    chromiumSandbox: true,
+                    timeout: 20_000,
+                    // Do not pass the supervisor's provider or machine credentials to Chrome.
+                    env: Object.fromEntries(["HOME", "PATH", "TMPDIR", "TEMP", "TMP", "SystemRoot"]
+                        .flatMap((key) => process.env[key] ? [[key, process.env[key]]] : [])),
+                }));
+            }
+            catch {
+                throw new Error("Runtime browser could not start. On the agent host run navarch-runtime browser-install. Check host browser permissions; do not change the task repository or CI to install capture tooling.");
+            }
+            for (const viewport of ["desktop", "mobile"]) {
+                assertActive();
+                const context = await browser.newContext({
+                    ...(viewport === "mobile" ? playwright_1.devices["iPhone 13"] : { viewport: { width: 1440, height: 900 } }),
+                    acceptDownloads: false,
+                    serviceWorkers: "block",
+                });
+                try {
+                    await context.route("**/*", (route) => {
+                        const scheme = new URL(route.request().url()).protocol;
+                        return ["http:", "https:"].includes(scheme) ? route.continue() : route.abort();
+                    });
+                    const page = await context.newPage();
+                    const response = await page.goto(args.url, { waitUntil: "load", timeout: 30_000 });
+                    if (!response?.ok())
+                        throw new Error(`Preview returned HTTP ${response?.status() ?? "unknown"}.`);
+                    if (args.wait_for_selector)
+                        await page.locator(args.wait_for_selector).first().waitFor({ timeout: 10_000 });
+                    await page.waitForTimeout(args.settle_ms);
+                    const bytes = await page.screenshot({ type: "png", timeout: 10_000 });
+                    if (bytes.length > 25 * 1024 * 1024)
+                        throw new Error("Screenshot exceeds 25 MiB.");
+                    assertActive();
+                    const fileName = `${args.evidence_role}-${viewport}-${(0, node_crypto_1.randomUUID)()}.png`;
+                    const registration = await fetchImpl(`${options.apiBase.replace(/\/+$/, "")}/api/mcp`, {
+                        method: "POST",
+                        signal: AbortSignal.timeout(30_000),
+                        headers: {
+                            authorization: `Bearer ${options.machineToken}`,
+                            "x-navarch-lease-id": options.leaseId,
+                            "content-type": "application/json",
+                            accept: "application/json, text/event-stream",
+                            "mcp-protocol-version": "2025-06-18",
+                        },
+                        body: JSON.stringify({ jsonrpc: "2.0", id: (0, node_crypto_1.randomUUID)(), method: "tools/call", params: {
+                                name: "register_artifact", arguments: {
+                                    file_name: fileName, mime_type: "image/png", size_bytes: bytes.length,
+                                    checksum_sha256: (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex"),
+                                    source_commit_sha: args.source_commit_sha, evidence_role: args.evidence_role,
+                                },
+                            } }),
+                    });
+                    if (!registration.ok)
+                        throw new Error(`Artifact registration returned HTTP ${registration.status}.`);
+                    const result = await registration.json();
+                    const destination = result.result?.structuredContent;
+                    if (result.error || result.result?.isError || !destination?.upload_url || !destination.public_url
+                        || new URL(destination.upload_url).protocol !== "https:" || new URL(destination.public_url).protocol !== "https:") {
+                        throw new Error("Artifact registration did not provide secure upload and public URLs.");
+                    }
+                    assertActive();
+                    const upload = await fetchImpl(destination.upload_url, {
+                        method: "PUT", headers: { "content-type": "image/png" },
+                        body: new Uint8Array(bytes), signal: AbortSignal.timeout(30_000),
+                    });
+                    if (!upload.ok)
+                        throw new Error(`Screenshot upload returned HTTP ${upload.status}.`);
+                    const item = { fileName, publicUrl: destination.public_url,
+                        sourceCommitSha: args.source_commit_sha, role: args.evidence_role, viewport };
+                    evidence.push(item);
+                    captured.push(item);
+                    images.push({ type: "image", data: bytes.toString("base64"), mimeType: "image/png" });
+                }
+                finally {
+                    await context.close();
+                }
+            }
+            return { captured, images };
+        }
+        finally {
+            try {
+                await browser?.close();
+            }
+            finally {
+                browser = undefined;
+                busy = false;
+            }
+        }
+    }
+    const http = (0, node_http_1.createServer)(async (req, res) => {
+        // Bound to loopback with an unguessable per-lease bearer. Browser-origin
+        // calls are rejected even if another page can reach the local port.
+        if (req.headers.origin || req.headers.authorization !== `Bearer ${token}`) {
+            res.writeHead(403).end();
+            return;
+        }
+        if (closed || !options.isActive()) {
+            res.writeHead(410).end();
+            return;
+        }
+        if (req.url !== "/mcp" || req.method !== "POST") {
+            res.writeHead(405).end();
+            return;
+        }
+        const server = new mcp_js_1.McpServer({ name: "navarch-browser", version: "1.0.0" });
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        server.registerTool("capture_visual_evidence", {
+            description: "Capture and upload desktop and mobile screenshots using Navarch's managed local browser. Works outside the coding-agent sandbox. Returns durable artifact URLs. Capture does not certify acceptance or that the URL serves the supplied commit. Evidence is automatically attached to the delivery PR at session completion.",
+            inputSchema: captureShape,
+        }, async (args) => {
+            try {
+                if (busy)
+                    throw new Error("A capture is already running. Wait for it to finish.");
+                const pending = capture(args);
+                activeCapture = pending;
+                const { captured, images } = await pending;
+                return { content: [{ type: "text", text: JSON.stringify(captured) }, ...images] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: "text", text: String(error) }] };
+            }
+        });
+        res.on("close", () => { void transport.close(); void server.close(); });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res);
+        }
+        catch {
+            if (!res.headersSent)
+                res.writeHead(500).end();
+        }
+    });
+    await new Promise((resolve, reject) => {
+        http.once("error", reject);
+        http.listen(0, "127.0.0.1", resolve);
+    });
+    const address = http.address();
+    if (!address || typeof address === "string")
+        throw new Error("Browser evidence listener unavailable.");
+    return {
+        token,
+        config: { type: "http", url: `http://127.0.0.1:${address.port}/mcp`, headers: { Authorization: `Bearer ${token}` } },
+        evidence,
+        async publishToPr(prUrl, repository, githubToken) {
+            const pending = evidence.filter((item) => !published.has(item.publicUrl));
+            if (!pending.length)
+                return;
+            assertActive();
+            const pr = new URL(prUrl);
+            const match = pr.pathname.match(/^\/([^/]+\/[^/]+)\/pull\/(\d+)$/);
+            if (pr.origin !== "https://github.com" || match?.[1]?.toLowerCase() !== repository.toLowerCase() || !githubToken) {
+                throw new Error("Cannot publish browser evidence without a scoped GitHub credential and matching delivery PR.");
+            }
+            const response = await fetchImpl(`https://api.github.com/repos/${repository}/issues/${match[2]}/comments`, {
+                method: "POST", signal: AbortSignal.timeout(30_000),
+                headers: { authorization: `Bearer ${githubToken}`, "content-type": "application/json", accept: "application/vnd.github+json" },
+                body: JSON.stringify({ body: ["## Navarch browser evidence", "", ...pending.flatMap((item) => [
+                            `### ${item.role} · ${item.viewport}`, `![${item.viewport}](${item.publicUrl})`,
+                            `Source commit (agent-reported): \`${item.sourceCommitSha}\``, "",
+                        ])].join("\n") }),
+            });
+            if (!response.ok)
+                throw new Error(`Evidence comment returned HTTP ${response.status}.`);
+            for (const item of pending)
+                published.add(item.publicUrl);
+        },
+        async close() {
+            closed = true;
+            const stopped = new Promise((resolve) => http.close(() => resolve()));
+            http.closeAllConnections();
+            await browser?.close().catch(() => undefined);
+            await activeCapture?.catch(() => undefined);
+            await stopped;
+        },
+    };
+}

package/dist/cli.cjs

@@ -18,6 +18,7 @@ const logger_cjs_1 = require("./logger.cjs");
 const update_coordinator_cjs_1 = require("./update-coordinator.cjs");
 const supervisor_cjs_1 = require("./supervisor.cjs");
 const worktree_janitor_cjs_1 = require("./worktree-janitor.cjs");
+const browser_evidence_cjs_1 = require("./browser-evidence.cjs");
 const log = (0, logger_cjs_1.createLogger)("cli");
 const PACKAGE_NAME = "@sagentlab/navarch-runtime";
 /** Accepted `--agent` ids as usage metavariables, generated from one source of truth. */
@@ -394,6 +395,7 @@ Usage:
   navarch-runtime start [--config-dir <path>] [--agent ${AGENT_TYPE_USAGE}] [--model <model>]
   navarch-runtime supervise [--config-dir <path>] [--agent ${AGENT_TYPE_USAGE}] [--model <model>]
   navarch-runtime doctor [--config-dir <path>] [--agent ${AGENT_TYPE_USAGE}]
+  navarch-runtime browser-install
   navarch-runtime code-graph --query <symbol-or-file> [--mode search|callers|callees|impact] [--commit HEAD] [--depth 1..5] [--repo <path>]
 
 Use a different --config-dir (or NAVARCH_CONFIG_DIR) for every agent instance.
@@ -424,6 +426,10 @@ async function main(argv = process.argv.slice(2)) {
             case "doctor":
                 await doctorCommand(flags);
                 break;
+            case "browser-install":
+                await (0, browser_evidence_cjs_1.installEvidenceBrowser)();
+                console.log("Navarch capture browser installed.");
+                break;
             case "help":
             case "--help":
             case "-h":

package/dist/session.cjs

@@ -26,6 +26,7 @@ const worktree_guard_cjs_1 = require("./worktree-guard.cjs");
 const adapter_watchdog_cjs_1 = require("./adapter-watchdog.cjs");
 const lease_heartbeat_cjs_1 = require("./lease-heartbeat.cjs");
 const adapter_capacity_cjs_1 = require("./adapter-capacity.cjs");
+const browser_evidence_cjs_1 = require("./browser-evidence.cjs");
 /** Filename the generated platform MCP config is written under inside the session metadata directory. */
 const MCP_CONFIG_FILENAME = "mcp-config.json";
 const GIT_CREDENTIAL_HELPER_FILENAME = "git-credential-navarch.cjs";
@@ -401,16 +402,22 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     let activityPending = Promise.resolve();
     let outputObservedAt = 0;
     let outputReportedAt = 0;
+    let outputUpdates = 0;
+    let agentTurnStartedAt = 0;
     let adapterRunning = false;
-    const reportActivity = (phase) => {
-        activityPending = activityPending.then(() => api.reportActivity(leaseId, phase)).catch((error) => {
+    const reportActivity = (phase, detail) => {
+        activityPending = activityPending.then(() => api.reportActivity(leaseId, phase, detail)).catch((error) => {
             log.warn(`activity update failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(String(error), registry.list())}`);
         });
     };
     const activityTimer = setInterval(() => {
         if (adapterRunning && outputObservedAt > outputReportedAt && Date.now() - outputReportedAt >= 60_000) {
             outputReportedAt = Date.now();
-            reportActivity("output");
+            reportActivity("output", {
+                outputUpdates,
+                elapsedSeconds: Math.floor((outputReportedAt - agentTurnStartedAt) / 1000),
+            });
+            outputUpdates = 0;
         }
     }, 15_000);
     const heartbeatGuard = new lease_heartbeat_cjs_1.LeaseHeartbeatGuard(claimed.expires_at, () => {
@@ -424,9 +431,24 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     if (deps.shutdownSignal?.aborted)
         abortForRuntimeShutdown();
     lifecycle.enteredMainSessionTry = true;
+    let browserEvidence;
     try {
         reportActivity("preparing");
         await gitWorktree.prepare();
+        if (!config.mcpConfigPath && config.sandboxMode === "host"
+            && ["build", "verify", "qa"].includes(task.task_type)
+            && task.required_capabilities?.includes("browser-use")
+            && ["codex", "claude-code", "gemini", "opencode", "acp"].includes(runtime)) {
+            browserEvidence = await (0, browser_evidence_cjs_1.startBrowserEvidence)({
+                apiBase: api.getBaseUrl(), machineToken: api.getToken() ?? "", leaseId,
+                isActive: () => !leaseLost && !sessionClosing && !deps.shutdownSignal?.aborted,
+            });
+            registry.register(browserEvidence.token);
+            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";
+        }
         if (gitWorktree.hostedCheckpointRestoreFailure) {
             log.warn(`hosted checkpoint for ${leaseId} could not be restored: ` +
                 `${(0, redact_cjs_1.redactText)(gitWorktree.hostedCheckpointRestoreFailure, registry.list())}; starting without it.`);
@@ -485,6 +507,9 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), runPrompt, "utf8");
             adapterStarted = true;
             adapterRunning = true;
+            agentTurnStartedAt = Date.now();
+            outputReportedAt = agentTurnStartedAt;
+            outputUpdates = 0;
             reportActivity("running");
             const remainingRuntimeMs = maxRuntimeMs > 0
                 ? maxRuntimeMs - (node_perf_hooks_1.performance.now() - agentBudgetStartedAt)
@@ -509,7 +534,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                     cwd: gitWorktree.worktreePath,
                     dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
                     signal: activeAbortController.signal,
-                    onActivity: () => { outputObservedAt = Date.now(); },
+                    onActivity: () => { outputObservedAt = Date.now(); outputUpdates += 1; },
                 }, task.idle_timeout_ms ?? config.sessionIdleTimeoutMs ?? 45 * 60_000, runtime === "opencode" ? config.opencodeStartupTimeoutMs : 0);
             activeAbortController = null;
             adapterRunning = false;
@@ -586,6 +611,19 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 log.warn(`head-branch PR lookup failed for ${leaseId}: ${String(err)}`);
             }
             // -- delivery gate -----------------------------------------------------
+            if (browserEvidence && !leaseLost) {
+                mapping.evidenceUrls.push(...browserEvidence.evidence.map((item) => item.publicUrl));
+                if (pullRequestUrl) {
+                    try {
+                        await browserEvidence.publishToPr(pullRequestUrl, bundle.repository?.full_name ?? task.repo, githubToken);
+                    }
+                    catch (error) {
+                        mapping.leaseOutcome = "failed";
+                        mapping.exitStatus = "failed";
+                        mapping.reportSummary = `${task.task_type === "verify" && headSha ? `Verification verdict: BLOCKED ${headSha}\n\n` : ""}Browser evidence was uploaded but could not be attached to the PR: ${String(error)}\n\n${mapping.reportSummary}`;
+                    }
+                }
+            }
             // A clean exit is not delivery. Read what the worktree actually holds
             // and, when work was started but never shipped, spend a correction turn
             // in the same worktree before failing the lease. See delivery.cjs for
@@ -778,6 +816,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         clearInterval(activityTimer);
         heartbeatGuard.stop();
         activeAbortController?.abort();
+        await browserEvidence?.close().catch((error) => log.warn(`browser evidence cleanup failed: ${String(error)}`));
         // Drain only an already-started filesystem update, never a stalled network
         // request. A later heartbeat response sees sessionClosing and does nothing.
         await Promise.resolve(heartbeatWorkspaceUpdate).catch(() => undefined);

package/dist/worktree-guard.cjs

@@ -219,8 +219,6 @@ function codexWorktreeGuardArgs(options) {
         "-c",
         'approvals_reviewer="auto_review"',
         "-c",
-        `projects.${tomlString(node_path_1.default.resolve(options.worktreePath))}.trust_level="untrusted"`,
-        "-c",
         `default_permissions=${tomlString(CODEX_GUARD_PROFILE)}`,
         "-c",
         `permissions.${CODEX_GUARD_PROFILE}.filesystem=${tomlInlineTable(filesystem)}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.67",
+  "version": "0.1.69",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",
@@ -53,6 +53,9 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^1.4.0",
-    "typescript": "^5.7.2"
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "playwright": "1.63.0",
+    "typescript": "^5.7.2",
+    "zod": "^3.25.76"
   }
 }