barebrowse 0.7.1 → 0.9.1

package/mcp-server.js

@@ -10,8 +10,47 @@
  */
 
 import { browse, connect } from './src/index.js';
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+// Read version from package.json so serverInfo.version doesn't drift behind
+// release bumps (pre-fix this was hardcoded 0.7.1 while package.json was 0.8.0).
+const _pkgPath = join(dirname(fileURLToPath(import.meta.url)), 'package.json');
+const PKG_VERSION = JSON.parse(readFileSync(_pkgPath, 'utf8')).version;
+
+/**
+ * Per-tool timeouts (ms). One blanket 30s was too short for SPA cold loads
+ * (goto regularly exceeded it on slow sites) and too long for instant ops
+ * like scroll. The split below is the H5 plan:
+ *   - navigation (goto/reload): 60s
+ *   - browser-history nav (back/forward): 30s
+ *   - interactive ops (click/type/press/scroll/hover/select/drag): 15s
+ *   - read-only ops (snapshot/tabs/eval/wait_for): 15s (wait_for has its own
+ *     internal deadline; this is the outer cap)
+ *   - heavy I/O (pdf/screenshot/upload): 45s
+ * Exported so tests can pin the contract.
+ */
+export const TIMEOUTS = {
+  goto: 60000,
+  reload: 60000,
+  back: 30000,
+  forward: 30000,
+  snapshot: 15000,
+  click: 15000,
+  type: 15000,
+  press: 15000,
+  scroll: 15000,
+  hover: 15000,
+  select: 15000,
+  drag: 15000,
+  tabs: 5000,
+  eval: 15000,
+  wait_for: 60000,
+  upload: 45000,
+  pdf: 45000,
+  screenshot: 45000,
+};
 
 // Optional: privacy assessment via wearehere
 let assessFn = null;
@@ -27,12 +66,17 @@ function isTransient(err) {
 }
 
 /**
- * Retry-once wrapper with per-attempt timeout.
- * On transient failure (CDP death OR timeout), resets session and retries once.
+ * Run fn with a per-attempt timeout. On transient failure (CDP death OR
+ * timeout), reset the session. If `retry` is true (default), retry once on
+ * a fresh page; if false, rethrow without retrying — required for
+ * non-idempotent ops (click/type/etc.) where a partial first attempt
+ * shouldn't be replayed against a blank fresh page.
  * @param {Function} fn - async function to execute
  * @param {number} timeoutMs - per-attempt timeout in ms
+ * @param {object} [opts]
+ * @param {boolean} [opts.retry=true] - whether to retry once on transient failure
  */
-async function withRetry(fn, timeoutMs) {
+async function withRetry(fn, timeoutMs, { retry = true } = {}) {
   async function attempt() {
     if (!timeoutMs) return await fn();
     let timer;
@@ -48,8 +92,9 @@ async function withRetry(fn, timeoutMs) {
     return await attempt();
   } catch (err) {
     if (!isTransient(err)) throw err;
-    // Transient failure — reset session and retry once
+    // Transient failure — reset session so the next request gets a fresh page.
     _page = null;
+    if (!retry) throw err;
     return await attempt();
   }
 }
@@ -96,15 +141,16 @@ function acquireAssessSlot() {
 }
 
 
-const TOOLS = [
+export const TOOLS = [
   {
     name: 'browse',
-    description: 'Browse a URL in a real browser. Use instead of web fetch when the page needs JavaScript, login cookies, consent dismissal, or bot detection. Returns a pruned ARIA snapshot with [ref=N] markers for interaction. Stateless — does not use the session page.',
+    description: 'One-shot headless browse — fetches a URL through a real browser (executes JS, injects cookies, dismisses consent, evades bot detection). Only when plain HTTP fetch can\'t render the page. Returns a pruned ARIA snapshot with [ref=N] markers. Stateless — for multi-step interaction use goto.',
     inputSchema: {
       type: 'object',
       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'],
@@ -112,7 +158,7 @@ const TOOLS = [
   },
   {
     name: 'goto',
-    description: 'Navigate the session page to a URL. Injects cookies from the user\'s browser for authenticated access. Returns ok — call snapshot to observe.',
+    description: 'Open URL in a persistent interactive browser session (pair with snapshot/click/type/press for multi-step flows). Use when the task needs clicking, typing, or form submission. Injects auth cookies. Returns ok — call snapshot to observe.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -127,6 +173,7 @@ 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.' },
       },
     },
@@ -221,8 +268,92 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'reload',
+    description: 'Reload the current page in the session. Returns ok — call snapshot to observe.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ignoreCache: { type: 'boolean', description: 'Bypass HTTP cache (hard reload). Default: false.' },
+      },
+    },
+  },
+  {
+    name: 'screenshot',
+    description: 'Capture a screenshot of the current page. Saves to .barebrowse/screenshot-*.png (or .jpeg/.webp) and returns the file path. Use the file with your image tools.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        format: { type: 'string', enum: ['png', 'jpeg', 'webp'], description: 'Image format (default: png)' },
+        quality: { type: 'number', description: 'JPEG/WebP quality 0-100 (default: 80, ignored for PNG)' },
+      },
+    },
+  },
+  {
+    name: 'wait_for',
+    description: 'Wait for visible text or a CSS selector to appear on the current page. Returns ok when found, throws on timeout.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Substring that must appear in document.body.innerText' },
+        selector: { type: 'string', description: 'CSS selector that must match document.querySelector' },
+        timeout: { type: 'number', description: 'Timeout in ms (default: 30000)' },
+      },
+    },
+  },
+  {
+    name: 'tabs',
+    description: 'List open tabs in the session, or switch to one by index. Returns JSON array of { index, url, title } or "ok" after switch.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        switchTo: { type: 'number', description: 'Tab index to activate. Omit to just list tabs.' },
+      },
+    },
+  },
+  {
+    name: 'select',
+    description: 'Set the value of a <select> dropdown (or custom listbox) by ref. Returns ok.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ref: { type: 'string', description: 'Element ref from snapshot' },
+        value: { type: 'string', description: 'Option value or visible text to select' },
+      },
+      required: ['ref', 'value'],
+    },
+  },
+  {
+    name: 'hover',
+    description: 'Hover over an element by ref (triggers tooltips, hover menus). Returns ok.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ref: { type: 'string', description: 'Element ref from snapshot' },
+      },
+      required: ['ref'],
+    },
+  },
 ];
 
