prose-qa 0.2.0 → 0.2.2

package/skills/agent-browser/bundled/vercel-sandbox/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: vercel-sandbox
+description: Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include "Vercel Sandbox browser", "microVM Chrome", "agent-browser in sandbox", "browser automation on Vercel", or any task requiring Chrome in a Vercel Sandbox.
+---
+
+# Browser Automation with Vercel Sandbox
+
+Run agent-browser + headless Chrome inside ephemeral Vercel Sandbox microVMs. A Linux VM spins up on demand, executes browser commands, and shuts down. Works with any Vercel-deployed framework (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.).
+
+## Dependencies
+
+```bash
+pnpm add @vercel/sandbox
+```
+
+The sandbox VM needs system dependencies for Chromium plus agent-browser itself. Use sandbox snapshots (below) to pre-install everything for sub-second startup.
+
+## Core Pattern
+
+```ts
+import { Sandbox } from "@vercel/sandbox";
+
+// System libraries required by Chromium on the sandbox VM (Amazon Linux / dnf)
+const CHROMIUM_SYSTEM_DEPS = [
+  "nss", "nspr", "libxkbcommon", "atk", "at-spi2-atk", "at-spi2-core",
+  "libXcomposite", "libXdamage", "libXrandr", "libXfixes", "libXcursor",
+  "libXi", "libXtst", "libXScrnSaver", "libXext", "mesa-libgbm", "libdrm",
+  "mesa-libGL", "mesa-libEGL", "cups-libs", "alsa-lib", "pango", "cairo",
+  "gtk3", "dbus-libs",
+];
+
+function getSandboxCredentials() {
+  if (
+    process.env.VERCEL_TOKEN &&
+    process.env.VERCEL_TEAM_ID &&
+    process.env.VERCEL_PROJECT_ID
+  ) {
+    return {
+      token: process.env.VERCEL_TOKEN,
+      teamId: process.env.VERCEL_TEAM_ID,
+      projectId: process.env.VERCEL_PROJECT_ID,
+    };
+  }
+  return {};
+}
+
+async function withBrowser<T>(
+  fn: (sandbox: InstanceType<typeof Sandbox>) => Promise<T>,
+): Promise<T> {
+  const snapshotId = process.env.AGENT_BROWSER_SNAPSHOT_ID;
+  const credentials = getSandboxCredentials();
+
+  const sandbox = snapshotId
+    ? await Sandbox.create({
+        ...credentials,
+        source: { type: "snapshot", snapshotId },
+        timeout: 120_000,
+      })
+    : await Sandbox.create({ ...credentials, runtime: "node24", timeout: 120_000 });
+
+  if (!snapshotId) {
+    await sandbox.runCommand("sh", [
+      "-c",
+      `sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUM_SYSTEM_DEPS.join(" ")} 2>&1 && sudo ldconfig 2>&1`,
+    ]);
+    await sandbox.runCommand("npm", ["install", "-g", "agent-browser"]);
+    await sandbox.runCommand("npx", ["agent-browser", "install"]);
+  }
+
+  try {
+    return await fn(sandbox);
+  } finally {
+    await sandbox.stop();
+  }
+}
+```
+
+## Screenshot
+
+The `screenshot --json` command saves to a file and returns the path. Read the file back as base64:
+
+```ts
+export async function screenshotUrl(url: string) {
+  return withBrowser(async (sandbox) => {
+    await sandbox.runCommand("agent-browser", ["open", url]);
+
+    const titleResult = await sandbox.runCommand("agent-browser", [
+      "get", "title", "--json",
+    ]);
+    const title = JSON.parse(await titleResult.stdout())?.data?.title || url;
+
+    const ssResult = await sandbox.runCommand("agent-browser", [
+      "screenshot", "--json",
+    ]);
+    const ssPath = JSON.parse(await ssResult.stdout())?.data?.path;
+    const b64Result = await sandbox.runCommand("base64", ["-w", "0", ssPath]);
+    const screenshot = (await b64Result.stdout()).trim();
+
+    await sandbox.runCommand("agent-browser", ["close"]);
+
+    return { title, screenshot };
+  });
+}
+```
+
+## Accessibility Snapshot
+
+```ts
+export async function snapshotUrl(url: string) {
+  return withBrowser(async (sandbox) => {
+    await sandbox.runCommand("agent-browser", ["open", url]);
+
+    const titleResult = await sandbox.runCommand("agent-browser", [
+      "get", "title", "--json",
+    ]);
+    const title = JSON.parse(await titleResult.stdout())?.data?.title || url;
+
+    const snapResult = await sandbox.runCommand("agent-browser", [
+      "snapshot", "-i", "-c",
+    ]);
+    const snapshot = await snapResult.stdout();
+
+    await sandbox.runCommand("agent-browser", ["close"]);
+
+    return { title, snapshot };
+  });
+}
+```
+
+## Multi-Step Workflows
+
+The sandbox persists between commands, so you can run full automation sequences:
+
+```ts
+export async function fillAndSubmitForm(url: string, data: Record<string, string>) {
+  return withBrowser(async (sandbox) => {
+    await sandbox.runCommand("agent-browser", ["open", url]);
+
+    const snapResult = await sandbox.runCommand("agent-browser", [
+      "snapshot", "-i",
+    ]);
+    const snapshot = await snapResult.stdout();
+    // Parse snapshot to find element refs...
+
+    for (const [ref, value] of Object.entries(data)) {
+      await sandbox.runCommand("agent-browser", ["fill", ref, value]);
+    }
+
+    await sandbox.runCommand("agent-browser", ["click", "@e5"]);
+    await sandbox.runCommand("agent-browser", ["wait", "--load", "networkidle"]);
+
+    const ssResult = await sandbox.runCommand("agent-browser", [
+      "screenshot", "--json",
+    ]);
+    const ssPath = JSON.parse(await ssResult.stdout())?.data?.path;
+    const b64Result = await sandbox.runCommand("base64", ["-w", "0", ssPath]);
+    const screenshot = (await b64Result.stdout()).trim();
+
+    await sandbox.runCommand("agent-browser", ["close"]);
+
+    return { screenshot };
+  });
+}
+```
+
+## Sandbox Snapshots (Fast Startup)
+
+A **sandbox snapshot** is a saved VM image of a Vercel Sandbox with system dependencies + agent-browser + Chromium already installed. Think of it like a Docker image -- instead of installing dependencies from scratch every time, the sandbox boots from the pre-built image.
+
+This is unrelated to agent-browser's *accessibility snapshot* feature (`agent-browser snapshot`), which dumps a page's accessibility tree. A sandbox snapshot is a Vercel infrastructure concept for fast VM startup.
+
+Without a sandbox snapshot, each run installs system deps + agent-browser + Chromium (~30s). With one, startup is sub-second.
+
+### Creating a sandbox snapshot
+
+The snapshot must include system dependencies (via `dnf`), agent-browser, and Chromium:
+
+```ts
+import { Sandbox } from "@vercel/sandbox";
+
+const CHROMIUM_SYSTEM_DEPS = [
+  "nss", "nspr", "libxkbcommon", "atk", "at-spi2-atk", "at-spi2-core",
+  "libXcomposite", "libXdamage", "libXrandr", "libXfixes", "libXcursor",
+  "libXi", "libXtst", "libXScrnSaver", "libXext", "mesa-libgbm", "libdrm",
+  "mesa-libGL", "mesa-libEGL", "cups-libs", "alsa-lib", "pango", "cairo",
+  "gtk3", "dbus-libs",
+];
+
+async function createSnapshot(): Promise<string> {
+  const sandbox = await Sandbox.create({
+    runtime: "node24",
+    timeout: 300_000,
+  });
+
+  await sandbox.runCommand("sh", [
+    "-c",
+    `sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUM_SYSTEM_DEPS.join(" ")} 2>&1 && sudo ldconfig 2>&1`,
+  ]);
+  await sandbox.runCommand("npm", ["install", "-g", "agent-browser"]);
+  await sandbox.runCommand("npx", ["agent-browser", "install"]);
+
+  const snapshot = await sandbox.snapshot();
+  return snapshot.snapshotId;
+}
+```
+
+Run this once, then set the environment variable:
+
+```bash
+AGENT_BROWSER_SNAPSHOT_ID=snap_xxxxxxxxxxxx
+```
+
+A helper script is available in the demo app:
+
+```bash
+npx tsx examples/environments/scripts/create-snapshot.ts
+```
+
+Recommended for any production deployment using the Sandbox pattern.
+
+## Authentication
+
+On Vercel deployments, the Sandbox SDK authenticates automatically via OIDC. For local development or explicit control, set:
+
+```bash
+VERCEL_TOKEN=<personal-access-token>
+VERCEL_TEAM_ID=<team-id>
+VERCEL_PROJECT_ID=<project-id>
+```
+
+These are spread into `Sandbox.create()` calls. When absent, the SDK falls back to `VERCEL_OIDC_TOKEN` (automatic on Vercel).
+
+## Scheduled Workflows (Cron)
+
+Combine with Vercel Cron Jobs for recurring browser tasks:
+
+```ts
+// app/api/cron/route.ts  (or equivalent in your framework)
+export async function GET() {
+  const result = await withBrowser(async (sandbox) => {
+    await sandbox.runCommand("agent-browser", ["open", "https://example.com/pricing"]);
+    const snap = await sandbox.runCommand("agent-browser", ["snapshot", "-i", "-c"]);
+    await sandbox.runCommand("agent-browser", ["close"]);
+    return await snap.stdout();
+  });
+
+  // Process results, send alerts, store data...
+  return Response.json({ ok: true, snapshot: result });
+}
+```
+
+```json
+// vercel.json
+{ "crons": [{ "path": "/api/cron", "schedule": "0 9 * * *" }] }
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `AGENT_BROWSER_SNAPSHOT_ID` | No (but recommended) | Pre-built sandbox snapshot ID for sub-second startup (see above) |
+| `VERCEL_TOKEN` | No | Vercel personal access token (for local dev; OIDC is automatic on Vercel) |
+| `VERCEL_TEAM_ID` | No | Vercel team ID (for local dev) |
+| `VERCEL_PROJECT_ID` | No | Vercel project ID (for local dev) |
+
+## Framework Examples
+
+The pattern works identically across frameworks. The only difference is where you put the server-side code:
+
+| Framework | Server code location |
+|---|---|
+| Next.js | Server actions, API routes, route handlers |
+| SvelteKit | `+page.server.ts`, `+server.ts` |
+| Nuxt | `server/api/`, `server/routes/` |
+| Remix | `loader`, `action` functions |
+| Astro | `.astro` frontmatter, API routes |
+
+## Example
+
+See `examples/environments/` in the agent-browser repo for a working app with the Vercel Sandbox pattern, including a sandbox snapshot creation script, streaming progress UI, and rate limiting.

package/skills/agent-browser/manifest.json

@@ -0,0 +1,42 @@
+{
+  "version": 1,
+  "core": {
+    "references": [
+      "authentication",
+      "commands",
+      "profiling",
+      "proxy-support",
+      "session-management",
+      "snapshot-refs",
+      "trust-boundaries",
+      "video-recording"
+    ],
+    "templates": [
+      "authenticated-session",
+      "capture-workflow",
+      "form-automation"
+    ]
+  },
+  "bundled": [
+    {
+      "name": "agentcore",
+      "description": "Run agent-browser on AWS Bedrock AgentCore cloud browsers. Use when the user wants to use AgentCore, run browser automation on AWS, use a cloud browser with AWS credentials, or needs a managed browser session backed by AWS infrastructure. Triggers include \"use agentcore\", \"run on AWS\", \"cloud browser with AWS\", \"bedrock browser\", \"agentcore session\", or any task requiring AWS-hosted browser automation."
+    },
+    {
+      "name": "dogfood",
+      "description": "Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to \"dogfood\", \"QA\", \"exploratory test\", \"find issues\", \"bug hunt\", \"test this app/site/platform\", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams."
+    },
+    {
+      "name": "electron",
+      "description": "Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools Protocol. Use when the user needs to interact with an Electron app, automate a desktop app, connect to a running app, control a native app, or test an Electron application. Triggers include \"automate Slack app\", \"control VS Code\", \"interact with Discord app\", \"test this Electron app\", \"connect to desktop app\", or any task requiring automation of a native Electron application."
+    },
+    {
+      "name": "slack",
+      "description": "Interact with Slack workspaces using browser automation. Use when the user needs to check unread channels, navigate Slack, send messages, extract data, find information, search conversations, or automate any Slack task. Triggers include \"check my Slack\", \"what channels have unreads\", \"send a message to\", \"search Slack for\", \"extract from Slack\", \"find who said\", or any task requiring programmatic Slack interaction."
+    },
+    {
+      "name": "vercel-sandbox",
+      "description": "Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include \"Vercel Sandbox browser\", \"microVM Chrome\", \"agent-browser in sandbox\", \"browser automation on Vercel\", or any task requiring Chrome in a Vercel Sandbox."
+    }
+  ]
+}

package/skills/agent-browser/references/authentication.md

@@ -0,0 +1,303 @@
+# Authentication Patterns
+
+Login flows, session persistence, OAuth, 2FA, and authenticated browsing.
+
+**Related**: [session-management.md](session-management.md) for state persistence details, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Import Auth from Your Browser](#import-auth-from-your-browser)
+- [Persistent Profiles](#persistent-profiles)
+- [Session Persistence](#session-persistence)
+- [Basic Login Flow](#basic-login-flow)
+- [Saving Authentication State](#saving-authentication-state)
+- [Restoring Authentication](#restoring-authentication)
+- [OAuth / SSO Flows](#oauth--sso-flows)
+- [Two-Factor Authentication](#two-factor-authentication)
+- [HTTP Basic Auth](#http-basic-auth)
+- [Cookie-Based Auth](#cookie-based-auth)
+- [Token Refresh Handling](#token-refresh-handling)
+- [Security Best Practices](#security-best-practices)
+
+## Import Auth from Your Browser
+
+The fastest way to authenticate is to reuse cookies from a Chrome session you are already logged into.
+
+**Step 1: Start Chrome with remote debugging**
+
+```bash
+# macOS
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
+
+# Linux
+google-chrome --remote-debugging-port=9222
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+```
+
+Log in to your target site(s) in this Chrome window as you normally would.
+
+> **Security note:** `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect and read cookies, execute JS, etc. Only use on trusted machines and close Chrome when done.
+
+**Step 2: Grab the auth state**
+
+```bash
+# Auto-discover the running Chrome and save its cookies + localStorage
+agent-browser --auto-connect state save ./my-auth.json
+```
+
+**Step 3: Reuse in automation**
+
+```bash
+# Load auth at launch
+agent-browser --state ./my-auth.json open https://app.example.com/dashboard
+
+# Or load into an existing session
+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.
+
+> **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:
+
+```bash
+agent-browser --session-name myapp state load ./my-auth.json
+# From now on, state is auto-saved/restored for "myapp"
+```
+
+## Persistent Profiles
+
+Use `--profile` to point agent-browser at a Chrome user data directory. This persists everything (cookies, IndexedDB, service workers, cache) across browser restarts without explicit save/load:
+
+```bash
+# First run: login once
+agent-browser --profile ~/.myapp-profile open https://app.example.com/login
+# ... complete login flow ...
+
+# All subsequent runs: already authenticated
+agent-browser --profile ~/.myapp-profile open https://app.example.com/dashboard
+```
+
+Use different paths for different projects or test users:
+
+```bash
+agent-browser --profile ~/.profiles/admin open https://app.example.com
+agent-browser --profile ~/.profiles/viewer open https://app.example.com
+```
+
+Or set via environment variable:
+
+```bash
+export AGENT_BROWSER_PROFILE=~/.myapp-profile
+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:
+
+```bash
+# Auto-saves state on close, auto-restores on next launch
+agent-browser --session-name twitter open https://twitter.com
+# ... login flow ...
+agent-browser close  # state saved to ~/.agent-browser/sessions/
+
+# Next time: state is automatically restored
+agent-browser --session-name twitter 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
+```
+
+## Basic Login Flow
+
+```bash
+# Navigate to login page
+agent-browser open https://app.example.com/login
+agent-browser wait --load networkidle
+
+# Get form elements
+agent-browser snapshot -i
+# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Sign In"
+
+# Fill credentials
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+
+# Submit
+agent-browser click @e3
+agent-browser wait --load networkidle
+
+# Verify login succeeded
+agent-browser get url  # Should be dashboard, not login
+```
+
+## Saving Authentication State
+
+After logging in, save state for reuse:
+
+```bash
+# Login first (see above)
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+
+# Save authenticated state
+agent-browser state save ./auth-state.json
+```
+
+## Restoring Authentication
+
+Skip login by loading saved state:
+
+```bash
+# Load saved auth state
+agent-browser state load ./auth-state.json
+
+# Navigate directly to protected page
+agent-browser open https://app.example.com/dashboard
+
+# Verify authenticated
+agent-browser snapshot -i
+```
+
+## OAuth / SSO Flows
+
+For OAuth redirects:
+
+```bash
+# Start OAuth flow
+agent-browser open https://app.example.com/auth/google
+
+# Handle redirects automatically
+agent-browser wait --url "**/accounts.google.com**"
+agent-browser snapshot -i
+
+# Fill Google credentials
+agent-browser fill @e1 "user@gmail.com"
+agent-browser click @e2  # Next button
+agent-browser wait 2000
+agent-browser snapshot -i
+agent-browser fill @e3 "password"
+agent-browser click @e4  # Sign in
+
+# Wait for redirect back
+agent-browser wait --url "**/app.example.com**"
+agent-browser state save ./oauth-state.json
+```
+
+## Two-Factor Authentication
+
+Handle 2FA with manual intervention:
+
+```bash
+# Login with credentials
+agent-browser open https://app.example.com/login --headed  # Show browser
+agent-browser snapshot -i
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+
+# Wait for user to complete 2FA manually
+echo "Complete 2FA in the browser window..."
+agent-browser wait --url "**/dashboard" --timeout 120000
+
+# Save state after 2FA
+agent-browser state save ./2fa-state.json
+```
+
+## HTTP Basic Auth
+
+For sites using HTTP Basic Authentication:
+
+```bash
+# Set credentials before navigation
+agent-browser set credentials username password
+
+# Navigate to protected resource
+agent-browser open https://protected.example.com/api
+```
+
+## Cookie-Based Auth
+
+Manually set authentication cookies:
+
+```bash
+# Set auth cookie
+agent-browser cookies set session_token "abc123xyz"
+
+# Navigate to protected page
+agent-browser open https://app.example.com/dashboard
+```
+
+## Token Refresh Handling
+
+For sessions with expiring tokens:
+
+```bash
+#!/bin/bash
+# Wrapper that handles token refresh
+
+STATE_FILE="./auth-state.json"
+
+# Try loading existing state
+if [[ -f "$STATE_FILE" ]]; then
+    agent-browser state load "$STATE_FILE"
+    agent-browser open https://app.example.com/dashboard
+
+    # Check if session is still valid
+    URL=$(agent-browser get url)
+    if [[ "$URL" == *"/login"* ]]; then
+        echo "Session expired, re-authenticating..."
+        # Perform fresh login
+        agent-browser snapshot -i
+        agent-browser fill @e1 "$USERNAME"
+        agent-browser fill @e2 "$PASSWORD"
+        agent-browser click @e3
+        agent-browser wait --url "**/dashboard"
+        agent-browser state save "$STATE_FILE"
+    fi
+else
+    # First-time login
+    agent-browser open https://app.example.com/login
+    # ... login flow ...
+fi
+```
+
+## Security Best Practices
+
+1. **Never commit state files** - They contain session tokens
+   ```bash
+   echo "*.auth-state.json" >> .gitignore
+   ```
+
+2. **Use environment variables for credentials**
+   ```bash
+   agent-browser fill @e1 "$APP_USERNAME"
+   agent-browser fill @e2 "$APP_PASSWORD"
+   ```
+
+3. **Clean up after automation**
+   ```bash
+   agent-browser cookies clear
+   rm -f ./auth-state.json
+   ```
+
+4. **Use short-lived sessions for CI/CD**
+   ```bash
+   # Don't persist state in CI
+   agent-browser open https://app.example.com/login
+   # ... login and perform actions ...
+   agent-browser close  # Session ends, nothing persisted
+   ```