pi-chrome 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# pi-chrome
+
+Pi extension for controlling the Chrome profile you already use.
+
+Unlike Chrome DevTools Protocol integrations, `pi-chrome` does not launch a separate debug browser profile. It uses a small companion Chrome extension installed in your normal Chrome profile, so Pi can work with your existing windows, tabs, and authenticated sessions.
+
+## Install
+
+```bash
+pi install npm:pi-chrome
+```
+
+For local development from this checkout:
+
+```bash
+pi install ./pi-chrome
+```
+
+## First-time setup
+
+In Pi, run:
+
+```text
+/chrome-onboard
+```
+
+Pi will first show setup instructions and wait for confirmation. Press Enter to continue. On macOS it will:
+
+- open `chrome://extensions`
+- reveal the bundled `browser-extension` folder in Finder
+- copy the extension folder path to your clipboard
+
+Then in Chrome:
+
+1. Enable **Developer mode**.
+2. Click **Load unpacked**.
+3. Select the revealed/copied `browser-extension` folder.
+4. Return to Pi and run:
+
+```text
+/chrome-status
+```
+
+Expected messages:
+
+```text
+Performing Chrome bridge health check
+Chrome profile bridge connected (ID: <chrome-extension-id>)
+```
+
+## Tools
+
+The package registers these Pi tools:
+
+- `chrome_launch` — setup/help entry point; opens a URL if the bridge is connected
+- `chrome_tab` — list, create, activate, close, or inspect tabs
+- `chrome_snapshot` — inspect title, URL, visible text, viewport, and clickable/focusable selectors
+- `chrome_navigate` — navigate an existing tab
+- `chrome_evaluate` — evaluate JavaScript in a tab
+- `chrome_click` — click by selector or coordinates
+- `chrome_type` — type text, optionally focusing a selector first
+- `chrome_key` — send keyboard keys
+- `chrome_wait_for` — wait for a selector or expression
+- `chrome_screenshot` — capture viewport screenshots to disk
+
+## Security model
+
+The companion Chrome extension runs in the Chrome profile where you install it and has broad tab/scripting permissions. Only install it from a package source you trust.
+
+The Pi side listens on `127.0.0.1:17318` by default. Override before starting Pi with:
+
+```bash
+PI_CHROME_BRIDGE_PORT=17319 pi
+```

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

@@ -0,0 +1,14 @@
+{
+  "manifest_version": 3,
+  "name": "Pi Existing Chrome Profile Bridge",
+  "version": "0.1.0",
+  "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/*"],
+  "background": {
+    "service_worker": "service_worker.js"
+  },
+  "action": {
+    "default_title": "Pi Chrome Bridge"
+  }
+}

package/extensions/chrome-profile-bridge/browser-extension/service_worker.js

