/**
 * HandlerEnvelope — unified success/error shape for all MCP tool handlers.
 *
 * Lifted out of runHandler.ts so any module (middleware, handlers, tests,
 * dashboard routes) can import the type without pulling in the full
 * runHandler runtime.  runHandler.ts re-exports these for back-compat.
 */
export type HandlerErrorCode = 'timeout' | 'sqlite-busy' | 'runtime-cold' | 'input-invalid' | 'nested-dispatch-refused' | 'internal';
export interface HandlerEnvelope<T = unknown> {
    ok: boolean;
    data?: T;
    error?: {
        code: HandlerErrorCode;
        message: string;
        retriable: boolean;
        hint?: string;
    };
    meta: {
        toolName: string;
        durationMs: number;
        attempts: number;
        runtimeHotAt: number | null;
    };
}
export interface RunHandlerOptions {
    /** Override the per-client default timeout. */
    timeoutMs?: number;
    /** Max retries for transient errors (SQLite-busy, runtime-cold). Default 1. */
    retries?: number;
    /** Caller name for per-client timeout selection. */
    callerName?: string;
    /** Timestamp (ms) when the runtime became hot. Passed through into meta. */
    runtimeHotAt?: number | null;
}
/**
 * Convert a HandlerEnvelope into the MCP tool-call response shape.
 *
 * On success:
 *  - If data is already a ToolResult (`{ content: Array<...> }`), appended footer + pass-through.
 *  - If data is an array of objects, rendered as ASCII table.
 *  - If data is a plain object, rendered as key-value rows.
 *  - If data is a string, returned as-is with footer appended.
 *
 * On error, a compact human-readable error block is produced.
 */
export declare function envelopeToMcpResponse<T>(envelope: HandlerEnvelope<T>): {
    content: Array<{
        type: 'text';
        text: string;
    }>;
};
