Skip to content

Inbox: attach any file from anywhere; images inline and as tiles, PDFs and files as downloads, comments on images and code - #1834

Merged
backnotprop merged 2 commits into
mainfrom
feat/inbox-attachments-v2
Oct 11, 2026
Merged

backnotprop merged 2 commits into
mainfrom
feat/inbox-attachments-v2

Conversation

@backnotprop

Copy link
Copy Markdown
Owner

The owner's answers on the attachments design (.product/approved/inbox-attachments/approval.md, not in the repo): quality UX first, simple, no heavy guardrails, "make it very accessible and ergonomic for an agent to point out a file so it shows".

Visible behaviour change: what an agent can attach

An agent can now attach any regular file its user can read, from anywhere on disk (an absolute path, or one relative to project_path), of any size. Before, files had to be inside the project and of an annotatable or code type. Still refused: folders ("attach the files in it, or a zip of them"), FIFOs/devices, and the dotenv family (.env, .env.* other than the annotatable .env.example), by the named path and its symlink target. The Inbox keeps a copy of each sent file in inbox/blobs/ (unchanged), so a large file now costs that much disk; Settings' Delete thread / Delete project remove it.

No size cap, as the owner asked. Workspaces may want one on its side (relay items, the iPhone); that question is with them. Send streams bytes through the hash into a temp blob (1 MiB chunks), and serving streams from one descriptor, so no file is held in memory. The relay's existing 32 MiB result-frame bound still answers 413 result_too_large for a larger download over the relay (there is no chunked attachment route in this repo yet).

Kinds

kind is strictly additive: markdown | text | html | mermaid | graphviz | code plus image, pdf, file. Every reader (window, phone surface, server) reads it through readInboxAttachmentKind, so a kind it does not know is file, a download. Decided at send from the bytes (decideInboxAttachmentKind):

Kind Rule Window
documents by extension while the bytes are text (binary: file) unchanged viewers
image sniffImageContentType (PNG/APNG, JPEG, GIF, WebP, AVIF, BMP, ICO magic bytes; SVG by its first element). Extension ignored: an HTML page named .svg is not an image inline in the message AND a tile with a thumbnail; opens beside the thread
pdf %PDF- in the first 1024 bytes Download
code any other UTF-8 text with no NUL (.mjs, Makefile, unknown extensions) code view with line comments
file everything else Download

Records gain additive media_type, width, height.

