agent-browser 0.6.0 → 0.7.2

package/skills/agent-browser/references/session-management.md

@@ -0,0 +1,181 @@
+# Session Management
+
+Run multiple isolated browser sessions concurrently with state persistence.
+
+## 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
+```

package/skills/agent-browser/references/snapshot-refs.md

@@ -0,0 +1,186 @@
+# Snapshot + Refs Workflow
+
+The core innovation of agent-browser: compact element references that reduce context usage dramatically for AI agents.
+
+## How It Works
+
+### The Problem
+Traditional browser automation sends full DOM to AI agents:
+```
+Full DOM/HTML sent → AI parses → Generates CSS selector → Executes action
+~3000-5000 tokens per interaction
+```
+
+### The Solution
+agent-browser uses compact snapshots with refs:
+```
+Compact snapshot → @refs assigned → Direct ref interaction
+~200-400 tokens per interaction
+```
+
+## The Snapshot Command
+
+```bash
+# Basic snapshot (shows page structure)
+agent-browser snapshot
+
+# Interactive snapshot (-i flag) - RECOMMENDED
+agent-browser snapshot -i
+```
+
+### Snapshot Output Format
+
+```
+Page: Example Site - Home
+URL: https://example.com
+
+@e1 [header]
+  @e2 [nav]
+    @e3 [a] "Home"
+    @e4 [a] "Products"
+    @e5 [a] "About"
+  @e6 [button] "Sign In"
+
+@e7 [main]
+  @e8 [h1] "Welcome"
+  @e9 [form]
+    @e10 [input type="email"] placeholder="Email"
+    @e11 [input type="password"] placeholder="Password"
+    @e12 [button type="submit"] "Log In"
+
+@e13 [footer]
+  @e14 [a] "Privacy Policy"
+```
+
+## Using Refs
+
+Once you have refs, interact directly:
+
+```bash
+# Click the "Sign In" button
+agent-browser click @e6
+
+# Fill email input
+agent-browser fill @e10 "user@example.com"
+
+# Fill password
+agent-browser fill @e11 "password123"
+
+# Submit the form
+agent-browser click @e12
+```
+
+## Ref Lifecycle
+
+**IMPORTANT**: Refs are invalidated when the page changes!
+
+```bash
+# Get initial snapshot
+agent-browser snapshot -i
+# @e1 [button] "Next"
+
+# Click triggers page change
+agent-browser click @e1
+
+# MUST re-snapshot to get new refs!
+agent-browser snapshot -i
+# @e1 [h1] "Page 2"  ← Different element now!
+```
+
+## Best Practices
+
+### 1. Always Snapshot Before Interacting
+
+```bash
+# CORRECT
+agent-browser open https://example.com
+agent-browser snapshot -i          # Get refs first
+agent-browser click @e1            # Use ref
+
+# WRONG
+agent-browser open https://example.com
+agent-browser click @e1            # Ref doesn't exist yet!
+```
+
+### 2. Re-Snapshot After Navigation
+
+```bash
+agent-browser click @e5            # Navigates to new page
+agent-browser snapshot -i          # Get new refs
+agent-browser click @e1            # Use new refs
+```
+
+### 3. Re-Snapshot After Dynamic Changes
+
+```bash
+agent-browser click @e1            # Opens dropdown
+agent-browser snapshot -i          # See dropdown items
+agent-browser click @e7            # Select item
+```
+
+### 4. Snapshot Specific Regions
+
+For complex pages, snapshot specific areas:
+
+```bash
+# Snapshot just the form
+agent-browser snapshot @e9
+```
+
+## Ref Notation Details
+
+```
+@e1 [tag type="value"] "text content" placeholder="hint"
+│    │   │             │               │
+│    │   │             │               └─ Additional attributes
+│    │   │             └─ Visible text
+│    │   └─ Key attributes shown
+│    └─ HTML tag name
+└─ Unique ref ID
+```
+
+### Common Patterns
+
+```
+@e1 [button] "Submit"                    # Button with text
+@e2 [input type="email"]                 # Email input
+@e3 [input type="password"]              # Password input
+@e4 [a href="/page"] "Link Text"         # Anchor link
+@e5 [select]                             # Dropdown
+@e6 [textarea] placeholder="Message"     # Text area
+@e7 [div class="modal"]                  # Container (when relevant)
+@e8 [img alt="Logo"]                     # Image
+@e9 [checkbox] checked                   # Checked checkbox
+@e10 [radio] selected                    # Selected radio
+```
+
+## Troubleshooting
+
+### "Ref not found" Error
+
+```bash
+# Ref may have changed - re-snapshot
+agent-browser snapshot -i
+```
+
+### Element Not Visible in Snapshot
+
+```bash
+# Scroll to reveal element
+agent-browser scroll --bottom
+agent-browser snapshot -i
+
+# Or wait for dynamic content
+agent-browser wait 1000
+agent-browser snapshot -i
+```
+
+### Too Many Elements
+
+```bash
+# Snapshot specific container
+agent-browser snapshot @e5
+
+# Or use get text for content-only extraction
+agent-browser get text @e5
+```

package/skills/agent-browser/references/video-recording.md

@@ -0,0 +1,162 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification.
+
+## Basic Recording
+
+```bash
+# Start recording
+agent-browser record start ./demo.webm
+
+# Perform actions
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser click @e1
+agent-browser fill @e2 "test input"
+
+# Stop and save
+agent-browser record stop
+```
+
+## Recording Commands
+
+```bash
+# Start recording to file
+agent-browser record start ./output.webm
+
+# Stop current recording
+agent-browser record stop
+
+# Restart with new file (stops current + starts new)
+agent-browser record restart ./take2.webm
+```
+
+## Use Cases
+
+### Debugging Failed Automation
+
+```bash
+#!/bin/bash
+# Record automation for debugging
+
+agent-browser record start ./debug-$(date +%Y%m%d-%H%M%S).webm
+
+# Run your automation
+agent-browser open https://app.example.com
+agent-browser snapshot -i
+agent-browser click @e1 || {
+    echo "Click failed - check recording"
+    agent-browser record stop
+    exit 1
+}
+
+agent-browser record stop
+```
+
+### Documentation Generation
+
+```bash
+#!/bin/bash
+# Record workflow for documentation
+
+agent-browser record start ./docs/how-to-login.webm
+
+agent-browser open https://app.example.com/login
+agent-browser wait 1000  # Pause for visibility
+
+agent-browser snapshot -i
+agent-browser fill @e1 "demo@example.com"
+agent-browser wait 500
+
+agent-browser fill @e2 "password"
+agent-browser wait 500
+
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser wait 1000  # Show result
+
+agent-browser record stop
+```
+
+### CI/CD Test Evidence
+
+```bash
+#!/bin/bash
+# Record E2E test runs for CI artifacts
+
+TEST_NAME="${1:-e2e-test}"
+RECORDING_DIR="./test-recordings"
+mkdir -p "$RECORDING_DIR"
+
+agent-browser record start "$RECORDING_DIR/$TEST_NAME-$(date +%s).webm"
+
+# Run test
+if run_e2e_test; then
+    echo "Test passed"
+else
+    echo "Test failed - recording saved"
+fi
+
+agent-browser record stop
+```
+
+## Best Practices
+
+### 1. Add Pauses for Clarity
+
+```bash
+# Slow down for human viewing
+agent-browser click @e1
+agent-browser wait 500  # Let viewer see result
+```
+
+### 2. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+agent-browser record start ./recordings/login-flow-2024-01-15.webm
+agent-browser record start ./recordings/checkout-test-run-42.webm
+```
+
+### 3. Handle Recording in Error Cases
+
+```bash
+#!/bin/bash
+set -e
+
+cleanup() {
+    agent-browser record stop 2>/dev/null || true
+    agent-browser close 2>/dev/null || true
+}
+trap cleanup EXIT
+
+agent-browser record start ./automation.webm
+# ... automation steps ...
+```
+
+### 4. Combine with Screenshots
+
+```bash
+# Record video AND capture key frames
+agent-browser record start ./flow.webm
+
+agent-browser open https://example.com
+agent-browser screenshot ./screenshots/step1-homepage.png
+
+agent-browser click @e1
+agent-browser screenshot ./screenshots/step2-after-click.png
+
+agent-browser record stop
+```
+
+## Output Format
+
+- Default format: WebM (VP8/VP9 codec)
+- Compatible with all modern browsers and video players
+- Compressed but high quality
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space
+- Some headless environments may have codec limitations

