pi-chrome 0.5.0 → 0.6.1

package/README.md

@@ -11,7 +11,7 @@ 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.
+- **Watch your authenticated Chrome work** — by default, `chrome_*` tool calls focus Chrome and activate the target tab so you can see the agent inspect, navigate, click, and type in real time. Switch to silent/background mode for the whole session with `/chrome-background`, or pass `background: true` on a single tool call when you want quiet.
 - **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.
 - **Built-in setup and agent guidance** — `/chrome-onboard` walks users through installing the companion extension, `/chrome-doctor` checks connectivity and version drift, screenshots save to disk, and the prompt primer tells agents to inspect with `chrome_snapshot` before acting and avoid destructive actions unless explicitly requested.
 
@@ -65,28 +65,28 @@ pi-chrome v<version>
 ✓ Companion Chrome extension responding (ID: <chrome-extension-id>, ext v<version>)
 ```
 
-## Foreground control
+## Background mode
 
-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.
+By default, `chrome_*` tools focus Chrome and activate the target tab so you can watch the agent work — great for demos, pair-driving, debugging, and first-time confidence that things are happening.
 
-When you want to watch the agent (demos, pair-driving, debugging), turn foreground on for the whole Pi session:
+When you want quiet (planner / audit / worker sessions running alongside your editor), turn background mode on for the whole Pi session:
 
 ```text
-/chrome-foreground          # toggle
-/chrome-foreground on       # explicit
-/chrome-foreground off      # explicit
+/chrome-background          # toggle
+/chrome-background on       # explicit
+/chrome-background off      # explicit
 ```
 
-For a single tool call, the agent can pass `foreground: true` directly. The per-call value always wins over the session toggle.
+For a single tool call, the agent can pass `background: 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):
+Silent inspection (no Chrome interruption):
 
 ```text
-Inspect my active GitHub tab in the background with chrome_snapshot and summarize the PR state without focusing Chrome.
+Inspect my active GitHub tab with chrome_snapshot using background:true and summarize the PR state without focusing Chrome.
 ```
 
 Existing authenticated tab:

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

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Pi Existing Chrome Profile Bridge",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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

