# 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