agent-browser 0.19.0 → 0.20.1

package/README.md

@@ -1,51 +1,41 @@
 # agent-browser
 
-Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallback.
+Headless browser automation CLI for AI agents. Fast native Rust CLI.
 
 ## Installation
 
 ### Global Installation (recommended)
 
-Installs the native Rust binary for maximum performance:
+Installs the native Rust binary:
 
 ```bash
 npm install -g agent-browser
-agent-browser install  # Download Chromium
+agent-browser install  # Download Chrome from Chrome for Testing (first time only)
 ```
 
-This is the fastest option -- commands run through the native Rust CLI directly with sub-millisecond parsing overhead.
-
-### Quick Start (no install)
-
-Run directly with `npx` if you want to try it without installing globally:
-
-```bash
-npx agent-browser install   # Download Chromium (first time only)
-npx agent-browser open example.com
-```
-
-> **Note:** `npx` routes through Node.js before reaching the Rust CLI, so it is noticeably slower than a global install. For regular use, install globally.
-
 ### Project Installation (local dependency)
 
 For projects that want to pin the version in `package.json`:
 
 ```bash
 npm install agent-browser
-npx agent-browser install
+agent-browser install
 ```
 
-Then use via `npx` or `package.json` scripts:
+Then use via `package.json` scripts or by invoking `agent-browser` directly.
+
+### Homebrew (macOS)
 
 ```bash
-npx agent-browser open example.com
+brew install agent-browser
+agent-browser install  # Download Chrome from Chrome for Testing (first time only)
 ```
 
-### Homebrew (macOS)
+### Cargo (Rust)
 
 ```bash
-brew install agent-browser
-agent-browser install  # Download Chromium
+cargo install agent-browser
+agent-browser install  # Download Chrome from Chrome for Testing (first time only)
 ```
 
 ### From Source
@@ -66,9 +56,13 @@ On Linux, install system dependencies:
 
 ```bash
 agent-browser install --with-deps
-# or manually: npx playwright install-deps chromium
 ```
 
