otherwise-cli 0.1.0

package/src/browser/session.js

@@ -0,0 +1,1109 @@
+/**
+ * Browser Session Manager
+ *
+ * Manages a persistent Playwright browser session across tool calls.
+ * Uses singleton pattern - one browser instance per agent session.
+ * Supports configurable headless/visible mode and auto-cleanup on idle.
+ * Uses user's default/selected browser (browserChannel in config) when set.
+ */
+
+import { config as cliConfig } from "../config.js";
+
+async function getChromium() {
+  try {
+    const pw = await import("playwright");
+    return pw.chromium;
+  } catch {
+    throw new Error(
+      "Playwright is not installed. Run: npx playwright install chromium"
+    );
+  }
+}
+
+// Singleton browser state
+let browserInstance = null;
+let currentPage = null;
+let idleTimeout = null;
+
+// Default timeout for idle cleanup (5 minutes)
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000;
+
+// Default timeout for operations (30 seconds)
+const OPERATION_TIMEOUT_MS = 30000;
+
+// Realistic User-Agent strings (rotated randomly)
+const USER_AGENTS = [
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15",
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:122.0) Gecko/20100101 Firefox/122.0",
+];
+
+// Common browser headers to appear more legitimate
+const BROWSER_HEADERS = {
+  Accept:
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
+  "Accept-Language": "en-US,en;q=0.9",
+  "Accept-Encoding": "gzip, deflate, br",
+  "Cache-Control": "no-cache",
+  Pragma: "no-cache",
+  "Sec-Ch-Ua":
+    '"Not A(Brand";v="99", "Google Chrome";v="121", "Chromium";v="121"',
+  "Sec-Ch-Ua-Mobile": "?0",
+  "Sec-Ch-Ua-Platform": '"macOS"',
+  "Sec-Fetch-Dest": "document",
+  "Sec-Fetch-Mode": "navigate",
+  "Sec-Fetch-Site": "none",
+  "Sec-Fetch-User": "?1",
+  "Upgrade-Insecure-Requests": "1",
+};
+
+/**
+ * Get a random User-Agent string
+ */
+function getRandomUserAgent() {
+  return USER_AGENTS[Math.floor(Math.random() * USER_AGENTS.length)];
+}
+
+/**
+ * Parse WEBSEARCH_PROXY or HTTPS_PROXY/HTTP_PROXY for Playwright.
+ * @returns {{ server: string, username?: string, password?: string } | null}
+ */
+function getWebSearchProxyConfig() {
+  const raw =
+    process.env.WEBSEARCH_PROXY ||
+    process.env.HTTPS_PROXY ||
+    process.env.HTTP_PROXY ||
+    null;
+  if (!raw || !raw.startsWith("http")) return null;
+  try {
+    const u = new URL(raw);
+    const server = `${u.protocol}//${u.hostname}${u.port ? ":" + u.port : ""}`;
+    const username = u.username || undefined;
+    const password = u.password || undefined;
+    return {
+      server,
+      ...(username && { username }),
+      ...(password && { password }),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reset the idle timeout - called after each operation
+ */
+function resetIdleTimeout() {
+  if (idleTimeout) {
+    clearTimeout(idleTimeout);
+  }
+  idleTimeout = setTimeout(async () => {
+    console.log("[Browser] Idle timeout reached, closing browser...");
+    await closeBrowser();
+  }, IDLE_TIMEOUT_MS);
+}
+
+/**
+ * Build Playwright launch options from config (user's default/selected browser).
+ * When config has no browserChannel, falls back to CLI store so fetchHtmlWithBrowser uses same browser.
+ * @param {object} config - { browserChannel?: string | null, browserHeadless?: boolean }
+ * @returns {{ headless: boolean, channel: string, args: string[] }}
+ */
+function getLaunchOptions(config = {}, options = {}) {
+  // Interactive session: always visible. One-off fetches (e.g. SERP) can stay headless.
+  const headless =
+    options.forceVisible === true ? false : config.browserHeadless !== false;
+  let channel =
+    (config.browserChannel && String(config.browserChannel).trim()) || null;
+  if (channel == null && typeof cliConfig?.get === "function") {
+    channel = cliConfig.get("browserChannel") || null;
+  }
+  const args = [
+    "--no-sandbox",
+    "--disable-setuid-sandbox",
+    "--disable-dev-shm-usage",
+    "--disable-accelerated-2d-canvas",
+    "--disable-gpu",
+    "--disable-blink-features=AutomationControlled",
+    "--disable-features=IsolateOrigins,site-per-process",
+    "--disable-infobars",
+    "--window-size=1280,800",
+  ];
+  // Use configured channel (chrome | msedge | chromium) or fall back to bundled chromium
+  const effectiveChannel =
+    channel === "chrome" || channel === "msedge" || channel === "chromium"
+      ? channel
+      : "chromium";
+  return {
+    headless,
+    channel: effectiveChannel,
+    args,
+  };
+}
+
+/**
+ * Get or create a browser page
+ * @param {object} config - Configuration object with browserHeadless, browserChannel
+ * @returns {Promise<Page>} - Playwright page instance
+ */
+export async function getBrowserPage(config = {}) {
+  resetIdleTimeout();
+
+  // If we have a valid page, return it
+  if (currentPage && !currentPage.isClosed()) {
+    return currentPage;
+  }
+
+  // If we have a browser but no page, create a new page
+  if (browserInstance) {
+    try {
+      currentPage = await browserInstance.newPage();
+      return currentPage;
+    } catch (err) {
+      // Browser might be in a bad state, close and recreate
+      console.log("[Browser] Browser in bad state, recreating...");
+      await closeBrowser();
+    }
+  }
+
+  const { headless, channel, args } = getLaunchOptions(config, {
+    forceVisible: true,
+  });
+  console.log(
+    `[Browser] Launching browser (channel: ${channel}, headless: ${headless})...`,
+  );
+
+  try {
+    const chromium = await getChromium();
+    browserInstance = await chromium.launch({
+      headless,
+      channel,
+      args,
+    });
+
+    // Create a new context with stealth settings
+    const userAgent = getRandomUserAgent();
+    const context = await browserInstance.newContext({
+      userAgent,
+      viewport: { width: 1280, height: 800 },
+      extraHTTPHeaders: BROWSER_HEADERS,
+      // Enable JavaScript and cookies like a real browser
+      javaScriptEnabled: true,
+      ignoreHTTPSErrors: true,
+      // Emulate real browser behavior
+      locale: "en-US",
+      timezoneId: "America/New_York",
+    });
+
+    // Create a new page
+    currentPage = await context.newPage();
+
+    // Set default timeouts
+    currentPage.setDefaultTimeout(OPERATION_TIMEOUT_MS);
+    currentPage.setDefaultNavigationTimeout(OPERATION_TIMEOUT_MS);
+
+    // Apply stealth scripts to evade detection
+    await currentPage.addInitScript(() => {
+      // Remove webdriver flag
+      Object.defineProperty(navigator, "webdriver", {
+        get: () => undefined,
+      });
+
+      // Spoof plugins
+      Object.defineProperty(navigator, "plugins", {
+        get: () => [1, 2, 3, 4, 5],
+      });
+
+      // Spoof languages
+      Object.defineProperty(navigator, "languages", {
+        get: () => ["en-US", "en"],
+      });
+
+      // Hide automation
+      window.chrome = { runtime: {} };
+
+      // Spoof permissions
+      const originalQuery = window.navigator.permissions.query;
+      window.navigator.permissions.query = (parameters) =>
+        parameters.name === "notifications"
+          ? Promise.resolve({ state: Notification.permission })
+          : originalQuery(parameters);
+    });
+
+    console.log("[Browser] Browser launched successfully with stealth mode");
+    console.log(
+      "[Browser] Using User-Agent:",
+      userAgent.substring(0, 50) + "...",
+    );
+    return currentPage;
+  } catch (err) {
+    console.error("[Browser] Failed to launch browser:", err);
+    throw new Error(`Failed to launch browser: ${err.message}`);
+  }
+}
+
+/**
+ * Close the browser and cleanup resources
+ */
+export async function closeBrowser() {
+  if (idleTimeout) {
+    clearTimeout(idleTimeout);
+    idleTimeout = null;
+  }
+
+  if (currentPage) {
+    try {
+      await currentPage.close();
+    } catch (err) {
+      // Page might already be closed
+    }
+    currentPage = null;
+  }
+
+  if (browserInstance) {
+    try {
+      await browserInstance.close();
+      console.log("[Browser] Browser closed");
+    } catch (err) {
+      console.error("[Browser] Error closing browser:", err);
+    }
+    browserInstance = null;
+  }
+}
+
+/**
+ * Get a snapshot of the current page state
+ * Useful for providing context to the LLM
+ * @returns {object|null} - Page state or null if no page
+ */
+export function getPageSnapshot() {
+  if (!currentPage || currentPage.isClosed()) {
+    return null;
+  }
+
+  return {
+    url: currentPage.url(),
+    title: currentPage.title(),
+  };
+}
+
+/**
+ * Check if browser is currently active
+ * @returns {boolean}
+ */
+export function isBrowserActive() {
+  return (
+    browserInstance !== null && currentPage !== null && !currentPage.isClosed()
+  );
+}
+
+/**
+ * Helper to check if a locator has any matching elements with a short timeout
+ * This prevents each selector strategy from waiting the full default timeout
+ * @param {Locator} locator - Playwright locator
+ * @param {number} timeout - Timeout in ms (default: 2000)
+ * @returns {Promise<boolean>} - True if element exists
+ */
+async function hasElement(locator, timeout = 2000) {
+  try {
+    // Use waitFor with a short timeout to check existence
+    await locator.first().waitFor({ state: "attached", timeout });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Find the best visible element from a locator when there are multiple matches
+ * Prioritizes: 1) visible in viewport, 2) visible at all, 3) first match
+ * @param {Locator} locator - Playwright locator with potential multiple matches
+ * @param {Page} page - Playwright page
+ * @returns {Promise<Locator>} - Best matching element
+ */
+async function findBestVisibleElement(locator, page) {
+  const count = await locator.count();
+
+  // If only one match, return it
+  if (count <= 1) {
+    return locator.first();
+  }
+
+  console.log(
+    `[Browser] Found ${count} matching elements, prioritizing visible ones`,
+  );
+
+  // Get viewport dimensions
+  const viewport = page.viewportSize() || { width: 1280, height: 720 };
+
+  // Check each element for visibility and viewport position
+  let bestElement = null;
+  let bestScore = -1;
+
+  for (let i = 0; i < Math.min(count, 10); i++) {
+    // Check first 10 matches max
+    const element = locator.nth(i);
+
+    try {
+      const isVisible = await element.isVisible();
+      if (!isVisible) continue;
+
+      // Get bounding box to check if in viewport
+      const box = await element.boundingBox();
+      if (!box) continue;
+
+      let score = 1; // Base score for visible element
+
+      // Higher score if fully in viewport
+      const inViewportX = box.x >= 0 && box.x + box.width <= viewport.width;
+      const inViewportY = box.y >= 0 && box.y + box.height <= viewport.height;
+      if (inViewportX && inViewportY) {
+        score += 10;
+      } else if (inViewportY) {
+        // At least vertically in viewport
+        score += 5;
+      }
+
+      // Prefer elements with unique identifying attributes (likely the "real" interactive element)
+      const hasId = await element.evaluate((el) => !!el.id);
+      const hasDataTestId = await element.evaluate((el) => !!el.dataset.testid);
+      const hasUniqueClass = await element.evaluate(
+        (el) =>
+          el.className && el.className.split(" ").some((c) => c.length > 5),
+      );
+
+      if (hasId) score += 3;
+      if (hasDataTestId) score += 3;
+      if (hasUniqueClass) score += 1;
+
+      // Prefer larger clickable area
+      const area = box.width * box.height;
+      if (area > 100) score += 1;
+      if (area > 500) score += 1;
+
+      if (score > bestScore) {
+        bestScore = score;
+        bestElement = element;
+      }
+    } catch {
+      // Element may have been removed, continue
+    }
+  }
+
+  if (bestElement) {
+    console.log(
+      `[Browser] Selected element with visibility score ${bestScore}`,
+    );
+    return bestElement;
+  }
+
+  // Fallback to first visible
+  console.log("[Browser] Falling back to first visible element");
+  return locator.first();
+}
+
+/**
+ * Smart element finder - tries multiple selector strategies
+ * Uses short timeouts for detection to avoid cumulative timeout buildup
+ * Supports Playwright-specific selectors like :has-text(), :text(), etc.
+ * @param {Page} page - Playwright page
+ * @param {string} selector - Selector string (CSS, text, Playwright pseudo-selectors, or aria)
+ * @returns {Promise<Locator>} - Element locator
+ */
+export async function findElement(page, selector) {
+  // Short timeout per strategy so we resolve or fail fast (was 2s; 800ms speeds up multi-strategy tries)
+  const DETECT_TIMEOUT = 800;
+
+  console.log(`[Browser] Finding element: "${selector}"`);
+
+  // Check if selector uses Playwright-specific pseudo-selectors
+  // These need to go through page.locator() directly, not querySelector
+  const playwrightPseudoSelectors = [
+    ":has-text(",
+    ":text(",
+    ":has(",
+    ":is(",
+    ":nth-match(",
+    ":visible",
+    ":above(",
+    ":below(",
+    ":left-of(",
+    ":right-of(",
+    ":near(",
+  ];
+  const isPlaywrightSelector = playwrightPseudoSelectors.some((ps) =>
+    selector.includes(ps),
+  );
+
+  // If it contains Playwright-specific pseudo-selectors, try it directly first
+  if (isPlaywrightSelector) {
+    try {
+      const locator = page.locator(selector);
+      if (await hasElement(locator, DETECT_TIMEOUT)) {
+        console.log(`[Browser] Found via Playwright selector: "${selector}"`);
+        return locator.first();
+      }
+    } catch (err) {
+      console.log(`[Browser] Playwright selector failed: ${err.message}`);
+      // Fall through to other strategies
+    }
+  }
+
+  // If it looks like a standard CSS selector (including a[href="..."]), try it directly
+  const looksLikeCss =
+    selector.startsWith("#") ||
+    selector.startsWith(".") ||
+    selector.startsWith("[") ||
+    selector.includes(">") ||
+    /^[a-zA-Z][a-zA-Z0-9]*\[/.test(selector.trim());
+  if (looksLikeCss) {
+    try {
+      const locator = page.locator(selector);
+      if (await hasElement(locator, DETECT_TIMEOUT)) {
+        console.log(`[Browser] Found via CSS selector: "${selector}"`);
+        return locator.first();
+      }
+    } catch (err) {
+      console.log(`[Browser] CSS selector failed: ${err.message}`);
+    }
+    // For a[href="value"] or [href="value"], try partial match a[href*="value"] (sites often use full URLs or extra params)
+    const hrefExactMatch =
+      selector.match(/^a\[href\s*=\s*["']([^"']+)["']\]$/i) ||
+      selector.match(/^\[href\s*=\s*["']([^"']+)["']\]$/i);
+    if (hrefExactMatch) {
+      const hrefValue = hrefExactMatch[1];
+      const tag = selector.startsWith("a") ? "a" : "*";
+      const partialSelector =
+        tag === "a"
+          ? `a[href*="${hrefValue.replace(/"/g, '\\"')}"]`
+          : `a[href*="${hrefValue.replace(/"/g, '\\"')}"]`;
+      try {
+        const locator = page.locator(partialSelector);
+        if (await hasElement(locator, DETECT_TIMEOUT)) {
+          console.log(`[Browser] Found via partial href: "${partialSelector}"`);
+          return await findBestVisibleElement(locator, page);
+        }
+      } catch (e) {
+        // ignore
+      }
+      // Also try link by accessible name (e.g. "Syrio_Forel" -> link text "Syrio Forel")
+      const slug = hrefValue.replace(/^.*\/wiki\//i, "").replace(/#.*$/, "");
+      const linkText = slug ? slug.replace(/_/g, " ").trim() : null;
+      if (linkText) {
+        try {
+          const byRole = page.getByRole("link", {
+            name: new RegExp(
+              linkText.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+              "i",
+            ),
+          });
+          if (await hasElement(byRole, DETECT_TIMEOUT)) {
+            console.log(`[Browser] Found via link role (name): "${linkText}"`);
+            return await findBestVisibleElement(byRole, page);
+          }
+        } catch (e) {
+          // ignore
+        }
+      }
+    }
+  }
+
+  // Try as text content (quoted strings)
+  if (selector.startsWith('"') && selector.endsWith('"')) {
+    const text = selector.slice(1, -1);
+    const locator = page.getByText(text, { exact: false });
+    if (await hasElement(locator, DETECT_TIMEOUT)) {
+      console.log(`[Browser] Found via quoted text: "${text}"`);
+      return locator.first();
+    }
+  }
+
+  // Try Playwright's getByText for :text() style selectors
+  const textMatch = selector.match(/^:text\(["'](.+)["']\)$/i);
+  if (textMatch) {
+    const text = textMatch[1];
+    const locator = page.getByText(text, { exact: false });
+    if (await hasElement(locator, DETECT_TIMEOUT)) {
+      console.log(`[Browser] Found via :text() pattern: "${text}"`);
+      return locator.first();
+    }
+  }
+
+  // Try role-based selectors (e.g., "button:Submit", "Input:Search Wikipedia", "link:Click here")
+  // Uses findBestVisibleElement to handle multiple matching roles. "Input" maps to "textbox".
+  const roleMatch = selector.match(
+    /^(button|link|textbox|input|checkbox|radio|combobox|menuitem|tab|option):(.+)$/i,
+  );
+  if (roleMatch) {
+    const [, role, name] = roleMatch;
+    const roleName =
+      role.toLowerCase() === "input" ? "textbox" : role.toLowerCase();
+    const nameStr =
+      name
+        .trim()
+        .replace(/^["']|["']$/g, "")
+        .trim() || name.trim();
+    const locator = page.getByRole(roleName, {
+      name: new RegExp(nameStr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i"),
+    });
+    if (await hasElement(locator, DETECT_TIMEOUT)) {
+      console.log(`[Browser] Found via role selector: ${role}:${name}`);
+      return await findBestVisibleElement(locator, page);
+    }
+  }
+
+  // Try common search input selectors when selector looks like a search prompt (e.g. "Search", "Search Wikipedia")
+  if (/\bsearch\b/i.test(selector) && selector.length < 80) {
+    for (const sel of [
+      'input[name="search"]',
+      'input[type="search"]',
+      "input[name='search']",
+      "[role='search'] input",
+      "form[role='search'] input",
+    ]) {
+      try {
+        const loc = page.locator(sel).first();
+        if (await hasElement(loc, DETECT_TIMEOUT)) {
+          console.log(`[Browser] Found via search input selector: ${sel}`);
+          return loc;
+        }
+      } catch {}
+    }
+  }
+
+  // Try finding button/link by text content first (most common use case)
+  // This is optimized for clicking buttons/links by their visible text
+  // Uses findBestVisibleElement to handle pages with duplicate text labels
+  try {
+    const buttonByText = page.locator(
+      `button:has-text("${selector}"), a:has-text("${selector}"), [role="button"]:has-text("${selector}")`,
+    );
+    if (await hasElement(buttonByText, DETECT_TIMEOUT)) {
+      console.log(`[Browser] Found button/link via text: "${selector}"`);
+      return await findBestVisibleElement(buttonByText, page);
+    }
+  } catch (err) {
+    // Selector might have special characters, try escaping
+    const escaped = selector.replace(/"/g, '\\"');
+    try {
+      const buttonByText = page.locator(
+        `button:has-text("${escaped}"), a:has-text("${escaped}"), [role="button"]:has-text("${escaped}")`,
+      );
+      if (await hasElement(buttonByText, DETECT_TIMEOUT)) {
+        console.log(
+          `[Browser] Found button/link via escaped text: "${escaped}"`,
+        );
+        return await findBestVisibleElement(buttonByText, page);
+      }
+    } catch {}
+  }
+
+  // Try as plain text (for any element with this text)
+  // Uses findBestVisibleElement to prioritize visible elements in viewport
+  const textLocator = page.getByText(selector, { exact: false });
+  if (await hasElement(textLocator, DETECT_TIMEOUT)) {
+    console.log(`[Browser] Found via text content: "${selector}"`);
+    return await findBestVisibleElement(textLocator, page);
+  }
+
+  // Try as placeholder text (for inputs)
+  const placeholderLocator = page.getByPlaceholder(selector);
+  if (await hasElement(placeholderLocator, DETECT_TIMEOUT)) {
+    console.log(`[Browser] Found via placeholder: "${selector}"`);
+    return placeholderLocator.first();
+  }
+
+  // Try as label text (for form fields)
+  const labelLocator = page.getByLabel(selector);
+  if (await hasElement(labelLocator, DETECT_TIMEOUT)) {
+    console.log(`[Browser] Found via label: "${selector}"`);
+    return labelLocator.first();
+  }
+
+  // Try test ID
+  const testIdLocator = page.getByTestId(selector);
+  if (await hasElement(testIdLocator, DETECT_TIMEOUT)) {
+    console.log(`[Browser] Found via testId: "${selector}"`);
+    return testIdLocator.first();
+  }
+
+  // Final fallback: try as generic locator (which supports more than querySelector)
+  try {
+    const cssLocator = page.locator(selector);
+    if (await hasElement(cssLocator, DETECT_TIMEOUT)) {
+      console.log(`[Browser] Found via fallback locator: "${selector}"`);
+      return cssLocator.first();
+    }
+  } catch (err) {
+    console.log(`[Browser] Fallback locator failed: ${err.message}`);
+  }
+
+  throw new Error(
+    `Could not find element: "${selector}". Tried Playwright selectors, CSS selectors, text content, roles, buttons/links, placeholders, labels, and testIds.`,
+  );
+}
+
+/**
+ * Extract readable text content from a page or element
+ * @param {Page} page - Playwright page
+ * @param {string} selector - Optional selector to scope extraction
+ * @returns {Promise<string>} - Extracted text content
+ */
+export async function extractPageContent(page, selector = null) {
+  // When selector is provided, use it only to SCOPE extraction (querySelector in evaluate).
+  // Do NOT use findElement() here — that is for finding a single clickable element; selectors
+  // like "#section ~ p" or "#section + p, #section + ul" are for scoping content and would fail findElement.
+
+  // Get the page title
+  const title = await page.title();
+  const url = page.url();
+
+  // Extract main content (selector scopes the root; querySelector returns first match)
+  const content = await page.evaluate((sel) => {
+    const target = sel ? document.querySelector(sel) : document.body;
+    if (!target) return null;
+
+    // Remove script, style, and hidden elements
+    const clone = target.cloneNode(true);
+    clone
+      .querySelectorAll(
+        'script, style, noscript, [hidden], [aria-hidden="true"]',
+      )
+      .forEach((el) => el.remove());
+
+    // Get text content
+    let text = clone.textContent || "";
+
+    // Clean up whitespace
+    text = text.replace(/\s+/g, " ").trim();
+
+    // Limit length
+    if (text.length > 10000) {
+      text = text.substring(0, 10000) + "... (truncated)";
+    }
+
+    return text;
+  }, selector);
+
+  if (content === null) {
+    return `Error: No element found for selector "${selector}". Use a valid CSS selector (e.g. "#section_id" or ".class"), or omit selector for full page content.`;
+  }
+
+  // Also get interactive elements for context (include href for links so agent can click reliably)
+  const interactiveElements = await page.evaluate(() => {
+    const elements = [];
+
+    // Get clickable elements; for links include href so agent can use a[href="..."]
+    document
+      .querySelectorAll('a, button, [role="button"], input[type="submit"]')
+      .forEach((el, i) => {
+        if (i >= 25) return; // Slightly more links for Wikipedia-style navigation
+        const text =
+          el.textContent?.trim()?.substring(0, 50) ||
+          el.getAttribute("aria-label") ||
+          el.getAttribute("title") ||
+          "";
+        if (text) {
+          const href =
+            el.tagName === "A" && el.getAttribute("href")
+              ? el.getAttribute("href")
+              : null;
+          elements.push({ type: el.tagName.toLowerCase(), text, href });
+        }
+      });
+
+    // Get input fields
+    document
+      .querySelectorAll('input:not([type="hidden"]), textarea, select')
+      .forEach((el, i) => {
+        if (i >= 10) return;
+        const label =
+          el.getAttribute("placeholder") ||
+          el.getAttribute("aria-label") ||
+          el.getAttribute("name") ||
+          "";
+        if (label) {
+          elements.push({ type: "input", label });
+        }
+      });
+
+    return elements;
+  });
+
+  // Format the output (include href for links so agent can click with a[href="..."] or :has-text())
+  let output = `Page: ${title}\nURL: ${url}\n\n`;
+
+  if (interactiveElements.length > 0) {
+    output += `Interactive elements (use selector a[href="..."] or text to click):\n`;
+    interactiveElements.forEach((el) => {
+      if (el.type === "input") {
+        output += `  - Input: "${el.label}"\n`;
+      } else if (el.href) {
+        output += `  - a: "${el.text}" → a[href="${el.href}"]\n`;
+      } else {
+        output += `  - ${el.type}: "${el.text}"\n`;
+      }
+    });
+    output += "\n";
+  }
+
+  output += `Content:\n${content}`;
+
+  return output;
+}
+
+/**
+ * Execute a sequence of browser actions in a single call
+ * Reduces latency by batching multiple operations
+ * @param {Page} page - Playwright page
+ * @param {Array} actions - Array of action objects
+ * @returns {Promise<object>} - Results of all actions
+ */
+export async function executeActionSequence(page, actions) {
+  const results = [];
+  let lastError = null;
+
+  for (let i = 0; i < actions.length; i++) {
+    const action = actions[i];
+    const actionResult = { action: action.type, index: i, success: false };
+
+    try {
+      switch (action.type) {
+        case "click": {
+          const element = await findElement(page, action.selector);
+          await element.scrollIntoViewIfNeeded();
+          const clickOptions = { timeout: 5000 };
+          if (action.force) clickOptions.force = true;
+
+          // Handle waitForNavigation option
+          const performClick = async () => {
+            try {
+              await element.click(clickOptions);
+              return { forced: false };
+            } catch (clickErr) {
+              // Auto-retry with force for overlay, not visible, or outside viewport
+              if (!action.force) {
+                const retryWithForce =
+                  clickErr.message.includes("intercepts pointer events") ||
+                  clickErr.message.includes("element is not visible") ||
+                  clickErr.message.includes("element is outside the viewport");
+                if (retryWithForce) {
+                  await element.click({ ...clickOptions, force: true });
+                  return { forced: true };
+                }
+              }
+              throw clickErr;
+            }
+          };
+
+          let clickResult;
+          if (action.waitForNavigation) {
+            // Wait for navigation to complete after click
+            const navigationTimeout = action.navigationTimeout || 30000;
+            try {
+              const [navResponse, result] = await Promise.all([
+                page
+                  .waitForNavigation({
+                    waitUntil: action.waitUntil || "domcontentloaded",
+                    timeout: navigationTimeout,
+                  })
+                  .catch(() => null), // Don't fail if no navigation occurs
+                performClick(),
+              ]);
+              clickResult = result;
+              if (navResponse) {
+                actionResult.navigated = true;
+                actionResult.newUrl = page.url();
+              }
+            } catch (navErr) {
+              // Navigation may not have occurred, but click might have succeeded
+              clickResult = await performClick();
+            }
+          } else {
+            clickResult = await performClick();
+          }
+
+          actionResult.success = true;
+          actionResult.message = `Clicked "${action.selector}"${clickResult?.forced ? " (auto-forced)" : ""}${actionResult.navigated ? ` → navigated to ${actionResult.newUrl}` : ""}`;
+          break;
+        }
+
+        case "type": {
+          const element = await findElement(page, action.selector);
+          if (action.clear !== false) {
+            await element.clear();
+          }
+          await element.type(action.text, { delay: action.delay || 0 });
+          if (action.submit) {
+            await element.press("Enter");
+          }
+          actionResult.success = true;
+          actionResult.message = `Typed "${action.text.substring(0, 20)}${action.text.length > 20 ? "..." : ""}" into "${action.selector}"`;
+          break;
+        }
+
+        case "fill": {
+          const element = await findElement(page, action.selector);
+          await element.fill(action.text);
+          if (action.submit) {
+            await element.press("Enter");
+          }
+          actionResult.success = true;
+          actionResult.message = `Filled "${action.text.substring(0, 20)}${action.text.length > 20 ? "..." : ""}" into "${action.selector}"`;
+          break;
+        }
+
+        case "wait": {
+          if (action.selector) {
+            // Wait for element
+            const element = await findElement(page, action.selector);
+            await element.waitFor({
+              state: action.state || "visible",
+              timeout: action.timeout || 10000,
+            });
+            actionResult.message = `Waited for "${action.selector}"`;
+          } else if (action.timeout || action.ms) {
+            // Wait for time
+            await page.waitForTimeout(action.timeout || action.ms);
+            actionResult.message = `Waited ${action.timeout || action.ms}ms`;
+          } else if (action.url) {
+            // Wait for URL
+            await page.waitForURL(action.url, {
+              timeout: action.timeout || 30000,
+            });
+            actionResult.message = `Waited for URL: ${action.url}`;
+          } else if (action.load) {
+            // Wait for load state
+            await page.waitForLoadState(action.load, {
+              timeout: action.timeout || 30000,
+            });
+            actionResult.message = `Waited for load state: ${action.load}`;
+          }
+          actionResult.success = true;
+          break;
+        }
+
+        case "scroll": {
+          if (action.selector) {
+            const element = await findElement(page, action.selector);
+            await element.scrollIntoViewIfNeeded();
+            actionResult.message = `Scrolled to "${action.selector}"`;
+          } else {
+            const direction = action.direction || "down";
+            const amount = action.amount || 500;
+            await page.evaluate(
+              ({ dir, amt }) => {
+                switch (dir) {
+                  case "down":
+                    window.scrollBy(0, amt);
+                    break;
+                  case "up":
+                    window.scrollBy(0, -amt);
+                    break;
+                  case "bottom":
+                    window.scrollTo(0, document.body.scrollHeight);
+                    break;
+                  case "top":
+                    window.scrollTo(0, 0);
+                    break;
+                }
+              },
+              { dir: direction, amt: amount },
+            );
+            actionResult.message = `Scrolled ${direction} ${amount}px`;
+          }
+          actionResult.success = true;
+          break;
+        }
+
+        case "hover": {
+          const element = await findElement(page, action.selector);
+          await element.hover();
+          actionResult.success = true;
+          actionResult.message = `Hovered over "${action.selector}"`;
+          break;
+        }
+
+        case "select": {
+          const element = await findElement(page, action.selector);
+          await element.selectOption(action.value);
+          actionResult.success = true;
+          actionResult.message = `Selected "${action.value}" in "${action.selector}"`;
+          break;
+        }
+
+        case "check": {
+          const element = await findElement(page, action.selector);
+          if (action.uncheck) {
+            await element.uncheck();
+            actionResult.message = `Unchecked "${action.selector}"`;
+          } else {
+            await element.check();
+            actionResult.message = `Checked "${action.selector}"`;
+          }
+          actionResult.success = true;
+          break;
+        }
+
+        case "press": {
+          if (action.selector) {
+            const element = await findElement(page, action.selector);
+            await element.press(action.key);
+          } else {
+            await page.keyboard.press(action.key);
+          }
+          actionResult.success = true;
+          actionResult.message = `Pressed "${action.key}"`;
+          break;
+        }
+
+        case "navigate": {
+          await page.goto(action.url, {
+            waitUntil: action.waitUntil || "domcontentloaded",
+            timeout: action.timeout || 30000,
+          });
+          actionResult.success = true;
+          actionResult.message = `Navigated to "${action.url}"`;
+          break;
+        }
+
+        case "evaluate": {
+          const result = await page.evaluate(action.script);
+          actionResult.success = true;
+          actionResult.message = "Executed script";
+          actionResult.result = result;
+          break;
+        }
+
+        case "screenshot": {
+          const path = action.path || `screenshot-${Date.now()}.png`;
+          await page.screenshot({ path, fullPage: action.fullPage || false });
+          actionResult.success = true;
+          actionResult.message = `Screenshot saved to ${path}`;
+          break;
+        }
+
+        case "read": {
+          const content = await extractPageContent(
+            page,
+            action.selector || null,
+          );
+          const maxLen = action.maxLength || 8000;
+          actionResult.success = true;
+          actionResult.message = "Extracted page content";
+          actionResult.result =
+            content.length > maxLen
+              ? content.substring(0, maxLen) + "\n\n... (truncated)"
+              : content;
+          break;
+        }
+
+        default:
+          actionResult.error = `Unknown action type: ${action.type}`;
+      }
+    } catch (err) {
+      actionResult.error = err.message;
+      lastError = err;
+
+      // If continueOnError is not set, stop the sequence
+      if (!action.continueOnError && !actions[i]?.continueOnError) {
+        results.push(actionResult);
+        break;
+      }
+    }
+
+    results.push(actionResult);
+
+    // Optional delay between actions
+    if (action.delayAfter) {
+      await page.waitForTimeout(action.delayAfter);
+    }
+  }
+
+  // Get final page state
+  const finalState = {
+    url: page.url(),
+    title: await page.title(),
+  };
+
+  return {
+    results,
+    completed: results.filter((r) => r.success).length,
+    failed: results.filter((r) => r.error).length,
+    total: actions.length,
+    finalState,
+    lastError: lastError?.message,
+  };
+}
+
+/**
+ * Fetch HTML from a URL using a one-off headless browser (does not use the singleton).
+ * Use for web search SERP pages that require JavaScript.
+ * Uses domcontentloaded + short wait for speed; SERP content is usually in initial DOM.
+ * @param {string} url - Full URL to load
+ * @param {object} options - { waitUntil?, timeout?, waitAfterLoad?, browserConfig? }
+ * @param {object} options.browserConfig - Optional { browserChannel } to use same browser as session
+ * @returns {Promise<string>} - Full page HTML after load
+ */
+export async function fetchHtmlWithBrowser(url, options = {}) {
+  const {
+    waitUntil = "domcontentloaded",
+    timeout = 12000,
+    waitAfterLoad = 1000,
+    browserConfig = {},
+  } = options;
+  const {
+    headless: _h,
+    channel,
+    args,
+  } = getLaunchOptions({ ...browserConfig, browserHeadless: true });
+  let browser = null;
+  try {
+    const chromium = await getChromium();
+    browser = await chromium.launch({
+      headless: true,
+      channel,
+      args,
+    });
+    const userAgent = getRandomUserAgent();
+    const proxyConfig = getWebSearchProxyConfig();
+    const context = await browser.newContext({
+      userAgent,
+      viewport: { width: 1280, height: 800 },
+      extraHTTPHeaders: BROWSER_HEADERS,
+      javaScriptEnabled: true,
+      ignoreHTTPSErrors: true,
+      locale: "en-US",
+      ...(proxyConfig && { proxy: proxyConfig }),
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(timeout);
+    page.setDefaultNavigationTimeout(timeout);
+    await page.addInitScript(() => {
+      Object.defineProperty(navigator, "webdriver", { get: () => undefined });
+      window.chrome = { runtime: {} };
+    });
+    await page.goto(url, { waitUntil, timeout });
+    if (waitAfterLoad > 0) await page.waitForTimeout(waitAfterLoad);
+    const html = await page.content();
+    return html;
+  } finally {
+    if (browser) {
+      try {
+        await browser.close();
+      } catch {}
+    }
+  }
+}
+
+export default {
+  getBrowserPage,
+  closeBrowser,
+  getPageSnapshot,
+  isBrowserActive,
+  findElement,
+  extractPageContent,
+  executeActionSequence,
+  fetchHtmlWithBrowser,
+};