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): 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__.pyindex 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 = Falseif 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"] = 0except Exception as exc: # noqa: BLE001logger.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"] = 0else: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_boundarydiff --git a/tests/middleware/compaction/test_boundary.py b/tests/middleware/compaction/test_boundary.pyindex 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 Noneassert 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) == 2diff --git a/tests/middleware/compaction/test_summarizer.py b/tests/middleware/compaction/test_summarizer.pyindex 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 resultdiff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.pyindex 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