/**
 * AI Failure to Human Escalation Integration
 *
 * This module provides primitives for integrating AI failures with human escalation:
 * - AIFailureClassifier: Classify AI errors into categories and map to escalation tiers
 * - ContextSanitizer: Extract and sanitize context for human review
 * - AutoEscalationTrigger: Trigger escalation based on failure patterns
 * - EscalationRouter: Route failures to appropriate human reviewers
 */
import type { Priority, ReviewResponse } from './types.js';
import type { HumanManager } from './human.js';
/**
 * Failure category
 */
export type FailureCategory = 'recoverable' | 'critical' | 'unknown';
/**
 * Failure severity levels
 */
export type FailureSeverity = 'low' | 'medium' | 'high' | 'critical';
/**
 * Cascade tier identifier (string union type for simplified tier references)
 */
export type CascadeTierId = 'code' | 'generative' | 'agentic' | 'human';
/**
 * AI failure information
 */
export interface AIFailure {
    /** Error code */
    code: string;
    /** Error message */
    message: string;
    /** When the failure occurred */
    timestamp: Date;
    /** Additional context */
    context?: Record<string, unknown>;
    /** Original error object */
    error?: Error;
}
/**
 * Custom failure type configuration
 */
export interface FailureTypeConfig {
    /** Failure code */
    code: string;
    /** Tier to route to */
    tier: CascadeTierId;
    /** Category */
    category: FailureCategory;
    /** Severity */
    severity: FailureSeverity;
    /** Description */
    description?: string;
}
/**
 * Category rule function
 */
export type CategoryRule = (failure: AIFailure) => boolean;
/**
 * Sanitized context for human review
 */
export interface SanitizedContext {
    failureCode?: string;
    failureMessage?: string;
    model?: string;
    requestId?: string;
    stackTrace?: string;
    timestamp?: Date;
    environment?: string;
    correlationId?: string;
    [key: string]: unknown;
}
/**
 * Escalation configuration
 */
export interface EscalationConfig {
    /** Number of consecutive failures before escalation */
    consecutiveFailureThreshold?: number;
    /** Failure rate threshold (0-1) */
    failureRateThreshold?: number;
    /** Minimum sample size for rate calculation */
    minSampleSize?: number;
    /** Time window in milliseconds */
    windowMs: number;
    /** Cooldown period after escalation */
    cooldownMs?: number;
    /** Per-error-code thresholds */
    thresholds?: Record<string, {
        consecutiveFailureThreshold?: number;
        failureRateThreshold?: number;
    }>;
    /** Callback when escalation is triggered */
    onEscalation?: (event: EscalationEvent) => void;
    /** Routing rules for escalation */
    routingRules?: Array<{
        pattern: RegExp;
        tier: CascadeTierId;
    }>;
}
/**
 * Escalation event emitted when escalation is triggered
 */
export interface EscalationEvent {
    /** Failure code that triggered escalation */
    failureCode: string;
    /** Number of failures */
    failureCount: number;
    /** When escalation was triggered */
    triggeredAt: Date;
    /** Recent failures */
    recentFailures: FailureRecord[];
}
/**
 * Record of a failure for tracking
 */
export interface FailureRecord {
    /** Failure code */
    code: string;
    /** Request ID */
    requestId: string;
    /** Timestamp */
    timestamp: Date;
    /** Whether it was a success */
    success: boolean;
    /** Additional context */
    context?: Record<string, unknown>;
}
/**
 * Escalation route information
 */
export interface EscalationRoute {
    /** Target tier */
    tier: CascadeTierId;
    /** Reason for routing */
    reason?: string;
}
/**
 * Human reviewer configuration
 */
export interface ReviewerConfig {
    /** Reviewer ID */
    id: string;
    /** Reviewer name */
    name: string;
    /** Tiers this reviewer can handle */
    tiers: CascadeTierId[];
    /** Capabilities */
    capabilities?: string[];
    /** Whether reviewer is available */
    available?: boolean;
    /** Whether reviewer is on-call */
    isOnCall?: boolean;
}
/**
 * Routing metrics
 */
export interface RoutingMetrics {
    /** Metrics by tier */
    byTier: Record<string, {
        routingCount: number;
    }>;
    /** Metrics by reviewer */
    byReviewer: Record<string, {
        assignmentCount: number;
    }>;
}
/**
 * Escalation request parameters
 */
export interface EscalationRequestParams {
    /** The AI failure */
    failure: AIFailure;
    /** Target tier */
    tier: CascadeTierId;
    /** Priority */
    priority: Priority;
    /** Request title */
    title?: string;
    /** Request description */
    description?: string;
}
/**
 * Created escalation request
 */
export interface CreatedEscalationRequest {
    /** Request ID */
    id: string;
    /** Request type */
    type: 'review';
    /** Priority */
    priority: Priority;
    /** Assignee ID */
    assignee: string;
    /** Metadata */
    metadata?: Record<string, unknown>;
}
/**
 * Classifies AI failures into categories and maps them to escalation tiers
 */
