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