/**
 * Diagnostic sidecar writer for compaction planner output.
 *
 * When the one-pass range planner returns malformed output or no usable ranges,
 * this module writes a private diagnostic file next to the persisted session
 * file. The sidecar is never written for in-memory sessions.
 *
 * Additionally, successful partial recovery from length-truncated responses
 * writes a private recovery diagnostic sidecar for operational observability.
 */
import type { Api, AssistantMessage, Model, Usage } from "@earendil-works/pi-ai/compat";
/** Failure categories emitted in diagnostic sidecars. */
export type DiagnosticFailureCategory = "malformed_output" | "no_usable_ranges" | "provider_error" | "stream_error";
/** Recovery categories emitted in recovery diagnostic sidecars. */
export type DiagnosticRecoveryCategory = "partial_length_recovery";
/** Safe model metadata subset (no credentials, no headers). */
export interface DiagnosticModelMeta {
    provider: string;
    id: string;
    api: string;
    contextWindow: number;
    maxTokens: number;
}
/** Full diagnostic payload written as the sidecar JSON file. */
export interface CompactionDiagnostic {
    version: 1;
    timestamp: string;
    failureCategory: DiagnosticFailureCategory;
    failureMessage: string;
    rawResponse: string;
    stopReason: string | undefined;
    providerError: string | undefined;
    usage: Usage | undefined;
    requestMaxTokens: number;
    model: DiagnosticModelMeta;
}
/** Recovery diagnostic payload written on successful partial recovery. */
export interface RecoveryDiagnostic {
    version: 1;
    timestamp: string;
    recoveryCategory: DiagnosticRecoveryCategory;
    rawResponse: string;
    stopReason: string | undefined;
    usage: Usage | undefined;
    requestMaxTokens: number;
    model: DiagnosticModelMeta;
    recoveredRangeCount: number;
}
export interface DiagnosticContext {
    /** Absolute path to the persisted session file, or undefined for in-memory sessions. */
    sessionFilePath: string | undefined;
    /** The model used for the planner request. */
    model: Model<Api>;
    /** The maxTokens value sent in the planner request. */
    requestMaxTokens: number;
    /** The full assistant response message, if one was received. */
    response: AssistantMessage | undefined;
    /** The full raw text extracted from the response. */
    rawResponseText: string;
    /** The failure category. */
    failureCategory: DiagnosticFailureCategory;
    /** The user-facing failure message. */
    failureMessage: string;
}
declare function buildDiagnosticPayload(ctx: DiagnosticContext): CompactionDiagnostic;
/**
 * Derive the sidecar file path from a session file path and current timestamp.
 * The sidecar sits alongside the session file with a `-compaction-diagnostic-<ts>.json` suffix.
 */
export declare function diagnosticSidecarPath(sessionFilePath: string): string;
/**
 * Attempt to write a diagnostic sidecar file. Returns the written path on
 * success, or undefined if the session is in-memory or writing fails.
 *
 * The file is written with mode 0o600 (owner-only read/write) on platforms
 * that support POSIX permissions.
 */
export declare function writeDiagnosticSidecar(ctx: DiagnosticContext): string | undefined;
/**
 * Build the diagnostic payload without writing. Exported for testing.
 */
export { buildDiagnosticPayload };
/** Context for writing a recovery diagnostic sidecar. */
export interface RecoveryDiagnosticContext {
    sessionFilePath: string | undefined;
    model: Model<Api>;
    requestMaxTokens: number;
    response: AssistantMessage;
    rawResponseText: string;
    recoveryCategory: DiagnosticRecoveryCategory;
    recoveredRangeCount: number;
}
declare function buildRecoveryPayload(ctx: RecoveryDiagnosticContext): RecoveryDiagnostic;
/**
 * Write a recovery diagnostic sidecar on successful partial recovery.
 * Returns the written path on success, or undefined if write fails or session is in-memory.
 * Write failures are silently swallowed — recovery success is never affected.
 */
export declare function writeRecoveryDiagnosticSidecar(ctx: RecoveryDiagnosticContext): string | undefined;
export { buildRecoveryPayload };
//# sourceMappingURL=range-planner-diagnostics.d.ts.map