android-midscene-automation 0.2.4 → 1.1.1

package/artemis-main/artemis/services/token_meter.py

@@ -0,0 +1,267 @@
+# 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.
+
+"""Session-level LLM token usage and cache-hit metering.
+
+Every gateway-managed LLM call reports its real ``usage_metadata`` here. The
+meter accumulates per-session totals and records one ``llm_usage`` trace per
+call into the DataEngine, carrying:
+
+- the call's measured ``prompt_tokens`` (``context_base_tokens`` in the trace
+  payload, kept for the timeline). Note: the session meter's
+  ``last_prompt_tokens`` is whichever call happened last in the session —
+  Planner, Validator, Checker, sub-agents included — so the compaction
+  thresholds do NOT read it; the operator records its own prompt size on the
+  transcript ledger (``TranscriptLedger.record_prompt_tokens``);
+- provider-reported cache hits (Gemini ``cached_content_token_count`` /
+  LangChain ``input_token_details.cache_read``) to establish the cache-hit-rate
+  baseline;
+- running per-session totals, including ``session_cached_ratio``
+  (cached / prompt tokens over the session) and the same ratio for the call's
+  own ``source`` (``source_cached_ratio``), so a session whose operator calls
+  never hit the prompt cache is visible on its ``llm_usage`` traces and in the
+  session summary line (:func:`log_session_summary`).
+
+This module never raises into the LLM call path and makes no decisions.
+"""
+
+import threading
+from typing import Any
+
+from artemis.data_engine.context_vars import CURRENT_NODE_NAME
+from artemis.llm.google import usage_from_message
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+_LOCK = threading.Lock()
+_METERS: dict[str, "SessionTokenMeter"] = {}
+
+# Size of the model context window the live Operator/FlashRunner prompt is
+# measured against when the UI reports "context used". The prompt size of the
+# last executor call (``context_base_tokens`` on its ``llm_usage`` trace) is
+# the numerator; this is the denominator.
+OPERATOR_CONTEXT_WINDOW_TOKENS = 1_000_000
+
+# Traced node names whose LLM calls carry the live executor context. Both the
+# Pro Operator and the Flash runner are "the operator" from the user's view.
+OPERATOR_NODE_NAMES = frozenset({"operator", "flashrunner"})
+
+
+def extract_usage(response: Any) -> dict[str, int] | None:
+    """Extracts unified token usage from an LLM response message, best-effort.
+
+    Thin wrapper over :func:`artemis.llm.google.usage.usage_from_message`
+    that keeps the meter's historical four-key shape. Returns None when the
+    response carries no usable usage numbers.
+    """
+    usage = usage_from_message(response)
+    if usage is None:
+        return None
+    return {
+        "prompt_tokens": usage["prompt_tokens"],
+        "completion_tokens": usage["completion_tokens"],
+        "total_tokens": usage["total_tokens"],
+        "cached_tokens": usage["cached_tokens"],
+    }
+
+
+def cached_ratio(cached_tokens: int, prompt_tokens: int) -> float:
+    """``cached / prompt`` rounded to three decimals; 0.0 with no prompt tokens."""
+    if prompt_tokens <= 0:
+        return 0.0
+    return round(cached_tokens / prompt_tokens, 3)
+
+
+class SessionTokenMeter:
+    """Accumulates measured LLM usage for one session, in total and per source."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        self._lock = threading.Lock()
+        self.llm_calls = 0
+        self.prompt_tokens = 0
+        self.completion_tokens = 0
+        self.cached_tokens = 0
+        self.cache_hit_calls = 0
+        self.last_prompt_tokens = 0
+        # Per-source totals (source = gateway endpoint key or lens label):
+        # {"llm_calls", "prompt_tokens", "cached_tokens", "cache_hit_calls"}.
+        self.sources: dict[str, dict[str, int]] = {}
+
+    def record(
+        self,
+        usage: dict[str, int],
+        *,
+        update_last_prompt: bool = True,
+        source: str | None = None,
+    ) -> dict[str, Any]:
+        """Accumulates one call's usage; returns a session snapshot.
+
+        ``update_last_prompt=False`` accumulates the totals without touching
+        ``last_prompt_tokens`` — background lens calls carry tiny prompts that
+        must not masquerade as the live context base consumed by the L2/L3
+        compaction thresholds. With a ``source`` the call also joins that
+        source's totals and the snapshot carries ``source_cached_ratio``.
+        """
+        with self._lock:
+            prompt = usage.get("prompt_tokens", 0)
+            cached = usage.get("cached_tokens", 0)
+            self.llm_calls += 1
+            self.prompt_tokens += prompt
+            self.completion_tokens += usage.get("completion_tokens", 0)
+            self.cached_tokens += cached
+            if cached > 0:
+                self.cache_hit_calls += 1
+            if update_last_prompt:
+                self.last_prompt_tokens = prompt
+            snapshot = self._snapshot_locked()
+            if source:
+                totals = self.sources.setdefault(
+                    source,
+                    {"llm_calls": 0, "prompt_tokens": 0, "cached_tokens": 0, "cache_hit_calls": 0},
+                )
+                totals["llm_calls"] += 1
+                totals["prompt_tokens"] += prompt
+                totals["cached_tokens"] += cached
+                if cached > 0:
+                    totals["cache_hit_calls"] += 1
+                snapshot["source_cached_ratio"] = cached_ratio(
+                    totals["cached_tokens"], totals["prompt_tokens"]
+                )
+            return snapshot
+
+    def _snapshot_locked(self) -> dict[str, Any]:
+        return {
+            "session_llm_calls": self.llm_calls,
+            "session_prompt_tokens": self.prompt_tokens,
+            "session_completion_tokens": self.completion_tokens,
+            "session_cached_tokens": self.cached_tokens,
+            "session_cache_hit_calls": self.cache_hit_calls,
+            "session_cached_ratio": cached_ratio(self.cached_tokens, self.prompt_tokens),
+        }
+
+    def snapshot(self) -> dict[str, Any]:
+        with self._lock:
+            return self._snapshot_locked()
+
+    def summary(self) -> dict[str, Any]:
+        """Session totals plus every source's totals with its ``cached_ratio``."""
+        with self._lock:
+            summary: dict[str, Any] = {"session_id": self.session_id, **self._snapshot_locked()}
+            summary["sources"] = {
+                source: {
+                    **totals,
+                    "cached_ratio": cached_ratio(totals["cached_tokens"], totals["prompt_tokens"]),
+                }
+                for source, totals in self.sources.items()
+            }
+            return summary
+
+
+def format_session_summary(session_id: Any) -> str:
+    """One log line: session cache ratio, then each source's calls and ratio."""
+    summary = get_meter(session_id).summary()
+    parts = [
+        f"LLM usage for session {summary['session_id']}:"
+        f" {summary['session_llm_calls']} calls,"
+        f" {summary['session_prompt_tokens']} prompt tokens,"
+        f" {summary['session_cached_tokens']} cached"
+        f" (cached_ratio={summary['session_cached_ratio']:.3f},"
+        f" cache-hit calls {summary['session_cache_hit_calls']})"
+    ]
+    for source, totals in summary["sources"].items():
+        parts.append(
+            f"{source}: {totals['llm_calls']} calls, cached_ratio={totals['cached_ratio']:.3f}"
+        )
+    return "; ".join(parts)
+
+
+def log_session_summary(session_id: Any) -> dict[str, Any] | None:
+    """Log the session's usage summary (INFO) at session end, best-effort.
+
+    Returns the summary dict, or None when the session never metered a call
+    (nothing is logged then). Never raises.
+    """
+    try:
+        key = str(session_id)
+        with _LOCK:
+            meter = _METERS.get(key)
+        if meter is None or meter.llm_calls == 0:
+            return None
+        logger.info(format_session_summary(key))
+        return meter.summary()
+    except Exception as exc:
+        logger.debug(f"Token meter session summary skipped: {exc}")
+        return None
+
+
+def get_meter(session_id: Any) -> SessionTokenMeter:
+    """Returns (creating on first use) the meter for a session id."""
+    key = str(session_id)
+    with _LOCK:
+        meter = _METERS.get(key)
+        if meter is None:
+            meter = SessionTokenMeter(key)
+            _METERS[key] = meter
+        return meter
+
+
+def record_llm_usage(
+    engine: Any,
+    response: Any,
+    *,
+    source: str | None = None,
+    update_last_prompt: bool = True,
+) -> dict | None:
+    """Meters one LLM response and records an ``llm_usage`` trace, best-effort.
+
+    ``context_base_tokens`` in the payload is this call's measured prompt size —
+    the running estimate of the live context for threshold decisions in later
+    milestones. Returns the recorded payload, or None when nothing was
+    recorded (no engine/session/usage). Never raises.
+    """
+    try:
+        if engine is None:
+            return None
+        session_id = getattr(engine, "current_session_id", None)
+        usage = extract_usage(response)
+        if not session_id or usage is None:
+            return None
+
+        snapshot = get_meter(session_id).record(
+            usage, update_last_prompt=update_last_prompt, source=source
+        )
+        payload: dict[str, Any] = {
+            **usage,
+            "context_base_tokens": usage["prompt_tokens"],
+            **snapshot,
+        }
+        if source:
+            payload["source"] = source
+        node = CURRENT_NODE_NAME.get()
+        if node:
+            payload["node"] = str(node)
+
+        engine.record_trace(
+            type="llm_call",
+            name="llm_usage",
+            payload=payload,
+            step_id=getattr(engine, "current_step_id", None),
+            status="success",
+        )
+        return payload
+    except Exception as meter_err:
+        logger.debug(f"Token metering skipped: {meter_err}")
+        return None

