digitalkin 1.0.2.dev0__tar.gz → 1.0.2.dev2__tar.gz

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 1.0.2.dev0
+Version: 1.0.2.dev2
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International
@@ -453,7 +453,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ag-ui-protocol>=0.1.18
-Requires-Dist: agentic-mesh-protocol==1.0.1.dev2
+Requires-Dist: agentic-mesh-protocol==1.0.1.dev4
 Requires-Dist: anyio>=4.13.0
 Requires-Dist: grpcio-health-checking==1.82.1
 Requires-Dist: grpcio-reflection==1.82.1

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev2}/pyproject.toml

@@ -28,7 +28,7 @@
 
     dependencies = [
         "ag-ui-protocol>=0.1.18",
-        "agentic-mesh-protocol==1.0.1.dev2",
+        "agentic-mesh-protocol==1.0.1.dev4",
         "anyio>=4.13.0",
         "grpcio-health-checking==1.82.1",
         "grpcio-reflection==1.82.1",
@@ -37,7 +37,7 @@
         "pydantic>=2.12.4",
         "redis[hiredis]>=7.4.0,<9",
     ]
-    version = "1.0.2.dev0"
+    version = "1.0.2.dev2"
 
     [project.optional-dependencies]
         agno = [ "agno>=2.6" ]

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev2}/src/digitalkin/__version__.py

@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("digitalkin")
 except PackageNotFoundError:
-    __version__ = "1.0.2.dev0"
+    __version__ = "1.0.2.dev2"

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev2}/src/digitalkin/community/agno/hitl.py

@@ -23,6 +23,7 @@ if TYPE_CHECKING:
     from agno.agent import Agent
     from agno.run.agent import RunOutput
 
+    from digitalkin.community.agno.toolkits.tool_loader import ToolLoaderTools
     from digitalkin.models.events import BaseAgentRunEvent
     from digitalkin.models.module import ModuleContext
     from digitalkin.services.storage import StorageStrategy
@@ -78,8 +79,10 @@ class PausedRunStore:
         seen: set[str] = set()
         pending: list[str] = []
         for tool in run_output.tools or []:
