harmonyrun 0.4.9__py3-none-any.whl

harmonyrun/agent/execution/anti_loop.py

@@ -0,0 +1,410 @@
+"""Anti-loop hint / warning message templates (pure text rendering).
+
+This module holds the **prompt-text** half of the anti-loop subsystem,
+separated from the **detection logic** that lives in
+``base/execution_agent.py``. The detection methods (``_check_stagnation`` /
+``_check_rotation_stuck`` / streak bookkeeping) compute small status dicts;
+the renderers here turn those into the bilingual ``<stagnation_warning>`` /
+``<rotation_unresponsive>`` / ``<off_target_hint>`` blocks spliced into the
+next LLM user message.
+
+Keeping the large en/zh literal blocks here means wording / localization can
+be edited without touching the algorithm file, and the detection logic can be
+unit-tested without snapshot-asserting on prose.
+
+All functions are pure (no ``self``, no device I/O): callers pass the already
+computed values. The thresholds used for phrasing are imported from
+``execution_agent`` to keep a single source of truth.
+"""
+
+from __future__ import annotations
+
+from harmonyrun.agent.execution.failure_classifier import FailureMode
+from harmonyrun.agent.execution.thresholds import (
+    STAGNATION_ABORT_AT,
+    STAGNATION_WARN_AT,
+    TOOL_REPEAT_WARN_AT,
+)
+
+
+def render_stagnation_warning_block(
+    *,
+    streak: int,
+    tool_repeat: int,
+    same_page: int,
+    cause: str,
+    page: str,
+    container_hint: str,
+) -> str:
+    """Render the ``<stagnation_warning>`` block.
+
+    ``container_hint`` is computed by the caller (it needs device-side state)
+    and spliced in verbatim; pass ``""`` when not applicable.
+    """
+    # 三类信号的措辞差异：
+    # - streak / tool_repeat：会触发硬终止，给出剩余步数提醒
+    # - same_page only：软信号，仅提示"页面长时间没跨"，不会自动 abort
+    hard_signal = streak >= STAGNATION_WARN_AT or tool_repeat >= TOOL_REPEAT_WARN_AT
+    if hard_signal:
+        remaining = max(0, STAGNATION_ABORT_AT - streak)
+        suffix = f" (≈ {remaining} step(s) left)." if streak > 0 else "."
+        tail = (
+            "_The framework will auto-abort after "
+            f"{STAGNATION_ABORT_AT} consecutive no-progress steps"
+            f"{suffix}_\n"
+        )
+    else:
+        # same_page-only：不要让 LLM 误以为会硬终止；强调"重新评估前提"
+        tail = (
+            "_This is an advisory: the framework will NOT auto-abort on "
+            "same-page stagnation alone (single-page tasks are valid). "
+            "But if you expected to navigate away, your previous tap "
+            f"likely did not work — currently on `{page or 'unknown'}` "
+            f"for {same_page} step(s)._\n"
+        )
+
+    return (
+        "\n<stagnation_warning>\n"
+        "## ⚠️ Stuck Detector\n"
+        f"You appear to be stuck: {cause}. "
+        "Re-issuing the same action will not help.\n\n"
+        "**Pick ONE of these now:**\n"
+        "1. Try a meaningfully different action — different target "
+        "element, `system_button` back, re-open the app, or scroll to "
+        "expose new UI.\n"
+        "2. Call `complete(success=false, message=\"...\")` with an "
+        "honest assessment of what's blocking you.\n\n"
+        f"{container_hint}"
+        f"{tail}"
+        "</stagnation_warning>\n"
+    )
+
+
+def render_container_tap_hint(*, index: int, tool_repeat: int, bounds: str) -> str:
+    """Render the container-tap hint appended inside ``<stagnation_warning>``.
+
+    Caller resolves ``index`` / ``bounds`` from the a11y tree first; this is
+    pure text assembly.
+    """
+    return (
+        f"**Container-tap hint:** element [{index}] clicked "
+        f"{tool_repeat} times with no UI change. "
+        "It may be a container (Rating control / WebView / section-header "
+        f"Row) and `click({{'index': {index}}})` always lands at its "
+        "center. Switch to absolute coordinates: call "
+        f"`click_at(x, y)` with (x, y) inside bounds=({bounds}) — pick "
+        "a sub-region different from the center (e.g. right edge for a "
+        "5-star Rating, a specific visible icon inside a WebView).\n\n"
+    )
+
+
+def render_rotation_stuck_block(
+    *, consecutive: int, requested: str, current: str, language: str = "en"
+) -> str:
+    """Render the ``<rotation_unresponsive>`` block in en/zh."""
+    if language == "zh":
+        return (
+            "\n<rotation_unresponsive>\n"
+            "## ⚠️ 设备拒绝旋转（前置条件未满足）\n"
+            f"你已经连续 {consecutive} 次调用 `set_rotation` 请求 "
+            f"`{requested}`，但 `<device_state>` 中的 **Orientation** "
+            f"字段（来源：DisplayManagerService）始终是 `{current}`。"
+            "继续重试不会改变结果——设备在当前姿态下不响应运行时旋转。\n\n"
+            "**默认动作（推荐）：** 立刻调用\n"
+            "```\n"
+            "complete(\n"
+            "  success=false,\n"
+            "  message=\"前置条件未满足：测试要求 "
+            f"{requested} 模式，但设备拒绝 set_rotation —— "
+            f"Orientation 仍为 {current}，无法在指定方向下执行视觉检查\",\n"
+            "  screenshot_evidence=[\n"
+            "    \"具体可见证据 1（引用 current screenshot 的内容 / "
+            "坐标 / 颜色 / 可见文本）\",\n"
+            "    \"具体可见证据 2\"\n"
+            "  ]\n"
+            ")\n"
+            "```\n"
+            "理由：测试用例名/标题已指明目标方向（如『横屏』『竖屏』），"
+            "**该方向是测试范围的一部分**；无法进入意味着这次执行不能"
+            "证明 expected_result 在目标方向下成立——不能算 PASS。\n\n"
+            "**例外（仅当你能明确说明当前方向也算"
+            "测试通过条件时才走这条路）：** 在当前 "
+            f"`{current}` 屏下做完整的视觉检查、并在 message 里写明"
+            "「测试声明需要 X 方向但设备只能在 Y 方向下检查，截图未发现遮挡，"
+            "因此**在 Y 方向上**通过」，并 `success=true`。\n\n"
+            "**禁止：** 再发任何 `set_rotation` 或 `wait`。\n"
+            "</rotation_unresponsive>\n"
+        )
+    return (
+        "\n<rotation_unresponsive>\n"
+        "## ⚠️ Device Refused Rotation (precondition unmet)\n"
+        f"You have called `set_rotation` with target `{requested}` "
+        f"{consecutive} time(s) in a row, but the **Orientation** "
+        "field in `<device_state>` (sourced from DisplayManagerService) "
+        f"still reads `{current}`. Retrying will not change that — "
+        "the device does not honor runtime rotation in its current "
+        "posture.\n\n"
+        "**Default action (recommended):** call\n"
+        "```\n"
+        "complete(\n"
+        "  success=false,\n"
+        "  message=\"Precondition unmet: test requires "
+        f"{requested} mode but device refused set_rotation — "
+        f"Orientation stayed at {current}; cannot run the visual "
+        "check in the orientation the test scope specifies\",\n"
+        "  screenshot_evidence=[\n"
+        "    \"<concrete visual anchor 1 — quote visible text / "
+        "coords / colors from current screenshot>\",\n"
+        "    \"<concrete visual anchor 2>\"\n"
+        "  ]\n"
+        ")\n"
+        "```\n"
+        "Reason: the test name/title encodes the required "
+        "orientation (e.g. '横屏'/'竖屏', 'landscape'/'portrait') "
+        "as part of the test scope. If you cannot enter that "
+        "orientation, the run did not exercise the scenario the "
+        "test was designed for — that's a failure, not a PASS.\n\n"
+        "**Exception (only when you can argue the current "
+        "orientation also satisfies the test):** do a full visual "
+        f"sweep on the current `{current}` screen and call "
+        "`complete(success=true, ...)` with a message explicitly "
+        "stating the orientation mismatch and why portrait-mode "
+        "evidence is sufficient.\n\n"
+        "**Forbidden:** any further `set_rotation` or `wait` call.\n"
+        "</rotation_unresponsive>\n"
+    )
+
+
+def render_off_target_hint_block(*, current: str, target: str, streak: int) -> str:
+    """Render the ``<off_target_hint>`` block."""
+    return (
+        "\n<off_target_hint>\n"
+        "## 🧭 Off-Target App Detector\n"
+        f"You are currently in `{current}` (target app is `{target}`) "
+        f"for {streak} step(s).\n\n"
+        "If this is an expected handoff (browser deep-link confirmation, "
+        "system settings, share sheet, OAuth) — continue.\n"
+        f"Otherwise call `open_app(\"{target}\")` to return to the "
+        "target app before doing anything else.\n"
+        "</off_target_hint>\n"
+    )
+
+
+def render_off_target_relaunch_notice(*, target: str, language: str = "en") -> str:
+    """Render the notice injected after the harness FORCED a relaunch of the
+    target app (Tier-2). Tells the model the screen it now sees is the freshly
+    relaunched target, not its previous off-target frame."""
+    if language == "zh":
+        return (
+            "\n<harness_intervention>\n"
+            "## 🛠️ 已自动拉回目标 app\n"
+            f"你之前偏离了目标 app，harness 已强制重新启动 `{target}`。"
+            "当前 `<device_state>` / 截图反映的是**重启后的目标 app**，"
+            "请据此重新定位，不要再依据之前那一帧操作。\n"
+            "</harness_intervention>\n"
+        )
+    return (
+        "\n<harness_intervention>\n"
+        "## 🛠️ Auto-returned to target app\n"
+        f"You had drifted off-target; the harness force-relaunched `{target}`. "
+        "The current `<device_state>` / screenshot reflect the **relaunched "
+        "target app** — re-orient from this frame, not your previous one.\n"
+        "</harness_intervention>\n"
+    )
+
+
+def render_stagnation_abort_reason(*, streak: int, tool_repeat: int) -> str:
+    """Build the failure reason for a hard-abort end/finalize event."""
+    if streak >= STAGNATION_ABORT_AT:
+        return (
+            f"Aborted: device UI unchanged for {streak} "
+            "consecutive steps — the agent is stuck in a loop with no "
+            "UI progress."
+        )
+    return (
+        f"Aborted: the LLM repeated the same tool call "
+        f"{tool_repeat} times consecutively while the "
+        f"UI was also unchanged for {streak} step(s) "
+        "— truly stuck (not a legitimate repeat like scrolling a list "
+        "or incrementing a counter)."
+    )
+
+
+# ===========================================================================
+# P0-1 classified failure-mode renderers
+#
+# Each mode owns one Tier-1 HINT renderer (budget-aware, bilingual) and one
+# Tier-3 CONCLUDE reason. ``render_failure_hint`` / ``render_failure_conclusion``
+# are the dispatch facades the agents call — keyed by ``FailureMode`` so adding
+# a mode = add a renderer + register it in the dispatch dicts below (open/closed,
+# matching the classifier's detector/policy registries).
+# ===========================================================================
+
+
+def render_obstruction_hint(
+    *, extra: dict, attempt: int, budget: int, container_hint: str, language: str
+) -> str:
+    modal = extra.get("modal_kind", "overlay")
+    if language == "zh":
+        return (
+            "\n<obstruction>\n"
+            "## ⚠️ 遮挡检测\n"
+            f"当前有 `{modal}` 浮层挡住目标，你上一步动作没有产生变化"
+            f"（已是第 {attempt}/{budget} 次卡在它上面）。\n\n"
+            "**先关掉它再继续**：点浮层外部 / 关闭图标 / `system_button(\"back\")`，"
+            "成功后再重试原动作。预算耗尽会判定 **Persistent Obstruction**。\n"
+            "</obstruction>\n"
+        )
+    return (
+        "\n<obstruction>\n"
+        "## ⚠️ Obstruction Detector\n"
+        f"A `{modal}` overlay is blocking the target and your last action "
+        f"produced no change (attempt {attempt}/{budget} stuck behind it).\n\n"
+        "**Dismiss it first**: tap outside / its close icon / "
+        "`system_button(\"back\")`, then retry the original action. "
+        "Exhausting the budget concludes **Persistent Obstruction**.\n"
+        "</obstruction>\n"
+    )
+
+
+def render_unresponsive_element_hint(
+    *, extra: dict, attempt: int, budget: int, container_hint: str, language: str
+) -> str:
+    if language == "zh":
+        return (
+            "\n<unresponsive_element>\n"
+            "## ⚠️ 元素无响应\n"
+            f"你反复点同一个元素但屏幕零变化（第 {attempt}/{budget} 次）。\n\n"
+            f"{container_hint}"
+            "**换招**：换一个目标元素、用坐标点子区域、或换导航路径；"
+            f"再无效将判定 **Unresponsive Element Bug**。\n"
+            "</unresponsive_element>\n"
+        )
+    return (
+        "\n<unresponsive_element>\n"
+        "## ⚠️ Unresponsive Element\n"
+        f"You tapped the same element repeatedly with zero screen change "
+        f"(attempt {attempt}/{budget}).\n\n"
+        f"{container_hint}"
+        "**Switch tactics**: a different target element, a coordinate tap on "
+        "a sub-region, or a different navigation path. Another no-op concludes "
+        "**Unresponsive Element Bug**.\n"
+        "</unresponsive_element>\n"
+    )
+
+
+def render_navigation_cycle_hint(
+    *, extra: dict, attempt: int, budget: int, container_hint: str, language: str
+) -> str:
+    page_a = extra.get("page_a", "A")
+    page_b = extra.get("page_b", "B")
+    # One side is the launcher / multitask shell → the bounce is almost always a
+    # gesture hijack (an edge swipe captured by system navigation), which the
+    # model is actively trying to recover from. Coach the reliable recovery
+    # instead of a generic "find another route".
+    if extra.get("system_surface") == "true":
+        if language == "zh":
+            return (
+                "\n<navigation_cycle>\n"
+                "## ⚠️ 手势被系统截获\n"
+                f"你在 app 与系统桌面/多任务之间来回（`{page_a}` ↔ `{page_b}`，"
+                f"第 {attempt}/{budget} 次）。你的边缘滑动很可能被系统手势导航吃掉了，"
+                "并没有在 app 内返回。\n\n"
+                "**改用可靠返回**：`system_button(\"back\")` 一定能在 app 内返回上一页；"
+                "或点页面上的返回/关闭按钮。别再重复同一条边缘滑动。\n"
+                "</navigation_cycle>\n"
+            )
+        return (
+            "\n<navigation_cycle>\n"
+            "## ⚠️ Gesture Captured by System\n"
+            f"You are bouncing between the app and the system launcher/multitask "
+            f"view (`{page_a}` ↔ `{page_b}`, attempt {attempt}/{budget}). Your "
+            "edge swipe was likely grabbed by system gesture navigation and did "
+            "not go back inside the app.\n\n"
+            "**Use a reliable back**: `system_button(\"back\")` always navigates "
+            "back inside the app; or tap the on-screen back/close button. Stop "
+            "repeating the same edge swipe.\n"
+            "</navigation_cycle>\n"
+        )
+    if language == "zh":
+        return (
+            "\n<navigation_cycle>\n"
+            "## ⚠️ 页面来回跳\n"
+            f"你在两个页面之间来回（`{page_a}` ↔ `{page_b}`，第 {attempt}/{budget} 次）。"
+            "重复同一路径不会前进。\n\n"
+            "**换一条路**：换不同的入口/元素、用搜索、或滚动暴露新 UI；"
+            "继续循环将判定 **Navigation Cycle**。\n"
+            "</navigation_cycle>\n"
+        )
+    return (
+        "\n<navigation_cycle>\n"
+        "## ⚠️ Navigation Cycle\n"
+        f"You are bouncing between two pages (`{page_a}` ↔ `{page_b}`, "
+        f"attempt {attempt}/{budget}). Repeating the same path will not "
+        "progress.\n\n"
+        "**Take a different route**: a different entry/element, search, or "
+        "scroll to expose new UI. Continuing the loop concludes "
+        "**Navigation Cycle**.\n"
+        "</navigation_cycle>\n"
+    )
+
+
+# mode → Tier-1 HINT renderer
+_HINT_RENDERERS = {
+    FailureMode.OBSTRUCTION: render_obstruction_hint,
+    FailureMode.UNRESPONSIVE_ELEMENT: render_unresponsive_element_hint,
+    FailureMode.NAVIGATION_CYCLE: render_navigation_cycle_hint,
+}
+
+
+def render_failure_hint(
+    *,
+    mode: FailureMode,
+    extra: dict,
+    attempt: int,
+    budget: int,
+    container_hint: str = "",
+    language: str = "en",
+) -> str:
+    """Dispatch to the mode's Tier-1 HINT block. Empty string for unmapped
+    modes (the caller then falls back to the generic stagnation block)."""
+    renderer = _HINT_RENDERERS.get(mode)
+    if renderer is None:
+        return ""
+    return renderer(
+        extra=extra,
+        attempt=attempt,
+        budget=budget,
+        container_hint=container_hint,
+        language=language,
+    )
+
+
+# mode → human-readable typed conclusion noun phrase (for the CONCLUDE reason)
+_CONCLUSION_DETAIL = {
+    FailureMode.OBSTRUCTION: (
+        "a blocking overlay (`{ref}`) kept obstructing the target after the "
+        "dismissal budget was spent"
+    ),
+    FailureMode.UNRESPONSIVE_ELEMENT: (
+        "element `{ref}` produced zero observable change across every attempt "
+        "— the control is unresponsive"
+    ),
+    FailureMode.NAVIGATION_CYCLE: (
+        "the agent kept bouncing between pages (`{ref}`) without progressing"
+    ),
+}
+
+
+def render_failure_conclusion(
+    *, label: str, mode: FailureMode, target_ref: str, severity: str
+) -> str:
+    """Build the structured typed reason for a Tier-3 CONCLUDE abort.
+
+    ``label`` is the policy's conclusion noun (e.g. "Unresponsive Element Bug");
+    the detail clause is mode-specific. Fed verbatim into the FastAgentEndEvent
+    reason so the trace / evals get a machine-readable failure class.
+    """
+    detail = _CONCLUSION_DETAIL.get(mode, "the failure budget was exhausted")
+    detail = detail.format(ref=target_ref or "?")
+    return f"Aborted [{label}, severity={severity}]: {detail}."