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): static dispatch catalog + schema-bearing LoadToolsOutput
xf gong4073a1aad28b
diff --git a/cubepi/deferred/_catalog.py b/cubepi/deferred/_catalog.pyindex ffb8590..3f2da35 100644--- a/cubepi/deferred/_catalog.py+++ b/cubepi/deferred/_catalog.py@@ -13,9 +13,39 @@ DEFAULT_CATALOG_HEADER = ()+DEFAULT_DISPATCH_CATALOG_HEADER = (+ "# Deferred tool groups\n"+ "\n"+ "These tool groups are available but not yet loaded. Call `load_tools(group_id)`\n"+ "to get their full schemas, then invoke them via\n"+ "`deferred_tool_call(tool_name=..., arguments=...)`.\n"+ "If you already know the right arguments from the names below, you may call\n"+ "`deferred_tool_call` directly — the tool loads on demand."+)++ToolSchema = dict[str, object]+def render_static_catalog(+ *,+ groups: list[DeferredToolGroup],+ header: str = DEFAULT_DISPATCH_CATALOG_HEADER,+) -> str:+ """Dispatch-mode catalog: byte-stable, independent of expansion state."""+ lines: list[str] = []+ for group in sorted(groups, key=lambda g: g.group_id):+ count = len(group.tool_names)+ lines.append(+ f"- `{group.group_id}` — {group.display_name}: "+ f"{group.description} ({count} tools)"+ )+ lines.append(f" {', '.join(group.tool_names)}")+ if not lines:+ return ""+ return header + "\n\n" + "\n".join(lines)++def render_catalog(*,groups: list[DeferredToolGroup],diff --git a/cubepi/deferred/_expand_tool.py b/cubepi/deferred/_expand_tool.pyindex a473a6c..78751d8 100644--- a/cubepi/deferred/_expand_tool.py+++ b/cubepi/deferred/_expand_tool.py@@ -29,6 +29,11 @@ class LoadToolsOutput(BaseModel):tool_names: list[str]remaining: interror: str | None = None+ # Dispatch mode only: full schemas, delivered in the tool result so they+ # live in message history (append-only, cache-safe). The calling+ # convention lives once in the static catalog header and the dispatcher+ # description — not repeated per result.+ schemas: list[dict[str, object]] | None = NoneLoadCallback = Callable[diff --git a/cubepi/deferred/types.py b/cubepi/deferred/types.pyindex 289c88f..8308d50 100644--- a/cubepi/deferred/types.py+++ b/cubepi/deferred/types.py@@ -2,9 +2,17 @@ from __future__ import annotationsfrom collections.abc import Awaitable, Callablefrom dataclasses import dataclass+from typing import Literalfrom cubepi.agent.types import AgentTool+# "dispatch" (default): static tools array + system prompt; schemas delivered+# via load_tools results; calls routed through the deferred_tool_call+# dispatcher. Zero prompt-cache invalidation.+# "inject": v1 behavior — loaded tools join the model-visible tools array+# (native tool calling, one full cache re-read per expansion).+DeferredStrategy = Literal["dispatch", "inject"]+@dataclassclass DeferredToolGroup:diff --git a/tests/deferred/test_catalog.py b/tests/deferred/test_catalog.pyindex da1d53a..b3af45f 100644--- a/tests/deferred/test_catalog.py+++ b/tests/deferred/test_catalog.py@@ -1,6 +1,10 @@from __future__ import annotations-from cubepi.deferred._catalog import render_catalog, render_expanded_schemas+from cubepi.deferred._catalog import (+ render_catalog,+ render_expanded_schemas,+ render_static_catalog,+)from cubepi.deferred.types import DeferredToolGroup@@ -161,3 +165,34 @@ class TestRenderExpandedSchemas:result_v1 = render_expanded_schemas(expanded_schemas=schemas_v1)result_v2 = render_expanded_schemas(expanded_schemas=schemas_v2)assert result_v2.startswith(result_v1)+++class TestStaticCatalog:+ def test_lists_all_tools_sorted_by_group_id(self) -> None:+ out = render_static_catalog(+ groups=[+ _make_group("b", "B", "b tools", ["t2"]),+ _make_group("a", "A", "a tools", ["t1"]),+ ],+ header="HDR",+ )+ assert out.index("`a`") < out.index("`b`")+ assert "t1" in out and "t2" in out++ def test_no_remaining_counts(self) -> None:+ out = render_static_catalog(+ groups=[_make_group("a", "A", "a tools", ["t1", "t2"])], header="HDR"+ )+ assert "remaining" not in out++ def test_deterministic(self) -> None:+ groups = [+ _make_group("a", "A", "a tools", ["t1"]),+ _make_group("b", "B", "b tools", ["t2"]),+ ]+ assert render_static_catalog(groups=groups, header="HDR") == (+ render_static_catalog(groups=list(reversed(groups)), header="HDR")+ )++ def test_no_groups_returns_empty(self) -> None:+ assert render_static_catalog(groups=[], header="HDR") == ""diff --git a/tests/deferred/test_expand_tool.py b/tests/deferred/test_expand_tool.pyindex 8924066..28a540b 100644--- a/tests/deferred/test_expand_tool.py+++ b/tests/deferred/test_expand_tool.py@@ -118,3 +118,15 @@ async def _noop_callback(group_id: str, tool_names: list[str] | None) -> LoadToolsOutput:return LoadToolsOutput(group_id=group_id, expanded=True, tool_names=[], remaining=0)+++def test_load_tools_output_carries_schemas() -> None:+ out = LoadToolsOutput(+ group_id="g",+ expanded=True,+ tool_names=["t"],+ remaining=0,+ schemas=[{"name": "t", "description": "d", "parameters": {}}],+ )+ dumped = out.model_dump()+ assert dumped["schemas"][0]["name"] == "t"