agentic-browser 2.3.0 → 2.4.0

package/dist/index.mjs

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

package/dist/mcp/index.d.mts

@@ -0,0 +1,5 @@
+
+//#region src/mcp/index.d.ts
+declare function main(): Promise<void>;
+//#endregion
+export { main };

package/dist/mcp/index.mjs

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-BCGndjhR.mjs";
+import { n as createAgenticBrowserCore } from "../runtime-PnWvjdzU.mjs";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -199,6 +202,29 @@ function compactMemoryResults(results) {
 }
 //#endregion
 //#region src/mcp/index.ts
+function readPackageVersion() {
+	try {
+		const dir = dirname(fileURLToPath(import.meta.url));
+		for (const rel of ["../../package.json", "../package.json"]) try {
+			const pkg = JSON.parse(readFileSync(join(dir, rel), "utf8"));
+			if (pkg.version) return pkg.version;
+		} catch {}
+	} catch {}
+	return "0.0.0";
+}
+function classifyError(message) {
+	const lower = message.toLowerCase();
+	if (lower.includes("not found") || lower.includes("no element")) return "SELECTOR_NOT_FOUND";
+	if (lower.includes("covered") || lower.includes("overlay")) return "ELEMENT_COVERED";
+	if (lower.includes("not editable") || lower.includes("readonly")) return "ELEMENT_NOT_EDITABLE";
+	if (lower.includes("navigation failed")) return "NAVIGATION_FAILED";
+	if (lower.includes("navigation") && lower.includes("timeout")) return "NAVIGATION_TIMEOUT";
+	if (lower.includes("cdp connection") || lower.includes("websocket")) return "CDP_DISCONNECTED";
+	if (lower.includes("session") && (lower.includes("dead") || lower.includes("terminated"))) return "SESSION_DEAD";
+	if (lower.includes("dialog")) return "DIALOG_BLOCKING";
+	if (lower.includes("timeout")) return "TIMEOUT";
+	return "UNKNOWN";
+}
 let core;
 let activeSessionId;
 const DEFAULT_MCP_MAX_CHARS = {
@@ -227,7 +253,7 @@ async function resolveSession(sessionId) {
 }
 const server = new McpServer({
 	name: "agentic-browser",
-	version: "0.1.0"
+	version: readPackageVersion()
 });
 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();
@@ -254,11 +280,17 @@ server.tool("browser_navigate", "Navigate the browser to a URL. A session is aut
 		const dismissed = await getCore().dismissCookieBanner(sid);
 		if (dismissed.dismissed) cookieBanner = dismissed;
 	} catch {}
+	let currentUrl;
+	try {
+		currentUrl = await getCore().getCurrentUrl(sid);
+	} catch {}
 	const compact = {
 		resultStatus: result.resultStatus,
 		resultMessage: result.resultMessage,
+		currentUrl,
 		cookieBanner
 	};
+	if (result.resultStatus === "failed") compact.errorCode = classifyError(result.resultMessage ?? "");
 	return { content: [{
 		type: "text",
 		text: JSON.stringify(compact)
@@ -305,10 +337,16 @@ server.tool("browser_interact", "Interact with a page element or perform browser
 		type: "interact",
 		payload
 	});
+	let currentUrl;
+	try {
+		currentUrl = await getCore().getCurrentUrl(sid);
+	} catch {}
 	const compact = {
 		resultStatus: result.resultStatus,
-		resultMessage: result.resultMessage
+		resultMessage: result.resultMessage,
+		currentUrl
 	};
+	if (result.resultStatus === "failed") compact.errorCode = classifyError(result.resultMessage ?? "");
 	return { content: [{
 		type: "text",
 		text: JSON.stringify(compact)
@@ -392,6 +430,24 @@ server.tool("browser_dismiss_cookies", "Dismiss cookie consent banners on the cu
 		text: JSON.stringify(result)
 	}] };
 });
+server.tool("browser_screenshot", "Capture a screenshot of the current page. Returns a base64-encoded image. Useful for visual verification, debugging element discovery failures, or when you need to see what the page looks like. A session is auto-started if needed.", {
+	format: z.enum(["jpeg", "png"]).default("jpeg").describe("Image format (jpeg is smaller, png is lossless)"),
+	quality: z.number().optional().describe("JPEG quality 0-100 (default 60, ignored for png)"),
+	fullPage: z.boolean().default(false).describe("Capture the full scrollable page instead of just the viewport"),
+	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
+}, async ({ format, quality, fullPage, sessionId }) => {
+	const sid = await resolveSession(sessionId);
+	const result = await getCore().screenshot(sid, {
+		format,
+		quality,
+		fullPage
+	});
+	return { content: [{
+		type: "image",
+		data: result.data,
+		mimeType: result.mimeType
+	}] };
+});
 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) return { content: [{

package/dist/{runtime-BCGndjhR.mjs → runtime-PnWvjdzU.mjs}

@@ -224,19 +224,78 @@ async function createTarget(cdpUrl, url = "about:blank") {
 	} catch {}
 	return await ensurePageWebSocketUrl(cdpUrl);
 }
-/** Verify the page is ready and optionally set a custom user-agent, using a single connection. */
+/**
+* Apply stealth patches that remove common automation fingerprints.
+* These run before any page loads so sites cannot detect the bot.
+*/
+const STEALTH_SCRIPT = `
+  // Remove navigator.webdriver flag
+  Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+
+  // Provide realistic plugins array (empty = headless fingerprint)
+  Object.defineProperty(navigator, 'plugins', {
+    get: () => {
+      const plugins = [
+        { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+        { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai', description: '' },
+        { name: 'Native Client', filename: 'internal-nacl-plugin', description: '' },
+      ];
+      plugins.length = 3;
+      Object.setPrototypeOf(plugins, PluginArray.prototype);
+      return plugins;
+    }
+  });
+
+  // Provide realistic languages
+  Object.defineProperty(navigator, 'languages', { get: () => ['en-US', 'en'] });
+
+  // Patch chrome.runtime to look like a real Chrome
+  if (!window.chrome) window.chrome = {};
+  if (!window.chrome.runtime) window.chrome.runtime = { id: undefined };
+
+  // Remove the CDP-injected sourceURL comment from Runtime.evaluate calls
+  const origToString = Function.prototype.toString;
+  Function.prototype.toString = function() {
+    if (this === Function.prototype.toString) return 'function toString() { [native code] }';
+    return origToString.call(this);
+  };
+
+  // Patch permissions query to report "prompt" instead of "denied" for notifications
+  const origQuery = window.Permissions?.prototype?.query;
+  if (origQuery) {
+    window.Permissions.prototype.query = function(params) {
+      if (params?.name === 'notifications') {
+        return Promise.resolve({ state: 'prompt', onchange: null });
+      }
+      return origQuery.call(this, params);
+    };
+  }
+`;
+/** Verify the page is ready, apply stealth, and optionally set a custom user-agent. */
 async function initTarget(targetWsUrl, userAgent) {
 	const conn = await CdpConnection.connect(targetWsUrl);
 	try {
 		const enables = [conn.send("Page.enable"), conn.send("Runtime.enable")];
-		if (userAgent) enables.push(conn.send("Network.enable"));
+		enables.push(conn.send("Network.enable"));
 		await Promise.all(enables);
+		await conn.send("Page.addScriptToEvaluateOnNewDocument", { source: STEALTH_SCRIPT });
+		await conn.send("Runtime.evaluate", {
+			expression: STEALTH_SCRIPT,
+			returnByValue: true
+		});
 		await conn.send("Runtime.evaluate", {
 			expression: "window.location.href",
 			returnByValue: true,
 			awaitPromise: true
 		});
 		if (userAgent) await conn.send("Network.setUserAgentOverride", { userAgent });
+		else try {
+			const { userAgent: currentUA } = await conn.send("Browser.getVersion");
+			if (currentUA?.includes("HeadlessChrome")) {
+				const cleanUA = currentUA.replace(/HeadlessChrome/g, "Chrome");
+				await conn.send("Network.setUserAgentOverride", { userAgent: cleanUA });
+			}
+		} catch {}
 	} finally {
 		conn.close();
 	}
@@ -732,7 +791,10 @@ var ChromeCdpBrowserController = class {
 				`--remote-debugging-port=${port}`,
 				`--user-data-dir=${profileDir}`,
 				"--no-first-run",
-				"--no-default-browser-check"
+				"--no-default-browser-check",
+				"--disable-blink-features=AutomationControlled",
+				"--disable-infobars",
+				"--excludeSwitches=enable-automation"
 			];
 			if (attempt.headless) args.push("--headless=new");
 			args.push("about:blank");
@@ -1076,6 +1138,38 @@ var ChromeCdpBrowserController = class {
 			})).result.value ?? "";
 		});
 	}
+	async screenshot(targetWsUrl, options) {
+		return await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			const format = options?.format ?? "jpeg";
+			const params = {
+				format,
+				quality: format === "jpeg" ? options?.quality ?? 60 : void 0
+			};
+			if (options?.fullPage) {
+				const metrics = await conn.send("Page.getLayoutMetrics");
+				params.clip = {
+					x: 0,
+					y: 0,
+					width: metrics.contentSize.width,
+					height: metrics.contentSize.height,
+					scale: 1
+				};
+			}
+			return {
+				data: (await conn.send("Page.captureScreenshot", params)).data,
+				mimeType: format === "png" ? "image/png" : "image/jpeg"
+			};
+		});
+	}
+	async getCurrentUrl(targetWsUrl) {
+		return await this.withRetry(targetWsUrl, async (conn) => {
+			return (await conn.send("Runtime.evaluate", {
+				expression: "window.location.href",
+				returnByValue: true
+			})).result.value ?? "";
+		});
+	}
 	async getContent(targetWsUrl, options) {
 		if (options.mode === "summary") return await this.getSummaryContent(targetWsUrl, options);
 		if (options.mode === "a11y") {
@@ -1149,7 +1243,8 @@ var ChromeCdpBrowserController = class {
 				fallbackSelectors: element.fallbackSelectors,
 				inputType: element.inputType,
 				placeholder: element.placeholder,
-				ariaLabel: element.ariaLabel
+				ariaLabel: element.ariaLabel,
+				currentValue: element.currentValue
 			});
 			if (primaryActions.length >= 8 && inputs.length >= 8) break;
 		}
