feat: introduce MCP server, cross-platform runtime, and Showcase UI reorganization

- Showcase UI Reorganization:
  * Move web UI dashboard from root directory into apps/showcase_ui/ for cleaner project structure
  * Add 'artemis ui' CLI command (artemis/interfaces/cli/commands/ui.py) and launcher scripts for the interactive showcase console
- Standalone MCP Server & Notifiers (mcp_server/):
  * Implement dedicated MCP server package with mobile automation tools (device_state, inspect_trace, task_manager, task_runner)
  * Add multi-channel notifiers (AgentAPI, Desktop notifications, Webhooks, File output, and Composite routing)
  * Introduce background task runner and trace store for autonomous mobile execution monitoring
- Cross-Platform Runtime & Toolchain Support:
  * Add artemis/platform/ with OS-specific implementations for Linux, macOS (Darwin), and Windows
  * Add artemis/runtime/supervisor.py for resilient process and agent runtime supervision
  * Add artemis/toolchain/ with dependency resolution and SDK descriptors
  * Add cross-platform launcher scripts (start.sh, start.bat) and installer scripts (scripts/install_deps.*)
- Core Enhancements & Diagnostics:
  * Enhance coordinate normalization, OCR API fallback, and perception pipeline
  * Add credential validation (credentials_validator.py) and system diagnostics
  * Update bilingual documentation (README.md, README_CN.md) and architecture diagrams
- Test Suite Expansion:
  * Add integration tests for cloud gateway, remote ADB, and Artemis login
  * Add unit tests covering core diagnostics, platform detection, toolchain, credentials validator, optional OCR, and MCP tools

artemis/platform/__init__.py

@@ -0,0 +1,61 @@
+# 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.
+
+"""Platform Abstraction Layer (PAL) single entry point and global singleton."""
+
+import sys
+
+from artemis.platform.base import (
+    IPlatform,
+    IPlatformPaths,
+    IPlatformProcess,
+    OSType,
+)
+from artemis.platform.darwin import DarwinPlatform
+from artemis.platform.linux import LinuxPlatform
+from artemis.platform.windows import WindowsPlatform
+
+
+def _create_platform() -> IPlatform:
+    """Factory creating the appropriate platform instance for current runtime environment."""
+    if sys.platform == "win32":
+        p = WindowsPlatform()
+    elif sys.platform == "darwin":
+        p = DarwinPlatform()
+    else:
+        p = LinuxPlatform()
+
+    # Automatically initialize UTF-8 environment
+    p.process.setup_utf8_io()
+    return p
+
+
+# Global singleton PAL instance
+platform: IPlatform = _create_platform()
+
+
+def get_platform() -> IPlatform:
+    """Get the active platform abstraction instance."""
+    global platform
+    return platform
+
+
+__all__ = [
+    "platform",
+    "get_platform",
+    "OSType",
+    "IPlatform",
+    "IPlatformPaths",
+    "IPlatformProcess",
+]

artemis/platform/base.py

@@ -0,0 +1,104 @@
+# 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.
+
+"""Platform Abstraction Layer (PAL) - Base Protocols and Types."""
+
+from enum import Enum
+from pathlib import Path
+from typing import Protocol
+
+
+class OSType(str, Enum):
+    """Operating System Type."""
+
+    LINUX = "linux"
+    MACOS = "darwin"
+    WINDOWS = "windows"
+    UNKNOWN = "unknown"
+
+
+class IPlatformPaths(Protocol):
+    """Standardized directory and path resolver for the target operating system."""
+
+    @property
+    def config_dir(self) -> Path:
+        """Directory for persistent user/app configuration files."""
+        ...
+
+    @property
+    def data_dir(self) -> Path:
+        """Directory for persistent data (traces, SQLite DBs, replays)."""
+        ...
+
+    @property
+    def cache_dir(self) -> Path:
+        """Directory for non-essential cached data."""
+        ...
+
+    @property
+    def logs_dir(self) -> Path:
+        """Directory for persistent runtime logs."""
+        ...
+
+    def temp_dir(self, subfolder: str | None = None) -> Path:
+        """Unified temporary files directory for screenshots, recordings, and scratchpads."""
+        ...
+
+    def resolve_app_dir(self) -> Path:
+        """Resolved central application root directory for backwards compatibility."""
+        ...
+
+
+class IPlatformProcess(Protocol):
+    """Platform-specific process management, signals, and stream handling."""
+
+    @property
+    def path_separator(self) -> str:
+        """Separator character used for PATH and PYTHONPATH (':' on POSIX, ';' on Windows)."""
+        ...
+
+    def terminate_process_tree(self, pid: int, timeout_seconds: float = 3.0) -> bool:
+        """Safely and recursively terminate a process and all its child processes."""
+        ...
+
+    def setup_utf8_io(self) -> None:
+        """Ensure standard I/O and process streams operate in UTF-8 mode."""
+        ...
+
+
+class IPlatform(Protocol):
+    """Unified Platform Abstraction Layer interface."""
+
+    @property
+    def os_type(self) -> OSType:
+        """Operating system type identifier."""
+        ...
+
+    @property
+    def paths(self) -> IPlatformPaths:
+        """Platform paths resolver."""
+        ...
+
+    @property
+    def process(self) -> IPlatformProcess:
+        """Platform process and execution manager."""
+        ...
+
+    def get_package_manager_name(self) -> str | None:
+        """Name of the detected preferred package manager (e.g. apt, brew, winget)."""
+        ...
+
+    def get_install_command(self, tool_name: str) -> str:
+        """Generate platform-specific installation command for a missing tool."""
+        ...

