docs(06): capture phase context

.planning/phases/06-web-chat/06-CONTEXT.md

@@ -0,0 +1,110 @@
+# 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*