feat: harden agent verification and runtime contracts

Introduce two-gate checker settlement, explicit graph visibility and checkpoints, structured LLM reliability, centralized action specifications, and corresponding tests and design documentation.

tests/tools/conftest.py

@@ -51,6 +51,9 @@ def artemis_context(inputs_dir, mock_adb_client):
 
     ctx.execution_setup = MagicMock()
     ctx.execution_setup.traces_path = str(inputs_dir)
+    # A bare MagicMock trace_name yields a repr with '<>' characters, which is an
+    # invalid path component on Windows once it flows into trace dir construction.
+    ctx.execution_setup.trace_name = "trace_output"
 
     # Initialize real DataEngine if the fixture database exists
     db_path = inputs_dir / "data_engine.db"

tests/tools/operator/test_operator_tools.py

@@ -13,56 +13,27 @@
 # limitations under the License.
 
 from langchain_core.tools import BaseTool
-from artemis.agents.operator.operator import OperatorNode
 import pytest
 
+from artemis.mcp.action_specs import OPERATOR_SHELL_ORDER, operator_shell_tool
+
 
 @pytest.mark.asyncio
-async def test_operator_tools(artemis_context, mock_state):
-    """Test all tools exposed by the OperatorNode."""
-    node = OperatorNode(ctx=artemis_context)
+async def test_operator_shell_tools():
+    """Every manifest-generated Operator shell is a declaration-only LangChain tool."""
+    sample_args = {
+        "click": {"target": 1, "times": 1, "delay_ms": 100},
+        "input_text": {"text": "hello", "target": 1, "clear_exist": True},
+        "swipe": {"gesture": "up"},
+        "press_key": {"key": "ENTER"},
+        "manage_app": {"action": "launch", "app_name": "Settings"},
+        "wait_for_delay": {"time_in_ms": 1000},
+        "long_press": {"target": 1, "duration": 1000},
+    }
+    assert set(sample_args) == set(OPERATOR_SHELL_ORDER)
 
-    click_tool = node._get_click_tool()
-    assert isinstance(click_tool, BaseTool)
-    res = click_tool.invoke({"target": 1, "times": 1, "delay_ms": 100})
-    assert res == "Action Recorded"
-
-    input_text_tool = node._get_input_text_tool()
-    assert isinstance(input_text_tool, BaseTool)
-    res = input_text_tool.invoke({"text": "hello", "target": 1, "clear_exist": True})
-    assert res == "Action Recorded"
-
-    swipe_tool = node._get_swipe_tool()
-    assert isinstance(swipe_tool, BaseTool)
-    res = swipe_tool.invoke({"gesture": "up"})
-    assert res == "Action Recorded"
-
-    press_key_tool = node._get_press_key_tool()
-    assert isinstance(press_key_tool, BaseTool)
-    res = press_key_tool.invoke({"key": "ENTER"})
-    assert res == "Action Recorded"
-
-    manage_app_tool = node._get_manage_app_tool()
-    assert isinstance(manage_app_tool, BaseTool)
-    res = manage_app_tool.invoke({"action": "launch", "app_name": "Settings"})
-    assert res == "Action Recorded"
-
-    wait_for_delay_tool = node._get_wait_for_delay_tool()
-    assert isinstance(wait_for_delay_tool, BaseTool)
-    res = wait_for_delay_tool.invoke({"time_in_ms": 1000})
-    assert res == "Action Recorded"
-
-    long_press_tool = node._get_long_press_tool()
-    assert isinstance(long_press_tool, BaseTool)
-    res = long_press_tool.invoke({"target": 1, "duration": 1000})
-    assert res == "Action Recorded"
-
-    wait_for_text_tool = node._get_wait_for_text_tool()
-    assert isinstance(wait_for_text_tool, BaseTool)
-    res = wait_for_text_tool.invoke({"text": "Success", "state": "visible", "timeout_ms": 5000})
-    assert res == "Action Recorded"
-
-    reply_tool = node._get_reply_to_checker_tool()
-    assert isinstance(reply_tool, BaseTool)
-    res = reply_tool.invoke({"reasoning": "This is a test reply."})
-    assert isinstance(res, str)
+    for name in OPERATOR_SHELL_ORDER:
+        tool = operator_shell_tool(name)
+        assert isinstance(tool, BaseTool)
+        assert tool.name == name
+        assert tool.invoke(sample_args[name]) == "Action Recorded"

tests/tools/video_analyzer/test_video_analyzer_tools.py

@@ -20,9 +20,13 @@ from artemis.agents.video_analyzer.video_analyzer import VideoAnalyzer
 
 
 @pytest.mark.asyncio
-async def test_video_analyzer_tools(artemis_context, mock_state, inputs_dir):
+async def test_video_analyzer_tools(artemis_context, mock_state, inputs_dir, tmp_path):
     artemis_context.device.mobile_platform = "android"
     artemis_context.adb_client = artemis_context.ui_adb_client
+    # A leaked MagicMock video_analyzer config coerces every numeric setting to
+    # 1 (float(MagicMock()) == 1.0), e.g. a 1s model-call timeout. None makes
+    # VideoAnalyzer fall back to its real defaults.
+    artemis_context.agent_config.video_analyzer = None
 
     agent = VideoAnalyzer(ctx=artemis_context)
 
@@ -70,6 +74,9 @@ async def test_video_analyzer_tools(artemis_context, mock_state, inputs_dir):
     )
     artemis_context._genai_client = agent.client
 
+    import shutil
+    import uuid
+
     mock_session = MagicMock()
     mock_session.local_video_path = Path(inputs_dir) / "recording.mp4"
     mock_session.start_time = 0.0
@@ -78,17 +85,40 @@ async def test_video_analyzer_tools(artemis_context, mock_state, inputs_dir):
     mock_session.process.returncode = None
     mock_session.android_video_segments = []
     mock_session.android_segment_index = 0
+    # Real-typed fields consumed by UnifiedMobileController.extract_segment_metadata
+    # and the pydantic VideoRecordingResult; leaked MagicMock attributes fail
+    # validation or produce invalid paths.
+    mock_session.android_segment_records = []
+    mock_session.android_segment_started_at = None
+    mock_session.video_id = uuid.uuid4()
+    mock_session.generation = 0
+    mock_session.sealed_until = None
 
     from unittest.mock import AsyncMock
 
     sample_video = Path(inputs_dir) / "recording.mp4"
     mock_driver = MagicMock()
     mock_driver.stop_video_recording = AsyncMock(return_value=sample_video)
+    # A bare MagicMock attribute is truthy, which would trip the mock-driver
+    # short-circuit in extract_segment_metadata and return a nonexistent path.
+    mock_driver.is_mock = False
     artemis_context._active_driver = mock_driver
 
-    with patch(
-        "artemis.controllers.android_controller.get_active_session",
-        return_value=mock_session,
+    # Screen-recording segments carry no audio track (render_timeline_clip maps
+    # only the video stream), so real audio extraction can never succeed here.
+    # Substitute the fixture mp3 as the extracted audio for the audio sub-agent.
+    audio_copy = tmp_path / "audio_recording.mp3"
+    shutil.copyfile(Path(inputs_dir) / "audio_recording.mp3", audio_copy)
+
+    with (
+        patch(
+            "artemis.controllers.unified_controller.get_active_session",
+            return_value=mock_session,
+        ),
+        patch(
+            "artemis.agents.video_analyzer.video_analyzer.extract_audio_from_video",
+            AsyncMock(return_value=audio_copy),
+        ),
     ):
         result = await agent.exec_extract_segment_metadata(start_time=0.0, end_time=1.0)
         assert isinstance(result, str)