package/artemis-main/artemis/telemetry/__init__.py

@@ -0,0 +1,35 @@
+# 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.
+
+"""Telemetry and distributed tracing layer for ARTEMIS."""
+
+from artemis.telemetry.models import (
+    SpanType,
+    TelemetrySpan,
+    TokenUsage,
+)
+from artemis.telemetry.tracer import (
+    CURRENT_PARENT_SPAN_ID,
+    CURRENT_TRACE_ID,
+    TelemetryTracer,
+)
+
+__all__ = [
+    "TelemetryTracer",
+    "TelemetrySpan",
+    "SpanType",
+    "TokenUsage",
+    "CURRENT_TRACE_ID",
+    "CURRENT_PARENT_SPAN_ID",
+]

package/artemis-main/artemis/telemetry/models.py

@@ -0,0 +1,64 @@
+# 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.
+
+"""Telemetry Data Models and Schema Definitions."""
+
+from enum import Enum
+import time
+from typing import Any
+from uuid import uuid4
+from pydantic import BaseModel, Field
+
+
+class SpanType(str, Enum):
+    AGENT = "agent"
+    LLM_CALL = "llm_call"
+    TOOL_EXECUTION = "tool_execution"
+    DEVICE_ACTION = "device_action"
+    SCREEN_CAPTURE = "screen_capture"
+    CUSTOM = "custom"
+
+
+class TokenUsage(BaseModel):
+    """LLM token consumption metrics."""
+
+    prompt_tokens: int = Field(default=0, description="Input prompt tokens")
+    completion_tokens: int = Field(default=0, description="Output generated tokens")
+    total_tokens: int = Field(default=0, description="Total tokens consumed")
+
+
+class TelemetrySpan(BaseModel):
+    """Structured telemetry span representing a single unit of agentic execution."""
+
+    span_id: str = Field(default_factory=lambda: str(uuid4()))
+    trace_id: str = Field(..., description="Root trace/session identifier")
+    parent_id: str | None = Field(default=None, description="Parent span identifier")
+    name: str = Field(..., description="Human-readable span operation name")
+    type: SpanType = Field(default=SpanType.CUSTOM, description="Span categorization")
+    start_time: float = Field(default_factory=time.time, description="Start timestamp")
+    end_time: float | None = Field(default=None, description="Completion timestamp")
+    duration_ms: float | None = Field(default=None, description="Elapsed execution time in ms")
+    status: str = Field(default="running", description="Status ('running', 'success', 'failed')")
+    payload: dict[str, Any] = Field(
+        default_factory=dict, description="Custom parameters and payloads"
+    )
+    error: str | None = Field(default=None, description="Exception message if failed")
+    token_usage: TokenUsage | None = Field(default=None, description="Token consumption metrics")
+
+    def finish(self, status: str = "success", error: str | None = None) -> None:
+        """Closes the span and calculates duration."""
+        self.end_time = time.time()
+        self.duration_ms = (self.end_time - self.start_time) * 1000.0
+        self.status = status
+        self.error = error

