1use 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";
28pub const CONTEXT_NOTE_MESSAGE_TYPE: &str = "ultron-note";
30
31pub 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
54pub trait ContextBranches: Send + Sync {
56 fn entries(&self, lane: &str) -> Result<Vec<Value>, String>;
58 fn append_custom(&self, lane: &str, custom_type: &str, data: &Value) -> Result<String, String>;
60 fn tip_id(&self, lane: &str) -> Result<Option<String>, String>;
62}
63
64pub 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
108fn 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#[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
192pub 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
209pub 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
225pub 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
244struct BranchView {
246 path: Vec<Value>,
247 compaction_index: Option<usize>,
248 window_start: usize,
250 applied: Vec<Applied>,
251 edits: Vec<(String, EditInfo)>,
253 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#[derive(Default)]
298struct Tracking {
299 current_cell: Option<String>,
301 unattributed: Vec<TaskLine>,
303 cells: Vec<(String, Vec<TaskLine>)>,
305 trimmed: Vec<(String, String, i64)>,
307 lanes: HashSet<String>,
309}
310
311pub struct ContextControl {
312 branches: Arc<dyn ContextBranches>,
313 clock: Clock,
314 trim: bool,
315 pending: Mutex<Vec<(String, Value)>>,
317 tracking: Mutex<Tracking>,
318 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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
1140fn 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}