@windagency/valora 2.0.1

package/dist/executor/tool-execution.service.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Tool Execution Service
+ *
+ * Defines and executes file manipulation tools for LLM-driven code generation.
+ * These tools allow the LLM to actually create, modify, and delete files.
+ *
+ * Tools supported:
+ * - write: Create or overwrite files
+ * - read_file: Read file contents
+ * - search_replace: Make targeted edits to files
+ * - delete_file: Remove files
+ * - run_terminal_cmd: Execute shell commands
+ * - list_dir: List directory contents
+ * - glob_file_search: Find files by pattern
+ * - grep: Search file contents
+ * - codebase_search: Semantic code search
+ * - query_session: Query previous session data for context reuse
+ */
+import type { MCPClientManagerService } from '../mcp/mcp-client-manager.service.js';
+import type { LLMToolCall, LLMToolDefinition, LLMToolResult } from '../types/llm.types.js';
+import { type MCPToolHandler } from '../mcp/mcp-tool-handler.js';
+import { type AllowedTool } from '../types/command.types.js';
+import { type IdempotencyOptions } from '../types/idempotency.types.js';
+import { type TraceContext } from '../types/tracing.types.js';
+import { type SimulatedOperation } from './tools/dry-run-simulator.service.js';
+export declare class ToolExecutionService {
+    private readonly hookExecutionService;
+    private readonly idempotencyStore;
+    private readonly logger;
+    private mcpClientManager;
+    private mcpToolHandler;
+    private readonly searchToolsService;
+    private readonly sessionToolsService;
+    private readonly tracer;
+    private readonly workingDir;
+    /**
+     * Session ID for scoping idempotency keys
+     * When set, idempotency is scoped to the current session
+     */
+    private sessionId?;
+    /**
+     * Trace context for distributed tracing
+     * When set, tool execution spans are linked to the parent trace
+     */
+    private traceContext?;
+    /**
+     * Idempotency options for tool execution
+     */
+    private idempotencyOptions;
+    /**
+     * Tracks files that have been read in this session.
+     * Used to allow writes to protected files only if they were read first,
+     * preventing blind overwrites while still allowing intentional updates.
+     */
+    private readonly readFiles;
+    /**
+     * Dry-run mode flag
+     * When enabled, state-changing tools are simulated instead of executed
+     */
+    private dryRunMode;
+    /**
+     * Dry-run simulator instance (lazy-initialized)
+     */
+    private dryRunSimulator;
+    constructor(workingDir?: string);
+    /**
+     * Set the trace context for distributed tracing
+     * Tool execution spans will be children of this context
+     */
+    setTraceContext(context: TraceContext): void;
+    /**
+     * Get the current trace context
+     */
+    getTraceContext(): TraceContext | undefined;
+    /**
+     * Set the session ID for idempotency scoping
+     * This should be called at the start of a command execution
+     */
+    setSessionId(sessionId: string): void;
+    /**
+     * Configure idempotency options
+     */
+    setIdempotencyOptions(options: IdempotencyOptions): void;
+    /**
+     * Set the MCP tool handler for executing MCP tools
+     */
+    setMCPToolHandler(handler: MCPToolHandler): void;
+    /**
+     * Set the MCP client manager for generating MCP tool definitions
+     */
+    setMCPClientManager(clientManager: MCPClientManagerService): void;
+    /**
+     * Disable idempotency for the current execution
+     * Useful when you want to force re-execution of all tools
+     */
+    disableIdempotency(): void;
+    /**
+     * Enable idempotency for the current execution
+     */
+    enableIdempotency(): void;
+    /**
+     * Enable or disable dry-run mode
+     * In dry-run mode, state-changing tools are simulated instead of executed
+     */
+    setDryRunMode(enabled: boolean): void;
+    /**
+     * Check if dry-run mode is enabled
+     */
+    isDryRunMode(): boolean;
+    /**
+     * Get simulated operations from dry-run mode
+     */
+    getSimulatedOperations(): SimulatedOperation[];
+    /**
+     * Clear simulated operations
+     */
+    clearSimulatedOperations(): void;
+    /**
+     * Get tool definitions for the specified allowed tools
+     * Built-in tools are returned from static definitions.
+     * MCP tools are generated as gateway tools that route to external MCP servers.
+     */
+    getToolDefinitions(allowedTools: AllowedTool[]): LLMToolDefinition[];
+    /**
+     * Build the description for an MCP tool definition
+     */
+    private buildMCPToolDescription;
+    /**
+     * Get the tool_name parameter description based on available tools
+     */
+    private getToolNameDescription;
+    /**
+     * Generate a gateway tool definition for an MCP tool
+     * This creates a tool that accepts tool_name and arguments parameters,
+     * allowing the LLM to call any tool on the connected MCP server.
+     */
+    private generateMCPToolDefinition;
+    /**
+     * Reset state for a new command execution
+     * Clears pending writes and resets confirmation state
+     * Should be called at the start of each command execution
+     */
+    resetForNewCommand(): void;
+    /**
+     * Invalidate all idempotency records for the current session
+     * Call this when session state changes significantly
+     */
+    invalidateSessionIdempotency(): Promise<number>;
+    /**
+     * Invalidate idempotency records for a specific tool
+     * Useful when external changes affect tool results
+     */
+    invalidateToolIdempotency(toolName: string): number;
+    /**
+     * Get idempotency store statistics
+     */
+    getIdempotencyStats(): {
+        max_records: number;
+        record_count: number;
+        store_dir: string;
+    };
+    /**
+     * Execute a tool call and return the result
+     *
+     * For idempotent tools (write, search_replace, delete_file, run_terminal_cmd),
+     * checks the idempotency store first and returns cached result if available.
+     * This prevents duplicate operations when the same tool call is retried.
+     *
+     * In dry-run mode, state-changing tools are simulated instead of executed.
+     * Read-only tools execute normally even in dry-run mode.
+     */
+    executeTool(toolCall: LLMToolCall): Promise<LLMToolResult>;
+    /**
+     * Internal method to execute a tool with span tracking
+     */
+    private executeToolWithSpan;
+    /**
+     * Execute multiple tool calls in parallel
+     */
+    executeTools(toolCalls: LLMToolCall[]): Promise<LLMToolResult[]>;
+    /**
+     * Route tool execution to the appropriate handler
+     */
+    private executeToolByName;
+    /**
+     * Execute an MCP tool call
+     * Routes the call to MCPToolHandler for connection management and execution
+     */
+    private executeMcpTool;
+    /**
+     * Paths that require confirmation before writing
+     * These are typically documentation/knowledge-base paths where user review is important
+     */
+    private static readonly CONFIRM_WRITE_PATHS;
+    /**
+     * Pending writes that require confirmation
+     * These are queued during pipeline execution and processed at the end
+     */
+    private pendingWrites;
+    /**
+     * Write content to a file
+     */
+    private executeWrite;
+    /**
+     * Check if there are pending writes that need confirmation
+     */
+    hasPendingWrites(): boolean;
+    /**
+     * Get the count of pending writes
+     */
+    getPendingWritesCount(): number;
+    /**
+     * Process all pending writes with user confirmation
+     * Called at the end of pipeline execution
+     * Returns the number of files successfully written
+     */
+    flushPendingWrites(): Promise<{
+        skipped: number;
+        written: number;
+    }>;
+    /**
+     * Maximum file size to read (1MB) - prevents reading extremely large files
+     * that could cause context overflow
+     */
+    private static readonly MAX_READ_FILE_SIZE;
+    /**
+     * Paths that should not be read (contain sensitive or very large data)
+     */
+    private static readonly BLOCKED_READ_PATHS;
+    /**
+     * Protected files that should not be overwritten if they already exist.
+     * The write tool will reject attempts to overwrite these files and suggest
+     * using search_replace instead.
+     */
+    private static readonly PROTECTED_FILES;
+    /**
+     * Read file contents
+     */
+    private executeReadFile;
+    /**
+     * Enforce modern CLI tool usage: block structured files (JSON/YAML/TOML/XML).
+     */
+    private validateNotStructuredFile;
+    /**
+     * Enforce modern CLI tool usage: block files with >100 lines.
+     */
+    private validateFileLineCount;
+    /**
+     * Search and replace in a file
+     */
+    private executeSearchReplace;
+    /**
+     * Delete a file
+     */
+    private executeDeleteFile;
+    /**
+     * Execute a terminal command
+     */
+    private executeTerminalCmd;
+    /**
+     * List directory contents
+     */
+    private executeListDir;
+    /**
+     * Web search (placeholder - would integrate with actual web search)
+     */
+    private executeWebSearch;
+    /**
+     * Resolve a path relative to the working directory
+     */
+    private resolvePath;
+    /**
+     * Validate and resolve a path for write operations.
+     * Validates both the original path and the resolved full path against forbidden paths.
+     *
+     * @param path - The path to validate and resolve
+     * @param operation - The operation being attempted (e.g., "write to", "delete", "modify")
+     * @returns The resolved full path
+     * @throws Error if the path is in a forbidden location
+     */
+    private validateAndResolvePath;
+    /**
+     * Get a summary of tool arguments for logging
+     * Returns the primary argument value that identifies what the tool is operating on
+     */
+    private getToolArgSummary;
+}
+export declare function getToolExecutionService(workingDir?: string): ToolExecutionService;
+//# sourceMappingURL=tool-execution.service.d.ts.map

package/dist/executor/tool-execution.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-execution.service.d.ts","sourceRoot":"","sources":["../../src/executor/tool-execution.service.ts"],"names":[],"mappings":"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"}