pi-chrome 0.3.0 → 0.3.1

package/README.md

@@ -10,7 +10,7 @@ Multiple Pi sessions can use Chrome at the same time. The first Pi session start
 
 - **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.
 - **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. Pass `foreground: true` to a tool only when you specifically need Chrome focused.
+- **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

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

@@ -315,6 +315,10 @@ const waitForValues = ["selector", "expression"] as const;
 
 export default function (pi: ExtensionAPI): void {
 	const bridge = new ChromeProfileBridge(DEFAULT_HOST, DEFAULT_PORT);
+	let foregroundDefault = false;
+
+	const withForeground = <T extends Record<string, unknown>>(params: T): T =>
+		({ ...params, foreground: ((params as { foreground?: boolean }).foreground) ?? foregroundDefault }) as T;
 
 	pi.on("session_start", async (_event, ctx) => {
 		await bridge.start();
@@ -337,7 +341,7 @@ export default function (pi: ExtensionAPI): void {
 <chrome-profile-bridge>
 Chrome control is available through the chrome_* tools via a companion Chrome extension installed in the user's normal Chrome profile.
 This is not CDP: it can use the user's existing Chrome windows and authenticated sessions after the user loads the companion browser extension.
-If chrome_* tools time out, ask the user to run /chrome-onboard, then load the bundled browser-extension folder in chrome://extensions. Prefer chrome_snapshot before clicking/typing. Avoid destructive actions unless explicitly requested. By default chrome_* tools run in the background and do not bring Chrome to the foreground; only pass foreground=true when you specifically need Chrome focused (for example, demoing a flow or capturing a screenshot the user should see).
+If chrome_* tools time out, ask the user to run /chrome-onboard, then load the bundled browser-extension folder in chrome://extensions. Prefer chrome_snapshot before clicking/typing. Avoid destructive actions unless explicitly requested. By default chrome_* tools run in the background and do not bring Chrome to the foreground. The user can flip this for the whole session via /chrome-foreground; you can also pass foreground=true on a single tool call when you specifically need Chrome focused (for example, demoing a flow or capturing a screenshot the user should see).
 </chrome-profile-bridge>`;
 		return { systemPrompt: event.systemPrompt + primer };
 	});
@@ -360,6 +364,32 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		},
 	});
 
+	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.",
+		getArgumentCompletions: (prefix) => {
+			const items = [
+				{ value: "on", label: "on", description: "Bring Chrome to the foreground for chrome_* actions" },
+				{ value: "off", label: "off", description: "Run chrome_* actions silently in the background" },
+			];
+			const lowered = prefix.toLowerCase();
+			const matches = items.filter((item) => item.value.startsWith(lowered));
+			return matches.length > 0 ? matches : null;
+		},
+		handler: async (args, ctx) => {
+			const arg = (args || "").trim().toLowerCase();
+			if (arg === "on" || arg === "true" || arg === "1") foregroundDefault = true;
+			else if (arg === "off" || arg === "false" || arg === "0") foregroundDefault = false;
+			else foregroundDefault = !foregroundDefault;
+			ctx.ui.notify(
+				foregroundDefault
+					? "Chrome foreground ON. chrome_* tools will focus Chrome and activate the target tab. Useful for demos and debugging — but Chrome will pop up over whatever you're doing."
+					: "Chrome foreground OFF. chrome_* tools run silently in the background. Your current app keeps focus.",
+				"info",
+			);
+		},
+	});
+
 	pi.registerCommand("chrome-onboard", {
 		description: "Guide Chrome extension setup for the existing-profile bridge",
 		handler: async (_args, ctx) => {
@@ -462,7 +492,11 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const snapshot = await bridge.send("page.snapshot", { ...params, maxElements: params.maxElements ?? MAX_ELEMENTS }, DEFAULT_TIMEOUT_MS);
+			const snapshot = await bridge.send(
+				"page.snapshot",
+				withForeground({ ...params, maxElements: params.maxElements ?? MAX_ELEMENTS }),
+				DEFAULT_TIMEOUT_MS,
+			);
 			return { content: [{ type: "text", text: truncateText(safeJson(snapshot)) }], details: { snapshot } };
 		},
 	});
@@ -487,7 +521,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.navigate", params, params.timeoutMs ?? 15_000);
+			const result = await bridge.send("page.navigate", withForeground(params), params.timeoutMs ?? 15_000);
 			return { content: [{ type: "text", text: `Navigated to ${params.url}` }], details: { result: result as Json } };
 		},
 	});
@@ -512,7 +546,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const value = await bridge.send("page.evaluate", params, DEFAULT_TIMEOUT_MS);
+			const value = await bridge.send("page.evaluate", withForeground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: truncateText(typeof value === "string" ? value : safeJson(value)) }], details: { value: value as Json } };
 		},
 	});
@@ -537,7 +571,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.click", params, DEFAULT_TIMEOUT_MS);
+			const result = await bridge.send("page.click", withForeground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: `Clicked ${params.selector ?? `${params.x},${params.y}`}` }], details: { result: result as Json } };
 		},
 	});
@@ -562,7 +596,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.type", params, DEFAULT_TIMEOUT_MS);
+			const result = await bridge.send("page.type", withForeground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: `Typed ${params.text.length} character(s)${params.selector ? ` into ${params.selector}` : ""}.` }], details: { result: result as Json } };
 		},
 	});
@@ -585,7 +619,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			port: Type.Optional(Type.Number()),
 		}),
 		async execute(_id, params): Promise<ToolTextResult> {
-			const result = await bridge.send("page.key", params, DEFAULT_TIMEOUT_MS);
+			const result = await bridge.send("page.key", withForeground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: `Pressed ${params.key}.` }], details: { result: result as Json } };
 		},
 	});
@@ -637,7 +671,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			const cwd = workspaceCwd(ctx);
 			const defaultPath = join(cwd, ".pi", "chrome-screenshots", `${new Date().toISOString().replace(/[:.]/g, "-")}.${format}`);
 			const outputPath = params.path ? resolve(cwd, params.path) : defaultPath;
-			const result = (await bridge.send("page.screenshot", params, DEFAULT_TIMEOUT_MS)) as { dataUrl: string; tab?: unknown };
+			const result = (await bridge.send("page.screenshot", withForeground(params), DEFAULT_TIMEOUT_MS)) as { dataUrl: string; tab?: unknown };
 			const base64 = result.dataUrl.replace(/^data:image\/(?:png|jpeg);base64,/, "");
 			await mkdir(dirname(outputPath), { recursive: true });
 			await writeFile(outputPath, Buffer.from(base64, "base64"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-chrome",
-  "version": "0.3.0",
+  "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.",
   "keywords": [
     "pi-package",