microdao-daarion/docs/debug/presence_layer_report_20251130.md

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:...

Приклад відповіді:

{
  "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

Приклад відповіді:

{
  "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

curl -s 'http://localhost:7025/internal/matrix/presence/@daarion_admin:daarion.space' | jq '.'

Результат: ✅ Повертає presence статус

3.2. Agent Presence

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:

   const fetchPresence = async (agentId: string) => {
     const res = await fetch(`/api/v1/agents/${agentId}/presence`);
     return res.json();
   };
   

2. Додати PresenceDot компонент (якщо ще немає):

   <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. Команди для перевірки

# 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