android-midscene-automation 0.2.4 → 1.1.1

package/artemis-main/artemis/config/settings.py

@@ -0,0 +1,315 @@
+# 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.
+
+"""Application settings and environment variable configuration management."""
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+from pydantic import Field, SecretStr, model_validator
+from pydantic_settings import BaseSettings
+
+from artemis.config.constants import (
+    DEFAULT_ADB_HOST,
+    DEFAULT_ADB_PORT,
+    DEFAULT_MODEL,
+    DEFAULT_PROFILE,
+    ENV_ANTHROPIC_API_KEY,
+    ENV_DATA_ENGINE_DB_PATH,
+    ENV_GCP_API_KEY,
+    ENV_GEMINI_API_KEY,
+    ENV_GOOGLE_API_KEY,
+    ENV_OCR_API_KEY,
+    ENV_OPEN_ROUTER_API_KEY,
+    ENV_OPENAI_API_KEY,
+    ENV_VISION_API_KEY,
+    ENV_XAI_API_KEY,
+)
+from artemis.config.paths import (
+    GLOBAL_APP_DIR,
+    get_data_engine_db_path,
+    get_default_traces_path,
+    get_env_file,
+    get_temp_dir,
+)
+from third_party.mobile_use.utils.logger import get_logger
+
+# Installed wheels load .env from the user directory, outside site-packages.
+_canonical_env = get_env_file()
+load_dotenv(dotenv_path=_canonical_env, verbose=True)
+_global_env = GLOBAL_APP_DIR / ".env"
+if _global_env.exists() and _global_env.resolve() != _canonical_env.resolve():
+    load_dotenv(dotenv_path=_global_env, verbose=True)
+
+logger = get_logger(__name__)
+
+
+def is_placeholder_key(val: str | SecretStr | None) -> bool:
+    """Check if an API credential is empty or an unconfigured placeholder value."""
+    if val is None:
+        return True
+    raw_str = val.get_secret_value() if isinstance(val, SecretStr) else str(val)
+    raw_str = raw_str.strip().lower()
+    if not raw_str:
+        return True
+    if raw_str in (
+        "api_key",
+        "your_api_key",
+        "your_api_key_here",
+        "your_gemini_api_key_here",
+        "your_google_cloud_vision_api_key_here",
+        "your_openai_api_key_here",
+        "your_anthropic_api_key_here",
+        "your_openrouter_api_key_here",
+        "your_xai_api_key_here",
+        "none",
+        "empty",
+        "null",
+        "undefined",
+    ):
+        return True
+    if (
+        (raw_str.startswith("your_") and raw_str.endswith("_here"))
+        or (raw_str.startswith("<") and raw_str.endswith(">"))
+        or (raw_str.startswith("[") and raw_str.endswith("]"))
+    ):
+        return True
+    return False
+
+
+class Settings(BaseSettings):
+    """Centralized ARTEMIS runtime settings loaded from environment and .env files."""
+
+    # LLM Provider Authentication
+    OPENAI_API_KEY: SecretStr | None = None
+    GOOGLE_API_KEY: SecretStr | None = None
+    GEMINI_API_KEY: SecretStr | None = None
+    GCP_API_KEY: SecretStr | None = None
+    ANTHROPIC_API_KEY: SecretStr | None = None
+    XAI_API_KEY: SecretStr | None = None
+    OPEN_ROUTER_API_KEY: SecretStr | None = None
+
+    # Google Cloud Vision OCR Authentication
+    OCR_API_KEY: SecretStr | None = None
+    VISION_API_KEY: SecretStr | None = None
+    API_KEY: SecretStr | None = None
+
+    # Custom Provider Endpoints
+    OPENAI_BASE_URL: str | None = None
+
+    # Android ADB Connectivity
+    ADB_HOST: str | None = Field(default=DEFAULT_ADB_HOST)
+    ADB_PORT: int | None = Field(default=DEFAULT_ADB_PORT)
+    ADB_DEVICE_SERIAL: str | None = None
+    # UI hierarchy backend: "auto" = Accessibility Helper with UIAutomator2
+    # fallback, "helper" = helper only, "uiautomator" = UIAutomator2 only.
+    ARTEMIS_HIERARCHY_BACKEND: str = Field(default="auto")
+    # Whether a task may install / upgrade the Accessibility Helper APK on a device
+    # it holds. False = only attach to a helper installed by `artemis helper install`.
+    ARTEMIS_HELPER_AUTO_INSTALL: bool = Field(default=True)
+
+    # Execution Defaults
+    PROJECT_NAME: str | None = None
+    ARTEMIS_DEFAULT_PROFILE: str = Field(default=DEFAULT_PROFILE)
+    ARTEMIS_DEFAULT_MODEL: str = Field(default=DEFAULT_MODEL)
+
+    # Explorer Tool Settings (the tier itself is configured in artemis.jsonc or
+    # via ARTEMIS_EXPLORER_VERSION; see artemis.config.agent.ExplorerConfig)
+    EXPLORER_CACHING: bool | None = Field(
+        default=None,
+        description=(
+            "Environment-level override for Explorer context caching; unset"
+            " defers to the agent configuration and the tier default."
+        ),
+    )
+
+    # LLM Reliability
+    LLM_PAUSE_TIMEOUT_SECONDS: float = Field(
+        default=900.0,
+        description=(
+            "How long a task waits in the paused state after exhausting LLM"
+            " retries before failing with LLMExhaustedError. <= 0 waits"
+            " forever (legacy interactive behavior)."
+        ),
+    )
+
+    # Paths & Storage
+    TRACES_PATH: Path = Field(default_factory=get_default_traces_path)
+    DATA_ENGINE_DB_PATH: Path = Field(default_factory=get_data_engine_db_path)
+    TEMP_PATH: Path = Field(default_factory=get_temp_dir)
+
+    model_config = {"env_file": ".env", "extra": "ignore"}
+
+    @model_validator(mode="after")
+    def fallback_api_keys(self) -> "Settings":
+        """Normalize Google / Gemini / GCP and OCR API keys and filter placeholders."""
+        # Sanitize any placeholder values loaded from environment or .env
+        for attr in (
+            "OPENAI_API_KEY",
+            "GOOGLE_API_KEY",
+            "GEMINI_API_KEY",
+            "GCP_API_KEY",
+            "ANTHROPIC_API_KEY",
+            "XAI_API_KEY",
+            "OPEN_ROUTER_API_KEY",
+            "OCR_API_KEY",
+            "VISION_API_KEY",
+            "API_KEY",
+        ):
+            val = getattr(self, attr, None)
+            if val and is_placeholder_key(val):
+                setattr(self, attr, None)
+
+        if not self.GOOGLE_API_KEY:
+            if self.GEMINI_API_KEY:
+                self.GOOGLE_API_KEY = self.GEMINI_API_KEY
+            elif self.GCP_API_KEY:
+                self.GOOGLE_API_KEY = self.GCP_API_KEY
+
+        # Fallback for OCR & Vision API keys
+        if not self.OCR_API_KEY and self.VISION_API_KEY:
+            self.OCR_API_KEY = self.VISION_API_KEY
+        return self
+
+    def get_api_key(self, provider: str) -> SecretStr | None:
+        """Get API key for a specified provider.
+
+        Args:
+            provider: Provider name (e.g., 'google', 'gemini', 'openai', 'ocr', 'vision').
+
+        Returns:
+            SecretStr containing the API key or None if not configured.
+        """
+        from artemis.llm.google.provider import is_google_family_provider
+
+        provider_lower = provider.lower()
+        key: SecretStr | None = None
+        if is_google_family_provider(provider_lower):
+            key = self.GOOGLE_API_KEY or self.GEMINI_API_KEY or self.GCP_API_KEY
+        elif provider_lower in ("ocr", "vision", "google_vision"):
+            key = self.OCR_API_KEY or self.VISION_API_KEY
+        elif provider_lower == "openai":
+            key = self.OPENAI_API_KEY
+        elif provider_lower in ("anthropic", "claude"):
+            key = self.ANTHROPIC_API_KEY
+        elif provider_lower == "openrouter":
+            key = self.OPEN_ROUTER_API_KEY
+        elif provider_lower in ("xai", "grok"):
+            key = self.XAI_API_KEY
+
+        if key and not is_placeholder_key(key):
+            return key
+        return None
+
+    def set_api_key(self, provider: str, key: str, persist_to_env: bool = False) -> None:
+        """Dynamically set an API key at runtime, optionally persisting to .env in the app dir.
+
+        Args:
+            provider: Target provider name.
+            key: Secret API key string.
+            persist_to_env: Whether to save the key to the app directory's .env file.
+        """
+        secret = SecretStr(key)
+        from artemis.llm.google.provider import is_google_family_provider
+
+        provider_lower = provider.lower()
+        env_key_name = None
+
+        if is_google_family_provider(provider_lower):
+            self.GOOGLE_API_KEY = secret
+            self.GEMINI_API_KEY = secret
+            self.GCP_API_KEY = secret
+            env_key_name = ENV_GEMINI_API_KEY
+            os.environ[ENV_GOOGLE_API_KEY] = key
+            os.environ[ENV_GEMINI_API_KEY] = key
+            os.environ[ENV_GCP_API_KEY] = key
+        elif provider_lower == "openai":
+            self.OPENAI_API_KEY = secret
+            env_key_name = ENV_OPENAI_API_KEY
+            os.environ[ENV_OPENAI_API_KEY] = key
+        elif provider_lower in ("anthropic", "claude"):
+            self.ANTHROPIC_API_KEY = secret
+            env_key_name = ENV_ANTHROPIC_API_KEY
+            os.environ[ENV_ANTHROPIC_API_KEY] = key
+        elif provider_lower == "openrouter":
+            self.OPEN_ROUTER_API_KEY = secret
+            env_key_name = ENV_OPEN_ROUTER_API_KEY
+            os.environ[ENV_OPEN_ROUTER_API_KEY] = key
+        elif provider_lower == "xai":
+            self.XAI_API_KEY = secret
+            env_key_name = ENV_XAI_API_KEY
+            os.environ[ENV_XAI_API_KEY] = key
+        elif provider_lower in ("ocr", "vision", "google_vision"):
+            self.OCR_API_KEY = secret
+            self.VISION_API_KEY = secret
+            env_key_name = ENV_OCR_API_KEY
+            os.environ[ENV_OCR_API_KEY] = key
+            os.environ[ENV_VISION_API_KEY] = key
+
+        if persist_to_env and env_key_name:
+            target_env_files = [get_env_file()]
+            seen_paths = set()
+            for env_file in target_env_files:
+                try:
+                    env_file.parent.mkdir(parents=True, exist_ok=True)
+                    resolved = env_file.resolve()
+                    if resolved in seen_paths:
+                        continue
+                    seen_paths.add(resolved)
+
+                    lines = []
+                    if env_file.exists():
+                        lines = env_file.read_text(encoding="utf-8").splitlines()
+
+                    # Determine keys to update
+                    keys_to_update = [env_key_name]
+                    if is_google_family_provider(provider_lower):
+                        keys_to_update = [ENV_GEMINI_API_KEY, ENV_GOOGLE_API_KEY, ENV_GCP_API_KEY]
+                    elif provider_lower in ("ocr", "vision", "google_vision"):
+                        keys_to_update = [ENV_OCR_API_KEY, ENV_VISION_API_KEY]
+
+                    new_lines = []
+                    updated_set = set()
+                    for line in lines:
+                        replaced = False
+                        for k in keys_to_update:
+                            if (
+                                line.startswith(f"{k}=")
+                                or line.startswith(f"#{k}=")
+                                or line.startswith(f"# {k}=")
+                            ):
+                                new_lines.append(f"{k}={key}")
+                                updated_set.add(k)
+                                replaced = True
+                                break
+                        if not replaced:
+                            new_lines.append(line)
+
+                    # Ensure the primary key is present if not replaced
+                    primary_key = keys_to_update[0]
+                    if primary_key not in updated_set:
+                        new_lines.append(f"{primary_key}={key}")
+
+                    env_file.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
+                except Exception as e:
+                    logger.warning(f"Could not persist {env_key_name} to {env_file}: {e}")
+
+
+# Singleton instance
+settings = Settings()
+
+# Synchronize DATA_ENGINE_DB_PATH in environment for external sub-processes/tools
+if settings.DATA_ENGINE_DB_PATH:
+    os.environ[ENV_DATA_ENGINE_DB_PATH] = str(settings.DATA_ENGINE_DB_PATH)

