/**
 * MCP Apps (ext-apps) Message Handler
 *
 * Server-side handler for bidirectional communication with ext-apps widgets.
 * Processes JSON-RPC requests from widgets and routes them to appropriate handlers.
 *
 * @see https://github.com/modelcontextprotocol/ext-apps
 * @packageDocumentation
 */
import type { FrontMcpLogger } from '../common';
import type { ExtAppsJsonRpcRequest, ExtAppsJsonRpcResponse, ExtAppsHostCapabilities } from './ext-apps.types';
/**
 * Context for handling ext-apps messages.
 * Provides access to scope services for routing requests.
 */
export interface ExtAppsHandlerContext {
    /** Session ID for this widget connection */
    sessionId: string;
    /** Logger instance */
    logger: FrontMcpLogger;
    /** Call a tool by name */
    callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
    /** Update model context (optional - host may not support) */
    updateModelContext?: (context: unknown, merge: boolean) => Promise<void>;
    /** Open a link (optional - host may not support) */
    openLink?: (url: string) => Promise<void>;
    /** Request display mode change (optional - host may not support) */
    setDisplayMode?: (mode: string) => Promise<void>;
    /** Close the widget (optional - host may not support) */
    close?: (reason?: string) => Promise<void>;
    /** Register a widget-defined tool (optional - host may not support) */
    registerTool?: (name: string, description: string, inputSchema: Record<string, unknown>) => Promise<void>;
    /** Unregister a widget-defined tool (optional - host may not support) */
    unregisterTool?: (name: string) => Promise<void>;
}
/**
 * Options for creating an ExtAppsMessageHandler.
 */
export interface ExtAppsMessageHandlerOptions {
    /** Handler context with routing capabilities */
    context: ExtAppsHandlerContext;
    /** Host capabilities to advertise */
    hostCapabilities?: ExtAppsHostCapabilities;
}
/**
 * Message handler for ext-apps widget-to-host JSON-RPC communication.
 *
 * Handles all JSON-RPC methods defined in the MCP Apps specification:
 * - ui/callServerTool - Proxy tool calls to the MCP server
 * - ui/updateModelContext - Update the model context with widget state
 * - ui/openLink - Request to open a URL
 * - ui/setDisplayMode - Request display mode change
 * - ui/close - Close the widget
 * - ui/log - Forward logs to server logger
 * - ui/registerTool - Register a widget-defined tool
 * - ui/unregisterTool - Unregister a widget-defined tool
 *
 * @example
 * ```typescript
 * import { ExtAppsMessageHandler } from '@frontmcp/sdk/ext-apps';
 *
 * const handler = new ExtAppsMessageHandler({
 *   context: {
 *     sessionId: 'session-123',
 *     logger: scopeLogger,
 *     callTool: async (name, args) => {
 *       // Route to tool call flow
 *       return scope.flows.run('tools:call-tool', { name, args });
 *     },
 *   },
 *   hostCapabilities: {
 *     serverToolProxy: true,
 *     logging: true,
 *   },
 * });
 *
 * // Handle incoming request
 * const response = await handler.handleRequest(request);
 * ```
 */
export declare class ExtAppsMessageHandler {
    private readonly context;
    private readonly hostCapabilities;
    private readonly logger;
    constructor(options: ExtAppsMessageHandlerOptions);
    /**
     * Get the host capabilities for this handler.
     */
    getHostCapabilities(): ExtAppsHostCapabilities;
    /**
     * Handle a JSON-RPC request from a widget.
     *
     * @param request - The JSON-RPC request
     * @returns The JSON-RPC response
     */
    handleRequest(request: ExtAppsJsonRpcRequest): Promise<ExtAppsJsonRpcResponse>;
    /**
     * Route a method to its handler.
     */
    private routeMethod;
    /**
     * Handle ui/initialize - Protocol handshake with widget.
     * Returns host capabilities and initial context.
     */
    private handleInitialize;
    /**
     * Handle ui/callServerTool - Route tool call to MCP server.
     */
    private handleCallServerTool;
    /**
     * Handle ui/updateModelContext - Update model context with widget state.
     */
    private handleUpdateModelContext;
    /**
     * Handle ui/openLink - Request to open a URL.
     */
    private handleOpenLink;
    /**
     * Handle ui/setDisplayMode - Request display mode change.
     */
    private handleSetDisplayMode;
    /**
     * Handle ui/close - Close the widget.
     */
    private handleClose;
    /**
     * Handle ui/log - Forward logs to server logger.
     */
    private handleLog;
    /**
     * Handle ui/registerTool - Register a widget-defined tool.
     */
    private handleRegisterTool;
    /**
     * Handle ui/unregisterTool - Unregister a widget-defined tool.
     */
    private handleUnregisterTool;
    /**
     * Get the appropriate error code for an error.
     */
    private getErrorCode;
}
/**
 * Base class for ext-apps errors.
 */
export declare class ExtAppsError extends Error {
    constructor(message: string);
}
/**
 * Method not found error.
 */
export declare class ExtAppsMethodNotFoundError extends ExtAppsError {
    constructor(message: string);
}
/**
 * Invalid params error.
 */
export declare class ExtAppsInvalidParamsError extends ExtAppsError {
    constructor(message: string);
}
/**
 * Feature not supported error.
 */
export declare class ExtAppsNotSupportedError extends ExtAppsError {
    constructor(message: string);
}
/**
 * Tool not found error.
 */
export declare class ExtAppsToolNotFoundError extends ExtAppsError {
    constructor(message: string);
}
/**
 * Factory function for creating an ExtAppsMessageHandler.
 */
export declare function createExtAppsMessageHandler(options: ExtAppsMessageHandlerOptions): ExtAppsMessageHandler;
//# sourceMappingURL=ext-apps.handler.d.ts.map