surfagent 1.1.1 → 1.2.0

package/AGENT.md

@@ -0,0 +1,212 @@
+## IMPORTANT: Never kill Chrome
+
+`surfagent` launches a **separate Chrome window** with its own profile. The user's personal Chrome stays untouched. NEVER run `pkill Chrome`, `killall Chrome`, or any command that kills Chrome processes. If you need to restart the debug session, use `surfagent start` — it will launch a new one without affecting anything.
+
+---
+
+## Critical Rule: Always Close Unused Tabs
+
+After completing any task, close tabs you no longer need:
+```bash
+curl -X POST localhost:3456/click -H 'Content-Type: application/json' -d '{"tab":"0","text":"close"}' 
+# Or via CLI:
+node dist/browser.js close all
+```
+
+---
+
+## Setup
+
+### Start everything (one command)
+
+```bash
+surfagent start
+```
+
+This will:
+1. Check if Chrome debug session is already running on port 9222
+2. If not, launch a **new Chrome window** with a separate profile (`/tmp/surfagent-chrome`)
+3. Copy cookies from the user's default Chrome profile (preserves logins)
+4. Start the API server on `http://localhost:3456`
+
+The user's personal Chrome browser is NOT affected. A second Chrome window will appear — this is the debug session that the API controls.
+
+### Other commands
+
+```bash
+surfagent start     # Chrome + API (recommended)
+surfagent chrome    # Launch Chrome debug session only
+surfagent api       # Start API only (Chrome must already be running)
+surfagent health    # Check if Chrome and API are running
+```
+
+---
+
+## API Endpoints (preferred for agents)
+
+The API is the primary interface. Always **recon first, then act**.
+
+See `API.md` for full documentation with examples.
+
+```bash
+# Recon a page — get full map of elements, forms, selectors
+curl -X POST localhost:3456/recon -H 'Content-Type: application/json' -d '{"url":"https://example.com","keepTab":true}'
+
+# Read page content — structured text, tables, notifications
+curl -X POST localhost:3456/read -H 'Content-Type: application/json' -d '{"tab":"0"}'
+
+# Fill form fields — real CDP keystrokes
+curl -X POST localhost:3456/fill -H 'Content-Type: application/json' -d '{"tab":"0","fields":[{"selector":"#email","value":"test@example.com"}],"submit":"enter"}'
+
+# Click an element
+curl -X POST localhost:3456/click -H 'Content-Type: application/json' -d '{"tab":"0","text":"Submit"}'
+
+# Scroll
+curl -X POST localhost:3456/scroll -H 'Content-Type: application/json' -d '{"tab":"0","direction":"down","amount":1000}'
+
+# Navigate (same tab)
+curl -X POST localhost:3456/navigate -H 'Content-Type: application/json' -d '{"tab":"0","url":"https://example.com"}'
+
+# Go back
+curl -X POST localhost:3456/navigate -H 'Content-Type: application/json' -d '{"tab":"0","back":true}'
+
+# Run JavaScript in a tab or iframe
+curl -X POST localhost:3456/eval -H 'Content-Type: application/json' -d '{"tab":"0","expression":"document.title"}'
+
+# Bring tab to front
+curl -X POST localhost:3456/focus -H 'Content-Type: application/json' -d '{"tab":"0"}'
+
+# Raw key typing — no clear step, for Google Sheets / contenteditable / canvas
+curl -X POST localhost:3456/type -H 'Content-Type: application/json' -d '{"tab":"0","keys":"Hello","submit":"tab"}'
+
+# Captcha detection and interaction (experimental)
+curl -X POST localhost:3456/captcha -H 'Content-Type: application/json' -d '{"tab":"0","action":"detect"}'
+
+# Dispatch DOM events — for React SPAs where /click or /fill submit fails
+curl -X POST localhost:3456/dispatch -H 'Content-Type: application/json' -d '{"tab":"0","selector":"form[role=search]","event":"submit"}'
+
+# React debug — find event handlers on element and ancestors
+curl -X POST localhost:3456/dispatch -H 'Content-Type: application/json' -d '{"tab":"0","selector":"[role=option]","reactDebug":true}'
+
+# List tabs
+curl localhost:3456/tabs
+
+# Health check
+curl localhost:3456/health
+```
+
+### Google Sheets
+
+Google Sheets requires `/type` instead of `/fill` for cell input (because `/fill` does Ctrl+A which selects all cells). Use the name box to navigate, then `/type` to enter data:
+
+```bash
+# 1. Click the name box
+curl -X POST localhost:3456/click -H 'Content-Type: application/json' -d '{"tab":"sheets","selector":"#t-name-box"}'
+
+# 2. Navigate to a cell
+curl -X POST localhost:3456/fill -H 'Content-Type: application/json' -d '{"tab":"sheets","fields":[{"selector":"#t-name-box","value":"A1","clear":true}],"submit":"enter"}'
+
+# 3. Type into the cell (Tab moves right, Enter moves down)
+curl -X POST localhost:3456/type -H 'Content-Type: application/json' -d '{"tab":"sheets","keys":"=SUM(B2:B10)","submit":"tab"}'
+```
+
+Some Sheets buttons (Add Sheet +, toolbar) only respond to CDP mouse events, not DOM clicks. See `API.md` for the CDP mouse click pattern.
+
+**Warning:** Navigating away from unsaved Sheets triggers a native Chrome "Leave page?" dialog that blocks ALL CDP commands. See `API.md` > "Native Chrome Dialogs" for detection and dismissal via Swift AX API.
+
+### Tab Targeting
+
+All endpoints accept a `tab` field:
+- `"0"` — by index
+- `"github"` — partial URL/title match
+- `"cdpn.io"` — matches cross-origin iframes too
+
+---
+
+## CLI Commands
+
+The CLI is useful for quick manual operations and debugging.
+
+```bash
+node dist/browser.js list                    # List all open tabs
+node dist/browser.js content <tab>           # Get text content from a tab
+node dist/browser.js content <tab> -s "sel"  # Get text from specific CSS selector
+node dist/browser.js content-all             # Get content from all tabs
+node dist/browser.js elements <tab>          # List interactive elements
+node dist/browser.js click <tab> <text>      # Click element by text
+node dist/browser.js type <tab> <text>       # Type into input field
+node dist/browser.js open <url>              # Navigate to URL
+node dist/browser.js open <url> --new-tab    # Open in new tab
+node dist/browser.js screenshot <tab> -o f   # Take screenshot
+node dist/browser.js search <query>          # Search across all tabs
+node dist/browser.js html <tab>              # Get full HTML of page
+node dist/browser.js html <tab> -s "sel"     # Get HTML of specific element
+node dist/browser.js desc <tab>              # Get item description from JSON-LD/meta
+node dist/browser.js close <tab>             # Close a specific tab
+node dist/browser.js close all               # Close all tabs except first
+```
+
+---
+
+## Architecture
+
+```
+surfagent start
+    │
+    ├── Launches Chrome (separate window, separate profile)
+    │   └── --remote-debugging-port=9222
+    │       --user-data-dir=/tmp/surfagent-chrome
+    │
+    └── Starts API Server (:3456)
+        │
+        ├── src/api/recon.ts    (page reconnaissance)
+        ├── src/api/act.ts      (fill, click, scroll, read, navigate, eval, dispatch, captcha)
+        └── src/api/server.ts   (HTTP routing)
+             │
+             └── src/chrome/    (CDP connection layer)
+                  │
+                  ▼
+             Chrome (:9222)     ← separate window, user's Chrome untouched
+```
+
+---
+
+## Troubleshooting
+
+**"Cannot connect to Chrome"**
+- Run `surfagent start` — it handles everything
+- If Chrome is already running with debug mode, use `surfagent api` to just start the API
+
+**A second Chrome window appeared**
+- This is expected. `surfagent` runs its own Chrome with a separate profile. Your personal Chrome is not affected. Close the surfagent Chrome window when you're done.
+
+**Elements not found**
+- Always `/recon` first to see what's available
+- Try partial text matching with `/click`
+- Some elements are `role="option"` or `li` with `aria-label` — use selector from recon
+
+**Form fields not filling**
+- Use the API `/fill` endpoint — it uses real CDP keystrokes
+- For SPAs, use `"submit": "enter"` instead of clicking submit buttons
+
+**React SPA — click/submit doesn't trigger navigation**
+- This happens when React event handlers are on ancestor elements, not the element you're clicking
+- Use `"submit": "form"` in `/fill` — dispatches a native submit event on the nearest `<form>`, which React picks up
+- For non-form cases, use `/dispatch` with `"reactDebug": true` to find which ancestor has the handler, then `/dispatch` the right event on it
+- Example (X.com search): `/fill` with `submit:"form"` works where `submit:"enter"` fails because the autocomplete combobox swallows the Enter key
+
+**Links opening new tabs instead of navigating**
+- The API `/click` handles `target="_blank"` automatically
+- It overrides the target and navigates in the same tab
+
+**Cross-origin iframes**
+- Target them by their domain: `"tab": "cdpn.io"`
+- CDP connects to iframes as separate targets
+
+**Tab hidden behind other tabs**
+- Use `/focus` to bring it to front
+- `/navigate` does this automatically
+
+**Too many tabs open**
+- Use `close all` to close all but first tab
+- Always clean up after tasks

