/**
 * @fileoverview Handler factory for tool definitions.
 * Constructs Context, checks inline auth, measures execution, formats response.
 * @module src/mcp-server/tools/utils/toolHandlerFactory
 */
import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
import type { CallToolResult, ContentBlock, ElicitRequestFormParams, ElicitRequestURLParams, ElicitResult, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
import { type ZodObject, type ZodRawShape } from 'zod';
import type { Context } from '../../../core/context.js';
import type { StorageService } from '../../../storage/core/StorageService.js';
import { type JsonRpcErrorCode } from '../../../types-global/errors.js';
import type { Logger } from '../../../utils/internal/logger.js';
import type { AnyToolDefinition } from './toolDefinition.js';
type SdkExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
/** Services required by the handler factory to construct Context. */
export interface HandlerFactoryServices {
    /**
     * When true, surface `ctx.sessionId` even in stateless HTTP mode (per-request
     * generated token). Wired from `createApp({ context: { exposeStatelessSessionId } })`.
     * Default false — `ctx.sessionId` is only set when the session has
     * request-spanning lifetime (HTTP `stateful` / `auto` mode).
     */
    exposeStatelessSessionId?: boolean;
    logger: Logger;
    storage: StorageService;
}
/**
 * Per-server notifier closures bound at registration time, targeting
 * `server.send*ListChanged()` and `server.server.elicitInput(...)`.
 *
 * Split from {@link HandlerFactoryServices} so each per-request McpServer gets
 * its own notifier closures — preventing a concurrent registerAll() from
 * overwriting an in-flight handler's notifier target (and potentially
 * notifying the wrong server).
 *
 * The sync handler factory prefers request-scoped notifiers
 * ({@link buildRequestScopedNotifiers}, #135) and uses these only as a fallback;
 * the background auto-task path uses them directly (no request scope), so those
 * notifications deliver on stdio but drop under HTTP.
 *
 * `elicitInput` and `getClientCapabilities` are bound at registration time to
 * the per-server `Server` instance so `wrapElicit` can gate `ctx.elicit` on
 * the client's advertised capability and forward elicitation requests on the
 * wire. Both are undefined in the auto-task background path (no connected
 * client is available).
 */
export interface HandlerNotifiers {
    /** Bound to `server.server.elicitInput.bind(server.server)`. */
    elicitInput?: (params: ElicitRequestFormParams | ElicitRequestURLParams) => Promise<ElicitResult>;
    /** Bound to `server.server.getClientCapabilities.bind(server.server)`. */
    getClientCapabilities?: () => {
        elicitation?: unknown;
    } | undefined;
    notifyPromptListChanged?: () => void;
    notifyResourceListChanged?: () => void;
    notifyResourceUpdated?: (uri: string) => void;
    notifyToolListChanged?: () => void;
}
/**
 * Shapes a `CallToolResult` for a tool error response with parity across both
 * surfaces clients forward to the agent:
 * - `content[]` — read by clients like Claude Desktop (markdown)
 * - `structuredContent.error` — read by clients like Claude Code (JSON)
 *
 * Both surfaces carry the same payload. When `data.recovery.hint` is present,
 * it is also mirrored into the `content[]` text so format()-only clients see
 * the recovery guidance.
 *
 * Note: `_meta.error` is intentionally NOT emitted — the error code, message,
 * and data live on `structuredContent.error` instead, mirroring the success
 * path's `structuredContent` surface.
 */
export declare function buildToolErrorResult(code: JsonRpcErrorCode, message: string, data: Record<string, unknown> | undefined): CallToolResult;
/**
 * Builds an error `CallToolResult` from a raw thrown value. Classifies via
 * {@link ErrorHandler.classifyOnly} when the value isn't already an
 * `McpError`. Only propagates data from `McpError` (its declared `data`) or
 * `ZodError` (its `issues`) — other thrown values get a `structuredContent.error`
 * with `code` and `message` only, so internal classification context never
 * leaks to clients.
 *
 * Use after invoking {@link ErrorHandler.handleError} for OTel/logging side
 * effects — this helper does not log.
 */
export declare function classifyAndBuildToolErrorResult(error: unknown): CallToolResult;
/**
 * The output schema advertised to clients in `tools/list`. When a tool declares
 * an `enrichment` block, that's `output.extend(enrichment)` so enrichment fields
 * appear in the advertised `outputSchema`; otherwise the bare `output`.
 */
export declare function effectiveOutputSchema(def: AnyToolDefinition): ZodObject<ZodRawShape>;
/**
 * Shapes the success `CallToolResult` surfaces from the validated domain payload
 * plus any accumulated enrichment:
 * - `structuredContent` — domain output merged with enrichment (validated against
 *   `output.extend(enrichment)`); the bare domain output when no enrichment block.
 * - `content[]` — the caller-rendered domain content (from `format()` or the
 *   JSON-stringify default, applied to the **domain payload only**) with the
 *   enrichment trailer always appended. Rendering the domain payload — never the
 *   merged object — keeps enrichment out of the JSON blob and avoids double-render.
 *
 * A required enrichment field the handler never populated fails the parse here,
 * surfacing the authoring bug as a loud error rather than dropping it silently.
 */
export declare function buildToolSuccessResult(def: AnyToolDefinition, ctx: Context, domainValidated: Record<string, unknown>, domainContent: ContentBlock[]): Pick<CallToolResult, 'content' | 'structuredContent'>;
/**
 * Creates an MCP tool handler from a tool definition.
 * The returned function is compatible with the MCP SDK's ToolCallback type.
 *
 * Responsibilities:
 * - Creates RequestContext from SDK context (for tracing)
 * - Creates unified Context (for the handler)
 * - Checks inline `auth` scopes if defined
 * - Validates input via Zod schema
 * - Measures execution time
 * - Formats response via `format` or JSON default
 * - Catches errors and returns `isError: true`
 */
export declare function createToolHandler(def: AnyToolDefinition, services: HandlerFactoryServices, notifiers: HandlerNotifiers): (input: Record<string, unknown>, extra: SdkExtra) => Promise<CallToolResult>;
export {};
//# sourceMappingURL=toolHandlerFactory.d.ts.map