1use std::borrow::{Borrow, Cow};
16use std::collections::{BTreeMap, BTreeSet};
17use std::fmt::{self, Write as _};
18use std::sync::Arc;
19
20use rig_core::catalog::ModelSpec;
21use rig_core::completion::{
22 AssistantContent, CompletionRequest, CompletionResponse, Message, UnsupportedOption,
23};
24use rig_core::conversation::{
25 Aside, AsideId, Author, Change, Conversation, Entry, MessageId, Spliced, pairing,
26};
27use rig_core::message::{StopReason, ToolCall, ToolResult, ToolResultContent, UserContent};
28use serde::{Deserialize, Serialize};
29
30use crate::session::replay;
31use crate::{HeuristicTokenCounter, SessionError, Store, TokenCounter};
32
33#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
37pub struct SummaryState {
38 pub summary: String,
40 #[serde(default, skip_serializing_if = "Vec::is_empty")]
42 pub tracked: Vec<TrackedSet>,
43}
44
45#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
48pub struct TrackedSet {
49 pub name: String,
51 pub values: BTreeSet<String>,
53}
54
55#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
58pub struct TrackArgument {
59 pub tool: Cow<'static, str>,
61 pub argument: Cow<'static, str>,
63 pub set: Cow<'static, str>,
65}
66
67impl TrackArgument {
68 pub const fn new(tool: &'static str, argument: &'static str, set: &'static str) -> Self {
70 Self {
71 tool: Cow::Borrowed(tool),
72 argument: Cow::Borrowed(argument),
73 set: Cow::Borrowed(set),
74 }
75 }
76
77 pub fn value<'c>(&self, call: &'c ToolCall) -> Option<&'c str> {
80 let function = &call.function;
81 if self.tool != function.name.as_str() {
82 return None;
83 }
84 function.arguments.get(self.argument.as_ref())?.as_str()
85 }
86}
87
88impl SummaryState {
89 pub fn message(&self) -> Option<String> {
94 if self.summary.is_empty() {
95 return None;
96 }
97 let mut text = format!(
98 "The conversation before this point was compacted into this summary:\n\n\
99 <summary>\n{}\n</summary>",
100 self.summary.trim()
101 );
102 for (index, set) in self.tracked.iter().enumerate() {
103 let later = self.tracked.get(index + 1..).unwrap_or_default();
104 let values: Vec<&str> = set
105 .values
106 .iter()
107 .filter(|value| !later.iter().any(|later| later.values.contains(*value)))
108 .map(String::as_str)
109 .collect();
110 if !values.is_empty() {
111 let _ = write!(
112 text,
113 "\n\n<{name}>\n{}\n</{name}>",
114 values.join("\n"),
115 name = set.name
116 );
117 }
118 }
119 Some(text)
120 }
121
122 pub fn track(&mut self, messages: &[impl Borrow<Message>], rules: &[TrackArgument]) {
125 for rule in rules {
126 if !self.tracked.iter().any(|set| set.name == rule.set) {
127 self.tracked.push(TrackedSet {
128 name: rule.set.clone().into_owned(),
129 values: BTreeSet::new(),
130 });
131 }
132 }
133 let paired = pairing::pair(
134 messages
135 .iter()
136 .map(|message| Some(message.borrow().clone()))
137 .collect(),
138 pairing::Pairing::canonical(),
139 );
140 let mut waiting: Vec<&ToolCall> = Vec::new();
141 for message in &paired.messages {
142 match message {
143 Message::Assistant(reply) => {
144 waiting = reply.tool_calls().collect();
145 }
146 Message::User { content } => {
147 for result in content.iter().filter_map(|part| match part {
148 UserContent::ToolResult(result) => Some(result),
149 _ => None,
150 }) {
151 let Some(at) = waiting.iter().position(|call| call.id == result.call)
152 else {
153 continue;
154 };
155 let call = waiting.remove(at);
156 if result.is_error {
157 continue;
158 }
159 for rule in rules {
160 let set = self.tracked.iter_mut().find(|set| set.name == rule.set);
161 if let (Some(value), Some(set)) = (rule.value(call), set) {
162 set.values.insert(value.to_owned());
163 }
164 }
165 }
166 }
167 Message::System { .. } => {}
168 }
169 }
170 }
171}
172
173fn cut_at(
181 messages: &[Arc<Message>],
182 from: usize,
183 keep_tokens: usize,
184 force: bool,
185 counter: &impl TokenCounter,
186) -> Option<usize> {
187 let mut kept = 0;
188 let mut newest = None;
189 for (index, message) in messages.iter().enumerate().skip(from + 1).rev() {
190 kept += counter.count(message);
191 if !can_start_live(message) {
192 continue;
193 }
194 newest.get_or_insert(index);
195 if kept >= keep_tokens {
196 return Some(index);
197 }
198 }
199 newest.filter(|_| force)
200}
201
202fn can_start_live(message: &Message) -> bool {
205 match message {
206 Message::User { content } => !content
207 .iter()
208 .any(|item| matches!(item, UserContent::ToolResult(_))),
209 Message::Assistant(_) | Message::System { .. } => true,
210 }
211}
212
213#[derive(Clone, Debug, PartialEq, Eq)]
215pub enum CompactReason {
216 Asked {
218 focus: String,
220 },
221 Threshold,
224 Overflow,
226}
227
228#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
249#[serde(from = "PolicyTable", into = "PolicyTable")]
250pub struct CompactionPolicy {
251 pub summarizer: Summarizer,
254 pub tracked: Vec<TrackArgument>,
256 pub keep_recent: usize,
260 pub keep_asked: usize,
263 pub clearing: ClearToolOutputs,
265 pub near_window: NearWindow,
267}
268
269impl Default for CompactionPolicy {
270 fn default() -> Self {
275 Self {
276 summarizer: Summarizer::DEFAULT,
277 tracked: Vec::new(),
278 keep_recent: 20_000,
279 keep_asked: 0,
280 clearing: ClearToolOutputs::default(),
281 near_window: NearWindow::default(),
282 }
283 }
284}
285
286#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
289#[serde(rename_all = "lowercase")]
290pub enum NearWindow {
291 #[default]
294 Summarize,
295 Clear,
297}
298
299#[derive(Serialize, Deserialize)]
301#[serde(default, deny_unknown_fields)]
302struct PolicyTable {
303 prompts: SummaryPrompts,
304 limits: SummaryLimits,
305 tracked: Vec<TrackArgument>,
306 keep_recent: usize,
307 keep_asked: usize,
308 clearing: ClearToolOutputs,
309 near_window: NearWindow,
310}
311
312impl Default for PolicyTable {
313 fn default() -> Self {
314 CompactionPolicy::default().into()
315 }
316}
317
318impl From<PolicyTable> for CompactionPolicy {
319 fn from(table: PolicyTable) -> Self {
320 Self {
321 summarizer: Summarizer {
322 prompts: table.prompts,
323 limits: table.limits,
324 },
325 tracked: table.tracked,
326 keep_recent: table.keep_recent,
327 keep_asked: table.keep_asked,
328 clearing: table.clearing,
329 near_window: table.near_window,
330 }
331 }
332}
333
334impl From<CompactionPolicy> for PolicyTable {
335 fn from(policy: CompactionPolicy) -> Self {
336 Self {
337 prompts: policy.summarizer.prompts,
338 limits: policy.summarizer.limits,
339 tracked: policy.tracked,
340 keep_recent: policy.keep_recent,
341 keep_asked: policy.keep_asked,
342 clearing: policy.clearing,
343 near_window: policy.near_window,
344 }
345 }
346}
347
348pub fn estimate_tokens(messages: &[impl Borrow<Message>]) -> u64 {
351 let counter = HeuristicTokenCounter::default();
352 messages
353 .iter()
354 .map(|message| counter.count(message.borrow()) as u64)
355 .fold(0, u64::saturating_add)
356}
357
358impl CompactionPolicy {
359 pub fn over_threshold(&self, tokens: u64, spec: &ModelSpec) -> bool {
363 spec.input_limit().is_some_and(|limit| {
364 tokens > u64::from(limit).saturating_sub(self.summarizer.limits.reserve)
365 })
366 }
367
368 pub fn keep(&self, reason: &CompactReason, spec: Option<&ModelSpec>) -> usize {
371 match reason {
372 CompactReason::Asked { .. } => self.keep_asked,
373 CompactReason::Threshold | CompactReason::Overflow => spec
374 .and_then(ModelSpec::input_limit)
375 .map_or(self.keep_recent, |limit| {
376 self.keep_recent
377 .min(usize::try_from(limit / 4).unwrap_or(usize::MAX))
378 }),
379 }
380 }
381
382 pub fn cut(
390 &self,
391 messages: &[Arc<Message>],
392 from: usize,
393 reason: &CompactReason,
394 spec: Option<&ModelSpec>,
395 ) -> Option<usize> {
396 cut_at(
397 messages,
398 from,
399 self.keep(reason, spec),
400 !matches!(reason, CompactReason::Threshold),
401 &HeuristicTokenCounter::default(),
402 )
403 }
404
405 pub fn plan(
409 &self,
410 state: &SummaryState,
411 messages: &[Arc<Message>],
412 from: usize,
413 upto: usize,
414 spec: &ModelSpec,
415 reason: &CompactReason,
416 ) -> Result<(SummaryState, CompletionRequest), UnsupportedOption> {
417 let older = messages.get(from.min(upto)..upto).unwrap_or_default();
418 let request = self
419 .summarizer
420 .request(older, &state.summary, reason, spec)?;
421 let mut next = state.clone();
422 next.track(older, &self.tracked);
423 Ok((next, request))
424 }
425}
426
427pub fn summary_author() -> Author {
429 Author::plugin("compaction")
430}
431
432pub fn summary_in(change: &Change) -> Option<MessageId> {
437 let Change::Splice { removed, with, .. } = change else {
438 return None;
439 };
440 let kept = |id: &MessageId| with.iter().any(|entry| entry.id == Some(*id));
441 if removed.iter().all(kept) {
442 return None;
443 }
444 let summary = summary_author();
445 with.iter()
446 .find(|entry| entry.author.as_ref() == Some(&summary))
447 .and_then(|entry| entry.id)
448}
449
450pub fn summarized_prefix(conversation: &Conversation) -> usize {
456 let author = summary_author();
457 let summaries = conversation.entries();
458 summaries
459 .take_while(|entry| entry.author == Some(&author))
460 .count()
461}
462
463#[derive(Clone, Debug)]
465pub struct SummaryPlan {
466 pub keep_from: Option<MessageId>,
470 pub state: SummaryState,
472 pub request: CompletionRequest,
474}
475
476#[derive(Clone, Debug)]
480pub struct SummaryCut {
481 pub keep_from: Option<MessageId>,
484 pub state: SummaryState,
487}
488
489impl CompactionPolicy {
490 pub fn cut_summary(
493 &self,
494 conversation: &Conversation,
495 state: &SummaryState,
496 reason: &CompactReason,
497 spec: &ModelSpec,
498 ) -> Option<SummaryCut> {
499 let messages = conversation.messages();
500 let from = summarized_prefix(conversation);
501 let upto = self.cut(messages, from, reason, Some(spec))?;
502 let mut next = state.clone();
503 next.track(
504 messages.get(from.min(upto)..upto).unwrap_or_default(),
505 &self.tracked,
506 );
507 Some(SummaryCut {
508 keep_from: conversation.id(upto),
509 state: next,
510 })
511 }
512
513 pub fn plan_summary(
520 &self,
521 conversation: &Conversation,
522 state: &SummaryState,
523 reason: &CompactReason,
524 spec: &ModelSpec,
525 ) -> Result<Option<SummaryPlan>, UnsupportedOption> {
526 let messages = conversation.messages();
527 let from = summarized_prefix(conversation);
528 let Some(upto) = self.cut(messages, from, reason, Some(spec)) else {
529 return Ok(None);
530 };
531 let (state, request) = self.plan(state, messages, from, upto, spec, reason)?;
532 Ok(Some(SummaryPlan {
533 keep_from: conversation.id(upto),
534 state,
535 request,
536 }))
537 }
538}
539
540pub fn apply_summary(
548 conversation: &mut Conversation,
549 keep_from: Option<MessageId>,
550 state: &SummaryState,
551) -> Option<Spliced> {
552 let end = match keep_from {
553 None => conversation.messages().len(),
554 Some(kept) => conversation.index_of(kept)?,
555 };
556 let summary = Entry::new(Message::user(state.message()?)).by(summary_author());
557 let spliced = conversation.splice(..end, [summary], summary_author());
558 if let Some(&summary) = spliced.changed.first() {
559 let compacted = Compacted {
560 summary,
561 replaced: spliced.removed.clone(),
562 state: state.clone(),
563 };
564 let value = serde_json::to_value(compacted).unwrap_or_default();
565 let aside = Aside::new(COMPACTED, summary_author(), value).after(Some(summary));
566 conversation.add_aside(aside);
567 }
568 Some(spliced)
569}
570
571pub const COMPACTED: &str = "rig.compaction";
573
574pub fn summary_state(conversation: &Conversation) -> SummaryState {
577 Compacted::of(conversation)
578 .last()
579 .map(|(_, compacted)| compacted.state)
580 .unwrap_or_default()
581}
582
583#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
587pub struct Compacted {
588 pub summary: MessageId,
590 pub replaced: Vec<MessageId>,
592 pub state: SummaryState,
594}
595
596impl Compacted {
597 pub fn of(conversation: &Conversation) -> impl Iterator<Item = (AsideId, Self)> + '_ {
600 let author = summary_author();
601 let records = conversation.asides();
602 let ours =
603 records.filter(move |(_, aside)| aside.kind == COMPACTED && aside.author == author);
604 ours.filter_map(|(id, aside)| Some((id, Self::deserialize(&aside.value).ok()?)))
605 }
606}
607
608#[derive(Clone, Debug, Default, PartialEq, Eq)]
610pub struct Uncompacted {
611 pub restored: Vec<MessageId>,
613 pub state: SummaryState,
616}
617
618#[derive(Debug, thiserror::Error)]
620pub enum UndoError {
621 #[error("there is no compaction to undo")]
623 Nothing,
624 #[error("its summary is no longer in the conversation")]
626 SummaryGone,
627 #[error("the session's log does not hold what it replaced")]
630 NotInLog,
631 #[error(transparent)]
633 Load(#[from] SessionError),
634}
635
636pub fn undo_summary(
648 conversation: &mut Conversation,
649 store: &dyn Store,
650 log: &str,
651 by: Author,
652) -> Result<Uncompacted, UndoError> {
653 let (aside, compacted) = Compacted::of(conversation)
654 .last()
655 .ok_or(UndoError::Nothing)?;
656 let at = conversation
657 .index_of(compacted.summary)
658 .ok_or(UndoError::SummaryGone)?;
659 let originals = summarized_in_log(store, log)?
660 .replaced
661 .remove(&compacted.summary)
662 .ok_or(UndoError::NotInLog)?;
663 let restored = conversation.restore(at..=at, originals, by).restored;
664 conversation.remove_aside(aside);
665 let state = Compacted::of(conversation).last().map(|(_, it)| it.state);
666 Ok(Uncompacted {
667 restored,
668 state: state.unwrap_or_default(),
669 })
670}
671
672#[derive(Clone, Debug, Default, PartialEq)]
674pub struct Summarized {
675 pub replaced: BTreeMap<MessageId, Vec<Entry>>,
678 pub records: BTreeMap<MessageId, Compacted>,
681}
682
683pub fn summarized_in_log(store: &dyn Store, log: &str) -> Result<Summarized, SessionError> {
692 let mut first: BTreeMap<MessageId, Option<Vec<Entry>>> = BTreeMap::new();
693 let mut records = BTreeMap::new();
694 replay(store, log, |before, recorded| {
695 let change = &recorded.change;
696 let (Some(summary), Change::Splice { removed, with, .. }) = (summary_in(change), change)
697 else {
698 return;
699 };
700 let kept = |id: &&MessageId| with.iter().any(|entry| entry.id == Some(**id));
701 let taken: Vec<&MessageId> = removed.iter().filter(|id| !kept(id)).collect();
702 for (_, record) in Compacted::of(before) {
703 if taken.contains(&&record.summary) {
704 records.entry(record.summary).or_insert(record);
705 }
706 }
707 first.entry(summary).or_insert_with(|| {
708 taken
709 .iter()
710 .map(|id| before.entry(before.index_of(**id)?))
711 .collect()
712 });
713 })?;
714 let found = first.into_iter();
715 let replaced = found
716 .filter_map(|(summary, taken)| Some((summary, taken?)))
717 .collect();
718 Ok(Summarized { replaced, records })
719}
720
721#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
724#[serde(default, deny_unknown_fields)]
725pub struct SummaryPrompts {
726 pub system: Cow<'static, str>,
728 pub initial: Cow<'static, str>,
730 pub update: Cow<'static, str>,
732 pub format: Cow<'static, str>,
734 pub in_place: Cow<'static, str>,
738 pub notes: Cow<'static, str>,
741}
742
743impl SummaryPrompts {
744 pub const DEFAULT: Self = Self {
747 system: Cow::Borrowed(
748 "You summarize a conversation between a user and a coding agent so that another \
749 model can continue the work from the summary alone. Read the conversation and \
750 write the summary in the exact format asked for.\n\n\
751 Do not continue the conversation. Do not answer questions in it. Output only the \
752 summary.",
753 ),
754 initial: Cow::Borrowed(
755 "The conversation above is to be summarized. Write a structured checkpoint of it \
756 that another model will use to continue the work.",
757 ),
758 update: Cow::Borrowed(
759 "The conversation above is the NEW part of a conversation whose earlier part is \
760 summarized in <previous-summary>. Update that summary with it:\n\
761 - keep everything in the previous summary that still holds;\n\
762 - add the new progress, decisions and context;\n\
763 - move items from \"In progress\" to \"Done\" when they were completed;\n\
764 - update \"Next steps\" to what is left;\n\
765 - drop what is no longer relevant.",
766 ),
767 format: Cow::Borrowed(
768 "\n\nUse exactly this format:\n\n\
769 ## Goal\n\
770 [What the user is trying to get done; several items if the session covers several \
771 tasks.]\n\n\
772 ## Constraints and preferences\n\
773 - [What the user asked for or ruled out, or \"(none)\"]\n\n\
774 ## Progress\n\
775 ### Done\n\
776 - [x] [Completed tasks and changes]\n\
777 ### In progress\n\
778 - [ ] [Current work]\n\
779 ### Blocked\n\
780 - [What prevents progress, if anything]\n\n\
781 ## Key decisions\n\
782 - **[Decision]**: [Why]\n\n\
783 ## Next steps\n\
784 1. [What should happen next, in order]\n\n\
785 ## Critical context\n\
786 - [Every specific value the work or the user may still need, copied character for \
787 character from the messages, tool outputs, notes on cleared outputs and the earlier \
788 summary: names, numbers, identifiers, paths, commands, errors. Never guess a value. Or \
789 \"(none)\".]\n\n\
790 Do not copy file contents or long outputs: a file on disk can be read again, so \
791 give its path and what in it matters.\n\n\
792 Keep each section short, except Critical context. Keep exact file paths, function \
793 names, commands and error messages.",
794 ),
795 in_place: Cow::Borrowed(
796 "Stop here: do not continue the work, do not answer the user and do not call any \
797 tool. Instead write a structured checkpoint of the conversation above. It replaces \
798 that conversation, so another model must be able to continue the work from it and \
799 the messages kept after it alone. If the conversation opens with a summary of an \
800 earlier part, fold it in: keep everything in it that still holds, every value under \
801 \"Critical context\" word for word, add the new progress, decisions and context, \
802 move items from \"In progress\" to \"Done\" when they were completed, and update \
803 \"Next steps\".",
804 ),
805 notes: Cow::Borrowed(
806 "Stop here: do not continue the work, do not answer the user and do not call any \
807 tool. To fit the context window, the larger tool outputs above are about to be \
808 replaced by a placeholder. Your messages, the user's messages, the tool calls and \
809 earlier notes stay as they are. Write notes that keep what those outputs hold that \
810 the work or the user may still need and that calling a tool again would not give \
811 back exactly:\n\
812 - every specific value, copied character for character: names, numbers, codes, \
813 identifiers, paths, URLs, versions, dates, settings, commands and error messages;\n\
814 - results and findings the work depends on;\n\
815 - when an output updates an earlier value, the newest value and which one it \
816 replaces.\n\n\
817 Copy only what the outputs say: never guess, complete or correct a value. Leave out \
818 what a tool would show again unchanged, such as a file still on disk. Don't repeat \
819 earlier notes. Write short lists grouped by the call they come from, and output only \
820 the notes.",
821 ),
822 };
823}
824
825#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
828#[serde(default, deny_unknown_fields)]
829pub struct SummaryLimits {
830 pub reserve: u64,
832 pub summary_tokens: u64,
834 pub snippet_chars: usize,
836 pub unknown_window_chars: usize,
838}
839
840impl SummaryLimits {
841 pub const DEFAULT: Self = Self {
844 reserve: 16_384,
845 summary_tokens: 32_000,
846 snippet_chars: 2_000,
847 unknown_window_chars: 400_000,
848 };
849}
850
851impl Default for SummaryLimits {
852 fn default() -> Self {
853 Self::DEFAULT
854 }
855}
856
857impl Default for SummaryPrompts {
858 fn default() -> Self {
859 Self::DEFAULT
860 }
861}
862
863#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
868#[serde(default, deny_unknown_fields)]
869pub struct Summarizer {
870 pub prompts: SummaryPrompts,
872 pub limits: SummaryLimits,
874}
875
876impl Summarizer {
877 pub const DEFAULT: Self = Self {
879 prompts: SummaryPrompts::DEFAULT,
880 limits: SummaryLimits::DEFAULT,
881 };
882}
883
884impl Default for Summarizer {
885 fn default() -> Self {
886 Self::DEFAULT
887 }
888}
889
890fn within(tokens: u64) -> String {
893 format!("\n\nKeep it under {tokens} tokens: a longer answer is cut off and thrown away.")
894}
895
896#[derive(Clone, Debug, PartialEq, Eq)]
898#[non_exhaustive]
899pub enum SummaryError {
900 Truncated,
902 CalledTool,
904 Empty,
906 Failed(String),
908}
909
910impl fmt::Display for SummaryError {
911 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
912 f.write_str(match self {
913 Self::Truncated => "the summary hit the model's output limit",
914 Self::CalledTool => "the model called a tool instead of summarizing",
915 Self::Empty => "the model returned no summary",
916 Self::Failed(why) => why,
917 })
918 }
919}
920
921impl std::error::Error for SummaryError {}
922
923pub fn known_limits(spec: &ModelSpec) -> bool {
928 spec.max_output_tokens.is_some() || spec.context_window.is_some()
929}
930
931pub const AFTER_OVERFLOW: u64 = 2;
935
936impl Summarizer {
937 pub fn request(
946 &self,
947 older: &[Arc<Message>],
948 previous: &str,
949 reason: &CompactReason,
950 spec: &ModelSpec,
951 ) -> Result<CompletionRequest, UnsupportedOption> {
952 let limits = &self.limits;
953 let focus = match reason {
954 CompactReason::Asked { focus } => focus.trim(),
955 _ => "",
956 };
957 let (most, budget) = match spec.input_limit().map(u64::from) {
958 None => (self.max_tokens(spec), limits.unknown_window_chars),
959 Some(limit) => {
960 let limit = match reason {
961 CompactReason::Overflow => limit / AFTER_OVERFLOW,
962 _ => limit,
963 };
964 let room = limit.saturating_sub(limits.reserve).max(limit / 2);
966 let most = self.max_tokens(spec).min(room / 2);
967 let chars = room.saturating_sub(most).saturating_mul(3);
969 (most, usize::try_from(chars).unwrap_or(usize::MAX))
970 }
971 };
972 let conversation = self.serialize(older);
973 let conversation = keep_end(&conversation, budget.saturating_sub(previous.len()));
974 let mut prompt = format!("<conversation>\n{conversation}\n</conversation>\n\n");
975 if previous.is_empty() {
976 prompt.push_str(&self.prompts.initial);
977 } else {
978 let _ = write!(
979 prompt,
980 "<previous-summary>\n{previous}\n</previous-summary>\n\n{}",
981 self.prompts.update
982 );
983 }
984 if !focus.is_empty() {
985 let _ = write!(prompt, "\n\nAdditional focus: {focus}");
986 }
987 prompt.push_str(&self.prompts.format);
988 prompt.push_str(&within(most));
989 let options = spec.default_options(None);
990 spec.validate(&options)?;
991 let request = CompletionRequest::new(Message::user(prompt))
992 .preamble(self.prompts.system.clone().into_owned())
993 .options(options);
994 Ok(if known_limits(spec) {
995 request.max_tokens(most)
996 } else {
997 request
998 })
999 }
1000
1001 pub fn max_tokens(&self, spec: &ModelSpec) -> u64 {
1004 let most = self.limits.summary_tokens;
1005 spec.max_output_tokens
1006 .map_or(most, |model| most.min(u64::from(model)))
1007 }
1008
1009 pub fn instruction(&self, focus: &str, tokens: u64) -> String {
1016 let mut text = self.prompts.in_place.clone().into_owned();
1017 if !focus.is_empty() {
1018 let _ = write!(text, "\n\nAdditional focus: {focus}");
1019 }
1020 text.push_str(&self.prompts.format);
1021 text.push_str(&within(tokens));
1022 text
1023 }
1024
1025 pub fn notes_instruction(&self, tokens: u64) -> String {
1029 let mut text = self.prompts.notes.clone().into_owned();
1030 text.push_str(&within(tokens));
1031 text
1032 }
1033
1034 pub fn summary_text(response: &CompletionResponse) -> Result<String, SummaryError> {
1036 match response.stop() {
1037 StopReason::Length => return Err(SummaryError::Truncated),
1038 StopReason::ToolUse => return Err(SummaryError::CalledTool),
1039 StopReason::Error(why) | StopReason::Aborted(why) => {
1040 return Err(SummaryError::Failed(why));
1041 }
1042 _ => {}
1043 }
1044 let text = response.text();
1045 let text = text.trim();
1046 if text.is_empty() {
1047 return Err(SummaryError::Empty);
1048 }
1049 Ok(text.to_owned())
1050 }
1051
1052 fn serialize(&self, messages: &[Arc<Message>]) -> String {
1055 let snippet = |text: &str| snippet(text, self.limits.snippet_chars);
1056 let mut parts: Vec<String> = Vec::new();
1057 for message in messages {
1058 match &**message {
1059 Message::System { content } => parts.push(format!("[System]: {content}")),
1060 Message::User { content } => {
1061 for item in content {
1062 match item {
1063 UserContent::Text(text) => {
1064 parts.push(format!("[User]: {}", text.text));
1065 }
1066 UserContent::ToolResult(result) => {
1067 let output: Vec<String> = result
1068 .content
1069 .iter()
1070 .map(|part| match part {
1071 ToolResultContent::Text(text) => text.text.clone(),
1072 ToolResultContent::Json { value } => value.to_string(),
1073 ToolResultContent::Image(_) => "[image]".to_owned(),
1074 })
1075 .collect();
1076 let label = if result.is_error {
1077 "Tool error"
1078 } else {
1079 "Tool result"
1080 };
1081 parts.push(format!("[{label}]: {}", snippet(&output.join("\n"))));
1082 }
1083 _ => parts.push("[User]: [attachment]".to_owned()),
1084 }
1085 }
1086 }
1087 Message::Assistant(reply) => {
1088 for item in &reply.content {
1089 match item {
1090 AssistantContent::Text(text) => {
1091 parts.push(format!("[Assistant]: {}", text.text));
1092 }
1093 AssistantContent::Reasoning(reasoning)
1094 if !reasoning.text.is_empty() =>
1095 {
1096 parts.push(format!("[Assistant thinking]: {}", reasoning.text));
1097 }
1098 AssistantContent::ToolCall(call) => {
1099 let arguments = serde_json::to_string(&call.function.arguments);
1100 parts.push(format!(
1101 "[Assistant tool call]: {}({})",
1102 call.function.name.as_str(),
1103 snippet(&arguments.unwrap_or_default())
1104 ));
1105 }
1106 _ => {}
1107 }
1108 }
1109 }
1110 }
1111 }
1112 parts.join("\n\n")
1113 }
1114}
1115
1116fn keep_end(text: &str, budget: usize) -> String {
1119 if text.len() <= budget {
1120 return text.to_owned();
1121 }
1122 let start = text.ceil_char_boundary(text.len() - budget);
1123 let rest = text.get(start..).unwrap_or_default();
1124 format!("[… {start} earlier characters left out]\n{rest}")
1125}
1126
1127fn snippet(text: &str, chars: usize) -> String {
1129 match text.char_indices().nth(chars) {
1130 Some((end, _)) => format!(
1131 "{}\n[… {} more characters]",
1132 text.get(..end).unwrap_or_default(),
1133 text.len() - end
1134 ),
1135 None => text.to_owned(),
1136 }
1137}
1138
1139#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
1141pub struct Cleared {
1142 pub results: usize,
1144 pub tokens: usize,
1146}
1147
1148#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1157#[serde(default, deny_unknown_fields)]
1158pub struct ClearToolOutputs {
1159 pub keep_tokens: usize,
1161 pub keep_under: usize,
1163}
1164
1165impl Default for ClearToolOutputs {
1166 fn default() -> Self {
1168 Self {
1169 keep_tokens: 20_000,
1170 keep_under: 500,
1171 }
1172 }
1173}
1174
1175impl ClearToolOutputs {
1176 pub const PLACEHOLDER: &'static str =
1178 "[output cleared to fit the context window; run the tool again if needed]";
1179
1180 pub fn new(keep_tokens: usize) -> Self {
1193 Self {
1194 keep_tokens,
1195 ..Self::default()
1196 }
1197 }
1198
1199 pub fn clear(&self, messages: &mut [Arc<Message>]) -> Cleared {
1201 let (targets, cleared) = self.targets(messages);
1202 for (at, items) in targets {
1203 if let Some(message) = messages.get_mut(at) {
1204 clear_items(Arc::make_mut(message), &items);
1205 }
1206 }
1207 cleared
1208 }
1209
1210 pub fn clear_conversation(&self, conversation: &mut Conversation, by: Author) -> Cleared {
1214 self.plan(conversation).apply(conversation, None, by)
1215 }
1216
1217 pub fn plan(&self, conversation: &Conversation) -> ClearPlan {
1221 let (targets, cleared) = self.targets(conversation.messages());
1222 let through = targets
1223 .keys()
1224 .next_back()
1225 .and_then(|&at| conversation.id(at));
1226 let targets = targets.into_iter();
1227 let targets = targets.filter_map(|(at, items)| Some((conversation.id(at)?, items)));
1228 ClearPlan {
1229 cleared,
1230 through,
1231 targets: targets.collect(),
1232 }
1233 }
1234
1235 fn targets(&self, messages: &[impl Borrow<Message>]) -> (BTreeMap<usize, Vec<usize>>, Cleared) {
1238 let counter = HeuristicTokenCounter::default();
1239 let mut cleared = Cleared::default();
1240 let mut targets: BTreeMap<usize, Vec<usize>> = BTreeMap::new();
1241 let mut kept = 0;
1242 let Some((_, earlier)) = messages.split_last() else {
1243 return (targets, cleared);
1244 };
1245 for (at, message) in earlier.iter().enumerate().rev() {
1246 let Message::User { content } = message.borrow() else {
1247 continue;
1248 };
1249 for (item_at, item) in content.iter().enumerate().rev() {
1250 let tokens = counter.count_user(item);
1251 let UserContent::ToolResult(result) = item else {
1252 continue;
1253 };
1254 if result.is_error || is_cleared(&result.content) || tokens < self.keep_under {
1255 continue;
1256 }
1257 kept += tokens;
1258 if kept <= self.keep_tokens {
1259 continue;
1260 }
1261 targets.entry(at).or_default().push(item_at);
1262 cleared.results += 1;
1263 cleared.tokens += tokens;
1264 }
1265 }
1266 (targets, cleared)
1267 }
1268}
1269
1270#[derive(Clone, Debug, Default, PartialEq, Eq)]
1273pub struct ClearPlan {
1274 pub cleared: Cleared,
1276 pub through: Option<MessageId>,
1279 targets: BTreeMap<MessageId, Vec<usize>>,
1280}
1281
1282impl ClearPlan {
1283 pub fn results<'c>(
1285 &self,
1286 conversation: &'c Conversation,
1287 ) -> impl Iterator<Item = &'c ToolResult> {
1288 conversation.entries().flat_map(move |entry| {
1289 let content = match entry.message {
1290 Message::User { content } => content.as_slice(),
1291 _ => &[],
1292 };
1293 let items = self.targets.get(&entry.id).into_iter().flatten();
1294 items.filter_map(|&at| match content.get(at) {
1295 Some(UserContent::ToolResult(result)) => Some(result),
1296 _ => None,
1297 })
1298 })
1299 }
1300
1301 pub fn apply(
1306 &self,
1307 conversation: &mut Conversation,
1308 notes: Option<&str>,
1309 by: Author,
1310 ) -> Cleared {
1311 conversation.edit_each(by, |entry| {
1312 let items = self.targets.get(&entry.id);
1313 let notes = notes.filter(|_| self.through == Some(entry.id));
1314 if items.is_none() && notes.is_none() {
1315 return None;
1316 }
1317 let items = items.map_or(&[][..], Vec::as_slice);
1318 let mut message = entry.message.clone();
1319 clear_items(&mut message, items);
1320 let noted = match (notes, &mut message) {
1321 (Some(notes), Message::User { content }) => {
1322 content.push(UserContent::text(format!(
1323 "<cleared-output-notes>\nNotes on the tool outputs above, written \
1324 before they were cleared:\n{}\n</cleared-output-notes>",
1325 notes.trim()
1326 )));
1327 true
1328 }
1329 _ => false,
1330 };
1331 (!items.is_empty() || noted).then_some(message)
1332 });
1333 self.cleared
1334 }
1335}
1336
1337fn clear_items(message: &mut Message, items: &[usize]) {
1339 let Message::User { content } = message else {
1340 return;
1341 };
1342 for (at, item) in content.iter_mut().enumerate() {
1343 if let UserContent::ToolResult(result) = item
1344 && items.contains(&at)
1345 {
1346 result.content = vec![ToolResultContent::text(ClearToolOutputs::PLACEHOLDER)];
1347 }
1348 }
1349}
1350
1351fn is_cleared(content: &[ToolResultContent]) -> bool {
1353 matches!(content, [only] if only.as_text() == Some(ClearToolOutputs::PLACEHOLDER))
1354}
1355
1356#[cfg(test)]
1357mod tests;