barebrowse 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-06-12
+
+### Added
+- **`readable()` — clean article extraction.** New read mode that returns the
+  main article of a page as clean text (title + body prose, nav/ads/sidebars
+  stripped) via Mozilla Readability injected in-page over CDP. Companion to
+  `snapshot()`, not a replacement: `snapshot()` is the *actionable* ARIA tree
+  for clicking/typing; `readable()` is for *reading/summarising* article-like
+  pages (news, blogs, docs, wiki), where `snapshot()` is noisy and silently
+  lossy on long prose. Article detection is unreliable, so `readable()` never
+  hard-gates — it always returns the text plus an advisory `confidence`
+  (`high`/`low`) and a hint to fall back to `snapshot()` on non-article pages.
+  Exposed everywhere: `page.readable()`, MCP `readable` tool, bareagent
+  `readable` tool, and `barebrowse readable` CLI (→ `.barebrowse/article-*.txt`).
+
+### Fixed
+- **Large pages no longer kill the CDP connection.** Node's built-in WebSocket
+  (undici) silently caps decompressed messages at ~3 MB and *permanently* tears
+  down the socket when a single `Accessibility.getFullAXTree` response exceeds
+  it — which broke `snapshot()` (and consent dismissal during `goto()`) on big
+  pages (e.g. long Wikipedia articles). `cdp.js` now uses the `ws` package with
+  a 256 MB `maxPayload`; the built-in exposes no way to raise the limit.
+  Regression test: `connect.test.js` snapshots a 12k-node page that tripped the
+  old cap.
+
+### Security
+- **MCP output files are now owner-only (`0600`).** `saveSnapshot()` and the
+  screenshot tool previously wrote snapshots / articles / screenshots with
+  default perms (`0644` in a `0755` dir under the standard umask) —
+  authenticated page content readable by other local users on a shared host.
+  They now write `0600` files in a `0700` dir, umask-independent, matching the
+  daemon's existing invariant. Regression-guarded by a test that fails on a
+  `0644` write.
+- **Daemon hardening:** `GET /status` (the only pre-auth endpoint) no longer
+  returns the pid; `/command` now caps the request body at 16 MB (→ `413`).
+
+### Changed
+- **Two runtime dependencies (previously zero):** `ws` (CDP transport, above)
+  and `@mozilla/readability` (`readable()`). Both are lightweight, widely
+  adopted, and actively maintained, per the project's dependency rule (external
+  only when the stdlib genuinely can't do the job).
+
 ## [0.12.0] - 2026-05-29
 
 ### Added

package/README.md

@@ -10,6 +10,7 @@
 ```
 
 <p align="center">
+  <a href="https://github.com/hamr0/barebrowse/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/hamr0/barebrowse/ci.yml?label=CI" alt="CI"></a>
   <img src="https://img.shields.io/github/package-json/v/hamr0/barebrowse?label=version&color=2a4f8c" alt="version (auto from package.json)">
   <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
 </p>
@@ -25,7 +26,7 @@ barebrowse gives your AI agent a real browser. Navigate, read, interact, move on
 
 It uses the browser you already have -- your sessions, your cookies. Pages come back stripped to what matters -- 40-90% fewer tokens than raw output.
 
-No Playwright. Zero dependencies. No bundled browser. No 200MB download.
+No Playwright. No bundled browser. No 200MB download. Two tiny dependencies (`ws` + Mozilla Readability).
 
 ## Install
 
@@ -44,6 +45,7 @@ Ships with TypeScript types (generated from JSDoc) — autocomplete and type-che
 ```bash
 barebrowse open https://example.com    # Start session + navigate
 barebrowse snapshot                    # ARIA snapshot → .barebrowse/page-*.yml