package/API.md

@@ -324,6 +324,7 @@ Fill form fields using real CDP keyboard input. This simulates actual keystrokes
 
 **Submit options:**
 - `"enter"` — press Enter key via CDP. Best option for single-page apps (SPAs).
+- `"form"` — dispatch a native `submit` event on the nearest `<form>` ancestor. **Use this for React SPAs** where Enter is intercepted by autocomplete/combobox widgets (e.g. X.com search, GitHub search).
 - `"auto"` — finds and clicks the nearest `button[type="submit"]` or `input[type="submit"]`.
 - `"#my-button"` — clicks a specific selector.
 
@@ -447,6 +448,55 @@ Check if the API can connect to Chrome.
 
 ---
 
+### POST /dispatch
+
+Dispatch any DOM event on any element. Built to solve React/Vue/Angular SPAs where `.click()` and CDP key events don't trigger framework event handlers.
+
+**Dispatch an event:**
+```json
+{ "tab": "0", "selector": "form[role=search]", "event": "submit" }
+```
+
+**With options:**
+```json
+{ "tab": "0", "selector": "#my-input", "event": "keydown", "eventInit": { "key": "Enter", "code": "Enter" } }
+```
+
+**React debug mode** — find all React event handlers on an element and its ancestors:
+```json
+{ "tab": "0", "selector": "[role=option]", "reactDebug": true }
+```
+
+**Parameters:**
+- `selector` (string, required) — CSS selector for target element
+- `event` (string, required unless reactDebug) — Event type: `"submit"`, `"click"`, `"input"`, `"change"`, `"keydown"`, `"pointerdown"`, etc.
+- `bubbles` (boolean) — Default: `true`. Set to `false` to prevent event bubbling.
+- `cancelable` (boolean) — Default: `true`
+- `detail` (any) — Payload for CustomEvent
+- `eventInit` (object) — Extra properties merged into the event constructor (e.g. `{key: "Enter"}` for KeyboardEvent)
+- `reactDebug` (boolean) — Instead of dispatching, return all React event handlers found walking up the DOM tree from the selector
+
+**Event response:**
+```json
+{ "success": true, "dispatched": "submit on FORM[role=search]", "_dispatchMs": 25 }
+```
+
+**React debug response:**
+```json
+{
+  "success": true,
+  "reactHandlers": [
+    { "tag": "FORM", "role": "search", "testid": null, "className": "...", "handlers": ["onSubmit"] },
+    { "tag": "DIV", "role": null, "testid": null, "className": "...", "handlers": ["onKeyDown"] },
+    { "tag": "DIV", "role": null, "testid": null, "className": "...", "handlers": ["onClick"] }
+  ]
+}
+```
+
+**When to use:** When `/click` or `/fill` submit doesn't trigger navigation or actions on React SPAs. Use `reactDebug` first to find which ancestor has the handler, then dispatch the right event on it.
+
+---
+
 ### POST /type
 
 Raw CDP key typing without clearing the field first. Use this for apps like **Google Sheets**, contenteditable elements, or any context where `/fill`'s Ctrl+A clear step causes side effects (e.g., selecting all cells instead of clearing a field).
