agentic-browser 1.2.0 → 1.4.0

package/README.md

@@ -84,6 +84,7 @@ agentic-browser agent start --user-profile /path/to/chrome/profile
 ```
 
 Default profile locations per platform:
+
 - **macOS:** `~/Library/Application Support/Google/Chrome`
 - **Linux:** `~/.config/google-chrome`
 - **Windows:** `%LOCALAPPDATA%\Google\Chrome\User Data`
@@ -92,10 +93,12 @@ Default profile locations per platform:
 
 These options can also be set via environment variables (CLI flags take precedence):
 
-| Variable                       | Example                        | Description                     |
-| ------------------------------ | ------------------------------ | ------------------------------- |
+| Variable                       | Example                       | Description                     |
+| ------------------------------ | ----------------------------- | ------------------------------- |
 | `AGENTIC_BROWSER_CDP_URL`      | `http://127.0.0.1:9222`       | Connect to a running Chrome     |
-| `AGENTIC_BROWSER_USER_PROFILE` | `default` or an absolute path  | Launch with a real profile      |
+| `AGENTIC_BROWSER_USER_PROFILE` | `default` or an absolute path | Launch with a real profile      |
+| `AGENTIC_BROWSER_HEADLESS`     | `true`                        | Run Chrome in headless mode     |
+| `AGENTIC_BROWSER_USER_AGENT`   | `MyBot/1.0`                   | Override the browser user-agent |
 
 ## Agent Commands (Recommended for LLMs)
 
@@ -105,6 +108,8 @@ The `agent` subcommand manages session state, auto-restarts on disconnect, gener
 agentic-browser agent start
 agentic-browser agent start --cdp-url http://127.0.0.1:9222
 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"}'
@@ -184,6 +189,8 @@ For direct control without session state management:
 agentic-browser session:start
 agentic-browser session:start --cdp-url http://127.0.0.1:9222
 agentic-browser session:start --user-profile default
