@narumitw/pi-chrome-devtools 0.52.3 → 0.53.0

package/src/browser-settings-menu.ts

@@ -1,8 +1,19 @@
 import { isAbsolute } from "node:path";
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 import { shutdownManagedBrowser } from "./browser-manager.js";
-import { applyRuntimeBrowserSettings, state } from "./runtime.js";
+import {
+	applyAvailableChromeDevtoolsTools,
+	configuredChromeDevtoolsTools,
+	setChromeDevtoolsSessionOwner,
+} from "./lazy-tools.js";
+import {
+	applyRuntimeBrowserSettings,
+	applyRuntimeWebMcpSetting,
+	invalidateWebMcpOperations,
+	state,
+	webMcpEnabled,
+} from "./runtime.js";
 import {
 	type BrowserSettingsPatch,
 	type BrowserSettingsSource,
@@ -10,6 +21,7 @@ import {
 	parseBrowserEndpoint,
 	type SettingsLoadResult,
 	saveBrowserSettings,
+	saveWebMcpSettings,
 } from "./settings.js";
 import { sanitizeChromeDevtoolsDisplay } from "./tool-selector.js";
 
@@ -18,6 +30,7 @@ type BrowserSettingsAction =
 	| "open-endpoint"
 	| "save-endpoint"
 	| "set-auto-launch"
+	| "set-webmcp"
 	| "open-executable"
 	| "save-executable"
 	| "show-extensions";
@@ -29,9 +42,11 @@ interface BrowserSettingsMenuState {
 type CommandContext = ExtensionCommandContext;
 
 export async function showChromeDevtoolsBrowserSettings(
+	pi: ExtensionAPI,
 	ctx: CommandContext,
 	generation: number,
 ): Promise<{ closeParent: boolean }> {
+	setChromeDevtoolsSessionOwner(pi, ctx.sessionManager);
 	const ownerSignal = state.sessionController.signal;
 	const isCurrent = () => generation === state.sessionGeneration && !ownerSignal.aborted;
 	const projectTrusted = ctx.isProjectTrusted();
@@ -71,6 +86,15 @@ export async function showChromeDevtoolsBrowserSettings(
 							currentValue: sanitizeChromeDevtoolsDisplay(browser.executablePath ?? "Automatic"),
 							action: "open-executable",
 						},
+						{
+							id: "webmcp",
+							label: "WebMCP · Experimental",
+							description:
+								"Allow user-confirmed calls to page-provided WebMCP tools in this browser session.",
+							currentValue: current.load.effectiveWebMcpEnabled ? "On" : "Off",
+							values: ["On", "Off"],
+							action: "set-webmcp",
+						},
 						{
 							id: "extensions",
 							label: "Unpacked extensions",
@@ -163,6 +187,26 @@ export async function showChromeDevtoolsBrowserSettings(
 				);
 				return { kind: "stay" };
 			},
+			"set-webmcp": async ({ value, signal }) => {
+				if (value !== "On" && value !== "Off") return { kind: "rejected" };
+				const saved = await saveAndApplyWebMcpSetting(
+					pi,
+					ctx,
+					generation,
+					ownerSignal,
+					signal,
+					projectTrusted,
+					value === "On",
+				);
+				if (!saved) return { kind: "rejected" };
+				ctx.ui.notify(
+					saved.effectiveWebMcpEnabled
+						? "Experimental WebMCP enabled. Every page-provided tool call requires confirmation. Choose gateway availability under Browser tools."
+						: "Experimental WebMCP disabled. Active WebMCP work was aborted and both gateway tools are unavailable.",
+					"warning",
+				);
+				return { kind: "stay" };
+			},
 			"open-executable": () => ({ kind: "to", screen: "executable" }),
 			"save-executable": async ({ value, signal }) => {
 				if (value === undefined) return { kind: "rejected" };
@@ -226,7 +270,8 @@ async function saveAndApplyBrowserPatch(
 		if (!isCurrent(generation, ownerSignal, actionSignal)) return false;
 		await saveBrowserSettings(patch);
 		if (!isCurrent(generation, ownerSignal, actionSignal)) return false;
-		await shutdownManagedBrowser();
+		invalidateWebMcpOperations(ctx.sessionManager, "Chrome DevTools browser configuration changed");
+		await shutdownManagedBrowser(undefined, { owner: ctx.sessionManager });
 		if (!isCurrent(generation, ownerSignal, actionSignal)) return false;
 		const loaded = await loadSettings({ cwd: ctx.cwd, projectTrusted });
 		if (!isCurrent(generation, ownerSignal, actionSignal)) return false;
@@ -239,8 +284,57 @@ async function saveAndApplyBrowserPatch(
 	}
 }
 
+async function saveAndApplyWebMcpSetting(
+	pi: ExtensionAPI,
+	ctx: CommandContext,
+	generation: number,
+	ownerSignal: AbortSignal,
+	actionSignal: AbortSignal,
+	projectTrusted: boolean,
+	enabled: boolean,
+) {
+	const previousEnabled = webMcpEnabled(ctx.sessionManager);
+	const previousTools = configuredChromeDevtoolsTools(pi);
+	try {
+		await ctx.waitForIdle();
+		if (!isCurrent(generation, ownerSignal, actionSignal)) return false;
+		applyRuntimeWebMcpSetting(enabled, ctx.sessionManager);
+		applyAvailableChromeDevtoolsTools(pi, previousTools);
+		await saveWebMcpSettings(enabled);
+		if (!isOwnerCurrent(generation, ownerSignal)) return false;
+		const loaded = await loadSettings({ cwd: ctx.cwd, projectTrusted });
+		if (!isOwnerCurrent(generation, ownerSignal)) return false;
+		state.settingsNotice = loaded.notice;
+		return loaded;
+	} catch (error) {
+		if (!isOwnerCurrent(generation, ownerSignal)) return false;
+		let rollbackError: unknown;
+		try {
+			applyRuntimeWebMcpSetting(previousEnabled, ctx.sessionManager);
+			applyAvailableChromeDevtoolsTools(pi, previousTools);
+		} catch (caught) {
+			rollbackError = caught;
+		}
+		if (isCurrent(generation, ownerSignal, actionSignal)) {
+			notifySaveFailure(
+				ctx,
+				rollbackError
+					? new Error(
+							`${formatError(error)}; WebMCP rollback failed: ${formatError(rollbackError)}`,
+						)
+					: error,
+			);
+		}
+		return false;
+	}
+}
+
+function isOwnerCurrent(generation: number, ownerSignal: AbortSignal) {
+	return generation === state.sessionGeneration && !ownerSignal.aborted;
+}
+
 function isCurrent(generation: number, ownerSignal: AbortSignal, actionSignal: AbortSignal) {
-	return generation === state.sessionGeneration && !ownerSignal.aborted && !actionSignal.aborted;
+	return isOwnerCurrent(generation, ownerSignal) && !actionSignal.aborted;
 }
 
 function invalidSettingsScreen(load: SettingsLoadResult) {

package/src/cdp-client.ts

@@ -14,34 +14,81 @@ import {
 } from "./runtime.js";
 
 interface CdpResponse<T = unknown> {
+	error?: { code: number; data?: unknown; message: string };
 	id: number;
 	result?: T;
-	error?: { code: number; message: string; data?: unknown };
 }
 
-export async function listPages(options: { waitMs?: number } = {}) {
+interface CdpEvent {
+	method: string;
+	params?: unknown;
+}
+
+interface PendingRequest {
+	cleanup: () => void;
+	reject: (reason: unknown) => void;
+	resolve: (value: unknown) => void;
+}
+
+interface EventWaiter<T = unknown> {
+	cleanup: () => void;
+	method: string;
+	predicate: (params: unknown) => params is T;
+	reject: (reason: unknown) => void;
+	resolve: (params: T) => void;
+}
+
+export type CdpWebSocketConstructor = new (url: string | URL) => WebSocket;
+
+export interface CdpOperationOptions {
+	signal?: AbortSignal;
+	timeoutMs?: number;
+}
+
+export interface CdpConnectOptions extends CdpOperationOptions {
+	webSocketConstructor?: CdpWebSocketConstructor;
+}
+
+const MAX_BUFFERED_EVENTS_PER_METHOD = 32;
+const MAX_CDP_MESSAGE_BYTES = 8 * 1024 * 1024;
+
+interface PageOperationOptions {
+	sessionOwner?: object;
+	signal?: AbortSignal;
+	waitMs?: number;
+}
+
+export async function listPages(options: PageOperationOptions = {}) {
 	const waitMs = options.waitMs ?? DEFAULT_ENDPOINT_WAIT_MS;
-	await ensureDevToolsEndpoint(waitMs);
-	return withEndpointRetry(async () => {
-		const pages = await fetchDevToolsJson<DevToolsPage[]>("/json/list");
-		return pages.filter((page) => page.type === "page" && page.webSocketDebuggerUrl);
-	}, waitMs);
+	await ensureDevToolsEndpoint(waitMs, options.signal, options.sessionOwner);
+	return withEndpointRetry(
+		async () => {
+			const pages = await fetchDevToolsJson<DevToolsPage[]>(
+				"/json/list",
+				{ signal: options.signal },
+				options.sessionOwner,
+			);
+			return pages.filter((page) => page.type === "page" && page.webSocketDebuggerUrl);
+		},
+		waitMs,
+		options.signal,
+	);
 }
 
-export async function getPage(pageId: string) {
-	const pages = await listPages();
+export async function getPage(pageId: string, options: PageOperationOptions = {}) {
+	const pages = await listPages(options);
 	return requirePage(pageId, pages);
 }
 
-export async function resolvePage(pageId?: string) {
-	const pages = await listPages();
+export async function resolvePage(pageId?: string, options: PageOperationOptions = {}) {
+	const pages = await listPages(options);
 	if (pageId) return requirePage(pageId, pages);
 
 	const page = resolveDefaultPage(pages);
 	if (!page) {
 		throw new Error(
 			[
-				`No Chrome pages found at ${devToolsEndpoint()}.`,
+				`No Chrome pages found at ${devToolsEndpoint(options.sessionOwner)}.`,
 				"Use chrome_devtools_navigate with a URL to create a page, or open a Chrome tab manually.",
 				launchHint(),
 			].join("\n"),
@@ -51,14 +98,17 @@ export async function resolvePage(pageId?: string) {
 	return page;
 }
 
-export async function resolvePageForNavigation(pageId?: string) {
-	const pages = await listPages();
+export async function resolvePageForNavigation(
+	pageId?: string,
+	options: PageOperationOptions = {},
+) {
+	const pages = await listPages(options);
 	if (pageId) return { created: false, page: requirePage(pageId, pages) };
 
 	const page = resolveDefaultPage(pages);
 	if (page) return { created: false, page };
 
-	return { created: true, page: await createPage("about:blank") };
+	return { created: true, page: await createPage("about:blank", options) };
 }
 
 function resolveDefaultPage(pages: DevToolsPage[]) {
@@ -86,15 +136,18 @@ function requirePage(pageId: string, pages: DevToolsPage[]) {
 	);
 }
 
-export async function createPage(url: string, options: { waitMs?: number } = {}) {
+export async function createPage(url: string, options: PageOperationOptions = {}) {
 	const waitMs = options.waitMs ?? DEFAULT_ENDPOINT_WAIT_MS;
-	await ensureDevToolsEndpoint(waitMs);
+	await ensureDevToolsEndpoint(waitMs, options.signal, options.sessionOwner);
 	const page = await withEndpointRetry(
 		() =>
-			fetchDevToolsJson<DevToolsPage>(`/json/new?${encodeURIComponent(url)}`, {
-				method: "PUT",
-			}),
+			fetchDevToolsJson<DevToolsPage>(
+				`/json/new?${encodeURIComponent(url)}`,
+				{ method: "PUT", signal: options.signal },
+				options.sessionOwner,
+			),
 		waitMs,
+		options.signal,
 	);
 	if (page.type !== "page" || !page.webSocketDebuggerUrl) {
 		throw new Error("Chrome DevTools created a target that is not an inspectable page.");
@@ -112,17 +165,21 @@ export function formatPage(page: DevToolsPage) {
 	};
 }
 
-export function textResult(text: string, details: unknown) {
+export function textResult<T>(text: string, details: T) {
 	return {
 		content: [{ type: "text" as const, text }],
 		details,
 	};
 }
 
-export async function withCdp<T>(page: DevToolsPage, callback: (client: CdpClient) => Promise<T>) {
+export async function withCdp<T>(
+	page: DevToolsPage,
+	callback: (client: CdpClient) => Promise<T>,
+	options: CdpConnectOptions = {},
+) {
 	if (!page.webSocketDebuggerUrl) throw new Error(`Page has no webSocketDebuggerUrl: ${page.id}`);
 
-	const client = await CdpClient.connect(page.webSocketDebuggerUrl);
+	const client = await CdpClient.connect(page.webSocketDebuggerUrl, options);
 	try {
 		return await callback(client);
 	} finally {
@@ -130,90 +187,279 @@ export async function withCdp<T>(page: DevToolsPage, callback: (client: CdpClien
 	}
 }
 
-class CdpClient {
+export class CdpClient {
+	#closed = false;
+	#eventBuffers = new Map<string, unknown[]>();
+	#eventWaiters = new Set<EventWaiter>();
 	#nextId = 1;
-	#pending = new Map<
-		number,
-		{
-			resolve: (value: unknown) => void;
-			reject: (reason: unknown) => void;
-			timeout: NodeJS.Timeout;
-		}
-	>();
-	private readonly socket: WebSocket;
+	#pending = new Map<number, PendingRequest>();
+	readonly #socket: WebSocket;
 
 	private constructor(socket: WebSocket) {
-		this.socket = socket;
-		socket.addEventListener("message", (event) => {
-			const response = JSON.parse(String(event.data)) as CdpResponse;
-			if (typeof response.id !== "number") return;
-
-			const pending = this.#pending.get(response.id);
-			if (!pending) return;
-
-			clearTimeout(pending.timeout);
-			this.#pending.delete(response.id);
-
-			if (response.error) {
-				pending.reject(new Error(`CDP error ${response.error.code}: ${response.error.message}`));
-			} else {
-				pending.resolve(response.result);
-			}
-		});
-
-		socket.addEventListener("close", () => {
-			this.rejectAll(new Error("Chrome DevTools WebSocket closed"));
-		});
-
-		socket.addEventListener("error", () => {
-			this.rejectAll(new Error("Chrome DevTools WebSocket error"));
-		});
+		this.#socket = socket;
+		socket.addEventListener("message", this.onMessage);
+		socket.addEventListener("close", this.onClose);
+		socket.addEventListener("error", this.onError);
 	}
 
-	static connect(url: string) {
+	static connect(url: string, options: CdpConnectOptions = {}) {
+		const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		const WebSocketImplementation = options.webSocketConstructor ?? WebSocket;
+		options.signal?.throwIfAborted();
 		return new Promise<CdpClient>((resolve, reject) => {
-			const socket = new WebSocket(url);
-			const timeout = setTimeout(() => {
-				socket.close();
-				reject(new Error(`Timed out connecting to Chrome DevTools WebSocket: ${url}`));
-			}, DEFAULT_TIMEOUT_MS);
-
-			socket.addEventListener("open", () => {
+			const socket = new WebSocketImplementation(url);
+			let settled = false;
+			const settle = (callback: () => void) => {
+				if (settled) return;
+				settled = true;
 				clearTimeout(timeout);
-				resolve(new CdpClient(socket));
-			});
-
-			socket.addEventListener("error", () => {
-				clearTimeout(timeout);
-				reject(new Error(`Failed to connect to Chrome DevTools WebSocket: ${url}`));
-			});
+				options.signal?.removeEventListener("abort", onAbort);
+				socket.removeEventListener("open", onOpen);
+				socket.removeEventListener("error", onConnectError);
+				callback();
+			};
+			const onOpen = () => settle(() => resolve(new CdpClient(socket)));
+			const onConnectError = () =>
+				settle(() => {
+					socket.close();
+					reject(new Error(`Failed to connect to Chrome DevTools WebSocket: ${url}`));
+				});
+			const onAbort = () =>
+				settle(() => {
+					socket.close();
+					reject(options.signal?.reason ?? abortError("Chrome DevTools connection aborted"));
+				});
+			const timeout = setTimeout(
+				() =>
+					settle(() => {
+						socket.close();
+						reject(new Error(`Timed out connecting to Chrome DevTools WebSocket: ${url}`));
+					}),
+				timeoutMs,
+			);
+			options.signal?.addEventListener("abort", onAbort, { once: true });
+			socket.addEventListener("open", onOpen, { once: true });
+			socket.addEventListener("error", onConnectError, { once: true });
 		});
 	}
 
-	send<T = unknown>(method: string, params?: Record<string, unknown>) {
+	send<T = unknown>(
+		method: string,
+		params: Record<string, unknown> = {},
+		options: CdpOperationOptions = {},
+	) {
+		this.throwIfClosed();
+		options.signal?.throwIfAborted();
 		const id = this.#nextId;
 		this.#nextId += 1;
-
 		return new Promise<T>((resolve, reject) => {
+			const onAbort = () => {
+				this.#pending.delete(id);
+				cleanup();
+				reject(options.signal?.reason ?? abortError(`CDP command aborted: ${method}`));
+			};
 			const timeout = setTimeout(() => {
 				this.#pending.delete(id);
+				options.signal?.removeEventListener("abort", onAbort);
 				reject(new Error(`Timed out waiting for CDP response: ${method}`));
-			}, DEFAULT_TIMEOUT_MS);
+			}, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+			const cleanup = () => {
+				clearTimeout(timeout);
+				options.signal?.removeEventListener("abort", onAbort);
+			};
+			this.#pending.set(id, {
+				cleanup,
+				reject,
+				resolve: resolve as (value: unknown) => void,
+			});
+			options.signal?.addEventListener("abort", onAbort, { once: true });
+			try {
+				this.#socket.send(JSON.stringify({ id, method, params }));
+			} catch (error) {
+				this.#pending.delete(id);
+				cleanup();
+				reject(error);
+			}
+		});
+	}
+
+	waitForEvent<T>(
+		method: string,
+		predicate: (params: unknown) => params is T,
+		options: CdpOperationOptions = {},
+	): Promise<T> {
+		this.throwIfClosed();
+		options.signal?.throwIfAborted();
+		const buffered = this.#eventBuffers.get(method) ?? [];
+		for (const [index, params] of buffered.entries()) {
+			if (!predicate(params)) continue;
+			buffered.splice(index, 1);
+			if (buffered.length === 0) this.#eventBuffers.delete(method);
+			return Promise.resolve(params);
+		}
 
-			this.#pending.set(id, { resolve: resolve as (value: unknown) => void, reject, timeout });
-			this.socket.send(JSON.stringify({ id, method, params: params ?? {} }));
+		return new Promise<T>((resolve, reject) => {
+			const waiter = {} as EventWaiter<T>;
+			const onAbort = () => {
+				this.#eventWaiters.delete(waiter as EventWaiter);
+				cleanup();
+				reject(options.signal?.reason ?? abortError(`CDP event wait aborted: ${method}`));
+			};
+			const timeout = setTimeout(() => {
+				this.#eventWaiters.delete(waiter as EventWaiter);
+				options.signal?.removeEventListener("abort", onAbort);
+				reject(new Error(`Timed out waiting for CDP event: ${method}`));
+			}, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+			const cleanup = () => {
+				clearTimeout(timeout);
+				options.signal?.removeEventListener("abort", onAbort);
+			};
+			Object.assign(waiter, { cleanup, method, predicate, reject, resolve });
+			this.#eventWaiters.add(waiter as EventWaiter);
+			options.signal?.addEventListener("abort", onAbort, { once: true });
 		});
 	}
 
-	close() {
-		this.socket.close();
+	close(reason: unknown = new Error("Chrome DevTools WebSocket closed")) {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#socket.removeEventListener("message", this.onMessage);
+		this.#socket.removeEventListener("close", this.onClose);
+		this.#socket.removeEventListener("error", this.onError);
+		this.rejectAll(reason);
+		this.#eventBuffers.clear();
+		try {
+			this.#socket.close();
+		} catch {
+			// The transport is already unusable; pending work has still been rejected.
+		}
 	}
 
-	private rejectAll(error: Error) {
+	private readonly onClose = () => {
+		this.close(new Error("Chrome DevTools WebSocket closed"));
+	};
+
+	private readonly onError = () => {
+		this.close(new Error("Chrome DevTools WebSocket error"));
+	};
+
+	private readonly onMessage = (event: MessageEvent) => {
+		if (typeof event.data !== "string") {
+			this.close(new Error("Chrome DevTools WebSocket sent an unsupported binary message"));
+			return;
+		}
+		if (
+			event.data.length > MAX_CDP_MESSAGE_BYTES ||
+			Buffer.byteLength(event.data, "utf8") > MAX_CDP_MESSAGE_BYTES
+		) {
+			this.close(new Error("Chrome DevTools WebSocket message exceeds the 8 MB limit"));
+			return;
+		}
+		let payload: unknown;
+		try {
+			payload = JSON.parse(event.data) as unknown;
+		} catch {
+			this.close(new Error("Chrome DevTools WebSocket sent malformed JSON"));
+			return;
+		}
+		if (!isRecord(payload)) {
+			this.close(new Error("Chrome DevTools WebSocket sent a malformed message"));
+			return;
+		}
+		if (typeof payload.id === "number") {
+			this.handleResponse(payload as unknown as CdpResponse);
+			return;
+		}
+		if (typeof payload.method !== "string") {
+			this.close(new Error("Chrome DevTools WebSocket sent a malformed event"));
+			return;
+		}
+		this.handleEvent(payload as unknown as CdpEvent);
+	};
+
+	private handleResponse(response: CdpResponse) {
+		const pending = this.#pending.get(response.id);
+		if (!pending) return;
+		this.#pending.delete(response.id);
+		pending.cleanup();
+		if (response.error) {
+			pending.reject(
+				new Error(
+					`CDP error ${response.error.code}: ${response.error.message}${
+						response.error.data === undefined ? "" : ` (${safeJson(response.error.data)})`
+					}`,
+				),
+			);
+			return;
+		}
+		pending.resolve(response.result);
+	}
+
+	private handleEvent(event: CdpEvent) {
+		if (event.method === "Inspector.detached" || event.method === "Target.detachedFromTarget") {
+			this.close(new Error(`Chrome DevTools target detached: ${safeJson(event.params)}`));
+			return;
+		}
+		for (const waiter of this.#eventWaiters) {
+			if (waiter.method !== event.method) continue;
+			let matched: boolean;
+			try {
+				matched = waiter.predicate(event.params);
+			} catch (error) {
+				this.#eventWaiters.delete(waiter);
+				waiter.cleanup();
+				waiter.reject(error);
+				return;
+			}
+			if (!matched) continue;
+			this.#eventWaiters.delete(waiter);
+			waiter.cleanup();
+			waiter.resolve(event.params);
+			return;
+		}
+		const buffer = this.#eventBuffers.get(event.method) ?? [];
+		buffer.push(event.params);
+		if (buffer.length > MAX_BUFFERED_EVENTS_PER_METHOD) {
+			this.close(
+				new Error(
+					`Chrome DevTools WebSocket buffered more than ${MAX_BUFFERED_EVENTS_PER_METHOD} ${event.method} events`,
+				),
+			);
+			return;
+		}
+		this.#eventBuffers.set(event.method, buffer);
+	}
+
+	private rejectAll(reason: unknown) {
 		for (const [id, pending] of this.#pending) {
-			clearTimeout(pending.timeout);
-			pending.reject(error);
 			this.#pending.delete(id);
+			pending.cleanup();
+			pending.reject(reason);
 		}
+		for (const waiter of this.#eventWaiters) {
+			this.#eventWaiters.delete(waiter);
+			waiter.cleanup();
+			waiter.reject(reason);
+		}
+	}
+
+	private throwIfClosed() {
+		if (this.#closed) throw new Error("Chrome DevTools WebSocket is closed");
+	}
+}
+
+function abortError(message: string) {
+	return new DOMException(message, "AbortError");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function safeJson(value: unknown) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
 	}
 }