agent-browser 0.30.1 → 0.31.0

package/README.md

@@ -557,7 +557,7 @@ agent-browser provides multiple ways to persist login sessions so you don't re-a
 |----------|----------|------------|
 | **Chrome profile reuse** | Reuse your existing Chrome login state (cookies, sessions) with zero setup | `--profile <name>` / `AGENT_BROWSER_PROFILE` |
 | **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` |
+| **Session persistence** | Auto-save/restore cookies + localStorage from a stable session key | `--session <id> --restore` / `AGENT_BROWSER_RESTORE` |
 | **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` |
@@ -578,9 +578,10 @@ 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
+# 4. Or use --restore for automatic persistence
+SESSION="$(agent-browser session id --scope worktree --prefix myapp)"
+agent-browser --session "$SESSION" --restore --state ./my-auth.json open https://app.example.com/dashboard
+# From now on, --session "$SESSION" --restore auto-saves/restores this state
 ```
 
 > **Security notes:**
@@ -610,6 +611,12 @@ agent-browser session list
 
 # Show current session
 agent-browser session
+
+# Generate a stable worktree-scoped session id
+agent-browser session id --scope worktree --prefix next-dev-loop
+
+# Inspect daemon, launch, and restore status
+agent-browser session info --json
 ```
 
 Each session has its own:
@@ -668,18 +675,18 @@ The profile directory stores:
 
 ## Session Persistence
 
-Alternatively, use `--session-name` to automatically save and restore cookies and localStorage across browser restarts:
+Use `--restore` with a stable `--session` 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
+# Generate a stable id for this worktree and auto-save/load state
+SESSION="$(agent-browser session id --scope worktree --prefix twitter)"
+agent-browser --session "$SESSION" --restore 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
+# Optional: validate restored state before auto-saving again
+agent-browser --session "$SESSION" --restore --restore-check-text Dashboard open twitter.com
 ```
 
 ### State Encryption
@@ -691,12 +698,15 @@ Encrypt saved session data at rest with AES-256-GCM:
 export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key>
 
 # State files are now encrypted automatically
-agent-browser --session-name secure open example.com
+agent-browser --session secure --restore open example.com
 ```
 
 | Variable                          | Description                                        |
 | --------------------------------- | -------------------------------------------------- |
-| `AGENT_BROWSER_SESSION_NAME`      | Auto-save/load state persistence name              |
+| `AGENT_BROWSER_RESTORE`           | Auto-save/load state persistence name              |
+| `AGENT_BROWSER_RESTORE_SAVE`      | Restore save policy: `auto`, `always`, or `never`  |
+| `AGENT_BROWSER_NAMESPACE`         | Namespace for daemon sockets and restore state     |
+| `AGENT_BROWSER_SESSION_NAME`      | Legacy 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) |
 
@@ -861,7 +871,13 @@ This is useful for multimodal AI models that can reason about visual layout, unl
 | 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) |
