harmonyrun 0.0.29__py3-none-any.whl

droidrun/__init__.py

@@ -0,0 +1,92 @@
+"""
+HarmonyRun - A framework for automating HarmonyOS devices through LLM agents.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("harmonyrun")
+except PackageNotFoundError:
+    # Running from a checkout without installing the distribution (e.g. scripts).
+    __version__ = "0.0.0+unknown"
+
+# Attach a default CLILogHandler so that every consumer (CLI, SDK, tools-only)
+# gets visible output without explicit setup.  CLI may replace this via
+# ``configure_logging()``.
+_logger = logging.getLogger("droidrun")
+try:
+    from droidrun.log_handlers import CLILogHandler
+
+    _logger.addHandler(CLILogHandler())
+    _logger.setLevel(logging.INFO)
+    _logger.propagate = False
+except ImportError:
+    # e.g. ``rich`` not installed — skip; subpackages like ``hdcutils`` still import.
+    pass
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "ResultEvent": ("droidrun.agent", "ResultEvent"),
+    "DroidAgent": ("droidrun.agent.droid", "DroidAgent"),
+    "load_llm": ("droidrun.agent.utils.llm_picker", "load_llm"),
+    "AgentConfig": ("droidrun.config_manager", "AgentConfig"),
+    "AppCardConfig": ("droidrun.config_manager", "AppCardConfig"),
+    "FastAgentConfig": ("droidrun.config_manager", "FastAgentConfig"),
+    "CredentialsConfig": ("droidrun.config_manager", "CredentialsConfig"),
+    "DeviceConfig": ("droidrun.config_manager", "DeviceConfig"),
+    "DroidrunConfig": ("droidrun.config_manager", "DroidrunConfig"),
+    "ExecutorConfig": ("droidrun.config_manager", "ExecutorConfig"),
+    "LLMProfile": ("droidrun.config_manager", "LLMProfile"),
+    "LoggingConfig": ("droidrun.config_manager", "LoggingConfig"),
+    "ManagerConfig": ("droidrun.config_manager", "ManagerConfig"),
+    "TelemetryConfig": ("droidrun.config_manager", "TelemetryConfig"),
+    "ToolsConfig": ("droidrun.config_manager", "ToolsConfig"),
+    "TracingConfig": ("droidrun.config_manager", "TracingConfig"),
+    "DeviceDriver": ("droidrun.tools", "DeviceDriver"),
+    "TreeStateProvider": ("droidrun.tools", "TreeStateProvider"),
+    "HarmonyDriver": ("droidrun.tools", "HarmonyDriver"),
+    "RecordingDriver": ("droidrun.tools", "RecordingDriver"),
+}
+
+
+def __getattr__(name: str) -> object:
+    spec = _LAZY_EXPORTS.get(name)
+    if spec is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    mod_name, attr = spec
+    return getattr(import_module(mod_name), attr)
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals().keys(), *_LAZY_EXPORTS.keys(), "__version__"})
+
+
+# Make main components available at package level
+__all__ = [
+    # Agent
+    "DroidAgent",
+    "load_llm",
+    "ResultEvent",
+    # Tools / Drivers
+    "DeviceDriver",
+    "TreeStateProvider",
+    "HarmonyDriver",
+    "RecordingDriver",
+    # Configuration
+    "DroidrunConfig",
+    "AgentConfig",
+    "FastAgentConfig",
+    "ManagerConfig",
+    "ExecutorConfig",
+    "AppCardConfig",
+    "DeviceConfig",
+    "LoggingConfig",
+    "TracingConfig",
+    "TelemetryConfig",
+    "ToolsConfig",
+    "CredentialsConfig",
+    "LLMProfile",
+]

droidrun/__main__.py

@@ -0,0 +1,8 @@
+"""
+DroidRun main entry point
+"""
+
+from droidrun.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

droidrun/agent/__init__.py

@@ -0,0 +1,3 @@
+from droidrun.agent.droid.events import ResultEvent
+
+__all__ = ["ResultEvent"]

droidrun/agent/action_context.py

@@ -0,0 +1,41 @@
+"""ActionContext — composed bag of dependencies for action functions.
+
+Replaces the ``tools=tools_instance`` parameter that action functions
+previously received.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from droidrun.agent.droid.state import DroidAgentState
+    from droidrun.credential_manager import CredentialManager
+    from droidrun.tools.driver.base import DeviceDriver
+    from droidrun.tools.ui.provider import StateProvider
+    from droidrun.tools.ui.state import UIState
+
+
+class ActionContext:
+    """Everything an action function needs to interact with the device."""
+
+    def __init__(
+        self,
+        driver: "DeviceDriver",
+        ui: "Optional[UIState]",
+        shared_state: "DroidAgentState",
+        state_provider: "StateProvider",
+        app_opener_llm=None,
+        credential_manager: "Optional[CredentialManager]" = None,
+        streaming: bool = False,
+        swipe_fast_default: bool = False,
+    ) -> None:
+        self.driver = driver
+        self.ui = ui  # refreshed each step before tool execution
+        self.shared_state = shared_state
+        self.state_provider = state_provider
+        self.app_opener_llm = app_opener_llm
+        self.credential_manager = credential_manager
+        self.streaming = streaming
+        #: When the ``swipe`` action omits ``fast``, use this (from ``tools.swipe_fast_default``).
+        self.swipe_fast_default = swipe_fast_default

droidrun/agent/action_result.py

@@ -0,0 +1,16 @@
+"""ActionResult — structured return type from action functions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ActionResult:
+    """What the agent sees after an action runs."""
+
+    success: bool
+    summary: str
+
+    def __str__(self) -> str:
+        return self.summary

droidrun/agent/common/constants.py

@@ -0,0 +1,11 @@
+"""Shared constants used across agent and batch packages."""
+
+LLM_HISTORY_LIMIT = 100
+"""Max number of recent conversation steps to include in LLM prompt."""
+
+# Canonical suite-managed resource names.
+# Used by TestCaseResourceManager (batch) and DroidAgent (agent) to coordinate
+# which resources are managed at suite level vs. per-phase level.
+RESOURCE_SCREEN_RECORDING = "screen_recording"
+RESOURCE_HILOG_MONITOR = "hilog_monitor"
+RESOURCE_DEVICE_DRIVER = "device_driver"

droidrun/agent/common/events.py

@@ -0,0 +1,139 @@
+from typing import Any, Dict, Optional
+
+from llama_index.core.workflow import Event
+from pydantic import Field
+
+
+class TimedEvent(Event):
+    """Base event with optional per-event timestamps.
+
+    Every event that flows through DroidAgent gets ``ts_unix`` and
+    ``ts_iso`` stamped by ``DroidAgent.handle_stream_event`` right before
+    it is appended to the trajectory.  Keeping the fields declared as
+    real pydantic fields ensures they end up in ``__dict__`` and are
+    therefore picked up by the trajectory serializer.
+    """
+
+    ts_unix: Optional[float] = None
+    ts_iso: Optional[str] = None
+
+
+class ScreenshotEvent(TimedEvent):
+    screenshot: bytes
+
+
+class RecordUIStateEvent(TimedEvent):
+    """Trajectory UI snapshot.
+
+    Carries the fully-formatted device-state string that was surfaced to
+    the model (phone state + indexed UI tree).  Previously this event
+    also transported the raw element list (``ui_state``); that field was
+    removed because the raw snapshot isn't used for debugging and it
+    bloated trajectory disk output.  The flattened element tree still
+    lives in memory on ``UIState.elements`` for the duration of a step.
+    """
+
+    #: Same string as ``UIState.formatted_text`` / ``shared_state.formatted_device_state``
+    #: (phone state + indexed UI tree) — what goes into manager/executor prompts.
+    formatted_device_state: str = ""
+
+
+class ToolExecutionEvent(TimedEvent):
+    """Emitted after every tool call dispatched through ToolRegistry."""
+
+    tool_name: str
+    tool_args: Dict[str, Any]
+    success: bool
+    summary: str
+    # Latency in milliseconds; None if not measured.
+    latency_ms: Optional[float] = None
+    # Repr of the exception when ``success`` is False.
+    error: Optional[str] = None
+    # Fast-agent turn index this tool call belongs to (1-based).  Lets us
+    # group tool calls by LLM turn when post-analyzing trajectories.
+    step_index: Optional[int] = None
+
+
+class DeviceActionEvent(TimedEvent):
+    """A single mutating or read operation routed through RecordingDriver.
+
+    Device operations are embedded directly in ``trajectory.jsonl`` so one
+    event stream can reconstruct both agent decisions and device I/O.
+    """
+
+    op: str
+    args: Dict[str, Any] = Field(default_factory=dict)
+    success: bool = True
+    error: Optional[str] = None
+    duration_ms: Optional[float] = None
+    # True for pure observation operations (screenshot, get_ui_tree, …).
+    readonly: bool = False
+    # Compact summaries for large read-only results such as screenshots/UI trees.
+    result_summary: Optional[Dict[str, Any]] = None
+
+
+_DEVICE_ENTRY_ARG_FIELDS: tuple[str, ...] = (
+    "subcmd",
+    "cmd",
+    "serial",
+    "returncode",
+    "stdout_preview",
+    "stderr_preview",
+    "timed_out",
+    "layer",
+)
+
+
+def device_action_event_from_entry(entry: Dict[str, Any]) -> DeviceActionEvent:
+    """Build the compact trajectory event for a recorded device operation.
+
+    The old ``device_ops.jsonl`` record carried some raw-hdc fields at top level.
+    To keep trajectory rows compact and consistent, those details are nested
+    under ``args`` only for operations that actually provide them.
+    """
+    args = dict(entry.get("args") or {})
+    for key in _DEVICE_ENTRY_ARG_FIELDS:
+        if key in entry and entry[key] is not None:
+            args.setdefault(key, entry[key])
+
+    return DeviceActionEvent(
+        op=entry.get("op", "unknown"),
+        args=args,
+        success=bool(entry.get("success", True)),
+        error=entry.get("error"),
+        duration_ms=entry.get("duration_ms"),
+        readonly=bool(entry.get("readonly", False)),
+        result_summary=entry.get("result_summary"),
+        ts_unix=entry.get("ts_unix"),
+        ts_iso=entry.get("ts_iso"),
+    )
+
+
+class ErrorEvent(TimedEvent):
+    """Top-level exception captured at driver/tool/workflow boundaries.
+
+    Use this to record unexpected failures so you can later correlate
+    them with the surrounding step / tool call.  The message/traceback
+    are raw strings — keep them succinct enough to be readable in
+    ``trajectory.jsonl``.
+    """
+
+    where: str
+    exception_type: str
+    message: str
+    traceback: Optional[str] = None
+    step_index: Optional[int] = None
+
+
+class PhaseStartEvent(TimedEvent):
+    """Marks the beginning of a test phase (setup/preconditions/test_execution/postconditions/teardown)."""
+
+    phase: str
+
+
+class PhaseEndEvent(TimedEvent):
+    """Marks the end of a test phase."""
+
+    phase: str
+    success: bool
+    reason: str = ""

droidrun/agent/common/ui_state_snapshot.py

@@ -0,0 +1,188 @@
+"""Build UI trajectory snapshots aligned with LLM-facing context.
+
+All blocks use a consistent Markdown-inside-XML-anchor shape so the model
+sees the same structure across fast_agent / manager / executor: each block
+is wrapped in an XML tag (``<device_state>``, ``<previous_device_state>``,
+etc.) for machine parseability, and the body is standard Markdown with
+``### Phone`` / ``### UI Tree`` sub-sections produced by the formatter.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+MANAGER_DEVICE_STATE_OPEN = "\n<device_state>\n## Device State\n\n"
+MANAGER_DEVICE_STATE_CLOSE = "\n</device_state>\n"
+
+
+def manager_device_state_block(formatted_inner: str) -> str:
+    inner = (formatted_inner or "").strip()
+    if not inner:
+        return ""
+    return MANAGER_DEVICE_STATE_OPEN + inner + MANAGER_DEVICE_STATE_CLOSE
+
+
+def manager_memory_block(manager_memory: str) -> str:
+    m = (manager_memory or "").strip()
+    if not m:
+        return ""
+    return f"\n<memory>\n{m}\n</memory>\n"
+
+
+def manager_previous_device_state_block(previous_formatted: str) -> str:
+    prev = (previous_formatted or "").strip()
+    if not prev:
+        return ""
+    return (
+        "\n<previous_device_state>\n"
+        "## Previous Device State\n\n"
+        f"{prev}\n"
+        "</previous_device_state>\n"
+    )
+
+
+def fast_agent_ui_sections(shared_state: Any, step: int, max_steps: int) -> Dict[str, str]:
+    """Fragments FastAgent appends to chat (excluding the image block).
+
+    Must stay in sync with the injection order in ``fast_agent.py`` so that
+    what we snapshot into the trajectory matches what the LLM actually saw.
+
+    Does not drain ``device_events``; caller drains after appending ``device_events``.
+    """
+    out: Dict[str, str] = {}
+    remaining = max_steps - step
+    out["step_progress"] = (
+        f"\n> **Progress:** step {step} / {max_steps} · {remaining} remaining\n"
+    )
+
+    events_text = shared_state.format_device_events()
+    if events_text:
+        out["device_events"] = (
+            "\n<device_events>\n"
+            "### Device Events\n"
+            "_Transient UI events captured via system-level monitoring. "
+            "Use this as the source of truth for toast verification._\n\n"
+            f"{events_text}\n"
+            "</device_events>\n"
+        )
+
+    app_card_text = (shared_state.app_card or "").strip()
+    if app_card_text:
+        out["app_card"] = f"\n<app_card>\n{app_card_text}\n</app_card>\n"
+
+    current_state = (shared_state.formatted_device_state or "").strip()
+    if current_state:
+        out["device_state"] = (
+            "\n<device_state>\n"
+            "## Device State\n\n"
+            f"{current_state}\n"
+            "</device_state>\n"
+        )
+
+    prev = (shared_state.previous_formatted_device_state or "").strip()
+    if prev:
+        out["previous_device_state"] = manager_previous_device_state_block(prev)
+
+    return out
+
+
+def build_fast_agent_ui_snapshot(
+    shared_state: Any,
+    step: int,
+    max_steps: int,
+    elements: List[Dict[str, Any]],
+    phone_state: Dict[str, Any],
+    focused_text: str,
+) -> Dict[str, Any]:
+    sections = fast_agent_ui_sections(shared_state, step, max_steps)
+    # Must match injection order in ``fast_agent.handle_llm_input``:
+    # progress → events → app_card → device_state (freshest closest to model head).
+    last_user = "".join(
+        sections.get(k, "")
+        for k in ("step_progress", "device_events", "app_card", "device_state")
+    )
+    return {
+        "schema_version": 2,
+        "agent": "fast_agent",
+        "elements": elements,
+        "phone_state": dict(phone_state) if phone_state else {},
+        "focused_text": focused_text or "",
+        "formatted_device_state": (shared_state.formatted_device_state or "").strip(),
+        "llm_text_sections": sections,
+        "llm_last_user_message_text": last_user,
+        "llm_second_to_last_user_message_text": sections.get(
+            "previous_device_state", ""
+        ),
+    }
+
+
+def build_manager_ui_snapshot(
+    shared_state: Any,
+    elements: List[Dict[str, Any]],
+    phone_state: Dict[str, Any],
+    focused_text: str,
+    manager_user_message_content: str,
+    user_message_count_before_append: int,
+    vision: bool,
+) -> Dict[str, Any]:
+    current = (shared_state.formatted_device_state or "").strip()
+    prev_plain = (shared_state.previous_formatted_device_state or "").strip()
+
+    memory_block = manager_memory_block(shared_state.manager_memory or "")
+    device_block = manager_device_state_block(shared_state.formatted_device_state or "")
+
+    second_augment = ""
+    if user_message_count_before_append >= 1 and prev_plain:
+        second_augment = manager_previous_device_state_block(
+            shared_state.previous_formatted_device_state or ""
+        )
+
+    return {
+        "schema_version": 2,
+        "agent": "manager",
+        "elements": elements,
+        "phone_state": dict(phone_state) if phone_state else {},
+        "focused_text": focused_text or "",
+        "formatted_device_state": current,
+        "previous_formatted_device_state": prev_plain,
+        "app_card": (shared_state.app_card or "").strip(),
+        "manager_user_message_content": manager_user_message_content,
+        "llm_last_user_text_appendix": memory_block + device_block,
+        "llm_second_to_last_user_text_appendix": second_augment,
+        "vision_includes_current_screenshot": bool(vision),
+    }
+
+
+def build_stateless_manager_ui_snapshot(
+    shared_state: Any,
+    full_user_message_text: str,
+) -> Dict[str, Any]:
+    return {
+        "schema_version": 2,
+        "agent": "stateless_manager",
+        "elements": list(shared_state.a11y_tree),
+        "phone_state": dict(shared_state.phone_state) if shared_state.phone_state else {},
+        "focused_text": shared_state.focused_text or "",
+        "formatted_device_state": (shared_state.formatted_device_state or "").strip(),
+        "previous_formatted_device_state": (
+            shared_state.previous_formatted_device_state or ""
+        ).strip(),
+        "app_card": (shared_state.app_card or "").strip(),
+        "full_user_message_text": full_user_message_text,
+    }
+
+
+def build_final_ui_snapshot(
+    elements: List[Dict[str, Any]],
+    phone_state: Dict[str, Any],
+    focused_text: str,
+    formatted_text: str,
+) -> Dict[str, Any]:
+    return {
+        "schema_version": 2,
+        "agent": "capture_final",
+        "elements": elements,
+        "phone_state": dict(phone_state) if phone_state else {},
+        "focused_text": focused_text or "",
+        "formatted_device_state": (formatted_text or "").strip(),
+    }

droidrun/agent/droid/__init__.py

@@ -0,0 +1,10 @@
+"""
+Droidrun Agent Module.
+
+This module provides a ReAct agent for automating HarmonyOS devices using reasoning and acting.
+"""
+
+from droidrun.agent.droid.droid_agent import DroidAgent
+from droidrun.agent.droid.state import DroidAgentState
+
+__all__ = ["DroidAgent", "DroidAgentState"]