gsd-pi 2.7.1 → 2.8.0

package/src/resources/extensions/browser-tools/tools/navigation.ts

@@ -0,0 +1,232 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import {
+	diffCompactStates,
+} from "../core.js";
+import type { ToolDeps, CompactPageState } from "../state.js";
+import {
+	setLastActionBeforeState,
+	setLastActionAfterState,
+} from "../state.js";
+
+export function registerNavigationTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	// -------------------------------------------------------------------------
+	// browser_navigate
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_navigate",
+		label: "Browser Navigate",
+		description:
+			"Open the browser (if not already open) and navigate to a URL. Waits for network idle. Returns page title and current URL. Use ONLY for visually verifying locally-running web apps (e.g. http://localhost:3000). Do NOT use for documentation sites, GitHub, search results, or any external URL — use web_search instead. Screenshots are only captured when the `screenshot` parameter is set to true.",
+		parameters: Type.Object({
+			url: Type.String({ description: "URL to navigate to, e.g. http://localhost:3000" }),
+			screenshot: Type.Optional(Type.Boolean({ description: "Capture and return a screenshot (default: false)", default: false })),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			let actionId: number | null = null;
+			let beforeState: CompactPageState | null = null;
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				beforeState = await deps.captureCompactPageState(p, { includeBodyText: true });
+				actionId = deps.beginTrackedAction("browser_navigate", params, beforeState.url).id;
+				await p.goto(params.url, { waitUntil: "domcontentloaded", timeout: 30000 });
+				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+				await new Promise(resolve => setTimeout(resolve, 300));
+
+				const title = await p.title();
+				const url = p.url();
+				const viewport = p.viewportSize();
+				const vpText = viewport ? `${viewport.width}x${viewport.height}` : "unknown";
+				const afterState = await deps.captureCompactPageState(p, { includeBodyText: true });
+				const summary = deps.formatCompactStateSummary(afterState);
+				const jsErrors = deps.getRecentErrors(p.url());
+				const diff = diffCompactStates(beforeState, afterState);
+				setLastActionBeforeState(beforeState);
+				setLastActionAfterState(afterState);
+				deps.finishTrackedAction(actionId, {
+					status: "success",
+					afterUrl: afterState.url,
+					warningSummary: jsErrors.trim() || undefined,
+					diffSummary: diff.summary,
+					changed: diff.changed,
+					beforeState,
+					afterState,
+				});
+
+				let screenshotContent: any[] = [];
+				if (params.screenshot) {
+					try {
+						let buf = await p.screenshot({ type: "jpeg", quality: 80, scale: "css" });
+						buf = await deps.constrainScreenshot(p, buf, "image/jpeg", 80);
+						screenshotContent = [{ type: "image", data: buf.toString("base64"), mimeType: "image/jpeg" }];
+					} catch {}
+				}
+
+				return {
+					content: [
+						{ type: "text", text: `Navigated to: ${url}\nTitle: ${title}\nViewport: ${vpText}\nAction: ${actionId}${jsErrors}\n\nDiff:\n${deps.formatDiffText(diff)}\n\nPage summary:\n${summary}` },
+						...screenshotContent,
+					],
+					details: { title, url, status: "loaded", viewport: vpText, actionId, diff },
+				};
+			} catch (err: any) {
+				if (actionId !== null) {
+					deps.finishTrackedAction(actionId, { status: "error", afterUrl: deps.getActivePageOrNull()?.url() ?? "", error: err.message, beforeState: beforeState ?? undefined });
+				}
+				const errorShot = await deps.captureErrorScreenshot(deps.getActivePageOrNull());
+				const content: any[] = [{ type: "text", text: `Navigation failed: ${err.message}` }];
+				if (errorShot) {
+					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
+				}
+				return {
+					content,
+					details: { status: "error", error: err.message, actionId },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_go_back
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_go_back",
+		label: "Browser Go Back",
+		description: "Navigate back in browser history. Returns a compact page summary after navigation.",
+		parameters: Type.Object({}),
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				const response = await p.goBack({ waitUntil: "domcontentloaded", timeout: 10000 });
+
+				if (!response) {
+					return {
+						content: [{ type: "text", text: "No previous page in history." }],
+						details: {},
+						isError: true,
+					};
+				}
+
+				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+
+				const title = await p.title();
+				const url = p.url();
+				const summary = await deps.postActionSummary(p);
+				const jsErrors = deps.getRecentErrors(p.url());
+
+				return {
+					content: [{ type: "text", text: `Navigated back to: ${url}\nTitle: ${title}${jsErrors}\n\nPage summary:\n${summary}` }],
+					details: { title, url },
+				};
+			} catch (err: any) {
+				const errorShot = await deps.captureErrorScreenshot(deps.getActivePageOrNull());
+				const content: any[] = [{ type: "text", text: `Go back failed: ${err.message}` }];
+				if (errorShot) {
+					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
+				}
+				return { content, details: { error: err.message }, isError: true };
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_go_forward
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_go_forward",
+		label: "Browser Go Forward",
+		description: "Navigate forward in browser history. Returns a compact page summary after navigation.",
+		parameters: Type.Object({}),
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				const response = await p.goForward({ waitUntil: "domcontentloaded", timeout: 10000 });
+
+				if (!response) {
+					return {
+						content: [{ type: "text", text: "No forward page in history." }],
+						details: {},
+						isError: true,
+					};
+				}
+
+				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+
+				const title = await p.title();
+				const url = p.url();
+				const summary = await deps.postActionSummary(p);
+				const jsErrors = deps.getRecentErrors(p.url());
+
+				return {
+					content: [{ type: "text", text: `Navigated forward to: ${url}\nTitle: ${title}${jsErrors}\n\nPage summary:\n${summary}` }],
+					details: { title, url },
+				};
+			} catch (err: any) {
+				const errorShot = await deps.captureErrorScreenshot(deps.getActivePageOrNull());
+				const content: any[] = [{ type: "text", text: `Go forward failed: ${err.message}` }];
+				if (errorShot) {
+					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
+				}
+				return { content, details: { error: err.message }, isError: true };
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_reload
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_reload",
+		label: "Browser Reload",
+		description: "Reload the current page. Returns a screenshot, compact page summary, and page metadata (same shape as browser_navigate).",
+		parameters: Type.Object({}),
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				await p.reload({ waitUntil: "domcontentloaded", timeout: 30000 });
+				await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+
+				const title = await p.title();
+				const url = p.url();
+				const viewport = p.viewportSize();
+				const vpText = viewport ? `${viewport.width}x${viewport.height}` : "unknown";
+				const summary = await deps.postActionSummary(p);
+				const jsErrors = deps.getRecentErrors(p.url());
+
+				let screenshotContent: any[] = [];
+				try {
+					let buf = await p.screenshot({ type: "jpeg", quality: 80, scale: "css" });
+					buf = await deps.constrainScreenshot(p, buf, "image/jpeg", 80);
+					screenshotContent = [{
+						type: "image",
+						data: buf.toString("base64"),
+						mimeType: "image/jpeg",
+					}];
+				} catch {}
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Reloaded: ${url}\nTitle: ${title}\nViewport: ${vpText}${jsErrors}\n\nPage summary:\n${summary}`,
+						},
+						...screenshotContent,
+					],
+					details: { title, url, viewport: vpText },
+				};
+			} catch (err: any) {
+				const errorShot = await deps.captureErrorScreenshot(deps.getActivePageOrNull());
+				const content: any[] = [{ type: "text", text: `Reload failed: ${err.message}` }];
+				if (errorShot) {
+					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
+				}
+				return { content, details: { error: err.message }, isError: true };
+			}
+		},
+	});
+}

package/src/resources/extensions/browser-tools/tools/pages.ts

@@ -0,0 +1,303 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import {
+	registryGetActive,
+	registryListPages,
+	registrySetActive,
+} from "../core.js";
+import type { ToolDeps } from "../state.js";
+import {
+	getPageRegistry,
+	getActiveFrame,
+	setActiveFrame,
+} from "../state.js";
+
+export function registerPageTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	// -------------------------------------------------------------------------
+	// browser_list_pages
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_list_pages",
+		label: "Browser List Pages",
+		description:
+			"List all open browser pages/tabs with their IDs, titles, URLs, and active status. Use to see what pages are available before switching.",
+		parameters: Type.Object({}),
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.ensureBrowser();
+				const pageRegistry = getPageRegistry();
+				for (const entry of pageRegistry.pages) {
+					try {
+						entry.title = await entry.page.title();
+						entry.url = entry.page.url();
+					} catch {
+						// Page may have been closed
+					}
+				}
+				const pages = registryListPages(pageRegistry);
+				if (pages.length === 0) {
+					return {
+						content: [{ type: "text", text: "No pages open." }],
+						details: { pages: [], count: 0 },
+					};
+				}
+				const lines = pages.map((p: any) => {
+					const active = p.isActive ? " ← active" : "";
+					const opener = p.opener !== null ? ` (opener: ${p.opener})` : "";
+					return `  [${p.id}] ${p.title || "(untitled)"} — ${p.url}${opener}${active}`;
+				});
+				return {
+					content: [{ type: "text", text: `${pages.length} page(s):\n${lines.join("\n")}` }],
+					details: { pages, count: pages.length },
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `List pages failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_switch_page
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_switch_page",
+		label: "Browser Switch Page",
+		description:
+			"Switch the active browser page/tab by page ID. Use browser_list_pages to see available IDs. Clears any active frame selection.",
+		parameters: Type.Object({
+			id: Type.Number({ description: "Page ID to switch to (from browser_list_pages)" }),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.ensureBrowser();
+				const pageRegistry = getPageRegistry();
+				registrySetActive(pageRegistry, params.id);
+				setActiveFrame(null);
+				const entry = registryGetActive(pageRegistry);
+				await entry.page.bringToFront();
+				const title = await entry.page.title().catch(() => "");
+				const url = entry.page.url();
+				entry.title = title;
+				entry.url = url;
+				return {
+					content: [{ type: "text", text: `Switched to page ${params.id}: ${title || "(untitled)"} — ${url}` }],
+					details: { id: params.id, title, url },
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Switch page failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_close_page
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_close_page",
+		label: "Browser Close Page",
+		description:
+			"Close a specific browser page/tab by ID. Cannot close the last remaining page. The page's close event triggers automatic registry cleanup and active-page fallback.",
+		parameters: Type.Object({
+			id: Type.Number({ description: "Page ID to close (from browser_list_pages)" }),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.ensureBrowser();
+				const pageRegistry = getPageRegistry();
+				if (pageRegistry.pages.length <= 1) {
+					return {
+						content: [{ type: "text", text: `Cannot close the last remaining page. Use browser_close to close the entire browser.` }],
+						details: { error: "last_page", pageCount: pageRegistry.pages.length },
+						isError: true,
+					};
+				}
+				const entry = pageRegistry.pages.find((e: any) => e.id === params.id);
+				if (!entry) {
+					const available = pageRegistry.pages.map((e: any) => e.id);
+					return {
+						content: [{ type: "text", text: `Page ${params.id} not found. Available page IDs: [${available.join(", ")}].` }],
+						details: { error: "not_found", available },
+						isError: true,
+					};
+				}
+				await entry.page.close();
+				setActiveFrame(null);
+				for (const remaining of pageRegistry.pages) {
+					try {
+						remaining.title = await remaining.page.title();
+						remaining.url = remaining.page.url();
+					} catch {}
+				}
+				const pages = registryListPages(pageRegistry);
+				const lines = pages.map((p: any) => {
+					const active = p.isActive ? " ← active" : "";
+					return `  [${p.id}] ${p.title || "(untitled)"} — ${p.url}${active}`;
+				});
+				return {
+					content: [{ type: "text", text: `Closed page ${params.id}. ${pages.length} page(s) remaining:\n${lines.join("\n")}` }],
+					details: { closedId: params.id, pages, count: pages.length },
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Close page failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_list_frames
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_list_frames",
+		label: "Browser List Frames",
+		description:
+			"List all frames in the active page, including the main frame and any iframes. Shows frame name, URL, and parent frame name. Use before browser_select_frame to identify available frames.",
+		parameters: Type.Object({}),
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.ensureBrowser();
+				const p = deps.getActivePage();
+				const frames = p.frames();
+				const mainFrame = p.mainFrame();
+				const activeFrame = getActiveFrame();
+				const frameList = frames.map((f, index) => {
+					const isMain = f === mainFrame;
+					const parentName = f.parentFrame()?.name() || (f.parentFrame() === mainFrame ? "main" : "");
+					return {
+						index,
+						name: f.name() || (isMain ? "main" : `(unnamed-${index})`),
+						url: f.url(),
+						isMain,
+						parentName: isMain ? null : (parentName || "main"),
+						isActive: f === activeFrame,
+					};
+				});
+				const lines = frameList.map((f) => {
+					const main = f.isMain ? " [main]" : "";
+					const active = f.isActive ? " ← selected" : "";
+					const parent = f.parentName ? ` (parent: ${f.parentName})` : "";
+					return `  [${f.index}] "${f.name}" — ${f.url}${main}${parent}${active}`;
+				});
+				const activeInfo = activeFrame ? `Active frame: "${activeFrame.name() || "(unnamed)"}"` : "No frame selected (operating on main page)";
+				return {
+					content: [{ type: "text", text: `${frameList.length} frame(s) in active page:\n${lines.join("\n")}\n\n${activeInfo}` }],
+					details: { frames: frameList, count: frameList.length, activeFrame: activeFrame?.name() ?? null },
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `List frames failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_select_frame
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_select_frame",
+		label: "Browser Select Frame",
+		description:
+			"Select a frame within the active page to operate on. Find frames by name, URL pattern, or index. Pass null or \"main\" to reset back to the main page frame. Once a frame is selected, tools like browser_evaluate, browser_find, and browser_click will operate within that frame (after T03 migration).",
+		parameters: Type.Object({
+			name: Type.Optional(Type.String({ description: "Frame name to select. Use 'main' or 'null' to reset to main frame." })),
+			urlPattern: Type.Optional(Type.String({ description: "URL substring to match against frame URLs." })),
+			index: Type.Optional(Type.Number({ description: "Frame index from browser_list_frames." })),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.ensureBrowser();
+				const p = deps.getActivePage();
+				const frames = p.frames();
+
+				if (params.name === "main" || params.name === "null" || params.name === null) {
+					setActiveFrame(null);
+					return {
+						content: [{ type: "text", text: "Reset to main page frame. Tools will operate on the main page." }],
+						details: { activeFrame: null },
+					};
+				}
+
+				if (params.name) {
+					const frame = frames.find((f) => f.name() === params.name);
+					if (!frame) {
+						const available = frames.map((f, i) => `[${i}] "${f.name() || "(unnamed)"}" — ${f.url()}`);
+						return {
+							content: [{ type: "text", text: `Frame with name "${params.name}" not found.\nAvailable frames:\n  ${available.join("\n  ")}` }],
+							details: { error: "frame_not_found", available },
+							isError: true,
+						};
+					}
+					setActiveFrame(frame);
+					return {
+						content: [{ type: "text", text: `Selected frame "${frame.name()}" — ${frame.url()}` }],
+						details: { name: frame.name(), url: frame.url() },
+					};
+				}
+
+				if (params.urlPattern) {
+					const frame = frames.find((f) => f.url().includes(params.urlPattern!));
+					if (!frame) {
+						const available = frames.map((f, i) => `[${i}] "${f.name() || "(unnamed)"}" — ${f.url()}`);
+						return {
+							content: [{ type: "text", text: `No frame URL matches "${params.urlPattern}".\nAvailable frames:\n  ${available.join("\n  ")}` }],
+							details: { error: "frame_not_found", available },
+							isError: true,
+						};
+					}
+					setActiveFrame(frame);
+					return {
+						content: [{ type: "text", text: `Selected frame "${frame.name() || "(unnamed)"}" — ${frame.url()}` }],
+						details: { name: frame.name(), url: frame.url() },
+					};
+				}
+
+				if (params.index !== undefined) {
+					if (params.index < 0 || params.index >= frames.length) {
+						return {
+							content: [{ type: "text", text: `Frame index ${params.index} out of range. ${frames.length} frame(s) available (0-${frames.length - 1}).` }],
+							details: { error: "index_out_of_range", count: frames.length },
+							isError: true,
+						};
+					}
+					const frame = frames[params.index];
+					setActiveFrame(frame);
+					return {
+						content: [{ type: "text", text: `Selected frame [${params.index}] "${frame.name() || "(unnamed)"}" — ${frame.url()}` }],
+						details: { index: params.index, name: frame.name(), url: frame.url() },
+					};
+				}
+
+				return {
+					content: [{ type: "text", text: "Provide name, urlPattern, or index to select a frame. Use name='main' to reset to main frame." }],
+					details: { error: "no_criteria" },
+					isError: true,
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Select frame failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}