+### Requirements
+
+- **Chrome** - Run `agent-browser install` to download Chrome from [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/) (Google's official automation channel). No Playwright or Node.js required for the daemon.
+- **Rust** - Only needed when building from source (see From Source above).
+
 ## Quick Start
 
 ```bash
@@ -322,7 +316,7 @@ agent-browser reload                  # Reload page
 ### Setup
 
 ```bash
-agent-browser install                 # Download Chromium browser
+agent-browser install                 # Download Chrome from Chrome for Testing (Google's official automation channel)
 agent-browser install --with-deps     # Also install system deps (Linux)
 ```
 
@@ -506,7 +500,7 @@ The `-C` flag is useful for modern web apps that use custom clickable elements (
 
 The `--annotate` flag overlays numbered labels on interactive elements in the screenshot. Each label `[N]` corresponds to ref `@eN`, so the same refs work for both visual and text-based workflows.
 
-In native mode, annotated screenshots are supported on the CDP-backed browser path (`--native` with Chromium/Lightpanda). The Safari/WebDriver backend does not yet support `--annotate`.
+Annotated screenshots are supported on the CDP-backed browser path (Chrome/Lightpanda). The Safari/WebDriver backend does not yet support `--annotate`.
 
 ```bash
 agent-browser screenshot --annotate
@@ -561,8 +555,7 @@ This is useful for multimodal AI models that can reason about visual layout, unl
 | `--action-policy <path>` | Path to action policy JSON file (or `AGENT_BROWSER_ACTION_POLICY` env) |
 | `--confirm-actions <list>` | Action categories requiring confirmation (or `AGENT_BROWSER_CONFIRM_ACTIONS` env) |
 | `--confirm-interactive` | Interactive confirmation prompts; auto-denies if stdin is not a TTY (or `AGENT_BROWSER_CONFIRM_INTERACTIVE` env) |
-| `--engine <name>` | Browser engine: `chrome` (default), `lightpanda`; implies `--native` (or `AGENT_BROWSER_ENGINE` env) |
-| `--native` | [Experimental] Use native Rust daemon instead of Node.js (or `AGENT_BROWSER_NATIVE` env) |
+| `--engine <name>` | Browser engine: `chrome` (default), `lightpanda` (or `AGENT_BROWSER_ENGINE` env) |
 | `--config <path>` | Use a custom config file (or `AGENT_BROWSER_CONFIG` env) |
 | `--debug` | Debug output |
 
@@ -606,7 +599,7 @@ Auto-discovered config files that are missing are silently ignored. If `--config
 
 ## Default Timeout
 
-The default Playwright timeout for standard operations (clicks, waits, fills, etc.) is 25 seconds. This is intentionally below the CLI's 30-second IPC read timeout so that Playwright returns a proper error instead of the CLI timing out with EAGAIN.
+The default timeout for standard operations (clicks, waits, fills, etc.) is 25 seconds. This is intentionally below the CLI's 30-second IPC read timeout so that the daemon returns a proper error instead of the CLI timing out with EAGAIN.
 
 Override the default timeout via environment variable:
 
@@ -615,11 +608,11 @@ Override the default timeout via environment variable:
 export AGENT_BROWSER_DEFAULT_TIMEOUT=45000
 ```
 
-> **Note:** Setting this above 30000 (30s) may cause EAGAIN errors on slow operations because the CLI's read timeout will expire before Playwright responds. The CLI retries transient errors automatically, but response times will increase.
+> **Note:** Setting this above 30000 (30s) may cause EAGAIN errors on slow operations because the CLI's read timeout will expire before the daemon responds. The CLI retries transient errors automatically, but response times will increase.
 
-| Variable                        | Description                                       |
-| ------------------------------- | ------------------------------------------------- |
-| `AGENT_BROWSER_DEFAULT_TIMEOUT` | Default Playwright timeout in ms (default: 25000) |
+| Variable                        | Description                              |
+| ------------------------------- | ---------------------------------------- |
+| `AGENT_BROWSER_DEFAULT_TIMEOUT` | Default operation timeout in ms (default: 25000) |
 
 ## Selectors
 
@@ -1009,61 +1002,22 @@ await browser.stopScreencast();
 
 agent-browser uses a client-daemon architecture:
 
-1. **Rust CLI** (fast native binary) - Parses commands, communicates with daemon
-2. **Node.js Daemon** (default) - Manages Playwright browser instance
-3. **Native Daemon** (experimental, `--native`) - Pure Rust daemon using direct CDP, no Node.js required
-4. **Fallback** - If native binary unavailable, uses Node.js directly
-
-The daemon starts automatically on first command and persists between commands for fast subsequent operations.
-
-**Browser Engine:** Uses Chromium by default. The default Node.js daemon also supports Firefox and WebKit via Playwright. The experimental native daemon speaks Chrome DevTools Protocol (CDP) directly and supports Chromium-based browsers and Safari (via WebDriver).
-
-## Experimental: Native Mode
-
-The native daemon is a pure Rust implementation that communicates with Chrome directly via CDP, eliminating the Node.js and Playwright dependencies. It is currently **experimental** and opt-in.
-
-### Enabling Native Mode
-
-```bash
-# Via flag
-agent-browser --native open example.com
-
-# Via environment variable (recommended for persistent use)
-export AGENT_BROWSER_NATIVE=1
-agent-browser open example.com
-```
-
-Or add to your config file (`agent-browser.json`):
-
-```json
-{ "native": true }
-```
-
-### What's Different
-
-|                     | Default (Node.js)           | Native (`--native`)              |
-| ------------------- | --------------------------- | -------------------------------- |
-| **Runtime**         | Node.js + Playwright        | Pure Rust binary                 |
-| **Protocol**        | Playwright protocol         | Direct CDP / WebDriver           |
-| **Install size**    | Larger (Node.js + npm deps) | Smaller (single binary)          |
-| **Browser support** | Chromium, Firefox, WebKit   | Chromium, Safari (via WebDriver) |
-| **Stability**       | Stable                      | Experimental                     |
+1. **Rust CLI** - Parses commands, communicates with daemon
+2. **Rust Daemon** - Pure Rust daemon using direct CDP, no Node.js required
 
-### Known Limitations
+The daemon starts automatically on first command and persists between commands for fast subsequent operations. To auto-shutdown the daemon after a period of inactivity, set `AGENT_BROWSER_IDLE_TIMEOUT_MS` (value in milliseconds). When set, the daemon closes the browser and exits after receiving no commands for the specified duration.
 
-- Firefox and WebKit are not yet supported (Chromium and Safari only)
-- Some Playwright-specific features (tracing format, HAR export) are not available
-- The native daemon and Node.js daemon share the same session socket, so you cannot run both simultaneously for the same session. Use `agent-browser close` before switching modes.
+**Browser Engine:** Uses Chrome (from Chrome for Testing) by default. The `--engine` flag selects between `chrome` and `lightpanda`. Supported browsers: Chromium/Chrome (via CDP) and Safari (via WebDriver for iOS).
 
 ## 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 x64 | Native Rust | Node.js  |
+| Platform    | Binary      |
+| ----------- | ----------- |
+| macOS ARM64 | Native Rust |
+| macOS x64   | Native Rust |
+| Linux ARM64 | Native Rust |
+| Linux x64   | Native Rust |
+| Windows x64 | Native Rust |
 
 ## Usage with AI Agents
 

package/package.json

@@ -1,20 +1,9 @@
 {
   "name": "agent-browser",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "Headless browser automation CLI for AI agents",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
   "files": [
-    "dist",
     "bin",
     "scripts",
     "skills"
@@ -26,7 +15,8 @@
     "browser",
     "automation",
     "headless",
-    "playwright",
+    "chrome",
+    "cdp",
     "cli",
     "agent"
   ],
@@ -39,55 +29,22 @@
     "url": "https://github.com/vercel-labs/agent-browser/issues"
   },
   "homepage": "https://github.com/vercel-labs/agent-browser#readme",
-  "dependencies": {
-    "node-simctl": "^7.4.0",
-    "playwright-core": "^1.57.0",
-    "webdriverio": "^9.15.0",
-    "ws": "^8.19.0",
-    "zod": "^3.22.4"
-  },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.52",
-    "@changesets/cli": "^2.29.8",
-    "@types/node": "^20.10.0",
-    "@types/ws": "^8.18.1",
-    "husky": "^9.1.7",
-    "lint-staged": "^15.2.11",
-    "playwright": "^1.57.0",
-    "prettier": "^3.7.4",
-    "tsx": "^4.6.0",
-    "typescript": "^5.3.0",
-    "vitest": "^4.0.16"
-  },
-  "lint-staged": {
-    "src/**/*.ts": "prettier --write"
+    "@changesets/cli": "^2.29.8"
   },
   "scripts": {
     "version:sync": "node scripts/sync-version.js",
     "version": "npm run version:sync && git add cli/Cargo.toml",
-    "build": "tsc",
     "build:native": "npm run version:sync && cargo build --release --manifest-path cli/Cargo.toml && node scripts/copy-native.js",
     "build:linux": "npm run version:sync && docker compose -f docker/docker-compose.yml run --rm build-linux",
     "build:macos": "npm run version:sync && (cargo build --release --manifest-path cli/Cargo.toml --target aarch64-apple-darwin & cargo build --release --manifest-path cli/Cargo.toml --target x86_64-apple-darwin & wait) && cp cli/target/aarch64-apple-darwin/release/agent-browser bin/agent-browser-darwin-arm64 && cp cli/target/x86_64-apple-darwin/release/agent-browser bin/agent-browser-darwin-x64",
     "build:windows": "npm run version:sync && docker compose -f docker/docker-compose.yml run --rm build-windows",
     "build:all-platforms": "npm run version:sync && (npm run build:linux & npm run build:windows & wait) && npm run build:macos",
     "build:docker": "docker build -t agent-browser-builder -f docker/Dockerfile.build .",
-    "release": "npm run version:sync && npm run build && npm run build:all-platforms && npm publish",
-    "start": "node dist/daemon.js",
-    "dev": "tsx src/daemon.ts",
-    "typecheck": "tsc --noEmit",
-    "format": "prettier --write 'src/**/*.ts'",
-    "format:check": "prettier --check 'src/**/*.ts'",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:e2e:dogfood": "vitest run test/e2e/dogfood.eval.ts",
-    "bench": "pnpm build && tsx test/benchmarks/run.ts",
-    "bench:node": "pnpm build && tsx test/benchmarks/run.ts --node-only",
-    "bench:native": "pnpm build && tsx test/benchmarks/run.ts --native-only",
-    "bench:engine": "pnpm build && tsx test/benchmarks/run.ts --engine",
+    "release": "npm run version:sync && npm run build:all-platforms && npm publish",
     "postinstall": "node scripts/postinstall.js",
     "changeset": "changeset",
     "ci:version": "changeset version && pnpm run version:sync && pnpm install --no-frozen-lockfile",
-    "ci:publish": "pnpm run version:sync && pnpm run build && changeset publish"
+    "ci:publish": "pnpm run version:sync && changeset publish"
   }
 }

