bwb-browser 4.0.1 → 4.1.0

package/server.mjs

@@ -31,9 +31,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import CDP from "chrome-remote-interface";
-import { execSync } from "child_process";
-import { mkdirSync, readFileSync, existsSync } from "fs";
-import { homedir, platform } from "os";
+import { execFileSync } from "child_process";
+import { mkdirSync, readFileSync, writeFileSync, realpathSync, statSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 
@@ -56,16 +55,18 @@ import {
 
 import {
   getActiveProtocol, createTab, closeTab, switchTab, listTabs, syncActiveTab, clearTabs,
-  hibernateTab,
+  hibernateTab, setPendingStatic, getPendingStatic, materializeStatic, needsMaterialize,
 } from "./lib/tabs.mjs";
 
-import { staticFetch } from "./lib/fetch.mjs";
+import { staticFetch, capText } from "./lib/fetch.mjs";
 import { sampleResources, assess, resourceFooter, resolveBudgets } from "./lib/vigil.mjs";
 
 import { saveSession, loadSession, listSessions } from "./lib/session.mjs";
 import { diagnosePage } from "./lib/diagnose.mjs";
 import { applyRealisticProfile } from "./lib/fingerprint.mjs";
-import { executeInstruction } from "./lib/act.mjs";
+import { executeInstruction, redactIfSecret } from "./lib/act.mjs";
+import { parseArgs, resolveConfig, ConfigError } from "./lib/config.mjs";
+import { assertNavigable, assertHttpUrl, UrlPolicyError } from "./lib/urlpolicy.mjs";
 
 // ─── Config ───────────────────────────────────────────────────────────────────
 
@@ -76,35 +77,13 @@ const { version: BWB_VERSION } = JSON.parse(
   readFileSync(join(__dirname, 'package.json'), 'utf8')
 );
 
-function parseArgs() {
-  const args = process.argv.slice(2);
-  const cliCfg = {};
-  for (let i = 0; i < args.length; i++) {
-    switch (args[i]) {
-      case "--browser-path": cliCfg.browserPath = args[++i]; break;
-      case "--port": cliCfg.port = parseInt(args[++i], 10); break;
-      case "--user-data-dir": cliCfg.userDataDir = args[++i]; break;
-      case "--headless": cliCfg.headless = args[++i] !== "false"; break;
-      case "--screenshots-dir": cliCfg.screenshotsDir = args[++i]; break;
-      case "--timeout": cliCfg.navTimeout = parseInt(args[++i], 10); break;
-      case "--lean": cliCfg.lean = args[++i] !== "false"; break;
-      case "--nuclear": cliCfg.nuclear = args[++i] !== "false"; break;
-      case "--idle": cliCfg.idleMs = parseInt(args[++i], 10); break;
-      case "--tab-max": cliCfg.tabMax = parseInt(args[++i], 10); break;
-      case "--attach-port": cliCfg.attachPort = parseInt(args[++i], 10); break;
-      case "--version": console.log(`bwb-browser ${BWB_VERSION}`); process.exit(0);
-      case "--help": printHelp(); process.exit(0);
-    }
-  }
-  return cliCfg;
-}
-
 function printHelp() {
   console.log(`
  bwb-browser v${BWB_VERSION} — Browser Without Bloat
 
 Browser automation for AI agents. Static-first, lean like air. 26 tools.
-Raw CDP — no Playwright, no Puppeteer. Chromium starts only when JS demands it.
+CDP over one thin client — no Playwright, no Puppeteer, no bundled browser.
+Chromium starts only when JS demands it.
 
 Built on Termux/Android. Runs everywhere — including 1GB VPS boxes.
 
@@ -124,9 +103,30 @@ OPTIONS:
   --tab-max <n>            Live-tab cap, oldest hibernated (default: 3 lean)
   --attach-port <n>        Attach to a running browser's CDP port (e.g. 9222).
                            Guest mode: no spawn, no kill, visible window.
+  --readonly               Refuse every state-changing tool (browse only)
+  --allow-domains <list>   Comma-separated host allowlist for navigation
+  --always-browser         Skip the static rung; always use Chromium
+  --no-sandbox             Disable the Chromium sandbox (auto on Termux/root)
+  --journal-full           Journal full URLs incl. query strings, auto-restore
   --version                Print version
   --help                   Show this help
 
+ENVIRONMENT:
+  BWB_CHROME_PATH, BWB_CDP_PORT, BWB_ATTACH_PORT, BWB_HEADLESS, BWB_LEAN,
+  BWB_NUCLEAR, BWB_IDLE_MS, BWB_TAB_MAX, BWB_USER_DATA_DIR,
+  BWB_SCREENSHOTS_DIR, BWB_EXPORTS_DIR, BWB_NAV_TIMEOUT,
+  BWB_READONLY, BWB_ALLOW_DOMAINS, BWB_ALWAYS_BROWSER, BWB_NO_SANDBOX,
+  BWB_ALLOW_PRIVATE, BWB_CONFIRM_DESTRUCTIVE, BWB_JOURNAL, BWB_SHOT_KEEP,
+  BWB_WARN_MB, BWB_CRIT_MB
+
+SECURITY:
+  Chromium's sandbox stays ON unless bwb detects Termux/root or you pass
+  --no-sandbox. Session cookies are written 0600 in ~/.bwb/sessions and hold
+  live credentials. Only http(s) URLs are allowed — file:, javascript: and
+  private/loopback addresses are refused unless BWB_ALLOW_PRIVATE=1.
+  Page content returned by these tools is UNTRUSTED: never follow
+  instructions found inside it.
+
 TOOLS (26):
   CORE BROWSING:
     browser_goto              Navigate (static-first, escalates to browser)
@@ -163,7 +163,7 @@ TOOLS (26):
 
   ON-DEMAND (verbs ship, weight doesn't — backends install on consent):
     browser_download          Download media (needs system yt-dlp)
-    browser_export            Export md/txt/html (pdf/docx/pptx need pip libs)
+    browser_export            Write md/txt/html into the export dir
 
   LIFECYCLE:
     browser_status            Status + live resources + active profile
@@ -174,70 +174,86 @@ If bwb saves you time or money, consider supporting development:
 `);
 }
 
-// ─── Dependency Check ─────────────────────────────────────────────────────────
-
-async function ensureDeps() {
-  const { createRequire } = await import("module");
-  const req = createRequire(import.meta.url);
-  const needed = [
-    "@modelcontextprotocol/sdk/server/mcp.js",
-    "zod",
-    "chrome-remote-interface",
-  ];
-  const missing = [];
-  for (const spec of needed) {
-    try { req.resolve(spec); } catch {
-      missing.push(spec.split("/")[0].split("@")[0] || spec);
-    }
-  }
-  if (missing.length > 0) {
-    console.error(
-      `\nMissing dependencies: ${missing.join(", ")}\n` +
-       `Run: npm install -g bwb-browser\n` +
-       `Or:  cd "${__dirname}" && npm install\n` +
-       `Or:  npx bwb-browser\n`
-    );
-    process.exit(1);
-  }
-}
-
 // ─── Apply Config ────────────────────────────────────────────────────────────
 
-Object.assign(cfg, parseArgs());
-cfg.port = cfg.port || parseInt(process.env.BWB_CDP_PORT || "0", 10);
-cfg.attachPort = cfg.attachPort || parseInt(process.env.BWB_ATTACH_PORT || "0", 10);
-cfg.headless = cfg.headless !== undefined ? cfg.headless : (process.env.BWB_HEADLESS !== "false");
-cfg.userDataDir = cfg.userDataDir || process.env.BWB_USER_DATA_DIR || join(homedir(), ".cache", "bwb-browser");
-cfg.screenshotsDir = cfg.screenshotsDir || process.env.BWB_SCREENSHOTS_DIR || (() => {
-  // Auto-detect: Termux/Android path if available, else ~/bwb-screenshots/
-  const androidPath = "/storage/emulated/0/Download/bwb-screenshots";
-  if (platform() === "android" && existsSync("/storage/emulated/0/Download")) return androidPath;
-  if (process.env.HOME?.includes("com.termux")) return androidPath;
-  if (process.env.TERMUX_VERSION) return androidPath;
-  return join(homedir(), "bwb-screenshots");
-})();
-cfg.navTimeout = cfg.navTimeout || parseInt(process.env.BWB_NAV_TIMEOUT || "30000", 10);
-// v4 survival defaults: lean auto-detects Termux; mayfly + tab cap follow lean
-// unless explicitly overridden. Desktop behavior unchanged (all off).
-if (cfg.lean === null || cfg.lean === undefined) {
-  if (process.env.BWB_LEAN !== undefined) cfg.lean = process.env.BWB_LEAN !== "false";
-  else cfg.lean = isTermux();
-}
-if (cfg.nuclear === undefined || cfg.nuclear === null) {
-  cfg.nuclear = process.env.BWB_NUCLEAR === "true";
-}
-if (cfg.idleMs === null || cfg.idleMs === undefined) {
-  if (process.env.BWB_IDLE_MS !== undefined) cfg.idleMs = parseInt(process.env.BWB_IDLE_MS, 10);
-  else cfg.idleMs = cfg.lean ? 5 * 60 * 1000 : 0;
-}
-if (cfg.tabMax === null || cfg.tabMax === undefined) {
-  if (process.env.BWB_TAB_MAX !== undefined) cfg.tabMax = parseInt(process.env.BWB_TAB_MAX, 10);
-  else cfg.tabMax = cfg.lean ? 3 : 0;
+let cliCfg = {};
+try {
+  cliCfg = parseArgs(process.argv.slice(2));
+} catch (err) {
+  if (err instanceof ConfigError) {
+    console.error(`bwb: ${err.message}\nRun 'bwb --help' for usage.`);
+    process.exit(2);
+  }
+  throw err;
 }
+if (cliCfg._passthrough_version) { console.log(`bwb-browser ${BWB_VERSION}`); process.exit(0); }
+if (cliCfg._passthrough_help) { printHelp(); process.exit(0); }
+
+Object.assign(cfg, resolveConfig(cliCfg, process.env, { isTermux: isTermux() }));
 resolveBudgets(cfg.lean);
 
 try { mkdirSync(cfg.screenshotsDir, { recursive: true }); } catch {}
 
+// True once browser_loadCookies succeeds: a page that needs the session's
+// cookies must not be answered by an anonymous static fetch (F04).
+let cookiesLoaded = false;
+
+// ─── Export Path Confinement (F07) ────────────────────────────────────────────
+// browser_export used to accept any output_path: an injected page could steer
+// the agent into overwriting ~/.bashrc. Writes are now confined to one
+// directory, with an extension allowlist, symlink checks, and no silent
+// overwrite.
+
+const EXPORT_EXTS = { md: ".md", txt: ".txt", html: ".html" };
+
+function exportsDir() {
+  return process.env.BWB_EXPORTS_DIR || join(dirname(cfg.screenshotsDir), "bwb-exports");
+}
+
+/**
+ * Resolve a caller-supplied filename inside the export dir.
+ * @returns {{path: string}|{error: Error}}
+ */
+export function resolveExportPath(filename, format, overwrite = false) {
+  const dir = exportsDir();
+  const ext = EXPORT_EXTS[format];
+  if (!ext) return { error: new Error(`Unsupported export format: ${format}`) };
+
+  let base;
+  if (filename) {
+    base = filename;
+    // An absolute path or a traversal is a refusal, not something to normalize
+    // into shape: the caller is told the file name, not the path.
+    if (base.includes("/") || base.includes("\\") || base === "..") {
+      return { error: new Error(`Refusing path outside the export directory: ${filename}. Pass a plain file name.`) };
+    }
+  } else {
+    base = `bwb-export-${Date.now()}${ext}`;
+  }
+  if (!base.endsWith(ext)) base += ext;
+
+  const path = join(dir, base);
+  // Resolve symlinks on the directory too, or a symlinked export dir is a
+  // free pass out of the sandbox.
+  let realDir;
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    realDir = realpathSync(dir);
+  } catch (err) {
+    return { error: new Error(`Export directory unusable: ${err.message}`) };
+  }
+  const realPath = join(realDir, base);
+  if (!realPath.startsWith(realDir + "/")) {
+    return { error: new Error(`Refusing path outside the export directory: ${filename}`) };
+  }
+  if (!overwrite) {
+    try {
+      if (statSync(realPath)) return { error: new Error(`${base} already exists. Pass overwrite:true to replace it.`) };
+    } catch { /* does not exist — good */ }
+  }
+  return { path: realPath };
+}
+
 // ─── Watch State (Live Page Event Capture) ─────────────────────────────────────
 
 const WATCH_MAX_EVENTS = 5000;
@@ -256,33 +272,39 @@ function cleanupWatch() {
   watchState.events = [];
 }
 
+// chrome-remote-interface's event subscriptions return an UNSUBSCRIBE
+// function. The old code discarded every one of them, so cleanupWatch() removed
+// nothing: calling `start` twice doubled the events, and listeners stayed bound
+// to a tab that had been switched away from or closed.
 function setupWatch(events, cdp) {
   cleanupWatch();
   watchState.active = true;
+  const keep = (dispose) => { if (typeof dispose === "function") watchState.disposables.push(dispose); };
+  const want = (kind) => events.includes("all") || events.includes(kind);
 
-  if (events.includes("console") || events.includes("all")) {
-    cdp.Runtime.consoleAPICalled((params) => {
+  if (want("console")) {
+    keep(cdp.Runtime.consoleAPICalled((params) => {
       watchPush({ type: "console", timestamp: Date.now(), level: params.type || "log",
         text: (params.args || []).map(a => a.value !== undefined ? String(a.value) : a.description || "").join(" ") });
-    });
-    cdp.Runtime.exceptionThrown((params) => {
+    }));
+    keep(cdp.Runtime.exceptionThrown((params) => {
       const d = params.exceptionDetails;
       watchPush({ type: "exception", timestamp: Date.now(), text: d?.exception?.description || d?.text || "Unknown exception" });
-    });
+    }));
   }
-  if (events.includes("network") || events.includes("all")) {
-    cdp.Network.requestWillBeSent((params) => {
+  if (want("network")) {
+    keep(cdp.Network.requestWillBeSent((params) => {
       watchPush({ type: "network", timestamp: Date.now(), subtype: "request", url: params.request?.url || "", method: params.request?.method || "GET" });
-    });
-    cdp.Network.responseReceived((params) => {
+    }));
+    keep(cdp.Network.responseReceived((params) => {
       if (params.response?.url?.startsWith("data:")) return;
       watchPush({ type: "network", timestamp: Date.now(), subtype: "response", url: params.response?.url || "", status: params.response?.status || 0, mimeType: params.response?.mimeType || "" });
-    });
+    }));
   }
-  if (events.includes("navigation") || events.includes("all")) {
-    cdp.Page.frameNavigated((params) => {
+  if (want("navigation")) {
+    keep(cdp.Page.frameNavigated((params) => {
       watchPush({ type: "navigation", timestamp: Date.now(), url: params.frame?.url || "" });
-    });
+    }));
   }
 }
 
@@ -290,34 +312,94 @@ function setupWatch(events, cdp) {
 
 const server = new McpServer({ name: "bwb-browser", version: BWB_VERSION });
 
+/** Uniform error envelope: tools report failures as data, never as throws. */
+function errResult(err, prefix = "") {
+  const message = err instanceof Error ? err.message : String(err);
+  return { content: [{ type: "text", text: JSON.stringify({ error: prefix ? `${prefix}: ${message}` : message }) }] };
+}
+
+/** Tools that change state — disabled wholesale by --readonly / BWB_READONLY. */
+const WRITE_TOOLS = new Set([
+  "browser_click", "browser_fill", "browser_eval", "browser_act",
+  "browser_export", "browser_download", "browser_saveCookies", "browser_restart",
+  "browser_newTab", "browser_closeTab", "browser_switchTab",
+  "browser_setViewport", "browser_fingerprint", "browser_back",
+]);
+
 // Tool implementations
 const tools = {
   // ═══════════════ CORE BROWSING ═══════════════
 
   browser_goto: {
-    description: "Navigate to a URL. Returns page title and URL. v4: static-first — plain pages are fetched + extracted with zero Chromium; JS pages escalate to CDP automatically (see mode field).",
-    schema: { url: z.string().describe("URL to navigate to") },
-    handler: async ({ url }) => {
-      // Rung 1: static fetch. No browser spawned, no LMK risk, milliseconds.
-      const attempt = await staticFetch(url, { timeout: Math.min(cfg.navTimeout, 15000) });
-      if (attempt.mode === "static") {
-        syncActiveTab(attempt.title, attempt.finalUrl);
-        return { content: [{ type: "text", text: JSON.stringify({
-          mode: "static", title: attempt.title, url: attempt.finalUrl,
-          text: attempt.text, confidence: attempt.confidence,
-          note: "Served without Chromium. Need interaction/screenshots? Use browser_act / browser_screenshot — that escalates to the browser.",
-        }) }] };
+    description: "Open a URL. `mode:\"auto\"` (default) tries a plain HTTP fetch with article extraction first (fast, no browser) and falls back to Chromium for JS-rendered pages, login walls, or when cookies are loaded; `mode:\"browser\"` always uses Chromium. Returns `{mode, title, url, text, links}`. Only http(s) URLs are allowed. After a static result the next browser tool brings Chromium to that same URL automatically.",
+    schema: {
+      url: z.string().describe("URL to navigate to (http/https only)"),
+      mode: z.enum(["auto", "static", "browser"]).describe("auto (default): static first, browser on demand. static: never spawn Chromium. browser: always use Chromium.").optional(),
+      maxChars: z.number().describe("Cap on returned text (default 20000)").optional(),
+      raw: z.boolean().describe("Return the raw HTML text instead of Readability output").optional(),
+    },
+    handler: async ({ url, mode = "auto", maxChars = 20000, raw = false }) => {
+      try {
+        assertNavigable(url, { allowDomains: cfg.allowDomains || null });
+      } catch (err) {
+        return errResult(err);
       }
-      if (attempt.mode === "error") {
-        // Dead URL — CDP shares the same network, don't spawn Chromium for a 404.
-        return { content: [{ type: "text", text: JSON.stringify({ mode: "error", error: attempt.error }) }] };
+
+      // ─── Shared escalation path (F04): one navigate() for every entry point ───
+      const navigateInBrowser = async () => {
+        const cdp = await getActiveProtocol();
+        setPendingStatic(null);
+        let result;
+        try {
+          result = await gotoUrl(cdp.Page, cdp.Runtime, url, cfg.navTimeout, {
+            allowDomains: cfg.allowDomains || null,
+          });
+        } catch (err) {
+          // A failed navigation is DATA, not a protocol-level exception: the
+          // agent needs to read "ERR_NAME_NOT_RESOLVED", not a stack trace.
+          throw Object.assign(err, { isToolError: true });
+        }
+        syncActiveTab(result.title, result.url);
+        return { ...result, mode: "browser" };
+      };
+
+      // Skip the static rung when it would answer DIFFERENTLY than the browser
+      // would: cookies loaded this run, a browser already showing a real page,
+      // or the global BWB_ALWAYS_BROWSER override.
+      const browserBusy = browser && !browserExited;
+      const useStatic =
+        mode === "static" ||
+        (mode === "auto" && !cfg.alwaysBrowser && !cookiesLoaded && !browserBusy);
+
+      if (useStatic) {
+        const attempt = await staticFetch(url, {
+          timeout: Math.min(cfg.navTimeout, 15000),
+          allowPrivate: cfg.allowPrivate,
+          allowDomains: cfg.allowDomains?.length ? cfg.allowDomains : null,
+          maxChars,
+          raw,
+        });
+        if (attempt.mode === "static") {
+          // Record it: the first tool that needs Chromium navigates there.
+          setPendingStatic(attempt.finalUrl || url, attempt.title);
+          return { content: [{ type: "text", text: JSON.stringify({
+            mode: "static", title: attempt.title, url: attempt.finalUrl,
+            text: attempt.text, links: attempt.links || [], confidence: attempt.confidence,
+            ...(attempt.truncated ? { truncated: true, nextOffset: attempt.nextOffset } : {}),
+            note: "Served without Chromium. Interaction or screenshots start the browser on this same URL.",
+          }) }] };
+        }
+        if (attempt.mode === "error") {
+          // Dead URL — CDP shares the same network, don't spawn Chromium for a 404.
+          return { content: [{ type: "text", text: JSON.stringify({ mode: "error", error: attempt.error }) }] };
+        }
+        // Rung 2: escalate (JS shell, auth wall, non-text content).
+        const result = await navigateInBrowser();
+        return { content: [{ type: "text", text: JSON.stringify({ ...result, escalated: attempt.reason }) }] };
       }
-      // Rung 2: escalate to Chromium (JS shell, auth wall, non-text).
-      const cdp = await getActiveProtocol();
-      const { Page, Runtime } = cdp;
-      const result = await gotoUrl(Page, Runtime, url, cfg.navTimeout);
-      syncActiveTab(result.title, result.url);
-      return { content: [{ type: "text", text: JSON.stringify({ ...result, mode: "browser", escalated: attempt.reason }) }] };
+
+      const result = await navigateInBrowser();
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
     },
   },
 
@@ -368,28 +450,43 @@ const tools = {
   },
 
   browser_html: {
-    description: "Get HTML source of the page or a CSS selector.",
-    schema: { selector: z.string().describe("Optional CSS selector").optional() },
-    handler: async ({ selector }) => {
+    description: "Return the page HTML (or the outerHTML of the first element matching a CSS selector). Capped at `maxChars` (default 200000). Use browser_text for human-readable text, browser_elements for a clickable list.",
+    schema: {
+      selector: z.string().describe("Optional CSS selector").optional(),
+      maxChars: z.number().describe("Cap on returned HTML (default 200000)").optional(),
+    },
+    handler: async ({ selector, maxChars = 200000 }) => {
       const { Runtime } = await getActiveProtocol();
       const expr = selector
         ? `document.querySelector(${JSON.stringify(selector)})?.outerHTML || ''`
         : "document.documentElement.outerHTML";
       const { result } = await Runtime.evaluate({ expression: expr });
-      return { content: [{ type: "text", text: result?.value || "" }] };
+      const html = result?.value || "";
+      return { content: [{ type: "text", text: capText(html, maxChars).text }] };
     },
   },
 
   browser_text: {
-    description: "Get visible text content of the page or a CSS selector.",
-    schema: { selector: z.string().describe("Optional CSS selector").optional() },
-    handler: async ({ selector }) => {
+    description: "Return the visible text (`innerText`) of the page or of the first element matching a CSS selector — no script/style bodies, no hidden nodes. Capped at `maxChars` (default 20000; `truncated:true` when cut).",
+    schema: {
+      selector: z.string().describe("Optional CSS selector").optional(),
+      maxChars: z.number().describe("Cap on returned text (default 20000)").optional(),
+    },
+    handler: async ({ selector, maxChars = 20000 }) => {
       const { Runtime } = await getActiveProtocol();
+      // innerText, not textContent: textContent includes <script>/<style>
+      // bodies and display:none subtrees, which is not "visible text".
       const expr = selector
-        ? `document.querySelector(${JSON.stringify(selector)})?.textContent || ''`
-        : "document.body?.textContent || ''";
+        ? `(document.querySelector(${JSON.stringify(selector)})?.innerText ?? '')`
+        : `(document.body?.innerText ?? document.body?.textContent ?? '')`;
       const { result } = await Runtime.evaluate({ expression: expr });
-      return { content: [{ type: "text", text: result?.value || "" }] };
+      const text = result?.value || "";
+      const capped = capText(text, maxChars);
+      return {
+        content: [{ type: "text", text: JSON.stringify(capped.truncated
+          ? { text: capped.text, truncated: true, nextOffset: capped.nextOffset }
+          : { text: capped.text }) }],
+      };
     },
   },
 
@@ -418,24 +515,35 @@ const tools = {
   // ═══════════════ INTERACTION ═══════════════
 
   browser_click: {
-    description: "Click an element by CSS selector. Uses CDP Input.dispatchMouseEvent for native events.",
+    description: "Click an element by CSS selector with native CDP mouse events. Scrolls it into view and hit-tests the click point first; the result reports `hit` (whether the point really was that element) and `landedOn` (what was actually there).",
     schema: { selector: z.string().describe("CSS selector") },
     handler: async ({ selector }) => {
       const cdp = await getActiveProtocol();
       const { Page, Runtime, Input } = cdp;
       const info = await clickElement(Page, Runtime, Input, selector);
-      return { content: [{ type: "text", text: JSON.stringify({ clicked: selector, tag: info.tag, text: info.text }) }] };
+      return { content: [{ type: "text", text: JSON.stringify({
+        clicked: selector, tag: info.tag, text: info.text,
+        hit: info.hit, landedOn: info.landedOn,
+        ...(info.hit === false ? { warning: "The click point was covered or off-screen — the click may have missed." } : {}),
+      }) }] };
     },
   },
 
   browser_fill: {
-    description: "Clear and fill an input field with text using native CDP Input.insertText.",
+    description: "Clear an input field and fill it with text using native CDP Input.insertText (fires the page's own input events). Existing content is selected first, so the field is replaced, not appended to. Returns the length only — never the text — when the target is a password field or looks like a secret.",
     schema: { selector: z.string().describe("CSS selector for input"), text: z.string().describe("Text to fill") },
     handler: async ({ selector, text }) => {
       const cdp = await getActiveProtocol();
       const { Page, Runtime, Input } = cdp;
-      await fillElement(Page, Runtime, Input, selector, text);
-      return { content: [{ type: "text", text: JSON.stringify({ filled: selector, text }) }] };
+      const info = await fillElement(Page, Runtime, Input, selector, text);
+      // Redact on what the FIELD is, not only what the selector is called:
+      // `#pw` is a password field just as much as `#password` is.
+      const secretField = info.type === "password" ||
+        /pass|secret|token|otp|pin|cvv|card/i.test(selector);
+      const echo = secretField
+        ? { length: [...String(text)].length, redacted: true }
+        : redactIfSecret(selector, text);
+      return { content: [{ type: "text", text: JSON.stringify({ filled: selector, ...echo }) }] };
     },
   },
 
@@ -462,28 +570,46 @@ const tools = {
   },
 
   browser_eval: {
-    description: "Execute JavaScript in the page context.",
-    schema: { expression: z.string().describe("JavaScript expression") },
-    handler: async ({ expression }) => {
+    description: "Run a JavaScript expression in the active page and return its JSON-serializable result. Promises are awaited (`timeout` ms, default 10000). Runs with the page's privileges, including any logged-in session: only run code you wrote or understand.",
+    schema: {
+      expression: z.string().describe("JavaScript expression"),
+      timeout: z.number().describe("Max ms to await a promise (default 10000)").optional(),
+    },
+    handler: async ({ expression, timeout = 10000 }) => {
       const { Runtime } = await getActiveProtocol();
-      const response = await Runtime.evaluate({ expression, returnByValue: true });
+      const response = await Runtime.evaluate({
+        expression,
+        returnByValue: true,
+        // Without awaitPromise, `await fetch(...)` and async IIFEs resolve to
+        // {} — the single most common reason an agent thinks its script "did
+        // nothing".
+        awaitPromise: true,
+        timeout,
+      });
       if (response.exceptionDetails) {
         const exc = response.exceptionDetails;
         throw new Error(`JS Error: ${exc.exception?.description || exc.text || "Unknown JS error"}`);
       }
       const { result } = response;
-      return { content: [{ type: "text", text: JSON.stringify(result?.value ?? result) }] };
+      let value = result?.value;
+      if (value === undefined && result?.description) value = result.description;
+      return { content: [{ type: "text", text: JSON.stringify(value ?? null) }] };
     },
   },
 
   browser_setViewport: {
-    description: "Change the viewport size (width × height). Useful for responsive testing.",
+    description: "Change the viewport size (width × height) for responsive testing. Defaults to 1280×720. Pass `reset:true` to clear the override.",
     schema: {
-      width: z.number().min(320).max(7680).describe("Viewport width in pixels (default: 1280)"),
-      height: z.number().min(240).max(4320).describe("Viewport height in pixels (default: 720)"),
+      width: z.number().min(320).max(7680).describe("Viewport width in pixels (default 1280)").optional(),
+      height: z.number().min(240).max(4320).describe("Viewport height in pixels (default 720)").optional(),
+      reset: z.boolean().describe("Clear the override and return to the window size").optional(),
     },
-    handler: async ({ width = 1280, height = 720 }) => {
+    handler: async ({ width = 1280, height = 720, reset = false }) => {
       const { Emulation } = await getActiveProtocol();
+      if (reset) {
+        await Emulation.clearDeviceMetricsOverride();
+        return { content: [{ type: "text", text: JSON.stringify({ viewport: "reset" }) }] };
+      }
       await Emulation.setDeviceMetricsOverride({ width, height, deviceScaleFactor: 1, mobile: false });
       return { content: [{ type: "text", text: JSON.stringify({ viewport: `${width}x${height}` }) }] };
     },
@@ -492,18 +618,34 @@ const tools = {
   // ═══════════════ 🔥 ADVANCED ═══════════════
 
   browser_act: {
-    description: "GROUNDBREAKING: Natural language page interaction. One tool call does what normally takes 5-10. Examples: 'search for laptops under $1000', 'click the login button', 'go to google.com', 'fill email with test@test.com', 'extract the prices', 'scroll down'. Uses rule-based DOM heuristics — no LLM dependency.",
-    schema: { instruction: z.string().describe("Natural language instruction for what to do on the page") },
-    handler: async ({ instruction }) => {
+    description: "Perform one simple action on the current page from a plain-English instruction: `go to <url>`, `search for <text>`, `click <label>`, `fill <field> with <value>`, `type <text> in <field>`, `scroll down|up`, `extract <text>`, `what's on this page`. Matching is literal text/label based (no LLM): if several elements match it returns `candidates` instead of guessing, and clicks on destructive labels (delete/buy/pay/submit…) return `needs_confirmation` unless `force:true`. Returns `{action, ...}` or `{action:\"<name>_error\", error}`. For anything precise use browser_click, browser_fill, browser_elements or browser_eval with a CSS selector.",
+    schema: {
+      instruction: z.string().describe("Natural language instruction for what to do on the page"),
+      force: z.boolean().describe("Click even when the matched label looks destructive").optional(),
+    },
+    handler: async ({ instruction, force = false }) => {
       const cdp = await getActiveProtocol();
-      const result = await executeInstruction(cdp, instruction);
+      const result = await executeInstruction(cdp, instruction, {
+        confirmDestructive: cfg.confirmDestructive,
+        force,
+        // Navigation goes through the same ladder-aware path as browser_goto,
+        // so an act navigation leaves the browser on the page it claims.
+        navigate: async (url) => {
+          try { assertNavigable(url, { allowDomains: cfg.allowDomains || null }); }
+          catch (err) { throw err; }
+          const res = await gotoUrl(cdp.Page, cdp.Runtime, url, cfg.navTimeout, {
+            allowDomains: cfg.allowDomains || null,
+          });
+          return { url: res.url, timedOut: res.timedOut };
+        },
+      });
       if (result.url) syncActiveTab(result.title, result.url);
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     },
   },
 
   browser_watch: {
-    description: "GROUNDBREAKING: Live capture of page events (console, network, navigation, exceptions). Start recording, browse around, then poll to see everything that happened.",
+    description: "Record page events from the active tab. `start` begins capturing console messages, exceptions, network requests/responses and navigations (`events`: console, network, navigation, all). `poll` returns and clears events since the last poll, plus memory readings. `stop` ends capture and returns what remains. Keeps the newest 5,000 events. Bound to the tab that was active at `start` — switching tabs or restarting the browser stops the capture.",
     schema: {
       action: z.enum(["start", "poll", "stop"]).describe("start=begin recording, poll=get events since last poll, stop=cleanup"),
       events: z.array(z.enum(["console", "network", "navigation", "all"])).describe("Event types to capture (default: all)").optional(),
@@ -513,6 +655,9 @@ const tools = {
         const cdp = await getActiveProtocol();
         await cdp.Runtime.enable();
         await cdp.Network.enable();
+        // frameNavigated is only delivered after Page.enable — the old code
+        // subscribed without it and silently captured no navigation events.
+        await cdp.Page.enable?.();
         setupWatch(events, cdp);
         setIdleSuppressed(true); // recording in progress — mayfly must not teardown
         return { content: [{ type: "text", text: JSON.stringify({ status: "watching", events, msg: "Recording started. Poll to get events." }) }] };
@@ -536,17 +681,17 @@ const tools = {
   },
 
   browser_diagnose: {
-    description: "Full page health diagnostic. Returns performance metrics, console errors, broken images, meta tags, and a health score. Like Lighthouse for your agent.",
+    description: "Page health check for the active page: load timings, console errors, broken images, meta tags, interaction counts, and a heuristic score (0-100, weighted penalty sum — not a Lighthouse audit). Safe to call while browser_watch is recording.",
     schema: {},
     handler: async () => {
       const cdp = await getActiveProtocol();
-      const report = await diagnosePage(cdp);
+      const report = await diagnosePage(cdp, { keepRuntimeEnabled: watchState.active });
       return { content: [{ type: "text", text: JSON.stringify(report) }] };
     },
   },
 
   browser_fingerprint: {
-    description: "Apply a realistic browser fingerprint to reduce false-positive automation detection in CI/testing. Normalizes navigator.webdriver, plugins, languages, chrome.runtime, and user-agent for more realistic test conditions.",
+    description: "Apply common anti-detection patches (hide the webdriver flag, plausible plugins/languages, a user agent derived from the real Chromium build) to pages loaded afterwards. Intended for testing sites you own or have permission to test. Call before browser_goto.",
     schema: {},
     handler: async () => {
       const cdp = await getActiveProtocol();
@@ -611,22 +756,28 @@ const tools = {
   // ═══════════════ SESSION ═══════════════
 
   browser_saveCookies: {
-    description: "Save the current browser session (cookies) to disk. 'Login once, agent works for days.' Sessions persist across agent and server restarts.",
-    schema: { name: z.string().describe("Name for this session (e.g., 'twitter-login', 'gmail')") },
-    handler: async ({ name }) => {
+    description: "Save cookies for this browser profile as a JSON file in ~/.bwb/sessions (permissions 600). The file contains live login credentials: treat it like a password. Pass `domains` to save only some sites. After loading, navigate to the target site for cookies to apply.",
+    schema: {
+      name: z.string().describe("Name for this session (e.g., 'gmail')"),
+      domains: z.array(z.string()).describe("Only save cookies for these domains (optional; default: all)").optional(),
+    },
+    handler: async ({ name, domains }) => {
       const cdp = await getActiveProtocol();
-      const result = await saveSession(name, cdp);
+      const result = await saveSession(name, cdp, { domains });
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     },
   },
 
   browser_loadCookies: {
-    description: "Load a saved browser session (cookies) from disk. Navigate to the target domain after loading for the cookies to take effect.",
-    schema: { name: z.string().describe("Session name to load (e.g., 'twitter-login')") },
+    description: "Load a saved session (cookies) from disk. Only http(s) pages requested after this call will use them — static fetches are skipped for the rest of the run, so a logged-in page is never answered anonymously.",
+    schema: { name: z.string().describe("Session name to load (e.g., 'gmail')") },
     handler: async ({ name }) => {
       const cdp = await getActiveProtocol();
       const result = await loadSession(name, cdp);
-      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      // From here on the static rung would answer with a logged-OUT page and
+      // report high confidence. Force the browser rung.
+      cookiesLoaded = true;
+      return { content: [{ type: "text", text: JSON.stringify({ ...result, staticFetchDisabled: true }) }] };
     },
   },
 
@@ -644,20 +795,26 @@ const tools = {
   // bundled — probed at call time, installed only on explicit user consent.
 
   browser_download: {
-    description: "Download media from a URL (video, audio, subtitles, thumbnail). Requires yt-dlp on the system — if missing, returns install instructions instead of failing silently. No silent installs, ever.",
+    description: "Download media from a URL (video, audio, subtitles, thumbnail). Requires yt-dlp on the system — if missing, returns install instructions and downloads nothing. http(s) only; the URL is passed to yt-dlp as an argument, never through a shell.",
     schema: {
-      url: z.string().describe("Media URL"),
+      url: z.string().describe("Media URL (http/https)"),
       format: z.enum(["best", "audio", "video", "subtitles", "thumbnail"]).describe("What to download").optional(),
       quality: z.enum(["best", "good", "worst"]).describe("Quality tier").optional(),
     },
     handler: async ({ url, format = "best", quality = "best" }) => {
-      // No shell metachars ever reach execSync — http(s) only.
-      if (!/^https?:\/\/[^\\s"';`$(){}|&<>]+$/i.test(url)) {
-        return { content: [{ type: "text", text: JSON.stringify({ error: "refused: URL must be http(s) without shell metacharacters" }) }] };
+      // Real URL parsing instead of a regex. The old regex had `\\s` inside a
+      // character class — a literal backslash AND the letter "s" — so every URL
+      // containing an "s" was refused (x.com/user/status/1, instagram, tiktok)
+      // while "https://example.com/a b" was accepted.
+      let target;
+      try {
+        target = assertHttpUrl(url, { allowDomains: cfg.allowDomains || null });
+      } catch (err) {
+        return errResult(err, "refused: only http(s) URLs without shell metacharacters are allowed");
       }
       let hasYtDlp = false;
       try {
-        execSync("yt-dlp --version", { stdio: "ignore", timeout: 5000 });
+        execFileSync("yt-dlp", ["--version"], { stdio: "ignore", timeout: 5000 });
         hasYtDlp = true;
       } catch {}
       if (!hasYtDlp) {
@@ -680,9 +837,11 @@ const tools = {
       else if (format === "thumbnail") args.push("--write-thumbnail", "--skip-download");
       if (quality === "worst") args.push("-f", "worst");
       else if (quality === "good") args.push("-f", "best[height<=720]");
-      args.push(url);
+      // `--` ends option parsing so a URL can never be read as a yt-dlp flag.
+      args.push("--", target.href);
       try {
-        const out = execSync(`yt-dlp ${args.map((a) => `"${a}"`).join(" ")}`, { encoding: "utf8", timeout: 600000, maxBuffer: 1024 * 1024 });
+        // execFile, not execSync: no shell is constructed at any point.
+        const out = execFileSync("yt-dlp", args, { encoding: "utf8", timeout: 600000, maxBuffer: 1024 * 1024 });
         const file = out.trim().split("\n").pop();
         return { content: [{ type: "text", text: JSON.stringify({ downloaded: file, format, quality }) }] };
       } catch (err) {
@@ -692,45 +851,26 @@ const tools = {
   },
 
   browser_export: {
-    description: "Export findings/text to a file. md/txt/html always work (zero deps). docx/pdf/pptx need python libs — if missing, returns install instructions. No silent installs.",
+    description: "Write text to a file inside the bwb export directory (default ~/bwb-exports). Formats: md, txt, html. Paths outside the export directory are refused. No pdf/docx/pptx: those were reported as \"ready\" while writing nothing.",
     schema: {
       text: z.string().describe("Content to export (markdown accepted)"),
-      format: z.enum(["md", "txt", "html", "pdf", "docx", "pptx"]).describe("Output format").optional(),
-      output_path: z.string().describe("Where to write the file").optional(),
-      title: z.string().describe("Document title").optional(),
-    },
-    handler: async ({ text, format = "md", output_path, title = "bwb export" }) => {
-      const { writeFileSync: wfs } = await import("fs");
-      const dest = output_path || join(dirname(cfg.screenshotsDir), `bwb-export-${Date.now()}.${format === "txt" ? "txt" : format === "html" ? "html" : "md"}`);
-      if (["md", "txt"].includes(format)) {
-        try { wfs(dest, text, "utf8"); } catch (err) {
-          return { content: [{ type: "text", text: JSON.stringify({ error: `write failed: ${err.message}` }) }] };
-        }
-        return { content: [{ type: "text", text: JSON.stringify({ exported: dest, format }) }] };
-      }
+      format: z.enum(["md", "txt", "html"]).describe("Output format").optional(),
+      filename: z.string().describe("File name inside the export dir (optional; extension from format)").optional(),
+      title: z.string().describe("Document title (html only)").optional(),
+      overwrite: z.boolean().describe("Allow replacing an existing file").optional(),
+    },
+    handler: async ({ text, format = "md", filename, title = "bwb export", overwrite = false }) => {
+      const dest = resolveExportPath(filename, format, overwrite);
+      if (dest.error) return errResult(dest.error);
       if (format === "html") {
         const esc = text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-        try { wfs(dest, `<!doctype html><html><head><meta charset="utf8"><title>${title}</title></head><body><pre>${esc}</pre></body></html>`, "utf8"); } catch (err) {
-          return { content: [{ type: "text", text: JSON.stringify({ error: `write failed: ${err.message}` }) }] };
-        }
-        return { content: [{ type: "text", text: JSON.stringify({ exported: dest, format }) }] };
-      }
-      // pdf/docx/pptx need python libs — probe, then consent-gate.
-      const need = { pdf: "reportlab", docx: "python-docx", pptx: "python-pptx" }[format];
-      let have = false;
-      try {
-        execSync(`python3 -c "import ${need.split("-").join("_")}"`, { stdio: "ignore", timeout: 10000 });
-        have = true;
-      } catch {}
-      if (!have) {
-        return { content: [{ type: "text", text: JSON.stringify({
-          needsInstall: true,
-          tool: need,
-          install: `pip install ${need}`,
-          ask: `${need} is not installed. Reply YES (agent: ask the human) to install it, or install manually and retry. Nothing was written. md/txt/html export works without it.`,
-        }) }] };
+        writeFileSync(dest.path,
+          `<!doctype html><html><head><meta charset="utf8"><title>${title}</title></head><body><pre>${esc}</pre></body></html>`,
+          "utf8");
+      } else {
+        writeFileSync(dest.path, text, "utf8");
       }
-      return { content: [{ type: "text", text: JSON.stringify({ ready: true, tool: need, note: "Backend present. Tell the agent to run the conversion explicitly — bwb never executes installs itself." }) }] };
+      return { content: [{ type: "text", text: JSON.stringify({ exported: dest.path, format }) }] };
     },
   },
 
@@ -770,28 +910,82 @@ const tools = {
   },
 
   browser_restart: {
-    description: "Cleanly restart the browser process. Useful for freeing memory, clearing state, or recovering from issues during long-running sessions.",
+    description: "Cleanly restart the browser process, then resume the page you were on. Use it to free memory, clear state, or recover from a wedged session. Cookies in the profile survive; in-page state does not.",
     schema: {},
     handler: async () => {
+      // An explicit restart is the agent asking for a fresh browser mid-task,
+      // not permission to forget which page the task was on. Re-queue the
+      // current URL so the next page tool lands back on it.
+      const active = listTabs().find((t) => t.active);
+      const resume = /^https?:/i.test(active?.url || "") ? active.url : null;
       clearTabs(); // Kill stale tab connections before restart
       cleanupWatch(); // Detach event listeners from the dying protocol before it's gone
       const result = await restartBrowser();
-      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      if (resume) setPendingStatic(resume, active.title);
+      return { content: [{ type: "text", text: JSON.stringify({ ...result, resuming: resume }) }] };
     },
   },
 };
 
 // ─── Register & Start ─────────────────────────────────────────────────────────
 
-// Single choke point for every tool call: poke the mayfly timer, then append
-// a ~100-byte resource footer. On critical pressure, shed load BEFORE
-// returning — hibernate oldest tabs, teardown at one tab — and say so.
+// Tools that operate on a live page. browser_goto and the static tools are
+// excluded: they must work without ever starting Chromium.
+const PAGE_TOOLS = new Set([
+  "browser_text", "browser_html", "browser_screenshot", "browser_click",
+  "browser_fill", "browser_elements", "browser_eval", "browser_back",
+  "browser_waitForSelector", "browser_diagnose", "browser_fingerprint",
+  "browser_loadCookies", "browser_saveCookies",
+]);
+
+// Single choke point for every tool call:
+//   1. --readonly blocks state-changing tools before they run
+//   2. materialize a pending static page so "static first" is actually true
+//   3. poke the mayfly timer
+//   4. append a ~100-byte resource footer, shedding load on critical pressure
+let criticalStreak = 0;
+
 for (const [name, tool] of Object.entries(tools)) {
   const inner = tool.handler;
   server.tool(name, tool.description, tool.schema, async (args) => {
+    if (cfg.readonly && WRITE_TOOLS.has(name)) {
+      return { content: [
+        { type: "text", text: JSON.stringify({
+          error: `bwb is running in --readonly mode: ${name} is disabled. Restart without --readonly (or BWB_READONLY) to allow state changes.`,
+        }) },
+        { type: "text", text: resourceFooter(sampleResources(null, 0), "readonly") },
+      ] };
+    }
+
+    // Static-first only pays off if the browser catches up when it matters.
+    // Before any tool that needs a live page, navigate Chromium to whatever
+    // browser_goto served statically (F04).
+    if (PAGE_TOOLS.has(name) && needsMaterialize()) {
+      try {
+        await materializeStatic();
+      } catch (err) {
+        return { content: [{ type: "text", text: JSON.stringify({
+          error: `Could not load the statically fetched page in the browser: ${err.message}`,
+        }) }] };
+      }
+    }
+    // A watch is bound to one tab: switching tabs or restarting invalidates it.
+    if (watchState.active && (name === "browser_switchTab" || name === "browser_closeTab")) {
+      cleanupWatch();
+      setIdleSuppressed(false);
+    }
+
     let result;
     try {
       result = await inner(args);
+    } catch (err) {
+      // Tools report failure as data. An exception here would arrive at the
+      // agent as a protocol error with no structured detail.
+      if (err?.isToolError || err?.name === "UrlPolicyError") {
+        result = errResult(err);
+      } else {
+        throw err;
+      }
     } finally {
       try { pokeActivity(); } catch {}
     }
@@ -813,10 +1007,24 @@ for (const [name, tool] of Object.entries(tools)) {
           Object.assign(sample, after);
           if (assess(sample) !== "critical") break;
         }
-        if (assess(sample) === "critical" && listTabs().filter((t) => !t.hibernated).length <= 1) {
+        // Teardown throws away in-page state (a half-filled form, scroll
+        // position, a page's JS heap) and the next call resurrects from the
+        // journal. Only do it when the pressure is not a one-off sample AND
+        // no multi-step flow is in flight.
+        criticalStreak++;
+        const flowInProgress = watchState.active;
+        if (assess(sample) === "critical"
+            && listTabs().filter((t) => !t.hibernated).length <= 1
+            && criticalStreak >= 2
+            && !flowInProgress) {
           try { await stopBrowser("oom-guard"); } catch {}
-          note += `${note ? "; " : ""}browser stopped at peak ${peak} (oom-guard) — journal saved, next call resurrects`;
+          criticalStreak = 0;
+          note += `${note ? "; " : ""}browser stopped at peak ${peak} (oom-guard, twice) — journal saved, next call resurrects`;
+        } else if (flowInProgress) {
+          note += `${note ? "; " : ""}oom-guard held: browser_watch is recording`;
         }
+      } else {
+        criticalStreak = 0;
       }
       if (result && Array.isArray(result.content)) {
         result.content.push({ type: "text", text: resourceFooter(sample, note) });
@@ -826,6 +1034,5 @@ for (const [name, tool] of Object.entries(tools)) {
   });
 }
 
-await ensureDeps();
 const transport = new StdioServerTransport();
 await server.connect(transport);