Skip to content

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

### Вихід:

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

### Вихід:

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