barebrowse 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.7.0
+
+MCP resilience: timeouts, auto-retry, LLM-friendly scroll, and click fallback for hidden elements.
+
+### Timeouts (`mcp-server.js`)
+- All MCP tool calls now have a hard timeout: 30s for session tools, 60s for `browse` and `assess`
+- Returns a structured error (`Tool "X" timed out after Ns`) instead of hanging silently
+- Previously: a hung browser or slow page caused `[Tool result missing due to internal error]` — opaque and unrecoverable
+
+### Auto-retry (`mcp-server.js`)
+- `withRetry()` wrapper on all session tools (goto, snapshot, click, type, press, scroll, back, forward, drag, upload, pdf)
+- On transient CDP failure (WebSocket closed, target/session closed), resets the session and retries once automatically
+- Non-CDP errors (validation, unknown tool) are not retried
+
+### LLM-friendly scroll (`mcp-server.js`, `src/bareagent.js`)
+- Scroll tool now accepts `direction: "up"/"down"` in addition to numeric `deltaY`
+- LLMs naturally say `scroll(direction: "down")` — this now works instead of crashing with `deltaX/deltaY expected for mouseWheel event`
+- `"down"` → `deltaY: 900`, `"up"` → `deltaY: -900`. Numeric `deltaY` still works and takes precedence.
+- Clear validation error if neither `direction` nor `deltaY` is provided
+
+### Click JS fallback (`src/interact.js`)
+- Click now falls back to JS `element.click()` when `DOM.scrollIntoViewIfNeeded` fails with "Node does not have a layout object"
+- This error occurs on elements that exist in the ARIA tree but have no visual layout (display:none, zero-size, collapsed sections, detached nodes)
+- Resolves the node via `DOM.requestNode` → `DOM.resolveNode` → `Runtime.callFunctionOn`
+- Other click errors still throw normally
+
+### Docs
+- Updated barebrowse.context.md, README.md, prd.md with resilience features
+- MCP server version string updated to 0.7.0
+
+### Tests
+- 71/71 passing — no test changes needed
+
 ## 0.6.1
 
 Headed fallback is now a per-navigation escape hatch, not a permanent mode switch. Graceful degradation when headed is unavailable.

package/README.md

@@ -87,7 +87,7 @@ Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`
 }
 ```
 
-12 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `forward`, `drag`, `upload`, `pdf`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Session runs in hybrid mode with automatic cookie injection.
+12 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `forward`, `drag`, `upload`, `pdf`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Session runs in hybrid mode with automatic cookie injection. All tools have timeouts (30s/60s) and auto-retry on transient failures.
 
 ### 3. Library -- for agentic automation
 
@@ -129,10 +129,10 @@ Everything the agent can do through barebrowse:
 | **Navigate** | Load a URL, wait for page load, auto-dismiss consent |
 | **Back / Forward** | Browser history navigation |
 | **Snapshot** | Pruned ARIA tree with `[ref=N]` markers. Two modes: `act` (buttons, links, inputs) and `read` (full text). 40-90% token reduction. |
-| **Click** | Scroll into view + mouse click at element center |
+| **Click** | Scroll into view + mouse click at element center, JS fallback for hidden elements |
 | **Type** | Focus + insert text, with option to clear existing content first |
 | **Press** | Special keys: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
-| **Scroll** | Mouse wheel up or down |
+| **Scroll** | Mouse wheel up or down (accepts direction or pixels) |
 | **Hover** | Move mouse to element center (triggers tooltips, hover states) |
 | **Select** | Set dropdown value (native select or custom dropdown) |
 | **Drag** | Drag one element to another (Kanban boards, sliders) |

package/barebrowse.context.md

@@ -1,7 +1,7 @@
 # barebrowse -- Integration Guide
 
 > For AI assistants and developers wiring barebrowse into a project.
-> v0.6.1 | Node.js >= 22 | 0 required deps | MIT
+> v0.7.0 | Node.js >= 22 | 0 required deps | MIT
 
 ## What this is
 
