vigthoria-cli 1.10.47 → 1.10.49

package/dist/utils/tools.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Vigthoria CLI Tools - Agentic Tool System
+ *
+ * This module provides Vigthoria Autonomous autonomous tool execution.
+ * Tools can be called by the AI to perform actions.
+ *
+ * Enhanced with:
+ * - Risk-based permission system
+ * - Automatic retry logic with exponential backoff
+ * - Undo functionality for file operations
+ * - Detailed error messages with suggestions
+ *
+ * @version 1.1.0
+ * @author Vigthoria Labs
+ */
+import { Logger } from './logger.js';
+export type StreamChunk = {
+    type: 'text' | 'delta' | 'error';
+    content: string;
+};
+export type UpdateInstallerResult = {
+    success: boolean;
+    platform: string;
+    error?: string;
+};
+export declare function installUpdateWindows(): Promise<UpdateInstallerResult>;
+export declare function robustifyStreamResponse(res: any): AsyncIterable<StreamChunk>;
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+export type SearchStatus = 'search_matches_found' | 'search_no_matches' | 'search_failed';
+export interface ToolResult {
+    success: boolean;
+    output?: string;
+    error?: string;
+    suggestion?: string;
+    canRetry?: boolean;
+    undoable?: boolean;
+    /** True when VIGTHORIA_DRY_RUN / VIGTHORIA_READ_ONLY caused a mutating tool to short-circuit. */
+    dryRun?: boolean;
+    /** Optional human-readable message attached to a dry-run / informational result. */
+    message?: string;
+    metadata?: {
+        searchStatus?: SearchStatus;
+        [key: string]: any;
+    };
+}
+export interface ToolCall {
+    tool: string;
+    args: Record<string, string>;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+    requiresPermission: boolean;
+    dangerous: boolean;
+    riskLevel: RiskLevel;
+    category: 'read' | 'write' | 'execute' | 'search';
+}
+interface UndoOperation {
+    id: string;
+    tool: string;
+    timestamp: number;
+    filePath?: string;
+    originalContent?: string | null;
+    description: string;
+}
+export declare enum ToolErrorType {
+    FILE_NOT_FOUND = "FILE_NOT_FOUND",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    TIMEOUT = "TIMEOUT",
+    INVALID_ARGS = "INVALID_ARGS",
+    EXECUTION_FAILED = "EXECUTION_FAILED",
+    USER_CANCELLED = "USER_CANCELLED"
+}
+export declare class AgenticTools {
+    private logger;
+    private cwd;
+    private permissionCallback;
+    private autoApprove;
+    private undoStack;
+    private maxUndoStack;
+    private retryConfig;
+    private formatExternalToolError;
+    private externalToolFailure;
+    private cleanupAfterToolError;
+    private runExternalCommand;
+    private isNonEmptyString;
+    private describeInvalidValue;
+    private assertStringRecord;
+    private requireNonEmptyString;
+    private requireArgsObject;
+    private sessionApprovedTools;
+    private static permissionsFile;
+    constructor(logger: Logger, cwd: string, permissionCallback: (action: string, options?: {
+        batchApproval?: boolean;
+    }) => Promise<boolean | 'batch' | 'persist'>, autoApprove?: boolean);
+    private getErrorMessage;
+    private assertToolCall;
+    /**
+     * Load persistent permissions for the current project
+     */
+    private loadPersistentPermissions;
+    /**
+     * Save a persistent permission for a tool in the current project
+     */
+    private savePersistentPermission;
+    /**
+     * Check if a tool has persistent permission for the current project
+     */
+    private hasPersistentPermission;
+    /**
+     * Clear session-approved tools (call this at the start of each new AI turn)
+     */
+    clearSessionApprovals(): void;
+    /**
+     * Get currently approved tools for this session
+     */
+    getSessionApprovedTools(): string[];
+    /**
+     * Get the undo stack for inspection
+     */
+    getUndoStack(): UndoOperation[];
+    /**
+     * Undo the last file operation
+     */
+    undo(): Promise<ToolResult>;
+    /**
+     * List of available tools - Vigthoria's advanced
+     * Enhanced with risk levels and categories
+     */
+    static getToolDefinitions(): ToolDefinition[];
+    /**
+     * Execute a tool call with enhanced error handling and retry logic
+     */
+    execute(call: ToolCall): Promise<ToolResult>;
+    private normalizeToolCall;
+    /**
+     * Execute tool with automatic retry for transient failures
+     */
+    private executeWithRetry;
+    /**
+     * Tool names that mutate the user's filesystem, shell state, or remote
+     * services.  Used by the dry-run / read-only gate below.
+     */
+    private static readonly MUTATING_TOOLS;
+    /**
+     * `VIGTHORIA_DRY_RUN=1` and `VIGTHORIA_READ_ONLY=1` are end-user safety
+     * switches: every mutating tool short-circuits with a clear "would have
+     * happened" result instead of touching the filesystem or network.
+     *
+     * The flags are checked at call-time (not at construction time) so they
+     * can be flipped per-prompt by users who want to inspect agent intent
+     * before committing.
+     */
+    private isDryRunActive;
+    /**
+     * Execute the actual tool operation
+     */
+    private executeTool;
+    /**
+     * Check if an error is retryable
+     */
+    private isRetryableError;
+    /**
+     * Safely stringify tool arguments without dumping very large payloads into logs.
+     */
+    private safeStringifyArgs;
+    /**
+     * Validate tool parameters
+     */
+    private validateParameters;
+    /**
+     * Create a standardized error result
+     */
+    private createErrorResult;
+    /**
+     * Enhanced permission request with risk visualization
+     */
+    private formatPermissionRequest;
+    private sleep;
+    /**
+     * Read file with enhanced error handling and suggestions
+     */
+    private readFile;
+    /**
+     * Write file with undo support
+     */
+    private writeFile;
+    /**
+     * Edit file with undo support and helpful error messages
+     */
+    private editFile;
+    private validateWrittenFile;
+    private validateJavaScriptSyntax;
+    private validateHtmlContent;
+    /**
+     * Execute bash command with enhanced error handling
+     * SECURITY: Commands are sandboxed to workspace directory
+     * WINDOWS: Detects Unix-specific commands and suggests alternatives
+     */
+    private bash;
+    private grep;
+    /**
+     * Windows grep: rg > Select-String > Node-native
+     */
+    private grepWindows;
+    /**
+     * Unix grep: rg > system grep (BSD/GNU)
+     */
+    private grepUnix;
+    /**
+     * Search using ripgrep (rg) — works on all platforms
+     */
+    private grepWithRg;
+    /**
+     * Search using PowerShell Select-String (Windows)
+     */
+    private grepWithSelectString;
+    /**
+     * Pure Node.js recursive file search — reliable on all platforms, no external deps
+     */
+    private grepNodeNative;
+    private listDir;
+    private glob;
+    private git;
+    /**
+     * Vigthoria Repository management tool
+     * Allows AI to push, pull, list, share, and manage projects in the Vigthoria Repository
+     */
+    private repo;
+    /**
+     * Fetch URL content - Cross-platform web fetching
+     * Uses Node.js native fetch (available in Node 18+)
+     */
+    private fetchUrl;
+    private browserTool;
+    /**
+     * Execute command via SSH on remote server
+     * Useful for running Unix commands from Windows
+     */
+    private sshExec;
+    /**
+     * Resolve and SANITIZE path - prevent path traversal outside workspace
+     * SECURITY: All paths MUST stay within the workspace (cwd)
+     */
+    private resolvePath;
+    /**
+     * Check if a path is within the allowed workspace
+     */
+    private isPathWithinWorkspace;
+    private task;
+    private multiEdit;
+    private codebaseSearch;
+    /**
+     * Parse tool calls from AI response (Vigthoria Agent format)
+     * Enhanced to handle various AI output formats including malformed JSON
+     */
+    static parseToolCalls(text: string): ToolCall[];
+    /**
+     * Get tools formatted for AI system prompt
+     */
+    static getToolsForPrompt(): string;
+}
+export {};