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
2026-08-18 13:59:27 -07:00
1 parent 78e478f502
commit 9a5aaf99b7
@@ -0,0 +1,66 @@
+# 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.
+
+"""Universal MCP Multi-Environment Notification System."""
+
+from typing import Any, Dict, Optional
+
+from mcp_server.notifiers.agentapi import AgentApiNotifier
+from mcp_server.notifiers.base import BaseNotifier
+from mcp_server.notifiers.composite import CompositeNotifier
+from mcp_server.notifiers.desktop import DesktopNotifier
+from mcp_server.notifiers.file import FileNotifier
+from mcp_server.notifiers.webhook import WebhookNotifier
+
+_default_notifier = CompositeNotifier()
+
+
+def get_default_notifier() -> CompositeNotifier:
+    """Returns the global default composite notifier instance."""
+    return _default_notifier
+
+
+def notify(
+    conversation_id: str,
+    message: str,
+    title: str | None = None,
+    event_type: str = "completed",
+    payload: dict[str, Any] | None = None,
+) -> bool:
+    """Dispatches a notification across all available channels (AgentAPI, Webhook, Desktop, File)."""
+    return _default_notifier.notify(
+        conversation_id=conversation_id,
+        message=message,
+        title=title,
+        event_type=event_type,
+        payload=payload,
+    )
+
+
+def notify_jetski(conversation_id: str, message: str) -> bool:
+    """Backward-compatible alias for notify()."""
+    return notify(conversation_id=conversation_id, message=message, event_type="completed")
+
+
+__all__ = [
+    "BaseNotifier",
+    "AgentApiNotifier",
+    "WebhookNotifier",
+    "DesktopNotifier",
+    "FileNotifier",
+    "CompositeNotifier",
+    "get_default_notifier",
+    "notify",
+    "notify_jetski",
+]
@@ -0,0 +1,170 @@
+# 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.
+
+"""AgentAPI Notifier for Jetski / Antigravity environments."""
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+from typing import Any
+
+from mcp_server.notifiers.base import BaseNotifier
+
+logger = logging.getLogger("mcp_server.notifiers.agentapi")
+
+
+class AgentApiNotifier(BaseNotifier):
+    """Notifier implementation for environments supporting the agentapi CLI (e.g. Jetski / Antigravity)."""
+
+    @property
+    def name(self) -> str:
+        return "agentapi"
+
+    def _find_agentapi_path(self) -> str | None:
+        """Locates the agentapi executable."""
+        which_path = shutil.which("agentapi")
+        if which_path:
+            return which_path
+
+        candidates = [
+            os.path.expanduser("~/.gemini/jetski/bin/agentapi"),
+            os.path.expanduser("~/.artemis/bin/agentapi"),
+            os.path.expanduser("~/bin/agentapi"),
+            "/usr/local/bin/agentapi",
+        ]
+        for cand in candidates:
+            if os.path.exists(cand) and os.access(cand, os.X_OK):
+                return cand
+        return None
+
+    def is_available(self) -> bool:
+        """Returns True if agentapi binary exists or LS address is detected."""
+        if self._find_agentapi_path():
+            return True
+        if "ANTIGRAVITY_LS_ADDRESS" in os.environ:
+            return True
+        return False
+
+    def _load_shared_env(self, force_proc_scan: bool = False) -> None:
+        """Recovers and loads ANTIGRAVITY_LS_ADDRESS and ANTIGRAVITY_CSRF_TOKEN."""
+        if not force_proc_scan:
+            try:
+                shared_candidates = [
+                    os.path.expanduser("~/.gemini/jetski/.jetski_env"),
+                    os.path.expanduser("~/.artemis/.artemis_env"),
+                ]
+                # Project root fallback
+                parent_dir = os.path.dirname(
+                    os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+                )
+                shared_candidates.append(os.path.join(parent_dir, ".jetski_env"))
+
+                for shared_file in shared_candidates:
+                    if os.path.exists(shared_file):
+                        with open(shared_file, encoding="utf-8") as f:
+                            env_data = json.load(f)
+                        for key, val in env_data.items():
+                            if val:
+                                os.environ[key] = val
+                                logger.debug(f"[EnvRecovery] Loaded {key} from {shared_file}.")
+                        return
+            except Exception as e:
+                logger.debug(f"[EnvRecovery] Error reading shared env file: {e}")
+
+        # Fallback to psutil process scan
+        logger.debug("[EnvRecovery] Scanning process table for active agent session...")
+        found_addr = None
+        found_token = None
+
+        try:
+            import psutil
+
+            for proc in psutil.process_iter(["environ"]):
+                try:
+                    env = proc.info.get("environ")
+                    if env and "ANTIGRAVITY_LS_ADDRESS" in env and "ANTIGRAVITY_CSRF_TOKEN" in env:
+                        found_addr = env["ANTIGRAVITY_LS_ADDRESS"]
+                        found_token = env["ANTIGRAVITY_CSRF_TOKEN"]
+                        break
+                except (psutil.AccessDenied, psutil.NoSuchProcess):
+                    continue
+        except ImportError:
+            # Fallback on Linux /proc
+            import glob
+
+            for env_path in glob.glob("/proc/[0-9]*/environ"):
+                try:
+                    with open(env_path, "rb") as f:
+                        content = f.read()
+                    env_vars = content.split(b"\x00")
+                    local_addr = None
+                    local_token = None
+                    for var in env_vars:
+                        if var.startswith(b"ANTIGRAVITY_LS_ADDRESS="):
+                            local_addr = var.split(b"=", 1)[1].decode("utf-8", errors="ignore")
+                        elif var.startswith(b"ANTIGRAVITY_CSRF_TOKEN="):
+                            local_token = var.split(b"=", 1)[1].decode("utf-8", errors="ignore")
+                    if local_addr and local_token:
+                        found_addr = local_addr
+                        found_token = local_token
+                        break
+                except Exception:
+                    pass
+
+        if found_addr and found_token:
+            os.environ["ANTIGRAVITY_LS_ADDRESS"] = found_addr
+            os.environ["ANTIGRAVITY_CSRF_TOKEN"] = found_token
+            logger.debug(f"[EnvRecovery] Recovered session from process. Address: {found_addr}")
+
+    def notify(
+        self,
+        conversation_id: str,
+        message: str,
+        title: str | None = None,
+        event_type: str = "completed",
+        payload: dict[str, Any] | None = None,
+    ) -> bool:
+        """Dispatches a notification via the agentapi send-message command."""
+        if not conversation_id or conversation_id.lower() in ("default", "none", ""):
+            return False
+
+        agentapi_path = self._find_agentapi_path()
+        if not agentapi_path:
+            return False
+
+        if "ANTIGRAVITY_LS_ADDRESS" not in os.environ or "ANTIGRAVITY_CSRF_TOKEN" not in os.environ:
+            self._load_shared_env()
+
+        cmd = [agentapi_path, "send-message"]
+        if title:
+            cmd.extend(["--title", title])
+        cmd.extend([conversation_id, message])
+
+        try:
+            subprocess.run(cmd, capture_output=True, text=True, check=True, timeout=10)
+            logger.info("AgentAPI notification sent successfully.")
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError, Exception):
+            try:
+                self._load_shared_env(force_proc_scan=True)
+                if "ANTIGRAVITY_LS_ADDRESS" in os.environ:
+                    subprocess.run(cmd, capture_output=True, text=True, check=True, timeout=10)
+                    logger.info("AgentAPI notification sent successfully on retry.")
+                    return True
+            except Exception as retry_err:
+                logger.debug(f"AgentAPI notification retry failed: {retry_err}")
+                return False
+        return False
@@ -0,0 +1,45 @@
+# 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.
+
+"""Base interface for MCP notification adapters."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseNotifier(ABC):
+    """Abstract base class for environment notification providers."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Name of the notifier adapter."""
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Checks if the notifier is configured and available in the current runtime environment."""
+        pass
+
+    @abstractmethod
+    def notify(
+        self,
+        conversation_id: str,
+        message: str,
+        title: str | None = None,
+        event_type: str = "completed",
+        payload: dict[str, Any] | None = None,
+    ) -> bool:
+        """Sends a notification to the target conversation / client."""
+        pass
@@ -0,0 +1,78 @@
+# 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.
+
+"""Composite Notifier coordinating multi-channel notifications."""
+
+import logging
+from typing import Any
+
+from mcp_server.notifiers.agentapi import AgentApiNotifier
+from mcp_server.notifiers.base import BaseNotifier
+from mcp_server.notifiers.desktop import DesktopNotifier
+from mcp_server.notifiers.file import FileNotifier
+from mcp_server.notifiers.webhook import WebhookNotifier
+
+logger = logging.getLogger("mcp_server.notifiers.composite")
+
+
+class CompositeNotifier(BaseNotifier):
+    """Aggregates multiple notifiers and broadcasts events across all available channels."""
+
+    def __init__(self, notifiers: list[BaseNotifier] | None = None):
+        if notifiers is not None:
+            self._notifiers = notifiers
+        else:
+            self._notifiers = [
+                FileNotifier(),
+                AgentApiNotifier(),
+                WebhookNotifier(),
+                DesktopNotifier(),
+            ]
+
+    @property
+    def name(self) -> str:
+        return "composite"
+
+    def is_available(self) -> bool:
+        return any(n.is_available() for n in self._notifiers)
+
+    def register_notifier(self, notifier: BaseNotifier) -> None:
+        """Registers an additional custom notifier."""
+        self._notifiers.append(notifier)
+
+    def notify(
+        self,
+        conversation_id: str,
+        message: str,
+        title: str | None = None,
+        event_type: str = "completed",
+        payload: dict[str, Any] | None = None,
+    ) -> bool:
+        any_success = False
+        for notifier in self._notifiers:
+            if notifier.is_available():
+                try:
+                    success = notifier.notify(
+                        conversation_id=conversation_id,
+                        message=message,
+                        title=title,
+                        event_type=event_type,
+                        payload=payload,
+                    )
+                    if success:
+                        any_success = True
+                except Exception as e:
+                    logger.debug(f"Notifier '{notifier.name}' encountered error: {e}")
+
+        return any_success
@@ -0,0 +1,92 @@
+# 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.
+
+"""Desktop Toast / OS notification adapter."""
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from typing import Any
+
+from mcp_server.notifiers.base import BaseNotifier
+
+logger = logging.getLogger("mcp_server.notifiers.desktop")
+
+
+class DesktopNotifier(BaseNotifier):
+    """Notifier that displays native desktop notifications when explicitly enabled."""
+
+    @property
+    def name(self) -> str:
+        return "desktop"
+
+    def is_available(self) -> bool:
+        return os.getenv("ARTEMIS_DESKTOP_NOTIFY", "").lower() in ("1", "true", "yes")
+
+    def notify(
+        self,
+        conversation_id: str,
+        message: str,
+        title: str | None = None,
+        event_type: str = "completed",
+        payload: dict[str, Any] | None = None,
+    ) -> bool:
+        if not self.is_available():
+            return False
+
+        header = title or f"☕ Artemis Task {event_type.capitalize()}"
+        clean_body = message.split("\n\n")[0][:120]
+
+        try:
+            if sys.platform == "linux":
+                if shutil.which("notify-send"):
+                    subprocess.run(
+                        ["notify-send", header, clean_body],
+                        stdout=subprocess.DEVNULL,
+                        stderr=subprocess.DEVNULL,
+                        timeout=3,
+                    )
+                    return True
+            elif sys.platform == "darwin":
+                if shutil.which("osascript"):
+                    script = f'display notification "{clean_body}" with title "{header}"'
+                    subprocess.run(
+                        ["osascript", "-e", script],
+                        stdout=subprocess.DEVNULL,
+                        stderr=subprocess.DEVNULL,
+                        timeout=3,
+                    )
+                    return True
+            elif sys.platform == "win32":
+                ps_cmd = (
+                    f"[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null; "
+                    f"$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02); "
+                    f'$textNodes = $template.GetElementsByTagName("text"); '
+                    f'$textNodes.Item(0).AppendChild($template.CreateTextNode("{header}")) > $null; '
+                    f'$textNodes.Item(1).AppendChild($template.CreateTextNode("{clean_body}")) > $null; '
+                    f"$toast = [Windows.UI.Notifications.ToastNotification]::new($template); "
+                    f'[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Artemis").Show($toast);'
+                )
+                subprocess.run(
+                    ["powershell", "-NoProfile", "-Command", ps_cmd],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=5,
+                )
+                return True
+        except Exception as e:
+            logger.debug(f"Desktop notification failed: {e}")
+        return False
@@ -0,0 +1,69 @@
+# 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.
+
+"""File-based notification recorder."""
+
+import json
+import logging
+import os
+import time
+from typing import Any
+
+from mcp_server.notifiers.base import BaseNotifier
+from mcp_server.utils import trace_store
+
+logger = logging.getLogger("mcp_server.notifiers.file")
+
+
+class FileNotifier(BaseNotifier):
+    """Notifier that records all notification events directly to the trace directory."""
+
+    @property
+    def name(self) -> str:
+        return "file"
+
+    def is_available(self) -> bool:
+        return True
+
+    def notify(
+        self,
+        conversation_id: str,
+        message: str,
+        title: str | None = None,
+        event_type: str = "completed",
+        payload: dict[str, Any] | None = None,
+    ) -> bool:
+        trace_id = (payload or {}).get("trace_id")
+        if not trace_id:
+            return False
+
+        try:
+            trace_dir = trace_store.get_trace_dir(trace_id)
+            os.makedirs(trace_dir, exist_ok=True)
+            log_file = os.path.join(trace_dir, "notifications.jsonl")
+
+            entry = {
+                "timestamp": time.time(),
+                "event_type": event_type,
+                "title": title,
+                "conversation_id": conversation_id,
+                "message": message,
+                "payload": payload or {},
+            }
+            with open(log_file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+            return True
+        except Exception as e:
+            logger.debug(f"File notification record failed: {e}")
+            return False
@@ -0,0 +1,87 @@
+# 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.
+
+"""Webhook Notifier for OpenClaw, CI pipelines, and external gateways."""
+
+import json
+import logging
+import os
+import time
+from typing import Any
+import urllib.request
+
+from mcp_server.notifiers.base import BaseNotifier
+
+logger = logging.getLogger("mcp_server.notifiers.webhook")
+
+
+class WebhookNotifier(BaseNotifier):
+    """Notifier that posts execution events to HTTP/HTTPS webhooks (e.g. OpenClaw / CI / Slack)."""
+
+    ENV_VARS = [
+        "OPENCLAW_WEBHOOK_URL",
+        "MCP_NOTIFICATION_WEBHOOK",
+        "ARTEMIS_WEBHOOK_URL",
+    ]
+
+    @property
+    def name(self) -> str:
+        return "webhook"
+
+    def _get_webhook_url(self) -> str | None:
+        for var in self.ENV_VARS:
+            val = os.getenv(var)
+            if val and val.startswith(("http://", "https://")):
+                return val
+        return None
+
+    def is_available(self) -> bool:
+        return self._get_webhook_url() is not None
+
+    def notify(
+        self,
+        conversation_id: str,
+        message: str,
+        title: str | None = None,
+        event_type: str = "completed",
+        payload: dict[str, Any] | None = None,
+    ) -> bool:
+        url = self._get_webhook_url()
+        if not url:
+            return False
+
+        data = {
+            "event": event_type,
+            "title": title or f"Artemis Task {event_type.capitalize()}",
+            "conversation_id": conversation_id,
+            "message": message,
+            "timestamp": time.time(),
+            "payload": payload or {},
+        }
+
+        try:
+            req_data = json.dumps(data).encode("utf-8")
+            req = urllib.request.Request(
+                url,
+                data=req_data,
+                headers={"Content-Type": "application/json", "User-Agent": "Artemis-MCP/3.0"},
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=5) as response:
+                if response.status in (200, 201, 202, 204):
+                    logger.info(f"Webhook notification delivered to {url}.")
+                    return True
+        except Exception as e:
+            logger.warning(f"Failed to deliver webhook notification to {url}: {e}")
+        return False