ralph_workflow/agents/
mod.rs

1//! Agent Abstraction Module
2//!
3//! Provides a pluggable agent system for different AI coding assistants
4//! (Claude, Codex, `OpenCode`, Goose, Cline, CCS, etc.)
5//!
6//! ## Module Structure
7//!
8//! - `ccs` - CCS (Claude Code Switch) alias resolution
9//! - `config` - Agent configuration types and TOML parsing
10//! - `error` - Error classification for fault-tolerant execution
11//! - `fallback` - Fallback chain configuration for agent switching
12//! - `parser` - JSON parser type definitions
13//! - `providers` - `OpenCode` provider types and authentication
14//! - `registry` - Agent registry for agent lookup and management
15//!
16//! ## Configuration
17//!
18//! Agents can be configured via (in order of increasing priority):
19//! 1. Built-in defaults (claude, codex, opencode, ccs, aider, goose, cline, continue, amazon-q, gemini)
20//! 2. Unified config file (`~/.config/ralph-workflow.toml`)
21//! 3. Environment variables (`RALPH_DEVELOPER_CMD`, `RALPH_REVIEWER_CMD`)
22//! 4. Programmatic registration via `AgentRegistry::register()`
23//!
24//! ## CCS (Claude Code Switch) Support
25//!
26//! CCS aliases can be defined in the unified config and used with `ccs/alias` syntax:
27//! ```toml
28//! [ccs_aliases]
29//! work = "ccs work"
30//! personal = "ccs personal"
31//! gemini = "ccs gemini"
32//!
33//! [agent_chain]
34//! developer = ["ccs/work", "claude"]
35//! ```
36//!
37//! ## Agent Switching / Fallback
38//!
39//! Configure fallback agents for automatic switching when primary agent fails:
40//! ```toml
41//! [agent_chain]
42//! developer = ["claude", "codex", "goose"]
43//! reviewer = ["codex", "claude"]
44//! max_retries = 3
45//! retry_delay_ms = 1000
46//! ```
47//!
48//! ## Example TOML Configuration
49//!
50//! ```toml
51//! [agents.myagent]
52//! cmd = "my-ai-tool run"
53//! output_flag = "--json-stream"
54//! yolo_flag = "--auto-fix"
55//! verbose_flag = "--verbose"
56//! can_commit = true
57//! json_parser = "claude"  # Use Claude's JSON parser
58//! ```
59
60mod ccs;
61mod ccs_env;
62mod config;
63mod error;
64pub mod fallback;
65pub mod opencode_api;
66mod opencode_resolver;
67mod parser;
68mod providers;
69mod registry;
70mod retry_timer;
71pub mod validation;
72
73// Re-export public types for crate-level access
74pub use ccs::is_ccs_ref;
75pub use config::{
76    global_agents_config_path, AgentConfig, AgentsConfigFile, ConfigInitResult, ConfigSource,
77};
78pub use error::{contains_glm_model, is_glm_like_agent, AgentErrorKind};
79pub use fallback::AgentRole;
80pub use parser::JsonParserType;
81pub use providers::{
82    auth_failure_advice, strip_model_flag_prefix, validate_model_flag, OpenCodeProviderType,
83};
84pub use registry::AgentRegistry;
85pub use retry_timer::RetryTimerProvider;
86
87#[cfg(any(test, feature = "test-utils"))]
88pub use retry_timer::TestRetryTimer;
89
90#[cfg(test)]
91mod tests {
92    use super::fallback::FallbackConfig;
93    use super::*;
94
95    #[test]
96    fn test_module_exports() {
97        // Verify all expected types are accessible through the module
98        let _ = AgentRegistry::new().unwrap();
99        let _ = FallbackConfig::default();
100        let _ = AgentErrorKind::Permanent;
101        let _ = AgentRole::Developer;
102        let _ = JsonParserType::Claude;
103        let _ = OpenCodeProviderType::OpenCodeZen;
104    }
105}
ralph_workflow/agents/mod.rs

ralph_workflow/agents/
mod.rs
