feat(attachments): attachments go where the workspace lives (whole attachments plan; SUPER-3014, SUPER-2658, SUPER-2874)
This PR now carries the whole attachments plan
Attachments: durable for cloud sessions, local for local ones (v18). The plan's separate PRs are folded in here and closed. The checklist is in the tracking page.
| Was | What | Commit here |
|---|---|---|
| #8704 + #8712 | Send through storage, body buffering, scoped resolve + resolveEach, reap files with the box (seam 6) | already in this branch |
| #8846 | Host store: lastUsedAt, daily sweep, fileId index, fileId on first-prompt parts, limits in shared (seams 2, 3, 8) | 9c81d7e093 |
| #8849 | Claude image blocks, Codex localImage, one resolver (cache or import by fileId), name+path block, parts floor (seam 4) | f68cfaaff8, d0919441dd, 233498e0c6 |
| #8851 | Desktop: parts by workspace, version gate, thumbnails from storage or host, terminal paste on the same switch, caps (seams 1, 3, 5, 7) | cef20a0899, 5a646e8ff4 |
| #8852 | Mobile: cloud parts by fileId, host branch, cloud rendering, path tags as cards | f32821b95d |
| #8854 | Docs: a box's host-service is as new as its last boot | cb1e6f209a |
| — | Fold-in fixes (floor, Files tab, leftovers, translations) | 635f21d54b |
| — | Merge of main (#9246, agents.ts imports) | 4444ea9257 |
Decisions made while folding in (please check)
- Large files in a local workspace. The plan refuses anything over 25 MB in a host workspace. This PR's SUPER-3014 fix copies local files with no cap. Both are kept: a chat file up to
MAX_INLINE_ATTACHMENT_BYTES(25 MB) becomes an attachment part, and a bigger local file goes throughattachments.writeIntoWorktreeas a path tag, so the 451 MB.dmgstill works. A relay-reached host refuses files over 25 MB, as the plan says. - Routes: same machine → desktop main copies the files. Remote → base64
attachments.uploadfor parts, and base64filesystem.writeFileinto.paradev/attachmentsfor paths; no storage. Cloud → storage, thenfileIdparts ormaterializeIntoWorkspacefor paths. ATTACHMENT_PARTS_MIN_HOST_VERSION = "2.0.4". 2.0.0–2.0.3 shipped without the new adapters. If this PR doesn't ship in 2.0.4, raise it before release. A local host is this build, so it always gets parts.- Files tab cap (25 MB) applies only to a workspace on another machine. Local drops keep no cap.
- The parser moved to
@superset/chat/core(shared by desktop and mobile) and keeps this PR'sname="…"and both.paradev/.supersetprefixes.
Checks on 4444ea9257
- typecheck passes in shared, chat, chat-runtime, chat-ui, host-service, trpc, cli and desktop.
- mobile typecheck has 187 errors, all in the existing baseline. None are in the files this PR changes.
- bun test:
- shared 1537, chat 108, chat-runtime 440, chat-ui 75, trpc 835, i18n 169, mobile 256, desktop 9079: all pass.
- host-service: 2710 pass, 23 fail. The same 23 fail on
ae52b5f402without these commits:- 22
background-namingsession tests: "path traversal detected". They pass alone and depend on test order. - the environmental
health.checksandbox test.
- 22
check:i18n: nothing missing in 17 locales (Ukrainian added). Biome is clean on the changed files.
Not verified / not in this PR
- Not run in the app or on a simulator after folding in. The plan's manual matrix is still owed: local, relay-reached and cloud workspaces with Claude and Codex, desktop ↔ mobile images, and a recreated box.
- Plan items with no code yet:
- the durable event-log integration (waits for the store);
- web and shared views rendering cloud parts;
- the CLI's cloud branch (still base64 through the gate);
- mobile's home-screen new chat (uploads to storage when you attach);
- Sentry from the clients;
- part images in the desktop gallery overlay.
resolvable.integration.tsis a manual DB test, not run in CI.
What & why
Fixes SUPER-3014. Attaching a 451MB .dmg in a local workspace failed with "files over 50MB can't be sent to a remote workspace".
This PR includes #8704 (SUPER-2658, merged in as 913077170c). #8704 sends desktop attachments through storage (createUpload → presigned PUT to R2 → attachFiles for cloud → materializeIntoWorkspace), which fixes the cloud-box ingress race. As written, it also sent local workspaces' attachments through our storage, and it refused files over 200MB.
On top of #8704:
- A local workspace never uses storage. When
useWorkspaceHostTargetsays the workspace is on this machine (localorlocal-starting), the new Electron main routeattachments.writeIntoWorktreewrites every file into.superset/attachments:- A file with a disk path (drag, picker, Finder copy) is copied with
COPYFILE_EXCL. There is no size cap, and the file never passes through renderer memory. - A clipboard blob (a pasted screenshot) is sent as base64 over IPC and written with
wx. It is capped atMAX_ATTACHMENT_BYTES. - Collisions get
_Nsuffixes, so the route never overwrites a file.
- A file with a disk path (drag, picker, Finder copy) is copied with
- A host target that is still resolving refuses the send ("Workspace is not ready") instead of falling through to storage.
- Remote and cloud workspaces keep #8704's storage route unchanged.
- Review fixes:
- The route validates every item before it writes anything, refuses UNC paths (an SMB/NTLM leak on Windows), and caps the base64 body.
- A path-count mismatch from the host or the route now throws instead of pairing a file with
"". ensureWorkspaceAttachmentsDirmoves to@superset/shared/workspace-attachments-dir, so the desktop and host-service share one.gitignorerule.
- Merge conflict:
cloud-workspace/reap.ts/reap.test.tskeep main's archive hook and #8704'sdetachAll+reapOrphanFiles.
After this, the only client that still sends a host workspace's files through storage is mobile (on main as well). The phone is never the host.
Against the attachments plan
The attachments plan:
- Goal 2: "local images stay off our servers". This PR meets it for every desktop surface.
- Seam 2: "a same-machine path import to get a local file past the inline cap" was dropped. This PR goes against that decision.
Attachment names and cards (f745e33547)
Problem: sent messages showed the sanitized disk name in a plain badge, e.g. Superset-arm64__21__1.dmg.
What changed:
- The
<attachment>tag now has an optional, escapedname="…"with the name the user attached. It is written only when that name differs from the disk name. - Every reader goes through
attachmentDisplayName: the message row, the image fallback, the gallery and the queued-prompt label. Tags written before this fall back to the disk name. - Files render as the composer's card (icon, name, type). It is extracted into
@superset/chat-ui/AttachmentFileCardand shared withAttachmentPills. - The name line drops the extension, because the type line shows it. Transcript cards size to the name (160–288px), so the message above reads Superset-arm64 (21) · DMG.
Compatibility: a desktop build without this change does not match a tag that has name=, so it shows such a message's tag as raw text. That is cosmetic only, because the agent reads the tag text either way.
Checked in the dev app:
- Sent
Superset-arm64 (21).dmgandmeeting notes (final).txt. The cards read "Superset-arm64 (21)" / DMG and "meeting notes (final)" / TXT, with the full name on hover. - Older messages show their disk names.
- The composer pill is unchanged apart from the extension moving to its type line.
Tests: desktop bun test 8872 pass. chat-ui tests and tsc pass. check:i18n leaves the catalogs unchanged.
Failed sends keep your files and say why (30bf515d86)
Problem: a failed chat send put the text back but dropped every attached file. A moved file showed a raw toast: ENOENT: no such file or directory, stat '…'.
What changed:
attachments.writeIntoWorktreenow returns{ ok: false, index, problem }when a source file ismissing, a folder (not-a-file) orunreadable. It checks readability by opening the file, because macOS privacy denials (EPERM) only show up atopen. It writes nothing in that case. A bad worktree and UNC paths still throw.sendAttachmentsToWorkspaceturns that result into anAttachmentSourceError.- The composer shows a translated message that names the file:
- "vanishing.txt" was moved or deleted. Attach it again.
- "My Folder" is a folder. Attach the files inside it instead.
- Paradev doesn't have permission to read "locked.txt".
- The composer re-adds every file except the bad one. Limit errors keep all files, so the user can remove some.
- Translations are written for all 16 locales.
check:i18nreports nothing missing.
Checked in the dev app:
- Attached
keep me.txtandvanishing.txt, deleted the second from disk, then sent. The friendly toast appeared, and the text andkeep me.txtcame back. Pressing Enter again sent it with no toast and no storage requests. - A folder and a
chmod 000file showed their messages.
Tests: route tests for each problem (nothing written), and a sendAttachmentsToWorkspace test for the error's index, name and problem. Desktop bun test 8874 pass.
How I tested it
End to end in the dev app. This was the cloud sandbox's dev stack, with the desktop restarted with RENDERER_REMOTE_DEBUG_PORT and driven over CDP.
- Setup: created a project and a local workspace on "This device". Turned the
acp-chatflag on through the renderer's PostHog client, as a setup override. - Journey: opened Chat and attached through the composer's real file input (
DOM.setFileInputFiles):- a 451MB
Superset-arm64 (21).dmg, the file from the report; notes.txt;- a PNG pasted from the system clipboard with Ctrl+V.
- a 451MB
- Result: typed a message and pressed send.
- No "Couldn't attach files" toast appeared, and the message rendered with the image thumbnail and both file badges.
- A fetch recorder in the renderer saw zero
createUpload/attachFiles/materializeIntoWorkspace/ R2 requests. - The worktree's
.superset/attachmentsholdsSuperset-arm64__21_.dmgandnotes.txt, both byte-identical to the sources (cmp), plusimage.png(64×64 PNG) and.gitignore(*).git statusin the worktree is clean. - Claude then answered "Authentication required", because the sandbox has no Claude login. That happens after the attachments were written.
Not checked in the app:
- The before state. I didn't run main's build to reproduce the toast.
- Remote and cloud workspaces. The dev stack has none, so their storage route is covered by unit tests only.
- Terminal rich input in a local workspace. It uses the same hook, but I didn't drive it.
Automated:
- Desktop
bun test: 8871 pass, 0 fail. It covers the new route tests (order, never overwrite, refuse a directory or UNC source before writing) and the newsendAttachmentsToWorkspacecases (same-machine send never touches storage and keeps the order of path, blob, path; blob cap; path-count mismatch throws). packages/trpc(752 pass) and the host-service attachment + chat-v3 suites pass.tscpasses in desktop, host-service and shared. Biome,check:i18nandsherifare clean.
Merge with main (71b7e89028, ae52b5f402)
71b7e89028 merges main at 9fca85d810. ae52b5f402 merges 7d6ec2de2f (#9265), with no conflicts, and formats attachmentTags.ts.
Conflicts and how they were resolved:
Composer.tsx: main's send path is kept (restoreDraft/prependToDraft, the hiddenchatContextpart, link chips). When a send fails, the composer restores the draft with only the attachments thatuseUploadAttachmentskeeps. The bad file is dropped, the other files stay, and theAttachmentSourceErrormessage shows.attachmentTags.test.ts: main'slegacyPastedMessagehelper and its.paradev+.supersetreader test are kept, together with this PR'sname=/attachmentDisplayNametest.attachmentTags.tsmerged cleanly: it reads both dirs and keeps the escapedname.uploadPastedFiles.ts(modify/delete): it stays deleted, and nothing imports it.TerminalPane.tsx: this PR'sAttachmentLimitErrorimport, plus main'sLinkActionMenu.- chat-ui
AttachmentPills.tsx: main'sRevealButtonandgroup/pill, rendered with this PR's sharedAttachmentFileCard. - host-service
chat-v3/agentImages.tsandtrpc/router/attachments/attachments.ts: these use the sharedensureWorkspaceAttachmentsDirinstead of main's localattachmentsDir. - i18n: the catalogs come from main and were regenerated. This PR's three attachment-error translations were copied back for every locale. Main added
uk, so I wrote Ukrainian translations for those three strings.
.paradev change: ensureWorkspaceAttachmentsDir now writes WORKSPACE_ATTACHMENTS_GITIGNORE. The Electron route attachments.writeIntoWorktree and host materializeIntoWorkspace already build paths from WORKSPACE_ATTACHMENTS_DIR, so they now write to .paradev/attachments. The sendAttachmentsToWorkspace test fixtures now use .paradev/attachments. Readers still accept .superset/attachments. A grep of this PR's diff against main finds no new .superset/attachments. The only "*\n" left is a test assertion on the .gitignore content, the same as main's agentImages.test.ts.
Checks run on ae52b5f402:
bun run typecheck: desktop, host-service, shared, trpc and chat-ui all pass.bun test:- desktop: 9074 pass, 0 fail.
- trpc: 835 pass, 0 fail.
- chat-ui: 75 pass, 0 fail.
- host-service: 2714 pass, 2 fail.
health.check … sandbox modeis environmental on a cloud box.pullRequests.mergePR > a failed refresh still reports the merge as donefailed once in the full run (called 2 times, expected 1). It passed 3 of 3 times on its own, and this PR does not change that directory.
bunx biome checkon the changed files: clean.bun run check:i18n: 0 missing in all 17 locales.
Not checked: I did not run the app after the merge. The new failed-send path through restoreDraft is covered by typecheck only. No test drives it, and I did not use it in the app.
Summary by CodeRabbit
-
New Features
- Upload files and clipboard attachments to local, remote, and cloud workspaces. Attachments are added to the workspace and referenced by workspace-relative paths.
- Terminal paste and file-drop uploads now use the same attachment flow.
- File attachments display clearer cards with filenames and file-type icons, and attachment names are preserved in chat.
-
Bug Fixes
- Improved handling of streamed requests so upload bodies are preserved.
- Improved feedback when attachment count or file-size limits are exceeded, or when a selected file is missing, is a folder, or cannot be read.