pi-browser-harness 0.1.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.3.1 — 2026-05-02
+
+### Bug fixes
+
+- **`browser_list_tabs`** now shows full 32-character targetIds instead of truncated `BE9DD1DC…` prefixes. The `browser_list_tabs` → `browser_switch_tab` round-trip is repaired.
+- **`browser_switch_tab`** now supports prefix matching: pass a unique hex prefix (≥8 chars) and it resolves to the full targetId automatically. Ambiguous prefixes return a clear error listing all matching tabs.
+- **`browser_download`** auto-creates the download directory with `mkdir -p` if it doesn't exist. Previously it required a pre-existing writable directory.
+- **`ensureAlive()`** now probes the page session with `Runtime.evaluate("1")` after the transport health check. If the page target has crashed (e.g. localhost server died), it reattaches automatically instead of returning a cryptic `session_not_found` error on the next tool call.
+
+### Docs & metadata
+
+- **`browser_dispatch_key`** prompt guidelines now explicitly note it dispatches a synthetic DOM `KeyboardEvent` and does NOT type text. Point users to `browser_type` / `browser_press_key` for actual text input.
+- **`browser_navigate`** prompt guidelines now warn that Google and strict-anti-bot sites may reject CDP navigation. `browser_http_get` is the recommended workaround.
+- **`browser_get_network_log`** prompt snippet updated with explicit workaround (`browser_execute_js` with `PerformanceObserver`).
+- **`sharp`** added to `optionalDependencies` so `npm install` attempts it (enables `browser_screenshot` `maxDim` auto-resize).
+- **`SKILL.md`** script bindings section updated to document the actual daemon API: `daemon.evaluateJs()`, `daemon.pageInfo()`, `daemon.listTabs()`, `daemon.session().call()`. Example script updated to match.
+- **`SKILL.md`** troubleshooting section now covers `sharp`/`maxDim` and Google anti-bot navigation.
+
+## 0.3.0 — 2026-05-02
+
+### Internal rewrite
+
+- Per-domain module split: every tool now lives in its own `src/domains/<name>.ts` file. The 1140-line `daemon.ts` and 2277-line `tools.ts` are gone; the three largest files are now `src/cdp/transport.ts` (~220 LOC), `src/client.ts` (~220 LOC), and `src/domains/js.ts` (~200 LOC).
+- New transport/session/client split: `BrowserDaemon` class replaced with `createBrowserClient()` factory composing a `CdpTransport` (factory) and `CdpSession` (factory).
+- All tool handlers now return `Result<T, E>`; one `defineBrowserTool` helper converts to pi's `ToolDefinition` and supplies a uniform `details` shape: `{ ok: true, ... }` on success, `{ ok: false, kind, message, ... }` on error.
+- Strict TypeScript flags enabled (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noPropertyAccessFromIndexSignature`, `noUnusedLocals`, `noUnusedParameters`). Zero `any` in the codebase. All boundary `as` casts documented.
+
+### Bug fixes (predictability)
+
+- `browser_navigate` no longer silently creates a new tab when navigation fails; outcome is reported explicitly via `details.outcome.kind` (`"in_place"` | `"new_tab_created"`).
+- Page-info cache invalidation is now automatic: the session subscribes to CDP `Page.frameNavigated` / `Page.loadEventFired` events. The 5 manual `invalidatePageInfoCache()` calls are gone.
+- Dialog read no longer mutates state on `Page.javascriptDialogClosed` — the dialog persists in the buffer until `takeDialog()` is called, fixing a fast-dismiss race that dropped dialogs.
+- `browser_dispatch_key` now returns `details.matched` (count of elements the synthetic event was dispatched to). Zero matches is an `invalid_state` error instead of a false success.
+- `browser_http_get` timeout now covers the response body read (legacy aborted headers but `await response.text()` could hang indefinitely).
+- `sharp` failures are distinguished from "sharp not installed" — actual errors no longer masked by the install hint.
+- Screenshot paths use `randomUUID()` per-namespace — no more concurrent-write collisions from `Date.now() + global counter`.
+- Reconnect is lazy (via `ensureAlive`) — no background reconnect, no stacked Chrome consent popups.
+- WebSocket events are routed through an `AsyncIterable` bound to each connection — stale events from a previous connection can no longer leak across reconnects.
+- `browser_wait_for_load` returns a typed `timeout` error if the deadline elapses (legacy returned a soft string).
+
+### Security fixes
+
+- All JS evaluation source is built via `safeJs\`...\`` (always JSON.stringify-safe). The previous `replace(/'/g, "\\'")` selector escaping (broken for backslashes, newlines, unicode quotes, `</script>`) is gone.
+- `browser_run_script` now requires:
+  - script path inside `tmpdir()`, `cwd()`, or `BH_SCRIPT_DIR` (other paths rejected with `invalid_state`)
+  - a mandatory timeout (default 60s, max 600s, enforced via `Promise.race`)
+  - the AbortSignal is honored even if the script ignores its `signal` parameter
+  - source size ≤ 1 MB
+  - return shape validated structurally (each content item must be `{ type: "text", text: string }`)
+- `browser_download` validates the directory exists and is writable before calling CDP (Chrome was silently downloading to nowhere if the dir was bogus).
+- `browser_upload_file` verifies the file exists and is readable before any CDP call (prevents half-set state on the input).
+- `pdfPath()` / `screenshotPath()` validate the namespace against a strict regex so a hostile namespace cannot escape `tmpdir()`.
+
+### Parameter renames (saved scripts must be updated)
+
+- `browser_click`: `clicks` → `count`
+- `browser_dispatch_key`: `event` → `eventType`
+
+### Removed
+
+- The unused `tabHistory`, `screenshotDir`, and `debugClicks` fields on persisted state.
+- The dead `tool_result` hook in `index.ts` for tab-history tracking (`details.targetId` was never set by any tool).
+- `src/protocol.ts`, `src/renderers.ts`, `src/daemon.ts`, `src/tools.ts` (replaced by per-domain files and `client.ts`).
+
+### Known follow-ups
+
+- `browser_get_network_log` returns a structured deprecation note. The new transport routes events through an `AsyncIterable` consumed by the session manager; a synchronous `recentEvents()` API is deferred. Use `browser_execute_js` with `PerformanceObserver` or `performance.getEntries()` as a workaround.
+- `browser_run_script` script binding is named `daemon` for back-compat, but the underlying object is now a `BrowserClient`. Scripts using `daemon.cdp(method, params)` should switch to `daemon.session().call(method, params)`.
+- No tests added in this rewrite; that's a separate workstream.
+
+## [0.2.0] - 2026-05-02
+
+### Changed
+- **Performance: fast `ensureAlive()`** — skips CDP `Target.getTargets` health-check roundtrip on every tool call. Uses WebSocket state check + 30s TTL. 96% faster per-call setup.
+- **Performance: event-based `waitForLoad()`** — replaces `readyState` polling (300ms interval) with CDP `Page.loadEventFired` / `frameStoppedLoading` event draining (50ms interval). Detects already-loaded pages in ~1ms (99.5% faster).
+- **Performance: JPEG screenshot support** — `captureScreenshot()` accepts `format` (png/jpeg) and `quality` (1-100). JPEG q80 is 29-49% smaller than PNG for complex pages, speeding up CDP transfer and reducing LLM context cost.
+- **Performance: page info caching** — `getPageInfo()` caches results for 1 second, eliminating redundant `evaluateJS` CDP roundtrips on back-to-back calls.
+- **Performance: parallel domain enables** — `switchTab()` enables Page/DOM/Runtime/Network domains via `Promise.all` instead of sequential await.
+- **Tools: `browser_screenshot`** now accepts `format` (png/jpeg) and `quality` parameters.
+- **Tools: `browser_wait_for_load`** now uses `daemon.waitForLoad()` (event-based) instead of polling.
+
 ## [0.1.0] - 2026-05-02
 
 ### Added

package/README.md

@@ -1,6 +1,8 @@
 # pi-browser-harness
 
-Full browser control for pi agents. Navigate, click, type, screenshot, and extract data from your real Chrome — driven by your coding agent.
+![pi-browser-harness](https://raw.githubusercontent.com/amankumarsingh77/pi-browser-harness/main/assets/hero.png)
+
+Full browser control for pi agents. Navigate, click, type, screenshot, and extract data from your real Chrome — all driven through natural language via CDP.
 
 ---
 
@@ -10,173 +12,163 @@ Full browser control for pi agents. Navigate, click, type, screenshot, and extra
 # 1. Install
 pi install npm:pi-browser-harness
 
-# Or install from GitHub:
-# pi install git:github.com/amankumarsingh77/pi-browser-harness
-
 # 2. Enable Chrome remote debugging
 #    Open chrome://inspect/#remote-debugging in Chrome,
-#    tick the "Discover network targets" checkbox, click Allow.
-#    No Chrome relaunch needed.
+#    tick "Discover network targets", click Allow.
+#    Or launch Chrome with --remote-debugging-port=9222
 
-# 3. Connect pi to Chrome
+# 3. Connect
 /browser-setup
 ```
 
-That's it. Try:
-
-```
-> navigate to https://github.com and take a screenshot
-```
-
 ### Requirements
 
 - pi (latest)
 - Node.js ≥ 22
-- Chrome / Chromium / Edge (any recent version)
-
-> If `chrome://inspect/#remote-debugging` isn't available, you can launch Chrome with `--remote-debugging-port=9222` instead. The harness will find it either way.
+- Chrome / Chromium / Edge
 
 ---
 
-## What you can do
+## Tools
 
-### Navigation & tabs
-
-| Tool | What it does |
-|------|--------------|
-| `browser_navigate` | Go to a URL (reuses the attached tab) |
+| Tool | Purpose |
+|------|---------|
+| `browser_screenshot` | Capture a PNG screenshot of the current page |
+| `browser_click` | Click at viewport coordinates |
+| `browser_type` | Type text into the focused element |
+| `browser_press_key` | Press a key (Enter, Tab, Escape, arrows, etc.) with optional modifiers |
+| `browser_scroll` | Scroll the page by delta pixels |
+| `browser_navigate` | Navigate to a URL |
 | `browser_new_tab` | Open a new tab, optionally navigate |
-| `browser_open_urls` | Open many URLs in parallel tabs |
-| `browser_go_back` / `browser_go_forward` | History navigation |
-| `browser_reload` | Reload the current page |
-| `browser_list_tabs` / `browser_current_tab` | Discover tabs |
-| `browser_switch_tab` | Switch the active tab |
-| `browser_page_info` | URL, title, viewport, scroll, dialog state |
-
-### Interaction
-
-| Tool | What it does |
-|------|--------------|
-| `browser_click` | Click at viewport coordinates (works through iframes / shadow DOM) |
-| `browser_type` | Type into the focused element |
-| `browser_press_key` | Send a key with optional modifiers |
-| `browser_scroll` | Scroll by delta pixels |
-| `browser_handle_dialog` | Accept or dismiss `alert` / `confirm` / `prompt` |
-
-### Visual & data
-
-| Tool | What it does |
-|------|--------------|
-| `browser_screenshot` | Capture the current page as PNG |
-| `browser_execute_js` | Run JS in the page and return the result |
-| `browser_http_get` | Direct HTTP GET — bypasses the browser, much faster for APIs |
+| `browser_open_urls` | Open multiple URLs in parallel tabs |
+| `browser_go_back` / `browser_go_forward` / `browser_reload` | History navigation |
+| `browser_page_info` | Get URL, title, viewport, scroll position, or dialog state |
+| `browser_list_tabs` / `browser_current_tab` / `browser_switch_tab` | Tab discovery and switching |
+| `browser_execute_js` | Run JavaScript in the page and return the result |
+| `browser_http_get` | Direct HTTP GET outside the browser — much faster for APIs |
 | `browser_wait` / `browser_wait_for_load` | Sleep, or wait for `readyState === 'complete'` |
-
-### Extending the harness at runtime
-
-| Tool | What it does |
-|------|--------------|
-| `browser_run_script` | Execute a temporary script file with daemon access |
+| `browser_handle_dialog` | Accept or dismiss `alert` / `confirm` / `prompt` |
+| `browser_run_script` | Execute a temporary script with daemon and Node.js access |
 
 ---
 
-## Usage
+## Core Patterns
 
-The core pattern is **screenshot → act → screenshot → verify.** Don't assume an action worked — look.
+The golden rule: **screenshot → act → screenshot → verify.** Never assume — always look.
 
-### Navigate and screenshot
+### Navigation
 
 ```
-browser_navigate("https://github.com/browser-use/browser-harness")
+browser_new_tab({ url: "https://example.com" })
 browser_wait_for_load()
 browser_screenshot()
 ```
 
-### Fill a form
+### Form filling
 
 ```
-browser_screenshot()                  # see the form
-browser_click(400, 200)               # click the search input
-browser_type("pi browser harness")    # type
-browser_press_key("Enter")            # submit
+browser_screenshot()                   # see the form
+browser_click({ x: 400, y: 200 })      # click the search input
+browser_type({ text: "query" })        # type
+browser_press_key({ key: "Enter" })    # submit
 browser_wait_for_load()
-browser_screenshot()                  # verify
+browser_screenshot()                   # verify
 ```
 
-### Extract data
+### Data extraction
 
-```js
-// Fast: hit the API directly, no browser
-browser_http_get("https://api.github.com/repos/browser-use/browser-harness")
+```
+browser_execute_js({ expression: "document.querySelector('.price').innerText" })
 
-// DOM scraping for rendered content
-browser_execute_js("document.querySelector('.price').innerText")
+browser_http_get({ url: "https://api.github.com/repos/amankumarsingh77/pi-browser-harness" })
 
 // Structured arrays
-browser_execute_js(`
-  JSON.stringify(
-    Array.from(document.querySelectorAll('.result')).map(el => ({
-      title: el.querySelector('h3')?.textContent,
-      link:  el.querySelector('a')?.href,
-    }))
-  )
-`)
+browser_execute_js({ expression: `Array.from(document.querySelectorAll('.result')).map(el => ({
+  title: el.querySelector('h3')?.textContent,
+  link:  el.querySelector('a')?.href,
+}))` })
 ```
 
-### Open multiple results in parallel
+### Research workflow
 
 ```
-browser_navigate("https://google.com/search?q=chrome+devtools+protocol")
-browser_open_urls({ urls: [
-  "https://chromedevtools.github.io/devtools-protocol/",
-  "https://developer.chrome.com/docs/devtools",
-]})
+browser_navigate({ url: "https://google.com/search?q=..." })
+// read search results
+browser_open_urls({ urls: ["url1", "url2", "url3"] })
 browser_list_tabs()
 browser_switch_tab({ targetId: "..." })
+browser_screenshot()
+browser_execute_js({ expression: "document.querySelector('.content').innerText" })
 ```
 
-### SPAs
-
-`browser_wait_for_load` only checks `readyState`. For React/Vue/etc., poll for the actual element you want:
+### Scrolling
 
-```js
-browser_execute_js("!!document.querySelector('.loaded-content')")
+```
+browser_screenshot()
+browser_scroll({ deltaY: -500 })
+browser_screenshot()
 ```
 
 ### Keyboard modifiers
 
-`browser_press_key` takes a modifier bitfield: `Alt=1`, `Ctrl=2`, `Meta/Cmd=4`, `Shift=8`. Combine with `|`.
+| Key | Bit |
+|-----|-----|
+| Alt | 1 |
+| Ctrl | 2 |
+| Meta / Cmd | 4 |
+| Shift | 8 |
 
+Combine with bitwise OR:
 ```
-browser_press_key("c", { modifiers: 2 })   // Ctrl+C
-browser_press_key("v", { modifiers: 4 })   // Cmd+V
-browser_press_key("T", { modifiers: 10 })  // Ctrl+Shift+T
+browser_press_key({ key: "c", modifiers: 2 })    // Ctrl+C
+browser_press_key({ key: "v", modifiers: 4 })    // Cmd+V
+browser_press_key({ key: "T", modifiers: 10 })   // Ctrl+Shift+T
 ```
 
-### Writing a temporary script
+### SPAs (React, Vue, etc.)
 
-When the built-ins aren't enough, write a script to disk and run it with `browser_run_script`.
+`browser_wait_for_load` only checks `readyState`. Poll for elements after:
+
+```
+browser_execute_js({ expression: "!!document.querySelector('.loaded-content')" })
+```
+
+### Dialogs
+
+JS dialogs (`alert` / `confirm` / `prompt`) freeze the page. Check `browser_page_info` first — if it reports a dialog, handle it before anything else:
+
+```
+browser_handle_dialog({ action: "accept" })       // confirm
+browser_handle_dialog({ action: "dismiss" })       // cancel
+browser_handle_dialog({ action: "accept", promptText: "hello" })  // prompt
+```
+
+---
+
+## Temporary Scripts
+
+When built-in tools aren't enough, write a script to disk and run it:
 
 ```js
-// 1. Write the script to disk
-write("/tmp/scrape-results.js", `
-  const data = await daemon.evaluateJS(\`
-    JSON.stringify(
-      Array.from(document.querySelectorAll('${params.selector}'))
-        .map(el => el.textContent.trim())
-    )
-  \`);
-  return {
-    content: [{ type: "text", text: data }],
-    details: { items: JSON.parse(data) },
-  };
+// 1. Write the script
+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 title = await daemon.evaluateJS("document.title");
+    results.push({ url, title });
+  }
+  return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
 `)
 
 // 2. Execute it
-browser_run_script("/tmp/scrape-results.js", { selector: ".result" })
+browser_run_script({ path: "/tmp/scrape-pages.js", params: { urls: [...] } })
 ```
 
-Scripts receive `params`, `daemon`, `require`, `signal`, `onUpdate`, `ctx`, plus the standard JS globals. The script is on disk — auditable and re-runnable.
+**Script bindings:** `params`, `daemon`, `require`, `signal`, `onUpdate`, `ctx`, `console`, `fetch`, `JSON`, `Buffer`, `setTimeout`, `clearTimeout`.
+
+Scripts are written to disk — auditable and re-runnable.
 
 ---
 
@@ -190,20 +182,50 @@ Scripts receive `params`, `daemon`, `require`, `signal`, `onUpdate`, `ctx`, plus
 
 ---
 
+## What NOT to do
+
+- Don't launch your own browser — you're connected to the user's real Chrome
+- Don't type credentials — if you hit an auth wall, stop and ask
+- Don't assume a page action worked — screenshot to verify
+- Don't write pixel coordinates into documentation — describe selectors and text instead
+- Don't ignore dialogs — check `browser_page_info` first
+
+---
+
+## Architecture
+
+```
+pi agent → pi-browser-harness (TypeScript)
+               │ CDP WebSocket
+               ▼
+            Chrome
+```
+
+Temporary scripts run inside the harness process with full daemon and Node.js access.
+
+---
+
 ## Troubleshooting
 
 | Symptom | Fix |
 |---------|-----|
-| `DevToolsActivePort not found` | Open `chrome://inspect/#remote-debugging`, tick the checkbox, click Allow, then retry. |
-| Connection fails after Chrome restart | Run `/browser-reload-daemon`. |
-| Page seems loaded but content is missing | SPA — `browser_wait_for_load` isn't enough. Poll with `browser_execute_js` for the element you need. |
-| A JS dialog is blocking actions | `browser_page_info` will report the dialog. Use `browser_handle_dialog` to accept or dismiss. |
+| `DevToolsActivePort not found` | Open `chrome://inspect/#remote-debugging`, tick the checkbox, click Allow |
+| Connection fails after Chrome restart | Run `/browser-reload-daemon` |
+| Page seems loaded but content is missing | SPA — poll with `browser_execute_js` for the element you need |
+| A JS dialog is blocking actions | `browser_page_info` will report it — use `browser_handle_dialog` |
+| Daemon not starting | Run `/browser-setup` to re-run guided setup |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, conventions, and PR process.
 
 ---
 
 ## Security
 
-This extension drives your real Chrome. The agent can see open tabs, read page content, submit forms, and act inside authenticated sessions. `browser_run_script` evaluates JavaScript in the pi process with full `require` access — review any temporary scripts the agent writes to `/tmp/` before executing them.
+This extension drives your real Chrome. The agent can see open tabs, read page content, submit forms, and act inside authenticated sessions. `browser_run_script` evaluates JavaScript in the pi process with full `require` access — review any temporary scripts before executing them.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",
@@ -62,6 +62,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "optionalDependencies": {
+    "sharp": "^0.33.0"
+  },
   "dependencies": {
     "ws": "^8.20.0"
   }

package/skills/pi-browser-harness/SKILL.md

@@ -130,7 +130,18 @@ The script is written to disk, so it's auditable and re-runnable.
 
 **Script bindings:**
 - `params` — the arguments passed to browser_run_script
-- `daemon` — browser daemon (daemon.cdp(), daemon.evaluateJS(), daemon.getPageInfo(), etc.)
+- `daemon` — browser daemon with these methods:
+  - `daemon.evaluateJs(expression)` — run JS in the current page
+  - `daemon.pageInfo()` — get current page info or dialog
+  - `daemon.listTabs()` — returns `{ success, data: [{ targetId, url, title }] }`
+  - `daemon.switchTab(targetId)` — switch to a tab by full targetId
+  - `daemon.newTab(url?)` — open and switch to a new tab
+  - `daemon.current()` — returns `{ targetId, url?, title? }`
+  - `daemon.session(targetId)` — returns a session object for raw CDP:
+    - `session.call(method, params?)` — CDP command on the page target
+    - `session.callOnTarget(method, params, sessionId)` — CDP on a specific session
+    - `session.callBrowser(method, params?)` — CDP on the browser target
+    - `session.takeDialog()` — get/dismiss pending dialog
 - `require` — Node.js require() (use 'fs', 'path', 'crypto', etc.)
 - `signal` — AbortSignal for cancellation
 - `onUpdate` — progress callback: onUpdate({ content: [{ type: 'text', text: '...' }] })
@@ -140,9 +151,9 @@ The script is written to disk, so it's auditable and re-runnable.
 **Example — a script that extracts structured data:**
 ```javascript
 // /tmp/extract-products.js
-const info = await daemon.getPageInfo();
-if ("dialog" in info) throw new Error("Dialog is blocking: " + info.dialog.message);
-const data = await daemon.evaluateJS(`
+const info = await daemon.pageInfo();
+if (info && "dialog" in info) throw new Error("Dialog is blocking: " + info.dialog.message);
+const data = await daemon.evaluateJs(`
   JSON.stringify(Array.from(document.querySelectorAll('${params.rowSelector}')).map(el => ({
     title: el.querySelector('${params.titleSelector}')?.textContent?.trim(),
     price: el.querySelector('${params.priceSelector}')?.textContent?.trim(),
@@ -196,6 +207,8 @@ browser_execute_js("!!document.querySelector('.loaded-content')")
 - **Stale session**: Run `/browser-reload-daemon` to restart the daemon
 - **Dialog blocking**: Run browser_page_info to detect it, then browser_handle_dialog
 - **Status check**: Run `/browser-status` to see daemon health and current page
+- **Screenshot maxDim not working**: Install sharp (`npm install sharp`) for auto-resize support
+- **Google navigation fails**: Google's anti-bot detection may reject CDP navigation; use `browser_http_get` to fetch search results instead
 
 ## Architecture
 

package/src/cdp/discovery.ts

@@ -0,0 +1,95 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { connect as netConnect } from "node:net";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+
+const PORT_PROBE_DEADLINE_MS = 30_000;
+const PORT_PROBE_INTERVAL_MS = 1_000;
+
+const profileDirs = (): ReadonlyArray<string> => {
+  const home = homedir();
+  return [
+    join(home, "Library/Application Support/Google/Chrome"),
+    join(home, "Library/Application Support/Microsoft Edge"),
+    join(home, "Library/Application Support/Microsoft Edge Beta"),
+    join(home, "Library/Application Support/Microsoft Edge Dev"),
+    join(home, "Library/Application Support/Microsoft Edge Canary"),
+    join(home, ".config/google-chrome"),
+    join(home, ".config/chromium"),
+    join(home, ".config/chromium-browser"),
+    join(home, ".config/microsoft-edge"),
+    join(home, ".config/microsoft-edge-beta"),
+    join(home, ".config/microsoft-edge-dev"),
+    join(home, ".var/app/org.chromium.Chromium/config/chromium"),
+    join(home, ".var/app/com.google.Chrome/config/google-chrome"),
+    join(home, ".var/app/com.brave.Browser/config/BraveSoftware/Brave-Browser"),
+    join(home, ".var/app/com.microsoft.Edge/config/microsoft-edge"),
+    join(home, "AppData/Local/Google/Chrome/User Data"),
+    join(home, "AppData/Local/Chromium/User Data"),
+    join(home, "AppData/Local/Microsoft/Edge/User Data"),
+    join(home, "AppData/Local/Microsoft/Edge Beta/User Data"),
+    join(home, "AppData/Local/Microsoft/Edge Dev/User Data"),
+    join(home, "AppData/Local/Microsoft/Edge SxS/User Data"),
+  ];
+};
+
+const probePort = (port: number): Promise<Result<void, CdpError>> =>
+  new Promise((resolve) => {
+    const sock = netConnect({ host: "127.0.0.1", port });
+    let settled = false;
+    const finish = (r: Result<void, CdpError>): void => {
+      if (settled) return;
+      settled = true;
+      sock.setTimeout(0);
+      sock.destroy();
+      resolve(r);
+    };
+    sock.setTimeout(1000, () => finish(err(cdpError("discovery_failed", "probe timeout"))));
+    sock.once("error", (e) => finish(err(cdpError("discovery_failed", e.message))));
+    sock.once("connect", () => finish(ok(undefined)));
+  });
+
+const waitForPort = async (port: number): Promise<Result<void, CdpError>> => {
+  const end = Date.now() + PORT_PROBE_DEADLINE_MS;
+  let lastMessage = "unknown";
+  while (Date.now() < end) {
+    const probe = await probePort(port);
+    if (probe.success) return probe;
+    lastMessage = probe.error.message;
+    await new Promise((r) => setTimeout(r, PORT_PROBE_INTERVAL_MS));
+  }
+  return err(cdpError(
+    "discovery_failed",
+    `Chrome's remote-debugging page is open, but DevTools is not live yet on 127.0.0.1:${port} — if Chrome opened a profile picker, choose your normal profile first, then tick the checkbox and click Allow if shown (last error: ${lastMessage})`,
+  ));
+};
+
+export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
+  const dirs = profileDirs();
+  for (const base of dirs) {
+    const portFile = join(base, "DevToolsActivePort");
+    let raw: string;
+    try {
+      raw = await readFile(portFile, "utf8");
+    } catch (e) {
+      // Node fs errors carry .code; see ErrnoException
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || code === undefined) continue;
+      return err(cdpError("discovery_failed", `failed to read ${portFile}: ${e instanceof Error ? e.message : String(e)}`));
+    }
+    const lines = raw.trim().split("\n");
+    if (lines.length < 2) continue;
+    const port = lines[0]?.trim();
+    const path = lines[1]?.trim();
+    if (!port || !path) continue;
+    const ready = await waitForPort(Number(port));
+    if (!ready.success) return ready;
+    return ok(`ws://127.0.0.1:${port}${path}`);
+  }
+  return err(cdpError(
+    "discovery_failed",
+    `DevToolsActivePort not found in ${dirs.join(", ")} — open chrome://inspect/#remote-debugging in your browser, tick the checkbox, click Allow, then retry. Or set BU_CDP_WS to a remote browser endpoint.`,
+  ));
+};

package/src/cdp/errors.ts

@@ -0,0 +1,19 @@
+export type CdpErrorKind =
+  | "transport_closed"
+  | "timeout"
+  | "session_not_found"
+  | "remote_error"
+  | "discovery_failed"
+  | "invalid_response";
+
+export type CdpError = {
+  readonly kind: CdpErrorKind;
+  readonly message: string;
+  readonly method?: string;
+};
+
+export const cdpError = (
+  kind: CdpErrorKind,
+  message: string,
+  method?: string,
+): CdpError => ({ kind, message, ...(method !== undefined ? { method } : {}) });