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