Chat Architecture Overview
The chat interface is implemented as a multi-column workspace. It separates the primary conversation from diagnostic “signals” to maintain readability while providing full transparency into agent operations.Key Components
ChatConsolePanel: The top-level container that orchestrates state between sessions, streams, and the inspector apps/web/src/chat/ChatConsolePanel.tsx#81-88.ChatComposer: The input area supporting slash commands, file attachments, and real-time context budget calculation apps/web/src/chat/ChatComposer.tsx#66-102.ChatTranscript: Renders the conversation history, including user messages, assistant responses, and inline tool calls apps/web/src/chat/ChatTranscript.tsx.ChatInspectorColumn: A persistent sidebar for “Workspace signals” such as session lineage, background tasks, and A2UI surfaces apps/web/src/chat/ChatInspectorColumn.tsx#109-155.A2UI Renderer: A specialized engine for rendering structured UI components (forms, charts, tables) sent by the agent apps/web/src/a2ui/renderer.tsx#36-63.
Data Flow: Chat Stream and Sessions
The interface relies on two primary hooks for data synchronization:useChatSessions: Manages the session catalog, allowing users to create, rename, archive, and switch between conversations apps/web/src/chat/useChatSessions.ts#37-42.useChatRunStream: Connects to the daemon’s gRPC/NDJSON gateway to handle live message streaming, tool updates, and run lifecycle events apps/web/src/chat/ChatConsolePanel.tsx#132-168.
Chat Interface Logic Flow
This diagram bridges the React component space with the underlying streaming and command logic. Sources: apps/web/src/chat/ChatComposer.tsx, apps/web/src/chat/chatCommandRegistry.ts, apps/web/src/chat/useChatRunStream.ts, apps/web/src/chat/useChatContextBudget.tsSlash Commands and Palette
Palyra uses a shared command registry defined inchatCommandRegistry.json apps/web/src/chat/chatCommandRegistry.json#1-133. This ensures parity between the Web Console and the TUI apps/web/src/chat/chatCommandRegistry.ts#33-36.
Command Execution
Commands are categorized by their execution target:local: Handled entirely within the UI (e.g.,/help) apps/web/src/chat/chatCommandRegistry.json#8.server: Dispatched to the daemon as a specific run action (e.g.,/branch,/undo,/interrupt) apps/web/src/chat/chatCommandRegistry.json#32.
The Slash Palette
TheuseChatSlashPalette hook provides real-time suggestions as the user types. It filters the registry based on keywords and surface compatibility (web vs tui) apps/web/src/chat/chatCommandRegistry.ts#38-42.
| Command | Synopsis | Purpose |
|---|---|---|
new | /new [label] | Create a fresh session apps/web/src/chat/chatCommandRegistry.json#27. |
branch | /branch [label] | Fork the current session into a new lineage apps/web/src/chat/chatCommandRegistry.json#196. |
undo | /undo [id] | Revert to a previous ChatCheckpointRecord apps/web/src/chat/chatCommandRegistry.json#147. |
interrupt | /interrupt | Force stop a running agent apps/web/src/chat/chatCommandRegistry.json#159. |
Context Budget and Compaction
To prevent context window overflow, the UI provides real-time visibility into token usage viauseChatContextBudget.
Budget Calculation
The system calculates aContextBudgetSummary including:
- Baseline Tokens: The existing session history apps/web/src/chat/chatShared.tsx#62.
- Draft Tokens: The current text in the composer apps/web/src/chat/chatShared.tsx#63.
- Attachment Tokens: Estimated tokens for uploaded files/images apps/web/src/chat/chatShared.tsx#65.
Session Compaction and Branching
When a session nears its limit, users can trigger Compaction:- Preview: The server plans which messages to summarize or prune apps/web/src/console/sections/SessionsSection.tsx#156-183.
- Apply: The server generates a
ChatCompactionArtifactRecordand updates the session tape apps/web/src/console/sections/SessionsSection.tsx#185-202.
A2UI: Agent-to-User Interface
A2UI is a protocol for agents to push structured interactive elements to the console. These are rendered via theA2uiRenderer.
Supported Components
The renderer handles several component types defined inA2uiComponent apps/web/src/a2ui/types.ts:
- Forms: Agents can request structured input from the user apps/web/src/a2ui/renderer.tsx#180-227.
- Tables: For displaying datasets with sortable columns apps/web/src/a2ui/renderer.tsx#149-173.
- Charts: Visualizing trends or metrics apps/web/src/a2ui/renderer.tsx#143.
- Markdown: Rich text descriptions apps/web/src/a2ui/renderer.tsx#122-123.
Canvas Rendering
A2UI documents can be designated as “Canvas” surfaces. TheChatConsolePanel tracks these via a2uiDocuments and provides a dedicated view for long-lived UI state that persists across multiple turns apps/web/src/chat/ChatConsolePanel.tsx#147.
A2UI Component Mapping
This diagram maps the A2UI JSON protocol to the React rendering logic. Sources: apps/web/src/a2ui/renderer.tsx, apps/web/src/a2ui/types.tsTranscript Retention and Search
To maintain performance, the UI implements a sliding window for the rendered transcript:- Retention: Up to 800 records are kept in the local state apps/web/src/chat/chatShared.tsx#25.
- Rendering: Only the most recent 120 items are actively rendered in the DOM apps/web/src/chat/chatShared.tsx#26.
Search and Pinning
Operators can search the session history usingsearchChatTranscript apps/web/src/chat/chatConsoleOperations.ts#25. Important events (like specific tool outputs or assistant conclusions) can be pinned using pinChatTranscriptRecord, which creates a ChatPinRecord for quick access in the inspector sidebar apps/web/src/chat/ChatConsolePanel.tsx#22.
Sources: apps/web/src/chat/chatShared.tsx, apps/web/src/chat/ChatConsolePanel.tsx, apps/web/src/chat/chatConsoleOperations.ts