@@ -613,9 +663,32 @@ const CDP = require('chrome-remote-interface');
 
 **Using the menu search:** Google Sheets has a menu search box (`input[aria-label="Menus"]` or `input[aria-label="Menus (Option+/)"]`). Use `/fill` to type a command (e.g., "Insert chart"), then `/click` on the matching result.
 
+**Clearing/removing wrong cell entries:** You cannot send Delete or Backspace keys to Google Sheets via CDP — they don't reach the grid. Instead, overwrite the cell with a space:
+
+```
+1. POST /click    { "tab": "sheets", "selector": "#t-name-box" }
+2. POST /fill     { "tab": "sheets", "fields": [{ "selector": "#t-name-box", "value": "F1", "clear": true }], "submit": "enter" }
+   → Navigate to the cell you want to clear
+3. POST /type     { "tab": "sheets", "keys": " ", "submit": "enter" }
+   → Overwrite with a space (effectively blanks the cell)
+```
+
+Repeat for each cell. Do NOT try `Delete`, `Backspace`, or `Cmd+Z` via CDP key events — they are silently ignored by the Sheets grid. The `/type` space-overwrite is the only reliable method.
+
+**Avoiding wrong entries in the first place:** When entering rows of data, always navigate to the first cell of each new row via the name box. Pressing Enter after the last column does NOT return to column A — it moves down within the same column. So after completing a row with Tab across columns:
+
+```
+# Wrong: pressing Enter after last column stays in that column
+# Right: use name box to jump to start of next row
+POST /click  { "tab": "sheets", "selector": "#t-name-box" }
+POST /fill   { "tab": "sheets", "fields": [{ "selector": "#t-name-box", "value": "A3", "clear": true }], "submit": "enter" }
+```
+
 **Key gotchas:**
 - Never use `/fill` directly on Google Sheets cells — it will wipe data via Ctrl+A
 - Always navigate to a cell via the name box first, then `/type`
+- Always use the name box to navigate to the start of each new row — Tab+Enter does not wrap back to column A
+- CDP keyboard events (Delete, Backspace, Cmd+Z) do not work on the Sheets grid — use space-overwrite instead
 - Some buttons (Add Sheet, menu items) only respond to CDP mouse events, not DOM clicks
 - Navigating away from unsaved Sheets triggers a native Chrome dialog — see the "Native Chrome Dialogs" section below
 
