barebrowse 0.4.7 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.5.1
+
+bareagent tool parity + test fix.
+
+### bareagent adapter
+- Added `hover`, `tabs`, `switchTab`, `pdf` tools (was 13 + assess, now 17 + assess)
+- bareagent now exposes the full connect() API surface
+
+### Tests
+- Fixed 2 snapshot URL prefix assertions (`# url` → `url: url`) to match 0.4.7 format change
+- 69/69 passing
+
+### Version
+- Package version: 0.5.1
+- MCP server version string updated
+
+## 0.5.0
+
+Privacy assessment via wearehere integration.
+
+### New: `assess` tool
+- Scans any URL for privacy risks: cookies, trackers, fingerprinting, dark patterns, data brokers, form surveillance, link tracking, and toxic terms of service
+- Returns compact JSON: score (0-100), risk level (low/moderate/high/critical), per-category breakdown (10 categories with score/max/summary), concerns list, and recommendation
+- Available in MCP server (13th tool) and bareagent adapter (14th tool)
+- Conditionally loaded: only available when `wearehere` npm package is installed
+- Uses a dedicated `connect()` page per scan (isolated from the session page)
+
+### Integration
+- `wearehere` added as optional dependency in package.json
+- MCP server: dynamic `import('wearehere')` with try/catch fallback
+- bareagent adapter: same dynamic import pattern
+- Zero impact when wearehere is not installed — all existing tools work unchanged
+
+### Version
+- Package version: 0.5.0
+- MCP server version string updated
+
+## 0.4.8
+
+- Fix: `browse()` one-shot also had `#` prefix (missed in 0.4.7)
+- MCP server version string updated
+
 ## 0.4.7
 
 Snapshot URL prefix format changed from `# <url>` to `url: <url>`.

package/README.md

@@ -87,11 +87,11 @@ 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`. 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.
 
 ### 3. Library -- for agentic automation
 
-Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for [bareagent](https://www.npmjs.com/package/bare-agent) (13 tools, auto-snapshot after every action).
+Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for [bareagent](https://www.npmjs.com/package/bare-agent) (17 tools, auto-snapshot after every action).
 
 For code examples, API reference, and wiring instructions, see **[barebrowse.context.md](barebrowse.context.md)** -- the full integration guide.
 
@@ -139,6 +139,7 @@ Everything the agent can do through barebrowse:
 | **Upload** | Set files on a file input element |
 | **Screenshot** | Page capture as base64 PNG/JPEG/WebP |
 | **PDF** | Export page as PDF |
+| **Assess** | Privacy scan: score (0-100), risk level, 10-category breakdown. Requires `npm install wearehere`. |
 | **Tabs** | List open tabs, switch between them |
 | **Wait for content** | Poll for text or CSS selector to appear on page |
 | **Wait for navigation** | SPA-aware: works for full page loads and pushState |
@@ -174,7 +175,7 @@ URL -> find/launch browser (chromium.js)
     -> agent-ready snapshot with [ref=N] markers
 ```
 
-11 modules, 2,400 lines, zero dependencies.
+11 modules, 2,400 lines, zero required dependencies.
 
 ## Requirements
 

package/barebrowse.context.md

@@ -1,7 +1,7 @@
 # barebrowse -- Integration Guide
 
 > For AI assistants and developers wiring barebrowse into a project.
-> v0.4.2 | Node.js >= 22 | 0 required deps | MIT
+> v0.5.1 | Node.js >= 22 | 0 required deps | MIT
 
 ## What this is
 
