pi-browser-harness 0.8.3 → 0.9.0

package/src/domains/search/web-search.ts

@@ -0,0 +1,116 @@
+import { Type } from "typebox";
+import { type Result, err, ok } from "../../util/result";
+import { applyTruncation } from "../../util/truncate";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
+import {
+  closeIsolatedTab,
+  evalInIsolatedTab,
+  navigateIsolatedTab,
+  openIsolatedTab,
+  waitForIsolatedLoad,
+} from "../isolated-tab";
+import { renderExpandableText } from "../render";
+import { buildSerpExtractionExpr } from "./extract";
+import { classifySerp, parseGoogleSerp, type SearchResult, type SerpExtraction } from "./google-serp";
+
+const LOAD_TIMEOUT_MS = 15_000;
+
+const WebSearchArgs = Type.Object({
+  query: Type.String({ description: "The search query." }),
+  limit: Type.Optional(
+    Type.Integer({ default: 10, minimum: 1, maximum: 30, description: "Max results to return. Default: 10." }),
+  ),
+});
+
+const buildSerpUrl = (query: string, limit: number): string =>
+  `https://www.google.com/search?q=${encodeURIComponent(query)}&num=${limit}&hl=en`;
+
+const isSerpExtraction = (value: unknown): value is SerpExtraction => {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return Array.isArray(v["anchors"]) && typeof v["pageText"] === "string";
+};
+
+const formatResults = (query: string, results: ReadonlyArray<SearchResult>): string => {
+  const lines = results.map((r) => `${r.rank}. ${r.title}\n   ${r.url}\n   ${r.snippet}`);
+  return `${results.length} result(s) for "${query}":\n\n${lines.join("\n\n")}`;
+};
+
+export const webSearchTool = defineBrowserTool({
+  name: "browser_web_search",
+  label: "Browser Web Search",
+  description:
+    "Search the web and return ranked results (title, url, snippet, rank). Scrapes a Google results page in the real Chrome — no API key. Returns links only; use browser_read_page to read a result's content.",
+  promptSnippet: "Search the web for a query",
+  promptGuidelines: [
+    "Returns ranked {title, url, snippet, rank} — links only, no page content. Follow up with browser_read_page.",
+    "On a CAPTCHA / bot wall the call fails with kind:'invalid_state' and details.reason:'captcha' (plus serpUrl) — surface it to the user; do not retry in a tight loop.",
+    "On zero results it fails with details.reason:'no_results' — rephrase the query and try again.",
+    "Runs in its own isolated tab and never disturbs the user's current tab.",
+  ],
+  parameters: WebSearchArgs,
+  async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
+    const limit = args.limit ?? 10;
+    const serpUrl = buildSerpUrl(args.query, limit);
+
+    const opened = await openIsolatedTab(client);
+    if (!opened.success) return err(opened.error);
+    const tab = opened.data;
+
+    try {
+      const navigated = await navigateIsolatedTab(client, tab, serpUrl);
+      if (!navigated.success) return err(navigated.error);
+
+      const loaded = await waitForIsolatedLoad(client, tab, LOAD_TIMEOUT_MS, signal);
+      if (!loaded.success) return err(loaded.error);
+
+      const extracted = await evalInIsolatedTab(client, tab, buildSerpExtractionExpr());
+      if (!extracted.success) return err(extracted.error);
+
+      const parsedJson = typeof extracted.data === "string" ? safeParse(extracted.data) : extracted.data;
+      if (!isSerpExtraction(parsedJson)) {
+        return err({ kind: "internal", message: "SERP extraction returned an unexpected shape" });
+      }
+
+      const results = parseGoogleSerp(parsedJson.anchors, limit);
+      const verdict = classifySerp(parsedJson.pageText, results.length);
+      if (verdict !== "ok") {
+        return err({
+          kind: "invalid_state",
+          message: verdict === "captcha" ? "Google served a CAPTCHA / bot wall" : "no results found",
+          details: { reason: verdict, serpUrl },
+        });
+      }
+
+      const body = formatResults(args.query, results);
+      const truncated = await applyTruncation(body, "search");
+      return ok({
+        text: truncated.text,
+        details: {
+          results,
+          engine: "google",
+          query: args.query,
+          render: {
+            summary: `${results.length} result(s) · google · "${args.query}"`,
+            body,
+            ...(truncated.fullOutputPath !== undefined ? { fullOutputPath: truncated.fullOutputPath } : {}),
+          },
+          ...(truncated.fullOutputPath !== undefined ? { fullOutputPath: truncated.fullOutputPath } : {}),
+        },
+      });
+    } finally {
+      await closeIsolatedTab(client, tab);
+    }
+  },
+  renderResult(result, expanded, theme) {
+    return renderExpandableText("web_search", result, expanded, theme);
+  },
+});
+
+const safeParse = (text: string): unknown => {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+};

