Skip to content

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

refactor: fold code-review cleanups — triple-return resolver, shared test helpers, sorted load_tools serialization

xf gong46822d59e875
diff --git a/cubepi/agent/tools.py b/cubepi/agent/tools.py
index bf1b542..e6efb5a 100644
--- a/cubepi/agent/tools.py
+++ b/cubepi/agent/tools.py
@@ -145,22 +145,29 @@ async def _resolve_tool_call(
context: AgentContext,
resolve_tool_call: Callable | None,
signal: asyncio.Event | None,
-) -> tuple[ToolCall, bool] | _ImmediateOutcome:
+) -> tuple[ToolCall, bool, _ImmediateOutcome | None]:
"""Give the resolve hook a chance to rewrite the call before anything
else sees it — events, validation, before/after hooks, and tracing all
- operate on the rewritten call. Returns ``(call, was_resolved)``, or an
- immediate error outcome if the resolver raised."""
+ operate on the rewritten call.
+
+ Returns ``(call, was_resolved, resolver_error)``; ``resolver_error`` is
+ an immediate error outcome (with the original call for attribution)
+ when the resolver raised."""
if not resolve_tool_call:
- return tool_call, False
+ return tool_call, False, None
try:
rewritten = await resolve_tool_call(tool_call, context=context, signal=signal)
except HitlControlException:
raise
except Exception as exc:
- return _ImmediateOutcome(result=_error_result(str(exc)), is_error=True)
+ return (
+ tool_call,
+ False,
+ _ImmediateOutcome(result=_error_result(str(exc)), is_error=True),
+ )
if rewritten is None:
- return tool_call, False
- return rewritten, True
+ return tool_call, False, None
+ return rewritten, True, None
async def _prepare_tool_call(
@@ -410,12 +417,9 @@ async def _execute_sequential(
messages: list[ToolResultMessage] = []
for tc in tool_calls:
- resolution = await _resolve_tool_call(tc, context, resolve_tool_call, signal)
- was_resolved = False
- if isinstance(resolution, _ImmediateOutcome):
- rtc = tc
- else:
- rtc, was_resolved = resolution
+ rtc, was_resolved, resolver_error = await _resolve_tool_call(
+ tc, context, resolve_tool_call, signal
+ )
await emit_event(
emit_fn,
@@ -424,18 +428,14 @@ async def _execute_sequential(
),
)
- preparation: _PreparedToolCall | _ImmediateOutcome
- if isinstance(resolution, _ImmediateOutcome):
- preparation = resolution
- else:
- preparation = await _prepare_tool_call(
- context,
- assistant_message,
- rtc,
- before_tool_call,
- signal,
- resolved=was_resolved,
- )
+ preparation = resolver_error or await _prepare_tool_call(
+ context,
+ assistant_message,
+ rtc,
+ before_tool_call,
+ signal,
+ resolved=was_resolved,
+ )
if isinstance(preparation, _ImmediateOutcome):
finalized = _FinalizedOutcome(
@@ -500,21 +500,17 @@ async def _execute_parallel(
# and trace spans permanently open.
entries: list[_FinalizedOutcome | _PreparedToolCall] = []
for tc in tool_calls:
- resolution = await _resolve_tool_call(tc, context, resolve_tool_call, signal)
- was_resolved = False
- if isinstance(resolution, _ImmediateOutcome):
- rtc = tc
- preparation: _PreparedToolCall | _ImmediateOutcome = resolution
- else:
- rtc, was_resolved = resolution
- preparation = await _prepare_tool_call(
- context,
- assistant_message,
- rtc,
- before_tool_call,
- signal,
- resolved=was_resolved,
- )
+ rtc, was_resolved, resolver_error = await _resolve_tool_call(
+ tc, context, resolve_tool_call, signal
+ )
+ preparation = resolver_error or await _prepare_tool_call(
+ context,
+ assistant_message,
+ rtc,
+ before_tool_call,
+ signal,
+ resolved=was_resolved,
+ )
if isinstance(preparation, _ImmediateOutcome):
# Immediate outcomes get a paired Start+End right here (the
diff --git a/cubepi/deferred/_expand_tool.py b/cubepi/deferred/_expand_tool.py
index 78751d8..7fa219f 100644
--- a/cubepi/deferred/_expand_tool.py
+++ b/cubepi/deferred/_expand_tool.py
@@ -55,7 +55,10 @@ def _make_load_tools(
) -> AgentToolResult:
del signal, on_update
output = await load_callback(args.group_id, args.tool_names)
- text = json.dumps(output.model_dump(), ensure_ascii=False)
+ # sort_keys: the rendered result becomes part of the cached prompt
+ # prefix on later turns and must serialize byte-identically across
+ # repeat calls (compaction self-rescue).
+ text = json.dumps(output.model_dump(), ensure_ascii=False, sort_keys=True)
return AgentToolResult(
content=[TextContent(text=text)],
is_error=not output.expanded,
diff --git a/tests/deferred/_helpers.py b/tests/deferred/_helpers.py
new file mode 100644
index 0000000..59673e4
--- /dev/null
+++ b/tests/deferred/_helpers.py
@@ -0,0 +1,82 @@
+"""Shared test fixtures for the deferred-tools suite."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from pydantic import BaseModel
+
+from cubepi.agent.types import AgentTool, AgentToolResult
+from cubepi.deferred import DeferredToolGroup, DeferredToolsMiddleware
+from cubepi.providers.base import TextContent
+
+
+class _Empty(BaseModel):
+ pass
+
+
+class _EchoArgs(BaseModel):
+ value: str
+
+
+def _dummy_tool(
+ name: str, description: str = "dummy", *, expose: bool = True
+) -> AgentTool:
+ async def _exec(tool_call_id, args, *, signal=None, on_update=None):
+ return AgentToolResult(content=[TextContent(text="ok")])
+
+ return AgentTool(
+ name=name,
+ description=description,
+ parameters=_Empty,
+ execute=_exec,
+ expose_to_model=expose,
+ )
+
+
+def _echo_tool(name: str) -> AgentTool:
+ async def _exec(tool_call_id, args, *, signal=None, on_update=None):
+ return AgentToolResult(content=[TextContent(text=f"echo:{args.value}")])
+
+ return AgentTool(name=name, description="echo", parameters=_EchoArgs, execute=_exec)
+
+
+def _make_group(
+ group_id: str,
+ tool_names: list[str],
+ *,
+ display_name: str = "Test",
+ description: str = "desc",
+ tool_factory: Callable[[str], AgentTool] = _dummy_tool,
+ loader_tools: list[AgentTool] | None = None,
+ loader_call_count: list[int] | None = None,
+) -> DeferredToolGroup:
+ tools = loader_tools or [tool_factory(n) for n in tool_names]
+ call_count = loader_call_count if loader_call_count is not None else [0]
+
+ async def _loader() -> list[AgentTool]:
+ call_count[0] += 1
+ return list(tools)
+
+ return DeferredToolGroup(
+ group_id=group_id,
+ display_name=display_name,
+ description=description,
+ tool_names=tool_names,
+ loader=_loader,
+ )
+
+
+def _mw(groups, *, strategy="dispatch", extra=None) -> DeferredToolsMiddleware:
+ extra = extra if extra is not None else {}
+ return DeferredToolsMiddleware(
+ groups=groups, extra_ref=lambda: extra, strategy=strategy
+ )
+
+
+def _make_faux_model():
+ """Create a minimal BoundModel for Agent construction."""
+ from cubepi.providers.faux import FauxProvider
+
+ provider = FauxProvider()
+ return provider.model("faux")
diff --git a/tests/deferred/test_agent_wiring.py b/tests/deferred/test_agent_wiring.py
index 33c1b0c..6c6c00f 100644
--- a/tests/deferred/test_agent_wiring.py
+++ b/tests/deferred/test_agent_wiring.py
@@ -1,45 +1,17 @@
from __future__ import annotations
+from pydantic import BaseModel
+
from cubepi.agent.agent import Agent
-from cubepi.agent.types import AgentTool, AgentToolResult
-from cubepi.deferred import DeferredToolGroup, DeferredToolsMiddleware
-from cubepi.providers.base import TextContent
+from cubepi.deferred import DeferredToolsMiddleware
from cubepi.middleware.base import Middleware
-from pydantic import BaseModel
+from tests.deferred._helpers import _dummy_tool, _make_faux_model, _make_group
class _Empty(BaseModel):
pass
-def _dummy_tool(name: str) -> AgentTool:
- async def _exec(tool_call_id, args, *, signal=None, on_update=None):
- return AgentToolResult(content=[TextContent(text="ok")])
-
- return AgentTool(name=name, description="dummy", parameters=_Empty, execute=_exec)
-
-
-def _make_group(group_id: str, tool_names: list[str]) -> DeferredToolGroup:
- async def _loader():
- return [_dummy_tool(n) for n in tool_names]
-
- return DeferredToolGroup(
- group_id=group_id,
- display_name="Test",
- description="desc",
- tool_names=tool_names,
- loader=_loader,
- )
-
-
-def _make_faux_model():
- """Create a minimal BoundModel for Agent construction."""
- from cubepi.providers.faux import FauxProvider
-
- provider = FauxProvider()
- return provider.model("faux")
-
-
class TestAgentDeferredToolGroups:
def test_agent_accepts_deferred_tool_groups(self) -> None:
model = _make_faux_model()
diff --git a/tests/deferred/test_dispatch.py b/tests/deferred/test_dispatch.py
index 1201555..b054d09 100644
--- a/tests/deferred/test_dispatch.py
+++ b/tests/deferred/test_dispatch.py
@@ -1,31 +1,24 @@
from __future__ import annotations
+import functools
import json
from pydantic import BaseModel
from cubepi.agent.types import AgentContext, AgentTool, AgentToolResult
-from cubepi.deferred import DeferredToolGroup, DeferredToolsMiddleware
from cubepi.providers.base import TextContent, ToolCall
+from cubepi.deferred import DeferredToolsMiddleware
+from tests.deferred._helpers import _dummy_tool, _echo_tool, _mw
+from tests.deferred._helpers import _make_group as _make_group_base
+
+# Dispatch tests exercise real argument round-trips — echo tools throughout.
+_make_group = functools.partial(_make_group_base, tool_factory=_echo_tool)
class _Empty(BaseModel):
pass
-def _dummy_tool(name: str, *, expose: bool = True) -> AgentTool:
- async def _exec(tool_call_id, args, *, signal=None, on_update=None):
- return AgentToolResult(content=[TextContent(text="ok")])
-
- return AgentTool(
- name=name,
- description="dummy",
- parameters=_Empty,
- execute=_exec,
- expose_to_model=expose,
- )
-
-
class TestExposeToModel:
def test_default_is_true(self) -> None:
async def _exec(tool_call_id, args, *, signal=None, on_update=None):
@@ -40,37 +33,6 @@ class TestExposeToModel:
assert [d.name for d in visible] == ["visible"]
-class _EchoArgs(BaseModel):
- value: str
-
-
-def _echo_tool(name: str) -> AgentTool:
- async def _exec(tool_call_id, args, *, signal=None, on_update=None):
- return AgentToolResult(content=[TextContent(text=f"echo:{args.value}")])
-
- return AgentTool(name=name, description="echo", parameters=_EchoArgs, execute=_exec)
-
-
-def _make_group(gid: str, names: list[str]) -> DeferredToolGroup:
- async def _loader():
- return [_echo_tool(n) for n in names]
-
- return DeferredToolGroup(
- group_id=gid,
- display_name="Test",
- description="desc",
- tool_names=names,
- loader=_loader,
- )
-
-
-def _mw(groups, *, strategy="dispatch", extra=None):
- extra = extra if extra is not None else {}
- return DeferredToolsMiddleware(
- groups=groups, extra_ref=lambda: extra, strategy=strategy
- )
-
-
class TestDispatchStrategy:
def test_tools_attr_has_both_builtins(self) -> None:
mw = _mw([_make_group("g", ["t1"])])
diff --git a/tests/deferred/test_middleware.py b/tests/deferred/test_middleware.py
index 1a3991a..c56be86 100644
--- a/tests/deferred/test_middleware.py
+++ b/tests/deferred/test_middleware.py
@@ -4,45 +4,7 @@ from cubepi.agent.types import AgentContext, AgentTool, AgentToolResult
from cubepi.deferred.middleware import DeferredToolsMiddleware
from cubepi.deferred.types import DeferredToolGroup
from cubepi.providers.base import TextContent
-
-
-def _dummy_tool(name: str, description: str = "dummy") -> AgentTool:
- from pydantic import BaseModel
-
- class _Empty(BaseModel):
- pass
-
- async def _exec(tool_call_id, args, *, signal=None, on_update=None):
- return AgentToolResult(content=[TextContent(text="ok")])
-
- return AgentTool(
- name=name, description=description, parameters=_Empty, execute=_exec
- )
-
-
-def _make_group(
- group_id: str,
- tool_names: list[str],
- *,
- display_name: str = "Test",
- description: str = "desc",
- loader_tools: list[AgentTool] | None = None,
- loader_call_count: list[int] | None = None,
-) -> DeferredToolGroup:
- tools = loader_tools or [_dummy_tool(n) for n in tool_names]
- call_count = loader_call_count if loader_call_count is not None else [0]
-
- async def _loader() -> list[AgentTool]:
- call_count[0] += 1
- return list(tools)
-
- return DeferredToolGroup(
- group_id=group_id,
- display_name=display_name,
- description=description,
- tool_names=tool_names,
- loader=_loader,
- )
+from tests.deferred._helpers import _dummy_tool, _make_group
class TestMiddlewareConstruction: