androidctl 0.1.0__py3-none-any.whl

androidctld/runtime/screen_state.py

@@ -0,0 +1,117 @@
+"""Shared accessors for current runtime screen state."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+
+from androidctld.artifacts.models import ScreenArtifacts
+from androidctld.protocol import RuntimeStatus
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.semantics.compiler import CompiledScreen
+from androidctld.semantics.public_models import (
+    PublicScreen,
+    iter_public_nodes,
+)
+
+
+@dataclass(frozen=True)
+class AuthoritativeCurrentBasis:
+    screen_id: str
+    screen_sequence: int
+    snapshot_id: int
+    captured_at: str
+    package_name: str | None
+    activity_name: str | None
+    public_screen: PublicScreen
+    compiled_screen: CompiledScreen
+    artifacts: ScreenArtifacts | None
+    public_refs: frozenset[str]
+
+
+def get_authoritative_current_basis(
+    runtime: WorkspaceRuntime,
+) -> AuthoritativeCurrentBasis | None:
+    with runtime.lock:
+        if runtime.status is not RuntimeStatus.READY:
+            return None
+        current_screen_id = runtime.current_screen_id
+        if not isinstance(current_screen_id, str) or not current_screen_id:
+            return None
+        latest_snapshot = runtime.latest_snapshot
+        screen_state = runtime.screen_state
+        if latest_snapshot is None or screen_state is None:
+            return None
+        public_screen = screen_state.public_screen
+        compiled_screen = screen_state.compiled_screen
+        if public_screen is None or compiled_screen is None:
+            return None
+        if public_screen.screen_id != current_screen_id:
+            return None
+        if compiled_screen.screen_id != current_screen_id:
+            return None
+        if compiled_screen.source_snapshot_id != latest_snapshot.snapshot_id:
+            return None
+        if compiled_screen.sequence != runtime.screen_sequence:
+            return None
+        if compiled_screen.captured_at != latest_snapshot.captured_at:
+            return None
+        if compiled_screen.package_name != latest_snapshot.package_name:
+            return None
+        if compiled_screen.activity_name != latest_snapshot.activity_name:
+            return None
+        if public_screen.app.package_name != latest_snapshot.package_name:
+            return None
+        if public_screen.app.activity_name != latest_snapshot.activity_name:
+            return None
+
+        public_screen_copy = deepcopy(public_screen)
+        compiled_screen_copy = deepcopy(compiled_screen)
+        artifacts_copy = deepcopy(screen_state.artifacts)
+        return AuthoritativeCurrentBasis(
+            screen_id=current_screen_id,
+            screen_sequence=runtime.screen_sequence,
+            snapshot_id=latest_snapshot.snapshot_id,
+            captured_at=latest_snapshot.captured_at,
+            package_name=latest_snapshot.package_name,
+            activity_name=latest_snapshot.activity_name,
+            public_screen=public_screen_copy,
+            compiled_screen=compiled_screen_copy,
+            artifacts=artifacts_copy,
+            public_refs=frozenset(
+                node.ref
+                for group in public_screen_copy.groups
+                for node in iter_public_nodes(group.nodes)
+                if node.ref
+            ),
+        )
+
+
+def current_public_screen(
+    runtime: WorkspaceRuntime, *, copy_value: bool = True
+) -> PublicScreen | None:
+    if runtime.screen_state is None or runtime.screen_state.public_screen is None:
+        return None
+    if copy_value:
+        return deepcopy(runtime.screen_state.public_screen)
+    return runtime.screen_state.public_screen
+
+
+def current_compiled_screen(
+    runtime: WorkspaceRuntime, *, copy_value: bool = True
+) -> CompiledScreen | None:
+    if runtime.screen_state is None or runtime.screen_state.compiled_screen is None:
+        return None
+    if copy_value:
+        return deepcopy(runtime.screen_state.compiled_screen)
+    return runtime.screen_state.compiled_screen
+
+
+def current_artifacts(
+    runtime: WorkspaceRuntime, *, copy_value: bool = True
+) -> ScreenArtifacts | None:
+    if runtime.screen_state is None or runtime.screen_state.artifacts is None:
+        return None
+    if copy_value:
+        return deepcopy(runtime.screen_state.artifacts)
+    return runtime.screen_state.artifacts

androidctld/runtime/state_repo.py

@@ -0,0 +1,70 @@
+"""Runtime state persistence repository."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from androidctld.protocol import RuntimeStatus
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.schema.persistence import (
+    RUNTIME_STATE_SCHEMA_VERSION,
+    RuntimeStateFile,
+    build_persistence_model,
+    validate_persistence_payload,
+)
+from androidctld.schema.persistence_io import atomic_write_json, load_json_object
+
+
+class RuntimeStateRepository:
+    def load(self, runtime_path: Path) -> WorkspaceRuntime | None:
+        if not runtime_path.exists():
+            return None
+        state_payload = load_json_object(runtime_path)
+        parsed = validate_persistence_payload(
+            RuntimeStateFile,
+            state_payload,
+            field_name="runtime",
+            schema_version=RUNTIME_STATE_SCHEMA_VERSION,
+        )
+        artifact_root = runtime_path.parent.resolve()
+        workspace_root = artifact_root.parent.resolve()
+        return WorkspaceRuntime(
+            workspace_root=workspace_root,
+            artifact_root=artifact_root,
+            runtime_path=runtime_path.resolve(),
+            status=parsed.status,
+            screen_sequence=parsed.screen_sequence,
+            current_screen_id=None,
+        )
+
+    def persist(
+        self,
+        runtime: WorkspaceRuntime,
+        *,
+        runtime_path: Path | None = None,
+    ) -> None:
+        target_runtime_path = runtime_path or runtime.runtime_path
+        state_payload = build_persistence_model(
+            RuntimeStateFile,
+            status=_status_for_persisted_runtime(runtime.status),
+            screen_sequence=runtime.screen_sequence,
+            updated_at=now_isoformat(),
+        ).model_dump(by_alias=True, mode="json")
+        state_payload["schemaVersion"] = RUNTIME_STATE_SCHEMA_VERSION
+        atomic_write_json(target_runtime_path, state_payload)
+
+
+def now_isoformat() -> str:
+    return (
+        datetime.now(timezone.utc)
+        .replace(microsecond=0)
+        .isoformat()
+        .replace("+00:00", "Z")
+    )
+
+
+def _status_for_persisted_runtime(status: RuntimeStatus) -> RuntimeStatus:
+    if status is RuntimeStatus.READY:
+        return RuntimeStatus.BROKEN
+    return status

