111 lines
5.1 KiB
Markdown
111 lines
5.1 KiB
Markdown
# Phase 6: Web Chat - Context
|
|
|
|
**Gathered:** 2026-03-25
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
Real-time web chat interface in the portal where users can converse with AI Employees. Treated as a new channel adapter ("web") alongside Slack and WhatsApp — same orchestrator pipeline (memory, tools, escalation, media, audit). Persistent conversation history. RBAC-enforced access. Responsive UX with typing indicators.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
All decisions at Claude's discretion — user trusts judgment.
|
|
|
|
### Chat UI Layout
|
|
- Dedicated `/chat` page in the portal (not a floating widget or sidebar) — full-screen chat experience
|
|
- Left sidebar: list of conversations grouped by agent, with timestamps and last message preview
|
|
- Right panel: active conversation with message bubbles (user right-aligned, agent left-aligned)
|
|
- "New Conversation" button opens an agent picker (shows agents the user has access to)
|
|
- Markdown rendering in agent messages (agents respond with formatted text)
|
|
- Image/document display inline (consistent with media support from Phase 2)
|
|
- Typing indicator (animated dots) while waiting for agent response
|
|
|
|
### Who Can Chat
|
|
- All three roles can chat: platform admin, customer admin, customer operator
|
|
- Users can only see and chat with agents belonging to tenants they have access to (RBAC)
|
|
- Platform admins can chat with any agent across all tenants (elevated access)
|
|
- Operators can chat (read-only restrictions don't apply to conversations — chatting IS the product)
|
|
|
|
### Conversation Management
|
|
- One conversation thread per user-agent pair (matches the per-user per-agent memory model from Phase 2)
|
|
- Users can start a new conversation (clears the thread context) or continue the existing one
|
|
- Conversation list shows all agents the user has chatted with, sorted by most recent
|
|
- Conversation history loads on page visit — scrollable, paginated for long histories
|
|
|
|
### Real-Time Communication
|
|
- WebSocket connection between portal and gateway for real-time message delivery
|
|
- Fallback to HTTP polling if WebSocket unavailable
|
|
- Gateway receives web chat message, normalizes to KonstructMessage (channel: "web"), dispatches through existing pipeline
|
|
- Agent response pushed back via WebSocket to update the chat UI
|
|
|
|
### Web Channel Adapter
|
|
- New "web" channel adapter in the gateway alongside Slack and WhatsApp
|
|
- Normalizes portal chat messages into KonstructMessage format
|
|
- channel_metadata includes: portal_user_id, tenant_id, conversation_id
|
|
- Tenant resolution from the authenticated session (not from channel metadata like Slack workspace ID)
|
|
- Outbound: push response via WebSocket connection keyed to conversation_id
|
|
|
|
### Claude's Discretion
|
|
- WebSocket library choice (native ws, Socket.IO, etc.)
|
|
- Message bubble visual design
|
|
- Conversation pagination strategy (infinite scroll vs load more)
|
|
- Whether to show tool invocation indicators in chat (e.g., "Searching knowledge base...")
|
|
- Agent avatar/icon in chat
|
|
- Sound notification on new message
|
|
- Mobile responsiveness approach
|
|
|
|
</decisions>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- The chat should feel like a modern messaging app (think Slack DMs or iMessage) — not a clinical chatbot widget
|
|
- Agent responses should render markdown naturally — code blocks, lists, bold text
|
|
- The typing indicator while the LLM generates makes it feel alive
|
|
- Conversation list on the left gives the feel of having multiple AI coworkers you can talk to
|
|
|
|
</specifics>
|
|
|
|
<code_context>
|
|
## Existing Code Insights
|
|
|
|
### Reusable Assets
|
|
- `packages/gateway/gateway/normalize.py` — Message normalization pattern (extend for "web" channel)
|
|
- `packages/gateway/gateway/channels/slack.py` — Channel adapter pattern to follow
|
|
- `packages/orchestrator/orchestrator/tasks.py:handle_message` — Existing Celery task processes all channels
|
|
- `packages/orchestrator/orchestrator/tasks.py:_send_response` — Channel-aware outbound routing (add "web" case)
|
|
- `packages/shared/shared/models/message.py:KonstructMessage` — Already supports "web" if added to ChannelType
|
|
- `packages/portal/components/session-sync.tsx` — Session data available for RBAC headers
|
|
- `packages/portal/lib/api.ts` — API client with RBAC headers (for REST fallback)
|
|
|
|
### Established Patterns
|
|
- Channel adapters normalize to KonstructMessage, dispatch to Celery, receive response via callback
|
|
- All message processing goes through the orchestrator pipeline (memory, tools, escalation, audit)
|
|
- Portal uses TanStack Query for data fetching, shadcn/ui for components
|
|
- RBAC enforced at both API (FastAPI Depends) and portal (proxy.ts) levels
|
|
|
|
### Integration Points
|
|
- Gateway needs new WebSocket endpoint + web channel adapter
|
|
- KonstructMessage.ChannelType needs "web" added
|
|
- _send_response in tasks.py needs "web" case (push via WebSocket/Redis pub-sub)
|
|
- Portal needs new /chat route with WebSocket client
|
|
- Conversation persistence: reuse existing Redis sliding window + pgvector (already keyed per-user per-agent)
|
|
|
|
</code_context>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — all at Claude's discretion, nothing out of scope raised
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 06-web-chat*
|
|
*Context gathered: 2026-03-25*
|