agent-browser 0.3.7 → 0.4.1

package/README.md

@@ -1,13 +1,33 @@
 # agent-browser
 
-Headless browser automation CLI for AI agents.
+Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallback.
 
 ## Installation
 
+### npm (recommended)
+
+```bash
+npm install -g agent-browser
+agent-browser install  # Download Chromium
+```
+
+### From Source
+
 ```bash
+git clone https://github.com/vercel-labs/agent-browser
+cd agent-browser
 pnpm install
-npx playwright install chromium
 pnpm build
+agent-browser install
+```
+
+### Linux Dependencies
+
+On Linux, install system dependencies:
+
+```bash
+agent-browser install --with-deps
+# or manually: npx playwright install-deps chromium
 ```
 
 ## Quick Start
@@ -44,17 +64,14 @@ agent-browser fill <sel> <text>       # Clear and fill
 agent-browser press <key>             # Press key (Enter, Tab, Control+a)
 agent-browser keydown <key>           # Hold key down
 agent-browser keyup <key>             # Release key
-agent-browser insert <text>           # Insert text (no key events)
 agent-browser hover <sel>             # Hover element
 agent-browser select <sel> <val>      # Select dropdown option
-agent-browser multiselect <sel> <v1> <v2>  # Multi-select
 agent-browser check <sel>             # Check checkbox
 agent-browser uncheck <sel>           # Uncheck checkbox
 agent-browser scroll <dir> [px]       # Scroll (up/down/left/right)
-agent-browser scrollinto <sel>        # Scroll element into view
+agent-browser scrollintoview <sel>    # Scroll element into view
 agent-browser drag <src> <tgt>        # Drag and drop
 agent-browser upload <sel> <files>    # Upload files
-agent-browser download [path]         # Wait for download
 agent-browser screenshot [path]       # Take screenshot (--full for full page)
 agent-browser pdf <path>              # Save as PDF
 agent-browser snapshot                # Accessibility tree with refs (best for AI)
@@ -140,14 +157,14 @@ agent-browser set geo <lat> <lng>     # Set geolocation
 agent-browser set offline [on|off]    # Toggle offline mode
 agent-browser set headers <json>      # Extra HTTP headers
 agent-browser set credentials <u> <p> # HTTP basic auth
-agent-browser set media [dark|light|print]  # Emulate media
+agent-browser set media [dark|light]  # Emulate color scheme
 ```
 
 ### Cookies & Storage
 
 ```bash
 agent-browser cookies                 # Get all cookies
-agent-browser cookies set <json>      # Set cookies
+agent-browser cookies set <name> <val> # Set cookie
 agent-browser cookies clear           # Clear cookies
 
 agent-browser storage local           # Get all localStorage
@@ -167,14 +184,13 @@ agent-browser network route <url> --body <json>  # Mock response
 agent-browser network unroute [url]            # Remove routes
 agent-browser network requests                 # View tracked requests
 agent-browser network requests --filter api    # Filter requests
-agent-browser response <url>                   # Get response body (waits for matching request)
 ```
 
 ### Tabs & Windows
 
 ```bash
 agent-browser tab                     # List tabs
-agent-browser tab new                 # New tab
+agent-browser tab new [url]           # New tab (optionally with URL)
 agent-browser tab <n>                 # Switch to tab n
 agent-browser tab close [n]           # Close tab
 agent-browser window new              # New window
@@ -197,15 +213,15 @@ agent-browser dialog dismiss          # Dismiss
 ### Debug
 
 ```bash
-agent-browser trace start             # Start recording trace
-agent-browser trace stop <path>       # Stop and save trace
+agent-browser trace start [path]      # Start recording trace
+agent-browser trace stop [path]       # Stop and save trace
 agent-browser console                 # View console messages
 agent-browser console --clear         # Clear console
 agent-browser errors                  # View page errors
+agent-browser errors --clear          # Clear errors
 agent-browser highlight <sel>         # Highlight element
 agent-browser state save <path>       # Save auth state
 agent-browser state load <path>       # Load auth state
-agent-browser initscript <js>         # Run JS on every page load
 ```
 
 ### Navigation
