CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
fix(compaction): preserve evidence before synthetic controls
Cue4716392ee8a2
diff --git a/cubepi/middleware/compaction/__init__.py b/cubepi/middleware/compaction/__init__.pyindex 0f72b1b..eacc609 100644--- a/cubepi/middleware/compaction/__init__.py+++ b/cubepi/middleware/compaction/__init__.py@@ -26,6 +26,8 @@ from cubepi.middleware.compaction.tokens import approx_tokens, real_context_estifrom cubepi.providers.base import (BoundModel,Message,+ UserMessage,+ is_synthetic_message,synthetic_user_message,)@@ -76,6 +78,28 @@ def _compressed_view(return list(messages)+def _split_trailing_synthetic_user_controls(+ messages: list[Message],+) -> tuple[list[Message], list[UserMessage]]:+ """Separate call-local user controls from the history they follow.++ Only the maximal trailing suffix is detached. Internal synthetic messages+ remain ordinary history, and synthetic tool results are never separated+ from their tool calls.+ """+ split_at = len(messages)+ trailing_controls: list[UserMessage] = []+ while split_at > 0:+ message = messages[split_at - 1]+ if not isinstance(message, UserMessage) or not is_synthetic_message(message):+ break+ trailing_controls.append(message)+ split_at -= 1++ trailing_controls.reverse()+ return list(messages[:split_at]), trailing_controls++def _load_state(value: Any) -> CompactionState | None:if value is None:return None@@ -174,6 +198,7 @@ class CompactionMiddleware(Middleware):ctx: AgentContext,signal: asyncio.Event | None = None,) -> list[Message]:+ history, trailing_controls = _split_trailing_synthetic_user_controls(messages)state = _load_state(ctx.extra.get("compaction"))raw_boundary = ctx.extra.get("compaction_until_msg_index")boundary = (@@ -183,8 +208,8 @@ class CompactionMiddleware(Middleware):if state is None and ("compaction" in ctx.extra or boundary > 0):boundary = 0_clear_state(ctx)- if boundary >= len(messages) or not _state_matches_history(- messages, state, boundary+ if boundary >= len(history) or not _state_matches_history(+ history, state, boundary):boundary = 0state = None@@ -200,7 +225,7 @@ class CompactionMiddleware(Middleware):effective_tail_tokens = max(1, self._max_tokens_before // 2)else:effective_tail_tokens = self._keep_tail_tokens- tail_start = tail_start_by_tokens(messages, effective_tail_tokens)+ tail_start = tail_start_by_tokens(history, effective_tail_tokens)# Threshold check uses the UN-pruned view. Pre-pruning is a pre-pass# for the summariser and the post-compaction tail; running it when no@@ -211,17 +236,23 @@ class CompactionMiddleware(Middleware):# 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)+ unpruned_compressed = [+ *_compressed_view(history, state, boundary),+ *trailing_controls,+ ]tokens_now = real_context_estimate(unpruned_compressed)if tokens_now < self._max_tokens_before:return unpruned_compressed- # Find boundary on the ORIGINAL messages. Pruning is deferred until- # we're committed to compacting — otherwise a bailout path (no safe+ # Find the boundary on ordinary history only. Trailing synthetic user+ # controls are call-local additions: they count toward the send size,+ # but must not consume the protected tail or manufacture a boundary+ # after current-turn evidence. Pruning is deferred until we're+ # committed to compacting — otherwise a bailout path (no safe# boundary, or the anti-thrash guard firing) would silently return a# pruned view with no state recording the loss.new_boundary = safe_boundary(- messages,+ history,tail_start=tail_start,min_compact=max(self._min_compact, boundary + 1),)@@ -277,10 +308,10 @@ class CompactionMiddleware(Middleware):preserved: dict[int, str] = {}if self._prune_tool_outputs:pruned_messages, preserved = prune_tool_results(- messages, tail_start=tail_start, compressor=self._compressor+ history, tail_start=tail_start, compressor=self._compressor)else:- pruned_messages = list(messages)+ pruned_messages = list(history)# Filter preserved messages out of summarizer input — their content# is attached verbatim to the summary, so summarizing them would be@@ -299,7 +330,7 @@ class CompactionMiddleware(Middleware):new_state = await summarize(model=self._summary_model,messages_to_summarize=summarizer_messages,- ref_messages=messages[boundary:new_boundary],+ ref_messages=history[boundary:new_boundary],existing=state,max_summary_tokens=self._max_summary_tokens,system_prompt_override=self._summary_prompt,@@ -318,7 +349,7 @@ class CompactionMiddleware(Middleware):)new_state = build_fallback_summary(summarizer_messages,- ref_messages=messages[boundary:new_boundary],+ ref_messages=history[boundary:new_boundary],existing=state,)# The LLM was just attempted — restart the half-open wait.@@ -326,7 +357,7 @@ class CompactionMiddleware(Middleware):else:new_state = build_fallback_summary(summarizer_messages,- ref_messages=messages[boundary:new_boundary],+ ref_messages=history[boundary:new_boundary],existing=state,)ctx.extra["compaction_fallback_runs"] = (@@ -337,8 +368,8 @@ class CompactionMiddleware(Middleware):prior_preserved = state.preserved_tool_results if state else []new_preserved = [PreservedToolResult(- tool_name=messages[idx].tool_name, # type: ignore[union-attr]- tool_call_id=messages[idx].tool_call_id, # type: ignore[union-attr]+ tool_name=history[idx].tool_name, # type: ignore[union-attr]+ tool_call_id=history[idx].tool_call_id, # type: ignore[union-attr]text=text,)for idx, text in preserved.items()@@ -348,7 +379,10 @@ class CompactionMiddleware(Middleware):ctx.extra["compaction"] = new_state.model_dump()ctx.extra["compaction_until_msg_index"] = new_boundary- result = _compressed_view(pruned_messages, new_state, new_boundary)+ result = [+ *_compressed_view(pruned_messages, new_state, new_boundary),+ *trailing_controls,+ ]# Anti-thrashing tracking — compare raw history to result tokens.tokens_after = approx_tokens(result)diff --git a/dev/plans/2026-08-26-compaction-synthetic-controls.md b/dev/plans/2026-08-26-compaction-synthetic-controls.mdnew file mode 100644index 0000000..4f7553f--- /dev/null+++ b/dev/plans/2026-08-26-compaction-synthetic-controls.md@@ -0,0 +1,156 @@+# Trailing Synthetic Controls Compaction Repair — Implementation Plan++> **For agentic workers:** Execute with strict RED → GREEN. Do not write production+> code until the focused production-shaped regression has failed for the expected+> reason.++**Goal:** Prevent trailing synthetic user controls from aging and pruning current-turn+tool evidence while preserving threshold accounting, message order, state refs, and+all existing compaction behavior.++**Spec:** [`dev/specs/2026-08-26-compaction-synthetic-controls.md`](../specs/2026-08-26-compaction-synthetic-controls.md)++**Architecture:** Add one private split helper in the compaction module. Run+state/tail/boundary/pruning/summarization over the ordinary history prefix, measure the+actual model-send view with controls attached, then reattach the unchanged controls on+every return path. No public API or state schema changes.++**Tech stack:** Python 3.11+, Pydantic v2 message models, pytest asyncio tests, Ruff,+mypy.++---++## File structure++- **Modify** `cubepi/middleware/compaction/__init__.py`+ - import `UserMessage` and `is_synthetic_message`;+ - add a private maximal-suffix split helper;+ - apply compaction decisions to history and reattach controls.+- **Modify** `tests/middleware/test_compaction.py`+ - add the production-shaped RED and focused controls.+- **Modify** `website/docs/guides/middleware/compaction.md`+ - document trailing synthetic-control behavior and ordering.+- **Create** this spec and plan.++## Task 1: Establish the real RED++- [ ] Add a test helper that creates two large, non-chip tool results with unique+ sentinels and one trailing `synthetic_user_message`.+- [ ] Use the production-relevant settings:+ - `max_tokens_before_compact=55_000`+ - `keep_tail_tokens=8_000`+ - `min_compact_messages=4`+- [ ] Message shape must be one assistant turn with two tool calls followed by their+ two results and the synthetic control.+- [ ] Assert the returned model view retains both full sentinels and the exact trailing+ control, and that no summary call/state is produced when history alone has no legal+ boundary.+- [ ] Run only that test and observe the expected RED: current CubePi compacts at the+ synthetic control and removes both result sentinels.++Command:++```bash+uv run pytest \+ tests/middleware/test_compaction.py::test_trailing_synthetic_control_does_not_age_current_tool_results \+ -vv+```++## Task 2: Implement the smallest generic repair++- [ ] Add `_split_trailing_synthetic_user_controls(messages)` returning a copied+ history prefix and ordered controls suffix.+- [ ] Match only `UserMessage` + `is_synthetic_message`; do not inspect source names or+ payload text.+- [ ] In `transform_context`, use history for:+ - state validation and refs;+ - tail computation and safe boundary;+ - pruning;+ - summarizer/ref slices;+ - preserved-result state.+- [ ] Build the threshold view as compressed history + controls so controls still count.+- [ ] Return history/compressed history + controls from every exit path.+- [ ] Keep raw/savings accounting over full input/output views.+- [ ] Run the focused RED again and observe GREEN.++## Task 3: Add boundary and compatibility controls++Write the remaining tests before expanding production code beyond Task 2. The Task 2+implementation should satisfy them without source-specific branches.++- [ ] Multiple trailing synthetic user controls survive unchanged and in exact order.+- [ ] A large trailing control contributes to threshold crossing; an otherwise+ under-threshold compactable history triggers compaction.+- [ ] Older history compacts while a current multi-tool turn keeps all raw results.+- [ ] A synthetic tail `ToolResultMessage` is not detached from its tool call.+- [ ] No-suffix behavior stays unchanged (existing tests plus an explicit equality+ control if needed).+- [ ] State refs remain valid across a repeated transform and when a formerly trailing+ synthetic user control becomes internal after an assistant message is appended.++Run:++```bash+uv run pytest tests/middleware/test_compaction.py -v+uv run pytest tests/middleware/compaction/ -v+uv run pytest tests/test_synthetic_messages.py -v+```++## Task 4: Document the behavior++Update `website/docs/guides/middleware/compaction.md`:++- [ ] explain that trailing synthetic `UserMessage` controls count toward total context+ but do not consume the historical tail or create a boundary;+- [ ] explain that they are reattached after the compressed history in original order;+- [ ] state that only a trailing user-role synthetic suffix is treated this way and+ synthetic tool results remain in history to preserve pairing;+- [ ] keep docs generic; do not mention Bot tool names or application payloads.++## Task 5: Verify CubePi comprehensively++- [ ] Focused tests:++```bash+uv run pytest tests/middleware/test_compaction.py -v+uv run pytest tests/middleware/compaction/ -v+uv run pytest tests/test_synthetic_messages.py -v+```++- [ ] Full test suite:++```bash+uv run pytest tests/+```++- [ ] Static gates:++```bash+uv run ruff check cubepi/ tests/+uv run ruff format --check cubepi/ tests/+uv run mypy cubepi+```++- [ ] Inspect `git diff --check` and the exact diff.+- [ ] Obtain independent spec-compliance review, then independent code-quality review.+- [ ] Resolve and re-review every confirmed finding.++Do not start CubePi's optional local Codex loop without separate permission under its+project instructions. Opening a PR later will still receive the repository's normal PR+Codex review.++## Task 6: Upstream delivery and Cubemanus adoption++Only after Task 5 is clean:++- [ ] Commit the CubePi branch; push and open a PR against `main`.+- [ ] Wait for exact-SHA CI and required PR review; do not merge before both are clean.+- [ ] Establish a consumable upstream commit/release.+- [ ] In the isolated Cubemanus worktree, update only the dependency pin/lock plus a+ real Bot lifecycle regression using actual Temporal Freshness → Compaction ordering.+- [ ] Run focused and full Bot tests plus independent reviews.+- [ ] Deliver through feature MR → `dgts` → exact-SHA build → `cuecue-test` deploy.+- [ ] Rerun the large report synthesis E2E and verify full evidence reaches synthesis,+ with no duplicate tool calls and stable SSE/replay/transcript/browser behavior.++Hard stop before `master`, PROD, ConfigMaps, Secrets, or unrelated MRs.diff --git a/dev/specs/2026-08-26-compaction-synthetic-controls.md b/dev/specs/2026-08-26-compaction-synthetic-controls.mdnew file mode 100644index 0000000..80f7786--- /dev/null+++ b/dev/specs/2026-08-26-compaction-synthetic-controls.md@@ -0,0 +1,240 @@+# Trailing Synthetic Controls Must Not Age Current-Turn Evidence++- **Date**: 2026-08-26+- **Status**: Approved for implementation+- **Branch / worktree**: `2026-08-26-compaction-synthetic-controls` → `.worktrees/2026-08-26-compaction-synthetic-controls`+- **Related**:+ - [`2026-06-26-run-scoped-compaction.md`](2026-06-26-run-scoped-compaction.md)+ - [`../../website/docs/guides/middleware/compaction.md`](../../website/docs/guides/middleware/compaction.md)++## 1. Motivation++`CompactionMiddleware` receives the message view produced by middleware earlier in+the transform chain. Those earlier transforms may append synthetic `UserMessage`+controls for the next model call: policy envelopes, reminders, continuation nudges,+or other framework instructions built with `synthetic_user_message(...)`.++Today compaction treats those call-local controls as ordinary conversation history+when it chooses the protected tail and a safe summary boundary. That can make tool+evidence produced immediately before the controls look old.++A production-equivalent Bot run exposed the failure with this shape:++```text+User(request)+Assistant(tool_call A, tool_call B)+ToolResult A # 106,277 chars+ToolResult B # 38,796 chars+Synthetic User(freshness control) # small, appended by transform_context+```++With `max_tokens_before_compact=55_000`, `keep_tail_tokens=8_000`, and+`min_compact_messages=4`:++1. the synthetic control alone becomes the protected tail;+2. `safe_boundary` accepts its index as a self-contained boundary;+3. both current-turn `ToolResultMessage`s fall before `tail_start`;+4. the default pruner replaces them with `[tool] N chars` markers;+5. the synthesis model sees that tools ran, but not the rows it must synthesize.++The model then correctly reports that row-level evidence is unavailable even though+the durable run transcript still contains the full results. This is not a tool-specific+or application-specific failure: any transform middleware that appends a synthetic+user-role control after current evidence can create the same false aging.++## 2. Required invariant++A **maximal trailing suffix of synthetic `UserMessage`s** is call-local control+context for compaction purposes:++- it remains visible to the main model;+- it remains in exact input order;+- it contributes to the total context-size trigger;+- it does **not** consume the protected historical tail;+- it does **not** create a compaction boundary;+- it is not summarized or pruned;+- compaction state refs and boundaries continue to describe the ordinary message+ prefix, not transient transform additions.++Only a trailing suffix is special. Synthetic user messages inside ordinary history+remain ordinary history. Only `UserMessage` controls are detached; synthetic+`ToolResultMessage`s stay with the history so no tool call/result pair can be+orphaned.++## 3. Design++### 3.1 Split the transformed view into history and trailing controls++At the start of `CompactionMiddleware.transform_context`, split the input at the+first message of the maximal trailing suffix satisfying both:++```python+isinstance(message, UserMessage) and is_synthetic_message(message)+```++The two views are:++- `history`: every message before that suffix;+- `trailing_controls`: the suffix, unchanged and ordered.++When no such suffix exists, `history` is the full input and+`trailing_controls` is empty, preserving current behavior.++### 3.2 State and boundary decisions use history only++The following operations use `history`, not the combined transformed view:++- persisted-state boundary range validation;+- `_state_matches_history`;+- `tail_start_by_tokens`;+- `safe_boundary`;+- `prune_tool_results`;+- summarizer slices and reference messages;+- preserved-result indexing and state refs;+- `_compressed_view` construction.++Because the detached controls form only a trailing suffix, every index in `history`+is also the same index in the original input. Existing `compaction_until_msg_index`+values and message refs therefore keep their meaning; no state-schema migration is+needed.++A synthetic user control that is durably persisted may be trailing for one call and+later become internal history after an assistant response follows it. This remains+safe: while trailing it cannot define the boundary; once internal it participates in+history normally, and every earlier boundary index remains stable.++### 3.3 Threshold decisions include controls++The main model receives the compressed/uncompressed history plus the controls, so+the threshold must measure that exact view:++```text+real_context_estimate(_compressed_view(history, state, boundary) + controls)+```++This prevents a large control suffix from bypassing compaction. The anti-thrash+emergency check and savings accounting continue to use the full input/output views,+so controls contribute to actual send size without affecting tail placement.++### 3.4 Reattach controls after every exit path++Every returned model view has this order:++```text+compressed_or_original_history + trailing_controls+```++This applies to:++- below-threshold returns;+- no-safe-boundary returns;+- anti-thrash skips;+- successful LLM summaries;+- deterministic fallback summaries.++Reattachment does not mutate the original messages or the control objects.++## 4. Why this boundary is generic and low-maintenance++The repair consumes CubePi's existing semantic marker,+`metadata["synthetic"] is True`; it introduces no source-name allowlist, middleware+registry, tool-family table, payload inspection, or application-specific exception.+Any current or future middleware using `synthetic_user_message(...)` receives the+same behavior automatically.++The restriction to a **maximal trailing suffix** is deliberate:++- trailing controls are the additions that can falsely displace current evidence;+- internal synthetic messages may be durable control history and can be summarized+ once later turns follow them;+- detaching arbitrary synthetic messages would require index remapping and would+ destabilize compaction refs;+- detaching synthetic tool results could orphan their tool calls.++## 5. Prior-art check and CubePi divergence++- **LangGraph** distinguishes a temporary `llm_input_messages` view from updates to+ persistent `messages` state. That supports the same architectural separation:+ model-call context transforms should not automatically redefine durable-history+ semantics.+- **pi agent context construction** converts compaction and branch-summary entries+ into synthetic context messages during context building, rather than treating all+ generated context as equivalent to persisted dialogue.+- **Claude Code** reconstructs post-compaction context in a fixed order — summary,+ explicitly retained messages, attachments, and hook results — instead of letting+ post-processing additions determine the retained conversation boundary.++CubePi differs because its middleware API intentionally uses one ordinary+`list[Message]` rather than introducing a second context-entry hierarchy. The+smallest compatible repair is therefore to consume the existing synthetic marker at+the compaction seam, not add a new message type or public API.++References:++- https://reference.langchain.com/python/langgraph.prebuilt/chat_agent_executor/create_react_agent+- https://github.com/earendil-works/pi/blob/main/packages/agent/src/harness/session/context.ts+- `/Users/test/work/claude-code/src/services/compact/compact.ts:325-337`++## 6. Non-goals++- No Bot-, finance-, freshness-, report-, or tool-specific preservation rule.+- No change to `tool_result_compressor` semantics.+- No automatic preservation of every large tool result.+- No new public middleware configuration or message metadata field.+- No change to provider serialization.+- No change to `safe_boundary`'s tool-call self-containment rules.+- No detachment of synthetic assistant or tool-result messages.+- No compaction-state schema/version migration.++## 7. Compatibility++This is a behavioral bug fix with no public API change.++- Inputs without a trailing synthetic-user suffix follow the same code path and must+ remain byte-for-byte/equality equivalent at the message-model level.+- Inputs with such a suffix may choose a different tail/boundary, preserving newer+ ordinary evidence that was previously pruned.+- The controls still count toward the threshold, so the repair cannot silently send+ an over-limit context merely by labeling content synthetic.+- Existing persisted boundaries remain valid because suffix removal never changes+ prefix indices.++## 8. Test plan++### Required RED++Drive the real `CompactionMiddleware.transform_context` with the production-shaped+five-message input above and the production threshold/tail/minimum values. Before the+fix, both large result sentinels disappear into size-only markers. After the fix, no+safe history-only boundary exists, so the original current-turn results and trailing+control all remain intact.++### Regression matrix++1. No trailing synthetic suffix: existing compaction behavior is unchanged.+2. One trailing synthetic user control: current tool evidence remains protected.+3. Multiple trailing synthetic user controls: all survive in exact order.+4. Controls count toward the threshold: history compacts when the combined send view,+ but not history alone, crosses the threshold.+5. A synthetic `ToolResultMessage` at the tail is not detached and remains paired with+ its tool call.+6. With older history before the current tool turn, the old prefix can compact while+ all current-turn tool results remain raw.+7. Persisted state refs/boundary remain valid across repeated calls and when a formerly+ trailing synthetic user message later becomes internal history.+8. Existing multi-round, pruner, circuit-breaker, anti-thrash, and run-scoped tests+ remain green.++## 9. Rollout++1. Land the generic fix and docs in CubePi after focused/full tests, lint, format, and+ type checks plus independent spec and code-quality review.+2. Establish the upstream commit/release path.+3. Update the Cubemanus dependency pin only after the upstream artifact is available.+4. Add a Bot lifecycle regression using its real Temporal Freshness transform before+ compaction.+5. Rebuild and deploy the exact Cubemanus `dgts` SHA to TEST, then rerun the demanding+ report synthesis E2E.++Rollback is a dependency-pin revert. No persisted state migration or data repair is+required.diff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.pyindex a5eb04e..8ee8eb6 100644--- a/tests/middleware/test_compaction.py+++ b/tests/middleware/test_compaction.py@@ -1157,3 +1157,274 @@ async def test_compressor_preserved_persists_across_compaction_rounds() -> None:result = await middleware2.transform_context(messages, ctx=ctx)summary_msg = result[0]assert "preserved data" in summary_msg.content[0].text+++async def test_trailing_synthetic_control_does_not_age_current_tool_results() -> None:+ """A call-local control must not make same-turn tool evidence look old.++ This is the production failure shape: one assistant proposes two tools, both+ return large results, and an earlier transform appends a small synthetic+ user control. The ordinary four-message history has no legal boundary at+ ``min_compact_messages=4``; the control must not manufacture one.+ """+ from cubepi.providers.base import (+ ToolCall,+ ToolResultMessage,+ synthetic_user_message,+ )++ provider = _FakeSummaryProvider(reply="summary must not run")+ middleware = CompactionMiddleware(+ summary_model=BoundModel(+ provider=provider,+ spec=Model(id="summary-model", provider_id="faux"),+ ),+ max_tokens_before_compact=55_000,+ keep_tail_tokens=8_000,+ max_summary_tokens=1_024,+ min_compact_messages=4,+ )+ report_a = "CURRENT_REPORT_A_SENTINEL|" + "A" * 106_277+ report_b = "CURRENT_REPORT_B_SENTINEL|" + "B" * 38_796+ control = synthetic_user_message(+ '{"candidate_schema_version":1,"required_action":"evaluate current evidence"}',+ source="freshness_candidate",+ )+ messages: list[Message] = [+ _user("Compare the latest two reports."),+ AssistantMessage(+ content=[+ ToolCall(id="c1", name="report_a", arguments={}),+ ToolCall(id="c2", name="report_b", arguments={}),+ ]+ ),+ ToolResultMessage(+ tool_call_id="c1",+ tool_name="report_a",+ content=[TextContent(text=report_a)],+ ),+ ToolResultMessage(+ tool_call_id="c2",+ tool_name="report_b",+ content=[TextContent(text=report_b)],+ ),+ control,+ ]+ ctx = AgentContext(system_prompt="", messages=messages, extra={})++ result = await middleware.transform_context(messages, ctx=ctx)++ assert result == messages+ assert result[-1] == control+ assert report_a in result[2].content[0].text+ assert report_b in result[3].content[0].text+ assert provider.calls == []+ assert "compaction" not in ctx.extra+++async def test_trailing_controls_count_toward_compaction_threshold() -> None:+ """Controls stay in the size calculation even though they do not set the tail."""+ from cubepi.middleware.compaction.tokens import real_context_estimate+ from cubepi.providers.base import synthetic_user_message++ provider = _FakeSummaryProvider(reply="combined view crossed threshold")+ middleware = CompactionMiddleware(+ summary_model=BoundModel(+ provider=provider,+ spec=Model(id="summary-model", provider_id="faux"),+ ),+ max_tokens_before_compact=20,+ keep_tail_tokens=4,+ max_summary_tokens=128,+ min_compact_messages=2,+ )+ history: list[Message] = [+ _user("u1"),+ _assistant("a1"),+ _user("u2"),+ _assistant("a2"),+ _user("u3"),+ _assistant("a3"),+ ]+ control = synthetic_user_message("C" * 100, source="large_call_control")+ messages = [*history, control]+ assert real_context_estimate(history) < 20+ assert real_context_estimate(messages) >= 20+ ctx = AgentContext(system_prompt="", messages=messages, extra={})++ result = await middleware.transform_context(messages, ctx=ctx)++ assert len(provider.calls) == 1+ assert "compaction" in ctx.extra+ assert result[-1] == control+++async def test_old_prefix_compacts_without_pruning_current_multi_tool_evidence() -> (+ None+):+ """Older turns may compact while a current multi-tool turn stays raw."""+ from cubepi.providers.base import (+ ToolCall,+ ToolResultMessage,+ synthetic_user_message,+ )++ provider = _FakeSummaryProvider(reply="old prefix summary")+ middleware = CompactionMiddleware(+ summary_model=BoundModel(+ provider=provider,+ spec=Model(id="summary-model", provider_id="faux"),+ ),+ max_tokens_before_compact=8_000,+ keep_tail_tokens=6_000,+ max_summary_tokens=512,+ min_compact_messages=4,+ )+ report_a = "RAW_CURRENT_A|" + "A" * 5_000+ report_b = "RAW_CURRENT_B|" + "B" * 5_000+ control_a = synthetic_user_message("policy A", source="policy_a")+ control_b = synthetic_user_message("policy B", source="policy_b")+ messages: list[Message] = [+ _user("old user 1 " * 700),+ _assistant("old answer 1 " * 700),+ _user("old user 2 " * 700),+ _assistant("old answer 2 " * 700),+ _user("current request"),+ AssistantMessage(+ content=[+ ToolCall(id="c1", name="report_a", arguments={}),+ ToolCall(id="c2", name="report_b", arguments={}),+ ]+ ),+ ToolResultMessage(+ tool_call_id="c1",+ tool_name="report_a",+ content=[TextContent(text=report_a)],+ ),+ ToolResultMessage(+ tool_call_id="c2",+ tool_name="report_b",+ content=[TextContent(text=report_b)],+ ),+ control_a,+ control_b,+ ]+ ctx = AgentContext(system_prompt="", messages=messages, extra={})++ result = await middleware.transform_context(messages, ctx=ctx)++ assert len(provider.calls) == 1+ assert isinstance(result[0], UserMessage)+ assert result[0].metadata.get("synthetic_source") == "compaction_summary"+ assert result[-2:] == [control_a, control_b]+ result_a = next(+ message+ for message in result+ if isinstance(message, ToolResultMessage) and message.tool_call_id == "c1"+ )+ result_b = next(+ message+ for message in result+ if isinstance(message, ToolResultMessage) and message.tool_call_id == "c2"+ )+ assert result_a.content[0].text == report_a+ assert result_b.content[0].text == report_b+++def test_split_only_detaches_trailing_synthetic_user_messages() -> None:+ """Plain user tails and synthetic tool results remain ordinary history."""+ from cubepi.middleware.compaction import (+ _split_trailing_synthetic_user_controls,+ )+ from cubepi.providers.base import (+ ToolCall,+ ToolResultMessage,+ synthetic_user_message,+ )++ synthetic_result = ToolResultMessage(+ tool_call_id="c1",+ tool_name="audit",+ content=[TextContent(text="synthetic cleanup result")],+ metadata={"synthetic": True},+ )+ tool_history: list[Message] = [+ _user("q"),+ AssistantMessage(content=[ToolCall(id="c1", name="audit", arguments={})]),+ synthetic_result,+ ]++ history, controls = _split_trailing_synthetic_user_controls(tool_history)+ assert history == tool_history+ assert controls == []++ plain_tail = [*tool_history, _user("real user tail")]+ history, controls = _split_trailing_synthetic_user_controls(plain_tail)+ assert history == plain_tail+ assert controls == []++ control_a = synthetic_user_message("a", source="a")+ control_b = synthetic_user_message("b", source="b")+ history, controls = _split_trailing_synthetic_user_controls(+ [*plain_tail, control_a, control_b]+ )+ assert history == plain_tail+ assert controls == [control_a, control_b]+++async def test_compaction_state_refs_survive_trailing_control_becoming_internal() -> (+ None+):+ """Suffix splitting does not change persisted prefix indices or refs."""+ from cubepi.providers.base import synthetic_user_message++ provider = _FakeSummaryProvider(reply="stable summary")+ compacting = CompactionMiddleware(+ summary_model=BoundModel(+ provider=provider,+ spec=Model(id="summary-model", provider_id="faux"),+ ),+ max_tokens_before_compact=1,+ keep_tail_tokens=4,+ max_summary_tokens=128,+ min_compact_messages=2,+ )+ control = synthetic_user_message("continue", source="continuation")+ messages: list[Message] = [+ _user("turn 1"),+ _assistant("reply 1"),+ _user("turn 2"),+ _assistant("reply 2"),+ _user("turn 3"),+ _assistant("reply 3"),+ control,+ ]+ ctx = AgentContext(system_prompt="", messages=messages, extra={})++ first = await compacting.transform_context(messages, ctx=ctx)+ boundary = ctx.extra["compaction_until_msg_index"]+ persisted_state = ctx.extra["compaction"]+ assert first[-1] == control++ under_threshold = CompactionMiddleware(+ summary_model=BoundModel(+ provider=_FakeSummaryProvider(),+ spec=Model(id="summary-model", provider_id="faux"),+ ),+ max_tokens_before_compact=1_000_000,+ keep_tail_tokens=4,+ min_compact_messages=2,+ )+ repeated = await under_threshold.transform_context(messages, ctx=ctx)+ assert repeated[0].metadata.get("synthetic_source") == "compaction_summary"+ assert repeated[-1] == control+ assert ctx.extra["compaction_until_msg_index"] == boundary+ assert ctx.extra["compaction"] == persisted_state++ with_response = [*messages, _assistant("response after control")]+ resumed = await under_threshold.transform_context(with_response, ctx=ctx)+ assert resumed[0].metadata.get("synthetic_source") == "compaction_summary"+ assert control in resumed+ assert resumed[-1] == with_response[-1]+ assert ctx.extra["compaction_until_msg_index"] == boundary+ assert ctx.extra["compaction"] == persisted_statediff --git a/website/docs/guides/middleware/compaction.md b/website/docs/guides/middleware/compaction.mdindex 5602395..b028ecf 100644--- a/website/docs/guides/middleware/compaction.md+++ b/website/docs/guides/middleware/compaction.md@@ -73,6 +73,22 @@ a single agent turn, between tool-call iterations — along two dimensions:never splits a `tool_use` from its `tool_result`, so the compressed view alwaysstays valid for the provider.+### Trailing synthetic controls++Transform middleware earlier in the chain may append synthetic `UserMessage`+controls for the next model call. CubePi keeps a maximal trailing suffix of those+controls outside the historical tail/boundary calculation: they cannot make tool+evidence immediately before them look old and become eligible for pruning.++The controls still count toward the real-token threshold, and CubePi reattaches them+unchanged after the original or compressed history in exact order. Only trailing+synthetic **user** messages receive this treatment. Internal synthetic messages remain+ordinary history, and synthetic `ToolResultMessage`s are never detached from their+tool calls.++Use `synthetic_user_message(...)` for middleware-generated user-role controls so this+behavior and the framework-wide synthetic marker stay consistent.+## Choosing thresholdsStart with conservative values: