android-midscene-automation 0.2.4 → 1.1.1

package/artemis-main/artemis/core/diagnostics/probes/toolchain_probe.py

@@ -0,0 +1,139 @@
+# 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.
+
+"""Toolchain and Video Recording Auxiliary Probe."""
+
+from artemis.core.diagnostics.probes.base import BaseProbe
+from artemis.core.diagnostics.schema import (
+    ProbeAction,
+    ProbeCategory,
+    ProbeResult,
+    ProbeStatus,
+)
+from artemis.platform import OSType, platform
+from artemis.toolchain import toolchain
+
+
+class ToolchainProbe(BaseProbe):
+    """Probe checking required multimedia and video recording toolchains (ffmpeg, scrcpy)."""
+
+    @property
+    def probe_id(self) -> str:
+        return "toolchain"
+
+    @property
+    def category(self) -> ProbeCategory:
+        return ProbeCategory.TOOLCHAIN
+
+    @property
+    def is_blocker(self) -> bool:
+        return False
+
+    async def probe(self) -> ProbeResult:
+        ffmpeg_path = toolchain.resolve("ffmpeg")
+        scrcpy_path = toolchain.resolve("scrcpy")
+
+        tools_installed = []
+        tools_missing = []
+        if ffmpeg_path:
+            tools_installed.append("FFmpeg")
+        else:
+            tools_missing.append("FFmpeg")
+
+        if scrcpy_path:
+            tools_installed.append("scrcpy")
+        else:
+            tools_missing.append("scrcpy")
+
+        metadata = {
+            "ffmpeg": ffmpeg_path is not None,
+            "scrcpy": scrcpy_path is not None,
+            "ffmpeg_path": ffmpeg_path,
+            "scrcpy_path": scrcpy_path,
+            "tools_installed": tools_installed,
+            "tools_missing": tools_missing,
+        }
+
+        if ffmpeg_path and scrcpy_path:
+            return ProbeResult(
+                id=self.probe_id,
+                category=self.category,
+                title="Video Recording Toolchain",
+                status=ProbeStatus.PASS,
+                is_blocker=self.is_blocker,
+                summary="Ready (FFmpeg + scrcpy)",
+                description=f"FFmpeg ({ffmpeg_path}) and scrcpy ({scrcpy_path}) are available. Live stream and high-speed video replays are active.",
+                metadata=metadata,
+                actions=[
+                    ProbeAction(
+                        action_type="hint",
+                        label="Toolchain Active",
+                        payload="FFmpeg and scrcpy are installed and active.",
+                    )
+                ],
+            )
+
+        missing_str = " & ".join(tools_missing)
+        actions = []
+
+        if platform.os_type == OSType.WINDOWS:
+            actions.append(
+                ProbeAction(
+                    action_type="command",
+                    label="Install via WinGet",
+                    payload="winget install Gyan.FFmpeg Genymobile.scrcpy",
+                )
+            )
+            actions.append(
+                ProbeAction(
+                    action_type="command",
+                    label="Run PowerShell Setup",
+                    payload="powershell -ExecutionPolicy Bypass -File scripts/install_deps.ps1",
+                )
+            )
+        elif platform.os_type == OSType.MACOS:
+            actions.append(
+                ProbeAction(
+                    action_type="command",
+                    label="Install via Homebrew",
+                    payload="brew install ffmpeg scrcpy",
+                )
+            )
+        else:
+            actions.append(
+                ProbeAction(
+                    action_type="command",
+                    label="Install on Linux",
+                    payload="sudo apt-get install -y ffmpeg scrcpy",
+                )
+            )
+            actions.append(
+                ProbeAction(
+                    action_type="command",
+                    label="One-Click Install Script",
+                    payload="bash scripts/install_deps.sh",
+                )
+            )
+
+        return ProbeResult(
+            id=self.probe_id,
+            category=self.category,
+            title="Video Recording Toolchain",
+            status=ProbeStatus.FAIL,
+            is_blocker=self.is_blocker,
+            summary=f"Missing {missing_str}",
+            description=f"Video toolchain is required for screen streaming and test replay recording. Missing: {missing_str}.",
+            metadata=metadata,
+            actions=actions,
+        )

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

