Skip to content

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

feat(deferred): static dispatch catalog + schema-bearing LoadToolsOutput

xf gong4073a1aad28b
diff --git a/cubepi/deferred/_catalog.py b/cubepi/deferred/_catalog.py
index 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.py
index 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: int
error: 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 = None
LoadCallback = Callable[
diff --git a/cubepi/deferred/types.py b/cubepi/deferred/types.py
index 289c88f..8308d50 100644
--- a/cubepi/deferred/types.py
+++ b/cubepi/deferred/types.py
@@ -2,9 +2,17 @@ from __future__ import annotations
from collections.abc import Awaitable, Callable
from dataclasses import dataclass
+from typing import Literal
from 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"]
+
@dataclass
class DeferredToolGroup:
diff --git a/tests/deferred/test_catalog.py b/tests/deferred/test_catalog.py
index 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.py
index 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"