feat: implement Agent Chat Widget for entity pages
TASK_PHASE_AGENT_CHAT_WIDGET_MVP.md completed:
Backend:
- Add /api/v1/agents/{agent_id}/chat-room endpoint
- Add /api/v1/nodes/{node_id}/chat-room endpoint
- Add /api/v1/microdaos/{slug}/chat-room endpoint
Frontend:
- Create AgentChatWidget.tsx floating chat component
- Integrate into /agents/:agentId page
- Integrate into /nodes/:nodeId page
- Integrate into /microdao/:slug page
Ontology rule implemented:
'No page without agents' = ability to directly talk to agents on that page
This commit is contained in:
Apple
229
docs/debug/agent_chat_widget_mvp_report_20251201.md
Normal file
229
docs/debug/agent_chat_widget_mvp_report_20251201.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```typescript
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
- [ ] `/agents/daarwizz` — click opens chat panel
|
||||
- [ ] `/agents/daarwizz` — chat connects to Matrix room (if available)
|
||||
- [ ] `/nodes/node-1-hetzner-gex44` — floating chat button visible
|
||||
- [ ] `/nodes/node-1-hetzner-gex44` — shows Guardian/Steward agents
|
||||
- [ ] `/microdao/daarion` — floating chat button visible
|
||||
- [ ] `/microdao/daarion` — shows orchestrator agent info
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user