feat(tools): read_page — fetch URLs without a browser

[askalf]

Summary

Adds a custom `read_page` tool to hands' SDK mode, alongside the existing `computer` / `bash` / `str_replace_based_edit_tool`. When the agent needs to read web content, it calls `read_page(url)` and gets back cleaned HTML + extracted page metadata directly — no browser, no screenshot, no JavaScript, no OCR.

This is the "browser without a browser" thesis turned into product. Most agent web tasks don't need to interact with a page; they need to read it. For that 80% case, screenshot+OCR is expensive overkill.

Architecture

`read_page` returns cleaned HTML directly to the agent as a `tool_result`. The agent — already a Claude model — reads HTML natively. No nested LLM call to translate HTML → markdown. This makes read_page meaningfully cheaper than alternatives that pre-render server-side.

```
fetch(url, browser-UA, follow-redirects)
→ cheerio parse
→ drop scripts/styles/iframes/svg/canvas/video/audio
→ keep only signal-bearing metadata (title, OG, Twitter, JSON-LD)
→ drop class/style/aria/data-*/onclick attributes
→ resolve relative href/src to absolute URLs
→ prune cookie/consent banners by class/id selector
→ inline lazy-loaded image data-src → src
→ 80KB hard size cap with truncation marker
```

Cost comparison (live-tested, sonnet-4-6 via dario, OAuth subscription billing)

Task	read_page	computer tool path (estimated)
Summarize Wikipedia article	2 turns, 14,236 in / 307 out	6-8 turns, ~50K+ in
Read Anthropic effort docs	2 turns, 10,659 in / 315 out	6-8 turns, ~50K+ in
Identify SPA shell	2 turns, 1,971 in / 330 out	4-6 turns, ~20K+ in

Each `computer` screenshot costs ~1,500 tokens; `read_page` returns ~1-7K tokens of cleaned HTML for the same content. Plus no browser cold-start, no scroll loops, no OCR-style flattening errors.

SPA handling

For pure-SPA URLs (empty body after cleaning, content fetched by JS), `read_page` returns a structured metadata summary plus an explicit marker telling the agent the body was JS-only. Verified live against `https://claude.ai/\` — the agent correctly identifies it as a SPA shell and works from the metadata rather than hallucinating content.

System prompt nudge

Added to `buildSdkSystemPrompt`:

For reading web pages: ALWAYS use the read_page tool, NEVER navigate to a URL with the computer tool. read_page fetches the URL and returns cleaned HTML directly to you — no browser, no screenshot, no JavaScript. Use it for: reading articles, browsing docs, GitHub READMEs, news pages, JSON APIs, RSS feeds. The computer tool is for clicking and typing into a UI; reading content does not need the UI.

Anti-pattern explicitly added: "Do NOT open a browser to read a URL — use read_page."

Test plan

• Unit: `test/page-cleanup.test.mjs` — 17 cases covering script/style/iframe stripping, relative→absolute URL resolution (including protocol-relative + fragment cases), aria/data-attribute removal, comment stripping, lazy-image inlining, JSON-LD parse with malformed-skip, size cap with truncation marker, cookie/consent class+id pruning.
• Local: `npm test` passes 66/66 (was 49 → 66; +17 from this PR).
• Live E2E: 3 prompts (Wikipedia article, Anthropic docs, claude.ai SPA), all successfully used `read_page` instead of the computer tool, all routed through dario for OAuth subscription billing.
• CI: standard hands checks (actionlint, build × Node, CodeQL).

New dependencies

• `cheerio` — HTML parser, ~70KB unpacked, no transitive web runtime. Used in `src/util/page-cleanup.ts`.

Notes

• Custom tool definition (vs. Anthropic beta tool type) — `read_page` is plumbed in alongside the existing beta-typed tools. The SDK accepts mixed tool definitions cleanly; no special handling needed beyond the dispatcher branch.
• Audit log already records every tool call — read_page entries land in `~/.hands/audit.jsonl` with `{tool: "read_page", args: {url}}` shape.
• This pairs cleanly with the dario auto-detect work in #26: `hands` auto-routes through dario for OAuth subscription billing AND uses `read_page` for static web content. The whole web-research path is now subscription-priced and fast.