ralph-workflow 0.7.18

PROMPT-driven multi-agent orchestrator for git repos
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

// Prefix debouncing for streaming display.
//
// Contains StreamingConfig and PrefixDebouncer (test-only).

/// Configuration for streaming display behavior.
///
/// This struct allows customization of streaming output features like
/// prefix debouncing and multi-line handling.
///
/// Default values:
/// - `prefix_delta_threshold`: 0 (disable count-based repetition; first delta still shows prefix)
/// - `prefix_time_threshold`: None (disable time-based repetition)
#[derive(Debug, Clone, Default)]
#[cfg(test)]
pub struct StreamingConfig {
    /// Minimum number of deltas between prefix displays.
    ///
    /// Semantics:
    /// - `0`: disable count-based repetition (prefix is still shown on the first delta)
    /// - `N > 0`: show the prefix every N deltas after the first (i.e., after N suppressed deltas)
    pub prefix_delta_threshold: u32,
    /// Minimum time between prefix displays (None = no time-based debouncing)
    pub prefix_time_threshold: Option<Duration>,
}

/// Controls prefix display frequency during streaming.
///
/// This debouncer reduces visual noise from frequent prefix redisplay during
/// rapid streaming (e.g., character-by-character output). It supports two
/// debouncing strategies:
///
/// 1. **Count-based**: Show prefix every N deltas
/// 2. **Time-based**: Show prefix after M milliseconds since last prefix
///
/// # Example
///
/// ```ignore
/// use std::time::Duration;
///
/// let config = StreamingConfig {
///     prefix_delta_threshold: 5,
///     prefix_time_threshold: Some(Duration::from_millis(100)),
/// };
/// let mut debouncer = PrefixDebouncer::new(config);
///
/// // First delta always shows prefix
/// assert!(debouncer.should_show_prefix(true));
///
/// // Subsequent deltas may skip prefix based on thresholds
/// assert!(!debouncer.should_show_prefix(false)); // Delta 2: skip
/// assert!(!debouncer.should_show_prefix(false)); // Delta 3: skip
/// // ... after threshold reached or time elapsed, prefix shows again
/// ```
#[derive(Debug, Clone)]
#[cfg(test)]
pub struct PrefixDebouncer {
    config: StreamingConfig,
    delta_count: u32,
    last_prefix_time: Option<Instant>,
}

#[cfg(test)]
impl PrefixDebouncer {
    /// Create a new prefix debouncer with the given configuration.
    #[must_use] 
    pub const fn new(config: StreamingConfig) -> Self {
        Self {
            config,
            delta_count: 0,
            last_prefix_time: None,
        }
    }

    /// Reset the debouncer state (e.g., at the start of a new content block).
    pub const fn reset(&mut self) {
        self.delta_count = 0;
        self.last_prefix_time = None;
    }

    /// Determine if the prefix should be shown for the current delta.
    ///
    /// # Arguments
    /// * `is_first_delta` - Whether this is the first delta of a content block
    ///
    /// # Returns
    /// * `true` - Show the prefix
    /// * `false` - Skip the prefix (still perform line clearing)
    pub fn should_show_prefix(&mut self, is_first_delta: bool) -> bool {
        // Always show prefix on first delta
        if is_first_delta {
            self.delta_count = 0;
            self.last_prefix_time = Some(Instant::now());
            return true;
        }

        self.delta_count = self.delta_count.saturating_add(1);

        // Check time-based threshold
        if let Some(threshold) = self.config.prefix_time_threshold {
            if let Some(last_time) = self.last_prefix_time {
                if last_time.elapsed() >= threshold {
                    self.delta_count = 0;
                    self.last_prefix_time = Some(Instant::now());
                    return true;
                }
            }
        }

        // Check count-based threshold
        if self.config.prefix_delta_threshold > 0
            && self.delta_count >= self.config.prefix_delta_threshold
        {
            self.delta_count = 0;
            self.last_prefix_time = Some(Instant::now());
            return true;
        }

        // Default behavior: only first delta shows prefix.
        // With no thresholds configured, subsequent deltas don't show prefix.
        // This preserves the original behavior while allowing opt-in debouncing.
        false
    }
}

#[cfg(test)]
impl Default for PrefixDebouncer {
    fn default() -> Self {
        Self::new(StreamingConfig::default())
    }
}