Skip to main content
The ConsoleApiClient is the primary interface between the React-based Web Console and the palyrad Control Plane API. It encapsulates the request lifecycle, including authentication, CSRF protection, retry logic, and the handling of NDJSON (Newline Delimited JSON) streams for real-time chat interactions.

​
Request Lifecycle & Security

The ConsoleApiClient manages a stateful connection to the backend. It handles the transition from an unauthenticated state to an active session, ensuring all subsequent mutating requests carry the necessary security tokens.

​
Authentication & CSRF

The client uses a two-step process for secure communication:
  1. Session Retrieval: The client fetches the current session using getSession() apps/web/src/consoleApi.ts#1044-1055.
  2. CSRF Protection: For any mutating HTTP method (POST, PUT, DELETE, PATCH), the client requires an x-palyra-csrf-token header apps/web/src/consoleApi.ts#1330-1341. If a session is active but the token is missing during a mutation, the client “fails closed” and throws an error apps/web/src/consoleApi.test.ts#92-106.

​
Retry & Timeout Logic

The client implements automatic retries for specific failure modes:
  • 429 Too Many Requests: The boot sequence retries the session fetch if rate limits are hit apps/web/src/App.test.tsx#38-67.
  • Timeouts: Default fetch timeouts are managed to prevent UI hangs during backend migrations or heavy loads.

​
Data Flow: Request to Response

The following diagram illustrates the lifecycle of a mutating request through the ConsoleApiClient. Mutating Request Lifecycle Sources: apps/web/src/consoleApi.ts#1330-1355, apps/web/src/consoleApi.test.ts#44-90

​
Error Handling

All API errors are encapsulated in the ControlPlaneApiError class apps/web/src/consoleApi.ts#1016-1028. This class captures:
  • Status Code: The HTTP status returned by the server.
  • Error Code: A machine-readable string (e.g., missing_session, rate_limit_exceeded).
  • Message: A human-readable description for UI display.
The checkResponse private method ensures that non-2xx responses are parsed and converted into ControlPlaneApiError instances before reaching the application logic apps/web/src/consoleApi.ts#1343-1355. Sources: apps/web/src/consoleApi.ts#1016-1028, apps/web/src/consoleApi.ts#1343-1355

​
Chat & NDJSON Streaming

For real-time chat, the client utilizes NDJSON (Newline Delimited JSON) streaming. This allows the UI to render agent thoughts, tool calls, and message fragments as they are generated by the daemon.

​
streamChatRun Implementation

The streamChatRun method apps/web/src/consoleApi.ts#1217-1249 initiates a POST request and processes the response body as a stream. It uses a TextDecoderStream to parse the incoming bytes into strings, splits them by newlines, and yields ChatStreamLine objects apps/web/src/consoleApi.ts#1240-1247. Chat Stream Entity Mapping Sources: apps/web/src/consoleApi.ts#1217-1249, apps/web/src/consoleApi.ts#896-915

​
Key Data Contracts

The backend contract is defined by several key interfaces that ensure type safety between the Rust daemon and the TypeScript frontend.

​
Session & Catalog

InterfacePurpose
ChatSessionRecordBasic session metadata (ID, principal, device) apps/web/src/consoleApi.ts#17-27.
SessionCatalogRecordExtended record for the catalog UI, including token counts and run states apps/web/src/consoleApi.ts#29-49.
SessionCatalogSummaryAggregated stats (active/archived/pending approvals) apps/web/src/consoleApi.ts#51-56.

​
Usage & Monitoring

The ConsoleApiClient provides methods to query operational metrics via getUsageSummary apps/web/src/consoleApi.ts#1102-1110.

​
API Method Groups

The client is organized into functional groups matching the Web Console sections: Backend Contract Mapping Sources: apps/web/src/consoleApi.ts#17-49, apps/web/src/consoleApi.ts#110-122, apps/web/src/consoleApi.ts#1030-1320