bwb-browser 4.0.0 → 4.1.0

package/lib/browser.mjs

@@ -5,9 +5,9 @@
  * restart, orphan cleanup, and screenshot persistence.
  */
 
-import { spawn, execSync } from "child_process";
+import { spawn, execSync, execFileSync } from "child_process";
 import { homedir, platform } from "os";
-import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync, unlinkSync, readFileSync } from "fs";
 import { join } from "path";
 import CDP from "chrome-remote-interface";
 
@@ -35,8 +35,23 @@ export const cfg = {
   nuclear: false, // --single-process: max RAM saving, min stability. Opt-in only.
   idleMs: null, // null = auto (5min lean, off desktop); 0 = never teardown
   tabMax: null, // null = auto (3 lean, unlimited desktop); 0 = unlimited
+  attachPort: 0, // 0 = off (spawn own browser). N = attach to existing
+                 // browser's CDP port (e.g. 9222) — never spawns, never kills.
+  noSandbox: false, // disable the Chromium sandbox (auto on Termux / as root)
+  allowPrivate: false, // allow static fetches to loopback/private addresses
+  allowDomains: null, // optional host allowlist for navigation
+  readonly: false, // refuse every state-changing tool
+  confirmDestructive: true, // act-clicks on destructive labels need confirmation
+  alwaysBrowser: false, // skip the static rung entirely
+  journalFull: false, // journal full URLs (with query strings) and auto-restore
+  shotKeep: 50, // screenshots retained on disk
 };
 
