surfaces/.planning/codebase/INTEGRATIONS.md

Интеграции (INTEGRATIONS.md)

Platform Agent API

• Тип: WebSocket (через AgentApi SDK)
• Назначение: Связь между Matrix-адаптером и внешней LLM-платформой.
• Контракт: Surface выступает "тупым" клиентом. Он отправляет platform_chat_id и user_id вместе с сообщениями. Платформа/Агент отвечает текстом и вложениями. Контейнерами агентов бот не управляет.

Matrix Homeserver

• Тип: HTTP/HTTPS API (via matrix-nio)
• Назначение: Пользовательский интерфейс и транспорт сообщений для бота.
• Ограничения: Поддерживается только нешифрованное (unencrypted) взаимодействие.

Файловая система (Shared Volume)

• Тип: Docker Shared Volume (/agents/)
• Назначение: Прямая передача файлов между поверхностью и агентами в обход сети. Поверхность пишет файлы в поддиректорию конкретного агента, агент их читает, и наоборот.