@@ -0,0 +1,83 @@
+# 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.
+
+"""Readiness collection and verdict shared by every diagnosis entry point.
+
+``artemis doctor`` and the ``mobile_diagnose`` MCP tool must agree on which
+probes run, in which order they are fixed, and what "ready" means. This module
+holds exactly that common core; each entry point layers its own extra
+conditions, fix policy and rendering on top.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from typing import Literal
+
+from artemis.core.diagnostics.engine import readiness_engine
+from artemis.core.diagnostics.probes.host_probe import IntegrationHostProbe
+from artemis.core.diagnostics.schema import ProbeResult, ProbeStatus, SystemReadinessReport
+
+Verdict = Literal["ready", "degraded", "blocked"]
+
+#: Fix order. Runtime problems mask everything after them, credentials mask
+#: device problems (a task cannot start without a model), and the toolchain is
+#: optional.
+CHECK_ORDER: dict[str, int] = {
+    "python_runtime": 0,
+    "system_config": 1,
+    "integration_host": 2,
+    "gemini_api_key": 3,
+    "android_adb": 4,
+    "toolchain": 5,
+    "vision_ocr_key": 6,
+}
+
+
+def sort_by_fix_order(results: Sequence[ProbeResult]) -> list[ProbeResult]:
+    """Order probe results so the first problem listed is the one to fix first."""
+    return sorted(results, key=lambda r: CHECK_ORDER.get(r.id, len(CHECK_ORDER)))
+
+
+async def collect_readiness() -> tuple[SystemReadinessReport, ProbeResult]:
+    """Run the engine probes and the integration-host probe concurrently."""
+    report, host = await asyncio.gather(
+        readiness_engine.run_all(force_refresh=True),
+        IntegrationHostProbe().probe(),
+    )
+    return report, host
+
+
+def base_verdict(results: Sequence[ProbeResult]) -> Verdict:
+    """Verdict from probe results alone.
+
+    Blocked when there is no blocker at all (nothing was checked) or any
+    blocker is not PASS; degraded when only optional checks fail; ready
+    otherwise.
+    """
+    blockers = [r for r in results if r.is_blocker]
+    if not blockers or any(r.status is not ProbeStatus.PASS for r in blockers):
+        return "blocked"
+    if any(r.status is not ProbeStatus.PASS for r in results):
+        return "degraded"
+    return "ready"
+
+
+def adb_keys_corrupted(results: Sequence[ProbeResult]) -> bool:
+    """Whether the ADB probe reported corrupted RSA keys (the one self-heal both entry points share)."""
+    adb = next((r for r in results if r.id == "android_adb"), None)
+    if adb is None:
+        return False
+    return bool((adb.metadata.get("adb_keys") or {}).get("is_corrupted"))

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

@@ -0,0 +1,118 @@
+# 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.
+
+"""Schema definitions for Artemis System Diagnostics & Readiness Engine."""
+
+from enum import Enum
+from typing import Any, Literal
+from pydantic import BaseModel, Field
+
+
+class ProbeStatus(str, Enum):
+    """Execution status of a readiness probe."""
+
+    PASS = "pass"  # 🟢 Ready for execution
+    WARN = "warn"  # 🟡 Warning / Non-blocking prerequisite missing (e.g. no devices attached)
+    FAIL = "fail"  # 🔴 Blocking prerequisite failure (e.g. ADB missing, no API key)
+    SKIPPED = "skipped"  # ⚪ Skipped probe
+
+
+class ProbeCategory(str, Enum):
+    """Category of system readiness check."""
+
+    DEVICE = "device"  # Hardware & Device Driver (ADB, Emulator, Cloud device)
+    CREDENTIALS = "auth"  # LLM API Keys & OCR Credentials
+    TOOLCHAIN = "toolchain"  # External tools (FFmpeg, scrcpy, etc.)
+    RUNTIME = "runtime"  # Python runtime & Config health
+
+
+class ProbeAction(BaseModel):
+    """Actionable guidance payload for quick remediation or user guidance."""
+
+    action_type: Literal["command", "hint", "link"] = Field(
+        description="Type of remediation action ('command' to copy/run, 'hint' for guidance, 'link' for docs)"
+    )
+    label: str = Field(description="Display label for the action button or badge")
+    payload: str = Field(description="Command string to execute/copy or explanation hint")
+
+
+class DeviceInfo(BaseModel):
+    """Structured Android device / emulator metadata."""
+
+    serial: str = Field(description="Device serial number or emulator port ID (e.g. emulator-5554)")
+    state: str = Field(
+        default="device", description="Connection state ('device', 'unauthorized', 'offline')"
+    )
+    model: str | None = Field(
+        default=None, description="Device model name (e.g. Pixel 8, sdk_gphone64_arm64)"
+    )
+    product: str | None = Field(default=None, description="Product code name")
+    android_version: str | None = Field(
+        default=None, description="Android OS release version (e.g. 14)"
+    )
+    screen_resolution: str | None = Field(
+        default=None, description="Screen width x height (e.g. 1080x2400)"
+    )
+    is_locked: bool | None = Field(
+        default=None,
+        description="Whether Android Keyguard currently blocks access; None when undetermined",
+    )
+    is_emulator: bool = Field(default=False, description="Whether the device is an emulator")
+    installed_packages: list[str] = Field(
+        default_factory=list, description="List of recognized installed package names"
+    )
+
+
+class ProbeResult(BaseModel):
+    """Outcome of a single readiness probe check."""
+
+    id: str = Field(
+        description="Unique identifier for the probe (e.g. 'android_adb', 'gemini_api_key')"
+    )
+    category: ProbeCategory = Field(description="Category of the probe")
+    title: str = Field(description="Human-readable title (e.g. 'Device / Emulator Connected')")
+    status: ProbeStatus = Field(description="Current status (pass, warn, fail)")
+    is_blocker: bool = Field(
+        default=True, description="Whether passing this probe is strictly required to run tasks"
+    )
+    summary: str = Field(
+        description="Short badge summary text (e.g. 'Connected', 'No Device', 'Active & Ready')"
+    )
+    description: str = Field(description="Detailed explanation of the status")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Arbitrary extra metadata (e.g. device list)"
+    )
+    actions: list[ProbeAction] = Field(
+        default_factory=list, description="List of actionable remediation steps"
+    )
+
+
+class SystemReadinessReport(BaseModel):
+    """Aggregated system readiness report across all probes."""
+
+    overall_ready: bool = Field(description="True if all blocker probes are passing")
+    blocker_count: int = Field(description="Total count of required blocker probes")
+    passed_blocker_count: int = Field(
+        description="Count of required blocker probes currently passing"
+    )
+    probes: list[ProbeResult] = Field(
+        default_factory=list, description="Ordered list of probe results"
+    )
+    active_device: DeviceInfo | None = Field(
+        default=None, description="Currently selected/active target device"
+    )
+    os_type: str = Field(
+        default="linux", description="Operating system type ('linux', 'darwin', 'windows')"
+    )
+    timestamp: float = Field(description="Unix timestamp of when the report was generated")

package/artemis-main/artemis/core/tool_declaration.py

@@ -0,0 +1,43 @@
+# 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.
+
+"""Standardized tool declaration adhering to JSON Schema format."""
+
+from typing import Any
+
+
+class ToolDeclaration(dict):
+    """OpenAI function schema with name, description and parameters properties."""
+
+    def __init__(self, name: str, description: str, parameters: dict[str, Any]):
+        super().__init__(
+            type="function",
+            function={
+                "name": name,
+                "description": description,
+                "parameters": parameters,
+            },
+        )
+
+    @property
+    def name(self) -> str:
+        return self.get("function", {}).get("name", "")
+
+    @property
+    def description(self) -> str:
+        return self.get("function", {}).get("description", "")
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return self.get("function", {}).get("parameters", {})

package/artemis-main/artemis/core/tool_failure.py

@@ -0,0 +1,56 @@
+# 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.
+
+"""Typed failures for text-returning helper tools.
+
+Tools return ``ToolFailure`` on failure; callers use ``is_tool_failure`` to
+check the result. The str subclass keeps results compatible with text consumers
+without treating words such as "Error" in tool output as a failure signal.
+
+Pydantic converts str subclasses to plain strings in ``ToolMessage.content``
+and ``ToolExecutionResult.text_summary``. Check the raw result before wrapping
+it and pass ``status="error"`` to preserve the failure state.
+"""
+
+from typing import Any
+
+from langchain_core.messages import ToolMessage
+
+
+class ToolFailure(str):
+    """A helper tool's failure report, carried as the text the agent reads."""
+
+    __slots__ = ()
+
+
+def is_tool_failure(result: Any) -> bool:
+    """Whether a tool result reports failure.
+
+    True for a ``ToolMessage`` whose ``status`` is ``"error"``, for a
+    :class:`ToolFailure` text, and for a content-block list whose text is a
+    :class:`ToolFailure`. Plain strings are never failures, whatever they say.
+    """
+    if isinstance(result, ToolMessage):
+        if result.status == "error":
+            return True
+        result = result.content
+    if isinstance(result, ToolFailure):
+        return True
+    if isinstance(result, list):
+        for block in result:
+            if isinstance(block, ToolFailure):
+                return True
+            if isinstance(block, dict) and isinstance(block.get("text"), ToolFailure):
+                return True
+    return False

package/artemis-main/artemis/data_engine/context_vars.py

@@ -0,0 +1,24 @@
+# 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.
+
+"""Context variables for Artemis DataEngine runtime tracing."""
+
+import contextvars
+
+CURRENT_TRACE_ID: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_trace_id", default=None
+)
+CURRENT_NODE_NAME: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_node_name", default=None
+)