The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
feat(compression): one prepared summary per compaction, newer messages join the tail
Tekniumc2383a680697
diff --git a/agent/context_compressor.py b/agent/context_compressor.pyindex 34609ccba6c..dabe554c6d5 100644--- a/agent/context_compressor.py+++ b/agent/context_compressor.py@@ -5488,7 +5488,8 @@ Write only the summary body. Do not include any preamble or prefix.""")return canonical_messagesprepared = self._take_prepared_summary(- messages, compress_start, compress_end, fresh=bool(force or focus_topic or bypass_cooldown or memory_context.strip()),+ messages, compress_start, compress_end, fresh=bool(force or focus_topic or bypass_cooldown),+ provider_context=bool(memory_context.strip()),)if prepared:compress_end = prepared.compress_end@@ -5530,8 +5531,7 @@ Write only the summary body. Do not include any preamble or prefix."""summary = None # pre-LLM summary skip (feasibility or benched model): no LLM call; Phase 4 inserts the deterministic fallbackif prepared:# The pass ran this window through _generate_summary; adopt its result as an inline call would.- self._record_summary_success(prepared.body)- summary = prepared.summary+ summary = self._adopt_prepared_summary(prepared)elif not feasibility_skip:summary = self._summarize_window(messages, turns_to_summarize, scan, focus_topic, memory_context, bypass_cooldown,diff --git a/agent/context_compressor_telemetry.py b/agent/context_compressor_telemetry.pyindex ec826c4c64e..0e44aaacee1 100644--- a/agent/context_compressor_telemetry.py+++ b/agent/context_compressor_telemetry.py@@ -56,6 +56,8 @@ class CompressionTelemetryMixin:"method": "none", "items_dropped": 0, "messages_before": None, "messages_after": None,"tokens_before": None, "tokens_after": None, "tokens_reclaimed": None, "token_count_method": None,"tool_results_pruned": None, "reasoning_items_pruned": None, "has_focus_topic": False,+ # True when the summary came from an opt-in prepared (background) pass (compression.prepare_ahead).+ "prepared_summary": False,}self._active_compression_telemetry = self._last_compression_telemetry = telemetryreturn telemetrydiff --git a/agent/context_compressor_window.py b/agent/context_compressor_window.pyindex ecbfcf20515..51e5b31fa34 100644--- a/agent/context_compressor_window.py+++ b/agent/context_compressor_window.py@@ -45,13 +45,23 @@ class CompactionWindowMixin:def _take_prepared_summary(self, messages: list[dict[str, Any]], compress_start: int, compress_end: int, *, fresh: bool,+ provider_context: bool,) -> Optional[PreparedSummary]:"""The summary prepared in the background for this window, which an automatic compaction splices at- ITS boundary; newer messages (at most one more tail budget) stay outside the summary, in the tail.- ``fresh`` compactions (manual, focus, overflow recovery, memory-provider context) summarize anew."""+ ITS boundary; every newer message stays outside the summary, in the tail. ``fresh`` compactions+ (manual, focus, overflow recovery, memory-provider context) summarize anew, and once a memory+ provider supplies context no further summaries are prepared (each would be thrown away)."""if self.prepared_compaction is None:return None+ if provider_context:+ self.prepared_compaction.stop_for_provider_context()return self.prepared_compaction.take(- messages, self._session_id, compress_start, compress_end, eligible=not fresh,- max_gap_tokens=self.tail_token_budget,+ messages, self._session_id, compress_start, compress_end, eligible=not (fresh or provider_context),)++ def _adopt_prepared_summary(self, prepared: PreparedSummary) -> str:+ """Adopt a prepared summary as an inline summary call would have left it; returns the handoff text."""+ from agent.prepared_compaction import adopt++ adopt(self, prepared)+ return prepared.summarydiff --git a/agent/prepared_compaction.py b/agent/prepared_compaction.pyindex 439068ac9ac..2bec5caccbe 100644--- a/agent/prepared_compaction.py+++ b/agent/prepared_compaction.py@@ -2,22 +2,23 @@When the provider-reported prompt size comes within ``PREPARE_BAND_RATIO`` ofthe compaction trigger, the turn loop (before a tool batch runs, and at turn-end) starts a background pass. The pass plans the same window+end) starts ONE background pass. The pass plans the same window``ContextCompressor.compress`` would plan and runs the existing summariser on acopy of the compressor and of that window's messages. The live transcript andcompressor 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, 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 compaction runs inline-exactly as without the flag.--When no completed candidate fits but a running pass would, compaction waits for+summary if the messages it covers are still the same messages: same session,+same head boundary, a boundary no later than the current tail cut, and the same+message structure (roles, tool call and result ids, and the durable+``message_uid`` where both sides carry one) up to that boundary. Message text is+not compared: plugins rewrite text in place, and a summary written before such a+rewrite still summarises the same messages. On a hit the summary replaces+``messages[start:candidate_end]`` and every message after the candidate+boundary, however many arrived since the pass started, stays verbatim in the+tail. On a miss compaction runs inline exactly as without the flag.++When no completed summary exists but a running pass fits, compaction waits forthat pass instead of starting the same summary over: the pass's streamedprogress and local prompt reading feed the waiting compaction's hooks, so thehost's idle watchdog and deadline extension see a live summary exactly as they@@ -29,65 +30,72 @@ stream is closed instead of being billed to completion for nothing.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-invalidate a summary written from a superset of the same information.+fresh; the first compaction that needs provider context stops further passes+for the agent, since every later one would need it too. A failed pass backs off+further passes but never touches the live compressor's cooldown or failure+state; a pass that recovered on the main model hands that fallback to the live+compressor on a splice, as an inline summary would."""from __future__ import annotationsimport copy-import dataclasses-import hashlibimport loggingimport threadingimport time-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom typing import Any, Callable, Optionallogger = logging.getLogger(__name__)-# Start passes once the real prompt count is within this fraction of the+# Start a pass once the real prompt count is within this fraction of the# 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-# splicing and the summariser is not called once per chatty turn.-MIN_EXTENSION_DELTA_TOKENS = 8_000# Minimum pause after a failed pass (the summariser's own cooldown applies when longer)._FAILED_PASS_BACKOFF_SECONDS = 60.0# Background passes running across the process (a cancelled pass frees its slot as it unwinds; its# provider stream closes on the aux cancel path, normally within one chunk)._slots = threading.BoundedSemaphore(2)--# How often a compaction waiting on a running pass re-checks cancellation and the deadline._WAIT_POLL_SECONDS = 0.5+# Compressor state a summary call leaves behind besides the summary: the main-model fallback after a+# failed summary model (sticky for the session) and the warning it raises. A splice adopts the pass's.+_SUMMARY_CALL_STATE = (+ "summary_model", "_last_aux_model_failure_error", "_last_aux_model_failure_model", "_last_aux_resolved_model",+)+# Attempt telemetry the summary call fills; a splice copies the pass's values onto the attempt.+_SUMMARY_CALL_TELEMETRY = (+ "aux_prompt_tokens", "aux_output_reservation", "aux_provider", "aux_model", "effective_aux_context", "fit_margin",+ "aux_call_duration_ms", "queue_wait_ms", "prompt_build_ms", "time_to_first_progress_ms", "summary_generation_ms",+ "summary_input_chars", "summary_input_sampled_chars", "summary_input_omitted_chars", "summary_input_record_count",+ "summary_input_sampled_record_count", "summary_input_elided_record_count", "fallback_used", "failure_class",+)++# Per message: (structure, durable uid or None).+_Identity = tuple[str, Optional[str]]@dataclass(frozen=True)class _Window:+ session_id: strcompress_start: intcompress_end: int- fingerprint: str+ identities: tuple[_Identity, ...] # one per message of ``messages[:compress_end]``@dataclass(frozen=True)class PreparedSummary(_Window):summary: str # prefixed handoff text, exactly as ``_generate_summary`` returns itbody: str # bare body the next compaction extends iteratively- prompt_tokens: int # provider-reported prompt size when this candidate was last planned or checked+ call_state: dict[str, Any] = field(default_factory=dict, compare=False) # _SUMMARY_CALL_STATE after the pass+ telemetry: dict[str, Any] = field(default_factory=dict, compare=False) # _SUMMARY_CALL_TELEMETRY of the passclass _PendingPass:"""The one running pass allowed to publish: its planned window, completion and cancel events, andthe progress and prompt-reading hooks of a compaction waiting on it."""- def __init__(self, window: _Window, prompt_tokens: int) -> None:+ def __init__(self, window: _Window) -> None:self.window = window- self.prompt_tokens = prompt_tokensself.done = threading.Event()# Set once nothing can use the pass any more; its summary stream is closed (the aux hard-cancel path).self.cancelled = threading.Event()@@ -105,73 +113,72 @@ class _PendingPass:hook(seconds)-def _text_of(content: Any) -> str:- if content is None:- return ""- if isinstance(content, str):- return content- if isinstance(content, list):- return "\n".join(- part if isinstance(part, str) else part["text"]- for part in content- if isinstance(part, str)- or (isinstance(part, dict) and part.get("type") in (None, "text") and isinstance(part.get("text"), str))- )- return str(content)---def _message_identity(msg: Any) -> str:- """Role, text, tool call ids/names and tool result ids; nothing the prune pass rewrites.- Text is normalised the way a SessionDB round trip normalises it."""+def _message_identity(msg: Any) -> _Identity:+ """Role, tool call ids/names and tool result ids, plus the durable ``message_uid`` when the message+ has been persisted. Text, tool arguments and result bodies are left out: the no-LLM prune and+ plugins rewrite them in place, while the splice only needs whole messages that line up."""if not isinstance(msg, dict):- return "?"- from agent.memory_manager import sanitize_context+ return "?", None+ from agent.message_metadata import message_uid_or_nonerole = str(msg.get("role") or "")if role == "tool":- return f"tool\x1f{msg.get('tool_call_id') or ''}"- parts = [role, sanitize_context(_text_of(msg.get("content"))).strip()]+ return f"tool\x1f{msg.get('tool_call_id') or ''}", message_uid_or_none(msg)+ parts = [role]for tc in msg.get("tool_calls") or []:if isinstance(tc, dict):fn = tc.get("function") or {}parts.append(f"{tc.get('id', '')}:{fn.get('name', '') if isinstance(fn, dict) else ''}")else:parts.append(f"{getattr(tc, 'id', '')}:{getattr(getattr(tc, 'function', None), 'name', '')}")- return "\x1f".join(parts)+ return "\x1f".join(parts), message_uid_or_none(msg)-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]:- digest.update(_message_identity(msg).encode("utf-8", errors="replace"))- digest.update(b"\x1e")- return digest.hexdigest()+def prefix_identities(messages: list[dict[str, Any]], end: int) -> tuple[_Identity, ...]:+ """Identity of each message in ``messages[:end]``."""+ return tuple(_message_identity(msg) for msg in messages[:end])def _mismatch(- entry: _Window, messages: list[dict[str, Any]], session_id: str, start: int, end: int,+ window: _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:- return f"head moved ({entry.compress_start} -> {start})"- if entry.compress_end > end:- return f"prepared boundary {entry.compress_end} is inside the protected tail (cut {end})"- if entry.compress_end > len(messages) or fingerprint(messages, session_id, start, entry.compress_end) != entry.fingerprint:- return "transcript changed"+ """Why *window* cannot splice into the planned window ``[start, end)`` of ``messages``, or None."""+ if window.session_id != session_id:+ return "another session"+ if window.compress_start != start:+ return f"head moved ({window.compress_start} -> {start})"+ if window.compress_end > end:+ return f"prepared boundary {window.compress_end} is inside the protected tail (cut {end})"+ if window.compress_end > len(messages):+ return "transcript shorter than the prepared window"+ for idx, ((structure, uid), msg) in enumerate(zip(window.identities, messages)):+ now_structure, now_uid = _message_identity(msg)+ if now_structure != structure:+ return f"message {idx} changed shape"+ if uid and now_uid and uid != now_uid:+ return f"message {idx} is a different message (rewound or branched)"return Nonedef _worker_copy(compressor: Any) -> Any:- """A compressor copy whose writes stay off the live one: no durable row, no attempt- telemetry, no host cancel consult (those belong to a foreground attempt)."""+ """A compressor copy whose writes stay off the live one: no durable row, private attempt+ telemetry, no host cancel consult (those belong to a foreground attempt), and the per-call+ fallback fields cleared as a compaction attempt clears them."""worker = copy.copy(compressor)worker._session_db = None- worker._active_compression_telemetry = worker._last_compression_telemetry = Noneworker._compression_cancelled_check = None+ worker._last_aux_model_failure_error = worker._last_aux_model_failure_model = None+ worker._begin_compression_telemetry(current_tokens=None)return worker+def _blocked_for_platform(agent: Any, origin: str) -> bool:+ """A turn-end pass in a session that ends with its turn (a cron run, a delegated child) is never used."""+ if origin != "turn-end":+ return False+ return getattr(agent, "platform", None) in ("cron", "subagent") or getattr(agent, "_delegate_depth", 0) > 0++class PreparedCompaction:"""Prepared-summary state owned by one ``ContextCompressor``."""@@ -180,6 +187,8 @@ class PreparedCompaction:self._entry: Optional[PreparedSummary] = Noneself._pending: Optional[_PendingPass] = None # the one pass allowed to publishself._retry_after = 0.0 # monotonic; set by a failed pass+ # Set by the first compaction that needed memory-provider context; such compactions summarise fresh.+ self._needs_provider_context = Falsedef discard(self, reason: str) -> None:"""Drop the candidate and cancel a running pass (it can no longer publish)."""@@ -192,23 +201,27 @@ class PreparedCompaction:"prepared compaction: dropped window=%d-%d reason=%s", entry.compress_start, entry.compress_end, reason,)+ def stop_for_provider_context(self) -> None:+ """A memory provider supplied summary context: stop preparing summaries that would be discarded."""+ if not self._needs_provider_context:+ self._needs_provider_context = True+ logger.info("prepared compaction: off for this agent (memory provider supplies compaction context)")+def take(- self, messages: list[dict[str, Any]], session_id: str, start: int, end: int, *,- eligible: bool, max_gap_tokens: int,+ self, messages: list[dict[str, Any]], session_id: str, start: int, end: int, *, eligible: bool,) -> Optional[PreparedSummary]:"""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 and a- running pass is cancelled: this compaction consumes or supersedes it."""+ whose window fits publishes while this compaction waits for it, else None. Either way the state is+ cleared and a running pass is cancelled: this compaction consumes or supersedes it."""with self._lock:entry, pending = self._entry, self._pendingself._entry = Nonereason = 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)+ reason = _mismatch(entry, messages, session_id, start, end)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:+ if pending is not None and _mismatch(pending.window, messages, session_id, start, end) is None:entry, reason = self._await(pending)elif entry is None:reason = "running pass does not fit" if pending is not None else "no candidate"@@ -229,20 +242,6 @@ 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) -> tuple[Optional[PreparedSummary], Optional[str]]:"""Wait on the compacting thread for *pending*: what it published, or None and why (the host'sdeadline, or the compression aux timeout without one; a host cancel; a discard; a failed pass).@@ -280,11 +279,11 @@ class PreparedCompaction:return None, "running pass discarded"with self._lock:entry, self._entry = self._entry, None- if entry is None or entry.fingerprint != pending.window.fingerprint:+ if entry is None or entry.identities != pending.window.identities:return None, "running pass failed"return entry, None- def _blocked(self, agent: Any, compressor: Any) -> bool:+ def _blocked(self, agent: Any, compressor: Any, origin: str) -> 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 sessionif (@@ -293,6 +292,8 @@ class PreparedCompaction:or getattr(compressor, "_micro_compact_enabled", False)):return True # another path owns compaction, or history is rewritten every turn+ if self._needs_provider_context or _blocked_for_platform(agent, origin):+ return Trueif compressor.awaiting_real_usage_after_compression or compressor._fallback_compression_streak >= 2:return True # no real usage yet, or the summary model is benched after repeated fallbackstokens = compressor.last_prompt_tokens@@ -305,64 +306,41 @@ class PreparedCompaction:def maybe_prepare(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."""+ """Start the pass when the next compaction is near and none ran yet; returns the started thread.+ Never raises."""token: Optional[_PendingPass] = Nonetry:- if self._blocked(agent, compressor):+ if self._blocked(agent, compressor, origin):return Nonewith self._lock:- if self._pending is not None:- return None- completed = self._entry- tokens = compressor.last_prompt_tokens- if completed is not None and 0 <= tokens - completed.prompt_tokens < MIN_EXTENSION_DELTA_TOKENS:- # The prompt has barely grown since the candidate's boundary was the cut: keep it without- # re-planning and re-fingerprinting the transcript before every tool batch.- return None+ if self._pending is not None or self._entry is not None:+ return None # one summary per compaction: later messages join the tail at the spliceworking, _, start, end = compressor._plan_compaction_window(messages)if start >= end:return None- session_id = compressor._session_id- extend = None- if completed is not None and _mismatch(completed, working, session_id, start, end) is None:- from agent.model_metadata import estimate_messages_tokens_rough-- delta = estimate_messages_tokens_rough(working[completed.compress_end:end])- if delta < MIN_EXTENSION_DELTA_TOKENS:- logger.debug("prepared compaction: keeping window=%d-%d, delta ~%d tokens",- completed.compress_start, completed.compress_end, delta)- with self._lock: # measure the next skip from this check, not from the plan- if self._entry is completed:- self._entry = dataclasses.replace(completed, prompt_tokens=tokens)- return None- extend = completedworker = _worker_copy(compressor)# Same handoff rehydration and window rows compress() uses (mutates only the worker).scan = worker._scan_window_handoffs(working, start, end, working[start:end])if scan.tail_start != end:return None # a handoff inside the protected tail: leave it to compress()turns = scan.turns_to_summarize- if extend is not None:- worker._previous_summary = extend.body- turns = working[extend.compress_end:end]if not turns:return Nonefocus = worker._derive_auto_focus_topic(working)- window_fingerprint = fingerprint(working, session_id, start, end)+ window = _Window(compressor._session_id, start, end, prefix_identities(working, end))# Never queue threads that retain transcripts while every slot is busy.if not _slots.acquire(blocking=False):return Nonewith self._lock:- if self._pending is not None:+ if self._pending is not None or self._entry is not None:_slots.release()return None- token = self._pending = _PendingPass(_Window(start, end, window_fingerprint), tokens)+ token = self._pending = _PendingPass(window)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, token, origin, extend),+ self._run_pass, name="compaction-prepare", args=(worker, copy.deepcopy(turns), focus, token, origin),)thread.start()return thread@@ -378,19 +356,18 @@ class PreparedCompaction:def _run_pass(self, worker: Any, turns: list[dict[str, Any]], focus: Optional[str], token: _PendingPass, origin: str,- extend: Optional[PreparedSummary],) -> None:from agent.auxiliary_client import AuxiliaryExplicitCancellation, aux_interrupt_protection, aux_progress_hookfrom agent.local_prompt_progress import prompt_reading_hookfrom agent.thread_scoped_output import thread_scoped_silence- start, end, window_fingerprint = token.window.compress_start, token.window.compress_end, token.window.fingerprint+ window = token.windowentry: Optional[PreparedSummary] = Nonestarted = time.monotonic()try:logger.info(- "prepared compaction: pass started origin=%s window=%d-%d turns=%d extends=%s",- origin, start, end, len(turns), extend is not None,+ "prepared compaction: pass started origin=%s window=%d-%d turns=%d",+ origin, window.compress_start, window.compress_end, len(turns),)with (thread_scoped_silence(), aux_interrupt_protection(cancel_event=token.cancelled),@@ -400,11 +377,15 @@ class PreparedCompaction:if token.cancelled.is_set():logger.info("prepared compaction: pass cancelled after %.1fs (superseded)", time.monotonic() - started)elif summary:+ telemetry = worker._active_compression_telemetry or {}entry = PreparedSummary(- start, end, window_fingerprint, summary, worker._previous_summary, token.prompt_tokens,+ window.session_id, window.compress_start, window.compress_end, window.identities,+ summary, worker._previous_summary,+ call_state={name: getattr(worker, name, None) for name in _SUMMARY_CALL_STATE},+ telemetry={key: telemetry.get(key) for key in _SUMMARY_CALL_TELEMETRY},)logger.info("prepared compaction: pass completed window=%d-%d in %.1fs",- start, end, time.monotonic() - started)+ window.compress_start, window.compress_end, time.monotonic() - started)else:logger.warning("prepared compaction: pass failed after %.1fs: %s", time.monotonic() - started,worker._last_summary_error or "summariser returned nothing")@@ -427,6 +408,18 @@ class PreparedCompaction:_slots.release()+def adopt(compressor: Any, prepared: PreparedSummary) -> None:+ """Leave the live compressor as the inline summary call would have: the summary is the iterative base,+ failure state cleared, the pass's main-model fallback (if any) carried over, its call in the telemetry."""+ compressor._record_summary_success(prepared.body)+ for name, value in prepared.call_state.items():+ setattr(compressor, name, value)+ telemetry = getattr(compressor, "_active_compression_telemetry", None)+ if isinstance(telemetry, dict):+ telemetry.update({key: value for key, value in prepared.telemetry.items() if value is not None})+ telemetry["prepared_summary"] = True++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)diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.pyindex 5cdb2087e01..efed5230280 100644--- a/hermes_cli/config_defaults.py+++ b/hermes_cli/config_defaults.py@@ -691,7 +691,7 @@ DEFAULT_CONFIG = {# front, before the first reply. Time-based complement to `threshold`; skipped when already at/below# threshold × target_ratio; honors the same cooldown/anti-thrash/lock guards. Example: 1800 = 30 min."idle_compact_after_seconds": 0,- # Opt-in: write the next summary in the background near the trigger; compaction uses (or waits for) it if the summarized turns are unchanged.+ # Opt-in: write the next summary in the background near the trigger; compaction uses (or waits for) it if it still covers the same messages."prepare_ahead": False,},# Anthropic prompt caching (Claude via OpenRouter or native API). cache_ttl: "5m" | "1h" | "auto"diff --git a/tests/agent/test_prepared_compaction.py b/tests/agent/test_prepared_compaction.pyindex f028d009344..788ebd19633 100644--- a/tests/agent/test_prepared_compaction.py+++ b/tests/agent/test_prepared_compaction.py@@ -4,14 +4,16 @@ 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, 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; 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.+* one pass per compaction: the candidate splices at its own boundary and every message after it, however+ many, stays verbatim in the tail;+* in-place text rewrites (plugins, the no-LLM prune, blank-echo drop) keep the candidate; a changed message+ structure, a rewound transcript, a moved head or another session's transcript never splices;+* without a completed candidate, 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, and memory-provider+ context stops further passes;+* a splice leaves the live compressor as the inline call would: main-model fallback state and telemetry."""from __future__ import annotations@@ -91,17 +93,13 @@ def _grow(msgs: list, n: int, size: int = 1200, tag: str = "new") -> list:return msgs + _messages(n, size=size, tag=tag)[1:]-# A later prompt that grew by more than the extension threshold since the first pass was planned.-_GROWN_TOKENS = 19500 + pc.MIN_EXTENSION_DELTA_TOKENS--def _agent(cc, tokens: int = 19500):cc.last_prompt_tokens = tokensreturn SimpleNamespace(context_compressor=cc, compression_enabled=True, api_mode="chat_completions")def _prepare(cc, msgs, tokens: int = 19500):- thread = pc.maybe_prepare(_agent(cc, tokens), msgs, origin="test")+ thread = pc.maybe_prepare(_agent(cc, tokens), msgs, origin="tool-batch")assert thread is not None, "expected a pass to start"thread.join(5.0)entry = cc.prepared_compaction._entry@@ -183,6 +181,19 @@ def test_gates_start_no_pass(setup):assert cc.calls == [][email protected]("agent_attrs", [{"platform": "cron"}, {"platform": "subagent"}, {"_delegate_depth": 1}],+ ids=["cron", "subagent-platform", "delegated-child"])+def test_turn_end_pass_skipped_where_the_session_ends_with_the_turn(agent_attrs):+ cc = _compressor()+ agent = _agent(cc)+ for name, value in agent_attrs.items():+ setattr(agent, name, value)+ assert pc.maybe_prepare(agent, _messages(30), origin="turn-end") is None+ thread = pc.maybe_prepare(agent, _messages(30), origin="tool-batch") # mid-turn passes still run+ assert thread is not None+ thread.join(5.0)++def test_pass_runs_under_the_callers_profile_scope(tmp_path):from hermes_constants import reset_hermes_home_override, set_hermes_home_override@@ -221,14 +232,16 @@ def test_append_only_growth_splices_at_the_candidate_boundary_keeping_newer_mess@pytest.mark.parametrize("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."""+def test_growth_past_the_candidate_beyond_the_tail_budget_still_splices_keeping_it_all_in_the_tail(pass_state):+ """However much arrived after the pass started, it joins the tail: no second summary call."""cc = _compressor()msgs = _messages(30)if pass_state == "running":cc.gate = threading.Event()running = pc.maybe_prepare(_agent(cc), msgs, origin="test")assert running is not None+ pending = cc.prepared_compaction._pending+ threading.Thread(target=lambda: wait_until(lambda: pending.on_progress is not None) and cc.gate.set()).start()else:_prepare(cc, msgs)window = (cc.prepared_compaction._entry or cc.prepared_compaction._pending.window)@@ -237,24 +250,49 @@ def test_growth_past_the_candidate_beyond_the_tail_budget_summarises_inline(passassert start == window.compress_start and end > window.compress_endassert estimate_messages_tokens_rough(later[window.compress_end:end]) > cc.tail_token_budget- compressed = cc.compress(later, current_tokens=cc.threshold_tokens + 1)+ from agent.auxiliary_client import aux_progress_hook++ with aux_progress_hook(lambda: None): # a host hook marks the moment the wait starts+ compressed = cc.compress(later, current_tokens=cc.threshold_tokens + 1)if pass_state == "running":running.join(5.0)- assert [c["worker"] for c in cc.calls] == [False], "not waited on: cancelled, one inline summary"- else:- 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+ assert [c["worker"] for c in cc.calls] == [True], "one summary, written by the pass"+ kept = later[window.compress_end:]+ for original, row in zip(kept, compressed[-len(kept):]):+ assert original["content"] in row["content"]+ assert cc.prepared_compaction._entry is None[email protected]("change", ["middle rewritten", "head moved", "other session"])+def test_in_place_text_rewrite_of_summarised_messages_keeps_the_candidate():+ """Plugins rewrite message text in place (redaction, pre-compaction notes): still the same messages."""+ cc = _compressor()+ msgs = _messages(30)+ for i, msg in enumerate(msgs):+ msg["message_uid"] = f"uid-{i}"+ entry = _prepare(cc, msgs)+ live = copy.deepcopy(msgs)+ live[entry.compress_start + 1]["content"] = "rewritten by a plugin"+ live[entry.compress_start + 2]["content"] = [{"type": "input_text", "text": "structured rewrite"}]+ compressed = cc.compress(live, current_tokens=cc.threshold_tokens + 1)+ assert [c["worker"] for c in cc.calls] == [True]+ assert entry.summary in _summary_row(compressed)["content"]++[email protected]("change", ["message dropped", "rewound", "head moved", "other session"])def test_changed_prefix_never_splices(change):cc = _compressor()msgs = _messages(30)+ for i, msg in enumerate(msgs):+ msg["message_uid"] = f"uid-{i}"entry = _prepare(cc, msgs)live = copy.deepcopy(msgs)- if change == "middle rewritten":- live[entry.compress_start + 1]["content"] = "rewritten"+ if change == "message dropped":+ del live[entry.compress_start + 1:entry.compress_start + 3] # roles still alternate; positions shift+ live[entry.compress_start + 1]["tool_calls"] = [{"id": "c1", "function": {"name": "x"}}]+ elif change == "rewound":+ # A rewind into the window that regrew the same shape: the rows are new messages.+ live[entry.compress_start + 1]["message_uid"] = "uid-after-rewind"elif change == "head moved":cc.compression_count = 1 # head protection decays after a compactionelse:@@ -274,6 +312,9 @@ def test_fresh_summary_paths_ignore_and_drop_the_candidate(kwargs):cc.compress(msgs, current_tokens=cc.threshold_tokens + 1, **kwargs)assert [c["worker"] for c in cc.calls] == [True, False]assert cc.prepared_compaction._entry is None+ # Provider context would be needed by every later compaction too: no more passes paid for and dropped.+ stopped = pc.maybe_prepare(_agent(cc), msgs, origin="test") is None+ assert stopped is ("memory_context" in kwargs)def test_prune_and_blank_echo_drop_do_not_invalidate_the_candidate():@@ -304,51 +345,26 @@ def test_prune_and_blank_echo_drop_do_not_invalidate_the_candidate():assert [c["worker"] for c in cc.calls] == [True], "the candidate must still splice"-def test_fingerprint_survives_a_session_db_round_trip(tmp_path):+def test_identity_survives_a_session_db_round_trip_and_catches_a_rewind(tmp_path):from hermes_state import SessionDBmsgs = _messages(20)- msgs[3]["content"] += " \n" # trailing whitespace the store stripsdb = SessionDB(db_path=tmp_path / "state.db")db.create_session("S1", source="cli")for m in msgs[1:]:db.append_message("S1", role=m["role"], content=m["content"])replayed = [msgs[0]] + db.get_messages_as_conversation("S1")- assert pc.fingerprint(replayed, "S1", 4, 15) == pc.fingerprint(msgs, "S1", 4, 15)- replayed[5]["content"] = "edited"- assert pc.fingerprint(replayed, "S1", 4, 15) != pc.fingerprint(msgs, "S1", 4, 15)+ window = pc._Window("S1", 4, 15, pc.prefix_identities(replayed, 15))+ assert pc._mismatch(window, msgs, "S1", 4, 15) is None, "the live dicts before their first persist"+ assert pc._mismatch(window, replayed, "S1", 4, 15) is None+ rewound = copy.deepcopy(replayed)+ rewound[6]["message_uid"] = "a-new-row"+ assert "different message" in pc._mismatch(window, rewound, "S1", 4, 15)# --------------------------------------------------------------------------- running passes-def test_completed_candidate_splices_while_an_extension_pass_runs(monkeypatch):- cc = _compressor()- 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)- _, _, _, 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_TOKENS), grown, origin="test")- assert running is not None- misfit = pc.PreparedCompaction._misfit-- def publish_mid_take(*args): # the extension finishes while compaction checks the candidate- if not cc.gate.is_set():- cc.gate.set()- running.join(5.0)- return misfit(*args)-- monkeypatch.setattr(pc.PreparedCompaction, "_misfit", staticmethod(publish_mid_take))- compressed = cc.compress(grown, current_tokens=cc.threshold_tokens + 1)- assert first.summary in _summary_row(compressed)["content"]- assert len(cc.calls) == 2 and cc.calls[1]["previous"] == first.body, "the pass was an extension"- assert cc.prepared_compaction._entry is None, "a pass planned before this compaction cannot outlive it"--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 eachstreamed chunk of the pass touches the compacting thread's progress hook (the host's idle watchdog)."""@@ -455,18 +471,25 @@ def test_session_reset_during_the_wait_wakes_it_without_waiting_for_the_pass():@pytest.mark.parametrize("boundary", ["reset", "end", "rebind"])def test_session_boundary_discards_candidate_and_running_pass(boundary):- cc = _compressor()+ def cross(cc, msgs):+ if boundary == "reset":+ cc.on_session_reset()+ elif boundary == "end":+ cc.on_session_end("S1", msgs)+ else: # /resume or /branch onto another session+ cc.bind_session_state(None, "S2")+msgs = _messages(30)- _prepare(cc, msgs)+ completed = _compressor()+ _prepare(completed, msgs)+ cross(completed, msgs)+ assert completed.prepared_compaction._entry is None++ cc = _compressor()cc.gate = threading.Event()- running = pc.maybe_prepare(_agent(cc, _GROWN_TOKENS), _grow(msgs, 14, size=2600), origin="test")+ running = pc.maybe_prepare(_agent(cc), msgs, origin="test")assert running is not None- if boundary == "reset":- cc.on_session_reset()- elif boundary == "end":- cc.on_session_end("S1", msgs)- else: # /resume or /branch onto another session- cc.bind_session_state(None, "S2")+ cross(cc, msgs)cc.gate.set()running.join(5.0)assert cc.prepared_compaction._entry is None and cc.prepared_compaction._pending is None@@ -482,57 +505,17 @@ def test_same_session_rebind_keeps_the_candidate():assert [c["worker"] for c in cc.calls] == [True]-# --------------------------------------------------------------------------- extension, failures+# --------------------------------------------------------------------------- one pass, failures, fallback-def test_small_delta_keeps_the_candidate_without_copying_or_taking_a_slot(monkeypatch):- cc = _compressor()- msgs = _messages(30)- first = _prepare(cc, msgs)- copies, plans, plan = [], [], cc._plan_compaction_window- monkeypatch.setattr(pc.copy, "deepcopy", lambda value, *a: copies.append(value) or value)- monkeypatch.setattr(cc, "_plan_compaction_window", lambda m: plans.append(1) or plan(m))- held = [pc._slots.acquire(blocking=False)] # leave exactly one slot free- try:- assert pc.maybe_prepare(_agent(cc), _grow(msgs, 4), origin="test") is None- assert pc._slots.acquire(blocking=False), "the skip held a slot"- pc._slots.release()- finally:- for ok in held:- if ok:- pc._slots.release()- assert copies == [] and cc.prepared_compaction._entry is first and len(cc.calls) == 1- assert plans == [], "an unchanged prompt size skips re-planning the window on the turn thread"---def test_grown_prompt_with_a_small_window_delta_keeps_the_candidate_and_rearms_the_skip(monkeypatch):- """Prompt growth that landed in the protected tail: the full check keeps the candidate, and the next- tool batch measures growth from that check instead of re-planning again."""+def test_a_held_candidate_starts_no_further_pass_however_far_the_prompt_grows(monkeypatch):cc = _compressor()msgs = _messages(30)first = _prepare(cc, msgs)plans, plan = [], cc._plan_compaction_windowmonkeypatch.setattr(cc, "_plan_compaction_window", lambda m: plans.append(1) or plan(m))- grown = _grow(msgs, 4)- for _ in range(2):- assert pc.maybe_prepare(_agent(cc, _GROWN_TOKENS), grown, origin="test") is None- kept = cc.prepared_compaction._entry- assert plans == [1] and len(cc.calls) == 1- assert (kept.compress_end, kept.summary, kept.prompt_tokens) == (first.compress_end, first.summary, _GROWN_TOKENS)---def test_extension_pass_summarises_only_the_delta_on_top_of_the_previous_body():- cc = _compressor()- msgs = _messages(30)- first = _prepare(cc, msgs)- grown = _grow(msgs, 14, size=2600)- second = _prepare(cc, grown, _GROWN_TOKENS)- call = cc.calls[1]- assert call["previous"] == first.body- assert call["n_turns"] == second.compress_end - first.compress_end- assert call["first"] == grown[first.compress_end]["content"][:10]- cc.compress(grown, current_tokens=cc.threshold_tokens + 1)- assert len(cc.calls) == 2 and cc._previous_summary == second.body+ assert pc.maybe_prepare(_agent(cc, cc.threshold_tokens - 1), _grow(msgs, 30, size=2600), origin="test") is None+ assert plans == [] and len(cc.calls) == 1 and cc.prepared_compaction._entry is firstdef test_failed_pass_backs_off_without_touching_live_failure_state(tmp_path, monkeypatch):@@ -544,23 +527,54 @@ def test_failed_pass_backs_off_without_touching_live_failure_state(tmp_path, moncc = _compressor()cc.bind_session_state(db, "S1")msgs = _messages(30)- first = _prepare(cc, msgs)monkeypatch.setattr(_StubCompressor, "_generate_summary", module.ContextCompressor._generate_summary)call = MagicMock(side_effect=RuntimeError("No LLM provider configured"))monkeypatch.setattr(module, "call_llm", call)- grown = _grow(msgs, 14, size=2600)- thread = pc.maybe_prepare(_agent(cc, _GROWN_TOKENS), grown, origin="test")+ thread = pc.maybe_prepare(_agent(cc), msgs, origin="test")thread.join(5.0)assert call.call_count == 1- assert cc.prepared_compaction._entry is first, "a failed extension keeps the previous candidate"+ assert cc.prepared_compaction._entry is Noneassert cc._summary_failure_cooldown_until == 0.0 and cc._last_summary_error is Noneassert db.get_compression_failure_cooldown("S1") is None- assert pc.maybe_prepare(_agent(cc, _GROWN_TOKENS), grown, origin="test") is None, "backs off"+ assert pc.maybe_prepare(_agent(cc), msgs, origin="test") is None, "backs off"assert call.call_count == 1+def test_splice_carries_the_passs_main_model_fallback_and_call_telemetry(monkeypatch):+ """The summary model failed inside the pass and the main model answered: the live compressor ends up+ as the inline call would leave it (sticky main-model route, the user warning's source, the call's+ telemetry), not as if the broken summary model had worked."""+ import agent.context_compressor as module++ cc = _compressor()+ cc.summary_model = "broken/summary-model"+ msgs = _messages(30)+ monkeypatch.setattr(_StubCompressor, "_generate_summary", module.ContextCompressor._generate_summary)++ calls = []++ def call_llm(**kwargs):+ calls.append(threading.current_thread().name)+ if len(calls) == 1:+ raise RuntimeError("model not found") # the configured summary model is broken+ message = SimpleNamespace(content="Recovered summary.", reasoning_content=None, reasoning=None)+ return SimpleNamespace(choices=[SimpleNamespace(message=message, finish_reason="stop")])++ monkeypatch.setattr(module, "call_llm", call_llm)+ _prepare(cc, msgs)+ cc.compress(msgs, current_tokens=cc.threshold_tokens + 1)++ assert calls == ["compaction-prepare"] * 2, "summary model failed, main model answered, both in the pass"+ assert cc.summary_model == "", "later compactions go straight to the main model, as inline"+ assert cc._last_aux_model_failure_model == "broken/summary-model"+ telemetry = cc._last_compression_telemetry+ assert telemetry["prepared_summary"] is True and telemetry["fallback_used"] is True+ assert telemetry["aux_model"] and telemetry["aux_call_duration_ms"] is not None+ assert telemetry["method"] == "aux_fallback_main"++# --------------------------------------------------------------------------- the real turn loopdiff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.mdindex ea29ab86616..b346d1651fa 100644--- a/website/docs/developer-guide/context-compression-and-caching.md+++ b/website/docs/developer-guide/context-compression-and-caching.md@@ -326,7 +326,7 @@ auxiliary:| `codex_responses_native` | `false` | bool | Opt in to OpenAI's server-side compaction on the Responses API. Engages for gpt-5.6-family models on the direct OpenAI API or a ChatGPT Codex subscription, and `gpt-6-astra` (including its `-900k` picker alias) on official Codex OAuth (see below) || `codex_responses_compact_threshold` | `null` | `null` or positive integer | Server-side compaction trigger, read **only when `codex_responses_native: true`** — it never changes when local compression fires; the local trigger is `threshold` (ratio) capped by `threshold_tokens`. `null` follows the resolved local compression trigger with an 8,192 token safety margin. A positive integer remains absolute and only clamps downward when required. Invalid values use automatic behavior. Automatic mode falls back to `200000` when no usable local trigger exists || `in_place` | `true` | bool | Compact on the same session id instead of rotating to a new one (see below) |-| `prepare_ahead` | `false` | bool | Opt-in: near the trigger, write the next summary in the background and splice it at the next automatic compaction when the summarized messages are unchanged (see below) |+| `prepare_ahead` | `false` | bool | Opt-in: near the trigger, write the next summary in the background and splice it at the next automatic compaction when it still covers the same messages (see below) |### In-place compaction (single stable session id)@@ -676,20 +676,26 @@ it is the handoff the transcript now carries.With `compression.prepare_ahead: true` (read at agent construction, so it takes effect on the nextsession or gateway agent rebuild), `agent/prepared_compaction.py` writes the next summary beforethe 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, 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), 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.+(`threshold_tokens`) below it, the turn loop starts one background pass, before a tool batch runs or+at turn end. Turn-end passes are skipped for cron runs and delegated children, whose sessions end+with the turn. 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. There is one pass+per compaction: while a summary is held, no further pass starts, however much the prompt grows.++At the next automatic threshold compaction `compress()` splices the completed summary when it still+covers the same messages: same session, unchanged head boundary, a candidate boundary no later than+the fresh tail cut, and the same message structure up to that boundary (role, tool call ids and+names, tool result ids, and the durable `message_uid` where both sides carry one). Message text,+tool arguments and tool bodies are not compared: the no-LLM prune and plugins rewrite them in place,+and the summary still describes the same messages. A dropped or inserted message, or a rewind or+branch into the window (new `message_uid`s), is a miss. The summary then covers+`[head, candidate boundary)` and every later message, however many arrived after the pass started, is+kept as tail; tail rules such as lean-mode tool stubbing still apply to them. Summary placement and+alternation handling are the normal Phase 4 assembly. The splice leaves the live compressor as the+inline call would have: a pass that recovered on the main model after the summary model failed hands+over that fallback (later compactions use the main model, and the user sees the broken-model+warning), and the attempt telemetry carries the pass's aux call with `prepared_summary: true`.When no completed candidate fits but the pass still running would, compaction waits for that passinstead of writing the same summary again. Each streamed chunk of the pass touches the waiting@@ -700,7 +706,8 @@ cancellation, or when a session boundary discards the pass, and compaction thenEverything else runs inline exactly as without the flag: no candidate, a candidate or running passthat 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+compactions where a memory provider contributes summary context (the first such compaction also stops+further passes for that agent, since each would be thrown away). A running pass overtaken by compaction or a sessionboundary (including a rebind to another session id on `/resume` or `/branch`) is cancelled: itcannot publish, and its summary stream is closed rather than billed to completion. 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 agenteviction 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.mdindex 4bb7767ba1e..0cdc237de6a 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 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.+`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. One summary is prepared per compaction. When automatic compaction fires and the summarized messages are still the same messages (text edits by plugins are fine; a dropped message or a rewind is not), the prepared summary is used instead of a summary call at that moment, and every message newer than it stays outside it, in the 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 an auxiliary summary call that may go unused, and it does not apply to manual `/compress`, plugin context engines, or native/app-server compaction. With a memory provider that adds context to compaction summaries it switches itself off after the first compaction, since every prepared summary would be discarded.`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.