package/artemis-main/artemis/constants.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.
+
+RECURSION_LIMIT = 30000
+
+# Optimization Constants
+CHECKER_MAX_ITERATIONS = 20
+VALIDATOR_POLL_TIMEOUT = 2.0
+VALIDATOR_POLL_INTERVAL = 0.2
+VALIDATOR_OCR_INTERVAL = 1.0
+VALIDATOR_UI_HIERARCHY_TIMEOUT = 1.0
+
+from google.genai import types as _genai_types
+
+SAFETY_SETTINGS_BLOCK_NONE = [
+    _genai_types.SafetySetting(
+        category=_genai_types.HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+        threshold=_genai_types.HarmBlockThreshold.BLOCK_NONE,
+    ),
+    _genai_types.SafetySetting(
+        category=_genai_types.HarmCategory.HARM_CATEGORY_HARASSMENT,
+        threshold=_genai_types.HarmBlockThreshold.BLOCK_NONE,
+    ),
+    _genai_types.SafetySetting(
+        category=_genai_types.HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
+        threshold=_genai_types.HarmBlockThreshold.BLOCK_NONE,
+    ),
+    _genai_types.SafetySetting(
+        category=_genai_types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+        threshold=_genai_types.HarmBlockThreshold.BLOCK_NONE,
+    ),
+    _genai_types.SafetySetting(
+        category=_genai_types.HarmCategory.HARM_CATEGORY_CIVIC_INTEGRITY,
+        threshold=_genai_types.HarmBlockThreshold.BLOCK_NONE,
+    ),
+]

