gsd-pi 2.22.0 → 2.24.0

package/scripts/postinstall.js

@@ -1,125 +1,23 @@
 #!/usr/bin/env node
 
 import { exec as execCb } from 'child_process'
-import { createRequire } from 'module'
-import os from 'os'
 import { dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const require = createRequire(import.meta.url)
-const pkg = require(resolve(__dirname, '..', 'package.json'))
 const cwd = resolve(__dirname, '..')
-const shouldSkipBrowserDownload =
+const shouldSkip =
   process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1' ||
   process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === 'true'
 
-// ---------------------------------------------------------------------------
-// Async exec helper — captures stdout+stderr, never inherits to terminal
-// ---------------------------------------------------------------------------
-function run(cmd, options = {}) {
+function run(cmd) {
   return new Promise((resolve) => {
-    execCb(cmd, { cwd, ...options }, (error, stdout, stderr) => {
-      resolve({ ok: !error, stdout, stderr, error })
+    execCb(cmd, { cwd }, (error, stdout, stderr) => {
+      resolve({ ok: !error, stdout, stderr })
     })
   })
 }
 
-// ---------------------------------------------------------------------------
-// Redirect stdout → stderr so npm always shows postinstall output.
-// npm ≥7 suppresses stdout from lifecycle scripts by default; stderr is
-// always forwarded. Clack writes to process.stdout, so we reroute it.
-// ---------------------------------------------------------------------------
-process.stdout.write = process.stderr.write.bind(process.stderr)
-
-// ---------------------------------------------------------------------------
-// ASCII banner — printed before clack UI for brand recognition
-// ---------------------------------------------------------------------------
-const cyan    = '\x1b[36m'
-const dim     = '\x1b[2m'
-const reset   = '\x1b[0m'
-
-const banner =
-  '\n' +
-  cyan +
-  '   ██████╗ ███████╗██████╗ \n' +
-  '  ██╔════╝ ██╔════╝██╔══██╗\n' +
-  '  ██║  ███╗███████╗██║  ██║\n' +
-  '  ██║   ██║╚════██║██║  ██║\n' +
-  '  ╚██████╔╝███████║██████╔╝\n' +
-  '   ╚═════╝ ╚══════╝╚═════╝ ' +
-  reset + '\n' +
-  '\n' +
-  `  Get Shit Done ${dim}v${pkg.version}${reset}\n`
-
-// ---------------------------------------------------------------------------
-// Main — wrapped in async IIFE, with graceful fallback if clack fails
-// ---------------------------------------------------------------------------
-;(async () => {
-  process.stderr.write(banner)
-
-  let p, pc
-
-  try {
-    p = await import('@clack/prompts')
-    pc = (await import('picocolors')).default
-  } catch {
-    // Clack or picocolors unavailable — fall back to minimal output
-    process.stderr.write(`  Run gsd to get started.\n\n`)
-    if (!shouldSkipBrowserDownload) {
-      await run('npx playwright install chromium')
-    }
-    return
-  }
-
-  // --- Branded intro -------------------------------------------------------
-  p.intro('Setup')
-
-  const results = []
-  const s = p.spinner()
-
-  // --- Playwright browser --------------------------------------------------
-  // Avoid --with-deps: install scripts should not block on interactive sudo
-  // prompts. If Linux libs are missing, suggest the explicit follow-up.
-  s.start('Setting up browser tools…')
-  if (shouldSkipBrowserDownload) {
-    s.stop(pc.yellow('Browser tools skipped via PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD'))
-    results.push({
-      label: 'Browser tools skipped — run ' + pc.cyan('npx playwright install chromium') + ' later if needed',
-      ok: false,
-    })
-  } else {
-    const pwResult = await run('npx playwright install chromium')
-    if (pwResult.ok) {
-      s.stop('Browser tools ready')
-      results.push({ label: 'Browser tools ready', ok: true })
-    } else {
-      const output = `${pwResult.stdout ?? ''}${pwResult.stderr ?? ''}`
-      if (os.platform() === 'linux' && output.includes('Host system is missing dependencies to run browsers.')) {
-        s.stop(pc.yellow('Browser downloaded, missing Linux deps'))
-        results.push({
-          label: 'Run ' + pc.cyan('sudo npx playwright install-deps chromium') + ' to finish setup',
-          ok: false,
-        })
-      } else {
-        s.stop(pc.yellow('Browser tools — skipped (non-fatal)'))
-        results.push({
-          label: 'Browser tools unavailable — run ' + pc.cyan('npx playwright install chromium'),
-          ok: false,
-        })
-      }
-    }
-  }
-
-  // --- Summary note --------------------------------------------------------
-  const lines = results.map(
-    (r) => (r.ok ? pc.green('✓') : pc.yellow('⚠')) + ' ' + r.label
-  )
-  lines.push('')
-  lines.push('Run ' + pc.cyan('gsd') + ' to get started.')
-
-  p.note(lines.join('\n'), 'Installed')
-
-  // --- Outro ---------------------------------------------------------------
-  p.outro(pc.green('Done!'))
-})()
+if (!shouldSkip) {
+  await run('npx playwright install chromium')
+}

package/src/resources/extensions/bg-shell/output-formatter.ts

@@ -10,12 +10,19 @@ import {
 import type { BgProcess, OutputDigest, OutputLine, GetOutputOptions } from "./types.js";
 import {
 	ERROR_PATTERNS,
+	ERROR_PATTERN_UNION,
+	WARNING_PATTERN_UNION,
+	READINESS_PATTERN_UNION,
+	BUILD_COMPLETE_PATTERN_UNION,
+	TEST_RESULT_PATTERN_UNION,
 	WARNING_PATTERNS,
 	URL_PATTERN,
 	PORT_PATTERN,
+	PORT_PATTERN_SOURCE,
 	READINESS_PATTERNS,
 	BUILD_COMPLETE_PATTERNS,
 	TEST_RESULT_PATTERNS,
+	LINE_DEDUP_MAX,
 } from "./types.js";
 import { addEvent, pushAlert } from "./process-manager.js";
 import { transitionToReady } from "./readiness-detector.js";
@@ -24,8 +31,8 @@ import { formatUptime, formatTimeAgo } from "./utilities.js";
 // ── Output Analysis ────────────────────────────────────────────────────────
 
 export function analyzeLine(bg: BgProcess, line: string, stream: "stdout" | "stderr"): void {
-	// Error detection
-	if (ERROR_PATTERNS.some(p => p.test(line))) {
+	// Error detection — single union regex instead of .some(p => p.test(line))
+	if (ERROR_PATTERN_UNION.test(line)) {
 		bg.recentErrors.push(line.trim().slice(0, 200)); // Cap line length
 		if (bg.recentErrors.length > 50) bg.recentErrors.splice(0, bg.recentErrors.length - 50);
 
@@ -40,8 +47,8 @@ export function analyzeLine(bg: BgProcess, line: string, stream: "stdout" | "std
 		}
 	}
 
-	// Warning detection
-	if (WARNING_PATTERNS.some(p => p.test(line))) {
+	// Warning detection — single union regex
+	if (WARNING_PATTERN_UNION.test(line)) {
 		bg.recentWarnings.push(line.trim().slice(0, 200));
 		if (bg.recentWarnings.length > 50) bg.recentWarnings.splice(0, bg.recentWarnings.length - 50);
 	}
@@ -56,9 +63,10 @@ export function analyzeLine(bg: BgProcess, line: string, stream: "stdout" | "std
 		}
 	}
 
-	// Port extraction
+	// Port extraction — PORT_PATTERN has /g flag so must be re-created per call
+	// Use PORT_PATTERN_SOURCE (string) to avoid re-parsing the literal each time
+	const portRe = new RegExp(PORT_PATTERN_SOURCE, "gi");
 	let portMatch: RegExpExecArray | null;
-	const portRe = new RegExp(PORT_PATTERN.source, PORT_PATTERN.flags);
 	while ((portMatch = portRe.exec(line)) !== null) {
 		const port = parseInt(portMatch[1], 10);
 		if (port > 0 && port <= 65535 && !bg.ports.includes(port)) {
@@ -71,7 +79,7 @@ export function analyzeLine(bg: BgProcess, line: string, stream: "stdout" | "std
 		}
 	}
 
-	// Readiness detection
+	// Readiness detection — single union regex
 	if (bg.status === "starting") {
 		// Check custom ready pattern first
 		if (bg.readyPattern) {
@@ -83,14 +91,14 @@ export function analyzeLine(bg: BgProcess, line: string, stream: "stdout" | "std
 		}
 
 		// Check built-in readiness patterns
-		if (bg.status === "starting" && READINESS_PATTERNS.some(p => p.test(line))) {
+		if (bg.status === "starting" && READINESS_PATTERN_UNION.test(line)) {
 			transitionToReady(bg, `Readiness pattern matched: ${line.trim().slice(0, 100)}`);
 		}
 	}
 
 	// Recovery detection: if we were in error and see a success pattern
 	if (bg.status === "error") {
-		if (READINESS_PATTERNS.some(p => p.test(line)) || BUILD_COMPLETE_PATTERNS.some(p => p.test(line))) {
+		if (READINESS_PATTERN_UNION.test(line) || BUILD_COMPLETE_PATTERN_UNION.test(line)) {
 			bg.status = "ready";
 			bg.recentErrors = [];
 			addEvent(bg, { type: "recovered", detail: "Process recovered from error state" });
@@ -98,10 +106,22 @@ export function analyzeLine(bg: BgProcess, line: string, stream: "stdout" | "std
 		}
 	}
 
-	// Dedup tracking
+	// Dedup tracking — evict oldest entry when map exceeds LINE_DEDUP_MAX (LRU via Map insertion order)
 	bg.totalRawLines++;
 	const lineHash = line.trim().slice(0, 100);
-	bg.lineDedup.set(lineHash, (bg.lineDedup.get(lineHash) || 0) + 1);
+	const existing = bg.lineDedup.get(lineHash);
+	if (existing !== undefined) {
+		// Re-insert to update insertion order (move to tail = most recent)
+		bg.lineDedup.delete(lineHash);
+		bg.lineDedup.set(lineHash, existing + 1);
+	} else {
+		if (bg.lineDedup.size >= LINE_DEDUP_MAX) {
+			// Evict oldest entry (Map iteration order = insertion order = LRU at head)
+			const oldest = bg.lineDedup.keys().next().value;
+			if (oldest !== undefined) bg.lineDedup.delete(oldest);
+		}
+		bg.lineDedup.set(lineHash, 1);
+	}
 }
 
 // ── Digest Generation ──────────────────────────────────────────────────────
@@ -154,12 +174,12 @@ export function getHighlights(bg: BgProcess, maxLines: number = 15): string[] {
 	for (let i = 0; i < bg.output.length; i++) {
 		const entry = bg.output[i];
 		let score = 0;
-		if (ERROR_PATTERNS.some(p => p.test(entry.line))) score += 10;
-		if (WARNING_PATTERNS.some(p => p.test(entry.line))) score += 5;
+		if (ERROR_PATTERN_UNION.test(entry.line)) score += 10;
+		if (WARNING_PATTERN_UNION.test(entry.line)) score += 5;
 		if (URL_PATTERN.test(entry.line)) score += 3;
-		if (READINESS_PATTERNS.some(p => p.test(entry.line))) score += 8;
-		if (TEST_RESULT_PATTERNS.some(p => p.test(entry.line))) score += 7;
-		if (BUILD_COMPLETE_PATTERNS.some(p => p.test(entry.line))) score += 6;
+		if (READINESS_PATTERN_UNION.test(entry.line)) score += 8;
+		if (TEST_RESULT_PATTERN_UNION.test(entry.line)) score += 7;
+		if (BUILD_COMPLETE_PATTERN_UNION.test(entry.line)) score += 6;
 		// Boost recent lines so highlights favor fresh output over stale
 		if (i >= bg.output.length - 50) score += 2;
 		if (score > 0) {

package/src/resources/extensions/bg-shell/process-manager.ts

@@ -39,6 +39,8 @@ export function setPendingAlerts(alerts: string[]): void {
 
 export function addOutputLine(bg: BgProcess, stream: "stdout" | "stderr", line: string): void {
 	bg.output.push({ stream, line, ts: Date.now() });
+	if (stream === "stdout") bg.stdoutLineCount++;
+	else bg.stderrLineCount++;
 	if (bg.output.length > MAX_BUFFER_LINES) {
 		const excess = bg.output.length - MAX_BUFFER_LINES;
 		bg.output.splice(0, excess);
@@ -60,8 +62,6 @@ export function pushAlert(bg: BgProcess, message: string): void {
 }
 
 export function getInfo(p: BgProcess): BgProcessInfo {
-	const stdoutLines = p.output.filter(l => l.stream === "stdout").length;
-	const stderrLines = p.output.filter(l => l.stream === "stderr").length;
 	return {
 		id: p.id,
 		label: p.label,
@@ -72,8 +72,8 @@ export function getInfo(p: BgProcess): BgProcessInfo {
 		exitCode: p.exitCode,
 		signal: p.signal,
 		outputLines: p.output.length,
-		stdoutLines,
-		stderrLines,
+		stdoutLines: p.stdoutLineCount,
+		stderrLines: p.stderrLineCount,
 		status: p.status,
 		processType: p.processType,
 		ports: p.ports,
@@ -161,6 +161,8 @@ export function startProcess(opts: StartOptions): BgProcess {
 		commandHistory: [],
 		lineDedup: new Map(),
 		totalRawLines: 0,
+		stdoutLineCount: 0,
+		stderrLineCount: 0,
 		envKeys: Object.keys(opts.env || {}),
 		restartCount: 0,
 		startConfig: {

package/src/resources/extensions/bg-shell/types.ts

@@ -90,10 +90,14 @@ export interface BgProcess {
 	lastWarningCount: number;
 	/** Command history for shell-type sessions */
 	commandHistory: string[];
-	/** Dedup tracker: hash → count of repeated lines */
+	/** Dedup tracker: hash → count of repeated lines (capped at LINE_DEDUP_MAX entries) */
 	lineDedup: Map<string, number>;
 	/** Total raw lines (before dedup) for token savings calc */
 	totalRawLines: number;
+	/** Tracked stdout line count (incremented in addOutputLine, avoids O(n) filter) */
+	stdoutLineCount: number;
+	/** Tracked stderr line count (incremented in addOutputLine, avoids O(n) filter) */
+	stderrLineCount: number;
 	/** Env snapshot (keys only, no values for security) */
 	envKeys: string[];
 	/** Restart count */
@@ -163,6 +167,8 @@ export interface ProcessManifest {
 export const MAX_BUFFER_LINES = 5000;
 export const MAX_EVENTS = 200;
 export const DEAD_PROCESS_TTL = 10 * 60 * 1000;
+/** Maximum unique entries in the per-process lineDedup Map before LRU eviction. */
+export const LINE_DEDUP_MAX = 500;
 export const PORT_PROBE_TIMEOUT = 500;
 export const READY_POLL_INTERVAL = 250;
 export const DEFAULT_READY_TIMEOUT = 30000;
@@ -249,3 +255,29 @@ export const BUILD_COMPLETE_PATTERNS: RegExp[] = [
 	/webpack\s+\d+\.\d+/i,
 	/bundle\s+(?:is\s+)?ready/i,
 ];
+
+// ── Compiled union regexes (single-pass alternatives to .some(p => p.test(line))) ──
+// Built once at module load — eliminates per-line RegExp construction overhead.
+
+export const ERROR_PATTERN_UNION = new RegExp(
+	ERROR_PATTERNS.map(p => p.source).join("|"),
+	"i",
+);
+export const WARNING_PATTERN_UNION = new RegExp(
+	WARNING_PATTERNS.map(p => p.source).join("|"),
+	"i",
+);
+export const READINESS_PATTERN_UNION = new RegExp(
+	READINESS_PATTERNS.map(p => p.source).join("|"),
+	"i",
+);
+export const BUILD_COMPLETE_PATTERN_UNION = new RegExp(
+	BUILD_COMPLETE_PATTERNS.map(p => p.source).join("|"),
+	"i",
+);
+export const TEST_RESULT_PATTERN_UNION = new RegExp(
+	TEST_RESULT_PATTERNS.map(p => p.source).join("|"),
+	"i",
+);
+/** PORT_PATTERN compiled once for reuse in analyzeLine (needs exec, so must be re-created per call with /g) */
+export const PORT_PATTERN_SOURCE = PORT_PATTERN.source;

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

@@ -10,9 +10,11 @@ import sharp from "sharp";
 import type { CompactPageState, CompactSelectorState } from "./state.js";
 import { formatCompactStateSummary } from "./utils.js";
 
-// Anthropic API rejects images > 2000px in multi-image requests.
-// Cap at 1568px (recommended optimal size) to stay well within limits.
-const MAX_SCREENSHOT_DIM = 1568;
+// Anthropic vision: 1568px is the recommended optimal width. Height is capped
+// generously at 8000px so tall full-page screenshots remain readable rather
+// than being squished into a square constraint.
+const MAX_SCREENSHOT_WIDTH = 1568;
+const MAX_SCREENSHOT_HEIGHT = 8000;
 
 // ---------------------------------------------------------------------------
 // Compact page state capture
@@ -120,9 +122,10 @@ export async function postActionSummary(p: Page, target?: Page | Frame): Promise
 // ---------------------------------------------------------------------------
 
 /**
- * If either dimension of the image buffer exceeds MAX_SCREENSHOT_DIM,
- * downscale proportionally using sharp. Returns the original buffer
- * unchanged if already within limits.
+ * Constrain screenshot dimensions for the Anthropic vision API.
+ * Width is capped at 1568px (optimal) and height at 8000px, each
+ * independently, using `fit: "inside"` so aspect ratio is preserved.
+ * Small images are never upscaled.
  *
  * `page` parameter is retained for ToolDeps signature stability (D008)
  * but is no longer used — all processing is server-side via sharp.
@@ -133,18 +136,17 @@ export async function constrainScreenshot(
 	mimeType: string,
 	quality: number,
 ): Promise<Buffer> {
-	const { width, height } = await sharp(buffer).metadata();
+	const meta = await sharp(buffer).metadata();
+	const width = meta.width;
+	const height = meta.height;
 
-	if (
-		width !== undefined &&
-		height !== undefined &&
-		width <= MAX_SCREENSHOT_DIM &&
-		height <= MAX_SCREENSHOT_DIM
-	) {
-		return buffer;
-	}
+	if (width === undefined || height === undefined) return buffer;
+	if (width <= MAX_SCREENSHOT_WIDTH && height <= MAX_SCREENSHOT_HEIGHT) return buffer;
 
-	const resizer = sharp(buffer).resize(MAX_SCREENSHOT_DIM, MAX_SCREENSHOT_DIM, { fit: "inside" });
+	const resizer = sharp(buffer).resize(MAX_SCREENSHOT_WIDTH, MAX_SCREENSHOT_HEIGHT, {
+		fit: "inside",
+		withoutEnlargement: true,
+	});
 
 	if (mimeType === "image/png") {
 		return Buffer.from(await resizer.png().toBuffer());

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

@@ -17,6 +17,16 @@ import { registerWaitTools } from "./tools/wait.js";
 import { registerPageTools } from "./tools/pages.js";
 import { registerFormTools } from "./tools/forms.js";
 import { registerIntentTools } from "./tools/intent.js";
+import { registerPdfTools } from "./tools/pdf.js";
+import { registerStatePersistenceTools } from "./tools/state-persistence.js";
+import { registerNetworkMockTools } from "./tools/network-mock.js";
+import { registerDeviceTools } from "./tools/device.js";
+import { registerExtractTools } from "./tools/extract.js";
+import { registerVisualDiffTools } from "./tools/visual-diff.js";
+import { registerZoomTools } from "./tools/zoom.js";
+import { registerCodegenTools } from "./tools/codegen.js";
+import { registerActionCacheTools } from "./tools/action-cache.js";
+import { registerInjectionDetectionTools } from "./tools/injection-detect.js";
 
 export default function (pi: ExtensionAPI) {
 	pi.on("session_shutdown", async () => { await closeBrowser(); });
@@ -48,4 +58,14 @@ export default function (pi: ExtensionAPI) {
 	registerPageTools(pi, deps);
 	registerFormTools(pi, deps);
 	registerIntentTools(pi, deps);
+	registerPdfTools(pi, deps);
+	registerStatePersistenceTools(pi, deps);
+	registerNetworkMockTools(pi, deps);
+	registerDeviceTools(pi, deps);
+	registerExtractTools(pi, deps);
+	registerVisualDiffTools(pi, deps);
+	registerZoomTools(pi, deps);
+	registerCodegenTools(pi, deps);
+	registerActionCacheTools(pi, deps);
+	registerInjectionDetectionTools(pi, deps);
 }

package/src/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/src/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";
+	}
+}