diff --git a/.planning/phases/06-web-chat/06-CONTEXT.md b/.planning/phases/06-web-chat/06-CONTEXT.md new file mode 100644 index 0000000..0f5b143 --- /dev/null +++ b/.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 + + +## 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 + + + + +## 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) + + + + +## Deferred Ideas + +None — all at Claude's discretion, nothing out of scope raised + + + +--- + +*Phase: 06-web-chat* +*Context gathered: 2026-03-25*