@@ -59,7 +59,7 @@ const snapshot = await browse('https://example.com', {
 | `click(ref)` | ref: string | void | Scroll into view + mouse press+release at center |
 | `type(ref, text, opts?)` | ref: string, text: string, opts: { clear?, keyEvents? } | void | Focus + insert text. `clear: true` replaces existing. |
 | `press(key)` | key: string | void | Special key: Enter, Tab, Escape, Backspace, Delete, arrows, Home, End, PageUp, PageDown, Space |
-| `scroll(deltaY)` | deltaY: number | void | Mouse wheel. Positive = down, negative = up. |
+| `scroll(deltaY)` | deltaY: number | void | Mouse wheel. Positive = down, negative = up. MCP/bareagent also accept `direction: "up"/"down"`. |
 | `hover(ref)` | ref: string | void | Move mouse to element center |
 | `select(ref, value)` | ref: string, value: string | void | Set `<select>` value or click custom dropdown option |
 | `drag(fromRef, toRef)` | fromRef: string, toRef: string | void | Drag from one element to another |
@@ -149,7 +149,7 @@ barebrowse can inject cookies from the user's real browser sessions, bypassing l
 | Media autoplay blocked | `--autoplay-policy=no-user-gesture-required` | Both |
 | Login walls | Cookie extraction from Firefox/Chromium + CDP injection | Both |
 | Pre-filled form inputs | `type({ clear: true })` selects all + deletes first | Both |
-| Off-screen elements | `DOM.scrollIntoViewIfNeeded` before every click | Both |
+| Off-screen elements | `DOM.scrollIntoViewIfNeeded` before every click, JS `.click()` fallback for no-layout elements | Both |
 | Form submission | `press('Enter')` triggers onsubmit | Both |
 | SPA navigation | `waitForNavigation()` uses loadEventFired + frameNavigated | Both |
 | Bot detection | ARIA node count (<50 = bot-blocked) + text heuristics. `botBlocked` flag set after every `goto()`. Hybrid fallback switches to headed. Snapshot shows `[BOT CHALLENGE DETECTED]` warning. | Hybrid |
@@ -241,7 +241,7 @@ Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe.
 
 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. Assess tries headless first; if bot-blocked (score ≤5 with all zeros), retries with a separate headed session. Tabs dismissed for consent and closed after every scan. Max 3 concurrent. Browser OOM/crash auto-recovers (session resets, server stays alive).
+Session tools share a singleton page, lazy-created on first use. All session tools have auto-retry on transient CDP failures (browser crash, WebSocket close) — session resets and retries once automatically. 30s timeout on all tools (60s for `browse`/`assess`). Scroll accepts `direction: "up"/"down"` in addition to numeric `deltaY`. Click falls back to JS `.click()` when elements have no layout. Assess tries headless first; if bot-blocked, retries headed. Browser OOM/crash auto-recovers (session resets, server stays alive).
 
 ## Architecture
 

package/mcp-server.js

@@ -25,6 +25,18 @@ function isCdpDead(err) {
   return m.includes('WebSocket') || m.includes('Target closed') || m.includes('Session closed') || m.includes('CDP');
 }
 
+/** Retry-once wrapper for transient CDP failures. Resets session and retries. */
+async function withRetry(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (!isCdpDead(err)) throw err;
+    // CDP died — reset session and retry once
+    _page = null;
+    return await fn();
+  }
+}
+
 const MAX_CHARS_DEFAULT = 30000;
 const OUTPUT_DIR = join(process.cwd(), '.barebrowse');
 
@@ -139,13 +151,13 @@ const TOOLS = [
   },
   {
     name: 'scroll',
-    description: 'Scroll the page. Positive deltaY scrolls down, negative scrolls up. Returns ok.',
+    description: 'Scroll the page up or down. Pass direction ("up"/"down") or a numeric deltaY. Returns ok.',
     inputSchema: {
       type: 'object',
       properties: {
-        deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up)' },
+        direction: { type: 'string', enum: ['up', 'down'], description: 'Scroll direction — "up" or "down" (scrolls ~3 screen-heights)' },
+        deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up). Overrides direction if both given.' },
       },
-      required: ['deltaY'],
     },
   },
   {
@@ -222,13 +234,13 @@ async function handleToolCall(name, args) {
       }
       return text;
     }
-    case 'goto': {
+    case 'goto': return withRetry(async () => {
       const page = await getPage();
       try { await page.injectCookies(args.url); } catch {}
       await page.goto(args.url);
       return 'ok';
-    }
-    case 'snapshot': {
+    });
+    case 'snapshot': return withRetry(async () => {
       const page = await getPage();
       const text = await page.snapshot();
       const limit = args.maxChars ?? MAX_CHARS_DEFAULT;
@@ -237,51 +249,58 @@ async function handleToolCall(name, args) {
         return `Snapshot (${text.length} chars) saved to ${file}`;
       }
       return text;
-    }
-    case 'click': {
+    });
+    case 'click': return withRetry(async () => {
       const page = await getPage();
       await page.click(args.ref);
       return 'ok';
-    }
-    case 'type': {
+    });
+    case 'type': return withRetry(async () => {
       const page = await getPage();
       await page.type(args.ref, args.text, { clear: args.clear });
       return 'ok';
-    }
-    case 'press': {
+    });
+    case 'press': return withRetry(async () => {
       const page = await getPage();
       await page.press(args.key);
       return 'ok';
-    }
-    case 'scroll': {
+    });
+    case 'scroll': return withRetry(async () => {
       const page = await getPage();
-      await page.scroll(args.deltaY);
+      let dy = args.deltaY;
+      if (dy == null && args.direction) {
+        dy = args.direction === 'up' ? -900 : 900;
+      }
+      if (dy == null || typeof dy !== 'number') {
+        throw new Error('scroll requires "direction" ("up"/"down") or numeric "deltaY"');
+      }
+      await page.scroll(dy);
       return 'ok';
-    }
-    case 'back': {
+    });
+    case 'back': return withRetry(async () => {
       const page = await getPage();
       await page.goBack();
       return 'ok';
-    }
-    case 'forward': {
+    });
+    case 'forward': return withRetry(async () => {
       const page = await getPage();
       await page.goForward();
       return 'ok';
-    }
-    case 'drag': {
+    });
+    case 'drag': return withRetry(async () => {
       const page = await getPage();
       await page.drag(args.fromRef, args.toRef);
       return 'ok';
-    }
-    case 'upload': {
+    });
+    case 'upload': return withRetry(async () => {
       const page = await getPage();
       await page.upload(args.ref, args.files);
       return 'ok';
-    }
-    case 'pdf': {
+    });
+    case 'pdf': return withRetry(async () => {
       const page = await getPage();
       return await page.pdf({ landscape: args.landscape });
-    }
+    });
     case 'assess': {
       if (!assessFn) throw new Error('wearehere is not installed. Run: npm install wearehere');
       const releaseSlot = await acquireAssessSlot();
@@ -350,7 +369,7 @@ async function handleMessage(msg) {
     return jsonrpcResponse(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'barebrowse', version: '0.6.0' },
+      serverInfo: { name: 'barebrowse', version: '0.7.0' },
     });
   }
 
