Skip to main content

compaction/
lib.rs

1//! Context compaction and branch summarization, ported from
2//! `packages/coding-agent/src/core/compaction/` (`compaction.ts`, `branch-summarization.ts`, `utils.ts`).
3//!
4//! Session entries and agent messages are JSON values in the session file format (see `session-file`), so custom
5//! roles (`bashExecution`, `custom`, `branchSummary`, `compactionSummary`) and unknown fields pass through untouched.
6//! Summaries are produced by a caller-supplied async model call that receives a [`SummaryRequest`] built from
7//! `ai` types and returns the provider's [`AssistantMessage`]; this crate does no I/O.
8
9mod branch;
10mod bug_summary;
11
12use std::collections::HashSet;
13
14use ai::transcript::{ContextUsageEstimate, normalize_context};
15use ai::{
16    AssistantContent, AssistantMessage, Context, Message, Model, StopReason, TextContent, TranscriptContext, Usage,
17    UserContent, UserMessage, UserMessageContent,
18};
19use indexmap::IndexSet;
20use jsrt::utf16;
21use protocol::custom_types;
22use serde_json::Value;
23use session_file::{Leaf, ProjectedEntry, SessionProjection, build_session_projection, current_system_message, js};
24use session_journal::context::convert_to_llm;
25
26pub use branch::{
27    BranchPreparation, BranchSummary, BranchSummaryError, BranchSummaryOptions, collect_entries_for_branch_summary,
28    generate_branch_summary, prepare_branch_entries,
29};
30pub use bug_summary::{bug_summary_request, bug_summary_text};
31
32// ============================================================================
33// Shared utilities (utils.ts)
34// ============================================================================
35
36fn str_of<'a>(value: &'a Value, key: &str) -> Option<&'a str> {
37    value.get(key).and_then(Value::as_str)
38}
39
40fn role(message: &Value) -> Option<&str> {
41    str_of(message, "role")
42}
43
44fn entry_type(entry: &Value) -> Option<&str> {
45    str_of(entry, "type")
46}
47
48/// `contentText(content, separator)`: a string as is, else the text blocks joined.
49fn content_text(content: Option<&Value>, separator: &str) -> String {
50    match content {
51        Some(Value::String(text)) => text.clone(),
52        Some(Value::Array(blocks)) => blocks
53            .iter()
54            .filter(|b| str_of(b, "type") == Some("text"))
55            .map(|b| js::join_string(b.get("text")))
56            .collect::<Vec<_>>()
57            .join(separator),
58        _ => String::new(),
59    }
60}
61
62/// Files touched by `read`, `write` and `edit` tool calls, in first-seen order.
63#[derive(Clone, Debug, Default, PartialEq, Eq)]
64pub struct FileOperations {
65    pub read: IndexSet<String>,
66    pub written: IndexSet<String>,
67    pub edited: IndexSet<String>,
68}
69
70/// `extractFileOpsFromMessage`: records the `path` argument of assistant `read`/`write`/`edit` tool calls.
71pub fn extract_file_ops_from_message(message: &Value, ops: &mut FileOperations) {
72    if role(message) != Some("assistant") {
73        return;
74    }
75    let Some(blocks) = message.get("content").and_then(Value::as_array) else {
76        return;
77    };
78    for block in blocks {
79        if str_of(block, "type") != Some("toolCall") || block.get("name").is_none() {
80            continue;
81        }
82        let Some(path) = block.get("arguments").and_then(|args| str_of(args, "path")) else {
83            continue;
84        };
85        if path.is_empty() {
86            continue;
87        }
88        let set = match str_of(block, "name") {
89            Some("read") => &mut ops.read,
90            Some("write") => &mut ops.written,
91            Some("edit") => &mut ops.edited,
92            _ => continue,
93        };
94        set.insert(path.to_string());
95    }
96}
97
98/// `computeFileLists`: `(read-only files, modified files)`, each sorted.
99pub fn compute_file_lists(ops: &FileOperations) -> (Vec<String>, Vec<String>) {
100    let modified: IndexSet<&String> = ops.edited.iter().chain(&ops.written).collect();
101    let mut read_files: Vec<String> = ops.read.iter().filter(|f| !modified.contains(f)).cloned().collect();
102    let mut modified_files: Vec<String> = modified.into_iter().cloned().collect();
103    utf16::sort(&mut read_files);
104    utf16::sort(&mut modified_files);
105    (read_files, modified_files)
106}
107
108/// `formatFileOperations`: the `<read-files>`/`<modified-files>` sections appended to a summary.
109pub fn format_file_operations(read_files: &[String], modified_files: &[String]) -> String {
110    let mut sections = Vec::new();
111    if !read_files.is_empty() {
112        sections.push(format!("<read-files>\n{}\n</read-files>", read_files.join("\n")));
113    }
114    if !modified_files.is_empty() {
115        sections.push(format!(
116            "<modified-files>\n{}\n</modified-files>",
117            modified_files.join("\n")
118        ));
119    }
120    if sections.is_empty() {
121        return String::new();
122    }
123    format!("\n\n{}", sections.join("\n\n"))
124}
125
126const TOOL_RESULT_MAX_CHARS: usize = 2000;
127
128fn truncate_for_summary(text: &str, max_chars: usize) -> String {
129    let len = utf16::len(text);
130    if len <= max_chars {
131        return text.to_string();
132    }
133    format!(
134        "{}\n\n[... {} more characters truncated]",
135        utf16::head(text, max_chars),
136        len - max_chars
137    )
138}
139
140/// `serializeConversation`: LLM messages (see [`convert_to_llm`]) as `[Role]: ...` text, so the summarizer reads the
141/// transcript instead of continuing it. Tool results are cut to 2000 characters.
142pub fn serialize_conversation(messages: &[Value]) -> String {
143    let mut parts = Vec::new();
144    for message in messages {
145        match role(message) {
146            Some("user") => {
147                let content = content_text(message.get("content"), "");
148                if !content.is_empty() {
149                    parts.push(format!("[User]: {content}"));
150                }
151            }
152            Some("assistant") => {
153                let blocks = message
154                    .get("content")
155                    .and_then(Value::as_array)
156                    .map_or(&[][..], Vec::as_slice);
157                let mut thinking = Vec::new();
158                let mut calls = Vec::new();
159                for block in blocks {
160                    match str_of(block, "type") {
161                        Some("thinking") => thinking.push(js::join_string(block.get("thinking"))),
162                        Some("toolCall") => {
163                            let args = match block.get("arguments") {
164                                Some(Value::Object(map)) => jsrt::json::object_entries(map)
165                                    .into_iter()
166                                    .map(|(k, v)| format!("{k}={}", jsrt::json::stringify(v)))
167                                    .collect::<Vec<_>>()
168                                    .join(", "),
169                                _ => String::new(),
170                            };
171                            calls.push(format!("{}({args})", js::join_string(block.get("name"))));
172                        }
173                        _ => {}
174                    }
175                }
176                if !thinking.is_empty() {
177                    parts.push(format!("[Assistant thinking]: {}", thinking.join("\n")));
178                }
179                if blocks.iter().any(|b| str_of(b, "type") == Some("text")) {
180                    parts.push(format!("[Assistant]: {}", content_text(message.get("content"), "\n")));
181                }
182                if !calls.is_empty() {
183                    parts.push(format!("[Assistant tool calls]: {}", calls.join("; ")));
184                }
185            }
186            Some("toolResult") => {
187                let content = content_text(message.get("content"), "");
188                if !content.is_empty() {
189                    parts.push(format!(
190                        "[Tool result]: {}",
191                        truncate_for_summary(&content, TOOL_RESULT_MAX_CHARS)
192                    ));
193                }
194            }
195            _ => {}
196        }
197    }
198    parts.join("\n\n")
199}
200
201/// [`convert_to_llm`] for a summary's conversation (Rust-only): recalled long-term memory and the active refinements
202/// are left out. They came from memory and the ledger; a summary that repeated them would be kept or proposed again
203/// as if the session had learned them.
204pub fn convert_for_summary(messages: &[Value]) -> Vec<Value> {
205    let recalled = |m: &Value| {
206        role(m) == Some("custom")
207            && matches!(
208                m.get("customType").and_then(Value::as_str),
209                Some(custom_types::RECALLED_MEMORY | custom_types::REFINEMENTS)
210            )
211    };
212    if !messages.iter().any(recalled) {
213        return convert_to_llm(messages);
214    }
215    let kept: Vec<Value> = messages.iter().filter(|m| !recalled(m)).cloned().collect();
216    convert_to_llm(&kept)
217}
218
219const SUMMARIZATION_SYSTEM_PROMPT: &str = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI assistant, then produce a structured summary following the exact format specified.
220
221Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";
222
223#[derive(Clone, Copy, Debug, PartialEq, Eq)]
224pub struct CompactionSettings {
225    pub enabled: bool,
226    pub reserve_tokens: u64,
227    pub keep_recent_tokens: u64,
228}
229
230impl Default for CompactionSettings {
231    fn default() -> Self {
232        CompactionSettings {
233            enabled: true,
234            reserve_tokens: 16384,
235            keep_recent_tokens: 20000,
236        }
237    }
238}
239
240fn number(value: &Value, key: &str) -> u64 {
241    value.get(key).and_then(Value::as_f64).map_or(0, |n| n as u64)
242}
243
244/// `calculateContextTokens`: `totalTokens`, else the sum of input, output and cache tokens.
245pub fn calculate_context_tokens(usage: &Value) -> u64 {
246    match number(usage, "totalTokens") {
247        0 => {
248            number(usage, "input") + number(usage, "output") + number(usage, "cacheRead") + number(usage, "cacheWrite")
249        }
250        total => total,
251    }
252}
253
254/// Usage of an assistant message that completed and reported a non-zero count.
255fn assistant_usage(message: &Value) -> Option<&Value> {
256    if role(message) != Some("assistant") || matches!(str_of(message, "stopReason"), Some("aborted" | "error")) {
257        return None;
258    }
259    message
260        .get("usage")
261        .filter(|u| jsrt::value::truthy(Some(u)) && calculate_context_tokens(u) > 0)
262}
263
264const ESTIMATED_IMAGE_CHARS: usize = 4800;
265
266fn text_and_image_chars(content: Option<&Value>) -> usize {
267    match content {
268        Some(Value::String(text)) => utf16::len(text),
269        Some(Value::Array(blocks)) => blocks
270            .iter()
271            .map(|block| match str_of(block, "type") {
272                Some("text") => str_of(block, "text").map_or(0, utf16::len),
273                Some("image") => ESTIMATED_IMAGE_CHARS,
274                _ => 0,
275            })
276            .sum(),
277        _ => 0,
278    }
279}
280
281/// `estimateTokens`: characters / 4, rounded up (an overestimate); images count 4800 characters.
282pub fn estimate_tokens(message: &Value) -> u64 {
283    let len = |key: &str| str_of(message, key).map_or(0, utf16::len);
284    let chars = match role(message) {
285        Some("system") => {
286            let sections: usize = match message.get("sections") {
287                Some(Value::Object(map)) => map.values().filter_map(Value::as_str).map(utf16::len).sum(),
288                _ => 0,
289            };
290            let tools = message
291                .get("toolsAdded")
292                .filter(|t| jsrt::value::truthy(Some(t)))
293                .map_or(0, |t| utf16::len(&jsrt::json::stringify(t)));
294            text_and_image_chars(message.get("content")) + sections + tools
295        }
296        Some("user" | "custom" | "toolResult") => text_and_image_chars(message.get("content")),
297        Some("assistant") => message
298            .get("content")
299            .and_then(Value::as_array)
300            .map_or(&[][..], Vec::as_slice)
301            .iter()
302            .map(|block| match str_of(block, "type") {
303                Some("text") => str_of(block, "text").map_or(0, utf16::len),
304                Some("thinking") => str_of(block, "thinking").map_or(0, utf16::len),
305                Some("toolCall") => {
306                    str_of(block, "name").map_or(0, utf16::len)
307                        + block
308                            .get("arguments")
309                            .map_or(0, |a| utf16::len(&jsrt::json::stringify(a)))
310                }
311                _ => 0,
312            })
313            .sum(),
314        Some("bashExecution") => len("command") + len("output"),
315        Some("branchSummary" | "compactionSummary") => len("summary"),
316        _ => 0,
317    };
318    chars.div_ceil(4) as u64
319}
320
321/// `estimateContextTokens`: the newest valid assistant usage plus estimates for the messages after it.
322pub fn estimate_context_tokens(messages: &[Value]) -> ContextUsageEstimate {
323    let last = messages
324        .iter()
325        .enumerate()
326        .rev()
327        .find_map(|(i, m)| assistant_usage(m).map(|u| (calculate_context_tokens(u), i)));
328    match last {
329        None => {
330            let tokens = messages.iter().map(estimate_tokens).sum();
331            ContextUsageEstimate {
332                tokens,
333                usage_tokens: 0,
334                trailing_tokens: tokens,
335                last_usage_index: None,
336            }
337        }
338        Some((usage_tokens, index)) => {
339            let trailing_tokens: u64 = messages[index + 1..].iter().map(estimate_tokens).sum();
340            ContextUsageEstimate {
341                tokens: usage_tokens + trailing_tokens,
342                usage_tokens,
343                trailing_tokens,
344                last_usage_index: Some(index),
345            }
346        }
347    }
348}
349
350/// `estimateProjectedContextTokens`: like [`estimate_context_tokens`], but usage recorded before the latest context
351/// edit or compaction on the branch is stale, so then every projected message is estimated instead.
352pub fn estimate_projected_context_tokens(
353    projection: &SessionProjection<'_>,
354    branch_entries: &[Value],
355) -> ContextUsageEstimate {
356    let estimate = estimate_context_tokens(&projection.messages);
357    if let Some(last_usage) = estimate.last_usage_index {
358        let mut start = 0;
359        let mut usage_entry_id = None;
360        for entry in &projection.entries {
361            let next = start + entry.messages.len();
362            if last_usage < next {
363                usage_entry_id = entry.source.get("id").filter(|id| jsrt::value::truthy(Some(id)));
364                break;
365            }
366            start = next;
367        }
368        let usage_entry_index =
369            usage_entry_id.and_then(|id| branch_entries.iter().position(|e| e.get("id") == Some(id)));
370        let invalidating = branch_entries
371            .iter()
372            .rposition(|e| matches!(entry_type(e), Some("context_edit" | "compaction")));
373        if usage_entry_index.is_some_and(|u| invalidating.is_none_or(|i| u > i)) {
374            return estimate;
375        }
376    }
377    let system = current_system_message(&projection.messages).map_or(0, |m| estimate_tokens(&m));
378    let tokens = system
379        + projection
380            .messages
381            .iter()
382            .filter(|m| role(m) != Some("system"))
383            .map(estimate_tokens)
384            .sum::<u64>();
385    ContextUsageEstimate {
386        tokens,
387        usage_tokens: 0,
388        trailing_tokens: tokens,
389        last_usage_index: None,
390    }
391}
392
393/// `shouldCompact`: whether the context leaves less than `reserve_tokens` of the window.
394pub fn should_compact(context_tokens: u64, context_window: u64, settings: &CompactionSettings) -> bool {
395    settings.enabled && i128::from(context_tokens) > i128::from(context_window) - i128::from(settings.reserve_tokens)
396}
397
398fn is_cut_point_message(message: &Value) -> bool {
399    matches!(
400        role(message),
401        Some("user" | "assistant" | "bashExecution" | "custom" | "branchSummary" | "compactionSummary")
402    )
403}
404
405fn is_turn_start_message(message: &Value) -> bool {
406    matches!(
407        role(message),
408        Some("user" | "bashExecution" | "custom" | "branchSummary" | "compactionSummary")
409    )
410}
411
412fn is_turn_start_entry(entry: &Value) -> bool {
413    entry_type(entry) != Some("compaction") && session_file::entry_messages(entry).iter().any(is_turn_start_message)
414}
415
416#[derive(Clone, Copy, Debug, PartialEq, Eq)]
417pub struct CutPoint {
418    /// Index of the first entry to keep.
419    pub first_kept_entry_index: usize,
420    /// The entry that starts the turn being split, when the cut is mid-turn.
421    pub turn_start_index: Option<usize>,
422    pub is_split_turn: bool,
423}
424
425/// `findTurnStartIndex`: the nearest entry at or before `entry_index` (not before `start_index`) that starts a turn.
426pub fn find_turn_start_index(entries: &[Value], entry_index: usize, start_index: usize) -> Option<usize> {
427    (start_index..=entry_index)
428        .rev()
429        .find(|&i| is_turn_start_entry(&entries[i]))
430}
431
432/// Walks back from `end` summing `tokens(i)`; once `keep` is reached, cuts at the nearest cut point at or after it.
433fn budget_cut(
434    cut_points: &[usize],
435    start: usize,
436    end: usize,
437    keep: u64,
438    tokens: impl Fn(usize) -> u64,
439) -> (usize, bool) {
440    let mut accumulated = 0;
441    for i in (start..end).rev() {
442        let message_tokens = tokens(i);
443        if message_tokens == 0 {
444            continue;
445        }
446        accumulated += message_tokens;
447        if accumulated >= keep {
448            let cut = cut_points
449                .iter()
450                .copied()
451                .find(|&c| c >= i)
452                .unwrap_or(cut_points[cut_points.len() - 1]);
453            return (cut, true);
454        }
455    }
456    (cut_points[0], false)
457}
458
459/// `findCutPoint`: the first entry to keep so that roughly `keep_recent_tokens` of recent context survive. Cuts only
460/// at user-like or assistant messages, never at tool results.
461pub fn find_cut_point(entries: &[Value], start_index: usize, end_index: usize, keep_recent_tokens: u64) -> CutPoint {
462    let cut_points: Vec<usize> = (start_index..end_index)
463        .filter(|&i| {
464            entry_type(&entries[i]) != Some("compaction")
465                && session_file::entry_messages(&entries[i])
466                    .iter()
467                    .any(is_cut_point_message)
468        })
469        .collect();
470    if cut_points.is_empty() {
471        return CutPoint {
472            first_kept_entry_index: start_index,
473            turn_start_index: None,
474            is_split_turn: false,
475        };
476    }
477    let (mut cut, _) = budget_cut(&cut_points, start_index, end_index, keep_recent_tokens, |i| {
478        session_file::entry_messages(&entries[i])
479            .iter()
480            .map(estimate_tokens)
481            .sum()
482    });
483    while cut > start_index {
484        let previous = &entries[cut - 1];
485        if entry_type(previous) == Some("compaction") || !session_file::entry_messages(previous).is_empty() {
486            break;
487        }
488        cut -= 1;
489    }
490    let starts_turn = is_turn_start_entry(&entries[cut]);
491    let turn_start_index = if starts_turn {
492        None
493    } else {
494        find_turn_start_index(entries, cut, start_index)
495    };
496    CutPoint {
497        first_kept_entry_index: cut,
498        turn_start_index,
499        is_split_turn: !starts_turn && turn_start_index.is_some(),
500    }
501}
502
503fn source_type<'a>(entry: &ProjectedEntry<'a>) -> Option<&'a str> {
504    entry_type(entry.source)
505}
506
507fn is_projected_turn_start(entry: &ProjectedEntry<'_>) -> bool {
508    source_type(entry) != Some("compaction") && entry.messages.iter().any(is_turn_start_message)
509}
510
511/// `findProjectedCutPoint`: [`find_cut_point`] over context-edited entries.
512fn find_projected_cut_point(entries: &[ProjectedEntry<'_>], start: usize, end: usize, keep: u64) -> CutPoint {
513    let cut_points: Vec<usize> = (start..end)
514        .filter(|&i| {
515            source_type(&entries[i]) != Some("compaction") && entries[i].messages.iter().any(is_cut_point_message)
516        })
517        .collect();
518    if cut_points.is_empty() {
519        return CutPoint {
520            first_kept_entry_index: start,
521            turn_start_index: None,
522            is_split_turn: false,
523        };
524    }
525    let (mut cut, exceeded) = budget_cut(&cut_points, start, end, keep, |i| {
526        entries[i].messages.iter().map(estimate_tokens).sum()
527    });
528
529    // A recovery attempt and its omission edits are context-invisible after the last visible input. Advance only for
530    // a closed suffix containing an omitted assistant attempt; arbitrary metadata must not move the cut past input.
531    let suffix = entries.get(cut + 1..end).unwrap_or_default();
532    let visible = |e: &ProjectedEntry<'_>| {
533        source_type(e) != Some("context_edit") && !session_file::entry_messages(e.source).is_empty()
534    };
535    let omitted = |e: &ProjectedEntry<'_>| visible(e) && e.messages.is_empty();
536    let omitted_ids: HashSet<String> = suffix
537        .iter()
538        .filter(|e| omitted(e))
539        .map(|e| id_key(e.source.get("id")))
540        .collect();
541    let external_replacement = suffix.iter().any(|e| {
542        source_type(e) == Some("context_edit")
543            && e.source.get("replacement") != Some(&Value::Null)
544            && !omitted_ids.contains(&id_key(e.source.get("targetId")))
545    });
546    let recovery_suffix = exceeded
547        && !external_replacement
548        && suffix.iter().any(|e| {
549            source_type(e) == Some("message")
550                && e.source.get("message").and_then(role) == Some("assistant")
551                && omitted(e)
552        })
553        && suffix
554            .iter()
555            .all(|e| source_type(e) != Some("compaction") && (!visible(e) || omitted(e)));
556    if recovery_suffix {
557        cut += 1;
558    }
559
560    while cut > start {
561        let previous = &entries[cut - 1];
562        if source_type(previous) == Some("compaction") || !previous.messages.is_empty() {
563            break;
564        }
565        cut -= 1;
566    }
567    let starts_turn = is_projected_turn_start(&entries[cut]);
568    let turn_start_index = if starts_turn {
569        None
570    } else {
571        (start..=cut).rev().find(|&i| is_projected_turn_start(&entries[i]))
572    };
573    CutPoint {
574        first_kept_entry_index: cut,
575        turn_start_index,
576        is_split_turn: !starts_turn && turn_start_index.is_some(),
577    }
578}
579
580/// JavaScript `Set`/`Map` key for an id: `undefined` is distinct from every string.
581fn id_key(value: Option<&Value>) -> String {
582    value.map_or_else(|| "undefined".to_string(), jsrt::json::stringify)
583}
584
585/// `CompactionPreparation`: what [`compact`] summarizes and keeps.
586#[derive(Clone, Debug, PartialEq)]
587pub struct CompactionPreparation {
588    pub first_kept_entry_id: String,
589    /// Messages summarized and dropped.
590    pub messages_to_summarize: Vec<Value>,
591    /// The start of a split turn, summarized separately.
592    pub turn_prefix_messages: Vec<Value>,
593    pub is_split_turn: bool,
594    pub tokens_before: u64,
595    /// The previous compaction's summary, for an iterative update.
596    pub previous_summary: Option<String>,
597    pub file_ops: FileOperations,
598    pub settings: CompactionSettings,
599}
600
601/// Messages an entry contributes to a summary: none for compactions, and never system messages (prompt state).
602fn summary_messages(entries: &[ProjectedEntry<'_>]) -> Vec<Value> {
603    entries
604        .iter()
605        .filter(|e| source_type(e) != Some("compaction"))
606        .flat_map(|e| e.messages.iter().filter(|m| role(m) != Some("system")).cloned())
607        .collect()
608}
609
610/// Adds the read/modified lists a pi-generated (not extension) summary entry recorded in `details`.
611fn add_recorded_files(entry: &Value, ops: &mut FileOperations) {
612    if jsrt::value::truthy(entry.get("fromHook")) {
613        return;
614    }
615    let Some(details) = entry.get("details").filter(|d| jsrt::value::truthy(Some(d))) else {
616        return;
617    };
618    let files = |key: &str| {
619        details
620            .get(key)
621            .and_then(Value::as_array)
622            .map_or(&[][..], Vec::as_slice)
623            .iter()
624            .filter_map(Value::as_str)
625            .map(str::to_string)
626    };
627    ops.read.extend(files("readFiles"));
628    ops.edited.extend(files("modifiedFiles"));
629}
630
631/// `prepareCompaction`: picks the cut on the session path and collects what to summarize. `None` when the path
632/// ends in a compaction or nothing would be summarized.
633pub fn prepare_compaction(path_entries: &[Value], settings: CompactionSettings) -> Option<CompactionPreparation> {
634    if path_entries.last().is_some_and(|e| entry_type(e) == Some("compaction")) {
635        return None;
636    }
637    let projection = build_session_projection(path_entries, Leaf::Last);
638    let entries = &projection.entries;
639    // The newest compaction is projected first; older ones in its kept range contribute nothing.
640    let prev_compaction = entries
641        .iter()
642        .position(|e| source_type(e) == Some("compaction") && !e.messages.is_empty());
643    let previous_summary = prev_compaction
644        .and_then(|i| str_of(entries[i].source, "summary"))
645        .map(str::to_string);
646    let boundary_start = prev_compaction.map_or(0, |i| i + 1);
647    let tokens_before = estimate_projected_context_tokens(&projection, path_entries).tokens;
648    let cut = find_projected_cut_point(entries, boundary_start, entries.len(), settings.keep_recent_tokens);
649
650    let first_kept_entry_id = entries
651        .get(cut.first_kept_entry_index)
652        .and_then(|e| str_of(e.source, "id"))
653        .filter(|id| !id.is_empty())?
654        .to_string();
655    let history_end = match cut.turn_start_index {
656        Some(turn_start) if cut.is_split_turn => turn_start,
657        _ => cut.first_kept_entry_index,
658    };
659    let messages_to_summarize = summary_messages(entries.get(boundary_start..history_end).unwrap_or_default());
660    let turn_prefix_messages = match cut.turn_start_index {
661        Some(turn_start) if cut.is_split_turn => summary_messages(&entries[turn_start..cut.first_kept_entry_index]),
662        _ => Vec::new(),
663    };
664    if messages_to_summarize.is_empty() && turn_prefix_messages.is_empty() {
665        return None;
666    }
667
668    let mut file_ops = FileOperations::default();
669    if let Some(i) = prev_compaction {
670        add_recorded_files(entries[i].source, &mut file_ops);
671    }
672    for message in messages_to_summarize.iter().chain(&turn_prefix_messages) {
673        extract_file_ops_from_message(message, &mut file_ops);
674    }
675    Some(CompactionPreparation {
676        first_kept_entry_id,
677        messages_to_summarize,
678        turn_prefix_messages,
679        is_split_turn: cut.is_split_turn,
680        tokens_before,
681        previous_summary,
682        file_ops,
683        settings,
684    })
685}
686
687const SUMMARIZATION_PROMPT: &str = "The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
688
689Use this EXACT format:
690
691## Goal
692[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
693
694## Constraints & Preferences
695- [Any constraints, preferences, or requirements mentioned by user]
696- [Or \"(none)\" if none were mentioned]
697
698## Progress
699### Done
700- [x] [Completed tasks/changes]
701
702### In Progress
703- [ ] [Current work]
704
705### Blocked
706- [Issues preventing progress, if any]
707
708## Key Decisions
709- **[Decision]**: [Brief rationale]
710
711## Next Steps
7121. [Ordered list of what should happen next]
713
714## Critical Context
715- [Any data, examples, or references needed to continue]
716- [Or \"(none)\" if not applicable]
717
718Keep each section concise. Preserve exact file paths, function names, and error messages.";
719
720const UPDATE_SUMMARIZATION_PROMPT: &str = "The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.
721
722Update the existing structured summary with new information. RULES:
723- PRESERVE all existing information from the previous summary
724- ADD new progress, decisions, and context from the new messages
725- UPDATE the Progress section: move items from \"In Progress\" to \"Done\" when completed
726- UPDATE \"Next Steps\" based on what was accomplished
727- PRESERVE exact file paths, function names, and error messages
728- If something is no longer relevant, you may remove it
729
730Use this EXACT format:
731
732## Goal
733[Preserve existing goals, add new ones if the task expanded]
734
735## Constraints & Preferences
736- [Preserve existing, add new ones discovered]
737
738## Progress
739### Done
740- [x] [Include previously done items AND newly completed items]
741
742### In Progress
743- [ ] [Current work - update based on progress]
744
745### Blocked
746- [Current blockers - remove if resolved]
747
748## Key Decisions
749- **[Decision]**: [Brief rationale] (preserve all previous, add new)
750
751## Next Steps
7521. [Update based on current state]
753
754## Critical Context
755- [Preserve important context, add new if needed]
756
757Keep each section concise. Preserve exact file paths, function names, and error messages.";
758
759const TURN_PREFIX_SUMMARIZATION_PROMPT: &str = "The messages above are earlier context from an ongoing conversation. Later messages are stored separately and do not need to be reconstructed.
760
761Create a concise checkpoint of the user's request and the progress shown above. This checkpoint will be placed before the later messages so the conversation can continue with the necessary context.
762
763## Original Request
764[What did the user ask for?]
765
766## Progress So Far
767- [Key decisions and work completed in these messages]
768
769## Context Needed to Continue
770- [Information from these messages needed to understand the later work]
771
772Only summarize information explicitly present above. Do not infer or recreate later messages.";
773
774/// One summarization call. The caller adds its credentials, headers and abort signal, always sends it with
775/// `cacheRetention: "none"` (one-off summaries must not write the cache), and mints a fresh routing session id when
776/// `session_id` is `None`.
777#[derive(Clone, Debug, PartialEq)]
778pub struct SummaryRequest {
779    pub context: TranscriptContext,
780    pub max_tokens: u64,
781    /// The thinking level, for reasoning models when one other than `off` was requested.
782    pub reasoning: Option<String>,
783    pub session_id: Option<String>,
784}
785
786/// The summarization transcript: the summarizer system prompt and one user message holding `prompt`.
787pub(crate) fn summary_context(prompt: String, now_ms: i64) -> TranscriptContext {
788    normalize_context(&Context {
789        system_prompt: Some(SUMMARIZATION_SYSTEM_PROMPT.to_string()),
790        messages: vec![Message::User(UserMessage {
791            content: UserMessageContent::Blocks(vec![UserContent::Text(TextContent {
792                text: prompt,
793                text_signature: None,
794            })]),
795            timestamp: now_ms,
796        })],
797        tools: None,
798    })
799}
800
801/// `min(floor(fraction * reserve), model.maxTokens || Infinity)`.
802fn summary_max_tokens(fraction: f64, reserve_tokens: u64, model: &Model) -> u64 {
803    let budget = (fraction * reserve_tokens as f64).floor() as u64;
804    if model.max_tokens > 0 {
805        budget.min(model.max_tokens)
806    } else {
807        budget
808    }
809}
810
811/// `getSummarizationFailure`: why a response must not become a checkpoint (an error, or a length stop that left
812/// the summary incomplete).
813pub(crate) fn summarization_failure(response: &AssistantMessage, label: &str) -> Option<String> {
814    match response.stop_reason {
815        StopReason::Error => Some(format!(
816            "{label} failed: {}",
817            response
818                .error_message
819                .as_deref()
820                .filter(|m| !m.is_empty())
821                .unwrap_or("Unknown error")
822        )),
823        StopReason::Length => Some(format!(
824            "{label} failed: generation hit the token cap and the summary is incomplete"
825        )),
826        _ => None,
827    }
828}
829
830fn has_tool_call(response: &AssistantMessage) -> bool {
831    response
832        .content
833        .iter()
834        .any(|b| matches!(b, AssistantContent::ToolCall(_)))
835}
836
837/// `contentText` of a response: its text blocks joined by newlines.
838fn response_text(response: &AssistantMessage) -> String {
839    response
840        .content
841        .iter()
842        .filter_map(|b| match b {
843            AssistantContent::Text(t) => Some(t.text.as_str()),
844            _ => None,
845        })
846        .collect::<Vec<_>>()
847        .join("\n")
848}
849
850/// Settings of one compaction run (`compact`'s model, focus, thinking level and routing session).
851#[derive(Clone, Copy, Debug)]
852pub struct CompactOptions<'a> {
853    pub model: &'a Model,
854    /// Extra focus appended to the summary prompt.
855    pub custom_instructions: Option<&'a str>,
856    pub thinking_level: Option<&'a str>,
857    /// Routing session id forwarded to the provider (without enabling prompt caching).
858    pub session_id: Option<&'a str>,
859    /// `Date.now()` for the request's user message.
860    pub now_ms: i64,
861}
862
863impl CompactOptions<'_> {
864    fn request(&self, prompt: String, max_tokens: u64) -> SummaryRequest {
865        let reasoning = self
866            .thinking_level
867            .filter(|level| self.model.reasoning && !level.is_empty() && *level != "off")
868            .map(str::to_string);
869        SummaryRequest {
870            context: summary_context(prompt, self.now_ms),
871            max_tokens,
872            reasoning,
873            session_id: self.session_id.map(str::to_string),
874        }
875    }
876}
877
878/// `generateSummaryWithUsage`: the history summary request (an update when `previous_summary` is set).
879pub fn history_summary_request(
880    messages: &[Value],
881    reserve_tokens: u64,
882    previous_summary: Option<&str>,
883    options: &CompactOptions<'_>,
884) -> SummaryRequest {
885    let previous = previous_summary.filter(|s| !s.is_empty());
886    let mut instructions = if previous.is_some() {
887        UPDATE_SUMMARIZATION_PROMPT
888    } else {
889        SUMMARIZATION_PROMPT
890    }
891    .to_string();
892    if let Some(focus) = options.custom_instructions.filter(|s| !s.is_empty()) {
893        instructions = format!("{instructions}\n\nAdditional focus: {focus}");
894    }
895    let conversation = serialize_conversation(&convert_for_summary(messages));
896    let mut prompt = format!("<conversation>\n{conversation}\n</conversation>\n\n");
897    if let Some(previous) = previous {
898        prompt.push_str(&format!("<previous-summary>\n{previous}\n</previous-summary>\n\n"));
899    }
900    prompt.push_str(&instructions);
901    options.request(prompt, summary_max_tokens(0.8, reserve_tokens, options.model))
902}
903
904/// `generateTurnPrefixSummary`'s request: a checkpoint of the start of a split turn, with half the budget.
905pub fn turn_prefix_request(messages: &[Value], reserve_tokens: u64, options: &CompactOptions<'_>) -> SummaryRequest {
906    let conversation = serialize_conversation(&convert_for_summary(messages));
907    let prompt = format!("# Conversation\n{conversation}\n\n# Instructions\n{TURN_PREFIX_SUMMARIZATION_PROMPT}");
908    turn_prefix_request_of(prompt, reserve_tokens, options)
909}
910
911/// A turn prefix summary request asking `prompt`: the summary request's shape (system prompt, reasoning, session)
912/// with half the reserve as its budget.
913pub fn turn_prefix_request_of(prompt: String, reserve_tokens: u64, options: &CompactOptions<'_>) -> SummaryRequest {
914    options.request(prompt, summary_max_tokens(0.5, reserve_tokens, options.model))
915}
916
917/// The history summary a split turn uses when nothing before the turn was summarized.
918pub const NO_PRIOR_HISTORY: &str = "No prior history.";
919
920/// The summary of a split turn: the history's summary, then the turn prefix's.
921pub fn split_turn_summary(history: &str, prefix: &str) -> String {
922    format!("{history}\n\n---\n\n**Turn Context (split turn):**\n\n{prefix}")
923}
924
925/// `CompactionResult`; `details` holds the file lists.
926#[derive(Clone, Debug, PartialEq)]
927pub struct CompactionResult {
928    pub summary: String,
929    pub first_kept_entry_id: String,
930    pub tokens_before: u64,
931    pub usage: Usage,
932    pub read_files: Vec<String>,
933    pub modified_files: Vec<String>,
934}
935
936impl CompactionResult {
937    /// The compaction entry it makes (Pi's `CompactionEntry` fields, written by Ultron itself: `fromHook` false),
938    /// keeping `retained_tail` after the summary and recording the summary's `usage`.
939    pub fn entry(&self, retained_tail: Vec<Value>, usage: Value) -> serde_json::Map<String, Value> {
940        let mut entry = serde_json::Map::new();
941        entry.insert("type".into(), "compaction".into());
942        entry.insert("summary".into(), self.summary.clone().into());
943        entry.insert("retainedTail".into(), Value::Array(retained_tail));
944        entry.insert("tokensBefore".into(), self.tokens_before.into());
945        entry.insert(
946            "details".into(),
947            serde_json::json!({"readFiles": self.read_files, "modifiedFiles": self.modified_files}),
948        );
949        entry.insert("usage".into(), usage);
950        entry.insert("fromHook".into(), false.into());
951        entry
952    }
953}
954
955fn combine_usage(first: &Usage, second: &Usage) -> Usage {
956    let optional =
957        |a: Option<u64>, b: Option<u64>| (a.is_some() || b.is_some()).then(|| a.unwrap_or(0) + b.unwrap_or(0));
958    Usage {
959        input: first.input + second.input,
960        output: first.output + second.output,
961        cache_read: first.cache_read + second.cache_read,
962        cache_write: first.cache_write + second.cache_write,
963        cache_write_1h: optional(first.cache_write_1h, second.cache_write_1h),
964        reasoning: optional(first.reasoning, second.reasoning),
965        total_tokens: first.total_tokens + second.total_tokens,
966        cost: ai::Cost {
967            input: first.cost.input + second.cost.input,
968            output: first.cost.output + second.cost.output,
969            cache_read: first.cost.cache_read + second.cost.cache_read,
970            cache_write: first.cost.cache_write + second.cost.cache_write,
971            total: first.cost.total + second.cost.total,
972        },
973    }
974}
975
976/// Why a request gave no summary: the error text is upstream's thrown message, and `too_long` says the model refused
977/// the request as longer than its window (Rust-only).
978struct SummaryFailure {
979    message: String,
980    too_long: bool,
981}
982
983/// Sends one request and checks the response.
984async fn summarize(
985    request: SummaryRequest,
986    label: &str,
987    call: &mut impl AsyncFnMut(SummaryRequest) -> AssistantMessage,
988) -> Result<(String, Usage), SummaryFailure> {
989    let response = call(request).await;
990    if let Some(message) = summarization_failure(&response, label) {
991        return Err(SummaryFailure {
992            message,
993            too_long: ai::overflow::is_context_overflow(&response),
994        });
995    }
996    if has_tool_call(&response) {
997        return Err(SummaryFailure {
998            message: format!("{label} attempted to call a tool"),
999            too_long: false,
1000        });
1001    }
1002    Ok((response_text(&response), response.usage))
1003}
1004
1005/// Where to cut two or more `messages` in half by estimated size, with a message on each side.
1006fn halfway(messages: &[Value]) -> usize {
1007    let total: u64 = messages.iter().map(estimate_tokens).sum();
1008    let mut seen = 0;
1009    let half = messages.iter().position(|message| {
1010        seen += estimate_tokens(message);
1011        seen * 2 >= total
1012    });
1013    half.map_or(1, |index| index + 1).clamp(1, messages.len() - 1)
1014}
1015
1016/// Summarizes `parts` in order, each updating the summary of what came before it (first `previous`). Rust-only: a
1017/// part the model refuses as too long is cut in half and each half is tried in its place. The summary goes to the
1018/// lane's current model, which after a model switch may count a history as more tokens than its window holds, and
1019/// no estimate made here predicts a provider's count. One message that is too long alone fails with the
1020/// provider's error.
1021async fn summarize_parts(
1022    parts: Vec<&[Value]>,
1023    mut previous: Option<String>,
1024    label: &str,
1025    reserve_tokens: u64,
1026    options: &CompactOptions<'_>,
1027    call: &mut impl AsyncFnMut(SummaryRequest) -> AssistantMessage,
1028) -> Result<(String, Usage), String> {
1029    let mut pending: Vec<&[Value]> = parts.into_iter().rev().collect();
1030    let mut usage: Option<Usage> = None;
1031    while let Some(part) = pending.pop() {
1032        let request = history_summary_request(part, reserve_tokens, previous.as_deref(), options);
1033        match summarize(request, label, call).await {
1034            Ok((text, used)) => {
1035                usage = Some(usage.map_or(used.clone(), |sum| combine_usage(&sum, &used)));
1036                previous = Some(text);
1037            }
1038            Err(failure) if failure.too_long && part.len() > 1 => {
1039                let (first, rest) = part.split_at(halfway(part));
1040                pending.extend([rest, first]);
1041            }
1042            Err(failure) => return Err(failure.message),
1043        }
1044    }
1045    Ok((previous.unwrap_or_default(), usage.unwrap_or_default()))
1046}
1047
1048/// `compact`: summarizes a prepared compaction through `call` (history, then the split turn's prefix when cutting
1049/// mid-turn) and appends the file lists.
1050pub async fn compact(
1051    preparation: &CompactionPreparation,
1052    options: &CompactOptions<'_>,
1053    mut call: impl AsyncFnMut(SummaryRequest) -> AssistantMessage,
1054) -> Result<CompactionResult, String> {
1055    let prep = preparation;
1056    let reserve = prep.settings.reserve_tokens;
1057    let split = prep.is_split_turn && !prep.turn_prefix_messages.is_empty();
1058    let mut previous = prep.previous_summary.clone();
1059    let mut usage = None;
1060    if !split || !prep.messages_to_summarize.is_empty() {
1061        let history = vec![&prep.messages_to_summarize[..]];
1062        let (text, used) = summarize_parts(history, previous, "Summarization", reserve, options, &mut call).await?;
1063        (previous, usage) = (Some(text), Some(used));
1064    }
1065    let plus = |used: Usage| usage.as_ref().map_or(used.clone(), |sum| combine_usage(sum, &used));
1066    let (mut summary, usage) = if split {
1067        const LABEL: &str = "Turn prefix summarization";
1068        let prefix = &prep.turn_prefix_messages[..];
1069        let request = turn_prefix_request(prefix, reserve, options);
1070        match summarize(request, LABEL, &mut call).await {
1071            Ok((prefix_text, used)) => {
1072                let history = previous.unwrap_or_else(|| NO_PRIOR_HISTORY.to_string());
1073                (split_turn_summary(&history, &prefix_text), plus(used))
1074            }
1075            // A prefix too long for the model is summarized as more history, in halves.
1076            Err(failure) if failure.too_long && prefix.len() > 1 => {
1077                let (first, rest) = prefix.split_at(halfway(prefix));
1078                let (text, used) =
1079                    summarize_parts(vec![first, rest], previous, LABEL, reserve, options, &mut call).await?;
1080                (text, plus(used))
1081            }
1082            Err(failure) => return Err(failure.message),
1083        }
1084    } else {
1085        (previous.unwrap_or_default(), usage.unwrap_or_default())
1086    };
1087    let (read_files, modified_files) = compute_file_lists(&prep.file_ops);
1088    summary.push_str(&format_file_operations(&read_files, &modified_files));
1089    Ok(CompactionResult {
1090        summary,
1091        first_kept_entry_id: prep.first_kept_entry_id.clone(),
1092        tokens_before: prep.tokens_before,
1093        usage,
1094        read_files,
1095        modified_files,
1096    })
1097}