feat: Presence Layer API implementation
Matrix Gateway:
- GET /internal/matrix/presence/{matrix_user_id} - get single user presence
- GET /internal/matrix/presence/bulk - get multiple users presence
City Service:
- GET /api/v1/agents/{agent_id}/presence - get agent presence via gateway
- get_matrix_presence_for_user() helper function
Task doc: TASK_PHASE_PRESENCE_LAYER_v1.md
This commit is contained in:
Apple
228
docs/tasks/TASK_PHASE_PRESENCE_LAYER_v1.md
Normal file
228
docs/tasks/TASK_PHASE_PRESENCE_LAYER_v1.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user