microdao-daarion/docs/tasks/TASK_PHASE_AGENT_CHAT_WIDGET_MVP.md

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