Skip to main content
This page details the implementation of the Palyra Console chat interface, the pipeline for preparing model prompts, and the “Durable Operating Surface” (Workspace). It covers how ephemeral chat transcripts are condensed into persistent knowledge through session compaction and how the system manages session branching and checkpoints.

​
Console Chat HTTP Handlers

The Console Chat API provides the bridge between the React-based Web Console and the underlying Orchestration Engine. These handlers manage session lifecycles, message streaming, and state mutations like renaming or resetting.

​
Key Handlers and Routes

​
Data Flow: Message Submission

  1. Authorization: authorize_console_session verifies the request crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#145.
  2. Attachment Processing: load_console_chat_message_attachments handles binary data crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#154-160.
  3. Parameter Delta: Builds the parameter_delta which includes explicit recall queries or context references crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#161-176.
  4. Run Execution: Spawns a background task to manage the RunStream and returns an NDJSON stream to the client crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#184-210.
Sources: crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#1-210

​
Prompt Preparation Pipeline

The provider_input.rs module is responsible for transforming a user’s raw input into a structured prompt for the LLM. This process involves augmenting the input with historical context, RAG (Retrieval-Augmented Generation) results, and workspace documents.

​
Pipeline Stages

  1. Vision Processing: build_provider_image_inputs extracts and validates image attachments based on MediaRuntimeConfig limits crates/palyra-daemon/src/application/provider_input.rs#107-155.
  2. Memory Augmentation: build_memory_augmented_prompt performs a vector search against the JournalStore to find relevant past interactions crates/palyra-daemon/src/application/provider_input.rs#158-200.
  3. Context References: Resolves [[tags]] or file paths into full text using preview_context_references crates/palyra-daemon/src/application/context_references.rs#72-129.
  4. Session Compaction Injection: If a session has been compacted, the summary and key facts are injected as a system-level block via render_compaction_prompt_block crates/palyra-daemon/src/application/provider_input.rs#14-17.

​
Context Reference Resolution

The system supports several types of inline references:

​
Pipeline Diagram

Title: Prompt Preparation Pipeline (Natural Language to Code Entity) Sources: crates/palyra-daemon/src/application/provider_input.rs#1-200, crates/palyra-daemon/src/application/context_references.rs#72-176

​
Session Compaction

Session Compaction is the process of condensing a long chat transcript into a concise summary and a set of “Durable Facts.” This prevents context window overflow and persists important information into the Workspace.

​
The Compaction Plan

A SessionCompactionPlan is generated by an LLM to determine:

​
Strategy: session_window_v1

The system uses a window-based strategy crates/palyra-daemon/src/application/session_compaction.rs#31:

​
Compaction Execution Flow

Title: Session Compaction and Workspace Persistence Sources: crates/palyra-daemon/src/application/session_compaction.rs#31-189, crates/palyra-daemon/src/application/mod.rs#1-14

​
Workspace and Durable Operating Surface

The Workspace represents the persistent filesystem-like view of an agent’s knowledge. It is composed of “Managed Blocks” within Markdown documents.

​
Document Types

The system recognizes several core document kinds crates/palyra-daemon/src/domain/workspace.rs#98-106:
  • README.md: High-level agent purpose and instructions.
  • MEMORY.md: Long-term facts and user preferences.
  • HEARTBEAT.md: Periodic status updates and active goals.

​
Managed Blocks

Documents use HTML comments to define regions that Palyra can safely edit:

​
Risk and Safety

The workspace implementation includes guardrails to prevent prompt injection and accidental leakage:

​
Workspace Structure Table

KindClassPrompt BindingPurpose
ReadmeCuratedSystemCandidateCore identity and instructions
MemoryCuratedSystemCandidateDurable facts from compaction
HeartbeatSystemNeverInternal state tracking
DailyUserManualOnlyUser-created logs
Sources: crates/palyra-daemon/src/domain/workspace.rs#1-230

​
Branching and Checkpoints

Palyra supports versioning the “Operating Surface” through Checkpoints and Session Branching.
  • Checkpoints: Created during compaction or manually, a OrchestratorCheckpointRecord stores the hashes of all workspace documents at a specific point in time crates/palyra-daemon/src/application/session_compaction.rs#184-189.
  • Branching: When a session is reset or branched, the agent can start from a previous checkpoint, allowing for “what-if” scenarios or recovery from poor compaction outcomes.
  • Deep Linking: The Web Console uses usePhase4DeepLinks to navigate directly to specific runs, compactions, or checkpoints apps/web/src/chat/usePhase4DeepLinks.ts#3-23.
Sources: crates/palyra-daemon/src/application/session_compaction.rs#184-189, apps/web/src/chat/usePhase4DeepLinks.ts#1-94