@agentium/browser 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1026 @@
+"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"
+];
+function pickUserAgent() {
+  return REALISTIC_USER_AGENTS[Math.floor(Math.random() * REALISTIC_USER_AGENTS.length)];
+}
+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
+    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
+    Object.defineProperty(navigator, 'plugins', {
+      get: () => {
+        const plugins = [
+          { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+          { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai', description: '' },
+          { name: 'Native Client', filename: 'internal-nacl-plugin', description: '' },
+        ];
+        plugins.length = 3;
+        return plugins;
+      },
+      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
+    Object.defineProperty(navigator, 'languages', {
+      get: () => ['en-US', 'en'],
+      configurable: true,
+    });
+
+    // \u2500\u2500 navigator.permissions.query \u2014 hide "denied" for notifications \u2500
+    const originalQuery = window.navigator.permissions.query.bind(window.navigator.permissions);
+    window.navigator.permissions.query = (params) => {
+      if (params.name === 'notifications') {
+        return Promise.resolve({ state: 'prompt', onchange: null });
+      }
+      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
+    if (!window.chrome) {
+      window.chrome = {};
+    }
+    if (!window.chrome.runtime) {
+      window.chrome.runtime = {
+        connect: () => {},
+        sendMessage: () => {},
+      };
+    }
+
+    // \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
+    const getParameterOrig = WebGLRenderingContext.prototype.getParameter;
+    WebGLRenderingContext.prototype.getParameter = function(param) {
+      if (param === 37445) return 'Intel Inc.';
+      if (param === 37446) return 'Intel Iris OpenGL Engine';
+      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
+    if (typeof WebGL2RenderingContext !== 'undefined') {
+      const getParam2Orig = WebGL2RenderingContext.prototype.getParameter;
+      WebGL2RenderingContext.prototype.getParameter = function(param) {
+        if (param === 37445) return 'Intel Inc.';
+        if (param === 37446) return 'Intel Iris OpenGL Engine';
+        return getParam2Orig.call(this, param);
+      };
+    }
+
+    // \u2500\u2500 Prevent iframe detection of automation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    Object.defineProperty(HTMLIFrameElement.prototype, 'contentWindow', {
+      get: function() {
+        return window;
+      },
+    });
+
+    // \u2500\u2500 Remove "cdc_" Playwright/ChromeDriver markers from DOM \u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        for (const node of mutation.addedNodes) {
+          if (node.nodeType === 1) {
+            const el = node;
+            for (const attr of [...el.attributes]) {
+              if (attr.name.startsWith('cdc_') || attr.name.startsWith('__playwright')) {
+                el.removeAttribute(attr.name);
+              }
+            }
+          }
+        }
+      }
+    });
+    observer.observe(document.documentElement, { attributes: true, childList: true, subtree: true });
+  `;
+}
+function buildStealthContextOpts(config, viewport) {
+  const opts = {
+    viewport,
+    userAgent: config.userAgent ?? pickUserAgent(),
+    locale: config.locale ?? "en-US",
+    timezoneId: config.timezone ?? "America/New_York",
+    colorScheme: "light",
+    deviceScaleFactor: 2,
+    hasTouch: false,
+    javaScriptEnabled: true,
+    ignoreHTTPSErrors: config.ignoreHTTPSErrors ?? false
+  };
+  if (config.geolocation) {
+    opts.geolocation = config.geolocation;
+    opts.permissions = ["geolocation"];
+  }
+  return opts;
+}
+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 };
+}
+
+// src/browser-provider.ts
+var BrowserProvider = class {
+  browser = null;
+  context = null;
+  page = null;
+  pages = /* @__PURE__ */ new Map();
+  activeTabId = "tab-0";
+  tabCounter = 0;
+  _viewport;
+  _videoDir;
+  _humanize;
+  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 };
+    const stealthEnabled = !!opts?.stealth;
+    const stealthCfg = typeof opts?.stealth === "object" ? opts.stealth : {};
+    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
+      };
+    }
+    const launchOpts = {
+      headless: opts?.headless ?? true
+    };
+    if (stealthEnabled) {
+      const { args, proxy } = buildStealthLaunchArgs(stealthCfg);
+      launchOpts.args = args;
+      if (proxy) launchOpts.proxy = proxy;
+    }
+    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 });
+  }
+  // ── Interaction (with optional humanize) ─────────────────────────────
+  async click(x, y) {
+    this.ensurePage();
+    const [fx, fy] = this.jitter(x, y);
+    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) {
+    await this.click(x, y);
+    await this.sleep(this._humanize ? this.randInt(150, 350) : 200);
+    const [fx, fy] = this.jitter(x, y);
+    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);
+  }
+  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();
+  }
+  // ── DOM Extraction ───────────────────────────────────────────────────
+  async extractDOM(opts) {
+    this.ensurePage();
+    const max = opts?.maxElements ?? 80;
+    const elements = await this.page.evaluate((limit) => {
+      const selectors = [
+        "a[href]",
+        "button",
+        "input",
+        "textarea",
+        "select",
+        "[role='button']",
+        "[role='link']",
+        "[role='tab']",
+        "[role='menuitem']",
+        "[onclick]",
+        "[contenteditable='true']"
+      ];
+      const all = globalThis.document.querySelectorAll(selectors.join(","));
+      const lines = [];
+      let count = 0;
+      const vh = globalThis.window.innerHeight;
+      const vw = globalThis.window.innerWidth;
+      for (const el of all) {
+        if (count >= limit) break;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0) continue;
+        if (rect.bottom < 0 || rect.top > vh) continue;
+        if (rect.right < 0 || rect.left > vw) continue;
+        const tag = el.tagName.toLowerCase();
+        const role = el.getAttribute("role") || tag;
+        const type = el.getAttribute("type") || "";
+        const text = (el.textContent || "").trim().slice(0, 80);
+        const placeholder = el.getAttribute("placeholder") || "";
+        const ariaLabel = el.getAttribute("aria-label") || "";
+        const href = el.getAttribute("href") || "";
+        const value = el.value || "";
+        const cx = Math.round(rect.left + rect.width / 2);
+        const cy = Math.round(rect.top + rect.height / 2);
+        let label = ariaLabel || text || placeholder || value;
+        if (!label && href) label = href.slice(0, 60);
+        if (!label) label = `(${tag}${type ? ` type=${type}` : ""})`;
+        lines.push(`[${cx},${cy}] ${role}${type ? `(${type})` : ""}: "${label}"`);
+        count++;
+      }
+      return lines.join("\n");
+    }, max);
+    return elements;
+  }
+  // ── 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) await this.context.close();
+    } catch (err) {
+      console.warn("[agentium/browser] Error closing context:", err instanceof Error ? err.message : err);
+    }
+    try {
+      if (this.browser) await this.browser.close();
+    } 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();
+  }
+  // ── 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)];
+  }
+  /**
+   * Simulate human mouse movement using Bézier-like interpolation.
+   * Moves from the current mouse position to the target in small steps.
+   */
+  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/prompts.ts
+function buildSystemPrompt(viewport, extraInstructions, credentialKeys) {
+  const lines = [
+    `You are a browser automation agent. You receive a screenshot of a web browser and decide what action to take next to complete the user's task.`,
+    ``,
+    `## Viewport`,
+    `The browser viewport is ${viewport.width}\xD7${viewport.height} pixels. All coordinates you provide must be within this range.`,
+    ``,
+    `## Available Actions`,
+    `Respond with a JSON object containing one of these actions:`,
+    ``,
+    `### click`,
+    `Click at a specific coordinate. Use for buttons, links, inputs, checkboxes, etc.`,
+    `\`{ "action": "click", "x": <number>, "y": <number>, "description": "<what you are clicking>" }\``,
+    ``,
+    `### type`,
+    `Type text. If x/y are provided, click that position first (to focus the input), then type. If omitted, types into the currently focused element. To press Enter after typing (e.g., to submit a search), append "\\n" to the text.`,
+    `\`{ "action": "type", "text": "<text to type>", "x": <number|optional>, "y": <number|optional> }\``,
+    `Example: \`{ "action": "type", "text": "search query\\n", "x": 640, "y": 300 }\` \u2014 clicks the search box, types, and presses Enter.`,
+    ``,
+    `### scroll`,
+    `Scroll the page up or down. Use when content is below or above the visible area.`,
+    `\`{ "action": "scroll", "direction": "up"|"down", "amount": <pixels, optional, default 400> }\``,
+    ``,
+    `### navigate`,
+    `Navigate to a specific URL. Use when you know the exact URL to visit.`,
+    `\`{ "action": "navigate", "url": "<full URL>" }\``,
+    ``,
+    `### back`,
+    `Go back to the previous page.`,
+    `\`{ "action": "back" }\``,
+    ``,
+    `### wait`,
+    `Wait for the page to load or for a timed event. Use sparingly.`,
+    `\`{ "action": "wait", "ms": <milliseconds> }\``,
+    ``,
+    `### done`,
+    `The task is complete. Provide a summary of what was accomplished.`,
+    `\`{ "action": "done", "result": "<summary of what was accomplished>" }\``,
+    ``,
+    `### fail`,
+    `The task cannot be completed. Explain why.`,
+    `\`{ "action": "fail", "reason": "<why the task failed>" }\``,
+    ``,
+    `## Rules`,
+    `1. ALWAYS look at the screenshot carefully before deciding your action.`,
+    `2. Provide coordinates that target the CENTER of the element you want to interact with.`,
+    `3. For text inputs: click the input field first (using "type" with x/y), then the text will be typed.`,
+    `4. After typing in a search box, you often need to press Enter \u2014 use type with text "\\n" or click the search/submit button.`,
+    `5. If your previous action didn't produce the expected result, try a different approach.`,
+    `6. If a page is loading or blank, use "wait" with a short delay and try again.`,
+    `7. If you see a cookie banner or popup, dismiss it first before proceeding with the task.`,
+    `8. NEVER hallucinate content. Only report what you can actually see on the screen.`,
+    `9. When the task is fully complete, use "done" immediately with a comprehensive result.`,
+    `10. If after several attempts you cannot complete the task, use "fail" with a clear reason.`,
+    ``,
+    `## Response Format`,
+    `Respond with ONLY a valid JSON object. No markdown, no explanation, just the JSON action.`
+  ];
+  if (credentialKeys && credentialKeys.length > 0) {
+    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 (extraInstructions) {
+    lines.push(``, `## Additional Instructions`, extraInstructions);
+  }
+  return lines.join("\n");
+}
+function buildUserMessage(task, pageUrl, pageTitle, stepIndex, actionHistory, domSnapshot) {
+  const lines = [];
+  lines.push(`**Task:** ${task}`);
+  lines.push(`**Current URL:** ${pageUrl}`);
+  if (pageTitle) lines.push(`**Page Title:** ${pageTitle}`);
+  lines.push(`**Step:** ${stepIndex + 1}`);
+  if (domSnapshot) {
+    lines.push(``);
+    lines.push(`**Interactive elements on page (format: [centerX,centerY] role: "label"):**`);
+    lines.push(domSnapshot);
+  }
+  if (actionHistory.length > 0) {
+    lines.push(``);
+    lines.push(`**Previous actions:**`);
+    for (const entry of actionHistory.slice(-10)) {
+      lines.push(`- ${entry}`);
+    }
+  }
+  lines.push(``);
+  lines.push(`Look at the screenshot and decide the next action to complete the task.`);
+  return lines.join("\n");
+}
+function summarizeAction(action) {
+  switch (action.action) {
+    case "click":
+      return `Clicked at (${action.x}, ${action.y}): ${action.description}`;
+    case "type":
+      return action.x != null ? `Clicked (${action.x}, ${action.y}) and typed "${action.text}"` : `Typed "${action.text}"`;
+    case "scroll":
+      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 `Took an extra screenshot`;
+    case "done":
+      return `Done: ${action.result}`;
+    case "fail":
+      return `Failed: ${action.reason}`;
+    default:
+      return JSON.stringify(action);
+  }
+}
+
+// src/browser-agent.ts
+var BrowserAgent = class {
+  name;
+  eventBus;
+  model;
+  instructions;
+  maxSteps;
+  headless;
+  viewport;
+  defaultStartUrl;
+  waitAfterAction;
+  maxRepeats;
+  useDOM;
+  storageState;
+  recordVideo;
+  credentials;
+  stealth;
+  humanize;
+  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.instructions = config.instructions;
+    this.maxSteps = config.maxSteps ?? 30;
+    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 ?? false;
+    this.storageState = config.storageState;
+    this.recordVideo = config.recordVideo;
+    this.credentials = config.credentials;
+    this.stealth = config.stealth;
+    this.humanize = config.humanize;
+    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 startUrl = opts?.startUrl ?? this.defaultStartUrl;
+    const sessionId = opts?.sessionId ?? `browser_${Date.now()}`;
+    const userId = opts?.userId;
+    const browser = new BrowserProvider();
+    const steps = [];
+    const actionHistory = [];
+    let extraInstructions = this.instructions ?? "";
+    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);
+    let lastActionKey = "";
+    let repeatCount = 0;
+    try {
+      this.logger.info("Launching browser", {
+        headless: this.headless,
+        viewport: this.viewport,
+        useDOM: this.useDOM,
+        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
+      });
+      if (startUrl) {
+        this.logger.info("Navigating to start URL", { url: startUrl });
+        await browser.navigate(startUrl);
+      }
+      for (let step = 0; step < this.maxSteps; step++) {
+        const screenshot = await browser.screenshot();
+        const pageInfo = await browser.getPageInfo();
+        let domSnapshot;
+        if (this.useDOM) {
+          domSnapshot = await browser.extractDOM();
+        }
+        this.eventBus.emit("browser.screenshot", { data: screenshot });
+        const userText = buildUserMessage(task, pageInfo.url, pageInfo.title, step, actionHistory, domSnapshot);
+        const messages = [
+          { role: "system", content: systemPrompt },
+          {
+            role: "user",
+            content: [
+              {
+                type: "image",
+                data: screenshot.toString("base64"),
+                mimeType: "image/png"
+              },
+              { type: "text", text: userText }
+            ]
+          }
+        ];
+        this.logger.debug("Sending screenshot to vision model", { step, url: pageInfo.url });
+        const response = await this.model.generate(messages, {
+          temperature: 0.1,
+          maxTokens: 1024,
+          apiKey: opts?.apiKey,
+          responseFormat: "json"
+        });
+        if (this.costTracker && response.usage) {
+          this.costTracker.track({
+            runId: sessionId,
+            agentName: this.name,
+            modelId: this.model.modelId,
+            usage: response.usage,
+            sessionId,
+            userId
+          });
+        }
+        const raw = typeof response.message.content === "string" ? response.message.content : "";
+        let action;
+        try {
+          action = JSON.parse(raw);
+        } catch {
+          this.logger.warn("Failed to parse model response as JSON, retrying", { raw });
+          actionHistory.push("(invalid JSON response \u2014 retrying)");
+          continue;
+        }
+        const step_ = {
+          index: step,
+          action,
+          screenshot,
+          pageUrl: pageInfo.url,
+          pageTitle: pageInfo.title,
+          timestamp: /* @__PURE__ */ new Date(),
+          dom: domSnapshot
+        };
+        steps.push(step_);
+        let summary = summarizeAction(action);
+        if (this.credentials) {
+          summary = this.credentials.mask(summary);
+        }
+        const actionKey = JSON.stringify(action);
+        if (actionKey === lastActionKey) {
+          repeatCount++;
+        } else {
+          lastActionKey = actionKey;
+          repeatCount = 1;
+        }
+        if (repeatCount > this.maxRepeats && action.action !== "done" && action.action !== "fail") {
+          this.logger.warn("Stuck in a loop \u2014 same action repeated", {
+            action: action.action,
+            repeats: repeatCount,
+            maxRepeats: this.maxRepeats
+          });
+          actionHistory.push(
+            `\u26A0 LOOP DETECTED: "${summary}" repeated ${repeatCount} times. The agent was stuck and auto-stopped. Try a different approach or a different startUrl.`
+          );
+          return await this.finalize(browser, steps, startTime, opts, {
+            result: `Stuck in a loop: "${summary}" was repeated ${repeatCount} times. The page may have a popup, consent banner, or unexpected state blocking progress.`,
+            success: false
+          });
+        }
+        actionHistory.push(summary);
+        this.logger.info(`Step ${step + 1}: ${summary}`);
+        this.eventBus.emit("browser.action", { action });
+        this.eventBus.emit("browser.step", {
+          index: step,
+          action,
+          pageUrl: pageInfo.url,
+          screenshot
+        });
+        if (action.action === "done") {
+          const result = this.credentials ? this.credentials.mask(action.result) : action.result;
+          return await this.finalize(browser, steps, startTime, opts, {
+            result,
+            success: true
+          });
+        }
+        if (action.action === "fail") {
+          const result = this.credentials ? this.credentials.mask(action.reason) : action.reason;
+          return await this.finalize(browser, steps, startTime, opts, {
+            result,
+            success: false
+          });
+        }
+        await this.executeAction(browser, action);
+        await this.sleep(this.waitAfterAction);
+      }
+      this.logger.warn("Max steps reached without completing task", { maxSteps: this.maxSteps });
+      return await this.finalize(browser, steps, startTime, opts, {
+        result: `Task not completed within ${this.maxSteps} steps. Last actions: ${actionHistory.slice(-3).join("; ")}`,
+        success: false
+      });
+    } 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
+      };
+    }
+  }
+  /**
+   * 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 ──────────────────────────────────────────────────
+  async finalize(browser, steps, startTime, opts, outcome) {
+    const finalScreenshot = await browser.screenshot();
+    const finalInfo = await browser.getPageInfo();
+    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
+    };
+    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;
+  }
+  async executeAction(browser, action) {
+    try {
+      switch (action.action) {
+        case "click":
+          await browser.click(action.x, action.y);
+          break;
+        case "type": {
+          const resolvedText = this.credentials ? this.credentials.resolve(action.text) : action.text;
+          if (action.x != null && action.y != null) {
+            await browser.clickAndType(action.x, action.y, resolvedText);
+          } else {
+            await browser.type(resolvedText);
+          }
+          if (resolvedText.includes("\n")) {
+            await browser.pressKey("Enter");
+          }
+          break;
+        }
+        case "scroll":
+          await browser.scroll(action.direction, action.amount);
+          break;
+        case "navigate":
+          await browser.navigate(action.url);
+          break;
+        case "back":
+          await browser.back();
+          break;
+        case "wait":
+          await this.sleep(Math.min(action.ms, 1e4));
+          break;
+        case "screenshot":
+          break;
+        default:
+          this.logger.warn("Unknown action", { action });
+      }
+    } catch (error) {
+      this.logger.warn("Action execution failed", { action: action.action, error: error.message });
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/credential-vault.ts
+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;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BrowserAgent,
+  BrowserProvider,
+  CredentialVault
+});