/**
 * MCP-specific error codes per JSON-RPC specification.
 * These codes are used in the JSON-RPC error response format.
 */
export declare const MCP_ERROR_CODES: {
    /** Unauthorized - missing credentials (-32001) */
    readonly UNAUTHORIZED: -32001;
    /** Resource not found (-32002) */
    readonly RESOURCE_NOT_FOUND: -32002;
    /** Forbidden - invalid or insufficient credentials (-32003) */
    readonly FORBIDDEN: -32003;
    /** Invalid request (-32600) */
    readonly INVALID_REQUEST: -32600;
    /** Method not found (-32601) */
    readonly METHOD_NOT_FOUND: -32601;
    /** Invalid params (-32602) */
    readonly INVALID_PARAMS: -32602;
    /** Internal error (-32603) */
    readonly INTERNAL_ERROR: -32603;
    /** Parse error (-32700) */
    readonly PARSE_ERROR: -32700;
};
export type McpErrorCode = (typeof MCP_ERROR_CODES)[keyof typeof MCP_ERROR_CODES];
/**
 * Base class for all MCP-related errors
 */
export declare abstract class McpError extends Error {
    /**
     * Unique error ID for tracking in logs
     */
    errorId: string;
    /**
     * Whether this error should expose details to the client
     */
    abstract readonly isPublic: boolean;
    /**
     * HTTP status code equivalent (for reference)
     */
    abstract readonly statusCode: number;
    /**
     * Error code for categorization
     */
    abstract readonly code: string;
    protected constructor(message: string, errorId?: string);
    private generateErrorId;
    /**
     * Get the public-facing error message
     */
    abstract getPublicMessage(): string;
    /**
     * Get the internal error message (for logging)
     */
    getInternalMessage(): string;
    /**
     * Convert to MCP error response format
     */
    toMcpError(isDevelopment?: boolean): {
        content: Array<{
            type: 'text';
            text: string;
        }>;
        isError: true;
        _meta?: {
            errorId: string;
            code: string;
            timestamp: string;
            stack?: string;
        };
    };
}
/**
 * Public errors - safe to expose to clients
 * These include validation errors, not found errors, etc.
 */
export declare class PublicMcpError extends McpError {
    readonly isPublic = true;
    readonly statusCode: number;
    readonly code: string;
    /**
     * Optional RFC 6750 `WWW-Authenticate` challenge to forward to the client
     * when the error maps to a 401. Set by callers that attach an auth challenge
     * (e.g. the local transport adapter when a verified token's session can't be
     * reconstructed, #471); rendered by the flow runner into a response header.
     */
    readonly wwwAuthenticate?: string;
    constructor(message: string, code?: string, statusCode?: number, wwwAuthenticate?: string);
    getPublicMessage(): string;
}
/**
 * Internal errors - should not expose details to clients
 * These are server errors, unexpected failures, etc.
 */
export declare class InternalMcpError extends McpError {
    readonly isPublic = false;
    readonly statusCode = 500;
    readonly code: string;
    constructor(message: string, code?: string);
    getPublicMessage(): string;
}
/**
 * Tool not found error
 */
export declare class ToolNotFoundError extends PublicMcpError {
    constructor(toolName: string);
}
/**
 * Tool not consented error.
 *
 * Thrown at `tools/call` time when consent mode is enabled and the caller's
 * verified token carries a `consent` claim whose selected-tool set does NOT
 * include the requested tool. This is the runtime enforcement of the consent
 * screen: a user who unchecked a tool during authorization cannot invoke it.
 *
 * Tokens with NO consent metadata (consent disabled) never reach this error —
 * the call-tool flow skips the check entirely so the default (allow-all)
 * behavior is preserved.
 *
 * Mapped to JSON-RPC -32003 (FORBIDDEN) so clients can distinguish a
 * deliberately-withheld tool from a missing one (-32601 / 404).
 */
export declare class ToolNotConsentedError extends PublicMcpError {
    readonly mcpErrorCode: -32003;
    readonly toolName: string;
    constructor(toolName: string);
    toJsonRpcError(): {
        code: number;
        message: string;
        data: {
            tool: string;
        };
    };
}
/**
 * Entry unavailable in the current environment.
 * Thrown when a tool/resource/prompt/skill/agent exists but is restricted
 * by its `availableWhen` constraint (os, runtime, deployment, provider,
 * target, surface, or env).
 *
 * Issue #417 — the error data now carries `missingAxes` so clients can
 * surface "this tool isn't reachable because surface=mcp / provider=vercel
 * / target=cli / …" without parsing the prose message.
 */
