Skip to content

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

fix(compaction): preserve evidence before synthetic controls

Cue4716392ee8a2
diff --git a/cubepi/middleware/compaction/__init__.py b/cubepi/middleware/compaction/__init__.py
index 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_esti
from 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 = 0
state = 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.py
index 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_state
diff --git a/website/docs/guides/middleware/compaction.md b/website/docs/guides/middleware/compaction.md
index 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 always
stays 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 thresholds
Start with conservative values: