assistme 0.3.0 → 0.3.2

package/src/tools/browser.ts

@@ -1,1209 +1,29 @@
 /**
- * CDP Browser Controller
- *
- * Connects to the user's REAL Chrome browser via Chrome DevTools Protocol.
- * This means the AI shares the user's cookies, sessions, and login state.
- *
- * Auto-launch: If Chrome isn't running with CDP enabled, the CLI will
- * automatically find Chrome, (re)launch it with --remote-debugging-port,
- * and connect — no manual setup required.
- *
- * Key difference from Playwright/Puppeteer:
- * - NOT a headless browser in a sandbox
- * - The user's ACTUAL browser with all their accounts logged in
- * - AI and user see the same tabs, same state
- */
-
-import { WebSocket } from "ws";
-import { execSync, spawn, type ChildProcess } from "node:child_process";
-import { platform, homedir } from "node:os";
-import { existsSync, unlinkSync, mkdirSync, cpSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-import { log } from "../utils/logger.js";
-
-interface CDPTab {
-  id: string;
-  title: string;
-  url: string;
-  type: string;
-  webSocketDebuggerUrl?: string;
-}
-
-interface CDPResponse {
-  id: number;
-  result?: Record<string, unknown>;
-  error?: { code: number; message: string };
-}
-
-/** Shape returned by Runtime.evaluate CDP calls */
-interface CDPEvalResult {
-  result?: { value?: unknown; description?: string };
-}
-
-/** Shape returned by Page.captureScreenshot CDP calls */
-interface CDPScreenshotResult {
-  data?: string;
-}
-
-export class BrowserController {
-  private ws: WebSocket | null = null;
-  private debugPort: number;
-  private messageId = 0;
-  private callbacks = new Map<number, (response: CDPResponse) => void>();
-  private connected = false;
-  private currentTabId: string | null = null;
-
-  constructor(port = 9222) {
-    this.debugPort = port;
-  }
-
-  // ── Connection ──────────────────────────────────────────────────
-
-  async isAvailable(): Promise<boolean> {
-    try {
-      const res = await fetch(`http://127.0.0.1:${this.debugPort}/json/version`, {
-        signal: AbortSignal.timeout(2000),
-      });
-      return res.ok;
-    } catch {
-      return false;
-    }
-  }
-
-  async connect(tabIndex?: number): Promise<string> {
-    // Reuse existing connection if still open and targeting the same tab
-    if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
-      if (tabIndex === undefined) {
-        return "Already connected to browser.";
-      }
-      // If a specific tab is requested, check if we're already on it
-      const tabs = await this.getTabs();
-      const pageTabs = tabs.filter((t) => t.type === "page");
-      const targetTab = pageTabs[tabIndex];
-      if (targetTab && targetTab.id === this.currentTabId) {
-        return `Already connected to tab: "${targetTab.title}"`;
-      }
-      // Need to switch — disconnect first
-      await this.disconnect();
-    }
-
-    const available = await this.isAvailable();
-    if (!available) {
-      throw new Error(
-        `Cannot connect to browser on port ${this.debugPort}. ` +
-          "Chrome remote debugging is not reachable. " +
-          "Please ensure Chrome is running with remote debugging enabled."
-      );
-    }
-
-    const tabs = await this.getTabs();
-    const pageTabs = tabs.filter((t) => t.type === "page");
-
-    if (pageTabs.length === 0) {
-      throw new Error("No browser tabs found. Please open at least one tab.");
-    }
-
-    const targetTab = pageTabs[tabIndex ?? 0];
-    if (!targetTab.webSocketDebuggerUrl) {
-      throw new Error("Tab does not expose a WebSocket debugger URL.");
-    }
-
-    this.currentTabId = targetTab.id;
-
-    return new Promise((resolve, reject) => {
-      let settled = false;
-      this.ws = new WebSocket(targetTab.webSocketDebuggerUrl!);
-
-      const connectTimeout = setTimeout(() => {
-        if (!settled) {
-          settled = true;
-          this.ws?.close();
-          reject(new Error("Connection timeout (5s)"));
-        }
-      }, 5000);
-
-      this.ws.on("open", () => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(connectTimeout);
-        this.connected = true;
-        // Enable required domains
-        this.send("Page.enable").catch(() => {});
-        this.send("Runtime.enable").catch(() => {});
-        this.send("DOM.enable").catch(() => {});
-        resolve(`Connected to tab: "${targetTab.title}" (${targetTab.url})`);
-      });
-
-      this.ws.on("message", (data) => {
-        try {
-          const msg = JSON.parse(data.toString()) as CDPResponse;
-          if (msg.id !== undefined && this.callbacks.has(msg.id)) {
-            this.callbacks.get(msg.id)!(msg);
-            this.callbacks.delete(msg.id);
-          }
-        } catch {
-          // Ignore non-JSON messages (events)
-        }
-      });
-
-      this.ws.on("error", (err) => {
-        this.connected = false;
-        if (!settled) {
-          settled = true;
-          clearTimeout(connectTimeout);
-          reject(new Error(`WebSocket error: ${err.message}`));
-        }
-      });
-
-      this.ws.on("close", () => {
-        this.connected = false;
-        this.ws = null;
-        // Reject pending CDP commands so they don't hang forever
-        for (const [id, cb] of this.callbacks) {
-          cb({ id, error: { code: -1, message: "WebSocket closed" } });
-        }
-        this.callbacks.clear();
-      });
-    });
-  }
-
-  async disconnect(): Promise<string> {
-    if (this.ws) {
-      this.ws.close();
-      this.ws = null;
-      this.connected = false;
-    }
-    return "Disconnected from browser.";
-  }
-
-  // ── CDP Protocol ────────────────────────────────────────────────
-
-  private async getTabs(): Promise<CDPTab[]> {
-    const res = await fetch(`http://127.0.0.1:${this.debugPort}/json`, {
-      signal: AbortSignal.timeout(3000),
-    });
-    return (await res.json()) as CDPTab[];
-  }
-
-  private send(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>> {
-    return new Promise((resolve, reject) => {
-      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-        reject(new Error("Not connected to browser. Call browser_connect first."));
-        return;
-      }
-
-      const id = ++this.messageId;
-      const timeout = setTimeout(() => {
-        this.callbacks.delete(id);
-        reject(new Error(`CDP command timed out: ${method}`));
-      }, 15000);
-
-      this.callbacks.set(id, (response) => {
-        clearTimeout(timeout);
-        if (response.error) {
-          reject(new Error(`CDP error: ${response.error.message}`));
-        } else {
-          resolve(response.result || {});
-        }
-      });
-
-      this.ws.send(JSON.stringify({ id, method, params }));
-    });
-  }
-
-  private ensureConnected() {
-    if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
-      throw new Error("Not connected to browser. Use browser_connect tool first.");
-    }
-  }
-
-  // ── Navigation ──────────────────────────────────────────────────
-
-  async navigate(url: string): Promise<string> {
-    this.ensureConnected();
-    await this.send("Page.navigate", { url });
-    // Wait for load
-    await this.waitForLoad();
-    const info = await this.getPageInfo();
-    return `Navigated to: ${info.title}\nURL: ${info.url}`;
-  }
-
-  async goBack(): Promise<string> {
-    this.ensureConnected();
-    await this.send("Page.navigateToHistoryEntry", {
-      entryId: -1,
-    }).catch(() => {});
-    // Fallback: use JS
-    await this.evaluate("window.history.back()");
-    await this.waitForLoad();
-    const info = await this.getPageInfo();
-    return `Went back to: ${info.title}`;
-  }
-
-  async reload(): Promise<string> {
-    this.ensureConnected();
-    await this.send("Page.reload");
-    await this.waitForLoad();
-    return "Page reloaded.";
-  }
-
-  // ── Page Reading ────────────────────────────────────────────────
-
-  async readPage(): Promise<string> {
-    this.ensureConnected();
-    const result = await this.send("Runtime.evaluate", {
-      expression: `
-        (function() {
-          // Get page title and URL
-          let output = "Title: " + document.title + "\\n";
-          output += "URL: " + window.location.href + "\\n\\n";
-
-          // Get main text content, cleaned up
-          const body = document.body.cloneNode(true);
-          // Remove scripts, styles, navs that add noise
-          body.querySelectorAll('script, style, noscript, svg, iframe').forEach(el => el.remove());
-
-          const text = body.innerText
-            .split('\\n')
-            .map(line => line.trim())
-            .filter(line => line.length > 0)
-            .join('\\n');
-
-          output += text;
-          return output.slice(0, 30000);
-        })()
-      `,
-      returnByValue: true,
-    });
-
-    return ((result as CDPEvalResult).result?.value as string) || "Could not read page content.";
-  }
-
-  async readElement(selector: string): Promise<string> {
-    this.ensureConnected();
-    const selectorJS = JSON.stringify(selector);
-    const result = await this.send("Runtime.evaluate", {
-      expression: `
-        (function() {
-          const el = document.querySelector(${selectorJS});
-          if (!el) return 'Element not found: ' + ${selectorJS};
-          return el.innerText || el.textContent || el.value || '(empty)';
-        })()
-      `,
-      returnByValue: true,
-    });
-
-    return ((result as CDPEvalResult).result?.value as string) || "Element not found.";
-  }
-
-  async getPageInfo(): Promise<{ title: string; url: string }> {
-    const result = await this.send("Runtime.evaluate", {
-      expression: `JSON.stringify({ title: document.title, url: window.location.href })`,
-      returnByValue: true,
-    });
-    try {
-      return JSON.parse(((result as CDPEvalResult).result?.value as string) || "{}");
-    } catch {
-      return { title: "Unknown", url: "unknown" };
-    }
-  }
-
-  // ── Screenshots (for Claude vision) ─────────────────────────────
-
-  async screenshot(): Promise<string> {
-    this.ensureConnected();
-    const result = await this.send("Page.captureScreenshot", {
-      format: "png",
-      quality: 80,
-      captureBeyondViewport: false,
-    });
-    // Returns base64-encoded PNG
-    return (result as CDPScreenshotResult).data || "";
-  }
-
-  // ── Interactions ────────────────────────────────────────────────
-
-  async click(selector: string): Promise<string> {
-    this.ensureConnected();
-    const selectorJS = JSON.stringify(selector);
-
-    const result = await this.send("Runtime.evaluate", {
-      expression: `
-        (function() {
-          const el = document.querySelector(${selectorJS});
-          if (!el) return 'Element not found: ' + ${selectorJS};
-
-          // Scroll into view
-          el.scrollIntoView({ block: 'center', behavior: 'instant' });
-
-          // Click
-          el.click();
-          return 'Clicked: ' + (el.tagName || '') + ' ' + (el.textContent || '').slice(0, 50).trim();
-        })()
-      `,
-      returnByValue: true,
-    });
-
-    // Small delay for any resulting navigation/animation
-    await new Promise((r) => setTimeout(r, 500));
-    return ((result as CDPEvalResult).result?.value as string) || "Click executed.";
-  }
-
-  async typeText(selector: string, text: string): Promise<string> {
-    this.ensureConnected();
-    // Use JSON.stringify for safe string interpolation into JS — handles all
-    // special characters (quotes, backslashes, newlines, unicode) correctly.
-    const selectorJS = JSON.stringify(selector);
-    const textJS = JSON.stringify(text);
-
-    const result = await this.send("Runtime.evaluate", {
-      expression: `
-        (function() {
-          const el = document.querySelector(${selectorJS});
-          if (!el) return 'Element not found: ' + ${selectorJS};
-
-          el.focus();
-          el.value = ${textJS};
-          el.dispatchEvent(new Event('input', { bubbles: true }));
-          el.dispatchEvent(new Event('change', { bubbles: true }));
-          return 'Typed into: ' + (el.tagName || '') + ' [' + (el.name || el.id || '') + ']';
-        })()
-      `,
-      returnByValue: true,
-    });
-
-    return ((result as CDPEvalResult).result?.value as string) || "Text entered.";
-  }
-
-  async pressKey(key: string): Promise<string> {
-    this.ensureConnected();
-
-    // Map common key names to CDP key codes
-    const keyMap: Record<string, { keyCode: number; code: string }> = {
-      Enter: { keyCode: 13, code: "Enter" },
-      Tab: { keyCode: 9, code: "Tab" },
-      Escape: { keyCode: 27, code: "Escape" },
-      Backspace: { keyCode: 8, code: "Backspace" },
-      ArrowDown: { keyCode: 40, code: "ArrowDown" },
-      ArrowUp: { keyCode: 38, code: "ArrowUp" },
-    };
-
-    const mapped = keyMap[key];
-    if (mapped) {
-      await this.send("Input.dispatchKeyEvent", {
-        type: "keyDown",
-        key,
-        code: mapped.code,
-        windowsVirtualKeyCode: mapped.keyCode,
-        nativeVirtualKeyCode: mapped.keyCode,
-      });
-      await this.send("Input.dispatchKeyEvent", {
-        type: "keyUp",
-        key,
-        code: mapped.code,
-        windowsVirtualKeyCode: mapped.keyCode,
-        nativeVirtualKeyCode: mapped.keyCode,
-      });
-    } else {
-      // Single character key
-      await this.send("Input.dispatchKeyEvent", {
-        type: "char",
-        text: key,
-      });
-    }
-
-    return `Pressed key: ${key}`;
-  }
-
-  async scrollDown(): Promise<string> {
-    this.ensureConnected();
-    await this.send("Runtime.evaluate", {
-      expression: "window.scrollBy(0, window.innerHeight * 0.8)",
-    });
-    await new Promise((r) => setTimeout(r, 300));
-    return "Scrolled down.";
-  }
-
-  async scrollUp(): Promise<string> {
-    this.ensureConnected();
-    await this.send("Runtime.evaluate", {
-      expression: "window.scrollBy(0, -window.innerHeight * 0.8)",
-    });
-    await new Promise((r) => setTimeout(r, 300));
-    return "Scrolled up.";
-  }
-
-  // ── JavaScript Evaluation ───────────────────────────────────────
-
-  async evaluate(expression: string): Promise<string> {
-    this.ensureConnected();
-    const result = await this.send("Runtime.evaluate", {
-      expression,
-      returnByValue: true,
-      awaitPromise: true,
-    });
-
-    const evalResult = (result as CDPEvalResult).result;
-    const value = evalResult?.value;
-    if (value === undefined) {
-      const desc = evalResult?.description;
-      return desc || "(undefined)";
-    }
-    return typeof value === "string" ? value : JSON.stringify(value, null, 2);
-  }
-
-  // ── Tab Management ──────────────────────────────────────────────
-
-  async listTabs(): Promise<string> {
-    const tabs = await this.getTabs();
-    const pageTabs = tabs.filter((t) => t.type === "page");
-
-    if (pageTabs.length === 0) return "No tabs open.";
-
-    return pageTabs
-      .map(
-        (t, i) =>
-          `[${i}] ${t.title.slice(0, 60)}${this.currentTabId === t.id ? " (active)" : ""}\n    ${t.url}`
-      )
-      .join("\n\n");
-  }
-
-  async switchTab(index: number): Promise<string> {
-    const tabs = await this.getTabs();
-    const pageTabs = tabs.filter((t) => t.type === "page");
-
-    if (index < 0 || index >= pageTabs.length) {
-      return `Invalid tab index. Available: 0-${pageTabs.length - 1}`;
-    }
-
-    // Disconnect from current tab
-    await this.disconnect();
-
-    // Connect to new tab
-    return this.connect(index);
-  }
-
-  async openNewTab(url?: string): Promise<string> {
-    const targetUrl = url || "about:blank";
-    const res = await fetch(
-      `http://127.0.0.1:${this.debugPort}/json/new?${encodeURIComponent(targetUrl)}`,
-      { signal: AbortSignal.timeout(5000) }
-    );
-    const tab = (await res.json()) as CDPTab;
-
-    // Connect to the new tab
-    await this.disconnect();
-    const tabs = await this.getTabs();
-    const idx = tabs.filter((t) => t.type === "page").findIndex((t) => t.id === tab.id);
-    if (idx >= 0) {
-      await this.connect(idx);
-    }
-
-    return `Opened new tab: ${targetUrl}`;
-  }
-
-  // ── Helpers ─────────────────────────────────────────────────────
-
-  private async waitForLoad(timeoutMs = 8000): Promise<void> {
-    const start = Date.now();
-    while (Date.now() - start < timeoutMs) {
-      try {
-        const result = await this.send("Runtime.evaluate", {
-          expression: "document.readyState",
-          returnByValue: true,
-        });
-        const state = (result as CDPEvalResult).result?.value;
-        if (state === "complete" || state === "interactive") {
-          // Extra small wait for dynamic content
-          await new Promise((r) => setTimeout(r, 500));
-          return;
-        }
-      } catch {
-        // Tab might be navigating
-      }
-      await new Promise((r) => setTimeout(r, 300));
-    }
-  }
-
-  /**
-   * Find interactive elements on the page for the AI to understand what's clickable
-   */
-  async getInteractiveElements(): Promise<string> {
-    this.ensureConnected();
-    const result = await this.send("Runtime.evaluate", {
-      expression: `
-        (function() {
-          const elements = [];
-          const selectors = 'a, button, input, select, textarea, [role="button"], [onclick]';
-          const all = document.querySelectorAll(selectors);
-          for (let i = 0; i < all.length && elements.length < 50; i++) {
-            const el = all[i];
-            const rect = el.getBoundingClientRect();
-            if (rect.width === 0 || rect.height === 0) continue; // Skip hidden
-
-            // Build a reliable CSS selector
-            let selector;
-            if (el.id) {
-              selector = '#' + CSS.escape(el.id);
-            } else if (el.getAttribute('data-testid')) {
-              selector = '[data-testid="' + el.getAttribute('data-testid') + '"]';
-            } else {
-              // Build a path-based selector: find nth-of-type among siblings
-              const tag = el.tagName.toLowerCase();
-              const parent = el.parentElement;
-              if (parent) {
-                const siblings = parent.querySelectorAll(':scope > ' + tag);
-                const idx = Array.from(siblings).indexOf(el) + 1;
-                selector = tag + ':nth-of-type(' + idx + ')';
-              } else {
-                selector = tag;
-              }
-            }
-
-            elements.push({
-              tag: el.tagName.toLowerCase(),
-              text: (el.textContent || '').trim().slice(0, 80),
-              type: el.getAttribute('type') || '',
-              name: el.getAttribute('name') || '',
-              id: el.id || '',
-              href: el.getAttribute('href') || '',
-              placeholder: el.getAttribute('placeholder') || '',
-              selector: selector,
-            });
-          }
-          return JSON.stringify(elements, null, 2);
-        })()
-      `,
-      returnByValue: true,
-    });
-
-    return ((result as CDPEvalResult).result?.value as string) || "[]";
-  }
-
-  isConnected(): boolean {
-    return this.connected && this.ws?.readyState === WebSocket.OPEN;
-  }
-
-  // ── Login Detection ────────────────────────────────────────────
-
-  /**
-   * Detect if the current page appears to be a login/authentication page.
-   * Checks URL patterns, password input fields, and login form actions.
-   */
-  async detectLoginPage(): Promise<{ isLoginPage: boolean; reason: string }> {
-    try {
-      const result = await this.send("Runtime.evaluate", {
-        expression: `
-          (function() {
-            var url = window.location.href.toLowerCase();
-
-            // URL-based detection
-            var loginPatterns = [
-              '/login', '/signin', '/sign-in', '/sign_in',
-              '/auth/', '/sso/', '/oauth/', '/session/new',
-              '/accounts/login', '/users/sign_in',
-              'accounts.google.com', 'login.microsoftonline.com',
-              'github.com/login', 'github.com/session',
-              'login.live.com', 'appleid.apple.com'
-            ];
-            for (var i = 0; i < loginPatterns.length; i++) {
-              if (url.indexOf(loginPatterns[i]) !== -1) {
-                return JSON.stringify({
-                  isLoginPage: true,
-                  reason: 'URL contains login pattern: ' + loginPatterns[i]
-                });
-              }
-            }
-
-            // Password input detection (visible only)
-            var passwordInputs = document.querySelectorAll('input[type="password"]');
-            for (var j = 0; j < passwordInputs.length; j++) {
-              var input = passwordInputs[j];
-              var rect = input.getBoundingClientRect();
-              var style = window.getComputedStyle(input);
-              if (rect.width > 0 && rect.height > 0 &&
-                  style.display !== 'none' && style.visibility !== 'hidden') {
-                return JSON.stringify({
-                  isLoginPage: true,
-                  reason: 'Page contains visible password input field'
-                });
-              }
-            }
-
-            // Login form action detection
-            var formSelectors = [
-              'form[action*="login"]', 'form[action*="signin"]',
-              'form[action*="session"]', 'form[action*="auth"]',
-              'form[action*="authenticate"]'
-            ];
-            var loginForms = document.querySelectorAll(formSelectors.join(','));
-            if (loginForms.length > 0) {
-              return JSON.stringify({
-                isLoginPage: true,
-                reason: 'Page contains login form'
-              });
-            }
-
-            return JSON.stringify({ isLoginPage: false, reason: '' });
-          })()
-        `,
-        returnByValue: true,
-      });
-
-      const value = (result as CDPEvalResult).result?.value as string;
-      return JSON.parse(value || '{"isLoginPage":false,"reason":""}');
-    } catch {
-      return { isLoginPage: false, reason: "" };
-    }
-  }
-}
-
-// ── Chrome Auto-Launch ──────────────────────────────────────────────
-
-/**
- * Find Chrome/Chromium binary path on the current platform.
- */
-export function findChromePath(): string | null {
-  const os = platform();
-
-  if (os === "darwin") {
-    const paths = [
-      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-      "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
-      "/Applications/Chromium.app/Contents/MacOS/Chromium",
-      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
-      "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
-    ];
-    return paths.find((p) => existsSync(p)) ?? null;
-  }
-
-  if (os === "linux") {
-    const names = [
-      "google-chrome",
-      "google-chrome-stable",
-      "chromium-browser",
-      "chromium",
-      "microsoft-edge",
-      "microsoft-edge-stable",
-      "brave-browser",
-    ];
-    for (const name of names) {
-      try {
-        return execSync(`which ${name}`, {
-          encoding: "utf-8",
-          stdio: ["pipe", "pipe", "pipe"],
-        }).trim();
-      } catch {
-        /* not found */
-      }
-    }
-    return null;
-  }
-
-  if (os === "win32") {
-    const prefixes = [
-      process.env.PROGRAMFILES,
-      process.env["PROGRAMFILES(X86)"],
-      process.env.LOCALAPPDATA,
-    ].filter(Boolean) as string[];
-
-    const subPaths = [
-      "Google\\Chrome\\Application\\chrome.exe",
-      "Microsoft\\Edge\\Application\\msedge.exe",
-      "BraveSoftware\\Brave-Browser\\Application\\brave.exe",
-    ];
-
-    for (const prefix of prefixes) {
-      for (const sub of subPaths) {
-        const p = `${prefix}\\${sub}`;
-        if (existsSync(p)) return p;
-      }
-    }
-    return null;
-  }
-
-  return null;
-}
-
-/**
- * Check if a Chromium-based browser is currently running.
- * Optionally pass the specific browser binary path for precise matching.
- */
-export function isChromeRunning(chromePath?: string): boolean {
-  try {
-    if (platform() === "win32") {
-      // Check for any Chromium-based browser process
-      const out = execSync(
-        'tasklist /FI "IMAGENAME eq chrome.exe" /FI "IMAGENAME eq msedge.exe" /FI "IMAGENAME eq brave.exe" /NH',
-        { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
-      );
-      return /chrome\.exe|msedge\.exe|brave\.exe/i.test(out);
-    }
-    if (platform() === "darwin") {
-      // If we know the exact binary, match it precisely
-      if (chromePath) {
-        const appDir = chromePath.replace(/\/Contents\/MacOS\/.*$/, "");
-        const out = execSync(`pgrep -f ${JSON.stringify(appDir)}`, {
-          encoding: "utf-8",
-          stdio: ["pipe", "pipe", "pipe"],
-        });
-        return out.trim().length > 0;
-      }
-      // Otherwise check all known Chromium browsers
-      const out = execSync(
-        'pgrep -f "(Google Chrome|Microsoft Edge|Brave Browser|Chromium).app/Contents/MacOS/"',
-        { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
-      );
-      return out.trim().length > 0;
-    }
-    // Linux
-    if (chromePath) {
-      const out = execSync(`pgrep -f ${JSON.stringify(chromePath)} 2>/dev/null || true`, {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-      return out.trim().length > 0;
-    }
-    const out = execSync("pgrep -f '(chrome|chromium|msedge|brave)' 2>/dev/null || true", {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    return out.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Derive the macOS app name from a binary path inside a .app bundle.
- */
-function macAppName(chromePath: string): string {
-  if (chromePath.includes("Brave Browser")) return "Brave Browser";
-  if (chromePath.includes("Microsoft Edge")) return "Microsoft Edge";
-  if (chromePath.includes("Chromium")) return "Chromium";
-  if (chromePath.includes("Canary")) return "Google Chrome Canary";
-  return "Google Chrome";
-}
-
-/**
- * Gracefully quit the browser, then force-kill if it doesn't exit in time.
- */
-async function killChromeGracefully(chromePath: string): Promise<void> {
-  const os = platform();
-  try {
-    if (os === "darwin") {
-      const app = macAppName(chromePath);
-      execSync(`osascript -e 'quit app "${app}"'`, {
-        timeout: 5000,
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-    } else if (os === "linux") {
-      // Kill the specific browser binary, not all Chromium variants
-      execSync(`pkill -TERM -f ${JSON.stringify(chromePath)}`, {
-        timeout: 5000,
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-    } else if (os === "win32") {
-      const exe = chromePath.split("\\").pop() || "chrome.exe";
-      execSync(`taskkill /IM "${exe}"`, {
-        timeout: 5000,
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-    }
-  } catch {
-    /* may already be closed */
-  }
-
-  // Wait for browser to fully exit (up to 8s)
-  const start = Date.now();
-  while (Date.now() - start < 8000) {
-    if (!isChromeRunning(chromePath)) {
-      log.debug(`Browser exited after ${Date.now() - start}ms`);
-      return;
-    }
-    await new Promise((r) => setTimeout(r, 500));
-  }
-
-  log.debug("Browser still running after graceful quit, force-killing...");
-
-  // Force kill if still alive
-  try {
-    if (os === "win32") {
-      const exe = chromePath.split("\\").pop() || "chrome.exe";
-      execSync(`taskkill /F /IM "${exe}"`, {
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-    } else {
-      execSync(`pkill -9 -f ${JSON.stringify(chromePath)}`, {
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-    }
-  } catch {
-    /* already dead */
-  }
-
-  // Wait for processes to fully terminate after SIGKILL
-  await new Promise((r) => setTimeout(r, 1000));
-
-  // Remove SingletonLock files that may linger after a force-kill
-  if (os !== "win32") {
-    const home = process.env.HOME;
-    if (home) {
-      const lockSuffixes = ["SingletonLock", "SingletonSocket", "SingletonCookie"];
-      const profileDirs =
-        os === "darwin"
-          ? [
-              `${home}/Library/Application Support/Google/Chrome`,
-              `${home}/Library/Application Support/Microsoft Edge`,
-              `${home}/Library/Application Support/BraveSoftware/Brave-Browser`,
-            ]
-          : [
-              `${home}/.config/google-chrome`,
-              `${home}/.config/chromium`,
-              `${home}/.config/microsoft-edge`,
-              `${home}/.config/BraveSoftware/Brave-Browser`,
-            ];
-      for (const dir of profileDirs) {
-        for (const suffix of lockSuffixes) {
-          const lockPath = `${dir}/${suffix}`;
-          try {
-            if (existsSync(lockPath)) {
-              unlinkSync(lockPath);
-              log.debug(`Removed stale lock: ${lockPath}`);
-            }
-          } catch {
-            /* best effort */
-          }
-        }
-      }
-    }
-  }
-}
-
-/**
- * Return the browser's default profile directory.
- */
-function getDefaultProfileDir(chromePath: string): string {
-  const home = homedir();
-  const os = platform();
-
-  if (os === "darwin") {
-    if (chromePath.includes("Brave Browser"))
-      return join(home, "Library", "Application Support", "BraveSoftware", "Brave-Browser");
-    if (chromePath.includes("Microsoft Edge"))
-      return join(home, "Library", "Application Support", "Microsoft Edge");
-    if (chromePath.includes("Chromium"))
-      return join(home, "Library", "Application Support", "Chromium");
-    if (chromePath.includes("Canary"))
-      return join(home, "Library", "Application Support", "Google", "Chrome Canary");
-    return join(home, "Library", "Application Support", "Google", "Chrome");
-  }
-
-  if (os === "win32") {
-    const appData = process.env.LOCALAPPDATA || join(home, "AppData", "Local");
-    if (chromePath.includes("brave"))
-      return join(appData, "BraveSoftware", "Brave-Browser", "User Data");
-    if (chromePath.includes("msedge")) return join(appData, "Microsoft", "Edge", "User Data");
-    return join(appData, "Google", "Chrome", "User Data");
-  }
-
-  // Linux
-  if (chromePath.includes("brave")) return join(home, ".config", "BraveSoftware", "Brave-Browser");
-  if (chromePath.includes("microsoft-edge")) return join(home, ".config", "microsoft-edge");
-  if (chromePath.includes("chromium")) return join(home, ".config", "chromium");
-  return join(home, ".config", "google-chrome");
-}
-
-/**
- * Return a dedicated debug profile directory for assistme.
- *
- * Chrome 136+ silently ignores --remote-debugging-port when launched with the
- * DEFAULT user-data-dir (security hardening against cookie-stealing malware).
- * It also ignores --user-data-dir pointing to the default path.
- * The flag ONLY works with a NON-DEFAULT --user-data-dir.
- *
- * Strategy: use ~/.assistme/browser-profile as a dedicated debug profile.
- * On first use, copy key files from the real profile (bookmarks, cookies,
- * login data, preferences) so the user doesn't start completely fresh.
- * Sessions accumulate in the debug profile from then on.
- *
- * See: https://developer.chrome.com/blog/remote-debugging-port
- */
-function getDebugProfileDir(chromePath: string): string {
-  const home = homedir();
-  const debugDir = join(home, ".assistme", "browser-profile");
-
-  if (!existsSync(debugDir)) {
-    mkdirSync(debugDir, { recursive: true });
-    log.debug(`Created debug profile directory: ${debugDir}`);
-
-    // Seed from the real profile — copy lightweight files, skip caches
-    const realDir = getDefaultProfileDir(chromePath);
-    if (existsSync(realDir)) {
-      seedDebugProfile(realDir, debugDir);
-    }
-  }
-
-  return debugDir;
-}
-
-/**
- * Copy essential profile data from the user's real Chrome profile to the
- * debug profile. This preserves bookmarks, preferences, and (where possible)
- * login state without copying multi-GB caches.
- *
- * Note: cookies/login data are encrypted with a key tied to the user-data-dir
- * on Chrome 136+, so they won't decrypt in the debug profile. The user will
- * need to log in once in the debug browser. After that, sessions persist.
- */
-function seedDebugProfile(realDir: string, debugDir: string): void {
-  // Files to copy from the profile root
-  const rootFiles = ["Local State"];
-  // Files to copy from the "Default" sub-profile
-  const profileFiles = ["Bookmarks", "Preferences", "Favicons", "Top Sites", "Shortcuts"];
-
-  for (const file of rootFiles) {
-    const src = join(realDir, file);
-    const dest = join(debugDir, file);
-    try {
-      if (existsSync(src)) {
-        cpSync(src, dest, { force: true });
-        log.debug(`Seeded: ${file}`);
-      }
-    } catch {
-      /* best effort */
-    }
-  }
-
-  // Copy the Default profile sub-directory essentials
-  const srcProfile = join(realDir, "Default");
-  const destProfile = join(debugDir, "Default");
-  if (existsSync(srcProfile)) {
-    mkdirSync(destProfile, { recursive: true });
-    for (const file of profileFiles) {
-      const src = join(srcProfile, file);
-      const dest = join(destProfile, file);
-      try {
-        if (existsSync(src)) {
-          cpSync(src, dest, { force: true });
-          log.debug(`Seeded: Default/${file}`);
-        }
-      } catch {
-        /* best effort */
-      }
-    }
-
-    // Copy Extensions directory if it exists (preserves user's extensions)
-    const srcExt = join(srcProfile, "Extensions");
-    const destExt = join(destProfile, "Extensions");
-    try {
-      if (existsSync(srcExt)) {
-        cpSync(srcExt, destExt, { recursive: true, force: true });
-        log.debug("Seeded: Default/Extensions");
-      }
-    } catch {
-      /* best effort — extensions can be large */
-    }
-  }
-}
-
-/**
- * Spawn a Chromium-based browser with CDP enabled.
- * Returns the child process for exit-code monitoring.
- *
- * Key design decisions:
- * - Launches the binary directly (not via macOS `open -a`) so flags are
- *   guaranteed to reach the process and the child stays alive.
- * - Uses a dedicated debug profile (not the default profile) so that:
- *   (a) Chrome 136+ allows --remote-debugging-port
- *   (b) Can run alongside the user's regular Chrome (different singleton)
- * - Callers should ensure no OTHER debug-profile Chrome is running, but
- *   the user's regular Chrome can stay open.
- */
-function spawnChrome(chromePath: string, port: number): ChildProcess {
-  const profileDir = getDebugProfileDir(chromePath);
-  const flags = [
-    `--remote-debugging-port=${port}`,
-    `--user-data-dir=${profileDir}`,
-    "--restore-last-session",
-  ];
-
-  log.debug(`Spawning browser: ${chromePath} ${flags.join(" ")}`);
-
-  const child = spawn(chromePath, flags, {
-    detached: true,
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-
-  // Capture stderr for diagnostics — Chrome prints errors here
-  let stderr = "";
-  child.stderr?.on("data", (chunk: Buffer) => {
-    stderr += chunk.toString();
-  });
-
-  child.on("error", (err) => {
-    log.error(`Chrome spawn error: ${err.message}`);
-  });
-
-  child.on("exit", (code, signal) => {
-    if (code !== null && code !== 0) {
-      log.debug(`Chrome exited with code ${code}${signal ? ` (signal: ${signal})` : ""}`);
-      if (stderr) {
-        // Log first few lines of stderr for diagnostics
-        const lines = stderr.split("\n").filter(Boolean).slice(0, 5);
-        for (const line of lines) {
-          log.debug(`  chrome stderr: ${line}`);
-        }
-      }
-    }
-  });
-
-  child.unref();
-  return child;
-}
-
-/**
- * Wait for CDP to become reachable.
- */
-async function waitForCDP(browser: BrowserController, timeoutMs = 30000): Promise<boolean> {
-  const start = Date.now();
-  let attempts = 0;
-  while (Date.now() - start < timeoutMs) {
-    attempts++;
-    if (await browser.isAvailable()) {
-      log.debug(`CDP became reachable after ${attempts} attempts (${Date.now() - start}ms)`);
-      return true;
-    }
-    await new Promise((r) => setTimeout(r, 500));
-  }
-  log.debug(`CDP not reachable after ${attempts} attempts (${timeoutMs}ms timeout)`);
-  return false;
-}
-
-/**
- * Check if a port is already in use by another process (not Chrome CDP).
- */
-async function isPortInUse(port: number): Promise<boolean> {
-  try {
-    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
-      signal: AbortSignal.timeout(1000),
-    });
-    // CDP /json/version returns a JSON object with "Browser" and "webSocketDebuggerUrl" keys.
-    // All Chromium-based browsers (Chrome, Edge, Brave) include these.
-    const body = await res.text();
-    return !body.includes("webSocketDebuggerUrl");
-  } catch {
-    // Connection refused → port is free
-    return false;
-  }
-}
-
-/**
- * Result of an auto-launch attempt.
- */
-export interface AutoLaunchResult {
-  success: boolean;
-  action: "already_available" | "launched" | "chrome_not_found" | "launch_failed" | "port_conflict";
-  chromePath?: string;
-  detail?: string;
-}
-
-/**
- * Ensure a Chromium browser is running with CDP enabled.
- *
- * Uses a SEPARATE debug profile (~/.assistme/browser-profile) so that:
- * - The user's regular Chrome can stay open — no killing required
- * - Chrome 136+ enables --remote-debugging-port (requires non-default dir)
- * - The debug browser has its own singleton — no conflicts
- *
- * Flow:
- * 1. CDP already reachable on the port → return immediately.
- * 2. Port occupied by a non-Chromium process → report conflict.
- * 3. Launch a new browser instance with the debug profile + CDP flag.
- */
-export async function ensureBrowserAvailable(port = 9222): Promise<AutoLaunchResult> {
-  const browser = getBrowser(port);
-
-  // Case 1: CDP already reachable
-  if (await browser.isAvailable()) {
-    log.debug("CDP already reachable — no launch needed");
-    return { success: true, action: "already_available" };
-  }
-
-  // Case 2: Port occupied by something else
-  if (await isPortInUse(port)) {
-    log.debug(`Port ${port} is in use by a non-Chrome process`);
-    return {
-      success: false,
-      action: "port_conflict",
-      detail: `Port ${port} is already in use by another process. Try a different port or stop the conflicting process.`,
-    };
-  }
-
-  // Find Chrome binary
-  const chromePath = findChromePath();
-  if (!chromePath) {
-    log.debug("Chrome binary not found on this system");
-    return { success: false, action: "chrome_not_found" };
-  }
-
-  log.debug(`Found Chrome at: ${chromePath}`);
-
-  // Launch a debug Chrome instance (separate profile — no need to kill the user's Chrome)
-  spawnChrome(chromePath, port);
-
-  if (await waitForCDP(browser)) {
-    return { success: true, action: "launched", chromePath };
-  }
-
-  // CDP didn't come up — check if the debug profile is locked by a previous
-  // crashed assistme session (stale SingletonLock)
-  const debugDir = getDebugProfileDir(chromePath);
-  const lockPath = join(debugDir, "SingletonLock");
-  if (existsSync(lockPath)) {
-    log.debug("Found stale SingletonLock in debug profile — removing and retrying");
-    try {
-      unlinkSync(lockPath);
-      // Also clean SingletonSocket/Cookie
-      for (const f of ["SingletonSocket", "SingletonCookie"]) {
-        try {
-          unlinkSync(join(debugDir, f));
-        } catch {
-          /* ok */
-        }
-      }
-    } catch {
-      /* best effort */
-    }
-
-    // Retry spawn
-    spawnChrome(chromePath, port);
-    if (await waitForCDP(browser, 15000)) {
-      return { success: true, action: "launched", chromePath };
-    }
-  }
-
-  return {
-    success: false,
-    action: "launch_failed",
-    chromePath,
-    detail:
-      "Could not start browser with remote debugging. Possible causes:\n" +
-      "  1) Another assistme debug browser is already using port " +
-      port +
-      "\n" +
-      "  2) The browser crashed on startup\n" +
-      "Try: rm -rf ~/.assistme/browser-profile && assistme",
-  };
-}
-
-// ── Singleton ───────────────────────────────────────────────────────
-
-let browserInstance: BrowserController | null = null;
-
-export function getBrowser(port = 9222): BrowserController {
-  if (!browserInstance) {
-    browserInstance = new BrowserController(port);
-  }
-  return browserInstance;
-}
+ * Re-export barrel — preserves backward compatibility while the actual logic
+ * lives in focused modules under browser/.
+ */
+
+// Types
+export type {
+  CDPTab,
+  CDPResponse,
+  CDPEvalResult,
+  CDPScreenshotResult,
+  BoundingBox,
+  RefEntry,
+  SnapshotResult,
+  ActionSpec,
+  ActionResult,
+  AutoLaunchResult,
+} from "../browser/types.js";
+
+// Controller
+export { BrowserController } from "../browser/controller.js";
+
+// Chrome launcher & singleton
+export {
+  findChromePath,
+  isChromeRunning,
+  ensureBrowserAvailable,
+  getBrowser,
+} from "../browser/chrome-launcher.js";