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