Skip to main content

session_core/
auto_compaction.rs

1//! Automatic compaction of the root lane: the settings it runs with and when it starts. The session worker's
2//! harness (packages/agent/src/harness/runtime/drive) compacts at a run's checkpoints, before the run ends or before
3//! its next request, when the context crosses `contextWindow - reserveTokens` (`checkpoint.ts`,
4//! `prepareCompactionThreshold`), and on a response that overflowed the window, compacting and retrying the request
5//! once (`response.ts`, `publishResponse`). The session actor runs both ([`crate::core`]); this module is the
6//! arithmetic and the classification, ported from pi-ai `isContextOverflow` / `isRecoverableLength` and the settings
7//! manager's `getCompactionSettings`.
8
9use ai::{AssistantMessage, StopReason};
10use compaction::CompactionSettings;
11use serde_json::Value;
12
13/// Why an automatic compaction runs (`compaction_start.reason`).
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15pub enum Reason {
16    Threshold,
17    Overflow,
18}
19
20impl Reason {
21    pub fn name(self) -> &'static str {
22        match self {
23            Reason::Threshold => "threshold",
24            Reason::Overflow => "overflow",
25        }
26    }
27
28    pub fn parse(name: &str) -> Option<Reason> {
29        match name {
30            "threshold" => Some(Reason::Threshold),
31            "overflow" => Some(Reason::Overflow),
32            _ => None,
33        }
34    }
35}
36
37/// `getCompactionTokenSetting`: a token setting must be a non-negative safe integer.
38fn token_setting(value: Option<&Value>, what: &str) -> Result<Option<u64>, String> {
39    let Some(value) = value else { return Ok(None) };
40    match value.as_f64() {
41        Some(n) if jsrt::number::is_safe_integer(n) && n >= 0.0 && value.is_number() => Ok(Some(n as u64)),
42        _ => Err(format!(
43            "Invalid {what} setting: {}. Expected a non-negative safe integer.",
44            jsrt::value::string(Some(value))
45        )),
46    }
47}
48
49/// `getCompactionSettings(model)`: `compaction.enabled` (default on), and each token setting from the model's
50/// `compaction.modelOverrides["provider/id"]`, else the ordinary setting, else the default (16384 reserved, 20000
51/// kept). `enabled` overrides the setting (`set_auto_compaction` on a live session).
52pub fn settings(
53    settings: &Value,
54    provider: &str,
55    model_id: &str,
56    enabled: Option<bool>,
57) -> Result<CompactionSettings, String> {
58    let defaults = CompactionSettings::default();
59    let compaction = settings.get("compaction");
60    let key = format!("{provider}/{model_id}");
61    let resolve = |field: &str, fallback: u64| -> Result<u64, String> {
62        let ordinary = token_setting(compaction.and_then(|c| c.get(field)), &format!("compaction.{field}"))?;
63        let entry = compaction
64            .and_then(|c| c.get("modelOverrides"))
65            .and_then(|o| o.get(&key));
66        if let Some(entry) = entry
67            && !entry.is_object()
68        {
69            return Err(format!(
70                "Invalid compaction.modelOverrides[\"{key}\"] setting: {}. Expected an object.",
71                jsrt::value::string(Some(entry))
72            ));
73        }
74        let overridden = token_setting(
75            entry.and_then(|e| e.get(field)),
76            &format!("compaction.modelOverrides[\"{key}\"].{field}"),
77        )?;
78        Ok(overridden.or(ordinary).unwrap_or(fallback))
79    };
80    let reserve_tokens = resolve("reserveTokens", defaults.reserve_tokens)?;
81    let keep_recent_tokens = resolve("keepRecentTokens", defaults.keep_recent_tokens)?;
82    // `compaction.enabled ?? true`, as JavaScript reads it.
83    let configured = match compaction.and_then(|c| c.get("enabled")) {
84        None | Some(Value::Null) => true,
85        Some(Value::Bool(on)) => *on,
86        Some(Value::Number(n)) => n.as_f64().is_some_and(|n| n != 0.0 && !n.is_nan()),
87        Some(Value::String(text)) => !text.is_empty(),
88        Some(_) => true,
89    };
90    Ok(CompactionSettings {
91        enabled: enabled.unwrap_or(configured),
92        reserve_tokens,
93        keep_recent_tokens,
94    })
95}
96
97/// pi-ai `isContextOverflow(message, contextWindow)`: an error a provider uses for an oversized request, a successful
98/// response whose input exceeds the window (silent overflow), or a length stop with no output that filled it.
99pub fn is_context_overflow(message: &AssistantMessage, context_window: u64) -> bool {
100    if harness::chat::models::is_context_overflow(message) {
101        return true;
102    }
103    let input = message.usage.input + message.usage.cache_read;
104    if context_window > 0 && message.stop_reason == StopReason::Stop && input > context_window {
105        return true;
106    }
107    context_window > 0
108        && message.stop_reason == StopReason::Length
109        && message.usage.output == 0
110        && input as f64 >= context_window as f64 * 0.99
111}
112
113/// pi-ai `isRecoverableLength`: a length stop below the output limit the request asked for.
114pub fn is_recoverable_length(message: &AssistantMessage, desired_max_output: u64) -> bool {
115    message.stop_reason == StopReason::Length && desired_max_output > 0 && message.usage.output < desired_max_output
116}
117
118/// `publishResponse`'s overflow: the response overflowed the window, or stopped for length below the requested
119/// limit; either one compacts and retries once.
120pub fn overflowed(message: &AssistantMessage, context_window: u64, intended_output_limit: u64) -> bool {
121    is_context_overflow(message, context_window) || is_recoverable_length(message, intended_output_limit)
122}
123
124/// `normalizeError`: an overflowed response as the error it is committed as.
125pub fn as_error(message: &AssistantMessage) -> AssistantMessage {
126    let mut error = message.clone();
127    error.error_message = Some(
128        message
129            .error_message
130            .clone()
131            .unwrap_or_else(|| "Assistant request exceeded the context window".into()),
132    );
133    error.stop_reason = StopReason::Error;
134    error
135}
136
137/// Whether a threshold compaction can be due at all: automatic compaction is on and the model has a window. The cheap
138/// half of [`threshold_due`], for callers that would otherwise build the whole context to learn nothing is due.
139pub fn may_be_due(settings: &CompactionSettings, context_window: u64) -> bool {
140    settings.enabled && context_window != 0
141}
142
143/// `prepareCompactionThreshold`: a threshold compaction is due at a checkpoint when compaction is on, the branch has
144/// no compaction at or after the checkpoint's trigger entry, and the context leaves less than `reserveTokens` of the
145/// window. `path` is the branch, oldest first; `tokens_before` the preparation's context estimate.
146pub fn threshold_due<V: std::borrow::Borrow<Value>>(
147    settings: &CompactionSettings,
148    path: &[V],
149    trigger: Option<&str>,
150    tokens_before: u64,
151    context_window: u64,
152) -> bool {
153    if !may_be_due(settings, context_window) {
154        return false;
155    }
156    let newest_compaction = path.iter().rposition(|e| e.borrow()["type"] == "compaction");
157    let trigger_index = trigger.and_then(|t| path.iter().position(|e| e.borrow()["id"] == t));
158    if let Some(compaction) = newest_compaction
159        && trigger_index.is_none_or(|trigger| compaction >= trigger)
160    {
161        return false;
162    }
163    compaction::should_compact(tokens_before, context_window, settings)
164}