@bastani/atomic 0.8.31-alpha.1 → 0.8.31-alpha.3

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

@@ -1,151 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-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

@@ -1,451 +0,0 @@
-# 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.