fix: add disposable, runtime factory protocol

Author: cristipufu

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-runtime"
-version = "0.0.6"
+version = "0.0.7"
 description = "Runtime abstractions and interfaces for building agents and automation scripts in the UiPath ecosystem"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

src/uipath/runtime/__init__.py

@@ -9,7 +9,11 @@
 )
 from uipath.runtime.context import UiPathRuntimeContext
 from uipath.runtime.events import UiPathRuntimeEvent
-from uipath.runtime.factory import UiPathRuntimeCreator, UiPathRuntimeScanner
+from uipath.runtime.factory import (
+    UiPathRuntimeCreatorProtocol,
+    UiPathRuntimeFactoryProtocol,
+    UiPathRuntimeScannerProtocol,
+)
 from uipath.runtime.result import (
     UiPathApiTrigger,
     UiPathBreakpointResult,
@@ -25,8 +29,9 @@
     "UiPathRuntimeContext",
     "UiPathRuntimeProtocol",
     "UiPathExecutionRuntime",
-    "UiPathRuntimeCreator",
-    "UiPathRuntimeScanner",
+    "UiPathRuntimeCreatorProtocol",
+    "UiPathRuntimeScannerProtocol",
+    "UiPathRuntimeFactoryProtocol",
     "UiPathRuntimeResult",
     "UiPathRuntimeStatus",
     "UiPathRuntimeEvent",

src/uipath/runtime/base.py

@@ -7,6 +7,7 @@
     AsyncGenerator,
     Literal,
     Optional,
+    Protocol,
 )
 
 from pydantic import BaseModel, Field
@@ -52,7 +53,7 @@ class UiPathStreamOptions(UiPathExecuteOptions):
     pass
 
 
