@dyyz1993/agent-browser 0.9.2

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

@@ -0,0 +1,173 @@
+# Video Recording
+
+Capture browser automation as video for debugging, documentation, or verification.
+
+**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Basic Recording](#basic-recording)
+- [Recording Commands](#recording-commands)
+- [Use Cases](#use-cases)
+- [Best Practices](#best-practices)
+- [Output Format](#output-format)
+- [Limitations](#limitations)
+
+## 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/api-interception.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# API Interception Template - Passively capture API responses
+# Usage: ./api-interception.sh [target_url] [output_file]
+
+TARGET_URL="${1:-https://example.com/user/profile}"
+OUTPUT_FILE="${2:-/tmp/api-response.json}"
+REQUEST_PATTERN="${3:-api/}"
+
+echo "=== 1. Close old session ==="
+agent-browser close 2>/dev/null
+sleep 1
+
+echo ""
+echo "=== 2. Open blank page ==="
+export https_proxy=http://127.0.0.1:7890
+agent-browser open "about:blank"
+sleep 1
+
+echo ""
+echo "=== 3. Start request listener in background ==="
+(agent-browser wait --request "$REQUEST_PATTERN" --timeout 30000 > /tmp/api-captured.json 2>&1) &
+WAIT_PID=$!
+sleep 1
+
+echo ""
+echo "=== 4. Navigate to target page ==="
+agent-browser open "$TARGET_URL"
+
+echo ""
+echo "=== 5. Wait for API response ==="
+wait $WAIT_PID 2>/dev/null
+
+echo ""
+echo "=== 6. Process captured data ==="
+if [ -f /tmp/api-captured.json ] && [ -s /tmp/api-captured.json ]; then
+  # Extract response body
+  jq '.body' /tmp/api-captured.json > "$OUTPUT_FILE"
+  
+  echo "Response saved to: $OUTPUT_FILE"
+  echo ""
+  echo "=== Preview ==="
+  jq '.' "$OUTPUT_FILE" | head -50
+else
+  echo "Error: No response captured"
+  exit 1
+fi
+
+echo ""
+echo "=== 7. Close browser ==="
+agent-browser close
+
+echo ""
+echo "=== Done ==="

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

@@ -0,0 +1,97 @@
+#!/bin/bash
+# Template: Authenticated Session Workflow
+# Purpose: Login once, save state, reuse for subsequent runs
+# Usage: ./authenticated-session.sh <login-url> [state-file]
+#
+# Environment variables:
+#   APP_USERNAME - Login username/email
+#   APP_PASSWORD - Login password
+#
+# Two modes:
+#   1. Discovery mode (default): Shows form structure so you can identify refs
+#   2. Login mode: Performs actual login after you update the refs
+#
+# Setup steps:
+#   1. Run once to see form structure (discovery mode)
+#   2. Update refs in LOGIN FLOW section below
+#   3. Set APP_USERNAME and APP_PASSWORD
+#   4. Delete the DISCOVERY section
+
+set -euo pipefail
+
+LOGIN_URL="${1:?Usage: $0 <login-url> [state-file]}"
+STATE_FILE="${2:-./auth-state.json}"
+
+echo "Authentication workflow: $LOGIN_URL"
+
+# ================================================================
+# SAVED STATE: Skip login if valid saved state exists
+# ================================================================
+if [[ -f "$STATE_FILE" ]]; then
+    echo "Loading saved state from $STATE_FILE..."
+    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: Shows form structure (delete after setup)
+# ================================================================
+echo "Opening login page..."
+agent-browser open "$LOGIN_URL"
+agent-browser wait --load networkidle
+
+echo ""
+echo "Login form structure:"
+echo "---"
+agent-browser snapshot -i
+echo "---"
+echo ""
+echo "Next steps:"
+echo "  1. Note the refs: username=@e?, password=@e?, submit=@e?"
+echo "  2. Update the LOGIN FLOW section below with your refs"
+echo "  3. Set: export APP_USERNAME='...' APP_PASSWORD='...'"
+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 "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 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,69 @@
+#!/bin/bash
+# Template: Content Capture Workflow
+# Purpose: Extract content from web pages (text, screenshots, PDF)
+# Usage: ./capture-workflow.sh <url> [output-dir]
+#
+# Outputs:
+#   - page-full.png: Full page screenshot
+#   - page-structure.txt: Page element structure with refs
+#   - page-text.txt: All text content
+#   - page.pdf: PDF version
+#
+# Optional: Load auth state for protected pages
+
+set -euo pipefail
+
+TARGET_URL="${1:?Usage: $0 <url> [output-dir]}"
+OUTPUT_DIR="${2:-.}"
+
+echo "Capturing: $TARGET_URL"
+mkdir -p "$OUTPUT_DIR"
+
+# Optional: Load authentication state
+# if [[ -f "./auth-state.json" ]]; then
+#     echo "Loading authentication state..."
+#     agent-browser state load "./auth-state.json"
+# fi
+
+# Navigate to target
+agent-browser open "$TARGET_URL"
+agent-browser wait --load networkidle
+
+# Get metadata
+TITLE=$(agent-browser get title)
+URL=$(agent-browser get url)
+echo "Title: $TITLE"
+echo "URL: $URL"
+
+# Capture full page screenshot
+agent-browser screenshot --full "$OUTPUT_DIR/page-full.png"
+echo "Saved: $OUTPUT_DIR/page-full.png"
+
+# Get page structure with refs
+agent-browser snapshot -i > "$OUTPUT_DIR/page-structure.txt"
+echo "Saved: $OUTPUT_DIR/page-structure.txt"
+
+# Extract all text content
+agent-browser get text body > "$OUTPUT_DIR/page-text.txt"
+echo "Saved: $OUTPUT_DIR/page-text.txt"
+
+# Save as PDF
+agent-browser pdf "$OUTPUT_DIR/page.pdf"
+echo "Saved: $OUTPUT_DIR/page.pdf"
+
+# Optional: Extract specific elements using refs from structure
+# agent-browser get text @e5 > "$OUTPUT_DIR/main-content.txt"
+
+# Optional: Handle infinite scroll pages
+# for i in {1..5}; do
+#     agent-browser scroll down 1000
+#     agent-browser wait 1000
+# done
+# agent-browser screenshot --full "$OUTPUT_DIR/page-scrolled.png"
+
+# Cleanup
+agent-browser close
+
+echo ""
+echo "Capture complete:"
+ls -la "$OUTPUT_DIR"

package/skills/agent-browser/templates/data-extraction.sh

@@ -0,0 +1,210 @@
+#!/bin/bash
+# Data Extraction Template - Universal pattern for web scraping
+# Usage: ./data-extraction.sh <url> [output_file] [mode]
+#
+# Modes:
+#   dom       - Extract from DOM elements (default)
+#   js        - Extract from JavaScript global variables
+#   api       - Intercept API responses
+#   scroll    - Infinite scroll collection
+#
+# Examples:
+#   ./data-extraction.sh https://example.com/products
+#   ./data-extraction.sh https://example.com/api/data output.json api
+#   ./data-extraction.sh https://example.com/list items.json scroll
+
+set -euo pipefail
+
+TARGET_URL="${1:?Usage: $0 <url> [output_file] [mode]}"
+OUTPUT_FILE="${2:-/tmp/extracted-data.json}"
+MODE="${3:-dom}"
+REQUEST_PATTERN="${4:-api/}"
+
+echo "=== Data Extraction Template ==="
+echo "URL: $TARGET_URL"
+echo "Mode: $MODE"
+echo "Output: $OUTPUT_FILE"
+echo ""
+
+echo "=== 1. Close old session ==="
+agent-browser close 2>/dev/null
+sleep 1
+
+case "$MODE" in
+  api)
+    echo ""
+    echo "=== 2. API Interception Mode ==="
+    export https_proxy=http://127.0.0.1:7890
+    agent-browser open "about:blank"
+    sleep 1
+    
+    echo ""
+    echo "=== 3. Start request listener ==="
+    (agent-browser wait --request "$REQUEST_PATTERN" --timeout 30000 > /tmp/api-response.json 2>&1) &
+    WAIT_PID=$!
+    sleep 1
+    
+    echo ""
+    echo "=== 4. Navigate to trigger API ==="
+    agent-browser open "$TARGET_URL"
+    
+    echo ""
+    echo "=== 5. Wait for response ==="
+    wait $WAIT_PID 2>/dev/null || true
+    
+    if [ -f /tmp/api-response.json ] && [ -s /tmp/api-response.json ]; then
+      jq '.' /tmp/api-response.json > "$OUTPUT_FILE"
+      echo "API response saved to: $OUTPUT_FILE"
+    else
+      echo "Warning: No API response captured, falling back to DOM extraction"
+      agent-browser eval 'document.body.innerText' > "$OUTPUT_FILE"
+    fi
+    ;;
+    
+  scroll)
+    echo ""
+    echo "=== 2. Infinite Scroll Mode ==="
+    export https_proxy=http://127.0.0.1:7890
+    agent-browser open "$TARGET_URL"
+    sleep 2
+    
+    ALL_DATA="[]"
+    PREV_COUNT=0
+    MAX_ITERATIONS=50
+    
+    for i in $(seq 1 $MAX_ITERATIONS); do
+      CURRENT=$(agent-browser eval '
+        JSON.stringify(
+          Array.from(document.querySelectorAll("a, .item, .card"))
+            .slice(0, 100)
+            .map(el => ({
+              text: el.textContent?.trim()?.substring(0, 200),
+              href: el.href || null
+            }))
+            .filter(item => item.text && item.text.length > 0)
+        )
+      ')
+      
+      ALL_DATA=$(echo "$ALL_DATA" "$CURRENT" | python3 -c "
+import sys, json
+data = []
+for line in sys.stdin:
+    line = line.strip()
+    if line:
+        try:
+            d = json.loads(line)
+            if isinstance(d, list): data.extend(d)
+        except: pass
+seen = set()
+unique = []
+for item in data:
+    key = item.get('href') or item.get('text', '')[:50]
+    if key not in seen:
+        seen.add(key)
+        unique.append(item)
+print(json.dumps(unique, ensure_ascii=False))
+      " 2>/dev/null || echo "[]")
+      
+      COUNT=$(echo "$ALL_DATA" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d))" 2>/dev/null || echo "0")
+      echo "[$i] Collected: $COUNT items"
+      
+      if [ "$COUNT" -eq "$PREV_COUNT" ] && [ "$COUNT" -gt 0 ]; then
+        echo "No new items, reached end"
+        break
+      fi
+      PREV_COUNT=$COUNT
+      
+      agent-browser scroll down 500
+      sleep 0.5
+    done
+    
+    echo "$ALL_DATA" | python3 -m json.tool > "$OUTPUT_FILE" 2>/dev/null || echo "$ALL_DATA" > "$OUTPUT_FILE"
+    echo "Scroll data saved to: $OUTPUT_FILE"
+    ;;
+    
+  js)
+    echo ""
+    echo "=== 2. JS Variable Extraction Mode ==="
+    export https_proxy=http://127.0.0.1:7890
+    agent-browser open "$TARGET_URL"
+    sleep 3
+    
+    agent-browser eval '
+      const result = {
+        url: window.location.href,
+        title: document.title,
+        
+        __INITIAL_STATE__: window.__INITIAL_STATE__ || null,
+        __NEXT_DATA__: window.__NEXT_DATA__ || null,
+        __NUXT__: window.__NUXT__ || null,
+        dataLayer: window.dataLayer || null,
+        
+        custom: {}
+      };
+      
+      JSON.stringify(result, (k, v) => {
+        if (typeof v === "function") return "[Function]";
+        return v;
+      }, 2);
+    ' > "$OUTPUT_FILE"
+    echo "JS variables saved to: $OUTPUT_FILE"
+    ;;
+    
+  dom|*)
+    echo ""
+    echo "=== 2. DOM Extraction Mode ==="
+    export https_proxy=http://127.0.0.1:7890
+    agent-browser open "$TARGET_URL"
+    sleep 2
+    
+    agent-browser eval '
+      const extractText = (sel) => {
+        const el = document.querySelector(sel);
+        return el?.textContent?.trim() || null;
+      };
+      
+      const extractAll = (sel, mapFn) => {
+        return Array.from(document.querySelectorAll(sel))
+          .map(mapFn)
+          .filter(Boolean);
+      };
+      
+      const data = {
+        url: window.location.href,
+        title: document.title,
+        meta: {
+          description: extractText("meta[name=\"description\"]"),
+          keywords: extractText("meta[name=\"keywords\"]")
+        },
+        headings: extractAll("h1, h2, h3", el => ({
+          level: el.tagName,
+          text: el.textContent?.trim()
+        })),
+        links: extractAll("a[href]", el => ({
+          text: el.textContent?.trim()?.substring(0, 100),
+          href: el.href
+        })).slice(0, 50),
+        images: extractAll("img[src]", el => ({
+          alt: el.alt,
+          src: el.src
+        })).slice(0, 20),
+        bodyText: document.body.innerText.substring(0, 5000)
+      };
+      
+      JSON.stringify(data, null, 2);
+    ' > "$OUTPUT_FILE"
+    echo "DOM data saved to: $OUTPUT_FILE"
+    ;;
+esac
+
+echo ""
+echo "=== 6. Preview results ==="
+head -100 "$OUTPUT_FILE"
+
+echo ""
+echo "=== 7. Close browser ==="
+agent-browser close
+
+echo ""
+echo "=== Extraction Complete ==="
+echo "Total items: $(wc -l < "$OUTPUT_FILE") lines"

package/skills/agent-browser/templates/form-automation.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# Template: Form Automation Workflow
+# Purpose: Fill and submit web forms with validation
+# Usage: ./form-automation.sh <form-url>
+#
+# This template demonstrates the snapshot-interact-verify pattern:
+# 1. Navigate to form
+# 2. Snapshot to get element refs
+# 3. Fill fields using refs
+# 4. Submit and verify result
+#
+# Customize: Update the refs (@e1, @e2, etc.) based on your form's snapshot output
+
+set -euo pipefail
+
+FORM_URL="${1:?Usage: $0 <form-url>}"
+
+echo "Form automation: $FORM_URL"
+
+# Step 1: Navigate to form
+agent-browser open "$FORM_URL"
+agent-browser wait --load networkidle
+
+# Step 2: Snapshot to discover form elements
+echo ""
+echo "Form structure:"
+agent-browser snapshot -i
+
+# Step 3: Fill form fields (customize these refs based on snapshot output)
+#
+# Common field types:
+#   agent-browser fill @e1 "John Doe"           # Text input
+#   agent-browser fill @e2 "user@example.com"   # Email input
+#   agent-browser fill @e3 "SecureP@ss123"      # Password input
+#   agent-browser select @e4 "Option Value"     # Dropdown
+#   agent-browser check @e5                     # Checkbox
+#   agent-browser click @e6                     # Radio button
+#   agent-browser fill @e7 "Multi-line text"   # Textarea
+#   agent-browser upload @e8 /path/to/file.pdf # File upload
+#
+# Uncomment and modify:
+# agent-browser fill @e1 "Test User"
+# agent-browser fill @e2 "test@example.com"
+# agent-browser click @e3  # Submit button
+
+# Step 4: Wait for submission
+# agent-browser wait --load networkidle
+# agent-browser wait --url "**/success"  # Or wait for redirect
+
+# Step 5: Verify result
+echo ""
+echo "Result:"
+agent-browser get url
+agent-browser snapshot -i
+
+# Optional: Capture evidence
+agent-browser screenshot /tmp/form-result.png
+echo "Screenshot saved: /tmp/form-result.png"
+
+# Cleanup
+agent-browser close
+echo "Done"