-            tid = getattr(tool, "tool_call_id", None)
-            if tid and tid not in seen and getattr(tool, "external_execution_required", False):
+            tid = tool.tool_call_id
+            # Skip tools already resolved in-process (e.g. a use_setup call handled by the
+            # runner): only genuinely unresolved external tools go to the front.
+            if tid and tid not in seen and tool.external_execution_required and tool.result is None:
                 seen.add(tid)
                 pending.append(tid)
         record = PausedRunRecord(
@@ -303,6 +306,7 @@ class AgnoHitlRunner:
         storage: StorageStrategy | None = None,
         store: PausedRunStore | None = None,
         dependency_key: str = "agui_tools",
+        tool_loader: ToolLoaderTools | None = None,
     ) -> None:
         """Initialize the runner.
 
@@ -314,6 +318,12 @@ class AgnoHitlRunner:
             store: Pre-built paused-run store; wins over ``storage``.
             dependency_key: Agno dependencies key carrying the AG-UI tool
                 list (must match :func:`make_tools_factory`).
+            tool_loader: The :class:`ToolLoaderTools` bound to the agent's tool list
+                (``ToolLoaderTools.find(tools)``). When present, a ``use_setup`` pause is
+                resolved and the run auto-continues instead of surfacing to the front.
+                When omitted, the runner locates it in ``agent.tools`` itself — otherwise
+                a ``use_setup`` pause would surface to the front as a frontend tool no
+                client implements, wedging the thread.
 
         Raises:
             ValueError: If neither ``storage`` nor ``store`` is provided.
@@ -323,9 +333,18 @@ class AgnoHitlRunner:
                 msg = "AgnoHitlRunner requires either `storage` or `store`."
                 raise ValueError(msg)
             store = PausedRunStore(storage)
+        if tool_loader is None:
+            # Lazy import: ToolLoaderTools requires the optional agno dependency at
+            # import time, while this module must stay importable without it (same
+            # convention as the rest of community.agno). vars(): test fakes may not
+            # carry a tools attribute at all.
+            from digitalkin.community.agno.toolkits.tool_loader import ToolLoaderTools
+
+            tool_loader = ToolLoaderTools.find(vars(agent).get("tools"))
         self._agent = agent
         self._store = store
         self._dependency_key = dependency_key
+        self._tool_loader = tool_loader
 
     async def run(
         self,
@@ -360,7 +379,9 @@ class AgnoHitlRunner:
             yield_run_output=True,
             dependencies={self._dependency_key: agui_tools or []},
         )
-        return await self._drive(stream=stream, send=send, thread_id=thread_id, run_output_cls=RunOutput)
+        return await self._drive(
+            stream=stream, send=send, thread_id=thread_id, run_output_cls=RunOutput, agui_tools=agui_tools
+        )
 
     async def continue_paused_run(
         self,
@@ -437,7 +458,9 @@ class AgnoHitlRunner:
             yield_run_output=True,
             dependencies={self._dependency_key: agui_tools or []},
         )
-        pause_info = await self._drive(stream=stream, send=send, thread_id=thread_id, run_output_cls=RunOutput)
+        pause_info = await self._drive(
+            stream=stream, send=send, thread_id=thread_id, run_output_cls=RunOutput, agui_tools=agui_tools
+        )
 
         if pause_info is None:
             await self._store.delete(thread_id)
@@ -612,31 +635,108 @@ class AgnoHitlRunner:
         send: Callable[[BaseAgentRunEvent], Coroutine[Any, Any, None]],
         thread_id: str,
         run_output_cls: type[RunOutput],
+        agui_tools: list[AgUiTool] | None = None,
     ) -> PauseInfo | None:
-        """Drain an Agno stream, forward events, persist on pause.
+        """Drain an Agno stream, forward events, and persist or auto-continue on pause.
+
+        A ``use_setup`` pause (dynamic tool load) is resolved in-process and the run
+        auto-continues with the enlarged tool list; a frontend-tool pause is persisted and
+        surfaced. The loop is bounded so a model that keeps calling ``use_setup`` cannot spin
+        forever.
+
+        Args:
+            stream: The Agno event stream to drain.
+            send: Digitalkin-event callback for each forwarded event.
+            thread_id: AG-UI thread identifier (storage key on a frontend pause).
+            run_output_cls: The ``RunOutput`` class used to spot the terminal run object.
+            agui_tools: Frontend tools to re-pass to Agno on an auto-continue.
 
         Returns:
-            :class:`PauseInfo` on pause, ``None`` otherwise.
+            :class:`PauseInfo` on a frontend pause, ``None`` on completion.
         """
         from digitalkin.community.agno.agno_adapter import AgnoStreamAdapter
 
-        adapter = AgnoStreamAdapter()
-        final_run_output: RunOutput | None = None
+        for _ in range(20):
+            adapter = AgnoStreamAdapter()
+            final_run_output: RunOutput | None = None
 
-        async for raw_event in stream:
-            if isinstance(raw_event, run_output_cls):
-                final_run_output = raw_event
-                continue
-            for event in adapter.to_digitalkin_events(raw_event):
+            async for raw_event in stream:
+                if isinstance(raw_event, run_output_cls):
+                    final_run_output = raw_event
+                    continue
+                for event in adapter.to_digitalkin_events(raw_event):
+                    await send(event)
+
+            for event in adapter.flush():
                 await send(event)
 
-        for event in adapter.flush():
-            await send(event)
+            if not (adapter.is_paused and final_run_output is not None and final_run_output.is_paused):
+                return None
+
+            # Resolve any use_setup calls in-process; if the pause has nothing left for the
+            # front, auto-continue so discover -> load -> use reads as a single turn.
+            if await self._load_paused_tools(final_run_output) and not self._pending_external(final_run_output):
+                stream = self._agent.acontinue_run(
+                    run_response=final_run_output,
+                    stream=True,
+                    stream_events=True,
+                    yield_run_output=True,
+                    dependencies={self._dependency_key: agui_tools or []},
+                )
+                continue
 
-        if adapter.is_paused and final_run_output is not None and getattr(final_run_output, "is_paused", False):
             pause_info = await self._store.save(run_output=final_run_output, thread_id=thread_id)
             # Attach AG-UI-shaped messages so the front can materialise the tool_call.
             pause_info.new_messages = HitlEvents.agno_messages_to_agui(final_run_output.messages or [])
             return pause_info
 
