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 +32 -0
- package/README.md +2 -0
- package/barebrowse.context.md +3 -1
- package/mcp-server.js +56 -6
- package/package.json +3 -2
- package/src/firefox-page.js +3 -2
- package/src/index.js +33 -16
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.
|
package/barebrowse.context.md
CHANGED
|
@@ -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
|
-
|
|
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
|
-
},
|
|
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))
|
|
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))
|
|
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', () => {
|
|
763
|
-
process.on('uncaughtException', () => {
|
|
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.
|
|
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",
|
package/src/firefox-page.js
CHANGED
|
@@ -642,8 +642,9 @@ export async function createFirefoxPage(bidi, opts = {}) {
|
|
|
642
642
|
},
|
|
643
643
|
|
|
644
644
|
async close() {
|
|
645
|
-
|
|
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
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
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
|
-
|
|
933
|
-
|
|
934
|
-
|
|
943
|
+
try {
|
|
944
|
+
await closePage();
|
|
945
|
+
} finally {
|
|
935
946
|
try {
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
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;
|