Skip to main content

kernel_apis/
context_control.rs

1//! `ctx.*` (port of the request side of `ultron/context-control.ts`) and the context-edit semantics it relies on
2//! (`applyContextEdits` / `contextEditsOf` of `packages/agent/src/harness/session/context.ts`).
3//!
4//! The model edits what it sees, never the durable transcript: every change is an entry appended to the calling
5//! lane's conversation branch (a `context_edit` custom entry for forget/summarize, its own custom entries for pins
6//! and notes), and only that branch sees it. Guard rails: the current user message, a tool call still waiting for
7//! its result, and pinned items are never edited; entries before the newest compaction are out of reach. A summary
8//! moves tool calls and their results together. Entries appended while a turn runs are not on the branch until the
9//! turn's next boundary; this module keeps them as pending so later reads in the same cell already see them.
10//!
11//! The branch itself lives in the session/harness: [`ContextBranches`] is what this module reads and appends.
12//! Entries are the TS `Entry` JSON (`{id, parentId, seq, timestamp, type, ...}`).
13
14use crate::util::{Clock, system_clock};
15use crate::{ApiModule, Request};
16use serde_json::{Map, Value, json};
17use session_journal::context::{
18    Applied, CONTEXT_EDIT_CUSTOM_TYPE, CONTEXT_OMITTED_CUSTOM_TYPE, apply_context_edits_marked, content_call_ids,
19    context_edits_of,
20};
21use std::collections::HashSet;
22use std::sync::{Arc, Mutex};
23
24pub const COMPACTION_TRIM_ENV: &str = "ULTRON_COMPACTION_TRIM";
25
26pub const CONTEXT_NOTE_CUSTOM_TYPE: &str = "ultron:context-note";
27pub const CONTEXT_PIN_CUSTOM_TYPE: &str = "ultron:context-pin";
28/// Custom message type of a note in the model's context.
29pub const CONTEXT_NOTE_MESSAGE_TYPE: &str = "ultron-note";
30
31/// `CONTEXT_ENTRY_PROJECTORS[CONTEXT_NOTE_CUSTOM_TYPE]`: a note is a custom message at its place in the branch
32/// ("Note (ctx.note): ..."); a note without text projects nothing.
33pub fn project_note(entry: &Value) -> Vec<Value> {
34    match entry["data"].get("text").and_then(Value::as_str) {
35        Some(text) if !text.is_empty() => vec![json!({"role": "custom", "customType": CONTEXT_NOTE_MESSAGE_TYPE,
36            "content": format!("Note (ctx.note): {text}"), "display": true, "timestamp": entry["timestamp"]})],
37        _ => Vec::new(),
38    }
39}
40
41const HISTORY_DEFAULT: i64 = 20;
42const HISTORY_MAX: i64 = 200;
43const PREVIEW_CHARS: usize = 160;
44const NOTE_MAX_CHARS: usize = 4000;
45const SUMMARY_MAX_CHARS: usize = 8000;
46const REASON_MAX_CHARS: usize = 500;
47const COLLAPSE_HEAD_CHARS: usize = 200;
48const COLLAPSE_MAX_TASKS: usize = 8;
49const TRIM_HEAD_CHARS: usize = 4096;
50const TRIM_TAIL_CHARS: usize = 1024;
51const STATE_LIST_MAX: usize = 20;
52const KINDS: &[&str] = &["user", "assistant", "tool", "custom", "note", "summary", "compaction"];
53
54/// The conversation branches of the session's lanes, as the harness keeps them.
55pub trait ContextBranches: Send + Sync {
56    /// The lane's committed branch, oldest first.
57    fn entries(&self, lane: &str) -> Result<Vec<Value>, String>;
58    /// Appends a custom entry (at once, or at the running turn's next boundary); returns its id.
59    fn append_custom(&self, lane: &str, custom_type: &str, data: &Value) -> Result<String, String>;
60    /// Id of the branch's newest committed entry.
61    fn tip_id(&self, lane: &str) -> Result<Option<String>, String>;
62}
63
64/// Readable text of a message, for previews and kept items (`messageText`).
65pub fn message_text(message: &Value) -> String {
66    match message.get("content") {
67        Some(Value::String(text)) => return text.clone(),
68        Some(Value::Array(parts)) => {
69            let texts: Vec<String> = parts
70                .iter()
71                .map(|part| {
72                    if !part.is_object() {
73                        return String::new();
74                    }
75                    match part["type"].as_str() {
76                        Some("text") => part["text"].as_str().unwrap_or_default().to_string(),
77                        Some("thinking") => part["thinking"].as_str().unwrap_or_default().to_string(),
78                        Some("toolCall") => {
79                            let name = match &part["name"] {
80                                Value::String(name) => name.clone(),
81                                Value::Null if part.get("name").is_none() => "undefined".into(),
82                                other => jsrt::json::stringify(other),
83                            };
84                            let arguments = match part.get("arguments") {
85                                Some(value) if !value.is_null() => jsrt::json::stringify(value),
86                                _ => "{}".into(),
87                            };
88                            format!("{name}({})", jsrt::utf16::head(&arguments, 2000))
89                        }
90                        Some("image") => "[image]".into(),
91                        _ => String::new(),
92                    }
93                })
94                .filter(|text| !text.is_empty())
95                .collect();
96            return texts.join("\n");
97        }
98        _ => {}
99    }
100    for key in ["summary", "output"] {
101        if let Some(Value::String(text)) = message.get(key) {
102            return text.clone();
103        }
104    }
105    String::new()
106}
107
108/// `oneLine`: whitespace runs collapsed to one space, trimmed, cut to `max` UTF-16 units with an ellipsis.
109fn one_line(text: &str, max: usize) -> String {
110    let flat = jsrt::string::flatten(text);
111    let flat = flat.as_str();
112    if jsrt::utf16::len(flat) > max {
113        format!("{}…", jsrt::utf16::head(flat, max - 1))
114    } else {
115        flat.to_string()
116    }
117}
118
119fn note_text(entry: &Value) -> String {
120    if entry["type"] == "custom"
121        && let Some(text) = entry["data"].get("text").and_then(Value::as_str)
122    {
123        return text.to_string();
124    }
125    String::new()
126}
127
128fn entry_bytes(entry: &Value) -> usize {
129    match entry["type"].as_str() {
130        Some("message") => {
131            let message = &entry["message"];
132            match message.get("content") {
133                Some(content) if !content.is_null() => jsrt::json::stringify(content).len(),
134                _ => jsrt::json::stringify(&Value::String(message_text(message))).len(),
135            }
136        }
137        Some("compaction" | "branch_summary") => entry["summary"].as_str().map_or(0, str::len),
138        Some("custom") if entry["customType"] == CONTEXT_NOTE_CUSTOM_TYPE => note_text(entry).len(),
139        _ => 0,
140    }
141}
142
143fn kind_of(entry: &Value) -> Option<&'static str> {
144    match entry["type"].as_str()? {
145        "message" => Some(match entry["message"]["role"].as_str() {
146            Some("user") => "user",
147            Some("assistant") => "assistant",
148            Some("toolResult") => "tool",
149            _ => "custom",
150        }),
151        "compaction" => Some("compaction"),
152        "branch_summary" => Some("summary"),
153        "custom" if entry["customType"] == CONTEXT_NOTE_CUSTOM_TYPE => Some("note"),
154        _ => None,
155    }
156}
157
158fn entry_text(entry: &Value) -> String {
159    match entry["type"].as_str() {
160        Some("message") => message_text(&entry["message"]),
161        Some("compaction" | "branch_summary") => entry["summary"].as_str().unwrap_or_default().to_string(),
162        _ => note_text(entry),
163    }
164}
165
166fn tool_call_ids(message: &Value) -> Vec<String> {
167    if message["role"] != "assistant" {
168        return Vec::new();
169    }
170    content_call_ids(&message["content"])
171}
172
173fn is_uuid(value: &str) -> bool {
174    let bytes = value.as_bytes();
175    bytes.len() == 36
176        && bytes.iter().enumerate().all(|(index, b)| match index {
177            8 | 13 | 18 | 23 => *b == b'-',
178            _ => b.is_ascii_hexdigit(),
179        })
180}
181
182/// A finished task as it stands in the root's context after collapse on return.
183#[derive(Debug, Clone, PartialEq)]
184pub struct TaskLine {
185    pub id: String,
186    pub definition: String,
187    pub key: String,
188    pub status: String,
189    pub cost: Option<f64>,
190}
191
192/// `taskLine`: one line that stands for a finished task.
193pub fn task_line(task: &TaskLine) -> String {
194    let key = if is_uuid(&task.key) {
195        String::new()
196    } else {
197        format!(" key={}", task.key)
198    };
199    let cost = match task.cost {
200        None => "cost=?".to_string(),
201        Some(cost) => format!("cost=${cost:.4}"),
202    };
203    format!(
204        "↳ task {} {}{key} {} {cost} · full result: await agents.result(\"{}\")",
205        task.id, task.definition, task.status, task.id
206    )
207}
208
209/// `collapsedCellText`: the collapsed form of a cell output that returned finished tasks.
210pub fn collapsed_cell_text(entry_id: &str, original: &str, tasks: &[TaskLine]) -> String {
211    let mut lines = vec![
212        format!(
213            "[collapsed on return: this cell output was {} bytes; ctx.get(\"{entry_id}\") shows it]",
214            original.len()
215        ),
216        one_line(original, COLLAPSE_HEAD_CHARS),
217    ];
218    lines.extend(tasks.iter().take(COLLAPSE_MAX_TASKS).map(task_line));
219    if tasks.len() > COLLAPSE_MAX_TASKS {
220        lines.push(format!("↳ +{} more finished tasks", tasks.len() - COLLAPSE_MAX_TASKS));
221    }
222    lines.join("\n")
223}
224
225/// `trimmedResultText`: head and tail of a tool result trimmed before compaction (UTF-16 offsets).
226pub fn trimmed_result_text(entry_id: &str, original: &str) -> String {
227    let units = jsrt::utf16::len(original);
228    let cut = units as i64 - TRIM_HEAD_CHARS as i64 - TRIM_TAIL_CHARS as i64;
229    let head = jsrt::utf16::head(original, TRIM_HEAD_CHARS);
230    let tail_start = jsrt::utf16::head(original, units.saturating_sub(TRIM_TAIL_CHARS)).len();
231    format!(
232        "{head}\n[... {cut} characters trimmed before compaction; ctx.get(\"{entry_id}\") shows them ...]\n{}",
233        &original[tail_start..]
234    )
235}
236
237#[derive(Debug, Clone)]
238struct EditInfo {
239    replacement: Option<Value>,
240    source: String,
241    reason: Option<String>,
242}
243
244/// A consistent read of one lane's branch plus this module's entries still pending behind a running turn.
245struct BranchView {
246    path: Vec<Value>,
247    compaction_index: Option<usize>,
248    /// Where the window (the entries after the last compaction) starts in `path`.
249    window_start: usize,
250    applied: Vec<Applied>,
251    /// Edit per target, in first-edit order (a later edit of the same target replaces it in place).
252    edits: Vec<(String, EditInfo)>,
253    /// Pinned ids, in pin order.
254    pins: Vec<String>,
255    protected: HashSet<String>,
256}
257
258impl BranchView {
259    fn window(&self) -> &[Value] {
260        &self.path[self.window_start..]
261    }
262    fn by_id(&self, id: &str) -> Option<&Value> {
263        self.window().iter().find(|entry| entry["id"] == id)
264    }
265    fn applied(&self, id: &str) -> Option<&Applied> {
266        self.applied.iter().find(|applied| applied.entry["id"] == id)
267    }
268    fn edit(&self, id: &str) -> Option<&EditInfo> {
269        self.edits.iter().find(|(target, _)| target == id).map(|(_, info)| info)
270    }
271    fn pinned(&self, id: &str) -> bool {
272        self.pins.iter().any(|pin| pin == id)
273    }
274}
275
276fn is_omitted(entry: &Value) -> bool {
277    entry["type"] == "custom" && entry["customType"] == CONTEXT_OMITTED_CUSTOM_TYPE
278}
279
280fn id_list(value: Option<&Value>) -> Result<Vec<String>, String> {
281    let items = value
282        .and_then(Value::as_array)
283        .filter(|items| !items.is_empty())
284        .ok_or("ids must be a nonempty list of item ids")?;
285    let ids = items
286        .iter()
287        .map(|id| jsrt::payload::nonempty_string(Some(id), "id"))
288        .collect::<Result<Vec<_>, _>>()?;
289    if ids.len() > HISTORY_MAX as usize {
290        return Err(format!("at most {HISTORY_MAX} ids per edit"));
291    }
292    let mut seen = HashSet::new();
293    Ok(ids.into_iter().filter(|id| seen.insert(id.clone())).collect())
294}
295
296/// Collapse-on-return bookkeeping and the lanes this module serves.
297#[derive(Default)]
298struct Tracking {
299    /// Root cell running now (tool call id).
300    current_cell: Option<String>,
301    /// Finished root-level tasks waiting for a cell to be attributed to.
302    unattributed: Vec<TaskLine>,
303    /// Cells (tool call ids, oldest first) whose output returned finished tasks and is not collapsed yet.
304    cells: Vec<(String, Vec<TaskLine>)>,
305    /// Per lane: tokens freed by trims since its newest assistant message (whose usage predates them).
306    trimmed: Vec<(String, String, i64)>,
307    /// Lanes that used ctx, and the root: only these carry notes and pins across compaction.
308    lanes: HashSet<String>,
309}
310
311pub struct ContextControl {
312    branches: Arc<dyn ContextBranches>,
313    clock: Clock,
314    trim: bool,
315    /// (lane, entry) appended by this module that the branch does not show yet.
316    pending: Mutex<Vec<(String, Value)>>,
317    tracking: Mutex<Tracking>,
318    /// The last `ctx.state` answer and the main branch it was read from (its tip and the ids pending on it): the TUI
319    /// asks every few seconds, and reading the branch copies all of it.
320    state_cache: Mutex<Option<(StateKey, Value)>>,
321}
322
323type StateKey = (Option<String>, Vec<String>);
324
325impl ContextControl {
326    pub fn new(branches: Arc<dyn ContextBranches>) -> Self {
327        let tracking = Tracking {
328            lanes: HashSet::from([kernel::ROOT_LANE.to_string()]),
329            ..Tracking::default()
330        };
331        Self {
332            branches,
333            clock: system_clock(),
334            trim: true,
335            pending: Mutex::new(Vec::new()),
336            tracking: Mutex::new(tracking),
337            state_cache: Mutex::new(None),
338        }
339    }
340
341    /// Trim old tool results before a threshold compaction (default on; `ULTRON_COMPACTION_TRIM=off` turns it off).
342    pub fn with_trim(mut self, trim: bool) -> Self {
343        self.trim = trim;
344        self
345    }
346
347    fn known(&self, lane: &str) {
348        jsrt::sync::lock(&self.tracking).lanes.insert(lane.to_string());
349    }
350
351    fn append(&self, lane: &str, custom_type: &str, data: Value) -> Result<String, String> {
352        let id = self.branches.append_custom(lane, custom_type, &data)?;
353        // While a turn runs the entry waits for the next boundary; later reads in this cell must already see it.
354        if self.branches.tip_id(lane)?.as_deref() != Some(id.as_str()) {
355            jsrt::sync::lock(&self.pending).push((
356                lane.to_string(),
357                json!({"id": id, "parentId": null, "seq": jsrt::number::MAX_SAFE_INTEGER, "timestamp": (self.clock)(),
358                    "type": "custom", "customType": custom_type, "data": data}),
359            ));
360        }
361        Ok(id)
362    }
363
364    fn view(&self, lane: &str) -> Result<BranchView, String> {
365        let committed = self.branches.entries(lane)?;
366        let committed_ids: HashSet<&str> = committed.iter().filter_map(|entry| entry["id"].as_str()).collect();
367        let mut pending = jsrt::sync::lock(&self.pending);
368        pending.retain(|(_, entry)| !entry["id"].as_str().is_some_and(|id| committed_ids.contains(id)));
369        let mut path = committed;
370        path.extend(
371            pending
372                .iter()
373                .filter(|(owner, _)| owner == lane)
374                .map(|(_, entry)| entry.clone()),
375        );
376        drop(pending);
377        let compaction_index = path.iter().rposition(|entry| entry["type"] == "compaction");
378        let window_start = compaction_index.map_or(0, |index| index + 1);
379        let window = &path[window_start..];
380        let applied = apply_context_edits_marked(window);
381        let mut edits: Vec<(String, EditInfo)> = Vec::new();
382        for entry in window {
383            let data = if entry["type"] == "custom" && entry["data"].is_object() {
384                &entry["data"]
385            } else {
386                &Value::Null
387            };
388            for edit in context_edits_of(entry) {
389                let info = EditInfo {
390                    replacement: edit.replacement,
391                    source: data["source"].as_str().unwrap_or("unknown").to_string(),
392                    reason: data["reason"].as_str().map(str::to_string),
393                };
394                match edits.iter_mut().find(|(target, _)| *target == edit.target_id) {
395                    Some(slot) => slot.1 = info,
396                    None => edits.push((edit.target_id, info)),
397                }
398            }
399        }
400        let mut pins: Vec<String> = Vec::new();
401        for entry in &path {
402            if entry["type"] != "custom" || entry["customType"] != CONTEXT_PIN_CUSTOM_TYPE || !entry["data"].is_object()
403            {
404                continue;
405            }
406            let Some(target) = entry["data"]["targetId"].as_str() else {
407                continue;
408            };
409            pins.retain(|pin| pin != target);
410            if entry["data"]["pinned"] != false {
411                pins.push(target.to_string());
412            }
413        }
414        // The current user message, and a tool call still waiting for its result, are never edited.
415        let mut protected = HashSet::new();
416        if let Some(user) = window
417            .iter()
418            .rev()
419            .find(|entry| entry["type"] == "message" && entry["message"]["role"] == "user")
420        {
421            protected.insert(user["id"].as_str().unwrap_or_default().to_string());
422        }
423        let results: HashSet<&str> = window
424            .iter()
425            .filter(|entry| entry["type"] == "message" && entry["message"]["role"] == "toolResult")
426            .filter_map(|entry| entry["message"]["toolCallId"].as_str())
427            .collect();
428        for entry in window {
429            if entry["type"] == "message"
430                && tool_call_ids(&entry["message"])
431                    .iter()
432                    .any(|id| !results.contains(id.as_str()))
433            {
434                protected.insert(entry["id"].as_str().unwrap_or_default().to_string());
435            }
436        }
437        Ok(BranchView {
438            path,
439            compaction_index,
440            window_start,
441            applied,
442            edits,
443            pins,
444            protected,
445        })
446    }
447
448    fn item(view: &BranchView, entry: &Value) -> Option<Value> {
449        let kind = kind_of(entry)?;
450        let id = entry["id"].as_str().unwrap_or_default();
451        let visible = view.applied(id);
452        let omitted = visible.is_some_and(|applied| is_omitted(&applied.entry));
453        let own = view.edit(id);
454        let mut state = "visible";
455        if own.is_some() || omitted || visible.is_none_or(|applied| applied.changed) {
456            state = match own {
457                Some(own) if own.source == "collapse" => "collapsed",
458                Some(own) if own.source == "ctx.summarize" => "summarized",
459                _ if omitted || own.is_some_and(|own| own.replacement.is_none()) => "forgotten",
460                _ => "replaced",
461            };
462        }
463        let mut item = Map::new();
464        item.insert("id".into(), entry["id"].clone());
465        item.insert("kind".into(), kind.into());
466        if entry["type"] == "message"
467            && entry["message"]["role"] == "toolResult"
468            && let Some(tool) = entry["message"].get("toolName")
469        {
470            item.insert("tool".into(), tool.clone());
471        }
472        let bytes = match visible {
473            Some(applied) if !omitted => entry_bytes(&applied.entry),
474            _ => 0,
475        };
476        item.insert("bytes".into(), bytes.into());
477        item.insert("original_bytes".into(), entry_bytes(entry).into());
478        item.insert("preview".into(), one_line(&entry_text(entry), PREVIEW_CHARS).into());
479        item.insert("state".into(), state.into());
480        item.insert("pinned".into(), view.pinned(id).into());
481        item.insert("protected".into(), view.protected.contains(id).into());
482        item.insert("at".into(), entry["timestamp"].clone());
483        Some(Value::Object(item))
484    }
485
486    fn visible_bytes(view: &BranchView) -> usize {
487        view.applied
488            .iter()
489            .filter(|applied| !is_omitted(&applied.entry))
490            .map(|applied| entry_bytes(&applied.entry))
491            .sum()
492    }
493
494    /// Refuses the whole request when any id is unknown, outside the context, protected, or pinned.
495    fn guard(view: &BranchView, ids: &[String]) -> Result<(), String> {
496        let mut problems = Vec::new();
497        for id in ids {
498            match view.by_id(id) {
499                None => problems.push(format!(
500                    "{id} is not in the model's context on this branch (unknown, or before the last compaction)"
501                )),
502                Some(entry) if matches!(kind_of(entry), None | Some("compaction" | "summary")) => {
503                    problems.push(format!(
504                        "{id} is a {} entry and cannot be edited",
505                        entry["type"].as_str().unwrap_or("undefined")
506                    ))
507                }
508                Some(_) if view.protected.contains(id) => {
509                    problems.push(format!("{id} belongs to the current user turn and cannot be edited"))
510                }
511                Some(_) if view.pinned(id) => problems.push(format!("{id} is pinned (ctx.unpin it first)")),
512                Some(_) => {}
513            }
514        }
515        if problems.is_empty() {
516            Ok(())
517        } else {
518            Err(format!("Context edit refused: {}", problems.join("; ")))
519        }
520    }
521
522    /// Tool calls and their results move together in a summarized span.
523    fn closure(view: &BranchView, ids: &[String]) -> Vec<String> {
524        let mut out: Vec<String> = ids.to_vec();
525        let add = |out: &mut Vec<String>, id: &str| {
526            if !out.iter().any(|known| known == id) {
527                out.push(id.to_string());
528            }
529        };
530        let mut call_owner: Vec<(String, String)> = Vec::new();
531        let mut results_of: Vec<(String, Vec<String>)> = Vec::new();
532        for entry in view.window() {
533            if entry["type"] != "message" {
534                continue;
535            }
536            let id = entry["id"].as_str().unwrap_or_default().to_string();
537            for call in tool_call_ids(&entry["message"]) {
538                match call_owner.iter_mut().find(|(known, _)| *known == call) {
539                    Some(slot) => slot.1 = id.clone(),
540                    None => call_owner.push((call, id.clone())),
541                }
542            }
543            if entry["message"]["role"] == "toolResult" {
544                let call = entry["message"]["toolCallId"].as_str().unwrap_or_default();
545                if let Some((_, owner)) = call_owner.iter().find(|(known, _)| known == call) {
546                    match results_of.iter_mut().find(|(known, _)| known == owner) {
547                        Some(slot) => slot.1.push(id.clone()),
548                        None => results_of.push((owner.clone(), vec![id.clone()])),
549                    }
550                }
551            }
552        }
553        for id in ids {
554            let Some(entry) = view.by_id(id) else { continue };
555            if entry["type"] == "message" && entry["message"]["role"] == "toolResult" {
556                let call = entry["message"]["toolCallId"].as_str().unwrap_or_default();
557                if let Some((_, owner)) = call_owner.iter().find(|(known, _)| known == call) {
558                    add(&mut out, owner);
559                }
560            }
561        }
562        for id in out.clone() {
563            if let Some((_, results)) = results_of.iter().find(|(owner, _)| *owner == id) {
564                for result in results {
565                    add(&mut out, result);
566                }
567            }
568        }
569        out
570    }
571
572    /// Forgotten, pinned and noted items of the root branch (`ctx.state`, the `/rlm` panel).
573    pub fn state(&self) -> Result<Value, String> {
574        let pending_ids = jsrt::sync::lock(&self.pending)
575            .iter()
576            .filter(|(lane, _)| lane == kernel::ROOT_LANE)
577            .map(|(_, entry)| entry["id"].as_str().unwrap_or_default().to_string())
578            .collect();
579        let key = (self.branches.tip_id(kernel::ROOT_LANE)?, pending_ids);
580        if let Some((cached, state)) = &*jsrt::sync::lock(&self.state_cache)
581            && *cached == key
582        {
583            return Ok(state.clone());
584        }
585        let state = self.read_state()?;
586        *jsrt::sync::lock(&self.state_cache) = Some((key, state.clone()));
587        Ok(state)
588    }
589
590    fn read_state(&self) -> Result<Value, String> {
591        let view = self.view(kernel::ROOT_LANE)?;
592        let item = |id: &str| match view.by_id(id) {
593            Some(entry) => json!({"id": id, "kind": kind_of(entry).unwrap_or("custom"),
594                "preview": one_line(&entry_text(entry), 80)}),
595            None => json!({"id": id}),
596        };
597        let edited: Vec<&(String, EditInfo)> = view.edits.iter().filter(|(id, _)| view.by_id(id).is_some()).collect();
598        let forgotten: Vec<Value> = edited
599            .iter()
600            .filter(|(_, info)| info.source != "collapse" && info.source != "trim")
601            .map(|(id, info)| {
602                let mut value = item(id);
603                value["source"] = info.source.clone().into();
604                if let Some(reason) = &info.reason {
605                    value["reason"] = reason.clone().into();
606                }
607                value
608            })
609            .collect();
610        let last = |items: Vec<Value>| -> Vec<Value> {
611            let skip = items.len().saturating_sub(STATE_LIST_MAX);
612            items.into_iter().skip(skip).collect()
613        };
614        let pinned: Vec<Value> = view.pins.iter().map(|id| item(id)).collect();
615        let notes = view
616            .path
617            .iter()
618            .filter(|entry| entry["type"] == "custom" && entry["customType"] == CONTEXT_NOTE_CUSTOM_TYPE)
619            .count();
620        Ok(json!({
621            "forgotten": last(forgotten.clone()),
622            "forgottenCount": forgotten.len(),
623            "collapsedCount": edited.len() - forgotten.len(),
624            "pinned": last(pinned),
625            "pinnedCount": view.pins.len(),
626            "notes": notes,
627        }))
628    }
629
630    pub fn handle_request(&self, kind: &str, payload: &Map<String, Value>, lane: &str) -> Result<Value, String> {
631        if kind == "ctx.state" {
632            jsrt::payload::fields(payload, &[])?;
633            return self.state();
634        }
635        self.known(lane);
636        let view = self.view(lane)?;
637        match kind {
638            "ctx.history" => {
639                kernel::ops::fields("ctx.history", payload)?;
640                let limit = match payload.get("limit") {
641                    None => HISTORY_DEFAULT,
642                    Some(value) => jsrt::number::safe_integer(value)
643                        .filter(|limit| (1..=HISTORY_MAX).contains(limit))
644                        .ok_or_else(|| format!("limit must be an integer between 1 and {HISTORY_MAX}"))?,
645                };
646                let kinds: Option<HashSet<&str>> = match payload.get("kinds") {
647                    None | Some(Value::Null) => None,
648                    Some(Value::Array(items))
649                        if items.iter().all(|k| k.as_str().is_some_and(|k| KINDS.contains(&k))) =>
650                    {
651                        Some(items.iter().filter_map(Value::as_str).collect())
652                    }
653                    Some(_) => return Err(format!("kinds must be a list of: {}", KINDS.join(", "))),
654                };
655                let items: Vec<Value> = view
656                    .window()
657                    .iter()
658                    .filter_map(|entry| Self::item(&view, entry))
659                    .filter(|item| {
660                        kinds
661                            .as_ref()
662                            .is_none_or(|kinds| kinds.contains(item["kind"].as_str().unwrap_or("")))
663                    })
664                    .collect();
665                let visible: u64 = items.iter().filter_map(|item| item["bytes"].as_u64()).sum();
666                let shown: Vec<Value> = items[items.len().saturating_sub(limit as usize)..].to_vec();
667                Ok(json!({"items": shown, "total": items.len(), "visible_bytes": visible,
668                    "compacted": view.compaction_index.is_some()}))
669            }
670            "ctx.get" => {
671                kernel::ops::fields("ctx.get", payload)?;
672                let id = jsrt::payload::nonempty_string(payload.get("id"), "id")?;
673                let entry = view.by_id(&id);
674                let item = entry.and_then(|entry| Self::item(&view, entry));
675                let (Some(entry), Some(mut item)) = (entry, item) else {
676                    return Err(format!("Unknown context item: {id}"));
677                };
678                item["text"] = entry_text(entry).into();
679                if entry["type"] == "message" {
680                    item["message"] = entry["message"].clone();
681                }
682                item["visible_text"] = match view.applied(&id) {
683                    Some(applied) if item["state"] != "forgotten" => entry_text(&applied.entry).into(),
684                    _ => Value::Null,
685                };
686                Ok(item)
687            }
688            "ctx.forget" => {
689                kernel::ops::fields("ctx.forget", payload)?;
690                let ids = id_list(payload.get("ids"))?;
691                let reason = jsrt::utf16::head(
692                    &jsrt::payload::nonempty_string(payload.get("reason"), "reason")?,
693                    REASON_MAX_CHARS,
694                )
695                .to_string();
696                Self::guard(&view, &ids)?;
697                let fresh: Vec<String> = ids
698                    .iter()
699                    .filter(|id| view.edit(id).is_none_or(|info| info.replacement.is_some()))
700                    .cloned()
701                    .collect();
702                let before = Self::visible_bytes(&view);
703                if fresh.is_empty() {
704                    return Ok(json!({"forgotten": [], "already": ids, "edit_id": null, "freed_bytes": 0}));
705                }
706                let edits: Vec<Value> = fresh
707                    .iter()
708                    .map(|id| json!({"targetId": id, "replacement": null}))
709                    .collect();
710                let edit_id = self.append(
711                    lane,
712                    CONTEXT_EDIT_CUSTOM_TYPE,
713                    json!({"edits": edits, "source": "ctx.forget", "reason": reason}),
714                )?;
715                let after = Self::visible_bytes(&self.view(lane)?);
716                let already: Vec<&String> = ids.iter().filter(|id| !fresh.contains(id)).collect();
717                Ok(json!({"forgotten": fresh, "already": already, "edit_id": edit_id,
718                    "freed_bytes": before.saturating_sub(after)}))
719            }
720            "ctx.summarize" => {
721                kernel::ops::fields("ctx.summarize", payload)?;
722                let text = jsrt::payload::nonempty_string(payload.get("text"), "text")?;
723                if jsrt::utf16::len(&text) > SUMMARY_MAX_CHARS {
724                    return Err(format!("text exceeds {SUMMARY_MAX_CHARS} characters"));
725                }
726                let mut ids = Self::closure(&view, &id_list(payload.get("ids"))?);
727                Self::guard(&view, &ids)?;
728                let order = |id: &String| view.window().iter().position(|entry| entry["id"] == id.as_str());
729                ids.sort_by_key(order);
730                let first = ids[0].clone();
731                let plural = if ids.len() == 1 { "" } else { "s" };
732                let mut edits = vec![json!({"targetId": first, "replacement": {
733                    "content": format!("[Summary of {} earlier item{plural} (ctx.summarize)]\n{text}", ids.len())}})];
734                edits.extend(ids[1..].iter().map(|id| json!({"targetId": id, "replacement": null})));
735                let before = Self::visible_bytes(&view);
736                let edit_id = self.append(
737                    lane,
738                    CONTEXT_EDIT_CUSTOM_TYPE,
739                    json!({"edits": edits, "source": "ctx.summarize"}),
740                )?;
741                let after = Self::visible_bytes(&self.view(lane)?);
742                Ok(json!({"summarized": ids, "summary_id": first, "edit_id": edit_id,
743                    "freed_bytes": before.saturating_sub(after)}))
744            }
745            "ctx.pin" | "ctx.unpin" => {
746                kernel::ops::fields(kind, payload)?;
747                let id = jsrt::payload::nonempty_string(payload.get("id"), "id")?;
748                if !view.by_id(&id).is_some_and(|entry| kind_of(entry).is_some()) {
749                    return Err(format!("Unknown context item: {id}"));
750                }
751                let pin = kind == "ctx.pin";
752                if view.pinned(&id) == pin {
753                    return Ok(json!({"id": id, "pinned": pin, "changed": false}));
754                }
755                self.append(lane, CONTEXT_PIN_CUSTOM_TYPE, json!({"targetId": id, "pinned": pin}))?;
756                Ok(json!({"id": id, "pinned": pin, "changed": true}))
757            }
758            "ctx.note" => {
759                kernel::ops::fields("ctx.note", payload)?;
760                let text = jsrt::payload::nonempty_string(payload.get("text"), "text")?;
761                if jsrt::utf16::len(&text) > NOTE_MAX_CHARS {
762                    return Err(format!("note exceeds {NOTE_MAX_CHARS} characters"));
763                }
764                Ok(json!({"id": self.append(lane, CONTEXT_NOTE_CUSTOM_TYPE, json!({"text": text}))?}))
765            }
766            _ => Err(kernel::ops::not_wired(kind)),
767        }
768    }
769}
770
771impl ApiModule for ContextControl {
772    fn prefixes(&self) -> &[&str] {
773        &["ctx."]
774    }
775
776    fn handle(&self, request: &Request<'_>) -> Result<Value, String> {
777        self.handle_request(request.kind, request.payload, request.lane)
778    }
779}
780
781const COLLAPSE_MIN_BYTES: usize = 600;
782const MAX_PENDING_CELLS: usize = 64;
783const TRIM_MIN_CHARS: usize = 8192;
784const TRIM_TARGET: f64 = 0.9;
785const KEPT_ITEM_CHARS: usize = 4000;
786const KEPT_TOTAL_CHARS: i64 = 16000;
787pub const CONTEXT_KEPT_MESSAGE_TYPE: &str = "ultron-context-kept";
788
789impl ContextControl {
790    /// Harness `tool_start`: a root `rlm` cell starts; finished tasks not yet attributed belong to it.
791    pub fn tool_start(&self, lane: &str, tool_name: &str, tool_call_id: &str) {
792        if lane != kernel::ROOT_LANE || tool_name != "rlm" {
793            return;
794        }
795        let mut tracking = jsrt::sync::lock(&self.tracking);
796        tracking.current_cell = Some(tool_call_id.to_string());
797        if !tracking.unattributed.is_empty() {
798            let lines = std::mem::take(&mut tracking.unattributed);
799            set_cell(&mut tracking.cells, tool_call_id, lines);
800        }
801    }
802
803    pub fn tool_end(&self, lane: &str, tool_call_id: &str) {
804        let mut tracking = jsrt::sync::lock(&self.tracking);
805        if lane == kernel::ROOT_LANE && tracking.current_cell.as_deref() == Some(tool_call_id) {
806            tracking.current_cell = None;
807        }
808    }
809
810    /// Harness `message_end`: once the root model answered after a cell's output, collapse it.
811    pub fn message_end(&self, lane: &str, role: &str) -> Result<(), String> {
812        if lane == kernel::ROOT_LANE && role == "assistant" && !jsrt::sync::lock(&self.tracking).cells.is_empty() {
813            self.collapse()?;
814        }
815        Ok(())
816    }
817
818    pub fn run_end(&self, lane: &str) -> Result<(), String> {
819        if lane == kernel::ROOT_LANE && !jsrt::sync::lock(&self.tracking).cells.is_empty() {
820            self.collapse()?;
821        }
822        Ok(())
823    }
824
825    /// A task's terminal result is durable (`NativeTask` JSON). Root-level tasks are attributed to the root cell
826    /// that returns them.
827    pub fn task_ended(&self, task: &Value, cost: Option<f64>) {
828        if task.get("parentId").is_some() {
829            return;
830        }
831        let text = |key: &str| task[key].as_str().unwrap_or_default().to_string();
832        let status = task["result"]["status"]
833            .as_str()
834            .map_or_else(|| text("state"), str::to_string);
835        let line = TaskLine {
836            id: text("id"),
837            definition: text("definition"),
838            key: text("key"),
839            status,
840            cost,
841        };
842        let mut tracking = jsrt::sync::lock(&self.tracking);
843        match tracking.current_cell.clone() {
844            Some(cell) => {
845                let mut lines = tracking
846                    .cells
847                    .iter()
848                    .find(|(id, _)| *id == cell)
849                    .map(|(_, lines)| lines.clone())
850                    .unwrap_or_default();
851                lines.push(line);
852                set_cell(&mut tracking.cells, &cell, lines);
853            }
854            None => {
855                tracking.unattributed.push(line);
856                if tracking.unattributed.len() > MAX_PENDING_CELLS {
857                    tracking.unattributed.remove(0);
858                }
859            }
860        }
861        while tracking.cells.len() > MAX_PENDING_CELLS {
862            tracking.cells.remove(0);
863        }
864    }
865
866    /// Harness `entry_added`: drops a pending copy of the entry; for a context edit, the event observers receive.
867    pub fn entry_added(&self, lane: &str, entry: &Value) -> Option<Value> {
868        if entry["type"] != "custom" {
869            return None;
870        }
871        jsrt::sync::lock(&self.pending).retain(|(_, pending)| pending["id"] != entry["id"]);
872        if entry["customType"] != CONTEXT_EDIT_CUSTOM_TYPE {
873            return None;
874        }
875        let data = if entry["data"].is_object() {
876            &entry["data"]
877        } else {
878            &Value::Null
879        };
880        let mut event = Map::new();
881        event.insert("lane".into(), lane.into());
882        event.insert("editId".into(), entry["id"].clone());
883        event.insert("source".into(), data["source"].as_str().unwrap_or("unknown").into());
884        if let Some(reason) = data["reason"].as_str() {
885            event.insert("reason".into(), reason.into());
886        }
887        let edits: Vec<Value> = context_edits_of(entry)
888            .into_iter()
889            .map(|edit| {
890                let action = if edit.replacement.is_none() { "omit" } else { "replace" };
891                json!({"targetId": edit.target_id, "action": action})
892            })
893            .collect();
894        event.insert("edits".into(), edits.into());
895        if let Some(tasks) = data["tasks"].as_array() {
896            let tasks: Vec<Value> = tasks
897                .iter()
898                .map(|task| match task {
899                    Value::String(text) => Value::String(text.clone()),
900                    other => Value::String(jsrt::json::stringify(other)),
901                })
902                .collect();
903            event.insert("tasks".into(), tasks.into());
904        }
905        Some(Value::Object(event))
906    }
907
908    /// Collapse cell outputs the model has already answered after.
909    fn collapse(&self) -> Result<(), String> {
910        if jsrt::sync::lock(&self.tracking).cells.is_empty() {
911            return Ok(());
912        }
913        let view = self.view(kernel::ROOT_LANE)?;
914        let mut edits = Vec::new();
915        let mut tasks = Vec::new();
916        let mut answered_after = false;
917        for entry in view.window().iter().rev() {
918            if entry["type"] != "message" {
919                continue;
920            }
921            let message = &entry["message"];
922            if message["role"] == "assistant" {
923                answered_after = true;
924                continue;
925            }
926            if message["role"] != "toolResult" || !answered_after {
927                continue;
928            }
929            let call = message["toolCallId"].as_str().unwrap_or_default();
930            let lines = {
931                let mut tracking = jsrt::sync::lock(&self.tracking);
932                let Some(index) = tracking.cells.iter().position(|(id, _)| id == call) else {
933                    continue;
934                };
935                tracking.cells.remove(index).1
936            };
937            let id = entry["id"].as_str().unwrap_or_default();
938            if view.pinned(id) || view.edit(id).is_some() {
939                continue;
940            }
941            let original = message_text(message);
942            if original.len() <= COLLAPSE_MIN_BYTES {
943                continue;
944            }
945            let content = collapsed_cell_text(id, &original, &lines);
946            if jsrt::utf16::len(&content) >= jsrt::utf16::len(&original) {
947                continue;
948            }
949            edits.push(json!({"targetId": id, "replacement": {"content": content}}));
950            tasks.extend(lines.into_iter().map(|line| line.id));
951        }
952        if edits.is_empty() {
953            return Ok(());
954        }
955        edits.reverse();
956        self.append(
957            kernel::ROOT_LANE,
958            CONTEXT_EDIT_CUSTOM_TYPE,
959            json!({"edits": edits, "source": "collapse", "reason": "task results returned", "tasks": tasks}),
960        )?;
961        Ok(())
962    }
963
964    /// Harness `before_compaction`: for a threshold compaction, trims tool results the model answered after when
965    /// that brings the estimate under 90% of the threshold; true declines the compaction.
966    pub fn before_compaction(
967        &self,
968        lane: &str,
969        reason: &str,
970        tokens_before: i64,
971        context_window: Option<i64>,
972        reserve_tokens: i64,
973    ) -> Result<bool, String> {
974        if !self.trim || reason != "threshold" {
975            return Ok(false);
976        }
977        self.known(lane);
978        let Some(window) = context_window else {
979            return Ok(false);
980        };
981        self.trim_instead(lane, tokens_before, window - reserve_tokens)
982    }
983
984    fn trim_instead(&self, lane: &str, tokens: i64, threshold: i64) -> Result<bool, String> {
985        let view = self.view(lane)?;
986        let target = threshold as f64 * TRIM_TARGET;
987        let last_assistant = view
988            .window()
989            .iter()
990            .rev()
991            .find(|entry| entry["type"] == "message" && entry["message"]["role"] == "assistant")
992            .and_then(|entry| entry["id"].as_str().map(str::to_string));
993        let credit = jsrt::sync::lock(&self.tracking)
994            .trimmed
995            .iter()
996            .find(|(name, assistant, _)| name == lane && Some(assistant) == last_assistant.as_ref())
997            .map_or(0, |(_, _, saved)| *saved);
998        if (tokens - credit) as f64 <= target {
999            return Ok(true);
1000        }
1001        let mut edits = Vec::new();
1002        let mut saved = 0i64;
1003        let mut answered_after = false;
1004        for entry in view.window().iter().rev() {
1005            if entry["type"] != "message" {
1006                continue;
1007            }
1008            let message = &entry["message"];
1009            if message["role"] == "assistant" {
1010                answered_after = true;
1011                continue;
1012            }
1013            if message["role"] != "toolResult" || !answered_after {
1014                continue;
1015            }
1016            let id = entry["id"].as_str().unwrap_or_default();
1017            if view.pinned(id) || view.edit(id).is_some() || view.protected.contains(id) {
1018                continue;
1019            }
1020            // Text only: an image's cost is not in its characters.
1021            if !message["content"]
1022                .as_array()
1023                .is_some_and(|parts| parts.iter().all(|part| part["type"] == "text"))
1024            {
1025                continue;
1026            }
1027            let original = message_text(message);
1028            if jsrt::utf16::len(&original) <= TRIM_MIN_CHARS {
1029                continue;
1030            }
1031            let content = trimmed_result_text(id, &original);
1032            saved += (jsrt::utf16::len(&original) as i64 - jsrt::utf16::len(&content) as i64).div_euclid(4);
1033            edits.push(json!({"targetId": id, "replacement": {"content": content}}));
1034        }
1035        let Some(last_assistant) = last_assistant else {
1036            return Ok(false);
1037        };
1038        if edits.is_empty() || (tokens - credit - saved) as f64 > target {
1039            return Ok(false);
1040        }
1041        edits.reverse();
1042        self.append(
1043            lane,
1044            CONTEXT_EDIT_CUSTOM_TYPE,
1045            json!({"edits": edits, "source": "trim", "reason": "trimmed old tool results instead of compacting"}),
1046        )?;
1047        let mut tracking = jsrt::sync::lock(&self.tracking);
1048        tracking.trimmed.retain(|(name, _, _)| name != lane);
1049        tracking
1050            .trimmed
1051            .push((lane.to_string(), last_assistant, credit + saved));
1052        Ok(true)
1053    }
1054
1055    /// Notes and pinned items that the newest compaction cut off, as one bounded text block.
1056    pub fn kept_across_compaction(&self, lane: &str) -> Result<Option<String>, String> {
1057        let view = self.view(lane)?;
1058        let Some(index) = view.compaction_index else {
1059            return Ok(None);
1060        };
1061        let retained: HashSet<String> = view.path[index]["retainedTail"]
1062            .as_array()
1063            .map(|tail| tail.iter().map(jsrt::json::stringify).collect())
1064            .unwrap_or_default();
1065        let before = &view.path[..index];
1066        let omitted: HashSet<String> = before
1067            .iter()
1068            .flat_map(context_edits_of)
1069            .filter(|edit| edit.replacement.is_none())
1070            .map(|edit| edit.target_id)
1071            .collect();
1072        let mut lines: Vec<String> = Vec::new();
1073        let mut budget = KEPT_TOTAL_CHARS;
1074        let mut add = |line: String| {
1075            if budget <= 0 {
1076                return;
1077            }
1078            let bounded = if jsrt::utf16::len(&line) as i64 > budget {
1079                format!("{}…", jsrt::utf16::head(&line, budget as usize - 1))
1080            } else {
1081                line
1082            };
1083            budget -= jsrt::utf16::len(&bounded) as i64;
1084            lines.push(bounded);
1085        };
1086        for entry in before {
1087            let id = entry["id"].as_str().unwrap_or_default();
1088            if entry["type"] == "custom" && entry["customType"] == CONTEXT_NOTE_CUSTOM_TYPE && !omitted.contains(id) {
1089                add(format!("- note {id}: {}", note_text(entry)));
1090            } else if view.pinned(id)
1091                && entry["type"] == "message"
1092                && !retained.contains(&jsrt::json::stringify(&entry["message"]))
1093            {
1094                let text = message_text(&entry["message"]);
1095                let text = if jsrt::utf16::len(&text) > KEPT_ITEM_CHARS {
1096                    format!("{}…", jsrt::utf16::head(&text, KEPT_ITEM_CHARS - 1))
1097                } else {
1098                    text
1099                };
1100                add(format!(
1101                    "- pinned {id} ({}): {text}",
1102                    entry["message"]["role"].as_str().unwrap_or("undefined")
1103                ));
1104            }
1105        }
1106        if lines.is_empty() {
1107            return Ok(None);
1108        }
1109        Ok(Some(format!(
1110            "Notes and pinned items kept across compaction (ctx.note / ctx.pin):\n{}",
1111            lines.join("\n")
1112        )))
1113    }
1114
1115    /// Harness `transform_context`: after a compaction summary, shows again the notes and pinned items it cut off
1116    /// (only for lanes that used ctx, and the root). `None` leaves the messages unchanged.
1117    pub fn transform_context(&self, lane: &str, messages: &[Value]) -> Result<Option<Vec<Value>>, String> {
1118        let Some(index) = messages
1119            .iter()
1120            .position(|message| message["role"] == "compactionSummary")
1121        else {
1122            return Ok(None);
1123        };
1124        if !jsrt::sync::lock(&self.tracking).lanes.contains(lane) {
1125            return Ok(None);
1126        }
1127        let Some(kept) = self.kept_across_compaction(lane)? else {
1128            return Ok(None);
1129        };
1130        let mut out = messages.to_vec();
1131        out.insert(
1132            index + 1,
1133            json!({"role": "custom", "customType": CONTEXT_KEPT_MESSAGE_TYPE, "content": kept, "display": false,
1134                "timestamp": (self.clock)()}),
1135        );
1136        Ok(Some(out))
1137    }
1138}
1139
1140/// Sets a cell's task lines, keeping its place in the insertion order (a JS Map).
1141fn set_cell(cells: &mut Vec<(String, Vec<TaskLine>)>, id: &str, lines: Vec<TaskLine>) {
1142    match cells.iter_mut().find(|(known, _)| known == id) {
1143        Some(slot) => slot.1 = lines,
1144        None => cells.push((id.to_string(), lines)),
1145    }
1146}