@@ -0,0 +1,344 @@
+const BRIDGE_URL = "http://127.0.0.1:17318";
+const CLIENT_NAME = `Pi Chrome Bridge ${chrome.runtime.id}`;
+const POLL_ERROR_BACKOFF_MS = 2000;
+let polling = false;
+
+function armKeepaliveAlarm() {
+  // MV3 service workers can be suspended; alarms are the supported way to
+  // wake the extension again. Chrome's minimum period is 0.5 minutes.
+  chrome.alarms.create("pi-bridge-keepalive", { periodInMinutes: 0.5 });
+}
+
+chrome.runtime.onInstalled.addListener(() => {
+  chrome.action.setBadgeText({ text: "pi" });
+  chrome.action.setBadgeBackgroundColor({ color: "#4f46e5" });
+  armKeepaliveAlarm();
+  void pollLoop();
+});
+
+chrome.runtime.onStartup.addListener(() => {
+  armKeepaliveAlarm();
+  void pollLoop();
+});
+
+chrome.alarms.onAlarm.addListener((alarm) => {
+  if (alarm.name === "pi-bridge-keepalive") void pollLoop();
+});
+
+chrome.action.onClicked.addListener(() => {
+  armKeepaliveAlarm();
+  void pollLoop();
+});
+
+armKeepaliveAlarm();
+
+setInterval(() => {
+  void pollLoop();
+}, 1000);
+
+async function pollLoop() {
+  if (polling) return;
+  polling = true;
+  try {
+    while (true) {
+      const response = await fetch(`${BRIDGE_URL}/next?name=${encodeURIComponent(CLIENT_NAME)}`, {
+        cache: "no-store",
+      });
+      if (!response.ok) throw new Error(`bridge /next HTTP ${response.status}`);
+      const payload = await response.json();
+      if (payload.type !== "command") break;
+      await handleCommand(payload.command);
+    }
+  } catch (error) {
+    await sleep(POLL_ERROR_BACKOFF_MS);
+  } finally {
+    polling = false;
+  }
+}
+
+async function handleCommand(command) {
+  try {
+    const result = await dispatch(command.action, command.params ?? {});
+    await postResult({ id: command.id, ok: true, result });
+  } catch (error) {
+    await postResult({ id: command.id, ok: false, error: error?.message ?? String(error) });
+  }
+}
+
+async function postResult(result) {
+  await fetch(`${BRIDGE_URL}/result`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(result),
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function dispatch(action, params) {
+  switch (action) {
+    case "tab.version":
+      return { extensionId: chrome.runtime.id, bridgeUrl: BRIDGE_URL, userAgent: navigator.userAgent };
+    case "tab.list":
+      return (await chrome.tabs.query({})).map(formatTab);
+    case "tab.new": {
+      const tab = await chrome.tabs.create({ url: params.url || "about:blank", active: true });
+      return formatTab(tab);
+    }
+    case "tab.activate": {
+      const tab = await getTabByParams(params);
+      await chrome.windows.update(tab.windowId, { focused: true });
+      return formatTab(await chrome.tabs.update(tab.id, { active: true }));
+    }
+    case "tab.close": {
+      const tab = await getTabByParams(params);
+      await chrome.tabs.remove(tab.id);
+      return { closed: tab.id };
+    }
+    case "page.snapshot":
+      return executeInTab(params, snapshotPage, [params.maxElements || 80]);
+    case "page.evaluate":
+      return executeInTab(params, evaluateExpression, [params.expression, params.awaitPromise !== false]);
+    case "page.click":
+      return executeInTab(params, clickPage, [params.selector ?? null, params.x ?? null, params.y ?? null]);
+    case "page.type":
+      return executeInTab(params, typeIntoPage, [params.selector ?? null, params.text || "", Boolean(params.pressEnter)]);
+    case "page.key":
+      return executeInTab(params, pressKeyInPage, [params.key]);
+    case "page.waitFor":
+      return executeInTab(params, waitForPage, [params.kind, params.value, params.timeoutMs || 10000, params.intervalMs || 250]);
+    case "page.navigate": {
+      const tab = await getTabByParams(params);
+      const wait = params.waitUntilLoad !== false ? waitForTabComplete(tab.id, params.timeoutMs || 15000) : Promise.resolve(undefined);
+      const updated = await chrome.tabs.update(tab.id, { url: params.url, active: true });
+      await wait;
+      return formatTab(await chrome.tabs.get(updated.id));
+    }
+    case "page.screenshot": {
+      const tab = await getTabByParams(params);
+      await chrome.windows.update(tab.windowId, { focused: true });
+      await chrome.tabs.update(tab.id, { active: true });
+      const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, {
+        format: params.format || "png",
+        quality: params.format === "jpeg" ? params.quality : undefined,
+      });
+      return { dataUrl, tab: formatTab(tab) };
+    }
+    default:
+      throw new Error(`Unknown action: ${action}`);
+  }
+}
+
+function formatTab(tab) {
+  return {
+    id: tab.id,
+    windowId: tab.windowId,
+    active: tab.active,
+    highlighted: tab.highlighted,
+    title: tab.title || "",
+    url: tab.url || "",
+    status: tab.status,
+    pinned: tab.pinned,
+    incognito: tab.incognito,
+  };
+}
+
+async function getTabByParams(params) {
+  const tabs = await chrome.tabs.query({});
+  let tab;
+  if (params.targetId !== undefined) {
+    const id = Number(params.targetId);
+    tab = tabs.find((candidate) => candidate.id === id);
+  } else if (params.urlIncludes) {
+    tab = tabs.find((candidate) => (candidate.url || "").includes(params.urlIncludes));
+  } else if (params.titleIncludes) {
+    tab = tabs.find((candidate) => (candidate.title || "").includes(params.titleIncludes));
+  } else {
+    const active = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
+    tab = active[0] || tabs.find((candidate) => candidate.active) || tabs[0];
+  }
+  if (!tab?.id) throw new Error("No matching Chrome tab found");
+  if ((tab.url || "").startsWith("chrome://") || (tab.url || "").startsWith("chrome-extension://")) {
+    throw new Error(`Chrome blocks extension automation on protected URL: ${tab.url}`);
+  }
+  return tab;
+}
+
+async function executeInTab(params, func, args) {
+  const tab = await getTabByParams(params);
+  await chrome.windows.update(tab.windowId, { focused: true });
+  await chrome.tabs.update(tab.id, { active: true });
+  const results = await chrome.scripting.executeScript({
+    target: { tabId: tab.id },
+    world: "MAIN",
+    func,
+    args,
+  });
+  return results?.[0]?.result;
+}
+
+function waitForTabComplete(tabId, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      chrome.tabs.onUpdated.removeListener(listener);
+      reject(new Error(`Timed out after ${timeoutMs}ms waiting for tab ${tabId} to load`));
+    }, timeoutMs);
+    const listener = (updatedTabId, changeInfo) => {
+      if (updatedTabId === tabId && changeInfo.status === "complete") {
+        clearTimeout(timer);
+        chrome.tabs.onUpdated.removeListener(listener);
+        resolve(true);
+      }
+    };
+    chrome.tabs.onUpdated.addListener(listener);
+  });
+}
+
+function snapshotPage(maxElements) {
+  const unique = (selector) => {
+    try { return document.querySelectorAll(selector).length === 1; } catch { return false; }
+  };
+  const cssEscape = (value) => (window.CSS && CSS.escape) ? CSS.escape(value) : String(value).replace(/[^a-zA-Z0-9_-]/g, "\\$&");
+  const selectorFor = (element) => {
+    if (element.id && unique("#" + cssEscape(element.id))) return "#" + cssEscape(element.id);
+    const attr = ["aria-label", "name", "placeholder", "data-testid", "role"].find((name) => element.getAttribute(name));
+    if (attr) {
+      const candidate = element.tagName.toLowerCase() + "[" + attr + "=" + JSON.stringify(element.getAttribute(attr)) + "]";
+      if (unique(candidate)) return candidate;
+    }
+    const parts = [];
+    let current = element;
+    while (current && current.nodeType === Node.ELEMENT_NODE && parts.length < 5) {
+      let part = current.tagName.toLowerCase();
+      if (current.classList.length > 0) part += "." + Array.from(current.classList).slice(0, 2).map(cssEscape).join(".");
+      const siblings = Array.from(current.parentElement?.children ?? []).filter((sibling) => sibling.tagName === current.tagName);
+      if (siblings.length > 1) part += ":nth-of-type(" + (siblings.indexOf(current) + 1) + ")";
+      parts.unshift(part);
+      const candidate = parts.join(" > ");
+      if (unique(candidate)) return candidate;
+      current = current.parentElement;
+    }
+    return parts.join(" > ");
+  };
+  const visible = (element) => {
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
+  };
+  const labelFor = (element) => (
+    element.getAttribute("aria-label") ||
+    element.getAttribute("title") ||
+    element.getAttribute("placeholder") ||
+    element.innerText ||
+    element.value ||
+    element.textContent ||
+    ""
+  ).trim().replace(/\s+/g, " ").slice(0, 160);
+  const candidates = Array.from(document.querySelectorAll('a, button, input, textarea, select, summary, [role="button"], [role="link"], [contenteditable="true"], [tabindex]:not([tabindex="-1"])'));
+  const elements = candidates.filter(visible).slice(0, maxElements).map((element, index) => {
+    const rect = element.getBoundingClientRect();
+    return {
+      index,
+      tag: element.tagName.toLowerCase(),
+      selector: selectorFor(element),
+      label: labelFor(element),
+      href: element.href || undefined,
+      type: element.getAttribute("type") || undefined,
+      role: element.getAttribute("role") || undefined,
+      disabled: Boolean(element.disabled || element.getAttribute("aria-disabled") === "true"),
+      rect: { x: Math.round(rect.x), y: Math.round(rect.y), width: Math.round(rect.width), height: Math.round(rect.height) },
+    };
+  });
+  return {
+    title: document.title,
+    url: location.href,
+    viewport: { width: innerWidth, height: innerHeight, scrollX, scrollY },
+    text: document.body ? document.body.innerText.replace(/\s+\n/g, "\n").trim().slice(0, 30000) : "",
+    elements,
+  };
+}
+
+async function evaluateExpression(expression, awaitPromise) {
+  const indirectEval = (0, eval);
+  const value = indirectEval(expression);
+  return awaitPromise && value && typeof value.then === "function" ? await value : value;
+}
+
+function 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 };
+}
+
+function clickPage(selector, x, y) {
+  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"]) {
+    point.element.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, view: window, clientX: point.x, clientY: point.y, button: 0 }));
+  }
+  return { x: point.x, y: point.y, selector, tag: point.element.tagName };
+}
+
+function typeIntoPage(selector, text, pressEnter) {
+  let element = selector ? document.querySelector(selector) : document.activeElement;
+  if (!element) throw new Error(selector ? `No element matches selector: ${selector}` : "No active element");
+  element.focus();
+  if (element.isContentEditable) {
+    document.execCommand("insertText", false, text);
+  } else if ("value" in element) {
+    const start = element.selectionStart ?? element.value.length;
+    const end = element.selectionEnd ?? element.value.length;
+    element.value = element.value.slice(0, start) + text + element.value.slice(end);
+    element.selectionStart = element.selectionEnd = start + text.length;
+    element.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "insertText", data: text }));
+    element.dispatchEvent(new Event("change", { bubbles: true }));
+  } else {
+    throw new Error("Focused element is not text-editable");
+  }
+  if (pressEnter) pressKeyInPage("Enter");
+  return { selector, length: text.length, pressEnter };
+}
+
+function pressKeyInPage(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 };
+}
+
+async function waitForPage(kind, value, timeoutMs, intervalMs) {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    let ok = false;
+    if (kind === "selector") ok = Boolean(document.querySelector(value));
+    else ok = Boolean((0, eval)(value));
+    if (ok) return { elapsedMs: Date.now() - started };
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  throw new Error(`Timed out after ${timeoutMs}ms waiting for ${kind}: ${value}`);
+}
+
+function 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;
+}

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

