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_session;
149pub mod exec_session_id;
150pub mod execution_context;
151pub mod execution_tracker;
152pub mod file_ops;
153pub mod file_search_bridge;
154pub mod file_search_rpc;
155pub mod file_tracker;
156pub mod generation_helpers;
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 time_compat;
208pub mod tool_middleware;
209pub mod workflow_optimizer;
210pub use resilience::circuit_breaker;
211pub mod health;
212pub mod improvement_algorithms;
213pub mod improvements_config;
214pub mod improvements_errors;
215pub mod improvements_registry_ext;
216mod install_support;
217pub mod optimized_registry;
218pub mod output_spooler;
219pub mod pattern_engine;
220pub mod request_response;
221pub mod unified_error;
222pub mod untrusted_data;
223
224// Re-export main types and traits for backward compatibility
225pub use ast_grep_installer::{AstGrepInstallOutcome, AstGrepStatus};
226pub use autonomous_executor::{AutonomousExecutor, AutonomousPolicy};
227pub use cache::FileCache;
228pub use command_cache::PermissionCache;
229pub use command_resolver::CommandResolver;
230pub use editing::{Patch, PatchError, PatchHunk, PatchLine, PatchOperation};
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    ApplyPatchHandler,
291    ApplyPatchRequest,
292    ApplyPatchRuntime,
293    ApplyPatchToolArgs,
294    // Orchestrator and sandboxing
295    Approvable,
296    // Core handler traits and types
297    ApprovalPolicy,
298    AskForApproval,
299    // Turn diff tracker with Agent Trace support
300    ChangeAttribution,
301    CommandSpec,
302    ConfiguredToolSpec,
303    ContentItem,
304    DiffTracker,
305    ExecApprovalRequirement,
306    // Event emission
307    ExecCommandInput,
308    ExecCommandSource,
309    ExecEnv,
310    ExecPolicyAmendment,
311    ExecToolCallOutput,
312    FileChange,
313    FileChangeKind,
314    FreeformTool,
315    FreeformToolFormat,
316    JsonSchema as ToolJsonSchema,
317    McpToolResult,
318    ParsedCommand,
319    RejectConfig,
320    ResponsesApiTool,
321    SandboxAttempt,
322    SandboxConfig,
323    SandboxManager,
324    SandboxPermissions,
325    SandboxPolicy,
326    SandboxTransformError,
327    Sandboxable,
328    SandboxablePreference,
329    SharedDiffTracker,
330    SharedTurnDiffTracker,
331    ShellEnvironmentPolicy,
332    ShellToolCallParams,
333    ToolCallError,
334    ToolCtx,
335    ToolEmitter,
336    ToolError,
337    ToolEventCtx,
338    ToolEventFailureKind,
339    ToolEventStage,
340    ToolHandler,
341    ToolInvocation,
342    ToolKind,
343    ToolOrchestrator,
344    ToolOutput,
345    ToolPayload,
346    ToolRuntime,
347    ToolSession,
348    ToolSpec,
349    TurnContext,
350    TurnDiffTracker,
351    create_apply_patch_freeform_tool,
352    create_apply_patch_json_tool,
353    default_exec_approval_requirement,
354    intercept_apply_patch,
355    new_shared_tracker,
356};
357pub use improvement_algorithms::{
358    MLScoreComponents, PatternState, TimeDecayedScore, ToolCallRecord, detect_pattern, jaro_winkler_similarity,
359};
360pub use improvements_config::{
361    CacheConfig, ContextConfig, FallbackConfig, ImprovementsConfig, PatternConfig, SimilarityConfig, TimeDecayConfig,
362};
363pub use improvements_errors::{
364    ErrorKind, EventType, ImprovementError, ImprovementEvent, ImprovementResult, ImprovementSeverity,
365    ImprovementSeverity as ErrorSeverity, ObservabilityContext, ObservabilitySink,
366};
367pub use improvements_registry_ext::{ToolMetrics, ToolRegistryImprovement};
368pub use lru_cache::{CacheObserver, CacheStats, LruCache};
369pub use pattern_detection::{DetectedPattern, PatternDetector};
370pub use tool_middleware::{Middleware, MiddlewareChain};
371pub use vtcode_utility_tool_specs::parse_tool_input_schema;
372pub use workflow_optimizer::{Optimization, OptimizationType, WorkflowOptimizer};
vtcode_core/tools/mod.rs

vtcode_core/tools/
mod.rs
