@mxf-dev/core 1.0.0

package/dist/protocols/mcp/tools/InfrastructureTools.d.ts

@@ -0,0 +1,826 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * InfrastructureTools.ts
+ *
+ * MCP tools for core infrastructure operations including filesystem, database,
+ * memory/storage, and shell operations. These tools provide essential capabilities
+ * for agents to interact with system resources through the MCP protocol.
+ */
+import { AgentId, ChannelId } from '../../../types/ChannelContext.js';
+import { ExecutionLanguage } from '../../../services/CodeExecutionSandboxService.js';
+/**
+ * Helper function to execute shell commands - can be used by other tools
+ */
+export declare function executeShellCommand(command: string, args?: string[], options?: {
+    workingDirectory?: string;
+    environment?: Record<string, string>;
+    timeout?: number;
+    captureOutput?: boolean;
+}): Promise<{
+    command: string;
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+    executionTime: number;
+    executedAt: number;
+}>;
+/**
+ * NOTE: Filesystem tools (read, write, list) are provided by the external MCP filesystem server
+ * (@modelcontextprotocol/server-filesystem) configured in ExternalServerConfigs.ts
+ *
+ * The external server provides:
+ * - read_file: Read file contents with encoding support
+ * - write_file: Write/append to files with safety checks
+ * - list_directory: List directory contents with filtering
+ * - get_file_info: Get file metadata
+ * - search_files: Search for files by name/pattern
+ *
+ * These tools were removed from internal implementation to avoid duplication
+ * and ensure consistent filesystem access through the MCP protocol.
+ */
+/**
+ * MCP Tool: memory_store
+ * Store key-value data with expiration and metadata
+ */
+export declare const memoryStoreTool: {
+    name: "memory_store";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            key: {
+                type: string;
+                description: string;
+            };
+            value: {
+                description: string;
+            };
+            ttl: {
+                type: string;
+                description: string;
+                minimum: number;
+            };
+            namespace: {
+                type: string;
+                description: string;
+                default: string;
+            };
+            metadata: {
+                type: string;
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(input: {
+        key: string;
+        value: any;
+        ttl?: number;
+        namespace?: string;
+        metadata?: Record<string, any>;
+        tags?: string[];
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<{
+        key: string;
+        namespace: string;
+        stored: boolean;
+        expiresAt?: number;
+        storedAt: number;
+    }>;
+};
+/**
+ * MCP Tool: memory_retrieve
+ * Retrieve stored data with fallback options
+ */
+export declare const memoryRetrieveTool: {
+    name: "memory_retrieve";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            key: {
+                type: string;
+                description: string;
+            };
+            namespace: {
+                type: string;
+                description: string;
+                default: string;
+            };
+            includeMetadata: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            defaultValue: {
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(input: {
+        key: string;
+        namespace?: string;
+        includeMetadata?: boolean;
+        defaultValue?: any;
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<{
+        key: string;
+        namespace: string;
+        value: any;
+        found: boolean;
+        expiresAt?: number;
+        metadata?: Record<string, any>;
+        retrievedAt: number;
+    }>;
+};
+/**
+ * MCP Tool: shell_execute
+ * Execute shell commands with output capture and safety controls
+ */
+export declare const shellExecTool: {
+    name: "shell_execute";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            command: {
+                type: string;
+                description: string;
+            };
+            args: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            workingDirectory: {
+                type: string;
+                description: string;
+            };
+            environment: {
+                type: string;
+                description: string;
+            };
+            timeout: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            captureOutput: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            allowedCommands: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            runInBackground: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            backgroundTimeout: {
+                type: string;
+                description: string;
+                minimum: number;
+            };
+        };
+        required: string[];
+    };
+    /**
+     * Delegates to the enhanced ShellExecuteHandler for foreground execution, or
+     * to BackgroundTaskManager for background execution.
+     *
+     * Foreground mode provides:
+     * - Command semantics (exit code interpretation)
+     * - Destructive command warnings
+     * - Command classification (read-only, silent, etc.)
+     * - Large output handling (persist + preview)
+     * - Event emission throughout lifecycle
+     * - spawn() instead of exec() for streaming
+     *
+     * Background mode provides:
+     * - Immediate taskId return
+     * - Ring-buffer output accumulation
+     * - Throttled progress events via EventBus
+     * - Query via shell_task_status tool
+     */
+    handler(input: {
+        command: string;
+        args?: string[];
+        workingDirectory?: string;
+        environment?: Record<string, string>;
+        timeout?: number;
+        captureOutput?: boolean;
+        allowedCommands?: string[];
+        description?: string;
+        runInBackground?: boolean;
+        backgroundTimeout?: number;
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<import("./shell/ShellExecuteHandler.js").ShellExecuteResult | {
+        taskId: string;
+        command: string;
+        description: string | undefined;
+        status: string;
+        message: string;
+    }>;
+};
+/**
+ * MCP Tool: shell_task_status
+ * Query the status and output of background shell tasks started via shell_execute
+ * with runInBackground: true.
+ */
+export declare const shellTaskStatusTool: {
+    name: "shell_task_status";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            taskId: {
+                type: string;
+                description: string;
+            };
+            action: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
+            agentId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler(input: {
+        taskId?: string;
+        action?: "status" | "output" | "cancel" | "list";
+        agentId?: AgentId;
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<{
+        action: string;
+        count: number;
+        tasks: import("../../../services/BackgroundTaskManager.js").BackgroundTaskInfo[];
+        taskId?: undefined;
+        cancelled?: undefined;
+        message?: undefined;
+        output?: undefined;
+        outputSize?: undefined;
+    } | {
+        action: string;
+        taskId: string;
+        cancelled: boolean;
+        message: string;
+        count?: undefined;
+        tasks?: undefined;
+        output?: undefined;
+        outputSize?: undefined;
+    } | {
+        action: string;
+        taskId: string;
+        output: string;
+        outputSize: number;
+        count?: undefined;
+        tasks?: undefined;
+        cancelled?: undefined;
+        message?: undefined;
+    } | {
+        taskId: string;
+        command: string;
+        description?: string;
+        status: import("../../../services/BackgroundTaskManager.js").BackgroundTaskStatus;
+        exitCode?: number;
+        outputPreview: string;
+        outputSize: number;
+        startTime: number;
+        endTime?: number;
+        elapsedSeconds: number;
+        agentId: AgentId;
+        channelId: ChannelId;
+        action: string;
+        count?: undefined;
+        tasks?: undefined;
+        cancelled?: undefined;
+        message?: undefined;
+        output?: undefined;
+    }>;
+};
+/**
+ * MCP Tool: code_execute
+ * Execute code in a sandboxed environment with security and resource limits
+ */
+export declare const codeExecuteTool: {
+    name: "code_execute";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            language: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            code: {
+                type: string;
+                description: string;
+                minLength: number;
+            };
+            timeout: {
+                type: string;
+                description: string;
+                default: number;
+                minimum: number;
+                maximum: number;
+            };
+            context: {
+                type: string;
+                description: string;
+                additionalProperties: boolean;
+            };
+            captureConsole: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    examples: ({
+        input: {
+            language: string;
+            code: string;
+            context?: undefined;
+        };
+        description: string;
+    } | {
+        input: {
+            language: string;
+            code: string;
+            context: {
+                data: {
+                    score: number;
+                    name: string;
+                }[];
+            };
+        };
+        description: string;
+    })[];
+    handler(input: {
+        language?: ExecutionLanguage;
+        code: string;
+        timeout?: number;
+        context?: Record<string, any>;
+        captureConsole?: boolean;
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<{
+        content: {
+            type: string;
+            data: {
+                success: boolean;
+                output: any;
+                logs?: string[];
+                executionTime: number;
+                codeHash: string;
+                error?: string;
+                resourceUsage: {
+                    memory: number;
+                    timeout: boolean;
+                };
+                outputTruncated?: boolean;
+                persistedOutputId?: string;
+            };
+        };
+    }>;
+};
+/**
+ * Export all infrastructure MCP tools
+ *
+ * NOTE: Filesystem tools are provided by the external @modelcontextprotocol/server-filesystem
+ * MCP server configured in ExternalServerConfigs.ts (autoStart: true)
+ */
+export declare const infrastructureTools: ({
+    name: "memory_store";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            key: {
+                type: string;
+                description: string;
+            };
+            value: {
+                description: string;
+            };
+            ttl: {
+                type: string;
+                description: string;
+                minimum: number;
+            };
+            namespace: {
+                type: string;
+                description: string;
+                default: string;
+            };
+            metadata: {
+                type: string;
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(input: {
+        key: string;
+        value: any;
+        ttl?: number;
+        namespace?: string;
+        metadata?: Record<string, any>;
+        tags?: string[];
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<{
+        key: string;
+        namespace: string;
+        stored: boolean;
+        expiresAt?: number;
+        storedAt: number;
+    }>;
+} | {
+    name: "memory_retrieve";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            key: {
+                type: string;
+                description: string;
+            };
+            namespace: {
+                type: string;
+                description: string;
+                default: string;
+            };
+            includeMetadata: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            defaultValue: {
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(input: {
+        key: string;
+        namespace?: string;
+        includeMetadata?: boolean;
+        defaultValue?: any;
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<{
+        key: string;
+        namespace: string;
+        value: any;
+        found: boolean;
+        expiresAt?: number;
+        metadata?: Record<string, any>;
+        retrievedAt: number;
+    }>;
+} | {
+    name: "shell_execute";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            command: {
+                type: string;
+                description: string;
+            };
+            args: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            workingDirectory: {
+                type: string;
+                description: string;
+            };
+            environment: {
+                type: string;
+                description: string;
+            };
+            timeout: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            captureOutput: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            allowedCommands: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            runInBackground: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            backgroundTimeout: {
+                type: string;
+                description: string;
+                minimum: number;
+            };
+        };
+        required: string[];
+    };
+    /**
+     * Delegates to the enhanced ShellExecuteHandler for foreground execution, or
+     * to BackgroundTaskManager for background execution.
+     *
+     * Foreground mode provides:
+     * - Command semantics (exit code interpretation)
+     * - Destructive command warnings
+     * - Command classification (read-only, silent, etc.)
+     * - Large output handling (persist + preview)
+     * - Event emission throughout lifecycle
+     * - spawn() instead of exec() for streaming
+     *
+     * Background mode provides:
+     * - Immediate taskId return
+     * - Ring-buffer output accumulation
+     * - Throttled progress events via EventBus
+     * - Query via shell_task_status tool
+     */
+    handler(input: {
+        command: string;
+        args?: string[];
+        workingDirectory?: string;
+        environment?: Record<string, string>;
+        timeout?: number;
+        captureOutput?: boolean;
+        allowedCommands?: string[];
+        description?: string;
+        runInBackground?: boolean;
+        backgroundTimeout?: number;
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<import("./shell/ShellExecuteHandler.js").ShellExecuteResult | {
+        taskId: string;
+        command: string;
+        description: string | undefined;
+        status: string;
+        message: string;
+    }>;
+} | {
+    name: "shell_task_status";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            taskId: {
+                type: string;
+                description: string;
+            };
+            action: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
+            agentId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler(input: {
+        taskId?: string;
+        action?: "status" | "output" | "cancel" | "list";
+        agentId?: AgentId;
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<{
+        action: string;
+        count: number;
+        tasks: import("../../../services/BackgroundTaskManager.js").BackgroundTaskInfo[];
+        taskId?: undefined;
+        cancelled?: undefined;
+        message?: undefined;
+        output?: undefined;
+        outputSize?: undefined;
+    } | {
+        action: string;
+        taskId: string;
+        cancelled: boolean;
+        message: string;
+        count?: undefined;
+        tasks?: undefined;
+        output?: undefined;
+        outputSize?: undefined;
+    } | {
+        action: string;
+        taskId: string;
+        output: string;
+        outputSize: number;
+        count?: undefined;
+        tasks?: undefined;
+        cancelled?: undefined;
+        message?: undefined;
+    } | {
+        taskId: string;
+        command: string;
+        description?: string;
+        status: import("../../../services/BackgroundTaskManager.js").BackgroundTaskStatus;
+        exitCode?: number;
+        outputPreview: string;
+        outputSize: number;
+        startTime: number;
+        endTime?: number;
+        elapsedSeconds: number;
+        agentId: AgentId;
+        channelId: ChannelId;
+        action: string;
+        count?: undefined;
+        tasks?: undefined;
+        cancelled?: undefined;
+        message?: undefined;
+        output?: undefined;
+    }>;
+} | {
+    name: "code_execute";
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            language: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            code: {
+                type: string;
+                description: string;
+                minLength: number;
+            };
+            timeout: {
+                type: string;
+                description: string;
+                default: number;
+                minimum: number;
+                maximum: number;
+            };
+            context: {
+                type: string;
+                description: string;
+                additionalProperties: boolean;
+            };
+            captureConsole: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    examples: ({
+        input: {
+            language: string;
+            code: string;
+            context?: undefined;
+        };
+        description: string;
+    } | {
+        input: {
+            language: string;
+            code: string;
+            context: {
+                data: {
+                    score: number;
+                    name: string;
+                }[];
+            };
+        };
+        description: string;
+    })[];
+    handler(input: {
+        language?: ExecutionLanguage;
+        code: string;
+        timeout?: number;
+        context?: Record<string, any>;
+        captureConsole?: boolean;
+    }, context: {
+        agentId: AgentId;
+        channelId: ChannelId;
+        requestId: string;
+    }): Promise<{
+        content: {
+            type: string;
+            data: {
+                success: boolean;
+                output: any;
+                logs?: string[];
+                executionTime: number;
+                codeHash: string;
+                error?: string;
+                resourceUsage: {
+                    memory: number;
+                    timeout: boolean;
+                };
+                outputTruncated?: boolean;
+                persistedOutputId?: string;
+            };
+        };
+    }>;
+})[];
+//# sourceMappingURL=InfrastructureTools.d.ts.map