@oh-my-pi/pi-coding-agent 17.2.4 → 17.2.6

package/src/tools/browser/relay/daemon.ts

@@ -0,0 +1,117 @@
+/**
+ * Broker-owned browser relay daemon.
+ *
+ * The MV3 extension can only dial OUT (service workers cannot listen on
+ * sockets), so a native process must own the relay port. Instead of making
+ * the user run `omp browser-relay` by hand, the relay kind lazily starts one
+ * under a profile-independent, machine-global daemon broker. Every relay
+ * consumer holds a connection to that broker, so one project exiting cannot
+ * tear down the fixed-port singleton while another project still uses it.
+ *
+ * A manually started relay may already own the port. Consumers still acquire
+ * the global broker lease before probing, then adopt that external server
+ * without attempting another bind.
+ */
+import { logger } from "@oh-my-pi/pi-utils";
+import { daemonClientForGlobal } from "../../../launch/client";
+import { describeQuietly, stopQuietly, waitReady } from "../../../launch/ensure";
+import { resolveWorkerSpawnCmd } from "../../../subprocess/worker-client";
+import { throwIfAborted } from "../../tool-errors";
+
+/** Stable broker daemon name for the relay server. */
+export const RELAY_DAEMON_NAME = "omp.browser.relay";
+const RELAY_BROKER_SCOPE = "browser-relay";
+/** Matches the serve banner (`omp browser relay listening on http://…`). */
+const READY_LOG_PATTERN = String.raw`browser relay listening on http://\S+`;
+const READY_TIMEOUT_MS = 15_000;
+const PROBE_TIMEOUT_MS = 1_500;
+/** probe→describe→start rounds; bounds cross-process races and wedged-relay replacement. */
+const ENSURE_ATTEMPTS = 3;
+
+/** True when the relay HTTP server answers /json/version at all (200 = extension connected, 503 = waiting for it). */
+export async function probeRelayServer(cdpUrl: string): Promise<boolean> {
+	try {
+		const res = await fetch(`${cdpUrl}/json/version`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+		await res.body?.cancel();
+		return res.ok || res.status === 503;
+	} catch {
+		return false;
+	}
+}
+
+/** Auto-start is only safe for endpoints this machine can own. */
+export function isLoopbackRelayUrl(cdpUrl: string): boolean {
+	try {
+		const { hostname } = new URL(cdpUrl);
+		return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "[::1]" || hostname === "::1";
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Ensure a relay server answers at `cdpUrl`, starting the broker-owned daemon
+ * when nothing is serving. Returns true once the HTTP endpoint responds — the
+ * extension handshake (503 → 200) is the caller's wait. False when the relay
+ * could not be started (broker unavailable or start rounds exhausted).
+ */
+export async function ensureRelayDaemon(opts: { cdpUrl: string; signal?: AbortSignal }): Promise<boolean> {
+	let port: string;
+	try {
+		port = String(new URL(opts.cdpUrl).port || 80);
+	} catch {
+		return false;
+	}
+	// Open the lazy client before probing. Merely caching SocketDaemonClient
+	// would not create the broker connection (and therefore would hold no lease).
+	const client = await daemonClientForGlobal(RELAY_BROKER_SCOPE);
+	throwIfAborted(opts.signal);
+	await client.request({ op: "ping" }, opts.signal);
+	if (await probeRelayServer(opts.cdpUrl)) return true;
+	const spawn = resolveWorkerSpawnCmd("browser-relay");
+	for (let attempt = 0; attempt < ENSURE_ATTEMPTS; attempt++) {
+		throwIfAborted(opts.signal);
+		// A manual serve or concurrent global-broker start may have won the
+		// port since the last round; adopt it instead of fighting the bind.
+		if (await probeRelayServer(opts.cdpUrl)) return true;
+		const existing = await describeQuietly(client, RELAY_DAEMON_NAME, "Browser relay", opts.signal);
+		if (existing && existing.state !== "exited" && existing.state !== "failed") {
+			if (existing.readyAt === undefined) await waitReady(client, RELAY_DAEMON_NAME, "Browser relay", opts.signal);
+			if (await probeRelayServer(opts.cdpUrl)) return true;
+			// Live record but nothing listening: replace the wedged daemon.
+			await stopQuietly(client, RELAY_DAEMON_NAME, "Browser relay", opts.signal);
+			continue;
+		}
+		try {
+			const started = await client.request(
+				{
+					op: "start",
+					spec: {
+						name: RELAY_DAEMON_NAME,
+						application: spawn.cmd[0]!,
+						args: [...spawn.cmd.slice(1), "--port", port],
+						env: {},
+						cwd: spawn.cwd ?? client.projectDir,
+						pty: false,
+						ready: { log: READY_LOG_PATTERN, timeoutMs: READY_TIMEOUT_MS },
+						restart: "no",
+						persist: false,
+						detached: false,
+					},
+				},
+				opts.signal,
+			);
+			if (started.op !== "start") continue;
+			if (await probeRelayServer(opts.cdpUrl)) return true;
+			await stopQuietly(client, RELAY_DAEMON_NAME, "Browser relay", opts.signal);
+		} catch (error) {
+			throwIfAborted(opts.signal);
+			// Lost a cross-process start race; the next round adopts the winner.
+			logger.debug("Browser relay start contention", {
+				name: RELAY_DAEMON_NAME,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+	return false;
+}

package/src/tools/browser/relay/extension-assets/background.js.txt

@@ -0,0 +1,242 @@
+// extension/background.ts
+var DEFAULT_PORT = 9224;
+var PING_INTERVAL_MS = 20000;
+var RECONNECT_MIN_MS = 1000;
+var RECONNECT_MAX_MS = 1e4;
+var ws = null;
+var reconnectDelay = RECONNECT_MIN_MS;
+var pingTimer = null;
+async function loadSettings() {
+  const stored = await chrome.storage.local.get({ port: DEFAULT_PORT, token: "" });
+  const port = Number(stored.port);
+  return {
+    port: Number.isInteger(port) && port > 0 && port <= 65535 ? port : DEFAULT_PORT,
+    token: typeof stored.token === "string" ? stored.token : ""
+  };
+}
+function snapshot(tab) {
+  if (tab.id === undefined)
+    return null;
+  return {
+    tabId: tab.id,
+    url: tab.url ?? tab.pendingUrl ?? "",
+    title: tab.title ?? "",
+    active: tab.active,
+    windowId: tab.windowId,
+    pinned: tab.pinned,
+    groupId: tab.groupId
+  };
+}
+var ompGroupTitle = null;
+var groupOps = Promise.resolve();
+function enqueueGroupOp(fn) {
+  const result = groupOps.then(fn, fn);
+  groupOps = result.catch(() => {});
+  return result;
+}
+async function groupTabs(tabIds, title, color) {
+  ompGroupTitle = title;
+  chrome.storage.session.set({ ompGroupTitle: title });
+  const byWindow = new Map;
+  for (const tabId of tabIds) {
+    try {
+      const tab = await chrome.tabs.get(tabId);
+      if (tab.pinned || tab.id === undefined)
+        continue;
+      const bucket = byWindow.get(tab.windowId) ?? [];
+      bucket.push(tab.id);
+      byWindow.set(tab.windowId, bucket);
+    } catch {}
+  }
+  const grouped = {};
+  for (const [windowId, ids] of byWindow) {
+    const existing = await chrome.tabGroups.query({ title, windowId });
+    let groupId;
+    if (existing[0]) {
+      groupId = existing[0].id;
+      for (const dupe of existing.slice(1)) {
+        const dupeTabs = await chrome.tabs.query({ groupId: dupe.id });
+        const dupeIds = dupeTabs.map((tab) => tab.id).filter((id) => id !== undefined);
+        if (dupeIds.length > 0)
+          await chrome.tabs.group({ tabIds: dupeIds, groupId });
+      }
+      await chrome.tabs.group({ tabIds: ids, groupId });
+    } else {
+      groupId = await chrome.tabs.group({ tabIds: ids });
+    }
+    await chrome.tabGroups.update(groupId, { title, color });
+    for (const id of ids)
+      grouped[String(id)] = groupId;
+  }
+  return { grouped };
+}
+async function restoreGroups() {
+  if (!ompGroupTitle) {
+    const stored = await chrome.storage.session.get({ ompGroupTitle: "" }).catch(() => ({ ompGroupTitle: "" }));
+    ompGroupTitle = typeof stored.ompGroupTitle === "string" && stored.ompGroupTitle ? stored.ompGroupTitle : null;
+  }
+  if (!ompGroupTitle)
+    return;
+  const groups = await chrome.tabGroups.query({ title: ompGroupTitle }).catch(() => []);
+  for (const group of groups) {
+    const tabs = await chrome.tabs.query({ groupId: group.id }).catch(() => []);
+    const ids = tabs.map((tab) => tab.id).filter((id) => id !== undefined);
+    if (ids.length > 0)
+      await chrome.tabs.ungroup(ids).catch(() => {});
+  }
+}
+function post(msg) {
+  if (ws?.readyState === WebSocket.OPEN)
+    ws.send(JSON.stringify(msg));
+}
+async function setBadge(connected) {
+  try {
+    await chrome.action.setBadgeText({ text: connected ? "on" : "off" });
+    await chrome.action.setBadgeBackgroundColor({ color: connected ? "#1a7f37" : "#8b8b8b" });
+  } catch {}
+}
+async function buildHello() {
+  const [tabs, targets] = await Promise.all([chrome.tabs.query({}), chrome.debugger.getTargets()]);
+  const snapshots = [];
+  for (const tab of tabs) {
+    const snap = snapshot(tab);
+    if (snap)
+      snapshots.push(snap);
+  }
+  const attachedTabIds = [];
+  for (const target of targets) {
+    if (target.attached && target.tabId !== undefined)
+      attachedTabIds.push(target.tabId);
+  }
+  const versionMatch = /Chrome\/[\d.]+/.exec(navigator.userAgent);
+  return {
+    t: "hello",
+    userAgent: navigator.userAgent,
+    browserVersion: versionMatch?.[0] ?? "Chrome/unknown",
+    tabs: snapshots,
+    attachedTabIds
+  };
+}
+async function runRpc(msg) {
+  switch (msg.op) {
+    case "attach":
+      await chrome.debugger.attach({ tabId: msg.tabId }, "1.3");
+      return {};
+    case "detach":
+      await chrome.debugger.detach({ tabId: msg.tabId });
+      return {};
+    case "send":
+      return await chrome.debugger.sendCommand(msg.sessionId ? { tabId: msg.tabId, sessionId: msg.sessionId } : { tabId: msg.tabId }, msg.method, msg.params);
+    case "createTab": {
+      const tab = await chrome.tabs.create({ url: msg.url });
+      const snap = snapshot(tab);
+      if (!snap)
+        throw new Error("created tab has no id");
+      return { tab: snap };
+    }
+    case "removeTab":
+      await chrome.tabs.remove(msg.tabId);
+      return {};
+    case "activateTab": {
+      const tab = await chrome.tabs.get(msg.tabId);
+      await chrome.windows.update(tab.windowId, { focused: true });
+      await chrome.tabs.update(msg.tabId, { active: true });
+      return {};
+    }
+    case "group":
+      return await enqueueGroupOp(() => groupTabs(msg.tabIds, msg.title, msg.color));
+    case "ungroup":
+      await enqueueGroupOp(() => chrome.tabs.ungroup(msg.tabIds).catch(() => {}));
+      return {};
+  }
+}
+function handleRelayMessage(raw) {
+  let msg;
+  try {
+    msg = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (msg.t === "pong")
+    return;
+  runRpc(msg).then((result) => post({ t: "rpcResult", id: msg.id, ok: true, result })).catch((err) => {
+    post({ t: "rpcResult", id: msg.id, ok: false, error: err instanceof Error ? err.message : String(err) });
+  });
+}
+function scheduleReconnect() {
+  const delay = reconnectDelay;
+  reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
+  setTimeout(() => void connect(), delay);
+}
+async function connect() {
+  if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING))
+    return;
+  const settings = await loadSettings();
+  const url = `ws://127.0.0.1:${settings.port}/ext${settings.token ? `?token=${encodeURIComponent(settings.token)}` : ""}`;
+  const socket = new WebSocket(url);
+  ws = socket;
+  socket.onopen = () => {
+    reconnectDelay = RECONNECT_MIN_MS;
+    setBadge(true);
+    buildHello().then((hello) => post(hello));
+    clearInterval(pingTimer ?? undefined);
+    pingTimer = setInterval(() => post({ t: "ping" }), PING_INTERVAL_MS);
+  };
+  socket.onmessage = (event) => {
+    if (typeof event.data === "string")
+      handleRelayMessage(event.data);
+  };
+  socket.onclose = () => {
+    if (ws !== socket)
+      return;
+    ws = null;
+    if (pingTimer !== null) {
+      clearInterval(pingTimer);
+      pingTimer = null;
+    }
+    setBadge(false);
+    restoreGroups();
+    scheduleReconnect();
+  };
+  socket.onerror = () => {
+    socket.close();
+  };
+}
+chrome.debugger.onEvent.addListener((source, method, params) => {
+  if (source.tabId === undefined)
+    return;
+  post({ t: "cdpEvent", tabId: source.tabId, sessionId: source.sessionId, method, params });
+});
+chrome.debugger.onDetach.addListener((source, reason) => {
+  if (source.tabId === undefined)
+    return;
+  post({ t: "detached", tabId: source.tabId, reason });
+});
+chrome.tabs.onCreated.addListener((tab) => {
+  const snap = snapshot(tab);
+  if (snap)
+    post({ t: "tabCreated", tab: snap });
+});
+chrome.tabs.onUpdated.addListener((_tabId, _changeInfo, tab) => {
+  const snap = snapshot(tab);
+  if (snap)
+    post({ t: "tabUpdated", tab: snap });
+});
+chrome.tabs.onRemoved.addListener((tabId) => {
+  post({ t: "tabRemoved", tabId });
+});
+chrome.alarms.create("omp-relay-keepalive", { periodInMinutes: 0.5 });
+chrome.alarms.onAlarm.addListener((alarm) => {
+  if (alarm.name === "omp-relay-keepalive")
+    connect();
+});
+chrome.storage.onChanged.addListener((_changes, areaName) => {
+  if (areaName !== "local")
+    return;
+  ws?.close();
+  connect();
+});
+chrome.action.onClicked.addListener(() => void chrome.runtime.openOptionsPage());
+chrome.runtime.onInstalled.addListener(() => void connect());
+chrome.runtime.onStartup.addListener(() => void connect());
+connect();

package/src/tools/browser/relay/extension-assets/manifest.json.txt

@@ -0,0 +1,14 @@
+{
+	"manifest_version": 3,
+	"name": "OMP Browser Relay",
+	"version": "0.1.0",
+	"description": "Lets the omp coding agent drive your existing tabs through a local CDP relay.",
+	"permissions": ["debugger", "tabs", "tabGroups", "storage", "alarms"],
+	"background": {
+		"service_worker": "background.js"
+	},
+	"options_page": "options.html",
+	"action": {
+		"default_title": "OMP Browser Relay (click for settings)"
+	}
+}

package/src/tools/browser/relay/extension-assets/options.html.txt

@@ -0,0 +1,53 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>OMP Browser Relay settings</title>
+		<style>
+			body {
+				font-family: system-ui, sans-serif;
+				max-width: 28rem;
+				margin: 2rem auto;
+				padding: 0 1rem;
+				color: #1f2328;
+			}
+			label {
+				display: block;
+				margin: 1rem 0 0.25rem;
+				font-weight: 600;
+			}
+			input {
+				width: 100%;
+				padding: 0.4rem 0.5rem;
+				font: inherit;
+				box-sizing: border-box;
+			}
+			button {
+				margin-top: 1.25rem;
+				padding: 0.45rem 1.1rem;
+				font: inherit;
+			}
+			#status {
+				margin-left: 0.75rem;
+				color: #1a7f37;
+			}
+			p.hint {
+				color: #57606a;
+				font-size: 0.85rem;
+			}
+		</style>
+	</head>
+	<body>
+		<h1>OMP Browser Relay</h1>
+		<p class="hint">
+			The extension connects to a local <code>omp-browser-relay</code> process. Values here must match the flags the
+			relay was started with.
+		</p>
+		<label for="port">Relay port</label>
+		<input id="port" type="number" min="1" max="65535" />
+		<label for="token">Token (optional)</label>
+		<input id="token" type="text" autocomplete="off" />
+		<button id="save">Save</button><span id="status"></span>
+		<script src="options.js"></script>
+	</body>
+</html>

package/src/tools/browser/relay/extension-assets/options.js.txt

@@ -0,0 +1,23 @@
+// Options page for the OMP Browser Relay extension (plain JS: shipped as-is).
+const DEFAULT_PORT = 9224;
+const portInput = document.getElementById("port");
+const tokenInput = document.getElementById("token");
+const status = document.getElementById("status");
+
+chrome.storage.local.get({ port: DEFAULT_PORT, token: "" }).then(stored => {
+	portInput.value = String(stored.port);
+	tokenInput.value = String(stored.token);
+});
+
+document.getElementById("save").addEventListener("click", async () => {
+	const port = Number(portInput.value);
+	if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+		status.textContent = "invalid port";
+		return;
+	}
+	await chrome.storage.local.set({ port, token: tokenInput.value });
+	status.textContent = "saved";
+	setTimeout(() => {
+		status.textContent = "";
+	}, 1500);
+});

package/src/tools/browser/relay/kind.ts

@@ -0,0 +1,41 @@
+/**
+ * Browser relay mode: drive the user's own Chrome tabs through the local CDP
+ * relay served by `omp browser-relay` (sibling `server.ts`/`bridge.ts`) plus
+ * its companion extension (`packages/browser-relay`, installed via
+ * `omp browser-relay install`). The relay impersonates Chrome's CDP discovery
+ * endpoint, so beyond kind resolution the entire connected-browser machinery
+ * (registry, tab supervisor, tab workers) applies unchanged.
+ */
+import { parseFlag } from "@oh-my-pi/pi-utils";
+
+/** Browser kind selecting the omp browser relay. */
+export interface RelayKind {
+	kind: "relay";
+	cdpUrl: string;
+}
+
+/** Default endpoint of the `omp-browser-relay` CLI. */
+export const DEFAULT_RELAY_URL = "http://127.0.0.1:9224";
+
+export interface ResolveRelayKindOptions {
+	/** `browser.relay` setting; `PI_BROWSER_RELAY=0|1` overrides it. */
+	settingEnabled?: boolean;
+	/** `browser.relayUrl` setting; falls back to {@link DEFAULT_RELAY_URL}. */
+	url?: string;
+}
+
+/**
+ * Resolve the relay browser kind, or null when relay mode is disabled.
+ * Mirrors `resolveCmuxKind`: the setting opts in, the env var is the final
+ * override in both directions.
+ */
+export function resolveRelayKind(
+	options?: ResolveRelayKindOptions | null,
+	env: Record<string, string | undefined> = process.env,
+): RelayKind | null {
+	if (!parseFlag(env.PI_BROWSER_RELAY, options?.settingEnabled ?? false)) {
+		return null;
+	}
+	const url = options?.url?.trim() || DEFAULT_RELAY_URL;
+	return { kind: "relay", cdpUrl: url.replace(/\/+$/, "") };
+}

package/src/tools/browser/relay/protocol.ts

@@ -0,0 +1,54 @@
+/**
+ * Wire protocol between the relay server and the Chrome extension.
+ *
+ * The extension dials out to `ws://127.0.0.1:<port>/ext` and exchanges JSON
+ * messages. The relay drives the extension with numbered RPCs; the extension
+ * pushes tab lifecycle and `chrome.debugger` events as they happen.
+ */
+
+/** Minimal view of a Chrome tab shared between extension and relay. */
+export interface TabSnapshot {
+	tabId: number;
+	url: string;
+	title: string;
+	active: boolean;
+	windowId: number;
+	/** Pinned tabs are never grouped (Chrome would silently unpin them). */
+	pinned: boolean;
+	/** Chrome tab group id; -1 when ungrouped. */
+	groupId: number;
+}
+
+/** RPCs the relay may ask the extension to perform. */
+export type RelayRpcRequest =
+	| { op: "attach"; tabId: number }
+	| { op: "detach"; tabId: number }
+	| { op: "send"; tabId: number; sessionId?: string; method: string; params?: Record<string, unknown> }
+	| { op: "createTab"; url: string }
+	| { op: "removeTab"; tabId: number }
+	| { op: "activateTab"; tabId: number }
+	/** Add tabs to the per-window omp group (created/reused by title), remembering prior membership. */
+	| { op: "group"; tabIds: number[]; title: string; color: string }
+	/** Return tabs to their pre-omp group (or ungroup); no-op for tabs the relay never grouped. */
+	| { op: "ungroup"; tabIds: number[] };
+
+/** Messages sent relay → extension. */
+export type RelayToExtMessage = ({ t: "rpc"; id: number } & RelayRpcRequest) | { t: "pong" };
+
+/** Messages sent extension → relay. */
+export type ExtToRelayMessage =
+	| {
+			t: "hello";
+			userAgent: string;
+			browserVersion: string;
+			tabs: TabSnapshot[];
+			/** Tabs that already have a `chrome.debugger` attachment (relay reconciles after a service-worker restart). */
+			attachedTabIds: number[];
+	  }
+	| { t: "cdpEvent"; tabId: number; sessionId?: string; method: string; params?: Record<string, unknown> }
+	| { t: "detached"; tabId: number; reason: string }
+	| { t: "tabCreated"; tab: TabSnapshot }
+	| { t: "tabUpdated"; tab: TabSnapshot }
+	| { t: "tabRemoved"; tabId: number }
+	| { t: "rpcResult"; id: number; ok: boolean; result?: unknown; error?: string }
+	| { t: "ping" };

package/src/tools/browser/relay/server.ts

@@ -0,0 +1,141 @@
+/**
+ * HTTP + WebSocket server for the browser relay.
+ *
+ * Impersonates Chrome's CDP discovery endpoint so the omp browser tool (and
+ * any puppeteer client) can connect with a plain `browserURL`:
+ * - `GET /json/version` → 200 with `webSocketDebuggerUrl` once the extension
+ *   is connected, 503 before that (clients like `waitForCdp` keep polling).
+ * - `GET /json` / `/json/list` → attachable page targets (debugging aid).
+ * - `WS /cdp` → downstream CDP clients (puppeteer).
+ * - `WS /ext` → the Chrome extension (token-gated when configured).
+ *
+ * Binds loopback only: anything that can reach this port can drive the
+ * user's logged-in browser.
+ */
+import { RelayBridge } from "./bridge";
+
+/** Options for {@link startRelayServer}. */
+export interface RelayServerOptions {
+	port: number;
+	/** Shared secret the extension must present as `?token=`; unset disables the check. */
+	token?: string;
+	/** Group tabs the agent actively drives under one per-window Chrome tab group (default on); `false` disables. */
+	group?: boolean | { title: string; color: string };
+	log?: (message: string, data?: Record<string, unknown>) => void;
+}
+
+/** A running relay server. */
+export interface RelayServer {
+	bridge: RelayBridge;
+	port: number;
+	stop(): void;
+}
+
+interface SocketData {
+	role: "cdp" | "ext";
+	connId?: number;
+}
+
+type RelayWebSocket = Bun.ServerWebSocket<SocketData>;
+
+const WS_KEEPALIVE_MS = 30_000;
+/** Screenshots travel base64-encoded through both websocket legs. */
+const MAX_PAYLOAD_BYTES = 256 * 1024 * 1024;
+/** Default appearance of the omp tab group. */
+const DEFAULT_GROUP = { title: "omp", color: "cyan" } as const;
+
+/** Start the relay server on 127.0.0.1. Throws if the port is taken. */
+export function startRelayServer(opts: RelayServerOptions): RelayServer {
+	const log = opts.log ?? (() => {});
+	const group =
+		opts.group === false ? null : opts.group === true || opts.group === undefined ? DEFAULT_GROUP : opts.group;
+	const bridge = new RelayBridge({ log, group });
+	const sockets = new Set<RelayWebSocket>();
+
+	const server = Bun.serve({
+		hostname: "127.0.0.1",
+		port: opts.port,
+		fetch(req, srv): Response | undefined {
+			const url = new URL(req.url);
+			const path = url.pathname.replace(/\/+$/, "") || "/";
+			if (path === "/cdp") {
+				// Browsers set Origin on websocket upgrades; native CDP clients
+				// don't. Reject any Origin so a web page can't drive the relay.
+				if (req.headers.get("origin")) return new Response("Forbidden", { status: 403 });
+				const data: SocketData = { role: "cdp" };
+				if (srv.upgrade(req, { data })) return undefined;
+				return new Response("websocket upgrade required", { status: 426 });
+			}
+			if (path === "/ext") {
+				const origin = req.headers.get("origin");
+				if (origin && !origin.startsWith("chrome-extension://")) {
+					return new Response("Forbidden", { status: 403 });
+				}
+				if (opts.token && url.searchParams.get("token") !== opts.token) {
+					return new Response("Unauthorized", { status: 401 });
+				}
+				const data: SocketData = { role: "ext" };
+				if (srv.upgrade(req, { data })) return undefined;
+				return new Response("websocket upgrade required", { status: 426 });
+			}
+			if (req.method !== "GET") return new Response("Method not allowed", { status: 405 });
+			if (path === "/json/version") {
+				if (!bridge.ready) {
+					return Response.json({ error: "relay extension is not connected" }, { status: 503 });
+				}
+				return Response.json(bridge.versionInfo(`ws://127.0.0.1:${opts.port}/cdp`));
+			}
+			if (path === "/json" || path === "/json/list") {
+				return Response.json(bridge.listTargets());
+			}
+			return new Response("Not found", { status: 404 });
+		},
+		websocket: {
+			maxPayloadLength: MAX_PAYLOAD_BYTES,
+			// Disabled: Bun caps idleTimeout at 255s, and the keepalive pings
+			// below already detect dead peers via the websocket close path.
+			idleTimeout: 0,
+			open(ws: RelayWebSocket): void {
+				sockets.add(ws);
+				if (ws.data.role === "ext") {
+					bridge.extConnected(ws);
+				} else {
+					ws.data.connId = bridge.cdpConnected(ws);
+				}
+			},
+			message(ws: RelayWebSocket, message: string | Buffer): void {
+				const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+				if (ws.data.role === "ext") {
+					bridge.extMessage(ws, text);
+				} else if (ws.data.connId !== undefined) {
+					bridge.cdpMessage(ws.data.connId, text);
+				}
+			},
+			close(ws: RelayWebSocket): void {
+				sockets.delete(ws);
+				if (ws.data.role === "ext") {
+					bridge.extClosed(ws);
+				} else if (ws.data.connId !== undefined) {
+					bridge.cdpClosed(ws.data.connId);
+				}
+			},
+		},
+	});
+
+	// Puppeteer connections go silent while the agent is idle; protocol-level
+	// pings count as activity and keep them under the idle timeout.
+	const keepalive = setInterval(() => {
+		for (const ws of sockets) ws.ping();
+	}, WS_KEEPALIVE_MS);
+	keepalive.unref();
+
+	log("relay listening", { port: opts.port });
+	return {
+		bridge,
+		port: opts.port,
+		stop() {
+			clearInterval(keepalive);
+			server.stop(true);
+		},
+	};
+}