gsd-pi 2.7.1 → 2.8.0

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

@@ -0,0 +1,400 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import {
+	formatTimelineEntries,
+	buildFailureHypothesis,
+	summarizeBrowserSession,
+} from "../core.js";
+import type { ToolDeps } from "../state.js";
+import {
+	ARTIFACT_ROOT,
+	HAR_FILENAME,
+	getPageRegistry,
+	getActiveFrame,
+	getConsoleLogs,
+	getNetworkLogs,
+	getDialogLogs,
+	getActionTimeline,
+	getActiveTraceSession,
+	setActiveTraceSession,
+	getHarState,
+	setHarState,
+	getSessionStartedAt,
+	getSessionArtifactDir,
+} from "../state.js";
+import {
+	getActiveFrameMetadata,
+	ensureDir,
+} from "../utils.js";
+
+export function registerSessionTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	// -------------------------------------------------------------------------
+	// browser_close
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_close",
+		label: "Browser Close",
+		description: "Close the browser and clean up all resources.",
+		parameters: Type.Object({}),
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.closeBrowser();
+				return {
+					content: [{ type: "text", text: "Browser closed." }],
+					details: {},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Close failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_trace_start
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_trace_start",
+		label: "Browser Trace Start",
+		description: "Start a Playwright trace for the current browser session and persist trace metadata under the session artifact directory.",
+		parameters: Type.Object({
+			name: Type.Optional(Type.String({ description: "Optional short trace session name for artifact filenames." })),
+			title: Type.Optional(Type.String({ description: "Optional trace title recorded in metadata." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { context: browserContext } = await deps.ensureBrowser();
+				const activeTrace = getActiveTraceSession();
+				if (activeTrace) {
+					return {
+						content: [{ type: "text", text: `Trace already active: ${activeTrace.name}` }],
+						details: { error: "trace_already_active", activeTraceSession: activeTrace, ...deps.getSessionArtifactMetadata() },
+						isError: true,
+					};
+				}
+				const startedAt = Date.now();
+				const name = (params.name?.trim() || `trace-${deps.formatArtifactTimestamp(startedAt)}`).replace(/[^a-zA-Z0-9._-]+/g, "-");
+				await browserContext.tracing.start({ screenshots: true, snapshots: true, sources: true, title: params.title ?? name });
+				setActiveTraceSession({ startedAt, name, title: params.title ?? name });
+				return {
+					content: [{ type: "text", text: `Trace started: ${name}\nSession dir: ${getSessionArtifactDir()}` }],
+					details: { activeTraceSession: getActiveTraceSession(), ...deps.getSessionArtifactMetadata() },
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Trace start failed: ${err.message}` }],
+					details: { error: err.message, ...deps.getSessionArtifactMetadata() },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_trace_stop
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_trace_stop",
+		label: "Browser Trace Stop",
+		description: "Stop the active Playwright trace and write the trace zip to disk under the session artifact directory.",
+		parameters: Type.Object({
+			name: Type.Optional(Type.String({ description: "Optional artifact basename override for the trace zip." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { context: browserContext } = await deps.ensureBrowser();
+				const activeTrace = getActiveTraceSession();
+				if (!activeTrace) {
+					return {
+						content: [{ type: "text", text: "No active trace session to stop." }],
+						details: { error: "trace_not_active", ...deps.getSessionArtifactMetadata() },
+						isError: true,
+					};
+				}
+				const traceSession = activeTrace;
+				const traceName = (params.name?.trim() || traceSession.name).replace(/[^a-zA-Z0-9._-]+/g, "-");
+				const tracePath = deps.buildSessionArtifactPath(`${traceName}.trace.zip`);
+				await browserContext.tracing.stop({ path: tracePath });
+				const fileStat = await stat(tracePath);
+				setActiveTraceSession(null);
+				return {
+					content: [{ type: "text", text: `Trace stopped: ${tracePath}` }],
+					details: {
+						path: tracePath,
+						bytes: fileStat.size,
+						elapsedMs: Date.now() - traceSession.startedAt,
+						traceName,
+						...deps.getSessionArtifactMetadata(),
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Trace stop failed: ${err.message}` }],
+					details: { error: err.message, ...deps.getSessionArtifactMetadata() },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_export_har
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_export_har",
+		label: "Browser Export HAR",
+		description: "Export the truthfully recorded session HAR from disk to a stable artifact path and return compact metadata.",
+		parameters: Type.Object({
+			filename: Type.Optional(Type.String({ description: "Optional destination filename within the session artifact directory." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.ensureBrowser();
+				const harState = getHarState();
+				if (!harState.enabled || !harState.configuredAtContextCreation || !harState.path) {
+					return {
+						content: [{ type: "text", text: "HAR export unavailable: HAR recording was not enabled at browser context creation." }],
+						details: { error: "har_not_enabled", ...deps.getSessionArtifactMetadata() },
+						isError: true,
+					};
+				}
+				const sourcePath = harState.path;
+				const destinationName = (params.filename?.trim() || `export-${HAR_FILENAME}`).replace(/[^a-zA-Z0-9._-]+/g, "-");
+				const destinationPath = deps.buildSessionArtifactPath(destinationName);
+				const exportResult = sourcePath === destinationPath
+					? { path: sourcePath, bytes: (await stat(sourcePath)).size }
+					: await deps.copyArtifactFile(sourcePath, destinationPath);
+				setHarState({
+					...harState,
+					exportCount: harState.exportCount + 1,
+					lastExportedPath: exportResult.path,
+					lastExportedAt: Date.now(),
+				});
+				return {
+					content: [{ type: "text", text: `HAR exported: ${exportResult.path}` }],
+					details: { path: exportResult.path, bytes: exportResult.bytes, ...deps.getSessionArtifactMetadata() },
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `HAR export failed: ${err.message}` }],
+					details: { error: err.message, ...deps.getSessionArtifactMetadata() },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_timeline
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_timeline",
+		label: "Browser Timeline",
+		description: "Return a compact structured summary of the tracked browser action timeline and optional on-disk export path.",
+		parameters: Type.Object({
+			writeToDisk: Type.Optional(Type.Boolean({ description: "Write the timeline JSON to disk under the session artifact directory." })),
+			filename: Type.Optional(Type.String({ description: "Optional JSON filename when writeToDisk is true." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.ensureBrowser();
+				const actionTimeline = getActionTimeline();
+				const timeline = formatTimelineEntries(actionTimeline.entries, {
+					limit: actionTimeline.limit,
+					totalActions: actionTimeline.nextId - 1,
+				});
+				let artifact: { path: string; bytes: number } | null = null;
+				if (params.writeToDisk) {
+					const filename = (params.filename?.trim() || "timeline.json").replace(/[^a-zA-Z0-9._-]+/g, "-");
+					artifact = await deps.writeArtifactFile(deps.buildSessionArtifactPath(filename), JSON.stringify(timeline, null, 2));
+				}
+				return {
+					content: [{ type: "text", text: artifact ? `${timeline.summary}\nArtifact: ${artifact.path}` : timeline.summary }],
+					details: { ...timeline, artifact, ...deps.getSessionArtifactMetadata() },
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Timeline failed: ${err.message}` }],
+					details: { error: err.message, ...deps.getSessionArtifactMetadata() },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_session_summary
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_session_summary",
+		label: "Browser Session Summary",
+		description: "Return a compact structured summary of the current browser session, including pages, actions, waits/assertions, bounded-history caveats, and trace/HAR state.",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.ensureBrowser();
+				const pages = await deps.getLivePagesSnapshot();
+				const actionTimeline = getActionTimeline();
+				const pageRegistry = getPageRegistry();
+				const consoleLogs = getConsoleLogs();
+				const networkLogs = getNetworkLogs();
+				const dialogLogs = getDialogLogs();
+				const baseSummary = summarizeBrowserSession({
+					timeline: actionTimeline,
+					totalActions: actionTimeline.nextId - 1,
+					pages,
+					activePageId: pageRegistry.activePageId,
+					activeFrame: getActiveFrameMetadata(),
+					consoleEntries: consoleLogs,
+					networkEntries: networkLogs,
+					dialogEntries: dialogLogs,
+					consoleLimit: 1000,
+					networkLimit: 1000,
+					dialogLimit: 1000,
+					sessionStartedAt: getSessionStartedAt(),
+					now: Date.now(),
+				});
+				const failureHypothesis = buildFailureHypothesis({
+					timeline: actionTimeline,
+					consoleEntries: consoleLogs,
+					networkEntries: networkLogs,
+					dialogEntries: dialogLogs,
+				});
+				const activeTrace = getActiveTraceSession();
+				const traceState = activeTrace
+					? { status: "active", ...activeTrace }
+					: { status: "inactive", lastTracePath: getSessionArtifactDir() ? deps.buildSessionArtifactPath("*.trace.zip") : null };
+				const harState = getHarState();
+				const harSummary = {
+					enabled: harState.enabled,
+					configuredAtContextCreation: harState.configuredAtContextCreation,
+					path: harState.path,
+					exportCount: harState.exportCount,
+					lastExportedPath: harState.lastExportedPath,
+					lastExportedAt: harState.lastExportedAt,
+				};
+				return {
+					content: [{ type: "text", text: `${baseSummary.summary}\nFailure hypothesis: ${failureHypothesis}` }],
+					details: {
+						...baseSummary,
+						failureHypothesis,
+						trace: traceState,
+						har: harSummary,
+						...deps.getSessionArtifactMetadata(),
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Session summary failed: ${err.message}` }],
+					details: { error: err.message, ...deps.getSessionArtifactMetadata() },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_debug_bundle
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_debug_bundle",
+		label: "Browser Debug Bundle",
+		description: "Write a timestamped debug bundle to disk with screenshot, logs, timeline, pages, session summary, and accessibility output, then return compact paths and counts.",
+		parameters: Type.Object({
+			selector: Type.Optional(Type.String({ description: "Optional CSS selector to scope the accessibility snapshot before fallback behavior applies." })),
+			name: Type.Optional(Type.String({ description: "Optional short bundle name suffix for the output directory." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				const startedAt = Date.now();
+				const sessionDir = await deps.ensureSessionArtifactDir();
+				const bundleDir = path.join(ARTIFACT_ROOT, `${deps.formatArtifactTimestamp(startedAt)}-${deps.sanitizeArtifactName(params.name ?? "debug-bundle", "debug-bundle")}`);
+				await ensureDir(bundleDir);
+				const pages = await deps.getLivePagesSnapshot();
+				const actionTimeline = getActionTimeline();
+				const pageRegistry = getPageRegistry();
+				const consoleLogs = getConsoleLogs();
+				const networkLogs = getNetworkLogs();
+				const dialogLogs = getDialogLogs();
+				const timeline = formatTimelineEntries(actionTimeline.entries, {
+					limit: actionTimeline.limit,
+					totalActions: actionTimeline.nextId - 1,
+				});
+				const sessionSummary = summarizeBrowserSession({
+					timeline: actionTimeline,
+					totalActions: actionTimeline.nextId - 1,
+					pages,
+					activePageId: pageRegistry.activePageId,
+					activeFrame: getActiveFrameMetadata(),
+					consoleEntries: consoleLogs,
+					networkEntries: networkLogs,
+					dialogEntries: dialogLogs,
+					consoleLimit: 1000,
+					networkLimit: 1000,
+					dialogLimit: 1000,
+					sessionStartedAt: getSessionStartedAt(),
+					now: Date.now(),
+				});
+				const failureHypothesis = buildFailureHypothesis({
+					timeline: actionTimeline,
+					consoleEntries: consoleLogs,
+					networkEntries: networkLogs,
+					dialogEntries: dialogLogs,
+				});
+				const accessibility = await deps.captureAccessibilityMarkdown(params.selector);
+				const screenshotPath = path.join(bundleDir, "screenshot.jpg");
+				await p.screenshot({ path: screenshotPath, type: "jpeg", quality: 80, fullPage: false });
+				const screenshotStat = await stat(screenshotPath);
+				const artifacts = {
+					screenshot: { path: screenshotPath, bytes: screenshotStat.size },
+					console: await deps.writeArtifactFile(path.join(bundleDir, "console.json"), JSON.stringify(consoleLogs, null, 2)),
+					network: await deps.writeArtifactFile(path.join(bundleDir, "network.json"), JSON.stringify(networkLogs, null, 2)),
+					dialog: await deps.writeArtifactFile(path.join(bundleDir, "dialog.json"), JSON.stringify(dialogLogs, null, 2)),
+					timeline: await deps.writeArtifactFile(path.join(bundleDir, "timeline.json"), JSON.stringify(timeline, null, 2)),
+					summary: await deps.writeArtifactFile(path.join(bundleDir, "summary.json"), JSON.stringify({
+						...sessionSummary,
+						failureHypothesis,
+						trace: getActiveTraceSession(),
+						har: getHarState(),
+						sessionArtifactDir: sessionDir,
+					}, null, 2)),
+					pages: await deps.writeArtifactFile(path.join(bundleDir, "pages.json"), JSON.stringify(pages, null, 2)),
+					accessibility: await deps.writeArtifactFile(path.join(bundleDir, "accessibility.md"), accessibility.snapshot),
+				};
+				return {
+					content: [{ type: "text", text: `Debug bundle written: ${bundleDir}\n${sessionSummary.summary}\nFailure hypothesis: ${failureHypothesis}` }],
+					details: {
+						bundleDir,
+						artifacts,
+						accessibilityScope: accessibility.scope,
+						accessibilitySource: accessibility.source,
+						counts: {
+							console: consoleLogs.length,
+							network: networkLogs.length,
+							dialog: dialogLogs.length,
+							actions: timeline.count,
+							pages: pages.length,
+						},
+						elapsedMs: Date.now() - startedAt,
+						summary: sessionSummary,
+						failureHypothesis,
+						...deps.getSessionArtifactMetadata(),
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Debug bundle failed: ${err.message}` }],
+					details: { error: err.message, ...deps.getSessionArtifactMetadata() },
+					isError: true,
+				};
+			}
+		},
+	});
+}

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

@@ -0,0 +1,247 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@gsd/pi-ai";
+import {
+	validateWaitParams,
+	createRegionStableScript,
+	parseThreshold,
+	includesNeedle,
+} from "../core.js";
+import type { ToolDeps } from "../state.js";
+import {
+	getConsoleLogs,
+} from "../state.js";
+
+export function registerWaitTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "browser_wait_for",
+		label: "Browser Wait For",
+		description:
+			"Wait for a condition before continuing. Use after actions that trigger async updates — data fetches, route changes, animations, loading spinners. Choose the appropriate condition: 'selector_visible' waits for an element to appear, 'selector_hidden' waits for it to disappear, 'url_contains' waits for the URL to match, 'network_idle' waits for all network requests to finish, 'delay' waits a fixed number of milliseconds, 'text_visible' waits for text to appear in the page body, 'text_hidden' waits for text to disappear from the page body, 'request_completed' waits for a network response whose URL contains the given substring, 'console_message' waits for a console log message containing the given substring, 'element_count' waits for the number of elements matching the CSS selector in 'value' to satisfy the 'threshold' expression (e.g. '>=3', '==0', '<5'), 'region_stable' waits for the DOM region matching the CSS selector in 'value' to stop changing.",
+		parameters: Type.Object({
+			condition: StringEnum([
+				"selector_visible",
+				"selector_hidden",
+				"url_contains",
+				"network_idle",
+				"delay",
+				"text_visible",
+				"text_hidden",
+				"request_completed",
+				"console_message",
+				"element_count",
+				"region_stable",
+			] as const),
+			value: Type.Optional(
+				Type.String({
+					description:
+						"For selector_visible/selector_hidden/element_count/region_stable: CSS selector. For url_contains/request_completed: URL substring. For text_visible/text_hidden/console_message: text substring. For delay: milliseconds as a string (e.g. '1000'). Not used for network_idle.",
+				})
+			),
+			threshold: Type.Optional(
+				Type.String({
+					description:
+						"Threshold expression for element_count (e.g. '>=3', '==0', '<5', or bare '3' which defaults to >=). Only used with element_count condition.",
+				})
+			),
+			timeout: Type.Optional(
+				Type.Number({
+					description: "Maximum milliseconds to wait before failing (default: 10000)",
+				})
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				const target = deps.getActiveTarget();
+				const timeout = params.timeout ?? 10000;
+
+				const validation = validateWaitParams({ condition: params.condition, value: params.value, threshold: (params as any).threshold });
+				if (validation) {
+					return {
+						content: [{ type: "text", text: validation.error }],
+						details: { error: validation.error, condition: params.condition },
+						isError: true,
+					};
+				}
+
+				switch (params.condition) {
+					case "selector_visible": {
+						if (!params.value) {
+							return {
+								content: [{ type: "text", text: "selector_visible requires a value (CSS selector)" }],
+								details: {},
+								isError: true,
+							};
+						}
+						await target.waitForSelector(params.value, { state: "visible", timeout });
+						return {
+							content: [{ type: "text", text: `Element "${params.value}" is now visible` }],
+							details: { condition: params.condition, value: params.value },
+						};
+					}
+
+					case "selector_hidden": {
+						if (!params.value) {
+							return {
+								content: [{ type: "text", text: "selector_hidden requires a value (CSS selector)" }],
+								details: {},
+								isError: true,
+							};
+						}
+						await target.waitForSelector(params.value, { state: "hidden", timeout });
+						return {
+							content: [{ type: "text", text: `Element "${params.value}" is now hidden` }],
+							details: { condition: params.condition, value: params.value },
+						};
+					}
+
+					case "url_contains": {
+						if (!params.value) {
+							return {
+								content: [{ type: "text", text: "url_contains requires a value (URL substring)" }],
+								details: {},
+								isError: true,
+							};
+						}
+						await p.waitForURL((url) => url.toString().includes(params.value!), { timeout });
+						return {
+							content: [{ type: "text", text: `URL now contains "${params.value}". Current URL: ${p.url()}` }],
+							details: { condition: params.condition, value: params.value, url: p.url() },
+						};
+					}
+
+					case "network_idle": {
+						await p.waitForLoadState("networkidle", { timeout });
+						return {
+							content: [{ type: "text", text: "Network is idle" }],
+							details: { condition: params.condition },
+						};
+					}
+
+					case "delay": {
+						const ms = parseInt(params.value ?? "1000", 10);
+						if (isNaN(ms)) {
+							return {
+								content: [{ type: "text", text: "delay requires a numeric value (milliseconds)" }],
+								details: {},
+								isError: true,
+							};
+						}
+						await new Promise((resolve) => setTimeout(resolve, ms));
+						return {
+							content: [{ type: "text", text: `Waited ${ms}ms` }],
+							details: { condition: params.condition, ms },
+						};
+					}
+
+					case "text_visible": {
+						await target.waitForFunction(
+							(needle: string) => {
+								const body = document.body?.innerText ?? "";
+								return body.toLowerCase().includes(needle.toLowerCase());
+							},
+							params.value!,
+							{ timeout }
+						);
+						return {
+							content: [{ type: "text", text: `Text "${params.value}" is now visible on the page` }],
+							details: { condition: params.condition, value: params.value },
+						};
+					}
+
+					case "text_hidden": {
+						await target.waitForFunction(
+							(needle: string) => {
+								const body = document.body?.innerText ?? "";
+								return !body.toLowerCase().includes(needle.toLowerCase());
+							},
+							params.value!,
+							{ timeout }
+						);
+						return {
+							content: [{ type: "text", text: `Text "${params.value}" is no longer visible on the page` }],
+							details: { condition: params.condition, value: params.value },
+						};
+					}
+
+					case "request_completed": {
+						const response = await deps.getActivePage().waitForResponse(
+							(resp) => resp.url().includes(params.value!),
+							{ timeout }
+						);
+						return {
+							content: [{ type: "text", text: `Request completed: ${response.url()} (status ${response.status()})` }],
+							details: { condition: params.condition, value: params.value, url: response.url(), status: response.status() },
+						};
+					}
+
+					case "console_message": {
+						const needle = params.value!;
+						const startTime = Date.now();
+						while (Date.now() - startTime < timeout) {
+							const match = getConsoleLogs().find((entry) => includesNeedle(entry.text, needle));
+							if (match) {
+								return {
+									content: [{ type: "text", text: `Console message matching "${needle}" found: "${match.text}"` }],
+									details: { condition: params.condition, value: needle, matchedText: match.text, matchedType: match.type },
+								};
+							}
+							await new Promise((resolve) => setTimeout(resolve, 100));
+						}
+						throw new Error(`Timed out waiting for console message matching "${needle}" (${timeout}ms)`);
+					}
+
+					case "element_count": {
+						const threshold = parseThreshold((params as any).threshold ?? ">=1");
+						if (!threshold) {
+							return {
+								content: [{ type: "text", text: `element_count threshold is malformed: "${(params as any).threshold}"` }],
+								details: { error: "malformed threshold", condition: params.condition },
+								isError: true,
+							};
+						}
+						const selector = params.value!;
+						const op = threshold.op;
+						const n = threshold.n;
+						await target.waitForFunction(
+							({ selector, op, n }: { selector: string; op: string; n: number }) => {
+								const count = document.querySelectorAll(selector).length;
+								switch (op) {
+									case ">=": return count >= n;
+									case "<=": return count <= n;
+									case "==": return count === n;
+									case ">": return count > n;
+									case "<": return count < n;
+									default: return false;
+								}
+							},
+							{ selector, op, n },
+							{ timeout }
+						);
+						return {
+							content: [{ type: "text", text: `Element count for "${selector}" satisfies ${op}${n}` }],
+							details: { condition: params.condition, value: selector, threshold: `${op}${n}` },
+						};
+					}
+
+					case "region_stable": {
+						const script = createRegionStableScript(params.value!);
+						await target.waitForFunction(script, undefined, { timeout, polling: 200 });
+						return {
+							content: [{ type: "text", text: `Region "${params.value}" is now stable` }],
+							details: { condition: params.condition, value: params.value },
+						};
+					}
+				}
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Wait failed: ${err.message}` }],
+					details: { error: err.message, condition: params.condition, value: params.value },
+					isError: true,
+				};
+			}
+		},
+	});
+}