Skip to main content
The Palyra ecosystem utilizes a set of standardized JSON envelope schemas and a specialized Agent-to-User Interface (A2UI) protocol to ensure type-safe, validated, and secure communication between the daemon, the web/desktop consoles, and external integration points.

​
JSON Envelope Schemas

Palyra defines several top-level envelope structures in schemas/json/envelopes/ to wrap different types of data payloads. These envelopes ensure that versioning, identification, and metadata are consistently handled across the system.
EnvelopePurposeKey Fields
a2ui-envelope.v1.jsonEncapsulates A2UI documents and incremental patches.v, id, surface, patch, experimental
message-envelope.v1.jsonStandard wrapper for chat messages and system notifications.v, id, timestamp, payload
webhook-envelope.v1.jsonFormat for egress notifications to external services.v, event_type, resource_id, data
config-export/import.v1.jsonPortable format for migrating daemon configuration and profiles.v, kind, metadata, encrypted_payload

​
A2UI Envelope Structure

The A2UI envelope is specifically designed for high-frequency UI updates. It supports an incremental patch mechanism (RFC 6902-inspired) to avoid re-sending the entire UI state over the wire. Sources: schemas/json/envelopes/a2ui-envelope.v1.json#1-201

​
A2UI Protocol Implementation

The A2UI protocol allows an agent to describe a structured interface (forms, tables, charts) that the client renders natively. This bypasses the security risks of dangerouslySetInnerHTML and provides a consistent look and feel across different surfaces.

​
Data Flow: From Patch to Render

The following diagram illustrates how an A2UI payload is processed from the Rust-based daemon validation to the React-based renderer. A2UI Processing Pipeline Sources: crates/palyra-a2ui/src/lib.rs#84-99, apps/web/src/a2ui/normalize.ts#33-77, apps/web/src/a2ui/renderer.tsx#36-63

​
Component Normalization and Sanitization

Before rendering, the normalizeA2uiDocument function in the web client enforces strict limits and sanitizes inputs to prevent layout breaking or injection attacks.
  • Identifier Sanitization: All component IDs are processed via sanitizeIdentifier to ensure they are valid DOM attributes apps/web/src/a2ui/normalize.ts#174-175.
  • Resource Limits: RenderInputLimits (defined in types.ts) constrain the number of components, string lengths, and table rows to prevent browser OOM or DoS via massive payloads apps/web/src/a2ui/types.ts#162-174.
  • Tone Mapping: Text components use a restricted set of tones (normal, muted, success, critical) mapped to CSS classes apps/web/src/a2ui/types.ts#43-46.

​
A2UI Renderer Components

The A2uiRenderer maps JSON component types to React components:
TypeReact ImplementationProps Source
textp with .a2ui-textA2uiTextProps
markdownSanitizedMarkdownA2uiMarkdownProps
listol / ulA2uiListProps
tableEntityTableA2uiTableProps
formAppFormA2uiFormProps
chartA2uiBarChartA2uiChartProps
Sources: apps/web/src/a2ui/renderer.tsx#116-147, apps/web/src/a2ui/types.ts#37-140

​
Experimental Governance

A2UI includes a first-class experimental block for features in rollout. This block enforces transparency and security reviews before an experimental UI surface can be rendered.

​
Security Gates

The protocol requires an experimental document to provide:
  1. Track ID: A unique identifier for the experiment apps/web/src/a2ui/normalize.ts#149.
  2. Feature Flag: The specific daemon-side flag controlling the feature apps/web/src/a2ui/normalize.ts#150.
  3. Security Review: A checklist of completed security assessments apps/web/src/a2ui/normalize.ts#155.
  4. Consent Enforcement: If ambient_mode is set to push_to_talk, the protocol strictly requires consent_required: true. Failure to provide this results in a validation error apps/web/src/a2ui/normalize.ts#123-128.
A2UI Security Validation Diagram Sources: crates/palyra-a2ui/src/lib.rs#25-27, apps/web/src/a2ui/tests/renderer.snapshot.test.tsx#56-79

​
Patching and State Management

The palyra-a2ui Rust crate provides utilities for generating and validating incremental updates to the UI state.

​
Styling and Layout

A2UI components are styled using Tailwind CSS and the HeroUI framework. The base layout for the renderer is defined as a CSS grid with a standard 1rem gap to ensure consistent spacing across different component combinations. Sources: apps/web/src/styles.css#140-153, apps/web/src/a2ui/renderer.tsx#38-42