agentic-browser 1.6.0 → 2.0.0

package/README.md

@@ -111,8 +111,8 @@ agentic-browser agent start --user-profile default
 agentic-browser agent start --headless
 agentic-browser agent start --user-agent "MyBot/1.0"
 agentic-browser agent status
-agentic-browser agent run navigate '{"url":"https://example.com"}'
-agentic-browser agent run interact '{"action":"click","selector":"#login"}'
+agentic-browser agent navigate https://example.com
+agentic-browser agent click "#login"
 agentic-browser agent content --mode text
 agentic-browser agent content --mode html --selector main
 agentic-browser agent elements
@@ -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 and fallback selectors usable in `agent run interact`:
+Returns a JSON array of elements with CSS selectors and fallback selectors usable in the typed agent commands like `agent click`, `agent type`, and `agent select`:
 
 ```json
 {
@@ -152,7 +152,7 @@ Returns a JSON array of elements with CSS selectors and fallback selectors usabl
 }
 ```
 
-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 responses are compact — `visible`, `actions`, and `tagName` are omitted to reduce token usage, and `enabled` is omitted when it is `true`. Responses also include a `summary` block with `countsByRole` and `primaryActions` so an LLM can identify the main controls faster. The full element shape is available via the programmatic API.
 
 ````
 
@@ -255,7 +255,7 @@ agentic-browser memory:stats
 
 1. `agent start` — launch Chrome and persist session.
 2. `agent elements` — discover what's on the page.
-3. `agent run navigate/interact` — execute actions using discovered selectors.
+3. `agent navigate`, `agent click`, `agent type`, `agent select`, and related typed commands — execute actions using discovered selectors.
 4. `agent content` — read page content after actions.
 5. `agent memory-search` — reuse known selectors for repeated tasks.
 6. `agent stop` — terminate when done.
@@ -265,7 +265,7 @@ agentic-browser memory:stats
 - Exactly **one** managed session is supported at a time.
 - Session state is persisted in `.agentic-browser/`.
 - All commands print exactly one JSON line to `stdout`.
-- `payloadJson` must be valid JSON.
+- The typed `agent` commands are the preferred interface for LLMs. Use low-level `command:run` only when you need raw JSON payload control.
 - Parse only `stdout` as result object and use exit code for success/failure.
 
 ## Programmatic API

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as createCliRuntime } from "../runtime-C7B024bN.mjs";
+import { r as createCliRuntime } from "../runtime-DUSoQl5x.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -64,7 +64,7 @@ async function agentStop(runtime) {
 		sessionId
 	};
 }