-class UiPathExecutable(typing.Protocol):
+class UiPathExecutableProtocol(typing.Protocol):
     """UiPath execution interface."""
 
     async def execute(
@@ -64,7 +65,7 @@ async def execute(
         ...
 
 
-class UiPathStreamable(typing.Protocol):
+class UiPathStreamableProtocol(typing.Protocol):
     """UiPath streaming interface."""
 
     async def stream(
@@ -111,7 +112,7 @@ async def stream(
         yield
 
 
-class HasSchema(typing.Protocol):
+class UiPathSchemaProtocol(typing.Protocol):
     """Contains runtime input and output schema."""
 
     async def get_schema(self) -> UiPathRuntimeSchema:
@@ -122,13 +123,25 @@ async def get_schema(self) -> UiPathRuntimeSchema:
         ...
 
 
+class UiPathDisposableProtocol(typing.Protocol):
+    """UiPath disposable interface."""
+
+    async def dispose(self) -> None:
+        """Close and clean up resources."""
+        ...
+
+
 # Note: explicitly marking it as a protocol for mypy.
 # https://mypy.readthedocs.io/en/stable/protocols.html#defining-subprotocols-and-subclassing-protocols
 # Note that inheriting from an existing protocol does not automatically turn the subclass into a protocol
 # – it just creates a regular (non-protocol) class or ABC that implements the given protocol (or protocols).
 # The Protocol base class must always be explicitly present if you are defining a protocol.
 class UiPathRuntimeProtocol(
-    UiPathExecutable, UiPathStreamable, HasSchema, typing.Protocol
+    UiPathExecutableProtocol,
+    UiPathStreamableProtocol,
+    UiPathSchemaProtocol,
+    UiPathDisposableProtocol,
+    Protocol,
 ):
     """UiPath Runtime Protocol."""
 

src/uipath/runtime/debug/runtime.py

@@ -122,13 +122,13 @@ async def _stream_and_debug(
 
         return final_result
 
-    async def cleanup(self) -> None:
+    async def get_schema(self) -> UiPathRuntimeSchema:
+        """Passthrough schema for the delegate."""
+        return await self.delegate.get_schema()
+
+    async def dispose(self) -> None:
         """Cleanup runtime resources."""
         try:
             await self.debug_bridge.disconnect()
         except Exception as e:
             logger.warning(f"Error disconnecting debug bridge: {e}")
-
-    async def get_schema(self) -> UiPathRuntimeSchema:
-        """Passthrough schema for the delegate."""
-        return await self.delegate.get_schema()

src/uipath/runtime/factory.py

@@ -5,17 +5,27 @@
 from uipath.runtime.base import UiPathRuntimeProtocol
 
 
-class UiPathRuntimeScanner(Protocol):
+class UiPathRuntimeScannerProtocol(Protocol):
     """Protocol for discovering all UiPath runtime instances."""
 
     def discover_runtimes(self) -> list[UiPathRuntimeProtocol]:
         """Discover all runtime classes."""
         ...
 
+    def discover_entrypoints(self) -> list[str]:
+        """Discover all runtime entrypoints."""
+        ...
+
 
-class UiPathRuntimeCreator(Protocol):
+class UiPathRuntimeCreatorProtocol(Protocol):
     """Protocol for creating a UiPath runtime given an entrypoint."""
 
-    def new_runtime(self, entrypoint: str) -> UiPathRuntimeProtocol:
+    async def new_runtime(self, entrypoint: str) -> UiPathRuntimeProtocol:
         """Create a new runtime instance."""
         ...
+
+
+class UiPathRuntimeFactoryProtocol(
+    UiPathRuntimeCreatorProtocol, UiPathRuntimeScannerProtocol, Protocol
+):
+    """Protocol for discovering and creating UiPath runtime instances."""

tests/test_debugger.py

@@ -64,7 +64,7 @@ def __init__(
 
         self.execute_called: bool = False
 
-    async def cleanup(self) -> None:
+    async def dispose(self) -> None:
         pass
 
     async def execute(
@@ -271,8 +271,8 @@ async def test_debug_runtime_execute_reports_errors_and_marks_faulted():
 
 
 @pytest.mark.asyncio
-async def test_debug_runtime_cleanup_calls_disconnect():
-    """cleanup() should call debug bridge disconnect."""
+async def test_debug_runtime_dispose_calls_disconnect():
+    """dispose() should call debug bridge disconnect."""
 
     runtime_impl = StreamingMockRuntime(node_sequence=["node-1"])
     bridge = make_debug_bridge_mock()
@@ -282,14 +282,14 @@ async def test_debug_runtime_cleanup_calls_disconnect():
         debug_bridge=bridge,
     )
 
-    await debug_runtime.cleanup()
+    await debug_runtime.dispose()
 
     cast(AsyncMock, bridge.disconnect).assert_awaited_once()
 
 
 @pytest.mark.asyncio
-async def test_debug_runtime_cleanup_suppresses_disconnect_errors():
-    """Errors from debug_bridge.disconnect should be suppressed, inner cleanup still runs."""
+async def test_debug_runtime_dispose_suppresses_disconnect_errors():
+    """Errors from debug_bridge.disconnect should be suppressed."""
 
     runtime_impl = StreamingMockRuntime(node_sequence=["node-1"])
     bridge = make_debug_bridge_mock()
@@ -300,7 +300,7 @@ async def test_debug_runtime_cleanup_suppresses_disconnect_errors():
         debug_bridge=bridge,
     )
 
-    # No exception should bubble up from cleanup()
-    await debug_runtime.cleanup()
+    # No exception should bubble up from dispose()
+    await debug_runtime.dispose()
 
     cast(AsyncMock, bridge.disconnect).assert_awaited_once()

tests/test_executor.py

@@ -33,6 +33,10 @@ async def stream(
         raise NotImplementedError()
         yield
 
+    async def dispose(self) -> None:
+        """Dispose resources if any."""
+        pass
+
 
 class MockRuntimeA(BaseMockRuntime):
     """Mock runtime A for testing."""
@@ -109,7 +113,7 @@ class UiPathTestRuntimeFactory:
     def __init__(self, runtime_class: type[UiPathRuntimeProtocol]):
         self.runtime_class = runtime_class
 
-    def new_runtime(self, entrypoint: str) -> UiPathRuntimeProtocol:
+    async def new_runtime(self, entrypoint: str) -> UiPathRuntimeProtocol:
         return self.runtime_class()
 
 
@@ -124,21 +128,21 @@ async def test_multiple_factories_same_executor():
     factory_c = UiPathTestRuntimeFactory(MockRuntimeC)
 
     # Execute runtime A
-    runtime_a = factory_a.new_runtime(entrypoint="")
+    runtime_a = await factory_a.new_runtime(entrypoint="")
     execution_runtime_a = UiPathExecutionRuntime(
         runtime_a, trace_manager, "runtime-a-span", execution_id="exec-a"
     )
     result_a = await execution_runtime_a.execute({"input": "a"})
 
     # Execute runtime B
-    runtime_b = factory_b.new_runtime(entrypoint="")
+    runtime_b = await factory_b.new_runtime(entrypoint="")
     execution_runtime_b = UiPathExecutionRuntime(
         runtime_b, trace_manager, "runtime-b-span", execution_id="exec-b"
     )
     result_b = await execution_runtime_b.execute({"input": "b"})
 
     # Execute runtime C with custom spans
-    runtime_c = factory_c.new_runtime(entrypoint="")
+    runtime_c = await factory_c.new_runtime(entrypoint="")
     execution_runtime_c = UiPathExecutionRuntime(
         runtime_c, trace_manager, "runtime-c-span", execution_id="exec-c"
     )