Skip to main content

microclaw_engine/
context_window.rs

1//! Token-aware context management: per-model window sizes, token estimates,
2//! tool-output pruning and the pieces of a structured compaction.
3//!
4//! Everything here is pure (no I/O, no provider calls) so it can be tested
5//! directly; `agent_engine::compact_messages` drives it.
6
7use std::collections::{HashMap, HashSet};
8
9use microclaw_core::llm_types::{ContentBlock, Message, MessageContent};
10
11use crate::config::Config;
12
13/// Prefix of the user message that carries a compaction summary.
14pub const SUMMARY_MARKER: &str = "[Conversation Summary]";
15
16/// The `model_context_window` default; a config that still has it lets the
17/// built-in model table decide.
18const DEFAULT_WINDOW: usize = 200_000;
19
20/// The automatic-compaction threshold never goes above this share of the
21/// usable window, so a long tool loop cannot run straight into an overflow
22/// (and a compaction cannot immediately re-trigger itself).
23pub const MAX_AUTO_COMPACT_PCT: usize = 90;
24
25/// Tokens counted for an inline image block.
26const IMAGE_TOKENS: usize = 1_600;
27
28/// Context window (input + output) of well-known model families, matched by
29/// substring on the lower-cased model name; the first match wins. Values are
30/// deliberately conservative.
31const MODEL_WINDOWS: &[(&str, usize)] = &[
32    ("[1m]", 1_000_000),
33    ("-1m", 1_000_000),
34    ("claude", 200_000),
35    ("gpt-5", 272_000),
36    ("gpt-4.1", 1_000_000),
37    ("gpt-4o", 128_000),
38    ("o4-mini", 200_000),
39    ("o3", 200_000),
40    ("codex", 272_000),
41    ("gemini", 1_000_000),
42    // DeepSeek V4 / V4.1 (`deepseek-v4-pro`, `deepseek-flash`): 1M tokens.
43    ("deepseek-v4", 1_000_000),
44    ("deepseek-flash", 1_000_000),
45    ("deepseek", 128_000),
46    ("qwen3-coder", 256_000),
47    ("qwen", 128_000),
48    ("kimi", 256_000),
49    ("moonshot", 128_000),
50    ("glm-4.6", 200_000),
51    ("glm", 128_000),
52    ("grok-4", 256_000),
53    ("grok", 128_000),
54    ("minimax", 200_000),
55    ("llama", 128_000),
56    ("mistral", 128_000),
57    ("codestral", 256_000),
58];
59
60/// Context window for `model`: an explicit `model_context_windows` entry,
61/// then an explicitly configured `model_context_window`, then the built-in
62/// table, then the default.
63pub fn context_window_for(config: &Config, model: &str) -> usize {
64    if let Some(window) = config.model_context_windows.get(model) {
65        return (*window).max(1);
66    }
67    if config.model_context_window != DEFAULT_WINDOW && config.model_context_window > 0 {
68        return config.model_context_window;
69    }
70    builtin_window(model).unwrap_or(DEFAULT_WINDOW)
71}
72
73fn builtin_window(model: &str) -> Option<usize> {
74    let name = model.to_ascii_lowercase();
75    MODEL_WINDOWS
76        .iter()
77        .find(|(pattern, _)| name.contains(pattern))
78        .map(|(_, window)| *window)
79}
80
81/// Context budget of one request: the window, the output reserve and the
82/// automatic-compaction threshold.
83#[derive(Debug, Clone, Copy, PartialEq, Eq)]
84pub struct ContextBudget {
85    pub window: usize,
86    pub reserved_output: usize,
87    /// Input tokens at which automatic compaction starts; 0 when disabled.
88    pub threshold: usize,
89}
90
91impl ContextBudget {
92    pub fn for_model(config: &Config, model: &str) -> Self {
93        let window = context_window_for(config, model);
94        let reserved_output = (config.max_tokens as usize).min(window / 4);
95        let usable = window.saturating_sub(reserved_output);
96        let pct = config
97            .context_pressure_compact_pct
98            .min(MAX_AUTO_COMPACT_PCT);
99        let threshold = if config.auto_compact && pct > 0 {
100            usable.saturating_mul(pct) / 100
101        } else {
102            0
103        };
104        Self {
105            window,
106            reserved_output,
107            threshold,
108        }
109    }
110
111    pub fn enabled(&self) -> bool {
112        self.threshold > 0
113    }
114
115    pub fn over(&self, tokens: usize) -> bool {
116        self.enabled() && tokens >= self.threshold
117    }
118}
119
120/// Rough token count of a string: four bytes per token for ASCII-heavy text,
121/// three for text dominated by multi-byte characters (CJK).
122pub fn estimate_text_tokens(text: &str) -> usize {
123    if text.is_empty() {
124        return 0;
125    }
126    let bytes = text.len();
127    let chars = text.chars().count();
128    let per_token = if bytes >= chars * 2 { 3 } else { 4 };
129    bytes.div_ceil(per_token)
130}
131
132pub fn estimate_block_tokens(block: &ContentBlock) -> usize {
133    match block {
134        ContentBlock::Text { text } => estimate_text_tokens(text),
135        ContentBlock::Image { .. } => IMAGE_TOKENS,
136        ContentBlock::ToolUse { name, input, .. } => {
137            8 + estimate_text_tokens(name) + estimate_text_tokens(&input.to_string())
138        }
139        ContentBlock::ToolResult { content, .. } => 8 + estimate_text_tokens(content),
140    }
141}
142
143pub fn estimate_message_tokens(message: &Message) -> usize {
144    4 + match &message.content {
145        MessageContent::Text(text) => estimate_text_tokens(text),
146        MessageContent::Blocks(blocks) => blocks.iter().map(estimate_block_tokens).sum(),
147    }
148}
149
150pub fn estimate_messages_tokens(messages: &[Message]) -> usize {
151    messages.iter().map(estimate_message_tokens).sum()
152}
153
154/// Where the tokens of a conversation go (for `/context`).
155#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
156pub struct ContextBreakdown {
157    pub summary: usize,
158    pub user_text: usize,
159    pub assistant_text: usize,
160    pub tool_calls: usize,
161    pub tool_results: usize,
162    pub images: usize,
163    pub messages: usize,
164}
165
166impl ContextBreakdown {
167    pub fn total(&self) -> usize {
168        self.summary
169            + self.user_text
170            + self.assistant_text
171            + self.tool_calls
172            + self.tool_results
173            + self.images
174    }
175}
176
177pub fn breakdown(messages: &[Message]) -> ContextBreakdown {
178    let mut out = ContextBreakdown {
179        messages: messages.len(),
180        ..Default::default()
181    };
182    for (index, message) in messages.iter().enumerate() {
183        let user = message.role == "user";
184        match &message.content {
185            MessageContent::Text(text) => {
186                let tokens = estimate_text_tokens(text) + 4;
187                if index == 0 && is_summary_message(message) {
188                    out.summary += tokens;
189                } else if user {
190                    out.user_text += tokens;
191                } else {
192                    out.assistant_text += tokens;
193                }
194            }
195            MessageContent::Blocks(blocks) => {
196                for block in blocks {
197                    let tokens = estimate_block_tokens(block);
198                    match block {
199                        ContentBlock::Text { .. } if user => out.user_text += tokens,
200                        ContentBlock::Text { .. } => out.assistant_text += tokens,
201                        ContentBlock::Image { .. } => out.images += tokens,
202                        ContentBlock::ToolUse { .. } => out.tool_calls += tokens,
203                        ContentBlock::ToolResult { .. } => out.tool_results += tokens,
204                    }
205                }
206            }
207        }
208    }
209    out
210}
211
212pub fn is_summary_message(message: &Message) -> bool {
213    message.role == "user"
214        && matches!(&message.content, MessageContent::Text(text) if text.starts_with(SUMMARY_MARKER))
215}
216
217/// The summary text carried by a leading summary message, if any.
218pub fn previous_summary(messages: &[Message]) -> Option<String> {
219    let first = messages.first()?;
220    if !is_summary_message(first) {
221        return None;
222    }
223    match &first.content {
224        MessageContent::Text(text) => Some(text[SUMMARY_MARKER.len()..].trim().to_string()),
225        MessageContent::Blocks(_) => None,
226    }
227}
228
229/// Result of [`prune_tool_results`].
230#[derive(Debug, Clone, Default, PartialEq, Eq)]
231pub struct PruneStats {
232    pub results_cleared: usize,
233    pub tokens_saved: usize,
234}
235
236const CLEARED_PREFIX: &str = "[output cleared to save context";
237const SUPERSEDED_PREFIX: &str = "[superseded by a later read";
238
239fn already_reduced(content: &str) -> bool {
240    content.starts_with(CLEARED_PREFIX) || content.starts_with(SUPERSEDED_PREFIX)
241}
242
243/// Tool results that must survive pruning: they are small and carry state
244/// the agent relies on.
245fn protected_tool(name: &str) -> bool {
246    matches!(
247        name,
248        "todo_read"
249            | "todo_write"
250            | "activate_skill"
251            | "report_progress"
252            | "clarify"
253            | "context_note"
254    )
255}
256
257#[derive(Debug, Clone)]
258struct ToolCall {
259    name: String,
260    input: serde_json::Value,
261}
262
263fn tool_calls_by_id(messages: &[Message]) -> HashMap<String, ToolCall> {
264    let mut calls = HashMap::new();
265    for message in messages {
266        if let MessageContent::Blocks(blocks) = &message.content {
267            for block in blocks {
268                if let ContentBlock::ToolUse {
269                    id, name, input, ..
270                } = block
271                {
272                    calls.insert(
273                        id.clone(),
274                        ToolCall {
275                            name: name.clone(),
276                            input: input.clone(),
277                        },
278                    );
279                }
280            }
281        }
282    }
283    calls
284}
285
286/// Short human description of a tool call: `read_file src/lib.rs`.
287fn describe_call(call: &ToolCall) -> String {
288    let arg = ["path", "file_path", "command", "pattern", "url", "query"]
289        .iter()
290        .find_map(|key| call.input.get(*key).and_then(|v| v.as_str()))
291        .map(|value| {
292            let first_line = value.lines().next().unwrap_or_default();
293            truncate_chars(first_line, 120)
294        })
295        .unwrap_or_default();
296    if arg.is_empty() {
297        call.name.clone()
298    } else {
299        format!("{} {}", call.name, arg)
300    }
301}
302
303/// Artifact pointer kept from a spilled tool result, so a cleared output can
304/// still be fetched in full.
305fn artifact_pointer(content: &str) -> Option<String> {
306    let start = content.find("art_")?;
307    let id: String = content[start..]
308        .chars()
309        .take_while(|c| c.is_ascii_alphanumeric() || *c == '_')
310        .collect();
311    (id.len() > 8).then_some(id)
312}
313
314fn read_key(call: &ToolCall) -> Option<String> {
315    if call.name != "read_file" {
316        return None;
317    }
318    let path = call
319        .input
320        .get("path")
321        .or_else(|| call.input.get("file_path"))
322        .and_then(|v| v.as_str())?;
323    let offset = call.input.get("offset").map(|v| v.to_string());
324    let limit = call.input.get("limit").map(|v| v.to_string());
325    Some(format!("{path}|{offset:?}|{limit:?}"))
326}
327
328/// Clear older tool outputs without calling a model.
329///
330/// Scanning from the newest message backwards, the most recent
331/// `protect_tokens` of tool output stay intact. Older outputs are replaced
332/// with a one-line stub naming the call, but only when that frees at least
333/// `minimum_tokens` (smaller savings are not worth invalidating the provider's
334/// prompt cache). Independently, a `read_file` result that a later identical
335/// read supersedes is always replaced. Tool use/result pairing is untouched:
336/// only result *contents* change.
337pub fn prune_tool_results(
338    messages: &mut [Message],
339    protect_tokens: usize,
340    minimum_tokens: usize,
341) -> PruneStats {
342    let calls = tool_calls_by_id(messages);
343    let mut stats = PruneStats::default();
344
345    // Pass 1: superseded reads (latest read of a path/range wins).
346    let mut seen_reads: HashSet<String> = HashSet::new();
347    for message in messages.iter_mut().rev() {
348        let MessageContent::Blocks(blocks) = &mut message.content else {
349            continue;
350        };
351        for block in blocks.iter_mut().rev() {
352            let ContentBlock::ToolResult {
353                tool_use_id,
354                content,
355                is_error,
356            } = block
357            else {
358                continue;
359            };
360            if is_error == &Some(true) || already_reduced(content) {
361                continue;
362            }
363            let Some(key) = calls.get(tool_use_id.as_str()).and_then(read_key) else {
364                continue;
365            };
366            if !seen_reads.insert(key) {
367                let before = estimate_text_tokens(content);
368                let path = calls
369                    .get(tool_use_id.as_str())
370                    .map(describe_call)
371                    .unwrap_or_default();
372                *content = format!("{SUPERSEDED_PREFIX} of the same file: {path}]");
373                stats.tokens_saved += before.saturating_sub(estimate_text_tokens(content));
374                stats.results_cleared += 1;
375            }
376        }
377    }
378
379    // Pass 2: find the tool results beyond the protected recent window.
380    let mut running = 0usize;
381    let mut candidates: Vec<(usize, usize)> = Vec::new();
382    let mut prunable = 0usize;
383    for (mi, message) in messages.iter().enumerate().rev() {
384        let MessageContent::Blocks(blocks) = &message.content else {
385            continue;
386        };
387        for (bi, block) in blocks.iter().enumerate().rev() {
388            let ContentBlock::ToolResult {
389                tool_use_id,
390                content,
391                ..
392            } = block
393            else {
394                continue;
395            };
396            if already_reduced(content) {
397                continue;
398            }
399            let tokens = estimate_text_tokens(content);
400            running += tokens;
401            if running <= protect_tokens {
402                continue;
403            }
404            let name = calls
405                .get(tool_use_id.as_str())
406                .map(|c| c.name.as_str())
407                .unwrap_or("");
408            if protected_tool(name) || tokens < 64 {
409                continue;
410            }
411            prunable += tokens;
412            candidates.push((mi, bi));
413        }
414    }
415    if prunable < minimum_tokens || candidates.is_empty() {
416        return stats;
417    }
418    for (mi, bi) in candidates {
419        let MessageContent::Blocks(blocks) = &mut messages[mi].content else {
420            continue;
421        };
422        let ContentBlock::ToolResult {
423            tool_use_id,
424            content,
425            ..
426        } = &mut blocks[bi]
427        else {
428            continue;
429        };
430        let before = estimate_text_tokens(content);
431        let lines = content.lines().count();
432        let what = calls
433            .get(tool_use_id.as_str())
434            .map(describe_call)
435            .unwrap_or_else(|| "tool".into());
436        let artifact = artifact_pointer(content)
437            .map(|id| format!("; full output in artifact `{id}` (fetch_artifact)"))
438            .unwrap_or_default();
439        *content = format!(
440            "{CLEARED_PREFIX}: {what} ({lines} lines, ~{before} tokens){artifact}; run it again if you need it]"
441        );
442        stats.tokens_saved += before.saturating_sub(estimate_text_tokens(content));
443        stats.results_cleared += 1;
444    }
445    stats
446}
447
448/// Index at which the kept (verbatim) tail starts when keeping roughly the
449/// last `keep_tokens` tokens. The tail always starts on a plain user message
450/// (never between a tool call and its result) and keeps at least the last
451/// such message. Returns 0 when there is nothing older to summarize.
452/// Tokens of recent history kept verbatim by a compaction that must bring
453/// the conversation down to `target_tokens`: the configured tail, but never
454/// more than half the target. Otherwise a small window (a local model, an
455/// eval case) whose whole history fits in the configured tail could never
456/// be compacted and would run into a context overflow instead.
457pub fn keep_recent_budget(configured: usize, target_tokens: Option<usize>) -> usize {
458    match target_tokens {
459        Some(target) => configured.min(target / 2),
460        None => configured,
461    }
462}
463
464pub fn token_split(messages: &[Message], keep_tokens: usize) -> usize {
465    let mut kept = 0usize;
466    let mut candidate = messages.len();
467    for (index, message) in messages.iter().enumerate().rev() {
468        kept += estimate_message_tokens(message);
469        candidate = index;
470        if kept > keep_tokens {
471            break;
472        }
473    }
474    // Move forward to the next plain user message so the tail is valid and
475    // stays within budget; fall back to the last plain user message.
476    let plain_user = |m: &Message| m.role == "user" && !has_tool_blocks(m);
477    let mut split = candidate;
478    while split < messages.len() && !plain_user(&messages[split]) {
479        split += 1;
480    }
481    if split >= messages.len() {
482        split = match messages.iter().rposition(plain_user) {
483            Some(index) => index,
484            None => return 0,
485        };
486    }
487    // Never "summarize" only a leading summary message.
488    if split <= 1 && messages.first().is_some_and(is_summary_message) {
489        return 0;
490    }
491    split
492}
493
494fn has_tool_blocks(message: &Message) -> bool {
495    match &message.content {
496        MessageContent::Blocks(blocks) => blocks.iter().any(|b| {
497            matches!(
498                b,
499                ContentBlock::ToolUse { .. } | ContentBlock::ToolResult { .. }
500            )
501        }),
502        MessageContent::Text(_) => false,
503    }
504}
505
506pub fn truncate_chars(text: &str, max: usize) -> String {
507    if text.chars().count() <= max {
508        return text.to_string();
509    }
510    let mut out: String = text.chars().take(max).collect();
511    out.push('…');
512    out
513}
514
515/// Render messages for the summarizer: tool results and tool inputs are
516/// capped so one huge output cannot crowd out the rest.
517pub fn render_for_summary(messages: &[Message]) -> String {
518    let calls = tool_calls_by_id(messages);
519    let mut out = String::new();
520    for message in messages {
521        if is_summary_message(message) {
522            continue;
523        }
524        let role = &message.role;
525        match &message.content {
526            MessageContent::Text(text) => {
527                out.push_str(&format!("[{role}]: {}\n\n", truncate_chars(text, 6_000)));
528            }
529            MessageContent::Blocks(blocks) => {
530                for block in blocks {
531                    match block {
532                        ContentBlock::Text { text } => {
533                            out.push_str(&format!("[{role}]: {}\n\n", truncate_chars(text, 6_000)))
534                        }
535                        ContentBlock::ToolUse { name, input, .. } => out.push_str(&format!(
536                            "[tool call] {name}({})\n",
537                            truncate_chars(&input.to_string(), 600)
538                        )),
539                        ContentBlock::ToolResult {
540                            tool_use_id,
541                            content,
542                            is_error,
543                        } => {
544                            let label = calls
545                                .get(tool_use_id.as_str())
546                                .map(|c| c.name.as_str())
547                                .unwrap_or("tool");
548                            let kind = if is_error == &Some(true) {
549                                "error"
550                            } else {
551                                "result"
552                            };
553                            out.push_str(&format!(
554                                "[{label} {kind}] {}\n\n",
555                                truncate_chars(content, 1_500)
556                            ));
557                        }
558                        ContentBlock::Image { .. } => out.push_str("[image]\n"),
559                    }
560                }
561            }
562        }
563    }
564    out
565}
566
567/// Split `text` into chunks of at most `max_chars` characters, on line
568/// boundaries where possible.
569pub fn chunk_text(text: &str, max_chars: usize) -> Vec<String> {
570    let max_chars = max_chars.max(1);
571    let mut chunks = Vec::new();
572    let mut current = String::new();
573    let mut current_chars = 0usize;
574    for line in text.split_inclusive('\n') {
575        let line_chars = line.chars().count();
576        if current_chars + line_chars > max_chars && !current.is_empty() {
577            chunks.push(std::mem::take(&mut current));
578            current_chars = 0;
579        }
580        if line_chars > max_chars {
581            let mut rest: Vec<char> = line.chars().collect();
582            while rest.len() > max_chars {
583                let tail = rest.split_off(max_chars);
584                chunks.push(rest.into_iter().collect());
585                rest = tail;
586            }
587            current = rest.into_iter().collect();
588            current_chars = current.chars().count();
589            continue;
590        }
591        current.push_str(line);
592        current_chars += line_chars;
593    }
594    if !current.is_empty() {
595        chunks.push(current);
596    }
597    chunks
598}
599
600/// Instructions for the summarizer. The sections are what a coding (or any
601/// long-running) session needs to continue without the original history.
602pub const SUMMARY_SYSTEM_PROMPT: &str = "You write handoff summaries of an AI assistant's working session. Another instance of the assistant will continue the work from your summary alone, so keep every fact it needs and drop chatter. Be specific: exact file paths, function names, commands, error messages and numbers. Never invent anything.";
603
604pub fn summary_request(
605    previous: Option<&str>,
606    transcript: &str,
607    focus: Option<&str>,
608    instructions: Option<&str>,
609) -> String {
610    let mut prompt = String::from(
611        "Update the handoff summary of this session. Write these sections, in this order, as Markdown headings (omit a section only when it has nothing):\n\
612         ## Goal and constraints — what the user wants and every requirement, preference or prohibition they stated (quote short ones verbatim)\n\
613         ## Decisions — what was decided and why\n\
614         ## Files and state — files read, created or changed, with what changed and their current state\n\
615         ## Errors and fixes — failures seen (commands, tests, checks) and how they were resolved or why they are still open\n\
616         ## Plan — the current task list with each item's status\n\
617         ## Verification — which checks or tests last passed or failed\n\
618         ## Next step — exactly what to do next\n",
619    );
620    if let Some(focus) = focus.filter(|f| !f.trim().is_empty()) {
621        prompt.push_str(&format!(
622            "\nThe user asked this summary to focus on: {}\n",
623            focus.trim()
624        ));
625    }
626    if let Some(instructions) = instructions.filter(|i| !i.trim().is_empty()) {
627        prompt.push_str(&format!(
628            "\nProject instructions for summaries: {}\n",
629            instructions.trim()
630        ));
631    }
632    match previous.filter(|p| !p.trim().is_empty()) {
633        Some(previous) => prompt.push_str(&format!(
634            "\nThe summary so far (keep everything that still matters, merge in the new history):\n<summary>\n{}\n</summary>\n",
635            previous.trim()
636        )),
637        None => prompt.push_str("\nThere is no earlier summary.\n"),
638    }
639    prompt.push_str(&format!(
640        "\nNew history to merge in:\n<history>\n{transcript}\n</history>\n\nReply with the updated summary only."
641    ));
642    prompt
643}
644
645/// Files changed through the file tools in `messages`.
646pub fn touched_files(messages: &[Message]) -> Vec<String> {
647    let mut files: Vec<String> = Vec::new();
648    let mut push = |path: &str| {
649        let path = path.trim();
650        if !path.is_empty() && !files.iter().any(|f| f == path) {
651            files.push(path.to_string());
652        }
653    };
654    for message in messages {
655        let MessageContent::Blocks(blocks) = &message.content else {
656            continue;
657        };
658        for block in blocks {
659            let ContentBlock::ToolUse { name, input, .. } = block else {
660                continue;
661            };
662            match name.as_str() {
663                "write_file" | "edit_file" => {
664                    if let Some(path) = input
665                        .get("path")
666                        .or_else(|| input.get("file_path"))
667                        .and_then(|v| v.as_str())
668                    {
669                        push(path);
670                    }
671                }
672                "apply_patch" => {
673                    let patch = input
674                        .get("patch")
675                        .or_else(|| input.get("input"))
676                        .and_then(|v| v.as_str())
677                        .unwrap_or_default();
678                    for line in patch.lines() {
679                        for prefix in [
680                            "*** Update File: ",
681                            "*** Add File: ",
682                            "*** Delete File: ",
683                            "*** Move to: ",
684                        ] {
685                            if let Some(path) = line.strip_prefix(prefix) {
686                                push(path);
687                            }
688                        }
689                    }
690                }
691                _ => {}
692            }
693        }
694    }
695    files
696}
697
698/// The user's own words in `messages` (newest last), excluding tool results
699/// and summaries, capped to `budget_tokens` counting from the newest.
700pub fn recent_user_requests(messages: &[Message], budget_tokens: usize) -> Vec<String> {
701    let mut picked: Vec<String> = Vec::new();
702    let mut used = 0usize;
703    for message in messages.iter().rev() {
704        if message.role != "user" || is_summary_message(message) {
705            continue;
706        }
707        let text = match &message.content {
708            MessageContent::Text(text) => text.clone(),
709            MessageContent::Blocks(blocks) => blocks
710                .iter()
711                .filter_map(|b| match b {
712                    ContentBlock::Text { text } => Some(text.as_str()),
713                    _ => None,
714                })
715                .collect::<Vec<_>>()
716                .join("\n"),
717        };
718        let text = text.trim();
719        if text.is_empty() {
720            continue;
721        }
722        let text = truncate_chars(text, 2_000);
723        let tokens = estimate_text_tokens(&text);
724        if used + tokens > budget_tokens && !picked.is_empty() {
725            break;
726        }
727        used += tokens;
728        picked.push(text);
729    }
730    picked.reverse();
731    picked
732}
733
734/// Summary written without a model, used when summarization fails: it keeps
735/// the earlier summary, the user's requests, the files changed and the last
736/// commands run.
737pub fn fallback_summary(messages: &[Message]) -> String {
738    let mut out = String::from(
739        "(Automatic summary unavailable; this is a mechanical digest of the earlier history.)\n",
740    );
741    if let Some(previous) = previous_summary(messages) {
742        out.push_str("\n## Earlier summary\n");
743        out.push_str(&previous);
744        out.push('\n');
745    }
746    let requests = recent_user_requests(messages, 3_000);
747    if !requests.is_empty() {
748        out.push_str("\n## User requests\n");
749        for request in requests {
750            out.push_str(&format!("- {}\n", request.replace('\n', " ")));
751        }
752    }
753    let files = touched_files(messages);
754    if !files.is_empty() {
755        out.push_str("\n## Files changed\n");
756        for file in files {
757            out.push_str(&format!("- {file}\n"));
758        }
759    }
760    let calls = tool_calls_by_id(messages);
761    let mut commands: Vec<String> = Vec::new();
762    for message in messages {
763        if let MessageContent::Blocks(blocks) = &message.content {
764            for block in blocks {
765                if let ContentBlock::ToolUse { id, name, .. } = block {
766                    if name == "bash" {
767                        if let Some(call) = calls.get(id.as_str()) {
768                            commands.push(describe_call(call));
769                        }
770                    }
771                }
772            }
773        }
774    }
775    if !commands.is_empty() {
776        out.push_str("\n## Last commands\n");
777        for command in commands.iter().rev().take(10).rev() {
778            out.push_str(&format!("- {command}\n"));
779        }
780    }
781    out
782}
783
784/// The user message that replaces summarized history: the summary plus the
785/// facts re-injected verbatim (the user's own requests and the files changed).
786pub fn summary_message_text(summary: &str, summarized: &[Message]) -> String {
787    let mut text = format!(
788        "{SUMMARY_MARKER}\nThis is a handoff summary of the earlier part of this conversation. Continue the work from here; do not restart it or redo finished steps.\n\n{}\n",
789        summary.trim()
790    );
791    let requests = recent_user_requests(summarized, 3_000);
792    if !requests.is_empty() {
793        text.push_str("\n## The user's earlier messages (verbatim, most recent last)\n");
794        for request in requests {
795            text.push_str(&format!("> {}\n\n", request.replace('\n', "\n> ")));
796        }
797    }
798    let files = touched_files(summarized);
799    if !files.is_empty() {
800        text.push_str("\n## Files changed earlier in this session\n");
801        for file in files {
802            text.push_str(&format!("- {file}\n"));
803        }
804    }
805    text
806}
807
808/// One line telling the model how full its context is.
809pub fn budget_note(budget: &ContextBudget, used_tokens: usize) -> String {
810    let usable = budget.window.saturating_sub(budget.reserved_output).max(1);
811    let pct = (used_tokens * 100 / usable).min(100);
812    if budget.enabled() {
813        format!(
814            "<context_budget>~{used_tokens} of {usable} tokens used ({pct}%); older history is compacted automatically at ~{} tokens. Prefer targeted reads and delegate wide searches to `explore` when the budget is tight.</context_budget>",
815            budget.threshold
816        )
817    } else {
818        format!("<context_budget>~{used_tokens} of {usable} tokens used ({pct}%).</context_budget>")
819    }
820}
821
822/// `context_note` and `rewind_context`, handled by the agent loop itself.
823pub fn context_tool_definitions() -> Vec<microclaw_core::llm_types::ToolDefinition> {
824    use microclaw_core::llm_types::ToolDefinition;
825    vec![
826        ToolDefinition {
827            name: "context_note".into(),
828            description: "Save a checkpoint in this turn with a one-line note about what you know so far (for example before trying an approach that may not work). Returns a checkpoint id for rewind_context. Notes also survive compaction.".into(),
829            input_schema: serde_json::json!({
830                "type": "object",
831                "properties": {
832                    "note": {"type": "string", "description": "What you have established so far"}
833                },
834                "required": ["note"]
835            }),
836        },
837        ToolDefinition {
838            name: "rewind_context".into(),
839            description: "Drop everything after a checkpoint from your context (failed attempts, long useless outputs) and continue from there with a note to your earlier self, e.g. \"the bug is not in parser.rs; look at lexer.rs\". Files you changed are NOT reverted.".into(),
840            input_schema: serde_json::json!({
841                "type": "object",
842                "properties": {
843                    "checkpoint": {"type": "string", "description": "Checkpoint id from context_note, e.g. cp-1"},
844                    "note": {"type": "string", "description": "What your earlier self should know"}
845                },
846                "required": ["checkpoint", "note"]
847            }),
848        },
849    ]
850}
851
852#[cfg(test)]
853mod tests {
854    use super::*;
855    use serde_json::json;
856
857    fn user(text: &str) -> Message {
858        Message {
859            role: "user".into(),
860            content: MessageContent::Text(text.into()),
861        }
862    }
863
864    fn assistant(text: &str) -> Message {
865        Message {
866            role: "assistant".into(),
867            content: MessageContent::Text(text.into()),
868        }
869    }
870
871    fn call(id: &str, name: &str, input: serde_json::Value) -> Message {
872        Message {
873            role: "assistant".into(),
874            content: MessageContent::Blocks(vec![ContentBlock::ToolUse {
875                id: id.into(),
876                name: name.into(),
877                input,
878                thought_signature: None,
879            }]),
880        }
881    }
882
883    fn result(id: &str, content: &str) -> Message {
884        Message {
885            role: "user".into(),
886            content: MessageContent::Blocks(vec![ContentBlock::ToolResult {
887                tool_use_id: id.into(),
888                content: content.into(),
889                is_error: None,
890            }]),
891        }
892    }
893
894    fn result_text(message: &Message) -> &str {
895        match &message.content {
896            MessageContent::Blocks(blocks) => match &blocks[0] {
897                ContentBlock::ToolResult { content, .. } => content,
898                _ => panic!("not a tool result"),
899            },
900            _ => panic!("not blocks"),
901        }
902    }
903
904    #[test]
905    fn window_uses_override_then_explicit_then_table() {
906        let mut config = Config::test_defaults();
907        assert_eq!(context_window_for(&config, "claude-sonnet-4-5"), 200_000);
908        assert_eq!(context_window_for(&config, "gpt-4o-mini"), 128_000);
909        assert_eq!(context_window_for(&config, "gemini-2.5-pro"), 1_000_000);
910        assert_eq!(context_window_for(&config, "unknown-model"), 200_000);
911        assert_eq!(context_window_for(&config, "deepseek-v4-pro"), 1_000_000);
912        assert_eq!(context_window_for(&config, "deepseek-flash"), 1_000_000);
913        assert_eq!(context_window_for(&config, "deepseek-v4-flash"), 1_000_000);
914        assert_eq!(context_window_for(&config, "deepseek-chat"), 128_000);
915        config.model_context_window = 64_000;
916        assert_eq!(context_window_for(&config, "gemini-2.5-pro"), 64_000);
917        config
918            .model_context_windows
919            .insert("gemini-2.5-pro".into(), 500_000);
920        assert_eq!(context_window_for(&config, "gemini-2.5-pro"), 500_000);
921    }
922
923    #[test]
924    fn budget_threshold_is_clamped_and_can_be_disabled() {
925        let mut config = Config::test_defaults();
926        config.max_tokens = 8_000;
927        config.context_pressure_compact_pct = 99;
928        let budget = ContextBudget::for_model(&config, "claude-x");
929        assert_eq!(budget.window, 200_000);
930        assert_eq!(budget.threshold, (200_000 - 8_000) * 90 / 100);
931        config.auto_compact = false;
932        assert!(!ContextBudget::for_model(&config, "claude-x").enabled());
933    }
934
935    #[test]
936    fn keep_recent_budget_fits_inside_the_compaction_target() {
937        // Large windows keep the configured tail.
938        assert_eq!(keep_recent_budget(24_000, Some(150_000)), 24_000);
939        // A small window caps it at half the target, so compaction still
940        // has something to summarize.
941        assert_eq!(keep_recent_budget(24_000, Some(6_000)), 3_000);
942        assert_eq!(keep_recent_budget(24_000, Some(0)), 0);
943        // Manual compaction (no target) keeps the configured tail.
944        assert_eq!(keep_recent_budget(24_000, None), 24_000);
945    }
946
947    #[test]
948    fn estimates_are_roughly_bytes_over_four() {
949        assert_eq!(estimate_text_tokens(""), 0);
950        assert_eq!(estimate_text_tokens(&"a".repeat(400)), 100);
951        // CJK: 3 bytes per char, ~1 token per char.
952        assert_eq!(estimate_text_tokens(&"上".repeat(300)), 300);
953    }
954
955    #[test]
956    fn pruning_clears_old_outputs_and_keeps_recent_ones() {
957        let big = "line\n".repeat(4_000); // ~5k tokens each
958        let mut messages = vec![user("start")];
959        for i in 0..6 {
960            let id = format!("t{i}");
961            messages.push(call(
962                &id,
963                "bash",
964                json!({"command": format!("cargo test {i}")}),
965            ));
966            messages.push(result(&id, &big));
967        }
968        let stats = prune_tool_results(&mut messages, 12_000, 5_000);
969        assert!(stats.results_cleared >= 3, "{stats:?}");
970        assert!(result_text(&messages[2]).starts_with(CLEARED_PREFIX));
971        assert!(result_text(&messages[2]).contains("bash cargo test 0"));
972        // The newest output survives.
973        assert_eq!(result_text(&messages[12]), big);
974    }
975
976    #[test]
977    fn pruning_skips_small_savings() {
978        let mut messages = vec![
979            user("go"),
980            call("a", "bash", json!({"command": "ls"})),
981            result("a", &"x".repeat(2_000)),
982            call("b", "bash", json!({"command": "ls"})),
983            result("b", &"y".repeat(2_000)),
984        ];
985        let stats = prune_tool_results(&mut messages, 100, 50_000);
986        assert_eq!(stats.results_cleared, 0);
987    }
988
989    #[test]
990    fn superseded_reads_are_replaced() {
991        let mut messages = vec![
992            user("go"),
993            call("a", "read_file", json!({"path": "src/lib.rs"})),
994            result("a", &"old ".repeat(500)),
995            call("b", "read_file", json!({"path": "src/lib.rs"})),
996            result("b", &"new ".repeat(500)),
997        ];
998        let stats = prune_tool_results(&mut messages, 1_000_000, 1_000_000);
999        assert_eq!(stats.results_cleared, 1);
1000        assert!(result_text(&messages[2]).starts_with(SUPERSEDED_PREFIX));
1001        assert!(result_text(&messages[4]).starts_with("new"));
1002    }
1003
1004    #[test]
1005    fn pruned_output_keeps_artifact_pointer() {
1006        let content = format!(
1007            "{}\n[--- truncated. Full result saved as artifact `art_0123456789abcdef` for 24h.",
1008            "z".repeat(40_000)
1009        );
1010        let mut messages = vec![
1011            user("go"),
1012            call("a", "bash", json!({"command": "make"})),
1013            result("a", &content),
1014            call("b", "bash", json!({"command": "make"})),
1015            result("b", "ok"),
1016        ];
1017        prune_tool_results(&mut messages, 10, 100);
1018        assert!(result_text(&messages[2]).contains("art_0123456789abcdef"));
1019    }
1020
1021    #[test]
1022    fn token_split_starts_on_plain_user_message() {
1023        let messages = vec![
1024            user("first"),
1025            assistant("a1"),
1026            user("second request"),
1027            call("a", "bash", json!({"command": "ls"})),
1028            result("a", &"r".repeat(4_000)),
1029            assistant("done"),
1030            user("third"),
1031            assistant("ok"),
1032        ];
1033        let split = token_split(&messages, 10);
1034        assert_eq!(split, 6);
1035        // A budget that covers everything from the second request on keeps
1036        // exactly that tail.
1037        let budget = estimate_messages_tokens(&messages[2..]) + 1;
1038        assert_eq!(token_split(&messages, budget), 2);
1039        assert_eq!(token_split(&messages[6..], 1_000_000), 0);
1040    }
1041
1042    #[test]
1043    fn summary_request_has_sections_previous_summary_and_focus() {
1044        let prompt = summary_request(
1045            Some("old facts"),
1046            "[user]: hi",
1047            Some("the parser"),
1048            Some("keep API names"),
1049        );
1050        for section in [
1051            "## Goal and constraints",
1052            "## Files and state",
1053            "## Next step",
1054        ] {
1055            assert!(prompt.contains(section));
1056        }
1057        assert!(prompt.contains("old facts"));
1058        assert!(prompt.contains("the parser"));
1059        assert!(prompt.contains("keep API names"));
1060    }
1061
1062    #[test]
1063    fn summary_message_reinjects_user_words_and_files() {
1064        let history = vec![
1065            user("Use pnpm, never npm."),
1066            call(
1067                "a",
1068                "edit_file",
1069                json!({"path": "src/a.rs", "old_string": "x", "new_string": "y"}),
1070            ),
1071            result("a", "ok"),
1072            call(
1073                "b",
1074                "apply_patch",
1075                json!({"patch": "*** Begin Patch\n*** Update File: src/b.rs\n@@\n-x\n+y\n*** End Patch"}),
1076            ),
1077            result("b", "ok"),
1078        ];
1079        let text = summary_message_text("## Goal\nfix it", &history);
1080        assert!(text.starts_with(SUMMARY_MARKER));
1081        assert!(text.contains("> Use pnpm, never npm."));
1082        assert!(text.contains("- src/a.rs"));
1083        assert!(text.contains("- src/b.rs"));
1084        let message = user(&text);
1085        let previous = previous_summary(&[message]).unwrap();
1086        assert!(previous.contains("fix it"), "{previous}");
1087    }
1088
1089    #[test]
1090    fn fallback_summary_keeps_requests_files_and_commands() {
1091        let history = vec![
1092            user(&format!("{SUMMARY_MARKER}\nearlier facts")),
1093            assistant("ok"),
1094            user("Do not change the public API."),
1095            call(
1096                "a",
1097                "write_file",
1098                json!({"path": "README.md", "content": "x"}),
1099            ),
1100            result("a", "ok"),
1101            call("b", "bash", json!({"command": "cargo test -p parser"})),
1102            result("b", "ok"),
1103        ];
1104        let digest = fallback_summary(&history);
1105        assert!(digest.contains("earlier facts"));
1106        assert!(digest.contains("Do not change the public API."));
1107        assert!(digest.contains("README.md"));
1108        assert!(digest.contains("cargo test -p parser"));
1109    }
1110
1111    #[test]
1112    fn render_caps_tool_output_and_chunks_split_on_lines() {
1113        let history = vec![
1114            user("go"),
1115            call("a", "bash", json!({"command": "ls"})),
1116            result("a", &"q".repeat(10_000)),
1117        ];
1118        let rendered = render_for_summary(&history);
1119        assert!(rendered.len() < 3_000);
1120        let chunks = chunk_text("aaa\nbbb\nccc\n", 8);
1121        assert_eq!(chunks, vec!["aaa\nbbb\n", "ccc\n"]);
1122        let chunks = chunk_text(&"x".repeat(25), 10);
1123        assert_eq!(chunks.len(), 3);
1124    }
1125
1126    #[test]
1127    fn breakdown_attributes_tokens() {
1128        let history = vec![
1129            user(&format!("{SUMMARY_MARKER}\nfacts")),
1130            assistant("ok"),
1131            call("a", "bash", json!({"command": "ls"})),
1132            result("a", "out"),
1133        ];
1134        let b = breakdown(&history);
1135        assert!(b.summary > 0 && b.assistant_text > 0 && b.tool_calls > 0 && b.tool_results > 0);
1136        assert_eq!(b.messages, 4);
1137        assert_eq!(
1138            b.total(),
1139            b.summary + b.user_text + b.assistant_text + b.tool_calls + b.tool_results + b.images
1140        );
1141    }
1142}