microdao-daarion/docs/debug/agent_chat_widget_mvp_report_20251201.md

Agent Chat Widget MVP - Implementation Report

Date: 2025-12-01 Task: docs/tasks/TASK_PHASE_AGENT_CHAT_WIDGET_MVP.md Status: ✅ COMPLETED

---

1. Summary

Реалізовано floating Agent Chat Widget на ключових сторінках MVP:

• /agents/:agentId — чат з конкретним агентом
• /nodes/:nodeId — чат з Node Guardian/Steward агентами
• /microdao/:slug — чат з orchestrator-агентом MicroDAO

Правило онтології виконано:

"Немає сторінки без агентів" означає не лише присутність аватарів, а й можливість напряму говорити з агентом на цій сторінці.

---

2. Backend Implementation

2.1. Нові API Endpoints

Додано до services/city-service/routes_city.py:

Endpoint	Method	Опис
/api/v1/agents/{agent_id}/chat-room	GET	Інформація про кімнату чату для агента
/api/v1/nodes/{node_id}/chat-room	GET	Інформація про кімнату чату для ноди
/api/v1/microdaos/{slug}/chat-room	GET	Інформація про кімнату чату для MicroDAO

2.2. Response Schema

Agent Chat Room:

{
  "agent_id": "daarwizz",
  "agent_display_name": "DAARWIZZ",
  "agent_avatar_url": "https://...",
  "agent_status": "online",
  "agent_kind": "orchestrator",
  "room_slug": "agent-console-daarwizz",
  "room_id": "room-uuid",
  "matrix_room_id": "!abc:matrix.daarion.space",
  "chat_available": true
}

Node Chat Room:

{
  "node_id": "node-1-hetzner-gex44",
  "node_name": "Hetzner GEX44 Production",
  "node_status": "online",
  "room_slug": "node-support-1_hetzner_gex44",
  "room_id": null,
  "matrix_room_id": null,
  "chat_available": false,
  "agents": [
    {"id": "guardian-os", "display_name": "GuardianOS", "kind": "service", "role": "guardian"},
    {"id": "pulse", "display_name": "Pulse", "kind": "service", "role": "steward"}
  ]
}

MicroDAO Chat Room:

{
  "microdao_id": "dao_daarion",
  "microdao_slug": "daarion",
  "microdao_name": "DAARION DAO",
  "room_slug": "microdao-lobby-daarion",
  "room_id": "room-uuid",
  "matrix_room_id": "!xyz:matrix.daarion.space",
  "chat_available": true,
  "orchestrator": {
    "id": "daarwizz",
    "display_name": "DAARWIZZ",
    "avatar_url": "https://...",
    "kind": "orchestrator",
    "role": "orchestrator"
  }
}

---

3. Frontend Implementation

3.1. Новий Компонент

File: apps/web/src/components/chat/AgentChatWidget.tsx

Features:

• Floating button у правому нижньому куті
• Collapsed state: кругла кнопка з аватаром агента та індикатором статусу
• Expanded state: панель чату ~500px висотою
• Автоматичний fetch chat-room info при mount
• Інтеграція з існуючим CityChatWidget для Matrix chat
• Показ агентів підтримки для Node context
• Graceful degradation коли кімната чату недоступна

Props:

interface AgentChatWidgetProps {
  contextType: 'agent' | 'node' | 'microdao';
  contextId: string;
  className?: string;
}

3.2. Інтеграція у Сторінки

Сторінка	Файл	Props
Agent Cabinet	apps/web/src/app/agents/[agentId]/page.tsx	contextType="agent" contextId={agentId}
Node Cabinet	apps/web/src/app/nodes/[nodeId]/page.tsx	contextType="node" contextId={nodeId}
MicroDAO Dashboard	apps/web/src/app/microdao/[slug]/page.tsx	contextType="microdao" contextId={slug}

---

4. Room Mapping

Відповідно до Rooms_Layer_Architecture_v1.md:

Context	Room Slug Pattern	Учасники
Agent	agent-console-{agentSlug}	Конкретний агент
Node	node-support-{nodeSlug}	GuardianOS, Pulse, інші core-агенти
MicroDAO	microdao-lobby-{slug}	Orchestrator агент + системні агенти DAO

---

5. UX/UI Details

5.1. Collapsed State

• Кругла кнопка 56x56px
• Gradient background: violet-600 → purple-700
• Avatar агента або іконка (Bot/Server/Building2)
• Status indicator: green (online) / gray (offline)
• Pulse animation для online агентів
• Hover tooltip: "Чат з {name}"

5.2. Expanded State

• Panel: 380px × 500px (responsive)
• Header: Avatar, Name, Status
• Chat area: Інтеграція з CityChatWidget
• Footer (Node): Список агентів підтримки
• Close button: X у верхньому правому куті

5.3. Error States

• Loading: Spinner
• Error: Alert з кнопкою "Спробувати знову"
• Chat unavailable: Інформаційне повідомлення

---

6. Files Changed

Backend

• services/city-service/routes_city.py — додано 3 нові endpoints

Frontend

• apps/web/src/components/chat/AgentChatWidget.tsx — NEW
• apps/web/src/app/agents/[agentId]/page.tsx — інтеграція
• apps/web/src/app/nodes/[nodeId]/page.tsx — інтеграція
• apps/web/src/app/microdao/[slug]/page.tsx — інтеграція

---

7. Deployment Steps

# 1. Commit changes
git add .
git commit -m "feat: implement Agent Chat Widget for entity pages"

# 2. Push to GitHub
git push origin main

# 3. Pull on NODE1
ssh root@144.76.224.179 "cd /opt/microdao-daarion && git pull"

# 4. Rebuild services
ssh root@144.76.224.179 "cd /opt/microdao-daarion && docker compose up -d --build daarion-city-service daarion-web"

---

8. Verification Checklist

• /agents/daarwizz — floating chat button visible ✅ "Чат з Chat"
• /agents/daarwizz — click opens chat panel (requires login)
• /agents/daarwizz — chat connects to Matrix room (if available)
• /nodes/node-1-hetzner-gex44 — floating chat button visible ✅ "Чат з Hetzner GEX44 Production"
• /nodes/node-1-hetzner-gex44 — shows Guardian/Steward agents ✅
• /microdao/daarion — floating chat button visible ✅ "Чат з DAARION DAO"
• /microdao/daarion — shows orchestrator agent info (requires room setup)

---

9. Known Limitations (MVP)

1. Room Creation: Widget does NOT create rooms automatically. Rooms must exist in city_rooms table with Matrix integration.
2. Authentication: Chat requires user to be logged in (via JWT).
3. Node Rooms: Node support rooms likely don't exist yet — widget will show "Chat unavailable".
4. Mobile: Panel takes ~90% of screen width on mobile — may need refinement.

---

10. Next Steps

1. Create Missing Rooms: Run /city/matrix/backfill or create rooms manually for:

   • Agent console rooms
   • Node support rooms
   • MicroDAO lobby rooms

2. Auto-Create Rooms: Consider adding room auto-creation in /chat-room endpoints.

3. Direct Messages: Add support for direct 1:1 chat with agents (not room-based).

4. Voice/Video: Future extension for audio/video calls with agents.

---

Report generated: 2025-12-01 Author: Cursor AI