Architecture Overview
The chat system is built around a centralized state orchestrator,ChatConsolePanel, which coordinates several specialized hooks and sub-components.
Component Relationship
The following diagram maps the logical “Chat Workspace” to the React components and hooks that implement them. Diagram: Chat Interface Component Mapping Sources: apps/web/src/chat/ChatConsolePanel.tsx#81-168, apps/web/src/chat/ChatConsoleWorkspaceView.tsx#50-193Session Management and Lineage
Sessions in Palyra are not just linear logs; they support branching and versioning (checkpoints).Session Lifecycle (useChatSessions)
The useChatSessions hook manages the catalog of available sessions, handling creation, renaming, archiving, and switching.
- Creation: Sessions can be created fresh via
/newor the UI apps/web/src/chat/useChatSessions.ts#176-178. - Persistence: It uses the
listSessionCatalogandresolveChatSessionAPI endpoints apps/web/src/chat/useChatSessions.ts#99-106.
Branching and Lineage
Palyra supports “Branching,” allowing a user to fork a session from a specific point in time.- Lineage Hints: The UI provides visual cues about where a session originated (e.g., “Active branch from [Parent] at run [ID]”) apps/web/src/chat/chatShared.tsx#38-39.
- Implementation:
buildSessionLineageHintformats the relationship between parent and child sessions apps/web/src/chat/chatShared.test.ts#75-101.
Run Orchestration and Streaming
TheuseChatRunStream hook is the core engine for active agent interactions. It manages the lifecycle of a “Run” within a session.
Data Flow: Run Events to UI
The daemon streams events (NDJSON) which are processed and transformed intoTranscriptEntry objects.
Diagram: Stream Processing Pipeline
- Token Batching: To maintain UI performance, assistant tokens are batched before updating the React state apps/web/src/chat/chatShared.tsx#230-244.
- Windowing: To prevent DOM bloat, the transcript is limited by
MAX_RENDERED_TRANSCRIPT(default 120 items) while keepingMAX_TRANSCRIPT_RETENTION(800 items) in memory apps/web/src/chat/chatShared.tsx#25-26.
The Chat Composer and Slash Commands
TheChatComposer handles user input, file attachments, and the shared slash command registry.
Slash Command Registry
Slash commands are shared between the Web Console and the CLI TUI. They are defined in a central JSON registry.- Registry:
chatCommandRegistry.jsondefines metadata likeexecution(local vs server) andsurfaces(web vs tui) apps/web/src/chat/chatCommandRegistry.json#1-13. - Palette:
useChatSlashPaletteprovides autocomplete suggestions as the user types/apps/web/src/chat/ChatConsolePanel.tsx#61-61.
Context Budgeting
Before sending a message, the composer calculates a “Context Budget” to warn users if the prompt is too large for the model’s window.- Calculation:
useChatContextBudgetaggregates baseline tokens, draft text tokens, and attachment estimates apps/web/src/chat/chatShared.tsx#61-72. - Limits: Soft limit at 12,000 tokens; hard limit at 16,000 tokens apps/web/src/chat/chatShared.tsx#29-30.
Continuity Operations
The interface provides tools for managing the long-term health and “undo” capability of a session.| Feature | Code Entity | Description |
|---|---|---|
| Compaction | runChatCompactionFlow | Reduces session size by summarizing older turns into artifacts apps/web/src/chat/ChatConsolePanel.tsx#24-24. |
| Undo Checkpoints | ChatCheckpointRecord | Allows reverting a session to a known good state apps/web/src/chat/ChatConsolePanel.tsx#6-6. |
| Recall Preview | useRecallPreview | Shows what information the agent will “recall” from memory/RAG for the current draft apps/web/src/chat/useRecallPreview.ts#1-1. |
| Context Preview | useContextReferencePreview | Resolves [[references]] in the composer text before submission apps/web/src/chat/useContextReferencePreview.ts#1-1. |
Inline Approvals
When an agent attempts a high-risk tool call, anapproval_request entry appears in the transcript.
- Controls:
ApprovalRequestControlsallows the user to Approve or Deny with a specificApprovalScope(once, session, or timeboxed) apps/web/src/chat/chatShared.tsx#141-221.