CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
fix(compaction): keep the trigger honest when the summary is dropped
蓝色天空83acfff384a4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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### Addeddiff --git a/cubeloop/middleware/compaction/__init__.py b/cubeloop/middleware/compaction/__init__.pyindex 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 = 0state = 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_compresseddiff --git a/cubeloop/middleware/compaction/state.py b/cubeloop/middleware/compaction/state.pyindex 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.pyindex bfe3f3b..c027720 100644--- a/tests/middleware/test_compaction.py+++ b/tests/middleware/test_compaction.py@@ -1,6 +1,7 @@from __future__ import annotationsimport asyncio+import loggingfrom typing import Anyfrom 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"] == boundaryassert 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+ )