1mod 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
32fn 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
48fn 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#[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
70pub 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
98pub 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
108pub 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
140pub 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
201pub 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
244pub 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
254fn 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
281pub 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
321pub 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
350pub 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
393pub 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 pub first_kept_entry_index: usize,
420 pub turn_start_index: Option<usize>,
422 pub is_split_turn: bool,
423}
424
425pub 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
432fn 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
459pub 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
511fn 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 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
580fn id_key(value: Option<&Value>) -> String {
582 value.map_or_else(|| "undefined".to_string(), jsrt::json::stringify)
583}
584
585#[derive(Clone, Debug, PartialEq)]
587pub struct CompactionPreparation {
588 pub first_kept_entry_id: String,
589 pub messages_to_summarize: Vec<Value>,
591 pub turn_prefix_messages: Vec<Value>,
593 pub is_split_turn: bool,
594 pub tokens_before: u64,
595 pub previous_summary: Option<String>,
597 pub file_ops: FileOperations,
598 pub settings: CompactionSettings,
599}
600
601fn 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
610fn 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
631pub 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 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#[derive(Clone, Debug, PartialEq)]
778pub struct SummaryRequest {
779 pub context: TranscriptContext,
780 pub max_tokens: u64,
781 pub reasoning: Option<String>,
783 pub session_id: Option<String>,
784}
785
786pub(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
801fn 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
811pub(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
837fn 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#[derive(Clone, Copy, Debug)]
852pub struct CompactOptions<'a> {
853 pub model: &'a Model,
854 pub custom_instructions: Option<&'a str>,
856 pub thinking_level: Option<&'a str>,
857 pub session_id: Option<&'a str>,
859 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
878pub 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
904pub 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
911pub 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
917pub const NO_PRIOR_HISTORY: &str = "No prior history.";
919
920pub 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#[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 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
976struct SummaryFailure {
979 message: String,
980 too_long: bool,
981}
982
983async 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
1005fn 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
1016async 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
1048pub 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 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}