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}

Вихід:

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