@@ -364,12 +383,19 @@ async function handleMessage(msg) {
 
   if (method === 'tools/call') {
     const { name, arguments: args } = params;
+    const TOOL_TIMEOUT = name === 'browse' || name === 'assess' ? 60000 : 30000;
     try {
-      const result = await handleToolCall(name, args || {});
+      let timer;
+      const result = await Promise.race([
+        handleToolCall(name, args || {}),
+        new Promise((_, rej) => { timer = setTimeout(() => rej(new Error(`Tool "${name}" timed out after ${TOOL_TIMEOUT / 1000}s`)), TOOL_TIMEOUT); }),
+      ]);
+      clearTimeout(timer);
       return jsonrpcResponse(id, {
         content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
       });
     } catch (err) {
+      if (isCdpDead(err)) _page = null;
       return jsonrpcResponse(id, {
         content: [{ type: 'text', text: `Error: ${err.message}` }],
         isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "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

@@ -116,15 +116,20 @@ export function createBrowseTools(opts = {}) {
     },
     {
       name: 'scroll',
-      description: 'Scroll the page. Returns the updated snapshot.',
+      description: 'Scroll the page up or down. Pass direction ("up"/"down") or a numeric deltaY. Returns the updated snapshot.',
       parameters: {
         type: 'object',
         properties: {
-          deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up)' },
+          direction: { type: 'string', enum: ['up', 'down'], description: 'Scroll direction — "up" or "down" (scrolls ~3 screen-heights)' },
+          deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up). Overrides direction if both given.' },
         },
-        required: ['deltaY'],
       },
-      execute: async ({ deltaY }) => actionAndSnapshot((page) => page.scroll(deltaY)),
+      execute: async ({ direction, deltaY }) => {
+        let dy = deltaY;
+        if (dy == null && direction) dy = direction === 'up' ? -900 : 900;
+        if (dy == null || typeof dy !== 'number') throw new Error('scroll requires "direction" or numeric "deltaY"');
+        return actionAndSnapshot((page) => page.scroll(dy));
+      },
     },
     {
       name: 'select',

package/src/interact.js

@@ -46,13 +46,27 @@ async function getCenter(session, backendNodeId) {
  * @param {number} backendNodeId - Backend DOM node ID
  */
 export async function click(session, backendNodeId) {
-  const { x, y } = await getCenter(session, backendNodeId);
-  await session.send('Input.dispatchMouseEvent', {
-    type: 'mousePressed', x, y, button: 'left', clickCount: 1,
-  });
-  await session.send('Input.dispatchMouseEvent', {
-    type: 'mouseReleased', x, y, button: 'left', clickCount: 1,
-  });
+  try {
+    const { x, y } = await getCenter(session, backendNodeId);
+    await session.send('Input.dispatchMouseEvent', {
+      type: 'mousePressed', x, y, button: 'left', clickCount: 1,
+    });
+    await session.send('Input.dispatchMouseEvent', {
+      type: 'mouseReleased', x, y, button: 'left', clickCount: 1,
+    });
+  } catch (err) {
+    // Element has no layout (display:none, zero-size, detached) — fall back to JS click
+    if (err.message && err.message.includes('layout object')) {
+      const { nodeId } = await session.send('DOM.requestNode', { backendNodeId });
+      const { object } = await session.send('DOM.resolveNode', { nodeId });
+      await session.send('Runtime.callFunctionOn', {
+        objectId: object.objectId,
+        functionDeclaration: 'function() { this.click(); }',
+      });
+    } else {
+      throw err;
+    }
+  }
 }
 
 /**