surfaces/.planning/threads/matrix-file-ingestion-context.md

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 всё ещё не подтверждён.