Skip to main content

codewhale_runtime/
goal_loop.rs

1//! Goal loop orchestrator — the persistent-objective control layer (#3215, and
2//! its lineage #891 / #1976 / #2058 / #2029).
3//!
4//! This is the **Workflow goal layer**: the decision core that turns a one-shot
5//! `/goal` into a persistent work loop. Given the durable goal status, the
6//! accumulated usage (from the per-goal accounting wired in `crates/state`
7//! `record_thread_goal_usage`), and a budget, it decides whether to **continue**
8//! (re-dispatch another worker turn toward the objective) or **stop** with a
9//! terminal status. It is the orchestrator in the Workflow≈ultracode mapping —
10//! the loop that fans work out to workers (`worker_profile`) and verifies before
11//! committing.
12//!
13//! Scope: **decision logic + types**. The engine (`core/engine.rs`) reads the
14//! `SharedGoalState` snapshot after each turn and calls `decide_continuation`
15//! to decide whether to re-dispatch. For operate-mode goals the terminal stops
16//! are a verified completion, a blocked report, the stall pause that fires
17//! when a critical verifier reports the same gap set
18//! [`MAX_REPEATED_GAP_PASSES`] times running (enforced in
19//! `GoalState::record_not_achieved`), and the opt-in continuation backstop
20//! (`[goal] max_continuations`); token/time accounting stays visible as
21//! telemetry but does not gate continuation — spend is bounded by stalling,
22//! not by a pass count, like grokbuild (`DEFAULT_AGENT_BUDGET` as call cap)
23//! and kimicode swarm (`turnBudget` per-task, resumable after
24//! budget-reached). Log when the backstop fires.
25
26use std::time::Duration;
27
28/// Default automatic cross-turn continuation policy for one goal run (#5052).
29///
30/// Goals are unlimited by default: completion, blocked status, or explicit
31/// user control ends the run. Operators who want a circuit breaker can opt in
32/// with `[goal] max_continuations`; `0` keeps the default unlimited behavior.
33pub const DEFAULT_MAX_GOAL_CONTINUATIONS: u32 = 0;
34
35/// Default per-engine-turn step allowance while a goal is active (#5994).
36/// Deliberate maintainer policy, not a measured number: five times the
37/// ordinary interactive allowance (200), so intentional goal work has room
38/// while every provider turn stays finite. The count of continuation passes
39/// remains governed separately (`[goal] max_continuations`).
40pub const DEFAULT_GOAL_MAX_STEPS: u32 = 1_000;
41
42/// How many consecutive critical `not_achieved` reviews naming the *same*
43/// normalized gap set a goal may accumulate before it pauses itself with
44/// `GoalPauseReason::NoProgress`.
45///
46/// This is the bound the continuation prompt promises the model, and it is the
47/// only default stop on a goal run: `DEFAULT_MAX_GOAL_CONTINUATIONS` is `0`, so
48/// without it the loop runs until the model volunteers a terminal status.
49/// Enforcement lives in `GoalState::record_not_achieved`, and it reuses the
50/// existing pause authority rather than adding a second one — both continuation
51/// dispatchers already refuse to re-dispatch a non-active goal, and
52/// `RuntimeThreadManager` already mirrors a non-limit pause into the durable
53/// `ThreadGoalStatus::Paused`, so the stop survives a restart and needs an
54/// explicit resume.
55///
56/// The counter is `1` on the first report of a gap set, so `3` means the
57/// verifier named identical remaining work three times running: two whole
58/// continuation passes that moved nothing the verifier can see. Two is too
59/// eager — one pass legitimately fails to land a fix and retries — and anything
60/// larger just buys more identical passes.
61pub const MAX_REPEATED_GAP_PASSES: u32 = 3;
62
63/// Upper bound for one between-turn quiet period. A day is long enough for
64/// coordinator cadences while preventing an accidental giant integer from
65/// becoming a practically uninterruptible-looking schedule receipt.
66pub const MAX_GOAL_CONTINUATION_DELAY_SECONDS: u64 = 24 * 60 * 60;
67
68/// Terminal or active state of a persistent goal.
69#[derive(Debug, Clone, Copy, PartialEq, Eq)]
70pub enum GoalRunStatus {
71    /// Still working toward the objective.
72    Active,
73    /// The objective was achieved (the model self-reported done and, ideally, a
74    /// verifier confirmed — see `GoalGate`).
75    Completed,
76    /// The model reported it is blocked and needs the user.
77    Blocked,
78}
79
80/// Why the loop stopped, for a terminal decision.
81#[derive(Debug, Clone, Copy, PartialEq, Eq)]
82pub enum StopReason {
83    /// Objective achieved.
84    Completed,
85    /// Model reported blocked.
86    Blocked,
87    /// Continuation circuit-breaker tripped (too many continuations without a
88    /// terminal signal).
89    ContinuationLimit,
90    /// The goal's token budget was reached while `[goal] enforce_token_budget`
91    /// opted the budget into a hard stop (#6013). Default-off: without the
92    /// opt-in the budget stays advisory telemetry and never produces this.
93    BudgetLimit,
94}
95
96/// Accumulated, durable progress for a goal run. Mirrors the fields wired by
97/// `crates/state` `record_thread_goal_usage` (tokens_used / time_used_seconds)
98/// plus a continuation counter the loop maintains.
99#[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/// The optional token/time bounds on a goal run. `None` fields mean unbounded
107/// for that resource; the continuation backstop (`max_continuations`) still
108/// applies unless configured to `0`.
109#[derive(Debug, Clone, Copy, PartialEq, Eq)]
110pub struct GoalBudget {
111    pub token_budget: Option<u64>,
112    pub time_budget_seconds: Option<u64>,
113    /// Whether `token_budget` stops the run when reached (#6013). `false`
114    /// keeps the default advisory behavior: crossing the budget logs and
115    /// continues. There is no time-budget enforcement because goals carry no
116    /// `time_budget` field — only `token_budget` can gate.
117    pub enforce_token_budget: bool,
118    /// Safety backstop on automatic continuation passes (#5052). `0` disables
119    /// the backstop: only terminal status stops the run.
120    pub max_continuations: u32,
121}
122
123impl GoalBudget {
124    /// No token or time cap. Terminal status, user control, and the default
125    /// continuation backstop still stop the run.
126    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    /// A token budget for telemetry/UI. It never pauses an unbounded goal.
136    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    /// Opt the token budget into a hard stop (`[goal] enforce_token_budget`).
146    /// With no `token_budget` set this is a no-op by construction — there is
147    /// no ceiling to reach.
148    #[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    /// Override the continuation backstop (`0` = unlimited until terminal
155    /// status).
156    #[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/// The decision the loop makes after each worker turn.
164#[derive(Debug, Clone, Copy, PartialEq, Eq)]
165pub enum ContinuationDecision {
166    /// Re-dispatch another turn toward the objective.
167    Continue,
168    /// Stop; the goal run is terminal.
169    Stop(StopReason),
170}
171
172/// Decide whether a persistent goal run should continue after a turn.
173///
174/// Precedence (most authoritative first):
175/// 1. A terminal model status (Completed / Blocked) ends the run.
176/// 2. The configurable continuation backstop stops a pathological loop
177///    (skipped entirely when configured to `0`).
178/// 3. Otherwise continue — the loop runs to the completion gate, not to a
179///    fixed pass count (#5052). Token/time budgets are advisory telemetry;
180///    they are surfaced in the UI but do not stop the run (unbounded).
181#[must_use]
182pub fn decide_continuation(
183    status: GoalRunStatus,
184    progress: GoalProgress,
185    budget: GoalBudget,
186) -> ContinuationDecision {
187    // 1. Terminal model signal wins.
188    match status {
189        GoalRunStatus::Completed => return ContinuationDecision::Stop(StopReason::Completed),
190        GoalRunStatus::Blocked => return ContinuationDecision::Stop(StopReason::Blocked),
191        GoalRunStatus::Active => {}
192    }
193
194    // 2. Token budget: advisory telemetry by default, or a hard stop when
195    //    `[goal] enforce_token_budget` opts in (#6013). Time stays advisory —
196    //    goals carry no time budget to enforce against.
197    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    // 3. Runaway-cost backstop. This deliberately uses the already-durable
226    // continuation counter instead of adding verifier fingerprints or another
227    // orchestration subsystem. `0` disables it — budget/terminal stops only.
228    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    // 4. Keep going.
239    ContinuationDecision::Continue
240}
241
242/// Outcome of waiting out the between-continuation quiet period.
243#[derive(Debug, Clone, Copy, PartialEq, Eq)]
244pub enum ContinuationWaitOutcome {
245    /// The quiet period elapsed — dispatch the continuation.
246    Elapsed,
247    /// Cancelled during the quiet period — never dispatch.
248    Cancelled,
249}
250
251/// Compute the quiet-period wait for a configured between-continuation delay.
252/// `None` continues immediately (unset or zero delay); a positive delay
253/// returns the capped wait shared by every dispatch path so no caller can
254/// construct an effectively uninterruptible schedule receipt.
255#[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
270/// Wait out the between-continuation quiet period, honoring cancellation.
271/// `None` resolves immediately so callers have a single dispatch gate: to
272/// `Cancelled` when the token is already cancelled, otherwise `Elapsed`.
273/// Cancellation is biased and always wins over a racing expiry — the same
274/// semantics as the interactive cadence (#5508), including a zero delay. Two dispatchers await
275/// this gate: the turn loop's intra-turn passes (every session), and the
276/// runtime host's cross-turn re-arm for host-managed engines
277/// (`RuntimeThreadManager::spawn_goal_continuation`), which never
278/// self-continue.
279pub 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/// Whether the durable token usage has reached an *enforced* token budget —
297/// the same condition on which [`decide_continuation`] stops with
298/// [`StopReason::BudgetLimit`]. Budgets are telemetry-only unless
299/// `[goal] enforce_token_budget` opts in, so without it this stays false and
300/// crossing a budget never closes the outbound gate. Preview and the live
301/// continuation loop share this predicate so they cannot disagree about spend.
302#[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/// Whether a stop reason represents success (Completed) vs. an early/forced exit.
312/// Useful for the UI/status projection (#2666 token/time visibility).
313#[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        // #5052 regression: the old hardcoded cap of 10 must not be a terminal
392        // stop. With no terminal signal, pass 10, 11, and far beyond keep
393        // continuing because the default has no hidden ceiling.
394        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        // 0 = unlimited-with-budget-stops: no continuation count ends the run…
426        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        // exceeded token budget is advisory — must still continue (unbounded)
437        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        // A goal created without `token_budget` has no ceiling to reach — the
469        // flag must not invent one.
470        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        // Completed wins even if there is plenty of budget left.
530        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}