/**
 * Intervention Controller
 *
 * Manages user intervention points during analysis.
 * Enables users to guide the analysis when the system needs human judgment.
 *
 * Intervention triggers:
 * 1. Low confidence - analysis results are uncertain
 * 2. Ambiguity - multiple valid analysis directions
 * 3. Timeout - analysis taking too long
 * 4. Agent request - agent explicitly asks for user input
 *
 * Design principles:
 * - Non-blocking by default (SSE notification, not synchronous wait)
 * - Clear context for user decision
 * - Timeout with default action (abort)
 * - State tracking for multi-turn interventions
 */
import { EventEmitter } from 'events';
import type { Finding } from '../types';
/**
 * Types of intervention triggers
 */
export type InterventionType = 'low_confidence' | 'ambiguity' | 'timeout' | 'agent_request' | 'circuit_breaker' | 'validation_required';
/**
 * User actions for intervention
 */
export type InterventionAction = 'continue' | 'focus' | 'abort' | 'custom' | 'select_option';
/**
 * Analysis direction candidate
 */
export interface AnalysisDirection {
    id: string;
    description: string;
    confidence: number;
    requiredAgents: string[];
    estimatedTime?: string;
}
/**
 * Context for an intervention point
 */
export interface InterventionContext {
    /** Current findings discovered so far */
    currentFindings: Finding[];
    /** Possible analysis directions */
    possibleDirections: AnalysisDirection[];
    /** Time elapsed so far */
    elapsedTimeMs: number;
    /** Current confidence level */
    confidence: number;
    /** Number of rounds completed */
    roundsCompleted: number;
    /** Summary of what's been done */
    progressSummary: string;
    /** Reason for intervention */
    triggerReason: string;
}
/**
 * Option for user selection
 */
export interface InterventionOption {
    id: string;
    label: string;
    description: string;
    action: InterventionAction;
    params?: Record<string, any>;
    /** Whether this is the recommended option */
    recommended?: boolean;
}
/**
 * Intervention point requiring user decision
 */
export interface InterventionPoint {
    id: string;
    sessionId: string;
    type: InterventionType;
    context: InterventionContext;
    options: InterventionOption[];
    /** Timestamp when intervention was created */
    createdAt: number;
    /** Timeout for user response (ms) */
    timeout: number;
    /** Default action if timeout expires */
    defaultAction: InterventionAction;
}
/**
 * User's decision for an intervention
 */
export interface UserDecision {
    interventionId: string;
    action: InterventionAction;
    selectedOptionId?: string;
    customInput?: string;
    params?: Record<string, any>;
}
/**
 * Directive for analysis based on user decision
 */
export interface AnalysisDirective {
    action: 'continue' | 'focus' | 'abort' | 'restart';
    reason: string;
    focusDirections?: string[];
    params?: Record<string, any>;
}
export interface InterventionConfig {
    /** Confidence threshold below which intervention is triggered */
    confidenceThreshold: number;
    /** Maximum analysis time before timeout intervention (ms) */
    timeoutThresholdMs: number;
    /** Default timeout for user response (ms) */
    userResponseTimeoutMs: number;
    /** Enable automatic interventions */
    autoIntervention: boolean;
}
export interface AnalysisState {
    sessionId: string;
    confidence: number;
    findings: Finding[];
    possibleDirections: AnalysisDirection[];
    elapsedTimeMs: number;
    roundsCompleted: number;
    progressSummary: string;
}
/**
 * Controller for managing user interventions during analysis.
 */
export declare class InterventionController extends EventEmitter {
    private config;
    private sessions;
    constructor(config?: Partial<InterventionConfig>);
    /**
     * Check if analysis state requires user intervention.
     *
     * @param state - Current analysis state
     * @returns Intervention point if intervention needed, null otherwise
     */
    checkIntervention(state: AnalysisState): InterventionPoint | null;
    /**
     * Create an intervention for agent request.
     */
    createAgentIntervention(sessionId: string, reason: string, options: InterventionOption[], context: Partial<InterventionContext>): InterventionPoint;
    /**
     * Create a validation-required intervention (e.g., for generated SQL).
     */
    createValidationIntervention(sessionId: string, validationTarget: string, validationContext: Record<string, any>): InterventionPoint;
    /**
     * Handle user's decision for an intervention.
     *
     * @param decision - User's decision
     * @returns Directive for how to proceed with analysis
     */
    handleUserDecision(decision: UserDecision): AnalysisDirective;
    /**
     * Check if there's a pending intervention for a session.
     */
    hasPendingIntervention(sessionId: string): boolean;
    /**
     * Get pending intervention for a session.
     */
    getPendingIntervention(sessionId: string): InterventionPoint | null;
    /**
     * Cancel pending intervention.
     */
    cancelIntervention(sessionId: string): void;
    /**
     * Reset state for a session.
     */
    resetSession(sessionId: string): void;
    /**
     * Update configuration.
     */
    updateConfig(config: Partial<InterventionConfig>): void;
    /**
     * Build intervention for low confidence situation.
     */
    private buildLowConfidenceIntervention;
    /**
     * Build intervention for ambiguity situation.
     */
    private buildAmbiguityIntervention;
    /**
     * Build intervention for timeout situation.
     */
    private buildTimeoutIntervention;
    /**
     * Create an intervention point.
     */
    private createIntervention;
    /**
     * Register intervention and start timeout.
     */
    private registerIntervention;
    /**
     * Handle intervention timeout.
     */
    private handleTimeout;
    /**
     * Handle option-specific action.
     */
    private handleOptionAction;
    /**
     * Get max confidence difference among directions.
     */
    private getMaxConfidenceDiff;
}
/**
 * Create an intervention controller instance.
 */
export declare function createInterventionController(config?: Partial<InterventionConfig>): InterventionController;
export default InterventionController;
//# sourceMappingURL=interventionController.d.ts.map