digitalkin 1.0.2.dev0__tar.gz → 1.0.2.dev1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 1.0.2.dev0
+Version: 1.0.2.dev1
 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.dev3
 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.dev1}/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.dev3",
         "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.dev1"
 
     [project.optional-dependencies]
         agno = [ "agno>=2.6" ]

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev1}/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.dev1"

{digitalkin-1.0.2.dev0 → digitalkin-1.0.2.dev1}/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.dev1}/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.dev1}/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.dev1}/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.dev1}/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
@@ -95,6 +96,12 @@ class RegistryTools(DkToolkit):
                 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")
@@ -145,6 +152,12 @@ class RegistryTools(DkToolkit):
             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")

digitalkin-1.0.2.dev1/src/digitalkin/community/agno/toolkits/setup.py

@@ -0,0 +1,204 @@
+"""Toolkit exposing the DigitalKin setup service to the agent (setup CRUD).
+
+Wraps the same ``SetupStrategy`` instance the module servicer already uses for the
+base StartStream/Stream flow (shared gRPC channel, borrowed on ``context.setup``),
+so the agent can create/read/update/delete setups and change their visibility.
+Owner/organisation/module of a created setup are resolved server-side from the
+request context; version lifecycle is platform-owned (content flows through the
+setup's ``current_setup_version``). Every tool returns the canonical envelope and
+never raises into the agent loop; permission denials are surfaced distinctly.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from google.protobuf.message import Message as ProtoMessage
+from pydantic import BaseModel
+
+from digitalkin.community.agno.toolkits.base import DkToolkit
+from digitalkin.grpc_servers.exceptions import PermissionDeniedError, ServerError
+from digitalkin.logger import logger
+from digitalkin.services.setup.exceptions import SetupServiceError
+from digitalkin.utils.proto_utils import ProtoUtils
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable
+
+    from digitalkin.models.module import ModuleContext
+    from digitalkin.services.setup.setup_strategy import SetupStrategy
+
+
+class SetupTools(DkToolkit):
+    """CRUD + visibility access to the DigitalKin setup service over the module's shared channel.
+
+    A setup is a configured instance of a module; its content lives in the embedded
+    ``current_setup_version``. The tools build the flat dicts the ``SetupStrategy``
+    expects and return a JSON envelope; results are normalised to plain JSON
+    regardless of whether the backend returns a Pydantic model, a proto, or a scalar.
+    """
+
+    def __init__(self, setup: SetupStrategy, context: ModuleContext | None = None) -> None:
+        """Initialize the toolkit with the module's setup service.
+
+        Args:
+            setup: The setup service strategy (shared with the servicer's base flow).
+            context: Module context; enables AG-UI notifications via the base toolkit.
+        """
+        self._setup = setup
+        super().__init__(
+            name="setup_tools",
+            tools=[
+                self.get_setup,
+                self.create_setup,
+                self.update_setup,
+                self.delete_setup,
+                self.change_visibility,
+            ],
+            context=context,
+        )
+
+    async def _guard(self, op: str, coro: Awaitable[Any]) -> tuple[bool, Any]:
+        """Await a setup-service call, converting failures into a fail envelope.
+
+        Args:
+            op: Tool name, used in the error message and metadata.
+            coro: The setup-service coroutine to await.
+
+        Returns:
+            ``(True, result)`` on success; ``(False, fail_envelope)`` on any
+            error — never raises into the agent loop.
+        """
+        try:
+            return True, await coro
+        except PermissionDeniedError:
+            return False, self._fail(f"permission denied: {op}", tool=op)
+        except (SetupServiceError, ServerError, ValueError) as error:
+            logger.warning("SetupTools: %s failed: %s", op, error)
+            return False, self._fail(str(error), tool=op)
+        except Exception as error:
+            # Backend contract surprises (KeyError, TypeError, ...) must not
+            # raise into the agent loop either.
+            logger.exception("SetupTools: %s failed unexpectedly", op)
+            return False, self._fail(f"{op} failed: {type(error).__name__}: {error}", tool=op)
+
+    async def _invalidate(self) -> None:
+        """Invalidate the servicer's setup cache after a successful write (best-effort).
+
+        No-op when the callback is not installed (e.g. outside the M4 flow).
+        """
+        if self._ctx is None:
+            return
+        invalidate = vars(self._ctx.callbacks).get("invalidate_setup")
+        if invalidate is None:
+            return
+        try:
+            invalidate()
+        except Exception:
+            logger.exception("SetupTools: setup-cache invalidation failed")
+
+    @staticmethod
+    def _jsonable(value: Any) -> Any:
+        """Normalise a backend return value to a JSON-serializable form.
+
+        Args:
+            value: A Pydantic model, proto message, or plain scalar/collection.
+
+        Returns:
+            A dict for models/protos, otherwise the value unchanged.
+        """
+        if isinstance(value, BaseModel):
+            return value.model_dump(mode="json")
+        if isinstance(value, ProtoMessage):
+            return ProtoUtils.proto_to_dict(value)
+        return value
+
+    async def get_setup(self, setup_id: str, version: str = "") -> str:
+        """Fetch a setup by id (optionally a specific version).
+
+        Args:
+            setup_id: The setup id to read.
+            version: Optional version to pin; omit for the current version.
+
+        Returns:
+            The canonical envelope; ``output`` = the setup with its current version,
+            status and visibility.
+        """
+        ok, result = await self._guard("get_setup", self._setup.get_setup({"setup_id": setup_id, "version": version}))
+        return result if not ok else self._ok(self._jsonable(result), tool="get_setup")
+
+    async def create_setup(self, name: str, content: dict[str, Any]) -> str:
+        """Create a new setup with an initial version.
+
+        The owner, organisation and target module are derived server-side from
+        this request's context — only a name and the configuration content are
+        needed. New setups start private; use ``change_visibility`` to share them.
+
+        Args:
+            name: Human-readable setup name.
+            content: The initial version's configuration payload.
+
+        Returns:
+            The canonical envelope; ``output`` = the created setup (id, status,
+            visibility, current version).
+        """
+        ok, result = await self._guard("create_setup", self._setup.create_setup({"name": name, "content": content}))
+        if not ok:
+            return result
+        await self._invalidate()
+        return self._ok(self._jsonable(result), tool="create_setup")
+
+    async def update_setup(self, setup_id: str, name: str, content: dict[str, Any]) -> str:
+        """Update an existing setup's name and current version content.
+
+        Args:
+            setup_id: The setup to update.
+            name: New setup name.
+            content: The current version's new configuration payload.
+
+        Returns:
+            The canonical envelope; ``output`` = the updated setup.
+        """
+        ok, result = await self._guard(
+            "update_setup",
+            self._setup.update_setup({"setup_id": setup_id, "name": name, "content": content}),
+        )
+        if not ok:
+            return result
+        await self._invalidate()
+        return self._ok(self._jsonable(result), tool="update_setup")
+
+    async def delete_setup(self, setup_id: str) -> str:
+        """Delete a setup by id.
+
+        Args:
+            setup_id: The setup to delete.
+
+        Returns:
+            The canonical envelope; ``output`` = the deletion result.
+        """
+        ok, result = await self._guard("delete_setup", self._setup.delete_setup({"setup_id": setup_id}))
+        if not ok:
+            return result
+        await self._invalidate()
+        return self._ok(self._jsonable(result), tool="delete_setup")
+
+    async def change_visibility(self, setup_id: str, visibility: Literal["public", "private", "internal"]) -> str:
+        """Change who can see and use a setup.
+
+        Args:
+            setup_id: The setup whose visibility to change.
+            visibility: "public" (everyone), "private" (owner only) or
+                "internal" (whole organisation).
+
+        Returns:
+            The canonical envelope; ``output`` = the setup with its updated visibility.
+        """
+        ok, result = await self._guard(
+            "change_visibility",
+            self._setup.change_visibility({"setup_id": setup_id, "visibility": visibility}),
+        )
+        if not ok:
+            return result
+        await self._invalidate()
+        return self._ok(self._jsonable(result), tool="change_visibility")