agentic-browser 2.5.1 → 2.6.1

package/AGENTS.md

@@ -37,7 +37,7 @@ src/
     chrome-launcher.ts    — Chrome executable discovery & launch
   transport/
     control-api.ts        — ControlApi facade (delegates to SessionManager)
-    ws-server.ts          — Authenticated WebSocket server
+    auth-middleware.ts    — verifyBearerAuth() token check helper
   memory/
     memory-service.ts     — Task memory coordination
     memory-index.ts       — Search/ranking (fuzzy match + freshness + domain)

package/dist/cli/index.d.mts

@@ -1,2 +1,2 @@
 
-export { };
+export {}

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as createCliRuntime } from "../runtime-BeD8ZcjH.mjs";
+import { r as createCliRuntime } from "../runtime-BzdbtFF4.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -323,6 +323,7 @@ async function main() {
 			payload: JSON.parse(payloadJson)
 		});
 		console.log(JSON.stringify(result));
+		if (result.resultStatus === "failed" || result.resultStatus === "timed_out") process.exitCode = 1;
 	});
 	program.command("page:content").argument("<sessionId>").option("--mode <mode>", "title|text|html|a11y|summary", "summary").option("--selector <selector>", "optional CSS selector").option("--max-chars <n>", "max characters for text/html/a11y modes").action(async (sessionId, options) => {
 		const result = await runPageContent(runtime, {
@@ -512,14 +513,14 @@ async function main() {
 		await startMcpServer();
 	});
 	program.command("setup").description("Configure agentic-browser as MCP server for your AI tool").action(async () => {
-		const { runSetup } = await import("../setup-BP0YyerC.mjs");
+		const { runSetup } = await import("../setup-DUAjdbQ3.mjs");
 		await runSetup();
 	});
 	await program.parseAsync(process.argv);
 	return keepAlive;
 }
 main().then((keepAlive) => {
-	if (!keepAlive) process.exit(0);
+	if (!keepAlive) process.exit(process.exitCode ?? 0);
 }).catch((error) => {
 	const message = error instanceof Error ? error.message : String(error);
 	console.error(JSON.stringify({ error: message }));

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 
-import WebSocket, { WebSocket as WebSocket$1 } from "ws";
+import WebSocket from "ws";
 import { z } from "zod";
-
 //#region src/session/browser-controller.d.ts
 type InteractAction = "click" | "type" | "press" | "waitFor" | "evaluate" | "scroll" | "hover" | "select" | "toggle" | "goBack" | "goForward" | "refresh" | "dialog";
 interface InteractPayload {
@@ -306,11 +305,8 @@ type SessionEvent = z.infer<typeof SessionEventSchema>;
 //#endregion
 //#region src/lib/config.d.ts
 interface AppConfig {
-  host: string;
-  wsPort: number;
   dataDir: string;
   browserExecutablePath?: string;
-  commandTimeoutMs: number;
   cdpUrl?: string;
   userProfileDir?: string;
   headless?: boolean;
@@ -337,8 +333,15 @@ declare class EventStore {
   private readonly filePath;
   private readonly bufferedLines;
   private flushTimer;
+  private pendingFlushDelayMs;
   private flushInFlight;
   constructor(baseDir: string);
+  /**
+   * Remove the process exit handlers and flush any buffered lines.
+   * Call when discarding a store (repeated context creation in tests/embedders
+   * would otherwise leak a listener pair per instance).
+   */
+  dispose(): void;
   append(event: SessionEvent): void;
   list(sessionId: string, limit?: number): SessionEvent[];
   clear(sessionId: string): void;
@@ -357,21 +360,6 @@ declare class SessionTokenService {
   seed(sessionId: string, token: string): void;
 }
 //#endregion
-//#region src/transport/ws-server.d.ts
-interface WsServerOptions {
-  host: string;
-  port: number;
-  tokenService: SessionTokenService;
-}
-declare class AuthenticatedWsServer {
-  private readonly options;
-  private readonly logger;
-  private server?;
-  constructor(options: WsServerOptions);
-  start(onMessage: (socket: WebSocket$1, data: unknown) => void): void;
-  stop(): void;
-}
-//#endregion
 //#region src/memory/memory-service.d.ts
 interface MemorySearchInput {
   taskIntent: string;
@@ -445,7 +433,6 @@ interface AppContext {
   logger: Logger;
   eventStore: EventStore;
   tokenService: SessionTokenService;
-  wsServer: AuthenticatedWsServer;
   memoryService: MemoryService;
 }
 //#endregion

package/dist/index.mjs

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

package/dist/mcp/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-BeD8ZcjH.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,11 +147,10 @@ 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 {
@@ -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",