palyra-common crate serves as the foundational utility library for the Palyra ecosystem. it provides critical shared logic for configuration management, secure string redaction, workspace manipulation via atomic patching, and input parsing for process runners and context references. These utilities are designed to be “fail-closed,” prioritizing security and integrity across both the daemon (palyrad) and the CLI (palyra).
Data Flow and Code Entity Mapping
The following diagram illustrates how core utilities inpalyra-common bridge the gap between raw input (Natural Language or Filesystem) and the structured internal state used by the daemon.
Diagram: Input Transformation to Code Entities
Sources: [crates/palyra-common/src/config_system.rs#89-99](http://crates/palyra-common/src/config_system.rs#89-99), [crates/palyra-common/src/workspace_patch.rs#207-211](http://crates/palyra-common/src/workspace_patch.rs#207-211), [crates/palyra-daemon/src/application/context_references.rs#72-79](http://crates/palyra-daemon/src/application/context_references.rs#72-79)
1. Configuration System (config_system.rs)
The configuration system manages the lifecycle of Palyra’s TOML configuration files. It handles versioning, migrations, and safe path-based mutation of configuration values.
Key Functions and Logic
- Versioning: Every config document must include a
versionkey. The system currently supportsCONFIG_VERSION_V1crates/palyra-common/src/config_system.rs#14-14. - Migration:
ensure_document_versionchecks the version and applies migrations if necessary, ensuring the daemon always operates on a compatible schema crates/palyra-common/src/config_system.rs#101-129. - Path-based Access: Functions like
get_value_at_pathandset_value_at_pathallow the CLI to manipulate specific nested keys (e.g.,daemon.port) using dot-notation strings crates/palyra-common/src/config_system.rs#153-172. - Validation: Segments of a config path are validated against forbidden names like
__proto__orconstructorto prevent injection attacks crates/palyra-common/src/config_system.rs#16-16.
Backup and Rotation
The system implements an automated backup rotation. When a configuration is modified viaset or unset, the existing file is rotated (e.g., palyra.toml.bak.1) up to a configurable limit (default 5) crates/palyra-common/src/config_system.rs#15-15.
Sources: [crates/palyra-common/src/config_system.rs#1-206](http://crates/palyra-common/src/config_system.rs#1-206)
2. Redaction Utilities (redaction.rs)
To prevent the accidental leakage of sensitive information (API keys, tokens, passwords) in logs or CLI output, palyra-common provides a comprehensive redaction suite.
| Utility Function | Purpose | Implementation Detail |
|---|---|---|
is_sensitive_key | Identifies if a key name is sensitive. | Checks against SENSITIVE_KEY_MARKERS like api_key, secret, vault_ref. crates/palyra-common/src/redaction.rs#5-28 |
redact_url | Strips credentials and sensitive query params. | Redacts userinfo and specific keys in query/fragments. crates/palyra-common/src/redaction.rs#63-86 |
redact_header | Redacts sensitive HTTP headers. | Specifically targets Authorization, Cookie, and Set-Cookie. crates/palyra-common/src/redaction.rs#49-60 |
redact_auth_error | Scans error messages for leaked tokens. | Looks for “Bearer” patterns and assignment tokens (e.g. key=val). crates/palyra-common/src/redaction.rs#89-111 |
[crates/palyra-common/src/redaction.rs#1-130](http://crates/palyra-common/src/redaction.rs#1-130)
3. Workspace Patching (workspace_patch.rs)
The workspace_patch module provides a secure mechanism for applying multi-file changes (Add, Update, Delete) to a local workspace. This is primarily used by agents to perform code modifications.
Execution Pipeline
- Validation: Enforces
WorkspacePatchLimits(max patch size, max files touched) crates/palyra-common/src/workspace_patch.rs#23-39. - Path Confinement: Ensures all target paths are relative and reside within the authorized
workspace_rootscrates/palyra-common/src/workspace_patch.rs#113-116. - Atomic Planning: Generates a
PatchPlanbefore any mutation occurs. - Execution & Rollback: Applies changes. If any file operation fails, it attempts a best-effort rollback to the state before the patch started crates/palyra-common/src/workspace_patch.rs#207-211.
[crates/palyra-common/src/workspace_patch.rs#158-211](http://crates/palyra-common/src/workspace_patch.rs#158-211)
4. Context References (context_references.rs)
This module handles the parsing and resolution of “mentions” within user prompts. These mentions allow users to inject external data into the LLM context.
Supported Reference Kinds
- File/Folder:
@path/to/file— Injects file contents or directory listings crates/palyra-daemon/src/application/context_references.rs#188-193. - Git (Diff/Staged):
#diffor#staged— Injects git changes crates/palyra-daemon/src/application/context_references.rs#194-199. - URL:
https://...— Fetches and injects web content (if enabled) crates/palyra-daemon/src/application/context_references.rs#200-203. - Memory:
#memory— Triggers a vector search in theJournalStorecrates/palyra-daemon/src/application/context_references.rs#204-206.
Safety Constraints
To prevent resource exhaustion, the following limits are enforced:- Max Reference Count: 8 per prompt crates/palyra-daemon/src/application/context_references.rs#27-27.
- Max Character Count: 24,000 total across all references crates/palyra-daemon/src/application/context_references.rs#28-28.
- Blocked Paths: Components like
.git,.ssh, and.awsare strictly forbidden crates/palyra-daemon/src/application/context_references.rs#38-38.
[crates/palyra-daemon/src/application/context_references.rs#27-129](http://crates/palyra-daemon/src/application/context_references.rs#27-129)
5. Daemon Config Schema (daemon_config_schema)
While config_system provides the mechanism for TOML manipulation, palyra-common also defines the strongly-typed schema used by the daemon.
RootFileConfig: The top-level structure representing the entirepalyra.tomlfile.redact_secret_config_values: A specialized function that takes aRootFileConfigand returns a copy where sensitive fields (likeopenai_api_keyorauth_token) are replaced with<redacted>. This is used by thepalyra config getcommand to prevent leaking secrets to the terminal by default crates/palyra-cli/tests/config_mutation.rs#149-170.
[crates/palyra-cli/tests/config_mutation.rs#149-209](http://crates/palyra-cli/tests/config_mutation.rs#149-209)