sub-agents-mcp 0.1.2

package/dist/tools/RunAgentTool.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * RunAgentTool implementation for executing Claude Code sub-agents via MCP
+ *
+ * Provides the run_agent tool that allows MCP clients to execute specific
+ * agents with parameters, integrating with AgentExecutor and AgentManager
+ * for complete agent execution workflow.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunAgentTool = void 0;
+const Logger_1 = require("../utils/Logger");
+/**
+ * RunAgentTool class implementing the run_agent MCP tool
+ *
+ * Provides execution of Claude Code sub-agents with parameter validation,
+ * error handling, and proper MCP response formatting.
+ */
+class RunAgentTool {
+    constructor(agentExecutor, agentManager) {
+        this.agentExecutor = agentExecutor;
+        this.agentManager = agentManager;
+        this.name = 'run_agent';
+        this.description = 'Execute a Claude Code sub-agent with specified parameters';
+        this.executionStats = new Map();
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                agent: {
+                    type: 'string',
+                    description: 'Name of the agent to execute',
+                },
+                prompt: {
+                    type: 'string',
+                    description: 'Prompt to send to the agent',
+                },
+                cwd: {
+                    type: 'string',
+                    description: 'Working directory for agent execution',
+                },
+                extra_args: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Additional command line arguments',
+                },
+            },
+            required: ['agent', 'prompt'],
+        };
+        // Use LOG_LEVEL environment variable if available
+        const logLevel = process.env['LOG_LEVEL'] || 'info';
+        this.logger = new Logger_1.Logger(logLevel);
+    }
+    /**
+     * Execute the run_agent tool with the provided parameters
+     *
+     * @param params - Tool execution parameters
+     * @returns Promise resolving to MCP tool response
+     * @throws {Error} When parameters are invalid or execution fails
+     */
+    async execute(params) {
+        const startTime = Date.now();
+        const requestId = this.generateRequestId();
+        this.logger.info('Run agent tool execution started', {
+            requestId,
+            timestamp: new Date().toISOString(),
+        });
+        try {
+            // Validate parameters with enhanced validation
+            const validatedParams = this.validateParams(params);
+            this.logger.debug('Parameters validated successfully', {
+                requestId,
+                agent: validatedParams.agent,
+                promptLength: validatedParams.prompt.length,
+                cwd: validatedParams.cwd,
+                extraArgsCount: validatedParams.extra_args?.length || 0,
+            });
+            // Check if agent exists
+            if (this.agentManager) {
+                const agent = await this.agentManager.getAgent(validatedParams.agent);
+                if (!agent) {
+                    this.logger.warn('Agent not found', {
+                        requestId,
+                        requestedAgent: validatedParams.agent,
+                    });
+                    return this.createErrorResponse(`Agent '${validatedParams.agent}' not found`, await this.getAvailableAgentsList());
+                }
+                this.logger.debug('Agent found and validated', {
+                    requestId,
+                    agentName: agent.name,
+                    agentDescription: agent.description,
+                });
+            }
+            // Execute agent if executor is available
+            if (this.agentExecutor) {
+                // Report progress: Starting agent execution
+                // Get agent definition content if available
+                let agentContext = validatedParams.agent;
+                if (this.agentManager) {
+                    const agent = await this.agentManager.getAgent(validatedParams.agent);
+                    if (agent?.content) {
+                        // Include full agent definition content as system context
+                        agentContext = agent.content;
+                    }
+                }
+                const executionParams = {
+                    agent: agentContext,
+                    prompt: validatedParams.prompt,
+                    ...(validatedParams.cwd !== undefined && { cwd: validatedParams.cwd }),
+                    ...(validatedParams.extra_args !== undefined && {
+                        extra_args: validatedParams.extra_args,
+                    }),
+                };
+                // Report progress: Executing agent
+                // Execute agent (this has its own timeout: MCP -> AI)
+                const result = await this.agentExecutor.executeAgent(executionParams);
+                // Report progress: Execution completed
+                // Update execution statistics
+                this.updateExecutionStats(validatedParams.agent, result.executionTime);
+                this.logger.info('Agent execution completed successfully', {
+                    requestId,
+                    agent: validatedParams.agent,
+                    exitCode: result.exitCode,
+                    executionTime: result.executionTime,
+                    totalTime: Date.now() - startTime,
+                });
+                // Mark MCP request as completed
+                return this.formatExecutionResponse(result, validatedParams.agent, requestId);
+            }
+            // Fallback response if executor is not available
+            this.logger.warn('Agent executor not available', { requestId });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Agent execution request received for '${validatedParams.agent}' with prompt: "${validatedParams.prompt}"\n\nNote: Agent executor not initialized.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const totalTime = Date.now() - startTime;
+            this.logger.error('Agent execution failed', error instanceof Error ? error : undefined, {
+                requestId,
+                totalTime,
+                errorType: error instanceof Error ? error.constructor.name : 'Unknown',
+            });
+            return this.createErrorResponse(`Agent execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`, null);
+        }
+    }
+    /**
+     * Validate and type-check the input parameters with comprehensive validation
+     *
+     * @private
+     * @param params - Raw parameters to validate
+     * @returns Validated parameters
+     * @throws {Error} When parameters are invalid
+     */
+    validateParams(params) {
+        if (!params || typeof params !== 'object') {
+            throw new Error('Invalid parameters: expected object');
+        }
+        const p = params;
+        // Validate required agent parameter with enhanced checks
+        if (!p['agent'] || typeof p['agent'] !== 'string') {
+            throw new Error('Agent parameter is required and must be a string');
+        }
+        const agentName = p['agent'].trim();
+        if (agentName === '') {
+            throw new Error('Invalid agent parameter: cannot be empty');
+        }
+        // Enhanced agent name validation
+        if (agentName.length > 100) {
+            throw new Error('Agent name too long (max 100 characters)');
+        }
+        if (!/^[a-zA-Z0-9_-]+$/.test(agentName)) {
+            throw new Error('Agent name contains invalid characters (only alphanumeric, underscore, and dash allowed)');
+        }
+        // Validate required prompt parameter with enhanced checks
+        if (!p['prompt'] || typeof p['prompt'] !== 'string') {
+            throw new Error('Prompt parameter is required and must be a string');
+        }
+        const prompt = p['prompt'].trim();
+        if (prompt === '') {
+            throw new Error('Invalid prompt parameter: cannot be empty');
+        }
+        if (prompt.length > 50000) {
+            throw new Error('Prompt too long (max 50,000 characters)');
+        }
+        // Validate optional cwd parameter with path validation
+        if (p['cwd'] !== undefined) {
+            if (typeof p['cwd'] !== 'string') {
+                throw new Error('CWD parameter must be a string if provided');
+            }
+            if (p['cwd'].length > 1000) {
+                throw new Error('Working directory path too long (max 1000 characters)');
+            }
+            // Basic path security check - prevent obvious malicious paths
+            if (p['cwd'].includes('..') || p['cwd'].includes('\0')) {
+                throw new Error('Invalid working directory path');
+            }
+        }
+        // Validate optional extra_args parameter with enhanced checks
+        if (p['extra_args'] !== undefined) {
+            if (!Array.isArray(p['extra_args'])) {
+                throw new Error('Extra args parameter must be an array if provided');
+            }
+            if (p['extra_args'].length > 20) {
+                throw new Error('Too many extra arguments (max 20 allowed)');
+            }
+            for (const [index, arg] of p['extra_args'].entries()) {
+                if (typeof arg !== 'string') {
+                    throw new Error(`Extra argument at index ${index} must be a string`);
+                }
+                if (arg.length > 1000) {
+                    throw new Error(`Extra argument at index ${index} too long (max 1000 characters)`);
+                }
+            }
+        }
+        return {
+            agent: agentName,
+            prompt: prompt,
+            cwd: p['cwd'],
+            extra_args: p['extra_args'],
+        };
+    }
+    /**
+     * Format agent execution response
+     *
+     * @private
+     * @param result - Agent execution result
+     * @param agentName - Name of the executed agent
+     * @param requestId - Request tracking ID
+     * @returns Formatted MCP response
+     */
+    formatExecutionResponse(result, agentName, requestId) {
+        // Determine execution status
+        const isSuccess = result.exitCode === 0 || // Normal completion
+            (result.exitCode === 143 && result.hasResult === true); // SIGTERM with result
+        const isPartialSuccess = result.exitCode === 124 && result.hasResult === true; // Timeout with partial result
+        const isError = !isSuccess && !isPartialSuccess;
+        // Content is just the agent's actual output
+        const contentText = result.stdout || result.stderr || 'No output';
+        // All metadata goes to structuredContent
+        const structuredContent = {
+            agent: agentName,
+            exitCode: result.exitCode,
+            executionTime: result.executionTime,
+            hasResult: result.hasResult || false,
+            status: isSuccess ? 'success' : isPartialSuccess ? 'partial' : 'error',
+        };
+        if (result.resultJson) {
+            structuredContent['result'] = result.resultJson;
+        }
+        if (result.stderr && result.stdout) {
+            // Only include stderr in structured content if we also have stdout
+            // Otherwise stderr is already in content
+            structuredContent['stderr'] = result.stderr;
+        }
+        if (requestId) {
+            structuredContent['requestId'] = requestId;
+        }
+        // Update statistics
+        const stats = this.executionStats.get(agentName);
+        if (stats) {
+            structuredContent['usageCount'] = stats.count;
+            structuredContent['averageTime'] = Math.round(stats.totalTime / stats.count);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: contentText,
+                },
+            ],
+            isError: isError,
+            structuredContent,
+        };
+    }
+    /**
+     * Create error response with optional available agents list
+     *
+     * @private
+     * @param errorMessage - Error message to display
+     * @param availableAgents - Optional list of available agents
+     * @returns Error response in MCP format
+     */
+    createErrorResponse(errorMessage, availableAgents) {
+        let responseText = `Error: ${errorMessage}`;
+        if (availableAgents && availableAgents.length > 0) {
+            responseText += `\n\nAvailable agents:\n${availableAgents.map((name) => `- ${name}`).join('\n')}`;
+        }
+        const errorStructuredContent = {
+            status: 'error',
+            error: errorMessage,
+        };
+        if (availableAgents) {
+            errorStructuredContent['availableAgents'] = availableAgents;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseText,
+                },
+            ],
+            isError: true,
+            structuredContent: errorStructuredContent,
+        };
+    }
+    /**
+     * Generate unique request ID for tracking
+     *
+     * @private
+     * @returns Unique request identifier
+     */
+    generateRequestId() {
+        return `run_agent_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Update execution statistics
+     *
+     * @private
+     * @param agentName - Name of the executed agent
+     * @param executionTime - Time taken for execution
+     */
+    updateExecutionStats(agentName, executionTime) {
+        const existing = this.executionStats.get(agentName);
+        if (existing) {
+            existing.count += 1;
+            existing.totalTime += executionTime;
+            existing.lastUsed = new Date();
+        }
+        else {
+            this.executionStats.set(agentName, {
+                count: 1,
+                totalTime: executionTime,
+                lastUsed: new Date(),
+            });
+        }
+    }
+    /**
+     * Get execution statistics for monitoring
+     *
+     * @returns Map of agent execution statistics
+     */
+    getExecutionStats() {
+        return new Map(this.executionStats);
+    }
+    /**
+     * Get list of available agent names
+     *
+     * @private
+     * @returns Promise resolving to array of agent names
+     */
+    async getAvailableAgentsList() {
+        if (!this.agentManager) {
+            return null;
+        }
+        try {
+            const agents = await this.agentManager.listAgents();
+            return agents.map((agent) => agent.name);
+        }
+        catch (error) {
+            this.logger.warn('Failed to get available agents list', {
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+            return null;
+        }
+    }
+}
+exports.RunAgentTool = RunAgentTool;
+//# sourceMappingURL=RunAgentTool.js.map

package/dist/tools/RunAgentTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunAgentTool.js","sourceRoot":"","sources":["../../src/tools/RunAgentTool.ts"],"names":[],"mappings":"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"}

package/dist/types/AgentDefinition.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Represents an AI agent definition loaded from a markdown file.
+ * This interface defines the structure for Claude Code sub-agent format files
+ * that contain agent instructions and metadata.
+ */
+export interface AgentDefinition {
+    /**
+     * The unique name identifier of the agent.
+     * Used as the key for agent selection and execution.
+     */
+    name: string;
+    /**
+     * Human-readable description of what the agent does.
+     * Provides context about the agent's purpose and capabilities.
+     */
+    description: string;
+    /**
+     * The full content/instructions for the agent.
+     * Contains the markdown content with agent directives and examples.
+     */
+    content: string;
+    /**
+     * Absolute file path where the agent definition is stored.
+     * Used for file watching and cache invalidation.
+     */
+    filePath: string;
+    /**
+     * Timestamp when the agent definition file was last modified.
+     * Used for cache invalidation and version tracking.
+     */
+    lastModified: Date;
+}
+//# sourceMappingURL=AgentDefinition.d.ts.map

package/dist/types/AgentDefinition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentDefinition.d.ts","sourceRoot":"","sources":["../../src/types/AgentDefinition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,YAAY,EAAE,IAAI,CAAA;CACnB"}

package/dist/types/AgentDefinition.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=AgentDefinition.js.map

package/dist/types/AgentDefinition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentDefinition.js","sourceRoot":"","sources":["../../src/types/AgentDefinition.ts"],"names":[],"mappings":""}

package/dist/types/ExecutionParams.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Parameters for executing an AI agent through the MCP server.
+ * These parameters are passed to the run_agent tool to initiate agent execution.
+ */
+export interface ExecutionParams {
+    /**
+     * Name of the agent to execute.
+     * Must match a loaded agent definition name.
+     */
+    agent: string;
+    /**
+     * User prompt/instructions to send to the agent.
+     * This is the input that will be processed by the agent.
+     */
+    prompt: string;
+    /**
+     * Optional working directory for the agent execution.
+     * If not provided, uses the current working directory.
+     */
+    cwd?: string;
+    /**
+     * Optional additional command line arguments.
+     * These are passed to the Claude Code CLI when executing the agent.
+     */
+    extra_args?: string[];
+}
+/**
+ * Result returned from agent execution.
+ * Contains the execution status and output/error information.
+ */
+export interface ExecutionResult {
+    /**
+     * Whether the agent execution was successful.
+     * True indicates successful completion, false indicates failure.
+     */
+    success: boolean;
+    /**
+     * Output content from the agent execution.
+     * Contains the agent's response or execution result.
+     */
+    output: string;
+    /**
+     * Error message if execution failed.
+     * Only present when success is false.
+     */
+    error?: string;
+}
+//# sourceMappingURL=ExecutionParams.d.ts.map

package/dist/types/ExecutionParams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionParams.d.ts","sourceRoot":"","sources":["../../src/types/ExecutionParams.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/dist/types/ExecutionParams.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ExecutionParams.js.map

package/dist/types/ExecutionParams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionParams.js","sourceRoot":"","sources":["../../src/types/ExecutionParams.ts"],"names":[],"mappings":""}

package/dist/types/ServerConfig.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Configuration interface for the MCP server.
+ * Defines the structure for server configuration parameters
+ * loaded from environment variables or defaults.
+ */
+export interface ServerConfigInterface {
+    /**
+     * Name identifier of the MCP server.
+     * Used in server registration and client communication.
+     */
+    serverName: string;
+    /**
+     * Version of the MCP server.
+     * Used in server identification and client compatibility checking.
+     */
+    serverVersion: string;
+    /**
+     * Directory path containing agent definition files.
+     * The server scans this directory for .md files containing agent definitions.
+     */
+    agentsDir: string;
+    /**
+     * Type of agent to use for execution.
+     * 'cursor' or 'claude'
+     */
+    agentType: 'cursor' | 'claude';
+    /**
+     * Log level for server operations.
+     * Controls verbosity of server logging output.
+     */
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    /**
+     * Maximum execution timeout in milliseconds for agent execution.
+     * Configurable via EXECUTION_TIMEOUT_MS environment variable.
+     * Default: 90000ms (90 seconds), Range: 1000ms - 240000ms (4 minutes)
+     */
+    executionTimeoutMs: number;
+}
+//# sourceMappingURL=ServerConfig.d.ts.map

package/dist/types/ServerConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerConfig.d.ts","sourceRoot":"","sources":["../../src/types/ServerConfig.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAE9B;;;OAGG;IACH,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;IAE7C;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,CAAA;CAC3B"}

package/dist/types/ServerConfig.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ServerConfig.js.map

package/dist/types/ServerConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerConfig.js","sourceRoot":"","sources":["../../src/types/ServerConfig.ts"],"names":[],"mappings":""}

package/dist/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Central export point for all type definitions used in the MCP server.
+ *
+ * This module provides type definitions for:
+ * - Agent definitions and metadata
+ * - Execution parameters and results
+ * - Server configuration
+ * - Type guards for runtime validation
+ *
+ * @example
+ * ```typescript
+ * import type { AgentDefinition, ExecutionParams } from 'src/types/types'
+ * import { isAgentDefinition, isExecutionParams } from 'src/types/types'
+ * ```
+ */
+export type { AgentDefinition } from '../types/AgentDefinition';
+export type { ExecutionParams, ExecutionResult } from '../types/ExecutionParams';
+export type { ServerConfigInterface } from '../types/ServerConfig';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AACjF,YAAY,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":""}

package/dist/utils/ErrorHandler.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Error context information for detailed error reporting.
+ */
+export interface ErrorContext {
+    /** Request ID for tracing */
+    requestId?: string;
+    /** Operation being performed when error occurred */
+    operation?: string;
+    /** Additional metadata relevant to the error */
+    metadata?: Record<string, unknown>;
+    /** Timestamp when error occurred */
+    timestamp?: Date;
+    /** Component or service where error originated */
+    component?: string;
+}
+/**
+ * Base application error class for structured error handling.
+ *
+ * Provides a standardized way to handle errors throughout the application
+ * with error codes, HTTP status codes, and contextual information for proper
+ * error response handling and debugging.
+ *
+ * @example
+ * ```typescript
+ * throw new AppError('Agent not found', 'AGENT_NOT_FOUND', 404, {
+ *   requestId: 'req_123',
+ *   operation: 'agent_execution',
+ *   component: 'AgentManager'
+ * })
+ * ```
+ */
+export declare class AppError extends Error {
+    /** Error code for programmatic error identification */
+    readonly code: string;
+    /** HTTP status code for error response handling */
+    readonly statusCode: number;
+    /** Context information for debugging and tracing */
+    readonly context: ErrorContext;
+    /**
+     * Creates a new AppError instance.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic identification
+     * @param statusCode - HTTP status code (default: 500)
+     * @param context - Additional context information
+     */
+    constructor(message: string, code: string, statusCode?: number, context?: ErrorContext);
+    /**
+     * Converts error to a structured object for logging or API responses.
+     *
+     * @returns Structured error object
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Creates a user-friendly error message without sensitive information.
+     *
+     * @returns User-friendly error message
+     */
+    toUserMessage(): string;
+}
+/**
+ * Validation error class for input validation failures.
+ *
+ * Used when user input fails validation checks such as format validation,
+ * required field checks, or constraint violations.
+ * Automatically sets HTTP status code to 400 (Bad Request).
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid email format', 'INVALID_EMAIL', {
+ *   operation: 'user_input_validation',
+ *   metadata: { field: 'email', value: 'invalid-email' }
+ * })
+ * ```
+ */
+export declare class ValidationError extends AppError {
+    /**
+     * Creates a new ValidationError instance.
+     *
+     * @param message - Description of the validation failure
+     * @param code - Error code for the specific validation failure
+     * @param context - Additional context information
+     */
+    constructor(message: string, code: string, context?: ErrorContext);
+}
+//# sourceMappingURL=ErrorHandler.d.ts.map