/** Shared error formatting for MCP tool handlers. */
import { ProjectCredentialNotFound as SdkProjectCredentialNotFound } from "../sdk/dist/index.js";
import { type ToolError, type ToolResult } from "./structured.js";
export type { ToolResult } from "./structured.js";
/**
 * Format an API error response into an agent-friendly MCP tool result.
 *
 * Always includes: HTTP status, API error message, and actionable next-step guidance.
 * Extracts optional fields: hint, retry_after, renew_url, usage, expires_at,
 * and lifecycle signals (lifecycle_state, entered_state_at, next_transition_at,
 * scheduled_purge_at) when the gateway returns them on a grace-state denial.
 * Grace-state (frozen/dormant) control-plane denials are HTTP 403 — 402 is
 * reserved for genuine payment challenges — but both statuses are handled
 * here so the richer "soft-delete grace window" guidance renders either way.
 *
 * @param res  A response-like object with `status` and `body`.
 * @param context  Short verb phrase: "running SQL", "deploying function", etc.
 */
export declare function formatApiError(res: {
    status: number;
    body: unknown;
}, context: string, error?: ToolError): ToolResult;
export declare function formatCanonicalErrorContext(source: unknown, opts?: {
    includeDetails?: boolean;
}): string[];
/**
 * Consistent "project not found in key store" error.
 */
export declare function projectNotFound(projectId: string): ToolResult;
/**
 * Consistent local project credential-cache miss error.
 */
export declare function projectCredentialNotFound(err: SdkProjectCredentialNotFound): ToolResult;
/**
 * Translate an SDK error into the MCP tool-result shape.
 *
 * Routing:
 *   - `ProjectNotFound` → {@link projectNotFound} (preserves existing text)
 *   - HTTP-backed errors (status !== null) → {@link formatApiError}
 *   - `NetworkError` / other `Run402Error` with no status → plain isError text
 *   - Unknown throwables → plain isError text
 *
 * Call this in the catch branch of a thin MCP shim that otherwise does
 * nothing but delegate to an SDK method and format the successful result.
 */
export declare function mapSdkError(err: unknown, context: string): ToolResult;
//# sourceMappingURL=errors.d.ts.map