feat: add agentic video analysis and clarify action results

Report device actions as dispatched and preserve full failure details. Route
Flash through McpActionExecutor and use ToolFailure across helper tools and
agent loops instead of inferring failure from response text.

Require model-provided descriptions for coordinate targets. Keep observed
element metadata separate from those descriptions in safety checks, visual
summaries, history, and frontend labels.

Add Gemini Interactions API video analysis with configurable processing mode,
chunk size, and timeouts. Centralize Google provider capabilities and token
usage normalization, and update google-genai to 2.22.0.

Preserve system instructions on follow-up interactions, replan pending chunks
when falling back to static processing, and reject unanswered native video
and audio segments instead of caching placeholder results. Keep helper-tool
failure status intact through history tools and committee calls.

Validation: 1,762 Python unit tests passed (3 skipped), 40 frontend formatter
tests passed, and the production UI build completed. Ruff lint, formatting,
the quality ratchet, and git diff checks passed.

tests/unit/utils/test_attempt_markers.py

@@ -0,0 +1,50 @@
+"""The ``attempts`` marker contract between the Validator and the renderers.
+
+The Validator writes ``"Dispatched"`` as the terminal attempt of an action the
+device accepted (kept only when a retry preceded it); every failed attempt keeps
+its error text. The renderers must read a retried-then-dispatched action as a
+clean dispatch, never as a failure.
+"""
+
+from artemis.utils.task_tree import (
+    _burst_member_status,
+    failed_execution_error,
+    format_result_clean,
+)
+
+
+def _report(attempts: list[str], status: str = "dispatched") -> dict:
+    return {
+        "status": status,
+        "execution": [
+            {"action": "tap", "normalized_coordinates": [500, 500], "attempts": attempts}
+        ],
+    }
+
+
+def test_retried_then_dispatched_action_is_not_a_failure():
+    report = _report(["Error: tap rejected", "Dispatched"])
+    assert failed_execution_error(report) is None
+    assert format_result_clean(report) is None
+
+
+def test_terminal_failure_keeps_every_attempt():
+    report = _report(["Error: tap rejected", "Error: tap rejected again"], status="failed")
+    assert failed_execution_error(report) == "Error: tap rejected | Error: tap rejected again"
+    assert format_result_clean(report) == "Error: tap rejected | Error: tap rejected again"
+
+
+def test_burst_member_labels_follow_the_dispatch_vocabulary():
+    report = {
+        "status": "failed",
+        "execution": [
+            {"action": "tap"},
+            {"action": "tap", "attempts": ["Error: boom"]},
+            {"action": "tap", "attempts": ["Skipped (burst aborted)"]},
+        ],
+    }
+    assert _burst_member_status(report, 0) == " (dispatched)"
+    assert _burst_member_status(report, 1) == " (FAILED: Error: boom)"
+    assert _burst_member_status(report, 2) == " (skipped)"
+    assert _burst_member_status(report, 3) == " (not dispatched)"
+    assert _burst_member_status({"execution": [{"attempts": ["Dispatched"]}]}, 0) == " (dispatched)"

tests/unit/utils/test_element_hit_test.py

@@ -12,9 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Tests for record-time action semantics enrichment (element hit testing)."""
+"""Tests for element hit testing (used by the Explorer's candidate de-dup)."""
 
-from artemis.utils.element_hit_test import find_element_at_point, hit_test_semantics
+from artemis.utils.element_hit_test import find_element_at_point
 
 
 def _xml_el(text, bounds, resource_id=None, cls="android.widget.TextView"):
@@ -37,14 +37,6 @@ def test_smallest_covering_element_wins():
     assert source == "hit_test"
     assert el["text"] == "Button"
 
-    semantics = hit_test_semantics(elements, 250, 230)
-    assert semantics == {
-        "target_label_source": "hit_test",
-        "target_text": "Button",
-        "target_class": "android.widget.TextView",
-        "target_resource_id": "btn_ok",
-    }
-
 
 def test_xml_element_preferred_over_smaller_ocr_element():
     elements = [
@@ -73,11 +65,9 @@ def test_ocr_fallback_when_no_xml_element_covers_point():
             "is_ocr": True,
         },
     ]
-    semantics = hit_test_semantics(elements, 150, 150)
-    assert semantics["target_label_source"] == "ocr"
-    assert semantics["target_text"] == "OCR Label"
-    assert "target_class" not in semantics
-    assert "target_resource_id" not in semantics
+    el, source = find_element_at_point(elements, 150, 150)
+    assert source == "ocr"
+    assert el["text"] == "OCR Label"
 
 
 def test_string_bounds_are_parsed():
@@ -88,13 +78,12 @@ def test_string_bounds_are_parsed():
 
 
 def test_graceful_degradation_to_none():