export declare class EntryUnavailableError extends PublicMcpError {
    readonly mcpErrorCode: -32003;
    readonly entryType: string;
    readonly entryName: string;
    readonly availability?: unknown;
    readonly runtimeContext?: unknown;
    /** Issue #417 — axes that failed to match (e.g. ['surface', 'provider']). */
    readonly missingAxes: string[];
    constructor(entryType: string, entryName: string, availability?: unknown, runtimeContext?: unknown, missingAxes?: string[]);
    /**
     * Convert to JSON-RPC error format per MCP specification.
     *
     * Issue #417 — `data` now exposes `{tool, missingAxes, constraint, context}`
     * so MCP clients can react structurally without parsing prose.
     */
    toJsonRpcError(): {
        code: number;
        message: string;
        data: {
            entryType: string;
            entry: string;
            missingAxes: string[];
            constraint?: unknown;
            context?: unknown;
        };
    };
}
/**
 * Resource not found error
 */
export declare class ResourceNotFoundError extends PublicMcpError {
    readonly uri: string;
    readonly mcpErrorCode: -32002;
    constructor(uri: string);
    /**
     * Convert to JSON-RPC error format per MCP specification.
     *
     * @example
     * {
     *   "code": -32002,
     *   "message": "Resource not found: file:///missing.txt",
     *   "data": { "uri": "file:///missing.txt" }
     * }
     */
    toJsonRpcError(): {
        code: number;
        message: string;
        data?: {
            uri: string;
        };
    };
}
/**
 * Resource read error (internal)
 */
export declare class ResourceReadError extends InternalMcpError {
    readonly originalError?: Error;
    constructor(uri: string, originalError?: Error);
    getInternalMessage(): string;
}
/**
 * Invalid resource URI error
 */
export declare class InvalidResourceUriError extends PublicMcpError {
    constructor(uri: string, reason?: string);
}
/**
 * Invalid input validation error
 */
export declare class InvalidInputError extends PublicMcpError {
    readonly validationErrors?: any;
    constructor(message?: string, validationErrors?: any);
    getInternalMessage(): string;
    getPublicMessage(): string;
}
/**
 * Invalid output validation error (internal - don't expose schema details)
 */
export interface InvalidOutputErrorDetails {
    /** Property path inside the structured output where the violation was found. */
    path?: string;
    /** String form of the offending value (e.g., 'Infinity', 'NaN'). */
    value?: string;
    /** Free-form reason for the rejection (e.g., 'non-finite-number'). */
    reason?: string;
}
export declare class InvalidOutputError extends InternalMcpError {
    private readonly hasCustomErrorId;
    /** Optional structured context — path/value/reason — for diagnostics. */
    readonly details?: InvalidOutputErrorDetails;
    constructor(errorIdOrDetails?: string | InvalidOutputErrorDetails, maybeDetails?: InvalidOutputErrorDetails);
    getPublicMessage(): string;
}
/**
 * Invalid method error
 */
export declare class InvalidMethodError extends PublicMcpError {
    constructor(method: string, expected: string);
}
/**
 * Request body exceeded the configured size limit.
 * Mapped to HTTP 413 by transport adapters and to JSON-RPC -32600
 * (Invalid Request) by `toJsonRpcError()` — JSON-RPC has no dedicated
 * "payload too large" code.
 */
export declare class PayloadTooLargeError extends PublicMcpError {
    readonly limit?: number;
    readonly length?: number;
    readonly mcpErrorCode: -32600;
    constructor(limit?: number, length?: number);
    toJsonRpcError(): {
        code: number;
        message: string;
        data: {
            limit?: number;
            length?: number;
        };
    };
}
/**
 * Tool execution error (internal)
 */
export declare class ToolExecutionError extends InternalMcpError {
    readonly originalError?: Error;
    constructor(toolName: string, originalError?: Error);
    getInternalMessage(): string;
}
/**
 * Rate limit error
 */
export declare class RateLimitError extends PublicMcpError {
    constructor(retryAfter?: number);
}
/**
 * Quota exceeded error
 */
export declare class QuotaExceededError extends PublicMcpError {
    constructor(quotaType?: string);
}
/**
 * Unauthorized error
 */
