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