microdao-daarion/docs/tasks/TASK_PHASE_MATRIX_GATEWAY_INTEGRATION_v1.md

TASK_PHASE_MATRIX_GATEWAY_INTEGRATION_v1

Version: 1.0 Status: Ready Priority: Critical (Rooms & Chat Layer)

---

1. МЕТА

Повністю інтегрувати Matrix у DAARION.city так, щоб:

• усі кімнати (City / MicroDAO / Node / Agent) мали matrix_room_id;
• gateway умів створювати кімнати та додавати агентів;
• чат-виджети на /agents /nodes /microdao працювали з реальними повідомленнями;
• з'явилися online-статуси та події для Agent Presence.

Цей таск спирається на вже виконаний:

• TASK_PHASE_ROOMS_LAYER_RESTORE_AND_MATRIX_INTEGRATION.md (rooms seeded у БД, citizens працюють, але Matrix ще не прив'язаний).

---

2. ОБСЯГ РОБОТ (SCOPE)

1. Matrix Room Creation API у matrix-gateway
2. Room ↔ Matrix синхронізація у city-service
3. Agent / Node / MicroDAO join-логіка через gateway
4. Message flow: frontend → city-service → gateway → Matrix → back
5. Статуси чату: chat_available, online/offline
6. Мінімальні тести + smoke-перевірки

---

3. ВИМОГИ ТА ІНВАРІАНТИ

3.1. Для кожної кімнати в rooms:

• rooms.id існує
• rooms.matrix_room_id НЕ NULL
• запис у matrix_rooms з посиланням на Matrix room

3.2. Для кожного публічного агента:

• є хоча б одна кімната, де агент учасник (через room_agents або аналог)
• чат-виджет показує chat_available = true (якщо Matrix OK)

3.3. Для кожної ноди:

• є support room node-{slug}-support
• у ній учасники: guardian + steward + технічні агенти

---

4. МОДУЛЬ 1 — MATRIX-GATEWAY

4.1. Нові endpoints (internal)

У сервісі matrix-gateway (Python/FastAPI або Node, залежно від репо):

1. POST /internal/matrix/room/create

   Вхід:

   {
     "room_alias": "string",      // наприклад "city-general"
     "room_name": "string",       // "General"
     "visibility": "public|private",
     "topic": "string|null"
   }
   

   Вихід:

   {
     "room_id": "!abcdefg:matrix.daarion.city",
     "room_alias": "#city-general:matrix.daarion.city"
   }
   

   Дії:

   • викликає Matrix API /_matrix/client/v3/createRoom
   • задає canonical alias, name, topic
   • повертає room_id для збереження в БД

2. POST /internal/matrix/room/join

   Вхід:

   {
     "room_id": "!room:matrix.daarion.city",
     "user_id": "@agent_daarwizz:matrix.daarion.city"
   }
   

   Дії:

   • викликає Matrix API join для user_id
   • обробляє помилки (already joined / banned / unknown)

3. POST /internal/matrix/message/send

   Вхід:

   {
     "room_id": "!room:matrix.daarion.city",
     "sender": "@agent_x:matrix.daarion.city",
     "body": "string"
   }
   

   Дії:

   • відправляє текстове повідомлення від імені бота/агента
   • повертає event_id

4.2. Конфігурація

• додати ENV:

  • MATRIX_HOMESERVER_URL
  • MATRIX_ACCESS_TOKEN (service/bot user)
  • MATRIX_DEFAULT_SENDER (наприклад, @daarion-bot:matrix.daarion.city)

• healthcheck:

  • GET /health → перевірка /versions на Matrix HS

---

5. МОДУЛЬ 2 — CITY-SERVICE (ROOM SYNC)

У services/city-service додати:

5.1. Repository-логіку

• новий модуль, наприклад repo_rooms_matrix.py:
  • get_rooms_without_matrix_id()
  • update_room_matrix_id(room_id, matrix_room_id)
  • get_agent_matrix_user(agent_id)
  • get_node_guardian_and_steward(node_id)

5.2. Сервіс-логіку синхронізації

1. POST /api/v1/rooms/sync/matrix

   Задача:

   • знайти всі кімнати, де matrix_room_id IS NULL
   • викликати matrix-gateway /room/create
   • зберегти matrix_room_id
   • (для city/microdao rooms) додати публічних агентів як учасників:
     • City: DARIO, DARIA, Atlas, Greeter
     • MicroDAO: orchestrator + core team
     • Node: guardian + steward
     • Agent: сам агент

2. Авто-виклик:

   • опційно: при створенні нової кімнати (event-based)
   • але для MVP достатньо ручного endpoint + одноразового запуску

---

6. МОДУЛЬ 3 — AGENT CHAT FLOW

6.1. Backend API

У city-service:

• GET /api/v1/agents/{agent_id}/chat-room

  Доповнити:

  • якщо matrix_room_id IS NULL → створити кімнату через gateway
  • повернути:

    {
      "room_id": "<uuid>",
      "matrix_room_id": "!room:matrix...",
      "agent_id": "<uuid>",
      "chat_available": true|false
    }
    

• опційно: POST /api/v1/agents/{agent_id}/message (для проксінгу повідомлень з frontend до gateway)

6.2. Frontend (apps/web)

Компонент AgentChatWidget:

• якщо chat_available === false → показувати "тимчасово недоступний"
• якщо chat_available === true:
  • використовувати Matrix JS SDK АБО власний lightweight client:
    • GET /api/v1/agents/{id}/chat-room
    • WS або long-poll на gateway
    • POST /internal/matrix/message/send через city-service

Для MVP можна обмежитись:

• односторонній відправлення повідомлень (log history локально)
• завантаження останніх N повідомлень із Matrix через gateway

---

7. МОДУЛЬ 4 — NODE / MICRODAO CHAT FLOW

Аналогічно до агента:

• GET /api/v1/nodes/{node_id}/chat-room
• GET /api/v1/microdaos/{slug}/chat-room

Логіка:

• якщо нема Matrix room → створити
• додати відповідних агентів:
  • Node: guardian + steward
  • MicroDAO: orchestrator + core team

Frontend вже має AgentChatWidget, достатньо змінити пропси:

• entityType: "agent" | "node" | "microdao"
• entityId / slug

---

8. MESSAGE FLOW & NATS (опціонально)

Якщо є час у межах таска:

• matrix-gateway → NATS subject integration.matrix.message
• city-service підписаний і логує event_outbox
• Agents можуть реагувати на події.

Якщо ні — відкласти у окремий таск.

---

9. TESTS / SMOKE CHECKLIST

Після завершення:

1. POST /api/v1/rooms/sync/matrix → всі rooms.matrix_room_id заповнені.
2. GET /city:
   • список кімнат завантажується у режимі "Мапа" і "Список".
3. /agents/daarwizz:
   • чат-виджет відкривається,
   • можна надіслати повідомлення,
   • у Matrix-клієнті видно це повідомлення.
4. /nodes/node-1-hetzner-gex44:
   • чат з guardian/steward доступний.
5. /microdao/daarion:
   • чат MicroDAO працює.

---

10. PROMPT ДЛЯ CURSOR

Виконай TASK_PHASE_MATRIX_GATEWAY_INTEGRATION_v1.md.

Фокус:
1) matrix-gateway (internal API: room/create, room/join, message/send)
2) city-service (room sync, agent/node/microdao chat-room API)
3) apps/web (AgentChatWidget інтеграція з Matrix)
4) мінімальний smoke-тест, як описано в розділі 9.

Використовуй існуючі foundation-документи у docs/foundation/ як джерело істини.
Після кожного завершеного модуля роби окремий git commit.
Не змінюй інші підсистеми, які не стосуються Rooms/Matrix/Chat.

---

Target Date: Immediate Priority: Critical Dependencies: Rooms Layer seeded, Matrix Synapse running