@@ -216,25 +232,13 @@ agent-browser forward                 # Go forward
 agent-browser reload                  # Reload page
 ```
 
-### Sessions
+### Setup
 
 ```bash
-agent-browser session                 # Show current session
-agent-browser session list            # List active sessions
+agent-browser install                 # Download Chromium browser
+agent-browser install --with-deps     # Also install system deps (Linux)
 ```
 
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--session <name>` | Use isolated session (or `AGENT_BROWSER_SESSION` env) |
-| `--json` | JSON output (for agents) |
-| `--full, -f` | Full page screenshot |
-| `--name, -n` | Locator name filter |
-| `--exact` | Exact text match |
-| `--headed` | Show browser window (not headless) |
-| `--debug` | Debug output |
-
 ## Sessions
 
 Run multiple isolated browser instances:
@@ -244,13 +248,54 @@ Run multiple isolated browser instances:
 agent-browser --session agent1 open site-a.com
 agent-browser --session agent2 open site-b.com
 
-# Or via environment
+# Or via environment variable
 AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"
 
-# List all
+# List active sessions
 agent-browser session list
+
+# Show current session
+agent-browser session
+```
+
+Each session has its own:
+- Browser instance
+- Cookies and storage
+- Navigation history
+- Authentication state
+
+## Snapshot Options
+
+The `snapshot` command supports filtering to reduce output size:
+
+```bash
+agent-browser snapshot                    # Full accessibility tree
+agent-browser snapshot -i                 # Interactive elements only (buttons, inputs, links)
+agent-browser snapshot -c                 # Compact (remove empty structural elements)
+agent-browser snapshot -d 3               # Limit depth to 3 levels
+agent-browser snapshot -s "#main"         # Scope to CSS selector
+agent-browser snapshot -i -c -d 5         # Combine options
 ```
 
+| Option | Description |
+|--------|-------------|
+| `-i, --interactive` | Only show interactive elements (buttons, links, inputs) |
+| `-c, --compact` | Remove empty structural elements |
+| `-d, --depth <n>` | Limit tree depth |
+| `-s, --selector <sel>` | Scope to CSS selector |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--session <name>` | Use isolated session (or `AGENT_BROWSER_SESSION` env) |
+| `--json` | JSON output (for agents) |
+| `--full, -f` | Full page screenshot |
+| `--name, -n` | Locator name filter |
+| `--exact` | Exact text match |
+| `--headed` | Show browser window (not headless) |
+| `--debug` | Debug output |
+
 ## Selectors
 
 ### Refs (Recommended for AI)
@@ -317,7 +362,7 @@ agent-browser is visible @e2 --json
 ```bash
 # 1. Navigate and get snapshot
 agent-browser open example.com
-agent-browser snapshot --json    # AI parses tree and refs
+agent-browser snapshot -i --json   # AI parses tree and refs
 
 # 2. AI identifies target refs from snapshot
 # 3. Execute actions using refs
@@ -325,7 +370,81 @@ agent-browser click @e2
 agent-browser fill @e3 "input text"
 
 # 4. Get new snapshot if page changed
-agent-browser snapshot --json
+agent-browser snapshot -i --json
+```
+
+## Headed Mode
+
+Show the browser window for debugging:
+
+```bash
+agent-browser open example.com --headed
+```
+
+This opens a visible browser window instead of running headless.
+
+## Architecture
+
+agent-browser uses a client-daemon architecture:
+
+1. **Rust CLI** (fast native binary) - Parses commands, communicates with daemon
+2. **Node.js Daemon** - Manages Playwright browser instance
+3. **Fallback** - If native binary unavailable, uses Node.js directly
+
+The daemon starts automatically on first command and persists between commands for fast subsequent operations.
+
+## Platforms
+
+| Platform | Binary | Fallback |
+|----------|--------|----------|
+| macOS ARM64 | ✅ Native Rust | Node.js |
+| macOS x64 | ✅ Native Rust | Node.js |
+| Linux ARM64 | ✅ Native Rust | Node.js |
+| Linux x64 | ✅ Native Rust | Node.js |
+| Windows | - | Node.js |
+
+## Usage with AI Agents
+
+### Just ask the agent
+
+The simplest approach - just tell your agent to use it:
+
+```
+Use agent-browser to test the login flow. Run agent-browser --help to see available commands.
+```
+
+The `--help` output is comprehensive and most agents can figure it out from there.
+
+### AGENTS.md / CLAUDE.md
+
+For more consistent results, add to your project or global instructions file:
+
+```markdown
+## Browser Automation
+
+Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.
+
+Core workflow:
+1. `agent-browser open <url>` - Navigate to page
+2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
+3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
+4. Re-snapshot after page changes
+```
+
+### Claude Code Skill
+
+For Claude Code, a [skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) provides richer context:
+
+```bash
+cp -r node_modules/agent-browser/skills/browsing-web .claude/skills/
+```
+
+Or download:
+
+```bash
+mkdir -p .claude/skills/browsing-web
+curl -o .claude/skills/browsing-web/SKILL.md \
+  https://raw.githubusercontent.com/vercel-labs/agent-browser/main/skills/browsing-web/SKILL.md
 ```
 
 ## License

