24860ec3f1
Update SKILL.md to match the latest upstream skill from vercel-labs/agent-browser, adding substantial new capabilities: - Authentication (auth vault, profiles, session persistence, state files) - Command chaining, annotated screenshots, diffing - Security features (content boundaries, domain allowlist, action policy) - iOS Simulator support, Lightpanda engine, downloads, clipboard - JS eval improvements (--stdin, -b for shell safety) - Timeout guidance, config files, session cleanup Add 7 reference docs (commands, authentication, snapshot-refs, session-management, video-recording, profiling, proxy-support) and 3 ready-to-use shell templates. Kept our YAML frontmatter, setup check section, and Playwright MCP comparison table which are unique to our plugin context.
194 lines
4.2 KiB
Markdown
194 lines
4.2 KiB
Markdown
# Session Management
|
|
|
|
Multiple isolated browser sessions with state persistence and concurrent browsing.
|
|
|
|
**Related**: [authentication.md](authentication.md) for login patterns, [SKILL.md](../SKILL.md) for quick start.
|
|
|
|
## Contents
|
|
|
|
- [Named Sessions](#named-sessions)
|
|
- [Session Isolation Properties](#session-isolation-properties)
|
|
- [Session State Persistence](#session-state-persistence)
|
|
- [Common Patterns](#common-patterns)
|
|
- [Default Session](#default-session)
|
|
- [Session Cleanup](#session-cleanup)
|
|
- [Best Practices](#best-practices)
|
|
|
|
## Named Sessions
|
|
|
|
Use `--session` flag to isolate browser contexts:
|
|
|
|
```bash
|
|
# Session 1: Authentication flow
|
|
agent-browser --session auth open https://app.example.com/login
|
|
|
|
# Session 2: Public browsing (separate cookies, storage)
|
|
agent-browser --session public open https://example.com
|
|
|
|
# Commands are isolated by session
|
|
agent-browser --session auth fill @e1 "user@example.com"
|
|
agent-browser --session public get text body
|
|
```
|
|
|
|
## Session Isolation Properties
|
|
|
|
Each session has independent:
|
|
- Cookies
|
|
- LocalStorage / SessionStorage
|
|
- IndexedDB
|
|
- Cache
|
|
- Browsing history
|
|
- Open tabs
|
|
|
|
## Session State Persistence
|
|
|
|
### Save Session State
|
|
|
|
```bash
|
|
# Save cookies, storage, and auth state
|
|
agent-browser state save /path/to/auth-state.json
|
|
```
|
|
|
|
### Load Session State
|
|
|
|
```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
|
|
```
|
|
|
|
### State File Contents
|
|
|
|
```json
|
|
{
|
|
"cookies": [...],
|
|
"localStorage": {...},
|
|
"sessionStorage": {...},
|
|
"origins": [...]
|
|
}
|
|
```
|
|
|
|
## 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
|
|
```
|
|
|
|
### Concurrent Scraping
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Scrape multiple sites concurrently
|
|
|
|
# Start all sessions
|
|
agent-browser --session site1 open https://site1.com &
|
|
agent-browser --session site2 open https://site2.com &
|
|
agent-browser --session site3 open https://site3.com &
|
|
wait
|
|
|
|
# Extract from each
|
|
agent-browser --session site1 get text body > site1.txt
|
|
agent-browser --session site2 get text body > site2.txt
|
|
agent-browser --session site3 get text body > site3.txt
|
|
|
|
# Cleanup
|
|
agent-browser --session site1 close
|
|
agent-browser --session site2 close
|
|
agent-browser --session site3 close
|
|
```
|
|
|
|
### A/B Testing Sessions
|
|
|
|
```bash
|
|
# Test different user experiences
|
|
agent-browser --session variant-a open "https://app.com?variant=a"
|
|
agent-browser --session variant-b open "https://app.com?variant=b"
|
|
|
|
# Compare
|
|
agent-browser --session variant-a screenshot /tmp/variant-a.png
|
|
agent-browser --session variant-b screenshot /tmp/variant-b.png
|
|
```
|
|
|
|
## Default Session
|
|
|
|
When `--session` is omitted, commands use the default session:
|
|
|
|
```bash
|
|
# These use the same default session
|
|
agent-browser open https://example.com
|
|
agent-browser snapshot -i
|
|
agent-browser close # Closes default session
|
|
```
|
|
|
|
## Session Cleanup
|
|
|
|
```bash
|
|
# Close specific session
|
|
agent-browser --session auth close
|
|
|
|
# List active sessions
|
|
agent-browser session list
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 1. Name Sessions Semantically
|
|
|
|
```bash
|
|
# GOOD: Clear purpose
|
|
agent-browser --session github-auth open https://github.com
|
|
agent-browser --session docs-scrape open https://docs.example.com
|
|
|
|
# AVOID: Generic names
|
|
agent-browser --session s1 open https://github.com
|
|
```
|
|
|
|
### 2. Always Clean Up
|
|
|
|
```bash
|
|
# Close sessions when done
|
|
agent-browser --session auth close
|
|
agent-browser --session scrape close
|
|
```
|
|
|
|
### 3. Handle State Files Securely
|
|
|
|
```bash
|
|
# Don't commit state files (contain auth tokens!)
|
|
echo "*.auth-state.json" >> .gitignore
|
|
|
|
# Delete after use
|
|
rm /tmp/auth-state.json
|
|
```
|
|
|
|
### 4. Timeout Long Sessions
|
|
|
|
```bash
|
|
# Set timeout for automated scripts
|
|
timeout 60 agent-browser --session long-task get text body
|
|
```
|