Files
luxe/crates/luxe-core/src/compaction.rs
Evan Whittaker d2129a886f Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md
- luxe remote puts the sessions on your computer in reach of your own phone or tablet over
  Tailscale: write, steer, answer prompts, send photos, browse files, diffs and GitHub, with a
  paired device and your own Tailscale login.
- luxe join lets another program on the same machine join a running session over the RPC protocol.
- An AGENTS.md in a subfolder reaches the model the first time it works there.
- Long sessions stay fast: no stall before each model call, lighter memory, cheaper drawing.
- A session is open in one Luxe at a time, web_search shares results across its phrasings, and a
  grep glob starting with ! excludes.

The CHANGELOG has the full list.
2026-10-20 02:40:13 -05:00

155 lines
6.2 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Compaction — keep long conversations inside the model's context window.
//!
//! Implements threshold-based auto-compaction and manual `/compact` command.
//! Walks back from the newest message, accumulating token estimates until
//! `keep_recent_tokens` is reached, then summarizes everything older than
//! that cut-point into a structured summary.
use crate::provider::ModelInfo;
use crate::session::{Entry, EntryId, SessionError};
use std::collections::HashSet;
mod budget;
mod context;
mod planner;
mod prune;
mod summary;
pub use budget::{
clamp_max_tokens_to_context, compaction_threshold, context_fullness_percent, context_tokens,
estimate_calibration, estimate_message_tokens, estimate_prefix_tokens, estimate_tokens,
last_observed_context_tokens, prompt_tokens, usable_context_window, ContextBudget,
CONTEXT_SAFETY_TOKENS,
};
pub(crate) use budget::{summary_max_tokens, IMAGE_TOKEN_ESTIMATE};
pub use context::{context_entries, context_messages};
pub use planner::find_compaction_point;
pub use prune::{prune_tool_outputs, ContextPressure};
pub(crate) use summary::SUMMARIZER_PROMPT;
pub use summary::{format_structured_summary, serialize_for_summary, summary_carries_content};
/// Settings controlling compaction behavior.
#[derive(Debug, Clone)]
pub struct CompactionSettings {
/// Whether compaction is enabled.
pub enabled: bool,
/// Cap on the output slice reserved below the context window. The real reserve is
/// `min(max_tokens, reserve_tokens)` — a reply/summary rarely needs the model's full max
/// output, so we never surrender a whole 128K-output budget (Claude Code and OpenCode cap the
/// same way, ~20K).
pub reserve_tokens: u32,
/// Tokens of recent context to keep verbatim.
pub keep_recent_tokens: u32,
/// Fraction of the usable window at which auto-compaction fires (0.0–1.0). A fraction, not a
/// fixed buffer, so the trigger scales sanely across 128K…1M windows.
pub compact_at_fraction: f64,
/// Tool output within the most-recent this-many tokens stays verbatim; older tool results are
/// pruned to a placeholder. Mirrors OpenCode's 40K protect window.
pub prune_protect_tokens: u32,
/// The quantum the elision boundary moves in, and the smallest gain worth moving it for.
/// Eliding rewrites the middle of the transcript, so it happens in deliberate steps rather
/// than continuously — see [`prune_tool_outputs`].
pub prune_min_tokens: u32,
/// Fraction of the usable window at or above which stale tool output is elided at all.
/// Below it the window is not scarce and eliding costs far more than it saves.
pub prune_at_fraction: f64,
/// The model that writes summaries, with the window and price the front-end resolved for it;
/// `None` uses the active model.
pub summarizer: Option<ModelInfo>,
}
impl Default for CompactionSettings {
fn default() -> Self {
Self {
enabled: true,
reserve_tokens: 20_000,
keep_recent_tokens: 20_000,
compact_at_fraction: 0.9,
prune_protect_tokens: 40_000,
prune_min_tokens: 20_000,
prune_at_fraction: 0.8,
summarizer: None,
}
}
}
/// A plan for what to compact.
#[derive(Debug)]
pub struct CompactionPlan {
/// Messages to summarize (everything before the cut-point).
pub messages_to_summarize: Vec<Entry>,
/// Non-empty only on split-turn: a turn prefix that exceeds keep_recent.
pub turn_prefix: Vec<Entry>,
/// The first entry to keep verbatim.
pub first_kept: EntryId,
/// Previous summary text, if any (for cumulative file tracking).
pub previous_summary: Option<String>,
/// Files this session has read or changed, carried across compactions.
pub file_ops: HashSet<String>,
/// Estimated tokens before compaction.
pub tokens_before: u64,
}
/// Errors that can occur during compaction.
#[derive(Debug, thiserror::Error)]
pub enum CompactionError {
#[error("session error: {0}")]
Session(SessionError),
#[error("provider error: {0}")]
Provider(String),
#[error("compaction cancelled")]
Cancelled,
}
crate::error_cause::from_cause!(CompactionError {
SessionError => Session,
});
/// After this many consecutive summarization failures, auto-compaction gives up for the rest of
/// the session instead of retrying a failing provider call every turn (Claude Code trips the same
/// kind of breaker after 3). A success resets the count.
pub const MAX_COMPACTION_FAILURES: u32 = 3;
/// Whether the auto-compaction circuit breaker has tripped for `consecutive_failures`.
pub fn compaction_circuit_open(consecutive_failures: u32) -> bool {
consecutive_failures >= MAX_COMPACTION_FAILURES
}
/// The most of a conversation a compaction may leave behind and still count as having worked.
///
/// A summary that frees a twentieth of the transcript has spent a provider call to buy nothing, and
/// the occupancy that triggered it is still over the line, so the next check — every tool
/// iteration — fires too. It happens on small windows, where the protected tail (capped at half the
/// usable window) is most of what there was to cut.
const COMPACTION_MUST_FREE: f64 = 0.2;
/// Whether a compaction freed enough of the transcript to have been worth making.
///
/// Both figures are the same char/4 estimate over the same shape, so the ratio is meaningful even
/// though neither number is exact.
pub fn compaction_was_effective(before: u64, after: u64) -> bool {
if before == 0 {
return true;
}
(before.saturating_sub(after) as f64 / before as f64) >= COMPACTION_MUST_FREE
}
/// Pick the model that writes the compaction summary: the configured `summarizer` when set, else
/// the caller's active model.
pub fn summarizer_model(summarizer: Option<&ModelInfo>, active: &ModelInfo) -> ModelInfo {
summarizer.unwrap_or(active).clone()
}
/// Why compaction is being considered.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CompactionTrigger {
/// Occupancy crossed the configured fraction of the usable window.
Threshold,
/// The user asked for it, so the threshold is not the question — only whether there is
/// anything older than the recent tail worth summarizing.
Manual,
}
#[cfg(test)]
mod tests;