agentic-browser 1.4.0 → 1.5.0

package/AGENTS.md

@@ -117,15 +117,15 @@ AgenticBrowserCore → ControlApi → SessionManager → BrowserController (CDP)
 
 Subcommand: `agentic-browser mcp` (stdio transport). Setup: `agentic-browser setup`. Tools:
 
-| Tool                    | Purpose                        |
-| ----------------------- | ------------------------------ |
-| `browser_start_session` | Start Chrome, return sessionId |
-| `browser_navigate`      | Navigate to URL                |
-| `browser_interact`      | click / type / press / waitFor |
-| `browser_get_content`   | Get page title / text / html   |
-| `browser_get_elements`  | Discover interactive elements  |
-| `browser_search_memory` | Search task memory             |
-| `browser_stop_session`  | Stop Chrome session            |
+| Tool                    | Purpose                                                                                                   |
+| ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| `browser_start_session` | Start Chrome, return sessionId                                                                            |
+| `browser_navigate`      | Navigate to URL                                                                                           |
+| `browser_interact`      | click / type / press / waitFor / scroll / hover / select / toggle / goBack / goForward / refresh / dialog |
+| `browser_get_content`   | Get page title / text / html                                                                              |
+| `browser_get_elements`  | Discover interactive elements                                                                             |
+| `browser_search_memory` | Search task memory                                                                                        |
+| `browser_stop_session`  | Stop Chrome session                                                                                       |
 
 ## For Browser Automation Tasks
 

package/README.md

@@ -132,7 +132,7 @@ agentic-browser agent elements --roles button,link,input --visible-only --limit
 agentic-browser agent elements --selector "#main-content"
 ```
 
-Returns a JSON array of elements with CSS selectors usable in `agent run interact`:
+Returns a JSON array of elements with CSS selectors and fallback selectors usable in `agent run interact`:
 
 ```json
 {
@@ -141,11 +141,9 @@ Returns a JSON array of elements with CSS selectors usable in `agent run interac
   "elements": [
     {
       "selector": "#login-btn",
+      "fallbackSelectors": ["button[aria-label=\"Login\"]"],
       "role": "button",
-      "tagName": "button",
       "text": "Login",
-      "actions": ["click"],
-      "visible": true,
       "enabled": true
     }
   ],
@@ -154,13 +152,17 @@ Returns a JSON array of elements with CSS selectors usable in `agent run interac
 }
 ```
 
+MCP responses are compact — `visible`, `actions`, and `tagName` are omitted to reduce token usage. The full element shape is available via the programmatic API.
+
+````
+
 ## MCP Server
 
 ### Quick Setup
 
 ```bash
 npx agentic-browser setup
