codetether_agent/tool/
mod.rs

1//! Tool system
2//!
3//! Tools are the executable capabilities available to agents.
4
5pub mod bash;
6pub mod batch;
7pub mod codesearch;
8pub mod confirm_edit;
9pub mod confirm_multiedit;
10pub mod edit;
11pub mod file;
12pub mod invalid;
13pub mod lsp;
14pub mod multiedit;
15pub mod patch;
16pub mod plan;
17pub mod prd;
18pub mod question;
19pub mod ralph;
20pub mod rlm;
21pub mod search;
22pub mod skill;
23pub mod task;
24pub mod todo;
25pub mod undo;
26pub mod webfetch;
27pub mod websearch;
28
29use anyhow::Result;
30use async_trait::async_trait;
31use serde::{Deserialize, Serialize};
32use serde_json::Value;
33use std::collections::HashMap;
34use std::sync::Arc;
35
36use crate::provider::Provider;
37
38/// A tool that can be executed by an agent
39#[async_trait]
40pub trait Tool: Send + Sync {
41    /// Tool identifier
42    fn id(&self) -> &str;
43
44    /// Human-readable name
45    fn name(&self) -> &str;
46
47    /// Description for the LLM
48    fn description(&self) -> &str;
49
50    /// JSON Schema for parameters
51    fn parameters(&self) -> Value;
52
53    /// Execute the tool with given arguments
54    async fn execute(&self, args: Value) -> Result<ToolResult>;
55}
56
57/// Result from tool execution
58#[derive(Debug, Clone, Serialize, Deserialize)]
59pub struct ToolResult {
60    pub output: String,
61    pub success: bool,
62    #[serde(default)]
63    pub metadata: HashMap<String, Value>,
64}
65
66impl ToolResult {
67    pub fn success(output: impl Into<String>) -> Self {
68        Self {
69            output: output.into(),
70            success: true,
71            metadata: HashMap::new(),
72        }
73    }
74
75    pub fn error(message: impl Into<String>) -> Self {
76        Self {
77            output: message.into(),
78            success: false,
79            metadata: HashMap::new(),
80        }
81    }
82
83    /// Create a structured error with code, tool name, missing fields, and example
84    ///
85    /// This helps LLMs self-correct by providing actionable information about what went wrong.
86    pub fn structured_error(
87        code: &str,
88        tool: &str,
89        message: &str,
90        missing_fields: Option<Vec<&str>>,
91        example: Option<Value>,
92    ) -> Self {
93        let mut error_obj = serde_json::json!({
94            "code": code,
95            "tool": tool,
96            "message": message,
97        });
98
99        if let Some(fields) = missing_fields {
100            error_obj["missing_fields"] = serde_json::json!(fields);
101        }
102
103        if let Some(ex) = example {
104            error_obj["example"] = ex;
105        }
106
107        let output = serde_json::to_string_pretty(&serde_json::json!({
108            "error": error_obj
109        }))
110        .unwrap_or_else(|_| format!("Error: {}", message));
111
112        let mut metadata = HashMap::new();
113        metadata.insert("error_code".to_string(), serde_json::json!(code));
114        metadata.insert("tool".to_string(), serde_json::json!(tool));
115
116        Self {
117            output,
118            success: false,
119            metadata,
120        }
121    }
122
123    pub fn with_metadata(mut self, key: impl Into<String>, value: Value) -> Self {
124        self.metadata.insert(key.into(), value);
125        self
126    }
127}
128
129/// Registry of available tools
130pub struct ToolRegistry {
131    tools: HashMap<String, Arc<dyn Tool>>,
132}
133
134impl ToolRegistry {
135    pub fn new() -> Self {
136        Self {
137            tools: HashMap::new(),
138        }
139    }
140
141    /// Register a tool
142    pub fn register(&mut self, tool: Arc<dyn Tool>) {
143        self.tools.insert(tool.id().to_string(), tool);
144    }
145
146    /// Get a tool by ID
147    pub fn get(&self, id: &str) -> Option<Arc<dyn Tool>> {
148        self.tools.get(id).cloned()
149    }
150
151    /// List all tool IDs
152    pub fn list(&self) -> Vec<&str> {
153        self.tools.keys().map(|s| s.as_str()).collect()
154    }
155
156    /// Get tool definitions for LLM
157    pub fn definitions(&self) -> Vec<crate::provider::ToolDefinition> {
158        self.tools
159            .values()
160            .map(|t| crate::provider::ToolDefinition {
161                name: t.id().to_string(),
162                description: t.description().to_string(),
163                parameters: t.parameters(),
164            })
165            .collect()
166    }
167
168    /// Create registry with all default tools (without batch)
169    pub fn with_defaults() -> Self {
170        let mut registry = Self::new();
171
172        registry.register(Arc::new(file::ReadTool::new()));
173        registry.register(Arc::new(file::WriteTool::new()));
174        registry.register(Arc::new(file::ListTool::new()));
175        registry.register(Arc::new(file::GlobTool::new()));
176        registry.register(Arc::new(search::GrepTool::new()));
177        registry.register(Arc::new(edit::EditTool::new()));
178        registry.register(Arc::new(bash::BashTool::new()));
179        registry.register(Arc::new(lsp::LspTool::new()));
180        registry.register(Arc::new(webfetch::WebFetchTool::new()));
181        registry.register(Arc::new(multiedit::MultiEditTool::new()));
182        registry.register(Arc::new(websearch::WebSearchTool::new()));
183        registry.register(Arc::new(codesearch::CodeSearchTool::new()));
184        registry.register(Arc::new(patch::ApplyPatchTool::new()));
185        registry.register(Arc::new(todo::TodoReadTool::new()));
186        registry.register(Arc::new(todo::TodoWriteTool::new()));
187        registry.register(Arc::new(question::QuestionTool::new()));
188        registry.register(Arc::new(task::TaskTool::new()));
189        registry.register(Arc::new(plan::PlanEnterTool::new()));
190        registry.register(Arc::new(plan::PlanExitTool::new()));
191        registry.register(Arc::new(skill::SkillTool::new()));
192        registry.register(Arc::new(rlm::RlmTool::new()));
193        registry.register(Arc::new(ralph::RalphTool::new()));
194        registry.register(Arc::new(prd::PrdTool::new()));
195        registry.register(Arc::new(confirm_edit::ConfirmEditTool::new()));
196        registry.register(Arc::new(confirm_multiedit::ConfirmMultiEditTool::new()));
197        registry.register(Arc::new(undo::UndoTool));
198        // Register the invalid tool handler for graceful error handling
199        registry.register(Arc::new(invalid::InvalidTool::new()));
200
201        registry
202    }
203
204    /// Create registry with provider for tools that need it (like RalphTool)
205    pub fn with_provider(provider: Arc<dyn Provider>, model: String) -> Self {
206        let mut registry = Self::new();
207
208        registry.register(Arc::new(file::ReadTool::new()));
209        registry.register(Arc::new(file::WriteTool::new()));
210        registry.register(Arc::new(file::ListTool::new()));
211        registry.register(Arc::new(file::GlobTool::new()));
212        registry.register(Arc::new(search::GrepTool::new()));
213        registry.register(Arc::new(edit::EditTool::new()));
214        registry.register(Arc::new(bash::BashTool::new()));
215        registry.register(Arc::new(lsp::LspTool::new()));
216        registry.register(Arc::new(webfetch::WebFetchTool::new()));
217        registry.register(Arc::new(multiedit::MultiEditTool::new()));
218        registry.register(Arc::new(websearch::WebSearchTool::new()));
219        registry.register(Arc::new(codesearch::CodeSearchTool::new()));
220        registry.register(Arc::new(patch::ApplyPatchTool::new()));
221        registry.register(Arc::new(todo::TodoReadTool::new()));
222        registry.register(Arc::new(todo::TodoWriteTool::new()));
223        registry.register(Arc::new(question::QuestionTool::new()));
224        registry.register(Arc::new(task::TaskTool::new()));
225        registry.register(Arc::new(plan::PlanEnterTool::new()));
226        registry.register(Arc::new(plan::PlanExitTool::new()));
227        registry.register(Arc::new(skill::SkillTool::new()));
228        registry.register(Arc::new(rlm::RlmTool::new()));
229        // RalphTool with provider for autonomous execution
230        registry.register(Arc::new(ralph::RalphTool::with_provider(provider, model)));
231        registry.register(Arc::new(prd::PrdTool::new()));
232        registry.register(Arc::new(undo::UndoTool));
233        // Register the invalid tool handler for graceful error handling
234        registry.register(Arc::new(invalid::InvalidTool::new()));
235
236        registry
237    }
238
239    /// Create Arc-wrapped registry with batch tool properly initialized.
240    /// The batch tool needs a weak reference to the registry, so we use
241    /// a two-phase initialization pattern.
242    pub fn with_defaults_arc() -> Arc<Self> {
243        let mut registry = Self::with_defaults();
244
245        // Create batch tool without registry reference
246        let batch_tool = Arc::new(batch::BatchTool::new());
247        registry.register(batch_tool.clone());
248
249        // Wrap registry in Arc
250        let registry = Arc::new(registry);
251
252        // Now give batch tool a weak reference to the registry
253        batch_tool.set_registry(Arc::downgrade(&registry));
254
255        registry
256    }
257
258    /// Create Arc-wrapped registry with provider and batch tool properly initialized.
259    /// The batch tool needs a weak reference to the registry, so we use
260    /// a two-phase initialization pattern.
261    #[allow(dead_code)]
262    pub fn with_provider_arc(provider: Arc<dyn Provider>, model: String) -> Arc<Self> {
263        let mut registry = Self::with_provider(provider, model);
264
265        // Create batch tool without registry reference
266        let batch_tool = Arc::new(batch::BatchTool::new());
267        registry.register(batch_tool.clone());
268
269        // Wrap registry in Arc
270        let registry = Arc::new(registry);
271
272        // Now give batch tool a weak reference to the registry
273        batch_tool.set_registry(Arc::downgrade(&registry));
274
275        registry
276    }
277}
278
279impl Default for ToolRegistry {
280    fn default() -> Self {
281        Self::with_defaults()
282    }
283}
codetether_agent/tool/mod.rs

codetether_agent/tool/
mod.rs
