assistme 0.1.9 → 0.1.11

package/dist/index.js

@@ -394,7 +394,7 @@ import {
 import { WebSocket } from "ws";
 import { execSync, spawn } from "child_process";
 import { platform } from "os";
-import { existsSync } from "fs";
+import { existsSync, unlinkSync } from "fs";
 var BrowserController = class {
   ws = null;
   debugPort;
@@ -446,8 +446,19 @@ var BrowserController = class {
     }
     this.currentTabId = targetTab.id;
     return new Promise((resolve2, 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)"));
+        }
+      }, 5e3);
       this.ws.on("open", () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(connectTimeout);
         this.connected = true;
         this.send("Page.enable").catch(() => {
         });
@@ -469,13 +480,20 @@ var BrowserController = class {
       });
       this.ws.on("error", (err) => {
         this.connected = false;
-        reject(new Error(`WebSocket error: ${err.message}`));
+        if (!settled) {
+          settled = true;
+          clearTimeout(connectTimeout);
+          reject(new Error(`WebSocket error: ${err.message}`));
+        }
       });
       this.ws.on("close", () => {
         this.connected = false;
         this.ws = null;
+        for (const [id, cb] of this.callbacks) {
+          cb({ id, error: { code: -1, message: "WebSocket closed" } });
+        }
+        this.callbacks.clear();
       });