+| `--restore [name]` | Auto-save/restore session state. Bare `--restore` uses `--session` as the key |
+| `--restore-save <policy>` | Restore save policy: `auto`, `always`, or `never` |
+| `--restore-check-url <glob>` | Validate restored state against a URL pattern |
+| `--restore-check-text <text>` | Validate restored state against page text |
+| `--restore-check-fn <js>` | Validate restored state against a truthy JavaScript expression |
+| `--namespace <name>` | Isolate daemon sockets and restore-state directories |
+| `--session-name <name>` | Legacy alias for restore persistence key |
 | `--profile <name\|path>` | Chrome profile name or persistent directory path (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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-browser",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "engines": {

package/skill-data/core/SKILL.md

@@ -221,18 +221,18 @@ agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url"
 ### Persist session across runs
 
 ```bash
-# Log in once, save cookies + localStorage
-agent-browser state save ./auth.json
+# Derive one stable id for this agent/worktree
+SESSION="$(agent-browser session id --scope worktree --prefix my-app)"
 
-# Later runs start already-logged-in
-agent-browser --state ./auth.json open https://app.example.com
+# Pass the same id and restore request on every command
+agent-browser --session "$SESSION" --restore open https://app.example.com
 ```
 
-Or use `--session-name` for auto-save/restore:
+`--restore` with no value uses the current `--session` as the persistence key. Agent skills should prefer this over hand-built state file paths. Use `--restore-save auto` by default so a failed restore does not overwrite the previous known-good state.
 
 ```bash
-AGENT_BROWSER_SESSION_NAME=my-app agent-browser open https://app.example.com
-# State is auto-saved and restored on subsequent runs with the same name.
+agent-browser --session "$SESSION" --restore --restore-check-text Dashboard open https://app.example.com
+agent-browser --session "$SESSION" session info --json
 ```
 
 ### Extract data
@@ -284,7 +284,7 @@ Stable `tabId`s mean `t2` points at the same tab across commands even when other
 
 ### Run multiple browsers in parallel
 
-Each `--session <name>` is an isolated browser with its own cookies, tabs, and refs. Useful for testing multi-user flows or parallel scraping:
+Each `--session <name>` is an isolated browser with its own cookies, tabs, and refs. For agent skills, derive stable names with `agent-browser session id --scope worktree --prefix <skill>`. Useful for testing multi-user flows or parallel scraping:
 
 ```bash
 agent-browser --session a open https://app.example.com
@@ -400,7 +400,7 @@ EOF
 
 **Cross-origin iframe not accessible** Cross-origin iframes that block accessibility tree access are silently skipped. Use `frame "#iframe"` to switch into them explicitly if the parent opts in, otherwise the iframe's contents aren't available via snapshot — fall back to `eval` in the iframe's origin or use the `--headers` flag to satisfy CORS.
 
-**Authentication expires mid-workflow** Use `--session-name <name>` or `state save`/`state load` so your session survives browser restarts. See [references/session-management.md](references/session-management.md) and [references/authentication.md](references/authentication.md).
+**Authentication expires mid-workflow** Use `--session <id> --restore` so your session survives browser restarts. Check `agent-browser session info --json` if restore fails. See [references/session-management.md](references/session-management.md) and [references/authentication.md](references/authentication.md).
 
 ## Global flags worth knowing
 
@@ -414,7 +414,9 @@ EOF
 --headers <json>        # HTTP headers scoped to the URL's origin
 --proxy <url>           # proxy server
 --state <path>          # load saved auth state from JSON
---session-name <name>   # auto-save/restore session state by name
+--restore [name]        # auto-save/restore session state, defaults to --session
+--restore-save <policy> # auto, always, or never
+--namespace <name>      # isolate daemon sockets and restore-state directories
 ```
 
 ## When to load another skill

package/skill-data/core/references/authentication.md

@@ -54,20 +54,22 @@ agent-browser --auto-connect state save ./my-auth.json
 # Load auth at launch
 agent-browser --state ./my-auth.json open https://app.example.com/dashboard
 
-# Or load into an existing session
+# Or load into an already-launched session
+agent-browser open about:blank
 agent-browser state load ./my-auth.json
 agent-browser open https://app.example.com/dashboard
 ```
 
-This works for any site, including those with complex OAuth flows, SSO, or 2FA -- as long as Chrome already has valid session cookies.
+This works for any site, including those with complex OAuth flows, SSO, or 2FA, as long as Chrome already has valid session cookies.
 
 > **Security note:** State files contain session tokens in plaintext. Add them to `.gitignore`, delete when no longer needed, and set `AGENT_BROWSER_ENCRYPTION_KEY` for encryption at rest. See [Security Best Practices](#security-best-practices).
 
-**Tip:** Combine with `--session-name` so the imported auth auto-persists across restarts:
+**Tip:** Combine with `--session <id> --restore` so the imported auth auto-persists across restarts:
 
 ```bash
-agent-browser --session-name myapp state load ./my-auth.json
-# From now on, state is auto-saved/restored for "myapp"
+SESSION="$(agent-browser session id --scope worktree --prefix myapp)"
+agent-browser --session "$SESSION" --restore --state ./my-auth.json open https://app.example.com/dashboard
+# From now on, state is auto-saved/restored for this session
 ```
 
 ## Persistent Profiles
@@ -99,23 +101,24 @@ agent-browser open https://app.example.com/dashboard
 
 ## Session Persistence
 
-Use `--session-name` to auto-save and restore cookies + localStorage by name, without managing files:
+Use `--restore` with a stable `--session` to auto-save and restore cookies + localStorage without managing files:
 
 ```bash
 # Auto-saves state on close, auto-restores on next launch
-agent-browser --session-name twitter open https://twitter.com
+SESSION="$(agent-browser session id --scope worktree --prefix twitter)"
+agent-browser --session "$SESSION" --restore open https://twitter.com
 # ... login flow ...
-agent-browser close  # state saved to ~/.agent-browser/sessions/
+agent-browser --session "$SESSION" --restore close  # state saved to ~/.agent-browser/sessions/
 
 # Next time: state is automatically restored
-agent-browser --session-name twitter open https://twitter.com
+agent-browser --session "$SESSION" --restore open https://twitter.com
 ```
 
 Encrypt state at rest:
 
 ```bash
 export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
-agent-browser --session-name secure open https://app.example.com
+agent-browser --session secure --restore open https://app.example.com
 ```
 
 ## Basic Login Flow

package/skill-data/core/references/session-management.md

@@ -16,7 +16,14 @@ Multiple isolated browser sessions with state persistence and concurrent browsin
 
 ## Named Sessions
 
-Use `--session` flag to isolate browser contexts:
+Use `--session` to isolate browser contexts. Agent skills should derive one stable id and reuse it on every command:
+
+```bash
+SESSION="$(agent-browser session id --scope worktree --prefix my-skill)"
+agent-browser --session "$SESSION" --restore open https://app.example.com/login
+```
+
+`--scope worktree` uses the Git worktree root when available, then the Git root, then the canonical current directory. This is the recommended default for agents because worktrees are commonly used for parallel agent runs.
 
 ```bash
 # Session 1: Authentication flow
@@ -42,60 +49,40 @@ Each session has independent:
 
 ## Session State Persistence
 
-### Save Session State
+### Automatic Restore
 
 ```bash
-# Save cookies, storage, and auth state
-agent-browser state save /path/to/auth-state.json
+# Bare --restore uses the current --session as the persistence key
+SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)"
+agent-browser --session "$SESSION" --restore open https://app.example.com/dashboard
 ```
 
-### Load Session State
+State is loaded before navigation and saved on close, daemon shutdown, idle timeout, and compatible relaunch. The default save policy is `--restore-save auto`, which skips auto-save if restore failed or validation failed.
 
 ```bash
-# Restore saved state
-agent-browser state load /path/to/auth-state.json
-
-# Continue with authenticated session
-agent-browser open https://app.example.com/dashboard
+agent-browser --session "$SESSION" --restore --restore-check-url "**/dashboard" open https://app.example.com/dashboard
+agent-browser --session "$SESSION" --restore --restore-check-text Dashboard open https://app.example.com/dashboard
+agent-browser --session "$SESSION" --restore --restore-check-fn "!!localStorage.getItem('session')" open https://app.example.com/dashboard
 ```
 
-### State File Contents
+Use `agent-browser session info --json` for diagnostics:
 
-```json
-{
-  "cookies": [...],
-  "localStorage": {...},
-  "sessionStorage": {...},
-  "origins": [...]
-}
+```bash
+agent-browser --session "$SESSION" session info --json
 ```
 
+### Manual State Files
+
+Use `state save`, `state load`, and `--state <path>` when you need an explicit portable JSON file. Do not make agents construct paths under `~/.agent-browser/sessions/`; prefer `--restore` for reusable agent sessions.
+
 ## Common Patterns
 
 ### Authenticated Session Reuse
 
 ```bash
 #!/bin/bash
-# Save login state once, reuse many times
-
-STATE_FILE="/tmp/auth-state.json"
-
-# Check if we have saved state
-if [[ -f "$STATE_FILE" ]]; then
-    agent-browser state load "$STATE_FILE"
-    agent-browser open https://app.example.com/dashboard
-else
-    # Perform login
-    agent-browser open https://app.example.com/login
-    agent-browser snapshot -i
-    agent-browser fill @e1 "$USERNAME"
-    agent-browser fill @e2 "$PASSWORD"
-    agent-browser click @e3
-    agent-browser wait --load networkidle
-
-    # Save for future use
-    agent-browser state save "$STATE_FILE"
-fi
+SESSION="$(agent-browser session id --scope worktree --prefix app)"
+agent-browser --session "$SESSION" --restore open https://app.example.com/dashboard
 ```
 
 ### Concurrent Scraping