* feat(agent): read chat attachments on demand Agent turns pasted query-selected attachment excerpts into the prompt before the model could act. List stored files as a manifest so the agent can page and search them through read_attachment. * fix(agent): preserve attachment access and image reads * fix(agent): bound attachment cleanup and image processing * Remove standalone read_attachment tool * Read attachments and images through read_file Merge read_attachment into read_file (attachment:// paths, numbered document images, staged-copy aliasing, query search), return sandbox images as images, describe images for non-vision models inside the tool call with bounded concurrency and model-chosen detail/focus, render image reads in the UI, and record image metadata in Langfuse. * fix(agent): make attachment pagination complete and bound image reads * refactor(agent): separate attachment reads and cache image observations * fix(attachment): read image batches concurrently and harden description cache - ReadImages authorizes once and describes images in parallel - start VLM deadlines after a slot is held; longer timeout for full reads - detach shared description calls from the first caller's context - skip rewriting unchanged sandbox projections - strip the description cache from temporary document API responses - render upload text before calling the vision model * fix(attachment): number images in document order and polish attachment UI - return resolved images in document order instead of reverse - show attachment file names instead of attachment:// IDs in tool titles - use the shared file icon and a lighter card for chat attachments * fix(ci): renumber attachment migrations and satisfy lint Main already took sqlite 000035 and versioned 000116, so the attachment lookup indexes move to the next free numbers. Also wrap the ReadImages signature and drop an unused test parameter. * fix(ci): expect sqlite migrations to reach version 36 |
||
|---|---|---|
| .. | ||
| README.md | ||
| images.go | ||
| reader.go | ||
| reader_test.go | ||
README.md
Chat attachment boundaries
Attachments remain readable without a sandbox. Durable storage and the temporary-document row are authoritative; sandbox files are disposable copies.
| Responsibility | Owner |
|---|---|
| Upload, session access, retention, task scheduling | service/temporary_document.go |
| Parser, OCR, image extraction, chunking | service/temporary_document_parse.go |
| Quick Answer excerpts and Agent attachment manifest | service/temporary_document_prompt.go |
| Authorized reads, bounded parse waits | attachment/Reader |
| Image preparation, scoped observations and reuse | attachment/ImageReader |
| Observation persistence and concurrent updates | repository/attachment_descriptions.go |
| Turn-start original/parsed-file reconciliation | service/session_attachment_staging.go |
| Copies produced by a successful read | service/attachment_sandbox.go |
| URI routing, pagination, image numbering and tool output | agent/tools/read_file_attachment.go |
| Vision transport and fallback for other tools | agent/engine.go, agent/tool_images.go |
agent_attachments.go wires session-scoped storage adapters into Reader, then
passes only interfaces.AttachmentReader to read_file. The reader authorizes
against persisted message attachments before looking up the tenant's document,
including documents inherited from a parent session. Neither the tool nor the
Agent engine queries attachment repositories.
Read and synchronization flow
- At turn start, stage originals and already-ready parsed text if the selected sandbox supports session input files. Host workspaces have no input directory and are never used for attachment staging.
read_file attachment://...resolves the session attachment and waits within the configured parse budget. A successful read projects newly-ready parsed text immediately, including when parsing finished after turn-start staging.- Image reads default to one image with
briefplus an optionalfocus. The tool prompt reservesfullfor an explicit close-reading request; full reads return at most one image. Explicit brief batches are capped at four. - Non-vision chat models use the configured VLM. Successful observations are keyed by document, prepared-image hash, model ID and normalized reading prompt (including detail/focus). Equal requests reuse the observation across turns and authorized forks; different requirements do not reuse a narrower answer. Each new description has a 30-second deadline. Failed or empty descriptions are not cached, and the engine does not repeat an attempted description.
- The document metadata stores a bounded observation cache through optimistic updates that preserve parser metadata and concurrent writes. Cache entries inherit the document's deletion and retention rules. They are not merged into parsed Markdown or presented as exhaustive OCR.
- After an image read, copy the prepared image and any available observation to
<original>.assets/. Tool results expose the paths, and observations carry their source, detail, focus, model and timestamp. Normal turn-start staging preserves these files while the original belongs to the session. After a sandbox rebuild, the next read recreates copies from durable data/cache.
No sandbox is needed for steps 2–5. Projection failures are reported separately and do not turn a successful durable read into a failure. Native vision sends images directly to the chat model and copies the image if a sandbox is present; it does not perform an extra VLM call just to manufacture a cached observation.
The cache reuses observations for the same model ID and prompt, not arbitrary semantic similarity between focus strings. Raw VLM reasoning from a native vision response is not an attachment artifact. These boundaries keep cache scope explicit and avoid speculative re-reading of every extracted image.