1use std::time::Duration;
27
28pub const DEFAULT_MAX_GOAL_CONTINUATIONS: u32 = 0;
34
35pub const DEFAULT_GOAL_MAX_STEPS: u32 = 1_000;
41
42pub const MAX_REPEATED_GAP_PASSES: u32 = 3;
62
63pub const MAX_GOAL_CONTINUATION_DELAY_SECONDS: u64 = 24 * 60 * 60;
67
68#[derive(Debug, Clone, Copy, PartialEq, Eq)]
70pub enum GoalRunStatus {
71 Active,
73 Completed,
76 Blocked,
78}
79
80#[derive(Debug, Clone, Copy, PartialEq, Eq)]
82pub enum StopReason {
83 Completed,
85 Blocked,
87 ContinuationLimit,
90 BudgetLimit,
94}
95
96#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
100pub struct GoalProgress {
101 pub tokens_used: u64,
102 pub time_used_seconds: u64,
103 pub continuations: u32,
104}
105
106#[derive(Debug, Clone, Copy, PartialEq, Eq)]
110pub struct GoalBudget {
111 pub token_budget: Option<u64>,
112 pub time_budget_seconds: Option<u64>,
113 pub enforce_token_budget: bool,
118 pub max_continuations: u32,
121}
122
123impl GoalBudget {
124 pub const fn unbounded() -> Self {
127 Self {
128 token_budget: None,
129 time_budget_seconds: None,
130 enforce_token_budget: false,
131 max_continuations: DEFAULT_MAX_GOAL_CONTINUATIONS,
132 }
133 }
134
135 pub const fn with_token_budget(token_budget: u64) -> Self {
137 Self {
138 token_budget: Some(token_budget),
139 time_budget_seconds: None,
140 enforce_token_budget: false,
141 max_continuations: DEFAULT_MAX_GOAL_CONTINUATIONS,
142 }
143 }
144
145 #[must_use]
149 pub const fn with_enforced_token_budget(mut self, enforce: bool) -> Self {
150 self.enforce_token_budget = enforce;
151 self
152 }
153
154 #[must_use]
157 pub const fn with_max_continuations(mut self, max_continuations: u32) -> Self {
158 self.max_continuations = max_continuations;
159 self
160 }
161}
162
163#[derive(Debug, Clone, Copy, PartialEq, Eq)]
165pub enum ContinuationDecision {
166 Continue,
168 Stop(StopReason),
170}
171
172#[must_use]
182pub fn decide_continuation(
183 status: GoalRunStatus,
184 progress: GoalProgress,
185 budget: GoalBudget,
186) -> ContinuationDecision {
187 match status {
189 GoalRunStatus::Completed => return ContinuationDecision::Stop(StopReason::Completed),
190 GoalRunStatus::Blocked => return ContinuationDecision::Stop(StopReason::Blocked),
191 GoalRunStatus::Active => {}
192 }
193
194 if budget
198 .token_budget
199 .is_some_and(|limit| progress.tokens_used >= limit)
200 {
201 if budget.enforce_token_budget {
202 tracing::info!(
203 tokens_used = progress.tokens_used,
204 token_budget = ?budget.token_budget,
205 "goal token budget reached; stopping ([goal] enforce_token_budget)"
206 );
207 return ContinuationDecision::Stop(StopReason::BudgetLimit);
208 }
209 tracing::debug!(
210 tokens_used = progress.tokens_used,
211 token_budget = ?budget.token_budget,
212 "goal over token budget but continuing (unbounded)"
213 );
214 }
215 if let Some(secs) = budget.time_budget_seconds
216 && progress.time_used_seconds >= secs
217 {
218 tracing::debug!(
219 time_used_seconds = progress.time_used_seconds,
220 time_budget_seconds = secs,
221 "goal over time budget but continuing (unbounded)"
222 );
223 }
224
225 if budget.max_continuations > 0 && progress.continuations >= budget.max_continuations {
229 tracing::warn!(
230 continuations = progress.continuations,
231 max_continuations = budget.max_continuations,
232 "goal continuation backstop fired: no terminal signal after the configured \
233 continuation limit ([goal] max_continuations)"
234 );
235 return ContinuationDecision::Stop(StopReason::ContinuationLimit);
236 }
237
238 ContinuationDecision::Continue
240}
241
242#[derive(Debug, Clone, Copy, PartialEq, Eq)]
244pub enum ContinuationWaitOutcome {
245 Elapsed,
247 Cancelled,
249}
250
251#[must_use]
256pub const fn continuation_wait(delay_seconds: u64) -> Option<Duration> {
257 if delay_seconds == 0 {
258 None
259 } else {
260 Some(Duration::from_secs(
261 if delay_seconds > MAX_GOAL_CONTINUATION_DELAY_SECONDS {
262 MAX_GOAL_CONTINUATION_DELAY_SECONDS
263 } else {
264 delay_seconds
265 },
266 ))
267 }
268}
269
270pub async fn await_continuation_wait(
280 wait: Option<Duration>,
281 cancel_token: &tokio_util::sync::CancellationToken,
282) -> ContinuationWaitOutcome {
283 if cancel_token.is_cancelled() {
284 return ContinuationWaitOutcome::Cancelled;
285 }
286 let Some(wait) = wait else {
287 return ContinuationWaitOutcome::Elapsed;
288 };
289 tokio::select! {
290 biased;
291 () = cancel_token.cancelled() => ContinuationWaitOutcome::Cancelled,
292 () = tokio::time::sleep(wait) => ContinuationWaitOutcome::Elapsed,
293 }
294}
295
296#[must_use]
303pub const fn token_budget_exhausted(progress: GoalProgress, budget: GoalBudget) -> bool {
304 budget.enforce_token_budget
305 && match budget.token_budget {
306 Some(limit) => progress.tokens_used >= limit,
307 None => false,
308 }
309}
310
311#[must_use]
314pub fn is_success(reason: StopReason) -> bool {
315 matches!(reason, StopReason::Completed)
316}
317
318#[cfg(test)]
319mod tests {
320 use super::*;
321
322 #[test]
323 fn completed_status_stops_with_success() {
324 let d = decide_continuation(
325 GoalRunStatus::Completed,
326 GoalProgress::default(),
327 GoalBudget::unbounded(),
328 );
329 assert_eq!(d, ContinuationDecision::Stop(StopReason::Completed));
330 assert!(is_success(StopReason::Completed));
331 }
332
333 #[test]
334 fn blocked_status_stops_without_success() {
335 let d = decide_continuation(
336 GoalRunStatus::Blocked,
337 GoalProgress::default(),
338 GoalBudget::unbounded(),
339 );
340 assert_eq!(d, ContinuationDecision::Stop(StopReason::Blocked));
341 assert!(!is_success(StopReason::Blocked));
342 }
343
344 #[test]
345 fn active_under_budget_continues() {
346 let progress = GoalProgress {
347 tokens_used: 10,
348 time_used_seconds: 5,
349 continuations: 2,
350 };
351 let budget = GoalBudget {
352 token_budget: Some(1000),
353 time_budget_seconds: Some(600),
354 enforce_token_budget: false,
355 max_continuations: DEFAULT_MAX_GOAL_CONTINUATIONS,
356 };
357 assert_eq!(
358 decide_continuation(GoalRunStatus::Active, progress, budget),
359 ContinuationDecision::Continue
360 );
361 }
362
363 #[test]
364 fn default_goal_has_no_continuation_limit() {
365 let progress = GoalProgress {
366 continuations: 10_000,
367 ..GoalProgress::default()
368 };
369 assert_eq!(
370 decide_continuation(GoalRunStatus::Active, progress, GoalBudget::unbounded()),
371 ContinuationDecision::Continue
372 );
373 }
374
375 #[test]
376 fn explicit_continuation_limit_stops_run() {
377 let configured_limit = 100;
378 let progress = GoalProgress {
379 continuations: configured_limit,
380 ..GoalProgress::default()
381 };
382 let budget = GoalBudget::unbounded().with_max_continuations(configured_limit);
383 assert_eq!(
384 decide_continuation(GoalRunStatus::Active, progress, budget),
385 ContinuationDecision::Stop(StopReason::ContinuationLimit)
386 );
387 }
388
389 #[test]
390 fn operate_goal_continues_past_ten_when_budget_remains() {
391 for continuations in [10, 11, 100, 10_000] {
395 let progress = GoalProgress {
396 tokens_used: 5_000,
397 time_used_seconds: 300,
398 continuations,
399 };
400 let budget = GoalBudget::with_token_budget(1_000_000);
401 assert_eq!(
402 decide_continuation(GoalRunStatus::Active, progress, budget),
403 ContinuationDecision::Continue,
404 "pass {continuations} must continue toward the completion gate",
405 );
406 }
407 }
408
409 #[test]
410 fn configured_backstop_halts_pathological_loop() {
411 let backstop = 25;
412 let progress = GoalProgress {
413 continuations: backstop,
414 ..GoalProgress::default()
415 };
416 let budget = GoalBudget::unbounded().with_max_continuations(backstop);
417 assert_eq!(
418 decide_continuation(GoalRunStatus::Active, progress, budget),
419 ContinuationDecision::Stop(StopReason::ContinuationLimit)
420 );
421 }
422
423 #[test]
424 fn zero_backstop_is_unlimited_and_budget_advisory() {
425 let progress = GoalProgress {
427 continuations: 10_000,
428 ..GoalProgress::default()
429 };
430 let budget = GoalBudget::unbounded().with_max_continuations(0);
431 assert_eq!(
432 decide_continuation(GoalRunStatus::Active, progress, budget),
433 ContinuationDecision::Continue
434 );
435
436 let progress = GoalProgress {
438 tokens_used: 1_000,
439 continuations: 10_000,
440 ..GoalProgress::default()
441 };
442 let budget = GoalBudget::with_token_budget(1_000).with_max_continuations(0);
443 assert_eq!(
444 decide_continuation(GoalRunStatus::Active, progress, budget),
445 ContinuationDecision::Continue,
446 "budget advisory — must continue even when over budget"
447 );
448 }
449
450 #[test]
451 fn enforced_token_budget_stops_the_run() {
452 let progress = GoalProgress {
453 tokens_used: 1000,
454 continuations: 1,
455 ..GoalProgress::default()
456 };
457 let budget = GoalBudget::with_token_budget(1000).with_enforced_token_budget(true);
458 assert_eq!(
459 decide_continuation(GoalRunStatus::Active, progress, budget),
460 ContinuationDecision::Stop(StopReason::BudgetLimit),
461 "enforce_token_budget makes an exhausted token budget terminal"
462 );
463 assert!(!is_success(StopReason::BudgetLimit));
464 }
465
466 #[test]
467 fn enforce_flag_without_a_token_budget_cannot_stop() {
468 let progress = GoalProgress {
471 tokens_used: u64::MAX / 2,
472 continuations: 1,
473 ..GoalProgress::default()
474 };
475 let budget = GoalBudget::unbounded().with_enforced_token_budget(true);
476 assert_eq!(
477 decide_continuation(GoalRunStatus::Active, progress, budget),
478 ContinuationDecision::Continue
479 );
480 }
481
482 #[test]
483 fn enforced_budget_still_yields_to_a_terminal_status() {
484 let budget = GoalBudget::with_token_budget(1000).with_enforced_token_budget(true);
485 assert_eq!(
486 decide_continuation(GoalRunStatus::Completed, GoalProgress::default(), budget),
487 ContinuationDecision::Stop(StopReason::Completed),
488 "a clean completion outranks the budget gate"
489 );
490 }
491
492 #[test]
493 fn token_budget_is_advisory_not_terminal() {
494 let progress = GoalProgress {
495 tokens_used: 1000,
496 continuations: 1,
497 ..GoalProgress::default()
498 };
499 let budget = GoalBudget::with_token_budget(1000);
500 assert_eq!(
501 decide_continuation(GoalRunStatus::Active, progress, budget),
502 ContinuationDecision::Continue,
503 "token budget is advisory — unbounded run must continue"
504 );
505 }
506
507 #[test]
508 fn time_budget_is_advisory_not_terminal() {
509 let progress = GoalProgress {
510 time_used_seconds: 601,
511 continuations: 1,
512 ..GoalProgress::default()
513 };
514 let budget = GoalBudget {
515 token_budget: None,
516 time_budget_seconds: Some(600),
517 enforce_token_budget: false,
518 max_continuations: DEFAULT_MAX_GOAL_CONTINUATIONS,
519 };
520 assert_eq!(
521 decide_continuation(GoalRunStatus::Active, progress, budget),
522 ContinuationDecision::Continue,
523 "time budget is advisory — unbounded run must continue"
524 );
525 }
526
527 #[test]
528 fn terminal_status_outranks_remaining_budget() {
529 let progress = GoalProgress::default();
531 let budget = GoalBudget {
532 token_budget: Some(1_000_000),
533 time_budget_seconds: Some(86_400),
534 enforce_token_budget: false,
535 max_continuations: DEFAULT_MAX_GOAL_CONTINUATIONS,
536 };
537 assert_eq!(
538 decide_continuation(GoalRunStatus::Completed, progress, budget),
539 ContinuationDecision::Stop(StopReason::Completed)
540 );
541 }
542
543 #[test]
544 fn continuation_wait_honors_configured_delay() {
545 assert_eq!(
546 continuation_wait(300),
547 Some(Duration::from_secs(300)),
548 "a positive configured delay must become the quiet-period wait"
549 );
550 assert_eq!(
551 continuation_wait(MAX_GOAL_CONTINUATION_DELAY_SECONDS + 1),
552 Some(Duration::from_secs(MAX_GOAL_CONTINUATION_DELAY_SECONDS)),
553 "the shared cap must bound an oversized configured delay"
554 );
555 }
556
557 #[test]
558 fn zero_delay_continues_immediately() {
559 assert_eq!(
560 continuation_wait(0),
561 None,
562 "an unset or zero delay must dispatch immediately"
563 );
564 }
565
566 #[tokio::test]
567 async fn cancellation_wins_over_pending_quiet_period() {
568 let cancel_token = tokio_util::sync::CancellationToken::new();
569 let canceller = cancel_token.clone();
570 tokio::spawn(async move {
571 tokio::time::sleep(Duration::from_millis(10)).await;
572 canceller.cancel();
573 });
574 assert_eq!(
575 await_continuation_wait(
576 continuation_wait(MAX_GOAL_CONTINUATION_DELAY_SECONDS),
577 &cancel_token,
578 )
579 .await,
580 ContinuationWaitOutcome::Cancelled,
581 "an explicit cancel during the quiet period must win and never dispatch"
582 );
583 }
584
585 #[test]
586 fn exhausted_budget_predicate_matches_the_live_stop() {
587 let progress = GoalProgress {
588 tokens_used: 1_000,
589 ..GoalProgress::default()
590 };
591 for enforce in [false, true] {
592 let budget = GoalBudget {
593 token_budget: Some(1_000),
594 time_budget_seconds: None,
595 enforce_token_budget: enforce,
596 max_continuations: 0,
597 };
598 assert_eq!(
599 token_budget_exhausted(progress, budget),
600 decide_continuation(GoalRunStatus::Active, progress, budget)
601 == ContinuationDecision::Stop(StopReason::BudgetLimit),
602 "preview must report exactly the budget stop the live loop takes (enforce={enforce})"
603 );
604 }
605 }
606
607 #[tokio::test]
608 async fn cancellation_wins_over_a_zero_delay() {
609 let cancel_token = tokio_util::sync::CancellationToken::new();
610 cancel_token.cancel();
611 assert_eq!(
612 await_continuation_wait(continuation_wait(0), &cancel_token).await,
613 ContinuationWaitOutcome::Cancelled,
614 "a cancelled goal with no quiet period must never dispatch"
615 );
616 }
617
618 #[tokio::test]
619 async fn elapsed_quiet_period_dispatches() {
620 let cancel_token = tokio_util::sync::CancellationToken::new();
621 assert_eq!(
622 await_continuation_wait(None, &cancel_token).await,
623 ContinuationWaitOutcome::Elapsed,
624 "an unset wait must gate the dispatch through immediately"
625 );
626 assert_eq!(
627 await_continuation_wait(Some(Duration::from_millis(1)), &cancel_token).await,
628 ContinuationWaitOutcome::Elapsed,
629 "an expired quiet period must dispatch"
630 );
631 }
632}