Skip to content

# 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: `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. Інтегрувати у сторінки:

4. `/agents` — біля кожного агента
5. `/agents/:id` — під аватаркою
6. `/nodes/:nodeId` — для Guardian/Steward
7. `/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`