microdao-daarion/docs/tasks/TASK_PHASE_PRESENCE_LAYER_v1.md

# TASK_PHASE_PRESENCE_LAYER_v1

Version: 1.0
Status: Ready
Priority: Critical (Agent Presence / City Presence / Chat Online State)

---

# 1. МЕТА ТА ОПИС

Впровадити **повний Presence Layer** у DAARION.city:

- online/offline/away для кожного агента;
- Matrix → Gateway → City Service → Frontend;
- інтеграція у всі ключові сторінки:
  `/agents`, `/agents/:id`, `/nodes/:nodeId`, `/microdao/:slug`, `/city`.

Presence — це системний фундамент для:
- живих агентів у місті,
- реального часу в чаті,
- індикаторів активності кімнат,
- майбутнього AI presence (LLM/Автономні агенти),
- системної безпеки.

---

# 2. ПРИНЦИП РОБОТИ (ІНВАРІАНТ)

Presence = стан Matrix user.

Кожен агент має:
- `agent.matrix_user_id` (наприклад, `@daarwizz:matrix.daarion.city`)
- presence береться з Matrix Homeserver API
- gateway перетворює у нормалізовану форму
- city-service кешує стан
- frontend показує живий статус

---

# 3. МОДУЛЬ 1 — MATRIX GATEWAY (BACKEND)

## 3.1. Додати endpoint

`GET /internal/matrix/presence/{matrix_user_id}`

### Вихід:

```json
{
  "user_id": "@dario:matrix.daarion.city",
  "presence": "online" | "offline" | "unavailable",
  "last_active_ago_ms": 12345
}
```

### Логіка:

- Використати Matrix API
  `/_matrix/client/v3/presence/{userId}/status`
- Обробити помилки:
  - no such user → `"offline"`
  - rate limited → повторити 1 раз
- Нормалізувати:
  - online → "online"
  - unavailable → "away"
  - offline → "offline"

## 3.2. Модуль Presence Poller (опціонально, але бажано)

- Кожні 30–60 секунд запитувати статуси публічних агентів.
- Зберігати кеш у пам'яті gateway.
- Зменшує навантаження на Matrix.

---

# 4. МОДУЛЬ 2 — CITY-SERVICE (API)

## 4.1. Новий endpoint:

`GET /api/v1/agents/{agent_id}/presence`

### Вихід:

```json
{
  "agent_id": "uuid",
  "presence": "online" | "offline" | "away",
  "matrix_user_id": "@agent_daarwizz:matrix.daarion.city",
  "last_active_ago_ms": <number|null>
}
```

### Логіка:

- city-service знаходить `agent.matrix_user_id`
- робить запит до gateway:
  `/internal/matrix/presence/{mxid}`
- кешує відповідь на 15–30 секунд (optional)
- повертає frontend

---

# 5. МОДУЛЬ 3 — FRONTEND (Next.js)

## 5.1. Новий API-клієнт

`lib/api/presence.ts`:

- `getAgentPresence(agentId)`
- повертає normalized presence

## 5.2. Компонент PresenceDot

`<PresenceDot state="online|offline|away" />`

- online → зелений
- away → жовтий
- offline → сірий

## 5.3. Інтеграції

### `/agents`

У таблиці списку агентів:

- додати `<PresenceDot>` зліва від аватарки.

### `/agents/:id`

Під аватаркою агента:

- "Статус: online/offline/away"

### `/nodes/:nodeId`

Для Guardian/Steward:

- показати presence

### `/microdao/:slug`

Для Orchestrator:

- показати presence

### `/city`

У City Rooms списку:

- показати presence адміністраторів кімнат (DARIO/DARIA)

---

# 6. МОДУЛЬ 4 — CHAT WIDGET інтеграція

### 6.1. У Chat Widget:

- якщо presence = offline → показати "Агент офлайн"
- якщо presence = away → "Агент може відповісти із затримкою"
- якщо presence = online → нормальна робота

### 6.2. Додати auto-refresh presence кожні 20–30 секунд

---

# 7. SMOKE ТЕСТИ

Після завершення:

1. `/agents`
   — для кожного публічного агента видно presence.

2. `/agents/daarwizz`
   — показує реальний статус DAARWIZZ.

3. `/nodes/node-1-hetzner-gex44`
   — guardian/steward мають presence-індикатор.

4. `/microdao/daarion`
   — orchestrator DAARWIZZ показує presence.

5. Chat Widget
   — якщо агент offline → видно попередження
   — якщо online → можливо писати

6. Gateway
   — endpoint `/internal/matrix/presence/{id}` повертає реальні дані.

---

# 8. ФІНАЛЬНИЙ АРТЕФАКТ

Cursor після виконання створює:

`docs/debug/presence_layer_report_<DATE>.md`

Зміст:

- список agent → presence
- список кімнат → адміністратори → presence
- приклади API-відповідей gateway і city-service
- скріншоти або описи UI-тестів

---

# 9. PROMPT ДЛЯ CURSOR

```
Виконай TASK_PHASE_PRESENCE_LAYER_v1.md.

Модулі:
1) matrix-gateway — додати presence API
2) city-service — presence endpoint
3) frontend — presence інтеграція до agent/node/microdao/city
4) chat widget — presence-механіка

Після завершення створи файл:
docs/debug/presence_layer_report_<DATE>.md

Орієнтуйся на foundation-документи у docs/foundation/.
```

---

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