palyra-common crate provides the shared foundation for the Palyra ecosystem. It contains core logic for configuration management, sensitive data redaction, filesystem workspace patching, and shared protocol constants used across the daemon, CLI, and desktop applications.
Configuration System (config_system)
The configuration system handles the lifecycle of TOML-based configuration files, including versioning, atomic updates, and automated backups.
TOML Migration & Versioning
All configuration files are versioned. The system currently supportsCONFIG_VERSION_V1 crates/palyra-common/src/config_system.rs#14-14.
parse_document_with_migration: Parses a TOML string into atoml::Valueand automatically upgrades unversioned files to V1 crates/palyra-common/src/config_system.rs#89-99.ensure_document_version: Checks theversionkey. If missing, it inserts the current version and marks the document as migrated crates/palyra-common/src/config_system.rs#101-129.
Path-Based Mutation
The system allows getting, setting, or unsetting values using dot-notation paths (e.g.,daemon.port).
- Validation: Paths are validated against forbidden segments like
__proto__orconstructorto prevent prototype pollution-style vulnerabilities in downstream consumers crates/palyra-common/src/config_system.rs#16-16. - Fail-Closed Mutation: If a path segment crosses a scalar value (e.g., trying to set
a.b.cwhena.bis an integer), the operation returns aPathCrossesScalarerror crates/palyra-common/src/config_system.rs#44-45.
Atomic File Operations & Backups
TheConfigPersistence trait (and its implementations) provides safe disk writes:
- Backup Rotation: Before writing, existing files are rotated through a configurable number of backups (default 5) using
.bak.Nextensions crates/palyra-common/src/config_system.rs#15-15. - Atomic Write: New configuration is written to a
.tmpfile and then renamed to the target path to ensure atomicity crates/palyra-common/src/config_system.rs#202-204. - Permissions: On Unix systems, the system attempts to preserve existing file permissions (e.g.,
0o600for secrets) during updates crates/palyra-cli/tests/config_mutation.rs#107-146.
Redaction Utilities
Theredaction module provides shared logic for identifying and masking sensitive information in logs, UI previews, and HTTP headers.
Sensitive Key Identification
The system maintains a list ofSENSITIVE_KEY_MARKERS including api_key, authorization, bearer, password, and token crates/palyra-common/src/redaction.rs#5-22. The is_sensitive_key function normalizes input strings to check for these markers crates/palyra-common/src/redaction.rs#25-28.
Specialized Redaction Routines
redact_url: Strips sensitiveuserinfo(username:password) and redacts specific query parameters or fragments if their keys are sensitive crates/palyra-common/src/redaction.rs#63-86.redact_header: Redacts entire header values for sensitive keys (likeAuthorization) and filters URLs inLocationorRefererheaders crates/palyra-common/src/redaction.rs#49-60.redact_auth_error: A stateful parser that walks through error messages (e.g., from LLM providers) to find and redact tokens following “bearer” or assignment patterns crates/palyra-common/src/redaction.rs#89-111.
Workspace Patching (workspace_patch)
The workspace_patch module implements a fail-closed mechanism for applying multi-file text changes to a local filesystem. This is primarily used by agents to modify codebases.
Execution Guardrails
The system enforcesWorkspacePatchLimits to prevent resource exhaustion or runaway processes:
max_patch_bytes: Limits the total size of the patch payload (default 256KB) crates/palyra-common/src/workspace_patch.rs#33-33.max_files_touched: Limits the number of distinct files a single patch can modify (default 64) crates/palyra-common/src/workspace_patch.rs#34-34.max_file_bytes: Limits the size of individual files being patched (default 2MB) crates/palyra-common/src/workspace_patch.rs#35-35.
Security & Sandboxing
- Path Confining: All paths must be relative and are strictly confined to authorized
workspace_roots. Attempts to escape via..or absolute paths result in aPathOutsideWorkspaceerror crates/palyra-common/src/workspace_patch.rs#113-116. - Atomic Rollback: Patching is performed in two phases: planning and execution. If any file write fails during execution, the system attempts a best-effort rollback of previously modified files crates/palyra-common/src/workspace_patch.rs#136-137.
Patch Operations
The system supports three primary operations crates/palyra-common/src/workspace_patch.rs#159-163:- Add: Creates a new file with specified content.
- Update: Modifies an existing file using “hunks” (context lines, additions, and removals).
- Delete: Removes a file from the workspace.
Process Runner Input (process_runner_input)
This utility handles the serialization and parsing of inputs for sandboxed process execution. It ensures that environment variables, arguments, and working directories are safely passed between the daemon and the sandbox runner.
Key entities include:
ProcessRunnerInput: Defines the command, arguments, environment variables, and resource limits crates/palyra-common/src/process_runner_input.rs.ProcessRunnerOutput: Captures exit codes, stdout, and stderr, while applying redaction to the output streams before they are returned to the LLM or logs crates/palyra-common/src/process_runner_input.rs.
Windows Security (windows_security)
On Windows platforms, palyra-common provides wrappers for the Data Protection API (DPAPI) to secure secrets at rest without requiring a master password from the user.
dpapi_protect_current_user: Encrypts a byte array using the current user’s credentials crates/palyra-common/src/lib.rs#14-14.dpapi_unprotect_current_user: Decrypts data previously encrypted by the same user on the same machine crates/palyra-common/src/lib.rs#14-14.
palyra-vault crate when the WindowsDpapi backend is selected crates/palyra-vault/src/backend.rs#15-16.
Sources: crates/palyra-common/src/lib.rs#13-14, crates/palyra-vault/src/backend.rs#47-49
Shared Constants & Schemas
The crate defines several monorepo-wide constants and schemas:- Protocol Versions:
CANONICAL_PROTOCOL_MAJOR(1) andCANONICAL_JSON_ENVELOPE_VERSION(1) crates/palyra-common/src/lib.rs#31-32. - Daemon Config Schema: Defines the
DaemonConfigstruct used for validatingpalyra.tomlsections like[daemon],[gateway], and[model_provider]crates/palyra-common/src/daemon_config_schema.rs. - Context References: Utilities for parsing and resolving context identifiers (e.g.,
@file:path) used in chat composers crates/palyra-common/src/context_references.rs.