Skip to main content
This page details the JSON-based contracts and schemas that govern communication between the Palyra daemon (palyrad), the Web Console, the Desktop Application, and the CLI. These contracts ensure type safety and structural consistency across disparate surfaces (Rust, TypeScript, and TUI).

​
Runtime Vocabulary and Shared Enums

Palyra uses a shared runtime vocabulary defined in the palyra-common crate. These enums are the source of truth for wire names used in JSON payloads, database records, and API responses.

​
Key Lifecycle Contracts

The runtime_contract_enum! macro in crates/palyra-common/src/runtime_contracts.rs#19-84 enforces case-insensitive parsing and provides backward-compatible aliases for legacy labels. Sources: crates/palyra-common/src/runtime_contracts.rs#87-101, crates/palyra-common/src/runtime_contracts.rs#117-126

​
A2UI: Agent-to-UI Updates

The A2UI (Agent-to-UI) system allows agents to push structured UI updates to the console. These updates are embedded within the RunStreamEvent envelopes and rendered by the Web Console.

​
Data Flow: Agent to Renderer

Sources: crates/palyra-daemon/src/application/run_stream/tape.rs#1-10, apps/web/src/styles.css#144-152

​
Cross-Surface Handoff Tokens

Cross-surface handoff allows a user to move from one Palyra interface (e.g., CLI/TUI) to another (e.g., Web Console) while maintaining context (session ID, run ID, or specific intent).

​
Handoff Schema (CrossSurfaceHandoff)

The handoff is typically encoded as URL query parameters or a JSON token. Implementation Details: Sources: apps/web/src/console/contracts.ts#22-31, schemas/json/cross_surface_handoff.schema.json

​
UX Telemetry Events

UX Telemetry events are structured JSON logs that track operator behavior and “friction” without using third-party analytics. These are stored in the SystemEventRecord table.

​
Telemetry Entity Mapping

The function toSystemEventPayload in apps/web/src/console/contracts.ts#221-244 transforms the high-level UI event into the flat SystemEventRecord structure required by the daemon’s record_console_event handler. Sources: apps/web/src/console/contracts.ts#33-64, apps/web/src/console/contracts.ts#221-244, crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#117-128

​
Auxiliary Task Contracts

Auxiliary tasks (summarization, vision, etc.) use strict execution contracts that define their input/output shapes and resource budgets. These are defined in auxiliary_executor.rs.

​
Task Type Definitions

These contracts are immutable at runtime and ensure that model providers are selected based on the model_preference (e.g., LowCost vs LowLatency). Sources: crates/palyra-daemon/src/auxiliary_executor.rs#92-155, crates/palyra-daemon/src/auxiliary_executor.rs#47-54

​
ACP: Agent Control Protocol Envelopes

The Agent Control Protocol (ACP) bridge allows the Web Console to dispatch commands using the same envelope format as realtime clients.

​
Command Envelope Structure

  • AcpCommandEnvelope: Contains the request_id, the command (e.g., SessionNew, RunCreate), and an idempotency_key.
  • AcpCommandResultEnvelope: Returns the ok status, the result JSON, or a StableErrorEnvelope.
The bridge is implemented in console_acp_command_handler, which unwraps the HTTP body and routes it to dispatch_acp_command. Sources: crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#54-59, crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#65-74, crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#142-180