agentic-browser 2.5.0 → 2.6.0

package/dist/mcp/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-C3Y-UgC1.mjs";
+import { n as createAgenticBrowserCore } from "../runtime-BzdbtFF4.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -147,15 +147,14 @@ function summarizeElements(elements) {
 	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({
+		if (primaryActions.length < 12 && typeof element.ref === "string" && element.ref && typeof element.text === "string" && element.text) primaryActions.push({
+			ref: element.ref,
 			role,
-			text: element.text,
-			selector: element.selector,
-			fallbackSelectors: element.fallbackSelectors
+			text: element.text
 		});
 	}
 	return {
-		countsByRole: Object.fromEntries([...byRole.entries()].sort((a, b) => b[1] - a[1])),
+		countsByRole: Object.fromEntries([...byRole.entries()].toSorted((a, b) => b[1] - a[1])),
 		primaryActions
 	};
 }
@@ -164,19 +163,24 @@ function compactElement(element, visibleOnly) {
 	if (visibleOnly) delete compact.visible;
 	delete compact.actions;
 	delete compact.tagName;
+	if (compact.ref) {
+		delete compact.selector;
+		delete compact.fallbackSelectors;
+	}
+	if (!compact.ref) delete compact.ref;
 	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));
+function compactInteractiveElementsResult(elements, meta, visibleOnly) {
+	const compacted = elements.map((el) => compactElement(el, visibleOnly));
 	return {
-		elements,
-		totalFound: result.totalFound,
-		truncated: result.truncated,
-		summary: summarizeElements(elements)
+		elements: compacted,
+		totalFound: meta.totalFound,
+		truncated: meta.truncated,
+		summary: summarizeElements(compacted)
 	};
 }
 function compactMemoryResults(results) {
@@ -201,6 +205,47 @@ function compactMemoryResults(results) {
 	}) };
 }
 //#endregion
