ConsoleApiClient and Application State

The Palyra Web Dashboard is a React-based Single Page Application (SPA) that serves as the primary operator interface for the daemon. It relies on a centralized ConsoleApiClient for all communication with the palyrad HTTP surface and uses a unified application state hook to manage domain-specific data, authentication, and the boot lifecycle.

ConsoleApiClient

The ConsoleApiClient class in apps/web/src/consoleApi.ts is the low-level transport layer for the dashboard. It encapsulates session management, CSRF protection, and specialized handling for streaming responses.

CSRF and Session Management

The client maintains an internal ConsoleSession object containing a csrf_token.

Automatic Injection: For any mutating HTTP request (POST, PUT, DELETE, PATCH), the client automatically injects the x-palyra-csrf-token header apps/web/src/consoleApi.ts#1612-1614.
Credentials: All requests are sent with credentials: "include" to ensure session cookies are transmitted apps/web/src/consoleApi.ts#1598-1600.
Fail-Closed: If a mutating request is attempted without a valid CSRF token in the client state, it throws a “Missing CSRF token” error apps/web/src/consoleApi.test.ts#92-106.

NDJSON Streaming

The client supports streaming runs and logs using Newline Delimited JSON (NDJSON).

streamChatRun: Uses the ReadableStream API to process lines as they arrive from the /console/v1/runs/:id/stream endpoint apps/web/src/consoleApi.ts#1335-1350.
Line Parsing: It buffers chunks and splits them by newline characters, parsing each complete line as a ChatStreamLine object apps/web/src/consoleApi.ts#1352-1370.

Data Flow: API Request Lifecycle

The following diagram illustrates how the ConsoleApiClient interacts with the browser’s fetch API and the daemon’s middleware. Console API Request Flow Sources: apps/web/src/consoleApi.ts#1591-1635, apps/web/src/consoleApi.test.ts#44-90

Application State and `useConsoleAppState`

The useConsoleAppState hook is the central state manager for the dashboard, located in apps/web/src/console/useConsoleAppState.tsx. It orchestrates the lifecycle of the application from boot to logout.

Domain Separation

To maintain maintainability, the state is split into logical domains, each managed by a specialized hook:

Auth: Managed via useAuthDomain, handling login/logout and session expiry apps/web/src/console/useConsoleAppState.tsx#21-21.
Overview: Managed via useOverviewDomain, providing diagnostics and deployment posture apps/web/src/console/useConsoleAppState.tsx#24-24.
Config: Managed via useConfigDomain, handling system settings and provider configurations apps/web/src/console/useConsoleAppState.tsx#23-23.
Support: Managed via useSupportDomain, for support bundle generation and log retrieval apps/web/src/console/useConsoleAppState.tsx#25-25.

Auto-Refresh Logic

The dashboard implements a TTL-based auto-refresh strategy for different sections. The shouldAutoRefreshSection function checks if a section’s data is stale based on defined intervals apps/web/src/console/useConsoleAppState.tsx#42-54.

Overview/Auth: 10 seconds.
Channels: 8 seconds.
Config/Secrets: 15 seconds.

Sources: apps/web/src/console/useConsoleAppState.tsx#164-240

Boot Lifecycle and Handoff Flow

The application follows a strict boot sequence to ensure the operator is authenticated before any domain data is fetched.

Boot Sequence

booting state: Initially true. The App component renders ConsoleBootScreen apps/web/src/App.tsx#16-18.
Handoff Check: The app checks for a desktop_handoff_token in the URL query parameters apps/web/src/console/useConsoleAppState.tsx#133-143.
Session Recovery:
- If a handoff token exists, it calls api.consumeDesktopHandoff(token) apps/web/src/console/useConsoleAppState.tsx#109-115.
- If no token or handoff fails, it attempts loadBootstrapSession which retries /console/v1/auth/session up to 5 times with exponential backoff to handle daemon startup latency apps/web/src/console/useConsoleAppState.tsx#88-107.
Transition: Once a session is acquired, booting is set to false. If no session is found, the user is redirected to ConsoleAuthScreen apps/web/src/App.tsx#20-30.

Desktop Handoff Token Flow

The “Desktop Handoff” is the primary mechanism for the Palyra Desktop app to open the web dashboard without requiring manual password entry. Handoff Token Exchange Sources: apps/web/src/console/useConsoleAppState.tsx#109-123, apps/web/src/App.test.tsx#69-107, apps/web/src/console/useConsoleAppState.tsx#145-153

Key Entities and Types

Entity	Description	File
`ConsoleSession`	Represents an active operator session, including principal, device, and CSRF token.	apps/web/src/consoleApi.ts#280-288
`SessionCatalogRecord`	Detailed metadata for a chat session, including token counts and approval status.	apps/web/src/consoleApi.ts#29-49
`UsageSummaryEnvelope`	Container for usage metrics, cost estimates, and timeline buckets.	apps/web/src/consoleApi.ts#124-130
`ControlPlaneApiError`	Custom error class for handling non-2xx responses from the daemon.	apps/web/src/consoleApi.ts#1568-1582

Sources: apps/web/src/consoleApi.ts#1-280