gsd-pi 2.33.1 → 2.34.0-dev.bbb5216

package/dist/resources/extensions/browser-tools/tools/interaction.ts

@@ -1,865 +0,0 @@
-import type { ExtensionAPI } from "@gsd/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
-import { StringEnum } from "@gsd/pi-ai";
-import {
-	diffCompactStates,
-} from "../core.js";
-import type { ToolDeps, CompactPageState } from "../state.js";
-import {
-	setLastActionBeforeState,
-	setLastActionAfterState,
-} from "../state.js";
-import { readFocusedDescriptor } from "../settle.js";
-
-export function registerInteractionTools(pi: ExtensionAPI, deps: ToolDeps): void {
-	// -------------------------------------------------------------------------
-	// browser_click
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_click",
-		label: "Browser Click",
-		description:
-			"Click an element on the page by CSS selector or by x,y coordinates. Returns a compact page summary plus lightweight verification details after clicking. Provide either selector or both x and y. Prefer selector over coordinates — selectors are more reliable because they handle shadow DOM via getByRole fallbacks. Use coordinates only when you have no other option.",
-		parameters: Type.Object({
-			selector: Type.Optional(
-				Type.String({ description: "CSS selector of the element to click. The tool will try getByRole fallbacks if the CSS selector fails (handles shadow DOM)." })
-			),
-			x: Type.Optional(Type.Number({ description: "X coordinate to click" })),
-			y: Type.Optional(Type.Number({ description: "Y coordinate to click" })),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			let actionId: number | null = null;
-			let beforeState: CompactPageState | null = null;
-			try {
-				const { page: p } = await deps.ensureBrowser();
-				const target = deps.getActiveTarget();
-				beforeState = await deps.captureCompactPageState(p, { selectors: params.selector ? [params.selector] : [], includeBodyText: true, target });
-				actionId = deps.beginTrackedAction("browser_click", params, beforeState.url).id;
-				const beforeUrl = p.url();
-				const beforeHash = deps.getUrlHash(beforeUrl);
-				const beforeTargetState = params.selector
-					? await deps.captureClickTargetState(target, params.selector)
-					: null;
-
-				if (params.selector) {
-					try {
-						await target.locator(params.selector).first().click({ timeout: 5000 });
-					} catch {
-						const nameMatch = params.selector.match(/\[(?:aria-label|name|placeholder)="([^"]+)"\]/i);
-						const roleName = nameMatch?.[1];
-						let clicked = false;
-						for (const role of ["combobox", "searchbox", "textbox", "button", "link"] as const) {
-							try {
-								const loc = roleName
-									? target.getByRole(role, { name: new RegExp(roleName, "i") })
-									: target.getByRole(role);
-								await loc.first().click({ timeout: 3000 });
-								clicked = true;
-								break;
-							} catch { /* try next role */ }
-						}
-						if (!clicked) {
-							if (params.x !== undefined && params.y !== undefined) {
-								await p.mouse.click(params.x, params.y);
-							} else {
-								throw new Error(`Could not click selector "${params.selector}" — element not found (shadow DOM?)`);
-							}
-						}
-					}
-				} else if (params.x !== undefined && params.y !== undefined) {
-					await p.mouse.click(params.x, params.y);
-				} else {
-					return {
-						content: [
-							{
-								type: "text",
-								text: "Must provide either selector or both x and y coordinates",
-							},
-						],
-						details: {},
-						isError: true,
-					};
-				}
-
-				const settle = await deps.settleAfterActionAdaptive(p);
-
-				const afterState = await deps.captureCompactPageState(p, { selectors: params.selector ? [params.selector] : [], includeBodyText: true, target });
-				const url = afterState.url;
-				const hash = deps.getUrlHash(url);
-				const afterTargetState = params.selector
-					? await deps.captureClickTargetState(target, params.selector)
-					: null;
-				const targetStateChanged = !!beforeTargetState && !!afterTargetState && (
-					beforeTargetState.exists !== afterTargetState.exists ||
-					beforeTargetState.ariaExpanded !== afterTargetState.ariaExpanded ||
-					beforeTargetState.ariaPressed !== afterTargetState.ariaPressed ||
-					beforeTargetState.ariaSelected !== afterTargetState.ariaSelected ||
-					beforeTargetState.open !== afterTargetState.open
-				);
-				const verification = deps.verificationFromChecks(
-					[
-						{ name: "url_changed", passed: url !== beforeUrl, value: url, expected: `!= ${beforeUrl}` },
-						{ name: "hash_changed", passed: hash !== beforeHash, value: hash, expected: `!= ${beforeHash}` },
-						{ name: "target_state_changed", passed: targetStateChanged, value: afterTargetState, expected: beforeTargetState },
-						{ name: "dialog_open", passed: afterState.dialog.count > beforeState!.dialog.count, value: afterState.dialog.count, expected: `> ${beforeState!.dialog.count}` },
-					],
-					"Try a more specific selector or click a clearly interactive element."
-				);
-				const clickTarget = params.selector ?? `(${params.x}, ${params.y})`;
-				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,
-					verificationSummary: verification.verificationSummary,
-					warningSummary: jsErrors.trim() || undefined,
-					diffSummary: diff.summary,
-					changed: diff.changed,
-					beforeState: beforeState!,
-					afterState,
-				});
-
-				return {
-					content: [{ type: "text", text: `Clicked: ${clickTarget}\nURL: ${url}\nAction: ${actionId}\n${deps.verificationLine(verification)}${jsErrors}\n\nDiff:\n${deps.formatDiffText(diff)}\n\nPage summary:\n${summary}` }],
-					details: { target: clickTarget, url, actionId, diff, ...settle, ...verification },
-				};
-			} 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: `Click failed: ${err.message}` }];
-				if (errorShot) {
-					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
-				}
-				return {
-					content,
-					details: { error: err.message },
-					isError: true,
-				};
-			}
-		},
-	});
-
-	// -------------------------------------------------------------------------
-	// browser_drag
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_drag",
-		label: "Browser Drag",
-		description:
-			"Drag an element and drop it onto another element. Use for sortable lists, kanban boards, sliders, and any drag-and-drop UI.",
-		parameters: Type.Object({
-			sourceSelector: Type.String({
-				description: "CSS selector of the element to drag",
-			}),
-			targetSelector: Type.String({
-				description: "CSS selector of the element to drop onto",
-			}),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			try {
-				const { page: p } = await deps.ensureBrowser();
-				const target = deps.getActiveTarget();
-				await target.dragAndDrop(params.sourceSelector, params.targetSelector, { timeout: 10000 });
-				const settle = await deps.settleAfterActionAdaptive(p);
-
-				const afterState = await deps.captureCompactPageState(p, { includeBodyText: false, target });
-				const summary = deps.formatCompactStateSummary(afterState);
-				const jsErrors = deps.getRecentErrors(p.url());
-
-				return {
-					content: [{
-						type: "text",
-						text: `Dragged "${params.sourceSelector}" → "${params.targetSelector}"${jsErrors}\n\nPage summary:\n${summary}`,
-					}],
-					details: { source: params.sourceSelector, target: params.targetSelector, ...settle },
-				};
-			} catch (err: any) {
-				const errorShot = await deps.captureErrorScreenshot(deps.getActivePageOrNull());
-				const content: any[] = [{ type: "text", text: `Drag failed: ${err.message}` }];
-				if (errorShot) {
-					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
-				}
-				return { content, details: { error: err.message }, isError: true };
-			}
-		},
-	});
-
-	// -------------------------------------------------------------------------
-	// browser_type
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_type",
-		label: "Browser Type",
-		description:
-			"Type text into an input element. By default uses atomic fill (clears and sets value instantly). Use 'slowly' for character-by-character typing when you need to trigger key handlers (e.g. search autocomplete). Use 'submit' to press Enter after typing. Returns a compact page summary plus lightweight verification details. IMPORTANT: Always provide a selector — do NOT rely on coordinate clicks to focus an input before calling this. CSS attribute selectors like combobox[aria-label='X'] work for most inputs; for shadow DOM inputs (e.g. Google Search), the tool automatically tries getByRole fallbacks.",
-		parameters: Type.Object({
-			text: Type.String({ description: "Text to type" }),
-			selector: Type.Optional(
-				Type.String({ description: "CSS selector of the input to type into (clicks it first). Examples: 'input[name=q]', 'textarea', 'combobox[aria-label=\"Search\"]'. The tool will try getByRole fallbacks if the CSS selector fails." })
-			),
-			clearFirst: Type.Optional(
-				Type.Boolean({
-					description:
-						"Clear the input's existing value before typing (default: false). Use this when replacing existing text.",
-				})
-			),
-			submit: Type.Optional(
-				Type.Boolean({
-					description: "Press Enter after typing to submit the form (default: false).",
-				})
-			),
-			slowly: Type.Optional(
-				Type.Boolean({
-					description:
-						"Type one character at a time instead of filling atomically. Use when you need to trigger key handlers (e.g. search autocomplete). 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();
-				const target = deps.getActiveTarget();
-				beforeState = await deps.captureCompactPageState(p, { selectors: params.selector ? [params.selector] : [], includeBodyText: true, target });
-				actionId = deps.beginTrackedAction("browser_type", params, beforeState.url).id;
-				const beforeUrl = p.url();
-
-				async function focusViaRole(selector: string): Promise<boolean> {
-					const nameMatch = selector.match(/\[(?:aria-label|name|placeholder)="([^"]+)"\]/i);
-					const roleName = nameMatch?.[1];
-					for (const role of ["combobox", "searchbox", "textbox"] as const) {
-						try {
-							const loc = roleName
-								? target.getByRole(role, { name: new RegExp(roleName, "i") })
-								: target.getByRole(role);
-							await loc.first().click({ timeout: 3000 });
-							return true;
-						} catch { /* try next */ }
-					}
-					return false;
-				}
-
-				if (params.selector) {
-					if (params.slowly) {
-						let focused = false;
-						try {
-							await target.locator(params.selector).first().click({ timeout: 5000 });
-							focused = true;
-						} catch {
-							focused = await focusViaRole(params.selector);
-						}
-						if (!focused) throw new Error(`Could not focus selector "${params.selector}"`);
-						if (params.clearFirst) {
-							await p.keyboard.press("Control+A");
-							await p.keyboard.press("Delete");
-						}
-						await p.keyboard.type(params.text);
-					} else {
-						let filled = false;
-						try {
-							await target.locator(params.selector).first().fill(params.text, { timeout: 5000 });
-							filled = true;
-						} catch { /* fall through */ }
-
-						if (!filled) {
-							const nameMatch = params.selector.match(/\[(?:aria-label|name|placeholder)="([^"]+)"\]/i);
-							const roleName = nameMatch?.[1];
-							for (const role of ["combobox", "searchbox", "textbox"] as const) {
-								try {
-									const loc = roleName
-										? target.getByRole(role, { name: new RegExp(roleName, "i") })
-										: target.getByRole(role);
-									await loc.first().fill(params.text, { timeout: 3000 });
-									filled = true;
-									break;
-								} catch { /* try next */ }
-							}
-						}
-
-						if (!filled) {
-							let focused = false;
-							try {
-								await target.locator(params.selector).first().click({ timeout: 5000 });
-								focused = true;
-							} catch {
-								focused = await focusViaRole(params.selector);
-							}
-							if (!focused) throw new Error(`Could not focus selector "${params.selector}"`);
-							if (params.clearFirst) {
-								await p.keyboard.press("Control+A");
-								await p.keyboard.press("Delete");
-							}
-							await target.locator(":focus").pressSequentially(params.text, { timeout: 5000 }).catch(() =>
-								p.keyboard.type(params.text)
-							);
-						} else if (params.clearFirst) {
-							// fill() already replaced the value; clearFirst is a no-op here
-						}
-					}
-				} else {
-					const hasFocus = await target.evaluate(() => {
-						const el = document.activeElement;
-						return !!(el && el !== document.body && el !== document.documentElement);
-					});
-					if (!hasFocus) {
-						return {
-							content: [{ type: "text", text: "Type failed: no element is focused. Use browser_click to focus an input first, or provide a selector." }],
-							details: { error: "no focused element" },
-							isError: true,
-						};
-					}
-					await target.locator(":focus").pressSequentially(params.text, { timeout: 10000 }).catch(() =>
-						p.keyboard.type(params.text)
-					);
-				}
-
-				if (params.submit) {
-					await p.keyboard.press("Enter");
-				}
-
-				const settle = await deps.settleAfterActionAdaptive(p);
-
-				const typedValue = await deps.readInputLikeValue(target, params.selector);
-				const afterUrl = p.url();
-				const verification = deps.verificationFromChecks(
-					[
-						{ name: "value_equals_expected", passed: typedValue === params.text, value: typedValue, expected: params.text },
-						{ name: "value_contains_expected", passed: typeof typedValue === "string" && typedValue.includes(params.text), value: typedValue, expected: params.text },
-						{ name: "url_changed_after_submit", passed: !!params.submit && afterUrl !== beforeUrl, value: afterUrl, expected: `!= ${beforeUrl}` },
-					],
-					"Try clearFirst=true, use a more specific selector, or set slowly=true for key-driven inputs."
-				);
-				const typeTarget = params.selector ? ` into "${params.selector}"` : "";
-				const afterState = await deps.captureCompactPageState(p, { selectors: params.selector ? [params.selector] : [], includeBodyText: true, target });
-				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,
-					verificationSummary: verification.verificationSummary,
-					warningSummary: jsErrors.trim() || undefined,
-					diffSummary: diff.summary,
-					changed: diff.changed,
-					beforeState: beforeState!,
-					afterState,
-				});
-
-				return {
-					content: [{ type: "text", text: `Typed "${params.text}"${typeTarget}\nAction: ${actionId}\n${deps.verificationLine(verification)}${jsErrors}\n\nDiff:\n${deps.formatDiffText(diff)}\n\nPage summary:\n${summary}` }],
-					details: { text: params.text, selector: params.selector, typedValue, actionId, diff, ...settle, ...verification },
-				};
-			} 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: `Type failed: ${err.message}` }];
-				if (errorShot) {
-					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
-				}
-				return {
-					content,
-					details: { error: err.message },
-					isError: true,
-				};
-			}
-		},
-	});
-
-	// -------------------------------------------------------------------------
-	// browser_upload_file
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_upload_file",
-		label: "Browser Upload File",
-		description:
-			"Set files on a file input element. The selector must target an <input type=\"file\"> element. Accepts one or more absolute file paths.",
-		parameters: Type.Object({
-			selector: Type.String({
-				description: 'CSS selector targeting the <input type="file"> element',
-			}),
-			files: Type.Array(Type.String({ description: "Absolute path to a file" }), {
-				description: "One or more file paths to upload",
-			}),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			try {
-				const { page: p } = await deps.ensureBrowser();
-				const target = deps.getActiveTarget();
-				const cleanFiles = params.files.map((f: string) => f.replace(/^@/, ""));
-				await target.locator(params.selector).first().setInputFiles(cleanFiles);
-				const settle = await deps.settleAfterActionAdaptive(p);
-
-				const afterState = await deps.captureCompactPageState(p, { includeBodyText: false, target });
-				const summary = deps.formatCompactStateSummary(afterState);
-				const jsErrors = deps.getRecentErrors(p.url());
-
-				return {
-					content: [{
-						type: "text",
-						text: `Uploaded ${cleanFiles.length} file(s) to "${params.selector}": ${cleanFiles.join(", ")}${jsErrors}\n\nPage summary:\n${summary}`,
-					}],
-					details: { selector: params.selector, files: cleanFiles, ...settle },
-				};
-			} catch (err: any) {
-				const errorShot = await deps.captureErrorScreenshot(deps.getActivePageOrNull());
-				const content: any[] = [{ type: "text", text: `Upload failed: ${err.message}` }];
-				if (errorShot) {
-					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
-				}
-				return { content, details: { error: err.message }, isError: true };
-			}
-		},
-	});
-
-	// -------------------------------------------------------------------------
-	// browser_scroll
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_scroll",
-		label: "Browser Scroll",
-		description: "Scroll the page up or down by a given number of pixels. Returns scroll position (px and percentage) and an accessibility snapshot of the visible content.",
-		parameters: Type.Object({
-			direction: StringEnum(["up", "down"] as const),
-			amount: Type.Optional(
-				Type.Number({ description: "Pixels to scroll (default: 300)" })
-			),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			try {
-				const { page: p } = await deps.ensureBrowser();
-				const target = deps.getActiveTarget();
-				const pixels = params.amount ?? 300;
-				const delta = params.direction === "up" ? -pixels : pixels;
-				await p.mouse.wheel(0, delta);
-
-				const settle = await deps.settleAfterActionAdaptive(p);
-
-				const scrollInfo = await target.evaluate(() => ({
-					scrollY: Math.round(window.scrollY),
-					scrollHeight: document.documentElement.scrollHeight,
-					clientHeight: document.documentElement.clientHeight,
-				}));
-				const maxScroll = scrollInfo.scrollHeight - scrollInfo.clientHeight;
-				const percent = maxScroll > 0 ? Math.round((scrollInfo.scrollY / maxScroll) * 100) : 0;
-
-				const afterState = await deps.captureCompactPageState(p, { includeBodyText: false, target });
-				const summary = deps.formatCompactStateSummary(afterState);
-				const jsErrors = deps.getRecentErrors(p.url());
-
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Scrolled ${params.direction} by ${pixels}px\n` +
-								  `Position: ${scrollInfo.scrollY}px / ${scrollInfo.scrollHeight}px (${percent}% down)\n` +
-								  `Viewport height: ${scrollInfo.clientHeight}px${jsErrors}\n\nPage summary:\n${summary}`,
-						},
-					],
-					details: { direction: params.direction, amount: pixels, ...scrollInfo, percent, ...settle },
-				};
-			} catch (err: any) {
-				return {
-					content: [{ type: "text", text: `Scroll failed: ${err.message}` }],
-					details: { error: err.message },
-					isError: true,
-				};
-			}
-		},
-	});
-
-	// -------------------------------------------------------------------------
-	// browser_hover
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_hover",
-		label: "Browser Hover",
-		description:
-			"Move the mouse over an element to trigger hover states — reveals tooltips, dropdown menus, CSS :hover effects, and other hover-dependent UI. Returns a compact page summary showing the resulting hover state.",
-		parameters: Type.Object({
-			selector: Type.String({
-				description: "CSS selector of the element to hover over",
-			}),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			try {
-				const { page: p } = await deps.ensureBrowser();
-				const target = deps.getActiveTarget();
-				await target.locator(params.selector).first().hover({ timeout: 10000 });
-				const settle = await deps.settleAfterActionAdaptive(p);
-
-				const afterState = await deps.captureCompactPageState(p, { includeBodyText: false, target });
-				const summary = deps.formatCompactStateSummary(afterState);
-				const jsErrors = deps.getRecentErrors(p.url());
-
-				return {
-					content: [{ type: "text", text: `Hovering over "${params.selector}"${jsErrors}\n\nPage summary:\n${summary}` }],
-					details: { selector: params.selector, ...settle },
-				};
-			} catch (err: any) {
-				const errorShot = await deps.captureErrorScreenshot(deps.getActivePageOrNull());
-				const content: any[] = [{ type: "text", text: `Hover failed: ${err.message}` }];
-				if (errorShot) {
-					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
-				}
-				return {
-					content,
-					details: { error: err.message },
-					isError: true,
-				};
-			}
-		},
-	});
-
-	// -------------------------------------------------------------------------
-	// browser_key_press
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_key_press",
-		label: "Browser Key Press",
-		description:
-			"Press a keyboard key or key combination. Returns a compact page summary plus lightweight verification details after the key press. Use for: submitting forms (Enter), closing modals (Escape), navigating focusable elements (Tab / Shift+Tab), operating dropdowns and menus (ArrowDown, ArrowUp, Space), copying/pasting (Meta+C, Meta+V). Key names follow the DOM KeyboardEvent key convention.",
-		parameters: Type.Object({
-			key: Type.String({
-				description:
-					"Key or combination to press, e.g. 'Enter', 'Escape', 'Tab', 'ArrowDown', 'ArrowUp', 'Space', 'Meta+A', 'Shift+Tab', 'Control+Enter'",
-			}),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			let actionId: number | null = null;
-			let beforeState: CompactPageState | null = null;
-			try {
-				const { page: p } = await deps.ensureBrowser();
-				const target = deps.getActiveTarget();
-				beforeState = await deps.captureCompactPageState(p, { includeBodyText: true, target });
-				actionId = deps.beginTrackedAction("browser_key_press", params, beforeState.url).id;
-				const beforeUrl = p.url();
-				const beforeFocus = await readFocusedDescriptor(target);
-
-				await p.keyboard.press(params.key);
-				const settle = await deps.settleAfterActionAdaptive(p, { checkFocusStability: true });
-
-				const afterState = await deps.captureCompactPageState(p, { includeBodyText: true, target });
-				const afterUrl = afterState.url;
-				const afterFocus = await readFocusedDescriptor(target);
-				const verification = deps.verificationFromChecks(
-					[
-						{ name: "url_changed", passed: afterUrl !== beforeUrl, value: afterUrl, expected: `!= ${beforeUrl}` },
-						{ name: "focus_changed", passed: afterFocus !== beforeFocus, value: afterFocus, expected: `!= ${beforeFocus}` },
-						{ name: "dialog_open", passed: afterState.dialog.count > beforeState!.dialog.count, value: afterState.dialog.count, expected: `> ${beforeState!.dialog.count}` },
-					],
-					"If this key should trigger UI changes, confirm focus is on the intended element first."
-				);
-
-				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,
-					verificationSummary: verification.verificationSummary,
-					warningSummary: jsErrors.trim() || undefined,
-					diffSummary: diff.summary,
-					changed: diff.changed,
-					beforeState: beforeState!,
-					afterState,
-				});
-
-				return {
-					content: [{ type: "text", text: `Pressed "${params.key}"\nAction: ${actionId}\n${deps.verificationLine(verification)}${jsErrors}\n\nDiff:\n${deps.formatDiffText(diff)}\n\nPage summary:\n${summary}` }],
-					details: { key: params.key, beforeFocus, afterFocus, actionId, diff, ...settle, ...verification },
-				};
-			} 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: `Key press failed: ${err.message}` }];
-				if (errorShot) {
-					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
-				}
-				return {
-					content,
-					details: { error: err.message },
-					isError: true,
-				};
-			}
-		},
-	});
-
-	// -------------------------------------------------------------------------
-	// browser_select_option
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_select_option",
-		label: "Browser Select Option",
-		description:
-			"Select an option from a <select> dropdown element by its visible label or value. Returns a compact page summary plus lightweight verification details. For custom-built dropdowns use browser_click to open them then browser_click to pick the option.",
-		parameters: Type.Object({
-			selector: Type.String({
-				description: "CSS selector targeting the <select> element",
-			}),
-			option: Type.String({
-				description:
-					"The option to select — can be the visible label text or the value attribute. Will try label first, then value.",
-			}),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			let actionId: number | null = null;
-			let beforeState: CompactPageState | null = null;
-			try {
-				const { page: p } = await deps.ensureBrowser();
-				const target = deps.getActiveTarget();
-				beforeState = await deps.captureCompactPageState(p, { selectors: [params.selector], includeBodyText: true, target });
-				actionId = deps.beginTrackedAction("browser_select_option", params, beforeState.url).id;
-
-				let selected: string[];
-				try {
-					selected = await target.selectOption(params.selector, { label: params.option }, { timeout: 5000 });
-				} catch {
-					selected = await target.selectOption(params.selector, { value: params.option }, { timeout: 5000 });
-				}
-
-				const settle = await deps.settleAfterActionAdaptive(p);
-
-				const selectedState = await target.locator(params.selector).first().evaluate((el) => {
-					if (!(el instanceof HTMLSelectElement)) {
-						return { selectedValues: [] as string[], selectedLabels: [] as string[] };
-					}
-					const selectedOptions = Array.from(el.selectedOptions || []);
-					return {
-						selectedValues: selectedOptions.map((opt) => opt.value),
-						selectedLabels: selectedOptions.map((opt) => (opt.textContent || "").trim()),
-					};
-				});
-				const optionNeedle = params.option.toLowerCase();
-				const verification = deps.verificationFromChecks(
-					[
-						{ name: "selected_values_include_option", passed: selectedState.selectedValues.includes(params.option), value: selectedState.selectedValues, expected: params.option },
-						{ name: "selected_labels_include_option", passed: selectedState.selectedLabels.some((label) => label.toLowerCase().includes(optionNeedle)), value: selectedState.selectedLabels, expected: params.option },
-					],
-					"Confirm whether the target select uses option label or value, then retry with that exact text."
-				);
-
-				const afterState = await deps.captureCompactPageState(p, { selectors: [params.selector], includeBodyText: true, target });
-				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,
-					verificationSummary: verification.verificationSummary,
-					warningSummary: jsErrors.trim() || undefined,
-					diffSummary: diff.summary,
-					changed: diff.changed,
-					beforeState: beforeState!,
-					afterState,
-				});
-
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Selected "${params.option}" in "${params.selector}". Values: ${selected.join(", ")}\nAction: ${actionId}\n${deps.verificationLine(verification)}${jsErrors}\n\nDiff:\n${deps.formatDiffText(diff)}\n\nPage summary:\n${summary}`,
-						},
-					],
-					details: { selector: params.selector, option: params.option, selected, selectedState, actionId, diff, ...settle, ...verification },
-				};
-			} 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: `Select option failed: ${err.message}` }];
-				if (errorShot) {
-					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
-				}
-				return {
-					content,
-					details: { error: err.message },
-					isError: true,
-				};
-			}
-		},
-	});
-
-	// -------------------------------------------------------------------------
-	// browser_set_checked
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_set_checked",
-		label: "Browser Set Checked",
-		description:
-			"Check or uncheck a checkbox or radio button. More reliable than clicking for form elements where you need a specific state.",
-		parameters: Type.Object({
-			selector: Type.String({
-				description: "CSS selector targeting the checkbox or radio input",
-			}),
-			checked: Type.Boolean({
-				description: "true to check, false to uncheck",
-			}),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			let actionId: number | null = null;
-			let beforeState: CompactPageState | null = null;
-			try {
-				const { page: p } = await deps.ensureBrowser();
-				const target = deps.getActiveTarget();
-				beforeState = await deps.captureCompactPageState(p, { selectors: [params.selector], includeBodyText: true, target });
-				actionId = deps.beginTrackedAction("browser_set_checked", params, beforeState.url).id;
-				await target.locator(params.selector).first().setChecked(params.checked, { timeout: 10000 });
-				const settle = await deps.settleAfterActionAdaptive(p);
-
-				const actualChecked = await target.locator(params.selector).first().isChecked().catch(() => null);
-				const verification = deps.verificationFromChecks(
-					[
-						{ name: "checked_state_matches", passed: actualChecked === params.checked, value: actualChecked, expected: params.checked },
-					],
-					"Ensure selector points to a checkbox/radio input and retry."
-				);
-
-				const state = params.checked ? "checked" : "unchecked";
-				const afterState = await deps.captureCompactPageState(p, { selectors: [params.selector], includeBodyText: true, target });
-				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,
-					verificationSummary: verification.verificationSummary,
-					warningSummary: jsErrors.trim() || undefined,
-					diffSummary: diff.summary,
-					changed: diff.changed,
-					beforeState: beforeState!,
-					afterState,
-				});
-
-				return {
-					content: [{
-						type: "text",
-						text: `Set "${params.selector}" to ${state}\nAction: ${actionId}\n${deps.verificationLine(verification)}${jsErrors}\n\nDiff:\n${deps.formatDiffText(diff)}\n\nPage summary:\n${summary}`,
-					}],
-					details: { selector: params.selector, checked: params.checked, actualChecked, actionId, diff, ...settle, ...verification },
-				};
-			} 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: `Set checked failed: ${err.message}` }];
-				if (errorShot) {
-					content.push({ type: "image", data: errorShot.data, mimeType: errorShot.mimeType });
-				}
-				return { content, details: { error: err.message }, isError: true };
-			}
-		},
-	});
-
-	// -------------------------------------------------------------------------
-	// browser_set_viewport
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_set_viewport",
-		label: "Browser Set Viewport",
-		description:
-			"Resize the browser viewport to test responsive layouts at different screen sizes. Use presets for common breakpoints or specify exact pixel dimensions. Essential for verifying mobile/tablet/desktop layouts.",
-		parameters: Type.Object({
-			preset: Type.Optional(
-				StringEnum(["mobile", "tablet", "desktop", "wide"] as const)
-			),
-			width: Type.Optional(
-				Type.Number({ description: "Custom viewport width in pixels (requires height too)" })
-			),
-			height: Type.Optional(
-				Type.Number({ description: "Custom viewport height in pixels (requires width too)" })
-			),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			try {
-				const { page: p } = await deps.ensureBrowser();
-
-				let width: number;
-				let height: number;
-				let label: string;
-
-				if (params.preset) {
-					switch (params.preset) {
-						case "mobile":
-							width = 390;
-							height = 844;
-							label = "mobile (390×844)";
-							break;
-						case "tablet":
-							width = 768;
-							height = 1024;
-							label = "tablet (768×1024)";
-							break;
-						case "desktop":
-							width = 1280;
-							height = 800;
-							label = "desktop (1280×800)";
-							break;
-						case "wide":
-							width = 1920;
-							height = 1080;
-							label = "wide (1920×1080)";
-							break;
-					}
-				} else if (params.width !== undefined && params.height !== undefined) {
-					width = params.width;
-					height = params.height;
-					label = `custom (${width}×${height})`;
-				} else {
-					return {
-						content: [
-							{
-								type: "text",
-								text: "Provide either a preset (mobile/tablet/desktop/wide) or both width and height.",
-							},
-						],
-						details: {},
-						isError: true,
-					};
-				}
-
-				await p.setViewportSize({ width: width!, height: height! });
-
-				return {
-					content: [{ type: "text", text: `Viewport set to ${label!}` }],
-					details: { width: width!, height: height!, label: label! },
-				};
-			} catch (err: any) {
-				return {
-					content: [{ type: "text", text: `Set viewport failed: ${err.message}` }],
-					details: { error: err.message },
-					isError: true,
-				};
-			}
-		},
-	});
-}