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