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 codex round-2 findings
xf gong1e221658c9a0
diff --git a/README.md b/README.mdindex 0e14cdb..65ffaa1 100644--- a/README.md+++ b/README.md@@ -200,12 +200,14 @@ let the model expand them on demand:from cubepi import Agentfrom 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 allload_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```pythonfrom 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.pyindex 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 resolutionsif 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.pyindex 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].textassert "Invalid arguments" in textassert "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.pyindex 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].textassert "Invalid arguments for tool 'deferred_tool_call'" in textassert "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"