feat: add wait until interrupt model (#1768)

Author: radu-mocanu

packages/uipath-platform/pyproject.toml

@@ -1,14 +1,14 @@
 [project]
 name = "uipath-platform"
-version = "0.1.81"
+version = "0.1.82"
 description = "HTTP client library for programmatic access to UiPath Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
 dependencies = [
   "httpx>=0.28.1",
   "tenacity>=9.0.0",
   "truststore>=0.10.1",
-  "uipath-core>=0.5.25, <0.6.0",
+  "uipath-core>=0.5.26, <0.6.0",
   "pydantic-function-models>=0.1.11",
   "sqlparse>=0.5.5",
 ]

packages/uipath-platform/src/uipath/platform/common/__init__.py

@@ -60,6 +60,7 @@
     WaitJobRaw,
     WaitSystemAgent,
     WaitTask,
+    WaitUntil,
 )
 from .paging import PagedResult
 
@@ -99,6 +100,7 @@
     "DocumentExtractionValidation",
     "WaitDocumentExtractionValidation",
     "WaitIntegrationEvent",
+    "WaitUntil",
     "RequestSpec",
     "Endpoint",
     "UiPathUrl",

packages/uipath-platform/src/uipath/platform/common/interrupt_models.py

@@ -1,8 +1,9 @@
 """Models for interrupt operations in UiPath platform."""
 
