diff --git a/docs/4-implementation/turn-loop/claude-invocation.md b/docs/4-implementation/turn-loop/claude-invocation.md index 8b642ecc7..85fd7f1c3 100644 --- a/docs/4-implementation/turn-loop/claude-invocation.md +++ b/docs/4-implementation/turn-loop/claude-invocation.md @@ -190,7 +190,8 @@ still applies. (`HIVE_AUTO_RESET_WATERMARK_TOKENS`, default **50% of the reported window**, none until the API reports one) AND the time since the last turn exceeds the assumed prompt-cache TTL (`HIVE_CACHE_TTL_SECS`, default - `3600`). Claude's prompt cache goes cold after a while; once it's cold, + `3600`; `0` turns the check off, so an idle session is always resumed, and + the harness logs a warning at start when it's off). Claude's prompt cache goes cold after a while; once it's cold, `--resume`-ing a large session pays the full re-upload cost with no benefit over starting fresh. `drive_turn` **archives** the current session (same mechanism as the operator reset — rename `.jsonl` → diff --git a/hive-agent/src/turn.rs b/hive-agent/src/turn.rs index f39e1d68b..21d29f54c 100644 --- a/hive-agent/src/turn.rs +++ b/hive-agent/src/turn.rs @@ -272,10 +272,31 @@ fn auto_reset_watermark_tokens(bus: &Bus) -> u64 { .unwrap_or_else(|| bus.api_context_window().map_or(0, |window| window / 2)) } -/// Resolve the assumed cache TTL: `HIVE_CACHE_TTL_SECS` if set, else +/// Resolve the assumed cache TTL: `HIVE_CACHE_TTL_SECS` if set (`0` disables +/// the heuristic, as the other zero-as-off knobs here do), else /// `DEFAULT_CACHE_TTL_SECS`. fn cache_ttl_secs() -> u64 { - env_u64_positive("HIVE_CACHE_TTL_SECS", DEFAULT_CACHE_TTL_SECS) + env_u64("HIVE_CACHE_TTL_SECS").unwrap_or(DEFAULT_CACHE_TTL_SECS) +} + +/// Whether the prompt cache has presumably gone cold, given how long the +/// session has sat idle and the assumed TTL. `ttl == 0` disables the heuristic: +/// the cache is never considered cold, so the session always resumes, as +/// [`DEFAULT_CACHE_TTL_SECS`] documents. Split out of [`maybe_auto_reset`] so +/// that decision is testable without a `Bus` or the system clock. +fn cache_is_cold(idle_secs: u64, ttl: u64) -> bool { + ttl != 0 && idle_secs >= ttl +} + +/// What the harness says at start when the cache heuristic is off (`ttl == 0`), +/// or `None` when it is on. A disabled heuristic is a deliberate setting with a +/// cost: a long-idle session is resumed, re-uploading its whole transcript on a +/// cold cache, where it would otherwise be dropped for a fresh start. +fn cache_disabled_note(ttl: u64) -> Option<&'static str> { + (ttl == 0).then_some( + "HIVE_CACHE_TTL_SECS=0: the prompt-cache TTL heuristic is off, so an idle session \ + is always resumed and never reset for a cold cache", + ) } /// Proactive-compaction watermark as a percent of the effective context @@ -346,6 +367,10 @@ impl CompactionPolicy for SoftLimitPolicy { /// /// Returns an error if the runtime selection in the environment is invalid. pub fn make_session(bus: &Bus) -> Result { + if let Some(note) = cache_disabled_note(cache_ttl_secs()) { + tracing::warn!("{note}"); + bus.emit(LiveEvent::Note { text: note.into() }); + } let policy = SoftLimitPolicy { percent: PercentPolicy { percent: compact_percent(), @@ -558,7 +583,7 @@ fn maybe_auto_reset(bus: &Bus, session: &AgentSession) { .map_or(0, |d| d.as_secs()); let idle_secs = now.saturating_sub(u64::try_from(last_ended).unwrap_or(0)); let ttl = cache_ttl_secs(); - if idle_secs < ttl { + if !cache_is_cold(idle_secs, ttl) { return; } bus.emit(LiveEvent::Note { @@ -878,9 +903,9 @@ fn archive_session(bus: &Bus, session: &AgentSession) { mod tests { use super::{PercentPolicy, SoftLimitPolicy, auto_reset_watermark_tokens}; use super::{ - PermissionAsk, TurnError, TurnOutcome, acp_permits, apply_telemetry, emit_turn_end, - error_to_turn, nonzero_or, parse_u64, report_compact, runtime_error_to_turn, - with_turn_end_compact, + PermissionAsk, TurnError, TurnOutcome, acp_permits, apply_telemetry, cache_disabled_note, + cache_is_cold, emit_turn_end, error_to_turn, nonzero_or, parse_u64, report_compact, + runtime_error_to_turn, with_turn_end_compact, }; use crate::events::{Bus, LiveEvent}; use hive_claude::{CompactionPolicy, Usage}; @@ -957,6 +982,25 @@ mod tests { assert!(policy.should_compact(reported)); } + /// A TTL of 0 turns the heuristic off: the cache is never cold, however + /// long the session idled. Any other TTL is cold once the idle time reaches it. + #[test] + fn a_zero_cache_ttl_never_calls_the_cache_cold() { + assert!(!cache_is_cold(0, 0)); + assert!(!cache_is_cold(u64::MAX, 0)); + assert!(!cache_is_cold(3599, 3600)); + assert!(cache_is_cold(3600, 3600)); + assert!(cache_is_cold(9_999, 3600)); + } + + /// The start-up warning names the setting, and only when it is off. + #[test] + fn the_start_up_warning_appears_only_when_the_cache_heuristic_is_off() { + assert!(cache_disabled_note(0).is_some_and(|n| n.contains("HIVE_CACHE_TTL_SECS=0"))); + assert_eq!(cache_disabled_note(3600), None); + assert_eq!(cache_disabled_note(300), None); + } + #[test] fn a_turn_that_parsed_nothing_does_not_keep_the_previous_resolved_model() { let resolved = crate::paths::with_harness_dir(|| {