package/skills/agent-browser/templates/authenticated-session.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# Template: Authenticated Session Workflow
+# Login once, save state, reuse for subsequent runs
+#
+# Usage:
+#   ./authenticated-session.sh <login-url> [state-file]
+#
+# Setup:
+#   1. Run once to see your form structure
+#   2. Note the @refs for your fields
+#   3. Uncomment LOGIN FLOW section and update refs
+
+set -euo pipefail
+
+LOGIN_URL="${1:?Usage: $0 <login-url> [state-file]}"
+STATE_FILE="${2:-./auth-state.json}"
+
+echo "Authentication workflow for: $LOGIN_URL"
+
+# ══════════════════════════════════════════════════════════════
+# SAVED STATE: Skip login if we have valid saved state
+# ══════════════════════════════════════════════════════════════
+if [[ -f "$STATE_FILE" ]]; then
+    echo "Loading saved authentication state..."
+    agent-browser state load "$STATE_FILE"
+    agent-browser open "$LOGIN_URL"
+    agent-browser wait --load networkidle
+
+    CURRENT_URL=$(agent-browser get url)
+    if [[ "$CURRENT_URL" != *"login"* ]] && [[ "$CURRENT_URL" != *"signin"* ]]; then
+        echo "Session restored successfully!"
+        agent-browser snapshot -i
+        exit 0
+    fi
+    echo "Session expired, performing fresh login..."
+    rm -f "$STATE_FILE"
+fi
+
+# ══════════════════════════════════════════════════════════════
+# DISCOVERY MODE: Show form structure (remove after setup)
+# ══════════════════════════════════════════════════════════════
+echo "Opening login page..."
+agent-browser open "$LOGIN_URL"
+agent-browser wait --load networkidle
+
+echo ""
+echo "┌─────────────────────────────────────────────────────────┐"
+echo "│ LOGIN FORM STRUCTURE                                    │"
+echo "├─────────────────────────────────────────────────────────┤"
+agent-browser snapshot -i
+echo "└─────────────────────────────────────────────────────────┘"
+echo ""
+echo "Next steps:"
+echo "  1. Note refs: @e? = username, @e? = password, @e? = submit"
+echo "  2. Uncomment LOGIN FLOW section below"
+echo "  3. Replace @e1, @e2, @e3 with your refs"
+echo "  4. Delete this DISCOVERY MODE section"
+echo ""
+agent-browser close
+exit 0
+
+# ══════════════════════════════════════════════════════════════
+# LOGIN FLOW: Uncomment and customize after discovery
+# ══════════════════════════════════════════════════════════════
+# : "${APP_USERNAME:?Set APP_USERNAME environment variable}"
+# : "${APP_PASSWORD:?Set APP_PASSWORD environment variable}"
+#
+# agent-browser open "$LOGIN_URL"
+# agent-browser wait --load networkidle
+# agent-browser snapshot -i
+#
+# # Fill credentials (update refs to match your form)
+# agent-browser fill @e1 "$APP_USERNAME"
+# agent-browser fill @e2 "$APP_PASSWORD"
+# agent-browser click @e3
+# agent-browser wait --load networkidle
+#
+# # Verify login succeeded
+# FINAL_URL=$(agent-browser get url)
+# if [[ "$FINAL_URL" == *"login"* ]] || [[ "$FINAL_URL" == *"signin"* ]]; then
+#     echo "ERROR: Login failed - still on login page"
+#     agent-browser screenshot /tmp/login-failed.png
+#     agent-browser close
+#     exit 1
+# fi
+#
+# # Save state for future runs
+# echo "Saving authentication state to: $STATE_FILE"
+# agent-browser state save "$STATE_FILE"
+# echo "Login successful!"
+# agent-browser snapshot -i

