Presence¶

Version: 2.0 Status: Ready Priority: Critical (Live Chat & Presence)

1. Поточний стан (вихідні дані)¶

Вже виконано у попередніх фазах:

Matrix Gateway:
✅ POST /internal/matrix/room/join
✅ POST /internal/matrix/message/send
✅ GET /internal/matrix/rooms/{id}/messages
City Service:
✅ Matrix-клієнт (join, send, get messages)
✅ ensure_room_has_matrix()
✅ POST /city/rooms/sync/matrix — bulk sync
Auto-create Matrix Rooms:
✅ agent chat rooms (частково)
✅ node support rooms (NODE1, NODE2)
✅ microDAO lobby rooms (DAARION)
Frontend:
✅ AgentChatWidget на /agents/:agentId, /nodes/:nodeId, /microdao/:slug
✅ Відображає "Увійти щоб почати спілкування" для неавторизованих

Обмеження зараз:

частина кімнат має matrix_room_id = NULL через rate limiting Synapse
не всі агенти додані в кімнати
чат-виджет працює лише як оболонка (немає повного send/receive циклу)
presence (online/offline) не реалізовано

2. Мета TASK_PHASE_MATRIX_FINALIZE_v2¶

Завершити інтеграцію Matrix так, щоб:

Усі кімнати (City, MicroDAO, Node, Agent) мали валідний matrix_room_id.
Усі потрібні агенти були учасниками своїх кімнат.
Message flow працював end-to-end:
frontend → city-service → gateway → Matrix → gateway → city-service → frontend.
Chat widget показував реальні повідомлення (історія + нові).
Presence (online/offline) відображався для агентів.
chat_available = true там, де Matrix-кімната та gateway працюють.

3. Scope (модулі та компоненти)¶

Цей таск включає:

Synapse (Matrix Homeserver) — налаштування rate limits.
Matrix Gateway — доопрацювання endpoint'ів та presence.
City Service — покращення room sync + чат API.
Frontend (Next.js) — повна інтеграція чат-виджета з Matrix.
Smoke-тести та короткий звіт.

4. Модуль 1 — Synapse (Matrix HS) Rate Limits¶

4.1. Завдання¶

Відкрити конфігурацію Synapse (homeserver.yaml або еквівалент).
Підняти або вимкнути rate limiting для:
room creation (createRoom)
room join
message send
Увімкнути/перевірити:
/versions
/presence (якщо потрібно окремо)

4.2. Орієнтовні параметри¶

(Конкретні значення — на розсуд Cursor, але ціль — щоб sync 20–30 кімнат проходив без помилок.)

# homeserver.yaml
rc_message:
  per_second: 100
  burst_count: 500

rc_joins:
  local:
    per_second: 50
    burst_count: 100
  remote:
    per_second: 10
    burst_count: 20

rc_login:
  address:
    per_second: 10
    burst_count: 50
  account:
    per_second: 10
    burst_count: 50

rc_admin_redaction:
  per_second: 100
  burst_count: 500

4.3. Acceptance¶

Повторний виклик POST /city/rooms/sync/matrix не падає по rate limit.
Всі кімнати з rooms отримали matrix_room_id.

5. Модуль 2 — Повна синхронізація кімнат¶

5.1. City Rooms¶

Для кожної city-кімнати (rooms.scope = 'city'):
якщо matrix_room_id IS NULL → створити через gateway (room/create або існуючу логіку).
оновити rooms.matrix_room_id.
додати системних агентів:
- DARIO, DARIA, DAARWIZZ
- інші public-агенти за потреби.

5.2. MicroDAO Rooms¶

Для кожного microDAO:
lobby, governance, news, builders, help (згідно Rooms_Layer_Architecture_v1).
створити Matrix-кімнати, якщо ще не створені.
orchestrator-агент має бути учасником lobby + governance.
core-team агенти — учасники builders/news (якщо такі задані).

5.3. Node Support Rooms¶

Для кожної ноди:
кімната node-{slug}-support.
додати:
- Node Guardian
- Node Steward
- (опційно) технічні агенти ноди (Pulse, Atomis, GuardianOS тощо).

5.4. Agent Direct Rooms¶

Для кожного агента:
створити або пересвідчитись в існуванні агенто-специфічної кімнати.
агент повинен бути учасником.
ця кімната використовується для direct-chat з агентом.

5.5. Acceptance¶

Усі записи rooms мають заповнений matrix_room_id для:
scope in ('city', 'microdao', 'node', 'agent').
Для кожного public-агента існує принаймні одна кімната, де він учасник.

6. Модуль 3 — Message Flow (send/receive)¶

