---
issueRef: "#154"
version: 3
updatedBy: {"kind":"agent","agent_id":"a6c6ea12-bfc6-4bdc-8031-324102dfa34d"}
updatedAt: 1786007117802
---
## Objective
Build a first-class attachment pipeline for agent-facing chat flows so files provided by the user are persisted, referenced, and made readable by agents without relying on prompt-text hacks.

## Why this exists
Current custom agent chat can only append a picked local path into the prompt text. That is not a robust attachment model and it does not guarantee that the target agent sandbox can read the file. Clipboard-paste support should not be built on top of this weak contract.

## Product target
Match as closely as reasonable the ergonomics of Codex / Claude Code style attachments while staying aligned with IdeA architecture:
- attachments are first-class entities, not just a string in the prompt;
- files are persisted in a stable host-controlled location;
- agents receive attachment context through an explicit contract;
- sandbox readability is guaranteed by construction for attached files;
- the model can support images first, then general files, without redesign.

## Non-goals
- No one-off frontend-only workaround that stores a browser blob URL or injects base64 into the prompt.
- No attachment flow that depends on the source file remaining at an arbitrary user path outside IdeA-managed storage.
- No design that works only for one provider/profile while breaking the abstraction for others.

## Expected architecture
A solid outcome should include the following, subject to Architect arbitration:
1. A durable attachment store owned by IdeA for agent/chat inputs.
2. A stable attachment identity and metadata contract (id, filename, mime, size, source kind, storage path, createdAt).
3. A transport contract from frontend to backend that sends structured attachment intent rather than only prompt text.
4. A backend/application path that materializes attachments into the attachment store and exposes them to the launched agent session.
5. A sandbox policy/story that makes attached files readable by the target agent without broadening access to arbitrary user filesystem paths.

## Storage / sandbox direction
Preferred direction:
- store agent-chat attachments under a project-owned IdeA path, for example `.ideai/attachments/agent-chat/...` or equivalent durable app-owned location that is intentionally mounted/readable for agent runs;
- if temporary staging is needed, staging must still end in a durable managed location before send;
- the chosen location must be easy to add to sandbox readable roots with minimal blast radius.

Important constraint:
- attached files should be readable even when the original source came from clipboard paste or from a user path outside the project root.

## UX contract this foundation should unlock
- picker-selected files become first-class attachments;
- clipboard-pasted images can use the exact same downstream attachment pipeline;
- future drag-and-drop can reuse the same contract;
- chat UI can display attachment chips/previews based on metadata instead of raw path strings.

## Suggested work split
### Architecture
- define ownership and location of the attachment store;
- decide whether the store is project-local vs app-data with projection into sandbox roots;
- define DTO/port contract for structured chat attachments;
- define lifecycle rules (persist until manually removed? per conversation? per turn?).

### Backend / app-tauri / application
- add write path for attachment creation/import;
- add any read-model or DTO needed by the custom chat flow;
- ensure structured launch / send path can pass attachment references to the session layer;
- ensure sandbox roots include the managed attachment location with least privilege.

### Frontend
- stop treating chat attachments as prompt suffix text;
- represent selected attachments as typed UI state;
- render chips/previews from metadata;
- call the new attachment APIs.

### QA
- verify picked file outside project root becomes readable by the agent through managed import;
- verify attachment survives send and session restart expectations defined by architecture;
- verify sandbox does not gain broad arbitrary read access.

## Acceptance criteria
- There is a first-class attachment contract for custom/structured agent chat.
- A user-selected file is imported into IdeA-managed storage before send.
- The target agent can read the attachment from within its sandbox without extra manual permission tweaking.
- The prompt path no longer relies on a brittle plain-text `[Fichier joint: ...]` suffix as the only attachment mechanism.
- The contract is reusable by clipboard image paste and future drag/drop.

## Risks to watch
- sandbox over-broadening to all of `$HOME` or arbitrary original source paths;
- provider-specific coupling that leaks one CLI's attachment semantics into the generic product contract;
- retention bloat if attachments are never garbage-collected;
- hidden duplication / large binary churn if images are copied repeatedly without lifecycle policy.

## Deliverable quality bar
This ticket is explicitly meant to prevent bricolage. If a proposed implementation cannot explain how attachment persistence, identity, routing, and sandbox readability work end-to-end, it is not sufficient.