+barebrowse readable                    # Clean article text → .barebrowse/article-*.txt
 barebrowse click 8                     # Click element
 barebrowse close                       # End session
 ```
@@ -94,7 +96,7 @@ 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).
+19 tools: `browse`, `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](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.
 
@@ -102,7 +104,7 @@ Troubleshooting MCP setup: `npx barebrowse doctor` scans every known config loca
 
 ### 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) (17 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) (18 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.
 
@@ -169,6 +171,7 @@ 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. |
+| **Readable** | Clean article text (title + body, chrome stripped — Reader-View engine). For *reading* article-like pages, not interacting. Advisory `confidence`; falls back to snapshot on non-articles. |
 | **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 |
@@ -215,7 +218,7 @@ URL -> find/launch browser (chromium.js)
     -> agent-ready snapshot with [ref=N] markers
 ```
 
-11 modules, 2,400 lines, zero required dependencies.
+14 modules, ~3,000 lines, two small dependencies (`ws`, `@mozilla/readability`).
 
 ## Requirements
 

package/barebrowse.context.md

@@ -67,6 +67,7 @@ const snapshot = await browse('https://example.com', {
 | `goForward()` | -- | void | Navigate forward in browser history |
 | `reload(opts?)` | { ignoreCache?: boolean, timeout?: number } | void | Reload the current page. Clears refMap (refs from pre-reload reject). |
 | `snapshot(pruneOpts?)` | false or { mode: 'act'\|'read' } | string | ARIA tree with `[ref=N]` markers. Pass `false` for raw. |
+| `readable()` | -- | object | Clean article text (Reader-View engine). `{ ok, title, byline, text, length, confidence: 'high'\|'low', readerable, hint? }` or `{ ok: false, hint }`. For *reading*, not interacting — see note below. |
 | `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 |
@@ -122,6 +123,28 @@ Key rules:
 - `click(ref)` / `type(ref, text)` / `hover(ref)` / `select(ref, value)` use these ref strings
 - Pruning removes noise (~47-95% token reduction) while keeping all interactive elements
 
+## readable() vs snapshot() — which to use
+
+Two different jobs:
+
+- **`snapshot()`** → the *actionable* ARIA tree (`[ref=N]` markers). Use it to **interact** (click/type/fill) or on **any** page type (home pages, search results, app UIs).
+- **`readable()`** → the *article* as clean reading text (title + body prose; nav/ads/sidebars stripped). Use it **only** to **read or summarise** article-like pages (news, blogs, docs, wiki), where `snapshot()` is both noisy and *silently lossy on long prose* (`read` pruning can drop body text).
+
+`readable()` is **not** a token-savings feature — vs a read-mode snapshot it can be smaller *or* larger depending on the page; its value is **complete, clean prose**. It returns no refs, so you cannot interact with its output.
+
+**Article detection is unreliable**, so `readable()` never hard-gates. It always returns whatever it extracted plus an advisory `confidence`:
+- `confidence: 'high'` → safe to treat as an article.
+- `confidence: 'low'` (or `ok: false`) → probably not an article; the `hint` tells the agent to fall back to `snapshot()`.
+
+```js
+const r = await page.readable();
+if (r.ok && r.confidence === 'high') {
+  use(r.text);              // clean article prose
+} else {
+  const snap = await page.snapshot({ mode: 'read' });  // fall back
+}
+```
+
 ## Interaction loop: observe, think, act
 
 ```javascript
@@ -207,10 +230,10 @@ try {
 ```
 
 `createBrowseTools(opts)` returns:
-- `tools` -- array of bareagent-compatible tool objects: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `select`, `hover`, `back`, `forward`, `reload` (v0.9.0), `drag`, `upload`, `tabs`, `switchTab`, `pdf`, `screenshot`, `wait_for` (v0.9.0), `downloads` (v0.9.0), plus `assess` if wearehere installed
+- `tools` -- array of bareagent-compatible tool objects: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `select`, `hover`, `back`, `forward`, `reload` (v0.9.0), `drag`, `upload`, `tabs`, `switchTab`, `pdf`, `screenshot`, `wait_for` (v0.9.0), `downloads` (v0.9.0), plus `assess` if wearehere installed
 - `close()` -- cleanup function, call when done
 
-Action tools (click, type, press, scroll, hover, goto, back, forward, reload, drag, upload, select, switchTab, wait_for) 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, reload, drag, upload, select, switchTab, wait_for) auto-return a fresh snapshot so the LLM always sees the result. 300ms settle delay after actions for DOM updates. `readable` is a read tool (like `snapshot`): it returns the article text directly, not a follow-up snapshot.
 
 `onDialog` is intentionally not exposed as a tool — it's a callback shape that doesn't fit a request/response tool loop. If your bareagent flow needs to override a confirm/prompt, drop to `import { connect }` directly and pass the page through.
 
@@ -221,6 +244,7 @@ For coding agents (Claude Code, Copilot, Cursor) and quick interactive testing.
 ```bash
 barebrowse open https://example.com    # Start daemon + navigate
 barebrowse snapshot                    # → .barebrowse/page-<timestamp>.yml
+barebrowse readable                    # → .barebrowse/article-<timestamp>.txt (clean article text)
 barebrowse click 8                     # Click element ref=8
 barebrowse type 12 hello world         # Type into element ref=12
 barebrowse back                        # Go back in history
@@ -262,11 +286,11 @@ barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or an
 }
 ```
 
