Skip to content

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

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__.py
index 9d9b9ff..ef515ae 100644
--- a/cubepi/middleware/compaction/__init__.py
+++ b/cubepi/middleware/compaction/__init__.py
@@ -1,16 +1,23 @@
from __future__ import annotations
-import logging
import asyncio
+import logging
from typing import Any
from pydantic import ValidationError
from cubepi.agent.types import AgentContext
from 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_results
from 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_tokens
from 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_model
self._max_tokens_before = max_tokens_before_compact
- self._keep_recent = keep_recent_messages
+ self._keep_tail_tokens = keep_tail_tokens
self._max_summary_tokens = max_summary_tokens
self._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 = 0
state = 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 result
def 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.py
index 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[Mess
continue
summary = 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 result
diff --git a/cubepi/middleware/compaction/summarizer.py b/cubepi/middleware/compaction/summarizer.py
index 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.py
index 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 000
diff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.py
index 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 == messages
assert "compaction" not in ctx.extra
assert "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.py
index 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.md
index 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 it
diff --git a/website/docs/guides/middleware/examples.md b/website/docs/guides/middleware/examples.md
index 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.md
index 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% 时,防抖会自动解除。
## 什么时候不用