+from datetime import datetime, timezone
 from typing import Annotated, Any
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 from uipath.platform.context_grounding.context_grounding_index import (
     ContextGroundingIndex,
@@ -279,3 +280,19 @@ class WaitIntegrationEvent(BaseModel):
     object_name: str
     filter_expression: str | None = None
     parameters: dict[str, str] | None = None
+
+
+class WaitUntil(BaseModel):
+    """Model representing a wait until an absolute point in time."""
+
+    resume_time: datetime = Field(alias="resumeTime")
+
+    model_config = ConfigDict(validate_by_name=True)
+
+    @field_validator("resume_time")
+    @classmethod
+    def validate_resume_time(cls, value: datetime) -> datetime:
+        """Validate and normalize resume_time to a UTC instant."""
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("resume_time must include timezone information")
+        return value.astimezone(timezone.utc)

packages/uipath-platform/src/uipath/platform/resume_triggers/_protocol.py

@@ -3,6 +3,7 @@
 import json
 import os
 import uuid
+from functools import cache
 from typing import Any
 
 from uipath.core.errors import (
@@ -49,6 +50,7 @@
     WaitJobRaw,
     WaitSystemAgent,
     WaitTask,
+    WaitUntil,
 )
 from uipath.platform.connections import EventArguments
 from uipath.platform.context_grounding import DeepRagStatus, IndexStatus
@@ -129,12 +131,18 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
             UiPathRuntimeError: If reading fails, job failed, API connection failed,
                 trigger type is unknown, or HITL feedback retrieval failed.
         """
-        uipath = UiPath()
+
+        @cache
+        def get_uipath() -> UiPath:
+            return UiPath()
 
         match trigger.trigger_type:
+            case UiPathResumeTriggerType.TIMER:
+                return {"resumeTime": serialize_object(trigger.resume_time)}
+
             case UiPathResumeTriggerType.TASK:
                 if trigger.item_key:
-                    task: Task = await uipath.tasks.retrieve_async(
+                    task: Task = await get_uipath().tasks.retrieve_async(
                         trigger.item_key,
                         app_folder_key=trigger.folder_key,
                         app_folder_path=trigger.folder_path,
@@ -182,7 +190,7 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
 
             case UiPathResumeTriggerType.JOB:
                 if trigger.item_key:
-                    job = await uipath.jobs.retrieve_async(
+                    job = await get_uipath().jobs.retrieve_async(
                         trigger.item_key,
                         folder_key=trigger.folder_key,
                         folder_path=trigger.folder_path,
@@ -223,7 +231,7 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
                             f"Process did not finish successfully. Error: {job_error}",
                         )
 
-                    output_data = await uipath.jobs.extract_output_async(job)
+                    output_data = await get_uipath().jobs.extract_output_async(job)
                     trigger_response = _try_convert_to_json_format(output_data)
 
                     # if response is an empty dictionary, use job state as placeholder value
@@ -239,9 +247,13 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
                     return trigger_response
             case UiPathResumeTriggerType.DEEP_RAG:
                 if trigger.item_key:
-                    deep_rag = await uipath.context_grounding.retrieve_deep_rag_async(
-                        trigger.item_key,
-                        index_name=self._extract_field("index_name", trigger.payload),
+                    deep_rag = (
+                        await get_uipath().context_grounding.retrieve_deep_rag_async(
+                            trigger.item_key,
+                            index_name=self._extract_field(
+                                "index_name", trigger.payload
+                            ),
+                        )
                     )
                     deep_rag_status = deep_rag.last_deep_rag_status
 
@@ -279,7 +291,7 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
 
             case UiPathResumeTriggerType.INDEX_INGESTION:
                 if trigger.item_key:
-                    index = await uipath.context_grounding.retrieve_by_id_async(
+                    index = await get_uipath().context_grounding.retrieve_by_id_async(
                         trigger.item_key
                     )
 
@@ -319,7 +331,7 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
                     )
                     assert destination_path is not None
                     try:
-                        await uipath.context_grounding.download_batch_transform_result_async(
+                        await get_uipath().context_grounding.download_batch_transform_result_async(
                             trigger.item_key,
                             destination_path,
                             validate_status=True,
@@ -349,10 +361,8 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
                     assert tag is not None
 
                     try:
-                        extraction_response = (
-                            await uipath.documents.retrieve_ixp_extraction_result_async(
-                                project_id, tag, trigger.item_key
-                            )
+                        extraction_response = await get_uipath().documents.retrieve_ixp_extraction_result_async(
+                            project_id, tag, trigger.item_key
                         )
                     except OperationNotCompleteException as e:
                         raise UiPathPendingTriggerError(
@@ -370,7 +380,7 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
                     assert project_id is not None
                     assert tag is not None
                     try:
-                        escalation_response = await uipath.documents.retrieve_ixp_extraction_validation_result_async(
+                        escalation_response = await get_uipath().documents.retrieve_ixp_extraction_validation_result_async(
                             project_id, tag, trigger.item_key
                         )
                     except OperationNotCompleteException as e:
@@ -394,7 +404,7 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
             case UiPathResumeTriggerType.API:
                 if trigger.api_resume and trigger.api_resume.inbox_id:
                     try:
-                        return await uipath.jobs.retrieve_api_payload_async(
+                        return await get_uipath().jobs.retrieve_api_payload_async(
                             trigger.api_resume.inbox_id
                         )
                     except Exception as e:
@@ -407,12 +417,16 @@ async def read_trigger(self, trigger: UiPathResumeTrigger) -> Any | None:
             case UiPathResumeTriggerType.INBOX:
                 if trigger.integration_resume and trigger.integration_resume.inbox_id:
                     try:
-                        inbox_payload = await uipath.jobs.retrieve_inbox_payload_async(
-                            trigger.integration_resume.inbox_id
+                        inbox_payload = (
+                            await get_uipath().jobs.retrieve_inbox_payload_async(
+                                trigger.integration_resume.inbox_id
+                            )
                         )
                         event_args = EventArguments.model_validate(inbox_payload)
-                        return await uipath.connections.retrieve_event_payload_async(
-                            event_args
+                        return (
+                            await get_uipath().connections.retrieve_event_payload_async(
+                                event_args
+                            )
                         )
                     except Exception as e:
                         raise UiPathFaultedTriggerError(
@@ -484,6 +498,9 @@ async def create_trigger(self, suspend_value: Any) -> UiPathResumeTrigger:
                 case UiPathResumeTriggerType.INBOX:
                     await self._handle_inbox_trigger(suspend_value, resume_trigger)
 
+                case UiPathResumeTriggerType.TIMER:
+                    self._handle_time_trigger(suspend_value, resume_trigger)
+
                 case UiPathResumeTriggerType.DEEP_RAG:
                     await self._handle_deep_rag_job_trigger(
                         suspend_value, resume_trigger
@@ -570,6 +587,8 @@ def _determine_trigger_type(self, value: Any) -> UiPathResumeTriggerType:
             return UiPathResumeTriggerType.IXP_VS_ESCALATION
         if isinstance(value, WaitIntegrationEvent):
             return UiPathResumeTriggerType.INBOX
+        if isinstance(value, WaitUntil):
+            return UiPathResumeTriggerType.TIMER
         # default to API trigger
         return UiPathResumeTriggerType.API
 
@@ -606,6 +625,8 @@ def _determine_trigger_name(self, value: Any) -> UiPathResumeTriggerName:
             return UiPathResumeTriggerName.EXTRACTION
         if isinstance(value, WaitIntegrationEvent):
             return UiPathResumeTriggerName.INBOX
+        if isinstance(value, WaitUntil):
+            return UiPathResumeTriggerName.TIMER
         # default to API trigger
         return UiPathResumeTriggerName.API
 
@@ -979,6 +1000,20 @@ async def _handle_inbox_trigger(
             inbox_id=str(uuid.uuid4()),
         )
 
+    def _handle_time_trigger(
+        self, value: WaitUntil, resume_trigger: UiPathResumeTrigger
+    ) -> None:
+        """Handle Timer-type resume triggers.
+
+        Orchestrator expects timer resume triggers as a top-level
+        `resumeTime` value on the resume trigger DTO.
+
+        Args:
+            value: The suspend value (WaitUntil)
+            resume_trigger: The resume trigger to populate
+        """
+        resume_trigger.resume_time = value.resume_time
+
 
 class UiPathResumeTriggerHandler:
     """Combined handler for creating and reading resume triggers.

packages/uipath-platform/tests/services/test_hitl.py

@@ -1,11 +1,13 @@
 import json
 import uuid
+from datetime import datetime, timedelta, timezone
 from typing import Any
 from unittest.mock import AsyncMock, patch
 
 import pytest
 from pytest_httpx import HTTPXMock
 from uipath.core.errors import ErrorCategory, UiPathFaultedTriggerError
+from uipath.core.serialization import serialize_object
 from uipath.core.triggers import (
     UiPathApiTrigger,
     UiPathIntegrationTrigger,
@@ -39,6 +41,7 @@
     WaitJobRaw,
     WaitSystemAgent,
     WaitTask,
+    WaitUntil,
 )
 from uipath.platform.connections import Connection
 from uipath.platform.context_grounding import (
@@ -1214,6 +1217,21 @@ async def test_read_ixp_vs_escalation_trigger_unassigned(
                 reader = UiPathResumeTriggerReader()
                 await reader.read_trigger(resume_trigger)
 
+    @pytest.mark.anyio
+    async def test_read_timer_trigger_serializes_resume_time(self) -> None:
+        """Test reading a timer trigger returns JSON-safe resume time data."""
+        resume_time = datetime(2026, 6, 27, 20, 14, 49, tzinfo=timezone.utc)
+        resume_trigger = UiPathResumeTrigger(
+            trigger_type=UiPathResumeTriggerType.TIMER,
+            trigger_name=UiPathResumeTriggerName.TIMER,
+            resume_time=resume_time,
+        )
+
+        reader = UiPathResumeTriggerReader()
+        result = await reader.read_trigger(resume_trigger)
+
+        assert result == {"resumeTime": serialize_object(resume_time)}
+
 
 class TestHitlProcessor:
     """Tests for the HitlProcessor class."""
@@ -2063,6 +2081,34 @@ async def test_create_resume_trigger_wait_document_extraction_validation(
         assert resume_trigger.trigger_type == UiPathResumeTriggerType.IXP_VS_ESCALATION
         assert resume_trigger.item_key == operation_id
 
+    @pytest.mark.anyio
+    async def test_create_resume_trigger_wait_until_normalizes_to_utc(self) -> None:
+        """Test creating a timer resume trigger for WaitUntil."""
+        local_resume_time = datetime(
+            2026,
+            6,
+            27,
+            23,
+            14,
+            49,
+            tzinfo=timezone(timedelta(hours=3)),
+        )
+        wait_until = WaitUntil(resume_time=local_resume_time)
+
+        processor = UiPathResumeTriggerCreator()
+        resume_trigger = await processor.create_trigger(wait_until)
+
+        assert resume_trigger.trigger_type == UiPathResumeTriggerType.TIMER
+        assert resume_trigger.trigger_name == UiPathResumeTriggerName.TIMER
+        assert resume_trigger.resume_time == datetime(
+            2026, 6, 27, 20, 14, 49, tzinfo=timezone.utc
+        )
+
+    def test_wait_until_requires_timezone_aware_resume_time(self) -> None:
+        """Test WaitUntil rejects timezone-naive resume times."""
+        with pytest.raises(ValueError, match="resume_time must include timezone"):
+            WaitUntil(resume_time=datetime(2026, 6, 27, 20, 14, 49))
+
 
 class TestDocumentExtractionModels:
     """Tests for document extraction models."""

packages/uipath-platform/uv.lock

@@ -1,13 +1,13 @@
 [project]
 name = "uipath"
-version = "2.11.15"
+version = "2.11.16"
 description = "Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
 dependencies = [
-  "uipath-core>=0.5.21, <0.6.0",
-  "uipath-runtime>=0.11.4, <0.12.0",
-  "uipath-platform>=0.1.81, <0.2.0",
+  "uipath-core>=0.5.26, <0.6.0",
+  "uipath-runtime>=0.11.5, <0.12.0",
+  "uipath-platform>=0.1.82, <0.2.0",
   "click>=8.3.1",
   "httpx>=0.28.1",
   "pyjwt>=2.10.1",