Skip to main content

tinyharness_lib/custom_tools/
shell.rs

1use std::collections::HashMap;
2
3use serde::{Deserialize, Serialize};
4use tokio::io::AsyncReadExt;
5
6/// A shell command with template substitution and timeout.
7///
8/// The `command` field is a template string with `{var}` placeholders.
9/// At execution time, the placeholders are replaced with values from a
10/// `HashMap<String, String>`. The command is run via `sh -c` (or `cmd /C`
11/// on Windows) with the substituted variables also available as `TH_*`
12/// environment variables.
13///
14/// This type backs the custom-tools system: each custom tool wraps a
15/// `ShellCommand` template executed with the tool's arguments substituted.
16#[derive(Debug, Clone, Serialize, Deserialize)]
17pub struct ShellCommand {
18    /// Command template, e.g. `"docker run --rm {image} sh -c \"$TH_COMMAND\""`.
19    pub command: String,
20    /// Timeout in seconds. Default: 30.
21    #[serde(default = "default_timeout")]
22    pub timeout_secs: u64,
23    /// Working directory for the command. If `None`, inherits the current
24    /// directory of the TinyHarness process.
25    #[serde(default, skip_serializing_if = "Option::is_none")]
26    pub cwd: Option<String>,
27}
28
29fn default_timeout() -> u64 {
30    30
31}
32
33impl ShellCommand {
34    /// Shell-escape a value for safe inline substitution into an unquoted
35    /// position in a shell command.
36    ///
37    /// Wraps the value in single quotes and escapes any single quotes within
38    /// it by replacing `'` with `'\''`. This prevents shell metacharacters
39    /// in the value (e.g. from LLM responses) from breaking the command.
40    fn shell_escape(value: &str) -> String {
41        // Replace ' with '\'' and wrap in single quotes.
42        // e.g.  I'll do it  →  'I'\''ll do it'
43        let escaped = value.replace('\'', "'\\''");
44        format!("'{}'", escaped)
45    }
46
47    /// Escape a value for safe substitution inside a double-quoted string in
48    /// a shell command.
49    ///
50    /// Inside double quotes, the special characters are `"`, `\`, `$`, and
51    /// backtick. These are backslash-escaped to prevent expansion or early
52    /// quote termination.
53    fn escape_for_double_quote(value: &str) -> String {
54        value
55            .replace('\\', "\\\\")
56            .replace('"', "\\\"")
57            .replace('$', "\\$")
58            .replace('`', "\\`")
59    }
60
61    /// Render the command template by substituting `{var}` placeholders.
62    ///
63    /// The renderer is **quote-context-aware**: it tracks whether each
64    /// `{var}` placeholder appears inside single quotes, double quotes, or
65    /// unquoted in the template, and applies the appropriate escaping:
66    ///
67    /// | Context | Strategy |
68    /// |---------|----------|
69    /// | Unquoted | Wrap in single quotes (`shell_escape`) |
70    /// | Inside `"..."` | Escape `"`, `\`, `$`, `` ` `` for double-quote context |
71    /// | Inside `'...'` | Close the quote, insert `shell_escape`d value, reopen |
72    ///
73    /// This prevents broken quoting when the template already wraps a
74    /// placeholder in quotes, e.g. `echo "{user_input}"` or `echo '{tool}'`.
75    ///
76    /// Missing variables (not present in `vars`) are left as-is — the
77    /// `{placeholder}` appears literally in the rendered command.
78    pub fn render(&self, vars: &HashMap<String, String>) -> String {
79        let chars: Vec<char> = self.command.chars().collect();
80        let mut result = String::new();
81        let mut i = 0;
82        let mut in_single = false;
83        let mut in_double = false;
84
85        while i < chars.len() {
86            let c = chars[i];
87
88            if c == '\'' && !in_double {
89                in_single = !in_single;
90                result.push(c);
91                i += 1;
92            } else if c == '"' && !in_single {
93                in_double = !in_double;
94                result.push(c);
95                i += 1;
96            } else if c == '{' {
97                // Try to find a matching `}` and look up the var name.
98                if let Some(end) = chars[i + 1..].iter().position(|&ch| ch == '}') {
99                    let var_name: String = chars[i + 1..i + 1 + end].iter().collect();
100                    if let Some(value) = vars.get(&var_name) {
101                        if in_double {
102                            // Inside double quotes: escape special chars
103                            // for double-quote context.
104                            result.push_str(&Self::escape_for_double_quote(value));
105                        } else if in_single {
106                            // Inside single quotes: close the quote, insert
107                            // the shell-escaped value, then reopen.
108                            // e.g. 'It is {var}' with value=it's →
109                            //   'It is '\''it'\''s''
110                            result.push('\'');
111                            result.push_str(&Self::shell_escape(value));
112                            result.push('\'');
113                        } else {
114                            // Unquoted: wrap in single quotes.
115                            result.push_str(&Self::shell_escape(value));
116                        }
117                        i += end + 2;
118                        continue;
119                    }
120                }
121                // Not a known var or no closing `}` — push literally.
122                result.push(c);
123                i += 1;
124            } else {
125                result.push(c);
126                i += 1;
127            }
128        }
129
130        result
131    }
132
133    /// Execute the command asynchronously.
134    ///
135    /// Returns `Ok(stdout)` on success (exit code 0), or `Err(message)` on
136    /// failure (non-zero exit, timeout, or spawn error).
137    ///
138    /// The `vars` are used for both `{var}` template substitution and as
139    /// `TH_*` environment variables.
140    pub async fn execute(&self, vars: &HashMap<String, String>) -> Result<String, String> {
141        let rendered = self.render(vars);
142
143        let mut cmd = if cfg!(target_os = "windows") {
144            let mut c = tokio::process::Command::new("cmd");
145            c.arg("/C").arg(&rendered);
146            c
147        } else {
148            let mut c = tokio::process::Command::new("sh");
149            c.arg("-c").arg(&rendered);
150            c
151        };
152
153        // Set environment variables
154        for (key, value) in vars {
155            let env_key = format!("TH_{}", key.to_uppercase().replace([' ', '-'], "_"));
156            cmd.env(env_key, value);
157        }
158        // Also set the raw key as an env var for convenience
159        for (key, value) in vars {
160            cmd.env(key, value);
161        }
162
163        if let Some(ref cwd) = self.cwd {
164            cmd.current_dir(cwd);
165        }
166
167        #[cfg(unix)]
168        cmd.process_group(0);
169
170        let mut child = cmd
171            .stdin(std::process::Stdio::null())
172            .stdout(std::process::Stdio::piped())
173            .stderr(std::process::Stdio::piped())
174            .spawn()
175            .map_err(|e| format!("Failed to spawn command: {}", e))?;
176
177        let timeout = tokio::time::Duration::from_secs(self.timeout_secs);
178        let wait_result = tokio::time::timeout(timeout, child.wait()).await;
179
180        match wait_result {
181            Ok(Ok(status)) => {
182                let stdout = read_pipe(child.stdout.take()).await;
183                let stderr = read_pipe(child.stderr.take()).await;
184
185                if status.success() {
186                    Ok(stdout.trim().to_string())
187                } else {
188                    let mut msg =
189                        format!("Command exited with code {}", status.code().unwrap_or(-1));
190                    if !stderr.is_empty() {
191                        msg.push_str(&format!("\n{}", stderr.trim()));
192                    }
193                    if !stdout.is_empty() {
194                        msg.push_str(&format!("\n{}", stdout.trim()));
195                    }
196                    Err(msg)
197                }
198            }
199            Ok(Err(e)) => {
200                crate::tools::run::kill_child(child).await;
201                Err(format!("Failed to wait for command: {}", e))
202            }
203            Err(_) => {
204                crate::tools::run::kill_child(child).await;
205                Err(format!(
206                    "Command timed out after {}s: {}",
207                    self.timeout_secs, rendered
208                ))
209            }
210        }
211    }
212}
213
214/// Read a piped stdout/stderr to a string, truncating at 10 KB.
215async fn read_pipe<T: tokio::io::AsyncRead + Unpin>(mut pipe: Option<T>) -> String {
216    if let Some(ref mut r) = pipe.as_mut() {
217        let mut buf = String::new();
218        let _ = r.read_to_string(&mut buf).await;
219        buf
220    } else {
221        String::new()
222    }
223}
224
225/// Execute a shell command for a custom tool, substituting tool arguments.
226///
227/// The tool arguments are passed as a `HashMap<String, String>` (same as
228/// built-in tools).
229pub async fn execute_shell_tool(command: &ShellCommand, args: &HashMap<String, String>) -> String {
230    match command.execute(args).await {
231        Ok(stdout) => {
232            if stdout.is_empty() {
233                "(no output)".to_string()
234            } else {
235                stdout
236            }
237        }
238        Err(e) => format!("Error: {}", e),
239    }
240}
241
242#[cfg(test)]
243mod tests {
244    use super::*;
245
246    #[test]
247    fn test_render_basic_substitution() {
248        let cmd = ShellCommand {
249            command: "echo {name}".to_string(),
250            timeout_secs: 5,
251            cwd: None,
252        };
253        let mut vars = HashMap::new();
254        vars.insert("name".to_string(), "world".to_string());
255        // Values are shell-escaped (wrapped in single quotes)
256        assert_eq!(cmd.render(&vars), "echo 'world'");
257    }
258
259    #[test]
260    fn test_render_multiple_vars() {
261        let cmd = ShellCommand {
262            command: "docker run --rm {image} sh -c {command}".to_string(),
263            timeout_secs: 30,
264            cwd: None,
265        };
266        let mut vars = HashMap::new();
267        vars.insert("image".to_string(), "ubuntu:latest".to_string());
268        vars.insert("command".to_string(), "ls -la".to_string());
269        // Each value is individually shell-escaped
270        assert_eq!(
271            cmd.render(&vars),
272            "docker run --rm 'ubuntu:latest' sh -c 'ls -la'"
273        );
274    }
275
276    #[test]
277    fn test_render_shell_escapes_single_quotes() {
278        let cmd = ShellCommand {
279            command: "echo {text}".to_string(),
280            timeout_secs: 5,
281            cwd: None,
282        };
283        let mut vars = HashMap::new();
284        vars.insert("text".to_string(), "I'll do it".to_string());
285        // Single quotes in the value are escaped: ' -> '\''
286        assert_eq!(cmd.render(&vars), "echo 'I'\\''ll do it'");
287    }
288
289    #[test]
290    fn test_render_shell_escapes_metacharacters() {
291        let cmd = ShellCommand {
292            command: "echo -n {response} | wc -c".to_string(),
293            timeout_secs: 5,
294            cwd: None,
295        };
296        let mut vars = HashMap::new();
297        vars.insert(
298            "response".to_string(),
299            "I'll find all files in `./src` and run $(whoami)".to_string(),
300        );
301        let rendered = cmd.render(&vars);
302        // The value is safely quoted — metacharacters are inert
303        assert_eq!(
304            rendered,
305            "echo -n 'I'\\''ll find all files in `./src` and run $(whoami)' | wc -c"
306        );
307    }
308
309    #[test]
310    fn test_render_inside_double_quotes() {
311        let cmd = ShellCommand {
312            command: "echo \"{text}\"".to_string(),
313            timeout_secs: 5,
314            cwd: None,
315        };
316        let mut vars = HashMap::new();
317        vars.insert("text".to_string(), "He said \"hi\" and $HOME".to_string());
318        // Inside double quotes: escape ", \, $, ` for double-quote context
319        let rendered = cmd.render(&vars);
320        assert_eq!(rendered, "echo \"He said \\\"hi\\\" and \\$HOME\"");
321    }
322
323    #[test]
324    fn test_render_inside_double_quotes_backtick() {
325        let cmd = ShellCommand {
326            command: "echo \"{text}\"".to_string(),
327            timeout_secs: 5,
328            cwd: None,
329        };
330        let mut vars = HashMap::new();
331        vars.insert("text".to_string(), "run `whoami`".to_string());
332        let rendered = cmd.render(&vars);
333        assert_eq!(rendered, "echo \"run \\`whoami\\`\"");
334    }
335
336    #[test]
337    fn test_render_inside_double_quotes_simple() {
338        let cmd = ShellCommand {
339            command: "echo \"{name}\"".to_string(),
340            timeout_secs: 5,
341            cwd: None,
342        };
343        let mut vars = HashMap::new();
344        vars.insert("name".to_string(), "world".to_string());
345        // Simple value inside double quotes — no extra quoting needed
346        let rendered = cmd.render(&vars);
347        assert_eq!(rendered, "echo \"world\"");
348    }
349
350    #[test]
351    fn test_render_inside_single_quotes() {
352        let cmd = ShellCommand {
353            command: "echo '{text}'".to_string(),
354            timeout_secs: 5,
355            cwd: None,
356        };
357        let mut vars = HashMap::new();
358        vars.insert("text".to_string(), "it's here".to_string());
359        let rendered = cmd.render(&vars);
360        assert_eq!(rendered, "echo '''it'\\''s here'''");
361    }
362
363    #[test]
364    fn test_render_inside_single_quotes_simple() {
365        let cmd = ShellCommand {
366            command: "echo '{name}'".to_string(),
367            timeout_secs: 5,
368            cwd: None,
369        };
370        let mut vars = HashMap::new();
371        vars.insert("name".to_string(), "world".to_string());
372        let rendered = cmd.render(&vars);
373        assert_eq!(rendered, "echo '''world'''");
374    }
375
376    #[test]
377    fn test_render_mixed_quotes_multiple_vars() {
378        let cmd = ShellCommand {
379            command: "echo \"{greeting}\" '{name}'".to_string(),
380            timeout_secs: 5,
381            cwd: None,
382        };
383        let mut vars = HashMap::new();
384        vars.insert("greeting".to_string(), "hello $USER".to_string());
385        vars.insert("name".to_string(), "world".to_string());
386        let rendered = cmd.render(&vars);
387        assert_eq!(rendered, "echo \"hello \\$USER\" '''world'''");
388    }
389
390    #[test]
391    fn test_render_nested_brace_not_var() {
392        let cmd = ShellCommand {
393            command: "echo {not_a_var}".to_string(),
394            timeout_secs: 5,
395            cwd: None,
396        };
397        let vars = HashMap::new();
398        // Unknown var stays as literal {not_a_var}
399        assert_eq!(cmd.render(&vars), "echo {not_a_var}");
400    }
401
402    #[test]
403    fn test_render_unclosed_brace() {
404        let cmd = ShellCommand {
405            command: "echo {name".to_string(),
406            timeout_secs: 5,
407            cwd: None,
408        };
409        let mut vars = HashMap::new();
410        vars.insert("name".to_string(), "world".to_string());
411        // No closing } — push { literally
412        assert_eq!(cmd.render(&vars), "echo {name");
413    }
414
415    #[test]
416    fn test_render_missing_var_stays_as_placeholder() {
417        let cmd = ShellCommand {
418            command: "echo {missing}".to_string(),
419            timeout_secs: 5,
420            cwd: None,
421        };
422        let vars = HashMap::new();
423        // Missing vars are left as-is (not replaced with empty string)
424        assert_eq!(cmd.render(&vars), "echo {missing}");
425    }
426
427    #[test]
428    fn test_render_no_vars() {
429        let cmd = ShellCommand {
430            command: "git status".to_string(),
431            timeout_secs: 5,
432            cwd: None,
433        };
434        let vars = HashMap::new();
435        assert_eq!(cmd.render(&vars), "git status");
436    }
437
438    #[test]
439    fn test_default_timeout() {
440        assert_eq!(default_timeout(), 30);
441    }
442
443    #[test]
444    fn test_shell_command_serde() {
445        let json = r#"{"command": "echo hi", "timeout_secs": 10}"#;
446        let cmd: ShellCommand = serde_json::from_str(json).unwrap();
447        assert_eq!(cmd.command, "echo hi");
448        assert_eq!(cmd.timeout_secs, 10);
449        assert!(cmd.cwd.is_none());
450    }
451
452    #[test]
453    fn test_shell_command_serde_default_timeout() {
454        let json = r#"{"command": "echo hi"}"#;
455        let cmd: ShellCommand = serde_json::from_str(json).unwrap();
456        assert_eq!(cmd.timeout_secs, 30);
457    }
458
459    #[test]
460    fn test_shell_command_serde_with_cwd() {
461        let json = r#"{"command": "ls", "timeout_secs": 5, "cwd": "/tmp"}"#;
462        let cmd: ShellCommand = serde_json::from_str(json).unwrap();
463        assert_eq!(cmd.cwd.as_deref(), Some("/tmp"));
464    }
465
466    #[tokio::test]
467    async fn test_execute_success() {
468        let cmd = ShellCommand {
469            command: "echo hello".to_string(),
470            timeout_secs: 5,
471            cwd: None,
472        };
473        let vars = HashMap::new();
474        let result = cmd.execute(&vars).await;
475        assert!(result.is_ok());
476        assert_eq!(result.unwrap(), "hello");
477    }
478
479    #[tokio::test]
480    async fn test_execute_with_substitution() {
481        // On Windows, cmd /C doesn't strip single quotes the way sh does,
482        // so shell-escaped values appear literally in the output.
483        let expected = if cfg!(target_os = "windows") {
484            "'world'"
485        } else {
486            "world"
487        };
488        let cmd = ShellCommand {
489            command: "echo {name}".to_string(),
490            timeout_secs: 5,
491            cwd: None,
492        };
493        let mut vars = HashMap::new();
494        vars.insert("name".to_string(), "world".to_string());
495        let result = cmd.execute(&vars).await;
496        assert!(result.is_ok());
497        assert_eq!(result.unwrap(), expected);
498    }
499
500    #[tokio::test]
501    async fn test_execute_failure() {
502        let cmd = ShellCommand {
503            command: "exit 1".to_string(),
504            timeout_secs: 5,
505            cwd: None,
506        };
507        let vars = HashMap::new();
508        let result = cmd.execute(&vars).await;
509        assert!(result.is_err());
510        assert!(result.unwrap_err().contains("exited with code 1"));
511    }
512
513    #[tokio::test]
514    async fn test_execute_timeout() {
515        // Use a long-running command that works on both platforms.
516        let cmd = ShellCommand {
517            command: (if cfg!(target_os = "windows") {
518                "ping -n 100 127.0.0.1 > NUL"
519            } else {
520                "sleep 100"
521            })
522            .to_string(),
523            timeout_secs: 1,
524            cwd: None,
525        };
526        let vars = HashMap::new();
527        let result = cmd.execute(&vars).await;
528        assert!(result.is_err());
529        assert!(
530            result.unwrap_err().contains("timed out"),
531            "expected 'timed out' in error"
532        );
533    }
534
535    #[tokio::test]
536    async fn test_execute_env_var_available() {
537        let cmd = ShellCommand {
538            command: (if cfg!(target_os = "windows") {
539                "echo %TH_NAME%"
540            } else {
541                "echo $TH_NAME"
542            })
543            .to_string(),
544            timeout_secs: 5,
545            cwd: None,
546        };
547        let mut vars = HashMap::new();
548        vars.insert("name".to_string(), "from_env".to_string());
549        let result = cmd.execute(&vars).await;
550        assert!(result.is_ok());
551        assert_eq!(result.unwrap(), "from_env");
552    }
553
554    #[tokio::test]
555    async fn test_execute_cwd() {
556        let tmp = std::env::temp_dir();
557        let cmd = ShellCommand {
558            command: (if cfg!(target_os = "windows") {
559                "cd"
560            } else {
561                "pwd"
562            })
563            .to_string(),
564            timeout_secs: 5,
565            cwd: Some(tmp.to_string_lossy().to_string()),
566        };
567        let vars = HashMap::new();
568        let result = cmd.execute(&vars).await;
569        assert!(result.is_ok());
570        let expected = std::fs::canonicalize(&tmp)
571            .unwrap_or_else(|_| tmp.clone())
572            .to_string_lossy()
573            .to_string();
574        let actual = result.unwrap();
575        if cfg!(target_os = "windows") {
576            let actual_canon = std::fs::canonicalize(&actual)
577                .or_else(|_| std::path::Path::new(&actual).canonicalize())
578                .map(|p| p.to_string_lossy().to_string())
579                .unwrap_or(actual);
580            let expected_canon = std::fs::canonicalize(&expected)
581                .map(|p| p.to_string_lossy().to_string())
582                .unwrap_or(expected);
583            assert_eq!(actual_canon.to_lowercase(), expected_canon.to_lowercase());
584        } else {
585            assert_eq!(actual, expected);
586        }
587    }
588
589    #[tokio::test]
590    async fn test_execute_shell_tool_success() {
591        let expected = if cfg!(target_os = "windows") {
592            "hello 'world'"
593        } else {
594            "hello world"
595        };
596        let cmd = ShellCommand {
597            command: "echo hello {name}".to_string(),
598            timeout_secs: 5,
599            cwd: None,
600        };
601        let mut args = HashMap::new();
602        args.insert("name".to_string(), "world".to_string());
603        let result = execute_shell_tool(&cmd, &args).await;
604        assert_eq!(result, expected);
605    }
606
607    #[tokio::test]
608    async fn test_execute_shell_tool_error() {
609        let cmd = ShellCommand {
610            command: "exit 42".to_string(),
611            timeout_secs: 5,
612            cwd: None,
613        };
614        let args = HashMap::new();
615        let result = execute_shell_tool(&cmd, &args).await;
616        assert!(result.starts_with("Error:"));
617    }
618
619    #[tokio::test]
620    async fn test_execute_shell_tool_empty_output() {
621        let cmd = ShellCommand {
622            command: "true".to_string(),
623            timeout_secs: 5,
624            cwd: None,
625        };
626        let args = HashMap::new();
627        let result = execute_shell_tool(&cmd, &args).await;
628        assert_eq!(result, "(no output)");
629    }
630
631    #[tokio::test]
632    async fn test_execute_double_quoted_var_with_special_chars() {
633        let cmd = ShellCommand {
634            command: "echo \"{text}\"".to_string(),
635            timeout_secs: 5,
636            cwd: None,
637        };
638        let mut vars = HashMap::new();
639        vars.insert("text".to_string(), "He said \"hi\" and $FOO".to_string());
640        let result = cmd.execute(&vars).await;
641        assert!(result.is_ok());
642        if cfg!(target_os = "windows") {
643            // cmd /C echoes backslash escapes and $ literally; the exact
644            // output is platform-specific, so only check the command succeeds.
645        } else {
646            assert_eq!(result.unwrap(), "He said \"hi\" and $FOO");
647        }
648    }
649
650    #[tokio::test]
651    async fn test_execute_single_quoted_var_with_single_quote() {
652        let cmd = ShellCommand {
653            command: "echo '{text}'".to_string(),
654            timeout_secs: 5,
655            cwd: None,
656        };
657        let mut vars = HashMap::new();
658        vars.insert("text".to_string(), "it's here".to_string());
659        let result = cmd.execute(&vars).await;
660        assert!(result.is_ok());
661        if cfg!(target_os = "windows") {
662            // cmd /C treats single quotes as literal characters.
663        } else {
664            assert_eq!(result.unwrap(), "it's here");
665        }
666    }
667
668    #[tokio::test]
669    async fn test_execute_unquoted_var_with_single_quote() {
670        let cmd = ShellCommand {
671            command: "echo {text}".to_string(),
672            timeout_secs: 5,
673            cwd: None,
674        };
675        let mut vars = HashMap::new();
676        vars.insert("text".to_string(), "it's here".to_string());
677        let result = cmd.execute(&vars).await;
678        assert!(result.is_ok());
679        if cfg!(target_os = "windows") {
680            // cmd /C treats single quotes as literal characters.
681        } else {
682            assert_eq!(result.unwrap(), "it's here");
683        }
684    }
685}