ralph/contracts/config/
mod.rs

1//! Configuration contracts for Ralph.
2//!
3//! Responsibilities:
4//! - Define config structs/enums and their merge behavior.
5//! - Provide defaults and schema helpers for configuration serialization.
6//!
7//! Not handled here:
8//! - Reading/writing config files or CLI parsing (see `crate::config`).
9//! - Queue/task contract definitions (see `super::queue` and `super::task`).
10//! - Runner definitions (see `super::runner`).
11//! - Model definitions (see `super::model`).
12//!
13//! Invariants/assumptions:
14//! - Config merge is leaf-wise: `Some` values override, `None` does not.
15//! - Serde/schemars attributes define the config contract.
16
17use crate::constants::defaults::DEFAULT_ID_WIDTH;
18use crate::constants::limits::{
19    DEFAULT_SIZE_WARNING_THRESHOLD_KB, DEFAULT_TASK_COUNT_WARNING_THRESHOLD,
20};
21use crate::constants::queue::{DEFAULT_DONE_FILE, DEFAULT_QUEUE_FILE};
22use crate::constants::timeouts::DEFAULT_SESSION_TIMEOUT_HOURS;
23use crate::contracts::model::{Model, ReasoningEffort};
24use crate::contracts::runner::{
25    ClaudePermissionMode, Runner, RunnerApprovalMode, RunnerCliConfigRoot, RunnerCliOptionsPatch,
26    RunnerOutputFormat, RunnerPlanMode, RunnerSandboxMode, RunnerVerbosity,
27    UnsupportedOptionPolicy,
28};
29use schemars::JsonSchema;
30use serde::{Deserialize, Serialize};
31use std::collections::BTreeMap;
32use std::path::PathBuf;
33
34mod agent;
35mod enums;
36mod loop_;
37mod notification;
38mod parallel;
39mod phase;
40mod plugin;
41mod profiles;
42mod queue;
43mod retry;
44#[cfg(test)]
45mod tests;
46mod webhook;
47
48pub use agent::{AgentConfig, CiGateConfig};
49pub use enums::{GitPublishMode, GitRevertMode, ProjectType, ScanPromptVersion};
50pub use loop_::LoopConfig;
51pub use notification::NotificationConfig;
52pub use parallel::{ParallelConfig, default_push_backoff_ms};
53pub use phase::{PhaseOverrideConfig, PhaseOverrides};
54pub use plugin::{PluginConfig, PluginsConfig};
55pub(crate) use profiles::{builtin_profile, builtin_profile_names, is_reserved_profile_name};
56pub use queue::{QueueAgingThresholds, QueueConfig};
57pub use retry::RunnerRetryConfig;
58pub use webhook::{WebhookConfig, WebhookEventSubscription, WebhookQueuePolicy};
59
60/// Root configuration struct for Ralph.
61#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
62#[serde(default, deny_unknown_fields)]
63pub struct Config {
64    /// Schema version for config.
65    pub version: u32,
66
67    /// "code" or "docs". Drives prompt defaults and small workflow decisions.
68    pub project_type: Option<ProjectType>,
69
70    /// Queue-related configuration.
71    pub queue: QueueConfig,
72
73    /// Agent runner defaults (Claude, Codex, OpenCode, Gemini, or Cursor).
74    pub agent: AgentConfig,
75
76    /// Parallel run-loop configuration.
77    pub parallel: ParallelConfig,
78
79    /// Run loop waiting configuration (daemon/continuous mode).
80    #[serde(rename = "loop")]
81    pub loop_field: LoopConfig,
82
83    /// Plugin configuration (enable/disable + per-plugin settings).
84    pub plugins: PluginsConfig,
85
86    /// Optional named profiles for quick workflow switching.
87    ///
88    /// Each profile is an AgentConfig-shaped patch applied over `agent` when selected.
89    /// Profile values override base config but are overridden by CLI flags and task.agent.
90    #[serde(skip_serializing_if = "Option::is_none")]
91    pub profiles: Option<BTreeMap<String, AgentConfig>>,
92}
93
94impl Default for Config {
95    fn default() -> Self {
96        Self {
97            version: 2,
98            project_type: Some(ProjectType::Code),
99            queue: QueueConfig {
100                file: Some(PathBuf::from(DEFAULT_QUEUE_FILE)),
101                done_file: Some(PathBuf::from(DEFAULT_DONE_FILE)),
102                id_prefix: Some("RQ".to_string()),
103                id_width: Some(DEFAULT_ID_WIDTH as u8),
104                size_warning_threshold_kb: Some(DEFAULT_SIZE_WARNING_THRESHOLD_KB),
105                task_count_warning_threshold: Some(DEFAULT_TASK_COUNT_WARNING_THRESHOLD),
106                max_dependency_depth: Some(10),
107                auto_archive_terminal_after_days: None,
108                aging_thresholds: Some(QueueAgingThresholds {
109                    warning_days: Some(7),
110                    stale_days: Some(14),
111                    rotten_days: Some(30),
112                }),
113            },
114            agent: AgentConfig {
115                runner: Some(Runner::Codex),
116                model: Some(Model::Gpt54),
117                reasoning_effort: Some(ReasoningEffort::Medium),
118                iterations: Some(1),
119                followup_reasoning_effort: None,
120                codex_bin: Some("codex".to_string()),
121                opencode_bin: Some("opencode".to_string()),
122                gemini_bin: Some("gemini".to_string()),
123                claude_bin: Some("claude".to_string()),
124                cursor_bin: Some("agent".to_string()),
125                kimi_bin: Some("kimi".to_string()),
126                pi_bin: Some("pi".to_string()),
127                phases: Some(3),
128                claude_permission_mode: Some(ClaudePermissionMode::AcceptEdits),
129                runner_cli: Some(RunnerCliConfigRoot {
130                    defaults: RunnerCliOptionsPatch {
131                        output_format: Some(RunnerOutputFormat::StreamJson),
132                        verbosity: Some(RunnerVerbosity::Normal),
133                        approval_mode: Some(RunnerApprovalMode::Default),
134                        sandbox: Some(RunnerSandboxMode::Default),
135                        plan_mode: Some(RunnerPlanMode::Default),
136                        unsupported_option_policy: Some(UnsupportedOptionPolicy::Warn),
137                    },
138                    runners: BTreeMap::from([
139                        (
140                            Runner::Codex,
141                            RunnerCliOptionsPatch {
142                                sandbox: Some(RunnerSandboxMode::Disabled),
143                                ..RunnerCliOptionsPatch::default()
144                            },
145                        ),
146                        (
147                            Runner::Claude,
148                            RunnerCliOptionsPatch {
149                                verbosity: Some(RunnerVerbosity::Verbose),
150                                ..RunnerCliOptionsPatch::default()
151                            },
152                        ),
153                    ]),
154                }),
155                phase_overrides: None,
156                instruction_files: None,
157                repoprompt_plan_required: Some(false),
158                repoprompt_tool_injection: Some(false),
159                ci_gate: Some(CiGateConfig {
160                    enabled: Some(true),
161                    argv: Some(vec!["make".to_string(), "ci".to_string()]),
162                }),
163                git_revert_mode: Some(GitRevertMode::Ask),
164                git_publish_mode: Some(GitPublishMode::Off),
165                notification: NotificationConfig {
166                    enabled: Some(true),
167                    notify_on_complete: Some(true),
168                    notify_on_fail: Some(true),
169                    notify_on_loop_complete: Some(true),
170                    suppress_when_active: Some(true),
171                    sound_enabled: Some(false),
172                    sound_path: None,
173                    timeout_ms: Some(8000),
174                },
175                webhook: WebhookConfig::default(),
176                runner_retry: RunnerRetryConfig::default(),
177                session_timeout_hours: Some(DEFAULT_SESSION_TIMEOUT_HOURS),
178                scan_prompt_version: Some(ScanPromptVersion::V2),
179            },
180            parallel: ParallelConfig {
181                workers: None,
182                workspace_root: None,
183                max_push_attempts: Some(50),
184                push_backoff_ms: Some(default_push_backoff_ms()),
185                workspace_retention_hours: Some(24),
186            },
187            loop_field: LoopConfig {
188                wait_when_empty: Some(false),
189                empty_poll_ms: Some(30_000),
190                wait_when_blocked: Some(false),
191                wait_poll_ms: Some(1000),
192                wait_timeout_seconds: Some(0),
193                notify_when_unblocked: Some(false),
194            },
195            plugins: PluginsConfig::default(),
196            profiles: None,
197        }
198    }
199}
ralph/contracts/config/mod.rs

ralph/contracts/config/
mod.rs
