vtcode_core/tools/
mod.rs

1//! # Tool System Architecture
2//!
3//! This module provides a modular, composable architecture for VTCode agent tools,
4//! implementing a registry-based system for tool discovery, execution, and management.
5//!
6//! ## Architecture Overview
7//!
8//! The tool system is designed around several key principles:
9//!
10//! - **Modularity**: Each tool is a focused, reusable component
11//! - **Registry Pattern**: Centralized tool registration and discovery
12//! - **Policy-Based Execution**: Configurable execution policies and safety checks
13//! - **Type Safety**: Strong typing for tool parameters and results
14//! - **Async Support**: Full async/await support for all tool operations
15//!
16//! ## Core Components
17//!
18//! ### Tool Registry
19//! ```rust,no_run
20//! use vtcode_core::tools::{ToolRegistry, ToolRegistration};
21//!
22//! #[tokio::main]
23//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
24//!     let workspace = std::env::current_dir()?;
25//!     let mut registry = ToolRegistry::new(workspace);
26//!
27//!     // Register a custom tool
28//!     let tool = ToolRegistration {
29//!         name: "my_tool".to_string(),
30//!         description: "A custom tool".to_string(),
31//!         parameters: serde_json::json!({"type": "object"}),
32//!         handler: |args| async move {
33//!             Ok(serde_json::json!({"result": "success"}))
34//!         },
35//!     };
36//!
37//!     registry.register_tool(tool).await?;
38//!     Ok(())
39//! }
40//! ```
41//!
42//! ### Tool Categories
43//!
44//! #### File Operations
45//! - **File Operations**: Read, write, create, delete files
46//! - **Search Tools**: Grep, AST-based search, advanced search
47//! - **Cache Management**: File caching and performance optimization
48//!
49//! #### Terminal Integration
50//! - **Bash Tools**: Shell command execution
51//! - **PTY Support**: Full terminal emulation
52//! - **Command Policies**: Safety and execution controls
53//!
54//! #### Code Analysis
55//! - **Tree-Sitter**: Syntax-aware code analysis
56//! - **AST Grep**: Structural code search and transformation
57//! - **Srgn**: Syntax-aware code modification
58//!
59//! ## Tool Execution
60//!
61//! ```rust,no_run
62//! use vtcode_core::tools::ToolRegistry;
63//!
64//! #[tokio::main]
65//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
66//!     let mut registry = ToolRegistry::new(std::env::current_dir()?);
67//!
68//!     // Execute a tool
69//!     let args = serde_json::json!({"path": "."});
70//!     let result = registry.execute_tool("list_files", args).await?;
71//!
72//!     println!("Result: {}", result);
73//!     Ok(())
74//! }
75//! ```
76//!
77//! ## Safety & Policies
78//!
79//! The tool system includes comprehensive safety features:
80//!
81//! - **Path Validation**: All file operations check workspace boundaries
82//! - **Command Policies**: Configurable allow/deny lists for terminal commands
83//! - **Execution Limits**: Timeout and resource usage controls
84//! - **Audit Logging**: Complete trail of tool executions
85//!
86//! ## Custom Tool Development
87//!
88//! ```rust,no_run
89//! use vtcode_core::tools::traits::Tool;
90//! use serde_json::Value;
91//!
92//! struct MyCustomTool;
93//!
94//! #[async_trait::async_trait]
95//! impl Tool for MyCustomTool {
96//!     async fn execute(&self, args: Value) -> Result<Value, Box<dyn std::error::Error + Send + Sync>> {
97//!         // Tool implementation
98//!         Ok(serde_json::json!({"status": "completed"}))
99//!     }
100//!
101//!     fn name(&self) -> &str {
102//!         "my_custom_tool"
103//!     }
104//!
105//!     fn description(&self) -> &str {
106//!         "A custom tool for specific tasks"
107//!     }
108//!
109//!     fn parameters(&self) -> Value {
110//!         serde_json::json!({
111//!             "type": "object",
112//!             "properties": {
113//!                 "input": {"type": "string"}
114//!             }
115//!         })
116//!     }
117//! }
118//! ```
119//!
120//! Modular tool system for VTCode
121//!
122//! This module provides a composable architecture for agent tools, breaking down
123//! the monolithic implementation into focused, reusable components.
124
125pub mod advanced_search;
126pub mod apply_patch;
127pub mod ast_grep;
128pub mod ast_grep_tool;
129pub mod bash_tool;
130pub mod cache;
131pub mod command;
132pub mod curl_tool;
133pub mod file_ops;
134pub mod file_search;
135pub mod grep_search;
136pub mod plan;
137pub mod registry;
138pub mod search;
139pub mod simple_search;
140pub mod srgn;
141pub mod traits;
142pub mod tree_sitter;
143pub mod types;
144
145// Re-export main types and traits for backward compatibility
146pub use ast_grep_tool::AstGrepTool;
147pub use bash_tool::BashTool;
148pub use cache::FileCache;
149pub use curl_tool::CurlTool;
150pub use grep_search::GrepSearchManager;
151pub use plan::{
152    PlanCompletionState, PlanManager, PlanStep, PlanSummary, PlanUpdateResult, StepStatus,
153    TaskPlan, UpdatePlanArgs,
154};
155pub use registry::{ToolRegistration, ToolRegistry};
156pub use simple_search::SimpleSearchTool;
157pub use srgn::SrgnTool;
158pub use traits::{Tool, ToolExecutor};
159pub use types::*;
160
161// Re-export function declarations for external use
162pub use registry::build_function_declarations;
163pub use registry::build_function_declarations_for_level;
vtcode_core/tools/mod.rs

vtcode_core/tools/
mod.rs
