@poncho-ai/browser 0.3.4 → 0.5.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/browser@0.3.4 build /Users/cesar/Dev/latitude/poncho-ai/packages/browser
+> @poncho-ai/browser@0.4.0 build /Users/cesar/Dev/latitude/poncho-ai/packages/browser
 > tsup src/index.ts --format esm --dts
 
 CLI Building entry: src/index.ts
@@ -7,8 +7,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 24.62 KB
-ESM ⚡️ Build success in 34ms
+ESM dist/index.js 34.91 KB
+ESM ⚡️ Build success in 218ms
 DTS Build start
-DTS ⚡️ Build success in 3120ms
-DTS dist/index.d.ts 4.13 KB
+DTS ⚡️ Build success in 5616ms
+DTS dist/index.d.ts 12.44 KB

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @poncho-ai/browser
 
+## 0.5.0
+
+### Minor Changes
+
+- [`540c8e6`](https://github.com/cesr/poncho-ai/commit/540c8e6d895a95c2f215deb4af219069543371d9) Thanks [@cesr](https://github.com/cesr)! - Add `browser_click_text` and `browser_execute_js` tools for interacting with elements that don't appear in the accessibility snapshot (e.g. styled divs acting as buttons). Also force new-tab navigations (`window.open`, `target="_blank"`) to stay in the current tab so agents don't lose context.
+
+## 0.4.0
+
+### Minor Changes
+
+- [`d997362`](https://github.com/cesr/poncho-ai/commit/d997362b114f6e9c5d95794cedff2c7675e32ca5) Thanks [@cesr](https://github.com/cesr)! - Add stealth mode to browser automation (enabled by default). Reduces bot-detection fingerprints with a realistic Chrome user-agent, navigator.webdriver override, window.chrome shim, fake plugins, WebGL patches, and anti-automation Chrome flags. Configurable via `stealth` and `userAgent` options in `poncho.config.js`.
+
 ## 0.3.4
 
 ### Patch Changes

package/dist/index.d.ts

@@ -56,6 +56,13 @@ interface BrowserConfig {
     sessionName?: string;
     executablePath?: string;
     headless?: boolean;
+    /** Custom user-agent string. When `stealth` is enabled a realistic Chrome UA
+     *  is used by default — set this to override it. */
+    userAgent?: string;
+    /** Reduce bot-detection fingerprints. Defaults to `true`.
+     *  Patches navigator.webdriver, injects window.chrome shim, sets a realistic
+     *  user-agent, and passes anti-automation Chrome flags. */
+    stealth?: boolean;
     storagePersistence?: BrowserStoragePersistence;
 }
 
@@ -66,6 +73,8 @@ declare class BrowserSession {
     private readonly sessionId;
     private manager;
     private readonly tabs;
+    private _contextStealthInstalled;
+    private readonly _uaOverrideApplied;
     private _lockQueue;
     private _locked;
     private _screencastConversation;
@@ -73,6 +82,25 @@ declare class BrowserSession {
     get profileDir(): string;
     private lock;
     private unlock;
+    private get stealthEnabled();
+    private get stealthUserAgent();
+    /**
+     * Install the stealth init script on the Playwright BrowserContext.
+     * This runs before ALL page scripts on every navigation across every tab.
+     * Only needs to be called once per browser launch.
+     */
+    private installContextStealth;
+    /**
+     * Force all new-tab navigations (window.open, target="_blank") to open
+     * in the current tab instead. Agents operate on a single tab at a time
+     * and can't see or interact with popups.
+     */
+    private installSameTabScript;
+    /**
+     * Override the user-agent via CDP on the current page target.
+     * CDP Network.setUserAgentOverride is per-target, so call per-tab.
+     */
+    private overrideUserAgentOnPage;
     private launchFreshManager;
     private ensureManager;
     private evictOldestTab;
@@ -100,6 +128,8 @@ declare class BrowserSession {
         title: string;
     }>;
     scroll(conversationId: string, direction: "up" | "down", amount?: number): Promise<void>;
+    clickText(conversationId: string, text: string, exact?: boolean): Promise<void>;
+    executeJs(conversationId: string, script: string): Promise<unknown>;
     closeTab(conversationId: string): Promise<void>;
     navigate(conversationId: string, action: string): Promise<void>;
     startScreencast(conversationId: string, options?: ScreencastOptions): Promise<void>;
@@ -119,4 +149,26 @@ declare class BrowserSession {
 
 declare function createBrowserTools(getSession: () => BrowserSession, getConversationId: () => string): ToolDefinition[];
 
-export { type BrowserConfig, type BrowserFrame, BrowserSession, type BrowserStatus, type BrowserStoragePersistence, type KeyboardInputEvent, type MouseInputEvent, type ScreencastOptions, type ScrollInputEvent, type ViewportOptions, createBrowserTools };
+/**
+ * Returns a realistic Chrome user-agent string for the host OS.
+ * Uses a recent stable Chrome version to blend in with normal traffic.
+ */
+declare function defaultUserAgent(): string;
+/**
+ * Static Chromium flags that suppress automation fingerprints.
+ */
+declare const STEALTH_ARGS: string[];
+/**
+ * Build the full stealth args array including the browser-level user-agent
+ * override. The `--user-agent` flag sets the UA globally — including in
+ * Web Workers and Service Workers — which context-level overrides can't reach.
+ */
+declare function buildStealthArgs(userAgent: string): string[];
+/**
+ * JS source injected via Playwright context.addInitScript().
+ * Runs before ALL page scripts on every navigation, every tab.
+ * Each section has its own try/catch so one failure doesn't block the rest.
+ */
+declare const STEALTH_INIT_SCRIPT = "\n(() => {\n  // 1. navigator.webdriver \u2192 false\n  try {\n    Object.defineProperty(Navigator.prototype, 'webdriver', {\n      get: () => false,\n      configurable: true,\n    });\n  } catch {}\n\n  // 2. window.chrome stub (headless Chromium omits it)\n  try {\n    if (!window.chrome) {\n      const chrome = {\n        app: {\n          isInstalled: false,\n          InstallState: { DISABLED: 'disabled', INSTALLED: 'installed', NOT_INSTALLED: 'not_installed' },\n          RunningState: { CANNOT_RUN: 'cannot_run', READY_TO_RUN: 'ready_to_run', RUNNING: 'running' },\n          getDetails() { return null; },\n          getIsInstalled() { return false; },\n          installState() { return 'not_installed'; },\n        },\n        runtime: {\n          OnInstalledReason: { CHROME_UPDATE: 'chrome_update', INSTALL: 'install', SHARED_MODULE_UPDATE: 'shared_module_update', UPDATE: 'update' },\n          OnRestartRequiredReason: { APP_UPDATE: 'app_update', OS_UPDATE: 'os_update', PERIODIC: 'periodic' },\n          PlatformArch: { ARM: 'arm', ARM64: 'arm64', MIPS: 'mips', MIPS64: 'mips64', X86_32: 'x86-32', X86_64: 'x86-64' },\n          PlatformNaclArch: { ARM: 'arm', MIPS: 'mips', MIPS64: 'mips64', X86_32: 'x86-32', X86_64: 'x86-64' },\n          PlatformOs: { ANDROID: 'android', CROS: 'cros', FUCHSIA: 'fuchsia', LINUX: 'linux', MAC: 'mac', OPENBSD: 'openbsd', WIN: 'win' },\n          RequestUpdateCheckStatus: { NO_UPDATE: 'no_update', THROTTLED: 'throttled', UPDATE_AVAILABLE: 'update_available' },\n          connect() { return { onMessage: { addListener() {}, removeListener() {} }, postMessage() {}, disconnect() {} }; },\n          sendMessage() {},\n          id: undefined,\n        },\n        csi() { return {}; },\n        loadTimes() { return {}; },\n      };\n      Object.defineProperty(window, 'chrome', {\n        value: chrome,\n        writable: false,\n        enumerable: true,\n        configurable: false,\n      });\n    }\n  } catch {}\n\n  // 3. navigator.plugins \u2014 expose the plugins a real Chrome has\n  try {\n    const makeMimeType = (type, desc, suffixes, plugin) => {\n      const mt = Object.create(MimeType.prototype);\n      Object.defineProperties(mt, {\n        type: { get: () => type },\n        description: { get: () => desc },\n        suffixes: { get: () => suffixes },\n        enabledPlugin: { get: () => plugin },\n      });\n      return mt;\n    };\n    const fakePluginDefs = [\n      { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer', description: 'Portable Document Format', hasMime: true },\n      { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai', description: '', hasMime: false },\n      { name: 'Native Client', filename: 'internal-nacl-plugin', description: '', hasMime: false },\n    ];\n    const plugins = [];\n    for (const fp of fakePluginDefs) {\n      const p = Object.create(Plugin.prototype);\n      const mime = fp.hasMime ? makeMimeType('application/x-google-chrome-pdf', 'Portable Document Format', 'pdf', p) : null;\n      Object.defineProperties(p, {\n        name: { get: () => fp.name },\n        filename: { get: () => fp.filename },\n        description: { get: () => fp.description },\n        length: { get: () => mime ? 1 : 0 },\n      });\n      if (mime) Object.defineProperty(p, 0, { get: () => mime });\n      Object.defineProperty(p, 'item', { value: (i) => i === 0 && mime ? mime : null });\n      Object.defineProperty(p, 'namedItem', { value: (n) => mime && n === mime.type ? mime : null });\n      Object.defineProperty(p, Symbol.iterator, { value: function*() { if (mime) yield mime; } });\n      plugins.push(p);\n    }\n    const pluginArray = Object.create(PluginArray.prototype);\n    plugins.forEach((p, i) => Object.defineProperty(pluginArray, i, { get: () => p, enumerable: true }));\n    Object.defineProperty(pluginArray, 'length', { get: () => plugins.length });\n    Object.defineProperty(pluginArray, 'item', { value: (i) => plugins[i] ?? null });\n    Object.defineProperty(pluginArray, 'namedItem', { value: (n) => plugins.find(p => p.name === n) ?? null });\n    Object.defineProperty(pluginArray, 'refresh', { value: () => {} });\n    Object.defineProperty(pluginArray, Symbol.iterator, { value: function*() { for (const p of plugins) yield p; } });\n    Object.defineProperty(navigator, 'plugins', { get: () => pluginArray, configurable: true });\n  } catch {}\n\n  // 4. navigator.languages\n  try {\n    Object.defineProperty(navigator, 'languages', {\n      get: () => Object.freeze(['en-US', 'en']),\n      configurable: true,\n    });\n  } catch {}\n\n  // 5. Notification.permission \u2014 return \"default\" (headless returns \"denied\")\n  try {\n    if (typeof Notification !== 'undefined' && Notification.permission === 'denied') {\n      Object.defineProperty(Notification, 'permission', {\n        get: () => 'default',\n        configurable: true,\n      });\n    }\n  } catch {}\n\n  // 6. WebGL vendor/renderer \u2014 hide SwiftShader (headless giveaway)\n  try {\n    const UNMASKED_VENDOR  = 0x9245;\n    const UNMASKED_RENDERER = 0x9246;\n    const spoofVendor = 'Google Inc. (Intel)';\n    const spoofRenderer = 'ANGLE (Intel, Intel(R) Iris(TM) Plus Graphics, OpenGL 4.1)';\n    for (const Ctx of [WebGLRenderingContext, typeof WebGL2RenderingContext !== 'undefined' ? WebGL2RenderingContext : null].filter(Boolean)) {\n      const orig = Ctx.prototype.getParameter;\n      Ctx.prototype.getParameter = function(param) {\n        if (param === UNMASKED_VENDOR)  return spoofVendor;\n        if (param === UNMASKED_RENDERER) return spoofRenderer;\n        return orig.call(this, param);\n      };\n    }\n  } catch {}\n\n  // 7. Prevent iframe-based detection of navigator.webdriver\n  try {\n    const origCreate = Document.prototype.createElement;\n    Document.prototype.createElement = function(...args) {\n      const el = origCreate.apply(this, args);\n      if (el.nodeName === 'IFRAME') {\n        const origGet = Object.getOwnPropertyDescriptor(HTMLIFrameElement.prototype, 'contentWindow')?.get;\n        if (origGet) {\n          Object.defineProperty(el, 'contentWindow', {\n            get() {\n              const w = origGet.call(this);\n              if (w) {\n                try {\n                  Object.defineProperty(w.navigator, 'webdriver', { get: () => false, configurable: true });\n                } catch {}\n              }\n              return w;\n            },\n            configurable: true,\n          });\n        }\n      }\n      return el;\n    };\n  } catch {}\n})();\n";
+
+export { type BrowserConfig, type BrowserFrame, BrowserSession, type BrowserStatus, type BrowserStoragePersistence, type KeyboardInputEvent, type MouseInputEvent, STEALTH_ARGS, STEALTH_INIT_SCRIPT, type ScreencastOptions, type ScrollInputEvent, type ViewportOptions, buildStealthArgs, createBrowserTools, defaultUserAgent };

package/dist/index.js

@@ -1,7 +1,182 @@
 // src/session.ts
 import { resolve, join } from "path";
-import { homedir, tmpdir } from "os";
+import { homedir, tmpdir, platform as platform2 } from "os";
 import { mkdir, readFile, unlink } from "fs/promises";
+
+// src/stealth.ts
+import { platform } from "os";
+function defaultUserAgent() {
+  const chromeVersion = "145.0.7632.117";
+  const os = platform();
+  if (os === "darwin") {
+    return `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeVersion} Safari/537.36`;
+  }
+  if (os === "win32") {
+    return `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeVersion} Safari/537.36`;
+  }
+  return `Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeVersion} Safari/537.36`;
+}
+var STEALTH_ARGS = [
+  "--disable-blink-features=AutomationControlled",
+  "--enable-webgl",
+  "--use-gl=angle",
+  "--enable-features=VaapiVideoDecoder",
+  "--ignore-gpu-blocklist"
+];
+function buildStealthArgs(userAgent) {
+  return [...STEALTH_ARGS, `--user-agent=${userAgent}`];
+}
+var STEALTH_INIT_SCRIPT = `
+(() => {
+  // 1. navigator.webdriver \u2192 false
+  try {
+    Object.defineProperty(Navigator.prototype, 'webdriver', {
+      get: () => false,
+      configurable: true,
+    });
+  } catch {}
+
+  // 2. window.chrome stub (headless Chromium omits it)
+  try {
+    if (!window.chrome) {
+      const chrome = {
+        app: {
+          isInstalled: false,
+          InstallState: { DISABLED: 'disabled', INSTALLED: 'installed', NOT_INSTALLED: 'not_installed' },
+          RunningState: { CANNOT_RUN: 'cannot_run', READY_TO_RUN: 'ready_to_run', RUNNING: 'running' },
+          getDetails() { return null; },
+          getIsInstalled() { return false; },
+          installState() { return 'not_installed'; },
+        },
+        runtime: {
+          OnInstalledReason: { CHROME_UPDATE: 'chrome_update', INSTALL: 'install', SHARED_MODULE_UPDATE: 'shared_module_update', UPDATE: 'update' },
+          OnRestartRequiredReason: { APP_UPDATE: 'app_update', OS_UPDATE: 'os_update', PERIODIC: 'periodic' },
+          PlatformArch: { ARM: 'arm', ARM64: 'arm64', MIPS: 'mips', MIPS64: 'mips64', X86_32: 'x86-32', X86_64: 'x86-64' },
+          PlatformNaclArch: { ARM: 'arm', MIPS: 'mips', MIPS64: 'mips64', X86_32: 'x86-32', X86_64: 'x86-64' },
+          PlatformOs: { ANDROID: 'android', CROS: 'cros', FUCHSIA: 'fuchsia', LINUX: 'linux', MAC: 'mac', OPENBSD: 'openbsd', WIN: 'win' },
+          RequestUpdateCheckStatus: { NO_UPDATE: 'no_update', THROTTLED: 'throttled', UPDATE_AVAILABLE: 'update_available' },
+          connect() { return { onMessage: { addListener() {}, removeListener() {} }, postMessage() {}, disconnect() {} }; },
+          sendMessage() {},
+          id: undefined,
+        },
+        csi() { return {}; },
+        loadTimes() { return {}; },
+      };
+      Object.defineProperty(window, 'chrome', {
+        value: chrome,
+        writable: false,
+        enumerable: true,
+        configurable: false,
+      });
+    }
+  } catch {}
+
+  // 3. navigator.plugins \u2014 expose the plugins a real Chrome has
+  try {
+    const makeMimeType = (type, desc, suffixes, plugin) => {
+      const mt = Object.create(MimeType.prototype);
+      Object.defineProperties(mt, {
+        type: { get: () => type },
+        description: { get: () => desc },
+        suffixes: { get: () => suffixes },
+        enabledPlugin: { get: () => plugin },
+      });
+      return mt;
+    };
+    const fakePluginDefs = [
+      { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer', description: 'Portable Document Format', hasMime: true },
+      { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai', description: '', hasMime: false },
+      { name: 'Native Client', filename: 'internal-nacl-plugin', description: '', hasMime: false },
+    ];
+    const plugins = [];
+    for (const fp of fakePluginDefs) {
+      const p = Object.create(Plugin.prototype);
+      const mime = fp.hasMime ? makeMimeType('application/x-google-chrome-pdf', 'Portable Document Format', 'pdf', p) : null;
+      Object.defineProperties(p, {
+        name: { get: () => fp.name },
+        filename: { get: () => fp.filename },
+        description: { get: () => fp.description },
+        length: { get: () => mime ? 1 : 0 },
+      });
+      if (mime) Object.defineProperty(p, 0, { get: () => mime });
+      Object.defineProperty(p, 'item', { value: (i) => i === 0 && mime ? mime : null });
+      Object.defineProperty(p, 'namedItem', { value: (n) => mime && n === mime.type ? mime : null });
+      Object.defineProperty(p, Symbol.iterator, { value: function*() { if (mime) yield mime; } });
+      plugins.push(p);
+    }
+    const pluginArray = Object.create(PluginArray.prototype);
+    plugins.forEach((p, i) => Object.defineProperty(pluginArray, i, { get: () => p, enumerable: true }));
+    Object.defineProperty(pluginArray, 'length', { get: () => plugins.length });
+    Object.defineProperty(pluginArray, 'item', { value: (i) => plugins[i] ?? null });
+    Object.defineProperty(pluginArray, 'namedItem', { value: (n) => plugins.find(p => p.name === n) ?? null });
+    Object.defineProperty(pluginArray, 'refresh', { value: () => {} });
+    Object.defineProperty(pluginArray, Symbol.iterator, { value: function*() { for (const p of plugins) yield p; } });
+    Object.defineProperty(navigator, 'plugins', { get: () => pluginArray, configurable: true });
+  } catch {}
+
+  // 4. navigator.languages
+  try {
+    Object.defineProperty(navigator, 'languages', {
+      get: () => Object.freeze(['en-US', 'en']),
+      configurable: true,
+    });
+  } catch {}
+
+  // 5. Notification.permission \u2014 return "default" (headless returns "denied")
+  try {
+    if (typeof Notification !== 'undefined' && Notification.permission === 'denied') {
+      Object.defineProperty(Notification, 'permission', {
+        get: () => 'default',
+        configurable: true,
+      });
+    }
+  } catch {}
+
+  // 6. WebGL vendor/renderer \u2014 hide SwiftShader (headless giveaway)
+  try {
+    const UNMASKED_VENDOR  = 0x9245;
+    const UNMASKED_RENDERER = 0x9246;
+    const spoofVendor = 'Google Inc. (Intel)';
+    const spoofRenderer = 'ANGLE (Intel, Intel(R) Iris(TM) Plus Graphics, OpenGL 4.1)';
+    for (const Ctx of [WebGLRenderingContext, typeof WebGL2RenderingContext !== 'undefined' ? WebGL2RenderingContext : null].filter(Boolean)) {
+      const orig = Ctx.prototype.getParameter;
+      Ctx.prototype.getParameter = function(param) {
+        if (param === UNMASKED_VENDOR)  return spoofVendor;
+        if (param === UNMASKED_RENDERER) return spoofRenderer;
+        return orig.call(this, param);
+      };
+    }
+  } catch {}
+
+  // 7. Prevent iframe-based detection of navigator.webdriver
+  try {
+    const origCreate = Document.prototype.createElement;
+    Document.prototype.createElement = function(...args) {
+      const el = origCreate.apply(this, args);
+      if (el.nodeName === 'IFRAME') {
+        const origGet = Object.getOwnPropertyDescriptor(HTMLIFrameElement.prototype, 'contentWindow')?.get;
+        if (origGet) {
+          Object.defineProperty(el, 'contentWindow', {
+            get() {
+              const w = origGet.call(this);
+              if (w) {
+                try {
+                  Object.defineProperty(w.navigator, 'webdriver', { get: () => false, configurable: true });
+                } catch {}
+              }
+              return w;
+            },
+            configurable: true,
+          });
+        }
+      }
+      return el;
+    };
+  } catch {}
+})();
+`;
+
+// src/session.ts
 var BrowserManagerCtor;
 async function getBrowserManagerCtor() {
   if (!BrowserManagerCtor) {
@@ -11,12 +186,56 @@ async function getBrowserManagerCtor() {
   return BrowserManagerCtor;
 }
 var MAX_TABS = 8;
+var SAME_TAB_INIT_SCRIPT = `
+(() => {
+  // Override window.open to navigate in-place
+  try {
+    const origOpen = window.open;
+    window.open = function(url, target, features) {
+      if (url) {
+        location.href = url;
+        return window;
+      }
+      return origOpen.call(this, url, target, features);
+    };
+  } catch {}
+
+  // Rewrite target="_blank" on existing and future links
+  try {
+    const rewrite = (el) => {
+      if (el.tagName === 'A' && el.target === '_blank') {
+        el.target = '_self';
+      }
+    };
+    // Catch links already in the DOM
+    document.addEventListener('DOMContentLoaded', () => {
+      document.querySelectorAll('a[target="_blank"]').forEach(rewrite);
+    });
+    // Catch dynamically added links
+    new MutationObserver((mutations) => {
+      for (const m of mutations) {
+        for (const node of m.addedNodes) {
+          if (node.nodeType !== 1) continue;
+          rewrite(node);
+          if (node.querySelectorAll) {
+            node.querySelectorAll('a[target="_blank"]').forEach(rewrite);
+          }
+        }
+      }
+    }).observe(document.documentElement, { childList: true, subtree: true });
+  } catch {}
+})();
+`;
 var BrowserSession = class {
   config;
   sessionId;
   manager;
   // Tab management: conversationId → tab state
   tabs = /* @__PURE__ */ new Map();
+  // Whether context-level stealth init script has been installed
+  _contextStealthInstalled = false;
+  // Track which tabs have had per-page CDP UA override applied
+  _uaOverrideApplied = /* @__PURE__ */ new Set();
   // Serialization lock for tab-switching operations
   _lockQueue = [];
   _locked = false;
@@ -57,18 +276,95 @@ var BrowserSession = class {
   // -----------------------------------------------------------------------
   // Core browser + tab management
   // -----------------------------------------------------------------------
+  get stealthEnabled() {
+    return this.config.stealth !== false;
+  }
+  get stealthUserAgent() {
+    if (this.config.userAgent) return this.config.userAgent;
+    if (this.stealthEnabled) return defaultUserAgent();
+    return void 0;
+  }
+  /**
+   * Install the stealth init script on the Playwright BrowserContext.
+   * This runs before ALL page scripts on every navigation across every tab.
+   * Only needs to be called once per browser launch.
+   */
+  async installContextStealth(mgr) {
+    if (this._contextStealthInstalled) return;
+    const ctx = mgr.getContext();
+    if (!ctx) {
+      console.warn("[poncho][browser] Cannot install stealth: no browser context");
+      return;
+    }
+    try {
+      await ctx.addInitScript({ content: STEALTH_INIT_SCRIPT });
+      this._contextStealthInstalled = true;
+      console.log("[poncho][browser] Stealth init script installed on context");
+    } catch (err) {
+      console.warn("[poncho][browser] Failed to install stealth init script:", err?.message ?? err);
+    }
+  }
+  /**
+   * Force all new-tab navigations (window.open, target="_blank") to open
+   * in the current tab instead. Agents operate on a single tab at a time
+   * and can't see or interact with popups.
+   */
+  async installSameTabScript(mgr) {
+    const ctx = mgr.getContext();
+    if (!ctx) return;
+    try {
+      await ctx.addInitScript({ content: SAME_TAB_INIT_SCRIPT });
+    } catch (err) {
+      console.warn("[poncho][browser] Failed to install same-tab init script:", err?.message ?? err);
+    }
+  }
+  /**
+   * Override the user-agent via CDP on the current page target.
+   * CDP Network.setUserAgentOverride is per-target, so call per-tab.
+   */
+  async overrideUserAgentOnPage(mgr, conversationId) {
+    if (this._uaOverrideApplied.has(conversationId)) return;
+    const ua = this.stealthUserAgent;
+    if (!ua) return;
+    try {
+      const cdp = await mgr.getCDPSession();
+      await cdp.send("Network.setUserAgentOverride", {
+        userAgent: ua,
+        acceptLanguage: "en-US,en;q=0.9",
+        platform: platform2() === "darwin" ? "macOS" : platform2() === "win32" ? "Win32" : "Linux x86_64"
+      });
+      this._uaOverrideApplied.add(conversationId);
+    } catch (err) {
+      console.warn("[poncho][browser] Failed to override UA via CDP:", err?.message ?? err);
+    }
+  }
   async launchFreshManager() {
     const Ctor = await getBrowserManagerCtor();
     const mgr = new Ctor();
     const viewport = this.config.viewport ?? { width: 1280, height: 720 };
     await mkdir(this.profileDir, { recursive: true });
-    await mgr.launch({
+    const launchOpts = {
       action: "launch",
       headless: this.config.headless ?? true,
       viewport: { width: viewport.width ?? 1280, height: viewport.height ?? 720 },
       executablePath: this.config.executablePath,
       profile: this.profileDir
-    });
+    };
+    if (this.stealthEnabled) {
+      const ua = this.stealthUserAgent;
+      launchOpts.userAgent = ua;
+      launchOpts.args = buildStealthArgs(ua);
+      console.log("[poncho][browser] Launching with stealth mode enabled (UA: " + ua + ")");
+    } else if (this.config.userAgent) {
+      launchOpts.userAgent = this.config.userAgent;
+    }
+    await mgr.launch(launchOpts);
+    this._contextStealthInstalled = false;
+    this._uaOverrideApplied.clear();
+    if (this.stealthEnabled) {
+      await this.installContextStealth(mgr);
+    }
+    await this.installSameTabScript(mgr);
     try {
       const cdp = await mgr.getCDPSession();
       await cdp.send("Debugger.disable");
@@ -89,6 +385,8 @@ var BrowserSession = class {
       } catch {
       }
       this.manager = void 0;
+      this._contextStealthInstalled = false;
+      this._uaOverrideApplied.clear();
       for (const [cid, tab] of this.tabs) {
         if (tab.tabIndex >= 0) {
           tab.tabIndex = -1;
@@ -129,6 +427,7 @@ var BrowserSession = class {
     oldest.tab.url = void 0;
     this.emitStatus(oldest.cid);
     this.tabs.delete(oldest.cid);
+    this._uaOverrideApplied.delete(oldest.cid);
   }
   /** Reconcile tab indices with the manager's actual page list. */
   async reconcileTabs(mgr) {
@@ -208,6 +507,8 @@ var BrowserSession = class {
         } catch {
         }
         this.manager = void 0;
+        this._contextStealthInstalled = false;
+        this._uaOverrideApplied.clear();
         for (const [, t] of this.tabs) {
           if (t.tabIndex >= 0) {
             t.tabIndex = -1;
@@ -225,6 +526,10 @@ var BrowserSession = class {
   async _doOpen(conversationId, url) {
     const mgr = await this.ensureManager();
     const tab = await this.switchToConversation(mgr, conversationId);
+    if (this.stealthEnabled) {
+      await this.installContextStealth(mgr);
+      await this.overrideUserAgentOnPage(mgr, conversationId);
+    }
     const page = mgr.getPage();
     await page.goto(url, { waitUntil: "domcontentloaded", timeout: 3e4 });
     tab.url = page.url();
@@ -308,6 +613,30 @@ var BrowserSession = class {
       this.unlock();
     }
   }
+  async clickText(conversationId, text, exact) {
+    await this.lock();
+    try {
+      const mgr = await this.ensureManager();
+      const tab = await this.switchToConversation(mgr, conversationId);
+      const selector = exact ? `text="${text}"` : `text=${text}`;
+      const locator = mgr.getLocator(selector);
+      await locator.click();
+      tab.url = mgr.getPage().url();
+    } finally {
+      this.unlock();
+    }
+  }
+  async executeJs(conversationId, script) {
+    await this.lock();
+    try {
+      const mgr = await this.ensureManager();
+      await this.switchToConversation(mgr, conversationId);
+      const page = mgr.getPage();
+      return await page.evaluate(script);
+    } finally {
+      this.unlock();
+    }
+  }
   async closeTab(conversationId) {
     await this.lock();
     try {
@@ -341,6 +670,7 @@ var BrowserSession = class {
       tab.url = void 0;
       this.emitStatus(conversationId);
       this.tabs.delete(conversationId);
+      this._uaOverrideApplied.delete(conversationId);
     } finally {
       this.unlock();
     }
@@ -564,6 +894,8 @@ var BrowserSession = class {
     } catch {
     }
     this.manager = void 0;
+    this._contextStealthInstalled = false;
+    this._uaOverrideApplied.clear();
     for (const [cid, tab] of this.tabs) {
       tab.active = false;
       tab.url = void 0;
@@ -654,6 +986,53 @@ function createBrowserTools(getSession, getConversationId) {
         return { clicked: ref };
       }
     },
+    {
+      name: "browser_click_text",
+      description: "Click the first visible element on the page that contains the given text. Use this when an element doesn't appear in the snapshot \u2014 e.g. styled divs acting as buttons. By default matches substring (case-insensitive); set exact=true for exact text match.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          text: {
+            type: "string",
+            description: "The visible text of the element to click"
+          },
+          exact: {
+            type: "boolean",
+            description: "If true, match the exact full text (case-sensitive). Default: false (substring, case-insensitive)."
+          }
+        },
+        required: ["text"]
+      },
+      handler: async (input) => {
+        const session = getSession();
+        const text = String(input.text ?? "");
+        if (!text) throw new Error("text is required");
+        const exact = input.exact === true;
+        await session.clickText(getConversationId(), text, exact);
+        return { clicked: text, exact };
+      }
+    },
+    {
+      name: "browser_execute_js",
+      description: "Execute JavaScript in the current page context and return the result. Use this to inspect or interact with the DOM when snapshot refs aren't available \u2014 e.g. finding elements by text content, getting bounding boxes, or clicking elements by selector. The script is evaluated via page.evaluate(); return a value to get it back.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          script: {
+            type: "string",
+            description: "JavaScript code to evaluate in the page. Use a return statement or expression to get a result back."
+          }
+        },
+        required: ["script"]
+      },
+      handler: async (input) => {
+        const session = getSession();
+        const script = String(input.script ?? "");
+        if (!script) throw new Error("script is required");
+        const result = await session.executeJs(getConversationId(), script);
+        return { result: result ?? null };
+      }
+    },
     {
       name: "browser_type",
       description: "Type text into a form field identified by its ref from the last snapshot. This clears the field first, then types the new value.",
@@ -755,5 +1134,9 @@ function createBrowserTools(getSession, getConversationId) {
 }
 export {
   BrowserSession,
-  createBrowserTools
+  STEALTH_ARGS,
+  STEALTH_INIT_SCRIPT,
+  buildStealthArgs,
+  createBrowserTools,
+  defaultUserAgent
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/browser",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "description": "Browser automation for Poncho agents, powered by agent-browser",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -1,5 +1,6 @@
 export { BrowserSession } from "./session.js";
 export { createBrowserTools } from "./tools.js";
+export { defaultUserAgent, STEALTH_ARGS, buildStealthArgs, STEALTH_INIT_SCRIPT } from "./stealth.js";
 export type {
   BrowserConfig,
   BrowserFrame,

package/src/session.ts

@@ -1,5 +1,5 @@
 import { resolve, join } from "node:path";
-import { homedir, tmpdir } from "node:os";
+import { homedir, tmpdir, platform } from "node:os";
 import { mkdir, readFile, unlink } from "node:fs/promises";
 import type {
   BrowserConfig,
@@ -10,16 +10,26 @@ import type {
   KeyboardInputEvent,
   ScrollInputEvent,
 } from "./types.js";
+import { defaultUserAgent, buildStealthArgs, STEALTH_INIT_SCRIPT } from "./stealth.js";
 
 type FrameListener = (frame: BrowserFrame) => void;
 type StatusListener = (status: BrowserStatus) => void;
 
 let BrowserManagerCtor: (new () => BrowserManagerInstance) | undefined;
 
+interface CDPSessionHandle {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+interface BrowserContextHandle {
+  addInitScript(script: string | { path?: string; content?: string }): Promise<void>;
+}
+
 interface BrowserManagerInstance {
   isLaunched(): boolean;
   launch(options: Record<string, unknown>): Promise<void>;
   getPage(): { url(): string; title(): Promise<string>; screenshot(opts?: Record<string, unknown>): Promise<Buffer>; goBack(): Promise<unknown>; goForward(): Promise<unknown>; evaluate(fn: string | (() => unknown)): Promise<unknown> };
+  getContext(): BrowserContextHandle | null;
   getSnapshot(options?: { interactive?: boolean; compact?: boolean }): Promise<{ tree: string; refs: Record<string, unknown> }>;
   getLocatorFromRef(ref: string): { click(): Promise<void> } | null;
   getLocator(selector: string): { fill(text: string): Promise<void>; click(): Promise<void> };
@@ -36,7 +46,7 @@ interface BrowserManagerInstance {
   isScreencasting(): boolean;
   injectMouseEvent(params: Record<string, unknown>): Promise<void>;
   injectKeyboardEvent(params: Record<string, unknown>): Promise<void>;
-  getCDPSession(): Promise<{ send(method: string, params?: Record<string, unknown>): Promise<unknown> }>;
+  getCDPSession(): Promise<CDPSessionHandle>;
   saveStorageState(path: string): Promise<void>;
   close(): Promise<void>;
   setViewport(width: number, height: number): Promise<void>;
@@ -52,6 +62,51 @@ async function getBrowserManagerCtor(): Promise<new () => BrowserManagerInstance
 
 const MAX_TABS = 8;
 
+/**
+ * Init script that forces new-tab navigations (window.open, target="_blank")
+ * to open in the current tab. Runs before page scripts on every navigation.
+ */
+const SAME_TAB_INIT_SCRIPT = `
+(() => {
+  // Override window.open to navigate in-place
+  try {
+    const origOpen = window.open;
+    window.open = function(url, target, features) {
+      if (url) {
+        location.href = url;
+        return window;
+      }
+      return origOpen.call(this, url, target, features);
+    };
+  } catch {}
+
+  // Rewrite target="_blank" on existing and future links
+  try {
+    const rewrite = (el) => {
+      if (el.tagName === 'A' && el.target === '_blank') {
+        el.target = '_self';
+      }
+    };
+    // Catch links already in the DOM
+    document.addEventListener('DOMContentLoaded', () => {
+      document.querySelectorAll('a[target="_blank"]').forEach(rewrite);
+    });
+    // Catch dynamically added links
+    new MutationObserver((mutations) => {
+      for (const m of mutations) {
+        for (const node of m.addedNodes) {
+          if (node.nodeType !== 1) continue;
+          rewrite(node);
+          if (node.querySelectorAll) {
+            node.querySelectorAll('a[target="_blank"]').forEach(rewrite);
+          }
+        }
+      }
+    }).observe(document.documentElement, { childList: true, subtree: true });
+  } catch {}
+})();
+`;
+
 // Per-conversation tab state
 interface ConversationTab {
   tabIndex: number;
@@ -70,6 +125,12 @@ export class BrowserSession {
   // Tab management: conversationId → tab state
   private readonly tabs = new Map<string, ConversationTab>();
 
+  // Whether context-level stealth init script has been installed
+  private _contextStealthInstalled = false;
+
+  // Track which tabs have had per-page CDP UA override applied
+  private readonly _uaOverrideApplied = new Set<string>();
+
   // Serialization lock for tab-switching operations
   private _lockQueue: Array<() => void> = [];
   private _locked = false;
@@ -116,6 +177,73 @@ export class BrowserSession {
   // Core browser + tab management
   // -----------------------------------------------------------------------
 
+  private get stealthEnabled(): boolean {
+    return this.config.stealth !== false;
+  }
+
+  private get stealthUserAgent(): string | undefined {
+    if (this.config.userAgent) return this.config.userAgent;
+    if (this.stealthEnabled) return defaultUserAgent();
+    return undefined;
+  }
+
+  /**
+   * Install the stealth init script on the Playwright BrowserContext.
+   * This runs before ALL page scripts on every navigation across every tab.
+   * Only needs to be called once per browser launch.
+   */
+  private async installContextStealth(mgr: BrowserManagerInstance): Promise<void> {
+    if (this._contextStealthInstalled) return;
+    const ctx = mgr.getContext();
+    if (!ctx) {
+      console.warn("[poncho][browser] Cannot install stealth: no browser context");
+      return;
+    }
+    try {
+      await ctx.addInitScript({ content: STEALTH_INIT_SCRIPT });
+      this._contextStealthInstalled = true;
+      console.log("[poncho][browser] Stealth init script installed on context");
+    } catch (err) {
+      console.warn("[poncho][browser] Failed to install stealth init script:", (err as Error)?.message ?? err);
+    }
+  }
+
+  /**
+   * Force all new-tab navigations (window.open, target="_blank") to open
+   * in the current tab instead. Agents operate on a single tab at a time
+   * and can't see or interact with popups.
+   */
+  private async installSameTabScript(mgr: BrowserManagerInstance): Promise<void> {
+    const ctx = mgr.getContext();
+    if (!ctx) return;
+    try {
+      await ctx.addInitScript({ content: SAME_TAB_INIT_SCRIPT });
+    } catch (err) {
+      console.warn("[poncho][browser] Failed to install same-tab init script:", (err as Error)?.message ?? err);
+    }
+  }
+
+  /**
+   * Override the user-agent via CDP on the current page target.
+   * CDP Network.setUserAgentOverride is per-target, so call per-tab.
+   */
+  private async overrideUserAgentOnPage(mgr: BrowserManagerInstance, conversationId: string): Promise<void> {
+    if (this._uaOverrideApplied.has(conversationId)) return;
+    const ua = this.stealthUserAgent;
+    if (!ua) return;
+    try {
+      const cdp = await mgr.getCDPSession();
+      await cdp.send("Network.setUserAgentOverride", {
+        userAgent: ua,
+        acceptLanguage: "en-US,en;q=0.9",
+        platform: platform() === "darwin" ? "macOS" : platform() === "win32" ? "Win32" : "Linux x86_64",
+      });
+      this._uaOverrideApplied.add(conversationId);
+    } catch (err) {
+      console.warn("[poncho][browser] Failed to override UA via CDP:", (err as Error)?.message ?? err);
+    }
+  }
+
   private async launchFreshManager(): Promise<BrowserManagerInstance> {
     const Ctor = await getBrowserManagerCtor();
     const mgr = new Ctor();
@@ -123,13 +251,36 @@ export class BrowserSession {
     const viewport = this.config.viewport ?? { width: 1280, height: 720 };
     await mkdir(this.profileDir, { recursive: true });
 
-    await mgr.launch({
+    const launchOpts: Record<string, unknown> = {
       action: "launch",
       headless: this.config.headless ?? true,
       viewport: { width: viewport.width ?? 1280, height: viewport.height ?? 720 },
       executablePath: this.config.executablePath,
       profile: this.profileDir,
-    });
+    };
+
+    if (this.stealthEnabled) {
+      const ua = this.stealthUserAgent!;
+      launchOpts.userAgent = ua;
+      launchOpts.args = buildStealthArgs(ua);
+      console.log("[poncho][browser] Launching with stealth mode enabled (UA: " + ua + ")");
+    } else if (this.config.userAgent) {
+      launchOpts.userAgent = this.config.userAgent;
+    }
+
+    await mgr.launch(launchOpts as Parameters<BrowserManagerInstance["launch"]>[0]);
+
+    // Reset stealth tracking for fresh browser
+    this._contextStealthInstalled = false;
+    this._uaOverrideApplied.clear();
+
+    // Install context-level stealth (covers all tabs, all navigations)
+    if (this.stealthEnabled) {
+      await this.installContextStealth(mgr);
+    }
+
+    // Redirect new-tab navigations into the current tab
+    await this.installSameTabScript(mgr);
 
     try {
       const cdp = await mgr.getCDPSession();
@@ -149,6 +300,8 @@ export class BrowserSession {
       // Manager exists but is dead/stale -- discard it
       try { await this.manager.close(); } catch { /* */ }
       this.manager = undefined;
+      this._contextStealthInstalled = false;
+      this._uaOverrideApplied.clear();
       // Clear tab state since they belonged to the dead browser
       for (const [cid, tab] of this.tabs) {
         if (tab.tabIndex >= 0) {
@@ -186,6 +339,7 @@ export class BrowserSession {
     oldest.tab.url = undefined;
     this.emitStatus(oldest.cid);
     this.tabs.delete(oldest.cid);
+    this._uaOverrideApplied.delete(oldest.cid);
   }
 
   /** Reconcile tab indices with the manager's actual page list. */
@@ -267,6 +421,8 @@ export class BrowserSession {
         console.log("[poncho][browser] Browser died mid-open, relaunching...");
         try { await this.manager?.close(); } catch { /* */ }
         this.manager = undefined;
+        this._contextStealthInstalled = false;
+        this._uaOverrideApplied.clear();
         for (const [, t] of this.tabs) {
           if (t.tabIndex >= 0) { t.tabIndex = -1; t.active = false; t.url = undefined; }
         }
@@ -281,6 +437,13 @@ export class BrowserSession {
   private async _doOpen(conversationId: string, url: string): Promise<{ title?: string }> {
     const mgr = await this.ensureManager();
     const tab = await this.switchToConversation(mgr, conversationId);
+
+    // Ensure context-level stealth is installed (covers reused managers too)
+    if (this.stealthEnabled) {
+      await this.installContextStealth(mgr);
+      await this.overrideUserAgentOnPage(mgr, conversationId);
+    }
+
     const page = mgr.getPage();
 
     await (page as unknown as { goto(url: string, opts?: Record<string, unknown>): Promise<unknown> })
@@ -375,6 +538,32 @@ export class BrowserSession {
     }
   }
 
+  async clickText(conversationId: string, text: string, exact?: boolean): Promise<void> {
+    await this.lock();
+    try {
+      const mgr = await this.ensureManager();
+      const tab = await this.switchToConversation(mgr, conversationId);
+      const selector = exact ? `text="${text}"` : `text=${text}`;
+      const locator = mgr.getLocator(selector);
+      await locator.click();
+      tab.url = mgr.getPage().url();
+    } finally {
+      this.unlock();
+    }
+  }
+
+  async executeJs(conversationId: string, script: string): Promise<unknown> {
+    await this.lock();
+    try {
+      const mgr = await this.ensureManager();
+      await this.switchToConversation(mgr, conversationId);
+      const page = mgr.getPage();
+      return await page.evaluate(script);
+    } finally {
+      this.unlock();
+    }
+  }
+
   async closeTab(conversationId: string): Promise<void> {
     await this.lock();
     try {
@@ -402,6 +591,7 @@ export class BrowserSession {
       tab.url = undefined;
       this.emitStatus(conversationId);
       this.tabs.delete(conversationId);
+      this._uaOverrideApplied.delete(conversationId);
     } finally {
       this.unlock();
     }
@@ -632,6 +822,8 @@ export class BrowserSession {
     await this.persistStorageState();
     try { await this.manager?.close(); } catch { /* */ }
     this.manager = undefined;
+    this._contextStealthInstalled = false;
+    this._uaOverrideApplied.clear();
     for (const [cid, tab] of this.tabs) {
       tab.active = false;
       tab.url = undefined;

package/src/stealth.ts

@@ -0,0 +1,195 @@
+import { platform } from "node:os";
+
+/**
+ * Returns a realistic Chrome user-agent string for the host OS.
+ * Uses a recent stable Chrome version to blend in with normal traffic.
+ */
+export function defaultUserAgent(): string {
+  const chromeVersion = "145.0.7632.117";
+  const os = platform();
+
+  if (os === "darwin") {
+    return `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeVersion} Safari/537.36`;
+  }
+
+  if (os === "win32") {
+    return `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeVersion} Safari/537.36`;
+  }
+
+  return `Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeVersion} Safari/537.36`;
+}
+
+/**
+ * Static Chromium flags that suppress automation fingerprints.
+ */
+export const STEALTH_ARGS: string[] = [
+  "--disable-blink-features=AutomationControlled",
+  "--enable-webgl",
+  "--use-gl=angle",
+  "--enable-features=VaapiVideoDecoder",
+  "--ignore-gpu-blocklist",
+];
+
+/**
+ * Build the full stealth args array including the browser-level user-agent
+ * override. The `--user-agent` flag sets the UA globally — including in
+ * Web Workers and Service Workers — which context-level overrides can't reach.
+ */
+export function buildStealthArgs(userAgent: string): string[] {
+  return [...STEALTH_ARGS, `--user-agent=${userAgent}`];
+}
+
+/**
+ * JS source injected via Playwright context.addInitScript().
+ * Runs before ALL page scripts on every navigation, every tab.
+ * Each section has its own try/catch so one failure doesn't block the rest.
+ */
+export const STEALTH_INIT_SCRIPT = `
+(() => {
+  // 1. navigator.webdriver → false
+  try {
+    Object.defineProperty(Navigator.prototype, 'webdriver', {
+      get: () => false,
+      configurable: true,
+    });
+  } catch {}
+
+  // 2. window.chrome stub (headless Chromium omits it)
+  try {
+    if (!window.chrome) {
+      const chrome = {
+        app: {
+          isInstalled: false,
+          InstallState: { DISABLED: 'disabled', INSTALLED: 'installed', NOT_INSTALLED: 'not_installed' },
+          RunningState: { CANNOT_RUN: 'cannot_run', READY_TO_RUN: 'ready_to_run', RUNNING: 'running' },
+          getDetails() { return null; },
+          getIsInstalled() { return false; },
+          installState() { return 'not_installed'; },
+        },
+        runtime: {
+          OnInstalledReason: { CHROME_UPDATE: 'chrome_update', INSTALL: 'install', SHARED_MODULE_UPDATE: 'shared_module_update', UPDATE: 'update' },
+          OnRestartRequiredReason: { APP_UPDATE: 'app_update', OS_UPDATE: 'os_update', PERIODIC: 'periodic' },
+          PlatformArch: { ARM: 'arm', ARM64: 'arm64', MIPS: 'mips', MIPS64: 'mips64', X86_32: 'x86-32', X86_64: 'x86-64' },
+          PlatformNaclArch: { ARM: 'arm', MIPS: 'mips', MIPS64: 'mips64', X86_32: 'x86-32', X86_64: 'x86-64' },
+          PlatformOs: { ANDROID: 'android', CROS: 'cros', FUCHSIA: 'fuchsia', LINUX: 'linux', MAC: 'mac', OPENBSD: 'openbsd', WIN: 'win' },
+          RequestUpdateCheckStatus: { NO_UPDATE: 'no_update', THROTTLED: 'throttled', UPDATE_AVAILABLE: 'update_available' },
+          connect() { return { onMessage: { addListener() {}, removeListener() {} }, postMessage() {}, disconnect() {} }; },
+          sendMessage() {},
+          id: undefined,
+        },
+        csi() { return {}; },
+        loadTimes() { return {}; },
+      };
+      Object.defineProperty(window, 'chrome', {
+        value: chrome,
+        writable: false,
+        enumerable: true,
+        configurable: false,
+      });
+    }
+  } catch {}
+
+  // 3. navigator.plugins — expose the plugins a real Chrome has
+  try {
+    const makeMimeType = (type, desc, suffixes, plugin) => {
+      const mt = Object.create(MimeType.prototype);
+      Object.defineProperties(mt, {
+        type: { get: () => type },
+        description: { get: () => desc },
+        suffixes: { get: () => suffixes },
+        enabledPlugin: { get: () => plugin },
+      });
+      return mt;
+    };
+    const fakePluginDefs = [
+      { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer', description: 'Portable Document Format', hasMime: true },
+      { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai', description: '', hasMime: false },
+      { name: 'Native Client', filename: 'internal-nacl-plugin', description: '', hasMime: false },
+    ];
+    const plugins = [];
+    for (const fp of fakePluginDefs) {
+      const p = Object.create(Plugin.prototype);
+      const mime = fp.hasMime ? makeMimeType('application/x-google-chrome-pdf', 'Portable Document Format', 'pdf', p) : null;
+      Object.defineProperties(p, {
+        name: { get: () => fp.name },
+        filename: { get: () => fp.filename },
+        description: { get: () => fp.description },
+        length: { get: () => mime ? 1 : 0 },
+      });
+      if (mime) Object.defineProperty(p, 0, { get: () => mime });
+      Object.defineProperty(p, 'item', { value: (i) => i === 0 && mime ? mime : null });
+      Object.defineProperty(p, 'namedItem', { value: (n) => mime && n === mime.type ? mime : null });
+      Object.defineProperty(p, Symbol.iterator, { value: function*() { if (mime) yield mime; } });
+      plugins.push(p);
+    }
+    const pluginArray = Object.create(PluginArray.prototype);
+    plugins.forEach((p, i) => Object.defineProperty(pluginArray, i, { get: () => p, enumerable: true }));
+    Object.defineProperty(pluginArray, 'length', { get: () => plugins.length });
+    Object.defineProperty(pluginArray, 'item', { value: (i) => plugins[i] ?? null });
+    Object.defineProperty(pluginArray, 'namedItem', { value: (n) => plugins.find(p => p.name === n) ?? null });
+    Object.defineProperty(pluginArray, 'refresh', { value: () => {} });
+    Object.defineProperty(pluginArray, Symbol.iterator, { value: function*() { for (const p of plugins) yield p; } });
+    Object.defineProperty(navigator, 'plugins', { get: () => pluginArray, configurable: true });
+  } catch {}
+
+  // 4. navigator.languages
+  try {
+    Object.defineProperty(navigator, 'languages', {
+      get: () => Object.freeze(['en-US', 'en']),
+      configurable: true,
+    });
+  } catch {}
+
+  // 5. Notification.permission — return "default" (headless returns "denied")
+  try {
+    if (typeof Notification !== 'undefined' && Notification.permission === 'denied') {
+      Object.defineProperty(Notification, 'permission', {
+        get: () => 'default',
+        configurable: true,
+      });
+    }
+  } catch {}
+
+  // 6. WebGL vendor/renderer — hide SwiftShader (headless giveaway)
+  try {
+    const UNMASKED_VENDOR  = 0x9245;
+    const UNMASKED_RENDERER = 0x9246;
+    const spoofVendor = 'Google Inc. (Intel)';
+    const spoofRenderer = 'ANGLE (Intel, Intel(R) Iris(TM) Plus Graphics, OpenGL 4.1)';
+    for (const Ctx of [WebGLRenderingContext, typeof WebGL2RenderingContext !== 'undefined' ? WebGL2RenderingContext : null].filter(Boolean)) {
+      const orig = Ctx.prototype.getParameter;
+      Ctx.prototype.getParameter = function(param) {
+        if (param === UNMASKED_VENDOR)  return spoofVendor;
+        if (param === UNMASKED_RENDERER) return spoofRenderer;
+        return orig.call(this, param);
+      };
+    }
+  } catch {}
+
+  // 7. Prevent iframe-based detection of navigator.webdriver
+  try {
+    const origCreate = Document.prototype.createElement;
+    Document.prototype.createElement = function(...args) {
+      const el = origCreate.apply(this, args);
+      if (el.nodeName === 'IFRAME') {
+        const origGet = Object.getOwnPropertyDescriptor(HTMLIFrameElement.prototype, 'contentWindow')?.get;
+        if (origGet) {
+          Object.defineProperty(el, 'contentWindow', {
+            get() {
+              const w = origGet.call(this);
+              if (w) {
+                try {
+                  Object.defineProperty(w.navigator, 'webdriver', { get: () => false, configurable: true });
+                } catch {}
+              }
+              return w;
+            },
+            configurable: true,
+          });
+        }
+      }
+      return el;
+    };
+  } catch {}
+})();
+`;

package/src/tools.ts

@@ -73,6 +73,62 @@ export function createBrowserTools(
         return { clicked: ref };
       },
     },
+    {
+      name: "browser_click_text",
+      description:
+        "Click the first visible element on the page that contains the given text. " +
+        "Use this when an element doesn't appear in the snapshot — e.g. styled divs acting as buttons. " +
+        "By default matches substring (case-insensitive); set exact=true for exact text match.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          text: {
+            type: "string",
+            description: "The visible text of the element to click",
+          },
+          exact: {
+            type: "boolean",
+            description:
+              "If true, match the exact full text (case-sensitive). Default: false (substring, case-insensitive).",
+          },
+        },
+        required: ["text"],
+      },
+      handler: async (input: BrowserToolInput) => {
+        const session = getSession();
+        const text = String(input.text ?? "");
+        if (!text) throw new Error("text is required");
+        const exact = input.exact === true;
+        await session.clickText(getConversationId(), text, exact);
+        return { clicked: text, exact };
+      },
+    },
+    {
+      name: "browser_execute_js",
+      description:
+        "Execute JavaScript in the current page context and return the result. " +
+        "Use this to inspect or interact with the DOM when snapshot refs aren't available — " +
+        "e.g. finding elements by text content, getting bounding boxes, or clicking elements by selector. " +
+        "The script is evaluated via page.evaluate(); return a value to get it back.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          script: {
+            type: "string",
+            description:
+              "JavaScript code to evaluate in the page. Use a return statement or expression to get a result back.",
+          },
+        },
+        required: ["script"],
+      },
+      handler: async (input: BrowserToolInput) => {
+        const session = getSession();
+        const script = String(input.script ?? "");
+        if (!script) throw new Error("script is required");
+        const result = await session.executeJs(getConversationId(), script);
+        return { result: result ?? null };
+      },
+    },
     {
       name: "browser_type",
       description:

package/src/types.ts

@@ -62,5 +62,12 @@ export interface BrowserConfig {
   sessionName?: string;
   executablePath?: string;
   headless?: boolean;
+  /** Custom user-agent string. When `stealth` is enabled a realistic Chrome UA
+   *  is used by default — set this to override it. */
+  userAgent?: string;
+  /** Reduce bot-detection fingerprints. Defaults to `true`.
+   *  Patches navigator.webdriver, injects window.chrome shim, sets a realistic
+   *  user-agent, and passes anti-automation Chrome flags. */
+  stealth?: boolean;
   storagePersistence?: BrowserStoragePersistence;
 }