artemis/platform/darwin.py

@@ -0,0 +1,150 @@
+# 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.
+
+"""macOS Platform Implementation (Apple Filesystem Hierarchy & Homebrew Integration)."""
+
+import os
+from pathlib import Path
+import shutil
+import signal
+import tempfile
+
+from artemis.platform.base import IPlatform, IPlatformPaths, IPlatformProcess, OSType
+
+
+class DarwinPlatformPaths(IPlatformPaths):
+    """macOS paths adhering to Apple standard Library/Application Support structure."""
+
+    def __init__(self):
+        self._home = Path.home()
+
+    @property
+    def config_dir(self) -> Path:
+        p = self._home / "Library" / "Application Support" / "artemis"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def data_dir(self) -> Path:
+        env_dir = os.getenv("ARTEMIS_APP_DIR") or os.getenv("ANTIGRAVITY_APP_DIR")
+        if env_dir:
+            p = Path(env_dir)
+            p.mkdir(parents=True, exist_ok=True)
+            return p
+
+        # Check legacy ~/.artemis or ~/.gemini/jetski directory if it exists
+        legacy_artemis = self._home / ".artemis"
+        if legacy_artemis.exists():
+            return legacy_artemis
+
+        legacy_jetski = self._home / ".gemini" / "jetski"
+        if legacy_jetski.exists():
+            return legacy_jetski
+
+        p = self._home / "Library" / "Application Support" / "artemis"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def cache_dir(self) -> Path:
+        p = self._home / "Library" / "Caches" / "artemis"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def logs_dir(self) -> Path:
+        p = self._home / "Library" / "Logs" / "artemis"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    def temp_dir(self, subfolder: str | None = None) -> Path:
+        base = Path(tempfile.gettempdir()) / "artemis"
+        target = base / subfolder if subfolder else base
+        target.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def resolve_app_dir(self) -> Path:
+        return self.data_dir
+
+
+class DarwinPlatformProcess(IPlatformProcess):
+    """macOS process management."""
+
+    @property
+    def path_separator(self) -> str:
+        return ":"
+
+    def terminate_process_tree(self, pid: int, timeout_seconds: float = 3.0) -> bool:
+        try:
+            import psutil
+
+            parent = psutil.Process(pid)
+            children = parent.children(recursive=True)
+            for child in children:
+                try:
+                    child.send_signal(signal.SIGTERM)
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    pass
+
+            parent.send_signal(signal.SIGTERM)
+            gone, alive = psutil.wait_procs(children + [parent], timeout=timeout_seconds)
+            for p in alive:
+                try:
+                    p.kill()
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    pass
+            return True
+        except Exception:
+            try:
+                os.kill(pid, signal.SIGKILL)
+                return True
+            except OSError:
+                return False
+
+    def setup_utf8_io(self) -> None:
+        pass
+
+
+class DarwinPlatform(IPlatform):
+    """macOS Platform Adapter."""
+
+    def __init__(self):
+        self._paths = DarwinPlatformPaths()
+        self._process = DarwinPlatformProcess()
+
+    @property
+    def os_type(self) -> OSType:
+        return OSType.MACOS
+
+    @property
+    def paths(self) -> IPlatformPaths:
+        return self._paths
+
+    @property
+    def process(self) -> IPlatformProcess:
+        return self._process
+
+    def get_package_manager_name(self) -> str | None:
+        if shutil.which("brew"):
+            return "brew"
+        return None
+
+    def get_install_command(self, tool_name: str) -> str:
+        pkg_map = {
+            "adb": "android-platform-tools",
+            "ffmpeg": "ffmpeg",
+            "scrcpy": "scrcpy",
+        }
+        pkg = pkg_map.get(tool_name, tool_name)
+        return f"brew install {pkg}"

artemis/platform/linux.py

