[nicklongmore86]

Design PR 3: the read_document agent tool, built on the sandboxed DocumentWorkerHost from #52.

What changed

Shared contract (src/main/tools/types.ts): ToolImage and ToolResult.images, the same edit as feat/provider-images. This PR only produces images. Provider code is untouched.

read_document (src/main/tools/read-document.ts, registered for every connection)

• Input: path, plus one of pages ("3", "2-5", "10-"), start (continue from a page) or region ({page,x,y,width,height}, zoom up to 8x). Optional include_location.
• Uses the same guard as read_file (granted folders, realpath, secret/protected blocklist) and openVerified (no links, single hard link, handle re-checked). The worker gets a copy of the bytes, never the path.
• content: a header (path, type, size, pages, range shown, title/author), then the text page by page, then notes. The last line gives either a start: N hint or "End of document". images: rendered drawing/scan pages (label: "page 3"), the zoomed region, or the photo (upright, scaled, EXIF/GPS stripped). Capture time and camera come back as text. Location only with include_location.
• No approval needed, but every call is audited. The entry records includeLocation when it was asked for and locationRead: true when a location was actually returned, plus the kind and the image count (new RunResult.audit, merged by defineTool).
• HEIC, AVIF and Office files get a clear "not supported yet" (unsupported). Text files are pointed to read_file. Reader refusals and worker failures (timeout, crash, memory, a misbehaving worker) become clean error results with an audit category (unreadable, out-of-range, timeout, worker-failed).
• Per-call limits come from Sandboxed document reader: sniffing, PDF (PDFium WASM) and images #52 (50 pages, 20 images, 100 MB, text budget). The tool also refuses files over 100 MB before reading them.

read_file: the binary refusal now says X is a PDF, not text; use read_document to read it. for PDFs and images.

Attachments: when a chat is sent, a PDF attachment is read by the reader:

• its text goes in page by page, in a fenced block marked user-provided and untrusted;
• drawn or scanned pages go as image blocks on the Claude API, with a note in their place on other connections (sendsImages);
• results are cached per attachment id (16 PDFs), so a re-send doesn't parse again;
• a PDF that can't be read becomes a placeholder that says why;
• PDF chips are no longer greyed (canReceive).

Image attachments are left for the other PR.

Lifecycle: one DocumentWorkerHost per app (src/main/index.ts), shared by the tool and attachments and disposed on will-quit.

Verification

• pnpm typecheck, pnpm lint and pnpm format:check: clean.
• pnpm test (Vitest, whole repo): 125 files passed, 2 skipped. 2673 test cases passed, 34 skipped.
  • New: src/main/tools/read-document.test.ts uses a fake host. It covers output format, ranges/start/regions, input validation, the photo GPS gate and its audit fields, unsupported types, error mapping, and the guards (outside the grant, .env, protected userData, symlink out of the grant, hard link, folder, missing file, over 100 MB). It also covers the new read_file messages.
  • New: the PDF cases in src/main/chat/attachments.test.ts: fenced untrusted text, images vs notes, caching, failure placeholders, and session wiring.
• pnpm build && xvfb-run -a pnpm test:e2e: 129 passed. That includes the new e2e/read-document.spec.ts (6 tests), which runs the real tools (out/main/tools.js, a new build entry) over the real worker:
  • a PDF: text, the drawn page as a decodable PNG, the start hint, a zoomed region;
  • a rotated JPEG with EXIF: comes back upright, with EXIF stripped, GPS only when asked, and locationRead audited;
  • guard refusals;
  • a password-protected PDF;
  • timeout and hostile-worker failures as clean tool errors, with main still responsive.

Notes for merging

• src/main/tools/types.ts matches the contract exactly. feat/provider-images may also touch canReceive in src/renderer/src/attachments/model.ts (for images), which could give a one-line conflict there.
• Until providers send tool images, images reach no model. Each content is written to make sense on its own.

🤖 Generated with Claude Code