Skip to content

The agent that grows with you

fix(agent): bound prepared-compaction staleness, size band from trigger, discard on rebind

Hugo Alves Pereira9212396c4e63
diff --git a/agent/context_compressor.py b/agent/context_compressor.py
index 4c4170bb151..514de85ec71 100644
--- a/agent/context_compressor.py
+++ b/agent/context_compressor.py
@@ -2326,6 +2326,8 @@ class ContextCompressor(
def bind_session_state(self, session_db: Any = None, session_id: str = "") -> None:
"""Bind the current session row so durable cooldowns can round-trip."""
+ if self.prepared_compaction is not None and (session_id or "") != self._session_id:
+ self.prepared_compaction.discard("session rebind")
self._session_db = session_db
self._session_id = session_id or ""
self._summary_failure_cooldown_until = 0.0
@@ -5515,10 +5517,12 @@ Write only the summary body. Do not include any preamble or prefix."""
)
return canonical_messages
# Opt-in: an automatic compaction may splice a summary prepared in the background at ITS
- # boundary; newer messages stay outside the summary, in the tail (agent/prepared_compaction.py).
+ # boundary; newer messages (at most one more tail budget) stay outside the summary, in the
+ # tail (agent/prepared_compaction.py).
prepared = self.prepared_compaction and self.prepared_compaction.take(
messages, self._session_id, compress_start, compress_end,
eligible=not (force or focus_topic or bypass_cooldown or memory_context.strip()),
+ max_gap_tokens=self.tail_token_budget,
)
if prepared:
compress_end = prepared.compress_end
diff --git a/agent/prepared_compaction.py b/agent/prepared_compaction.py
index e199b7e354e..3d80ac1224e 100644
--- a/agent/prepared_compaction.py
+++ b/agent/prepared_compaction.py
@@ -1,27 +1,29 @@
"""Opt-in prepared compaction (``compression.prepare_ahead``, default off).
When the provider-reported prompt size comes within ``PREPARE_BAND_RATIO`` of
-the context window below the compaction trigger, the turn loop (before a tool
-batch runs, and at turn end) starts a background pass. The pass plans the same
-window ``ContextCompressor.compress`` would plan and runs the existing
-summariser on a copy of the compressor and of that window's messages. The
-live transcript and compressor are untouched, so the prompt cache is too.
+the compaction trigger, the turn loop (before a tool batch runs, and at turn
+end) starts a background pass. The pass plans the same window
+``ContextCompressor.compress`` would plan and runs the existing summariser on a
+copy of the compressor and of that window's messages. The live transcript and
+compressor are untouched, so the prompt cache is too.
At the next automatic threshold compaction ``compress`` takes the completed
candidate if it still fits: same head boundary, a boundary no later than the
-current tail cut, and an unchanged transcript up to that boundary. On a hit the
+current tail cut, an unchanged transcript up to that boundary, and at most the
+tail token budget between that boundary and the current cut. On a hit the
candidate's summary replaces ``messages[start:candidate_end]``; everything
after the candidate boundary stays outside the summary, as tail, including
messages a fresh plan would have summarised (existing tail handling, such as
-lean-mode tool-result stubs, still applies). On a miss, or when the pass has not finished,
-compaction runs inline exactly as without the flag. A running pass is never
-waited on (the wait would sit inside the host's compression idle timeout) and
-loses the right to publish once compaction runs.
+lean-mode tool-result stubs, still applies). On a miss, or when the pass has
+not finished, compaction runs inline exactly as without the flag. A running
+pass is never waited on (the wait would sit inside the host's compression idle
+timeout) and loses the right to publish once compaction runs.
-State is per compressor and in memory only; every session boundary discards
-it. Manual, focus, overflow-recovery and memory-provider-context compactions
-always summarise fresh. A failed pass backs off further passes but never
-touches the live compressor's cooldown or failure state.
+State is per compressor and in memory only; every session boundary (reset,
+end, or a rebind to another session id) discards it. Manual, focus,
+overflow-recovery and memory-provider-context compactions always summarise
+fresh. A failed pass backs off further passes but never touches the live
+compressor's cooldown or failure state.
The fingerprint ignores what the no-LLM prune rewrites (tool result bodies,
tool call arguments, image parts), so a prune between pass and splice does not
@@ -40,7 +42,7 @@ from typing import Any, Dict, List, Optional
logger = logging.getLogger(__name__)
# Start passes once the real prompt count is within this fraction of the
-# context window below the compaction trigger.
+# compaction trigger (a band below ``threshold_tokens``).
PREPARE_BAND_RATIO = 0.12
# A completed candidate that still fits is only extended once this many rough
# tokens sit between its boundary and the current cut; until then it keeps
@@ -147,9 +149,11 @@ class PreparedCompaction:
)
def take(
- self, messages: List[Dict[str, Any]], session_id: str, start: int, end: int, *, eligible: bool,
+ self, messages: List[Dict[str, Any]], session_id: str, start: int, end: int, *,
+ eligible: bool, max_gap_tokens: int,
) -> Optional[PreparedSummary]:
"""The completed candidate when it fits ``compress()``'s planned window, else None.
+ A candidate whose boundary trails the cut by more than ``max_gap_tokens`` is stale.
Either way the state is cleared: this compaction consumes or supersedes it."""
with self._lock:
entry, running = self._entry, self._pending is not None
@@ -160,6 +164,12 @@ class PreparedCompaction:
reason = "pass still running" if running else "no candidate"
else:
reason = _mismatch(entry, messages, session_id, start, end)
+ if reason is None:
+ from agent.model_metadata import estimate_messages_tokens_rough
+
+ gap = estimate_messages_tokens_rough(messages[entry.compress_end:end])
+ if gap > max_gap_tokens:
+ reason = f"stale candidate (~{gap} tokens past its boundary, budget {max_gap_tokens})"
if reason is not None:
if entry is not None or running:
logger.info("prepared compaction: splice miss reason=%s", reason)
@@ -181,7 +191,7 @@ class PreparedCompaction:
if compressor.awaiting_real_usage_after_compression:
return True
tokens = compressor.last_prompt_tokens
- band_floor = compressor.threshold_tokens - int(compressor.context_length * PREPARE_BAND_RATIO)
+ band_floor = int(compressor.threshold_tokens * (1 - PREPARE_BAND_RATIO))
if tokens <= 0 or compressor.threshold_tokens <= 0 or tokens < band_floor:
return True
now = time.monotonic()
diff --git a/tests/agent/test_prepared_compaction.py b/tests/agent/test_prepared_compaction.py
index ab94c2fd5d8..0da447bf20b 100644
--- a/tests/agent/test_prepared_compaction.py
+++ b/tests/agent/test_prepared_compaction.py
@@ -5,9 +5,11 @@ Behaviour contracts, with the summariser stubbed at its model boundary:
* flag off (the default) leaves the whole compression path as it was: no state, no pass, inline summary;
* a pass never changes the live transcript or compressor, and runs under the caller's profile scope;
* append-only growth keeps a candidate, which splices at its own boundary with newer messages kept as tail;
-* a rewritten prefix, a moved head or another session's transcript never splices;
+* a rewritten prefix, a moved head, another session's transcript or more than a tail budget of growth past
+ the candidate never splices;
* a completed candidate splices while an extension pass runs; a pass that has not finished is never
- waited on, and a pass overtaken by compaction or a session boundary cannot publish;
+ waited on, and a pass overtaken by compaction or a session boundary cannot publish (a same-session
+ rebind keeps the candidate);
* manual, focus, overflow-recovery and memory-context compactions summarise fresh;
* the no-LLM prune and blank-echo drop between pass and splice do not invalidate the candidate.
"""
@@ -23,6 +25,7 @@ import pytest
from agent import prepared_compaction as pc
from agent.context_compressor import COMPRESSED_SUMMARY_METADATA_KEY, ContextCompressor
+from agent.model_metadata import estimate_messages_tokens_rough
from agent.prepared_compaction import PreparedCompaction
@@ -146,7 +149,10 @@ def test_pass_leaves_live_transcript_and_compressor_untouched():
@pytest.mark.parametrize("setup", [
- lambda a, cc: setattr(cc, "last_prompt_tokens", 20000 - int(40960 * pc.PREPARE_BAND_RATIO) - 1),
+ lambda a, cc: setattr(cc, "last_prompt_tokens", int(20000 * (1 - pc.PREPARE_BAND_RATIO)) - 1),
+ # A small absolute trigger on a large window: the band is sized from the trigger, not the window.
+ lambda a, cc: (setattr(cc, "context_length", 200_000), setattr(cc, "threshold_tokens", 20000),
+ setattr(cc, "last_prompt_tokens", 1000)),
lambda a, cc: setattr(cc, "awaiting_real_usage_after_compression", True),
lambda a, cc: setattr(a, "compression_enabled", False),
lambda a, cc: setattr(a, "_persist_disabled", True), # background-review fork
@@ -154,11 +160,13 @@ def test_pass_leaves_live_transcript_and_compressor_untouched():
lambda a, cc: setattr(a, "codex_responses_native_compaction", True),
lambda a, cc: setattr(cc, "_micro_compact_enabled", True),
lambda a, cc: setattr(cc, "_summary_failure_cooldown_until", time.monotonic() + 60),
-], ids=["below-band", "awaiting-usage", "disabled", "fork", "app-server", "native", "micro", "cooldown"])
+], ids=["below-band", "small-trigger-large-window", "awaiting-usage", "disabled", "fork", "app-server", "native",
+ "micro", "cooldown"])
def test_gates_start_no_pass(setup):
cc = _compressor()
agent = _agent(cc)
setup(agent, cc)
+ assert cc.threshold_tokens == 20000
assert pc.maybe_prepare(agent, _messages(30), origin="test") is None
assert cc.calls == []
@@ -200,6 +208,21 @@ def test_append_only_growth_splices_at_the_candidate_boundary_keeping_newer_mess
assert cc.prepared_compaction._entry is None
+def test_growth_past_the_candidate_beyond_the_tail_budget_summarises_inline():
+ cc = _compressor()
+ msgs = _messages(30)
+ entry = _prepare(cc, msgs)
+ later = _grow(msgs, 24)
+ _, _, start, end = cc._plan_compaction_window(later)
+ assert start == entry.compress_start and end > entry.compress_end
+ assert estimate_messages_tokens_rough(later[entry.compress_end:end]) > cc.tail_token_budget
+
+ compressed = cc.compress(later, current_tokens=cc.threshold_tokens + 1)
+
+ assert [c["worker"] for c in cc.calls] == [True, False], "stale candidate: inline summary expected"
+ assert "Summary v2" in _summary_row(compressed)["content"]
+
+
@pytest.mark.parametrize("change", ["middle rewritten", "head moved", "other session"])
def test_changed_prefix_never_splices(change):
cc = _compressor()
@@ -277,9 +300,13 @@ def test_fingerprint_survives_a_session_db_round_trip(tmp_path):
def test_completed_candidate_splices_while_an_extension_pass_runs():
cc = _compressor()
- msgs = _messages(30)
+ cc.tail_token_budget = 12_000 # room for a gap that starts an extension yet still splices
+ msgs = _messages(80)
first = _prepare(cc, msgs)
- grown = _grow(msgs, 14, size=2600) # clears MIN_EXTENSION_DELTA_TOKENS
+ grown = _grow(msgs, 14, size=2600)
+ _, _, _, end = cc._plan_compaction_window(grown)
+ gap = estimate_messages_tokens_rough(grown[first.compress_end:end])
+ assert pc.MIN_EXTENSION_DELTA_TOKENS <= gap <= cc.tail_token_budget
cc.gate = threading.Event()
running = pc.maybe_prepare(_agent(cc), grown, origin="test")
assert running is not None
@@ -312,7 +339,7 @@ def test_unfinished_pass_is_not_waited_on_and_cannot_publish_later():
assert cc.prepared_compaction._entry is None
[email protected]("boundary", ["reset", "end"])
[email protected]("boundary", ["reset", "end", "rebind"])
def test_session_boundary_discards_candidate_and_running_pass(boundary):
cc = _compressor()
msgs = _messages(30)
@@ -322,13 +349,25 @@ def test_session_boundary_discards_candidate_and_running_pass(boundary):
assert running is not None
if boundary == "reset":
cc.on_session_reset()
- else:
+ elif boundary == "end":
cc.on_session_end("S1", msgs)
+ else: # /resume or /branch onto another session
+ cc.bind_session_state(None, "S2")
cc.gate.set()
running.join(5.0)
assert cc.prepared_compaction._entry is None and cc.prepared_compaction._pending is None
+def test_same_session_rebind_keeps_the_candidate():
+ cc = _compressor()
+ msgs = _messages(30)
+ entry = _prepare(cc, msgs)
+ cc.bind_session_state(None, "S1") # e.g. on_session_start after construction already bound S1
+ assert cc.prepared_compaction._entry is entry
+ cc.compress(_grow(msgs, 4), current_tokens=cc.threshold_tokens + 1)
+ assert [c["worker"] for c in cc.calls] == [True]
+
+
# --------------------------------------------------------------------------- extension, failures
@@ -439,7 +478,7 @@ def test_turn_that_crosses_the_trigger_splices_the_summary_prepared_during_its_t
cc = agent.context_compressor
assert (cc.prepared_compaction is not None) is prepare_ahead
cc.context_length, cc.threshold_tokens, cc.tail_token_budget = 40960, 20000, 2500
- band_floor = cc.threshold_tokens - int(cc.context_length * pc.PREPARE_BAND_RATIO)
+ band_floor = int(cc.threshold_tokens * (1 - pc.PREPARE_BAND_RATIO))
summaries, tool_started = [], threading.Event()
diff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.md
index 159b13c49ed..31dc199845f 100644
--- a/website/docs/developer-guide/context-compression-and-caching.md
+++ b/website/docs/developer-guide/context-compression-and-caching.md
@@ -675,26 +675,28 @@ it is the handoff the transcript now carries.
With `compression.prepare_ahead: true` (read at agent construction, so it takes effect on the next
session or gateway agent rebuild), `agent/prepared_compaction.py` writes the next summary before
-the trigger fires. When the last provider-reported prompt count is within 12% of the context window
-below the trigger, the turn loop starts a background pass before a tool batch runs and at turn end.
-The pass plans the same window `compress()` plans (`_plan_compaction_window`) and calls the same
+the trigger fires. When the last provider-reported prompt count is within 12% of the trigger
+(`threshold_tokens`) below it, the turn loop starts a background pass before a tool batch runs and
+at turn end. The pass plans the same window `compress()` plans (`_plan_compaction_window`) and calls the same
`_generate_summary` on a copy of the compressor and of the window's messages, so the live transcript,
the system prompt and the prompt cache are untouched until compaction.
At the next automatic threshold compaction `compress()` splices the completed candidate only when
-the head boundary is unchanged, the candidate boundary is no later than the fresh tail cut, and the
+the head boundary is unchanged, the candidate boundary is no later than the fresh tail cut, the
transcript up to that boundary fingerprints identically (role, text, tool call ids and names, tool
-result ids; not the tool bodies or arguments the prune rewrites). The summary then covers
-`[head, candidate boundary)` and every later message is kept as tail, including messages a fresh
-plan would have summarized; tail rules such as lean-mode tool stubbing still apply to them. Summary
-placement and alternation handling are the normal Phase 4 assembly.
+result ids; not the tool bodies or arguments the prune rewrites), and the messages between the
+candidate boundary and the fresh cut fit in one more tail budget (`tail_token_budget`, rough
+estimate). The summary then covers `[head, candidate boundary)` and every later message is kept as
+tail, including those messages a fresh plan would have summarized; tail rules such as lean-mode
+tool stubbing still apply to them. Summary placement and alternation handling are the normal
+Phase 4 assembly.
Everything else runs inline exactly as without the flag: no candidate, a candidate that no longer
fits, a pass still running (never waited on: the wait would count against the compression idle
timeout), manual `/compress`, focus compaction, provider-overflow recovery, and compactions where a
memory provider contributes summary context. A running pass overtaken by compaction or a session
-boundary cannot publish its result. A failed pass pauses further passes but never arms the live
-compressor's failure cooldown. State is per compressor and in memory only, so a gateway agent
+boundary (including a rebind to another session id on `/resume` or `/branch`) cannot publish its
+result. A failed pass pauses further passes but never arms the live compressor's failure cooldown. State is per compressor and in memory only, so a gateway agent
eviction or process restart simply means the next compaction runs inline. Plugin context engines,
Codex app-server sessions, native Responses compaction and micro-compaction are not prepared.