package/src/index.ts

@@ -14,6 +14,7 @@
  *   /browser-setup          — guided setup wizard
  *   /browser-status         — show client status and current page
  *   /browser-reload-daemon  — restart the browser client
+ *   /deep-research <q>      — research a question on the web, write a cited report
  *
  * Flags:
  *   --browser-namespace <name>   — override namespace (default: auto)
@@ -24,6 +25,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { type BrowserClient, createBrowserClient } from "./client";
 import { getBrowserSystemPrompt } from "./prompt";
 import { registerSetupCommand } from "./setup";
+import { registerDeepResearchCommand } from "./deep-research";
 import { type BrowserState, defaultState, persistState, restoreState } from "./state";
 import { registerAllTools } from "./registry";
 import { cleanupTempDirs } from "./util/truncate";
@@ -107,9 +109,10 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
     if (!client) {
       const transport = createDaemonTransport(state.namespace);
 
-      const initialOwnership: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string } = {};
+      const initialOwnership: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string; harnessWindowId?: number } = {};
       if (state.ownedTargetIds !== undefined) initialOwnership.ownedTargetIds = state.ownedTargetIds;
       if (state.harnessWindowTargetId !== undefined) initialOwnership.harnessWindowTargetId = state.harnessWindowTargetId;
+      if (state.harnessWindowId !== undefined) initialOwnership.harnessWindowId = state.harnessWindowId;
 
       client = createBrowserClient({
         namespace: state.namespace,
@@ -122,6 +125,9 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
             ...(snap.harnessWindowTargetId !== undefined
               ? { harnessWindowTargetId: snap.harnessWindowTargetId }
               : {}),
+            ...(snap.harnessWindowId !== undefined
+              ? { harnessWindowId: snap.harnessWindowId }
+              : {}),
           };
           // Ownership changes can fire from CDP events at any time,
           // including after session replacement when pi's ctx is stale.
@@ -141,27 +147,31 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
       toolsRegistered = true;
     }
     registerSetupCommand(pi, client);
-    ctx.ui.setStatus(
-      "browser",
-      client.status().alive ? "🟢 Browser connected" : "🔴 Browser — run /browser-setup",
-    );
+    registerDeepResearchCommand(pi);
   });
 
   pi.on("session_shutdown", async () => {
-    persistState(pi, state);
     if (client) {
       try {
         // Detach from the page target (removes the "Chrome is being controlled"
         // banner) but keep the transport alive for the next session.
         await client.detach();
+        // Close every tab this session opened so no stale harness tabs linger
+        // in the user's browser between sessions. This also clears the persisted
+        // ownership + window binding via onOwnershipChange, so the next session
+        // starts with a fresh dedicated window rather than reattaching to leftovers.
+        await client.closeOwnedTabs();
       } catch (e) {
-        console.warn("[pi-browser-harness] client.detach() failed during shutdown:", e);
+        console.warn("[pi-browser-harness] browser teardown failed during shutdown:", e);
       }
       // ponytail: keep the transport alive across sessions.
       // Do NOT call client.stop() or null out client — the daemon connection
       // persists and eliminates the per-session "Allow Remote Debugging" prompt.
       // Only Chrome restart or daemon death triggers a new prompt.
     }
+    // Persist last — closeOwnedTabs mutates `state` through onOwnershipChange,
+    // so this captures the cleared ownership set.
+    persistState(pi, state);
     await cleanupTempDirs();
   });
 

