Chat Console Architecture
The chat interface is implemented as a multi-column React layout centered around theChatConsolePanel. It coordinates state between the conversation transcript, the composer, and a diagnostic “Inspector” column.
Key Components
| Component | Responsibility | Source |
|---|---|---|
ChatConsolePanel | Central orchestrator for chat state, streaming, and side-panel actions. | apps/web/src/chat/ChatConsolePanel.tsx#71-77 |
ChatComposer | Handles user input, slash commands, file uploads, and context budget visualization. | apps/web/src/chat/ChatComposer.tsx#53-84 |
ChatTranscript | Renders the message history, including tool calls, A2UI frames, and inline approvals. | apps/web/src/chat/ChatTranscript.tsx |
ChatInspectorColumn | Displays workspace signals: budget, session lineage, background tasks, and search. | apps/web/src/chat/ChatInspectorColumn.tsx#109-155 |
Data Flow: User Input to Daemon
The following diagram illustrates how a user message moves from the React UI to the Rust backend and starts a streamed run. Chat Run Initiation Flow Sources: apps/web/src/chat/ChatConsolePanel.tsx#120-156, crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#139-182, apps/web/src/chat/useChatRunStream.tsRun Streaming (NDJSON)
Palyra uses a line-delimited JSON (NDJSON) stream for real-time updates. This allows the UI to render incremental assistant tokens, tool execution status, and A2UI patches without waiting for the full run completion.Stream Handling in the UI
TheuseChatRunStream hook manages the fetch request to the stream endpoint. It parses each line as a TranscriptEntry and updates the local state.
- Incremental Tokens: Assistant tokens are buffered and appended to the active message entry.
- Run Lifecycle: The hook tracks
run_id,run_status, andrun_tape(the event log of the current run). - Termination: Handles stream closure and error states (e.g., model timeouts or policy denials).
Context Budget & Previews
To prevent context window overflow and provide transparency, the UI calculates a “Context Budget” before the user sends a message.Budget Calculation
ThebuildContextBudgetSummary function estimates the token count for the current session baseline, the draft text, active attachments, and context references.
- Soft Limit: 12,000 tokens. apps/web/src/chat/chatShared.tsx#22
- Hard Limit: 16,000 tokens. apps/web/src/chat/chatShared.tsx#23
- Visual Feedback: The budget bar changes “tone” (default, warning, danger) based on the ratio of estimated tokens to limits. apps/web/src/chat/chatShared.tsx#54-65
Context & Recall Previews
The UI provides real-time previews of what information will be “recalled” by the daemon:useContextReferencePreview: Parses the composer text for@path/to/filesyntax and resolves file content previews via the daemon. apps/web/src/chat/useContextReferencePreview.tsuseRecallPreview: Simulates the daemon’s RAG (Retrieval-Augmented Generation) process to show which memory items or workspace files will be auto-injected based on the current query. apps/web/src/chat/useRecallPreview.ts
Tool Approvals & A2UI
Palyra integrates security and UI updates directly into the chat transcript.Approval Request Handling
When a tool requires human-in-the-loop (HITL) authorization, the daemon emits anapproval_request event.
- Inline Controls: The
ChatTranscriptrendersApprovalRequestControlsapps/web/src/chat/chatShared.tsx#230-235. - Decision Scopes: Operators can approve for “once”, the “session”, or a “timeboxed” duration apps/web/src/chat/chatShared.tsx#170.
- Action: Decisions are sent via
decideInlineApproval, which calls the daemon’s approval resolution endpoint. apps/web/src/chat/ChatConsolePanel.tsx#148
A2UI (Agent-to-UI) Updates
Agents can publish structured UI updates via thea2ui event type.
- Surfaces: Unique UI “surfaces” are tracked in the
a2uiDocumentsstate apps/web/src/chat/ChatConsolePanel.tsx#135. - Rendering: The transcript renders these as interactive frames or specialized widgets.
- Canvas Frames: URLs starting with
/canvas/v1/frame/are rendered in sandboxed iframes. apps/web/src/chat/chatShared.tsx#24
Session Lifecycle Management
The console supports advanced session operations to manage long-running conversations.Compaction & Checkpoints
Long sessions are managed through Compaction, which summarizes older events to free up context budget.- Preview vs Apply: Operators can
/compact previewto see what will be condensed or/compact applyto commit the change. apps/web/src/chat/chatShared.tsx#145-150 - Checkpoints: Compaction automatically creates a
ChatCheckpointRecord, allowing the session to be restored to its pre-compaction state if information was lost. apps/web/src/chat/chatConsoleUtils.ts#81-100
Branching
The/branch command creates a new child session from the current run’s state. This is useful for exploring alternative paths without polluting the main session history. apps/web/src/chat/chatShared.tsx#102-106
Entity Relationship: Session & Run
Sources: crates/palyra-daemon/src/application/session_compaction.rs#76-126, apps/web/src/chat/chatShared.tsx#76-163, crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#36-105