barebrowse 0.21.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,37 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.22.0] - 2026-10-14
4
+
5
+ ### Added
6
+
7
+ - **The MCP server releases its browser after an idle TTL.** A session left
8
+ open kept a Chromium/Firefox process and profile dir alive indefinitely.
9
+ `BAREBROWSE_IDLE_MINUTES` (default 15, `0` = off; blank or invalid falls back
10
+ to the default, values are capped at `setTimeout`'s maximum) closes the
11
+ browser once no tool call has arrived for that long. The timer pauses while a
12
+ call is in flight, so a long-running call is never cut off, and the next call
13
+ simply opens a fresh browser.
14
+
15
+ ### Fixed
16
+
17
+ - **MCP transient-error resets no longer orphan the running browser.** Five reset
18
+ sites set the page to `null` without closing it, so the next call launched a
19
+ second browser while the first kept running. They now go through
20
+ `resetPage()`, which closes the browser before forgetting it.
21
+ - **`close()` always runs hard cleanup, even when the browser is dead or hung.**
22
+ The polite tab close had no timeout and ran before cleanup, so a killed or
23
+ unresponsive browser leaked its process and temp profile dir. The polite close
24
+ is now bounded and cleanup runs in a `finally`, on both engines.
25
+ - **An ordinary `wait_for` timeout no longer resets the page.** The MCP retry
26
+ layer treated any "timed out" error as transient, which also matched
27
+ `waitFor`'s own not-found message, so a missed wait tore down the browser.
28
+ That message is now excluded.
29
+ - **`wait_for` with `timeout` of 60s or more is no longer cut off at 60s.** The
30
+ retry layer's fixed 60s outer deadline fired first and was treated as
31
+ transient, resetting the page and browser. The outer deadline is now
32
+ `max(60s, requested timeout + 5s)`.
33
+ - **The publish workflow now fails when `package-lock.json`'s version drifts from `package.json`.** npm writes that field on install, so a release that bumps `package.json` without running one leaves it behind — and nothing caught it: `npm ci` fails when the lockfile's *dependency* entries disagree, but never checks the lockfile's copy of the project's own version. `scripts/check-lockfile.mjs` (`npm run check:lockfile`) compares both places npm writes it and runs in the publish workflow. No lockfile is not a failure.
34
+
3
35
  ## [0.21.0] - 2026-09-17
4
36
 
5
37
  ### Added
package/README.md CHANGED
@@ -98,6 +98,8 @@ Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`
98
98
 
99
99
  MCP tools: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`, `capabilities` (reports the active engine — chromium or firefox — and what the session can do; no side effects). Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
100
100
 
101
+ **Idle release.** An MCP server can outlive its conversation, so it closes its browser after `BAREBROWSE_IDLE_MINUTES` (default `15`, `0` = never, blank/invalid = default, fractional allowed, capped at ~24.8 days) with no tool call in flight. The next call opens a fresh browser (a new job, not a resume — a page left open, e.g. a solved captcha in the headed window, is gone). A transient browser error also closes the broken browser rather than orphaning it; an ordinary `wait_for` timeout does not reset the page.
102
+
101
103
  `browse` and `snapshot` accept `pruneMode: 'act'|'read'`. `act` (default) keeps interactive elements — best for clicking/filling. `read` keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If act-mode collapses a content-heavy page near-totally, the snapshot includes a `hint: …` line suggesting `pruneMode='read'` so the agent doesn't bail to a separate HTTP fetch.
102
104
 
103
105
  `npx barebrowse doctor` reports the runtime environment first — default engine/mode, installed Chromium/Firefox binaries, cookie sources, and any live session's engine + capabilities — then scans every known MCP config location and flags scope conflicts. `npx barebrowse install --force` overwrites an existing entry pointing at a different endpoint.
@@ -96,7 +96,7 @@ const snapshot = await browse('https://example.com', {
96
96
  | `createTab()` | -- | tab handle | New tab in same browser. Returns `{ goto, botBlocked, injectCookies, waitForNetworkIdle, cdp, close }`. Tab close doesn't affect session. |
97
97
  | `engine` | -- | `'chromium'`\|`'firefox'` | Which engine drives this session. Always readable (both shapes carry it); a typed literal, so it also narrows the union: `if (page.engine === 'firefox') page.bidi.…`. |
98
98
  | `capabilities` | -- | object | Feature introspection: `{ engine, mode, attach, escapeHatch, reloadIgnoreCache, downloads, stealth, cookieInjection }`. Ask "what can this session do?" without probing for `cdp`/`bidi`. All fields are launch-fixed except `stealth`, which is a live getter reflecting the session's current headed/headless state (it can flip mid-session after a hybrid bot-challenge relaunch). `reloadIgnoreCache` is false on Firefox (upstream BiDi gap); `downloads`/`stealth`/`cookieInjection` reflect mode + attach + incognito. |
99
- | `close()` | -- | void | Close page, disconnect CDP, kill browser (if headless) |
99
+ | `close()` | -- | void | Close page, disconnect CDP, kill browser (if headless). The tab close is bounded (2.5s), so a dead/hung browser still gets killed and its profile + owned download dir removed. Attach mode never kills your browser |
100
100
 
101
101
  **connect() options** (in addition to mode/port/consent):
102
102
  - `engine: 'chromium'|'firefox'` — Browser engine. Default `chromium` (CDP). When you don't pass `engine`, `connect()` prefers Chromium but **falls back to Firefox** (with a one-line `console.warn` to stderr) if no Chromium browser is installed; if neither engine is installed it throws naming both. An **explicit** `engine` is always honored — it errors if that engine's binary is missing rather than silently switching. Attach mode (`port`) is Chromium/CDP-only and never falls back. `firefox` drives Firefox over WebDriver BiDi (CDP is deprecated there) — a separate transport with the same `page.*` API; the ARIA snapshot is reconstructed in-page since BiDi has no `getFullAXTree`. Consent auto-dismiss and stealth (headless anti-detection) work on Firefox as of v0.16.0; the CLI daemon's console/network capture and `waitForNetworkIdle` work as of v0.17.0; ad/tracker blocking (`blockAds`/`blockUrls`) and JS dialog handling (`dialogLog`/`onDialog`) work as of Phase 3; `hybrid` mode, `saveState`, `waitForNavigation`, and download tracking (`page.downloads`) work as of Phase 4. The only remaining Firefox gap is `reload()` ignoring `ignoreCache` (upstream BiDi limitation).
@@ -295,6 +295,8 @@ barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or an
295
295
 
296
296
  19 core tools: `browse` (one-shot), `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. Plus `assess` (privacy scan) if `wearehere` is installed (`npm install wearehere`). Plus the **opt-in `eval` tool** gated by `BAREBROWSE_MCP_EVAL=1` (default OFF) — `Runtime.evaluate` in the user's authenticated session can read cookies/localStorage and hit any same-origin endpoint, so opt-in only.
297
297
 
298
+ **Idle release:** the MCP server closes its browser after `BAREBROWSE_IDLE_MINUTES` of no tool calls (default `15`; `0` = off; blank/invalid = default; capped at ~24.8 days; calls in flight postpone it). The next call opens a fresh browser — page state (open tabs, a solved captcha) is not resumed. Transient browser errors close the broken browser instead of orphaning it; a `wait_for` that merely times out keeps the page (its outer deadline is `max(60s, timeout+5s)`).
299
+
298
300
  Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe. This avoids double-token output since MCP tool calls are cheap to chain.
299
301
 
300
302
  `browse`, `snapshot`, and `readable` accept a `maxChars` param (default 30000). If the output exceeds the limit it's saved to `.barebrowse/` and a short message with the file path is returned instead (`page-<timestamp>.yml` for snapshots, `article-<timestamp>.txt` for `readable`). `screenshot` always saves to `.barebrowse/screenshot-<timestamp>.{png,jpeg,webp}` and returns the file path (raw base64 in a JSON-RPC response would blow `maxChars`). `tabs` returns the JSON array, or with `switchTo: N` it switches and returns `'ok'`. All files MCP writes are owner-only (`0600` in a `0700` dir) — they can hold authenticated page content, so they're not world-readable on a shared host.
package/mcp-server.js CHANGED
@@ -63,6 +63,8 @@ try {
63
63
 
64
64
  function isTransient(err) {
65
65
  const m = err.message || '';
66
+ // A wait_for that simply didn't find its text is a normal result, not a broken browser.
67
+ if (m.startsWith('waitFor timed out')) return false;
66
68
  return m.includes('WebSocket') || m.includes('Target closed') || m.includes('Session closed')
67
69
  || m.includes('CDP') || m.includes('Timeout waiting for CDP event') || m.includes('timed out');
68
70
  }
@@ -95,7 +97,7 @@ async function withRetry(fn, timeoutMs, { retry = true } = {}) {
95
97
  } catch (err) {
96
98
  if (!isTransient(err)) throw err;
97
99
  // Transient failure — reset session so the next request gets a fresh page.
98
- _page = null;
100
+ resetPage();
99
101
  if (!retry) throw err;
100
102
  return await attempt();
101
103
  }
@@ -118,6 +120,49 @@ export function saveSnapshot(text, { prefix = 'page', ext = 'yml' } = {}) {
118
120
  let _page = null;
119
121
  let _pageConnecting = null;
120
122
 
123
+ /**
124
+ * Forget the current session AND close its browser. A bare `_page = null`
125
+ * orphaned the browser (still running, holding GBs) — the next getPage() just
126
+ * launched a second one. Fire-and-forget: callers are on error paths.
127
+ */
128
+ function resetPage() {
129
+ const p = _page;
130
+ _page = null;
131
+ if (p) p.close().catch(() => {});
132
+ }
133
+
134
+ // Idle TTL: a server can outlive its conversation by days, holding a browser
135
+ // (GBs) the whole time. After BAREBROWSE_IDLE_MINUTES (default 15, 0 = off)
136
+ // with no tools/call in flight, release it; the next call opens a fresh one.
137
+ // Capped at setTimeout's max (2^31-1 ms, ~24.8 days): beyond it Node fires after 1ms.
138
+ /**
139
+ * Outer deadline for wait_for: follows the requested wait (page.waitFor
140
+ * defaults to 30000) plus 5s slack, never below TIMEOUTS.wait_for. Otherwise a
141
+ * wait >= the fixed deadline trips withRetry's transient "timed out" and resets
142
+ * the page.
143
+ */
144
+ export function waitForDeadline(timeout) {
145
+ return Math.max(TIMEOUTS.wait_for, (timeout || 30000) + 5000);
146
+ }
147
+
148
+ export function idleMs(raw) {
149
+ const DEFAULT = 15 * 60_000;
150
+ if (raw === undefined || String(raw).trim() === '') return DEFAULT;
151
+ const n = Number(raw);
152
+ if (!Number.isFinite(n) || n < 0) return DEFAULT;
153
+ return Math.min(n * 60_000, 2 ** 31 - 1);
154
+ }
155
+ const IDLE_MS = idleMs(process.env.BAREBROWSE_IDLE_MINUTES);
156
+ let _inflight = 0;
157
+ let _idleTimer = null;
158
+
159
+ function armIdle() {
160
+ clearTimeout(_idleTimer);
161
+ if (!IDLE_MS || _inflight) return;
162
+ _idleTimer = setTimeout(() => { if (!_inflight && _page) resetPage(); }, IDLE_MS);
163
+ _idleTimer.unref();
164
+ }
165
+
121
166
  /**
122
167
  * The engine + mode this server is configured to use, derived from env WITHOUT
123
168
  * launching a browser. Both engines ship in the library; which one this server
@@ -558,7 +603,7 @@ async function handleToolCall(name, args) {
558
603
  const page = await getPage();
559
604
  await page.waitFor({ text: args.text, selector: args.selector, timeout: args.timeout });
560
605
  return 'ok';
561
- }, TIMEOUTS.wait_for, { retry: false });
606
+ }, waitForDeadline(args.timeout), { retry: false });
562
607
  case 'tabs': return withRetry(async () => {
563
608
  const page = await getPage();
564
609
  if (typeof args.switchTo === 'number') {
@@ -639,7 +684,7 @@ async function handleToolCall(name, args) {
639
684
  } catch (err) {
640
685
  clearTimeout(timer);
641
686
  await tab.close().catch(() => {});
642
- if (isTransient(err)) _page = null;
687
+ if (isTransient(err)) resetPage();
643
688
  throw err;
644
689
  }
645
690
  } finally {
@@ -693,17 +738,22 @@ async function handleMessage(msg) {
693
738
 
694
739
  if (method === 'tools/call') {
695
740
  const { name, arguments: args } = params;
741
+ _inflight++;
742
+ clearTimeout(_idleTimer);
696
743
  try {
697
744
  const result = await handleToolCall(name, args || {});
698
745
  return jsonrpcResponse(id, {
699
746
  content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
700
747
  });
701
748
  } catch (err) {
702
- if (isTransient(err)) _page = null;
749
+ if (isTransient(err)) resetPage();
703
750
  return jsonrpcResponse(id, {
704
751
  content: [{ type: 'text', text: `Error: ${err.message}` }],
705
752
  isError: true,
706
753
  });
754
+ } finally {
755
+ _inflight--;
756
+ armIdle();
707
757
  }
708
758
  }
709
759
 
@@ -759,8 +809,8 @@ export function runStdio() {
759
809
 
760
810
  // Prevent unhandled rejections and uncaught exceptions from crashing the server.
761
811
  // Browser OOM/crash rejects all pending CDP promises — some may not be awaited.
762
- process.on('unhandledRejection', () => { _page = null; });
763
- process.on('uncaughtException', () => { _page = null; });
812
+ process.on('unhandledRejection', () => { resetPage(); });
813
+ process.on('uncaughtException', () => { resetPage(); });
764
814
 
765
815
  // Clean up on exit
766
816
  process.on('SIGINT', async () => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "barebrowse",
3
- "version": "0.21.0",
3
+ "version": "0.22.0",
4
4
  "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -43,7 +43,8 @@
43
43
  "test:integration": "node --test test/integration/*.test.js",
44
44
  "typecheck": "tsc --noEmit",
45
45
  "build:types": "tsc",
46
- "prepublishOnly": "npm run build:types"
46
+ "prepublishOnly": "npm run build:types",
47
+ "check:lockfile": "node scripts/check-lockfile.mjs"
47
48
  },
48
49
  "keywords": [
49
50
  "browser",
@@ -642,8 +642,9 @@ export async function createFirefoxPage(bidi, opts = {}) {
642
642
  },
643
643
 
644
644
  async close() {
645
- try { await bidi.send('browsingContext.close', { context: topContext }); } catch {}
646
- bidi.close();
645
+ // Best-effort and bounded: a hung browser must not block the hard cleanup.
646
+ try { await withTimeout(bidi.send('browsingContext.close', { context: topContext }), 2500, 'close'); } catch {}
647
+ try { bidi.close(); } catch {}
647
648
  },
648
649
  };
649
650
 
package/src/index.js CHANGED
@@ -809,16 +809,27 @@ export async function connect(opts = {}) {
809
809
  },
810
810
 
811
811
  async close() {
812
- await cdp.send('Target.closeTarget', { targetId: page.targetId });
813
- cdp.close();
814
- await cleanupBrowser(browser);
815
- // If we created the download dir ourselves, clean it up too. Caller-
816
- // supplied opts.downloadPath stays — the caller owns the lifecycle.
817
- if (ownedDownloadDir) {
818
- try {
819
- const { rmSync } = await import('node:fs');
820
- rmSync(ownedDownloadDir, { recursive: true, force: true });
821
- } catch {}
812
+ // Polite tab close is best-effort and bounded: a dead or hung browser
813
+ // must not skip the hard cleanup below (the profile dir / process leak).
814
+ let timer;
815
+ try {
816
+ await Promise.race([
817
+ cdp.send('Target.closeTarget', { targetId: page.targetId }),
818
+ new Promise((r) => { timer = setTimeout(r, 2500); }),
819
+ ]);
820
+ } catch {} finally { clearTimeout(timer); }
821
+ try { cdp.close(); } catch {}
822
+ try {
823
+ await cleanupBrowser(browser); // no-op in attach mode (process: null)
824
+ } finally {
825
+ // If we created the download dir ourselves, clean it up too. Caller-
826
+ // supplied opts.downloadPath stays — the caller owns the lifecycle.
827
+ if (ownedDownloadDir) {
828
+ try {
829
+ const { rmSync } = await import('node:fs');
830
+ rmSync(ownedDownloadDir, { recursive: true, force: true });
831
+ } catch {}
832
+ }
822
833
  }
823
834
  },
824
835
  };
@@ -929,13 +940,19 @@ async function connectFirefox(opts) {
929
940
  });
930
941
  const closePage = page.close.bind(page);
931
942
  page.close = async () => {
932
- await closePage();
933
- await cleanupFirefox(browser); // `browser` tracks the relaunched one if hybrid fired
934
- if (ownedDownloadDir) {
943
+ try {
944
+ await closePage();
945
+ } finally {
935
946
  try {
936
- const { rmSync } = await import('node:fs');
937
- rmSync(ownedDownloadDir, { recursive: true, force: true });
938
- } catch { /* best-effort reap */ }
947
+ await cleanupFirefox(browser); // `browser` tracks the relaunched one if hybrid fired
948
+ } finally {
949
+ if (ownedDownloadDir) {
950
+ try {
951
+ const { rmSync } = await import('node:fs');
952
+ rmSync(ownedDownloadDir, { recursive: true, force: true });
953
+ } catch { /* best-effort reap */ }
954
+ }
955
+ }
939
956
  }
940
957
  };
941
958
  return page;