docs: add TASK_PHASE_AGENT_CHAT_WIDGET_MVP.md

Task for implementing floating chat widget on agent/node/microdao pages. Follows ontology rule: 'No page without agents means ability to talk to them directly.' Scope: - Backend: /chat-room API endpoints - Frontend: AgentChatWidget.tsx component - Integration: /agents/:agentId, /nodes/:nodeId, /microdao/:slug
2025-11-30 09:04:04 -08:00
parent 644edd3f30
commit fb4a33f016
1 changed files with 189 additions and 0 deletions
--- a/docs/tasks/TASK_PHASE_AGENT_CHAT_WIDGET_MVP.md
+++ b/docs/tasks/TASK_PHASE_AGENT_CHAT_WIDGET_MVP.md
@@ -0,0 +1,189 @@
+# TASK PHASE — AGENT CHAT WIDGET (MVP)
+
+Version: 1.0
+Status: ACTIVE
+Target: DAARION.space (Next.js frontend + city-service)
+
+## 1. Мета
+
+Зробити так, щоб на ключових сторінках MVP ("кабінет агента", "кабінет ноди", "кабінет microDAO")
+завжди було доступне **інтерактивне вікно чату** з відповідним агентом / агентами.
+
+Реалізувати правило онтології:  
+> "Немає сторінки без агентів" означає не лише присутність аватарів,  
+> а й можливість **напряму говорити з агентом** на цій сторінці.
+
+---
+
+## 2. Область робіт (scope)
+
+### Сторінки
+
+1. `/agents/:agentId`
+2. `/nodes/:nodeId`
+3. `/microdao/:slug` (або фактичний маршрут для MicroDAO Dashboard)
+
+На цих сторінках має з'явитись **Agent Chat Widget**.
+
+---
+
+## 3. UX / UI Вимоги
+
+### 3.1. Agent Chat Dock (загальна поведінка)
+
+- Плаваюча кнопка/іконка в правому нижньому куті:
+  - стан `collapsed` → кругла кнопка з аватаром агента;
+  - стан `expanded` → панель чату (висота ~40–60% екрану).
+- Панель чату:
+  - заголовок: ім'я агента (+ роль: Orchestrator / GuardianOS / Steward / District Lead тощо);
+  - індикатор статусу (online / degraded / offline);
+  - основна область повідомлень;
+  - input для тексту (MVP: лише текст).
+- На мобільному:
+  - панель займає більшу частину екрану при розгортанні;
+  - кнопка закриття повертає в collapsed-стан.
+
+### 3.2. Прив'язка до сутності
+
+- На сторінці агента `/agents/:agentId`:
+  - чат з **цим агентом** (primary_agent = agentId).
+- На сторінці ноди `/nodes/:nodeId`:
+  - чат із **Node GuardianOS** + **Node Steward (Pulse)** для цієї ноди.
+- На сторінці microDAO:
+  - чат з **orchestrator-агентом microDAO** (або DAARWIZZ для root DAARION).
+
+---
+
+## 4. Backend / Matrix / Rooms
+
+### 4.1. Джерело істини
+
+Використати існуючий Rooms / Matrix шар згідно з:
+
+- `Rooms_Layer_Architecture_v1.md`
+- `City_Interface_Architecture_v1.md`
+- `Agents_Interface_Architecture_v1.md`
+
+### 4.2. Мапінг "сторінка → кімната"
+
+MVP-правило:
+
+- `/agents/:agentId`  
+  → кімната типу: `agent-console-{agentSlug}`
+
+- `/nodes/:nodeId`  
+  → кімната типу: `node-support-{nodeSlug}`  
+  (учасники: GuardianOS, Pulse та, за потреби, інші core-агенти Ноди)
+
+- `/microdao/:slug`  
+  → кімната типу: `microdao-lobby-{slug}`  
+  (орchestrator microDAO + системні агенти цього DAO)
+
+### 4.3. API-рівень (MVP)
+
+Якщо вже є готовий endpoint для кімнат — використати його.  
+Якщо немає — додати мінімальний:
+
+- `GET /api/v1/agents/{agentId}/chat-room`
+  - повертає: `room_id`, `matrix_server`, `agent_display_name`, `avatar_url`
+- `GET /api/v1/nodes/{nodeId}/chat-room`
+- `GET /api/v1/microdaos/{slug}/chat-room`
+
+(або еквівалентні маршрути, узгоджені з поточною схемою city-service).
+
+Frontend не повинен сам вигадувати roomId — лише використовує те, що повертає API.
+
+---
+
+## 5. Frontend (Next.js)
+
+### 5.1. Новий компонент
+
+Створити компонент:
+
+- `apps/web/src/components/chat/AgentChatWidget.tsx`
+
+Функціонал:
+
+- приймає props:
+  - `contextType: "agent" | "node" | "microdao"`
+  - `contextId: string` (agentId / nodeId / microdaoSlug)
+- при mount:
+  - викликає відповідний API `/chat-room` для отримання roomId / agentInfo;
+  - ініціалізує клієнт (Matrix/WebSocket/HTTP-пулінг — згідно з існуючою інтеграцією).
+- рендерить:
+  - кнопку (collapsed),
+  - панель чату (expanded).
+
+Можна використати існуючі частини **CityChatWidget / MatrixChatPage**,  
+але в компактному режимі.
+
+### 5.2. Інтеграція у сторінки
+
+- `/agents/:agentId`
+  - імпорт `AgentChatWidget`
+  - `contextType="agent"`, `contextId = agentId`
+
+- `/nodes/:nodeId`
+  - `contextType="node"`, `contextId = nodeId`
+
+- `/microdao/:slug`
+  - `contextType="microdao"`, `contextId = slug`
+
+---
+
+## 6. Acceptance Criteria
+
+1. **Agents**
+   - Зайти на `/agents/:agentId` (наприклад, DAARWIZZ, Clan Bot).
+   - Бачити плаваючу кнопку чату.
+   - Натиснути → відкрити панель.
+   - Надіслати повідомлення → воно йде в відповідну Matrix-кімнату для цього агента.
+
+2. **Nodes**
+   - Зайти на `/nodes/node-1-hetzner-gex44`.
+   - Бачити чат із GuardianOS/Pulse (Node Support).
+   - Повідомлення потрапляють у кімнату `node-support-node-1-hetzner-gex44`.
+
+3. **MicroDAO**
+   - Зайти на сторінку DAARION root microDAO + District-платформ (GREENFOOD, ENERGYUNION, SOUL, CLAN — коли UI буде готовий).
+   - Бачити чат з orchestrator-агентом цього DAO.
+
+4. **Онтологічна відповідність**
+   - На всіх трьох типах сторінок є:
+     - присутність агентів (бейджі, профіль),
+     - можливість **напряму говорити** з ними через вбудований чат.
+
+---
+
+## 7. Вихідні артефакти
+
+Після виконання:
+
+- `docs/debug/agent_chat_widget_mvp_report_<DATE>.md`  
+  з описом:
+  - які сторінки підключені;
+  - які roomId використовуються;
+  - скріншоти або посилання на UI.
+
+---
+
+## 8. Технічні нотатки
+
+### Існуючі компоненти для перевикористання
+
+- `apps/web/src/components/city/CityChatWidget.tsx` — може бути основою
+- `apps/web/src/app/agents/[agentId]/page.tsx` — вже має вкладку "Chat", але це inline чат, не floating widget
+- Matrix інтеграція через `matrix-gateway`
+
+### Пріоритет реалізації
+
+1. Спочатку `/agents/:agentId` — найпростіший кейс (один агент)
+2. Потім `/microdao/:slug` — orchestrator + можливо кілька агентів
+3. Нарешті `/nodes/:nodeId` — Guardian + Steward
+
+### Fallback якщо Matrix недоступний
+
+- Показати повідомлення "Чат тимчасово недоступний"
+- Запропонувати альтернативу: посилання на Telegram канал агента (якщо є)
+