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(deferred): address PR codex review findings
xf gong4b433d07dce7
diff --git a/cubepi/agent/tools.py b/cubepi/agent/tools.pyindex e6efb5a..b5c0ca2 100644--- a/cubepi/agent/tools.py+++ b/cubepi/agent/tools.py@@ -372,21 +372,30 @@ async def execute_tool_calls() -> ToolCallBatch:tool_calls = [c for c in assistant_message.content if isinstance(c, ToolCall)]+ # Resolve up front (in order) so the execution-mode decision below sees+ # the REAL tool names — a dispatcher call targeting a sequential tool+ # must route through the sequential executor. Resolution is idempotent,+ # so hoisting it ahead of execution is safe.+ resolutions: list[tuple[ToolCall, bool, _ImmediateOutcome | None]] = []+ for tc in tool_calls:+ resolutions.append(+ await _resolve_tool_call(tc, context, resolve_tool_call, signal)+ )+has_sequential = any(t.execution_mode == "sequential"- for tc in tool_calls+ for (rtc, _, _) in resolutionsif context.toolsfor t in context.tools- if t.name == tc.name+ if t.name == rtc.name)if tool_execution == "sequential" or has_sequential:return await _execute_sequential(context,assistant_message,- tool_calls,+ resolutions,before_tool_call,- resolve_tool_call,after_tool_call,signal,emit,@@ -394,9 +403,8 @@ async def execute_tool_calls(return await _execute_parallel(context,assistant_message,- tool_calls,+ resolutions,before_tool_call,- resolve_tool_call,after_tool_call,signal,emit,@@ -406,9 +414,8 @@ async def execute_tool_calls(async def _execute_sequential(context: AgentContext,assistant_message: AssistantMessage,- tool_calls: list[ToolCall],+ resolutions: list[tuple[ToolCall, bool, _ImmediateOutcome | None]],before_tool_call: Callable | None,- resolve_tool_call: Callable | None,after_tool_call: Callable | None,signal: asyncio.Event | None,emit_fn: Callable,@@ -416,11 +423,7 @@ async def _execute_sequential(finalized_list: list[_FinalizedOutcome] = []messages: list[ToolResultMessage] = []- for tc in tool_calls:- rtc, was_resolved, resolver_error = await _resolve_tool_call(- tc, context, resolve_tool_call, signal- )-+ for rtc, was_resolved, resolver_error in resolutions:await emit_event(emit_fn,ToolExecutionStartEvent(@@ -482,9 +485,8 @@ async def _execute_sequential(async def _execute_parallel(context: AgentContext,assistant_message: AssistantMessage,- tool_calls: list[ToolCall],+ resolutions: list[tuple[ToolCall, bool, _ImmediateOutcome | None]],before_tool_call: Callable | None,- resolve_tool_call: Callable | None,after_tool_call: Callable | None,signal: asyncio.Event | None,emit_fn: Callable,@@ -499,10 +501,7 @@ async def _execute_parallel(# End event when prepare later raised, leaving state.pending_tool_calls# and trace spans permanently open.entries: list[_FinalizedOutcome | _PreparedToolCall] = []- for tc in tool_calls:- rtc, was_resolved, resolver_error = await _resolve_tool_call(- tc, context, resolve_tool_call, signal- )+ for rtc, was_resolved, resolver_error in resolutions:preparation = resolver_error or await _prepare_tool_call(context,assistant_message,diff --git a/cubepi/deferred/middleware.py b/cubepi/deferred/middleware.pyindex f54bb0d..9ed702d 100644--- a/cubepi/deferred/middleware.py+++ b/cubepi/deferred/middleware.py@@ -304,30 +304,60 @@ class DeferredToolsMiddleware(Middleware):name = args.get("tool_name") if isinstance(args, dict) else Noneif not isinstance(name, str) or name not in self._tool_to_group:return None # falls through to the dispatcher's error fallback+ inner = args.get("arguments")+ if inner is None:+ inner = {}+ if not isinstance(inner, dict):+ # Let the dispatcher's own schema validation reject the call —+ # coercing to {} would silently run no-arg tools on garbage+ # input.+ return Nonealready_loaded = context.tools is not None and any(t.name == name for t in context.tools)if not already_loaded:- await self._ensure_loaded(self._tool_to_group[name], [name], context)- inner = args.get("arguments")- return ToolCall(- id=tool_call.id,- name=name,- arguments=inner if isinstance(inner, dict) else {},- )+ error = await self._ensure_loaded(+ self._tool_to_group[name], [name], context+ )+ if error is not None:+ # The engine converts resolver exceptions into the call's+ # error result — the model sees WHY the load failed instead+ # of a misleading "tool not found".+ raise RuntimeError(error)+ return ToolCall(id=tool_call.id, name=name, arguments=inner)async def _ensure_loaded(self,group_id: str,tool_names: list[str],context: AgentContext,- ) -> None:- """Implicit load for dispatched calls: reuse the load path, then drain- staged tools into the live context immediately (no after_tool_call- fires on the dispatcher's behalf for a rewritten call)."""- await self._expand_callback(group_id, tool_names)+ ) -> str | None:+ """Ephemeral load for dispatched calls.++ Shares the loader cache and per-group locks (the loader still runs+ at most once per group per run) but records NO expansion state and+ never calls ``on_tools_expanded`` — a fork-forwarded resolver must+ not mutate the parent agent's ``extra`` or tool list. Recording+ state stays the job of an explicit ``load_tools`` call.++ Returns an error string when the loader failed, ``None`` on+ success.+ """+ group = self._groups[group_id]+ lock = self._loader_locks.setdefault(group_id, asyncio.Lock())+ async with lock:+ try:+ if group_id not in self._loader_cache:+ self._loader_cache[group_id] = await group.loader()+ except Exception as exc:+ return f"Loading deferred tool group '{group_id}' failed: {exc}"+ wanted = set(tool_names)if context.tools is not None:- self._drain_pending(context.tools)+ existing = {t.name for t in context.tools}+ for t in self._loader_cache[group_id]:+ if t.name in wanted and t.name not in existing:+ context.tools.append(replace(t, expose_to_model=False))+ return None# ------------------------------------------------------------------# System prompt: catalog (static in dispatch mode)diff --git a/dev/specs/2026-06-10-deferred-dispatcher.md b/dev/specs/2026-06-10-deferred-dispatcher.mdindex f27588a..15c7b18 100644--- a/dev/specs/2026-06-10-deferred-dispatcher.md+++ b/dev/specs/2026-06-10-deferred-dispatcher.md@@ -204,10 +204,14 @@ The middleware's resolver:1. `tool_call.name != "deferred_tool_call"` → return `None` (no-op for everything else).2. Parse `{tool_name, arguments}`. Unknown `tool_name` (not in any group) → leave the callunresolved with a structured error result listing valid names.-3. **Implicit load**: if `tool_name`'s group isn't loaded, run the loader (cache + lock), append- the group's tools to `context.tools` (`expose_to_model=False`), record load state in- `extra["expanded_groups"]`.-4. Return `ToolCall(id=同, name=tool_name, arguments=arguments)`.+3. **Implicit load** (ephemeral, state-free): if `tool_name` isn't already in+ `context.tools`, run the loader (shared cache + per-group lock), append the requested+ tool to `context.tools` (`expose_to_model=False`). No `extra["expanded_groups"]` write,+ no `on_tools_expanded` — state recording belongs to explicit `load_tools` only+ (fork-safety; see §Forks). A loader failure raises, which the engine converts into the+ call's error result.+4. Non-dict `arguments` → return `None` (the dispatcher's own schema validation rejects the+ call). Otherwise return `ToolCall(id=同, name=tool_name, arguments=arguments)`.**Validation failure includes the schema.** When a dispatch-resolved call fails`model_validate`, the error result appends the tool's full schema JSON, so the model retries@@ -224,12 +228,14 @@ payload, and no resolver runs), a regression vs v1 where expanded tools stayed uforks. `load_tools` remains fork-denied as in v1 (its *execute* is wrapped); the forwardedresolver, however, does not go through that execute — so dispatched calls work in forks foralready-loaded tools, and dispatching an unloaded tool triggers an **implicit load from the-fork**. This is deliberate: the loader cache and per-group locks live on the shared-middleware instance, so the loader still runs at most once across parent + forks, loaded-tools are appended hidden (no cache impact anywhere), and the recorded-`extra["expanded_groups"]` state simply pre-warms the parent. Deferred loading is-process-level resource acquisition, not conversation state — sharing it across forks is-coherent where v1's model-visible injection was not.+fork**. Implicit loads are **ephemeral and state-free** (revised per PR codex review): they+share only the loader cache and per-group locks (the loader still runs at most once across+parent + forks — process-level resource acquisition), append the hidden tool to the *local*+context only, and never write `extra["expanded_groups"]` or call `on_tools_expanded` — a+fork-forwarded resolver therefore cannot mutate the parent agent's state or tool list.+Recording expansion state stays the job of an explicit `load_tools` call. An implicit load+whose loader fails surfaces the loader error as the dispatched call's error result (not a+misleading "tool not found").`prepare_resumed_state` takes a **required** `strategy` kwarg (no default) so a host cannotresume with a strategy that mismatches its middleware construction.diff --git a/tests/deferred/test_dispatch.py b/tests/deferred/test_dispatch.pyindex b054d09..f8333fa 100644--- a/tests/deferred/test_dispatch.py+++ b/tests/deferred/test_dispatch.py@@ -7,7 +7,7 @@ from pydantic import BaseModelfrom cubepi.agent.types import AgentContext, AgentTool, AgentToolResultfrom cubepi.providers.base import TextContent, ToolCall-from cubepi.deferred import DeferredToolsMiddleware+from cubepi.deferred import DeferredToolGroup, DeferredToolsMiddlewarefrom tests.deferred._helpers import _dummy_tool, _echo_tool, _mwfrom tests.deferred._helpers import _make_group as _make_group_base@@ -325,3 +325,147 @@ class TestDispatchFork:if getattr(m, "tool_call_id", None) == "tc-2"]assert echo_results == ["echo:fork"]+++class TestCodexReviewFindings:+ async def test_dispatched_sequential_tool_runs_in_sequential_mode(self) -> None:+ """The execution-mode decision must see the RESOLVED tool name —+ a dispatcher call targeting a sequential tool may not run in the+ parallel executor."""+ import asyncio as aio++ from cubepi.agent.tools import execute_tool_calls+ from cubepi.providers.faux import faux_assistant_message++ order: list[str] = []++ class _NoArgs(BaseModel):+ pass++ async def _slow_exec(tool_call_id, args, *, signal=None, on_update=None):+ await aio.sleep(0.05)+ order.append("seq")+ return AgentToolResult(content=[TextContent(text="seq")])++ async def _fast_exec(tool_call_id, args, *, signal=None, on_update=None):+ order.append("fast")+ return AgentToolResult(content=[TextContent(text="fast")])++ seq_tool = AgentTool(+ name="seq_tool",+ description="d",+ parameters=_NoArgs,+ execute=_slow_exec,+ execution_mode="sequential",+ )+ fast_tool = AgentTool(+ name="fast_tool", description="d", parameters=_NoArgs, execute=_fast_exec+ )+ group = _make_group_base("g", ["seq_tool"], loader_tools=[seq_tool])+ extra: dict = {}+ mw = DeferredToolsMiddleware(+ groups=[group], extra_ref=lambda: extra, strategy="dispatch"+ )+ ctx = AgentContext(+ system_prompt="", messages=[], tools=[*mw.tools, fast_tool], extra=extra+ )+ calls = [+ ToolCall(+ id="tc-a",+ name="deferred_tool_call",+ arguments={"tool_name": "seq_tool", "arguments": {}},+ ),+ ToolCall(id="tc-b", name="fast_tool", arguments={}),+ ]+ await execute_tool_calls(+ ctx,+ faux_assistant_message(calls, stop_reason="tool_use"),+ resolve_tool_call=mw.resolve_tool_call,+ emit=lambda e: None,+ )+ assert order == ["seq", "fast"]++ async def test_implicit_load_records_no_state(self) -> None:+ """Implicit loads are ephemeral: no expanded_groups entry, no+ on_tools_expanded callback — a fork-forwarded resolver cannot+ mutate the parent agent."""+ extra: dict = {}+ seen: list = []+ group = _make_group("g", ["t1"])+ mw = DeferredToolsMiddleware(+ groups=[group],+ extra_ref=lambda: extra,+ strategy="dispatch",+ on_tools_expanded=seen.append,+ )+ ctx = AgentContext(system_prompt="", messages=[], tools=list(mw.tools))+ call = ToolCall(+ id="tc-1",+ name="deferred_tool_call",+ arguments={"tool_name": "t1", "arguments": {"value": "hi"}},+ )+ rewritten = await mw.resolve_tool_call(call, context=ctx)+ assert rewritten is not None and rewritten.name == "t1"+ assert any(t.name == "t1" and not t.expose_to_model for t in ctx.tools)+ assert "expanded_groups" not in extra+ assert seen == []++ async def test_implicit_load_failure_surfaces_loader_error(self) -> None:+ from cubepi.agent.tools import execute_tool_calls+ from cubepi.providers.faux import faux_assistant_message++ async def _failing_loader():+ raise RuntimeError("connection refused")++ group = DeferredToolGroup(+ group_id="g",+ display_name="G",+ description="d",+ tool_names=["t1"],+ loader=_failing_loader,+ )+ extra: dict = {}+ mw = DeferredToolsMiddleware(+ groups=[group], extra_ref=lambda: extra, strategy="dispatch"+ )+ ctx = AgentContext(system_prompt="", messages=[], tools=list(mw.tools))+ call = ToolCall(+ id="tc-f",+ name="deferred_tool_call",+ arguments={"tool_name": "t1", "arguments": {}},+ )+ batch = await execute_tool_calls(+ ctx,+ faux_assistant_message(call, stop_reason="tool_use"),+ resolve_tool_call=mw.resolve_tool_call,+ emit=lambda e: None,+ )+ msg = batch.messages[0]+ assert msg.is_error is True+ assert "connection refused" in msg.content[0].text+ assert "not found" not in msg.content[0].text++ async def test_dispatcher_rejects_non_dict_arguments(self) -> None:+ """Garbage inner arguments must hit the dispatcher's own schema+ validation, not be coerced to {} and silently run the tool."""+ from cubepi.agent.tools import execute_tool_calls+ from cubepi.providers.faux import faux_assistant_message++ mw = _mw([_make_group("g", ["t1"])])+ ctx = AgentContext(system_prompt="", messages=[], tools=list(mw.tools))+ call = ToolCall(+ id="tc-bad",+ name="deferred_tool_call",+ arguments={"tool_name": "t1", "arguments": "oops"},+ )+ batch = await execute_tool_calls(+ ctx,+ faux_assistant_message(call, stop_reason="tool_use"),+ resolve_tool_call=mw.resolve_tool_call,+ emit=lambda e: None,+ )+ msg = batch.messages[0]+ assert msg.is_error is True+ text = msg.content[0].text+ assert "Invalid arguments for tool 'deferred_tool_call'" in text+ assert "dictionary" in text