package/skills/agent-browser/templates/capture-workflow.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# Template: Content Capture Workflow
+# Extract content from web pages with optional authentication
+
+set -euo pipefail
+
+TARGET_URL="${1:?Usage: $0 <url> [output-dir]}"
+OUTPUT_DIR="${2:-.}"
+
+echo "Capturing content from: $TARGET_URL"
+mkdir -p "$OUTPUT_DIR"
+
+# Optional: Load authentication state if needed
+# if [[ -f "./auth-state.json" ]]; then
+#     agent-browser state load "./auth-state.json"
+# fi
+
+# Navigate to target page
+agent-browser open "$TARGET_URL"
+agent-browser wait --load networkidle
+
+# Get page metadata
+echo "Page title: $(agent-browser get title)"
+echo "Page URL: $(agent-browser get url)"
+
+# Capture full page screenshot
+agent-browser screenshot --full "$OUTPUT_DIR/page-full.png"
+echo "Screenshot saved: $OUTPUT_DIR/page-full.png"
+
+# Get page structure
+agent-browser snapshot -i > "$OUTPUT_DIR/page-structure.txt"
+echo "Structure saved: $OUTPUT_DIR/page-structure.txt"
+
+# Extract main content
+# Adjust selector based on target site structure
+# agent-browser get text @e1 > "$OUTPUT_DIR/main-content.txt"
+
+# Extract specific elements (uncomment as needed)
+# agent-browser get text "article" > "$OUTPUT_DIR/article.txt"
+# agent-browser get text "main" > "$OUTPUT_DIR/main.txt"
+# agent-browser get text ".content" > "$OUTPUT_DIR/content.txt"
+
+# Get full page text
+agent-browser get text body > "$OUTPUT_DIR/page-text.txt"
+echo "Text content saved: $OUTPUT_DIR/page-text.txt"
+
+# Optional: Save as PDF
+agent-browser pdf "$OUTPUT_DIR/page.pdf"
+echo "PDF saved: $OUTPUT_DIR/page.pdf"
+
+# Optional: Capture with scrolling for infinite scroll pages
+# scroll_and_capture() {
+#     local count=0
+#     while [[ $count -lt 5 ]]; do
+#         agent-browser scroll down 1000
+#         agent-browser wait 1000
+#         ((count++))
+#     done
+#     agent-browser screenshot --full "$OUTPUT_DIR/page-scrolled.png"
+# }
+# scroll_and_capture
+
+# Cleanup
+agent-browser close
+
+echo ""
+echo "Capture complete! Files saved to: $OUTPUT_DIR"
+ls -la "$OUTPUT_DIR"