Skip to main content

funera_builtin_tools/
lib.rs

1//! # funera-builtin-tools
2//!
3//! Default tool implementations for the funera agent framework.
4//!
5//! Provides four built-in tools that implement the funera_core `Tool` trait:
6//!
7//! | Tool | Description |
8//! |------|-------------|
9//! | [`ReadTool`] | Read files and directories with hashline-anchored output |
10//! | [`WriteTool`] | Write content to files, auto-creating parent directories |
11//! | [`EditTool`] | Edit files using hashline-anchored replace/append/prepend operations |
12//! | [`ShellTool`] | Execute shell commands cross-platform with timeout |
13//!
14//! ## Quick start
15//!
16//! ```rust,ignore
17//! use funera_builtin_tools::register_all_tools;
18//! use funera_core::re_act::tool::ToolRegistry;
19//!
20//! let mut registry = ToolRegistry::new();
21//! register_all_tools(&mut registry);
22//! ```
23
24pub mod edit;
25pub mod hashline;
26pub mod read;
27pub mod shell;
28pub mod write;
29
30pub use edit::EditTool;
31pub use read::ReadTool;
32pub use shell::ShellTool;
33pub use write::WriteTool;
34
35use std::sync::Arc;
36
37#[cfg(feature = "sandbox")]
38pub use funera_core::security::sandbox::SandboxPolicy;
39
40use funera_core::re_act::tool::ToolRegistry;
41
42/// Register all four built-in tools (read, write, edit, shell) in the given registry.
43///
44/// The `shell` tool is registered **without** kernel sandboxing.
45/// Use [`register_all_tools_with_sandbox`] to enable it.
46pub fn register_all_tools(registry: &mut ToolRegistry) {
47    registry.add_tool(Arc::new(ReadTool));
48    registry.add_tool(Arc::new(WriteTool));
49    registry.add_tool(Arc::new(EditTool));
50    registry.add_tool(Arc::new(ShellTool::new()));
51}
52
53/// Register all built-in tools, configuring the `shell` tool with a
54/// [`SandboxPolicy`] for kernel-enforced isolation.
55///
56/// | Platform | Mechanism |
57/// |----------|-----------|
58/// | Linux    | Landlock (nono crate) |
59/// | macOS    | Seatbelt (nono crate) |
60/// | Windows  | Write-Restricted Token + ACLs |
61///
62/// Unsupported platforms/kernels gracefully degrade to normal execution.
63#[cfg(feature = "sandbox")]
64pub fn register_all_tools_with_sandbox(registry: &mut ToolRegistry, policy: SandboxPolicy) {
65    registry.add_tool(Arc::new(ReadTool));
66    registry.add_tool(Arc::new(WriteTool));
67    registry.add_tool(Arc::new(EditTool));
68    registry.add_tool(Arc::new(ShellTool::with_sandbox(policy)));
69}
70
71#[cfg(test)]
72mod tests {
73    use super::*;
74
75    #[test]
76    fn register_all_tools_adds_four_tools() {
77        let mut registry = ToolRegistry::new();
78        register_all_tools(&mut registry);
79        assert_eq!(registry.tool_count(), 4);
80        assert!(registry.tool_exists("read"));
81        assert!(registry.tool_exists("write"));
82        assert!(registry.tool_exists("edit"));
83        assert!(registry.tool_exists("shell"));
84    }
85
86    #[test]
87    fn each_tool_has_valid_schema() {
88        let mut registry = ToolRegistry::new();
89        register_all_tools(&mut registry);
90        let json = registry.available_tools_json();
91        let tools = json.as_array().unwrap();
92        assert_eq!(tools.len(), 4);
93        for tool in tools {
94            assert!(tool["function"]["name"].as_str().is_some());
95            assert!(tool["function"]["parameters"].is_object());
96        }
97    }
98
99    #[cfg(feature = "sandbox")]
100    #[test]
101    fn register_all_tools_with_sandbox_adds_four_tools() {
102        let mut registry = ToolRegistry::new();
103        register_all_tools_with_sandbox(&mut registry, SandboxPolicy::disabled());
104        assert_eq!(registry.tool_count(), 4);
105        assert!(registry.tool_exists("read"));
106        assert!(registry.tool_exists("write"));
107        assert!(registry.tool_exists("edit"));
108        assert!(registry.tool_exists("shell"));
109    }
110}