aboutsummaryrefslogtreecommitdiff
path: root/extensions/chrome-profile-bridge
diff options
context:
space:
mode:
Diffstat (limited to 'extensions/chrome-profile-bridge')
-rw-r--r--extensions/chrome-profile-bridge/browser-extension/service_worker.js427
-rw-r--r--extensions/chrome-profile-bridge/index.ts118
2 files changed, 396 insertions, 149 deletions
diff --git a/extensions/chrome-profile-bridge/browser-extension/service_worker.js b/extensions/chrome-profile-bridge/browser-extension/service_worker.js
index 1f178e4..85be0a2 100644
--- a/extensions/chrome-profile-bridge/browser-extension/service_worker.js
+++ b/extensions/chrome-profile-bridge/browser-extension/service_worker.js
@@ -226,35 +226,34 @@ function isPiChromeOwnedTarget(tabId, sessionKey) {
return false;
}
-// Create a fresh automation target for `sessionKey`. If this session already has a tab group,
-// create the tab inside that group's window so one Pi session keeps one Chrome tab group (Chrome
-// groups cannot span windows). If no group exists yet, prefer an isolated window; fall back to a
-// tab. When the tab is created in a pre-existing group window, leave windowId unset so cleanup only
-// closes our tab, never that whole window.
+// The window agents' tabs go in: the user's last focused normal window, so every session's tabs
+// sit together in one window (as tab groups) instead of a window each. An inactive tab still takes
+// trusted input and renders screenshots (measured 2026-11-14), so sharing a window costs nothing.
+// Null when no normal window is open; the caller then creates one.
+async function agentWindowId() {
+ if (typeof chrome.windows?.getLastFocused !== "function") return null;
+ const win = await chrome.windows.getLastFocused({ windowTypes: ["normal"] }).catch(() => null);
+ if (win && typeof win.id === "number" && !win.incognito) return win.id;
+ const all = typeof chrome.windows.getAll === "function" ? await chrome.windows.getAll({ windowTypes: ["normal"] }).catch(() => []) : [];
+ const other = all.find((w) => typeof w.id === "number" && !w.incognito);
+ return other ? other.id : null;
+}
+
+// Create a fresh automation target for `sessionKey`: an inactive tab in the session's group's
+// window if it has a group (Chrome groups cannot span windows), else in the user's window. A new
+// window only when the browser has none. When the tab goes in a pre-existing window, windowId stays unset.
async function createAutomationTarget(sessionKey, groupTitle) {
const existingGroup = groupTitle ? await findGroupRecordByTitle(groupTitle) : null;
- if (existingGroup && typeof existingGroup.windowId === "number") {
- const tab = await chrome.tabs.create({ url: "about:blank", active: false, windowId: existingGroup.windowId });
- automationTargets.set(sessionKey, { windowId: undefined, tabId: typeof tab.id === "number" ? tab.id : undefined });
+ const windowId = existingGroup && typeof existingGroup.windowId === "number" ? existingGroup.windowId : await agentWindowId();
+ if (windowId === null && typeof chrome.windows?.create === "function") {
+ const win = await chrome.windows.create({ url: "about:blank", focused: false });
+ const created = win && Array.isArray(win.tabs) ? win.tabs[0] : undefined;
+ if (!created || typeof created.id !== "number") throw new Error("Chrome created a window without a tab");
+ automationTargets.set(sessionKey, { windowId: typeof win.id === "number" ? win.id : undefined, tabId: created.id });
await persistAutomationTargets();
- return tab;
+ return created;
}
- if (chrome.windows && typeof chrome.windows.create === "function") {
- try {
- const win = await chrome.windows.create({ url: "about:blank", focused: false });
- const created = win && Array.isArray(win.tabs) ? win.tabs[0] : undefined;
- if (created && typeof created.id === "number") {
- automationTargets.set(sessionKey, { windowId: typeof win.id === "number" ? win.id : undefined, tabId: created.id });
- await persistAutomationTargets();
- return created;
- }
- } catch {
- // Window creation can fail (policy, headless, etc.); fall back to a dedicated tab below.
- }
- }
- // Tab fallback: the tab lives in a pre-existing (user/shared) window we did NOT create, so we
- // must leave windowId unset — cleanup then closes only our tab, never the user's window.
- const tab = await chrome.tabs.create({ url: "about:blank", active: false });
+ const tab = await chrome.tabs.create({ url: "about:blank", active: false, ...(windowId !== null ? { windowId } : {}) });
automationTargets.set(sessionKey, { windowId: undefined, tabId: typeof tab.id === "number" ? tab.id : undefined });
await persistAutomationTargets();
return tab;
@@ -430,6 +429,7 @@ async function attachDebugger(tabId) {
if (err) err = await retryPageTargetIfExtensionBlocked(err, "attach-page-target-retry3");
if (err) {
recordAttachEvent({ kind: "attach-retry2-failed", tabId, message: String(err.message || err), tabUrl: tabSnapshot?.url });
+ if (FOREIGN_EXTENSION_BLOCK.test(String(err.message || err))) throw await overlayBlockedError(tabId);
const meta = await describeInputTarget(tabId);
throw new Error(`Chrome debugger attach failed for tab ${tabId}: ${String(err.message || err)}${targetMetaSuffix(meta)}`);
}
@@ -439,6 +439,13 @@ async function attachDebugger(tabId) {
// Seed pointer in a plausible "just left the address bar" location.
const entry = { detachAt: Date.now() + INPUT_IDLE_DETACH_MS, pointer: { x: 120 + Math.random() * 200, y: 80 + Math.random() * 120 }, debuggee: attachedDebuggee || { tabId } };
attachedTabs.set(tabId, entry);
+ // Page events are what tell us a page opened a dialog; without them nobody answers it.
+ // Agents' tabs are usually inactive, so also let the page believe it has focus: menus and pickers
+ // that close on blur stay open. Ends when the debugger detaches.
+ await Promise.all([
+ cdpRaw(tabId, "Page.enable", {}).catch(() => undefined),
+ cdpRaw(tabId, "Emulation.setFocusEmulationEnabled", { enabled: true }).catch(() => undefined),
+ ]);
return entry;
}
@@ -476,10 +483,12 @@ async function inputDebug(params) {
};
}
-// Chrome drops trusted CDP input to hidden pages: mouse presses and keys are silently ignored and
-// mouse moves can hang waiting for a frame. A page is hidden when its tab is inactive, its window is
-// minimized, or (macOS) its window became a native window-tab behind a full-screen window. Check
-// before sending input so the caller gets an actionable error instead of a false success.
+// A page is hidden when its tab is inactive, its window is minimized, or (macOS) its window is
+// covered or on another Space. Measured 2026-11-14 in Brave: an inactive tab still takes trusted
+// CDP clicks, key presses, text and mouse moves, and screenshots render it live; only mouseWheel
+// hangs waiting for a frame that never comes, so chrome.scroll scrolls hidden pages by script.
+// Clicks, text, key presses and screenshots measured the same in Chrome 157 on 2026-11-18.
+// A minimized window is untested, so input there still fails up front with an actionable error.
async function pageVisibilityState(tabId) {
try {
const evaluated = await cdp(tabId, "Runtime.evaluate", { expression: "document.visibilityState", returnByValue: true });
@@ -497,8 +506,20 @@ function hiddenTabReason(tab, win) {
return "its window is covered by another window or is on another Space (Chrome treats fully covered windows as hidden)";
}
+// The tab and window when trusted input to the page may be dropped (hidden in a minimized window),
+// else null.
+async function inputRefusingWindow(tab) {
+ if ((await pageVisibilityState(tab.id)) !== "hidden") return null;
+ const fresh = await chrome.tabs.get(tab.id).catch(() => tab);
+ const win = typeof chrome.windows?.get === "function" ? await chrome.windows.get(fresh?.windowId ?? tab.windowId).catch(() => null) : null;
+ return win?.state === "minimized" ? { fresh, win } : null;
+}
+
async function assertTabVisibleForInput(tab, params, label) {
- let state = await pageVisibilityState(tab.id);
+ const refusing = await inputRefusingWindow(tab);
+ if (!refusing) return;
+ const { fresh, win } = refusing;
+ let state = "hidden";
if (state !== "hidden") return;
if (foregroundRequested(params)) {
// bringToFront just ran; give Chrome a moment to report the page visible.
@@ -508,11 +529,9 @@ async function assertTabVisibleForInput(tab, params, label) {
}
if (state !== "hidden") return;
}
- const fresh = await chrome.tabs.get(tab.id).catch(() => tab);
- const win = typeof chrome.windows?.get === "function" ? await chrome.windows.get(fresh?.windowId ?? tab.windowId).catch(() => null) : null;
const error = new Error(
- `${label}: tab ${tab.id} is hidden because ${hiddenTabReason(fresh, win)}. Chrome ignores trusted input to hidden pages, so the events would be dropped. ` +
- `Pass background:false for this call (or run /chrome background off) to bring the tab forward. chrome_click and chrome_fill can instead use their DOM fallback (untrusted page events).`,
+ `${label}: tab ${tab.id} is hidden because ${hiddenTabReason(fresh, win)}. Input to a minimized window may be dropped. ` +
+ `Pass background:false for this call to bring the tab forward. chrome_click and chrome_fill can instead use their DOM fallback (untrusted page events).`,
);
error.hiddenTab = true;
error.windowState = win?.state;
@@ -610,27 +629,36 @@ async function executeScriptWithFallback(options, label) {
if (!isScriptingAccessDenied(error) || !chrome.debugger) throw error;
const tabId = options?.target?.tabId;
recordAttachEvent({ kind: "scripting-denied-cdp-fallback", tabId, files: options?.files || null, message: String(error?.message || error).slice(0, 300) });
- if (Array.isArray(options?.files) && options.files.length) {
- for (const file of options.files) {
- if (!packagedFileSources.has(file)) {
- const response = await fetch(chrome.runtime.getURL(file));
- if (!response.ok) throw new Error(`Could not read ${file} for CDP injection (HTTP ${response.status})`);
- packagedFileSources.set(file, await response.text());
- }
- const injected = await cdpEval(tabId, packagedFileSources.get(file));
- if (injected.exceptionDetails) {
- throw new Error(`${label || file}: ${cdpExceptionText(injected.exceptionDetails) || "CDP injection failed"}`);
- }
+ return executeScriptViaCdp(options, label);
+ }
+}
+
+// The CDP half of executeScriptWithFallback, also used directly when scripting silently runs
+// nothing: a document served with CSP `sandbox` (no allow-scripts), such as
+// raw.githubusercontent.com, makes chrome.scripting.executeScript resolve with a null result
+// instead of throwing, while Runtime.evaluate still works there.
+async function executeScriptViaCdp(options, label) {
+ const tabId = options?.target?.tabId;
+ if (Array.isArray(options?.files) && options.files.length) {
+ for (const file of options.files) {
+ if (!packagedFileSources.has(file)) {
+ const response = await fetch(chrome.runtime.getURL(file));
+ if (!response.ok) throw new Error(`Could not read ${file} for CDP injection (HTTP ${response.status})`);
+ packagedFileSources.set(file, await response.text());
+ }
+ const injected = await cdpEval(tabId, packagedFileSources.get(file));
+ if (injected.exceptionDetails) {
+ throw new Error(`${label || file}: ${cdpExceptionText(injected.exceptionDetails) || "CDP injection failed"}`);
}
- return [{ result: undefined }];
- }
- const expression = `(${options.func.toString()})(...${JSON.stringify(Array.isArray(options.args) ? options.args : [])})`;
- const result = await cdpEval(tabId, expression);
- if (result.exceptionDetails) {
- throw new Error(`${label || "page script"}: ${cdpExceptionText(result.exceptionDetails) || "evaluation failed"}`);
}
- return [{ result: result.result?.value }];
+ return [{ result: undefined }];
+ }
+ const expression = `(${options.func.toString()})(...${JSON.stringify(Array.isArray(options.args) ? options.args : [])})`;
+ const result = await cdpEval(tabId, expression);
+ if (result.exceptionDetails) {
+ throw new Error(`${label || "page script"}: ${cdpExceptionText(result.exceptionDetails) || "evaluation failed"}`);
}
+ return [{ result: result.result?.value }];
}
// Wraps cdpRaw with one auto-recover on detached/closed sessions:
@@ -656,6 +684,12 @@ async function findForeignExtensionTargets() {
}
}
+// Other extensions' targets that belong to this tab: by the target's tabId, or by the tabId that
+// password managers put in the frame's own URL (the frame target can come without a tabId).
+function foreignTargetsForTab(all, tabId) {
+ return all.filter((t) => t.tabId === tabId || new RegExp(`[?&]tabId=${tabId}(?:[&#]|$)`).test(String(t.url || "")));
+}
+
function extractForeignExtId(targets) {
for (const t of targets) {
if (t.extensionId && t.extensionId !== chrome.runtime.id) return t.extensionId;
@@ -665,14 +699,90 @@ function extractForeignExtId(targets) {
return null;
}
-async function dismissOverlayViaEscape(tabId) {
- // Esc routes through key dispatcher (target-by-focus), not by mouse coordinates, so it
- // works even when a foreign chrome-extension popup is intercepting pointer events.
+const FOREIGN_EXTENSION_BLOCK = /Cannot access a chrome-extension:\/\/ URL of different extension/i;
+
+// Another extension's frame on the page (a password manager's inline prompt, an autofill menu)
+// makes Chrome refuse the debugger on that tab. Nothing is closed automatically: the user may be
+// using the prompt (signing in, approving something for the agent). The error gives the agent the
+// facts and lets it decide, with overlay.clear (chrome_clear_overlay) to close it when it is only
+// in the way.
+async function overlayBlockedError(tabId) {
+ const targets = foreignTargetsForTab(await findForeignExtensionTargets(), tabId);
+ const url = String(targets[0]?.url || "").replace(/[?#].*$/, "");
+ const id = extractForeignExtId(targets) || "unknown";
+ return new Error(
+ `Another extension (${id}${url ? `, ${url}` : ""}) has a prompt open on this tab, probably a password manager such as 1Password, and Chrome will not let the debugger work on the tab while it is there. ` +
+ `If it is only in your way, call chrome_clear_overlay for this tab. If you are waiting for the user to sign in or approve something with it, leave it alone and tell the user. Navigating the tab away also frees it.`,
+ );
+}
+
+// Injected into the page by overlay.clear, in the extension's isolated world: only there can
+// chrome.dom.openOrClosedShadowRoot read a closed shadow root, and password managers put their
+// frame in one (1Password: a <com-1password-uso> element with the frame inside; there is no iframe
+// in the page's own DOM). Removes every element whose shadow root holds another extension's
+// iframe, plus loose foreign iframes, then blurs the focused field and sends Escape.
+function clearForeignOverlays(ownId) {
+ const removed = [];
+ const isForeignFrame = (el) => el.tagName === "IFRAME" && /^chrome-extension:\/\//.test(el.src) && !el.src.startsWith(`chrome-extension://${ownId}/`);
+ const rootOf = (el) => {
+ try {
+ return (typeof chrome !== "undefined" && chrome.dom && chrome.dom.openOrClosedShadowRoot ? chrome.dom.openOrClosedShadowRoot(el) : null) || el.shadowRoot;
+ } catch {
+ return el.shadowRoot;
+ }
+ };
+ // Returns the foreign frame URLs found inside `root`, looking through nested shadow roots.
+ const framesIn = (root) => {
+ const found = [];
+ for (const el of Array.from(root.querySelectorAll("*"))) {
+ if (isForeignFrame(el)) found.push(el.src.replace(/[?#].*$/, ""));
+ const inner = rootOf(el);
+ if (inner) found.push(...framesIn(inner));
+ }
+ return found;
+ };
+ for (const el of Array.from(document.querySelectorAll("*"))) {
+ if (!el.isConnected) continue;
+ if (isForeignFrame(el)) {
+ removed.push(el.src.replace(/[?#].*$/, ""));
+ el.remove();
+ continue;
+ }
+ const root = rootOf(el);
+ const frames = root ? framesIn(root) : [];
+ if (frames.length > 0) {
+ removed.push(`<${el.tagName.toLowerCase()}> holding ${frames.join(", ")}`);
+ el.remove();
+ }
+ }
+ const active = document.activeElement;
+ if (active && active !== document.body && typeof active.blur === "function") active.blur();
+ document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", code: "Escape", bubbles: true }));
+ const custom = Array.from(document.querySelectorAll("*")).filter((el) => el.tagName.includes("-")).map((el) => el.tagName.toLowerCase());
+ return { removed, seen: { iframes: document.querySelectorAll("iframe").length, customElements: [...new Set(custom)].slice(0, 10), active: document.activeElement?.tagName ?? null } };
+}
+
+async function clearOverlay(params) {
+ const tab = await getTabByParams(params, { createOwnedTarget: false });
+ let injected = { removed: [] };
try {
- await cdpRaw(tabId, "Input.dispatchKeyEvent", { type: "keyDown", key: "Escape", code: "Escape", windowsVirtualKeyCode: 27 });
- await cdpRaw(tabId, "Input.dispatchKeyEvent", { type: "keyUp", key: "Escape", code: "Escape", windowsVirtualKeyCode: 27 });
- await sleep(120);
- } catch {}
+ const [first] = await executeScriptTimed({ target: { tabId: tab.id, frameIds: [0] }, func: clearForeignOverlays, args: [chrome.runtime.id] }, "chrome_clear_overlay");
+ injected = first?.result ?? injected;
+ } catch (error) {
+ throw new Error(`Could not run the clean-up on tab ${tab.id}: ${error?.message || error}`);
+ }
+ // The prompt takes a moment to go: try the debugger for up to about a second.
+ let debuggerAttachable = false;
+ for (let attempt = 0; attempt < 6 && !debuggerAttachable; attempt++) {
+ await sleep(attempt === 0 ? 150 : 200);
+ try {
+ await attachDebugger(tab.id);
+ debuggerAttachable = true;
+ } catch {}
+ }
+ const allForeign = await findForeignExtensionTargets();
+ const remaining = foreignTargetsForTab(allForeign, tab.id).map((t) => String(t.url || "").replace(/[?#].*$/, ""));
+ return { tab: { id: tab.id, url: tab.url, title: tab.title }, removedFrames: injected.removed, remainingForeignTargets: remaining, foreignTargetsAnywhere: allForeign.map((t) => ({ type: t.type, tabId: t.tabId, url: String(t.url || "").replace(/[?#].*$/, "") })).slice(0, 20), injectedReport: injected, debuggerAttachable, cleared: debuggerAttachable && remaining.length === 0 };
}
async function cdp(tabId, method, params, opts) {
@@ -681,28 +791,8 @@ async function cdp(tabId, method, params, opts) {
} catch (error) {
const msg = String(error?.message || error);
const isStale = /Debugger is not attached|Detached while|Target closed|No tab with id/i.test(msg);
- const isForeignExtBlock = /Cannot access a chrome-extension:\/\/ URL of different extension/i.test(msg);
- if (isForeignExtBlock && /Input\./.test(method)) {
- // Foreign chrome-extension popup (autofill, password manager) is hijacking input.
- // Try once: dismiss via Esc, then retry.
- const before = await findForeignExtensionTargets();
- recordAttachEvent({ kind: "foreign-ext-detected", tabId, method, foreignExtId: extractForeignExtId(before), targetCount: before.length });
- await dismissOverlayViaEscape(tabId);
- try {
- return await cdpRaw(tabId, method, params, opts);
- } catch (retryErr) {
- const retryMsg = String(retryErr?.message || retryErr);
- if (/Cannot access a chrome-extension:\/\/ URL of different extension/i.test(retryMsg)) {
- const after = await findForeignExtensionTargets();
- const id = extractForeignExtId(after) || extractForeignExtId(before) || "unknown";
- throw new Error(
- `Another Chrome extension (${id}) has an input overlay on this page (e.g. a password manager / autofill popup). \n` +
- `pi-chrome tried to dismiss it with Escape but it reappeared. Disable that extension on this page, close its popup, or focus the field via Tab instead of clicking.`,
- );
- }
- throw retryErr;
- }
- }
+ const isForeignExtBlock = FOREIGN_EXTENSION_BLOCK.test(msg);
+ if (isForeignExtBlock) throw await overlayBlockedError(tabId);
if (!isStale) throw error;
attachedTabs.delete(tabId);
await attachDebugger(tabId).catch(() => undefined);
@@ -1293,6 +1383,22 @@ async function chromeInputFill(params) {
}
}
+// Runs in the page: scroll the innermost scrollable element under (x, y), else the document.
+function scrollHiddenPage(x, y, dx, dy) {
+ const canScroll = (el) => {
+ const style = getComputedStyle(el);
+ const yOk = dy !== 0 && /(auto|scroll|overlay)/.test(style.overflowY) && el.scrollHeight > el.clientHeight;
+ const xOk = dx !== 0 && /(auto|scroll|overlay)/.test(style.overflowX) && el.scrollWidth > el.clientWidth;
+ return yOk || xOk;
+ };
+ let el = document.elementFromPoint(x, y);
+ while (el && el !== document.body && el !== document.documentElement && !canScroll(el)) el = el.parentElement;
+ const target = el && el !== document.body && el !== document.documentElement ? el : (document.scrollingElement || document.documentElement);
+ const before = { x: target.scrollLeft, y: target.scrollTop };
+ target.scrollBy({ left: dx, top: dy, behavior: "instant" });
+ return { scrolled: target === document.scrollingElement ? "document" : (target.tagName || "").toLowerCase(), before, after: { x: target.scrollLeft, y: target.scrollTop } };
+}
+
async function chromeInputScroll(params) {
const tab = await getTabByParams(params);
await bringToFront(tab, params);
@@ -1302,6 +1408,14 @@ async function chromeInputScroll(params) {
const x = resolved.rect ? resolved.rect.left + Math.min(resolved.rect.width, 800) / 2 : resolved.x;
const y = resolved.rect ? resolved.rect.top + Math.min(resolved.rect.height, 600) / 2 : resolved.y;
const totalY = params.deltaY || 0, totalX = params.deltaX || 0;
+ // Chrome never answers a mouseWheel sent to a hidden page, so scroll it by script instead.
+ if ((await pageVisibilityState(tab.id)) === "hidden") {
+ const evaluated = await cdp(tab.id, "Runtime.evaluate", {
+ expression: `(${scrollHiddenPage.toString()})(${JSON.stringify(x)}, ${JSON.stringify(y)}, ${JSON.stringify(totalX)}, ${JSON.stringify(totalY)})`,
+ returnByValue: true,
+ });
+ return { input: "script", reason: "tab is hidden (not the window's active tab), where Chrome drops scroll-wheel events", deltaX: totalX, deltaY: totalY, ...(evaluated?.result?.value || {}) };
+ }
// Profile mimics a trackpad flick: short ramp-up (~15% of events), then geometric decay
// with a ~12% drop per event. Gives momentum tail tests something to find, and the small
// tail deltas (a handful of <20px events) put IntersectionObserver thresholds in range.
@@ -1402,7 +1516,35 @@ function fileChooserTabIdForSource(source) {
return undefined;
}
+// Dialogs a page opens (alert, confirm, prompt, and the "Leave site?" prompt of a beforeunload
+// handler) block the tab until someone answers, and the agent cannot see them. We answer them:
+// "stay"/cancel, unless page.navigate was told leaveIfAsked and it is a beforeunload prompt.
+// page.navigate waits on dialogWaiters to report a dismissed one instead of timing out.
+const dialogPolicy = new Map(); // tabId -> { leave: boolean }, only while page.navigate runs
+const dialogWaiters = new Map(); // tabId -> resolve(dialog), only while page.navigate runs
+
+function describeDialog(dialog) {
+ if (dialog.type === "beforeunload") return 'a "Leave site? Changes you made may not be saved" prompt (the page has a beforeunload handler)';
+ return `a JavaScript ${dialog.type} dialog saying "${dialog.message}"`;
+}
+
+async function handleDialogOpening(tabId, params) {
+ const leave = params?.type === "beforeunload" && dialogPolicy.get(tabId)?.leave === true;
+ const dialog = { type: params?.type, message: params?.message ?? "", url: params?.url, accepted: leave };
+ try {
+ await cdp(tabId, "Page.handleJavaScriptDialog", { accept: leave });
+ } catch (error) {
+ console.warn(`[pi-chrome] could not answer a ${dialog.type} dialog on tab ${tabId}: ${error?.message || error}`);
+ }
+ if (!leave) dialogWaiters.get(tabId)?.(dialog);
+}
+
function handleDebuggerEvent(source, method, params) {
+ if (method === "Page.javascriptDialogOpening") {
+ const dialogTabId = fileChooserTabIdForSource(source);
+ if (dialogTabId !== undefined) void handleDialogOpening(dialogTabId, params);
+ return;
+ }
if (method !== "Page.fileChooserOpened") return;
const tabId = fileChooserTabIdForSource(source);
const entry = tabId === undefined ? undefined : pendingFileChoosers.get(tabId);
@@ -1524,11 +1666,12 @@ async function chromeInputUpload(params) {
}
// The target opens the native picker when clicked. Intercept the chooser so no OS dialog appears,
-// then attach the files to the input Chrome reports. The click is trusted Chrome input when the page
-// is visible; a hidden page drops trusted input, so there we call element.click() with a CDP user
-// gesture instead (an untrusted event, like chrome_click's DOM fallback) unless domFallback:false.
+// then attach the files to the input Chrome reports. The click is trusted Chrome input, also on an
+// inactive tab; in a minimized window, where trusted input may be dropped, we call element.click()
+// with a CDP user gesture instead (an untrusted event, like chrome_click's DOM fallback) unless
+// domFallback:false.
async function uploadViaFileChooser(tab, params, paths, objectId, info) {
- const hidden = (await pageVisibilityState(tab.id)) === "hidden";
+ const hidden = Boolean(await inputRefusingWindow(tab));
if (hidden && params.domFallback === false) await assertTabVisibleForInput(tab, params, "chrome.upload");
await cdp(tab.id, "Page.enable", {});
await cdp(tab.id, "Page.setInterceptFileChooserDialog", { enabled: true });
@@ -1554,7 +1697,7 @@ async function uploadViaFileChooser(tab, params, paths, objectId, info) {
input: "chrome",
mode: "file-chooser",
trigger,
- reason: trigger === "activation-click" ? "target tab is hidden; Chrome drops trusted input to hidden pages" : undefined,
+ reason: trigger === "activation-click" ? "target tab is hidden in a minimized window, where trusted input may be dropped" : undefined,
inFrame: info.inFrame || undefined,
uploaded: paths.map((path) => ({ path })),
};
@@ -1753,17 +1896,25 @@ async function groupTab(tab, title, color) {
if (!tab || typeof tab.id !== "number") throw new Error("No tab to group");
const groupTitle = cleanGroupTitle(title);
let groupId = tab.groupId;
+ let createdGroup = false;
if (typeof groupId !== "number" || groupId < 0) {
// Some browsers omit windowId on freshly created tabs; read it back instead of guessing.
const windowId = typeof tab.windowId === "number" ? tab.windowId : (await chrome.tabs.get(tab.id).catch(() => null))?.windowId;
const existing = await findGroupByTitle(windowId, groupTitle);
// Without createProperties.windowId Chrome creates the group in the *current* (user's) window
// and moves the tab there, pulling Pi's automation tab out of its own window as a hidden tab.
+ createdGroup = existing === null;
groupId = existing !== null
? await chrome.tabs.group({ groupId: existing, tabIds: [tab.id] })
: await chrome.tabs.group(typeof windowId === "number" ? { tabIds: [tab.id], createProperties: { windowId } } : { tabIds: [tab.id] });
}
- await chrome.tabGroups.update(groupId, { title: groupTitle, color: cleanGroupColor(color), collapsed: false });
+ // A new group starts collapsed to one label in the user's window, unless its tab is the one
+ // showing (collapsing would switch the window to another tab). Leave an existing group as the
+ // user set it.
+ const fresh = await chrome.tabs.get(tab.id).catch(() => tab);
+ const update = { title: groupTitle, color: cleanGroupColor(color) };
+ if (createdGroup) update.collapsed = fresh?.active !== true;
+ await chrome.tabGroups.update(groupId, update);
const grouped = await chrome.tabs.get(tab.id);
return { tab: await formatTab(grouped), group: await groupRecord(groupId) };
}
@@ -1795,10 +1946,21 @@ async function dispatch(action, params) {
const existingGroup = await findGroupRecordByTitle(groupTitle);
const createParams = { url: params.url || "about:blank", active: foregroundRequested(params) };
if (existingGroup && typeof existingGroup.windowId === "number") createParams.windowId = existingGroup.windowId;
+ // No group of this session yet: use the window of its automation tab if it has one, else the
+ // user's window. A window of its own only when the browser has no window open.
+ let ownWindow = false;
+ if (createParams.windowId === undefined) {
+ const home = await resolveOwnedAutomationTarget(sessionKeyOf(params)).catch(() => null);
+ const windowId = home && typeof home.windowId === "number" ? home.windowId : await agentWindowId();
+ if (windowId !== null) createParams.windowId = windowId;
+ else ownWindow = typeof chrome.windows?.create === "function";
+ }
// Register the creation as in flight until the tab is tracked, so early capture (which only
// runs in tracked tabs) waits for it instead of skipping the new tab's first page load.
const creation = (async () => {
- const created = await chrome.tabs.create(createParams);
+ const created = ownWindow
+ ? (await chrome.windows.create({ url: createParams.url, focused: createParams.active })).tabs[0]
+ : await chrome.tabs.create(createParams);
await trackSessionTab(sessionKeyOf(params), created.id, true);
return created;
})();
@@ -1831,7 +1993,7 @@ async function dispatch(action, params) {
}
case "tab.activate": {
if (!foregroundRequested(params)) {
- throw new Error("Tab activation is blocked by background mode. Ask the user to run /chrome background off to allow foreground work.");
+ throw new Error("Tab activation is blocked: the call asked for background, or the user turned background mode on (/chrome background on).");
}
// Management actions never auto-create an automation target (createOwnedTarget:false): with
// no explicit target they act on an owned target if one exists, else error — they must never
@@ -1922,17 +2084,49 @@ async function dispatch(action, params) {
// Register a one-shot document_start content script. We register, navigate, wait, then unregister.
await registerInitScript(tab.id, params.initScript);
}
- 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 });
+ // Attach first: the debugger is how we hear about, and answer, a "Leave site?" prompt.
+ // Best effort: another extension's frame on the page (a password manager's inline prompt)
+ // makes Chrome refuse the attach, and navigating away is often how a stuck tab is freed.
+ // Without the debugger we cannot answer a Leave-site prompt, but the navigation still runs.
try {
- await wait;
+ await attachDebugger(tab.id);
+ await cdp(tab.id, "Page.enable", {}).catch(() => undefined);
+ } catch (error) {
+ console.warn(`[pi-chrome] navigating tab ${tab.id} without the debugger: ${error?.message || error}`);
+ }
+ dialogPolicy.set(tab.id, { leave: params.leaveIfAsked === true });
+ const dialogDismissed = new Promise((resolve) => dialogWaiters.set(tab.id, resolve));
+ const waitsForLoad = params.waitUntilLoad !== false;
+ const wait = waitsForLoad ? waitForTabComplete(tab.id, params.timeoutMs || 15000) : Promise.resolve(undefined);
+ wait.catch(() => undefined); // if the dialog wins the race, a later load timeout is not an error
+ try {
+ const updated = await chrome.tabs.update(tab.id, { url: params.url });
+ // Without waiting for the load, still give a prompt a moment to show up.
+ const outcome = await Promise.race([
+ wait.then(() => ({ loaded: true })),
+ dialogDismissed.then((dialog) => ({ dialog })),
+ ...(waitsForLoad ? [] : [new Promise((resolve) => setTimeout(() => resolve({ loaded: true }), 700))]),
+ ]);
+ if (outcome.dialog) {
+ throw new Error(
+ `Navigation to ${params.url} did not happen: the page at ${outcome.dialog.url || tab.url} opened ${describeDialog(outcome.dialog)}, ` +
+ `and it was dismissed, so the tab stayed where it was. ` +
+ (outcome.dialog.type === "beforeunload"
+ ? "Nothing was lost, but the page may hold unsaved changes. If you know nothing unsaved matters here (you just saved or submitted, or this is a throwaway tab), call chrome_navigate again with leaveIfAsked: true. Otherwise ask the user."
+ : "Look at the page to see what it was asking."),
+ );
+ }
+ return await formatTab(await chrome.tabs.get(updated.id));
} finally {
+ dialogPolicy.delete(tab.id);
+ dialogWaiters.delete(tab.id);
if (params.initScript) await unregisterInitScript(tab.id).catch(() => undefined);
}
- return await formatTab(await chrome.tabs.get(updated.id));
}
case "page.screenshot":
return takeScreenshot(params);
+ case "overlay.clear":
+ return clearOverlay(params);
case "cdp.targets": {
// Diagnostics: CDP targets anchored to the resolved tab, including foreign overlay targets
// (password managers, autofill, DevTools front-ends) that explain "Detached while handling
@@ -2276,6 +2470,28 @@ async function withOptionalSnapshot(params, actionFn) {
// chrome.scripting.executeScript({ files }). That file is free of eval/new Function, so it works
// on strict-CSP pages, and it installs globalThis.__piChromeSnapshotPage / __piChromeInspectTarget.
// It shares window.__PI_CHROME_STATE__ (same el- uid scheme) with the CDP-injected input helpers.
+// Injects snapshot_injected.js and runs `scriptOptions.func` (which must return an
+// { ok, value | error } envelope) in the tab's top frame. chrome.scripting is primary; if it
+// resolves without an envelope, the page ran no extension script (CSP `sandbox` without
+// allow-scripts, e.g. raw.githubusercontent.com), so both steps are redone over CDP.
+async function runSnapshotInjected(tab, kind, scriptOptions) {
+ const inject = { target: { tabId: tab.id, frameIds: [0] }, world: "MAIN", files: ["snapshot_injected.js"] };
+ const run = { target: { tabId: tab.id, frameIds: [0] }, world: "MAIN", ...scriptOptions };
+ const injectLabel = `inject ${kind} script in tab ${tab.id}`;
+ const runLabel = `run ${kind} script in tab ${tab.id}`;
+ await executeScriptWithFallback(inject, injectLabel);
+ const results = await executeScriptWithFallback(run, runLabel);
+ const first = results?.[0];
+ if (first?.error || first?.result != null || !chrome.debugger) return results;
+ recordAttachEvent({ kind: "scripting-no-result-cdp-fallback", tabId: tab.id, files: inject.files });
+ await executeScriptViaCdp(inject, injectLabel);
+ const viaCdp = await executeScriptViaCdp(run, runLabel);
+ if (viaCdp?.[0]?.result == null) {
+ throw new Error(`Chrome ${kind} script returned no result in tab ${tab.id} (${tab.url || "unknown url"}); the page may block script execution.`);
+ }
+ return viaCdp;
+}
+
async function snapshotInTab(params) {
const tab = await getTabByParams(params);
await bringToFront(tab, params);
@@ -2288,14 +2504,7 @@ async function snapshotInTab(params) {
params.query ?? null,
params.maxTextChars ?? null,
];
- await executeScriptWithFallback({
- target: { tabId: tab.id, frameIds: [0] },
- world: "MAIN",
- files: ["snapshot_injected.js"],
- }, `inject snapshot script in tab ${tab.id}`);
- const results = await executeScriptWithFallback({
- target: { tabId: tab.id, frameIds: [0] },
- world: "MAIN",
+ const results = await runSnapshotInjected(tab, "snapshot", {
func: async (invocationArgs) => {
try {
const snapshotPage = globalThis.__piChromeSnapshotPage;
@@ -2306,7 +2515,7 @@ async function snapshotInTab(params) {
}
},
args: [args],
- }, `run snapshot script in tab ${tab.id}`);
+ });
const first = results?.[0];
if (first?.error) {
const message = typeof first.error === "string" ? first.error : (first.error.message || JSON.stringify(first.error));
@@ -2324,14 +2533,7 @@ async function inspectInTab(params) {
const tab = await getTabByParams(params);
await bringToFront(tab, params);
const args = [params.uid ?? null, params.selector ?? null, params.scrollIntoView === true];
- await executeScriptWithFallback({
- target: { tabId: tab.id, frameIds: [0] },
- world: "MAIN",
- files: ["snapshot_injected.js"],
- }, `inject inspect script in tab ${tab.id}`);
- const results = await executeScriptWithFallback({
- target: { tabId: tab.id, frameIds: [0] },
- world: "MAIN",
+ const results = await runSnapshotInjected(tab, "inspect", {
func: async (invocationArgs) => {
try {
const inspectTarget = globalThis.__piChromeInspectTarget;
@@ -2342,7 +2544,7 @@ async function inspectInTab(params) {
}
},
args: [args],
- }, `run inspect script in tab ${tab.id}`);
+ });
const first = results?.[0];
if (first?.error) {
const message = typeof first.error === "string" ? first.error : (first.error.message || JSON.stringify(first.error));
@@ -2412,6 +2614,9 @@ function foregroundRequested(params) {
async function bringToFront(tab, params) {
if (!foregroundRequested(params)) return tab;
await chrome.windows.update(tab.windowId, { focused: true });
+ if (typeof tab.groupId === "number" && tab.groupId >= 0 && chrome.tabGroups) {
+ await chrome.tabGroups.update(tab.groupId, { collapsed: false }).catch(() => undefined);
+ }
return chrome.tabs.update(tab.id, { active: true });
}
diff --git a/extensions/chrome-profile-bridge/index.ts b/extensions/chrome-profile-bridge/index.ts
index 6156e81..2cbd5da 100644
--- a/extensions/chrome-profile-bridge/index.ts
+++ b/extensions/chrome-profile-bridge/index.ts
@@ -73,7 +73,7 @@ const DEFAULT_PORT = REMOTE_BRIDGE?.port ?? Number(process.env.PI_CHROME_BRIDGE_
const DEFAULT_TIMEOUT_MS = 30_000;
const MAX_TEXT_CHARS = 30_000;
const MAX_ELEMENTS = 80;
-const BACKGROUND_PARAM_DESCRIPTION = "If true, avoid explicit Chrome focus/tab activation for this call. /chrome background on (default) enforces this for every call and ignores false. Ask the user to run /chrome background off to allow foreground work.";
+const BACKGROUND_PARAM_DESCRIPTION = "Default true: work on the tab where it is, without changing what the user sees (an inactive tab takes clicks, typing and screenshots fine). Pass false only when you need the tab showing: it activates the tab and raises its window over what the user is doing. Refused if the user has turned background mode on with /chrome background on.";
function resolveRemoteBridge(raw: string | undefined): { host: string; port: number } | undefined {
const value = raw?.trim();
@@ -133,8 +133,11 @@ function truncateText(text: string, maxChars = MAX_TEXT_CHARS): string {
return `${text.slice(0, maxChars)}\n\n[truncated ${text.length - maxChars} characters]`;
}
+// JSON.stringify returns undefined (not a string) for undefined, functions, and symbols. A tool
+// result block with `text: undefined` is persisted to the session and makes every later turn
+// fail with "Cannot read properties of undefined (reading 'length')", so always return a string.
function safeJson(value: unknown): string {
- return JSON.stringify(value, null, 2);
+ return JSON.stringify(value, null, 2) ?? String(value);
}
const snapshotModeValues = ["auto", "interactive", "forms", "pageMap", "text", "changes", "full"] as const;
@@ -150,7 +153,8 @@ function rectText(rect: any): string {
}
function formatChromeSnapshot(snapshot: any): string {
- if (!snapshot || typeof snapshot !== "object") return safeJson(snapshot);
+ if (snapshot == null) throw new Error("Chrome returned no snapshot for this page; it may block extension scripts. Try chrome_evaluate instead.");
+ if (typeof snapshot !== "object") return safeJson(snapshot);
if (snapshot.mode === "full") return truncateText(safeJson(snapshot));
const lines: string[] = [];
lines.push(`# Chrome snapshot${snapshot.mode ? ` (${snapshot.mode})` : ""}`);
@@ -266,7 +270,7 @@ function describeTypeEvidence(result: unknown, typedLength: number, pressEnter:
&& typeof r.existingTextLengthBefore === "number" && r.existingTextLengthBefore === r.valueLengthAfter
&& (r.valueRedacted === true || r.valueBefore === r.valueAfter);
if (unchanged) {
- lines.push("\u26a0 The field value did not change: the keystrokes did not reach this field. It may not have keyboard focus (background/hidden tabs often cannot take focus); focus it with a uid/selector click, or ask the user to run /chrome background off, then verify.");
+ lines.push("\u26a0 The field value did not change: the keystrokes did not reach this field. It may not have keyboard focus; focus it with a uid/selector click and verify, or retry with background:false to bring the tab forward.");
} else if (r.insertedAt === "caret-middle" && typedLength > 0) {
lines.push("⚠ Text was spliced into the middle of existing content; chrome_type does NOT replace. Use chrome_fill (or chrome_type replace=true) to replace a field's value.");
if (pressEnter) lines.push("⚠ If Enter submitted the form, it submitted the spliced value above, not just your text.");
@@ -351,7 +355,8 @@ async function pruneScreenshotDir(dir: string, retentionDays?: number): Promise<
// End screenshot pruning.
function formatChromeInspect(inspect: any): string {
- if (!inspect || typeof inspect !== "object") return safeJson(inspect);
+ if (inspect == null) throw new Error("Chrome returned no inspect result for this page; it may block extension scripts. Try chrome_evaluate instead.");
+ if (typeof inspect !== "object") return safeJson(inspect);
const t = inspect.target || {};
const lines: string[] = [];
lines.push(`# Chrome inspect ${t.uid || ""}`.trim());
@@ -878,6 +883,7 @@ const CHROME_TOOL_NAMES = [
"chrome_upload_file",
"chrome_cdp",
"chrome_cdp_targets",
+ "chrome_clear_overlay",
] as const;
const CHROME_TOOL_NAME_SET = new Set<string>(CHROME_TOOL_NAMES);
const CHROME_TOOL_CHANGE_ENTRY = "pi-chrome-tool-change";
@@ -916,11 +922,9 @@ export default function (pi: ExtensionAPI): void {
if (!alreadyLoaded) globalState[PI_CHROME_GLOBAL_KEY] = { version: PI_CHROME_VERSION, root: currentRoot, token: instanceToken };
const bridge = new ChromeProfileBridge(DEFAULT_HOST, DEFAULT_PORT);
- let backgroundEnabled = true;
+ // Off by default: agents may bring a tab forward when they need to (background:false).
+ let backgroundEnabled = false;
let chromeAuthorizedUntil: number | "indefinite" | undefined;
- // Whether the current grant stood in from PI_CHROME_AUTHORIZE rather than being given by
- // the user this session. The footer announces only the latter.
- let envGranted = false;
// Restore an authorization that survived a /reload. Drop it if it already expired.
const persistedAuth = globalState[PI_CHROME_AUTH_KEY];
if (persistedAuth) {
@@ -1020,7 +1024,6 @@ export default function (pi: ExtensionAPI): void {
chromeToolsUsable = false;
if (logAction && wasUsable) logChromeToolChange(logAction, { authorizedUntil: undefined });
chromeAuthorizedUntil = undefined;
- envGranted = false;
persistAuth();
// Revoking control ends pi-chrome's automation for this session; tidy up the target we own.
void cleanupAutomationTargetBestEffort();
@@ -1077,8 +1080,16 @@ export default function (pi: ExtensionAPI): void {
return typeof id === "string" && id ? `session:${id}` : undefined;
};
+ // FORK: with PI_CHROME_AUTHORIZE set, Chrome control is standing configuration, not session
+ // state, so the footer never shows. Read from the environment on every update, not from any
+ // saved state, so no grant restored across /reload or a session switch can bring it back.
+ const envAuthorizes = (): boolean => {
+ const value = process.env.PI_CHROME_AUTHORIZE?.trim();
+ return !!value && parseAuthorizeArg(value) !== undefined;
+ };
+
const updateChromeStatus = (ctx: ExtensionContext): void => {
- if (chromeControlAuthorized() && !envGranted) {
+ if (chromeControlAuthorized() && !envAuthorizes()) {
ctx.ui.setStatus("chrome", ctx.ui.theme.fg("success", "●") + " Chrome Bridge" + authCountdownLabel());
} else {
ctx.ui.setStatus("chrome", undefined);
@@ -1116,14 +1127,16 @@ export default function (pi: ExtensionAPI): void {
const authorizedBridgeSend = async (action: string, params: Record<string, unknown>, timeoutMs = DEFAULT_TIMEOUT_MS, signal?: AbortSignal): Promise<unknown> => {
requireChromeControlAuthorized();
- // Background on is a session policy, not a default that tool arguments can override.
- // Apply it here so tab.new, chrome_launch(url), and tools without a background parameter
- // cannot bypass it. Background off still permits per-call background:true.
+ // Background on (opt-in, /chrome background on) is a session policy that tool arguments cannot
+ // override. Apply it here so tab.new, chrome_launch(url), and tools without a background
+ // parameter cannot bypass it. Off (the default) lets each call choose.
const typed = params as { background?: boolean; foreground?: boolean };
- const requestedBackground = typed.background ?? (typed.foreground !== undefined ? !typed.foreground : false);
+ // Unspecified means background, so nothing changes what the user sees unless an agent asks;
+ // tab.activate exists to bring a tab forward, so it defaults the other way.
+ const requestedBackground = typed.background ?? (typed.foreground !== undefined ? !typed.foreground : action !== "tab.activate");
const background = backgroundEnabled || requestedBackground;
if (action === "tab.activate" && background) {
- throw new Error("Tab activation is blocked by background mode. Ask the user to run /chrome background off to allow foreground work.");
+ throw new Error("Tab activation is blocked: the user turned background mode on (/chrome background on).");
}
// Scope every action to this session's dedicated automation target and tab group.
const sessionKey = sessionKeyFor(sessionCtx);
@@ -1174,7 +1187,6 @@ export default function (pi: ExtensionAPI): void {
const grant = parseAuthorizeArg(autoGrant);
if (grant) {
chromeAuthorizedUntil = grant.until;
- envGranted = true;
} else {
ctx.ui.notify(`Ignoring PI_CHROME_AUTHORIZE="${autoGrant}": use minutes (15m, 30, 45) or indefinite.`, "warning");
}
@@ -1204,6 +1216,12 @@ export default function (pi: ExtensionAPI): void {
// /reload continues the same session. On exit, give Chrome a bounded opportunity to
// close this session's created tabs and ungroup adopted tabs before stopping the broker.
if (event?.reason !== "reload") await cleanupAutomationTargetBestEffort();
+ // A /chrome authorize grant belongs to this session: /reload keeps it, while /new, /resume
+ // and /fork start a different session in this process, which must not inherit it. "quit"
+ // leaves it alone: a subagent quitting in this process must not drop its parent's grant.
+ if (event?.reason === "new" || event?.reason === "resume" || event?.reason === "fork") {
+ delete globalState[PI_CHROME_AUTH_KEY];
+ }
bridge.stop();
if (globalState[PI_CHROME_GLOBAL_KEY]?.token === instanceToken) {
delete globalState[PI_CHROME_GLOBAL_KEY];
@@ -1258,8 +1276,8 @@ Capability model (important):
- \`chrome_evaluate\` and \`chrome_snapshot\` run in MAIN world via **CDP \`Runtime.evaluate\`**, which is not subject to the page's Content-Security-Policy. They work even on strict-CSP pages (e.g. github.com, many bank/SaaS apps) that block \`'unsafe-eval'\`. \`chrome_navigate initScript\` likewise injects at document_start via CDP and bypasses CSP. \`chrome_screenshot\`, \`chrome_tab\`, and Chrome input also work under any CSP.
- Input tools return structured details and support \`includeSnapshot=true\` on click/type/fill/key. Use the fresh snapshot to verify state instead of repeating blindly. If the action started a navigation, the snapshot waits (up to 5s) for the new page.
- \`chrome_type\` never replaces: with a uid/selector it appends at the end of the field; without one it types at the current caret. Check its before/after report. Use \`chrome_fill\` to replace a field.
-- Chrome ignores real input to hidden pages (inactive tabs, minimized windows, windows behind a macOS full-screen window). Input tools report this instead of silently doing nothing; retry with background:false only when bringing the tab forward is acceptable.
-- \`chrome_cdp\` runs any raw CDP method on a tab (emulation, cookies, PDF, accessibility tree, etc.) when no dedicated chrome_* tool fits; \`chrome_cdp_targets\` diagnoses debugger/overlay conflicts.
+- Inactive (hidden) tabs work: clicks, typing, keys and screenshots reach them without bringing them forward, and chrome_scroll scrolls them by script. Only a minimized window refuses input; pass background:false to bring a tab forward when you need it showing.
+- \`chrome_cdp\` runs any raw CDP method on a tab (emulation, cookies, PDF, accessibility tree, etc.) when no dedicated chrome_* tool fits; \`chrome_cdp_targets\` diagnoses debugger/overlay conflicts, and \`chrome_clear_overlay\` closes a password manager prompt that blocks a tab (unless you are waiting for the user to use it).
Usage rules:
1. If a chrome_* tool says Chrome control is locked, ask the user to run \`/chrome authorize\` before retrying.
@@ -1267,9 +1285,12 @@ Usage rules:
3. \`includeSnapshot=true\` on click/type/fill/key to verify in one round trip.
4. If \`chrome_evaluate\` returns null when you expected a value, the expression evaluated to null/undefined in the page; surface the value via \`JSON.stringify\` to confirm.
5. \`chrome_navigate\` supports an optional \`initScript\` that runs at document_start in MAIN world for the next navigation (good for seeding localStorage or stubbing Date.now).
-6. /chrome background on (default) is a hard policy: per-call \`background=false\` cannot override it, new tabs stay inactive, and \`chrome_tab activate\` is blocked. Ask the user to run /chrome background off when they want foreground/watch mode. With background off, per-call \`background=true\` still avoids explicit focus/tab activation. Screenshots use CDP without activating background tabs; debugger failures never fall back to tab activation. Page scripts, trusted input, native prompts, and Chrome/OS behavior can still affect focus.
+6. By default every call works in the background: tabs open inactive and nothing changes what the user sees. Pass \`background: false\` on a call (or use \`chrome_tab activate\`) only when you need the tab showing, for example a page that misbehaves while hidden or something the user should watch; it activates the tab and raises its window over what the user is doing. If the user has run /chrome background on, that is refused and you must work without it.
7. If you hit a native file-picker or privileged browser prompt gate, tell the user; generic clicks/typing/CSP gates are handled by Chrome input.
-8. Run /chrome doctor when in doubt about connectivity or capabilities.`;
+8. Run /chrome doctor when in doubt about connectivity or capabilities.
+9. A page can open dialogs you cannot see: alert, confirm, prompt, and the \"Leave site? Changes you made may not be saved\" prompt of a page with unsaved changes. They are dismissed for you (stay, cancel). \`chrome_navigate\` reports one by failing, and \`leaveIfAsked: true\` leaves anyway; use that only when you know nothing unsaved matters, and ask the user when unsure. If a click or key press that should have navigated did nothing, a Leave-site prompt may have stopped it: check the page, then ask the user before discarding anything.
+10. Your tabs open in the user's browser window, inactive, in your session's own tab group (collapsed to one label). An inactive tab takes clicks, typing and screenshots normally, so you do not need it showing. Reuse your tab (navigate it) rather than opening new ones, and close tabs you opened when you are done with them. Do not open new windows unless the user asks.
+11. If a tool fails saying another extension (a password manager such as 1Password) has a prompt open on the tab, decide whether it is in your way or part of the task. If it is just in your way, call \`chrome_clear_overlay\` for the tab. If you need the user to sign in, authorize or approve something with it, leave it alone and tell the user what you are waiting for. Navigating the tab away also frees it.`;
// Shared handlers, dispatched by the unified /chrome command below.
const doctorHandler = async (ctx: ExtensionContext) => {
@@ -1277,7 +1298,7 @@ Usage rules:
const lines: string[] = [
`pi-chrome v${PI_CHROME_VERSION}`,
`• Authorization: ${authSummary()}.`,
- `• Background: ${backgroundEnabled ? "on (hard)" : "off (foreground/watch mode)"}.`,
+ `• Background: ${backgroundEnabled ? "on (hard)" : "off (agents may bring a tab forward with background:false; default)"}.`,
];
const status = bridge.status();
const roleLabel = status.remote
@@ -1346,8 +1367,7 @@ Usage rules:
lines.push(`• Pi hasn't opened its own tab in this session yet.`);
} else if (own.visibility === "hidden") {
lines.push(
- `⚠ Pi's tab is hidden because ${own.hiddenReason ?? "its window is not visible"}. Chrome ignores clicks and typing in hidden tabs, so those tools will fail until it's visible.`,
- ` Fix: bring Pi's window forward or uncover it, or run /chrome background off to let Pi bring it forward.`,
+ `⚠ Pi's tab is hidden because ${own.hiddenReason ?? "its window is not visible"}. Clicks, typing and screenshots still work there; only a minimized window refuses input.`,
);
} else if (own.visibility === "visible") {
lines.push(`✓ Pi's tab is visible, so clicks and typing will reach it.`);
@@ -1365,7 +1385,7 @@ Usage rules:
// Existing background setting is the hard policy. No args = toggle; no separate lock mode.
const BACKGROUND_DESC: Record<string, string> = {
on: "Hard background: pi-chrome will not explicitly focus windows or activate tabs; per-call foreground overrides and tab activation are blocked. Page/Chrome behavior can still affect focus.",
- off: "Foreground/watch mode: Chrome may come forward and switch tabs. Per-call background:true still avoids explicit focus/tab activation.",
+ off: "Default. Calls work in the background unless an agent passes background:false to bring its tab forward.",
};
const backgroundHandler = async (ctx: ExtensionContext, args: string) => {
@@ -1400,7 +1420,6 @@ Usage rules:
}
const wasUsable = chromeToolsUsable;
chromeAuthorizedUntil = until;
- envGranted = false;
persistAuth();
activateChromeTools();
chromeToolsUsable = true;
@@ -1560,8 +1579,8 @@ Usage rules:
];
} else if (path[0] === "background" && path.length === 1) {
candidates = [
- { fullValue: "background on", label: "on", description: "Hard background: block explicit focus/tab activation and per-call foreground overrides. (default)" },
- { fullValue: "background off", label: "off", description: "Bring Chrome to the front so you can watch." },
+ { fullValue: "background on", label: "on", description: "Hard background: block explicit focus/tab activation and per-call foreground overrides." },
+ { fullValue: "background off", label: "off", description: "Let agents bring a tab forward when they ask to. (default)" },
{ fullValue: "background toggle", label: "toggle", description: "Flip whichever way it's currently set." },
{ fullValue: "background status", label: "status", description: "Show the current setting." },
];
@@ -1644,7 +1663,7 @@ Usage rules:
pi.registerTool({
name: "chrome_tab",
label: "Chrome Tab",
- description: "List, create, activate, close, group, ungroup, or inspect tabs in the user's existing Chrome profile via the companion extension. New/grouped tabs always use this session's Pi tab group. Background mode keeps new tabs inactive and blocks activate; ask the user to run /chrome background off for foreground/watch mode. activate/close/group/ungroup require a target (targetId/urlIncludes/titleIncludes); with no target they act on this session's pi-chrome automation tab if one exists, and otherwise error rather than touching the user's active tab.",
+ description: "List, create, activate, close, group, ungroup, or inspect tabs in the user's existing Chrome profile via the companion extension. New/grouped tabs always use this session's Pi tab group, inactive, in the user's window; prefer navigating a tab you already have to opening another. Inactive tabs take input and screenshots fine; activate only when you need the tab showing (it changes what the user sees). activate/close/group/ungroup require a target (targetId/urlIncludes/titleIncludes); with no target they act on this session's pi-chrome automation tab if one exists, and otherwise error rather than touching the user's active tab.",
promptSnippet: "List/open/activate/close/group existing Chrome tabs through the companion extension.",
parameters: Type.Object({
action: StringEnum(tabActionValues),
@@ -1680,7 +1699,7 @@ Usage rules:
name: "chrome_snapshot",
label: "Chrome Snapshot",
description:
- "Inspect a page in the user's existing Chrome profile. Default output is a concise, agent-friendly observation with structural layout/context, stable uids, visible actions, form fields, page hints, and changes since the previous snapshot. Use mode/query/nearUid to zoom instead of dumping the whole page. Background mode (default) blocks explicit focus/tab activation even with background=false. Ask the user to run /chrome background off for foreground/watch mode.",
+ "Inspect a page in the user's existing Chrome profile. Default output is a concise, agent-friendly observation with structural layout/context, stable uids, visible actions, form fields, page hints, and changes since the previous snapshot. Use mode/query/nearUid to zoom instead of dumping the whole page. Works on inactive tabs without bringing them forward.",
promptSnippet: "Observe the current Chrome page: concise summary, structural layout, visible actions, forms, page map, query matches, and stable uids.",
parameters: Type.Object({
targetId: Type.Optional(Type.String()),
@@ -1785,8 +1804,8 @@ Usage rules:
name: "chrome_navigate",
label: "Chrome Navigate",
description:
- "Navigate a Chrome tab to a URL via the companion extension. With no target, navigation goes to pi-chrome's own dedicated automation window/tab — it never replaces the user's active tab. Pass targetId/urlIncludes/titleIncludes only to act on a specific existing tab. Background mode (default) blocks explicit focus/tab activation even with background=false; /chrome background off allows foreground/watch mode. Optionally waits for load completion.",
- promptSnippet: "Navigate a Chrome tab in the user's existing profile.",
+ "Navigate a Chrome tab to a URL via the companion extension. With no target, navigation goes to pi-chrome's own dedicated automation window/tab — it never replaces the user's active tab. Pass targetId/urlIncludes/titleIncludes only to act on a specific existing tab. Works on inactive tabs without bringing them forward. Optionally waits for load completion. Some pages ask \"Leave site? Changes you made may not be saved\" before navigating away; you cannot see that prompt, so it is answered for you: the default is to stay, and the call then fails at once saying so, with the tab unchanged and nothing lost. Retry with leaveIfAsked: true only if you know nothing unsaved matters (you just saved or submitted, or the tab is a throwaway you opened); if you are not sure, ask the user, because leaving discards unsaved work for good. leaveIfAsked applies to this one call only. Any other JavaScript dialog (alert, confirm, prompt) that appears during the navigation is dismissed and reported the same way.",
+ promptSnippet: "Navigate a Chrome tab in the user's existing profile; a page's \"Leave site?\" prompt makes the call fail unless leaveIfAsked is true.",
parameters: Type.Object({
url: Type.String(),
targetId: Type.Optional(Type.String()),
@@ -1794,6 +1813,7 @@ Usage rules:
titleIncludes: Type.Optional(Type.String()),
waitUntilLoad: Type.Optional(Type.Boolean({ default: true })),
timeoutMs: Type.Optional(Type.Number({ default: 15_000 })),
+ leaveIfAsked: Type.Optional(Type.Boolean({ description: "Leave the page even if it asks \"Leave site? Changes you made may not be saved\". Default false: the navigation fails and the tab stays. Set it only when you know nothing unsaved matters; otherwise ask the user. This call only." })),
initScript: Type.Optional(Type.String({ description: "Optional JavaScript source to run in MAIN world at document_start of the next navigation. Useful for seeding localStorage, stubbing Date.now(), or defining navigator.webdriver=undefined. Requires the companion extension's webNavigation permission." })),
background: Type.Optional(Type.Boolean({ description: BACKGROUND_PARAM_DESCRIPTION })),
host: Type.Optional(Type.String()),
@@ -1809,7 +1829,7 @@ Usage rules:
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. Background mode (default) blocks explicit focus/tab activation even with background=false; /chrome background off allows foreground/watch mode.",
+ "Evaluate JavaScript in an existing Chrome tab through the companion extension. Runs in the page context and returns JSON-serializable values when possible. Works on inactive tabs without bringing them forward.",
promptSnippet: "Evaluate JavaScript in the active Chrome tab through the companion extension.",
parameters: Type.Object({
expression: Type.String(),
@@ -1843,7 +1863,7 @@ Usage rules:
selector: Type.Optional(Type.String({ description: "CSS selector to click. Prefer uid from chrome_snapshot when available." })),
x: Type.Optional(Type.Number({ description: "Viewport x coordinate if uid/selector is omitted." })),
y: Type.Optional(Type.Number({ description: "Viewport y coordinate if uid/selector is omitted." })),
- domFallback: Type.Optional(Type.Boolean({ description: "If true (default), fall back to DOM-dispatched click if Chrome's CDP input path is blocked (extension overlay, debugger failure, or a hidden tab that ignores trusted input)." })),
+ domFallback: Type.Optional(Type.Boolean({ description: "If true (default), fall back to DOM-dispatched click if Chrome's CDP input path is blocked (extension overlay, debugger failure, or a minimized window that refuses trusted input)." })),
includeSnapshot: Type.Optional(Type.Boolean({ description: "If true, include a fresh chrome_snapshot result after the click." })),
maxElements: Type.Optional(Type.Number({ default: MAX_ELEMENTS, description: "Max elements in the included snapshot." })),
targetId: Type.Optional(Type.String()),
@@ -1908,7 +1928,7 @@ Usage rules:
selector: Type.Optional(Type.String({ description: "CSS selector to fill if uid is omitted." })),
perCharacter: Type.Optional(Type.Boolean({ default: false, description: "Send individual key events even in contenteditables. Default: one native text insertion for contenteditables; key events for other fields." })),
submit: Type.Optional(Type.Boolean({ description: "If true, press Enter after filling." })),
- domFallback: Type.Optional(Type.Boolean({ description: "If true (default), fall back to DOM value-setting if Chrome's CDP input path is blocked (extension overlay, debugger failure, or a hidden tab that ignores trusted input)." })),
+ domFallback: Type.Optional(Type.Boolean({ description: "If true (default), fall back to DOM value-setting if Chrome's CDP input path is blocked (extension overlay, debugger failure, or a minimized window that refuses trusted input)." })),
includeSnapshot: Type.Optional(Type.Boolean({ description: "If true, include a fresh chrome_snapshot result after filling." })),
maxElements: Type.Optional(Type.Number({ default: MAX_ELEMENTS, description: "Max elements in the included snapshot." })),
targetId: Type.Optional(Type.String()),
@@ -1933,7 +1953,7 @@ Usage rules:
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). Background mode (default) blocks explicit focus/tab activation even with background=false; /chrome background off allows foreground/watch mode. Pass includeSnapshot=true to verify after the keypress.",
+ "Send a keyboard key to an existing Chrome tab (Enter, Escape, Tab, Backspace, Delete, ArrowUp/Down/Left/Right, or one character). Works on inactive tabs without bringing them forward. Pass includeSnapshot=true to verify after the keypress.",
promptSnippet: "Press keys in Chrome through the companion extension.",
parameters: Type.Object({
key: Type.String(),
@@ -2051,7 +2071,7 @@ Usage rules:
name: "chrome_screenshot",
label: "Chrome Screenshot",
description:
- "Capture a screenshot of a Chrome tab via CDP and save it to disk without activating background tabs. Requires debugger access; failures never fall back to activating a tab. Background mode (default) ignores background=false; /chrome background off allows foreground/watch mode.",
+ "Capture a screenshot of a Chrome tab via CDP and save it to disk without activating background tabs. Requires debugger access; failures never fall back to activating a tab. Inactive tabs render fine; no need to bring them forward.",
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>." })),
@@ -2241,7 +2261,7 @@ Usage rules:
name: "chrome_cdp",
label: "Chrome CDP Call",
description:
- "Low-level escape hatch: run one Chrome DevTools Protocol (CDP) method against a tab (no target = this session's automation tab), e.g. Emulation.setDeviceMetricsOverride, Network.getCookies, DOM.getDocument, Page.printToPDF, Accessibility.getFullAXTree. Put CDP fields inside params. Nothing is filtered against a safe list: destructive methods run as given. Prefer dedicated chrome_* tools when they cover the task. Background mode blocks Page.bringToFront and Target.activateTarget, but other methods can still change what the user sees. Screenshot/binary payloads and results over 256 KiB are summarised instead of returned in full. Domain events are not streamed back; only the method's direct result is returned.",
+ "Low-level escape hatch: run one Chrome DevTools Protocol (CDP) method against a tab (no target = this session's automation tab), e.g. Emulation.setDeviceMetricsOverride, Network.getCookies, DOM.getDocument, Page.printToPDF, Accessibility.getFullAXTree. Put CDP fields inside params. Nothing is filtered against a safe list: destructive methods run as given. Prefer dedicated chrome_* tools when they cover the task. Page.bringToFront and Target.activateTarget are blocked unless the call passes background:false, and other methods can still change what the user sees. Screenshot/binary payloads and results over 256 KiB are summarised instead of returned in full. Domain events are not streamed back; only the method's direct result is returned.",
promptSnippet: "Run a raw Chrome DevTools Protocol method against a Chrome tab (low-level escape hatch).",
parameters: Type.Object({
method: Type.String({ description: "CDP method name, e.g. \"Runtime.evaluate\" or \"Emulation.setDeviceMetricsOverride\"." }),
@@ -2272,6 +2292,28 @@ Usage rules:
});
pi.registerTool({
+ name: "chrome_clear_overlay",
+ label: "Chrome Clear Overlay",
+ description:
+ "Close another extension's prompt that is blocking a tab, usually a password manager's (1Password) inline sign-in or autofill prompt. While such a prompt is open Chrome refuses the debugger on that tab, so screenshots, clicks, typing and evaluate fail with \"Another extension ... has a prompt open on this tab\". Decide for yourself whether to use it: if the prompt is just in your way (it popped up on a field you are filling, or you do not need anything from it), clear it. If you need the user to sign in, authorize or approve something with it, or the user may be in the middle of using it, do not clear it: tell the user what you are waiting for. It removes the other extension's frame, blurs the focused field and sends Escape, then reports whether the tab is usable again. Side effect: the password manager may not show its inline prompt again on that page until the page is reloaded, so if the user then needs to sign in there, reload the page (or tell them to). It does not touch the page's own content, and it cannot close 1Password's browser-toolbar popup or the 1Password desktop app (if the result says the tab is still blocked, tell the user). Navigating the tab away also frees it.",
+ promptSnippet: "Close a password manager prompt that blocks a tab, unless you are waiting for the user to use it.",
+ parameters: Type.Object({
+ targetId: Type.Optional(Type.String()),
+ urlIncludes: Type.Optional(Type.String()),
+ titleIncludes: Type.Optional(Type.String()),
+ }),
+ async execute(_id, params, signal): Promise<ToolTextResult> {
+ const value = await authorizedBridgeSend("overlay.clear", params, DEFAULT_TIMEOUT_MS, signal);
+ const result = value as { tab?: { id?: number; url?: string }; removedFrames?: string[]; remainingForeignTargets?: string[]; debuggerAttachable?: boolean; cleared?: boolean } | undefined;
+ const removed = result?.removedFrames ?? [];
+ const text = result?.cleared
+ ? `Cleared${removed.length ? `: removed ${removed.join(", ")}` : " (nothing to remove, the prompt had already gone)"}. Tab ${result.tab?.id} is usable again. The password manager may not show its inline prompt again on this page until it is reloaded.`
+ : `The tab is still blocked${result?.remainingForeignTargets?.length ? ` by ${result.remainingForeignTargets.join(", ")}` : ""}${removed.length ? ` (removed ${removed.join(", ")} but it is still there or came back)` : ""}. The prompt may be the password manager's toolbar popup or desktop app, which this tool cannot close: tell the user, or navigate the tab away. Diagnostics: ${JSON.stringify({ foreignTargetsAnywhere: (result as any)?.foreignTargetsAnywhere, injectedReport: (result as any)?.injectedReport })}`;
+ return { content: [{ type: "text", text }], details: { value: (value ?? null) as Json } };
+ },
+ });
+
+ pi.registerTool({
name: "chrome_cdp_targets",
label: "Chrome CDP Targets",
description: