agentic-browser 2.1.0 → 2.2.0

package/README.md

@@ -113,7 +113,7 @@ agentic-browser agent start --user-agent "MyBot/1.0"
 agentic-browser agent status
 agentic-browser agent navigate https://example.com
 agentic-browser agent click "#login"
-agentic-browser agent content --mode text
+agentic-browser agent content --mode summary
 agentic-browser agent content --mode html --selector main
 agentic-browser agent elements
 agentic-browser agent elements --roles button,link --limit 20
@@ -156,6 +156,8 @@ MCP responses are compact — `visible`, `actions`, and `tagName` are omitted to
 
 When an element lives inside an open shadow root or a same-origin iframe, discovery returns a composed locator using `>>>` to cross boundaries, for example `iframe[name="checkout"] >>> button[aria-label="Pay"]`. The same locator string works with `agent click`, `agent type`, MCP `browser_interact`, and fallback selectors.
 
+`agent content` and MCP `browser_get_content` now default to `summary`, which returns a low-token overview with `title`, `headings`, `landmarks`, `primaryActions`, `inputs`, `alerts`, and iframe metadata. Use `a11y` when you need the deeper accessibility structure, and `text` or `html` only when you need raw content.
+
 ````
 
 ## MCP Server
@@ -225,8 +227,8 @@ More `interact` actions:
 ### 4. Read Page Content
 
 ```bash
+agentic-browser page:content <sessionId> --mode summary
 agentic-browser page:content <sessionId> --mode title
-agentic-browser page:content <sessionId> --mode text
 agentic-browser page:content <sessionId> --mode html --selector main
 ```
 

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as createCliRuntime } from "../runtime-CEvs2yzE.mjs";
+import { r as createCliRuntime } from "../runtime-CRkUsvhV.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -151,7 +151,8 @@ async function agentContent(runtime, input) {
 		action: "content",
 		...await runtime.api.getContent(sessionId, {
 			mode: input.mode,
-			selector: input.selector
+			selector: input.selector,
+			maxChars: input.maxChars
 		})
 	};
 }
@@ -249,7 +250,8 @@ async function runCommand(runtime, input) {
 async function runPageContent(runtime, input) {
 	return await runtime.api.getContent(input.sessionId, {
 		mode: input.mode,
-		selector: input.selector
+		selector: input.selector,
+		maxChars: input.maxChars
 	});
 }
 //#endregion
@@ -322,11 +324,12 @@ async function main() {
 		});
 		console.log(JSON.stringify(result));
 	});
-	program.command("page:content").argument("<sessionId>").option("--mode <mode>", "title|text|html|a11y", "text").option("--selector <selector>", "optional CSS selector").action(async (sessionId, options) => {
+	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, {
 			sessionId,
 			mode: options.mode,
-			selector: options.selector
+			selector: options.selector,
+			maxChars: options.maxChars ? Number.parseInt(options.maxChars, 10) : void 0
 		});
 		console.log(JSON.stringify(result));
 	});
@@ -470,8 +473,12 @@ async function main() {
 		const result = await agentTerminate(runtime);
 		console.log(JSON.stringify(result));
 	});
-	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);
+	agent.command("content").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 (options) => {
+		const result = await agentContent(runtime, {
+			mode: options.mode,
+			selector: options.selector,
+			maxChars: options.maxChars ? Number.parseInt(options.maxChars, 10) : void 0
+		});
 		console.log(JSON.stringify(result));
 	});
 	agent.command("elements").description("List interactive elements on the current page").option("--roles <roles>", "comma-separated roles filter", (v) => v.split(",")).option("--visible-only", "only visible elements", true).option("--no-visible-only", "include hidden elements").option("--limit <n>", "max elements", "50").option("--selector <selector>", "scope to CSS selector subtree").action(async (options) => {

package/dist/index.mjs

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

package/dist/mcp/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-CEvs2yzE.mjs";
+import { n as createAgenticBrowserCore } from "../runtime-CRkUsvhV.mjs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -22,10 +22,27 @@ function truncateContent(content, limit) {
 	};
 	const originalLength = content.length;
 	return {
-		content: content.slice(0, limit) + `\n\n[Truncated — showing first ${limit} of ${originalLength} characters. Use a CSS selector to scope the content.]`,
+		content: content.slice(0, limit) + `\n\n[Truncated - showing first ${limit} of ${originalLength} characters. Use a CSS selector to scope the content, or use mode="summary" for a lower-token overview.]`,
 		truncated: true
 	};
 }
