Skip to content

# 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
2. Зайти на `/agents/:agentId` (наприклад, DAARWIZZ, Clan Bot).
3. Бачити плаваючу кнопку чату.
4. Натиснути → відкрити панель.

5. Надіслати повідомлення → воно йде в відповідну Matrix-кімнату для цього агента.

6. Nodes

7. Зайти на `/nodes/node-1-hetzner-gex44`.
8. Бачити чат із GuardianOS/Pulse (Node Support).

9. Повідомлення потрапляють у кімнату `node-support-node-1-hetzner-gex44`.

10. MicroDAO

11. Зайти на сторінку DAARION root microDAO + District-платформ (GREENFOOD, ENERGYUNION, SOUL, CLAN — коли UI буде готовий).

12. Бачити чат з orchestrator-агентом цього DAO.

13. Онтологічна відповідність

14. На всіх трьох типах сторінок є:
    - присутність агентів (бейджі, профіль),
    - можливість напряму говорити з ними через вбудований чат.

## 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 канал агента (якщо є)