agent-browser 0.17.0 → 0.18.0

package/README.md

@@ -131,6 +131,7 @@ agent-browser get value <sel>         # Get input value
 agent-browser get attr <sel> <attr>   # Get attribute
 agent-browser get title               # Get page title
 agent-browser get url                 # Get current URL
+agent-browser get cdp-url             # Get CDP WebSocket URL (for DevTools, debugging)
 agent-browser get count <sel>         # Count matching elements
 agent-browser get box <sel>           # Get bounding box
 agent-browser get styles <sel>        # Get computed styles
@@ -197,7 +198,7 @@ agent-browser mouse wheel <dy> [dx]   # Scroll wheel
 ### Browser Settings
 
 ```bash
-agent-browser set viewport <w> <h>    # Set viewport size
+agent-browser set viewport <w> <h> [scale]  # Set viewport size (scale for retina, e.g. 2)
 agent-browser set device <name>       # Emulate device ("iPhone 14")
 agent-browser set geo <lat> <lng>     # Set geolocation
 agent-browser set offline [on|off]    # Toggle offline mode
@@ -283,6 +284,7 @@ agent-browser console --clear         # Clear console
 agent-browser errors                  # View page errors (uncaught JavaScript exceptions)
 agent-browser errors --clear          # Clear errors
 agent-browser highlight <sel>         # Highlight element
+agent-browser inspect                 # Open Chrome DevTools for the active page
 agent-browser state save <path>       # Save auth state
 agent-browser state load <path>       # Load auth state
 agent-browser state list              # List saved state files
@@ -308,6 +310,47 @@ agent-browser install                 # Download Chromium browser
 agent-browser install --with-deps     # Also install system deps (Linux)
 ```
 
+## Authentication
+
+agent-browser provides multiple ways to persist login sessions so you don't re-authenticate every run.
+
+### Quick summary
+
+| Approach | Best for | Flag / Env |
+|----------|----------|------------|
+| **Persistent profile** | Full browser state (cookies, IndexedDB, service workers, cache) across restarts | `--profile <path>` / `AGENT_BROWSER_PROFILE` |
+| **Session persistence** | Auto-save/restore cookies + localStorage by name | `--session-name <name>` / `AGENT_BROWSER_SESSION_NAME` |
+| **Import from your browser** | Grab auth from a Chrome session you already logged into | `--auto-connect` + `state save` |
+| **State file** | Load a previously saved state JSON on launch | `--state <path>` / `AGENT_BROWSER_STATE` |
+| **Auth vault** | Store credentials locally (encrypted), login by name | `auth save` / `auth login` |
+
+### Import auth from your browser
+
+If you are already logged in to a site in Chrome, you can grab that auth state and reuse it:
+
+```bash
+# 1. Launch Chrome with remote debugging enabled
+#    macOS:
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
+#    Or use --auto-connect to discover an already-running Chrome
+
+# 2. Connect and save the authenticated state
+agent-browser --auto-connect state save ./my-auth.json
+
+# 3. Use the saved auth in future sessions
+agent-browser --state ./my-auth.json open https://app.example.com/dashboard
+
+# 4. Or use --session-name for automatic persistence
+agent-browser --session-name myapp state load ./my-auth.json
+# From now on, --session-name myapp auto-saves/restores this state
+```
+
+> **Security notes:**
+> - `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect. Only use on trusted machines and close Chrome when done.
+> - State files contain session tokens in plaintext. Add them to `.gitignore` and delete when no longer needed. For encryption at rest, set `AGENT_BROWSER_ENCRYPTION_KEY` (see [State Encryption](#state-encryption)).
+
+For full details on login flows, OAuth, 2FA, cookie-based auth, and the auth vault, see the [Authentication](docs/src/app/sessions/page.mdx) docs.
+
 ## Sessions
 
 Run multiple isolated browser instances:
@@ -415,7 +458,7 @@ agent-browser includes security features for safe AI agent deployments. All feat
 | `AGENT_BROWSER_CONFIRM_ACTIONS` | Action categories requiring confirmation |
 | `AGENT_BROWSER_CONFIRM_INTERACTIVE` | Enable interactive confirmation prompts |
 
-See [Security documentation](https://agent-browser.vercel.app/security) for details.
+See [Security documentation](https://agent-browser.dev/security) for details.
 
 ## Snapshot Options
 
@@ -445,6 +488,8 @@ 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`.
+
 ```bash
 agent-browser screenshot --annotate
 # -> Screenshot saved to /tmp/screenshot-2026-02-17T12-00-00-abc123.png
@@ -713,7 +758,22 @@ agent-browser --executable-path /path/to/chromium open example.com
 AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com
 ```
 
-### Serverless Example (Vercel/AWS Lambda)
+### Serverless (Vercel)
+
+Run agent-browser + Chrome in an ephemeral Vercel Sandbox microVM. No external server needed:
+
+```typescript
+import { Sandbox } from "@vercel/sandbox";
+
+const sandbox = await Sandbox.create({ runtime: "node24" });
+await sandbox.runCommand("agent-browser", ["open", "https://example.com"]);
+const result = await sandbox.runCommand("agent-browser", ["screenshot", "--json"]);
+await sandbox.stop();
+```
+
+See the [environments example](examples/environments/) for a working demo with a UI and deploy-to-Vercel button.
+
+### Serverless (AWS Lambda)
 
 ```typescript
 import chromium from '@sparticuz/chromium';
@@ -1119,7 +1179,6 @@ To enable Browserbase, use the `-p` flag:
 
 ```bash
 export BROWSERBASE_API_KEY="your-api-key"
