ralph_workflow/reducer/state/continuation/mod.rs
1//! Continuation state for development and fix iterations.
2//!
3//! This module contains the [`ContinuationState`] structure and associated logic for managing
4//! continuation and retry attempts across development and fix phases.
5//!
6//! # Overview
7//!
8//! The continuation system provides three key mechanisms:
9//!
10//! ## 1. Continuation Context and Budget System
11//!
12//! When agent work is incomplete (status "partial" or "failed" for development,
13//! "`issues_remain`" or "failed" for fix), the system can trigger a **continuation**
14//! to let the agent continue work in the same iteration.
15//!
16//! **Budget limits:**
17//! - Development: `max_continue_count` attempts (default 3)
18//! - Fix: `max_fix_continue_count` attempts (default 10)
19//!
20//! **Context tracking:**
21//! - Previous status, summary, files changed, next steps
22//! - Continuation attempt counter
23//! - Context file write/cleanup flags
24//!
25//! **Budget exhaustion triggers:**
26//! - When `continuation_attempt >= max_continue_count`, no more continuations allowed
27//! - System proceeds to next phase even if work is incomplete
28//!
29//! ## 2. Retry Mechanisms
30//!
31//! The system supports two types of retries when agent invocations fail:
32//!
33//! ### XSD Retries
34//!
35//! Triggered when agent output fails XML parsing or XSD validation:
36//! - Budget: `max_xsd_retry_count` (default 10)
37//! - Behavior: Re-invoke same agent with validation error feedback
38//! - Session reuse: Preserves provider-side context for deterministic retries
39//! - Exhaustion: Falls back to next agent in chain
40//!
41//! ### Same-Agent Retries
42//!
43//! Triggered for transient invocation failures (timeout, internal error):
44//! - Budget: `max_same_agent_retry_count` (default 2)
45//! - Behavior: Re-invoke same agent with reduced scope guidance
46//! - Exhaustion: Falls back to next agent in chain
47//!
48//! ## 3. Loop Detection Mechanism
49//!
50//! Prevents infinite tight loops by tracking consecutive identical effects:
51//!
52//! **Effect fingerprinting:**
53//! - Each effect execution is fingerprinted (e.g., "InvokeAgent(Developer, continuation=2)")
54//! - System tracks `last_effect_kind` and `consecutive_same_effect_count`
55//!
56//! **Detection threshold:**
57//! - `max_consecutive_same_effect` (default 100, see [`DEFAULT_LOOP_DETECTION_THRESHOLD`])
58//! - When threshold is exceeded, triggers loop recovery
59//!
60//! **Recovery behavior:**
61//! - Resets continuation state (including loop counters)
62//! - Advances to next agent or phase to break the cycle
63//!
64//! # State Immutability
65//!
66//! This is **pure state code** with no side effects:
67//! - All methods return new `ContinuationState` instances
68//! - No I/O operations (filesystem, environment, logging)
69//! - No external dependencies beyond serde for serialization
70//!
71//! # Module Structure
72//!
73//! - [`state`]: Core `ContinuationState` struct definition
74//! - [`budget`]: Budget tracking and exhaustion checking
75//! - [`loop_detection`]: Loop detection and effect fingerprinting
76
77mod budget;
78mod loop_detection;
79mod state;
80
81pub use state::{ContinuationState, DEFAULT_LOOP_DETECTION_THRESHOLD};