Skip to main content

codewhale_runtime/
turn_budget.rs

1//! Turn budgets shared by interactive hosts and headless execution.
2//!
3//! Model steps and the cumulative per-turn wall clock are uncapped by
4//! default. Explicit positive limits still apply; neither a step counter nor
5//! elapsed time is a measure of useful progress, and a long autonomous turn
6//! should not stop at an arbitrary hour. Per-step stream budgets remain
7//! finite: they bound one stuck request, not the whole turn.
8//!
9//! `EngineConfig` retains its integer representation for embedders:
10//! `u32::MAX` represents no model-step limit. `TurnContext::step_limit`
11//! resolves that representation to `None` before checking a ceiling or
12//! emitting diagnostics. It is not a very large finite fallback.
13//!
14//! ## Honesty at the limit
15//!
16//! Hitting a budget is never a clean success. The step ceiling already ends
17//! the turn as `TurnOutcomeStatus::Failed` with the limit named (or, when
18//! the model still owes work, grants exactly one bounded final-report turn
19//! first). [`TurnWallClock`] follows the same contract in `run_turn`.
20
21use std::time::{Duration, Instant};
22
23/// No model-step limit unless the caller configures one. This is the
24/// compatibility representation, not a ceiling checked at `u32::MAX`.
25pub const DEFAULT_MAX_MODEL_STEPS: u32 = u32::MAX;
26
27/// No per-turn wall-clock limit unless the caller configures one.
28///
29/// `Duration::MAX` is the representation, mirroring
30/// [`DEFAULT_MAX_MODEL_STEPS`]: [`TurnWallClock::exhausted`] can never reach
31/// it, and callers turning it into an absolute deadline must use
32/// `checked_add` (see `exec_agent`). When configured, the budget is measured
33/// across every model step of one turn, not per request, and time blocked on
34/// a human approval decision is excluded (see
35/// [`TurnWallClock::begin_human_wait`]).
36pub const DEFAULT_TURN_WALL_CLOCK: Duration = Duration::MAX;
37
38/// Default per-step cap on accumulated streamed content, in bytes: the total
39/// text, reasoning and tool-argument content before aborting the stream.
40/// Preserves the pre-R1 hard-coded value; R1 only makes it overridable.
41pub const DEFAULT_STREAM_MAX_CONTENT_BYTES: usize = 10 * 1024 * 1024;
42/// Smallest accepted per-step stream content cap (64 KiB).
43pub const MIN_STREAM_MAX_CONTENT_BYTES: usize = 64 * 1024;
44/// Largest accepted per-step stream content cap (512 MiB).
45pub const MAX_STREAM_MAX_CONTENT_BYTES: usize = 512 * 1024 * 1024;
46
47/// Default per-step cap on a single stream's wall-clock duration, in
48/// seconds. Preserves the pre-R1 hard-coded value.
49///
50/// Sanity backstop for total stream wall-clock duration. **Not** a routine
51/// kill switch — the stream chunk idle timeout is the primary stall
52/// detector. The wall-clock cap is here only to bound pathological cases
53/// (e.g. a server that keeps sending heartbeats forever without progress).
54///
55/// History: this used to be 300s (5 min) which was too aggressive — V4
56/// thinking turns on hard prompts legitimately exceed 5 minutes wall-clock
57/// while still emitting reasoning_content chunks the whole way. Bumped to
58/// 30 min in v0.6.6 after long-reasoning turns hit the old cap. Codex defaults to a
59/// per-chunk idle of 300s with no wall-clock cap; we keep both layers but
60/// give the wall-clock a generous window so it never fires in practice.
61pub const DEFAULT_STREAM_MAX_DURATION_SECS: u64 = 1800;
62/// Smallest accepted per-step stream duration cap.
63pub const MIN_STREAM_MAX_DURATION_SECS: u64 = 10;
64/// Largest accepted per-step stream duration cap (24 hours).
65pub const MAX_STREAM_MAX_DURATION_SECS: u64 = 86_400;
66
67/// Default retry budget for proven pre-dispatch stream-open failures.
68/// An unknown dispatched outcome never spends this budget to replay a POST.
69pub const DEFAULT_STREAM_MAX_RESUMES: u32 = 3;
70/// Largest accepted safe-open retry budget. `0` disables outer open retries.
71pub const MAX_STREAM_MAX_RESUMES: u32 = 10;
72/// Historical default retained for configuration compatibility; inactive in Core.
73pub const DEFAULT_STREAM_MAX_TRANSPARENT_RETRIES: u32 = 2;
74/// Historical accepted bound for the inactive compatibility setting.
75pub const MAX_STREAM_MAX_TRANSPARENT_RETRIES: u32 = 10;
76/// Historical error-count default retained for compatibility; Core ends on
77/// the first uncertain admitted stream error.
78pub const DEFAULT_STREAM_MAX_ERRORS: u32 = 5;
79/// Smallest accepted compatibility value. `0` selects the historical default.
80pub const MIN_STREAM_MAX_ERRORS: u32 = 1;
81/// Largest accepted compatibility value.
82pub const MAX_STREAM_MAX_ERRORS: u32 = 50;
83
84/// Safe-open retries and parsed historical stream settings. The compatibility
85/// fields never authorize replay or error tolerance for an opened stream.
86#[derive(Debug, Clone, Copy, PartialEq, Eq)]
87pub struct StreamRetryLimits {
88    /// Proven pre-dispatch stream-open retries.
89    pub max_resumes: u32,
90    /// Inactive Core compatibility setting.
91    pub max_transparent_retries: u32,
92    /// Inactive Core compatibility setting; an uncertain error ends the stream.
93    pub max_errors: u32,
94}
95
96impl Default for StreamRetryLimits {
97    fn default() -> Self {
98        resolve_stream_retry_limits(None, None, None)
99    }
100}
101
102/// Resolve configured stream retry budgets.
103///
104/// `None` selects each default. The two retry counts accept `0` (no
105/// retries) and clamp to their maximum. The error streak is a finite stream
106/// budget like `stream_max_content_mb`: `0` selects its default, and other
107/// values clamp to `MIN_STREAM_MAX_ERRORS..=MAX_STREAM_MAX_ERRORS`.
108#[must_use]
109pub fn resolve_stream_retry_limits(
110    max_resumes: Option<u32>,
111    max_transparent_retries: Option<u32>,
112    max_errors: Option<u32>,
113) -> StreamRetryLimits {
114    StreamRetryLimits {
115        max_resumes: max_resumes
116            .unwrap_or(DEFAULT_STREAM_MAX_RESUMES)
117            .min(MAX_STREAM_MAX_RESUMES),
118        max_transparent_retries: max_transparent_retries
119            .unwrap_or(DEFAULT_STREAM_MAX_TRANSPARENT_RETRIES)
120            .min(MAX_STREAM_MAX_TRANSPARENT_RETRIES),
121        max_errors: match max_errors {
122            None | Some(0) => DEFAULT_STREAM_MAX_ERRORS,
123            Some(value) => value.clamp(MIN_STREAM_MAX_ERRORS, MAX_STREAM_MAX_ERRORS),
124        },
125    }
126}
127
128/// Resolve a configured model-step ceiling.
129///
130/// `None` and `0` select the uncapped default. Positive values are preserved;
131/// `u32::MAX` remains the compatibility representation for no limit.
132#[must_use]
133pub fn resolve_max_model_steps(raw: Option<u32>) -> u32 {
134    match raw {
135        None | Some(0) => DEFAULT_MAX_MODEL_STEPS,
136        Some(value) => value,
137    }
138}
139
140/// Resolve a configured per-turn wall-clock budget.
141///
142/// `None` and `0` select the uncapped default ([`DEFAULT_TURN_WALL_CLOCK`]).
143/// Explicit positive values, in seconds, are preserved.
144#[must_use]
145pub fn resolve_turn_wall_clock(raw: Option<u64>) -> Duration {
146    match raw {
147        None | Some(0) => DEFAULT_TURN_WALL_CLOCK,
148        Some(value) => Duration::from_secs(value),
149    }
150}
151
152/// Resolve a configured per-step stream content cap, given megabytes.
153///
154/// `None` and `0` both resolve to [`DEFAULT_STREAM_MAX_CONTENT_BYTES`].
155#[must_use]
156pub fn resolve_stream_max_content_bytes(raw_mb: Option<u64>) -> usize {
157    match raw_mb {
158        None | Some(0) => DEFAULT_STREAM_MAX_CONTENT_BYTES,
159        Some(mb) => usize::try_from(mb.saturating_mul(1024 * 1024))
160            .unwrap_or(MAX_STREAM_MAX_CONTENT_BYTES)
161            .clamp(MIN_STREAM_MAX_CONTENT_BYTES, MAX_STREAM_MAX_CONTENT_BYTES),
162    }
163}
164
165/// Resolve a configured per-step stream duration cap, in seconds.
166///
167/// `None` and `0` both resolve to [`DEFAULT_STREAM_MAX_DURATION_SECS`].
168#[must_use]
169pub fn resolve_stream_max_duration_secs(raw: Option<u64>) -> u64 {
170    match raw {
171        None | Some(0) => DEFAULT_STREAM_MAX_DURATION_SECS,
172        Some(value) => value.clamp(MIN_STREAM_MAX_DURATION_SECS, MAX_STREAM_MAX_DURATION_SECS),
173    }
174}
175
176/// Cumulative wall-clock budget for one turn.
177///
178/// Started once at the top of `Engine::run_turn` and checked at the
179/// provider-request boundary, so a turn that trips the budget stops before
180/// authorizing another billable request and keeps every tool result already
181/// in the transcript.
182///
183/// Time blocked on a human approval decision is excluded: the budget bounds
184/// what the agent spends on its own, not how long a person takes to answer.
185/// Without that exclusion an approval prompt left open overnight would fail
186/// the turn — and discard the work the user just approved — the moment they
187/// came back.
188#[derive(Debug)]
189pub struct TurnWallClock {
190    budget: Duration,
191    started_at: Instant,
192    /// Total time already excluded because the turn was blocked on a human.
193    excluded: Duration,
194    /// Set while currently blocked on a human decision.
195    blocked_since: Option<Instant>,
196}
197
198impl TurnWallClock {
199    /// Start a fresh budget. A zero budget is legal here (and only here):
200    /// it is how tests assert the stop path without sleeping. Configuration
201    /// never produces one — [`resolve_turn_wall_clock`] reads `0` as no limit.
202    pub fn start(budget: Duration) -> Self {
203        Self {
204            budget,
205            started_at: Instant::now(),
206            excluded: Duration::ZERO,
207            blocked_since: None,
208        }
209    }
210
211    /// The budget this clock was started with.
212    pub fn budget(&self) -> Duration {
213        self.budget
214    }
215
216    /// Wall-clock time this turn has spent on its own work, excluding time
217    /// blocked on a human decision.
218    pub fn spent(&self) -> Duration {
219        let blocked_now = self
220            .blocked_since
221            .map_or(Duration::ZERO, |since| since.elapsed());
222        self.started_at
223            .elapsed()
224            .saturating_sub(self.excluded)
225            .saturating_sub(blocked_now)
226    }
227
228    /// Whether the cumulative budget is spent.
229    pub fn exhausted(&self) -> bool {
230        self.spent() >= self.budget
231    }
232
233    /// Stop counting: the turn is now waiting on a human decision.
234    /// Idempotent — a second call while already blocked does nothing, so a
235    /// nested or re-entered approval cannot double-exclude.
236    pub fn begin_human_wait(&mut self) {
237        if self.blocked_since.is_none() {
238            self.blocked_since = Some(Instant::now());
239        }
240    }
241
242    /// Resume counting after a human decision, banking the blocked time.
243    pub fn end_human_wait(&mut self) {
244        if let Some(since) = self.blocked_since.take() {
245            self.excluded = self.excluded.saturating_add(since.elapsed());
246        }
247    }
248
249    /// Test-only: pretend `elapsed` more wall-clock time has passed, so the
250    /// exhaustion path can be exercised without sleeping. An in-progress
251    /// human wait is rewound too — otherwise the simulated time would count
252    /// as agent-owned work that never actually happened.
253    #[cfg(any(test, feature = "test-support"))]
254    pub fn rewind_for_test(&mut self, elapsed: Duration) {
255        self.started_at = self
256            .started_at
257            .checked_sub(elapsed)
258            .unwrap_or(self.started_at);
259        if let Some(since) = self.blocked_since {
260            self.blocked_since = Some(since.checked_sub(elapsed).unwrap_or(since));
261        }
262    }
263}
264
265#[cfg(test)]
266mod tests {
267    use super::*;
268
269    #[test]
270    fn model_step_defaults_do_not_install_a_ceiling() {
271        assert_eq!(resolve_max_model_steps(None), DEFAULT_MAX_MODEL_STEPS);
272        assert_eq!(resolve_max_model_steps(Some(0)), DEFAULT_MAX_MODEL_STEPS);
273        assert_eq!(DEFAULT_MAX_MODEL_STEPS, u32::MAX);
274        assert_eq!(resolve_max_model_steps(Some(u32::MAX)), u32::MAX);
275    }
276
277    #[test]
278    fn model_step_ceiling_preserves_the_owner_limit() {
279        assert_eq!(resolve_max_model_steps(Some(7)), 7);
280        assert_eq!(resolve_max_model_steps(Some(1)), 1);
281        assert_eq!(
282            resolve_max_model_steps(Some(200_000)),
283            200_000,
284            "explicit positive overrides retain the configured ceiling"
285        );
286    }
287
288    #[test]
289    fn turn_wall_clock_defaults_to_no_limit() {
290        assert_eq!(resolve_turn_wall_clock(None), DEFAULT_TURN_WALL_CLOCK);
291        assert_eq!(resolve_turn_wall_clock(Some(0)), DEFAULT_TURN_WALL_CLOCK);
292        let mut clock = TurnWallClock::start(resolve_turn_wall_clock(None));
293        clock.rewind_for_test(Duration::from_secs(10 * 24 * 60 * 60));
294        assert!(!clock.exhausted(), "the default never stops a turn");
295    }
296
297    /// Code mode and headless exec sleep toward what is left of the default
298    /// budget; a near-`Duration::MAX` sleep must park, not panic.
299    #[tokio::test]
300    async fn an_unbounded_remaining_budget_is_a_safe_sleep() {
301        let remaining = DEFAULT_TURN_WALL_CLOCK.saturating_sub(Duration::from_secs(1));
302        let woke =
303            tokio::time::timeout(Duration::from_millis(20), tokio::time::sleep(remaining)).await;
304        assert!(woke.is_err(), "the sleep parks until cancelled");
305        let started = std::time::Instant::now();
306        assert!(started.checked_add(remaining).is_none());
307    }
308
309    #[test]
310    fn turn_wall_clock_preserves_the_owner_limit() {
311        assert_eq!(resolve_turn_wall_clock(Some(120)), Duration::from_secs(120));
312        assert_eq!(resolve_turn_wall_clock(Some(1)), Duration::from_secs(1));
313        assert_eq!(
314            resolve_turn_wall_clock(Some(u64::MAX)),
315            Duration::from_secs(u64::MAX)
316        );
317    }
318
319    #[test]
320    fn stream_caps_default_reject_zero_and_are_overridable() {
321        assert_eq!(
322            resolve_stream_max_content_bytes(None),
323            DEFAULT_STREAM_MAX_CONTENT_BYTES
324        );
325        assert_eq!(
326            resolve_stream_max_content_bytes(Some(0)),
327            DEFAULT_STREAM_MAX_CONTENT_BYTES
328        );
329        assert_eq!(resolve_stream_max_content_bytes(Some(1)), 1024 * 1024);
330        assert_eq!(
331            resolve_stream_max_content_bytes(Some(u64::MAX)),
332            MAX_STREAM_MAX_CONTENT_BYTES
333        );
334
335        assert_eq!(
336            resolve_stream_max_duration_secs(None),
337            DEFAULT_STREAM_MAX_DURATION_SECS
338        );
339        assert_eq!(
340            resolve_stream_max_duration_secs(Some(0)),
341            DEFAULT_STREAM_MAX_DURATION_SECS
342        );
343        assert_eq!(resolve_stream_max_duration_secs(Some(60)), 60);
344        assert_eq!(
345            resolve_stream_max_duration_secs(Some(u64::MAX)),
346            MAX_STREAM_MAX_DURATION_SECS
347        );
348    }
349
350    #[test]
351    fn stream_retry_limits_default_to_historical_values_and_clamp() {
352        let defaults = resolve_stream_retry_limits(None, None, None);
353        assert_eq!(defaults, StreamRetryLimits::default());
354        assert_eq!(defaults.max_resumes, 3);
355        assert_eq!(defaults.max_transparent_retries, 2);
356        assert_eq!(defaults.max_errors, 5);
357
358        let disabled = resolve_stream_retry_limits(Some(0), Some(0), Some(0));
359        assert_eq!(disabled.max_resumes, 0, "0 disables resumes");
360        assert_eq!(disabled.max_transparent_retries, 0);
361        assert_eq!(
362            disabled.max_errors, DEFAULT_STREAM_MAX_ERRORS,
363            "0 selects the error-streak default, like the other finite stream budgets"
364        );
365        assert_eq!(
366            resolve_stream_retry_limits(None, None, Some(1)).max_errors,
367            MIN_STREAM_MAX_ERRORS
368        );
369
370        let huge = resolve_stream_retry_limits(Some(u32::MAX), Some(u32::MAX), Some(u32::MAX));
371        assert_eq!(huge.max_resumes, MAX_STREAM_MAX_RESUMES);
372        assert_eq!(
373            huge.max_transparent_retries,
374            MAX_STREAM_MAX_TRANSPARENT_RETRIES
375        );
376        assert_eq!(huge.max_errors, MAX_STREAM_MAX_ERRORS);
377    }
378
379    #[test]
380    fn wall_clock_exhausts_once_the_budget_is_spent() {
381        let mut clock = TurnWallClock::start(Duration::from_secs(60));
382        assert!(!clock.exhausted());
383        clock.rewind_for_test(Duration::from_secs(61));
384        assert!(clock.exhausted());
385        assert!(clock.spent() >= clock.budget());
386    }
387
388    #[test]
389    fn wall_clock_excludes_time_blocked_on_a_human_decision() {
390        let mut clock = TurnWallClock::start(Duration::from_secs(60));
391        clock.begin_human_wait();
392        // The human took two minutes; the agent spent none of its budget.
393        clock.rewind_for_test(Duration::from_secs(120));
394        assert!(
395            !clock.exhausted(),
396            "an unanswered approval prompt must not burn the turn budget"
397        );
398        clock.end_human_wait();
399        assert!(!clock.exhausted());
400        // Agent-owned time after the decision still counts.
401        clock.rewind_for_test(Duration::from_secs(61));
402        assert!(clock.exhausted());
403    }
404
405    #[test]
406    fn nested_human_waits_cannot_double_exclude() {
407        let mut clock = TurnWallClock::start(Duration::from_secs(60));
408        clock.begin_human_wait();
409        clock.begin_human_wait();
410        clock.rewind_for_test(Duration::from_secs(30));
411        clock.end_human_wait();
412        // A second unmatched end is a no-op, not another exclusion.
413        clock.end_human_wait();
414        clock.rewind_for_test(Duration::from_secs(61));
415        assert!(clock.exhausted());
416    }
417}