feat: Matrix Gateway integration for Rooms Layer
Matrix Gateway:
- Add POST /internal/matrix/room/join endpoint
- Add POST /internal/matrix/message/send endpoint
- Add GET /internal/matrix/rooms/{room_id}/messages endpoint
City Service:
- Add POST /rooms/sync/matrix endpoint for bulk sync
- Update get_agent_chat_room to auto-create Matrix rooms
- Update get_node_chat_room to auto-create Matrix rooms
- Update get_microdao_chat_room to auto-create Matrix rooms
- Add join_user_to_room, send_message_to_room, get_room_messages to matrix_client
- Add ensure_room_has_matrix helper function
This enables:
- Automatic Matrix room creation for all entity types
- chat_available = true when Matrix room exists
- Real-time messaging via Matrix
This commit is contained in:
Apple
269
docs/tasks/TASK_PHASE_MATRIX_GATEWAY_INTEGRATION_v1.md
Normal file
269
docs/tasks/TASK_PHASE_MATRIX_GATEWAY_INTEGRATION_v1.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 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`
|
||||
|
||||
Вхід:
|
||||
```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` для збереження в БД
|
||||
|
||||
2. `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)
|
||||
|
||||
3. `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. Сервіс-логіку синхронізації
|
||||
|
||||
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
|
||||
- повернути:
|
||||
```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
|
||||
|
||||
Після завершення:
|
||||
|
||||
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
|
||||
|
||||
```text
|
||||
Виконай 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
|
||||
|
||||
Reference in New Issue
Block a user