@narumitw/pi-chrome-devtools 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# pi-chrome-devtools
+
+A public [pi](https://pi.dev) extension package that exposes Chrome DevTools Protocol (CDP) tools to the agent.
+
+It is inspired by [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp), but implemented as native pi tools instead of an MCP server.
+
+## Install
+
+```bash
+pi install npm:@narumitw/pi-chrome-devtools
+```
+
+Try without installing:
+
+```bash
+pi -e npm:@narumitw/pi-chrome-devtools
+```
+
+Try this package locally from the repository root:
+
+```bash
+pi -e ./extensions/pi-chrome-devtools
+```
+
+## Start Chrome with CDP enabled
+
+The extension connects to `127.0.0.1:9222` by default.
+
+```bash
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/pi-chrome-devtools
+```
+
+On macOS:
+
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/pi-chrome-devtools
+```
+
+Override the endpoint if needed:
+
+```bash
+PI_CHROME_DEVTOOLS_HOST=127.0.0.1 PI_CHROME_DEVTOOLS_PORT=9223 pi -e ./extensions/pi-chrome-devtools
+```
+
+## Tools
+
+- `chrome_devtools_list_pages` — list inspectable Chrome tabs/pages.
+- `chrome_devtools_select_page` — select the active page for later tool calls.
+- `chrome_devtools_navigate` — navigate a page to a URL.
+- `chrome_devtools_evaluate` — evaluate JavaScript in the selected page.
+- `chrome_devtools_screenshot` — capture a PNG screenshot.
+
+## Command
+
+```text
+/chrome-devtools
+```
+
+Shows the configured CDP endpoint and quick start hint.
+
+## Package layout
+
+```txt
+extensions/pi-chrome-devtools/
+├── src/
+│   └── chrome-devtools.ts
+├── README.md
+├── LICENSE
+├── tsconfig.json
+└── package.json
+```
+
+The package exposes its extension through `package.json`:
+
+```json
+{
+  "pi": {
+    "extensions": ["./src/chrome-devtools.ts"]
+  }
+}
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "@narumitw/pi-chrome-devtools",
+	"version": "0.1.3",
+	"description": "Pi extension that exposes Chrome DevTools Protocol tools.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"chrome",
+		"devtools",
+		"cdp"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/chrome-devtools.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check . && npm run typecheck",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"typebox": "^1.1.37"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.14",
+		"@mariozechner/pi-coding-agent": "0.73.0",
+		"typescript": "6.0.3"
+	}
+}

package/src/chrome-devtools.ts

