# Thread: Matrix file ingestion and agent-visible storage contract

## Status: IN PROGRESS

## Goal

Сохранить текущий контекст сессии для следующего агента и зафиксировать следующую архитектурную развилку: как принимать вложения из Matrix и делать их доступными агенту.

## Current State

Phase 4 Matrix MVP уже собран и проверен на уровне per-room routing:
- обычные сообщения теперь идут в `platform_chat_id`, а не в общий локальный `C1/C2`
- `!context` показывает состояние текущего Matrix-чата
- `!save` и `!load` привязаны к текущему room-context
- `PrototypeStateStore` хранит live state per context
- последние изменения закоммичены в `feat/matrix-direct-agent-prototype`

Коммиты, которые важно знать:
- `c11c8ec` `feat(task-5): scope matrix context state per room`
- `07c5078` `feat(task-7): verify matrix per-room context routing`

## What We Learned About Platform Runtime

Текущий `external/platform-agent` не является отдельным контейнером на чат.
Фактическая модель сейчас такая:
- один FastAPI-процесс
- singleton `AgentService`
- `thread_id` используется как ключ памяти в LangGraph, а не как контейнерная изоляция
- файловой изоляции на чат сейчас нет
- `/workspace` как общий mount для Matrix bot и platform-agent сейчас не настроен
- отдельного upload API для вложений в текущем коде не видно

Ключевые файлы:
- `external/platform-agent/src/api/external.py`
- `external/platform-agent/src/agent/service.py`
- `external/platform-agent/src/agent/base.py`

## File Handling Requirement

Пользовательский запрос на текущем этапе:
- принимать файл или сообщение с файлом из Matrix
- сохранять файл локально
- передавать агенту явный сигнал, что к сообщению есть вложения
- сообщать, где лежит файл

Но есть техническое ограничение:
- если Matrix bot пишет файл только в своём контейнере, platform-agent его не увидит
- значит нужен либо общий storage, либо upload в платформу, либо контейнеризация platform-agent с общим volume

## Recommended Design Direction

Самый прагматичный MVP-вариант:
- хранить вложения в общем каталоге, который виден и Matrix bot, и platform-agent
- формировать для агента структурированный payload с:
  - локальным путём
  - original filename
  - mime type
  - attachment type
- если есть текст пользователя, дополнять сообщение краткой summary-подсказкой про вложения
- если прислан только файл, отправлять synthetic message вроде “пользователь прислал файл”

Если общий каталог невозможен в текущем runtime:
- следующий вариант это upload endpoint в platform-agent
- Matrix surface скачивает файл и загружает его в платформу, а платформа уже кладёт его в своё доступное хранилище

## Open Questions

1. Где должен жить shared storage: host path, docker volume или platform-side volume?
2. Нужен ли немедленный upload API в platform-agent, или сначала достаточно shared path?
3. Должны ли файлы быть scoped per room/platform_chat_id, а не per user?

## Next Step For Another Agent

1. Подтвердить runtime-модель хранения файлов.
2. Проверить, как сейчас запускаются Matrix bot и platform-agent в реальной dev-схеме.
3. После выбора storage contract начать с изменений в Matrix attachment ingestion.

## Notes

- Контекст этой сессии сохранён как отдельный thread, потому что текущий следующий рискованный шаг уже не про context routing, а про файловый transport.
- Не смешивать этот трек с незавершённой историей про `!branch`: upstream branch/snapshot API всё ещё не подтверждён.