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