Ticket #223: composer attachments — verification
- Date: 2026-11-10
- Branch:
ticket/223-attachments - Spec: parent #209; ticket #223
- Unit gate:
npm run verify(typecheck + full test suite)
Behavior
- A paste whose text is a single existing file path becomes an attachment chip.
- Absolute paths,
~paths,./and../paths, and quoted paths with spaces are recognized. - A
file://URL is accepted; ordinary web URLs and prose stay text. - A path that does not name an existing regular file falls through to the native textarea paste, so normal text is never captured.
- Absolute paths,
- A paste carrying clipboard image bytes is stored and attached. The composer prefers magic-byte detection, then the host paste metadata (
mimeType), and also accepts animage/*base64 data URI pasted as text. - The composer keeps pending attachments per conversation surface, renders them above the input, and removes the last one with Backspace on an empty draft or by clicking its chip.
- Sending works with text, attachments, or both. An attachment-only message stores an empty transcript text and a work title naming the attachment.
Store and caps
Files are copied into the conversation directory (never linked to the source):
<conversation directory>/.ensemble/attachments/<conversation-key>/
index.json # metadata descriptors only
<attachment-id>-<safe-name> # copied bytes, mode 0600- Group conversation key:
group:<workspaceID>under the workspace directory. - Workspace direct key:
direct:<agentID>:<workspaceID>under the workspace directory. - Home direct key:
direct:<agentID>under the agent home directory. - Conversation storage cap: 250 MB. The add is rejected before writing when the copied file would exceed it.
- Per-file cap: 10 MB.
- Per-message caps: 8 files and 25 MB total, checked by the composer before an add and re-checked by the service on send.
- Errors name the file, current size, and the limit, and say what to do next.
- Cleanup removes a conversation's directory when its workspace is deleted or Ensemble is reset; agent deletion removes that agent's direct directories. Removing a draft chip deletes its stored copy.
Prompt payload and transcript
The host prompt uses its declared file shape:
ts
{
uri: "file:///…/attachments/<conversation>/<id>-<name>",
name: "screenshot.png",
description: "image/png, 12.3 KB",
}uri is a store file URL. No bytes are inlined and no source path is used.
Durable messages, subtasks, and direct queue rows carry only:
ts
{ id, name, mime, size, kind }The transcript renders a chip line per attachment with the name, MIME, and a readable size. Host prompt files are mirrored through nativePromptAttachments(files), which deliberately drops uri, data, and any path so tickets #215/#216 can attach the same metadata to native turns.
Snapshot and logs
- The snapshot contains metadata descriptors only, in the same places as before (message rows, direct queue rows, subtasks).
- The service does not log attachment bytes, source paths, or store paths. The add result returns metadata only.
- Tests assert that a stored file's contents, its workspace directory, and the
.ensemble/attachmentspath never appear in the serialized snapshot.
Terminal-dependent behavior
Path paste is the reliable cross-terminal path: terminal paste carries text, so the composer resolves and copies the file itself.
Clipboard images depend on the terminal and host paste bridge:
- A terminal that forwards raw clipboard bytes with
mimeType: image/*or a recognizable PNG/JPEG/GIF/WebP/BMP signature is handled. - Most terminals only send text through bracketed paste. In those terminals, copy the image as a file path, or paste a base64
data:image/...URI. - OS drag/drop of arbitrary binary files is not promised. A future drop surface can reuse the same add/store path.
Tests
src/v2/attachments.test.ts— path paste, clipboard bytes/data URI, metadata-only store, per-file/per-message caps, store bound, prompt file payload, native prompt mirroring, chip labels, cleanup, id resolution, and per-conversation drafts.src/v2/service.test.ts— direct prompt files, group prompt files, attachment-only clipboard image send, oversized/too-many rejection, snapshot metadata, and workspace-delete cleanup.src/v2/queue.test.ts— attachment ids distinguish otherwise-identical work without changing legacy keys.src/v2/tui/app-wiring.test.ts— paste seam, service add/remove, send payload, and transcript chip rendering are wired.
Conflict notes
- Direct-session selection (
ensureChatSession) is unchanged.chatSendgains attachment resolution after the existing target selection; ticket #214 is editing the same function, so that hunk is the merge-risk area. - Native ingestion (#215/#216) is untouched.
nativePromptAttachmentsis the metadata seam those tickets call when they copy inbox files to rows.