agentic-browser 2.6.2 → 2.7.1

package/dist/{runtime-Bo7FmRYk.mjs → runtime-CnexYwrf.mjs}

@@ -393,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
@@ -493,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;
@@ -500,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) {
@@ -556,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) {
@@ -1015,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);
@@ -1276,32 +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);
-				const nav = await this.armMainFrameNavigationWait(conn);
-				await this.dispatchMouseClick(conn, point.x, point.y);
-				await nav.result;
-				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();
@@ -1319,7 +1597,7 @@ var ChromeCdpBrowserController = class {
         if (result && typeof result === 'object' && typeof result.then === 'function') {
           result = await result;
         }
-        return typeof result === 'string' ? result : JSON.stringify(result);
+        return result === undefined ? 'undefined' : JSON.stringify(result);
       }
       if (payload.action === 'scroll') {
         if (payload.selector) {
@@ -1348,11 +1626,18 @@ 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"}
+  );
+  // Always JSON-encode so strings like "42" or "" survive the round trip as strings.
+  return __agenticResult === undefined ? 'undefined' : JSON.stringify(__agenticResult);
+})()` : buildExpression(scoped),
+					returnByValue: true,
+					awaitPromise: true
+				})).result.value ?? "";
+			});
 		}, "connection");
 	}
 	async screenshot(targetWsUrl, options) {
@@ -1388,6 +1673,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") {
@@ -1773,6 +2118,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',
@@ -2044,6 +2393,7 @@ var ChromeCdpBrowserController = class {
       }
 
       const results = [];
+      const crossOriginFrames = [];
       let totalFound = 0;
 
       function maybeRecordElement(root, path, el) {
@@ -2061,6 +2411,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;
 
@@ -2104,12 +2473,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);
             }
           }
 
@@ -2120,7 +2498,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: [],
@@ -2134,12 +2514,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();
+			}
 		});
 	}
 	/**
@@ -2153,22 +2552,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 = `(() => {
@@ -2423,7 +2833,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)
@@ -2444,62 +2889,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 };
 		});
 	}
 	/**
@@ -2696,6 +3148,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");
@@ -2762,7 +3272,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",
@@ -3153,6 +3664,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);
@@ -3437,6 +4010,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) };
 	}
@@ -4580,7 +5168,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) {
@@ -4592,6 +5183,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);
 	}