+        logger.warning("AgnoHitlRunner: auto-continue limit reached for thread_id=%s", thread_id)
+        from digitalkin.models.events import AgentRunEvent, RunErrorEvent
+
+        await send(
+            RunErrorEvent(
+                event=AgentRunEvent.RUN_ERROR,
+                error_type="auto_continue_limit",
+                content=(
+                    "The run was stopped after too many consecutive in-process tool "
+                    "loads (use_setup). Send a new message to continue."
+                ),
+                error_details=None,
+                timestamp=None,
+                metadata=None,
+            )
+        )
         return None
+
+    async def _load_paused_tools(self, run_output: RunOutput) -> bool:
+        """Resolve ``use_setup`` calls in a paused run, writing each tool result in place.
+
+        Args:
+            run_output: The paused Agno run.
+
+        Returns:
+            ``True`` if at least one ``use_setup`` call was handled, else ``False`` (no
+            loader wired, or the pause carries only frontend tools).
+        """
+        if self._tool_loader is None:
+            return False
+        handled = False
+        loader_tool = self._tool_loader.tool_name
+        for tool in run_output.tools or []:
+            if tool.external_execution_required and tool.result is None and tool.tool_name == loader_tool:
+                setup_id = (tool.tool_args or {}).get("setup_id", "")
+                tool.result = await self._tool_loader.load(setup_id)
+                handled = True
+        return handled
+
+    @staticmethod
+    def _pending_external(run_output: RunOutput) -> bool:
+        """Report whether any external tool in the paused run still needs a result.
+
+        Args:
+            run_output: The paused Agno run (after :meth:`_load_paused_tools`).
+
+        Returns:
+            ``True`` if a frontend tool call remains unresolved (must go to the front).
+        """
+        return any(tool.external_execution_required and tool.result is None for tool in run_output.tools or [])

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev2}/src/digitalkin/community/agno/toolkits/__init__.py

@@ -9,6 +9,8 @@ from digitalkin.community.agno.toolkits.base import DkToolkit
 from digitalkin.community.agno.toolkits.chat_history import ChatHistoryTools
 from digitalkin.community.agno.toolkits.defaults import DefaultToolkits
 from digitalkin.community.agno.toolkits.registry import RegistryTools
+from digitalkin.community.agno.toolkits.setup import SetupTools
+from digitalkin.community.agno.toolkits.tool_loader import ToolLoaderTools
 from digitalkin.community.agno.toolkits.user_profile import UserProfileTools
 
 __all__ = [
@@ -16,5 +18,7 @@ __all__ = [
     "DefaultToolkits",
     "DkToolkit",
     "RegistryTools",
+    "SetupTools",
+    "ToolLoaderTools",
     "UserProfileTools",
 ]

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev2}/src/digitalkin/community/agno/toolkits/base.py

@@ -32,16 +32,28 @@ class DkToolkit(Toolkit):
     which pushes AG-UI custom events onto the caller's gRPC stream.
     """
 
-    def __init__(self, name: str, tools: list[Any], context: ModuleContext | None = None) -> None:
+    def __init__(
+        self,
+        name: str,
+        tools: list[Any],
+        context: ModuleContext | None = None,
+        external_execution_required_tools: list[str] | None = None,
+    ) -> None:
         """Initialize the toolkit.
 
         Args:
             name: Toolkit name registered with Agno.
             tools: Bound tool callables to expose to the agent.
             context: Module context; when present, :meth:`_notify` can emit AG-UI events.