androidctld/runtime/store.py

@@ -0,0 +1,76 @@
+"""Workspace runtime store and persistence."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from androidctld.config import DaemonConfig
+from androidctld.protocol import RuntimeStatus
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.runtime.state_repo import RuntimeStateRepository
+from androidctld.schema.persistence import RUNTIME_STATE_FILE_NAME
+
+
+class RuntimeSerialCommandBusyError(RuntimeError):
+    """Raised when a public runtime command is already active."""
+
+
+class RuntimeStore:
+    def __init__(
+        self,
+        config: DaemonConfig,
+        state_repo: RuntimeStateRepository | None = None,
+    ) -> None:
+        self._config = config
+        self._state_repo = state_repo or RuntimeStateRepository()
+        self._lock = threading.RLock()
+        self._runtime: WorkspaceRuntime | None = None
+        self._active_command: str | None = None
+
+    def get_runtime(self) -> WorkspaceRuntime:
+        with self._lock:
+            if self._runtime is None:
+                runtime_path = (
+                    self._config.workspace_root
+                    / ".androidctl"
+                    / RUNTIME_STATE_FILE_NAME
+                )
+                loaded = self._state_repo.load(runtime_path)
+                if loaded is None:
+                    artifact_root = runtime_path.parent
+                    self._runtime = WorkspaceRuntime(
+                        workspace_root=self._config.workspace_root,
+                        artifact_root=artifact_root,
+                        runtime_path=runtime_path,
+                        status=RuntimeStatus.NEW,
+                    )
+                else:
+                    self._runtime = loaded
+            return self._runtime
+
+    def persist_runtime(self, runtime: WorkspaceRuntime) -> None:
+        artifact_root = self._config.workspace_root / ".androidctl"
+        self._state_repo.persist(
+            runtime,
+            runtime_path=artifact_root / RUNTIME_STATE_FILE_NAME,
+        )
+
+    def ensure_runtime(self) -> WorkspaceRuntime:
+        return self.get_runtime()
+
+    @contextmanager
+    def begin_serial_command(self, command_name: str) -> Iterator[None]:
+        with self._lock:
+            if self._active_command is not None:
+                raise RuntimeSerialCommandBusyError(
+                    "overlapping control requests are not allowed"
+                )
+            self._active_command = command_name
+        try:
+            yield
+        finally:
+            with self._lock:
+                if self._active_command == command_name:
+                    self._active_command = None

androidctld/runtime_policy.py

@@ -0,0 +1,127 @@
+"""Runtime policy constants shared across androidctld subsystems."""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+from androidctld.protocol import CommandKind
+
+DEFAULT_DEVICE_PORT: Final[int] = 17171
+DEFAULT_DEVICE_RPC_TIMEOUT_SECONDS: Final[float] = 5.0
+ANDROID_SCREENSHOT_METHOD_TIMEOUT_SECONDS: Final[float] = 11.0
+SCREENSHOT_DEVICE_RPC_TRANSPORT_MARGIN_SECONDS: Final[float] = 1.0
+SCREENSHOT_DEVICE_RPC_TIMEOUT_SECONDS: Final[float] = (
+    ANDROID_SCREENSHOT_METHOD_TIMEOUT_SECONDS
+    + SCREENSHOT_DEVICE_RPC_TRANSPORT_MARGIN_SECONDS
+)
+ADB_COMMAND_TIMEOUT_SECONDS: Final[float] = 10.0
+DAEMON_HTTP_MAX_REQUEST_BODY_BYTES: Final[int] = 1 * 1024 * 1024
+DAEMON_HTTP_SOCKET_TIMEOUT_SECONDS: Final[float] = 5.0
+DEVICE_RPC_MAX_RESPONSE_BYTES: Final[int] = 4 * 1024 * 1024
+SCREENSHOT_MAX_BINARY_BYTES: Final[int] = 32 * 1024 * 1024
+SCREENSHOT_MAX_BASE64_CHARS: Final[int] = ((SCREENSHOT_MAX_BINARY_BYTES + 2) // 3) * 4
+SCREENSHOT_MAX_RPC_RESPONSE_BYTES: Final[int] = 48 * 1024 * 1024
+SCREENSHOT_MAX_OUTPUT_PIXELS: Final[int] = 16_777_216
+MAIN_LOOP_SLEEP_SECONDS: Final[float] = 0.1
+NON_NUMERIC_REF_SORT_BUCKET: Final[int] = 1_000_000_000
+
+DEVICE_RPC_REQUEST_ID_BOOTSTRAP: Final[str] = "androidctld-bootstrap"
+DEVICE_RPC_REQUEST_ID_SNAPSHOT: Final[str] = "androidctld-snapshot"
+DEVICE_RPC_REQUEST_ID_SETTLE: Final[str] = "androidctld-settle"
+DEVICE_RPC_REQUEST_ID_ACTION: Final[str] = "androidctld-action"
+DEVICE_RPC_REQUEST_ID_ACTION_REPAIRED: Final[str] = "androidctld-action-repaired"
+DEVICE_RPC_REQUEST_ID_WAIT: Final[str] = "androidctld-wait"
+DEVICE_RPC_REQUEST_ID_SCREENSHOT: Final[str] = "androidctld-screenshot"
+DEVICE_RPC_REQUEST_ID_LIST_APPS: Final[str] = "androidctld-list-apps"
+
+DEFAULT_SNAPSHOT_INCLUDE_INVISIBLE: Final[bool] = True
+DEFAULT_SNAPSHOT_INCLUDE_SYSTEM_WINDOWS: Final[bool] = True
+DEFAULT_SCREENSHOT_FORMAT: Final[str] = "png"
+DEFAULT_SCREENSHOT_SCALE: Final[float] = 1.0
+
+DEFAULT_SETTLE_MIN_GRACE_MS: Final[int] = 200
+SETTLE_MIN_GRACE_MS_BY_COMMAND: Final[dict[CommandKind, int]] = {
+    CommandKind.OPEN: 500,
+}
+DEFAULT_SETTLE_MAX_TOTAL_MS: Final[int] = 1200
+SETTLE_MAX_TOTAL_MS_BY_COMMAND: Final[dict[CommandKind, int]] = {
+    CommandKind.OPEN: 4000,
+}
+DEFAULT_SETTLE_STABLE_WINDOW_MS: Final[int] = 300
+SETTLE_STABLE_WINDOW_MS_BY_COMMAND: Final[dict[CommandKind, int]] = {
+    CommandKind.OPEN: 500,
+}
+DEFAULT_SETTLE_SNAPSHOT_MAX_INTERVAL_MS: Final[int] = 250
+SETTLE_SNAPSHOT_MAX_INTERVAL_MS_BY_COMMAND: Final[dict[CommandKind, int]] = {
+    CommandKind.OPEN: 500,
+}
+SETTLE_POLL_SLICE_MS: Final[int] = 100
+
+WAIT_TIMEOUT_MS_BY_KIND: Final[dict[str, int]] = {
+    "text": 3000,
+    "screen-change": 3000,
+    "gone": 3000,
+    "app": 3000,
+    "idle": 3000,
+}
+
+ACTION_TIMEOUT_MS_BY_COMMAND: Final[dict[CommandKind, int]] = {
+    CommandKind.OPEN: 5000,
+    CommandKind.TAP: 5000,
+    CommandKind.LONG_TAP: 5000,
+    CommandKind.TYPE: 8000,
+    CommandKind.GLOBAL: 5000,
+    CommandKind.SCROLL: 5000,
+    CommandKind.FOCUS: 5000,
+    CommandKind.SUBMIT: 5000,
+}
+
+WAIT_EVENT_POLL_SLICE_MS: Final[int] = 250
+WAIT_SNAPSHOT_MAX_INTERVAL_MS: Final[int] = 500
+WAIT_LOOP_SLEEP_SECONDS: Final[float] = 0.05
+TRANSIENT_INVALID_SNAPSHOT_RETRY_SECONDS: Final[float] = 0.05
+TRANSIENT_INVALID_SNAPSHOT_MAX_RETRIES: Final[int] = 2
+WAIT_IDLE_STABLE_WINDOW_MS: Final[int] = 500
+QUERY_PROGRESS_WAIT_SECONDS: Final[float] = 0.2
+QUERY_PROGRESS_POLL_SECONDS: Final[float] = 0.02
+
+
+def settle_min_grace_ms(kind: CommandKind) -> int:
+    return SETTLE_MIN_GRACE_MS_BY_COMMAND.get(kind, DEFAULT_SETTLE_MIN_GRACE_MS)
+
+
+def settle_max_total_ms(kind: CommandKind) -> int:
+    return SETTLE_MAX_TOTAL_MS_BY_COMMAND.get(kind, DEFAULT_SETTLE_MAX_TOTAL_MS)
+
+
+def settle_stable_window_ms(kind: CommandKind) -> int:
+    return SETTLE_STABLE_WINDOW_MS_BY_COMMAND.get(kind, DEFAULT_SETTLE_STABLE_WINDOW_MS)
+
+
+def settle_snapshot_max_interval_ms(kind: CommandKind) -> int:
+    return SETTLE_SNAPSHOT_MAX_INTERVAL_MS_BY_COMMAND.get(
+        kind, DEFAULT_SETTLE_SNAPSHOT_MAX_INTERVAL_MS
+    )
+
+
+def default_wait_timeout_ms(wait_kind: object) -> int:
+    normalized = str(getattr(wait_kind, "value", wait_kind))
+    return WAIT_TIMEOUT_MS_BY_KIND[normalized]
+
+
+def action_timeout_ms(kind: CommandKind) -> int:
+    return ACTION_TIMEOUT_MS_BY_COMMAND[kind]
+
+
+def default_snapshot_params() -> dict[str, bool]:
+    return {
+        "includeInvisible": DEFAULT_SNAPSHOT_INCLUDE_INVISIBLE,
+        "includeSystemWindows": DEFAULT_SNAPSHOT_INCLUDE_SYSTEM_WINDOWS,
+    }
+
+
+def default_screenshot_params() -> dict[str, Any]:
+    return {
+        "format": DEFAULT_SCREENSHOT_FORMAT,
+        "scale": DEFAULT_SCREENSHOT_SCALE,
+    }

androidctld/schema/__init__.py

@@ -0,0 +1,5 @@
+"""Schema helpers for daemon ingress, persistence, and device payloads."""
+
+from androidctld.schema.base import ApiModel, to_camel
+
+__all__ = ["ApiModel", "to_camel"]

androidctld/schema/base.py

@@ -0,0 +1,132 @@
+"""Shared boundary-model conventions for androidctld schemas."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+from pydantic_core import InitErrorDetails
+from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from pydantic._internal._model_construction import ModelMetaclass as _ModelMetaclass
+else:
+    _ModelMetaclass = type(BaseModel)
+
+
+def to_camel(name: str) -> str:
+    parts = name.split("_")
+    if len(parts) == 1:
+        return name
+    head, *tail = parts
+    return head + "".join(
+        segment[:1].upper() + segment[1:] for segment in tail if segment
+    )
+
+
+class _ApiModelMeta(_ModelMetaclass):
+    def __call__(cls, *args: Any, **kwargs: Any) -> Any:
+        model_cls = cast(type[ApiModel], cls)
+        if kwargs and model_cls._contains_alias_kwargs(kwargs):
+            raise ValidationError.from_exception_data(
+                model_cls.__name__,
+                model_cls._alias_init_errors(kwargs),
+            )
+        return super().__call__(*args, **kwargs)
+
+
+class ApiModel(BaseModel, metaclass=_ApiModelMeta):
+    model_config = ConfigDict(
+        strict=True,
+        extra="forbid",
+        alias_generator=to_camel,
+        validate_by_alias=True,
+        validate_by_name=True,
+        use_enum_values=False,
+    )
+
+    @classmethod
+    def model_validate(
+        cls,
+        obj: Any,
+        *,
+        strict: bool | None = None,
+        extra: Literal["allow", "ignore", "forbid"] | None = None,
+        from_attributes: bool | None = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> Self:
+        # External payload parsing stays alias-only by default, while internal
+        # code can still use normal snake_case keyword construction.
+        return super().model_validate(
+            obj,
+            strict=strict,
+            extra=extra,
+            from_attributes=from_attributes,
+            context=context,
+            by_alias=True if by_alias is None else by_alias,
+            by_name=False if by_name is None else by_name,
+        )
+
+    @classmethod
+    def model_validate_json(
+        cls,
+        json_data: str | bytes | bytearray,
+        *,
+        strict: bool | None = None,
+        extra: Literal["allow", "ignore", "forbid"] | None = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> Self:
+        return super().model_validate_json(
+            json_data,
+            strict=strict,
+            extra=extra,
+            context=context,
+            by_alias=True if by_alias is None else by_alias,
+            by_name=False if by_name is None else by_name,
+        )
+
+    def model_copy(
+        self,
+        *,
+        update: Mapping[str, Any] | None = None,
+        deep: bool = False,
+    ) -> Self:
+        model_type = type(self)
+        if update and model_type._contains_alias_kwargs(update):
+            raise ValidationError.from_exception_data(
+                model_type.__name__,
+                model_type._alias_init_errors(update),
+            )
+        return super().model_copy(update=update, deep=deep)
+
+    @classmethod
+    def _contains_alias_kwargs(cls, data: Mapping[str, Any]) -> bool:
+        return any(
+            field.alias is not None
+            and field.alias != field_name
+            and field.alias in data
+            for field_name, field in cls.model_fields.items()
+        )
+
+    @classmethod
+    def _alias_init_errors(cls, data: Mapping[str, Any]) -> list[InitErrorDetails]:
+        return [
+            InitErrorDetails(
+                type="extra_forbidden",
+                loc=(field.alias,),
+                input=data[field.alias],
+            )
+            for field_name, field in cls.model_fields.items()
+            if field.alias is not None
+            and field.alias != field_name
+            and field.alias in data
+        ]
+
+
+def dump_api_model(model: ApiModel) -> dict[str, Any]:
+    return model.model_dump(by_alias=True, mode="json")

androidctld/schema/core.py

@@ -0,0 +1,35 @@
+"""Shared schema decoding helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SchemaDecodeError(ValueError):
+    field: str
+    problem: str
+
+    def __str__(self) -> str:
+        return f"{self.field} {self.problem}"
+
+
+def expect_field(payload: dict[str, Any], key: str, field_name: str) -> object:
+    if key not in payload:
+        raise SchemaDecodeError(field_name, "is required")
+    return payload[key]
+
+
+def expect_object(value: object, field_name: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise SchemaDecodeError(field_name, "must be a JSON object")
+    return dict(value)
+
+
+def expect_int(value: object, field_name: str, minimum: int | None = None) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise SchemaDecodeError(field_name, "must be an integer")
+    if minimum is not None and value < minimum:
+        raise SchemaDecodeError(field_name, f"must be an integer >= {minimum}")
+    return value

androidctld/schema/daemon_api.py

@@ -0,0 +1,108 @@
+"""Typed daemon ingress parsing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import ValidationError
+
+from androidctl_contracts import daemon_api as wire_api
+from androidctl_contracts.command_catalog import is_daemon_command_kind
+from androidctl_contracts.daemon_api import HealthResult
+from androidctld.commands.command_models import InternalCommand
+from androidctld.commands.from_boundary import (
+    compile_connect_command,
+    compile_global_action_command,
+    compile_list_apps_command,
+    compile_observe_command,
+    compile_open_command,
+    compile_ref_action_command,
+    compile_screenshot_command,
+    compile_service_wait_command,
+)
+from androidctld.errors import bad_request
+from androidctld.schema.validation_errors import validation_error_to_bad_request
+
+__all__ = [
+    "HealthResult",
+    "ParsedCommandRun",
+    "parse_command_run_request",
+    "require_empty_payload",
+]
+
+
+@dataclass(frozen=True)
+class ParsedCommandRun:
+    command: InternalCommand
+
+
+def require_empty_payload(payload: dict[str, Any], route: str) -> None:
+    if payload:
+        raise bad_request(f"{route} does not accept request payload")
+
+
+def parse_command_run_request(payload: dict[str, Any]) -> ParsedCommandRun:
+    _validate_command_run_payload_shape(payload)
+    try:
+        boundary = wire_api.CommandRunRequest.model_validate(
+            payload,
+            strict=True,
+        )
+    except ValidationError as error:
+        raise validation_error_to_bad_request(error, field_name=None) from error
+    return ParsedCommandRun(
+        command=_adapt_wire_command_payload(boundary.command),
+    )
+
+
+def _validate_command_run_payload_shape(payload: dict[str, Any]) -> None:
+    if "command" not in payload:
+        raise bad_request("command is required", {"field": "command"})
+
+    command = payload["command"]
+    if not isinstance(command, dict):
+        raise bad_request("command must be a JSON object", {"field": "command"})
+
+    kind_raw = command.get("kind")
+    if not isinstance(kind_raw, str):
+        raise bad_request("command.kind must be a string", {"field": "command.kind"})
+
+    kind = kind_raw.strip()
+    if not kind:
+        raise bad_request(
+            "command.kind must be a non-empty string",
+            {"field": "command.kind"},
+        )
+
+    if not is_daemon_command_kind(kind):
+        raise bad_request(
+            "unsupported command kind",
+            {"field": "command.kind", "kind": kind},
+        )
+
+
+def _adapt_wire_command_payload(
+    payload: wire_api.DaemonCommandPayload,
+) -> InternalCommand:
+    if isinstance(payload, wire_api.ConnectCommandPayload):
+        return compile_connect_command(payload)
+    if isinstance(payload, wire_api.ObserveCommandPayload):
+        return compile_observe_command(payload)
+    if isinstance(payload, wire_api.ListAppsCommandPayload):
+        return compile_list_apps_command(payload)
+    if isinstance(payload, wire_api.OpenCommandPayload):
+        return compile_open_command(payload)
+    if isinstance(payload, wire_api.RefActionCommandPayload):
+        return compile_ref_action_command(payload)
+    if isinstance(payload, wire_api.TypeCommandPayload):
+        return compile_ref_action_command(payload)
+    if isinstance(payload, wire_api.ScrollCommandPayload):
+        return compile_ref_action_command(payload)
+    if isinstance(payload, wire_api.GlobalActionCommandPayload):
+        return compile_global_action_command(payload)
+    if isinstance(payload, wire_api.WaitCommandPayload):
+        return compile_service_wait_command(payload)
+    if isinstance(payload, wire_api.ScreenshotCommandPayload):
+        return compile_screenshot_command(payload)
+    raise TypeError(f"unsupported wire command payload: {type(payload)!r}")