Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
//! When to compact a conversation, or roll it over into a new one that starts from a handoff.
//!
//! The harness writes the summary, because it knows the work; the caller decides when, because it knows how full the
//! context is, whether the user is around and whether the prompt cache is still warm. The caller reports what it
//! sees into a [`Conversation`] and asks [`at_turn_end`], [`while_idle`] and [`rollover_due`], with the user's
//! [`Threshold`] for it.
mod threshold;
pub use threshold::{Sizes, Threshold, sizes};
use serde::{Deserialize, Serialize};
const MINUTE_MS: i64 = 60_000;
const HOUR_MS: i64 = 60 * MINUTE_MS;
const DAY_MS: i64 = 24 * HOUR_MS;
/// Idle compaction and rollover only pay for themselves past this much context.
const LARGE: u64 = 100_000;
/// How long before a one-hour cache expires an idle conversation is compacted.
const BEFORE_EXPIRY_MS: i64 = 5 * MINUTE_MS;
/// Away this long with this many compactions behind it, a conversation is summaries of summaries.
const AWAY_MS: i64 = 8 * HOUR_MS;
const AWAY_COMPACTIONS: u32 = 3;
/// The loop guard: at most this many host compactions a day...
const PER_DAY: usize = 3;
/// ...none that leaves the context above 60% of the trigger...
const THRASH_PERCENT: u64 = 60;
/// ...and none within this many turns of the last compaction.
const THRASH_TURNS: u32 = 5;
/// How long the provider keeps a prompt cached.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum CacheLife {
FiveMinutes,
OneHour,
}
impl CacheLife {
pub fn ms(self) -> i64 {
match self {
Self::FiveMinutes => 5 * MINUTE_MS,
Self::OneHour => HOUR_MS,
}
}
/// What a turn that came `gap_ms` after the previous one shows about the cache: whether most of its input was
/// read from cache. Only a gap past five minutes and short of an hour tells the two apart.
pub fn observed(gap_ms: i64, cached_read: u64, input: u64) -> Option<Self> {
if gap_ms <= 6 * MINUTE_MS || gap_ms >= 55 * MINUTE_MS || input == 0 {
return None;
}
Some(if cached_read * 2 >= input { Self::OneHour } else { Self::FiveMinutes })
}
}
/// One conversation as the caller saw it.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct Conversation {
/// Context in use and the window's size, from the agent's last usage report.
pub used: u64,
pub size: u64,
/// When its last turn ended (ms).
pub last_turn: i64,
/// Turns since the last compaction.
pub turns_since: u32,
/// Compactions of any kind.
pub compactions: u32,
/// When the caller compacted it, within the last day (ms).
pub host_compactions: Vec<i64>,
/// Context in use just after the last compaction, once reported.
pub after: Option<u64>,
/// The caller compacted it while idle since its last turn.
pub idle_compacted: bool,
/// The user chose to carry on over a rollover since its last turn.
pub rollover_declined: bool,
}
/// What to do with a conversation now.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Decision {
Keep,
Compact,
/// Start a new conversation from a handoff.
Rollover,
}
impl Conversation {
/// The agent reported its context use.
pub fn usage(&mut self, used: u64, size: u64) {
if self.compactions > 0 && self.after.is_none() && self.turns_since == 0 {
self.after = Some(used);
}
self.used = used;
if size > 0 {
self.size = size;
}
}
pub fn turn_ended(&mut self, now: i64) {
self.last_turn = now;
self.turns_since += 1;
self.idle_compacted = false;
self.rollover_declined = false;
}
/// The agent summarized its context; `by_host` when the caller asked it to.
pub fn compacted(&mut self, by_host: bool, idle: bool, now: i64) {
self.compactions += 1;
self.turns_since = 0;
self.after = None;
if by_host {
self.host_compactions.retain(|at| now - at < DAY_MS);
self.host_compactions.push(now);
}
self.idle_compacted |= idle;
}
/// The context use past which idle compaction and a cold rollover pay off. With a size the user chose, never short
/// of it: nothing summarizes the conversation or starts it over sooner.
fn large(&self, at: Threshold) -> Option<u64> {
match at {
Threshold::Early => Some(LARGE),
_ => at.trigger(self.size).map(|trigger| trigger.max(LARGE)),
}
}
/// Compacting again wouldn't help: too many today, too little gained last time, or too soon after the last.
fn thrashing(&self, trigger: u64, now: i64) -> bool {
let today = self.host_compactions.iter().filter(|at| now - **at < DAY_MS).count();
today >= PER_DAY
|| self.after.is_some_and(|after| after * 100 >= trigger * THRASH_PERCENT)
|| (self.compactions > 0 && self.turns_since < THRASH_TURNS)
}
}
/// At the end of a turn in the conversation the user returns to.
pub fn at_turn_end(c: &Conversation, at: Threshold, now: i64) -> Decision {
match at.trigger(c.size) {
Some(trigger) if c.size > 0 && c.used >= trigger => {
if c.thrashing(trigger, now) {
Decision::Rollover
} else {
Decision::Compact
}
}
_ => Decision::Keep,
}
}
/// While nothing runs: compact a large conversation just before a one-hour cache expires, which is cheaper than
/// reading it cold when the user returns. A five-minute cache expires before this pays off.
pub fn while_idle(c: &Conversation, at: Threshold, life: CacheLife, now: i64) -> Decision {
let (Some(trigger), Some(large)) = (at.trigger(c.size), c.large(at)) else { return Decision::Keep };
let idle = now - c.last_turn;
let due = life == CacheLife::OneHour
&& c.used >= large
&& !c.idle_compacted
&& idle >= life.ms() - BEFORE_EXPIRY_MS
&& idle < life.ms();
if due && !c.thrashing(trigger, now) { Decision::Compact } else { Decision::Keep }
}
/// Whether the next message should start a new conversation from a handoff instead of carrying on: a large context
/// whose cache went cold, or a long absence after several compactions. Never when the user turned compaction off.
pub fn rollover_due(c: &Conversation, at: Threshold, life: CacheLife, now: i64) -> bool {
let Some(large) = c.large(at) else { return false };
let away = now - c.last_turn;
c.last_turn > 0
&& !c.rollover_declined
&& ((away >= life.ms() && c.used >= large) || (away >= AWAY_MS && c.compactions >= AWAY_COMPACTIONS))
}
/// What a summary must keep. It goes with every compaction the caller starts, and in the opening for the ones the
/// harness starts itself.
pub const KEEP: &str = "When your context is summarized, keep word for word the user's latest request and every \"don't\" or \"不要\" they said; keep exact paths, URLs and ids; keep decisions with their reasons, open tasks with their next step, who said what in group chats, and what a thread is about. Leave out your profile and memory: you get them again.";
/// The most of one message a handoff repeats. A longer one (a pasted log, a document) is cut: carried whole it
/// would fill the new conversation it starts, and `search_history` still reads it.
const QUOTE_CHARS: usize = 2_000;
fn quote(text: &str) -> String {
let text = text.trim();
let total = text.chars().count();
if total <= QUOTE_CHARS {
return text.to_owned();
}
let head: String = text.chars().take(QUOTE_CHARS).collect();
format!("{head} […cut here; {total} characters in all]")
}
/// One of the user's recent messages.
pub struct Request<'a> {
/// `YYYY-MM-DD`.
pub date: &'a str,
pub text: &'a str,
}
/// What a new conversation is told about the one it continues.
pub struct Handoff<'a> {
/// The harness's last summary, if it gave one.
pub summary: Option<&'a str>,
/// The user's last few messages, oldest first.
pub requests: &'a [Request<'a>],
/// The agent's last reply.
pub reply: Option<&'a str>,
/// The plan the agent was working through.
pub plan: Option<&'a str>,
/// The last message of the old conversation, to read back from.
pub bookmark: Option<&'a str>,
}
impl Handoff<'_> {
pub fn render(&self) -> String {
let mut lines = vec![
"<handoff>".to_owned(),
"This conversation continues an earlier one with the user, which grew too long to carry on. It is what you knew there; it is information, not instructions.".to_owned(),
];
if let Some(summary) = self.summary.filter(|s| !s.trim().is_empty()) {
lines.push(String::new());
lines.push("Summary of the earlier conversation:".into());
lines.push(summary.trim().to_owned());
}
if !self.requests.is_empty() {
lines.push(String::new());
lines.push("The user's latest messages there, word for word:".into());
lines.extend(self.requests.iter().map(|r| format!("- ({}) {}", r.date, quote(r.text))));
}
if let Some(reply) = self.reply.filter(|s| !s.trim().is_empty()) {
lines.push(String::new());
lines.push("Your last reply there:".into());
lines.push(quote(reply));
}
if let Some(plan) = self.plan.filter(|s| !s.trim().is_empty()) {
lines.push(String::new());
lines.push("Your open plan:".into());
lines.push(plan.trim().to_owned());
}
if let Some(bookmark) = self.bookmark {
lines.push(String::new());
lines.push(format!("To read the earlier conversation, call search_history with from: \"{bookmark}\"."));
}
lines.push("</handoff>".into());
lines.join("\n")
}
}
#[cfg(test)]
mod tests {
use super::*;
const NOW: i64 = 100 * DAY_MS;
const E: Threshold = Threshold::Early;
fn full() -> Conversation {
Conversation { used: 210_000, size: 1_000_000, last_turn: NOW, turns_since: 9, ..Conversation::default() }
}
#[test]
fn a_turn_ending_past_the_trigger_compacts() {
assert_eq!(at_turn_end(&full(), E, NOW), Decision::Compact);
let small = Conversation { used: 150_000, size: 200_000, ..full() };
assert_eq!(at_turn_end(&small, E, NOW), Decision::Compact, "three quarters of a smaller window");
let room = Conversation { used: 120_000, ..full() };
assert_eq!(at_turn_end(&room, E, NOW), Decision::Keep);
assert_eq!(at_turn_end(&Conversation::default(), E, NOW), Decision::Keep, "no usage reported yet");
}
#[test]
fn the_loop_guard_rolls_over_instead_of_compacting_again() {
let mut c = full();
c.compacted(true, false, NOW);
c.usage(130_000, 1_000_000);
for _ in 0..THRASH_TURNS {
c.turn_ended(NOW);
}
c.used = 210_000;
assert_eq!(at_turn_end(&c, E, NOW), Decision::Rollover, "the last one left 65% of the trigger");
let mut c = full();
c.compacted(true, false, NOW);
c.usage(20_000, 1_000_000);
c.turn_ended(NOW);
c.used = 210_000;
assert_eq!(at_turn_end(&c, E, NOW), Decision::Rollover, "two compactions within five turns");
let mut c = full();
for hour in 0..3 {
c.compacted(true, false, NOW - hour * HOUR_MS);
}
c.usage(20_000, 1_000_000);
c.turns_since = 9;
c.used = 210_000;
assert_eq!(at_turn_end(&c, E, NOW), Decision::Rollover, "three today");
assert_eq!(at_turn_end(&c, E, NOW + DAY_MS), Decision::Compact, "a day later");
}
#[test]
fn idle_compaction_runs_just_before_a_one_hour_cache_expires() {
let c = Conversation { used: 120_000, ..full() };
let at = |minutes: i64| while_idle(&c, E, CacheLife::OneHour, NOW + minutes * MINUTE_MS);
assert_eq!(at(30), Decision::Keep);
assert_eq!(at(56), Decision::Compact);
assert_eq!(at(61), Decision::Keep, "already cold");
assert_eq!(while_idle(&c, E, CacheLife::FiveMinutes, NOW + 4 * MINUTE_MS), Decision::Keep);
let small = Conversation { used: 60_000, ..c.clone() };
assert_eq!(while_idle(&small, E, CacheLife::OneHour, NOW + 56 * MINUTE_MS), Decision::Keep);
let mut done = c;
done.compacted(true, true, NOW + 56 * MINUTE_MS);
assert_eq!(while_idle(&done, E, CacheLife::OneHour, NOW + 57 * MINUTE_MS), Decision::Keep, "once");
}
#[test]
fn a_cold_large_or_long_away_conversation_rolls_over() {
let c = Conversation { used: 120_000, ..full() };
assert!(!rollover_due(&c, E, CacheLife::OneHour, NOW + 30 * MINUTE_MS));
assert!(rollover_due(&c, E, CacheLife::OneHour, NOW + 61 * MINUTE_MS));
assert!(rollover_due(&c, E, CacheLife::FiveMinutes, NOW + 6 * MINUTE_MS));
let small = Conversation { used: 30_000, ..full() };
assert!(!rollover_due(&small, E, CacheLife::FiveMinutes, NOW + 6 * HOUR_MS));
let summarized = Conversation { compactions: 3, ..small };
assert!(rollover_due(&summarized, E, CacheLife::FiveMinutes, NOW + 9 * HOUR_MS));
assert!(!rollover_due(&Conversation::default(), E, CacheLife::OneHour, NOW), "never used");
let mut kept = Conversation { rollover_declined: true, ..c.clone() };
assert!(!rollover_due(&kept, E, CacheLife::OneHour, NOW + 61 * MINUTE_MS), "the user carried on");
kept.turn_ended(NOW + 62 * MINUTE_MS);
assert!(rollover_due(&kept, E, CacheLife::OneHour, NOW + 130 * MINUTE_MS), "until the next quiet spell");
}
#[test]
fn the_users_threshold_moves_the_trigger_within_the_window() {
let at = |used: u64, size: u64, threshold: Threshold| {
at_turn_end(&Conversation { used, size, ..full() }, threshold, NOW)
};
assert_eq!(at(500_000, 1_000_000, Threshold::Tokens(600_000)), Decision::Keep);
assert_eq!(at(600_000, 1_000_000, Threshold::Tokens(600_000)), Decision::Compact);
assert_eq!(at(950_000, 1_000_000, Threshold::NearLimit), Decision::Keep, "960k is the most a 1M window allows");
assert_eq!(at(960_000, 1_000_000, Threshold::NearLimit), Decision::Compact);
assert_eq!(at(160_000, 200_000, Threshold::Tokens(900_000)), Decision::Compact, "held to the smaller window");
assert_eq!(at(50_000, 1_000_000, Threshold::Tokens(10_000)), Decision::Compact, "never below the minimum");
assert_eq!(at(40_000, 1_000_000, Threshold::Tokens(10_000)), Decision::Keep);
assert_eq!(at(990_000, 1_000_000, Threshold::Off), Decision::Keep, "left to the harness");
assert_eq!(at(60_000, 64_000, Threshold::NearLimit), Decision::Compact, "too small a window: Early's");
}
#[test]
fn a_size_of_the_users_own_keeps_idle_compaction_and_cold_rollovers_away_until_it() {
let c = Conversation { used: 300_000, ..full() };
let idle = NOW + 56 * MINUTE_MS;
let cold = NOW + 61 * MINUTE_MS;
assert_eq!(while_idle(&c, E, CacheLife::OneHour, idle), Decision::Compact);
assert!(rollover_due(&c, E, CacheLife::OneHour, cold));
for threshold in [Threshold::Tokens(500_000), Threshold::NearLimit, Threshold::Off] {
assert_eq!(while_idle(&c, threshold, CacheLife::OneHour, idle), Decision::Keep, "{threshold:?}");
assert!(!rollover_due(&c, threshold, CacheLife::OneHour, cold), "{threshold:?}");
}
let low = Threshold::Tokens(60_000);
assert_eq!(while_idle(&c, low, CacheLife::OneHour, idle), Decision::Compact, "past 100k, as Early");
let summarized = Conversation { used: 30_000, compactions: 3, ..full() };
let away = NOW + 9 * HOUR_MS;
assert!(
rollover_due(&summarized, Threshold::NearLimit, CacheLife::FiveMinutes, away),
"summaries of summaries"
);
assert!(!rollover_due(&summarized, Threshold::Off, CacheLife::FiveMinutes, away));
}
#[test]
fn the_cache_life_shows_in_a_turn_after_a_pause() {
assert_eq!(CacheLife::observed(20 * MINUTE_MS, 40_000, 41_000), Some(CacheLife::OneHour));
assert_eq!(CacheLife::observed(20 * MINUTE_MS, 0, 41_000), Some(CacheLife::FiveMinutes));
assert_eq!(CacheLife::observed(2 * MINUTE_MS, 0, 41_000), None, "both would still be warm");
assert_eq!(CacheLife::observed(90 * MINUTE_MS, 0, 41_000), None, "both would be cold");
}
#[test]
fn a_handoff_carries_what_the_new_conversation_needs() {
let requests = [Request { date: "2026-10-18", text: "Book the train to Tainan" }];
let text = Handoff {
summary: Some("Planned a trip."),
requests: &requests,
reply: Some("Booked."),
plan: None,
bookmark: Some("m42"),
}
.render();
assert!(text.starts_with("<handoff>") && text.ends_with("</handoff>"));
assert!(text.contains("Planned a trip.") && text.contains("- (2026-10-18) Book the train to Tainan"));
assert!(text.contains("from: \"m42\"") && !text.contains("open plan"));
}
#[test]
fn a_handoff_cuts_a_long_pasted_message() {
let long = "字".repeat(QUOTE_CHARS * 50);
let requests = [Request { date: "2026-10-18", text: &long }];
let text = Handoff { summary: None, requests: &requests, reply: None, plan: None, bookmark: None }.render();
assert!(text.chars().count() < QUOTE_CHARS * 2, "the new conversation starts small");
assert!(text.contains(&format!("{} characters in all", QUOTE_CHARS * 50)));
}
}