pi-chrome 0.2.1 → 0.3.0

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. Pass `foreground: true` to a tool only when you specifically need Chrome focused.
 - **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

@@ -318,9 +318,12 @@ export default function (pi: ExtensionAPI): void {
 
 	pi.on("session_start", async (_event, ctx) => {
 		await bridge.start();
+		const status = bridge.status();
 		ctx.ui.setStatus("chrome", `Chrome bridge :${DEFAULT_PORT}`);
 		ctx.ui.notify(
-			`Chrome profile bridge listening at ${bridge.url}. Run /chrome-onboard to load the bundled browser extension in your normal Chrome profile.`,
+			status.mode === "client"
+				? `Chrome profile bridge connected to shared bridge at ${bridge.url}.`
+				: `Chrome profile bridge listening at ${bridge.url}. Run /chrome-onboard to load the bundled browser extension in your normal Chrome profile.`,
 			"info",
 		);
 	});
@@ -334,7 +337,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; only pass foreground=true 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 };
 	});
@@ -445,13 +448,16 @@ 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()),
 		}),
@@ -464,7 +470,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(),
@@ -473,6 +480,9 @@ 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()),
 		}),
@@ -486,7 +496,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(),
@@ -495,6 +505,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 evaluating. Default false." }),
+			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
 		}),
@@ -507,7 +520,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." })),
@@ -516,6 +530,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 clicking. Default false." }),
+			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
 		}),
@@ -528,7 +545,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(),
@@ -537,6 +555,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 typing. Default false." }),
+			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
 		}),
@@ -549,13 +570,17 @@ 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()),
 		}),
@@ -590,7 +615,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>." })),
@@ -600,6 +626,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()),
 		}),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-chrome",
-  "version": "0.2.1",
-  "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.0",
+  "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",