ralph_workflow/reducer/event/awaiting_dev_fix.rs
1//! Events for `AwaitingDevFix` phase.
2//!
3//! This phase handles pipeline failure remediation with escalating recovery strategies.
4
5use crate::agents::AgentRole;
6use serde::{Deserialize, Serialize};
7
8// Import PipelinePhase from the parent event module (defined in mod.rs)
9use crate::reducer::event::PipelinePhase;
10
11/// Events for `AwaitingDevFix` phase.
12///
13/// This phase handles pipeline failure remediation with escalating recovery strategies.
14///
15/// # When This Occurs
16///
17/// The `AwaitingDevFix` phase is entered when the pipeline encounters a terminal
18/// failure condition (e.g., agent chain exhausted) in any phase. The pipeline
19/// implements an aggressive recovery system with escalating strategies rather
20/// than immediate termination.
21///
22/// # State Flow (Updated)
23///
24/// 1. Terminal failure detected (e.g., `AgentChainExhausted`)
25/// 2. Reducer transitions to `AwaitingDevFix` phase
26/// 3. `DevFixTriggered` event emitted
27/// 4. Development agent invoked with failure context
28/// 5. `DevFixCompleted` event emitted (attempt count incremented, level set)
29/// 6. `RecoveryAttempted` event transitions back to failed phase
30/// 7. Recovery attempt (retry same operation, or escalate to phase reset, etc.)
31/// 8. If recovery fails, repeat steps 3-7 with escalating strategies:
32/// - Level 1 (attempts 1-3): Retry same operation
33/// - Level 2 (attempts 4-6): Reset to phase start
34/// - Level 3 (attempts 7-9): Reset iteration counter
35/// - Level 4 (attempts 10+): Reset to iteration 0
36/// 9. Recovery is intentionally non-terminating for unattended operation.
37/// Completion markers / termination are reserved for explicit safety valve or
38/// catastrophic external paths (not attempt-count based escalation).
39///
40/// # Emitted By
41///
42/// - Dev-fix flow handlers in `handler/lifecycle.rs`
43/// - Recovery handlers in `handler/context.rs`
44/// - Completion marker handlers
45#[derive(Clone, Serialize, Deserialize, Debug)]
46pub enum AwaitingDevFixEvent {
47 /// Dev-fix flow was triggered.
48 ///
49 /// Emitted when entering the dev-fix phase. Records which phase and agent
50 /// failed, providing context for the development agent.
51 DevFixTriggered {
52 /// Phase where the failure occurred.
53 failed_phase: PipelinePhase,
54 /// Agent role that failed.
55 failed_role: AgentRole,
56 },
57 /// Dev-fix flow was skipped (not yet implemented or disabled).
58 DevFixSkipped {
59 /// Reason for skipping.
60 reason: String,
61 },
62 /// Dev-fix flow completed (may or may not have fixed the issue).
63 ///
64 /// Emitted after the development agent finishes its fix attempt.
65 /// The `success` field indicates whether the agent believes it fixed
66 /// the issue, but does not guarantee the pipeline will succeed on retry.
67 DevFixCompleted {
68 /// Whether the fix attempt succeeded.
69 success: bool,
70 /// Optional summary of what was fixed.
71 summary: Option<String>,
72 },
73 /// Dev-fix agent is unavailable (quota/usage limit).
74 ///
75 /// Emitted when the dev-fix agent cannot be invoked due to resource limits.
76 /// The pipeline stays in the recovery loop without a fix attempt so unattended
77 /// execution remains non-terminating by default.
78 DevFixAgentUnavailable {
79 /// Phase where the failure occurred.
80 failed_phase: PipelinePhase,
81 /// Reason for unavailability.
82 reason: String,
83 },
84 /// Completion marker was emitted to filesystem.
85 ///
86 /// Emitted after writing the completion marker to `.agent/tmp/completion_marker`.
87 /// The reducer uses this event to transition from `AwaitingDevFix` to Interrupted,
88 /// enabling the pipeline to complete gracefully.
89 CompletionMarkerEmitted {
90 /// Whether this is a failure completion (true) or success (false).
91 is_failure: bool,
92 },
93 /// Completion marker failed to write to filesystem.
94 ///
95 /// This event is emitted when `EmitCompletionMarkerAndTerminate` attempts to write
96 /// `.agent/tmp/completion_marker` but the workspace write fails.
97 ///
98 /// The reducer must NOT transition to Interrupted in this case so orchestration
99 /// can retry marker emission deterministically.
100 CompletionMarkerWriteFailed {
101 /// Whether this is a failure completion (true) or success (false).
102 is_failure: bool,
103 /// Error message from the underlying workspace write.
104 error: String,
105 },
106 /// Recovery attempt initiated at a specific escalation level.
107 ///
108 /// Emitted when the dev-fix completes and the pipeline is ready to retry.
109 /// The escalation level determines the recovery strategy.
110 RecoveryAttempted {
111 /// The recovery escalation level being attempted (1-4).
112 level: u32,
113 /// Number of recovery attempts so far for this failure.
114 attempt_count: u32,
115 /// Phase to resume work in after applying recovery policy.
116 ///
117 /// This is carried from the effect parameters so the reducer does not
118 /// need to trust potentially-stale `failed_phase_for_recovery` when
119 /// applying the reset.
120 target_phase: PipelinePhase,
121 },
122 /// Recovery escalated to a higher level.
123 ///
124 /// Emitted when a recovery attempt fails and we escalate to a more
125 /// aggressive recovery strategy (e.g., from retry → phase reset).
126 RecoveryEscalated {
127 /// Previous escalation level.
128 from_level: u32,
129 /// New escalation level.
130 to_level: u32,
131 /// Reason for escalation.
132 reason: String,
133 },
134 /// Recovery succeeded - pipeline can resume normal operation.
135 ///
136 /// Emitted when a recovery attempt successfully fixes the issue
137 /// (e.g., the retry succeeds, or the reset phase completes).
138 RecoverySucceeded {
139 /// The escalation level that succeeded.
140 level: u32,
141 /// Total attempts before success.
142 total_attempts: u32,
143 },
144}