Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

fix(compaction): keep the trigger honest when the summary is dropped

蓝色天空83acfff384a4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8cb7a9a..b5ceab2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+
+- **Compaction no longer goes blind when its persisted state is dropped.** Three
+ defects compounded into `ContextLengthExceeded` on long conversations
+ (`#233`):
+ - `message_ref` hashed the whole message dump, including bookkeeping the
+ framework and the host rewrite after the fact — `run_id` (re-stamped on
+ messages the framework re-touches, e.g. the injected `todo_stale_reminder`
+ nudges) and `timestamp` / `metadata` (host-owned; CubePlex writes a
+ per-turn `memory_snapshot.captured_at` into it). On a 901-message
+ conversation 38 of 877 refs drifted between compaction runs, so
+ `_state_matches_history` returned False and the state was discarded.
+ Identity is now the role, the content, and the tool linkage only.
+ - The trigger sized a raw-history send with `real_context_estimate`, which is
+ anchored to the most recent usage-bearing assistant and adds only what
+ follows it. Every message *before* the anchor is assumed to be covered by
+ that turn's `input_tokens` — true only while a summary covers the prefix.
+ With the state dropped it reported 57,278 tokens for a 901-message history
+ whose actual send was >= 256,001. When no summary is in effect the trigger
+ now also consults the char estimate, which does see the whole list.
+ - Dropping the state is logged at WARNING. It means the next send is the raw
+ history; previously it was silent, so the failure presented as "the model
+ got slow" until the provider returned 400.
+
## [0.15.1] - 2026-09-24
### Added
diff --git a/cubeloop/middleware/compaction/__init__.py b/cubeloop/middleware/compaction/__init__.py
index 3cbf2d9..31233f4 100644
--- a/cubeloop/middleware/compaction/__init__.py
+++ b/cubeloop/middleware/compaction/__init__.py
@@ -214,6 +214,18 @@ class CompactionMiddleware(Middleware):
if boundary >= len(history) or not _state_matches_history(
history, state, boundary
):
+ # Dropping the state is not free: the next send is the RAW history,
+ # which is what the summary was protecting against. It must never be
+ # silent — a drifted ref once cost an operator a 30-turn outage that
+ # looked like "the model is slow" (see #233).
+ if state is not None or boundary > 0:
+ logger.warning(
+ "CompactionMiddleware: dropping compaction state "
+ "(boundary=%d, history=%d) — the persisted summary no longer "
+ "matches this history, so this turn sends the raw history",
+ boundary,
+ len(history),
+ )
boundary = 0
state = None
_clear_state(ctx)
@@ -244,6 +256,32 @@ class CompactionMiddleware(Middleware):
*trailing_controls,
]
tokens_now = real_context_estimate(unpruned_compressed)
+ if state is None or boundary <= 0:
+ # No summary is in effect, so ``unpruned_compressed`` IS the raw
+ # history and ``real_context_estimate`` cannot be trusted for it.
+ # That function is anchored to the most recent usage-bearing
+ # assistant and only adds the char estimate of what follows that
+ # anchor: every message *before* the anchor is assumed to be
+ # accounted for by the anchor's own ``input_tokens``. That holds
+ # only while the anchored turn's prompt is still the prompt being
+ # sent — i.e. while a summary covers the prefix. With the summary
+ # dropped it reports the size of a history that no longer exists.
+ #
+ # Measured on the 901-message conversation from #233: 57,278 tokens
+ # for the compacted view AND 57,278 for the raw history that
+ # replaced it, while the actual send was >= 256,001 tokens. The
+ # threshold check saw 57,278 < 80,281, returned the raw history
+ # without compacting, and the provider answered
+ # ``ContextLengthExceeded``.
+ #
+ # The char estimate does see the whole list, so it acts as a floor
+ # here. It is deliberately a floor and not the estimate itself, and
+ # deliberately only when no summary is in effect: its conservative
+ # chars-per-token ratio over-reads prose, which would double-trigger
+ # compaction on an ordinary compacted view. This mirrors the
+ # anti-thrash guard below, which already sizes the raw history with
+ # ``approx_tokens``.
+ tokens_now = max(tokens_now, approx_tokens(unpruned_compressed))
if tokens_now < self._max_tokens_before:
return unpruned_compressed
diff --git a/cubeloop/middleware/compaction/state.py b/cubeloop/middleware/compaction/state.py
index c6b2262..036296d 100644
--- a/cubeloop/middleware/compaction/state.py
+++ b/cubeloop/middleware/compaction/state.py
@@ -27,11 +27,36 @@ class CompactionState(BaseModel):
preserved_tool_results: list[PreservedToolResult] = Field(default_factory=list)
+# Bookkeeping that does NOT change what a summary of the message describes, and
+# that the framework or the host rewrites after the message is stored. Hashing
+# it makes the refs drift, which silently invalidates the persisted compaction
+# state (`_state_matches_history` → False → the raw history is sent instead of
+# the compacted view).
+#
+# - ``run_id``: re-stamped on every run that re-touches the message. Observed in
+# production on the framework's own injected user messages — the
+# ``todo_stale_reminder`` nudges (`metadata.synthetic_source`) carried a fresh
+# ``run_id`` each turn.
+# - ``timestamp``: normalised on persistence.
+# - ``metadata``: host-owned free-form bag (``UserMessage.metadata`` is
+# documented as such). Hosts put per-turn snapshots in it — CubePlex writes
+# ``memory_snapshot.captured_at``, a fresh timestamp on every turn.
+#
+# Impact when they *were* hashed: on a 901-message conversation 38 of 877 refs
+# drifted between compaction runs, the state was dropped for 30+ turns, and the
+# trigger could not see the raw history it was about to send (57,278 estimated
+# vs >= 256,001 actually sent) — every request ended in
+# ``ContextLengthExceeded``. See #233.
+_VOLATILE_REF_FIELDS = ("run_id", "timestamp", "metadata")
+
+
def message_ref(message: Message) -> str:
message_id = str(getattr(message, "id", "") or "")
if message_id:
return f"id:{message_id}"
payload = message.model_dump(mode="json", exclude_none=True)
+ for field in _VOLATILE_REF_FIELDS:
+ payload.pop(field, None)
encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
return "sha256:" + hashlib.sha256(encoded).hexdigest()
diff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.py
index bfe3f3b..c027720 100644
--- a/tests/middleware/test_compaction.py
+++ b/tests/middleware/test_compaction.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import asyncio
+import logging
from typing import Any
from cubeloop.agent.types import AgentContext
@@ -20,6 +21,7 @@ from cubeloop.providers.base import (
StreamOptions,
TextContent,
ToolDefinition,
+ ToolResultMessage,
Usage,
UserMessage,
)
@@ -1428,3 +1430,189 @@ async def test_compaction_state_refs_survive_trailing_control_becoming_internal(
assert resumed[-1] == with_response[-1]
assert ctx.extra["compaction_until_msg_index"] == boundary
assert ctx.extra["compaction"] == persisted_state
+
+
+# --- #233: a dropped summary must not take the trigger down with it ---
+
+
+def test_message_ref_ignores_volatile_bookkeeping() -> None:
+ """Identity is the message's content, not its bookkeeping.
+
+ ``run_id`` / ``timestamp`` / ``metadata`` are rewritten after the message is
+ stored — the framework re-stamps ``run_id`` on messages it re-touches (the
+ injected ``todo_stale_reminder`` nudges did this every turn) and hosts write
+ per-turn snapshots into ``UserMessage.metadata``. Hashing them made refs
+ drift, which is what dropped the state in #233.
+ """
+ baseline = UserMessage(content=[TextContent(text="hello")], run_id="run-1")
+ restamped = UserMessage(
+ content=[TextContent(text="hello")],
+ run_id="run-2",
+ timestamp=1_231.5,
+ )
+ snapshot_a = UserMessage(
+ content=[TextContent(text="hello")],
+ metadata={"memory_snapshot": {"captured_at": "2026-10-13T11:43:58Z"}},
+ )
+ snapshot_b = UserMessage(
+ content=[TextContent(text="hello")],
+ metadata={"memory_snapshot": {"captured_at": "2026-10-13T12:13:44Z"}},
+ )
+
+ assert message_ref(baseline) == message_ref(restamped)
+ assert message_ref(snapshot_a) == message_ref(snapshot_b)
+
+ # Content and tool linkage are identity and must still be hashed.
+ assert message_ref(baseline) != message_ref(
+ UserMessage(content=[TextContent(text="hello!")], run_id="run-1")
+ )
+ result = [
+ ToolResultMessage(
+ tool_call_id="c1", tool_name="t", content=[TextContent(text="x")]
+ ),
+ ToolResultMessage(
+ tool_call_id="c2", tool_name="t", content=[TextContent(text="x")]
+ ),
+ ]
+ assert message_ref(result[0]) != message_ref(result[1])
+
+
+def _stale_state_for(messages: list[Message]) -> CompactionState:
+ """A state whose refs describe a *different* history — the shape of #233."""
+ return CompactionState(
+ summary="stale summary from a history that no longer matches",
+ summarized_message_refs=["sha256:does-not-match"],
+ )
+
+
+async def test_over_limit_raw_history_is_compacted_after_state_invalidation() -> None:
+ """The trigger must size the raw history it is about to send.
+
+ Regression (#233): ``real_context_estimate`` anchors on the most recent
+ usage-bearing assistant and adds only what follows it, so it reports the
+ size of the summary-era prompt — not the raw history that replaces it once
+ the state is dropped. On the real conversation it returned 57,278 for both
+ the compacted view and the 901-message raw history (actual send:
+ >= 256,001 tokens). The check saw 57,278 < 80,281 and returned the
+ over-limit history without compacting.
+ """
+ provider = _FakeSummaryProvider(reply="summary")
+ middleware = CompactionMiddleware(
+ summary_model=BoundModel(
+ provider=provider,
+ spec=Model(id="summary-model", provider_id="faux"),
+ ),
+ # The production values from #233.
+ max_tokens_before_compact=80_281,
+ keep_tail_tokens=8,
+ min_compact_messages=2,
+ )
+ messages: list[Message] = [
+ _user("turn 1"),
+ _assistant("reply 1"),
+ # 200_000 chars ≈ 100_000 approx tokens: on its own well over the
+ # 80_281 threshold. It sits BEFORE the anchor, which is exactly why the
+ # anchor-based estimate cannot see it.
+ _user("x" * 200_000),
+ AssistantMessage(
+ content=[TextContent(text="ok")],
+ usage=Usage(input_tokens=57_000),
+ ),
+ _user("continue"),
+ _assistant("reply"),
+ ]
+ ctx = AgentContext(
+ system_prompt="",
+ messages=messages,
+ extra={
+ "compaction": _stale_state_for(messages).model_dump(),
+ "compaction_until_msg_index": 3,
+ },
+ )
+
+ result = await middleware.transform_context(messages, ctx=ctx)
+
+ # The state was dropped, so compaction had to run on the raw history.
+ assert len(provider.calls) == 1
+ assert ctx.extra["compaction_until_msg_index"] > 0
+ assert len(result) < len(messages)
+ assert result[0].metadata.get("synthetic_source") == "compaction_summary"
+ # The over-limit prefix is gone; only the protected tail survived.
+ assert not any(
+ isinstance(block, TextContent) and len(block.text) > 100_000
+ for message in result
+ if isinstance(message, (UserMessage, AssistantMessage))
+ for block in message.content
+ if isinstance(block, TextContent)
+ )
+
+
+async def test_char_floor_does_not_re_trigger_on_a_valid_compacted_view() -> None:
+ """The floor covers only the dropped-state fallback.
+
+ With a live summary the view is already compacted: the raw history behind it
+ must not drive the trigger, or every turn would re-summarise. Guards against
+ the fix for #233 being applied unconditionally.
+ """
+ provider = _FakeSummaryProvider(reply="summary")
+ middleware = _make_middleware(
+ provider, max_tokens_before=80_281, keep_tail_tokens=8
+ )
+ messages: list[Message] = [
+ # A raw prefix that is far over the threshold, but already summarised.
+ _user("x" * 200_000),
+ _assistant("reply 1"),
+ _user("turn 2"),
+ _assistant("reply 2"),
+ # The live tail — small, and with no usage of its own.
+ _user("continue"),
+ _assistant("reply 3"),
+ ]
+ boundary = 4
+ ctx = AgentContext(
+ system_prompt="",
+ messages=messages,
+ extra={
+ "compaction": CompactionState(
+ summary="live summary",
+ summarized_message_refs=message_refs(messages[:boundary]),
+ ).model_dump(),
+ "compaction_until_msg_index": boundary,
+ },
+ )
+
+ result = await middleware.transform_context(messages, ctx=ctx)
+
+ assert provider.calls == []
+ assert len(result) == 3
+ assert result[0].metadata.get("synthetic_source") == "compaction_summary"
+ assert "live summary" in result[0].content[0].text
+ assert result[1:] == messages[boundary:]
+ assert ctx.extra["compaction_until_msg_index"] == boundary
+
+
+async def test_dropping_compaction_state_is_logged(caplog: Any) -> None:
+ """A dropped summary means a raw-history send; it must not be silent."""
+ provider = _FakeSummaryProvider(reply="summary")
+ middleware = _make_middleware(provider, max_tokens_before=1_000_000)
+ messages: list[Message] = [
+ _user("brand new 1"),
+ _assistant("reply 1"),
+ _user("brand new 2"),
+ _assistant("reply 2"),
+ ]
+ ctx = AgentContext(
+ system_prompt="",
+ messages=messages,
+ extra={
+ "compaction": _stale_state_for(messages).model_dump(),
+ "compaction_until_msg_index": 2,
+ },
+ )
+
+ with caplog.at_level(logging.WARNING):
+ await middleware.transform_context(messages, ctx=ctx)
+
+ assert any(
+ "dropping compaction state" in record.getMessage() for record in caplog.records
+ )