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,63 @@
+# 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.
+
+"""Unit tests for backward compatibility layer with legacy 'jetski' imports."""
+
+import importlib.util
+import pytest
+
+if not importlib.util.find_spec("jetski"):
+    pytest.skip("Legacy 'jetski' package not installed", allow_module_level=True)
+
+
+def test_legacy_jetski_mcp_imports():
+    from jetski.mcp.base import mcp as jetski_mcp
+    from mcp_server.base import mcp as mcp_server_mcp
+
+    assert jetski_mcp is mcp_server_mcp
+
+
+def test_legacy_jetski_tools_imports():
+    from jetski.mcp.tools.task_runner import mobile_run_task as j_run
+    from mcp_server.tools.task_runner import mobile_run_task as a_run
+
+    assert j_run is a_run
+
+    from jetski.mcp.tools.task_manager import mobile_manage_task as j_manage
+    from mcp_server.tools.task_manager import mobile_manage_task as a_manage
+
+    assert j_manage is a_manage
+
+    from jetski.mcp.tools.device_state import mobile_get_device_state as j_dev
+    from mcp_server.tools.device_state import mobile_get_device_state as a_dev
+
+    assert j_dev is a_dev
+
+    from jetski.mcp.tools.inspect_trace import mobile_inspect_trace as j_insp
+    from mcp_server.tools.inspect_trace import mobile_inspect_trace as a_insp
+
+    assert j_insp is a_insp
+
+
+def test_legacy_jetski_utils_imports():
+    from jetski.utils.trace_store import init_trace
+    from mcp_server.utils.trace_store import init_trace as a_init
+
+    assert init_trace is a_init
+
+    from jetski.utils.notifier import notify, notify_jetski
+    from mcp_server.notifiers import notify as a_notify
+
+    assert notify is a_notify
+    assert callable(notify_jetski)
@@ -0,0 +1,113 @@
+# 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.
+
+"""Unit tests for Artemis MCP Tools."""
+
+import inspect
+import shutil
+import tempfile
+import uuid
+import pytest
+
+from mcp_server.tools import (
+    mobile_get_device_state,
+    mobile_inspect_trace,
+    mobile_manage_task,
+    mobile_run_task,
+)
+from mcp_server.utils import trace_store
+
+
+@pytest.fixture
+def temp_trace_env(monkeypatch):
+    temp_dir = tempfile.mkdtemp()
+    monkeypatch.setattr(trace_store, "TRACES_DIR", temp_dir)
+    yield temp_dir
+    shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+def test_tool_signatures():
+    # mobile_run_task signature check
+    sig_run = inspect.signature(mobile_run_task)
+    assert "task_desc" in sig_run.parameters
+    assert "conversation_id" in sig_run.parameters
+    assert "model" in sig_run.parameters
+    assert "locked_app_package" in sig_run.parameters
+    assert "app_path" in sig_run.parameters
+    assert "expected_output_desc" in sig_run.parameters
+
+    # mobile_manage_task signature check
+    sig_manage = inspect.signature(mobile_manage_task)
+    assert "action" in sig_manage.parameters
+    assert "trace_id" in sig_manage.parameters
+    assert "instruction" in sig_manage.parameters
+
+    # mobile_get_device_state signature check
+    sig_device = inspect.signature(mobile_get_device_state)
+    assert "view_type" in sig_device.parameters
+
+    # mobile_inspect_trace signature check
+    sig_inspect = inspect.signature(mobile_inspect_trace)
+    assert "action" in sig_inspect.parameters
+    assert "trace_id" in sig_inspect.parameters
+    assert "step_number" in sig_inspect.parameters
+
+
+def test_mobile_run_task_invalid_model():
+    with pytest.raises(ValueError, match="Invalid model"):
+        mobile_run_task(task_desc="test", conversation_id="conv-1", model="invalid_model")
+
+
+def test_mobile_manage_task_unknown_trace(temp_trace_env):
+    res = mobile_manage_task(action="status", trace_id="non-existent-trace")
+    assert res["status"] == "unknown"
+    assert "not found" in res["message"]
+
+
+def test_mobile_manage_task_status_and_stop(temp_trace_env):
+    trace_id = str(uuid.uuid4())
+    trace_store.init_trace(trace_id, "Test task", "Flash", "conv-1")
+
+    # Status check
+    status_res = mobile_manage_task(action="status", trace_id=trace_id)
+    assert status_res["trace_id"] == trace_id
+    assert status_res["status"] == "running"
+    assert status_res["model"] == "Flash"
+
+    # Stop without PID
+    stop_res = mobile_manage_task(action="stop", trace_id=trace_id)
+    assert stop_res["trace_id"] == trace_id
+    assert "PID" in stop_res["message"] or "Cannot stop" in stop_res["message"]
+
+
+def test_mobile_manage_task_inject_instruction(temp_trace_env):
+    trace_id = str(uuid.uuid4())
+    trace_store.init_trace(trace_id, "Test task", "Pro", "conv-1")
+
+    # Missing instruction parameter
+    err_res = mobile_manage_task(action="inject_instruction", trace_id=trace_id)
+    assert "Missing required argument" in err_res["message"]
+
+    # Valid injection
+    ok_res = mobile_manage_task(
+        action="inject_instruction", trace_id=trace_id, instruction="Scroll down slowly"
+    )
+    assert "Successfully injected" in ok_res["message"]
+
+
+@pytest.mark.asyncio
+async def test_mobile_inspect_trace_invalid_action():
+    res = await mobile_inspect_trace(action="invalid_action", trace_id="trace-123")
+    assert "error" in res
+    assert "not supported" in res["message"]
@@ -0,0 +1,131 @@
+# 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.
+
+"""Unit tests for MCP Multi-Environment Notifiers."""
+
+import json
+import os
+import shutil
+import tempfile
+import pytest
+
+from mcp_server.notifiers import (
+    BaseNotifier,
+    CompositeNotifier,
+    DesktopNotifier,
+    FileNotifier,
+    WebhookNotifier,
+    notify,
+)
+from mcp_server.utils import trace_store
+
+
+class DummyNotifier(BaseNotifier):
+    def __init__(self, available: bool = True, return_val: bool = True):
+        self._available = available
+        self._return_val = return_val
+        self.called_with = None
+
+    @property
+    def name(self) -> str:
+        return "dummy"
+
+    def is_available(self) -> bool:
+        return self._available
+
+    def notify(self, conversation_id, message, title=None, event_type="completed", payload=None):
+        self.called_with = {
+            "conversation_id": conversation_id,
+            "message": message,
+            "title": title,
+            "event_type": event_type,
+            "payload": payload,
+        }
+        return self._return_val
+
+
+def test_file_notifier():
+    temp_dir = tempfile.mkdtemp()
+    try:
+        trace_id = "test-file-trace-123"
+        trace_dir = os.path.join(temp_dir, trace_id)
+        os.makedirs(trace_dir, exist_ok=True)
+
+        notifier = FileNotifier()
+        with pytest.MonkeyPatch.context() as mp:
+            mp.setattr(trace_store, "TRACES_DIR", temp_dir)
+            success = notifier.notify(
+                conversation_id="conv-1",
+                message="Task completed",
+                title="Done",
+                event_type="completed",
+                payload={"trace_id": trace_id},
+            )
+            assert success is True
+
+            log_file = os.path.join(trace_dir, "notifications.jsonl")
+            assert os.path.exists(log_file)
+            with open(log_file, encoding="utf-8") as f:
+                lines = f.readlines()
+                assert len(lines) == 1
+                entry = json.loads(lines[0])
+                assert entry["event_type"] == "completed"
+                assert entry["message"] == "Task completed"
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+def test_webhook_notifier_not_configured(monkeypatch):
+    for var in WebhookNotifier.ENV_VARS:
+        monkeypatch.delenv(var, raising=False)
+    notifier = WebhookNotifier()
+    assert notifier.is_available() is False
+    assert notifier.notify("conv-1", "hello") is False
+
+
+def test_desktop_notifier_not_enabled(monkeypatch):
+    monkeypatch.delenv("ARTEMIS_DESKTOP_NOTIFY", raising=False)
+    notifier = DesktopNotifier()
+    assert notifier.is_available() is False
+
+
+def test_composite_notifier_dispatch():
+    d1 = DummyNotifier(available=True, return_val=True)
+    d2 = DummyNotifier(available=False, return_val=False)
+    d3 = DummyNotifier(available=True, return_val=True)
+
+    composite = CompositeNotifier(notifiers=[d1, d2, d3])
+    assert composite.is_available() is True
+
+    result = composite.notify(
+        conversation_id="conv-abc",
+        message="Hello World",
+        title="Test Title",
+        event_type="completed",
+        payload={"key": "val"},
+    )
+    assert result is True
+    assert d1.called_with is not None
+    assert d1.called_with["conversation_id"] == "conv-abc"
+    assert d2.called_with is None
+    assert d3.called_with is not None
+
+
+def test_global_notify_function():
+    res = notify(
+        conversation_id="conv-xyz",
+        message="Test message",
+        payload={"trace_id": "test-trace"},
+    )
+    assert isinstance(res, bool)
@@ -0,0 +1,77 @@
+# 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.
+
+"""Unit tests for MCP trace store."""
+
+import shutil
+import tempfile
+import uuid
+import pytest
+
+from mcp_server.utils import trace_store
+
+
+@pytest.fixture
+def temp_trace_env(monkeypatch):
+    temp_dir = tempfile.mkdtemp()
+    monkeypatch.setattr(trace_store, "TRACES_DIR", temp_dir)
+    yield temp_dir
+    shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+def test_init_and_read_status(temp_trace_env):
+    trace_id = str(uuid.uuid4())
+    task_desc = "Test open settings"
+    model = "Flash"
+    conv_id = "test-conv-123"
+
+    init_res = trace_store.init_trace(trace_id, task_desc, model, conv_id)
+    assert init_res["trace_id"] == trace_id
+    assert init_res["status"] == "running"
+    assert init_res["model"] == "Flash"
+
+    status_data = trace_store.read_status(trace_id)
+    assert status_data is not None
+    assert status_data["trace_id"] == trace_id
+    assert status_data["task_desc"] == task_desc
+    assert status_data["conversation_id"] == conv_id
+
+
+def test_update_trace_status(temp_trace_env):
+    trace_id = str(uuid.uuid4())
+    trace_store.init_trace(trace_id, "Test task", "Pro", "conv-456")
+
+    updated = trace_store.update_trace_status(
+        trace_id=trace_id,
+        status="completed",
+        result={"success": True},
+    )
+    assert updated is not None
+    assert updated["status"] == "completed"
+    assert updated["result"] == {"success": True}
+    assert updated["end_time"] is not None
+
+    failed = trace_store.update_trace_status(
+        trace_id=trace_id,
+        status="failed",
+        error="App crashed",
+    )
+    assert failed is not None
+    assert failed["status"] == "failed"
+    assert failed["error"] == "App crashed"
+
+
+def test_read_nonexistent_status(temp_trace_env):
+    non_existent = str(uuid.uuid4())
+    assert trace_store.read_status(non_existent) is None