android-midscene-automation 0.2.3 → 1.1.0

package/artemis-main/artemis/core/diagnostics/__init__.py

@@ -0,0 +1,90 @@
+# 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
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Artemis Diagnostics & System Readiness Package."""
+
+from artemis.core.diagnostics.adb_keys import (
+    AdbKeyStatus,
+    get_adb_key_paths,
+    heal_adb_keys,
+    inspect_adb_keys,
+)
+from artemis.core.diagnostics.device_smoke import smoke_test_device
+from artemis.core.diagnostics.emulator_manager import (
+    EmulatorLaunchStage,
+    EmulatorLaunchState,
+    emulator_manager,
+)
+from artemis.core.diagnostics.engine import ReadinessEngine, readiness_engine
+from artemis.core.diagnostics.probes.adb_probe import AdbDeviceProbe
+from artemis.core.diagnostics.probes.base import BaseProbe
+from artemis.core.diagnostics.probes.credentials_probe import (
+    LLMCredentialsProbe,
+    VisionOCRProbe,
+)
+from artemis.core.diagnostics.probes.host_probe import IntegrationHostProbe
+from artemis.core.diagnostics.probes.runtime_probe import (
+    PythonRuntimeProbe,
+    SystemConfigProbe,
+)
+from artemis.core.diagnostics.probes.toolchain_probe import ToolchainProbe
+from artemis.core.diagnostics.readiness import (
+    CHECK_ORDER,
+    Verdict,
+    adb_keys_corrupted,
+    base_verdict,
+    collect_readiness,
+    sort_by_fix_order,
+)
+from artemis.core.diagnostics.schema import (
+    DeviceInfo,
+    ProbeAction,
+    ProbeCategory,
+    ProbeResult,
+    ProbeStatus,
+    SystemReadinessReport,
+)
+
+__all__ = [
+    "ReadinessEngine",
+    "readiness_engine",
+    "emulator_manager",
+    "EmulatorLaunchStage",
+    "EmulatorLaunchState",
+    "BaseProbe",
+    "IntegrationHostProbe",
+    "PythonRuntimeProbe",
+    "SystemConfigProbe",
+    "AdbDeviceProbe",
+    "LLMCredentialsProbe",
+    "VisionOCRProbe",
+    "ToolchainProbe",
+    "DeviceInfo",
+    "ProbeAction",
+    "ProbeCategory",
+    "ProbeResult",
+    "ProbeStatus",
+    "SystemReadinessReport",
+    "AdbKeyStatus",
+    "get_adb_key_paths",
+    "inspect_adb_keys",
+    "heal_adb_keys",
+    "smoke_test_device",
+    "CHECK_ORDER",
+    "Verdict",
+    "collect_readiness",
+    "base_verdict",
+    "adb_keys_corrupted",
+    "sort_by_fix_order",
+]

package/artemis-main/artemis/core/diagnostics/adb_keys.py

@@ -0,0 +1,270 @@
+# 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
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""ADB Authentication Key Diagnostic and Automated Self-Healing Module.
+
+Android 4.2.2+ requires RSA authentication keys (~/.android/adbkey) for USB debugging.
+When key files become 0-bytes or corrupted (due to aborted writes, touch commands,
+or disk sync issues), ADB fails to send the public key, causing connected devices
+to silently remain in an 'unauthorized' state without ever displaying the authorization prompt.
+
+This module provides detection and self-healing for corrupted ADB keys.
+"""
+
+from dataclasses import asdict, dataclass
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import time
+from typing import Any
+
+from artemis.toolchain import toolchain
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class AdbKeyStatus:
+    """Status details for ADB authentication keys."""
+
+    is_valid: bool
+    is_corrupted: bool
+    exists: bool
+    key_path: str
+    pub_key_path: str
+    key_size_bytes: int = 0
+    pub_key_size_bytes: int = 0
+    error_reason: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def get_adb_key_paths() -> tuple[Path, Path]:
+    """Resolve the paths to the active ADB private and public key files."""
+    adb_vendor_keys = os.environ.get("ADB_VENDOR_KEYS")
+    if adb_vendor_keys:
+        custom_priv = Path(adb_vendor_keys.split(os.pathsep)[0])
+        custom_pub = Path(f"{custom_priv}.pub")
+        return custom_priv, custom_pub
+
+    android_dir = Path.home() / ".android"
+    return android_dir / "adbkey", android_dir / "adbkey.pub"
+
+
+def inspect_adb_keys() -> AdbKeyStatus:
+    """Inspect ADB authentication RSA key files for corruption or invalid state."""
+    priv_path, pub_path = get_adb_key_paths()
+
+    if not priv_path.exists() and not pub_path.exists():
+        # Fresh environment: ADB will automatically generate keys on first start
+        return AdbKeyStatus(
+            is_valid=True,
+            is_corrupted=False,
+            exists=False,
+            key_path=str(priv_path),
+            pub_key_path=str(pub_path),
+            key_size_bytes=0,
+            pub_key_size_bytes=0,
+            error_reason=None,
+        )
+
+    priv_size = priv_path.stat().st_size if priv_path.exists() else 0
+    pub_size = pub_path.stat().st_size if pub_path.exists() else 0
+
+    # 1. Check for 0-byte or truncated private key file
+    if priv_path.exists():
+        if priv_size == 0:
+            return AdbKeyStatus(
+                is_valid=False,
+                is_corrupted=True,
+                exists=True,
+                key_path=str(priv_path),
+                pub_key_path=str(pub_path),
+                key_size_bytes=0,
+                pub_key_size_bytes=pub_size,
+                error_reason="Private key file is 0 bytes (empty). ADB cannot authenticate devices.",
+            )
+        if priv_size < 100:
+            return AdbKeyStatus(
+                is_valid=False,
+                is_corrupted=True,
+                exists=True,
+                key_path=str(priv_path),
+                pub_key_path=str(pub_path),
+                key_size_bytes=priv_size,
+                pub_key_size_bytes=pub_size,
+                error_reason=f"Private key file is suspiciously small ({priv_size} bytes).",
+            )
+
+        # Validate PEM header structure
+        try:
+            content = priv_path.read_text(encoding="utf-8", errors="replace")
+            if "BEGIN" not in content or "PRIVATE KEY" not in content:
+                return AdbKeyStatus(
+                    is_valid=False,
+                    is_corrupted=True,
+                    exists=True,
+                    key_path=str(priv_path),
+                    pub_key_path=str(pub_path),
+                    key_size_bytes=priv_size,
+                    pub_key_size_bytes=pub_size,
+                    error_reason="Private key does not contain a valid PEM private key header.",
+                )
+        except Exception as e:
+            return AdbKeyStatus(
+                is_valid=False,
+                is_corrupted=True,
+                exists=True,
+                key_path=str(priv_path),
+                pub_key_path=str(pub_path),
+                key_size_bytes=priv_size,
+                pub_key_size_bytes=pub_size,
+                error_reason=f"Cannot read private key: {e}",
+            )
+
+    # 2. Check for 0-byte public key if it exists
+    if pub_path.exists() and pub_size == 0:
+        return AdbKeyStatus(
+            is_valid=False,
+            is_corrupted=True,
+            exists=True,
+            key_path=str(priv_path),
+            pub_key_path=str(pub_path),
+            key_size_bytes=priv_size,
+            pub_key_size_bytes=0,
+            error_reason="Public key file (adbkey.pub) is 0 bytes (empty).",
+        )
+
+    return AdbKeyStatus(
+        is_valid=True,
+        is_corrupted=False,
+        exists=True,
+        key_path=str(priv_path),
+        pub_key_path=str(pub_path),
+        key_size_bytes=priv_size,
+        pub_key_size_bytes=pub_size,
+        error_reason=None,
+    )
+
+
+def heal_adb_keys(adb_path: str | None = None, force: bool = False) -> dict[str, Any]:
+    """Auto-heal corrupted ADB authentication keys.
+
+    If keys are corrupted (or if `force=True`), this function:
+    1. Backs up or removes corrupted key files.
+    2. Restarts the ADB server to cleanly generate a fresh RSA 2048-bit key pair.
+    3. Verifies that the new key pair is healthy and valid.
+    """
+    status = inspect_adb_keys()
+    if not status.is_corrupted and not force:
+        return {
+            "success": True,
+            "repaired": False,
+            "message": "ADB keys are healthy, no repair required.",
+            "status": status.to_dict(),
+        }
+
+    priv_path, pub_path = get_adb_key_paths()
+    priv_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Backup corrupted non-empty files before removal
+    timestamp = int(time.time())
+    if priv_path.exists() and priv_path.stat().st_size > 0:
+        backup_path = priv_path.with_name(f"adbkey.corrupted.{timestamp}")
+        try:
+            shutil.copy2(priv_path, backup_path)
+            logger.info(f"Backed up corrupted adbkey to {backup_path}")
+        except Exception as e:
+            logger.warning(f"Could not backup corrupted adbkey: {e}")
+
+    # Remove corrupted key files
+    try:
+        if priv_path.exists():
+            priv_path.unlink(missing_ok=True)
+        if pub_path.exists():
+            pub_path.unlink(missing_ok=True)
+    except Exception as e:
+        logger.error(f"Failed to remove corrupted adb keys: {e}")
+        return {
+            "success": False,
+            "repaired": False,
+            "message": f"Failed to remove corrupted ADB key files: {e}",
+            "status": status.to_dict(),
+        }
+
+    # Resolve ADB executable
+    resolved_adb = adb_path or toolchain.resolve("adb") or shutil.which("adb") or "adb"
+
+    # Restart ADB server to trigger key generation
+    try:
+        clean_env = os.environ.copy()
+        clean_env.pop("ADB_SERVER_SOCKET", None)
+        subprocess.run(
+            [resolved_adb, "kill-server"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=5,
+            env=clean_env,
+        )
+        subprocess.run(
+            [resolved_adb, "start-server"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=5,
+            env=clean_env,
+        )
+        # Execute adb devices to trigger initial handshake & key material generation if needed
+        subprocess.run(
+            [resolved_adb, "devices"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=5,
+            env=clean_env,
+        )
+    except Exception as e:
+        logger.error(f"Error restarting ADB server during key healing: {e}")
+        return {
+            "success": False,
+            "repaired": False,
+            "message": f"Failed to restart ADB server: {e}",
+            "status": status.to_dict(),
+        }
+
+    # Re-inspect to verify health
+    new_status = inspect_adb_keys()
+    if new_status.is_valid and new_status.key_size_bytes > 0:
+        logger.info("Successfully healed corrupted ADB keys.")
+        return {
+            "success": True,
+            "repaired": True,
+            "message": "Corrupted ADB keys were successfully repaired and regenerated.",
+            "status": new_status.to_dict(),
+        }
+    elif new_status.is_valid and not new_status.is_corrupted:
+        return {
+            "success": True,
+            "repaired": True,
+            "message": "Corrupted ADB keys cleared. Fresh keys will be created on first device connection.",
+            "status": new_status.to_dict(),
+        }
+    else:
+        return {
+            "success": False,
+            "repaired": False,
+            "message": f"Key healing completed, but keys remain invalid: {new_status.error_reason}",
+            "status": new_status.to_dict(),
+        }

package/artemis-main/artemis/core/diagnostics/adb_server_connection.py

@@ -0,0 +1,330 @@
+# 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
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Process-wide ADB server endpoint discovery and activation."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+import re
+import subprocess
+from typing import Any, Callable
+
+from dotenv import set_key
+
+from artemis.config import settings
+from artemis.config.paths import ROOT_DIR, get_app_dir
+from artemis.runtime.adb_endpoint import (
+    AdbEndpoint,
+    AdbSession,
+    InvalidAdbEndpoint,
+    current_adb_endpoint,
+)
+from artemis.toolchain import toolchain
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+AdbServerEndpoint = AdbEndpoint
+InvalidAdbServerEndpoint = InvalidAdbEndpoint
+
+
+class AdbServerConnectionManager:
+    """Validate, probe, activate, and persist the selected ADB server endpoint."""
+
+    def __init__(
+        self,
+        *,
+        adb_resolver: Callable[[], str | None] | None = None,
+        env_files: list[Path] | None = None,
+    ) -> None:
+        self._adb_resolver = adb_resolver or (lambda: toolchain.resolve("adb"))
+        self._env_files = env_files
+        self._activation_lock = asyncio.Lock()
+
+    @staticmethod
+    def validate_endpoint(host: str, port: int) -> AdbServerEndpoint:
+        return AdbEndpoint.create(host, port)
+
+    def current_endpoint(self) -> AdbServerEndpoint:
+        return current_adb_endpoint()
+
+    def status(self) -> dict[str, Any]:
+        return {"endpoint": self.current_endpoint().to_dict()}
+
+    def synchronize_environment(self) -> AdbServerEndpoint:
+        """Align subprocess and Python ADB clients with the configured endpoint."""
+        socket_endpoint = self._endpoint_from_socket(os.environ.get("ADB_SERVER_SOCKET"))
+        has_explicit_host = bool(os.environ.get("ADB_HOST") or os.environ.get("ADB_PORT"))
+        endpoint = (
+            socket_endpoint
+            if socket_endpoint is not None and not has_explicit_host
+            else self.current_endpoint()
+        )
+        self._activate(endpoint)
+        return endpoint
+
+    async def connect(
+        self,
+        host: str,
+        port: int,
+        *,
+        persist: bool = True,
+    ) -> dict[str, Any]:
+        """Probe an endpoint, then make it the process-wide ADB server on success."""
+        endpoint = self.validate_endpoint(host, port)
+        probe_result = await self.probe(host, port)
+        if not probe_result["success"]:
+            return probe_result
+
+        persisted = False
+        persistence_error: str | None = None
+        async with self._activation_lock:
+            self._activate(endpoint)
+            if persist:
+                try:
+                    await asyncio.to_thread(self._persist, endpoint)
+                    persisted = True
+                except Exception as exc:
+                    persistence_error = str(exc)
+                    logger.warning(f"Unable to persist ADB server endpoint: {exc}")
+
+        message = probe_result["message"]
+        if persist and not persisted:
+            message = (
+                f"{message} The connection is active for this session, but Artemis could not "
+                "save it for the next launch."
+            )
+
+        return {
+            **probe_result,
+            "endpoint": endpoint.to_dict(),
+            "message": message,
+            "persisted": persisted,
+            "persistence_error": persistence_error,
+        }
+
+    async def probe(self, host: str, port: int) -> dict[str, Any]:
+        """Test an endpoint without changing the process preference."""
+        endpoint = self.validate_endpoint(host, port)
+        return await asyncio.to_thread(self._probe_sync, endpoint)
+
+    async def use_local_server(self, *, persist: bool = True) -> dict[str, Any]:
+        """Restore the standard local ADB server without killing any remote daemon."""
+        endpoint = AdbEndpoint.local()
+        persisted = False
+        persistence_error: str | None = None
+        async with self._activation_lock:
+            self._activate(endpoint)
+            if persist:
+                try:
+                    await asyncio.to_thread(self._persist, endpoint)
+                    persisted = True
+                except Exception as exc:
+                    persistence_error = str(exc)
+                    logger.warning(f"Unable to persist local ADB server endpoint: {exc}")
+
+        message = "Artemis is now using the local ADB server."
+        if persist and not persisted:
+            message += " The setting could not be saved for the next launch."
+        return {
+            "success": True,
+            "endpoint": endpoint.to_dict(),
+            "persisted": persisted,
+            "persistence_error": persistence_error,
+            "message": message,
+        }
+
+    def _probe_sync(self, endpoint: AdbServerEndpoint) -> dict[str, Any]:
+        adb_path = self._adb_resolver()
+        if not adb_path:
+            return {
+                "success": False,
+                "error_code": "adb_not_found",
+                "message": "Android Platform Tools (adb) is not installed or not on PATH.",
+                "endpoint": endpoint.to_dict(),
+                "devices": [],
+            }
+
+        session = AdbSession(endpoint, adb_path=adb_path)
+        command = session.command(["devices", "-l"])
+        try:
+            result = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=8,
+                env=self._probe_environment(),
+            )
+        except subprocess.TimeoutExpired:
+            return {
+                "success": False,
+                "error_code": "timeout",
+                "message": (
+                    "The ADB server did not respond. Check that the host and port are correct "
+                    "and accessible from this computer."
+                ),
+                "endpoint": endpoint.to_dict(),
+                "devices": [],
+            }
+        except OSError as exc:
+            logger.warning(f"Failed to execute ADB endpoint probe: {exc}")
+            return {
+                "success": False,
+                "error_code": "adb_execution_failed",
+                "message": f"Unable to run adb: {exc}",
+                "endpoint": endpoint.to_dict(),
+                "devices": [],
+            }
+
+        stdout = result.stdout or ""
+        stderr = result.stderr or ""
+        output = "\n".join(part.strip() for part in (stdout, stderr) if part.strip())
+        devices = self._parse_devices(stdout)
+        if result.returncode != 0:
+            return {
+                "success": False,
+                "error_code": "server_unreachable",
+                "message": self._connection_error_message(output),
+                "output": output,
+                "endpoint": endpoint.to_dict(),
+                "devices": [],
+            }
+
+        ready_devices = [device for device in devices if device["state"] == "device"]
+        if ready_devices:
+            message = (
+                f"Connected to {endpoint.host}:{endpoint.port} and found "
+                f"{len(ready_devices)} ready device{'s' if len(ready_devices) != 1 else ''}."
+            )
+        elif devices:
+            message = (
+                "The ADB server is reachable, but its devices require attention. "
+                "Unlock the phone and approve USB debugging if prompted."
+            )
+        else:
+            message = (
+                "The ADB server is reachable, but no devices are attached to the remote computer."
+            )
+
+        return {
+            "success": True,
+            "message": message,
+            "output": output,
+            "endpoint": endpoint.to_dict(),
+            "devices": devices,
+        }
+
+    @staticmethod
+    def _parse_devices(output: str) -> list[dict[str, str | None]]:
+        devices: list[dict[str, str | None]] = []
+        for raw_line in output.splitlines():
+            line = raw_line.strip()
+            if not line or line.lower().startswith("list of devices") or line.startswith("*"):
+                continue
+            parts = line.split()
+            if len(parts) < 2:
+                continue
+            metadata = {
+                key: value.replace("_", " ")
+                for token in parts[2:]
+                if ":" in token
+                for key, value in [token.split(":", 1)]
+            }
+            devices.append(
+                {
+                    "serial": parts[0],
+                    "state": parts[1],
+                    "model": metadata.get("model"),
+                    "product": metadata.get("product"),
+                }
+            )
+        return devices
+
+    @staticmethod
+    def _connection_error_message(output: str) -> str:
+        lowered = output.lower()
+        if "cannot connect" in lowered or "failed to connect" in lowered:
+            return (
+                "No ADB server is listening at this address. Verify that the host and port are "
+                "correct and accessible from this computer."
+            )
+        if "version" in lowered and "mismatch" in lowered:
+            return (
+                "The local and remote ADB versions are incompatible. Use matching Android "
+                "Platform Tools versions on both computers."
+            )
+        return output or "Unable to reach the ADB server endpoint."
+
+    @staticmethod
+    def _probe_environment() -> dict[str, str]:
+        environment = os.environ.copy()
+        environment.pop("ADB_SERVER_SOCKET", None)
+        return environment
+
+    @classmethod
+    def _endpoint_from_socket(cls, value: str | None) -> AdbServerEndpoint | None:
+        if not value or not value.startswith("tcp:"):
+            return None
+        address = value.removeprefix("tcp:")
+        if address.startswith("["):
+            match = re.fullmatch(r"\[([^]]+)]:(\d+)", address)
+        else:
+            match = re.fullmatch(r"(.+):(\d+)", address)
+        if match is None:
+            return None
+        try:
+            return cls.validate_endpoint(match.group(1), int(match.group(2)))
+        except (InvalidAdbServerEndpoint, ValueError):
+            return None
+
+    @staticmethod
+    def _activate(endpoint: AdbServerEndpoint) -> None:
+        settings.ADB_HOST = endpoint.host
+        settings.ADB_PORT = endpoint.port
+        endpoint.apply_to_environment()
+        logger.info(
+            f"Activated {endpoint.mode} ADB server endpoint {endpoint.host}:{endpoint.port}"
+        )
+
+    def _persist(self, endpoint: AdbServerEndpoint) -> None:
+        for env_file in self._environment_files():
+            env_file.parent.mkdir(parents=True, exist_ok=True)
+            if not env_file.exists():
+                env_file.touch()
+            set_key(str(env_file), "ADB_HOST", endpoint.host, quote_mode="never")
+            set_key(str(env_file), "ADB_PORT", str(endpoint.port), quote_mode="never")
+
+    def _environment_files(self) -> list[Path]:
+        if self._env_files is not None:
+            candidates = self._env_files
+        else:
+            candidates = [ROOT_DIR / ".env", get_app_dir() / ".env"]
+
+        unique_files: list[Path] = []
+        seen: set[Path] = set()
+        for candidate in candidates:
+            resolved = candidate.resolve()
+            if resolved not in seen:
+                seen.add(resolved)
+                unique_files.append(candidate)
+        return unique_files
+
+
+adb_server_connection = AdbServerConnectionManager()
+adb_server_connection.synchronize_environment()