+            external_execution_required_tools: Tool names Agno must pause on (executed
+                outside the agent loop) instead of running their entrypoint.
         """
         self._ctx = context
-        super().__init__(name=name, tools=tools)
+        super().__init__(
+            name=name,
+            tools=tools,
+            external_execution_required_tools=external_execution_required_tools or [],
+        )
 
     @staticmethod
     def _ok(output: Any, **metadata: Any) -> str:

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev2}/src/digitalkin/community/agno/toolkits/defaults.py

@@ -6,6 +6,8 @@ from typing import TYPE_CHECKING, Any
 
 from digitalkin.community.agno.toolkits.chat_history import ChatHistoryTools
 from digitalkin.community.agno.toolkits.registry import RegistryTools
+from digitalkin.community.agno.toolkits.setup import SetupTools
+from digitalkin.community.agno.toolkits.tool_loader import ToolLoaderTools
 from digitalkin.community.agno.toolkits.user_profile import UserProfileTools
 
 if TYPE_CHECKING:
@@ -33,18 +35,28 @@ class DefaultToolkits:
     def build(context: ModuleContext, session_id: str | None = None) -> list[Toolkit]:
         """Build the default toolkits from a module context.
 
+        Includes SetupTools only when ``context.setup`` is wired (the servicer's shared
+        setup service). ToolLoaderTools is always added and bound to the returned list so
+        dynamically-loaded tools land in the exact list the agent's factory splats.
+
         Args:
-            context: The module context carrying the user_profile and registry services.
+            context: The module context carrying the services and (optional) setup service.
             session_id: The Agno session whose chat history should be readable.
 
         Returns:
-            [ChatHistoryTools, UserProfileTools, RegistryTools].
+            [ChatHistoryTools, UserProfileTools, RegistryTools, (SetupTools?), ToolLoaderTools].
         """
-        return [
+        tools: list[Toolkit] = [
             ChatHistoryTools(session_id=session_id, context=context),
             UserProfileTools(context.user_profile, context=context),
             RegistryTools(context.registry, context=context),
         ]
+        if context.setup is not None:
+            tools.append(SetupTools(context.setup, context=context))
+        loader = ToolLoaderTools(context=context)
+        tools.append(loader)
+        loader.bind_tools(tools)
+        return tools
 
     @staticmethod
     def bind_host(tools: list[Any] | Callable[..., list[Any]] | None, host: Any) -> None:

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev2}/src/digitalkin/community/agno/toolkits/registry.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, ClassVar, Literal
 
 from digitalkin.community.agno.toolkits.base import DkToolkit
+from digitalkin.grpc_servers.exceptions import PermissionDeniedError
 from digitalkin.logger import logger
 from digitalkin.models.services.registry import RegistryModuleType, RegistrySetupStatus
 from digitalkin.services.registry.exceptions import RegistryServiceError
@@ -36,7 +37,7 @@ class RegistryTools(DkToolkit):
         self._registry = registry
         super().__init__(
             name="registry_tools",
-            tools=[self.search_setups, self.search_modules],
+            tools=[self.search_setups, self.search_modules, self.get_service_setup],
             context=context,
         )
 
@@ -48,10 +49,10 @@ class RegistryTools(DkToolkit):
             kind: The requested kind filter.
 
         Returns:
-            Error message when ``kind`` is neither 'tool' nor 'kin', else None.
+            Error message when ``kind`` is not 'tool', 'kin' or 'service', else None.
         """
-        if kind is not None and kind not in {"tool", "kin"}:
-            return f"invalid kind '{kind}'; use 'tool' or 'kin'"
+        if kind is not None and kind not in {"tool", "kin", "service"}:
+            return f"invalid kind '{kind}'; use 'tool', 'kin' or 'service'"
         return None
 
     def _clamp(self, limit: int) -> int:
@@ -66,16 +67,16 @@ class RegistryTools(DkToolkit):
         return min(max(limit, 1), self._MAX_RESULTS)
 
     async def search_setups(
-        self, query: str | None = None, kind: Literal["tool", "kin"] | None = None, limit: int = 10
+        self, query: str | None = None, kind: Literal["tool", "kin", "service"] | None = None, limit: int = 10
     ) -> str:
-        """Search ready-to-use setups (configured agent/tool instances you can actually invoke).
+        """Search ready-to-use setups (configured agent/tool/service instances you can actually invoke).
 
         A setup is an installed, configured instance of a module — the thing you can
-        call. Use this to discover which tools or agents (kins) are available.
+        call. Use this to discover which tools, agents (kins) or services are available.
 
         Args:
             query: Free text matched against setup name and documentation. Omit to list all.
