feat: add session state management vercel-labs/agent-browser #42

[amannhq]

This PR implements session persistence with automatic state save/restore, encryption support, and comprehensive state management commands.

Resolves #42
Resolves #86

New Features

1. Session Persistence (--session-name)

Automatically save and restore cookies/localStorage across browser restarts:

# 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/

#### 2. State Encryption (AES-256-GCM)

Encrypt sensitive session data at rest:

```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

3. State Management Commands

Command	Description
state list	List saved state files with size, date, encryption status
state show <file>	Show state summary (cookies, origins, domains)
state rename <old> <new>	Rename a state file
state clear <session>	Clear states for a specific session name
state clear --all	Clear all saved states
state clean --older-than <days>	Delete states older than N days
state save <path>	Manual save to custom path
state load <path>	Manual load from custom path

4. Auto-Expiration

Automatically clean up old state files:

export AGENT_BROWSER_STATE_EXPIRE_DAYS=7  # Default: 30

# Or manually clean old states
agent-browser state clean --older-than 7

#### 5. Session Name Validation

Security hardening to prevent path traversal attacks:
- Only alphanumeric, hyphens, underscores allowed
- Rejects `../`, spaces, slashes, special characters

---

### Environment Variables

| 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) |
---

[vercel]

@amannhq is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[ctate]

Feature looks good but has compilation issues (missing types: ScreencastFrame, StreamServer, extensions property) - can you plz take a look?

[amannhq]

Feature looks good but has compilation issues (missing types: ScreencastFrame, StreamServer, extensions property) - can you plz take a look?

ok checking it

[pavelklymenko]

@amannhq will it also address [#115]?(#115)

[amannhq]

@amannhq will it also address [#115]?(#115)

This functionality already exists via the --session-name flag.

Working Solution

# 1. Login in headed mode
agent-browser --session-name goofish open https://www.goofish.com/ --headed
# ... login manually ...
agent-browser close  # Auto-saves auth

# 2. Headless automation - still logged in!
agent-browser --session-name goofish open https://www.goofish.com/
agent-browser snapshot  # See authenticated content

Feature that was propsed

agent-browser state load auth.json --headed  # Won't work

• state load requires a browser to already be running
• --headed is not a valid flag for state load

How --session-name Works

When	What Happens
On close	Auto-saves cookies, localStorage, sessionStorage to ~/.agent-browser/sessions/{name}-default.json
On next open	Auto-loads saved state

No manual state save/load needed.

Note on Mode Switching

You can't toggle headed/headless on a running browser (Playwright limitation). But with --session-name:

1. Close headed (auto-saves)
2. Reopen headless (auto-loads)
3. Auth preserved!

Optional: Encryption

For sensitive logins (banking, etc.), encrypt your session files with AES-256-GCM:

# Generate a 64-character hex key (32 bytes)
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)

# Now all session files are encrypted automatically
agent-browser --session-name banking open https://mybank.com --headed

Session file is saved to the same location (~/.agent-browser/sessions/) but contents are encrypted and unreadable without the key.

[amannhq]

@ctate closing this PR added a new pr with all the fixes
Please check PR #184