import type { ToolConfigDiagnostic } from "./tool-config-validation.js";
export type FrameworkErrorKind = "tool-config" | "runtime-init" | "runtime-dispose" | "coordinator-init" | "provider-init" | "provider-register" | "tts-init" | "tool-state-load" | "tool-state-save" | "section-controller-init" | "section-controller-dispose" | "unknown";
export type FrameworkErrorSeverity = "warning" | "error";
export interface FrameworkErrorModel {
    kind: FrameworkErrorKind;
    severity: FrameworkErrorSeverity;
    source: string;
    message: string;
    details: string[];
    recoverable: boolean;
    cause?: unknown;
}
export declare function toFrameworkErrorModel(args: {
    kind: FrameworkErrorKind;
    severity?: FrameworkErrorSeverity;
    source: string;
    message: string;
    details?: string[];
    recoverable?: boolean;
    cause?: unknown;
}): FrameworkErrorModel;
export declare function frameworkErrorFromUnknown(args: {
    kind: FrameworkErrorKind;
    source: string;
    error: unknown;
    recoverable?: boolean;
}): FrameworkErrorModel;
/**
 * Coordinator-side error context shape consumed by
 * {@link frameworkErrorFromCoordinatorContext}.
 *
 * This is a deliberately small, structural mirror of
 * `ToolkitErrorContext` from `ToolkitCoordinator.ts`. It lives here (and not
 * in `ToolkitCoordinator.ts`) to keep `framework-error.ts` free of a cycle
 * back to the coordinator. `ToolkitErrorContext` remains the source of
 * truth for coordinator code; values of that type satisfy this shape.
 */
export interface FrameworkErrorCoordinatorContext {
    phase: "coordinator-ready" | "state-load" | "state-save" | "provider-register" | "provider-init" | "tts-init" | "section-controller-init" | "section-controller-dispose";
    providerId?: string;
    details?: Record<string, unknown>;
}
/**
 * Build a {@link FrameworkErrorModel} from a coordinator-side error +
 * context pair.
 *
 * Maps `context.phase` to the canonical {@link FrameworkErrorKind} and
 * synthesizes a `source` from `context.providerId` when present
 * (`pie-toolkit-coordinator/<providerId>`); falls back to a phase-tagged
 * source (`pie-toolkit-coordinator:<phase>`) otherwise. Forwards the
 * original `error` as `cause` so hosts that care about the underlying
 * `Error` keep getting it.
 *
 * Recoverable defaults to `false` (most coordinator-phase failures are
 * not auto-recovered today). Override with `recoverable: true` for the
 * phases where the coordinator continues operating after the failure.
 */
export declare function frameworkErrorFromCoordinatorContext(args: {
    error: unknown;
    context: FrameworkErrorCoordinatorContext;
    recoverable?: boolean;
}): FrameworkErrorModel;
export declare function frameworkErrorFromToolConfigDiagnostics(args: {
    source: string;
    diagnostics: ToolConfigDiagnostic[];
    recoverable?: boolean;
}): FrameworkErrorModel;
export declare function formatFrameworkErrorForConsole(error: FrameworkErrorModel): string;