package/src/prompt.ts

@@ -2,150 +2,126 @@
  * System prompt guidance for browser usage.
  *
  * Injects a compact browser control reference into the pi system prompt.
- * Per-tool guidelines are injected via promptGuidelines on each tool registration.
- * This prompt provides only the cross-cutting patterns and tool reference table.
+ * This prompt carries only cross-cutting knowledge — the mental model, tool
+ * routing, workflows, and gotchas. Per-tool specifics (schemas, detailed usage)
+ * are injected separately via promptGuidelines on each tool registration, so this
+ * file intentionally does NOT restate full tool descriptions.
  */
 
 export function getBrowserSystemPrompt(): string {
   return `
 ## Browser Control
 
-You have full control of a real Chrome browser via \`browser_*\` tools.
-The browser connects to the user's running Chrome (not a headless instance).
-
-**These tools coexist with all other standard pi tools** — read, bash, edit,
-write, and any other built-in tools are still available. Use browser_* tools
-to interact with pages visually, and other tools alongside them.
-
-### Browser-Specific Tools
-
-| Tool | Purpose |
-|------|---------|
-| browser_snapshot | Accessibility-tree snapshot. Assigns every interactive element a stable **ref** (\`[eN]\`) plus \`@(x,y)\`. Refs are the primary handle for interaction tools — they survive re-renders, coordinates don't. |
-| browser_screenshot | Capture a PNG or JPEG screenshot of the current page (rendered inline in the TUI; the LLM reads the image via the saved file path) |
-| browser_click | Click an element by **ref** (preferred — re-resolves position, survives re-renders) or viewport x/y. Appends a compact diff of page changes. |
-| browser_type | Type text into the focused element (real keystrokes; requires a focused field) |
-| browser_fill | Fill an input/textarea by **ref** (preferred) or selector — updates React/Vue controlled components, verifies the value, appends a page-changes diff |
-| browser_select_option | Select an option in a native <select> by **ref** (preferred) or selector, choosing by value/label/index (fires change) |
-| browser_focus | Focus an element by **ref** (preferred) or selector (deterministic; use before browser_type) |
-| browser_press_key | Press a keyboard key (Enter, Tab, Escape, arrows, etc.) |
-| browser_scroll | Scroll the page at coordinates |
-| browser_navigate | Navigate to a URL (result details.outcome.kind is "in_place" or "new_tab_created") |
-| browser_new_tab | Open a new tab, optionally navigate |
-| browser_open_urls | Open multiple URLs in new tabs (parallel) |
-| browser_go_back / browser_go_forward / browser_reload | History navigation |
-| browser_page_info | Get page URL, title, viewport, scroll position, or dialog info |
-| browser_list_tabs | List all open browser tabs |
-| browser_current_tab | Get current tab info |
-| browser_switch_tab | Switch to a different tab by targetId |
-| browser_execute_js | Execute JavaScript and return the result |
-| browser_http_get | Direct HTTP GET (outside browser, for APIs) |
-| browser_console | Read JS errors / console output on the current tab (diagnostic — use when an action looks broken; pass sinceSeq from the previous nextCursor to see only new messages) |
-| browser_wait | Wait N seconds |
-| browser_wait_for | Wait until a selector/text appears (or a selector disappears) — use for SPA content before interacting |
-| browser_wait_for_load | Wait for document.readyState === 'complete' (returns a typed timeout error if the page doesn't reach readyState=complete in N seconds, default 15) |
-| browser_handle_dialog | Accept or dismiss a JS dialog |
-| browser_run_script | Execute a temporary script file with daemon access (write script to disk, then run) |
-
-### Temporary Scripts
-
-When the built-in tools aren't enough for a multi-step workflow, write a temporary
-script to disk and execute it with browser_run_script. The script runs in the
-harness process with direct access to the browser daemon and Node.js APIs.
+You drive a **real Chrome** (the user's running instance, not headless) through
+\`browser_*\` tools. These coexist with every standard pi tool — read, bash, edit,
+write — so mix them freely: \`browser_*\` for the page, everything else alongside.
 
-\`\`\`
-write("/tmp/scrape-pages.js", \`
-  const results = [];
-  for (const url of params.urls) {
-    await daemon.cdp("Page.navigate", { url });
-    await new Promise(r => setTimeout(r, 2000));
-    const data = await daemon.evaluateJS("document.title");
-    results.push({ url, title: data });
-  }
-  return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
-\`)
-browser_run_script("/tmp/scrape-pages.js", { urls: [...] })
-\`\`\`
+### The core handle: refs
 
-Script bindings: params, daemon, require, signal, onUpdate, ctx, console, fetch, JSON, Buffer, setTimeout, clearTimeout.
+Interaction is ref-first. Call \`browser_snapshot\` to get an accessibility tree
+where every interactive element has a stable ref (\`[eN]\`) and \`@(x,y)\`. **Target
+elements by ref, not by coordinates or guessed selectors** — refs are keyed to
+element identity, so they survive the re-renders that React/Vue forms trigger on
+every edit and save. Coordinates go stale; guessed selectors miss.
 
-### Parallel Execution
+- Prefer \`browser_fill\` for text — it fires input/change so controlled components
+  update, and returns the value for verification. Use \`browser_click\` + \`browser_type\`
+  only for keystroke-sensitive widgets (autocomplete, masked inputs).
+- Mutating calls append a compact **"Page changes"** diff — read it to confirm the
+  change landed (form closed, new \`*[eN]\` appeared).
+- \`"ref is stale"\` means the page changed: re-run \`browser_snapshot\` for fresh refs.
 
-Observation tools (browser_screenshot, browser_page_info, browser_execute_js, browser_list_tabs, browser_http_get, etc.) can run in parallel with each other and with mutation tools. The harness automatically serializes mutation tools (click, type, scroll, navigate, switch_tab, etc.) so they never race on shared state. When operations are independent, emit them in the same turn for better performance.
+### Choosing a tool
 
-**Examples of safe parallel calls:**
-\`\`\`
-browser_screenshot() + browser_page_info() + browser_execute_js("document.title")
-browser_http_get("https://api.example.com/data") + browser_click(x, y)
-\`\`\`
+| To… | Reach for |
+|-----|-----------|
+| See the page structure (for interaction) | \`browser_snapshot\` (refs) |
+| See the page visually | \`browser_screenshot\` |
+| Search the web | \`browser_web_search\` → ranked {title, url, snippet} |
+| Read an article's clean text | \`browser_read_page\` (reader mode; url or owned tab) |
+| Extract specific DOM values | \`browser_execute_js\` |
+| Hit a JSON/API endpoint | \`browser_http_get\` (raw GET, outside the browser) |
+| Click / fill / type / select / focus / press a key | \`browser_click\` · \`browser_fill\` · \`browser_type\` · \`browser_select_option\` · \`browser_focus\` · \`browser_press_key\` |
+| Upload a file · drag · resize viewport | \`browser_upload_file\` · \`browser_drag_and_drop\` · \`browser_viewport_resize\` |
+| Go to a URL / open many / manage tabs | \`browser_navigate\` · \`browser_new_tab\` · \`browser_open_urls\` · \`browser_list_tabs\` · \`browser_switch_tab\` · \`browser_go_back\`/\`go_forward\`/\`reload\` |
+| Wait for content / load / a fixed delay | \`browser_wait_for\` (selector/text) · \`browser_wait_for_load\` (readyState) · \`browser_wait\` |
+| Inspect page / handle a dialog | \`browser_page_info\` · \`browser_current_tab\` · \`browser_handle_dialog\` |
+| Diagnose a broken action | \`browser_console\` (JS errors) · \`browser_get_network_log\` |
+| Save output / config downloads | \`browser_print_to_pdf\` · \`browser_download\` |
+| Anything the tools can't express | \`browser_run_script\` (see Extending) |
 
-**Multi-agent note**: When multiple subagents use the browser, tab switching by one agent changes the active tab for all agents. Per-tab data (console buffers, network traces, dialogs, page info cache) is isolated — switching tabs does not destroy another agent's collected data. Call \`browser_current_tab\` before mutation tools to confirm you're on the expected tab. If \`browser_page_info\` returns a dialog, handle it with \`browser_handle_dialog\` promptly — dialogs block page interaction and are not queued across agents.
+Each tool carries its own detailed guidelines — this table is only for routing.
 
-### Common Patterns
+### Workflows
 
-**Navigation:**
+**Research (search → read):**
 \`\`\`
-browser_new_tab("https://example.com") → browser_wait_for_load() → browser_screenshot()
+browser_web_search("query")        // ranked links, no page content
+→ browser_read_page(url)           // clean article text for the top hits
+// fall back to browser_open_urls + browser_execute_js only when reader mode misses
 \`\`\`
 
-**Form filling (ref-first — this is the reliable path on React/SPA forms):**
+**Form filling (ref-first — the reliable path on SPA forms):**
 \`\`\`
-browser_wait_for({ selector: "#email" })                    // ensure SPA field is rendered
-browser_snapshot()                                          // each interactive element gets a [eN] ref
-→ browser_fill({ ref: "e7", value: "a@b.com" })            // target by ref, not a guessed selector
-→ browser_select_option({ ref: "e9", label: "India" })     // native <select> by ref
-→ browser_click({ ref: "e12" })                            // e.g. Save — re-resolves position even if the form reflowed
-// each mutating call appends a compact "Page changes" diff — read it to confirm
-// the change landed (e.g. a save closed the form, a new field appeared as *[eN]).
+browser_wait_for({ selector: "#email" })   // ensure the field is rendered
+browser_snapshot()                          // interactive elements get [eN] refs
+→ browser_fill({ ref: "e7", value: "a@b.com" })
+→ browser_select_option({ ref: "e9", label: "India" })
+→ browser_click({ ref: "e12" })             // re-resolves position even after reflow
+// read each "Page changes" diff to confirm the step landed
 \`\`\`
-**Why ref over selector/coordinates:** refs are keyed to the element's identity, so
-they survive the re-renders that React/Vue forms trigger on every edit and save —
-coordinates go stale and selectors you guess often don't match. If a call returns
-"ref is stale", the page changed: re-run browser_snapshot for fresh refs.
-
-Prefer browser_fill for text inputs/textareas — it fires input/change so controlled
-components update, and returns the field's value for verification. Use browser_click +
-browser_type only for keystroke-sensitive widgets (autocomplete, masked inputs);
-browser_type requires an already-focused field and errors if none is focused.
 
-**Data extraction:**
+**Navigate + verify:**
 \`\`\`
-browser_execute_js("document.querySelector('.price').innerText")
-// or for APIs:
-browser_http_get("https://api.example.com/data")
+browser_new_tab("https://example.com") → browser_wait_for_load() → browser_screenshot()
 \`\`\`
 
-**Scrolling:**
-\`\`\`
-browser_screenshot() → browser_scroll({ deltaY: 500 }) → browser_screenshot()
-\`\`\`
-Note: deltaY follows W3C wheel-event convention: positive=down, negative=up. Default deltaY=300 scrolls down.
+**Scroll:** \`browser_scroll({ deltaY: 500 })\` — W3C wheel convention: positive = down,
+negative = up (default 300, down).
 
-**Research Workflow (search + browser):**
+### Parallelism
+
+Observation tools (\`browser_screenshot\`, \`browser_page_info\`, \`browser_execute_js\`,
+\`browser_list_tabs\`, \`browser_http_get\`, \`browser_web_search\`, \`browser_read_page\`, …)
+run in parallel with each other and with mutations. The harness serializes mutations
+(click, type, scroll, navigate, switch_tab) so they never race. Emit independent calls
+in one turn:
 \`\`\`
-browser_navigate("https://google.com/search?q=...") → search engine in a tab
-browser_open_urls(urls: ["url1", "url2", ...]) → open result pages in parallel tabs
-browser_list_tabs() → see all open tabs with targetIds
-browser_switch_tab(targetId: "...") → switch to a tab
-browser_screenshot() → visually inspect the page
-browser_execute_js("document.querySelector('.main').innerText") → extract content
+browser_screenshot() + browser_page_info() + browser_execute_js("document.title")
 \`\`\`
 
-**Temporary Scripts (extending the harness):**
+**Multi-agent:** tab switching by one agent changes the active tab for all agents,
+but per-tab data (console, network, dialogs) stays isolated. Call \`browser_current_tab\`
+before a mutation to confirm you're on the expected tab. Handle any dialog reported by
+\`browser_page_info\` promptly — dialogs block interaction and aren't queued across agents.
+
+**Session boundary & tab hygiene:** you operate only inside this session's own Chrome
+window. \`browser_switch_tab\`/\`browser_close_tab\` refuse tabs this session didn't open,
+and \`browser_list_tabs\` defaults to owned tabs — never reach into the user's other tabs
+or windows. Close tabs when you're done with them: call \`browser_close_tab\` on any tab
+you opened (via \`browser_new_tab\`/\`browser_open_urls\`) once you've extracted what you
+need. Don't leave a pile of stale tabs behind — keep only what a later step still needs.
+(Leftover tabs are closed automatically when the session ends, but close them yourself
+as you go.)
+
+### Extending: temporary scripts
+
+When built-in tools can't express a multi-step workflow, write a script to a temp file
+and run it with \`browser_run_script\`. It executes in the harness process with direct
+daemon + Node access.
 \`\`\`
-write("/tmp/extract.js", "...script with daemon access...") → browser_run_script("/tmp/extract.js")
+write(<tempfile>.js, \`
+  const results = [];
+  for (const url of params.urls) {
+    await daemon.cdp("Page.navigate", { url });
+    await new Promise(r => setTimeout(r, 2000));
+    results.push({ url, title: await daemon.evaluateJS("document.title") });
+  }
+  return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+\`)
+browser_run_script(<tempfile>.js, { urls: [...] })
 \`\`\`
-
-### Additional Tools
-
-| Tool | Purpose |
-|------|---------|
-| browser_upload_file | Upload a file to a file input by **ref** (preferred) or selector (bypasses file picker) |
-| browser_dispatch_key | Dispatch a DOM KeyboardEvent on an element by **ref** (preferred) or selector (for React/Vue inputs); returns details.matched |
-| browser_download | Configure download directory and disable save-as prompts |
-| browser_viewport_resize | Resize the viewport for responsive testing |
-| browser_drag_and_drop | Perform drag-and-drop from one coordinate to another |
-| browser_print_to_pdf | Print the current page to a PDF file |
-| browser_get_network_log | Get buffered network request/response events |
+Script bindings: params, daemon, require, signal, onUpdate, ctx, console, fetch, JSON,
+Buffer, setTimeout, clearTimeout. Use a real temp path from the OS — don't hardcode \`/tmp\`.
 `;
 }