+//#region src/mcp/element-refs.ts
+var ElementRefRegistry = class {
+	bySession = /* @__PURE__ */ new Map();
+	/**
+	* Assign fresh refs to a freshly-discovered element list, replacing any prior
+	* refs for the session. Elements without a selector (nothing to act on) are
+	* still returned but get no ref.
+	*/
+	assign(sessionId, elements) {
+		const map = /* @__PURE__ */ new Map();
+		let n = 0;
+		const annotated = elements.map((el) => {
+			if (!el.selector) return {
+				...el,
+				ref: ""
+			};
+			const ref = `e${++n}`;
+			map.set(ref, {
+				selector: el.selector,
+				fallbackSelectors: el.fallbackSelectors,
+				text: el.text,
+				role: el.role
+			});
+			return {
+				...el,
+				ref
+			};
+		});
+		this.bySession.set(sessionId, map);
+		return { elements: annotated };
+	}
+	/** Resolve a ref to its selector target, or undefined if unknown/stale. */
+	resolve(sessionId, ref) {
+		return this.bySession.get(sessionId)?.get(ref);
+	}
+	/** Drop a session's refs (on stop/restart) so stale handles can't resolve. */
+	clear(sessionId) {
+		this.bySession.delete(sessionId);
+	}
+};
+//#endregion
 //#region src/mcp/index.ts
 function readPackageVersion() {
 	try {
@@ -241,6 +286,28 @@ function getCore() {
 function genId(prefix) {
 	return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
+const refs = new ElementRefRegistry();
+/**
+* Discover interactive elements, assign fresh refs for the session, and return
+* the compact agent-facing view (refs + role/text, no raw selectors). This is
+* the single "what can I see and do now" snapshot both browser_get_elements and
+* the post-interact page state share.
+*/
+async function snapshotElements(sessionId, opts = {}) {
+	const visibleOnly = opts.visibleOnly ?? true;
+	const result = await getCore().getInteractiveElements({
+		sessionId,
+		visibleOnly,
+		limit: opts.limit ?? 50,
+		selector: opts.selector,
+		roles: opts.roles
+	});
+	const { elements } = refs.assign(sessionId, result.elements);
+	return compactInteractiveElementsResult(elements, {
+		totalFound: result.totalFound,
+		truncated: result.truncated
+	}, visibleOnly);
+}
 /**
 * Resolve a session ID — auto-starts a session if none exists.
 * This means the LLM never has to call browser_start_session explicitly.
@@ -296,7 +363,7 @@ server.tool("browser_navigate", "Navigate the browser to a URL. A session is aut
 		text: JSON.stringify(compact)
 	}] };
 });
-server.tool("browser_interact", "Interact with a page element or perform browser actions. Element actions: \"click\", \"type\", \"press\", \"waitFor\", \"scroll\", \"hover\", \"select\", \"toggle\". Navigation actions: \"goBack\" (browser back), \"goForward\" (browser forward), \"refresh\" (reload page). Dialog action: \"dialog\" (handle JS alert/confirm/prompt — use text=\"dismiss\" to cancel, value=\"...\" for prompt input). Fallback selectors are tried automatically if the primary selector fails. A session is auto-started if needed.", {
+server.tool("browser_interact", "Interact with a page element or perform browser actions. Point at a target with `ref` (from browser_get_elements, e.g. \"e3\") — like clicking what you see. `selector` (CSS) still works as an escape hatch. Element actions: \"click\", \"type\", \"press\", \"waitFor\", \"scroll\", \"hover\", \"select\", \"toggle\". Navigation actions: \"goBack\", \"goForward\", \"refresh\". Dialog action: \"dialog\" (text=\"dismiss\" to cancel, value=\"...\" for prompt input). After an action that can change the page, the response includes a fresh `pageState` (new refs + summary) so you can see the result and pick your next action without a separate browser_get_elements call. A session is auto-started if needed.", {
 	action: z.enum([
 		"click",
 		"type",
@@ -311,8 +378,9 @@ server.tool("browser_interact", "Interact with a page element or perform browser
 		"refresh",
 		"dialog"
 	]).describe("The interaction type"),
-	selector: z.string().optional().describe("CSS selector for the target element"),
-	fallbackSelectors: z.array(z.string()).optional().describe("Backup CSS selectors tried if the primary selector fails (from browser_get_elements)"),
+	ref: z.string().optional().describe("Element ref from browser_get_elements (e.g. \"e3\") — preferred over selector"),
+	selector: z.string().optional().describe("CSS selector for the target element (escape hatch)"),
+	fallbackSelectors: z.array(z.string()).optional().describe("Backup CSS selectors tried if the primary selector fails"),
 	text: z.string().optional().describe("Text to type (for \"type\"), or \"dismiss\" to dismiss a dialog (for \"dialog\")"),
 	key: z.string().optional().describe("Key to press (required for \"press\" action, e.g. \"Enter\", \"Tab\")"),
 	value: z.string().optional().describe("Option value to select (for \"select\"), or prompt text (for \"dialog\")"),
@@ -320,11 +388,25 @@ server.tool("browser_interact", "Interact with a page element or perform browser
 	scrollY: z.number().optional().describe("Vertical scroll delta in pixels (for \"scroll\" action, positive = down)"),
 	timeoutMs: z.number().optional().describe("Timeout in milliseconds (for \"waitFor\" action, default 4000)"),
 	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
-}, async ({ action, selector, fallbackSelectors, text, key, value, scrollX, scrollY, timeoutMs, sessionId }) => {
+}, async ({ action, ref, selector, fallbackSelectors, text, key, value, scrollX, scrollY, timeoutMs, sessionId }) => {
 	const sid = await resolveSession(sessionId);
 	const payload = { action };
-	if (selector) payload.selector = selector;
-	if (fallbackSelectors) payload.fallbackSelectors = fallbackSelectors;
+	if (!selector && ref) {
+		const resolved = refs.resolve(sid, ref);
+		if (!resolved) return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				resultStatus: "failed",
+				resultMessage: `Unknown or stale ref "${ref}". Call browser_get_elements to refresh element refs.`,
+				errorCode: "SELECTOR_NOT_FOUND"
+			})
+		}] };
+		payload.selector = resolved.selector;
+		if (resolved.fallbackSelectors) payload.fallbackSelectors = resolved.fallbackSelectors;
+	} else {
+		if (selector) payload.selector = selector;
+		if (fallbackSelectors) payload.fallbackSelectors = fallbackSelectors;
+	}
 	if (text) payload.text = text;
 	if (key) payload.key = key;
 	if (value) payload.value = value;
@@ -347,6 +429,13 @@ server.tool("browser_interact", "Interact with a page element or perform browser
 		currentUrl
 	};
 	if (result.resultStatus === "failed") compact.errorCode = classifyError(result.resultMessage ?? "");
+	const pageChanging = action !== "hover" && action !== "waitFor";
+	if (result.resultStatus === "success" && pageChanging) try {
+		compact.pageState = await snapshotElements(sid, {
+			visibleOnly: true,
+			limit: 50
+		});
+	} catch {}
 	return { content: [{
 		type: "text",
 		text: JSON.stringify(compact)
@@ -374,10 +463,10 @@ server.tool("browser_get_content", "Get the current page content. Modes: \"summa
 	});
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(compactPageContent(result))
+		text: JSON.stringify(compactPageContent(result, effectiveMaxChars))
 	}] };
 });
-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.", {
+server.tool("browser_get_elements", "Discover interactive elements on the current page (buttons, links, inputs, etc.). Each element gets a short ref like \"e1\" — pass that ref to browser_interact to act on it, the way you would point at something you see rather than describing its markup. Refs stay valid until the next browser_get_elements call or the next page-changing interaction. Actions per role: link/button/custom→click, input/textarea/contenteditable→click+type+press, select→click+select, checkbox/radio→toggle. A session is auto-started if needed.", {
 	roles: z.array(z.enum([
 		"link",
 		"button",
@@ -394,9 +483,7 @@ server.tool("browser_get_elements", "Discover all interactive elements on the cu
 	selector: z.string().optional().describe("CSS selector to scope element discovery to a subtree"),
 	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
 }, async ({ roles, visibleOnly, limit, selector, sessionId }) => {
-	const sid = await resolveSession(sessionId);
-	const result = await getCore().getInteractiveElements({
-		sessionId: sid,
+	const snapshot = await snapshotElements(await resolveSession(sessionId), {
 		roles,
 		visibleOnly,
 		limit,
@@ -404,7 +491,7 @@ server.tool("browser_get_elements", "Discover all interactive elements on the cu
 	});
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(compactInteractiveElementsResult(result, visibleOnly))
+		text: JSON.stringify(snapshot)
 	}] };
 });
 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.", {
@@ -458,6 +545,7 @@ server.tool("browser_stop_session", "Stop the browser session and terminate Chro
 		})
 	}] };
 	await getCore().stopSession(sid);
+	refs.clear(sid);
 	if (activeSessionId === sid) activeSessionId = void 0;
 	return { content: [{
 		type: "text",