leapfrog-mcp 0.6.1 → 0.6.2

package/README.md

@@ -6,7 +6,7 @@
 <p align="center"><strong>Multi-session browser MCP for AI agents.</strong><br/>36 tools. 15 parallel sessions. Stealth. HUD. Self-improvement. Up to 10x fewer tokens.</p>
 
 <p align="center">
-<code>npm i leapfrog</code>&nbsp;&nbsp;|&nbsp;&nbsp;Works with Claude Code, Cursor, Windsurf
+<code>npm i leapfrog-mcp</code>&nbsp;&nbsp;|&nbsp;&nbsp;Works with Claude Code, Cursor, Windsurf
 </p>
 
 ---
@@ -33,9 +33,9 @@ Savings range from 2-10x depending on page complexity. Content-heavy pages see t
 ## Quick Start
 
 ```bash
-npx leapfrog --doctor          # verify everything works
-npx leapfrog --stealth-audit   # test all 19 stealth patches
-npx leapfrog --config          # print MCP config to paste
+npx leapfrog-mcp --doctor          # verify everything works
+npx leapfrog-mcp --stealth-audit   # test all 19 stealth patches
+npx leapfrog-mcp --config          # print MCP config to paste
 ```
 
 Add to `~/.mcp.json` (Claude Code) or your editor's MCP config:
@@ -44,12 +44,11 @@ Add to `~/.mcp.json` (Claude Code) or your editor's MCP config:
 {
   "leapfrog": {
     "command": "npx",
-    "args": ["-y", "leapfrog"],
+    "args": ["-y", "leapfrog-mcp"],
     "env": {
       "LEAP_MAX_SESSIONS": "15",
       "LEAP_TILE": "true",
       "LEAP_HUD": "true",
-      "LEAP_SOUND": "true",
       "LEAP_AUTO_CONSENT": "true"
     }
   }
@@ -57,8 +56,9 @@ Add to `~/.mcp.json` (Claude Code) or your editor's MCP config:
 ```
 
 Leapfrog uses `playwright-core` (15MB) instead of `playwright` (1.6GB) and does **not** bundle a browser. Either:
-- Set `LEAP_CHANNEL=chrome` to use your installed Chrome/Chromium
+- Set `LEAP_CHANNEL=chrome` to use your installed Chrome/Chromium (recommended)
 - Or run `npx playwright-core install chromium` to install the bundled Chromium binary
+- Or set `LEAP_CDP_ENDPOINT` to connect to an already-running Chrome instance
 
 ## Feature Matrix
 
@@ -94,7 +94,14 @@ Leapfrog uses `playwright-core` (15MB) instead of `playwright` (1.6GB) and does
 
 ## Stealth
 
-Leapfrog ships 19 anti-detection patches enabled by default (`LEAP_STEALTH=true`). These cover the vectors that fingerprint services like CreepJS and fingerprint-pro actually check:
+Leapfrog ships 19 anti-detection patches enabled by default (`LEAP_STEALTH=true`). Four modes:
+
+- **`true`** (default) — all 19 patches active
+- **`passive`** — removes automation signals only (webdriver, HeadlessChrome). Does NOT fake identity (WebGL, fonts, audio). Better for sites where trust matters more than evasion.
+- **`auto`** — per-domain EXP3 bandit selects the optimal stealth configuration based on what's worked before
+- **`false`** — no stealth patches
+
+These cover the vectors that fingerprint services like CreepJS and fingerprint-pro actually check:
 
 - Client Hints brands (strips HeadlessChrome)
 - `navigator.webdriver` forced to `undefined`
@@ -231,7 +238,7 @@ Leapfrog learns from every visit. Per-domain knowledge persists at `~/.leapfrog/
 | 6 | **Selector healing** | Remembers element fingerprints → selectors, heals broken refs across visits |
 | 7 | **API endpoint caching** | Discovered API endpoints persist across sessions |
 | 8 | **Interaction heat maps** | Tracks which elements agents actually use, suppresses untouched elements _(coming)_ |
-| 9 | **Strategy selection** | Adversarial bandit (EXP3) for stealth config optimization _(coming)_ |
+| 9 | **Strategy selection** | Adversarial bandit (EXP3) for stealth config optimization. Use `LEAP_STEALTH=auto` to enable. |
 
 LRU eviction at 500 domains. Inspect with the `domain_knowledge` tool.
 
@@ -323,23 +330,29 @@ Leapfrog uses pond metaphors to keep things memorable. Your agent is the frog.
 | `LEAP_MAX_SESSIONS` | `15` | Max concurrent sessions |
 | `LEAP_IDLE_TIMEOUT` | `1800000` | Session idle timeout in ms (30 min). Set `0` to disable. |
 | `LEAP_HEADLESS` | `true` | Set `false` to watch the browser |
+| `LEAP_HEADED` | `false` | Set `true` to watch the browser (positive alternative to `LEAP_HEADLESS`) |
 | `LEAP_CHANNEL` | _(bundled chromium)_ | Set `chrome` to use your installed Chrome |
+| `LEAP_CDP_ENDPOINT` | _(none)_ | Connect to a running Chrome instance (e.g. `http://localhost:9222`) |
+| `LEAP_EXTENSIONS` | _(none)_ | Comma-separated paths to browser extensions to load |
 | `LEAP_ALLOW_JS` | `true` | Allow JS evaluation in `extract` and `wait_for` |
-| `LEAP_STEALTH` | `true` | Stealth mode (anti-bot evasion) — 19 patches |
+| `LEAP_STEALTH` | `true` | Stealth mode: `true` \| `passive` \| `auto` \| `false`. See Stealth section. |
+| `LEAP_STEALTH_PROFILES` | `false` | Enable stealth patches on profile (auth'd) sessions |
+| `LEAP_CDP_STEALTH` | `true` | CDP detection evasion (`Runtime.enable` filtering) |
 | `LEAP_HUMANIZE` | `false` | Experimental. Human-like mouse movement, typing cadence, and scroll behavior. |
 | `LEAP_ALLOW_EXECUTE` | `true` | Allow the `execute` tool (sandboxed Playwright scripts) |
 | `LEAP_BLOCK_LOCALHOST` | `false` | Block localhost/127.x.x.x (allowed by default for local dev) |
 | `LEAP_PROFILES_DIR` | `~/.leapfrog/chrome-profiles` | Directory for persistent browser profiles |
 | `LEAP_TILE` | `false` | Tile sessions in a grid (`true` \| `master` \| `false`) |
 | `LEAP_TILE_PADDING` | `8` | Padding between tiled windows (px) |
+| `LEAP_MULTI_TILE` | `false` | Multi-terminal tiling coordination across Leapfrog instances |
+| `LEAP_SCREEN_WIDTH` | _(auto)_ | Explicit screen width for tiling calculations |
+| `LEAP_SCREEN_HEIGHT` | _(auto)_ | Explicit screen height for tiling calculations |
 | `LEAP_HUD` | `false` | Click ripple, zoom-to-target, scroll-to-target on agent actions |
-| `LEAP_SOUND` | `false` | Marimba chime on intervention detection (macOS) |
-| `LEAP_NOTIFY` | `false` | macOS notification center alerts on intervention detection |
 | `LEAP_AUTO_CONSENT` | `true` | Auto-dismiss cookie consent banners (10 frameworks + fallback) |
 | `LEAP_TRACE` | `false` | Per-session Playwright tracing (screenshots + DOM snapshots) |
 | `LEAP_RECORD` | `false` | Session recording (action history export) |
-| `LEAP_SIDECAR_PORT` | `9222` | Sidecar HTTP server port (used with tiling) |
-| `LEAP_CDP_STEALTH` | `true` | CDP detection evasion (`Runtime.enable` filtering) |
+| `LEAP_REBROWSER` | `false` | Enable Rebrowser integration |
+| `LEAP_AUTO_WARM` | `false` | Auto-warm profiles by loading key URLs on session create |
 | `LEAP_CAPTCHA_PROVIDER` | _(none)_ | External CAPTCHA solver: `capsolver` \| `2captcha` \| `nopecha` |
 | `LEAP_CAPTCHA_API_KEY` | _(none)_ | API key for the configured CAPTCHA provider |
 | `LEAP_MAX_SESSIONS_PER_CLIENT` | _(none)_ | Per-client session pool limit |
@@ -348,10 +361,10 @@ Leapfrog uses pond metaphors to keep things memorable. Your agent is the frog.
 ## Tests
 
 ```
- 815 passing across 33 suites
+ 769 passing across 31 suites
 ```
 
-Session management, snapshot engine, network intelligence, tab management, security, SSRF protection, stealth patches (19), humanization (mouse, typing, scroll), page classification, harness intelligence, API intelligence, script executor, extended actions, HUD overlays, human intervention, cookie consent, domain knowledge, tracing, sidecar HTTP, bug regression, stress tests, benchmarks.
+Session management, snapshot engine, snapshot differ, network intelligence, tab management, security, SSRF protection, stealth patches (19), stealth enhanced, humanization (mouse, typing, scroll), page classification, harness intelligence, API intelligence, script executor, extended actions, HUD overlays, human intervention, cookie consent, domain knowledge, selector healing, stable elements, tile manager, bug regression, integration smoke, stress tests, benchmarks.
 
 ```bash
 npm test

package/dist/index.js

@@ -49,7 +49,9 @@ const MAX_SNAPSHOT_CHARS = 10000;
 const ALLOW_JS = process.env.LEAP_ALLOW_JS !== "false";
 const ALLOW_EXECUTE = process.env.LEAP_ALLOW_EXECUTE !== "false";
 const LEAP_PROFILES_DIR = process.env.LEAP_PROFILES_DIR ?? path.join(os.homedir(), ".leapfrog", "chrome-profiles");
-const LEAP_TILE = process.env.LEAP_TILE;
+// WORKAROUND: Claude Code on Windows does not pass mcp.json env vars to child process.
+// Default to "grid" so tiling works out of the box on all platforms.
+const LEAP_TILE = process.env.LEAP_TILE || "grid";
 const LEAP_TILE_PADDING = Number(process.env.LEAP_TILE_PADDING ?? 8);
 const LEAP_SCREEN_WIDTH = Number(process.env.LEAP_SCREEN_WIDTH || 0);
 const LEAP_SCREEN_HEIGHT = Number(process.env.LEAP_SCREEN_HEIGHT || 0);
@@ -79,9 +81,10 @@ if (LEAP_TILE && LEAP_TILE !== "false") {
 // Zero cost for single-terminal (just tracks one instance). No extra env var needed.
 let tilesCoord = null;
 if (LEAP_TILE && LEAP_TILE !== "false") {
-    // Screen size: prefer env vars, fall back to 1920x1080. CDP detection will update later.
-    const defaultW = LEAP_SCREEN_WIDTH > 0 ? LEAP_SCREEN_WIDTH : 1920;
-    const defaultH = LEAP_SCREEN_HEIGHT > 0 ? LEAP_SCREEN_HEIGHT : 1080;
+    // Screen size: prefer env vars, then auto-detected screen, fall back to 1920x1080.
+    const detectedScreen = tileManager.getScreenSize();
+    const defaultW = LEAP_SCREEN_WIDTH > 0 ? LEAP_SCREEN_WIDTH : detectedScreen?.width ?? 1920;
+    const defaultH = LEAP_SCREEN_HEIGHT > 0 ? LEAP_SCREEN_HEIGHT : detectedScreen?.height ?? 1080;
     tilesCoord = new TilesCoordinator(defaultW, defaultH);
     // File watcher only needed for multi-terminal mode (multiple Leapfrog instances).
     // In single-instance mode, the watcher causes spurious reflows that fight
@@ -3002,7 +3005,7 @@ function printConfig() {
     const config = {
         leapfrog: {
             command: "npx",
-            args: ["-y", "leapfrog"],
+            args: ["-y", "leapfrog-mcp"],
             env: {
                 LEAP_MAX_SESSIONS: "15",
             },

package/dist/session-manager.js

@@ -288,10 +288,9 @@ export class SessionManager {
             if (stealth.isEnabled()) {
                 launchArgs.push(...stealth.getLaunchArgs());
             }
-            // Windows DPI: prevent Chromium from double-scaling window positions
-            if (process.platform === 'win32') {
-                launchArgs.push('--force-device-scale-factor=1');
-            }
+            // Windows DPI: --force-device-scale-factor=1 REMOVED
+            // On high-DPI Windows (250%), it renders content at 1x = unreadable tiny text.
+            // Let Chrome auto-detect DPI; CDP handles window positioning correctly without it.
             // ── Window position args ───────────────────────────────────────
             // When tiling: grid position. Otherwise: just place on the detected screen.
             const screen = tileManager.getScreenSize();
@@ -578,6 +577,22 @@ export class SessionManager {
                 logger.warn("tile.position_failed", { error: e.message });
             }
         }
+        // ── Debounced reflow after creation (Windows only) ─────────────
+        // On Windows, launch args position each window for a grid that includes
+        // only the sessions created so far. Earlier windows end up at stale positions.
+        // Reflow all after a 500ms debounce so rapid batch creates settle into one reflow.
+        // Skipped on macOS where CDP reflow can move windows to the wrong screen.
+        if (process.platform === "win32" && tileManager.isEnabled() && this.sessions.size > 1) {
+            clearTimeout(globalThis.__leapReflowTimer);
+            globalThis.__leapReflowTimer = setTimeout(async () => {
+                try {
+                    await tileManager.reflowAll(this.sessions);
+                }
+                catch (e) {
+                    logger.warn("tile.reflow_after_create_failed", { error: e.message });
+                }
+            }, 500);
+        }
         // ── Auto-reflow on external close ──────────────────────────────
         // When the user manually closes a browser window (X button), clean up
         // the session and reflow remaining tiled windows. Without this, closing

package/dist/tile-manager.d.ts

@@ -48,8 +48,8 @@ declare class TileManager {
      */
     static detectTerminalScreen(): ScreenWorkArea | null;
     /**
-     * Windows: detect which monitor contains the foreground window via PowerShell.
-     * Uses .NET System.Windows.Forms.Screen to map foreground window → screen bounds.
+     * Windows: detect primary screen working area via PowerShell.
+     * Uses System.Windows.Forms.Screen — no DllImport, no escaping issues.
      */
     static detectScreenViaPowershell(): ScreenWorkArea | null;
     detectScreen(page: Page): Promise<ScreenWorkArea>;

package/dist/tile-manager.js

@@ -76,36 +76,12 @@ class TileManager {
         return null;
     }
     /**
-     * Windows: detect which monitor contains the foreground window via PowerShell.
-     * Uses .NET System.Windows.Forms.Screen to map foreground window → screen bounds.
+     * Windows: detect primary screen working area via PowerShell.
+     * Uses System.Windows.Forms.Screen — no DllImport, no escaping issues.
      */
     static detectScreenViaPowershell() {
         try {
-            // PowerShell script:
-            // 1. Get foreground window handle via user32.dll
-            // 2. Get window RECT via user32.dll
-            // 3. Find which Screen contains that RECT
-            // 4. Output WorkingArea (excludes taskbar) as "x y width height"
-            const script = `powershell -NoProfile -NonInteractive -Command "
-Add-Type -AssemblyName System.Windows.Forms
-Add-Type -TypeDefinition '
-using System;
-using System.Runtime.InteropServices;
-public class WinAPI {
-  [DllImport(\\\"user32.dll\\\")] public static extern IntPtr GetForegroundWindow();
-  [DllImport(\\\"user32.dll\\\")] public static extern bool GetWindowRect(IntPtr hWnd, out RECT lpRect);
-  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
-}
-'
-$hwnd = [WinAPI]::GetForegroundWindow()
-$rect = New-Object WinAPI+RECT
-[void][WinAPI]::GetWindowRect($hwnd, [ref]$rect)
-$pt = New-Object System.Drawing.Point($rect.Left, $rect.Top)
-$scr = [System.Windows.Forms.Screen]::FromPoint($pt)
-$wa = $scr.WorkingArea
-Write-Output ('{0} {1} {2} {3}' -f $wa.X, $wa.Y, $wa.Width, $wa.Height)
-"`;
-            const result = execSync(script, { timeout: 10000, encoding: "utf-8" }).trim();
+            const result = execSync('powershell -NoProfile -NonInteractive -Command "Add-Type -AssemblyName System.Windows.Forms; $wa = [System.Windows.Forms.Screen]::PrimaryScreen.WorkingArea; Write-Output ($wa.X.ToString() + \' \' + $wa.Y.ToString() + \' \' + $wa.Width.ToString() + \' \' + $wa.Height.ToString())"', { timeout: 10000, encoding: "utf-8" }).trim();
             const parts = result.split(/\s+/).map(Number);
             if (parts.length === 4 && parts.every((n) => !isNaN(n))) {
                 return { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leapfrog-mcp",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Multi-session browser MCP for AI agents — 36 tools, stealth, persistent auth, code-first scripts, API sniffer, agent intelligence",
   "type": "module",
   "main": "dist/index.js",

package/dist/adaptive-wait.d.ts

@@ -1,72 +0,0 @@
-import type { Page } from "playwright-core";
-import type { Session, SnapshotResult } from "./types.js";
-import { type ClassificationResult } from "./page-classifier.js";
-import type { SessionManager } from "./session-manager.js";
-type WaitStrategy = "load" | "domcontentloaded" | "networkidle";
-export interface AdaptiveNavigateOptions {
-    /** Wait strategy to start with. Default: "load" */
-    waitUntil?: WaitStrategy;
-    /** Enable auto-retry stealth escalation. Default: true */
-    autoRetry?: boolean;
-    /** Max escalation level (0-5). Default: 3 */
-    maxRetryLevel?: number;
-    /** Stealth mode override from bandit selection. Applied per-page via stealth.applyToPage(). */
-    stealthModeOverride?: 'off' | 'passive' | 'active';
-    /** Bandit arm index for this navigation (passed through for outcome tracking). */
-    banditArmIndex?: number;
-}
-export type PageQuality = "GOOD" | "EMPTY" | "TIMEOUT" | "BLOCKED";
-export interface AdaptiveNavigateResult {
-    /** The snapshot result from the best attempt */
-    snapshot: SnapshotResult;
-    /** Page classification */
-    classification: ClassificationResult;
-    /** Final page URL after navigation */
-    url: string;
-    /** Page title */
-    title: string;
-    /** The page quality assessment */
-    quality: PageQuality;
-    /** Which waitUntil strategy succeeded */
-    finalStrategy: WaitStrategy;
-    /** Escalation metadata if stealth retries were used */
-    escalation?: EscalationMeta;
-    /** Bandit arm index used for this navigation (for outcome tracking) */
-    banditArmIndex?: number;
-    /** Stealth mode override applied by the bandit */
-    stealthModeOverride?: string;
-    /** The session that owns the page (may change if session was rotated) */
-    session: Session;
-    /** The page instance (may change if session was rotated) */
-    page: Page;
-}
-export interface EscalationMeta {
-    /** Level at which navigation succeeded (0-5) */
-    level: number;
-    /** Human-readable label for the level */
-    label: string;
-    /** Total retries attempted */
-    attempts: number;
-    /** Whether the session was rotated (Level 3+) */
-    sessionRotated: boolean;
-    /** New session ID if rotated */
-    newSessionId?: string;
-}
-/**
- * Adaptive navigate: replaces the naive page.goto() in the navigate tool.
- *
- * 1. Tries the requested waitUntil strategy
- * 2. Evaluates page quality (snapshot + classification)
- * 3. Retries with alternative strategies if EMPTY/TIMEOUT
- * 4. Escalates with stealth retries if BLOCKED/CHALLENGE
- *
- * Returns a rich result with snapshot, classification, escalation metadata,
- * and the final session/page (which may differ if session was rotated).
- */
-export declare function adaptiveNavigate(page: Page, session: Session, url: string, sessionManager: SessionManager, options?: AdaptiveNavigateOptions): Promise<AdaptiveNavigateResult>;
-/**
- * Format the AdaptiveNavigateResult into the text output for the MCP tool response.
- * Matches the existing navigate output format with optional escalation metadata.
- */
-export declare function formatAdaptiveResult(result: AdaptiveNavigateResult): string;
-export {};