@@ -0,0 +1,337 @@
+import { defineTool, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 9222;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+interface DevToolsPage {
+	id: string;
+	type: string;
+	title: string;
+	url: string;
+	webSocketDebuggerUrl?: string;
+}
+
+interface ChromeDevToolsState {
+	host: string;
+	port: number;
+	activePageId?: string;
+}
+
+interface CdpResponse<T = unknown> {
+	id: number;
+	result?: T;
+	error?: {
+		code: number;
+		message: string;
+		data?: unknown;
+	};
+}
+
+const state: ChromeDevToolsState = {
+	host: process.env.PI_CHROME_DEVTOOLS_HOST ?? DEFAULT_HOST,
+	port: Number(process.env.PI_CHROME_DEVTOOLS_PORT ?? DEFAULT_PORT),
+};
+
+const listPagesTool = defineTool({
+	name: "chrome_devtools_list_pages",
+	label: "Chrome DevTools: List Pages",
+	description: "List Chrome tabs/pages from a running Chrome DevTools Protocol endpoint.",
+	promptSnippet: "List Chrome tabs/pages available over Chrome DevTools Protocol",
+	parameters: Type.Object({}),
+	async execute() {
+		const pages = await listPages();
+		return textResult(JSON.stringify(pages.map(formatPage), null, 2), { pages });
+	},
+});
+
+const selectPageTool = defineTool({
+	name: "chrome_devtools_select_page",
+	label: "Chrome DevTools: Select Page",
+	description: "Select the active Chrome page for later chrome_devtools_* tool calls.",
+	promptSnippet: "Select the Chrome tab/page to inspect or control",
+	parameters: Type.Object({
+		pageId: Type.String({ description: "Page id from chrome_devtools_list_pages." }),
+	}),
+	async execute(_toolCallId, params) {
+		const page = await getPage(params.pageId);
+		state.activePageId = page.id;
+		return textResult(`Selected page ${page.id}: ${page.title}\n${page.url}`, {
+			page: formatPage(page),
+		});
+	},
+});
+
+const navigateTool = defineTool({
+	name: "chrome_devtools_navigate",
+	label: "Chrome DevTools: Navigate",
+	description: "Navigate a Chrome page to a URL through Chrome DevTools Protocol.",
+	promptSnippet: "Navigate the selected Chrome tab to a URL",
+	parameters: Type.Object({
+		url: Type.String({ description: "URL to navigate to." }),
+		pageId: Type.Optional(
+			Type.String({ description: "Optional page id. Defaults to selected or first page." }),
+		),
+	}),
+	async execute(_toolCallId, params) {
+		const page = await resolvePage(params.pageId);
+		const result = await withCdp(page, async (client) => {
+			await client.send("Page.enable");
+			return client.send("Page.navigate", { url: params.url });
+		});
+
+		state.activePageId = page.id;
+		return textResult(`Navigated ${page.id} to ${params.url}`, { page: formatPage(page), result });
+	},
+});
+
+const evaluateTool = defineTool({
+	name: "chrome_devtools_evaluate",
+	label: "Chrome DevTools: Evaluate",
+	description: "Evaluate JavaScript in a Chrome page through Chrome DevTools Protocol.",
+	promptSnippet: "Evaluate JavaScript in the selected Chrome tab",
+	parameters: Type.Object({
+		expression: Type.String({ description: "JavaScript expression to evaluate." }),
+		pageId: Type.Optional(
+			Type.String({ description: "Optional page id. Defaults to selected or first page." }),
+		),
+		awaitPromise: Type.Optional(
+			Type.Boolean({ description: "Whether to await a returned Promise. Defaults to true." }),
+		),
+	}),
+	async execute(_toolCallId, params) {
+		const page = await resolvePage(params.pageId);
+		const result = await withCdp(page, (client) =>
+			client.send("Runtime.evaluate", {
+				expression: params.expression,
+				awaitPromise: params.awaitPromise ?? true,
+				returnByValue: true,
+			}),
+		);
+
+		state.activePageId = page.id;
+		return textResult(JSON.stringify(result, null, 2), { page: formatPage(page), result });
+	},
+});
+
+const screenshotTool = defineTool({
+	name: "chrome_devtools_screenshot",
+	label: "Chrome DevTools: Screenshot",
+	description: "Capture a PNG screenshot from a Chrome page through Chrome DevTools Protocol.",
+	promptSnippet: "Capture a screenshot from the selected Chrome tab",
+	parameters: Type.Object({
+		pageId: Type.Optional(
+			Type.String({ description: "Optional page id. Defaults to selected or first page." }),
+		),
+		fullPage: Type.Optional(
+			Type.Boolean({ description: "Capture the full document, not just the viewport." }),
+		),
+	}),
+	async execute(_toolCallId, params) {
+		const page = await resolvePage(params.pageId);
+		const result = await withCdp(page, async (client) => {
+			await client.send("Page.enable");
+
+			if (!params.fullPage) {
+				return client.send<{ data: string }>("Page.captureScreenshot", { format: "png" });
+			}
+
+			const metrics = await client.send<{
+				contentSize: { x: number; y: number; width: number; height: number };
+			}>("Page.getLayoutMetrics");
+
+			return client.send<{ data: string }>("Page.captureScreenshot", {
+				captureBeyondViewport: true,
+				format: "png",
+				clip: {
+					x: metrics.contentSize.x,
+					y: metrics.contentSize.y,
+					width: metrics.contentSize.width,
+					height: metrics.contentSize.height,
+					scale: 1,
+				},
+			});
+		});
+
+		state.activePageId = page.id;
+		return {
+			content: [
+				{ type: "text", text: `Captured PNG screenshot from ${page.title || page.url}` },
+				{ type: "image", data: result.data, mimeType: "image/png" },
+			],
+			details: { page: formatPage(page), bytes: Buffer.byteLength(result.data, "base64") },
+		};
+	},
+});
+
+export default function chromeDevtools(pi: ExtensionAPI) {
+	pi.registerTool(listPagesTool);
+	pi.registerTool(selectPageTool);
+	pi.registerTool(navigateTool);
+	pi.registerTool(evaluateTool);
+	pi.registerTool(screenshotTool);
+
+	pi.registerCommand("chrome-devtools", {
+		description: "Show Chrome DevTools endpoint and quick start help",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify(
+				`Chrome DevTools endpoint: http://${state.host}:${state.port}. Start Chrome with --remote-debugging-port=${state.port}.`,
+				"info",
+			);
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		ctx.ui.setStatus("chrome-devtools", `cdp: ${state.host}:${state.port}`);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		ctx.ui.setStatus("chrome-devtools", undefined);
+	});
+}
+
+async function listPages() {
+	const response = await fetch(`http://${state.host}:${state.port}/json/list`);
+	if (!response.ok) {
+		throw new Error(`Chrome DevTools endpoint returned ${response.status} ${response.statusText}`);
+	}
+
+	const pages = (await response.json()) as DevToolsPage[];
+	return pages.filter((page) => page.type === "page" && page.webSocketDebuggerUrl);
+}
+
+async function getPage(pageId: string) {
+	const pages = await listPages();
+	const page = pages.find((candidate) => candidate.id === pageId);
+	if (!page) throw new Error(`Chrome DevTools page not found: ${pageId}`);
+	return page;
+}
+
+async function resolvePage(pageId?: string) {
+	if (pageId) return getPage(pageId);
+	if (state.activePageId) return getPage(state.activePageId);
+
+	const pages = await listPages();
+	const page = pages[0];
+	if (!page) {
+		throw new Error(
+			`No Chrome pages found at http://${state.host}:${state.port}. Start Chrome with --remote-debugging-port=${state.port}.`,
+		);
+	}
+
+	return page;
+}
+
+function formatPage(page: DevToolsPage) {
+	return {
+		id: page.id,
+		type: page.type,
+		title: page.title,
+		url: page.url,
+	};
+}
+
+function textResult(text: string, details: unknown) {
+	return {
+		content: [{ type: "text" as const, text }],
+		details,
+	};
+}
+
+async function withCdp<T>(page: DevToolsPage, callback: (client: CdpClient) => Promise<T>) {
+	if (!page.webSocketDebuggerUrl) throw new Error(`Page has no webSocketDebuggerUrl: ${page.id}`);
+
+	const client = await CdpClient.connect(page.webSocketDebuggerUrl);
+	try {
+		return await callback(client);
+	} finally {
+		client.close();
+	}
+}
+
+class CdpClient {
+	#nextId = 1;
+	#pending = new Map<
+		number,
+		{
+			resolve: (value: unknown) => void;
+			reject: (reason: unknown) => void;
+			timeout: NodeJS.Timeout;
+		}
+	>();
+
+	private constructor(private readonly socket: WebSocket) {
+		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"));
+		});
+	}
+
+	static connect(url: string) {
+		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", () => {
+				clearTimeout(timeout);
+				resolve(new CdpClient(socket));
+			});
+
+			socket.addEventListener("error", () => {
+				clearTimeout(timeout);
+				reject(new Error(`Failed to connect to Chrome DevTools WebSocket: ${url}`));
+			});
+		});
+	}
+
+	send<T = unknown>(method: string, params?: Record<string, unknown>) {
+		const id = this.#nextId;
+		this.#nextId += 1;
+
+		return new Promise<T>((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				this.#pending.delete(id);
+				reject(new Error(`Timed out waiting for CDP response: ${method}`));
+			}, DEFAULT_TIMEOUT_MS);
+
+			this.#pending.set(id, { resolve: resolve as (value: unknown) => void, reject, timeout });
+			this.socket.send(JSON.stringify({ id, method, params: params ?? {} }));
+		});
+	}
+
+	close() {
+		this.socket.close();
+	}
+
+	private rejectAll(error: Error) {
+		for (const [id, pending] of this.#pending) {
+			clearTimeout(pending.timeout);
+			pending.reject(error);
+			this.#pending.delete(id);
+		}
+	}
+}