Skip to content

The agent that grows with you

feat(agent): opt-in prepared compaction (compression.prepare_ahead)

Hugo Alves Pereira32a636bc8d26
diff --git a/agent/agent_init.py b/agent/agent_init.py
index b7e66eedd83..04c8a0abe3e 100644
--- a/agent/agent_init.py
+++ b/agent/agent_init.py
@@ -1554,6 +1554,7 @@ def _parse_compression_config(agent, _agent_cfg) -> CompressionSettings:
codex_responses_native=responses_native,
codex_responses_compact_threshold=compact_threshold,
idle_compact_after_seconds=idle_compact_after_seconds,
+ prepare_ahead=is_truthy_value(cfg.get("prepare_ahead"), default=False),
)
@@ -1994,6 +1995,9 @@ def _build_context_engine(agent, _agent_cfg, cs, _custom_providers, _effective_c
):
if hasattr(_cc, _attr):
setattr(_cc, _attr, _value)
+ if cs.prepare_ahead and isinstance(_cc, ContextCompressor):
+ from agent.prepared_compaction import PreparedCompaction
+ _cc.prepared_compaction = PreparedCompaction()
agent.compression_checkpoint_required = cs.checkpoint_required
from agent.conversation_compression_checkpoint import _warn_checkpoint_required_without_capable_provider
_warn_checkpoint_required_without_capable_provider(agent)
diff --git a/agent/context_compressor.py b/agent/context_compressor.py
index 3fbf176fd5c..4c4170bb151 100644
--- a/agent/context_compressor.py
+++ b/agent/context_compressor.py
@@ -2152,6 +2152,9 @@ class ContextCompressor(
"""Default context engine: prune tool results, protect head/tail, summarize the middle
with an LLM, and iteratively update the previous summary on later compactions."""
+ # agent/prepared_compaction.PreparedCompaction when compression.prepare_ahead is on, else None.
+ prepared_compaction: Any = None
+
@property
def name(self) -> str:
return "compressor"
@@ -2278,6 +2281,8 @@ class ContextCompressor(
def _reset_session_compaction_state(self) -> None:
"""Shared per-session reset for /new, /reset and session end."""
+ if self.prepared_compaction is not None:
+ self.prepared_compaction.discard("session boundary")
# A handoff may carry role="user" only for alternation, so role alone can't prove a human turn existed.
self._previous_summary = self._summary_has_user_turn = self._last_summary_error = None
self._last_aux_model_failure_error = self._last_aux_model_failure_model = None
@@ -3936,17 +3941,20 @@ Summary generation was unavailable, so this is a best-effort deterministic fallb
from agent.conversation_compression import _raise_if_stale_attempt
_raise_if_stale_attempt(self)
- self._previous_summary = summary
- self._clear_compression_failure_cooldown()
- self._summary_model_fallen_back = False
- self._last_summary_error = None
- self._clear_terminal_summary_failures()
- # The provider answered a summary again: the sustained-overload budget restarts (#123167).
- self._reset_consecutive_overload_aborts()
+ self._record_summary_success(summary)
return self._with_summary_prefix(summary)
except Exception as e:
return self._on_summary_failure(e, turns_to_summarize, focus_topic, memory_context)
+ def _record_summary_success(self, summary: str) -> None:
+ """A healthy summary becomes the iterative base and clears the failure state."""
+ self._previous_summary = summary
+ self._clear_compression_failure_cooldown()
+ self._summary_model_fallen_back = False
+ self._last_summary_error = None
+ for flag, _class, _msg in _TERMINAL_SUMMARY_FAILURES:
+ setattr(self, flag, False)
+
def _build_summary_prompt(
self, content_to_summarize: str, summary_budget: int, focus_topic: Optional[str],
memory_context: str, has_user_turn: bool,
@@ -5506,6 +5514,14 @@ Write only the summary body. Do not include any preamble or prefix."""
n_messages,
)
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).
+ 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()),
+ )
+ if prepared:
+ compress_end = prepared.compress_end
turns_to_summarize = messages[compress_start:compress_end]
# Lean mode demotes stale tail tool results before summary generation so stubs exist even if it aborts.
if getattr(self, "tail_mode", "lean") == "lean":
@@ -5537,12 +5553,16 @@ Write only the summary body. Do not include any preamble or prefix."""
from agent.conversation_compression import _raise_if_stale_attempt
_raise_if_stale_attempt(self)
- feasibility_skip = not force and (
+ feasibility_skip = not (force or prepared) and (
self._fallback_streak_skip(telemetry)
or self._feasibility_skip(telemetry, turns_to_summarize, compress_start, compress_end)
)
summary = None # pre-LLM summary skip (feasibility or benched model): no LLM call; Phase 4 inserts the deterministic fallback
- if not feasibility_skip:
+ if 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
+ elif not feasibility_skip:
summary = self._summarize_window(
messages, turns_to_summarize, scan, focus_topic, memory_context, bypass_cooldown,
)
diff --git a/agent/prepared_compaction.py b/agent/prepared_compaction.py
new file mode 100644
index 00000000000..e199b7e354e
--- /dev/null
+++ b/agent/prepared_compaction.py
@@ -0,0 +1,296 @@
+"""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.
+
+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
+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.
+
+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.
+
+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.
+"""
+from __future__ import annotations
+
+import copy
+import hashlib
+import logging
+import threading
+import time
+from dataclasses import dataclass
+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.
+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 summariser calls in flight across the process.
+_slots = threading.BoundedSemaphore(2)
+
+
+@dataclass(frozen=True)
+class PreparedSummary:
+ compress_start: int
+ compress_end: int
+ fingerprint: str
+ summary: str # prefixed handoff text, exactly as ``_generate_summary`` returns it
+ body: str # bare body the next compaction extends iteratively
+
+
+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."""
+ if not isinstance(msg, dict):
+ return "?"
+ from agent.memory_manager import sanitize_context
+
+ role = 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()]
+ 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)
+
+
+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 _mismatch(
+ entry: PreparedSummary, 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"
+ return None
+
+
+def _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)."""
+ worker = copy.copy(compressor)
+ worker._session_db = None
+ worker._active_compression_telemetry = worker._last_compression_telemetry = None
+ worker._compression_cancelled_check = None
+ return worker
+
+
+class PreparedCompaction:
+ """Prepared-summary state owned by one ``ContextCompressor``."""
+
+ 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._retry_after = 0.0 # monotonic; set by a failed pass
+
+ def discard(self, reason: str) -> None:
+ """Drop the candidate; a running pass may finish but can no longer publish."""
+ with self._lock:
+ entry, self._entry, self._pending = self._entry, None, None
+ if entry is not None:
+ logger.info(
+ "prepared compaction: dropped window=%d-%d reason=%s", entry.compress_start, entry.compress_end, reason,
+ )
+
+ def take(
+ 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 None.
+ 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 not None:
+ if entry is not None or running:
+ logger.info("prepared compaction: splice miss reason=%s", reason)
+ return None
+ logger.info(
+ "prepared compaction: splice hit window=%d-%d (fresh cut %d)", entry.compress_start, entry.compress_end, end,
+ )
+ return entry
+
+ 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
+ if (
+ getattr(agent, "api_mode", None) == "codex_app_server"
+ or getattr(agent, "codex_responses_native_compaction", False)
+ or getattr(compressor, "_micro_compact_enabled", False)
+ ):
+ return True # another path owns compaction, or history is rewritten every turn
+ 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)
+ if tokens <= 0 or compressor.threshold_tokens <= 0 or tokens < band_floor:
+ return True
+ now = time.monotonic()
+ 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,
+ ) -> Optional[threading.Thread]:
+ """Start a pass when the next compaction is near; returns the started thread. Never raises."""
+ token: Optional[object] = None
+ try:
+ if self._blocked(agent, compressor):
+ return None
+ with self._lock:
+ if self._pending is not None:
+ return None
+ completed = self._entry
+ working, _, 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)
+ return None
+ extend = completed
+ worker = _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 None
+ focus = worker._derive_auto_focus_topic(working)
+ window_fingerprint = fingerprint(working, session_id, start, end)
+ # Never queue threads that retain transcripts while every slot is busy.
+ if not _slots.acquire(blocking=False):
+ return None
+ with self._lock:
+ if self._pending is not None:
+ _slots.release()
+ return None
+ token = self._pending = object()
+ 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),
+ )
+ thread.start()
+ return thread
+ except Exception:
+ if token is not None:
+ with self._lock:
+ if self._pending is token:
+ self._pending = None
+ _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],
+ ) -> None:
+ from agent.thread_scoped_output import thread_scoped_silence
+
+ entry: Optional[PreparedSummary] = None
+ started = 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,
+ )
+ with thread_scoped_silence():
+ summary = worker._generate_summary(turns, focus_topic=focus)
+ if summary:
+ entry = PreparedSummary(start, end, window_fingerprint, summary, worker._previous_summary)
+ logger.info("prepared compaction: pass completed window=%d-%d in %.1fs",
+ start, 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")
+ except Exception:
+ logger.warning("prepared compaction: pass crashed", exc_info=True)
+ finally:
+ with self._lock:
+ if self._pending is token:
+ self._pending = None
+ if entry is not None:
+ self._entry = entry
+ else:
+ self._retry_after = max(
+ worker._summary_failure_cooldown_until, time.monotonic() + _FAILED_PASS_BACKOFF_SECONDS,
+ )
+ _slots.release()
+
+
+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)
+ return state.maybe_prepare(agent, compressor, messages, origin) if state is not None else None
diff --git a/agent/turn_finalizer.py b/agent/turn_finalizer.py
index d41b0f06f71..8890e6040fb 100644
--- a/agent/turn_finalizer.py
+++ b/agent/turn_finalizer.py
@@ -858,6 +858,11 @@ def finalize_turn(
review_skills=_should_review_skills,
)
+ # Opt-in (compression.prepare_ahead): near the trigger, write the next compaction summary
+ # between turns. No-op otherwise; never raises.
+ from agent.prepared_compaction import maybe_prepare
+ maybe_prepare(agent, messages, origin="turn-end")
+
# Memory provider on_session_end()/shutdown_all() are NOT called here:
# run_conversation() runs once per message; CLI/gateway own session-end cleanup.
if not getattr(agent, "_persist_disabled", False):
diff --git a/agent/turn_tool_round.py b/agent/turn_tool_round.py
index 86ab0ad4e94..0afc7ab88dd 100644
--- a/agent/turn_tool_round.py
+++ b/agent/turn_tool_round.py
@@ -163,6 +163,11 @@ def run_tool_round(
with suppress(Exception):
agent.stream_delta_callback(None)
+ # Opt-in (compression.prepare_ahead): when this response put the session near the trigger,
+ # write the next compaction summary while the tools run. No-op otherwise; never raises.
+ from agent.prepared_compaction import maybe_prepare
+ maybe_prepare(agent, messages, origin="tool-batch")
+
agent._execute_tool_calls(assistant_message, messages, effective_task_id, api_call_count)
from hermes_cli.observability.shared_metrics_harness import finish_tool_round
diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py
index 5fd79bdf2ef..69836fd8568 100644
--- a/hermes_cli/config_defaults.py
+++ b/hermes_cli/config_defaults.py
@@ -693,6 +693,10 @@ DEFAULT_CONFIG = {
# 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: near the trigger, write the next compaction summary in the background (during
+ # tool execution and between turns). Automatic compaction splices it only when the
+ # summarized messages are unchanged; otherwise it summarizes inline as usual.
+ "prepare_ahead": False,
},
# Anthropic prompt caching (Claude via OpenRouter or native API). cache_ttl: "5m" | "1h" | "auto"
# (auto = 1h for human-paced sessions — cli/tui/desktop/messaging — and 5m for subagent, cron,
diff --git a/tests/agent/test_prepared_compaction.py b/tests/agent/test_prepared_compaction.py
new file mode 100644
index 00000000000..ab94c2fd5d8
--- /dev/null
+++ b/tests/agent/test_prepared_compaction.py
@@ -0,0 +1,480 @@
+"""Opt-in prepared compaction (``compression.prepare_ahead``, agent/prepared_compaction.py).
+
+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 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;
+* 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.
+"""
+from __future__ import annotations
+
+import copy
+import threading
+import time
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agent import prepared_compaction as pc
+from agent.context_compressor import COMPRESSED_SUMMARY_METADATA_KEY, ContextCompressor
+from agent.prepared_compaction import PreparedCompaction
+
+
+class _StubCompressor(ContextCompressor):
+ """Records every summariser call; ``gate`` holds background passes only (shared with the worker copy)."""
+
+ def _generate_summary(self, turns_to_summarize, focus_topic=None, memory_context="", bypass_cooldown=False):
+ from hermes_constants import get_hermes_home
+
+ worker = threading.current_thread().name == "compaction-prepare"
+ if worker and self.gate is not None:
+ assert self.gate.wait(5.0), "pass never released"
+ self.calls.append({
+ "worker": worker,
+ "n_turns": len(turns_to_summarize),
+ "first": turns_to_summarize[0].get("content", "")[:10],
+ "previous": self._previous_summary,
+ "focus": focus_topic,
+ "home": str(get_hermes_home()),
+ })
+ body = f"Summary v{len(self.calls)} of {len(turns_to_summarize)} turns."
+ self._previous_summary = body
+ return self._with_summary_prefix(body)
+
+
+def _compressor(*, enabled: bool = True, session_id: str = "S1") -> _StubCompressor:
+ with patch("agent.context_compressor.get_model_context_length", return_value=40960):
+ cc = _StubCompressor(model="test/model", protect_first_n=3, protect_last_n=5, quiet_mode=True)
+ cc.context_length = 40960
+ cc.threshold_tokens = 20000
+ cc.tail_token_budget = 2500
+ cc.calls, cc.gate = [], None
+ cc._session_id = session_id
+ if enabled:
+ cc.prepared_compaction = PreparedCompaction()
+ return cc
+
+
+def _messages(n: int, size: int = 1200, tag: str = "m") -> list:
+ msgs = [{"role": "system", "content": "sys"}]
+ for i in range(n):
+ msgs.append({"role": "user" if i % 2 == 0 else "assistant", "content": f"{tag}{i} " + "z" * size})
+ return msgs
+
+
+def _grow(msgs: list, n: int, size: int = 1200, tag: str = "new") -> list:
+ return msgs + _messages(n, size=size, tag=tag)[1:]
+
+
+def _agent(cc, tokens: int = 19500):
+ cc.last_prompt_tokens = tokens
+ return 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")
+ assert thread is not None, "expected a pass to start"
+ thread.join(5.0)
+ entry = cc.prepared_compaction._entry
+ assert entry is not None
+ return entry
+
+
+def _summary_row(compressed: list) -> dict:
+ rows = [m for m in compressed if m.get(COMPRESSED_SUMMARY_METADATA_KEY)]
+ assert len(rows) == 1
+ return rows[0]
+
+
+def _wait_until(predicate, timeout: float = 5.0) -> bool:
+ deadline = time.monotonic() + timeout
+ while time.monotonic() < deadline:
+ if predicate():
+ return True
+ time.sleep(0.01)
+ return predicate()
+
+
+# --------------------------------------------------------------------------- default off
+
+
+def test_flag_off_leaves_compression_inline_and_stateless():
+ cc = _compressor(enabled=False)
+ msgs = _messages(30)
+ assert pc.maybe_prepare(_agent(cc), msgs, origin="test") is None
+ compressed = cc.compress(msgs, current_tokens=cc.threshold_tokens + 1)
+ assert [c["worker"] for c in cc.calls] == [False]
+ assert cc.prepared_compaction is None
+ assert "Summary v1" in _summary_row(compressed)["content"]
+
+
+def test_config_flag_reaches_the_compressor_through_the_loader(tmp_path, monkeypatch):
+ from agent.agent_init import _parse_compression_config
+ from hermes_cli.config import DEFAULT_CONFIG, load_config_readonly
+
+ agent = SimpleNamespace(model="m", provider="openrouter", api_mode="chat_completions", quiet_mode=True)
+ assert DEFAULT_CONFIG["compression"]["prepare_ahead"] is False
+ assert _parse_compression_config(agent, load_config_readonly()).prepare_ahead is False
+
+ home = tmp_path / "profile"
+ home.mkdir()
+ (home / "config.yaml").write_text("compression:\n prepare_ahead: true\n", encoding="utf-8")
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ assert _parse_compression_config(agent, load_config_readonly()).prepare_ahead is True
+
+
+# --------------------------------------------------------------------------- the pass
+
+
+def test_pass_leaves_live_transcript_and_compressor_untouched():
+ cc = _compressor()
+ msgs = _messages(30)
+ before = copy.deepcopy(msgs)
+ entry = _prepare(cc, msgs)
+ 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)
+ assert (entry.compress_start, entry.compress_end) == (start, end)
+ assert entry.body == f"Summary v1 of {end - start} turns."
+
+
+ lambda a, cc: setattr(cc, "last_prompt_tokens", 20000 - int(40960 * pc.PREPARE_BAND_RATIO) - 1),
+ 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
+ lambda a, cc: setattr(a, "api_mode", "codex_app_server"),
+ 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"])
+def test_gates_start_no_pass(setup):
+ cc = _compressor()
+ agent = _agent(cc)
+ setup(agent, cc)
+ assert pc.maybe_prepare(agent, _messages(30), origin="test") is None
+ assert cc.calls == []
+
+
+def test_pass_runs_under_the_callers_profile_scope(tmp_path):
+ from hermes_constants import reset_hermes_home_override, set_hermes_home_override
+
+ homes = [tmp_path / "a", tmp_path / "b", tmp_path / "a"]
+ compressors = []
+ for home in homes:
+ cc = _compressor()
+ token = set_hermes_home_override(home)
+ try:
+ _prepare(cc, _messages(30))
+ finally:
+ reset_hermes_home_override(token)
+ compressors.append(cc)
+ assert [cc.calls[0]["home"] for cc in compressors] == [str(h) for h in homes]
+
+
+# --------------------------------------------------------------------------- the splice
+
+
+def test_append_only_growth_splices_at_the_candidate_boundary_keeping_newer_messages():
+ cc = _compressor()
+ msgs = _messages(30)
+ entry = _prepare(cc, msgs)
+ later = _grow(msgs, 8)
+ assert cc._plan_compaction_window(later)[3] > entry.compress_end # a fresh plan would cut later
+
+ compressed = cc.compress(later, current_tokens=cc.threshold_tokens + 1)
+
+ assert [c["worker"] for c in cc.calls] == [True], "no summariser call on the turn"
+ assert entry.summary in _summary_row(compressed)["content"]
+ kept = later[entry.compress_end:]
+ for original, row in zip(kept, compressed[-len(kept):]):
+ assert original["content"] in row["content"]
+ assert cc._previous_summary == entry.body
+ assert cc.prepared_compaction._entry is None
+
+
[email protected]("change", ["middle rewritten", "head moved", "other session"])
+def test_changed_prefix_never_splices(change):
+ cc = _compressor()
+ msgs = _messages(30)
+ entry = _prepare(cc, msgs)
+ live = copy.deepcopy(msgs)
+ if change == "middle rewritten":
+ live[entry.compress_start + 1]["content"] = "rewritten"
+ elif change == "head moved":
+ cc.compression_count = 1 # head protection decays after a compaction
+ else:
+ cc._session_id = "S2"
+ compressed = cc.compress(live, current_tokens=cc.threshold_tokens + 1)
+ assert [c["worker"] for c in cc.calls] == [True, False], "inline summary expected"
+ assert "Summary v2" in _summary_row(compressed)["content"]
+
+
[email protected]("kwargs", [
+ {"force": True}, {"focus_topic": "auth bug"}, {"bypass_cooldown": True}, {"memory_context": "provider note"},
+], ids=["manual", "focus", "overflow-recovery", "memory-context"])
+def test_fresh_summary_paths_ignore_and_drop_the_candidate(kwargs):
+ cc = _compressor()
+ msgs = _messages(30)
+ _prepare(cc, msgs)
+ 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
+
+
+def test_prune_and_blank_echo_drop_do_not_invalidate_the_candidate():
+ cc = _compressor()
+ msgs = [{"role": "system", "content": "sys"}]
+ for i in range(12): # tool rounds whose bodies and arguments the prune rewrites
+ msgs += [
+ {"role": "user", "content": f"u{i} " + "q" * 400},
+ {"role": "assistant", "content": f"a{i}", "tool_calls": [{
+ "id": f"c{i}", "type": "function",
+ "function": {"name": "read_file", "arguments": '{"path": "%s"}' % ("p" * 900)},
+ }]},
+ {"role": "tool", "tool_call_id": f"c{i}", "name": "read_file", "content": f"r{i} " + "r" * 3000},
+ {"role": "assistant", "content": f"done {i} " + "d" * 400},
+ ]
+ msgs += [{"role": "user", "content": "latest ask"}, {"role": "user", "content": " "},
+ {"role": "assistant", "content": "working on it"}]
+ working, pruned, _, _ = cc._plan_compaction_window(msgs)
+ assert pruned > 0 and len(working) == len(msgs) - 1, "prune ran and the trailing blank echo was dropped"
+ entry = _prepare(cc, msgs)
+
+ live = _grow(msgs, 4) # a newer user turn: the old echo is no longer trailing, so it stays
+ live_working, live_pruned, start, end = cc._plan_compaction_window(live)
+ assert len(live_working) == len(live) and live_pruned >= pruned
+ assert start == entry.compress_start and end >= entry.compress_end
+
+ cc.compress(live, current_tokens=cc.threshold_tokens + 1)
+ 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):
+ from hermes_state import SessionDB
+
+ msgs = _messages(20)
+ msgs[3]["content"] += " \n" # trailing whitespace the store strips
+ db = 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)
+
+
+# --------------------------------------------------------------------------- running passes
+
+
+def test_completed_candidate_splices_while_an_extension_pass_runs():
+ cc = _compressor()
+ msgs = _messages(30)
+ first = _prepare(cc, msgs)
+ grown = _grow(msgs, 14, size=2600) # clears MIN_EXTENSION_DELTA_TOKENS
+ cc.gate = threading.Event()
+ running = pc.maybe_prepare(_agent(cc), grown, origin="test")
+ assert running is not None
+
+ started = time.monotonic()
+ compressed = cc.compress(grown, current_tokens=cc.threshold_tokens + 1)
+ assert time.monotonic() - started < 2.0, "must not wait for the running pass"
+ assert first.summary in _summary_row(compressed)["content"]
+
+ cc.gate.set()
+ running.join(5.0)
+ assert len(cc.calls) == 2 and cc.calls[1]["previous"] == first.body, "the pass was an extension"
+ assert cc.prepared_compaction._entry is None, "an overtaken pass cannot publish"
+
+
+def test_unfinished_pass_is_not_waited_on_and_cannot_publish_later():
+ 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"
+
+ cc.gate.set()
+ running.join(5.0)
+ assert cc.prepared_compaction._entry is None
+
+
[email protected]("boundary", ["reset", "end"])
+def test_session_boundary_discards_candidate_and_running_pass(boundary):
+ cc = _compressor()
+ msgs = _messages(30)
+ _prepare(cc, msgs)
+ cc.gate = threading.Event()
+ running = pc.maybe_prepare(_agent(cc), _grow(msgs, 14, size=2600), origin="test")
+ assert running is not None
+ if boundary == "reset":
+ cc.on_session_reset()
+ else:
+ cc.on_session_end("S1", msgs)
+ cc.gate.set()
+ running.join(5.0)
+ assert cc.prepared_compaction._entry is None and cc.prepared_compaction._pending is None
+
+
+# --------------------------------------------------------------------------- extension, failures
+
+
+def test_small_delta_keeps_the_candidate_without_copying_or_taking_a_slot(monkeypatch):
+ cc = _compressor()
+ msgs = _messages(30)
+ first = _prepare(cc, msgs)
+ copies = []
+ monkeypatch.setattr(pc.copy, "deepcopy", lambda value, *a: copies.append(value) or value)
+ 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
+
+
+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)
+ 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
+
+
+def test_failed_pass_backs_off_without_touching_live_failure_state(tmp_path, monkeypatch):
+ from hermes_state import SessionDB
+ import agent.context_compressor as module
+
+ db = SessionDB(db_path=tmp_path / "state.db")
+ db.create_session("S1", source="cli")
+ cc = _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, 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._summary_failure_cooldown_until == 0.0 and cc._last_summary_error is None
+ assert db.get_compression_failure_cooldown("S1") is None
+ assert pc.maybe_prepare(_agent(cc), grown, origin="test") is None, "backs off"
+ assert call.call_count == 1
+
+
+# --------------------------------------------------------------------------- the real turn loop
+
+
+def _loop_response(*, prompt_tokens: int, tool_call_id: str | None = None, content=None):
+ tool_calls = [SimpleNamespace(
+ id=tool_call_id, type="function", function=SimpleNamespace(name="web_search", arguments='{"query": "q"}'),
+ )] if tool_call_id else None
+ msg = SimpleNamespace(content=content, tool_calls=tool_calls, reasoning_content=None, reasoning=None)
+ resp = SimpleNamespace(
+ choices=[SimpleNamespace(message=msg, finish_reason="tool_calls" if tool_calls else "stop")], model="test/model",
+ )
+ resp.usage = SimpleNamespace(prompt_tokens=prompt_tokens, completion_tokens=50, total_tokens=prompt_tokens + 50)
+ return resp
+
+
[email protected]("prepare_ahead", [True, False])
+def test_turn_that_crosses_the_trigger_splices_the_summary_prepared_during_its_tools(prepare_ahead):
+ """Real run_conversation with the provider and tool boundaries mocked; config via the real loader.
+
+ Response 1 lands in the band: with the flag, the pass runs while that batch's tool executes.
+ Response 2 crosses the trigger, so the loop compacts after the second batch: a splice with the
+ flag (and no second pass), an inline summary without it.
+ """
+ import os
+ from pathlib import Path
+
+ from run_agent import AIAgent
+
+ if prepare_ahead:
+ Path(os.environ["HERMES_HOME"], "config.yaml").write_text(
+ "compression:\n prepare_ahead: true\n", encoding="utf-8",
+ )
+ tool_defs = [{"type": "function", "function": {
+ "name": "web_search", "description": "search", "parameters": {"type": "object", "properties": {}},
+ }}]
+ with (
+ patch("model_tools.get_tool_definitions", return_value=tool_defs),
+ patch("model_tools.check_toolset_requirements", return_value={}),
+ patch("agent.process_bootstrap.OpenAI"),
+ ):
+ agent = AIAgent(api_key="test-key-1234567890", base_url="https://openrouter.ai/api/v1",
+ quiet_mode=True, skip_context_files=True, skip_memory=True)
+ agent.client = MagicMock()
+ agent._cached_system_prompt = "You are helpful."
+ agent._use_prompt_caching = False
+ agent.save_trajectories = False
+ 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)
+
+ summaries, tool_started = [], threading.Event()
+
+ def summarise(turns, focus_topic=None, **_):
+ on_worker = threading.current_thread().name == "compaction-prepare"
+ if on_worker: # the pass is meant to overlap the tool
+ assert tool_started.wait(5.0), "no tool ran while the pass was pending"
+ summaries.append(on_worker)
+ return cc._with_summary_prefix(f"Summary of {len(turns)} turns.")
+
+ cc._generate_summary = summarise
+ pass_during_tool = []
+
+ def run_tool(*_a, **_k):
+ state = cc.prepared_compaction
+ pass_during_tool.append(state is not None and state._pending is not None)
+ tool_started.set()
+ if state is not None:
+ assert _wait_until(lambda: state._pending is None)
+ return '{"ok": true}'
+
+ agent.client.chat.completions.create.side_effect = [
+ _loop_response(prompt_tokens=band_floor + 1000, tool_call_id="c1"),
+ _loop_response(prompt_tokens=cc.threshold_tokens + 1000, tool_call_id="c2"),
+ _loop_response(prompt_tokens=6000, content="done"),
+ ]
+ with (
+ patch("model_tools.handle_function_call", side_effect=run_tool),
+ patch.object(agent, "_persist_session"),
+ patch.object(agent, "_save_trajectory"),
+ patch.object(agent, "_cleanup_task_resources"),
+ ):
+ result = agent.run_conversation("continue", conversation_history=_messages(30)[1:])
+
+ assert result["completed"] is True and result["final_response"] == "done"
+ assert len([m for m in result["messages"] if m.get(COMPRESSED_SUMMARY_METADATA_KEY)]) == 1
+ assert pass_during_tool == [prepare_ahead, False]
+ assert summaries == [prepare_ahead], "one summariser call: on the worker with the flag, inline without"
diff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.md
index 6dd5aea303f..159b13c49ed 100644
--- a/website/docs/developer-guide/context-compression-and-caching.md
+++ b/website/docs/developer-guide/context-compression-and-caching.md
@@ -297,6 +297,7 @@ compression:
codex_responses_native: false # Opt-in server compaction: gpt-5.6 on OpenAI/Codex; Astra on Codex OAuth
codex_responses_compact_threshold: null # Server compaction trigger; only used when codex_responses_native: true
in_place: true # Compact on the same session id, no rotation (default: true)
+ prepare_ahead: false # Opt-in: prepare the next summary in the background (default: false)
# Summarization model/provider configured under auxiliary:
auxiliary:
@@ -325,6 +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) |
### In-place compaction (single stable session id)
@@ -669,6 +671,33 @@ The `_previous_summary` field on the compressor instance stores the last summary
text for this purpose. A deterministic fallback summary is stored there too, since
it is the handoff the transcript now carries.
+### Prepared compaction (opt-in)
+
+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
+`_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
+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.
+
+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
+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.
+
## Before/After Example
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 8c64bd991a1..22fab6d3a02 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -1028,6 +1028,7 @@ compression:
protect_first_n: 3 # Non-system head messages pinned across compactions (0 = pin nothing)
in_place: true # Compact on the same session id (no rotation) — see below
idle_compact_after_seconds: 0 # Opt-in idle compaction (0 = disabled) — see below
+ prepare_ahead: false # Opt-in: prepare the next summary in the background — see below
hygiene_hard_message_limit: 5000 # Gateway safety valve — see below
hygiene_timeout_seconds: 30 # Max seconds of NO summary-model output before hygiene compression is cut off
hygiene_total_ceiling_seconds: 600 # Absolute cap on the hygiene wait even while tokens are still streaming
@@ -1079,6 +1080,8 @@ 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.
+
`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.
:::tip Gateway hot-reload of compression and context length