feat(desktop): attachments go where the workspace lives, as chat parts

Draft
SU
15d ago
+3135-764

Stacked. Draft until its dependencies are merged and released.

  • #8704: send attachments through storage, now including #8712's attachment.resolveEach. This branch merges #8704's head.
  • #8846 (plan PR 3) and #8849 (plan PR 4): the host store sweep and the adapter resolver. This branch is built on #8849's branch.

The base is main, so until those merge the diff includes them. This PR's own changes are commits 3767934b6d (code) and 0037f2f03c (the clipboard paragraph in docs/cloud-sandbox-mismatches.md). The plan's release order applies: the API (#8704) must be live in production before this ships (seam 5 calls attachment.resolveEach), and remote hosts and boxes get parts only from host 1.41.0 (the version gate below).

Summary

The desktop part of the attachments plan (v6): seams 1, 3 (with the version gate), 5 and 7. An attachment now lives where its workspace lives. In a cloud workspace it is a storage object named by fileId. In a workspace on a machine someone owns, it is a file in that host's store and never goes through our servers. Chat sends both kinds as attachment parts, not path tags.

Why

  • Since #8704, every desktop attachment goes through our storage, including those for a local or relay-reached host. That breaks the plan's goal 2: local images stay off our servers.
  • Chat flattened attachments into <attachment path> text tags, because two of the three adapters dropped parts. #8849 fixes the adapters. With tags, mobile shows a desktop attachment as raw text, and nothing without the box can render a cloud session's images.

How it works

  • Send (seam 1): utils/sendAttachmentsToWorkspace now exports sendAttachments, which picks the transfer from the workspace's home (useAttachmentHome: a box is cloud; a local or remote host is host).
    • cloud: attachment.createUpload → presigned PUT → cloudWorkspace.attachFiles. The part is { type: "attachment", fileId, name, mimeType, sizeBytes }, with no attachmentId.
    • host: base64 attachments.upload over loopback or the relay. The part is { attachmentId, … }, with no fileId.
    • A host workspace refuses a file over MAX_INLINE_ATTACHMENT_BYTES (25 MB) before anything is sent. The message tells the user to mention the file's path if it is on the workspace's machine. A cloud workspace keeps the 200 MB cap.
    • It sends attachments_sent / attachments_send_failed to PostHog with surface, home and host kind. Failures use rawErrorMessage.
  • Composer (seam 3): useUploadAttachments sends parts when hostReadsAttachmentParts(version) (from #8849, in @superset/shared/host-version, against ATTACHMENT_PARTS_MIN_HOST_VERSION). A local host is always this build, so it gets parts without a version check. A remote host or box reports its version through useHostServiceInfo. While the version is unknown, or below the floor, the composer sends path tags as before. An attachment-only message leaves out the empty text part (the Anthropic API rejects an empty text block; #8849 also drops one).
  • Render (seam 5): UserMessageRow renders image parts through AttachmentPartImage → useAttachmentSource. A cloud part resolves through attachment.resolveEach and a fetch from storage, with no box needed. The calls one render makes are batched into one resolveEach per 10 ids. A host part reads through attachments.read. The cache never goes stale and is dropped after an hour. A thumbnail over MAX_THUMBNAIL_BYTES, a missing file, or a failed read shows the name badge. primeAttachmentSource seeds the query with the File just sent, so the sent row does no read. Non-image parts stay name badges. Old transcripts with path tags render as before.
  • Paths (seam 7): sendAttachmentsToWorkspace (used by terminal paste and drop, the rich input, and the below-floor composer) now branches the same way. A host gets base64 filesystem.writeFile into .superset/attachments/ (create-only .gitignore, collision-probed names), which is the pre-#8704 path and is safe over the relay. A box keeps #8704's storage + materializeIntoWorkspace flow. The Files tab skips files over the inline cap with a toast and writes the rest. Design mode skips a screenshot over the cap and refuses context over it.
  • i18n: the limit messages are now Lingui messages (the #8704 versions were plain English), plus the new Files tab and design mode messages. I wrote the translations for all 16 locales.

Where this differs from the plan, or I left part of it out

  • The new-workspace modal's host branch (store.ts) and the CLI's cloud branch (lib/upload-attachments.ts) are not moved onto sendAttachments. The modal already uploads to the host, so moving it is a refactor with no behaviour change. The CLI is outside this desktop PR. The CLI still base64-uploads to a cloud box through the gate, which is the goal-3 path the plan wants closed. That needs its own PR.
  • The gallery overlay does not include part images yet. Path-tag images still open in it. Part images render as thumbnails without click-to-preview, because the gallery is keyed by worktree path.
  • No Sentry event from the renderer on a send failure, only PostHog. The host side reports resolve failures to Sentry (#8849).
  • The Files tab cap: the plan says "the shared per-file cap" for every host kind. I used MAX_INLINE_ATTACHMENT_BYTES (25 MB), because the bytes travel as one base64 body. This is a new limit for local Files tab drops too, which had no cap before. Please confirm, or I'll exempt local hosts.

tRPC compatibility

  • No procedure changes. New client calls: attachment.resolveEach (API, from #8704), and the host's attachments.upload / read / filesystem.writeFile, which exist on every supported host.
  • If resolveEach is missing (API not deployed), a cloud thumbnail falls back to a badge. A host below 1.41.0 never receives parts.

Testing

  • sendAttachmentsToWorkspace.test.ts (13 tests):
    • sendAttachments picks cloud or host from the home;
    • a cloud part has fileId and no attachmentId, and the files are anchored;
    • a host part has attachmentId, and storage is never called;
    • a host workspace refuses a file over the inline cap before any upload, and a cloud workspace takes that file;
    • onSent gets each part with its file;
    • naming, count and size limits;
    • a rejected PUT never anchors;
    • paths: a box materializes from storage, a host gets base64 writes into the worktree with a .gitignore, and an existing name gets a suffix.
  • attachmentSource.test.ts: a cloud part reads from storage and never the host; a host part reads from the host and never storage; a gone cloud file gives a badge; a primed row renders without any read; a render's resolves go out in one call.
  • hostReadsAttachmentParts and its test moved to #8849, so mobile can use it without this PR.
  • apps/desktop bun run typecheck passes. bun test in apps/desktop passes 8661 tests (0 fail). packages/shared and packages/i18n tests pass. bun run check:i18n passes (the catalog diff has only the new entries). Biome is clean.
  • Not verified: none of this ran in the Electron app; this sandbox has no Electron build (the native rebuild fails here). I did not do the plan's manual matrix: a pasted screenshot and a Finder drop into a local, a relay-reached and a cloud workspace, with Claude and Codex, checked on desktop and mobile, and after recreating the box. Please run it before taking this out of draft.

Known limitations

  • Remote hosts and boxes below 1.41.0 still get path tags. For a remote host, those tags now come from a direct worktree write, not storage, so the goal-2 exception the plan accepted for this window is gone.
  • A box that never cold-wakes stays below the floor and keeps path tags.
  • A host-session thumbnail goes back to a badge once the host's 30-day sweep removes the file (#8846).