+function resolveCompactedContent(result, limit) {
+	if (result.truncated) return {
+		content: result.content,
+		truncated: true
+	};
+	return truncateContent(result.content, limit);
+}
+function parseStructuredSummary(result) {
+	if (result.structuredContent) return result.structuredContent;
+	if (!result.content) return;
+	try {
+		const parsed = JSON.parse(result.content);
+		return parsed && typeof parsed === "object" ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
 function summarizeTextContent(content) {
 	const lines = uniqueLines(content);
 	return {
@@ -68,9 +85,23 @@ function compactPageContent(result, maxChars) {
 		text: 8e3,
 		a11y: 1e4,
 		html: 4e3,
-		title: void 0
+		title: void 0,
+		summary: void 0
 	}[result.mode];
-	const truncated = truncateContent(result.content, limit);
+	if (result.mode === "summary") {
+		const structured = parseStructuredSummary(result);
+		if (structured) return {
+			mode: "summary",
+			...structured,
+			truncated: false
+		};
+		return {
+			mode: "summary",
+			content: result.content,
+			truncated: false
+		};
+	}
+	const truncated = resolveCompactedContent(result, limit);
 	if (result.mode === "title") return {
 		...result,
 		truncated: false
@@ -81,6 +112,7 @@ function compactPageContent(result, maxChars) {
 			mode: result.mode,
 			content: truncated.content,
 			truncated: truncated.truncated,
+			originalLength: result.originalLength,
 			summaryLines: summary.summaryLines,
 			previewLines: summary.previewLines
 		};
@@ -91,6 +123,7 @@ function compactPageContent(result, maxChars) {
 			mode: result.mode,
 			content: truncated.content,
 			truncated: truncated.truncated,
+			originalLength: result.originalLength,
 			headings: summary.headings,
 			landmarks: summary.landmarks,
 			actions: summary.actions,
@@ -101,7 +134,8 @@ function compactPageContent(result, maxChars) {
 	return {
 		mode: result.mode,
 		content: truncated.content,
-		truncated: truncated.truncated
+		truncated: truncated.truncated,
+		originalLength: result.originalLength
 	};
 }
 function summarizeElements(elements) {
@@ -159,6 +193,13 @@ function compactMemoryResults(results) {
 //#region src/mcp/index.ts
 let core;
 let activeSessionId;
+const DEFAULT_MCP_MAX_CHARS = {
+	summary: void 0,
+	title: void 0,
+	text: 8e3,
+	a11y: 1e4,
+	html: 4e3
+};
 function getCore() {
 	if (!core) core = createAgenticBrowserCore();
 	return core;
@@ -265,26 +306,29 @@ server.tool("browser_interact", "Interact with a page element or perform browser
 		text: JSON.stringify(compact)
 	}] };
 });
-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.", {
+server.tool("browser_get_content", "Get the current page content. Modes: \"summary\" (recommended low-token overview with headings, actions, inputs, alerts, and iframe awareness), \"text\" (readable text), \"a11y\" (accessibility tree for deeper structure), \"title\" (page title only), \"html\" (raw HTML). A session is auto-started if needed.", {
 	mode: z.enum([
 		"title",
 		"text",
 		"html",
-		"a11y"
-	]).default("text").describe("Content extraction mode"),
+		"a11y",
+		"summary"
+	]).default("summary").describe("Content extraction mode"),
 	selector: z.string().optional().describe("CSS selector to scope content (e.g. \"main\", \"#content\")"),
-	maxChars: z.number().optional().describe("Maximum characters to return (default: 12000 for text/a11y, 6000 for html, no cap for title). Use a CSS selector to scope content instead of raising this limit."),
+	maxChars: z.number().optional().describe("Maximum characters to return (default: 8000 for text, 10000 for a11y, 4000 for html, ignored for summary/title). Use a CSS selector to scope content instead of raising this limit."),
 	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
 }, async ({ mode, selector, maxChars, sessionId }) => {
 	const sid = await resolveSession(sessionId);
+	const effectiveMaxChars = maxChars ?? DEFAULT_MCP_MAX_CHARS[mode];
 	const result = await getCore().getPageContent({
 		sessionId: sid,
 		mode,
-		selector
+		selector,
+		maxChars: effectiveMaxChars
 	});
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(compactPageContent(result, maxChars))
+		text: JSON.stringify(compactPageContent(result))
 	}] };
 });
 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.", {

