Skip to main content

session_core/
context_reminder.rs

1//! The context-pressure reminder (Rust-only; TypeScript has none): when a lane's context nears the point where the
2//! harness compacts it, the lane's next `rlm` result ends with one `[context: ...]` line telling the model to free
3//! space with `ctx` itself. Models given one reminder shortly before the budget edit their context; without one they
4//! rarely do ("Context Language Models", arXiv 2609.37725).
5//!
6//! - The limit is the compaction threshold, `contextWindow - reserveTokens` (with auto-compaction off the same
7//!   number, the usable window). The reminder triggers at `limit - margin`, where the margin is
8//!   `max(2048, contextWindow / 10)`; `ULTRON_CONTEXT_REMINDER_TOKENS=<n>` sets it, `ULTRON_CONTEXT_REMINDER=off`
9//!   (`0`, `false`) disables the reminder.
10//! - The context use is the estimate the harness compacts by: the newest answer's usage plus estimates of the
11//!   messages after it (the session actor wires that meter, [`ContextReminders::set_meter`]), plus this result
12//!   (its text, and 4,800 characters per image as the compaction estimator counts one). An inference frame's lane
13//!   (`rlm.infer` / `rlm.map` with depth) measures its own conversation the same way against the frame model's
14//!   window ([`ContextReminders::set_frame_lane`]).
15//! - Successful results, error results (a raised exception, a kernel failure) and the completion message of a cell
16//!   that kept running in the background (`cell_done`) all carry it; an aborted cell does not.
17//! - Once per approach: a lane that was reminded is not reminded again until its use fell below the trigger (after
18//!   `ctx` edits) or its context was compacted.
19//! - Every lane whose model has a known window, except lanes on Claude Code (`claude-code/*`, whose context is Claude
20//!   Code's) and the external Claude Code root (no session actor, so no meter).
21
22use jsrt::sync;
23use std::collections::HashMap;
24use std::sync::{Arc, Mutex, OnceLock};
25
26/// The smallest margin before the limit (the paper's 2,048 tokens).
27pub const MIN_MARGIN: u64 = 2048;
28
29/// Whether reminders are on, and the margin the environment sets.
30#[derive(Clone, Copy, Debug, PartialEq, Eq)]
31pub struct ReminderSettings {
32    pub enabled: bool,
33    pub margin: Option<u64>,
34}
35
36impl ReminderSettings {
37    /// From `ULTRON_CONTEXT_REMINDER` (`off`, `0`, `false`: disabled) and `ULTRON_CONTEXT_REMINDER_TOKENS` (a
38    /// non-negative integer; anything else keeps the default margin).
39    pub fn from_vars(reminder: Option<&str>, tokens: Option<&str>) -> ReminderSettings {
40        ReminderSettings {
41            enabled: !crate::flag_off(reminder),
42            margin: tokens.and_then(|value| value.trim().parse::<u64>().ok()),
43        }
44    }
45}
46
47/// The margin before the limit: the environment's, else `max(2048, 10% of the context window)`.
48pub fn margin(context_window: u64, configured: Option<u64>) -> u64 {
49    configured.unwrap_or_else(|| MIN_MARGIN.max(context_window / 10))
50}
51
52/// Where a lane's context runs out: the compaction threshold, or with auto-compaction off the usable window.
53#[derive(Clone, Copy, Debug, PartialEq, Eq)]
54pub struct Limit {
55    pub context_window: u64,
56    pub reserve_tokens: u64,
57    /// Whether auto-compaction is on (it compacts at the limit).
58    pub compaction: bool,
59}
60
61impl Limit {
62    /// `contextWindow - reserveTokens`.
63    pub fn tokens(&self) -> u64 {
64        self.context_window.saturating_sub(self.reserve_tokens)
65    }
66
67    /// The use at which the reminder shows.
68    pub fn trigger(&self, configured_margin: Option<u64>) -> u64 {
69        self.tokens()
70            .saturating_sub(margin(self.context_window, configured_margin))
71    }
72}
73
74/// The limit of a lane on `model` whose compaction is `compaction` (on or off) with `reserve_tokens`; none on Claude
75/// Code (`claude-code/*`), which manages its own context.
76pub fn lane_limit(model: &ai::Model, compaction: bool, reserve_tokens: u64) -> Option<Limit> {
77    (model.provider != ai::claude_code::PROVIDER).then_some(Limit {
78        context_window: model.context_window,
79        reserve_tokens,
80        compaction,
81    })
82}
83
84/// A token count as the reminder shows it: below 1,000 as is, else in thousands to one decimal (rounded down).
85pub fn format_tokens(tokens: u64) -> String {
86    if tokens < 1000 {
87        return tokens.to_string();
88    }
89    let tenths = tokens / 100;
90    match tenths % 10 {
91        0 => format!("{}k", tenths / 10),
92        decimal => format!("{}.{decimal}k", tenths / 10),
93    }
94}
95
96pub fn reminder_line(used: u64, limit: &Limit) -> String {
97    let at = if limit.compaction {
98        "before compaction"
99    } else {
100        "before the context limit"
101    };
102    format!(
103        "[context: {} of {} tokens used {at}; free space with ctx now: await ctx.history() lists items with their bytes, await ctx.forget(ids, reason) or await ctx.summarize(ids, text) drops or shortens them]",
104        format_tokens(used),
105        format_tokens(limit.tokens())
106    )
107}
108
109/// A lane's context use: `tokens`, and `epoch`, which changes when the context is compacted (the summary's entry).
110#[derive(Clone, Copy, Debug, PartialEq, Eq)]
111pub struct Measure {
112    pub tokens: u64,
113    pub epoch: Option<u64>,
114}
115
116/// A lane's context use before its cell result, if known.
117pub type ContextMeter = Arc<dyn Fn(&str) -> Option<Measure> + Send + Sync>;
118
119/// One lane's own context use (an inference frame's conversation, which has no durable conversation).
120pub type LaneMeter = Arc<dyn Fn() -> Option<u64> + Send + Sync>;
121
122/// The characters an image counts as in the estimate, as the compaction estimator counts it (`estimateTokens`).
123pub const ESTIMATED_IMAGE_CHARS: u64 = 4800;
124
125#[derive(Default)]
126struct LaneState {
127    /// Reminded since the use last fell below the trigger or the context was compacted.
128    reminded: bool,
129    epoch: Option<u64>,
130}
131
132/// Every lane's reminder state, its limit and the meter of its context use.
133pub struct ContextReminders {
134    settings: ReminderSettings,
135    limits: Mutex<HashMap<String, Limit>>,
136    lanes: Mutex<HashMap<String, LaneState>>,
137    meter: OnceLock<ContextMeter>,
138    lane_meters: Mutex<HashMap<String, LaneMeter>>,
139}
140
141impl ContextReminders {
142    pub fn new(settings: ReminderSettings) -> ContextReminders {
143        ContextReminders {
144            settings,
145            limits: Mutex::default(),
146            lanes: Mutex::default(),
147            meter: OnceLock::new(),
148            lane_meters: Mutex::default(),
149        }
150    }
151
152    pub fn settings(&self) -> ReminderSettings {
153        self.settings
154    }
155
156    /// Where the lane's context use comes from (the session actor's durable conversations).
157    pub fn set_meter(&self, meter: ContextMeter) {
158        let _ = self.meter.set(meter);
159    }
160
161    /// The limit of `lane` from now on: its model and compaction settings; `None` (a lane on Claude Code, a model
162    /// without a known window): no reminders.
163    pub fn set_limit(&self, lane: &str, limit: Option<Limit>) {
164        let mut limits = sync::lock(&self.limits);
165        match limit.filter(|limit| limit.context_window > 0) {
166            Some(limit) => limits.insert(lane.to_string(), limit),
167            None => limits.remove(lane),
168        };
169    }
170
171    /// `lane`'s own context meter (an in-memory subagent's loop, crate::memory_children), its limit unchanged;
172    /// `None` returns it to the session's meter.
173    pub fn set_lane_meter(&self, lane: &str, meter: Option<LaneMeter>) {
174        match meter {
175            Some(meter) => sync::lock(&self.lane_meters).insert(lane.to_string(), meter),
176            None => sync::lock(&self.lane_meters).remove(lane),
177        };
178    }
179
180    /// An inference frame's lane (crate::frames): its own meter (the frame conversation's estimate) and its limit,
181    /// the frame model's window (frames never compact). `None` ends both (the frame ended).
182    pub fn set_frame_lane(&self, lane: &str, frame: Option<(Limit, LaneMeter)>) {
183        match frame {
184            Some((limit, meter)) => {
185                self.set_limit(lane, Some(limit));
186                sync::lock(&self.lane_meters).insert(lane.to_string(), meter);
187            }
188            None => {
189                self.set_limit(lane, None);
190                sync::lock(&self.lane_meters).remove(lane);
191                sync::lock(&self.lanes).remove(lane);
192            }
193        }
194    }
195
196    pub fn limit(&self, lane: &str) -> Option<Limit> {
197        sync::lock(&self.limits).get(lane).copied()
198    }
199
200    /// The lane's context was compacted: its next result past the trigger reminds again.
201    pub fn rearm(&self, lane: &str) {
202        if let Some(state) = sync::lock(&self.lanes).get_mut(lane) {
203            state.reminded = false;
204        }
205    }
206
207    /// The lane's use is `measure`: the reminder line when it reached the trigger and the lane was not reminded
208    /// in this approach; below the trigger (or in a new epoch) the lane is re-armed.
209    pub fn observe(&self, lane: &str, measure: Measure) -> Option<String> {
210        if !self.settings.enabled {
211            return None;
212        }
213        let limit = self.limit(lane)?;
214        let mut lanes = sync::lock(&self.lanes);
215        let state = lanes.entry(lane.to_string()).or_default();
216        if state.epoch != measure.epoch {
217            state.epoch = measure.epoch;
218            state.reminded = false;
219        }
220        if measure.tokens < limit.trigger(self.settings.margin) {
221            state.reminded = false;
222            return None;
223        }
224        if state.reminded {
225            return None;
226        }
227        state.reminded = true;
228        Some(reminder_line(measure.tokens, &limit))
229    }
230
231    /// The reminder for `lane`'s result `text` with `images` images: the meter's use plus the result's own estimate,
232    /// as the harness estimates a tool result (`ceil(chars / 4)`, an image counting
233    /// [`ESTIMATED_IMAGE_CHARS`]). A lane with its own meter (a frame) reads that one.
234    pub fn reminder(&self, lane: &str, text: &str, images: usize) -> Option<String> {
235        if !self.settings.enabled {
236            return None;
237        }
238        let own = sync::lock(&self.lane_meters).get(lane).cloned();
239        let measure = match own {
240            Some(meter) => Measure {
241                tokens: meter()?,
242                epoch: None,
243            },
244            None => (self.meter.get()?)(lane)?,
245        };
246        let chars = text.encode_utf16().count() as u64 + images as u64 * ESTIMATED_IMAGE_CHARS;
247        self.observe(
248            lane,
249            Measure {
250                tokens: measure.tokens + chars.div_ceil(4),
251                epoch: measure.epoch,
252            },
253        )
254    }
255}