6.1. Backend (city-service)¶

Переконатись/додати:

API для надсилання повідомлень від імені користувача/агента:
POST /api/v1/chat/rooms/{room_id}/messages
- вхід: { "body": "text" }
- діє:
- перевіряє, які Matrix credentials використовувати (service user або impersonation)
- викликає matrix-gateway /internal/matrix/message/send.
API для отримання історії:
GET /api/v1/chat/rooms/{room_id}/messages?limit=50
повертає список повідомлень (час, автор, текст).

За потреби використати існуючий get_room_messages() у city-service.

6.2. Gateway¶

Гарантувати:
правильне формування body для Matrix send (m.room.message, msgtype: m.text).
розбір GET /internal/matrix/rooms/{id}/messages для history.

6.3. Acceptance¶

Через API (curl/Postman) можливо:
надіслати повідомлення у кімнату.
прочитати історію.
Це працює хоча б для:
agent room (DAARWIZZ),
node support room (NODE1),
DAARION microDAO lobby.

7. Модуль 4 — Presence (online/offline)¶

7.1. Gateway¶

Реалізувати простий Presence Poller:
періодично опитувати Matrix API (presence endpoints або sync).
зберігати стан online/away/offline для Matrix user IDs агентів.
Надати internal endpoint:
GET /internal/matrix/presence/{matrix_user_id} → { "state": "online" | "offline" | "unavailable" }.

7.2. City-Service¶

Додати endpoint:
GET /api/v1/agents/{agent_id}/presence
- мапить agent_id → matrix_user_id → викликає gateway → повертає presence.
(Опційно) кешувати presence у пам'яті на 15–60 секунд.

7.3. Frontend¶

На сторінках:
/agents
/agents/:agentId
/nodes/:nodeId (для Guardian/Steward)
/microdao/:slug (для orchestrator)

Показати:

зелена точка — online
жовта — away/degraded
сіра — offline/unknown

7.4. Acceptance¶

Presence-індикатори відображаються в UI.
Відповідають реальному status (принаймні для test users/agents).

8.1. AgentChatWidget (Next.js)¶

Розширити:

Додавання станів:
loading
no_room
chat_available
auth_required
Для chat_available = true:
при відкритті:
- GET /api/v1/chat/rooms/{room_id}/messages?limit=N — завантажити історію.
при відправці:
- POST /api/v1/chat/rooms/{room_id}/messages — надіслати.
відображати список повідомлень (без fancy UI, MVP-стиль).
Для неавторизованих:
показати CTA "Увійти, щоб продовжити спілкування".

8.2. Інтеграція за контекстами¶

Для /agents/:agentId:
кімната агента (direct)
Для /nodes/:nodeId:
node support room
Для /microdao/:slug:
microDAO lobby room

8.3. Acceptance¶

На кожній із трьох сторінок можливий діалог:
відправити повідомлення,
бачити історію,
не отримувати помилки 4xx/5xx (за нормальних умов).

9. Smoke-тести (обов'язкові)¶

DAARWIZZ Chat
Відкрити /agents/daarwizz.
Відкрити чат.
Написати повідомлення.
Переконатися, що воно з'являється в історії.
NODE1 Guardian Chat
Відкрити /nodes/node-1-hetzner-gex44.
Відкрити чат.
Написати повідомлення.
Переконатися, що воно доходить до Matrix.
DAARION MicroDAO Chat
Відкрити /microdao/daarion.
Переконатися, що кімната існує, є історія, можна написати повідомлення.
Presence
На /agents бачити індикатор присутності (хоча б у базовій формі).
Змінити стан в Matrix (якщо можливо) та перевірити оновлення.

10. Вихідні артефакти¶

Після виконання таска Cursor має створити:

docs/debug/matrix_finalize_v2_report_<DATE>.md Зміст:
перелік створених Matrix кімнат;
список agent rooms, node rooms, microDAO rooms;
приклади presence-станів;
приклад message flow (request/response);
скріншоти або опис перевірених UI-сторінок.

11. PROMPT ДЛЯ CURSOR¶

Рекомендований текст:

Виконай, будь ласка,
docs/tasks/TASK_PHASE_MATRIX_FINALIZE_v2.md
у повному обсязі.
Зосередься на:
– Synapse rate limits,
– повній синхронізації Matrix rooms,
– message send/receive,
– presence,
– інтеграції AgentChatWidget з реальними повідомленнями.

Після завершення створи файл
docs/debug/matrix_finalize_v2_report_<DATE>.md
з результатами smoke-тестів та фактами реалізації.

Target Date: Immediate Priority: Critical Dependencies: Matrix Gateway running, Synapse accessible