1. Workspace Patch Protocol
The Workspace Patch protocol is used by the daemon to perform atomic, validated filesystem operations. It is designed to be “fail-closed,” ensuring that no mutations occur if safety checks (traversal, size limits, or UTF-8 validity) fail.Implementation Details
The core logic resides inpalyra-common and provides a WorkspacePatchRequest structure that encapsulates the patch content and redaction policies crates/palyra-common/src/workspace_patch.rs#67-71.
Key enforcement mechanisms include:
- Path Confinement: All paths must be relative and are strictly checked against
workspace_rootsto prevent directory traversal crates/palyra-common/src/workspace_patch.rs#113-116. - Resource Limits: The
WorkspacePatchLimitsstruct defines maximums for patch size (default 256KB), touched files (default 64), and individual file sizes (default 2MB) crates/palyra-common/src/workspace_patch.rs#30-39. - Atomic Rollback: If a multi-file patch fails mid-execution, the system attempts a best-effort rollback to restore the previous state crates/palyra-common/src/workspace_patch.rs#96-98.
Patch Data Flow
The following diagram illustrates how aWorkspacePatchRequest is transformed into a PatchPlan and eventually a WorkspacePatchOutcome.
Workspace Patch Execution Flow
Sources: crates/palyra-common/src/workspace_patch.rs#207-212, crates/palyra-common/src/workspace_patch.rs#184-193
2. A2UI (Agent-to-UI) Protocol
The A2UI protocol enables agents to dynamically construct and update rich UI components in the web console without requiring a full page reload or complex custom code. It uses a JSON-based document model updated via RFC 6902-inspired patches.A2UI Document Structure
AnA2uiDocument consists of a surface identifier and an array of A2uiComponent objects apps/web/src/a2ui/renderer.tsx#13-21. Supported components include:
- Markdown: Rendered via
SanitizedMarkdownapps/web/src/a2ui/renderer.tsx#72-73. - Tables: Rendered using
EntityTableapps/web/src/a2ui/renderer.tsx#113-122. - Forms: Interactive elements with checkboxes, selects, and text inputs apps/web/src/a2ui/renderer.tsx#186-240.
- Charts: Visual data representations apps/web/src/a2ui/renderer.tsx#92-93.
Patch Operations
Updates are sent asPatchDocument objects containing an array of operations (add, replace, remove) apps/web/src/a2ui/patch.ts#127-138. The applyPatchDocument function handles the state transition apps/web/src/a2ui/patch.ts#47-52.
| Operation | Description | Implementation |
|---|---|---|
add | Inserts a value at a path or appends to an array (-) | applyAddOperation |
replace | Overwrites an existing value at a path | applyReplaceOperation |
remove | Deletes a key or array element | applyRemoveOperation |
3. Security Model & Renderer Constraints
The A2UI renderer implements a strict security model to prevent cross-site scripting (XSS) and prototype pollution from untrusted agent output.Prototype Pollution Protection
TheapplyPatchDocument logic enforces a FORBIDDEN_POINTER_TOKENS set, which includes __proto__, prototype, and constructor apps/web/src/a2ui/patch.ts#16-16. Any patch attempting to traverse these tokens is immediately rejected with an A2uiError apps/web/src/a2ui/tests/patch.security.test.tsx#9-30.
Resource Budgets
To prevent Denial of Service (DoS) attacks via massive patches, the system enforces aPatchProcessingBudget apps/web/src/a2ui/patch.ts#10-11:
maxOpsPerPatch: Limits the number of operations in a single tick apps/web/src/a2ui/patch.ts#31-36.maxPathLength: Prevents deeply nested or excessively long JSON pointer strings apps/web/src/a2ui/patch.ts#71-77.maxApplyMsPerTick: Ensures patch application does not block the main UI thread for too long apps/web/src/a2ui/patch.ts#79-84.
4. UI Component Mapping
The following table maps A2UI component types to their internal React implementations and CSS classes used for styling.| Component Type | React Component | CSS Class | Data Attributes |
|---|---|---|---|
text | ComponentBody | .a2ui-text | data-tone |
markdown | SanitizedMarkdown | .a2ui-renderer | N/A |
form | A2uiForm | .a2ui-form | data-component-id |
table | A2uiTable | .a2ui-table-wrap | data-component-type |