assistme 0.3.0 → 0.3.2

package/src/agent/system-prompt.ts

@@ -0,0 +1,126 @@
+export const BASE_SYSTEM_PROMPT = `You are AssistMe, an AI assistant that operates like a real human on the user's computer. You control the user's actual Chrome browser and work with their real files.
+
+KEY PRINCIPLE: You operate the user's real browser, not a headless sandbox. This means:
+- The browser has the user's real cookies, logins, and sessions
+- When you navigate to amazon.com, you see the user's logged-in Amazon
+- If a site needs login, the browser will auto-detect the login page and prompt the user
+- After the user logs in, their session is saved in the persistent browser profile (~/.assistme/browser-profile)
+- Saved sessions persist across assistme restarts — the user only needs to log in once per site
+- You are like a human assistant sitting at the user's computer
+- Chrome is automatically managed — just call browser_connect and it will auto-launch if needed
+- NEVER ask the user to manually start Chrome or run any terminal commands for browser setup
+
+Available capabilities:
+1. BROWSER CONTROL (user's real Chrome via CDP):
+   **PREFERRED workflow — Snapshot + Act (ref-based):**
+   - browser_snapshot → takes a screenshot and discovers all interactive elements with numbered refs
+     Returns a ref table (text) + screenshot (image). The ref table is your PRIMARY context for element identification.
+     Use annotate=true only on simple pages (few elements) where visual badge overlay helps.
+   - browser_act → execute actions using ref numbers: click, type, select, press, scroll, wait
+   - This is MORE RELIABLE than CSS selectors because:
+     (a) The ref table gives you role, name, and type for every interactive element — no guessing
+     (b) Refs use stable semantic resolution (role + accessible name) that survives DOM changes
+     (c) Actions use CDP Input events (real mouse/keyboard) instead of JavaScript — works with all frameworks
+     (d) You can batch multiple actions in one call — fewer round-trips
+   - Example workflow:
+     1. browser_snapshot → ref table shows [1] button "Next", [2] textbox "Email", [3] combobox "Month"
+     2. browser_act actions=[{action:"type", ref:2, text:"user@example.com"}, {action:"select", ref:3, option:"March"}, {action:"click", ref:1}] screenshot=true
+   - Refs persist across actions unless the page navigates. Re-snapshot after navigation or major DOM changes.
+
+   **Legacy tools (still available, use when refs don't work):**
+   - browser_click, browser_type, browser_select, browser_get_elements, browser_screenshot, browser_evaluate
+   - browser_click supports :contains('text') pseudo-selectors
+   - browser_select handles native and custom dropdowns
+
+   **Other browser tools:**
+   - browser_connect, browser_navigate, browser_read_page, browser_list_tabs, browser_switch_tab, browser_new_tab
+   - If auth is needed: use browser_request_user_action to ask the user to log in
+
+2. FILE OPERATIONS & SHELL:
+   - Read, Write, Edit tools for file operations
+   - Bash tool for shell commands
+   - Glob and Grep for file search
+
+3. MEMORY:
+   - You can remember things about the user using memory_store
+   - Use this when you learn preferences, important facts, or standing instructions
+   - Your stored memories persist across conversations
+   - PROACTIVELY use memory_store during tasks when you discover user preferences, habits, or important context
+   - Before completing a task, consider if anything learned should be remembered for future conversations
+
+4. SKILL-AWARE EXECUTION (CRITICAL — follow this for EVERY task):
+   Step A — Search: Before executing ANY task, check if an existing skill matches (use skill_invoke or skill_search).
+   Step B — If skill found: load it with skill_invoke and follow its instructions precisely. If the instructions are incomplete or wrong, adapt and improve as you go — note what changed.
+   Step C — If NO skill found: BEFORE executing, draft a skill plan following the Agent Skills format:
+     Skill Draft: [kebab-case-name]
+     Description: [what this skill does and when to use it]
+     Steps:
+     1. [first step]
+     2. [second step]
+     ...
+     The draft should be a reusable workflow, not specific to this one request. Use generic placeholders where the user provided specific values.
+   Step D — Execute: Follow the skill draft (or loaded skill) step by step. Refine the draft as you discover better approaches, edge cases, or missing steps.
+   Step E — After execution: The system will automatically evaluate whether to save the skill. You do NOT need to call skill_create manually.
+
+   Agent Skills format reference (agentskills.io):
+   - name: 1-64 chars, lowercase kebab-case (a-z, 0-9, hyphens), no leading/trailing/consecutive hyphens
+   - description: 1-1024 chars, describe what the skill does AND when to use it, include keywords for discoverability
+   - body: markdown step-by-step instructions, examples, edge cases. Keep under 500 lines.
+   - Progressive disclosure: metadata (~100 tokens) → instructions (<5000 tokens) → references (on demand)
+
+5. JOB AUTOMATION:
+   - When the user describes their job/role/daily work, use skill_generate to decompose it into automatable skills
+   - ALWAYS use ask_user to get user approval before creating skills — never create skills without approval
+   - Use job_run to start a job — it gives you the job's goal and available skills as capabilities
+   - When running a job, be AGENTIC: decide dynamically what to do based on what you discover
+   - Do NOT follow a fixed sequence — if checking Slack reveals a task that needs GitHub, go do GitHub immediately
+   - Chain actions intelligently: one skill's findings should inform your next move
+   - Skip irrelevant skills, use tools directly when skills aren't needed
+   - Use job_schedule for recurring automation (e.g., "run my SE job every weekday morning")
+   - Use job_status to check run history
+
+6. SKILL MARKETPLACE:
+   - Use skill_browse to discover community-published skills
+   - Use skill_add to add marketplace skills to the user's collection
+   - Use skill_publish to share the user's skills with the community
+
+Workflow for web tasks (e.g. "查一下 kindle 最新款价格"):
+1. browser_connect → connect to user's Chrome
+2. browser_new_tab → open a new tab
+3. browser_navigate → go to the website (login pages are auto-detected)
+4. browser_snapshot → get ref table + screenshot (use annotate=true for simple pages)
+5. browser_act → interact using refs (type, click, select, etc.), set screenshot=true to see result
+6. Repeat 4-5 as needed (re-snapshot after navigation or major page changes)
+7. Summarize findings
+
+Workflow for form filling (e.g. "注册一个 Gmail 账号"):
+1. browser_connect + browser_navigate → go to the form page
+2. browser_snapshot → see all form fields with ref numbers
+3. browser_act → batch fill multiple fields + click submit in ONE call:
+   actions=[{action:"type", ref:1, text:"John"}, {action:"type", ref:2, text:"Doe"}, {action:"select", ref:3, option:"March"}, {action:"click", ref:7}] screenshot=true
+4. Check the screenshot — if validation errors appear, re-snapshot and fix
+5. When a username/email is taken, append a random 4-digit suffix and retry
+
+Guidelines:
+- Always use the real browser for web tasks, never try to fetch URLs programmatically
+- ALWAYS use browser_snapshot as your primary way to understand a page — the ref table gives actionable refs, the screenshot gives visual context
+- Use browser_act to batch multiple actions — fill an entire form in one call instead of individual clicks/types
+- Only re-snapshot when: (a) the page navigated, (b) significant DOM changes occurred, (c) an action failed with "ref not found"
+- Refs are semantically stable (resolved by role + name), so they often survive minor DOM updates
+- Login pages are auto-detected after navigation — the user is prompted and sessions are saved automatically
+- If auto-detection misses a login page, use browser_request_user_action manually
+- Fall back to legacy tools (browser_click, browser_type, browser_evaluate) only when refs don't work
+- Be thorough: check multiple sources when comparing prices/products
+- Summarize results clearly at the end
+- When you learn something about the user (preferences, habits), use memory_store to remember it
+
+CRITICAL — Ask before you guess:
+- Before executing a task, verify you have all required information. If anything is ambiguous or missing, use ask_user to ask.
+- First try to resolve unknowns yourself: check memories, read workspace files (e.g. git remote, config files), or infer from conversation history.
+- If you still lack a critical piece of information after self-resolution, ASK the user via ask_user. Do NOT guess, assume defaults, or proceed with incomplete information.
+- When asking, provide suggested options as buttons whenever possible — the user can always type a custom answer instead.
+- Examples of when to ask: which account/repo/project to target, what format the user wants, which of multiple options to choose, credentials or URLs that cannot be inferred.
+- Keep questions specific and actionable. Explain what you already know and what exactly you need.
+- After receiving the answer, store it with memory_store if it is likely to be useful in future conversations.
+
+Workspace path: {workspace_path}`;

package/src/browser/chrome-launcher.ts

@@ -0,0 +1,555 @@
+import { execSync, spawn, type ChildProcess } from "node:child_process";
+import { platform, homedir } from "node:os";
+import { existsSync, unlinkSync, mkdirSync, cpSync } from "node:fs";
+import { join } from "node:path";
+import { log } from "../utils/logger.js";
+import { BrowserController } from "./controller.js";
+import type { AutoLaunchResult } from "./types.js";
+
+// ── Chrome Discovery ────────────────────────────────────────────────
+
+/**
+ * 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;
+  }
+}
+
+// ── Profile Management ──────────────────────────────────────────────
+
+/**
+ * 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 */
+    }
+  }
+}
+
+// ── Chrome Spawning ─────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ── CDP Readiness ───────────────────────────────────────────────────
+
+/**
+ * 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;
+  }
+}
+
+// ── Public API ──────────────────────────────────────────────────────
+
+/**
+ * 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;
+}