package/src/registry.ts

@@ -19,6 +19,8 @@ import { consoleTool } from "./domains/console";
 import { snapshotTool } from "./domains/snapshot";
 import { executeJsTool, runScriptTool } from "./domains/js";
 import { setupTool } from "./domains/setup";
+import { webSearchTool } from "./domains/search/web-search";
+import { readPageTool } from "./domains/readpage/read-page";
 
 // Mutation tools that modify page / browser state are marked `serialized: true`
 // so they run through a shared async mutex.  Observation / read-only tools are
@@ -61,6 +63,10 @@ const TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
   snapshotTool,
   executeJsTool,
   runScriptTool,
+  // Opens and owns an isolated tab to scrape a SERP — same class as openUrlsTool.
+  { ...webSearchTool, serialized: true },
+  // Pure isolated read (own sessionId, own tab) — safe concurrent, like executeJsTool.
+  readPageTool,
 ];
 
 export const registerAllTools = (pi: ExtensionAPI, client: BrowserClient): void => {

package/src/setup.ts

@@ -8,6 +8,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { execSync } from "node:child_process";
 import type { BrowserClient } from "./client";
 import { ensureDaemon } from "./daemon/spawn";
+import { DAEMON_SOCKET_PATH } from "./daemon/protocol";
 
 // ── Public: register the /browser-setup slash command ──────────────────────
 
@@ -41,7 +42,7 @@ export async function performSetup(client: BrowserClient): Promise<SetupResult>
   // Step 2: Start the browser daemon (spawns if not running, silently reuses if alive)
   const daemonReady = await ensureDaemon();
   if (!daemonReady) {
-    return { success: false, error: "Could not start the browser daemon. Check /tmp/pi-browser-daemon.sock." };
+    return { success: false, error: `Could not start the browser daemon. Check ${DAEMON_SOCKET_PATH}.` };
   }
 
   // Step 3: Connect to Chrome DevTools
@@ -59,9 +60,12 @@ export async function performSetup(client: BrowserClient): Promise<SetupResult>
       return {
         success: false,
         error:
-          "Chrome remote debugging needs to be enabled.\n\n" +
-          'Open chrome://inspect/#remote-debugging in your browser, tick the\n' +
+          "Browser remote debugging needs to be enabled.\n\n" +
+          "Open chrome://inspect/#remote-debugging (or brave://inspect,\n" +
+          "edge://inspect) in your browser, tick the\n" +
           '"Discover network targets" / Allow checkbox, then retry.\n\n' +
+          "If that doesn't expose DevTools, relaunch the browser with\n" +
+          "--remote-debugging-port=9222.\n\n" +
           "Or set BU_CDP_WS to a remote browser WebSocket URL.",
       };
     }
