Core Envelope Principles
Palyra utilizes a “fail-closed” approach to JSON processing. All major contracts enforceadditionalProperties: false (or #[serde(deny_unknown_fields)] in Rust) to prevent forward-compatibility issues where an agent might provide parameters the current runtime does not understand, potentially leading to insecure defaults.
Common Primitives & Security
Envelopes often include security-sensitive data. The system provides shared primitives for identifying and scrubbing sensitive keys to prevent accidental leakage into logs or run histories.- Redaction Markers: A standardized list of sensitive keys (e.g.,
api_key,bearer,client_secret) is used to identify fields that must be scrubbed[crates/palyra-common/src/redaction.rs#5-22](http://crates/palyra-common/src/redaction.rs#5-22). - Payload Limits: To prevent Denial of Service (DoS) via resource exhaustion, envelopes like workspace patches enforce strict byte limits
[crates/palyra-common/src/workspace_patch.rs#23-39](http://crates/palyra-common/src/workspace_patch.rs#23-39).
[crates/palyra-common/src/redaction.rs#5-22](http://crates/palyra-common/src/redaction.rs#5-22), [crates/palyra-common/src/process_runner_input.rs#5-17](http://crates/palyra-common/src/process_runner_input.rs#5-17)
Workspace Patch Contract
The Workspace Patch system uses a specific JSON/Text-based envelope to describe atomic mutations to the filesystem. It includes built-in safety checks for path traversal and file size.WorkspacePatchRequest
This envelope carries the raw patch string and the policy for how the outcome should be previewed.| Field | Type | Description |
|---|---|---|
patch | String | The Unified Diff or custom patch format string [crates/palyra-common/src/workspace_patch.rs#68-68](http://crates/palyra-common/src/workspace_patch.rs#68-68). |
dry_run | bool | If true, validates and plans but does not write to disk [crates/palyra-common/src/workspace_patch.rs#69-69](http://crates/palyra-common/src/workspace_patch.rs#69-69). |
redaction_policy | Struct | Patterns to scrub from the resulting redacted_preview [crates/palyra-common/src/workspace_patch.rs#70-70](http://crates/palyra-common/src/workspace_patch.rs#70-70). |
WorkspacePatchOutcome
After execution, the system returns an attestation of what changed.| Field | Type | Description |
|---|---|---|
patch_sha256 | String | Hash of the input patch for auditability [crates/palyra-common/src/workspace_patch.rs#93-93](http://crates/palyra-common/src/workspace_patch.rs#93-93). |
files_touched | Vec<Attestation> | List of files modified, including before/after SHA256 hashes [crates/palyra-common/src/workspace_patch.rs#75-88](http://crates/palyra-common/src/workspace_patch.rs#75-88). |
redacted_preview | String | A safe-to-log preview of the changes [crates/palyra-common/src/workspace_patch.rs#97-97](http://crates/palyra-common/src/workspace_patch.rs#97-97). |
[crates/palyra-common/src/workspace_patch.rs#65-98](http://crates/palyra-common/src/workspace_patch.rs#65-98)
Tool Execution Envelopes
Tool inputs are strictly typed to ensure the LLM (or caller) provides exactly what the tool expects.Process Runner Input (palyra.process.run)
The ProcessRunnerToolInput struct defines the contract for executing arbitrary commands within the sandbox [crates/palyra-common/src/process_runner_input.rs#7-17](http://crates/palyra-common/src/process_runner_input.rs#7-17).
- Enforcement: The
#[serde(deny_unknown_fields)]attribute ensures that if an agent attempts to pass an unsupported field (likeenv_varsif not explicitly allowed), the request is rejected[crates/palyra-common/src/process_runner_input.rs#6-6](http://crates/palyra-common/src/process_runner_input.rs#6-6). - Validation: The
parse_process_runner_tool_inputfunction handles the conversion from raw slice to the typed contract[crates/palyra-common/src/process_runner_input.rs#26-31](http://crates/palyra-common/src/process_runner_input.rs#26-31).
[crates/palyra-common/src/process_runner_input.rs#7-31](http://crates/palyra-common/src/process_runner_input.rs#7-31)
Fuzzing & Contract Integrity
To ensure the robustness of JSON envelope parsing against malicious or malformed inputs, Palyra employs extensive fuzzing. Fuzz targets are located in thefuzz/ directory and exercise the parsing logic of every major contract.
workspace_patch_parser: Fuzzes theapply_workspace_patchlogic with random byte sequences to find panics in the diff parser[fuzz/fuzz_targets/workspace_patch_parser.rs#40-40](http://fuzz/fuzz_targets/workspace_patch_parser.rs#40-40).process_runner_input_parser: Targets theProcessRunnerToolInputcontract to ensure thedeny_unknown_fieldsand type constraints are enforced correctly[fuzz/fuzz_targets/process_runner_input_parser.rs#8-13](http://fuzz/fuzz_targets/process_runner_input_parser.rs#8-13).redaction_routines: Validates that the redaction logic correctly identifies and replaces sensitive tokens in various string contexts[fuzz/Cargo.toml#61-65](http://fuzz/Cargo.toml#61-65).
Configuration Limits
Fuzzing targets use the sameWorkspacePatchLimits as the production daemon to ensure consistency between the security model and the testing environment [fuzz/fuzz_targets/workspace_patch_parser.rs#34-39](http://fuzz/fuzz_targets/workspace_patch_parser.rs#34-39).
Sources: [fuzz/fuzz_targets/workspace_patch_parser.rs#1-41](http://fuzz/fuzz_targets/workspace_patch_parser.rs#1-41), [fuzz/fuzz_targets/process_runner_input_parser.rs#1-13](http://fuzz/fuzz_targets/process_runner_input_parser.rs#1-13), [fuzz/Cargo.toml#18-80](http://fuzz/Cargo.toml#18-80)