1use std::time::{Duration, Instant};
22
23pub const DEFAULT_MAX_MODEL_STEPS: u32 = u32::MAX;
26
27pub const DEFAULT_TURN_WALL_CLOCK: Duration = Duration::MAX;
37
38pub const DEFAULT_STREAM_MAX_CONTENT_BYTES: usize = 10 * 1024 * 1024;
42pub const MIN_STREAM_MAX_CONTENT_BYTES: usize = 64 * 1024;
44pub const MAX_STREAM_MAX_CONTENT_BYTES: usize = 512 * 1024 * 1024;
46
47pub const DEFAULT_STREAM_MAX_DURATION_SECS: u64 = 1800;
62pub const MIN_STREAM_MAX_DURATION_SECS: u64 = 10;
64pub const MAX_STREAM_MAX_DURATION_SECS: u64 = 86_400;
66
67pub const DEFAULT_STREAM_MAX_RESUMES: u32 = 3;
70pub const MAX_STREAM_MAX_RESUMES: u32 = 10;
72pub const DEFAULT_STREAM_MAX_TRANSPARENT_RETRIES: u32 = 2;
74pub const MAX_STREAM_MAX_TRANSPARENT_RETRIES: u32 = 10;
76pub const DEFAULT_STREAM_MAX_ERRORS: u32 = 5;
79pub const MIN_STREAM_MAX_ERRORS: u32 = 1;
81pub const MAX_STREAM_MAX_ERRORS: u32 = 50;
83
84#[derive(Debug, Clone, Copy, PartialEq, Eq)]
87pub struct StreamRetryLimits {
88 pub max_resumes: u32,
90 pub max_transparent_retries: u32,
92 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#[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#[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#[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#[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#[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#[derive(Debug)]
189pub struct TurnWallClock {
190 budget: Duration,
191 started_at: Instant,
192 excluded: Duration,
194 blocked_since: Option<Instant>,
196}
197
198impl TurnWallClock {
199 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 pub fn budget(&self) -> Duration {
213 self.budget
214 }
215
216 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 pub fn exhausted(&self) -> bool {
230 self.spent() >= self.budget
231 }
232
233 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 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 #[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 #[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 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 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 clock.end_human_wait();
414 clock.rewind_for_test(Duration::from_secs(61));
415 assert!(clock.exhausted());
416 }
417}