bwb-browser 4.0.0 → 4.0.1

package/AGENTS.md

@@ -226,6 +226,18 @@ BWB_CHROME_PATH=/path/to/chrome bwb
 bwb --browser-path /path/to/chrome
 ```
 
+### Attach Mode (drive the window you're looking at)
+```bash
+# Launch your browser with remote debugging first, e.g.:
+#   brave --remote-debugging-port=9222
+BWB_ATTACH_PORT=9222 bwb
+# or
+bwb --attach-port 9222
+```
+Guest mode: no spawn, no kill, no journal restore. `browser_newTab` opens a
+VISIBLE tab in your window. Auto-shed is disabled (those are your real tabs) —
+pressure is reported, you close them. `browser_status` shows `attached: true`.
+
 ---
 
 ## License

package/README.md

@@ -90,7 +90,7 @@ Create tabs, close them, switch between them, save cookies, load them back. Like
 
 Normalizes `navigator.webdriver`, plugins, languages, and user-agent for testing environments. Not "stealth mode" — just honest fingerprint normalization so your tests actually match real user conditions.
 
-### 7. Element Screenshots (new in 3.2.0)
+### 7. Element Screenshots
 
 Capture just one element — a login form, a chart, a product card — not the whole page:
 
@@ -105,20 +105,24 @@ Every screenshot is saved to disk (Android: `/storage/emulated/0/Download/bwb-sc
 
 ---
 
-## What's New in 3.2.0
+## What's New in 4.0.0 — "Lightweight Like Air"
 
-### New
-- **`browser_screenshot({ selector })`** — element-level capture. Grab just the login form, the chart, the product card — not the whole page.
-- **Screenshot directory auto-detect** — Termux/Android → `/storage/emulated/0/Download/bwb-screenshots/`, desktop → `~/bwb-screenshots/`. Override with `BWB_SCREENSHOTS_DIR`.
+### Static-first fetch ladder
+- **`browser_goto` no longer spawns Chromium for plain pages** — fetch + extract in milliseconds (`mode: "static"`). JS pages escalate automatically (`mode: "browser"` + reason). Dead URLs error without spawning anything.
+- **On-demand capabilities** — `browser_download` / `browser_export` ship as verbs, not weight. Missing backends prompt for consent install. Nothing heavy is ever bundled.
 