@@ -90,7 +90,7 @@ const snapshot = await browse('https://example.com', {
 The snapshot is a YAML-like ARIA tree. First line is the page URL, second is pruning stats, then the tree:
 
 ```
-# https://example.com/
+url: https://example.com/
 # 379 chars → 45 chars (88% pruned)
 - heading "Example Domain" [level=1] [ref=3]
 - link "More information..." [ref=8]
@@ -184,10 +184,10 @@ try {
 ```
 
 `createBrowseTools(opts)` returns:
-- `tools` -- array of bareagent-compatible tool objects (browse, goto, snapshot, click, type, press, scroll, select, back, forward, drag, upload, screenshot)
+- `tools` -- array of bareagent-compatible tool objects (browse, goto, snapshot, click, type, press, scroll, select, hover, back, forward, drag, upload, tabs, switchTab, pdf, screenshot, plus assess if wearehere installed)
 - `close()` -- cleanup function, call when done
 
-Action tools (click, type, press, scroll, goto) auto-return a fresh snapshot so the LLM always sees the result. 300ms settle delay after actions for DOM updates.
+Action tools (click, type, press, scroll, hover, goto, back, forward, drag, upload, select, switchTab) auto-return a fresh snapshot so the LLM always sees the result. 300ms settle delay after actions for DOM updates.
 
 ## CLI session mode
 
@@ -233,7 +233,7 @@ barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or an
 }
 ```
 
-12 tools exposed: `browse` (one-shot), `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `forward`, `drag`, `upload`, `pdf`.
+12 core tools: `browse` (one-shot), `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `forward`, `drag`, `upload`, `pdf`. Plus `assess` (privacy scan) if `wearehere` is installed (`npm install wearehere`).
 
 Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe. This avoids double-token output since MCP tool calls are cheap to chain.
 
@@ -270,9 +270,37 @@ URL -> chromium.js (find/launch browser, permission flags)
 | `src/interact.js` | ~170 | Click, type, press, scroll, hover, select |
 | `src/consent.js` | 200 | Auto-dismiss cookie consent dialogs across languages |
 | `src/stealth.js` | ~40 | Navigator patches for headless anti-detection |
-| `src/bareagent.js` | ~120 | Tool adapter for bareagent Loop |
+| `src/bareagent.js` | ~250 | Tool adapter for bareagent Loop |
 | `mcp-server.js` | ~170 | MCP server (JSON-RPC over stdio) |
 
+## Privacy assessment (optional)
+
+Install `wearehere` to add an `assess` tool to both the MCP server and bareagent adapter:
+
+```bash
+npm install wearehere
+```
+
+The `assess` tool navigates to a URL in an isolated browser page, scans for 10 privacy categories (cookies, trackers, fingerprinting, dark patterns, data brokers, form surveillance, link tracking, toxic terms, stored data, network traffic), and returns a compact JSON assessment:
+
+```json
+{
+  "site": "example.com",
+  "score": 62,
+  "risk": "high",
+  "recommendation": "Significant privacy risks. Avoid sharing personal info here.",
+  "concerns": ["Heavy hidden tracking", "Aggressive device fingerprinting"],
+  "categories": {
+    "cookies":      { "score": 10, "max": 15, "summary": "7 third-party cookies" },
+    "trackers":     { "score": 20, "max": 20, "summary": "14 hidden elements" },
+    "profiling":    { "score": 10, "max": 20, "summary": "Canvas + WebGL" },
+    "terms":        { "score": 15, "max": 15, "summary": "Binding arbitration" }
+  }
+}
+```
+
+Useful for agent threshold decisions: "skip sites above score 40", "warn if terms score >= 10", etc. When wearehere is not installed, the tool simply doesn't appear — no errors, no impact.
+
 ## Gotchas
 
 1. **Refs are ephemeral.** Every `snapshot()` call generates new refs. Always snapshot before interacting. Never cache refs across snapshots.

package/mcp-server.js

@@ -13,6 +13,13 @@ import { browse, connect } from './src/index.js';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+// Optional: privacy assessment via wearehere
+let assessFn = null;
+try {
+  ({ assess: assessFn } = await import('wearehere'));
+} catch {}
+
+
 const MAX_CHARS_DEFAULT = 30000;
 const OUTPUT_DIR = join(process.cwd(), '.barebrowse');
 
@@ -158,6 +165,23 @@ const TOOLS = [
   },
 ];
 
+// Add assess tool if wearehere is installed
+if (assessFn) {
+  TOOLS.push({
+    name: 'assess',
+    description: 'Privacy assessment of any website. Navigates to the URL, scans for cookies, trackers, fingerprinting, dark patterns, data brokers, form surveillance, link tracking, and toxic terms. Returns a compact JSON with risk score (0-100), per-category breakdown, and recommendation. Powered by wearehere.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'URL to assess (e.g. "https://example.com")' },
+        timeout: { type: 'number', description: 'Navigation timeout in ms (default: 30000)' },
+        settle: { type: 'number', description: 'Time to wait for trackers to load after page load, in ms (default: 3000)' },
+      },
+      required: ['url'],
+    },
+  });
+}
+
 async function handleToolCall(name, args) {
   switch (name) {
     case 'browse': {
@@ -229,6 +253,19 @@ async function handleToolCall(name, args) {
       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 page = await connect({ mode: 'hybrid' });
+      try {
+        const result = await assessFn(page, args.url, {
+          timeout: args.timeout,
+          settle: args.settle,
+        });
+        return JSON.stringify(result, null, 2);
+      } finally {
+        await page.close().catch(() => {});
+      }
+    }
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
@@ -249,7 +286,7 @@ async function handleMessage(msg) {
     return jsonrpcResponse(id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'barebrowse', version: '0.4.6' },
+      serverInfo: { name: 'barebrowse', version: '0.5.1' },
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.4.7",
+  "version": "0.5.1",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "type": "module",
   "main": "src/index.js",
@@ -28,5 +28,8 @@
     "mcp",
     "headless"
   ],
+  "optionalDependencies": {
+    "wearehere": "^1.0.0"
+  },
   "license": "MIT"
 }

package/src/bareagent.js

@@ -13,6 +13,12 @@
 
 import { browse, connect } from './index.js';
 
+// Optional: privacy assessment via wearehere
+let assessFn = null;
+try {
+  ({ assess: assessFn } = await import('wearehere'));
+} catch {}
+
 const SETTLE_MS = 300;
 const settle = () => new Promise((r) => setTimeout(r, SETTLE_MS));
 
@@ -133,6 +139,18 @@ export function createBrowseTools(opts = {}) {
       },
       execute: async ({ ref, value }) => actionAndSnapshot((page) => page.select(ref, value)),
     },
+    {
+      name: 'hover',
+      description: 'Hover over an element by its ref. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'string', description: 'Element ref from snapshot' },
+        },
+        required: ['ref'],
+      },
+      execute: async ({ ref }) => actionAndSnapshot((page) => page.hover(ref)),
+    },
     {
       name: 'back',
       description: 'Go back in browser history. Returns the updated snapshot.',
@@ -171,6 +189,42 @@ export function createBrowseTools(opts = {}) {
       },
       execute: async ({ ref, files }) => actionAndSnapshot((page) => page.upload(ref, files)),
     },
+    {
+      name: 'tabs',
+      description: 'List all open tabs. Returns JSON array of { index, url, title }.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => {
+        const page = await getPage();
+        const tabList = await page.tabs();
+        return JSON.stringify(tabList, null, 2);
+      },
+    },
+    {
+      name: 'switchTab',
+      description: 'Switch to a tab by index. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          index: { type: 'number', description: 'Tab index (from tabs tool output)' },
+        },
+        required: ['index'],
+      },
+      execute: async ({ index }) => actionAndSnapshot((page) => page.switchTab(index)),
+    },
+    {
+      name: 'pdf',
+      description: 'Export current page as PDF. Returns base64-encoded PDF data.',
+      parameters: {
+        type: 'object',
+        properties: {
+          landscape: { type: 'boolean', description: 'Landscape orientation (default: false)' },
+        },
+      },
+      execute: async ({ landscape } = {}) => {
+        const page = await getPage();
+        return await page.pdf({ landscape });
+      },
+    },
     {
       name: 'screenshot',
       description: 'Take a screenshot of the current page. Returns base64-encoded image.',
@@ -187,6 +241,32 @@ export function createBrowseTools(opts = {}) {
     },
   ];
 
+  // Add assess tool if wearehere is installed
+  if (assessFn) {
+    tools.push({
+      name: 'assess',
+      description: 'Privacy assessment of a website. Returns risk score (0-100), per-category breakdown, concerns, and recommendation.',
+      parameters: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'URL to assess' },
+          timeout: { type: 'number', description: 'Navigation timeout in ms (default: 30000)' },
+          settle: { type: 'number', description: 'Time to wait for trackers to load, in ms (default: 3000)' },
+        },
+        required: ['url'],
+      },
+      execute: async ({ url, timeout, settle }) => {
+        const page = await connect(opts);
+        try {
+          const result = await assessFn(page, url, { timeout, settle });
+          return JSON.stringify(result, null, 2);
+        } finally {
+          await page.close().catch(() => {});
+        }
+      },
+    });
+  }
+
   return {
     tools,
     async close() {

package/src/index.js

@@ -103,7 +103,7 @@ export async function browse(url, opts = {}) {
     } else {
       snapshot = raw;
     }
-    const stats = `# ${url}\n# ${raw.length.toLocaleString()} chars → ${snapshot.length.toLocaleString()} chars (${Math.round((1 - snapshot.length / raw.length) * 100)}% pruned)`;
+    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;
 
     // Step 7: Clean up