gsd-pi 2.22.0 → 2.23.0

package/src/resources/extensions/browser-tools/tools/state-persistence.ts

@@ -0,0 +1,202 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+/**
+ * State persistence tools — save/restore cookies, localStorage, sessionStorage.
+ */
+
+const STATE_DIR = ".gsd/browser-state";
+
+export function registerStatePersistenceTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	// -------------------------------------------------------------------------
+	// browser_save_state
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_save_state",
+		label: "Browser Save State",
+		description:
+			"Save cookies, localStorage, and sessionStorage to disk so authenticated sessions survive browser restarts. " +
+			"State files are written to .gsd/browser-state/ and should be gitignored (may contain auth tokens). " +
+			"Never displays secret values in output.",
+		parameters: Type.Object({
+			name: Type.Optional(
+				Type.String({ description: "Name for the state file (default: 'default'). Used as the filename stem." }),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { context: ctx, page: p } = await deps.ensureBrowser();
+				const name = deps.sanitizeArtifactName(params.name ?? "default", "default");
+
+				const { mkdir, writeFile } = await import("node:fs/promises");
+				const path = await import("node:path");
+				const stateDir = path.resolve(process.cwd(), STATE_DIR);
+				await mkdir(stateDir, { recursive: true });
+
+				// 1. Playwright storageState: cookies + localStorage
+				const storageState = await ctx.storageState();
+
+				// 2. sessionStorage: must be extracted per-origin via page.evaluate
+				const sessionStorageData: Record<string, Record<string, string>> = {};
+				try {
+					const origin = new URL(p.url()).origin;
+					const ssData = await p.evaluate(() => {
+						const data: Record<string, string> = {};
+						for (let i = 0; i < sessionStorage.length; i++) {
+							const key = sessionStorage.key(i);
+							if (key) data[key] = sessionStorage.getItem(key) ?? "";
+						}
+						return data;
+					});
+					if (Object.keys(ssData).length > 0) {
+						sessionStorageData[origin] = ssData;
+					}
+				} catch {
+					// Page may not have a valid origin (about:blank, etc.)
+				}
+
+				const combined = {
+					storageState,
+					sessionStorage: sessionStorageData,
+					savedAt: new Date().toISOString(),
+					url: p.url(),
+				};
+
+				const filePath = path.join(stateDir, `${name}.json`);
+				await writeFile(filePath, JSON.stringify(combined, null, 2));
+
+				// Ensure .gitignore covers the state dir
+				const gitignorePath = path.resolve(process.cwd(), STATE_DIR, ".gitignore");
+				await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => {});
+
+				const cookieCount = storageState.cookies?.length ?? 0;
+				const localStorageOrigins = storageState.origins?.length ?? 0;
+				const sessionStorageOrigins = Object.keys(sessionStorageData).length;
+
+				return {
+					content: [{
+						type: "text",
+						text: `State saved: ${filePath}\nCookies: ${cookieCount}\nlocalStorage origins: ${localStorageOrigins}\nsessionStorage origins: ${sessionStorageOrigins}`,
+					}],
+					details: {
+						path: filePath,
+						cookieCount,
+						localStorageOrigins,
+						sessionStorageOrigins,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Save state failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_restore_state
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_restore_state",
+		label: "Browser Restore State",
+		description:
+			"Restore cookies, localStorage, and sessionStorage from a previously saved state file. " +
+			"Injects cookies via context.addCookies() and storage via page.evaluate(). " +
+			"For full fidelity, restore before navigating to the target site.",
+		parameters: Type.Object({
+			name: Type.Optional(
+				Type.String({ description: "Name of the state file to restore (default: 'default')." }),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { context: ctx, page: p } = await deps.ensureBrowser();
+				const name = deps.sanitizeArtifactName(params.name ?? "default", "default");
+
+				const { readFile } = await import("node:fs/promises");
+				const path = await import("node:path");
+				const filePath = path.join(process.cwd(), STATE_DIR, `${name}.json`);
+
+				let raw: string;
+				try {
+					raw = await readFile(filePath, "utf-8");
+				} catch {
+					return {
+						content: [{ type: "text", text: `State file not found: ${filePath}` }],
+						details: { error: "file_not_found", path: filePath },
+						isError: true,
+					};
+				}
+
+				const combined = JSON.parse(raw);
+				const storageState = combined.storageState;
+				const sessionStorageData: Record<string, Record<string, string>> = combined.sessionStorage ?? {};
+
+				// 1. Restore cookies
+				let cookieCount = 0;
+				if (storageState?.cookies?.length) {
+					await ctx.addCookies(storageState.cookies);
+					cookieCount = storageState.cookies.length;
+				}
+
+				// 2. Restore localStorage via page.evaluate
+				let localStorageOrigins = 0;
+				if (storageState?.origins?.length) {
+					for (const origin of storageState.origins) {
+						try {
+							await p.evaluate((items: Array<{ name: string; value: string }>) => {
+								for (const { name, value } of items) {
+									localStorage.setItem(name, value);
+								}
+							}, origin.localStorage ?? []);
+							localStorageOrigins++;
+						} catch {
+							// Origin mismatch — localStorage can only be set on matching origin
+						}
+					}
+				}
+
+				// 3. Restore sessionStorage via page.evaluate
+				let sessionStorageOrigins = 0;
+				for (const [_origin, data] of Object.entries(sessionStorageData)) {
+					try {
+						await p.evaluate((items: Record<string, string>) => {
+							for (const [key, value] of Object.entries(items)) {
+								sessionStorage.setItem(key, value);
+							}
+						}, data);
+						sessionStorageOrigins++;
+					} catch {
+						// Origin mismatch
+					}
+				}
+
+				return {
+					content: [{
+						type: "text",
+						text: `State restored from: ${filePath}\nCookies: ${cookieCount}\nlocalStorage origins: ${localStorageOrigins}\nsessionStorage origins: ${sessionStorageOrigins}\nSaved at: ${combined.savedAt ?? "unknown"}`,
+					}],
+					details: {
+						path: filePath,
+						cookieCount,
+						localStorageOrigins,
+						sessionStorageOrigins,
+						savedAt: combined.savedAt,
+						savedUrl: combined.url,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Restore state failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}

package/src/resources/extensions/browser-tools/tools/visual-diff.ts

@@ -0,0 +1,209 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+/**
+ * Visual regression diffing — compare current page screenshot against a stored baseline.
+ */
+
+const BASELINE_DIR = ".gsd/browser-baselines";
+
+export function registerVisualDiffTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "browser_visual_diff",
+		label: "Browser Visual Diff",
+		description:
+			"Compare current page screenshot against a stored baseline pixel-by-pixel. " +
+			"Returns similarity score (0–1), diff pixel count, and optionally generates a diff image highlighting changes. " +
+			"On first run with no baseline, saves the current screenshot as the baseline. " +
+			"Baselines are stored in .gsd/browser-baselines/ (gitignored, environment-specific).",
+		parameters: Type.Object({
+			name: Type.Optional(
+				Type.String({
+					description:
+						"Baseline name (default: auto-generated from URL + viewport). " +
+						"Use consistent names to compare the same view across runs.",
+				}),
+			),
+			selector: Type.Optional(
+				Type.String({
+					description: "CSS selector to scope comparison to a specific element instead of full viewport.",
+				}),
+			),
+			threshold: Type.Optional(
+				Type.Number({
+					description:
+						"Pixel matching threshold 0–1 (default: 0.1). " +
+						"Higher values are more tolerant of anti-aliasing and rendering differences.",
+				}),
+			),
+			updateBaseline: Type.Optional(
+				Type.Boolean({
+					description: "If true, overwrite the existing baseline with the current screenshot (default: false).",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				const { mkdir, readFile, writeFile } = await import("node:fs/promises");
+				const pathMod = await import("node:path");
+
+				const baselineDir = pathMod.resolve(process.cwd(), BASELINE_DIR);
+				await mkdir(baselineDir, { recursive: true });
+
+				// Ensure .gitignore
+				const gitignorePath = pathMod.join(baselineDir, ".gitignore");
+				await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => {});
+
+				// Generate baseline name
+				const url = p.url();
+				const viewport = p.viewportSize();
+				const vpSuffix = viewport ? `${viewport.width}x${viewport.height}` : "unknown";
+				const autoName = deps.sanitizeArtifactName(
+					`${new URL(url).pathname.replace(/\//g, "-")}-${vpSuffix}`,
+					`baseline-${vpSuffix}`,
+				);
+				const name = deps.sanitizeArtifactName(params.name ?? autoName, autoName);
+
+				const baselinePath = pathMod.join(baselineDir, `${name}.png`);
+				const diffPath = pathMod.join(baselineDir, `${name}-diff.png`);
+
+				// Capture current screenshot as PNG (needed for pixel comparison)
+				let currentBuffer: Buffer;
+				if (params.selector) {
+					const locator = p.locator(params.selector).first();
+					currentBuffer = await locator.screenshot({ type: "png" });
+				} else {
+					currentBuffer = await p.screenshot({ type: "png", fullPage: false });
+				}
+
+				// Check if baseline exists
+				let baselineBuffer: Buffer | null = null;
+				try {
+					baselineBuffer = await readFile(baselinePath) as Buffer;
+				} catch {
+					// No baseline yet
+				}
+
+				if (!baselineBuffer || params.updateBaseline) {
+					// Save as new baseline
+					await writeFile(baselinePath, currentBuffer);
+					return {
+						content: [{
+							type: "text",
+							text: baselineBuffer
+								? `Baseline updated: ${baselinePath}\nSize: ${(currentBuffer.length / 1024).toFixed(1)} KB`
+								: `Baseline created (first run): ${baselinePath}\nSize: ${(currentBuffer.length / 1024).toFixed(1)} KB\nRe-run to compare against this baseline.`,
+						}],
+						details: {
+							baselinePath,
+							baselineCreated: !baselineBuffer,
+							baselineUpdated: !!baselineBuffer,
+							sizeBytes: currentBuffer.length,
+						},
+					};
+				}
+
+				// Perform pixel comparison using sharp for PNG decoding
+				const sharp = (await import("sharp")).default;
+
+				const baselineMeta = await sharp(baselineBuffer).metadata();
+				const currentMeta = await sharp(currentBuffer).metadata();
+
+				const bWidth = baselineMeta.width ?? 0;
+				const bHeight = baselineMeta.height ?? 0;
+				const cWidth = currentMeta.width ?? 0;
+				const cHeight = currentMeta.height ?? 0;
+
+				// If dimensions differ, report mismatch
+				if (bWidth !== cWidth || bHeight !== cHeight) {
+					return {
+						content: [{
+							type: "text",
+							text: `Dimension mismatch: baseline is ${bWidth}x${bHeight}, current is ${cWidth}x${cHeight}. Cannot compare.\nUse updateBaseline: true to reset.`,
+						}],
+						details: {
+							match: false,
+							dimensionMismatch: true,
+							baselineDimensions: { width: bWidth, height: bHeight },
+							currentDimensions: { width: cWidth, height: cHeight },
+						},
+					};
+				}
+
+				// Extract raw RGBA pixel data
+				const baselineRaw = await sharp(baselineBuffer).ensureAlpha().raw().toBuffer();
+				const currentRaw = await sharp(currentBuffer).ensureAlpha().raw().toBuffer();
+
+				const width = bWidth;
+				const height = bHeight;
+				const totalPixels = width * height;
+				const threshold = params.threshold ?? 0.1;
+
+				// Simple pixel-by-pixel comparison (avoiding pixelmatch dependency)
+				const diffData = Buffer.alloc(width * height * 4);
+				let diffPixels = 0;
+				const thresholdSq = threshold * threshold * 255 * 255 * 3;
+
+				for (let i = 0; i < totalPixels; i++) {
+					const offset = i * 4;
+					const dr = baselineRaw[offset] - currentRaw[offset];
+					const dg = baselineRaw[offset + 1] - currentRaw[offset + 1];
+					const db = baselineRaw[offset + 2] - currentRaw[offset + 2];
+					const distSq = dr * dr + dg * dg + db * db;
+
+					if (distSq > thresholdSq) {
+						diffPixels++;
+						// Mark diff pixels as red
+						diffData[offset] = 255;     // R
+						diffData[offset + 1] = 0;   // G
+						diffData[offset + 2] = 0;   // B
+						diffData[offset + 3] = 255; // A
+					} else {
+						// Dim unchanged pixels
+						diffData[offset] = currentRaw[offset] >> 1;
+						diffData[offset + 1] = currentRaw[offset + 1] >> 1;
+						diffData[offset + 2] = currentRaw[offset + 2] >> 1;
+						diffData[offset + 3] = 255;
+					}
+				}
+
+				const similarity = 1 - (diffPixels / totalPixels);
+				const match = diffPixels === 0;
+
+				// Save diff image
+				await sharp(diffData, { raw: { width, height, channels: 4 } })
+					.png()
+					.toFile(diffPath);
+
+				return {
+					content: [{
+						type: "text",
+						text: match
+							? `Visual diff: MATCH (100% similar)\nBaseline: ${baselinePath}`
+							: `Visual diff: ${(similarity * 100).toFixed(2)}% similar\nDiff pixels: ${diffPixels} of ${totalPixels} (${((diffPixels / totalPixels) * 100).toFixed(2)}%)\nDiff image: ${diffPath}\nBaseline: ${baselinePath}`,
+					}],
+					details: {
+						match,
+						similarity,
+						diffPixels,
+						totalPixels,
+						diffPercentage: (diffPixels / totalPixels) * 100,
+						dimensions: { width, height },
+						baselinePath,
+						diffImagePath: match ? undefined : diffPath,
+						threshold,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Visual diff failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}

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

@@ -0,0 +1,104 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+/**
+ * Region zoom / high-res capture — capture and upscale specific page regions.
+ */
+
+export function registerZoomTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "browser_zoom_region",
+		label: "Browser Zoom Region",
+		description:
+			"Capture and optionally upscale a specific rectangular region of the page for detailed inspection. " +
+			"Useful for dense UIs where full-page screenshots have text too small to read. " +
+			"Returns the region as an inline image, same as browser_screenshot.",
+		parameters: Type.Object({
+			x: Type.Number({ description: "Left coordinate of the region in CSS pixels." }),
+			y: Type.Number({ description: "Top coordinate of the region in CSS pixels." }),
+			width: Type.Number({ description: "Width of the region in CSS pixels." }),
+			height: Type.Number({ description: "Height of the region in CSS pixels." }),
+			scale: Type.Optional(
+				Type.Number({
+					description: "Upscale factor (default: 2). Use 1 for native resolution, 2-4 for zoomed detail.",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				const { x, y, width, height } = params;
+				const scale = params.scale ?? 2;
+
+				// Validate dimensions
+				if (width <= 0 || height <= 0) {
+					return {
+						content: [{ type: "text", text: "Width and height must be positive." }],
+						details: { error: "invalid_dimensions" },
+						isError: true,
+					};
+				}
+
+				// Capture the region using Playwright's clip option
+				const regionBuffer = await p.screenshot({
+					type: "png",
+					clip: { x, y, width, height },
+				});
+
+				let outputBuffer: Buffer = regionBuffer;
+				let outputMime = "image/png";
+
+				// Upscale if scale > 1
+				if (scale > 1) {
+					const sharp = (await import("sharp")).default;
+					const targetWidth = Math.round(width * scale);
+					const targetHeight = Math.round(height * scale);
+
+					outputBuffer = await sharp(regionBuffer)
+						.resize(targetWidth, targetHeight, {
+							kernel: "lanczos3",
+							fit: "fill",
+						})
+						.png()
+						.toBuffer();
+				}
+
+				const base64Data = outputBuffer.toString("base64");
+				const title = await p.title();
+				const url = p.url();
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Region capture: ${width}x${height} at (${x},${y})${scale > 1 ? ` upscaled ${scale}x to ${Math.round(width * scale)}x${Math.round(height * scale)}` : ""}\nPage: ${title}\nURL: ${url}`,
+						},
+						{
+							type: "image",
+							data: base64Data,
+							mimeType: outputMime,
+						},
+					],
+					details: {
+						region: { x, y, width, height },
+						scale,
+						outputDimensions: {
+							width: Math.round(width * scale),
+							height: Math.round(height * scale),
+						},
+						title,
+						url,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Region zoom failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}

package/src/resources/extensions/gsd/auto-dashboard.ts

@@ -41,6 +41,8 @@ export interface AutoDashboardData {
   profileDowngraded?: boolean;
   /** Number of pending captures awaiting triage (0 if none or file missing) */
   pendingCaptureCount: number;
+  /** Cross-process: another auto-mode session detected via auto.lock (PID, startedAt) */
+  remoteSession?: { pid: number; startedAt: string; unitType: string; unitId: string };
 }
 
 // ─── Unit Description Helpers ─────────────────────────────────────────────────

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -130,6 +130,16 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   if (!absPath) return unitType === "replan-slice";
   if (!existsSync(absPath)) return false;
 
+  // plan-slice must produce a plan with actual task entries, not just a scaffold.
+  // The plan file may exist from a prior discussion/context step with only headings
+  // but no tasks. Without this check the artifact is considered "complete" and the
+  // unit gets skipped — but deriveState still returns phase:"planning" because the
+  // plan has no tasks, creating an infinite skip loop (#699).
+  if (unitType === "plan-slice") {
+    const planContent = readFileSync(absPath, "utf-8");
+    if (!/^- \[[xX ]\] \*\*T\d+:/m.test(planContent)) return false;
+  }
+
   // execute-task must also have its checkbox marked [x] in the slice plan
   if (unitType === "execute-task") {
     const parts = unitId.split("/");