-async function agentRun(runtime, input) {
+async function executeAgentCommand(runtime, input) {
 	const sessionId = requireSessionId(runtime);
 	await ensureReady(runtime, sessionId);
 	const attempt = () => runtime.api.executeCommand(sessionId, {
@@ -75,22 +75,75 @@ async function agentRun(runtime, input) {
 	try {
 		const first = await attempt();
 		if (first.resultStatus === "failed") throw new Error(first.resultMessage ?? "Command failed");
-		return {
-			ok: true,
-			action: "run",
-			...first
-		};
+		return first;
 	} catch {
 		await runtime.api.restartSession(sessionId);
 		const second = await attempt();
 		if (second.resultStatus === "failed") throw new Error(second.resultMessage ?? "Command failed after retry");
-		return {
-			ok: true,
-			action: "run",
-			...second
-		};
+		return second;
 	}
 }
+async function agentNavigate(runtime, input) {
+	const result = await executeAgentCommand(runtime, {
+		type: "navigate",
+		payload: { url: input.url }
+	});
+	let cookieBanner;
+	if (result.resultStatus === "success") try {
+		const sessionId = requireSessionId(runtime);
+		const dismissed = await runtime.api.dismissCookieBanner(sessionId);
+		if (dismissed.dismissed) cookieBanner = dismissed;
+	} catch {}
+	return {
+		ok: true,
+		action: "navigate",
+		...result,
+		cookieBanner
+	};
+}
+async function agentInteract(runtime, input) {
+	const result = await executeAgentCommand(runtime, {
+		type: "interact",
+		payload: input
+	});
+	return {
+		ok: true,
+		action: input.action,
+		...result
+	};
+}
+async function agentRestart(runtime) {
+	return {
+		ok: true,
+		action: "restart",
+		...await executeAgentCommand(runtime, {
+			type: "restart",
+			payload: {}
+		})
+	};
+}
+async function agentTerminate(runtime) {
+	const result = await executeAgentCommand(runtime, {
+		type: "terminate",
+		payload: {}
+	});
+	saveState(runtime, { sessionId: null });
+	return {
+		ok: true,
+		action: "terminate",
+		...result
+	};
+}
+async function agentDismissCookies(runtime) {
+	const sessionId = requireSessionId(runtime);
+	await ensureReady(runtime, sessionId);
+	return {
+		ok: true,
+		action: "cookies",
+		sessionId,
+		...await runtime.api.dismissCookieBanner(sessionId)
+	};
+}
 async function agentContent(runtime, input) {
 	const sessionId = requireSessionId(runtime);
 	await ensureReady(runtime, sessionId);
@@ -243,6 +296,7 @@ async function main() {
 	const runtime = createCliRuntime();
 	const program = new Command();
 	program.name("agentic-browser").description("Agentic browser CLI");
+	const collect = (value, previous = []) => [...previous, value];
 	program.command("session:start").option("--cdp-url <url>", "connect to existing Chrome via CDP endpoint URL").option("--user-profile <path>", "use 'default' for system Chrome profile or an absolute path").option("--headless", "run Chrome in headless mode (no visible window)").option("--user-agent <string>", "override the browser user-agent string").action(async (options) => {
 		if (options.cdpUrl) runtime.context.config.cdpUrl = options.cdpUrl;
 		if (options.userProfile) runtime.context.config.userProfileDir = options.userProfile === "true" || options.userProfile === "default" ? "default" : options.userProfile;
@@ -328,13 +382,109 @@ async function main() {
 		const result = await agentStop(runtime);
 		console.log(JSON.stringify(result));
 	});
-	agent.command("run").argument("<type>", "navigate|interact|restart|terminate").argument("<payloadJson>", "JSON payload").action(async (type, payloadJson) => {
-		const result = await agentRun(runtime, {
-			type,
-			payload: JSON.parse(payloadJson)
+	agent.command("navigate").argument("<url>").action(async (url) => {
+		const result = await agentNavigate(runtime, { url });
+		console.log(JSON.stringify(result));
+	});
+	agent.command("click").argument("<selector>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, options) => {
+		const result = await agentInteract(runtime, {
+			action: "click",
+			selector,
+			fallbackSelectors: options.fallback
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("type").argument("<selector>").argument("<text>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, text, options) => {
+		const result = await agentInteract(runtime, {
+			action: "type",
+			selector,
+			text,
+			fallbackSelectors: options.fallback
 		});
 		console.log(JSON.stringify(result));
 	});
+	agent.command("press").argument("<key>").action(async (key) => {
+		const result = await agentInteract(runtime, {
+			action: "press",
+			key
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("wait").argument("<selector>").option("--timeout <ms>", "timeout in milliseconds", "2000").action(async (selector, options) => {
+		const result = await agentInteract(runtime, {
+			action: "waitFor",
+			selector,
+			timeoutMs: Number.parseInt(options.timeout, 10)
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("hover").argument("<selector>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, options) => {
+		const result = await agentInteract(runtime, {
+			action: "hover",
+			selector,
+			fallbackSelectors: options.fallback
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("select").argument("<selector>").argument("<value>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, value, options) => {
+		const result = await agentInteract(runtime, {
+			action: "select",
+			selector,
+			value,
+			fallbackSelectors: options.fallback
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("toggle").argument("<selector>").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, options) => {
+		const result = await agentInteract(runtime, {
+			action: "toggle",
+			selector,
+			fallbackSelectors: options.fallback
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("scroll").option("--x <pixels>", "horizontal scroll delta", "0").option("--y <pixels>", "vertical scroll delta", "0").option("--selector <selector>", "scroll a specific element instead of the page").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (options) => {
+		const result = await agentInteract(runtime, {
+			action: "scroll",
+			selector: options.selector,
+			fallbackSelectors: options.fallback,
+			scrollX: Number.parseInt(options.x, 10),
+			scrollY: Number.parseInt(options.y, 10)
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("back").action(async () => {
+		const result = await agentInteract(runtime, { action: "goBack" });
+		console.log(JSON.stringify(result));
+	});
+	agent.command("forward").action(async () => {
+		const result = await agentInteract(runtime, { action: "goForward" });
+		console.log(JSON.stringify(result));
+	});
+	agent.command("refresh").action(async () => {
+		const result = await agentInteract(runtime, { action: "refresh" });
+		console.log(JSON.stringify(result));
+	});
+	agent.command("dialog").option("--dismiss", "dismiss the current dialog").option("--value <text>", "prompt response text").action(async (options) => {
+		const result = await agentInteract(runtime, {
+			action: "dialog",
+			text: options.dismiss ? "dismiss" : void 0,
+			value: options.value
+		});
+		console.log(JSON.stringify(result));
+	});
+	agent.command("cookies").action(async () => {
+		const result = await agentDismissCookies(runtime);
+		console.log(JSON.stringify(result));
+	});
+	agent.command("restart").action(async () => {
+		const result = await agentRestart(runtime);
+		console.log(JSON.stringify(result));
+	});
+	agent.command("terminate").action(async () => {
+		const result = await agentTerminate(runtime);
+		console.log(JSON.stringify(result));
+	});
 	agent.command("content").option("--mode <mode>", "title|text|html|a11y", "text").option("--selector <selector>", "optional CSS selector").action(async (options) => {
 		const result = await agentContent(runtime, options);
 		console.log(JSON.stringify(result));

package/dist/index.mjs

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

package/dist/mcp/index.mjs

@@ -1,9 +1,163 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-C7B024bN.mjs";
+import { n as createAgenticBrowserCore } from "../runtime-DUSoQl5x.mjs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+//#region src/mcp/response-helpers.ts
+function uniqueLines(content, maxLineLength = 160) {
+	const seen = /* @__PURE__ */ new Set();
+	const lines = [];
+	for (const raw of content.split("\n")) {
+		const line = raw.replace(/\s+/g, " ").trim();
+		if (!line || seen.has(line)) continue;
+		seen.add(line);
+		lines.push(line.slice(0, maxLineLength));
+	}
+	return lines;
+}
+function truncateContent(content, limit) {
+	if (!limit || content.length <= limit) return {
+		content,
+		truncated: false
+	};
+	const originalLength = content.length;
+	return {
+		content: content.slice(0, limit) + `\n\n[Truncated — showing first ${limit} of ${originalLength} characters. Use a CSS selector to scope the content.]`,
+		truncated: true
+	};
+}
+function summarizeTextContent(content) {
+	const lines = uniqueLines(content);
+	return {
+		summaryLines: lines.slice(0, 8),
+		previewLines: lines.slice(0, 20)
+	};
+}
+function summarizeA11yContent(content) {
+	const lines = uniqueLines(content);
+	const headings = [];
+	const landmarks = [];
+	const actions = [];
+	const inputs = [];
+	for (const line of lines) {
+		const lower = line.toLowerCase();
+		if ((lower.startsWith("heading ") || lower.includes(" heading ")) && headings.length < 8) {
+			headings.push(line);
+			continue;
+		}
+		if ((lower.startsWith("main") || lower.startsWith("navigation") || lower.startsWith("banner") || lower.startsWith("complementary") || lower.startsWith("contentinfo") || lower.startsWith("search")) && landmarks.length < 8) {
+			landmarks.push(line);
+			continue;
+		}
+		if ((lower.includes("button") || lower.includes("link")) && actions.length < 12) {
+			actions.push(line);
+			continue;
+		}
+		if ((lower.includes("textbox") || lower.includes("combobox") || lower.includes("searchbox") || lower.includes("checkbox") || lower.includes("radio")) && inputs.length < 12) inputs.push(line);
+	}
+	return {
+		headings,
+		landmarks,
+		actions,
+		inputs,
+		previewLines: lines.slice(0, 30)
+	};
+}
+function compactPageContent(result, maxChars) {
+	const limit = maxChars ?? {
+		text: 8e3,
+		a11y: 1e4,
+		html: 4e3,
+		title: void 0
+	}[result.mode];
+	const truncated = truncateContent(result.content, limit);
+	if (result.mode === "title") return {
+		...result,
+		truncated: false
+	};
+	if (result.mode === "text") {
+		const summary = summarizeTextContent(truncated.content);
+		return {
+			mode: result.mode,
+			content: truncated.content,
+			truncated: truncated.truncated,
+			summaryLines: summary.summaryLines,
+			previewLines: summary.previewLines
+		};
+	}
+	if (result.mode === "a11y") {
+		const summary = summarizeA11yContent(truncated.content);
+		return {
+			mode: result.mode,
+			content: truncated.content,
+			truncated: truncated.truncated,
+			headings: summary.headings,
+			landmarks: summary.landmarks,
+			actions: summary.actions,
+			inputs: summary.inputs,
+			previewLines: summary.previewLines
+		};
+	}
+	return {
+		mode: result.mode,
+		content: truncated.content,
+		truncated: truncated.truncated
+	};
+}
+function summarizeElements(elements) {
+	const byRole = /* @__PURE__ */ new Map();
+	const primaryActions = [];
+	for (const element of elements) {
+		const role = String(element.role ?? "unknown");
+		byRole.set(role, (byRole.get(role) ?? 0) + 1);
+		if (primaryActions.length < 12 && typeof element.selector === "string" && typeof element.text === "string" && element.text) primaryActions.push({
+			role,
+			text: element.text,
+			selector: element.selector,
+			fallbackSelectors: element.fallbackSelectors
+		});
+	}
+	return {
+		countsByRole: Object.fromEntries([...byRole.entries()].sort((a, b) => b[1] - a[1])),
+		primaryActions
+	};
+}
+function compactElement(element, visibleOnly) {
+	const compact = { ...element };
+	if (visibleOnly) delete compact.visible;
+	delete compact.actions;
+	delete compact.tagName;
+	if (compact.enabled === true) delete compact.enabled;
+	if (!compact.text) delete compact.text;
+	if (compact.ariaLabel && compact.ariaLabel === compact.text) delete compact.ariaLabel;
+	if (compact.placeholder && compact.placeholder === compact.text) delete compact.placeholder;
+	return compact;
+}
+function compactInteractiveElementsResult(result, visibleOnly) {
+	const elements = result.elements.map((el) => compactElement(el, visibleOnly));
+	return {
+		elements,
+		totalFound: result.totalFound,
+		truncated: result.truncated,
+		summary: summarizeElements(elements)
+	};
+}
+function compactMemoryResults(results) {
+	return { results: 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;
+	}) };
+}
+
+//#endregion
 //#region src/mcp/index.ts
 let core;
 let activeSessionId;
@@ -48,9 +202,15 @@ server.tool("browser_navigate", "Navigate the browser to a URL. A session is aut
 		type: "navigate",
 		payload: { url }
 	});
+	let cookieBanner;
+	if (result.resultStatus === "success") try {
+		const dismissed = await getCore().dismissCookieBanner(sid);
+		if (dismissed.dismissed) cookieBanner = dismissed;
+	} catch {}
 	const compact = {
 		resultStatus: result.resultStatus,
-		resultMessage: result.resultMessage
+		resultMessage: result.resultMessage,
+		cookieBanner
 	};
 	return { content: [{
 		type: "text",
@@ -124,30 +284,9 @@ server.tool("browser_get_content", "Get the current page content. Modes: \"text\
 		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,
-			truncated: false
-		})
+		text: JSON.stringify(compactPageContent(result, maxChars))
 	}] };
 });
 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.", {
@@ -175,21 +314,9 @@ 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({
-			elements: compactElements,
-			totalFound: result.totalFound,
-			truncated: result.truncated
-		})
+		text: JSON.stringify(compactInteractiveElementsResult(result, visibleOnly))
 	}] };
 });
 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.", {
@@ -197,24 +324,14 @@ server.tool("browser_search_memory", "Search task memory for previously learned
 	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 compactResults = getCore().searchMemory({
+	const result = 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({ results: compactResults })
+		text: JSON.stringify(compactMemoryResults(result.results))
 	}] };
 });
 server.tool("browser_dismiss_cookies", "Dismiss cookie consent banners on the current page. Uses the accessibility tree first (most robust), then falls back to known CSS selectors and text-based button matching. Supports banners in English, German, French, Spanish, Italian, Dutch, and Portuguese. Call this after navigating to a new page. A session is auto-started if needed.", { sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)") }, async ({ sessionId }) => {
@@ -253,6 +370,9 @@ async function main() {
 			} catch {}
 			activeSessionId = void 0;
 		}
+		try {
+			getCore().context.memoryService.flushSync();
+		} catch {}
 		try {
 			getCore().sessions.cleanupSessions({ maxAgeDays: 0 });
 		} catch {}

package/dist/{runtime-C7B024bN.mjs → runtime-DUSoQl5x.mjs}

@@ -50,6 +50,7 @@ var CdpConnection = class CdpConnection {
 		return new CdpConnection(ws);
 	}
 	async send(method, params, timeoutMs = 15e3) {
+		if (this.ws.readyState !== WebSocket.OPEN) throw new Error(`WebSocket not open (state=${this.ws.readyState}), cannot send '${method}'`);
 		const id = ++this.nextId;
 		const payload = {
 			id,
@@ -106,8 +107,8 @@ var CdpConnection = class CdpConnection {
 		this.ws.close();
 	}
 };
-async function getJson(url) {
-	const response = await fetch(url);
+async function getJson(url, timeoutMs = 5e3) {
+	const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
 	if (!response.ok) throw new Error(`HTTP ${response.status}: ${url}`);
 	return await response.json();
 }
@@ -202,9 +203,15 @@ function resolveDefaultProfileDir() {
 }
 var ChromeCdpBrowserController = class {
 	connections = /* @__PURE__ */ new Map();
+	cleanupInterval;
 	constructor(baseDir, connectionFactory = CdpConnection.connect) {
 		this.baseDir = baseDir;
 		this.connectionFactory = connectionFactory;
+		this.cleanupInterval = setInterval(() => {
+			const cutoff = Date.now() - 300 * 1e3;
+			for (const [url, entry] of this.connections) if (entry.lastUsedAt < cutoff) this.dropConnection(url);
+		}, 6e4);
+		this.cleanupInterval.unref();
 	}
 	async getConnection(targetWsUrl) {
 		const cached = this.connections.get(targetWsUrl);
@@ -354,7 +361,8 @@ var ChromeCdpBrowserController = class {
 			await this.ensureEnabled(targetWsUrl);
 			const navigatedPromise = conn.waitForEvent("Page.frameNavigated", 6e3).catch(() => void 0);
 			const loadPromise = Promise.race([conn.waitForEvent("Page.loadEventFired", 6e3), conn.waitForEvent("Page.frameStoppedLoading", 6e3)]);
-			await conn.send("Page.navigate", { url });
+			const navResult = await conn.send("Page.navigate", { url });
+			if (navResult.errorText) throw new Error(`Navigation failed: ${navResult.errorText}`);
 			const navigatedEvent = await navigatedPromise;
 			try {
 				await loadPromise;
@@ -924,10 +932,17 @@ var ChromeCdpBrowserController = class {
 	* Returns silently on failure — never blocks navigation.
 	*/
 	async dismissCookieBanner(targetWsUrl) {
+		try {
+			const domResult = await this.dismissViaDom(targetWsUrl);
+			if (domResult.dismissed) return domResult;
+		} catch {}
 		try {
 			const a11yResult = await this.dismissViaA11y(targetWsUrl);
 			if (a11yResult.dismissed) return a11yResult;
 		} catch {}
+		return { dismissed: false };
+	}
+	async dismissViaDom(targetWsUrl) {
 		const expression = `(() => {
       // Common cookie-consent button selectors (ordered by specificity)
       const selectors = [
@@ -988,22 +1003,18 @@ var ChromeCdpBrowserController = class {
 
       return JSON.stringify({ dismissed: false });
     })()`;
-		try {
-			return await this.withRetry(targetWsUrl, async (conn) => {
-				await this.ensureEnabled(targetWsUrl);
-				const raw = (await conn.send("Runtime.evaluate", {
-					expression,
-					returnByValue: true
-				})).result.value ?? "{\"dismissed\":false}";
-				try {
-					return JSON.parse(raw);
-				} catch {
-					return { dismissed: false };
-				}
-			});
-		} catch {
-			return { dismissed: false };
-		}
+		return await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			const raw = (await conn.send("Runtime.evaluate", {
+				expression,
+				returnByValue: true
+			})).result.value ?? "{\"dismissed\":false}";
+			try {
+				return JSON.parse(raw);
+			} catch {
+				return { dismissed: false };
+			}
+		});
 	}
 	/**
 	* Use the CDP Accessibility tree to find and click consent buttons.
@@ -1172,6 +1183,7 @@ var MockBrowserController = class {
 //#region src/session/session-store.ts
 var SessionStore = class {
 	filePath;
+	cache = null;
 	constructor(baseDir) {
 		fs.mkdirSync(baseDir, { recursive: true });
 		this.filePath = path.join(baseDir, "sessions.json");
@@ -1239,9 +1251,19 @@ var SessionStore = class {
 		this.write(state);
 	}
 	read() {
-		return JSON.parse(fs.readFileSync(this.filePath, "utf8"));
+		if (this.cache) return this.cache;
+		try {
+			const parsed = JSON.parse(fs.readFileSync(this.filePath, "utf8"));
+			this.cache = parsed;
+			return parsed;
+		} catch {
+			const empty = { sessions: {} };
+			this.write(empty);
+			return empty;
+		}
 	}
 	write(state) {
+		this.cache = state;
 		fs.writeFileSync(this.filePath, JSON.stringify(state, null, 2), "utf8");
 	}
 };
@@ -1691,7 +1713,7 @@ function loadConfig(env = process.env) {
 		wsPort,
 		commandTimeoutMs,
 		logDir: env.AGENTIC_BROWSER_LOG_DIR ?? path.resolve(process.cwd(), ".agentic-browser"),
-		browserExecutablePath: env.AGENTIC_BROWSER_CHROME_PATH,
+		browserExecutablePath: env.AGENTIC_BROWSER_CHROME_EXECUTABLE_PATH ?? env.AGENTIC_BROWSER_CHROME_PATH,
 		cdpUrl: env.AGENTIC_BROWSER_CDP_URL,
 		userProfileDir,
 		headless: env.AGENTIC_BROWSER_HEADLESS === "true" || env.AGENTIC_BROWSER_HEADLESS === "1",
@@ -1733,54 +1755,55 @@ var Logger = class {
 
 //#endregion
 //#region src/observability/event-store.ts
+const MAX_EVENTS_PER_SESSION = 500;
 var EventStore = class {
 	events = /* @__PURE__ */ new Map();
 	filePath;
 	constructor(baseDir) {
-		this.baseDir = baseDir;
 		fs.mkdirSync(baseDir, { recursive: true });
 		this.filePath = path.join(baseDir, "session-events.log");
 	}
 	append(event) {
-		const existing = this.events.get(event.sessionId) ?? [];
+		let existing = this.events.get(event.sessionId) ?? [];
 		existing.push(event);
+		if (existing.length > MAX_EVENTS_PER_SESSION) existing = existing.slice(-MAX_EVENTS_PER_SESSION);
 		this.events.set(event.sessionId, existing);
-		fs.appendFile(this.filePath, `${JSON.stringify(event)}\n`, "utf8", () => {});
+		fs.appendFileSync(this.filePath, `${JSON.stringify(event)}\n`, "utf8");
 	}
 	list(sessionId, limit = 100) {
 		const entries = this.events.get(sessionId) ?? [];
 		return entries.slice(Math.max(0, entries.length - limit));
 	}
+	clear(sessionId) {
+		this.events.delete(sessionId);
+	}
 };
 
 //#endregion
 //#region src/auth/session-token.ts
 var SessionTokenService = class {
-	bySession = /* @__PURE__ */ new Map();
+	tokens = /* @__PURE__ */ new Map();
 	issue(sessionId) {
 		const token = crypto.randomBytes(24).toString("hex");
-		this.bySession.set(sessionId, { token });
+		this.tokens.set(sessionId, token);
 		return token;
 	}
 	validate(sessionId, token) {
-		const record = this.bySession.get(sessionId);
-		if (!record || record.revokedAt) return false;
-		const expected = Buffer.from(record.token);
-		const provided = Buffer.from(token);
-		if (expected.length !== provided.length) return false;
-		return crypto.timingSafeEqual(expected, provided);
+		const expected = this.tokens.get(sessionId);
+		if (!expected) return false;
+		const expectedBuf = Buffer.from(expected);
+		const providedBuf = Buffer.from(token);
+		if (expectedBuf.length !== providedBuf.length) return false;
+		return crypto.timingSafeEqual(expectedBuf, providedBuf);
 	}
 	revoke(sessionId) {
-		const record = this.bySession.get(sessionId);
-		if (!record) return;
-		record.revokedAt = (/* @__PURE__ */ new Date()).toISOString();
-		this.bySession.set(sessionId, record);
+		this.tokens.delete(sessionId);
 	}
 	get(sessionId) {
-		return this.bySession.get(sessionId)?.token;
+		return this.tokens.get(sessionId);
 	}
 	seed(sessionId, token) {
-		this.bySession.set(sessionId, { token });
+		this.tokens.set(sessionId, token);
 	}
 };
 
@@ -2018,6 +2041,8 @@ const MemoryStateSchema = z.object({ insights: z.array(TaskInsightSchema) });
 //#region src/memory/task-insight-store.ts
 const EMPTY_STATE = { insights: [] };
 const FLUSH_DELAY_MS = 500;
+const REGISTERED_EXIT_HANDLERS = Symbol.for("agentic-browser.task-insight-store.exit-handlers");
+const REGISTERED_STORES = Symbol.for("agentic-browser.task-insight-store.instances");
 var TaskInsightStore = class {
 	filePath;
 	/** In-memory cache – authoritative after first load. */
@@ -2033,16 +2058,7 @@ var TaskInsightStore = class {
 			if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
 		} catch {}
 		if (!fs.existsSync(this.filePath)) this.writeDisk(EMPTY_STATE);
-		const onExit = () => this.flushSync();
-		process.on("exit", onExit);
-		process.on("SIGINT", () => {
-			this.flushSync();
-			process.exit(0);
-		});
-		process.on("SIGTERM", () => {
-			this.flushSync();
-			process.exit(0);
-		});
+		this.registerProcessHandlers();
 	}
 	list() {
 		return this.getCache();
@@ -2082,13 +2098,10 @@ var TaskInsightStore = class {
 	}
 	markDirty() {
 		this.dirty = true;
-		if (!this.flushTimer) {
-			this.flushTimer = setTimeout(() => {
-				this.flushTimer = null;
-				this.flushSync();
-			}, FLUSH_DELAY_MS);
-			if (this.flushTimer && typeof this.flushTimer === "object" && "unref" in this.flushTimer) this.flushTimer.unref();
-		}
+		if (!this.flushTimer) this.flushTimer = setTimeout(() => {
+			this.flushTimer = null;
+			this.flushSync();
+		}, FLUSH_DELAY_MS);
 	}
 	/** Read and validate from disk (only on first load or corruption recovery). */
 	readDisk() {
@@ -2127,6 +2140,25 @@ var TaskInsightStore = class {
 		fs.writeFileSync(tempPath, JSON.stringify(state, null, 2), "utf8");
 		fs.renameSync(tempPath, this.filePath);
 	}
+	registerProcessHandlers() {
+		const proc = process;
+		const stores = proc[REGISTERED_STORES] ??= /* @__PURE__ */ new Set();
+		stores.add(this);
+		if (proc[REGISTERED_EXIT_HANDLERS]) return;
+		proc[REGISTERED_EXIT_HANDLERS] = true;
+		const flushAll = () => {
+			for (const store of stores) store.flushSync();
+		};
+		process.on("exit", flushAll);
+		process.on("SIGINT", () => {
+			flushAll();
+			process.exit(0);
+		});
+		process.on("SIGTERM", () => {
+			flushAll();
+			process.exit(0);
+		});
+	}
 };
 
 //#endregion
@@ -2141,6 +2173,10 @@ var MemoryService = class {
 		this.store = new TaskInsightStore(baseDir);
 		this.index = new MemoryIndex();
 	}
+	/** Force an immediate synchronous flush of pending writes. */
+	flushSync() {
+		this.store.flushSync();
+	}
 	search(input) {
 		const cacheKey = `${input.taskIntent}\0${input.siteDomain ?? ""}\0${input.limit ?? 10}`;
 		const now = Date.now();
@@ -2191,7 +2227,7 @@ var MemoryService = class {
 	}
 	recordSuccess(input) {
 		const insights = this.store.list();
-		const matched = this.findBestExactMatch(insights, input.taskIntent, input.siteDomain);
+		const matched = this.findBestExactMatch(insights, input);
 		const evidence = this.createEvidence(input, "success");
 		if (!matched) {
 			const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -2248,7 +2284,7 @@ var MemoryService = class {
 	}
 	recordFailure(input, errorMessage) {
 		const insights = this.store.list();
-		const matched = this.findBestExactMatch(insights, input.taskIntent, input.siteDomain);
+		const matched = this.findBestExactMatch(insights, input);
 		if (!matched) return;
 		const signal = detectStalenessSignal(errorMessage, input.selector);
 		const evidence = this.createEvidence(input, "failure", errorMessage);
@@ -2261,15 +2297,37 @@ var MemoryService = class {
 		this.invalidateSearchCache();
 		return failed;
 	}
-	findBestExactMatch(insights, taskIntent, siteDomain) {
-		const intentLower = taskIntent.toLowerCase();
-		const domainLower = siteDomain.toLowerCase();
+	findBestExactMatch(insights, input) {
+		const intentLower = input.taskIntent.toLowerCase();
+		const domainLower = input.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;
+			if (!best || this.scoreExactMatch(insight, input) > this.scoreExactMatch(best, input) || this.scoreExactMatch(insight, input) === this.scoreExactMatch(best, input) && insight.updatedAt > best.updatedAt) best = insight;
 		}
 		return best;
 	}
+	scoreExactMatch(insight, input) {
+		let score = 0;
+		if (insight.sitePathPattern === input.sitePathPattern) score += 4;
+		else if (insight.sitePathPattern === "/" || input.sitePathPattern === "/" || this.sameFirstPathSegment(insight.sitePathPattern, input.sitePathPattern)) score += 2;
+		if (input.selector) {
+			if (insight.actionRecipe.some((step) => step.selector === input.selector)) score += 3;
+			if (insight.evidence.some((ev) => ev.selector === input.selector && ev.result === "success")) score += 2;
+			if ((insight.selectorAliases ?? []).some((alias) => alias.selector === input.selector)) score += 1;
+		}
+		score += Math.min(insight.successCount, 5) * .1;
+		score -= Math.min(insight.failureCount, 5) * .1;
+		return score;
+	}
+	sameFirstPathSegment(left, right) {
+		const normalize = (value) => {
+			const [firstSegment = ""] = value.replace(/\/\*$/, "").split("/").filter(Boolean);
+			return firstSegment.toLowerCase();
+		};
+		const leftSegment = normalize(left);
+		const rightSegment = normalize(right);
+		return Boolean(leftSegment) && leftSegment === rightSegment;
+	}
 	createEvidence(input, result, reason) {
 		return {
 			evidenceId: crypto.randomUUID(),

package/package.json

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