87 lines
5.2 KiB
Markdown
87 lines
5.2 KiB
Markdown
---
|
|
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. |