agent-browser-stealth 0.17.0-fork.2 → 0.24.0-fork.2

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

@@ -6,6 +6,9 @@ Login flows, session persistence, OAuth, 2FA, and authenticated browsing.
 
 ## 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)
@@ -16,6 +19,104 @@ Login flows, session persistence, OAuth, 2FA, and authenticated browsing.
 - [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

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

@@ -58,6 +58,7 @@ agent-browser get value @e1       # Get input value
 agent-browser get attr @e1 href   # Get attribute
 agent-browser get title           # Get page title
 agent-browser get url             # Get current URL
+agent-browser get cdp-url         # Get CDP WebSocket URL
 agent-browser get count ".item"   # Count matching elements
 agent-browser get box @e1         # Get bounding box
 agent-browser get styles @e1      # Get computed styles (font, color, bg, etc.)
@@ -129,6 +130,7 @@ agent-browser find nth 2 "a" hover
 
 ```bash
 agent-browser set viewport 1920 1080          # Set viewport size
+agent-browser set viewport 1920 1080 2        # 2x retina (same CSS size, higher res screenshots)
 agent-browser set device "iPhone 14"          # Emulate device
 agent-browser set geo 37.7749 -122.4194       # Set geolocation (alias: geolocation)
 agent-browser set offline on                  # Toggle offline mode
@@ -175,15 +177,44 @@ agent-browser window new          # New window
 ## Frames
 
 ```bash
-agent-browser frame "#iframe"     # Switch to iframe
+agent-browser frame "#iframe"     # Switch to iframe by CSS selector
+agent-browser frame @e3           # Switch to iframe by element ref
 agent-browser frame main          # Back to main frame
 ```
 
+### Iframe support
+
+Iframes are detected automatically during snapshots. When the main-frame snapshot runs, `Iframe` nodes are resolved and their content is inlined beneath the iframe element in the output (one level of nesting; iframes within iframes are not expanded).
+
+```bash
+agent-browser snapshot -i
+# @e3 [Iframe] "payment-frame"
+#   @e4 [input] "Card number"
+#   @e5 [button] "Pay"
+
+# Interact directly — refs inside iframes already work
+agent-browser fill @e4 "4111111111111111"
+agent-browser click @e5
+
+# Or switch frame context for scoped snapshots
+agent-browser frame @e3               # Switch using element ref
+agent-browser snapshot -i             # Snapshot scoped to that iframe
+agent-browser frame main              # Return to main frame
+```
+
+The `frame` command accepts:
+- **Element refs** — `frame @e3` resolves the ref to an iframe element
+- **CSS selectors** — `frame "#payment-iframe"` finds the iframe by selector
+- **Frame name/URL** — matches against the browser's frame tree
+
 ## Dialogs
 
+By default, `alert` and `beforeunload` dialogs are automatically accepted so they never block the agent. `confirm` and `prompt` dialogs still require explicit handling. Use `--no-auto-dialog` to disable this behavior.
+
 ```bash
 agent-browser dialog accept [text]  # Accept dialog
 agent-browser dialog dismiss        # Dismiss dialog
+agent-browser dialog status         # Check if a dialog is currently open
 ```
 
 ## JavaScript
@@ -245,6 +276,7 @@ agent-browser console --clear             # Clear console
 agent-browser errors                      # View page errors
 agent-browser errors --clear              # Clear errors
 agent-browser highlight @e1               # Highlight element
+agent-browser inspect                     # Open Chrome DevTools for this session
 agent-browser trace start                 # Start recording trace
 agent-browser trace stop trace.zip        # Stop and save trace
 agent-browser profiler start              # Start Chrome DevTools profiling
@@ -258,6 +290,6 @@ AGENT_BROWSER_SESSION="mysession"            # Default session name
 AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # Custom browser path
 AGENT_BROWSER_EXTENSIONS="/ext1,/ext2"       # Comma-separated extension paths
 AGENT_BROWSER_PROVIDER="browserbase"         # Cloud browser provider
-AGENT_BROWSER_STREAM_PORT="9223"             # WebSocket streaming port
+AGENT_BROWSER_STREAM_PORT="9223"             # Override WebSocket streaming port (default: OS-assigned)
 AGENT_BROWSER_HOME="/path/to/agent-browser"  # Custom install location
 ```

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

@@ -162,6 +162,31 @@ agent-browser snapshot @e9
 @e10 [radio] selected                    # Selected radio
 ```
 
+## Iframes
+
+Snapshots automatically detect and inline iframe content. When the main-frame snapshot runs, each `Iframe` node is resolved and its child accessibility tree is included directly beneath it in the output. Refs assigned to elements inside iframes carry frame context, so interactions like `click`, `fill`, and `type` work without manually switching frames.
+
+```bash
+agent-browser snapshot -i
+# @e1 [heading] "Checkout"
+# @e2 [Iframe] "payment-frame"
+#   @e3 [input] "Card number"
+#   @e4 [input] "Expiry"
+#   @e5 [button] "Pay"
+# @e6 [button] "Cancel"
+
+# Interact with iframe elements directly using their refs
+agent-browser fill @e3 "4111111111111111"
+agent-browser fill @e4 "12/28"
+agent-browser click @e5
+```
+
+**Key details:**
+- Only one level of iframe nesting is expanded (iframes within iframes are not recursed)
+- Cross-origin iframes that block accessibility tree access are silently skipped
+- Empty iframes or iframes with no interactive content are omitted from the output
+- To scope a snapshot to a single iframe, use `frame @ref` then `snapshot -i`
+
 ## Troubleshooting
 
 ### "Ref not found" Error

package/skills/agentcore/SKILL.md

@@ -0,0 +1,115 @@
+---
+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.
+allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*)
+---
+
+# AWS Bedrock AgentCore
+
+Run agent-browser on cloud browser sessions hosted by AWS Bedrock AgentCore. All standard agent-browser commands work identically; the only difference is where the browser runs.
+
+## Setup
+
+Credentials are resolved automatically:
+
+1. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, optionally `AWS_SESSION_TOKEN`)
+2. AWS CLI fallback (`aws configure export-credentials`), which supports SSO, IAM roles, and named profiles
+
+No additional setup is needed if the user already has working AWS credentials.
+
+## Core Workflow
+
+```bash
+# Open a page on an AgentCore cloud browser
+agent-browser -p agentcore open https://example.com
+
+# Everything else is the same as local Chrome
+agent-browser snapshot -i
+agent-browser click @e1
+agent-browser screenshot page.png
+agent-browser close
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AGENTCORE_REGION` | AWS region | `us-east-1` |
+| `AGENTCORE_BROWSER_ID` | Browser identifier | `aws.browser.v1` |
+| `AGENTCORE_PROFILE_ID` | Persistent browser profile (cookies, localStorage) | (none) |
+| `AGENTCORE_SESSION_TIMEOUT` | Session timeout in seconds | `3600` |
+| `AWS_PROFILE` | AWS CLI profile for credential resolution | `default` |
+
+## Persistent Profiles
+
+Use `AGENTCORE_PROFILE_ID` to persist browser state across sessions. This is useful for maintaining login sessions:
+
+```bash
+# First run: log in
+AGENTCORE_PROFILE_ID=my-app agent-browser -p agentcore open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password"
+agent-browser click @e3
+agent-browser close
+
+# Future runs: already authenticated
+AGENTCORE_PROFILE_ID=my-app agent-browser -p agentcore open https://app.example.com/dashboard
+```
+
+## Live View
+
+When a session starts, AgentCore prints a Live View URL to stderr. Open it in a browser to watch the session in real time from the AWS Console:
+
+```
+Session: abc123-def456
+Live View: https://us-east-1.console.aws.amazon.com/bedrock-agentcore/browser/aws.browser.v1/session/abc123-def456#
+```
+
+## Region Selection
+
+```bash
+# Default: us-east-1
+agent-browser -p agentcore open https://example.com
+
+# Explicit region
+AGENTCORE_REGION=eu-west-1 agent-browser -p agentcore open https://example.com
+```
+
+## Credential Patterns
+
+```bash
+# Explicit credentials (CI/CD, scripts)
+export AWS_ACCESS_KEY_ID=AKIA...
+export AWS_SECRET_ACCESS_KEY=...
+agent-browser -p agentcore open https://example.com
+
+# SSO (interactive)
+aws sso login --profile my-profile
+AWS_PROFILE=my-profile agent-browser -p agentcore open https://example.com
+
+# IAM role / default credential chain
+agent-browser -p agentcore open https://example.com
+```
+
+## Using with AGENT_BROWSER_PROVIDER
+
+Set the provider via environment variable to avoid passing `-p agentcore` on every command:
+
+```bash
+export AGENT_BROWSER_PROVIDER=agentcore
+export AGENTCORE_REGION=us-east-2
+
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser click @e1
+agent-browser close
+```
+
+## Common Issues
+
+**"Failed to run aws CLI"** means AWS CLI is not installed or not in PATH. Either install it or set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` directly.
+
+**"AWS CLI failed: ... Run 'aws sso login'"** means SSO credentials have expired. Run `aws sso login` to refresh them.
+
+**Session timeout:** The default is 3600 seconds (1 hour). For longer tasks, increase with `AGENTCORE_SESSION_TIMEOUT=7200`.

package/skills/dogfood/SKILL.md

@@ -190,11 +190,13 @@ agent-browser --session {SESSION} close
 ## Guidance
 
 - **Repro is everything.** Every issue needs proof -- but match the evidence to the issue. Interactive bugs need video and step-by-step screenshots. Static bugs (typos, placeholder text, visual glitches visible on load) only need a single annotated screenshot.
-- **Verify reproducibility before collecting evidence.** Before recording video or taking screenshots, verify the issue is reproducible with at least one retry. If it cannot be reproduced consistently, do not report it as a confirmed issue.
+- **Verify reproducibility before collecting evidence.** Before recording video or taking screenshots, verify the issue is reproducible with at least one retry. If it can't be reproduced consistently, it's not a valid issue.
 - **Don't record video for static issues.** A typo or clipped text doesn't benefit from a video. Save video for issues that involve user interaction, timing, or state changes.
 - **For interactive issues, screenshot each step.** Capture the before, the action, and the after -- so someone can see the full sequence.
 - **Write repro steps that map to screenshots.** Each numbered step in the report should reference its corresponding screenshot. A reader should be able to follow the steps visually without touching a browser.
-- **Use the right snapshot command.** Use `snapshot -i` to find clickable or fillable elements. Use plain `snapshot` when you need readable page content such as text, headings, or data lists.
+- **Use the right snapshot command.**
+  - `snapshot -i` — for finding clickable/fillable elements (buttons, inputs, links)
+  - `snapshot` (no flag) — for reading page content (text, headings, data lists)
 - **Be thorough but use judgment.** You are not following a test script -- you are exploring like a real user would. If something feels off, investigate.
 - **Write findings incrementally.** Append each issue to the report as you discover it. If the session is interrupted, findings are preserved. Never batch all issues for the end.
 - **Never delete output files.** Do not `rm` screenshots, videos, or the report mid-session. Do not close the session and restart. Work forward, not backward.

package/skills/electron/SKILL.md

@@ -102,6 +102,31 @@ agent-browser tab 2
 agent-browser tab --url "*settings*"
 ```
 
+## Webview Support
+
+Electron `<webview>` elements are automatically discovered and can be controlled like regular pages. Webviews appear as separate targets in the tab list with `type: "webview"`:
+
+```bash
+# Connect to running Electron app
+agent-browser connect 9222
+
+# List targets -- webviews appear alongside pages
+agent-browser tab
+# Example output:
+#   0: [page]    Slack - Main Window     https://app.slack.com/
+#   1: [webview] Embedded Content        https://example.com/widget
+
+# Switch to a webview
+agent-browser tab 1
+
+# Interact with the webview normally
+agent-browser snapshot -i
+agent-browser click @e3
+agent-browser screenshot webview.png
+```
+
+**Note:** Webview support works via raw CDP connection.
+
 ## Common Patterns
 
 ### Inspect and Navigate an App
@@ -163,7 +188,7 @@ agent-browser --session vscode snapshot -i
 
 ## Color Scheme
 
-Playwright overrides the color scheme to `light` by default when connecting via CDP. To preserve dark mode:
+The default color scheme when connecting via CDP may be `light`. To preserve dark mode:
 
 ```bash
 agent-browser connect 9222
@@ -192,7 +217,6 @@ AGENT_BROWSER_COLOR_SCHEME=dark agent-browser connect 9222
 ### Elements not appearing in snapshot
 
 - The app may use multiple webviews. Use `agent-browser tab` to list targets and switch to the right one
-- Use `agent-browser snapshot -i -C` to include cursor-interactive elements (divs with onclick handlers)
 
 ### Cannot type in input fields
 

package/skills/slack/SKILL.md

@@ -235,15 +235,6 @@ agent-browser console
 agent-browser errors
 ```
 
-### View raw HTML of an element
-
-```bash
-# Snapshot shows the accessibility tree. If an element isn't there,
-# it may not be interactive (e.g., div instead of button)
-# Use snapshot -i -C to include cursor-interactive divs
-agent-browser snapshot -i -C
-```
-
 ### Get current page state
 
 ```bash

package/skills/slack/references/slack-tasks.md

@@ -334,19 +334,13 @@ If you can't find an element:
    agent-browser snapshot -i
    ```
 
-3. **Try snapshot with extended range**
-   ```bash
-   # Include cursor-interactive elements (divs with onclick handlers)
-   agent-browser snapshot -i -C
-   ```
-
-4. **Check current URL**
+3. **Check current URL**
    ```bash
    agent-browser get url
    # Verify you're in the right section
    ```
 
-5. **Wait for page to load**
+4. **Wait for page to load**
    ```bash
    agent-browser wait --load networkidle
    agent-browser wait 1000