Skip to content

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

feat(deferred): expand_tools builtin tool (#166)

xf gong0dd95263729d
diff --git a/cubepi/deferred/_expand_tool.py b/cubepi/deferred/_expand_tool.py
new file mode 100644
index 0000000..525fb5e
--- /dev/null
+++ b/cubepi/deferred/_expand_tool.py
@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable
+
+from pydantic import BaseModel, Field
+
+from cubepi.agent.types import AgentTool, AgentToolResult
+from cubepi.providers.base import TextContent
+from cubepi.types import StructuredValue
+
+
+class ExpandToolsInput(BaseModel):
+ group_id: str = Field(
+ description="The group_id from your 'Deferred tool groups' catalog.",
+ )
+ tool_names: list[str] | None = Field(
+ default=None,
+ description="Specific tools to expand. Omit to expand all tools in the group.",
+ )
+
+
+class ExpandToolsOutput(BaseModel):
+ group_id: str
+ expanded: bool
+ tool_names: list[str]
+ remaining: int
+ error: str | None = None
+
+
+ExpandCallback = Callable[
+ [str, list[str] | None],
+ Awaitable[ExpandToolsOutput],
+]
+
+
+def _make_expand_tools(
+ *,
+ expand_callback: ExpandCallback,
+) -> AgentTool[ExpandToolsInput]:
+ async def _execute(
+ tool_call_id: str,
+ args: ExpandToolsInput,
+ *,
+ signal: asyncio.Event | None = None,
+ on_update: Callable[[StructuredValue], None] | None = None,
+ ) -> AgentToolResult:
+ del signal, on_update
+ output = await expand_callback(args.group_id, args.tool_names)
+ text = json.dumps(output.model_dump(), ensure_ascii=False)
+ return AgentToolResult(
+ content=[TextContent(text=text)],
+ is_error=bool(output.error),
+ )
+
+ return AgentTool(
+ name="expand_tools",
+ description=(
+ "Expand a deferred tool group to make its tools available. "
+ "Call with a group_id from the 'Deferred tool groups' catalog. "
+ "Optionally pass tool_names to expand specific tools only."
+ ),
+ parameters=ExpandToolsInput,
+ execute=_execute,
+ )
diff --git a/tests/deferred/test_expand_tool.py b/tests/deferred/test_expand_tool.py
new file mode 100644
index 0000000..639b87a
--- /dev/null
+++ b/tests/deferred/test_expand_tool.py
@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import pytest
+
+from cubepi.deferred._expand_tool import (
+ ExpandToolsInput,
+ ExpandToolsOutput,
+ _make_expand_tools,
+)
+from cubepi.agent.types import AgentTool
+
+
+class TestExpandToolsInput:
+ def test_group_id_only(self) -> None:
+ inp = ExpandToolsInput(group_id="mcp:github")
+ assert inp.group_id == "mcp:github"
+ assert inp.tool_names is None
+
+ def test_group_id_with_tool_names(self) -> None:
+ inp = ExpandToolsInput(group_id="mcp:github", tool_names=["create_issue"])
+ assert inp.tool_names == ["create_issue"]
+
+
+class TestExpandToolsOutput:
+ def test_success_output(self) -> None:
+ out = ExpandToolsOutput(
+ group_id="mcp:github",
+ expanded=True,
+ tool_names=["create_issue"],
+ remaining=5,
+ )
+ assert out.expanded is True
+ assert out.error is None
+
+ def test_error_output(self) -> None:
+ out = ExpandToolsOutput(
+ group_id="bad:id",
+ expanded=False,
+ tool_names=[],
+ remaining=0,
+ error="Unknown group_id: bad:id",
+ )
+ assert out.expanded is False
+ assert out.error is not None
+
+
+class TestMakeExpandTools:
+ def test_returns_agent_tool(self) -> None:
+ tool = _make_expand_tools(expand_callback=_noop_callback)
+ assert isinstance(tool, AgentTool)
+ assert tool.name == "expand_tools"
+
+ def test_schema_has_group_id_and_tool_names(self) -> None:
+ tool = _make_expand_tools(expand_callback=_noop_callback)
+ defn = tool.to_definition()
+ props = defn.parameters.get("properties", {})
+ assert "group_id" in props
+ assert "tool_names" in props
+
+ async def test_execute_calls_callback(self) -> None:
+ calls: list[tuple[str, list[str] | None]] = []
+
+ async def _callback(group_id: str, tool_names: list[str] | None) -> ExpandToolsOutput:
+ calls.append((group_id, tool_names))
+ return ExpandToolsOutput(
+ group_id=group_id,
+ expanded=True,
+ tool_names=["t1"],
+ remaining=0,
+ )
+
+ tool = _make_expand_tools(expand_callback=_callback)
+ result = await tool.execute("call-1", ExpandToolsInput(group_id="mcp:github"))
+ assert len(calls) == 1
+ assert calls[0] == ("mcp:github", None)
+ assert result.is_error is None or result.is_error is False
+
+ async def test_execute_with_tool_names(self) -> None:
+ calls: list[tuple[str, list[str] | None]] = []
+
+ async def _callback(group_id: str, tool_names: list[str] | None) -> ExpandToolsOutput:
+ calls.append((group_id, tool_names))
+ return ExpandToolsOutput(
+ group_id=group_id,
+ expanded=True,
+ tool_names=tool_names or [],
+ remaining=0,
+ )
+
+ tool = _make_expand_tools(expand_callback=_callback)
+ result = await tool.execute(
+ "call-2",
+ ExpandToolsInput(group_id="mcp:github", tool_names=["create_issue"]),
+ )
+ assert calls[0] == ("mcp:github", ["create_issue"])
+
+ async def test_execute_error_sets_is_error(self) -> None:
+ async def _err_callback(group_id: str, tool_names: list[str] | None) -> ExpandToolsOutput:
+ return ExpandToolsOutput(
+ group_id=group_id,
+ expanded=False,
+ tool_names=[],
+ remaining=0,
+ error="Unknown group_id: bad",
+ )
+
+ tool = _make_expand_tools(expand_callback=_err_callback)
+ result = await tool.execute("call-3", ExpandToolsInput(group_id="bad"))
+ assert result.is_error is True
+
+
+async def _noop_callback(group_id: str, tool_names: list[str] | None) -> ExpandToolsOutput:
+ return ExpandToolsOutput(group_id=group_id, expanded=True, tool_names=[], remaining=0)