screenforge 0.10.0__tar.gz → 0.11.0__tar.gz

{screenforge-0.10.0 → screenforge-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenforge
-Version: 0.10.0
+Version: 0.11.0
 Summary: AI-driven cross-platform UI automation engine with test script generation
 License: MIT
 Project-URL: Homepage, https://github.com/jhinzzz/ScreenForge

screenforge-0.11.0/cli/_version.py

@@ -0,0 +1 @@
+__version__ = "0.11.0"

{screenforge-0.10.0 → screenforge-0.11.0}/cli/modes/default.py

@@ -58,6 +58,7 @@ def run_default_mode(
         step_count = 0
         last_error = ""
         consecutive_failures = 0
+        consecutive_not_found = 0
         last_ui_json = ""
 
         while step_count < args.max_steps:
@@ -177,11 +178,27 @@ def run_default_mode(
                         success=False,
                         action_description="not_found",
                     )
+                    # not_found is exempt from the failure circuit breaker so vision
+                    # gets a chance, but a model stuck returning it makes no progress
+                    # and burns one LLM call per step up to max_steps (token bleed).
+                    # Cap consecutive not_found at the same threshold and stop.
+                    consecutive_not_found += 1
+                    if consecutive_not_found >= args.max_retries:
+                        final_error = (
+                            f"Stopped after {consecutive_not_found} consecutive 'not_found' — "
+                            f"target never appeared in the UI tree."
+                        )
+                        log.error(
+                            f"[E025] {consecutive_not_found} consecutive 'not_found'. "
+                            f"Fix: re-run with --vision, or refine --goal / scroll the target into view."
+                        )
+                        return 1
                     continue
                 else:
                     result = executor.execute_and_record(action_data)
                     if result.get("success"):
                         consecutive_failures = 0
+                        consecutive_not_found = 0
                         history_manager.add_step(
                             result["code_lines"], result["action_description"]
                         )

{screenforge-0.10.0 → screenforge-0.11.0}/cli/session.py

@@ -108,6 +108,30 @@ def start_session_recording(session_id: str, platform: str, udid: str = "") -> s
     return video_path
 
 
+def _reap_with_timeout(pid: int, timeout: float) -> None:
+    """Wait for a signalled recording process to exit, then SIGKILL if it won't.
+
+    Bare os.waitpid(pid, 0) blocks forever — if `xcrun simctl recordVideo` ever
+    ignores SIGINT, --session-end would hang the whole CLI. Poll with WNOHANG up
+    to `timeout`, then SIGKILL and reap so we never block indefinitely.
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            reaped, _ = os.waitpid(pid, os.WNOHANG)
+        except ChildProcessError:
+            return  # already reaped elsewhere
+        if reaped:
+            return
+        time.sleep(0.1)
+    # Still alive after the grace period — kill hard and reap the zombie.
+    try:
+        os.kill(pid, signal.SIGKILL)
+        os.waitpid(pid, 0)
+    except OSError:
+        pass
+
+
 def stop_session_recording(session_id: str) -> str:
     session = load_session(session_id)
     if not session:
@@ -120,7 +144,7 @@ def stop_session_recording(session_id: str) -> str:
     try:
         pgid = os.getpgid(pid)
         os.killpg(pgid, signal.SIGINT)
-        os.waitpid(pid, 0)
+        _reap_with_timeout(pid, timeout=10.0)
     except OSError:
         try:
             os.kill(pid, signal.SIGINT)

{screenforge-0.10.0 → screenforge-0.11.0}/common/ai.py

@@ -1,4 +1,5 @@
 import json
+import re
 import time
 
 from openai import OpenAI
@@ -18,6 +19,39 @@ def _strip_json_fences(text: str) -> str:
     return text
 
 
+# Endpoints (base_url) that 400'd on response_format — never retried with it.
+# response_format={"type":"json_object"} cuts malformed responses (fewer retries,
+# fewer tokens), but is NOT universal across OpenAI-compatible endpoints, which
+# this tool promises to support. So: try once per endpoint, remember a rejection,
+# and fall back to a plain call forever after. Prompts already say "output JSON".
+_JSON_MODE_UNSUPPORTED: set = set()
+
+
+def chat_completion_json(client, **kwargs):
+    """chat.completions.create that requests JSON mode when the endpoint allows.
+
+    Detect-once per endpoint: on the first 400-style rejection of response_format
+    we record the base_url and never send it again, so an endpoint without JSON
+    mode pays one failed call total, not one per request.
+    """
+    endpoint = str(getattr(client, "base_url", ""))
+    if endpoint not in _JSON_MODE_UNSUPPORTED:
+        try:
+            return client.chat.completions.create(
+                response_format={"type": "json_object"}, **kwargs
+            )
+        except Exception as e:
+            # Only json-mode-shaped rejections fall back; real network/auth errors
+            # must surface to the caller's existing try/except unchanged.
+            msg = str(e).lower()
+            if "response_format" in msg or "json" in msg or "not support" in msg:
+                log.warning(f"[AI] Endpoint rejected JSON mode, falling back for {endpoint}")
+                _JSON_MODE_UNSUPPORTED.add(endpoint)
+            else:
+                raise
+    return client.chat.completions.create(**kwargs)
+
+
 class AIBrain:
     def __init__(self):
         # 实例化文本专属客户端
@@ -39,20 +73,48 @@ class AIBrain:
 
     def _verify_locator_in_ui(self, decision: dict, ui_dict: dict) -> bool:
         """
-        校验缓存中推荐的动作，其元素是否真实存在于当前的 UI 树中
+        校验缓存中推荐的动作，其元素是否真实存在于当前的 UI 树中。
+
+        L2 是跨页面的全局语义缓存，一条决策可能命中一个并不存在该元素的页面。
+        本方法是那道安全网：能确认元素不存在时返回 False 丢弃该命中；无法确认
+        （元素无该属性、选择器无法解析）时放行，绝不误伤有效缓存。
         """
         loc_type = decision.get("locator_type")
         loc_val = decision.get("locator_value")
 
-        # 如果动作不需要特定元素 (比如 answer 或某些全局操作)，直接放行
-        if (
-            not loc_type
-            or not loc_val
-            or loc_type not in ["text", "description", "resourceId", "id"]
-        ):
+        # 无定位需求 (swipe / press 等全局动作) 直接放行
+        if not loc_type or not loc_val:
             return True
 
         elements = ui_dict.get("ui_elements", [])
+
+        # css 是 Web 端最常用的定位器 (Prompt 铁律排第一)，且 L2 是跨页面全局缓存，
+        # 因此必须校验而非放行。压缩后的 Web 树只能确认执行器自己产出的两种形态:
+        # `#id` -> 元素 id，`[name="x"]` -> 元素 name (见 executor.LocatorBuilder)。
+        # 其它选择器 (class/标签/后代) 树里无法还原，判为无法确认 -> 放行。
+        if loc_type == "css":
+            # Only a SIMPLE selector round-trips to a tree attribute. The charset
+            # excludes CSS combinators/escapes (space > + ~ , . [ : \) on purpose:
+            # `#form input` and `#user\.email` are compound or escaped, so the raw
+            # string never equals an `id` value — comparing anyway would discard a
+            # VALID L2 hit and force a fresh paid LLM call, inverting this method's
+            # purpose. Unverifiable → pass through.
+            simple = r"[^\s>+~,.\[\]:\\#]+"
+            m = re.fullmatch(rf"#({simple})", loc_val) or re.fullmatch(
+                rf'\[name="({simple})"\]', loc_val
+            )
+            if not m:
+                return True
+            attr = "id" if loc_val.startswith("#") else "name"
+            target = m.group(1)
+            values = [el.get(attr) for el in elements if el.get(attr)]
+            if not values:  # 树里没有任何该属性 -> 无从确认 -> 放行
+                return True
+            return target in values
+
+        if loc_type not in ["text", "description", "resourceId", "id"]:
+            return True
+
         for el in elements:
             if loc_type == "text" and el.get("text") == loc_val:
                 return True
@@ -263,7 +325,8 @@ class AIBrain:
         result_text = ""
         try:
             with ai_status(f"Thinking ({model_name})..."):
-                response = client.chat.completions.create(
+                response = chat_completion_json(
+                    client,
                     model=model_name,
                     messages=[
                         {"role": "system", "content": system_prompt},

{screenforge-0.10.0 → screenforge-0.11.0}/common/ai_autonomous.py

@@ -1,7 +1,7 @@
 import json
 
 import config.config as config
-from common.ai import AIBrain, _strip_json_fences
+from common.ai import AIBrain, _strip_json_fences, chat_completion_json
 from common.logs import log
 from common.progress import ai_status
 
@@ -80,7 +80,8 @@ class AutonomousBrain(AIBrain):
         result_text = ""
         try:
             with ai_status("Planning execution steps..."):
-                response = active_client.chat.completions.create(
+                response = chat_completion_json(
+                    active_client,
                     model=active_model,
                     messages=[
                         {"role": "system", "content": system_prompt},
@@ -225,7 +226,8 @@ class AutonomousBrain(AIBrain):
         result_text = ""
         try:
             with ai_status("Reasoning about next action..."):
-                response = active_client.chat.completions.create(
+                response = chat_completion_json(
+                    active_client,
                     model=active_model,
                     messages=[
                         {"role": "system", "content": system_prompt},

screenforge-0.11.0/common/cache/cache_hash.py

@@ -0,0 +1,88 @@
+import hashlib
+import json
+import re
+from typing import Any, Dict
+
+_BLOCKLIST = frozenset(
+    [
+        "加密货币",
+        "比特币",
+        "meme币",
+        "美股代币",
+        "贵金属代币",
+        "热门资产",
+        "已上线",
+        "已上架",
+        "上架",
+        "下架",
+        "公告",
+        "活动",
+    ]
+)
+
+
+def _latin_anchor(raw_text: str) -> str:
+    """A Latin/non-CJK anchor from an element's text, or '' if not anchor-like.
+
+    Mirrors the CJK path's dynamic-data immunity: digits and symbols are
+    stripped so a changing price/balance/count doesn't move the skeleton hash
+    ("Balance 100" and "Balance 9999" both reduce to "balance"). Whitespace is
+    collapsed and case is folded so render noise doesn't fork the fingerprint.
+
+    ponytail: 2..24 chars keeps button/nav labels ("login", "delete account")
+    and drops long description sentences — the Latin analogue of the CJK 2..6
+    window. Raise the ceiling only if a real multi-word control exceeds it.
+    """
+    letters_only = re.sub(r"[^a-zA-Z\s]", "", raw_text)
+    normalized = " ".join(letters_only.split()).lower()
+    return normalized if 2 <= len(normalized) <= 24 else ""
+
+
+def _extract_semantic_fingerprint(ui_json: Dict[str, Any]) -> list:
+    """
+    提取页面锚点指纹，免疫动态数据和渲染顺序波动。
+    """
+    fingerprint_features = set()
+    elements = ui_json.get("ui_elements", [])
+
+    for el in elements:
+        raw_text = el.get("text", "") or el.get("desc", "")
+        # 抹除所有数字、字母、符号，只保留纯汉字
+        cn_text = re.sub(r"[^\u4e00-\u9fa5]", "", raw_text)
+
+        # 标准的 UI 导航或按钮，通常在 2 到 6 个汉字之间
+        if 2 <= len(cn_text) <= 6 and cn_text not in _BLOCKLIST:
+            fingerprint_features.add(f"{el.get('class')}|{cn_text}")
+
+    # Non-CJK pages (English etc.) carry NO Chinese anchors, so the loop above
+    # yields nothing and every such page collapsed to one constant hash — L1's
+    # exact key then replayed an action recorded on a DIFFERENT page. Fall back
+    # to Latin anchors so those pages get distinct identities too. Page-level,
+    # not per-element: a page WITH usable CJK anchors keeps exactly its old
+    # fingerprint (Chinese behavior frozen); only a fully-anchorless page falls
+    # through here.
+    if not fingerprint_features:
+        for el in elements:
+            anchor = _latin_anchor(el.get("text", "") or el.get("desc", ""))
+            if anchor:
+                fingerprint_features.add(f"{el.get('class')}|{anchor}")
+
+    # 强制排序并转为列表，保证哈希的绝对一致性
+    return sorted(list(fingerprint_features))
+
+
+def compute_ui_hash(ui_json: Dict[str, Any]) -> str:
+    """计算用于混合缓存匹配的页面骨架 Hash"""
+    fingerprint = _extract_semantic_fingerprint(ui_json)
+    fingerprint_str = json.dumps(fingerprint)
+    hash_obj = hashlib.sha256()
+    hash_obj.update(fingerprint_str.encode("utf-8"))
+    return hash_obj.hexdigest()
+
+
+def compute_instruction_hash(instruction: str) -> str:
+    """计算用于混合缓存 O(1) 精确匹配的指令 Hash"""
+    normalized_inst = re.sub(r"\s+", " ", instruction).strip().lower()
+    hash_obj = hashlib.sha256()
+    hash_obj.update(normalized_inst.encode("utf-8"))
+    return hash_obj.hexdigest()

{screenforge-0.10.0 → screenforge-0.11.0}/common/cache/cache_manager.py

@@ -1,3 +1,4 @@
+import json
 import os
 
 os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
@@ -30,6 +31,7 @@ class CacheManager:
         self._cache_dir = cache_dir
         self._enabled = enabled
         self._ttl_seconds = ttl_days * 24 * 60 * 60
+        self._max_size_bytes = max_size_mb * 1024 * 1024
         self._stats = CacheStats(cache_dir)
         self._model_loader = EmbeddingModelLoader()
 
@@ -178,6 +180,10 @@ class CacheManager:
             return False
         try:
             cache_data = load_cache(self._cache_dir)
+            # Prune expired entries here: the write path reloads and re-saves the
+            # whole file, so without this it re-persists dead entries forever. The
+            # read path only saves on a hit, so misses can't be relied on to prune.
+            cache_data = cleanup_expired_entries(cache_data, self._ttl_seconds)
             entries = cache_data.setdefault("entries", {})
             current_vector = self._get_embedding(instruction)
             keys_to_delete = []
@@ -219,12 +225,45 @@ class CacheManager:
             if ui_hash is not None:
                 entry["ui_hash"] = ui_hash
             entries[exact_key] = entry
+            self._evict_to_fit(cache_data, exact_key)
             save_cache(self._cache_dir, cache_data)
             return True
         except Exception as e:
             log.error(f"[Cache Error] Write failed: {e}")
             return False
 
+    def _evict_to_fit(self, cache_data: Dict, keep_key: str) -> None:
+        """Evict least-recently-accessed entries until the cache fits max_size_bytes.
+
+        TTL bounds age; this bounds size within the TTL window. The just-written
+        key is never evicted (a single entry larger than the cap still persists —
+        the cap is a soft ceiling, not a hard reject of the current write).
+        """
+        entries = cache_data.get("entries", {})
+
+        # ponytail: re-serializes on each eviction (O(n²) worst case). Fine —
+        # TTL already bounds entry count and eviction is rare; switch to a running
+        # byte tally if a cache ever evicts hundreds of entries in one write.
+        def size() -> int:
+            return len(json.dumps(cache_data, ensure_ascii=False).encode("utf-8"))
+
+        if size() <= self._max_size_bytes:
+            return
+        # Oldest access first; the current write is pinned last so it survives.
+        ordered = sorted(
+            entries.keys(),
+            key=lambda k: (
+                k == keep_key,
+                entries[k].get("metadata", {}).get("last_accessed", ""),
+            ),
+        )
+        for k in ordered:
+            if k == keep_key or len(entries) <= 1:
+                break
+            del entries[k]
+            if size() <= self._max_size_bytes:
+                break
+
     def get(self, instruction: str, ui_json: Dict[str, Any], platform: str) -> Optional[Dict[str, Any]]:
         try:
             ui_hash = compute_ui_hash(ui_json)

{screenforge-0.10.0 → screenforge-0.11.0}/config/config.py

@@ -51,12 +51,17 @@ DEFAULT_TIMEOUT = float(os.getenv("DEFAULT_TIMEOUT", 30.0))
 # ==========================================
 # 用户填入各环境/平台的 App 包名或 URL 后，launch_app 会自动拉起；默认留空=不自动启动。
 # 这是文档化的用户旋钮（见 docs/capability-matrix.md），不是死代码。
+# Auto-launch target per (env, platform). Env-driven so a pip-installed user can
+# set an Android package / iOS bundle / web start-URL without editing the source.
+# Empty (the default) means "don't auto-launch" — correct for web (the brain
+# issues goto) and for driving an already-open mobile app. Env vars follow the
+# pattern APP_TARGET_<ENV>_<PLATFORM>, e.g. APP_TARGET_DEV_ANDROID=com.foo.bar.
 APP_ENV_CONFIG = {
-    "dev": {
-        "android": "",
-        "ios": "",
-        "web": "",
-    },
+    env: {
+        platform: os.getenv(f"APP_TARGET_{env.upper()}_{platform.upper()}", "")
+        for platform in ("android", "ios", "web")
+    }
+    for env in ("dev", "prod", "us_dev", "us_prod")
 }
 
 # ==========================================

{screenforge-0.10.0 → screenforge-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "screenforge"
-version = "0.10.0"
+version = "0.11.0"
 description = "AI-driven cross-platform UI automation engine with test script generation"
 readme = "README.md"
 requires-python = ">=3.11"

{screenforge-0.10.0 → screenforge-0.11.0}/screenforge.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenforge
-Version: 0.10.0
+Version: 0.11.0
 Summary: AI-driven cross-platform UI automation engine with test script generation
 License: MIT
 Project-URL: Homepage, https://github.com/jhinzzz/ScreenForge

{screenforge-0.10.0 → screenforge-0.11.0}/screenforge.egg-info/SOURCES.txt

@@ -73,6 +73,7 @@ tests/test_capabilities.py
 tests/test_case_memory_identity.py
 tests/test_cli_action_json.py
 tests/test_codegen_quality.py
+tests/test_config_app_target.py
 tests/test_dispatch.py
 tests/test_doctor_orphan_browser.py
 tests/test_dom_capture.py
@@ -113,6 +114,7 @@ tests/test_run_reporter.py
 tests/test_run_resume.py
 tests/test_runtime_modes.py
 tests/test_screenshot_annotator.py
+tests/test_session_reap.py
 tests/test_shared_observation_stash.py
 tests/test_shorthand.py
 tests/test_tool_protocol_diagnosis.py

screenforge-0.11.0/tests/test_ai_brain.py

@@ -0,0 +1,210 @@
+"""Tests for common/ai.py — AIBrain action decision and cache interaction."""
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+@pytest.fixture
+def mock_config(monkeypatch):
+    monkeypatch.setattr("config.config.OPENAI_API_KEY", "test-key")
+    monkeypatch.setattr("config.config.OPENAI_BASE_URL", "http://localhost")
+    monkeypatch.setattr("config.config.VISION_API_KEY", "test-key")
+    monkeypatch.setattr("config.config.VISION_BASE_URL", "http://localhost")
+    monkeypatch.setattr("config.config.VISION_MODEL_NAME", "gpt-4o")
+    monkeypatch.setattr("config.config.MODEL_NAME", "gpt-4o")
+    monkeypatch.setattr("config.config.CACHE_DIR", "/tmp/test_cache")
+    monkeypatch.setattr("config.config.CACHE_ENABLED", False)
+    monkeypatch.setattr("config.config.CACHE_TTL_DAYS", 1)
+    monkeypatch.setattr("config.config.CACHE_MAX_SIZE_MB", 10)
+
+
+@pytest.fixture
+def brain(mock_config):
+    with patch("common.ai.OpenAI") as mock_openai_cls:
+        mock_openai_cls.side_effect = [MagicMock(), MagicMock()]
+        from common.ai import AIBrain
+        return AIBrain()
+
+
+class TestVerifyLocatorInUi:
+    def test_no_locator_type_passes(self, brain):
+        decision = {"action": "swipe", "locator_type": "", "locator_value": ""}
+        assert brain._verify_locator_in_ui(decision, {"ui_elements": []}) is True
+
+    def test_text_locator_found(self, brain):
+        decision = {"locator_type": "text", "locator_value": "Login"}
+        ui = {"ui_elements": [{"text": "Login", "id": ""}]}
+        assert brain._verify_locator_in_ui(decision, ui) is True
+
+    def test_text_locator_not_found(self, brain):
+        decision = {"locator_type": "text", "locator_value": "Login"}
+        ui = {"ui_elements": [{"text": "Register", "id": ""}]}
+        assert brain._verify_locator_in_ui(decision, ui) is False
+
+    def test_id_locator_found(self, brain):
+        decision = {"locator_type": "resourceId", "locator_value": "btn_submit"}
+        ui = {"ui_elements": [{"text": "", "id": "btn_submit"}]}
+        assert brain._verify_locator_in_ui(decision, ui) is True
+
+    def test_description_locator_found(self, brain):
+        decision = {"locator_type": "description", "locator_value": "Close dialog"}
+        ui = {"ui_elements": [{"desc": "Close dialog", "text": ""}]}
+        assert brain._verify_locator_in_ui(decision, ui) is True
+
+    def test_css_locator_passthrough(self, brain):
+        # Empty tree → nothing to verify against → pass through (don't discard).
+        decision = {"locator_type": "css", "locator_value": "#btn"}
+        ui = {"ui_elements": []}
+        assert brain._verify_locator_in_ui(decision, ui) is True
+
+    def test_css_id_present_is_accepted(self, brain):
+        decision = {"locator_type": "css", "locator_value": "#username"}
+        ui = {"ui_elements": [{"id": "username", "class": "input"}]}
+        assert brain._verify_locator_in_ui(decision, ui) is True
+
+    def test_css_id_absent_on_a_page_that_has_ids_is_rejected(self, brain):
+        # P1: L2 is a GLOBAL cross-page cache. A `#username` decision learned on
+        # page A must NOT replay on page B where ids exist but none match — the
+        # old allowlist waved ALL css through, so this returned True (wrong).
+        decision = {"locator_type": "css", "locator_value": "#username"}
+        ui = {"ui_elements": [{"id": "search", "class": "input"}]}
+        assert brain._verify_locator_in_ui(decision, ui) is False
+
+    def test_css_id_passes_through_when_tree_carries_no_ids(self, brain):
+        # Can't confirm presence or absence → pass through, never false-reject.
+        decision = {"locator_type": "css", "locator_value": "#username"}
+        ui = {"ui_elements": [{"text": "Login", "class": "button"}]}
+        assert brain._verify_locator_in_ui(decision, ui) is True
+
+    def test_css_name_attribute_verified(self, brain):
+        present = {"locator_type": "css", "locator_value": '[name="email"]'}
+        absent = {"locator_type": "css", "locator_value": '[name="email"]'}
+        ui = {"ui_elements": [{"name": "email", "class": "input"}]}
+        other = {"ui_elements": [{"name": "phone", "class": "input"}]}
+        assert brain._verify_locator_in_ui(present, ui) is True
+        assert brain._verify_locator_in_ui(absent, other) is False
+
+    def test_css_complex_selector_passes_through(self, brain):
+        # A selector the compressed tree can't resolve (class/tag/descendant)
+        # is unverifiable → pass through rather than discard a valid hit.
+        decision = {"locator_type": "css", "locator_value": "div.card > button.primary"}
+        ui = {"ui_elements": [{"id": "search", "class": "button"}]}
+        assert brain._verify_locator_in_ui(decision, ui) is True
+
+    @pytest.mark.parametrize(
+        "selector",
+        [
+            "#login-form input",            # descendant
+            "#login-form > .btn",           # child combinator
+            "#username.form-control",       # id + class compound
+            '#login-form input[name="u"]',  # descendant + attribute
+            "#a, #b",                       # selector list
+        ],
+    )
+    def test_css_compound_selector_starting_with_id_passes_through(self, brain, selector):
+        # A compound selector only STARTS with #id — the rest narrows to a
+        # descendant/class. Comparing the whole string against `id` values always
+        # fails, which DISCARDS a valid L2 hit and forces a fresh paid LLM call —
+        # the opposite of why this verification exists. Unverifiable → pass through.
+        ui = {"ui_elements": [{"id": "login-form", "class": "form"}]}
+        assert brain._verify_locator_in_ui({"locator_type": "css", "locator_value": selector}, ui) is True
+
+    @pytest.mark.parametrize(
+        ("raw_id", "selector"),
+        [
+            ("user.email", r"#user\.email"),    # Angular/JSF-style dotted id
+            ("form:submit", r"#form\:submit"),  # JSF colon id
+            ("2fa_code", "#\\32 fa_code"),      # leading digit, CSS.escape form
+        ],
+    )
+    def test_css_escaped_id_selector_is_not_false_rejected(self, brain, raw_id, selector):
+        # executor._escape_css_ident backslash-escapes special chars, so the
+        # selector text never equals the raw `id` in the tree. A literal compare
+        # rejects a locator whose element is RIGHT THERE. Must not return False.
+        ui = {"ui_elements": [{"id": raw_id, "class": "input"}]}
+        assert brain._verify_locator_in_ui({"locator_type": "css", "locator_value": selector}, ui) is True
+
+    def test_css_escaped_name_selector_is_not_false_rejected(self, brain):
+        # Same for [name="..."]: a quote in the name is escaped when built.
+        ui = {"ui_elements": [{"name": 'we"ird', "class": "input"}]}
+        decision = {"locator_type": "css", "locator_value": '[name="we\\"ird"]'}
+        assert brain._verify_locator_in_ui(decision, ui) is True
+
+    def test_css_plain_id_rejection_still_works(self, brain):
+        # The safety net must stay armed for the simple case it was built for.
+        ui = {"ui_elements": [{"id": "search", "class": "input"}]}
+        decision = {"locator_type": "css", "locator_value": "#username"}
+        assert brain._verify_locator_in_ui(decision, ui) is False
+
+
+class TestGetAction:
+    def _make_llm_response(self, content: str):
+        response = MagicMock()
+        response.choices = [MagicMock()]
+        response.choices[0].message.content = content
+        return response
+
+    def test_returns_parsed_result(self, brain):
+        result_json = json.dumps({"result": {"action": "click", "locator_type": "text", "locator_value": "Login"}})
+        brain.text_client.chat.completions.create.return_value = self._make_llm_response(result_json)
+
+        result = brain.get_action("click login button", '{"ui_elements": []}', "web", skip_cache=True)
+        assert result["action"] == "click"
+        assert result["locator_value"] == "Login"
+
+    def test_handles_markdown_wrapped_json(self, brain):
+        content = '```json\n{"result": {"action": "input", "locator_type": "css", "locator_value": "#email"}}\n```'
+        brain.text_client.chat.completions.create.return_value = self._make_llm_response(content)
+
+        result = brain.get_action("type in email", '{"ui_elements": []}', "web", skip_cache=True)
+        assert result["action"] == "input"
+
+    def test_returns_empty_on_parse_failure(self, brain):
+        brain.text_client.chat.completions.create.return_value = self._make_llm_response("not json at all")
+
+        result = brain.get_action("do something", '{"ui_elements": []}', "web", skip_cache=True)
+        assert result == {}
+
+    def test_returns_empty_on_api_error(self, brain):
+        brain.text_client.chat.completions.create.side_effect = Exception("connection timeout")
+
+        result = brain.get_action("do something", '{"ui_elements": []}', "web", skip_cache=True)
+        assert result == {}
+
+    def test_requests_json_mode_when_supported(self, brain):
+        result_json = json.dumps({"result": {"action": "click", "locator_type": "text", "locator_value": "Login"}})
+        brain.text_client.chat.completions.create.return_value = self._make_llm_response(result_json)
+
+        brain.get_action("click login", '{"ui_elements": []}', "web", skip_cache=True)
+        _, kwargs = brain.text_client.chat.completions.create.call_args
+        assert kwargs.get("response_format") == {"type": "json_object"}
+
+    def test_falls_back_when_endpoint_rejects_json_mode(self, brain):
+        import common.ai as ai_mod
+        ai_mod._JSON_MODE_UNSUPPORTED.clear()
+        result_json = json.dumps({"result": {"action": "click", "locator_type": "text", "locator_value": "Go"}})
+        good = self._make_llm_response(result_json)
+
+        def create(**kwargs):
+            if "response_format" in kwargs:
+                raise Exception("400: response_format is not supported by this model")
+            return good
+
+        brain.text_client.chat.completions.create.side_effect = create
+        result = brain.get_action("click go", '{"ui_elements": []}', "web", skip_cache=True)
+        assert result["action"] == "click"  # fallback (no response_format) succeeded
+        ai_mod._JSON_MODE_UNSUPPORTED.clear()
+
+    def test_uses_vision_client_when_screenshot_provided(self, brain):
+        result_json = json.dumps({"result": {"action": "click", "locator_type": "text", "locator_value": "OK"}})
+        brain.vision_client.chat.completions.create.return_value = self._make_llm_response(result_json)
+
+        result = brain.get_action(
+            "click ok", '{"ui_elements": []}', "web",
+            screenshot_base64="base64data", skip_cache=True,
+        )
+        assert result["action"] == "click"
+        brain.vision_client.chat.completions.create.assert_called_once()
+        brain.text_client.chat.completions.create.assert_not_called()