+// Powerful escape hatch — guarded behind an explicit env-var opt-in.
+// Runtime.evaluate in the user's authenticated session lets an agent read
+// cookies/localStorage, dispatch arbitrary events, hit any endpoint, etc.
+// Off by default; flip BAREBROWSE_MCP_EVAL=1 to enable.
+if (process.env.BAREBROWSE_MCP_EVAL === '1') {
+  TOOLS.push({
+    name: 'eval',
+    description: 'Run a JavaScript expression in the current page and return the result. POWERFUL: full access to the authenticated session — DOM, cookies, localStorage, fetch. Enabled because BAREBROWSE_MCP_EVAL=1 is set.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        expression: { type: 'string', description: 'JavaScript expression to evaluate' },
+      },
+      required: ['expression'],
+    },
+  });
+}
+
 // Add assess tool if wearehere is installed
 if (assessFn) {
   TOOLS.push({
@@ -245,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);
@@ -261,32 +392,32 @@ async function handleToolCall(name, args) {
       try { await page.injectCookies(args.url); } catch {}
       await page.goto(args.url);
       return 'ok';
-    }, 30000);
+    }, 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);
         return `Snapshot (${text.length} chars) saved to ${file}`;
       }
       return text;
-    }, 30000);
+    }, TIMEOUTS.snapshot);
     case 'click': return withRetry(async () => {
       const page = await getPage();
       await page.click(args.ref);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.click, { retry: false });
     case 'type': return withRetry(async () => {
       const page = await getPage();
       await page.type(args.ref, args.text, { clear: args.clear });
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.type, { retry: false });
     case 'press': return withRetry(async () => {
       const page = await getPage();
       await page.press(args.key);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.press, { retry: false });
     case 'scroll': return withRetry(async () => {
       const page = await getPage();
       let dy = args.deltaY;
@@ -298,31 +429,90 @@ async function handleToolCall(name, args) {
       }
       await page.scroll(dy);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.scroll, { retry: false });
     case 'back': return withRetry(async () => {
       const page = await getPage();
       await page.goBack();
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.back, { retry: false });
     case 'forward': return withRetry(async () => {
       const page = await getPage();
       await page.goForward();
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.forward, { retry: false });
     case 'drag': return withRetry(async () => {
       const page = await getPage();
       await page.drag(args.fromRef, args.toRef);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.drag, { retry: false });
     case 'upload': return withRetry(async () => {
       const page = await getPage();
       await page.upload(args.ref, args.files);
       return 'ok';
-    }, 30000);
+    }, TIMEOUTS.upload, { retry: false });
     case 'pdf': return withRetry(async () => {
       const page = await getPage();
       return await page.pdf({ landscape: args.landscape });
-    }, 30000);
+    }, TIMEOUTS.pdf);
+    case 'reload': return withRetry(async () => {
+      const page = await getPage();
+      await page.reload({ ignoreCache: !!args.ignoreCache });
+      return 'ok';
+    }, TIMEOUTS.reload);
+    case 'screenshot': return withRetry(async () => {
+      const page = await getPage();
+      const format = args.format || 'png';
+      const b64 = await page.screenshot({ format, quality: args.quality });
+      mkdirSync(OUTPUT_DIR, { recursive: true });
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(OUTPUT_DIR, `screenshot-${ts}.${format}`);
+      writeFileSync(file, Buffer.from(b64, 'base64'));
+      return file;
+    }, TIMEOUTS.screenshot);
+    case 'wait_for': return withRetry(async () => {
+      const page = await getPage();
+      await page.waitFor({ text: args.text, selector: args.selector, timeout: args.timeout });
+      return 'ok';
+    }, TIMEOUTS.wait_for, { retry: false });
+    case 'tabs': return withRetry(async () => {
+      const page = await getPage();
+      if (typeof args.switchTo === 'number') {
+        await page.switchTab(args.switchTo);
+        return 'ok';
+      }
+      const list = await page.tabs();
+      return JSON.stringify(list, null, 2);
+    }, TIMEOUTS.tabs, { retry: false });
+    case 'select': return withRetry(async () => {
+      const page = await getPage();
+      await page.select(args.ref, args.value);
+      return 'ok';
+    }, TIMEOUTS.select, { retry: false });
+    case 'hover': return withRetry(async () => {
+      const page = await getPage();
+      await page.hover(args.ref);
+      return 'ok';
+    }, TIMEOUTS.hover, { retry: false });
+    case 'eval': {
+      // Only reachable when BAREBROWSE_MCP_EVAL=1 — the tool isn't registered
+      // otherwise, but this guard is the second line of defense in case the
+      // env var changes between tools/list and tools/call.
+      if (process.env.BAREBROWSE_MCP_EVAL !== '1') {
+        throw new Error('eval is disabled. Set BAREBROWSE_MCP_EVAL=1 to enable.');
+      }
+      return withRetry(async () => {
+        const page = await getPage();
+        const { result, exceptionDetails } = await page.cdp.send('Runtime.evaluate', {
+          expression: args.expression,
+          returnByValue: true,
+          awaitPromise: true,
+        });
+        if (exceptionDetails) {
+          throw new Error(exceptionDetails.text + (exceptionDetails.exception?.description ? `: ${exceptionDetails.exception.description}` : ''));
+        }
+        return result.value === undefined ? 'undefined' : JSON.stringify(result.value);
+      }, TIMEOUTS.eval, { retry: false });
+    }
     case 'assess': {
       if (!assessFn) throw new Error('wearehere is not installed. Run: npm install wearehere');
       const releaseSlot = await acquireAssessSlot();
@@ -391,7 +581,7 @@ async function handleMessage(msg) {
     return jsonrpcResponse(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'barebrowse', version: '0.7.1' },
+      serverInfo: { name: 'barebrowse', version: PKG_VERSION },
     });
   }
 
@@ -423,55 +613,71 @@ async function handleMessage(msg) {
 }
 
 // --- Stdio transport ---
+//
+// Exported as runStdio() so callers (notably cli.js) can explicitly start the
+// JSON-RPC loop. The previous "auto-start when isMain" guard broke the
+// `npx barebrowse mcp` path because cli.js launches the server via
+// `await import('./mcp-server.js')` — process.argv[1] is cli.js, not
+// mcp-server.js, so isMain was false and the loop never started. Both the
+// direct `node mcp-server.js` invocation and the cli.js path now call
+// runStdio() explicitly. Tests import TIMEOUTS/TOOLS without calling it.
+
+export function runStdio() {
+  // One-line startup banner to stderr (stderr because stdout is the JSON-RPC
+  // channel — must not contain non-JSON-RPC bytes). Captured by Claude Code's
+  // MCP log, makes "I added barebrowse twice and got the wrong one" issues
+  // diagnosable: the path here is the absolute file actually being served,
+  // so a scope conflict shows two different paths in two log files.
+  const _selfPath = fileURLToPath(import.meta.url);
+  process.stderr.write(`barebrowse mcp v${PKG_VERSION} | serving from ${_selfPath} | pid ${process.pid}\n`);
+
+  let buffer = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+
+    let newlineIdx;
+    while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newlineIdx).trim();
+      buffer = buffer.slice(newlineIdx + 1);
+      if (!line) continue;
 
-let buffer = '';
-
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (chunk) => {
-  buffer += chunk;
-
-  let newlineIdx;
-  while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
-    const line = buffer.slice(0, newlineIdx).trim();
-    buffer = buffer.slice(newlineIdx + 1);
-    if (!line) continue;
-
-    try {
-      const msg = JSON.parse(line);
-
-      handleMessage(msg).then((response) => {
-        if (response) {
+      try {
+        const msg = JSON.parse(line);
 
-          process.stdout.write(response + '\n');
+        handleMessage(msg).then((response) => {
+          if (response) {
+            process.stdout.write(response + '\n');
+          }
+        }).catch((err) => {
+          process.stdout.write(jsonrpcError(msg.id, -32700, `Error: ${err.message}`) + '\n');
+        });
+      } catch (err) {
+        process.stdout.write(jsonrpcError(null, -32700, `Parse error: ${err.message}`) + '\n');
+      }
+    }
+  });
 
-        }
-      }).catch((err) => {
+  // Prevent unhandled rejections and uncaught exceptions from crashing the server.
+  // Browser OOM/crash rejects all pending CDP promises — some may not be awaited.
+  process.on('unhandledRejection', () => { _page = null; });
+  process.on('uncaughtException', () => { _page = null; });
 
-        process.stdout.write(jsonrpcError(msg.id, -32700, `Error: ${err.message}`) + '\n');
-      });
-    } catch (err) {
+  // Clean up on exit
+  process.on('SIGINT', async () => {
+    if (_page) await _page.close().catch(() => {});
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => {
+    if (_page) await _page.close().catch(() => {});
+    process.exit(0);
+  });
+}
 
-      process.stdout.write(jsonrpcError(null, -32700, `Parse error: ${err.message}`) + '\n');
-    }
-  }
-});
-
-// Prevent unhandled rejections and uncaught exceptions from crashing the server.
-// Browser OOM/crash rejects all pending CDP promises — some may not be awaited.
-process.on('unhandledRejection', (err) => {
-  _page = null;
-});
-process.on('uncaughtException', (err) => {
-  _page = null;
-});
-
-// Clean up on exit
-process.on('SIGINT', async () => {
-  if (_page) await _page.close().catch(() => {});
-  process.exit(0);
-});
-
-process.on('SIGTERM', async () => {
-  if (_page) await _page.close().catch(() => {});
-  process.exit(0);
-});
+// Direct invocation (`node mcp-server.js`) still works without cli.js — auto-
+// start if this file IS process.argv[1]. The cli.js path imports + calls
+// runStdio() explicitly so we never depend on argv[1] matching.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runStdio();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.7.1",
+  "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",
@@ -31,5 +31,5 @@
   "optionalDependencies": {
     "wearehere": "^1.0.0"
   },
