Skip to content

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

fix(deferred): address codex round-2 findings

xf gong1e221658c9a0
diff --git a/README.md b/README.md
index 0e14cdb..65ffaa1 100644
--- a/README.md
+++ b/README.md
@@ -200,12 +200,14 @@ let the model expand them on demand:
from cubepi import Agent
from cubepi.deferred import DeferredToolGroup
+# load_github_tools is a zero-arg async callable returning list[AgentTool]
+# (e.g. wrap load_mcp_tools_stdio(...).tools — see the website guide).
github_group = DeferredToolGroup(
group_id="mcp:github",
display_name="GitHub",
description="Issues, PRs, repos, code search",
tool_names=["create_issue", "search_repos", "create_pr", "list_comments"],
- loader=github_mcp.load_tools, # async () -> list[AgentTool]
+ loader=load_github_tools,
)
agent = Agent(
@@ -231,9 +233,13 @@ load_tools(group_id="mcp:github") # load all
load_tools(group_id="mcp:github", tool_names=["create_issue"]) # or just one
```
-The loader is called once per group per run; subsequent selective expansions
-filter from the cached result. Expanded tool schemas are appended to the system
-prompt in expansion order (append-only) for prompt-cache prefix stability.
+The loader is called once per group per run; subsequent selective loads filter
+from the cached result. With the default `dispatch` strategy, `load_tools`
+returns the full schemas in its tool result and loaded tools are invoked via
+the `deferred_tool_call` dispatcher — the tools array and system prompt stay
+byte-stable, so loading never invalidates the prompt cache. The v1 behavior
+(native injection into the model-visible tools array) is available with
+`deferred_tool_strategy="inject"`.
For advanced use (custom catalog header, cross-run replay), construct
`DeferredToolsMiddleware` directly:
@@ -241,10 +247,12 @@ For advanced use (custom catalog header, cross-run replay), construct
```python
from cubepi.deferred import DeferredToolsMiddleware
-# Replay expansion state from a previous run
+# Replay expansion state from a previous run (strategy is required and
+# must match the middleware's strategy)
resumed = await DeferredToolsMiddleware.prepare_resumed_state(
groups=all_groups,
expanded=saved_extra["expanded_groups"],
+ strategy="dispatch",
)
agent = Agent(
model=model,
diff --git a/cubepi/agent/tools.py b/cubepi/agent/tools.py
index b5c0ca2..167cc92 100644
--- a/cubepi/agent/tools.py
+++ b/cubepi/agent/tools.py
@@ -167,6 +167,13 @@ async def _resolve_tool_call(
)
if rewritten is None:
return tool_call, False, None
+ if rewritten.id != tool_call.id:
+ # Enforce the resolver contract: the result message is keyed by the
+ # original id on the wire, so a resolver that invents a new id would
+ # desynchronize provider-side tool_result correlation.
+ rewritten = ToolCall(
+ id=tool_call.id, name=rewritten.name, arguments=rewritten.arguments
+ )
return rewritten, True, None
@@ -372,17 +379,41 @@ 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.
+ has_sequential_raw = any(
+ t.execution_mode == "sequential"
+ for tc in tool_calls
+ if context.tools
+ for t in context.tools
+ if t.name == tc.name
+ )
+
+ if tool_execution == "sequential" or has_sequential_raw:
+ # Already sequential by raw names: resolve lazily, one call at a
+ # time, so a later dispatcher call's side effects (e.g. a deferred
+ # group loader) never run before an earlier sequential tool that
+ # may set up the state they depend on.
+ return await _execute_sequential(
+ context,
+ assistant_message,
+ tool_calls,
+ before_tool_call,
+ resolve_tool_call,
+ after_tool_call,
+ signal,
+ emit,
+ )
+
+ # Would-be-parallel batch: no ordering guarantee exists, so resolution
+ # may run eagerly. It must — the execution-mode decision has to see the
+ # REAL tool names: a dispatcher call targeting a sequential tool routes
+ # the whole batch through the sequential executor.
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(
+ has_sequential_resolved = any(
t.execution_mode == "sequential"
for (rtc, _, _) in resolutions
if context.tools
@@ -390,15 +421,17 @@ async def execute_tool_calls(
if t.name == rtc.name
)
- if tool_execution == "sequential" or has_sequential:
+ if has_sequential_resolved:
return await _execute_sequential(
context,
assistant_message,
- resolutions,
+ tool_calls,
before_tool_call,
+ resolve_tool_call,
after_tool_call,
signal,
emit,
+ preresolved=resolutions,
)
return await _execute_parallel(
context,
@@ -414,16 +447,28 @@ async def execute_tool_calls(
async def _execute_sequential(
context: AgentContext,
assistant_message: AssistantMessage,
- resolutions: list[tuple[ToolCall, bool, _ImmediateOutcome | None]],
+ tool_calls: list[ToolCall],
before_tool_call: Callable | None,
+ resolve_tool_call: Callable | None,
after_tool_call: Callable | None,
signal: asyncio.Event | None,
emit_fn: Callable,
+ *,
+ preresolved: list[tuple[ToolCall, bool, _ImmediateOutcome | None]] | None = None,
) -> ToolCallBatch:
finalized_list: list[_FinalizedOutcome] = []
messages: list[ToolResultMessage] = []
- for rtc, was_resolved, resolver_error in resolutions:
+ for idx, tc in enumerate(tool_calls):
+ if preresolved is not None:
+ rtc, was_resolved, resolver_error = preresolved[idx]
+ else:
+ # Lazy: resolve only when this call's turn comes, after every
+ # earlier call in the batch has fully executed.
+ rtc, was_resolved, resolver_error = await _resolve_tool_call(
+ tc, context, resolve_tool_call, signal
+ )
+
await emit_event(
emit_fn,
ToolExecutionStartEvent(
diff --git a/tests/agent/test_resolve_tool_call.py b/tests/agent/test_resolve_tool_call.py
index b820d0a..5b66c62 100644
--- a/tests/agent/test_resolve_tool_call.py
+++ b/tests/agent/test_resolve_tool_call.py
@@ -155,3 +155,30 @@ async def test_unresolved_call_validation_error_has_no_schema() -> None:
text = batch.messages[0].content[0].text
assert "Invalid arguments" in text
assert "Full schema" not in text
+
+
+async def test_rewritten_call_keeps_original_id() -> None:
+ """The engine enforces the resolver contract: a rewritten call that
+ changes the id is corrected back to the original, so provider-side
+ tool_result correlation never desynchronizes."""
+ real = _echo_tool("real_tool", expose=False)
+ ctx = AgentContext(system_prompt="", messages=[], tools=[real])
+ call = ToolCall(
+ id="tc-orig",
+ name="deferred_tool_call",
+ arguments={"tool_name": "real_tool", "arguments": {"value": "hi"}},
+ )
+
+ async def sloppy_resolver(tool_call, *, context, signal=None):
+ return ToolCall( # buggy: invents a new id
+ id="tc-INVENTED",
+ name="real_tool",
+ arguments=tool_call.arguments["arguments"],
+ )
+
+ batch = await execute_tool_calls(
+ ctx, _assistant_with(call), resolve_tool_call=sloppy_resolver, emit=_noop_emit
+ )
+ msg = batch.messages[0]
+ assert msg.tool_call_id == "tc-orig"
+ assert msg.content[0].text == "echo:hi"
diff --git a/tests/deferred/test_dispatch.py b/tests/deferred/test_dispatch.py
index f8333fa..44f78f1 100644
--- a/tests/deferred/test_dispatch.py
+++ b/tests/deferred/test_dispatch.py
@@ -469,3 +469,67 @@ class TestCodexReviewFindings:
text = msg.content[0].text
assert "Invalid arguments for tool 'deferred_tool_call'" in text
assert "dictionary" in text
+
+
+class TestSequentialOrderingPreserved:
+ async def test_sequential_batch_resolves_lazily(self) -> None:
+ """In a batch that is sequential by raw names, a later dispatcher
+ call's loader must NOT run before an earlier sequential tool has
+ executed (the loader may depend on state that tool sets up)."""
+ from cubepi.agent.tools import execute_tool_calls
+ from cubepi.providers.faux import faux_assistant_message
+
+ class _NoArgs(BaseModel):
+ pass
+
+ state: dict = {}
+
+ async def _setup_exec(tool_call_id, args, *, signal=None, on_update=None):
+ state["credentials"] = "ready"
+ return AgentToolResult(content=[TextContent(text="setup done")])
+
+ setup_tool = AgentTool(
+ name="setup_tool",
+ description="d",
+ parameters=_NoArgs,
+ execute=_setup_exec,
+ execution_mode="sequential",
+ )
+
+ loader_saw: list = []
+
+ async def _loader():
+ loader_saw.append(state.get("credentials"))
+ return [_echo_tool("t1")]
+
+ group = DeferredToolGroup(
+ group_id="g",
+ display_name="G",
+ description="d",
+ tool_names=["t1"],
+ loader=_loader,
+ )
+ extra: dict = {}
+ mw = DeferredToolsMiddleware(
+ groups=[group], extra_ref=lambda: extra, strategy="dispatch"
+ )
+ ctx = AgentContext(
+ system_prompt="", messages=[], tools=[*mw.tools, setup_tool], extra=extra
+ )
+ calls = [
+ ToolCall(id="tc-1", name="setup_tool", arguments={}),
+ ToolCall(
+ id="tc-2",
+ name="deferred_tool_call",
+ arguments={"tool_name": "t1", "arguments": {"value": "hi"}},
+ ),
+ ]
+ batch = await execute_tool_calls(
+ ctx,
+ faux_assistant_message(calls, stop_reason="tool_use"),
+ resolve_tool_call=mw.resolve_tool_call,
+ emit=lambda e: None,
+ )
+ # Loader ran AFTER the sequential setup tool executed.
+ assert loader_saw == ["ready"]
+ assert batch.messages[1].content[0].text == "echo:hi"