agent-browser 0.9.4 → 0.11.0

package/README.md

@@ -4,13 +4,43 @@ Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallba
 
 ## Installation
 
-### npm (recommended)
+### Global Installation (recommended)
+
+Installs the native Rust binary for maximum performance:
 
 ```bash
 npm install -g agent-browser
 agent-browser install  # Download Chromium
 ```
 
+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
+```
+
+Then use via `npx` or `package.json` scripts:
+
+```bash
+npx agent-browser open example.com
+```
+
 ### Homebrew (macOS)
 
 ```bash
@@ -65,7 +95,7 @@ agent-browser find role button click --name "Submit"
 
 ```bash
 agent-browser open <url>              # Navigate to URL (aliases: goto, navigate)
-agent-browser click <sel>             # Click element
+agent-browser click <sel>             # Click element (--new-tab to open in new tab)
 agent-browser dblclick <sel>          # Double-click element
 agent-browser focus <sel>             # Focus element
 agent-browser type <sel> <text>       # Type into element
@@ -100,6 +130,7 @@ agent-browser get title               # Get page title
 agent-browser get url                 # Get current URL
 agent-browser get count <sel>         # Count matching elements
 agent-browser get box <sel>           # Get bounding box
+agent-browser get styles <sel>        # Get computed styles
 ```
 
 ### Check State
@@ -125,7 +156,9 @@ agent-browser find last <sel> <action> [value]        # Last match
 agent-browser find nth <n> <sel> <action> [value]     # Nth match
 ```
 
-**Actions:** `click`, `fill`, `check`, `hover`, `text`
+**Actions:** `click`, `fill`, `type`, `hover`, `focus`, `check`, `uncheck`, `text`
+
+**Options:** `--name <name>` (filter role by accessible name), `--exact` (require exact text match)
 
 **Examples:**
 ```bash
@@ -225,6 +258,8 @@ agent-browser dialog dismiss          # Dismiss
 ```bash
 agent-browser trace start [path]      # Start recording trace
 agent-browser trace stop [path]       # Stop and save trace
+agent-browser profiler start          # Start Chrome DevTools profiling
+agent-browser profiler stop [path]    # Stop and save profile (.json)
 agent-browser console                 # View console messages (log, error, warn, info)
 agent-browser console --clear         # Clear console
 agent-browser errors                  # View page errors (uncaught JavaScript exceptions)
@@ -232,6 +267,12 @@ 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 state list              # List saved state files
+agent-browser state show <file>       # Show state summary
+agent-browser state rename <old> <new> # Rename state file
+agent-browser state clear [name]      # Clear states for session
+agent-browser state clear --all       # Clear all saved states
+agent-browser state clean --older-than <days>  # Delete old states
 ```
 
 ### Navigation
@@ -302,6 +343,40 @@ The profile directory stores:
 
 **Tip**: Use different profile paths for different projects to keep their browser state isolated.
 
+## Session Persistence
+
+Alternatively, use `--session-name` to automatically save and restore cookies and localStorage across browser restarts:
+
+```bash
+# Auto-save/load state for "twitter" session
+agent-browser --session-name twitter open twitter.com
+
+# Login once, then state persists automatically
+# State files stored in ~/.agent-browser/sessions/
+
+# Or via environment variable
+export AGENT_BROWSER_SESSION_NAME=twitter
+agent-browser open twitter.com
+```
+
+### State Encryption
+
+Encrypt saved session data at rest with AES-256-GCM:
+
+```bash
+# Generate key: openssl rand -hex 32
+export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key>
+
+# State files are now encrypted automatically
+agent-browser --session-name secure open example.com
+```
+
+| Variable | Description |
+|----------|-------------|
+| `AGENT_BROWSER_SESSION_NAME` | Auto-save/load state persistence name |
+| `AGENT_BROWSER_ENCRYPTION_KEY` | 64-char hex key for AES-256-GCM encryption |
+| `AGENT_BROWSER_STATE_EXPIRE_DAYS` | Auto-delete states older than N days (default: 30) |
+
 ## Snapshot Options
 
 The `snapshot` command supports filtering to reduce output size:
