android-emu-agent 0.1.3__py3-none-any.whl

android_emu_agent/reliability/manager.py

@@ -0,0 +1,244 @@
+"""Reliability manager - ADB diagnostics and forensics commands."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import shlex
+import shutil
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import structlog
+
+from android_emu_agent.errors import (
+    AgentError,
+    adb_command_error,
+    adb_not_found_error,
+    permission_error,
+    process_not_found_error,
+)
+
+if TYPE_CHECKING:
+    from adbutils import AdbDevice
+
+logger = structlog.get_logger()
+
+DEFAULT_EVENTS_PATTERN = r"am_proc_died|am_anr|am_crash|am_low_memory|wm_on_paused|wm_on_resumed"
+
+TRIM_LEVELS = {
+    "RUNNING_MODERATE",
+    "RUNNING_LOW",
+    "RUNNING_CRITICAL",
+    "UI_HIDDEN",
+    "BACKGROUND",
+    "MODERATE",
+    "COMPLETE",
+}
+
+
+@dataclass(frozen=True)
+class CommandOutput:
+    output: str
+    line_count: int
+    total_lines: int
+
+
+class ReliabilityManager:
+    """Runs reliability diagnostics via ADB."""
+
+    def __init__(self, output_dir: Path | None = None) -> None:
+        default_dir = Path.home() / ".android-emu-agent" / "artifacts" / "reliability"
+        self.output_dir = output_dir or default_dir
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    async def exit_info(self, device: AdbDevice, package: str, list_only: bool) -> str:
+        cmd = f"dumpsys activity exit-info {package}"
+        if list_only:
+            cmd += " list"
+        return await self._shell(device, cmd)
+
+    async def bugreport(self, serial: str, filename: str | None = None) -> Path:
+        timestamp = self._timestamp()
+        name = filename or f"bugreport_{serial}_{timestamp}.zip"
+        if not name.endswith(".zip"):
+            name = f"{name}.zip"
+        output_path = self.output_dir / name
+        await self._run_adb(serial, ["bugreport", str(output_path)])
+        logger.info("bugreport_saved", serial=serial, path=str(output_path))
+        return output_path
+
+    async def logcat_events(
+        self, device: AdbDevice, pattern: str | None, since: str | None
+    ) -> CommandOutput:
+        cmd = "logcat -b events -d"
+        if since:
+            cmd += f" -t {shlex.quote(since)}"
+        output = await self._shell(device, cmd)
+        lines = output.splitlines()
+        if pattern:
+            try:
+                regex = re.compile(pattern)
+            except re.error as exc:  # pragma: no cover - depends on user input
+                raise AgentError(
+                    code="ERR_INVALID_PATTERN",
+                    message=f"Invalid regex pattern: {pattern}",
+                    context={"pattern": pattern},
+                    remediation="Provide a valid regex for --pattern",
+                ) from exc
+            filtered = [line for line in lines if regex.search(line)]
+        else:
+            filtered = lines
+        return CommandOutput(
+            output="\n".join(filtered),
+            line_count=len(filtered),
+            total_lines=len(lines),
+        )
+
+    async def dropbox_list(self, device: AdbDevice, package: str | None) -> str:
+        output = await self._shell(device, "dumpsys dropbox")
+        if package:
+            filtered = [line for line in output.splitlines() if package in line]
+            return "\n".join(filtered)
+        return output
+
+    async def dropbox_print(self, device: AdbDevice, tag: str) -> str:
+        return await self._shell(device, f"dumpsys dropbox --print {tag}")
+
+    async def background_restrictions(self, device: AdbDevice, package: str) -> dict[str, str]:
+        appops = await self._shell(device, f"cmd appops get {package} RUN_IN_BACKGROUND")
+        standby = await self._shell(device, f"am get-standby-bucket {package}")
+        return {"appops": appops, "standby_bucket": standby}
+
+    async def last_anr(self, device: AdbDevice) -> str:
+        return await self._shell(device, "dumpsys activity lastanr")
+
+    async def jobscheduler(self, device: AdbDevice, package: str) -> str:
+        return await self._shell(device, f"dumpsys jobscheduler {package}")
+
+    async def compile_package(self, device: AdbDevice, package: str, mode: str) -> str:
+        if mode == "reset":
+            return await self._shell(device, f"cmd package compile --reset {package}")
+        if mode == "speed":
+            return await self._shell(device, f"cmd package compile -m speed -f {package}")
+        raise AgentError(
+            code="ERR_INVALID_MODE",
+            message=f"Invalid compile mode: {mode}",
+            context={"mode": mode},
+            remediation="Use 'reset' or 'speed'",
+        )
+
+    async def always_finish_activities(self, device: AdbDevice, enabled: bool) -> str:
+        value = "1" if enabled else "0"
+        return await self._shell(device, f"settings put global always_finish_activities {value}")
+
+    async def run_as_ls(self, device: AdbDevice, package: str, path: str) -> str:
+        safe_path = shlex.quote(path)
+        return await self._shell(device, f"run-as {package} ls -R {safe_path}")
+
+    async def dump_heap(
+        self,
+        device: AdbDevice,
+        serial: str,
+        package: str,
+        keep_remote: bool,
+    ) -> Path:
+        timestamp = self._timestamp()
+        safe_pkg = package.replace(".", "_")
+        remote_path = f"/data/local/tmp/{safe_pkg}_{timestamp}.hprof"
+        await self._shell(device, f"am dumpheap {package} {remote_path}")
+
+        local_path = self.output_dir / f"heap_{safe_pkg}_{timestamp}.hprof"
+        await self._run_adb(serial, ["pull", remote_path, str(local_path)])
+
+        if not keep_remote:
+            await self._shell(device, f"rm -f {remote_path}")
+
+        logger.info("heap_dump_saved", serial=serial, path=str(local_path))
+        return local_path
+
+    async def sigquit(self, device: AdbDevice, package: str) -> int:
+        pid = await self._pidof(device, package)
+        await self._shell(device, f"kill -3 {pid}")
+        return pid
+
+    async def oom_score_adj(self, device: AdbDevice, package: str, score: int) -> int:
+        pid = await self._pidof(device, package)
+        await self._shell_su(device, f"echo {score} > /proc/{pid}/oom_score_adj")
+        return pid
+
+    async def trim_memory(self, device: AdbDevice, package: str, level: str) -> str:
+        return await self._shell(device, f"am send-trim-memory {package} {level}")
+
+    async def pull_root_dir(
+        self,
+        device: AdbDevice,
+        serial: str,
+        remote_dir: str,
+        name: str,
+    ) -> Path:
+        stage_parent = "/data/local/tmp/android-emu-agent"
+        stage_dir = f"{stage_parent}/{name}"
+        stage_cmd = (
+            f"rm -rf {stage_dir} && mkdir -p {stage_parent} && cp -r {remote_dir} {stage_parent}"
+        )
+        await self._shell_su(device, stage_cmd)
+
+        local_path = self.output_dir / f"{serial}_{self._timestamp()}_{name}"
+        await self._run_adb(serial, ["pull", stage_dir, str(local_path)])
+
+        await self._shell(device, f"rm -rf {stage_dir}")
+        logger.info("root_dir_pulled", serial=serial, remote=remote_dir, local=str(local_path))
+        return local_path
+
+    async def _shell(self, device: AdbDevice, command: str) -> str:
+        def _run() -> str:
+            result = device.shell(command)
+            output = getattr(result, "output", None)
+            return output if isinstance(output, str) else str(result)
+
+        return await asyncio.to_thread(_run)
+
+    async def _shell_su(self, device: AdbDevice, command: str) -> str:
+        return await self._shell(device, f"su -c {shlex.quote(command)}")
+
+    async def _pidof(self, device: AdbDevice, package: str) -> int:
+        output = await self._shell(device, f"pidof {package}")
+        pid = output.strip().split(" ")[0] if output.strip() else ""
+        if not pid.isdigit():
+            raise process_not_found_error(package)
+        return int(pid)
+
+    async def _run_adb(self, serial: str, args: list[str]) -> subprocess.CompletedProcess[str]:
+        def _run() -> subprocess.CompletedProcess[str]:
+            adb_path = shutil.which("adb")
+            if not adb_path:
+                raise adb_not_found_error()
+            return subprocess.run(
+                [adb_path, "-s", serial, *args],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+
+        try:
+            return await asyncio.to_thread(_run)
+        except AgentError:
+            raise
+        except FileNotFoundError as exc:
+            raise adb_not_found_error() from exc
+        except subprocess.CalledProcessError as exc:
+            reason = (exc.stderr or exc.stdout or str(exc)).strip()
+            raise adb_command_error(" ".join(args), reason) from exc
+
+    @staticmethod
+    def _timestamp() -> str:
+        return datetime.now().strftime("%Y%m%d_%H%M%S")
+
+
+def require_root(is_rooted: bool, operation: str) -> None:
+    if not is_rooted:
+        raise permission_error(operation)

android_emu_agent/ui/__init__.py

@@ -0,0 +1 @@
+"""UI - Snapshot generation, context resolution, ref management."""

android_emu_agent/ui/context.py

@@ -0,0 +1,169 @@
+"""Context resolver - Activity, window, IME, and dialog detection."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeVar, cast
+
+import structlog
+
+if TYPE_CHECKING:
+    from adbutils import AdbDevice
+
+logger = structlog.get_logger()
+T = TypeVar("T")
+
+
+@dataclass
+class UIContext:
+    """Current UI context from the device."""
+
+    package: str | None
+    activity: str | None
+    top_resumed_activity: str | None
+    top_window: str | None
+    orientation: str
+    window_focused: bool
+    ime_visible: bool
+    ime_package: str | None
+    system_dialogs: list[str]
+
+
+class ContextResolver:
+    """Resolves current UI context from device state."""
+
+    async def resolve(self, device: AdbDevice) -> UIContext:
+        """Resolve current UI context from device."""
+        # Run multiple shell commands in parallel
+        results = await asyncio.gather(
+            self._get_focused_activity(device),
+            self._get_window_info(device),
+            self._get_ime_info(device),
+            return_exceptions=True,
+        )
+
+        activity_info = self._unwrap_result(results[0], default={})
+        window_info = self._unwrap_result(results[1], default={})
+        ime_info = self._unwrap_result(results[2], default={})
+
+        return UIContext(
+            package=activity_info.get("package"),
+            activity=activity_info.get("activity"),
+            top_resumed_activity=activity_info.get("top_resumed"),
+            top_window=self._string_or_none(window_info.get("top_window")),
+            orientation=self._string_value(window_info.get("orientation"), "PORTRAIT"),
+            window_focused=bool(window_info.get("focused", True)),
+            ime_visible=bool(ime_info.get("visible", False)),
+            ime_package=self._string_or_none(ime_info.get("package")),
+            system_dialogs=self._detect_system_dialogs(activity_info, window_info),
+        )
+
+    async def _get_focused_activity(self, device: AdbDevice) -> dict[str, str]:
+        """Get focused activity info via dumpsys."""
+
+        def _run() -> str:
+            return cast(
+                str,
+                device.shell(
+                    "dumpsys activity activities | grep -E 'mResumedActivity|mFocusedActivity'"
+                ),
+            )
+
+        output = await asyncio.to_thread(_run)
+        result: dict[str, str] = {}
+
+        # Parse mResumedActivity: ActivityRecord{... com.foo/.MainActivity ...}
+        resumed_match = re.search(r"mResumedActivity.*?(\S+/\S+)", output)
+        if resumed_match:
+            full = resumed_match.group(1)
+            result["top_resumed"] = full
+            if "/" in full:
+                pkg, activity = full.split("/", 1)
+                result["package"] = pkg
+                result["activity"] = activity
+
+        return result
+
+    async def _get_window_info(self, device: AdbDevice) -> dict[str, str | bool]:
+        """Get window focus and orientation info."""
+
+        def _run() -> str:
+            focus = device.shell("dumpsys window windows | grep -E 'mCurrentFocus|mFocusedApp'")
+            orientation = device.shell("dumpsys input | grep -E 'SurfaceOrientation'")
+            return f"{focus}\n{orientation}"
+
+        output = await asyncio.to_thread(_run)
+        result: dict[str, str | bool] = {"focused": True}
+
+        focus_match = re.search(r"mCurrentFocus=Window\{([^}]+)\}", output)
+        if focus_match:
+            result["top_window"] = focus_match.group(1)
+
+        orientation = "PORTRAIT"
+        orientation_match = re.search(r"SurfaceOrientation:\s*(\d)", output)
+        if orientation_match:
+            value = orientation_match.group(1)
+            if value in {"1", "3"}:
+                orientation = "LANDSCAPE"
+        result["orientation"] = orientation
+
+        return result
+
+    async def _get_ime_info(self, device: AdbDevice) -> dict[str, str | bool]:
+        """Get IME (keyboard) visibility info."""
+
+        def _run() -> str:
+            return cast(str, device.shell("dumpsys input_method | grep -E 'mInputShown|mCurId'"))
+
+        output = await asyncio.to_thread(_run)
+        result: dict[str, str | bool] = {"visible": False}
+
+        if "mInputShown=true" in output:
+            result["visible"] = True
+
+        id_match = re.search(r"mCurId=(\S+)", output)
+        if id_match:
+            result["package"] = id_match.group(1)
+
+        return result
+
+    def _detect_system_dialogs(
+        self,
+        activity_info: dict[str, str],  # noqa: ARG002
+        window_info: dict[str, str | bool],
+    ) -> list[str]:
+        """Detect common system dialogs."""
+        dialogs: list[str] = []
+        top_window = str(window_info.get("top_window", ""))
+
+        # Common system dialog patterns
+        if "GrantPermissions" in top_window:
+            dialogs.append("runtime_permission")
+        if "Chooser" in top_window:
+            dialogs.append("chooser")
+        if "ResolverActivity" in top_window:
+            dialogs.append("app_chooser")
+
+        return dialogs
+
+    @staticmethod
+    def _unwrap_result(result: T | BaseException, *, default: T) -> T:
+        if isinstance(result, BaseException):
+            return default
+        return result
+
+    @staticmethod
+    def _string_or_none(value: object | None) -> str | None:
+        if value is None:
+            return None
+        return str(value)
+
+    @staticmethod
+    def _string_value(value: object | None, fallback: str) -> str:
+        if value is None:
+            return fallback
+        if isinstance(value, bool):
+            return fallback
+        return str(value)

