Skip to content

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.
  • 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 an image/* 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/attachments path 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. chatSend gains 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. nativePromptAttachments is the metadata seam those tickets call when they copy inbox files to rows.

Released under the MIT License.