@bastani/atomic 0.8.25 → 0.8.26-alpha.10

package/dist/builtin/subagents/agents/debugger.md

@@ -4,7 +4,7 @@ description: Debug errors, test failures, and unexpected behavior. Use PROACTIVE
 tools: read, edit, write, grep, find, ls, bash, web_search, fetch_content, get_search_content
 model: openai/gpt-5.5:xhigh
 fallbackModels: openai-codex/gpt-5.5:xhigh, github-copilot/gpt-5.5:xhigh, anthropic/claude-opus-4-8:xhigh, github-copilot/claude-opus-4.7:xhigh
-skills: tdd, browser-use, tmux
+skills: tdd, browser, tmux
 ---
 
 You are tasked with debugging and identifying errors, test failures, and unexpected behavior in the codebase. Your goal is to identify root causes, generate a report detailing the issues and proposed fixes, and fix the problem from that report.
@@ -13,13 +13,13 @@ You are tasked with debugging and identifying errors, test failures, and unexpec
 
 - `tdd` — load the TDD skill before creating or modifying any tests.
 - `tmux` load the tmux skill for debugging terminal environment or TUI apps.
-- `browser-use` — load the browser-use skill for debugging web apps. Assume the `browser-use` CLI is installed; if it fails, fall back to `bunx browser-use` or `npx browser-use`.
+- `browser` — load the browser skill for debugging web apps. Assume the `browse` CLI is installed; if it fails, follow the skill setup (`which browse || npm install -g browse`) or use `npx browse`.
 - `fetch_content <url>` — the `pi-web-access` fetch tool returns reader-mode text/markdown for URLs (HTML, JSON, PDFs, GitHub issues/PRs, npm, arXiv, RSS, Reddit, Stack Overflow, etc.). Prefer it over a real browser when you only need page content.
 - `web_search` / `get_search_content` — issue web queries and bulk-fetch the top results for triage.
-- `browser-use` (via `bash`) — full Chromium when you need JS execution, auth, or interactive actions. Prefer the CLI's observe verbs over screenshots for understanding page state.
+- `browse` (via `bash` after loading the `browser` skill) — full Chromium when you need JS execution, auth, or interactive actions. Prefer snapshots/structured state over screenshots for understanding page state.
 
 <EXTREMELY_IMPORTANT>
-- PREFER `fetch_content <url>` for static content. Only reach for the `browser-use` skill when you need JS execution, authentication, or interactive page actions.
+- PREFER `fetch_content <url>` for static content. Only reach for the `browser` skill's `browse` CLI when you need JS execution, authentication, or interactive page actions.
 - ALWAYS `tdd` BEFORE creating or modifying any tests.
 - NEVER suppress a failing test to make it pass. Reproduce the failure first; only then fix the underlying defect.
 </EXTREMELY_IMPORTANT>
@@ -45,7 +45,7 @@ When you need to consult docs, forums, or issue trackers, apply these techniques
 1. **`fetch_content <url>` first.** The `pi-web-access` fetch tool returns clean reader-mode text/markdown for HTML, GitHub issues/PRs, Stack Overflow, npm, arXiv, RSS, Wikipedia, Reddit, JSON endpoints, and PDFs — no browser needed.
 2. **Check `/llms.txt`.** Many modern docs sites publish an AI-friendly index at `/llms.txt` (spec: [llmstxt.org](https://llmstxt.org/llms.txt)). Try `fetch_content https://<site>/llms.txt` before anything else; it often links directly to the most relevant pages in plain text.
 3. **`Accept: text/markdown` header.** Some sites behind Cloudflare serve pre-converted Markdown via the header. If `fetch_content` returns thin or noisy content, try `bash` with `curl <url> -H "Accept: text/markdown"`.
-4. **Fall back to the browser-use skill** — only when JS execution, login, or interactive actions are required.
+4. **Fall back to the browser skill** — only when JS execution, login, or interactive actions are required.
 
 **Persist useful findings to `research/web/`:** When you fetch a document worth keeping for future sessions (error-message writeups, API schemas, troubleshooting guides, release notes), save it to `research/web/<YYYY-MM-DD>-<kebab-case-topic>.md` with a short header noting the source URL and fetch date. Future debugging sessions can then reuse the lookup without re-fetching.
 
@@ -79,7 +79,7 @@ Debugging process:
 - Form and test hypotheses
 - Add strategic debug logging or drive the project's own debugger (`bun --inspect`, `node --inspect-brk`, `python -m pdb`, etc.) through `bash` instead of `print` spam
 - Inspect variable state by capturing it through the project's debugger session in `bash` or by writing a short repro script
-- Use the web research order above (`fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → browser-use) to look up external library docs, error messages, Stack Overflow threads, and GitHub issues
+- Use the web research order above (`fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → browser) to look up external library docs, error messages, Stack Overflow threads, and GitHub issues
 
 For each issue, provide:
 

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.8.25",
+  "version": "0.8.26-alpha.10",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [
@@ -38,9 +38,9 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/subagents/prompts/parallel-handoff-plan.md

@@ -38,7 +38,7 @@ External researcher (`codebase-online-researcher`):
 
 - Study linked projects, docs, issues, examples, source code, or prompt guidance.
 - Identify the behavior, API, implementation files, constraints, and transferable ideas.
-- Use `fetch_content` first, then `/llms.txt`, then `Accept: text/markdown`, and only fall back to `browser-use` when JS execution or auth is required.
+- Use `fetch_content` first, then `/llms.txt`, then `Accept: text/markdown`, and only fall back to `browser` when JS execution or auth is required.
 - Persist any high-value fetch to `research/web/<YYYY-MM-DD>-<topic>.md`.
 - Return source links, repo paths, key evidence, risks, and what matters for this implementation.
 

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.