diff --git a/CHANGELOG.md b/CHANGELOG.md index f84810f9..f3d4a3f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## [0.7.4] - 2026-03-18 + +### Added + +- **Hand off to a real Chrome when the headless browser gets stuck.** Hit a CAPTCHA, auth wall, or MFA prompt? Run `$B handoff "reason"` and a visible Chrome opens at the exact same page with all your cookies and tabs intact. Solve the problem, tell Claude you're done, and `$B resume` picks up right where you left off with a fresh snapshot. +- **Auto-handoff hint after 3 consecutive failures.** If the browse tool fails 3 times in a row, it suggests using `handoff` — so you don't waste time watching the AI retry a CAPTCHA. +- **15 new tests for the handoff feature.** Unit tests for state save/restore, failure tracking, edge cases, plus integration tests for the full headless-to-headed flow with cookie and tab preservation. + +### Changed + +- `recreateContext()` refactored to use shared `saveState()`/`restoreState()` helpers — same behavior, less code, ready for future state persistence features. +- `browser.close()` now has a 5-second timeout to prevent hangs when closing headed browsers on macOS. + ## [0.7.3] - 2026-03-18 ### Added diff --git a/SKILL.md b/SKILL.md index c04c1480..6a1e72fe 100644 --- a/SKILL.md +++ b/SKILL.md @@ -525,7 +525,9 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`. ### Server | Command | Description | |---------|-------------| +| `handoff [message]` | Open visible Chrome at current page for user takeover | | `restart` | Restart server | +| `resume` | Re-snapshot after user takeover, return control to AI | | `status` | Health check | | `stop` | Shutdown server | diff --git a/VERSION b/VERSION index f38fc539..0a1ffad4 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.7.3 +0.7.4 diff --git a/browse/SKILL.md b/browse/SKILL.md index 5c3bf096..455c2e70 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -259,6 +259,32 @@ $B diff https://staging.app.com https://prod.app.com ### 11. Show screenshots to the user After `$B screenshot`, `$B snapshot -a -o`, or `$B responsive`, always use the Read tool on the output PNG(s) so the user can see them. Without this, screenshots are invisible. +## User Handoff + +When you hit something you can't handle in headless mode (CAPTCHA, complex auth, multi-factor +login), hand off to the user: + +```bash +# 1. Open a visible Chrome at the current page +$B handoff "Stuck on CAPTCHA at login page" + +# 2. Tell the user what happened (via AskUserQuestion) +# "I've opened Chrome at the login page. Please solve the CAPTCHA +# and let me know when you're done." + +# 3. When user says "done", re-snapshot and continue +$B resume +``` + +**When to use handoff:** +- CAPTCHAs or bot detection +- Multi-factor authentication (SMS, authenticator app) +- OAuth flows that require user interaction +- Complex interactions the AI can't handle after 3 attempts + +The browser preserves all state (cookies, localStorage, tabs) across the handoff. +After `resume`, you get a fresh snapshot of wherever the user left off. + ## Snapshot Flags The snapshot is your primary tool for understanding and interacting with pages. @@ -381,6 +407,8 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`. ### Server | Command | Description | |---------|-------------| +| `handoff [message]` | Open visible Chrome at current page for user takeover | | `restart` | Restart server | +| `resume` | Re-snapshot after user takeover, return control to AI | | `status` | Health check | | `stop` | Shutdown server |