// @lifecycle canonical - Shell verification gate type definitions for Ralph Wiggum loops.
/**
 * Shell Verification Gate Types
 *
 * Type definitions for shell-based verification gates that enable
 * "Ralph Wiggum" style autonomous loops where Claude's work is validated
 * by real shell command execution (ground truth) rather than LLM self-evaluation.
 *
 * @see plans/ralph-style-loop.md for the implementation plan
 */

/**
 * Configuration for a shell verification gate.
 *
 * Defines the shell command to execute for validation along with
 * execution parameters like timeout and working directory.
 *
 * Options:
 * - max: Maximum attempts (default: 5)
 * - timeout: Command timeout in seconds (default: 300)
 * - loop: Enable Stop hook integration for autonomous loops
 *
 * Presets (apply with :fast, :full, :extended):
 * - :fast     → max:1, timeout:30   (quick feedback)
 * - :full     → max:5, timeout:300  (CI-style)
 * - :extended → max:10, timeout:600 (long tests)
 *
 * Checkpoint/rollback functionality is available via resource_manager.
 */
export interface ShellVerifyGate {
  /** The shell command to execute for verification */
  command: string;
  /** Working directory for command execution (defaults to project root) */
  workingDir?: string;
  /** Timeout in milliseconds (defaults to SHELL_VERIFY_DEFAULT_TIMEOUT) */
  timeout?: number;
  /** Additional environment variables for the command */
  env?: Record<string, string>;
  /**
   * Content piped to the command's stdin. When the gate.yaml criterion sets
   * `shell_stdin_source: 'agent_response'`, the runner populates this with the
   * (possibly truncated) agent response from the current execution context.
   * Scripts can then parse claims from stdin and verify against ground truth.
   */
  stdin?: string;

  // === Ralph Loop Options ===

  /** Enable Stop hook integration for autonomous loops (default: false) */
  loop?: boolean;
  /** Maximum iterations before force-stop (default: 5, or preset value) */
  maxIterations?: number;
  /** Applied preset name (:fast, :full, :extended) - sets max and timeout */
  preset?: 'fast' | 'full' | 'extended';
}

/**
 * Result of executing a shell verification command.
 *
 * Contains all information needed to determine pass/fail status
 * and provide diagnostic feedback to Claude.
 */
export interface ShellVerifyResult {
  /** Whether the verification passed (exit code 0) */
  passed: boolean;
  /** Process exit code (0 = pass, non-zero = fail) */
  exitCode: number;
  /** Standard output from the command */
  stdout: string;
  /** Standard error from the command */
  stderr: string;
  /** Execution duration in milliseconds */
  durationMs: number;
  /** The command that was executed */
  command: string;
  /** Whether the command timed out */
  timedOut?: boolean;
}

/**
 * Pending shell verification state tracked during chain execution.
 *
 * Persisted across responses to track retry attempts and
 * accumulate results from multiple verification runs.
 */
export interface PendingShellVerification {
  /** The shell verification gate configuration */
  shellVerify: ShellVerifyGate;
  /** Results from previous verification attempts */
  previousResults: ShellVerifyResult[];
  /** Current attempt count (1-indexed) */
  attemptCount: number;
  /** Maximum attempts before escalation */
  maxAttempts: number;
  /** Unique identifier for this verification gate */
  gateId: string;
  /** Original user goal/request for context-isolated loops */
  originalGoal?: string;
  /** Gate IDs that triggered this shell verification (from gate.yaml shell_verify criteria) */
  sourceGateIds?: string[];
}

/**
 * Shell verification executor configuration.
 */
export interface ShellVerifyExecutorConfig {
  /** Default timeout in milliseconds */
  defaultTimeout?: number;
  /** Maximum allowed timeout in milliseconds */
  maxTimeout?: number;
  /** Default working directory for command execution */
  defaultWorkingDir?: string;
  /** Enable debug logging */
  debug?: boolean;
}

/**
 * Maximum characters to include from command output.
 * Large outputs are truncated to prevent context overflow.
 */
export const SHELL_OUTPUT_MAX_CHARS = 5000;

/**
 * Default max iterations for autonomous loops.
 */
export const SHELL_VERIFY_DEFAULT_MAX_ITERATIONS = 10;

/**
 * State persisted to runtime-state/verify-state.db for Stop hook integration.
 *
 * This enables the Stop hook to read verification config set by prompt_engine
 * and run verification when Claude tries to stop, creating autonomous loops.
 */
export interface VerifyActiveState {
  /** Chain session ID for tracking */
  sessionId: string;
  /** Configuration from :: verify:"cmd" syntax */
  config: {
    command: string;
    timeout: number;
    maxIterations: number;
    workingDir?: string;
    preset?: 'fast' | 'full' | 'extended';
    /** Original user goal for context-isolated loops */
    originalGoal?: string;
  };
  /** Runtime state updated by Stop hook */
  state: {
    iteration: number;
    lastResult: ShellVerifyResult | null;
    startedAt: string;
  };
}