package/dist/{runtime-CEvs2yzE.mjs → runtime-CRkUsvhV.mjs}

@@ -5,8 +5,8 @@ import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import WebSocket, { WebSocketServer } from "ws";
-import { URL as URL$1, fileURLToPath } from "node:url";
 import crypto from "node:crypto";
+import { URL as URL$1 } from "node:url";
 import { z } from "zod";
 //#region src/session/chrome-launcher.ts
 const CANDIDATES = [
@@ -22,16 +22,6 @@ function discoverChrome(explicitPath) {
 	return found;
 }
 //#endregion
-//#region src/session/extension-loader.ts
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-function loadControlExtension() {
-	const packageRoot = path.resolve(__dirname, "..");
-	return {
-		extensionPath: path.resolve(packageRoot, "extension"),
-		loadedAt: (/* @__PURE__ */ new Date()).toISOString()
-	};
-}
-//#endregion
 //#region src/session/browser-controller.ts
 var CdpConnection = class CdpConnection {
 	nextId = 0;
@@ -274,6 +264,7 @@ function resolveDefaultProfileDir() {
 	if (platform === "win32") return path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome", "User Data");
 	return path.join(home, ".config", "google-chrome");
 }
+const CONTENT_TRUNCATION_HINT = "Use a CSS selector to scope the content, or use mode=\"summary\" for a lower-token overview.";
 const LOCATOR_RUNTIME_HELPERS = String.raw`
       const LOCATOR_SEPARATOR = ' >>> ';
 
@@ -482,6 +473,168 @@ ${LOCATOR_RUNTIME_HELPERS}
 ${body}
     })()`;
 }
+const SPECIAL_KEY_PAYLOADS = new Map([
+	["Enter", {
+		key: "Enter",
+		code: "Enter",
+		windowsVirtualKeyCode: 13,
+		nativeVirtualKeyCode: 13,
+		text: "\r",
+		unmodifiedText: "\r"
+	}],
+	["Tab", {
+		key: "Tab",
+		code: "Tab",
+		windowsVirtualKeyCode: 9,
+		nativeVirtualKeyCode: 9
+	}],
+	["Escape", {
+		key: "Escape",
+		code: "Escape",
+		windowsVirtualKeyCode: 27,
+		nativeVirtualKeyCode: 27
+	}],
+	["Backspace", {
+		key: "Backspace",
+		code: "Backspace",
+		windowsVirtualKeyCode: 8,
+		nativeVirtualKeyCode: 8
+	}],
+	["Delete", {
+		key: "Delete",
+		code: "Delete",
+		windowsVirtualKeyCode: 46,
+		nativeVirtualKeyCode: 46
+	}],
+	["Space", {
+		key: " ",
+		code: "Space",
+		windowsVirtualKeyCode: 32,
+		nativeVirtualKeyCode: 32,
+		text: " ",
+		unmodifiedText: " "
+	}],
+	[" ", {
+		key: " ",
+		code: "Space",
+		windowsVirtualKeyCode: 32,
+		nativeVirtualKeyCode: 32,
+		text: " ",
+		unmodifiedText: " "
+	}],
+	["ArrowUp", {
+		key: "ArrowUp",
+		code: "ArrowUp",
+		windowsVirtualKeyCode: 38,
+		nativeVirtualKeyCode: 38
+	}],
+	["ArrowDown", {
+		key: "ArrowDown",
+		code: "ArrowDown",
+		windowsVirtualKeyCode: 40,
+		nativeVirtualKeyCode: 40
+	}],
+	["ArrowLeft", {
+		key: "ArrowLeft",
+		code: "ArrowLeft",
+		windowsVirtualKeyCode: 37,
+		nativeVirtualKeyCode: 37
+	}],
+	["ArrowRight", {
+		key: "ArrowRight",
+		code: "ArrowRight",
+		windowsVirtualKeyCode: 39,
+		nativeVirtualKeyCode: 39
+	}],
+	["Home", {
+		key: "Home",
+		code: "Home",
+		windowsVirtualKeyCode: 36,
+		nativeVirtualKeyCode: 36
+	}],
+	["End", {
+		key: "End",
+		code: "End",
+		windowsVirtualKeyCode: 35,
+		nativeVirtualKeyCode: 35
+	}],
+	["PageUp", {
+		key: "PageUp",
+		code: "PageUp",
+		windowsVirtualKeyCode: 33,
+		nativeVirtualKeyCode: 33
+	}],
+	["PageDown", {
+		key: "PageDown",
+		code: "PageDown",
+		windowsVirtualKeyCode: 34,
+		nativeVirtualKeyCode: 34
+	}]
+]);
+function appendTruncationNotice(content, limit, originalLength) {
+	return content + `\n\n[Truncated - showing first ${limit} of ${originalLength} characters. ${CONTENT_TRUNCATION_HINT}]`;
+}
+function applyContentLimit(content, limit, originalLength = content.length) {
+	if (!limit || originalLength <= limit) return {
+		content,
+		truncated: false
+	};
+	return {
+		content: appendTruncationNotice(content.slice(0, limit), limit, originalLength),
+		truncated: true,
+		originalLength
+	};
+}
+function normalizeRuntimeContentPayload(value, limit) {
+	if (typeof value === "string") {
+		const limited = applyContentLimit(value, limit);
+		return {
+			content: limited.content,
+			truncated: limited.truncated || void 0,
+			originalLength: limited.originalLength
+		};
+	}
+	const content = value?.content ?? "";
+	if (value?.truncated) {
+		const originalLength = value.originalLength ?? content.length;
+		const effectiveLimit = limit && limit > 0 ? limit : content.length;
+		return {
+			content: content.includes("[Truncated - showing first") || effectiveLimit === 0 ? content : appendTruncationNotice(content, effectiveLimit, originalLength),
+			truncated: true,
+			originalLength
+		};
+	}
+	const limited = applyContentLimit(content, limit, value?.originalLength ?? content.length);
+	return {
+		content: limited.content,
+		truncated: limited.truncated || void 0,
+		originalLength: limited.originalLength
+	};
+}
+function buildKeyDispatchPayload(inputKey) {
+	const key = inputKey || "Enter";
+	const special = SPECIAL_KEY_PAYLOADS.get(key);
+	if (special) return { ...special };
+	if (key.length === 1) {
+		const upper = key.toUpperCase();
+		const code = key >= "a" && key <= "z" ? `Key${upper}` : key >= "A" && key <= "Z" ? `Key${key}` : key >= "0" && key <= "9" ? `Digit${key}` : "Unidentified";
+		const keyCode = upper.charCodeAt(0);
+		return {
+			key,
+			code,
+			windowsVirtualKeyCode: keyCode,
+			nativeVirtualKeyCode: keyCode,
+			text: key,
+			unmodifiedText: key
+		};
+	}
+	return {
+		key,
+		code: key,
+		windowsVirtualKeyCode: 0,
+		nativeVirtualKeyCode: 0
+	};
+}
 var ChromeCdpBrowserController = class {
 	connections = /* @__PURE__ */ new Map();
 	cleanupInterval;
@@ -564,7 +717,6 @@ var ChromeCdpBrowserController = class {
 	async launch(sessionId, options) {
 		const { executablePath: explicitPath, userProfileDir, headless, userAgent } = options ?? {};
 		const executablePath = discoverChrome(explicitPath);
-		const extension = loadControlExtension();
 		let profileDir;
 		if (userProfileDir === "default") profileDir = resolveDefaultProfileDir();
 		else if (userProfileDir) profileDir = userProfileDir;
@@ -572,23 +724,7 @@ 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 = headless ? [{
-			withExtension: false,
-			headless: true
-		}] : [
-			{
-				withExtension: true,
-				headless: false
-			},
-			{
-				withExtension: false,
-				headless: false
-			},
-			{
-				withExtension: false,
-				headless: true
-			}
-		];
+		const launchAttempts = headless ? [{ headless: true }] : [{ headless: false }, { headless: true }];
 		let lastError;
 		for (const attempt of launchAttempts) {
 			const port = await getFreePort();
@@ -598,7 +734,6 @@ var ChromeCdpBrowserController = class {
 				"--no-first-run",
 				"--no-default-browser-check"
 			];
-			if (attempt.withExtension) args.push(`--disable-extensions-except=${extension.extensionPath}`, `--load-extension=${extension.extensionPath}`);
 			if (attempt.headless) args.push("--headless=new");
 			args.push("about:blank");
 			const child = spawn(executablePath, args, {
@@ -782,6 +917,42 @@ var ChromeCdpBrowserController = class {
 			clickCount: 1
 		});
 	}
+	async focusTarget(conn, payload) {
+		if (!payload.selector) return;
+		const expression = buildLocatorRuntimeExpression("payload", payload, `
+      const resolved = resolveWithFallbacks(payload.selector, payload.fallbackSelectors);
+      const el = resolved.element;
+      ensureInView(el);
+      if (typeof el.focus === 'function') {
+        el.focus();
+      }
+      return true;
+`);
+		await conn.send("Runtime.evaluate", {
+			expression,
+			returnByValue: true,
+			awaitPromise: true
+		});
+	}
+	async dispatchKeyPress(conn, keyInput) {
+		const payload = buildKeyDispatchPayload(keyInput ?? "Enter");
+		await conn.send("Input.dispatchKeyEvent", {
+			type: payload.text ? "keyDown" : "rawKeyDown",
+			key: payload.key,
+			code: payload.code,
+			windowsVirtualKeyCode: payload.windowsVirtualKeyCode,
+			nativeVirtualKeyCode: payload.nativeVirtualKeyCode,
+			text: payload.text,
+			unmodifiedText: payload.unmodifiedText
+		});
+		await conn.send("Input.dispatchKeyEvent", {
+			type: "keyUp",
+			key: payload.key,
+			code: payload.code,
+			windowsVirtualKeyCode: payload.windowsVirtualKeyCode,
+			nativeVirtualKeyCode: payload.nativeVirtualKeyCode
+		});
+	}
 	async interact(targetWsUrl, payload) {
 		if (payload.action === "goBack") return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
@@ -820,7 +991,7 @@ var ChromeCdpBrowserController = class {
 			return "page refreshed";
 		});
 		if (payload.action === "dialog") return await this.handleDialogAction(targetWsUrl, payload);
-		if (payload.action === "click" || payload.action === "hover" || payload.action === "type") return await this.withRetry(targetWsUrl, async (conn) => {
+		if (payload.action === "click" || payload.action === "hover" || payload.action === "type" || payload.action === "press") return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
 			if (payload.action === "click") {
 				const point = await this.preparePointerTarget(conn, payload);
@@ -843,18 +1014,15 @@ var ChromeCdpBrowserController = class {
 				});
 				return "hovered";
 			}
+			if (payload.action === "press") {
+				await this.focusTarget(conn, payload);
+				await this.dispatchKeyPress(conn, payload.key);
+				return "pressed";
+			}
 			if (await this.prepareTypeTarget(conn, payload) === "ready") await conn.send("Input.insertText", { text: payload.text ?? "" });
 			return "typed";
 		});
 		const expression = buildLocatorRuntimeExpression("payload", payload, `
-      if (payload.action === 'press') {
-        const target = deepActiveElement();
-        if (!target) throw new Error('No active element to press key on');
-        const key = payload.key ?? 'Enter';
-        target.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
-        target.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));
-        return 'pressed';
-      }
       if (payload.action === 'waitFor') {
         const timeout = payload.timeoutMs ?? 2000;
         const started = Date.now();
@@ -877,10 +1045,10 @@ var ChromeCdpBrowserController = class {
       if (payload.action === 'scroll') {
         if (payload.selector) {
           const el = resolveWithFallbacks(payload.selector, payload.fallbackSelectors).element;
-          el.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0, behavior: 'smooth' });
+          el.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0 });
           return 'scrolled element';
         }
-        window.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0, behavior: 'smooth' });
+        window.scrollBy({ left: payload.scrollX ?? 0, top: payload.scrollY ?? 0 });
         return 'scrolled page';
       }
       if (payload.action === 'select') {
@@ -909,37 +1077,234 @@ var ChromeCdpBrowserController = class {
 		});
 	}
 	async getContent(targetWsUrl, options) {
-		if (options.mode === "a11y") return {
-			mode: "a11y",
-			content: await this.getAccessibilityTree(targetWsUrl, options.selector)
-		};
+		if (options.mode === "summary") return await this.getSummaryContent(targetWsUrl, options);
+		if (options.mode === "a11y") {
+			const limited = normalizeRuntimeContentPayload(await this.getAccessibilityTree(targetWsUrl, options.selector), options.maxChars);
+			return {
+				mode: "a11y",
+				content: limited.content,
+				truncated: limited.truncated,
+				originalLength: limited.originalLength
+			};
+		}
 		const expression = buildLocatorRuntimeExpression("options", options, `
-      if (options.mode === 'title') return document.title ?? '';
+      const limit =
+        typeof options.maxChars === 'number' && Number.isFinite(options.maxChars) && options.maxChars > 0
+          ? Math.floor(options.maxChars)
+          : null;
+
+      function serializeContent(content) {
+        const normalized = typeof content === 'string' ? content : String(content ?? '');
+        const originalLength = normalized.length;
+        if (limit !== null && originalLength > limit) {
+          return { content: normalized.slice(0, limit), truncated: true, originalLength };
+        }
+        return { content: normalized, truncated: false, originalLength };
+      }
+
+      if (options.mode === 'title') return serializeContent(document.title ?? '');
       if (options.mode === 'html') {
         if (options.selector) {
           const el = resolveLocator(options.selector);
-          return el ? el.outerHTML : '';
+          return serializeContent(el ? el.outerHTML : '');
         }
-        return document.documentElement?.outerHTML ?? '';
+        return serializeContent(document.documentElement?.outerHTML ?? '');
       }
       if (options.selector) {
         const el = resolveLocator(options.selector);
-        return el ? el.innerText ?? '' : '';
+        return serializeContent(el ? el.innerText ?? '' : '');
       }
-      return document.body?.innerText ?? '';
+      return serializeContent(document.body?.innerText ?? '');
 `);
 		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
-			const content = (await conn.send("Runtime.evaluate", {
+			const limited = normalizeRuntimeContentPayload((await conn.send("Runtime.evaluate", {
 				expression,
-				returnByValue: true
-			})).result.value ?? "";
+				returnByValue: true,
+				awaitPromise: true
+			})).result.value, options.maxChars);
 			return {
 				mode: options.mode,
-				content
+				content: limited.content,
+				truncated: limited.truncated,
+				originalLength: limited.originalLength
 			};
 		});
 	}
+	summarizeInteractiveElements(result) {
+		const primaryActions = [];
+		const inputs = [];
+		for (const element of result.elements) {
+			if (primaryActions.length < 8 && (element.role === "button" || element.role === "link" || element.role === "custom")) primaryActions.push({
+				role: element.role,
+				text: element.text,
+				selector: element.selector,
+				fallbackSelectors: element.fallbackSelectors,
+				href: element.href
+			});
+			if (inputs.length < 8 && (element.role === "input" || element.role === "textarea" || element.role === "select" || element.role === "checkbox" || element.role === "radio" || element.role === "contenteditable")) inputs.push({
+				role: element.role,
+				text: element.text,
+				selector: element.selector,
+				fallbackSelectors: element.fallbackSelectors,
+				inputType: element.inputType,
+				placeholder: element.placeholder,
+				ariaLabel: element.ariaLabel
+			});
+			if (primaryActions.length >= 8 && inputs.length >= 8) break;
+		}
+		return {
+			primaryActions,
+			inputs
+		};
+	}
+	async getSummaryContent(targetWsUrl, options) {
+		const expression = buildLocatorRuntimeExpression("options", options, `
+      const scopeSelector = options.selector;
+      let scopeRoot = document.body ?? document.documentElement;
+      if (scopeSelector) {
+        try {
+          scopeRoot = resolveLocator(scopeSelector) ?? scopeRoot;
+        } catch {
+          scopeRoot = scopeRoot ?? document.documentElement;
+        }
+      }
+
+      function escapeAttr(value) {
+        return String(value ?? '').replace(/\\\\/g, '\\\\\\\\').replace(/"/g, '\\\\"');
+      }
+
+      function uniqueValues(values, limit) {
+        const seen = new Set();
+        const results = [];
+        for (const value of values) {
+          const normalized = String(value ?? '').replace(/\\s+/g, ' ').trim();
+          if (!normalized || seen.has(normalized)) continue;
+          seen.add(normalized);
+          results.push(normalized.slice(0, 160));
+          if (results.length >= limit) break;
+        }
+        return results;
+      }
+
+      function textOf(el) {
+        if (!el) return '';
+        const ariaLabel = el.getAttribute && el.getAttribute('aria-label');
+        if (ariaLabel) return ariaLabel;
+        const text = el.innerText || el.textContent || '';
+        return text.replace(/\\s+/g, ' ').trim();
+      }
+
+      function frameSelector(frame) {
+        if (frame.id) return '#' + CSS.escape(frame.id);
+        const name = frame.getAttribute('name');
+        if (name) return 'iframe[name="' + escapeAttr(name) + '"]';
+        const title = frame.getAttribute('title');
+        if (title) return 'iframe[title="' + escapeAttr(title) + '"]';
+        const src = frame.getAttribute('src');
+        if (src) return 'iframe[src="' + escapeAttr(src) + '"]';
+        const parent = frame.parentElement;
+        if (!parent) return 'iframe';
+        const siblings = Array.from(parent.children).filter((candidate) => candidate.tagName === frame.tagName);
+        if (siblings.length === 1) return 'iframe';
+        return 'iframe:nth-of-type(' + (siblings.indexOf(frame) + 1) + ')';
+      }
+
+      const headingSelectors = 'h1,h2,h3,h4,h5,h6,[role="heading"]';
+      const landmarkSelectors = [
+        'main',
+        'nav',
+        'aside',
+        'header',
+        'footer',
+        '[role="main"]',
+        '[role="navigation"]',
+        '[role="banner"]',
+        '[role="complementary"]',
+        '[role="contentinfo"]',
+        '[role="search"]'
+      ].join(',');
+      const alertSelectors = '[role="alert"], [aria-live="assertive"], dialog[open], [aria-modal="true"]';
+
+      const headings = uniqueValues(
+        Array.from(scopeRoot.querySelectorAll(headingSelectors)).map((el) => textOf(el)),
+        8
+      );
+      const landmarks = uniqueValues(
+        Array.from(scopeRoot.querySelectorAll(landmarkSelectors)).map((el) => {
+          const role = el.getAttribute('role') || el.tagName.toLowerCase();
+          const label = textOf(el);
+          return label ? role + ' "' + label.slice(0, 80) + '"' : role;
+        }),
+        8
+      );
+      const alerts = uniqueValues(
+        Array.from(scopeRoot.querySelectorAll(alertSelectors)).map((el) => textOf(el)),
+        6
+      );
+
+      const allFrames = Array.from(scopeRoot.querySelectorAll('iframe'));
+      const frames = allFrames.slice(0, 8).map((frame) => {
+        let sameOrigin = false;
+        try {
+          sameOrigin = !!frame.contentDocument;
+        } catch {
+          sameOrigin = false;
+        }
+
+        return {
+          selector: frameSelector(frame),
+          name: frame.getAttribute('name') || undefined,
+          title: frame.getAttribute('title') || undefined,
+          src: frame.getAttribute('src') || frame.src || undefined,
+          sameOrigin,
+        };
+      });
+
+      return {
+        url: window.location.href,
+        title: document.title ?? '',
+        headings,
+        landmarks,
+        alerts,
+        frames,
+        crossOriginFrameCount: allFrames.filter((frame) => {
+          try {
+            return !frame.contentDocument;
+          } catch {
+            return true;
+          }
+        }).length,
+        hasMoreFrames: allFrames.length > frames.length,
+        scopedToSelector: scopeSelector || undefined,
+      };
+`);
+		const pageSummary = await this.withRetry(targetWsUrl, async (conn) => {
+			await this.ensureEnabled(targetWsUrl);
+			return (await conn.send("Runtime.evaluate", {
+				expression,
+				returnByValue: true,
+				awaitPromise: true
+			})).result.value ?? {};
+		});
+		const elements = await this.getInteractiveElements(targetWsUrl, {
+			selector: options.selector,
+			visibleOnly: true,
+			limit: 24
+		});
+		const elementSummary = this.summarizeInteractiveElements(elements);
+		return {
+			mode: "summary",
+			content: "",
+			structuredContent: {
+				mode: "summary",
+				...pageSummary,
+				...elementSummary,
+				totalInteractiveElements: elements.totalFound,
+				truncatedInteractiveElements: elements.truncated
+			}
+		};
+	}
 	formatAccessibilityTree(nodes) {
 		const childrenMap = /* @__PURE__ */ new Map();
 		const nodeMap = /* @__PURE__ */ new Map();
@@ -1616,17 +1981,29 @@ var MockBrowserController = class {
 	async getContent(cdpUrl, options) {
 		const page = this.pages.get(cdpUrl);
 		if (!page) throw new Error("mock page missing");
-		if (options.mode === "title") return {
-			mode: "title",
-			content: page.title
-		};
-		if (options.mode === "html") return {
-			mode: "html",
-			content: page.html
+		if (options.mode === "summary") return {
+			mode: "summary",
+			content: "",
+			structuredContent: {
+				mode: "summary",
+				url: page.url,
+				title: page.title,
+				headings: [page.title],
+				landmarks: [],
+				alerts: [],
+				frames: [],
+				primaryActions: [],
+				inputs: [],
+				totalInteractiveElements: 0,
+				truncatedInteractiveElements: false
+			}
 		};
+		const limited = applyContentLimit(options.mode === "title" ? page.title : options.mode === "html" ? page.html : page.text, options.maxChars);
 		return {
-			mode: "text",
-			content: page.text
+			mode: options.mode,
+			content: limited.content,
+			truncated: limited.truncated || void 0,
+			originalLength: limited.originalLength
 		};
 	}
 	async getInteractiveElements(_targetWsUrl, _options) {
@@ -2217,16 +2594,26 @@ const MAX_EVENTS_PER_SESSION = 500;
 var EventStore = class {
 	events = /* @__PURE__ */ new Map();
 	filePath;
+	bufferedLines = [];
+	flushTimer;
+	flushInFlight;
 	constructor(baseDir) {
 		fs.mkdirSync(baseDir, { recursive: true });
 		this.filePath = path.join(baseDir, "session-events.log");
+		process.once("beforeExit", this.flushSync);
+		process.once("exit", this.flushSync);
 	}
 	append(event) {
 		let existing = this.events.get(event.sessionId) ?? [];
 		existing.push(event);
 		if (existing.length > MAX_EVENTS_PER_SESSION) existing = existing.slice(-MAX_EVENTS_PER_SESSION);
 		this.events.set(event.sessionId, existing);
-		fs.appendFileSync(this.filePath, `${JSON.stringify(event)}\n`, "utf8");
+		this.bufferedLines.push(`${JSON.stringify(event)}\n`);
+		if (this.bufferedLines.length >= 20) {
+			this.flushSoon(0);
+			return;
+		}
+		this.flushSoon(25);
 	}
 	list(sessionId, limit = 100) {
 		const entries = this.events.get(sessionId) ?? [];
@@ -2235,6 +2622,36 @@ var EventStore = class {
 	clear(sessionId) {
 		this.events.delete(sessionId);
 	}
+	flushSoon(delayMs) {
+		if (this.flushInFlight) return this.flushInFlight;
+		if (this.flushTimer) return Promise.resolve();
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = void 0;
+			this.flushAsync();
+		}, delayMs);
+		this.flushTimer.unref();
+		return Promise.resolve();
+	}
+	async flushAsync() {
+		if (this.flushInFlight || this.bufferedLines.length === 0) return;
+		const chunk = this.bufferedLines.splice(0, this.bufferedLines.length).join("");
+		this.flushInFlight = fs.promises.appendFile(this.filePath, chunk, "utf8").catch(() => {}).finally(() => {
+			this.flushInFlight = void 0;
+			if (this.bufferedLines.length > 0) this.flushSoon(0);
+		});
+		await this.flushInFlight;
+	}
+	flushSync = () => {
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = void 0;
+		}
+		if (this.bufferedLines.length === 0) return;
+		const chunk = this.bufferedLines.splice(0, this.bufferedLines.length).join("");
+		try {
+			fs.appendFileSync(this.filePath, chunk, "utf8");
+		} catch {}
+	};
 };
 //#endregion
 //#region src/auth/session-token.ts
@@ -2876,7 +3293,8 @@ var AgenticBrowserCore = class {
 	async getPageContent(input) {
 		return await this.api.getContent(input.sessionId, {
 			mode: input.mode,
-			selector: input.selector
+			selector: input.selector,
+			maxChars: input.maxChars
 		});
 	}
 	async getInteractiveElements(input) {

package/package.json

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