minitap-mobile-use 2.7.2__py3-none-any.whl → 2.8.0__py3-none-any.whl

minitap/mobile_use/main.py

@@ -43,7 +43,7 @@ async def run_automation(
         config.with_graph_config_callbacks(graph_config_callbacks)
 
     agent = Agent(config=config.build())
-    agent.init(
+    await agent.init(
         retry_count=int(os.getenv("MOBILE_USE_HEALTH_RETRIES", 5)),
         retry_wait_seconds=int(os.getenv("MOBILE_USE_HEALTH_DELAY", 2)),
     )
@@ -63,7 +63,7 @@ async def run_automation(
 
     await agent.run_task(request=task.build())
 
-    agent.clean()
+    await agent.clean()
 
 
 @app.command()

minitap/mobile_use/sdk/agent.py

@@ -13,6 +13,7 @@ from typing import Any, TypeVar, overload
 from adbutils import AdbClient
 from dotenv import load_dotenv
 from langchain_core.messages import AIMessage
+from PIL import Image
 from pydantic import BaseModel
 
 from minitap.mobile_use.agents.outputter.outputter import outputter
@@ -37,12 +38,14 @@ from minitap.mobile_use.graph.state import State
 from minitap.mobile_use.sdk.builders.agent_config_builder import get_default_agent_config
 from minitap.mobile_use.sdk.builders.task_request_builder import TaskRequestBuilder
 from minitap.mobile_use.sdk.constants import DEFAULT_HW_BRIDGE_BASE_URL, DEFAULT_SCREEN_API_BASE_URL
+from minitap.mobile_use.sdk.services.cloud_mobile import CloudMobileService
 from minitap.mobile_use.sdk.services.platform import PlatformService
 from minitap.mobile_use.sdk.types.agent import AgentConfig
 from minitap.mobile_use.sdk.types.exceptions import (
     AgentNotInitializedError,
     AgentProfileNotFoundError,
     AgentTaskRequestError,
+    CloudMobileServiceUninitializedError,
     DeviceNotFoundError,
     ExecutableNotFoundError,
     PlatformServiceUninitializedError,
@@ -92,6 +95,7 @@ class Agent:
     _adb_client: AdbClient | None
     _current_task: asyncio.Task | None = None
     _task_lock: asyncio.Lock
+    _cloud_mobile_id: str | None = None
 
     def __init__(self, *, config: AgentConfig | None = None):
         self._config = config or get_default_agent_config()
@@ -105,19 +109,38 @@ class Agent:
             self._config.servers.screen_api_base_url == DEFAULT_SCREEN_API_BASE_URL
         )
         self._task_lock = asyncio.Lock()
+
         # Initialize platform service if API key is available in environment
-        # Note: Can also be initialized later with API key from request
+        # Note: Can also be initialized later with API key at agent .init()
         if settings.MINITAP_API_KEY:
             self._platform_service = PlatformService()
+            self._cloud_mobile_service = CloudMobileService()
         else:
             self._platform_service = None
+            self._cloud_mobile_service = None
 
-    def init(
+    async def init(
         self,
+        api_key: str | None = None,
         server_restart_attempts: int = 3,
         retry_count: int = 5,
         retry_wait_seconds: int = 5,
     ):
+        if api_key:
+            self._platform_service = PlatformService(api_key=api_key)
+            self._cloud_mobile_service = CloudMobileService(api_key=api_key)
+
+        # Skip initialization for cloud devices - no local setup required
+        if self._config.cloud_mobile_id_or_ref:
+            if not self._cloud_mobile_service:
+                raise CloudMobileServiceUninitializedError()
+            self._cloud_mobile_id = await self._cloud_mobile_service.resolve_cloud_mobile_id(
+                cloud_mobile_id_or_ref=self._config.cloud_mobile_id_or_ref,
+            )
+            logger.info("Cloud device configured - skipping local initialization")
+            self._initialized = True
+            return True
+
         if not which("adb") and not which("xcrun"):
             raise ExecutableNotFoundError("cli_tools")
         if self._is_default_hw_bridge and not which("maestro"):
@@ -233,25 +256,30 @@ class Agent:
         name: str | None = None,
         request: TaskRequest[TOutput] | PlatformTaskRequest[TOutput] | None = None,
     ) -> str | dict | TOutput | None:
+        # Check if cloud mobile is configured
+        if self._config.cloud_mobile_id_or_ref:
+            if request is None or not isinstance(request, PlatformTaskRequest):
+                raise AgentTaskRequestError(
+                    "When using a cloud mobile, only PlatformTaskRequest is supported. "
+                    "Use AgentConfigBuilder.for_cloud_mobile() only with PlatformTaskRequest."
+                )
+            # Use cloud mobile execution path
+            return await self._run_cloud_mobile_task(request=request)
+
+        # Normal local execution path
         if request is not None:
             task_info = None
-            platform_service = None
             if isinstance(request, PlatformTaskRequest):
-                # Initialize platform service with API key from request if provided
-                if request.api_key:
-                    platform_service = PlatformService(api_key=request.api_key)
-                elif self._platform_service:
-                    platform_service = self._platform_service
-                else:
+                if not self._platform_service:
                     raise PlatformServiceUninitializedError()
-                task_info = await platform_service.create_task_run(request=request)
+                task_info = await self._platform_service.create_task_run(request=request)
                 if isinstance(request, CloudDevicePlatformTaskRequest):
                     request.task_run_id = task_info.task_run.id
                     request.task_run_id_available_event.set()
                 self._config.agent_profiles[task_info.llm_profile.name] = task_info.llm_profile
                 request = task_info.task_request
             return await self._run_task(
-                request=request, task_info=task_info, platform_service=platform_service
+                request=request, task_info=task_info, platform_service=self._platform_service
             )
         if goal is None:
             raise AgentTaskRequestError("Goal is required")
@@ -267,6 +295,96 @@ class Agent:
             task_request.with_name(name=name)
         return await self._run_task(task_request.build())
 
+    async def _run_cloud_mobile_task(
+        self,
+        request: PlatformTaskRequest[TOutput],
+    ) -> str | dict | TOutput | None:
+        """
+        Execute a task on a cloud mobile.
+
+        This method triggers the task execution on the Platform and polls
+        for completion without running any agentic logic locally.
+        """
+        if not self._cloud_mobile_id:
+            raise AgentTaskRequestError("Cloud mobile ID is not configured")
+
+        if not self._cloud_mobile_service:
+            raise CloudMobileServiceUninitializedError()
+
+        # Start cloud mobile if not already started
+        logger.info(f"Starting cloud mobile '{self._cloud_mobile_id}'...")
+        await self._cloud_mobile_service.start_and_wait_for_ready(
+            cloud_mobile_id=self._cloud_mobile_id,
+        )
+        logger.info(
+            f"Starting cloud mobile task execution '{self._cloud_mobile_id}'",
+        )
+
+        def log_callback(message: str):
+            """Callback for logging timeline updates."""
+            logger.info(message)
+
+        def status_callback(
+            status: TaskRunStatus,
+            status_message: str | None,
+        ):
+            """Callback for status updates."""
+            logger.info(f"Task status update: [{status}] {status_message}")
+
+        async def _execute_cloud(cloud_mobile_service: CloudMobileService, cloud_mobile_id: str):
+            try:
+                # Execute task on cloud mobile and wait for completion
+                final_status, error, output = await cloud_mobile_service.run_task_on_cloud_mobile(
+                    cloud_mobile_id=cloud_mobile_id,
+                    request=request,
+                    on_status_update=status_callback,
+                    on_log=log_callback,
+                )
+                if final_status == "completed":
+                    logger.success("Cloud mobile task completed successfully")
+                    return output
+                if final_status == "failed":
+                    logger.error(f"Cloud mobile task failed: {error}")
+                    raise AgentTaskRequestError(
+                        f"Task execution failed on cloud mobile: {error}",
+                    )
+                if final_status == "cancelled":
+                    logger.warning("Cloud mobile task was cancelled")
+                    raise AgentTaskRequestError("Task execution was cancelled")
+                logger.error(f"Unknown cloud mobile task status: {final_status}")
+                raise AgentTaskRequestError(f"Unknown task status: {final_status}")
+            except asyncio.CancelledError:
+                # Propagate cancellation to parent coroutine.
+                logger.info("Task cancelled during execution, re-raising CancelledError")
+                raise
+            except AgentTaskRequestError:
+                # Re-raise known exceptions
+                raise
+            except Exception as e:
+                logger.error(f"Unexpected error during cloud mobile task execution: {e}")
+                raise AgentTaskRequestError(f"Unexpected error: {e}") from e
+
+        async with self._task_lock:
+            if self._current_task and not self._current_task.done():
+                logger.warning(
+                    "Another cloud task is running; cancelling it before starting new one.",
+                )
+                self.stop_current_task()
+                try:
+                    await self._current_task
+                except asyncio.CancelledError:
+                    pass
+            try:
+                self._current_task = asyncio.create_task(
+                    _execute_cloud(
+                        cloud_mobile_service=self._cloud_mobile_service,
+                        cloud_mobile_id=self._cloud_mobile_id,
+                    ),
+                )
+                return await self._current_task
+            finally:
+                self._current_task = None
+
     async def _run_task(
         self,
         request: TaskRequest[TOutput],
@@ -456,6 +574,9 @@ class Agent:
         Uses the configured Screen API base URL instead of hardcoding localhost.
         """
         try:
+            # In cloud mode, local streaming health is irrelevant.
+            if self._config.cloud_mobile_id_or_ref:
+                return True
             response = self._screen_api_client.get_with_retry("/streaming-status", timeout=2)
             if response.status_code == 200:
                 data = response.json()
@@ -465,7 +586,86 @@ class Agent:
         except Exception:
             return False
 
-    def clean(self, force: bool = False):
+    async def get_screenshot(self) -> Image.Image:
+        """
+        Capture a screenshot from the mobile device.
+
+        For cloud mobiles, this method calls the mobile-manager endpoint.
+        For local mobiles, it uses ADB (Android) or xcrun (iOS) directly.
+
+        Returns:
+            Screenshot as PIL Image
+
+        Raises:
+            AgentNotInitializedError: If the agent is not initialized
+            PlatformServiceUninitializedError: If cloud mobile service is not available
+            Exception: If screenshot capture fails
+        """
+        # Check if cloud mobile is configured
+        if self._cloud_mobile_id:
+            if not self._cloud_mobile_service:
+                raise CloudMobileServiceUninitializedError()
+            screenshot = await self._cloud_mobile_service.get_screenshot(
+                cloud_mobile_id=self._cloud_mobile_id,
+            )
+            return screenshot
+
+        # Local device - use ADB or xcrun directly
+        if not self._initialized:
+            raise AgentNotInitializedError()
+
+        if self._device_context.mobile_platform == DevicePlatform.ANDROID:
+            # Use ADB to capture screenshot
+            logger.info("Capturing screenshot from local Android device")
+            if not self._adb_client:
+                raise Exception("ADB client not initialized")
+
+            device = self._adb_client.device(serial=self._device_context.device_id)
+            screenshot = await asyncio.to_thread(device.screenshot)
+            logger.info("Screenshot captured from local Android device")
+            return screenshot
+
+        elif self._device_context.mobile_platform == DevicePlatform.IOS:
+            # Use xcrun to capture screenshot
+            import functools
+            import subprocess
+            from io import BytesIO
+
+            logger.info("Capturing screenshot from local iOS device")
+            try:
+                # xcrun simctl io <device> screenshot --type=png -
+                result = await asyncio.to_thread(
+                    functools.partial(
+                        subprocess.run,
+                        [
+                            "xcrun",
+                            "simctl",
+                            "io",
+                            self._device_context.device_id,
+                            "screenshot",
+                            "--type=png",
+                            "-",
+                        ],
+                        capture_output=True,
+                        check=True,
+                    )
+                )
+                # Convert bytes to PIL Image
+                screenshot = Image.open(BytesIO(result.stdout))
+                logger.info("Screenshot captured from local iOS device")
+                return screenshot
+            except subprocess.CalledProcessError as e:
+                logger.error(f"Failed to capture screenshot: {e}")
+                raise Exception(f"Failed to capture screenshot from iOS device: {e}")
+
+        else:
+            raise Exception(f"Unsupported platform: {self._device_context.mobile_platform}")
+
+    async def clean(self, force: bool = False):
+        if self._cloud_mobile_id:
+            self._initialized = False
+            logger.info("✅ Cloud-mode agent stopped.")
+            return
         if not self._initialized and not force:
             return
         screen_api_ok, hw_bridge_ok = stop_servers(

minitap/mobile_use/sdk/builders/agent_config_builder.py

@@ -45,6 +45,7 @@ class AgentConfigBuilder:
         self._device_platform: DevicePlatform | None = None
         self._servers: ServerConfig = get_default_servers()
         self._graph_config_callbacks: Callbacks = None
+        self._cloud_mobile_id_or_ref: str | None = None
 
     def add_profile(self, profile: AgentProfile, validate: bool = True) -> "AgentConfigBuilder":
         """
@@ -95,10 +96,35 @@ class AgentConfigBuilder:
             platform: The device platform (ANDROID or IOS)
             device_id: The unique identifier for the device
         """
+        if self._cloud_mobile_id_or_ref is not None:
+            raise ValueError(
+                "Device ID cannot be set when a cloud mobile is already configured.\n"
+                "> for_device() and for_cloud_mobile() are mutually exclusive"
+            )
         self._device_id = device_id
         self._device_platform = platform
         return self
 
+    def for_cloud_mobile(self, cloud_mobile_id_or_ref: str) -> "AgentConfigBuilder":
+        """
+        Configure the mobile-use agent to use a cloud mobile.
+
+        When using a cloud mobile, tasks are executed remotely via the Platform API,
+        and only PlatformTaskRequest can be used.
+
+        Args:
+            cloud_mobile_id_or_ref: The unique identifier or reference name for the cloud mobile.
+                Can be either a UUID (e.g., '550e8400-e29b-41d4-a716-446655440000')
+                or a reference name (e.g., 'my-test-device')
+        """
+        if self._device_id is not None:
+            raise ValueError(
+                "Cloud mobile device ID cannot be set when a device is already configured.\n"
+                "> for_device() and for_cloud_mobile() are mutually exclusive"
+            )
+        self._cloud_mobile_id_or_ref = cloud_mobile_id_or_ref
+        return self
+
     def with_default_task_config(self, config: TaskRequestCommon) -> "AgentConfigBuilder":
         """
         Set the default task configuration.
@@ -217,6 +243,7 @@ class AgentConfigBuilder:
             device_platform=self._device_platform,
             servers=self._servers,
             graph_config_callbacks=self._graph_config_callbacks,
+            cloud_mobile_id_or_ref=self._cloud_mobile_id_or_ref,
         )
 
 

minitap/mobile_use/sdk/examples/README.md

@@ -15,7 +15,7 @@ These examples demonstrate two different ways to use the SDK, each applying an a
 This script shows the simplest way to run minitap :
 
 - Visit https://platform.minitap.ai to create a task and get your API key.
-- Initialize the agent with your API key: Agent(minitap_api_key=...).
+- Initialize the agent with your API key: .init(api_key=...).
 - Ask the agent to run one of the tasks you’ve set up in the Minitap platform
   (e.g., "like-instagram-post").
 - The task’s goal and settings live in the Minitap platform, you don’t need

minitap/mobile_use/sdk/examples/platform_manual_task_example.py

@@ -34,7 +34,7 @@ async def main() -> None:
     Set MINITAP_API_KEY and MINITAP_BASE_URL environment variables.
     """
     agent = Agent()
-    agent.init()
+    await agent.init()
 
     # Example 1: Simple manual task
     result = await agent.run_task(
@@ -58,7 +58,7 @@ async def main() -> None:
     )
     print("Result 2:", result)
 
-    agent.clean()
+    await agent.clean()
 
 
 if __name__ == "__main__":

minitap/mobile_use/sdk/examples/platform_minimal_example.py

@@ -31,16 +31,15 @@ async def main() -> None:
     Set MINITAP_API_KEY and MINITAP_BASE_URL environment variables.
     """
     agent = Agent()
-    agent.init()
+    await agent.init(api_key="<api-key>")  # or set MINITAP_API_KEY env variable
     result = await agent.run_task(
         request=PlatformTaskRequest(
             task="your-task-name",
             profile="your-profile-name",
-            api_key="<api-key>",  # or set MINITAP_API_KEY env variable
         )
     )
     print(result)
-    agent.clean()
+    await agent.clean()
 
 
 if __name__ == "__main__":

minitap/mobile_use/sdk/examples/simple_photo_organizer.py

@@ -33,7 +33,7 @@ async def main() -> None:
 
     try:
         # Initialize agent (finds a device, starts required servers)
-        agent.init()
+        await agent.init()
 
         # Calculate yesterday's date for the example
         yesterday = date.today() - timedelta(days=1)
@@ -69,7 +69,7 @@ async def main() -> None:
         print(f"Error: {e}")
     finally:
         # Always clean up resources
-        agent.clean()
+        await agent.clean()
 
 
 if __name__ == "__main__":

minitap/mobile_use/sdk/examples/smart_notification_assistant.py

@@ -167,7 +167,7 @@ async def main():
 
     try:
         # Initialize agent (finds a device, starts required servers)
-        agent.init()
+        await agent.init()
 
         print("Checking for notifications...")
 
@@ -217,7 +217,7 @@ async def main():
 
     finally:
         # Clean up
-        agent.clean()
+        await agent.clean()
         print(f"\nTraces saved to: {traces_dir}")
 
 

minitap/mobile_use/sdk/services/cloud_mobile.py

@@ -0,0 +1,582 @@
+"""Service for managing cloud device (virtual mobile) task execution."""
+
+import asyncio
+from datetime import UTC, datetime
+from io import BytesIO
+import json
+from typing import Any, Literal
+from collections.abc import Callable
+
+import httpx
+from PIL import Image
+from pydantic import BaseModel, Field
+
+from minitap.mobile_use.config import settings
+from minitap.mobile_use.sdk.types.exceptions import PlatformServiceError
+from minitap.mobile_use.sdk.types.platform import TaskRunStatus
+from minitap.mobile_use.sdk.types.task import PlatformTaskRequest
+from minitap.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class RunTaskRequest(BaseModel):
+    """Request to run a task on a virtual mobile."""
+
+    task_request: dict[str, Any] = Field(..., alias="taskRequest", description="Task request")
+
+
+class RunTaskResponse(BaseModel):
+    """Response from running a task on a virtual mobile."""
+
+    task_run_id: str = Field(..., alias="taskRunId", description="ID of the task run")
+
+
+class SubgoalTimelineItemResponse(BaseModel):
+    """A subgoal timeline item."""
+
+    name: str = Field(..., alias="name", description="Name of the subgoal")
+    state: str = Field(..., alias="state", description="State of the subgoal")
+    started_at: datetime | None = Field(
+        None,
+        alias="startedAt",
+        description="Start time of the subgoal",
+    )
+    ended_at: datetime | None = Field(
+        None,
+        alias="endedAt",
+        description="End time of the subgoal",
+    )
+
+
+class AgentThoughtTimelineItemResponse(BaseModel):
+    """An agent thought timeline item."""
+
+    agent: str = Field(..., alias="agent", description="Agent who thought")
+    content: str = Field(..., alias="content", description="Content of the thought")
+    timestamp: datetime = Field(..., alias="timestamp", description="Timestamp of the thought")
+
+
+class TaskRunInfo(BaseModel):
+    """Information about a task run."""
+
+    id: str
+    status: TaskRunStatus
+    status_message: str | None = None
+    output: str | dict[str, Any] | None = None
+
+
+class TimelineItem(BaseModel):
+    """A timeline item (subgoal or agent thought)."""
+
+    timestamp: datetime
+    content: str
+
+
+VMState = Literal["Stopped", "Starting", "Ready", "Error", "Stopping", "Unknown"]
+
+
+class VirtualMobileInfo(BaseModel):
+    """Information about a virtual mobile."""
+
+    id: str
+    reference_name: str | None = None
+    state: VMState
+    message: str | None = None
+
+
+class CloudMobileService:
+    """
+    Service for executing tasks on cloud mobiles.
+
+    This service handles:
+    - Starting and waiting for cloud mobiles to be ready
+    - Triggering task execution via the Platform
+    - Polling Platform API for task status and logs
+    - Handling task cancellation
+    - Timeout management for stalled tasks
+    """
+
+    def __init__(self, api_key: str | None = None, http_timeout_seconds: int = 120):
+        self._platform_base_url = settings.MINITAP_BASE_URL
+
+        if api_key:
+            self._api_key = api_key
+        elif settings.MINITAP_API_KEY:
+            self._api_key = settings.MINITAP_API_KEY.get_secret_value()
+        else:
+            raise PlatformServiceError(
+                message="Please provide an API key or set MINITAP_API_KEY environment variable.",
+            )
+
+        self._timeout = httpx.Timeout(timeout=http_timeout_seconds)
+        self._client = httpx.AsyncClient(
+            base_url=f"{self._platform_base_url}/api",
+            timeout=self._timeout,
+            headers={
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    async def start_and_wait_for_ready(
+        self,
+        cloud_mobile_id: str,
+        poll_interval_seconds: float = 5.0,
+        timeout_seconds: float = 300.0,
+    ) -> VirtualMobileInfo:
+        """
+        Start a cloud mobile by keeping it alive and wait for it to become ready.
+
+        Args:
+            cloud_mobile_id: ID of the cloud mobile to start
+            poll_interval_seconds: Seconds between status polls (default: 5.0)
+            timeout_seconds: Maximum time to wait for ready state (default: 300.0)
+
+        Returns:
+            VirtualMobileInfo with the final state
+
+        Raises:
+            PlatformServiceError: If the cloud mobile fails to start or times out
+        """
+        logger.info(f"Starting cloud mobile '{cloud_mobile_id}'")
+
+        # Step 1: Trigger keep-alive to start the VM
+        await self._keep_alive(cloud_mobile_id)
+
+        # Step 2: Poll until ready or timeout
+        start_time = datetime.now(UTC)
+
+        while True:
+            # Check timeout
+            elapsed = (datetime.now(UTC) - start_time).total_seconds()
+            if elapsed > timeout_seconds:
+                raise PlatformServiceError(
+                    message=f"Timeout waiting for cloud mobile to be ready after {timeout_seconds}s"
+                )
+
+            # Get current status
+            vm_info = await self._get_virtual_mobile_status(cloud_mobile_id)
+
+            logger.info(
+                f"Cloud mobile '{cloud_mobile_id}' status: {vm_info.state} - {vm_info.message}"
+            )
+
+            # Check if ready
+            if vm_info.state == "Ready":
+                logger.success(f"Cloud mobile '{cloud_mobile_id}' is ready")
+                return vm_info
+
+            # Check for error state
+            if vm_info.state == "Error":
+                raise PlatformServiceError(
+                    message=f"Cloud mobile entered error state: {vm_info.message}"
+                )
+
+            # Wait before next poll
+            await asyncio.sleep(poll_interval_seconds)
+
+    async def _keep_alive(self, cloud_mobile_id: str) -> None:
+        """Keep a cloud mobile alive to prevent idle shutdown."""
+        try:
+            response = await self._client.post(f"daas/virtual-mobiles/{cloud_mobile_id}/keep-alive")
+            response.raise_for_status()
+            logger.info(f"Keep-alive sent to cloud mobile '{cloud_mobile_id}'")
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(
+                message="Failed to keep cloud mobile alive: "
+                f"{e.response.status_code} - {e.response.text}"
+            )
+
+    async def _get_virtual_mobile_status(self, cloud_mobile_id: str) -> VirtualMobileInfo:
+        """Get the current status of a cloud mobile."""
+        try:
+            response = await self._client.get(f"daas/virtual-mobiles/{cloud_mobile_id}")
+            response.raise_for_status()
+            data = response.json()
+
+            return VirtualMobileInfo(
+                id=data["id"],
+                reference_name=data.get("referenceName"),
+                state=data["state"].get("current", "Unknown"),
+                message=data["state"].get("message", "Unknown"),
+            )
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(
+                message="Failed to get cloud mobile status: "
+                f"{e.response.status_code} - {e.response.text}"
+            )
+
+    async def resolve_cloud_mobile_id(self, cloud_mobile_id_or_ref: str) -> str:
+        """
+        Resolve a cloud mobile identifier (ID or reference name) to a cloud mobile UUID.
+
+        Uses the GetVirtualMobile endpoint which supports both UUID and reference name lookup.
+
+        Args:
+            cloud_mobile_id_or_ref: Either a cloud mobile UUID or reference name
+
+        Returns:
+            The cloud mobile UUID
+
+        Raises:
+            PlatformServiceError: If the cloud mobile is not found or resolution fails
+        """
+        try:
+            response = await self._client.get(f"daas/virtual-mobiles/{cloud_mobile_id_or_ref}")
+            response.raise_for_status()
+            data = response.json()
+
+            resolved_id = data["id"]
+            logger.info(f"Resolved '{cloud_mobile_id_or_ref}' to UUID '{resolved_id}'")
+            return resolved_id
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(
+                message=f"Failed to resolve cloud mobile identifier '{cloud_mobile_id_or_ref}': "
+                f"{e.response.status_code} - {e.response.text}"
+            )
+
+    async def run_task_on_cloud_mobile(
+        self,
+        cloud_mobile_id: str,
+        request: PlatformTaskRequest,
+        on_status_update: Callable[[TaskRunStatus, str | None], None] | None = None,
+        on_log: Callable[[str], None] | None = None,
+        poll_interval_seconds: float = 2.0,
+        stall_timeout_seconds: float = 300.0,
+    ) -> tuple[TaskRunStatus, str | None, Any | None]:
+        """
+        Run a task on a cloud mobile and wait for completion.
+
+        Args:
+            cloud_mobile_id: ID of the cloud mobile to run the task on
+            request: Platform task request to execute
+            on_status_update: Optional callback for status updates
+            on_log: Optional callback for log messages
+            poll_interval_seconds: Seconds between status polls (default: 2.0)
+            stall_timeout_seconds: Timeout if no new timeline activity (default: 300.0)
+
+        Returns:
+            Tuple of (final_status, error_message, output)
+
+        Raises:
+            PlatformServiceError: If the task execution fails
+        """
+        task_run_id: str | None = None
+        try:
+            # Step 1: Trigger the task run
+            logger.info(f"Starting task on cloud mobile '{cloud_mobile_id}'")
+
+            task_run_id = await self._trigger_task_run(
+                cloud_mobile_id=cloud_mobile_id,
+                request=request,
+            )
+            logger.info(f"Task run started: {task_run_id}")
+
+            # Step 2: Poll for completion
+            final_status, error, output = await self._poll_task_until_completion(
+                cloud_mobile_id=cloud_mobile_id,
+                task_run_id=task_run_id,
+                on_status_update=on_status_update,
+                on_log=on_log,
+                poll_interval_seconds=poll_interval_seconds,
+                stall_timeout_seconds=stall_timeout_seconds,
+            )
+
+            return final_status, error, output
+
+        except asyncio.CancelledError:
+            # Task was cancelled locally - propagate to the Platform
+            logger.info("Task cancelled locally, propagating to the Platform")
+            if task_run_id is not None:
+                try:
+                    await self.cancel_task_runs(cloud_mobile_id)
+                except Exception as e:
+                    logger.warning(f"Failed to propagate cancellation: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to run task on cloud device: {str(e)}")
+            raise PlatformServiceError(message=f"Failed to run task on cloud device: {e}")
+
+    async def _trigger_task_run(self, cloud_mobile_id: str, request: PlatformTaskRequest) -> str:
+        """Trigger a task run on the Platform and return the task run ID."""
+        try:
+            # Build the task request payload
+            payload = RunTaskRequest(
+                taskRequest={
+                    "profile": request.profile,
+                    "task": (
+                        request.task if isinstance(request.task, str) else request.task.model_dump()
+                    ),
+                }
+            )
+
+            response = await self._client.post(
+                f"daas/virtual-mobiles/{cloud_mobile_id}/run-task",
+                json=payload.model_dump(by_alias=True),
+            )
+            response.raise_for_status()
+
+            result = RunTaskResponse.model_validate(response.json())
+            return result.task_run_id
+
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(message=f"Failed to trigger task run on the Platform: {e}")
+
+    async def _poll_task_until_completion(
+        self,
+        cloud_mobile_id: str,
+        task_run_id: str,
+        on_status_update: Callable[[TaskRunStatus, str | None], None] | None,
+        on_log: Callable[[str], None] | None,
+        poll_interval_seconds: float,
+        stall_timeout_seconds: float,
+    ) -> tuple[TaskRunStatus, str | None, Any | None]:
+        """
+        Poll task run status until it completes, fails, or times out.
+
+        Returns:
+            Tuple of (final_status, error_message, output)
+        """
+        last_poll_time: datetime | None = None
+        last_activity_time = datetime.now(UTC)
+        current_status: TaskRunStatus = "pending"
+        previous_status: TaskRunStatus | None = None
+
+        while True:
+            # Check for stall timeout
+            now = datetime.now(UTC)
+            time_since_last_activity = (now - last_activity_time).total_seconds()
+            if time_since_last_activity > stall_timeout_seconds:
+                error_msg = (
+                    f"Task stalled: No activity for {stall_timeout_seconds} seconds. "
+                    "The task is considered failed."
+                )
+                logger.error(f"{error_msg} (task_run_id: {task_run_id})")
+                await self.cancel_task_runs(cloud_mobile_id)
+                return "cancelled", error_msg, None
+
+            # Fetch current task run status
+            task_info = await self._get_task_run_status(task_run_id)
+            current_status = task_info.status
+
+            # Notify status update
+            if previous_status != current_status and on_status_update:
+                previous_status = current_status
+                last_activity_time = now
+                try:
+                    on_status_update(
+                        task_info.status,
+                        task_info.status_message,
+                    )
+                except Exception as e:
+                    logger.warning(f"Status update callback failed: {e}")
+
+            # Check for subgoal updates
+            subgoal_updates = await self._get_subgoal_updates(
+                task_run_id=task_run_id,
+                after_timestamp=last_poll_time,
+            )
+
+            # Check for new agent thoughts
+            new_thoughts = await self._get_new_agent_thoughts(
+                task_run_id=task_run_id,
+                after_timestamp=last_poll_time,
+            )
+
+            updates = sorted(
+                subgoal_updates + new_thoughts,
+                key=lambda item: item.timestamp,
+            )
+            if updates:
+                last_activity_time = now
+                for update in updates:
+                    if on_log:
+                        try:
+                            on_log(f"[{update.timestamp}] {update.content}")
+                        except Exception as e:
+                            logger.warning(f"Log callback failed: {e}")
+
+            # Check if task is in terminal state
+            if current_status in ["completed", "failed", "cancelled"]:
+                logger.info(f"Task '{task_run_id}' reached terminal state: {current_status}")
+                error = (
+                    task_info.status_message if current_status in ["failed", "cancelled"] else None
+                )
+                return current_status, error, task_info.output
+
+            # Wait before next poll
+            last_poll_time = now
+            await asyncio.sleep(poll_interval_seconds)
+
+    async def _get_task_run_status(self, task_run_id: str) -> TaskRunInfo:
+        """Get the current status of a task run."""
+        try:
+            response = await self._client.get(f"v1/task-runs/{task_run_id}")
+            response.raise_for_status()
+            data = response.json()
+
+            output: str | dict[str, Any] | None = None
+            raw_output = data.get("output")
+            try:
+                if raw_output is not None:
+                    output = json.loads(raw_output)
+            except json.JSONDecodeError:
+                output = raw_output
+
+            return TaskRunInfo(
+                id=data["id"],
+                status=data["status"],
+                status_message=data.get("statusMessage"),
+                output=output,
+            )
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(message=f"Failed to get task run status: {e}")
+
+    async def _get_subgoal_updates(
+        self,
+        task_run_id: str,
+        after_timestamp: datetime | None,
+    ) -> list[TimelineItem]:
+        """Get new subgoals from the timeline after a specific timestamp."""
+        try:
+            started_subgoals = await self._get_filtered_subgoals(
+                task_run_id=task_run_id,
+                sort_by="started_at",
+                sort_order="asc",
+                after_timestamp=after_timestamp,
+            )
+            ended_subgoals = await self._get_filtered_subgoals(
+                task_run_id=task_run_id,
+                sort_by="ended_at",
+                sort_order="asc",
+                after_timestamp=after_timestamp,
+            )
+            items: list[TimelineItem] = []
+            for subgoal in started_subgoals:
+                if subgoal.started_at is None:
+                    continue
+                items.append(
+                    TimelineItem(
+                        timestamp=subgoal.started_at,
+                        content=f"[START][{subgoal.name}] {subgoal.state}",
+                    )
+                )
+            for subgoal in ended_subgoals:
+                if subgoal.ended_at is None:
+                    continue
+                items.append(
+                    TimelineItem(
+                        timestamp=subgoal.ended_at,
+                        content=f"[END][{subgoal.name}] {subgoal.state}",
+                    )
+                )
+            return items
+        except httpx.HTTPStatusError as e:
+            logger.warning(f"Failed to get subgoals timeline: {e}")
+            return []
+
+    async def _get_filtered_subgoals(
+        self,
+        task_run_id: str,
+        sort_by: str,
+        sort_order: str,
+        after_timestamp: datetime | None,
+    ) -> list[SubgoalTimelineItemResponse]:
+        params: dict[str, Any] = {
+            "page": 1,
+            "pageSize": 50,
+            "sortBy": sort_by,
+            "sortOrder": sort_order,
+        }
+        if after_timestamp:
+            params["after"] = after_timestamp.isoformat()
+
+        response = await self._client.get(
+            f"v1/task-runs/{task_run_id}/subgoals/timeline",
+            params=params,
+        )
+        response.raise_for_status()
+        data = response.json()
+        subgoals = [
+            SubgoalTimelineItemResponse.model_validate(item) for item in data.get("subgoals", [])
+        ]
+        return subgoals
+
+    async def _get_new_agent_thoughts(
+        self, task_run_id: str, after_timestamp: datetime | None
+    ) -> list[TimelineItem]:
+        """Get new agent thoughts from the timeline after a specific timestamp."""
+        try:
+            params: dict[str, Any] = {"page": 1, "pageSize": 50}
+            if after_timestamp:
+                params["after"] = after_timestamp.isoformat()
+
+            response = await self._client.get(
+                f"v1/task-runs/{task_run_id}/agent-thoughts/timeline",
+                params=params,
+            )
+            response.raise_for_status()
+            data = response.json()
+            agent_thoughts = [
+                AgentThoughtTimelineItemResponse.model_validate(item)
+                for item in data.get("agentThoughts", [])
+            ]
+
+            items: list[TimelineItem] = []
+            for thought in agent_thoughts:
+                items.append(
+                    TimelineItem(
+                        timestamp=thought.timestamp,
+                        content=f"[{thought.agent}] {thought.content}",
+                    )
+                )
+            return items
+        except httpx.HTTPStatusError as e:
+            logger.warning(f"Failed to get agent thoughts timeline: {e}")
+            return []
+
+    async def cancel_task_runs(self, cloud_mobile_id: str) -> None:
+        """Cancel all task runs on the Platform for a specific cloud mobile."""
+        try:
+            # Only one task can run on a cloud mobile at a time.
+            # Therefore, cancelling all tasks running on it implies cancelling the task run.
+            response = await self._client.post(
+                f"v1/task-runs/virtual-mobile/{cloud_mobile_id}/cancel"
+            )
+            response.raise_for_status()
+            logger.info(f"Task runs cancelled on cloud mobile '{cloud_mobile_id}'")
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(message=f"Failed to cancel task run: {e}")
+
+    async def get_screenshot(self, cloud_mobile_id: str) -> Image.Image:
+        """
+        Get a screenshot from a cloud mobile.
+
+        Args:
+            cloud_mobile_id: ID of the cloud mobile to capture screenshot from
+
+        Returns:
+            Screenshot as PIL Image
+
+        Raises:
+            PlatformServiceError: If the screenshot capture fails
+        """
+        try:
+            logger.info(f"Capturing screenshot from cloud mobile '{cloud_mobile_id}'")
+            response = await self._client.get(f"daas/virtual-mobiles/{cloud_mobile_id}/screenshot")
+            response.raise_for_status()
+
+            # Convert bytes to PIL Image
+            image = Image.open(BytesIO(response.content))
+
+            size_bytes = len(response.content)
+            logger.info(
+                f"Screenshot captured from cloud mobile '{cloud_mobile_id}' ({size_bytes} bytes)"
+            )
+            return image
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(
+                message=f"Failed to get screenshot from cloud mobile: "
+                f"{e.response.status_code} - {e.response.text}"
+            )

minitap/mobile_use/sdk/types/agent.py

@@ -65,6 +65,8 @@ class AgentConfig(BaseModel):
         device_id: Specific device to target (if None, first available is used).
         device_platform: Platform of the device to target.
         servers: Custom server configurations.
+        cloud_mobile_id_or_ref: ID or reference name of cloud mobile (virtual mobile)
+                                to use for remote execution.
     """
 
     agent_profiles: dict[str, AgentProfile]
@@ -74,5 +76,6 @@ class AgentConfig(BaseModel):
     device_platform: DevicePlatform | None = None
     servers: ServerConfig
     graph_config_callbacks: Callbacks = None
+    cloud_mobile_id_or_ref: str | None = None
 
     model_config = {"arbitrary_types_allowed": True}

minitap/mobile_use/sdk/types/exceptions.py

@@ -124,6 +124,13 @@ class PlatformServiceUninitializedError(MobileUseError):
         )
 
 
+class CloudMobileServiceUninitializedError(MobileUseError):
+    """Exception raised when a cloud mobile service call fails."""
+
+    def __init__(self):
+        super().__init__("Cloud mobile service is not initialized!")
+
+
 class PlatformServiceError(MobileUseError):
     """Exception raised when a platform service call fails."""
 

minitap/mobile_use/sdk/types/task.py

@@ -127,13 +127,10 @@ class PlatformTaskRequest[TOutput](TaskRequestBase):
         task: Either a task name to fetch from the platform, or a
               ManualTaskConfig to create manually
         profile: Optional profile name specified by the user on the platform
-        api_key: Optional API key to authenticate with the platform
-                 (overrides MINITAP_API_KEY env variable)
     """
 
     task: str | ManualTaskConfig
     profile: str | None = None
-    api_key: str | None = None
 
 
 class CloudDevicePlatformTaskRequest[TOutput](PlatformTaskRequest[TOutput]):

{minitap_mobile_use-2.7.2.dist-info → minitap_mobile_use-2.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: minitap-mobile-use
-Version: 2.7.2
+Version: 2.8.0
 Summary: AI-powered multi-agent system that automates real Android and iOS devices through low-level control using LangGraph.
 Author: Pierre-Louis Favreau, Jean-Pierre Lo, Nicolas Dehandschoewercker
 License: MIT License

{minitap_mobile_use-2.7.2.dist-info → minitap_mobile_use-2.8.0.dist-info}/RECORD

@@ -36,26 +36,27 @@ minitap/mobile_use/controllers/platform_specific_commands_controller.py,sha256=8
 minitap/mobile_use/controllers/types.py,sha256=c4dd6b266dd8f157ca1e6a211369ba8e7f65d3fda72b0742bda1128eefd99473,2935
 minitap/mobile_use/graph/graph.py,sha256=94dbac498a77eab3fbb413182ec4c3272c353837f71268344e150a2c00a9747e,6012
 minitap/mobile_use/graph/state.py,sha256=1903f49772be7f9725e69718194a7be953203f882ec5e26211a5db6fdc569478,3596
-minitap/mobile_use/main.py,sha256=1405a13eab2c3b86b148bb9678e829447522753a10572935fc1e3ed3bbce6878,3927
+minitap/mobile_use/main.py,sha256=1f0568a4e889837591ace797d2a0186ca4dc8e82ae7f9b64588fa8ece5701ee6,3939
 minitap/mobile_use/sdk/__init__.py,sha256=4e5555c0597242b9523827194a2500b9c6d7e5c04b1ccd2056c9b1f4d42a31cd,318
-minitap/mobile_use/sdk/agent.py,sha256=a1380a32b14784ce3cdcd7deaca2ffd643491bc23372297a24798a53bc7a1a37,30579
+minitap/mobile_use/sdk/agent.py,sha256=057d0a347fe87ec5e5a7edfedd9637df41be304e15181a9d60a781940f806450,39228
 minitap/mobile_use/sdk/builders/__init__.py,sha256=d6c96d39b80900a114698ef205ab5061a541f33bfa99c456d9345e5adb8ff6ff,424
-minitap/mobile_use/sdk/builders/agent_config_builder.py,sha256=4b8ed9eb84d9093f18166e4c4f99e3da6941cf374c9c112cb3c37ea0fadcfe02,7917
+minitap/mobile_use/sdk/builders/agent_config_builder.py,sha256=d3f75c7d0431bde7b64915fcb68b30aa2c3e0d714cec09997310d4410f23490d,9206
 minitap/mobile_use/sdk/builders/index.py,sha256=64336ac3b3dea4673a48e95b8c5ac4196ecd5d2196380377d102593d0a1dc138,442
 minitap/mobile_use/sdk/builders/task_request_builder.py,sha256=9e6cf7afb68af986d6a81487179bb79d28f63047a068725d92996dbcbe753376,6857
 minitap/mobile_use/sdk/constants.py,sha256=436ba0700c6cf37ac0c9e3995a5f5a0d54ca87af72686eb9667a2c6a96e30f68,292
-minitap/mobile_use/sdk/examples/README.md,sha256=c92e57d6efc5bce9f3c8668b20d9ce80396aefb7a685636ee84de8c7b9c1403e,3247
+minitap/mobile_use/sdk/examples/README.md,sha256=9cdc39b7f2b715c61430e162a3136732efc25d767203072dc5d17f1c5e566783,3239
 minitap/mobile_use/sdk/examples/__init__.py,sha256=c23868a2ca7e9b76e80d6835fe93c10e13ea8f2287dd6e785511b8ac30354e9b,46
-minitap/mobile_use/sdk/examples/platform_manual_task_example.py,sha256=00f54d58fa0abe9a1df20b3593633c239947c5acdf716fe9be1f58f9f56d8caa,1937
-minitap/mobile_use/sdk/examples/platform_minimal_example.py,sha256=bdb86142f4bb5d95d54838fc6487bb06e5e21db5106385344138be1653071aea,1389
-minitap/mobile_use/sdk/examples/simple_photo_organizer.py,sha256=8ad1cebb5281e3663264560bd15b090add41d2821b1db77e4cbc829860c98df8,2606
-minitap/mobile_use/sdk/examples/smart_notification_assistant.py,sha256=ecab26c6fd2af59bb22dbc67f0eeb4a4a73e4394639b34fb2d44f04f218e2b61,8104
+minitap/mobile_use/sdk/examples/platform_manual_task_example.py,sha256=e3ce79c6454aea1641b69ddc1df7552c599fccd88d4c006c55b3c6284bb24282,1949
+minitap/mobile_use/sdk/examples/platform_minimal_example.py,sha256=a42f744e37f9ed3fff51183b7eeedf140d6aabaf29b35bf80a7ab267cc2b5c0e,1387
+minitap/mobile_use/sdk/examples/simple_photo_organizer.py,sha256=4b271309905d3b99cd60060a5e4a12594983838641ef456dbba4b3cbc842edcd,2618
+minitap/mobile_use/sdk/examples/smart_notification_assistant.py,sha256=c5605bf4d4e79ff7f41eee58910a45d317fb217b5aa5dc498ed00c5f0f2f14be,8116
+minitap/mobile_use/sdk/services/cloud_mobile.py,sha256=5ec8e2e37a100c5783c0b2d33b91f33a5abcf299b75516debc05e1bdb6b51b13,21802
 minitap/mobile_use/sdk/services/platform.py,sha256=516b17f5286f8cb7ef7d5f0d2b0af23b90b17588faa9f638ea5cdb4f3935e64e,12545
 minitap/mobile_use/sdk/types/__init__.py,sha256=433aff6b35f84a985633204edbbdaca9f2f61fb2b822630f9723c481b9bb5c10,1078
-minitap/mobile_use/sdk/types/agent.py,sha256=390d5c642b3480f4a2203ddd28ec115c785f2576bec81e82e4db3c129399c020,2260
-minitap/mobile_use/sdk/types/exceptions.py,sha256=684c0049c5af417edf7e46e515be14fd57a0614c81b06ed52f379bc9d0bbebf3,4499
+minitap/mobile_use/sdk/types/agent.py,sha256=d286cf2c4eb0c98c82928e295750c16adf1072d5ace3353ddb512b5bd7593877,2453
+minitap/mobile_use/sdk/types/exceptions.py,sha256=81e12f2bfe3937d730dc47a0938d3911239a162ddbd1a1179473a155946cb836,4722
 minitap/mobile_use/sdk/types/platform.py,sha256=6d1eefa6fb73aea1c574eeb24b05ee89d0119e6e01cdcd6022923df8f7d511e7,5295
-minitap/mobile_use/sdk/types/task.py,sha256=3d44a07bca698b2bbfc18e240c0b4be74e6fb4422ab7ed0a9a9b411e903021b8,8539
+minitap/mobile_use/sdk/types/task.py,sha256=c7f0b3c59ee980eb63e9836268701069e805107b9057ec1a098daa236b30d0ba,8382
 minitap/mobile_use/sdk/utils.py,sha256=647f1f4a463c3029c3b0eb3c33f7dd778d5f5fd9d293224f5474595a60e1de6f,967
 minitap/mobile_use/servers/config.py,sha256=8a4a6bce23e2093d047a91e135e2f88627f76ac12177d071f25a3ca739b3afeb,575
 minitap/mobile_use/servers/device_hardware_bridge.py,sha256=39c20834812d9929163affaedd0e285ab0b349948b3236156c04a3e0bf094272,7456
@@ -96,7 +97,7 @@ minitap/mobile_use/utils/shell_utils.py,sha256=b35ae7f863379adb86c9ba0f9b3b9d495
 minitap/mobile_use/utils/test_ui_hierarchy.py,sha256=96c1549c05b4f7254a22d57dbd40aea860756f1e0b9d8cc24319383643448422,5911
 minitap/mobile_use/utils/time.py,sha256=41bfaabb3751de11443ccb4a3f1f53d5ebacc7744c72e32695fdcc3d23f17d49,160
 minitap/mobile_use/utils/ui_hierarchy.py,sha256=f3370518035d9daf02c08042a9e28ad564f4fc81a2b268103b9a7f8bc5c61d11,3797
-minitap_mobile_use-2.7.2.dist-info/WHEEL,sha256=ab6157bc637547491fb4567cd7ddf26b04d63382916ca16c29a5c8e94c9c9ef7,79
-minitap_mobile_use-2.7.2.dist-info/entry_points.txt,sha256=663a29cfd551a4eaa0f27335f0bd7e4a732a4e39c76b68ef5c8dc444d4a285fa,60
-minitap_mobile_use-2.7.2.dist-info/METADATA,sha256=5d363ea1b75c0ae699cf85b94fa2ccb86b97af30dc3f382638e4c3f907bda627,11995
-minitap_mobile_use-2.7.2.dist-info/RECORD,,
+minitap_mobile_use-2.8.0.dist-info/WHEEL,sha256=ab6157bc637547491fb4567cd7ddf26b04d63382916ca16c29a5c8e94c9c9ef7,79
+minitap_mobile_use-2.8.0.dist-info/entry_points.txt,sha256=663a29cfd551a4eaa0f27335f0bd7e4a732a4e39c76b68ef5c8dc444d4a285fa,60
+minitap_mobile_use-2.8.0.dist-info/METADATA,sha256=d1131fea7bfc7ac26bd51ee3266dae6191ffefffde7e8193043059dd6dd40ee3,11995
+minitap_mobile_use-2.8.0.dist-info/RECORD,,