feat: add resumable runtime

Author: cristipufu

src/uipath/runtime/__init__.py

@@ -8,19 +8,33 @@
     UiPathStreamOptions,
 )
 from uipath.runtime.context import UiPathRuntimeContext
+from uipath.runtime.debug.breakpoint import UiPathBreakpointResult
+from uipath.runtime.debug.bridge import UiPathDebugBridgeProtocol
+from uipath.runtime.debug.exception import UiPathDebugQuitError
+from uipath.runtime.debug.runtime import (
+    UiPathDebugRuntime,
+)
 from uipath.runtime.events import UiPathRuntimeEvent
 from uipath.runtime.factory import (
     UiPathRuntimeCreatorProtocol,
     UiPathRuntimeFactoryProtocol,
     UiPathRuntimeScannerProtocol,
 )
 from uipath.runtime.result import (
+    UiPathRuntimeResult,
+    UiPathRuntimeStatus,
+)
+from uipath.runtime.resumable.protocols import (
+    UiPathResumableStorageProtocol,
+    UiPathResumeTriggerProtocol,
+)
+from uipath.runtime.resumable.runtime import (
+    UiPathResumableRuntime,
+)
+from uipath.runtime.resumable.trigger import (
     UiPathApiTrigger,
-    UiPathBreakpointResult,
     UiPathResumeTrigger,
     UiPathResumeTriggerType,
-    UiPathRuntimeResult,
-    UiPathRuntimeStatus,
 )
 
 __all__ = [
@@ -35,9 +49,15 @@
     "UiPathRuntimeResult",
     "UiPathRuntimeStatus",
     "UiPathRuntimeEvent",
-    "UiPathBreakpointResult",
+    "UiPathResumableStorageProtocol",
+    "UiPathResumeTriggerProtocol",
     "UiPathApiTrigger",
     "UiPathResumeTrigger",
     "UiPathResumeTriggerType",
+    "UiPathResumableRuntime",
+    "UiPathDebugQuitError",
+    "UiPathDebugBridgeProtocol",
+    "UiPathDebugRuntime",
+    "UiPathBreakpointResult",
     "UiPathStreamNotSupportedError",
 ]

src/uipath/runtime/debug/__init__.py

@@ -1,5 +1,6 @@
 """Initialization module for the debug package."""
 
+from uipath.runtime.debug.breakpoint import UiPathBreakpointResult
 from uipath.runtime.debug.bridge import UiPathDebugBridgeProtocol
 from uipath.runtime.debug.exception import (
     UiPathDebugQuitError,
@@ -10,4 +11,5 @@
     "UiPathDebugQuitError",
     "UiPathDebugBridgeProtocol",
     "UiPathDebugRuntime",
+    "UiPathBreakpointResult",
 ]

src/uipath/runtime/debug/breakpoint.py

@@ -0,0 +1,20 @@
+"""Module defining the result for execution suspended at a breakpoint."""
+
+from typing import Any, Literal
+
+from pydantic import Field
+
+from uipath.runtime.result import UiPathRuntimeResult, UiPathRuntimeStatus
+
+
+class UiPathBreakpointResult(UiPathRuntimeResult):
+    """Result for execution suspended at a breakpoint."""
+
+    # Force status to always be SUSPENDED
+    status: UiPathRuntimeStatus = Field(
+        default=UiPathRuntimeStatus.SUSPENDED, frozen=True
+    )
+    breakpoint_node: str  # Which node the breakpoint is at
+    breakpoint_type: Literal["before", "after"]  # Before or after the node
+    current_state: dict[str, Any] | Any  # Current workflow state at breakpoint
+    next_nodes: list[str]  # Which node(s) will execute next

src/uipath/runtime/debug/bridge.py

@@ -2,11 +2,11 @@
 
 from typing import Any, Literal, Protocol
 
-from uipath.runtime import (
-    UiPathBreakpointResult,
+from uipath.runtime.debug.breakpoint import UiPathBreakpointResult
+from uipath.runtime.events import UiPathRuntimeStateEvent
+from uipath.runtime.result import (
     UiPathRuntimeResult,
 )
-from uipath.runtime.events import UiPathRuntimeStateEvent
 
 
 class UiPathDebugBridgeProtocol(Protocol):

src/uipath/runtime/debug/runtime.py

@@ -3,19 +3,24 @@
 import logging
 from typing import Any, Optional
 
-from uipath.runtime import (
-    UiPathBreakpointResult,
+from uipath.runtime.base import (
     UiPathExecuteOptions,
     UiPathRuntimeProtocol,
-    UiPathRuntimeResult,
-    UiPathRuntimeStatus,
     UiPathStreamNotSupportedError,
     UiPathStreamOptions,
 )
-from uipath.runtime.debug import UiPathDebugBridgeProtocol, UiPathDebugQuitError
+from uipath.runtime.debug import (
+    UiPathBreakpointResult,
+    UiPathDebugBridgeProtocol,
+    UiPathDebugQuitError,
+)
 from uipath.runtime.events import (
     UiPathRuntimeStateEvent,
 )
+from uipath.runtime.result import (
+    UiPathRuntimeResult,
+    UiPathRuntimeStatus,
+)
 from uipath.runtime.schema import UiPathRuntimeSchema
 
 logger = logging.getLogger(__name__)

src/uipath/runtime/result.py

@@ -1,12 +1,13 @@
 """Result of an execution with status and optional error information."""
 
 from enum import Enum
-from typing import Any, Literal, Optional, Union
+from typing import Any, Optional, Union
 
 from pydantic import BaseModel, Field
 
 from uipath.runtime.errors import UiPathErrorContract
 from uipath.runtime.events import UiPathRuntimeEvent, UiPathRuntimeEventType
+from uipath.runtime.resumable.trigger import UiPathResumeTrigger
 
 
 class UiPathRuntimeStatus(str, Enum):
@@ -17,42 +18,6 @@ class UiPathRuntimeStatus(str, Enum):
     SUSPENDED = "suspended"
 
 
-class UiPathResumeTriggerType(str, Enum):
-    """Constants representing different types of resume job triggers in the system."""
-
-    NONE = "None"
-    QUEUE_ITEM = "QueueItem"
-    JOB = "Job"
-    ACTION = "Task"
-    TIMER = "Timer"
-    INBOX = "Inbox"
-    API = "Api"
-
-
-class UiPathApiTrigger(BaseModel):
-    """API resume trigger request."""
-
-    inbox_id: Optional[str] = Field(default=None, alias="inboxId")
-    request: Any = None
-
-    model_config = {"populate_by_name": True}
-
-
-class UiPathResumeTrigger(BaseModel):
-    """Information needed to resume execution."""
-
-    trigger_type: UiPathResumeTriggerType = Field(
-        default=UiPathResumeTriggerType.API, alias="triggerType"
-    )
-    item_key: Optional[str] = Field(default=None, alias="itemKey")
-    api_resume: Optional[UiPathApiTrigger] = Field(default=None, alias="apiResume")
-    folder_path: Optional[str] = Field(default=None, alias="folderPath")
-    folder_key: Optional[str] = Field(default=None, alias="folderKey")
-    payload: Optional[Any] = Field(default=None, alias="interruptObject")
-
-    model_config = {"populate_by_name": True}
-
-
 class UiPathRuntimeResult(UiPathRuntimeEvent):
     """Result of an execution with status and optional error information."""
 
@@ -86,16 +51,3 @@ def to_dict(self) -> dict[str, Any]:
             result["error"] = self.error.model_dump()
 
         return result
-
-
-class UiPathBreakpointResult(UiPathRuntimeResult):
-    """Result for execution suspended at a breakpoint."""
-
-    # Force status to always be SUSPENDED
-    status: UiPathRuntimeStatus = Field(
-        default=UiPathRuntimeStatus.SUSPENDED, frozen=True
-    )
-    breakpoint_node: str  # Which node the breakpoint is at
-    breakpoint_type: Literal["before", "after"]  # Before or after the node
-    current_state: dict[str, Any] | Any  # Current workflow state at breakpoint
-    next_nodes: list[str]  # Which node(s) will execute next

src/uipath/runtime/resumable/__init__.py

@@ -0,0 +1,23 @@
+"""Module for resumable runtime features."""
+
+from uipath.runtime.resumable.protocols import (
+    UiPathResumableStorageProtocol,
+    UiPathResumeTriggerCreatorProtocol,
+    UiPathResumeTriggerProtocol,
+    UiPathResumeTriggerReaderProtocol,
+)
+from uipath.runtime.resumable.trigger import (
+    UiPathApiTrigger,
+    UiPathResumeTrigger,
+    UiPathResumeTriggerType,
+)
+
+__all__ = [
+    "UiPathResumableStorageProtocol",
+    "UiPathResumeTriggerCreatorProtocol",
+    "UiPathResumeTriggerReaderProtocol",
+    "UiPathResumeTriggerProtocol",
+    "UiPathResumeTrigger",
+    "UiPathResumeTriggerType",
+    "UiPathApiTrigger",
+]

src/uipath/runtime/resumable/protocols.py

@@ -0,0 +1,84 @@
+"""Module defining the protocol for resume trigger storage."""
+
+from typing import Any, Optional, Protocol
+
+from uipath.runtime.resumable.trigger import UiPathResumeTrigger
+
+
+class UiPathResumableStorageProtocol(Protocol):
+    """Protocol for storing and retrieving resume triggers."""
+
+    async def save_trigger(self, trigger: UiPathResumeTrigger) -> None:
+        """Save a resume trigger to storage.
+
+        Args:
+            trigger: The resume trigger to persist
+
+        Raises:
+            Exception: If storage operation fails
+        """
+        ...
+
+    async def get_latest_trigger(self) -> Optional[UiPathResumeTrigger]:
+        """Retrieve the most recent resume trigger from storage.
+
+        Returns:
+            The latest resume trigger, or None if no triggers exist
+
+        Raises:
+            Exception: If retrieval operation fails
+        """
+        ...
+
+
+class UiPathResumeTriggerCreatorProtocol(Protocol):
+    """Protocol for creating resume triggers from suspend values."""
+
+    async def create_trigger(self, suspend_value: Any) -> UiPathResumeTrigger:
+        """Create a resume trigger from a suspend value.
+
+        Args:
+            suspend_value: The value that caused the suspension.
+                Can be UiPath models (CreateAction, InvokeProcess, etc.),
+                strings, or any other value that needs HITL processing.
+
+        Returns:
+            UiPathResumeTrigger ready to be persisted
+
+        Raises:
+            UiPathRuntimeError: If trigger creation fails
+        """
+        ...
+
+
+class UiPathResumeTriggerReaderProtocol(Protocol):
+    """Protocol for reading resume triggers and converting them to runtime input."""
+
+    async def read_trigger(self, trigger: UiPathResumeTrigger) -> Optional[Any]:
+        """Read a resume trigger and convert it to runtime-compatible input.
+
+        This method retrieves data from UiPath services (Actions, Jobs, API)
+        based on the trigger type and returns it in a format that the
+        runtime can use to resume execution.
+
+        Args:
+            trigger: The resume trigger to read
+
+        Returns:
+            The data retrieved from UiPath services, ready to be used
+            as resume input. Format depends on trigger type:
+            - ACTION: Action data (possibly with escalation processing)
+            - JOB: Job output data
+            - API: API payload
+            Returns None if no data is available.
+
+        Raises:
+            UiPathRuntimeError: If reading fails or job failed
+        """
+        ...
+
+
+class UiPathResumeTriggerProtocol(
+    UiPathResumeTriggerCreatorProtocol, UiPathResumeTriggerReaderProtocol, Protocol
+):
+    """Protocol combining both creation and reading of resume triggers."""