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}