@@ -89,19 +93,31 @@ export async function performSetup(client: BrowserClient): Promise<SetupResult>
 function checkChromeRunning(): boolean {
   try {
     if (process.platform === "darwin") {
-      // ps -o comm= returns the full executable path on modern macOS.
-      // We check for "Google Chrome" anywhere in the path (case-insensitive),
-      // excluding helper/renderer subprocesses.
+      // ps -o comm= returns the full executable path on modern macOS, e.g.
+      // "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser". We check
+      // for a known Chromium-family name anywhere in the path (case-insensitive),
+      // excluding helper/renderer/gpu/crashpad/updater subprocesses that linger
+      // after the user quits the browser.
       const out = execSync("ps -A -o comm=", { timeout: 5000 }).toString().toLowerCase();
       const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
+      const browserNames = ["google chrome", "chromium", "microsoft edge", "brave browser"];
       return lines.some((l) => {
-        if (l.includes("helper") || l.includes("renderer") || l.includes("crashpad")) return false;
-        return l.includes("google chrome") || l.includes("chromium") || l.includes("microsoft edge");
+        if (
+          l.includes("helper") ||
+          l.includes("renderer") ||
+          l.includes("crashpad") ||
+          l.includes(" gpu") ||
+          l.includes("updater")
+        ) return false;
+        return browserNames.some((name) => l.includes(name));
       });
     } else if (process.platform === "linux") {
       const out = execSync("ps -A -o comm=,args=", { timeout: 5000 }).toString().toLowerCase();
       const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
-      const browserComms = ["chrome", "chromium", "chromium-browser", "msedge", "microsoft-edge", "google-chrome"];
+      const browserComms = [
+        "chrome", "chromium", "chromium-browser", "msedge", "microsoft-edge",
+        "google-chrome", "brave", "brave-browser",
+      ];
       return lines.some((line) => {
         const parts = line.split(/\s+/);
         const comm = parts[0] ?? "";
@@ -111,7 +127,7 @@ function checkChromeRunning(): boolean {
       });
     } else if (process.platform === "win32") {
       const out = execSync("tasklist", { timeout: 5000 }).toString().toLowerCase();
-      return ["chrome.exe", "msedge.exe"].some((n) => out.includes(n));
+      return ["chrome.exe", "msedge.exe", "brave.exe"].some((n) => out.includes(n));
     }
   } catch {
     // best-effort

package/src/state.ts

@@ -12,6 +12,7 @@ export type BrowserState = {
   readonly remoteBrowserId?: string;
   readonly ownedTargetIds?: ReadonlyArray<string>;
   readonly harnessWindowTargetId?: string;
+  readonly harnessWindowId?: number;
 };
 
 export const defaultState = (namespace = "default"): BrowserState => ({