feat(storage): define first-class attachment references for tools and artifacts

[alteixeira20]

Area

MCP

Problem or Motivation

Discussion #4806 asks whether chat uploads can be handed to MCP/custom tools as the original uploaded file.

This affects maker workflows, document/image conversion, MCP tools, custom tools, returned artifacts, and storage hygiene. Today, file-based tool workflows are harder to reason about if uploads are represented as inline payloads or local paths rather than first-class attachment references.

Tools should be able to work with original uploaded bytes when the user asks for that, but they should not casually receive arbitrary host filesystem paths or large inline base64 payloads.

Proposed Solution

Define a small first-class attachment/artifact contract for Odysseus.

The first version should aim for:

• original upload bytes are preserved once;
• every upload has a stable attachment ID;
• metadata is stored with the attachment: original filename, MIME type, size, checksum, owning message/session, and created time;
• the agent/tool layer receives attachment references, not inline base64 payloads;
• tools/MCP servers can request controlled read access to specific attachment IDs;
• generated files are returned as artifacts with IDs, metadata, MIME type, and preview/download handling;
• retention and deletion behavior is documented.

Suggested first implementation slice:

1. define the attachment metadata/reference shape;
2. ensure current-message uploads can be referenced by stable ID;
3. expose a read-only attachment lookup path to tools;
4. add one small proof case that reads an uploaded file and returns a derived artifact;
5. document lifecycle and permission boundaries.

Alternatives Considered

Passing raw local filesystem paths directly to tools would be simpler, but it couples tools to host/container path layout and risks exposing broader filesystem access than intended.

Inlining large base64 payloads into messages/tool calls is also undesirable because it increases DB size, prompt/tool payload size, and search-indexing risk.

Prior Art / Related Issues

Related discussions: #4806, #4762.

This also connects to storage hygiene because first-class attachment references would help avoid duplicating uploaded bytes in chat_messages.content.

Are you willing to implement this?

Partially — I can help but need guidance

[SamTanna]

I’m the user from discussion #4806, and I’d be glad to test the first implementation slice when it is ready.

A minimal acceptance test for my use case would be:

1. upload a small PNG or PDF in chat;
2. confirm it is stored once and represented by a stable attachment ID;
3. pass that attachment reference to a simple tool or MCP server;
4. have the tool read the original bytes;
5. return a derived file, such as a grayscale PNG or copied PDF;
6. display that output in the conversation as a downloadable artifact linked to the source attachment.

That would validate both sides of the proposal:

• avoiding large inline/base64 duplication in chat storage;
• enabling controlled file-based tool workflows.

I do not need host filesystem paths exposed directly. A controlled read endpoint or attachment lookup by ID would be preferable.

I’m not in a position to implement the feature, but I can provide test files, run a development build, and report exact results.

[alteixeira20]

@SamTanna, I'll try to implement this either today or tomorrow and ping you back for additional testing, thanks for the availability and contribution!