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): cross-turn persistence, fork isolation, race safety
xf gong8e70bdfd76ad
diff --git a/cubepi/agent/agent.py b/cubepi/agent/agent.pyindex 5c33acd..52fd6da 100644--- a/cubepi/agent/agent.py+++ b/cubepi/agent/agent.py@@ -190,6 +190,7 @@ class Agent(Generic[TMessage]):deferred_mw = DeferredToolsMiddleware(groups=deferred_tool_groups,extra_ref=lambda: self._extra,+ on_tools_expanded=lambda tools: self._state._tools.extend(tools),)middleware = [*(middleware or []), deferred_mw]middleware = middleware or []@@ -535,10 +536,17 @@ class Agent(Generic[TMessage]):# as explicit args means we pass middleware=[] to avoid composing# middleware twice — the parent's composed result already lives on# self.transform_context etc.+ #+ # Strip middleware-owned tools (e.g. expand_tools) — their execute+ # callbacks close over the parent's state and would corrupt it.+ _mw_tool_ids = {+ id(t) for mw in self._middleware for t in getattr(mw, "tools", []) or []+ }+ fork_tools = [t for t in self._state.tools if id(t) not in _mw_tool_ids]child: Agent = Agent(model=self._model,system_prompt=self._state.system_prompt,- tools=list(self._state.tools),+ tools=fork_tools,thinking=self._state.thinking,convert_to_llm=self.convert_to_llm,transform_context=self.transform_context,diff --git a/cubepi/deferred/middleware.py b/cubepi/deferred/middleware.pyindex ccc2d0b..9ec4392 100644--- a/cubepi/deferred/middleware.py+++ b/cubepi/deferred/middleware.py@@ -43,6 +43,7 @@ class ResumedState:pre_loaded_tools: list[AgentTool]remaining_groups: list[DeferredToolGroup]expanded_schemas: list[tuple[str, list[ToolSchema]]]+ loader_cache: dict[str, list[AgentTool]]class DeferredToolsMiddleware(Middleware):@@ -59,13 +60,18 @@ class DeferredToolsMiddleware(Middleware):extra_ref: Callable[[], dict[str, Any]],catalog_header: str = DEFAULT_CATALOG_HEADER,resumed_schemas: list[tuple[str, list[ToolSchema]]] | None = None,+ resumed_loader_cache: dict[str, list[AgentTool]] | None = None,+ on_tools_expanded: Callable[[list[AgentTool]], None] | None = None,) -> None:self._groups: dict[str, DeferredToolGroup] = {g.group_id: g for g in groups}self._extra_ref = extra_refself._catalog_header = catalog_header+ self._on_tools_expanded = on_tools_expanded# Loader called exactly once per group per run.- self._loader_cache: dict[str, list[AgentTool]] = {}+ self._loader_cache: dict[str, list[AgentTool]] = (+ dict(resumed_loader_cache) if resumed_loader_cache else {}+ )# Append-only, expansion order for cache stability.self._expanded_schemas: list[tuple[str, list[ToolSchema]]] = (list(resumed_schemas) if resumed_schemas else []@@ -115,11 +121,10 @@ class DeferredToolsMiddleware(Middleware):all_loaded = self._loader_cache[group_id]- # Determine what is already expanded.- expanded_groups: dict[str, list[str] | None] = extra.get(- "expanded_groups",- {},- )+ # Use the shared dict in extra — never replace it, only mutate in place.+ if "expanded_groups" not in extra:+ extra["expanded_groups"] = {}+ expanded_groups: dict[str, list[str] | None] = extra["expanded_groups"]already_val = expanded_groups.get(group_id)if group_id in expanded_groups and already_val is None:# Fully expanded (None sentinel) — everything already injected.@@ -154,7 +159,6 @@ class DeferredToolsMiddleware(Middleware):merged.append(name)merged_set.add(name)expanded_groups[group_id] = merged- extra["expanded_groups"] = expanded_groups# Record schemas for expanded tools (append-only).if newly_expanded:@@ -178,6 +182,9 @@ class DeferredToolsMiddleware(Middleware):# Stage newly expanded tools for injection by after_tool_call.self._pending_injection.extend(newly_expanded)+ # Persist to the agent's canonical tool list for cross-prompt() use.+ if newly_expanded and self._on_tools_expanded:+ self._on_tools_expanded(newly_expanded)# Calculate remaining count.current_expanded = expanded_groups.get(group_id)@@ -195,6 +202,22 @@ class DeferredToolsMiddleware(Middleware):remaining=max(remaining, 0),)+ # ------------------------------------------------------------------+ # Drain pending injection into a tools list (shared by _expand and+ # after_tool_call so the dedup logic lives in one place).+ # ------------------------------------------------------------------++ def _drain_pending(self, tools: list[AgentTool]) -> None:+ if not self._pending_injection:+ return+ pending = list(self._pending_injection)+ self._pending_injection.clear()+ existing_names = {t.name for t in tools}+ for tool in pending:+ if tool.name not in existing_names:+ tools.append(tool)+ existing_names.add(tool.name)+# ------------------------------------------------------------------# Combined expand + inject (for testing without the full agent loop)# ------------------------------------------------------------------@@ -207,14 +230,8 @@ class DeferredToolsMiddleware(Middleware):context: AgentContext,) -> ExpandToolsOutput:output = await self._expand_callback(group_id, tool_names)- if output.expanded and self._pending_injection:- newly_expanded = list(self._pending_injection)- self._pending_injection.clear()- if context.tools is not None:- existing_names = {t.name for t in context.tools}- for tool in newly_expanded:- if tool.name not in existing_names:- context.tools.append(tool)+ if output.expanded and context.tools is not None:+ self._drain_pending(context.tools)return output# ------------------------------------------------------------------@@ -232,16 +249,8 @@ class DeferredToolsMiddleware(Middleware):return Noneif ctx.is_error:return None-- if self._pending_injection:- newly_expanded = list(self._pending_injection)- self._pending_injection.clear()- if ctx.context.tools is not None:- existing_names = {t.name for t in ctx.context.tools}- for tool in newly_expanded:- if tool.name not in existing_names:- ctx.context.tools.append(tool)-+ if ctx.context.tools is not None:+ self._drain_pending(ctx.context.tools)return None# ------------------------------------------------------------------@@ -299,6 +308,7 @@ class DeferredToolsMiddleware(Middleware):pre_loaded: list[AgentTool] = []remaining: list[DeferredToolGroup] = []schemas: list[tuple[str, list[ToolSchema]]] = []+ cache: dict[str, list[AgentTool]] = {}for group in groups:exp = expanded.get(group.group_id)@@ -308,6 +318,7 @@ class DeferredToolsMiddleware(Middleware):continueloaded = await group.loader()+ cache[group.group_id] = loadedif exp is None:# Fully expanded (None sentinel) — load all, drop from remaining.pre_loaded.extend(loaded)@@ -334,4 +345,5 @@ class DeferredToolsMiddleware(Middleware):pre_loaded_tools=pre_loaded,remaining_groups=remaining,expanded_schemas=schemas,+ loader_cache=cache,)diff --git a/tests/deferred/test_agent_wiring.py b/tests/deferred/test_agent_wiring.pyindex 4a681f9..677dac9 100644--- a/tests/deferred/test_agent_wiring.py+++ b/tests/deferred/test_agent_wiring.py@@ -120,3 +120,35 @@ class TestAgentDeferredToolGroups:assert not any(isinstance(mw, DeferredToolsMiddleware) for mw in agent._middleware)++ def test_on_tools_expanded_wired(self) -> None:+ model = _make_faux_model()+ group = _make_group("mcp:github", ["t1"])+ agent = Agent(+ model=model,+ tools=[_dummy_tool("builtin")],+ deferred_tool_groups=[group],+ )+ deferred_mw = next(+ mw for mw in agent._middleware if isinstance(mw, DeferredToolsMiddleware)+ )+ assert deferred_mw._on_tools_expanded is not None+++class TestForkOnceStripsMiddlewareTools:+ def test_fork_tools_exclude_expand_tools(self) -> None:+ model = _make_faux_model()+ group = _make_group("mcp:github", ["t1", "t2"])+ agent = Agent(+ model=model,+ tools=[_dummy_tool("builtin")],+ deferred_tool_groups=[group],+ )+ # Collect middleware tool ids.+ mw_tool_ids = {+ id(t) for mw in agent._middleware for t in getattr(mw, "tools", []) or []+ }+ fork_tools = [t for t in agent._state.tools if id(t) not in mw_tool_ids]+ fork_tool_names = [t.name for t in fork_tools]+ assert "builtin" in fork_tool_names+ assert "expand_tools" not in fork_tool_namesdiff --git a/tests/deferred/test_middleware.py b/tests/deferred/test_middleware.pyindex df2e05f..6f7a209 100644--- a/tests/deferred/test_middleware.py+++ b/tests/deferred/test_middleware.py@@ -330,3 +330,106 @@ class TestPrepareResumedState:assert "mcp:github" in promptassert "mcp:slack" in promptassert "t1" in prompt++ async def test_loader_cache_populated(self) -> None:+ group = _make_group("mcp:github", ["t1", "t2"])+ expanded: dict[str, list[str] | None] = {"mcp:github": None}+ resumed = await DeferredToolsMiddleware.prepare_resumed_state(+ groups=[group],+ expanded=expanded,+ )+ assert "mcp:github" in resumed.loader_cache+ assert len(resumed.loader_cache["mcp:github"]) == 2++ async def test_resumed_loader_cache_skips_reload(self) -> None:+ call_count = [0]+ group = _make_group("mcp:github", ["t1"], loader_call_count=call_count)+ expanded: dict[str, list[str] | None] = {"mcp:github": ["t1"]}+ resumed = await DeferredToolsMiddleware.prepare_resumed_state(+ groups=[group],+ expanded=expanded,+ )+ assert call_count[0] == 1++ extra: dict = {"expanded_groups": dict(expanded)}+ mw = DeferredToolsMiddleware(+ groups=resumed.remaining_groups,+ extra_ref=lambda: extra,+ resumed_schemas=resumed.expanded_schemas,+ resumed_loader_cache=resumed.loader_cache,+ )+ ctx = AgentContext(+ system_prompt="",+ messages=[],+ tools=list(mw.tools) + resumed.pre_loaded_tools,+ extra=extra,+ )+ # Expanding remaining tools should NOT call loader again.+ await mw._expand(group_id="mcp:github", tool_names=None, context=ctx)+ assert call_count[0] == 1 # still 1, not 2+++class TestOnToolsExpandedCallback:+ async def test_callback_invoked_on_expansion(self) -> None:+ expanded_tools: list[AgentTool] = []+ extra: dict = {}+ group = _make_group("mcp:github", ["t1", "t2"])+ mw = DeferredToolsMiddleware(+ groups=[group],+ extra_ref=lambda: extra,+ on_tools_expanded=lambda tools: expanded_tools.extend(tools),+ )+ ctx = AgentContext(+ system_prompt="",+ messages=[],+ tools=list(mw.tools),+ extra=extra,+ )+ await mw._expand(group_id="mcp:github", tool_names=None, context=ctx)+ assert len(expanded_tools) == 2+ assert {t.name for t in expanded_tools} == {"t1", "t2"}++ async def test_callback_not_invoked_on_idempotent(self) -> None:+ call_count = [0]++ def _on_expanded(tools: list[AgentTool]) -> None:+ call_count[0] += 1++ extra: dict = {}+ group = _make_group("mcp:github", ["t1"])+ mw = DeferredToolsMiddleware(+ groups=[group],+ extra_ref=lambda: extra,+ on_tools_expanded=_on_expanded,+ )+ ctx = AgentContext(+ system_prompt="",+ messages=[],+ tools=list(mw.tools),+ extra=extra,+ )+ await mw._expand(group_id="mcp:github", tool_names=None, context=ctx)+ assert call_count[0] == 1+ await mw._expand(group_id="mcp:github", tool_names=None, context=ctx)+ assert call_count[0] == 1 # no new tools, no callback+++class TestExpandedGroupsDictStability:+ async def test_shared_dict_mutated_in_place(self) -> None:+ """expanded_groups dict in extra is mutated in place, not replaced."""+ extra: dict = {}+ g1 = _make_group("mcp:a", ["t1"])+ g2 = _make_group("mcp:b", ["t2"])+ mw = DeferredToolsMiddleware(groups=[g1, g2], extra_ref=lambda: extra)+ ctx = AgentContext(+ system_prompt="",+ messages=[],+ tools=list(mw.tools),+ extra=extra,+ )+ await mw._expand(group_id="mcp:a", tool_names=None, context=ctx)+ dict_ref = extra["expanded_groups"]+ await mw._expand(group_id="mcp:b", tool_names=None, context=ctx)+ # Same dict object, not a new one.+ assert extra["expanded_groups"] is dict_ref+ assert set(dict_ref.keys()) == {"mcp:a", "mcp:b"}diff --git a/website/docs/guides/middleware/deferred-tools.md b/website/docs/guides/middleware/deferred-tools.mdindex 730a9eb..4999156 100644--- a/website/docs/guides/middleware/deferred-tools.md+++ b/website/docs/guides/middleware/deferred-tools.md@@ -180,6 +180,7 @@ agent = Agent(| `pre_loaded_tools` | Tools from previously-expanded groups, ready to use || `remaining_groups` | Groups that were never expanded or only partially expanded || `expanded_schemas` | Schema data for the system prompt (pass to `resumed_schemas` for advanced use) |+| `loader_cache` | Pre-loaded tool cache (pass to `resumed_loader_cache` to avoid redundant loader calls) |Fully expanded groups are loaded and removed from the deferred set.Partially expanded groups load the selected tools but stay deferrable@@ -197,6 +198,7 @@ mw = DeferredToolsMiddleware(groups=resumed.remaining_groups,extra_ref=lambda: agent_extra,resumed_schemas=resumed.expanded_schemas,+ resumed_loader_cache=resumed.loader_cache,)agent = Agent(@@ -236,6 +238,8 @@ agent = Agent(| `extra_ref` | `() -> dict` | required | Returns the live `ctx.extra` dict || `catalog_header` | `str` | *(built-in)* | Header text for the catalog section || `resumed_schemas` | `list[tuple[str, list[dict]]] \| None` | `None` | Schema data to seed from a previous run |+| `resumed_loader_cache` | `dict[str, list[AgentTool]] \| None` | `None` | Pre-loaded tool cache from a previous run (avoids re-calling loaders on resume) |+| `on_tools_expanded` | `(list[AgentTool]) -> None \| None` | `None` | Called after new tools are expanded (used internally for cross-turn persistence) |When using the `Agent(deferred_tool_groups=...)` shorthand, `extra_ref`is automatically bound to `self._extra`.