barebrowse 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.9.1
+
+### Pruning — `pruneMode` reaches MCP / bareagent and `read` finally works
+
+- **`mode: 'read'` is now a real alias for `mode: 'browse'`** in `prune()`.
+  Previously, the CLI (`barebrowse snapshot --mode=read`) and the SKILL.md
+  advertised a `read` mode that did not exist — `MODE_REGIONS[mode] ||
+  MODE_REGIONS.act` silently fell back to act-mode pruning. Articles, docs,
+  and blog posts therefore came back gutted no matter which mode the agent
+  asked for, which is why Claude tended to give up and fall back to
+  WebFetch. One-line alias at the top of `prune()` fixes it; `act|browse|
+  navigate|full` still behave unchanged.
+- **MCP `browse` and `snapshot` tools gained a `pruneMode: 'act'|'read'`
+  parameter** (mcp-server.js). Before this, the MCP surface had no way to
+  ask for any mode other than `act` — `browse`'s `mode` param was browser
+  mode (headless/headed/hybrid), and `snapshot` accepted only `maxChars`.
+  Tool descriptions now tell the caller when to pick `read` (content-heavy
+  pages: articles, docs, blogs).
+- **bareagent `browse` and `snapshot` tools gained the same `pruneMode`
+  parameter** (`src/bareagent.js`) with identical semantics. The `browse`
+  handler preserves any caller-supplied default `opts.pruneMode` when the
+  tool is called without an arg (`pruneMode ? { ...opts, pruneMode } : opts`).
+- **Auto-hint when act-mode looks suspect.** When `page.snapshot()` or
+  `browse()` is called in act mode against a substantial page (raw > 5 KB)
+  and the pruned output collapses to under 500 chars AND under 5% of raw,
+  the result includes a one-line `hint: act mode dropped most of the page
+  — retry with pruneMode='read' …` directly between the stats line and the
+  tree. Thresholds are deliberately conservative: an e-commerce or
+  search-results page (many interactive elements kept) won't trigger it;
+  a paragraph-heavy article will.
+- **Regression test:** `test/unit/prune.test.js` — "aliases mode='read' to
+  browse mode" pins the alias contract by asserting `prune(tree, {mode:
+  'read'})` deep-equals `prune(tree, {mode: 'browse'})` and that paragraphs
+  survive (the act-mode-style stripping that previously masqueraded as
+  read-mode is gone).
+
 ## 0.9.0
 
 Phase B — every H1–H9 from `docs/02-features/fix-plan.md` shipped one

package/README.md

@@ -94,6 +94,8 @@ Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`
 
 18 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. 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).
 
+`browse` and `snapshot` accept `pruneMode: 'act'|'read'` (v0.9.1). `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.
+
 Troubleshooting MCP setup: `npx barebrowse doctor` scans every known config location and flags scope conflicts. `npx barebrowse install --force` overwrites an existing entry pointing at a different endpoint.
 
 ### 3. Library -- for agentic automation

package/barebrowse.context.md

@@ -1,7 +1,7 @@
 # barebrowse -- Integration Guide
 
 > For AI assistants and developers wiring barebrowse into a project.
-> v0.9.0 | Node.js >= 22 | 0 required deps | Apache-2.0
+> v0.9.1 | Node.js >= 22 | 0 required deps | Apache-2.0
 
 ## What this is
 
@@ -255,6 +255,8 @@ Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe.
 
 `browse` and `snapshot` accept a `maxChars` param (default 30000). If the snapshot exceeds the limit, it's saved to `.barebrowse/page-<timestamp>.yml` and a short message with the file path is returned instead. `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'`.
 
+`browse` and `snapshot` also accept `pruneMode: 'act'|'read'`. `act` (the default) keeps interactive elements and short labels — best for clicking/filling. `read` keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. Same surface on the bareagent adapter. If act mode collapses a content-heavy page (raw > 5 KB → pruned < 500 chars AND < 5% of raw), the result includes a `hint: act mode dropped most of the page — retry with pruneMode='read' …` line between the stats and the tree so the caller knows to re-snapshot in read mode instead of bailing to a separate HTTP fetch.
+
 Session runs in hybrid mode (headless with automatic headed fallback on bot detection). `goto` injects cookies from the user's browser before navigation for authenticated access.
 
 Session tools share a singleton page, lazy-created on first use. All session tools have auto-retry on transient failures (browser crash, WebSocket close, navigation timeout) on a per-tool deadline (v0.9.0 H5): `goto`/`reload`/`wait_for` 60s, `back`/`forward` 30s, interactive ops (`click`/`type`/`press`/`scroll`/`hover`/`select`/`drag`/`snapshot`/`eval`) 15s, `tabs` 5s, heavy I/O (`pdf`/`screenshot`/`upload`) 45s — replaces the prior blanket 30s. Session resets between attempts. Idempotent tools retry once; mutating tools (`click`/`type`/`upload`/etc.) `{ retry: false }` so partial first attempts don't replay on a fresh page. Scroll accepts `direction: "up"/"down"` in addition to numeric `deltaY`. Click falls back to JS `.click()` when elements have no layout. `browse` has a 60s timeout (no retry — stateless). Assess tries headless first; if bot-blocked, retries headed. Browser OOM/crash auto-recovers (session resets, server stays alive).

package/mcp-server.js

