palyrad daemon via the Console API. The system manages complex state transitions including asynchronous session bootstrapping, CSRF-protected mutations, and real-time diagnostic streaming.
ConsoleApiClient Implementation
TheConsoleApiClient is the primary interface for all frontend-to-backend communication. It abstracts the underlying HTTP transport, manages session headers, and enforces security protocols like CSRF.
Method Categories
| Category | Role | Key Methods |
|---|---|---|
| Auth | Session lifecycle and handoff | getSession, login, consumeDesktopHandoff |
| Chat | Session and run management | listSessions, createSession, createRun, getChatStream |
| Inventory | Node and device management | listInventory, getDeviceDetail, rotateDeviceKey |
| Diagnostics | System health and audit | getDiagnostics, listAuditEvents, listSupportJobs |
| Config | Runtime mutation | inspectConfig, validateConfig, mutateConfig, recoverConfig |
CSRF Enforcement
The client implements a “fail-closed” security model for mutating requests (POST, PUT, DELETE). It requires a validcsrf_token obtained during the session bootstrap or login phase.
- Logic: If a mutating request is attempted without a token, the client throws an error before the network call is initiated apps/web/src/consoleApi.test.ts#92-106.
- Header: Validated tokens are attached via the
x-palyra-csrf-tokenheader apps/web/src/consoleApi.test.ts#87-88.
NDJSON Streaming
For chat interactions, the client utilizesgetChatStream to handle Network Delimited JSON (NDJSON). This allows the UI to render incremental LLM tokens and tool execution updates as they arrive from the GatewayService.
Sources: apps/web/src/consoleApi.ts#1-100, apps/web/src/consoleApi.test.ts#44-90.
State Management and Session Bootstrap
State is centralized in theuseConsoleAppState hook, which orchestrates the transition from a “booting” state to an active operator session.
Session Bootstrap with Exponential Backoff
When the console loads, it attempts to recover an existing session. To handle transient daemon unavailability (e.g., during a restart), the system employs a retry loop:- Attempts: Up to 5 retries apps/web/src/console/useConsoleAppState.tsx#56-56.
- Backoff: Delay increases by
150ms * attemptapps/web/src/console/useConsoleAppState.tsx#55-101. - Retryable Errors: Only 401 (Unauthorized), 403 (Forbidden), and 429 (Rate Limited) trigger retries apps/web/src/console/useConsoleAppState.tsx#73-85.
Desktop Handoff Flow
The console supports a seamless transition from the Desktop App via a “Handoff Token.”- The app detects a
desktop_handoff_tokenin the URL query parameters apps/web/src/console/useConsoleAppState.tsx#132-142. - It calls
api.consumeDesktopHandoff(token)apps/web/src/console/useConsoleAppState.tsx#114-114. - Upon success, the token is stripped from the address bar to prevent replay or accidental sharing apps/web/src/console/useConsoleAppState.tsx#144-152.
Section TTL Auto-Refresh
To keep diagnostics and status chips current without overwhelming the daemon, the console implements TTL-based background refreshing.- Overview/Diagnostics: 10 seconds apps/web/src/console/useConsoleAppState.tsx#42-42.
- Channels: 8 seconds apps/web/src/console/useConsoleAppState.tsx#44-44.
- Config/Secrets: 15 seconds apps/web/src/console/useConsoleAppState.tsx#48-49.
Data Flow: Code Entity Space
The following diagrams illustrate the relationship between React UI components, the API client, and the backend data models.Session Initialization Sequence
This diagram shows howuseConsoleAppState interacts with ConsoleApiClient and the backend ConsoleSession model.
Sources: apps/web/src/App.tsx#11-33, apps/web/src/console/useConsoleAppState.tsx#87-106, crates/palyra-control-plane/src/models.rs#7-16.
Config Mutation Workflow
This diagram maps the UI interaction in theOperationsSection to the ConfigMutationEnvelope in the backend.
Sources: apps/web/src/console/sections/OperationsSection.tsx#85-92, apps/web/src/consoleApi.ts#153-175, crates/palyra-control-plane/src/models.rs#164-174.
Technical Detail: Diagnostics and Support
The console provides a deep-dive interface for system troubleshooting via theOperationsSection and SupportSection.
Diagnostics Snapshot
ThediagnosticsSnapshot is a comprehensive JSON object containing:
- Model Provider State: Circuit breaker status and latency apps/web/src/console/sections/OperationsSection.tsx#106-111.
- Observability: Recent failure logs and operation counters apps/web/src/console/sections/OperationsSection.tsx#56-60.
- Doctor Recovery: Status of automated fix-it jobs apps/web/src/console/sections/OperationsSection.tsx#137-145.
Support Bundle Lifecycle
Support bundles are managed as asynchronous jobs to ensure large exports do not timeout the browser session.- Queueing:
createSupportBundlesends a request to the daemon apps/web/src/console/sections/SupportSection.tsx#178-181. - Tracking: The
SupportSectionpollssupportBundleJobsto show progress (Queued -> Running -> Succeeded/Failed) apps/web/src/console/sections/SupportSection.tsx#97-101. - Retrieval: Once succeeded, the
output_pathis used to download the ZIP artifact apps/web/src/console/fixtures/m56ControlPlane.ts#180-198.