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 thepalyra-common crate. These enums are the source of truth for wire names used in JSON payloads, database records, and API responses.
Key Lifecycle Contracts
| Enum | Purpose | Canonical Wire Values |
|---|---|---|
RunLifecyclePhase | States of an agent run | queued, running, waiting_for_approval, paused, completed, failed, aborted, expired |
RunLifecycleHookPhase | Plugin execution points | before_run, before_tool, after_tool, before_delivery, after_run |
AuxiliaryTaskKind | Types of side-tasks | summary, recall_search, classification, extraction, objective_judge, vision |
AuxiliaryTaskState | Status of background work | pending, running, succeeded, failed, cancelled |
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 theRunStreamEvent 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-152Cross-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.
| Field | Type | Description |
|---|---|---|
section | HandoffSection | Target dashboard domain (e.g., approvals, chat, memory). |
sessionId | string | The active ULID for the chat session. |
runId | string | The specific run ULID to inspect. |
intent | HandoffIntent | Specific action: approve, resume-session, reopen-canvas, etc. |
source | TelemetrySurface | Originating surface: web, desktop, tui, mobile. |
- Parsing:
parseConsoleHandoffin apps/web/src/console/contracts.ts#154-172 handles the transition from URL search params to the typed object. - Normalization:
normalizeHandoffIntentmaps various string formats (snake_case, kebab-case) to the canonicalHandoffIntentapps/web/src/console/contracts.ts#199-213.
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 theSystemEventRecord table.
Telemetry Entity Mapping
The functiontoSystemEventPayload 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 inauxiliary_executor.rs.
Task Type Definitions
| Task Type | Input Contract | Output Contract | Default Budget |
|---|---|---|---|
Summary | plain_text_context | bounded_plain_text_summary | 1,200 tokens |
RecallSearch | query_plus_optional_context | ranked_recall_evidence_json | 1,600 tokens |
Classification | plain_text_payload | single_label_json | 600 tokens |
ObjectiveJudge | objective_judge_input_json | objective_judge_strict_json | 900 tokens |
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 therequest_id, thecommand(e.g.,SessionNew,RunCreate), and anidempotency_key.AcpCommandResultEnvelope: Returns theokstatus, theresultJSON, or aStableErrorEnvelope.
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