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
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.pyindex 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 anythingelse 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, Nonetry:rewritten = await resolve_tool_call(tool_call, context=context, signal=signal)except HitlControlException:raiseexcept 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, Noneasync 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 (thediff --git a/cubepi/deferred/_expand_tool.py b/cubepi/deferred/_expand_tool.pyindex 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_updateoutput = 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.pynew file mode 100644index 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.pyindex 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 DeferredToolsMiddlewarefrom cubepi.middleware.base import Middleware-from pydantic import BaseModel+from tests.deferred._helpers import _dummy_tool, _make_faux_model, _make_groupclass _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.pyindex 1201555..b054d09 100644--- a/tests/deferred/test_dispatch.py+++ b/tests/deferred/test_dispatch.py@@ -1,31 +1,24 @@from __future__ import annotations+import functoolsimport jsonfrom pydantic import BaseModelfrom cubepi.agent.types import AgentContext, AgentTool, AgentToolResult-from cubepi.deferred import DeferredToolGroup, DeferredToolsMiddlewarefrom 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.pyindex 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, AgentToolResultfrom cubepi.deferred.middleware import DeferredToolsMiddlewarefrom cubepi.deferred.types import DeferredToolGroupfrom 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_groupclass TestMiddlewareConstruction: