docs(research): plan first-class attachments

[AndrewBarba]

Summary

#4224 keeps attachment bytes out of session history, but the session sandbox is still the only store. Files can vanish when a snapshot changes, and every attachment boots a sandbox. The model also can't reopen a visible image by path, and one oversized image breaks every later call. This research plan proposes a pluggable attachment store with the sandbox as the default, so behavior without configuration does not change. Vercel Blob is opt-in. Two model-facing fixes ship first: path labels on every attachment and a pixel gate.

Related to #3833, #276, and #4194.

Scope decisions:

• Four fixes with direct user reports ship as separate PRs: fix(slack): collect thread attachments across recent messages instead of only the newest #706, fix(slack): drop external remote files from attachment collection #856, Cancelled turn with an attachment persists a raw eve-url: file part when the cancellation lands before the harness step starts; every later model call fails with AI_DownloadError #3419, and eveChannel: support fetchFile for URL file parts (large web uploads) #4194.
• Reads try the configured store first, then the sandbox. eve-sandbox: refs keep working, so live sessions keep their images.
• Built-in agent copies can read the parent's attachments, as they can today through the shared sandbox. Declared subagents stay isolated.
• Deferred, because there is no direct demand or a dependency is missing: outbound files, toModel, pending Slack files, model capability gating, and trace content.

The plan also compares the attachment handling in opencode v2, Codex, and pi. This PR adds only the plan. It changes no code.

Validation

• oxfmt --check research/first-class-attachments.md and git diff --check pass.
• I checked the plan's claims about current code against the source. A fresh-context review checked the plan end to end against eight scenarios, and this revision addresses its findings.
• Not applicable: tests and changeset, because this is a research document only.

Checklist

• This change was requested or approved by a maintainer
• I ran the relevant checks from CONTRIBUTING.md
• I added tests and documentation where relevant
• I added a changeset if this touches the published eve package
• DCO sign-off passes for every commit (git commit --signoff)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
eve-docs	Ready	Preview, v0	Oct 7, 2026 6:13pm UTC
eve-pkg	Ready	Preview, v0	Oct 7, 2026 6:13pm UTC

[chadhietala]

Is there anyway to pass by reference with some url? Just thinking through the implications of this for tracing.

[AndrewBarba]

Good question. d34ff90 adds a Tracing section with two answers:

• Traces: yes. With refs, model-call spans record the attachment descriptor instead of base64. A trace viewer opens the file through the session-authorized route GET /eve/v1/sessions/:id/attachments/:sha, so traces do not store a copy.
• Providers: no, for now. A signed store URL changes each time eve mints it. The same message then renders differently on each call, which breaks the prompt cache (see research/tool-result-media.md). Private URLs also fail when the provider fetches them (Slack channel: a Google Drive/Dropbox file linked in a thread crashes every later mention (AI_DownloadError: 401) #855). If payload size becomes a problem, provider Files API file_ids are the better option.

[AndrewBarba]

Superseded by #4625. That plan keeps today's sandbox storage and fixes the attachment pipeline without a new store primitive. The path labels, the inline gate, and PDFs in read_file from this plan carry over into that stack.