@agentium/browser 3.1.1 → 4.0.0

package/dist/index.cjs

@@ -1,66 +1,185 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  BrowserAgent: () => BrowserAgent,
-  BrowserProvider: () => BrowserProvider,
-  CredentialVault: () => CredentialVault
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/browser-agent.ts
-var import_core = require("@agentium/core");
-var import_zod = require("zod");
-
-// src/stealth.ts
-var REALISTIC_USER_AGENTS = [
-  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
-  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
-  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
-  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
-  "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
-  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.2 Safari/605.1.15"
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _agentium_core = require("@agentium/core");
+let zod_v3 = require("zod/v3");
+function searchUrl(query, engine = "duckduckgo") {
+	const q = encodeURIComponent(query.trim());
+	switch (engine) {
+		case "google": return `https://www.google.com/search?q=${q}`;
+		case "bing": return `https://www.bing.com/search?q=${q}`;
+		default: return `https://html.duckduckgo.com/html/?q=${q}`;
+	}
+}
+function isSearchResultsUrl(url) {
+	try {
+		const u = new URL(url);
+		const host = u.hostname.replace(/^www\./, "");
+		if (host === "duckduckgo.com" || host.endsWith(".duckduckgo.com")) return u.searchParams.has("q") || u.pathname.includes("/html");
+		if (host === "google.com" || host.endsWith(".google.com")) return u.pathname.startsWith("/search");
+		if (host === "bing.com" || host.endsWith(".bing.com")) return u.pathname.startsWith("/search");
+		return false;
+	} catch {
+		return false;
+	}
+}
+/** Bot-block / challenge pages (DDG 418, Google sorry, Cloudflare, …). */
+function isBlockedPageUrl(url) {
+	return /418\.html|\/sorry\/|captcha|challenge|cf-browser-verification/i.test(url);
+}
+function isBotChallengeText(text) {
+	return /unfortunately, bots use|select all squares containing a duck|unusual traffic from your computer|are you a robot|verify you are human|detected unusual traffic/i.test(text);
+}
+const CHROME_LABEL = /^(email us|feedback|privacy|terms|settings|facebook|twitter|reddit|about|help|sign in|log in|login|all regions|any time|more results|next|previous|images|videos|news|maps|shopping|lite|duckduckgo|menu|home|cookies|advertising|github|wikipedia|instagram|youtube)$/i;
+function isResultTitle(label) {
+	const t = label.replace(/\s+/g, " ").trim();
+	if (t.length < 16) return false;
+	if (CHROME_LABEL.test(t)) return false;
+	if (/^(https?:|javascript:|mailto:)/i.test(t)) return false;
+	return true;
+}
+function looksLikeResultList(text) {
+	const lines = text.split("\n").map((l) => l.replace(/^\d+\.\s*/, "").trim()).filter(Boolean);
+	return lines.length >= 2 && lines.filter(isResultTitle).length >= 2;
+}
+/** Longest non-chrome link labels — search result titles, not "email us". */
+function titlesFromElements(elements, max = 5) {
+	const seen = /* @__PURE__ */ new Set();
+	const labels = [];
+	for (const e of elements) {
+		if (e.tag !== "a" && e.role !== "link" && e.role !== "heading") continue;
+		const label = e.label?.replace(/\s+/g, " ").trim() ?? "";
+		if (!isResultTitle(label) || seen.has(label.toLowerCase())) continue;
+		seen.add(label.toLowerCase());
+		labels.push(label);
+	}
+	labels.sort((a, b) => b.length - a.length);
+	return labels.slice(0, max).map((t, i) => `${i + 1}. ${t}`).join("\n");
+}
+const SERP_TITLE_SELECTORS = [
+	"a.result__a",
+	"a.result-link",
+	"#links .result__a",
+	"h2 a",
+	"h3 a",
+	"a > h3"
+];
+function guessSearchQuery(task) {
+	const quoted = task.match(/["']([^"']{1,200})["']/);
+	if (quoted?.[1]) return quoted[1].trim();
+	return task.replace(/^(please\s+)?(search for|google|bing|find|look up)\s+/i, "").slice(0, 200).trim();
+}
+/**
+* Closed action list for this frame: chrome (back, scroll, done, …) plus
+* `click_N` / `type_N` from the DOM snapshot. Used by the Jev planner and
+* as documentation of what `executeAction` can run without free-form JSON.
+*/
+function buildActionSpace(elements, tabs = [], opts) {
+	const max = opts?.max ?? 40;
+	const criteria = {
+		back: "Go to the previous page",
+		screenshot: "Take a fresh screenshot next step",
+		fail: "Give up — the task cannot be completed",
+		new_tab: "Open a blank new tab"
+	};
+	if (opts?.allowWait !== false) criteria.wait = "Wait for the page to settle. Use at most once.";
+	if (opts?.allowDone !== false) criteria.done = "The task is finished — return the result titles you already found";
+	if (opts?.allowSearch !== false) criteria.search = "Open a NEW web search. Do not pick this if results are already on screen.";
+	if ((opts?.pagesBelow ?? 1) > 0) criteria.scroll_down = "Scroll down one viewport";
+	if ((opts?.pagesAbove ?? 1) > 0) criteria.scroll_up = "Scroll up one viewport";
+	const slice = elements.slice(0, max);
+	for (const e of slice) {
+		const label = e.label?.trim() || e.role || e.tag;
+		criteria[`click_${e.index}`] = `Click [${e.index}] ${e.role}: ${label}`;
+		if (e.isInput) criteria[`type_${e.index}`] = `Type into [${e.index}] ${label}`;
+	}
+	for (const tab of tabs) {
+		if (!tab.active) criteria[`switch_tab_${tab.id}`] = `Switch to tab ${tab.id} (${tab.url || "blank"})`;
+		if (tabs.length > 1) criteria[`close_tab_${tab.id}`] = `Close tab ${tab.id}`;
+	}
+	return {
+		criteria,
+		toAction(label) {
+			return labelToAction(label);
+		}
+	};
+}
+function labelToAction(label, extras) {
+	if (label === "back") return { action: "back" };
+	if (label === "scroll_down") return {
+		action: "scroll",
+		direction: "down"
+	};
+	if (label === "scroll_up") return {
+		action: "scroll",
+		direction: "up"
+	};
+	if (label === "wait") return {
+		action: "wait",
+		ms: 1500
+	};
+	if (label === "screenshot") return { action: "screenshot" };
+	if (label === "done") return {
+		action: "done",
+		result: extras?.doneResult ?? "Done"
+	};
+	if (label === "fail") return {
+		action: "fail",
+		reason: "Jev chose fail"
+	};
+	if (label === "search") return {
+		action: "search",
+		query: extras?.searchQuery ?? ""
+	};
+	if (label === "new_tab") return { action: "new_tab" };
+	if (label === "none") return void 0;
+	const click = /^click_(\d+)$/.exec(label);
+	if (click) return {
+		action: "click",
+		index: Number(click[1])
+	};
+	const type = /^type_(\d+)$/.exec(label);
+	if (type) return {
+		action: "type",
+		index: Number(type[1]),
+		text: extras?.typeText ?? ""
+	};
+	const sw = /^switch_tab_(.+)$/.exec(label);
+	if (sw) return {
+		action: "switch_tab",
+		tabId: sw[1]
+	};
+	const cl = /^close_tab_(.+)$/.exec(label);
+	if (cl) return {
+		action: "close_tab",
+		tabId: cl[1]
+	};
+}
+//#endregion
+//#region src/stealth.ts
+const REALISTIC_USER_AGENTS = [
+	"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+	"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+	"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
+	"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
+	"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+	"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.2 Safari/605.1.15"
 ];
+/** Pick a random realistic user-agent string. */
 function pickUserAgent() {
-  return REALISTIC_USER_AGENTS[Math.floor(Math.random() * REALISTIC_USER_AGENTS.length)];
+	return REALISTIC_USER_AGENTS[Math.floor(Math.random() * REALISTIC_USER_AGENTS.length)];
 }
+/**
+* JavaScript that runs inside every page to patch common bot-detection vectors.
+* Injected via Playwright's `context.addInitScript()`.
+*/
 function getStealthScript() {
-  return `
-    // \u2500\u2500 navigator.webdriver \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+	return `
+    // ── navigator.webdriver ──────────────────────────────────────────
     Object.defineProperty(navigator, 'webdriver', {
       get: () => undefined,
       configurable: true,
     });
 
-    // \u2500\u2500 navigator.plugins \u2014 appear non-empty \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    // ── navigator.plugins — appear non-empty ─────────────────────────
     Object.defineProperty(navigator, 'plugins', {
       get: () => {
         const plugins = [
@@ -74,13 +193,13 @@ function getStealthScript() {
       configurable: true,
     });
 
-    // \u2500\u2500 navigator.languages \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    // ── navigator.languages ──────────────────────────────────────────
     Object.defineProperty(navigator, 'languages', {
       get: () => ['en-US', 'en'],
       configurable: true,
     });
 
-    // \u2500\u2500 navigator.permissions.query \u2014 hide "denied" for notifications \u2500
+    // ── navigator.permissions.query — hide "denied" for notifications ─
     const originalQuery = window.navigator.permissions.query.bind(window.navigator.permissions);
     window.navigator.permissions.query = (params) => {
       if (params.name === 'notifications') {
@@ -89,7 +208,7 @@ function getStealthScript() {
       return originalQuery(params);
     };
 
-    // \u2500\u2500 chrome runtime \u2014 make it look like a real Chrome \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    // ── chrome runtime — make it look like a real Chrome ─────────────
     if (!window.chrome) {
       window.chrome = {};
     }
@@ -100,7 +219,7 @@ function getStealthScript() {
       };
     }
 
-    // \u2500\u2500 WebGL renderer \u2014 mask headless indicators \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    // ── WebGL renderer — mask headless indicators ────────────────────
     const getParameterOrig = WebGLRenderingContext.prototype.getParameter;
     WebGLRenderingContext.prototype.getParameter = function(param) {
       if (param === 37445) return 'Intel Inc.';
@@ -108,7 +227,7 @@ function getStealthScript() {
       return getParameterOrig.call(this, param);
     };
 
-    // \u2500\u2500 WebGL2 renderer \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    // ── WebGL2 renderer ──────────────────────────────────────────────
     if (typeof WebGL2RenderingContext !== 'undefined') {
       const getParam2Orig = WebGL2RenderingContext.prototype.getParameter;
       WebGL2RenderingContext.prototype.getParameter = function(param) {
@@ -118,8 +237,8 @@ function getStealthScript() {
       };
     }
 
-    // \u2500\u2500 Remove "cdc_" Playwright/ChromeDriver markers from new elements \u2500
-    // Only watches childList additions, NOT every attribute mutation \u2014
+    // ── Remove "cdc_" Playwright/ChromeDriver markers from new elements ─
+    // Only watches childList additions, NOT every attribute mutation —
     // attributes:true subtree:true is O(every DOM write) on heavy SPAs
     // like FreightOS and noticeably slows the page.
     try {
@@ -148,580 +267,582 @@ function getStealthScript() {
     //   An earlier version returned the parent window, which breaks legitimate
     //   page JS on any site that uses iframes (checkout widgets, embedded
     //   videos, A/B test scripts, analytics). The "anti-detection" value was
-    //   minimal \u2014 modern detectors don't rely on that property anyway \u2014 and
+    //   minimal — modern detectors don't rely on that property anyway — and
     //   the breakage caused pages to fail to boot, leaving font-test residue
     //   on screen.
   `;
 }
+/**
+* Build Playwright context options from a StealthConfig.
+*/
 function buildStealthContextOpts(config, viewport) {
-  const opts = {
-    viewport,
-    userAgent: config.userAgent ?? pickUserAgent(),
-    locale: config.locale ?? "en-US",
-    timezoneId: config.timezone ?? "America/New_York",
-    colorScheme: "light",
-    // Default to 1 — matches the most common real-user setup and avoids
-    // visual zoom/stretch in headed mode on non-Retina displays (the host
-    // OS would downsample a 2× rendered surface). Users on Retina-only
-    // deployments can opt back into DPR=2 for sharper screenshots.
-    deviceScaleFactor: config.deviceScaleFactor ?? 1,
-    hasTouch: false,
-    javaScriptEnabled: true,
-    ignoreHTTPSErrors: config.ignoreHTTPSErrors ?? false
-  };
-  if (config.geolocation) {
-    opts.geolocation = config.geolocation;
-    opts.permissions = ["geolocation"];
-  }
-  return opts;
+	const opts = {
+		viewport,
+		userAgent: config.userAgent ?? pickUserAgent(),
+		locale: config.locale ?? "en-US",
+		timezoneId: config.timezone ?? "America/New_York",
+		colorScheme: "light",
+		deviceScaleFactor: config.deviceScaleFactor ?? 1,
+		hasTouch: false,
+		javaScriptEnabled: true,
+		ignoreHTTPSErrors: config.ignoreHTTPSErrors ?? false
+	};
+	if (config.geolocation) {
+		opts.geolocation = config.geolocation;
+		opts.permissions = ["geolocation"];
+	}
+	return opts;
 }
+/**
+* Build Playwright launch options for stealth.
+*/
 function buildStealthLaunchArgs(config) {
-  const args = [
-    "--disable-blink-features=AutomationControlled",
-    "--disable-infobars",
-    "--disable-dev-shm-usage",
-    "--no-first-run",
-    "--no-default-browser-check"
-  ];
-  const proxy = config.proxy ? { server: config.proxy.server, username: config.proxy.username, password: config.proxy.password } : void 0;
-  return { args, proxy };
+	return {
+		args: [
+			"--disable-blink-features=AutomationControlled",
+			"--disable-infobars",
+			"--disable-dev-shm-usage",
+			"--no-first-run",
+			"--no-default-browser-check"
+		],
+		proxy: config.proxy ? {
+			server: config.proxy.server,
+			username: config.proxy.username,
+			password: config.proxy.password
+		} : void 0
+	};
 }
-
-// src/browser-provider.ts
+//#endregion
+//#region src/browser-provider.ts
+/**
+* Playwright wrapper with stealth anti-detection, human-like behavior,
+* indexed DOM element resolution, and a rich action vocabulary.
+*
+* The `BrowserProvider` is intentionally LLM-agnostic — it exposes the
+* primitives that `BrowserAgent` orchestrates via vision+DOM reasoning.
+*/
 var BrowserProvider = class {
-  browser = null;
-  context = null;
-  page = null;
-  pages = /* @__PURE__ */ new Map();
-  activeTabId = "tab-0";
-  tabCounter = 0;
-  _viewport;
-  _videoDir;
-  _humanize;
-  /**
-   * Most recent DOM snapshot (one per `extractDOM` call). Indexed actions
-   * (`clickByIndex`, `inputByIndex`, …) resolve their `index` against this.
-   */
-  _lastDom = [];
-  /** True if we connected over CDP (don't tear down the browser on close). */
-  _attached = false;
-  constructor() {
-    this._viewport = { width: 1280, height: 720 };
-  }
-  // ── Lifecycle ────────────────────────────────────────────────────────
-  async launch(opts) {
-    const pw = await import("playwright");
-    const chromium = pw.chromium;
-    this._viewport = opts?.viewport ?? { width: 1280, height: 720 };
-    if (opts?.humanize) {
-      const h = typeof opts.humanize === "object" ? opts.humanize : {};
-      this._humanize = {
-        typingDelay: h.typingDelay ?? [40, 120],
-        clickJitter: h.clickJitter ?? 3,
-        actionDelay: h.actionDelay ?? [200, 800],
-        mouseMovement: h.mouseMovement ?? true
-      };
-    }
-    if (opts?.cdpUrl) {
-      this.browser = await chromium.connectOverCDP(opts.cdpUrl);
-      this._attached = true;
-      const contexts = this.browser.contexts();
-      this.context = contexts.length > 0 ? contexts[0] : await this.browser.newContext({ viewport: this._viewport });
-      const existingPages = this.context.pages();
-      this.page = existingPages.length > 0 ? existingPages[0] : await this.context.newPage();
-      this.tabCounter = 0;
-      this.activeTabId = "tab-0";
-      this.pages.set("tab-0", this.page);
-      return;
-    }
-    const stealthEnabled = !!opts?.stealth;
-    const stealthCfg = typeof opts?.stealth === "object" ? opts.stealth : {};
-    const headless = opts?.headless ?? true;
-    const launchOpts = { headless };
-    const args = [];
-    if (stealthEnabled) {
-      const stealth = buildStealthLaunchArgs(stealthCfg);
-      args.push(...stealth.args);
-      if (stealth.proxy) launchOpts.proxy = stealth.proxy;
-    }
-    if (!headless) {
-      const CHROME_VERTICAL_CHROME_PX = 140;
-      args.push(`--window-size=${this._viewport.width},${this._viewport.height + CHROME_VERTICAL_CHROME_PX}`);
-      args.push("--window-position=0,0");
-    }
-    if (args.length) launchOpts.args = args;
-    this.browser = await chromium.launch(launchOpts);
-    let contextOpts;
-    if (stealthEnabled) {
-      contextOpts = buildStealthContextOpts(stealthCfg, this._viewport);
-    } else {
-      contextOpts = {
-        viewport: this._viewport,
-        userAgent: pickUserAgent()
-      };
-    }
-    if (opts?.storageState) {
-      contextOpts.storageState = opts.storageState;
-    }
-    if (opts?.recordVideo) {
-      const dir = typeof opts.recordVideo === "object" ? opts.recordVideo.dir : "./browser-videos";
-      contextOpts.recordVideo = { dir, size: this._viewport };
-      this._videoDir = dir;
-    }
-    this.context = await this.browser.newContext(contextOpts);
-    if (stealthEnabled && stealthCfg.patchFingerprint !== false) {
-      await this.context.addInitScript(getStealthScript());
-    }
-    this.page = await this.context.newPage();
-    this.tabCounter = 0;
-    this.activeTabId = "tab-0";
-    this.pages.set("tab-0", this.page);
-  }
-  // ── Cookie / Auth Persistence ────────────────────────────────────────
-  async saveStorageState(path) {
-    this.ensureContext();
-    await this.context.storageState({ path });
-  }
-  // ── Navigation ───────────────────────────────────────────────────────
-  async navigate(url) {
-    this.ensurePage();
-    if (!/^https?:\/\//i.test(url)) {
-      throw new Error(`Invalid URL scheme: only http:// and https:// are allowed`);
-    }
-    await this.page.goto(url, { waitUntil: "domcontentloaded", timeout: 3e4 });
-    await this.waitForStable(500);
-  }
-  async back() {
-    this.ensurePage();
-    await this.page.goBack({ waitUntil: "domcontentloaded", timeout: 15e3 });
-  }
-  // ── Screenshot ───────────────────────────────────────────────────────
-  async screenshot() {
-    this.ensurePage();
-    return await this.page.screenshot({
-      type: "png",
-      fullPage: false,
-      scale: "css"
-    });
-  }
-  /** Viewport size in CSS pixels (matches screenshot dimensions). */
-  get viewport() {
-    return this._viewport;
-  }
-  /** Most recent DOM snapshot. Each entry has a stable `index`. */
-  get lastDom() {
-    return this._lastDom;
-  }
-  // ── Coordinate-based Interaction ─────────────────────────────────────
-  async click(x, y) {
-    this.ensurePage();
-    const [cx, cy] = this.clampToViewport(x, y);
-    const [fx, fy] = this.jitter(cx, cy);
-    if (this._humanize?.mouseMovement) {
-      await this.humanMouseMove(fx, fy);
-    }
-    await this.page.mouse.click(fx, fy);
-    await this.humanPause();
-  }
-  async type(text) {
-    this.ensurePage();
-    const delay = this._humanize ? this.randInt(this._humanize.typingDelay[0], this._humanize.typingDelay[1]) : 30;
-    await this.page.keyboard.type(text, { delay });
-    await this.humanPause();
-  }
-  async clickAndType(x, y, text) {
-    const [cx, cy] = this.clampToViewport(x, y);
-    await this.click(cx, cy);
-    await this.sleep(this._humanize ? this.randInt(150, 350) : 200);
-    const [fx, fy] = this.jitter(cx, cy);
-    await this.page.mouse.click(fx, fy, { clickCount: 3 });
-    await this.sleep(this._humanize ? this.randInt(80, 200) : 100);
-    await this.type(text);
-  }
-  async pressKey(key) {
-    this.ensurePage();
-    await this.page.keyboard.press(key);
-  }
-  /**
-   * Send arbitrary keyboard keys / shortcuts. Accepts a single
-   * Playwright key spec (`"Enter"`, `"Control+l"`, `"Shift+ArrowDown"`)
-   * or a space-separated sequence (`"Tab Tab Enter"`).
-   */
-  async sendKeys(keys) {
-    this.ensurePage();
-    const tokens = keys.trim().split(/\s+/).filter(Boolean);
-    for (const token of tokens) {
-      await this.page.keyboard.press(token);
-      await this.sleep(this._humanize ? this.randInt(40, 120) : 30);
-    }
-    await this.humanPause();
-  }
-  async scroll(direction, amount) {
-    this.ensurePage();
-    const base = amount ?? 400;
-    const jittered = this._humanize ? base + this.randInt(-40, 40) : base;
-    const scrollY = direction === "down" ? jittered : -jittered;
-    if (this._humanize) {
-      const steps = this.randInt(2, 4);
-      const perStep = scrollY / steps;
-      for (let i = 0; i < steps; i++) {
-        await this.page.mouse.wheel(0, perStep);
-        await this.sleep(this.randInt(30, 80));
-      }
-    } else {
-      await this.page.mouse.wheel(0, scrollY);
-    }
-    await this.humanPause();
-  }
-  // ── Indexed Interaction (preferred path) ─────────────────────────────
-  /**
-   * Build a Playwright locator for a DOM-snapshot index. Each `extractDOM`
-   * call tags surviving elements with `data-bua-idx="<n>"`; we resolve by
-   * that attribute. Returns null if the index is unknown.
-   */
-  locatorForIndex(index) {
-    if (!this.page) return null;
-    if (!this._lastDom.find((e) => e.index === index)) return null;
-    return this.page.locator(`[data-bua-idx="${index}"]`).first();
-  }
-  /**
-   * Click an element by its DOM-snapshot index. The most reliable click
-   * path on dynamic pages — survives layout shifts and DPR oddities.
-   */
-  async clickByIndex(index, opts) {
-    this.ensurePage();
-    const loc = this.locatorForIndex(index);
-    if (!loc) return false;
-    try {
-      await loc.scrollIntoViewIfNeeded({ timeout: 1500 }).catch(() => {
-      });
-      await loc.click({ timeout: opts?.timeout ?? 5e3 });
-      await this.humanPause();
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  /**
-   * Focus an indexed input, optionally clear it, and type. Returns false
-   * if the index couldn't be resolved or the input couldn't be focused.
-   */
-  async inputByIndex(index, text, opts) {
-    this.ensurePage();
-    const loc = this.locatorForIndex(index);
-    if (!loc) return false;
-    try {
-      const timeout = opts?.timeout ?? 5e3;
-      await loc.scrollIntoViewIfNeeded({ timeout: 1500 }).catch(() => {
-      });
-      if (opts?.clear !== false) {
-        await loc.fill("", { timeout });
-      }
-      const delay = this._humanize ? this.randInt(this._humanize.typingDelay[0], this._humanize.typingDelay[1]) : 30;
-      await loc.click({ timeout });
-      await loc.pressSequentially(text, { delay });
-      if (opts?.submit) {
-        await this.page.keyboard.press("Enter");
-      }
-      await this.humanPause();
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  async uploadFileByIndex(index, path) {
-    this.ensurePage();
-    const loc = this.locatorForIndex(index);
-    if (!loc) return false;
-    try {
-      await loc.setInputFiles(path, { timeout: 5e3 });
-      await this.humanPause();
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  /** Scroll the indexed element into view (no click). */
-  async scrollIntoViewByIndex(index) {
-    this.ensurePage();
-    const loc = this.locatorForIndex(index);
-    if (!loc) return false;
-    try {
-      await loc.scrollIntoViewIfNeeded({ timeout: 3e3 });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  // ── Text-based Interaction ───────────────────────────────────────────
-  /**
-   * Deterministic, DOM-based click using Playwright's text locator.
-   *
-   * Returns `true` if a matching, visible, clickable element was found and
-   * clicked within `timeout` ms; `false` otherwise (so the caller can fall
-   * back to coordinate clicking). Substring-matches by default — e.g.
-   * `clickByText("Cheapest")` matches "Cheapest · 23-28 days · $2,550".
-   */
-  async clickByText(keyword, opts) {
-    this.ensurePage();
-    const timeout = opts?.timeout ?? 3e3;
-    try {
-      const locator = this.page.locator(`text=${keyword}`).first();
-      await locator.click({ timeout });
-      await this.humanPause();
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  /**
-   * Scroll the first occurrence of `text` into view. Returns false if no
-   * match was found within the timeout.
-   */
-  async findText(text, opts) {
-    this.ensurePage();
-    const timeout = opts?.timeout ?? 3e3;
-    try {
-      const locator = this.page.getByText(text).first();
-      await locator.scrollIntoViewIfNeeded({ timeout });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  // ── Dropdowns ────────────────────────────────────────────────────────
-  /**
-   * Read the options of a native `<select>` at the given DOM-snapshot
-   * index. Returns `[]` if the element is not a `<select>`.
-   */
-  async dropdownOptions(index) {
-    this.ensurePage();
-    const loc = this.locatorForIndex(index);
-    if (!loc) return [];
-    try {
-      return await loc.evaluate((el) => {
-        if (!el || el.tagName !== "SELECT") return [];
-        return Array.from(el.options).map((opt) => ({
-          value: opt.value,
-          label: (opt.label || opt.textContent || "").trim(),
-          selected: !!opt.selected
-        }));
-      });
-    } catch {
-      return [];
-    }
-  }
-  /**
-   * Select an option in a native `<select>` by its visible text or value.
-   * Returns false if the element isn't a `<select>` or no option matched.
-   */
-  async selectDropdown(index, text) {
-    this.ensurePage();
-    const loc = this.locatorForIndex(index);
-    if (!loc) return false;
-    try {
-      await loc.selectOption({ label: text }, { timeout: 3e3 });
-      await this.humanPause();
-      return true;
-    } catch {
-      try {
-        await loc.selectOption({ value: text }, { timeout: 3e3 });
-        await this.humanPause();
-        return true;
-      } catch {
-        return false;
-      }
-    }
-  }
-  // ── JS Evaluation ────────────────────────────────────────────────────
-  /**
-   * Run arbitrary JS in the page context. The caller is responsible for
-   * gating this behind a config flag — the BrowserAgent only routes the
-   * `evaluate` action here when `allowEvaluate: true`.
-   *
-   * The code is wrapped in `(async () => { ... })()` and the return value
-   * is coerced to a string for the model.
-   */
-  async evaluate(code) {
-    this.ensurePage();
-    try {
-      const result = await this.page.evaluate(
-        // eslint-disable-next-line @typescript-eslint/no-implied-eval
-        new Function("return (async () => { " + code + " })()")
-      );
-      if (result === void 0) return "undefined";
-      if (result === null) return "null";
-      if (typeof result === "string") return result;
-      try {
-        return JSON.stringify(result);
-      } catch {
-        return String(result);
-      }
-    } catch (e) {
-      throw new Error(`evaluate failed: ${e?.message ?? e}`);
-    }
-  }
-  // ── Page text (for `extract`) ────────────────────────────────────────
-  /**
-   * Returns a clean text representation of the visible page body, with
-   * optional link extraction. Used by the BrowserAgent's `extract` action
-   * — the text is passed to a (usually cheap) LLM with the user's query.
-   */
-  async pageText(opts) {
-    this.ensurePage();
-    const maxChars = opts?.maxChars ?? 2e4;
-    const extractLinks = !!opts?.extractLinks;
-    const raw = await this.page.evaluate((withLinks) => {
-      const doc = globalThis.document;
-      const SKIP = /* @__PURE__ */ new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "SVG"]);
-      const win = globalThis.window;
-      const lines = [];
-      function visit(node) {
-        if (!node) return;
-        if (node.nodeType === 3) {
-          const t = (node.nodeValue || "").trim();
-          if (t) lines.push(t);
-          return;
-        }
-        if (node.nodeType !== 1) return;
-        const tag = node.tagName.toUpperCase();
-        if (SKIP.has(tag)) return;
-        const style = win.getComputedStyle(node);
-        if (style && (style.visibility === "hidden" || style.display === "none")) return;
-        if (tag === "A" && withLinks) {
-          const href = node.getAttribute("href") || "";
-          const txt = (node.innerText || node.textContent || "").trim();
-          if (txt && href) {
-            lines.push(`[${txt}](${href})`);
-            return;
-          }
-        }
-        for (const child of node.childNodes) visit(child);
-      }
-      visit(doc.body);
-      return lines.join("\n");
-    }, extractLinks);
-    const collapsed = raw.replace(/\n{3,}/g, "\n\n").trim();
-    return collapsed.length > maxChars ? `${collapsed.slice(0, maxChars)}
-\u2026[truncated]` : collapsed;
-  }
-  // ── DOM Extraction (with index tagging) ──────────────────────────────
-  /**
-   * Snapshot the interactive elements visible in the viewport, tag each
-   * with a `data-bua-idx="<n>"` attribute (used by indexed actions), and
-   * return:
-   *   - `text`: a human-readable string fed to the model
-   *   - `elements`: the structured list with stable indices
-   *   - `scroll`: spatial context (pages above/below, hidden interactive count)
-   *
-   * Five properties matter for accuracy:
-   *  - **Hit-tested**: each listed coordinate / index actually reaches the
-   *    labeled element (overlays / occlusion skip the entry).
-   *  - **Visibility filtered (with parent chain)**: an element is dropped
-   *    if itself OR any ancestor is `display:none`, `visibility:hidden`,
-   *    `pointer-events:none`, or near-zero opacity.
-   *  - **Shadow DOM piercing**: traverses open shadow roots so custom
-   *    elements / web components are visible to the agent.
-   *  - **Same-origin iframes**: walks into each accessible iframe and
-   *    includes its interactive elements (offset by the iframe's screen
-   *    position so the coordinates the model sees are still viewport-
-   *    relative).
-   *  - **`cursor: pointer` fallback pass**: catches custom React widgets
-   *    that have no semantic role/href/onclick but are clickable.
-   */
-  async extractDOM(opts) {
-    this.ensurePage();
-    const max = opts?.maxElements ?? 200;
-    const mainResult = await this.page.evaluate((limit) => {
-      return globalThis.__buaExtract(limit, 0, 0, "main");
-    }, max).catch(async () => {
-      await this.installExtractorScript();
-      return await this.page.evaluate((limit) => {
-        return globalThis.__buaExtract(limit, 0, 0, "main");
-      }, max);
-    });
-    const collected = mainResult.elements;
-    const scroll = mainResult.scroll;
-    try {
-      const frames = this.page.frames();
-      for (const frame of frames) {
-        if (frame === this.page.mainFrame()) continue;
-        if (collected.length >= max) break;
-        let bbox = null;
-        try {
-          const owner = await frame.frameElement();
-          if (owner) {
-            const rect = await owner.boundingBox();
-            if (rect) bbox = { x: rect.x, y: rect.y };
-          }
-        } catch {
-          continue;
-        }
-        if (!bbox) continue;
-        let iframeRes = null;
-        try {
-          iframeRes = await frame.evaluate(
-            (args) => {
-              return globalThis.__buaExtract(args.limit, args.ox, args.oy, args.frame);
-            },
-            { limit: max - collected.length, ox: bbox.x, oy: bbox.y, frame: frame.url() || "(iframe)" }
-          );
-        } catch {
-          try {
-            await frame.evaluate(this.extractorScriptSource());
-            iframeRes = await frame.evaluate(
-              (args) => {
-                return globalThis.__buaExtract(args.limit, args.ox, args.oy, args.frame);
-              },
-              { limit: max - collected.length, ox: bbox.x, oy: bbox.y, frame: frame.url() || "(iframe)" }
-            );
-          } catch {
-          }
-        }
-        if (iframeRes?.elements?.length) {
-          const offset = collected.length;
-          for (let i = 0; i < iframeRes.elements.length; i++) {
-            const e = iframeRes.elements[i];
-            e.index = offset + i + 1;
-            collected.push(e);
-            if (collected.length >= max) break;
-          }
-        }
-      }
-    } catch {
-    }
-    this._lastDom = collected;
-    const lines = collected.map((e) => {
-      const typeSuffix = e.type ? `(${e.type})` : "";
-      const frameSuffix = e.frame && e.frame !== "main" ? ` [frame]` : "";
-      return `[${e.index}] [${e.cx},${e.cy}] ${e.role}${typeSuffix}${frameSuffix}: "${e.label}"`;
-    });
-    return { text: lines.join("\n"), elements: collected, scroll };
-  }
-  /**
-   * Install the `__buaExtract` global on the main page. Idempotent —
-   * subsequent calls are no-ops.
-   */
-  async installExtractorScript() {
-    if (!this.page) return;
-    await this.page.evaluate(this.extractorScriptSource());
-  }
-  /**
-   * The extractor source. Lives in its own method so we can also inject
-   * it into iframes that haven't yet had it loaded.
-   *
-   * This function intentionally runs entirely in the page context. It:
-   *   - traverses the regular DOM + open shadow roots (deep)
-   *   - applies a parent-chain visibility filter
-   *   - applies a `cursor:pointer` second pass for custom widgets
-   *   - hit-tests each candidate at its center to avoid overlay collisions
-   *   - returns scroll context (pages above/below, hidden counts)
-   *   - tags survivors with `data-bua-idx` for indexed actions
-   */
-  extractorScriptSource() {
-    return (
-      /* js */
-      `
+	browser = null;
+	context = null;
+	page = null;
+	pages = /* @__PURE__ */ new Map();
+	activeTabId = "tab-0";
+	tabCounter = 0;
+	_viewport;
+	_videoDir;
+	_humanize;
+	/**
+	* Most recent DOM snapshot (one per `extractDOM` call). Indexed actions
+	* (`clickByIndex`, `inputByIndex`, …) resolve their `index` against this.
+	*/
+	_lastDom = [];
+	/** True if we connected over CDP (don't tear down the browser on close). */
+	_attached = false;
+	constructor() {
+		this._viewport = {
+			width: 1280,
+			height: 720
+		};
+	}
+	async launch(opts) {
+		const chromium = (await import("playwright")).chromium;
+		this._viewport = opts?.viewport ?? {
+			width: 1280,
+			height: 720
+		};
+		if (opts?.humanize) {
+			const h = typeof opts.humanize === "object" ? opts.humanize : {};
+			this._humanize = {
+				typingDelay: h.typingDelay ?? [40, 120],
+				clickJitter: h.clickJitter ?? 3,
+				actionDelay: h.actionDelay ?? [200, 800],
+				mouseMovement: h.mouseMovement ?? true
+			};
+		}
+		if (opts?.cdpUrl) {
+			this.browser = await chromium.connectOverCDP(opts.cdpUrl);
+			this._attached = true;
+			const contexts = this.browser.contexts();
+			this.context = contexts.length > 0 ? contexts[0] : await this.browser.newContext({ viewport: this._viewport });
+			const existingPages = this.context.pages();
+			this.page = existingPages.length > 0 ? existingPages[0] : await this.context.newPage();
+			this.tabCounter = 0;
+			this.activeTabId = "tab-0";
+			this.pages.set("tab-0", this.page);
+			return;
+		}
+		const stealthEnabled = !!opts?.stealth;
+		const stealthCfg = typeof opts?.stealth === "object" ? opts.stealth : {};
+		const headless = opts?.headless ?? true;
+		const launchOpts = { headless };
+		const args = [];
+		if (stealthEnabled) {
+			const stealth = buildStealthLaunchArgs(stealthCfg);
+			args.push(...stealth.args);
+			if (stealth.proxy) launchOpts.proxy = stealth.proxy;
+		}
+		if (!headless) {
+			args.push(`--window-size=${this._viewport.width},${this._viewport.height + 140}`);
+			args.push("--window-position=0,0");
+		}
+		if (args.length) launchOpts.args = args;
+		this.browser = await chromium.launch(launchOpts);
+		let contextOpts;
+		if (stealthEnabled) contextOpts = buildStealthContextOpts(stealthCfg, this._viewport);
+		else contextOpts = {
+			viewport: this._viewport,
+			userAgent: pickUserAgent()
+		};
+		if (opts?.storageState) contextOpts.storageState = opts.storageState;
+		if (opts?.recordVideo) {
+			const dir = typeof opts.recordVideo === "object" ? opts.recordVideo.dir : "./browser-videos";
+			contextOpts.recordVideo = {
+				dir,
+				size: this._viewport
+			};
+			this._videoDir = dir;
+		}
+		this.context = await this.browser.newContext(contextOpts);
+		if (stealthEnabled && stealthCfg.patchFingerprint !== false) await this.context.addInitScript(getStealthScript());
+		this.page = await this.context.newPage();
+		this.tabCounter = 0;
+		this.activeTabId = "tab-0";
+		this.pages.set("tab-0", this.page);
+	}
+	async saveStorageState(path) {
+		this.ensureContext();
+		await this.context.storageState({ path });
+	}
+	async navigate(url) {
+		this.ensurePage();
+		if (!/^https?:\/\//i.test(url)) throw new Error(`Invalid URL scheme: only http:// and https:// are allowed`);
+		await this.page.goto(url, {
+			waitUntil: "domcontentloaded",
+			timeout: 3e4
+		});
+		await this.waitForStable(500);
+	}
+	async back() {
+		this.ensurePage();
+		await this.page.goBack({
+			waitUntil: "domcontentloaded",
+			timeout: 15e3
+		});
+	}
+	async screenshot() {
+		this.ensurePage();
+		return await this.page.screenshot({
+			type: "png",
+			fullPage: false,
+			scale: "css"
+		});
+	}
+	/** Viewport size in CSS pixels (matches screenshot dimensions). */
+	get viewport() {
+		return this._viewport;
+	}
+	/** Most recent DOM snapshot. Each entry has a stable `index`. */
+	get lastDom() {
+		return this._lastDom;
+	}
+	async click(x, y) {
+		this.ensurePage();
+		const [cx, cy] = this.clampToViewport(x, y);
+		const [fx, fy] = this.jitter(cx, cy);
+		if (this._humanize?.mouseMovement) await this.humanMouseMove(fx, fy);
+		await this.page.mouse.click(fx, fy);
+		await this.humanPause();
+	}
+	async type(text) {
+		this.ensurePage();
+		const delay = this._humanize ? this.randInt(this._humanize.typingDelay[0], this._humanize.typingDelay[1]) : 30;
+		await this.page.keyboard.type(text, { delay });
+		await this.humanPause();
+	}
+	async clickAndType(x, y, text) {
+		const [cx, cy] = this.clampToViewport(x, y);
+		await this.click(cx, cy);
+		await this.sleep(this._humanize ? this.randInt(150, 350) : 200);
+		const [fx, fy] = this.jitter(cx, cy);
+		await this.page.mouse.click(fx, fy, { clickCount: 3 });
+		await this.sleep(this._humanize ? this.randInt(80, 200) : 100);
+		await this.type(text);
+	}
+	async pressKey(key) {
+		this.ensurePage();
+		await this.page.keyboard.press(key);
+	}
+	/**
+	* Send arbitrary keyboard keys / shortcuts. Accepts a single
+	* Playwright key spec (`"Enter"`, `"Control+l"`, `"Shift+ArrowDown"`)
+	* or a space-separated sequence (`"Tab Tab Enter"`).
+	*/
+	async sendKeys(keys) {
+		this.ensurePage();
+		const tokens = keys.trim().split(/\s+/).filter(Boolean);
+		for (const token of tokens) {
+			await this.page.keyboard.press(token);
+			await this.sleep(this._humanize ? this.randInt(40, 120) : 30);
+		}
+		await this.humanPause();
+	}
+	async scroll(direction, amount) {
+		this.ensurePage();
+		const base = amount ?? 400;
+		const jittered = this._humanize ? base + this.randInt(-40, 40) : base;
+		const scrollY = direction === "down" ? jittered : -jittered;
+		if (this._humanize) {
+			const steps = this.randInt(2, 4);
+			const perStep = scrollY / steps;
+			for (let i = 0; i < steps; i++) {
+				await this.page.mouse.wheel(0, perStep);
+				await this.sleep(this.randInt(30, 80));
+			}
+		} else await this.page.mouse.wheel(0, scrollY);
+		await this.humanPause();
+	}
+	/**
+	* Build a Playwright locator for a DOM-snapshot index. Each `extractDOM`
+	* call tags surviving elements with `data-bua-idx="<n>"`; we resolve by
+	* that attribute. Returns null if the index is unknown.
+	*/
+	locatorForIndex(index) {
+		if (!this.page) return null;
+		if (!this._lastDom.find((e) => e.index === index)) return null;
+		return this.page.locator(`[data-bua-idx="${index}"]`).first();
+	}
+	/**
+	* Click an element by its DOM-snapshot index. The most reliable click
+	* path on dynamic pages — survives layout shifts and DPR oddities.
+	*/
+	async clickByIndex(index, opts) {
+		this.ensurePage();
+		const loc = this.locatorForIndex(index);
+		if (!loc) return false;
+		try {
+			await loc.scrollIntoViewIfNeeded({ timeout: 1500 }).catch(() => {});
+			await loc.click({ timeout: opts?.timeout ?? 5e3 });
+			await this.humanPause();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Focus an indexed input, optionally clear it, and type. Returns false
+	* if the index couldn't be resolved or the input couldn't be focused.
+	*/
+	async inputByIndex(index, text, opts) {
+		this.ensurePage();
+		const loc = this.locatorForIndex(index);
+		if (!loc) return false;
+		try {
+			const timeout = opts?.timeout ?? 5e3;
+			await loc.scrollIntoViewIfNeeded({ timeout: 1500 }).catch(() => {});
+			if (opts?.clear !== false) await loc.fill("", { timeout });
+			const delay = this._humanize ? this.randInt(this._humanize.typingDelay[0], this._humanize.typingDelay[1]) : 30;
+			await loc.click({ timeout });
+			await loc.pressSequentially(text, { delay });
+			if (opts?.submit) await this.page.keyboard.press("Enter");
+			await this.humanPause();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async uploadFileByIndex(index, path) {
+		this.ensurePage();
+		const loc = this.locatorForIndex(index);
+		if (!loc) return false;
+		try {
+			await loc.setInputFiles(path, { timeout: 5e3 });
+			await this.humanPause();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Scroll the indexed element into view (no click). */
+	async scrollIntoViewByIndex(index) {
+		this.ensurePage();
+		const loc = this.locatorForIndex(index);
+		if (!loc) return false;
+		try {
+			await loc.scrollIntoViewIfNeeded({ timeout: 3e3 });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Deterministic, DOM-based click using Playwright's text locator.
+	*
+	* Returns `true` if a matching, visible, clickable element was found and
+	* clicked within `timeout` ms; `false` otherwise (so the caller can fall
+	* back to coordinate clicking). Substring-matches by default — e.g.
+	* `clickByText("Cheapest")` matches "Cheapest · 23-28 days · $2,550".
+	*/
+	async clickByText(keyword, opts) {
+		this.ensurePage();
+		const timeout = opts?.timeout ?? 3e3;
+		try {
+			await this.page.locator(`text=${keyword}`).first().click({ timeout });
+			await this.humanPause();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Scroll the first occurrence of `text` into view. Returns false if no
+	* match was found within the timeout.
+	*/
+	async findText(text, opts) {
+		this.ensurePage();
+		const timeout = opts?.timeout ?? 3e3;
+		try {
+			await this.page.getByText(text).first().scrollIntoViewIfNeeded({ timeout });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Read the options of a native `<select>` at the given DOM-snapshot
+	* index. Returns `[]` if the element is not a `<select>`.
+	*/
+	async dropdownOptions(index) {
+		this.ensurePage();
+		const loc = this.locatorForIndex(index);
+		if (!loc) return [];
+		try {
+			return await loc.evaluate((el) => {
+				if (el?.tagName !== "SELECT") return [];
+				return Array.from(el.options).map((opt) => ({
+					value: opt.value,
+					label: (opt.label || opt.textContent || "").trim(),
+					selected: !!opt.selected
+				}));
+			});
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Select an option in a native `<select>` by its visible text or value.
+	* Returns false if the element isn't a `<select>` or no option matched.
+	*/
+	async selectDropdown(index, text) {
+		this.ensurePage();
+		const loc = this.locatorForIndex(index);
+		if (!loc) return false;
+		try {
+			await loc.selectOption({ label: text }, { timeout: 3e3 });
+			await this.humanPause();
+			return true;
+		} catch {
+			try {
+				await loc.selectOption({ value: text }, { timeout: 3e3 });
+				await this.humanPause();
+				return true;
+			} catch {
+				return false;
+			}
+		}
+	}
+	/**
+	* Run arbitrary JS in the page context. The caller is responsible for
+	* gating this behind a config flag — the BrowserAgent only routes the
+	* `evaluate` action here when `allowEvaluate: true`.
+	*
+	* The code is wrapped in `(async () => { ... })()` and the return value
+	* is coerced to a string for the model.
+	*/
+	async evaluate(code) {
+		this.ensurePage();
+		try {
+			const result = await this.page.evaluate(new Function(`return (async () => { ${code} })()`));
+			if (result === void 0) return "undefined";
+			if (result === null) return "null";
+			if (typeof result === "string") return result;
+			try {
+				return JSON.stringify(result);
+			} catch {
+				return String(result);
+			}
+		} catch (e) {
+			throw new Error(`evaluate failed: ${e?.message ?? e}`);
+		}
+	}
+	/**
+	* Returns a clean text representation of the visible page body, with
+	* optional link extraction. Used by the BrowserAgent's `extract` action
+	* — the text is passed to a (usually cheap) LLM with the user's query.
+	*/
+	async pageText(opts) {
+		this.ensurePage();
+		const maxChars = opts?.maxChars ?? 2e4;
+		const extractLinks = !!opts?.extractLinks;
+		const collapsed = (await this.page.evaluate((withLinks) => {
+			const doc = globalThis.document;
+			const SKIP = /* @__PURE__ */ new Set([
+				"SCRIPT",
+				"STYLE",
+				"NOSCRIPT",
+				"TEMPLATE",
+				"SVG"
+			]);
+			const win = globalThis.window;
+			const lines = [];
+			function visit(node) {
+				if (!node) return;
+				if (node.nodeType === 3) {
+					const t = (node.nodeValue || "").trim();
+					if (t) lines.push(t);
+					return;
+				}
+				if (node.nodeType !== 1) return;
+				const tag = node.tagName.toUpperCase();
+				if (SKIP.has(tag)) return;
+				const style = win.getComputedStyle(node);
+				if (style && (style.visibility === "hidden" || style.display === "none")) return;
+				if (tag === "A" && withLinks) {
+					const href = node.getAttribute("href") || "";
+					const txt = (node.innerText || node.textContent || "").trim();
+					if (txt && href) {
+						lines.push(`[${txt}](${href})`);
+						return;
+					}
+				}
+				for (const child of node.childNodes) visit(child);
+			}
+			visit(doc.body);
+			return lines.join("\n");
+		}, extractLinks)).replace(/\n{3,}/g, "\n\n").trim();
+		return collapsed.length > maxChars ? `${collapsed.slice(0, maxChars)}\n…[truncated]` : collapsed;
+	}
+	/**
+	* Snapshot the interactive elements visible in the viewport, tag each
+	* with a `data-bua-idx="<n>"` attribute (used by indexed actions), and
+	* return:
+	*   - `text`: a human-readable string fed to the model
+	*   - `elements`: the structured list with stable indices
+	*   - `scroll`: spatial context (pages above/below, hidden interactive count)
+	*
+	* Five properties matter for accuracy:
+	*  - **Hit-tested**: each listed coordinate / index actually reaches the
+	*    labeled element (overlays / occlusion skip the entry).
+	*  - **Visibility filtered (with parent chain)**: an element is dropped
+	*    if itself OR any ancestor is `display:none`, `visibility:hidden`,
+	*    `pointer-events:none`, or near-zero opacity.
+	*  - **Shadow DOM piercing**: traverses open shadow roots so custom
+	*    elements / web components are visible to the agent.
+	*  - **Same-origin iframes**: walks into each accessible iframe and
+	*    includes its interactive elements (offset by the iframe's screen
+	*    position so the coordinates the model sees are still viewport-
+	*    relative).
+	*  - **`cursor: pointer` fallback pass**: catches custom React widgets
+	*    that have no semantic role/href/onclick but are clickable.
+	*/
+	async extractDOM(opts) {
+		this.ensurePage();
+		const max = opts?.maxElements ?? 200;
+		const mainResult = await this.page.evaluate((limit) => {
+			return globalThis.__buaExtract(limit, 0, 0, "main");
+		}, max).catch(async () => {
+			await this.installExtractorScript();
+			return await this.page.evaluate((limit) => {
+				return globalThis.__buaExtract(limit, 0, 0, "main");
+			}, max);
+		});
+		const collected = mainResult.elements;
+		const scroll = mainResult.scroll;
+		try {
+			const frames = this.page.frames();
+			for (const frame of frames) {
+				if (frame === this.page.mainFrame()) continue;
+				if (collected.length >= max) break;
+				let bbox = null;
+				try {
+					const owner = await frame.frameElement();
+					if (owner) {
+						const rect = await owner.boundingBox();
+						if (rect) bbox = {
+							x: rect.x,
+							y: rect.y
+						};
+					}
+				} catch {
+					continue;
+				}
+				if (!bbox) continue;
+				let iframeRes = null;
+				try {
+					iframeRes = await frame.evaluate((args) => {
+						return globalThis.__buaExtract(args.limit, args.ox, args.oy, args.frame);
+					}, {
+						limit: max - collected.length,
+						ox: bbox.x,
+						oy: bbox.y,
+						frame: frame.url() || "(iframe)"
+					});
+				} catch {
+					try {
+						await frame.evaluate(this.extractorScriptSource());
+						iframeRes = await frame.evaluate((args) => {
+							return globalThis.__buaExtract(args.limit, args.ox, args.oy, args.frame);
+						}, {
+							limit: max - collected.length,
+							ox: bbox.x,
+							oy: bbox.y,
+							frame: frame.url() || "(iframe)"
+						});
+					} catch {}
+				}
+				if (iframeRes?.elements?.length) {
+					const offset = collected.length;
+					for (let i = 0; i < iframeRes.elements.length; i++) {
+						const e = iframeRes.elements[i];
+						e.index = offset + i + 1;
+						collected.push(e);
+						if (collected.length >= max) break;
+					}
+				}
+			}
+		} catch {}
+		this._lastDom = collected;
+		return {
+			text: collected.map((e) => {
+				const typeSuffix = e.type ? `(${e.type})` : "";
+				const frameSuffix = e.frame && e.frame !== "main" ? ` [frame]` : "";
+				return `[${e.index}] [${e.cx},${e.cy}] ${e.role}${typeSuffix}${frameSuffix}: "${e.label}"`;
+			}).join("\n"),
+			elements: collected,
+			scroll
+		};
+	}
+	/**
+	* Install the `__buaExtract` global on the main page. Idempotent —
+	* subsequent calls are no-ops.
+	*/
+	async installExtractorScript() {
+		if (!this.page) return;
+		await this.page.evaluate(this.extractorScriptSource());
+	}
+	/**
+	* The extractor source. Lives in its own method so we can also inject
+	* it into iframes that haven't yet had it loaded.
+	*
+	* This function intentionally runs entirely in the page context. It:
+	*   - traverses the regular DOM + open shadow roots (deep)
+	*   - applies a parent-chain visibility filter
+	*   - applies a `cursor:pointer` second pass for custom widgets
+	*   - hit-tests each candidate at its center to avoid overlay collisions
+	*   - returns scroll context (pages above/below, hidden counts)
+	*   - tags survivors with `data-bua-idx` for indexed actions
+	*/
+	extractorScriptSource() {
+		return `
       (function () {
         if (typeof window.__buaExtract === "function") return;
 
@@ -842,8 +963,10 @@ var BrowserProvider = class {
             var title = el.getAttribute("title") || "";
             var name = el.getAttribute("name") || "";
             var href = el.getAttribute("href") || "";
-            var value = el.value || "";
-            var label = ariaLabel || text || placeholder || title || value || name;
+            // Field contents are never labels. Password, OTP and payment values
+            // must not enter model observations or recorded DOM snapshots.
+            var isField = tag === "input" || tag === "textarea" || el.isContentEditable === true;
+            var label = ariaLabel || (isField ? "" : text) || placeholder || title || name;
             if (!label && href) label = href.slice(0, 60);
             if (!label) label = "(" + tag + (type ? (" type=" + type) : "") + ")";
 
@@ -887,1425 +1010,1638 @@ var BrowserProvider = class {
           };
         };
       })();
-    `
-    );
-  }
-  // ── Page Info ────────────────────────────────────────────────────────
-  async getPageInfo() {
-    this.ensurePage();
-    const url = this.page.url();
-    let title = "";
-    try {
-      title = await this.page.title();
-    } catch (err) {
-      console.warn("[agentium/browser] Error getting page title:", err instanceof Error ? err.message : err);
-    }
-    return { url, title, viewportSize: this._viewport };
-  }
-  async waitForStable(minWait = 300) {
-    this.ensurePage();
-    await this.sleep(minWait);
-    try {
-      await this.page.waitForLoadState("networkidle", { timeout: 5e3 });
-    } catch (err) {
-      console.warn("[agentium/browser] Error waiting for stable:", err instanceof Error ? err.message : err);
-    }
-  }
-  // ── Multi-Tab / Parallel Browsing ────────────────────────────────────
-  async newTab(url) {
-    this.ensureContext();
-    const newPage = await this.context.newPage();
-    this.tabCounter++;
-    const tabId = `tab-${this.tabCounter}`;
-    this.pages.set(tabId, newPage);
-    if (url) {
-      await newPage.goto(url, { waitUntil: "domcontentloaded", timeout: 3e4 });
-    }
-    return tabId;
-  }
-  async switchTab(tabId) {
-    const targetPage = this.pages.get(tabId);
-    if (!targetPage) throw new Error(`Tab "${tabId}" not found`);
-    this.page = targetPage;
-    this.activeTabId = tabId;
-    await this.page.bringToFront();
-  }
-  async closeTab(tabId) {
-    if (this.pages.size <= 1) throw new Error("Cannot close the last tab");
-    const targetPage = this.pages.get(tabId);
-    if (!targetPage) throw new Error(`Tab "${tabId}" not found`);
-    await targetPage.close();
-    this.pages.delete(tabId);
-    if (this.activeTabId === tabId) {
-      const firstRemaining = this.pages.entries().next().value;
-      if (firstRemaining) {
-        this.activeTabId = firstRemaining[0];
-        this.page = firstRemaining[1];
-      }
-    }
-  }
-  listTabs() {
-    const tabs = [];
-    for (const [id, pg] of this.pages) {
-      tabs.push({ id, url: pg.url(), active: id === this.activeTabId });
-    }
-    return tabs;
-  }
-  get currentTabId() {
-    return this.activeTabId;
-  }
-  // ── Video Recording ──────────────────────────────────────────────────
-  async getVideoPath(tabId) {
-    const targetPage = tabId ? this.pages.get(tabId) : this.page;
-    if (!targetPage) return null;
-    try {
-      const video = targetPage.video();
-      if (!video) return null;
-      return await video.path();
-    } catch (err) {
-      console.warn("[agentium/browser] Error getting video path:", err instanceof Error ? err.message : err);
-      return null;
-    }
-  }
-  get videoDir() {
-    return this._videoDir;
-  }
-  // ── Cleanup ──────────────────────────────────────────────────────────
-  async close() {
-    try {
-      if (this.context && !this._attached) await this.context.close();
-    } catch (err) {
-      console.warn("[agentium/browser] Error closing context:", err instanceof Error ? err.message : err);
-    }
-    try {
-      if (this.browser && !this._attached) await this.browser.close();
-      else if (this.browser && this._attached) {
-        try {
-          await this.browser.close();
-        } catch {
-        }
-      }
-    } catch (err) {
-      console.warn("[agentium/browser] Error closing browser:", err instanceof Error ? err.message : err);
-    }
-    this.page = null;
-    this.context = null;
-    this.browser = null;
-    this.pages.clear();
-    this._lastDom = [];
-  }
-  // ── Private: Humanize helpers ────────────────────────────────────────
-  /** Add small random offset to coordinates to avoid pixel-perfect bot patterns. */
-  jitter(x, y) {
-    if (!this._humanize) return [x, y];
-    const j = this._humanize.clickJitter;
-    return [x + this.randInt(-j, j), y + this.randInt(-j, j)];
-  }
-  /**
-   * Safety net: clamp coordinates returned by the vision model to the actual
-   * viewport. If a model occasionally returns image-space coordinates from a
-   * 2x screenshot (despite our `scale: "css"` fix), this prevents Playwright
-   * from clicking at e.g. (2200, 1300) and either erroring or landing on a
-   * random off-screen element.
-   */
-  clampToViewport(x, y) {
-    const cx = Math.max(0, Math.min(this._viewport.width - 1, Math.round(x)));
-    const cy = Math.max(0, Math.min(this._viewport.height - 1, Math.round(y)));
-    return [cx, cy];
-  }
-  /**
-   * Simulate human mouse movement using smoothstep interpolation.
-   */
-  async humanMouseMove(targetX, targetY) {
-    const steps = this.randInt(5, 12);
-    const startX = this._viewport.width / 2;
-    const startY = this._viewport.height / 2;
-    for (let i = 1; i <= steps; i++) {
-      const t = i / steps;
-      const ease = t * t * (3 - 2 * t);
-      const cx = startX + (targetX - startX) * ease + this.randInt(-2, 2);
-      const cy = startY + (targetY - startY) * ease + this.randInt(-2, 2);
-      await this.page.mouse.move(cx, cy);
-      await this.sleep(this.randInt(5, 20));
-    }
-    await this.page.mouse.move(targetX, targetY);
-  }
-  /** Small random pause after an interaction. */
-  async humanPause() {
-    if (!this._humanize) return;
-    const [min, max] = this._humanize.actionDelay;
-    await this.sleep(this.randInt(min, max));
-  }
-  randInt(min, max) {
-    return Math.floor(Math.random() * (max - min + 1)) + min;
-  }
-  ensurePage() {
-    if (!this.page) throw new Error("Browser not launched. Call launch() first.");
-  }
-  ensureContext() {
-    if (!this.context) throw new Error("Browser not launched. Call launch() first.");
-  }
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
+    `;
+	}
+	async getPageInfo() {
+		this.ensurePage();
+		const url = this.page.url();
+		let title = "";
+		try {
+			title = await this.page.title();
+		} catch (err) {
+			console.warn("[agentium/browser] Error getting page title:", err instanceof Error ? err.message : err);
+		}
+		return {
+			url,
+			title,
+			viewportSize: this._viewport
+		};
+	}
+	async waitForStable(minWait = 300) {
+		this.ensurePage();
+		await this.sleep(minWait);
+		try {
+			await this.page.waitForLoadState("networkidle", { timeout: 5e3 });
+		} catch (err) {
+			console.warn("[agentium/browser] Error waiting for stable:", err instanceof Error ? err.message : err);
+		}
+	}
+	async newTab(url) {
+		this.ensureContext();
+		const newPage = await this.context.newPage();
+		this.tabCounter++;
+		const tabId = `tab-${this.tabCounter}`;
+		this.pages.set(tabId, newPage);
+		if (url) await newPage.goto(url, {
+			waitUntil: "domcontentloaded",
+			timeout: 3e4
+		});
+		return tabId;
+	}
+	async switchTab(tabId) {
+		const targetPage = this.pages.get(tabId);
+		if (!targetPage) throw new Error(`Tab "${tabId}" not found`);
+		this.page = targetPage;
+		this.activeTabId = tabId;
+		await this.page.bringToFront();
+	}
+	async closeTab(tabId) {
+		if (this.pages.size <= 1) throw new Error("Cannot close the last tab");
+		const targetPage = this.pages.get(tabId);
+		if (!targetPage) throw new Error(`Tab "${tabId}" not found`);
+		await targetPage.close();
+		this.pages.delete(tabId);
+		if (this.activeTabId === tabId) {
+			const firstRemaining = this.pages.entries().next().value;
+			if (firstRemaining) {
+				this.activeTabId = firstRemaining[0];
+				this.page = firstRemaining[1];
+			}
+		}
+	}
+	async visibleText(maxChars = 2e3) {
+		this.ensurePage();
+		return this.page.evaluate((n) => (globalThis.document?.body?.innerText ?? "").slice(0, n), maxChars);
+	}
+	/**
+	* Grep visible page text. No LLM. Used by `search_page`.
+	*/
+	async searchPage(opts) {
+		this.ensurePage();
+		const pattern = opts.pattern;
+		const useRegex = !!opts.regex;
+		const caseSensitive = !!opts.caseSensitive;
+		const maxResults = Math.min(Math.max(opts.maxResults ?? 20, 1), 50);
+		const contextChars = opts.contextChars ?? 100;
+		return this.page.evaluate(({ pattern, useRegex, caseSensitive, maxResults, contextChars }) => {
+			const text = globalThis.document?.body?.innerText ?? "";
+			const src = String(pattern);
+			const flags = caseSensitive ? "g" : "gi";
+			let re;
+			try {
+				re = useRegex ? new RegExp(src, flags) : new RegExp(src.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), flags);
+			} catch {
+				return [];
+			}
+			const matches = [];
+			let m = re.exec(text);
+			while (m && matches.length < Number(maxResults)) {
+				const start = Math.max(0, m.index - Number(contextChars));
+				const end = Math.min(text.length, m.index + m[0].length + Number(contextChars));
+				matches.push({
+					match: m[0],
+					context: text.slice(start, end),
+					index: m.index
+				});
+				if (!re.global) break;
+				m = re.exec(text);
+			}
+			return matches;
+		}, {
+			pattern,
+			useRegex,
+			caseSensitive,
+			maxResults,
+			contextChars
+		});
+	}
+	/**
+	* querySelectorAll over the page. No LLM. Used by `find_elements`.
+	*/
+	async findElements(selector, opts) {
+		this.ensurePage();
+		const maxResults = Math.min(Math.max(opts?.maxResults ?? 50, 1), 80);
+		return this.page.evaluate(({ selector, maxResults }) => {
+			const doc = globalThis.document;
+			let nodes;
+			try {
+				nodes = Array.from(doc.querySelectorAll(selector)).slice(0, maxResults);
+			} catch {
+				return [];
+			}
+			return nodes.map((el) => ({
+				tag: String(el.tagName ?? "").toLowerCase(),
+				text: String(el.textContent ?? "").trim().slice(0, 200),
+				href: el.href ? String(el.href) : void 0
+			}));
+		}, {
+			selector,
+			maxResults
+		});
+	}
+	listTabs() {
+		const tabs = [];
+		for (const [id, pg] of this.pages) tabs.push({
+			id,
+			url: pg.url(),
+			active: id === this.activeTabId
+		});
+		return tabs;
+	}
+	get currentTabId() {
+		return this.activeTabId;
+	}
+	async getVideoPath(tabId) {
+		const targetPage = tabId ? this.pages.get(tabId) : this.page;
+		if (!targetPage) return null;
+		try {
+			const video = targetPage.video();
+			if (!video) return null;
+			return await video.path();
+		} catch (err) {
+			console.warn("[agentium/browser] Error getting video path:", err instanceof Error ? err.message : err);
+			return null;
+		}
+	}
+	get videoDir() {
+		return this._videoDir;
+	}
+	async close() {
+		try {
+			if (this.context && !this._attached) await this.context.close();
+		} catch (err) {
+			console.warn("[agentium/browser] Error closing context:", err instanceof Error ? err.message : err);
+		}
+		try {
+			if (this.browser && !this._attached) await this.browser.close();
+			else if (this.browser && this._attached) try {
+				await this.browser.close();
+			} catch {}
+		} catch (err) {
+			console.warn("[agentium/browser] Error closing browser:", err instanceof Error ? err.message : err);
+		}
+		this.page = null;
+		this.context = null;
+		this.browser = null;
+		this.pages.clear();
+		this._lastDom = [];
+	}
+	/** Add small random offset to coordinates to avoid pixel-perfect bot patterns. */
+	jitter(x, y) {
+		if (!this._humanize) return [x, y];
+		const j = this._humanize.clickJitter;
+		return [x + this.randInt(-j, j), y + this.randInt(-j, j)];
+	}
+	/**
+	* Safety net: clamp coordinates returned by the vision model to the actual
+	* viewport. If a model occasionally returns image-space coordinates from a
+	* 2x screenshot (despite our `scale: "css"` fix), this prevents Playwright
+	* from clicking at e.g. (2200, 1300) and either erroring or landing on a
+	* random off-screen element.
+	*/
+	clampToViewport(x, y) {
+		return [Math.max(0, Math.min(this._viewport.width - 1, Math.round(x))), Math.max(0, Math.min(this._viewport.height - 1, Math.round(y)))];
+	}
+	/**
+	* Simulate human mouse movement using smoothstep interpolation.
+	*/
+	async humanMouseMove(targetX, targetY) {
+		const steps = this.randInt(5, 12);
+		const startX = this._viewport.width / 2;
+		const startY = this._viewport.height / 2;
+		for (let i = 1; i <= steps; i++) {
+			const t = i / steps;
+			const ease = t * t * (3 - 2 * t);
+			const cx = startX + (targetX - startX) * ease + this.randInt(-2, 2);
+			const cy = startY + (targetY - startY) * ease + this.randInt(-2, 2);
+			await this.page.mouse.move(cx, cy);
+			await this.sleep(this.randInt(5, 20));
+		}
+		await this.page.mouse.move(targetX, targetY);
+	}
+	/** Small random pause after an interaction. */
+	async humanPause() {
+		if (!this._humanize) return;
+		const [min, max] = this._humanize.actionDelay;
+		await this.sleep(this.randInt(min, max));
+	}
+	randInt(min, max) {
+		return Math.floor(Math.random() * (max - min + 1)) + min;
+	}
+	ensurePage() {
+		if (!this.page) throw new Error("Browser not launched. Call launch() first.");
+	}
+	ensureContext() {
+		if (!this.context) throw new Error("Browser not launched. Call launch() first.");
+	}
+	sleep(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
 };
-
-// src/loop-detector.ts
+//#endregion
+//#region src/loop-detector.ts
 var LoopDetector = class {
-  actionWindow = [];
-  pageHistory = [];
-  actionWindowSize;
-  pageHistorySize;
-  /** Thresholds: repeat counts at which each severity fires. */
-  actionThresholds;
-  /** Thresholds: consecutive unchanged-page counts at which each fires. */
-  pageThresholds;
-  constructor(opts) {
-    this.actionWindowSize = opts?.actionWindowSize ?? 20;
-    this.pageHistorySize = opts?.pageHistorySize ?? 10;
-    this.actionThresholds = {
-      warn: opts?.actionThresholds?.warn ?? 5,
-      escalate: opts?.actionThresholds?.escalate ?? 8,
-      abort: opts?.actionThresholds?.abort ?? 12
-    };
-    this.pageThresholds = {
-      warn: opts?.pageThresholds?.warn ?? 5,
-      escalate: opts?.pageThresholds?.escalate ?? 8,
-      abort: opts?.pageThresholds?.abort ?? 12
-    };
-  }
-  /**
-   * Record an action and return advice for the runtime. `severity` of
-   * `abort` means the loop should terminate now.
-   */
-  recordAction(action) {
-    const key = normalizeAction(action);
-    this.actionWindow.push(key);
-    if (this.actionWindow.length > this.actionWindowSize) this.actionWindow.shift();
-    let count = 0;
-    for (const k of this.actionWindow) if (k === key) count++;
-    if (count >= this.actionThresholds.abort) {
-      return {
-        severity: "abort",
-        message: `Auto-stopped: the action "${key}" has been repeated ${count} times in the last ${this.actionWindow.length} steps with no apparent progress.`
-      };
-    }
-    if (count >= this.actionThresholds.escalate) {
-      return {
-        severity: "escalate",
-        message: `You have repeated essentially the same action ${count} times. The current approach is NOT working \u2014 pick a different strategy: scroll, navigate elsewhere, dismiss a popup, or use "fail" if the task truly cannot be done.`
-      };
-    }
-    if (count >= this.actionThresholds.warn) {
-      return {
-        severity: "warn",
-        message: `You've repeated this action ${count} times \u2014 if the page hasn't changed, try a different approach.`
-      };
-    }
-    return { severity: "none" };
-  }
-  /**
-   * Record a page fingerprint and return advice if the page has been
-   * stagnant. Counts consecutive identical fingerprints at the END of
-   * the history (so a single navigation resets the counter).
-   */
-  recordPage(fp) {
-    this.pageHistory.push(fp);
-    if (this.pageHistory.length > this.pageHistorySize) this.pageHistory.shift();
-    let stagnantCount = 1;
-    for (let i = this.pageHistory.length - 2; i >= 0; i--) {
-      const prev = this.pageHistory[i];
-      if (prev.url === fp.url && prev.interactiveCount === fp.interactiveCount && prev.textHash === fp.textHash) {
-        stagnantCount++;
-      } else {
-        break;
-      }
-    }
-    if (stagnantCount >= this.pageThresholds.abort) {
-      return {
-        severity: "abort",
-        message: `Auto-stopped: the page hasn't changed in ${stagnantCount} consecutive steps. Likely a blocking overlay or dead control.`
-      };
-    }
-    if (stagnantCount >= this.pageThresholds.escalate) {
-      return {
-        severity: "escalate",
-        message: `The page has not changed in ${stagnantCount} steps. Something is blocking progress \u2014 try dismissing popups, navigating elsewhere, or scrolling.`
-      };
-    }
-    if (stagnantCount >= this.pageThresholds.warn) {
-      return {
-        severity: "warn",
-        message: `Page hasn't changed in ${stagnantCount} steps \u2014 verify your action is taking effect.`
-      };
-    }
-    return { severity: "none" };
-  }
-  /** Combine two advices, returning the more severe one. */
-  static combine(a, b) {
-    const rank = { none: 0, warn: 1, escalate: 2, abort: 3 };
-    return rank[a.severity] >= rank[b.severity] ? a : b;
-  }
+	actionWindow = [];
+	pageHistory = [];
+	actionWindowSize;
+	pageHistorySize;
+	/** Thresholds: repeat counts at which each severity fires. */
+	actionThresholds;
+	/** Thresholds: consecutive unchanged-page counts at which each fires. */
+	pageThresholds;
+	constructor(opts) {
+		this.actionWindowSize = opts?.actionWindowSize ?? 20;
+		this.pageHistorySize = opts?.pageHistorySize ?? 10;
+		this.actionThresholds = {
+			warn: opts?.actionThresholds?.warn ?? 5,
+			escalate: opts?.actionThresholds?.escalate ?? 8,
+			abort: opts?.actionThresholds?.abort ?? 12
+		};
+		this.pageThresholds = {
+			warn: opts?.pageThresholds?.warn ?? 5,
+			escalate: opts?.pageThresholds?.escalate ?? 8,
+			abort: opts?.pageThresholds?.abort ?? 12
+		};
+	}
+	/**
+	* Record an action and return advice for the runtime. `severity` of
+	* `abort` means the loop should terminate now.
+	*/
+	recordAction(action) {
+		const key = normalizeAction(action);
+		this.actionWindow.push(key);
+		if (this.actionWindow.length > this.actionWindowSize) this.actionWindow.shift();
+		let count = 0;
+		for (const k of this.actionWindow) if (k === key) count++;
+		if (count >= this.actionThresholds.abort) return {
+			severity: "abort",
+			message: `Auto-stopped: the action "${key}" has been repeated ${count} times in the last ${this.actionWindow.length} steps with no apparent progress.`
+		};
+		if (count >= this.actionThresholds.escalate) return {
+			severity: "escalate",
+			message: `You have repeated essentially the same action ${count} times. The current approach is NOT working — pick a different strategy: scroll, navigate elsewhere, dismiss a popup, or use "fail" if the task truly cannot be done.`
+		};
+		if (count >= this.actionThresholds.warn) return {
+			severity: "warn",
+			message: `You've repeated this action ${count} times — if the page hasn't changed, try a different approach.`
+		};
+		return { severity: "none" };
+	}
+	/**
+	* Record a page fingerprint and return advice if the page has been
+	* stagnant. Counts consecutive identical fingerprints at the END of
+	* the history (so a single navigation resets the counter).
+	*/
+	recordPage(fp) {
+		this.pageHistory.push(fp);
+		if (this.pageHistory.length > this.pageHistorySize) this.pageHistory.shift();
+		let stagnantCount = 1;
+		for (let i = this.pageHistory.length - 2; i >= 0; i--) {
+			const prev = this.pageHistory[i];
+			if (prev.url === fp.url && prev.interactiveCount === fp.interactiveCount && prev.textHash === fp.textHash) stagnantCount++;
+			else break;
+		}
+		if (stagnantCount >= this.pageThresholds.abort) return {
+			severity: "abort",
+			message: `Auto-stopped: the page hasn't changed in ${stagnantCount} consecutive steps. Likely a blocking overlay or dead control.`
+		};
+		if (stagnantCount >= this.pageThresholds.escalate) return {
+			severity: "escalate",
+			message: `The page has not changed in ${stagnantCount} steps. Something is blocking progress — try dismissing popups, navigating elsewhere, or scrolling.`
+		};
+		if (stagnantCount >= this.pageThresholds.warn) return {
+			severity: "warn",
+			message: `Page hasn't changed in ${stagnantCount} steps — verify your action is taking effect.`
+		};
+		return { severity: "none" };
+	}
+	/** Combine two advices, returning the more severe one. */
+	static combine(a, b) {
+		const rank = {
+			none: 0,
+			warn: 1,
+			escalate: 2,
+			abort: 3
+		};
+		return rank[a.severity] >= rank[b.severity] ? a : b;
+	}
 };
+/**
+* Normalize an action for loop comparison. The goal is to canonicalize
+* tiny variations the LLM produces (e.g. different `description`s for
+* the same click) into a single key while keeping actions that are
+* fundamentally different (different `index`, `text`, `url`, …) distinct.
+*/
 function normalizeAction(action) {
-  switch (action.action) {
-    case "click":
-      if (typeof action.index === "number") return `click:${action.index}`;
-      if (typeof action.x === "number" && typeof action.y === "number") {
-        return `click:xy:${Math.round(action.x / 16)},${Math.round(action.y / 16)}`;
-      }
-      return `click:?`;
-    case "type":
-      if (typeof action.index === "number") return `type:${action.index}:${truncate(action.text, 40)}`;
-      return `type:?:${truncate(action.text, 40)}`;
-    case "scroll":
-      return `scroll:${action.direction}:${action.amount ?? "default"}${action.index != null ? `:${action.index}` : ""}`;
-    case "navigate":
-      return `navigate:${action.url}`;
-    case "back":
-      return "back";
-    case "wait":
-      return `wait:${Math.round(action.ms / 1e3)}`;
-    case "screenshot":
-      return "screenshot";
-    case "send_keys":
-      return `send_keys:${action.keys}`;
-    case "find_text":
-      return `find_text:${truncate(action.text, 40)}`;
-    case "evaluate":
-      return `evaluate:${truncate(action.code, 80)}`;
-    case "dropdown_options":
-      return `dropdown_options:${action.index}`;
-    case "select_dropdown":
-      return `select_dropdown:${action.index}:${truncate(action.text, 40)}`;
-    case "upload_file":
-      return `upload_file:${action.index}:${action.path}`;
-    case "extract":
-      return `extract:${truncate(action.query, 80)}`;
-    case "tool":
-      return `tool:${action.name}`;
-    case "done":
-    case "fail":
-      return action.action;
-  }
+	switch (action.action) {
+		case "click":
+			if (typeof action.index === "number") return `click:${action.index}`;
+			if (typeof action.x === "number" && typeof action.y === "number") return `click:xy:${Math.round(action.x / 16)},${Math.round(action.y / 16)}`;
+			return `click:?`;
+		case "type":
+			if (typeof action.index === "number") return `type:${action.index}:${truncate(action.text, 40)}`;
+			return `type:?:${truncate(action.text, 40)}`;
+		case "scroll": return `scroll:${action.direction}:${action.amount ?? "default"}${action.index != null ? `:${action.index}` : ""}`;
+		case "navigate": return `navigate:${action.url}${action.newTab ? ":new" : ""}`;
+		case "search": return `search:${truncate(action.query, 40)}:${action.engine ?? "default"}`;
+		case "new_tab": return `new_tab:${action.url ?? ""}`;
+		case "switch_tab": return `switch_tab:${action.tabId}`;
+		case "close_tab": return `close_tab:${action.tabId}`;
+		case "search_page": return `search_page:${truncate(action.pattern, 40)}`;
+		case "find_elements": return `find_elements:${truncate(action.selector, 40)}`;
+		case "back": return "back";
+		case "wait": return `wait:${Math.round(action.ms / 1e3)}`;
+		case "screenshot": return "screenshot";
+		case "send_keys": return `send_keys:${action.keys}`;
+		case "find_text": return `find_text:${truncate(action.text, 40)}`;
+		case "evaluate": return `evaluate:${truncate(action.code, 80)}`;
+		case "dropdown_options": return `dropdown_options:${action.index}`;
+		case "select_dropdown": return `select_dropdown:${action.index}:${truncate(action.text, 40)}`;
+		case "upload_file": return `upload_file:${action.index}:${action.path}`;
+		case "extract": return `extract:${truncate(action.query, 80)}`;
+		case "tool": return `tool:${action.name}`;
+		case "done":
+		case "fail": return action.action;
+	}
 }
+/**
+* Tiny non-cryptographic string hash, stable across runs. Used for the
+* DOM-text portion of `PageFingerprint`.
+*/
 function fnvHash(s) {
-  let h = 2166136261;
-  for (let i = 0; i < s.length; i++) {
-    h ^= s.charCodeAt(i);
-    h = h * 16777619 >>> 0;
-  }
-  return h;
+	let h = 2166136261;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = h * 16777619 >>> 0;
+	}
+	return h;
 }
 function truncate(s, n) {
-  if (!s) return "";
-  return s.length <= n ? s : `${s.slice(0, n)}\u2026`;
+	if (!s) return "";
+	return s.length <= n ? s : `${s.slice(0, n)}…`;
 }
-
-// src/prompts.ts
+//#endregion
+//#region src/prompts.ts
 function buildSystemPrompt(viewport, extraInstructions, credentialKeys, options) {
-  const maxActions = options?.maxActionsPerStep ?? 3;
-  const allowEvaluate = !!options?.allowEvaluate;
-  const tools = options?.tools ?? [];
-  const useVision = options?.useVision ?? "auto";
-  const useThinking = options?.useThinking ?? true;
-  if (options?.overrideSystemMessage) {
-    const lines2 = [options.overrideSystemMessage];
-    appendCredentials(lines2, credentialKeys);
-    lines2.push("", "## Response Format", responseFormatLines(maxActions, useThinking).join("\n"));
-    return lines2.join("\n");
-  }
-  const lines = [];
-  lines.push(
-    `You are a browser automation agent. Your job is to complete the user's task by interacting with a real web page.`,
-    ``,
-    `## What you receive each step`,
-    `- The current URL and page title`,
-    `- A numbered list of interactive elements visible in the viewport (the "DOM snapshot"). Each entry looks like \`[idx] [cx,cy] role(type): "label"\` where \`idx\` is a stable per-step index, \`cx,cy\` are the CSS-pixel center coordinates, and \`label\` is the visible text / aria-label / placeholder. **Use the index to act on elements** \u2014 it is the most reliable handle.`
-  );
-  if (useVision !== false) {
-    lines.push(
-      `- A PNG screenshot of the same viewport at exactly ${viewport.width}\xD7${viewport.height} pixels. Use it for visual context (layout, icons, charts) when the DOM snapshot is ambiguous.`
-    );
-  } else {
-    lines.push(`- (Vision is disabled \u2014 no screenshot. Rely entirely on the DOM snapshot and page text.)`);
-  }
-  lines.push(
-    `- A short list of your previous actions (so you don't repeat yourself).`,
-    ``,
-    `## Coordinate System`,
-    `The browser viewport is ${viewport.width}\xD7${viewport.height} CSS pixels, top-left origin. Coordinates outside that range are rejected.`,
-    ``,
-    `## Available Actions`,
-    `Respond with a JSON object \u2014 or, when several independent actions can be safely batched (e.g. filling multiple form fields), an array of up to ${maxActions} JSON objects. The runtime executes them in order and stops early if the page navigates.`,
-    ``,
-    `### click \u2014 by index (preferred)`,
-    `\`{ "action": "click", "index": <n>, "description": "<what you are clicking, ideally with the visible text in quotes>" }\``,
-    `If you cannot find a matching index (e.g. an element is partly off-screen and not in the snapshot), you may fall back to coordinates: \`{ "action": "click", "x": <n>, "y": <n>, "description": "Click on 'Cheapest' tab" }\`. The runtime will additionally try a Playwright text locator using the quoted phrase.`,
-    ``,
-    `### type \u2014 by index (preferred)`,
-    `Type into the element at \`index\`. The field is cleared first by default. Set \`"submit": true\` to press Enter after typing (e.g. submit a search).`,
-    `\`{ "action": "type", "index": <n>, "text": "<text>", "clear": true, "submit": false }\``,
-    `Fallback: \`{ "action": "type", "text": "<text>", "x": <n>, "y": <n> }\` clicks the coordinates first, then types.`,
-    ``,
-    `### scroll`,
-    `\`{ "action": "scroll", "direction": "down"|"up", "amount": 400 }\` or \`{ "action": "scroll", "index": <n> }\` to scroll a specific element into view.`,
-    ``,
-    `### find_text`,
-    `Scroll the first occurrence of a phrase into the viewport. Use this instead of repeated \`scroll\` actions when you know what you're hunting for.`,
-    `\`{ "action": "find_text", "text": "Annual report 2024" }\``,
-    ``,
-    `### send_keys`,
-    `Send arbitrary keys / shortcuts. Single key, combo (with \`+\`), or space-separated sequence.`,
-    `\`{ "action": "send_keys", "keys": "Tab Tab Enter" }\` \xB7 \`{ "action": "send_keys", "keys": "Control+l" }\` \xB7 \`{ "action": "send_keys", "keys": "Escape" }\``,
-    ``,
-    `### dropdown_options / select_dropdown`,
-    `Inspect or set a native \`<select>\` by index. **Do not click into native selects** \u2014 the OS overlay is not part of the DOM.`,
-    `\`{ "action": "dropdown_options", "index": <n> }\` returns the option list in the next observation.`,
-    `\`{ "action": "select_dropdown", "index": <n>, "text": "United States" }\` picks the matching option.`,
-    ``,
-    `### upload_file`,
-    `Set a file on an \`<input type="file">\` by index. \`path\` must be a path the runtime can read; the agent does NOT have a filesystem of its own.`,
-    `\`{ "action": "upload_file", "index": <n>, "path": "/abs/path/to/file.pdf" }\``,
-    ``,
-    `### navigate / back`,
-    `\`{ "action": "navigate", "url": "<full URL>" }\` \xB7 \`{ "action": "back" }\``,
-    ``,
-    `### wait / screenshot`,
-    `\`{ "action": "wait", "ms": <ms \u2264 10000> }\` \xB7 \`{ "action": "screenshot" }\` (request a fresh image on the next step \u2014 only useful when vision mode is "auto").`,
-    ``,
-    `### extract`,
-    `Extract structured information from the current page using a secondary LLM. Cheaper than reasoning over multiple screenshots yourself when you just need facts/text. The extracted result is returned in the next observation as \`Last extract result:\`.`,
-    `\`{ "action": "extract", "query": "List the top 5 result titles and their prices", "extractLinks": false }\``
-  );
-  if (allowEvaluate) {
-    lines.push(
-      ``,
-      `### evaluate (JS escape hatch)`,
-      `Run arbitrary JavaScript in the page context. Use this ONLY when no other action fits \u2014 e.g. shadow DOM access, complex selectors, custom widget state. The return value is stringified and returned in the next observation.`,
-      `\`{ "action": "evaluate", "code": "return document.title" }\``
-    );
-  }
-  if (tools.length > 0) {
-    lines.push(``, `### tool \u2014 invoke a custom tool`);
-    lines.push(
-      `In addition to browser actions, you have access to the following custom tools. Invoke them with \`{ "action": "tool", "name": "<tool>", "args": { ... } }\`. The result is returned in the next observation.`
-    );
-    for (const t of tools) {
-      lines.push(`- **${t.name}** \u2014 ${t.description}`);
-    }
-  }
-  lines.push(
-    ``,
-    `### done / fail`,
-    `\`{ "action": "done", "result": "<comprehensive summary of what was accomplished and any data the user asked for>" }\` \u2014 use when the task is complete.`,
-    `\`{ "action": "fail", "reason": "<why>" }\` \u2014 use when the task cannot be completed even after several attempts.`,
-    ``,
-    `## Rules`,
-    `1. ALWAYS check the DOM snapshot first. If the target element is listed, use its \`index\`. Coordinates are a fallback.`,
-    `2. For text-bearing targets, ALSO include the visible label in quotes in \`description\` \u2014 the runtime will use it as a third-tier fallback if the locator fails.`,
-    `3. Dismiss cookie banners, consent dialogs, and modal popups FIRST \u2014 they intercept clicks on elements behind them.`,
-    `4. If a previous action clearly hit the wrong thing, do NOT repeat it. Pick a different element or a different action.`,
-    `5. Batch independent actions when safe (e.g. filling 3 form fields). Don't batch when an action navigates or substantially changes the DOM.`,
-    `6. NEVER hallucinate. Only report data you can actually see in the snapshot, screenshot, or an extract result.`,
-    `7. When the task is fully complete, return \`done\` IMMEDIATELY with a thorough result \u2014 don't add extra confirmation steps.`,
-    `8. If after several attempts you cannot make progress, return \`fail\` with a clear reason.`
-  );
-  appendCredentials(lines, credentialKeys);
-  if (extraInstructions) {
-    lines.push(``, `## Additional Instructions`, extraInstructions);
-  }
-  lines.push(``, `## Response Format`, responseFormatLines(maxActions, useThinking).join("\n"));
-  return lines.join("\n");
+	const maxActions = options?.maxActionsPerStep ?? 3;
+	const allowEvaluate = !!options?.allowEvaluate;
+	const tools = options?.tools ?? [];
+	const useVision = options?.useVision ?? "auto";
+	const useThinking = options?.useThinking ?? true;
+	if (options?.overrideSystemMessage) {
+		const lines = [options.overrideSystemMessage];
+		appendCredentials(lines, credentialKeys);
+		lines.push("", "## Response Format", responseFormatLines(maxActions, useThinking).join("\n"));
+		return lines.join("\n");
+	}
+	const lines = [];
+	lines.push(`You are a browser automation agent. Your job is to complete the user's task by interacting with a real web page.`, ``, `## What you receive each step`, `- The current URL and page title`, `- A numbered list of interactive elements visible in the viewport (the "DOM snapshot"). Each entry looks like \`[idx] [cx,cy] role(type): "label"\` where \`idx\` is a stable per-step index, \`cx,cy\` are the CSS-pixel center coordinates, and \`label\` is the visible text / aria-label / placeholder. **Use the index to act on elements** — it is the most reliable handle.`);
+	if (useVision !== false) lines.push(`- A PNG screenshot of the same viewport at exactly ${viewport.width}×${viewport.height} pixels. Use it for visual context (layout, icons, charts) when the DOM snapshot is ambiguous.`);
+	else lines.push(`- (Vision is disabled — no screenshot. Rely entirely on the DOM snapshot and page text.)`);
+	lines.push(`- A short list of your previous actions (so you don't repeat yourself).`, ``, `## Coordinate System`, `The browser viewport is ${viewport.width}×${viewport.height} CSS pixels, top-left origin. Coordinates outside that range are rejected.`, ``, `## Available Actions`, `Respond with a JSON object — or, when several independent actions can be safely batched (e.g. filling multiple form fields), an array of up to ${maxActions} JSON objects. The runtime executes them in order and stops early if the page navigates.`, ``, `### click — by index (preferred)`, `\`{ "action": "click", "index": <n>, "description": "<what you are clicking, ideally with the visible text in quotes>" }\``, `If you cannot find a matching index (e.g. an element is partly off-screen and not in the snapshot), you may fall back to coordinates: \`{ "action": "click", "x": <n>, "y": <n>, "description": "Click on 'Cheapest' tab" }\`. The runtime will additionally try a Playwright text locator using the quoted phrase.`, ``, `### type — by index (preferred)`, `Type into the element at \`index\`. The field is cleared first by default. Set \`"submit": true\` to press Enter after typing (e.g. submit a search).`, `\`{ "action": "type", "index": <n>, "text": "<text>", "clear": true, "submit": false }\``, `Fallback: \`{ "action": "type", "text": "<text>", "x": <n>, "y": <n> }\` clicks the coordinates first, then types.`, ``, `### scroll`, `\`{ "action": "scroll", "direction": "down"|"up", "amount": 400 }\` or \`{ "action": "scroll", "index": <n> }\` to scroll a specific element into view.`, ``, `### find_text`, `Scroll the first occurrence of a phrase into the viewport. Use this instead of repeated \`scroll\` actions when you know what you're hunting for.`, `\`{ "action": "find_text", "text": "Annual report 2024" }\``, ``, `### send_keys`, `Send arbitrary keys / shortcuts. Single key, combo (with \`+\`), or space-separated sequence.`, `\`{ "action": "send_keys", "keys": "Tab Tab Enter" }\` · \`{ "action": "send_keys", "keys": "Control+l" }\` · \`{ "action": "send_keys", "keys": "Escape" }\``, ``, `### dropdown_options / select_dropdown`, `Inspect or set a native \`<select>\` by index. **Do not click into native selects** — the OS overlay is not part of the DOM.`, `\`{ "action": "dropdown_options", "index": <n> }\` returns the option list in the next observation.`, `\`{ "action": "select_dropdown", "index": <n>, "text": "United States" }\` picks the matching option.`, ``, `### upload_file`, `Set a file on an \`<input type="file">\` by index. \`path\` must be a path the runtime can read; the agent does NOT have a filesystem of its own.`, `\`{ "action": "upload_file", "index": <n>, "path": "/abs/path/to/file.pdf" }\``, ``, `### navigate / back / search`, `\`{ "action": "navigate", "url": "<full URL>" }\` · \`{ "action": "navigate", "url": "<full URL>", "newTab": true }\` · \`{ "action": "back" }\``, `\`{ "action": "search", "query": "<query>", "engine": "duckduckgo"|"google"|"bing" }\` opens a search-engine results page (default engine: duckduckgo).`, ``, `### tabs`, `Tab ids come from the **Open tabs** list in the observation.`, `\`{ "action": "new_tab", "url": "<optional URL>" }\` · \`{ "action": "switch_tab", "tabId": "tab-2" }\` · \`{ "action": "close_tab", "tabId": "tab-1" }\``, ``, `### search_page / find_elements`, `Zero-LLM inspect. Use these instead of \`extract\` when you just need to grep visible text or run a CSS selector.`, `\`{ "action": "search_page", "pattern": "Total", "regex": false, "caseSensitive": false }\``, `\`{ "action": "find_elements", "selector": "a.storylink" }\``, ``, `### wait / screenshot`, `\`{ "action": "wait", "ms": <ms ≤ 10000> }\` · \`{ "action": "screenshot" }\` (request a fresh image on the next step — only useful when vision mode is "auto").`, ``, `### extract`, `Extract structured information from the current page using a secondary LLM. Cheaper than reasoning over multiple screenshots yourself when you just need facts/text. The extracted result is returned in the next observation as \`Last extract result:\`.`, `\`{ "action": "extract", "query": "List the top 5 result titles and their prices", "extractLinks": false }\``);
+	if (allowEvaluate) lines.push(``, `### evaluate (JS escape hatch)`, `Run arbitrary JavaScript in the page context. Use this ONLY when no other action fits — e.g. shadow DOM access, complex selectors, custom widget state. The return value is stringified and returned in the next observation.`, `\`{ "action": "evaluate", "code": "return document.title" }\``);
+	if (tools.length > 0) {
+		lines.push(``, `### tool — invoke a custom tool`);
+		lines.push(`In addition to browser actions, you have access to the following custom tools. Invoke them with \`{ "action": "tool", "name": "<tool>", "args": { ... } }\`. The result is returned in the next observation.`);
+		for (const t of tools) lines.push(`- **${t.name}** — ${t.description}`);
+	}
+	lines.push(``, `### done / fail`, `\`{ "action": "done", "result": "<comprehensive summary of what was accomplished and any data the user asked for>" }\` — use when the task is complete.`, `\`{ "action": "fail", "reason": "<why>" }\` — use when the task cannot be completed even after several attempts.`, ``, `## Rules`, `1. ALWAYS check the DOM snapshot first. If the target element is listed, use its \`index\`. Coordinates are a fallback.`, `2. For text-bearing targets, ALSO include the visible label in quotes in \`description\` — the runtime will use it as a third-tier fallback if the locator fails.`, `3. Dismiss cookie banners, consent dialogs, and modal popups FIRST — they intercept clicks on elements behind them.`, `4. If a previous action clearly hit the wrong thing, do NOT repeat it. Pick a different element or a different action.`, `5. Batch independent actions when safe (e.g. filling 3 form fields). Don't batch when an action navigates or substantially changes the DOM.`, `6. NEVER hallucinate. Only report data you can actually see in the snapshot, screenshot, or an extract result.`, `7. When the task is fully complete, return \`done\` IMMEDIATELY with a thorough result — don't add extra confirmation steps.`, `8. If after several attempts you cannot make progress, return \`fail\` with a clear reason.`);
+	appendCredentials(lines, credentialKeys);
+	if (extraInstructions) lines.push(``, `## Additional Instructions`, extraInstructions);
+	lines.push(``, `## Response Format`, responseFormatLines(maxActions, useThinking).join("\n"));
+	return lines.join("\n");
 }
 function appendCredentials(lines, credentialKeys) {
-  if (!credentialKeys || credentialKeys.length === 0) return;
-  lines.push(
-    ``,
-    `## Secure Credentials`,
-    `The following credential placeholders are available for use in "type" actions:`,
-    ...credentialKeys.map((k) => `- \`{{${k}}}\``),
-    ``,
-    `When you need to fill in a login form or any field requiring these credentials,`,
-    `use the EXACT placeholder (e.g. \`{{email}}\`) as the "text" value in a type action.`,
-    `The system will securely replace them with real values at execution time.`,
-    `NEVER guess, invent, or ask the user for the actual credential values.`,
-    `NEVER include real credential values in "done" or "fail" results.`
-  );
+	if (!credentialKeys || credentialKeys.length === 0) return;
+	lines.push(``, `## Secure Credentials`, `The following credential placeholders are available for use in "type" actions:`, ...credentialKeys.map((k) => `- \`{{${k}}}\``), ``, `When you need to fill in a login form or any field requiring these credentials,`, `use the EXACT placeholder (e.g. \`{{email}}\`) as the "text" value in a type action.`, `The system will securely replace them with real values at execution time.`, `NEVER guess, invent, or ask the user for the actual credential values.`, `NEVER include real credential values in "done" or "fail" results.`);
 }
 function responseFormatLines(maxActions, useThinking) {
-  if (!useThinking) {
-    return [
-      `Respond with ONLY valid JSON. No markdown, no commentary.`,
-      `Either a single action object, or an array of up to ${maxActions} action objects to execute in order.`
-    ];
-  }
-  return [
-    `Respond with ONLY a single valid JSON object. No markdown, no commentary.`,
-    ``,
-    `Use this exact shape:`,
-    "```json",
-    `{`,
-    `  "thinking": "Short chain-of-thought: what do I see, what's my plan?",`,
-    `  "evaluation_previous_goal": "Did the previous action succeed? success/partial/failure + 1 line",`,
-    `  "memory": "Compact bullet list of facts to remember across steps (URLs, found data, \u2026)",`,
-    `  "next_goal": "What I want to accomplish in THIS step",`,
-    `  "action": <single action object OR array of up to ${maxActions} action objects>`,
-    `}`,
-    "```",
-    ``,
-    `On the very first step, set "evaluation_previous_goal" to "n/a \u2014 first step".`,
-    `Keep each text field to one short paragraph or a few lines. Be concrete.`,
-    `Only the "action" field is executed; the others help you self-correct over multiple steps.`
-  ];
+	if (!useThinking) return [`Respond with ONLY valid JSON. No markdown, no commentary.`, `Either a single action object, or an array of up to ${maxActions} action objects to execute in order.`];
+	return [
+		`Respond with ONLY a single valid JSON object. No markdown, no commentary.`,
+		``,
+		`Use this exact shape:`,
+		"```json",
+		`{`,
+		`  "thinking": "Short chain-of-thought: what do I see, what's my plan?",`,
+		`  "evaluation_previous_goal": "Did the previous action succeed? success/partial/failure + 1 line",`,
+		`  "memory": "Compact bullet list of facts to remember across steps (URLs, found data, …)",`,
+		`  "next_goal": "What I want to accomplish in THIS step",`,
+		`  "action": <single action object OR array of up to ${maxActions} action objects>`,
+		`}`,
+		"```",
+		``,
+		`On the very first step, set "evaluation_previous_goal" to "n/a — first step".`,
+		`Keep each text field to one short paragraph or a few lines. Be concrete.`,
+		`Only the "action" field is executed; the others help you self-correct over multiple steps.`
+	];
 }
-function buildUserMessage(task, pageUrl, pageTitle, stepIndex, actionHistory, domSnapshot, lastExtract, scroll, nudge, stepBudget) {
-  const lines = [];
-  lines.push(`**Task:** ${task}`);
-  lines.push(`**Current URL:** ${pageUrl}`);
-  if (pageTitle) lines.push(`**Page Title:** ${pageTitle}`);
-  if (stepBudget) {
-    lines.push(`**Step:** ${stepIndex + 1} of ${stepBudget.max} (${stepBudget.max - stepIndex - 1} remaining)`);
-  } else {
-    lines.push(`**Step:** ${stepIndex + 1}`);
-  }
-  if (scroll) {
-    const parts = [];
-    parts.push(`${scroll.totalInteractive} interactive elements (${scroll.hiddenInteractive} hidden)`);
-    if (scroll.pagesAbove > 0) parts.push(`${scroll.pagesAbove} page${scroll.pagesAbove === 1 ? "" : "s"} above`);
-    if (scroll.pagesBelow > 0) parts.push(`${scroll.pagesBelow} page${scroll.pagesBelow === 1 ? "" : "s"} below`);
-    if (scroll.pagesAbove === 0 && scroll.pagesBelow === 0) parts.push("fits in viewport");
-    lines.push(`**Page stats:** ${parts.join(" \xB7 ")}`);
-  }
-  if (domSnapshot !== void 0) {
-    if (domSnapshot.trim().length === 0) {
-      lines.push(``);
-      lines.push(
-        `**\u26A0 Empty page / no interactive elements detected.** The page may be blank, blocked by a captcha/anti-bot wall, mid-load, or rendered with shadow DOM in an unsupported way. Consider: \`wait\` + retry, \`navigate\` to a different URL, or \`fail\` if the site is blocking access.`
-      );
-    } else {
-      lines.push(``);
-      lines.push(`**Interactive elements (format: [idx] [cx,cy] role: "label"):**`);
-      lines.push(domSnapshot);
-    }
-  }
-  if (lastExtract) {
-    lines.push(``);
-    lines.push(`**Last extract result:**`);
-    lines.push(lastExtract);
-  }
-  if (actionHistory.length > 0) {
-    lines.push(``);
-    lines.push(`**Previous actions:**`);
-    for (const entry of actionHistory.slice(-10)) {
-      lines.push(`- ${entry}`);
-    }
-  }
-  if (nudge) {
-    lines.push(``);
-    lines.push(`**\u26A0 Runtime hint:** ${nudge}`);
-  }
-  lines.push(``);
-  lines.push(`Decide the next action(s) to complete the task.`);
-  return lines.join("\n");
+function buildUserMessage(task, pageUrl, pageTitle, stepIndex, actionHistory, domSnapshot, lastExtract, scroll, nudge, stepBudget, tabs) {
+	const lines = [];
+	lines.push(`**Task:** ${task}`);
+	lines.push(`**Current URL:** ${pageUrl}`);
+	if (pageTitle) lines.push(`**Page Title:** ${pageTitle}`);
+	if (stepBudget) lines.push(`**Step:** ${stepIndex + 1} of ${stepBudget.max} (${stepBudget.max - stepIndex - 1} remaining)`);
+	else lines.push(`**Step:** ${stepIndex + 1}`);
+	if (scroll) {
+		const parts = [];
+		parts.push(`${scroll.totalInteractive} interactive elements (${scroll.hiddenInteractive} hidden)`);
+		if (scroll.pagesAbove > 0) parts.push(`${scroll.pagesAbove} page${scroll.pagesAbove === 1 ? "" : "s"} above`);
+		if (scroll.pagesBelow > 0) parts.push(`${scroll.pagesBelow} page${scroll.pagesBelow === 1 ? "" : "s"} below`);
+		if (scroll.pagesAbove === 0 && scroll.pagesBelow === 0) parts.push("fits in viewport");
+		lines.push(`**Page stats:** ${parts.join(" · ")}`);
+	}
+	if (tabs && tabs.length > 0) {
+		lines.push(`**Open tabs:**`);
+		for (const tab of tabs) {
+			const mark = tab.active ? " (active)" : "";
+			lines.push(`- ${tab.id}${mark}: ${tab.url || "blank"}`);
+		}
+	}
+	if (domSnapshot !== void 0) {
+		if (domSnapshot.trim().length === 0) {
+			lines.push(``);
+			lines.push(`**⚠ Empty page / no interactive elements detected.** The page may be blank, blocked by a captcha/anti-bot wall, mid-load, or rendered with shadow DOM in an unsupported way. Consider: \`wait\` + retry, \`navigate\` to a different URL, or \`fail\` if the site is blocking access.`);
+		} else {
+			lines.push(``);
+			lines.push(`**Interactive elements (format: [idx] [cx,cy] role: "label"):**`);
+			lines.push(domSnapshot);
+		}
+	}
+	if (lastExtract) {
+		lines.push(``);
+		lines.push(`**Last extract result:**`);
+		lines.push(lastExtract);
+	}
+	if (actionHistory.length > 0) {
+		lines.push(``);
+		lines.push(`**Previous actions:**`);
+		for (const entry of actionHistory.slice(-10)) lines.push(`- ${entry}`);
+	}
+	if (nudge) {
+		lines.push(``);
+		lines.push(`**⚠ Runtime hint:** ${nudge}`);
+	}
+	lines.push(``);
+	lines.push(`Decide the next action(s) to complete the task.`);
+	return lines.join("\n");
 }
 function summarizeAction(action) {
-  switch (action.action) {
-    case "click":
-      if (typeof action.index === "number") return `Clicked [${action.index}]: ${action.description ?? ""}`.trim();
-      return `Clicked at (${action.x}, ${action.y}): ${action.description ?? ""}`.trim();
-    case "type":
-      if (typeof action.index === "number") return `Typed into [${action.index}]: "${action.text}"`;
-      return action.x != null ? `Clicked (${action.x}, ${action.y}) and typed "${action.text}"` : `Typed "${action.text}"`;
-    case "scroll":
-      if (typeof action.index === "number") return `Scrolled [${action.index}] into view`;
-      return `Scrolled ${action.direction}${action.amount ? ` ${action.amount}px` : ""}`;
-    case "navigate":
-      return `Navigated to ${action.url}`;
-    case "back":
-      return `Went back to previous page`;
-    case "wait":
-      return `Waited ${action.ms}ms`;
-    case "screenshot":
-      return `Requested a fresh screenshot`;
-    case "send_keys":
-      return `Sent keys: ${action.keys}`;
-    case "find_text":
-      return `Scrolled to text: "${action.text}"`;
-    case "evaluate":
-      return `Evaluated JS`;
-    case "dropdown_options":
-      return `Read dropdown options at [${action.index}]`;
-    case "select_dropdown":
-      return `Selected "${action.text}" in dropdown [${action.index}]`;
-    case "upload_file":
-      return `Uploaded file to [${action.index}]: ${action.path}`;
-    case "extract":
-      return `Extracted: "${action.query}"`;
-    case "tool":
-      return `Called tool "${action.name}"`;
-    case "done":
-      return `Done: ${action.result}`;
-    case "fail":
-      return `Failed: ${action.reason}`;
-    default:
-      return JSON.stringify(action);
-  }
+	switch (action.action) {
+		case "click":
+			if (typeof action.index === "number") return `Clicked [${action.index}]: ${action.description ?? ""}`.trim();
+			return `Clicked at (${action.x}, ${action.y}): ${action.description ?? ""}`.trim();
+		case "type":
+			if (typeof action.index === "number") return `Typed into [${action.index}]: "${action.text}"`;
+			return action.x != null ? `Clicked (${action.x}, ${action.y}) and typed "${action.text}"` : `Typed "${action.text}"`;
+		case "scroll":
+			if (typeof action.index === "number") return `Scrolled [${action.index}] into view`;
+			return `Scrolled ${action.direction}${action.amount ? ` ${action.amount}px` : ""}`;
+		case "navigate": return action.newTab ? `Opened ${action.url} in a new tab` : `Navigated to ${action.url}`;
+		case "search": return `Searched ${action.engine ?? "web"} for "${action.query}"`;
+		case "new_tab": return action.url ? `Opened new tab: ${action.url}` : `Opened new tab`;
+		case "switch_tab": return `Switched to ${action.tabId}`;
+		case "close_tab": return `Closed ${action.tabId}`;
+		case "search_page": return `Searched page for "${action.pattern}"`;
+		case "find_elements": return `Found elements: ${action.selector}`;
+		case "back": return `Went back to previous page`;
+		case "wait": return `Waited ${action.ms}ms`;
+		case "screenshot": return `Requested a fresh screenshot`;
+		case "send_keys": return `Sent keys: ${action.keys}`;
+		case "find_text": return `Scrolled to text: "${action.text}"`;
+		case "evaluate": return `Evaluated JS`;
+		case "dropdown_options": return `Read dropdown options at [${action.index}]`;
+		case "select_dropdown": return `Selected "${action.text}" in dropdown [${action.index}]`;
+		case "upload_file": return `Uploaded file to [${action.index}]: ${action.path}`;
+		case "extract": return `Extracted: "${action.query}"`;
+		case "tool": return `Called tool "${action.name}"`;
+		case "done": return `Done: ${action.result}`;
+		case "fail": return `Failed: ${action.reason}`;
+		default: return JSON.stringify(action);
+	}
 }
-
-// src/browser-agent.ts
+//#endregion
+//#region src/browser-agent.ts
 var BrowserAgent = class {
-  name;
-  eventBus;
-  model;
-  pageExtractionLLM;
-  fallbackModel;
-  useThinking;
-  historyWindow;
-  instructions;
-  extendSystemMessage;
-  overrideSystemMessage;
-  maxSteps;
-  maxFailures;
-  maxActionsPerStep;
-  initialActions;
-  useVision;
-  directlyOpenUrl;
-  headless;
-  viewport;
-  defaultStartUrl;
-  waitAfterAction;
-  maxRepeats;
-  useDOM;
-  allowEvaluate;
-  allowedDomains;
-  prohibitedDomains;
-  storageState;
-  cdpUrl;
-  recordVideo;
-  credentials;
-  stealth;
-  humanize;
-  tools;
-  costTracker;
-  memoryManager = null;
-  logger;
-  /** Access the MemoryManager (if memory is configured). */
-  get memory() {
-    return this.memoryManager;
-  }
-  constructor(config) {
-    this.name = config.name;
-    this.model = config.model;
-    this.pageExtractionLLM = config.pageExtractionLLM ?? null;
-    this.fallbackModel = config.fallbackModel ?? null;
-    this.useThinking = config.useThinking ?? true;
-    this.historyWindow = Math.max(0, config.historyWindow ?? 6);
-    this.instructions = config.instructions;
-    this.extendSystemMessage = config.extendSystemMessage;
-    this.overrideSystemMessage = config.overrideSystemMessage;
-    this.maxSteps = config.maxSteps ?? 30;
-    this.maxFailures = config.maxFailures ?? 3;
-    this.maxActionsPerStep = Math.max(1, config.maxActionsPerStep ?? 3);
-    this.initialActions = config.initialActions ?? [];
-    this.useVision = config.useVision ?? "auto";
-    this.directlyOpenUrl = config.directlyOpenUrl ?? true;
-    this.headless = config.headless ?? true;
-    this.viewport = config.viewport ?? { width: 1280, height: 720 };
-    this.defaultStartUrl = config.startUrl;
-    this.waitAfterAction = config.waitAfterAction ?? 1500;
-    this.maxRepeats = config.maxRepeats ?? 3;
-    this.useDOM = config.useDOM ?? true;
-    this.allowEvaluate = config.allowEvaluate ?? false;
-    this.allowedDomains = config.allowedDomains;
-    this.prohibitedDomains = config.prohibitedDomains;
-    this.storageState = config.storageState;
-    this.cdpUrl = config.cdpUrl;
-    this.recordVideo = config.recordVideo;
-    this.credentials = config.credentials;
-    this.stealth = config.stealth;
-    this.humanize = config.humanize;
-    this.tools = config.tools ?? [];
-    this.costTracker = config.costTracker ?? null;
-    this.eventBus = config.eventBus ?? new import_core.EventBus();
-    this.logger = new import_core.Logger({
-      prefix: `BrowserAgent:${config.name}`,
-      level: config.logLevel ?? "silent"
-    });
-    if (config.memory) {
-      this.memoryManager = new import_core.MemoryManager(config.memory);
-    }
-  }
-  async run(task, opts) {
-    const startTime = Date.now();
-    const maxSteps = opts?.maxSteps ?? this.maxSteps;
-    const sessionId = opts?.sessionId ?? `browser_${Date.now()}`;
-    const userId = opts?.userId;
-    const browser = new BrowserProvider();
-    const steps = [];
-    const actionHistory = [];
-    const extractedContent = [];
-    let lastExtractResult;
-    let consecutiveFailures = 0;
-    let lastActionWasScreenshot = false;
-    const loop = new LoopDetector();
-    const historyTurns = [];
-    const baseExtra = [this.instructions, this.extendSystemMessage].filter(Boolean).join("\n\n");
-    let extraInstructions = baseExtra;
-    if (this.memoryManager) {
-      await this.memoryManager.ensureReady();
-      const memoryContext = await this.memoryManager.buildContext(sessionId, userId, task, this.name);
-      if (memoryContext) {
-        extraInstructions = extraInstructions ? `${extraInstructions}
-
-${memoryContext}` : memoryContext;
-      }
-    }
-    const credentialKeys = this.credentials?.keys();
-    const systemPrompt = buildSystemPrompt(this.viewport, extraInstructions || void 0, credentialKeys, {
-      overrideSystemMessage: this.overrideSystemMessage,
-      maxActionsPerStep: this.maxActionsPerStep,
-      allowEvaluate: this.allowEvaluate,
-      tools: this.tools,
-      useVision: this.useVision,
-      useDOM: this.useDOM,
-      useThinking: this.useThinking
-    });
-    try {
-      this.logger.info("Launching browser", {
-        headless: this.headless,
-        viewport: this.viewport,
-        useDOM: this.useDOM,
-        useVision: this.useVision,
-        useThinking: this.useThinking,
-        cdpUrl: this.cdpUrl ?? void 0,
-        recordVideo: !!this.recordVideo,
-        stealth: !!this.stealth,
-        humanize: !!this.humanize
-      });
-      await browser.launch({
-        headless: this.headless,
-        viewport: this.viewport,
-        storageState: this.storageState,
-        recordVideo: this.recordVideo,
-        stealth: this.stealth,
-        humanize: this.humanize,
-        cdpUrl: this.cdpUrl
-      });
-      const startUrl = opts?.startUrl ?? this.defaultStartUrl ?? this.detectUrlInTask(task);
-      if (startUrl) {
-        this.logger.info("Navigating to start URL", { url: startUrl });
-        this.assertDomainAllowed(startUrl);
-        await browser.navigate(startUrl);
-        await this.navigationHealthCheck(browser, startUrl);
-      }
-      for (const ia of this.initialActions) {
-        try {
-          await this.executeAction(browser, ia, actionHistory, extractedContent);
-        } catch (e) {
-          this.logger.warn("initialAction failed", { action: ia, error: e?.message });
-        }
-        await this.sleep(this.waitAfterAction);
-      }
-      for (let step = 0; step < maxSteps; step++) {
-        const pageInfo = await browser.getPageInfo();
-        let domSnapshot;
-        let scrollCtx;
-        if (this.useDOM) {
-          const dom = await browser.extractDOM();
-          domSnapshot = dom.text;
-          scrollCtx = dom.scroll;
-        }
-        const pageAdvice = loop.recordPage({
-          url: pageInfo.url,
-          interactiveCount: scrollCtx?.totalInteractive ?? 0,
-          textHash: fnvHash(domSnapshot ?? "")
-        });
-        if (pageAdvice.severity === "abort") {
-          return await this.finalize(browser, steps, startTime, opts, extractedContent, {
-            result: pageAdvice.message ?? "Auto-stopped: page is stagnant.",
-            success: false
-          });
-        }
-        const wantVision = this.shouldCaptureVision(step, lastActionWasScreenshot);
-        const screenshot = wantVision ? await browser.screenshot() : Buffer.alloc(0);
-        if (wantVision) this.eventBus.emit("browser.screenshot", { data: screenshot });
-        const isLastStep = step === maxSteps - 1;
-        const nudgeParts = [];
-        if (pageAdvice.severity !== "none" && pageAdvice.message) nudgeParts.push(pageAdvice.message);
-        if (isLastStep) {
-          nudgeParts.push(
-            "This is your FINAL step. Return a `done` action right now summarizing whatever you have, even if partial."
-          );
-        }
-        const nudge = nudgeParts.length > 0 ? nudgeParts.join(" ") : void 0;
-        const userText = buildUserMessage(
-          task,
-          pageInfo.url,
-          pageInfo.title,
-          step,
-          actionHistory,
-          domSnapshot,
-          lastExtractResult,
-          scrollCtx,
-          nudge,
-          { current: step, max: maxSteps }
-        );
-        const messages = this.buildMessages(systemPrompt, historyTurns, userText, wantVision ? screenshot : null);
-        this.logger.debug("Calling model", { step, url: pageInfo.url, vision: wantVision });
-        const { response, modelUsed } = await this.callModelWithFallback(messages, opts?.apiKey);
-        if (!response) {
-          consecutiveFailures++;
-          actionHistory.push(`(model call failed \u2014 retrying, ${consecutiveFailures}/${this.maxFailures})`);
-          if (consecutiveFailures > this.maxFailures) {
-            return await this.forceDone(browser, steps, startTime, opts, extractedContent, actionHistory, "model");
-          }
-          continue;
-        }
-        if (this.costTracker && response.usage) {
-          this.costTracker.track({
-            runId: sessionId,
-            agentName: this.name,
-            modelId: modelUsed.modelId,
-            usage: response.usage,
-            sessionId,
-            userId
-          });
-        }
-        const raw = typeof response.message.content === "string" ? response.message.content : "";
-        const envelope = this.parseEnvelope(raw);
-        if (!envelope) {
-          consecutiveFailures++;
-          this.logger.warn("Failed to parse model response", { raw: raw.slice(0, 200), consecutiveFailures });
-          if (consecutiveFailures > this.maxFailures) {
-            return await this.forceDone(browser, steps, startTime, opts, extractedContent, actionHistory, "parse");
-          }
-          actionHistory.push("(invalid JSON response \u2014 retrying)");
-          continue;
-        }
-        consecutiveFailures = 0;
-        historyTurns.push({ userText, hasScreenshot: wantVision, envelope });
-        if (this.historyWindow > 0 && historyTurns.length > this.historyWindow) {
-          historyTurns.splice(0, historyTurns.length - this.historyWindow);
-        }
-        const actions = (Array.isArray(envelope.action) ? envelope.action : [envelope.action]).slice(
-          0,
-          this.maxActionsPerStep
-        );
-        let didTerminate = null;
-        let didNavigate = false;
-        lastActionWasScreenshot = false;
-        for (let ai = 0; ai < actions.length; ai++) {
-          const action = actions[ai];
-          let summary = summarizeAction(action);
-          if (this.credentials) summary = this.credentials.mask(summary);
-          const advice = loop.recordAction(action);
-          if (advice.severity === "abort" && action.action !== "done" && action.action !== "fail") {
-            this.logger.warn("Loop detector aborting run", { advice });
-            actionHistory.push(`\u26A0 ${advice.message ?? "loop detected \u2014 auto-stopping"}`);
-            didTerminate = {
-              result: advice.message ?? "Stuck in a loop \u2014 auto-stopped.",
-              success: false
-            };
-            break;
-          }
-          actionHistory.push(summary);
-          this.logger.info(`Step ${step + 1}.${ai + 1}: ${summary}`);
-          this.eventBus.emit("browser.action", { action });
-          if (action.action === "done") {
-            const result = this.credentials ? this.credentials.mask(action.result) : action.result;
-            didTerminate = { result, success: true };
-            break;
-          }
-          if (action.action === "fail") {
-            const result = this.credentials ? this.credentials.mask(action.reason) : action.reason;
-            didTerminate = { result, success: false };
-            break;
-          }
-          let stepOk = true;
-          let stepOutput;
-          try {
-            const exec = await this.executeAction(browser, action, actionHistory, extractedContent);
-            stepOutput = exec?.output;
-            if (exec?.didNavigate) {
-              didNavigate = true;
-              await this.navigationHealthCheck(browser, pageInfo.url);
-            }
-            if (action.action === "extract" && exec?.output) lastExtractResult = exec.output;
-            if (action.action === "screenshot") lastActionWasScreenshot = true;
-          } catch (e) {
-            stepOk = false;
-            consecutiveFailures++;
-            this.logger.warn("Action failed", { action: action.action, error: e?.message, consecutiveFailures });
-            actionHistory.push(`(error: ${e?.message ?? "unknown"})`);
-            if (consecutiveFailures > this.maxFailures) {
-              didTerminate = {
-                result: `Action ${action.action} failed ${consecutiveFailures} times. Last error: ${e?.message}`,
-                success: false
-              };
-              break;
-            }
-          }
-          steps.push({
-            index: steps.length,
-            action,
-            screenshot,
-            pageUrl: pageInfo.url,
-            pageTitle: pageInfo.title,
-            timestamp: /* @__PURE__ */ new Date(),
-            dom: domSnapshot,
-            output: stepOutput,
-            ok: stepOk,
-            thinking: envelope.thinking,
-            evaluationPreviousGoal: envelope.evaluationPreviousGoal,
-            memory: envelope.memory,
-            nextGoal: envelope.nextGoal
-          });
-          this.eventBus.emit("browser.step", {
-            index: steps.length - 1,
-            action,
-            pageUrl: pageInfo.url,
-            screenshot
-          });
-          await this.sleep(this.waitAfterAction);
-          if (didNavigate) break;
-        }
-        if (didTerminate) {
-          return await this.finalize(browser, steps, startTime, opts, extractedContent, didTerminate);
-        }
-      }
-      this.logger.warn("Max steps reached without explicit done", { maxSteps });
-      return await this.forceDone(browser, steps, startTime, opts, extractedContent, actionHistory, "max_steps");
-    } catch (error) {
-      this.logger.error("Browser agent error", { error: error.message });
-      this.eventBus.emit("browser.error", { error });
-      await browser.close();
-      return {
-        result: `Error: ${error.message}`,
-        success: false,
-        steps,
-        finalUrl: "",
-        finalScreenshot: Buffer.alloc(0),
-        durationMs: Date.now() - startTime,
-        extractedContent
-      };
-    }
-  }
-  /**
-   * Returns a ToolDef that lets a regular Agent delegate browser tasks
-   * to this BrowserAgent.
-   */
-  asTool(config) {
-    return {
-      name: config?.name ?? "browse_web",
-      description: config?.description ?? "Open a browser and autonomously complete a task on a website. Provide a clear task description and optionally a starting URL.",
-      parameters: import_zod.z.object({
-        task: import_zod.z.string().describe("What to do in the browser (e.g., 'Search for X and return the top 3 results')"),
-        startUrl: import_zod.z.string().optional().describe("URL to start at (e.g., 'https://www.google.com')")
-      }),
-      execute: async (args) => {
-        const result = await this.run(args.task, { startUrl: args.startUrl });
-        return result.result;
-      }
-    };
-  }
-  // ── Private helpers ──────────────────────────────────────────────────
-  shouldCaptureVision(step, lastActionWasScreenshot) {
-    if (this.useVision === false) return false;
-    if (this.useVision === true) return true;
-    if (step === 0) return true;
-    if (!this.useDOM) return true;
-    return lastActionWasScreenshot;
-  }
-  detectUrlInTask(task) {
-    if (!this.directlyOpenUrl) return void 0;
-    const match = task.match(/https?:\/\/[^\s)<>"']+/);
-    return match ? match[0] : void 0;
-  }
-  assertDomainAllowed(url) {
-    if (!this.allowedDomains?.length && !this.prohibitedDomains?.length) return;
-    let host;
-    try {
-      host = new URL(url).hostname.toLowerCase();
-    } catch {
-      throw new Error(`Cannot parse URL for domain check: ${url}`);
-    }
-    if (this.allowedDomains?.length && !this.allowedDomains.some((p) => matchDomain(host, p))) {
-      throw new Error(`Navigation blocked: ${host} is not in allowedDomains`);
-    }
-    if (this.prohibitedDomains?.length && this.prohibitedDomains.some((p) => matchDomain(host, p))) {
-      throw new Error(`Navigation blocked: ${host} is in prohibitedDomains`);
-    }
-  }
-  /**
-   * Build the message array sent to the model: system prompt + a compact
-   * summary of older turns (if any) + the most recent `historyWindow`
-   * turns verbatim + the current step's user message.
-   *
-   * Inspired by browser-use's history compaction. Keeps tokens bounded
-   * while giving the model meaningful context about what it already
-   * tried.
-   */
-  buildMessages(systemPrompt, historyTurns, currentUserText, currentScreenshot) {
-    const msgs = [{ role: "system", content: systemPrompt }];
-    if (this.historyWindow > 0 && historyTurns.length > 0) {
-      for (const turn of historyTurns) {
-        const env = turn.envelope;
-        const replay = [];
-        if (env.thinking) replay.push(`thinking: ${env.thinking}`);
-        if (env.evaluationPreviousGoal) replay.push(`evaluation: ${env.evaluationPreviousGoal}`);
-        if (env.memory) replay.push(`memory: ${env.memory}`);
-        if (env.nextGoal) replay.push(`next_goal: ${env.nextGoal}`);
-        replay.push(`action: ${JSON.stringify(env.action)}`);
-        msgs.push({ role: "assistant", content: replay.join("\n") });
-      }
-    }
-    const content = [];
-    if (currentScreenshot && currentScreenshot.length > 0) {
-      content.push({
-        type: "image",
-        data: currentScreenshot.toString("base64"),
-        mimeType: "image/png"
-      });
-    }
-    content.push({ type: "text", text: currentUserText });
-    msgs.push({ role: "user", content });
-    return msgs;
-  }
-  /**
-   * Call the primary model, retrying once with `fallbackModel` on
-   * transient errors (5xx, 429, network). Returns the response or
-   * `null` if both models failed.
-   */
-  async callModelWithFallback(messages, apiKey) {
-    const reqOpts = { temperature: 0.1, maxTokens: 1024, apiKey, responseFormat: "json" };
-    try {
-      const r = await this.model.generate(messages, reqOpts);
-      return { response: r, modelUsed: this.model };
-    } catch (e) {
-      if (this.fallbackModel && this.isTransientError(e)) {
-        this.logger.warn("Primary model failed; trying fallbackModel", {
-          error: e?.message,
-          primary: this.model.modelId,
-          fallback: this.fallbackModel.modelId
-        });
-        try {
-          const r = await this.fallbackModel.generate(messages, reqOpts);
-          return { response: r, modelUsed: this.fallbackModel };
-        } catch (e2) {
-          this.logger.warn("Fallback model also failed", { error: e2?.message });
-          return { response: null, modelUsed: this.model };
-        }
-      }
-      this.logger.warn("Model call failed (no fallback configured)", { error: e?.message });
-      return { response: null, modelUsed: this.model };
-    }
-  }
-  isTransientError(e) {
-    const msg = String(e?.message ?? e).toLowerCase();
-    if (msg.includes("rate limit") || msg.includes("429")) return true;
-    if (msg.includes("timeout") || msg.includes("etimedout")) return true;
-    if (msg.includes("econnreset") || msg.includes("network")) return true;
-    if (/\b5\d\d\b/.test(msg)) return true;
-    if (msg.includes("401") || msg.includes("402") || msg.includes("auth")) return true;
-    return false;
-  }
-  /**
-   * Parse the model's raw response into an `AgentOutput`. Tolerant to
-   * three shapes:
-   *  - Full envelope: { thinking, evaluation_previous_goal, action, ... }
-   *  - Raw action object (legacy / `useThinking: false`)
-   *  - Raw action array
-   *
-   * Also strips ```json fences the model occasionally adds.
-   */
-  parseEnvelope(raw) {
-    if (!raw) return null;
-    let s = raw.trim();
-    const fence = s.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/);
-    if (fence) s = fence[1].trim();
-    let json;
-    try {
-      json = JSON.parse(s);
-    } catch {
-      const m = s.match(/[[{][\s\S]*[\]}]/);
-      if (!m) return null;
-      try {
-        json = JSON.parse(m[0]);
-      } catch {
-        return null;
-      }
-    }
-    if (Array.isArray(json)) return { action: json };
-    if (json && typeof json === "object" && typeof json.action === "string") {
-      return { action: json };
-    }
-    if (json && typeof json === "object" && "action" in json) {
-      const out = { action: json.action };
-      out.thinking = json.thinking ?? json.reasoning ?? void 0;
-      out.evaluationPreviousGoal = json.evaluationPreviousGoal ?? json.evaluation_previous_goal ?? void 0;
-      out.memory = json.memory ?? void 0;
-      out.nextGoal = json.nextGoal ?? json.next_goal ?? void 0;
-      return out;
-    }
-    return null;
-  }
-  /**
-   * Quick post-navigation health check. If the page came back blank
-   * (no body text and no interactive elements), reload once and wait
-   * for stable. This catches the "FreightOS half-loaded font test" class
-   * of failure before the LLM ever sees it.
-   */
-  async navigationHealthCheck(browser, url) {
-    try {
-      const ok = await browser.pageText({ maxChars: 200 }).catch(() => "");
-      if (ok && ok.trim().length > 5) return;
-      this.logger.warn("Navigation produced an empty page; reloading once", { url });
-      await this.sleep(800);
-      try {
-        await browser.navigate(url);
-      } catch {
-      }
-    } catch {
-    }
-  }
-  /**
-   * Force-finalize the run with whatever partial data the agent has.
-   * Called when:
-   *   - `maxSteps` is exhausted without an explicit `done`,
-   *   - `maxFailures` is exceeded,
-   *   - the model can't produce parseable JSON enough times to make
-   *     forward progress.
-   * The result is composed from `extractedContent` + the last few
-   * action summaries so the caller gets something useful instead of
-   * just a one-line error.
-   */
-  async forceDone(browser, steps, startTime, opts, extractedContent, actionHistory, reason) {
-    const reasonLine = reason === "model" ? "Model call failed too many consecutive times." : reason === "parse" ? "Model produced invalid JSON too many times." : "Max step budget exhausted before an explicit `done`.";
-    const tail = actionHistory.slice(-5).join(" \u2192 ");
-    const extracts = extractedContent.length > 0 ? `
-
-Extracts so far:
-${extractedContent.join("\n---\n")}` : "";
-    const result = `${reasonLine}
-Last actions: ${tail || "(none)"}${extracts}`;
-    return await this.finalize(browser, steps, startTime, opts, extractedContent, {
-      result,
-      success: false
-    });
-  }
-  async finalize(browser, steps, startTime, opts, extractedContent, outcome) {
-    let finalScreenshot;
-    let finalInfo;
-    try {
-      finalScreenshot = await browser.screenshot();
-      finalInfo = await browser.getPageInfo();
-    } catch {
-      finalScreenshot = Buffer.alloc(0);
-      finalInfo = { url: "", title: "" };
-    }
-    if (opts?.saveStorageState) {
-      try {
-        await browser.saveStorageState(opts.saveStorageState);
-        this.logger.info("Storage state saved", { path: opts.saveStorageState });
-      } catch (e) {
-        this.logger.warn("Failed to save storage state", { error: e.message });
-      }
-    }
-    let videoPath;
-    if (this.recordVideo) {
-      videoPath = await browser.getVideoPath() ?? void 0;
-    }
-    await browser.close();
-    const output = {
-      result: outcome.result,
-      success: outcome.success,
-      steps,
-      finalUrl: finalInfo.url,
-      finalScreenshot,
-      durationMs: Date.now() - startTime,
-      videoPath,
-      extractedContent
-    };
-    if (this.memoryManager) {
-      const sessionId = opts?.sessionId ?? `browser_${startTime}`;
-      const userId = opts?.userId;
-      const actionSummary = steps.map((s) => summarizeAction(s.action)).join("; ");
-      const messages = [
-        { role: "user", content: `Task: ${outcome.result}` },
-        { role: "assistant", content: `Actions: ${actionSummary}. Result: ${outcome.result}` }
-      ];
-      this.memoryManager.appendMessages(sessionId, messages, this.model).catch((e) => this.logger.warn("Memory persist failed", { error: String(e) }));
-      try {
-        this.memoryManager.afterRun(sessionId, userId, messages, this.model, this.name);
-      } catch (e) {
-        this.logger.warn("Memory afterRun failed", { error: String(e) });
-      }
-    }
-    this.eventBus.emit("browser.done", {
-      result: output.result,
-      success: outcome.success,
-      steps
-    });
-    return output;
-  }
-  /**
-   * Execute a single action. Returns `{ output?, didNavigate? }` for the
-   * caller's state tracking. May throw — the loop handles failure-budget
-   * accounting in that case.
-   */
-  async executeAction(browser, action, _actionHistory, extractedContent) {
-    switch (action.action) {
-      case "click": {
-        if (typeof action.index === "number") {
-          const ok = await browser.clickByIndex(action.index);
-          if (ok) return {};
-        }
-        const keyword = this.extractClickKeyword(action.description);
-        if (keyword && await browser.clickByText(keyword)) {
-          this.logger.debug("Clicked by text", { keyword });
-          return {};
-        }
-        if (typeof action.x === "number" && typeof action.y === "number") {
-          await browser.click(action.x, action.y);
-          return {};
-        }
-        throw new Error(`click action has no resolvable target (index/text/coordinates)`);
-      }
-      case "type": {
-        const resolvedText = this.credentials ? this.credentials.resolve(action.text) : action.text;
-        const submit = action.submit ?? resolvedText.includes("\n");
-        const cleanText = submit ? resolvedText.replace(/\n+$/, "") : resolvedText;
-        if (typeof action.index === "number") {
-          const ok = await browser.inputByIndex(action.index, cleanText, {
-            clear: action.clear,
-            submit
-          });
-          if (ok) return {};
-        }
-        if (typeof action.x === "number" && typeof action.y === "number") {
-          await browser.clickAndType(action.x, action.y, cleanText);
-          if (submit) await browser.pressKey("Enter");
-          return {};
-        }
-        await browser.type(cleanText);
-        if (submit) await browser.pressKey("Enter");
-        return {};
-      }
-      case "scroll": {
-        if (typeof action.index === "number") {
-          await browser.scrollIntoViewByIndex(action.index);
-          return {};
-        }
-        await browser.scroll(action.direction, action.amount);
-        return {};
-      }
-      case "navigate": {
-        this.assertDomainAllowed(action.url);
-        await browser.navigate(action.url);
-        return { didNavigate: true };
-      }
-      case "back":
-        await browser.back();
-        return { didNavigate: true };
-      case "wait":
-        await this.sleep(Math.min(action.ms, 1e4));
-        return {};
-      case "screenshot":
-        return {};
-      case "send_keys":
-        await browser.sendKeys(action.keys);
-        return {};
-      case "find_text":
-        await browser.findText(action.text);
-        return {};
-      case "evaluate": {
-        if (!this.allowEvaluate) {
-          throw new Error("evaluate is disabled. Set allowEvaluate: true on BrowserAgent to enable.");
-        }
-        const out = await browser.evaluate(action.code);
-        return { output: `evaluate \u2192 ${out}` };
-      }
-      case "dropdown_options": {
-        const options = await browser.dropdownOptions(action.index);
-        const formatted = options.map((o, i) => `${i + 1}. "${o.label}" (value="${o.value}")${o.selected ? " [selected]" : ""}`).join("\n");
-        return { output: `Dropdown [${action.index}] options:
-${formatted || "(no options found)"}` };
-      }
-      case "select_dropdown": {
-        const ok = await browser.selectDropdown(action.index, action.text);
-        if (!ok) throw new Error(`Could not select "${action.text}" on dropdown [${action.index}]`);
-        return {};
-      }
-      case "upload_file": {
-        const ok = await browser.uploadFileByIndex(action.index, action.path);
-        if (!ok) throw new Error(`Could not upload "${action.path}" to [${action.index}]`);
-        return {};
-      }
-      case "extract": {
-        const pageText = await browser.pageText({ extractLinks: action.extractLinks });
-        const model = this.pageExtractionLLM ?? this.model;
-        const messages = [
-          {
-            role: "system",
-            content: "You extract information from web pages. Use ONLY the page content provided. If the requested information is not present, say so explicitly. Be concise and structured (lists/tables) when appropriate."
-          },
-          {
-            role: "user",
-            content: `Query: ${action.query}
-
-Page content:
-${pageText}`
-          }
-        ];
-        const response = await model.generate(messages, { temperature: 0, maxTokens: 2048 });
-        const out = typeof response.message.content === "string" ? response.message.content : "";
-        const masked = this.credentials ? this.credentials.mask(out) : out;
-        extractedContent.push(masked);
-        return { output: masked };
-      }
-      case "tool": {
-        const tool = this.tools.find((t) => t.name === action.name);
-        if (!tool) throw new Error(`Tool "${action.name}" is not registered on this BrowserAgent`);
-        const ctx = new import_core.RunContext({
-          sessionId: `browser_${this.name}_${Date.now()}`,
-          eventBus: this.eventBus
-        });
-        const result = await tool.execute(action.args ?? {}, ctx);
-        const out = typeof result === "string" ? result : JSON.stringify(result);
-        return { output: `${action.name} \u2192 ${out}` };
-      }
-      // `done` and `fail` are intercepted by the run loop before we get
-      // here. Listing them keeps the discriminated union exhaustive.
-      case "done":
-      case "fail":
-        return {};
-    }
-  }
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-  /**
-   * Parse a quoted target keyword from a click action's `description`.
-   * Returns `undefined` for generic / ambiguous labels (login buttons,
-   * close, OK, etc.) where a substring text match could fire on the
-   * wrong element.
-   */
-  extractClickKeyword(description) {
-    if (!description) return void 0;
-    const match = description.match(
-      /['"\u2018\u2019\u201C\u201D]([^'"\u2018\u2019\u201C\u201D]{1,80})['"\u2018\u2019\u201C\u201D]/
-    );
-    if (!match) return void 0;
-    const keyword = match[1].trim();
-    if (!keyword || keyword.length < 2) return void 0;
-    const skip = /* @__PURE__ */ new Set([
-      "log in",
-      "login",
-      "sign in",
-      "sign up",
-      "submit",
-      "close",
-      "ok",
-      "okay",
-      "cancel",
-      "yes",
-      "no",
-      "x",
-      "continue",
-      "next",
-      "back",
-      "accept",
-      "dismiss",
-      "got it",
-      "agree",
-      "i agree",
-      "allow",
-      "deny"
-    ]);
-    if (skip.has(keyword.toLowerCase())) return void 0;
-    return keyword;
-  }
+	name;
+	eventBus;
+	model;
+	pageExtractionLLM;
+	fallbackModel;
+	useThinking;
+	historyWindow;
+	instructions;
+	extendSystemMessage;
+	overrideSystemMessage;
+	maxSteps;
+	maxFailures;
+	maxActionsPerStep;
+	initialActions;
+	useVision;
+	directlyOpenUrl;
+	headless;
+	viewport;
+	defaultStartUrl;
+	waitAfterAction;
+	maxRepeats;
+	useDOM;
+	allowEvaluate;
+	allowedDomains;
+	prohibitedDomains;
+	storageState;
+	cdpUrl;
+	recordVideo;
+	credentials;
+	stealth;
+	humanize;
+	tools;
+	approvalManager;
+	executionPolicy;
+	planner;
+	jevModel;
+	maxActionChoices;
+	searchEngine;
+	jevProvider = null;
+	costTracker;
+	memoryManager = null;
+	logger;
+	/** Access the MemoryManager (if memory is configured). */
+	get memory() {
+		return this.memoryManager;
+	}
+	constructor(config) {
+		this.name = config.name;
+		this.model = config.model;
+		this.pageExtractionLLM = config.pageExtractionLLM ?? null;
+		this.fallbackModel = config.fallbackModel ?? null;
+		this.useThinking = config.useThinking ?? true;
+		this.historyWindow = Math.max(0, config.historyWindow ?? 6);
+		this.instructions = config.instructions;
+		this.extendSystemMessage = config.extendSystemMessage;
+		this.overrideSystemMessage = config.overrideSystemMessage;
+		this.maxSteps = config.maxSteps ?? 30;
+		this.maxFailures = config.maxFailures ?? 3;
+		this.maxActionsPerStep = Math.max(1, config.maxActionsPerStep ?? 3);
+		this.initialActions = config.initialActions ?? [];
+		this.useVision = config.useVision ?? "auto";
+		this.directlyOpenUrl = config.directlyOpenUrl ?? true;
+		this.headless = config.headless ?? true;
+		this.viewport = config.viewport ?? {
+			width: 1280,
+			height: 720
+		};
+		this.defaultStartUrl = config.startUrl;
+		this.waitAfterAction = config.waitAfterAction ?? 1500;
+		this.maxRepeats = config.maxRepeats ?? 3;
+		this.useDOM = config.useDOM ?? true;
+		this.allowEvaluate = config.allowEvaluate ?? false;
+		this.allowedDomains = config.allowedDomains;
+		this.prohibitedDomains = config.prohibitedDomains;
+		this.storageState = config.storageState;
+		this.cdpUrl = config.cdpUrl;
+		this.recordVideo = config.recordVideo;
+		this.credentials = config.credentials;
+		this.stealth = config.stealth;
+		this.humanize = config.humanize;
+		this.eventBus = config.eventBus ?? new _agentium_core.EventBus();
+		this.tools = config.tools ?? [];
+		this.executionPolicy = config.executionPolicy;
+		this.approvalManager = config.approvalManager ?? (config.approval ? new _agentium_core.ApprovalManager({
+			...config.approval,
+			eventBus: this.eventBus
+		}) : null);
+		this.planner = config.planner ?? "vision";
+		this.jevModel = config.jevModel ?? "jev-latest";
+		this.maxActionChoices = config.maxActionChoices ?? 40;
+		this.searchEngine = config.searchEngine ?? "duckduckgo";
+		this.costTracker = config.costTracker ?? null;
+		this.logger = new _agentium_core.Logger({
+			prefix: `BrowserAgent:${config.name}`,
+			level: config.logLevel ?? "silent"
+		});
+		if (config.memory) this.memoryManager = new _agentium_core.MemoryManager(config.memory);
+	}
+	async run(task, opts) {
+		const startTime = Date.now();
+		const maxSteps = opts?.maxSteps ?? this.maxSteps;
+		const sessionId = opts?.context?.sessionId ?? opts?.sessionId ?? `browser_${startTime}`;
+		const userId = opts?.context?.userId ?? opts?.userId;
+		const ctx = opts?.context ?? new _agentium_core.RunContext({
+			sessionId,
+			userId,
+			tenantId: opts?.tenantId,
+			signal: opts?.signal,
+			runMode: opts?.runMode,
+			executionPolicy: this.executionPolicy,
+			eventBus: this.eventBus
+		});
+		const executor = new _agentium_core.ToolExecutor(this.tools, {
+			approvalManager: this.approvalManager ?? void 0,
+			executionPolicy: this.executionPolicy,
+			agentName: this.name
+		});
+		const browser = new BrowserProvider();
+		const steps = [];
+		const actionHistory = [];
+		const extractedContent = [];
+		let lastExtractResult;
+		let consecutiveFailures = 0;
+		let lastActionWasScreenshot = false;
+		const loop = new LoopDetector();
+		/**
+		* Rolling conversation history. Each entry stores the structured
+		* agent envelope so we can replay model_thoughts to the model on
+		* subsequent steps — this is what `historyWindow > 0` buys us.
+		*/
+		const historyTurns = [];
+		let extraInstructions = [this.instructions, this.extendSystemMessage].filter(Boolean).join("\n\n");
+		if (this.memoryManager) {
+			await this.memoryManager.ensureReady();
+			const memoryContext = await this.memoryManager.buildContext(sessionId, userId, task, this.name);
+			if (memoryContext) extraInstructions = extraInstructions ? `${extraInstructions}\n\n${memoryContext}` : memoryContext;
+		}
+		const credentialKeys = this.credentials?.keys();
+		const systemPrompt = buildSystemPrompt(this.viewport, extraInstructions || void 0, credentialKeys, {
+			overrideSystemMessage: this.overrideSystemMessage,
+			maxActionsPerStep: this.maxActionsPerStep,
+			allowEvaluate: this.allowEvaluate,
+			tools: this.tools,
+			useVision: this.useVision,
+			useDOM: this.useDOM,
+			useThinking: this.useThinking
+		});
+		try {
+			if (ctx.signal?.aborted) throw new Error("Browser run cancelled");
+			if (ctx.runMode === "plan") throw new Error("Native browser operations are not supported in plan mode");
+			this.logger.info("Launching browser", {
+				headless: this.headless,
+				viewport: this.viewport,
+				useDOM: this.useDOM,
+				useVision: this.useVision,
+				useThinking: this.useThinking,
+				cdpUrl: this.cdpUrl ?? void 0,
+				recordVideo: !!this.recordVideo,
+				stealth: !!this.stealth,
+				humanize: !!this.humanize
+			});
+			await browser.launch({
+				headless: this.headless,
+				viewport: this.viewport,
+				storageState: this.storageState,
+				recordVideo: this.recordVideo,
+				stealth: this.stealth,
+				humanize: this.humanize,
+				cdpUrl: this.cdpUrl
+			});
+			const startUrl = opts?.startUrl ?? this.defaultStartUrl ?? this.detectUrlInTask(task);
+			if (startUrl) {
+				this.logger.info("Navigating to start URL", { url: startUrl });
+				this.assertDomainAllowed(startUrl);
+				await browser.navigate(startUrl);
+				await this.navigationHealthCheck(browser, startUrl);
+			}
+			for (const ia of this.initialActions) {
+				try {
+					await this.executeAction(browser, ia, actionHistory, extractedContent, ctx, executor);
+				} catch (e) {
+					this.logger.warn("initialAction failed", {
+						action: ia,
+						error: e?.message
+					});
+				}
+				await this.sleep(this.waitAfterAction);
+			}
+			for (let step = 0; step < maxSteps; step++) {
+				if (ctx.signal?.aborted) throw new Error("Browser run cancelled");
+				const pageInfo = await browser.getPageInfo();
+				let domSnapshot;
+				let scrollCtx;
+				let elements = [];
+				if (this.useDOM) {
+					const dom = await browser.extractDOM();
+					domSnapshot = dom.text;
+					scrollCtx = dom.scroll;
+					elements = dom.elements;
+				}
+				const tabs = browser.listTabs();
+				const pageAdvice = loop.recordPage({
+					url: pageInfo.url,
+					interactiveCount: scrollCtx?.totalInteractive ?? 0,
+					textHash: fnvHash(domSnapshot ?? "")
+				});
+				if (pageAdvice.severity === "abort") return await this.finalize(browser, steps, startTime, opts, extractedContent, {
+					result: pageAdvice.message ?? "Auto-stopped: page is stagnant.",
+					success: false
+				});
+				const wantVision = this.shouldCaptureVision(step, lastActionWasScreenshot);
+				const screenshot = wantVision ? await browser.screenshot() : Buffer.alloc(0);
+				if (wantVision) this.eventBus.emit("browser.screenshot", { data: screenshot });
+				const isLastStep = step === maxSteps - 1;
+				const nudgeParts = [];
+				if (pageAdvice.severity !== "none" && pageAdvice.message) nudgeParts.push(pageAdvice.message);
+				if (isLastStep) nudgeParts.push("This is your FINAL step. Return a `done` action right now summarizing whatever you have, even if partial.");
+				const nudge = nudgeParts.length > 0 ? nudgeParts.join(" ") : void 0;
+				const userText = buildUserMessage(task, pageInfo.url, pageInfo.title, step, actionHistory, domSnapshot, lastExtractResult, scrollCtx, nudge, {
+					current: step,
+					max: maxSteps
+				}, tabs);
+				this.logger.debug("Calling planner", {
+					step,
+					url: pageInfo.url,
+					planner: this.planner,
+					vision: wantVision
+				});
+				let envelope = null;
+				let modelUsed = this.model;
+				if (this.planner === "jev") {
+					const planned = await this.planWithJev({
+						task,
+						url: pageInfo.url,
+						title: pageInfo.title,
+						elements,
+						tabs,
+						actionHistory,
+						lastExtract: lastExtractResult,
+						pagesBelow: scrollCtx?.pagesBelow,
+						pagesAbove: scrollCtx?.pagesAbove,
+						apiKey: opts?.apiKey,
+						signal: ctx.signal
+					});
+					envelope = planned.envelope;
+					modelUsed = planned.modelUsed;
+					if (this.costTracker && planned.usage) this.costTracker.track({
+						runId: sessionId,
+						agentName: this.name,
+						modelId: modelUsed.modelId,
+						usage: planned.usage,
+						sessionId,
+						userId
+					});
+				} else {
+					const messages = this.buildMessages(systemPrompt, historyTurns, userText, wantVision ? screenshot : null);
+					const { response, modelUsed: used } = await this.callModelWithFallback(messages, opts?.apiKey, ctx.signal);
+					modelUsed = used;
+					if (!response) {
+						consecutiveFailures++;
+						actionHistory.push(`(model call failed — retrying, ${consecutiveFailures}/${this.maxFailures})`);
+						if (consecutiveFailures > this.maxFailures) return await this.forceDone(browser, steps, startTime, opts, extractedContent, actionHistory, "model");
+						continue;
+					}
+					if (this.costTracker && response.usage) this.costTracker.track({
+						runId: sessionId,
+						agentName: this.name,
+						modelId: modelUsed.modelId,
+						usage: response.usage,
+						sessionId,
+						userId
+					});
+					const raw = typeof response.message.content === "string" ? response.message.content : "";
+					envelope = this.parseEnvelope(raw);
+				}
+				if (ctx.signal?.aborted) throw new Error("Browser run cancelled");
+				if (!envelope) {
+					consecutiveFailures++;
+					this.logger.warn("Failed to parse planner response", {
+						planner: this.planner,
+						consecutiveFailures
+					});
+					if (consecutiveFailures > this.maxFailures) return await this.forceDone(browser, steps, startTime, opts, extractedContent, actionHistory, "parse");
+					actionHistory.push("(invalid JSON response — retrying)");
+					continue;
+				}
+				consecutiveFailures = 0;
+				historyTurns.push({
+					userText,
+					hasScreenshot: wantVision,
+					envelope
+				});
+				if (this.historyWindow > 0 && historyTurns.length > this.historyWindow) historyTurns.splice(0, historyTurns.length - this.historyWindow);
+				const actions = (Array.isArray(envelope.action) ? envelope.action : [envelope.action]).slice(0, this.maxActionsPerStep);
+				let didTerminate = null;
+				let didNavigate = false;
+				lastActionWasScreenshot = false;
+				for (let ai = 0; ai < actions.length; ai++) {
+					if (ctx.signal?.aborted) throw new Error("Browser run cancelled");
+					const action = actions[ai];
+					let summary = summarizeAction(action);
+					if (this.credentials) summary = this.credentials.mask(summary);
+					const advice = loop.recordAction(action);
+					if (advice.severity === "abort" && action.action !== "done" && action.action !== "fail") {
+						this.logger.warn("Loop detector aborting run", { advice });
+						actionHistory.push(`⚠ ${advice.message ?? "loop detected — auto-stopping"}`);
+						didTerminate = {
+							result: advice.message ?? "Stuck in a loop — auto-stopped.",
+							success: false
+						};
+						break;
+					}
+					actionHistory.push(summary);
+					this.logger.info(`Step ${step + 1}.${ai + 1}: ${summary}`);
+					this.eventBus.emit("browser.action", { action });
+					if (action.action === "done") {
+						didTerminate = {
+							result: this.credentials ? this.credentials.mask(action.result) : action.result,
+							success: true
+						};
+						break;
+					}
+					if (action.action === "fail") {
+						didTerminate = {
+							result: this.credentials ? this.credentials.mask(action.reason) : action.reason,
+							success: false
+						};
+						break;
+					}
+					let stepOk = true;
+					let stepOutput;
+					try {
+						const exec = await this.executeAction(browser, action, actionHistory, extractedContent, ctx, executor);
+						stepOutput = exec?.output;
+						if (exec?.didNavigate) {
+							didNavigate = true;
+							await this.navigationHealthCheck(browser, pageInfo.url);
+						}
+						if (exec?.output && (action.action === "extract" || action.action === "search" || action.action === "find_elements" || action.action === "search_page")) lastExtractResult = exec.output;
+						if (action.action === "screenshot") lastActionWasScreenshot = true;
+					} catch (e) {
+						stepOk = false;
+						consecutiveFailures++;
+						this.logger.warn("Action failed", {
+							action: action.action,
+							error: e?.message,
+							consecutiveFailures
+						});
+						actionHistory.push(`(error: ${e?.message ?? "unknown"})`);
+						if (consecutiveFailures > this.maxFailures) {
+							didTerminate = {
+								result: `Action ${action.action} failed ${consecutiveFailures} times. Last error: ${e?.message}`,
+								success: false
+							};
+							break;
+						}
+					}
+					steps.push({
+						index: steps.length,
+						action,
+						screenshot,
+						pageUrl: pageInfo.url,
+						pageTitle: pageInfo.title,
+						timestamp: /* @__PURE__ */ new Date(),
+						dom: domSnapshot,
+						output: stepOutput,
+						ok: stepOk,
+						thinking: envelope.thinking,
+						evaluationPreviousGoal: envelope.evaluationPreviousGoal,
+						memory: envelope.memory,
+						nextGoal: envelope.nextGoal
+					});
+					this.eventBus.emit("browser.step", {
+						index: steps.length - 1,
+						action,
+						pageUrl: pageInfo.url,
+						screenshot
+					});
+					await this.sleep(this.waitAfterAction);
+					if (didNavigate) break;
+				}
+				if (didTerminate) return await this.finalize(browser, steps, startTime, opts, extractedContent, didTerminate);
+			}
+			this.logger.warn("Max steps reached without explicit done", { maxSteps });
+			return await this.forceDone(browser, steps, startTime, opts, extractedContent, actionHistory, "max_steps");
+		} catch (error) {
+			this.logger.error("Browser agent error", { error: error.message });
+			this.eventBus.emit("browser.error", { error });
+			await browser.close();
+			return {
+				result: `Error: ${error.message}`,
+				success: false,
+				steps,
+				finalUrl: "",
+				finalScreenshot: Buffer.alloc(0),
+				durationMs: Date.now() - startTime,
+				extractedContent
+			};
+		} finally {
+			if (!opts?.context) this.approvalManager?.cancelRun(ctx.runId);
+		}
+	}
+	/**
+	* Returns a ToolDef that lets a regular Agent delegate browser tasks
+	* to this BrowserAgent.
+	*/
+	asTool(config) {
+		return {
+			name: config?.name ?? "browse_web",
+			description: config?.description ?? "Open a browser and autonomously complete a task on a website. Provide a clear task description and optionally a starting URL.",
+			parameters: zod_v3.z.object({
+				task: zod_v3.z.string().describe("What to do in the browser (e.g., 'Search for X and return the top 3 results')"),
+				startUrl: zod_v3.z.string().optional().describe("URL to start at (e.g., 'https://www.google.com')")
+			}),
+			execute: async (args, ctx) => {
+				return (await this.run(args.task, {
+					startUrl: args.startUrl,
+					context: ctx
+				})).result;
+			}
+		};
+	}
+	shouldCaptureVision(step, lastActionWasScreenshot) {
+		if (this.planner === "jev" && this.useVision !== true) return false;
+		if (this.useVision === false) return false;
+		if (this.useVision === true) return true;
+		if (step === 0) return true;
+		if (!this.useDOM) return true;
+		return lastActionWasScreenshot;
+	}
+	detectUrlInTask(task) {
+		if (!this.directlyOpenUrl) return void 0;
+		const match = task.match(/https?:\/\/[^\s)<>"']+/);
+		return match ? match[0] : void 0;
+	}
+	assertDomainAllowed(url) {
+		if (!this.allowedDomains?.length && !this.prohibitedDomains?.length) return;
+		let host;
+		try {
+			host = new URL(url).hostname.toLowerCase();
+		} catch {
+			throw new Error(`Cannot parse URL for domain check: ${url}`);
+		}
+		if (this.allowedDomains?.length && !this.allowedDomains.some((p) => matchDomain(host, p))) throw new Error(`Navigation blocked: ${host} is not in allowedDomains`);
+		if (this.prohibitedDomains?.length && this.prohibitedDomains.some((p) => matchDomain(host, p))) throw new Error(`Navigation blocked: ${host} is in prohibitedDomains`);
+	}
+	/**
+	* Build the message array sent to the model: system prompt + a compact
+	* summary of older turns (if any) + the most recent `historyWindow`
+	* turns verbatim + the current step's user message.
+	*
+	* Inspired by browser-use's history compaction. Keeps tokens bounded
+	* while giving the model meaningful context about what it already
+	* tried.
+	*/
+	buildMessages(systemPrompt, historyTurns, currentUserText, currentScreenshot) {
+		const msgs = [{
+			role: "system",
+			content: systemPrompt
+		}];
+		if (this.historyWindow > 0 && historyTurns.length > 0) for (const turn of historyTurns) {
+			const env = turn.envelope;
+			const replay = [];
+			if (env.thinking) replay.push(`thinking: ${env.thinking}`);
+			if (env.evaluationPreviousGoal) replay.push(`evaluation: ${env.evaluationPreviousGoal}`);
+			if (env.memory) replay.push(`memory: ${env.memory}`);
+			if (env.nextGoal) replay.push(`next_goal: ${env.nextGoal}`);
+			replay.push(`action: ${JSON.stringify(env.action)}`);
+			msgs.push({
+				role: "assistant",
+				content: replay.join("\n")
+			});
+		}
+		const content = [];
+		if (currentScreenshot && currentScreenshot.length > 0) content.push({
+			type: "image",
+			data: currentScreenshot.toString("base64"),
+			mimeType: "image/png"
+		});
+		content.push({
+			type: "text",
+			text: currentUserText
+		});
+		msgs.push({
+			role: "user",
+			content
+		});
+		return msgs;
+	}
+	/**
+	* Call the primary model, retrying once with `fallbackModel` on
+	* transient errors (5xx, 429, network). Returns the response or
+	* `null` if both models failed.
+	*/
+	async callModelWithFallback(messages, apiKey, signal) {
+		const reqOpts = {
+			temperature: .1,
+			maxTokens: 1024,
+			apiKey,
+			signal,
+			responseFormat: "json"
+		};
+		try {
+			signal?.throwIfAborted();
+			const r = await this.model.generate(messages, reqOpts);
+			signal?.throwIfAborted();
+			return {
+				response: r,
+				modelUsed: this.model
+			};
+		} catch (e) {
+			signal?.throwIfAborted();
+			if (this.fallbackModel && this.isTransientError(e)) {
+				this.logger.warn("Primary model failed; trying fallbackModel", {
+					error: e?.message,
+					primary: this.model.modelId,
+					fallback: this.fallbackModel.modelId
+				});
+				try {
+					const r = await this.fallbackModel.generate(messages, reqOpts);
+					signal?.throwIfAborted();
+					return {
+						response: r,
+						modelUsed: this.fallbackModel
+					};
+				} catch (e2) {
+					signal?.throwIfAborted();
+					this.logger.warn("Fallback model also failed", { error: e2?.message });
+					return {
+						response: null,
+						modelUsed: this.model
+					};
+				}
+			}
+			this.logger.warn("Model call failed (no fallback configured)", { error: e?.message });
+			return {
+				response: null,
+				modelUsed: this.model
+			};
+		}
+	}
+	isTransientError(e) {
+		const msg = String(e?.message ?? e).toLowerCase();
+		if (msg.includes("rate limit") || msg.includes("429")) return true;
+		if (msg.includes("timeout") || msg.includes("etimedout")) return true;
+		if (msg.includes("econnreset") || msg.includes("network")) return true;
+		if (/\b5\d\d\b/.test(msg)) return true;
+		if (msg.includes("401") || msg.includes("402") || msg.includes("auth")) return true;
+		return false;
+	}
+	getJev() {
+		if (!this.jevProvider) this.jevProvider = (0, _agentium_core.jev)(this.jevModel);
+		return this.jevProvider;
+	}
+	/**
+	* Ask Jev to pick one label from this frame's action space, then map it
+	* to a BrowserAction. Type/search strings come from a text model or the task.
+	*/
+	async planWithJev(args) {
+		const alreadySearched = args.actionHistory.some((h) => /^Searched /.test(h));
+		const alreadyWaited = args.actionHistory.some((h) => /^Waited /.test(h));
+		const foundTitles = args.lastExtract ?? titlesFromElements(args.elements);
+		const space = buildActionSpace(args.elements, args.tabs, {
+			max: this.maxActionChoices,
+			pagesBelow: args.pagesBelow,
+			pagesAbove: args.pagesAbove,
+			allowSearch: !alreadySearched && !isSearchResultsUrl(args.url) && !isBlockedPageUrl(args.url),
+			allowDone: looksLikeResultList(foundTitles),
+			allowWait: !alreadyWaited
+		});
+		const provider = this.getJev();
+		args.signal?.throwIfAborted();
+		try {
+			const response = await provider.generate([{
+				role: "user",
+				content: JSON.stringify({
+					task: args.task,
+					url: args.url,
+					title: args.title,
+					lastActions: args.actionHistory.slice(-8),
+					lastExtract: args.lastExtract,
+					visibleTitles: titlesFromElements(args.elements, 8),
+					tabs: args.tabs,
+					hint: looksLikeResultList(foundTitles) ? "Result titles are in lastExtract. Pick done." : alreadySearched ? "A search already ran. Wait or click a result title. Do not search again." : void 0
+				})
+			}], {
+				questions: { action: (0, _agentium_core.choice)("Which browser action next? Do not repeat lastActions. If search results are already visible, click a result or done.", space.criteria) },
+				apiKey: args.apiKey,
+				signal: args.signal
+			});
+			args.signal?.throwIfAborted();
+			const raw = typeof response.message.content === "string" ? response.message.content : "";
+			let pick;
+			try {
+				const answers = JSON.parse(raw);
+				pick = typeof answers.action === "string" ? answers.action : answers.action?.choice;
+			} catch {
+				pick = void 0;
+			}
+			if (!pick) return {
+				envelope: null,
+				modelUsed: provider,
+				usage: response.usage
+			};
+			const extras = {
+				searchQuery: pick === "search" ? guessSearchQuery(args.task) : void 0,
+				typeText: pick.startsWith("type_") ? await this.inferTypeText(args.task, pick, args.signal) : void 0,
+				doneResult: pick === "done" ? looksLikeResultList(args.lastExtract ?? "") ? args.lastExtract : titlesFromElements(args.elements) || args.lastExtract || "Done" : void 0
+			};
+			const action = labelToAction(pick, extras);
+			if (!action) return {
+				envelope: null,
+				modelUsed: provider,
+				usage: response.usage
+			};
+			return {
+				envelope: {
+					action,
+					nextGoal: pick
+				},
+				modelUsed: provider,
+				usage: response.usage
+			};
+		} catch (e) {
+			args.signal?.throwIfAborted();
+			this.logger.warn("Jev planner failed", { error: e?.message });
+			return {
+				envelope: null,
+				modelUsed: provider
+			};
+		}
+	}
+	async pageLooksBlocked(browser) {
+		if (isBlockedPageUrl((await browser.getPageInfo()).url)) return true;
+		try {
+			return isBotChallengeText(await browser.visibleText());
+		} catch {
+			return false;
+		}
+	}
+	async scrapeSerpTitles(browser) {
+		for (const selector of SERP_TITLE_SELECTORS) {
+			const found = await browser.findElements(selector, { maxResults: 8 });
+			const labels = [];
+			const seen = /* @__PURE__ */ new Set();
+			for (const f of found) {
+				const text = f.text.replace(/\s+/g, " ").trim();
+				if (!isResultTitle(text) || seen.has(text.toLowerCase())) continue;
+				seen.add(text.toLowerCase());
+				labels.push(text);
+			}
+			if (labels.length >= 2) return labels.slice(0, 5).map((t, i) => `${i + 1}. ${t}`).join("\n");
+		}
+		return "";
+	}
+	async inferTypeText(task, pick, signal) {
+		signal?.throwIfAborted();
+		const model = this.pageExtractionLLM ?? (this.model.providerId === "jev" ? null : this.model);
+		if (!model) return guessSearchQuery(task);
+		try {
+			const response = await model.generate([{
+				role: "user",
+				content: `Task: ${task}\nThe next browser action is ${pick}. Reply with ONLY the text to type into that field. No quotes.`
+			}], { signal });
+			signal?.throwIfAborted();
+			return (typeof response.message.content === "string" ? response.message.content.trim() : "").replace(/^["']|["']$/g, "").slice(0, 500);
+		} catch {
+			signal?.throwIfAborted();
+			return guessSearchQuery(task);
+		}
+	}
+	/**
+	* Parse the model's raw response into an `AgentOutput`. Tolerant to
+	* three shapes:
+	*  - Full envelope: { thinking, evaluation_previous_goal, action, ... }
+	*  - Raw action object (legacy / `useThinking: false`)
+	*  - Raw action array
+	*
+	* Also strips ```json fences the model occasionally adds.
+	*/
+	parseEnvelope(raw) {
+		if (!raw) return null;
+		let s = raw.trim();
+		const fence = s.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/);
+		if (fence) s = fence[1].trim();
+		let json;
+		try {
+			json = JSON.parse(s);
+		} catch {
+			const m = s.match(/[[{][\s\S]*[\]}]/);
+			if (!m) return null;
+			try {
+				json = JSON.parse(m[0]);
+			} catch {
+				return null;
+			}
+		}
+		if (Array.isArray(json)) return { action: json };
+		if (json && typeof json === "object" && typeof json.action === "string") return { action: json };
+		if (json && typeof json === "object" && "action" in json) {
+			const out = { action: json.action };
+			out.thinking = json.thinking ?? json.reasoning ?? void 0;
+			out.evaluationPreviousGoal = json.evaluationPreviousGoal ?? json.evaluation_previous_goal ?? void 0;
+			out.memory = json.memory ?? void 0;
+			out.nextGoal = json.nextGoal ?? json.next_goal ?? void 0;
+			return out;
+		}
+		return null;
+	}
+	/**
+	* Quick post-navigation health check. If the page came back blank
+	* (no body text and no interactive elements), reload once and wait
+	* for stable. This catches the "FreightOS half-loaded font test" class
+	* of failure before the LLM ever sees it.
+	*/
+	async navigationHealthCheck(browser, url) {
+		try {
+			const ok = await browser.pageText({ maxChars: 200 }).catch(() => "");
+			if (ok && ok.trim().length > 5) return;
+			this.logger.warn("Navigation produced an empty page; reloading once", { url });
+			await this.sleep(800);
+			try {
+				await browser.navigate(url);
+			} catch {}
+		} catch {}
+	}
+	/**
+	* Force-finalize the run with whatever partial data the agent has.
+	* Called when:
+	*   - `maxSteps` is exhausted without an explicit `done`,
+	*   - `maxFailures` is exceeded,
+	*   - the model can't produce parseable JSON enough times to make
+	*     forward progress.
+	* The result is composed from `extractedContent` + the last few
+	* action summaries so the caller gets something useful instead of
+	* just a one-line error.
+	*/
+	async forceDone(browser, steps, startTime, opts, extractedContent, actionHistory, reason) {
+		const reasonLine = reason === "model" ? "Model call failed too many consecutive times." : reason === "parse" ? "Model produced invalid JSON too many times." : "Max step budget exhausted before an explicit `done`.";
+		const tail = actionHistory.slice(-5).join(" → ");
+		const extracts = extractedContent.length > 0 ? `\n\nExtracts so far:\n${extractedContent.join("\n---\n")}` : "";
+		const result = `${reasonLine}\nLast actions: ${tail || "(none)"}${extracts}`;
+		return await this.finalize(browser, steps, startTime, opts, extractedContent, {
+			result,
+			success: false
+		});
+	}
+	async finalize(browser, steps, startTime, opts, extractedContent, outcome) {
+		let finalScreenshot;
+		let finalInfo;
+		try {
+			finalScreenshot = await browser.screenshot();
+			finalInfo = await browser.getPageInfo();
+		} catch {
+			finalScreenshot = Buffer.alloc(0);
+			finalInfo = {
+				url: "",
+				title: ""
+			};
+		}
+		if (opts?.saveStorageState) try {
+			await browser.saveStorageState(opts.saveStorageState);
+			this.logger.info("Storage state saved", { path: opts.saveStorageState });
+		} catch (e) {
+			this.logger.warn("Failed to save storage state", { error: e.message });
+		}
+		let videoPath;
+		if (this.recordVideo) videoPath = await browser.getVideoPath() ?? void 0;
+		await browser.close();
+		const output = {
+			result: outcome.result,
+			success: outcome.success,
+			steps,
+			finalUrl: finalInfo.url,
+			finalScreenshot,
+			durationMs: Date.now() - startTime,
+			videoPath,
+			extractedContent
+		};
+		if (this.memoryManager) {
+			const sessionId = opts?.context?.sessionId ?? opts?.sessionId ?? `browser_${startTime}`;
+			const userId = opts?.context?.userId ?? opts?.userId;
+			const actionSummary = steps.map((s) => summarizeAction(s.action)).join("; ");
+			const messages = [{
+				role: "user",
+				content: `Task: ${outcome.result}`
+			}, {
+				role: "assistant",
+				content: `Actions: ${actionSummary}. Result: ${outcome.result}`
+			}];
+			this.memoryManager.appendMessages(sessionId, messages, this.model).catch((e) => this.logger.warn("Memory persist failed", { error: String(e) }));
+			try {
+				this.memoryManager.afterRun(sessionId, userId, messages, this.model, this.name);
+			} catch (e) {
+				this.logger.warn("Memory afterRun failed", { error: String(e) });
+			}
+		}
+		this.eventBus.emit("browser.done", {
+			result: output.result,
+			success: outcome.success,
+			steps
+		});
+		return output;
+	}
+	/**
+	* Execute a single action. Returns `{ output?, didNavigate? }` for the
+	* caller's state tracking. May throw — the loop handles failure-budget
+	* accounting in that case.
+	*/
+	async executeAction(browser, action, _actionHistory, extractedContent, ctx, executor) {
+		if (ctx.signal?.aborted) throw new Error("Browser run cancelled");
+		switch (action.action) {
+			case "click": {
+				if (typeof action.index === "number") {
+					if (await browser.clickByIndex(action.index)) return {};
+				}
+				const keyword = this.extractClickKeyword(action.description);
+				if (keyword && await browser.clickByText(keyword)) {
+					this.logger.debug("Clicked by text", { keyword });
+					return {};
+				}
+				if (typeof action.x === "number" && typeof action.y === "number") {
+					await browser.click(action.x, action.y);
+					return {};
+				}
+				throw new Error(`click action has no resolvable target (index/text/coordinates)`);
+			}
+			case "type": {
+				const resolvedText = this.credentials ? this.credentials.resolve(action.text) : action.text;
+				const submit = action.submit ?? resolvedText.includes("\n");
+				const cleanText = submit ? resolvedText.replace(/\n+$/, "") : resolvedText;
+				if (typeof action.index === "number") {
+					if (await browser.inputByIndex(action.index, cleanText, {
+						clear: action.clear,
+						submit
+					})) return {};
+				}
+				if (typeof action.x === "number" && typeof action.y === "number") {
+					await browser.clickAndType(action.x, action.y, cleanText);
+					if (submit) await browser.pressKey("Enter");
+					return {};
+				}
+				await browser.type(cleanText);
+				if (submit) await browser.pressKey("Enter");
+				return {};
+			}
+			case "scroll":
+				if (typeof action.index === "number") {
+					await browser.scrollIntoViewByIndex(action.index);
+					return {};
+				}
+				await browser.scroll(action.direction, action.amount);
+				return {};
+			case "navigate":
+				this.assertDomainAllowed(action.url);
+				if (action.newTab) {
+					const tabId = await browser.newTab(action.url);
+					await browser.switchTab(tabId);
+					return {
+						didNavigate: true,
+						output: `Opened ${action.url} in ${tabId}`
+					};
+				}
+				await browser.navigate(action.url);
+				return { didNavigate: true };
+			case "search": {
+				const engine = action.engine ?? this.searchEngine;
+				const url = searchUrl(action.query, engine);
+				this.assertDomainAllowed(url);
+				await browser.navigate(url);
+				let used = engine;
+				if (await this.pageLooksBlocked(browser)) {
+					if (engine === "duckduckgo") {
+						const fallback = searchUrl(action.query, "bing");
+						this.assertDomainAllowed(fallback);
+						await browser.navigate(fallback);
+						used = "bing";
+					} else return {
+						didNavigate: true,
+						output: `Search blocked on ${engine}. Pick fail or navigate elsewhere.`
+					};
+				}
+				await browser.waitForStable(400);
+				return {
+					didNavigate: true,
+					output: await this.scrapeSerpTitles(browser) || `Searched ${used} for "${action.query}"`
+				};
+			}
+			case "new_tab": {
+				if (action.url) this.assertDomainAllowed(action.url);
+				const tabId = await browser.newTab(action.url);
+				await browser.switchTab(tabId);
+				return {
+					didNavigate: !!action.url,
+					output: `Opened ${tabId}`
+				};
+			}
+			case "switch_tab":
+				await browser.switchTab(action.tabId);
+				return {
+					didNavigate: true,
+					output: `Switched to ${action.tabId}`
+				};
+			case "close_tab":
+				await browser.closeTab(action.tabId);
+				return { output: `Closed ${action.tabId}` };
+			case "search_page": {
+				const hits = await browser.searchPage({
+					pattern: action.pattern,
+					regex: action.regex,
+					caseSensitive: action.caseSensitive,
+					maxResults: action.maxResults
+				});
+				const lines = hits.map((h, i) => `${i + 1}. "${h.match}" — …${h.context}…`);
+				return { output: hits.length ? `search_page:\n${lines.join("\n")}` : "search_page: no matches" };
+			}
+			case "find_elements": {
+				const found = await browser.findElements(action.selector, { maxResults: action.maxResults });
+				const lines = found.map((el, i) => `${i + 1}. <${el.tag}> ${el.text}${el.href ? ` ${el.href}` : ""}`);
+				return { output: found.length ? `find_elements:\n${lines.join("\n")}` : "find_elements: none" };
+			}
+			case "back":
+				await browser.back();
+				return { didNavigate: true };
+			case "wait":
+				await this.sleep(Math.min(action.ms, 1e4));
+				return {};
+			case "screenshot": return {};
+			case "send_keys":
+				await browser.sendKeys(action.keys);
+				return {};
+			case "find_text":
+				await browser.findText(action.text);
+				return {};
+			case "evaluate":
+				if (!this.allowEvaluate) throw new Error("evaluate is disabled. Set allowEvaluate: true on BrowserAgent to enable.");
+				return { output: `evaluate → ${await browser.evaluate(action.code)}` };
+			case "dropdown_options": {
+				const formatted = (await browser.dropdownOptions(action.index)).map((o, i) => `${i + 1}. "${o.label}" (value="${o.value}")${o.selected ? " [selected]" : ""}`).join("\n");
+				return { output: `Dropdown [${action.index}] options:\n${formatted || "(no options found)"}` };
+			}
+			case "select_dropdown":
+				if (!await browser.selectDropdown(action.index, action.text)) throw new Error(`Could not select "${action.text}" on dropdown [${action.index}]`);
+				return {};
+			case "upload_file":
+				if (!await browser.uploadFileByIndex(action.index, action.path)) throw new Error(`Could not upload "${action.path}" to [${action.index}]`);
+				return {};
+			case "extract": {
+				const pageText = await browser.pageText({ extractLinks: action.extractLinks });
+				const model = this.pageExtractionLLM ?? this.model;
+				const messages = [{
+					role: "system",
+					content: "You extract information from web pages. Use ONLY the page content provided. If the requested information is not present, say so explicitly. Be concise and structured (lists/tables) when appropriate."
+				}, {
+					role: "user",
+					content: `Query: ${action.query}\n\nPage content:\n${pageText}`
+				}];
+				const response = await model.generate(messages, {
+					temperature: 0,
+					maxTokens: 2048,
+					signal: ctx.signal
+				});
+				ctx.signal?.throwIfAborted();
+				const out = typeof response.message.content === "string" ? response.message.content : "";
+				const masked = this.credentials ? this.credentials.mask(out) : out;
+				extractedContent.push(masked);
+				return { output: masked };
+			}
+			case "tool": {
+				const tool = this.tools.find((t) => t.name === action.name);
+				if (!tool) throw new Error(`Tool "${action.name}" is not registered on this BrowserAgent`);
+				const [result] = await executor.executeAll([{
+					id: `browser-tool-${ctx.runId}-${Date.now()}`,
+					name: tool.name,
+					arguments: action.args ?? {}
+				}], ctx);
+				if (result.error) throw new Error(result.error);
+				const out = typeof result.result === "string" ? result.result : result.result.content;
+				return { output: `${action.name} → ${out}` };
+			}
+			case "done":
+			case "fail": return {};
+		}
+	}
+	sleep(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+	/**
+	* Parse a quoted target keyword from a click action's `description`.
+	* Returns `undefined` for generic / ambiguous labels (login buttons,
+	* close, OK, etc.) where a substring text match could fire on the
+	* wrong element.
+	*/
+	extractClickKeyword(description) {
+		if (!description) return void 0;
+		const match = description.match(/['"\u2018\u2019\u201C\u201D]([^'"\u2018\u2019\u201C\u201D]{1,80})['"\u2018\u2019\u201C\u201D]/);
+		if (!match) return void 0;
+		const keyword = match[1].trim();
+		if (!keyword || keyword.length < 2) return void 0;
+		if ((/* @__PURE__ */ new Set([
+			"log in",
+			"login",
+			"sign in",
+			"sign up",
+			"submit",
+			"close",
+			"ok",
+			"okay",
+			"cancel",
+			"yes",
+			"no",
+			"x",
+			"continue",
+			"next",
+			"back",
+			"accept",
+			"dismiss",
+			"got it",
+			"agree",
+			"i agree",
+			"allow",
+			"deny"
+		])).has(keyword.toLowerCase())) return void 0;
+		return keyword;
+	}
 };
+/**
+* Domain wildcard matcher. Supports:
+*   "example.com"       — exact match
+*   "*.example.com"     — example.com and any subdomain
+*   "*"                 — anything
+* Case-insensitive.
+*/
 function matchDomain(host, pattern) {
-  const h = host.toLowerCase();
-  let p = pattern.toLowerCase().replace(/^https?\*?:\/\//, "").replace(/^\/+/, "");
-  if (p.includes("/")) p = p.split("/")[0];
-  if (p === "*") return true;
-  if (p === h) return true;
-  if (p.startsWith("*.")) {
-    const base = p.slice(2);
-    return h === base || h.endsWith(`.${base}`);
-  }
-  return false;
+	const h = host.toLowerCase();
+	let p = pattern.toLowerCase().replace(/^https?\*?:\/\//, "").replace(/^\/+/, "");
+	if (p.includes("/")) p = p.split("/")[0];
+	if (p === "*") return true;
+	if (p === h) return true;
+	if (p.startsWith("*.")) {
+		const base = p.slice(2);
+		return h === base || h.endsWith(`.${base}`);
+	}
+	return false;
 }
-
-// src/credential-vault.ts
+//#endregion
+//#region src/credential-vault.ts
+/**
+* Secure credential store for BrowserAgent.
+*
+* Secrets are stored in memory and NEVER sent to the LLM.
+* The model works with placeholders (e.g. `{{email}}`, `{{password}}`),
+* and the agent resolves them to real values only at execution time.
+*/
 var CredentialVault = class {
-  secrets = /* @__PURE__ */ new Map();
-  constructor(initial) {
-    if (initial) {
-      for (const [key, value] of Object.entries(initial)) {
-        this.set(key, value);
-      }
-    }
-  }
-  /** Store a credential. Key names become the placeholder: `{{key}}`. */
-  set(key, value) {
-    this.secrets.set(key.toLowerCase(), value);
-    return this;
-  }
-  /** Retrieve a credential value. Returns undefined if not found. */
-  get(key) {
-    return this.secrets.get(key.toLowerCase());
-  }
-  has(key) {
-    return this.secrets.has(key.toLowerCase());
-  }
-  /** List available placeholder names (never exposes values). */
-  keys() {
-    return [...this.secrets.keys()];
-  }
-  /**
-   * Load credentials from environment variables.
-   * Maps env var names to placeholder keys.
-   *
-   * @example
-   * vault.fromEnv({ email: "LOGIN_EMAIL", password: "LOGIN_PASS" });
-   */
-  fromEnv(mapping) {
-    for (const [key, envVar] of Object.entries(mapping)) {
-      const value = process.env[envVar];
-      if (value) this.set(key, value);
-    }
-    return this;
-  }
-  /**
-   * Replace `{{key}}` placeholders in text with actual credential values.
-   * Used internally by BrowserAgent right before executing a type action.
-   */
-  resolve(text) {
-    return text.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
-      return this.get(key) ?? `{{${key}}}`;
-    });
-  }
-  /**
-   * Replace any occurrence of real credential values in text with
-   * their `{{key}}` placeholder. Used to sanitize logs and action history.
-   */
-  mask(text) {
-    let masked = text;
-    for (const [key, value] of this.secrets) {
-      if (value && masked.includes(value)) {
-        masked = masked.split(value).join(`{{${key}}}`);
-      }
-    }
-    return masked;
-  }
+	secrets = /* @__PURE__ */ new Map();
+	constructor(initial) {
+		if (initial) for (const [key, value] of Object.entries(initial)) this.set(key, value);
+	}
+	/** Store a credential. Key names become the placeholder: `{{key}}`. */
+	set(key, value) {
+		this.secrets.set(key.toLowerCase(), value);
+		return this;
+	}
+	/** Retrieve a credential value. Returns undefined if not found. */
+	get(key) {
+		return this.secrets.get(key.toLowerCase());
+	}
+	has(key) {
+		return this.secrets.has(key.toLowerCase());
+	}
+	/** List available placeholder names (never exposes values). */
+	keys() {
+		return [...this.secrets.keys()];
+	}
+	/**
+	* Load credentials from environment variables.
+	* Maps env var names to placeholder keys.
+	*
+	* @example
+	* vault.fromEnv({ email: "LOGIN_EMAIL", password: "LOGIN_PASS" });
+	*/
+	fromEnv(mapping) {
+		for (const [key, envVar] of Object.entries(mapping)) {
+			const value = process.env[envVar];
+			if (value) this.set(key, value);
+		}
+		return this;
+	}
+	/**
+	* Replace `{{key}}` placeholders in text with actual credential values.
+	* Used internally by BrowserAgent right before executing a type action.
+	*/
+	resolve(text) {
+		return text.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+			return this.get(key) ?? `{{${key}}}`;
+		});
+	}
+	/**
+	* Replace any occurrence of real credential values in text with
+	* their `{{key}}` placeholder. Used to sanitize logs and action history.
+	*/
+	mask(text) {
+		let masked = text;
+		for (const [key, value] of this.secrets) if (value && masked.includes(value)) masked = masked.split(value).join(`{{${key}}}`);
+		return masked;
+	}
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  BrowserAgent,
-  BrowserProvider,
-  CredentialVault
-});
+//#endregion
+exports.BrowserAgent = BrowserAgent;
+exports.BrowserProvider = BrowserProvider;
+exports.CredentialVault = CredentialVault;
+exports.buildActionSpace = buildActionSpace;
+exports.guessSearchQuery = guessSearchQuery;
+exports.isBlockedPageUrl = isBlockedPageUrl;
+exports.isBotChallengeText = isBotChallengeText;
+exports.isResultTitle = isResultTitle;
+exports.isSearchResultsUrl = isSearchResultsUrl;
+exports.labelToAction = labelToAction;
+exports.looksLikeResultList = looksLikeResultList;
+exports.searchUrl = searchUrl;
+exports.titlesFromElements = titlesFromElements;