Surfaces_team/surfaces
4
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions
surfaces/.planning/.continue-here.md
Mikhail Putilovskij 8ffbe7b6b3 wip: deployment architecture research — Phase 05 ready to plan 
- docs/deploy-architecture.md: full deployment topology, agent API, file transfer via shared volume
- .planning/HANDOFF.json + .continue-here.md: session state for Phase 05 planning
2026-04-27 21:46:27 +03:00

4.9 KiB
Raw Blame History

context phase task total_tasks status last_updated
pre-planning 05-deployment 0 0 ready-to-plan 2026-04-27T18:44:51.832Z

<current_state> Phase 04 полностью завершена и закоммичена на ветке feat/matrix-direct-agent-prototype (135 тестов зелёные). Этот сеанс был посвящён архитектуре деплоя — изучили платформенные репозитории и обсудили топологию с командой платформы. Вся информация о деплое зафиксирована в docs/deploy-architecture.md. Phase 05 не спланирована, следующий шаг — /gsd-plan-phase. </current_state>

<completed_work>

  • Изучены актуальные версии platform-agent, platform-agent_api, platform-master
  • Уточнена топология деплоя с платформой (схема с reverse proxy и shared volume)
  • Созданы docs/deploy-architecture.md — полное summary архитектуры деплоя </completed_work>

<remaining_work>

  • Смержить feat/matrix-direct-agent-prototype → main
  • Спланировать Phase 05 (деплой)
  • Выполнить Phase 05:
    • Обновить config/matrix-agents.yaml (добавить base_url, workspace_path, user_agents)
    • Обновить sdk/real.py (AgentApi конструктор, file transfer)
    • Обработка MsgEventSendFile в Matrix адаптере (скачать файл из volume, отправить пользователю)
    • Обработка входящих файлов от Matrix пользователей (сохранить в workspace, передать в attachments)
    • Написать docker-compose.yml для деплоя </remaining_work>

<decisions_made>

  • Топология: один инстанс Matrix-бота, один агент-контейнер на пользователя, reverse proxy на lambda.coredump.ru:7000 роутит по пути /agent_N/
  • Файлы: через shared volume /agents/. Surface пишет файл в /agents/{N}/, передаёт относительный путь в attachments=["file.txt"]. При MsgEventSendFile(path) — читает файл из /agents/{N}/{path} и шлёт в Matrix.
  • Agent API: используем master (attachments и MsgEventSendFile есть). Ветку #9-clientside-tool-call игнорируем — она в разработке и убирает нужные фичи.
  • Конфиг: два словаря — user_id → agent_id и agent_id → {base_url, workspace_path}
  • Master: не используем для MVP. Статический конфиг. При готовности Master — мигрируем.
  • chat_id: пока chat_id=0 (один контекст на пользователя) </decisions_made>
  • AGENT_ID + COMPOSIO_API_KEY: Composio смержен в main platform-agent, теперь обязателен. Значения нужны от Азамата перед деплоем.
  • agent_api #9: убирает attachments и MsgEventSendFile — если смержат до деплоя, сломает наш file transfer. Нужно уточнить сроки.

Required Reading (in order)

  1. docs/deploy-architecture.md — полная архитектура деплоя, топология, API, файловый обмен, конфиг
  2. adapter/matrix/routed_platform.py — текущий RoutedPlatformClient
  3. sdk/real.py — текущий AgentApi wrapper
  4. config/matrix-agents.yaml и config/matrix-agents.example.yaml — текущий формат конфига (нужно расширить)

Infrastructure State

  • Ветка: feat/matrix-direct-agent-prototype — готова к merge, 135 тестов зелёные
  • config/matrix-agents.yaml — незакоммичен (live config, добавить в .gitignore)
  • docs/deploy-architecture.md — незакоммичен (новый файл этого сеанса)
  • platform-agent main: Composio уже смержен (требует AGENT_ID, COMPOSIO_API_KEY в env)
Архитектура деплоя полностью прояснена. Нет неизвестных блокеров (кроме env-переменных от платформы). Phase 05 — чисто инженерная задача: обновить конфиг, sdk, Matrix адаптер, написать compose. Всё что нужно знать — в docs/deploy-architecture.md.

<next_action>

  1. /clear
  2. /gsd-resume-work — прочитает этот файл и предложит план Phase 05
  3. Прочитать docs/deploy-architecture.md
  4. /gsd-plan-phase 05 </next_action>