-### Bug Fixes
-- **`browser_back` rewritten** — native CDP history navigation (the `Page.goBack` call doesn't exist in bundled CDP 1.3; the old `history.back()` JS hack is gone). Verified with real two-step back navigation.
-- **`browser_act` precision fixes** — navigation regex no longer swallows compound instructions ("go to X and read the title" works), "fill X with Y" vs "type Y in X" no longer swap target/text, and `search` can't hijack "fill search with X"
-- **`killOrphanedChrome` safety** — graceful SIGTERM→SIGKILL, now scoped to bwb's own profile so it never kills another agent's browser
-- **`browser_restart` hygiene** — watch listeners can't outlive the dying protocol
-- **`browser_status` accuracy** — uses the real bound port, no more hardcoded 9222 poke
+### Vigilance system
+- **Every tool response carries a `[bwb resources]` footer** — MCP + Chromium MB, tabs, ok/watch/critical. `browser_watch` streams memory samples on its existing poll rhythm.
+- **Thresholds act, then report** — critical pressure hibernates tabs, tears down at one tab, journals everything. The agent reads about the save, never discovers the OOM.
 
-*Fixes from the PR #1 code review by @netzro (Hermes Agent) are incorporated and credited in the [changelog](./CHANGELOG.md).*
+### Survival profile
+- **`--lean` auto-enables on Termux** — capped renderers, silenced background services, 3-tab cap, 5-minute mayfly teardown, 256MB JS heap. `--nuclear` opts into `--single-process`.
+- **Tab journal + lazy restore** — kills become resume points, not disasters. `bwb --setup` prints a survival guide.
+
+### Breaking
+- `browser_title` + `browser_url` folded into `browser_status.targets`. Still 26 tools — that's now a release gate.
+
+*Full story in the [changelog](./CHANGELOG.md). Older releases documented there too.*
 
 ---
 
@@ -127,7 +131,7 @@ Every screenshot is saved to disk (Android: `/storage/emulated/0/Download/bwb-sc
 ```bash
 npm install -g bwb-browser
 bwb --version
-# → bwb-browser 3.2.0
+# → bwb-browser 4.0.0
 ```
 
 Done. If you have Chrome/Chromium anywhere on your system, bwb finds it. No config files. No environment variables. Just works.
@@ -151,12 +155,10 @@ bwb
 | **`browser_watch`** | 🔥 Live event capture — console, network, errors, navigation |
 | **`browser_diagnose`** | 🔥 Full page health check — perf, errors, broken images, score |
 | **`browser_fingerprint`** | 🔥 Realistic browser profile for testing |
-| `browser_goto` | Navigate to a URL |
+| `browser_goto` | Navigate — static-first, escalates to browser with reason |
 | `browser_screenshot` | Take a screenshot — whole page, viewport, or a single element via `selector` |
 | `browser_html` | Get page/selector HTML |
 | `browser_text` | Get page/selector text |
-| `browser_title` | Get page title |
-| `browser_url` | Get current URL |
 | `browser_back` | Go back in history |
 | `browser_click` | Click an element (native CDP) |
 | `browser_fill` | Fill an input field (native CDP) |
@@ -171,7 +173,9 @@ bwb
 | `browser_saveCookies` | Save session to disk |
 | `browser_loadCookies` | Load session from disk |
 | `browser_listSessions` | List saved sessions |
-| `browser_status` | Browser connection info |
+| `browser_download` | Download media (needs system yt-dlp, consent-gated) |
+| `browser_export` | Export md/txt/html (pdf/docx/pptx need pip libs, consent-gated) |
+| `browser_status` | Status + live resources + active profile |
 | `browser_restart` | Restart the browser |
 
 ---
@@ -212,13 +216,13 @@ See [AGENTS.md](./AGENTS.md) for copy-paste configs for each one.
 
 ## The Backstory
 
-I built this because I was tired of every browser automation tool assuming you have 400MB to spare and a desktop-class machine. I work from my phone sometimes. Termux exists. Why shouldn't browser automation work there too?
+Every browser automation tool assumes you have 400MB to spare and a desktop-class machine. That assumption excludes phones, cheap VPS boxes, Raspberry Pis, and CI runners — most of the world's computers.
 
-So I did what any reasonable person would do: I ignored all the existing solutions and wrote my own, using nothing but raw CDP — the protocol Chrome speaks natively. No wrappers. No abstractions. Just JSON messages over WebSocket.
+bwb is engineered against the hardest constraint first: **a memory-pressured device where every megabyte is contested.** No bundled browser. No wrapper frameworks. Just raw CDP — the protocol Chrome speaks natively — plus a static-fetch ladder so Chromium only starts when JavaScript demands it. Mobile-first isn't a feature here. It's the design spec everything else has to survive.
 
-The result is 76KB of source code that does what 400MB of dependencies do. It's not _better_ code — it's _less_ code. And sometimes less is all you need.
+The result is ~136KB of source that does what 400MB of dependencies do. Not better code — less code, held to budgets: 26 tools max, 60 kB tarball max, zero native modules. Constraints are features.
 
-*— Krish Tiwari ([@krshforever](https://github.com/krshforever)), somewhere on an Indian train, writing code on a phone*
+*— Krish Tiwari ([@krshforever](https://github.com/krshforever))*
 
 ---
 

package/lib/browser.mjs

@@ -35,8 +35,15 @@ 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.
 };
 
+// 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() {
@@ -119,8 +126,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: [
@@ -179,6 +189,34 @@ 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);
@@ -297,7 +335,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 +345,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 {
@@ -326,7 +366,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 {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bwb-browser",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Browser Without Bloat — lightweight MCP server that gives AI agents browser superpowers. Static-first fetch ladder (Chromium only when JS demands it), lean profiles for Termux/1GB VPS, resource vigilance, tab journaling. Runs anywhere. Stays lean like air.",
   "bin": {
     "bwb": "bin/bwb"

package/server.mjs

@@ -21,6 +21,10 @@
  *                                             (default: 5min lean, off desktop)
  *   --tab-max / BWB_TAB_MAX                 — Live-tab cap, oldest hibernated
  *                                             (default: 3 lean, unlimited desktop)
+ *   --attach-port / BWB_ATTACH_PORT         — Attach to an already-running
+ *                                             browser's CDP port (e.g. 9222)
+ *                                             instead of spawning. Guest mode:
+ *                                             never spawns, kills, or restores.
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -35,7 +39,7 @@ import { fileURLToPath } from "url";
 
 import {
   ensureBrowser, restartBrowser, stopBrowser, saveScreenshot,
-  cfg, browser, browserExited, actualCdpPort,
+  cfg, browser, browserExited, actualCdpPort, attached,
   isTermux, pokeActivity, setIdleSuppressed,
 } from "./lib/browser.mjs";
 
@@ -87,6 +91,7 @@ function parseArgs() {
       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);
     }
@@ -117,6 +122,8 @@ OPTIONS:
   --nuclear                Add --single-process (max saving, min stability)
   --idle <ms>              Mayfly teardown after N ms idle (default: 5min lean)
   --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.
   --version                Print version
   --help                   Show this help
 
@@ -198,6 +205,7 @@ async function ensureDeps() {
 
 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 || (() => {
@@ -733,9 +741,11 @@ const tools = {
     schema: {},
     handler: async () => {
       const status = { connected: false, port: cfg.port, actualPort: null, running: false, pid: null, tabs: [] };
-      if (browser && !browserExited) {
+      // Attach mode: no child process (browser === null) — liveness is the CDP link.
+      if ((browser && !browserExited) || (attached && !browserExited)) {
         status.running = true;
-        status.pid = browser.pid;
+        status.pid = browser ? browser.pid : null;
+        if (attached) status.attached = true;
         status.tabs = listTabs();
         // actualCdpPort is the real bound port; cfg.port may be 0 (random).
         // Never fall back to a hardcoded 9222 — that could be another tool's browser.
@@ -753,6 +763,7 @@ const tools = {
         status.resources = sampleResources(browser?.pid, status.tabs.filter((t) => !t.hibernated).length);
         status.resources.state = assess(status.resources);
         status.profile = { lean: cfg.lean, nuclear: cfg.nuclear, idleMs: cfg.idleMs, tabMax: cfg.tabMax };
+        if (attached) status.profile.attached = actualCdpPort || cfg.attachPort;
       } catch {}
       return { content: [{ type: "text", text: JSON.stringify(status) }] };
     },
@@ -788,7 +799,9 @@ for (const [name, tool] of Object.entries(tools)) {
       const liveTabs = listTabs().filter((t) => !t.hibernated).length;
       const sample = sampleResources(browser?.pid, liveTabs);
       let note = "";
-      if (assess(sample) === "critical" && browser && !browserExited) {
+      // Never auto-shed in attach mode: those are the user's REAL tabs.
+      // Report pressure in the footer; the human closes their own tabs.
+      if (!attached && assess(sample) === "critical" && browser && !browserExited) {
         // Evidence first: keep the peak numbers that triggered the shed.
         const peak = `${sample.mcpMb}+${sample.chromiumMb ?? "?"}MB`;
         // Shed oldest non-active tabs first; teardown at one tab. Journal keeps all.