/**
 * MCP Tool Result Helpers
 *
 * Provides:
 * - createToolResult: Builds a stable structured and text result envelope.
 * - createToolErrorResult: Builds a structured MCP error response.
 * - ensureStructuredToolResult: Adds the envelope to legacy JSON-text results.
 */
import type { PolicyDecision } from "../core/policy/types.js";
/** Stable status values shared by PlatformIO MCP tools. */
export type ToolResultStatus = "completed" | "running" | "cancelled" | "failed" | "blocked" | "unavailable";
/** Common structured result envelope exposed to MCP clients. */
export interface ToolResultEnvelope<TData = unknown> {
    success: boolean;
    status: ToolResultStatus;
    summary: string;
    data?: TData;
    diagnostics?: unknown[];
    nextSteps?: string[];
    taskId?: string;
    logPaths?: string[];
    observedAt: string;
    policyDecision?: PolicyDecision;
}
/** MCP-compatible response containing both legacy JSON text and structured data. */
export interface StructuredToolResult<TData = unknown> {
    content: Array<{
        type: "text";
        text: string;
    }>;
    structuredContent: ToolResultEnvelope<TData>;
    isError?: boolean;
}
/**
 * Builds a stable response while preserving JSON-in-text compatibility.
 *
 * @param input - Result fields, excluding the generated observation timestamp.
 * @returns MCP content and structuredContent with identical envelope data.
 */
export declare function createToolResult<TData>(input: Omit<ToolResultEnvelope<TData>, "observedAt"> & {
    observedAt?: string;
}): StructuredToolResult<TData>;
/**
 * Builds a stable error response with actionable next steps.
 *
 * @param summary - Concise explanation of the failure.
 * @param options - Optional data, diagnostics, and remediation details.
 * @returns MCP error response.
 */
export declare function createToolErrorResult<TData = unknown>(summary: string, options?: {
    status?: Extract<ToolResultStatus, "failed" | "blocked" | "unavailable">;
    data?: TData;
    diagnostics?: unknown[];
    nextSteps?: string[];
    policyDecision?: PolicyDecision;
}): StructuredToolResult<TData>;
/**
 * Adds structured content to a legacy MCP response while preserving its text.
 *
 * @param toolName - Public MCP tool name used in the fallback summary.
 * @param response - Existing response returned by a tool handler.
 * @returns Original content plus a stable structured result envelope.
 */
export declare function ensureStructuredToolResult<TResponse extends {
    content?: Array<{
        type?: string;
        text?: string;
    }>;
    structuredContent?: ToolResultEnvelope;
    isError?: boolean;
}>(toolName: string, response: TResponse): TResponse & {
    structuredContent: ToolResultEnvelope;
};
//# sourceMappingURL=tool-result.d.ts.map