package/artemis-main/artemis/telemetry/replay.py

@@ -0,0 +1,34 @@
+# 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.
+
+"""Trace Replay and Inspection utilities."""
+
+from pathlib import Path
+from typing import Any
+from artemis.telemetry.storage.json_storage import JsonStorage
+
+
+class TraceReplayer:
+    """Loads and formats historic task traces for replay and visual inspection."""
+
+    def __init__(self, traces_dir: Path | str = "traces"):
+        self.storage = JsonStorage(storage_dir=traces_dir)
+
+    def get_trace_summary(self, trace_id: str) -> dict[str, Any]:
+        spans = self.storage.read_spans(trace_id)
+        return {
+            "trace_id": trace_id,
+            "total_spans": len(spans),
+            "spans": spans,
+        }

package/artemis-main/artemis/telemetry/storage/json_storage.py

@@ -0,0 +1,47 @@
+# 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.
+
+"""JSON Lines Telemetry Storage Backend."""
+
+import json
+from pathlib import Path
+from typing import Any
+from artemis.telemetry.models import TelemetrySpan
+
+
+class JsonStorage:
+    """Persists spans into newline-delimited JSON files."""
+
+    def __init__(self, storage_dir: Path | str = "traces"):
+        self.storage_dir = Path(storage_dir)
+
+    def write_span(self, trace_id: str, span: TelemetrySpan) -> None:
+        target_dir = self.storage_dir / trace_id
+        target_dir.mkdir(parents=True, exist_ok=True)
+        log_file = target_dir / "spans.jsonl"
+
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(json.dumps(span.model_dump(), ensure_ascii=False) + "\n")
+
+    def read_spans(self, trace_id: str) -> list[dict[str, Any]]:
+        log_file = self.storage_dir / trace_id / "spans.jsonl"
+        if not log_file.exists():
+            return []
+
+        spans = []
+        with open(log_file, encoding="utf-8") as f:
+            for line in f:
+                if line.strip():
+                    spans.append(json.loads(line))
+        return spans

