pi-chrome 0.3.1 → 0.4.0

package/README.md

@@ -1,5 +1,7 @@
 # pi-chrome
 
+[![npm version](https://img.shields.io/npm/v/pi-chrome.svg)](https://www.npmjs.com/package/pi-chrome)
+
 Control the Chrome profile you already use from Pi.
 
 `pi-chrome` gives Pi agents browser tools for your **real Chrome windows, tabs, and authenticated sessions**. It uses a companion Chrome extension instead of the Chrome DevTools Protocol (CDP), so it does not launch a throwaway debug browser profile and does not require re-signing into the apps you already have open.
@@ -9,8 +11,8 @@ Multiple Pi sessions can use Chrome at the same time. The first Pi session start
 ## Why try it?
 
 - **Uses your existing Chrome profile** — works with the Chrome windows/tabs you are already using, including logged-in GitHub, admin dashboards, local apps, and internal tools.
+- **Background by default** — agents can inspect, navigate, click, type, and snapshot without bringing Chrome to the foreground or interrupting whatever you are doing. Toggle for the whole session with `/chrome-foreground`, or pass `foreground: true` on a single tool call.
 - **Full browser automation toolkit for Pi** — list/create/activate/close tabs, snapshot pages with usable CSS selectors, navigate, evaluate JavaScript, click, type, press keys, wait for page state, and capture screenshots.
-- **Background by default** — agents can inspect, navigate, click, type, and snapshot without bringing Chrome to the foreground or interrupting whatever you are doing. Toggle for the whole session with `/chrome-foreground` (useful for demos, pair-driving, debugging) or pass `foreground: true` on a single tool call.
 - **Built-in setup and agent guidance** — `/chrome-onboard` walks users through installing the companion extension, `/chrome-status` checks connectivity, screenshots save to disk, and the prompt primer tells agents to inspect with `chrome_snapshot` before acting and avoid destructive actions unless explicitly requested.
 
 ## Install
@@ -25,6 +27,10 @@ For local development from a checkout:
 pi install ./pi-chrome
 ```
 
+### Why an unpacked Chrome extension?
+
+The Chrome Web Store does not allow extensions that talk to a local bridge controlled by another tool, so `pi-chrome` ships its companion as an unpacked extension you load yourself. The source is small, MIT-licensed, and lives in `extensions/chrome-profile-bridge/browser-extension/` next to this README — read it before loading.
+
 ## First-time setup
 
 In Pi, run:
@@ -57,20 +63,68 @@ Performing Chrome bridge health check
 Chrome profile bridge connected (ID: <chrome-extension-id>)
 ```
 
-## Quick demo prompt
+## Foreground control
+
+By default, `chrome_*` tools act silently in the background — your editor or terminal keeps focus and Chrome does not pop up. This lets agents work alongside you without interrupting whatever you are doing.
 
-After setup, try this in Pi:
+When you want to watch the agent (demos, pair-driving, debugging), turn foreground on for the whole Pi session:
+
+```text
+/chrome-foreground          # toggle
+/chrome-foreground on       # explicit
+/chrome-foreground off      # explicit
+```
+
+For a single tool call, the agent can pass `foreground: true` directly. The per-call value always wins over the session toggle.
+
+## Quick demo prompts
+
+After setup, try one of these in Pi:
+
+Background inspection (no Chrome interruption):
+
+```text
+Inspect my active GitHub tab in the background with chrome_snapshot and summarize the PR state without focusing Chrome.
+```
+
+Existing authenticated tab:
 
 ```text
 Use chrome_tab list to find my existing GitHub tab, chrome_snapshot it, then summarize the visible PR state. Do not click anything yet.
 ```
 
-Or for a local web app repro:
+Local web app repro with screenshot:
 
 ```text
 Use chrome_tab list to find my localhost app, inspect it with chrome_snapshot, navigate through the bug repro flow, and save a screenshot when you reach the broken state.
 ```
 
+## Recipes
+
+Copy-paste these into Pi after setup. Each one uses tabs you already have open and accounts you are already signed into.
+
+- **PR triage:** "Use chrome_tab list to find my GitHub notifications tab, snapshot it, and summarize PRs needing my review."
+- **Linear standup:** "Open my Linear current cycle in the active tab, snapshot it, and write me a 5-bullet standup."
+- **Bug repro with evidence:** "Open the staging app I'm already signed into, reproduce <bug>, and save a screenshot of each step under ./repro/."
+- **Form auto-fill (no submit):** "Open <vendor> portal, fill the new-vendor form from this JSON, but stop before submit."
+- **Admin cross-check:** "Across my Stripe / Postmark / our admin tabs, find any user where state disagrees."
+- **Local dev visual diff:** "Snapshot localhost:3000 and the staging URL of the same page; tell me what's visually different."
+- **Auth-only data pull:** "Open my analytics dashboard tab and chrome_evaluate to extract today's KPIs from the page state."
+
+Screenshots save under `.pi/chrome-screenshots/` by default, which composes nicely with PR demo workflows.
+
+## Diagnostics
+
+- `/chrome-status` — quick health check; reports the connected Chrome extension ID and version.
+- `/chrome-doctor` — deeper diagnosis with one-line fixes for common setup failures (extension not loaded, bridge owner stale after `pi update`, version mismatch between pi-chrome and the loaded Chrome extension).
+
+If the Chrome extension you have loaded is older than `pi-chrome` on disk, `/chrome-doctor` will tell you to reload it from `chrome://extensions`.
+
+## Compose with
+
+- **pi-qq** — ask side questions about what the agent saw in Chrome without polluting the main transcript: `/qq summarize what the active GitHub tab shows`.
+- **PR demo skills** (such as `ios-pr-agent` / `ios-demo-record` workflows) — `chrome_screenshot` writes to `.pi/chrome-screenshots/` so you can attach images to PR descriptions or demo bundles.
+
 ## Tools
 
 The package registers these Pi tools:
@@ -88,7 +142,8 @@ The package registers these Pi tools:
 
 These tools are especially useful for authenticated web app debugging, repro flows, admin workflows, visual checks, and inspecting local development pages without rebuilding login state.
 
-## How it works
+<details>
+<summary><strong>How it works (technical details)</strong></summary>
 
 Pi starts a local bridge on `127.0.0.1:17318`. The companion Chrome extension, installed in your normal Chrome profile, polls that local bridge for commands and executes them using Chrome extension APIs.
 
@@ -96,6 +151,8 @@ If another Pi session is already running the bridge, additional Pi sessions auto
 
 This is intentionally different from CDP-based tools: the browser extension lives inside the profile you already use, so Pi can interact with existing tabs and authenticated page state.
 
+</details>
+
 ## Security model
 
 The companion Chrome extension runs in the Chrome profile where you install it and has broad tab/scripting permissions. Only install it from a package source you trust.

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

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Pi Existing Chrome Profile Bridge",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "Lets Pi control tabs in this existing Chrome profile via a local bridge at 127.0.0.1.",
   "permissions": ["tabs", "scripting", "storage", "activeTab", "alarms"],
   "host_permissions": ["<all_urls>", "http://127.0.0.1:17318/*"],

package/extensions/chrome-profile-bridge/browser-extension/service_worker.js

@@ -80,7 +80,12 @@ function sleep(ms) {
 async function dispatch(action, params) {
   switch (action) {
     case "tab.version":
-      return { extensionId: chrome.runtime.id, bridgeUrl: BRIDGE_URL, userAgent: navigator.userAgent };
+      return {
+        extensionId: chrome.runtime.id,
+        extensionVersion: chrome.runtime.getManifest().version,
+        bridgeUrl: BRIDGE_URL,
+        userAgent: navigator.userAgent,
+      };
     case "tab.list":
       return (await chrome.tabs.query({})).map(formatTab);
     case "tab.new": {

package/extensions/chrome-profile-bridge/index.ts

@@ -46,6 +46,7 @@ type BridgeResult = {
 	error?: string;
 };
 
+const PI_CHROME_VERSION = "0.4.0";
 const DEFAULT_HOST = process.env.PI_CHROME_BRIDGE_HOST ?? "127.0.0.1";
 const DEFAULT_PORT = Number(process.env.PI_CHROME_BRIDGE_PORT ?? "17318");
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -351,19 +352,50 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		handler: async (_args, ctx) => {
 			ctx.ui.notify("Performing Chrome bridge health check", "info");
 			try {
-				const version = (await bridge.send("tab.version", {}, 35_000)) as { extensionId?: string };
-				ctx.ui.notify(
-					version.extensionId
-						? `Chrome profile bridge connected (ID: ${version.extensionId})`
-						: "Chrome profile bridge connected",
-					"info",
-				);
+				const version = (await bridge.send("tab.version", {}, 35_000)) as { extensionId?: string; extensionVersion?: string };
+				const suffix = [version.extensionId ? `ID: ${version.extensionId}` : null, version.extensionVersion ? `ext v${version.extensionVersion}` : null]
+					.filter(Boolean)
+					.join(", ");
+				ctx.ui.notify(suffix ? `Chrome profile bridge connected (${suffix})` : "Chrome profile bridge connected", "info");
 			} catch (error) {
 				ctx.ui.notify(`Chrome bridge health check failed: ${(error as Error).message}`, "warning");
 			}
 		},
 	});
 
+	pi.registerCommand("chrome-doctor", {
+		description:
+			"Diagnose Chrome bridge setup. Checks the local bridge, the companion Chrome extension, and reports a one-line fix for common failures.",
+		handler: async (_args, ctx) => {
+			const lines: string[] = [`pi-chrome v${PI_CHROME_VERSION}`];
+			const status = bridge.status();
+			lines.push(`• Local bridge: mode=${status.mode}, url=${status.url}`);
+			try {
+				const version = (await bridge.send("tab.version", {}, 8_000)) as {
+					extensionId?: string;
+					extensionVersion?: string;
+				};
+				if (version.extensionId)
+					lines.push(`✓ Companion Chrome extension responding (ID: ${version.extensionId}, ext v${version.extensionVersion ?? "unknown"})`);
+				else lines.push("✓ Companion Chrome extension responding (no extension ID reported)");
+				if (version.extensionVersion && version.extensionVersion !== PI_CHROME_VERSION) {
+					lines.push(
+						`⚠ Extension version (${version.extensionVersion}) differs from pi-chrome (${PI_CHROME_VERSION}). Reload "Pi Existing Chrome Profile Bridge" in chrome://extensions to pick up the latest service worker.`,
+					);
+				}
+			} catch (error) {
+				const message = (error as Error).message;
+				lines.push(`✗ Companion Chrome extension not responding: ${message}`);
+				if (message.includes("older pi-chrome without multi-session")) {
+					lines.push("  Fix: restart the Pi session that owns the bridge (it was started on an older pi-chrome).");
+				} else {
+					lines.push("  Fix: run /chrome-onboard, then load the bundled browser-extension folder in chrome://extensions and keep that Chrome window open.");
+				}
+			}
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
 	pi.registerCommand("chrome-foreground", {
 		description:
 			"Toggle whether chrome_* tools bring Chrome to the foreground. Foreground ON: you can watch the agent work in your browser, useful for demos, pair-driving, and debugging — tradeoff: Chrome pops up and steals focus, interrupting whatever app you were using. Foreground OFF (default): chrome_* tools act silently in the background, so your editor/terminal keeps focus and your workflow is not interrupted. Pass `on` / `off` to set explicitly, or no argument to toggle.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-chrome",
-  "version": "0.3.1",
-  "description": "Control your existing authenticated Chrome profile from one or more Pi sessions with tabs, snapshots, clicks, typing, JS evaluation, waits, and screenshots. Background-by-default so Chrome stops popping up when agents act.",
+  "version": "0.4.0",
+  "description": "Control your existing authenticated Chrome profile from Pi with tabs, snapshots, clicks, typing, JS evaluation, waits, and screenshots \u2014 background by default.",
   "keywords": [
     "pi-package",
     "pi-extension",