feat(attachments): attachments go where the workspace lives (whole attachments plan; SUPER-3014, SUPER-2658, SUPER-2874)

Merged
HA
15d ago
+4895-1007

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.

WasWhatCommit here
#8704 + #8712Send through storage, body buffering, scoped resolve + resolveEach, reap files with the box (seam 6)already in this branch
#8846Host store: lastUsedAt, daily sweep, fileId index, fileId on first-prompt parts, limits in shared (seams 2, 3, 8)9c81d7e093
#8849Claude image blocks, Codex localImage, one resolver (cache or import by fileId), name+path block, parts floor (seam 4)f68cfaaff8, d0919441dd, 233498e0c6
#8851Desktop: parts by workspace, version gate, thumbnails from storage or host, terminal paste on the same switch, caps (seams 1, 3, 5, 7)cef20a0899, 5a646e8ff4
#8852Mobile: cloud parts by fileId, host branch, cloud rendering, path tags as cardsf32821b95d
#8854Docs: a box's host-service is as new as its last bootcb1e6f209a
—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 through attachments.writeIntoWorktree as a path tag, so the 451 MB .dmg still 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.upload for parts, and base64 filesystem.writeFile into .paradev/attachments for paths; no storage. Cloud → storage, then fileId parts or materializeIntoWorkspace for 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's name="…" and both .paradev/.superset prefixes.

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 ae52b5f402 without these commits:
      • 22 background-naming session tests: "path traversal detected". They pass alone and depend on test order.
      • the environmental health.check sandbox test.
  • 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.ts is 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 useWorkspaceHostTarget says the workspace is on this machine (local or local-starting), the new Electron main route attachments.writeIntoWorktree writes 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 at MAX_ATTACHMENT_BYTES.
    • Collisions get _N suffixes, so the route never overwrites a file.
  • 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 "".
    • ensureWorkspaceAttachmentsDir moves to @superset/shared/workspace-attachments-dir, so the desktop and host-service share one .gitignore rule.
  • Merge conflict: cloud-workspace/reap.ts / reap.test.ts keep main's archive hook and #8704's detachAll + 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, escaped name="…" 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/AttachmentFileCard and shared with AttachmentPills.
  • 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).dmg and meeting 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.writeIntoWorktree now returns { ok: false, index, problem } when a source file is missing, a folder (not-a-file) or unreadable. It checks readability by opening the file, because macOS privacy denials (EPERM) only show up at open. It writes nothing in that case. A bad worktree and UNC paths still throw.
  • sendAttachmentsToWorkspace turns that result into an AttachmentSourceError.
  • 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:i18n reports nothing missing.

Checked in the dev app:

  • Attached keep me.txt and vanishing.txt, deleted the second from disk, then sent. The friendly toast appeared, and the text and keep me.txt came back. Pressing Enter again sent it with no toast and no storage requests.
  • A folder and a chmod 000 file 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-chat flag 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.
  • 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/attachments holds Superset-arm64__21_.dmg and notes.txt, both byte-identical to the sources (cmp), plus image.png (64×64 PNG) and .gitignore (*). git status in 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 new sendAttachmentsToWorkspace cases (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.
  • tsc passes in desktop, host-service and shared. Biome, check:i18n and sherif are 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 hidden chatContext part, link chips). When a send fails, the composer restores the draft with only the attachments that useUploadAttachments keeps. The bad file is dropped, the other files stay, and the AttachmentSourceError message shows.
  • attachmentTags.test.ts: main's legacyPastedMessage helper and its .paradev + .superset reader test are kept, together with this PR's name= / attachmentDisplayName test. attachmentTags.ts merged cleanly: it reads both dirs and keeps the escaped name.
  • uploadPastedFiles.ts (modify/delete): it stays deleted, and nothing imports it.
  • TerminalPane.tsx: this PR's AttachmentLimitError import, plus main's LinkActionMenu.
  • chat-ui AttachmentPills.tsx: main's RevealButton and group/pill, rendered with this PR's shared AttachmentFileCard.
  • host-service chat-v3/agentImages.ts and trpc/router/attachments/attachments.ts: these use the shared ensureWorkspaceAttachmentsDir instead of main's local attachmentsDir.
  • 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 mode is environmental on a cloud box. pullRequests.mergePR > a failed refresh still reports the merge as done failed 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 check on 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.