@@ -0,0 +1,550 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { existsSync, statSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * Existing-profile Chrome bridge for pi.
+ *
+ * This is intentionally not a Chrome DevTools Protocol integration. CDP cannot attach to
+ * already-running normal Chrome windows and recent Chrome builds block default-profile
+ * remote debugging. Instead, install the companion Chrome extension from the
+ * browser-extension folder bundled next to this Pi extension.
+ *
+ * The companion extension runs inside the user's real Chrome profile and polls this local
+ * pi extension for commands. That gives pi access to the user's existing tabs/authenticated
+ * profile, subject to the browser extension permissions the user grants.
+ */
+
+type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+type ToolTextResult = {
+	content: Array<{ type: "text"; text: string }>;
+	details?: Record<string, unknown>;
+};
+
+type BridgeCommand = {
+	id: string;
+	action: string;
+	params: Record<string, unknown>;
+};
+
+type PendingCommand = {
+	command: BridgeCommand;
+	resolve: (value: unknown) => void;
+	reject: (error: Error) => void;
+	timer: NodeJS.Timeout;
+};
+
+type BridgeResult = {
+	id: string;
+	ok: boolean;
+	result?: unknown;
+	error?: string;
+};
+
+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;
+const MAX_TEXT_CHARS = 30_000;
+const MAX_ELEMENTS = 80;
+
+function truncateText(text: string, maxChars = MAX_TEXT_CHARS): string {
+	if (text.length <= maxChars) return text;
+	return `${text.slice(0, maxChars)}\n\n[truncated ${text.length - maxChars} characters]`;
+}
+
+function safeJson(value: unknown): string {
+	return JSON.stringify(value, null, 2);
+}
+
+function extensionRoot(): string {
+	// Resolve relative to this extension file, not ctx.cwd. ctx.cwd can temporarily be
+	// an attachment/clipboard path when Pi is handling pasted images.
+	if (typeof __dirname === "string") return __dirname;
+	return process.cwd();
+}
+
+function workspaceCwd(ctx: ExtensionContext): string {
+	for (const candidate of [ctx.cwd, process.cwd()]) {
+		if (!candidate) continue;
+		try {
+			if (existsSync(candidate) && statSync(candidate).isDirectory()) return candidate;
+		} catch {
+			// try next candidate
+		}
+	}
+	return process.cwd();
+}
+
+function browserExtensionPath(): string {
+	return join(extensionRoot(), "browser-extension");
+} 
+
+function readRequestBody(request: IncomingMessage): Promise<string> {
+	return new Promise((resolveBody, rejectBody) => {
+		const chunks: Buffer[] = [];
+		request.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+		request.on("end", () => resolveBody(Buffer.concat(chunks).toString("utf8")));
+		request.on("error", rejectBody);
+	});
+}
+
+function sendJson(response: ServerResponse, status: number, body: unknown): void {
+	response.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"access-control-allow-origin": "*",
+		"access-control-allow-methods": "GET,POST,OPTIONS",
+		"access-control-allow-headers": "content-type",
+		"cache-control": "no-store",
+	});
+	response.end(JSON.stringify(body));
+}
+
+class ChromeProfileBridge {
+	private server: Server | undefined;
+	private pending = new Map<string, PendingCommand>();
+	private queue: BridgeCommand[] = [];
+	private waiters: Array<(command: BridgeCommand | undefined) => void> = [];
+	private lastSeenAt: number | undefined;
+	private clientName: string | undefined;
+
+	constructor(
+		private readonly host: string,
+		private readonly port: number,
+	) {}
+
+	get url(): string {
+		return `http://${this.host}:${this.port}`;
+	}
+
+	get connected(): boolean {
+		// MV3 service workers can pause between polls/alarms. Treat a recent poll as
+		// connected without sending a synthetic command; real chrome_* tool calls are
+		// the authoritative end-to-end health check.
+		return this.lastSeenAt !== undefined && Date.now() - this.lastSeenAt < 5 * 60_000;
+	}
+
+	status(): Record<string, unknown> {
+		return {
+			url: this.url,
+			connected: this.connected,
+			lastSeenAt: this.lastSeenAt,
+			clientName: this.clientName,
+			queuedCommands: this.queue.length,
+			pendingCommands: this.pending.size,
+		};
+	}
+
+	async start(): Promise<void> {
+		if (this.server) return;
+		this.server = createServer((request, response) => {
+			void this.handle(request, response).catch((error) => {
+				sendJson(response, 500, { error: (error as Error).message });
+			});
+		});
+		await new Promise<void>((resolveStart, rejectStart) => {
+			this.server!.once("error", rejectStart);
+			this.server!.listen(this.port, this.host, () => {
+				this.server!.off("error", rejectStart);
+				resolveStart();
+			});
+		});
+	}
+
+	stop(): void {
+		for (const pending of this.pending.values()) {
+			clearTimeout(pending.timer);
+			pending.reject(new Error("Chrome profile bridge stopped"));
+		}
+		this.pending.clear();
+		this.queue = [];
+		for (const waiter of this.waiters) waiter(undefined);
+		this.waiters = [];
+		this.server?.close();
+		this.server = undefined;
+	}
+
+	send(action: string, params: Record<string, unknown>, timeoutMs = DEFAULT_TIMEOUT_MS): Promise<unknown> {
+		const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+		const command = { id, action, params };
+		return new Promise((resolveCommand, rejectCommand) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				this.queue = this.queue.filter((queued) => queued.id !== id);
+				rejectCommand(
+					new Error(
+						`Timed out waiting for Chrome extension after ${timeoutMs}ms. Run /chrome-onboard, then load the bundled browser-extension folder in your normal Chrome profile.`,
+					),
+				);
+			}, timeoutMs);
+			this.pending.set(id, { command, resolve: resolveCommand, reject: rejectCommand, timer });
+			this.enqueue(command);
+		});
+	}
+
+	private enqueue(command: BridgeCommand): void {
+		const waiter = this.waiters.shift();
+		if (waiter) waiter(command);
+		else this.queue.push(command);
+	}
+
+	private async handle(request: IncomingMessage, response: ServerResponse): Promise<void> {
+		if (request.method === "OPTIONS") {
+			sendJson(response, 200, { ok: true });
+			return;
+		}
+		const url = new URL(request.url ?? "/", this.url);
+		if (request.method === "GET" && url.pathname === "/status") {
+			sendJson(response, 200, this.status());
+			return;
+		}
+		if (request.method === "GET" && url.pathname === "/next") {
+			this.lastSeenAt = Date.now();
+			this.clientName = url.searchParams.get("name") ?? undefined;
+			const command = this.queue.shift() ?? (await this.waitForCommand(25_000));
+			sendJson(response, 200, command ? { type: "command", command } : { type: "none" });
+			return;
+		}
+		if (request.method === "POST" && url.pathname === "/result") {
+			this.lastSeenAt = Date.now();
+			const result = JSON.parse(await readRequestBody(request)) as BridgeResult;
+			const pending = this.pending.get(result.id);
+			if (!pending) {
+				sendJson(response, 404, { ok: false, error: "unknown command id" });
+				return;
+			}
+			clearTimeout(pending.timer);
+			this.pending.delete(result.id);
+			if (result.ok) pending.resolve(result.result);
+			else pending.reject(new Error(result.error ?? "Chrome extension command failed"));
+			sendJson(response, 200, { ok: true });
+			return;
+		}
+		sendJson(response, 404, { error: "not found" });
+	}
+
+	private waitForCommand(timeoutMs: number): Promise<BridgeCommand | undefined> {
+		return new Promise((resolveWait) => {
+			const timer = setTimeout(() => {
+				this.waiters = this.waiters.filter((waiter) => waiter !== resolveWait);
+				resolveWait(undefined);
+			}, timeoutMs);
+			this.waiters.push((command) => {
+				clearTimeout(timer);
+				resolveWait(command);
+			});
+		});
+	}
+}
+
+const tabActionValues = ["list", "new", "activate", "close", "version"] as const;
+const imageFormatValues = ["png", "jpeg"] as const;
+const waitForValues = ["selector", "expression"] as const;
+
+export default function (pi: ExtensionAPI): void {
+	const bridge = new ChromeProfileBridge(DEFAULT_HOST, DEFAULT_PORT);
+
+	pi.on("session_start", async (_event, ctx) => {
+		await bridge.start();
+		ctx.ui.setStatus("chrome", `Chrome bridge :${DEFAULT_PORT}`);
+		ctx.ui.notify(
+			`Chrome profile bridge listening at ${bridge.url}. Run /chrome-onboard to load the bundled browser extension in your normal Chrome profile.`,
+			"info",
+		);
+	});
+
+	pi.on("session_shutdown", () => {
+		bridge.stop();
+	});
+
+	pi.on("before_agent_start", (event) => {
+		const primer = `
+<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.
+</chrome-profile-bridge>`;
+		return { systemPrompt: event.systemPrompt + primer };
+	});
+
+	pi.registerCommand("chrome-status", {
+		description: "Run an explicit health check against the existing-profile Chrome companion extension",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify("Performing Chrome bridge health check", "info");
+			try {
+				const version = (await bridge.send("tab.version", {}, 35_000)) as { extensionId?: string };
+				ctx.ui.notify(
+					version.extensionId
+						? `Chrome profile bridge connected (ID: ${version.extensionId})`
+						: "Chrome profile bridge connected",
+					"info",
+				);
+			} catch {
+				ctx.ui.notify("Chrome bridge health check timed out. Run /chrome-onboard to connect Chrome.", "warning");
+			}
+		},
+	});
+
+	pi.registerCommand("chrome-onboard", {
+		description: "Guide Chrome extension setup for the existing-profile bridge",
+		handler: async (_args, ctx) => {
+			const extensionPath = browserExtensionPath();
+			const proceed = await ctx.ui.confirm(
+				"Chrome bridge setup",
+				`This will open chrome://extensions and reveal the extension folder in Finder.\n\nAfter the windows open: enable Developer mode → Load unpacked → select:\n${extensionPath}\n\nPress Enter to continue, or Esc to cancel.`,
+			);
+			if (!proceed) {
+				ctx.ui.notify("Chrome bridge setup cancelled", "info");
+				return;
+			}
+			if (process.platform === "darwin") {
+				await pi.exec("open", ["-a", "Google Chrome", "chrome://extensions"], { cwd: workspaceCwd(ctx), timeout: 5_000 }).catch(() => undefined);
+				await pi.exec("open", ["-R", join(extensionPath, "manifest.json")], { cwd: workspaceCwd(ctx), timeout: 5_000 }).catch(() => undefined);
+				await pi.exec("sh", ["-lc", `printf %s ${JSON.stringify(extensionPath)} | pbcopy`], { cwd: workspaceCwd(ctx), timeout: 5_000 }).catch(() => undefined);
+			}
+			ctx.ui.notify(
+				"Chrome bridge setup opened. The extension path has been copied to your clipboard. After loading it, run /chrome-status.",
+				"info",
+			);
+		},
+	});
+
+	pi.registerTool({
+		name: "chrome_launch",
+		label: "Chrome Bridge Setup",
+		description:
+			"Start/check the local bridge used by the companion Chrome extension. This does not launch a separate Chrome profile; install the unpacked Chrome extension in your existing Chrome profile to connect.",
+		promptSnippet: "Show instructions for connecting Pi to the user's existing Chrome profile via the companion extension.",
+		parameters: Type.Object({
+			port: Type.Optional(Type.Number({ description: "Ignored unless PI_CHROME_BRIDGE_PORT is set before Pi starts." })),
+			url: Type.Optional(Type.String({ description: "Optional URL to open in the existing Chrome profile after the extension is connected." })),
+			userDataDir: Type.Optional(Type.String({ description: "Ignored. This bridge intentionally uses the user's existing Chrome profile through the companion extension." })),
+			useDefaultProfile: Type.Optional(Type.Boolean({ description: "Ignored; existing-profile access comes from the companion Chrome extension." })),
+			headless: Type.Optional(Type.Boolean({ description: "Ignored." })),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx): Promise<ToolTextResult> {
+			if (params.url && bridge.connected) {
+				const result = await bridge.send("tab.new", { url: params.url }, DEFAULT_TIMEOUT_MS);
+				return { content: [{ type: "text", text: `Chrome bridge connected; opened ${params.url}` }], details: { status: bridge.status(), result } };
+			}
+			return {
+				content: [
+					{
+						type: "text",
+						text:
+							`Chrome profile bridge is listening at ${bridge.url}.\n\n` +
+							`To connect your existing Chrome profile:\n` +
+							`1. Open chrome://extensions in the Chrome profile you normally use.\n` +
+							`2. Enable Developer mode.\n` +
+							`3. Click “Load unpacked”.\n` +
+							`4. Select: ${browserExtensionPath()}\n\n` +
+							`Status: ${bridge.connected ? "connected" : "waiting for extension"}.`,
+					},
+				],
+				details: { status: bridge.status(), extensionPath: browserExtensionPath() },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "chrome_tab",
+		label: "Chrome Tab",
+		description: "List, create, activate, close, or inspect tabs in the user's existing Chrome profile via the companion extension.",
+		promptSnippet: "List/open/activate/close existing Chrome tabs through the companion extension.",
+		parameters: Type.Object({
+			action: StringEnum(tabActionValues),
+			url: Type.Optional(Type.String({ description: "URL for action=new." })),
+			targetId: Type.Optional(Type.String({ description: "Chrome tab id for activate/close." })),
+			host: Type.Optional(Type.String()),
+			port: Type.Optional(Type.Number()),
+		}),
+		async execute(_id, params): Promise<ToolTextResult> {
+			const result = await bridge.send(`tab.${params.action}`, params, DEFAULT_TIMEOUT_MS);
+			if (params.action === "list") {
+				const tabs = result as Array<{ id: number; title: string; url: string; active: boolean; windowId: number }>;
+				const text = tabs.map((tab) => `${tab.id}\t${tab.active ? "*" : " "}\t${tab.title || "(untitled)"}\t${tab.url}`).join("\n") || "No tabs.";
+				return { content: [{ type: "text", text }], details: { tabs } };
+			}
+			return { content: [{ type: "text", text: safeJson(result) }], details: { result: result as Json } };
+		},
+	});
+
+	pi.registerTool({
+		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.",
+		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 })),
+			host: Type.Optional(Type.String()),
+			port: Type.Optional(Type.Number()),
+		}),
+		async execute(_id, params): Promise<ToolTextResult> {
+			const snapshot = await bridge.send("page.snapshot", { ...params, maxElements: params.maxElements ?? MAX_ELEMENTS }, DEFAULT_TIMEOUT_MS);
+			return { content: [{ type: "text", text: truncateText(safeJson(snapshot)) }], details: { snapshot } };
+		},
+	});
+
+	pi.registerTool({
+		name: "chrome_navigate",
+		label: "Chrome Navigate",
+		description: "Navigate an existing Chrome tab to a URL via the companion extension. Optionally waits for load completion.",
+		promptSnippet: "Navigate a Chrome tab in the user's existing profile.",
+		parameters: Type.Object({
+			url: Type.String(),
+			targetId: Type.Optional(Type.String()),
+			urlIncludes: Type.Optional(Type.String()),
+			titleIncludes: Type.Optional(Type.String()),
+			waitUntilLoad: Type.Optional(Type.Boolean({ default: true })),
+			timeoutMs: Type.Optional(Type.Number({ default: 15_000 })),
+			host: Type.Optional(Type.String()),
+			port: Type.Optional(Type.Number()),
+		}),
+		async execute(_id, params): Promise<ToolTextResult> {
+			const result = await bridge.send("page.navigate", params, params.timeoutMs ?? 15_000);
+			return { content: [{ type: "text", text: `Navigated to ${params.url}` }], details: { result: result as Json } };
+		},
+	});
+
+	pi.registerTool({
+		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.",
+		promptSnippet: "Evaluate JavaScript in the active Chrome tab through the companion extension.",
+		parameters: Type.Object({
+			expression: Type.String(),
+			awaitPromise: Type.Optional(Type.Boolean({ default: true })),
+			returnByValue: Type.Optional(Type.Boolean({ default: true })),
+			targetId: Type.Optional(Type.String()),
+			urlIncludes: Type.Optional(Type.String()),
+			titleIncludes: Type.Optional(Type.String()),
+			host: Type.Optional(Type.String()),
+			port: Type.Optional(Type.Number()),
+		}),
+		async execute(_id, params): Promise<ToolTextResult> {
+			const value = await bridge.send("page.evaluate", params, DEFAULT_TIMEOUT_MS);
+			return { content: [{ type: "text", text: truncateText(typeof value === "string" ? value : safeJson(value)) }], details: { value: value as Json } };
+		},
+	});
+
+	pi.registerTool({
+		name: "chrome_click",
+		label: "Chrome Click",
+		description: "Click a CSS selector or viewport coordinate in an existing Chrome tab through the companion extension.",
+		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." })),
+			x: Type.Optional(Type.Number({ description: "Viewport x coordinate if selector is omitted." })),
+			y: Type.Optional(Type.Number({ description: "Viewport y coordinate if selector is omitted." })),
+			targetId: Type.Optional(Type.String()),
+			urlIncludes: Type.Optional(Type.String()),
+			titleIncludes: Type.Optional(Type.String()),
+			host: Type.Optional(Type.String()),
+			port: Type.Optional(Type.Number()),
+		}),
+		async execute(_id, params): Promise<ToolTextResult> {
+			const result = await bridge.send("page.click", params, DEFAULT_TIMEOUT_MS);
+			return { content: [{ type: "text", text: `Clicked ${params.selector ?? `${params.x},${params.y}`}` }], details: { result: result as Json } };
+		},
+	});
+
+	pi.registerTool({
+		name: "chrome_type",
+		label: "Chrome Type",
+		description: "Focus an optional CSS selector, then type text into an existing Chrome tab through the companion extension.",
+		promptSnippet: "Type text into Chrome, optionally focusing a selector first.",
+		parameters: Type.Object({
+			text: Type.String(),
+			selector: Type.Optional(Type.String({ description: "CSS selector to focus before typing." })),
+			pressEnter: Type.Optional(Type.Boolean()),
+			targetId: Type.Optional(Type.String()),
+			urlIncludes: Type.Optional(Type.String()),
+			titleIncludes: Type.Optional(Type.String()),
+			host: Type.Optional(Type.String()),
+			port: Type.Optional(Type.Number()),
+		}),
+		async execute(_id, params): Promise<ToolTextResult> {
+			const result = await bridge.send("page.type", params, DEFAULT_TIMEOUT_MS);
+			return { content: [{ type: "text", text: `Typed ${params.text.length} character(s)${params.selector ? ` into ${params.selector}` : ""}.` }], details: { result: result as Json } };
+		},
+	});
+
+	pi.registerTool({
+		name: "chrome_key",
+		label: "Chrome Key",
+		description: "Send a keyboard key to an existing Chrome tab (Enter, Escape, Tab, Backspace, Delete, ArrowUp/Down/Left/Right, or one character).",
+		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()),
+			host: Type.Optional(Type.String()),
+			port: Type.Optional(Type.Number()),
+		}),
+		async execute(_id, params): Promise<ToolTextResult> {
+			const result = await bridge.send("page.key", params, DEFAULT_TIMEOUT_MS);
+			return { content: [{ type: "text", text: `Pressed ${params.key}.` }], details: { result: result as Json } };
+		},
+	});
+
+	pi.registerTool({
+		name: "chrome_wait_for",
+		label: "Chrome Wait For",
+		description: "Poll an existing Chrome tab until a selector exists or a JavaScript expression returns truthy.",
+		promptSnippet: "Wait for page state in Chrome before further automation.",
+		parameters: Type.Object({
+			kind: StringEnum(waitForValues),
+			value: Type.String({ description: "CSS selector when kind=selector; JavaScript expression when kind=expression." }),
+			timeoutMs: Type.Optional(Type.Number({ default: 10_000 })),
+			intervalMs: Type.Optional(Type.Number({ default: 250 })),
+			targetId: Type.Optional(Type.String()),
+			urlIncludes: Type.Optional(Type.String()),
+			titleIncludes: Type.Optional(Type.String()),
+			host: Type.Optional(Type.String()),
+			port: Type.Optional(Type.Number()),
+		}),
+		async execute(_id, params): Promise<ToolTextResult> {
+			const result = await bridge.send("page.waitFor", params, (params.timeoutMs ?? 10_000) + 2_000);
+			return { content: [{ type: "text", text: `Observed ${params.kind}: ${params.value}` }], details: { result: result as Json } };
+		},
+	});
+
+	pi.registerTool({
+		name: "chrome_screenshot",
+		label: "Chrome Screenshot",
+		description: "Capture a screenshot of an existing Chrome tab via the companion extension and save it to disk.",
+		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>." })),
+			format: Type.Optional(StringEnum(imageFormatValues)),
+			quality: Type.Optional(Type.Number({ description: "JPEG quality 0-100." })),
+			fullPage: Type.Optional(Type.Boolean({ description: "Not supported by the extension bridge yet; viewport screenshots are captured." })),
+			targetId: Type.Optional(Type.String()),
+			urlIncludes: Type.Optional(Type.String()),
+			titleIncludes: Type.Optional(Type.String()),
+			host: Type.Optional(Type.String()),
+			port: Type.Optional(Type.Number()),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx: ExtensionContext): Promise<ToolTextResult> {
+			const format = params.format ?? "png";
+			const cwd = workspaceCwd(ctx);
+			const defaultPath = join(cwd, ".pi", "chrome-screenshots", `${new Date().toISOString().replace(/[:.]/g, "-")}.${format}`);
+			const outputPath = params.path ? resolve(cwd, params.path) : defaultPath;
+			const result = (await bridge.send("page.screenshot", params, DEFAULT_TIMEOUT_MS)) as { dataUrl: string; tab?: unknown };
+			const base64 = result.dataUrl.replace(/^data:image\/(?:png|jpeg);base64,/, "");
+			await mkdir(dirname(outputPath), { recursive: true });
+			await writeFile(outputPath, Buffer.from(base64, "base64"));
+			return { content: [{ type: "text", text: `Saved Chrome screenshot to ${outputPath}` }], details: { path: outputPath, format, tab: result.tab } };
+		},
+	});
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "pi-chrome",
+  "version": "0.1.0",
+  "description": "Pi extension for controlling the user's existing Chrome profile through a companion browser extension.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "chrome",
+    "browser",
+    "automation"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "files": [
+    "extensions",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/chrome-profile-bridge/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}