Skip to main content
The ConsoleApiClient is the central TypeScript class responsible for all communication between the Palyra Web Console and the palyrad daemon. It implements the control-plane.v1 contract, providing a type-safe interface for session management, agent orchestration, system diagnostics, and vault operations.

​
Architecture Overview

The ConsoleApiClient acts as a high-level wrapper around the browser’s fetch API. It manages authentication state, enforces CSRF protection for mutating requests, and handles the parsing of NDJSON (Newline Delimited JSON) streams for real-time agent feedback.

​
Data Flow: Web Console to Daemon

The following diagram illustrates the lifecycle of a request from the UI through the ConsoleApiClient to the daemon’s HTTP surface. Console API Request Lifecycle Sources: apps/web/src/consoleApi.ts#36-106, apps/web/src/consoleApi.test.ts#44-90

​
Session Bootstrapping & Desktop Handoff

The Web Console follows a specific lifecycle to establish a session, especially when launched from the Palyra Desktop Companion.
  1. Handoff Token Check: On initial load, the app checks for a desktop_handoff_token in the URL search parameters apps/web/src/App.test.tsx#69-75.
  2. Handoff Consumption: If present, it calls /console/v1/auth/browser-handoff/session to exchange the short-lived token for a persistent session cookie and CSRF token apps/web/src/App.test.tsx#102-105.
  3. Standard Session Bootstrap: If no handoff token exists, it attempts to refresh the existing session via GET /console/v1/auth/session apps/web/src/consoleApi.test.ts#15-42.
  4. Retry Logic: The bootstrap process includes retries for transient errors (e.g., rate limits) before redirecting to the login screen apps/web/src/App.test.tsx#38-50.
Sources: apps/web/src/App.test.tsx#38-107, apps/web/src/App.tsx#11-33

​
Security: CSRF & Authentication

The ConsoleApiClient enforces strict security boundaries based on the HTTP method:

​
The control-plane.v1 Contract

Every response from the daemon includes a contract descriptor. The client and UI verify this to ensure protocol compatibility apps/web/src/console/fixtures/m56ControlPlane.ts#1-3.
FeatureRequirementImplementation
CredentialsincludeAlways passed via fetch init to support HttpOnly cookies.
CSRF Headerx-palyra-csrf-tokenSynchronized from the session response to all subsequent POSTs.
Contract Versioncontrol-plane.v1Verified in envelope interfaces like SessionCatalogListEnvelope.
Sources: apps/web/src/consoleApi.ts#58-73, apps/web/src/consoleApi.test.ts#44-60

​
Key API Methods & Interface Definitions

The client organizes methods by functional domains corresponding to the palyrad subsystems.

​
Routines & Automations

Manages cron jobs and manual triggers.

​
Vault & Secrets

Handles sensitive data with explicit “reveal” mechanics.

​
Diagnostics & Support

Sources: apps/web/src/consoleApi.ts#245-260, apps/web/src/console/sections/CronSection.tsx#183-203, apps/web/src/console/sections/SecretsSection.tsx#20-40

​
NDJSON Streaming

For Chat and Run execution, the ConsoleApiClient handles NDJSON streams. This allows the UI to render incremental updates (tokens, tool calls, and state changes) as they happen. Streaming Data Flow Sources: apps/web/src/consoleApi.ts#1-8, apps/web/src/consoleApi.test.ts#6-8

​
TypeScript Contract Definitions

The API uses rigorous interface definitions to ensure the UI matches the daemon’s JSON envelopes. 
// Example of the Session Catalog contract
export interface SessionCatalogRecord {
  session_id: string;
  session_key: string;
  principal: string;
  created_at_unix_ms: number;
  updated_at_unix_ms: number;
  total_tokens: number;
  archived: boolean;
  pending_approvals: number;
}

export interface SessionCatalogListEnvelope {
  contract: ContractDescriptor; // "control-plane.v1"
  sessions: SessionCatalogRecord[];
  summary: SessionCatalogSummary;
  page: PageInfo;
}
Sources: apps/web/src/consoleApi.ts#17-73