-    # No elements at all
-    assert hit_test_semantics(None, 100, 100) == {"target_label_source": "none"}
-    assert hit_test_semantics([], 100, 100) == {"target_label_source": "none"}
+    assert find_element_at_point(None, 100, 100) == (None, "none")
+    assert find_element_at_point([], 100, 100) == (None, "none")
 
     # Point outside every element
     elements = [_xml_el("Item", [0, 0, 50, 50])]
-    assert hit_test_semantics(elements, 500, 500) == {"target_label_source": "none"}
+    assert find_element_at_point(elements, 500, 500) == (None, "none")
 
     # Malformed element data must not raise
     malformed = [
@@ -105,10 +94,4 @@ def test_graceful_degradation_to_none():
         "not-a-dict",
         None,
     ]
-    assert hit_test_semantics(malformed, 10, 10) == {"target_label_source": "none"}
-
-
-def test_element_without_optional_fields_only_reports_source():
-    elements = [{"text": "", "bounds": [0, 0, 100, 100], "class": None, "resource_id": None}]
-    semantics = hit_test_semantics(elements, 50, 50)
-    assert semantics == {"target_label_source": "hit_test"}
+    assert find_element_at_point(malformed, 10, 10) == (None, "none")

tests/unit/utils/test_task_tree.py

@@ -532,7 +532,7 @@ def test_build_plan_and_history_fast_action_burst():
         "* [Planned Fast-Action Burst]: 3 actions fired back to back without the"
         " safety net" in output
     )
-    assert "    1. Tapped element at [500, 900] (executed)" in output
+    assert "    1. Tapped element at [500, 900] (dispatched)" in output
     assert "    2. Tapped 'Skip' at [880, 120] (FAILED: Error: tap rejected)" in output
     assert "    3. Pressed key 'BACK' (skipped)" in output
     assert (
@@ -751,3 +751,88 @@ def test_format_action_clean_reads_flash_arguments_and_maps_manage_app():
         )
         == "Tapped 'Save' at [1, 2]"
     )
+
+
+def test_format_action_clean_marks_self_described_coordinate_targets():
+    """A coordinate target's label is the model's own description, and every
+    later reader sees it marked as such; an index target's observed element
+    text carries no marker."""
+    from artemis.utils.task_tree import SELF_DESCRIBED_MARKER, format_action_clean
+
+    assert SELF_DESCRIBED_MARKER == "(self-described)"
+    assert (
+        format_action_clean(
+            {"action": "tap", "coordinates": [540, 1440], "target_description": "play button"}
+        )
+        == "Tapped 'play button' (self-described) at [540, 1440]"
+    )
+    # Observed text outranks the description when both are present, unmarked.
+    assert (
+        format_action_clean(
+            {
+                "action": "tap",
+                "coordinates": [1, 2],
+                "target_text": "Play",
+                "target_description": "play button",
+            }
+        )
+        == "Tapped 'Play' at [1, 2]"
+    )
+    assert (
+        format_action_clean(
+            {
+                "action": "long_press_on",
+                "coordinates": [1, 2],
+                "duration": 1500,
+                "target_description": "app icon",
+            }
+        )
+        == "Long pressed 'app icon' (self-described) at [1, 2] for 1500ms"
+    )
+    assert (
+        format_action_clean(
+            {
+                "action": "focus_and_input_text",
+                "coordinates": [3, 4],
+                "text": "hello",
+                "target_description": "search box",
+            }
+        )
+        == "Inputted 'hello' into 'search box' (self-described) at [3, 4]"
+    )
+    assert (
+        format_action_clean(
+            {
+                "action": "swipe",
+                "coordinates": [100, 500, 900, 500],
+                "duration": 800,
+                "target_description": "brightness knob",
+            }
+        )
+        == "Swiped 'brightness knob' (self-described) from [100, 500] to [900, 500] over 800ms"
+    )
+    # Flash keeps the description under ``args``; it is read from there too.
+    assert (
+        format_action_clean(
+            {
+                "action": "click",
+                "coordinates": [320, 399],
+                "args": {"target": [320, 399], "target_description": "skip ad"},
+            }
+        )
+        == "Tapped 'skip ad' (self-described) at [320, 399]"
+    )
+    assert format_action_clean(
+        {
+            "action": "click_sequence",
+            "coordinates": [[500, 280], [885, 362]],
+            "target_descriptions": ["video body", "skip button"],
+        }
+    ) == (
+        "Tapped sequence of targets: 'video body' (self-described) at [500, 280],"
+        " 'skip button' (self-described) at [885, 362]"
+    )
+    # Unnamed targets stay unnamed: no marker without a description.
+    assert format_action_clean({"action": "tap", "coordinates": [1, 2]}) == (
+        "Tapped element at [1, 2]"
+    )