Skip to content

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

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__.py
index 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.py
index 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_tokens
from 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 -= 1
diff --git a/tests/middleware/compaction/test_boundary.py b/tests/middleware/compaction/test_boundary.py
index 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 None
def 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 None
def 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) == 2
def 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