@@ -1261,11 +1356,84 @@ var ChromeCdpBrowserController = class {
         };
       });
 
+      // Extract a readable content excerpt so the LLM understands what the page is about
+      function extractContentExcerpt(root, maxChars) {
+        const skipTags = new Set(['SCRIPT','STYLE','NOSCRIPT','SVG','PATH','META','LINK','BR','HR','IMG']);
+        const blocks = [];
+        let totalChars = 0;
+        const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+          acceptNode: function(node) {
+            const parent = node.parentElement;
+            if (!parent) return NodeFilter.FILTER_REJECT;
+            if (skipTags.has(parent.tagName)) return NodeFilter.FILTER_REJECT;
+            const view = (parent.ownerDocument && parent.ownerDocument.defaultView) ? parent.ownerDocument.defaultView : window;
+            const style = view.getComputedStyle(parent);
+            if (style.display === 'none' || style.visibility === 'hidden') return NodeFilter.FILTER_REJECT;
+            return NodeFilter.FILTER_ACCEPT;
+          }
+        });
+        let node;
+        while ((node = walker.nextNode())) {
+          const text = node.textContent.replace(/\\s+/g, ' ').trim();
+          if (!text || text.length < 2) continue;
+          if (totalChars + text.length > maxChars) {
+            const remaining = maxChars - totalChars;
+            if (remaining > 20) blocks.push(text.slice(0, remaining));
+            break;
+          }
+          blocks.push(text);
+          totalChars += text.length;
+        }
+        return blocks.join(' ').replace(/\\s+/g, ' ').trim();
+      }
+
+      // Group inputs by their parent form for contextual understanding
+      function discoverForms(root) {
+        const forms = [];
+        for (const form of Array.from(root.querySelectorAll('form')).slice(0, 6)) {
+          const formInputs = Array.from(form.querySelectorAll('input:not([type="hidden"]), select, textarea'));
+          if (!formInputs.length) continue;
+          const submitBtn = form.querySelector('button[type="submit"], input[type="submit"], button:not([type])');
+          forms.push({
+            action: form.getAttribute('action') || undefined,
+            method: (form.getAttribute('method') || 'get').toUpperCase(),
+            fields: formInputs.slice(0, 10).map(function(el) {
+              const tag = el.tagName.toLowerCase();
+              return {
+                name: el.getAttribute('name') || undefined,
+                type: tag === 'select' ? 'select' : tag === 'textarea' ? 'textarea' : (el.type || 'text'),
+                label: (function() {
+                  const id = el.id;
+                  if (id) {
+                    const label = root.querySelector('label[for="' + CSS.escape(id) + '"]');
+                    if (label) return textOf(label).slice(0, 60);
+                  }
+                  const closest = el.closest('label');
+                  if (closest) return textOf(closest).slice(0, 60);
+                  const ariaLabel = el.getAttribute('aria-label');
+                  if (ariaLabel) return ariaLabel.slice(0, 60);
+                  return el.getAttribute('placeholder') || undefined;
+                })(),
+                required: el.required || el.getAttribute('aria-required') === 'true' || false,
+                currentValue: ('value' in el && typeof el.value === 'string' && el.value) ? el.value.slice(0, 100) : undefined,
+              };
+            }),
+            submitText: submitBtn ? textOf(submitBtn).slice(0, 40) : undefined,
+          });
+        }
+        return forms;
+      }
+
+      const contentExcerpt = extractContentExcerpt(scopeRoot, 1500);
+      const forms = discoverForms(scopeRoot);
+
       return {
         url: window.location.href,
         title: document.title ?? '',
+        contentExcerpt,
         headings,
         landmarks,
+        forms: forms.length ? forms : undefined,
         alerts,
         frames,
         crossOriginFrameCount: allFrames.filter((frame) => {
@@ -1697,6 +1865,9 @@ var ChromeCdpBrowserController = class {
         if (ariaLabel) entry.ariaLabel = ariaLabel;
         const placeholder = el.getAttribute('placeholder');
         if (placeholder) entry.placeholder = placeholder;
+        if ('value' in el && typeof el.value === 'string' && el.value) {
+          entry.currentValue = el.value.slice(0, 200);
+        }
 
         results.push(entry);
       }
@@ -1978,6 +2149,15 @@ var MockBrowserController = class {
 		if (payload.action === "dialog") return payload.text === "dismiss" ? "dismissed confirm: mock dialog" : "accepted confirm: mock dialog";
 		return `interacted:${payload.action}`;
 	}
+	async screenshot(_targetWsUrl, options) {
+		return {
+			data: "bW9jaw==",
+			mimeType: (options?.format ?? "jpeg") === "png" ? "image/png" : "image/jpeg"
+		};
+	}
+	async getCurrentUrl(cdpUrl) {
+		return this.pages.get(cdpUrl)?.url ?? "about:blank";
+	}
 	async getContent(cdpUrl, options) {
 		const page = this.pages.get(cdpUrl);
 		if (!page) throw new Error("mock page missing");
@@ -2253,6 +2433,14 @@ var SessionManager = class {
 		const record = await this.ensureSession(sessionId);
 		return await this.browser.getInteractiveElements(record.targetWsUrl, options);
 	}
+	async screenshot(sessionId, options) {
+		const record = await this.ensureSession(sessionId);
+		return await this.browser.screenshot(record.targetWsUrl, options);
+	}
+	async getCurrentUrl(sessionId) {
+		const record = await this.ensureSession(sessionId);
+		return await this.browser.getCurrentUrl(record.targetWsUrl);
+	}
 	async dismissCookieBanner(sessionId) {
 		const record = await this.ensureSession(sessionId);
 		const result = await this.browser.dismissCookieBanner(record.targetWsUrl);
@@ -2528,6 +2716,12 @@ var ControlApi = class {
 	async dismissCookieBanner(sessionId) {
 		return await this.sessions.dismissCookieBanner(sessionId);
 	}
+	async screenshot(sessionId, options) {
+		return await this.sessions.screenshot(sessionId, options);
+	}
+	async getCurrentUrl(sessionId) {
+		return await this.sessions.getCurrentUrl(sessionId);
+	}
 	listEvents(sessionId, limit = 100) {
 		return { events: this.eventStore.list(sessionId, limit) };
 	}
@@ -3566,8 +3760,9 @@ var AgenticBrowserCore = class {
 		return this.api.getSession(sessionId);
 	}
 	async runCommand(input) {
+		const commandId = input.commandId ?? `${input.type}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 		return await this.api.executeCommand(input.sessionId, {
-			commandId: input.commandId,
+			commandId,
 			type: input.type,
 			payload: input.payload
 		});
@@ -3590,6 +3785,12 @@ var AgenticBrowserCore = class {
 	async dismissCookieBanner(sessionId) {
 		return await this.api.dismissCookieBanner(sessionId);
 	}
+	async screenshot(sessionId, options) {
+		return await this.api.screenshot(sessionId, options);
+	}
+	async getCurrentUrl(sessionId) {
+		return await this.api.getCurrentUrl(sessionId);
+	}
 	async restartSession(sessionId) {
 		return await this.api.restartSession(sessionId);
 	}

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "agentic-browser",
-  "version": "2.3.0",
+  "version": "2.4.0",
+  "description": "CLI and MCP server for AI agents to control Chrome via CDP",
+  "keywords": [
+    "agent",
+    "ai",
+    "automation",
+    "browser",
+    "cdp",
+    "chrome",
+    "devtools-protocol",
+    "llm",
+    "mcp"
+  ],
+  "homepage": "https://ph1p.github.io/agentic-browser",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,10 +30,20 @@
   ],
   "type": "module",
   "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
   "exports": {
-    ".": "./dist/index.mjs",
-    "./cli": "./dist/cli/index.mjs",
-    "./mcp": "./dist/mcp/index.mjs"
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.mts",
+      "default": "./dist/cli/index.mjs"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.mts",
+      "default": "./dist/mcp/index.mjs"
+    }
   },
   "publishConfig": {
     "access": "public",
@@ -65,5 +88,8 @@
     "vitest": "^4.0.18",
     "vocs": "1.4.1"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "packageManager": "pnpm@10.32.0"
 }