-            kind: Optional filter: "tool" (invocable tools) or "kin" (agents).
+            kind: Optional filter: "tool" (invocable tools), "kin" (agents) or "service".
             limit: Max results (default 10, max 25).
 
         Returns:
@@ -89,12 +90,24 @@ class RegistryTools(DkToolkit):
         try:
             setups = await self._registry.search_setups(
                 query=query,
-                module_types=[RegistryModuleType.ARCHETYPE if kind == "kin" else RegistryModuleType.TOOL_MODULE]
+                module_types=[
+                    {
+                        "tool": RegistryModuleType.TOOL_MODULE,
+                        "kin": RegistryModuleType.ARCHETYPE,
+                        "service": RegistryModuleType.SERVICE,
+                    }[kind]
+                ]
                 if kind
                 else None,
                 statuses=[RegistrySetupStatus.READY, RegistrySetupStatus.CONFIGURATION_SUCCEEDED],
                 limit=cap,
             )
+        except PermissionDeniedError:
+            return self._fail("permission denied: search_setups", tool="search_setups")
+        except ValueError as error:
+            # Enum encoding drift (fail-closed): permanent, retrying will not help.
+            logger.error("RegistryTools: setup search filter rejected: %s", error)
+            return self._fail("search filter not supported by this registry version", tool="search_setups")
         except RegistryServiceError as error:
             logger.warning("RegistryTools: setup search failed: %s", error)
             return self._fail(self._UNAVAILABLE, tool="search_setups")
@@ -115,8 +128,33 @@ class RegistryTools(DkToolkit):
             tool="search_setups",
         )
 
+    async def get_service_setup(self, setup_id: str) -> str:
+        """Fetch a service's configuration content (a JSON document) by setup id.
+
+        Use after discovering a service via ``search_setups`` and the user accepted it:
+        pass the proposed setup's ``setup_id`` to read the service content. Always
+        returns the latest version.
+
+        Args:
+            setup_id: The service setup id (from a ``search_setups`` result).
+
+        Returns:
+            The canonical envelope; ``output`` = the service configuration JSON object.
+        """
+        try:
+            content = await self._registry.get_service_setup(setup_id)
+        except PermissionDeniedError:
+            return self._fail("permission denied: get_service_setup", tool="get_service_setup")
+        except RegistryServiceError as error:
+            logger.warning("RegistryTools: service setup fetch failed: %s", error)
+            return self._fail(self._UNAVAILABLE, tool="get_service_setup")
+
+        if content is None:
+            return self._fail(f"service setup '{setup_id}' not found or has no content", tool="get_service_setup")
+        return self._ok(content, tool="get_service_setup")
+
     async def search_modules(
-        self, query: str | None = None, kind: Literal["tool", "kin"] | None = None, limit: int = 10
+        self, query: str | None = None, kind: Literal["tool", "kin", "service"] | None = None, limit: int = 10
     ) -> str:
         """Search the module catalog (module TYPES, not configured instances).
 
@@ -126,7 +164,7 @@ class RegistryTools(DkToolkit):
 
         Args:
             query: Free text matched against module names. Omit to list all.
-            kind: Optional filter: "tool" or "kin" (agents/archetypes).
+            kind: Optional filter: "tool", "kin" (agents/archetypes) or "service".
             limit: Max results (default 10, max 25).
 
         Returns:
@@ -141,10 +179,18 @@ class RegistryTools(DkToolkit):
             pending = self._registry.search_tools(name=query, limit=cap)
         elif kind == "kin":
             pending = self._registry.search_kins(name=query, limit=cap)
+        elif kind == "service":
+            pending = self._registry.search_services(name=query, limit=cap)
         else:
             pending = self._registry.search(name=query, limit=cap)
         try:
             modules = await pending
+        except PermissionDeniedError:
+            return self._fail("permission denied: search_modules", tool="search_modules")
+        except ValueError as error:
+            # Enum encoding drift (fail-closed): permanent, retrying will not help.
+            logger.error("RegistryTools: module search filter rejected: %s", error)
+            return self._fail("search filter not supported by this registry version", tool="search_modules")
         except RegistryServiceError as error:
             logger.warning("RegistryTools: module search failed: %s", error)
             return self._fail(self._UNAVAILABLE, tool="search_modules")