feat(web): attach PDFs, ZIPs, and other files to a turn

[t3dotgg]

The file upload APIs and tolerant attachment contracts from #8235 are now on main. This PR adds the web client for them.

The composer accepts PDFs, ZIPs, and other files up to the server's advertised limit through the paperclip button or paste. Uploads start while the user types, survive draft and stash moves, and render as rows that download with the original filename. Unknown attachment types render as inert rows instead of crashing the thread.

One shared upload flow in packages/client-runtime owns verification, transfer, release, and size limits. Draft discard, project delete, stash, file removal, and send cleanup all use that flow. Interrupted uploads return as "Attach again" markers instead of disappearing.

Release warning: clients with the old image-only attachment contract cannot decode threads that contain file attachments. The compatibility work in #8235 makes the merged server contract tolerant and keeps existing mobile code from treating files as images. Hold the web release until a compatible mobile build is available. #8237 adds mobile file support.

Original work by Theo Browne with Claude Fable 5 in the Claude Code harness. Modernized by GPT-5.6 Sol in the Codex harness.

---

Note

Medium Risk
Touches the turn send/upload pipeline and draft persistence; threads with file attachments require a tolerant client contract, so release coordination with older mobile builds matters.

Overview
Adds generic file attachments to the chat composer (paperclip, paste, drag) alongside images, with images and files sharing the per-turn attachment cap and server-advertised size limits.

Send and upload path: ChatView snapshots images and files together, runs shared upload/capability checks before and after upload, builds optimistic file rows, and wires timeline on-demand downloads via signed asset URLs. Annotation screenshots respect the combined attachment limit so prompts do not claim crops that were not sent.

Composer UX: ChatComposer stages file rows (upload progress, retry, “attach again” after interrupted uploads), blocks send when capabilities or limits fail, and extends stash restore/save to persisted file uploads with environment checks and expiry verification.

Persistence: composerDraftStore persists file metadata (upload ids or needs-reattach markers), enforces combined limits, and handles moves across threads/environments. Plan follow-up actions hide while any composer attachment is staged (shouldShowPlanFollowUpPrompt).

Timeline: User messages render non-image attachments as download links or inert rows for unknown types. Project/sidebar draft counts include files; project delete passes thread refs when releasing draft uploads.

^{Reviewed by Cursor Bugbot for commit 129f2ad. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add PDF, ZIP, and generic file attachment support to chat turns

• Extends the chat composer to support generic file attachments alongside images, including selection via paste or paperclip button, progress tracking, and retry controls
• Updates composerDraftStore, attachmentUploadQueue, and prompt stash store to persist file metadata, deduplicate attachments, manage upload lifecycles, and handle cross-environment moves
• Adds server capability checks to enforce staging limits and reject non-image files on servers that lack upload support
• Renders received file attachments in the timeline as downloadable links or buttons using generated signed URLs
• Risk: Non-image attachments now throw an error during send if the server does not support attachment uploads; cross-environment draft moves strip source upload linkage for byte-backed files

^{Macroscope summarized 129f2ad.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7697ac98-d68b-4b0a-aa8c-fb19042ba35d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.3 KiB	13.3 KiB	−29 B (−0.2%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	−6 B (−0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	−23 B (−0.3%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.6 KiB	55.6 KiB	−44 B (−0.1%)	66.4 KiB	✅
Codex	Live turn messages	11	10	−1 (−9.1%)	21	✅
Claude	Total thread wire	13.3 KiB	13.3 KiB	−56 B (−0.4%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	−1 B (−0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.4 KiB	6.4 KiB	−55 B (−0.8%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.4 KiB	56.4 KiB	−88 B (−0.2%)	66.4 KiB	✅
Claude	Live turn messages	11	9	−2 (−18.2%)	21	✅

Baseline: 0e2905e · PR result: 129f2ad · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Reviewed the new/changed Effect-adjacent code (packages/client-runtime/src/state/attachments.ts, apps/web/src/state/attachments.ts, and the web upload-queue call sites) against the service conventions. The new createAttachmentEnvironmentAtoms factory correctly mirrors createAssetEnvironmentAtoms (runtime passed in, no hidden globals, no ManagedRuntime/runPromise outside the existing atom-command boundary), and no service tags/layers were moved or redefined. One predicate convention issue below.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This change introduces a substantial production workflow for uploading, persisting, transferring, deleting, and downloading user files alongside turns. Its broad runtime surface and server-side file lifecycle warrant human review despite extensive tests and backward-compatible persistence.

^{You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

Reviewed the web composer/timeline attachment UI. Two interaction findings on changed lines, both about the new needs-reattach / capacity paths giving the user no working path or feedback.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding: the new file-attachment download button in MessagesTimeline renders its filename center-aligned, unlike the visually identical anchor and inert rows next to it.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding on the new send-block wording in ChatComposer. The rest of the attachment UI (file rows, paperclip trigger, stash menu file badge, timeline file rows) reuses the existing primitives and row treatments consistently, and the earlier findings on the timeline download row alignment, the marker re-pick path, and the swallowed paste are resolved.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

One finding: the needs-reattach file row label ignores the canReattachFiles guard that the send-block reason uses, so on a server without file-attachment support (or before the capability arrives) the row tells the user to attach again while no attach control is rendered.

^{Posted via Macroscope — UI Consistency}