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(middleware): cap tool-result text in after_tool_call
xf gong005c75ab8483
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cf6bc7f..1d28645 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added++- **`ToolResultLimitMiddleware` caps tool-result text in `after_tool_call`.**+ Oversized text is truncated to `max_chars` (default 20,000) with a notice+ telling the model to narrow the call. The rewrite happens before+ `ToolExecutionEndEvent`, so the model, checkpointer, and host consumers+ all see the truncated result. Image blocks are kept; tools in+ `exclude_tool_names` pass through.+## [0.15.0] - 2026-09-16### Addeddiff --git a/cubeloop/middleware/__init__.py b/cubeloop/middleware/__init__.pyindex a9feea5..a3e8378 100644--- a/cubeloop/middleware/__init__.py+++ b/cubeloop/middleware/__init__.py@@ -9,6 +9,7 @@ __all__ = ["CompactionState","GoalMiddleware","ToolResultCompressor",+ "ToolResultLimitMiddleware","Middleware","SubagentMiddleware","SubagentRequest",@@ -29,6 +30,10 @@ _LAZY = {"CompactionMiddleware": ("cubeloop.middleware.compaction", "CompactionMiddleware"),"CompactionState": ("cubeloop.middleware.compaction", "CompactionState"),"ToolResultCompressor": ("cubeloop.middleware.compaction", "ToolResultCompressor"),+ "ToolResultLimitMiddleware": (+ "cubeloop.middleware.tool_result_limit",+ "ToolResultLimitMiddleware",+ ),"GoalMiddleware": ("cubeloop.middleware.goal", "GoalMiddleware"),"SubagentMiddleware": ("cubeloop.middleware.subagents", "SubagentMiddleware"),"SubagentRequest": ("cubeloop.middleware.subagents", "SubagentRequest"),diff --git a/cubeloop/middleware/tool_result_limit.py b/cubeloop/middleware/tool_result_limit.pynew file mode 100644index 0000000..f231a65--- /dev/null+++ b/cubeloop/middleware/tool_result_limit.py@@ -0,0 +1,103 @@+"""Cap tool-result text before CubeLoop emits ``ToolExecutionEndEvent``.++``after_tool_call`` runs after the tool returns and before the end event is+published, so a truncated result is what the model, the checkpointer, and+host event consumers all see. Hosts whose event bus has a byte budget+(CubePlex projects at 1 MiB) stay inside that budget without failing the+required consumer.++Non-text blocks (images) are preserved. Tools listed in+``exclude_tool_names`` pass through unchanged.+"""++from __future__ import annotations++import asyncio+from collections.abc import Collection++from cubeloop.agent.types import AfterToolCallContext, AfterToolCallResult+from cubeloop.middleware.base import Middleware+from cubeloop.providers.base import Content, TextContent++DEFAULT_MAX_TOOL_RESULT_CHARS = 20_000++_TRUNCATION_NOTICE = (+ "\n\n[truncated: tool result was {total} characters; "+ "showing first {kept}. Narrow the tool call and retry.]"+)+++def _text_char_count(content: list[Content]) -> int:+ return sum(len(block.text) for block in content if isinstance(block, TextContent))+++def truncate_tool_result_content(+ content: list[Content],+ *,+ max_chars: int,+) -> list[Content] | None:+ """Return truncated content, or ``None`` when no truncation is needed."""+ total = _text_char_count(content)+ if total <= max_chars:+ return None++ remaining = max_chars+ truncated: list[Content] = []+ for block in content:+ if not isinstance(block, TextContent):+ truncated.append(block)+ continue+ if remaining <= 0:+ continue+ if len(block.text) <= remaining:+ truncated.append(block)+ remaining -= len(block.text)+ continue+ truncated.append(TextContent(text=block.text[:remaining]))+ remaining = 0++ notice = _TRUNCATION_NOTICE.format(total=total, kept=max_chars)+ if truncated and isinstance(truncated[-1], TextContent):+ truncated[-1] = TextContent(text=truncated[-1].text + notice)+ else:+ truncated.append(TextContent(text=notice.lstrip()))+ return truncated+++class ToolResultLimitMiddleware(Middleware):+ """Rewrite oversized tool results in ``after_tool_call``.++ Place this after other ``after_tool_call`` middleware so the truncated+ content is what later composition and ``ToolExecutionEndEvent`` see.+ Under the default last-non-None composer, a later middleware that+ returns a result without ``content`` will drop this rewrite — put this+ last, or use a merging composer.+ """++ def __init__(+ self,+ *,+ max_chars: int = DEFAULT_MAX_TOOL_RESULT_CHARS,+ exclude_tool_names: Collection[str] = (),+ ) -> None:+ if max_chars < 1:+ raise ValueError("max_chars must be >= 1")+ self.max_chars = max_chars+ self.exclude_tool_names = frozenset(exclude_tool_names)++ async def after_tool_call(+ self,+ ctx: AfterToolCallContext,+ *,+ signal: asyncio.Event | None = None,+ ) -> AfterToolCallResult | None:+ del signal+ if ctx.tool_call.name in self.exclude_tool_names:+ return None+ truncated = truncate_tool_result_content(+ ctx.result.content,+ max_chars=self.max_chars,+ )+ if truncated is None:+ return None+ return AfterToolCallResult(content=truncated)diff --git a/tests/middleware/test_init_exports.py b/tests/middleware/test_init_exports.pyindex fd719ca..eba9034 100644--- a/tests/middleware/test_init_exports.py+++ b/tests/middleware/test_init_exports.py@@ -10,6 +10,7 @@ def test_lazy_exports_resolve_builtin_middleware() -> None:assert middleware.CompactionState.__name__ == "CompactionState"assert middleware.SubagentMiddleware.__name__ == "SubagentMiddleware"assert middleware.SubagentSpec.__name__ == "SubagentSpec"+ assert middleware.ToolResultLimitMiddleware.__name__ == "ToolResultLimitMiddleware"def test_unknown_lazy_export_raises_attribute_error() -> None:diff --git a/tests/middleware/test_tool_result_limit.py b/tests/middleware/test_tool_result_limit.pynew file mode 100644index 0000000..a973a40--- /dev/null+++ b/tests/middleware/test_tool_result_limit.py@@ -0,0 +1,125 @@+from __future__ import annotations++import pytest++from cubeloop.agent.types import (+ AfterToolCallContext,+ AgentContext,+ AgentToolResult,+)+from cubeloop.middleware import ToolResultLimitMiddleware+from cubeloop.middleware.tool_result_limit import (+ DEFAULT_MAX_TOOL_RESULT_CHARS,+ truncate_tool_result_content,+)+from cubeloop.providers.base import (+ AssistantMessage,+ Content,+ ImageContent,+ TextContent,+ ToolCall,+)+++def _ctx(+ text: str | list[Content],+ *,+ name: str = "execute",+) -> AfterToolCallContext:+ content: list[Content] = (+ [TextContent(text=text)] if isinstance(text, str) else list(text)+ )+ return AfterToolCallContext(+ assistant_message=AssistantMessage(content=[]),+ tool_call=ToolCall(id="t1", name=name, arguments={}),+ args={},+ result=AgentToolResult(content=content),+ is_error=False,+ context=AgentContext(system_prompt="", messages=[]),+ )+++class TestTruncateToolResultContent:+ def test_under_limit_returns_none(self) -> None:+ content = [TextContent(text="hello")]+ assert truncate_tool_result_content(content, max_chars=10) is None++ def test_exact_limit_returns_none(self) -> None:+ content = [TextContent(text="a" * 20)]+ assert truncate_tool_result_content(content, max_chars=20) is None++ def test_over_limit_keeps_prefix_and_appends_notice(self) -> None:+ content = [TextContent(text="abcdefghij")]+ out = truncate_tool_result_content(content, max_chars=4)+ assert out is not None+ assert len(out) == 1+ assert isinstance(out[0], TextContent)+ assert out[0].text.startswith("abcd")+ assert "[truncated:" in out[0].text+ assert "10 characters" in out[0].text+ assert "showing first 4" in out[0].text++ def test_truncates_across_text_blocks(self) -> None:+ content = [+ TextContent(text="aaa"),+ TextContent(text="bbbbbb"),+ ]+ out = truncate_tool_result_content(content, max_chars=5)+ assert out is not None+ texts = [b.text for b in out if isinstance(b, TextContent)]+ assert texts[0] == "aaa"+ assert texts[1].startswith("bb")+ assert "[truncated:" in texts[-1]++ def test_preserves_image_blocks(self) -> None:+ content = [+ ImageContent(source="data:image/png;base64,xx", media_type="image/png"),+ TextContent(text="x" * 50),+ ]+ out = truncate_tool_result_content(content, max_chars=4)+ assert out is not None+ assert isinstance(out[0], ImageContent)+ assert isinstance(out[1], TextContent)+ assert out[1].text.startswith("xxxx")+ assert "[truncated:" in out[1].text+++class TestToolResultLimitMiddleware:+ def test_rejects_non_positive_max_chars(self) -> None:+ with pytest.raises(ValueError, match="max_chars"):+ ToolResultLimitMiddleware(max_chars=0)++ async def test_under_limit_is_noop(self) -> None:+ mw = ToolResultLimitMiddleware(max_chars=20)+ assert await mw.after_tool_call(_ctx("short")) is None++ async def test_over_limit_rewrites_content(self) -> None:+ mw = ToolResultLimitMiddleware(max_chars=8)+ result = await mw.after_tool_call(_ctx("0123456789abcdef"))+ assert result is not None+ assert result.content is not None+ assert isinstance(result.content[0], TextContent)+ assert result.content[0].text.startswith("01234567")+ assert "[truncated:" in result.content[0].text+ assert result.details is None++ async def test_excluded_tool_passes_through(self) -> None:+ mw = ToolResultLimitMiddleware(+ max_chars=4,+ exclude_tool_names={"load_skill"},+ )+ huge = "x" * 100+ assert await mw.after_tool_call(_ctx(huge, name="load_skill")) is None+ rewritten = await mw.after_tool_call(_ctx(huge, name="execute"))+ assert rewritten is not None++ async def test_default_cap_matches_exported_constant(self) -> None:+ mw = ToolResultLimitMiddleware()+ assert mw.max_chars == DEFAULT_MAX_TOOL_RESULT_CHARS+ body = "y" * (DEFAULT_MAX_TOOL_RESULT_CHARS + 50)+ result = await mw.after_tool_call(_ctx(body))+ assert result is not None+ assert result.content is not None+ text = result.content[0].text+ assert text.startswith("y" * DEFAULT_MAX_TOOL_RESULT_CHARS)+ assert "[truncated:" in textdiff --git a/website/docs/guides/middleware/examples.md b/website/docs/guides/middleware/examples.mdindex 0b0b674..6ca00ba 100644--- a/website/docs/guides/middleware/examples.md+++ b/website/docs/guides/middleware/examples.md@@ -171,6 +171,26 @@ class SummaryInjector(Middleware):return f"{system_prompt}\n\nContext: {summary}".strip()```+## Built-in tool-result cap++`ToolResultLimitMiddleware` truncates oversized tool-result text in+`after_tool_call` so a runaway `execute` / fetch / MCP payload cannot+blow the next model call (or a host event-size budget).++```python+from cubeloop.middleware import ToolResultLimitMiddleware++agent = Agent(+ model=…,+ middleware=[+ ToolResultLimitMiddleware(max_chars=20_000),+ ],+)+```++See [Tool Result Limit](./tool-result-limit.md) for options, exclusions,+and placement.+## Built-in compaction`CompactionMiddleware` summarizes older turns into `ctx.extra` anddiff --git a/website/docs/guides/middleware/tool-result-limit.md b/website/docs/guides/middleware/tool-result-limit.mdnew file mode 100644index 0000000..41095f7--- /dev/null+++ b/website/docs/guides/middleware/tool-result-limit.md@@ -0,0 +1,70 @@+---+title: Tool Result Limit+description: "Use ToolResultLimitMiddleware to cap tool-result text before it is emitted to the model and host event consumers."+---++# Tool Result Limit++`ToolResultLimitMiddleware` truncates oversized tool-result text in+`after_tool_call`, before CubeLoop publishes `ToolExecutionEndEvent`.+The model, the checkpointer, and any host event consumer all see the+truncated result.++Use it when a tool can return unbounded output — shell commands,+web fetches, MCP tools — and a huge result would blow the context+window or a host event-size budget.++## Basic setup++```python+from cubeloop import Agent+from cubeloop.middleware import ToolResultLimitMiddleware++agent = Agent(+ model=provider.model("claude-sonnet-4-6"),+ middleware=[+ ToolResultLimitMiddleware(),+ ],+)+```++The default cap is 20,000 characters of text content. Results at or+under the cap pass through unchanged (`after_tool_call` returns+`None`). Over the cap, text is cut to the first `max_chars` characters+and a notice is appended:++```text+[truncated: tool result was 1082017 characters; showing first 20000. Narrow the tool call and retry.]+```++Image blocks are kept. Only `TextContent` counts toward the cap.++## Options++```python+ToolResultLimitMiddleware(+ max_chars=20_000,+ exclude_tool_names={"load_skill"},+)+```++- `max_chars` — maximum characters of text kept from the original+ result. Must be `>= 1`.+- `exclude_tool_names` — tool names that skip truncation. Use this for+ tools whose full payload is load-bearing (for example a skill body+ returned by `load_skill`).++## Placement++Put this **after** other `after_tool_call` middleware so they rewrite+the full result first, and the truncated text is what+`ToolExecutionEndEvent` carries.++CubeLoop's default composer is last-non-`None` wins. A later+middleware that returns an `AfterToolCallResult` without `content`+would drop this rewrite. Keep `ToolResultLimitMiddleware` last, or+use a composer that merges `content` and `details`.++Subagent child agents do not inherit parent middleware. Pass the same+instance (or a second one) via `SubagentMiddleware(inherited_middleware=...)`+if child tool results should be capped too.diff --git a/website/sidebars.ts b/website/sidebars.tsindex 6343f77..1baf8f4 100644--- a/website/sidebars.ts+++ b/website/sidebars.ts@@ -45,6 +45,7 @@ const sidebars: SidebarsConfig = {'guides/middleware/compaction','guides/middleware/subagents','guides/middleware/todo',+ 'guides/middleware/tool-result-limit','guides/middleware/deferred-tools','guides/middleware/goal','guides/middleware/examples',