Skip to main content

rig_memory/
compaction.rs

1//! Compacting a long conversation: a [`CompactionPolicy`] says when and where to cut and plans
2//! the summary, which [`apply_summary`] puts in place of the older messages; [`ClearToolOutputs`]
3//! frees context without a model call. The default prompts and limits follow the
4//! [pi coding agent](https://github.com/badlogic/pi-mono).
5//!
6//! ```
7//! use rig_memory::{CompactionPolicy, SummaryState};
8//!
9//! let policy = CompactionPolicy::default();
10//! let reason = rig_memory::CompactReason::Threshold;
11//! assert_eq!(policy.cut(&[], 0, &reason, None), None);
12//! assert_eq!(SummaryState::default().message(), None);
13//! ```
14
15use 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/// A summary of a conversation's older messages and the values tracked
34/// across compactions (such as the files a coding agent read). The default
35/// is the state before the first compaction.
36#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
37pub struct SummaryState {
38    /// The summary; empty before the first compaction.
39    pub summary: String,
40    /// Named sets of values, in the order they were first tracked.
41    #[serde(default, skip_serializing_if = "Vec::is_empty")]
42    pub tracked: Vec<TrackedSet>,
43}
44
45/// One named set of a [`SummaryState`], sent after the summary inside a
46/// `<name>` tag.
47#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
48pub struct TrackedSet {
49    /// The set's name, also its tag.
50    pub name: String,
51    /// Its values.
52    pub values: BTreeSet<String>,
53}
54
55/// A rule of [`SummaryState::track`]: the string argument `argument` of
56/// every call of the tool `tool` that succeeded goes into the set `set`.
57#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
58pub struct TrackArgument {
59    /// The tool's name.
60    pub tool: Cow<'static, str>,
61    /// The argument's name.
62    pub argument: Cow<'static, str>,
63    /// The set's name.
64    pub set: Cow<'static, str>,
65}
66
67impl TrackArgument {
68    /// The rule tracking `argument` of `tool` in the set `set`.
69    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    /// The argument it tracks of `call`, when `call` is of its tool and
78    /// that argument is a string.
79    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    /// The text that stands for the summarized messages, `None` before the
90    /// first compaction. A value appears only in the last set that holds
91    /// it, so a later set (files changed) overrides an earlier one (files
92    /// read).
93    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    /// Adds the arguments `rules` name of successful tool calls in `messages` to
123    /// the tracked sets, creating the rules' sets in rule order first.
124    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
173/// Where a new compaction of `messages`, whose first `from` are summarized
174/// already, should end: the first message it keeps. Walking back from the
175/// newest message, it keeps at least `keep_tokens` and cuts before a reply
176/// or a user's own message, never between a tool call and its result.
177/// With `force`, a shorter conversation still has its older messages
178/// summarized, all but the newest reply or message. `None` when nothing
179/// new would be summarized.
180fn 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
202/// Whether the messages a request sends as they are may start with
203/// `message`: a reply, or a user message that answers no tool call.
204fn 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/// Why a conversation is compacted.
214#[derive(Clone, Debug, PartialEq, Eq)]
215pub enum CompactReason {
216    /// The user asked, with what to focus on, if anything.
217    Asked {
218        /// What the summary should keep above all; may be empty.
219        focus: String,
220    },
221    /// The next request would leave less than the reserve of the model's
222    /// input limit free.
223    Threshold,
224    /// The model refused the request as too long.
225    Overflow,
226}
227
228/// How a conversation is compacted: what the summarizer is asked, the tool
229/// arguments a summary keeps track of, such as the files a coding agent's
230/// file tools read and changed, how much of the newest conversation stays
231/// as it is, and how old tool outputs are cleared first. Tokens are
232/// estimated by the default [`HeuristicTokenCounter`].
233///
234/// Its serde form is one flat table, the summarizer's `prompts` and
235/// `limits` beside the other fields; each field missing is the default's,
236/// and an unknown one is refused.
237///
238/// ```
239/// use rig_memory::CompactionPolicy;
240///
241/// let policy: CompactionPolicy =
242///     serde_json::from_value(serde_json::json!({"keep_recent": 1000, "limits": {"reserve": 1}}))?;
243/// assert_eq!(policy.keep_recent, 1000);
244/// assert_eq!(policy.summarizer.limits.reserve, 1);
245/// assert_eq!(policy.keep_asked, CompactionPolicy::default().keep_asked);
246/// # Ok::<(), serde_json::Error>(())
247/// ```
248#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
249#[serde(from = "PolicyTable", into = "PolicyTable")]
250pub struct CompactionPolicy {
251    /// The summarizer; its reserve is how much of the model's input limit
252    /// is kept free.
253    pub summarizer: Summarizer,
254    /// The tool arguments tracked across compactions.
255    pub tracked: Vec<TrackArgument>,
256    /// Tokens of the newest messages an automatic compaction keeps as they
257    /// are, a quarter of the model's input limit at most: the work carries on,
258    /// so its recent part stays.
259    pub keep_recent: usize,
260    /// Tokens of the newest messages a compaction the user asked for keeps
261    /// as they are; the newest reply or message always stays.
262    pub keep_asked: usize,
263    /// How old tool outputs are cleared before a summary is asked for.
264    pub clearing: ClearToolOutputs,
265    /// What happens to the tool outputs a clearing near the window drops.
266    pub near_window: NearWindow,
267}
268
269impl Default for CompactionPolicy {
270    /// [`Summarizer::DEFAULT`], nothing tracked, the newest 20k tokens kept
271    /// by an automatic compaction and none beyond the newest reply or
272    /// message by an asked one, [`ClearToolOutputs::default`], and notes
273    /// on what clearing drops near the window.
274    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/// What a clearing near the model's window does with the tool outputs it
287/// drops; its serde form is `"summarize"` or `"clear"`.
288#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
289#[serde(rename_all = "lowercase")]
290pub enum NearWindow {
291    /// The model first writes notes on the outputs that cannot be had
292    /// again ([`SummaryPrompts::notes`]), which stay after them.
293    #[default]
294    Summarize,
295    /// They are cleared with no model call.
296    Clear,
297}
298
299/// The serde form of a [`CompactionPolicy`]: one flat table.
300#[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
348/// The estimated tokens of `messages`, by the default
349/// [`HeuristicTokenCounter`], as a policy estimates them.
350pub 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    /// Whether a request of `tokens` leaves less than the summarizer's
360    /// reserve of `spec`'s [input limit](ModelSpec::input_limit) free.
361    /// Never, when the limit is not known.
362    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    /// Tokens of the newest messages a compaction for `reason` with `spec`
369    /// keeps as they are.
370    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    /// Where a compaction for `reason` should end: the index of the first
383    /// message it keeps, after the newest messages within
384    /// [`keep`](Self::keep) and never between a tool call and its result,
385    /// or `None` when nothing new would be summarized. `from` is how many
386    /// leading messages are summaries already ([`summarized_prefix`]). A
387    /// short conversation is still summarized when the user asked or the
388    /// model overflowed.
389    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    /// The summary request for a compaction ending at `upto`, and the
406    /// [`SummaryState`] the new summary goes into (with the tracked
407    /// arguments of the newly summarized messages).
408    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
427/// Who writes a compaction's summary: the author of its entry.
428pub fn summary_author() -> Author {
429    Author::plugin("compaction")
430}
431
432/// The summary a compaction put in, when `change` is one: the id of the
433/// entry by [`summary_author`] in a splice that took messages out.
434/// Clearing old tool outputs, by the same author, keeps every message and
435/// is none.
436pub 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
450/// How many of the first entries of `conversation` are summaries (by
451/// [`summary_author`]): what a new compaction builds on from its
452/// [`SummaryState`] instead of reading it again. It is the `from` the
453/// policy's [`cut`](CompactionPolicy::cut) and
454/// [`plan`](CompactionPolicy::plan) are given.
455pub 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/// A summary [`CompactionPolicy::plan_summary`] planned.
464#[derive(Clone, Debug)]
465pub struct SummaryPlan {
466    /// The first message the compaction keeps; `None` when it summarizes
467    /// every message. By id, so a splice made while the summary is written
468    /// does not move it.
469    pub keep_from: Option<MessageId>,
470    /// The state the summary goes into.
471    pub state: SummaryState,
472    /// The request for the summary.
473    pub request: CompletionRequest,
474}
475
476/// Where a compaction [`CompactionPolicy::cut_summary`] chose ends, with no
477/// request: for a summary asked at the end of the conversation itself
478/// ([`Summarizer::instruction`]).
479#[derive(Clone, Debug)]
480pub struct SummaryCut {
481    /// The first message kept, by id; `None` when it summarizes every
482    /// message.
483    pub keep_from: Option<MessageId>,
484    /// The state the summary goes into, with the tracked arguments of the
485    /// newly summarized messages.
486    pub state: SummaryState,
487}
488
489impl CompactionPolicy {
490    /// [`cut`](Self::cut) for `conversation`, with the state the summary
491    /// goes into. `None` when nothing new would be summarized.
492    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    /// [`cut`](Self::cut) and [`plan`](Self::plan) in one step, for
514    /// `conversation`. Returns `None` when nothing new would be summarized.
515    ///
516    /// # Errors
517    ///
518    /// When `spec` does not take the summary request's options.
519    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
540/// Puts the summary of `state` in place of the messages of
541/// `conversation` before `keep_from` (every message with `None`), earlier
542/// summaries included: one user entry by [`summary_author`], a splice it
543/// makes, followed by an aside of kind [`COMPACTED`] that says what it
544/// replaced ([`Compacted`]), so [`undo_summary`] can put that back.
545/// `None`, changing nothing, when `keep_from` was taken out meanwhile or
546/// `state` has no summary.
547pub 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
571/// The kind of the aside [`apply_summary`] puts after each summary.
572pub const COMPACTED: &str = "rig.compaction";
573
574/// The summary state the next compaction of `conversation` builds on: the
575/// newest compaction's not undone ([`Compacted`]), or the state before any.
576pub fn summary_state(conversation: &Conversation) -> SummaryState {
577    Compacted::of(conversation)
578        .last()
579        .map(|(_, compacted)| compacted.state)
580        .unwrap_or_default()
581}
582
583/// What a compaction replaced, kept with the conversation in an aside of
584/// kind [`COMPACTED`] by [`summary_author`] after its summary: the newest
585/// one is what [`undo_summary`] puts back.
586#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
587pub struct Compacted {
588    /// The summary's entry.
589    pub summary: MessageId,
590    /// The entries it replaced, earlier summaries included, in order.
591    pub replaced: Vec<MessageId>,
592    /// The state it put in, which the next compaction builds on.
593    pub state: SummaryState,
594}
595
596impl Compacted {
597    /// The record of every compaction of `conversation` not undone, oldest
598    /// first, each with its aside.
599    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/// What [`undo_summary`] did.
609#[derive(Clone, Debug, Default, PartialEq, Eq)]
610pub struct Uncompacted {
611    /// The entries put back in place of the summary, with their ids.
612    pub restored: Vec<MessageId>,
613    /// The summary state now: the compaction's before it, or the state
614    /// before any.
615    pub state: SummaryState,
616}
617
618/// Why [`undo_summary`] put nothing back.
619#[derive(Debug, thiserror::Error)]
620pub enum UndoError {
621    /// The conversation has no compaction left to undo.
622    #[error("there is no compaction to undo")]
623    Nothing,
624    /// The newest compaction's summary is no longer in the conversation.
625    #[error("its summary is no longer in the conversation")]
626    SummaryGone,
627    /// The session's log does not hold what it replaced, such as before
628    /// the compaction was saved.
629    #[error("the session's log does not hold what it replaced")]
630    NotInLog,
631    /// The session's log could not be read.
632    #[error(transparent)]
633    Load(#[from] SessionError),
634}
635
636/// Undoes the newest compaction of `conversation`, the conversation saved
637/// in the log `log` of `store`: the entries its summary replaced, read
638/// from that log as they were just before it, are put back in the
639/// summary's place with their ids ([`Conversation::restore`] by `by`), and
640/// its [`Compacted`] aside goes. Entries added after the summary stay
641/// after them. Undone one after another, compactions come back newest
642/// first, each with the summary it built on.
643///
644/// # Errors
645///
646/// [`UndoError`], changing nothing.
647pub 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/// What the compactions in a session's log replaced ([`summarized_in_log`]).
673#[derive(Clone, Debug, Default, PartialEq)]
674pub struct Summarized {
675    /// The entries each summary's splice ([`summary_in`]) took out, by the
676    /// summary's id, as they were just before it.
677    pub replaced: BTreeMap<MessageId, Vec<Entry>>,
678    /// The record of each summary a later compaction took out, by the
679    /// summary's id: the conversation lost it with its summary.
680    pub records: BTreeMap<MessageId, Compacted>,
681}
682
683/// What the compactions in the log `log` of `store` replaced, read in one
684/// pass over the log. A summary named again, as by an undo that put it
685/// back, keeps what it first replaced. A summary whose entries the log
686/// does not hold is left out.
687///
688/// # Errors
689///
690/// As [`load`](crate::load).
691pub 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/// What a [`Summarizer`] asks the model. Each prompt missing from its serde
722/// form is the default's.
723#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
724#[serde(default, deny_unknown_fields)]
725pub struct SummaryPrompts {
726    /// The summarizer's system prompt.
727    pub system: Cow<'static, str>,
728    /// The request for a first summary, after the conversation.
729    pub initial: Cow<'static, str>,
730    /// The request to fold the conversation into `<previous-summary>`.
731    pub update: Cow<'static, str>,
732    /// The summary's format, after any request.
733    pub format: Cow<'static, str>,
734    /// The request for a summary sent at the end of the conversation
735    /// itself, after the agent's own system prompt and tools, in place of
736    /// `system`, `initial` and `update` ([`Summarizer::instruction`]).
737    pub in_place: Cow<'static, str>,
738    /// The request for notes on the tool outputs a clearing drops, sent as
739    /// `in_place` is and opening with the same words ([`ClearPlan::apply`]).
740    pub notes: Cow<'static, str>,
741}
742
743impl SummaryPrompts {
744    /// A structured checkpoint of an agent's work: goal, constraints,
745    /// progress, decisions, next steps and critical context.
746    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/// The sizes a [`Summarizer`] works within. Each size missing from its
826/// serde form is the default's.
827#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
828#[serde(default, deny_unknown_fields)]
829pub struct SummaryLimits {
830    /// Tokens left free below the model's input limit.
831    pub reserve: u64,
832    /// The longest summary asked for, in tokens.
833    pub summary_tokens: u64,
834    /// Characters of a tool's output or arguments the model sees.
835    pub snippet_chars: usize,
836    /// Characters of conversation sent when the model's window is unknown.
837    pub unknown_window_chars: usize,
838}
839
840impl SummaryLimits {
841    /// 16k tokens reserved, summaries up to 32k tokens, 2,000-character
842    /// snippets and 400k characters for an unknown window.
843    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/// Builds the request for a summary of a conversation's older messages and
864/// reads the summary from the model's answer. The conversation goes as
865/// text in one user message, so the model reads it rather than continues
866/// it.
867#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
868#[serde(default, deny_unknown_fields)]
869pub struct Summarizer {
870    /// What the model is asked.
871    pub prompts: SummaryPrompts,
872    /// Sizes.
873    pub limits: SummaryLimits,
874}
875
876impl Summarizer {
877    /// [`SummaryPrompts::DEFAULT`] within [`SummaryLimits::DEFAULT`].
878    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
890/// Tells the model a summary's output limit of `tokens`, as a reply cut
891/// there is not used ([`Summarizer::summary_text`]).
892fn within(tokens: u64) -> String {
893    format!("\n\nKeep it under {tokens} tokens: a longer answer is cut off and thrown away.")
894}
895
896/// Why a summary cannot be used.
897#[derive(Clone, Debug, PartialEq, Eq)]
898#[non_exhaustive]
899pub enum SummaryError {
900    /// The summary hit the model's output limit, so it is incomplete.
901    Truncated,
902    /// The model called a tool instead of summarizing.
903    CalledTool,
904    /// The model returned no text.
905    Empty,
906    /// The reply failed or was filtered, for this reason.
907    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
923/// Whether `spec` knows what bounds its output: its output limit or its
924/// window. A request to a model that knows neither is sent no output limit,
925/// so its server's default holds; an input limit alone says nothing of the
926/// output.
927pub fn known_limits(spec: &ModelSpec) -> bool {
928    spec.max_output_tokens.is_some() || spec.context_window.is_some()
929}
930
931/// How much of the model's input limit a call after an overflow may
932/// read, as a divisor: half. A bigger one is nearly the refused request
933/// again, slow to answer and close to overflowing itself.
934pub const AFTER_OVERFLOW: u64 = 2;
935
936impl Summarizer {
937    /// The request to `spec` for a summary of `older` for `reason`, merged
938    /// into `previous` when that is not empty. A summary the user asked for
939    /// keeps its focus above all; one after an overflow reads at most
940    /// [`AFTER_OVERFLOW`] of the input limit. The room below the reserve, or
941    /// half the limit when that is more, is split: the summary asks for at
942    /// most half of it, and the older messages fill the rest. A model whose
943    /// output bounds are unknown ([`known_limits`]) is sent no output
944    /// limit, as a turn is not, so its server's default holds.
945    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                // At least half the limit, whatever the reserve leaves.
965                let room = limit.saturating_sub(limits.reserve).max(limit / 2);
966                let most = self.max_tokens(spec).min(room / 2);
967                // Three characters a token, to stay under the window with code.
968                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    /// The longest summary asked of `spec`: the limit's, or the model's
1002    /// output limit when that is lower.
1003    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    /// The message that asks for a summary at the end of the conversation
1010    /// itself, the agent's own request with its system prompt and tools cut
1011    /// before the first message kept, so the provider can read all of it
1012    /// from its prompt cache: [`SummaryPrompts::in_place`], `focus` when it
1013    /// is not empty, the format, and the output limit of `tokens` the
1014    /// request asks for.
1015    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    /// The message that asks, in place, for notes on the tool outputs about
1026    /// to be cleared ([`SummaryPrompts::notes`]), with the output limit of
1027    /// `tokens` the request asks for.
1028    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    /// The summary in a finished answer, or why it cannot be used.
1035    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    /// `messages` as text, one labelled block per part, with long tool
1053    /// outputs and arguments cut.
1054    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
1116/// The last `budget` bytes of `text`, cut at a character, with a note when
1117/// the start is left out.
1118fn 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
1127/// `text` cut to `chars` characters, saying how much was cut.
1128fn 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/// What [`ClearToolOutputs::clear`] took out.
1140#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
1141pub struct Cleared {
1142    /// Tool results cleared.
1143    pub results: usize,
1144    /// Their estimated tokens.
1145    pub tokens: usize,
1146}
1147
1148/// Frees context by clearing the outputs of older tool calls: walking back
1149/// from the end, the outputs within the first `keep_tokens` stay, and every
1150/// older one is replaced by a placeholder. The last message is never
1151/// touched: it is what the model must answer. Error results stay, being
1152/// short and telling the model what went wrong, and so do outputs under
1153/// `keep_under` tokens, which free little. The calls themselves stay, so
1154/// the conversation keeps its shape. Each size missing from its serde form
1155/// is the default's.
1156#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1157#[serde(default, deny_unknown_fields)]
1158pub struct ClearToolOutputs {
1159    /// Tokens of the newest tool output kept.
1160    pub keep_tokens: usize,
1161    /// Tokens under which an output is never cleared.
1162    pub keep_under: usize,
1163}
1164
1165impl Default for ClearToolOutputs {
1166    /// The newest 20k tokens of output kept, and every output under 500.
1167    fn default() -> Self {
1168        Self {
1169            keep_tokens: 20_000,
1170            keep_under: 500,
1171        }
1172    }
1173}
1174
1175impl ClearToolOutputs {
1176    /// What a cleared output says.
1177    pub const PLACEHOLDER: &'static str =
1178        "[output cleared to fit the context window; run the tool again if needed]";
1179
1180    /// Keep the newest `keep_tokens` of tool output, counted by the default
1181    /// [`HeuristicTokenCounter`], and say [`Self::PLACEHOLDER`] instead of
1182    /// the rest but outputs under the default `keep_under`: the serde form
1183    /// that names only `keep_tokens`.
1184    ///
1185    /// ```
1186    /// use rig_memory::ClearToolOutputs;
1187    ///
1188    /// let config: ClearToolOutputs = serde_json::from_str(r#"{"keep_tokens": 8000}"#)?;
1189    /// assert_eq!(ClearToolOutputs::new(8000), config);
1190    /// # Ok::<(), serde_json::Error>(())
1191    /// ```
1192    pub fn new(keep_tokens: usize) -> Self {
1193        Self {
1194            keep_tokens,
1195            ..Self::default()
1196        }
1197    }
1198
1199    /// Clears older tool outputs of `messages` in place.
1200    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    /// Clears older tool outputs of `conversation`, as [`Self::clear`]
1211    /// does, rewriting the entries that change in place by `by`
1212    /// ([`Conversation::edit_each`]), so they keep their ids.
1213    pub fn clear_conversation(&self, conversation: &mut Conversation, by: Author) -> Cleared {
1214        self.plan(conversation).apply(conversation, None, by)
1215    }
1216
1217    /// Which tool outputs of `conversation` [`Self::clear_conversation`]
1218    /// would clear, by message id, so the plan still applies once messages
1219    /// arrive or a copy of the conversation is edited.
1220    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    /// The tool results of `messages` to clear, as the indices of their
1236    /// content items by message, and what clearing them takes out.
1237    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/// The tool outputs a clearing replaces ([`ClearToolOutputs::plan`]), by
1271/// message id.
1272#[derive(Clone, Debug, Default, PartialEq, Eq)]
1273pub struct ClearPlan {
1274    /// What applying it takes out, as planned.
1275    pub cleared: Cleared,
1276    /// The newest message holding an output it clears, after whose outputs
1277    /// notes go; `None` when it clears nothing.
1278    pub through: Option<MessageId>,
1279    targets: BTreeMap<MessageId, Vec<usize>>,
1280}
1281
1282impl ClearPlan {
1283    /// The tool results of `conversation` it clears.
1284    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    /// Replaces the outputs it clears in `conversation` with the
1302    /// placeholder, with `notes`, if any, as a text part after
1303    /// [`through`](Self::through)'s, by one [`Conversation::edit_each`] by
1304    /// `by`. Returns what it planned to take out.
1305    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
1337/// Replaces the tool results at `items` of `message` with the placeholder.
1338fn 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
1351/// Whether `content` is a cleared output.
1352fn is_cleared(content: &[ToolResultContent]) -> bool {
1353    matches!(content, [only] if only.as_text() == Some(ClearToolOutputs::PLACEHOLDER))
1354}
1355
1356#[cfg(test)]
1357mod tests;