Skip to content

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

fix(deferred): cross-turn persistence, fork isolation, race safety

xf gong8e70bdfd76ad
diff --git a/cubepi/agent/agent.py b/cubepi/agent/agent.py
index 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.py
index 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_ref
self._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 None
if 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):
continue
loaded = await group.loader()
+ cache[group.group_id] = loaded
if 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.py
index 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_names
diff --git a/tests/deferred/test_middleware.py b/tests/deferred/test_middleware.py
index 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 prompt
assert "mcp:slack" in prompt
assert "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.md
index 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`.