Skip to content

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

feat(deferred): add DeferredToolGroup dataclass (#166)

xf gong34dc2cb27e74
diff --git a/cubepi/deferred/__init__.py b/cubepi/deferred/__init__.py
new file mode 100644
index 0000000..29a8464
--- /dev/null
+++ b/cubepi/deferred/__init__.py
@@ -0,0 +1,5 @@
+"""Deferred tool groups — progressive tool disclosure primitive."""
+
+from cubepi.deferred.types import DeferredToolGroup
+
+__all__ = ["DeferredToolGroup"]
diff --git a/cubepi/deferred/types.py b/cubepi/deferred/types.py
new file mode 100644
index 0000000..289c88f
--- /dev/null
+++ b/cubepi/deferred/types.py
@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from cubepi.agent.types import AgentTool
+
+
+@dataclass
+class DeferredToolGroup:
+ """A group of tools that starts collapsed and expands on demand.
+
+ ``loader`` is called exactly once per group per agent run — the middleware
+ caches the result and filters by ``tool_names`` on selective expansions.
+ """
+
+ group_id: str
+ display_name: str
+ description: str
+ tool_names: list[str]
+ loader: Callable[[], Awaitable[list[AgentTool]]]
diff --git a/tests/deferred/__init__.py b/tests/deferred/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/deferred/test_catalog.py b/tests/deferred/test_catalog.py
new file mode 100644
index 0000000..0e32022
--- /dev/null
+++ b/tests/deferred/test_catalog.py
@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import pytest
+
+from cubepi.deferred.types import DeferredToolGroup
+
+
+class TestDeferredToolGroup:
+ def test_basic_construction(self) -> None:
+ async def _loader():
+ return []
+
+ group = DeferredToolGroup(
+ group_id="mcp:github",
+ display_name="GitHub",
+ description="Code hosting: issues, PRs, repos",
+ tool_names=["create_issue", "search_repos"],
+ loader=_loader,
+ )
+ assert group.group_id == "mcp:github"
+ assert group.display_name == "GitHub"
+ assert group.description == "Code hosting: issues, PRs, repos"
+ assert group.tool_names == ["create_issue", "search_repos"]
+ assert group.loader is _loader