package/scripts/postinstall.js

@@ -80,7 +80,7 @@ async function main() {
     // On global installs, fix npm's bin entry to use native binary directly
     await fixGlobalInstallBin();
     
-    showPlaywrightReminder();
+    showInstallReminder();
     return;
   }
 
@@ -102,8 +102,7 @@ async function main() {
     
     console.log(`✓ Downloaded native binary: ${binaryName}`);
   } catch (err) {
-    console.log(`⚠ Could not download native binary: ${err.message}`);
-    console.log(`  The CLI will use Node.js fallback (slightly slower startup)`);
+    console.log(`Could not download native binary: ${err.message}`);
     console.log('');
     console.log('To build the native binary locally:');
     console.log('  1. Install Rust: https://rustup.rs');
@@ -114,21 +113,19 @@ async function main() {
   // This avoids the /bin/sh error on Windows and provides zero-overhead execution
   await fixGlobalInstallBin();
 
-  showPlaywrightReminder();
+  showInstallReminder();
 }
 
-function showPlaywrightReminder() {
+function showInstallReminder() {
+  console.log('');
+  console.log('  To download Chrome, run:');
+  console.log('');
+  console.log('    agent-browser install');
+  console.log('');
+  console.log('  On Linux, include system dependencies with:');
+  console.log('');
+  console.log('    agent-browser install --with-deps');
   console.log('');
-  console.log('╔═══════════════════════════════════════════════════════════════════════════╗');
-  console.log('║ To download browser binaries, run:                                        ║');
-  console.log('║                                                                           ║');
-  console.log('║     npx playwright install chromium                                       ║');
-  console.log('║                                                                           ║');
-  console.log('║ On Linux, include system dependencies with:                               ║');
-  console.log('║                                                                           ║');
-  console.log('║     npx playwright install --with-deps chromium                           ║');
-  console.log('║                                                                           ║');
-  console.log('╚═══════════════════════════════════════════════════════════════════════════╝');
 }
 
 /**

package/skills/agent-browser/SKILL.md

@@ -6,6 +6,8 @@ allowed-tools: Bash(npx agent-browser:*), Bash(agent-browser:*)
 
 # Browser Automation with agent-browser
 
+The CLI uses Chrome/Chromium via CDP directly. Install via `npm i -g agent-browser`, `brew install agent-browser`, or `cargo install agent-browser`. Run `agent-browser install` to download Chrome.
+
 ## Core Workflow
 
 Every browser automation follows this pattern:
@@ -441,7 +443,7 @@ agent-browser diff url https://staging.example.com https://prod.example.com --sc
 
 ## Timeouts and Slow Pages
 
-The default Playwright timeout is 25 seconds for local browsers. This can be overridden with the `AGENT_BROWSER_DEFAULT_TIMEOUT` environment variable (value in milliseconds). For slow websites or large pages, use explicit waits instead of relying on the default timeout:
+The default timeout is 25 seconds. This can be overridden with the `AGENT_BROWSER_DEFAULT_TIMEOUT` environment variable (value in milliseconds). For slow websites or large pages, use explicit waits instead of relying on the default timeout:
 
 ```bash
 # Wait for network activity to settle (best for slow pages)
@@ -485,6 +487,12 @@ agent-browser --session agent1 close   # Close specific session
 
 If a previous session was not closed properly, the daemon may still be running. Use `agent-browser close` to clean it up before starting new work.
 
+To auto-shutdown the daemon after a period of inactivity (useful for ephemeral/CI environments):
+
+```bash
+AGENT_BROWSER_IDLE_TIMEOUT_MS=60000 agent-browser open example.com
+```
+
 ## Ref Lifecycle (Important)
 
 Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after:
@@ -503,8 +511,6 @@ agent-browser click @e1              # Use new refs
 
 Use `--annotate` to take a screenshot with numbered labels overlaid on interactive elements. Each label `[N]` maps to ref `@eN`. This also caches refs, so you can interact with elements immediately without a separate snapshot.
 
-In native mode, this currently works on the CDP-backed browser path (Chromium/Lightpanda). The Safari/WebDriver backend does not yet support `--annotate`.
-
 ```bash
 agent-browser screenshot --annotate
 # Output includes the image path and a legend:
@@ -589,21 +595,6 @@ Priority (lowest to highest): `~/.agent-browser/config.json` < `./agent-browser.
 | [references/profiling.md](references/profiling.md)                   | Chrome DevTools profiling for performance analysis        |
 | [references/proxy-support.md](references/proxy-support.md)           | Proxy configuration, geo-testing, rotating proxies        |
 
-## Experimental: Native Mode
-
-agent-browser has an experimental native Rust daemon that communicates with Chrome directly via CDP, bypassing Node.js and Playwright entirely. It is opt-in and not recommended for production use yet.
-
-```bash
-# Enable via flag
-agent-browser --native open example.com
-
-# Enable via environment variable (avoids passing --native every time)
-export AGENT_BROWSER_NATIVE=1
-agent-browser open example.com
-```
-
-The native daemon supports Chromium and Safari (via WebDriver). Firefox and WebKit are not yet supported. All core commands (navigate, snapshot, click, fill, screenshot, cookies, storage, tabs, eval, etc.) work identically in native mode. Use `agent-browser close` before switching between native and default mode within the same session.
-
 ## Browser Engine Selection
 
 Use `--engine` to choose a local browser engine. The default is `chrome`.

package/skills/electron/SKILL.md

@@ -104,11 +104,11 @@ agent-browser tab --url "*settings*"
 
 ## Webview Support
 
-Electron `<webview>` elements are automatically discovered and can be controlled like regular pages. When using `--native` mode, webviews appear as separate targets in the tab list with `type: "webview"`:
+Electron `<webview>` elements are automatically discovered and can be controlled like regular pages. Webviews appear as separate targets in the tab list with `type: "webview"`:
 
 ```bash
-# Connect in native mode
-agent-browser --native connect 9222
+# Connect to running Electron app
+agent-browser connect 9222
 
 # List targets -- webviews appear alongside pages
 agent-browser tab
@@ -125,7 +125,7 @@ agent-browser click @e3
 agent-browser screenshot webview.png
 ```
 
-**Note:** Webview support requires `--native` mode (raw CDP). The Playwright-based mode does not support webview targets.
+**Note:** Webview support works via raw CDP connection.
 
 ## Common Patterns
 
@@ -188,7 +188,7 @@ agent-browser --session vscode snapshot -i
 
 ## Color Scheme
 
-Playwright overrides the color scheme to `light` by default when connecting via CDP. To preserve dark mode:
+The default color scheme when connecting via CDP may be `light`. To preserve dark mode:
 
 ```bash
 agent-browser connect 9222

package/dist/action-policy.d.ts

@@ -1,14 +0,0 @@
-export interface ActionPolicy {
-    default: 'allow' | 'deny';
-    allow?: string[];
-    deny?: string[];
-}
-export type PolicyDecision = 'allow' | 'deny' | 'confirm';
-export declare const KNOWN_CATEGORIES: Set<string>;
-export declare function getActionCategory(action: string): string;
-export declare function loadPolicyFile(policyPath: string): ActionPolicy;
-export declare function initPolicyReloader(policyPath: string, policy: ActionPolicy): void;
-export declare function reloadPolicyIfChanged(): ActionPolicy | null;
-export declare function checkPolicy(action: string, policy: ActionPolicy | null, confirmCategories: Set<string>): PolicyDecision;
-export declare function describeAction(action: string, command: Record<string, unknown>): string;
-//# sourceMappingURL=action-policy.d.ts.map

package/dist/action-policy.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"action-policy.d.ts","sourceRoot":"","sources":["../src/action-policy.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AA4K1D,eAAO,MAAM,gBAAgB,aAE5B,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAwB/D;AAQD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAIjF;AAED,wBAAgB,qBAAqB,IAAI,YAAY,GAAG,IAAI,CAkB3D;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAC7B,cAAc,CAkBhB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAyBvF"}