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): run-scoped compaction and real-token triggering
xf gongd7d8b51a353a
diff --git a/cubepi/middleware/compaction/__init__.py b/cubepi/middleware/compaction/__init__.pyindex 3912d33..0f72b1b 100644--- a/cubepi/middleware/compaction/__init__.py+++ b/cubepi/middleware/compaction/__init__.py@@ -22,7 +22,7 @@ from cubepi.middleware.compaction.summarizer import (build_fallback_summary,summarize,)-from cubepi.middleware.compaction.tokens import approx_tokens+from cubepi.middleware.compaction.tokens import approx_tokens, real_context_estimatefrom cubepi.providers.base import (BoundModel,Message,@@ -206,8 +206,13 @@ class CompactionMiddleware(Middleware):# for the summariser and the post-compaction tail; running it when no# compaction is needed would silently hide tool outputs from the main# model every turn, with no state recording the loss.+ #+ # The trigger uses ``real_context_estimate`` (anchored to the last+ # turn's real usage) rather than the char heuristic: under prompt+ # caching the true fill is dominated by cache_read tokens that a char+ # estimate has no way to see.unpruned_compressed = _compressed_view(messages, state, boundary)- tokens_now = approx_tokens(unpruned_compressed)+ tokens_now = real_context_estimate(unpruned_compressed)if tokens_now < self._max_tokens_before:return unpruned_compressed@@ -252,12 +257,15 @@ class CompactionMiddleware(Middleware):)# Anti-thrashing guard — uses raw_tokens so prior cumulative summaries- # don't mask a genuinely over-limit history.+ # don't mask a genuinely over-limit history. The emergency override also+ # checks ``tokens_now`` (the real, cache-aware fill we'd actually send):+ # under prompt caching the char-based ``raw_tokens`` can stay under the+ # 1.5× line while the true context is well over it, which would let the+ # low-savings guard keep skipping an over-threshold send.raw_tokens = approx_tokens(messages)low_savings = _load_int(ctx.extra.get("compaction_low_savings_count"), 0)- force_emergency = (- raw_tokens >= self._max_tokens_before * _ANTI_THRASH_FORCE_RATIO- )+ emergency_limit = self._max_tokens_before * _ANTI_THRASH_FORCE_RATIO+ force_emergency = raw_tokens >= emergency_limit or tokens_now >= emergency_limitenough_new = (new_boundary - boundary) >= _ANTI_THRASH_NEW_MSGSif low_savings >= _MAX_LOW_SAVINGS and not force_emergency and not enough_new:logger.debug("CompactionMiddleware: skipping — low savings guard active")diff --git a/cubepi/middleware/compaction/boundary.py b/cubepi/middleware/compaction/boundary.pyindex ba73851..9383044 100644--- a/cubepi/middleware/compaction/boundary.py+++ b/cubepi/middleware/compaction/boundary.py@@ -6,7 +6,6 @@ from cubepi.providers.base import (Message,ToolCall,ToolResultMessage,- UserMessage,)@@ -43,8 +42,19 @@ def safe_boundary(``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.+ are the protected tail; this function searches backward from there for the+ latest **self-contained turn boundary** — an index whose suffix+ ``messages[candidate:]`` has no orphaned tool-call/result pairs.++ Any message type may be a boundary as long as the suffix is self-contained;+ in practice this lands on a ``UserMessage`` or the ``AssistantMessage`` that+ starts the next turn. A ``ToolResultMessage`` can never be a boundary — a+ suffix beginning with a tool result orphans it, so it is rejected. This is+ what lets compaction advance *within* a single long run (a tool-call chain+ with no intervening user messages), not only between user turns. Suffix+ self-containment is the sole correctness rule: a result always follows its+ tool_use, so the only way to orphan a pair is a result whose call landed in+ the summarised prefix, which the check below rejects.Returns ``None`` when:- ``tail_start`` is out of range (negative, zero, or beyond ``messages``)@@ -61,9 +71,6 @@ def safe_boundary(candidate -= 1while candidate > 0:- if not isinstance(messages[candidate], UserMessage):- candidate -= 1- continueif not _suffix_is_self_contained(messages[candidate:]):candidate -= 1continuediff --git a/cubepi/middleware/compaction/tokens.py b/cubepi/middleware/compaction/tokens.pyindex c3cb46b..db575bf 100644--- a/cubepi/middleware/compaction/tokens.py+++ b/cubepi/middleware/compaction/tokens.py@@ -6,23 +6,28 @@ from cubepi.providers.base import (AssistantMessage,Message,TextContent,+ ThinkingContent,ToolCall,ToolResultMessage,UserMessage,)_CHARS_PER_TOKEN = 2.0-_SCALE_MIN_TOKENS = 100def approx_tokens(messages: list[Message]) -> int:- """Conservative token estimate for the exact message view sent to the LLM."""+ """Conservative char-based token estimate for a message view.++ A *relative*-sizing helper: used for tail budgeting, pruning decisions, and+ the summary budget, where a consistent estimator bias cancels out. For the+ compaction *trigger* (an absolute count compared against a threshold) use+ :func:`real_context_estimate` instead — it is anchored to real provider+ usage rather than a character heuristic.+ """if not messages:return 0total_chars = 0- scale_factor: float | None = None-for message in messages:if isinstance(message, UserMessage):for user_block in message.content:@@ -32,24 +37,51 @@ def approx_tokens(messages: list[Message]) -> int:for assistant_block in message.content:if isinstance(assistant_block, TextContent):total_chars += len(assistant_block.text)+ elif isinstance(assistant_block, ThinkingContent):+ # Thinking blocks are serialised back into the next request+ # (extended thinking + tool use), so they count toward the+ # next prompt — omitting them undercounts thinking-heavy runs.+ total_chars += len(assistant_block.thinking)elif isinstance(assistant_block, ToolCall):total_chars += len(json.dumps(assistant_block.arguments or {}))- usage = message.usage- if (- usage- and usage.input_tokens >= _SCALE_MIN_TOKENS- and scale_factor is None- ):- chars_estimate = usage.input_tokens * _CHARS_PER_TOKEN- if chars_estimate > 0:- raw_factor = total_chars / chars_estimate- scale_factor = max(1.0, min(raw_factor, 1.25))elif isinstance(message, ToolResultMessage):for result_block in message.content:if isinstance(result_block, TextContent):total_chars += len(result_block.text)- estimate = total_chars / _CHARS_PER_TOKEN- if scale_factor is not None:- return int(estimate * scale_factor)- return int(estimate)+ return int(total_chars / _CHARS_PER_TOKEN)+++def real_context_estimate(messages: list[Message]) -> int:+ """Best estimate of the true context fill, for the compaction trigger.++ Anchored to real provider usage: walks backward to the most recent+ ``AssistantMessage`` whose usage is a real measurement and takes that turn's+ actual prompt size — ``input_tokens + cache_read_tokens + cache_write_tokens``.+ cubepi normalises ``input_tokens`` to the *uncached* portion on every+ provider, so under prompt caching most of the prompt lives in the cache+ fields; all three must be summed or the count is a large undercount. The+ char estimate of everything from that assistant onward (its own output,+ which becomes input next turn, plus any messages appended since) is added on+ top.++ A zero-sum usage is *not* a measurement: error / abort / partial assistant+ messages carry ``usage=Usage()`` (see agent.py, faux.py, the *_responses+ providers). Anchoring on one would drop the entire earlier history from the+ estimate and silently stop compaction right after a failure, so the walk+ skips them and keeps looking for a real anchor.++ Falls back to :func:`approx_tokens` when no measured usage is present — the+ cold start before the first model response, or a tail of only zero-usage+ error messages.+ """+ for i in range(len(messages) - 1, -1, -1):+ message = messages[i]+ if isinstance(message, AssistantMessage) and message.usage is not None:+ usage = message.usage+ base = (+ usage.input_tokens + usage.cache_read_tokens + usage.cache_write_tokens+ )+ if base > 0:+ return base + approx_tokens(messages[i:])+ return approx_tokens(messages)diff --git a/dev/plans/2026-06-26-run-scoped-compaction.md b/dev/plans/2026-06-26-run-scoped-compaction.mdnew file mode 100644index 0000000..a0b60b8--- /dev/null+++ b/dev/plans/2026-06-26-run-scoped-compaction.md@@ -0,0 +1,186 @@+# Run-scoped Compaction & Real-token Triggering — Implementation Plan++> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.++**Goal:** Let `CompactionMiddleware` compress history *within* a single long+agentic run (not just between user turns), and trigger compaction on the *real*+context token count instead of a cache-blind char estimate.++**Spec:** [`dev/specs/2026-06-26-run-scoped-compaction.md`](../specs/2026-06-26-run-scoped-compaction.md)++**Architecture:** Two surgical changes inside `cubepi/middleware/compaction/`, no+`loop.py` / `agent.py` / public-API changes:+1. `boundary.py` — drop the `UserMessage`-only gate in `safe_boundary`; rely on+ the existing suffix self-containment check. Turn-boundary `AssistantMessage`+ cuts become legal, so the boundary advances inside a run.+2. `tokens.py` + `__init__.py` — add a real-token estimate that prefers the most+ recent `AssistantMessage.usage` (summing `input + cache_read + cache_write`)+ plus the estimated delta since; switch the trigger onto it; delete the+ `scale_factor` calibration (its only job was absolute-vs-threshold, now served+ by real numbers).++A third spec item (§2.3, oversized tool results) ships **docs only** — the+existing `after_tool_call` seam is the mechanism; no code.++**Tech Stack:** Python 3.11+, Pydantic v2, pytest (`asyncio_mode=auto`), mypy+strict, `FauxProvider` for deterministic runs.++---++## File Structure++- **Modify** `cubepi/middleware/compaction/boundary.py:42-74` — remove+ `UserMessage` gate in `safe_boundary`; reword docstring.+- **Modify** `cubepi/middleware/compaction/tokens.py` — remove `scale_factor`+ block (lines 15, 24, 37-46, 53-54); add `real_context_estimate(messages)`.+- **Modify** `cubepi/middleware/compaction/__init__.py:209-212` — switch trigger+ from `approx_tokens(...)` to `real_context_estimate(...)`.+- **Modify** `tests/middleware/compaction/test_boundary.py` (or equivalent) — add+ run-scoped boundary cases.+- **Modify/Create** `tests/middleware/compaction/test_tokens.py` — real-token+ estimate + calibration-removal cases.+- **Modify** `tests/middleware/compaction/test_*.py` — update any test asserting a+ `UserMessage` boundary or relying on the `scale_factor`.+- **Modify** `website/docs/guides/middleware/compaction.md` — document in-run+ compaction, real-token triggering, and the `after_tool_call` seam for oversized+ tool results.++> Confirm exact test-file paths first: `ls tests/middleware/compaction/`.++---++## Task 1: Run-scoped boundary (§2.1)++**Files:**+- Modify: `cubepi/middleware/compaction/boundary.py`+- Test: `tests/middleware/compaction/test_boundary.py`++- [ ] **Step 1: Write the failing tests**++ Build a message list that mimics a long run with **no intermediate+ `UserMessage`**: `User(open)`, then repeated `Assistant(tool_use)` ++ `ToolResult` pairs, plus a multi-tool turn (`Assistant(tool_use A, tool_use B)`,+ `ToolResult A`, `ToolResult B`). Assert:+ - `safe_boundary(msgs, tail_start=…)` returns an index pointing at a turn-start+ `AssistantMessage` (not pinned to the opening user message).+ - `_suffix_is_self_contained(msgs[boundary:])` holds for the returned index.+ - The boundary is never *between* `ToolResult A` and `ToolResult B`, and never+ between a `tool_use` and its `ToolResult` (parametrize over every index;+ accepted indices must all be self-contained).+ - `ToolResultMessage` indices are never returned.+ - Existing user-boundary behaviour still works (regression: a normal multi-run+ history still cuts cleanly).++- [ ] **Step 2: Implement**++ In `safe_boundary` (`boundary.py:63-72`), delete the gate:+ ```python+ if not isinstance(messages[candidate], UserMessage):+ candidate -= 1+ continue+ ```+ Keep the `_suffix_is_self_contained` check and the `min_compact` guard. Reword+ the docstring (`boundary.py:42-53`): "searches the prefix for the latest+ **self-contained turn boundary**" (drop the "latest `UserMessage`" wording).+ Remove the now-unused `UserMessage` import if nothing else uses it.++- [ ] **Step 3: Verify** — `uv run pytest tests/middleware/compaction/test_boundary.py -v`, `uv run mypy cubepi`, `uv run ruff check cubepi/ tests/`.++---++## Task 2: Real-token trigger + remove calibration (§2.2)++**Files:**+- Modify: `cubepi/middleware/compaction/tokens.py`, `cubepi/middleware/compaction/__init__.py`+- Test: `tests/middleware/compaction/test_tokens.py`++- [ ] **Step 1: Write the failing tests**++ - `real_context_estimate(messages)`:+ - With a trailing `AssistantMessage` carrying `usage`+ (`input_tokens=1000, cache_read_tokens=50_000, cache_write_tokens=2_000`)+ and two messages appended after it, returns+ `53_000 + approx_tokens(tail_two)` — i.e. **sums all three** usage fields,+ not `input_tokens` alone.+ - With **no** usage anywhere (cold start), falls back to+ `approx_tokens(messages)`.+ - Picks the **most recent** usage-bearing assistant when several exist.+ - `approx_tokens` no longer applies a scale factor: an `AssistantMessage` with+ `usage` produces the same value as one without (pure `chars/2`).+ - End-to-end via `FauxProvider` reporting cache usage (`faux.py:262-265`):+ compaction triggers when the *combined* real count crosses the threshold even+ though `input_tokens` alone is well under it.++- [ ] **Step 2: Implement**++ - `tokens.py`: add+ ```python+ def real_context_estimate(messages: list[Message]) -> int:+ # walk backward to the most recent AssistantMessage with usage;+ # base = usage.input_tokens + usage.cache_read_tokens + usage.cache_write_tokens+ # return base + approx_tokens(messages_after_that_assistant)+ # no usage anywhere -> approx_tokens(messages)+ ```+ - `tokens.py`: delete the calibration — `scale_factor` var (line 24), the+ `usage` lookup + clamp block (lines 37-46), the `* scale_factor` return path+ (lines 53-54), and `_SCALE_MIN_TOKENS` (line 15). `approx_tokens` becomes a+ pure char estimate. Keep the per-message-type char accounting intact.+ - `__init__.py:209-212`: replace the trigger+ ```python+ tokens_now = approx_tokens(unpruned_compressed)+ if tokens_now < self._max_tokens_before:+ ```+ with `tokens_now = real_context_estimate(unpruned_compressed)`. **Leave+ `raw_tokens` (anti-thrash, `__init__.py:256`), `tokens_after`+ (`__init__.py:346`), `tail_start_by_tokens`, and the summary budget on+ `approx_tokens`** — those are relative/budget decisions where a consistent+ bias cancels.++- [ ] **Step 3: Verify** — `uv run pytest tests/middleware/compaction/ -v`, `uv run mypy cubepi`, `uv run ruff check`. Note any tail-size drift caused by uncalibrated `approx_tokens` and confirm anti-thrash tests still pass (retune only if red — see Open Q2).++---++## Task 3 (CONDITIONAL — gated on spec Open Q1): threshold auto-binding++> Implement **only** if the user chooses to auto-default the threshold. Otherwise skip.++- [ ] Default `max_tokens_before_compact` from the bound model when omitted:+ `int(ratio * model.context_window)` (`providers/base.py:91`), ratio per the+ user's answer. Add a test that an unset threshold derives from `context_window`+ and an explicit threshold still wins. Document the default in the docs page.++---++## Task 4: Documentation (§2.3 seam + the two features)++**Files:**+- Modify: `website/docs/guides/middleware/compaction.md`++- [ ] **Step 1:** Document **in-run compaction** — compaction now advances the+ summary boundary at turn boundaries inside a single run, not only between user+ turns.+- [ ] **Step 2:** Document **real-token triggering** — the trigger uses the true+ context fill (`input + cache_read + cache_write` from the last turn's usage),+ so thresholds behave correctly under prompt caching.+- [ ] **Step 3:** Add a short **"Bounding oversized tool results"** note: this is+ the application's responsibility via an `after_tool_call` middleware (link+ `hooks.md`), because cubepi is environment-agnostic and cannot assume where to+ persist spilled content. Show a minimal sketch that previews + replaces a large+ result using `AfterToolCallResult.content`.++---++## Final verification++- [ ] `uv run pytest tests/` (full suite green).+- [ ] `uv run ruff check cubepi/ tests/` and `uv run ruff format --check cubepi/ tests/`.+- [ ] `uv run mypy cubepi`.+- [ ] Re-read the spec's §5 test-plan checklist; confirm every bullet has a test.+- [ ] Docs updated (feature is not done without docs — CLAUDE.md §4).++## Open decisions to confirm before/while implementing++1. **Threshold auto-binding** (Task 3) — do it now and with what ratio, or keep+ `max_tokens_before_compact` explicit?+2. **Anti-thrash tuning** — keep `_ANTI_THRASH_NEW_MSGS = 8` for the tighter+ in-run cadence (default: keep, verify via tests), or retune?diff --git a/dev/specs/2026-06-26-run-scoped-compaction.md b/dev/specs/2026-06-26-run-scoped-compaction.mdnew file mode 100644index 0000000..1274a88--- /dev/null+++ b/dev/specs/2026-06-26-run-scoped-compaction.md@@ -0,0 +1,246 @@+# Run-scoped Compaction, Real-token Triggering, and an Env-agnostic Tool-result Seam++- **Date**: 2026-06-26+- **Status**: Draft+- **Branch / worktree**: `2026-06-26-run-scoped-compaction` → `.worktrees/2026-06-26-run-scoped-compaction`+- **Related**: [`2026-06-08-compaction-improvements.md`](2026-06-08-compaction-improvements.md) (the+ pruner / circuit-breaker / anti-thrash machinery this spec builds on)++## 1. Motivation++`CompactionMiddleware` already summarises old history to keep long agents within+context. Its `transform_context` hook fires before **every** model call+(`loop.py:711`, inside the inner `while has_more_tool_calls` loop at+`loop.py:497`), so the *hook position* is already in the right place to compact+mid-run. Three real gaps remain:++| # | Gap | Impact |+|---|-----|--------|+| 1 | `safe_boundary` only cuts at a `UserMessage` (`boundary.py:64`) | A single long agentic **run** has no user messages in its tool-call chain, so the summary boundary is pinned to the run's opening prompt. The unbounded tool_use/tool_result chain inside the run is never compressed — compaction is effectively *between-run only*. |+| 2 | Trigger uses a char estimate calibrated with `usage.input_tokens` only (`tokens.py:40,43`) | Across **all** cubepi providers `input_tokens` is the *uncached* prompt portion; under prompt caching (the agent norm) most of the prompt is `cache_read` and never appears in `input_tokens`. The calibration silently degrades to a flat 1.25× multiplier and the trigger undercounts real context fill. |+| 3 | Oversized tool results have no bound, and cubepi has nowhere to put spilled content | A single huge tool result (the most-recent message, which the model must read this turn) cannot be compacted away — by definition it has to be sent. cubepi is **environment-agnostic**: it must not assume a filesystem / session dir / blob store, so it cannot implement claude-code's persist-to-disk strategy in core. |++This spec **implements (1) and (2)** — small, surgical changes inside the+compaction package. **(3) ships no code**: the seam already exists+(`after_tool_call`); this spec only documents that it is the supported mechanism+and records *why* cubepi can't do more in core.++---++## 2. Design++### 2.1 Run-scoped compaction — let the boundary advance within a run++**Current behaviour** (`boundary.py:63-72`):++```python+while candidate > 0:+ if not isinstance(messages[candidate], UserMessage): # ← the restriction+ candidate -= 1+ continue+ if not _suffix_is_self_contained(messages[candidate:]):+ candidate -= 1+ continue+ if candidate < min_compact:+ return None+ return candidate+```++A run's message shape is `User(open) → Assistant(tool_use) → ToolResult →+Assistant(tool_use) → ToolResult → …` with **no `UserMessage` in between**. So+the only candidate is the run's opening prompt; the growing tail is never cut.++**Fix**: drop the `isinstance(..., UserMessage)` gate entirely. The boundary then+lands on the first self-contained suffix start walking back from `tail_start` —+which is a turn-boundary `AssistantMessage` when no user message is nearby.++```python+while candidate > 0:+ if not _suffix_is_self_contained(messages[candidate:]):+ candidate -= 1+ continue+ if candidate < min_compact:+ return None+ return candidate+```++**Why this is correct (and why we don't need the UserMessage anchor).**+The only invariant the provider requires after compaction is that+`[summary_user, *messages[boundary:]]` has no orphaned tool_use/tool_result.+`_suffix_is_self_contained` (`boundary.py:77`) already guarantees this:++- Candidate is a `ToolResultMessage` → suffix starts with a tool_result whose id+ is not yet in `available_call_ids` → rejected. ✅ (so ToolResultMessage can+ never be a cut point — the "add tool-result as candidate" idea is subsumed and+ correctly excluded.)+- Candidate splits a multi-tool turn between `ToolResult A | ToolResult B` →+ suffix starts with the orphan `ToolResult B` → rejected. ✅+- Candidate is a turn-start `AssistantMessage` (all its tool_use results follow+ it) → self-contained → accepted. ✅+- "tool_use in suffix, its result in prefix" is impossible: a result always+ follows its tool_use in message order, so `tool_use_index ≥ boundary ⇒+ result_index ≥ boundary`. ✅++Therefore the `UserMessage` check was a *semantic* anchor (summaries end at a+conversational turn), never a correctness requirement. Removing it also gives a+boundary **closer to the tail** (the first self-contained point, not the latest+user turn) → larger summarised region → more aggressive in-run compaction, which+is exactly the goal.++**Side effects / required follow-ups:**++- **Docstring** (`boundary.py:42-53`) currently says "searches the prefix for the+ latest `UserMessage`" — reword to "latest self-contained turn boundary".+- **Semantic shift**: the summary may now end mid-run (after a tool turn) rather+ than at a user turn. For agentic runs this reads naturally (`[summary_user,+ assistant_continues_acting, …]`). Confirm `summarize`'s handoff prompt+ (`summarizer.py`) produces coherent text for a half-run tool chain.+- **Residual case (out of scope here, see §2.3)**: if a *single* turn is itself+ larger than the context budget (100 parallel tool calls, or one giant tool+ result), it is atomic and cannot be split by any boundary. That is a+ tool-output-bounding problem, not a boundary problem.++### 2.2 Trigger on real tokens; remove the calibration++**Current behaviour.** The trigger compares `approx_tokens(unpruned_compressed)`+(char-based, `chars/2`) against the configured threshold (`__init__.py:210-211`).+`usage` is consulted only to compute a calibration `scale_factor`, and only from+`usage.input_tokens` (`tokens.py:37-46`), clamped to `[1.0, 1.25]`.++**Problem.** cubepi normalises `Usage.input_tokens` to the **uncached** prompt+portion on every provider:++- Anthropic (`anthropic.py:790-795`): `input_tokens` is natively cache-excluded;+ `cache_read_tokens = cache_read_input_tokens`, `cache_write_tokens =+ cache_creation_input_tokens`.+- OpenAI (`openai.py:258-265`): `input_tokens = max(prompt_tokens -+ cached_tokens, 0)`.+- OpenAI Responses (`openai_responses.py:539`), Faux (`faux.py:253`): same.++So the real prompt fill is `input_tokens + cache_read_tokens ++cache_write_tokens`. Using `input_tokens` alone undercounts massively whenever+caching is on, and the `[1.0, 1.25]` clamp masks the bug by pinning the factor at+1.25.++**Decision: switch the trigger to the real token count and delete the calibration+entirely** (path *b* from the design discussion, not "fix the calibration to use+all three").++Rationale — calibration's *only* job is to make an **absolute** char estimate+match reality for comparison against an **absolute** threshold. Once the trigger+uses the real number, every other use of `approx_tokens` is a **relative**+decision (where to cut, what to prune, the summary budget) where a consistent+estimator bias cancels. A bounded "nudge up 0–25%" heuristic with a known+scope-mismatch (numerator counts the assistant's own output; the real+`input_tokens` does not, but does include system prompt + tool defs) adds nothing+there and is a liability to maintain.++**New trigger:**++```+real_last = usage.input_tokens + usage.cache_read_tokens + usage.cache_write_tokens+ # from the most recent AssistantMessage that carries usage+estimate = real_last + approx_tokens(messages_appended_since_that_assistant)+compact if estimate >= threshold+```++- `messages_appended_since` is a small delta (the assistant + its tool results);+ over-estimating it only triggers compaction slightly early — safe.+- **Cold start**: the first `transform_context` has no assistant/usage yet → fall+ back to `approx_tokens` over the whole view. So `approx_tokens` stays, but+ *uncalibrated*: delete the `scale_factor` block (`tokens.py:24,37-46,53-54`),+ keep the plain `chars/2` path for relative sizing and cold start.++**Threshold sourcing (smaller, optional).** `max_tokens_before_compact` remains a+constructor arg, but we can default it from the bound model when omitted:+`threshold = int(ratio * model.context_window)` (`Model.context_window`,+`providers/base.py:91`; default ratio TBD, e.g. 0.75). This removes the "swap+model, forget to retune the threshold" footgun. Marked optional — confirm in+review whether to bind it now or keep it explicit.++### 2.3 Env-agnostic tool-result seam++**Why this can't live in cubepi core.** claude-code bounds tool output with a+persist-to-disk + 2000-byte-preview strategy (`toolResultStorage.ts`), and+Read throws-and-paginates. Both assume an environment: a session directory, a+readable filesystem, a `Read` tool to fetch the spilled file. **cubepi is+environment-agnostic** — core must not assume a filesystem, a session dir, or a+blob store. *Where* an oversized result goes (disk, object storage, a database+row, dropped) is an upper-layer decision.++**Divergence call-out (per CLAUDE.md):** claude-code does X (persist to a session+dir, hand back a path the model can `Read`); cubepi does Y (detect oversize in a+middleware, delegate the sink to the application) because Z (cubepi has no+environment to persist into and must stay dependency-/env-lean).++**The seam already exists.** `Middleware.after_tool_call` (`base.py:59`) receives+`AfterToolCallContext` (`types.py:91-97`: `tool_call`, `args`, `result`,+`is_error`, `context`) and may return `AfterToolCallResult` (`types.py:75-79`:+`content`, `details`, `is_error`, `terminate`). An application can already+implement an `after_tool_call` middleware that:++1. measures the result's text size,+2. ships the full bytes wherever it wants (its environment's choice),+3. returns an `AfterToolCallResult` whose `content` is a preview + a reference+ the app understands.++cubepi never sees the storage. This satisfies "reserve a mechanism for the upper+layer to do the handling itself."++**Scope decision: ship no code for this.** We do *not* add a `ToolResultGuard`+middleware or a `ToolResultSink` protocol. The existing `after_tool_call` seam is+sufficient and any helper would have to bake in a preview/size policy that is+itself application-specific. This spec's only deliverable here is **documentation**:+a short note in the compaction / middleware docs stating that bounding oversized+tool results is an `after_tool_call` middleware responsibility owned by the+application, with the env-agnostic rationale above. No core change, no new types.++This is orthogonal to §2.1/§2.2: §2.1 handles the common case (many+normal-sized turns); the pathological single giant result that compaction+provably cannot fix is the application's job via the documented seam.++---++## 3. Non-goals++- Mid-tool-pair cutting (splitting inside a tool_use/tool_result pair). Rejected+ as risky; §2.1's turn-boundary cutting is sufficient and provably safe.+- Any new tool-result middleware/type (`ToolResultGuard` / `ToolResultSink`).+ Core stays env-agnostic; the existing `after_tool_call` seam is the mechanism+ and we only document it.+- Post-compaction context re-injection (re-reading touched files) — already ruled+ out in `2026-06-08-compaction-improvements.md` §1 as application-specific.+- Dynamic per-tool caps computed from context-window size. claude-code uses fixed+ per-tool constants + env/flag overrides; we follow that — the cap is the app's+ policy, not context-relative math.++## 4. Open questions (spec stage — to confirm with the user)++1. **Threshold auto-binding (§2.2)**: default `max_tokens_before_compact` from+ `model.context_window * ratio` now, or keep it explicit? If now, what ratio?+2. **Anti-thrash tuning (§2.1)**: with the boundary advancing ~2 messages/turn,+ `_ANTI_THRASH_NEW_MSGS = 8` (`__init__.py:50`) gates how often in-run+ compaction fires. Keep 8, or retune for the tighter in-run cadence? (Leaning+ keep — verify via tests rather than guess.)++## 5. Test plan (FauxProvider)++- **2.1** — A run with a pure tool-call chain (no intermediate UserMessage)+ compacts at a turn boundary; the cut never orphans a tool_use/tool_result;+ multi-tool-per-turn is never split between results; `ctx.extra["compaction"]`+ state accumulates correctly across in-run turns; `_state_matches_history`+ (`__init__.py:118`) still validates after an in-run cut.+- **2.2** — With `FauxProvider` reporting cache_read/cache_write usage+ (`faux.py:262-265`), the trigger fires at the real combined token count, not the+ uncached `input_tokens`; cold-start (no usage yet) falls back to the estimate;+ `scale_factor` is gone and relative decisions (tail, prune, budget) are+ unaffected.+- **2.3** — No code, no test. Documentation only (the `after_tool_call` seam).++## 6. Rollout / compatibility++- §2.1 changes default boundary placement — existing callers get *more* in-run+ compaction automatically. Update any test asserting a UserMessage boundary.+- §2.2 removes `scale_factor`; behaviour-visible only when caching is active+ (compaction now triggers nearer the true limit). No API change.+- §2.3 ships no code — docs only; no behavioural or API change.diff --git a/tests/middleware/compaction/test_boundary.py b/tests/middleware/compaction/test_boundary.pyindex 1bdeaa2..6fdaec6 100644--- a/tests/middleware/compaction/test_boundary.py+++ b/tests/middleware/compaction/test_boundary.py@@ -77,7 +77,7 @@ def test_rejects_suffix_with_orphan_tool_result() -> None:assert safe_boundary(messages, tail_start=4, min_compact=1) is None-def test_accepts_suffix_with_matching_tool_call_and_result() -> None:+def test_accepts_assistant_turn_start_as_boundary() -> None:call = ToolCall(id="c1", name="search", arguments={})messages: list[Message] = [_user("q1"),@@ -87,10 +87,11 @@ def test_accepts_suffix_with_matching_tool_call_and_result() -> None:_tool_result("c1"),_assistant("done"),]- # 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+ # tail_start=3 is the assistant that opens a tool turn. Its suffix+ # [assistant(c1), tool_result(c1), assistant(done)] is self-contained, so+ # the boundary lands there (closest to the tail) rather than walking all the+ # way back to the user message at index 2.+ assert safe_boundary(messages, tail_start=3, min_compact=1) == 3def test_enforces_min_compact() -> None:@@ -150,8 +151,9 @@ def test_safe_boundary_using_tail_start_by_tokens() -> None:]tail_start = tail_start_by_tokens(messages, budget=1) # tiny budget → tail=5assert 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+ # safe_boundary walks back to the latest self-contained turn boundary <= 5;+ # the last assistant (index 5) has a self-contained suffix, so it wins.+ assert safe_boundary(messages, tail_start=tail_start, min_compact=1) == 5def test_safe_boundary_rejects_out_of_range_tail_start() -> None:@@ -170,5 +172,79 @@ def test_safe_boundary_tail_start_equals_len_clamps_in_bounds() -> None:_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+ # tail_start == 4 == len(messages). Clamp to 3; index 3 (assistant a2) has a+ # self-contained suffix, so the boundary lands there.+ assert safe_boundary(messages, tail_start=4, min_compact=1) == 3+++# --- run-scoped compaction: cut at turn boundaries inside a single run ---+++def _run_with_tool_chain() -> list[Message]:+ """A long run with NO intervening UserMessage — just a tool-call chain."""+ return [+ _user("open"),+ _assistant(tool_calls=[ToolCall(id="c1", name="t", arguments={})]),+ _tool_result("c1"),+ _assistant(tool_calls=[ToolCall(id="c2", name="t", arguments={})]),+ _tool_result("c2"),+ _assistant(tool_calls=[ToolCall(id="c3", name="t", arguments={})]),+ _tool_result("c3"),+ ]+++def test_run_scoped_cut_lands_on_inner_turn_not_run_start() -> None:+ messages = _run_with_tool_chain()+ # Protect only the last turn ([a(c3), tool_result c3]); the boundary must+ # advance to the assistant that opens that turn (index 5), NOT stay pinned to+ # the run's opening user message at index 0.+ boundary = safe_boundary(messages, tail_start=5, min_compact=1)+ assert boundary == 5+ assert _is_self_contained(messages[boundary:])+++def test_run_scoped_never_splits_a_multi_tool_turn() -> None:+ messages: list[Message] = [+ _user("open"),+ _assistant(+ tool_calls=[+ ToolCall(id="A", name="t", arguments={}),+ ToolCall(id="B", name="t", arguments={}),+ ]+ ),+ _tool_result("A"),+ _tool_result("B"),+ _assistant(tool_calls=[ToolCall(id="C", name="t", arguments={})]),+ _tool_result("C"),+ ]+ # Searching back from the tail must skip the tool_result for C (orphan) and+ # land on the assistant opening the C turn (index 4) — never between the A/B+ # results of the multi-tool turn.+ boundary = safe_boundary(messages, tail_start=5, min_compact=1)+ assert boundary == 4+ assert _is_self_contained(messages[boundary:])+++def test_every_returned_boundary_is_self_contained() -> None:+ """Core invariant: whatever index safe_boundary returns, the kept suffix+ never orphans a tool_use/tool_result pair — across every tail_start."""+ messages = _run_with_tool_chain()+ for tail_start in range(1, len(messages) + 1):+ boundary = safe_boundary(messages, tail_start=tail_start, min_compact=1)+ if boundary is None:+ continue+ assert not isinstance(messages[boundary], ToolResultMessage)+ assert _is_self_contained(messages[boundary:])+++def _is_self_contained(suffix: list[Message]) -> bool:+ available: set[str] = set()+ for message in suffix:+ if isinstance(message, AssistantMessage):+ for block in message.content:+ if isinstance(block, ToolCall) and block.id:+ available.add(block.id)+ elif isinstance(message, ToolResultMessage):+ if message.tool_call_id and message.tool_call_id not in available:+ return False+ return Truediff --git a/tests/middleware/compaction/test_tokens.py b/tests/middleware/compaction/test_tokens.pyindex b12d929..7dd12ab 100644--- a/tests/middleware/compaction/test_tokens.py+++ b/tests/middleware/compaction/test_tokens.py@@ -1,9 +1,13 @@from __future__ import annotations-from cubepi.middleware.compaction.tokens import approx_tokens+from cubepi.middleware.compaction.tokens import (+ approx_tokens,+ real_context_estimate,+)from cubepi.providers.base import (AssistantMessage,TextContent,+ ThinkingContent,ToolCall,ToolResultMessage,Usage,@@ -21,7 +25,9 @@ def test_text_chars_use_conservative_cjk_safe_estimate() -> None:assert approx_tokens(messages) == 100-def test_usage_metadata_scales_estimate_up() -> None:+def test_usage_metadata_does_not_scale_estimate() -> None:+ # approx_tokens is now a pure char estimate — usage no longer calibrates it.+ # (1000 chars / 2 = 500, regardless of the reported usage.)messages = [UserMessage(content=[TextContent(text="x" * 900)]),AssistantMessage(@@ -30,7 +36,7 @@ def test_usage_metadata_scales_estimate_up() -> None:),]- assert approx_tokens(messages) == 625+ assert approx_tokens(messages) == 500def test_tool_result_text_is_counted() -> None:@@ -45,6 +51,14 @@ def test_tool_result_text_is_counted() -> None:assert approx_tokens(messages) == 100+def test_thinking_content_is_counted() -> None:+ # Thinking blocks are serialised back into the next request, so they count+ # toward the prompt — omitting them undercounts thinking-heavy runs.+ messages = [AssistantMessage(content=[ThinkingContent(thinking="x" * 200)])]++ assert approx_tokens(messages) == 100++def test_tool_call_arguments_are_counted() -> None:messages = [AssistantMessage(@@ -59,3 +73,80 @@ def test_tool_call_arguments_are_counted() -> None:]assert approx_tokens(messages) > 0+++# --- real_context_estimate: trigger anchored to real provider usage ---+++def test_real_estimate_sums_all_usage_fields() -> None:+ # Under prompt caching most of the prompt is cache_read; input_tokens alone+ # is a large undercount. The estimate must sum input + cache_read + cache_write.+ messages = [+ UserMessage(content=[TextContent(text="x" * 1000)]),+ AssistantMessage(+ content=[],+ usage=Usage(+ input_tokens=1_000,+ cache_read_tokens=50_000,+ cache_write_tokens=2_000,+ ),+ ),+ ]+ # base = 1000 + 50000 + 2000 = 53000; the trailing assistant has empty+ # content so the char delta from it is 0.+ assert real_context_estimate(messages) == 53_000+++def test_real_estimate_adds_char_delta_from_last_usage_onward() -> None:+ messages = [+ AssistantMessage(content=[], usage=Usage(input_tokens=10_000)),+ UserMessage(content=[TextContent(text="x" * 400)]), # 200 tokens+ ToolResultMessage(+ tool_call_id="c1",+ tool_name="t",+ content=[TextContent(text="x" * 200)], # 100 tokens+ ),+ ]+ # base=10000 (only input present) + approx_tokens(messages[0:]) = 300.+ assert real_context_estimate(messages) == 10_300+++def test_real_estimate_uses_most_recent_usage() -> None:+ messages = [+ AssistantMessage(content=[], usage=Usage(input_tokens=5_000)),+ UserMessage(content=[TextContent(text="x" * 100)]),+ AssistantMessage(content=[], usage=Usage(input_tokens=20_000)),+ ]+ # The most recent usage-bearing assistant (index 2) wins; nothing follows it.+ assert real_context_estimate(messages) == 20_000+++def test_real_estimate_cold_start_falls_back_to_approx() -> None:+ messages = [UserMessage(content=[TextContent(text="x" * 200)])] # no usage+ assert real_context_estimate(messages) == approx_tokens(messages) == 100+++def test_real_estimate_skips_zero_usage_error_assistant() -> None:+ # error/abort/partial assistants carry usage=Usage() (all zeros). Anchoring+ # on one would drop the earlier history and stop compaction after a failure.+ messages = [+ UserMessage(content=[TextContent(text="x" * 1000)]),+ AssistantMessage(content=[], usage=Usage(input_tokens=80_000)),+ ToolResultMessage(+ tool_call_id="c",+ tool_name="t",+ content=[TextContent(text="x" * 200)], # 100 tokens+ ),+ AssistantMessage(content=[TextContent(text="boom")], usage=Usage()), # zero-sum+ ]+ # Anchors on the real 80_000 at index 1, not the zero error at index 3:+ # 80000 + approx_tokens(messages[1:]) = 80000 + (0 + 100 + 2) = 80102.+ assert real_context_estimate(messages) == 80_102+++def test_real_estimate_only_zero_usage_falls_back_to_approx() -> None:+ messages = [+ UserMessage(content=[TextContent(text="x" * 200)]), # 100 tokens+ AssistantMessage(content=[], usage=Usage()), # zero-sum, not an anchor+ ]+ assert real_context_estimate(messages) == approx_tokens(messages) == 100diff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.pyindex dd412a0..67527b0 100644--- a/tests/middleware/test_compaction.py+++ b/tests/middleware/test_compaction.py@@ -19,6 +19,7 @@ from cubepi.providers.base import (StreamOptions,TextContent,ToolDefinition,+ Usage,UserMessage,)@@ -421,6 +422,37 @@ async def test_anti_thrashing_emergency_override_when_raw_history_too_large() ->assert "compaction" in ctx.extra+async def test_anti_thrashing_emergency_override_when_real_tokens_too_large() -> None:+ """Cache-aware emergency: char-based raw_tokens stays under 1.5×, but the+ real fill (dominated by cache_read) is over it, so the guard is overridden.+ The old raw-only check would have let the guard keep skipping."""+ provider = _FakeSummaryProvider(reply="short summary")+ middleware = _make_middleware(provider, max_tokens_before=200)+ messages: list[Message] = [+ _user("turn 1"),+ _assistant("reply 1"),+ _user("turn 2"),+ _assistant("reply 2"),+ _user("turn 3"),+ AssistantMessage(+ content=[TextContent(text="reply 3")],+ usage=Usage(cache_read_tokens=500), # real fill lives in the cache+ ),+ ]+ ctx = AgentContext(+ system_prompt="",+ messages=messages,+ extra={"compaction_low_savings_count": 2}, # guard tripped+ )++ # raw_tokens (~19) is far under 1.5 * 200 = 300, so the raw-only emergency+ # check does NOT fire; the real estimate (>=500, cache-aware) does.+ calls_before = len(provider.calls)+ await middleware.transform_context(messages, ctx=ctx)+ 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 evenwhen the transcript was built from pre-pruned content. Otherwise thediff --git a/website/docs/guides/middleware/compaction.md b/website/docs/guides/middleware/compaction.mdindex d428cd3..3bb54b4 100644--- a/website/docs/guides/middleware/compaction.md+++ b/website/docs/guides/middleware/compaction.md@@ -53,6 +53,26 @@ next process can resume with the existing summary. If the message refs no longermatch the current history, the middleware clears the stale state and starts overrather than sending an invalid summary.+## How compaction triggers++Compaction is evaluated **before every model call** — including the calls *inside*+a single agent turn, between tool-call iterations — along two dimensions:++- **Real-token threshold.** The trigger compares the *true* context fill against+ `max_tokens_before_compact`. CubePi anchors the estimate to the last turn's+ actual provider usage — `input_tokens + cache_read_tokens + cache_write_tokens`+ — so it stays accurate under prompt caching, where most of the prompt is served+ from cache and would be invisible to a character-only estimate. Before the first+ model response (no usage yet), it falls back to a character estimate. Zero-usage+ error/abort messages are skipped so a failure never resets the estimate.++- **In-run boundaries.** The summary boundary advances at any self-contained+ *turn boundary*, not only at user messages. A long agentic run — one user prompt+ followed by many tool-call iterations with no intervening user message — is+ compacted *as it grows*, cutting between complete tool turns. The middleware+ never splits a `tool_use` from its `tool_result`, so the compressed view always+ stays valid for the provider.+## Choosing thresholdsStart with conservative values:@@ -256,9 +276,53 @@ 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%.+LLM calls for no gain. The guard automatically lifts when the context grows+past 1.5× the threshold — measured by either the raw character estimate or the+real cache-aware token count, so prompt caching can't hide a genuinely+over-limit context — when the boundary would advance ≥ 8 messages, or when a+later compaction does save ≥ 10%.++## Bounding oversized tool results++Compaction summarizes *old* history, but it can't shrink a single tool result+that the model must read on the **current** turn — if one tool returns more than+the context window holds, no summary helps. Bounding that is the *application's*+job, because CubePi is environment-agnostic: it has no filesystem, session+directory, or blob store to spill overflow into, and where overflow goes is your+call.++The seam is the `after_tool_call` middleware hook. Inspect the result, persist+the full content wherever your environment keeps it, and return a replacement+that previews the content plus a reference the model can follow:++```python+from cubepi.middleware import Middleware+from cubepi.agent.types import AfterToolCallContext, AfterToolCallResult+from cubepi.providers.base import TextContent++class BoundToolResults(Middleware):+ def __init__(self, *, max_chars: int = 20_000) -> None:+ self._max_chars = max_chars++ async def after_tool_call(self, ctx: AfterToolCallContext, *, signal=None):+ text = "".join(+ b.text for b in ctx.result.content if isinstance(b, TextContent)+ )+ if len(text) <= self._max_chars:+ return None # pass through unchanged++ ref = my_store.put(text) # YOUR environment decides where+ preview = text[: self._max_chars]+ return AfterToolCallResult(+ content=[TextContent(text=f"{preview}\n\n[full output stored: {ref}]")],+ is_error=ctx.result.is_error,+ terminate=ctx.result.terminate,+ )+```++CubePi never inspects `ref` — a disk path, object-store key, database id, or a+plain truncation marker are all equally valid. This keeps tool-output policy in+the layer that actually owns the environment.## When not to use itdiff --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 627659e..530ed11 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@@ -48,6 +48,23 @@ middleware 会向 `AgentContext.extra` 写入两个键:`ctx.extra`,所以下一个进程可以带着已有摘要继续。如果消息引用与当前历史不再匹配,middleware 会清除旧状态并重新开始,而不是发送无效摘要。+## 压缩触发机制++压缩在**每次模型调用前**评估——包括单个 agent turn *内部*、多轮工具调用+之间的那些调用——并沿两个维度触发:++- **真实 token 阈值。** 触发判据用*真实*上下文占用与 `max_tokens_before_compact`+ 比较。CubePi 把估算锚定到上一轮的真实 provider usage ——+ `input_tokens + cache_read_tokens + cache_write_tokens` ——所以在 prompt+ caching 下依然准确(此时大部分 prompt 由缓存提供,纯字符估算根本看不到)。+ 首次模型响应前(还没有 usage)回退到字符估算。零值的 error/abort 消息会被+ 跳过,因此一次失败不会重置估算。++- **run 内边界。** 摘要边界可以在任何**自洽的 turn 边界**前移,不再只限于用户+ 消息。一个长 agentic run ——一条用户 prompt 后跟着多轮工具调用、中间没有用户+ 消息——会*随着增长被压缩*,在完整的工具 turn 之间切分。middleware 绝不会把+ `tool_use` 和它的 `tool_result` 切开,所以压缩后的视图对 provider 始终合法。+## 阈值选择先用保守值:@@ -165,8 +182,48 @@ agent 不会因为 summariser 模型故障而卡在超限状态。下一次 LLM会自动重置熔断器。第二道防线是**防抖(anti-thrashing)**:如果连续两次压缩节省不到 10%,-下一次会跳过——避免在临界状态反复消耗 LLM 调用。当原始历史超过阈值的-1.5 倍、边界能前进 ≥ 8 条消息、或一次压缩节省 ≥ 10% 时,防抖会自动解除。+下一次会跳过——避免在临界状态反复消耗 LLM 调用。当上下文超过阈值的 1.5 倍时+防抖会自动解除——这里用字符估算或真实 cache-aware token 数二者之一衡量,+所以 prompt caching 无法掩盖一个真正超限的上下文;此外边界能前进 ≥ 8 条消息、+或一次压缩节省 ≥ 10% 时也会解除。++## 限制超大工具结果++压缩总结的是*旧*历史,但它无法缩小一个模型在**当前**轮必须读取的单个工具+结果——如果某个工具返回的内容超过上下文窗口能容纳的量,再多摘要也无济于事。+限制它是*上层应用*的职责,因为 CubePi 是环境无关的:它没有文件系统、会话目录+或对象存储可以把溢出内容写进去,而内容落到哪里由你决定。++接入点是 `after_tool_call` middleware hook。检查结果、把完整内容持久化到你的+环境里,再返回一个包含预览 + 模型可追溯引用的替换内容:++```python+from cubepi.middleware import Middleware+from cubepi.agent.types import AfterToolCallContext, AfterToolCallResult+from cubepi.providers.base import TextContent++class BoundToolResults(Middleware):+ def __init__(self, *, max_chars: int = 20_000) -> None:+ self._max_chars = max_chars++ async def after_tool_call(self, ctx: AfterToolCallContext, *, signal=None):+ text = "".join(+ b.text for b in ctx.result.content if isinstance(b, TextContent)+ )+ if len(text) <= self._max_chars:+ return None # 原样放行++ ref = my_store.put(text) # 由你的环境决定存到哪+ preview = text[: self._max_chars]+ return AfterToolCallResult(+ content=[TextContent(text=f"{preview}\n\n[full output stored: {ref}]")],+ is_error=ctx.result.is_error,+ terminate=ctx.result.terminate,+ )+```++CubePi 从不解析 `ref` ——磁盘路径、对象存储 key、数据库 id,或一个纯截断标记+都同样有效。这样工具输出策略就留在真正掌握环境的那一层。## 什么时候不用