pi-chrome 0.2.2 → 0.3.1

package/README.md

@@ -10,6 +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. 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/browser-extension/service_worker.js

@@ -111,20 +111,35 @@ async function dispatch(action, params) {
       return executeInTab(params, waitForPage, [params.kind, params.value, params.timeoutMs || 10000, params.intervalMs || 250]);
     case "page.navigate": {
       const tab = await getTabByParams(params);
+      if (params.foreground) await bringToFront(tab);
       const wait = params.waitUntilLoad !== false ? waitForTabComplete(tab.id, params.timeoutMs || 15000) : Promise.resolve(undefined);
-      const updated = await chrome.tabs.update(tab.id, { url: params.url, active: true });
+      const updated = await chrome.tabs.update(tab.id, { url: params.url });
       await wait;
       return formatTab(await chrome.tabs.get(updated.id));
     }
     case "page.screenshot": {
       const tab = await getTabByParams(params);
-      await chrome.windows.update(tab.windowId, { focused: true });
-      await chrome.tabs.update(tab.id, { active: true });
-      const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, {
-        format: params.format || "png",
-        quality: params.format === "jpeg" ? params.quality : undefined,
-      });
-      return { dataUrl, tab: formatTab(tab) };
+      if (params.foreground) await bringToFront(tab);
+      // captureVisibleTab requires the target tab to be the active tab in its window. Activate it
+      // without focusing the window so other apps don't get pushed behind Chrome, and restore the
+      // previous active tab afterwards to minimize disruption.
+      let previousActiveId;
+      if (!tab.active) {
+        const activeBefore = await chrome.tabs.query({ active: true, windowId: tab.windowId });
+        previousActiveId = activeBefore[0]?.id;
+        await chrome.tabs.update(tab.id, { active: true });
+      }
+      try {
+        const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, {
+          format: params.format || "png",
+          quality: params.format === "jpeg" ? params.quality : undefined,
+        });
+        return { dataUrl, tab: formatTab(tab) };
+      } finally {
+        if (previousActiveId !== undefined && previousActiveId !== tab.id) {
+          await chrome.tabs.update(previousActiveId, { active: true }).catch(() => undefined);
+        }
+      }
     }
     default:
       throw new Error(`Unknown action: ${action}`);
@@ -168,8 +183,7 @@ async function getTabByParams(params) {
 
 async function executeInTab(params, func, args) {
   const tab = await getTabByParams(params);
-  await chrome.windows.update(tab.windowId, { focused: true });
-  await chrome.tabs.update(tab.id, { active: true });
+  if (params.foreground) await bringToFront(tab);
   const results = await chrome.scripting.executeScript({
     target: { tabId: tab.id },
     world: "MAIN",
@@ -179,6 +193,11 @@ async function executeInTab(params, func, args) {
   return results?.[0]?.result;
 }
 
+async function bringToFront(tab) {
+  await chrome.windows.update(tab.windowId, { focused: true });
+  await chrome.tabs.update(tab.id, { active: true });
+}
+
 function waitForTabComplete(tabId, timeoutMs) {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {

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.
+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) => {
@@ -448,18 +478,25 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		name: "chrome_snapshot",
 		label: "Chrome Snapshot",
 		description:
-			"Inspect a page in the user's existing Chrome profile: title, URL, visible body text, viewport, and clickable/focusable elements with CSS selectors.",
+			"Inspect a page in the user's existing Chrome profile: title, URL, visible body text, viewport, and clickable/focusable elements with CSS selectors. Runs in the background by default; pass foreground=true to bring Chrome to the front first.",
 		promptSnippet: "Inspect the current Chrome page and get CSS selectors for browser automation.",
 		parameters: Type.Object({
 			targetId: Type.Optional(Type.String()),
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
 			maxElements: Type.Optional(Type.Number({ default: MAX_ELEMENTS })),
+			foreground: Type.Optional(
+				Type.Boolean({ description: "If true, focus the Chrome window and activate the tab before inspecting. Default false to avoid interrupting the user." }),
+			),
 			host: Type.Optional(Type.String()),
 			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 } };
 		},
 	});
@@ -467,7 +504,8 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 	pi.registerTool({
 		name: "chrome_navigate",
 		label: "Chrome Navigate",
-		description: "Navigate an existing Chrome tab to a URL via the companion extension. Optionally waits for load completion.",
+		description:
+			"Navigate an existing Chrome tab to a URL via the companion extension. Navigates in the background by default and does not change the user's currently active tab; pass foreground=true to also focus Chrome and activate the tab. Optionally waits for load completion.",
 		promptSnippet: "Navigate a Chrome tab in the user's existing profile.",
 		parameters: Type.Object({
 			url: Type.String(),
@@ -476,11 +514,14 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			titleIncludes: Type.Optional(Type.String()),
 			waitUntilLoad: Type.Optional(Type.Boolean({ default: true })),
 			timeoutMs: Type.Optional(Type.Number({ default: 15_000 })),
+			foreground: Type.Optional(
+				Type.Boolean({ description: "If true, focus the Chrome window and activate the tab before navigating. Default false." }),
+			),
 			host: Type.Optional(Type.String()),
 			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 } };
 		},
 	});
@@ -489,7 +530,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		name: "chrome_evaluate",
 		label: "Chrome Evaluate",
 		description:
-			"Evaluate JavaScript in an existing Chrome tab through the companion extension. Runs in the page context and returns JSON-serializable values when possible.",
+			"Evaluate JavaScript in an existing Chrome tab through the companion extension. Runs in the page context (background) and returns JSON-serializable values when possible. Pass foreground=true to also focus Chrome and activate the tab.",
 		promptSnippet: "Evaluate JavaScript in the active Chrome tab through the companion extension.",
 		parameters: Type.Object({
 			expression: Type.String(),
@@ -498,11 +539,14 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			targetId: Type.Optional(Type.String()),
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
+			foreground: Type.Optional(
+				Type.Boolean({ description: "If true, focus the Chrome window and activate the tab before evaluating. Default false." }),
+			),
 			host: Type.Optional(Type.String()),
 			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 } };
 		},
 	});
@@ -510,7 +554,8 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 	pi.registerTool({
 		name: "chrome_click",
 		label: "Chrome Click",
-		description: "Click a CSS selector or viewport coordinate in an existing Chrome tab through the companion extension.",
+		description:
+			"Click a CSS selector or viewport coordinate in an existing Chrome tab through the companion extension. The click is dispatched as a synthetic DOM event in the background by default; pass foreground=true to focus Chrome and activate the tab first.",
 		promptSnippet: "Click page elements in Chrome by selector or viewport coordinate.",
 		parameters: Type.Object({
 			selector: Type.Optional(Type.String({ description: "CSS selector to click. Prefer selectors from chrome_snapshot." })),
@@ -519,11 +564,14 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			targetId: Type.Optional(Type.String()),
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
+			foreground: Type.Optional(
+				Type.Boolean({ description: "If true, focus the Chrome window and activate the tab before clicking. Default false." }),
+			),
 			host: Type.Optional(Type.String()),
 			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 } };
 		},
 	});
@@ -531,7 +579,8 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 	pi.registerTool({
 		name: "chrome_type",
 		label: "Chrome Type",
-		description: "Focus an optional CSS selector, then type text into an existing Chrome tab through the companion extension.",
+		description:
+			"Focus an optional CSS selector, then type text into an existing Chrome tab through the companion extension. Runs in the background by default; pass foreground=true to focus Chrome and activate the tab first.",
 		promptSnippet: "Type text into Chrome, optionally focusing a selector first.",
 		parameters: Type.Object({
 			text: Type.String(),
@@ -540,11 +589,14 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			targetId: Type.Optional(Type.String()),
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
+			foreground: Type.Optional(
+				Type.Boolean({ description: "If true, focus the Chrome window and activate the tab before typing. Default false." }),
+			),
 			host: Type.Optional(Type.String()),
 			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 } };
 		},
 	});
@@ -552,18 +604,22 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 	pi.registerTool({
 		name: "chrome_key",
 		label: "Chrome Key",
-		description: "Send a keyboard key to an existing Chrome tab (Enter, Escape, Tab, Backspace, Delete, ArrowUp/Down/Left/Right, or one character).",
+		description:
+			"Send a keyboard key to an existing Chrome tab (Enter, Escape, Tab, Backspace, Delete, ArrowUp/Down/Left/Right, or one character). Runs in the background by default; pass foreground=true to focus Chrome and activate the tab first.",
 		promptSnippet: "Press keys in Chrome through the companion extension.",
 		parameters: Type.Object({
 			key: Type.String(),
 			targetId: Type.Optional(Type.String()),
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
+			foreground: Type.Optional(
+				Type.Boolean({ description: "If true, focus the Chrome window and activate the tab before sending the key. Default false." }),
+			),
 			host: Type.Optional(Type.String()),
 			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 } };
 		},
 	});
@@ -593,7 +649,8 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 	pi.registerTool({
 		name: "chrome_screenshot",
 		label: "Chrome Screenshot",
-		description: "Capture a screenshot of an existing Chrome tab via the companion extension and save it to disk.",
+		description:
+			"Capture a screenshot of an existing Chrome tab via the companion extension and save it to disk. Chrome's extension screenshot API requires the target tab to be the active tab in its window, so this momentarily activates it (without focusing the window) and restores the previous active tab. Pass foreground=true to also bring the Chrome window to the front.",
 		promptSnippet: "Capture Chrome screenshots and save them under .pi/chrome-screenshots by default.",
 		parameters: Type.Object({
 			path: Type.Optional(Type.String({ description: "Output path. Defaults to .pi/chrome-screenshots/<timestamp>.<format>." })),
@@ -603,6 +660,9 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 			targetId: Type.Optional(Type.String()),
 			urlIncludes: Type.Optional(Type.String()),
 			titleIncludes: Type.Optional(Type.String()),
+			foreground: Type.Optional(
+				Type.Boolean({ description: "If true, focus the Chrome window and activate the tab before capturing. Default false." }),
+			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
 		}),
@@ -611,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,7 +1,7 @@
 {
   "name": "pi-chrome",
-  "version": "0.2.2",
-  "description": "Control your existing authenticated Chrome profile from one or more Pi sessions with tabs, snapshots, clicks, typing, JS evaluation, waits, and screenshots.",
+  "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",
     "pi-extension",