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
feat(compaction): token-based tail protection (tail_start_by_tokens + safe_boundary rewrite)
xf gong00d0580f92f8
diff --git a/cubepi/middleware/compaction/__init__.py b/cubepi/middleware/compaction/__init__.pyindex 237e65e..9d9b9ff 100644--- a/cubepi/middleware/compaction/__init__.py+++ b/cubepi/middleware/compaction/__init__.py@@ -111,9 +111,13 @@ class CompactionMiddleware(Middleware):if approx_tokens(compressed) < self._max_tokens_before:return compressed+ # Bridge: Task 3 replaced safe_boundary's keep_recent param with+ # an explicit tail_start index. Task 6 will swap the constructor+ # to keep_tail_tokens and call tail_start_by_tokens here.+ tail_start = max(0, len(messages) - self._keep_recent)new_boundary = safe_boundary(messages,- keep_recent=self._keep_recent,+ tail_start=tail_start,min_compact=max(self._min_compact, boundary + 1),)if new_boundary is None or new_boundary <= boundary:diff --git a/cubepi/middleware/compaction/boundary.py b/cubepi/middleware/compaction/boundary.pyindex 891216b..ba73851 100644--- a/cubepi/middleware/compaction/boundary.py+++ b/cubepi/middleware/compaction/boundary.py@@ -1,5 +1,6 @@from __future__ import annotations+from cubepi.middleware.compaction.tokens import approx_tokensfrom cubepi.providers.base import (AssistantMessage,Message,@@ -9,17 +10,56 @@ from cubepi.providers.base import ()+def tail_start_by_tokens(messages: list[Message], budget: int) -> int:+ """Walk backward accumulating token estimates; return where the tail starts.++ Contract:+ - Empty input → return 0.+ - Non-empty input → return an index in ``[0, len(messages) - 1]``.+ - Walk backward, summing ``approx_tokens([msg])``. Return the first index+ whose inclusion would push the accumulated total *strictly over* budget,+ *provided* at least one message is already in the tail. (Equal-to-budget+ is acceptable.) If the last message alone exceeds budget, it is still+ included — the tail always contains ≥ 1 message for non-empty input.+ """+ if not messages:+ return 0+ accumulated = 0+ for i in range(len(messages) - 1, -1, -1):+ msg_tokens = approx_tokens([messages[i]])+ if accumulated + msg_tokens > budget and accumulated > 0:+ return i + 1+ accumulated += msg_tokens+ return 0++def safe_boundary(messages: list[Message],*,- keep_recent: int,+ tail_start: int,min_compact: int = 1,) -> int | None:- """Return a message index that can be summarized safely."""- if len(messages) <= keep_recent:+ """Return a message index that can be summarised safely.++ ``tail_start`` is the precomputed protection boundary (call+ :func:`tail_start_by_tokens` first). Messages at ``[tail_start, end)``+ are the protected tail; this function searches the prefix for the latest+ ``UserMessage`` whose suffix has no orphaned tool-call/result pairs.++ Returns ``None`` when:+ - ``tail_start`` is out of range (negative, zero, or beyond ``messages``)+ - no candidate satisfies the tool-call self-containment rule+ - the candidate would be smaller than ``min_compact``+ """+ if tail_start <= 0 or tail_start > len(messages):return None- candidate = len(messages) - keep_recent+ # Start the search at the first message inside the tail (we want to+ # split BEFORE the tail begins).+ candidate = tail_start+ if candidate == len(messages):+ candidate -= 1+while candidate > 0:if not isinstance(messages[candidate], UserMessage):candidate -= 1diff --git a/tests/middleware/compaction/test_boundary.py b/tests/middleware/compaction/test_boundary.pyindex 9045b65..f8e664a 100644--- a/tests/middleware/compaction/test_boundary.py+++ b/tests/middleware/compaction/test_boundary.py@@ -1,6 +1,9 @@from __future__ import annotations-from cubepi.middleware.compaction.boundary import safe_boundary+from cubepi.middleware.compaction.boundary import (+ safe_boundary,+ tail_start_by_tokens,+)from cubepi.providers.base import (AssistantMessage,Message,@@ -34,6 +37,13 @@ def _tool_result(call_id: str) -> ToolResultMessage:)+def _big_user(chars: int) -> UserMessage:+ return UserMessage(content=[TextContent(text="x" * chars)])+++# --- safe_boundary with explicit tail_start ---++def test_returns_boundary_at_user_message_start() -> None:messages: list[Message] = [_user("q1"),@@ -43,14 +53,14 @@ def test_returns_boundary_at_user_message_start() -> None:_user("q3"),_assistant("a3"),]+ # tail_start=4 → msgs[4:] are the protected tail, walk back from 4 → 4 is+ # already a UserMessage, suffix [4..] self-contained, return 4.+ assert safe_boundary(messages, tail_start=4, min_compact=1) == 4- assert safe_boundary(messages, keep_recent=2, min_compact=1) == 4--def test_short_history_has_no_safe_boundary() -> None:+def test_no_safe_boundary_when_tail_start_zero() -> None:messages: list[Message] = [_user("q1"), _assistant("a1")]-- assert safe_boundary(messages, keep_recent=2) is None+ assert safe_boundary(messages, tail_start=0) is Nonedef test_rejects_suffix_with_orphan_tool_result() -> None:@@ -63,8 +73,8 @@ def test_rejects_suffix_with_orphan_tool_result() -> None:_tool_result("orphan"),_assistant("done"),]-- assert safe_boundary(messages, keep_recent=2, min_compact=1) is None+ # tail_start=4 brings the orphan ToolResult into the tail — no safe split.+ assert safe_boundary(messages, tail_start=4, min_compact=1) is Nonedef test_accepts_suffix_with_matching_tool_call_and_result() -> None:@@ -77,8 +87,10 @@ def test_accepts_suffix_with_matching_tool_call_and_result() -> None:_tool_result("c1"),_assistant("done"),]-- assert safe_boundary(messages, keep_recent=3, min_compact=1) == 2+ # tail_start=3 lands inside a tool-call/result pair (3 is the assistant+ # with the call). Walk back: 3 not UserMessage → 2 is UserMessage,+ # suffix [2..] is self-contained → return 2.+ assert safe_boundary(messages, tail_start=3, min_compact=1) == 2def test_enforces_min_compact() -> None:@@ -88,6 +100,62 @@ def test_enforces_min_compact() -> None:_user("q2"),_assistant("a2"),]+ assert safe_boundary(messages, tail_start=2, min_compact=3) is None+ assert safe_boundary(messages, tail_start=2, min_compact=1) == 2+++# --- tail_start_by_tokens ---+++def test_tail_start_protects_what_fits_in_budget() -> None:+ # 4 messages × ~1000 tokens each. Budget 1500 fits only the last:+ # i=3 → accum 0+1000=1000 (not > 1500), accum=1000.+ # i=2 → 1000+1000=2000 > 1500 AND accum>0 → return 3.+ msgs = [_big_user(2000) for _ in range(4)]+ assert tail_start_by_tokens(msgs, 1500) == 3+++def test_tail_start_all_fit_returns_zero() -> None:+ msgs = [_big_user(10) for _ in range(3)]+ assert tail_start_by_tokens(msgs, 100_000) == 0+++def test_tail_start_oversized_last_message_still_in_tail() -> None:+ # The final message alone exceeds budget — must still end up in the tail.+ msgs = [_big_user(100), _big_user(100), _big_user(100_000)]+ assert tail_start_by_tokens(msgs, 1000) == 2+++def test_tail_start_empty_input() -> None:+ assert tail_start_by_tokens([], 1000) == 0+++def test_tail_start_returns_index_in_bounds() -> None:+ msgs = [_big_user(2000) for _ in range(5)]+ result = tail_start_by_tokens(msgs, 500)+ assert 0 <= result <= len(msgs) - 1+++# --- safe_boundary + tail_start interaction (the documented composition) ---+++def test_safe_boundary_using_tail_start_by_tokens() -> None:+ messages: list[Message] = [+ _user("q1"),+ _assistant("a1"),+ _user("q2"),+ _assistant("a2"),+ _user("q3"),+ _assistant("a3"),+ ]+ tail_start = tail_start_by_tokens(messages, budget=1) # tiny budget → tail=5+ assert tail_start == 5+ # safe_boundary then walks back to find the latest UserMessage <= 5.+ assert safe_boundary(messages, tail_start=tail_start, min_compact=1) == 4+- assert safe_boundary(messages, keep_recent=2, min_compact=3) is None- assert safe_boundary(messages, keep_recent=2, min_compact=1) == 2+def test_safe_boundary_rejects_out_of_range_tail_start() -> None:+ messages: list[Message] = [_user("q")]+ # Negative or too-large tail_start → None (no work to do).+ assert safe_boundary(messages, tail_start=-1) is None+ assert safe_boundary(messages, tail_start=99) is None