Skip to content

# 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` для збереження в БД

1. `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)

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

1. Авто-виклик:
2. опційно: при створенні нової кімнати (event-based)
3. але для 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. список кімнат завантажується у режимі "Мапа" і "Список".
4. `/agents/daarwizz`:
5. чат-виджет відкривається,
6. можна надіслати повідомлення,
7. у Matrix-клієнті видно це повідомлення.
8. `/nodes/node-1-hetzner-gex44`:
9. чат з guardian/steward доступний.
10. `/microdao/daarion`:
11. чат 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