package/artemis-main/artemis/context.py

@@ -0,0 +1,289 @@
+# 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.
+
+"""Runtime context shared by Artemis agents, tools and drivers for a single task run."""
+
+from __future__ import annotations
+
+import asyncio
+
+from pathlib import Path
+from typing import Any, Literal, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from artemis.data_engine.engine import DataEngine
+
+try:
+    from adbutils import AdbClient
+except ImportError:
+    AdbClient = Any
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+from artemis.utils.video import detect_video_tools_enabled
+
+
+from artemis.config import ExplorerConfig, LLMConfig, OutputterConfig
+
+
+from third_party.mobile_use.context import (
+    AppLaunchResult,
+    DeviceContext,
+    DeviceClientAccessors,
+    DevicePlatform,
+    ExecutionSetupBase,
+)
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ExecutionSetup(ExecutionSetupBase):
+    """Execution setup for a task."""
+
+    video_recording_tools_enabled: bool = Field(default_factory=detect_video_tools_enabled)
+    disable_checker: bool = False
+    """Legacy master switch (compat alias): ``True`` disables BOTH the midway
+    checkpoints and the final check, regardless of the individual gates below.
+    Factory default is ``False``: the exit final review runs out of the box."""
+    disable_midway_checks: bool = True
+    """Midway checkpoints are OFF by default (factory layering: final check on,
+    planner validation on, midway checks off)."""
+    disable_final_check: bool = False
+    checker_max_iterations: int = 20
+    final_check_max_attempts: int = 3
+    checkpoint_max_repairs: int = 2
+    max_concurrent_checkpoints: int = 3
+    checkpoint_timeout: float = 180.0
+    settlement_timeout: float = 120.0
+    assert_failure_policy: Literal["continue", "halt"] = "continue"
+    disable_device_probes: bool = False
+    disable_planner_validation: bool = False
+    enable_committee: bool = False
+    committee_debate_rounds: int = 2
+    disable_outputter: bool = False
+    outputter: OutputterConfig = Field(default_factory=OutputterConfig)
+    explorer: ExplorerConfig = Field(default_factory=ExplorerConfig)
+    explorer_versions: dict[str, str] = Field(default_factory=dict)
+
+    @property
+    def midway_checks_enabled(self) -> bool:
+        """Midway checkpoint gate: honors both the individual switch and the
+        legacy ``disable_checker`` master alias."""
+        return not (self.disable_midway_checks or self.disable_checker)
+
+    @property
+    def final_check_enabled(self) -> bool:
+        """Final review gate: honors both the individual switch and the legacy
+        ``disable_checker`` master alias."""
+        return not (self.disable_final_check or self.disable_checker)
+
+    @property
+    def checks_enabled(self) -> bool:
+        """True when any check gate is active (drives conditional prompt assembly)."""
+        return self.midway_checks_enabled or self.final_check_enabled
+
+    @property
+    def explorer_version(self) -> str:
+        return self.explorer.default_version
+
+    @property
+    def explorer_flash_mode(self) -> str:
+        return self.explorer.flash_mode
+
+    @property
+    def explorer_pro_mode(self) -> str:
+        return self.explorer.pro_mode
+
+    @property
+    def explorer_caching(self) -> bool | None:
+        return self.explorer.caching
+
+
+class ArtemisContext(DeviceClientAccessors, BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="allow",
+    )
+
+    device: DeviceContext
+    llm_config: LLMConfig | None = None
+    agent_config: Any = None
+    adb_client: Any | None = None
+    ui_adb_client: Any | None = None
+    adb_task_registry: Any | None = None
+    """Per-task ADB background-task registry (``artemis.tools.command_tool``).
+    Created lazily on first ADB tool use; killed at task end."""
+
+    execution_setup: ExecutionSetup | None = None
+
+    data_engine: DataEngine | None = None
+    planner_task: asyncio.Task[Any] | None = None
+    background_tasks: list[asyncio.Task[Any]] = Field(default_factory=list)
+    background_task_grace_period_seconds: float = 2.0
+    package_cache: dict[str, str | None] = Field(default_factory=dict)
+    background_jobs: dict[str, dict[str, Any]] = Field(default_factory=dict)
+
+    pending_checkpoints: list[Any] = Field(default_factory=list)
+    """Queued :class:`~artemis.graph.checkpoints.PendingCheckpoint` entries.
+    ``_process_plan_write`` only enqueues; ``execution_check_node`` spawns after
+    the turn's step is recorded so the evidence anchor points at a real step."""
+    checkpoint_tasks: dict[str, Any] = Field(default_factory=dict)
+    """checkpoint_id -> (attempt_id, asyncio.Task). One in-flight attempt per
+    checkpoint; supersede harvests/cancels the old entry before replacing it."""
+    checkpoint_attempt_seq: dict[str, int] = Field(default_factory=dict)
+    """checkpoint_id -> monotonically increasing attempt counter."""
+    checkpoint_repairs: dict[str, int] = Field(default_factory=dict)
+    """checkpoint_id -> number of verify-fail repairs already applied."""
+    assert_halt: bool = False
+    """Latched by an assert failure under ``assert_failure_policy='halt'``."""
+    final_check_attempts: int = 0
+    """Number of final-check passes already executed at exit settlement."""
+
+    last_validated_plan: str | None = None
+    """Ratchet baseline for planner validation: the last plan content whose
+    top-level milestones were validated (or the initial plan). Drift is always
+    judged against this, never against the immediately preceding write."""
+    pending_validated_plan: str | None = None
+    """Plan content currently under async planner validation; becomes the new
+    baseline when the validator approves it."""
+
+    guidance_unprotected_checks: set[tuple[str, str]] = Field(default_factory=set)
+    """``(kind, text)`` of every check line that existed in the task plan when a
+    mid-run user instruction arrived. User guidance outranks the plan's declared
+    standards, so these lines lose their machine restoration for the rest of the
+    run (the Operator may drop or reword them at any later write); check lines
+    added afterwards stay protected until the next instruction."""
+    guidance_retired_checks: set[tuple[str, str]] = Field(default_factory=set)
+    """``(kind, text)`` of the check lines the Operator actually dropped under
+    that waiver. A verdict recorded for such a line before it was retired is a
+    result for a requirement the user withdrew: the run outcome reports it as
+    retired instead of counting it as a pass or failure."""
+
+    _genai_client: Any | None = PrivateAttr(default=None)
+    _video_blackboard: Any | None = PrivateAttr(default=None)
+    _video_circuit_breaker: Any | None = PrivateAttr(default=None)
+    _mobile_controller: Any | None = PrivateAttr(default=None)
+    _active_driver: Any | None = PrivateAttr(default=None)
+    """Cached device driver singleton (artemis.drivers.factory.get_driver)."""
+    mcp_client_ctx: Any | None = None
+    mcp_session: Any | None = None
+    action_session: Any | None = None
+    """In-process unified action MCP session (artemis.mcp.action_session)."""
+    actuator: Any | None = None
+    """Optional actuator backend override (artemis.mcp.actuators). ``None`` selects
+    the default AdbActuator; installing e.g. a robot-arm backend happens here."""
+
+    step_memory: Any | None = None
+    """Shared :class:`~artemis.memory.step_memory.StepMemoryService` composition
+    root (history redesign §6.2). Created on first use via
+    ``artemis.memory.ensure_step_memory``; Flash and Pro profiles share one
+    instance so summary jobs, retries, and flush semantics are unified."""
+
+    transcript_ledger: Any | None = None
+    """Session :class:`~artemis.memory.transcript.TranscriptLedger` for the Pro
+    operator's transcript prompt path (``agent.memory.transcript.enabled``).
+    Lives beside ``step_memory``; the State never carries message payloads."""
+
+    async def __aenter__(self) -> ArtemisContext:
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        # Close the in-process action session before draining background tasks so its
+        # owner task exits cleanly rather than being cancelled below.
+        if self.action_session is not None:
+            try:
+                await self.action_session.aclose()
+            except Exception as exc:
+                logger.debug(f"Action session close failed; skipped: {exc}", exc_info=True)
+            finally:
+                self.action_session = None
+
+        # Drain in-flight step-summary jobs before the generic background-task
+        # sweep: the shared service owns its own bounded flush semantics. On an
+        # exceptional exit the flush is skipped and the jobs are cancelled below.
+        if self.step_memory is not None and callable(getattr(self.step_memory, "flush", None)):
+            try:
+                if exc_type is None:
+                    await self.step_memory.flush()
+                else:
+                    await self.step_memory.flush(timeout_seconds=0.0)
+            except Exception as exc:
+                logger.debug(f"Step-memory flush failed; skipped: {exc}", exc_info=True)
+
+        # Drain in-flight chunk capsule jobs the same way (M3): the chunk
+        # manager persists any harvested capsules so the DB copy is complete
+        # even though the frozen transcript text is not re-rendered.
+        chunker = getattr(self.transcript_ledger, "chunker", None)
+        if chunker is not None and callable(getattr(chunker, "flush", None)):
+            try:
+                if exc_type is None:
+                    await chunker.flush()
+                else:
+                    await chunker.flush(timeout_seconds=0.0)
+            except Exception as exc:
+                logger.debug(f"History chunk flush failed; skipped: {exc}", exc_info=True)
+
+        if self.background_tasks:
+            tasks = list(self.background_tasks)
+            pending_tasks = [task for task in tasks if not task.done()]
+            grace_period = (
+                max(0.0, self.background_task_grace_period_seconds) if exc_type is None else 0.0
+            )
+
+            if pending_tasks and grace_period > 0:
+                logger.info(
+                    f"Draining {len(pending_tasks)} background tasks for up to "
+                    f"{grace_period:.1f}s..."
+                )
+                _, pending_tasks = await asyncio.wait(
+                    pending_tasks,
+                    timeout=grace_period,
+                )
+
+            if pending_tasks:
+                logger.info(
+                    f"Cancelling {len(pending_tasks)} unfinished background tasks; "
+                    "primary automation is already complete."
+                )
+                for task in pending_tasks:
+                    task.cancel()
+
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            for task, result in zip(tasks, results):
+                if isinstance(result, Exception):
+                    logger.error(
+                        f"Background task {task.get_name()} failed: {result}",
+                        exc_info=result,
+                    )
+            self.background_tasks.clear()
+
+        if self.mcp_client_ctx:
+            try:
+                await self.mcp_client_ctx.__aexit__(exc_type, exc_val, exc_tb)
+            except Exception as exc:
+                logger.debug(f"MCP client context exit failed; skipped: {exc}", exc_info=True)
+            finally:
+                self.mcp_client_ctx = None
+                self.mcp_session = None
+
+        if self.data_engine:
+            try:
+                await self.data_engine.shutdown()
+            except Exception as exc:
+                logger.debug(f"DataEngine shutdown failed; skipped: {exc}", exc_info=True)
+
+
+from artemis.data_engine.engine import DataEngine
+
+ArtemisContext.model_rebuild()

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

@@ -0,0 +1,41 @@
+# 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.
+
+"""Backward compatibility layer for legacy artemis.controllers module.
+All new development should use artemis.drivers instead.
+"""
+
+from artemis.drivers.base import BaseDeviceDriver, KeyCode, ScreenData, SwipeDirection
+from artemis.drivers.factory import create_driver, get_driver
+from artemis.drivers.types import (
+    Bounds,
+    CoordinatesSelectorRequest,
+    PercentagesSelectorRequest,
+    SwipeRequest,
+    TapOutput,
+)
+
+__all__ = [
+    "BaseDeviceDriver",
+    "KeyCode",
+    "ScreenData",
+    "SwipeDirection",
+    "Bounds",
+    "CoordinatesSelectorRequest",
+    "PercentagesSelectorRequest",
+    "SwipeRequest",
+    "TapOutput",
+    "create_driver",
+    "get_driver",
+]