Skip to main content

tinyharness_lib/custom_tools/
custom_tool.rs

1use std::collections::HashMap;
2
3use schemars::Schema;
4use serde::{Deserialize, Serialize};
5use serde_json::Value;
6
7use super::shell::{ShellCommand, execute_shell_tool};
8use crate::tools::tool::{BoxFuture, Tool, ToolCategory, make_tool};
9
10/// Category string for custom tools, as used in the config file.
11///
12/// `"readonly"` maps to `ToolCategory::ReadOnly` (auto-executed, no confirmation).
13/// `"destructive"` maps to `ToolCategory::Destructive` (requires confirmation).
14/// `"signal"` is not allowed for custom tools.
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
16#[serde(rename_all = "lowercase")]
17pub enum CustomToolCategory {
18    ReadOnly,
19    Destructive,
20}
21
22impl CustomToolCategory {
23    pub fn to_tool_category(self) -> ToolCategory {
24        match self {
25            CustomToolCategory::ReadOnly => ToolCategory::ReadOnly,
26            CustomToolCategory::Destructive => ToolCategory::Destructive,
27        }
28    }
29}
30
31/// Definition of a custom tool from the custom-tools config file.
32///
33/// Custom tools are registered alongside built-in tools and can be called
34/// by the LLM. They execute shell commands with parameter substitution.
35#[derive(Debug, Clone, Serialize, Deserialize)]
36pub struct CustomToolDefinition {
37    /// Tool name (must not collide with built-in tool names).
38    pub name: String,
39    /// Description shown to the LLM.
40    pub description: String,
41    /// `"readonly"` or `"destructive"`. Readonly tools are auto-executed;
42    /// destructive tools require user confirmation.
43    pub category: CustomToolCategory,
44    /// JSON Schema for the tool's parameters. This is sent to the LLM as-is.
45    pub parameters: Value,
46    /// Shell command template with `{param}` placeholders.
47    #[serde(flatten)]
48    pub command: ShellCommand,
49}
50
51impl CustomToolDefinition {
52    /// Convert this definition into a `Tool` that can be registered in `ToolManager`.
53    pub fn build_tool(&self) -> Result<Tool, String> {
54        let parameters: Schema = serde_json::from_value(self.parameters.clone()).map_err(|e| {
55            format!(
56                "Failed to parse parameters schema for '{}': {}",
57                self.name, e
58            )
59        })?;
60
61        let command = self.command.clone();
62        let category = self.category.to_tool_category();
63        let description = self.description.clone();
64
65        Ok(make_tool(
66            &self.name,
67            &description,
68            category,
69            parameters,
70            move |args: HashMap<String, String>| -> BoxFuture<'static, String> {
71                let cmd = command.clone();
72                Box::pin(async move { execute_shell_tool(&cmd, &args).await })
73            },
74        ))
75    }
76}
77
78#[cfg(test)]
79mod tests {
80    use super::*;
81
82    #[test]
83    fn test_custom_tool_category_serde() {
84        let json = r#""readonly""#;
85        let cat: CustomToolCategory = serde_json::from_str(json).unwrap();
86        assert_eq!(cat, CustomToolCategory::ReadOnly);
87
88        let json = r#""destructive""#;
89        let cat: CustomToolCategory = serde_json::from_str(json).unwrap();
90        assert_eq!(cat, CustomToolCategory::Destructive);
91    }
92
93    #[test]
94    fn test_custom_tool_definition_parses() {
95        let json = r#"{
96            "name": "docker_run",
97            "description": "Run a command in a Docker container",
98            "category": "destructive",
99            "parameters": {
100                "type": "object",
101                "properties": {
102                    "image": { "type": "string", "description": "Docker image" },
103                    "command": { "type": "string", "description": "Shell command" }
104                },
105                "required": ["image", "command"]
106            },
107            "command": "docker run --rm {image} sh -c \"$TH_COMMAND\"",
108            "timeout_secs": 120
109        }"#;
110        let tool: CustomToolDefinition = serde_json::from_str(json).unwrap();
111        assert_eq!(tool.name, "docker_run");
112        assert_eq!(tool.category, CustomToolCategory::Destructive);
113        assert_eq!(
114            tool.command.command,
115            "docker run --rm {image} sh -c \"$TH_COMMAND\""
116        );
117        assert_eq!(tool.command.timeout_secs, 120);
118    }
119
120    #[test]
121    fn test_custom_tool_definition_default_timeout() {
122        let json = r#"{
123            "name": "greet",
124            "description": "Say hi",
125            "category": "readonly",
126            "parameters": {
127                "type": "object",
128                "properties": {
129                    "name": { "type": "string" }
130                },
131                "required": ["name"]
132            },
133            "command": "echo hello {name}"
134        }"#;
135        let tool: CustomToolDefinition = serde_json::from_str(json).unwrap();
136        assert_eq!(tool.command.timeout_secs, 30);
137    }
138
139    #[test]
140    fn test_build_tool_success() {
141        let def = CustomToolDefinition {
142            name: "greet".to_string(),
143            description: "Say hello".to_string(),
144            category: CustomToolCategory::ReadOnly,
145            parameters: serde_json::json!({
146                "type": "object",
147                "properties": {
148                    "name": { "type": "string", "description": "Who to greet" }
149                },
150                "required": ["name"]
151            }),
152            command: ShellCommand {
153                command: "echo hello {name}".to_string(),
154                timeout_secs: 5,
155                cwd: None,
156            },
157        };
158        let tool = def.build_tool().unwrap();
159        assert_eq!(tool.name, "greet");
160        assert_eq!(tool.description, "Say hello");
161        assert_eq!(tool.category, ToolCategory::ReadOnly);
162    }
163
164    #[test]
165    fn test_build_tool_invalid_schema() {
166        let def = CustomToolDefinition {
167            name: "bad".to_string(),
168            description: "Bad tool".to_string(),
169            category: CustomToolCategory::ReadOnly,
170            parameters: serde_json::json!("not an object"),
171            command: ShellCommand {
172                command: "echo hi".to_string(),
173                timeout_secs: 5,
174                cwd: None,
175            },
176        };
177        let result = def.build_tool();
178        assert!(result.is_err());
179        assert!(
180            result
181                .err()
182                .unwrap()
183                .contains("Failed to parse parameters schema")
184        );
185    }
186
187    #[tokio::test]
188    async fn test_built_tool_executes() {
189        let def = CustomToolDefinition {
190            name: "echo_tool".to_string(),
191            description: "Echo a value".to_string(),
192            category: CustomToolCategory::ReadOnly,
193            parameters: serde_json::json!({
194                "type": "object",
195                "properties": {
196                    "value": { "type": "string", "description": "Value to echo" }
197                },
198                "required": ["value"]
199            }),
200            command: ShellCommand {
201                command: "echo {value}".to_string(),
202                timeout_secs: 5,
203                cwd: None,
204            },
205        };
206        let tool = def.build_tool().unwrap();
207        let args = serde_json::json!({"value": "test123"});
208        let result = crate::tools::tool::execute_tool_call(&tool, &args).await;
209        // On Windows, cmd /C doesn't strip single quotes the way sh does,
210        // so shell-escaped values appear literally in the output.
211        let expected = if cfg!(target_os = "windows") {
212            "'test123'"
213        } else {
214            "test123"
215        };
216        assert_eq!(result, expected);
217    }
218
219    #[tokio::test]
220    async fn test_built_tool_error_on_failure() {
221        let def = CustomToolDefinition {
222            name: "fail_tool".to_string(),
223            description: "Always fails".to_string(),
224            category: CustomToolCategory::Destructive,
225            parameters: serde_json::json!({
226                "type": "object",
227                "properties": {},
228                "required": []
229            }),
230            command: ShellCommand {
231                command: "exit 1".to_string(),
232                timeout_secs: 5,
233                cwd: None,
234            },
235        };
236        let tool = def.build_tool().unwrap();
237        let args = serde_json::json!({});
238        let result = crate::tools::tool::execute_tool_call(&tool, &args).await;
239        assert!(result.starts_with("Error:"));
240    }
241}