palyrad). These clients encapsulate the authentication lifecycle, CSRF protection, and the multiplexed communication required for both standard RESTful operations and real-time NDJSON (Newline Delimited JSON) streaming of agent activities.
System Architecture and Data Flow
The Control Plane architecture bridges the TypeScript-based Web Console and Rust-based external tools (like the Desktop App) to the daemon’s Axum-based HTTP transport layer.Control Plane Connectivity Diagram
This diagram illustrates how code entities across different languages and processes interact via the Control Plane. Sources: apps/web/src/consoleApi.ts#1-100, crates/palyra-control-plane/src/client.rs#33-40, crates/palyra-daemon/src/transport/http/router.rs#134-180, crates/palyra-daemon/src/transport/http/handlers/console/mod.rs#1-28Authentication and Session Lifecycle
The authentication flow is designed to support both browser-based sessions (Web Console) and direct token-based access (Admin/Desktop).- Session Bootstrap: The client attempts to retrieve an existing session via
GET /console/v1/auth/session. If a session cookie exists, the daemon returns aConsoleSessioncontaining a CSRF token. - Login: If no session exists, the client calls
login()with anadmin_token. - CSRF Management: For all mutating requests (POST, PUT, DELETE), the client must include the
x-palyra-csrf-tokenheader. TheConsoleApiClientautomatically manages this state once a session is established. - Handoff: The Desktop App can generate a
desktop_handoff_tokento transition a secure session from the local desktop process to the web browser.
Code Entity Mapping: Auth Flow
Sources: apps/web/src/consoleApi.ts#1330-1360, crates/palyra-control-plane/src/client.rs#67-83, apps/web/src/App.test.tsx#38-67, crates/palyra-control-plane/src/models.rs#7-16Key Client Methods and Capabilities
Both clients provide a comprehensive suite of methods for managing the Palyra environment.| Category | Key Methods (TypeScript / Rust) | Description |
|---|---|---|
| Chat | streamChatMessage, getSessionTranscript | Streams agent responses via NDJSON or fetches full history. |
| Config | mutateConfig, getRawConfig | Updates palyra.toml values at specific paths. |
| Browser | createBrowserSession, navigateBrowserSession | Proxies automation commands to palyra-browserd. |
| Governance | getUsageSummary, listUsagePolicies | Monitors token consumption and budget limits. |
| Security | listSecrets, revealSecret, decideApproval | Manages vault entries and human-in-the-loop decisions. |
Safe-Read Retry Policy
The RustControlPlaneClient implements a retry policy for “safe” (idempotent) read operations (GET requests). If a request fails due to transient network issues, it retries up to safe_read_retries times (defaulting to 1) crates/palyra-control-plane/src/client.rs#12-27.
NDJSON Streaming and Error Handling
ThestreamChatMessage method is the most complex interaction, utilizing Newline Delimited JSON to provide real-time updates from the Orchestrator.
Implementation Details
- Streaming: The client uses the
ReadableStreamAPI (in TS) orReceiverStream(in Rust) to process chunks of text as they arrive. - Line Parsing: Each line is parsed as a
ChatStreamLineapps/web/src/consoleApi.ts#500-520. - Error Envelopes: If the API returns a non-200 status, the response body is expected to be an
ErrorEnvelopecontaining a machine-readable error code and a human-readable message crates/palyra-control-plane/src/errors.rs#7-15.
Error Handling Logic
TheConsoleApiClient throws a ControlPlaneApiError which includes the HTTP status and the server-provided error details. This allows the UI to distinguish between “Rate Limit Exceeded” (429) and “Authentication Required” (401/403) apps/web/src/consoleApi.test.ts#4-8.
Security Middleware and Headers
All requests passing through the Control Plane are subject to security middleware in the daemon.- Rate Limiting:
admin_rate_limit_middlewareprevents brute-force attempts on the admin token crates/palyra-daemon/src/transport/http/router.rs#127-130. - Security Headers:
admin_console_security_headers_middlewareinjectsX-Content-Type-Options: nosniffand strictContent-Security-Policyheaders crates/palyra-daemon/src/transport/http/router.rs#131-133. - Principal Validation: The daemon validates the
x-palyra-principalandx-palyra-device-idheaders for all admin requests to ensure they match the authenticated session crates/palyra-daemon/tests/admin_surface.rs#46-64.