-  "license": "MIT"
+  "license": "Apache-2.0"
 }

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);
       },
     },
     {
@@ -244,6 +250,39 @@ export function createBrowseTools(opts = {}) {
         return await page.screenshot({ format });
       },
     },
+    {
+      name: 'reload',
+      description: 'Reload the current page. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ignoreCache: { type: 'boolean', description: 'Bypass HTTP cache (hard reload). Default: false.' },
+        },
+      },
+      execute: async ({ ignoreCache } = {}) => actionAndSnapshot((page) => page.reload({ ignoreCache })),
+    },
+    {
+      name: 'wait_for',
+      description: 'Wait for visible text or a CSS selector to appear on the current page. Returns the updated snapshot once found.',
+      parameters: {
+        type: 'object',
+        properties: {
+          text: { type: 'string', description: 'Substring that must appear in document.body.innerText' },
+          selector: { type: 'string', description: 'CSS selector that must match document.querySelector' },
+          timeout: { type: 'number', description: 'Timeout in ms (default: 30000)' },
+        },
+      },
+      execute: async ({ text, selector, timeout } = {}) => actionAndSnapshot((page) => page.waitFor({ text, selector, timeout })),
+    },
+    {
+      name: 'downloads',
+      description: 'List files captured via Content-Disposition: attachment downloads during this session. Returns JSON array of { url, suggestedFilename, savedPath, state, totalBytes, receivedBytes } per file.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => {
+        const page = await getPage();
+        return JSON.stringify(page.downloads.map((d) => ({ ...d })), null, 2);
+      },
+    },
   ];
 
   // Add assess tool if wearehere is installed