export declare class UnauthorizedError extends PublicMcpError {
    constructor(message?: string, wwwAuthenticate?: string);
}
/**
 * Generic server error wrapper
 */
export declare class GenericServerError extends InternalMcpError {
    readonly originalError?: Error;
    constructor(message: string, originalError?: Error);
    getInternalMessage(): string;
}
/**
 * Dependency not found error (internal) - thrown when a required dependency
 * is not found in a registry during initialization.
 */
export declare class DependencyNotFoundError extends InternalMcpError {
    constructor(registryName: string, dependencyName: string);
}
/**
 * Invalid hook flow error - thrown when a hook is registered with a flow
 * that is not supported by the entry type (e.g., tool hook on resource class).
 */
export declare class InvalidHookFlowError extends InternalMcpError {
    constructor(message: string);
}
/**
 * Invalid plugin scope error - thrown when a plugin with scope='server'
 * is used in a standalone app, which is not allowed.
 */
export declare class InvalidPluginScopeError extends InternalMcpError {
    constructor(message: string);
}
/**
 * Request context not available error - thrown when code attempts to access
 * RequestContext outside of a request scope (i.e., without AsyncLocalStorage context).
 */
export declare class RequestContextNotAvailableError extends InternalMcpError {
    constructor(message?: string);
}
/**
 * Auth configuration error - thrown when auth configuration is invalid
 * (e.g., transparent mode on parent with multiple child providers).
 */
export declare class AuthConfigurationError extends PublicMcpError {
    readonly errors: string[];
    readonly suggestion?: string;
    constructor(message: string, options?: {
        errors?: string[];
        suggestion?: string;
    });
    getPublicMessage(): string;
}
/**
 * Prompt not found error.
 */
export declare class PromptNotFoundError extends PublicMcpError {
    constructor(promptName: string);
}
/**
 * Prompt execution error - wraps errors during prompt execution.
 */
export declare class PromptExecutionError extends InternalMcpError {
    readonly promptName: string;
    readonly originalError?: Error;
    constructor(promptName: string, cause?: Error);
    getInternalMessage(): string;
}
/**
 * Session missing error - thrown when a request is made without a valid session.
 * This is a public error as the client needs to know they need to authenticate.
 */
export declare class SessionMissingError extends PublicMcpError {
    constructor(message?: string);
}
/**
 * Unsupported client version error - thrown when a client connects with
 * an unsupported protocol version.
 */
export declare class UnsupportedClientVersionError extends PublicMcpError {
    readonly clientVersion: string;
    constructor(version: string);
    /**
     * Factory method for creating from a version string.
     */
    static fromVersion(version: string): UnsupportedClientVersionError;
}
/**
 * Global configuration not found error - thrown when a plugin requires
 * global configuration that is not defined in @FrontMcp decorator.
 */
export declare class GlobalConfigNotFoundError extends PublicMcpError {
    readonly pluginName: string;
    readonly configKey: string;
    constructor(pluginName: string, configKey: string);
}
/**
 * Check if the error is a public error that can be safely shown to users
 */
export declare function isPublicError(error: any): error is PublicMcpError;
/**
 * Convert any error to an MCP error
 */
export declare function toMcpError(error: any): McpError;
/**
 * Format error for MCP response
 */
export declare function formatMcpErrorResponse(error: any, isDevelopment?: boolean): {
    content: Array<{
        type: "text";
        text: string;
    }>;
    isError: true;
    _meta?: {
        errorId: string;
        code: string;
        timestamp: string;
        stack?: string;
    };
};
/**
 * Walk an error chain (cause / originalError) and return the most
 * user-friendly message available — preferring `PublicMcpError.getPublicMessage()`,
 * falling back to a wrapped `originalError`'s public message, and finally
 * to `error.message` / `String(error)`.
 *
 * Used by the CLI error formatter so that `this.fail(new PublicMcpError('X'))`
 * surfaces "X" rather than the wrapper's "Tool execution failed: Unknown error".
 *
 * Cycles in the chain (legal in JS — e.g. `e.cause = e`, or transitive
 * `a.cause = b; b.cause = a`) are short-circuited via a `WeakSet` of
 * already-visited error objects. The walker terminates immediately on
 * revisit instead of recursing further.
 */
export declare function extractPublicMessage(error: unknown): string;
//# sourceMappingURL=mcp.error.d.ts.map