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_with_sandbox};
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        self.build_tool_with_sandbox(None)
55    }
56
57    /// [`CustomToolDefinition::build_tool`] with an OS-level process sandbox.
58    ///
59    /// The sandbox is captured by the handler because tool handlers are opaque
60    /// closures that outlive the `ToolManager`, so it must be supplied at
61    /// registration time — see [`ToolManager::set_sandbox`].
62    ///
63    /// [`ToolManager::set_sandbox`]: crate::tools::ToolManager::set_sandbox
64    pub fn build_tool_with_sandbox(
65        &self,
66        sandbox: Option<crate::sandbox::Sandbox>,
67    ) -> Result<Tool, String> {
68        let parameters: Schema = serde_json::from_value(self.parameters.clone()).map_err(|e| {
69            format!(
70                "Failed to parse parameters schema for '{}': {}",
71                self.name, e
72            )
73        })?;
74
75        let command = self.command.clone();
76        let category = self.category.to_tool_category();
77        let description = self.description.clone();
78
79        Ok(make_tool(
80            &self.name,
81            &description,
82            category,
83            parameters,
84            move |args: HashMap<String, String>| -> BoxFuture<'static, String> {
85                let cmd = command.clone();
86                let sb = sandbox.clone();
87                Box::pin(
88                    async move { execute_shell_tool_with_sandbox(&cmd, &args, sb.as_ref()).await },
89                )
90            },
91        ))
92    }
93}
94
95#[cfg(test)]
96mod tests {
97    use super::*;
98
99    #[test]
100    fn test_custom_tool_category_serde() {
101        let json = r#""readonly""#;
102        let cat: CustomToolCategory = serde_json::from_str(json).unwrap();
103        assert_eq!(cat, CustomToolCategory::ReadOnly);
104
105        let json = r#""destructive""#;
106        let cat: CustomToolCategory = serde_json::from_str(json).unwrap();
107        assert_eq!(cat, CustomToolCategory::Destructive);
108    }
109
110    #[test]
111    fn test_custom_tool_definition_parses() {
112        let json = r#"{
113            "name": "docker_run",
114            "description": "Run a command in a Docker container",
115            "category": "destructive",
116            "parameters": {
117                "type": "object",
118                "properties": {
119                    "image": { "type": "string", "description": "Docker image" },
120                    "command": { "type": "string", "description": "Shell command" }
121                },
122                "required": ["image", "command"]
123            },
124            "command": "docker run --rm {image} sh -c \"$TH_COMMAND\"",
125            "timeout_secs": 120
126        }"#;
127        let tool: CustomToolDefinition = serde_json::from_str(json).unwrap();
128        assert_eq!(tool.name, "docker_run");
129        assert_eq!(tool.category, CustomToolCategory::Destructive);
130        assert_eq!(
131            tool.command.command,
132            "docker run --rm {image} sh -c \"$TH_COMMAND\""
133        );
134        assert_eq!(tool.command.timeout_secs, 120);
135    }
136
137    #[test]
138    fn test_custom_tool_definition_default_timeout() {
139        let json = r#"{
140            "name": "greet",
141            "description": "Say hi",
142            "category": "readonly",
143            "parameters": {
144                "type": "object",
145                "properties": {
146                    "name": { "type": "string" }
147                },
148                "required": ["name"]
149            },
150            "command": "echo hello {name}"
151        }"#;
152        let tool: CustomToolDefinition = serde_json::from_str(json).unwrap();
153        assert_eq!(tool.command.timeout_secs, 30);
154    }
155
156    #[test]
157    fn test_build_tool_success() {
158        let def = CustomToolDefinition {
159            name: "greet".to_string(),
160            description: "Say hello".to_string(),
161            category: CustomToolCategory::ReadOnly,
162            parameters: serde_json::json!({
163                "type": "object",
164                "properties": {
165                    "name": { "type": "string", "description": "Who to greet" }
166                },
167                "required": ["name"]
168            }),
169            command: ShellCommand {
170                command: "echo hello {name}".to_string(),
171                timeout_secs: 5,
172                cwd: None,
173            },
174        };
175        let tool = def.build_tool().unwrap();
176        assert_eq!(tool.name, "greet");
177        assert_eq!(tool.description, "Say hello");
178        assert_eq!(tool.category, ToolCategory::ReadOnly);
179    }
180
181    #[test]
182    fn test_build_tool_invalid_schema() {
183        let def = CustomToolDefinition {
184            name: "bad".to_string(),
185            description: "Bad tool".to_string(),
186            category: CustomToolCategory::ReadOnly,
187            parameters: serde_json::json!("not an object"),
188            command: ShellCommand {
189                command: "echo hi".to_string(),
190                timeout_secs: 5,
191                cwd: None,
192            },
193        };
194        let result = def.build_tool();
195        assert!(result.is_err());
196        assert!(
197            result
198                .err()
199                .unwrap()
200                .contains("Failed to parse parameters schema")
201        );
202    }
203
204    #[tokio::test]
205    async fn test_built_tool_executes() {
206        let def = CustomToolDefinition {
207            name: "echo_tool".to_string(),
208            description: "Echo a value".to_string(),
209            category: CustomToolCategory::ReadOnly,
210            parameters: serde_json::json!({
211                "type": "object",
212                "properties": {
213                    "value": { "type": "string", "description": "Value to echo" }
214                },
215                "required": ["value"]
216            }),
217            command: ShellCommand {
218                command: "echo {value}".to_string(),
219                timeout_secs: 5,
220                cwd: None,
221            },
222        };
223        let tool = def.build_tool().unwrap();
224        let args = serde_json::json!({"value": "test123"});
225        let result = crate::tools::tool::execute_tool_call(&tool, &args).await;
226        // On Windows, cmd /C doesn't strip single quotes the way sh does,
227        // so shell-escaped values appear literally in the output.
228        let expected = if cfg!(target_os = "windows") {
229            "'test123'"
230        } else {
231            "test123"
232        };
233        assert_eq!(result, expected);
234    }
235
236    #[tokio::test]
237    async fn test_built_tool_error_on_failure() {
238        let def = CustomToolDefinition {
239            name: "fail_tool".to_string(),
240            description: "Always fails".to_string(),
241            category: CustomToolCategory::Destructive,
242            parameters: serde_json::json!({
243                "type": "object",
244                "properties": {},
245                "required": []
246            }),
247            command: ShellCommand {
248                command: "exit 1".to_string(),
249                timeout_secs: 5,
250                cwd: None,
251            },
252        };
253        let tool = def.build_tool().unwrap();
254        let args = serde_json::json!({});
255        let result = crate::tools::tool::execute_tool_call(&tool, &args).await;
256        assert!(result.starts_with("Error:"));
257    }
258}