@@ -196,10 +196,26 @@ async function executeInTab(params, func, args) {
   const results = await chrome.scripting.executeScript({
     target: { tabId: tab.id },
     world: "MAIN",
-    func,
-    args,
+    func: async (source, invocationArgs) => {
+      try {
+        const injected = (0, eval)(`(${source})`);
+        return { ok: true, value: await injected(...invocationArgs) };
+      } catch (error) {
+        return { ok: false, error: error?.stack || error?.message || String(error) };
+      }
+    },
+    args: [func.toString(), args],
   });
-  return results?.[0]?.result;
+  const first = results?.[0];
+  if (first?.error) {
+    const message = typeof first.error === "string" ? first.error : (first.error.message || JSON.stringify(first.error));
+    throw new Error(message);
+  }
+  const envelope = first?.result;
+  if (envelope && typeof envelope === "object" && envelope.ok === false) {
+    throw new Error(envelope.error || "Chrome page script failed");
+  }
+  return envelope?.value;
 }
 
 async function bringToFront(tab) {
@@ -307,6 +323,17 @@ function resolvePoint(selector, x, y) {
 }
 
 function clickPage(selector, x, y) {
+  const resolvePoint = (selector, x, y) => {
+    if (selector) {
+      const element = document.querySelector(selector);
+      if (!element) throw new Error(`No element matches selector: ${selector}`);
+      element.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
+      const rect = element.getBoundingClientRect();
+      return { element, x: rect.left + rect.width / 2, y: rect.top + rect.height / 2, rect };
+    }
+    if (typeof x !== "number" || typeof y !== "number") throw new Error("Provide selector or x/y");
+    return { element: document.elementFromPoint(x, y), x, y, rect: undefined };
+  };
   const point = resolvePoint(selector, x, y);
   if (!point.element) throw new Error("No element at click point");
   for (const type of ["pointerdown", "mousedown", "pointerup", "mouseup", "click"]) {
@@ -316,6 +343,28 @@ function clickPage(selector, x, y) {
 }
 
 function typeIntoPage(selector, text, pressEnter) {
+  const normalizeKey = (key) => {
+    const table = {
+      enter: "Enter",
+      escape: "Escape",
+      tab: "Tab",
+      backspace: "Backspace",
+      delete: "Delete",
+      arrowup: "ArrowUp",
+      arrowdown: "ArrowDown",
+      arrowleft: "ArrowLeft",
+      arrowright: "ArrowRight",
+    };
+    return table[String(key).toLowerCase()] || key;
+  };
+  const pressKey = (key) => {
+    const target = document.activeElement || document.body;
+    const normalized = normalizeKey(key);
+    target.dispatchEvent(new KeyboardEvent("keydown", { key: normalized, bubbles: true, cancelable: true }));
+    target.dispatchEvent(new KeyboardEvent("keyup", { key: normalized, bubbles: true, cancelable: true }));
+    if (normalized === "Enter" && target instanceof HTMLFormElement) target.requestSubmit();
+    return { key: normalized };
+  };
   let element = selector ? document.querySelector(selector) : document.activeElement;
   if (!element) throw new Error(selector ? `No element matches selector: ${selector}` : "No active element");
   element.focus();
@@ -331,11 +380,25 @@ function typeIntoPage(selector, text, pressEnter) {
   } else {
     throw new Error("Focused element is not text-editable");
   }
-  if (pressEnter) pressKeyInPage("Enter");
+  if (pressEnter) pressKey("Enter");
   return { selector, length: text.length, pressEnter };
 }
 
 function pressKeyInPage(key) {
+  const normalizeKey = (key) => {
+    const table = {
+      enter: "Enter",
+      escape: "Escape",
+      tab: "Tab",
+      backspace: "Backspace",
+      delete: "Delete",
+      arrowup: "ArrowUp",
+      arrowdown: "ArrowDown",
+      arrowleft: "ArrowLeft",
+      arrowright: "ArrowRight",
+    };
+    return table[String(key).toLowerCase()] || key;
+  };
   const target = document.activeElement || document.body;
   const normalized = normalizeKey(key);
   target.dispatchEvent(new KeyboardEvent("keydown", { key: normalized, bubbles: true, cancelable: true }));

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

@@ -46,7 +46,7 @@ type BridgeResult = {
 	error?: string;
 };
 
-const PI_CHROME_VERSION = "0.5.0";
+const PI_CHROME_VERSION = "0.6.1";
 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;
@@ -339,10 +339,21 @@ 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;
+	let backgroundDefault = false;
+
+	// Translate the public `background` parameter (default false = visible/foreground) into the
+	// service worker's wire-level `foreground` flag, accepting legacy `foreground` as a fallback.
+	const withBackground = <T extends Record<string, unknown>>(params: T): T => {
+		const typed = params as { background?: boolean; foreground?: boolean };
+		const explicit =
+			typed.background !== undefined
+				? typed.background
+				: typed.foreground !== undefined
+					? !typed.foreground
+					: undefined;
+		const background = explicit ?? backgroundDefault;
+		return { ...params, foreground: !background } as T;
+	};
 
 	pi.on("session_start", async (_event, ctx) => {
 		await bridge.start();
@@ -365,7 +376,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. 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).
+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 focus Chrome and activate the target tab so the user can watch the agent work. The user can switch to silent/background mode for the whole session via /chrome-background; you can also pass background=true on a single tool call when the user explicitly wants the action to be silent (for example, scraping while they keep working in another app).
 </chrome-profile-bridge>`;
 		return { systemPrompt: event.systemPrompt + primer };
 	});
@@ -404,13 +415,13 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		},
 	});
 
-	pi.registerCommand("chrome-foreground", {
+	pi.registerCommand("chrome-background", {
 		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.",
+			"Toggle silent/background mode for chrome_* tools. Background ON: chrome_* tools act silently — your editor/terminal keeps focus, Chrome does not pop up, your workflow is not interrupted. Background OFF (default): Chrome focuses and activates the target tab so you can watch the agent work, useful for demos, pair-driving, and debugging — tradeoff: Chrome pops up and steals focus. 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" },
+				{ value: "on", label: "on", description: "Run chrome_* actions silently without focusing Chrome" },
+				{ value: "off", label: "off", description: "Bring Chrome to the foreground for chrome_* actions (default)" },
 			];
 			const lowered = prefix.toLowerCase();
 			const matches = items.filter((item) => item.value.startsWith(lowered));
@@ -418,13 +429,13 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		},
 		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;
+			if (arg === "on" || arg === "true" || arg === "1") backgroundDefault = true;
+			else if (arg === "off" || arg === "false" || arg === "0") backgroundDefault = false;
+			else backgroundDefault = !backgroundDefault;
 			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.",
+				backgroundDefault
+					? "Chrome background mode ON. chrome_* tools will run silently. Your current app keeps focus."
+					: "Chrome background mode OFF. chrome_* tools will focus Chrome and activate the target tab so you can watch the agent work.",
 				"info",
 			);
 		},
@@ -518,15 +529,15 @@ 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. Runs in the background by default; pass foreground=true to bring Chrome to the front first.",
+			"Inspect a page in the user's existing Chrome profile: title, URL, visible body text, viewport, and clickable/focusable elements with CSS selectors. Brings Chrome to the foreground by default so the user can watch; pass background=true to inspect silently.",
 		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." }),
+			background: Type.Optional(
+				Type.Boolean({ description: "If true, run silently in the background without focusing Chrome. Default false (Chrome focuses + tab activates so the user can watch)." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
@@ -534,7 +545,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		async execute(_id, params): Promise<ToolTextResult> {
 			const snapshot = await bridge.send(
 				"page.snapshot",
-				withForeground({ ...params, maxElements: params.maxElements ?? MAX_ELEMENTS }),
+				withBackground({ ...params, maxElements: params.maxElements ?? MAX_ELEMENTS }),
 				DEFAULT_TIMEOUT_MS,
 			);
 			return { content: [{ type: "text", text: truncateText(safeJson(snapshot)) }], details: { snapshot } };
@@ -545,7 +556,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		name: "chrome_navigate",
 		label: "Chrome Navigate",
 		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.",
+			"Navigate an existing Chrome tab to a URL via the companion extension. By default focuses Chrome and activates the tab so the user can watch; pass background=true to navigate silently. Optionally waits for load completion.",
 		promptSnippet: "Navigate a Chrome tab in the user's existing profile.",
 		parameters: Type.Object({
 			url: Type.String(),
@@ -554,14 +565,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." }),
+			background: Type.Optional(
+				Type.Boolean({ description: "If true, navigate silently without focusing Chrome. 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", withForeground(params), params.timeoutMs ?? 15_000);
+			const result = await bridge.send("page.navigate", withBackground(params), params.timeoutMs ?? 15_000);
 			return { content: [{ type: "text", text: `Navigated to ${params.url}` }], details: { result: result as Json } };
 		},
 	});
@@ -570,7 +581,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 (background) and returns JSON-serializable values when possible. Pass foreground=true to also focus Chrome and activate the tab.",
+			"Evaluate JavaScript in an existing Chrome tab through the companion extension. Runs in the page context and returns JSON-serializable values when possible. By default focuses Chrome and activates the tab; pass background=true to evaluate silently.",
 		promptSnippet: "Evaluate JavaScript in the active Chrome tab through the companion extension.",
 		parameters: Type.Object({
 			expression: Type.String(),
@@ -579,14 +590,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." }),
+			background: Type.Optional(
+				Type.Boolean({ description: "If true, evaluate silently without focusing Chrome. 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", withForeground(params), DEFAULT_TIMEOUT_MS);
+			const value = await bridge.send("page.evaluate", withBackground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: truncateText(typeof value === "string" ? value : safeJson(value)) }], details: { value: value as Json } };
 		},
 	});
@@ -595,7 +606,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		name: "chrome_click",
 		label: "Chrome Click",
 		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.",
+			"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; by default Chrome is focused so the user can watch, pass background=true to click silently.",
 		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." })),
@@ -604,14 +615,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." }),
+			background: Type.Optional(
+				Type.Boolean({ description: "If true, click silently without focusing Chrome. 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", withForeground(params), DEFAULT_TIMEOUT_MS);
+			const result = await bridge.send("page.click", withBackground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: `Clicked ${params.selector ?? `${params.x},${params.y}`}` }], details: { result: result as Json } };
 		},
 	});
@@ -620,7 +631,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		name: "chrome_type",
 		label: "Chrome Type",
 		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.",
+			"Focus an optional CSS selector, then type text into an existing Chrome tab through the companion extension. By default focuses Chrome and activates the tab so the user can watch; pass background=true to type silently.",
 		promptSnippet: "Type text into Chrome, optionally focusing a selector first.",
 		parameters: Type.Object({
 			text: Type.String(),
@@ -629,14 +640,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." }),
+			background: Type.Optional(
+				Type.Boolean({ description: "If true, type silently without focusing Chrome. 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", withForeground(params), DEFAULT_TIMEOUT_MS);
+			const result = await bridge.send("page.type", withBackground(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 } };
 		},
 	});
@@ -645,21 +656,21 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		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). Runs in the background by default; pass foreground=true to focus Chrome and activate the tab first.",
+			"Send a keyboard key to an existing Chrome tab (Enter, Escape, Tab, Backspace, Delete, ArrowUp/Down/Left/Right, or one character). By default focuses Chrome and activates the tab so the user can watch; pass background=true to send the key silently.",
 		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." }),
+			background: Type.Optional(
+				Type.Boolean({ description: "If true, send the key silently without focusing Chrome. 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", withForeground(params), DEFAULT_TIMEOUT_MS);
+			const result = await bridge.send("page.key", withBackground(params), DEFAULT_TIMEOUT_MS);
 			return { content: [{ type: "text", text: `Pressed ${params.key}.` }], details: { result: result as Json } };
 		},
 	});
@@ -690,7 +701,7 @@ If chrome_* tools time out, ask the user to run /chrome-onboard, then load the b
 		name: "chrome_screenshot",
 		label: "Chrome Screenshot",
 		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.",
+			"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. By default Chrome is focused and the tab activates so the user can watch; pass background=true to capture silently (the tab is briefly activated within its window for the capture, then the previous active tab is restored).",
 		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>." })),
@@ -700,8 +711,8 @@ 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." }),
+			background: Type.Optional(
+				Type.Boolean({ description: "If true, capture silently without focusing the Chrome window (the target tab is briefly activated within its window for the capture, then restored). Default false." }),
 			),
 			host: Type.Optional(Type.String()),
 			port: Type.Optional(Type.Number()),
@@ -711,7 +722,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", withForeground(params), DEFAULT_TIMEOUT_MS)) as { dataUrl: string; tab?: unknown };
+			const result = (await bridge.send("page.screenshot", withBackground(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.5.0",
-  "description": "Drive your existing logged-in Chrome from Pi \u2014 no re-login, no throwaway profile, background by default.",
+  "version": "0.6.1",
+  "description": "Drive your existing logged-in Chrome from Pi \u2014 no re-login, no throwaway profile, watch the agent work in real time (or toggle quiet background mode).",
   "keywords": [
     "pi-package",
     "pi-extension",