IdeA/.ideai/tickets/154/carnet.md

issueRef, version, updatedBy, updatedAt

issueRef	version	updatedBy	updatedAt
#154	3	kind agent_id agent a6c6ea12-bfc6-4bdc-8031-324102dfa34d	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.