@@ -150,6 +150,7 @@ export const TOOLS = [
       properties: {
         url: { type: 'string', description: 'URL to browse' },
         mode: { type: 'string', enum: ['headless', 'headed', 'hybrid'], description: 'Browser mode (default: headless)' },
+        pruneMode: { type: 'string', enum: ['act', 'read'], description: 'Pruning mode. "act" (default) keeps interactive elements and short labels — best for clicking/filling. "read" keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If the page is content-heavy and act-mode returns mostly empty, retry with "read".' },
         maxChars: { type: 'number', description: 'Max chars to return inline. Larger snapshots are saved to .barebrowse/ and a file path is returned instead. Default: 30000.' },
       },
       required: ['url'],
@@ -172,6 +173,7 @@ export const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
+        pruneMode: { type: 'string', enum: ['act', 'read'], description: 'Pruning mode. "act" (default) keeps interactive elements and short labels — best for clicking/filling. "read" keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If a previous snapshot looked empty on a content-heavy page, retry with "read".' },
         maxChars: { type: 'number', description: 'Max chars to return inline. Larger snapshots are saved to .barebrowse/ and a file path is returned instead. Default: 30000.' },
       },
     },
@@ -374,7 +376,7 @@ async function handleToolCall(name, args) {
     case 'browse': {
       let timer;
       const text = await Promise.race([
-        browse(args.url, { mode: args.mode }),
+        browse(args.url, { mode: args.mode, pruneMode: args.pruneMode }),
         new Promise((_, rej) => { timer = setTimeout(() => rej(new Error('browse timed out after 60s')), 60000); }),
       ]);
       clearTimeout(timer);
@@ -393,7 +395,7 @@ async function handleToolCall(name, args) {
     }, TIMEOUTS.goto);
     case 'snapshot': return withRetry(async () => {
       const page = await getPage();
-      const text = await page.snapshot();
+      const text = await page.snapshot(args.pruneMode ? { mode: args.pruneMode } : undefined);
       const limit = args.maxChars ?? MAX_CHARS_DEFAULT;
       if (text.length > limit) {
         const file = saveSnapshot(text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "type": "module",
   "main": "src/index.js",

package/src/bareagent.js

@@ -50,10 +50,11 @@ export function createBrowseTools(opts = {}) {
         type: 'object',
         properties: {
           url: { type: 'string', description: 'URL to browse' },
+          pruneMode: { type: 'string', enum: ['act', 'read'], description: '"act" (default) for interactive elements only; "read" for paragraphs and long text (articles/docs).' },
         },
         required: ['url'],
       },
-      execute: async ({ url }) => await browse(url, opts),
+      execute: async ({ url, pruneMode }) => await browse(url, pruneMode ? { ...opts, pruneMode } : opts),
     },
     {
       name: 'goto',
@@ -70,10 +71,15 @@ export function createBrowseTools(opts = {}) {
     {
       name: 'snapshot',
       description: 'Get the current ARIA snapshot. Returns a YAML-like tree with [ref=N] markers on interactive elements.',
-      parameters: { type: 'object', properties: {} },
-      execute: async () => {
+      parameters: {
+        type: 'object',
+        properties: {
+          pruneMode: { type: 'string', enum: ['act', 'read'], description: '"act" (default) for interactive elements only; "read" for paragraphs and long text (articles/docs).' },
+        },
+      },
+      execute: async ({ pruneMode } = {}) => {
         const page = await getPage();
-        return await page.snapshot();
+        return await page.snapshot(pruneMode ? { mode: pruneMode } : undefined);
       },
     },
     {

package/src/index.js

@@ -110,7 +110,11 @@ export async function browse(url, opts = {}) {
       snapshot = raw;
     }
     const stats = `url: ${url}\n${raw.length.toLocaleString()} chars → ${snapshot.length.toLocaleString()} chars (${Math.round((1 - snapshot.length / raw.length) * 100)}% pruned)`;
-    snapshot = stats + '\n' + snapshot;
+    const actMode = !opts.pruneMode || opts.pruneMode === 'act';
+    const hint = (actMode && raw.length > 5000 && snapshot.length < 500 && snapshot.length < raw.length * 0.05)
+      ? `hint: act mode dropped most of the page — retry with pruneMode='read' for paragraphs and long text\n`
+      : '';
+    snapshot = stats + '\n' + hint + snapshot;
 
     // Step 7: Clean up
     await cdp.send('Target.closeTarget', { targetId: page.targetId });
@@ -382,10 +386,14 @@ export async function connect(opts = {}) {
       const pageUrl = entries[currentIndex]?.url || '';
       const warn = botBlocked ? '[BOT CHALLENGE DETECTED — page content may be incomplete or blocked]\n' : '';
       if (pruneOpts === false) return `url: ${pageUrl}\n` + warn + raw;
-      const pruned = pruneTree(result.tree, { mode: pruneOpts?.mode || 'act' });
+      const mode = pruneOpts?.mode || 'act';
+      const pruned = pruneTree(result.tree, { mode });
       const out = formatTree(pruned);
       const stats = `url: ${pageUrl}\n${raw.length.toLocaleString()} chars → ${out.length.toLocaleString()} chars (${Math.round((1 - out.length / raw.length) * 100)}% pruned)`;
-      return stats + '\n' + warn + out;
+      const hint = (mode === 'act' && raw.length > 5000 && out.length < 500 && out.length < raw.length * 0.05)
+        ? `hint: act mode dropped most of the page — retry with pruneMode='read' for paragraphs and long text\n`
+        : '';
+      return stats + '\n' + hint + warn + out;
     },
 
     async click(ref) {

package/src/prune.js

@@ -65,7 +65,8 @@ const SKIP_ROLES = new Set([
  * @returns {object|null} Pruned tree
  */
 export function prune(tree, options = {}) {
-  const { mode = 'act', context = '' } = options;
+  let { mode = 'act', context = '' } = options;
+  if (mode === 'read') mode = 'browse';
   const allowedRegions = MODE_REGIONS[mode] || MODE_REGIONS.act;
   const isBrowse = mode === 'browse';
   const keywords = context