@poncho-ai/browser 0.3.4 → 0.4.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 /home/runner/work/poncho-ai/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 62ms
 DTS Build start
-DTS ⚡️ Build success in 3120ms
-DTS dist/index.d.ts 4.13 KB
+DTS ⚡️ Build success in 4777ms
+DTS dist/index.d.ts 12.44 KB

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @poncho-ai/browser
 
+## 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,19 @@ 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;
+    /**
+     * 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;
@@ -119,4 +141,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) {
@@ -17,6 +192,10 @@ var BrowserSession = class {
   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 +236,80 @@ 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);
+    }
+  }
+  /**
+   * 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);
+    }
     try {
       const cdp = await mgr.getCDPSession();
       await cdp.send("Debugger.disable");
@@ -89,6 +330,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 +372,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 +452,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 +471,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();
@@ -341,6 +591,7 @@ var BrowserSession = class {
       tab.url = void 0;
       this.emitStatus(conversationId);
       this.tabs.delete(conversationId);
+      this._uaOverrideApplied.delete(conversationId);
     } finally {
       this.unlock();
     }
@@ -564,6 +815,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;
@@ -755,5 +1008,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.4.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>;
@@ -70,6 +80,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 +132,58 @@ 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);
+    }
+  }
+
+  /**
+   * 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 +191,33 @@ 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);
+    }
 
     try {
       const cdp = await mgr.getCDPSession();
@@ -149,6 +237,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 +276,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 +358,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 +374,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> })
@@ -402,6 +502,7 @@ export class BrowserSession {
       tab.url = undefined;
       this.emitStatus(conversationId);
       this.tabs.delete(conversationId);
+      this._uaOverrideApplied.delete(conversationId);
     } finally {
       this.unlock();
     }
@@ -632,6 +733,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/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;
 }

package/.turbo/turbo-test.log

@@ -1,12 +0,0 @@
-
-> @poncho-ai/browser@0.3.0 test /Users/cesar/Dev/latitude/poncho-ai/packages/browser
-> vitest --passWithNoTests
-
-
- RUN  v1.6.1 /Users/cesar/Dev/latitude/poncho-ai/packages/browser
-
-include: **/*.{test,spec}.?(c|m)[jt]s?(x)
-exclude:  **/node_modules/**, **/dist/**, **/cypress/**, **/.{idea,git,cache,output,temp}/**, **/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*
-watch exclude:  **/node_modules/**, **/dist/**
-No test files found, exiting with code 0
-