@@ -758,6 +831,70 @@ if let windows = windowsRef as? [AXUIElement] {
 
 ---
 
+## React SPAs — When `/click` and `/fill` Submit Don't Work
+
+React, Vue, and Angular use synthetic event systems with event delegation. Sometimes `.click()` and CDP key events don't trigger framework handlers — especially on comboboxes, autocomplete widgets, and custom dropdowns.
+
+**Symptoms:**
+- `/click` returns `success: true` but nothing happens
+- `/fill` with `submit: "enter"` fills the input but doesn't navigate
+- CDP `Input.dispatchMouseEvent` / `Input.dispatchKeyEvent` are silently ignored
+
+**Diagnosis — use `/dispatch` with `reactDebug`:**
+
+```bash
+# Find which elements have React handlers and what events they listen for
+curl -X POST localhost:3456/dispatch -d '{"tab":"0","selector":"[role=option]","reactDebug":true}'
+```
+
+This walks up the DOM from your target element, inspecting `__reactProps$*` on each ancestor, and returns every React event handler it finds. The response tells you exactly which element to target and which event to dispatch.
+
+**Fix — dispatch the right event on the right element:**
+
+```bash
+# Dispatch a submit event on a form (most common fix for search boxes)
+curl -X POST localhost:3456/dispatch -d '{"tab":"0","selector":"form[role=search]","event":"submit"}'
+
+# Or dispatch a click on the ancestor that has the onClick handler
+curl -X POST localhost:3456/dispatch -d '{"tab":"0","selector":"div[data-testid=wrapper]","event":"click"}'
+```
+
+**Or use `/fill` with `submit: "form"` (one-step shortcut):**
+
+```bash
+curl -X POST localhost:3456/fill -d '{"tab":"0","fields":[{"selector":"input[aria-label=\"Search query\"]","value":"my query"}],"submit":"form"}'
+```
+
+### X.com (Twitter) Search — worked example
+
+X.com's search combobox is a textbook case. The `role="option"` autocomplete suggestions have **zero event handlers** — the `onClick` lives on a distant ancestor DIV, `onKeyDown` on a separate container, and `onSubmit` on the form.
+
+**What works:**
+```
+POST /fill  { "tab": "0", "fields": [{ "selector": "input[aria-label=\"Search query\"]", "value": "query" }], "submit": "form" }
+```
+
+**Fallback — URL navigation:**
+```
+POST /navigate  { "tab": "0", "url": "https://x.com/search?q=your%20query&src=typed_query&f=top" }
+```
+Query parameters: `q` (query), `f` (`top`, `latest`, `people`, `photos`, `videos`).
+
+### General debugging workflow for any React SPA
+
+```
+1. Try /click or /fill with submit:"enter" first — it works on most sites
+2. If it fails:
+   POST /dispatch  { "tab": "0", "selector": "THE_STUCK_ELEMENT", "reactDebug": true }
+   → Read the handler tree to find which ancestor has which handler
+3. Dispatch the right event:
+   POST /dispatch  { "tab": "0", "selector": "THE_ANCESTOR", "event": "THE_EVENT" }
+4. If it's a form with an input, use submit:"form" shortcut:
+   POST /fill      { "tab": "0", "fields": [...], "submit": "form" }
+```
+
+---
+
 ## Important Notes
 
 - **Always recon before acting.** The selectors you need come from the recon response.

package/CLAUDE.md

@@ -82,6 +82,12 @@ curl -X POST localhost:3456/type -H 'Content-Type: application/json' -d '{"tab":
 # Captcha detection and interaction (experimental)
 curl -X POST localhost:3456/captcha -H 'Content-Type: application/json' -d '{"tab":"0","action":"detect"}'
 
+# Dispatch DOM events (React SPA workaround when /click or /fill submit fails)
+curl -X POST localhost:3456/dispatch -H 'Content-Type: application/json' -d '{"tab":"0","selector":"form[role=search]","event":"submit"}'
+
+# React debug — find event handlers on element ancestors
+curl -X POST localhost:3456/dispatch -H 'Content-Type: application/json' -d '{"tab":"0","selector":"[role=option]","reactDebug":true}'
+
 # List tabs
 curl localhost:3456/tabs
 

package/SURFAGENT_BUG_REPORT.md

@@ -0,0 +1,199 @@
+# Surfagent v1.1.0 — QA Bug Report
+
+**Date:** 2026-04-13
+**Tester:** Claude (automated QA)
+**Environment:** macOS Darwin 24.5.0, Chrome via CDP port 9222, API port 3500
+**Scope:** All API endpoints, CLI commands, error handling, edge cases (single-tab browsing)
+
+---
+
+## BUGS
+
+### BUG-1: `/click` response `clicked` field returns empty text [Medium]
+
+**Steps:** Click any element by text or selector on any page.
+**Expected:** `clicked` field should contain the element tag + visible text (e.g. `"A: Show HN"`).
+**Actual:** Returns empty text like `"A: "`, `"TEXTAREA: "` on many elements.
+
+**Root cause:** In `act.ts:219`, the click handler uses `el.innerText || el.value` but many elements (links with nested spans, textareas before user input) return empty `innerText`. The code also doesn't check `el.textContent` or `el.getAttribute('aria-label')` as fallbacks.
+
+**File:** `src/api/act.ts`, lines 218-219
+**Suggested fix:** Use the same `getText()` helper from `recon.ts` which checks `innerText`, `textContent`, `value`, `aria-label`, `title`, `alt`, and `name`.
+
+---
+
+### BUG-2: HTML entities in tab titles not decoded [Low]
+
+**Steps:** Open a page with `&` in the title (e.g. BBC). Call `GET /tabs` or CLI `list`.
+**Expected:** Title shows `&` (decoded).
+**Actual:** Title shows `&` (HTML entity).
+
+**Example:** `"BBC Home - Breaking News, World News, US News, Sports, Business, Innovation, Climate, Culture, Travel, Video & Audio"`
+
+**Root cause:** Chrome CDP returns HTML-encoded titles for some pages. `tabs.ts` passes them through without decoding.
+
+**File:** `src/chrome/tabs.ts`
+**Suggested fix:** Decode HTML entities in title after receiving from CDP (e.g. replace `&amp;` -> `&`, `&lt;` -> `<`, etc.).
+
+---
+
+### BUG-3: `reconUrl` title discrepancy vs `reconTab` [Low]
+
+**Steps:** Call `/recon` with `{"url":"https://httpbin.org/html", "keepTab":true}`. Then call `/recon` with `{"tab":"httpbin"}`.
+**Expected:** Both return the same title.
+**Actual:**
+- `reconUrl` returns `title: ""` (uses `document.title` which is empty)
+- `reconTab` returns `title: "httpbin.org/html"` (uses CDP target title, which Chrome auto-generates)
+
+**Root cause:** `reconUrl` reads title via `document.title` in JS. `reconTab` reads from CDP target metadata. When a page has no `<title>` tag, these diverge.
+
+**File:** `src/api/recon.ts`, lines 345-348 vs 434
+**Suggested fix:** In `reconUrl`, fall back to CDP target title when `document.title` is empty.
+
+---
+
+### BUG-4: Windows platform: `getChromePath()` uses Unix-only `test -f` [Medium]
+
+**Steps:** Run `surfagent start` on Windows.
+**Expected:** Chrome is found at standard Windows paths.
+**Actual:** `execSync('test -f "..."')` always fails on Windows (no `test` command in cmd.exe).
+
+**File:** `src/cli.ts`, lines 56-58
+**Suggested fix:** Use `fs.existsSync()` instead of `execSync('test -f ...')` for cross-platform compatibility.
+
+---
+
+### BUG-5: `-h` flag conflict in CLI — `--host` shadows `--help` [Medium]
+
+**Steps:** Run `node dist/browser.js -h`
+**Expected:** Shows help output.
+**Actual:** Error: `option '-h, --host <string>' argument missing`
+
+**Root cause:** Commander.js reserves `-h` for `--help` by default, but the program overrides it with `-h, --host`.
+
+**File:** `src/browser.ts`, line 27
+**Suggested fix:** Change host shorthand to `-H` or `--host` only (no shorthand). Keep `-h` for help.
+
+---
+
+### BUG-6: CLI version mismatch [Low]
+
+**Steps:** Run `node dist/browser.js --version`
+**Expected:** Shows `1.1.0` (matching package.json).
+**Actual:** Shows `1.0.0`.
+
+**File:** `src/browser.ts`, line 20 — `.version('1.0.0')` should be `1.1.0`
+**Suggested fix:** Read version from package.json or update hardcoded string.
+
+---
+
+### BUG-7: CLI program name is "browser" not "surfagent" [Low]
+
+**Steps:** Run `node dist/browser.js --help`
+**Expected:** `Usage: surfagent [options] [command]`
+**Actual:** `Usage: browser [options] [command]`
+
+**File:** `src/browser.ts`, line 19 — `.name('browser')` should be `.name('surfagent')`
+
+---
+
+### BUG-8: Help text references wrong repo URL [Low]
+
+**Steps:** Run `npx surfagent help`
+**Actual output:** `Full API docs: https://github.com/AllAboutAI-YT/webpilot#readme`
+**Expected:** Should reference `https://github.com/AllAboutAI-YT/surfagent#readme`
+
+**File:** `src/cli.ts`, line 133
+
+---
+
+### BUG-9: 404 error message lists only 3 of 12+ endpoints [Low]
+
+**Steps:** Hit any unknown endpoint (e.g. `GET /notreal`).
+**Actual:** `"Not found. Endpoints: POST /recon, GET /tabs, GET /health"`
+**Expected:** Should list all endpoints or link to docs.
+
+**File:** `src/api/server.ts`, line 211
+**Suggested fix:** List all endpoints or say `"Not found. See GET /health for status or docs at <url>"`
+
+---
+
+### BUG-10: Error messages echo back full user input (info leak / response bloat) [Low]
+
+**Steps:** Send a request with an extremely long tab pattern (e.g. 10,000 chars).
+**Actual:** Error response includes the full 10K string: `"Tab not found: AAAA...AAAA"`
+**Expected:** Error should truncate the echoed input.
+
+**File:** `src/api/act.ts`, line 25
+**Suggested fix:** Truncate `tabPattern` in error messages to ~100 chars.
+
+---
+
+## IMPROVEMENTS
+
+### IMP-1: No `/close` API endpoint [High]
+
+The CLI has a `close` command but there is no HTTP API equivalent. Agents using the API cannot close tabs without using the CLI. The CLAUDE.md docs suggest using `/click` with text "close" which is unreliable.
+
+**Suggested:** Add `POST /close` endpoint with `{"tab": "...", "all": false}`.
+
+---
+
+### IMP-2: `/fill` returns HTTP 200 even when all fields fail [Medium]
+
+When every field in a `/fill` request fails (e.g. all selectors not found), the response is HTTP 200 with `success: false` in each field. An agent checking only HTTP status would think the operation succeeded.
+
+**Suggested:** Return HTTP 207 (Multi-Status) or at minimum add a top-level `"allSucceeded": false` field.
+
+---
+
+### IMP-3: No timeout parameter on `/click` with `waitAfter` [Low]
+
+`/click` supports `waitAfter` but caps it at 10 seconds silently. There's no feedback that the wait was capped.
+
+**Suggested:** Return `"waitCapped": true` in response when `waitAfter` exceeds 10s.
+
+---
+
+### IMP-4: `/scroll` contentPreview unreliable on pages with fixed/sticky sidebars [Low]
+
+The scroll content preview skips `position: fixed/sticky` elements via `getComputedStyle` check on `el.closest('nav, aside, ...')`, but many sticky sidebars use `position: sticky` on a non-nav/aside element. Some content may be incorrectly filtered.
+
+---
+
+### IMP-5: `/dismiss` has limited cookie banner coverage [Low]
+
+Tested on BBC — no cookie banner dismissed despite BBC having a consent banner. The consent patterns list is good but may miss banners that use custom markup (not standard `<button>` elements, or that appear inside shadow DOM or iframes).
+
+---
+
+### IMP-6: No `POST /screenshot` API endpoint [Medium]
+
+The CLI has a `screenshot` command but there's no HTTP API equivalent. Screenshots are essential for agent visual verification.
+
+**Suggested:** Add `POST /screenshot` returning base64-encoded image or saving to a path.
+
+---
+
+### IMP-7: `startChrome()` copies cookies but not LocalStorage/IndexedDB [Low]
+
+Cookies are copied from the default Chrome profile, preserving some logins. But many modern apps use LocalStorage or IndexedDB for auth tokens (e.g. SPAs), which are not copied.
+
+---
+
+### IMP-8: No rate limiting or request queuing [Low]
+
+Concurrent CDP connections to the same tab could cause race conditions. While basic parallel reads worked in testing, concurrent writes (fill + click on same tab) could conflict.
+
+**Suggested:** Add optional request queuing per tab to serialize mutations.
+
+---
+
+## SUMMARY
+
+| Category | Count | Critical | Medium | Low |
+|----------|-------|----------|--------|-----|
+| Bugs     | 10    | 0        | 3      | 7   |
+| Improvements | 8 | 0        | 3      | 5   |
+
+**Overall assessment:** The core functionality (recon, navigate, fill, click, scroll, read, eval) works reliably. Error handling is solid across all endpoints with proper HTTP status codes and descriptive messages. The main issues are cosmetic/documentation bugs and missing API parity with the CLI. The most impactful improvements would be adding `/close` and `/screenshot` API endpoints.

package/dist/api/act.d.ts

@@ -99,3 +99,22 @@ export declare function typeKeys(tabPattern: string, keys: string, options: {
     typed: number;
     submitted?: boolean;
 }>;
+export interface DispatchRequest {
+    tab: string;
+    selector: string;
+    event: string;
+    bubbles?: boolean;
+    cancelable?: boolean;
+    detail?: any;
+    eventInit?: Record<string, any>;
+    reactDebug?: boolean;
+}
+export declare function dispatchEvent(request: DispatchRequest, options: {
+    port?: number;
+    host?: string;
+}): Promise<{
+    success: boolean;
+    dispatched?: string;
+    reactHandlers?: any[];
+    error?: string;
+}>;

package/dist/api/act.js

@@ -20,7 +20,7 @@ async function resolveTab(tabPattern, port, host) {
         }
     }
     if (!tab)
-        throw new Error(`Tab not found: ${tabPattern}`);
+        throw new Error(`Tab not found: ${tabPattern.length > 100 ? tabPattern.substring(0, 100) + '...' : tabPattern}`);
     return tab;
 }
 export async function fillFields(request, options) {
@@ -142,6 +142,29 @@ export async function fillFields(request, options) {
                 await cdp.Input.dispatchKeyEvent({ type: 'keyDown', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 });
                 await cdp.Input.dispatchKeyEvent({ type: 'keyUp', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 });
             }
+            else if (request.submit === 'form') {
+                // Dispatch native submit event on nearest form — works on React SPAs where Enter is intercepted
+                // (e.g. X.com search combobox, autocomplete widgets that swallow Enter key)
+                await client.Runtime.evaluate({
+                    expression: `
+            (function() {
+              // Find the last filled field and its nearest form ancestor
+              const lastSelector = ${JSON.stringify(request.fields.length > 0 ? request.fields[request.fields.length - 1].selector : null)};
+              let form;
+              if (lastSelector) {
+                const field = document.querySelector(lastSelector);
+                form = field ? field.closest('form') : null;
+              }
+              if (!form) {
+                form = document.querySelector('form');
+              }
+              if (!form) throw new Error('No form found');
+              form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+            })()
+          `,
+                    returnByValue: true
+                });
+            }
             else {
                 const submitSelector = request.submit === 'auto'
                     ? 'button[type="submit"], input[type="submit"]'
@@ -707,3 +730,80 @@ export async function typeKeys(tabPattern, keys, options) {
         throw error;
     }
 }
+export async function dispatchEvent(request, options) {
+    const port = options.port || 9222;
+    const host = options.host || 'localhost';
+    const tab = await resolveTab(request.tab, port, host);
+    const client = await connectToTab(tab.id, port, host);
+    try {
+        const result = await client.Runtime.evaluate({
+            expression: `
+        (function() {
+          const selector = ${JSON.stringify(request.selector)};
+          const eventType = ${JSON.stringify(request.event)};
+          const bubbles = ${request.bubbles !== false};
+          const cancelable = ${request.cancelable !== false};
+          const detail = ${JSON.stringify(request.detail || null)};
+          const extraInit = ${JSON.stringify(request.eventInit || {})};
+          const reactDebug = ${JSON.stringify(!!request.reactDebug)};
+
+          const el = document.querySelector(selector);
+          if (!el) return { success: false, error: 'Element not found: ' + selector };
+
+          // React debug: walk up tree and find all React event handlers
+          if (reactDebug) {
+            const handlers = [];
+            let current = el;
+            while (current && current !== document.documentElement) {
+              const propsKey = Object.keys(current).find(k => k.startsWith('__reactProps'));
+              if (propsKey) {
+                const props = current[propsKey] || {};
+                const reactHandlers = Object.keys(props).filter(k => typeof props[k] === 'function' && k.startsWith('on'));
+                if (reactHandlers.length > 0) {
+                  handlers.push({
+                    tag: current.tagName,
+                    role: current.getAttribute('role'),
+                    testid: current.getAttribute('data-testid'),
+                    className: (current.className || '').toString().substring(0, 60),
+                    handlers: reactHandlers
+                  });
+                }
+              }
+              current = current.parentElement;
+            }
+            return { success: true, reactHandlers: handlers };
+          }
+
+          // Build the event object
+          let event;
+          const init = { bubbles, cancelable, ...extraInit };
+
+          // Use specific event constructors for better compatibility
+          if (eventType === 'click' || eventType === 'mousedown' || eventType === 'mouseup' || eventType === 'dblclick') {
+            event = new MouseEvent(eventType, init);
+          } else if (eventType === 'keydown' || eventType === 'keyup' || eventType === 'keypress') {
+            event = new KeyboardEvent(eventType, init);
+          } else if (eventType === 'input' || eventType === 'change') {
+            event = new Event(eventType, init);
+          } else if (eventType === 'pointerdown' || eventType === 'pointerup' || eventType === 'pointermove') {
+            event = new PointerEvent(eventType, init);
+          } else if (detail !== null) {
+            event = new CustomEvent(eventType, { ...init, detail });
+          } else {
+            event = new Event(eventType, init);
+          }
+
+          el.dispatchEvent(event);
+          return { success: true, dispatched: eventType + ' on ' + el.tagName + (el.getAttribute('role') ? '[role=' + el.getAttribute('role') + ']' : '') };
+        })()
+      `,
+            returnByValue: true
+        });
+        await client.close();
+        return result.result.value;
+    }
+    catch (error) {
+        await client.close();
+        throw error;
+    }
+}

package/dist/api/recon.js

@@ -286,7 +286,17 @@ export async function reconUrl(url, options) {
             expression: 'document.title',
             returnByValue: true
         });
