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)¶

Matrix Room Creation API у matrix-gateway
Room ↔ Matrix синхронізація у city-service
Agent / Node / MicroDAO join-логіка через gateway
Message flow: frontend → city-service → gateway → Matrix → back
Статуси чату: chat_available, online/offline
Мінімальні тести + 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, залежно від репо):

POST /internal/matrix/room/create

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

Вихід: json { "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 для збереження в БД

POST /internal/matrix/room/join

Вхід: json { "room_id": "!room:matrix.daarion.city", "user_id": "@agent_daarwizz:matrix.daarion.city" }

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

POST /internal/matrix/message/send

Вхід: json { "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. Сервіс-логіку синхронізації¶

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: сам агент

Авто-виклик:
опційно: при створенні нової кімнати (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 - повернути: json { "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¶

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

POST /api/v1/rooms/sync/matrix → всі rooms.matrix_room_id заповнені.
GET /city:
список кімнат завантажується у режимі "Мапа" і "Список".
/agents/daarwizz:
чат-виджет відкривається,
можна надіслати повідомлення,
у Matrix-клієнті видно це повідомлення.
/nodes/node-1-hetzner-gex44:
чат з guardian/steward доступний.
/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