@@ -0,0 +1,173 @@
+# 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.
+
+"""Linux Platform Implementation (XDG Base Directory Specification & POSIX Process Model)."""
+
+import os
+from pathlib import Path
+import shutil
+import signal
+import tempfile
+
+from artemis.platform.base import IPlatform, IPlatformPaths, IPlatformProcess, OSType
+
+
+class LinuxPlatformPaths(IPlatformPaths):
+    """Linux paths adhering to the XDG Base Directory specification with legacy fallbacks."""
+
+    def __init__(self):
+        self._home = Path.home()
+
+    @property
+    def config_dir(self) -> Path:
+        xdg_config = os.getenv("XDG_CONFIG_HOME")
+        if xdg_config:
+            p = Path(xdg_config) / "artemis"
+        else:
+            p = self._home / ".config" / "artemis"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def data_dir(self) -> Path:
+        # Check custom app dir override first
+        env_dir = os.getenv("ARTEMIS_APP_DIR") or os.getenv("ANTIGRAVITY_APP_DIR")
+        if env_dir:
+            p = Path(env_dir)
+            p.mkdir(parents=True, exist_ok=True)
+            return p
+
+        xdg_data = os.getenv("XDG_DATA_HOME")
+        if xdg_data:
+            p = Path(xdg_data) / "artemis"
+            p.mkdir(parents=True, exist_ok=True)
+            return p
+
+        # Check legacy ~/.gemini/jetski or ~/.artemis directory if it exists
+        legacy_jetski = self._home / ".gemini" / "jetski"
+        if legacy_jetski.exists():
+            return legacy_jetski
+
+        legacy_artemis = self._home / ".artemis"
+        if legacy_artemis.exists():
+            return legacy_artemis
+
+        p = self._home / ".local" / "share" / "artemis"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def cache_dir(self) -> Path:
+        xdg_cache = os.getenv("XDG_CACHE_HOME")
+        if xdg_cache:
+            p = Path(xdg_cache) / "artemis"
+        else:
+            p = self._home / ".cache" / "artemis"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def logs_dir(self) -> Path:
+        p = self.data_dir / "logs"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    def temp_dir(self, subfolder: str | None = None) -> Path:
+        base = Path(tempfile.gettempdir()) / "artemis"
+        target = base / subfolder if subfolder else base
+        target.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def resolve_app_dir(self) -> Path:
+        return self.data_dir
+
+
+class LinuxPlatformProcess(IPlatformProcess):
+    """Linux process management using POSIX signals and process groups."""
+
+    @property
+    def path_separator(self) -> str:
+        return ":"
+
+    def terminate_process_tree(self, pid: int, timeout_seconds: float = 3.0) -> bool:
+        try:
+            import psutil
+
+            parent = psutil.Process(pid)
+            children = parent.children(recursive=True)
+            for child in children:
+                try:
+                    child.send_signal(signal.SIGTERM)
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    pass
+
+            parent.send_signal(signal.SIGTERM)
+            gone, alive = psutil.wait_procs(children + [parent], timeout=timeout_seconds)
+            for p in alive:
+                try:
+                    p.kill()
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    pass
+            return True
+        except Exception:
+            try:
+                os.kill(pid, signal.SIGKILL)
+                return True
+            except OSError:
+                return False
+
+    def setup_utf8_io(self) -> None:
+        pass
+
+
+class LinuxPlatform(IPlatform):
+    """Linux Platform Adapter."""
+
+    def __init__(self):
+        self._paths = LinuxPlatformPaths()
+        self._process = LinuxPlatformProcess()
+
+    @property
+    def os_type(self) -> OSType:
+        return OSType.LINUX
+
+    @property
+    def paths(self) -> IPlatformPaths:
+        return self._paths
+
+    @property
+    def process(self) -> IPlatformProcess:
+        return self._process
+
+    def get_package_manager_name(self) -> str | None:
+        for pm in ("apt-get", "dnf", "pacman", "zypper"):
+            if shutil.which(pm):
+                return pm
+        return None
+
+    def get_install_command(self, tool_name: str) -> str:
+        pm = self.get_package_manager_name()
+        pkg_map = {
+            "adb": {"apt-get": "adb", "dnf": "android-tools", "pacman": "android-tools"},
+            "ffmpeg": {"apt-get": "ffmpeg", "dnf": "ffmpeg", "pacman": "ffmpeg"},
+            "scrcpy": {"apt-get": "scrcpy", "dnf": "scrcpy", "pacman": "scrcpy"},
+        }
+        pkg = pkg_map.get(tool_name, {}).get(pm, tool_name)
+        if pm == "apt-get":
+            return f"sudo apt-get install -y {pkg}"
+        elif pm == "dnf":
+            return f"sudo dnf install -y {pkg}"
+        elif pm == "pacman":
+            return f"sudo pacman -S --noconfirm {pkg}"
+        return f"Install {tool_name} using your system package manager."

artemis/platform/windows.py

