AutoCompactor class final

Compact helper that owns the multi-pass + retry + smol→main logic. Hosts register a single AutoCompactor.run call after each run; the helper handles everything else.

Constructors

AutoCompactor({required Session session, required AgentState state, required int window, required CompactionSettings settings, required SummarizeFn summary, required SummarizeFn mainSummary, required Model? smolModel, required AutoCompactorHooks hooks, Future<void> memoryExtractionHook(String summarizedText)?, CompactionPrompts prompts = defaultCompactionPrompts, List<Skill> operativeSkills = const [], int maxPasses = 8, int maxAttempts = 3, Duration baseBackoff = const Duration(seconds: 1), bool force = false, Duration attemptBudget = const Duration(seconds: 300), Duration totalBudget = const Duration(minutes: 15), CancelToken? runToken})
const

Properties

attemptBudget → Duration
Wall-clock budget for ONE summarization attempt. A provider endpoint that accepts the request and never answers (no bytes, no error, no done) would otherwise pend stream.result forever and wedge the turn on the compaction spinner for as long as the user is willing to watch it — the provider-level connect/idle watchdogs cover clean hangs, but not dribbling keep-alives or a lost completion. When the budget fires the attempt fails with a TimeoutException (not transient — no retry spin), the pass falls to the next summarizer / the local trim, and the turn goes on. 300 s (gh-740 M1, raised from 90 s): a summarizer writes a bounded summary, and "Compacting context…" must never read as a hang (the 0.1.240 default was 10 minutes per attempt — up to 20 minutes of silent spinner when both summarizers dribbled).
final
baseBackoff → Duration
First backoff sleep between same-pass attempts (multiplied by attempt number): 1s, 2s.
final
force → bool
When true, skip the shouldCompact gate and run the compactor unconditionally. Set by manual /compact (the user asked, so we honour the request even when the auto-trigger threshold isn't crossed).
final
hashCode → int
The hash code for this object.
no setterinherited
hooks → AutoCompactorHooks
Progress / error sink.
final
mainSummary → SummarizeFn
Fallback summarizer (typically the main model).
final
maxAttempts → int
Retry attempts per pass before falling back / failing.
final
maxPasses → int
Upper bound on pass count per run. Picked so a 1M→200k session compacts down in 2-3 passes; deep enough for the worst case but bounded so a model that just won't summarize doesn't loop forever.
final
memoryExtractionHook → Future<void> Function(String summarizedText)?
Optional Phase 2 hook: forwarded to every CompactionManager so durable-fact extraction (CLI long-term memory, future Flutter equivalents) runs once per pass with the summarized span.
final
operativeSkills → List<Skill>
gh-1409: the skills known to the session — their operative: directives ride every summarization prompt as the verbatim-preserve pinned block (AC3) and are protected from the sanitizer (AC4). Empty (default) → prompts byte-identical to the pre-pin pipeline (F4 compat guard).
final
pinnedOperative → PinnedOperativePayload?
The pinned-operative payload derived from operativeSkills (null when the skills declare no operative lines).
no setter
prompts → CompactionPrompts
Summarization prompts forwarded to the CompactionManager so a host's prompts: yaml override reaches the same summary callback that streamFunctionSummarizer already uses.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
runToken → CancelToken?
The owning run's cancellation token (issue #1085 M1/M3), when the compaction runs inside a run (mid-run over-window relief). When it cancels — a USER abort, never the suspended watchdog — every in-flight summarization attempt is cancelled with it, so an abort kills the compaction promptly instead of waiting out the 15-30 min relief. null = not linked (standalone compaction).
final
session → Session
The session to compact and to read the projected transcript from.
final
settings → CompactionSettings
Compaction thresholds (reserveTokens, keepRecentTokens, triggerRatio).
final
smolModel → Model?
The model passed to summary (i.e. the smol Model spec).
final
state → AgentState
Agent state whose AgentState.messages is replaced with the compacted transcript on success.
final
summary → SummarizeFn
The summarizer used at the top of the pass chain (typically the smol role). May equal mainSummary for hosts without a separate smol (the helper skips the fallback in that case).
final
totalBudget → Duration
Wall-clock budget for the WHOLE compactor run across all passes, attempts and summarizers. Checked before each attempt: once the elapsed time is over the budget, remaining attempts are skipped and the run falls to the local trim. Bounds pathological combinations (maxPasses × retries × smol+main) that would otherwise keep the UI on the compaction spinner for tens of minutes. Defaults to attemptBudget × maxAttempts (15 min for the 300s gh-740 M1 attempt budget) — the total must never be smaller than one attempt, or a single full timeout would exhaust it and silently collapse the retry ladder to a single attempt.
final
window → int
The model's context window (in tokens). Used by shouldCompact.
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
run() → Future<bool>
Drives the multi-pass loop. Returns true on success (the transcript fits in window), false when the loop gave up or every summarizer failed.
toString() → String
A string representation of this object.
inherited

Operators

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