agent_works/compression/
mod.rs

1//! Context compression for long agent conversations.
2//!
3//! Long tool-heavy conversations balloon the message list sent to the LLM on
4//! every turn, slowing each call down and eventually exceeding the context
5//! window. This module provides a [`CompressionMiddleware`] that observes the
6//! per-LLM-call message list via
7//! [`Middleware::on_pre_llm`](agent_base::Middleware::on_pre_llm) and, once
8//! estimated tokens exceed a configurable threshold, summarises the *earlier*
9//! portion into a compact handoff message.
10//!
11//! # Strategy
12//!
13//! The compressor uses a **hybrid retention** approach:
14//!
15//! 1. **System prompt** — always preserved verbatim.
16//! 2. **Recent N messages** — kept verbatim (including tool results), placed at
17//!    the end to leverage the model's recency bias.
18//! 3. **Older history** — condensed into a single handoff summary by an LLM
19//!    call, cached via a stable-prefix hash to avoid redundant re-summarisation.
20//!
21//! This balances information preservation (recent tool data stays intact) with
22//! token efficiency (older context is compressed).
23//!
24//! # Architecture
25//!
26//! ```text
27//! session.chat_messages().to_vec()          ← full history clone
28//!     ↓
29//! CompressionMiddleware::on_pre_llm()       ← gate → split → cache check → summarise → assemble
30//!     ↓
31//! [system prompt] + [summary] + [recent N]  ← compressed copy for this LLM call only
32//! ```
33//!
34//! The session's stored history is **never** modified by automatic compression;
35//! only the per-call message copy is trimmed. The `/compact` CLI command can
36//! optionally write the compressed form back to the session.
37//!
38//! # Feature gate
39//!
40//! This module is behind the `compression` Cargo feature.
41
42mod compactor;
43mod config;
44pub mod events;
45mod filter;
46mod middleware;
47mod policy;
48mod summarizer;
49
50pub use compactor::{ContextCompactor, safe_cut_index, serialize_block, truncate_str};
51pub use config::CompressionConfig;
52pub use events::{CompressionEvent, CompressionTrigger};
53pub use filter::{SUMMARY_PREFIX, is_summary_message, split_system_prompt};
54pub use middleware::CompressionMiddleware;
55pub use policy::{
56    AutoCompressionPolicy, CompressionPolicy, RateLimitPolicy, UserConfirmationPolicy,
57};
58pub use summarizer::{language_instruction, summarize, truncate_summary_output};
agent_works/compression/mod.rs

agent_works/compression/
mod.rs
