Skip to main content

compaction/
branch.rs

1//! Branch summarization for tree navigation (`branch-summarization.ts`): when leaving a branch, summarize it so its
2//! context is not lost.
3
4use ai::{AssistantMessage, Model, StopReason, Usage};
5use serde_json::Value;
6use session_file::{SessionManager, js};
7
8use crate::{
9    FileOperations, SummaryRequest, add_recorded_files, compute_file_lists, convert_for_summary, entry_type,
10    estimate_tokens, extract_file_ops_from_message, format_file_operations, has_tool_call, response_text,
11    serialize_conversation, str_of, summarization_failure, summary_context,
12};
13
14/// `collectEntriesForBranchSummary`: the entries from `old_leaf_id` back to (not including) its deepest common
15/// ancestor with `target_id`, oldest first, and that ancestor's id.
16pub fn collect_entries_for_branch_summary(
17    session: &SessionManager,
18    old_leaf_id: Option<&str>,
19    target_id: &str,
20) -> (Vec<Value>, Option<String>) {
21    let Some(old_leaf_id) = old_leaf_id.filter(|id| !id.is_empty()) else {
22        return (Vec::new(), None);
23    };
24    let old_path: Vec<&Value> = session.branch_entries(Some(old_leaf_id));
25    let common_ancestor = session
26        .branch_entries(Some(target_id))
27        .into_iter()
28        .rev()
29        .find(|e| old_path.iter().any(|o| o.get("id") == e.get("id")))
30        .and_then(|e| str_of(e, "id"))
31        .map(str::to_string);
32    let mut entries = Vec::new();
33    let mut current = Some(old_leaf_id.to_string());
34    while let Some(id) = current.filter(|id| !id.is_empty() && Some(id) != common_ancestor.as_ref()) {
35        let Some(entry) = session.entry(&id) else { break };
36        entries.push(entry.clone());
37        current = str_of(entry, "parentId").map(str::to_string);
38    }
39    entries.reverse();
40    (entries, common_ancestor)
41}
42
43/// The message an entry contributes to a branch summary; tool results are skipped (their call carries the context).
44fn message_from_entry(entry: &Value) -> Option<Value> {
45    let timestamp = || js::date_json(entry.get("timestamp"));
46    let object = |pairs: Vec<(&str, Option<Value>)>| {
47        Value::Object(
48            pairs
49                .into_iter()
50                .filter_map(|(k, v)| Some((k.to_string(), v?)))
51                .collect(),
52        )
53    };
54    match entry_type(entry)? {
55        "message" => entry
56            .get("message")
57            .filter(|m| str_of(m, "role") != Some("toolResult"))
58            .cloned(),
59        "custom_message" => Some(object(vec![
60            ("role", Some("custom".into())),
61            ("customType", entry.get("customType").cloned()),
62            ("content", entry.get("content").cloned()),
63            ("display", entry.get("display").cloned()),
64            ("details", entry.get("details").cloned()),
65            ("timestamp", Some(timestamp())),
66        ])),
67        "branch_summary" => Some(object(vec![
68            ("role", Some("branchSummary".into())),
69            ("summary", entry.get("summary").cloned()),
70            ("fromId", entry.get("fromId").cloned()),
71            ("timestamp", Some(timestamp())),
72        ])),
73        "compaction" => Some(object(vec![
74            ("role", Some("compactionSummary".into())),
75            ("summary", entry.get("summary").cloned()),
76            ("tokensBefore", entry.get("tokensBefore").cloned()),
77            ("timestamp", Some(timestamp())),
78        ])),
79        _ => None,
80    }
81}
82
83#[derive(Clone, Debug, PartialEq)]
84pub struct BranchPreparation {
85    /// Messages to summarize, oldest first.
86    pub messages: Vec<Value>,
87    pub file_ops: FileOperations,
88    pub total_tokens: u64,
89}
90
91/// `prepareBranchEntries`: the newest messages that fit `token_budget` (0 or less: no limit), plus file operations
92/// from every entry, including the lists recorded by earlier pi-generated branch summaries.
93pub fn prepare_branch_entries(entries: &[Value], token_budget: i64) -> BranchPreparation {
94    let mut file_ops = FileOperations::default();
95    for entry in entries.iter().filter(|e| entry_type(e) == Some("branch_summary")) {
96        add_recorded_files(entry, &mut file_ops);
97    }
98    let mut newest_first = Vec::new();
99    let mut total_tokens = 0;
100    for entry in entries.iter().rev() {
101        let Some(message) = message_from_entry(entry) else {
102            continue;
103        };
104        extract_file_ops_from_message(&message, &mut file_ops);
105        let tokens = estimate_tokens(&message);
106        if token_budget > 0 && (total_tokens + tokens) as i64 > token_budget {
107            // A summary is important context: still take it while under 90% of the budget.
108            let summary = matches!(entry_type(entry), Some("compaction" | "branch_summary"));
109            if summary && (total_tokens as f64) < token_budget as f64 * 0.9 {
110                newest_first.push(message);
111                total_tokens += tokens;
112            }
113            break;
114        }
115        newest_first.push(message);
116        total_tokens += tokens;
117    }
118    newest_first.reverse();
119    BranchPreparation {
120        messages: newest_first,
121        file_ops,
122        total_tokens,
123    }
124}
125
126const BRANCH_SUMMARY_PREAMBLE: &str =
127    "The user explored a different conversation branch before returning here.\nSummary of that exploration:\n\n";
128
129const BRANCH_SUMMARY_PROMPT: &str =
130    "Create a structured summary of this conversation branch for context when returning later.
131
132Use this EXACT format:
133
134## Goal
135[What was the user trying to accomplish in this branch?]
136
137## Constraints & Preferences
138- [Any constraints, preferences, or requirements mentioned]
139- [Or \"(none)\" if none were mentioned]
140
141## Progress
142### Done
143- [x] [Completed tasks/changes]
144
145### In Progress
146- [ ] [Work that was started but not finished]
147
148### Blocked
149- [Issues preventing progress, if any]
150
151## Key Decisions
152- **[Decision]**: [Brief rationale]
153
154## Next Steps
1551. [What should happen next to continue this work]
156
157Keep each section concise. Preserve exact file paths, function names, and error messages.";
158
159/// `GenerateBranchSummaryOptions` without transport settings (those belong to the caller's model call).
160#[derive(Clone, Copy, Debug)]
161pub struct BranchSummaryOptions<'a> {
162    pub model: &'a Model,
163    pub custom_instructions: Option<&'a str>,
164    /// Use `custom_instructions` instead of the default prompt rather than appending them.
165    pub replace_instructions: bool,
166    /// Tokens reserved when selecting branch history (upstream default 16384).
167    pub reserve_tokens: u64,
168    /// `Date.now()` for the request's user message.
169    pub now_ms: i64,
170}
171
172/// A generated branch summary; `usage` is `None` when there was nothing to summarize.
173#[derive(Clone, Debug, PartialEq)]
174pub struct BranchSummary {
175    pub summary: String,
176    pub usage: Option<Usage>,
177    pub read_files: Vec<String>,
178    pub modified_files: Vec<String>,
179}
180
181/// Why no branch summary was produced.
182#[derive(Clone, Debug, PartialEq, Eq)]
183pub enum BranchSummaryError {
184    Aborted,
185    Failed(String),
186}
187
188/// `generateBranchSummary`: summarizes abandoned branch `entries` (oldest first) through `call`.
189pub async fn generate_branch_summary(
190    entries: &[Value],
191    options: &BranchSummaryOptions<'_>,
192    mut call: impl AsyncFnMut(SummaryRequest) -> AssistantMessage,
193) -> Result<BranchSummary, BranchSummaryError> {
194    let model = options.model;
195    let context_window = if model.context_window > 0 {
196        model.context_window
197    } else {
198        128_000
199    };
200    let budget = context_window as i64 - options.reserve_tokens as i64;
201    let BranchPreparation { messages, file_ops, .. } = prepare_branch_entries(entries, budget);
202    if messages.is_empty() {
203        return Ok(BranchSummary {
204            summary: "No content to summarize".to_string(),
205            usage: None,
206            read_files: Vec::new(),
207            modified_files: Vec::new(),
208        });
209    }
210    let conversation = serialize_conversation(&convert_for_summary(&messages));
211    let custom = options.custom_instructions.filter(|s| !s.is_empty());
212    let instructions = match custom {
213        Some(custom) if options.replace_instructions => custom.to_string(),
214        Some(custom) => format!("{BRANCH_SUMMARY_PROMPT}\n\nAdditional focus: {custom}"),
215        None => BRANCH_SUMMARY_PROMPT.to_string(),
216    };
217    let prompt = format!("<conversation>\n{conversation}\n</conversation>\n\n{instructions}");
218    let request = SummaryRequest {
219        context: summary_context(prompt, options.now_ms),
220        max_tokens: if model.max_tokens > 0 {
221            model.max_tokens.min(4096)
222        } else {
223            4096
224        },
225        reasoning: None,
226        session_id: None,
227    };
228    let response = call(request).await;
229    if response.stop_reason == StopReason::Aborted {
230        return Err(BranchSummaryError::Aborted);
231    }
232    if let Some(failure) = summarization_failure(&response, "Branch summarization") {
233        return Err(BranchSummaryError::Failed(failure));
234    }
235    if has_tool_call(&response) {
236        return Err(BranchSummaryError::Failed(
237            "Branch summarization attempted to call a tool".to_string(),
238        ));
239    }
240    let (read_files, modified_files) = compute_file_lists(&file_ops);
241    let summary = format!(
242        "{BRANCH_SUMMARY_PREAMBLE}{}{}",
243        response_text(&response),
244        format_file_operations(&read_files, &modified_files)
245    );
246    Ok(BranchSummary {
247        summary,
248        usage: Some(response.usage),
249        read_files,
250        modified_files,
251    })
252}