agentic-browser 2.6.1 → 2.7.0

package/dist/{runtime-BzdbtFF4.mjs → runtime-CfQ0xGAm.mjs}

@@ -8,7 +8,33 @@ import WebSocket from "ws";
 import crypto from "node:crypto";
 import { URL as URL$1 } from "node:url";
 import { z } from "zod";
-//#region src/session/chrome-launcher.ts
+/**
+* Create a directory (recursively) and tighten it to owner-only if it already existed
+* with wider permissions (skips home, filesystem root, and dirs owned by another user).
+*/
+function ensurePrivateDir(dir) {
+	fs.mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	try {
+		if (process.platform === "win32" || typeof process.getuid !== "function") return;
+		const resolved = path.resolve(dir);
+		if (resolved === path.parse(resolved).root || resolved === path.resolve(os.homedir())) return;
+		const st = fs.statSync(resolved);
+		if (!st.isDirectory() || st.uid !== process.getuid()) return;
+		if ((st.mode & 63) !== 0) fs.chmodSync(resolved, 448);
+	} catch {}
+}
+/** Write a file with owner-only permissions, tightening any pre-existing file. */
+function writePrivateFileSync(file, data) {
+	fs.writeFileSync(file, data, {
+		encoding: "utf8",
+		mode: 384
+	});
+	fs.chmodSync(file, 384);
+}
+// src/session/chrome-launcher.ts
 const CANDIDATES = [
 	"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
 	"/usr/bin/google-chrome",
@@ -21,8 +47,36 @@ function discoverChrome(explicitPath) {
 	if (!found) throw new Error("No supported Chrome installation found.");
 	return found;
 }
-//#endregion
-//#region src/session/browser-controller.ts
+// src/session/browser-controller.ts
+/**
+* Detect a running Chrome that owns `profileDir`. On macOS/Linux `SingletonLock`
+* is a dangling symlink to `<hostname>-<pid>`, so existsSync (which follows
+* symlinks) cannot see it; inspect the link itself and probe the pid.
+*/
+function isProfileLocked(profileDir) {
+	const lockFile = path.join(profileDir, "SingletonLock");
+	let target;
+	try {
+		if (!fs.lstatSync(lockFile).isSymbolicLink()) return { locked: true };
+		target = fs.readlinkSync(lockFile);
+	} catch {
+		return { locked: false };
+	}
+	const pid = Number(target.slice(target.lastIndexOf("-") + 1));
+	if (!Number.isInteger(pid) || pid <= 0) return { locked: true };
+	try {
+		process.kill(pid, 0);
+		return {
+			locked: true,
+			pid
+		};
+	} catch (e) {
+		return {
+			locked: e.code === "EPERM",
+			pid
+		};
+	}
+}
 var CdpConnection = class CdpConnection {
 	ws;
 	nextId = 0;
@@ -339,6 +393,28 @@ async function initTarget(targetWsUrl, userAgent) {
 		conn.close();
 	}
 }
+/** Called on the iframe element: origin of its content box in top-level viewport coordinates. */
+const FRAME_CONTENT_OFFSET_FUNCTION = `function () {
+  const rect = this.getBoundingClientRect();
+  const style = getComputedStyle(this);
+  let x = rect.left + this.clientLeft + (parseFloat(style.paddingLeft) || 0);
+  let y = rect.top + this.clientTop + (parseFloat(style.paddingTop) || 0);
+  let doc = this.ownerDocument;
+  while (doc) {
+    let frameElement = null;
+    try {
+      frameElement = doc.defaultView && doc.defaultView.frameElement;
+    } catch {
+      frameElement = null;
+    }
+    if (!frameElement) break;
+    const frameRect = frameElement.getBoundingClientRect();
+    x += frameRect.left + frameElement.clientLeft;
+    y += frameRect.top + frameElement.clientTop;
+    doc = frameElement.ownerDocument;
+  }
+  return { x, y };
+}`;
 /**
 * Run Runtime.evaluate and surface in-page exceptions as errors.
 * CDP reports page-side throws via `exceptionDetails` on an otherwise successful
@@ -439,6 +515,82 @@ const LOCATOR_RUNTIME_HELPERS = String.raw`
         return false;
       }
 
+      const TEXT_INTERACTIVE_SELECTOR = [
+        'a[href]', 'button', 'input[type="button"]', 'input[type="submit"]', 'input[type="reset"]',
+        '[role="button"]', '[role="link"]', '[role="menuitem"]', '[role="tab"]', '[role="option"]',
+        '[role="checkbox"]', '[role="radio"]', '[role="switch"]', 'summary', 'label', 'option',
+        '[onclick]', '[tabindex]'
+      ].join(',');
+
+      function normalizeText(value) {
+        return String(value ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+      }
+
+      function textLabels(el, useInnerText) {
+        const labels = [];
+        const body = useInnerText && typeof el.innerText === 'string' ? el.innerText : el.textContent;
+        if (body) labels.push(normalizeText(body));
+        for (const attr of ['aria-label', 'title', 'alt', 'placeholder']) {
+          const value = el.getAttribute && el.getAttribute(attr);
+          if (value) labels.push(normalizeText(value));
+        }
+        if (el.tagName && el.tagName.toLowerCase() === 'input' && typeof el.value === 'string' && el.value) {
+          labels.push(normalizeText(el.value));
+        }
+        return labels;
+      }
+
+      function hasBox(el) {
+        const rect = el.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+      }
+
+      // text=Foo matches by visible text (exact first, then substring);
+      // text="Foo" matches exactly. Interactive and visible elements win.
+      function queryByText(root, query) {
+        let raw = String(query).trim();
+        let exactOnly = false;
+        if (raw.length >= 2 && (raw[0] === '"' || raw[0] === "'") && raw[raw.length - 1] === raw[0]) {
+          raw = raw.slice(1, -1);
+          exactOnly = true;
+        }
+        const needle = normalizeText(raw);
+        if (!needle) return null;
+
+        function pick(candidates, useInnerText, preferSmallest) {
+          let best = null;
+          let bestScore = -1;
+          let bestSize = Infinity;
+          for (const el of candidates) {
+            const labels = textLabels(el, useInnerText);
+            let score = -1;
+            if (labels.some((label) => label === needle)) score = 2;
+            else if (!exactOnly && labels.some((label) => label.includes(needle))) score = 1;
+            if (score < 0) continue;
+            if (hasBox(el)) score += 4;
+            const size = preferSmallest ? (el.textContent || '').length : 0;
+            if (score > bestScore || (score === bestScore && size < bestSize)) {
+              best = el;
+              bestScore = score;
+              bestSize = size;
+            }
+          }
+          return best;
+        }
+
+        // On equal score the element with the least text is the most specific match.
+        const interactive = pick(root.querySelectorAll(TEXT_INTERACTIVE_SELECTOR), true, true);
+        if (interactive) return interactive;
+        return pick(root.querySelectorAll(root.nodeType === 9 ? 'body *' : '*'), false, true);
+      }
+
+      function querySegment(root, part) {
+        if (/^text=/i.test(part)) {
+          return queryByText(root, part.slice(5));
+        }
+        return root.querySelector(part);
+      }
+
       function resolveLocator(locator) {
         const parts = splitLocator(locator);
         if (parts.length === 0) return null;
@@ -446,7 +598,7 @@ const LOCATOR_RUNTIME_HELPERS = String.raw`
         let root = document;
         let element = null;
         for (let index = 0; index < parts.length; index += 1) {
-          element = root.querySelector(parts[index]);
+          element = querySegment(root, parts[index]);
           if (!element) return null;
 
           if (index === parts.length - 1) {
@@ -502,7 +654,7 @@ const LOCATOR_RUNTIME_HELPERS = String.raw`
         if (lastError) {
           throw lastError;
         }
-        throw new Error('Selector not found');
+        throw new Error('Element not found: ' + locators.join(' | '));
       }
 
       function ensureInView(element) {
@@ -749,7 +901,7 @@ function buildKeyDispatchPayload(inputKey) {
 	};
 }
 /** Connection pool configuration */
-const CONNECTION_IDLE_TIMEOUT_MS = 300 * 1e3;
+const CONNECTION_IDLE_TIMEOUT_MS = 3e5;
 const CONNECTION_CLEANUP_INTERVAL_MS = 6e4;
 /**
 * True when the error means the socket was closed/not-open — i.e. the request
@@ -765,6 +917,7 @@ var ChromeCdpBrowserController = class {
 	baseDir;
 	connectionFactory;
 	connections = /* @__PURE__ */ new Map();
+	pendingConnections = /* @__PURE__ */ new Map();
 	cleanupInterval;
 	/**
 	* User-agent override resolved at target init, keyed by target ws URL.
@@ -793,17 +946,27 @@ var ChromeCdpBrowserController = class {
 			cached.lastUsedAt = Date.now();
 			return cached.conn;
 		}
-		const conn = await this.connectionFactory(targetWsUrl);
-		await this.applySessionOverrides(conn, targetWsUrl);
-		this.connections.set(targetWsUrl, {
-			conn,
-			enabled: {
-				page: false,
-				runtime: false
-			},
-			lastUsedAt: Date.now()
-		});
-		return conn;
+		const pending = this.pendingConnections.get(targetWsUrl);
+		if (pending) return pending;
+		const p = (async () => {
+			const conn = await this.connectionFactory(targetWsUrl);
+			await this.applySessionOverrides(conn, targetWsUrl);
+			this.connections.set(targetWsUrl, {
+				conn,
+				enabled: {
+					page: false,
+					runtime: false
+				},
+				lastUsedAt: Date.now()
+			});
+			return conn;
+		})();
+		this.pendingConnections.set(targetWsUrl, p);
+		try {
+			return await p;
+		} finally {
+			this.pendingConnections.delete(targetWsUrl);
+		}
 	}
 	/**
 	* Re-apply session-scoped stealth patches + UA override on a fresh connection.
@@ -883,9 +1046,11 @@ var ChromeCdpBrowserController = class {
 		if (userProfileDir === "default") profileDir = resolveDefaultProfileDir();
 		else if (userProfileDir) profileDir = userProfileDir;
 		else profileDir = path.join(this.baseDir, "profiles", sessionId);
-		fs.mkdirSync(profileDir, { recursive: true });
+		if (userProfileDir) fs.mkdirSync(profileDir, { recursive: true });
+		else ensurePrivateDir(profileDir);
 		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 lock = isProfileLocked(profileDir);
+		if (lock.locked) throw new Error(`Chrome profile is already in use (lock file exists: ${lockFile}${lock.pid ? `, pid ${lock.pid}` : ""}). Quit the running Chrome instance first, or use --cdp-url to connect to it instead.`);
 		const launchAttempts = headless ? [{ headless: true }] : [{ headless: false }, { headless: true }];
 		let lastError;
 		for (const attempt of launchAttempts) {
@@ -948,6 +1113,182 @@ var ChromeCdpBrowserController = class {
 			return await fn(conn);
 		}
 	}
+	/**
+	* Split a composed locator at the first iframe whose document the page
+	* cannot reach (cross-origin). Returns null when no such boundary exists.
+	*/
+	async splitAtCrossOriginFrame(conn, locator) {
+		if (!locator.includes(">>>")) return null;
+		return (await evaluateOnPage(conn, {
+			expression: buildLocatorRuntimeExpression("locator", locator, `
+      const parts = splitLocator(locator);
+      let root = document;
+      for (let index = 0; index < parts.length - 1; index += 1) {
+        const el = querySegment(root, parts[index]);
+        if (!el) return null;
+        const tag = el.tagName ? el.tagName.toLowerCase() : '';
+        if (tag === 'iframe' || tag === 'frame') {
+          let doc = null;
+          try {
+            doc = el.contentDocument;
+          } catch {
+            doc = null;
+          }
+          if (!doc) {
+            return {
+              frame: parts.slice(0, index + 1).join(LOCATOR_SEPARATOR),
+              rest: parts.slice(index + 1).join(LOCATOR_SEPARATOR),
+            };
+          }
+          root = doc;
+          continue;
+        }
+        if (el.shadowRoot) {
+          root = el.shadowRoot;
+          continue;
+        }
+        return null;
+      }
+      return null;
+`),
+			returnByValue: true,
+			awaitPromise: true
+		})).result.value ?? null;
+	}
+	/**
+	* Work out which frame a payload targets. An explicit `frame` wins;
+	* otherwise a composed selector crossing a cross-origin iframe is split.
+	*/
+	async resolveFrameTarget(conn, payload) {
+		if (payload.frame) return {
+			frame: payload.frame,
+			payload
+		};
+		if (!payload.selector) return { payload };
+		const split = await this.splitAtCrossOriginFrame(conn, payload.selector);
+		if (!split) return { payload };
+		const prefix = split.frame + " >>> ";
+		const fallbackSelectors = payload.fallbackSelectors?.map((fallback) => fallback.startsWith(prefix) ? fallback.slice(prefix.length) : fallback);
+		return {
+			frame: split.frame,
+			payload: {
+				...payload,
+				selector: split.rest,
+				fallbackSelectors
+			}
+		};
+	}
+	/**
+	* Open an evaluation scope inside an iframe. Same-process frames get an
+	* isolated world on the page connection; out-of-process (cross-site) frames
+	* get their own CDP connection to the frame target. Input events still go
+	* to the page connection, translated by `getOffset()`.
+	*/
+	async openFrameScope(conn, targetWsUrl, frameLocator) {
+		const objectId = (await evaluateOnPage(conn, {
+			expression: buildLocatorRuntimeExpression("frameLocator", frameLocator, `
+      const el = resolveLocator(frameLocator);
+      if (!el) throw new Error('Frame not found: ' + frameLocator);
+      const tag = el.tagName ? el.tagName.toLowerCase() : '';
+      if (tag !== 'iframe' && tag !== 'frame') {
+        throw new Error('Frame locator does not match an iframe: ' + frameLocator);
+      }
+      ensureInView(el);
+      return el;
+`),
+			awaitPromise: true
+		})).result.objectId;
+		if (!objectId) throw new Error(`Frame not found: ${frameLocator}`);
+		const releaseObject = () => {
+			conn.send("Runtime.releaseObject", { objectId }).catch(() => {});
+		};
+		try {
+			const frameId = (await conn.send("DOM.describeNode", { objectId })).node?.frameId;
+			if (!frameId) throw new Error(`Frame has no document yet: ${frameLocator}`);
+			const getOffset = async () => {
+				return (await conn.send("Runtime.callFunctionOn", {
+					objectId,
+					functionDeclaration: FRAME_CONTENT_OFFSET_FUNCTION,
+					returnByValue: true
+				})).result.value ?? {
+					x: 0,
+					y: 0
+				};
+			};
+			let world = null;
+			try {
+				world = await conn.send("Page.createIsolatedWorld", {
+					frameId,
+					worldName: "agentic-browser"
+				});
+			} catch {
+				world = null;
+			}
+			if (world?.executionContextId !== void 0) {
+				const contextId = world.executionContextId;
+				return {
+					client: {
+						send: (method, params, timeoutMs) => conn.send(method, method === "Runtime.evaluate" ? {
+							...params,
+							contextId
+						} : params, timeoutMs),
+						waitForEvent: (method, timeoutMs) => conn.waitForEvent(method, timeoutMs),
+						close: () => {}
+					},
+					getOffset,
+					release: releaseObject
+				};
+			}
+			const frameWsUrl = targetWsUrl.replace(/\/devtools\/page\/[^/?#]+/, `/devtools/page/${frameId}`);
+			if (frameWsUrl === targetWsUrl) throw new Error(`Cannot derive a frame target URL from ${targetWsUrl}`);
+			let frameConn;
+			let lastError;
+			const listUrl = targetWsUrl.replace(/^ws(s?):\/\/([^/]+)\/.*$/, "http$1://$2/json/list");
+			for (let attempt = 0; attempt < 4 && !frameConn; attempt++) {
+				if (attempt > 0) {
+					await getJson(listUrl).catch(() => {});
+					if (attempt > 1) await new Promise((resolve) => setTimeout(resolve, 250 * attempt));
+				}
+				try {
+					frameConn = await this.connectionFactory(frameWsUrl);
+				} catch (error) {
+					lastError = error;
+				}
+			}
+			if (!frameConn) throw new Error(`Unable to attach to cross-origin frame ${frameLocator}: ${lastError?.message}`, { cause: lastError });
+			const attached = frameConn;
+			return {
+				client: attached,
+				getOffset,
+				release: () => {
+					releaseObject();
+					try {
+						attached.close();
+					} catch {}
+				}
+			};
+		} catch (error) {
+			releaseObject();
+			throw error;
+		}
+	}
+	/** Run `fn` against the frame a payload targets (the page itself when none). */
+	async withFrameScope(conn, targetWsUrl, payload, fn) {
+		const target = await this.resolveFrameTarget(conn, payload);
+		if (!target.frame) return await fn(conn, payload, async () => ({
+			x: 0,
+			y: 0
+		}));
+		const scope = await this.openFrameScope(conn, targetWsUrl, target.frame);
+		try {
+			return await fn(scope.client, {
+				...target.payload,
+				frame: void 0
+			}, scope.getOffset);
+		} finally {
+			scope.release();
+		}
+	}
 	async navigate(targetWsUrl, url) {
 		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
@@ -1078,6 +1419,40 @@ var ChromeCdpBrowserController = class {
 		if (value !== "ready" && value !== "cleared") throw new Error("Unable to resolve type target");
 		return value;
 	}
+	/**
+	* Arm a wait for a main-frame navigation BEFORE the click is dispatched, so
+	* the start event cannot be missed. Resolves "navigated" once the main frame
+	* started loading and then committed/loaded (each stage timeout-tolerant),
+	* or "none" when no main-frame load started within 500 ms.
+	*/
+	async armMainFrameNavigationWait(conn) {
+		const matching = conn.waitForEventMatching?.bind(conn);
+		if (!matching) return { result: (async () => {
+			try {
+				await conn.waitForEvent("Page.frameNavigated", 50);
+			} catch {
+				return "none";
+			}
+			try {
+				await Promise.race([conn.waitForEvent("Page.loadEventFired", 3e3), conn.waitForEvent("Page.frameStoppedLoading", 3e3)]);
+			} catch {}
+			return "navigated";
+		})() };
+		let mainFrameId;
+		try {
+			mainFrameId = (await conn.send("Page.getFrameTree")).frameTree?.frame?.id;
+		} catch {}
+		const isMain = (params) => mainFrameId === void 0 || params.frameId === mainFrameId;
+		const started = matching("Page.frameStartedLoading", isMain, 500).then(() => true, () => false);
+		return { result: (async () => {
+			if (!await started) return "none";
+			const navigated = matching("Page.frameNavigated", (params) => !params.frame?.parentId, 5e3).catch(() => void 0);
+			const loaded = Promise.race([matching("Page.frameStoppedLoading", isMain, 5e3), matching("Page.loadEventFired", () => true, 5e3)]).catch(() => void 0);
+			await navigated;
+			await loaded;
+			return "navigated";
+		})() };
+	}
 	async dispatchMouseClick(conn, x, y) {
 		await conn.send("Input.dispatchMouseEvent", {
 			type: "mouseMoved",
@@ -1175,36 +1550,36 @@ var ChromeCdpBrowserController = class {
 		if (payload.action === "dialog") return await this.handleDialogAction(targetWsUrl, payload);
 		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);
-				await this.dispatchMouseClick(conn, point.x, point.y);
-				try {
-					await conn.waitForEvent("Page.frameNavigated", 50);
-					try {
-						await Promise.race([conn.waitForEvent("Page.loadEventFired", 3e3), conn.waitForEvent("Page.frameStoppedLoading", 3e3)]);
-					} catch {}
-				} catch {}
-				return "clicked";
-			}
-			if (payload.action === "hover") {
-				const point = await this.preparePointerTarget(conn, payload);
-				await conn.send("Input.dispatchMouseEvent", {
-					type: "mouseMoved",
-					x: point.x,
-					y: point.y,
-					button: "none"
-				});
-				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";
+			return await this.withFrameScope(conn, targetWsUrl, payload, async (client, scoped, getOffset) => {
+				if (scoped.action === "click") {
+					const local = await this.preparePointerTarget(client, scoped);
+					const offset = await getOffset();
+					const nav = await this.armMainFrameNavigationWait(conn);
+					await this.dispatchMouseClick(conn, local.x + offset.x, local.y + offset.y);
+					await nav.result;
+					return "clicked";
+				}
+				if (scoped.action === "hover") {
+					const local = await this.preparePointerTarget(client, scoped);
+					const offset = await getOffset();
+					await conn.send("Input.dispatchMouseEvent", {
+						type: "mouseMoved",
+						x: local.x + offset.x,
+						y: local.y + offset.y,
+						button: "none"
+					});
+					return "hovered";
+				}
+				if (scoped.action === "press") {
+					await this.focusTarget(client, scoped);
+					await this.dispatchKeyPress(conn, scoped.key);
+					return "pressed";
+				}
+				if (await this.prepareTypeTarget(client, scoped) === "ready") await conn.send("Input.insertText", { text: scoped.text ?? "" });
+				return "typed";
+			});
 		}, "connection");
-		const expression = buildLocatorRuntimeExpression("payload", payload, `
+		const buildExpression = (scoped) => buildLocatorRuntimeExpression("payload", scoped, `
       if (payload.action === 'waitFor') {
         const timeout = payload.timeoutMs ?? 2000;
         const started = Date.now();
@@ -1251,11 +1626,17 @@ var ChromeCdpBrowserController = class {
 `);
 		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
-			return (await evaluateOnPage(conn, {
-				expression,
-				returnByValue: true,
-				awaitPromise: true
-			})).result.value ?? "";
+			return await this.withFrameScope(conn, targetWsUrl, payload, async (client, scoped) => {
+				return (await evaluateOnPage(client, {
+					expression: scoped.action === "evaluate" ? `(async () => {
+  const __agenticResult = await (${scoped.text ?? "undefined"}
+  );
+  return typeof __agenticResult === 'string' ? __agenticResult : JSON.stringify(__agenticResult);
+})()` : buildExpression(scoped),
+					returnByValue: true,
+					awaitPromise: true
+				})).result.value ?? "";
+			});
 		}, "connection");
 	}
 	async screenshot(targetWsUrl, options) {
@@ -1291,6 +1672,66 @@ var ChromeCdpBrowserController = class {
 			})).result.value ?? "";
 		});
 	}
+	async getPageState(targetWsUrl) {
+		return await this.withRetry(targetWsUrl, async (conn) => {
+			return (await evaluateOnPage(conn, {
+				expression: "({ url: location.href, title: document.title, readyState: document.readyState })",
+				returnByValue: true
+			})).result.value ?? {
+				url: "",
+				title: "",
+				readyState: "loading"
+			};
+		});
+	}
+	async listTabs(cdpUrl) {
+		return (await getJson(`${cdpUrl}/json/list`)).filter((target) => target.type === "page" && target.webSocketDebuggerUrl).map((target) => ({
+			id: target.id,
+			url: target.url ?? "",
+			title: target.title ?? "",
+			targetWsUrl: target.webSocketDebuggerUrl
+		}));
+	}
+	async openTab(cdpUrl) {
+		const endpoint = `${cdpUrl}/json/new?${encodeURIComponent("about:blank")}`;
+		let created;
+		for (const method of ["PUT", "GET"]) try {
+			const response = await fetch(endpoint, {
+				method,
+				signal: AbortSignal.timeout(5e3)
+			});
+			if (!response.ok) continue;
+			created = await response.json();
+			if (created.webSocketDebuggerUrl) break;
+		} catch {}
+		if (!created?.webSocketDebuggerUrl) throw new Error(`Unable to open a new tab via ${cdpUrl}/json/new`);
+		const targetWsUrl = created.webSocketDebuggerUrl;
+		const host = new URL(cdpUrl).host;
+		let userAgent;
+		for (const [wsUrl, ua] of this.userAgentOverrides) if (new URL(wsUrl).host === host) {
+			userAgent = ua;
+			break;
+		}
+		const appliedUa = await initTarget(targetWsUrl, userAgent);
+		if (appliedUa) this.userAgentOverrides.set(targetWsUrl, appliedUa);
+		return {
+			id: created.id,
+			url: created.url ?? "about:blank",
+			title: created.title ?? "",
+			targetWsUrl
+		};
+	}
+	async activateTab(cdpUrl, tabId) {
+		if (!(await fetch(`${cdpUrl}/json/activate/${encodeURIComponent(tabId)}`, { signal: AbortSignal.timeout(5e3) })).ok) throw new Error(`Tab not found: ${tabId}`);
+	}
+	async closeTab(cdpUrl, tabId) {
+		const tab = (await this.listTabs(cdpUrl)).find((candidate) => candidate.id === tabId);
+		if (!tab) throw new Error(`Tab not found: ${tabId}`);
+		this.dropConnection(tab.targetWsUrl);
+		this.userAgentOverrides.delete(tab.targetWsUrl);
+		const response = await fetch(`${cdpUrl}/json/close/${encodeURIComponent(tabId)}`, { signal: AbortSignal.timeout(5e3) });
+		if (!response.ok) throw new Error(`Unable to close tab ${tabId}: HTTP ${response.status}`);
+	}
 	async getContent(targetWsUrl, options) {
 		if (options.mode === "summary") return await this.getSummaryContent(targetWsUrl, options);
 		if (options.mode === "a11y") {
@@ -1676,6 +2117,10 @@ var ChromeCdpBrowserController = class {
       const limit = options.limit ?? 50;
       const scopeSelector = options.selector;
       const roleFilter = options.roles ? new Set(options.roles) : null;
+      const hrefFilter = options.href ? String(options.href).toLowerCase() : '';
+      const textFilter = options.text
+        ? String(options.text).replace(/\\s+/g, ' ').trim().toLowerCase()
+        : '';
       const candidateSelector = [
         'a[href]',
         'button',
@@ -1947,6 +2392,7 @@ var ChromeCdpBrowserController = class {
       }
 
       const results = [];
+      const crossOriginFrames = [];
       let totalFound = 0;
 
       function maybeRecordElement(root, path, el) {
@@ -1964,6 +2410,25 @@ var ChromeCdpBrowserController = class {
         const visible = isVisible(el);
         if (visibleOnly && !visible) return;
 
+        if (hrefFilter) {
+          const href = typeof el.href === 'string' ? el.href : el.getAttribute('href');
+          if (!href || !String(href).toLowerCase().includes(hrefFilter)) return;
+        }
+        if (textFilter) {
+          const haystack = [
+            el.innerText || el.textContent || '',
+            el.getAttribute('aria-label'),
+            el.getAttribute('placeholder'),
+            el.getAttribute('title'),
+            typeof el.value === 'string' ? el.value : '',
+          ]
+            .filter(Boolean)
+            .join(' ')
+            .replace(/\\s+/g, ' ')
+            .toLowerCase();
+          if (!haystack.includes(textFilter)) return;
+        }
+
         totalFound += 1;
         if (results.length >= limit) return;
 
@@ -2007,12 +2472,21 @@ var ChromeCdpBrowserController = class {
           }
 
           if (current.tagName && current.tagName.toLowerCase() === 'iframe') {
+            let frameDocument = null;
             try {
-              if (current.contentDocument) {
-                walkRoot(current.contentDocument, path.concat(buildSelector(root, current)));
-              }
+              frameDocument = current.contentDocument;
             } catch {
-              // ignore inaccessible frames
+              frameDocument = null;
+            }
+            if (frameDocument) {
+              walkRoot(frameDocument, path.concat(buildSelector(root, current)));
+            } else if (crossOriginFrames.length < 20 && isVisible(current)) {
+              // Cross-origin: not walkable from here, report it so callers can pass it as frame.
+              const info = { selector: composeLocator(path, buildSelector(root, current)) };
+              const title = current.getAttribute('title');
+              if (title) info.title = title.slice(0, 80);
+              if (current.src) info.src = String(current.src).slice(0, 200);
+              crossOriginFrames.push(info);
             }
           }
 
@@ -2023,7 +2497,9 @@ var ChromeCdpBrowserController = class {
       }
 
       walkRoot(document, []);
-      return { elements: results, totalFound, truncated: totalFound > results.length };
+      const output = { elements: results, totalFound, truncated: totalFound > results.length };
+      if (crossOriginFrames.length) output.crossOriginFrames = crossOriginFrames;
+      return output;
 `);
 		const emptyResult = {
 			elements: [],
@@ -2037,12 +2513,31 @@ var ChromeCdpBrowserController = class {
 		};
 		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
-			const result = await evaluateOnPage(conn, {
+			const evaluate = async (client) => extract(await evaluateOnPage(client, {
 				expression,
 				returnByValue: true,
 				awaitPromise: true
-			});
-			return extract(result);
+			}));
+			if (!options.frame) return await evaluate(conn);
+			const scope = await this.openFrameScope(conn, targetWsUrl, options.frame);
+			try {
+				const inner = await evaluate(scope.client);
+				const withPrefix = (selector) => `${options.frame} >>> ${selector}`;
+				return {
+					...inner,
+					elements: inner.elements.map((element) => ({
+						...element,
+						selector: withPrefix(element.selector),
+						fallbackSelectors: element.fallbackSelectors?.map(withPrefix)
+					})),
+					crossOriginFrames: inner.crossOriginFrames?.map((frame) => ({
+						...frame,
+						selector: withPrefix(frame.selector)
+					}))
+				};
+			} finally {
+				scope.release();
+			}
 		});
 	}
 	/**
@@ -2056,22 +2551,33 @@ var ChromeCdpBrowserController = class {
 	* Returns silently on failure — never blocks navigation.
 	*/
 	async dismissCookieBanner(targetWsUrl) {
+		const notes = /* @__PURE__ */ new Set();
 		for (let attempt = 0; attempt < 2; attempt++) {
 			try {
 				const domResult = await this.dismissViaDom(targetWsUrl);
 				if (domResult.dismissed) return domResult;
-			} catch {}
+			} catch (error) {
+				notes.add(`dom: ${error.message}`);
+			}
 			try {
 				const iframeResult = await this.dismissViaIframe(targetWsUrl);
 				if (iframeResult.dismissed) return iframeResult;
-			} catch {}
+				if (iframeResult.detail) notes.add(iframeResult.detail);
+			} catch (error) {
+				notes.add(`iframe: ${error.message}`);
+			}
 			try {
 				const a11yResult = await this.dismissViaA11y(targetWsUrl);
 				if (a11yResult.dismissed) return a11yResult;
-			} catch {}
+			} catch (error) {
+				notes.add(`a11y: ${error.message}`);
+			}
 			if (attempt === 0) await new Promise((resolve) => setTimeout(resolve, 800));
 		}
-		return { dismissed: false };
+		return {
+			dismissed: false,
+			detail: notes.size ? [...notes].join("; ") : "no consent banner or accept button found (page, consent iframes, a11y tree)"
+		};
 	}
 	async dismissViaDom(targetWsUrl) {
 		const expression = `(() => {
@@ -2326,7 +2832,42 @@ var ChromeCdpBrowserController = class {
 	* These banners render inside an iframe that needs to be accessed separately.
 	*/
 	async dismissViaIframe(targetWsUrl) {
+		const innerSearch = `function (doc) {
+      const innerSelectors = [
+        // Sourcepoint specific
+        'button.sp_choice_type_11',              // Accept all
+        'button.sp_choice_type_ACCEPT_ALL',      // Accept all variant
+        'button.sp_choice_type_SAVE_AND_EXIT',   // Save & exit
+        '.priv-save-btn',                        // Sourcepoint frame
+        '.message-button',                       // Generic Sourcepoint
+        // Title-based
+        'button[title*="Accept"]', 'button[title*="accept"]',
+        'button[title*="Agree"]', 'button[title*="agree"]',
+        'button[title*="Allow"]',
+        'button[title*="Akzeptieren"]', 'button[title*="akzeptieren"]',
+        'button[title*="Zustimmen"]',
+      ];
+      for (const innerSel of innerSelectors) {
+        const btn = doc.querySelector(innerSel);
+        if (btn && btn.offsetWidth > 0) {
+          btn.click();
+          return { method: 'iframe', detail: innerSel };
+        }
+      }
+      // Text-based fallback inside the iframe
+      const buttons = doc.querySelectorAll('button, [role="button"]');
+      for (const btn of buttons) {
+        const text = (btn.textContent || '').trim();
+        if (text.length > 60) continue;
+        if (/accept|agree|allow|akzeptieren|zustimmen|einwilligen|accepter|aceptar/i.test(text)) {
+          btn.click();
+          return { method: 'iframe-text', detail: text };
+        }
+      }
+      return null;
+    }`;
 		const expression = `(() => {
+      const clickAccept = ${innerSearch};
       // Known consent iframe selectors
       const iframeSelectors = [
         'iframe[id^="sp_message_iframe"]',              // Sourcepoint (dynamic ID suffix)
@@ -2347,62 +2888,69 @@ var ChromeCdpBrowserController = class {
         'iframe[src*="consentmanager"]',
       ];
 
+      // Cross-origin consent frames are handed back so the caller can attach to them.
+      const crossOrigin = [];
       for (const sel of iframeSelectors) {
+        const iframe = document.querySelector(sel);
+        if (!iframe) continue;
+        let doc = null;
         try {
-          const iframe = document.querySelector(sel);
-          if (!iframe) continue;
-          const doc = iframe.contentDocument || iframe.contentWindow?.document;
-          if (!doc) continue;
-
-          // Try known selectors inside the iframe
-          const innerSelectors = [
-            // Sourcepoint specific
-            'button.sp_choice_type_11',              // Accept all
-            'button.sp_choice_type_ACCEPT_ALL',      // Accept all variant
-            'button.sp_choice_type_SAVE_AND_EXIT',   // Save & exit
-            '.priv-save-btn',                        // Sourcepoint frame
-            '.message-button',                       // Generic Sourcepoint
-            // Title-based
-            'button[title*="Accept"]', 'button[title*="accept"]',
-            'button[title*="Agree"]', 'button[title*="agree"]',
-            'button[title*="Allow"]',
-            'button[title*="Akzeptieren"]', 'button[title*="akzeptieren"]',
-            'button[title*="Zustimmen"]',
-          ];
-          for (const innerSel of innerSelectors) {
-            const btn = doc.querySelector(innerSel);
-            if (btn && btn.offsetWidth > 0) {
-              btn.click();
-              return JSON.stringify({ dismissed: true, method: 'iframe', detail: sel + ' > ' + innerSel });
-            }
-          }
-
-          // Text-based fallback inside iframe
-          const buttons = doc.querySelectorAll('button, [role="button"]');
-          for (const btn of buttons) {
-            const text = (btn.textContent || '').trim();
-            if (text.length > 60) continue;
-            if (/accept|agree|allow|akzeptieren|zustimmen|einwilligen|accepter|aceptar/i.test(text)) {
-              btn.click();
-              return JSON.stringify({ dismissed: true, method: 'iframe-text', detail: text });
-            }
-          }
-        } catch { /* cross-origin iframe — skip */ }
+          doc = iframe.contentDocument || iframe.contentWindow?.document || null;
+        } catch {
+          doc = null;
+        }
+        if (!doc) {
+          const locator = iframe.id ? '#' + CSS.escape(iframe.id) : sel;
+          if (!crossOrigin.includes(locator)) crossOrigin.push(locator);
+          continue;
+        }
+        const hit = clickAccept(doc);
+        if (hit) return { dismissed: true, method: hit.method, detail: sel + ' > ' + hit.detail };
       }
-
-      return JSON.stringify({ dismissed: false });
+      return { dismissed: false, crossOrigin };
     })()`;
 		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
-			const raw = (await evaluateOnPage(conn, {
+			const value = (await evaluateOnPage(conn, {
 				expression,
 				returnByValue: true
-			})).result.value ?? "{\"dismissed\":false}";
-			try {
-				return JSON.parse(raw);
-			} catch {
-				return { dismissed: false };
+			})).result.value;
+			if (!value) return { dismissed: false };
+			if (value.dismissed) return {
+				dismissed: true,
+				method: value.method,
+				detail: value.detail
+			};
+			const notes = [];
+			for (const frame of value.crossOrigin ?? []) {
+				let scope;
+				try {
+					scope = await this.openFrameScope(conn, targetWsUrl, frame);
+				} catch (error) {
+					notes.push(`consent iframe ${frame}: ${error.message}`);
+					continue;
+				}
+				try {
+					const hit = (await evaluateOnPage(scope.client, {
+						expression: `(${innerSearch})(document)`,
+						returnByValue: true
+					})).result.value;
+					if (hit) return {
+						dismissed: true,
+						method: hit.method,
+						detail: `${frame} >>> ${hit.detail}`
+					};
+					notes.push(`consent iframe ${frame}: no accept button found`);
+				} catch (error) {
+					notes.push(`consent iframe ${frame}: ${error.message}`);
+				} finally {
+					scope.release();
+				}
 			}
+			return notes.length ? {
+				dismissed: false,
+				detail: notes.join("; ")
+			} : { dismissed: false };
 		});
 	}
 	/**
@@ -2599,6 +3147,64 @@ var MockBrowserController = class {
 	async getCurrentUrl(cdpUrl) {
 		return this.pages.get(cdpUrl)?.url ?? "about:blank";
 	}
+	tabs = /* @__PURE__ */ new Map();
+	tabCounter = 0;
+	/** Tab ids are the page keys (targetWsUrl); the initial page is the cdpUrl itself. */
+	tabIds(cdpUrl) {
+		let ids = this.tabs.get(cdpUrl);
+		if (!ids) {
+			ids = this.pages.has(cdpUrl) ? [cdpUrl] : [];
+			this.tabs.set(cdpUrl, ids);
+		}
+		return ids;
+	}
+	async getPageState(targetWsUrl) {
+		const page = this.pages.get(targetWsUrl);
+		if (!page) throw new Error("mock page missing");
+		return {
+			url: page.url,
+			title: page.title,
+			readyState: "complete"
+		};
+	}
+	async listTabs(cdpUrl) {
+		return this.tabIds(cdpUrl).map((id) => {
+			const page = this.pages.get(id);
+			return {
+				id,
+				url: page?.url ?? "about:blank",
+				title: page?.title ?? "",
+				targetWsUrl: id
+			};
+		});
+	}
+	async openTab(cdpUrl) {
+		this.tabCounter += 1;
+		const id = `${cdpUrl}/tab-${this.tabCounter}`;
+		this.pages.set(id, {
+			url: "about:blank",
+			title: "about:blank",
+			text: "",
+			html: "<html><body></body></html>"
+		});
+		this.tabIds(cdpUrl).push(id);
+		return {
+			id,
+			url: "about:blank",
+			title: "about:blank",
+			targetWsUrl: id
+		};
+	}
+	async activateTab(cdpUrl, tabId) {
+		if (!this.tabIds(cdpUrl).includes(tabId)) throw new Error(`Tab not found: ${tabId}`);
+	}
+	async closeTab(cdpUrl, tabId) {
+		const ids = this.tabIds(cdpUrl);
+		const index = ids.indexOf(tabId);
+		if (index === -1) throw new Error(`Tab not found: ${tabId}`);
+		ids.splice(index, 1);
+		this.pages.delete(tabId);
+	}
 	async getContent(cdpUrl, options) {
 		const page = this.pages.get(cdpUrl);
 		if (!page) throw new Error("mock page missing");
@@ -2640,8 +3246,7 @@ var MockBrowserController = class {
 	terminate(_pid) {}
 	closeConnection(_targetWsUrl) {}
 };
-//#endregion
-//#region src/lib/domain-schemas.ts
+// src/lib/domain-schemas.ts
 const InteractActionSchema = z.enum([
 	"click",
 	"type",
@@ -2666,7 +3271,8 @@ const InteractPayloadSchema = z.object({
 	value: z.string().optional(),
 	scrollX: z.number().optional(),
 	scrollY: z.number().optional(),
-	timeoutMs: z.number().optional()
+	timeoutMs: z.number().optional(),
+	frame: z.string().optional()
 });
 const SessionStatusSchema = z.enum([
 	"starting",
@@ -2747,12 +3353,11 @@ z.object({
 	createdAt: z.string().datetime(),
 	severity: EventSeveritySchema
 });
-//#endregion
-//#region src/session/session-store.ts
+// src/session/session-store.ts
 var SessionStore = class {
 	filePath;
 	constructor(baseDir) {
-		fs.mkdirSync(baseDir, { recursive: true });
+		ensurePrivateDir(baseDir);
 		this.filePath = path.join(baseDir, "sessions.json");
 		if (!fs.existsSync(this.filePath)) this.write({ sessions: {} });
 	}
@@ -2838,12 +3443,68 @@ var SessionStore = class {
 	}
 	write(state) {
 		const tmp = `${this.filePath}.${process.pid}.tmp`;
-		fs.writeFileSync(tmp, JSON.stringify(state, null, 2), "utf8");
+		writePrivateFileSync(tmp, JSON.stringify(state, null, 2));
 		fs.renameSync(tmp, this.filePath);
 	}
 };
-//#endregion
-//#region src/session/session-manager.ts
+// src/session/url-policy.ts
+function assertNavigableUrl(raw, opts) {
+	let parsed;
+	try {
+		parsed = new URL(raw);
+	} catch {
+		throw new Error(`Invalid URL: ${raw}`);
+	}
+	const { protocol } = parsed;
+	if (protocol === "http:" || protocol === "https:") return;
+	if (raw === "about:blank") return;
+	if (protocol === "file:" && opts.allowFileUrls) return;
+	throw new Error(`Navigation to ${protocol} URLs is not allowed${protocol === "file:" ? " (set AGENTIC_BROWSER_ALLOW_FILE_URLS=true to allow file: URLs)" : ""}`);
+}
+// src/memory/redact-step-payload.ts
+const ALLOWED_KEYS = /* @__PURE__ */ new Set([
+	"action",
+	"selector",
+	"fallbackSelectors",
+	"ref",
+	"key",
+	"direction",
+	"amount",
+	"deltaY",
+	"scrollX",
+	"scrollY",
+	"timeoutMs",
+	"redacted"
+]);
+const URL_IN_TEXT = /\bhttps?:\/\/[^\s"'<>]+/gi;
+/** Reduce a URL to origin + pathname, dropping query string and fragment. */
+function stripUrl(rawUrl) {
+	try {
+		const parsed = new URL(rawUrl);
+		return `${parsed.origin}${parsed.pathname}`;
+	} catch {
+		return;
+	}
+}
+/** Strip query strings and fragments from every http(s) URL embedded in free text. */
+function redactUrlsInText(text) {
+	return text.replace(URL_IN_TEXT, (match) => stripUrl(match) ?? "[url]");
+}
+/** Keep only structural, non-secret keys of a step payload; typed text and values are dropped. */
+function redactStepPayload(payload) {
+	const result = {};
+	for (const [key, value] of Object.entries(payload)) {
+		if (key === "url") {
+			const stripped = typeof value === "string" ? stripUrl(value) : void 0;
+			if (stripped !== void 0) result.url = stripped;
+			continue;
+		}
+		if (ALLOWED_KEYS.has(key)) result[key] = value;
+	}
+	if ("text" in payload || "value" in payload) result.redacted = true;
+	return result;
+}
+// src/session/session-manager.ts
 var SessionManager = class {
 	ctx;
 	browser;
@@ -2926,6 +3587,7 @@ var SessionManager = class {
 			if (input.type === "navigate") {
 				const url = String(input.payload.url ?? "");
 				if (!url) throw new Error("navigate command requires payload.url");
+				assertNavigableUrl(url, { allowFileUrls: this.ctx.config.allowFileUrls });
 				const finalUrl = await this.browser.navigate(record.targetWsUrl, url);
 				this.store.setLastUrl(sessionId, finalUrl);
 				resultMessage = `Navigated to ${finalUrl}`;
@@ -3001,6 +3663,68 @@ var SessionManager = class {
 		const record = await this.ensureSession(sessionId);
 		return await this.browser.getCurrentUrl(record.targetWsUrl);
 	}
+	async getPageState(sessionId) {
+		const record = await this.ensureSession(sessionId);
+		return await this.browser.getPageState(record.targetWsUrl);
+	}
+	async listTabs(sessionId) {
+		const record = await this.ensureSession(sessionId);
+		return (await this.browser.listTabs(record.cdpUrl)).map((tab) => ({
+			...tab,
+			active: tab.targetWsUrl === record.targetWsUrl
+		}));
+	}
+	/** Points the session at another tab; later commands run there. */
+	async switchTab(sessionId, tabId) {
+		const record = await this.ensureSession(sessionId);
+		const tab = (await this.browser.listTabs(record.cdpUrl)).find((t) => t.id === tabId);
+		if (!tab) throw new Error(`Tab not found: ${tabId}`);
+		await this.browser.activateTab(record.cdpUrl, tab.id);
+		this.store.save({
+			...record,
+			targetWsUrl: tab.targetWsUrl,
+			lastUrl: tab.url || record.lastUrl
+		});
+		this.recordEvent(sessionId, "lifecycle", "info", `Switched to tab ${tab.id}`);
+		return tab;
+	}
+	async newTab(sessionId) {
+		const record = await this.ensureSession(sessionId);
+		const tab = await this.browser.openTab(record.cdpUrl);
+		await this.browser.activateTab(record.cdpUrl, tab.id);
+		this.store.save({
+			...record,
+			targetWsUrl: tab.targetWsUrl,
+			lastUrl: tab.url
+		});
+		this.recordEvent(sessionId, "lifecycle", "info", `Opened tab ${tab.id}`);
+		return tab;
+	}
+	/** Closes a tab; closing the active one moves the session to a remaining tab. */
+	async closeTab(sessionId, tabId) {
+		const record = await this.ensureSession(sessionId);
+		const tabs = await this.browser.listTabs(record.cdpUrl);
+		const target = tabs.find((t) => t.id === tabId);
+		if (!target) throw new Error(`Tab not found: ${tabId}`);
+		const remaining = tabs.filter((t) => t.id !== tabId);
+		if (remaining.length === 0) throw new Error("Refusing to close the last tab; use agent stop to end the session");
+		await this.browser.closeTab(record.cdpUrl, tabId);
+		let active = tabs.find((t) => t.targetWsUrl === record.targetWsUrl) ?? remaining[0];
+		if (target.targetWsUrl === record.targetWsUrl) {
+			active = remaining[remaining.length - 1];
+			await this.browser.activateTab(record.cdpUrl, active.id);
+			this.store.save({
+				...record,
+				targetWsUrl: active.targetWsUrl,
+				lastUrl: active.url
+			});
+		}
+		this.recordEvent(sessionId, "lifecycle", "info", `Closed tab ${tabId}`);
+		return {
+			closed: tabId,
+			active
+		};
+	}
 	async dismissCookieBanner(sessionId) {
 		const record = await this.ensureSession(sessionId);
 		const result = await this.browser.dismissCookieBanner(record.targetWsUrl);
@@ -3219,7 +3943,7 @@ var SessionManager = class {
 				type: input.type === "navigate" ? "navigate" : input.type === "interact" ? "interact" : "assert",
 				summary: input.type === "interact" ? `interact:${action ?? "unknown"}` : input.type,
 				selector,
-				payload: input.payload
+				payload: redactStepPayload(input.payload)
 			},
 			selector,
 			url: inputUrl
@@ -3246,8 +3970,7 @@ var SessionManager = class {
 		}
 	}
 };
-//#endregion
-//#region src/transport/control-api.ts
+// src/transport/control-api.ts
 var ControlApi = class {
 	sessions;
 	constructor(sessions) {
@@ -3286,6 +4009,21 @@ var ControlApi = class {
 	async getCurrentUrl(sessionId) {
 		return await this.sessions.getCurrentUrl(sessionId);
 	}
+	async getPageState(sessionId) {
+		return await this.sessions.getPageState(sessionId);
+	}
+	async listTabs(sessionId) {
+		return await this.sessions.listTabs(sessionId);
+	}
+	async switchTab(sessionId, tabId) {
+		return await this.sessions.switchTab(sessionId, tabId);
+	}
+	async newTab(sessionId) {
+		return await this.sessions.newTab(sessionId);
+	}
+	async closeTab(sessionId, tabId) {
+		return await this.sessions.closeTab(sessionId, tabId);
+	}
 	listEvents(sessionId, limit = 100) {
 		return { events: this.sessions.listEvents(sessionId, limit) };
 	}
@@ -3305,8 +4043,7 @@ var ControlApi = class {
 		return this.sessions.cleanupSessions(input);
 	}
 };
-//#endregion
-//#region src/lib/config.ts
+// src/lib/config.ts
 function loadConfig(env = process.env) {
 	const userProfile = env.AGENTIC_BROWSER_USER_PROFILE;
 	let userProfileDir;
@@ -3318,11 +4055,11 @@ function loadConfig(env = process.env) {
 		cdpUrl: env.AGENTIC_BROWSER_CDP_URL,
 		userProfileDir,
 		headless: env.AGENTIC_BROWSER_HEADLESS === "true" || env.AGENTIC_BROWSER_HEADLESS === "1",
-		userAgent: env.AGENTIC_BROWSER_USER_AGENT || void 0
+		userAgent: env.AGENTIC_BROWSER_USER_AGENT || void 0,
+		allowFileUrls: env.AGENTIC_BROWSER_ALLOW_FILE_URLS === "true" || env.AGENTIC_BROWSER_ALLOW_FILE_URLS === "1"
 	};
 }
-//#endregion
-//#region src/observability/logger.ts
+// src/observability/logger.ts
 var Logger = class {
 	namespace;
 	constructor(namespace) {
@@ -3353,8 +4090,7 @@ var Logger = class {
 		this.emit("error", message, context);
 	}
 };
-//#endregion
-//#region src/observability/event-store.ts
+// src/observability/event-store.ts
 const MAX_EVENTS_PER_SESSION = 500;
 var EventStore = class {
 	events = /* @__PURE__ */ new Map();
@@ -3364,8 +4100,11 @@ var EventStore = class {
 	pendingFlushDelayMs = Number.POSITIVE_INFINITY;
 	flushInFlight;
 	constructor(baseDir) {
-		fs.mkdirSync(baseDir, { recursive: true });
+		ensurePrivateDir(baseDir);
 		this.filePath = path.join(baseDir, "session-events.log");
+		try {
+			if (fs.existsSync(this.filePath)) fs.chmodSync(this.filePath, 384);
+		} catch {}
 		process.on("beforeExit", this.flushSync);
 		process.on("exit", this.flushSync);
 	}
@@ -3416,7 +4155,10 @@ var EventStore = class {
 	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 = fs.promises.appendFile(this.filePath, chunk, {
+			encoding: "utf8",
+			mode: 384
+		}).catch(() => {}).finally(() => {
 			this.flushInFlight = void 0;
 			if (this.bufferedLines.length > 0) this.flushSoon(0);
 		});
@@ -3430,12 +4172,14 @@ var EventStore = class {
 		if (this.bufferedLines.length === 0) return;
 		const chunk = this.bufferedLines.splice(0, this.bufferedLines.length).join("");
 		try {
-			fs.appendFileSync(this.filePath, chunk, "utf8");
+			fs.appendFileSync(this.filePath, chunk, {
+				encoding: "utf8",
+				mode: 384
+			});
 		} catch {}
 	};
 };
-//#endregion
-//#region src/auth/session-token.ts
+// src/auth/session-token.ts
 var SessionTokenService = class {
 	tokens = /* @__PURE__ */ new Map();
 	issue(sessionId) {
@@ -3461,8 +4205,7 @@ var SessionTokenService = class {
 		this.tokens.set(sessionId, token);
 	}
 };
-//#endregion
-//#region src/memory/memory-index.ts
+// src/memory/memory-index.ts
 function normalize(value) {
 	return value.trim().toLowerCase();
 }
@@ -3571,8 +4314,7 @@ var MemoryIndex = class {
 		return candidates.map((insight) => scoreInsight(insight, normalizedIntent, normalizedDomain, profileLookup)).filter(relevant).toSorted((a, b) => b.result.score - a.result.score).slice(0, limit).map((scored) => scored.result);
 	}
 };
-//#endregion
-//#region src/memory/staleness-detector.ts
+// src/memory/staleness-detector.ts
 const MAX_SUSPECT_STRIKES = 2;
 function detectStalenessSignal(errorMessage, selector) {
 	const lowered = errorMessage.toLowerCase();
@@ -3600,7 +4342,7 @@ function applyFailure(insight, signal) {
 	};
 }
 function applyAgeStaleness(insight) {
-	const ageDays = (Date.now() - Date.parse(insight.lastVerifiedAt)) / (1440 * 60 * 1e3);
+	const ageDays = (Date.now() - Date.parse(insight.lastVerifiedAt)) / 864e5;
 	if (insight.freshness === "fresh" && ageDays > 30) return {
 		...insight,
 		freshness: "suspect",
@@ -3627,8 +4369,57 @@ function applySuccess(insight) {
 		updatedAt: now
 	};
 }
-//#endregion
-//#region src/memory/memory-schemas.ts
+// src/lib/flush-registry.ts
+const REGISTRY = Symbol.for("agentic-browser.flush-registry");
+function flushAll(items) {
+	for (const item of items) try {
+		item.flushSync();
+	} catch {}
+}
+function createRegistry() {
+	const items = /* @__PURE__ */ new Set();
+	const onSignal = (signal) => {
+		flushAll(items);
+		if (process.listenerCount(signal) === 1) process.exit(0);
+	};
+	return {
+		items,
+		onExit: () => flushAll(items),
+		onSigint: () => onSignal("SIGINT"),
+		onSigterm: () => onSignal("SIGTERM")
+	};
+}
+/**
+* Register an item to be flushed synchronously on process exit / SIGINT / SIGTERM.
+* Returns an idempotent unregister function; the process listeners are removed
+* once the last item is unregistered.
+*/
+function registerFlushable(item) {
+	const proc = process;
+	let registry = proc[REGISTRY];
+	if (!registry) {
+		registry = createRegistry();
+		proc[REGISTRY] = registry;
+		process.on("exit", registry.onExit);
+		process.on("SIGINT", registry.onSigint);
+		process.on("SIGTERM", registry.onSigterm);
+	}
+	registry.items.add(item);
+	const owner = registry;
+	let done = false;
+	return () => {
+		if (done) return;
+		done = true;
+		owner.items.delete(item);
+		if (owner.items.size === 0 && proc[REGISTRY] === owner) {
+			process.off("exit", owner.onExit);
+			process.off("SIGINT", owner.onSigint);
+			process.off("SIGTERM", owner.onSigterm);
+			delete proc[REGISTRY];
+		}
+	};
+}
+// src/memory/memory-schemas.ts
 const InsightFreshnessSchema = z.enum([
 	"fresh",
 	"suspect",
@@ -3705,27 +4496,25 @@ const SiteProfileSchema = z.object({
 	createdAt: z.string().datetime()
 });
 const SiteProfileStateSchema = z.object({ profiles: z.array(SiteProfileSchema) });
-//#endregion
-//#region src/memory/site-profile-store.ts
+// src/memory/site-profile-store.ts
 const EMPTY_STATE$1 = { profiles: [] };
 const FLUSH_DELAY_MS$1 = 500;
-const REGISTERED_EXIT_HANDLERS$1 = Symbol.for("agentic-browser.site-profile-store.exit-handlers");
-const REGISTERED_STORES$1 = Symbol.for("agentic-browser.site-profile-store.instances");
 var SiteProfileStore = class {
 	filePath;
 	cached = null;
 	dirty = false;
 	flushTimer = null;
+	unregister;
 	constructor(baseDir) {
 		const memoryDir = path.join(baseDir, "memory");
-		fs.mkdirSync(memoryDir, { recursive: true });
+		ensurePrivateDir(memoryDir);
 		this.filePath = path.join(memoryDir, "site-profiles.json");
 		const tmpPath = `${this.filePath}.tmp`;
 		try {
 			if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
 		} catch {}
 		if (!fs.existsSync(this.filePath)) this.writeDisk(EMPTY_STATE$1);
-		this.registerProcessHandlers();
+		this.unregister = registerFlushable(this);
 	}
 	list() {
 		return this.getCache();
@@ -3746,6 +4535,11 @@ var SiteProfileStore = class {
 		else profiles.push(normalized);
 		this.markDirty();
 	}
+	/** Flush pending writes and stop flushing on process exit. Idempotent. */
+	dispose() {
+		this.flushSync();
+		this.unregister();
+	}
 	flushSync() {
 		if (this.flushTimer) {
 			clearTimeout(this.flushTimer);
@@ -3802,51 +4596,30 @@ var SiteProfileStore = class {
 	}
 	writeDisk(state) {
 		const tempPath = `${this.filePath}.tmp`;
-		fs.writeFileSync(tempPath, JSON.stringify(state, null, 2), "utf8");
+		writePrivateFileSync(tempPath, JSON.stringify(state, null, 2));
 		fs.renameSync(tempPath, this.filePath);
 	}
-	registerProcessHandlers() {
-		const proc = process;
-		const stores = proc[REGISTERED_STORES$1] ??= /* @__PURE__ */ new Set();
-		stores.add(this);
-		if (proc[REGISTERED_EXIT_HANDLERS$1]) return;
-		proc[REGISTERED_EXIT_HANDLERS$1] = true;
-		const flushAll = () => {
-			for (const store of stores) store.flushSync();
-		};
-		process.on("exit", flushAll);
-		process.on("SIGINT", () => {
-			flushAll();
-			process.exit(0);
-		});
-		process.on("SIGTERM", () => {
-			flushAll();
-			process.exit(0);
-		});
-	}
 };
-//#endregion
-//#region src/memory/task-insight-store.ts
+// src/memory/task-insight-store.ts
 const EMPTY_STATE = { insights: [] };
 const FLUSH_DELAY_MS = 500;
-const REGISTERED_EXIT_HANDLERS = Symbol.for("agentic-browser.task-insight-store.exit-handlers");
-const REGISTERED_STORES = Symbol.for("agentic-browser.task-insight-store.instances");
 var TaskInsightStore = class {
 	filePath;
 	/** In-memory cache – authoritative after first load. */
 	cached = null;
 	dirty = false;
 	flushTimer = null;
+	unregister;
 	constructor(baseDir) {
 		const memoryDir = path.join(baseDir, "memory");
-		fs.mkdirSync(memoryDir, { recursive: true });
+		ensurePrivateDir(memoryDir);
 		this.filePath = path.join(memoryDir, "insights.json");
 		const tmpPath = `${this.filePath}.tmp`;
 		try {
 			if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
 		} catch {}
 		if (!fs.existsSync(this.filePath)) this.writeDisk(EMPTY_STATE);
-		this.registerProcessHandlers();
+		this.unregister = registerFlushable(this);
 	}
 	list() {
 		return this.getCache();
@@ -3876,6 +4649,11 @@ var TaskInsightStore = class {
 		this.cached = insights;
 		this.markDirty();
 	}
+	/** Flush pending writes and stop flushing on process exit. Idempotent. */
+	dispose() {
+		this.flushSync();
+		this.unregister();
+	}
 	/** Force an immediate synchronous flush (used at shutdown). */
 	flushSync() {
 		if (this.flushTimer) {
@@ -3892,8 +4670,52 @@ var TaskInsightStore = class {
 		if (this.cached) return this.cached;
 		const state = this.readDisk();
 		this.cached = state.insights;
+		if (this.sanitizeCached(this.cached)) this.markDirty();
 		return this.cached;
 	}
+	/**
+	* Redact already-persisted step payloads and URL query strings/fragments in place.
+	* Returns true if anything changed.
+	*/
+	sanitizeCached(insights) {
+		let changed = false;
+		for (const insight of insights) {
+			const expectedOutcome = redactUrlsInText(insight.expectedOutcome);
+			if (expectedOutcome !== insight.expectedOutcome) {
+				insight.expectedOutcome = expectedOutcome;
+				changed = true;
+			}
+			const taskIntent = redactUrlsInText(insight.taskIntent);
+			if (taskIntent !== insight.taskIntent) {
+				insight.taskIntent = taskIntent;
+				changed = true;
+			}
+			for (const evidence of insight.evidence) {
+				if (evidence.url !== void 0) {
+					const url = stripUrl(evidence.url);
+					if (url !== evidence.url) {
+						evidence.url = url;
+						changed = true;
+					}
+				}
+				if (evidence.reason !== void 0) {
+					const reason = redactUrlsInText(evidence.reason);
+					if (reason !== evidence.reason) {
+						evidence.reason = reason;
+						changed = true;
+					}
+				}
+			}
+			for (const step of insight.actionRecipe) {
+				const redacted = redactStepPayload(step.payload);
+				if (JSON.stringify(redacted) !== JSON.stringify(step.payload)) {
+					step.payload = redacted;
+					changed = true;
+				}
+			}
+		}
+		return changed;
+	}
 	markDirty() {
 		this.dirty = true;
 		if (!this.flushTimer) this.flushTimer = setTimeout(() => {
@@ -3935,31 +4757,11 @@ var TaskInsightStore = class {
 	}
 	writeDisk(state) {
 		const tempPath = `${this.filePath}.tmp`;
-		fs.writeFileSync(tempPath, JSON.stringify(state, null, 2), "utf8");
+		writePrivateFileSync(tempPath, JSON.stringify(state, null, 2));
 		fs.renameSync(tempPath, this.filePath);
 	}
-	registerProcessHandlers() {
-		const proc = process;
-		const stores = proc[REGISTERED_STORES] ??= /* @__PURE__ */ new Set();
-		stores.add(this);
-		if (proc[REGISTERED_EXIT_HANDLERS]) return;
-		proc[REGISTERED_EXIT_HANDLERS] = true;
-		const flushAll = () => {
-			for (const store of stores) store.flushSync();
-		};
-		process.on("exit", flushAll);
-		process.on("SIGINT", () => {
-			flushAll();
-			process.exit(0);
-		});
-		process.on("SIGTERM", () => {
-			flushAll();
-			process.exit(0);
-		});
-	}
 };
-//#endregion
-//#region src/memory/memory-service.ts
+// src/memory/memory-service.ts
 /** Memory service configuration */
 const SEARCH_CACHE_TTL_MS = 2e3;
 const MAX_SELECTOR_ALIASES = 10;
@@ -3987,6 +4789,11 @@ var MemoryService = class {
 		this.store.flushSync();
 		this.profileStore.flushSync();
 	}
+	/** Flush pending writes and release the stores' process exit hooks. */
+	dispose() {
+		this.store.dispose();
+		this.profileStore.dispose();
+	}
 	search(input) {
 		const cacheKey = `${input.taskIntent}\0${input.siteDomain ?? ""}\0${input.limit ?? 10}`;
 		const now = Date.now();
@@ -4048,7 +4855,8 @@ var MemoryService = class {
 		this.invalidateSearchCache();
 		return verified;
 	}
-	recordSuccess(input) {
+	recordSuccess(rawInput) {
+		const input = this.sanitizeInput(rawInput);
 		this.updateSiteProfile(input.siteDomain, input.selector, input.url, input.sitePathPattern);
 		const insights = this.store.list();
 		const matched = this.findBestExactMatch(insights, input);
@@ -4107,13 +4915,14 @@ var MemoryService = class {
 		this.invalidateSearchCache();
 		return withAliases;
 	}
-	recordFailure(input, errorMessage) {
+	recordFailure(rawInput, errorMessage) {
+		const input = this.sanitizeInput(rawInput);
 		this.updateSiteProfile(input.siteDomain, input.selector, input.url, input.sitePathPattern);
 		const insights = this.store.list();
 		const matched = this.findBestExactMatch(insights, input);
 		if (!matched) return;
 		const signal = detectStalenessSignal(errorMessage, input.selector);
-		const evidence = this.createEvidence(input, "failure", errorMessage);
+		const evidence = this.createEvidence(input, "failure", redactUrlsInText(errorMessage));
 		const failed = applyFailure({
 			...matched,
 			useCount: matched.useCount + 1,
@@ -4235,6 +5044,15 @@ var MemoryService = class {
 		const rightSegment = normalizePathSegment(right);
 		return Boolean(leftSegment) && leftSegment === rightSegment;
 	}
+	/** Strip query strings and fragments from every URL-bearing field before it is persisted. */
+	sanitizeInput(input) {
+		return {
+			...input,
+			url: input.url ? stripUrl(input.url) ?? void 0 : void 0,
+			expectedOutcome: redactUrlsInText(input.expectedOutcome),
+			taskIntent: redactUrlsInText(input.taskIntent)
+		};
+	}
 	createEvidence(input, result, reason) {
 		return {
 			evidenceId: crypto.randomUUID(),
@@ -4287,8 +5105,7 @@ var MemoryService = class {
 		return [...recipe, step].slice(-8);
 	}
 };
-//#endregion
-//#region src/cli/app.ts
+// src/cli/app.ts
 function createAppContext(env = process.env) {
 	const config = loadConfig(env);
 	return {
@@ -4299,17 +5116,31 @@ function createAppContext(env = process.env) {
 		memoryService: new MemoryService(config.dataDir)
 	};
 }
-//#endregion
-//#region src/cli/runtime.ts
+// src/cli/runtime.ts
 var AgenticBrowserCore = class {
 	context;
 	sessions;
 	api;
+	browserController;
+	disposed = false;
 	constructor(context, browserController) {
 		this.context = context;
+		this.browserController = browserController;
 		this.sessions = new SessionManager(context, browserController);
 		this.api = new ControlApi(this.sessions);
 	}
+	/**
+	* Release process-level resources (event store and memory store exit handlers,
+	* controller timers). Flushes pending memory writes.
+	* Does not terminate browser sessions. Idempotent.
+	*/
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.browserController.dispose?.();
+		this.context.eventStore.dispose();
+		this.context.memoryService.dispose();
+	}
 	async startSession(input = { browser: "chrome" }) {
 		return await this.api.createSession(input);
 	}
@@ -4336,7 +5167,10 @@ var AgenticBrowserCore = class {
 			roles: input.roles,
 			visibleOnly: input.visibleOnly,
 			limit: input.limit,
-			selector: input.selector
+			selector: input.selector,
+			href: input.href,
+			text: input.text,
+			frame: input.frame
 		});
 	}
 	async dismissCookieBanner(sessionId) {
@@ -4348,6 +5182,21 @@ var AgenticBrowserCore = class {
 	async getCurrentUrl(sessionId) {
 		return await this.api.getCurrentUrl(sessionId);
 	}
+	async getPageState(sessionId) {
+		return await this.api.getPageState(sessionId);
+	}
+	async listTabs(sessionId) {
+		return await this.api.listTabs(sessionId);
+	}
+	async switchTab(sessionId, tabId) {
+		return await this.api.switchTab(sessionId, tabId);
+	}
+	async newTab(sessionId) {
+		return await this.api.newTab(sessionId);
+	}
+	async closeTab(sessionId, tabId) {
+		return await this.api.closeTab(sessionId, tabId);
+	}
 	async restartSession(sessionId) {
 		return await this.api.restartSession(sessionId);
 	}
@@ -4380,5 +5229,4 @@ function createMockAgenticBrowserCore(env) {
 function createCliRuntime() {
 	return createAgenticBrowserCore();
 }
-//#endregion
-export { createMockAgenticBrowserCore as i, createAgenticBrowserCore as n, createCliRuntime as r, AgenticBrowserCore as t };
+export { isConnectionError as a, createMockAgenticBrowserCore as i, createAgenticBrowserCore as n, ensurePrivateDir as o, createCliRuntime as r, writePrivateFileSync as s, AgenticBrowserCore as t };