pi-chrome 0.15.49 → 0.15.53

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable user-facing changes to `pi-chrome`.
 
+## 0.15.53 — 2026-09-26
+
+Changes adapted from community forks (ardhiqii, kkunkunya, nihar-oracle, steimerbyte).
+
+- **Connector recovers from stalled connections.** The extension's `/next` long poll now gives up after 45s (the bridge holds it for up to 25s). Before this, a half-open socket (Pi process died, machine slept, network changed) could leave the extension waiting forever until someone reloaded it by hand. Result posts time out, retry on network/5xx failures, and are never posted twice for the same command.
+- **Page actions work on a fresh automation tab.** Chrome refuses `chrome.scripting` on a top-level `about:blank`, which is where the dedicated automation tab starts. As a result, `chrome_snapshot`, `chrome_inspect`, console/network listing, uid click targeting, and the `/chrome doctor` page probe failed on that tab with `Cannot access contents of url "about:blank"`. When Chrome refuses scripting for a permission reason, these calls now fall back to CDP `Runtime.evaluate`. Ordinary pages still use `chrome.scripting` first.
+- **Chrome tools in subagent sessions.** A second load of the same pi-chrome install in one process (for example, pi-subagents) was skipped as a duplicate, so subagents had no `chrome_*` tools. It now loads as a client of the shared bridge. Subagents share the parent's authorization and get their own automation tab and tab group. Two different install roots are still treated as duplicates. `chrome_launch` in a client session now reports the shared connection state instead of always saying "waiting for extension".
+- **New `chrome_cdp` and `chrome_cdp_targets` tools.** `chrome_cdp` runs one raw Chrome DevTools Protocol method on a tab and validates the method/params first. `timeoutMs` can extend the deadline up to 120s, and screenshot/binary or oversized results are summarized instead of returned in full. Background mode blocks `Page.bringToFront` and `Target.activateTarget`. `chrome_cdp_targets` lists CDP targets on a tab, such as password-manager overlays or DevTools, to help diagnose `Detached while handling command`. It never attaches the debugger or creates a tab.
+- **`chrome_type` shows what it typed.** Results include the field value before and after, and `insertedAt` (`empty`, `caret-end`, `caret-middle`, `replaced-selection`, `replaced-all`). The text warns when input was spliced into existing content, when Enter may have submitted the spliced value, and when the field did not change at all (keystrokes did not reach it). Password/OTP/card-like fields report only lengths. New `replace: true` selects all with Chrome's platform-neutral `selectAll` editing command and deletes before typing. Tool descriptions now state that `chrome_type` inserts at the caret and `chrome_fill` replaces.
+- **`includeSnapshot` waits for navigations.** If a click/type/fill/key action starts a navigation, the included snapshot waits up to 5s for the new page and reports `navigation {from, to, settled, waitedMs}`. Before, it could describe the page being replaced. Actions without navigation do not wait. A page that was already loading is reported but not waited on.
+- **CDP timeouts report as timeouts.** A timed-out CDP command now fails with `CDP <method> timed out after Nms`. Before, the cleanup detach surfaced as `Detached while handling command`, and the command was re-sent once, so a slow command could run twice.
+- **`chrome_tab new` reports the loaded tab.** It waits up to 5s for the URL to load and returns `loadStatus` instead of Chrome's initial empty `loading` tab.
+- **Tool activation.** `chrome_find`, `chrome_inspect`, and the new CDP tools are now activated by `/chrome authorize` and removed from the active tool set by `/chrome revoke` or grant expiry, like the other `chrome_*` tools.
+- **Validation.** New unit suites: `bridge-resilience`, `cdp-passthrough`, `type-evidence`.
+
+## 0.15.51 — 2026-09-10
+
+- **Fewer Chrome commands.** Removed `/chrome status`; use bare `/chrome` for the quick connection, authorization, and background dashboard plus controls. The dashboard remains lightweight and does not run page probes.
+- **Complete Doctor report.** `/chrome doctor` now includes authorization and background state alongside connection, version, page checks, and troubleshooting hints, even when Chrome is offline or outdated.
+- **Command regressions.** Added tests for command dispatch/completion, lightweight dashboard behavior, Doctor state reporting, and failure paths. `/chrome background status` remains available.
+
+## 0.15.50 — 2026-09-10
+
+- **README clarity.** Lead with workflow examples, correct setup ordering and platform-specific onboarding instructions, and clarify privacy guidance. Describe background behavior and the on/off/status controls directly.
+- **Documentation-only release.** Browser behavior and permissions are unchanged. The companion version matches the npm package version.
+
 ## 0.15.49 — 2026-09-10
 
 - **Validation scope.** Node regression suites passed. Live browser validation remains incomplete: an input attempt encountered `Input.dispatchMouseEvent: Detached while handling command.`; a subsequent retest was blocked by a disconnected companion. No live-browser pass is claimed for these changes.