package/bin/agent-browser

@@ -1,4 +1,7 @@
 #!/bin/sh
+# agent-browser CLI wrapper
+# Detects OS/arch and runs the appropriate native binary
+
 SCRIPT="$0"
 while [ -L "$SCRIPT" ]; do
   SCRIPT_DIR="$(cd "$(dirname "$SCRIPT")" && pwd)"
@@ -6,10 +9,18 @@ while [ -L "$SCRIPT" ]; do
   case "$SCRIPT" in /*) ;; *) SCRIPT="$SCRIPT_DIR/$SCRIPT" ;; esac
 done
 SCRIPT_DIR="$(cd "$(dirname "$SCRIPT")" && pwd)"
+
 OS=$(uname -s | tr '[:upper:]' '[:lower:]')
 ARCH=$(uname -m)
 case "$OS" in darwin) OS="darwin" ;; linux) OS="linux" ;; mingw*|msys*|cygwin*) OS="win32" ;; esac
 case "$ARCH" in x86_64|amd64) ARCH="x64" ;; aarch64|arm64) ARCH="arm64" ;; esac
+
 BINARY="$SCRIPT_DIR/agent-browser-${OS}-${ARCH}"
-[ -f "$BINARY" ] && [ -x "$BINARY" ] && exec "$BINARY" "$@"
-exec node "$SCRIPT_DIR/../dist/index.js" "$@"
+
+if [ -f "$BINARY" ] && [ -x "$BINARY" ]; then
+  exec "$BINARY" "$@"
+fi
+
+echo "Error: No binary found for ${OS}-${ARCH}" >&2
+echo "Run 'npm run build:native' to build for your platform" >&2
+exit 1

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAoGT,MAAM,YAAY,CAAC;AASpB;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiPjG"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAoGT,MAAM,YAAY,CAAC;AAkDpB;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiPjG"}

package/dist/actions.js

@@ -1,4 +1,31 @@
 import { successResponse, errorResponse } from './protocol.js';
+/**
+ * Convert Playwright errors to AI-friendly messages
+ */
+function toAIFriendlyError(error, selector) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Handle strict mode violation (multiple elements match)
+    if (message.includes('strict mode violation')) {
+        // Extract count if available
+        const countMatch = message.match(/resolved to (\d+) elements/);
+        const count = countMatch ? countMatch[1] : 'multiple';
+        return new Error(`Selector "${selector}" matched ${count} elements. ` +
+            `Run 'snapshot' to get updated refs, or use a more specific CSS selector.`);
+    }
+    // Handle element not found
+    if (message.includes('waiting for') &&
+        (message.includes('to be visible') || message.includes('Timeout'))) {
+        return new Error(`Element "${selector}" not found or not visible. ` +
+            `Run 'snapshot' to see current page elements.`);
+    }
+    // Handle element not interactable
+    if (message.includes('intercepts pointer events') || message.includes('not visible')) {
+        return new Error(`Element "${selector}" is not interactable (may be hidden or covered). ` +
+            `Try scrolling it into view or check if a modal/overlay is blocking it.`);
+    }
+    // Return original error for unknown cases
+    return error instanceof Error ? error : new Error(message);
+}
 /**
  * Execute a command and return a response
  */
