@bastani/atomic 0.8.26-alpha.1 → 0.8.26-alpha.11

package/dist/builtin/subagents/skills/browser/EXAMPLES.md

@@ -0,0 +1,151 @@
+# Browser Automation Examples
+
+Common browser automation workflows using the `browse` CLI. Each example demonstrates a distinct pattern using real commands.
+
+For localhost and other local dev flows, start with `browse open <url> --local` for a clean isolated browser. Use `browse open <url> --auto-connect` only when the agent should attach to an existing debuggable Chrome session for cookies or login state.
+
+## Example 1: Extract Data from a Page
+
+**User request**: "Get the product details from example.com/product/123"
+
+```bash
+browse open https://example.com/product/123
+browse snapshot                          # read page structure + element refs
+browse get text "body"                   # extract all visible text content
+browse stop
+```
+
+Parse the text output to extract structured data (name, price, description, etc.).
+
+For a specific section, use a CSS selector:
+
+```bash
+browse get text ".product-details"       # text from a specific container
+```
+
+**Note**: `browse get text` requires a CSS selector — use `"body"` for all page text.
+
+## Example 2: Fill and Submit a Form
+
+**User request**: "Fill out the contact form on example.com with my information"
+
+```bash
+browse open https://example.com/contact
+browse snapshot                          # find form fields and their refs
+browse click @0-3                        # click the Name input (ref from snapshot)
+browse type "John Doe"
+browse press Tab                         # move to next field
+browse type "john@example.com"
+browse fill "#message" "I would like to inquire about your services"
+browse snapshot                          # verify fields are filled
+browse click @0-8                        # click Submit button (ref from snapshot)
+browse snapshot                          # confirm submission result
+browse stop
+```
+
+**Key pattern**: Use `browse snapshot` before interacting to discover element refs, then `browse click <ref>` and `browse type` to interact.
+
+## Example 3: Multi-Step Navigation
+
+**User request**: "Get headlines from the first 3 pages of results on example.com/news"
+
+```bash
+browse open https://example.com/news
+browse snapshot                          # read page 1 content
+browse get text ".headline"              # extract headlines
+
+browse snapshot                          # find "Next" button ref
+browse click @0-12                       # click Next (ref from snapshot)
+browse wait load                         # wait for page 2 to load
+browse get text ".headline"              # extract page 2 headlines
+
+browse snapshot                          # find Next again (ref may change)
+browse click @0-15                       # click Next
+browse wait load
+browse get text ".headline"              # extract page 3 headlines
+
+browse stop
+```
+
+**Key pattern**: Re-run `browse snapshot` after each navigation because element refs change when the page updates.
+
+## Example 4: Escalate to Remote Mode
+
+**User request**: "Scrape pricing from competitor.com" (a site with Cloudflare protection)
+
+```bash
+# Attempt 1: local mode
+browse open https://competitor.com/pricing --local
+browse snapshot
+# Output shows: "Checking your browser..." (Cloudflare interstitial)
+# or: page content is empty / access denied
+browse stop
+```
+
+The agent detects bot protection and tells the user:
+
+> This site has Cloudflare bot detection. Browserbase remote mode can use Browserbase Identity with a Verified browser and residential proxies. Want me to set it up?
+
+If the user agrees:
+
+```bash
+# Set Browserbase credentials
+export BROWSERBASE_API_KEY="bb_live_..."
+
+# Retry in remote mode
+browse open https://competitor.com/pricing --remote
+browse snapshot                          # full page content now accessible
+browse get text ".pricing-table"
+browse stop
+```
+
+## Example 5: Persist Login with Context ID
+
+**User request**: "Log into my dashboard and save the session so I don't have to log in again next time"
+
+This uses Browserbase contexts to persist cookies and storage across sessions. Requires remote mode.
+
+```bash
+# Session 1: Log in and persist state
+SESSION_JSON="$(browse cloud sessions create --context-id ctx_abc123 --persist --keep-alive)"
+SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
+CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"
+
+browse open https://app.example.com/login --cdp "$CONNECT_URL"
+browse snapshot                          # find login form fields
+browse click @0-3                        # click email input
+browse type "user@example.com"
+browse press Tab
+browse type "my-password"
+browse click @0-7                        # click Sign In button
+browse wait load
+browse snapshot                          # confirm logged-in dashboard
+browse stop
+browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE  # state is saved back to ctx_abc123
+```
+
+In a later session, reuse the same context — already authenticated:
+
+```bash
+# Session 2: Resume with saved state (already logged in)
+SESSION_JSON="$(browse cloud sessions create --context-id ctx_abc123 --keep-alive)"
+SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
+CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"
+
+browse open https://app.example.com/dashboard --cdp "$CONNECT_URL"
+browse snapshot                          # dashboard loads — no login needed
+browse get text ".welcome-message"
+browse stop
+browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE
+```
+
+**Key pattern**: Use `browse cloud sessions create --context-id <id> --persist` for the first Browserbase session to save auth state, then attach with `browse open ... --cdp "$CONNECT_URL"`. On subsequent sessions, create with the same `--context-id` and omit `--persist` if you don't want changes saved back.
+
+## Tips
+
+- **Snapshot first**: Always run `browse snapshot` before interacting — it gives you the accessibility tree with element refs
+- **Use refs to click**: `browse click @0-5` is more reliable than trying to describe elements
+- **Re-snapshot after actions**: Element refs change when the page updates
+- **`get text` for data extraction**: Use `browse get text [selector]` to pull text content from specific elements
+- **`stop` when done**: Always `browse stop` to clean up the browser session
+- **Prefer snapshot over screenshot**: Snapshot is fast and structured; screenshot is slow and uses vision tokens. Only screenshot when you need visual context (layout, images, debugging)

