Skip to content

# 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

- [x] `/agents/daarwizz` — floating chat button visible ✅ "Чат з Chat"
- [ ] `/agents/daarwizz` — click opens chat panel (requires login)
- [ ] `/agents/daarwizz` — chat connects to Matrix room (if available)
- [x] `/nodes/node-1-hetzner-gex44` — floating chat button visible ✅ "Чат з Hetzner GEX44 Production"
- [x] `/nodes/node-1-hetzner-gex44` — shows Guardian/Steward agents ✅
- [x] `/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:
2. Agent console rooms
3. Node support rooms

4. MicroDAO lobby rooms

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

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

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

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