package/README.md

@@ -1,157 +1,111 @@
 # pi-chrome
 
-> Let [Pi](https://pi.dev) use your existing signed-in Chrome profile after explicit authorization.
+**Give Pi the Chrome you're already signed into.**
 
-**MIT · 0 runtime deps · loopback-only bridge (`127.0.0.1:17318`) · inspectable unpacked Chrome extension.** Review [`extensions/chrome-profile-bridge/browser-extension/`](./extensions/chrome-profile-bridge/browser-extension) before loading. Verify setup with `/chrome doctor`.
+Debug your app, inspect signed-in dashboards, and capture screenshots using your existing Chrome profile—without setting up a separate automation browser.
 
-```text
-You:    "Find my open GitHub PR tab, summarize review state, and screenshot failing CI."
-Agent:  chrome_tab(list) → chrome_snapshot(uid:…) → chrome_screenshot(...)
-        ✓ 3 reviewers, 1 change requested, CI red on iOS. Saved → .pi/chrome-screenshots/ci.png
-You:    [keeps coding — agent never asked you to log in]
-```
-
-`pi-chrome` runs through a small Chrome extension inside the Chrome profile **you already use** — including sites where you're already signed in. Agents can inspect or control Chrome only after you run `/chrome authorize` in current Pi session.
+Built for the [Pi coding agent](https://pi.dev).
 
----
+## What you can do
 
-## Install
+Try prompts like these after setup:
 
-```bash
-pi install npm:pi-chrome
-```
+| Use case | Ask Pi |
+| --- | --- |
+| **Debug a signed-in app** | “Reproduce the filter bug in my staging app. Inspect captured console and network errors, then save a screenshot.” |
+| **Understand an existing page** | “Find my open dashboard tab and summarize what's on the page. Don't change anything.” |
+| **Create evidence for a PR** | “On my local app, capture the empty, loading, and populated states of this feature for my PR.” |
 
-In Pi:
+Pi gets tools to inspect pages, click, type, fill forms, scroll, upload files, capture screenshots, and inspect captured console logs and `fetch`/`XMLHttpRequest` responses. A raw Chrome DevTools Protocol tool (`chrome_cdp`) covers anything else, such as device emulation, cookies, PDFs, or the accessibility tree. You describe the task; Pi handles the agent loop.
 
-```text
-/chrome onboard
-```
+**Best fit:** interactive workflows in the Chrome profile you already use. For deterministic CI tests, consider a test framework such as Playwright; for fleets of isolated browsers, consider a hosted browser service. See [more workflows](./docs/EXAMPLES.md) and [browser-tool comparisons](./docs/COMPARISON.md).
 
-This opens `chrome://extensions` and copies bundled extension path. In Chrome Extensions:
+## Quick start
 
-1. Turn on **Developer mode**.
-2. Click **Load unpacked**.
-3. Open path field with **Cmd+Shift+G** on macOS or **Ctrl+L** on Windows/Linux.
-4. Paste copied path.
-5. Press Enter.
+**Requirements:** [Pi](https://pi.dev) and Google Chrome. Setup includes a one-time manual installation of the bundled Chrome companion extension.
 
-Reload Pi so installed package loads:
+> **Trust and privacy:** The companion has broad browser permissions and runs in your real Chrome profile. Review [its source](./extensions/chrome-profile-bridge/browser-extension/) before loading it, and authorize only tasks you trust. The browser bridge is local, but page content returned to Pi may be sent to your configured model provider.
 
-```text
-/reload
-```
+### 1. Install and load the Pi package
 
-Check bridge:
+In your terminal:
 
-```text
-/chrome doctor
+```bash
+pi install npm:pi-chrome
 ```
 
-You should see:
+Start Pi with `pi`. If Pi is already running, run `/reload` in that session **before** using the `/chrome` commands.
 
-```text
-✓ Chrome is connected (...)
-```
+### 2. Connect Chrome
 
-Authorize current session:
+In Pi:
 
 ```text
-/chrome authorize
-/chrome doctor
+/chrome onboard
 ```
 
-Second doctor run should show all checks passing.
+The setup dialog shows the companion extension's folder path.
 
----
+- **macOS:** after confirmation, Pi opens `chrome://extensions`, reveals the companion folder in Finder, and copies its path to your clipboard.
+- **Windows/Linux:** copy the folder path shown in the dialog and open `chrome://extensions` manually. Automatic desktop opening and clipboard setup are currently macOS-only.
 
-## What it can do
+In Chrome:
 
-- Read and summarize pages you're already signed into.
-- Click, type, fill forms, scroll, drag, tap, and upload files.
-- Capture screenshots for bugs, PRs, and demos.
-- Inspect console logs and captured `fetch`/`XMLHttpRequest` responses.
-- Manage tabs without taking over your active window.
-
-Tool parameters and gotchas are documented inline in Pi.
-
-### Typing into rich editors
-
-`chrome_type` and `chrome_fill` use one native CDP `Input.insertText` operation for focused contenteditables. This avoids per-character delays for long text and preserves Unicode/newlines. Ordinary inputs and textareas retain individual key events.
-
-For an editor that needs a `keydown` for every character, pass `perCharacter:true`. Bulk insertion still uses Chrome's input system, but does not emit per-character key events or a clipboard `paste` event. Use `includeSnapshot:true` to verify the result; `chrome_fill` still honors `domFallback:false` when synthetic fallback is unwanted.
-
----
+1. Turn on **Developer mode**.
+2. Click **Load unpacked**.
+3. Select the companion folder shown by `/chrome onboard`. On macOS, press **Cmd+Shift+G** in the folder picker and paste the copied path.
 
-## Safety model
+### 3. Authorize and verify
 
-Chrome control is locked by default. Authorize per Pi session:
+In Pi:
 
 ```text
-/chrome authorize          # 15 minutes
-/chrome authorize 30m      # custom duration
-/chrome authorize indefinite
-/chrome revoke             # lock again
-/chrome status
+/chrome authorize
+/chrome doctor
 ```
 
-Safety properties:
-
-- Extension runs in your real Chrome profile and has broad tab/scripting permissions. Install only from trusted package source.
-- Pi side binds to `127.0.0.1:17318` only; no default network exposure.
-- Bridge rejects browser-origin command requests, so ordinary web pages cannot drive it through CORS.
-- Each Pi session gets its own automation target; user tabs/windows are not closed by cleanup.
-- `/chrome revoke` closes only calling session's automation target.
-
-Security details: [`SECURITY.md`](./SECURITY.md). Architecture details: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
+Approve the authorization prompt for a task you trust. The default authorization lasts **15 minutes**. Doctor should report `✓ Chrome is connected (...)`; follow its instructions if any checks fail.
 
----
-
-## Commands
+Then try a read-only first task:
 
 ```text
-/chrome onboard             # guided setup
-/chrome doctor              # connectivity + version + eval checks
-/chrome status              # connection + auth + background state
-/chrome authorize [duration]
-/chrome revoke
-/chrome background on       # default: hard background policy
-/chrome background off      # foreground/watch mode
-/chrome background status
+List my open Chrome tabs without navigating, clicking, or changing anything.
 ```
 
-If loaded extension is older than installed `pi-chrome`, `/chrome doctor` tells you to reload it from `chrome://extensions`.
-
-### Background policy
-
-`/chrome background on` is enforced, not an overridable default. Per-call `background:false` cannot bring Chrome forward, new tabs stay inactive, and `chrome_tab activate` is blocked. Use the existing `/chrome background off` for foreground/watch mode; per-call `background:true` still works when that mode is off.
-
-Screenshots use CDP without activating background tabs. Debugger/capture failures return errors, never an activation fallback. Reload both Pi and the Chrome companion after upgrading; old companions reject background tab creation/screenshots rather than silently switching tabs.
+Run `/chrome revoke` when finished. Use `/chrome authorize` again whenever you want to grant access for another task or session.
 
-This prevents explicit pi-chrome focus/activation, not every Chrome/OS side effect. Trusted input, page popups, native prompts, debugger banners, and macOS Spaces can still affect focus. Inactive pages may throttle rendering or reject focus-gated actions. See [scope and risks](./docs/ARCHITECTURE.md#scope-and-risks).
+## Safety
 
----
+- **Per-session approval.** Pi's Chrome tools require `/chrome authorize`. `/chrome revoke` locks them and requests cleanup of that session's owned automation tabs. Cleanup preserves existing user tabs.
+- **Separate targets by default.** Page actions without an explicit target use a session-owned automation window or tab. The agent can deliberately target an existing tab when your task calls for it.
+- **Local transport, not a sandbox.** The bridge binds to `127.0.0.1:17318` and rejects browser-origin command requests. It does not authenticate arbitrary non-browser local callers; it is not protection against hostile processes on your machine.
+- **Background mode:** `/chrome background on` (default) blocks pi-chrome tools from directly bringing Chrome to the front or switching your selected tab. Use `/chrome background off` to allow those actions, and `/chrome background status` to check the setting.
 
-## Limits
+### Limits
 
-`pi-chrome` works best on web-page workflows exposed through DOM, screenshots, tabs, network, console, and Chrome input. It is not full OS automation.
+This is browser automation, not full OS control. Native Chrome/OS dialogs, password-manager prompts, passkeys/security keys/biometrics, CAPTCHA challenges, cross-origin iframe DOM access, rich multitouch/stylus gestures, and arbitrary desktop apps are outside its reliable tool surface. Some workflows need human assistance.
 
-Current limits include native Chrome/OS surfaces, print/save dialogs, permission bubbles, password-manager prompts, cross-origin iframe DOM access, CAPTCHA/bot challenges, passkeys/security keys/biometrics, rich multitouch/pinch/stylus gestures, and arbitrary desktop apps.
+If page inspection or evaluation is blocked, use screenshots and coordinate input where possible. Background pages can throttle rendering or reject focus-gated actions. See the [FAQ](./docs/FAQ.md) for details.
 
-For strict-CSP pages, use screenshots + coordinate input when snapshot/evaluate paths are blocked.
-
----
+## Commands
 
-## Docs
+```text
+/chrome                      # quick connection/auth/background dashboard and controls
+/chrome onboard              # one-time companion setup
+/chrome authorize            # authorize this Pi session for 15 minutes
+/chrome authorize 30m        # choose a duration
+/chrome authorize indefinite # no time limit; revoke when finished
+/chrome revoke               # lock tools and request session cleanup
+/chrome doctor               # full diagnostics, including authorization/background state
+/chrome background on        # default: block explicit focus/tab activation
+/chrome background off       # allow foreground/watch mode
+/chrome background status
+```
 
-- Examples: [`docs/EXAMPLES.md`](./docs/EXAMPLES.md)
-- FAQ: [`docs/FAQ.md`](./docs/FAQ.md)
-- Comparison: [`docs/COMPARISON.md`](./docs/COMPARISON.md)
-- Security: [`SECURITY.md`](./SECURITY.md)
-- Benchmark suite: [`test-suite/README.md`](./test-suite/README.md)
-- Architecture: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)
+Bare `/chrome` checks the connection without running page probes. Use `/chrome doctor` for version and page checks, troubleshooting hints, and authorization/background state.
 
----
+Tool parameters are documented inline in Pi. See [architecture](./docs/ARCHITECTURE.md) for target ownership, screenshot behavior, and background-policy details.
 
-## License
+### Updating and troubleshooting
 
-MIT. See [LICENSE](./LICENSE).
+After `pi update npm:pi-chrome`, run `/reload` in Pi and reload **Pi Chrome Connector** in `chrome://extensions`. Run `/chrome doctor` to check the connection and companion version.

package/SECURITY.md

@@ -27,6 +27,7 @@ The Chrome extension under `extensions/chrome-profile-bridge/browser-extension/`
 - Loopback bridge only. No remote port. No telemetry.
 - Chrome real input layer for interactive controls.
 - Chrome control locked by default; `/chrome authorize` unlocks current Pi session after terminal confirmation, `/chrome revoke` locks it again.
+- `chrome_cdp` sends raw Chrome DevTools Protocol commands to a tab. It is locked behind `/chrome authorize` like every other tool, but it is not filtered against a safe list. Background mode blocks only its explicit focus methods (`Page.bringToFront`, `Target.activateTarget`).
 - Hard background mode is on by default: tools cannot override it to explicitly focus windows or activate tabs. `/chrome background off` allows foreground/watch mode. This is not a security sandbox: trusted input, page scripts, native prompts, and Chrome/OS behavior can still affect focus.
 
 ## Custom ports

package/docs/FAQ.md

@@ -32,6 +32,8 @@ Chrome control is also locked per Pi session until you run `/chrome authorize`;
 
 Yes. The first session opens the local bridge; later sessions detect it and pipe their commands through the same bridge. Each Pi session must be authorized with `/chrome authorize` before its chrome_* tools work. Each session also owns its **own** dedicated automation window (ownership is keyed by session id inside the one extension), so concurrent sessions never navigate into or close each other's tabs.
 
+Subagent sessions that run inside an authorized Pi process (for example with pi-subagents) also get the chrome_* tools. They share the parent's `/chrome authorize` grant and bridge, but each subagent gets its own automation tab and tab group, which are cleaned up when the subagent session ends.
+
 ## Does pi-chrome navigate my current tab?
 
 No. The first chrome_* action that has no explicit target opens a **dedicated automation window** that pi-chrome owns (falling back to a dedicated tab only if a separate window can't be created), and reuses it for the rest of the session. Your existing tabs and windows are never reused or overwritten. Pass `targetId`/`urlIncludes`/`titleIncludes` to deliberately act on a tab you already have open.
@@ -50,7 +52,7 @@ pi-chrome ships as an unpacked extension so the source and broad browser permiss
 
 ## What's the install footprint?
 
-- Pi side: one extension that registers 19 tools and a few slash commands.
+- Pi side: one extension that registers 23 tools and a few slash commands.
 - Chrome side: one unpacked extension, ~2000 LOC of plain JavaScript, no dependencies.
 
 ## Can I script it without Pi?

package/extensions/chrome-profile-bridge/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Pi Chrome Connector",
-  "version": "0.15.49",
+  "version": "0.15.53",
   "description": "Lets Pi control tabs in Chrome via a local connector at 127.0.0.1.",
   "permissions": [
     "tabs",