> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON Schemas and Cross-Surface Contracts

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * apps/desktop/ui/src/i18n.ts
  * apps/web/src/a2ui/**tests**/renderer.snapshot.test.tsx
  * apps/web/src/a2ui/normalize.ts
  * apps/web/src/a2ui/renderer.tsx
  * apps/web/src/a2ui/sample.ts
  * apps/web/src/a2ui/types.ts
  * apps/web/src/console/ConsoleShell.tsx
  * apps/web/src/console/components/layout/ConsoleAuthScreen.tsx
  * apps/web/src/console/contracts.test.ts
  * apps/web/src/console/contracts.ts
  * apps/web/src/console/i18n.ts
  * apps/web/src/console/sections/ApprovalsSection.tsx
  * apps/web/src/styles.css
  * crates/palyra-cli/src/tui/handoff.rs
  * crates/palyra-cli/src/tui/text.rs
  * crates/palyra-common/src/runtime\_contracts.rs
  * crates/palyra-daemon/src/application/provider\_input.rs
  * crates/palyra-daemon/src/application/run\_stream/tape.rs
  * crates/palyra-daemon/src/application/session\_compaction.rs
  * crates/palyra-daemon/src/auxiliary\_executor.rs
  * crates/palyra-daemon/src/background\_queue.rs
  * crates/palyra-daemon/src/objective\_judge.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/acp.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/chat.rs
  * schemas/json/cross\_surface\_handoff.schema.json
  * schemas/json/ux\_telemetry\_event.schema.json
</details>

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

| 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`                                           |

The `runtime_contract_enum!` macro in [crates/palyra-common/src/runtime\_contracts.rs#19-84](http://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](http://crates/palyra-common/src/runtime_contracts.rs#87-101), [crates/palyra-common/src/runtime\_contracts.rs#117-126](http://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

```mermaid theme={null}
graph TD
    subgraph "Daemon (Rust)"
        A["Agent Loop"] -- "Tool Output" --> B["run_stream::tape::send_tool_result_with_tape"]
        B -- "JSON Payload" --> C["Axum NDJSON Stream"]
    end

    subgraph "Web Console (React)"
        C -- "Fetch ReadableStream" --> D["useConsoleAppState"]
        D -- "Update State" --> E["A2UI Renderer"]
        E -- "Dynamic Components" --> F["DOM"]
    end

    [crates/palyra-daemon/src/application/run_stream/tape.rs:79-108] --> B
    [crates/palyra-daemon/src/transport/http/handlers/console/chat.rs:9-14] --> C
    [apps/web/src/styles.css:144-152] --> E
```

**Sources:** [crates/palyra-daemon/src/application/run\_stream/tape.rs#1-10](http://crates/palyra-daemon/src/application/run_stream/tape.rs#1-10), [apps/web/src/styles.css#144-152](http://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.

| 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`.             |

**Implementation Details:**

* **Parsing:** `parseConsoleHandoff` in [apps/web/src/console/contracts.ts#154-172](http://apps/web/src/console/contracts.ts#154-172) handles the transition from URL search params to the typed object.
* **Normalization:** `normalizeHandoffIntent` maps various string formats (snake\_case, kebab-case) to the canonical `HandoffIntent` [apps/web/src/console/contracts.ts#199-213](http://apps/web/src/console/contracts.ts#199-213).

**Sources:** [apps/web/src/console/contracts.ts#22-31](http://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

```mermaid theme={null}
classDiagram
    class UxTelemetryEvent {
        +string name ("ux.approval.resolved")
        +TelemetrySurface surface
        +string section
        +string outcome ("ok", "blocked")
        +number latencyMs
    }
    class SystemEventRecord {
        +string operator_event
        +number timestamp_unix_ms
        +JsonValue payload_json
    }
    UxTelemetryEvent ..> SystemEventRecord : "Serialized into payload_json"
```

The function `toSystemEventPayload` in [apps/web/src/console/contracts.ts#221-244](http://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](http://apps/web/src/console/contracts.ts#33-64), [apps/web/src/console/contracts.ts#221-244](http://apps/web/src/console/contracts.ts#221-244), [crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#117-128](http://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

| 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     |

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](http://crates/palyra-daemon/src/auxiliary_executor.rs#92-155), [crates/palyra-daemon/src/auxiliary\_executor.rs#47-54](http://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](http://crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#54-59), [crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#65-74](http://crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#65-74), [crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#142-180](http://crates/palyra-daemon/src/transport/http/handlers/console/acp.rs#142-180)