@@ -331,25 +406,66 @@ The `-C` flag is useful for modern web apps that use custom clickable elements (
 | Option | Description |
 |--------|-------------|
 | `--session <name>` | Use isolated session (or `AGENT_BROWSER_SESSION` env) |
+| `--session-name <name>` | Auto-save/restore session state (or `AGENT_BROWSER_SESSION_NAME` env) |
 | `--profile <path>` | Persistent browser profile directory (or `AGENT_BROWSER_PROFILE` env) |
+| `--state <path>` | Load storage state from JSON file (or `AGENT_BROWSER_STATE` env) |
 | `--headers <json>` | Set HTTP headers scoped to the URL's origin |
 | `--executable-path <path>` | Custom browser executable (or `AGENT_BROWSER_EXECUTABLE_PATH` env) |
+| `--extension <path>` | Load browser extension (repeatable; or `AGENT_BROWSER_EXTENSIONS` env) |
 | `--args <args>` | Browser launch args, comma or newline separated (or `AGENT_BROWSER_ARGS` env) |
 | `--user-agent <ua>` | Custom User-Agent string (or `AGENT_BROWSER_USER_AGENT` env) |
 | `--proxy <url>` | Proxy server URL with optional auth (or `AGENT_BROWSER_PROXY` env) |
 | `--proxy-bypass <hosts>` | Hosts to bypass proxy (or `AGENT_BROWSER_PROXY_BYPASS` env) |
+| `--ignore-https-errors` | Ignore HTTPS certificate errors (useful for self-signed certs) |
+| `--allow-file-access` | Allow file:// URLs to access local files (Chromium only) |
 | `-p, --provider <name>` | Cloud browser provider (or `AGENT_BROWSER_PROVIDER` env) |
+| `--device <name>` | iOS device name, e.g. "iPhone 15 Pro" (or `AGENT_BROWSER_IOS_DEVICE` 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) |
-| `--cdp <port>` | Connect via Chrome DevTools Protocol |
+| `--cdp <port\|url>` | Connect via Chrome DevTools Protocol (port or WebSocket URL) |
 | `--auto-connect` | Auto-discover and connect to running Chrome (or `AGENT_BROWSER_AUTO_CONNECT` env) |
-| `--ignore-https-errors` | Ignore HTTPS certificate errors (useful for self-signed certs) |
-| `--allow-file-access` | Allow file:// URLs to access local files (Chromium only) |
+| `--config <path>` | Use a custom config file (or `AGENT_BROWSER_CONFIG` env) |
 | `--debug` | Debug output |
 
+## Configuration
+
+Create an `agent-browser.json` file to set persistent defaults instead of repeating flags on every command.
+
+**Locations (lowest to highest priority):**
+
+1. `~/.agent-browser/config.json` -- user-level defaults
+2. `./agent-browser.json` -- project-level overrides (in working directory)
+3. `AGENT_BROWSER_*` environment variables override config file values
+4. CLI flags override everything
+
+**Example `agent-browser.json`:**
+
+```json
+{
+  "headed": true,
+  "proxy": "http://localhost:8080",
+  "profile": "./browser-data",
+  "userAgent": "my-agent/1.0",
+  "ignoreHttpsErrors": true
+}
+```
+
+Use `--config <path>` or `AGENT_BROWSER_CONFIG` to load a specific config file instead of the defaults:
+
+```bash
+agent-browser --config ./ci-config.json open example.com
+AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com
+```
+
+All options from the table above can be set in the config file using camelCase keys (e.g., `--executable-path` becomes `"executablePath"`, `--proxy-bypass` becomes `"proxyBypass"`). Unknown keys are ignored for forward compatibility.
+
+Boolean flags accept an optional `true`/`false` value to override config settings. For example, `--headed false` disables `"headed": true` from config. A bare `--headed` is equivalent to `--headed true`.
+
+Auto-discovered config files that are missing are silently ignored. If `--config <path>` points to a missing or invalid file, agent-browser exits with an error. Extensions from user and project configs are merged (concatenated), not replaced.
+
+> **Tip:** If your project-level `agent-browser.json` contains environment-specific values (paths, proxies), consider adding it to `.gitignore`.
+
 ## Selectors
 
 ### Refs (Recommended for AI)
@@ -711,7 +827,7 @@ The daemon starts automatically on first command and persists between commands f
 
 ### Just ask the agent
 
-The simplest approach - just tell your agent to use it:
+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.
@@ -719,7 +835,7 @@ Use agent-browser to test the login flow. Run agent-browser --help to see availa
 
 The `--help` output is comprehensive and most agents can figure it out from there.
 
-### AI Coding Assistants
+### AI Coding Assistants (recommended)
 
 Add the skill to your AI coding assistant for richer context:
 
@@ -727,7 +843,17 @@ Add the skill to your AI coding assistant for richer context:
 npx skills add vercel-labs/agent-browser
 ```
 
-This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf.
+This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. The skill is fetched from the repository, so it stays up to date automatically -- do not copy `SKILL.md` from `node_modules` as it will become stale.
+
+### Claude Code
+
+Install as a Claude Code skill:
+
+```bash
+npx skills add vercel-labs/agent-browser
+```
+
+This adds the skill to `.claude/skills/agent-browser/SKILL.md` in your project. The skill teaches Claude Code the full agent-browser workflow, including the snapshot-ref interaction pattern, session management, and timeout handling.
 
 ### AGENTS.md / CLAUDE.md
 

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAqHT,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,IAAI,GAClD,IAAI,CAEN;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAqDzE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAmQjG"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAUpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EA4HT,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,IAAI,GAClD,IAAI,CAEN;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAqDzE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiRjG"}

package/dist/actions.js

@@ -1,6 +1,8 @@
+import * as fs from 'fs';
+import * as path from 'path';
 import { mkdirSync } from 'node:fs';
-import path from 'node:path';
 import { getAppDir } from './daemon.js';
+import { getSessionsDir, readStateFile, isValidSessionName, isEncryptedPayload, listStateFiles, cleanupExpiredStates, } from './state-utils.js';
 import { successResponse, errorResponse } from './protocol.js';
 // Callback for screencast frames - will be set by the daemon when streaming is active
 let screencastFrameCallback = null;
@@ -188,6 +190,10 @@ export async function executeCommand(command, browser) {
                 return await handleTraceStart(command, browser);
             case 'trace_stop':
                 return await handleTraceStop(command, browser);
+            case 'profiler_start':
+                return await handleProfilerStart(command, browser);
+            case 'profiler_stop':
+                return await handleProfilerStop(command, browser);
             case 'har_start':
                 return await handleHarStart(command, browser);
             case 'har_stop':
@@ -196,6 +202,16 @@ export async function executeCommand(command, browser) {
                 return await handleStateSave(command, browser);
             case 'state_load':
                 return await handleStateLoad(command, browser);
+            case 'state_list':
+                return await handleStateList(command);
+            case 'state_clear':
+                return await handleStateClear(command);
+            case 'state_show':
+                return await handleStateShow(command);
+            case 'state_clean':
+                return await handleStateClean(command);
+            case 'state_rename':
+                return await handleStateRename(command);
             case 'console':
                 return await handleConsole(command, browser);
             case 'errors':
@@ -336,6 +352,27 @@ async function handleClick(command, browser) {
     // Support both refs (@e1) and regular selectors
     const locator = browser.getLocator(command.selector);
     try {
+        // If --new-tab flag is set, get the href and open in a new tab
+        if (command.newTab) {
+            const fullUrl = await locator.evaluate((el) => {
+                const href = el.getAttribute('href');
+                // URL and document.baseURI are available in the browser context
+                return href
+                    ? new globalThis.URL(href, globalThis.document.baseURI).toString()
+                    : '';
+            });
+            if (!fullUrl) {
+                throw new Error(`Element '${command.selector}' does not have an href attribute. --new-tab only works on links.`);
+            }
+            await browser.newTab();
+            const newPage = browser.getPage();
+            await newPage.goto(fullUrl);
+            return successResponse(command.id, {
+                clicked: true,
+                newTab: true,
+                url: fullUrl,
+            });
+        }
         await locator.click({
             button: command.button,
             clickCount: command.clickCount,
@@ -980,7 +1017,24 @@ async function handleTraceStart(command, browser) {
 }
 async function handleTraceStop(command, browser) {
     await browser.stopTracing(command.path);
-    return successResponse(command.id, { path: command.path });
+    return successResponse(command.id, command.path ? { path: command.path } : { traceStopped: true });
+}
+async function handleProfilerStart(command, browser) {
+    await browser.startProfiling({ categories: command.categories });
+    return successResponse(command.id, { started: true });
+}
+async function handleProfilerStop(command, browser) {
+    let outputPath = command.path;
+    if (!outputPath) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const random = Math.random().toString(36).substring(2, 8);
+        const filename = `profile-${timestamp}-${random}.json`;
+        const profileDir = path.join(getAppDir(), 'tmp', 'profiles');
+        mkdirSync(profileDir, { recursive: true });
+        outputPath = path.join(profileDir, filename);
+    }
+    const result = await browser.stopProfiling(outputPath);
+    return successResponse(command.id, result);
 }
 async function handleHarStart(command, browser) {
     await browser.startHarRecording();
@@ -1001,12 +1055,145 @@ async function handleStateSave(command, browser) {
     return successResponse(command.id, { path: command.path });
 }
 async function handleStateLoad(command, browser) {
-    // Storage state is loaded at context creation
+    if (browser.isLaunched()) {
+        return errorResponse(command.id, 'Cannot load state while browser is running. Close browser first, then relaunch with loaded state.');
+    }
+    if (!fs.existsSync(command.path)) {
+        return errorResponse(command.id, `State file not found: ${command.path}`);
+    }
+    await browser.launch({
+        id: command.id,
+        action: 'launch',
+        headless: true,
+        autoStateFilePath: command.path,
+    });
     return successResponse(command.id, {
-        note: 'Storage state must be loaded at browser launch. Use --state flag.',
+        loaded: true,
         path: command.path,
     });
 }
+async function handleStateList(command) {
+    const sessionsDir = getSessionsDir();
+    const files = listStateFiles();
+    if (files.length === 0) {
+        return successResponse(command.id, { files: [], directory: sessionsDir });
+    }
+    const stateFiles = files
+        .map((filename) => {
+        const filepath = path.join(sessionsDir, filename);
+        const stats = fs.statSync(filepath);
+        let encrypted = false;
+        try {
+            const content = fs.readFileSync(filepath, 'utf-8');
+            const parsed = JSON.parse(content);
+            encrypted = isEncryptedPayload(parsed);
+        }
+        catch {
+            // Ignore parse errors
+        }
+        return {
+            filename,
+            path: filepath,
+            size: stats.size,
+            modified: stats.mtime.toISOString(),
+            encrypted,
+        };
+    })
+        .sort((a, b) => new Date(b.modified).getTime() - new Date(a.modified).getTime());
+    return successResponse(command.id, { files: stateFiles, directory: sessionsDir });
+}
+async function handleStateClear(command) {
+    const sessionsDir = getSessionsDir();
+    if (command.sessionName && !isValidSessionName(command.sessionName)) {
+        return errorResponse(command.id, 'Invalid session name. Use only letters, numbers, dashes, and underscores.');
+    }
+    const files = listStateFiles();
+    if (files.length === 0) {
+        return successResponse(command.id, { cleared: 0, deleted: [] });
+    }
+    const deleted = [];
+    if (command.all) {
+        for (const file of files) {
+            fs.unlinkSync(path.join(sessionsDir, file));
+            deleted.push(file);
+        }
+    }
+    else if (command.sessionName) {
+        for (const file of files) {
+            if (file.startsWith(`${command.sessionName}-`)) {
+                fs.unlinkSync(path.join(sessionsDir, file));
+                deleted.push(file);
+            }
+        }
+    }
+    return successResponse(command.id, { cleared: deleted.length, deleted });
+}
+async function handleStateShow(command) {
+    const sessionsDir = getSessionsDir();
+    const baseName = command.filename.replace(/\.json$/, '');
+    if (!command.filename.endsWith('.json') || !isValidSessionName(baseName)) {
+        return errorResponse(command.id, 'Invalid filename. Use only letters, numbers, dashes, and underscores (with .json extension).');
+    }
+    const filepath = path.join(sessionsDir, command.filename);
+    if (!fs.existsSync(filepath)) {
+        return errorResponse(command.id, `State file not found: ${command.filename}`);
+    }
+    try {
+        const { data: state, wasEncrypted } = readStateFile(filepath);
+        const stats = fs.statSync(filepath);
+        const stateObj = state;
+        const cookies = stateObj.cookies?.length || 0;
+        const origins = stateObj.origins?.length || 0;
+        const domains = [...new Set((stateObj.cookies || []).map((c) => c.domain))];
+        return successResponse(command.id, {
+            filename: command.filename,
+            path: filepath,
+            size: stats.size,
+            modified: stats.mtime.toISOString(),
+            encrypted: wasEncrypted,
+            summary: {
+                cookies,
+                origins,
+                domains,
+            },
+            state,
+        });
+    }
+    catch (e) {
+        return errorResponse(command.id, `Failed to parse state file: ${e.message}`);
+    }
+}
+async function handleStateClean(command) {
+    const deleted = cleanupExpiredStates(command.days);
+    const keptCount = listStateFiles().length;
+    return successResponse(command.id, {
+        cleaned: deleted.length,
+        deleted,
+        keptCount,
+        days: command.days,
+    });
+}
+async function handleStateRename(command) {
+    const sessionsDir = getSessionsDir();
+    if (!isValidSessionName(command.oldName) || !isValidSessionName(command.newName)) {
+        return errorResponse(command.id, 'Invalid name. Use only letters, numbers, dashes, and underscores.');
+    }
+    const oldPath = path.join(sessionsDir, `${command.oldName}.json`);
+    const newPath = path.join(sessionsDir, `${command.newName}.json`);
+    if (!fs.existsSync(oldPath)) {
+        return errorResponse(command.id, `State file not found: ${command.oldName}.json`);
+    }
+    if (fs.existsSync(newPath)) {
+        return errorResponse(command.id, `Destination already exists: ${command.newName}.json`);
+    }
+    fs.renameSync(oldPath, newPath);
+    return successResponse(command.id, {
+        renamed: true,
+        oldName: `${command.oldName}.json`,
+        newName: `${command.newName}.json`,
+        path: newPath,
+    });
+}
 async function handleConsole(command, browser) {
     if (command.clear) {
         browser.clearConsoleMessages();