android-midscene-automation 0.2.4 → 1.1.1

package/artemis-main/packages/artemis-client/src/artemis_client/models.py

@@ -0,0 +1,212 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+
+"""Dependency-free data models for the Artemis remote API."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+TERMINAL_TASK_STATUSES = frozenset(
+    {"completed", "success", "failed", "cancelled", "canceled", "rejected"}
+)
+SUCCESS_TASK_STATUSES = frozenset({"completed", "success"})
+
+
+def _string(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _integer(value: Any) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _device_from_payload(payload: Mapping[str, Any]) -> str | None:
+    direct = _string(payload.get("device_serial") or payload.get("device_id"))
+    if direct:
+        return direct
+
+    device_info = payload.get("device_info")
+    if isinstance(device_info, str):
+        try:
+            device_info = json.loads(device_info)
+        except (TypeError, ValueError, json.JSONDecodeError):
+            return None
+    if isinstance(device_info, Mapping):
+        return _string(device_info.get("device_serial") or device_info.get("device_id"))
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class TaskHandle:
+    """A task accepted by the remote Artemis scheduler."""
+
+    task_id: str
+    status: str
+    device_serial: str | None = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def session_id(self) -> str:
+        """Compatibility alias for servers that call a task a session."""
+        return self.task_id
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> TaskHandle:
+        task_id = _string(payload.get("task_id") or payload.get("session_id") or payload.get("id"))
+        if not task_id:
+            from artemis_client.errors import ProtocolError
+
+            raise ProtocolError("Task admission response did not contain a task/session ID")
+        return cls(
+            task_id=task_id,
+            status=(_string(payload.get("status")) or "queued").lower(),
+            device_serial=_device_from_payload(payload),
+            raw=dict(payload),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TaskResult:
+    """Current or terminal state of a remote Artemis task."""
+
+    task_id: str
+    status: str
+    goal: str | None = None
+    profile: str | None = None
+    device_serial: str | None = None
+    output: Any = None
+    error: str | None = None
+    turns: int | None = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def session_id(self) -> str:
+        return self.task_id
+
+    @property
+    def trace_id(self) -> str:
+        return self.task_id
+
+    @property
+    def done(self) -> bool:
+        return self.status in TERMINAL_TASK_STATUSES
+
+    @property
+    def succeeded(self) -> bool:
+        return self.status in SUCCESS_TASK_STATUSES
+
+    @classmethod
+    def from_payload(
+        cls,
+        payload: Mapping[str, Any],
+        *,
+        task_id: str | None = None,
+    ) -> TaskResult:
+        resolved_id = _string(
+            payload.get("task_id")
+            or payload.get("session_id")
+            or payload.get("trace_id")
+            or payload.get("id")
+            or task_id
+        )
+        if not resolved_id:
+            from artemis_client.errors import ProtocolError
+
+            raise ProtocolError("Task response did not contain a task/session ID")
+
+        output = payload.get("output")
+        if output is None:
+            output = payload.get("result")
+        if output is None:
+            output = payload.get("summary")
+
+        return cls(
+            task_id=resolved_id,
+            status=(_string(payload.get("status")) or "unknown").lower(),
+            goal=_string(payload.get("goal") or payload.get("initial_goal")),
+            profile=_string(payload.get("profile")),
+            device_serial=_device_from_payload(payload),
+            output=output,
+            error=_string(payload.get("error") or payload.get("error_message")),
+            turns=_integer(payload.get("turns") or payload.get("current_turn")),
+            raw=dict(payload),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Device:
+    """A device reported by the remote Artemis host."""
+
+    serial: str
+    state: str
+    model: str | None = None
+    product: str | None = None
+    busy: bool = False
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> Device:
+        serial = _string(
+            payload.get("serial") or payload.get("device_serial") or payload.get("device_id")
+        )
+        if not serial:
+            from artemis_client.errors import ProtocolError
+
+            raise ProtocolError("Device response did not contain a serial number")
+        state = (_string(payload.get("state") or payload.get("status")) or "unknown").lower()
+        busy_value = payload.get("busy")
+        if busy_value is None:
+            busy_value = payload.get("is_busy")
+        return cls(
+            serial=serial,
+            state=state,
+            model=_string(payload.get("model")),
+            product=_string(payload.get("product")),
+            busy=bool(busy_value) or state in {"busy", "running", "locked"},
+            raw=dict(payload),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Capabilities:
+    """Features advertised by an Artemis host."""
+
+    api_version: str
+    features: frozenset[str]
+    server_version: str | None = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    def supports(self, feature: str) -> bool:
+        return feature in self.features
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> Capabilities:
+        raw_features = payload.get("features") or []
+        if isinstance(raw_features, Mapping):
+            features = frozenset(str(key) for key, enabled in raw_features.items() if enabled)
+        elif isinstance(raw_features, (list, tuple, set, frozenset)):
+            features = frozenset(str(item) for item in raw_features)
+        else:
+            features = frozenset()
+        return cls(
+            api_version=_string(payload.get("api_version")) or "unknown",
+            server_version=_string(payload.get("server_version") or payload.get("version")),
+            features=features,
+            raw=dict(payload),
+        )

package/artemis-main/packages/artemis-client/src/artemis_client/py.typed

@@ -0,0 +1 @@
+

package/artemis-main/packages/artemis-client/src/artemis_client/transport.py

@@ -0,0 +1,134 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+
+"""Small JSON-over-HTTP transport implemented with the Python standard library."""
+
+from __future__ import annotations
+
+import json
+import ssl
+import urllib.error
+import urllib.request
+from typing import Any, Mapping
+from urllib.parse import urlsplit
+
+from artemis_client.errors import (
+    ApiError,
+    AuthenticationError,
+    ConflictError,
+    NetworkError,
+    NotFoundError,
+    ProtocolError,
+)
+
+
+class JsonTransport:
+    """Synchronous transport used internally by the async client.
+
+    Calls are moved to worker threads by :class:`ArtemisClient`, keeping the
+    public API asynchronous without adding an HTTP dependency.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token: str | None = None,
+        timeout: float = 30.0,
+        headers: Mapping[str, str] | None = None,
+        ssl_context: ssl.SSLContext | None = None,
+    ) -> None:
+        normalized = base_url.rstrip("/")
+        parsed = urlsplit(normalized)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError("base_url must be an absolute http:// or https:// URL")
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+
+        self.base_url = normalized
+        self.timeout = float(timeout)
+        self.ssl_context = ssl_context
+        self.headers = {
+            "Accept": "application/json",
+            "User-Agent": "artemis-client/0.1",
+            **dict(headers or {}),
+        }
+        if token:
+            self.headers["Authorization"] = f"Bearer {token}"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Mapping[str, Any] | None = None,
+    ) -> Any:
+        if not path.startswith("/"):
+            path = f"/{path}"
+        url = f"{self.base_url}{path}"
+        body = None
+        headers = dict(self.headers)
+        if json_body is not None:
+            body = json.dumps(json_body, separators=(",", ":")).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        request = urllib.request.Request(
+            url,
+            data=body,
+            headers=headers,
+            method=method.upper(),
+        )
+        try:
+            with urllib.request.urlopen(
+                request,
+                timeout=self.timeout,
+                context=self.ssl_context,
+            ) as response:
+                data = response.read()
+                if not data:
+                    return None
+                try:
+                    return json.loads(data.decode("utf-8"))
+                except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+                    raise ProtocolError(f"Artemis host returned invalid JSON from {path}") from exc
+        except urllib.error.HTTPError as exc:
+            payload = self._decode_error_payload(exc)
+            detail = self._error_detail(payload, exc.reason)
+            error_type = {
+                401: AuthenticationError,
+                403: AuthenticationError,
+                404: NotFoundError,
+                409: ConflictError,
+            }.get(exc.code, ApiError)
+            raise error_type(exc.code, detail, payload=payload) from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            reason = getattr(exc, "reason", exc)
+            raise NetworkError(f"Could not reach Artemis host at {url}: {reason}") from exc
+
+    @staticmethod
+    def _decode_error_payload(error: urllib.error.HTTPError) -> Any:
+        try:
+            data = error.read()
+        except OSError:
+            return None
+        if not data:
+            return None
+        try:
+            return json.loads(data.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return data.decode("utf-8", errors="replace")
+
+    @staticmethod
+    def _error_detail(payload: Any, fallback: Any) -> str:
+        if isinstance(payload, Mapping):
+            detail = payload.get("detail") or payload.get("error") or payload.get("message")
+            if detail is not None:
+                return str(detail)
+        if isinstance(payload, str) and payload.strip():
+            return payload.strip()
+        return str(fallback or "request failed")

package/artemis-main/packages/artemis-client/tests/test_client.py

@@ -0,0 +1,289 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+
+from __future__ import annotations
+
+import unittest
+from collections import defaultdict
+from collections.abc import Mapping
+from typing import Any
+
+from artemis_client import (
+    ArtemisClient,
+    NotFoundError,
+    ProtocolError,
+    TaskRejectedError,
+    TaskTimeoutError,
+)
+
+
+class FakeTransport:
+    def __init__(self) -> None:
+        self.responses: dict[tuple[str, str], list[Any]] = defaultdict(list)
+        self.calls: list[tuple[str, str, Mapping[str, Any] | None]] = []
+
+    def add(self, method: str, path: str, *responses: Any) -> None:
+        self.responses[(method, path)].extend(responses)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Mapping[str, Any] | None = None,
+    ) -> Any:
+        self.calls.append((method, path, json_body))
+        queued = self.responses[(method, path)]
+        if not queued:
+            raise AssertionError(f"Unexpected request: {method} {path}")
+        response = queued.pop(0)
+        if isinstance(response, BaseException):
+            raise response
+        return response
+
+
+class ArtemisClientTests(unittest.IsolatedAsyncioTestCase):
+    def setUp(self) -> None:
+        self.transport = FakeTransport()
+        self.client = ArtemisClient(
+            "https://artemis.example.test",
+            poll_interval=0.001,
+            transport=self.transport,
+        )
+
+    async def test_submit_sends_idempotent_session_id(self) -> None:
+        task_id = "00000000-0000-4000-8000-000000000123"
+        self.transport.add(
+            "POST",
+            "/api/run",
+            {
+                "status": "started",
+                "tasks": [
+                    {
+                        "session_id": task_id,
+                        "status": "pending",
+                        "device_serial": "pixel-8",
+                    }
+                ],
+            },
+        )
+
+        handle = await self.client.submit(
+            "Open Settings",
+            task_id=task_id,
+            device_serial="pixel-8",
+            options={"record_video": True},
+        )
+
+        self.assertEqual(handle.task_id, task_id)
+        self.assertEqual(handle.device_serial, "pixel-8")
+        body = self.transport.calls[0][2]
+        assert body is not None
+        self.assertEqual(body["session_id"], task_id)
+        self.assertEqual(body["ingress"], "python_sdk")
+        self.assertEqual(body["options"], {"record_video": True})
+
+    async def test_submit_forwards_pro_tuning_knobs_normalised(self) -> None:
+        task_id = "00000000-0000-4000-8000-000000000321"
+        self.transport.add(
+            "POST",
+            "/api/run",
+            {"status": "started", "tasks": [{"session_id": task_id, "status": "pending"}]},
+        )
+
+        await self.client.submit(
+            "Audit checkout",
+            profile="pro",
+            task_id=task_id,
+            verification_level=" Strict ",
+            explorer_mode="ULTRA",
+        )
+
+        body = self.transport.calls[0][2]
+        assert body is not None
+        self.assertEqual(body["verification_level"], "strict")
+        self.assertEqual(body["explorer_mode"], "ultra")
+
+    async def test_submit_omits_pro_tuning_knobs_when_unset(self) -> None:
+        task_id = "00000000-0000-4000-8000-000000000322"
+        self.transport.add(
+            "POST",
+            "/api/run",
+            {"status": "started", "tasks": [{"session_id": task_id, "status": "pending"}]},
+        )
+
+        await self.client.submit("Open Settings", task_id=task_id, explorer_mode="  ")
+
+        body = self.transport.calls[0][2]
+        assert body is not None
+        self.assertNotIn("verification_level", body)
+        self.assertNotIn("explorer_mode", body)
+
+    async def test_submit_rejects_unknown_pro_tuning_values_before_any_request(self) -> None:
+        with self.assertRaisesRegex(ValueError, "verification_level"):
+            await self.client.submit("Open Settings", verification_level="paranoid")
+        with self.assertRaisesRegex(ValueError, "explorer_mode"):
+            await self.client.submit("Open Settings", explorer_mode="turbo")
+        self.assertEqual(self.transport.calls, [])
+
+    async def test_submit_rejected_task_raises_specific_error(self) -> None:
+        self.transport.add(
+            "POST",
+            "/api/run",
+            {
+                "status": "rejected",
+                "error": "Device is offline",
+                "tasks": [],
+            },
+        )
+
+        with self.assertRaisesRegex(TaskRejectedError, "Device is offline"):
+            await self.client.submit("Open Settings")
+
+    async def test_submit_rejects_non_uuid_task_id(self) -> None:
+        with self.assertRaisesRegex(ValueError, "valid UUID"):
+            await self.client.submit("Open Settings", task_id="not-a-uuid")
+
+    async def test_run_finds_queued_task_then_reads_terminal_session(self) -> None:
+        task_id = "00000000-0000-4000-8000-000000000124"
+        self.transport.add(
+            "POST",
+            "/api/run",
+            {
+                "status": "started",
+                "tasks": [{"session_id": task_id, "status": "pending"}],
+            },
+        )
+        self.transport.add(
+            "GET",
+            f"/api/sessions/{task_id}",
+            NotFoundError(404, "not created yet"),
+            {
+                "session_id": task_id,
+                "status": "completed",
+                "goal": "Open Settings",
+                "current_turn": 4,
+                "summary": "Battery page opened",
+            },
+        )
+        self.transport.add(
+            "GET",
+            "/api/status",
+            {
+                "status": "running",
+                "queue": [{"session_id": task_id, "status": "pending"}],
+            },
+        )
+
+        result = await self.client.run("Open Settings", task_id=task_id, timeout=1)
+
+        self.assertTrue(result.done)
+        self.assertTrue(result.succeeded)
+        self.assertEqual(result.turns, 4)
+        self.assertEqual(result.output, "Battery page opened")
+
+    async def test_get_task_returns_launching_when_not_visible_yet(self) -> None:
+        self.transport.add(
+            "GET",
+            "/api/sessions/new-task",
+            NotFoundError(404, "missing"),
+        )
+        self.transport.add("GET", "/api/status", {"status": "idle", "queue": []})
+
+        result = await self.client.get_task("new-task")
+
+        self.assertEqual(result.status, "launching")
+        self.assertFalse(result.done)
+
+    async def test_wait_for_task_times_out(self) -> None:
+        class LaunchingClient(ArtemisClient):
+            async def get_task(self, task_id: str):  # type: ignore[override]
+                from artemis_client import TaskResult
+
+                return TaskResult(task_id=task_id, status="running")
+
+        client = LaunchingClient(
+            "https://artemis.example.test",
+            poll_interval=0.001,
+            transport=self.transport,
+        )
+        with self.assertRaises(TaskTimeoutError):
+            await client.wait_for_task("slow-task", timeout=0.003)
+
+    async def test_list_devices_accepts_legacy_shape(self) -> None:
+        self.transport.add(
+            "GET",
+            "/api/devices",
+            {
+                "devices": [
+                    {
+                        "serial": "emulator-5554",
+                        "state": "device",
+                        "model": "Pixel_8",
+                        "busy": True,
+                    }
+                ]
+            },
+        )
+
+        devices = await self.client.list_devices()
+
+        self.assertEqual(len(devices), 1)
+        self.assertEqual(devices[0].serial, "emulator-5554")
+        self.assertTrue(devices[0].busy)
+
+    async def test_capabilities_falls_back_for_legacy_server(self) -> None:
+        self.transport.add(
+            "GET",
+            "/api/v1/capabilities",
+            NotFoundError(404, "not implemented"),
+        )
+
+        capabilities = await self.client.capabilities()
+
+        self.assertEqual(capabilities.api_version, "legacy")
+        self.assertTrue(capabilities.supports("tasks.submit"))
+
+    async def test_health_uses_fast_scheduler_endpoint(self) -> None:
+        self.transport.add("GET", "/api/status", {"status": "idle"})
+
+        health = await self.client.health()
+
+        self.assertEqual(health["status"], "idle")
+
+    async def test_readiness_uses_full_diagnostics_endpoint(self) -> None:
+        self.transport.add(
+            "GET",
+            "/api/system/readiness",
+            {"overall_status": "ready"},
+        )
+
+        readiness = await self.client.readiness()
+
+        self.assertEqual(readiness["overall_status"], "ready")
+
+    async def test_invalid_devices_payload_is_rejected(self) -> None:
+        self.transport.add("GET", "/api/devices", {"devices": "not-a-list"})
+
+        with self.assertRaises(ProtocolError):
+            await self.client.list_devices()
+
+    async def test_stop_targets_one_session(self) -> None:
+        self.transport.add("POST", "/api/stop", {"status": "stopped"})
+
+        stopped = await self.client.stop("task-stop")
+
+        self.assertTrue(stopped)
+        self.assertEqual(
+            self.transport.calls[0],
+            ("POST", "/api/stop", {"session_id": "task-stop"}),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()