android_emu_agent/ui/ref_resolver.py

@@ -0,0 +1,149 @@
+"""Ref resolver - Locator bundles, drift detection, stale ref handling."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger()
+
+
+@dataclass
+class LocatorBundle:
+    """Bundle of locator strategies for an element."""
+
+    ref: str
+    generation: int
+    resource_id: str | None
+    content_desc: str | None
+    text: str | None
+    class_name: str
+    bounds: list[int]
+    ancestry_hash: str
+    index: int  # Position among siblings
+    ancestry_path: str = ""  # Path from root like "FrameLayout/LinearLayout/Button"
+    element_hash: str = ""  # Stable hash for identification
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dict for storage."""
+        return {
+            "ref": self.ref,
+            "generation": self.generation,
+            "resource_id": self.resource_id,
+            "content_desc": self.content_desc,
+            "text": self.text,
+            "class_name": self.class_name,
+            "bounds": self.bounds,
+            "ancestry_hash": self.ancestry_hash,
+            "index": self.index,
+            "ancestry_path": self.ancestry_path,
+            "element_hash": self.element_hash,
+        }
+
+
+class RefResolver:
+    """Manages element refs and locator resolution."""
+
+    def __init__(self) -> None:
+        # session_id -> (generation -> (ref -> LocatorBundle))
+        self._ref_maps: dict[str, dict[int, dict[str, LocatorBundle]]] = {}
+
+    def store_refs(
+        self,
+        session_id: str,
+        generation: int,
+        elements: list[dict[str, Any]],
+    ) -> None:
+        """Store ref -> locator mappings for a snapshot generation."""
+        if session_id not in self._ref_maps:
+            self._ref_maps[session_id] = {}
+
+        ref_map: dict[str, LocatorBundle] = {}
+        for i, elem in enumerate(elements):
+            bundle = LocatorBundle(
+                ref=elem["ref"],
+                generation=generation,
+                resource_id=elem.get("resource_id"),
+                content_desc=elem.get("content_desc"),
+                text=elem.get("text"),
+                class_name=elem.get("class", ""),
+                bounds=elem.get("bounds", [0, 0, 0, 0]),
+                ancestry_hash=self._compute_ancestry_hash(elem),
+                index=i,
+            )
+            ref_map[elem["ref"]] = bundle
+
+        self._ref_maps[session_id][generation] = ref_map
+        logger.info(
+            "refs_stored",
+            session_id=session_id,
+            generation=generation,
+            count=len(ref_map),
+        )
+
+        # Cleanup old generations (keep last 3)
+        self._cleanup_old_generations(session_id, generation)
+
+    def resolve_ref(
+        self,
+        session_id: str,
+        ref: str,
+        current_generation: int,
+    ) -> tuple[LocatorBundle | None, bool]:
+        """
+        Resolve a ref to its locator bundle.
+
+        Returns:
+            (bundle, is_stale): Bundle if found, and whether it's from an old generation.
+        """
+        if session_id not in self._ref_maps:
+            return None, False
+
+        session_refs = self._ref_maps[session_id]
+
+        # Check current generation first
+        if current_generation in session_refs and ref in session_refs[current_generation]:
+            return session_refs[current_generation][ref], False
+
+        # Check previous generations (stale but might work)
+        for gen in sorted(session_refs.keys(), reverse=True):
+            if gen < current_generation and ref in session_refs[gen]:
+                logger.warning(
+                    "stale_ref_resolved",
+                    ref=ref,
+                    ref_generation=gen,
+                    current_generation=current_generation,
+                )
+                return session_refs[gen][ref], True
+
+        return None, False
+
+    def clear_session(self, session_id: str) -> None:
+        """Clear all refs for a session."""
+        if session_id in self._ref_maps:
+            del self._ref_maps[session_id]
+            logger.info("session_refs_cleared", session_id=session_id)
+
+    def _compute_ancestry_hash(self, elem: dict[str, Any]) -> str:
+        """Compute hash of element's identifying features."""
+        key_parts = [
+            elem.get("resource_id", ""),
+            elem.get("class", ""),
+            str(elem.get("bounds", [])),
+        ]
+        key = "|".join(key_parts)
+        return hashlib.md5(key.encode()).hexdigest()[:8]
+
+    def _cleanup_old_generations(self, session_id: str, current: int) -> None:
+        """Remove generations older than current - 2."""
+        if session_id not in self._ref_maps:
+            return
+
+        session_refs = self._ref_maps[session_id]
+        old_gens = [g for g in session_refs if g < current - 2]
+        for gen in old_gens:
+            del session_refs[gen]
+            logger.debug("generation_cleaned", session_id=session_id, generation=gen)