Skip to content

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

fix(compaction): tail-budget clamp + half-open circuit breaker + 100% patch coverage

xf gongf715db4f09eb
diff --git a/cubepi/middleware/compaction/__init__.py b/cubepi/middleware/compaction/__init__.py
index 5c561ee..60b7e63 100644
--- a/cubepi/middleware/compaction/__init__.py
+++ b/cubepi/middleware/compaction/__init__.py
@@ -34,6 +34,7 @@ SUMMARY_PREFIX = (
logger = logging.getLogger(__name__)
_MAX_FAILURES = 3
+_HALF_OPEN_AFTER_FALLBACK_RUNS = 5
_MIN_SAVINGS_PCT = 10.0
_MAX_LOW_SAVINGS = 2
_ANTI_THRASH_NEW_MSGS = 8
@@ -71,6 +72,15 @@ def _clear_state(ctx: AgentContext) -> None:
ctx.extra.pop("compaction_until_msg_index", None)
+def _load_int(value: Any, default: int) -> int:
+ if isinstance(value, (int, float, str)):
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ return default
+ return default
+
+
def _state_matches_history(
messages: list[Message],
state: CompactionState | None,
@@ -145,7 +155,17 @@ class CompactionMiddleware(Middleware):
_clear_state(ctx)
# Single tail computation — shared by pruner and safe_boundary.
- tail_start = tail_start_by_tokens(messages, self._keep_tail_tokens)
+ # Clamp the effective tail budget to at most half the trigger
+ # threshold. Without this, a configuration where
+ # ``keep_tail_tokens`` exceeds ``max_tokens_before_compact``
+ # produces ``tail_start == 0`` for any history that triggers
+ # compaction — the tail swallows everything and ``safe_boundary``
+ # finds nothing to summarise.
+ effective_tail_tokens = min(
+ self._keep_tail_tokens,
+ max(1, self._max_tokens_before // 2),
+ )
+ tail_start = tail_start_by_tokens(messages, effective_tail_tokens)
# Phase 1: pre-prune old tool results (cheap, no LLM call) — skip
# entirely when prune_tool_outputs=False (audit-chain agents).
@@ -171,26 +191,37 @@ class CompactionMiddleware(Middleware):
return compressed
# Circuit breaker — gates LLM only; fallback always runs.
- failures_raw = ctx.extra.get("compaction_failures", 0)
- failures = (
- int(failures_raw) if isinstance(failures_raw, (int, float, str)) else 0
- )
+ failures = _load_int(ctx.extra.get("compaction_failures"), 0)
llm_allowed = failures < _MAX_FAILURES
+
+ # Half-open: after enough fallback-only runs, give the LLM one
+ # attempt. Success → full reset; failure → breaker re-opens.
+ # Without this the breaker would be permanent: LLM is gated → it
+ # never gets a chance to succeed → counter never decrements.
+ half_open_retry = False
if not llm_allowed:
- logger.warning(
- "CompactionMiddleware: LLM circuit breaker open (%d failures), using fallback",
- failures,
- )
+ fallback_runs = _load_int(ctx.extra.get("compaction_fallback_runs"), 0)
+ if fallback_runs >= _HALF_OPEN_AFTER_FALLBACK_RUNS:
+ logger.info(
+ "CompactionMiddleware: breaker half-open after %d fallback runs, retrying LLM",
+ fallback_runs,
+ )
+ llm_allowed = True
+ half_open_retry = True
+ # Consume the wait window — on retry failure the LLM should
+ # not fire again immediately; another N fallback runs must
+ # accumulate first.
+ ctx.extra["compaction_fallback_runs"] = 0
+ else:
+ logger.warning(
+ "CompactionMiddleware: LLM circuit breaker open (%d failures), using fallback",
+ failures,
+ )
# Anti-thrashing guard — uses raw_tokens so prior cumulative summaries
# don't mask a genuinely over-limit history.
raw_tokens = approx_tokens(messages)
- low_savings_raw = ctx.extra.get("compaction_low_savings_count", 0)
- low_savings = (
- int(low_savings_raw)
- if isinstance(low_savings_raw, (int, float, str))
- else 0
- )
+ low_savings = _load_int(ctx.extra.get("compaction_low_savings_count"), 0)
force_emergency = (
raw_tokens >= self._max_tokens_before * _ANTI_THRASH_FORCE_RATIO
)
@@ -211,21 +242,32 @@ class CompactionMiddleware(Middleware):
existing_summary_suffix=self._existing_summary_suffix,
abort_signal=signal,
)
+ # Full reset on LLM success.
ctx.extra["compaction_failures"] = 0
+ ctx.extra["compaction_fallback_runs"] = 0
except Exception as exc: # noqa: BLE001
logger.warning("CompactionMiddleware LLM summariser failed: %s", exc)
- ctx.extra["compaction_failures"] = failures + 1
+ # Half-open retry that fails re-opens the breaker; a normal
+ # failure just increments toward open.
+ ctx.extra["compaction_failures"] = (
+ _MAX_FAILURES if half_open_retry else failures + 1
+ )
new_state = build_fallback_summary(
pruned_messages[boundary:new_boundary],
ref_messages=messages[boundary:new_boundary],
existing=state,
)
+ # The LLM was just attempted — restart the half-open wait.
+ ctx.extra["compaction_fallback_runs"] = 0
else:
new_state = build_fallback_summary(
pruned_messages[boundary:new_boundary],
ref_messages=messages[boundary:new_boundary],
existing=state,
)
+ ctx.extra["compaction_fallback_runs"] = (
+ _load_int(ctx.extra.get("compaction_fallback_runs"), 0) + 1
+ )
ctx.extra["compaction"] = new_state.model_dump()
ctx.extra["compaction_until_msg_index"] = new_boundary
diff --git a/tests/middleware/compaction/test_boundary.py b/tests/middleware/compaction/test_boundary.py
index f8e664a..1bdeaa2 100644
--- a/tests/middleware/compaction/test_boundary.py
+++ b/tests/middleware/compaction/test_boundary.py
@@ -159,3 +159,16 @@ def test_safe_boundary_rejects_out_of_range_tail_start() -> None:
# 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
+
+
+def test_safe_boundary_tail_start_equals_len_clamps_in_bounds() -> None:
+ """When tail_start == len(messages), the search starts at the last valid
+ index — exercises the clamp at boundary.py's ``candidate -= 1``."""
+ messages: list[Message] = [
+ _user("q1"),
+ _assistant("a1"),
+ _user("q2"),
+ _assistant("a2"),
+ ]
+ # tail_start == 4 == len(messages). Clamp to 3, walk back to 2 (UserMessage).
+ assert safe_boundary(messages, tail_start=4, min_compact=1) == 2
diff --git a/tests/middleware/compaction/test_summarizer.py b/tests/middleware/compaction/test_summarizer.py
index bbb74db..6b6ba1c 100644
--- a/tests/middleware/compaction/test_summarizer.py
+++ b/tests/middleware/compaction/test_summarizer.py
@@ -442,3 +442,40 @@ async def test_summarize_uses_existing_summary_suffix_override() -> None:
captured = provider.calls[0]["system_prompt"]
assert captured.startswith("BASE")
assert "MERGE THIS: prior" in captured
+
+
+# --- coverage: _shrink_strings list + fall-through; _format_arguments non-JSON ---
+
+
+def test_shrink_strings_recurses_into_lists() -> None:
+ """The list branch of _shrink_strings shrinks string leaves inside lists,
+ leaves non-string leaves intact."""
+ from cubepi.middleware.compaction.summarizer import _shrink_strings
+
+ long_text = "x" * 500
+ obj = ["short", long_text, 42, True, None, [long_text]]
+ shrunk = _shrink_strings(obj)
+ assert isinstance(shrunk, list)
+ assert shrunk[0] == "short"
+ assert shrunk[1].startswith("x" * 200) and "truncated" in shrunk[1]
+ assert shrunk[2] == 42
+ assert shrunk[3] is True
+ assert shrunk[4] is None
+ # Nested list also recurses.
+ assert "truncated" in shrunk[5][0]
+
+
+def test_format_arguments_non_json_serialisable_falls_back_to_str() -> None:
+ """A value json.dumps can't handle (e.g. a custom object) falls back to
+ str() instead of raising — defensive against odd backend payloads."""
+ from cubepi.middleware.compaction.summarizer import _format_arguments
+
+ class _NotJson:
+ def __repr__(self) -> str:
+ return "<not-json>"
+
+ # Pass a dict where one VALUE is non-serialisable. _shrink_strings does
+ # NOT recurse into custom objects (returns them as-is), so json.dumps
+ # raises TypeError → fallback to str().
+ result = _format_arguments({"x": _NotJson()})
+ assert "<not-json>" in result
diff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.py
index 19406bd..1b029e8 100644
--- a/tests/middleware/test_compaction.py
+++ b/tests/middleware/test_compaction.py
@@ -365,9 +365,10 @@ async def test_anti_thrashing_skips_compaction_when_guard_tripped() -> None:
"""Guard fires when low_savings_count >= 2, raw history not over 1.5×
threshold, and new_boundary advance < 8 messages."""
provider = _FakeSummaryProvider(reply="x")
- # Threshold chosen so raw_tokens (~24) stays under 1.5 * threshold
- # (= 36) but above threshold (= 20) — guard CAN fire.
- middleware = _make_middleware(provider, max_tokens_before=20)
+ # Threshold chosen so tokens_now (~18) EXCEEDS threshold (so the
+ # under-threshold fast-path doesn't fire) AND raw_tokens (~18) stays
+ # under 1.5 * threshold (so emergency override doesn't bypass the guard).
+ middleware = _make_middleware(provider, max_tokens_before=15)
messages: list[Message] = [
_user("turn 1"),
_assistant("reply 1"),
@@ -544,3 +545,177 @@ async def test_summary_prompt_constructor_argument_passthrough() -> None:
assert len(provider.calls) == 1
# No prior summary, so the prompt should be the override verbatim.
assert provider.calls[0]["system_prompt"] == "CUSTOM PROMPT BODY"
+
+
+# --- coverage: extra_llm_calls ---
+
+
+def test_extra_llm_calls_returns_summary_model() -> None:
+ provider = _FakeSummaryProvider()
+ bound = BoundModel(
+ provider=provider,
+ spec=Model(id="m", provider_id="faux"),
+ )
+ middleware = CompactionMiddleware(
+ summary_model=bound,
+ max_tokens_before_compact=100,
+ keep_tail_tokens=8,
+ )
+ assert middleware.extra_llm_calls() == (bound,)
+
+
+# --- codex review: effective tail budget clamp ---
+
+
+async def test_keep_tail_tokens_clamped_below_threshold() -> None:
+ """If keep_tail_tokens >= max_tokens_before_compact, the tail must NOT
+ swallow the entire history; otherwise compaction can never trigger.
+ The middleware clamps the effective tail to half the threshold."""
+ provider = _FakeSummaryProvider(reply="summary")
+ middleware = CompactionMiddleware(
+ summary_model=BoundModel(
+ provider=provider,
+ spec=Model(id="m", provider_id="faux"),
+ ),
+ max_tokens_before_compact=10,
+ keep_tail_tokens=200, # configured larger than threshold AND than raw
+ min_compact_messages=2,
+ )
+ messages: list[Message] = [
+ _user("turn 1"),
+ _assistant("reply 1"),
+ _user("turn 2"),
+ _assistant("reply 2"),
+ _user("turn 3"),
+ _assistant("reply 3"),
+ ]
+ ctx = AgentContext(system_prompt="", messages=messages, extra={})
+ await middleware.transform_context(messages, ctx=ctx)
+
+ # Without the clamp, the whole 18-token history would fit in the
+ # 200-token tail budget and safe_boundary would return None → no
+ # compaction. With the clamp, the effective tail is min(200, 10//2)=5
+ # tokens, so compaction fires and writes state.
+ assert "compaction" in ctx.extra
+ assert len(provider.calls) == 1
+
+
+# --- codex review: half-open circuit breaker ---
+
+
+async def test_circuit_breaker_half_open_retries_llm_after_fallback_runs() -> None:
+ """After _MAX_FAILURES failures the breaker opens. After
+ _HALF_OPEN_AFTER_FALLBACK_RUNS fallback-only runs, the breaker goes
+ half-open and the LLM is attempted again. If it succeeds, the breaker
+ fully resets."""
+ from cubepi.middleware.compaction import _HALF_OPEN_AFTER_FALLBACK_RUNS
+
+ provider = _FakeSummaryProvider(raises=RuntimeError("down"))
+ middleware = _make_middleware(provider, max_tokens_before=1)
+ ctx = AgentContext(system_prompt="", messages=[], extra={})
+
+ # Drive the breaker open with 3 LLM failures across growing histories.
+ messages: list[Message] = []
+ for i in range(3):
+ messages = [
+ *messages,
+ _user(f"turn {i * 2}"),
+ _assistant(f"reply {i * 2}"),
+ _user(f"turn {i * 2 + 1}"),
+ _assistant(f"reply {i * 2 + 1}"),
+ ]
+ await middleware.transform_context(messages, ctx=ctx)
+ assert ctx.extra["compaction_failures"] == 3
+ calls_when_open = len(provider.calls)
+
+ # Run fallback-only turns until the breaker should go half-open.
+ for i in range(_HALF_OPEN_AFTER_FALLBACK_RUNS):
+ messages = [
+ *messages,
+ _user(f"fbr {i} q"),
+ _assistant(f"fbr {i} a"),
+ ]
+ await middleware.transform_context(messages, ctx=ctx)
+ # No LLM call attempted during fallback-only phase.
+ assert len(provider.calls) == calls_when_open
+ assert ctx.extra["compaction_fallback_runs"] == _HALF_OPEN_AFTER_FALLBACK_RUNS
+
+ # Swap to a working LLM and run one more turn — half-open path triggers,
+ # LLM is attempted, succeeds, breaker fully resets.
+ provider.raises = None
+ provider.reply = "real summary"
+ messages = [*messages, _user("recovered q"), _assistant("recovered a")]
+ await middleware.transform_context(messages, ctx=ctx)
+
+ assert len(provider.calls) == calls_when_open + 1
+ assert ctx.extra["compaction_failures"] == 0
+ assert ctx.extra["compaction_fallback_runs"] == 0
+
+
+async def test_half_open_failure_re_opens_breaker() -> None:
+ """Half-open retry that fails snaps the breaker back to MAX_FAILURES."""
+ from cubepi.middleware.compaction import _HALF_OPEN_AFTER_FALLBACK_RUNS
+
+ provider = _FakeSummaryProvider(raises=RuntimeError("down"))
+ middleware = _make_middleware(provider, max_tokens_before=1)
+ ctx = AgentContext(system_prompt="", messages=[], extra={})
+
+ messages: list[Message] = []
+ # 3 failures → breaker opens.
+ for i in range(3):
+ messages = [
+ *messages,
+ _user(f"t{i}a"),
+ _assistant(f"r{i}a"),
+ _user(f"t{i}b"),
+ _assistant(f"r{i}b"),
+ ]
+ await middleware.transform_context(messages, ctx=ctx)
+ # Fallback-only runs until half-open is ready.
+ for i in range(_HALF_OPEN_AFTER_FALLBACK_RUNS):
+ messages = [*messages, _user(f"f{i}"), _assistant(f"a{i}")]
+ await middleware.transform_context(messages, ctx=ctx)
+
+ # Half-open turn: LLM still failing.
+ calls_before_retry = len(provider.calls)
+ messages = [*messages, _user("retry q"), _assistant("retry a")]
+ await middleware.transform_context(messages, ctx=ctx)
+
+ # LLM was attempted (half-open allowed one try) and failed.
+ assert len(provider.calls) == calls_before_retry + 1
+ # Breaker re-opens (failures back to MAX, not MAX+1).
+ assert ctx.extra["compaction_failures"] == 3
+
+
+# --- coverage: _load_int with bad type ---
+
+
+async def test_corrupt_failure_counter_treated_as_zero() -> None:
+ """Non-numeric values in ctx.extra are treated as 0 — defensive parsing.
+
+ Covers both the ``isinstance`` reject path (wrong type) and the
+ ``ValueError`` catch path (string that can't be parsed as int).
+ """
+ provider = _FakeSummaryProvider()
+ middleware = _make_middleware(provider, max_tokens_before=1)
+ messages: list[Message] = [
+ _user("turn 1"),
+ _assistant("reply 1"),
+ _user("turn 2"),
+ _assistant("reply 2"),
+ _user("turn 3"),
+ _assistant("reply 3"),
+ ]
+ ctx = AgentContext(
+ system_prompt="",
+ messages=messages,
+ extra={
+ "compaction_failures": "not-an-int", # ValueError in int()
+ "compaction_low_savings_count": ["bad", "shape"], # isinstance reject
+ "compaction_fallback_runs": None, # isinstance reject
+ },
+ )
+ await middleware.transform_context(messages, ctx=ctx)
+ # Compaction proceeded as if all counters were 0.
+ assert "compaction" in ctx.extra
+ assert ctx.extra["compaction_failures"] == 0 # success path