Browser skill (#485)

* Add `BrowserTool`

* add some logging

* go with npm install -g

* remove dep changes since the switch to npm install -g

* tweak

* tweak

* tweak

* tweak

* tweak timeout

* tweak

* remove logs

* skill investigation doc

* wip

* wip

* tweak

* lock agent-browser version

* tweak

* logs

* logs

* more logs

* more debug stuff

* try this

* try this

* try this

* fix PATH

* try this

* tweak

* tweak

* tweak

* update wiki entries

* update wiki once again

* lint fix

---------

Co-authored-by: Colin McDonnell <colinmcd94@gmail.com>

mcp/server.ts

@@ -1,11 +1,13 @@
 // this must be imported first
 import "./arkConfig.ts";
 import { createServer } from "node:net";
+import { setTimeout as sleep } from "node:timers/promises";
 import { FastMCP, type Tool } from "fastmcp";
 import type { AgentUsage } from "../agents/index.ts";
 import { ghPullfrogMcpName } from "../external.ts";
 import type { Mode } from "../modes.ts";
 import type { PrepResult } from "../prep/index.ts";
+import { closeBrowserDaemon } from "../utils/browser.ts";
 import { log } from "../utils/cli.ts";
 import type { OctokitWithPlugins } from "../utils/github.ts";
 import type { ResolvedPayload } from "../utils/payload.ts";
@@ -51,6 +53,8 @@ export type BackgroundProcess = {
   pidPath: string;
 };
 
+export type BrowserDaemon = { binDir: string; error?: never } | { binDir?: never; error: string };
+
 export type StoredPushDest = {
   remoteName: string;
   remoteBranch: string;
@@ -70,6 +74,7 @@ export interface ToolState {
   checkoutSha?: string;
   selectedMode?: string;
   backgroundProcesses: Map<string, BackgroundProcess>;
+  browserDaemon?: BrowserDaemon | undefined;
   review?: {
     id: number;
     nodeId: string;
@@ -319,7 +324,7 @@ async function killBackgroundProcesses(toolState: ToolState): Promise<void> {
       // already dead
     }
   }
-  await new Promise((resolve) => setTimeout(resolve, 200));
+  await sleep(200);
   for (const proc of backgroundProcesses.values()) {
     try {
       process.kill(-proc.pid, "SIGKILL");
@@ -347,6 +352,7 @@ export async function startMcpHttpServer(
   return {
     url: startResult.url,
     [Symbol.asyncDispose]: async () => {
+      closeBrowserDaemon(ctx.toolState);
       await killBackgroundProcesses(ctx.toolState);
       await startResult.server.stop();
     },

mcp/shell.ts

@@ -4,7 +4,9 @@ import { randomUUID } from "node:crypto";
 import { closeSync, openSync, writeFileSync } from "node:fs";
 import { userInfo } from "node:os";
 import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 import { type } from "arktype";
+import { ensureBrowserDaemon } from "../utils/browser.ts";
 import { log } from "../utils/log.ts";
 import { resolveEnv } from "../utils/secrets.ts";
 import type { ToolContext } from "./server.ts";
@@ -115,7 +117,12 @@ function spawnShell(params: SpawnParams): ChildProcess {
     // sudo is only needed for unshare; the actual command should run as the normal user
     // to avoid ownership mismatches with files created by the Node.js parent process.
     const username = userInfo().username;
-    const escaped = params.command.replace(/'/g, "'\\''");
+    // su -p resets PATH on many Linux systems (ALWAYS_SET_PATH in /etc/login.defs).
+    // restore it from the SANDBOX_PATH env var that survives the su transition.
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: we need to restore the PATH variable
+    const pathRestore = 'export PATH="${SANDBOX_PATH:-$PATH}"; ';
+    const escaped = (pathRestore + params.command).replace(/'/g, "'\\''");
+    envArgs.push(`SANDBOX_PATH=${params.env.PATH ?? ""}`);
     return spawn(
       "sudo",
       [
@@ -195,6 +202,21 @@ Do NOT use this tool for git commands — use the dedicated git tools instead.`,
       const cwd = params.working_directory ?? process.cwd();
       const env = resolveEnv(ctx.payload.shell === "enabled" ? "inherit" : "restricted");
 
+      if (params.command.includes("agent-browser")) {
+        const daemonError = ensureBrowserDaemon(ctx.toolState);
+        if (daemonError) {
+          return {
+            output: `browser daemon unavailable: ${daemonError}`,
+            exit_code: 1,
+            timed_out: false,
+          };
+        }
+        const binDir = ctx.toolState.browserDaemon?.binDir;
+        if (binDir) {
+          env.PATH = `${binDir}:${env.PATH ?? ""}`;
+        }
+      }
+
       if (params.background) {
         const tempDir = getTempDir();
         const handle = `bg-${randomUUID().slice(0, 8)}`;
@@ -305,7 +327,7 @@ export function KillBackgroundTool(ctx: ToolContext) {
       } catch {
         // already dead
       }
-      await new Promise((resolve) => setTimeout(resolve, 200));
+      await sleep(200);
       try {
         process.kill(-proc.pid, "SIGKILL");
       } catch {