@@ -262,21 +289,31 @@ async function handleNavigate(command, browser) {
 async function handleClick(command, browser) {
     // Support both refs (@e1) and regular selectors
     const locator = browser.getLocator(command.selector);
-    await locator.click({
-        button: command.button,
-        clickCount: command.clickCount,
-        delay: command.delay,
-    });
+    try {
+        await locator.click({
+            button: command.button,
+            clickCount: command.clickCount,
+            delay: command.delay,
+        });
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
+    }
     return successResponse(command.id, { clicked: true });
 }
 async function handleType(command, browser) {
     const locator = browser.getLocator(command.selector);
-    if (command.clear) {
-        await locator.fill('');
+    try {
+        if (command.clear) {
+            await locator.fill('');
+        }
+        await locator.pressSequentially(command.text, {
+            delay: command.delay,
+        });
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
     }
-    await locator.pressSequentially(command.text, {
-        delay: command.delay,
-    });
     return successResponse(command.id, { typed: true });
 }
 async function handlePress(command, browser) {
@@ -391,12 +428,22 @@ async function handleScroll(command, browser) {
 async function handleSelect(command, browser) {
     const locator = browser.getLocator(command.selector);
     const values = Array.isArray(command.values) ? command.values : [command.values];
-    await locator.selectOption(values);
+    try {
+        await locator.selectOption(values);
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
+    }
     return successResponse(command.id, { selected: values });
 }
 async function handleHover(command, browser) {
     const locator = browser.getLocator(command.selector);
-    await locator.hover();
+    try {
+        await locator.hover();
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
+    }
     return successResponse(command.id, { hovered: true });
 }
 async function handleContent(command, browser) {
@@ -444,33 +491,63 @@ async function handleWindowNew(command, browser) {
 // New handlers for enhanced Playwright parity
 async function handleFill(command, browser) {
     const locator = browser.getLocator(command.selector);
-    await locator.fill(command.value);
+    try {
+        await locator.fill(command.value);
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
+    }
     return successResponse(command.id, { filled: true });
 }
 async function handleCheck(command, browser) {
     const locator = browser.getLocator(command.selector);
-    await locator.check();
+    try {
+        await locator.check();
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
+    }
     return successResponse(command.id, { checked: true });
 }
 async function handleUncheck(command, browser) {
     const locator = browser.getLocator(command.selector);
-    await locator.uncheck();
+    try {
+        await locator.uncheck();
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
+    }
     return successResponse(command.id, { unchecked: true });
 }
 async function handleUpload(command, browser) {
     const locator = browser.getLocator(command.selector);
     const files = Array.isArray(command.files) ? command.files : [command.files];
-    await locator.setInputFiles(files);
+    try {
+        await locator.setInputFiles(files);
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
+    }
     return successResponse(command.id, { uploaded: files });
 }
 async function handleDoubleClick(command, browser) {
     const locator = browser.getLocator(command.selector);
-    await locator.dblclick();
+    try {
+        await locator.dblclick();
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
+    }
     return successResponse(command.id, { clicked: true });
 }
 async function handleFocus(command, browser) {
     const locator = browser.getLocator(command.selector);
-    await locator.focus();
+    try {
+        await locator.focus();
+    }
+    catch (error) {
+        throw toAIFriendlyError(error, command.selector);
+    }
     return successResponse(command.id, { focused: true });
 }
 async function handleDrag(command, browser) {
@@ -556,7 +633,15 @@ async function handleCookiesGet(command, browser) {
 async function handleCookiesSet(command, browser) {
     const page = browser.getPage();
     const context = page.context();
-    await context.addCookies(command.cookies);
+    // Auto-fill URL for cookies that don't have domain/path/url set
+    const pageUrl = page.url();
+    const cookies = command.cookies.map((cookie) => {
+        if (!cookie.url && !cookie.domain && !cookie.path) {
+            return { ...cookie, url: pageUrl };
+        }
+        return cookie;
+    });
+    await context.addCookies(cookies);
     return successResponse(command.id, { set: true });
 }
 async function handleCookiesClear(command, browser) {