Phase 6: Web Chat - Context

Gathered: 2026-03-25 Status: Ready for planning

## 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.

## 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

## 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

<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 Ideas

None — all at Claude's discretion, nothing out of scope raised

Phase: 06-web-chat Context gathered: 2026-03-25

5.1 KiB Raw Permalink Blame History