-18 core tools as of v0.9.0: `browse` (one-shot), `goto`, `snapshot`, `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.
+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.
 
 Action tools return `'ok'` -- the agent calls `snapshot` explicitly to observe. This avoids double-token output since MCP tool calls are cheap to chain.
 
-`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`, `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.
 
 `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.
 

package/cli.js

@@ -38,6 +38,8 @@ if (args.includes('--daemon-internal')) {
   await cmdProxy('goto', { url: args[1], timeout: parseFlag('--timeout') });
 } else if (cmd === 'snapshot') {
   await cmdProxy('snapshot', { mode: parseFlag('--mode') });
+} else if (cmd === 'readable') {
+  await cmdProxy('readable');
 } else if (cmd === 'screenshot') {
   await cmdProxy('screenshot', { format: parseFlag('--format') });
 } else if (cmd === 'click' && args[1]) {
@@ -504,6 +506,7 @@ Navigation:
   barebrowse forward                Go forward in history
   barebrowse reload [--no-cache]    Reload current page
   barebrowse snapshot [--mode=M]    ARIA snapshot -> .barebrowse/page-*.yml
+  barebrowse readable               Clean article text -> .barebrowse/article-*.txt
   barebrowse screenshot [--format]  Screenshot -> .barebrowse/screenshot-*.png
   barebrowse pdf [--landscape]      PDF export -> .barebrowse/page-*.pdf
 

package/mcp-server.js

@@ -3,13 +3,15 @@
  * mcp-server.js — MCP server for barebrowse.
  *
  * Raw JSON-RPC 2.0 over stdio. No SDK dependency.
- * 12 tools: browse, goto, snapshot, click, type, press, scroll, back, forward, drag, upload, pdf.
+ * Tools: browse, goto, snapshot, readable, click, type, press, scroll, back,
+ * forward, drag, upload, pdf, reload, screenshot, wait_for, tabs, select, hover.
  *
  * Session tools share a singleton page, lazy-created on first use.
  * Action tools return 'ok' — agent calls snapshot explicitly to observe.
  */
 
 import { browse, connect } from './src/index.js';
+import { formatReadable } from './src/readable.js';
 import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
@@ -102,11 +104,14 @@ async function withRetry(fn, timeoutMs, { retry = true } = {}) {
 const MAX_CHARS_DEFAULT = 30000;
 const OUTPUT_DIR = join(process.cwd(), '.barebrowse');
 
-function saveSnapshot(text) {
-  mkdirSync(OUTPUT_DIR, { recursive: true });
+export function saveSnapshot(text, { prefix = 'page', ext = 'yml' } = {}) {
+  // Owner-only: snapshots/articles can hold authenticated page content
+  // (logged-in text, reflected session data). Matches the daemon's 0600/0700
+  // invariant — and is umask-independent because the modes are explicit.
+  mkdirSync(OUTPUT_DIR, { recursive: true, mode: 0o700 });
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  const file = join(OUTPUT_DIR, `page-${ts}.yml`);
-  writeFileSync(file, text);
+  const file = join(OUTPUT_DIR, `${prefix}-${ts}.${ext}`);
+  writeFileSync(file, text, { mode: 0o600 });
   return file;
 }
 
@@ -178,6 +183,16 @@ export const TOOLS = [
       },
     },
   },
+  {
+    name: 'readable',
+    description: 'Extract the main article of the current page as clean reading text (title + body prose, nav/ads/sidebars stripped — the Firefox Reader View engine). Use ONLY when your goal is to READ or SUMMARISE article-like content (news, blog posts, docs, wiki). For clicking/typing/forms, or for non-article pages (home pages, search results, app UIs), use snapshot instead. On a non-article page this returns a low-confidence result with a hint to use snapshot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        maxChars: { type: 'number', description: 'Max chars to return inline. Longer articles are saved to .barebrowse/ and a file path is returned instead. Default: 30000.' },
+      },
+    },
+  },
   {
     name: 'click',
     description: 'Click an element by its ref from the snapshot. Returns ok — call snapshot to observe.',
@@ -403,6 +418,18 @@ async function handleToolCall(name, args) {
       }
       return text;
     }, TIMEOUTS.snapshot);
+    case 'readable': return withRetry(async () => {
+      const page = await getPage();
+      const r = await page.readable();
+      if (!r.ok) return r.hint;
+      const body = formatReadable(r);
+      const limit = args.maxChars ?? MAX_CHARS_DEFAULT;
+      if (body.length > limit) {
+        const file = saveSnapshot(body, { prefix: 'article', ext: 'txt' });
+        return `Article "${r.title}" (${r.text.length} chars, confidence: ${r.confidence}) saved to ${file}`;
+      }
+      return body;
+    }, TIMEOUTS.snapshot);
     case 'click': return withRetry(async () => {
       const page = await getPage();
       await page.click(args.ref);
@@ -463,10 +490,11 @@ async function handleToolCall(name, args) {
       const page = await getPage();
       const format = args.format || 'png';
       const b64 = await page.screenshot({ format, quality: args.quality });
-      mkdirSync(OUTPUT_DIR, { recursive: true });
+      mkdirSync(OUTPUT_DIR, { recursive: true, mode: 0o700 });
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const file = join(OUTPUT_DIR, `screenshot-${ts}.${format}`);
-      writeFileSync(file, Buffer.from(b64, 'base64'));
+      // Owner-only: a screenshot of an authenticated page is sensitive too.
+      writeFileSync(file, Buffer.from(b64, 'base64'), { mode: 0o600 });
       return file;
     }, TIMEOUTS.screenshot);
     case 'wait_for': return withRetry(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "repository": {
     "type": "git",
@@ -63,5 +63,9 @@
   "devDependencies": {
     "@types/node": "^25.9.1",
     "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "ws": "^8.21.0"
   }
 }

package/src/bareagent.js

@@ -14,6 +14,7 @@
 /// <reference path="./wearehere.d.ts" />
 
 import { browse, connect } from './index.js';
+import { formatReadable } from './readable.js';
 
 // Optional: privacy assessment via wearehere
 let assessFn = null;
@@ -93,6 +94,15 @@ export function createBrowseTools(opts = {}) {
         return await page.snapshot(pruneMode ? { mode: pruneMode } : undefined);
       },
     },
+    {
+      name: 'readable',
+      description: 'Extract the main article as clean reading text (title + body prose, chrome stripped — Firefox Reader View engine). Use ONLY to READ/SUMMARISE article-like pages (news, blogs, docs, wiki). For interacting, or for non-article pages, use snapshot. Returns a low-confidence hint to use snapshot when the page is not an article.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => {
+        const page = await getPage();
+        return formatReadable(await page.readable());
+      },
+    },
     {
       name: 'click',
       description: 'Click an element by its ref from the snapshot. Returns the updated snapshot.',

package/src/cdp.js

@@ -2,20 +2,29 @@
  * cdp.js — Minimal Chrome DevTools Protocol client over WebSocket.
  *
  * Sends JSON-RPC commands, receives responses and events.
- * Uses Node 22's built-in WebSocket (no external deps).
+ * Uses the `ws` package (not Node's built-in WebSocket): the built-in
+ * silently caps decompressed messages at ~3 MB and permanently kills the
+ * socket when a single CDP response (e.g. Accessibility.getFullAXTree on a
+ * large page) exceeds it — with no way to raise the limit. `ws` exposes
+ * maxPayload, so we lift the ceiling and disable compression.
  *
  * Supports flattened sessions: when a sessionId is provided,
  * it's sent at the top level of the message (not inside params).
  * Events from sessions are also dispatched by sessionId.
  */
 
+import WebSocket from 'ws';
+
+/** Lift the message ceiling well past any realistic AX/DOM payload. */
+const MAX_PAYLOAD = 256 * 1024 * 1024; // 256 MB
+
 /**
  * Create a CDP client connected to the given WebSocket URL.
  * @param {string} wsUrl - WebSocket URL (ws://127.0.0.1:PORT/devtools/...)
  * @returns {Promise<object>} CDP client ({ send, on, once, session, close })
  */
 export async function createCDP(wsUrl) {
-  const ws = new WebSocket(wsUrl);
+  const ws = new WebSocket(wsUrl, { maxPayload: MAX_PAYLOAD, perMessageDeflate: false });
   let nextId = 1;
   const pending = new Map();   // id → { resolve, reject }
   const listeners = new Map(); // "method" or "sessionId:method" → Set<callback>

package/src/daemon.js

@@ -11,6 +11,7 @@ import { writeFileSync, mkdirSync, existsSync, readFileSync, unlinkSync } from '
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { join, resolve } from 'node:path';
 import { connect } from './index.js';
+import { formatReadable } from './readable.js';
 
 /** Owner-only file write helper — daemon artifacts can hold authenticated content. */
 function writeFilePrivate(path, data) {
@@ -191,6 +192,17 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       return { ok: true, file };
     },
 
+    async readable() {
+      const r = await page.readable();
+      // A non-article page is not an error — surface the hint so the agent
+      // knows to fall back to snapshot, rather than failing the command.
+      if (!r.ok) return { ok: true, value: r.hint };
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(absDir, `article-${ts}.txt`);
+      writeFilePrivate(file, formatReadable(r));
+      return { ok: true, file };
+    },
+
     async screenshot({ format }) {
       const data = await page.screenshot({ format: format || 'png' });
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
@@ -361,8 +373,11 @@ export async function runDaemon(opts, outputDir, initialUrl) {
   // Start HTTP server on random port
   const server = createServer(async (req, res) => {
     if (req.method === 'GET' && req.url === '/status') {
+      // Liveness only — no pid. /status is the one pre-auth endpoint, and
+      // isAlive() just checks res.ok; the pid clients show comes from
+      // session.json (owner-only), so nothing consumes a pid here.
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: true, pid: process.pid }));
+      res.end(JSON.stringify({ ok: true }));
       return;
     }
 
@@ -380,8 +395,20 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       return;
     }
 
+    // Cap the request body. Post-auth, single local user, but an unbounded
+    // `body +=` is a needless memory-DoS foot-gun. 16 MB covers any realistic
+    // eval expression / typed text.
+    const MAX_BODY = 16 * 1024 * 1024;
     let body = '';
-    for await (const chunk of req) body += chunk;
+    for await (const chunk of req) {
+      body += chunk;
+      if (body.length > MAX_BODY) {
+        res.writeHead(413, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'Request body too large' }));
+        req.destroy();
+        return;
+      }
+    }
 
     let parsed;
     try {

package/src/index.js

@@ -18,6 +18,7 @@ import { dismissConsent } from './consent.js';
 import { applyStealth } from './stealth.js';
 import { DEFAULT_BLOCKLIST } from './blocklist.js';
 import { waitForNetworkIdle } from './network-idle.js';
+import { readable as extractReadable } from './readable.js';
 import { assertNavigable, assertUploadAllowed } from './url-guard.js';
 import { join as pathJoin } from 'node:path';
 import { chmodSync } from 'node:fs';
@@ -459,6 +460,13 @@ export async function connect(opts = {}) {
       return stats + '\n' + hint + warn + out;
     },
 
+    // Clean article text (Firefox Reader View engine), for reading/summarising
+    // — not for interacting. Returns { ok:false, hint } on non-article pages.
+    // See readable.js for why this never hard-gates on article detection.
+    async readable() {
+      return extractReadable(page.session);
+    },
+
     async click(ref) {
       const entry = refMap.get(ref);
       if (!entry) throw new Error(`No element found for ref "${ref}"`);

package/src/readable.js

@@ -0,0 +1,116 @@
+/**
+ * readable.js — extract the main article of a page as clean reading text.
+ *
+ * Companion to snapshot(): snapshot() yields an *actionable* ARIA tree for
+ * clicking/typing; readable() yields the *readable* article (title + body
+ * prose, nav/ads/sidebars stripped) for "read/summarise this" tasks, where
+ * snapshot() is both noisy and silently lossy on long prose.
+ *
+ * Runs Mozilla's Readability (the engine behind Firefox Reader View) inside
+ * the live page over CDP — so JS-rendered articles work, unlike a raw fetch.
+ * `isProbablyReaderable` gives an article-likelihood signal, but it is not
+ * reliable on its own (false negatives on minimally-marked-up essays, false
+ * positives on link-dense portals), so readable() never hard-gates: it always
+ * returns whatever Readability extracted plus an advisory `confidence`. A
+ * low-confidence result is the agent's cue to fall back to snapshot().
+ */
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// Read the self-contained browser builds once at module load and inject their
+// source into the page. Both define globals (Readability, isProbablyReaderable)
+// when evaluated in a non-module context; the `if (typeof module ...)` tails are
+// harmless no-ops in the page.
+const READABILITY_SRC = readFileSync(require.resolve('@mozilla/readability/Readability.js'), 'utf8');
+const READERABLE_SRC = readFileSync(require.resolve('@mozilla/readability/Readability-readerable.js'), 'utf8');
+
+/** Below this many characters of extracted text, treat as low confidence. */
+const MIN_ARTICLE_CHARS = 1500;
+
+// Fully static — interpolates only the two module-level source constants — so
+// it's built once at load, not rebuilt (~120 KB) on every readable() call.
+const EXTRACT_EXPRESSION = `(() => {
+  ${READERABLE_SRC}
+  ${READABILITY_SRC}
+  try {
+    const readerable = isProbablyReaderable(document);
+    // Readability mutates the document it parses — clone so the live page
+    // (and any later snapshot()/interaction) is untouched.
+    const art = new Readability(document.cloneNode(true)).parse();
+    if (!art || !art.textContent || !art.textContent.trim()) {
+      return { ok: false, readerable };
+    }
+    return {
+      ok: true,
+      readerable,
+      title: art.title || '',
+      byline: art.byline || '',
+      text: art.textContent.trim(),
+      length: art.length || art.textContent.length,
+    };
+  } catch (e) {
+    return { ok: false, err: String(e && e.message || e) };
+  }
+})()`;
+
+/**
+ * Render a readable() result as a text block: a short header (title / byline /
+ * confidence, with the fall-back hint inline when present) then the body. On a
+ * failed extraction it returns the hint. Shared by the MCP, bareagent, and
+ * CLI/daemon surfaces so their output can't drift apart.
+ * @param {object} r - a readable() result.
+ * @returns {string}
+ */
+export function formatReadable(r) {
+  if (!r.ok) return r.hint;
+  const header = `title: ${r.title}${r.byline ? `\nbyline: ${r.byline}` : ''}\n`
+    + `confidence: ${r.confidence}${r.hint ? ` (${r.hint})` : ''}\n\n`;
+  return header + r.text;
+}
+
+/**
+ * Extract the main article from the current page.
+ * @param {object} session - CDP session-scoped handle (.send()).
+ * @returns {Promise<object>} One of:
+ *   { ok: false, hint }                              — no article content found
+ *   { ok: true, title, byline, text, length,
+ *     confidence: 'high'|'low', readerable, hint? }  — extracted article
+ */
+export async function readable(session) {
+  const { result } = await session.send('Runtime.evaluate', {
+    expression: EXTRACT_EXPRESSION,
+    returnByValue: true,
+    awaitPromise: true,
+  });
+  const r = result.value || {};
+
+  if (!r.ok) {
+    return {
+      ok: false,
+      hint: r.err
+        ? `readable extraction failed (${r.err}); use snapshot()`
+        : 'no article content found on this page; use snapshot() instead',
+    };
+  }
+
+  // Advisory confidence: high only when the reader-view heuristic agrees AND
+  // there is a substantial amount of text. Low is not an error — the text is
+  // still returned; it just means "verify, or prefer snapshot()".
+  const confidence = r.readerable && r.length >= MIN_ARTICLE_CHARS ? 'high' : 'low';
+  const out = {
+    ok: true,
+    title: r.title,
+    byline: r.byline,
+    text: r.text,
+    length: r.length,
+    readerable: r.readerable,
+    confidence,
+  };
+  if (confidence === 'low') {
+    out.hint = 'low article confidence — this may not be an article; consider snapshot()';
+  }
+  return out;
+}

package/types/cdp.d.ts

@@ -1,13 +1,3 @@
-/**
- * cdp.js — Minimal Chrome DevTools Protocol client over WebSocket.
- *
- * Sends JSON-RPC commands, receives responses and events.
- * Uses Node 22's built-in WebSocket (no external deps).
- *
- * Supports flattened sessions: when a sessionId is provided,
- * it's sent at the top level of the message (not inside params).
- * Events from sessions are also dispatched by sessionId.
- */
 /**
  * Create a CDP client connected to the given WebSocket URL.
  * @param {string} wsUrl - WebSocket URL (ws://127.0.0.1:PORT/devtools/...)

package/types/readable.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Render a readable() result as a text block: a short header (title / byline /
+ * confidence, with the fall-back hint inline when present) then the body. On a
+ * failed extraction it returns the hint. Shared by the MCP, bareagent, and
+ * CLI/daemon surfaces so their output can't drift apart.
+ * @param {object} r - a readable() result.
+ * @returns {string}
+ */
+export function formatReadable(r: object): string;
+/**
+ * Extract the main article from the current page.
+ * @param {object} session - CDP session-scoped handle (.send()).
+ * @returns {Promise<object>} One of:
+ *   { ok: false, hint }                              — no article content found
+ *   { ok: true, title, byline, text, length,
+ *     confidence: 'high'|'low', readerable, hint? }  — extracted article
+ */
+export function readable(session: object): Promise<object>;