File Attachment Handling#

File attachments in agent chat sessions are handled through a reference-based architecture implemented in Stage 1 of the Agent Multi-Modality project 1. The core design principle: upload once, reference always — messages and records carry an opaque server-issued attachment_id, never raw bytes or base64.

This contrasts with an earlier pattern where the front end re-sent the full message history (including embedded attachment bytes) on every turn, causing payload growth and repeated re-uploads 2.

Architecture Overview#

The four implementation layers are 3 4 5 6:

Upload Flow and Media Type Classification#

Multipart Upload#

Attachments are uploaded via POST /sessions/attachments before the message is sent 3. The flow is two-phase:

1. Pending — file bytes arrive via multipart upload; a record is created in pending state.
2. Ready — after the attachment is referenced in a message (POST /sessions/attachments/reference), it transitions to ready and becomes durable.

The frontend orchestrates this in useAttachmentUploads.ts and blocks the send button until all uploads settle 6. Upload errors are typed (cap exceeded, quota, invalid format, in-flight) with Retry-After support.

Byte Sniffing / Media Type Classification#

Server-side media type classification lives in api/oss/src/core/sessions/attachments/media.py 3. The client-supplied MIME type is never trusted — the server reads magic bytes from the file content to canonicalize the media type.

Known limitation: Upload-time byte sniffing cannot fully validate image integrity cheaply. A truncated PNG may still classify as image/png and pass upload, only to be rejected by the provider at inference time with a 400 invalid_request_error. The runner or frontend should map this class of provider error to a user-friendly message 7.

Quotas and Limits#

Per-session and per-kind limits are enforced in api/oss/src/core/sessions/attachments/dtos.py 3:

A background sweep task (attachment_sweep.py) reaps unclaimed files after 24 hours and stuck pending uploads after 15 minutes 3.

Storage: Immutable Originals and Working Copies#

Each attachment has two copies 1:

• Immutable original — stored in a dedicated session-scoped attachments mount, isolated from generic mount operations via the protected mount policy in api/oss/src/core/mounts/service.py. Backs model perception, download, inline rendering, and history reconstruction.
• Working copy — materialized at cwd/attachments/<attachment_id>/<filename> inside the agent's sandbox. The agent may read, edit, or delete it; it is re-materialized only when missing (never overwriting agent edits).

The attachment mount is deliberately hidden from generic mount APIs so clients cannot read, overwrite, or enumerate attachments through the general mounts surface 3.

Runner: Capability Gating and Delivery#

The runner (PR #5615) resolves attachment_id references into native ACP content blocks before passing a turn to the harness 4. Delivery is gated by three intersecting layers:

1. Protocol transport — does the wire protocol support this content type?
2. Adapter fidelity — does the harness adapter (e.g., claude-agent-acp, pi-acp) pass this block type through?
3. Model modalities — does the target model's capability set include this input type?

Capability metadata is resolved from the model catalog at the resolver boundary in sdks/python/agenta/sdk/agents/connections/resolver.py 5.

Key runner behaviors 4:

• Attachment-only turns (no text) are now valid — currentUserTurn(request) is the single authority on turn content.
• Every attachment gets a mention line in the prompt so a turn is never empty even if all blocks are gated.
• Delivery outcomes emit durable attachment_delivery events with stable reason codes recorded in transcript.ts.
• Graceful degradation on cold start: when a session must be rebuilt from records, each attachment is restored individually; missing files show as "no longer available" notices rather than failing the whole turn 4 2.

When a modality is unsupported (e.g., audio — blocked on adapter work), the file is attached as a workspace file with a visible notice; it is never silently dropped 1.

Frontend Transport and Rendering#

The frontend (PR #5619) sends zero base64 in messages 6. After upload, the composer assembles message parts with:

• A content URL pointing to GET /sessions/attachments/{id}/content
• Metadata carrying { attachmentId, size } (no bytes)

Key files:

• attachmentTransport.ts — upload via POST with axios progress tracking, idempotency key retry, and typed error taxonomy
• attachments.ts — builds reference-only message parts
• AgentConversation.tsx — renders from content route with authenticated blob fallback for reloaded conversations
• ComposerAttachments.tsx — progress/retry/dismiss UI

Paste and drag-to-attach paths are gated on the file-uploads feature flag (PR #5604) 8. Per-file named delivery notices render both live and on conversation replay.

Key Source Files#