-export BROWSERBASE_PROJECT_ID="your-project-id"
 agent-browser -p browserbase open https://example.com
 ```
 
@@ -1128,13 +1187,12 @@ Or use environment variables for CI/scripts:
 ```bash
 export AGENT_BROWSER_PROVIDER=browserbase
 export BROWSERBASE_API_KEY="your-api-key"
-export BROWSERBASE_PROJECT_ID="your-project-id"
 agent-browser open https://example.com
 ```
 
 When enabled, agent-browser connects to a Browserbase session instead of launching a local browser. All commands work identically.
 
-Get your API key and project ID from the [Browserbase Dashboard](https://browserbase.com/overview).
+Get your API key from the [Browserbase Dashboard](https://browserbase.com/overview).
 
 ### Browser Use
 

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAqBpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAsIT,MAAM,YAAY,CAAC;AAQpB;;;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;AAKD,wBAAgB,gBAAgB,IAAI,IAAI,CAuBvC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6CjG"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAqBpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAsIT,MAAM,YAAY,CAAC;AAQpB;;;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;AAKD,wBAAgB,gBAAgB,IAAI,IAAI,CAuBvC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6CjG"}

package/dist/actions.js

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { exec } from 'node:child_process';
 import { mkdirSync } from 'node:fs';
 import { getAppDir } from './daemon.js';
 import { checkPolicy, describeAction, getActionCategory, loadPolicyFile, initPolicyReloader, reloadPolicyIfChanged, } from './action-policy.js';
@@ -229,6 +230,10 @@ async function dispatchAction(command, browser) {
             return await handleReload(command, browser);
         case 'url':
             return await handleUrl(command, browser);
+        case 'cdp_url':
+            return handleCdpUrl(command, browser);
+        case 'inspect':
+            return await handleInspect(command, browser);
         case 'title':
             return await handleTitle(command, browser);
         case 'getattribute':
@@ -1065,11 +1070,29 @@ async function handlePermissions(command, browser) {
     });
 }
 async function handleViewport(command, browser) {
-    await browser.setViewport(command.width, command.height);
-    return successResponse(command.id, {
+    if (command.deviceScaleFactor && command.deviceScaleFactor !== 1) {
+        await browser.setViewport(command.width, command.height);
+        await browser.setDeviceScaleFactor(command.deviceScaleFactor, command.width, command.height, false);
+    }
+    else {
+        // deviceScaleFactor is 1 or undefined -- clear any previously-set CDP
+        // Emulation.setDeviceMetricsOverride so stale DPR doesn't persist.
+        try {
+            await browser.clearDeviceMetricsOverride();
+        }
+        catch {
+            // Ignore if override was never set
+        }
+        await browser.setViewport(command.width, command.height);
+    }
+    const result = {
         width: command.width,
         height: command.height,
-    });
+    };
+    if (command.deviceScaleFactor !== undefined) {
+        result.deviceScaleFactor = command.deviceScaleFactor;
+    }
+    return successResponse(command.id, result);
 }
 async function handleUserAgent(command, browser) {
     const page = browser.getPage();
@@ -1127,6 +1150,62 @@ async function handleUrl(command, browser) {
     const page = browser.getPage();
     return successResponse(command.id, { url: page.url() });
 }
+function handleCdpUrl(command, browser) {
+    const cdpUrl = browser.getCdpUrl();
+    if (!cdpUrl) {
+        return errorResponse(command.id, 'CDP URL not available (browser may not be launched)');
+    }
+    return successResponse(command.id, { cdpUrl });
+}
+async function handleInspect(command, browser) {
+    const cdpUrl = browser.getCdpUrl();
+    if (!cdpUrl) {
+        return errorResponse(command.id, 'CDP URL not available (browser may not be launched)');
+    }
+    // Shut down any existing inspect server so we always target the current page
+    browser.stopInspectServer();
+    const stripped = cdpUrl.replace(/^(wss?|https?):\/\//, '');
+    const hostPort = stripped.split('/')[0];
+    // Get the target ID so the inspect server can create its own dedicated CDP session
+    const page = browser.getPage();
+    const context = page.context();
+    const tmpCdp = await context.newCDPSession(page);
+    let targetId = '';
+    try {
+        const info = await tmpCdp.send('Target.getTargetInfo');
+        targetId = info?.targetInfo?.targetId || '';
+    }
+    catch (err) {
+        console.error('[inspect] getTargetInfo failed:', err);
+    }
+    await tmpCdp.detach();
+    if (!targetId) {
+        return errorResponse(command.id, 'Could not determine target ID for active page');
+    }
+    const { InspectServer } = await import('./inspect-server.js');
+    const server = new InspectServer({
+        chromeHostPort: hostPort,
+        targetId,
+        chromeWsUrl: cdpUrl,
+    });
+    await server.start();
+    browser.setInspectServer(server);
+    const url = `http://127.0.0.1:${server.port}`;
+    openUrlInBrowser(url);
+    return successResponse(command.id, { opened: true, url });
+}
+function openUrlInBrowser(url) {
+    const platform = process.platform;
+    const cmd = platform === 'darwin'
+        ? `open "${url}"`
+        : platform === 'win32'
+            ? `start "" "${url}"`
+            : `xdg-open "${url}"`;
+    exec(cmd, (err) => {
+        if (err)
+            console.error('[inspect] Failed to open browser:', err.message);
+    });
+}
 async function handleTitle(command, browser) {
     const page = browser.getPage();
     const title = await page.title();
@@ -1141,7 +1220,8 @@ async function handleGetAttribute(command, browser) {
 async function handleGetText(command, browser) {
     const page = browser.getPage();
     const locator = browser.getLocator(command.selector);
-    const text = await locator.textContent();
+    const inner = await locator.innerText();
+    const text = inner || (await locator.textContent()) || '';
     return successResponse(command.id, { text, origin: page.url() });
 }
 async function handleIsVisible(command, browser) {