mobilerun-core-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{mobilerun_core_cli-0.1.0 → mobilerun_core_cli-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mobilerun-core-cli
-Version: 0.1.0
-Summary: Slim async Portal client + Android device driver, extracted from mobilerun.
+Version: 0.2.0
+Summary: Slim async local device drivers for Android Portal and iOS Portal, extracted from mobilerun.
 Project-URL: Homepage, https://github.com/droidrun/mobilerun-core-cli
 Project-URL: Repository, https://github.com/droidrun/mobilerun-core-cli
 Project-URL: Bug Tracker, https://github.com/droidrun/mobilerun-core-cli/issues
@@ -33,8 +33,8 @@ Description-Content-Type: text/markdown
 </picture>
 
 <p align="center">
-  <strong>mobilerun-core-cli is the slim async Portal + Android device driver core of <a href="https://github.com/droidrun/mobilerun">mobilerun</a>.</strong><br>
-  No CLI, no agent, no LLM providers — just enough to drive a real Android device through the Mobilerun Portal app over ADB. Intended as an embedding library for higher-level tools.
+  <strong>mobilerun-core-cli is the slim async local-driver core of <a href="https://github.com/droidrun/mobilerun">mobilerun</a>.</strong><br>
+  No CLI, no agent, no LLM providers — just local Android/iOS drivers for higher-level tools such as <code>mobilerun-core</code>.
 </p>
 
 <div align="center">
@@ -54,16 +54,17 @@ Description-Content-Type: text/markdown
 
 ---
 
-- 📱 Drive a real Android device — `tap`, `swipe`, `type`, `screenshot`, `get_ui_tree`, `start_app`, `install_app`, …
-- ⚡ TCP-with-content-provider fallback — fast HTTP path over `adb forward`, transparent fallback to content-provider RPC.
+- 📱 Drive local devices — Android over ADB+Portal, Android Portal HTTP-only, or iOS Portal HTTP.
+- ⚡ TCP-with-content-provider fallback — fast Android HTTP path over `adb forward`, transparent fallback to content-provider RPC.
+- 🔌 HTTP-only drivers — connect to already-running Android/iOS portals without taking over setup.
 - 🛠 Portal lifecycle — download, install, accessibility enablement, auto-upgrade.
-- 🪶 Slim — four files, four runtime deps (`async_adbutils`, `httpx`, `requests`, `rich`).
+- 🪶 Slim — a small async driver package with four runtime deps (`async_adbutils`, `httpx`, `requests`, `rich`).
 - 🔌 Embeddable — designed to be wrapped by sync facades (e.g. `mobilerun-core`) or used directly.
 - 🤝 In sync with upstream — verbatim slice of [`droidrun/mobilerun`](https://github.com/droidrun/mobilerun); behaviour and API track upstream.
 
 ## 📦 Installation
 
-> **Note:** Python `>=3.11,<3.14`. Requires [ADB](https://developer.android.com/studio/releases/platform-tools) on `PATH` and a device with USB debugging enabled.
+> **Note:** Python `>=3.11,<3.14`. The Android ADB driver requires [ADB](https://developer.android.com/studio/releases/platform-tools) on `PATH` and a device with USB debugging enabled. HTTP-only drivers require an already-running portal URL.
 
 ```bash
 uv pip install mobilerun-core-cli
@@ -93,6 +94,41 @@ async def main():
     tree = await driver.get_ui_tree()
 
 
+asyncio.run(main())
+```
+
+HTTP-only Android:
+
+```python
+import asyncio
+from mobilerun_core_cli import AndroidPortalHttpDriver
+
+
+async def main():
+    driver = AndroidPortalHttpDriver(
+        url="http://127.0.0.1:18080",
+        token="...",
+    )
+    await driver.connect()
+    await driver.tap(540, 1200)
+
+
+asyncio.run(main())
+```
+
+iOS Portal:
+
+```python
+import asyncio
+from mobilerun_core_cli import IOSPortalDriver
+
+
+async def main():
+    driver = IOSPortalDriver("http://127.0.0.1:6643")
+    await driver.connect()
+    await driver.start_app("com.apple.Preferences")
+
+
 asyncio.run(main())
 ```
 
@@ -104,7 +140,9 @@ mobilerun_core_cli/
 ├── portal.py              Portal APK lifecycle + content-provider helpers
 ├── driver/
 │   ├── base.py            DeviceDriver ABC, DeviceDisconnectedError
-│   └── android.py         AndroidDriver — ADB-backed concrete driver
+│   ├── android.py         AndroidDriver — ADB-backed concrete driver
+│   ├── android_http.py    AndroidPortalHttpDriver — HTTP-only Android driver
+│   └── ios.py             IOSPortalDriver — ios-portal HTTP driver
 └── transport/
     └── portal_client.py   PortalClient — TCP-with-content-provider fallback
 ```
@@ -116,6 +154,8 @@ Re-exported from `mobilerun_core_cli`:
 | Symbol | What it is |
 |---|---|
 | `AndroidDriver` | ADB+Portal device driver. Async methods: `tap`, `swipe`, `input_text`, `press_button`, `start_app`, `install_app`, `screenshot`, `get_ui_tree`, `get_apps`, `list_packages`, `get_date`. |
+| `AndroidPortalHttpDriver` | HTTP-only Android Portal driver. Requires `url` and bearer `token`; does not use ADB at runtime. |
+| `IOSPortalDriver` / `IOSDriver` | iOS Portal HTTP driver. Requires an already-running `ios-portal` URL. |
 | `DeviceDriver` | Abstract base for drivers. `supported: set[str]` declares which verbs a subclass implements. |
 | `DeviceDisconnectedError` | Raised when the device drops mid-call. |
 | `PortalClient` | HTTP-or-content-provider client for the on-device Portal. Used internally by `AndroidDriver`; can be constructed directly for low-level access. |
@@ -144,9 +184,9 @@ logging.getLogger("mobilerun_core_cli").setLevel(logging.DEBUG)
 
 ## 🔗 Relationship to upstream `mobilerun`
 
-This package is a verbatim slice of the upstream framework's Android driver + Portal modules, with imports rewritten under `mobilerun_core_cli` and loggers renamed. It tracks the upstream API for those four files; new features (iOS driver, recording driver, cloud driver, agent/CLI) stay upstream.
+This package owns local execution drivers. The full framework imports these drivers for CLI/agent flows; `mobilerun-core` wraps them behind a sync, backend-neutral API.
 
-Use `mobilerun-core-cli` when you only need to drive a real Android device and want to keep the dependency footprint small.
+Use `mobilerun-core-cli` when you need async local drivers directly.
 Use [`mobilerun`](https://github.com/droidrun/mobilerun) when you want the full LLM-agent experience, CLI/TUI, and multi-platform support out of the box.
 
 ## 📄 License

{mobilerun_core_cli-0.1.0 → mobilerun_core_cli-0.2.0}/README.md

@@ -5,8 +5,8 @@
 </picture>
 
 <p align="center">
-  <strong>mobilerun-core-cli is the slim async Portal + Android device driver core of <a href="https://github.com/droidrun/mobilerun">mobilerun</a>.</strong><br>
-  No CLI, no agent, no LLM providers — just enough to drive a real Android device through the Mobilerun Portal app over ADB. Intended as an embedding library for higher-level tools.
+  <strong>mobilerun-core-cli is the slim async local-driver core of <a href="https://github.com/droidrun/mobilerun">mobilerun</a>.</strong><br>
+  No CLI, no agent, no LLM providers — just local Android/iOS drivers for higher-level tools such as <code>mobilerun-core</code>.
 </p>
 
 <div align="center">
@@ -26,16 +26,17 @@
 
 ---
 
-- 📱 Drive a real Android device — `tap`, `swipe`, `type`, `screenshot`, `get_ui_tree`, `start_app`, `install_app`, …
-- ⚡ TCP-with-content-provider fallback — fast HTTP path over `adb forward`, transparent fallback to content-provider RPC.
+- 📱 Drive local devices — Android over ADB+Portal, Android Portal HTTP-only, or iOS Portal HTTP.
+- ⚡ TCP-with-content-provider fallback — fast Android HTTP path over `adb forward`, transparent fallback to content-provider RPC.
+- 🔌 HTTP-only drivers — connect to already-running Android/iOS portals without taking over setup.
 - 🛠 Portal lifecycle — download, install, accessibility enablement, auto-upgrade.
-- 🪶 Slim — four files, four runtime deps (`async_adbutils`, `httpx`, `requests`, `rich`).
+- 🪶 Slim — a small async driver package with four runtime deps (`async_adbutils`, `httpx`, `requests`, `rich`).
 - 🔌 Embeddable — designed to be wrapped by sync facades (e.g. `mobilerun-core`) or used directly.
 - 🤝 In sync with upstream — verbatim slice of [`droidrun/mobilerun`](https://github.com/droidrun/mobilerun); behaviour and API track upstream.
 
 ## 📦 Installation
 
-> **Note:** Python `>=3.11,<3.14`. Requires [ADB](https://developer.android.com/studio/releases/platform-tools) on `PATH` and a device with USB debugging enabled.
+> **Note:** Python `>=3.11,<3.14`. The Android ADB driver requires [ADB](https://developer.android.com/studio/releases/platform-tools) on `PATH` and a device with USB debugging enabled. HTTP-only drivers require an already-running portal URL.
 
 ```bash
 uv pip install mobilerun-core-cli
@@ -65,6 +66,41 @@ async def main():
     tree = await driver.get_ui_tree()
 
 
+asyncio.run(main())
+```
+
+HTTP-only Android:
+
+```python
+import asyncio
+from mobilerun_core_cli import AndroidPortalHttpDriver
+
+
+async def main():
+    driver = AndroidPortalHttpDriver(
+        url="http://127.0.0.1:18080",
+        token="...",
+    )
+    await driver.connect()
+    await driver.tap(540, 1200)
+
+
+asyncio.run(main())
+```
+
+iOS Portal:
+
+```python
+import asyncio
+from mobilerun_core_cli import IOSPortalDriver
+
+
+async def main():
+    driver = IOSPortalDriver("http://127.0.0.1:6643")
+    await driver.connect()
+    await driver.start_app("com.apple.Preferences")
+
+
 asyncio.run(main())
 ```
 
@@ -76,7 +112,9 @@ mobilerun_core_cli/
 ├── portal.py              Portal APK lifecycle + content-provider helpers
 ├── driver/
 │   ├── base.py            DeviceDriver ABC, DeviceDisconnectedError
-│   └── android.py         AndroidDriver — ADB-backed concrete driver
+│   ├── android.py         AndroidDriver — ADB-backed concrete driver
+│   ├── android_http.py    AndroidPortalHttpDriver — HTTP-only Android driver
+│   └── ios.py             IOSPortalDriver — ios-portal HTTP driver
 └── transport/
     └── portal_client.py   PortalClient — TCP-with-content-provider fallback
 ```
@@ -88,6 +126,8 @@ Re-exported from `mobilerun_core_cli`:
 | Symbol | What it is |
 |---|---|
 | `AndroidDriver` | ADB+Portal device driver. Async methods: `tap`, `swipe`, `input_text`, `press_button`, `start_app`, `install_app`, `screenshot`, `get_ui_tree`, `get_apps`, `list_packages`, `get_date`. |
+| `AndroidPortalHttpDriver` | HTTP-only Android Portal driver. Requires `url` and bearer `token`; does not use ADB at runtime. |
+| `IOSPortalDriver` / `IOSDriver` | iOS Portal HTTP driver. Requires an already-running `ios-portal` URL. |
 | `DeviceDriver` | Abstract base for drivers. `supported: set[str]` declares which verbs a subclass implements. |
 | `DeviceDisconnectedError` | Raised when the device drops mid-call. |
 | `PortalClient` | HTTP-or-content-provider client for the on-device Portal. Used internally by `AndroidDriver`; can be constructed directly for low-level access. |
@@ -116,9 +156,9 @@ logging.getLogger("mobilerun_core_cli").setLevel(logging.DEBUG)
 
 ## 🔗 Relationship to upstream `mobilerun`
 
-This package is a verbatim slice of the upstream framework's Android driver + Portal modules, with imports rewritten under `mobilerun_core_cli` and loggers renamed. It tracks the upstream API for those four files; new features (iOS driver, recording driver, cloud driver, agent/CLI) stay upstream.
+This package owns local execution drivers. The full framework imports these drivers for CLI/agent flows; `mobilerun-core` wraps them behind a sync, backend-neutral API.
 
-Use `mobilerun-core-cli` when you only need to drive a real Android device and want to keep the dependency footprint small.
+Use `mobilerun-core-cli` when you need async local drivers directly.
 Use [`mobilerun`](https://github.com/droidrun/mobilerun) when you want the full LLM-agent experience, CLI/TUI, and multi-platform support out of the box.
 
 ## 📄 License

{mobilerun_core_cli-0.1.0 → mobilerun_core_cli-0.2.0}/mobilerun_core_cli/__init__.py

@@ -1,9 +1,19 @@
 """Slim async Portal+driver core, extracted from droidrun/mobilerun."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from mobilerun_core_cli.driver.android import AndroidDriver
+from mobilerun_core_cli.driver.android_http import (
+    AndroidPortalHttpDriver,
+    validate_android_portal_url,
+)
 from mobilerun_core_cli.driver.base import DeviceDisconnectedError, DeviceDriver
+from mobilerun_core_cli.driver.ios import (
+    IOSDriver,
+    IOSPortalDriver,
+    discover_ios_portal,
+    validate_ios_portal_url,
+)
 from mobilerun_core_cli.portal import (
     A11Y_SERVICE_NAME,
     PORTAL_PACKAGE_NAME,
@@ -19,8 +29,14 @@ from mobilerun_core_cli.transport.portal_client import PortalClient
 
 __all__ = [
     "AndroidDriver",
+    "AndroidPortalHttpDriver",
     "DeviceDriver",
     "DeviceDisconnectedError",
+    "IOSDriver",
+    "IOSPortalDriver",
+    "discover_ios_portal",
+    "validate_android_portal_url",
+    "validate_ios_portal_url",
     "PortalClient",
     "PORTAL_PACKAGE_NAME",
     "A11Y_SERVICE_NAME",

mobilerun_core_cli-0.2.0/mobilerun_core_cli/driver/__init__.py

@@ -0,0 +1,24 @@
+from mobilerun_core_cli.driver.android import AndroidDriver
+from mobilerun_core_cli.driver.android_http import (
+    AndroidPortalHttpDriver,
+    validate_android_portal_url,
+)
+from mobilerun_core_cli.driver.base import DeviceDisconnectedError, DeviceDriver
+from mobilerun_core_cli.driver.ios import (
+    IOSDriver,
+    IOSPortalDriver,
+    discover_ios_portal,
+    validate_ios_portal_url,
+)
+
+__all__ = [
+    "AndroidDriver",
+    "AndroidPortalHttpDriver",
+    "DeviceDriver",
+    "DeviceDisconnectedError",
+    "IOSDriver",
+    "IOSPortalDriver",
+    "discover_ios_portal",
+    "validate_android_portal_url",
+    "validate_ios_portal_url",
+]

{mobilerun_core_cli-0.1.0 → mobilerun_core_cli-0.2.0}/mobilerun_core_cli/driver/android.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import asyncio
 import logging
 import os
+import shlex
 from typing import Any, Dict, List, Optional
 
 from async_adbutils import adb
@@ -38,7 +39,9 @@ class AndroidDriver(DeviceDriver):
         "get_apps",
         "list_packages",
         "install_app",
-        "drag",
+        "stop_app",
+        "uninstall_app",
+        "press_key_code",
     }
 
     supported_buttons = {"back", "home", "enter"}
@@ -115,7 +118,11 @@ class AndroidDriver(DeviceDriver):
                 f"Button '{button}' not supported. "
                 f"Supported: {', '.join(sorted(self.supported_buttons))}"
             )
-        await self.device.keyevent(self._BUTTON_KEYCODES[button_lower])
+        await self.press_key_code(self._BUTTON_KEYCODES[button_lower])
+
+    async def press_key_code(self, key_code: int) -> None:
+        await self.ensure_connected()
+        await self.device.keyevent(int(key_code))
 
     async def drag(
         self,
@@ -132,20 +139,34 @@ class AndroidDriver(DeviceDriver):
 
     async def start_app(self, package: str, activity: Optional[str] = None) -> str:
         await self.ensure_connected()
-        try:
-            logger.debug(f"Starting app {package} with activity {activity}")
+        logger.debug(f"Starting app {package} with activity {activity}")
+        if not activity:
+            dumpsys_output = await self.device.shell(
+                f"cmd package resolve-activity --brief {shlex.quote(package)}"
+            )
+            component = next(
+                (
+                    line.strip()
+                    for line in reversed(dumpsys_output.splitlines())
+                    if "/" in line
+                ),
+                None,
+            )
+            if not component:
+                detail = dumpsys_output.strip() or "<empty>"
+                raise RuntimeError(
+                    f"Could not resolve launch activity for {package}: {detail}"
+                )
+            activity = component.split("/", 1)[1].strip()
             if not activity:
-                dumpsys_output = await self.device.shell(
-                    f"cmd package resolve-activity --brief {package}"
+                raise RuntimeError(
+                    f"Could not resolve launch activity for {package}: {component}"
                 )
-                activity = dumpsys_output.splitlines()[1].split("/")[1]
 
-            logger.debug(f"Activity: {activity}")
-            await self.device.app_start(package, activity)
-            logger.debug(f"App started: {package} with activity {activity}")
-            return f"App started: {package} with activity {activity}"
-        except Exception as e:
-            return f"Failed to start app {package}: {e}"
+        logger.debug(f"Activity: {activity}")
+        await self.device.app_start(package, activity)
+        logger.debug(f"App started: {package} with activity {activity}")
+        return f"App started: {package} with activity {activity}"
 
     async def install_app(self, path: str, **kwargs) -> str:
         await self.ensure_connected()
@@ -169,6 +190,16 @@ class AndroidDriver(DeviceDriver):
         logger.debug(f"Installed app: {path} with result: {result}")
         return result
 
+    async def stop_app(self, package: str) -> str:
+        await self.ensure_connected()
+        await self.device.shell(f"am force-stop {shlex.quote(package)}")
+        return f"Stopped {package}"
+
+    async def uninstall_app(self, package: str) -> str:
+        await self.ensure_connected()
+        result = await self.device.shell(f"pm uninstall {shlex.quote(package)}")
+        return result.strip() or f"Uninstalled {package}"
+
     async def get_apps(self, include_system: bool = True) -> List[Dict[str, str]]:
         await self.ensure_connected()
         return await self.portal.get_apps(include_system)

mobilerun_core_cli-0.2.0/mobilerun_core_cli/driver/android_http.py

@@ -0,0 +1,272 @@
+"""Android Portal HTTP-only driver.
+
+This backend talks to a running Mobilerun Portal HTTP server with an
+explicit bearer token. It deliberately does not use ADB: setup, token
+retrieval, port forwarding, and APK installation belong to the ADB-backed
+driver or external provisioning.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlparse
+
+import httpx
+
+from mobilerun_core_cli.driver.base import DeviceDriver
+
+logger = logging.getLogger("mobilerun_core_cli")
+
+
+_ANDROID_KEY_CODES = {
+    "back": 4,
+    "home": 3,
+    "menu": 82,
+    "enter": 66,
+    "delete": 67,
+    "escape": 111,
+    "tab": 61,
+    "space": 62,
+    "search": 84,
+    "page_up": 92,
+    "page_down": 93,
+    "volume_up": 24,
+    "volume_down": 25,
+    "power": 26,
+    "media_play_pause": 85,
+    "media_next": 87,
+    "media_prev": 88,
+}
+
+
+def validate_android_portal_url(url: str) -> str:
+    """Validate and normalize an Android Portal HTTP base URL."""
+    normalized = url.rstrip("/")
+    parsed = urlparse(normalized)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ValueError(
+            "Android HTTP device must be the portal base URL, "
+            "e.g. http://127.0.0.1:8080"
+        )
+    return normalized
+
+
+class AndroidPortalHttpDriver(DeviceDriver):
+    """Android device driver for Portal HTTP without ADB."""
+
+    platform = "Android"
+
+    supported = {
+        "tap",
+        "swipe",
+        "input_text",
+        "press_button",
+        "press_key_code",
+        "start_app",
+        "stop_app",
+        "screenshot",
+        "get_ui_tree",
+        "get_apps",
+        "list_packages",
+    }
+
+    supported_buttons = set(_ANDROID_KEY_CODES)
+
+    def __init__(
+        self,
+        url: str,
+        token: str,
+        *,
+        timeout: float = 30.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not token:
+            raise ValueError("Android Portal HTTP requires a non-empty auth token")
+        self.url = validate_android_portal_url(url)
+        self.token = token
+        self.timeout = timeout
+        self.transport = transport
+        self._client: httpx.AsyncClient | None = None
+        self._connected = False
+
+    # -- lifecycle ---------------------------------------------------------
+
+    async def connect(self) -> None:
+        if self._connected:
+            return
+        self._client = httpx.AsyncClient(
+            base_url=self.url,
+            timeout=self.timeout,
+            headers={"Authorization": f"Bearer {self.token}"},
+            transport=self.transport,
+        )
+        try:
+            response = await self._client.get("/version")
+            if response.status_code in {401, 403}:
+                raise PermissionError(
+                    "Android Portal HTTP authentication failed; check the bearer token"
+                )
+            response.raise_for_status()
+        except PermissionError:
+            await self._client.aclose()
+            self._client = None
+            raise
+        except Exception as exc:
+            await self._client.aclose()
+            self._client = None
+            raise ConnectionError(
+                f"Could not connect to Android Portal HTTP at {self.url}"
+            ) from exc
+        self._connected = True
+        logger.info("Connected to Android Portal HTTP at %s", self.url)
+
+    async def ensure_connected(self) -> None:
+        if not self._connected:
+            await self.connect()
+
+    @property
+    def _http(self) -> httpx.AsyncClient:
+        if self._client is None:
+            raise ConnectionError("AndroidPortalHttpDriver is not connected")
+        return self._client
+
+    # -- helpers -----------------------------------------------------------
+
+    @staticmethod
+    def _unwrap_json(data: Any) -> Any:
+        if isinstance(data, dict):
+            status = data.get("status")
+            if status == "error":
+                message = data.get("message") or data.get("error") or data
+                raise RuntimeError(f"Portal returned error: {message}")
+            inner_key = "result" if "result" in data else "data" if "data" in data else None
+            if inner_key is not None:
+                inner = data[inner_key]
+                if isinstance(inner, str):
+                    try:
+                        return json.loads(inner)
+                    except json.JSONDecodeError:
+                        return inner
+                return inner
+        return data
+
+    @classmethod
+    def _unwrap_response(cls, response: httpx.Response) -> Any:
+        response.raise_for_status()
+        if not response.content:
+            return None
+        try:
+            return cls._unwrap_json(response.json())
+        except json.JSONDecodeError:
+            return response.content
+
+    async def _post(self, path: str, payload: dict[str, Any]) -> Any:
+        await self.ensure_connected()
+        return self._unwrap_response(await self._http.post(path, json=payload))
+
+    # -- input actions -----------------------------------------------------
+
+    async def tap(self, x: int, y: int) -> None:
+        await self._post("/tap", {"x": int(x), "y": int(y)})
+
+    async def swipe(
+        self,
+        x1: int,
+        y1: int,
+        x2: int,
+        y2: int,
+        duration_ms: float = 1000,
+    ) -> None:
+        await self._post(
+            "/swipe",
+            {
+                "startX": int(x1),
+                "startY": int(y1),
+                "endX": int(x2),
+                "endY": int(y2),
+                "duration": float(duration_ms),
+            },
+        )
+
+    async def input_text(
+        self,
+        text: str,
+        clear: bool = False,
+        stealth: bool = False,
+        wpm: int = 0,
+    ) -> bool:
+        encoded = base64.b64encode(text.encode()).decode("ascii")
+        await self._post("/keyboard/input", {"base64_text": encoded, "clear": clear})
+        return True
+
+    async def press_button(self, button: str) -> None:
+        button_lower = button.lower()
+        if button_lower not in self.supported_buttons:
+            raise ValueError(
+                f"Button '{button}' not supported. "
+                f"Supported: {', '.join(sorted(self.supported_buttons))}"
+            )
+        await self.press_key_code(_ANDROID_KEY_CODES[button_lower])
+
+    async def press_key_code(self, key_code: int) -> None:
+        await self._post("/keyboard/key", {"key_code": int(key_code)})
+
+    # -- app management ----------------------------------------------------
+
+    async def start_app(self, package: str, activity: Optional[str] = None) -> str:
+        payload = {"package": package}
+        if activity:
+            payload["activity"] = activity
+        await self._post("/app", payload)
+        return f"Started {package}"
+
+    async def stop_app(self, package: str) -> str:
+        await self._post("/app/stop", {"package": package})
+        return f"Stopped {package}"
+
+    async def get_apps(self, include_system: bool = True) -> List[Dict[str, str]]:
+        await self.ensure_connected()
+        data = self._unwrap_response(await self._http.get("/packages"))
+        if isinstance(data, dict) and "packages" in data:
+            data = data["packages"]
+        if not isinstance(data, list):
+            return []
+
+        apps: list[dict[str, str]] = []
+        for app in data:
+            if not isinstance(app, dict):
+                continue
+            if not include_system and app.get("isSystemApp", False):
+                continue
+            package = app.get("packageName") or app.get("package") or ""
+            label = app.get("label") or package
+            apps.append({"package": package, "label": label})
+        return apps
+
+    async def list_packages(self, include_system: bool = False) -> List[str]:
+        apps = await self.get_apps(include_system=include_system)
+        return [app["package"] for app in apps if app.get("package")]
+
+    # -- state / observation ----------------------------------------------
+
+    async def screenshot(self, hide_overlay: bool = True) -> bytes:
+        await self.ensure_connected()
+        params = {"hideOverlay": "true" if hide_overlay else "false"}
+        response = await self._http.get("/screenshot", params=params)
+        response.raise_for_status()
+        content_type = response.headers.get("content-type", "")
+        if "image/" in content_type or response.content.startswith(b"\x89PNG"):
+            return response.content
+
+        data = self._unwrap_response(response)
+        if isinstance(data, str):
+            return base64.b64decode(data)
+        raise ValueError("Invalid screenshot response from Android Portal HTTP")
+
+    async def get_ui_tree(self) -> Dict[str, Any]:
+        await self.ensure_connected()
+        data = self._unwrap_response(await self._http.get("/state_full"))
+        return data if isinstance(data, dict) else {}

{mobilerun_core_cli-0.1.0 → mobilerun_core_cli-0.2.0}/mobilerun_core_cli/driver/base.py

@@ -76,6 +76,10 @@ class DeviceDriver:
         """
         raise NotImplementedError
 
+    async def press_key_code(self, key_code: int) -> None:
+        """Press a platform-native integer key code."""
+        raise NotImplementedError
+
     async def drag(
         self,
         x1: int,
@@ -100,6 +104,14 @@ class DeviceDriver:
         """Install an APK/IPA at *path*."""
         raise NotImplementedError
 
+    async def stop_app(self, package: str) -> str:
+        """Stop a running application."""
+        raise NotImplementedError
+
+    async def uninstall_app(self, package: str) -> str:
+        """Uninstall an application."""
+        raise NotImplementedError
+
     async def get_apps(self, include_system: bool = True) -> List[Dict[str, str]]:
         """Return installed apps as ``[{"package": …, "label": …}, …]``."""
         raise NotImplementedError