Files attached to a chat (spec §5.3, §9).

Like PhoenixKitAgent.Conversations, every function acts for a live browser session: the {session_token_uuid, user_uuid} reference and, in the options, impersonated: boolean (PhoenixKitAgent.Conversations has the checks that come first and their refusals: an impersonated or revoked session, a user without agent, a chat that is not the user's). The owner is the only one who adds a file to a chat, reads its row, discards it or is given the address of its bytes; an Owner or an Admin of the site is no exception here.

Adding a file

add/4 takes the file the Dock got from allow_upload (its temporary path and the name and type the browser gave), checks it, keeps it and starts its processing, and returns the row as pending. In order:

1. the chat is the session user's; the upload is a readable, non-empty file no larger than max_attachment_mb (the size is read from the file, not believed from the caller);
2. the content tells the kind (PhoenixKitAgent.Attachments.Detect): png/jpg/webp/heic, pdf, xlsx/csv, txt/md; anything else is :unsupported_type. A picture for a user whose model is not known to take images, while the module has no vision model to describe it, is :no_vision_model here, before anything is stored (see the processor);
3. the chat has room: no more than max_attachments_per_message files that are not part of a message yet (a failed one takes no room there), and the user has no more than unsent_files (Attachments.Bounds) files of any status waiting in all their chats that are not deleted — a failed one stays until it is discarded, and counts here. The count and the row are made under a lock on the chat, so parallel uploads cannot pass it;
4. the bytes are stored in the module's hidden Storage library, in the user's folder (PhoenixKitAgent.Library), uploaded by the user — a Manager with media.view_all neither sees nor reads them, and the permanent file token is refused; the file is not in Media. The same bytes of the same user are one Storage file, as in any library. Storage is given a neutral name for the file (the row keeps the user's), since Storage writes the name to its own log lines and job arguments;
5. PhoenixKitAgent.Attachments.Processor works on the file in a task.

add/4 writes to Storage and may take long: call it off the LiveView process. The row's status goes pending → ready | failed; when it does the chat's topic (PhoenixKitAgent.Conversations.topic/1) hears {:agent_attachment_processed, conversation_uuid, attachment_uuid}, and the listener reads the row with get/3. error of a failed row is a code (see the processor), never text of the file.

The row add/4 returns is pending as it was when processing started, and a small file can be processed — and its message sent — before the caller has that return value. So a listener must not let it replace a row it already read as ready or failed: after add/4 returns, read the row again with get/3 (or keep whichever of the two is settled).

Sending

A ready attachment that belongs to the user and to the chat is passed to PhoenixKitAgent.Turns.start/6 by uuid; the turn links it to the user message it stores. Its extracted text goes with the message and stays in the history, the attachments of one message sharing agent_history_chars between them; a picture's pixels go only in the turn of that message (and, for a model that sees, are not described afterwards: later turns carry a line that names the picture and the assistant's own answer). When the provider refuses the first model call of a turn that carries pictures, the turn takes its files off the message again (PhoenixKitAgent.Turns.Runner) — only a refusal of the request itself (400, 413, 415, 422), not a missing model or a failure of the provider. So does a turn whose model is no longer known to take images: the pixels are not sent, the model is not called, and a notice (pictures_not_seen) says to attach the files again, to be described. After a turn has ended, list_unsent/3 is the list to show.

The bytes

Nobody but the owner gets at them, and only through url/3: an expiring address of the file in Storage, minted for the session's own scope.

Refusals

Those of PhoenixKitAgent.Conversations, and :file_unreadable, :empty_file, :too_large, :unsupported_type, :unsupported_encoding (a text, CSV or Markdown file that is not UTF-8: save it as UTF-8), :no_vision_model, :too_many, :storage_unavailable, :already_sent.

A row that is still pending after the processing deadline and a margin (the node was restarted, the task was lost) is settled as failed/timeout the next time the user's rows are read, so it neither blocks a message nor holds a place; the Dock offers to discard it like any failed one.