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

ralph_workflow/agents/
mod.rs
