vtcode_core/tools/
mod.rs

1//! # Tool System Architecture
2//!
3//! This module provides a modular, composable architecture for VT Code 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,ignore
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_file with ripgrep for fast regex-based pattern matching, glob patterns, type filtering
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//! ## Tool Execution
56//!
57//! ```rust,ignore
58//! use vtcode_core::tools::ToolRegistry;
59//!
60//! #[tokio::main]
61//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
62//!     let mut registry = ToolRegistry::new(std::env::current_dir()?);
63//!
64//!     // Execute a tool
65//!     let args = serde_json::json!({"path": "."});
66//!     let result = registry.execute_tool("list_files", args).await?;
67//!
68//!     println!("Result: {}", result);
69//!     Ok(())
70//! }
71//! ```
72//!
73//! ## Safety & Policies
74//!
75//! The tool system includes comprehensive safety features:
76//!
77//! - **Path Validation**: All file operations check workspace boundaries
78//! - **Command Policies**: Configurable allow/deny lists for terminal commands
79//! - **Execution Limits**: Timeout and resource usage controls
80//! - **Audit Logging**: Complete trail of tool executions
81//!
82//! ## Custom Tool Development
83//!
84//! ```rust,ignore
85//! use vtcode_core::tools::traits::Tool;
86//! use serde_json::Value;
87//!
88//! struct MyCustomTool;
89//!
90//! #[async_trait::async_trait]
91//! impl Tool for MyCustomTool {
92//!     async fn execute(&self, args: Value) -> Result<Value, Box<dyn std::error::Error + Send + Sync>> {
93//!         // Tool implementation
94//!         Ok(serde_json::json!({"status": "completed"}))
95//!     }
96//!
97//!     fn name(&self) -> &str {
98//!         "my_custom_tool"
99//!     }
100//!
101//!     fn description(&self) -> &str {
102//!         "A custom tool for specific tasks"
103//!     }
104//!
105//!     fn parameters(&self) -> Value {
106//!         serde_json::json!({
107//!             "type": "object",
108//!             "properties": {
109//!                 "input": {"type": "string"}
110//!             }
111//!         })
112//!     }
113//! }
114//! ```
115//!
116//! Modular tool system for VT Code
117//!
118//! This module provides a composable architecture for agent tools, breaking down
119//! the monolithic implementation into focused, reusable components.
120
121pub mod apply_patch;
122pub use apply_patch::mutation_target_paths;
123pub mod ast_grep_binary;
124pub mod ast_grep_installer;
125pub(crate) mod ast_grep_language;
126pub mod builder;
127pub mod constants;
128pub mod error_messages;
129pub(crate) mod rate_limit_config;
130pub mod request_user_input;
131
132pub mod autonomous_executor;
133pub mod cache;
134pub(crate) mod code_search;
135pub use code_search::normalised_identity as normalised_code_search_identity;
136pub use code_search::normalised_loop_identity as normalised_code_search_loop_identity;
137pub use code_search::normalised_path as normalised_code_search_path;
138pub use code_search::scope_contains_mutated_path as code_search_scope_contains_mutated_path;
139pub mod command;
140pub mod command_args;
141pub mod command_cache;
142pub mod command_policy;
143pub mod command_resolver;
144pub mod continuation;
145pub mod edited_file_monitor;
146pub mod editing;
147pub mod error_helpers;
148pub mod exec_read_target;
149pub mod exec_session;
150pub mod exec_session_id;
151pub mod execution_context;
152pub mod execution_tracker;
153pub mod file_ops;
154pub mod file_search_bridge;
155pub mod file_search_rpc;
156pub mod file_tracker;
157mod grep_backend;
158pub mod grep_cache;
159pub mod grep_file;
160pub mod handlers;
161pub mod invocation;
162pub mod mcp;
163pub mod names;
164pub mod native_memory;
165pub(crate) mod output_limits;
166pub mod path_env;
167pub mod plugins;
168pub mod pty;
169pub mod read_limits;
170pub mod resilience;
171
172pub use resilience::rate_limiter;
173pub mod defuddle;
174pub mod outline_search;
175pub mod registry;
176pub mod result;
177pub mod result_cache;
178pub mod result_metadata;
179pub mod ripgrep_binary;
180pub mod ripgrep_installer;
181pub mod safety_gateway;
182pub mod search_metrics;
183pub(crate) mod search_runtime;
184pub mod shell;
185pub mod shell_snapshot;
186pub mod skills;
187pub mod summarizers;
188#[cfg(feature = "tui")]
189pub mod terminal_app;
190pub mod tool_effectiveness;
191pub mod tool_intent;
192pub mod traits;
193pub(crate) mod tree_sitter_runtime;
194pub mod types;
195pub mod validation;
196pub mod validation_cache;
197pub mod web_fetch;
198pub mod web_search;
199
200// Production-grade improvements modules
201pub use resilience::adaptive_rate_limiter;
202pub mod async_middleware;
203pub mod cached_executor;
204pub mod lru_cache;
205pub mod pattern_detection;
206pub mod registry_adapters;
207pub mod tool_middleware;
208pub mod workflow_optimizer;
209pub use resilience::circuit_breaker;
210pub mod health;
211pub mod improvement_algorithms;
212pub mod improvements_config;
213pub mod improvements_errors;
214pub mod improvements_registry_ext;
215mod install_support;
216pub mod optimized_registry;
217pub mod output_spooler;
218pub mod pattern_engine;
219pub mod request_response;
220pub mod unified_error;
221pub mod untrusted_data;
222
223// Re-export main types and traits for backward compatibility
224pub use ast_grep_installer::{AstGrepInstallOutcome, AstGrepStatus};
225pub use autonomous_executor::{AutonomousExecutor, AutonomousPolicy};
226pub use cache::FileCache;
227pub use command_cache::PermissionCache;
228pub use command_resolver::CommandResolver;
229pub use editing::{Patch, PatchError, PatchHunk, PatchLine, PatchOperation};
230pub use exec_read_target::{ExecReadTarget, parse_exec_read_target};
231pub use exec_session_id::ExecSessionId;
232pub use execution_context::{ToolExecutionContext, ToolExecutionRecord, ToolPattern};
233pub use execution_tracker::{ExecutionRecord, ExecutionStats, ExecutionStatus, ExecutionTracker};
234pub use file_search_rpc::{
235    FileMatchRpc, FileSearchRpcHandler, ListFilesRequest, ListFilesResponse, RpcError, RpcRequest, RpcResponse,
236    SearchFilesRequest, SearchFilesResponse,
237};
238pub use grep_file::GrepSearchManager;
239pub use invocation::{InvocationBuilder, ToolInvocation as UnifiedToolInvocation, ToolInvocationId};
240pub use search_runtime::{
241    SearchToolBundleStatus, SearchToolReadiness, dominant_workspace_language, search_tool_bundle_status,
242};
243
244pub use defuddle::DefuddleTool;
245pub use optimized_registry::{CachedToolMetadata as OptimizedToolMetadata, OptimizedToolRegistry};
246pub use plugins::{PluginHandle, PluginId, PluginInstaller, PluginManifest, PluginRuntime};
247pub use pty::{PtyCommandRequest, PtyCommandResult, PtyManager};
248pub use registry::{
249    ApprovalPattern, ApprovalRecorder, CgpRuntimeMode, JustificationExtractor, JustificationManager, RiskLevel,
250    ToolJustification, ToolRegistration, ToolRegistry, ToolRiskContext, ToolRiskScorer, ToolSource, WorkspaceTrust,
251    native_cgp_tool_factory, wrap_registered_native_tool,
252};
253pub use request_response::{ToolCallRequest, ToolCallResponse};
254pub use result::{TokenCounts, ToolMetadata, ToolMetadataBuilder, ToolResult as SplitToolResult};
255pub use result_cache::{ToolCacheKey, ToolResultCache};
256pub use result_metadata::{EnhancedToolResult, ResultCompleteness, ResultMetadata, ResultScorer, ScorerRegistry};
257pub use ripgrep_installer::RipgrepStatus;
258pub use safety_gateway::{
259    SafetyCheckResult, SafetyContext, SafetyDecision, SafetyError, SafetyGateway, SafetyGatewayConfig, SafetyStats,
260    SafetyTrustLevel,
261};
262pub use search_metrics::{SearchMetric, SearchMetrics, SearchMetricsStats};
263pub use shell_snapshot::{
264    FileFingerprint, ShellKind, ShellSnapshot, ShellSnapshotManager, SnapshotStats, apply_snapshot_env,
265    global_snapshot_manager,
266};
267pub use tool_effectiveness::{
268    AdaptiveToolSelector, ToolEffectiveness, ToolEffectivenessTracker, ToolFailureMode, ToolSelectionContext,
269    ToolSelector,
270};
271pub use traits::{Tool, ToolExecutor};
272pub use types::*;
273pub use unified_error::{
274    DebugContext as UnifiedToolDebugContext, ErrorSeverity as UnifiedErrorSeverity, UnifiedErrorKind, UnifiedToolError,
275};
276pub use web_fetch::WebFetchTool;
277pub use web_search::WebSearchTool;
278
279// Dynamic context discovery
280pub use output_spooler::{SpoolResult, SpoolState, SpooledOutputReference, SpoolerConfig, ToolOutputSpooler};
281
282// Production-grade improvements re-exports
283pub use async_middleware::{
284    AsyncCachingMiddleware, AsyncLoggingMiddleware, AsyncMiddleware, AsyncMiddlewareChain, AsyncRetryMiddleware,
285    MiddlewareToolResult, ToolRequest as MiddlewareToolRequest,
286};
287pub use cached_executor::{CachedToolExecutor, ExecutorStats};
288pub use handlers::{
289    // Apply patch handler
290    // Orchestrator and sandboxing
291    Approvable,
292    // Core handler traits and types
293    ApprovalPolicy,
294    AskForApproval,
295    // Turn diff tracker with Agent Trace support
296    ChangeAttribution,
297    CommandSpec,
298    ConfiguredToolSpec,
299    ContentItem,
300    DiffTracker,
301    ExecApprovalRequirement,
302    // Event emission
303    ExecEnv,
304    ExecPolicyAmendment,
305    ExecToolCallOutput,
306    FileChange,
307    FileChangeKind,
308    FreeformTool,
309    FreeformToolFormat,
310    JsonSchema as ToolJsonSchema,
311    McpToolResult,
312    RejectConfig,
313    ResponsesApiTool,
314    SandboxAttempt,
315    SandboxConfig,
316    SandboxManager,
317    SandboxPermissions,
318    SandboxPolicy,
319    SandboxTransformError,
320    Sandboxable,
321    SandboxablePreference,
322    SharedDiffTracker,
323    SharedTurnDiffTracker,
324    ShellEnvironmentPolicy,
325    ShellToolCallParams,
326    ToolCallError,
327    ToolCtx,
328    ToolError,
329    ToolHandler,
330    ToolInvocation,
331    ToolKind,
332    ToolOutput,
333    ToolPayload,
334    ToolRuntime,
335    ToolSession,
336    ToolSpec,
337    TurnContext,
338    TurnDiffTracker,
339    default_exec_approval_requirement,
340    new_shared_tracker,
341};
342pub use improvement_algorithms::{
343    MLScoreComponents, PatternState, TimeDecayedScore, ToolCallRecord, detect_pattern, jaro_winkler_similarity,
344};
345pub use improvements_config::{
346    CacheConfig, ContextConfig, FallbackConfig, ImprovementsConfig, PatternConfig, SimilarityConfig, TimeDecayConfig,
347};
348pub use improvements_errors::{
349    ErrorKind, EventType, ImprovementError, ImprovementEvent, ImprovementResult, ImprovementSeverity,
350    ImprovementSeverity as ErrorSeverity, ObservabilityContext, ObservabilitySink,
351};
352pub use improvements_registry_ext::{ToolMetrics, ToolRegistryImprovement};
353pub use lru_cache::{CacheObserver, CacheStats, LruCache};
354pub use pattern_detection::{DetectedPattern, PatternDetector};
355pub use tool_middleware::{Middleware, MiddlewareChain};
356pub use vtcode_utility_tool_specs::parse_tool_input_schema;
357pub use workflow_optimizer::{Optimization, OptimizationType, WorkflowOptimizer};
358
359pub mod source_inspection;
vtcode_core/tools/mod.rs

vtcode_core/tools/
mod.rs
