packages/frontend/lib/features/agent/models/agent_validation.dart

import 'agent_automation.dart';

/// Environment gate that prevented an agent run from finalizing.
enum AgentValidationBlockerKind {
  dependency,
  analyzer,
  analyzerFreshness,
  preview,
}

/// Metadata for the gate that blocked a candidate final response.
class AgentValidationBlocker {
  const AgentValidationBlocker._({
    required this.kind,
    required this.repairPrompt,
    this.analyzerFreshnessGeneration,
  });

  factory AgentValidationBlocker.dependency({
    required String repairPrompt,
  }) {
    return AgentValidationBlocker._(
      kind: AgentValidationBlockerKind.dependency,
      repairPrompt: repairPrompt,
    );
  }

  factory AgentValidationBlocker.analyzer({
    required String repairPrompt,
  }) {
    return AgentValidationBlocker._(
      kind: AgentValidationBlockerKind.analyzer,
      repairPrompt: repairPrompt,
    );
  }

  factory AgentValidationBlocker.analyzerFreshness({
    required String repairPrompt,
    int? generation,
  }) {
    return AgentValidationBlocker._(
      kind: AgentValidationBlockerKind.analyzerFreshness,
      repairPrompt: repairPrompt,
      analyzerFreshnessGeneration: generation,
    );
  }

  factory AgentValidationBlocker.preview({
    required String repairPrompt,
  }) {
    return AgentValidationBlocker._(
      kind: AgentValidationBlockerKind.preview,
      repairPrompt: repairPrompt,
    );
  }

  /// Gate responsible for blocking finalization.
  final AgentValidationBlockerKind kind;

  /// Focused instruction injected when validation failed.
  final String repairPrompt;

  /// Mutation generation whose analyzer freshness validation timed out.
  final int? analyzerFreshnessGeneration;
}

/// Outcome of validating a candidate final response against the workspace.
class AgentValidationResult {
  const AgentValidationResult._({
    required this.passed,
    required this.automationResults,
    this.blocker,
  });

  /// Creates a successful validation result.
  factory AgentValidationResult.passed({
    required List<AgentAutomationResult> automationResults,
  }) {
    return AgentValidationResult._(
      passed: true,
      automationResults: automationResults,
    );
  }

  /// Creates a blocked validation result with feedback for the next model step.
  factory AgentValidationResult.blocked({
    required List<AgentAutomationResult> automationResults,
    required AgentValidationBlocker blocker,
  }) {
    return AgentValidationResult._(
      passed: false,
      automationResults: automationResults,
      blocker: blocker,
    );
  }

  /// Whether every required environment gate passed.
  final bool passed;

  /// Automatic actions performed while validating the candidate response.
  final List<AgentAutomationResult> automationResults;

  /// Gate-specific blocker details when validation failed.
  final AgentValidationBlocker? blocker;
}