/**
 * Friction Feedback System
 *
 * Provides clear explanations, actionable next steps, and decision options
 * when AI actions are denied or escalated. Implements FR119-FR122.
 *
 * Part of Epic 3: Friction Feedback System
 *
 * @packageDocumentation
 */
import type { ID, TrustLevel, TrustScore } from '../common/types.js';
import type { Decision } from '../common/types.js';
/**
 * Denial reason categories for clear messaging
 */
export declare const DenialReasonCategory: {
    readonly TRUST_INSUFFICIENT: "trust_insufficient";
    readonly POLICY_VIOLATION: "policy_violation";
    readonly CAPABILITY_RESTRICTED: "capability_restricted";
    readonly RATE_LIMITED: "rate_limited";
    readonly RESOURCE_UNAVAILABLE: "resource_unavailable";
    readonly ESCALATION_REQUIRED: "escalation_required";
    readonly CONTEXT_INVALID: "context_invalid";
    readonly PERMISSION_DENIED: "permission_denied";
};
export type DenialReasonCategory = (typeof DenialReasonCategory)[keyof typeof DenialReasonCategory];
/**
 * Severity level of the denial
 */
export declare const DenialSeverity: {
    readonly LOW: "low";
    readonly MEDIUM: "medium";
    readonly HIGH: "high";
    readonly CRITICAL: "critical";
};
export type DenialSeverity = (typeof DenialSeverity)[keyof typeof DenialSeverity];
/**
 * Action type for next steps
 */
export declare const NextStepAction: {
    readonly REQUEST_ESCALATION: "request_escalation";
    readonly MODIFY_PARAMETERS: "modify_parameters";
    readonly WAIT_RETRY: "wait_retry";
    readonly CONTACT_ADMIN: "contact_admin";
    readonly INCREASE_TRUST: "increase_trust";
    readonly REQUEST_CAPABILITY: "request_capability";
    readonly PROVIDE_CONTEXT: "provide_context";
    readonly ACKNOWLEDGE: "acknowledge";
};
export type NextStepAction = (typeof NextStepAction)[keyof typeof NextStepAction];
/**
 * Human-readable denial explanation
 */
export interface DenialExplanation {
    /** Short, clear summary of why the action was denied */
    summary: string;
    /** Detailed explanation with context */
    details: string;
    /** Category of denial for routing */
    category: DenialReasonCategory;
    /** Severity level */
    severity: DenialSeverity;
    /** The specific policy or rule that triggered denial */
    triggeringRule?: {
        id: string;
        name: string;
        description?: string;
    };
    /** Trust context if relevant */
    trustContext?: {
        currentScore: TrustScore;
        currentLevel: TrustLevel;
        requiredLevel?: TrustLevel;
        requiredScore?: TrustScore;
        gap?: number;
    };
    /** Timestamp of denial */
    occurredAt: string;
    /** Unique identifier for this explanation */
    explanationId: string;
}
/**
 * Actionable next step
 */
export interface NextStep {
    /** Action identifier */
    action: NextStepAction;
    /** Human-readable label */
    label: string;
    /** Detailed description of what this action does */
    description: string;
    /** Is this step recommended? */
    recommended: boolean;
    /** Priority (1 = highest) */
    priority: number;
    /** Estimated time to complete (human-readable) */
    estimatedTime?: string;
    /** Prerequisites or conditions */
    prerequisites?: string[];
    /** Link or route to take action (for UI) */
    actionUrl?: string;
    /** Additional parameters for the action */
    parameters?: Record<string, unknown>;
}
/**
 * Decision option for human reviewers
 */
export interface DecisionOption {
    /** Decision identifier */
    id: string;
    /** Action type */
    action: 'approve' | 'reject' | 'escalate' | 'request_info' | 'defer';
    /** Display label */
    label: string;
    /** Description of consequences */
    consequence: string;
    /** Severity/impact indicator */
    impact: 'low' | 'medium' | 'high';
    /** Is this the default/recommended option? */
    isDefault: boolean;
    /** Require confirmation before executing? */
    requiresConfirmation: boolean;
    /** Required fields for this decision */
    requiredFields?: string[];
}
/**
 * Complete friction feedback response
 */
export interface FrictionFeedback {
    /** Unique feedback identifier */
    feedbackId: string;
    /** Related intent ID */
    intentId: ID;
    /** Related agent ID */
    agentId: ID;
    /** Denial explanation */
    explanation: DenialExplanation;
    /** Available next steps */
    nextSteps: NextStep[];
    /** Decision options (for escalations) */
    decisionOptions?: DecisionOption[];
    /** Generated at timestamp */
    generatedAt: string;
    /** Feedback version for evolution tracking */
    version: string;
}
/**
 * Agent understanding signal
 */
export interface AgentUnderstandingSignal {
    /** Signal identifier */
    signalId: string;
    /** Agent ID */
    agentId: ID;
    /** Related feedback ID */
    feedbackId: string;
    /** Signal type */
    type: 'acknowledged' | 'confused' | 'retried_same' | 'retried_modified' | 'escalated' | 'abandoned';
    /** Timestamp */
    timestamp: string;
    /** Time since denial (ms) */
    responseTimeMs: number;
    /** Additional context */
    context?: Record<string, unknown>;
}
/**
 * Friction feedback generation context
 */
export interface FrictionContext {
    intentId: ID;
    agentId: ID;
    tenantId: ID;
    decision: Decision;
    action: string;
    category?: string;
    parameters?: Record<string, unknown>;
}
export declare const REVIEWER_DECISION_OPTIONS: DecisionOption[];
/**
 * Friction Feedback Service
 *
 * Generates clear, actionable feedback when AI actions are denied or escalated.
 */
export declare class FrictionFeedbackService {
    private understandingSignals;
    /**
     * Generate friction feedback for a denied action
     */
    generateFeedback(context: FrictionContext): FrictionFeedback;
    /**
     * Generate explanation for denial
     */
    private generateExplanation;
    /**
     * Generate next steps based on category
     */
    private generateNextSteps;
    /**
     * Generate decision options for reviewers
     */
    private generateDecisionOptions;
    /**
     * Determine denial category from decision
     */
    private determineCategory;
    /**
     * Determine severity based on context
     */
    private determineSeverity;
    /**
     * Record agent understanding signal (FR122)
     */
    recordUnderstandingSignal(agentId: ID, feedbackId: string, type: AgentUnderstandingSignal['type'], responseTimeMs: number, context?: Record<string, unknown>): AgentUnderstandingSignal;
    /**
     * Get understanding signals for an agent
     */
    getUnderstandingSignals(agentId: ID): AgentUnderstandingSignal[];
    /**
     * Analyze understanding patterns for an agent
     */
    analyzeUnderstandingPatterns(agentId: ID): {
        totalSignals: number;
        acknowledgedRate: number;
        confusionRate: number;
        retryRate: number;
        abandonmentRate: number;
        avgResponseTimeMs: number;
        recommendations: string[];
    };
}
/**
 * Create a new friction feedback service
 */
export declare function createFrictionFeedbackService(): FrictionFeedbackService;
//# sourceMappingURL=index.d.ts.map