-```
+````
 
 Detects your AI tools (Claude Code, Cursor) and writes the MCP config automatically.
 
@@ -211,6 +213,12 @@ More `interact` actions:
 - `{"action":"type","selector":"input[name=q]","text":"innoq"}`
 - `{"action":"press","key":"Enter"}`
 - `{"action":"waitFor","selector":"main","timeoutMs":4000}`
+- `{"action":"goBack"}` — browser back
+- `{"action":"goForward"}` — browser forward
+- `{"action":"refresh"}` — reload page
+- `{"action":"dialog"}` — accept a JS dialog (alert/confirm/prompt)
+- `{"action":"dialog","text":"dismiss"}` — dismiss a dialog
+- `{"action":"dialog","value":"answer"}` — respond to a prompt dialog
 
 ### 4. Read Page Content
 

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as createCliRuntime } from "../runtime-CODdeRWR.mjs";
+import { r as createCliRuntime } from "../runtime-OsYo7Rh2.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";

package/dist/index.mjs

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { i as createMockAgenticBrowserCore, n as createAgenticBrowserCore, t as AgenticBrowserCore } from "./runtime-CODdeRWR.mjs";
+import { i as createMockAgenticBrowserCore, n as createAgenticBrowserCore, t as AgenticBrowserCore } from "./runtime-OsYo7Rh2.mjs";
 
 export { AgenticBrowserCore, createAgenticBrowserCore, createMockAgenticBrowserCore };

package/dist/mcp/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-CODdeRWR.mjs";
+import { n as createAgenticBrowserCore } from "../runtime-OsYo7Rh2.mjs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -31,9 +31,10 @@ const server = new McpServer({
 server.tool("browser_start_session", "Start a new Chrome browser session (or return the existing one if healthy). Sessions auto-start when you call any other browser tool, so you rarely need to call this explicitly. Use this to force a fresh session after stopping the previous one.", {}, async () => {
 	const session = await getCore().startSession();
 	activeSessionId = session.sessionId;
+	const { authTokenRef: _, ...compactSession } = session;
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(session)
+		text: JSON.stringify(compactSession)
 	}] };
 });
 server.tool("browser_navigate", "Navigate the browser to a URL. A session is auto-started if needed.", {
@@ -47,12 +48,16 @@ server.tool("browser_navigate", "Navigate the browser to a URL. A session is aut
 		type: "navigate",
 		payload: { url }
 	});
+	const compact = {
+		resultStatus: result.resultStatus,
+		resultMessage: result.resultMessage
+	};
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(result)
+		text: JSON.stringify(compact)
 	}] };
 });
-server.tool("browser_interact", "Interact with a page element. Actions: \"click\" (click element), \"type\" (type text into input), \"press\" (press a keyboard key like Enter), \"waitFor\" (wait for element to appear), \"scroll\" (scroll page or element), \"hover\" (hover over element), \"select\" (pick option in <select>), \"toggle\" (toggle checkbox/radio/switch). A session is auto-started if needed.", {
+server.tool("browser_interact", "Interact with a page element or perform browser actions. Element actions: \"click\", \"type\", \"press\", \"waitFor\", \"scroll\", \"hover\", \"select\", \"toggle\". Navigation actions: \"goBack\" (browser back), \"goForward\" (browser forward), \"refresh\" (reload page). Dialog action: \"dialog\" (handle JS alert/confirm/prompt — use text=\"dismiss\" to cancel, value=\"...\" for prompt input). Fallback selectors are tried automatically if the primary selector fails. A session is auto-started if needed.", {
 	action: z.enum([
 		"click",
 		"type",
@@ -61,20 +66,26 @@ server.tool("browser_interact", "Interact with a page element. Actions: \"click\
 		"scroll",
 		"hover",
 		"select",
-		"toggle"
+		"toggle",
+		"goBack",
+		"goForward",
+		"refresh",
+		"dialog"
 	]).describe("The interaction type"),
 	selector: z.string().optional().describe("CSS selector for the target element"),
-	text: z.string().optional().describe("Text to type (required for \"type\" action)"),
+	fallbackSelectors: z.array(z.string()).optional().describe("Backup CSS selectors tried if the primary selector fails (from browser_get_elements)"),
+	text: z.string().optional().describe("Text to type (for \"type\"), or \"dismiss\" to dismiss a dialog (for \"dialog\")"),
 	key: z.string().optional().describe("Key to press (required for \"press\" action, e.g. \"Enter\", \"Tab\")"),
-	value: z.string().optional().describe("Option value to select (required for \"select\" action)"),
+	value: z.string().optional().describe("Option value to select (for \"select\"), or prompt text (for \"dialog\")"),
 	scrollX: z.number().optional().describe("Horizontal scroll delta in pixels (for \"scroll\" action)"),
 	scrollY: z.number().optional().describe("Vertical scroll delta in pixels (for \"scroll\" action, positive = down)"),
 	timeoutMs: z.number().optional().describe("Timeout in milliseconds (for \"waitFor\" action, default 4000)"),
 	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
-}, async ({ action, selector, text, key, value, scrollX, scrollY, timeoutMs, sessionId }) => {
+}, async ({ action, selector, fallbackSelectors, text, key, value, scrollX, scrollY, timeoutMs, sessionId }) => {
 	const sid = await resolveSession(sessionId);
 	const payload = { action };
 	if (selector) payload.selector = selector;
+	if (fallbackSelectors) payload.fallbackSelectors = fallbackSelectors;
 	if (text) payload.text = text;
 	if (key) payload.key = key;
 	if (value) payload.value = value;
@@ -87,9 +98,13 @@ server.tool("browser_interact", "Interact with a page element. Actions: \"click\
 		type: "interact",
 		payload
 	});
+	const compact = {
+		resultStatus: result.resultStatus,
+		resultMessage: result.resultMessage
+	};
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(result)
+		text: JSON.stringify(compact)
 	}] };
 });
 server.tool("browser_get_content", "Get the current page content. Modes: \"text\" (readable text), \"a11y\" (accessibility tree — best for understanding page structure), \"title\" (page title only), \"html\" (raw HTML). Use \"a11y\" to see the full page hierarchy with roles, names, and states. A session is auto-started if needed.", {
@@ -100,20 +115,42 @@ server.tool("browser_get_content", "Get the current page content. Modes: \"text\
 		"a11y"
 	]).default("text").describe("Content extraction mode"),
 	selector: z.string().optional().describe("CSS selector to scope content (e.g. \"main\", \"#content\")"),
+	maxChars: z.number().optional().describe("Maximum characters to return (default: 12000 for text/a11y, 6000 for html, no cap for title). Use a CSS selector to scope content instead of raising this limit."),
 	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
-}, async ({ mode, selector, sessionId }) => {
+}, async ({ mode, selector, maxChars, sessionId }) => {
 	const sid = await resolveSession(sessionId);
 	const result = await getCore().getPageContent({
 		sessionId: sid,
 		mode,
 		selector
 	});
+	const limit = maxChars ?? {
+		text: 12e3,
+		a11y: 12e3,
+		html: 6e3,
+		title: void 0
+	}[mode];
+	if (limit && typeof result.content === "string" && result.content.length > limit) {
+		const originalLength = result.content.length;
+		const truncatedContent = result.content.slice(0, limit) + `\n\n[Truncated — showing first ${limit} of ${originalLength} characters. Use a CSS selector to scope the content.]`;
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				...result,
+				content: truncatedContent,
+				truncated: true
+			})
+		}] };
+	}
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(result)
+		text: JSON.stringify({
+			...result,
+			truncated: false
+		})
 	}] };
 });
-server.tool("browser_get_elements", "Discover all interactive elements on the current page (buttons, links, inputs, etc.). Returns CSS selectors you can use with browser_interact. A session is auto-started if needed.", {
+server.tool("browser_get_elements", "Discover all interactive elements on the current page (buttons, links, inputs, etc.). Returns CSS selectors and fallbackSelectors you can use with browser_interact. Pass fallbackSelectors to browser_interact for automatic retry when the primary selector breaks. Actions are derived from role: link/button/custom→click, input/textarea/contenteditable→click+type+press, select→click+select, checkbox/radio→toggle. A session is auto-started if needed.", {
 	roles: z.array(z.enum([
 		"link",
 		"button",
@@ -138,24 +175,46 @@ server.tool("browser_get_elements", "Discover all interactive elements on the cu
 		limit,
 		selector
 	});
+	const compactElements = result.elements.map((el) => {
+		const compact = { ...el };
+		if (visibleOnly) delete compact.visible;
+		delete compact.actions;
+		delete compact.tagName;
+		if (compact.ariaLabel && compact.ariaLabel === compact.text) delete compact.ariaLabel;
+		return compact;
+	});
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(result)
+		text: JSON.stringify({
+			elements: compactElements,
+			totalFound: result.totalFound,
+			truncated: result.truncated
+		})
 	}] };
 });
-server.tool("browser_search_memory", "Search task memory for previously learned selectors and interaction patterns. Use this before interacting with a known site to reuse proven selectors instead of rediscovering them.", {
+server.tool("browser_search_memory", "Search task memory for previously learned selectors, selector aliases, and interaction patterns. Results include selectorHints (proven selectors) and selectorAliases (human-readable names mapped to selectors with fallbacks). Use this before interacting with a known site to reuse proven selectors instead of rediscovering them.", {
 	taskIntent: z.string().describe("What you want to do, e.g. \"login:github.com\" or \"search:amazon.de\""),
 	siteDomain: z.string().optional().describe("Domain to scope the search"),
 	limit: z.number().default(5).describe("Maximum number of results")
 }, async ({ taskIntent, siteDomain, limit }) => {
-	const result = getCore().searchMemory({
+	const compactResults = getCore().searchMemory({
 		taskIntent,
 		siteDomain,
 		limit
+	}).results.map((r) => {
+		const compact = { ...r };
+		delete compact.score;
+		delete compact.lastVerifiedAt;
+		if (Array.isArray(compact.selectorAliases)) compact.selectorAliases = compact.selectorAliases.map((alias) => {
+			const compactAlias = { ...alias };
+			if (Array.isArray(compactAlias.fallbackSelectors) && compactAlias.fallbackSelectors.length === 0) delete compactAlias.fallbackSelectors;
+			return compactAlias;
+		});
+		return compact;
 	});
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(result)
+		text: JSON.stringify({ results: compactResults })
 	}] };
 });
 server.tool("browser_stop_session", "Stop the browser session and terminate Chrome. The next browser tool call will auto-start a fresh session.", { sessionId: z.string().optional().describe("Session ID (uses active session if omitted)") }, async ({ sessionId }) => {

package/dist/{runtime-CODdeRWR.mjs → runtime-OsYo7Rh2.mjs}

@@ -92,6 +92,16 @@ var CdpConnection = class CdpConnection {
 			this.ws.on("message", onMessage);
 		});
 	}
+	onEvent(method, handler) {
+		const onMessage = (raw) => {
+			const message = JSON.parse(raw.toString("utf8"));
+			if (message.method === method) handler(message.params ?? {});
+		};
+		this.ws.on("message", onMessage);
+		return () => {
+			this.ws.off("message", onMessage);
+		};
+	}
 	close() {
 		this.ws.close();
 	}
@@ -150,25 +160,19 @@ async function createTarget(cdpUrl, url = "about:blank") {
 	} catch {}
 	return await ensurePageWebSocketUrl(cdpUrl);
 }
-async function applyUserAgent(targetWsUrl, userAgent) {
-	const conn = await CdpConnection.connect(targetWsUrl);
-	try {
-		await conn.send("Network.enable");
-		await conn.send("Network.setUserAgentOverride", { userAgent });
-	} finally {
-		conn.close();
-	}
-}
-async function evaluateExpression(targetWsUrl, expression) {
+/** Verify the page is ready and optionally set a custom user-agent, using a single connection. */
+async function initTarget(targetWsUrl, userAgent) {
 	const conn = await CdpConnection.connect(targetWsUrl);
 	try {
-		await conn.send("Page.enable");
-		await conn.send("Runtime.enable");
-		return (await conn.send("Runtime.evaluate", {
-			expression,
+		const enables = [conn.send("Page.enable"), conn.send("Runtime.enable")];
+		if (userAgent) enables.push(conn.send("Network.enable"));
+		await Promise.all(enables);
+		await conn.send("Runtime.evaluate", {
+			expression: "window.location.href",
 			returnByValue: true,
 			awaitPromise: true
-		})).result.value ?? "";
+		});
+		if (userAgent) await conn.send("Network.setUserAgentOverride", { userAgent });
 	} finally {
 		conn.close();
 	}
@@ -236,8 +240,7 @@ var ChromeCdpBrowserController = class {
 		if (!port) throw new Error(`Invalid CDP URL: could not extract port from ${cdpUrl}`);
 		await waitForDebugger(port);
 		const targetWsUrl = await createTarget(cdpUrl);
-		await evaluateExpression(targetWsUrl, "window.location.href");
-		if (options?.userAgent) await applyUserAgent(targetWsUrl, options.userAgent);
+		await initTarget(targetWsUrl, options?.userAgent);
 		return {
 			pid: 0,
 			cdpUrl,
@@ -247,13 +250,27 @@ var ChromeCdpBrowserController = class {
 	async ensureEnabled(targetWsUrl) {
 		const cached = this.connections.get(targetWsUrl);
 		if (!cached) return;
-		if (!cached.enabled.page) {
-			await cached.conn.send("Page.enable");
+		const promises = [];
+		if (!cached.enabled.page) promises.push(cached.conn.send("Page.enable").then(() => {
 			cached.enabled.page = true;
-		}
-		if (!cached.enabled.runtime) {
-			await cached.conn.send("Runtime.enable");
+		}));
+		if (!cached.enabled.runtime) promises.push(cached.conn.send("Runtime.enable").then(() => {
 			cached.enabled.runtime = true;
+		}));
+		if (promises.length) await Promise.all(promises);
+		if (!cached.dialogListenerAttached && cached.conn.onEvent) {
+			cached.conn.onEvent("Page.javascriptDialogOpening", (params) => {
+				cached.pendingDialog = {
+					type: params.type,
+					message: params.message,
+					defaultPrompt: params.defaultPrompt
+				};
+				if (params.type === "alert") {
+					cached.conn.send("Page.handleJavaScriptDialog", { accept: true }).catch(() => {});
+					cached.pendingDialog = void 0;
+				}
+			});
+			cached.dialogListenerAttached = true;
 		}
 	}
 	async launch(sessionId, options) {
@@ -305,9 +322,8 @@ var ChromeCdpBrowserController = class {
 				await waitForDebugger(port);
 				const cdpUrl = `http://127.0.0.1:${port}`;
 				const targetWsUrl = await createTarget(cdpUrl, "about:blank");
