Skip to main content

kiss_coding/
compaction.rs

1//! Compaction: summarize older context when the window fills, keeping a
2//! recent tail. Also branch summarization support for /tree navigation.
3
4use kiss_agent::{AgentMessage, convert_to_llm};
5use kiss_ai::{ContentBlock, Message, Model, StreamOptions, ThinkingLevel, UserContent};
6use serde_json::json;
7use std::borrow::Borrow;
8
9const TOOL_RESULT_SERIALIZE_CAP: usize = 2000;
10
11/// chars/4 heuristic, matching pi's estimator for messages without usage.
12pub fn estimate_tokens_text(text: &str) -> u64 {
13    (text.len() as u64).div_ceil(4)
14}
15
16pub fn estimate_message_tokens(message: &AgentMessage) -> u64 {
17    let text = match message {
18        AgentMessage::User(u) => u.content.as_text(),
19        AgentMessage::Assistant(a) => a
20            .content
21            .iter()
22            .map(|c| match c {
23                ContentBlock::Text { text, .. } => text.len(),
24                ContentBlock::Thinking { thinking, .. } => thinking.len(),
25                ContentBlock::ToolCall(tc) => tc.arguments.to_string().len() + tc.name.len(),
26                ContentBlock::Image { .. } => 1600,
27            })
28            .sum::<usize>()
29            .to_string(),
30        AgentMessage::ToolResult(t) => t
31            .content
32            .iter()
33            .map(|c| match c {
34                ContentBlock::Text { text, .. } => text.len(),
35                _ => 1600,
36            })
37            .sum::<usize>()
38            .to_string(),
39        AgentMessage::BashExecution(b) => (b.command.len() + b.output.len()).to_string(),
40        AgentMessage::Custom(c) => c.content.as_text(),
41        AgentMessage::BranchSummary(b) => b.summary.clone(),
42        AgentMessage::CompactionSummary(c) => c.summary.clone(),
43    };
44    match message {
45        AgentMessage::Assistant(_) | AgentMessage::ToolResult(_) => text
46            .parse::<u64>()
47            .map(|chars| chars.div_ceil(4))
48            .unwrap_or_else(|_| estimate_tokens_text(&text)),
49        _ => estimate_tokens_text(&text),
50    }
51}
52
53/// Estimated context size: prefer the last assistant usage (input+output+
54/// cache) and add estimates for everything after it.
55pub fn estimate_context_tokens(messages: &[AgentMessage]) -> u64 {
56    estimate_context_tokens_iter(messages.iter())
57}
58
59pub(crate) fn estimate_context_tokens_iter<M: Borrow<AgentMessage>>(
60    messages: impl DoubleEndedIterator<Item = M>,
61) -> u64 {
62    let mut tokens = 0;
63    for message in messages.rev() {
64        let message = message.borrow();
65        if let AgentMessage::Assistant(assistant) = message {
66            return tokens
67                + assistant.usage.input
68                + assistant.usage.output
69                + assistant.usage.cache_read
70                + assistant.usage.cache_write;
71        }
72        tokens += estimate_message_tokens(message);
73    }
74    tokens
75}
76
77/// Serialize a conversation to labeled text for the summary prompt. Tool
78/// results are capped so summarization stays cheap.
79pub fn serialize_conversation(messages: &[Message]) -> String {
80    let mut out = String::new();
81    for message in messages {
82        match message {
83            Message::User(u) => {
84                out.push_str(&format!("[User]: {}\n", u.content.as_text()));
85            }
86            Message::Assistant(a) => {
87                let mut tool_calls: Vec<String> = Vec::new();
88                for block in &a.content {
89                    match block {
90                        // Replayed thinking is often not in the live context. Including
91                        // it can make the summary request larger than the context it
92                        // summarizes.
93                        ContentBlock::Thinking { .. } => {}
94                        ContentBlock::Text { text, .. } => {
95                            if !text.is_empty() {
96                                out.push_str(&format!("[Assistant]: {text}\n"));
97                            }
98                        }
99                        ContentBlock::ToolCall(tc) => {
100                            let args = tc
101                                .arguments
102                                .as_object()
103                                .map(|o| {
104                                    o.iter()
105                                        .map(|(k, v)| format!("{k}={v}"))
106                                        .collect::<Vec<_>>()
107                                        .join(", ")
108                                })
109                                .unwrap_or_else(|| tc.arguments.to_string());
110                            tool_calls.push(format!("{}({args})", tc.name));
111                        }
112                        ContentBlock::Image { .. } => {}
113                    }
114                }
115                if !tool_calls.is_empty() {
116                    out.push_str(&format!(
117                        "[Assistant tool calls]: {}\n",
118                        tool_calls.join("; ")
119                    ));
120                }
121            }
122            Message::ToolResult(t) => {
123                let text: String = t
124                    .content
125                    .iter()
126                    .filter_map(|c| match c {
127                        ContentBlock::Text { text, .. } => Some(text.as_str()),
128                        _ => None,
129                    })
130                    .collect::<Vec<_>>()
131                    .join("\n");
132                let capped = if text.chars().count() > TOOL_RESULT_SERIALIZE_CAP {
133                    let kept: String = text.chars().take(TOOL_RESULT_SERIALIZE_CAP).collect();
134                    let dropped = text.chars().count() - TOOL_RESULT_SERIALIZE_CAP;
135                    format!("{kept}\n[... {dropped} characters truncated]")
136                } else {
137                    text
138                };
139                out.push_str(&format!("[Tool result]: {capped}\n"));
140            }
141        }
142    }
143    out
144}
145
146/// Extract read/modified file paths from tool calls in the messages.
147pub fn extract_file_ops(messages: &[AgentMessage]) -> (Vec<String>, Vec<String>) {
148    let mut read: Vec<String> = Vec::new();
149    let mut modified: Vec<String> = Vec::new();
150    for message in messages {
151        let AgentMessage::Assistant(a) = message else {
152            continue;
153        };
154        for tc in a.tool_calls() {
155            let Some(path) = tc.arguments["path"].as_str() else {
156                continue;
157            };
158            match tc.name.as_str() {
159                "read" => read.push(path.to_string()),
160                "edit" | "write" => modified.push(path.to_string()),
161                _ => {}
162            }
163        }
164    }
165    read.sort();
166    read.dedup();
167    modified.sort();
168    modified.dedup();
169    (read, modified)
170}
171
172pub const SUMMARY_FORMAT: &str = "## Goal\n[What the user is trying to accomplish]\n\n## Constraints & Preferences\n- [Requirements mentioned by user]\n\n## Progress\n### Done\n- [x] [Completed tasks]\n\n### In Progress\n- [ ] [Current work]\n\n### Blocked\n- [Issues, if any]\n\n## Key Decisions\n- **[Decision]**: [Rationale]\n\n## Next Steps\n1. [What should happen next]\n\n## Critical Context\n- [Data needed to continue]";
173
174/// Cut-point decision for a compaction pass.
175#[derive(Debug, Clone, PartialEq)]
176pub struct CompactionPlan {
177    /// Messages to summarize (complete turns before the cut).
178    pub to_summarize: Vec<AgentMessage>,
179    /// Messages kept verbatim after the cut (the retained tail).
180    pub kept: Vec<AgentMessage>,
181    /// Split-turn prefix that must be summarized separately.
182    pub turn_prefix: Vec<AgentMessage>,
183    pub is_split_turn: bool,
184    pub tokens_before: u64,
185}
186
187fn is_valid_cut(message: &AgentMessage) -> bool {
188    // Never cut at tool results: they must stay with their tool call.
189    matches!(
190        message,
191        AgentMessage::User(_)
192            | AgentMessage::Assistant(_)
193            | AgentMessage::BashExecution(_)
194            | AgentMessage::Custom(_)
195            | AgentMessage::BranchSummary(_)
196    )
197}
198
199fn is_turn_start(message: &AgentMessage) -> bool {
200    matches!(
201        message,
202        AgentMessage::User(_) | AgentMessage::Custom(_) | AgentMessage::BashExecution(_)
203    )
204}
205
206/// Choose the cut point: walk back from the newest message accumulating
207/// estimates until `keep_recent_tokens`, then snap to a turn boundary.
208pub fn plan_compaction(messages: &[AgentMessage], keep_recent_tokens: u64) -> CompactionPlan {
209    let tokens_before = estimate_context_tokens(messages);
210    let mut budget = 0u64;
211    let mut cut = messages.len();
212    for (i, message) in messages.iter().enumerate().rev() {
213        budget += estimate_message_tokens(message);
214        if budget > keep_recent_tokens {
215            break;
216        }
217        if is_valid_cut(message) {
218            cut = i;
219        }
220    }
221    if cut == messages.len() && !messages.is_empty() {
222        // Keep at least the final message when everything is over budget.
223        cut = messages.len() - 1;
224        while cut > 0 && !is_valid_cut(&messages[cut]) {
225            cut -= 1;
226        }
227    }
228
229    // Snap to a turn start when possible. Otherwise this is a split turn.
230    let turn_start = messages[..cut].iter().rposition(is_turn_start);
231    match turn_start {
232        Some(_) if is_turn_start(&messages[cut]) => CompactionPlan {
233            to_summarize: messages[..cut].to_vec(),
234            kept: messages[cut..].to_vec(),
235            turn_prefix: Vec::new(),
236            is_split_turn: false,
237            tokens_before,
238        },
239        Some(start) => CompactionPlan {
240            to_summarize: messages[..start].to_vec(),
241            kept: messages[cut..].to_vec(),
242            turn_prefix: messages[start..cut].to_vec(),
243            is_split_turn: true,
244            tokens_before,
245        },
246        None => CompactionPlan {
247            to_summarize: Vec::new(),
248            kept: messages[cut..].to_vec(),
249            turn_prefix: messages[..cut].to_vec(),
250            is_split_turn: cut > 0,
251            tokens_before,
252        },
253    }
254}
255
256/// Whether auto-compaction should trigger.
257pub fn should_compact(context_tokens: u64, context_window: u64, reserve_tokens: u64) -> bool {
258    context_tokens > context_window.saturating_sub(reserve_tokens)
259}
260
261pub struct SummaryOutcome {
262    pub summary: String,
263    pub usage: Option<kiss_ai::Usage>,
264}
265
266fn summary_failure(message: &kiss_ai::AssistantMessage) -> Option<String> {
267    match message.stop_reason {
268        kiss_ai::StopReason::Error => Some(format!(
269            "summary generation failed: {}",
270            message.error_message.as_deref().unwrap_or("unknown error")
271        )),
272        kiss_ai::StopReason::Length => {
273            Some("summary generation failed: response reached the token limit".into())
274        }
275        _ if message.tool_calls().next().is_some() => {
276            Some("summary generation failed: response contained a tool call".into())
277        }
278        _ => None,
279    }
280}
281
282fn summary_prompt(
283    conversation_text: &str,
284    previous_summary: Option<&str>,
285    custom_instructions: Option<&str>,
286    continuation: bool,
287) -> String {
288    let mut prompt = format!("# Conversation\n{conversation_text}\n\n# Instructions\n");
289    if continuation {
290        prompt.push_str("The conversation above is earlier context from an ongoing task. Later messages are retained separately. Create a concise checkpoint that can be placed before them so work can continue; do not infer or recreate later messages. Use exactly this structure:\n\n");
291    } else {
292        prompt.push_str("Summarize the conversation so a coding agent can pick up where it left off. Use exactly this structure:\n\n");
293    }
294    prompt.push_str(SUMMARY_FORMAT);
295    prompt.push_str("\n\nAlso include, at the end, a <read-files> block listing files that were read and a <modified-files> block listing files that were changed, one path per line, when known.");
296    if let Some(prev) = previous_summary {
297        prompt.push_str("\n\nA previous summary of earlier context exists. Fold it in:\n\n");
298        prompt.push_str(prev);
299    }
300    if let Some(custom) = custom_instructions {
301        prompt.push_str("\n\nAdditional focus requested by the user: ");
302        prompt.push_str(custom);
303    }
304    prompt
305}
306
307/// Generate a structured summary with the LLM. One-off prompt: fresh session
308/// id and no cache writes wanted, so it's a plain request.
309pub async fn generate_summary(
310    model: &Model,
311    credential: Option<kiss_ai::ResolvedCredential>,
312    conversation_text: &str,
313    previous_summary: Option<&str>,
314    custom_instructions: Option<&str>,
315    continuation: bool,
316    cancel: tokio_util::sync::CancellationToken,
317) -> anyhow::Result<SummaryOutcome> {
318    let prompt = summary_prompt(
319        conversation_text,
320        previous_summary,
321        custom_instructions,
322        continuation,
323    );
324    let context = kiss_ai::Context {
325        system_prompt: None,
326        openai_responses_input: None,
327        messages: vec![Message::User(kiss_ai::UserMessage {
328            content: UserContent::Text(prompt),
329            timestamp: kiss_ai::now_ms(),
330        })],
331        tools: vec![],
332    };
333    let options = StreamOptions {
334        credential,
335        reasoning: ThinkingLevel::Off,
336        cancel,
337        ..Default::default()
338    };
339    let message = kiss_ai::stream_simple(model, &context, &options)
340        .result()
341        .await;
342    if let Some(error) = summary_failure(&message) {
343        anyhow::bail!(error);
344    }
345    Ok(SummaryOutcome {
346        summary: message.text(),
347        usage: Some(message.usage),
348    })
349}
350
351/// Details payload stored on compaction/branch-summary entries.
352pub fn file_ops_details(read: &[String], modified: &[String]) -> serde_json::Value {
353    json!({"readFiles": read, "modifiedFiles": modified})
354}
355
356/// Serialize agent messages for summarization (convert then serialize).
357pub fn serialize_agent_messages(messages: &[AgentMessage]) -> String {
358    serialize_conversation(&convert_to_llm(messages))
359}
360
361#[cfg(test)]
362mod tests {
363    use super::*;
364    use kiss_ai::{AssistantMessage, StopReason, ToolCall, ToolResultMessage};
365
366    fn user(text: &str) -> AgentMessage {
367        AgentMessage::user(text)
368    }
369
370    fn assistant(text: &str) -> AgentMessage {
371        let mut m = AssistantMessage::empty("fake", "fake", "fake");
372        m.content.push(ContentBlock::text(text));
373        m.stop_reason = StopReason::Stop;
374        AgentMessage::Assistant(m)
375    }
376
377    fn tool_result(text: &str) -> AgentMessage {
378        AgentMessage::ToolResult(ToolResultMessage {
379            tool_call_id: "c".into(),
380            tool_name: "bash".into(),
381            content: vec![ContentBlock::text(text)],
382            details: None,
383            usage: None,
384            is_error: false,
385            timestamp: 0,
386        })
387    }
388
389    #[test]
390    fn context_estimate_uses_latest_usage_and_only_its_tail() {
391        let mut measured = AssistantMessage::empty("test", "test", "test");
392        measured.usage.input = 100;
393        measured.usage.output = 20;
394        measured.usage.cache_read = 30;
395        measured.usage.cache_write = 40;
396        for (messages, expected) in [
397            (vec![], 0),
398            (vec![user("12345")], 2),
399            (
400                vec![
401                    user(&"old".repeat(1000)),
402                    AgentMessage::Assistant(measured.clone()),
403                    user("tailtailtail"),
404                ],
405                193,
406            ),
407            (
408                vec![
409                    AgentMessage::Assistant(measured),
410                    assistant("new response"),
411                    user("tailtailtail"),
412                ],
413                3,
414            ),
415        ] {
416            assert_eq!(estimate_context_tokens(&messages), expected);
417        }
418    }
419
420    #[test]
421    fn cut_at_turn_boundary_never_tool_result() {
422        // Two turns. Small keep budget keeps only the last turn.
423        let messages = vec![
424            user(&"a".repeat(400)),
425            assistant(&"b".repeat(400)),
426            tool_result(&"c".repeat(400)),
427            user(&"d".repeat(400)),
428            assistant(&"e".repeat(400)),
429        ];
430        let plan = plan_compaction(&messages, 250);
431        assert!(!plan.is_split_turn);
432        assert!(matches!(plan.kept.first().unwrap(), AgentMessage::User(_)));
433        assert_eq!(plan.to_summarize.len(), 3);
434    }
435
436    #[test]
437    fn split_turn_detected() {
438        // One huge turn: user + many assistant/tool pairs.
439        let messages = vec![
440            user("start"),
441            assistant(&"x".repeat(2000)),
442            tool_result(&"y".repeat(2000)),
443            assistant(&"z".repeat(2000)),
444        ];
445        let plan = plan_compaction(&messages, 600);
446        assert!(plan.is_split_turn);
447        assert!(plan.to_summarize.is_empty());
448        assert!(!plan.turn_prefix.is_empty());
449        // Kept must not start with a tool result.
450        assert!(is_valid_cut(plan.kept.first().unwrap()));
451    }
452
453    #[test]
454    fn oversized_trailing_tool_result_keeps_its_assistant_call() {
455        let messages = vec![
456            user("start"),
457            assistant("tool call"),
458            tool_result(&"x".repeat(8_000)),
459        ];
460        let plan = plan_compaction(&messages, 10);
461        assert!(matches!(
462            plan.kept.first(),
463            Some(AgentMessage::Assistant(_))
464        ));
465        assert!(matches!(
466            plan.kept.get(1),
467            Some(AgentMessage::ToolResult(_))
468        ));
469    }
470
471    #[test]
472    fn serialization_labels_and_caps() {
473        let big = "L".repeat(3000);
474        let messages = vec![user("do it"), assistant("on it"), tool_result(&big)];
475        let text = serialize_agent_messages(&messages);
476        assert!(text.contains("[User]: do it"));
477        assert!(text.contains("[Assistant]: on it"));
478        assert!(text.contains("characters truncated"));
479    }
480
481    #[test]
482    fn file_ops_extraction() {
483        let mut a = AssistantMessage::empty("f", "f", "f");
484        a.content.push(ContentBlock::ToolCall(ToolCall {
485            id: "1".into(),
486            name: "read".into(),
487            arguments: json!({"path": "src/a.rs"}),
488            thought_signature: None,
489            arguments_error: None,
490        }));
491        a.content.push(ContentBlock::ToolCall(ToolCall {
492            id: "2".into(),
493            name: "edit".into(),
494            arguments: json!({"path": "src/b.rs"}),
495            thought_signature: None,
496            arguments_error: None,
497        }));
498        let (read, modified) = extract_file_ops(&[AgentMessage::Assistant(a)]);
499        assert_eq!(read, vec!["src/a.rs"]);
500        assert_eq!(modified, vec!["src/b.rs"]);
501    }
502
503    #[test]
504    fn threshold() {
505        assert!(should_compact(190_000, 200_000, 16_384));
506        assert!(!should_compact(100_000, 200_000, 16_384));
507    }
508
509    #[test]
510    fn split_turn_prompt_separates_conversation_from_continuation_instructions() {
511        let prompt = summary_prompt("user work", None, None, true);
512        assert!(prompt.starts_with("# Conversation\nuser work\n\n# Instructions\n"));
513        assert!(prompt.contains("Later messages are retained separately"));
514        assert!(prompt.contains("do not infer or recreate later messages"));
515    }
516
517    #[test]
518    fn incomplete_summary_is_rejected() {
519        let mut message = AssistantMessage::empty("fake", "fake", "fake");
520        message.stop_reason = StopReason::Length;
521        assert_eq!(
522            summary_failure(&message).as_deref(),
523            Some("summary generation failed: response reached the token limit")
524        );
525    }
526
527    #[test]
528    fn summary_with_tool_call_is_rejected() {
529        let mut message = AssistantMessage::empty("fake", "fake", "fake");
530        message.stop_reason = StopReason::ToolUse;
531        message.content.push(ContentBlock::ToolCall(ToolCall {
532            id: "call-1".into(),
533            name: "read".into(),
534            arguments: json!({"path": "src/lib.rs"}),
535            thought_signature: None,
536            arguments_error: None,
537        }));
538        assert_eq!(
539            summary_failure(&message).as_deref(),
540            Some("summary generation failed: response contained a tool call")
541        );
542    }
543}