# 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`