-				await evaluateExpression(targetWsUrl, "window.location.href");
 				if (!child.pid) throw new Error("Failed to launch Chrome process");
-				if (userAgent) await applyUserAgent(targetWsUrl, userAgent);
+				await initTarget(targetWsUrl, userAgent);
 				return {
 					pid: child.pid,
 					cdpUrl,
@@ -346,12 +362,83 @@ var ChromeCdpBrowserController = class {
 			return navigatedEvent?.frame?.url ?? url;
 		});
 	}
+	async handleDialogAction(targetWsUrl, payload) {
+		return await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			const cached = this.connections.get(targetWsUrl);
+			if (!cached?.pendingDialog) try {
+				await conn.waitForEvent("Page.javascriptDialogOpening", 500);
+				await new Promise((r) => setTimeout(r, 50));
+			} catch {
+				return "no dialog present";
+			}
+			const dialog = cached?.pendingDialog;
+			if (!dialog) return "no dialog present";
+			const dismiss = payload.text === "dismiss";
+			await conn.send("Page.handleJavaScriptDialog", {
+				accept: !dismiss,
+				promptText: payload.value
+			});
+			const result = dismiss ? `dismissed ${dialog.type}` : `accepted ${dialog.type}`;
+			if (cached) cached.pendingDialog = void 0;
+			return `${result}: ${dialog.message}`;
+		});
+	}
 	async interact(targetWsUrl, payload) {
+		if (payload.action === "goBack") return await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			const navigatedPromise = conn.waitForEvent("Page.frameNavigated", 3e3).catch(() => void 0);
+			await conn.send("Runtime.evaluate", {
+				expression: "history.back()",
+				returnByValue: true
+			});
+			const event = await navigatedPromise;
+			if (!event) return "no history to go back";
+			try {
+				await Promise.race([conn.waitForEvent("Page.loadEventFired", 5e3), conn.waitForEvent("Page.frameStoppedLoading", 5e3)]);
+			} catch {}
+			return `navigated back to ${event.frame?.url ?? "previous page"}`;
+		});
+		if (payload.action === "goForward") return await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			const navigatedPromise = conn.waitForEvent("Page.frameNavigated", 3e3).catch(() => void 0);
+			await conn.send("Runtime.evaluate", {
+				expression: "history.forward()",
+				returnByValue: true
+			});
+			const event = await navigatedPromise;
+			if (!event) return "no history to go forward";
+			try {
+				await Promise.race([conn.waitForEvent("Page.loadEventFired", 5e3), conn.waitForEvent("Page.frameStoppedLoading", 5e3)]);
+			} catch {}
+			return `navigated forward to ${event.frame?.url ?? "next page"}`;
+		});
+		if (payload.action === "refresh") return await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			await conn.send("Page.reload");
+			try {
+				await Promise.race([conn.waitForEvent("Page.loadEventFired", 1e4), conn.waitForEvent("Page.frameStoppedLoading", 1e4)]);
+			} catch {}
+			return "page refreshed";
+		});
+		if (payload.action === "dialog") return await this.handleDialogAction(targetWsUrl, payload);
 		const expression = `(async () => {
       const payload = ${JSON.stringify(payload)};
+
+      function resolveElement(selector, fallbacks) {
+        let el = selector ? document.querySelector(selector) : null;
+        if (el) return el;
+        if (fallbacks && fallbacks.length) {
+          for (const fb of fallbacks) {
+            el = document.querySelector(fb);
+            if (el) return el;
+          }
+        }
+        throw new Error('Selector not found');
+      }
+
       if (payload.action === 'click') {
-        const el = document.querySelector(payload.selector);
-        if (!el) throw new Error('Selector not found');
+        const el = resolveElement(payload.selector, payload.fallbackSelectors);
         const rect = el.getBoundingClientRect();
         if (rect.width === 0 && rect.height === 0) {
           throw new Error('Element has zero size – it may be hidden or not rendered');
@@ -369,8 +456,7 @@ var ChromeCdpBrowserController = class {
         return 'clicked';
       }
       if (payload.action === 'type') {
-        const el = document.querySelector(payload.selector);
-        if (!el) throw new Error('Selector not found');
+        const el = resolveElement(payload.selector, payload.fallbackSelectors);
         el.focus();
         el.value = payload.text ?? '';
         el.dispatchEvent(new Event('input', { bubbles: true }));
@@ -405,8 +491,7 @@ var ChromeCdpBrowserController = class {
       }
       if (payload.action === 'scroll') {
         if (payload.selector) {
-          const el = document.querySelector(payload.selector);
-          if (!el) throw new Error('Selector not found');
+          const el = resolveElement(payload.selector, payload.fallbackSelectors);
           el.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0, behavior: 'smooth' });
           return 'scrolled element';
         }
@@ -414,8 +499,7 @@ var ChromeCdpBrowserController = class {
         return 'scrolled page';
       }
       if (payload.action === 'hover') {
-        const el = document.querySelector(payload.selector);
-        if (!el) throw new Error('Selector not found');
+        const el = resolveElement(payload.selector, payload.fallbackSelectors);
         const rect = el.getBoundingClientRect();
         const cx = rect.left + rect.width / 2;
         const cy = rect.top + rect.height / 2;
@@ -425,8 +509,7 @@ var ChromeCdpBrowserController = class {
         return 'hovered';
       }
       if (payload.action === 'select') {
-        const el = document.querySelector(payload.selector);
-        if (!el) throw new Error('Selector not found');
+        const el = resolveElement(payload.selector, payload.fallbackSelectors);
         if (el.tagName.toLowerCase() !== 'select') throw new Error('Element is not a <select>');
         el.value = payload.value ?? '';
         el.dispatchEvent(new Event('change', { bubbles: true }));
@@ -434,8 +517,7 @@ var ChromeCdpBrowserController = class {
         return 'selected ' + el.value;
       }
       if (payload.action === 'toggle') {
-        const el = document.querySelector(payload.selector);
-        if (!el) throw new Error('Selector not found');
+        const el = resolveElement(payload.selector, payload.fallbackSelectors);
         el.click();
         const checked = el.checked !== undefined ? el.checked : el.getAttribute('aria-checked') === 'true';
         return 'toggled to ' + (checked ? 'checked' : 'unchecked');
@@ -608,34 +690,62 @@ var ChromeCdpBrowserController = class {
         return value.replace(/\\\\/g, '\\\\\\\\').replace(/"/g, '\\\\"');
       }
 
+      function tryUniqueSelector(sel) {
+        try { return document.querySelectorAll(sel).length === 1 ? sel : null; }
+        catch { return null; }
+      }
+
       function buildSelector(el) {
         if (el.id) return '#' + CSS.escape(el.id);
 
         const name = el.getAttribute('name');
         if (name) {
           const tag = el.tagName.toLowerCase();
-          const sel = tag + '[name="' + escapeAttr(name) + '"]';
-          if (document.querySelectorAll(sel).length === 1) return sel;
+          const sel = tryUniqueSelector(tag + '[name="' + escapeAttr(name) + '"]');
+          if (sel) return sel;
         }
 
         const testId = el.getAttribute('data-testid') || el.getAttribute('data-test-id');
         if (testId) {
           const attr = el.hasAttribute('data-testid') ? 'data-testid' : 'data-test-id';
-          const sel = '[' + attr + '="' + escapeAttr(testId) + '"]';
-          if (document.querySelectorAll(sel).length === 1) return sel;
+          const sel = tryUniqueSelector('[' + attr + '="' + escapeAttr(testId) + '"]');
+          if (sel) return sel;
         }
 
         const ariaLabel = el.getAttribute('aria-label');
         if (ariaLabel) {
           const tag = el.tagName.toLowerCase();
-          const sel = tag + '[aria-label="' + escapeAttr(ariaLabel) + '"]';
-          if (document.querySelectorAll(sel).length === 1) return sel;
+          const sel = tryUniqueSelector(tag + '[aria-label="' + escapeAttr(ariaLabel) + '"]');
+          if (sel) return sel;
+        }
+
+        const dataCy = el.getAttribute('data-cy');
+        if (dataCy) {
+          const sel = tryUniqueSelector('[data-cy="' + escapeAttr(dataCy) + '"]');
+          if (sel) return sel;
+        }
+
+        const dataTest = el.getAttribute('data-test');
+        if (dataTest) {
+          const sel = tryUniqueSelector('[data-test="' + escapeAttr(dataTest) + '"]');
+          if (sel) return sel;
         }
 
+        const role = el.getAttribute('role');
+        if (role && ariaLabel) {
+          const sel = tryUniqueSelector('[role="' + escapeAttr(role) + '"][aria-label="' + escapeAttr(ariaLabel) + '"]');
+          if (sel) return sel;
+        }
+
+        // Path fallback — anchor at nearest ancestor with an id for shorter selectors
         const parts = [];
         let current = el;
         while (current && current !== document.documentElement) {
           const tag = current.tagName.toLowerCase();
+          if (current !== el && current.id) {
+            parts.unshift('#' + CSS.escape(current.id));
+            break;
+          }
           const parent = current.parentElement;
           if (!parent) { parts.unshift(tag); break; }
           const siblings = Array.from(parent.children).filter(
@@ -652,6 +762,50 @@ var ChromeCdpBrowserController = class {
         return parts.join(' > ');
       }
 
+      function buildFallbackSelectors(el, primarySelector) {
+        const fallbacks = [];
+        const candidates = [];
+
+        if (el.id) candidates.push('#' + CSS.escape(el.id));
+
+        const name = el.getAttribute('name');
+        if (name) {
+          const tag = el.tagName.toLowerCase();
+          const sel = tag + '[name="' + escapeAttr(name) + '"]';
+          candidates.push(sel);
+        }
+
+        const testId = el.getAttribute('data-testid') || el.getAttribute('data-test-id');
+        if (testId) {
+          const attr = el.hasAttribute('data-testid') ? 'data-testid' : 'data-test-id';
+          candidates.push('[' + attr + '="' + escapeAttr(testId) + '"]');
+        }
+
+        const ariaLabel = el.getAttribute('aria-label');
+        if (ariaLabel) {
+          const tag = el.tagName.toLowerCase();
+          candidates.push(tag + '[aria-label="' + escapeAttr(ariaLabel) + '"]');
+        }
+
+        const dataCy = el.getAttribute('data-cy');
+        if (dataCy) candidates.push('[data-cy="' + escapeAttr(dataCy) + '"]');
+
+        const dataTest = el.getAttribute('data-test');
+        if (dataTest) candidates.push('[data-test="' + escapeAttr(dataTest) + '"]');
+
+        const role = el.getAttribute('role');
+        if (role && ariaLabel) {
+          candidates.push('[role="' + escapeAttr(role) + '"][aria-label="' + escapeAttr(ariaLabel) + '"]');
+        }
+
+        for (const sel of candidates) {
+          if (sel === primarySelector) continue;
+          if (tryUniqueSelector(sel)) fallbacks.push(sel);
+          if (fallbacks.length >= 3) break;
+        }
+        return fallbacks;
+      }
+
       function isVisible(el) {
         const style = window.getComputedStyle(el);
         if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
@@ -715,8 +869,9 @@ var ChromeCdpBrowserController = class {
         totalFound++;
         if (results.length >= limit) continue;
 
+        const primarySelector = buildSelector(el);
         const entry = {
-          selector: buildSelector(el),
+          selector: primarySelector,
           role,
           tagName: el.tagName.toLowerCase(),
           text: getText(el),
@@ -725,6 +880,9 @@ var ChromeCdpBrowserController = class {
           enabled: isEnabled(el),
         };
 
+        const fb = buildFallbackSelectors(el, primarySelector);
+        if (fb.length) entry.fallbackSelectors = fb;
+
         if (role === 'link' && el.href) entry.href = el.href;
         if (role === 'input') entry.inputType = (el.type || 'text').toLowerCase();
         const al = el.getAttribute('aria-label');
@@ -799,9 +957,30 @@ var MockBrowserController = class {
 		page.title = url;
 		page.text = `Content of ${url}`;
 		page.html = `<html><body>${page.text}</body></html>`;
+		this.history.splice(this.historyIndex + 1);
+		this.history.push(url);
+		this.historyIndex = this.history.length - 1;
 		return url;
 	}
-	async interact(_cdpUrl, payload) {
+	history = [];
+	historyIndex = -1;
+	async interact(cdpUrl, payload) {
+		if (payload.action === "goBack") {
+			if (this.historyIndex <= 0) return "no history to go back";
+			this.historyIndex--;
+			const page = this.pages.get(cdpUrl);
+			if (page) page.url = this.history[this.historyIndex] ?? page.url;
+			return `navigated back to ${page?.url ?? "previous page"}`;
+		}
+		if (payload.action === "goForward") {
+			if (this.historyIndex >= this.history.length - 1) return "no history to go forward";
+			this.historyIndex++;
+			const page = this.pages.get(cdpUrl);
+			if (page) page.url = this.history[this.historyIndex] ?? page.url;
+			return `navigated forward to ${page?.url ?? "next page"}`;
+		}
+		if (payload.action === "refresh") return "page refreshed";
+		if (payload.action === "dialog") return payload.text === "dismiss" ? "dismissed confirm: mock dialog" : "accepted confirm: mock dialog";
 		return `interacted:${payload.action}`;
 	}
 	async getContent(cdpUrl, options) {
@@ -1401,7 +1580,7 @@ var EventStore = class {
 		const existing = this.events.get(event.sessionId) ?? [];
 		existing.push(event);
 		this.events.set(event.sessionId, existing);
-		fs.appendFileSync(this.filePath, `${JSON.stringify(event)}\n`, "utf8");
+		fs.appendFile(this.filePath, `${JSON.stringify(event)}\n`, "utf8", () => {});
 	}
 	list(sessionId, limit = 100) {
 		const entries = this.events.get(sessionId) ?? [];
@@ -1502,6 +1681,9 @@ function buildSelectorHints(insight) {
 	}
 	return [...weightedSelectors.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([selector]) => selector);
 }
+function buildSelectorAliases(insight) {
+	return insight.selectorAliases ?? [];
+}
 function selectorSignal(insight) {
 	const recipeSelectors = insight.actionRecipe.filter((step) => Boolean(step.selector)).length;
 	const recipeCoverage = insight.actionRecipe.length > 0 ? recipeSelectors / insight.actionRecipe.length : 0;
@@ -1525,6 +1707,7 @@ function scoreInsight(insight, normalizedIntent, normalizedDomain) {
 		freshness: insight.freshness,
 		lastVerifiedAt: insight.lastVerifiedAt,
 		selectorHints: buildSelectorHints(insight),
+		selectorAliases: buildSelectorAliases(insight),
 		score
 	};
 }
@@ -1639,6 +1822,11 @@ const EvidenceRecordSchema = z.object({
 	url: z.string().optional(),
 	recordedAt: z.string().datetime()
 });
+const SelectorAliasSchema = z.object({
+	alias: z.string().min(1),
+	selector: z.string().min(1),
+	fallbackSelectors: z.array(z.string()).default([])
+});
 const TaskInsightSchema = z.object({
 	insightId: z.string().min(1),
 	taskIntent: z.string().min(1),
@@ -1656,7 +1844,8 @@ const TaskInsightSchema = z.object({
 	createdAt: z.string().datetime(),
 	updatedAt: z.string().datetime(),
 	supersedes: z.string().optional(),
-	evidence: z.array(EvidenceRecordSchema)
+	evidence: z.array(EvidenceRecordSchema),
+	selectorAliases: z.array(SelectorAliasSchema).default([])
 });
 const MemoryStateSchema = z.object({ insights: z.array(TaskInsightSchema) });
 
@@ -1841,7 +2030,7 @@ var MemoryService = class {
 		const evidence = this.createEvidence(input, "success");
 		if (!matched) {
 			const now = (/* @__PURE__ */ new Date()).toISOString();
-			const created = {
+			let created = {
 				insightId: crypto.randomUUID(),
 				taskIntent: input.taskIntent,
 				siteDomain: input.siteDomain,
@@ -1857,8 +2046,10 @@ var MemoryService = class {
 				lastVerifiedAt: now,
 				createdAt: now,
 				updatedAt: now,
-				evidence: [evidence]
+				evidence: [evidence],
+				selectorAliases: []
 			};
+			created = this.maybeGenerateAliases(created);
 			this.store.upsert(created);
 			this.invalidateSearchCache();
 			return created;
@@ -1872,7 +2063,7 @@ var MemoryService = class {
 		});
 		if (matched.freshness === "suspect" || matched.freshness === "stale") {
 			const now = (/* @__PURE__ */ new Date()).toISOString();
-			const versioned = {
+			let versioned = {
 				...refreshed,
 				insightId: crypto.randomUUID(),
 				supersedes: matched.insightId,
@@ -1880,13 +2071,15 @@ var MemoryService = class {
 				createdAt: now,
 				updatedAt: now
 			};
+			versioned = this.maybeGenerateAliases(versioned);
 			this.store.upsert(versioned);
 			this.invalidateSearchCache();
 			return versioned;
 		}
-		this.store.upsert(refreshed);
+		const withAliases = this.maybeGenerateAliases(refreshed);
+		this.store.upsert(withAliases);
 		this.invalidateSearchCache();
-		return refreshed;
+		return withAliases;
 	}
 	recordFailure(input, errorMessage) {
 		const insights = this.store.list();
@@ -1904,7 +2097,13 @@ var MemoryService = class {
 		return failed;
 	}
 	findBestExactMatch(insights, taskIntent, siteDomain) {
-		return insights.filter((insight) => insight.taskIntent.toLowerCase() === taskIntent.toLowerCase() && insight.siteDomain.toLowerCase() === siteDomain.toLowerCase()).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+		const intentLower = taskIntent.toLowerCase();
+		const domainLower = siteDomain.toLowerCase();
+		let best;
+		for (const insight of insights) if (insight.taskIntent.toLowerCase() === intentLower && insight.siteDomain.toLowerCase() === domainLower) {
+			if (!best || insight.updatedAt > best.updatedAt) best = insight;
+		}
+		return best;
 	}
 	createEvidence(input, result, reason) {
 		return {
@@ -1917,6 +2116,42 @@ var MemoryService = class {
 			recordedAt: (/* @__PURE__ */ new Date()).toISOString()
 		};
 	}
+	maybeGenerateAliases(insight) {
+		if (insight.confidence < .8 || insight.successCount < 3) return insight;
+		const aliasMap = /* @__PURE__ */ new Map();
+		for (const existing of insight.selectorAliases ?? []) aliasMap.set(existing.selector, existing);
+		const selectors = /* @__PURE__ */ new Set();
+		for (const step of insight.actionRecipe) if (step.selector) selectors.add(step.selector);
+		for (const ev of insight.evidence) if (ev.selector && ev.result === "success") selectors.add(ev.selector);
+		for (const selector of selectors) {
+			if (aliasMap.has(selector)) continue;
+			const alias = this.deriveAliasName(selector);
+			if (alias) aliasMap.set(selector, {
+				alias,
+				selector,
+				fallbackSelectors: []
+			});
+			if (aliasMap.size >= 10) break;
+		}
+		return {
+			...insight,
+			selectorAliases: [...aliasMap.values()].slice(0, 10)
+		};
+	}
+	deriveAliasName(selector) {
+		const idMatch = selector.match(/^#([\w-]+)$/);
+		if (idMatch) return idMatch[1].replace(/[-_]/g, " ");
+		const nameMatch = selector.match(/\[name="([^"]+)"\]/);
+		if (nameMatch) return nameMatch[1];
+		const ariaMatch = selector.match(/\[aria-label="([^"]+)"\]/);
+		if (ariaMatch) return ariaMatch[1];
+		const testIdMatch = selector.match(/\[data-testid="([^"]+)"\]/);
+		if (testIdMatch) return testIdMatch[1];
+		const cyMatch = selector.match(/\[data-cy="([^"]+)"\]/);
+		if (cyMatch) return cyMatch[1];
+		const testMatch = selector.match(/\[data-test="([^"]+)"\]/);
+		if (testMatch) return testMatch[1];
+	}
 	mergeRecipe(recipe, step) {
 		if (recipe.find((existing) => existing.summary === step.summary && existing.selector === step.selector)) return recipe;
 		return [...recipe, step].slice(-8);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-browser",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",