microdao-daarion/docs/tasks/TASK_AGENT_HUB_MVP.md

TASK: Implement Agent Hub (Team Assistant) using existing Messenger as core

Goal: Створити головний "Agent Hub" інтерфейс (Team Assistant), який:

• показує список microDAO / команд / агентів,
• дозволяє вибрати агента й говорити з ним (на основі Messenger),
• показує контекст (проєкти, задачі, квести, стан агента),
• стане /home для користувача.

Constraints:

• Використати існуючий Messenger (channels, messages, WS) як ядро для чату.
• Не дублювати логіку відправки/отримання повідомлень.
• Agent Hub = надбудова над Messenger + Agents + Projects (stub).

---

1) Frontend structure

Create feature:

src/features/agent-hub/
  AgentHubPage.tsx
  components/
    AgentSidebar.tsx
    AgentList.tsx
    AgentListItem.tsx
    AgentSummaryCard.tsx
    AgentContextPanel.tsx
    AgentStatusBadge.tsx
  hooks/
    useAgents.ts
    useAgentHubState.ts
  api/
    getAgents.ts
    getAgentSummary.ts
    getAgentContext.ts

Route:

• Додати /hub або /home:

  <Route path="/hub" element={<AgentHubPage />} />
  

Layout (3-колонковий)

┌──────────────────┬────────────────────────────┬───────────────────┐
│ Left:            │ Center:                    │ Right:            │
│ Agents sidebar   │ Chat (Messenger embed)     │ Context panel     │
└──────────────────┴────────────────────────────┴───────────────────┘

Left (AgentSidebar):

• список:
  • "My microDAO"
  • "My agents"
  • "System agents"
• кожен агент: name, kind, microDAO badge, status badge.
• фільтр/пошук.

Center:

• Вбудований Messenger:
  • Reuse MessengerPage components:
    • ChannelHeader
    • MessageList
    • MessageComposer
  • Але:
    • працюємо з "direct" або "agent-specific" channel.
• При виборі агента:
  • якщо ще немає direct channel з цим агентом:
    • викликати backend:

      POST /api/messaging/channels
      {
        "name": "DM with Sofia-Prime",
        "type": "direct",
        "agent_id": "<agent_id>"
      }
      

    • запамʼятати channel_id.
  • якщо є → просто підключити Messenger до цього channel_id.

Right (AgentContextPanel):

• картка обраного агента:
  • імʼя, архетип, модель, microDAO.
  • статус: active/idle, останній reply.
• блок "Active projects" (stub):
  • отримати з /api/agent-hub/agents/{id}/context
  • список 3–5 проєктів/тасок (можна поки мок).
• блок "Capabilities":
  • список інструментів агента (з blueprint):
    • "Can manage tasks"
    • "Can summarise channels"
    • "Can create follow-ups"

---

2) Backend: Agent Hub API

New service or extend existing agents-service:

services/agents-service/ (якщо вже є, розширити)

Endpoints:

GET /api/agent-hub/agents

→ список агентів для поточного користувача:

[
  {
    "id": "agent:sofia",
    "name": "Sofia-Prime",
    "kind": "assistant",
    "microdao_id": "microdao:7",
    "status": "online",
    "model": "gpt-4.1",
    "avatar_url": null
  }
]

GET /api/agent-hub/agents/{agentId}/summary

→ коротке резюме:

{
  "id": "agent:sofia",
  "name": "Sofia-Prime",
  "kind": "assistant",
  "microdao_id": "microdao:7",
  "specialization": "Team Assistant / PM",
  "description": "Допомагає планувати, підсумовувати, слідкує за задачами.",
  "last_activity_at": "...",
  "stats": {
    "messages_last_24h": 42,
    "channels": 5
  }
}

GET /api/agent-hub/agents/{agentId}/context

→ контекст:

{
  "projects": [
    { "id": "...", "name": "Messenger v1", "status": "active" },
    { "id": "...", "name": "City Dashboard", "status": "active" }
  ],
  "followups": [
    { "id": "...", "title": "Перевірити NATS інтеграцію", "due_at": "..." }
  ]
}

POST /api/agent-hub/agents/{agentId}/ensure-direct-channel

Body: {}

Behavior:

• знайти чи існує direct channel між user та agent:

  SELECT FROM channels WHERE kind='direct' AND user_id=... AND agent_id=...
  

• якщо не існує:
  • створити в messaging-service:

    POST /internal/messaging/channels
    {
      "name": "DM with Sofia-Prime",
      "kind": "direct",
      "microdao_id": "<current microdao>",
      "participants": ["user:...", "agent:sofia"]
    }
    

  • повернути channel_id.
• якщо існує → повернути channel_id.

---

3) Frontend wiring

useAgents.ts:

• GET /api/agent-hub/agents
• зберігати список агентів + loading/error.

useAgentHubState.ts:

• стан:
  • selectedAgentId
  • selectedChannelId
• методи:
  • selectAgent(agentId):
    • викликати /api/agent-hub/agents/{agentId}/ensure-direct-channel
    • зберегти channelId
  • selectChannel(channelId)

AgentHubPage.tsx:

• Layout на 3 колонки.
• Зліва: AgentSidebar (list, onSelect → selectAgent).
• Центр:
  • якщо selectedChannelId:
    • рендер Messenger core:

      <MessengerChannelView channelId={selectedChannelId} />
      

    (створити обгортку над існуючими компонентами Messenger, яка приймає channelId як проп).
• Праворуч: AgentContextPanel (summary + context для selectedAgent).

---

4) Reuse Messenger components

Створити lightweight обгортку:

src/features/messenger/components/MessengerChannelView.tsx

Яка:

• приймає channelId як проп,
• внутрішньо використовує:
  • useMessages(channelId)
  • useMessagingWebSocket(channelId)
  • MessageList
  • MessageComposer
  • ChannelHeader (можна переоприділити title під імʼя агента).

Це дозволяє:

• зберегти один стек логіки для Messenger,
• використовувати його і в /messenger, і в /hub.

---

5) Навігація

Додати кнопку/посилання:

• з Onboarding (PortalScene) → редірект у /hub замість /city або як додаткову опцію.
• з /city-v2 HUD: кнопка "Agent Hub" → /hub.
• з /messenger: кнопка "Open Agent Hub" → /hub.

---

6) Документація

Додати:

• docs/AGENT_HUB_MVP.md:
  • опис ролі Agent Hub,
  • API endpoints,
  • UX flow (вибір агента → відкриття каналу → контекст справа),
  • як це повʼязано з agent-runtime (Phase 2).

---

Acceptance Criteria

• ✅ Route /hub відкривається без помилок.
• ✅ В AgentSidebar видно список агентів для поточного користувача.
• ✅ При виборі агента створюється (або знаходиться) direct channel, відкривається чат (Messenger components).
• ✅ Праворуч показується хоча б stub-контекст (projects/followups з мокових даних).
• ✅ Агент, підʼєднаний через Phase 2 (agent_filter + router + runtime), може відповідати в direct channel з Agent Hub.

---

Version: 1.0.0
Date: 2025-11-24
Priority: High
Estimated Time: 2 weeks
Dependencies: TASK_PHASE2_AGENT_INTEGRATION.md (recommended but not blocking for UI)