+agentic-browser session:start --headless
+agentic-browser session:start --user-agent "MyBot/1.0"
 ```
 
 ### 2. Read Session Status

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as createCliRuntime } from "../runtime-D6awVhGy.mjs";
+import { r as createCliRuntime } from "../runtime-CODdeRWR.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -243,9 +243,11 @@ async function main() {
 	const runtime = createCliRuntime();
 	const program = new Command();
 	program.name("agentic-browser").description("Agentic browser CLI");
-	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").action(async (options) => {
+	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;
+		if (options.headless) runtime.context.config.headless = true;
+		if (options.userAgent) runtime.context.config.userAgent = options.userAgent;
 		const result = await runSessionStart(runtime, { browser: "chrome" });
 		console.log(JSON.stringify(result));
 	});
@@ -281,7 +283,7 @@ async function main() {
 		});
 		console.log(JSON.stringify(result));
 	});
-	program.command("page:content").argument("<sessionId>").option("--mode <mode>", "title|text|html", "text").option("--selector <selector>", "optional CSS selector").action(async (sessionId, options) => {
+	program.command("page:content").argument("<sessionId>").option("--mode <mode>", "title|text|html|a11y", "text").option("--selector <selector>", "optional CSS selector").action(async (sessionId, options) => {
 		const result = await runPageContent(runtime, {
 			sessionId,
 			mode: options.mode,
@@ -310,9 +312,11 @@ async function main() {
 		console.log(JSON.stringify(result));
 	});
 	const agent = program.command("agent").description("Stateful agent wrapper with session persistence and auto-retry");
-	agent.command("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").action(async (options) => {
+	agent.command("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;
+		if (options.headless) runtime.context.config.headless = true;
+		if (options.userAgent) runtime.context.config.userAgent = options.userAgent;
 		const result = await agentStart(runtime);
 		console.log(JSON.stringify(result));
 	});
@@ -331,7 +335,7 @@ async function main() {
 		});
 		console.log(JSON.stringify(result));
 	});
-	agent.command("content").option("--mode <mode>", "title|text|html", "text").option("--selector <selector>", "optional CSS selector").action(async (options) => {
+	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-D6awVhGy.mjs";
+import { i as createMockAgenticBrowserCore, n as createAgenticBrowserCore, t as AgenticBrowserCore } from "./runtime-CODdeRWR.mjs";
 
 export { AgenticBrowserCore, createAgenticBrowserCore, createMockAgenticBrowserCore };

package/dist/mcp/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-D6awVhGy.mjs";
+import { n as createAgenticBrowserCore } from "../runtime-CODdeRWR.mjs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -14,11 +14,21 @@ function getCore() {
 function genId(prefix) {
 	return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
+/**
+* Resolve a session ID — auto-starts a session if none exists.
+* This means the LLM never has to call browser_start_session explicitly.
+*/
+async function resolveSession(sessionId) {
+	if (sessionId) return sessionId;
+	if (activeSessionId) return activeSessionId;
+	activeSessionId = (await getCore().startSession()).sessionId;
+	return activeSessionId;
+}
 const server = new McpServer({
 	name: "agentic-browser",
 	version: "0.1.0"
 });
-server.tool("browser_start_session", "Start a Chrome browser session for web automation. Call this first before using any other browser tool. Returns a sessionId you'll need for all subsequent calls.", {}, async () => {
+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;
 	return { content: [{
@@ -26,12 +36,11 @@ server.tool("browser_start_session", "Start a Chrome browser session for web aut
 		text: JSON.stringify(session)
 	}] };
 });
-server.tool("browser_navigate", "Navigate the browser to a URL. The browser must have an active session.", {
+server.tool("browser_navigate", "Navigate the browser to a URL. A session is auto-started if needed.", {
 	url: z.string().describe("The URL to navigate to"),
-	sessionId: z.string().optional().describe("Session ID (uses active session if omitted)")
+	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
 }, async ({ url, sessionId }) => {
-	const sid = sessionId ?? activeSessionId;
-	if (!sid) throw new Error("No active session. Call browser_start_session first.");
+	const sid = await resolveSession(sessionId);
 	const result = await getCore().runCommand({
 		sessionId: sid,
 		commandId: genId("nav"),
@@ -43,25 +52,34 @@ server.tool("browser_navigate", "Navigate the browser to a URL. The browser must
 		text: JSON.stringify(result)
 	}] };
 });
-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).", {
+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.", {
 	action: z.enum([
 		"click",
 		"type",
 		"press",
-		"waitFor"
+		"waitFor",
+		"scroll",
+		"hover",
+		"select",
+		"toggle"
 	]).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)"),
 	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)"),
+	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 (uses active session if omitted)")
-}, async ({ action, selector, text, key, timeoutMs, sessionId }) => {
-	const sid = sessionId ?? activeSessionId;
-	if (!sid) throw new Error("No active session. Call browser_start_session first.");
+	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
+}, async ({ action, selector, text, key, value, scrollX, scrollY, timeoutMs, sessionId }) => {
+	const sid = await resolveSession(sessionId);
 	const payload = { action };
 	if (selector) payload.selector = selector;
 	if (text) payload.text = text;
 	if (key) payload.key = key;
+	if (value) payload.value = value;
+	if (scrollX !== void 0) payload.scrollX = scrollX;
+	if (scrollY !== void 0) payload.scrollY = scrollY;
 	if (timeoutMs) payload.timeoutMs = timeoutMs;
 	const result = await getCore().runCommand({
 		sessionId: sid,
@@ -74,17 +92,17 @@ server.tool("browser_interact", "Interact with a page element. Actions: \"click\
 		text: JSON.stringify(result)
 	}] };
 });
-server.tool("browser_get_content", "Get the current page content. Modes: \"title\" (page title only), \"text\" (readable text content), \"html\" (raw HTML). Use selector to scope to a specific element.", {
+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.", {
 	mode: z.enum([
 		"title",
 		"text",
-		"html"
+		"html",
+		"a11y"
 	]).default("text").describe("Content extraction mode"),
 	selector: z.string().optional().describe("CSS selector to scope content (e.g. \"main\", \"#content\")"),
-	sessionId: z.string().optional().describe("Session ID (uses active session if omitted)")
+	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
 }, async ({ mode, selector, sessionId }) => {
-	const sid = sessionId ?? activeSessionId;
-	if (!sid) throw new Error("No active session. Call browser_start_session first.");
+	const sid = await resolveSession(sessionId);
 	const result = await getCore().getPageContent({
 		sessionId: sid,
 		mode,
@@ -95,7 +113,7 @@ server.tool("browser_get_content", "Get the current page content. Modes: \"title
 		text: JSON.stringify(result)
 	}] };
 });
-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. Call this to understand what's on the page before interacting.", {
+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.", {
 	roles: z.array(z.enum([
 		"link",
 		"button",
@@ -110,10 +128,9 @@ server.tool("browser_get_elements", "Discover all interactive elements on the cu
 	visibleOnly: z.boolean().default(true).describe("Only return visible elements"),
 	limit: z.number().default(50).describe("Maximum number of elements to return"),
 	selector: z.string().optional().describe("CSS selector to scope element discovery to a subtree"),
-	sessionId: z.string().optional().describe("Session ID (uses active session if omitted)")
+	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
 }, async ({ roles, visibleOnly, limit, selector, sessionId }) => {
-	const sid = sessionId ?? activeSessionId;
-	if (!sid) throw new Error("No active session. Call browser_start_session first.");
+	const sid = await resolveSession(sessionId);
 	const result = await getCore().getInteractiveElements({
 		sessionId: sid,
 		roles,
@@ -141,9 +158,15 @@ server.tool("browser_search_memory", "Search task memory for previously learned
 		text: JSON.stringify(result)
 	}] };
 });
-server.tool("browser_stop_session", "Stop the browser session and terminate Chrome. Call this when you're done with browser automation.", { sessionId: z.string().optional().describe("Session ID (uses active session if omitted)") }, async ({ sessionId }) => {
+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 }) => {
 	const sid = sessionId ?? activeSessionId;
-	if (!sid) throw new Error("No active session.");
+	if (!sid) return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			ok: true,
+			message: "No active session to stop."
+		})
+	}] };
 	await getCore().stopSession(sid);
 	if (activeSessionId === sid) activeSessionId = void 0;
 	return { content: [{
@@ -163,6 +186,9 @@ async function main() {
 			} catch {}
 			activeSessionId = void 0;
 		}
+		try {
+			getCore().sessions.cleanupSessions({ maxAgeDays: 0 });
+		} catch {}
 	};
 	await server.connect(transport);
 }

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

@@ -101,12 +101,34 @@ async function getJson(url) {
 	if (!response.ok) throw new Error(`HTTP ${response.status}: ${url}`);
 	return await response.json();
 }
+/** Check if the debug port is accepting TCP connections (faster than an HTTP fetch). */
+function probePort(port) {
+	return new Promise((resolve) => {
+		const socket = net.createConnection({
+			host: "127.0.0.1",
+			port
+		});
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve(true);
+		});
+		socket.once("error", () => {
+			socket.destroy();
+			resolve(false);
+		});
+	});
+}
 async function waitForDebugger(port) {
-	for (let i = 0; i < 60; i += 1) try {
-		await getJson(`http://127.0.0.1:${port}/json/version`);
-		return;
-	} catch {
-		await new Promise((resolve) => setTimeout(resolve, 250));
+	const maxMs = 15e3;
+	const start = Date.now();
+	let delay = 50;
+	while (Date.now() - start < maxMs) {
+		if (await probePort(port)) try {
+			await getJson(`http://127.0.0.1:${port}/json/version`);
+			return;
+		} catch {}
+		await new Promise((resolve) => setTimeout(resolve, delay));
+		delay = Math.min(delay * 2, 250);
 	}
 	throw new Error("Chrome debug endpoint did not become ready in time");
 }