Workspaces / iPhone / Android (apps live in the Workspaces repo): please follow the new kinds image, pdf, file and treat any unknown kind as file. New byte routes on the device door: attachments/<id>/image, attachments/<id>/download, markups/<name> (the person's marked-up image comments). The phone surface draws a plain card for image/pdf/file/unknown kinds and never reads their bytes as text; the shell is expected to show them natively.

Serving (by attachment id only, never a path)

  • GET /api/inbox/attachments/:id/image[?version=sent]: kind image only; Content-Type re-sniffed from the bytes served; X-Content-Type-Options: nosniff, Content-Security-Policy: sandbox; default-src 'none'; style-src 'unsafe-inline', Cross-Origin-Resource-Policy: same-origin (the message-images policy), ETag/304. The window draws images only through <img src>, so an SVG never runs.
  • GET /api/inbox/attachments/:id/download[?version=sent]: any kind; Content-Disposition: attachment (ASCII filename + filename*=UTF-8''), application/pdf for a PDF else application/octet-stream, CSP sandbox, nosniff, CORP.
  • The text routes (/:id, /view) answer 415 for binary kinds; HTML still renders only through the sandboxed HtmlViewer path.
  • Sec-Fetch-Site: cross-site|same-site is refused before anything is read.
  • The phone's door forwards to these same window routes, so the dotenv refusal (one checkCurrent) and the headers are one; inbox-attachments-kinds.test.ts compares door and window header for header, and proves a record naming a .env is refused on both.

Comments, reusing existing pieces

  • Images: a comment box under the image plus Mark up, which opens ui's ImageAnnotator (pen, arrow, circle). The drawing is posted to POST /api/inbox/markups (same-origin, stale-tab guarded), kept once as inbox/markups/<sha256>.png, and rides the comment's images, so the reply's feedback names a file the agent can open (- [shot, marked up] /…/inbox/markups/<sha>.png). Selecting a comment shows its drawing on the stage. Markups go with their thread/project.
  • Code: CodeFilePopout's body is extracted into an exported CodeFileView (the popout renders it unchanged), and the pane uses it: Pierre's File, click a line, drag a range or select code. Stored as Plannotator annotations (blockId code-L<a>-<b>, inboxCode), exported "(lines 12–14)", Unanchored when the lines changed. Plain text above 100,000 characters, as before.
  • Both flow into the Send feedback with the other attachments' annotations. PDFs and files take none (422 annotation_not_allowed).
  • Two small seams in @plannotator/ui, defaults unchanged: AnnotationPanel emptyHint, and CodeFileView allowImages / lang. One fix that also reaches plan review's code popout: [data-code] { align-content: start }, so a short file's lines no longer stretch to fill the dialog height.

Not in this PR: Show in Finder (owner wants a mock first), a PDF viewer (download for now), a size cap.

Tests

  • packages/shared/inbox/attachments.test.ts: each kind from bytes, outside-project absolute path accepted, .env/.env.local/symlink to .env/folder/FIFO refused with nothing written, a 5 MB file streamed with the right hash, an image that stops being one reads as changed type.
  • packages/server/inbox-attachments-kinds.test.ts (real Inbox, MCP SDK, temp data dir): kinds and the outside path, headers per route and kind, 415s, cross-site 403s, 304, Content-Disposition encoding, image and code comments kept / PDF refused, markup removed with its thread, and the device door.
  • packages/inbox/attachmentKinds.test.tsx (DOM): image inline + tile thumbnail from the image route, PDF/file/unknown kind as Download links (sent version when the current is gone), the image pane, and the feedback text for an image comment with its markup and a code comment with its lines.
  • tests/e2e/inbox-attachments-kinds.spec.ts (Playwright, compiled binary, tailscale trapped): real Chromium screenshots attached (one from outside the project), images loaded inline and as thumbnails, PDF and zip downloads with their bytes, Mark up + comment, a code line comment, and the agent's wait_for_reply reading both.
  • bun run typecheck clean; full bun test green (one CI allowlist entry added for the new DOM test); inbox-attachments.spec.ts, surface.spec.ts, inbox-message-images.spec.ts pass on the compiled binary.

Screenshots (light and dark, 1440×900) were taken by the e2e spec: thread with images inline and as tiles, the image beside the thread, the image annotator, a comment with its markup, a selected comment showing its drawing, a code line comment, the reply with both annotations.

…s and files as downloads, comments on images and code

The owner's answers on the attachments design (2026-10-10): quality UX
first, no heavy guardrails, "make it very accessible and ergonomic for an
agent to point out a file so it shows".

- Any regular file the agent can read attaches, by an absolute path
  anywhere or one relative to project_path. Refused only: not a regular
  file (a folder says to attach its files or a zip), and the dotenv family.
  No size cap. Bytes stream through the hash into a temp blob, so no file
  is held in memory; the current file's hash is cached per stat.
- The kind is read from the bytes: image (sniffed magic bytes, SVG by its
  first element), pdf (%PDF-), code (any other UTF-8 text), file (the
  rest); documents keep their viewers while their bytes are text. Kinds
  are additive: every reader treats an unknown kind as file (download).
- Serving by id only: /image (re-sniffed type, image CSP, nosniff, CORP,
  ETag) for <img src>; /download for any kind (attachment disposition,
  application/pdf or octet-stream, sandbox CSP), streamed. Text routes
  refuse binary kinds. Cross-site requests refused before any read. The
  phone's door forwards to the same routes (one check, same headers).
- Window: a message's images show inline (a justified gallery) and as
  tiles with thumbnails; PDFs, files and unknown kinds are Download links;
  the image pane shows the image with a comment box and Mark up (ui's
  ImageAnnotator), whose drawing is kept under inbox/markups and rides the
  comment; code opens in ui's CodeFileView (CodeFilePopout's body, Pierre's
  File) with line and range comments. Both flow into the Send feedback.
- Phone surface: a plain card for image, pdf, file and unknown kinds.
- The agent guide, the MCP description, the skill and the docs say so.
…r, async reads)

- Relay: a result body over 3/4 of the 32 MiB frame is refused from its
  Content-Length before a byte is read; a body without a length is read
  through a reader that cancels once it passes the bound (readRelayBody).
- Text routes (/view, raw, and the phone's view) check the open handle's
  size first and answer 413 attachment_too_large over 16 MB; the pane shows
  its Download card. A text or code file over 16 MB attaches as `file`.
- An attached HTML page's folder (possibly a home folder): the Inbox's
  asset route refuses any `.`-prefixed segment and the dotenv family, as
  requested and by realpath, and nested documents get connect-src 'none'
  (opt-in options on createHtmlAssetRegistry; annotate unchanged).
- Hashing and reading are async (FileHandle, 1 MiB chunks); a send primes
  the current-file hash; listing hashes a changed file only up to 8 MB and
  judges a larger one by its stat. Text reads use the same O_NOFOLLOW |
  O_NONBLOCK handle checked by dev/ino.
- Dotenv rule matches annotate's: `(^|.)env`, `.envrc`, `.env.*` (not
  `.env.example`).
- Stale `.send.*.tmp` blobs are swept at start and on delete; a delete
  removes only the markups the deleted annotations named.
- Cross-site check on /view and /threads/:id/attachments; the door's
  allowlist comment says what it carries.
@backnotprop
backnotprop force-pushed the feat/inbox-attachments-v2 branch from d83d07f to 87d3894 Compare October 11, 2026 00:13
@backnotprop
backnotprop merged commit f742bd5 into main Oct 11, 2026
32 checks passed
@backnotprop
backnotprop deleted the feat/inbox-attachments-v2 branch October 11, 2026 00:44
backnotprop added a commit to leoreisdias/plannotator that referenced this pull request Oct 13, 2026
Resolves the conflicts with backnotprop#1834, which turned createHtmlAssetRegistry()
into createHtmlAssetRegistry(options): folderPath joins refuseAssetPath and
documentCsp in HtmlAssetRegistryOptions, annotate passes it only for
annotate-folder sessions, and main's boundPort / createAIRuntime lines are
kept.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant