Skip to content

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

feat(deferred): DeferredToolsMiddleware core (#166)

xf gongd2cde13f8527
diff --git a/cubepi/deferred/__init__.py b/cubepi/deferred/__init__.py
index 29a8464..4b486ae 100644
--- a/cubepi/deferred/__init__.py
+++ b/cubepi/deferred/__init__.py
@@ -1,5 +1,6 @@
"""Deferred tool groups — progressive tool disclosure primitive."""
+from cubepi.deferred.middleware import DeferredToolsMiddleware, ResumedState
from cubepi.deferred.types import DeferredToolGroup
-__all__ = ["DeferredToolGroup"]
+__all__ = ["DeferredToolGroup", "DeferredToolsMiddleware", "ResumedState"]
diff --git a/cubepi/deferred/middleware.py b/cubepi/deferred/middleware.py
new file mode 100644
index 0000000..7cc643c
--- /dev/null
+++ b/cubepi/deferred/middleware.py
@@ -0,0 +1,321 @@
+"""DeferredToolsMiddleware — progressive tool disclosure for large tool sets.
+
+Two-phase expansion:
+1. ``_expand_callback`` runs inside ``expand_tools`` execute (no AgentContext).
+ Validates, invokes the loader (cached), updates state, queues pending tools.
+2. ``after_tool_call`` fires after execute and injects pending tools into
+ ``ctx.context.tools`` so the next model loop iteration sees them.
+
+``_expand`` combines both phases for testing without the full agent loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from cubepi.agent.types import (
+ AfterToolCallContext,
+ AfterToolCallResult,
+ AgentContext,
+ AgentTool,
+)
+from cubepi.deferred._catalog import (
+ DEFAULT_CATALOG_HEADER,
+ ToolSchema,
+ render_catalog,
+ render_expanded_schemas,
+)
+from cubepi.deferred._expand_tool import (
+ ExpandToolsOutput,
+ _make_expand_tools,
+)
+from cubepi.deferred.types import DeferredToolGroup
+from cubepi.middleware.base import Middleware
+
+
+@dataclass
+class ResumedState:
+ """Pre-loaded tools and remaining groups for cross-run replay."""
+
+ pre_loaded_tools: list[AgentTool]
+ remaining_groups: list[DeferredToolGroup]
+
+
+class DeferredToolsMiddleware(Middleware):
+ """Middleware that manages deferred tool groups via progressive disclosure.
+
+ Attributes:
+ tools: ``[expand_tools]`` — merged into agent state at construction.
+ """
+
+ def __init__(
+ self,
+ *,
+ groups: list[DeferredToolGroup],
+ extra_ref: Callable[[], dict[str, Any]],
+ catalog_header: str = DEFAULT_CATALOG_HEADER,
+ ) -> None:
+ self._groups: dict[str, DeferredToolGroup] = {
+ g.group_id: g for g in groups
+ }
+ self._extra_ref = extra_ref
+ self._catalog_header = catalog_header
+
+ # Loader called exactly once per group per run.
+ self._loader_cache: dict[str, list[AgentTool]] = {}
+ # Append-only, expansion order for cache stability.
+ self._expanded_schemas: list[tuple[str, list[ToolSchema]]] = []
+ # Staging area: expand_callback queues, after_tool_call drains.
+ self._pending_injection: list[AgentTool] = []
+
+ self.tools: list[AgentTool] = [
+ _make_expand_tools(expand_callback=self._expand_callback)
+ ]
+
+ # ------------------------------------------------------------------
+ # Phase 1: expand callback (called from expand_tools execute)
+ # ------------------------------------------------------------------
+
+ async def _expand_callback(
+ self,
+ group_id: str,
+ tool_names: list[str] | None,
+ ) -> ExpandToolsOutput:
+ extra = self._extra_ref()
+ group = self._groups.get(group_id)
+ if group is None:
+ return ExpandToolsOutput(
+ group_id=group_id,
+ expanded=False,
+ tool_names=[],
+ remaining=0,
+ error=(
+ f"Unknown group_id: {group_id}. "
+ f"Available: {', '.join(sorted(self._groups))}"
+ ),
+ )
+
+ # Load once per group per run.
+ try:
+ if group_id not in self._loader_cache:
+ self._loader_cache[group_id] = await group.loader()
+ except Exception as exc:
+ return ExpandToolsOutput(
+ group_id=group_id,
+ expanded=False,
+ tool_names=[],
+ remaining=len(group.tool_names),
+ error=f"Loader failed: {exc}",
+ )
+
+ all_loaded = self._loader_cache[group_id]
+
+ # Determine what is already expanded.
+ expanded_groups: dict[str, list[str] | None] = extra.get(
+ "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.
+ already_set: set[str] = {t.name for t in all_loaded}
+ elif isinstance(already_val, list):
+ already_set = set(already_val)
+ else:
+ already_set = set()
+
+ # Filter to requested tools.
+ if tool_names is not None:
+ requested_set = set(tool_names)
+ requested = [t for t in all_loaded if t.name in requested_set]
+ else:
+ requested = list(all_loaded)
+
+ newly_expanded = [t for t in requested if t.name not in already_set]
+ expanded_names = [t.name for t in requested]
+
+ # Update expansion state.
+ if tool_names is None:
+ expanded_groups[group_id] = None
+ else:
+ prev = expanded_groups.get(group_id)
+ if prev is None and group_id in expanded_groups:
+ pass # already fully expanded, no-op
+ else:
+ merged = list(prev) if isinstance(prev, list) else []
+ merged_set = set(merged)
+ for name in expanded_names:
+ if name not in merged_set:
+ 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:
+ new_schemas = [
+ t.to_definition().model_dump() for t in newly_expanded
+ ]
+ existing_idx = next(
+ (
+ i
+ for i, (gid, _) in enumerate(self._expanded_schemas)
+ if gid == group_id
+ ),
+ None,
+ )
+ if existing_idx is not None:
+ prev_schemas = self._expanded_schemas[existing_idx][1]
+ self._expanded_schemas[existing_idx] = (
+ group_id,
+ prev_schemas + new_schemas,
+ )
+ else:
+ self._expanded_schemas.append((group_id, new_schemas))
+
+ # Stage newly expanded tools for injection by after_tool_call.
+ self._pending_injection = newly_expanded
+
+ # Calculate remaining count.
+ current_expanded = expanded_groups.get(group_id)
+ if current_expanded is None and group_id in expanded_groups:
+ remaining = 0
+ elif isinstance(current_expanded, list):
+ remaining = len(group.tool_names) - len(current_expanded)
+ else:
+ remaining = len(group.tool_names)
+
+ return ExpandToolsOutput(
+ group_id=group_id,
+ expanded=True,
+ tool_names=expanded_names,
+ remaining=max(remaining, 0),
+ )
+
+ # ------------------------------------------------------------------
+ # Combined expand + inject (for testing without the full agent loop)
+ # ------------------------------------------------------------------
+
+ async def _expand(
+ self,
+ *,
+ group_id: str,
+ tool_names: list[str] | None,
+ context: AgentContext,
+ ) -> ExpandToolsOutput:
+ output = await self._expand_callback(group_id, tool_names)
+ if output.expanded and self._pending_injection:
+ newly_expanded = self._pending_injection
+ self._pending_injection = []
+ 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)
+ return output
+
+ # ------------------------------------------------------------------
+ # Phase 2: after_tool_call hook (injects tools into live context)
+ # ------------------------------------------------------------------
+
+ async def after_tool_call(
+ self,
+ ctx: AfterToolCallContext,
+ *,
+ signal: asyncio.Event | None = None,
+ ) -> AfterToolCallResult | None:
+ del signal
+ if ctx.tool_call.name != "expand_tools":
+ return None
+ if ctx.is_error:
+ return None
+
+ if self._pending_injection:
+ newly_expanded = self._pending_injection
+ self._pending_injection = []
+ 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)
+
+ return None
+
+ # ------------------------------------------------------------------
+ # System prompt: catalog + expanded schemas
+ # ------------------------------------------------------------------
+
+ async def transform_system_prompt(
+ self,
+ system_prompt: str,
+ *,
+ ctx: AgentContext,
+ signal: asyncio.Event | None = None,
+ ) -> str:
+ del signal
+ extra = self._extra_ref()
+ expanded: dict[str, list[str] | None] = extra.get(
+ "expanded_groups", {},
+ )
+
+ catalog = render_catalog(
+ groups=list(self._groups.values()),
+ expanded=expanded,
+ header=self._catalog_header,
+ )
+
+ schemas = render_expanded_schemas(
+ expanded_schemas=self._expanded_schemas,
+ )
+
+ parts = [system_prompt]
+ if catalog:
+ parts.append(catalog)
+ if schemas:
+ parts.append(schemas)
+
+ return "\n\n".join(parts)
+
+ # ------------------------------------------------------------------
+ # Cross-run replay
+ # ------------------------------------------------------------------
+
+ @staticmethod
+ async def prepare_resumed_state(
+ groups: list[DeferredToolGroup],
+ expanded: dict[str, list[str] | None],
+ ) -> ResumedState:
+ """Replay expansion state from a previous run.
+
+ Fully expanded groups (``None``) get all tools pre-loaded and are
+ removed from the remaining set. Partially expanded groups get the
+ selected tools pre-loaded but stay in remaining (still deferrable).
+ Unexpanded groups pass through untouched.
+ """
+ pre_loaded: list[AgentTool] = []
+ remaining: list[DeferredToolGroup] = []
+
+ for group in groups:
+ exp = expanded.get(group.group_id)
+ if exp is None and group.group_id not in expanded:
+ # Never expanded — stays deferred.
+ remaining.append(group)
+ continue
+
+ loaded = await group.loader()
+ if exp is None:
+ # Fully expanded (None sentinel) — load all, drop from remaining.
+ pre_loaded.extend(loaded)
+ else:
+ # Partially expanded — load selected, keep in remaining.
+ name_set = set(exp)
+ selected = [t for t in loaded if t.name in name_set]
+ pre_loaded.extend(selected)
+ remaining.append(group)
+
+ return ResumedState(
+ pre_loaded_tools=pre_loaded,
+ remaining_groups=remaining,
+ )
diff --git a/tests/deferred/test_middleware.py b/tests/deferred/test_middleware.py
new file mode 100644
index 0000000..1c5b331
--- /dev/null
+++ b/tests/deferred/test_middleware.py
@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from cubepi.agent.types import AgentContext, AgentTool, AgentToolResult, AfterToolCallContext
+from cubepi.deferred.middleware import DeferredToolsMiddleware, ResumedState
+from cubepi.deferred.types import DeferredToolGroup
+from cubepi.providers.base import AssistantMessage, TextContent, ToolCall
+
+
+def _dummy_tool(name: str, description: str = "dummy") -> AgentTool:
+ from pydantic import BaseModel
+
+ class _Empty(BaseModel):
+ pass
+
+ async def _exec(tool_call_id, args, *, signal=None, on_update=None):
+ return AgentToolResult(content=[TextContent(text="ok")])
+
+ return AgentTool(name=name, description=description, parameters=_Empty, execute=_exec)
+
+
+def _make_group(
+ group_id: str,
+ tool_names: list[str],
+ *,
+ display_name: str = "Test",
+ description: str = "desc",
+ loader_tools: list[AgentTool] | None = None,
+ loader_call_count: list[int] | None = None,
+) -> DeferredToolGroup:
+ tools = loader_tools or [_dummy_tool(n) for n in tool_names]
+ call_count = loader_call_count if loader_call_count is not None else [0]
+
+ async def _loader() -> list[AgentTool]:
+ call_count[0] += 1
+ return list(tools)
+
+ return DeferredToolGroup(
+ group_id=group_id,
+ display_name=display_name,
+ description=description,
+ tool_names=tool_names,
+ loader=_loader,
+ )
+
+
+class TestMiddlewareConstruction:
+ def test_tools_attribute_contains_expand_tools(self) -> None:
+ extra: dict = {}
+ group = _make_group("mcp:a", ["t1"])
+ mw = DeferredToolsMiddleware(groups=[group], extra_ref=lambda: extra)
+ assert len(mw.tools) == 1
+ assert mw.tools[0].name == "expand_tools"
+
+
+class TestTransformSystemPrompt:
+ async def test_appends_catalog(self) -> None:
+ extra: dict = {}
+ group = _make_group("mcp:github", ["create_issue", "search_repos"])
+ mw = DeferredToolsMiddleware(groups=[group], extra_ref=lambda: extra)
+ ctx = AgentContext(system_prompt="base", messages=[])
+ result = await mw.transform_system_prompt("base prompt", ctx=ctx)
+ assert "mcp:github" in result
+ assert "create_issue" in result
+ assert "base prompt" in result
+
+ async def test_fully_expanded_group_omitted_from_catalog(self) -> None:
+ extra: dict = {"expanded_groups": {"mcp:github": None}}
+ group = _make_group("mcp:github", ["t1"])
+ mw = DeferredToolsMiddleware(groups=[group], extra_ref=lambda: extra)
+ ctx = AgentContext(system_prompt="", messages=[])
+ result = await mw.transform_system_prompt("base", ctx=ctx)
+ assert "mcp:github" not in result or "Expanded tool groups" in result
+
+ async def test_expanded_schemas_appended_after_catalog(self) -> None:
+ extra: dict = {"expanded_groups": {"mcp:a": None}}
+ group = _make_group("mcp:a", ["t1"])
+ mw = DeferredToolsMiddleware(groups=[group], extra_ref=lambda: extra)
+ mw._expanded_schemas.append(
+ ("mcp:a", [{"name": "t1", "description": "Tool 1", "parameters": {}}])
+ )
+ ctx = AgentContext(system_prompt="", messages=[])
+ result = await mw.transform_system_prompt("base", ctx=ctx)
+ assert "Expanded tool groups" in result
+ assert "t1" in result
+
+
+class TestAfterToolCallExpansion:
+ async def test_expand_all_injects_tools(self) -> None:
+ extra: dict = {}
+ group = _make_group("mcp:github", ["create_issue", "search_repos"])
+ mw = DeferredToolsMiddleware(groups=[group], extra_ref=lambda: extra)
+
+ context_tools: list[AgentTool] = [mw.tools[0]]
+ ctx = AgentContext(
+ system_prompt="", messages=[], tools=context_tools, extra=extra,
+ )
+
+ output = await mw._expand(
+ group_id="mcp:github", tool_names=None, context=ctx,
+ )
+ assert output.expanded is True
+ assert len(output.tool_names) == 2
+ assert output.remaining == 0
+ assert len(context_tools) == 3 # expand_tools + 2 new
+ assert extra["expanded_groups"] == {"mcp:github": None}
+
+ async def test_expand_selective_injects_only_requested(self) -> None:
+ extra: dict = {}
+ group = _make_group(
+ "mcp:github", ["create_issue", "search_repos", "create_pr"],
+ )
+ mw = DeferredToolsMiddleware(groups=[group], extra_ref=lambda: extra)
+
+ context_tools: list[AgentTool] = [mw.tools[0]]
+ ctx = AgentContext(
+ system_prompt="", messages=[], tools=context_tools, extra=extra,
+ )
+
+ output = await mw._expand(
+ group_id="mcp:github", tool_names=["create_issue"], context=ctx,
+ )
+ assert output.expanded is True
+ assert output.tool_names == ["create_issue"]
+ assert output.remaining == 2
+ assert len(context_tools) == 2 # expand_tools + 1 new
+ assert extra["expanded_groups"] == {"mcp:github": ["create_issue"]}
+
+ async def test_incremental_expand_same_group(self) -> None:
+ extra: dict = {}
+ call_count = [0]
+ group = _make_group(
+ "mcp:github", ["t1", "t2", "t3"], loader_call_count=call_count,
+ )
+ mw = DeferredToolsMiddleware(groups=[group], extra_ref=lambda: extra)
+
+ context_tools: list[AgentTool] = [mw.tools[0]]
+ ctx = AgentContext(
+ system_prompt="", messages=[], tools=context_tools, extra=extra,
+ )
+
+ await mw._expand(group_id="mcp:github", tool_names=["t1"], context=ctx)
+ assert len(context_tools) == 2
+ assert extra["expanded_groups"] == {"mcp:github": ["t1"]}
+
+ await mw._expand(group_id="mcp:github", tool_names=["t2"], context=ctx)
+ assert len(context_tools) == 3
+ assert extra["expanded_groups"] == {"mcp:github": ["t1", "t2"]}
+
+ assert call_count[0] == 1
+
+ async def test_expand_unknown_group_returns_error(self) -> None:
+ extra: dict = {}
+ mw = DeferredToolsMiddleware(groups=[], extra_ref=lambda: extra)
+ ctx = AgentContext(
+ system_prompt="", messages=[], tools=[], extra=extra,
+ )
+
+ output = await mw._expand(
+ group_id="bad:id", tool_names=None, context=ctx,
+ )
+ assert output.expanded is False
+ assert output.error is not None
+ assert "expanded_groups" not in extra
+
+ async def test_expand_idempotent_no_duplicate(self) -> None:
+ extra: dict = {}
+ group = _make_group("mcp:github", ["t1"])
+ mw = DeferredToolsMiddleware(groups=[group], extra_ref=lambda: extra)
+
+ context_tools: list[AgentTool] = [mw.tools[0]]
+ ctx = AgentContext(
+ system_prompt="", messages=[], tools=context_tools, extra=extra,
+ )
+
+ await mw._expand(
+ group_id="mcp:github", tool_names=None, context=ctx,
+ )
+ assert len(context_tools) == 2
+
+ await mw._expand(
+ group_id="mcp:github", tool_names=None, context=ctx,
+ )
+ assert len(context_tools) == 2
+
+ async def test_loader_failure_returns_error(self) -> None:
+ async def _failing_loader() -> list[AgentTool]:
+ raise RuntimeError("connection refused")
+
+ group = DeferredToolGroup(
+ group_id="mcp:broken",
+ display_name="Broken",
+ description="desc",
+ tool_names=["t1"],
+ loader=_failing_loader,
+ )
+ extra: dict = {}
+ mw = DeferredToolsMiddleware(groups=[group], extra_ref=lambda: extra)
+ ctx = AgentContext(
+ system_prompt="", messages=[], tools=[], extra=extra,
+ )
+
+ output = await mw._expand(
+ group_id="mcp:broken", tool_names=None, context=ctx,
+ )
+ assert output.expanded is False
+ assert "connection refused" in (output.error or "")
+ assert "expanded_groups" not in extra
+
+
+class TestExpansionOrderPreserved:
+ async def test_expansion_order_in_schemas(self) -> None:
+ extra: dict = {}
+ g1 = _make_group("mcp:z", ["tz"])
+ g2 = _make_group("mcp:a", ["ta"])
+ 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:z", tool_names=None, context=ctx)
+ await mw._expand(group_id="mcp:a", tool_names=None, context=ctx)
+
+ assert list(extra["expanded_groups"].keys()) == ["mcp:z", "mcp:a"]
+ assert len(mw._expanded_schemas) == 2
+ assert mw._expanded_schemas[0][0] == "mcp:z"
+ assert mw._expanded_schemas[1][0] == "mcp:a"
+
+
+class TestPrepareResumedState:
+ async def test_fully_expanded_group(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 len(resumed.pre_loaded_tools) == 2
+ assert len(resumed.remaining_groups) == 0
+
+ async def test_partially_expanded_group(self) -> None:
+ group = _make_group("mcp:github", ["t1", "t2", "t3"])
+ expanded: dict[str, list[str] | None] = {"mcp:github": ["t1"]}
+ resumed = await DeferredToolsMiddleware.prepare_resumed_state(
+ groups=[group], expanded=expanded,
+ )
+ assert len(resumed.pre_loaded_tools) == 1
+ assert resumed.pre_loaded_tools[0].name == "t1"
+ assert len(resumed.remaining_groups) == 1
+
+ async def test_unexpanded_group_stays_deferred(self) -> None:
+ group = _make_group("mcp:github", ["t1"])
+ expanded: dict[str, list[str] | None] = {}
+ resumed = await DeferredToolsMiddleware.prepare_resumed_state(
+ groups=[group], expanded=expanded,
+ )
+ assert len(resumed.pre_loaded_tools) == 0
+ assert len(resumed.remaining_groups) == 1