4-Mode Context Compaction Engine (Decision 08, REQ-PBT-06).
Supports all 4 compaction modes:
:manual— User or RPC explicitly triggers/compactwith optional custom instructions.:threshold— Synchronous turn-boundary compaction whencurrent_tokens + reserve_tokens >= context_window(reserve_tokens: 16_384,keep_recent_tokens: 20_000).:background— Asynchronous Oban worker (SuperPi.Workers.CompactionWorker) triggered whencurrent_tokens >= background_tokens; summarizes older turns concurrently and appends a non-destructivepi.compactionentry (head_entry_id) without blocking the active stream.:overflow— Auto-recovery compaction when an LLM provider returns a context-window overflow error; compacts with a tighterkeep_recent_tokensbudget and signals immediate retry.
Cut-Point Tool-Pair Invariant (REQ-PBT-06)
find_safe_cut_point/2 walks backwards from the end of visible_entries until keep_recent_tokens
is accumulated, and then advances/adjusts the cut index so that no tool_call assistant entry is ever
separated from its corresponding role: "tool" result entries. Every tool result in the kept tail
is guaranteed to have its originating assistant tool_call also in the kept tail.
Summary
Functions
Evaluates whether :threshold or :background compaction should run based on current token usage.
Returns :none, {:threshold, meta}, or {:background, meta}.
Executes compaction in one of the 4 modes (:manual, :threshold, :background, :overflow).
Estimates token count for an entry (~4 chars per token heuristic).
Computes {compacted_prefix, kept_tail, head_entry_id} for visible_entries given keep_recent_tokens.
Functions
Evaluates whether :threshold or :background compaction should run based on current token usage.
Returns :none, {:threshold, meta}, or {:background, meta}.
@spec compact!(integer(), atom(), keyword()) :: {:ok, :noop} | {:ok, map()} | {:enqueued, Oban.Job.t()}
Executes compaction in one of the 4 modes (:manual, :threshold, :background, :overflow).
- For
:backgroundwithenqueue: true, schedules an asynchronousObanjob on the:compactionqueue. - Otherwise computes the safe cut point (
find_safe_cut_point/2), summarizes the prefix, and appends a durablepi.compactionentry withhead_entry_id: first_kept_id.
Estimates token count for an entry (~4 chars per token heuristic).
Computes {compacted_prefix, kept_tail, head_entry_id} for visible_entries given keep_recent_tokens.
Guarantees the Tool-Pair Cut-Point Invariant (REQ-PBT-06):
kept_tailnever starts on arole == "tool"message entry.- Every
role == "tool"entry inkept_tailhas its precedingrole == "assistant"tool-call entry included inkept_tailas well.