-        const title = titleResult.result.value || '';
+        let title = titleResult.result.value || '';
+        // Fall back to CDP target title when document.title is empty (e.g. pages with no <title> tag)
+        if (!title) {
+            try {
+                const targets = await CDP.List({ port, host });
+                const t = targets.find((t) => t.id === target.id);
+                if (t?.title)
+                    title = t.title;
+            }
+            catch { }
+        }
         // Get current URL (may have redirected)
         const urlResult = await client.Runtime.evaluate({
             expression: 'window.location.href',
@@ -307,7 +317,7 @@ export async function reconUrl(url, options) {
         }
         return {
             url: finalUrl,
-            title,
+            title: title || target.title || '',
             tabId: target.id,
             timestamp: new Date().toISOString(),
             meta: data.meta,

package/dist/api/server.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import http from 'node:http';
 import { reconUrl, reconTab } from './recon.js';
-import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract, dismissOverlays, typeKeys } from './act.js';
+import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract, dismissOverlays, typeKeys, dispatchEvent } from './act.js';
 import { getAllTabs } from '../chrome/tabs.js';
 const PORT = parseInt(process.env.API_PORT || '3456', 10);
 const CDP_PORT = parseInt(process.env.CDP_PORT || '9222', 10);
@@ -150,6 +150,16 @@ const server = http.createServer(async (req, res) => {
             const result = await typeKeys(body.tab, body.keys, { port: CDP_PORT, host: CDP_HOST, submit: body.submit });
             return json(res, 200, result);
         }
+        // POST /dispatch — dispatch DOM events on elements (React SPA workaround)
+        if (path === '/dispatch' && req.method === 'POST') {
+            const body = parseBody(await readBody(req));
+            if (!body.tab || !body.selector || (!body.event && !body.reactDebug)) {
+                return json(res, 400, { error: 'Provide "tab", "selector", and "event" (e.g. "submit", "click"). Add "reactDebug":true to inspect React handlers instead.' });
+            }
+            const start = Date.now();
+            const result = await dispatchEvent(body, { port: CDP_PORT, host: CDP_HOST });
+            return json(res, 200, { ...result, _dispatchMs: Date.now() - start });
+        }
         // POST /navigate — go to url, back, or forward in same tab
         if (path === '/navigate' && req.method === 'POST') {
             const body = parseBody(await readBody(req));
@@ -180,7 +190,7 @@ const server = http.createServer(async (req, res) => {
                 return json(res, 503, { status: 'error', cdpConnected: false });
             }
         }
-        json(res, 404, { error: 'Not found. Endpoints: POST /recon, GET /tabs, GET /health' });
+        json(res, 404, { error: 'Not found. Endpoints: POST /recon, /read, /fill, /click, /type, /scroll, /navigate, /eval, /dispatch, /dismiss, /captcha, /focus | GET /tabs, /health' });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -212,6 +222,7 @@ server.listen(PORT, () => {
     console.log(`  POST /recon   — { url: "..." } or { tab: "0" }`);
     console.log(`  POST /fill    — { tab, fields: [{ selector, value }], submit? }`);
     console.log(`  POST /click   — { tab, selector? , text? }`);
+    console.log(`  POST /dispatch— { tab, selector, event, reactDebug? }`);
     console.log(`  GET  /tabs    — list open Chrome tabs`);
     console.log(`  GET  /health  — check CDP connection`);
 });

package/dist/browser.js

@@ -14,13 +14,13 @@ import { descCommand } from './commands/desc.js';
 import { closeCommand } from './commands/close.js';
 const program = new Command();
 program
-    .name('browser')
-    .description('CLI tool to interact with Chrome tabs via CDP')
-    .version('1.0.0');
+    .name('surfagent')
+    .description('Browser automation CLI for AI agents — interact with Chrome tabs via CDP')
+    .version('1.1.1');
 // Global options
 program
     .option('-p, --port <number>', 'Chrome debugging port', '9222')
-    .option('-h, --host <string>', 'Chrome debugging host', 'localhost');
+    .option('-H, --host <string>', 'Chrome debugging host', 'localhost');
 // List command
 program
     .command('list')

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { execSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -49,8 +50,8 @@ function getChromePath() {
     };
     for (const p of paths[os] || []) {
         try {
-            execSync(`test -f "${p}"`, { stdio: 'ignore' });
-            return p;
+            if (fs.existsSync(p))
+                return p;
         }
         catch {
             continue;
@@ -120,7 +121,7 @@ Environment variables:
   CHROME_USER_DATA_DIR  Chrome profile directory (default: /tmp/surfagent-chrome)
 
 After starting, your AI agent can call http://localhost:3456
-Full API docs: https://github.com/AllAboutAI-YT/webpilot#readme
+Full API docs: https://github.com/AllAboutAI-YT/surfagent#readme
 `);
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surfagent",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Browser automation API for AI agents — structured page recon, form filling, clicking, and navigation via Chrome CDP",
   "keywords": [
     "ai-agent",

package/src/api/act.ts

@@ -22,7 +22,7 @@ async function resolveTab(tabPattern: string, port: number, host: string): Promi
     }
   }
 
-  if (!tab) throw new Error(`Tab not found: ${tabPattern}`);
+  if (!tab) throw new Error(`Tab not found: ${tabPattern.length > 100 ? tabPattern.substring(0, 100) + '...' : tabPattern}`);
   return tab;
 }
 
@@ -163,6 +163,28 @@ export async function fillFields(
         // Press Enter via CDP — works on SPAs like YouTube
         await cdp.Input.dispatchKeyEvent({ type: 'keyDown', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 });
         await cdp.Input.dispatchKeyEvent({ type: 'keyUp', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 });
+      } else if (request.submit === 'form') {
+        // Dispatch native submit event on nearest form — works on React SPAs where Enter is intercepted
+        // (e.g. X.com search combobox, autocomplete widgets that swallow Enter key)
+        await client.Runtime.evaluate({
+          expression: `
+            (function() {
+              // Find the last filled field and its nearest form ancestor
+              const lastSelector = ${JSON.stringify(request.fields.length > 0 ? request.fields[request.fields.length - 1].selector : null)};
+              let form;
+              if (lastSelector) {
+                const field = document.querySelector(lastSelector);
+                form = field ? field.closest('form') : null;
+              }
+              if (!form) {
+                form = document.querySelector('form');
+              }
+              if (!form) throw new Error('No form found');
+              form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+            })()
+          `,
+          returnByValue: true
+        });
       } else {
         const submitSelector = request.submit === 'auto'
           ? 'button[type="submit"], input[type="submit"]'
@@ -815,3 +837,99 @@ export async function typeKeys(
     throw error;
   }
 }
+
+// POST /dispatch — dispatch any DOM event on any element
+// Solves React SPAs where .click() and CDP key events don't trigger synthetic event handlers
+export interface DispatchRequest {
+  tab: string;
+  selector: string;          // CSS selector for target element
+  event: string;             // Event type: "submit", "click", "input", "change", "focus", "blur", etc.
+  bubbles?: boolean;         // Default: true
+  cancelable?: boolean;      // Default: true
+  detail?: any;              // For CustomEvent detail payload
+  eventInit?: Record<string, any>; // Extra event init properties (e.g. {key: "Enter"} for KeyboardEvent)
+  reactDebug?: boolean;      // If true, return React event handlers found on element and ancestors
+}
+
+export async function dispatchEvent(
+  request: DispatchRequest,
+  options: { port?: number; host?: string }
+): Promise<{ success: boolean; dispatched?: string; reactHandlers?: any[]; error?: string }> {
+  const port = options.port || 9222;
+  const host = options.host || 'localhost';
+
+  const tab = await resolveTab(request.tab, port, host);
+  const client = await connectToTab(tab.id, port, host);
+
+  try {
+    const result = await client.Runtime.evaluate({
+      expression: `
+        (function() {
+          const selector = ${JSON.stringify(request.selector)};
+          const eventType = ${JSON.stringify(request.event)};
+          const bubbles = ${request.bubbles !== false};
+          const cancelable = ${request.cancelable !== false};
+          const detail = ${JSON.stringify(request.detail || null)};
+          const extraInit = ${JSON.stringify(request.eventInit || {})};
+          const reactDebug = ${JSON.stringify(!!request.reactDebug)};
+
+          const el = document.querySelector(selector);
+          if (!el) return { success: false, error: 'Element not found: ' + selector };
+
+          // React debug: walk up tree and find all React event handlers
+          if (reactDebug) {
+            const handlers = [];
+            let current = el;
+            while (current && current !== document.documentElement) {
+              const propsKey = Object.keys(current).find(k => k.startsWith('__reactProps'));
+              if (propsKey) {
+                const props = current[propsKey] || {};
+                const reactHandlers = Object.keys(props).filter(k => typeof props[k] === 'function' && k.startsWith('on'));
+                if (reactHandlers.length > 0) {
+                  handlers.push({
+                    tag: current.tagName,
+                    role: current.getAttribute('role'),
+                    testid: current.getAttribute('data-testid'),
+                    className: (current.className || '').toString().substring(0, 60),
+                    handlers: reactHandlers
+                  });
+                }
+              }
+              current = current.parentElement;
+            }
+            return { success: true, reactHandlers: handlers };
+          }
+
+          // Build the event object
+          let event;
+          const init = { bubbles, cancelable, ...extraInit };
+
+          // Use specific event constructors for better compatibility
+          if (eventType === 'click' || eventType === 'mousedown' || eventType === 'mouseup' || eventType === 'dblclick') {
+            event = new MouseEvent(eventType, init);
+          } else if (eventType === 'keydown' || eventType === 'keyup' || eventType === 'keypress') {
+            event = new KeyboardEvent(eventType, init);
+          } else if (eventType === 'input' || eventType === 'change') {
+            event = new Event(eventType, init);
+          } else if (eventType === 'pointerdown' || eventType === 'pointerup' || eventType === 'pointermove') {
+            event = new PointerEvent(eventType, init);
+          } else if (detail !== null) {
+            event = new CustomEvent(eventType, { ...init, detail });
+          } else {
+            event = new Event(eventType, init);
+          }
+
+          el.dispatchEvent(event);
+          return { success: true, dispatched: eventType + ' on ' + el.tagName + (el.getAttribute('role') ? '[role=' + el.getAttribute('role') + ']' : '') };
+        })()
+      `,
+      returnByValue: true
+    });
+
+    await client.close();
+    return result.result.value as any;
+  } catch (error) {
+    await client.close();
+    throw error;
+  }
+}

package/src/api/recon.ts

@@ -343,7 +343,15 @@ export async function reconUrl(
       expression: 'document.title',
       returnByValue: true
     });
-    const title = titleResult.result.value as string || '';
+    let title = titleResult.result.value as string || '';
+    // Fall back to CDP target title when document.title is empty (e.g. pages with no <title> tag)
+    if (!title) {
+      try {
+        const targets = await CDP.List({ port, host });
+        const t = targets.find((t: any) => t.id === target.id);
+        if (t?.title) title = t.title;
+      } catch {}
+    }
 
     // Get current URL (may have redirected)
     const urlResult = await client.Runtime.evaluate({
@@ -370,7 +378,7 @@ export async function reconUrl(
 
     return {
       url: finalUrl,
-      title,
+      title: title || target.title || '',
       tabId: target.id,
       timestamp: new Date().toISOString(),
       meta: data.meta,

package/src/api/server.ts

@@ -2,7 +2,7 @@
 
 import http from 'node:http';
 import { reconUrl, reconTab } from './recon.js';
-import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract, dismissOverlays, typeKeys } from './act.js';
+import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract, dismissOverlays, typeKeys, dispatchEvent } from './act.js';
 import { getAllTabs } from '../chrome/tabs.js';
 
 const PORT = parseInt(process.env.API_PORT || '3456', 10);
@@ -176,6 +176,17 @@ const server = http.createServer(async (req, res) => {
       return json(res, 200, result);
     }
 
+    // POST /dispatch — dispatch DOM events on elements (React SPA workaround)
+    if (path === '/dispatch' && req.method === 'POST') {
+      const body = parseBody(await readBody(req));
+      if (!body.tab || !body.selector || (!body.event && !body.reactDebug)) {
+        return json(res, 400, { error: 'Provide "tab", "selector", and "event" (e.g. "submit", "click"). Add "reactDebug":true to inspect React handlers instead.' });
+      }
+      const start = Date.now();
+      const result = await dispatchEvent(body, { port: CDP_PORT, host: CDP_HOST });
+      return json(res, 200, { ...result, _dispatchMs: Date.now() - start });
+    }
+
     // POST /navigate — go to url, back, or forward in same tab
     if (path === '/navigate' && req.method === 'POST') {
       const body = parseBody(await readBody(req));
@@ -208,7 +219,7 @@ const server = http.createServer(async (req, res) => {
       }
     }
 
-    json(res, 404, { error: 'Not found. Endpoints: POST /recon, GET /tabs, GET /health' });
+    json(res, 404, { error: 'Not found. Endpoints: POST /recon, /read, /fill, /click, /type, /scroll, /navigate, /eval, /dispatch, /dismiss, /captcha, /focus | GET /tabs, /health' });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`[${new Date().toISOString()}] Error:`, message);
@@ -242,6 +253,7 @@ server.listen(PORT, () => {
   console.log(`  POST /recon   — { url: "..." } or { tab: "0" }`);
   console.log(`  POST /fill    — { tab, fields: [{ selector, value }], submit? }`);
   console.log(`  POST /click   — { tab, selector? , text? }`);
+  console.log(`  POST /dispatch— { tab, selector, event, reactDebug? }`);
   console.log(`  GET  /tabs    — list open Chrome tabs`);
   console.log(`  GET  /health  — check CDP connection`);
 });

package/src/browser.ts

@@ -17,14 +17,14 @@ import { closeCommand } from './commands/close.js';
 const program = new Command();
 
 program
-  .name('browser')
-  .description('CLI tool to interact with Chrome tabs via CDP')
-  .version('1.0.0');
+  .name('surfagent')
+  .description('Browser automation CLI for AI agents — interact with Chrome tabs via CDP')
+  .version('1.1.1');
 
 // Global options
 program
   .option('-p, --port <number>', 'Chrome debugging port', '9222')
-  .option('-h, --host <string>', 'Chrome debugging host', 'localhost');
+  .option('-H, --host <string>', 'Chrome debugging host', 'localhost');
 
 // List command
 program

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { execSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -54,8 +55,7 @@ function getChromePath(): string | null {
 
   for (const p of paths[os] || []) {
     try {
-      execSync(`test -f "${p}"`, { stdio: 'ignore' });
-      return p;
+      if (fs.existsSync(p)) return p;
     } catch {
       continue;
     }
@@ -130,7 +130,7 @@ Environment variables:
   CHROME_USER_DATA_DIR  Chrome profile directory (default: /tmp/surfagent-chrome)
 
 After starting, your AI agent can call http://localhost:3456
-Full API docs: https://github.com/AllAboutAI-YT/webpilot#readme
+Full API docs: https://github.com/AllAboutAI-YT/surfagent#readme
 `);
     return;
   }