CompactionService class

Context compaction service.

Manages the three-phase compaction pipeline:

  1. Microcompaction — lightweight clearing of old tool results to free tokens without an API call.
  2. Auto-compact trigger — checks whether token usage has crossed the threshold requiring full compaction.
  3. Full compaction — summarizes the conversation via an LLM call and replaces messages with the summary.

Supports both full and partial compaction, system prompt preservation, and prompt-too-long retry logic.

Constructors

CompactionService({required ApiProvider provider})
Create a CompactionService backed by the given provider.

Properties

hashCode → int
The hash code for this object.
no setterinherited
provider → ApiProvider
The API provider used for summary generation.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

autoCompactIfNeeded({required List<Message> messages, required String systemPrompt, int contextWindow = 200000}) → Future<CompactionResult?>
Auto-compact if needed. Returns null when no compaction was needed.
compactConversation({required List<Message> messages, required String systemPrompt, int contextWindow = 200000, bool isAutoCompact = false, String? customInstructions, bool suppressFollowUpQuestions = false, OnCompactProgress? onProgress}) → Future<CompactionResult>
Run full conversation compaction via summarization.
estimateTokenCount(List<Message> messages) → int
Estimate token count for a list of messages.
microcompact(List<Message> messages, {int keepRecent = 5}) → List<Message>
Lightweight pre-API clearing of old tool results.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
partialCompactConversation({required List<Message> allMessages, required int pivotIndex, required String systemPrompt, String? userFeedback, PartialCompactDirection direction = PartialCompactDirection.from, OnCompactProgress? onProgress}) → Future<CompactionResult>
Partial compaction around a selected message index.
shouldAutoCompact(List<Message> messages, {int contextWindow = 200000}) → bool
Returns true when messages exceed the auto-compact threshold.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

truncateHeadForPtlRetry(List<Message> messages, int? tokenGap) → List<Message>?
Drops the oldest API-round groups from messages until tokenGap is covered. Returns null when nothing can be dropped without leaving an empty summarize set.