+// True when connected to a foreign (user-owned) browser via --attach-port.
+// Attached browsers are never spawned, killed, or journal-restored —
+// bwb is a guest there. Tab hibernation still works but closes REAL tabs.
+export let attached = false;
+
 // ─── Environment ─────────────────────────────────────────────────────────────
 
 export function isTermux() {
@@ -77,24 +92,81 @@ export function pokeActivity() {
 
 // `fuser -k` and `lsof` can't read /proc/net/tcp on Termux/Android (permission denied).
 // Instead, kill by PID from `ps` — works on every platform.
-// Only kills bwb's headless Chrome instances (marked by `remote-debugging-port` flag),
-// NOT the user's normal Chrome browser.
+// Only kills bwb's own headless Chrome instances (marked by remote-debugging-port
+// AND our user-data-dir), NOT the user's normal Chrome browser.
+//
+// The process list is read with execFile and filtered in JS: the previous
+// `ps aux | grep … | xargs kill` pipeline put cfg.userDataDir into a shell
+// string with only `"` and `\` escaped, and it does not exist on Windows.
 export function killOrphanedChrome() {
+  if (platform() === "win32") return; // no ps/grep/awk/xargs; use the CDP port instead
+  let out;
   try {
-    // Only touch Chromes using OUR user-data-dir — never another agent's browser.
-    const scopedMatch = cfg.userDataDir
-      ? `grep "remote-debugging-port" | grep "${String(cfg.userDataDir).replace(/["\\]/g, "\\$&")}" | grep -v grep`
-      : `grep "remote-debugging-port" | grep -v grep`;
-    // SIGTERM first for clean shutdown
-    execSync(
-      `ps aux | ${scopedMatch} | awk '{print $2}' | xargs -r kill -15 2>/dev/null; true`,
-      { encoding: "utf8", timeout: 5000 }
-    );
-    // Give them a moment to exit cleanly, then SIGKILL survivors
-    execSync(
-      `sleep 1 && ps aux | ${scopedMatch} | awk '{print $2}' | xargs -r kill -9 2>/dev/null; true`,
-      { encoding: "utf8", timeout: 5000 }
-    );
+    out = execFileSync("ps", ["-eo", "pid=,args="], { encoding: "utf8", timeout: 5000 });
+  } catch {
+    return;
+  }
+  const scope = cfg.userDataDir ? String(cfg.userDataDir) : null;
+  const pids = [];
+  for (const line of out.split("\n")) {
+    const m = /^\s*(\d+)\s+(.*)$/.exec(line);
+    if (!m) continue;
+    const [, pid, args] = m;
+    if (!args.includes("remote-debugging-port")) continue;
+    if (args.includes("--type=")) continue; // renderers/zygotes die with the parent
+    if (scope && !args.includes(scope)) continue;
+    pids.push(Number(pid));
+  }
+  if (!pids.length) return;
+  for (const pid of pids) { try { process.kill(pid, "SIGTERM"); } catch {} }
+}
+
+// ─── Profile Lock (two agents, one profile) ───────────────────────────────────
+// Chrome locks its user-data-dir, but bwb's killOrphanedChrome runs first and
+// would SIGTERM the OTHER agent's browser. A tiny owner file turns that from
+// "one agent silently kills the other mid-task" into a clear error.
+
+function ownerLockPath() {
+  return cfg.userDataDir ? join(cfg.userDataDir, "bwb-owner.json") : null;
+}
+
+function processAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
+export function checkProfileLock() {
+  const path = ownerLockPath();
+  if (!path) return;
+  try {
+    const owner = JSON.parse(readFileSync(path, "utf8"));
+    if (owner.pid && owner.pid !== process.pid && processAlive(owner.pid)) {
+      throw new Error(
+        `Another bwb process (pid ${owner.pid}) is already using ${cfg.userDataDir}. ` +
+        `Sharing a profile makes them kill each other's browser. Use a different ` +
+        `--user-data-dir or --port, or stop that process.`
+      );
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("Another bwb process")) throw err;
+    // No lock, or unreadable/corrupt: not an error.
+  }
+}
+
+function writeProfileLock() {
+  const path = ownerLockPath();
+  if (!path) return;
+  try {
+    mkdirSync(cfg.userDataDir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify({ pid: process.pid, port: cfg.port, startedAt: Date.now() }), { mode: 0o600 });
+  } catch {}
+}
+
+function clearProfileLock() {
+  const path = ownerLockPath();
+  if (!path) return;
+  try {
+    const owner = JSON.parse(readFileSync(path, "utf8"));
+    if (owner.pid === process.pid) unlinkSync(path);
   } catch {}
 }
 
@@ -107,6 +179,7 @@ export function findBrowserPath(cliPath) {
 
   const os = platform();
   const home = homedir();
+  const lookup = platform() === "win32" ? "where" : "which";
 
   const candidates = {
     android: [
@@ -119,8 +192,11 @@ export function findBrowserPath(cliPath) {
       "chromium-browser",
       "chromium",
       "google-chrome-stable",
+      "brave-browser",
+      "brave",
       "/usr/bin/google-chrome",
       "/usr/bin/chromium-browser",
+      "/usr/bin/brave-browser",
       "/snap/bin/chromium",
     ],
     darwin: [
@@ -141,13 +217,31 @@ export function findBrowserPath(cliPath) {
       continue;
     }
     try {
-      const path = execSync(`which "${bin}" 2>/dev/null || echo "no"`, { encoding: "utf8", timeout: 3000 }).trim();
-      if (path && path !== "no") return path;
+      // No shell: the candidate list is data, never a command string.
+      const out = execFileSync(lookup, [bin], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] });
+      const path = String(out).split(/\r?\n/).map((l) => l.trim()).filter(Boolean)[0];
+      if (path) return path;
     } catch { /* try next */ }
   }
   return null;
 }
 
+/**
+ * Does Chromium's setuid/namespace sandbox work here?
+ *
+ * It does NOT on Termux (no user namespaces) and not when running as root or
+ * inside most Docker images — and there bwb genuinely cannot start without
+ * --no-sandbox. Everywhere else the sandbox is the main containment for a
+ * browser that an LLM is pointing at pages chosen by untrusted content, so it
+ * stays on. BWB_NO_SANDBOX=1 forces it off.
+ */
+function needsNoSandbox() {
+  if (cfg.noSandbox) return true;
+  if (isTermux()) return true;
+  if (process.platform === "win32") return false;
+  return typeof process.getuid === "function" && process.getuid() === 0;
+}
+
 function assertBrowserExists(cliPath) {
   const path = findBrowserPath(cliPath);
   if (!path) {
@@ -179,19 +273,49 @@ export async function ensureBrowser() {
   browserStartup = new Promise((res, rej) => { startResolve = res; startReject = rej; });
   browserStartup.catch(() => { browserStartup = null; });
 
+  // ─── Attach mode: guest on someone else's browser ──────────────────────
+  // No spawn, no orphan-kill, no journal restore (never navigate a user's
+  // tabs on connect). ensureDefaultTab() registers whatever is already open.
+  if (cfg.attachPort) {
+    (async () => {
+      try {
+        const port = cfg.attachPort;
+        const cdp = await CDP({ port });
+        protocol = cdp;
+        browser = null;
+        attached = true;
+        actualCdpPort = port;
+        startResolve(cdp);
+        pokeActivity();
+      } catch (err) {
+        browserStartup = null;
+        browserExited = true;
+        attached = false;
+        startReject(new Error(
+          `Attach failed: no browser listening on CDP port ${cfg.attachPort} (${err.message}). ` +
+          `Launch one with --remote-debugging-port=${cfg.attachPort} first.`
+        ));
+      }
+    })();
+    return browserStartup;
+  }
+  attached = false;
+
   (async () => {
     try {
       const browserPath = assertBrowserExists(cfg.browserPath);
+      checkProfileLock();
+      writeProfileLock();
       killOrphanedChrome();
       await new Promise(r => setTimeout(r, 500));
 
       const debugPort = cfg.port || 0;
+      const noSandbox = needsNoSandbox();
       const args = [
         "--headless",
-        "--no-sandbox",
+        ...(noSandbox ? ["--no-sandbox", "--disable-setuid-sandbox"] : []),
         "--disable-gpu",
         "--disable-dev-shm-usage",
-        "--disable-setuid-sandbox",
         "--disable-software-rasterizer",
         "--remote-debugging-port=" + debugPort,
         "--user-data-dir=" + cfg.userDataDir,
@@ -202,6 +326,9 @@ export async function ensureBrowser() {
 
       browser = spawn(browserPath, args, {
         stdio: ["ignore", "pipe", "pipe"],
+        // Own process group: a Ctrl-C or an ungraceful exit must take the
+        // renderer tree with it, not leave orphans behind.
+        detached: true,
         env: { ...process.env, DISPLAY: process.env.DISPLAY || ":0" },
       });
 
@@ -297,7 +424,8 @@ export async function stopBrowser(reason = "manual") {
       try { await protocol.close(); } catch {}
       protocol = null;
     }
-    if (browser) {
+    // Attached browsers are foreign — disconnect only, never kill.
+    if (browser && !attached) {
       try { browser.kill("SIGTERM"); } catch {}
       await new Promise(r => setTimeout(r, 1500));
       try { browser.kill("SIGKILL"); } catch {}
@@ -306,6 +434,7 @@ export async function stopBrowser(reason = "manual") {
   } catch {}
   browserExited = true; // next ensureBrowser() respawns fresh + restores journal
   actualCdpPort = null;
+  attached = false;
   browserStartup = null;
   cleaningUp = false;
   try {
@@ -318,7 +447,7 @@ export async function stopBrowser(reason = "manual") {
 // ─── Restart ──────────────────────────────────────────────────────────────────
 
 export async function restartBrowser() {
-  if (cleaningUp) return;
+  if (cleaningUp) return { status: "busy" };
   cleaningUp = true;
 
   try {
@@ -326,7 +455,9 @@ export async function restartBrowser() {
       try { await protocol.close(); } catch {}
       protocol = null;
     }
-    if (browser) {
+    // Attached browsers are foreign — disconnect only, never kill.
+    // Next ensureBrowser() re-attaches (no journal restore in attach mode).
+    if (browser && !attached) {
       browser.kill("SIGTERM");
       await new Promise(r => setTimeout(r, 2000));
       try { browser.kill("SIGKILL"); } catch {}
@@ -357,31 +488,57 @@ async function restoreJournalTabs() {
 
 // ─── Screenshot Helper ────────────────────────────────────────────────────────
 
+/**
+ * Write a screenshot to disk. The filename carried second-level precision, so
+ * two shots in the same second overwrote each other; and nothing ever cleaned
+ * up (on Termux this is the public Download folder — a long agent loop fills
+ * storage). Now: millisecond + random suffix, and the newest BWB_SHOT_KEEP
+ * files are kept.
+ */
 export function saveScreenshot(base64Data) {
-  const now = new Date();
-  const timestamp = now.toISOString().replace(/[:.]/g, "-").slice(0, 19);
-  const filename = `bwb-${timestamp}.jpeg`;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 23);
+  const rand = Math.random().toString(36).slice(2, 6);
+  const filename = `bwb-${stamp}-${rand}.jpeg`;
   const filepath = join(cfg.screenshotsDir, filename);
   try {
     mkdirSync(cfg.screenshotsDir, { recursive: true });
     writeFileSync(filepath, Buffer.from(base64Data, "base64"));
+    pruneScreenshots(cfg.screenshotsDir, cfg.shotKeep);
     return filepath;
   } catch {
     return null;
   }
 }
 
+function pruneScreenshots(dir, keep = 50) {
+  if (!keep || keep < 1) return;
+  try {
+    const files = readdirSync(dir)
+      .filter((f) => f.startsWith("bwb-") && f.endsWith(".jpeg"))
+      .map((f) => ({ f, t: statSync(join(dir, f)).mtimeMs }))
+      .sort((a, b) => b.t - a.t);
+    for (const { f } of files.slice(keep)) {
+      try { unlinkSync(join(dir, f)); } catch {}
+    }
+  } catch {}
+}
+
 // ─── Cleanup ──────────────────────────────────────────────────────────────────
 
 function cleanupSync() {
   if (cleaningUp) return;
   cleaningUp = true;
+  clearProfileLock();
   try {
     if (browser) {
-      browser.kill("SIGTERM");
-      setTimeout(() => {
-        try { browser?.kill("SIGKILL"); } catch {}
-      }, 3000);
+      const child = browser;
+      child.kill("SIGTERM");
+      // The old code armed a 3s SIGKILL timer and then the signal handler
+      // called process.exit(0) — so the timer never fired and a Chromium that
+      // ignored SIGTERM was orphaned. Kill the whole process group instead,
+      // synchronously, using the detached spawn above.
+      const pid = child.pid;
+      try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch {} }
       browser = null;
     }
   } catch {}

package/lib/config.mjs

@@ -0,0 +1,180 @@
+/**
+ * bwb-browser — Config resolution (pure, testable)
+ *
+ * Precedence: CLI flag > env var > default. Kept out of server.mjs so it can be
+ * unit-tested without booting an MCP server (see test/config.test.mjs).
+ */
+
+import { existsSync } from "fs";
+import { homedir, platform } from "os";
+import { join } from "path";
+
+/** Flags that take a value. Value = next token, if it isn't another flag. */
+const VALUE_FLAGS = {
+  "--browser-path": "browserPath",
+  "--port": "port",
+  "--user-data-dir": "userDataDir",
+  "--screenshots-dir": "screenshotsDir",
+  "--timeout": "navTimeout",
+  "--idle": "idleMs",
+  "--tab-max": "tabMax",
+  "--attach-port": "attachPort",
+  "--allow-domains": "allowDomains",
+};
+
+/** Flags that are booleans. `--flag`, `--flag true`, `--flag false`. */
+const BOOL_FLAGS = {
+  "--headless": "headless",
+  "--lean": "lean",
+  "--nuclear": "nuclear",
+  "--readonly": "readonly",
+  "--no-sandbox": "noSandbox",
+  "--always-browser": "alwaysBrowser",
+  "--journal-full": "journalFull",
+  "--confirm-destructive": "confirmDestructive",
+};
+
+/** Flags that take an integer value. */
+const INT_FLAGS = new Set([
+  "--port", "--timeout", "--idle", "--tab-max", "--attach-port",
+]);
+
+export class ConfigError extends Error {}
+
+/**
+ * Parse argv (without node/script) into a partial config.
+ * Bare booleans never swallow the next flag — `--nuclear --lean true` yields
+ * both. Unknown flags are an error instead of a silent typo.
+ */
+export function parseArgs(argv = []) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (BOOL_FLAGS[arg]) {
+      const next = argv[i + 1];
+      const key = BOOL_FLAGS[arg];
+      if (next === undefined || next.startsWith("--")) {
+        out[key] = true;
+      } else if (next === "true" || next === "false") {
+        out[key] = next === "true";
+        i++;
+      } else {
+        throw new ConfigError(`${arg} expects true or false, got "${next}"`);
+      }
+      continue;
+    }
+
+    if (VALUE_FLAGS[arg]) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new ConfigError(`${arg} requires a value`);
+      }
+      const key = VALUE_FLAGS[arg];
+      if (INT_FLAGS.has(arg)) {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 0) {
+          throw new ConfigError(`${arg} expects a non-negative integer, got "${value}"`);
+        }
+        out[key] = n;
+      } else {
+        out[key] = value;
+      }
+      i++;
+      continue;
+    }
+
+    // Flags handled by server.mjs itself (lifecycle, not config).
+    if (arg === "--version" || arg === "--help" || arg === "--setup"
+      || arg === "--dry-run" || arg === "--yes") {
+      out[`_passthrough_${arg.slice(2)}`] = true;
+      continue;
+    }
+
+    throw new ConfigError(`Unknown option: ${arg}`);
+  }
+  return out;
+}
+
+function defaultScreenshotsDir(env, isAndroid) {
+  const androidPath = "/storage/emulated/0/Download/bwb-screenshots";
+  if (isAndroid && existsSync("/storage/emulated/0/Download")) return androidPath;
+  if (env.TERMUX_VERSION) return androidPath;
+  return join(homedir(), "bwb-screenshots");
+}
+
+/**
+ * Resolve the full runtime config.
+ * @param {object} cli  output of parseArgs
+ * @param {object} env  process.env
+ * @param {object} opts {isTermux}
+ */
+export function resolveConfig(cli = {}, env = process.env, opts = {}) {
+  const isTermux = opts.isTermux ?? false;
+  const termux = isTermux || Boolean(
+    env.TERMUX_VERSION ||
+    env.PREFIX?.includes("com.termux") ||
+    env.HOME?.includes("com.termux")
+  );
+
+  const envInt = (name, fallback) => {
+    if (env[name] === undefined || env[name] === "") return fallback;
+    const n = Number(env[name]);
+    return Number.isInteger(n) && n >= 0 ? n : fallback;
+  };
+  const envBool = (name) => (env[name] === undefined ? undefined : env[name] !== "false");
+
+  const cfg = {};
+
+  cfg.port = cli.port ?? envInt("BWB_CDP_PORT", 0);
+  cfg.attachPort = cli.attachPort ?? envInt("BWB_ATTACH_PORT", 0);
+  cfg.headless = cli.headless ?? envBool("BWB_HEADLESS") ?? true;
+  cfg.browserPath = cli.browserPath ?? env.BWB_CHROME_PATH ?? null;
+
+  // Chromium's sandbox is kept where it works. --no-sandbox is needed on Termux,
+  // under root/Docker, or with an explicit BWB_NO_SANDBOX=1 — not everywhere.
+  cfg.noSandbox = cli.noSandbox ?? envBool("BWB_NO_SANDBOX") ?? false;
+
+  // Agent-safety policy (F27). readonly disables every state-changing tool;
+  // allowDomains is an optional host allowlist for goto/newTab/act navigation.
+  cfg.readonly = cli.readonly ?? envBool("BWB_READONLY") ?? false;
+  cfg.allowDomains = normalizeDomains(cli.allowDomains ?? env.BWB_ALLOW_DOMAINS ?? "");
+  cfg.confirmDestructive = cli.confirmDestructive ?? envBool("BWB_CONFIRM_DESTRUCTIVE") ?? true;
+
+  cfg.userDataDir = cli.userDataDir
+    ?? env.BWB_USER_DATA_DIR
+    ?? join(homedir(), ".cache", "bwb-browser");
+
+  cfg.screenshotsDir = cli.screenshotsDir
+    ?? env.BWB_SCREENSHOTS_DIR
+    ?? defaultScreenshotsDir(env, platform() === "android" || termux);
+
+  cfg.navTimeout = cli.navTimeout ?? envInt("BWB_NAV_TIMEOUT", 30000);
+  cfg.alwaysBrowser = cli.alwaysBrowser ?? envBool("BWB_ALWAYS_BROWSER") ?? false;
+
+  // v4 survival defaults: lean auto-detects Termux; mayfly + tab cap follow lean.
+  cfg.lean = cli.lean ?? envBool("BWB_LEAN") ?? termux;
+  cfg.nuclear = cli.nuclear ?? (env.BWB_NUCLEAR === "true");
+
+  cfg.idleMs = cli.idleMs
+    ?? (env.BWB_IDLE_MS !== undefined ? envInt("BWB_IDLE_MS", 0) : (cfg.lean ? 5 * 60 * 1000 : 0));
+  cfg.tabMax = cli.tabMax
+    ?? (env.BWB_TAB_MAX !== undefined ? envInt("BWB_TAB_MAX", 0) : (cfg.lean ? 3 : 0));
+
+  // Journal restore re-fires recorded URLs. Only automatic on a lean profile
+  // (the post-LMK resurrection flow); elsewhere it is opt-in (F09).
+  cfg.journalFull = cli.journalFull ?? (env.BWB_JOURNAL === "full");
+
+  cfg.allowPrivate = envBool("BWB_ALLOW_PRIVATE") ?? false;
+  cfg.shotKeep = envInt("BWB_SHOT_KEEP", 50);
+
+  return cfg;
+}
+
+function normalizeDomains(raw) {
+  if (!raw) return [];
+  const list = Array.isArray(raw) ? raw : String(raw).split(",");
+  return list
+    .map((d) => String(d).trim().toLowerCase().replace(/^\*\./, ""))
+    .filter(Boolean);
+}

package/lib/diagnose.mjs

@@ -9,23 +9,23 @@
 /**
  * Run a full diagnostic on the current page.
  * Returns performance metrics, console errors, broken images, meta tags.
+ *
+ * @param {object} protocol
+ * @param {object} [opts] {keepRuntimeEnabled} — true while browser_watch is
+ *   recording. Runtime.disable() does NOT throw when Runtime was already
+ *   enabled (it is a no-op), so the old "did it throw?" probe never detected
+ *   that case and diagnose silently killed an active watch's console feed.
  */
-export async function diagnosePage(protocol) {
-  const { Runtime, Network, Page } = protocol;
+export async function diagnosePage(protocol, opts = {}) {
+  const { Runtime } = protocol;
+  const keepRuntimeEnabled = opts.keepRuntimeEnabled === true;
 
   // Collect console errors during diagnostic
   const consoleErrors = [];
   let unsubConsole, unsubException;
-  let runtimeWasAlreadyEnabled = false;
 
   try {
-    // Check if Runtime is already enabled; if not, enable it
-    try {
-      await Runtime.enable();
-    } catch {
-      // Already enabled — that's fine, but don't disable it later
-      runtimeWasAlreadyEnabled = true;
-    }
+    await Runtime.enable();
     unsubConsole = Runtime.consoleAPICalled((params) => {
       if (params.type === "error" || params.type === "warning") {
         consoleErrors.push({
@@ -121,7 +121,7 @@ export async function diagnosePage(protocol) {
   // Cleanup
   try { if (unsubConsole) unsubConsole(); } catch {}
   try { if (unsubException) unsubException(); } catch {}
-  if (!runtimeWasAlreadyEnabled) {
+  if (!keepRuntimeEnabled) {
     try { await Runtime.disable(); } catch {}
   }
 
@@ -140,6 +140,8 @@ export async function diagnosePage(protocol) {
       hasBrokenImages: brokenImages.length > 0,
       hasConsoleErrors: consoleErrors.length > 0,
     },
+    // Heuristic, not a Lighthouse audit: a weighted penalty sum, not a
+    // measured performance grade.
     score: calculateHealthScore(performance, consoleErrors, brokenImages),
   };
 }