Skip to main content

kiss_workflow/
progress.rs

1//! Live run state and the snapshots a user interface renders.
2//!
3//! State changes bump a version counter published on a `watch` channel. A
4//! viewer subscribes and redraws only when the version moves, so nothing polls.
5//! Snapshots are built at most once per change and shared behind an `Arc`.
6
7use crate::runner::AgentId;
8use std::sync::{Arc, Mutex};
9use std::time::{Duration, Instant};
10use tokio::sync::{Notify, watch};
11use tokio_util::sync::CancellationToken;
12
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum RunStatus {
15    Running,
16    Paused,
17    Completed,
18    Failed,
19    Stopped,
20}
21
22impl RunStatus {
23    pub fn is_finished(self) -> bool {
24        matches!(
25            self,
26            RunStatus::Completed | RunStatus::Failed | RunStatus::Stopped
27        )
28    }
29
30    pub fn label(self) -> &'static str {
31        match self {
32            RunStatus::Running => "running",
33            RunStatus::Paused => "paused",
34            RunStatus::Completed => "completed",
35            RunStatus::Failed => "failed",
36            RunStatus::Stopped => "stopped",
37        }
38    }
39}
40
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub enum AgentStatus {
43    Queued,
44    Running,
45    Completed,
46    Failed,
47    Stopped,
48    /// Replayed from a previous run rather than started again.
49    Reused,
50    /// The user asked for a new attempt, and the active call is stopping.
51    Restarting,
52}
53
54impl AgentStatus {
55    pub fn is_finished(self) -> bool {
56        !matches!(
57            self,
58            AgentStatus::Queued | AgentStatus::Running | AgentStatus::Restarting
59        )
60    }
61
62    pub fn label(self) -> &'static str {
63        match self {
64            AgentStatus::Queued => "queued",
65            AgentStatus::Running => "running",
66            AgentStatus::Completed => "completed",
67            AgentStatus::Failed => "failed",
68            AgentStatus::Stopped => "stopped",
69            AgentStatus::Reused => "reused",
70            AgentStatus::Restarting => "restarting",
71        }
72    }
73}
74
75/// One agent as shown in the progress view.
76#[derive(Debug, Clone)]
77pub struct AgentSnapshot {
78    pub id: AgentId,
79    pub label: String,
80    pub status: AgentStatus,
81    pub tokens: u64,
82    pub elapsed: Duration,
83    pub prompt: String,
84    pub result: Option<String>,
85    pub error: Option<String>,
86}
87
88/// One phase, with its agents.
89#[derive(Debug, Clone)]
90pub struct PhaseSnapshot {
91    pub title: String,
92    pub agents: Vec<AgentSnapshot>,
93    pub tokens: u64,
94}
95
96impl PhaseSnapshot {
97    pub fn finished_agents(&self) -> usize {
98        self.agents
99            .iter()
100            .filter(|agent| agent.status.is_finished())
101            .count()
102    }
103}
104
105/// The whole run as shown in the progress view.
106#[derive(Debug, Clone)]
107pub struct RunSnapshot {
108    pub status: RunStatus,
109    pub elapsed: Duration,
110    pub log: Vec<String>,
111    pub phases: Vec<PhaseSnapshot>,
112    pub tokens: u64,
113    pub error: Option<String>,
114}
115
116impl RunSnapshot {
117    pub fn total_agents(&self) -> usize {
118        self.phases.iter().map(|phase| phase.agents.len()).sum()
119    }
120
121    pub fn finished_agents(&self) -> usize {
122        self.phases.iter().map(PhaseSnapshot::finished_agents).sum()
123    }
124
125    /// The phase with work in flight, or the last one that has any agents.
126    pub fn active_phase(&self) -> Option<&PhaseSnapshot> {
127        self.phases
128            .iter()
129            .find(|phase| phase.agents.iter().any(|agent| !agent.status.is_finished()))
130            .or_else(|| {
131                self.phases
132                    .iter()
133                    .rev()
134                    .find(|phase| !phase.agents.is_empty())
135            })
136    }
137}
138
139struct AgentRecord {
140    id: AgentId,
141    label: String,
142    status: AgentStatus,
143    tokens: u64,
144    started: Option<Instant>,
145    elapsed: Duration,
146    prompt: String,
147    result: Option<String>,
148    error: Option<String>,
149    cancel: CancellationToken,
150}
151
152struct PhaseRecord {
153    title: String,
154    agents: Vec<AgentRecord>,
155}
156
157struct Inner {
158    status: RunStatus,
159    started: Instant,
160    finished: Option<Instant>,
161    log: Vec<String>,
162    phases: Vec<PhaseRecord>,
163    current_phase: usize,
164    error: Option<String>,
165}
166
167/// The live state of one run.
168pub(crate) struct RunState {
169    inner: Mutex<Inner>,
170    version: watch::Sender<u64>,
171    /// The snapshot for the current version, built on first request.
172    cached: Mutex<Option<(u64, Arc<RunSnapshot>)>>,
173    resumed: Notify,
174    stop: CancellationToken,
175}
176
177/// The phase used before a script calls `phase()`.
178pub(crate) const DEFAULT_PHASE: &str = "Workflow";
179
180impl RunState {
181    pub(crate) fn new(declared_phases: &[String]) -> Arc<RunState> {
182        let mut phases: Vec<PhaseRecord> = declared_phases
183            .iter()
184            .map(|title| PhaseRecord {
185                title: title.clone(),
186                agents: Vec::new(),
187            })
188            .collect();
189        if phases.is_empty() {
190            phases.push(PhaseRecord {
191                title: DEFAULT_PHASE.to_string(),
192                agents: Vec::new(),
193            });
194        }
195        let (version, _) = watch::channel(0);
196        Arc::new(RunState {
197            inner: Mutex::new(Inner {
198                status: RunStatus::Running,
199                started: Instant::now(),
200                finished: None,
201                log: Vec::new(),
202                phases,
203                current_phase: 0,
204                error: None,
205            }),
206            version,
207            cached: Mutex::new(None),
208            resumed: Notify::new(),
209            stop: CancellationToken::new(),
210        })
211    }
212
213    pub(crate) fn stop_token(&self) -> CancellationToken {
214        self.stop.clone()
215    }
216
217    pub fn subscribe(&self) -> watch::Receiver<u64> {
218        self.version.subscribe()
219    }
220
221    fn changed(&self) {
222        if let Ok(mut cached) = self.cached.lock() {
223            *cached = None;
224        }
225        self.version
226            .send_modify(|version| *version = version.wrapping_add(1));
227    }
228
229    /// Select the phase later agents belong to, adding it when it is new.
230    pub(crate) fn set_phase(&self, title: &str) {
231        let Ok(mut inner) = self.inner.lock() else {
232            return;
233        };
234        match inner.phases.iter().position(|phase| phase.title == title) {
235            Some(index) => inner.current_phase = index,
236            None => {
237                inner.phases.push(PhaseRecord {
238                    title: title.to_string(),
239                    agents: Vec::new(),
240                });
241                inner.current_phase = inner.phases.len() - 1;
242            }
243        }
244        drop(inner);
245        self.changed();
246    }
247
248    pub(crate) fn current_phase_title(&self) -> String {
249        let Ok(inner) = self.inner.lock() else {
250            return DEFAULT_PHASE.to_string();
251        };
252        inner
253            .phases
254            .get(inner.current_phase)
255            .map(|phase| phase.title.clone())
256            .unwrap_or_else(|| DEFAULT_PHASE.to_string())
257    }
258
259    pub(crate) fn log(&self, message: String) {
260        if let Ok(mut inner) = self.inner.lock() {
261            inner.log.push(message);
262        }
263        self.changed();
264    }
265
266    /// Register an agent before it starts, returning the token that stops it.
267    pub(crate) fn register_agent(
268        &self,
269        id: AgentId,
270        label: String,
271        prompt: String,
272    ) -> CancellationToken {
273        let cancel = self.stop.child_token();
274        if let Ok(mut inner) = self.inner.lock() {
275            let phase = inner.current_phase;
276            if let Some(phase) = inner.phases.get_mut(phase) {
277                phase.agents.push(AgentRecord {
278                    id,
279                    label,
280                    status: AgentStatus::Queued,
281                    tokens: 0,
282                    started: None,
283                    elapsed: Duration::ZERO,
284                    prompt,
285                    result: None,
286                    error: None,
287                    cancel: cancel.clone(),
288                });
289            }
290        }
291        self.changed();
292        cancel
293    }
294
295    pub(crate) fn agent_started(&self, id: AgentId) {
296        self.with_agent(id, |agent| {
297            // A restart that arrived before the call began must survive it.
298            if agent.status != AgentStatus::Restarting {
299                agent.status = AgentStatus::Running;
300            }
301            agent.started = Some(Instant::now());
302        });
303    }
304
305    pub(crate) fn agent_finished(
306        &self,
307        id: AgentId,
308        status: AgentStatus,
309        result: Option<String>,
310        error: Option<String>,
311        tokens: u64,
312    ) {
313        self.with_agent(id, |agent| {
314            agent.status = status;
315            agent.result = result;
316            agent.error = error;
317            agent.tokens = tokens;
318            if let Some(started) = agent.started {
319                agent.elapsed = started.elapsed();
320            }
321        });
322    }
323
324    fn with_agent(&self, id: AgentId, apply: impl FnOnce(&mut AgentRecord)) {
325        if let Ok(mut inner) = self.inner.lock()
326            && let Some(agent) = inner
327                .phases
328                .iter_mut()
329                .flat_map(|phase| phase.agents.iter_mut())
330                .find(|agent| agent.id == id)
331        {
332            apply(agent);
333        }
334        self.changed();
335    }
336
337    pub(crate) fn finish(&self, status: RunStatus, error: Option<String>) {
338        if let Ok(mut inner) = self.inner.lock() {
339            inner.status = status;
340            inner.error = error;
341            inner.finished = Some(Instant::now());
342        }
343        self.changed();
344    }
345
346    // ----- user controls ----------------------------------------------------
347
348    pub fn pause(&self) {
349        if let Ok(mut inner) = self.inner.lock()
350            && inner.status == RunStatus::Running
351        {
352            inner.status = RunStatus::Paused;
353            drop(inner);
354            self.changed();
355        }
356    }
357
358    pub fn resume(&self) {
359        if let Ok(mut inner) = self.inner.lock()
360            && inner.status == RunStatus::Paused
361        {
362            inner.status = RunStatus::Running;
363            drop(inner);
364            self.resumed.notify_waiters();
365            self.changed();
366        }
367    }
368
369    pub fn is_paused(&self) -> bool {
370        self.inner
371            .lock()
372            .is_ok_and(|inner| inner.status == RunStatus::Paused)
373    }
374
375    /// Wait here while the run is paused. Returns false when the run was
376    /// stopped while waiting.
377    pub(crate) async fn wait_while_paused(&self) -> bool {
378        while self.is_paused() {
379            if self.stop.is_cancelled() {
380                return false;
381            }
382            let resumed = self.resumed.notified();
383            // Re-check after arming the wait, so a resume that lands in between
384            // is not missed.
385            if !self.is_paused() {
386                break;
387            }
388            tokio::select! {
389                _ = resumed => {}
390                _ = self.stop.cancelled() => return false,
391            }
392        }
393        !self.stop.is_cancelled()
394    }
395
396    pub fn stop(&self) {
397        self.stop.cancel();
398        // A paused run must wake so that it can observe the stop.
399        self.resume();
400        self.changed();
401    }
402
403    pub fn stop_agent(&self, id: AgentId) {
404        if let Ok(inner) = self.inner.lock()
405            && let Some(agent) = inner
406                .phases
407                .iter()
408                .flat_map(|phase| phase.agents.iter())
409                .find(|agent| agent.id == id)
410        {
411            agent.cancel.cancel();
412        }
413        self.changed();
414    }
415
416    /// Ask an active agent to stop its current child session and start again.
417    ///
418    /// Finished agents cannot be changed because their value can already have
419    /// moved through later script stages. Relaunching a finished result is a
420    /// new workflow run, not an in-place control action.
421    pub fn restart_agent(&self, id: AgentId) {
422        if let Ok(mut inner) = self.inner.lock()
423            && let Some(agent) = inner
424                .phases
425                .iter_mut()
426                .flat_map(|phase| phase.agents.iter_mut())
427                .find(|agent| agent.id == id)
428            && matches!(agent.status, AgentStatus::Queued | AgentStatus::Running)
429        {
430            agent.status = AgentStatus::Restarting;
431            agent.cancel.cancel();
432        }
433        self.changed();
434    }
435
436    /// Replace the cancelled token after a restart request.
437    pub(crate) fn take_restart(&self, id: AgentId) -> Option<CancellationToken> {
438        if self.stop.is_cancelled() {
439            return None;
440        }
441        let mut inner = self.inner.lock().ok()?;
442        let agent = inner
443            .phases
444            .iter_mut()
445            .flat_map(|phase| phase.agents.iter_mut())
446            .find(|agent| agent.id == id && agent.status == AgentStatus::Restarting)?;
447        agent.status = AgentStatus::Queued;
448        agent.started = None;
449        agent.elapsed = Duration::ZERO;
450        agent.result = None;
451        agent.error = None;
452        agent.cancel = self.stop.child_token();
453        let cancel = agent.cancel.clone();
454        drop(inner);
455        self.changed();
456        Some(cancel)
457    }
458
459    // ----- snapshots --------------------------------------------------------
460
461    pub fn snapshot(&self) -> Arc<RunSnapshot> {
462        let version = *self.version.borrow();
463        if let Ok(cached) = self.cached.lock()
464            && let Some((cached_version, snapshot)) = cached.as_ref()
465            && *cached_version == version
466        {
467            return snapshot.clone();
468        }
469        let snapshot = Arc::new(self.build_snapshot());
470        if let Ok(mut cached) = self.cached.lock() {
471            *cached = Some((version, snapshot.clone()));
472        }
473        snapshot
474    }
475
476    fn build_snapshot(&self) -> RunSnapshot {
477        let Ok(inner) = self.inner.lock() else {
478            return RunSnapshot {
479                status: RunStatus::Failed,
480                elapsed: Duration::ZERO,
481                log: Vec::new(),
482                phases: Vec::new(),
483                tokens: 0,
484                error: Some("the run state was poisoned".into()),
485            };
486        };
487        let mut total_tokens = 0;
488        let phases = inner
489            .phases
490            .iter()
491            .map(|phase| {
492                let mut phase_tokens = 0;
493                let agents = phase
494                    .agents
495                    .iter()
496                    .map(|agent| {
497                        phase_tokens += agent.tokens;
498                        AgentSnapshot {
499                            id: agent.id,
500                            label: agent.label.clone(),
501                            status: agent.status,
502                            tokens: agent.tokens,
503                            elapsed: match (agent.status.is_finished(), agent.started) {
504                                (false, Some(started)) => started.elapsed(),
505                                _ => agent.elapsed,
506                            },
507                            prompt: agent.prompt.clone(),
508                            result: agent.result.clone(),
509                            error: agent.error.clone(),
510                        }
511                    })
512                    .collect();
513                total_tokens += phase_tokens;
514                PhaseSnapshot {
515                    title: phase.title.clone(),
516                    agents,
517                    tokens: phase_tokens,
518                }
519            })
520            .collect();
521        RunSnapshot {
522            status: inner.status,
523            elapsed: inner
524                .finished
525                .unwrap_or_else(Instant::now)
526                .saturating_duration_since(inner.started),
527            log: inner.log.clone(),
528            phases,
529            tokens: total_tokens,
530            error: inner.error.clone(),
531        }
532    }
533}
534
535#[cfg(test)]
536mod tests {
537    use super::*;
538
539    #[test]
540    fn declared_phases_appear_before_any_agent_runs() {
541        let state = RunState::new(&["Discover".into(), "Audit".into()]);
542        let snapshot = state.snapshot();
543        assert_eq!(snapshot.phases.len(), 2);
544        assert_eq!(snapshot.phases[0].title, "Discover");
545        assert_eq!(snapshot.total_agents(), 0);
546    }
547
548    #[test]
549    fn a_script_without_phases_gets_one_default_phase() {
550        let state = RunState::new(&[]);
551        assert_eq!(state.snapshot().phases[0].title, DEFAULT_PHASE);
552    }
553
554    #[test]
555    fn an_undeclared_phase_is_added_when_it_is_first_used() {
556        let state = RunState::new(&["Discover".into()]);
557        state.set_phase("Verify");
558        state.register_agent(0, "check".into(), "prompt".into());
559        let snapshot = state.snapshot();
560        assert_eq!(snapshot.phases.len(), 2);
561        assert_eq!(snapshot.phases[1].title, "Verify");
562        assert_eq!(snapshot.phases[1].agents.len(), 1);
563    }
564
565    #[test]
566    fn snapshots_are_shared_until_the_state_changes() {
567        let state = RunState::new(&[]);
568        let first = state.snapshot();
569        let second = state.snapshot();
570        assert!(Arc::ptr_eq(&first, &second));
571
572        state.register_agent(0, "one".into(), "prompt".into());
573        let third = state.snapshot();
574        assert!(!Arc::ptr_eq(&first, &third));
575    }
576
577    #[test]
578    fn the_version_moves_on_every_change_so_viewers_never_poll() {
579        let state = RunState::new(&[]);
580        let mut versions = state.subscribe();
581        assert_eq!(*versions.borrow_and_update(), 0);
582        state.log("started".into());
583        assert!(versions.has_changed().unwrap_or(false));
584    }
585
586    #[test]
587    fn finished_counts_ignore_agents_still_working() {
588        let state = RunState::new(&[]);
589        state.register_agent(0, "one".into(), "p".into());
590        state.register_agent(1, "two".into(), "p".into());
591        state.agent_started(0);
592        state.agent_finished(0, AgentStatus::Completed, Some("ok".into()), None, 12);
593        let snapshot = state.snapshot();
594        assert_eq!(snapshot.total_agents(), 2);
595        assert_eq!(snapshot.finished_agents(), 1);
596        assert_eq!(snapshot.tokens, 12);
597    }
598
599    #[tokio::test]
600    async fn a_paused_run_continues_after_resume() {
601        let state = RunState::new(&[]);
602        state.pause();
603        assert!(state.is_paused());
604        assert_eq!(state.snapshot().status, RunStatus::Paused);
605
606        let waiter = state.clone();
607        let handle = tokio::spawn(async move { waiter.wait_while_paused().await });
608        tokio::task::yield_now().await;
609        state.resume();
610        assert!(handle.await.unwrap());
611        assert_eq!(state.snapshot().status, RunStatus::Running);
612    }
613
614    #[test]
615    fn a_restart_requested_before_the_call_begins_still_restarts_it() {
616        let state = RunState::new(&[]);
617        state.register_agent(0, "agent".into(), "prompt".into());
618        state.restart_agent(0);
619        state.agent_started(0);
620        assert!(state.take_restart(0).is_some());
621        assert_eq!(
622            state.snapshot().phases[0].agents[0].status,
623            AgentStatus::Queued
624        );
625    }
626
627    #[test]
628    fn pausing_a_finished_run_changes_nothing() {
629        let state = RunState::new(&[]);
630        state.finish(RunStatus::Completed, None);
631        state.pause();
632        assert!(!state.is_paused());
633        assert_eq!(state.snapshot().status, RunStatus::Completed);
634    }
635
636    #[tokio::test]
637    async fn stopping_a_paused_run_releases_it() {
638        let state = RunState::new(&[]);
639        state.pause();
640        let waiter = state.clone();
641        let handle = tokio::spawn(async move { waiter.wait_while_paused().await });
642        tokio::task::yield_now().await;
643        state.stop();
644        // False means "do not carry on", which is what a stopped run needs.
645        assert!(!handle.await.unwrap());
646    }
647}