zeph_config/
execution.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Named execution environment configuration (`[execution]` TOML section).
5//!
6//! Provides [`ExecutionConfig`] — the configuration type for the top-level `[execution]`
7//! section — and [`EnvironmentConfig`] for each `[[execution.environments]]` entry.
8//!
9//! The `ShellExecutor` calls `ExecutionConfig::build_registry` at construction time to
10//! produce a `HashMap<String, ExecutionContext>` that is consulted on every tool call.
11
12use std::collections::BTreeMap;
13
14use serde::{Deserialize, Serialize};
15
16/// Top-level `[execution]` configuration section.
17///
18/// # Config example
19///
20/// ```toml
21/// [execution]
22/// default_env = "repo"
23///
24/// [[execution.environments]]
25/// name = "repo"
26/// cwd = "/Users/me/Dev/myproject"
27/// env = { CARGO_TARGET_DIR = "/tmp/cargo-target" }
28///
29/// [[execution.environments]]
30/// name = "scratch"
31/// cwd = "/tmp/scratch"
32/// ```
33///
34/// # Note on case sensitivity
35///
36/// Environment names are **case-sensitive**. Convention is lowercase (`"repo"`, `"scratch"`).
37/// An unknown `default_env` or `context.name` is a hard error at resolution time.
38#[derive(Debug, Default, Deserialize, Serialize, Clone)]
39pub struct ExecutionConfig {
40    /// Name of the environment applied when a `ToolCall` carries no explicit context
41    /// and no `default_env` would otherwise be used.  This is the least-specific
42    /// fallback layer in the CWD/env precedence stack.
43    #[serde(default, skip_serializing_if = "Option::is_none")]
44    pub default_env: Option<String>,
45
46    /// Named execution environments.  Each entry becomes a registry key that
47    /// `ShellExecutor` consults when `ToolCall::context.name` is set.
48    #[serde(default, rename = "environments")]
49    pub environments: Vec<EnvironmentConfig>,
50}
51
52/// A single named execution environment entry (`[[execution.environments]]`).
53#[derive(Debug, Deserialize, Serialize, Clone)]
54pub struct EnvironmentConfig {
55    /// Registry key.  Case-sensitive; convention is lowercase.
56    pub name: String,
57    /// Absolute or relative working directory for commands using this environment.
58    ///
59    /// Relative paths are resolved relative to the process CWD at registry-build time
60    /// (i.e. agent startup).  Non-existent paths are a hard error.
61    pub cwd: String,
62    /// Extra environment variables injected into the subprocess for this environment.
63    ///
64    /// Because these originate from operator-authored TOML, registry contexts are
65    /// *trusted*: the `env_blocklist` final filter pass is skipped.
66    #[serde(default)]
67    pub env: BTreeMap<String, String>,
68}
zeph_config/execution.rs

zeph_config/
execution.rs
