Affected by 
README
¶
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. Use completeattachment://<handle>/images/Naddresses, never bare/images/N. Exact chart/table values and calculations usefullwith a focused question; full reads return at most one image. Explicit brief batches are capped at four. Observations preserve category, series and unit alongside each value. Missing associations or inconsistent totals require a focused re-read, not guessed data. - 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. Descriptions have a 60-second deadline (150 seconds for full reads), starting after a model slot is acquired. 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.
Documentation
¶
Overview ¶
Package attachment owns session-authorized attachment reads. It has no agent, tool, database or sandbox dependency; adapters supply storage and projections.
Index ¶
- type Description
- type DescriptionCache
- type ImageReader
- type Projection
- type Reader
- func (r *Reader) List(ctx context.Context) ([]interfaces.AttachmentDocument, error)
- func (r *Reader) ReadImages(ctx context.Context, documentID string, numbers []int, detail, focus string) ([]interfaces.AttachmentImageRead, error)
- func (r *Reader) Resolve(ctx context.Context, ref string, wait bool) (*interfaces.AttachmentDocument, error)
- func (r *Reader) WaitTimeout() time.Duration
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Description ¶
type Description struct {
Text string `json:"text"`
Detail string `json:"detail"`
Focus string `json:"focus,omitempty"`
Model string `json:"model"`
CreatedAt time.Time `json:"created_at"`
}
Description records the scope of an observation; it is never merged into parsed document text or treated as a complete reading of the image.
type DescriptionCache ¶
type DescriptionCache interface {
Get(ctx context.Context, documentID, key string) (*Description, error)
Put(ctx context.Context, documentID, key string, value Description) error
}
DescriptionCache persists scoped observations alongside their owning document.
type ImageReader ¶
type ImageReader struct {
Model string
Describe func(context.Context, []byte, string) (string, error)
Cache DescriptionCache
// contains filtered or unexported fields
}
ImageReader describes requested images and reuses equivalent prior observations.
type Projection ¶
type Projection interface {
Document(context.Context, *types.TemporaryDocument) (string, error)
Image(
ctx context.Context, doc *types.TemporaryDocument, number int,
data []byte, mime, key string, description *Description,
) (map[string]string, error)
}
Projection is optional. The durable document and cache remain usable when the sandbox is absent, expires, or fails to accept a copy.
type Reader ¶
type Reader struct {
Images *ImageReader
Projection Projection
// contains filtered or unexported fields
}
Reader coordinates authorized attachment reads independently of tools and sandboxes.
func NewReader ¶
func NewReader(store Store, wait time.Duration, readImage func(context.Context, string) ([]byte, error)) *Reader
NewReader binds durable storage to one conversation and its parse wait budget.
func (*Reader) List ¶
func (r *Reader) List(ctx context.Context) ([]interfaces.AttachmentDocument, error)
List loads the authorized inventory once, then resolves each document without waiting or projecting files. Listing must not reload the message history per item.
func (*Reader) ReadImages ¶
func (r *Reader) ReadImages( ctx context.Context, documentID string, numbers []int, detail, focus string, ) ([]interfaces.AttachmentImageRead, error)
ReadImages authorizes the document once, then prepares, describes and projects the requested images concurrently.
func (*Reader) Resolve ¶
func (r *Reader) Resolve(ctx context.Context, ref string, wait bool) (*interfaces.AttachmentDocument, error)
Resolve opens a session attachment, optionally waiting for parsing and syncing its text.
func (*Reader) WaitTimeout ¶
WaitTimeout bounds parsing plus one image batch: the batch is described concurrently, with room for one queue round behind other reads.
Source Files