package/artemis-main/artemis/telemetry/tracer.py

@@ -0,0 +1,85 @@
+# 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.
+
+"""Telemetry Tracer and Span Life Cycle Manager."""
+
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+import json
+from pathlib import Path
+from typing import Any
+from collections.abc import AsyncIterator
+from uuid import uuid4
+
+from artemis.telemetry.models import SpanType, TelemetrySpan
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+CURRENT_TRACE_ID: ContextVar[str] = ContextVar("CURRENT_TRACE_ID", default="global-session")
+CURRENT_PARENT_SPAN_ID: ContextVar[str | None] = ContextVar("CURRENT_PARENT_SPAN_ID", default=None)
+
+
+class TelemetryTracer:
+    """Central tracer for recording and persisting telemetry spans."""
+
+    def __init__(self, trace_id: str | None = None, traces_dir: Path | None = None):
+        self.trace_id = trace_id or str(uuid4())
+        self.traces_dir = traces_dir or Path("traces") / self.trace_id
+        self.spans: list[TelemetrySpan] = []
+        self._log_file: Path | None = None
+
+    def _ensure_log_file(self) -> Path:
+        if self._log_file is None:
+            self.traces_dir.mkdir(parents=True, exist_ok=True)
+            self._log_file = self.traces_dir / "telemetry_spans.jsonl"
+        return self._log_file
+
+    def record_span(self, span: TelemetrySpan) -> None:
+        """Appends and persists completed span."""
+        self.spans.append(span)
+        try:
+            log_file = self._ensure_log_file()
+            with open(log_file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(span.model_dump(), ensure_ascii=False) + "\n")
+        except Exception as e:
+            logger.warning(f"Failed to persist telemetry span {span.span_id}: {e}")
+
+    @asynccontextmanager
+    async def start_span(
+        self,
+        name: str,
+        span_type: SpanType = SpanType.CUSTOM,
+        payload: dict[str, Any] | None = None,
+    ) -> AsyncIterator[TelemetrySpan]:
+        """Asynchronous context manager creating and recording a span."""
+        parent_id = CURRENT_PARENT_SPAN_ID.get()
+        span = TelemetrySpan(
+            trace_id=self.trace_id,
+            parent_id=parent_id,
+            name=name,
+            type=span_type,
+            payload=payload or {},
+        )
+
+        token = CURRENT_PARENT_SPAN_ID.set(span.span_id)
+        try:
+            yield span
+            span.finish(status="success")
+        except Exception as e:
+            span.finish(status="failed", error=str(e))
+            raise
+        finally:
+            CURRENT_PARENT_SPAN_ID.reset(token)
+            self.record_span(span)

