Component Architecture
The chat interface is composed of several specialized React components that separate the conversation transcript from debugging data and session management.Key Components
| Component | Responsibility |
|---|---|
ChatConsolePanel | The top-level orchestrator that manages state for the entire chat view, including session switching and run streaming apps/web/src/chat/ChatConsolePanel.tsx#81-88. |
ChatConsoleWorkspaceView | Defines the three-column layout: Sessions Sidebar, Main Conversation, and Inspector Column apps/web/src/chat/ChatConsoleWorkspaceView.tsx#50-75. |
ChatComposer | The input area supporting multi-line text, slash commands, file attachments, and context budget visualization apps/web/src/chat/ChatComposer.tsx#66-102. |
ChatTranscript | Renders the message history, including specialized blocks for tool calls, A2UI surfaces, and approval requests apps/web/src/chat/ChatTranscript.tsx. |
ChatInspectorColumn | A dedicated sidebar for technical metadata: A2UI surfaces, background tasks, session lineage, and JSON payload inspection apps/web/src/chat/ChatInspectorColumn.tsx#109-155. |
Workspace Data Flow
The following diagram illustrates how user input in theChatComposer triggers a stream that updates the ChatTranscript and ChatInspectorColumn.
Title: Chat Console Data Flow
Sources: apps/web/src/chat/ChatConsolePanel.tsx#132-168, apps/web/src/chat/ChatComposer.tsx#145-151, apps/web/src/chat/useChatRunStream.ts
Streaming Lifecycle (NDJSON)
Palyra uses a streaming protocol based on NDJSON (Newline Delimited JSON) to provide real-time feedback during agent execution. TheuseChatRunStream hook manages the connection to the daemon’s gateway apps/web/src/chat/ChatConsolePanel.tsx#162-168.
- Initiation:
sendMessageis called, sending a POST request to the gateway. - NDJSON Processing: The client parses incoming chunks into discrete
TranscriptEntryobjects apps/web/src/chat/chatShared.tsx#97-114. - Entry Types:
user/assistant: Standard message bubbles.tool: Displays tool execution status and results.approval_request: Pauses the stream for user intervention apps/web/src/chat/chatShared.tsx#88.a2ui: Signals that a UI surface should be rendered or patched apps/web/src/chat/chatShared.tsx#90.
- Token Batching: To prevent UI lag, assistant tokens are collected and applied in batches via
applyAssistantTokenBatchapps/web/src/chat/chatShared.tsx#230-235.
Context Budget Estimation
TheChatComposer includes a real-time Context Budget indicator to help operators avoid model context window overflows.
- Calculation: The
useChatContextBudgethook estimates the total token count by summing the baseline session tokens, the current draft text, resolved context references, and file attachments apps/web/src/chat/chatShared.tsx#61-72. - Limits: The system defines a
SOFT_LIMIT(12,000 tokens) and aHARD_LIMIT(16,000 tokens) apps/web/src/chat/chatShared.tsx#29-30. - Visual Feedback: The budget bar changes its “tone” (
default,warning,danger) based on the ratio of estimated tokens to the limit apps/web/src/chat/ChatComposer.tsx#152-163.
Slash Commands & Suggestions
The Chat Console implements a robust slash command system that provides parity between the Web UI and the TUI (Terminal User Interface).- Registry: Commands are defined in
chatCommandRegistry.jsonand categorized by surface (web,tui) apps/web/src/chat/chatCommandRegistry.ts#3-18. - Palette: The
useChatSlashPalettehook manages the visibility of the command suggestion listbox apps/web/src/chat/useChatSlashPalette.ts#62-72. - Entity Suggestions: Commands like
/resume,/checkpoint, and/delegatedynamically fetch entity catalogs (sessions, checkpoints, or agents) to provide auto-completion apps/web/src/chat/chatCommandSuggestions.ts#162-182. - Execution: Commands are executed via
executeChatSlashCommand, which routes the command to the appropriate handler (e.g.,branchCurrentSessionActionfor/branch) apps/web/src/chat/chatSlashActions.ts#147-186.
Human-in-the-Loop (HITL) & Approvals
When an agent attempts a sensitive action (e.g., writing to a file or making a payment), the stream emits anapproval_request.
- UI Controls: The
ApprovalRequestControlscomponent allows the operator to approve or deny the request apps/web/src/chat/chatShared.tsx#141-159. - Scope: Operators can approve for a single instance (
once), the entiresession, or atimeboxedduration apps/web/src/chat/chatShared.tsx#81. - Drafting: The
ApprovalDraftstate tracks the reason and TTL (Time-To-Live) for the decision before it is committed to the backend apps/web/src/chat/chatShared.tsx#116-121.
Compaction & Checkpoints
To manage long-running conversations, Palyra supports session state manipulation.- Checkpoints: Operators can create named snapshots of a session. The
/undocommand uses “undo-safe” checkpoints created automatically before new runs to restore state if an agent goes off-track apps/web/src/chat/chatSlashActions.ts#17-34, apps/web/src/chat/chatCommandSuggestions.ts#100-108. - Compaction: The
/compactcommand (invokingrunChatCompactionFlow) summarizes or removes old transcript entries to reclaim context budget while preserving essential information apps/web/src/chat/ChatConsolePanel.tsx#24.
Session Branching & Lineage
Palyra treats conversations as a tree rather than a linear list.- Branching: The
/branchcommand creates a new child session from the current state. This is handled bybranchCurrentSessionActionapps/web/src/chat/chatSessionActions.ts#153-167. - Lineage: The
ChatInspectorColumndisplays the session’s “Lineage” (e.g., parent session IDs) and “Branch state” to help operators track where a conversation diverged apps/web/src/chat/ChatInspectorColumn.tsx#192-198.