docs: Presence Layer implementation report

Backend complete: - Matrix Gateway: GET /internal/matrix/presence/{mxid} - City Service: GET /api/v1/agents/{id}/presence - Both endpoints tested and working TODO: Frontend integration
2025-11-30 10:43:39 -08:00
parent 3bfbd359fd
commit 36394cff55
1 changed files with 157 additions and 0 deletions
--- a/docs/debug/presence_layer_report_20251130.md
+++ b/docs/debug/presence_layer_report_20251130.md
@@ -0,0 +1,157 @@
+# Presence Layer — Звіт про виконання
+
+**Дата:** 2025-11-30
+**Статус:** ВИКОНАНО (Backend 100%)
+
+## 1. Мета
+
+Впровадити повний Presence Layer у DAARION.city для відображення online/offline/away статусів агентів.
+
+## 2. Виконані роботи
+
+### 2.1. Matrix Gateway ✅
+
+Нові endpoints:
+
+```
+GET /internal/matrix/presence/{matrix_user_id}
+GET /internal/matrix/presence/bulk?user_ids=@user1:...,@user2:...
+```
+
+**Приклад відповіді:**
+
+```json
+{
+  "user_id": "@daarion_admin:daarion.space",
+  "presence": "offline",
+  "last_active_ago_ms": 415845,
+  "status_msg": null
+}
+```
+
+**Нормалізація:**
+- Matrix `online` → `"online"`
+- Matrix `unavailable` → `"away"`
+- Matrix `offline` / not found → `"offline"`
+
+### 2.2. City Service ✅
+
+Новий endpoint:
+
+```
+GET /api/v1/agents/{agent_id}/presence
+```
+
+**Приклад відповіді:**
+
+```json
+{
+  "agent_id": "daarwizz",
+  "display_name": "DAARWIZZ",
+  "matrix_user_id": "@agent_daarwizz:daarion.space",
+  "presence": "offline",
+  "last_active_ago_ms": null,
+  "status_msg": null
+}
+```
+
+**Логіка:**
+1. Отримує агента з БД
+2. Генерує Matrix user ID: `@agent_{slug}:daarion.space`
+3. Запитує presence у Matrix Gateway
+4. Повертає нормалізований результат
+
+## 3. API Тести
+
+### 3.1. Matrix Gateway Presence
+
+```bash
+curl -s 'http://localhost:7025/internal/matrix/presence/@daarion_admin:daarion.space' | jq '.'
+```
+
+**Результат:** ✅ Повертає presence статус
+
+### 3.2. Agent Presence
+
+```bash
+curl -s 'http://localhost:7001/api/v1/agents/daarwizz/presence' | jq '.'
+```
+
+**Результат:** ✅ Повертає presence агента
+
+## 4. Інтеграція з Frontend
+
+### 4.1. Наявні компоненти
+
+Файл `apps/web/src/components/ui/AgentPresenceBadge.tsx` вже існує і використовує:
+- `useAgentPresence` hook
+- `globalPresenceClient` для SSE
+
+### 4.2. Рекомендації для повної інтеграції
+
+1. **Оновити `useAgentPresence`** для використання нового API:
+   ```typescript
+   const fetchPresence = async (agentId: string) => {
+     const res = await fetch(`/api/v1/agents/${agentId}/presence`);
+     return res.json();
+   };
+   ```
+
+2. **Додати `PresenceDot` компонент** (якщо ще немає):
+   ```typescript
+   <PresenceDot state="online|offline|away" />
+   ```
+
+3. **Інтегрувати у сторінки:**
+   - `/agents` — біля кожного агента
+   - `/agents/:id` — під аватаркою
+   - `/nodes/:nodeId` — для Guardian/Steward
+   - `/microdao/:slug` — для Orchestrator
+
+## 5. Наступні кроки
+
+### 5.1. Frontend інтеграція (TODO)
+
+- [ ] Оновити `AgentPresenceBadge` для нового API
+- [ ] Додати auto-refresh кожні 30 секунд
+- [ ] Інтегрувати у Chat Widget
+
+### 5.2. Agent Matrix Users (TODO)
+
+- [ ] Створити Matrix users для агентів
+- [ ] Налаштувати агентів для відправки heartbeat
+
+## 6. Архітектура
+
+```
+Frontend → City Service → Matrix Gateway → Synapse
+                ↓
+            Agent DB
+```
+
+**Flow:**
+1. Frontend запитує `/api/v1/agents/{id}/presence`
+2. City Service знаходить агента в БД
+3. City Service генерує Matrix user ID
+4. City Service запитує Gateway
+5. Gateway запитує Synapse
+6. Результат повертається назад
+
+## 7. Команди для перевірки
+
+```bash
+# Matrix Gateway presence
+curl -s 'http://localhost:7025/internal/matrix/presence/@daarion_admin:daarion.space' | jq '.'
+
+# Agent presence
+curl -s 'http://localhost:7001/api/v1/agents/daarwizz/presence' | jq '.'
+
+# Bulk presence
+curl -s 'http://localhost:7025/internal/matrix/presence/bulk?user_ids=@daarion_admin:daarion.space' | jq '.'
+```
+
+---
+
+**Автор:** Cursor AI
+**Таск:** `TASK_PHASE_PRESENCE_LAYER_v1.md`
+