package/artemis-main/artemis/toolchain/__init__.py

@@ -0,0 +1,52 @@
+# 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.
+
+"""Managed Toolchain and Binary Discovery Subsystem."""
+
+import os
+from pathlib import Path
+
+from artemis.toolchain.descriptors import TOOLS, ToolDescriptor
+from artemis.toolchain.resolver import ToolchainResolver, toolchain
+
+
+def ensure_toolchain_in_path() -> None:
+    """Prepend resolved toolchain paths (e.g. adb, scrcpy, ffmpeg) to process PATH."""
+    for tool_name in ("adb", "ffmpeg", "scrcpy"):
+        tool_path = toolchain.resolve(tool_name)
+        if tool_path:
+            parent_dir = str(Path(tool_path).parent)
+            current_path = os.environ.get("PATH", "")
+            if parent_dir not in current_path.split(os.pathsep):
+                os.environ["PATH"] = f"{parent_dir}{os.pathsep}{current_path}"
+
+
+# Auto-configure process PATH upon import
+ensure_toolchain_in_path()
+
+find_adb = toolchain.find_adb
+find_ffmpeg = toolchain.find_ffmpeg
+find_scrcpy = toolchain.find_scrcpy
+is_installed = toolchain.is_installed
+
+__all__ = [
+    "toolchain",
+    "ToolchainResolver",
+    "ToolDescriptor",
+    "TOOLS",
+    "find_adb",
+    "find_ffmpeg",
+    "find_scrcpy",
+    "is_installed",
+]

package/artemis-main/artemis/toolchain/descriptors.py

@@ -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.
+
+"""Toolchain descriptors and metadata for cross-platform binary discovery."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _get_embedded_adb() -> str | None:
+    """Fallback to adb binary bundled with adbutils if available."""
+    try:
+        import adbutils
+
+        if hasattr(adbutils, "adb_path"):
+            return adbutils.adb_path()
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        # Optional dependency probe: not installed or no bundled binary.
+        logger.debug("Embedded adb probe via adbutils skipped: %s", exc, exc_info=True)
+    return None
+
+
+def _get_embedded_ffmpeg() -> str | None:
+    """Fallback to ffmpeg binary bundled with imageio_ffmpeg if available."""
+    try:
+        import imageio_ffmpeg
+
+        if hasattr(imageio_ffmpeg, "get_ffmpeg_exe"):
+            return imageio_ffmpeg.get_ffmpeg_exe()
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        # Optional dependency probe: not installed, or imageio_ffmpeg raises
+        # RuntimeError when it ships no binary for this platform.
+        logger.debug("Embedded ffmpeg probe via imageio_ffmpeg skipped: %s", exc, exc_info=True)
+    return None
+
+
+@dataclass(frozen=True)
+class ToolDescriptor:
+    """Metadata and resolution strategies for an external binary/toolchain."""
+
+    name: str
+    binary_name: str
+    win_binary_name: str
+    sdk_relative_path: str | None = None
+    embedded_fallback: Callable[[], str | None] | None = None
+    description: str = ""
+
+
+# Standard supported toolchains
+TOOLS: dict[str, ToolDescriptor] = {
+    "adb": ToolDescriptor(
+        name="adb",
+        binary_name="adb",
+        win_binary_name="adb.exe",
+        sdk_relative_path="platform-tools/adb",
+        embedded_fallback=_get_embedded_adb,
+        description="Android Debug Bridge client",
+    ),
+    "ffmpeg": ToolDescriptor(
+        name="ffmpeg",
+        binary_name="ffmpeg",
+        win_binary_name="ffmpeg.exe",
+        embedded_fallback=_get_embedded_ffmpeg,
+        description="FFmpeg multimedia processing framework",
+    ),
+    "scrcpy": ToolDescriptor(
+        name="scrcpy",
+        binary_name="scrcpy",
+        win_binary_name="scrcpy.exe",
+        description="Screen Copy display and control tool",
+    ),
+    "uv": ToolDescriptor(
+        name="uv",
+        binary_name="uv",
+        win_binary_name="uv.exe",
+        description="Fast Python package manager",
+    ),
+}