ornold-mcp 1.0.0

package/executor/multi-browser.ts

@@ -0,0 +1,1960 @@
+import * as playwright from 'patchright';
+import type { Browser, BrowserContext, Page } from 'patchright';
+import type {
+  BrowserEndpoint,
+  ConnectedBrowser,
+  ParallelResult,
+  ParallelResults,
+  BrowserStatus,
+  SnapshotResult,
+  NavigationTarget,
+  TextMapping,
+  VariableMapping,
+} from './types.js';
+import { ConcurrencyLimiter, detectOptimalConcurrency } from './concurrency.js';
+import {
+  generateProfile,
+  preActionDelay,
+  humanMouseMove,
+  humanClick,
+  getClickTarget,
+  humanTypeText,
+  humanDelay,
+  ensureCursor,
+  type HumanProfile,
+} from './human-like.js';
+
+/**
+ * MultiBrowserExecutor - Core class for managing multiple browser connections
+ * and executing parallel operations across all of them.
+ * Uses ref-based element targeting like the original Playwright MCP.
+ * 
+ * OPTIMIZATION: Uses concurrency limiter with auto-detection based on system resources.
+ */
+export class MultiBrowserExecutor {
+  private browsers: Map<string, ConnectedBrowser> = new Map();
+  private defaultTimeout: number;
+  private limiter: ConcurrencyLimiter;
+  private heavyLimiter: ConcurrencyLimiter;
+  private lightLimiter: ConcurrencyLimiter;
+  
+  // Cache for browser sync - prevents excessive API calls
+  private lastSyncTime: number = 0;
+  private syncInProgress: Promise<void> | null = null;
+  private static readonly SYNC_TTL_MS = 5000; // 5 seconds cache TTL
+
+  // Track last mouse position per browser for human-like movement
+  private lastMousePosition: Map<string, { x: number; y: number }> = new Map();
+  // Per-browser human profiles for varied timing
+  private profiles: Map<string, HumanProfile> = new Map();
+
+  // Console messages collected per browser (since connect time)
+  private consoleMessages: Map<string, Array<{ type: string; text: string; timestamp: number }>> = new Map();
+  // Network requests collected per browser (since connect time)
+  private networkRequests: Map<string, Array<{ url: string; method: string; status?: number; resourceType: string; timestamp: number }>> = new Map();
+
+  constructor(options: { timeout?: number; maxConcurrency?: number } = {}) {
+    this.defaultTimeout = options.timeout ?? 5000; // 5 seconds like original MCP
+    
+    // Auto-detect optimal concurrency based on system resources
+    const detected = detectOptimalConcurrency();
+    
+    // Allow override via options, otherwise use detected values
+    const defaultConcurrency = options.maxConcurrency ?? detected.default;
+    const heavyConcurrency = options.maxConcurrency 
+      ? Math.max(2, Math.floor(options.maxConcurrency * 0.75)) 
+      : detected.heavy;
+    const lightConcurrency = options.maxConcurrency 
+      ? Math.min(options.maxConcurrency * 1.5, 10) 
+      : detected.light;
+    
+    this.limiter = new ConcurrencyLimiter(defaultConcurrency);
+    this.heavyLimiter = new ConcurrencyLimiter(heavyConcurrency);
+    this.lightLimiter = new ConcurrencyLimiter(lightConcurrency);
+    
+    console.error(`[Executor] Concurrency limiters initialized: default=${defaultConcurrency}, heavy=${heavyConcurrency}, light=${lightConcurrency}`);
+  }
+
+  // ==================== CONNECTION MANAGEMENT ====================
+
+  /**
+   * Connect to multiple browsers with controlled concurrency.
+   * OPTIMIZATION: Limits simultaneous connections to prevent overwhelming CDP endpoints.
+   */
+  async connectAll(endpoints: BrowserEndpoint[]): Promise<ParallelResults<BrowserStatus>> {
+    const start = Date.now();
+    console.error(`[Executor] connectAll: starting connection to ${endpoints.length} browsers with concurrency limit`);
+    
+    // Use a dedicated limiter for connections - don't overwhelm CDP
+    // ✅ ИСПРАВЛЕНИЕ: Убран лимит 3 для RunPod сервера
+    // Теперь используем heavy limiter без дополнительных ограничений
+    const connectionLimiter = new ConcurrencyLimiter(
+      this.heavyLimiter.limit
+    );
+    
+    const tasks = endpoints.map(async (endpoint): Promise<ParallelResult<BrowserStatus>> => {
+      return connectionLimiter.run(async () => {
+        const taskStart = Date.now();
+        try {
+          console.error(`[Executor] Connecting to ${endpoint.id} at ${endpoint.cdpEndpoint}...`);
+          const result = await this.connect(endpoint);
+          console.error(`[Executor] ✅ Connected to ${endpoint.id}: ${result.url}`);
+          return {
+            browserId: endpoint.id,
+            success: true,
+            result,
+            duration: Date.now() - taskStart,
+          };
+        } catch (error) {
+          console.error(`[Executor] ❌ Failed to connect to ${endpoint.id}: ${error}`);
+          return {
+            browserId: endpoint.id,
+            success: false,
+            error: String(error),
+            duration: Date.now() - taskStart,
+          };
+        }
+      });
+    });
+
+    const results = await Promise.all(tasks);
+    
+    console.error(`[Executor] connectAll complete: ${results.filter(r => r.success).length}/${results.length} connected in ${Date.now() - start}ms`);
+    return {
+      results,
+      totalDuration: Date.now() - start,
+      successCount: results.filter(r => r.success).length,
+      failureCount: results.filter(r => !r.success).length,
+    };
+  }
+
+  async connect(endpoint: BrowserEndpoint, retries = 3): Promise<BrowserStatus> {
+    if (this.browsers.has(endpoint.id)) {
+      throw new Error(`Browser ${endpoint.id} is already connected`);
+    }
+
+    let lastError: Error | null = null;
+    
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        console.error(`[Executor] Attempt ${attempt}/${retries} to connect to ${endpoint.id} at ${endpoint.cdpEndpoint}`);
+        
+        const browser = await playwright.chromium.connectOverCDP(endpoint.cdpEndpoint, {
+          headers: endpoint.cdpHeaders,
+        });
+        
+        // Success - continue with the rest of the connect logic
+        return await this._finishConnect(endpoint, browser);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        console.error(`[Executor] Attempt ${attempt}/${retries} failed for ${endpoint.id}: ${lastError.message}`);
+        
+        if (attempt < retries) {
+          // Wait before retry (fast exponential backoff: 300ms, 600ms, 1200ms)
+          const delay = Math.pow(2, attempt - 1) * 300;
+          console.error(`[Executor] Retrying in ${delay}ms...`);
+          await new Promise(r => setTimeout(r, delay));
+        }
+      }
+    }
+    
+    throw lastError || new Error(`Failed to connect to ${endpoint.id} after ${retries} attempts`);
+  }
+
+  private async _finishConnect(endpoint: BrowserEndpoint, browser: Browser): Promise<BrowserStatus> {
+    let context: BrowserContext;
+    let page: Page;
+
+    const contexts = browser.contexts();
+    console.error(`[Executor] Browser ${endpoint.id} has ${contexts.length} contexts`);
+    
+    if (contexts.length > 0) {
+      context = contexts[0];
+      const pages = context.pages();
+      console.error(`[Executor] Context has ${pages.length} pages`);
+      
+      if (pages.length > 0) {
+        // Используем существующую страницу (первую не-blank, или первую)
+        page = pages.find(p => !p.url().startsWith('about:')) || pages[0];
+        console.error(`[Executor] Using existing page: ${page.url()}`);
+      } else {
+        // Нет страниц - для Linken Sphere через прокси это нормально,
+        // ждём появления страницы вместо создания новой
+        console.error(`[Executor] No pages in context, waiting for existing page...`);
+        
+        // Ждём до 2 секунд пока появится страница (fast polling)
+        const waitStart = Date.now();
+        while (Date.now() - waitStart < 2000) {
+          const currentPages = context.pages();
+          if (currentPages.length > 0) {
+            page = currentPages.find(p => !p.url().startsWith('about:')) || currentPages[0];
+            console.error(`[Executor] Found page after waiting: ${page.url()}`);
+            break;
+          }
+          await new Promise(r => setTimeout(r, 100));
+        }
+        
+        // Если всё ещё нет страниц - создаём только в крайнем случае
+        if (!page!) {
+          console.error(`[Executor] No pages appeared after 2s, creating new page (fallback)`);
+          page = await context.newPage();
+        }
+      }
+    } else {
+      // Нет контекстов - тоже ждём, для CDP over proxy контексты могут появиться позже
+      console.error(`[Executor] No contexts, waiting for context to appear...`);
+      
+      const waitStart = Date.now();
+      while (Date.now() - waitStart < 2000) {
+        const currentContexts = browser.contexts();
+        if (currentContexts.length > 0) {
+          context = currentContexts[0];
+          const pages = context.pages();
+          if (pages.length > 0) {
+            page = pages.find(p => !p.url().startsWith('about:')) || pages[0];
+            console.error(`[Executor] Found context and page after waiting: ${page!.url()}`);
+            break;
+          }
+        }
+        await new Promise(r => setTimeout(r, 100));
+      }
+      
+      // Fallback - создаём только если ничего не появилось
+      if (!context!) {
+        console.error(`[Executor] Creating new context and page for ${endpoint.id} (fallback)`);
+        context = await browser.newContext();
+        page = await context.newPage();
+      } else if (!page!) {
+        console.error(`[Executor] Context found but no pages, creating page (fallback)`);
+        page = await context.newPage();
+      }
+    }
+
+    // Clean up extra about:blank pages created by connectOverCDP
+    // Keep only the page we selected — close the rest if they're blank
+    try {
+      const allPages = context.pages();
+      for (const p of allPages) {
+        if (p !== page && p.url() === 'about:blank') {
+          await p.close().catch(() => {});
+          console.error(`[Executor] Closed extra about:blank page for ${endpoint.id}`);
+        }
+      }
+    } catch {}
+
+    // Set timeouts like original MCP
+    page.setDefaultTimeout(this.defaultTimeout);
+    page.setDefaultNavigationTimeout(60000);
+
+    const connected: ConnectedBrowser = {
+      id: endpoint.id,
+      browser,
+      context,
+      page,
+      endpoint,
+      connectedAt: new Date(),
+    };
+
+    this.browsers.set(endpoint.id, connected);
+    console.error(`[Executor] Successfully stored ${endpoint.id} in browsers map. Total browsers: ${this.browsers.size}`);
+
+    // Set up console message tracking
+    const consoleLog: Array<{ type: string; text: string; timestamp: number }> = [];
+    this.consoleMessages.set(endpoint.id, consoleLog);
+    page.on('console', (msg) => {
+      consoleLog.push({ type: msg.type(), text: msg.text(), timestamp: Date.now() });
+      if (consoleLog.length > 1000) consoleLog.shift();
+    });
+
+    // Set up network request tracking
+    const networkLog: Array<{ url: string; method: string; status?: number; resourceType: string; timestamp: number }> = [];
+    this.networkRequests.set(endpoint.id, networkLog);
+    page.on('response', (response) => {
+      const req = response.request();
+      networkLog.push({
+        url: req.url(),
+        method: req.method(),
+        status: response.status(),
+        resourceType: req.resourceType(),
+        timestamp: Date.now(),
+      });
+      if (networkLog.length > 1000) networkLog.shift();
+    });
+
+    browser.on('disconnected', () => {
+      console.error(`[Executor] Browser ${endpoint.id} disconnected`);
+      this.browsers.delete(endpoint.id);
+      this.consoleMessages.delete(endpoint.id);
+      this.networkRequests.delete(endpoint.id);
+
+      // Auto-reconnect after 500ms (fast reconnect)
+      setTimeout(async () => {
+        if (!this.browsers.has(endpoint.id)) {
+          console.error(`[Executor] Attempting auto-reconnect for ${endpoint.id}...`);
+          try {
+            await this.connect(endpoint, 2); // 2 retries for reconnect
+            console.error(`[Executor] ✅ Auto-reconnected ${endpoint.id}`);
+          } catch (e) {
+            console.error(`[Executor] ❌ Auto-reconnect failed for ${endpoint.id}: ${e instanceof Error ? e.message : String(e)}`);
+          }
+        }
+      }, 500);
+    });
+
+    const url = page.url();
+    const title = await page.title().catch(() => '');
+    console.error(`[Executor] Browser ${endpoint.id} connected. URL: ${url}, Title: ${title}`);
+
+    return {
+      id: endpoint.id,
+      connected: true,
+      url,
+      title,
+      endpoint: endpoint.cdpEndpoint,
+      tags: endpoint.tags,
+      connectedAt: connected.connectedAt,
+    };
+  }
+
+  async disconnect(browserId: string): Promise<void> {
+    const browser = this.browsers.get(browserId);
+    if (!browser) throw new Error(`Browser ${browserId} not found`);
+    await browser.browser.close().catch(() => {});
+    this.browsers.delete(browserId);
+    this.consoleMessages.delete(browserId);
+    this.networkRequests.delete(browserId);
+  }
+
+  async disconnectAll(): Promise<void> {
+    const ids = Array.from(this.browsers.keys());
+    await Promise.all(
+      ids.map(id => this.disconnect(id).catch(() => {}))
+    );
+    // Force clear the map in case any disconnect failed
+    this.browsers.clear();
+  }
+
+  async listBrowsers(): Promise<BrowserStatus[]> {
+    const statuses: BrowserStatus[] = [];
+    for (const [id, browser] of this.browsers) {
+      try {
+        statuses.push({
+          id,
+          connected: browser.browser.isConnected(),
+          url: browser.page.url(),
+          title: await browser.page.title().catch(() => ''),
+          endpoint: browser.endpoint.cdpEndpoint,
+          tags: browser.endpoint.tags,
+          connectedAt: browser.connectedAt,
+        });
+      } catch {
+        statuses.push({
+          id,
+          connected: false,
+          endpoint: browser.endpoint.cdpEndpoint,
+          tags: browser.endpoint.tags,
+        });
+      }
+    }
+    return statuses;
+  }
+
+  /**
+   * Detailed status check for all browsers
+   */
+  async getDetailedStatus(options: { checkContent?: boolean } = {}): Promise<{
+    browsers: Array<{
+      id: string;
+      status: 'ok' | 'disconnected' | 'error' | 'behind';
+      url: string;
+      title: string;
+      error?: string;
+      responsive: boolean;
+    }>;
+    summary: {
+      total: number;
+      ok: number;
+      problems: number;
+    };
+    majorityUrl?: string;
+  }> {
+    const results: Array<{
+      id: string;
+      status: 'ok' | 'disconnected' | 'error' | 'behind';
+      url: string;
+      title: string;
+      error?: string;
+      responsive: boolean;
+    }> = [];
+
+    const urlCounts = new Map<string, number>();
+
+    for (const [id, browser] of this.browsers) {
+      try {
+        // Check if browser is connected
+        if (!browser.browser.isConnected()) {
+          results.push({
+            id,
+            status: 'disconnected',
+            url: '',
+            title: '',
+            error: 'Browser disconnected',
+            responsive: false,
+          });
+          continue;
+        }
+
+        // Try to get page info
+        const url = browser.page.url();
+        const title = await browser.page.title().catch(() => '');
+        
+        // Check responsiveness with a simple evaluate (fast 1s timeout)
+        let responsive = true;
+        try {
+          let timeoutId: ReturnType<typeof setTimeout>;
+          const timeoutPromise = new Promise<never>((_, reject) => {
+            timeoutId = setTimeout(() => reject(new Error('timeout')), 1000);
+          });
+
+          try {
+            await Promise.race([
+              browser.page.evaluate(() => true),
+              timeoutPromise,
+            ]);
+            clearTimeout(timeoutId!);
+          } catch {
+            clearTimeout(timeoutId!);
+            responsive = false;
+          }
+        } catch {
+          responsive = false;
+        }
+
+        // Count URLs to find majority
+        const baseUrl = url.split('?')[0]; // Ignore query params
+        urlCounts.set(baseUrl, (urlCounts.get(baseUrl) || 0) + 1);
+
+        results.push({
+          id,
+          status: responsive ? 'ok' : 'error',
+          url,
+          title,
+          error: responsive ? undefined : 'Page not responding',
+          responsive,
+        });
+      } catch (error) {
+        results.push({
+          id,
+          status: 'error',
+          url: '',
+          title: '',
+          error: String(error),
+          responsive: false,
+        });
+      }
+    }
+
+    // Find majority URL (where most browsers are)
+    let majorityUrl: string | undefined;
+    let maxCount = 0;
+    for (const [url, count] of urlCounts) {
+      if (count > maxCount) {
+        maxCount = count;
+        majorityUrl = url;
+      }
+    }
+
+    // Mark browsers that are behind (different URL from majority)
+    if (majorityUrl && maxCount > 1) {
+      for (const result of results) {
+        if (result.status === 'ok' && result.url.split('?')[0] !== majorityUrl) {
+          result.status = 'behind';
+        }
+      }
+    }
+
+    const okCount = results.filter(r => r.status === 'ok').length;
+
+    return {
+      browsers: results,
+      summary: {
+        total: results.length,
+        ok: okCount,
+        problems: results.length - okCount,
+      },
+      majorityUrl,
+    };
+  }
+
+  /**
+   * Sync browsers from API (on-demand) with retry logic.
+   * Called automatically when getBrowserIds finds no connected browsers.
+   */
+  async syncFromAPI(retries = 2): Promise<void> {
+    const apiServerUrl = process.env.API_SERVER_URL;
+    const userId = process.env.USER_ID;
+
+    if (!apiServerUrl || !userId) {
+      console.error(`[Executor] syncFromAPI: missing API_SERVER_URL or USER_ID`);
+      return;
+    }
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        const url = `${apiServerUrl}/api/browsers?userId=${userId}`;
+        console.error(`[Executor] syncFromAPI: fetching ${url} (attempt ${attempt}/${retries})`);
+
+        // Add timeout for fetch (fast 5s timeout)
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 5000); // 5s timeout
+
+        try {
+          const response = await fetch(url, { signal: controller.signal });
+          clearTimeout(timeoutId);
+
+          if (!response.ok) {
+            throw new Error(`API returned ${response.status}`);
+          }
+
+          const data = await response.json() as { browsers: Array<{ id: string; cdpEndpoint: string; tags?: string[] }> };
+          const apiBrowsers = data.browsers || [];
+
+          console.error(`[Executor] syncFromAPI: API returned ${apiBrowsers.length} browsers`);
+
+          // Get currently connected IDs
+          const connectedIds = new Set(this.browsers.keys());
+
+          // Connect new browsers
+          for (const browser of apiBrowsers) {
+            if (!connectedIds.has(browser.id)) {
+              console.error(`[Executor] syncFromAPI: connecting ${browser.id}`);
+              try {
+                await this.connect({
+                  id: browser.id,
+                  cdpEndpoint: browser.cdpEndpoint,
+                  tags: browser.tags || [],
+                });
+                console.error(`[Executor] syncFromAPI: ✓ connected ${browser.id}`);
+              } catch (e) {
+                console.error(`[Executor] syncFromAPI: ✗ failed ${browser.id}: ${e instanceof Error ? e.message : String(e)}`);
+              }
+            }
+          }
+
+          // Disconnect stale browsers (in local but not in API)
+          const apiIds = new Set(apiBrowsers.map(b => b.id));
+          for (const id of connectedIds) {
+            if (!apiIds.has(id)) {
+              console.error(`[Executor] syncFromAPI: disconnecting stale ${id}`);
+              try {
+                await this.disconnect(id);
+              } catch {
+                // Ignore disconnect errors
+              }
+            }
+          }
+
+          console.error(`[Executor] syncFromAPI: done, now have ${this.browsers.size} browsers`);
+          this.lastSyncTime = Date.now(); // Update cache timestamp
+          return; // Success, exit
+        } catch (e) {
+          clearTimeout(timeoutId);
+          throw e;
+        }
+      } catch (e) {
+        lastError = e instanceof Error ? e : new Error(String(e));
+        console.error(`[Executor] syncFromAPI: attempt ${attempt}/${retries} failed: ${lastError.message}`);
+
+        if (attempt < retries) {
+          const delay = Math.pow(2, attempt - 1) * 300; // Fast exponential backoff
+          console.error(`[Executor] syncFromAPI: retrying in ${delay}ms...`);
+          await new Promise(r => setTimeout(r, delay));
+        }
+      }
+    }
+
+    console.error(`[Executor] syncFromAPI: all ${retries} attempts failed`);
+  }
+
+  getBrowserIds(filter?: { browserIds?: string[]; tags?: string[] }): string[] {
+    let ids = Array.from(this.browsers.keys());
+    if (filter?.browserIds?.length) {
+      ids = ids.filter(id => filter.browserIds!.includes(id));
+    }
+    if (filter?.tags?.length) {
+      ids = ids.filter(id => {
+        const browser = this.browsers.get(id);
+        return browser?.endpoint.tags?.some(t => filter.tags!.includes(t));
+      });
+    }
+    return ids;
+  }
+
+  /**
+   * Ensure browsers are loaded before operations.
+   * Uses caching to prevent excessive API calls.
+   * Only syncs if: no browsers connected AND cache expired.
+   */
+  async ensureBrowsersLoaded(): Promise<void> {
+    // If we have browsers, skip sync entirely
+    if (this.browsers.size > 0) {
+      return;
+    }
+    
+    // Check cache TTL
+    const now = Date.now();
+    if (now - this.lastSyncTime < MultiBrowserExecutor.SYNC_TTL_MS) {
+      console.error(`[Executor] ensureBrowsersLoaded: skipping sync, cache valid (${now - this.lastSyncTime}ms old)`);
+      return;
+    }
+    
+    // Deduplicate concurrent sync requests
+    if (this.syncInProgress) {
+      console.error(`[Executor] ensureBrowsersLoaded: sync already in progress, waiting...`);
+      await this.syncInProgress;
+      return;
+    }
+    
+    console.error(`[Executor] ensureBrowsersLoaded: no browsers, syncing from API...`);
+    this.syncInProgress = this.syncFromAPI().finally(() => {
+      this.syncInProgress = null;
+    });
+    await this.syncInProgress;
+  }
+
+  getBrowserEndpoint(browserId: string): BrowserEndpoint | undefined {
+    const browser = this.browsers.get(browserId);
+    return browser?.endpoint;
+  }
+
+  getPage(browserId: string): Page {
+    const browser = this.browsers.get(browserId);
+    if (!browser) throw new Error(`Browser ${browserId} not found`);
+    return browser.page;
+  }
+
+  // ==================== PARALLEL EXECUTION ====================
+
+  /**
+   * Get the appropriate limiter based on operation type
+   */
+  private getLimiter(type?: 'heavy' | 'light' | number): ConcurrencyLimiter {
+    if (typeof type === 'number') {
+      return new ConcurrencyLimiter(type);
+    }
+    switch (type) {
+      case 'heavy':
+        return this.heavyLimiter;
+      case 'light':
+        return this.lightLimiter;
+      default:
+        return this.limiter;
+    }
+  }
+
+  /**
+   * Execute action on multiple browsers with controlled concurrency.
+   * This prevents system overload when operating on 9+ browsers.
+   * Concurrency is auto-detected based on system resources (RAM, CPU cores).
+   * 
+   * @param browserIds - specific browsers to target, or undefined for all
+   * @param action - async function to execute on each browser
+   * @param options.timeout - per-browser timeout
+   * @param options.concurrency - 'heavy' | 'light' | number - type of operation or explicit limit
+   */
+  async executeParallel<T>(
+    browserIds: string[] | undefined,
+    action: (page: Page, browserId: string) => Promise<T>,
+    options: { timeout?: number; concurrency?: 'heavy' | 'light' | number } = {}
+  ): Promise<ParallelResults<T>> {
+    const start = Date.now();
+
+    // Auto-sync from API if no browsers connected
+    await this.ensureBrowsersLoaded();
+
+    const ids = browserIds ?? this.getBrowserIds();
+    const timeout = options.timeout ?? this.defaultTimeout;
+
+    // Get appropriate limiter based on operation type
+    const limiter = this.getLimiter(options.concurrency);
+
+    console.error(`[Executor] executeParallel: running on ${ids.length} browsers with concurrency limit: [${ids.join(', ')}]`);
+
+    const tasks = ids.map(async (id): Promise<ParallelResult<T>> => {
+      // Wait for slot in limiter - this prevents all 9 browsers from executing at once
+      return limiter.run(async () => {
+        const taskStart = Date.now();
+        const browser = this.browsers.get(id);
+
+        if (!browser) {
+          console.error(`[Executor] ❌ Browser ${id} not found in map`);
+          return {
+            browserId: id,
+            success: false,
+            error: `Browser ${id} not found`,
+            duration: Date.now() - taskStart,
+          };
+        }
+
+        // Check if browser is still connected before executing
+        if (!browser.browser.isConnected()) {
+          console.error(`[Executor] ❌ Browser ${id} is disconnected`);
+          this.browsers.delete(id);
+          return {
+            browserId: id,
+            success: false,
+            error: `Browser ${id} is disconnected`,
+            duration: Date.now() - taskStart,
+          };
+        }
+
+        try {
+          console.error(`[Executor] 🔄 Executing action on ${id}...`);
+
+          // Use AbortController pattern to properly cleanup timeout
+          let timeoutId: ReturnType<typeof setTimeout>;
+          const timeoutPromise = new Promise<never>((_, reject) => {
+            timeoutId = setTimeout(() => reject(new Error('Timeout')), timeout);
+          });
+
+          try {
+            const result = await Promise.race([
+              action(browser.page, id),
+              timeoutPromise,
+            ]);
+
+            clearTimeout(timeoutId!);
+            console.error(`[Executor] ✅ Action completed on ${id}`);
+            return {
+              browserId: id,
+              success: true,
+              result,
+              duration: Date.now() - taskStart,
+            };
+          } catch (error) {
+            clearTimeout(timeoutId!);
+            throw error;
+          }
+        } catch (error) {
+          console.error(`[Executor] ❌ Action failed on ${id}: ${error}`);
+          return {
+            browserId: id,
+            success: false,
+            error: String(error),
+            duration: Date.now() - taskStart,
+          };
+        }
+      });
+    });
+
+    const results = await Promise.all(tasks);
+
+    console.error(`[Executor] executeParallel complete: ${results.filter(r => r.success).length}/${results.length} succeeded in ${Date.now() - start}ms`);
+    return {
+      results,
+      totalDuration: Date.now() - start,
+      successCount: results.filter(r => r.success).length,
+      failureCount: results.filter(r => !r.success).length,
+    };
+  }
+
+  // ==================== NAVIGATION ====================
+
+  /**
+   * Navigate multiple browsers to the same URL.
+   * OPTIMIZATION: Uses higher concurrency for navigation (it's mostly network-bound)
+   */
+  async parallelNavigate(
+    url: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<{ url: string; title: string }>> {
+    return this.executeParallel(
+      browserIds, 
+      async (page) => {
+        await page.goto(url, { waitUntil: 'domcontentloaded' });
+        await page.waitForLoadState('load', { timeout: 5000 }).catch(() => {});
+        return { url: page.url(), title: await page.title() };
+      }, 
+      { 
+        timeout: 60000,
+        concurrency: 'light' 
+      }
+    );
+  }
+
+  async parallelNavigateMulti(
+    targets: NavigationTarget[]
+  ): Promise<ParallelResults<{ url: string; title: string }>> {
+    const start = Date.now();
+    
+    const tasks = targets.map(async (target): Promise<ParallelResult<{ url: string; title: string }>> => {
+      const taskStart = Date.now();
+      const browser = this.browsers.get(target.browserId);
+      
+      if (!browser) {
+        return {
+          browserId: target.browserId,
+          success: false,
+          error: `Browser ${target.browserId} not found`,
+          duration: Date.now() - taskStart,
+        };
+      }
+
+      try {
+        await browser.page.goto(target.url, { waitUntil: 'domcontentloaded' });
+        await browser.page.waitForLoadState('load', { timeout: 5000 }).catch(() => {});
+        return {
+          browserId: target.browserId,
+          success: true,
+          result: { url: browser.page.url(), title: await browser.page.title() },
+          duration: Date.now() - taskStart,
+        };
+      } catch (error) {
+        return {
+          browserId: target.browserId,
+          success: false,
+          error: String(error),
+          duration: Date.now() - taskStart,
+        };
+      }
+    });
+
+    const results = await Promise.all(tasks);
+    
+    return {
+      results,
+      totalDuration: Date.now() - start,
+      successCount: results.filter(r => r.success).length,
+      failureCount: results.filter(r => !r.success).length,
+    };
+  }
+
+  async parallelGoBack(browserIds?: string[]): Promise<ParallelResults<void>> {
+    return this.executeParallel(browserIds, async (page) => {
+      await page.goBack();
+    });
+  }
+
+  async parallelGoForward(browserIds?: string[]): Promise<ParallelResults<void>> {
+    return this.executeParallel(browserIds, async (page) => {
+      await page.goForward();
+    });
+  }
+
+  async parallelReload(browserIds?: string[]): Promise<ParallelResults<void>> {
+    return this.executeParallel(browserIds, async (page) => {
+      await page.reload();
+    });
+  }
+
+  // ==================== SNAPSHOT ====================
+
+  async parallelSnapshot(
+    browserIds?: string[],
+    options: { compact?: boolean } = {}
+  ): Promise<ParallelResults<SnapshotResult>> {
+    const MAX_SNAPSHOT_SIZE = 30000;
+
+    return this.executeParallel(
+      browserIds,
+      async (page, browserId) => {
+        // Extract interactive elements with real HTML attributes for selector building
+        const elements = await page.evaluate((compactMode: boolean) => {
+          const interactiveTags = new Set(['a', 'button', 'input', 'select', 'textarea', 'summary']);
+          const interactiveRoles = new Set([
+            'button', 'link', 'textbox', 'combobox', 'searchbox',
+            'checkbox', 'radio', 'switch', 'slider', 'spinbutton',
+            'menuitem', 'menuitemcheckbox', 'menuitemradio',
+            'option', 'tab', 'treeitem', 'listbox',
+          ]);
+
+          interface ElementInfo {
+            tag: string;
+            selector: string;
+            text: string;
+            type?: string;
+            value?: string;
+            checked?: boolean;
+            disabled?: boolean;
+            href?: string;
+            placeholder?: string;
+            section?: string;
+          }
+
+          // Build the best unique selector for an element
+          function buildSelector(el: Element): string {
+            const tag = el.tagName.toLowerCase();
+            // 1. id — best
+            if (el.id) return `#${CSS.escape(el.id)}`;
+            // 2. data-testid
+            const testId = el.getAttribute('data-testid');
+            if (testId) return `[data-testid="${testId}"]`;
+            // 3. name attribute
+            const name = el.getAttribute('name');
+            if (name) return `${tag}[name="${name}"]`;
+            // 4. placeholder
+            const placeholder = el.getAttribute('placeholder');
+            if (placeholder) return `${tag}[placeholder="${placeholder}"]`;
+            // 5. aria-label
+            const ariaLabel = el.getAttribute('aria-label');
+            if (ariaLabel) return `[aria-label="${ariaLabel}"]`;
+            // 6. role + name
+            const role = el.getAttribute('role');
+            if (role) {
+              const text = el.textContent?.trim().slice(0, 40);
+              if (text) return `role=${role}[name="${text}"]`;
+              return `[role="${role}"]`;
+            }
+            // 7. tag + text content for buttons/links
+            if (tag === 'button' || tag === 'a') {
+              const text = el.textContent?.trim().slice(0, 40);
+              if (text) return `${tag}:has-text("${text}")`;
+            }
+            // 8. tag + type for inputs
+            const type = el.getAttribute('type');
+            if (tag === 'input' && type) return `input[type="${type}"]`;
+            // 9. class-based fallback
+            if (el.className && typeof el.className === 'string') {
+              const cls = el.className.trim().split(/\s+/)[0];
+              if (cls) return `${tag}.${CSS.escape(cls)}`;
+            }
+            return tag;
+          }
+
+          // Find nearest section/heading for context
+          function findSection(el: Element): string {
+            let node: Element | null = el;
+            while (node) {
+              // Check previous siblings and parent for headings
+              let sibling = node.previousElementSibling;
+              while (sibling) {
+                if (/^H[1-6]$/.test(sibling.tagName)) {
+                  return sibling.textContent?.trim().slice(0, 50) || '';
+                }
+                sibling = sibling.previousElementSibling;
+              }
+              // Check parent landmarks
+              const role = node.getAttribute('role');
+              const ariaLabel = node.getAttribute('aria-label');
+              if (role === 'navigation' || role === 'main' || role === 'banner' ||
+                  role === 'dialog' || role === 'form') {
+                return `[${role}${ariaLabel ? ': ' + ariaLabel : ''}]`;
+              }
+              if (node.tagName === 'NAV' || node.tagName === 'MAIN' ||
+                  node.tagName === 'HEADER' || node.tagName === 'FOOTER' ||
+                  node.tagName === 'FORM') {
+                const label = ariaLabel || node.getAttribute('name') || '';
+                return `[${node.tagName.toLowerCase()}${label ? ': ' + label : ''}]`;
+              }
+              node = node.parentElement;
+            }
+            return '';
+          }
+
+          const results: ElementInfo[] = [];
+          const seen = new Set<string>();
+
+          // Also collect headings for page structure context
+          if (!compactMode) {
+            const headings = Array.from(document.querySelectorAll('h1, h2, h3'));
+            for (const h of headings) {
+              const text = h.textContent?.trim().slice(0, 80);
+              if (text) {
+                results.push({
+                  tag: h.tagName.toLowerCase(),
+                  selector: '',
+                  text: text,
+                });
+              }
+            }
+          }
+
+          const allElements = Array.from(document.querySelectorAll('*'));
+          for (const el of allElements) {
+            const tag = el.tagName.toLowerCase();
+            const role = el.getAttribute('role');
+            const isInteractive = interactiveTags.has(tag) ||
+                                  (role !== null && interactiveRoles.has(role)) ||
+                                  el.getAttribute('contenteditable') === 'true' ||
+                                  (el.getAttribute('tabindex') !== null && el.getAttribute('tabindex') !== '-1');
+
+            if (!isInteractive) continue;
+
+            // Skip hidden elements
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0) continue;
+            const style = window.getComputedStyle(el);
+            if (style.display === 'none' || style.visibility === 'hidden') continue;
+
+            const selector = buildSelector(el);
+            // Deduplicate by selector
+            if (seen.has(selector)) continue;
+            seen.add(selector);
+
+            const text = el.textContent?.trim().slice(0, 60) || '';
+            const info: ElementInfo = { tag, selector, text };
+
+            // Add useful attributes
+            const type = el.getAttribute('type');
+            if (type) info.type = type;
+
+            if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+              if (el.value) info.value = el.value.slice(0, 60);
+            }
+            if (el instanceof HTMLInputElement && (el.type === 'checkbox' || el.type === 'radio')) {
+              info.checked = el.checked;
+            }
+            if ((el as HTMLElement).getAttribute('disabled') !== null) {
+              info.disabled = true;
+            }
+
+            const href = el.getAttribute('href');
+            if (href && href !== '#' && !href.startsWith('javascript:')) {
+              info.href = href.slice(0, 100);
+            }
+
+            const placeholder = el.getAttribute('placeholder');
+            if (placeholder) info.placeholder = placeholder;
+
+            // Section context (only in full mode)
+            if (!compactMode) {
+              const section = findSection(el);
+              if (section) info.section = section;
+            }
+
+            results.push(info);
+          }
+
+          return results;
+        }, !!options.compact);
+
+        // Format elements into readable text
+        let snapshot = this.formatSnapshot(elements, !!options.compact);
+
+        // Truncate if too large
+        if (snapshot.length > MAX_SNAPSHOT_SIZE) {
+          snapshot = snapshot.substring(0, MAX_SNAPSHOT_SIZE) +
+            `\n\n... [TRUNCATED: ${elements.length} elements total, showing first ${MAX_SNAPSHOT_SIZE} chars]`;
+        }
+
+        return {
+          browserId,
+          snapshot,
+          url: page.url(),
+          title: await page.title(),
+        };
+      },
+      { concurrency: 'heavy' }
+    );
+  }
+
+  /**
+   * Format extracted elements into readable snapshot text
+   */
+  private formatSnapshot(elements: Array<{
+    tag: string; selector: string; text: string;
+    type?: string; value?: string; checked?: boolean;
+    disabled?: boolean; href?: string; placeholder?: string; section?: string;
+  }>, compact: boolean): string {
+    const lines: string[] = [];
+    let lastSection = '';
+
+    for (const el of elements) {
+      // Headings (structure context, full mode only)
+      if (!el.selector && (el.tag === 'h1' || el.tag === 'h2' || el.tag === 'h3')) {
+        lines.push(`\n## ${el.text}`);
+        continue;
+      }
+
+      // Section separator
+      if (!compact && el.section && el.section !== lastSection) {
+        lastSection = el.section;
+        lines.push(`\n--- ${el.section} ---`);
+      }
+
+      // Build element line
+      let line = `- ${el.tag}`;
+      if (el.type) line += `[type=${el.type}]`;
+      if (el.disabled) line += ' (disabled)';
+      line += `  →  ${el.selector}`;
+
+      // Add context
+      const details: string[] = [];
+      if (el.placeholder) details.push(`placeholder="${el.placeholder}"`);
+      if (el.value) details.push(`value="${el.value}"`);
+      if (el.checked !== undefined) details.push(el.checked ? 'checked' : 'unchecked');
+      if (el.text && el.text.length > 0) details.push(`"${el.text}"`);
+      if (el.href) details.push(`→ ${el.href}`);
+
+      if (details.length > 0) {
+        line += `  ${details.join(' | ')}`;
+      }
+
+      lines.push(line);
+    }
+
+    return lines.join('\n');
+  }
+
+
+  /**
+   * Take screenshots from multiple browsers.
+   * OPTIMIZATION: Uses JPEG format with quality 70% for ~5x smaller files.
+   * For 9 browsers: ~4.5MB PNG → ~900KB JPEG
+   */
+  async parallelScreenshot(
+    browserIds?: string[],
+    options: { fullPage?: boolean; quality?: number; format?: 'png' | 'jpeg' } = {}
+  ): Promise<ParallelResults<Buffer>> {
+    // Use JPEG with quality 70% by default for much smaller files
+    const format = options.format ?? 'jpeg';
+    const quality = format === 'jpeg' ? (options.quality ?? 70) : undefined;
+    
+    // Lower concurrency for heavy screenshot operations
+    return this.executeParallel(
+      browserIds, 
+      async (page) => {
+        return await page.screenshot({ 
+          fullPage: options.fullPage,
+          type: format,
+          quality,
+        });
+      },
+      { concurrency: 'heavy' }
+    );
+  }
+
+
+  // ==================== HUMAN-LIKE HELPERS ====================
+
+  /** Get or create a human profile for a browser */
+  private getProfile(browserId: string): HumanProfile {
+    let profile = this.profiles.get(browserId);
+    if (!profile) {
+      profile = generateProfile(browserId);
+      this.profiles.set(browserId, profile);
+    }
+    return profile;
+  }
+
+  /** Get last known mouse position, or a random starting position */
+  private getMousePos(browserId: string): { x: number; y: number } {
+    return this.lastMousePosition.get(browserId) ?? {
+      x: 200 + Math.random() * 400,
+      y: 150 + Math.random() * 300,
+    };
+  }
+
+  /** Update tracked mouse position */
+  private setMousePos(browserId: string, pos: { x: number; y: number }): void {
+    this.lastMousePosition.set(browserId, pos);
+  }
+
+  // ==================== REF-BASED INTERACTION (human-like) ====================
+
+  async parallelClick(
+    selector: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<void>> {
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const profile = this.getProfile(browserId);
+      const locator = page.locator(selector);
+      await locator.waitFor({ state: 'visible', timeout: 5000 });
+
+      await ensureCursor(page);
+      await preActionDelay(profile);
+
+      const { target } = await getClickTarget(page, locator);
+      const fromPos = this.getMousePos(browserId);
+      await humanClick(page, target, fromPos, profile);
+      this.setMousePos(browserId, target);
+    });
+  }
+
+  async parallelFill(
+    selector: string,
+    text: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<string>> {
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const profile = this.getProfile(browserId);
+      const locator = page.locator(selector);
+      await locator.waitFor({ state: 'visible', timeout: 5000 });
+
+      await ensureCursor(page);
+      await preActionDelay(profile);
+
+      // Human-like click to focus
+      const { target } = await getClickTarget(page, locator);
+      const fromPos = this.getMousePos(browserId);
+      await humanClick(page, target, fromPos, profile);
+      this.setMousePos(browserId, target);
+
+      // Clear existing content
+      await humanDelay(80, 200);
+      await page.keyboard.press('Meta+a');
+      await humanDelay(30, 80);
+      await page.keyboard.press('Backspace');
+      await humanDelay(50, 150);
+
+      // Type via CDP with human-like delays
+      await humanTypeText(page, text, profile);
+
+      return `filled "${text}"`;
+    });
+  }
+
+  async parallelFillMulti(
+    selector: string,
+    texts: TextMapping
+  ): Promise<ParallelResults<void>> {
+    const browserIds = Object.keys(texts);
+
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const text = texts[browserId];
+      if (!text) throw new Error(`No text provided for browser ${browserId}`);
+
+      const profile = this.getProfile(browserId);
+      const locator = page.locator(selector);
+      await locator.waitFor({ state: 'visible', timeout: 5000 });
+
+      await ensureCursor(page);
+      await preActionDelay(profile);
+
+      // Human-like click to focus
+      const { target } = await getClickTarget(page, locator);
+      const fromPos = this.getMousePos(browserId);
+      await humanClick(page, target, fromPos, profile);
+      this.setMousePos(browserId, target);
+
+      // Clear + type via CDP
+      await humanDelay(80, 200);
+      await page.keyboard.press('Meta+a');
+      await humanDelay(30, 80);
+      await page.keyboard.press('Backspace');
+      await humanDelay(50, 150);
+
+      await humanTypeText(page, text, profile);
+    });
+  }
+
+  async parallelType(
+    selector: string,
+    text: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<void>> {
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const profile = this.getProfile(browserId);
+      const locator = page.locator(selector);
+      await locator.waitFor({ state: 'visible', timeout: 5000 });
+
+      await ensureCursor(page);
+
+      // Click to focus with human-like movement
+      const { target } = await getClickTarget(page, locator);
+      const fromPos = this.getMousePos(browserId);
+      await humanClick(page, target, fromPos, profile);
+      this.setMousePos(browserId, target);
+
+      await humanDelay(50, 150);
+
+      // Type via CDP with human-like delays
+      await humanTypeText(page, text, profile);
+    });
+  }
+
+  async parallelHover(
+    selector: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<void>> {
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const profile = this.getProfile(browserId);
+      const locator = page.locator(selector);
+      await locator.waitFor({ state: 'visible', timeout: 5000 });
+
+      await ensureCursor(page);
+      await preActionDelay(profile);
+
+      const { target } = await getClickTarget(page, locator);
+      const fromPos = this.getMousePos(browserId);
+      await humanMouseMove(page, fromPos, target, profile);
+      this.setMousePos(browserId, target);
+    });
+  }
+
+  async parallelSelectOption(
+    selector: string,
+    values: string[],
+    browserIds?: string[]
+  ): Promise<ParallelResults<string[]>> {
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const profile = this.getProfile(browserId);
+      const locator = page.locator(selector);
+      await locator.waitFor({ state: 'visible', timeout: 5000 });
+
+      await ensureCursor(page);
+      await preActionDelay(profile);
+
+      // Human-like click to open dropdown
+      const { target } = await getClickTarget(page, locator);
+      const fromPos = this.getMousePos(browserId);
+      await humanClick(page, target, fromPos, profile);
+      this.setMousePos(browserId, target);
+
+      await humanDelay(200, 500);
+
+      return await locator.selectOption(values);
+    });
+  }
+
+  async parallelPressKey(
+    key: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<void>> {
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      await preActionDelay(this.getProfile(browserId));
+      await page.keyboard.press(key);
+    });
+  }
+
+  async parallelClickCoordinates(
+    coordinates: Record<string, { x: number; y: number }>,
+    options: { center?: number; timeout?: number; fromViewport?: boolean } = {}
+  ): Promise<ParallelResults<{ clickedAt: { x: number; y: number }; documentY: number; scrollY: number }>> {
+    const browserIds = Object.keys(coordinates);
+
+    return this.executeParallel(
+      browserIds,
+      async (page, browserId) => {
+        const profile = this.getProfile(browserId);
+        const target = coordinates[browserId];
+        if (!target) {
+          throw new Error(`No coordinates provided for browser ${browserId}`);
+        }
+
+        const viewport = page.viewportSize();
+        if (!viewport) {
+          throw new Error('Viewport size is not available for the page');
+        }
+
+        await ensureCursor(page);
+        await preActionDelay(profile);
+
+        if (options.fromViewport !== false) {
+          const clickX = Math.max(0, Math.min(Math.round(target.x), viewport.width - 1));
+          const clickY = Math.max(0, Math.min(Math.round(target.y), viewport.height - 1));
+
+          const fromPos = this.getMousePos(browserId);
+          await humanClick(page, { x: clickX, y: clickY }, fromPos, profile);
+          this.setMousePos(browserId, { x: clickX, y: clickY });
+
+          const scrollY = await page.evaluate(() => (globalThis as any).scrollY ?? 0);
+          return {
+            clickedAt: { x: clickX, y: clickY },
+            documentY: scrollY + clickY,
+            scrollY,
+          };
+        } else {
+          const desiredCenter = options.center ?? viewport.height / 2;
+          const desiredScroll = Math.max(0, Math.floor(target.y - desiredCenter));
+
+          await page.evaluate((scrollY) => {
+            (globalThis as any).scrollTo?.(0, scrollY);
+          }, desiredScroll);
+          const actualScroll = await page.evaluate(() => (globalThis as any).scrollY ?? 0);
+
+          const clickX = Math.max(0, Math.min(Math.round(target.x), viewport.width - 1));
+          const clickY = Math.round(target.y - actualScroll);
+
+          if (clickY < 0 || clickY > viewport.height) {
+            throw new Error(
+              `Target Y=${target.y} is outside viewport after scrolling (scrollY=${actualScroll}, viewportHeight=${viewport.height})`
+            );
+          }
+
+          const fromPos = this.getMousePos(browserId);
+          await humanClick(page, { x: clickX, y: clickY }, fromPos, profile);
+          this.setMousePos(browserId, { x: clickX, y: clickY });
+
+          return {
+            clickedAt: { x: clickX, y: clickY },
+            documentY: target.y,
+            scrollY: actualScroll,
+          };
+        }
+      },
+      { timeout: options.timeout ?? this.defaultTimeout }
+    );
+  }
+
+  /**
+   * Click at center of normalized bounding box (from OmniParser output)
+   */
+  async parallelClickNormalizedBox(
+    box: [number, number, number, number],
+    browserIds: string[],
+    options: { button?: 'left' | 'right' | 'middle'; clickCount?: number; delay?: number; timeout?: number } = {}
+  ): Promise<ParallelResults<{ absoluteX: number; absoluteY: number; viewport: { width: number; height: number } }>> {
+    const [x1, y1, x2, y2] = box;
+
+    if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1 || y1 < 0 || y1 > 1 || y2 < 0 || y2 > 1) {
+      throw new Error('Coordinates must be normalized (0-1 range)');
+    }
+
+    const normalizedX = (x1 + x2) / 2;
+    const normalizedY = (y1 + y2) / 2;
+
+    return this.executeParallel(
+      browserIds,
+      async (page, browserId) => {
+        const profile = this.getProfile(browserId);
+        const viewport = page.viewportSize();
+        if (!viewport) {
+          throw new Error('Viewport size is not available');
+        }
+
+        const absoluteX = Math.round(normalizedX * viewport.width);
+        const absoluteY = Math.round(normalizedY * viewport.height);
+
+        await ensureCursor(page);
+        await preActionDelay(profile);
+
+        const fromPos = this.getMousePos(browserId);
+        await humanMouseMove(page, fromPos, { x: absoluteX, y: absoluteY }, profile);
+
+        await page.mouse.down({ button: options.button || 'left' });
+        await humanDelay(50, 120);
+        await page.mouse.up({ button: options.button || 'left' });
+
+        if (options.clickCount && options.clickCount > 1) {
+          for (let i = 1; i < options.clickCount; i++) {
+            await humanDelay(80, 150);
+            await page.mouse.down({ button: options.button || 'left' });
+            await humanDelay(30, 80);
+            await page.mouse.up({ button: options.button || 'left' });
+          }
+        }
+
+        this.setMousePos(browserId, { x: absoluteX, y: absoluteY });
+        return { absoluteX, absoluteY, viewport };
+      },
+      { timeout: options.timeout ?? this.defaultTimeout }
+    );
+  }
+
+  // ==================== CODE EXECUTION ====================
+
+  async parallelRunCode(
+    code: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<unknown>> {
+    return this.executeParallel(browserIds, async (page) => {
+      const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+      const fn = new AsyncFunction('page', code);
+      return await fn(page);
+    });
+  }
+
+  async parallelRunCodeWithVariables(
+    codeTemplate: string,
+    variables: VariableMapping
+  ): Promise<ParallelResults<unknown>> {
+    const browserIds = Object.keys(variables);
+    
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const vars = variables[browserId] || {};
+      
+      let code = codeTemplate;
+      for (const [key, value] of Object.entries(vars)) {
+        code = code.replace(new RegExp(`{{${key}}}`, 'g'), value);
+      }
+      
+      const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+      const fn = new AsyncFunction('page', code);
+      return await fn(page);
+    });
+  }
+
+  async parallelEvaluate(
+    script: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<unknown>> {
+    return this.executeParallel(browserIds, async (page) => {
+      return await page.evaluate(script);
+    });
+  }
+
+  // ==================== WAITING ====================
+
+  async parallelWaitFor(
+    options: { time?: number; text?: string; textGone?: string },
+    browserIds?: string[]
+  ): Promise<ParallelResults<void>> {
+    // Calculate timeout: for time-based waits, use the wait time + buffer;
+    // for text waits, use 30s default and pass it to Playwright's waitFor
+    const waitTimeMs = options.time ? options.time * 1000 : 0;
+    const textTimeout = 30000;
+    const timeout = waitTimeMs + textTimeout + 5000; // buffer for overhead
+
+    return this.executeParallel(browserIds, async (page) => {
+      if (options.time) {
+        await page.waitForTimeout(options.time * 1000);
+      }
+      if (options.text) {
+        await page.getByText(options.text).waitFor({ timeout: textTimeout });
+      }
+      if (options.textGone) {
+        await page.getByText(options.textGone).waitFor({ state: 'hidden', timeout: textTimeout });
+      }
+    }, { timeout });
+  }
+
+  // ==================== FILE OPERATIONS (downloads, uploads, drag&drop) ====================
+
+  /** Cached project files directory path */
+  private projectFilesDir: string | null | undefined = undefined;
+
+  /** Fetch project files directory from API (cached) */
+  async getProjectFilesDir(): Promise<string | null> {
+    if (this.projectFilesDir !== undefined) return this.projectFilesDir;
+
+    const apiUrl = process.env.API_SERVER_URL;
+    const userId = process.env.USER_ID;
+    const deviceId = process.env.DEVICE_ID;
+
+    if (!apiUrl || !userId) {
+      this.projectFilesDir = null;
+      return null;
+    }
+
+    try {
+      const params = new URLSearchParams({ userId });
+      if (deviceId) params.set('deviceId', deviceId);
+      const resp = await fetch(`${apiUrl}/api/project-path?${params}`);
+      const data = await resp.json() as { localPath: string | null };
+      this.projectFilesDir = data.localPath;
+      console.error(`[Executor] Project files dir: ${this.projectFilesDir}`);
+      return this.projectFilesDir;
+    } catch (e) {
+      console.error(`[Executor] Failed to fetch project path:`, e);
+      this.projectFilesDir = null;
+      return null;
+    }
+  }
+
+  /** Configure browser to download files to project directory */
+  async setupDownloads(
+    browserIds?: string[]
+  ): Promise<ParallelResults<string>> {
+    const dir = await this.getProjectFilesDir();
+    if (!dir) {
+      throw new Error('Project files directory not available — file relay may not be connected');
+    }
+
+    return this.executeParallel(browserIds, async (page) => {
+      const cdp = await page.context().newCDPSession(page);
+      try {
+        await cdp.send('Page.setDownloadBehavior', {
+          behavior: 'allow',
+          downloadPath: dir,
+        });
+      } finally {
+        await cdp.detach().catch(() => {});
+      }
+      return `Downloads → ${dir}`;
+    });
+  }
+
+  /** List files in the project directory */
+  async listProjectFiles(): Promise<string[]> {
+    const dir = await this.getProjectFilesDir();
+    if (!dir) return [];
+
+    const ids = this.getBrowserIds();
+    if (ids.length === 0) return [];
+
+    const browser = this.browsers.get(ids[0]);
+    if (!browser) return [];
+
+    try {
+      const cdp = await browser.page.context().newCDPSession(browser.page);
+      try {
+        const result = await cdp.send('Runtime.evaluate', {
+          expression: `
+            (() => {
+              try {
+                const fs = require('fs');
+                const path = require('path');
+                const dir = ${JSON.stringify(dir)};
+                if (!fs.existsSync(dir)) return JSON.stringify([]);
+                const files = fs.readdirSync(dir).filter(f => !f.startsWith('.'));
+                return JSON.stringify(files.map(f => {
+                  const stat = fs.statSync(path.join(dir, f));
+                  return { name: f, size: stat.size, modified: stat.mtimeMs };
+                }));
+              } catch(e) { return JSON.stringify({ error: e.message }); }
+            })()
+          `,
+          returnByValue: true,
+        });
+
+        const value = result.result?.value;
+        if (typeof value === 'string') {
+          return JSON.parse(value);
+        }
+      } finally {
+        await cdp.detach().catch(() => {});
+      }
+    } catch {
+      // fallback — return empty
+    }
+    return [];
+  }
+
+  /** Upload a file from project directory via filechooser (selector-based) */
+  async parallelUploadFile(
+    selector: string,
+    fileName: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<string>> {
+    const dir = await this.getProjectFilesDir();
+    if (!dir) {
+      throw new Error('Project files directory not available');
+    }
+
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const profile = this.getProfile(browserId);
+      const locator = page.locator(selector);
+      await locator.waitFor({ state: 'visible', timeout: 5000 });
+
+      await ensureCursor(page);
+      await preActionDelay(profile);
+
+      const fileChooserPromise = page.waitForEvent('filechooser', { timeout: 10000 });
+
+      const { target } = await getClickTarget(page, locator);
+      const fromPos = this.getMousePos(browserId);
+      await humanClick(page, target, fromPos, profile);
+      this.setMousePos(browserId, target);
+
+      const fileChooser = await fileChooserPromise;
+      const filePath = `${dir}/${fileName}`;
+      await fileChooser.setFiles(filePath);
+
+      return `Uploaded "${fileName}" from ${dir}`;
+    }, { timeout: 15000 });
+  }
+
+  // ==================== BATCH FORM FILL ====================
+
+  async parallelFillForm(
+    fields: Array<{ selector: string; value: string }>,
+    browserIds?: string[]
+  ): Promise<ParallelResults<string>> {
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const profile = this.getProfile(browserId);
+      const filled: string[] = [];
+
+      for (const field of fields) {
+        const locator = page.locator(field.selector);
+        await locator.waitFor({ state: 'visible', timeout: 5000 });
+
+        await ensureCursor(page);
+        await preActionDelay(profile);
+
+        // Human-like click to focus
+        const { target } = await getClickTarget(page, locator);
+        const fromPos = this.getMousePos(browserId);
+        await humanClick(page, target, fromPos, profile);
+        this.setMousePos(browserId, target);
+
+        // Clear existing content
+        await humanDelay(80, 200);
+        await page.keyboard.press('Meta+a');
+        await humanDelay(30, 80);
+        await page.keyboard.press('Backspace');
+        await humanDelay(50, 150);
+
+        // Type value
+        await humanTypeText(page, field.value, profile);
+        filled.push(`${field.selector}="${field.value}"`);
+      }
+
+      return `Filled ${filled.length} fields: ${filled.join(', ')}`;
+    }, { timeout: fields.length * 5000 + 5000 });
+  }
+
+  // ==================== ELEMENT DRAG & DROP ====================
+
+  async parallelDrag(
+    startSelector: string,
+    endSelector: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<string>> {
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const profile = this.getProfile(browserId);
+
+      const startLocator = page.locator(startSelector);
+      const endLocator = page.locator(endSelector);
+      await startLocator.waitFor({ state: 'visible', timeout: 5000 });
+      await endLocator.waitFor({ state: 'visible', timeout: 5000 });
+
+      await ensureCursor(page);
+      await preActionDelay(profile);
+
+      const { target: startPos } = await getClickTarget(page, startLocator);
+      const { target: endPos } = await getClickTarget(page, endLocator);
+      const fromPos = this.getMousePos(browserId);
+
+      // Move to start element
+      await humanMouseMove(page, fromPos, startPos, profile);
+      await humanDelay(50, 150);
+
+      // Mouse down on start
+      await page.mouse.down();
+      await humanDelay(100, 250);
+
+      // Move to end element (drag)
+      await humanMouseMove(page, startPos, endPos, profile);
+      await humanDelay(50, 150);
+
+      // Mouse up on end (drop)
+      await page.mouse.up();
+      this.setMousePos(browserId, endPos);
+
+      return `Dragged "${startSelector}" → "${endSelector}"`;
+    }, { timeout: 15000 });
+  }
+
+  // ==================== TAB MANAGEMENT ====================
+
+  async parallelTabs(
+    action: 'list' | 'new' | 'close' | 'select',
+    options: { index?: number; url?: string } = {},
+    browserIds?: string[]
+  ): Promise<ParallelResults<unknown>> {
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const browser = this.browsers.get(browserId);
+      if (!browser) throw new Error(`Browser ${browserId} not found`);
+
+      const context = browser.context;
+      const pages = context.pages();
+
+      switch (action) {
+        case 'list': {
+          return pages.map((p, i) => ({
+            index: i,
+            url: p.url(),
+            active: p === browser.page,
+          }));
+        }
+        case 'new': {
+          const newPage = await context.newPage();
+          if (options.url) {
+            await newPage.goto(options.url, { waitUntil: 'domcontentloaded' });
+          }
+          browser.page = newPage;
+          newPage.setDefaultTimeout(this.defaultTimeout);
+          newPage.setDefaultNavigationTimeout(60000);
+          this._setupPageTracking(browserId, newPage);
+          return { index: context.pages().length - 1, url: newPage.url() };
+        }
+        case 'close': {
+          const idx = options.index ?? pages.indexOf(browser.page);
+          if (idx < 0 || idx >= pages.length) throw new Error(`Tab index ${idx} out of range (0-${pages.length - 1})`);
+          const targetPage = pages[idx];
+          await targetPage.close();
+          if (targetPage === browser.page) {
+            const remaining = context.pages();
+            if (remaining.length > 0) {
+              browser.page = remaining[Math.min(idx, remaining.length - 1)];
+            }
+          }
+          return { closed: idx, remaining: context.pages().length };
+        }
+        case 'select': {
+          if (options.index === undefined) throw new Error('index required for select action');
+          const currentPages = context.pages();
+          if (options.index < 0 || options.index >= currentPages.length) {
+            throw new Error(`Tab index ${options.index} out of range (0-${currentPages.length - 1})`);
+          }
+          browser.page = currentPages[options.index];
+          await browser.page.bringToFront();
+          return { selected: options.index, url: browser.page.url() };
+        }
+      }
+    }, { timeout: 30000 });
+  }
+
+  /** Set up console/network tracking on a new page */
+  private _setupPageTracking(browserId: string, page: Page): void {
+    const consoleLog = this.consoleMessages.get(browserId);
+    if (consoleLog) {
+      page.on('console', (msg) => {
+        consoleLog.push({ type: msg.type(), text: msg.text(), timestamp: Date.now() });
+        if (consoleLog.length > 1000) consoleLog.shift();
+      });
+    }
+    const networkLog = this.networkRequests.get(browserId);
+    if (networkLog) {
+      page.on('response', (response) => {
+        const req = response.request();
+        networkLog.push({
+          url: req.url(),
+          method: req.method(),
+          status: response.status(),
+          resourceType: req.resourceType(),
+          timestamp: Date.now(),
+        });
+        if (networkLog.length > 1000) networkLog.shift();
+      });
+    }
+  }
+
+  // ==================== DIALOG HANDLING ====================
+
+  async parallelHandleDialog(
+    accept: boolean,
+    promptText?: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<string>> {
+    return this.executeParallel(browserIds, async (page) => {
+      return new Promise<string>((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error('No dialog appeared within 10 seconds'));
+        }, 10000);
+
+        page.once('dialog', async (dialog) => {
+          clearTimeout(timeout);
+          const type = dialog.type();
+          const message = dialog.message();
+          try {
+            if (accept) {
+              await dialog.accept(promptText);
+            } else {
+              await dialog.dismiss();
+            }
+            resolve(`${accept ? 'Accepted' : 'Dismissed'} ${type} dialog: "${message}"`);
+          } catch (e) {
+            reject(e);
+          }
+        });
+      });
+    }, { timeout: 15000 });
+  }
+
+  // ==================== CONSOLE MESSAGES ====================
+
+  async parallelConsoleMessages(
+    onlyErrors?: boolean,
+    browserIds?: string[]
+  ): Promise<ParallelResults<Array<{ type: string; text: string; timestamp: number }>>> {
+    await this.ensureBrowsersLoaded();
+    const ids = browserIds ?? this.getBrowserIds();
+
+    const results = ids.map((id) => {
+      let messages = this.consoleMessages.get(id) || [];
+      if (onlyErrors) {
+        messages = messages.filter(m => m.type === 'error');
+      }
+      return {
+        browserId: id,
+        success: true as const,
+        result: [...messages],
+        duration: 0,
+      };
+    });
+
+    return {
+      results,
+      totalDuration: 0,
+      successCount: results.length,
+      failureCount: 0,
+    };
+  }
+
+  // ==================== NETWORK REQUESTS ====================
+
+  async parallelNetworkRequests(
+    browserIds?: string[]
+  ): Promise<ParallelResults<Array<{ url: string; method: string; status?: number; resourceType: string; timestamp: number }>>> {
+    await this.ensureBrowsersLoaded();
+    const ids = browserIds ?? this.getBrowserIds();
+
+    const results = ids.map((id) => {
+      const requests = this.networkRequests.get(id) || [];
+      return {
+        browserId: id,
+        success: true as const,
+        result: [...requests],
+        duration: 0,
+      };
+    });
+
+    return {
+      results,
+      totalDuration: 0,
+      successCount: results.length,
+      failureCount: 0,
+    };
+  }
+
+  /** Drag and drop a file onto a dropzone (selector-based) */
+  async parallelDragDropFile(
+    selector: string,
+    fileName: string,
+    browserIds?: string[]
+  ): Promise<ParallelResults<string>> {
+    const dir = await this.getProjectFilesDir();
+    if (!dir) {
+      throw new Error('Project files directory not available');
+    }
+
+    return this.executeParallel(browserIds, async (page, browserId) => {
+      const profile = this.getProfile(browserId);
+      const locator = page.locator(selector);
+      await locator.waitFor({ state: 'visible', timeout: 5000 });
+
+      await ensureCursor(page);
+      await preActionDelay(profile);
+
+      const { target } = await getClickTarget(page, locator);
+      const fromPos = this.getMousePos(browserId);
+      await humanMouseMove(page, fromPos, target, profile);
+      this.setMousePos(browserId, target);
+
+      const filePath = `${dir}/${fileName}`;
+
+      await page.evaluate(async ({ x, y, fileName, filePath }: { x: number; y: number; fileName: string; filePath: string }) => {
+        const dropzone = document.elementFromPoint(x, y);
+        if (!dropzone) throw new Error('No element at drop coordinates');
+
+        const dataTransfer = new DataTransfer();
+        try {
+          const resp = await fetch(`file://${filePath}`);
+          const blob = await resp.blob();
+          const file = new File([blob], fileName, { type: blob.type });
+          dataTransfer.items.add(file);
+        } catch {
+          const file = new File([''], fileName);
+          dataTransfer.items.add(file);
+        }
+
+        const events = ['dragenter', 'dragover', 'drop'];
+        for (const eventType of events) {
+          const event = new DragEvent(eventType, {
+            bubbles: true,
+            cancelable: true,
+            dataTransfer,
+          });
+          dropzone.dispatchEvent(event);
+          await new Promise(r => setTimeout(r, 50));
+        }
+      }, { x: target.x, y: target.y, fileName, filePath });
+
+      return `Dropped "${fileName}" onto element`;
+    }, { timeout: 15000 });
+  }
+}