agentic-browser 1.3.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,12 +93,12 @@ Default profile locations per platform:
 
 These options can also be set via environment variables (CLI flags take precedence):
 
-| 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_HEADLESS`     | `true`                         | Run Chrome in headless mode          |
-| `AGENTIC_BROWSER_USER_AGENT`   | `MyBot/1.0`                    | Override the browser user-agent      |
+| 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_HEADLESS`     | `true`                        | Run Chrome in headless mode     |
+| `AGENTIC_BROWSER_USER_AGENT`   | `MyBot/1.0`                   | Override the browser user-agent |
 
 ## Agent Commands (Recommended for LLMs)
 

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as createCliRuntime } from "../runtime-Dvmv5Xi_.mjs";
+import { r as createCliRuntime } from "../runtime-CODdeRWR.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -283,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,
@@ -335,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-Dvmv5Xi_.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-Dvmv5Xi_.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-Dvmv5Xi_.mjs → runtime-CODdeRWR.mjs}

@@ -403,6 +403,43 @@ 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');
     })()`;
 		return await this.withRetry(targetWsUrl, async (conn) => {
@@ -422,6 +459,10 @@ var ChromeCdpBrowserController = class {
 		});
 	}
 	async getContent(targetWsUrl, options) {
+		if (options.mode === "a11y") return {
+			mode: "a11y",
+			content: await this.getAccessibilityTree(targetWsUrl)
+		};
 		const expression = `(() => {
       const options = ${JSON.stringify(options)};
       if (options.mode === 'title') return document.title ?? '';
@@ -450,6 +491,51 @@ var ChromeCdpBrowserController = class {
 			};
 		});
 	}
+	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 expression = `(() => {
       const options = ${JSON.stringify(options)};
@@ -799,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])),
@@ -826,7 +921,10 @@ 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, { userAgent: this.ctx.config.userAgent }) : await this.browser.launch(sessionId, {
@@ -854,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,
@@ -922,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) {
@@ -965,11 +1077,13 @@ 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, {
+		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,
@@ -1067,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");

package/package.json

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