droidrun-agent 0.1.1__tar.gz

droidrun_agent-0.1.1/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.3
+Name: droidrun-agent
+Version: 0.1.1
+Summary: Add your description here
+Author: 涵曦
+Author-email: 涵曦 <im.hanxi@gmail.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: websockets>=12.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# [droidrun-agent](https://github.com/hanxi/droidrun-agent)
+
+[![PyPI version](https://img.shields.io/pypi/v/droidrun-agent)](https://pypi.org/project/droidrun-agent/)
+[![Python](https://img.shields.io/pypi/pyversions/droidrun-agent)](https://pypi.org/project/droidrun-agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Async Python client for the [DroidRun Portal](https://github.com/droidrun/droidrun-portal) local API. Provides both HTTP and WebSocket clients to control Android devices through Portal's accessibility service.
+
+## Features
+
+- **HTTP Client** (`PortalHTTPClient`) - Communicates with Portal's HTTP server (default port 8080)
+- **WebSocket Client** (`PortalWSClient`) - Communicates with Portal's WebSocket server (default port 8081) using JSON-RPC style messages
+- Bearer token authentication
+- Async context manager support (`async with`)
+- Automatic reconnection for WebSocket client
+- Full type hints
+
+## Installation
+
+```bash
+pip install droidrun-agent
+```
+
+Or install from source using [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/hanxi/droidrun-agent.git
+cd droidrun-agent
+uv sync
+```
+
+## Quick Start
+
+### HTTP Client
+
+```python
+import asyncio
+from droidrun_agent import PortalHTTPClient
+
+async def main():
+    async with PortalHTTPClient("http://192.168.1.100:8080", token="YOUR_TOKEN") as client:
+        # Health check (no auth required)
+        await client.ping()
+
+        # Get device UI state
+        state = await client.get_state_full()
+        print(state)
+
+        # Tap on screen coordinates
+        await client.tap(200, 400)
+
+        # Take a screenshot (returns PNG bytes)
+        png_data = await client.take_screenshot()
+        with open("screenshot.png", "wb") as f:
+            f.write(png_data)
+
+asyncio.run(main())
+```
+
+### WebSocket Client
+
+```python
+import asyncio
+from droidrun_agent import PortalWSClient
+
+async def main():
+    async with PortalWSClient("ws://192.168.1.100:8081", token="YOUR_TOKEN") as ws:
+        # Tap on screen coordinates
+        await ws.tap(200, 400)
+
+        # Get device state
+        state = await ws.get_state()
+        print(state)
+
+        # Take a screenshot (returns PNG bytes)
+        png_data = await ws.take_screenshot()
+        with open("screenshot.png", "wb") as f:
+            f.write(png_data)
+
+        # Install APK from URL (WebSocket only)
+        await ws.install(["https://example.com/app.apk"])
+
+asyncio.run(main())
+```
+
+## Documentation
+
+For detailed API documentation of the DroidRun Portal local API, see:
+- [Local API Documentation](https://github.com/droidrun/droidrun-portal/blob/main/docs/local-api.md)
+
+## API Reference
+
+### PortalHTTPClient
+
+| Method | Description |
+|---|---|
+| `ping()` | Health check (no auth required) |
+| `get_a11y_tree()` | Get simplified accessibility tree |
+| `get_a11y_tree_full(filter=True)` | Get full accessibility tree |
+| `get_state()` | Get simplified UI state |
+| `get_state_full(filter=True)` | Get full UI state (a11y tree + phone state) |
+| `get_phone_state()` | Get phone state info |
+| `get_version()` | Get Portal app version string |
+| `get_packages()` | Get list of launchable packages |
+| `take_screenshot(hide_overlay=True)` | Take device screenshot, returns PNG bytes |
+| `tap(x, y)` | Tap screen coordinates |
+| `swipe(start_x, start_y, end_x, end_y, duration=None)` | Swipe gesture |
+| `global_action(action)` | Execute accessibility global action |
+| `start_app(package, activity=None, stop_before_launch=False)` | Launch an app |
+| `stop_app(package)` | Stop an app |
+| `input_text(text, clear=True)` | Input text via Portal keyboard |
+| `clear_input()` | Clear focused input field |
+| `press_key(key_code)` | Send an Android key code |
+| `set_overlay_offset(offset)` | Set overlay vertical offset in pixels |
+| `set_socket_port(port)` | Update the HTTP server port |
+
+### PortalWSClient
+
+Supports all methods from HTTP client, plus:
+
+| Method | Description |
+|---|---|
+| `get_time()` | Get device Unix timestamp in milliseconds |
+| `install(urls, hide_overlay=True)` | Install APK(s) from URL(s), supports split APKs |
+
+### Exceptions
+
+| Exception | Description |
+|---|---|
+| `PortalError` | Base exception for all Portal client errors |
+| `PortalConnectionError` | Failed to connect to Portal server |
+| `PortalAuthError` | Authentication failed (invalid or missing token) |
+| `PortalTimeoutError` | Request timed out |
+| `PortalResponseError` | Server returned an unexpected or error response |
+
+## Requirements
+
+- Python >= 3.11
+- [httpx](https://www.python-httpx.org/) >= 0.28.1
+- [websockets](https://websockets.readthedocs.io/) >= 12.0
+
+## Development Workflow
+
+This project uses [uv](https://docs.astral.sh/uv/) for development. Here are the common development commands:
+
+### Code Formatting
+
+```bash
+# Format all Python code
+uv format
+
+# Check formatting without making changes
+uv format --check
+```
+
+### Code Quality
+
+```bash
+# Run code quality checks
+uv run ruff check .
+
+# Automatically fix fixable issues
+uv run ruff check --fix .
+```
+
+### Testing
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run tests with verbose output
+uv run pytest -v
+
+# Run tests and show coverage
+uv run pytest --cov=src
+```
+
+### Dependency Management
+
+```bash
+# Install development dependencies
+uv sync --group dev
+
+# Add a new dependency
+uv add package_name
+
+# Add a development dependency
+uv add --group dev package_name
+
+# Remove a dependency
+uv remove package_name
+```
+
+### Complete Development Flow
+
+```bash
+# 1. Format code
+uv format
+
+# 2. Check code quality
+uv run ruff check .
+
+# 3. Run tests
+uv run pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

droidrun_agent-0.1.1/README.md

@@ -0,0 +1,210 @@
+# [droidrun-agent](https://github.com/hanxi/droidrun-agent)
+
+[![PyPI version](https://img.shields.io/pypi/v/droidrun-agent)](https://pypi.org/project/droidrun-agent/)
+[![Python](https://img.shields.io/pypi/pyversions/droidrun-agent)](https://pypi.org/project/droidrun-agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Async Python client for the [DroidRun Portal](https://github.com/droidrun/droidrun-portal) local API. Provides both HTTP and WebSocket clients to control Android devices through Portal's accessibility service.
+
+## Features
+
+- **HTTP Client** (`PortalHTTPClient`) - Communicates with Portal's HTTP server (default port 8080)
+- **WebSocket Client** (`PortalWSClient`) - Communicates with Portal's WebSocket server (default port 8081) using JSON-RPC style messages
+- Bearer token authentication
+- Async context manager support (`async with`)
+- Automatic reconnection for WebSocket client
+- Full type hints
+
+## Installation
+
+```bash
+pip install droidrun-agent
+```
+
+Or install from source using [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/hanxi/droidrun-agent.git
+cd droidrun-agent
+uv sync
+```
+
+## Quick Start
+
+### HTTP Client
+
+```python
+import asyncio
+from droidrun_agent import PortalHTTPClient
+
+async def main():
+    async with PortalHTTPClient("http://192.168.1.100:8080", token="YOUR_TOKEN") as client:
+        # Health check (no auth required)
+        await client.ping()
+
+        # Get device UI state
+        state = await client.get_state_full()
+        print(state)
+
+        # Tap on screen coordinates
+        await client.tap(200, 400)
+
+        # Take a screenshot (returns PNG bytes)
+        png_data = await client.take_screenshot()
+        with open("screenshot.png", "wb") as f:
+            f.write(png_data)
+
+asyncio.run(main())
+```
+
+### WebSocket Client
+
+```python
+import asyncio
+from droidrun_agent import PortalWSClient
+
+async def main():
+    async with PortalWSClient("ws://192.168.1.100:8081", token="YOUR_TOKEN") as ws:
+        # Tap on screen coordinates
+        await ws.tap(200, 400)
+
+        # Get device state
+        state = await ws.get_state()
+        print(state)
+
+        # Take a screenshot (returns PNG bytes)
+        png_data = await ws.take_screenshot()
+        with open("screenshot.png", "wb") as f:
+            f.write(png_data)
+
+        # Install APK from URL (WebSocket only)
+        await ws.install(["https://example.com/app.apk"])
+
+asyncio.run(main())
+```
+
+## Documentation
+
+For detailed API documentation of the DroidRun Portal local API, see:
+- [Local API Documentation](https://github.com/droidrun/droidrun-portal/blob/main/docs/local-api.md)
+
+## API Reference
+
+### PortalHTTPClient
+
+| Method | Description |
+|---|---|
+| `ping()` | Health check (no auth required) |
+| `get_a11y_tree()` | Get simplified accessibility tree |
+| `get_a11y_tree_full(filter=True)` | Get full accessibility tree |
+| `get_state()` | Get simplified UI state |
+| `get_state_full(filter=True)` | Get full UI state (a11y tree + phone state) |
+| `get_phone_state()` | Get phone state info |
+| `get_version()` | Get Portal app version string |
+| `get_packages()` | Get list of launchable packages |
+| `take_screenshot(hide_overlay=True)` | Take device screenshot, returns PNG bytes |
+| `tap(x, y)` | Tap screen coordinates |
+| `swipe(start_x, start_y, end_x, end_y, duration=None)` | Swipe gesture |
+| `global_action(action)` | Execute accessibility global action |
+| `start_app(package, activity=None, stop_before_launch=False)` | Launch an app |
+| `stop_app(package)` | Stop an app |
+| `input_text(text, clear=True)` | Input text via Portal keyboard |
+| `clear_input()` | Clear focused input field |
+| `press_key(key_code)` | Send an Android key code |
+| `set_overlay_offset(offset)` | Set overlay vertical offset in pixels |
+| `set_socket_port(port)` | Update the HTTP server port |
+
+### PortalWSClient
+
+Supports all methods from HTTP client, plus:
+
+| Method | Description |
+|---|---|
+| `get_time()` | Get device Unix timestamp in milliseconds |
+| `install(urls, hide_overlay=True)` | Install APK(s) from URL(s), supports split APKs |
+
+### Exceptions
+
+| Exception | Description |
+|---|---|
+| `PortalError` | Base exception for all Portal client errors |
+| `PortalConnectionError` | Failed to connect to Portal server |
+| `PortalAuthError` | Authentication failed (invalid or missing token) |
+| `PortalTimeoutError` | Request timed out |
+| `PortalResponseError` | Server returned an unexpected or error response |
+
+## Requirements
+
+- Python >= 3.11
+- [httpx](https://www.python-httpx.org/) >= 0.28.1
+- [websockets](https://websockets.readthedocs.io/) >= 12.0
+
+## Development Workflow
+
+This project uses [uv](https://docs.astral.sh/uv/) for development. Here are the common development commands:
+
+### Code Formatting
+
+```bash
+# Format all Python code
+uv format
+
+# Check formatting without making changes
+uv format --check
+```
+
+### Code Quality
+
+```bash
+# Run code quality checks
+uv run ruff check .
+
+# Automatically fix fixable issues
+uv run ruff check --fix .
+```
+
+### Testing
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run tests with verbose output
+uv run pytest -v
+
+# Run tests and show coverage
+uv run pytest --cov=src
+```
+
+### Dependency Management
+
+```bash
+# Install development dependencies
+uv sync --group dev
+
+# Add a new dependency
+uv add package_name
+
+# Add a development dependency
+uv add --group dev package_name
+
+# Remove a dependency
+uv remove package_name
+```
+
+### Complete Development Flow
+
+```bash
+# 1. Format code
+uv format
+
+# 2. Check code quality
+uv run ruff check .
+
+# 3. Run tests
+uv run pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

droidrun_agent-0.1.1/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "droidrun-agent"
+version = "0.1.1"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "涵曦", email = "im.hanxi@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28.1",
+    "websockets>=12.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "black>=24.0.0",
+    "ruff>=0.8.0",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "C",    # mccabe
+    "B",    # flake8-bugbear
+    "UP",   # pyupgrade
+]
+
+[tool.black]
+line-length = 120
+target-version = ['py311']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+    \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+)/
+'''
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

droidrun_agent-0.1.1/src/droidrun_agent/__init__.py

@@ -0,0 +1,21 @@
+"""DroidRun Agent - HTTP and WebSocket clients for Portal local API."""
+
+from .exceptions import (
+    PortalAuthError,
+    PortalConnectionError,
+    PortalError,
+    PortalResponseError,
+    PortalTimeoutError,
+)
+from .http_client import PortalHTTPClient
+from .ws_client import PortalWSClient
+
+__all__ = [
+    "PortalHTTPClient",
+    "PortalWSClient",
+    "PortalError",
+    "PortalConnectionError",
+    "PortalAuthError",
+    "PortalTimeoutError",
+    "PortalResponseError",
+]

droidrun_agent-0.1.1/src/droidrun_agent/exceptions.py

@@ -0,0 +1,23 @@
+"""Portal client exceptions."""
+
+from __future__ import annotations
+
+
+class PortalError(Exception):
+    """Base exception for Portal client errors."""
+
+
+class PortalConnectionError(PortalError):
+    """Failed to connect to Portal server."""
+
+
+class PortalAuthError(PortalError):
+    """Authentication failed (invalid or missing token)."""
+
+
+class PortalTimeoutError(PortalError):
+    """Request timed out."""
+
+
+class PortalResponseError(PortalError):
+    """Server returned an unexpected or error response."""

droidrun_agent-0.1.1/src/droidrun_agent/http_client.py

@@ -0,0 +1,349 @@
+"""
+PortalHTTPClient - Complete HTTP client for DroidRun Portal.
+
+Communicates with Portal's HTTP server (default port 8080) using Bearer token auth.
+Supports all GET and POST endpoints defined in the Portal local API.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+from typing import Any
+
+import httpx
+
+from .exceptions import (
+    PortalAuthError,
+    PortalConnectionError,
+    PortalResponseError,
+    PortalTimeoutError,
+)
+
+logger = logging.getLogger("droidrun_agent")
+
+
+class PortalHTTPClient:
+    """
+    Async HTTP client for DroidRun Portal.
+
+    Usage::
+
+        async with PortalHTTPClient(
+            "http://192.168.1.100:8080", token="TOKEN"
+        ) as client:
+            await client.ping()
+            state = await client.get_state_full()
+            await client.tap(200, 400)
+    """
+
+    def __init__(self, base_url: str, token: str, timeout: float = 10.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._headers = {"Authorization": f"Bearer {token}"}
+        self._client: httpx.AsyncClient | None = None
+
+    async def connect(self) -> None:
+        """Create the underlying HTTP client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=self._headers,
+                timeout=self.timeout,
+            )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> PortalHTTPClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            await self.connect()
+        assert self._client is not None
+        return self._client
+
+    def _unwrap(self, data: dict[str, Any]) -> Any:
+        """Extract value from Portal response envelope
+        (``{result: ...}`` or ``{data: ...}``)."""
+        key = "result" if "result" in data else "data" if "data" in data else None
+        if key is None:
+            return data
+        value = data[key]
+        if isinstance(value, str):
+            try:
+                return json.loads(value)
+            except (json.JSONDecodeError, ValueError):
+                return value
+        return value
+
+    async def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        auth: bool = True,
+        raw: bool = False,
+    ) -> Any:
+        """Send GET request and return parsed response."""
+        client = await self._ensure_client()
+        headers = self._headers if auth else {}
+        try:
+            resp = await client.get(path, params=params, headers=headers)
+        except httpx.ConnectError as exc:
+            raise PortalConnectionError(f"Cannot connect to {self.base_url}{path}: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise PortalTimeoutError(f"GET {path} timed out: {exc}") from exc
+
+        if resp.status_code in (401, 403):
+            raise PortalAuthError(f"Auth failed for GET {path}: HTTP {resp.status_code}")
+        if resp.status_code != 200:
+            raise PortalResponseError(f"GET {path} returned HTTP {resp.status_code}: {resp.text}")
+
+        if raw:
+            return resp.content
+
+        data = resp.json()
+        if isinstance(data, dict):
+            return self._unwrap(data)
+        return data
+
+    async def _post(self, path: str, form: dict[str, Any]) -> Any:
+        """Send POST request with form-encoded body and return parsed response."""
+        client = await self._ensure_client()
+        # Remove None values from form data
+        form_data = {k: v for k, v in form.items() if v is not None}
+        try:
+            resp = await client.post(path, data=form_data)
+        except httpx.ConnectError as exc:
+            raise PortalConnectionError(f"Cannot connect to {self.base_url}{path}: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise PortalTimeoutError(f"POST {path} timed out: {exc}") from exc
+
+        if resp.status_code in (401, 403):
+            raise PortalAuthError(f"Auth failed for POST {path}: HTTP {resp.status_code}")
+        if resp.status_code != 200:
+            raise PortalResponseError(f"POST {path} returned HTTP {resp.status_code}: {resp.text}")
+
+        data = resp.json()
+        if isinstance(data, dict):
+            return self._unwrap(data)
+        return data
+
+    # ------------------------------------------------------------------
+    # GET endpoints
+    # ------------------------------------------------------------------
+
+    async def ping(self) -> dict[str, Any]:
+        """Health check (no auth required)."""
+        return await self._get("/ping", auth=False)
+
+    async def get_a11y_tree(self) -> dict[str, Any]:
+        """Get simplified accessibility tree."""
+        return await self._get("/a11y_tree")
+
+    async def get_a11y_tree_full(self, *, filter: bool = True) -> dict[str, Any]:
+        """Get full accessibility tree. Set filter=False to keep small elements."""
+        params = {"filter": str(filter).lower()}
+        return await self._get("/a11y_tree_full", params=params)
+
+    async def get_state(self) -> dict[str, Any]:
+        """Get simplified UI state."""
+        return await self._get("/state")
+
+    async def get_state_full(self, *, filter: bool = True) -> dict[str, Any]:
+        """Get full UI state (a11y tree + phone state).
+        Set filter=False to keep small elements."""
+        params = {"filter": str(filter).lower()}
+        return await self._get("/state_full", params=params)
+
+    async def get_phone_state(self) -> dict[str, Any]:
+        """Get phone state info."""
+        return await self._get("/phone_state")
+
+    async def get_version(self) -> str:
+        """Get Portal app version string."""
+        result = await self._get("/version")
+        if isinstance(result, str):
+            return result
+        if isinstance(result, dict):
+            return result.get("version", str(result))
+        return str(result)
+
+    async def get_packages(self) -> list[dict[str, Any]]:
+        """Get list of launchable packages."""
+        result = await self._get("/packages")
+        if isinstance(result, list):
+            return result
+        if isinstance(result, dict) and "packages" in result:
+            return result["packages"]
+        return []
+
+    async def take_screenshot(self, *, hide_overlay: bool = True) -> bytes:
+        """
+        Take device screenshot. Returns PNG bytes.
+
+        The HTTP endpoint returns binary PNG directly.
+        Falls back to JSON envelope parsing for compatibility.
+        """
+        params: dict[str, Any] = {}
+        if not hide_overlay:
+            params["hideOverlay"] = "false"
+
+        max_retries = 3
+        for attempt in range(max_retries + 1):
+            client = await self._ensure_client()
+            try:
+                resp = await client.get("/screenshot", params=params)
+            except httpx.ConnectError as exc:
+                raise PortalConnectionError(f"Screenshot connect error: {exc}") from exc
+            except httpx.TimeoutException as exc:
+                raise PortalTimeoutError(f"Screenshot timed out: {exc}") from exc
+
+            if resp.status_code in (401, 403):
+                raise PortalAuthError(f"Screenshot auth failed: HTTP {resp.status_code}")
+            if resp.status_code != 200:
+                error_text = resp.text
+                if "interval too short" in error_text.lower() and attempt < max_retries:
+                    await asyncio.sleep(0.5)
+                    continue
+                raise PortalResponseError(f"Screenshot failed: HTTP {resp.status_code}")
+
+            break
+
+        content_type = resp.headers.get("content-type", "")
+
+        # Binary PNG response (check content-type and magic bytes)
+        if "image/" in content_type or "octet-stream" in content_type:
+            return resp.content
+        if resp.content[:4] == b"\x89PNG":
+            return resp.content
+
+        # JSON envelope with base64 PNG.
+        # NOTE: We intentionally avoid _unwrap() here because it applies
+        # json.loads() to string values, which can over-parse the base64 data.
+        data = resp.json()
+
+        # Check for server-side error envelope (HTTP 200 but JSON error body)
+        if isinstance(data, dict) and "error" in data:
+            raise PortalResponseError(
+                f"Screenshot failed: {data.get('error')} (status={data.get('status')})"
+            )
+
+        # Direct base64 string
+        if isinstance(data, str):
+            return base64.b64decode(data)
+
+        if isinstance(data, dict):
+            # Extract raw value from envelope without json.loads
+            raw = data.get("result") or data.get("data")
+            if isinstance(raw, str):
+                return base64.b64decode(raw)
+            # Nested dict – look for a base64-encoded PNG in values
+            target = raw if isinstance(raw, dict) else data
+            for val in target.values():
+                if isinstance(val, str) and len(val) > 100:
+                    try:
+                        decoded = base64.b64decode(val)
+                        if decoded[:4] == b"\x89PNG":
+                            return decoded
+                    except Exception:
+                        continue
+
+        detail = f"keys={list(data.keys())}" if isinstance(data, dict) else f"type={type(data)}"
+        raise PortalResponseError(f"Unexpected screenshot response format: {detail}")
+
+    # ------------------------------------------------------------------
+    # POST endpoints
+    # ------------------------------------------------------------------
+
+    async def tap(self, x: int, y: int) -> dict[str, Any]:
+        """Tap screen coordinates."""
+        return await self._post("/tap", {"x": x, "y": y})
+
+    async def swipe(
+        self,
+        start_x: int,
+        start_y: int,
+        end_x: int,
+        end_y: int,
+        duration: int | None = None,
+    ) -> dict[str, Any]:
+        """Swipe from (start_x, start_y) to (end_x, end_y).
+        Duration in ms (optional)."""
+        return await self._post(
+            "/swipe",
+            {
+                "startX": start_x,
+                "startY": start_y,
+                "endX": end_x,
+                "endY": end_y,
+                "duration": duration,
+            },
+        )
+
+    async def global_action(self, action: int) -> dict[str, Any]:
+        """Execute accessibility global action by Android action ID."""
+        return await self._post("/global", {"action": action})
+
+    async def start_app(
+        self,
+        package: str,
+        activity: str | None = None,
+        stop_before_launch: bool = False,
+    ) -> dict[str, Any]:
+        """Launch an app by package name."""
+        return await self._post(
+            "/app",
+            {
+                "package": package,
+                "activity": activity,
+                "stopBeforeLaunch": str(stop_before_launch).lower(),
+            },
+        )
+
+    async def stop_app(self, package: str) -> dict[str, Any]:
+        """Best-effort stop an app."""
+        return await self._post("/app/stop", {"package": package})
+
+    async def input_text(self, text: str, clear: bool = True) -> dict[str, Any]:
+        """Input text via Portal keyboard. Text is base64-encoded automatically."""
+        encoded = base64.b64encode(text.encode()).decode()
+        return await self._post(
+            "/keyboard/input",
+            {
+                "base64_text": encoded,
+                "clear": str(clear).lower(),
+            },
+        )
+
+    async def clear_input(self) -> dict[str, Any]:
+        """Clear focused input field."""
+        return await self._post("/keyboard/clear", {})
+
+    async def press_key(self, key_code: int) -> dict[str, Any]:
+        """Send an Android key code."""
+        return await self._post("/keyboard/key", {"key_code": key_code})
+
+    async def set_overlay_offset(self, offset: int) -> dict[str, Any]:
+        """Set overlay vertical offset in pixels."""
+        return await self._post("/overlay_offset", {"offset": offset})
+
+    async def set_socket_port(self, port: int) -> dict[str, Any]:
+        """Update the HTTP server port."""
+        return await self._post("/socket_port", {"port": port})

droidrun_agent-0.1.1/src/droidrun_agent/ws_client.py

@@ -0,0 +1,348 @@
+"""
+PortalWSClient - Complete WebSocket client for DroidRun Portal.
+
+Communicates with Portal's WebSocket server (default port 8081)
+using JSON-RPC style messages.
+Supports all methods defined in the Portal local API,
+including binary screenshot frames.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import uuid
+from typing import Any
+
+import websockets
+from websockets.asyncio.client import ClientConnection
+
+from .exceptions import (
+    PortalConnectionError,
+    PortalResponseError,
+    PortalTimeoutError,
+)
+
+logger = logging.getLogger("droidrun_agent")
+
+
+class PortalWSClient:
+    """
+    Async WebSocket client for DroidRun Portal.
+
+    Uses JSON-RPC style request/response with UUID-based matching.
+    Automatically reconnects when a method is called on a broken connection.
+
+    Usage::
+
+        async with PortalWSClient("ws://192.168.1.100:8081", token="TOKEN") as ws:
+            await ws.tap(200, 400)
+            state = await ws.get_state()
+            png = await ws.take_screenshot()
+    """
+
+    def __init__(
+        self,
+        base_url: str = "ws://localhost:8081",
+        token: str = "",
+        timeout: float = 10.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._ws: ClientConnection | None = None
+        self._listener_task: asyncio.Task[None] | None = None
+        self._pending: dict[str, asyncio.Future[Any]] = {}
+        self._closed = False
+
+    @property
+    def _url(self) -> str:
+        return f"{self.base_url}/?token={self.token}"
+
+    # ------------------------------------------------------------------
+    # Connection management
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> None:
+        """Establish WebSocket connection and start listener."""
+        if self._ws is not None:
+            return
+        try:
+            self._ws = await websockets.connect(self._url)
+        except Exception as exc:
+            raise PortalConnectionError(f"Cannot connect to {self._url}: {exc}") from exc
+        self._closed = False
+        self._listener_task = asyncio.create_task(self._listen())
+        logger.debug("WebSocket connected to %s", self.base_url)
+
+    async def close(self) -> None:
+        """Gracefully close the WebSocket connection."""
+        self._closed = True
+        if self._listener_task is not None:
+            self._listener_task.cancel()
+            try:
+                await self._listener_task
+            except asyncio.CancelledError:
+                pass
+            self._listener_task = None
+        if self._ws is not None:
+            await self._ws.close()
+            self._ws = None
+        # Fail all pending futures
+        for fut in self._pending.values():
+            if not fut.done():
+                fut.set_exception(PortalConnectionError("Connection closed"))
+        self._pending.clear()
+
+    async def __aenter__(self) -> PortalWSClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def _ensure_connected(self) -> None:
+        """Reconnect if the connection is broken."""
+        if self._ws is None or self._closed:
+            self._ws = None
+            self._closed = False
+            if self._listener_task is not None:
+                self._listener_task.cancel()
+                try:
+                    await self._listener_task
+                except asyncio.CancelledError:
+                    pass
+                self._listener_task = None
+            await self.connect()
+
+    # ------------------------------------------------------------------
+    # Listener
+    # ------------------------------------------------------------------
+
+    async def _listen(self) -> None:
+        """Background task: receive messages and dispatch to pending futures."""
+        assert self._ws is not None
+        try:
+            async for message in self._ws:
+                if isinstance(message, bytes):
+                    self._handle_binary(message)
+                else:
+                    self._handle_text(message)
+        except websockets.ConnectionClosed:
+            logger.debug("WebSocket connection closed")
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.debug("WebSocket listener error: %s", exc)
+        finally:
+            self._ws = None
+            # Fail remaining pending futures
+            for fut in self._pending.values():
+                if not fut.done():
+                    fut.set_exception(PortalConnectionError("Connection lost"))
+            self._pending.clear()
+
+    def _handle_text(self, raw: str) -> None:
+        """Parse JSON response and resolve the matching future."""
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            logger.warning("Non-JSON message received: %s", raw[:200])
+            return
+
+        msg_id = data.get("id")
+        if msg_id is None:
+            logger.debug("Message without id: %s", raw[:200])
+            return
+
+        fut = self._pending.pop(str(msg_id), None)
+        if fut is None or fut.done():
+            return
+
+        status = data.get("status", "")
+        if status == "success":
+            fut.set_result(data.get("result"))
+        else:
+            fut.set_exception(PortalResponseError(f"Method returned status={status}: {data.get('result', data)}"))
+
+    def _handle_binary(self, data: bytes) -> None:
+        """Parse binary screenshot frame: first 36 bytes = UUID, rest = PNG."""
+        if len(data) < 36:
+            logger.warning("Binary frame too short (%d bytes)", len(data))
+            return
+
+        msg_id = data[:36].decode("ascii", errors="replace")
+        png_data = data[36:]
+
+        fut = self._pending.pop(msg_id, None)
+        if fut is None or fut.done():
+            logger.debug("No pending future for binary frame id=%s", msg_id)
+            return
+
+        fut.set_result(png_data)
+
+    # ------------------------------------------------------------------
+    # RPC call
+    # ------------------------------------------------------------------
+
+    async def _call(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        """Send a JSON-RPC request and wait for the response."""
+        await self._ensure_connected()
+        assert self._ws is not None
+
+        request_id = str(uuid.uuid4())
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future[Any] = loop.create_future()
+        self._pending[request_id] = fut
+
+        msg = {"id": request_id, "method": method}
+        if params:
+            msg["params"] = params
+
+        try:
+            await self._ws.send(json.dumps(msg))
+        except Exception as exc:
+            self._pending.pop(request_id, None)
+            raise PortalConnectionError(f"Send failed for {method}: {exc}") from exc
+
+        try:
+            return await asyncio.wait_for(fut, timeout=self.timeout)
+        except TimeoutError:
+            self._pending.pop(request_id, None)
+            raise PortalTimeoutError(f"Timeout waiting for response to {method}") from None
+
+    # ------------------------------------------------------------------
+    # Action methods
+    # ------------------------------------------------------------------
+
+    async def tap(self, x: int, y: int) -> Any:
+        """Tap screen coordinates."""
+        return await self._call("tap", {"x": x, "y": y})
+
+    async def swipe(
+        self,
+        start_x: int,
+        start_y: int,
+        end_x: int,
+        end_y: int,
+        duration: int | None = None,
+    ) -> Any:
+        """Swipe from (start_x, start_y) to (end_x, end_y).
+        Duration in ms (optional)."""
+        params: dict[str, Any] = {
+            "startX": start_x,
+            "startY": start_y,
+            "endX": end_x,
+            "endY": end_y,
+        }
+        if duration is not None:
+            params["duration"] = duration
+        return await self._call("swipe", params)
+
+    async def global_action(self, action: int) -> Any:
+        """Execute accessibility global action by Android action ID."""
+        return await self._call("global", {"action": action})
+
+    async def start_app(
+        self,
+        package: str,
+        activity: str | None = None,
+        stop_before_launch: bool = False,
+    ) -> Any:
+        """Launch an app by package name."""
+        params: dict[str, Any] = {"package": package}
+        if activity is not None:
+            params["activity"] = activity
+        if stop_before_launch:
+            params["stopBeforeLaunch"] = True
+        return await self._call("app", params)
+
+    async def stop_app(self, package: str) -> Any:
+        """Best-effort stop an app."""
+        return await self._call("app/stop", {"package": package})
+
+    async def input_text(self, text: str, clear: bool = True) -> Any:
+        """Input text via Portal keyboard. Text is base64-encoded automatically."""
+        encoded = base64.b64encode(text.encode()).decode()
+        return await self._call(
+            "keyboard/input",
+            {
+                "base64_text": encoded,
+                "clear": clear,
+            },
+        )
+
+    async def clear_input(self) -> Any:
+        """Clear focused input field."""
+        return await self._call("keyboard/clear")
+
+    async def press_key(self, key_code: int) -> Any:
+        """Send an Android key code."""
+        return await self._call("keyboard/key", {"key_code": key_code})
+
+    async def set_overlay_offset(self, offset: int) -> Any:
+        """Set overlay vertical offset in pixels."""
+        return await self._call("overlay_offset", {"offset": offset})
+
+    async def set_socket_port(self, port: int) -> Any:
+        """Update the HTTP server port."""
+        return await self._call("socket_port", {"port": port})
+
+    async def take_screenshot(self, *, hide_overlay: bool = True) -> bytes:
+        """Take device screenshot. Returns PNG bytes.
+
+        WebSocket returns a binary frame: first 36 bytes = request UUID,
+        rest = PNG data.
+        """
+        max_retries = 3
+        for attempt in range(max_retries + 1):
+            try:
+                result = await self._call("screenshot", {"hideOverlay": hide_overlay})
+                break
+            except PortalResponseError as exc:
+                if "interval too short" in str(exc).lower() and attempt < max_retries:
+                    await asyncio.sleep(0.5)
+                    continue
+                raise
+        if isinstance(result, bytes):
+            return result
+        # Fallback: base64-encoded string
+        if isinstance(result, str):
+            return base64.b64decode(result)
+        raise PortalResponseError(f"Unexpected screenshot result type: {type(result)}")
+
+    # ------------------------------------------------------------------
+    # Query methods
+    # ------------------------------------------------------------------
+
+    async def get_packages(self) -> Any:
+        """List launchable packages."""
+        return await self._call("packages")
+
+    async def get_state(self, *, filter: bool = True) -> Any:
+        """Get full state. Set filter=False to keep small elements."""
+        return await self._call("state", {"filter": filter})
+
+    async def get_version(self) -> Any:
+        """Get Portal app version."""
+        return await self._call("version")
+
+    async def get_time(self) -> Any:
+        """Get device Unix timestamp in milliseconds."""
+        return await self._call("time")
+
+    async def install(
+        self,
+        urls: list[str],
+        hide_overlay: bool = True,
+    ) -> Any:
+        """Install APK(s) from URL(s). WebSocket only. Supports split APKs."""
+        return await self._call(
+            "install",
+            {
+                "urls": urls,
+                "hideOverlay": hide_overlay,
+            },
+        )