@@ -128,6 +150,15 @@ 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) {
 	const conn = await CdpConnection.connect(targetWsUrl);
 	try {
@@ -199,13 +230,14 @@ var ChromeCdpBrowserController = class {
 	closeConnection(targetWsUrl) {
 		this.dropConnection(targetWsUrl);
 	}
-	async connect(cdpUrl) {
+	async connect(cdpUrl, options) {
 		const parsed = new URL(cdpUrl);
 		const port = Number.parseInt(parsed.port, 10);
 		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);
 		return {
 			pid: 0,
 			cdpUrl,
@@ -224,7 +256,8 @@ var ChromeCdpBrowserController = class {
 			cached.enabled.runtime = true;
 		}
 	}
-	async launch(sessionId, explicitPath, userProfileDir) {
+	async launch(sessionId, options) {
+		const { executablePath: explicitPath, userProfileDir, headless, userAgent } = options ?? {};
 		const executablePath = discoverChrome(explicitPath);
 		const extension = loadControlExtension();
 		let profileDir;
@@ -234,7 +267,10 @@ var ChromeCdpBrowserController = class {
 		fs.mkdirSync(profileDir, { recursive: true });
 		const lockFile = path.join(profileDir, "SingletonLock");
 		if (fs.existsSync(lockFile)) throw new Error(`Chrome profile is already in use (lock file exists: ${lockFile}). Quit the running Chrome instance first, or use --cdp-url to connect to it instead.`);
-		const launchAttempts = [
+		const launchAttempts = headless ? [{
+			withExtension: false,
+			headless: true
+		}] : [
 			{
 				withExtension: true,
 				headless: false
@@ -271,6 +307,7 @@ var ChromeCdpBrowserController = class {
 				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);
 				return {
 					pid: child.pid,
 					cdpUrl,
@@ -285,36 +322,31 @@ var ChromeCdpBrowserController = class {
 		}
 		throw new Error(lastError?.message ?? "Unable to launch Chrome");
 	}
-	async navigate(targetWsUrl, url) {
+	/** Execute fn with a pooled connection; on failure drop connection and retry once. */
+	async withRetry(targetWsUrl, fn) {
 		let conn = await this.getConnection(targetWsUrl);
 		try {
-			await this.ensureEnabled(targetWsUrl);
-			const loadPromise = Promise.race([conn.waitForEvent("Page.loadEventFired", 6e3), conn.waitForEvent("Page.frameStoppedLoading", 6e3)]);
-			await conn.send("Page.navigate", { url });
-			try {
-				await loadPromise;
-			} catch {}
-			return (await conn.send("Runtime.evaluate", {
-				expression: "window.location.href",
-				returnByValue: true
-			})).result.value ?? url;
+			return await fn(conn);
 		} catch {
 			this.dropConnection(targetWsUrl);
 			conn = await this.getConnection(targetWsUrl);
+			return await fn(conn);
+		}
+	}
+	async navigate(targetWsUrl, url) {
+		return await this.withRetry(targetWsUrl, async (conn) => {
 			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 navigatedEvent = await navigatedPromise;
 			try {
 				await loadPromise;
 			} catch {}
-			return (await conn.send("Runtime.evaluate", {
-				expression: "window.location.href",
-				returnByValue: true
-			})).result.value ?? url;
-		}
+			return navigatedEvent?.frame?.url ?? url;
+		});
 	}
 	async interact(targetWsUrl, payload) {
-		let conn = await this.getConnection(targetWsUrl);
 		const expression = `(async () => {
       const payload = ${JSON.stringify(payload)};
       if (payload.action === 'click') {
@@ -371,33 +403,68 @@ var ChromeCdpBrowserController = class {
         }
         return typeof result === 'string' ? result : JSON.stringify(result);
       }
+      if (payload.action === 'scroll') {
+        if (payload.selector) {
+          const el = document.querySelector(payload.selector);
+          if (!el) throw new Error('Selector not found');
+          el.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0, behavior: 'smooth' });
+          return 'scrolled element';
+        }
+        window.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0, behavior: 'smooth' });
+        return 'scrolled page';
+      }
+      if (payload.action === 'hover') {
+        const el = document.querySelector(payload.selector);
+        if (!el) throw new Error('Selector not found');
+        const rect = el.getBoundingClientRect();
+        const cx = rect.left + rect.width / 2;
+        const cy = rect.top + rect.height / 2;
+        el.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true, clientX: cx, clientY: cy }));
+        el.dispatchEvent(new MouseEvent('mouseover', { bubbles: true, clientX: cx, clientY: cy }));
+        el.dispatchEvent(new MouseEvent('mousemove', { bubbles: true, clientX: cx, clientY: cy }));
+        return 'hovered';
+      }
+      if (payload.action === 'select') {
+        const el = document.querySelector(payload.selector);
+        if (!el) throw new Error('Selector not found');
+        if (el.tagName.toLowerCase() !== 'select') throw new Error('Element is not a <select>');
+        el.value = payload.value ?? '';
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        return 'selected ' + el.value;
+      }
+      if (payload.action === 'toggle') {
+        const el = document.querySelector(payload.selector);
+        if (!el) throw new Error('Selector not found');
+        el.click();
+        const checked = el.checked !== undefined ? el.checked : el.getAttribute('aria-checked') === 'true';
+        return 'toggled to ' + (checked ? 'checked' : 'unchecked');
+      }
       throw new Error('Unsupported interact action');
     })()`;
-		const execute = async (c) => {
+		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
-			const value = (await c.send("Runtime.evaluate", {
+			const value = (await conn.send("Runtime.evaluate", {
 				expression,
 				returnByValue: true,
 				awaitPromise: true
 			})).result.value ?? "";
 			if (payload.action === "click" && value === "clicked") try {
-				await c.waitForEvent("Page.frameStoppedLoading", 500);
+				await conn.waitForEvent("Page.frameNavigated", 50);
+				try {
+					await Promise.race([conn.waitForEvent("Page.loadEventFired", 3e3), conn.waitForEvent("Page.frameStoppedLoading", 3e3)]);
+				} catch {}
 			} catch {}
 			return value;
-		};
-		try {
-			return await execute(conn);
-		} catch {
-			this.dropConnection(targetWsUrl);
-			conn = await this.getConnection(targetWsUrl);
-			return await execute(conn);
-		}
+		});
 	}
 	async getContent(targetWsUrl, options) {
-		const o = JSON.stringify(options);
-		let conn = await this.getConnection(targetWsUrl);
+		if (options.mode === "a11y") return {
+			mode: "a11y",
+			content: await this.getAccessibilityTree(targetWsUrl)
+		};
 		const expression = `(() => {
-      const options = ${o};
+      const options = ${JSON.stringify(options)};
       if (options.mode === 'title') return document.title ?? '';
       if (options.mode === 'html') {
         if (options.selector) {
@@ -412,7 +479,7 @@ var ChromeCdpBrowserController = class {
       }
       return document.body?.innerText ?? '';
     })()`;
-		try {
+		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
 			const content = (await conn.send("Runtime.evaluate", {
 				expression,
@@ -422,25 +489,56 @@ var ChromeCdpBrowserController = class {
 				mode: options.mode,
 				content
 			};
-		} catch {
-			this.dropConnection(targetWsUrl);
-			conn = await this.getConnection(targetWsUrl);
-			await this.ensureEnabled(targetWsUrl);
-			const content = (await conn.send("Runtime.evaluate", {
-				expression,
-				returnByValue: true
-			})).result.value ?? "";
-			return {
-				mode: options.mode,
-				content
+		});
+	}
+	async getAccessibilityTree(targetWsUrl) {
+		return await this.withRetry(targetWsUrl, async (conn) => {
+			await conn.send("Accessibility.enable");
+			const { nodes } = await conn.send("Accessibility.getFullAXTree");
+			const childrenMap = /* @__PURE__ */ new Map();
+			const nodeMap = /* @__PURE__ */ new Map();
+			for (const node of nodes) {
+				nodeMap.set(node.nodeId, node);
+				if (node.parentId) {
+					const siblings = childrenMap.get(node.parentId);
+					if (siblings) siblings.push(node.nodeId);
+					else childrenMap.set(node.parentId, [node.nodeId]);
+				}
+			}
+			const lines = [];
+			const formatNode = (nodeId, depth) => {
+				const node = nodeMap.get(nodeId);
+				if (!node) return;
+				const role = node.role?.value ?? "unknown";
+				const name = node.name?.value ?? "";
+				const value = node.value?.value ?? "";
+				if (node.ignored) {
+					const children = childrenMap.get(nodeId) ?? node.childIds ?? [];
+					for (const childId of children) formatNode(childId, depth);
+					return;
+				}
+				const skip = !name && !value && (role === "generic" || role === "none" || role === "GenericContainer");
+				if (!skip) {
+					let line = `${"  ".repeat(depth)}${role}`;
+					if (name) line += ` "${name}"`;
+					if (value) line += ` value="${value}"`;
+					if (node.properties) {
+						for (const prop of node.properties) if (prop.value.value === true) line += ` [${prop.name}]`;
+						else if (prop.name === "checked" && prop.value.value === "mixed") line += ` [indeterminate]`;
+					}
+					lines.push(line);
+				}
+				const children = childrenMap.get(nodeId) ?? node.childIds ?? [];
+				for (const childId of children) formatNode(childId, skip ? depth : depth + 1);
 			};
-		}
+			const roots = nodes.filter((n) => !n.parentId);
+			for (const root of roots) formatNode(root.nodeId, 0);
+			return lines.join("\n");
+		});
 	}
 	async getInteractiveElements(targetWsUrl, options) {
-		const o = JSON.stringify(options);
-		let conn = await this.getConnection(targetWsUrl);
 		const expression = `(() => {
-      const options = ${o};
+      const options = ${JSON.stringify(options)};
       const visibleOnly = options.visibleOnly !== false;
       const limit = options.limit ?? 50;
       const scopeSelector = options.selector;
@@ -649,21 +747,13 @@ var ChromeCdpBrowserController = class {
 			if (v && typeof v === "object" && Array.isArray(v.elements)) return v;
 			return emptyResult;
 		};
-		try {
-			await this.ensureEnabled(targetWsUrl);
-			return extract(await conn.send("Runtime.evaluate", {
-				expression,
-				returnByValue: true
-			}));
-		} catch {
-			this.dropConnection(targetWsUrl);
-			conn = await this.getConnection(targetWsUrl);
+		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
 			return extract(await conn.send("Runtime.evaluate", {
 				expression,
 				returnByValue: true
 			}));
-		}
+		});
 	}
 	terminate(pid) {
 		if (pid === 0) return;
@@ -674,7 +764,7 @@ var ChromeCdpBrowserController = class {
 };
 var MockBrowserController = class {
 	pages = /* @__PURE__ */ new Map();
-	async launch(sessionId) {
+	async launch(sessionId, _options) {
 		const cdpUrl = `mock://${sessionId}`;
 		const targetWsUrl = cdpUrl;
 		this.pages.set(cdpUrl, {
@@ -689,7 +779,7 @@ var MockBrowserController = class {
 			targetWsUrl
 		};
 	}
-	async connect(cdpUrl) {
+	async connect(cdpUrl, _options) {
 		this.pages.set(cdpUrl, {
 			url: "about:blank",
 			title: "about:blank",
@@ -795,6 +885,15 @@ var SessionStore = class {
 		};
 		this.write(state);
 	}
+	/** Remove all terminated sessions from the store. Returns the count removed. */
+	purgeTerminated() {
+		const state = this.read();
+		const before = Object.keys(state.sessions).length;
+		for (const [id, record] of Object.entries(state.sessions)) if (record.session.status === "terminated" && id !== state.activeSessionId) delete state.sessions[id];
+		const removed = before - Object.keys(state.sessions).length;
+		if (removed > 0) this.write(state);
+		return removed;
+	}
 	replaceSessions(sessions, activeSessionId) {
 		const state = {
 			sessions: Object.fromEntries(sessions.map((record) => [record.session.sessionId, record])),
@@ -822,10 +921,18 @@ var SessionManager = class {
 	async createSession(input) {
 		if (input.browser !== "chrome") throw new Error("Only chrome is supported");
 		const active = this.store.getActive();
-		if (active && active.session.status !== "terminated") throw new Error("A managed session is already active");
+		if (active && active.session.status !== "terminated") {
+			if (await this.isSessionAlive(active)) return active.session;
+			await this.forceTerminate(active);
+		}
 		const sessionId = crypto.randomUUID();
 		const token = this.ctx.tokenService.issue(sessionId);
-		const launched = this.ctx.config.cdpUrl ? await this.browser.connect(this.ctx.config.cdpUrl) : await this.browser.launch(sessionId, this.ctx.config.browserExecutablePath, this.ctx.config.userProfileDir);
+		const launched = this.ctx.config.cdpUrl ? await this.browser.connect(this.ctx.config.cdpUrl, { userAgent: this.ctx.config.userAgent }) : await this.browser.launch(sessionId, {
+			executablePath: this.ctx.config.browserExecutablePath,
+			userProfileDir: this.ctx.config.userProfileDir,
+			headless: this.ctx.config.headless,
+			userAgent: this.ctx.config.userAgent
+		});
 		const session = {
 			sessionId,
 			status: "ready",
@@ -845,9 +952,25 @@ var SessionManager = class {
 	getSession(sessionId) {
 		return this.mustGetRecord(sessionId).session;
 	}
+	/** Return a healthy session, recovering automatically if needed. */
+	async ensureSession(sessionId) {
+		const record = this.store.get(sessionId);
+		if (!record) throw new Error("Session not found");
+		if (record.session.status === "ready") {
+			if (await this.isSessionAlive(record)) return record;
+			this.recordEvent(sessionId, "lifecycle", "warning", "Session connection lost, recovering");
+		}
+		if (record.session.status !== "terminated") try {
+			const recovered = await this.restartSession(sessionId);
+			return this.mustGetRecord(recovered.sessionId);
+		} catch (restartError) {
+			this.recordEvent(sessionId, "lifecycle", "error", `Recovery failed: ${restartError.message}`);
+			throw new Error(`Session is not ready and recovery failed: ${restartError.message}`);
+		}
+		throw new Error("Session is terminated. Start a new session.");
+	}
 	async executeCommand(sessionId, input) {
-		const record = this.mustGetRecord(sessionId);
-		if (record.session.status !== "ready") throw new Error("Session is not ready. Restart session and retry.");
+		const record = await this.ensureSession(sessionId);
 		const command = {
 			commandId: input.commandId,
 			sessionId,
@@ -913,13 +1036,11 @@ var SessionManager = class {
 		return completed;
 	}
 	async getContent(sessionId, options) {
-		const record = this.mustGetRecord(sessionId);
-		if (record.session.status !== "ready") throw new Error("Session is not ready");
+		const record = await this.ensureSession(sessionId);
 		return await this.browser.getContent(record.targetWsUrl, options);
 	}
 	async getInteractiveElements(sessionId, options) {
-		const record = this.mustGetRecord(sessionId);
-		if (record.session.status !== "ready") throw new Error("Session is not ready");
+		const record = await this.ensureSession(sessionId);
 		return await this.browser.getInteractiveElements(record.targetWsUrl, options);
 	}
 	setStatus(status, reason) {
@@ -956,11 +1077,18 @@ var SessionManager = class {
 	}
 	async restartSession(sessionId) {
 		const record = this.mustGetRecord(sessionId);
-		if (record.session.status === "ready") return record.session;
 		if (this.browser.closeConnection) try {
 			this.browser.closeConnection(record.targetWsUrl);
 		} catch {}
-		const relaunched = await this.browser.launch(sessionId, this.ctx.config.browserExecutablePath);
+		if (record.pid > 0) try {
+			this.browser.terminate(record.pid);
+		} catch {}
+		const relaunched = this.ctx.config.cdpUrl ? await this.browser.connect(this.ctx.config.cdpUrl, { userAgent: this.ctx.config.userAgent }) : await this.browser.launch(sessionId, {
+			executablePath: this.ctx.config.browserExecutablePath,
+			userProfileDir: this.ctx.config.userProfileDir,
+			headless: this.ctx.config.headless,
+			userAgent: this.ctx.config.userAgent
+		});
 		const restarted = {
 			...record.session,
 			status: "ready",
@@ -1053,6 +1181,40 @@ var SessionManager = class {
 			dryRun
 		};
 	}
+	/** Quick health check — probe the CDP connection with a lightweight evaluate. */
+	async isSessionAlive(record) {
+		if (!record.targetWsUrl) return false;
+		if (record.pid > 0) try {
+			process.kill(record.pid, 0);
+		} catch (err) {
+			if (err.code === "EPERM") {} else return false;
+		}
+		try {
+			await this.browser.getContent(record.targetWsUrl, { mode: "title" });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Force-terminate a session record, cleaning up process, connection, and store. */
+	async forceTerminate(record) {
+		const { sessionId } = record.session;
+		if (this.browser.closeConnection) try {
+			this.browser.closeConnection(record.targetWsUrl);
+		} catch {}
+		if (record.pid > 0) try {
+			this.browser.terminate(record.pid);
+		} catch {}
+		this.ctx.tokenService.revoke(sessionId);
+		const terminated = {
+			...record.session,
+			status: "terminated",
+			endedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		this.store.setSession(terminated);
+		this.store.clearActive(sessionId);
+		this.recordEvent(sessionId, "lifecycle", "warning", "Session force-terminated (stale)");
+	}
 	mustGetRecord(sessionId) {
 		const record = this.store.get(sessionId);
 		if (!record) throw new Error("Session not found");
@@ -1187,7 +1349,9 @@ function loadConfig(env = process.env) {
 		logDir: env.AGENTIC_BROWSER_LOG_DIR ?? path.resolve(process.cwd(), ".agentic-browser"),
 		browserExecutablePath: env.AGENTIC_BROWSER_CHROME_PATH,
 		cdpUrl: env.AGENTIC_BROWSER_CDP_URL,
-		userProfileDir
+		userProfileDir,
+		headless: env.AGENTIC_BROWSER_HEADLESS === "true" || env.AGENTIC_BROWSER_HEADLESS === "1",
+		userAgent: env.AGENTIC_BROWSER_USER_AGENT || void 0
 	};
 }
 
@@ -1345,29 +1509,64 @@ function selectorSignal(insight) {
 	const evidenceStrength = Math.min(selectorEvidence / 5, 1);
 	return .7 * recipeCoverage + .3 * evidenceStrength;
 }
+function scoreInsight(insight, normalizedIntent, normalizedDomain) {
+	const insightIntent = normalize(insight.taskIntent);
+	const intentMatch = insightIntent === normalizedIntent ? 1 : 0;
+	const intentPartial = intentMatch === 1 || insightIntent.includes(normalizedIntent) || normalizedIntent.includes(insightIntent) ? .65 : 0;
+	const domainMatch = normalizedDomain && normalize(insight.siteDomain) === normalizedDomain ? 1 : normalizedDomain ? 0 : .6;
+	const reliability = .6 * confidenceFromCounts(insight.successCount, insight.failureCount) + .4 * freshnessWeight(insight.freshness);
+	const selectorQuality = selectorSignal(insight);
+	const score = .5 * Math.max(intentMatch, intentPartial) + .2 * domainMatch + .15 * reliability + .15 * selectorQuality;
+	return {
+		insightId: insight.insightId,
+		taskIntent: insight.taskIntent,
+		siteDomain: insight.siteDomain,
+		confidence: insight.confidence,
+		freshness: insight.freshness,
+		lastVerifiedAt: insight.lastVerifiedAt,
+		selectorHints: buildSelectorHints(insight),
+		score
+	};
+}
 var MemoryIndex = class {
+	/** Domain → insights index, rebuilt lazily when insight list changes. */
+	domainIndex = /* @__PURE__ */ new Map();
+	indexedInsights = null;
+	indexedLength = 0;
+	/** Rebuild the domain index when the underlying array or its size changes. */
+	ensureIndex(insights) {
+		if (this.indexedInsights === insights && this.indexedLength === insights.length) return;
+		this.domainIndex.clear();
+		for (const insight of insights) {
+			const domain = normalize(insight.siteDomain);
+			let bucket = this.domainIndex.get(domain);
+			if (!bucket) {
+				bucket = [];
+				this.domainIndex.set(domain, bucket);
+			}
+			bucket.push(insight);
+		}
+		this.indexedInsights = insights;
+		this.indexedLength = insights.length;
+	}
 	search(insights, input) {
 		const normalizedIntent = normalize(input.taskIntent);
 		const normalizedDomain = input.siteDomain ? normalize(input.siteDomain) : void 0;
 		const limit = input.limit ?? 10;
-		return insights.map((insight) => {
-			const intentMatch = normalize(insight.taskIntent) === normalizedIntent ? 1 : 0;
-			const intentPartial = intentMatch === 1 || normalize(insight.taskIntent).includes(normalizedIntent) || normalizedIntent.includes(normalize(insight.taskIntent)) ? .65 : 0;
-			const domainMatch = normalizedDomain && normalize(insight.siteDomain) === normalizedDomain ? 1 : normalizedDomain ? 0 : .6;
-			const reliability = .6 * confidenceFromCounts(insight.successCount, insight.failureCount) + .4 * freshnessWeight(insight.freshness);
-			const selectorQuality = selectorSignal(insight);
-			const score = .5 * Math.max(intentMatch, intentPartial) + .2 * domainMatch + .15 * reliability + .15 * selectorQuality;
-			return {
-				insightId: insight.insightId,
-				taskIntent: insight.taskIntent,
-				siteDomain: insight.siteDomain,
-				confidence: insight.confidence,
-				freshness: insight.freshness,
-				lastVerifiedAt: insight.lastVerifiedAt,
-				selectorHints: buildSelectorHints(insight),
-				score
-			};
-		}).filter((result) => result.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
+		this.ensureIndex(insights);
+		const candidates = normalizedDomain ? this.domainIndex.get(normalizedDomain) ?? [] : insights;
+		if (limit === 1 && normalizedDomain) {
+			let best;
+			for (const insight of candidates) {
+				const result = scoreInsight(insight, normalizedIntent, normalizedDomain);
+				if (result.score > 0 && (!best || result.score > best.score)) {
+					best = result;
+					if (best.score >= .95) break;
+				}
+			}
+			return best ? [best] : [];
+		}
+		return candidates.map((insight) => scoreInsight(insight, normalizedIntent, normalizedDomain)).filter((result) => result.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
 	}
 };
 
@@ -1464,8 +1663,13 @@ const MemoryStateSchema = z.object({ insights: z.array(TaskInsightSchema) });
 //#endregion
 //#region src/memory/task-insight-store.ts
 const EMPTY_STATE = { insights: [] };
+const FLUSH_DELAY_MS = 500;
 var TaskInsightStore = class {
 	filePath;
+	/** In-memory cache – authoritative after first load. */
+	cached = null;
+	dirty = false;
+	flushTimer = null;
 	constructor(baseDir) {
 		const memoryDir = path.join(baseDir, "memory");
 		fs.mkdirSync(memoryDir, { recursive: true });
@@ -1474,27 +1678,66 @@ var TaskInsightStore = class {
 		try {
 			if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
 		} catch {}
-		if (!fs.existsSync(this.filePath)) this.write(EMPTY_STATE);
+		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);
+		});
 	}
 	list() {
-		return this.read().insights;
+		return this.getCache();
 	}
 	get(insightId) {
-		return this.read().insights.find((insight) => insight.insightId === insightId);
+		return this.getCache().find((insight) => insight.insightId === insightId);
 	}
 	upsert(insight) {
 		TaskInsightSchema.parse(insight);
-		const state = this.read();
-		const index = state.insights.findIndex((entry) => entry.insightId === insight.insightId);
-		if (index >= 0) state.insights[index] = insight;
-		else state.insights.push(insight);
-		this.write(state);
+		const insights = this.getCache();
+		const index = insights.findIndex((entry) => entry.insightId === insight.insightId);
+		if (index >= 0) insights[index] = insight;
+		else insights.push(insight);
+		this.markDirty();
 	}
 	replaceMany(insights) {
 		for (const insight of insights) TaskInsightSchema.parse(insight);
-		this.write({ insights });
+		this.cached = insights;
+		this.markDirty();
+	}
+	/** Force an immediate synchronous flush (used at shutdown). */
+	flushSync() {
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = null;
+		}
+		if (this.dirty && this.cached) {
+			this.writeDisk({ insights: this.cached });
+			this.dirty = false;
+		}
 	}
-	read() {
+	/** Return the in-memory cache, loading from disk on first access. */
+	getCache() {
+		if (this.cached) return this.cached;
+		this.cached = this.readDisk().insights;
+		return this.cached;
+	}
+	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();
+		}
+	}
+	/** Read and validate from disk (only on first load or corruption recovery). */
+	readDisk() {
 		let raw;
 		try {
 			raw = JSON.parse(fs.readFileSync(this.filePath, "utf8"));
@@ -1511,7 +1754,7 @@ var TaskInsightStore = class {
 				if (salvaged.length > 0) {
 					const state = { insights: salvaged };
 					this.backupAndReset();
-					this.write(state);
+					this.writeDisk(state);
 					return state;
 				}
 			}
@@ -1525,7 +1768,7 @@ var TaskInsightStore = class {
 			fs.copyFileSync(this.filePath, corruptPath);
 		} catch {}
 	}
-	write(state) {
+	writeDisk(state) {
 		const tempPath = `${this.filePath}.tmp`;
 		fs.writeFileSync(tempPath, JSON.stringify(state, null, 2), "utf8");
 		fs.renameSync(tempPath, this.filePath);
@@ -1534,15 +1777,31 @@ var TaskInsightStore = class {
 
 //#endregion
 //#region src/memory/memory-service.ts
+const SEARCH_CACHE_TTL_MS = 2e3;
 var MemoryService = class {
 	store;
 	index;
+	/** Simple TTL cache for search results keyed by intent+domain+limit. */
+	searchCache = /* @__PURE__ */ new Map();
 	constructor(baseDir) {
 		this.store = new TaskInsightStore(baseDir);
 		this.index = new MemoryIndex();
 	}
 	search(input) {
-		return this.index.search(this.store.list(), input);
+		const cacheKey = `${input.taskIntent}\0${input.siteDomain ?? ""}\0${input.limit ?? 10}`;
+		const now = Date.now();
+		const cached = this.searchCache.get(cacheKey);
+		if (cached && now - cached.ts < SEARCH_CACHE_TTL_MS) return cached.results;
+		const results = this.index.search(this.store.list(), input);
+		this.searchCache.set(cacheKey, {
+			results,
+			ts: now
+		});
+		return results;
+	}
+	/** Invalidate search cache when data changes. */
+	invalidateSearchCache() {
+		this.searchCache.clear();
 	}
 	inspect(insightId) {
 		const insight = this.store.get(insightId);
@@ -1573,6 +1832,7 @@ var MemoryService = class {
 			updatedAt: now
 		};
 		this.store.upsert(verified);
+		this.invalidateSearchCache();
 		return verified;
 	}
 	recordSuccess(input) {
@@ -1600,6 +1860,7 @@ var MemoryService = class {
 				evidence: [evidence]
 			};
 			this.store.upsert(created);
+			this.invalidateSearchCache();
 			return created;
 		}
 		const refreshed = applySuccess({
@@ -1620,9 +1881,11 @@ var MemoryService = class {
 				updatedAt: now
 			};
 			this.store.upsert(versioned);
+			this.invalidateSearchCache();
 			return versioned;
 		}
 		this.store.upsert(refreshed);
+		this.invalidateSearchCache();
 		return refreshed;
 	}
 	recordFailure(input, errorMessage) {
@@ -1637,6 +1900,7 @@ var MemoryService = class {
 			evidence: [...matched.evidence.slice(-49), evidence]
 		}, signal);
 		this.store.upsert(failed);
+		this.invalidateSearchCache();
 		return failed;
 	}
 	findBestExactMatch(insights, taskIntent, siteDomain) {

package/package.json

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