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;
65mod parser;
66mod providers;
67mod registry;
68
69// Re-export public types for crate-level access
70pub use ccs::is_ccs_ref;
71pub use config::{
72    global_agents_config_path, AgentConfig, AgentsConfigFile, ConfigInitResult, ConfigSource,
73};
74pub use error::{is_glm_like_agent, AgentErrorKind};
75pub use fallback::AgentRole;
76pub use parser::JsonParserType;
77pub use providers::{
78    auth_failure_advice, strip_model_flag_prefix, validate_model_flag, OpenCodeProviderType,
79};
80pub use registry::AgentRegistry;
81
82#[cfg(test)]
83mod tests {
84    use super::fallback::FallbackConfig;
85    use super::*;
86
87    #[test]
88    fn test_module_exports() {
89        // Verify all expected types are accessible through the module
90        let _ = AgentRegistry::new().unwrap();
91        let _ = FallbackConfig::default();
92        let _ = AgentErrorKind::Permanent;
93        let _ = AgentRole::Developer;
94        let _ = JsonParserType::Claude;
95        let _ = OpenCodeProviderType::OpenCodeZen;
96    }
97}
ralph_workflow/agents/mod.rs

ralph_workflow/agents/
mod.rs
