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;
157pub mod generation_helpers;
158mod grep_backend;
159pub mod grep_cache;
160pub mod grep_file;
161pub mod handlers;
162pub mod invocation;
163pub mod mcp;
164pub mod names;
165pub mod native_memory;
166pub(crate) mod output_limits;
167pub mod path_env;
168pub mod plugins;
169pub mod pty;
170pub mod read_limits;
171pub mod resilience;
172
173pub use resilience::rate_limiter;
174pub mod defuddle;
175pub mod outline_search;
176pub mod registry;
177pub mod result;
178pub mod result_cache;
179pub mod result_metadata;
180pub mod ripgrep_binary;
181pub mod ripgrep_installer;
182pub mod safety_gateway;
183pub mod search_metrics;
184pub(crate) mod search_runtime;
185pub mod shell;
186pub mod shell_snapshot;
187pub mod skills;
188pub mod summarizers;
189#[cfg(feature = "tui")]
190pub mod terminal_app;
191pub mod tool_effectiveness;
192pub mod tool_intent;
193pub mod traits;
194pub(crate) mod tree_sitter_runtime;
195pub mod types;
196pub mod validation;
197pub mod validation_cache;
198pub mod web_fetch;
199pub mod web_search;
200
201// Production-grade improvements modules
202pub use resilience::adaptive_rate_limiter;
203pub mod async_middleware;
204pub mod cached_executor;
205pub mod lru_cache;
206pub mod pattern_detection;
207pub mod registry_adapters;
208pub mod time_compat;
209pub mod tool_middleware;
210pub mod workflow_optimizer;
211pub use resilience::circuit_breaker;
212pub mod health;
213pub mod improvement_algorithms;
214pub mod improvements_config;
215pub mod improvements_errors;
216pub mod improvements_registry_ext;
217mod install_support;
218pub mod optimized_registry;
219pub mod output_spooler;
220pub mod pattern_engine;
221pub mod request_response;
222pub mod unified_error;
223pub mod untrusted_data;
224
225// Re-export main types and traits for backward compatibility
226pub use ast_grep_installer::{AstGrepInstallOutcome, AstGrepStatus};
227pub use autonomous_executor::{AutonomousExecutor, AutonomousPolicy};
228pub use cache::FileCache;
229pub use command_cache::PermissionCache;
230pub use command_resolver::CommandResolver;
231pub use editing::{Patch, PatchError, PatchHunk, PatchLine, PatchOperation};
232pub use exec_read_target::{ExecReadTarget, parse_exec_read_target};
233pub use exec_session_id::ExecSessionId;
234pub use execution_context::{ToolExecutionContext, ToolExecutionRecord, ToolPattern};
235pub use execution_tracker::{ExecutionRecord, ExecutionStats, ExecutionStatus, ExecutionTracker};
236pub use file_search_rpc::{
237    FileMatchRpc, FileSearchRpcHandler, ListFilesRequest, ListFilesResponse, RpcError, RpcRequest, RpcResponse,
238    SearchFilesRequest, SearchFilesResponse,
239};
240pub use grep_file::GrepSearchManager;
241pub use invocation::{InvocationBuilder, ToolInvocation as UnifiedToolInvocation, ToolInvocationId};
242pub use search_runtime::{
243    SearchToolBundleStatus, SearchToolReadiness, dominant_workspace_language, search_tool_bundle_status,
244};
245
246pub use defuddle::DefuddleTool;
247pub use optimized_registry::{CachedToolMetadata as OptimizedToolMetadata, OptimizedToolRegistry};
248pub use plugins::{PluginHandle, PluginId, PluginInstaller, PluginManifest, PluginRuntime};
249pub use pty::{PtyCommandRequest, PtyCommandResult, PtyManager};
250pub use registry::{
251    ApprovalPattern, ApprovalRecorder, CgpRuntimeMode, JustificationExtractor, JustificationManager, RiskLevel,
252    ToolJustification, ToolRegistration, ToolRegistry, ToolRiskContext, ToolRiskScorer, ToolSource, WorkspaceTrust,
253    native_cgp_tool_factory, wrap_registered_native_tool,
254};
255pub use request_response::{ToolCallRequest, ToolCallResponse};
256pub use result::{TokenCounts, ToolMetadata, ToolMetadataBuilder, ToolResult as SplitToolResult};
257pub use result_cache::{ToolCacheKey, ToolResultCache};
258pub use result_metadata::{EnhancedToolResult, ResultCompleteness, ResultMetadata, ResultScorer, ScorerRegistry};
259pub use ripgrep_installer::RipgrepStatus;
260pub use safety_gateway::{
261    SafetyCheckResult, SafetyContext, SafetyDecision, SafetyError, SafetyGateway, SafetyGatewayConfig, SafetyStats,
262    SafetyTrustLevel,
263};
264pub use search_metrics::{SearchMetric, SearchMetrics, SearchMetricsStats};
265pub use shell_snapshot::{
266    FileFingerprint, ShellKind, ShellSnapshot, ShellSnapshotManager, SnapshotStats, apply_snapshot_env,
267    global_snapshot_manager,
268};
269pub use tool_effectiveness::{
270    AdaptiveToolSelector, ToolEffectiveness, ToolEffectivenessTracker, ToolFailureMode, ToolSelectionContext,
271    ToolSelector,
272};
273pub use traits::{Tool, ToolExecutor};
274pub use types::*;
275pub use unified_error::{
276    DebugContext as UnifiedToolDebugContext, ErrorSeverity as UnifiedErrorSeverity, UnifiedErrorKind, UnifiedToolError,
277};
278pub use web_fetch::WebFetchTool;
279pub use web_search::WebSearchTool;
280
281// Dynamic context discovery
282pub use output_spooler::{SpoolResult, SpoolState, SpooledOutputReference, SpoolerConfig, ToolOutputSpooler};
283
284// Production-grade improvements re-exports
285pub use async_middleware::{
286    AsyncCachingMiddleware, AsyncLoggingMiddleware, AsyncMiddleware, AsyncMiddlewareChain, AsyncRetryMiddleware,
287    MiddlewareToolResult, ToolRequest as MiddlewareToolRequest,
288};
289pub use cached_executor::{CachedToolExecutor, ExecutorStats};
290pub use handlers::{
291    // Apply patch handler
292    ApplyPatchHandler,
293    ApplyPatchRequest,
294    ApplyPatchRuntime,
295    ApplyPatchToolArgs,
296    // Orchestrator and sandboxing
297    Approvable,
298    // Core handler traits and types
299    ApprovalPolicy,
300    AskForApproval,
301    // Turn diff tracker with Agent Trace support
302    ChangeAttribution,
303    CommandSpec,
304    ConfiguredToolSpec,
305    ContentItem,
306    DiffTracker,
307    ExecApprovalRequirement,
308    // Event emission
309    ExecCommandInput,
310    ExecCommandSource,
311    ExecEnv,
312    ExecPolicyAmendment,
313    ExecToolCallOutput,
314    FileChange,
315    FileChangeKind,
316    FreeformTool,
317    FreeformToolFormat,
318    JsonSchema as ToolJsonSchema,
319    McpToolResult,
320    ParsedCommand,
321    RejectConfig,
322    ResponsesApiTool,
323    SandboxAttempt,
324    SandboxConfig,
325    SandboxManager,
326    SandboxPermissions,
327    SandboxPolicy,
328    SandboxTransformError,
329    Sandboxable,
330    SandboxablePreference,
331    SharedDiffTracker,
332    SharedTurnDiffTracker,
333    ShellEnvironmentPolicy,
334    ShellToolCallParams,
335    ToolCallError,
336    ToolCtx,
337    ToolEmitter,
338    ToolError,
339    ToolEventCtx,
340    ToolEventFailureKind,
341    ToolEventStage,
342    ToolHandler,
343    ToolInvocation,
344    ToolKind,
345    ToolOrchestrator,
346    ToolOutput,
347    ToolPayload,
348    ToolRuntime,
349    ToolSession,
350    ToolSpec,
351    TurnContext,
352    TurnDiffTracker,
353    create_apply_patch_freeform_tool,
354    create_apply_patch_json_tool,
355    default_exec_approval_requirement,
356    intercept_apply_patch,
357    new_shared_tracker,
358};
359pub use improvement_algorithms::{
360    MLScoreComponents, PatternState, TimeDecayedScore, ToolCallRecord, detect_pattern, jaro_winkler_similarity,
361};
362pub use improvements_config::{
363    CacheConfig, ContextConfig, FallbackConfig, ImprovementsConfig, PatternConfig, SimilarityConfig, TimeDecayConfig,
364};
365pub use improvements_errors::{
366    ErrorKind, EventType, ImprovementError, ImprovementEvent, ImprovementResult, ImprovementSeverity,
367    ImprovementSeverity as ErrorSeverity, ObservabilityContext, ObservabilitySink,
368};
369pub use improvements_registry_ext::{ToolMetrics, ToolRegistryImprovement};
370pub use lru_cache::{CacheObserver, CacheStats, LruCache};
371pub use pattern_detection::{DetectedPattern, PatternDetector};
372pub use tool_middleware::{Middleware, MiddlewareChain};
373pub use vtcode_utility_tool_specs::parse_tool_input_schema;
374pub use workflow_optimizer::{Optimization, OptimizationType, WorkflowOptimizer};
375
376pub mod source_inspection;
vtcode_core/tools/mod.rs

vtcode_core/tools/
mod.rs
