/**
 * Escalation Controller (Phase 5)
 *
 * An onIteration handler that watches for stagnation and climbs an escalation
 * ladder: when the best gate score stops improving for N consecutive turns,
 * advance to the next tier. Tiers escalate cost progressively — widen
 * exploration, enable the critic, raise the turn budget, and finally switch to
 * a stronger model — so cheap strategies are exhausted before expensive ones.
 *
 * The controller is pure policy: it inspects IterationRecords and returns
 * directives. The loop owns all mutation. This keeps escalation testable in
 * isolation and swappable without touching the loop.
 */
import type { IterationRecord, IterationDirective, LoopExecutor } from './convergence-loop.js';
export interface EscalationTier {
    /** Label surfaced in directive notes and logs */
    label: string;
    /** Widen best-of-N exploration to this many candidates */
    setCandidates?: number;
    /** Turn the structured critic on */
    enableCritic?: boolean;
    /** Raise the absolute turn budget */
    raiseMaxTurns?: number;
    /** Escalate to a stronger model */
    switchExecutor?: LoopExecutor;
}
export interface EscalationConfig {
    tiers: EscalationTier[];
    /**
     * Consecutive non-improving turns that trigger advancing one tier
     * (default 2). A turn "improves" if its score exceeds the best seen so far.
     */
    stagnationTurns?: number;
    /** Minimum score delta to count as improvement (default 0.01) */
    improvementEpsilon?: number;
    /** Called whenever a tier is applied (telemetry/logging) */
    onEscalate?: (tier: EscalationTier, turn: number) => void;
}
export interface EscalationController {
    onIteration: (record: IterationRecord) => IterationDirective;
    /** Index of the next tier to apply (for inspection/tests) */
    tierIndex(): number;
}
export interface DefaultLadderOptions {
    /** Candidates to widen exploration to on the first escalation (default 3) */
    candidates?: number;
    /** Current turn budget; the model-switch tier raises it by +2 */
    maxTurns?: number;
    /** A stronger model executor; when present, adds a final model-switch tier */
    escalateExecutor?: LoopExecutor;
    /** Display name for the stronger model (for the tier label) */
    escalateModelName?: string;
}
/**
 * The canonical escalation ladder: exhaust cheap strategies before expensive
 * ones — widen exploration, then enable the critic, then (if configured)
 * switch to a stronger model with a couple extra turns. Library-owned so
 * non-CLI callers get the same policy.
 */
export declare function defaultEscalationLadder(options?: DefaultLadderOptions): EscalationTier[];
/**
 * Build a stagnation-driven escalation controller. Returns an `onIteration`
 * suitable for ConvergenceConfig, plus a `tierIndex` accessor for tests.
 */
export declare function createEscalationController(config: EscalationConfig): EscalationController;
//# sourceMappingURL=escalation.d.ts.map