gsd-pi 2.22.0 → 2.23.0

package/packages/pi-coding-agent/src/core/tools/bash.ts

@@ -43,6 +43,71 @@ function getTempFilePath(): string {
 	return join(tmpdir(), `pi-bash-${id}.log`);
 }
 
+/**
+ * Detect whether a command fragment ends with an unquoted & (background operator).
+ * Returns true for patterns like: `cmd &`, `cmd arg &`, `cmd & disown`, `(cmd) &`.
+ * Returns false when & appears inside a string literal or as &&.
+ */
+function endsWithBackgroundOperator(fragment: string): boolean {
+	// Remove content inside single-quoted strings to avoid false positives
+	const stripped = fragment.replace(/'[^']*'/g, "''");
+	// Match trailing & not preceded by another & (i.e., not &&)
+	return /(?<!&)&\s*(?:disown\s*)?(?:#.*)?$/.test(stripped.trim());
+}
+
+/**
+ * Determine whether a command segment already redirects stdout away from the terminal.
+ * Checks for >, >>, &>, |, /dev/null redirects.
+ */
+function hasOutputRedirect(segment: string): boolean {
+	// Remove single-quoted strings to avoid matching inside them
+	const stripped = segment.replace(/'[^']*'/g, "''");
+	// Match >, >> not preceded by 2 (stderr-only) — we only care about stdout
+	// Also match &> (combined), >&, or a pipe | which routes stdout elsewhere
+	return /(?<!\d)(?:>>?|&>|>&|\|)/.test(stripped);
+}
+
+/**
+ * Rewrite a command that uses & for backgrounding so the background process
+ * does not inherit the bash tool's stdout/stderr pipes.
+ *
+ * Without this, `python -m http.server 8080 &` causes the bash tool to hang
+ * indefinitely because Node.js keeps the pipe open until every process that
+ * inherited it exits — including the long-running server.
+ *
+ * The rewrite adds `>/dev/null 2>&1` before each & where stdout is not already
+ * redirected, ensuring the background process detaches from the pipes while
+ * still producing a human-readable notice in the tool output.
+ *
+ * Returns { command: string; rewritten: boolean }.
+ */
+export function rewriteBackgroundCommand(command: string): { command: string; rewritten: boolean } {
+	// Quick pre-check: if there's no & at all, skip the more expensive processing
+	if (!command.includes("&")) return { command, rewritten: false };
+
+	// Split on ; and newlines to handle compound commands.
+	// We rewrite each segment independently.
+	// Note: this is intentionally simple and covers the common LLM patterns.
+	// It does not attempt to parse complex nested subshells.
+	const segments = command.split(/(?<=[;\n])/);
+	let anyRewritten = false;
+
+	const rewrittenSegments = segments.map((segment) => {
+		if (!endsWithBackgroundOperator(segment)) return segment;
+		if (hasOutputRedirect(segment)) return segment;
+
+		anyRewritten = true;
+		// Insert >/dev/null 2>&1 before the trailing & (and optional disown/comment)
+		return segment.replace(
+			/(?<!&)(&\s*(?:disown\s*)?(?:#.*)?)$/,
+			">/dev/null 2>&1 $1",
+		);
+	});
+
+	if (!anyRewritten) return { command, rewritten: false };
+	return { command: rewrittenSegments.join(""), rewritten: true };
+}
+
 const bashSchema = Type.Object({
 	command: Type.String({ description: "Bash command to execute" }),
 	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
@@ -239,8 +304,25 @@ export function createBashTool(cwd: string, options?: BashToolOptions): AgentToo
 				}
 			}
 
+			// Rewrite background commands (&) to redirect output away from the pipes.
+			// Without this, `cmd &` causes the tool to hang because the background
+			// process inherits the piped stdout/stderr and keeps them open indefinitely.
+			const bgResult = rewriteBackgroundCommand(command);
+			const effectiveCommand = bgResult.command;
+			if (bgResult.rewritten) {
+				// Surface a brief advisory so the LLM knows what happened.
+				// The rewrite is transparent for the common case; explicit detachment
+				// (nohup, start_new_session) is preferred for robustness.
+				onUpdate?.({
+					content: [{
+						type: "text" as const,
+						text: "Note: Background command output redirected to /dev/null to prevent pipe hang. Use nohup or setsid for reliable detachment.",
+					}],
+					details: undefined,
+				});
+			}
 			// Apply command prefix if configured (e.g., "shopt -s expand_aliases" for alias support)
-			const resolvedCommand = sanitizeCommand(commandPrefix ? `${commandPrefix}\n${command}` : command);
+			const resolvedCommand = sanitizeCommand(commandPrefix ? `${commandPrefix}\n${effectiveCommand}` : effectiveCommand);
 			const spawnContext = resolveSpawnContext(resolvedCommand, cwd, spawnHook);
 
 			return new Promise((resolve, reject) => {

package/packages/pi-coding-agent/src/core/tools/index.ts

@@ -7,6 +7,7 @@ export {
 	type BashToolOptions,
 	bashTool,
 	createBashTool,
+	rewriteBackgroundCommand,
 } from "./bash.js";
 export {
 	type BashInterceptorRule,

package/packages/pi-coding-agent/src/index.ts

@@ -235,6 +235,7 @@ export {
 	type BashToolInput,
 	type BashToolOptions,
 	bashTool,
+	rewriteBackgroundCommand,
 	checkBashInterception,
 	type CompiledInterceptor,
 	compileInterceptor,

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