Skip to content

The agent that grows with you

feat(compression): wait for a running prepared-compaction pass at the threshold

kshitijk4poord2d1824fdfbf
diff --git a/agent/prepared_compaction.py b/agent/prepared_compaction.py
index 3d80ac1224e..6aa1e7f3e9b 100644
--- a/agent/prepared_compaction.py
+++ b/agent/prepared_compaction.py
@@ -14,10 +14,16 @@ 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 compaction runs inline
+exactly as without the flag.
+
+When no completed candidate fits but a running pass would, compaction waits for
+that pass instead of starting the same summary over: the pass's streamed
+progress feeds the waiting compaction's progress hook, so the host's idle
+watchdog sees a live summary exactly as it would inline, and the wait ends at
+the host's deadline (the compression aux timeout without one) or on
+cancellation. A pass that is not waited on loses the right to publish once
+compaction runs.
State is per compressor and in memory only; every session boundary (reset,
end, or a rebind to another session id) discards it. Manual, focus,
@@ -37,7 +43,7 @@ import logging
import threading
import time
from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Optional
logger = logging.getLogger(__name__)
@@ -54,15 +60,38 @@ _FAILED_PASS_BACKOFF_SECONDS = 60.0
_slots = threading.BoundedSemaphore(2)
+# How often a compaction waiting on a running pass re-checks cancellation and the deadline.
+_WAIT_POLL_SECONDS = 0.5
+
+
@dataclass(frozen=True)
-class PreparedSummary:
+class _Window:
compress_start: int
compress_end: int
fingerprint: str
+
+
+@dataclass(frozen=True)
+class PreparedSummary(_Window):
summary: str # prefixed handoff text, exactly as ``_generate_summary`` returns it
body: str # bare body the next compaction extends iteratively
+class _PendingPass:
+ """The one running pass allowed to publish: its planned window, a completion event, and the
+ progress hook of a compaction waiting on it."""
+
+ def __init__(self, window: _Window) -> None:
+ self.window = window
+ self.done = threading.Event()
+ self.on_progress: Optional[Callable[[], None]] = None
+
+ def touch(self) -> None:
+ hook = self.on_progress
+ if hook is not None:
+ hook()
+
+
def _text_of(content: Any) -> str:
if content is None:
return ""
@@ -98,7 +127,7 @@ def _message_identity(msg: Any) -> str:
return "\x1f".join(parts)
-def fingerprint(messages: List[Dict[str, Any]], session_id: str, start: int, end: int) -> str:
+def fingerprint(messages: list[dict[str, Any]], session_id: str, start: int, end: int) -> str:
"""Identity of ``messages[:end]`` for a window ``[start, end)`` of ``session_id``."""
digest = hashlib.sha256(f"{session_id}\x1f{start}:{end}".encode("utf-8", errors="replace"))
for msg in messages[:end]:
@@ -108,7 +137,7 @@ def fingerprint(messages: List[Dict[str, Any]], session_id: str, start: int, end
def _mismatch(
- entry: PreparedSummary, messages: List[Dict[str, Any]], session_id: str, start: int, end: int,
+ entry: _Window, messages: list[dict[str, Any]], session_id: str, start: int, end: int,
) -> Optional[str]:
"""Why ``entry`` does not fit the planned window ``[start, end)`` of ``messages``, or None."""
if entry.compress_start != start:
@@ -136,7 +165,7 @@ class PreparedCompaction:
def __init__(self) -> None:
self._lock = threading.Lock()
self._entry: Optional[PreparedSummary] = None
- self._pending: Optional[object] = None # token of the one pass allowed to publish
+ self._pending: Optional[_PendingPass] = None # the one pass allowed to publish
self._retry_after = 0.0 # monotonic; set by a failed pass
def discard(self, reason: str) -> None:
@@ -149,29 +178,32 @@ class PreparedCompaction:
)
def take(
- self, messages: List[Dict[str, Any]], session_id: str, start: int, end: int, *,
+ 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."""
+ """The completed candidate when it fits ``compress()``'s planned window, else what a running pass
+ whose window fits publishes while this compaction waits for it, else None. A window 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
- self._entry = self._pending = None
- if not eligible:
- reason = "fresh summary required"
- elif entry is None:
- 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:
+ entry, pending = self._entry, self._pending
+ self._entry = None
+ reason = None if eligible else "fresh summary required"
+ if reason is None and entry is not None:
+ reason = self._misfit(entry, messages, session_id, start, end, max_gap_tokens)
+ try:
+ if eligible and (entry is None or reason is not None):
+ if pending is not None and self._misfit(pending.window, messages, session_id, start, end, max_gap_tokens) is None:
+ entry = self._await(pending)
+ reason = None if entry is not None else "running pass did not finish in time"
+ elif entry is None:
+ reason = "running pass does not fit" if pending is not None else "no candidate"
+ finally:
+ with self._lock:
+ if self._pending is pending:
+ self._pending = None
+ if reason is not None or entry is None:
+ if entry is not None or pending is not None:
logger.info("prepared compaction: splice miss reason=%s", reason)
return None
logger.info(
@@ -179,6 +211,47 @@ class PreparedCompaction:
)
return entry
+ @staticmethod
+ def _misfit(
+ window: _Window, messages: list[dict[str, Any]], session_id: str, start: int, end: int, max_gap_tokens: int,
+ ) -> Optional[str]:
+ """Why *window* cannot splice into the planned window ``[start, end)``, or None."""
+ reason = _mismatch(window, messages, session_id, start, end)
+ if reason is None:
+ from agent.model_metadata import estimate_messages_tokens_rough
+
+ gap = estimate_messages_tokens_rough(messages[window.compress_end:end])
+ if gap > max_gap_tokens:
+ reason = f"stale candidate (~{gap} tokens past its boundary, budget {max_gap_tokens})"
+ return reason
+
+ def _await(self, pending: _PendingPass) -> Optional[PreparedSummary]:
+ """Wait on the compacting thread for *pending* and return what it published; None at the host's
+ deadline (the compression aux timeout without one) or when the host cancels. Meanwhile the pass's
+ streamed progress feeds this thread's aux progress hook, so the host's idle watchdog sees a live
+ summary exactly as it would inline."""
+ from agent.auxiliary_client import (
+ _aux_progress, _capture_aux_cancel_check, _captured_aux_cancel_requested, _current_aux_stream_deadline,
+ _effective_aux_timeout,
+ )
+
+ cancel_check = _capture_aux_cancel_check()
+ deadline = _current_aux_stream_deadline() or time.monotonic() + float(_effective_aux_timeout("compression", None))
+ pending.on_progress = getattr(_aux_progress, "hook", None)
+ logger.info(
+ "prepared compaction: waiting for the running pass window=%d-%d",
+ pending.window.compress_start, pending.window.compress_end,
+ )
+ try:
+ while not pending.done.wait(max(0.0, min(_WAIT_POLL_SECONDS, deadline - time.monotonic()))):
+ if time.monotonic() >= deadline or (cancel_check is not None and _captured_aux_cancel_requested(cancel_check)):
+ return None
+ finally:
+ pending.on_progress = None
+ with self._lock:
+ entry, self._entry = self._entry, None
+ return entry if entry is not None and entry.fingerprint == pending.window.fingerprint else None
+
def _blocked(self, agent: Any, compressor: Any) -> bool:
if not getattr(agent, "compression_enabled", False) or getattr(agent, "_persist_disabled", False):
return True # compression off, or a background-review fork of the live session
@@ -198,10 +271,10 @@ class PreparedCompaction:
return now < compressor._summary_failure_cooldown_until or now < self._retry_after
def maybe_prepare(
- self, agent: Any, compressor: Any, messages: List[Dict[str, Any]], origin: str,
+ self, agent: Any, compressor: Any, messages: list[dict[str, Any]], origin: str,
) -> Optional[threading.Thread]:
"""Start a pass when the next compaction is near; returns the started thread. Never raises."""
- token: Optional[object] = None
+ token: Optional[_PendingPass] = None
try:
if self._blocked(agent, compressor):
return None
@@ -243,13 +316,13 @@ class PreparedCompaction:
if self._pending is not None:
_slots.release()
return None
- token = self._pending = object()
+ token = self._pending = _PendingPass(_Window(start, end, window_fingerprint))
from agent.memory_provider import spawn_context_thread
# Profile and secret scope ride the contextvars into the pass.
thread = spawn_context_thread(
self._run_pass, name="compaction-prepare",
- args=(worker, copy.deepcopy(turns), focus, start, end, window_fingerprint, token, origin, extend),
+ args=(worker, copy.deepcopy(turns), focus, token, origin, extend),
)
thread.start()
return thread
@@ -258,16 +331,19 @@ class PreparedCompaction:
with self._lock:
if self._pending is token:
self._pending = None
+ token.done.set()
_slots.release()
logger.debug("prepared compaction: maybe_prepare failed", exc_info=True)
return None
def _run_pass(
- self, worker: Any, turns: List[Dict[str, Any]], focus: Optional[str], start: int, end: int,
- window_fingerprint: str, token: object, origin: str, extend: Optional[PreparedSummary],
+ self, worker: Any, turns: list[dict[str, Any]], focus: Optional[str], token: _PendingPass, origin: str,
+ extend: Optional[PreparedSummary],
) -> None:
+ from agent.auxiliary_client import aux_progress_hook
from agent.thread_scoped_output import thread_scoped_silence
+ start, end, window_fingerprint = token.window.compress_start, token.window.compress_end, token.window.fingerprint
entry: Optional[PreparedSummary] = None
started = time.monotonic()
try:
@@ -275,7 +351,7 @@ class PreparedCompaction:
"prepared compaction: pass started origin=%s window=%d-%d turns=%d extends=%s",
origin, start, end, len(turns), extend is not None,
)
- with thread_scoped_silence():
+ with thread_scoped_silence(), aux_progress_hook(token.touch):
summary = worker._generate_summary(turns, focus_topic=focus)
if summary:
entry = PreparedSummary(start, end, window_fingerprint, summary, worker._previous_summary)
@@ -296,10 +372,11 @@ class PreparedCompaction:
self._retry_after = max(
worker._summary_failure_cooldown_until, time.monotonic() + _FAILED_PASS_BACKOFF_SECONDS,
)
+ token.done.set()
_slots.release()
-def maybe_prepare(agent: Any, messages: List[Dict[str, Any]], *, origin: str) -> Optional[threading.Thread]:
+def maybe_prepare(agent: Any, messages: list[dict[str, Any]], *, origin: str) -> Optional[threading.Thread]:
"""Turn-loop hook; a no-op unless ``compression.prepare_ahead`` gave the compressor state."""
compressor = getattr(agent, "context_compressor", None)
state = getattr(compressor, "prepared_compaction", None)
diff --git a/tests/agent/test_prepared_compaction.py b/tests/agent/test_prepared_compaction.py
index 0da447bf20b..98e09c013a1 100644
--- a/tests/agent/test_prepared_compaction.py
+++ b/tests/agent/test_prepared_compaction.py
@@ -7,9 +7,9 @@ Behaviour contracts, with the summariser stubbed at its model boundary:
* append-only growth keeps a candidate, which splices at its own boundary with newer messages kept as tail;
* 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 (a same-session
- rebind keeps the candidate);
+* a completed candidate splices while an extension pass runs; without one, compaction waits for a running
+ pass whose window fits (forwarding its progress to the host) until the host's deadline, 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.
"""
@@ -38,6 +38,10 @@ class _StubCompressor(ContextCompressor):
worker = threading.current_thread().name == "compaction-prepare"
if worker and self.gate is not None:
assert self.gate.wait(5.0), "pass never released"
+ if worker and self.stream_progress:
+ from agent.auxiliary_client import _aux_progress
+
+ _aux_progress.hook() # one streamed chunk
self.calls.append({
"worker": worker,
"n_turns": len(turns_to_summarize),
@@ -57,7 +61,7 @@ def _compressor(*, enabled: bool = True, session_id: str = "S1") -> _StubCompres
cc.context_length = 40960
cc.threshold_tokens = 20000
cc.tail_token_budget = 2500
- cc.calls, cc.gate = [], None
+ cc.calls, cc.gate, cc.stream_progress = [], None, False
cc._session_id = session_id
if enabled:
cc.prepared_compaction = PreparedCompaction()
@@ -143,7 +147,7 @@ def test_pass_leaves_live_transcript_and_compressor_untouched():
assert msgs == before
assert cc._previous_summary is None and cc.compression_count == 0
assert [c["worker"] for c in cc.calls] == [True]
- working, _, start, end = cc._plan_compaction_window(msgs)
+ _working, _, start, end = cc._plan_compaction_window(msgs)
assert (entry.compress_start, entry.compress_end) == (start, end)
assert entry.body == f"Summary v1 of {end - start} turns."
@@ -208,19 +212,31 @@ 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():
[email protected]("pass_state", ["completed", "running"])
+def test_growth_past_the_candidate_beyond_the_tail_budget_summarises_inline(pass_state):
+ """A stale window never splices, and a running pass with a stale window is not waited on."""
cc = _compressor()
msgs = _messages(30)
- entry = _prepare(cc, msgs)
+ if pass_state == "running":
+ cc.gate = threading.Event()
+ running = pc.maybe_prepare(_agent(cc), msgs, origin="test")
+ assert running is not None
+ else:
+ _prepare(cc, msgs)
+ window = (cc.prepared_compaction._entry or cc.prepared_compaction._pending.window)
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
+ assert start == window.compress_start and end > window.compress_end
+ assert estimate_messages_tokens_rough(later[window.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"]
+ if pass_state == "running":
+ assert running.is_alive(), "not waited on"
+ cc.gate.set()
+ running.join(5.0)
+ assert sorted(c["worker"] for c in cc.calls) == [False, True], "one pass, one inline summary"
+ assert "Summary v" in _summary_row(compressed)["content"] and cc.prepared_compaction._entry is None
@pytest.mark.parametrize("change", ["middle rewritten", "head moved", "other session"])
@@ -322,17 +338,41 @@ def test_completed_candidate_splices_while_an_extension_pass_runs():
assert cc.prepared_compaction._entry is None, "an overtaken pass cannot publish"
-def test_unfinished_pass_is_not_waited_on_and_cannot_publish_later():
+def test_compaction_waits_for_a_running_pass_and_forwards_its_progress():
+ """No candidate yet: the compaction waits for the running pass instead of summarising again, and each
+ streamed chunk of the pass touches the compacting thread's progress hook (the host's idle watchdog)."""
+ from agent.auxiliary_client import aux_progress_hook
+
+ cc = _compressor()
+ cc.gate, cc.stream_progress = threading.Event(), True
+ msgs = _messages(30)
+ running = pc.maybe_prepare(_agent(cc), msgs, origin="test")
+ assert running is not None
+ host_progress = []
+ threading.Timer(0.3, cc.gate.set).start()
+ with aux_progress_hook(lambda: host_progress.append(threading.current_thread().name)):
+ compressed = cc.compress(msgs, current_tokens=cc.threshold_tokens + 1)
+ running.join(5.0)
+
+ assert [c["worker"] for c in cc.calls] == [True], "the pass's summary was spliced, no inline call"
+ assert "Summary v1" in _summary_row(compressed)["content"]
+ assert host_progress == ["compaction-prepare"], "pass progress reached the waiting host"
+ assert cc.prepared_compaction._pending is None and cc.prepared_compaction._entry is None
+
+
+def test_wait_ends_at_the_host_deadline_then_summarises_inline_and_the_pass_cannot_publish():
+ from agent.auxiliary_client import aux_stream_deadline
+
cc = _compressor()
cc.gate = threading.Event()
msgs = _messages(30)
running = pc.maybe_prepare(_agent(cc), msgs, origin="test")
assert running is not None
- started = time.monotonic()
- cc.compress(msgs, current_tokens=cc.threshold_tokens + 1)
- assert time.monotonic() - started < 2.0
- assert _wait_until(lambda: len(cc.calls) == 1) and cc.calls[0]["worker"] is False, "inline summary"
+ with aux_stream_deadline(time.monotonic() + 0.2):
+ cc.compress(msgs, current_tokens=cc.threshold_tokens + 1)
+ assert running.is_alive(), "the wait ended at the host deadline, not with the pass"
+ assert [c["worker"] for c in cc.calls] == [False], "inline summary after the deadline"
cc.gate.set()
running.join(5.0)
diff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.md
index 31dc199845f..8a4ce13d024 100644
--- a/website/docs/developer-guide/context-compression-and-caching.md
+++ b/website/docs/developer-guide/context-compression-and-caching.md
@@ -691,10 +691,15 @@ tail, including those messages a fresh plan would have summarized; tail rules su
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
+When no completed candidate fits but the pass still running would, compaction waits for that pass
+instead of writing the same summary again. Each streamed chunk of the pass touches the waiting
+compaction's progress hook, so the host's idle watchdog treats the wait like an inline summary
+stream. The wait ends at the host's deadline (the compression aux timeout when there is none) or on
+cancellation, and compaction then summarizes inline.
+
+Everything else runs inline exactly as without the flag: no candidate, a candidate or running pass
+that no longer fits, 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 (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,
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 22fab6d3a02..4bb7767ba1e 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -1080,7 +1080,7 @@ The value is the **first rung** of an escalating ladder, not a fixed interval: c
`idle_compact_after_seconds` is an **opt-in, time-based** trigger that complements the size-based `threshold`. Default `0` (disabled). When set above 0, a session that resumes after at least that many seconds of inactivity compacts its accumulated history up front, before the first reply — so a long-lived thread (e.g. a Telegram conversation you come back to hours later) doesn't re-read its full stale context on every subsequent turn. It never fires when the context is already at or below the post-compression target (`threshold × target_ratio`), and it honors the same failure-cooldown, anti-thrash, and per-session lock guards as every automatic compaction. Example: `idle_compact_after_seconds: 1800` compacts after 30 minutes idle.
-`prepare_ahead` (default `false`) writes the next compaction summary in the background once the session is close to the trigger, while tools run and between turns. When automatic compaction fires and the summarized messages are unchanged, the prepared summary is used instead of a summary call at that moment; messages newer than the prepared summary stay outside it and are handled as the usual uncompressed tail. If no prepared summary is ready or it no longer matches, compaction runs exactly as it does without the option. It spends auxiliary summary calls that may go unused, and it does not apply to manual `/compress`, plugin context engines, or native/app-server compaction.
+`prepare_ahead` (default `false`) writes the next compaction summary in the background once the session is close to the trigger, while tools run and between turns. When automatic compaction fires and the summarized messages are unchanged, the prepared summary is used instead of a summary call at that moment; messages newer than the prepared summary stay outside it and are handled as the usual uncompressed tail. If the prepared summary is still being written when compaction fires, compaction waits for it (within the usual compression time limit) rather than writing it again. If there is no prepared summary or it no longer matches, compaction runs exactly as it does without the option. It spends auxiliary summary calls that may go unused, and it does not apply to manual `/compress`, plugin context engines, or native/app-server compaction.
`proactive_prune_tokens` enables a deterministic, no-LLM prune of old tool-result payloads that runs independently of `threshold`. On large-window models the `threshold` compaction (≈50% of the window) rarely fires, so bulky tool outputs (terminal dumps, file reads, web extracts) ride along in history and get re-sent on every subsequent turn. When re-sent history exceeds `proactive_prune_tokens` (default `0` = off; try `48000` to enable), the prune dedupes identical results and summarizes older oversized tool results, protecting the most recent `protect_last_n` messages and never calling the model. Tool-call arguments are execution records and are never rewritten by pruning; the summary model has a separate bounded serializer for copies included in its prompt. The pressure pass likewise demotes tool-result bodies only. During full semantic compaction the carried head/tail rows keep those tool-result demotions (so an oversized tail can still compress), while tool-call arguments stay byte-exact. The opt-in proactive prune still commits eligible tool-result-body demotions, so `proactive_prune_min_reclaim_tokens` (default `4096`) keeps those cache-breaking commits episodic; `proactive_prune_min_result_chars` (default `8000`, clamped to ≥ 200) sets the size below which a tool result is left untouched. This runs only under the built-in `compressor` engine; other context engines inherit a no-op.