1use 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 Reused,
50 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#[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#[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#[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 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
167pub(crate) struct RunState {
169 inner: Mutex<Inner>,
170 version: watch::Sender<u64>,
171 cached: Mutex<Option<(u64, Arc<RunSnapshot>)>>,
173 resumed: Notify,
174 stop: CancellationToken,
175}
176
177pub(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 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 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 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 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 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 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 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 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 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 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 assert!(!handle.await.unwrap());
646 }
647}