package/dist/builtin/subagents/skills/browser/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browserbase, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/builtin/subagents/skills/browser/REFERENCE.md

@@ -0,0 +1,451 @@
+# Browser Automation CLI Reference
+
+Technical reference for the `browse` CLI tool.
+
+## Table of Contents
+
+- [Architecture](#architecture)
+- [Command Reference](#command-reference)
+  - [Navigation](#navigation)
+  - [Page State](#page-state)
+  - [Interaction](#interaction)
+  - [Session Management](#session-management)
+  - [JavaScript Evaluation](#javascript-evaluation)
+  - [Viewport](#viewport)
+  - [Network Capture](#network-capture)
+- [Configuration](#configuration)
+  - [Global Flags](#global-flags)
+  - [Environment Variables](#environment-variables)
+- [Error Messages](#error-messages)
+
+## Architecture
+
+The browse CLI is a **daemon-based** command-line tool:
+
+- **Daemon process**: A background process manages the browser instance. Auto-starts on the first command (e.g., `browse open`), persists across commands, and stops with `browse stop`.
+- **Local mode**: `browse open <url> --local` launches a clean isolated local browser. It is the default when `BROWSERBASE_API_KEY` is unset. Use `browse open <url> --auto-connect` to attach to an existing debuggable Chrome, or `browse open <url> --cdp <port|url>` to attach to a specific CDP target.
+- **Remote mode** (Browserbase): Connects to a Browserbase cloud browser session when `BROWSERBASE_API_KEY` is set.
+- **Accessibility-first**: Use `browse snapshot` to get the page's accessibility tree with element refs, then interact using those refs.
+
+## Command Reference
+
+### Navigation
+
+#### `open <url>`
+
+Navigate to a URL. Auto-starts the daemon if not running.
+
+```bash
+browse open https://example.com
+browse open https://example.com --wait networkidle   # wait for all network requests to finish (useful for SPAs)
+browse open https://example.com --wait domcontentloaded
+```
+
+The `--wait` flag controls when navigation is considered complete. Values: `load` (default), `domcontentloaded`, `networkidle`. Use `networkidle` for JavaScript-heavy pages that fetch data after initial load.
+
+##### Context persistence (remote mode only)
+
+Create a Browserbase session with `browse cloud sessions create --context-id <id>`, then attach to its CDP endpoint with `browse open <url> --cdp <connectUrl>`. Add `--persist` to the cloud session if state changes should save back to the context.
+
+```bash
+SESSION_JSON="$(browse cloud sessions create --context-id ctx_abc123 --persist --keep-alive)"
+SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
+CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"
+
+browse open https://example.com --cdp "$CONNECT_URL"
+# ...interact with the page...
+browse stop
+browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE
+```
+
+- `--context-id <id>` — Browserbase context ID to load when creating the cloud session.
+- `--persist` — Save cookies/storage changes back to the context when the Browserbase session is released. Requires `--context-id`.
+- `--keep-alive` — Keep the Browserbase session alive while the local browse daemon attaches and detaches.
+- After `browse open ... --cdp "$CONNECT_URL"`, follow-up commands in that session do not repeat `--cdp`; the daemon remembers the attached target.
+
+#### `reload`
+
+Reload the current page.
+
+```bash
+browse reload
+```
+
+#### `back` / `forward`
+
+Navigate browser history.
+
+```bash
+browse back
+browse forward
+```
+
+---
+
+### Page State
+
+#### `snapshot`
+
+Get the accessibility tree with interactive element refs. This is the primary way to understand page structure.
+
+```bash
+browse snapshot
+browse snapshot --compact                # tree only, no ref maps
+```
+
+Returns a text representation of the page with refs like `@0-5` that can be passed to `click`. Use `--compact` for shorter output when you only need the tree.
+
+#### `screenshot [path]`
+
+Take a visual screenshot. Slower than snapshot and uses vision tokens.
+
+```bash
+browse screenshot                        # print base64 JSON
+browse screenshot --path ./capture.png   # custom path
+browse screenshot --full-page            # capture entire scrollable page
+```
+
+#### `get <property> [selector]`
+
+Get page properties. Available properties: `url`, `title`, `text`, `html`, `value`, `box`, `visible`, `checked`.
+
+```bash
+browse get url                           # current URL
+browse get title                         # page title
+browse get text "body"                   # all visible text (selector required)
+browse get text ".product-info"          # text within a CSS selector
+browse get html "#main"                  # inner HTML of an element
+browse get value "#email-input"          # value of a form field
+browse get box "#header"                 # bounding box (centroid coordinates)
+browse get visible ".modal"              # check if element is visible
+browse get checked "#agree"              # check if checkbox/radio is checked
+```
+
+**Note**: `get text` requires a CSS selector argument — use `"body"` for full page text.
+
+#### `refs`
+
+Show the cached ref map from the last `browse snapshot`. Useful for looking up element refs without re-running a full snapshot.
+
+```bash
+browse refs
+```
+
+---
+
+### Interaction
+
+#### `click <ref>`
+
+Click an element by its ref from `browse snapshot` output.
+
+```bash
+browse click @0-5                        # click element with ref 0-5
+```
+
+#### `click_xy <x> <y>`
+
+Click at exact viewport coordinates.
+
+```bash
+browse click_xy 500 300
+```
+
+#### `hover <x> <y>`
+
+Hover at viewport coordinates.
+
+```bash
+browse hover 500 300
+```
+
+#### `type <text>`
+
+Type text into the currently focused element.
+
+```bash
+browse type "Hello, world!"
+browse type "slow typing" --delay 100    # 100ms between keystrokes
+browse type "human-like" --mistakes      # simulate human typing with typos
+```
+
+#### `fill <selector> <value>`
+
+Fill an input element matching a CSS selector. Add `--press-enter` when Enter is needed.
+
+```bash
+browse fill "#search" "browser automation"
+browse fill "input[name=email]" "user@example.com"
+browse fill "#search" "query" --press-enter   # fill and press Enter
+```
+
+#### `select <selector> <values...>`
+
+Select option(s) from a dropdown.
+
+```bash
+browse select "#country" "United States"
+browse select "#tags" "javascript" "typescript"    # multi-select
+```
+
+#### `press <key>`
+
+Press a keyboard key or key combination.
+
+```bash
+browse press Enter
+browse press Tab
+browse press Escape
+browse press Cmd+A                       # select all (Mac)
+browse press Ctrl+C                      # copy (Linux/Windows)
+```
+
+#### `mouse scroll <x> <y> <deltaX> <deltaY>`
+
+Scroll at a given position by a given amount.
+
+```bash
+browse mouse scroll 500 300 0 -300       # scroll up at (500, 300)
+browse mouse scroll 500 300 0 500        # scroll down
+```
+
+#### `mouse drag <fromX> <fromY> <toX> <toY>`
+
+Drag from one viewport coordinate to another.
+
+```bash
+browse mouse drag 80 80 310 100                # drag with default 10 steps
+browse mouse drag 80 80 310 100 --steps 20     # more intermediate steps
+browse mouse drag 80 80 310 100 --delay 50     # 50ms between steps
+browse mouse drag 80 80 310 100 --button right # use right mouse button
+browse mouse drag 80 80 310 100 --return-xpath # return source/target XPaths
+```
+
+#### `highlight <selector>`
+
+Highlight an element on the page for visual debugging.
+
+```bash
+browse highlight "#submit-btn"           # highlight for 2 seconds (default)
+browse highlight ".nav" -d 5000          # highlight for 5 seconds
+```
+
+#### `is <check> <selector>`
+
+Check element state. Available checks: `visible`, `checked`.
+
+```bash
+browse is visible ".modal"               # returns { visible: true/false }
+browse is checked "#agree"               # returns { checked: true/false }
+```
+
+#### `wait <type> [arg]`
+
+Wait for a condition.
+
+```bash
+browse wait load                         # wait for page load
+browse wait "selector" ".results"        # wait for element to appear
+browse wait timeout 3000                 # wait 3 seconds
+```
+
+---
+
+### Session Management
+
+#### `start`
+
+Start the browser daemon manually. Usually not needed — the daemon auto-starts on first command.
+
+```bash
+browse start
+```
+
+#### `stop`
+
+Stop the browser daemon and close the browser.
+
+```bash
+browse stop
+browse stop --force                      # force kill if daemon is unresponsive
+```
+
+#### `status`
+
+Check whether the daemon is running, its connection details, and current environment.
+
+```bash
+browse status
+```
+
+#### Starting sessions with a mode flag
+
+Choose the browser target on the command that starts the session:
+
+```bash
+browse open https://example.com --local
+browse open https://example.com --local --headed
+browse open https://example.com --auto-connect
+browse open https://example.com --cdp 9222
+browse open https://example.com --cdp ws://localhost:9222/devtools/browser/...
+browse open https://example.com --remote
+```
+
+- `browse status` shows the resolved mode and active target once the daemon is running.
+- `browse stop` closes the current daemon session; the next `browse open` chooses mode from its flags or environment.
+
+#### `tab new [url]`
+
+Create a new tab, optionally navigating to a URL.
+
+```bash
+browse tab new                           # open blank tab
+browse tab new https://example.com       # open tab with URL
+```
+
+#### `tab list`
+
+List all open tabs.
+
+```bash
+browse tab list
+```
+
+#### `tab switch <index-or-target-id>`
+
+Switch to a tab by its index or target ID (from `browse tab list`).
+
+```bash
+browse tab switch 1
+```
+
+#### `tab close [index-or-target-id]`
+
+Close a tab. Closes current tab if no index given. The CLI refuses to close the last remaining tab.
+
+```bash
+browse tab close          # close current tab
+browse tab close 2        # close tab at index 2
+```
+
+---
+
+### JavaScript Evaluation
+
+#### `eval <expression>`
+
+Evaluate JavaScript in the page context.
+
+```bash
+browse eval "document.title"
+browse eval "document.querySelectorAll('a').length"
+```
+
+---
+
+### Viewport
+
+#### `viewport <width> <height>`
+
+Set the browser viewport size.
+
+```bash
+browse viewport 1920 1080
+```
+
+---
+
+### Network Capture
+
+Capture network requests to the filesystem for inspection.
+
+#### `network on`
+
+Enable network request capture. Creates a temp directory where requests and responses are saved as JSON files.
+
+```bash
+browse network on
+```
+
+#### `network off`
+
+Disable network capture.
+
+```bash
+browse network off
+```
+
+#### `network path`
+
+Show the capture directory path.
+
+```bash
+browse network path
+```
+
+#### `network clear`
+
+Clear all captured requests.
+
+```bash
+browse network clear
+```
+
+---
+
+## Configuration
+
+### Common Flags
+
+#### `--session <name>`
+
+Run commands against a named session, enabling multiple concurrent browsers.
+
+```bash
+browse open https://a.com --session work
+browse open https://b.com --session personal
+```
+
+Context flags such as `--context-id` and `--persist` live on `browse cloud sessions create`; attach to the resulting `connectUrl` with `browse open ... --cdp <connectUrl>`.
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BROWSE_SESSION` | No | Default session name (alternative to `--session`) |
+| `BROWSERBASE_API_KEY` | For remote mode | API key from https://browserbase.com/settings; makes Browserbase the default desired mode when no override is set |
+| `BROWSERBASE_PROJECT_ID` | No | Passed through to Browserbase when set |
+
+Without an override, setting `BROWSERBASE_API_KEY` makes Browserbase the default desired mode. Otherwise the default desired mode is local. Use `--local`, `--remote`, `--auto-connect`, or `--cdp <port|url>` on `browse open` when you need an explicit target.
+
+### Setting credentials
+
+```bash
+export BROWSERBASE_API_KEY="bb_live_..."
+```
+
+Get these values from https://browserbase.com/settings.
+
+---
+
+## Error Messages
+
+**"No active page"**
+- The daemon is running but has no page open.
+- Fix: Run `browse open <url>`. If the issue persists, run `browse stop` and retry. For zombie daemons: `pkill -f "browse.*daemon"`.
+
+**"Chrome not found"** / **"Could not find local Chrome installation"**
+- Chrome/Chromium is not installed or not in a standard location.
+- Fix: Install Chrome, use `browse open <url> --auto-connect` if you already have a debuggable Chrome running, or switch to remote with `browse open <url> --remote` (no local browser needed).
+
+**"Daemon not running"**
+- No daemon process is active. Most commands auto-start the daemon, but `snapshot`, `click`, etc. require an active session.
+- Fix: Run `browse open <url>` to start a session.
+
+**Element ref not found (e.g., "@0-5")**
+- The ref from a previous snapshot is no longer valid (page changed).
+- Fix: Run `browse snapshot` again to get fresh refs.
+
+**Timeout errors**
+- The page took too long to load or an element didn't appear.
+- Fix: Try `browse wait load` before interacting, or increase wait time.