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): wire pre-pruning + circuit breaker + anti-thrashing + fallback
xf gongdc69199f7939
diff --git a/cubepi/middleware/compaction/__init__.py b/cubepi/middleware/compaction/__init__.pyindex 9d9b9ff..ef515ae 100644--- a/cubepi/middleware/compaction/__init__.py+++ b/cubepi/middleware/compaction/__init__.py@@ -1,16 +1,23 @@from __future__ import annotations-import loggingimport asyncio+import loggingfrom typing import Anyfrom pydantic import ValidationErrorfrom cubepi.agent.types import AgentContextfrom cubepi.middleware.base import Middleware-from cubepi.middleware.compaction.boundary import safe_boundary+from cubepi.middleware.compaction.boundary import (+ safe_boundary,+ tail_start_by_tokens,+)+from cubepi.middleware.compaction.pruner import prune_tool_resultsfrom cubepi.middleware.compaction.state import CompactionState, message_refs-from cubepi.middleware.compaction.summarizer import summarize+from cubepi.middleware.compaction.summarizer import (+ build_fallback_summary,+ summarize,+)from cubepi.middleware.compaction.tokens import approx_tokensfrom cubepi.providers.base import (BoundModel,@@ -22,6 +29,12 @@ from cubepi.providers.base import (SUMMARY_PREFIX = "[Conversation summary so far]\n"logger = logging.getLogger(__name__)+_MAX_FAILURES = 3+_MIN_SAVINGS_PCT = 10.0+_MAX_LOW_SAVINGS = 2+_ANTI_THRASH_NEW_MSGS = 8+_ANTI_THRASH_FORCE_RATIO = 1.5+def _compressed_view(messages: list[Message],@@ -68,20 +81,33 @@ def _state_matches_history(class CompactionMiddleware(Middleware):- """Keep long histories within context by summarizing older turns."""+ """Keep long histories within context by summarizing older turns.++ Three layered guards keep the summariser from misbehaving under load:++ - **Pre-pruning pass** (cheap, no LLM call) replaces large old tool+ results with one-line summaries before the LLM ever sees them.+ - **Circuit breaker** gates only the LLM call; after+ ``_MAX_FAILURES`` consecutive errors, switches to the deterministic+ fallback summariser (still compacts context — never gets stuck).+ - **Anti-thrashing guard** skips compaction when prior runs saved+ under ``_MIN_SAVINGS_PCT``; resets when savings recover, the+ boundary advances by ``_ANTI_THRASH_NEW_MSGS`` messages, or raw+ history exceeds ``max_tokens_before_compact * _ANTI_THRASH_FORCE_RATIO``.+ """def __init__(self,*,summary_model: BoundModel,max_tokens_before_compact: int,- keep_recent_messages: int = 8,- max_summary_tokens: int = 1024,+ keep_tail_tokens: int = 8_000,+ max_summary_tokens: int | None = None,min_compact_messages: int = 4,) -> None:self._summary_model = summary_modelself._max_tokens_before = max_tokens_before_compact- self._keep_recent = keep_recent_messages+ self._keep_tail_tokens = keep_tail_tokensself._max_summary_tokens = max_summary_tokensself._min_compact = min_compact_messages@@ -97,6 +123,7 @@ class CompactionMiddleware(Middleware):boundary = (int(raw_boundary) if isinstance(raw_boundary, (int, float, str)) else 0)+if state is None and ("compaction" in ctx.extra or boundary > 0):boundary = 0_clear_state(ctx)@@ -106,15 +133,20 @@ class CompactionMiddleware(Middleware):boundary = 0state = None_clear_state(ctx)- compressed = _compressed_view(messages, state, boundary)- if approx_tokens(compressed) < self._max_tokens_before:+ # Single tail computation — shared by pruner and safe_boundary.+ tail_start = tail_start_by_tokens(messages, self._keep_tail_tokens)++ # Phase 1: pre-prune old tool results (cheap, no LLM call).+ pruned_messages = prune_tool_results(messages, tail_start=tail_start)++ compressed = _compressed_view(pruned_messages, state, boundary)++ tokens_now = approx_tokens(compressed)+ if tokens_now < 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)+ # Find boundary before guards (needed for anti-thrash new-msgs check).new_boundary = safe_boundary(messages,tail_start=tail_start,@@ -123,21 +155,74 @@ class CompactionMiddleware(Middleware):if new_boundary is None or new_boundary <= boundary:return compressed- try:- new_state = await summarize(- model=self._summary_model,- messages_to_summarize=messages[boundary:new_boundary],- existing=state,- max_summary_tokens=self._max_summary_tokens,- abort_signal=signal,+ # 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+ )+ llm_allowed = failures < _MAX_FAILURES+ if not llm_allowed:+ logger.warning(+ "CompactionMiddleware: LLM circuit breaker open (%d failures), using fallback",+ failures,)- except Exception as exc: # noqa: BLE001- logger.warning("CompactionMiddleware summarizer failed, skipping: %s", exc)++ # 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+ )+ force_emergency = (+ raw_tokens >= self._max_tokens_before * _ANTI_THRASH_FORCE_RATIO+ )+ enough_new = (new_boundary - boundary) >= _ANTI_THRASH_NEW_MSGS+ if low_savings >= _MAX_LOW_SAVINGS and not force_emergency and not enough_new:+ logger.debug("CompactionMiddleware: skipping — low savings guard active")return compressed+ if llm_allowed:+ try:+ new_state = await summarize(+ model=self._summary_model,+ messages_to_summarize=pruned_messages[boundary:new_boundary],+ ref_messages=messages[boundary:new_boundary],+ existing=state,+ max_summary_tokens=self._max_summary_tokens,+ abort_signal=signal,+ )+ ctx.extra["compaction_failures"] = 0+ except Exception as exc: # noqa: BLE001+ logger.warning("CompactionMiddleware LLM summariser failed: %s", exc)+ ctx.extra["compaction_failures"] = failures + 1+ new_state = build_fallback_summary(+ pruned_messages[boundary:new_boundary],+ ref_messages=messages[boundary:new_boundary],+ existing=state,+ )+ else:+ new_state = build_fallback_summary(+ pruned_messages[boundary:new_boundary],+ ref_messages=messages[boundary:new_boundary],+ existing=state,+ )+ctx.extra["compaction"] = new_state.model_dump()ctx.extra["compaction_until_msg_index"] = new_boundary- return _compressed_view(messages, new_state, new_boundary)+ result = _compressed_view(pruned_messages, new_state, new_boundary)++ # Anti-thrashing tracking — compare raw history to result tokens.+ tokens_after = approx_tokens(result)+ if raw_tokens > 0:+ savings_pct = (raw_tokens - tokens_after) / raw_tokens * 100+ ctx.extra["compaction_low_savings_count"] = (+ low_savings + 1 if savings_pct < _MIN_SAVINGS_PCT else 0+ )++ return resultdef extra_llm_calls(self) -> tuple[BoundModel, ...]:# Surface the bound summary model so ``cubepi.tracing.Recorder`` can@@ -152,4 +237,5 @@ class CompactionMiddleware(Middleware):__all__ = ["CompactionMiddleware","CompactionState",+ "SUMMARY_PREFIX",]diff --git a/cubepi/middleware/compaction/pruner.py b/cubepi/middleware/compaction/pruner.pyindex 4df2949..f6e1c3e 100644--- a/cubepi/middleware/compaction/pruner.py+++ b/cubepi/middleware/compaction/pruner.py@@ -30,9 +30,7 @@ def prune_tool_results(messages: list[Message], *, tail_start: int) -> list[Messcontinuesummary = f"[{msg.tool_name}] {len(text)} chars"- result.append(- msg.model_copy(update={"content": [TextContent(text=summary)]})- )+ result.append(msg.model_copy(update={"content": [TextContent(text=summary)]}))return resultdiff --git a/cubepi/middleware/compaction/summarizer.py b/cubepi/middleware/compaction/summarizer.pyindex b6e83b7..1ee57a2 100644--- a/cubepi/middleware/compaction/summarizer.py+++ b/cubepi/middleware/compaction/summarizer.py@@ -18,7 +18,7 @@ from cubepi.providers.base import (_ARG_VALUE_CHARS = 200_ARG_REPR_MAX = 500-_SUMMARY_MIN = 1024 # matches prior fixed default — never regress below it+_SUMMARY_MIN = 1024 # matches prior fixed default — never regress below it_SUMMARY_RATIO = 0.15_SUMMARY_MAX = 4096@@ -96,7 +96,9 @@ def _format_message_for_summary(message: Message) -> str:if isinstance(block, TextContent):parts.append(block.text)elif isinstance(block, ToolCall):- parts.append(f"[tool_call:{block.name}]{_format_arguments(block.arguments)}")+ parts.append(+ f"[tool_call:{block.name}]{_format_arguments(block.arguments)}"+ )elif hasattr(block, "text"):parts.append(str(getattr(block, "text", "")))return f"[{role}] " + " ".join(parts)diff --git a/tests/middleware/compaction/test_summarizer.py b/tests/middleware/compaction/test_summarizer.pyindex d845735..59990d7 100644--- a/tests/middleware/compaction/test_summarizer.py+++ b/tests/middleware/compaction/test_summarizer.py@@ -219,9 +219,7 @@ def test_tool_call_repr_max_chars_enforced() -> None:def test_tool_call_empty_arguments() -> None:- msg = AssistantMessage(- content=[ToolCall(id="c1", name="ping", arguments={})]- )+ msg = AssistantMessage(content=[ToolCall(id="c1", name="ping", arguments={})])formatted = _format_message_for_summary(msg)assert "[tool_call:ping]" in formatted@@ -267,9 +265,7 @@ async def test_summarize_uses_dynamic_budget_when_none() -> None:provider=provider,spec=Model(id="summary-model", provider_id="faux"),),- messages_to_summarize=[- UserMessage(content=[TextContent(text="x" * 40_000)])- ],+ messages_to_summarize=[UserMessage(content=[TextContent(text="x" * 40_000)])],existing=None,)# 20 000 tokens * 0.15 = 3 000diff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.pyindex 02a8436..f05667f 100644--- a/tests/middleware/test_compaction.py+++ b/tests/middleware/test_compaction.py@@ -70,14 +70,17 @@ def _make_middleware(provider: _FakeSummaryProvider,*,max_tokens_before: int = 1000,+ keep_tail_tokens: int = 8,) -> CompactionMiddleware:+ """Tiny tail-token budget (~2 small test messages) approximates the+ old ``keep_recent_messages=2`` behaviour for these scenarios."""return CompactionMiddleware(summary_model=BoundModel(provider=provider,spec=Model(id="summary-model", provider_id="faux"),),max_tokens_before_compact=max_tokens_before,- keep_recent_messages=2,+ keep_tail_tokens=keep_tail_tokens,max_summary_tokens=512,min_compact_messages=2,)@@ -170,7 +173,9 @@ async def test_over_threshold_without_safe_boundary_returns_compressed_view() ->assert provider.calls == []-async def test_summarizer_failure_returns_current_view_without_writing_state() -> None:+async def test_summarizer_failure_writes_fallback_state() -> None:+ """When the LLM raises, build_fallback_summary() runs so the agent+ still gets a compressed view; failures counter increments."""provider = _FakeSummaryProvider(raises=RuntimeError("LLM unavailable"))middleware = _make_middleware(provider, max_tokens_before=1)messages: list[Message] = [@@ -185,8 +190,14 @@ async def test_summarizer_failure_returns_current_view_without_writing_state() -result = await middleware.transform_context(messages, ctx=ctx)- assert result == messages- assert "compaction" not in ctx.extra+ # Fallback state was written despite the LLM failure.+ assert "compaction" in ctx.extra+ state = CompactionState.model_validate(ctx.extra["compaction"])+ assert state.is_fallback is True+ # Failure counter incremented.+ assert ctx.extra["compaction_failures"] == 1+ # Result is compressed (summary + tail), not the raw message list.+ assert len(result) < len(messages)async def test_stale_boundary_larger_than_history_is_ignored() -> None:@@ -289,3 +300,167 @@ async def test_malformed_persisted_state_is_cleared() -> None:assert result == messagesassert "compaction" not in ctx.extraassert "compaction_until_msg_index" not in ctx.extra+++# --- Task 6: circuit breaker, anti-thrashing, refs survive pruning ---+++async def test_circuit_breaker_opens_after_three_failures() -> None:+ """After 3 LLM failures the breaker opens; 4th call uses fallback (no LLM).++ Messages grow each turn so safe_boundary keeps advancing — without that,+ once a fallback state is persisted, subsequent calls early-return at+ ``new_boundary <= boundary`` and the LLM is never called again.+ """+ provider = _FakeSummaryProvider(raises=RuntimeError("down"))+ middleware = _make_middleware(provider, max_tokens_before=1)+ ctx = AgentContext(system_prompt="", messages=[], extra={})++ 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"] == i + 1+ assert "compaction" in ctx.extra++ calls_before_breaker = len(provider.calls)++ # Turn 4: breaker open → LLM NOT called, fallback still runs.+ messages = [*messages, _user("more"), _assistant("more reply")]+ result = await middleware.transform_context(messages, ctx=ctx)+ assert len(provider.calls) == calls_before_breaker # no new LLM call+ assert ctx.extra["compaction_failures"] == 3 # frozen at MAX_FAILURES+ assert "compaction" in ctx.extra+ assert len(result) < len(messages) # still compressed via fallback+++async def test_circuit_breaker_resets_on_llm_success() -> None:+ provider = _FakeSummaryProvider(reply="real summary")+ 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": 2}, # pre-seed: 2 prior failures+ )++ await middleware.transform_context(messages, ctx=ctx)+ assert ctx.extra["compaction_failures"] == 0 # reset after success+++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)+ 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_low_savings_count": 2}, # guard tripped+ )++ calls_before = len(provider.calls)+ await middleware.transform_context(messages, ctx=ctx)+ # Neither LLM nor fallback ran — early skip.+ assert len(provider.calls) == calls_before+ assert "compaction" not in ctx.extra+++async def test_anti_thrashing_emergency_override_when_raw_history_too_large() -> None:+ """When raw history >= 1.5 × threshold, the guard is overridden."""+ provider = _FakeSummaryProvider(reply="short summary")+ middleware = _make_middleware(provider, max_tokens_before=10)+ # Build a large enough history that raw tokens exceed 1.5 × 10 = 15.+ messages: list[Message] = [+ _user("x" * 100),+ _assistant("y" * 100),+ _user("z" * 100),+ _assistant("w" * 100),+ _user("a" * 100),+ _assistant("b" * 100),+ ]+ ctx = AgentContext(+ system_prompt="",+ messages=messages,+ extra={"compaction_low_savings_count": 2}, # guard tripped+ )++ calls_before = len(provider.calls)+ await middleware.transform_context(messages, ctx=ctx)+ # Emergency override fired despite the guard.+ assert len(provider.calls) > calls_before+ assert "compaction" in ctx.extra+++async def test_pruned_tool_results_do_not_break_state_refs() -> None:+ """Refs persisted in CompactionState come from ORIGINAL messages even+ when the transcript was built from pre-pruned content. Otherwise the+ next turn would see ref mismatch and clear the state, looping forever."""+ from cubepi.providers.base import ToolCall, ToolResultMessage++ provider = _FakeSummaryProvider(reply="real summary")+ middleware = _make_middleware(provider, max_tokens_before=1)+ big_result = "tool output line\n" * 200 # > 120 chars → pruner targets it+ messages: list[Message] = [+ _user("audit q"),+ AssistantMessage(+ content=[ToolCall(id="c1", name="audit_query", arguments={"q": "X"})]+ ),+ ToolResultMessage(+ tool_call_id="c1",+ tool_name="audit_query",+ content=[TextContent(text=big_result)],+ ),+ _user("what next?"),+ _assistant("fix it"),+ _user("ok"),+ ]+ ctx = AgentContext(system_prompt="", messages=messages, extra={})++ await middleware.transform_context(messages, ctx=ctx)+ boundary_after_first = ctx.extra["compaction_until_msg_index"]++ # Second turn with same messages: state must validate, not be cleared.+ await middleware.transform_context(messages, ctx=ctx)+ assert ctx.extra.get("compaction_until_msg_index", 0) >= boundary_after_first+ state = CompactionState.model_validate(ctx.extra["compaction"])+ assert state.is_fallback is False # real LLM summary+++def test_keep_recent_messages_no_longer_accepted() -> None:+ """Breaking change — old parameter name raises TypeError."""+ import pytest++ provider = _FakeSummaryProvider()+ with pytest.raises(TypeError):+ CompactionMiddleware(+ summary_model=BoundModel(+ provider=provider,+ spec=Model(id="m", provider_id="faux"),+ ),+ max_tokens_before_compact=100,+ keep_recent_messages=8, # type: ignore[call-arg]+ )diff --git a/tests/tracing/test_recorder.py b/tests/tracing/test_recorder.pyindex 0382a33..82d006f 100644--- a/tests/tracing/test_recorder.py+++ b/tests/tracing/test_recorder.py@@ -514,7 +514,7 @@ class TestMiddlewareProviders:mw = CompactionMiddleware(summary_model=BoundModel(provider=summarizer, spec=summary_model),max_tokens_before_compact=1,- keep_recent_messages=1,+ keep_tail_tokens=4,max_summary_tokens=128,min_compact_messages=2,)@@ -590,7 +590,7 @@ class TestMiddlewareProviders:mw = CompactionMiddleware(summary_model=BoundModel(provider=shared, spec=summary_model),max_tokens_before_compact=1,- keep_recent_messages=1,+ keep_tail_tokens=4,max_summary_tokens=128,min_compact_messages=2,)diff --git a/website/docs/guides/middleware/compaction.md b/website/docs/guides/middleware/compaction.mdindex e0a0ccc..8235b29 100644--- a/website/docs/guides/middleware/compaction.md+++ b/website/docs/guides/middleware/compaction.md@@ -29,15 +29,17 @@ agent = Agent(CompactionMiddleware(summary_model=summary_model,max_tokens_before_compact=80_000,- keep_recent_messages=8,- max_summary_tokens=1024,+ keep_tail_tokens=8_000, # token budget for the protected tail+ # max_summary_tokens=None → dynamic budget (recommended)),],)```-The summary call uses `Provider.generate(...)` with `temperature=0.0`,-`thinking="off"`, and `max_output_tokens=max_summary_tokens`.+The summary call uses `Provider.generate(...)` with `temperature=0.0` and+`thinking="off"`. `max_output_tokens` is computed dynamically from the+content size (floor 1024, ceiling 4096) when `max_summary_tokens` is `None`,+or passed verbatim otherwise.## What gets persisted@@ -59,16 +61,20 @@ Start with conservative values:CompactionMiddleware(summary_model=cheap_model,max_tokens_before_compact=80_000,- keep_recent_messages=8,- max_summary_tokens=1024,+ keep_tail_tokens=8_000,)```-Raise `max_tokens_before_compact` if your model has a large context window and-you want fewer summary calls. Raise `keep_recent_messages` when recent tool-outputs or user corrections are especially important. Increase-`max_summary_tokens` for long-running research or coding sessions where the-summary needs more detail.+Raise `max_tokens_before_compact` if your model has a large context window+and you want fewer summary calls. Raise `keep_tail_tokens` when recent tool+outputs or user corrections are especially important — the tail-token budget+is checked against `approx_tokens` per message, so it adapts to how heavy+the recent traffic actually is (a budget of 8 000 protects ~1–2 large tool+results, or 30+ short turns).++By default, `max_summary_tokens=None` means the summariser's output budget+is computed dynamically as `clamp(content_tokens × 0.15, 1024, 4096)`.+Override with an explicit int to pin the budget.## Tracing@@ -96,9 +102,18 @@ when summarization runs first.## Failure behavior-If the summary provider fails, CubePi logs a warning and continues with the-previous compressed view or the original messages. The agent run is not failed-only because compaction could not refresh.+If the summary provider fails, CubePi falls back to a deterministic, no-LLM+summary built from message structure (user-request first lines, distinct+tool names) so context still shrinks. After three consecutive LLM failures+a circuit breaker opens and skips the LLM entirely; the fallback keeps+running so the agent doesn't get stuck over-limit waiting for a broken+summariser model. The breaker resets the first time the LLM succeeds again.++A second guard tracks **anti-thrashing**: if compaction saves less than 10%+of context two runs in a row, the next attempt is skipped to avoid burning+LLM calls for no gain. The guard automatically lifts when raw history grows+past 1.5× the threshold, when the boundary would advance ≥ 8 messages, or+when a later compaction does save ≥ 10%.## When not to use itdiff --git a/website/docs/guides/middleware/examples.md b/website/docs/guides/middleware/examples.mdindex 3692090..f77180d 100644--- a/website/docs/guides/middleware/examples.md+++ b/website/docs/guides/middleware/examples.md@@ -189,7 +189,7 @@ agent = Agent(CompactionMiddleware(summary_model=summary_model,max_tokens_before_compact=80_000,- keep_recent_messages=8,+ keep_tail_tokens=8_000,),],)diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/compaction.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/compaction.mdindex b0eb081..cc78595 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/compaction.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/compaction.md@@ -25,15 +25,17 @@ agent = Agent(CompactionMiddleware(summary_model=summary_model,max_tokens_before_compact=80_000,- keep_recent_messages=8,- max_summary_tokens=1024,+ keep_tail_tokens=8_000, # 受保护尾部的 token 预算+ # max_summary_tokens=None → 动态预算(推荐)),],)```摘要调用使用 `Provider.generate(...)`,并设置 `temperature=0.0`、-`thinking="off"`、`max_output_tokens=max_summary_tokens`。+`thinking="off"`。当 `max_summary_tokens=None`(默认)时,+`max_output_tokens` 根据内容大小动态计算(下限 1024、上限 4096);+传入显式整数则原样使用。## 持久化内容@@ -54,14 +56,19 @@ middleware 会向 `AgentContext.extra` 写入两个键:CompactionMiddleware(summary_model=cheap_model,max_tokens_before_compact=80_000,- keep_recent_messages=8,- max_summary_tokens=1024,+ keep_tail_tokens=8_000,)```如果模型上下文很大、希望减少摘要调用,可以提高`max_tokens_before_compact`。如果最近工具输出或用户修正很重要,可以提高-`keep_recent_messages`。长时间研究或编码会话可提高 `max_summary_tokens`。+`keep_tail_tokens`——这是基于 `approx_tokens` 的 token 预算,+能根据近期流量自动适配(8 000 大约能保护 1–2 个大工具结果,或+30+ 条短消息)。++默认 `max_summary_tokens=None` 时,summariser 输出预算按+`clamp(content_tokens × 0.15, 1024, 4096)` 动态计算。传入显式整数+则原样固定。## Tracing@@ -85,8 +92,15 @@ agent 的主 provider/model,不会被先跑的 summarizer 覆盖。## 失败行为-如果摘要 provider 失败,CubePi 会记录 warning,并继续使用之前的压缩视图或-原始消息。agent 不会仅仅因为压缩刷新失败而失败。+如果摘要 provider 失败,CubePi 会用基于消息结构的**确定性 fallback**+(用户请求首行 + 出现过的工具名)来生成摘要,让上下文继续收缩。连续 3 次+LLM 失败后**熔断器**打开,跳过 LLM 调用——但 fallback 仍然运行,+agent 不会因为 summariser 模型故障而卡在超限状态。下一次 LLM 成功调用+会自动重置熔断器。++第二道防线是**防抖(anti-thrashing)**:如果连续两次压缩节省不到 10%,+下一次会跳过——避免在临界状态反复消耗 LLM 调用。当原始历史超过阈值的+1.5 倍、边界能前进 ≥ 8 条消息、或一次压缩节省 ≥ 10% 时,防抖会自动解除。## 什么时候不用