Chat & Interaction UI

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/src/features/chat/components/ChatPanel.tsx
• apps/web/src/features/chat/state/useChatPanelController.ts
• apps/web/src/features/chat/types.ts
• apps/web/src/features/chat/state/chatMessageMapper.ts
• apps/web/src/features/chat/components/messages/PlanPreviewMessage.tsx
• apps/web/src/features/sources/components/SourceHeader.tsx

The Chat & Interaction UI serves as the primary interface for users to convert raw information into structured briefings. It acts as a conversational bridge between the Library (source materials) and the Briefing System, allowing users to guide AI agents through specific enrichment intents.

This system is built as a sidebar interaction (Sheet) that maintains state throughout the briefing lifecycle: from selecting a research intent and approving a multi-step execution plan to monitoring real-time agent progress and viewing the final result.

Architecture and UI Components

The UI is built using a side-sheet pattern that slides out from the right, ensuring the user can maintain context with the source material while interacting with the chat.

ChatPanel Component

The ChatPanel is the root UI container. It utilizes a Sheet component from the UI library to provide an overlay interface. It manages three primary areas:

1. Header: Displays the current source context (e.g., the title of the article or video being briefed).
2. Message Area: A scrollable list powered by a MessageList component and wrapped in a ChatMessageHandlersProvider to provide action callbacks to individual message items.
3. Input Form: A simple text input for user queries, though currently focused on driving the V1 automated flow.

Sources: apps/web/src/features/chat/components/ChatPanel.tsx:39-101, apps/web/src/features/chat/types.ts:145-148

Message Representation

Messages are structured as polymorphic objects identified by a type field. This allows the system to render standard text, interactive intent selectors, execution plans, and progress trackers within the same stream.

A diagram showing the relationship between the ChatMessage container and specialized payloads for planning and progress.
Sources: apps/web/src/features/chat/types.ts:88-100

State Management and Data Flow

The logic is centralized in the useChatPanelController hook, which manages transitions between different stages of the briefing generation process.

Briefing Generation Lifecycle

The interaction follows a specific sequence of states to ensure user control over AI agent actions:

1. Initialization: User clicks "Generate Briefing" on a source page, which triggers openFromSource.
2. Intent Selection: The controller presents options like deep_dive, contextual_expansion, or truth_grounding.
3. Planning: The backend generates a plan. The UI displays this via a plan_preview message.
4. Execution: Upon user approval, the briefing status moves to generating, and the UI switches to a polling-driven step_progress view.
5. Completion: Once the briefing is ready, a result message is appended with a navigation link.

Sequence diagram illustrating the handshake between the user interface and the backend for briefing creation.
Sources: apps/web/src/features/chat/state/useChatPanelController.ts:86-118, apps/web/src/features/chat/state/useChatPanelController.ts:153-200

Key Logic and Data Structures

Interaction Handlers

The system uses a set of standardized handlers to manage user actions within the message stream.

Action	Handler Function	Description
Select Intent	selectIntent	Sends the chosen research goal to the API to generate a specific plan.
Approve Plan	approvePlan	Confirms the AI-generated steps and starts agent execution.
Retry	retryFailedBriefing	Restarts the generation process if a step fails or times out.
Navigate	navigateToBriefing	Transitions the user from the chat sidebar to the full briefing document.

Sources: apps/web/src/features/chat/state/useChatPanelController.ts:153-247, apps/web/src/features/chat/components/ChatPanel.tsx:61-68

Message Mapping Logic

The chatMessageMapper is responsible for transforming raw BriefingResponse objects and BriefingRunSummaryResponse data into ChatMessage arrays. It handles the "upsert" logic to ensure that mutable messages (like progress bars) are updated in place rather than appended as new messages.

• Initial Bootstrap: Creates the first system message and the intent selector.
• Merge Logic: When a briefing update is received via polling, mergeBriefingMessages identifies if it should show a plan_preview or step_progress based on the briefing status.
• Status Handling: Once a briefing reaches a terminal status (ready or failed), it appends the final result or error message.

Sources: apps/web/src/features/chat/state/chatMessageMapper.ts:64-83, apps/web/src/features/chat/state/chatMessageMapper.ts:158-210

Execution Tracking

The UI tracks execution progress at two levels:

1. Run Level: Overall duration, tool call counts, and synthesis status.
2. Step Level: Individual subagent status (running, succeeded, failed), attempt counts, and resource usage (web searches, references).

Sources: apps/web/src/features/chat/types.ts:67-85, apps/web/src/features/chat/state/chatMessageMapper.ts:117-148

Conclusion

The Chat & Interaction UI provides a controlled, step-by-step workflow for briefing generation. By combining stateful polling, specialized message types for execution progress, and a polymorphic message mapper, it enables a complex background agent process (defined in AiSubagentExecutionRunner.kt) to be rendered as a readable and actionable conversation.

Sources: apps/web/src/features/chat/state/useChatPanelController.ts