export declare class AIFailureClassifier {
    private tierMappings;
    private categoryMappings;
    private severityMappings;
    private categoryRules;
    private failureTracker;
    private frequencyThreshold;
    constructor();
    /**
     * Map an AI error code to an escalation tier
     */
    mapToTier(code: string): CascadeTierId | undefined;
    /**
     * Register a custom mapping from error code to tier
     */
    registerMapping(code: string, tier: CascadeTierId): void;
    /**
     * Categorize a failure
     */
    categorize(failure: AIFailure): FailureCategory;
    /**
     * Register a custom category rule
     */
    registerCategoryRule(rule: CategoryRule, category: FailureCategory): void;
    /**
     * Assess the severity of a failure
     */
    assessSeverity(failure: AIFailure, options?: {
        checkFrequency?: boolean;
    }): FailureSeverity;
    /**
     * Track a failure for frequency analysis
     */
    trackFailure(failure: AIFailure): void;
    /**
     * Register a custom failure type with full configuration
     */
    registerFailureType(config: FailureTypeConfig): void;
    /**
     * Unregister a failure type
     */
    unregisterFailureType(code: string): void;
    /**
     * List all registered failure types
     */
    listFailureTypes(): string[];
}
/**
 * Options for ContextSanitizer
 */
export interface ContextSanitizerOptions {
    /** Whether to redact email addresses */
    redactEmails?: boolean;
}
/**
 * Sanitizes context data before human review by removing sensitive information
 */
export declare class ContextSanitizer {
    private options;
    private customPatterns;
    constructor(options?: ContextSanitizerOptions);
    /**
     * Extract relevant context from an AI failure
     */
    extractContext(failure: AIFailure, options?: {
        includeStackTrace?: boolean;
    }): SanitizedContext;
    /**
     * Sanitize context by redacting sensitive data
     */
    sanitize<T extends Record<string, unknown>>(context: T): T;
    /**
     * Recursively sanitize a value
     */
    private sanitizeValue;
    /**
     * Check if a key is sensitive
     */
    private isSensitiveKey;
    /**
     * Sanitize a string by replacing patterns
     */
    private sanitizeString;
    /**
     * Add a custom redaction pattern
     */
    addRedactionPattern(pattern: RegExp, name: string): void;
    /**
     * Enrich context with metadata
     */
    enrich<T extends Record<string, unknown>>(context: T, options?: {
        includeEnvironment?: boolean;
        environment?: string;
        correlationId?: string;
    }): T & {
        timestamp: Date;
        requestId: string;
        environment?: string;
        correlationId?: string;
    };
    /**
     * Generate a unique request ID
     */
    private generateRequestId;
}
/**
 * Triggers escalation based on failure patterns and thresholds
 */
export declare class AutoEscalationTrigger {
    private config;
    private failureRecords;
    private cooldowns;
    /**
     * Configure the escalation trigger
     */
    configure(config: EscalationConfig): void;
    /**
     * Record a failure
     */
    recordFailure(params: {
        code: string;
        requestId: string;
        context?: Record<string, unknown>;
    }): void;
    /**
     * Record a success
     * For consecutive failure threshold: resets the failure streak
     * For rate-based threshold: adds a success record to calculate rate
     */
    recordSuccess(params: {
        code: string;
        requestId: string;
    }): void;
    /**
     * Check if escalation should be triggered
     */
    shouldEscalate(code: string): boolean;
    /**
     * Get records within the time window
     */
    private getRecentRecords;
    /**
     * Get threshold for a specific code
     */
    private getThresholdForCode;
    /**
     * Acknowledge escalation (starts cooldown)
     */
    acknowledgeEscalation(code: string): void;
    /**
     * Check and trigger escalation
     */
    checkAndEscalate(code: string): void;
    /**
     * Get escalation route based on routing rules
     */
    getEscalationRoute(code: string): EscalationRoute | undefined;
}
/**
 * Routes AI failures to appropriate human reviewers
 */
export declare class EscalationRouter {
    private reviewers;
    private metrics;
    private humanManager?;
    /**
     * Set the HumanManager for request creation
     */
    setHumanManager(manager: HumanManager): void;
    /**
     * Register a human reviewer
     */
    registerReviewer(config: ReviewerConfig): void;
    /**
     * Get reviewers for a specific tier
     */
    getReviewersForTier(tier: CascadeTierId): ReviewerConfig[];
    /**
     * Get reviewers by capability
     */
    getReviewersByCapability(capability: string): ReviewerConfig[];
    /**
     * Get available reviewers for a tier
     */
    getAvailableReviewers(tier: CascadeTierId): ReviewerConfig[];
    /**
     * Create an escalation request
     */
    createEscalationRequest(params: EscalationRequestParams): Promise<CreatedEscalationRequest>;
    /**
     * Escalate for human review using HumanManager
     */
    escalateForReview(params: EscalationRequestParams): Promise<ReviewResponse | undefined>;
    /**
     * Record a routing event
     */
    recordRouting(tier: string, reviewerId: string): void;
    /**
     * Get routing metrics
     */
    getMetrics(): RoutingMetrics;
}
//# sourceMappingURL=ai-failure-escalation.d.ts.map