@@ -0,0 +1,190 @@
+# 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.
+
+"""Windows Platform Implementation (KnownFolders/AppData, Win32 Process Tree & UTF-8 Injection)."""
+
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+
+from artemis.platform.base import IPlatform, IPlatformPaths, IPlatformProcess, OSType
+
+
+class WindowsPlatformPaths(IPlatformPaths):
+    """Windows paths adhering to KnownFolders (%APPDATA% / %LOCALAPPDATA%)."""
+
+    def __init__(self):
+        self._home = Path.home()
+
+    @property
+    def config_dir(self) -> Path:
+        appdata = os.getenv("APPDATA")
+        if appdata:
+            p = Path(appdata) / "Artemis"
+        else:
+            p = self._home / "AppData" / "Roaming" / "Artemis"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def data_dir(self) -> Path:
+        env_dir = os.getenv("ARTEMIS_APP_DIR") or os.getenv("ANTIGRAVITY_APP_DIR")
+        if env_dir:
+            p = Path(env_dir)
+            p.mkdir(parents=True, exist_ok=True)
+            return p
+
+        local_appdata = os.getenv("LOCALAPPDATA")
+        if local_appdata:
+            p = Path(local_appdata) / "Artemis"
+            p.mkdir(parents=True, exist_ok=True)
+            return p
+
+        legacy_jetski = self._home / ".gemini" / "jetski"
+        if legacy_jetski.exists():
+            return legacy_jetski
+
+        legacy_artemis = self._home / ".artemis"
+        if legacy_artemis.exists():
+            return legacy_artemis
+
+        p = self._home / "AppData" / "Local" / "Artemis"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def cache_dir(self) -> Path:
+        p = self.data_dir / "cache"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def logs_dir(self) -> Path:
+        p = self.data_dir / "logs"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    def temp_dir(self, subfolder: str | None = None) -> Path:
+        base = Path(tempfile.gettempdir()) / "artemis"
+        target = base / subfolder if subfolder else base
+        target.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def resolve_app_dir(self) -> Path:
+        return self.data_dir
+
+
+class WindowsPlatformProcess(IPlatformProcess):
+    """Windows process management with tree termination and UTF-8 console streams."""
+
+    @property
+    def path_separator(self) -> str:
+        return ";"
+
+    def terminate_process_tree(self, pid: int, timeout_seconds: float = 3.0) -> bool:
+        # 1. Try taskkill /F /T /PID on Windows (fastest and cleanest for process trees)
+        try:
+            res = subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(pid)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=False,
+                timeout=timeout_seconds,
+            )
+            if res.returncode == 0:
+                return True
+        except Exception:
+            pass
+
+        # 2. Fallback to psutil
+        try:
+            import psutil
+
+            parent = psutil.Process(pid)
+            children = parent.children(recursive=True)
+            for child in children:
+                try:
+                    child.kill()
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    pass
+            parent.kill()
+            return True
+        except Exception:
+            return False
+
+    def setup_utf8_io(self) -> None:
+        """Configures Windows stdout/stderr to UTF-8 mode to prevent encoding crashes."""
+        if hasattr(sys.stdout, "reconfigure"):
+            try:
+                sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+        if hasattr(sys.stderr, "reconfigure"):
+            try:
+                sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+        os.environ["PYTHONUTF8"] = "1"
+
+
+class WindowsPlatform(IPlatform):
+    """Windows Platform Adapter."""
+
+    def __init__(self):
+        self._paths = WindowsPlatformPaths()
+        self._process = WindowsPlatformProcess()
+
+    @property
+    def os_type(self) -> OSType:
+        return OSType.WINDOWS
+
+    @property
+    def paths(self) -> IPlatformPaths:
+        return self._paths
+
+    @property
+    def process(self) -> IPlatformProcess:
+        return self._process
+
+    def get_package_manager_name(self) -> str | None:
+        for pm in ("winget", "choco", "scoop"):
+            if shutil.which(pm):
+                return pm
+        return None
+
+    def get_install_command(self, tool_name: str) -> str:
+        pm = self.get_package_manager_name() or "winget"
+        pkg_map = {
+            "adb": {
+                "winget": "winget install Google.PlatformTools",
+                "choco": "choco install adb",
+                "scoop": "scoop install adb",
+            },
+            "ffmpeg": {
+                "winget": "winget install Gyan.FFmpeg",
+                "choco": "choco install ffmpeg",
+                "scoop": "scoop install ffmpeg",
+            },
+            "scrcpy": {
+                "winget": "winget install Genymobile.scrcpy",
+                "choco": "choco install scrcpy",
+                "scoop": "scoop install scrcpy",
+            },
+        }
+        if tool_name in pkg_map and pm in pkg_map[tool_name]:
+            return pkg_map[tool_name][pm]
+        return f"winget install {tool_name} (or download official installer)"