-      setTimeout(() => reject(new Error("Connection timeout")), 5e3);
     });
   }
   async disconnect() {
@@ -577,12 +595,12 @@ URL: ${info.url}`;
   }
   async readElement(selector) {
     this.ensureConnected();
-    const escaped = selector.replace(/'/g, "\\'");
+    const selectorJS = JSON.stringify(selector);
     const result = await this.send("Runtime.evaluate", {
       expression: `
         (function() {
-          const el = document.querySelector('${escaped}');
-          if (!el) return 'Element not found: ${escaped}';
+          const el = document.querySelector(${selectorJS});
+          if (!el) return 'Element not found: ' + ${selectorJS};
           return el.innerText || el.textContent || el.value || '(empty)';
         })()
       `,
@@ -614,12 +632,12 @@ URL: ${info.url}`;
   // ── Interactions ────────────────────────────────────────────────
   async click(selector) {
     this.ensureConnected();
-    const escaped = selector.replace(/'/g, "\\'");
+    const selectorJS = JSON.stringify(selector);
     const result = await this.send("Runtime.evaluate", {
       expression: `
         (function() {
-          const el = document.querySelector('${escaped}');
-          if (!el) return 'Element not found: ${escaped}';
+          const el = document.querySelector(${selectorJS});
+          if (!el) return 'Element not found: ' + ${selectorJS};
 
           // Scroll into view
           el.scrollIntoView({ block: 'center', behavior: 'instant' });
@@ -636,16 +654,16 @@ URL: ${info.url}`;
   }
   async typeText(selector, text) {
     this.ensureConnected();
-    const escaped = selector.replace(/'/g, "\\'");
-    const textEscaped = text.replace(/'/g, "\\'").replace(/\\/g, "\\\\");
+    const selectorJS = JSON.stringify(selector);
+    const textJS = JSON.stringify(text);
     const result = await this.send("Runtime.evaluate", {
       expression: `
         (function() {
-          const el = document.querySelector('${escaped}');
-          if (!el) return 'Element not found: ${escaped}';
+          const el = document.querySelector(${selectorJS});
+          if (!el) return 'Element not found: ' + ${selectorJS};
 
           el.focus();
-          el.value = '${textEscaped}';
+          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 || '') + ']';
@@ -784,12 +802,32 @@ URL: ${info.url}`;
         (function() {
           const elements = [];
           const selectors = 'a, button, input, select, textarea, [role="button"], [onclick]';
-          document.querySelectorAll(selectors).forEach((el, i) => {
-            if (i > 50) return; // Cap at 50 elements
+          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) return; // Skip hidden
+            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;
+              }
+            }
 
-            const info = {
+            elements.push({
               tag: el.tagName.toLowerCase(),
               text: (el.textContent || '').trim().slice(0, 80),
               type: el.getAttribute('type') || '',
@@ -797,12 +835,9 @@ URL: ${info.url}`;
               id: el.id || '',
               href: el.getAttribute('href') || '',
               placeholder: el.getAttribute('placeholder') || '',
-              selector: el.id ? '#' + el.id
-                : el.className ? el.tagName.toLowerCase() + '.' + el.className.split(' ')[0]
-                : el.tagName.toLowerCase() + ':nth-of-type(' + (i+1) + ')',
-            };
-            elements.push(info);
-          });
+              selector: selector,
+            });
+          }
           return JSON.stringify(elements, null, 2);
         })()
       `,
@@ -820,12 +855,23 @@ function findChromePath() {
     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/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") {
-    for (const name of ["google-chrome", "google-chrome-stable", "chromium-browser", "chromium"]) {
+    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",
@@ -842,31 +888,53 @@ function findChromePath() {
       process.env["PROGRAMFILES(X86)"],
       process.env.LOCALAPPDATA
     ].filter(Boolean);
+    const subPaths = [
+      "Google\\Chrome\\Application\\chrome.exe",
+      "Microsoft\\Edge\\Application\\msedge.exe",
+      "BraveSoftware\\Brave-Browser\\Application\\brave.exe"
+    ];
     for (const prefix of prefixes) {
-      const p = `${prefix}\\Google\\Chrome\\Application\\chrome.exe`;
-      if (existsSync(p)) return p;
+      for (const sub of subPaths) {
+        const p = `${prefix}\\${sub}`;
+        if (existsSync(p)) return p;
+      }
     }
     return null;
   }
   return null;
 }
-function isChromeRunning() {
+function isChromeRunning(chromePath) {
   try {
     if (platform() === "win32") {
-      const out2 = execSync('tasklist /FI "IMAGENAME eq chrome.exe" /NH', {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"]
-      });
-      return out2.includes("chrome.exe");
+      const out2 = 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(out2);
     }
     if (platform() === "darwin") {
-      const out2 = execSync('pgrep -f "Google Chrome.app/Contents/MacOS/Google Chrome"', {
+      if (chromePath) {
+        const appDir = chromePath.replace(/\/Contents\/MacOS\/.*$/, "");
+        const out3 = execSync(`pgrep -f ${JSON.stringify(appDir)}`, {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        return out3.trim().length > 0;
+      }
+      const out2 = execSync(
+        'pgrep -f "(Google Chrome|Microsoft Edge|Brave Browser|Chromium).app/Contents/MacOS/"',
+        { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+      );
+      return out2.trim().length > 0;
+    }
+    if (chromePath) {
+      const out2 = execSync(`pgrep -f ${JSON.stringify(chromePath)} 2>/dev/null || true`, {
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
       });
       return out2.trim().length > 0;
     }
-    const out = execSync("pgrep -f '(chrome|chromium)' 2>/dev/null || true", {
+    const out = execSync("pgrep -f '(chrome|chromium|msedge|brave)' 2>/dev/null || true", {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     });
@@ -875,21 +943,30 @@ function isChromeRunning() {
     return false;
   }
 }
-async function killChromeGracefully() {
+function macAppName(chromePath) {
+  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";
+}
+async function killChromeGracefully(chromePath) {
   const os = platform();
   try {
     if (os === "darwin") {
-      execSync(`osascript -e 'quit app "Google Chrome"'`, {
+      const app = macAppName(chromePath);
+      execSync(`osascript -e 'quit app "${app}"'`, {
         timeout: 5e3,
         stdio: ["pipe", "pipe", "pipe"]
       });
     } else if (os === "linux") {
-      execSync("pkill -TERM -f chrome", {
+      execSync(`pkill -TERM -f ${JSON.stringify(chromePath)}`, {
         timeout: 5e3,
         stdio: ["pipe", "pipe", "pipe"]
       });
     } else if (os === "win32") {
-      execSync("taskkill /IM chrome.exe", {
+      const exe = chromePath.split("\\").pop() || "chrome.exe";
+      execSync(`taskkill /IM "${exe}"`, {
         timeout: 5e3,
         stdio: ["pipe", "pipe", "pipe"]
       });
@@ -898,33 +975,94 @@ async function killChromeGracefully() {
   }
   const start = Date.now();
   while (Date.now() - start < 8e3) {
-    if (!isChromeRunning()) return;
+    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...");
   try {
     if (os === "win32") {
-      execSync("taskkill /F /IM chrome.exe", {
+      const exe = chromePath.split("\\").pop() || "chrome.exe";
+      execSync(`taskkill /F /IM "${exe}"`, {
         stdio: ["pipe", "pipe", "pipe"]
       });
     } else {
-      execSync("pkill -9 -f chrome", {
+      execSync(`pkill -9 -f ${JSON.stringify(chromePath)}`, {
         stdio: ["pipe", "pipe", "pipe"]
       });
     }
   } catch {
   }
   await new Promise((r) => setTimeout(r, 1e3));
+  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 {
+          }
+        }
+      }
+    }
+  }
 }
 function spawnChrome(chromePath, port) {
   const cdpFlag = `--remote-debugging-port=${port}`;
-  log.debug(`Spawning Chrome: ${chromePath} ${cdpFlag} --restore-last-session`);
-  const child = spawn(chromePath, [cdpFlag, "--restore-last-session"], {
-    detached: true,
-    stdio: "ignore"
+  const os = platform();
+  let child;
+  if (os === "darwin") {
+    const appName = macAppName(chromePath);
+    log.debug(
+      `Spawning browser via: open -a "${appName}" --args ${cdpFlag} --restore-last-session`
+    );
+    child = spawn("open", ["-a", appName, "--args", cdpFlag, "--restore-last-session"], {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } else {
+    log.debug(`Spawning Chrome: ${chromePath} ${cdpFlag} --restore-last-session`);
+    child = spawn(chromePath, [cdpFlag, "--restore-last-session"], {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  }
+  let stderr = "";
+  child.stderr?.on("data", (chunk) => {
+    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) {
+        const lines = stderr.split("\n").filter(Boolean).slice(0, 5);
+        for (const line of lines) {
+          log.debug(`  chrome stderr: ${line}`);
+        }
+      }
+    }
+  });
   child.unref();
   return child;
 }
@@ -973,39 +1111,71 @@ async function ensureBrowserAvailable(port = 9222) {
     return { success: false, action: "chrome_not_found" };
   }
   log.debug(`Found Chrome at: ${chromePath}`);
-  const running = isChromeRunning();
-  log.debug(`Chrome currently running: ${running}`);
+  const running = isChromeRunning(chromePath);
+  log.debug(`Browser currently running: ${running}`);
   if (running) {
-    log.debug("Killing Chrome gracefully for restart with CDP...");
-    await killChromeGracefully();
-    spawnChrome(chromePath, port);
+    log.debug("Killing browser gracefully for restart with CDP...");
+    await killChromeGracefully(chromePath);
+    if (isChromeRunning(chromePath)) {
+      log.debug("Browser still running after kill attempt \u2014 cannot restart with CDP");
+      return {
+        success: false,
+        action: "launch_failed",
+        chromePath,
+        detail: "Could not stop the existing browser process. Please quit the browser manually and run assistme again."
+      };
+    }
+    await new Promise((r) => setTimeout(r, 2e3));
+    const child2 = spawnChrome(chromePath, port);
     if (await waitForCDP(browser)) {
       return { success: true, action: "restarted", chromePath };
     }
+    if (child2.exitCode !== null) {
+      log.debug(
+        `Browser process already exited (code ${child2.exitCode}) \u2014 may have crashed or profile is locked`
+      );
+      return {
+        success: false,
+        action: "launch_failed",
+        chromePath,
+        detail: `Browser exited immediately (code ${child2.exitCode}). The profile may be locked. Try closing all browser windows first, then run assistme again.`
+      };
+    }
     log.debug("First CDP wait timed out after restart, retrying...");
     if (await waitForCDP(browser, 15e3)) {
       return { success: true, action: "restarted", chromePath };
     }
+    const stillRunning2 = isChromeRunning(chromePath);
     return {
       success: false,
       action: "launch_failed",
       chromePath,
-      detail: "Chrome was restarted but CDP did not become reachable within timeout."
+      detail: stillRunning2 ? "Browser is running but CDP port is not responding. Try: 1) Quit the browser completely, 2) Run assistme again." : "Browser was restarted but exited unexpectedly. Try launching it manually to check for errors."
     };
   }
-  spawnChrome(chromePath, port);
+  const child = spawnChrome(chromePath, port);
   if (await waitForCDP(browser)) {
     return { success: true, action: "launched", chromePath };
   }
+  if (child.exitCode !== null) {
+    log.debug(`Browser process already exited (code ${child.exitCode})`);
+    return {
+      success: false,
+      action: "launch_failed",
+      chromePath,
+      detail: `Browser exited immediately (code ${child.exitCode}). Try launching it manually to see any error dialogs.`
+    };
+  }
   log.debug("First CDP wait timed out after launch, retrying...");
   if (await waitForCDP(browser, 15e3)) {
     return { success: true, action: "launched", chromePath };
   }
+  const stillRunning = isChromeRunning(chromePath);
   return {
     success: false,
     action: "launch_failed",
     chromePath,
-    detail: "Chrome was launched but CDP did not become reachable within timeout."
+    detail: stillRunning ? "Chrome is running but CDP port is not responding. Try quitting Chrome completely and running assistme again." : "Chrome exited unexpectedly after launch."
   };
 }
 var browserInstance = null;
@@ -1161,7 +1331,7 @@ import {
   readFileSync,
   writeFileSync,
   statSync,
-  unlinkSync,
+  unlinkSync as unlinkSync2,
   rmSync
 } from "fs";
 import { join, basename, dirname } from "path";
@@ -1581,9 +1751,9 @@ ${content}
         await execUnzip(`unzip -o "${zipPath}" -d "${skillDir}"`, {
           timeout: 15e3
         });
-        unlinkSync(zipPath);
+        unlinkSync2(zipPath);
       } catch {
-        unlinkSync(zipPath);
+        unlinkSync2(zipPath);
         const fileResp = await fetch(
           `${CLAWHUB_API}/skills/${encodeURIComponent(name)}/file?path=SKILL.md&tag=latest`
         );
@@ -1654,7 +1824,7 @@ ${content}
       if (dir !== SKILLS_DIR) {
         rmSync(dir, { recursive: true, force: true });
       } else {
-        unlinkSync(skill.filePath);
+        unlinkSync2(skill.filePath);
       }
       this.skills.delete(name);
       return true;
@@ -2192,6 +2362,18 @@ ${stderr}` : "";
 }
 
 // src/tools/index.ts
+async function ensureConnected(browser, tabIndex) {
+  if (browser.isConnected() && tabIndex === void 0) return;
+  if (!await browser.isAvailable()) {
+    const result = await ensureBrowserAvailable();
+    if (!result.success) {
+      throw new Error(
+        `Chrome is not available (${result.action}). ${result.detail || "Please ensure Google Chrome is installed."}`
+      );
+    }
+  }
+  await browser.connect(tabIndex);
+}
 async function executeTool(name, input) {
   const browser = getBrowser();
   switch (name) {
@@ -2218,34 +2400,35 @@ async function executeTool(name, input) {
       return executeShell(input.command, input.cwd);
     // ── Browser (CDP) ───────────────────────────────────────
     case "browser_connect": {
-      if (!await browser.isAvailable()) {
-        const result = await ensureBrowserAvailable();
-        if (!result.success) {
-          throw new Error(
-            `Failed to auto-launch Chrome (${result.action}). Please ensure Google Chrome is installed.`
-          );
-        }
-      }
-      return browser.connect(input.tab_index);
+      await ensureConnected(browser, input.tab_index);
+      return browser.isConnected() ? "Connected to browser." : "Failed to connect.";
     }
     case "browser_navigate":
-      if (!browser.isConnected()) await browser.connect();
+      await ensureConnected(browser);
       return browser.navigate(input.url);
     case "browser_read_page":
+      await ensureConnected(browser);
       return browser.readPage();
     case "browser_screenshot":
+      await ensureConnected(browser);
       return browser.screenshot();
     case "browser_click":
+      await ensureConnected(browser);
       return browser.click(input.selector);
     case "browser_type":
+      await ensureConnected(browser);
       return browser.typeText(input.selector, input.text);
     case "browser_press_key":
+      await ensureConnected(browser);
       return browser.pressKey(input.key);
     case "browser_scroll":
+      await ensureConnected(browser);
       return input.direction === "up" ? browser.scrollUp() : browser.scrollDown();
     case "browser_get_elements":
+      await ensureConnected(browser);
       return browser.getInteractiveElements();
     case "browser_evaluate":
+      await ensureConnected(browser);
       return browser.evaluate(input.expression);
     case "browser_list_tabs":
       return browser.listTabs();
@@ -2264,7 +2447,23 @@ async function executeTool(name, input) {
       console.log(`  (Waiting up to ${waitSeconds}s for you to complete this)`);
       console.log("\u2501".repeat(60));
       console.log("\n");
-      await new Promise((r) => setTimeout(r, waitSeconds * 1e3));
+      let initialUrl = "";
+      try {
+        const info = await browser.getPageInfo();
+        initialUrl = info.url;
+      } catch {
+      }
+      const deadline = Date.now() + waitSeconds * 1e3;
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 3e3));
+        try {
+          const info = await browser.getPageInfo();
+          if (initialUrl && info.url !== initialUrl) {
+            break;
+          }
+        } catch {
+        }
+      }
       try {
         const pageInfo = await browser.readPage();
         return `User action wait completed. Current page state:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistme",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "AssistMe CLI Agent - AI-powered assistant that controls your real browser",
   "type": "module",
   "main": "dist/index.js",

package/src/tools/browser.ts

@@ -17,7 +17,7 @@
 import { WebSocket } from "ws";
 import { execSync, spawn, type ChildProcess } from "node:child_process";
 import { platform } from "node:os";
-import { existsSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { log } from "../utils/logger.js";
 
 interface CDPTab {
@@ -110,9 +110,21 @@ export class BrowserController {
     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(() => {});
@@ -135,15 +147,22 @@ export class BrowserController {
 
       this.ws.on("error", (err) => {
         this.connected = false;
-        reject(new Error(`WebSocket error: ${err.message}`));
+        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();
       });
-
-      setTimeout(() => reject(new Error("Connection timeout")), 5000);
     });
   }
 
@@ -261,12 +280,12 @@ export class BrowserController {
 
   async readElement(selector: string): Promise<string> {
     this.ensureConnected();
-    const escaped = selector.replace(/'/g, "\\'");
+    const selectorJS = JSON.stringify(selector);
     const result = await this.send("Runtime.evaluate", {
       expression: `
         (function() {
-          const el = document.querySelector('${escaped}');
-          if (!el) return 'Element not found: ${escaped}';
+          const el = document.querySelector(${selectorJS});
+          if (!el) return 'Element not found: ' + ${selectorJS};
           return el.innerText || el.textContent || el.value || '(empty)';
         })()
       `,
@@ -305,13 +324,13 @@ export class BrowserController {
 
   async click(selector: string): Promise<string> {
     this.ensureConnected();
-    const escaped = selector.replace(/'/g, "\\'");
+    const selectorJS = JSON.stringify(selector);
 
     const result = await this.send("Runtime.evaluate", {
       expression: `
         (function() {
-          const el = document.querySelector('${escaped}');
-          if (!el) return 'Element not found: ${escaped}';
+          const el = document.querySelector(${selectorJS});
+          if (!el) return 'Element not found: ' + ${selectorJS};
 
           // Scroll into view
           el.scrollIntoView({ block: 'center', behavior: 'instant' });
@@ -331,17 +350,19 @@ export class BrowserController {
 
   async typeText(selector: string, text: string): Promise<string> {
     this.ensureConnected();
-    const escaped = selector.replace(/'/g, "\\'");
-    const textEscaped = text.replace(/'/g, "\\'").replace(/\\/g, "\\\\");
+    // 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('${escaped}');
-          if (!el) return 'Element not found: ${escaped}';
+          const el = document.querySelector(${selectorJS});
+          if (!el) return 'Element not found: ' + ${selectorJS};
 
           el.focus();
-          el.value = '${textEscaped}';
+          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 || '') + ']';
@@ -513,12 +534,32 @@ export class BrowserController {
         (function() {
           const elements = [];
           const selectors = 'a, button, input, select, textarea, [role="button"], [onclick]';
-          document.querySelectorAll(selectors).forEach((el, i) => {
-            if (i > 50) return; // Cap at 50 elements
+          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) return; // Skip hidden
-
-            const info = {
+            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') || '',
@@ -526,12 +567,9 @@ export class BrowserController {
               id: el.id || '',
               href: el.getAttribute('href') || '',
               placeholder: el.getAttribute('placeholder') || '',
-              selector: el.id ? '#' + el.id
-                : el.className ? el.tagName.toLowerCase() + '.' + el.className.split(' ')[0]
-                : el.tagName.toLowerCase() + ':nth-of-type(' + (i+1) + ')',
-            };
-            elements.push(info);
-          });
+              selector: selector,
+            });
+          }
           return JSON.stringify(elements, null, 2);
         })()
       `,
@@ -559,12 +597,23 @@ export function findChromePath(): string | null {
       "/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") {
-    for (const name of ["google-chrome", "google-chrome-stable", "chromium-browser", "chromium"]) {
+    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",
@@ -584,9 +633,17 @@ export function findChromePath(): string | null {
       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) {
-      const p = `${prefix}\\Google\\Chrome\\Application\\chrome.exe`;
-      if (existsSync(p)) return p;
+      for (const sub of subPaths) {
+        const p = `${prefix}\\${sub}`;
+        if (existsSync(p)) return p;
+      }
     }
     return null;
   }
@@ -595,28 +652,45 @@ export function findChromePath(): string | null {
 }
 
 /**
- * Check if any Chrome process is currently running.
+ * Check if a Chromium-based browser is currently running.
+ * Optionally pass the specific browser binary path for precise matching.
  */
-export function isChromeRunning(): boolean {
+export function isChromeRunning(chromePath?: string): boolean {
   try {
     if (platform() === "win32") {
-      const out = execSync('tasklist /FI "IMAGENAME eq chrome.exe" /NH', {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-      return out.includes("chrome.exe");
+      // 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") {
-      // Match the main Chrome process (not helper/renderer sub-processes).
-      // No trailing $ — the process command line includes flags after the binary.
-      const out = execSync('pgrep -f "Google Chrome.app/Contents/MacOS/Google Chrome"', {
+      // 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;
     }
-    // Linux — match common chrome binary names
-    const out = execSync("pgrep -f '(chrome|chromium)' 2>/dev/null || true", {
+    const out = execSync("pgrep -f '(chrome|chromium|msedge|brave)' 2>/dev/null || true", {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
     });
@@ -627,24 +701,37 @@ export function isChromeRunning(): boolean {
 }
 
 /**
- * Gracefully quit Chrome, then force-kill if it doesn't exit in time.
+ * 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(): Promise<void> {
+async function killChromeGracefully(chromePath: string): Promise<void> {
   const os = platform();
   try {
     if (os === "darwin") {
-      // osascript sends a clean "quit" — Chrome saves session state
-      execSync("osascript -e 'quit app \"Google Chrome\"'", {
+      const app = macAppName(chromePath);
+      execSync(`osascript -e 'quit app "${app}"'`, {
         timeout: 5000,
         stdio: ["pipe", "pipe", "pipe"],
       });
     } else if (os === "linux") {
-      execSync("pkill -TERM -f chrome", {
+      // 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") {
-      execSync("taskkill /IM chrome.exe", {
+      const exe = chromePath.split("\\").pop() || "chrome.exe";
+      execSync(`taskkill /IM "${exe}"`, {
         timeout: 5000,
         stdio: ["pipe", "pipe", "pipe"],
       });
@@ -653,50 +740,130 @@ async function killChromeGracefully(): Promise<void> {
     /* may already be closed */
   }
 
-  // Wait for Chrome to fully exit (up to 8s)
+  // Wait for browser to fully exit (up to 8s)
   const start = Date.now();
   while (Date.now() - start < 8000) {
-    if (!isChromeRunning()) return;
+    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") {
-      execSync("taskkill /F /IM chrome.exe", {
+      const exe = chromePath.split("\\").pop() || "chrome.exe";
+      execSync(`taskkill /F /IM "${exe}"`, {
         stdio: ["pipe", "pipe", "pipe"],
       });
     } else {
-      execSync("pkill -9 -f chrome", {
+      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 */
+          }
+        }
+      }
+    }
+  }
 }
 
 /**
  * Spawn Chrome with the remote-debugging-port flag.
  * Returns the child process so callers can detect early failures.
+ *
+ * On macOS, uses `open -a` which goes through Launch Services — the correct
+ * way to launch a .app bundle and ensure flags reach the Chrome process.
+ * Direct binary invocation on macOS can fail because Chrome's Mach-O binary
+ * goes through framework wrappers that may drop command-line flags.
+ *
+ * IMPORTANT: On macOS, `open -a` ignores --args if Chrome is ALREADY running.
+ * Callers must ensure Chrome is fully quit before calling this function.
  */
 function spawnChrome(chromePath: string, port: number): ChildProcess {
   const cdpFlag = `--remote-debugging-port=${port}`;
+  const os = platform();
+
+  let child: ChildProcess;
+
+  if (os === "darwin") {
+    const appName = macAppName(chromePath);
+    log.debug(
+      `Spawning browser via: open -a "${appName}" --args ${cdpFlag} --restore-last-session`
+    );
+    child = spawn("open", ["-a", appName, "--args", cdpFlag, "--restore-last-session"], {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } else {
+    log.debug(`Spawning Chrome: ${chromePath} ${cdpFlag} --restore-last-session`);
+    child = spawn(chromePath, [cdpFlag, "--restore-last-session"], {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  }
 
-  // Always invoke the Chrome binary directly rather than `open -a`.
-  // On macOS, `open -a` silently ignores --args when Chrome is already
-  // running, which would cause CDP to never be enabled.
-  log.debug(`Spawning Chrome: ${chromePath} ${cdpFlag} --restore-last-session`);
-  const child = spawn(chromePath, [cdpFlag, "--restore-last-session"], {
-    detached: true,
-    stdio: "ignore",
+  // 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;
 }
@@ -791,51 +958,97 @@ export async function ensureBrowserAvailable(port = 9222): Promise<AutoLaunchRes
 
   log.debug(`Found Chrome at: ${chromePath}`);
 
-  const running = isChromeRunning();
-  log.debug(`Chrome currently running: ${running}`);
+  const running = isChromeRunning(chromePath);
+  log.debug(`Browser currently running: ${running}`);
 
-  // Case 3: Chrome running without CDP → restart
+  // Case 3: Browser running without CDP → restart
   if (running) {
-    log.debug("Killing Chrome gracefully for restart with CDP...");
-    await killChromeGracefully();
-    spawnChrome(chromePath, port);
+    log.debug("Killing browser gracefully for restart with CDP...");
+    await killChromeGracefully(chromePath);
+
+    // Verify browser is fully dead — critical on macOS where `open -a`
+    // ignores --args if the app is still alive.
+    if (isChromeRunning(chromePath)) {
+      log.debug("Browser still running after kill attempt — cannot restart with CDP");
+      return {
+        success: false,
+        action: "launch_failed",
+        chromePath,
+        detail:
+          "Could not stop the existing browser process. Please quit the browser manually and run assistme again.",
+      };
+    }
+
+    // Extra wait for profile lock release after kill
+    await new Promise((r) => setTimeout(r, 2000));
+
+    const child = spawnChrome(chromePath, port);
 
     if (await waitForCDP(browser)) {
       return { success: true, action: "restarted", chromePath };
     }
 
-    // Retry once — Chrome can be slow to start (extensions, session restore)
+    // Check if browser process exited immediately
+    if (child.exitCode !== null) {
+      log.debug(
+        `Browser process already exited (code ${child.exitCode}) — may have crashed or profile is locked`
+      );
+      return {
+        success: false,
+        action: "launch_failed",
+        chromePath,
+        detail: `Browser exited immediately (code ${child.exitCode}). The profile may be locked. Try closing all browser windows first, then run assistme again.`,
+      };
+    }
+
+    // Retry once — browser can be slow to start (extensions, session restore)
     log.debug("First CDP wait timed out after restart, retrying...");
     if (await waitForCDP(browser, 15000)) {
       return { success: true, action: "restarted", chromePath };
     }
 
+    const stillRunning = isChromeRunning(chromePath);
     return {
       success: false,
       action: "launch_failed",
       chromePath,
-      detail: "Chrome was restarted but CDP did not become reachable within timeout.",
+      detail: stillRunning
+        ? "Browser is running but CDP port is not responding. Try: 1) Quit the browser completely, 2) Run assistme again."
+        : "Browser was restarted but exited unexpectedly. Try launching it manually to check for errors.",
     };
   }
 
-  // Case 4: Chrome not running → launch
-  spawnChrome(chromePath, port);
+  // Case 4: Browser not running → launch
+  const child = spawnChrome(chromePath, port);
 
   if (await waitForCDP(browser)) {
     return { success: true, action: "launched", chromePath };
   }
 
+  if (child.exitCode !== null) {
+    log.debug(`Browser process already exited (code ${child.exitCode})`);
+    return {
+      success: false,
+      action: "launch_failed",
+      chromePath,
+      detail: `Browser exited immediately (code ${child.exitCode}). Try launching it manually to see any error dialogs.`,
+    };
+  }
+
   // Retry once
   log.debug("First CDP wait timed out after launch, retrying...");
   if (await waitForCDP(browser, 15000)) {
     return { success: true, action: "launched", chromePath };
   }
 
+  const stillRunning = isChromeRunning(chromePath);
   return {
     success: false,
     action: "launch_failed",
     chromePath,
-    detail: "Chrome was launched but CDP did not become reachable within timeout.",
+    detail: stillRunning
+      ? "Chrome is running but CDP port is not responding. Try quitting Chrome completely and running assistme again."
+      : "Chrome exited unexpectedly after launch.",
   };
 }
 

package/src/tools/index.ts

@@ -1,4 +1,4 @@
-import { getBrowser, ensureBrowserAvailable } from "./browser.js";
+import { type BrowserController, getBrowser, ensureBrowserAvailable } from "./browser.js";
 import {
   readFileContent,
   writeFileContent,
@@ -270,6 +270,25 @@ export function getToolDefinitions(): ToolDefinition[] {
   ];
 }
 
+/**
+ * Ensure Chrome is running with CDP and we have an active WebSocket connection.
+ * Called lazily by every browser tool so the user never has to call browser_connect explicitly.
+ */
+async function ensureConnected(browser: BrowserController, tabIndex?: number): Promise<void> {
+  if (browser.isConnected() && tabIndex === undefined) return;
+
+  // Auto-launch Chrome if CDP is not reachable
+  if (!(await browser.isAvailable())) {
+    const result = await ensureBrowserAvailable();
+    if (!result.success) {
+      throw new Error(
+        `Chrome is not available (${result.action}). ${result.detail || "Please ensure Google Chrome is installed."}`
+      );
+    }
+  }
+  await browser.connect(tabIndex);
+}
+
 export async function executeTool(name: string, input: Record<string, unknown>): Promise<string> {
   const browser = getBrowser();
 
@@ -298,36 +317,35 @@ export async function executeTool(name: string, input: Record<string, unknown>):
 
     // ── Browser (CDP) ───────────────────────────────────────
     case "browser_connect": {
-      // Auto-launch Chrome if CDP is not reachable
-      if (!(await browser.isAvailable())) {
-        const result = await ensureBrowserAvailable();
-        if (!result.success) {
-          throw new Error(
-            `Failed to auto-launch Chrome (${result.action}). ` +
-              "Please ensure Google Chrome is installed."
-          );
-        }
-      }
-      return browser.connect(input.tab_index as number | undefined);
+      await ensureConnected(browser, input.tab_index as number | undefined);
+      return browser.isConnected() ? "Connected to browser." : "Failed to connect.";
     }
     case "browser_navigate":
-      if (!browser.isConnected()) await browser.connect();
+      await ensureConnected(browser);
       return browser.navigate(input.url as string);
     case "browser_read_page":
+      await ensureConnected(browser);
       return browser.readPage();
     case "browser_screenshot":
+      await ensureConnected(browser);
       return browser.screenshot();
     case "browser_click":
+      await ensureConnected(browser);
       return browser.click(input.selector as string);
     case "browser_type":
+      await ensureConnected(browser);
       return browser.typeText(input.selector as string, input.text as string);
     case "browser_press_key":
+      await ensureConnected(browser);
       return browser.pressKey(input.key as string);
     case "browser_scroll":
+      await ensureConnected(browser);
       return (input.direction as string) === "up" ? browser.scrollUp() : browser.scrollDown();
     case "browser_get_elements":
+      await ensureConnected(browser);
       return browser.getInteractiveElements();
     case "browser_evaluate":
+      await ensureConnected(browser);
       return browser.evaluate(input.expression as string);
     case "browser_list_tabs":
       return browser.listTabs();
@@ -350,10 +368,31 @@ export async function executeTool(name: string, input: Record<string, unknown>):
       console.log("━".repeat(60));
       console.log("\n");
 
-      // Wait for the user to act (they do it in their browser)
-      await new Promise((r) => setTimeout(r, waitSeconds * 1000));
+      // Capture current page URL to detect navigation (sign that user acted)
+      let initialUrl = "";
+      try {
+        const info = await browser.getPageInfo();
+        initialUrl = info.url;
+      } catch {
+        /* may not be connected */
+      }
+
+      // Poll every 3s instead of blind wait — detect URL changes early
+      const deadline = Date.now() + waitSeconds * 1000;
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 3000));
+        try {
+          const info = await browser.getPageInfo();
+          if (initialUrl && info.url !== initialUrl) {
+            // User navigated — action likely completed
+            break;
+          }
+        } catch {
+          // Connection may have dropped during user action
+        }
+      }
 
-      // After waiting, read the page to see current state
+      // Read the page to see current state
       try {
         const pageInfo = await browser.readPage();
         return `User action wait completed. Current page state:\n${pageInfo.slice(0, 3000)}`;