gsd-pi 2.22.0 → 2.24.0

package/dist/resources/extensions/browser-tools/tests/browser-tools-unit.test.cjs

@@ -612,3 +612,28 @@ describe("constrainScreenshot", () => {
 		assert.equal(meta.height, 1568);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// browser_save_pdf — tool registration
+// ---------------------------------------------------------------------------
+
+describe("browser_save_pdf tool registration", () => {
+	it("registerPdfTools exports a function", () => {
+		const { registerPdfTools } = jiti("../tools/pdf.ts");
+		assert.equal(typeof registerPdfTools, "function", "registerPdfTools should be a function");
+	});
+
+	it("tool can be registered with a mock pi", () => {
+		const { registerPdfTools } = jiti("../tools/pdf.ts");
+		const registeredTools = [];
+		const mockPi = {
+			registerTool: (tool) => registeredTools.push(tool),
+		};
+		const mockDeps = {};
+		registerPdfTools(mockPi, mockDeps);
+		assert.equal(registeredTools.length, 1, "should register exactly 1 tool");
+		assert.equal(registeredTools[0].name, "browser_save_pdf", "tool name should be browser_save_pdf");
+		assert.ok(registeredTools[0].parameters, "tool should have parameters schema");
+		assert.equal(typeof registeredTools[0].execute, "function", "tool should have execute function");
+	});
+});

package/dist/resources/extensions/browser-tools/tools/action-cache.ts

@@ -0,0 +1,216 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+/**
+ * Action caching — cache semantic intent → selector mappings to skip LLM inference on repeat visits.
+ * Internal optimization that hooks into browser_find_best / browser_act.
+ */
+
+interface CacheEntry {
+	selector: string;
+	score: number;
+	url: string;
+	domHash: string;
+	timestamp: number;
+	hitCount: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+const MAX_CACHE_SIZE = 200;
+
+export function registerActionCacheTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	// -------------------------------------------------------------------------
+	// browser_action_cache
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_action_cache",
+		label: "Browser Action Cache",
+		description:
+			"Manage the action cache that maps page structure + intent → resolved selectors. " +
+			"Cache reduces token cost on repeat visits to same pages. " +
+			"Actions: 'stats' (show cache metrics), 'get' (lookup cached selector), " +
+			"'put' (store a selector mapping), 'clear' (flush cache).",
+		parameters: Type.Object({
+			action: Type.String({
+				description: "Cache action: 'stats', 'get', 'put', or 'clear'.",
+			}),
+			intent: Type.Optional(
+				Type.String({ description: "Semantic intent key (for get/put). E.g., 'submit_form', 'close_dialog'." }),
+			),
+			selector: Type.Optional(
+				Type.String({ description: "CSS selector to cache (for put)." }),
+			),
+			score: Type.Optional(
+				Type.Number({ description: "Confidence score 0–1 for the cached selector (for put)." }),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				const url = p.url();
+
+				switch (params.action) {
+					case "stats": {
+						const entries = [...cache.values()];
+						const totalHits = entries.reduce((sum, e) => sum + e.hitCount, 0);
+						return {
+							content: [{
+								type: "text",
+								text: `Action cache: ${cache.size} entries, ${totalHits} total hits\nMax size: ${MAX_CACHE_SIZE}`,
+							}],
+							details: {
+								size: cache.size,
+								maxSize: MAX_CACHE_SIZE,
+								totalHits,
+								entries: entries.map((e) => ({
+									url: e.url,
+									selector: e.selector,
+									hitCount: e.hitCount,
+									score: e.score,
+								})),
+							},
+						};
+					}
+
+					case "get": {
+						if (!params.intent) {
+							return {
+								content: [{ type: "text", text: "Intent parameter required for 'get' action." }],
+								details: { error: "missing_intent" },
+								isError: true,
+							};
+						}
+
+						const domHash = await computeDomHash(p);
+						const key = buildCacheKey(url, domHash, params.intent);
+						const entry = cache.get(key);
+
+						if (!entry) {
+							return {
+								content: [{ type: "text", text: `Cache miss for intent "${params.intent}" on ${url}` }],
+								details: { hit: false, intent: params.intent, url },
+							};
+						}
+
+						// Validate the cached selector still exists
+						const exists = await p.locator(entry.selector).first().isVisible().catch(() => false);
+						if (!exists) {
+							cache.delete(key);
+							return {
+								content: [{ type: "text", text: `Cache entry stale (selector no longer visible): ${entry.selector}` }],
+								details: { hit: false, stale: true, selector: entry.selector },
+							};
+						}
+
+						entry.hitCount++;
+						return {
+							content: [{
+								type: "text",
+								text: `Cache hit: "${params.intent}" → ${entry.selector} (score: ${entry.score}, hits: ${entry.hitCount})`,
+							}],
+							details: { hit: true, ...entry },
+						};
+					}
+
+					case "put": {
+						if (!params.intent || !params.selector) {
+							return {
+								content: [{ type: "text", text: "Intent and selector parameters required for 'put' action." }],
+								details: { error: "missing_params" },
+								isError: true,
+							};
+						}
+
+						const domHash = await computeDomHash(p);
+						const key = buildCacheKey(url, domHash, params.intent);
+
+						// Evict oldest entries if at capacity
+						if (cache.size >= MAX_CACHE_SIZE && !cache.has(key)) {
+							const oldestKey = [...cache.entries()]
+								.sort(([, a], [, b]) => a.timestamp - b.timestamp)[0]?.[0];
+							if (oldestKey) cache.delete(oldestKey);
+						}
+
+						const entry: CacheEntry = {
+							selector: params.selector,
+							score: params.score ?? 1.0,
+							url,
+							domHash,
+							timestamp: Date.now(),
+							hitCount: 0,
+						};
+						cache.set(key, entry);
+
+						return {
+							content: [{
+								type: "text",
+								text: `Cached: "${params.intent}" → ${params.selector} (cache size: ${cache.size})`,
+							}],
+							details: { stored: true, key, ...entry, cacheSize: cache.size },
+						};
+					}
+
+					case "clear": {
+						const size = cache.size;
+						cache.clear();
+						return {
+							content: [{ type: "text", text: `Action cache cleared (${size} entries removed).` }],
+							details: { cleared: size },
+						};
+					}
+
+					default:
+						return {
+							content: [{ type: "text", text: `Unknown action: ${params.action}. Use 'stats', 'get', 'put', or 'clear'.` }],
+							details: { error: "unknown_action" },
+							isError: true,
+						};
+				}
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Action cache error: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}
+
+function buildCacheKey(url: string, domHash: string, intent: string): string {
+	// Normalize URL — strip hash and query params for broader matching
+	let normalized: string;
+	try {
+		const u = new URL(url);
+		normalized = `${u.origin}${u.pathname}`;
+	} catch {
+		normalized = url;
+	}
+	return `${normalized}|${domHash}|${intent}`;
+}
+
+async function computeDomHash(page: any): Promise<string> {
+	try {
+		return await page.evaluate(() => {
+			// Structural hash based on element count + tag distribution
+			const tags = new Map<string, number>();
+			const all = document.querySelectorAll("*");
+			for (const el of all) {
+				const tag = el.tagName;
+				tags.set(tag, (tags.get(tag) ?? 0) + 1);
+			}
+			const entries = [...tags.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+			const str = entries.map(([t, c]) => `${t}:${c}`).join("|");
+			// Simple hash
+			let h = 5381;
+			for (let i = 0; i < str.length; i++) {
+				h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+			}
+			return (h >>> 0).toString(16);
+		});
+	} catch {
+		return "unknown";
+	}
+}

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

@@ -0,0 +1,274 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+import { getActionTimeline } from "../state.js";
+
+/**
+ * Test code generation — transform recorded browser session into a Playwright test script.
+ */
+
+export function registerCodegenTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "browser_generate_test",
+		label: "Browser Generate Test",
+		description:
+			"Generate a runnable Playwright test script from the recorded action timeline. " +
+			"Transforms navigation, click, type, and assertion actions into standard Playwright test syntax. " +
+			"Uses stable selectors (role-based preferred). Writes the test file to a configurable path.",
+		parameters: Type.Object({
+			name: Type.Optional(
+				Type.String({ description: "Test name (used for describe/test block and filename). Default: 'recorded-session'." }),
+			),
+			outputPath: Type.Optional(
+				Type.String({
+					description:
+						"Output file path for the generated test. Default: writes to session artifacts directory. " +
+						"Use a path ending in .spec.ts for standard Playwright test convention.",
+				}),
+			),
+			includeAssertions: Type.Optional(
+				Type.Boolean({ description: "Include assertion steps from the timeline (default: true)." }),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				await deps.ensureBrowser();
+				const timeline = getActionTimeline();
+
+				if (timeline.entries.length === 0) {
+					return {
+						content: [{ type: "text", text: "No actions recorded in the current session. Interact with pages first, then generate a test." }],
+						details: { error: "no_actions" },
+						isError: true,
+					};
+				}
+
+				const testName = params.name ?? "recorded-session";
+				const includeAssertions = params.includeAssertions ?? true;
+
+				// Transform timeline entries into Playwright test code
+				const testLines: string[] = [];
+				const imports = new Set<string>();
+				imports.add("test");
+				imports.add("expect");
+
+				testLines.push(`test.describe('${escapeString(testName)}', () => {`);
+				testLines.push(`  test('recorded session', async ({ page }) => {`);
+
+				let lastUrl = "";
+				let actionCount = 0;
+
+				for (const entry of timeline.entries) {
+					if (entry.status === "error" && entry.tool !== "browser_assert") continue;
+
+					const params = parseParamsSummary(entry.paramsSummary);
+
+					switch (entry.tool) {
+						case "browser_navigate": {
+							const url = params.url;
+							if (url && url !== lastUrl) {
+								testLines.push(`    await page.goto(${quote(url)});`);
+								lastUrl = url;
+								actionCount++;
+							}
+							break;
+						}
+
+						case "browser_click": {
+							const selector = params.selector;
+							if (selector) {
+								testLines.push(`    await page.locator(${quote(selector)}).click();`);
+								actionCount++;
+							}
+							break;
+						}
+
+						case "browser_click_ref": {
+							// Refs are session-specific — add comment
+							testLines.push(`    // browser_click_ref: ${entry.paramsSummary} — replace with stable selector`);
+							actionCount++;
+							break;
+						}
+
+						case "browser_type": {
+							const selector = params.selector;
+							const text = params.text;
+							if (selector && text) {
+								testLines.push(`    await page.locator(${quote(selector)}).fill(${quote(text)});`);
+								actionCount++;
+							}
+							break;
+						}
+
+						case "browser_fill_ref": {
+							testLines.push(`    // browser_fill_ref: ${entry.paramsSummary} — replace with stable selector`);
+							actionCount++;
+							break;
+						}
+
+						case "browser_key_press": {
+							const key = params.key;
+							if (key) {
+								testLines.push(`    await page.keyboard.press(${quote(key)});`);
+								actionCount++;
+							}
+							break;
+						}
+
+						case "browser_select_option": {
+							const selector = params.selector;
+							const option = params.option;
+							if (selector && option) {
+								testLines.push(`    await page.locator(${quote(selector)}).selectOption(${quote(option)});`);
+								actionCount++;
+							}
+							break;
+						}
+
+						case "browser_set_checked": {
+							const selector = params.selector;
+							const checked = params.checked;
+							if (selector) {
+								testLines.push(`    await page.locator(${quote(selector)}).setChecked(${checked === "true"});`);
+								actionCount++;
+							}
+							break;
+						}
+
+						case "browser_hover": {
+							const selector = params.selector;
+							if (selector) {
+								testLines.push(`    await page.locator(${quote(selector)}).hover();`);
+								actionCount++;
+							}
+							break;
+						}
+
+						case "browser_wait_for": {
+							const condition = params.condition;
+							const value = params.value;
+							if (condition === "selector_visible" && value) {
+								testLines.push(`    await expect(page.locator(${quote(value)})).toBeVisible();`);
+								actionCount++;
+							} else if (condition === "text_visible" && value) {
+								testLines.push(`    await expect(page.locator('body')).toContainText(${quote(value)});`);
+								actionCount++;
+							} else if (condition === "url_contains" && value) {
+								testLines.push(`    await page.waitForURL(${quote(`**/*${value}*`)});`);
+								actionCount++;
+							} else if (condition === "network_idle") {
+								testLines.push(`    await page.waitForLoadState('networkidle');`);
+								actionCount++;
+							} else if (condition === "delay" && value) {
+								testLines.push(`    await page.waitForTimeout(${value});`);
+								actionCount++;
+							}
+							break;
+						}
+
+						case "browser_assert": {
+							if (!includeAssertions) break;
+							// The assertion details are in verificationSummary
+							if (entry.verificationSummary) {
+								testLines.push(`    // Assertion: ${entry.verificationSummary}`);
+							}
+							actionCount++;
+							break;
+						}
+
+						case "browser_scroll": {
+							const direction = params.direction;
+							const amount = params.amount ?? "300";
+							const delta = direction === "up" ? `-${amount}` : amount;
+							testLines.push(`    await page.mouse.wheel(0, ${delta});`);
+							actionCount++;
+							break;
+						}
+
+						case "browser_set_viewport": {
+							const width = params.width;
+							const height = params.height;
+							if (width && height) {
+								testLines.push(`    await page.setViewportSize({ width: ${width}, height: ${height} });`);
+								actionCount++;
+							}
+							break;
+						}
+
+						default:
+							// Skip tools that don't map to Playwright test actions
+							break;
+					}
+				}
+
+				testLines.push(`  });`);
+				testLines.push(`});`);
+
+				const importLine = `import { ${[...imports].join(", ")} } from '@playwright/test';`;
+				const fullTest = `${importLine}\n\n${testLines.join("\n")}\n`;
+
+				// Write to file
+				let outputPath: string;
+				if (params.outputPath) {
+					outputPath = params.outputPath;
+				} else {
+					const safeName = deps.sanitizeArtifactName(testName, "recorded-session");
+					outputPath = deps.buildSessionArtifactPath(`${safeName}.spec.ts`);
+				}
+
+				await deps.ensureSessionArtifactDir();
+				const { path: writtenPath, bytes } = await deps.writeArtifactFile(outputPath, fullTest);
+
+				return {
+					content: [{
+						type: "text",
+						text: `Test generated: ${writtenPath}\nActions: ${actionCount}\nTimeline entries processed: ${timeline.entries.length}\n\n${fullTest}`,
+					}],
+					details: {
+						path: writtenPath,
+						bytes,
+						actionCount,
+						timelineEntries: timeline.entries.length,
+						testCode: fullTest,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Test generation failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}
+
+function escapeString(s: string): string {
+	return s.replace(/'/g, "\\'").replace(/\\/g, "\\\\");
+}
+
+function quote(s: string): string {
+	// Use single quotes for simple strings, backtick for those with quotes
+	if (!s.includes("'")) return `'${s}'`;
+	if (!s.includes("`")) return `\`${s}\``;
+	return `'${s.replace(/'/g, "\\'")}'`;
+}
+
+/**
+ * Parse the paramsSummary string back into key-value pairs.
+ * Format: key="value", key=value, key=[N], key={...}
+ */
+function parseParamsSummary(summary: string): Record<string, string> {
+	const result: Record<string, string> = {};
+	if (!summary) return result;
+
+	const regex = /(\w+)=(?:"([^"]*(?:\\"[^"]*)*)"|([^,\s]+))/g;
+	let match;
+	while ((match = regex.exec(summary)) !== null) {
+		const key = match[1];
+		const value = match[2] ?? match[3];
+		result[key] = value;
+	}
+	return result;
+}

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

@@ -0,0 +1,183 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+/**
+ * Device emulation tool — full device simulation using Playwright's built-in device descriptors.
+ */
+
+export function registerDeviceTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "browser_emulate_device",
+		label: "Browser Emulate Device",
+		description:
+			"Simulate a specific device by setting viewport, user agent, device scale factor, touch, and mobile flag. " +
+			"Uses Playwright's built-in device descriptors (~143 devices). Accepts fuzzy matching on device name. " +
+			"Note: Full emulation (user agent, isMobile) requires a context restart — the current page state will be lost. " +
+			"The tool recreates the context with the device profile applied.",
+		parameters: Type.Object({
+			device: Type.String({
+				description:
+					"Device name (e.g., 'iPhone 15', 'Pixel 7', 'iPad Pro 11'). " +
+					"Case-insensitive fuzzy matching. Use 'list' to see all available devices.",
+			}),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { chromium, devices } = await import("playwright");
+				const allDeviceNames = Object.keys(devices);
+
+				// Handle 'list' request
+				if (params.device.toLowerCase() === "list") {
+					// Group by base device name (remove landscape variants for cleaner display)
+					const baseNames = allDeviceNames.filter((n) => !n.endsWith(" landscape"));
+					return {
+						content: [{
+							type: "text",
+							text: `Available devices (${allDeviceNames.length} total, ${baseNames.length} base):\n${baseNames.join("\n")}`,
+						}],
+						details: { devices: baseNames, total: allDeviceNames.length },
+					};
+				}
+
+				// Fuzzy match device name
+				const needle = params.device.toLowerCase();
+				let exactMatch = allDeviceNames.find((n) => n.toLowerCase() === needle);
+				if (!exactMatch) {
+					// Try contains match
+					const containsMatches = allDeviceNames.filter((n) => n.toLowerCase().includes(needle));
+					if (containsMatches.length === 1) {
+						exactMatch = containsMatches[0];
+					} else if (containsMatches.length > 1) {
+						// Pick the shortest match (most specific)
+						containsMatches.sort((a, b) => a.length - b.length);
+						exactMatch = containsMatches[0];
+						const suggestions = containsMatches.slice(0, 5).join(", ");
+						// Continue with best match but mention alternatives
+					} else {
+						// No match at all — suggest closest
+						const suggestions = allDeviceNames
+							.map((n) => ({ name: n, score: fuzzyScore(needle, n.toLowerCase()) }))
+							.sort((a, b) => b.score - a.score)
+							.slice(0, 5)
+							.map((s) => s.name);
+
+						return {
+							content: [{
+								type: "text",
+								text: `No device matching "${params.device}". Did you mean:\n${suggestions.map((s) => `  - ${s}`).join("\n")}`,
+							}],
+							details: { error: "no_match", suggestions },
+							isError: true,
+						};
+					}
+				}
+
+				const deviceDescriptor = devices[exactMatch!];
+				if (!deviceDescriptor) {
+					return {
+						content: [{ type: "text", text: `Device descriptor not found for "${exactMatch}"` }],
+						details: { error: "descriptor_not_found" },
+						isError: true,
+					};
+				}
+
+				// Context restart required for full emulation.
+				// Save current URL to navigate back after restart.
+				const { page: currentPage, context: currentCtx } = await deps.ensureBrowser();
+				const currentUrl = currentPage.url();
+
+				// Close existing browser and relaunch with device profile
+				await deps.closeBrowser();
+
+				// Re-launch — ensureBrowser doesn't accept device params, so we do it manually.
+				// This is a one-off context creation with device emulation.
+				const needsHeadless = process.platform === "linux" && !process.env.DISPLAY;
+				const launchOptions: Record<string, unknown> = {
+					headless: needsHeadless || process.env.FORCE_HEADLESS === "true",
+				};
+				const customPath = process.env.BROWSER_PATH;
+				if (customPath) launchOptions.executablePath = customPath;
+
+				const browser = await chromium.launch(launchOptions);
+				const context = await browser.newContext({
+					...deviceDescriptor,
+				});
+
+				// Inject evaluate helpers
+				const { EVALUATE_HELPERS_SOURCE } = await import("../evaluate-helpers.js");
+				await context.addInitScript(EVALUATE_HELPERS_SOURCE);
+
+				// Wire up state
+				const {
+					setBrowser, setContext, pageRegistry, setSessionStartedAt,
+					setSessionArtifactDir, resetAllState,
+				} = await import("../state.js");
+				const { registryAddPage, registrySetActive } = await import("../core.js");
+
+				// Reset state for new session
+				resetAllState();
+				setBrowser(browser);
+				setContext(context);
+				setSessionStartedAt(Date.now());
+
+				const page = await context.newPage();
+				const entry = registryAddPage(pageRegistry, {
+					page,
+					title: "",
+					url: "about:blank",
+					opener: null,
+				});
+				registrySetActive(pageRegistry, entry.id);
+				deps.attachPageListeners(page, entry.id);
+
+				// Navigate back to previous URL if it wasn't about:blank
+				if (currentUrl && currentUrl !== "about:blank") {
+					await page.goto(currentUrl, { waitUntil: "domcontentloaded", timeout: 15000 }).catch(() => {});
+				}
+
+				const viewport = deviceDescriptor.viewport;
+				const vpText = viewport ? `${viewport.width}x${viewport.height}` : "unknown";
+
+				return {
+					content: [{
+						type: "text",
+						text: `Device emulation active: ${exactMatch}\nViewport: ${vpText}\nUser Agent: ${deviceDescriptor.userAgent?.slice(0, 80) ?? "default"}...\nMobile: ${deviceDescriptor.isMobile ?? false}\nTouch: ${deviceDescriptor.hasTouch ?? false}\nScale Factor: ${deviceDescriptor.deviceScaleFactor ?? 1}\n\nContext was restarted for full emulation. Page state was reset.`,
+					}],
+					details: {
+						device: exactMatch,
+						viewport: vpText,
+						isMobile: deviceDescriptor.isMobile ?? false,
+						hasTouch: deviceDescriptor.hasTouch ?? false,
+						deviceScaleFactor: deviceDescriptor.deviceScaleFactor ?? 1,
+						userAgent: deviceDescriptor.userAgent,
+						restoredUrl: currentUrl,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Device emulation failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}
+
+/**
+ * Simple fuzzy scoring — counts matching characters in order.
+ */
+function fuzzyScore(needle: string, haystack: string): number {
+	let score = 0;
+	let hi = 0;
+	for (let ni = 0; ni < needle.length && hi < haystack.length; ni++) {
+		const idx = haystack.indexOf(needle[ni], hi);
+		if (idx >= 0) {
+			score++;
+			hi = idx + 1;
+		}
+	}
+	return score / Math.max(needle.length, 1);
+}