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
feat(deferred): DeferredToolsMiddleware core (#166)
xf gongd2cde13f8527
diff --git a/cubepi/deferred/__init__.py b/cubepi/deferred/__init__.pyindex 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, ResumedStatefrom cubepi.deferred.types import DeferredToolGroup-__all__ = ["DeferredToolGroup"]+__all__ = ["DeferredToolGroup", "DeferredToolsMiddleware", "ResumedState"]diff --git a/cubepi/deferred/middleware.py b/cubepi/deferred/middleware.pynew file mode 100644index 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.pynew file mode 100644index 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