rf-mcp 0.34.0.dev3__tar.gz → 0.34.0.dev5__tar.gz

{rf_mcp-0.34.0.dev3 → rf_mcp-0.34.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rf-mcp
-Version: 0.34.0.dev3
+Version: 0.34.0.dev5
 Summary: Robot Framework MCP Server - Natural Language Test Automation Bridge
 Project-URL: Homepage, https://github.com/manykarim/rf-mcp
 Project-URL: Repository, https://github.com/manykarim/rf-mcp
@@ -21,9 +21,11 @@ Requires-Dist: tomlkit>=0.12.0
 Provides-Extra: all
 Requires-Dist: django<5.0,>=4.2; extra == 'all'
 Requires-Dist: model2vec>=0.4.0; extra == 'all'
+Requires-Dist: platynui-cli==0.13.0.dev2; (python_version >= '3.12') and extra == 'all'
 Requires-Dist: robotframework-appiumlibrary; extra == 'all'
 Requires-Dist: robotframework-browser; extra == 'all'
 Requires-Dist: robotframework-databaselibrary; extra == 'all'
+Requires-Dist: robotframework-platynui==0.13.0.dev2; (python_version >= '3.12') and extra == 'all'
 Requires-Dist: robotframework-requests; extra == 'all'
 Requires-Dist: robotframework-seleniumlibrary; extra == 'all'
 Requires-Dist: sqlite-vec>=0.1.6; extra == 'all'
@@ -228,7 +230,7 @@ uv pip install --pre rf-mcp[desktop]  # PlatynUI new-core (Rust) native desktop
 uv pip install rf-mcp[frontend]  # Django-based web frontend dashboard
 uv pip install rf-mcp[memory]    # Persistent semantic memory (sqlite-vec + model2vec)
 uv pip install rf-mcp[semantic]  # Sentence-transformers for find_keywords embedding ranking
-uv pip install rf-mcp[all]       # All optional Robot Framework libraries (desktop is separate — prerelease/3.12+)
+uv pip install rf-mcp[all]       # All optional Robot Framework libraries (includes desktop on Python 3.12+)
 
 # Alternatively, add to an existing uv project
 uv init

{rf_mcp-0.34.0.dev3 → rf_mcp-0.34.0.dev5}/README.md

@@ -171,7 +171,7 @@ uv pip install --pre rf-mcp[desktop]  # PlatynUI new-core (Rust) native desktop
 uv pip install rf-mcp[frontend]  # Django-based web frontend dashboard
 uv pip install rf-mcp[memory]    # Persistent semantic memory (sqlite-vec + model2vec)
 uv pip install rf-mcp[semantic]  # Sentence-transformers for find_keywords embedding ranking
-uv pip install rf-mcp[all]       # All optional Robot Framework libraries (desktop is separate — prerelease/3.12+)
+uv pip install rf-mcp[all]       # All optional Robot Framework libraries (includes desktop on Python 3.12+)
 
 # Alternatively, add to an existing uv project
 uv init

{rf_mcp-0.34.0.dev3 → rf_mcp-0.34.0.dev5}/pyproject.toml

@@ -4,7 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rf-mcp"
-version = "0.34.0.dev3"
+# 0.34.0.dev5: harden-platynui-stuck-key-release — extend the platynui-windows-runtime
+# stuck-key net from modifiers-only to a tracked held-key registry (releases
+# non-modifier keys too) plus persisted-state recovery across hard process kills.
+version = "0.34.0.dev5"
 description = "Robot Framework MCP Server - Natural Language Test Automation Bridge"
 authors = [{ name = "Many Kasiriha" }]
 license = { text = "Apache-2.0" }
@@ -65,6 +68,12 @@ all = [
     "sqlite-vec>=0.1.6",
     "model2vec>=0.4.0",
     "tiktoken>=0.7.0",
+    # Desktop automation is part of [all]. Referenced as a self-extra so the
+    # PlatynUI pins stay defined in exactly one place (see `desktop` above) —
+    # bumping them there is enough. The `python_version >= "3.12"` markers ride
+    # along, so on 3.10/3.11 this contributes nothing and [all] still resolves.
+    # The exact-pinned prerelease is accepted without a global --pre.
+    "rf-mcp[desktop]",
 ]
 # NOTE: dev tooling lives in [dependency-groups].dev (PEP 735), which is what
 # `uv sync` / CI use. The former [project.optional-dependencies].dev extra was

{rf_mcp-0.34.0.dev3 → rf_mcp-0.34.0.dev5}/src/robotmcp/components/execution/desktop_display_safety.py

@@ -40,12 +40,39 @@ ISOLATION_MARKER_ENV = "ROBOTMCP_PLATYNUI_ISOLATED_DISPLAY"
 ISOLATION_XPID_ENV = "ROBOTMCP_PLATYNUI_ISOLATED_XPID"
 ALLOW_ACTIVE_ENV = "ROBOTMCP_PLATYNUI_ALLOW_ACTIVE_DESKTOP"
 SAFETY_GUARD_ENV = "ROBOTMCP_PLATYNUI_SAFETY_GUARD"  # "warn" => log, don't block
+# Strict opt-IN to enforce isolation on Windows (change:
+# fix-platynui-windows-runtime, F4). Windows has no headless-isolation model
+# (no Xvfb/Xephyr equivalent), so the guard is permissive by default there;
+# operators who insist on isolation set this to refuse instead.
+REQUIRE_ISOLATED_ENV = "ROBOTMCP_PLATYNUI_REQUIRE_ISOLATED"
 
 _X_SERVER_BINARIES = ("xvfb", "xephyr", "xorg", "/x ", "/x\x00", "x11")
 
 ISOLATED = "isolated"
 ACTIVE = "active"
 UNKNOWN = "unknown"
+# Windows has exactly one interactive desktop and no X11 isolated-display
+# model; the X11/EWMH/marker probes never apply (change:
+# fix-platynui-windows-runtime, F4).
+WINDOWS = "windows"
+
+# Windows-accurate isolation note — NEVER the Linux nested-X-server recipe.
+_WINDOWS_ISOLATION_NOTE = (
+    "On Windows there is no headless nested-display isolation model. Desktop "
+    "automation drives the active session's desktop. To isolate it, run rf-mcp "
+    "in a dedicated Windows user session or over RDP to a separate session."
+)
+
+
+def _is_windows() -> bool:
+    """True on Windows (patchable via ``os.name`` in tests)."""
+    return os.name == "nt"
+
+
+def require_isolated(environ: Optional[Dict[str, str]] = None) -> bool:
+    """Strict opt-in to enforce isolation on Windows (F4)."""
+    env = environ if environ is not None else os.environ
+    return env.get(REQUIRE_ISOLATED_ENV, "").strip().lower() in {"1", "true", "yes"}
 
 
 def _bound_display(environ: Dict[str, str]) -> Optional[str]:
@@ -201,6 +228,14 @@ def classify_bound_display_detailed(
     ``none`` (no display bound / probe inconclusive).
     """
     env = environ if environ is not None else os.environ
+    # Windows: no X11/EWMH/marker model applies — classify as `windows` before
+    # any probe (change: fix-platynui-windows-runtime, F4).
+    if _is_windows():
+        return {
+            "display": None,
+            "isolation": WINDOWS,
+            "isolation_source": "windows_console",
+        }
     display = _bound_display(env)
     if _has_isolation_marker(env, display):
         # Corroborate the marker against a recorded X-server PID (change:
@@ -286,6 +321,30 @@ def evaluate_safety(
             "classification": classification, "enforcing": True,
             "allowed": True, "bypassed": False, "reason": None,
         }
+    if classification == WINDOWS:
+        # F4: Windows has no isolated-display model — refusing every keyword
+        # (with an impossible Xephyr recipe) blocks all Windows automation.
+        # Allow by default with a one-time active-desktop warning; a strict
+        # opt-in enforces isolation for operators who want it. No Xephyr recipe.
+        if require_isolated(env):
+            return {
+                "classification": classification, "enforcing": True,
+                "allowed": False, "bypassed": False,
+                "reason": (
+                    "ROBOTMCP_PLATYNUI_REQUIRE_ISOLATED is set and this is a "
+                    "Windows active desktop. " + _WINDOWS_ISOLATION_NOTE
+                ),
+                "windows_note": _WINDOWS_ISOLATION_NOTE,
+            }
+        return {
+            "classification": classification, "enforcing": True,
+            "allowed": True, "bypassed": False,
+            "reason": (
+                "PlatynUI will drive the ACTIVE Windows desktop. "
+                + _WINDOWS_ISOLATION_NOTE
+            ),
+            "windows_note": _WINDOWS_ISOLATION_NOTE,
+        }
     reason = (
         f"bound display classified '{classification}': refusing desktop input "
         "to avoid leaking onto the user's active session. Run on an isolated "

{rf_mcp-0.34.0.dev3 → rf_mcp-0.34.0.dev5}/src/robotmcp/components/execution/desktop_guidance.py

@@ -30,6 +30,7 @@ _LOCATOR_CRIB: List[str] = [
     "Launch the app first (Process.Start Process), then Query for its control:Frame before acting.",
     "Read a value back with Get Attribute on the scoped node; GTK text views expose native:Text.CharacterCount (not live text content).",
     "Take Screenshot signature is (descriptor, filename, rect) — the FIRST positional is a node descriptor, not a filename; pass filename= for a path.",
+    "Prefer the atomic 'Keyboard Type' (self-contained press+release) for shortcuts, e.g. Keyboard Type  <descriptor>  <Ctrl+A>. A bare 'Keyboard Press' sends key-DOWN ONLY and MUST be paired with 'Keyboard Release' — an unpaired Press (esp. a non-modifier like a letter/F-key/Escape) leaves a key physically held on the OS.",
     "For the full locator cookbook call get_locator_guidance (topic defaults to the desktop/PlatynUI chapter).",
 ]
 

{rf_mcp-0.34.0.dev3 → rf_mcp-0.34.0.dev5}/src/robotmcp/components/execution/keyword_executor.py

@@ -535,6 +535,22 @@ class KeywordExecutor:
             logger.debug("desktop input-effect snapshot skipped: %s", exc)
             return None
 
+    @staticmethod
+    def _is_desktop_keyboard_keyword(session, keyword) -> bool:
+        """True when this is a PlatynUI keyboard keyword on a desktop session
+        (change: fix-platynui-windows-runtime, F16). Used to release held
+        modifiers when a keyboard keyword fails or is killed mid-chord."""
+        try:
+            is_desktop = getattr(session, "is_desktop_session", None)
+            if not (callable(is_desktop) and is_desktop() is True):
+                return False
+            norm = str(keyword or "").lower().rsplit(".", 1)[-1].strip()
+            return norm in (
+                "keyboard press", "keyboard type", "keyboard release",
+            )
+        except Exception:  # pragma: no cover - defensive
+            return False
+
     def _platynui_safety_guard(self, session, keyword):
         """Active-desktop safety guard for PlatynUI interaction keywords
         (change: platynui-desktop-safety-isolation).
@@ -565,6 +581,18 @@ class KeywordExecutor:
                 "PlatynUI safety guard: refused on %s desktop",
                 outcome["classification"],
             )
+        elif outcome["classification"] == "windows":
+            # F4: one-time warning that Windows automation drives the active
+            # desktop (there is no isolated-display model on Windows).
+            if not getattr(session, "_platynui_windows_warned", False):
+                try:
+                    session._platynui_windows_warned = True
+                except Exception:
+                    pass
+                logger.warning(
+                    "PlatynUI: driving the ACTIVE Windows desktop — %s",
+                    outcome.get("reason") or "",
+                )
         return outcome
 
     def _platynui_focus_before_act(self, session, keyword, arguments):
@@ -1886,13 +1914,165 @@ class KeywordExecutor:
         # causing it to go to stderr instead of the MCP transport.
         # The lock also prevents concurrent Selenium WebDriver access.
         async with self._execution_lock:
-            return await self._execute_keyword_serialized(
-                session, keyword, arguments, browser_library_manager,
-                detail_level, library_prefix, assign_to, use_context, timeout_ms,
-                record=record,
-                pre_validate_timeout_ms=pre_validate_timeout_ms,
+            # F16 + harden-platynui-stuck-key-release: a desktop keyboard keyword
+            # that raises or returns failure may have been killed mid-chord,
+            # leaving a key physically held at the OS level (the operator's
+            # keyboard wedged). We track the EXACT keys held (incl. non-modifiers)
+            # so teardown/failure/exit release precisely those. A SUCCESSFUL
+            # Keyboard Press legitimately holds a key for a later Keyboard
+            # Release, so we do NOT release on success — but we DO record it.
+            _kbd = self._is_desktop_keyboard_keyword(session, keyword)
+            _kbd_kind, _kbd_seq = (
+                self._desktop_keyboard_op(keyword, arguments) if _kbd else (None, None)
+            )
+            # Record intended-held keys BEFORE dispatch so a kill mid-call is
+            # covered by the persisted state file (Press holds; Type holds then
+            # releases within the same call).
+            if _kbd_kind in ("press", "type") and _kbd_seq:
+                self._record_pressed_keys(_kbd_seq)
+            try:
+                result = await self._execute_keyword_serialized(
+                    session, keyword, arguments, browser_library_manager,
+                    detail_level, library_prefix, assign_to, use_context,
+                    timeout_ms,
+                    record=record,
+                    pre_validate_timeout_ms=pre_validate_timeout_ms,
+                )
+            except BaseException:
+                # An exception (incl. CancelledError from a killed run) is the
+                # canonical "killed mid-chord" case. Release SYNCHRONOUSLY here
+                # so it is guaranteed to run even while the task is being
+                # cancelled (an awaited offload could be interrupted before it
+                # dispatches). keyboard_release is a fast input dispatch, not a
+                # tree query, so the brief on-loop cost is acceptable.
+                if _kbd:
+                    self._release_desktop_keys()
+                raise
+            _released_here = False
+            if (
+                _kbd
+                and isinstance(result, dict)
+                and not result.get("success", True)
+                # F2: a steering-confidence downgrade means the native keyword
+                # actually SUCCEEDED (the key is held as intended) — releasing
+                # would corrupt a deliberate Press/Release chord. Only release
+                # on a genuine execution failure.
+                and not self._is_steering_downgrade(result)
+            ):
+                # F4: offload the release off the event loop on the normal
+                # failure-return path (no cancellation concern here). Releases
+                # the exact tracked held set (incl. non-modifiers) + clears state.
+                await asyncio.to_thread(self._release_desktop_keys)
+                _released_here = True
+                # Steering: point the agent at the atomic Keyboard Type, which
+                # cannot leave a key held.
+                try:
+                    hints = result.setdefault("hints", [])
+                    if isinstance(hints, list):
+                        hints.append({
+                            "type": "platynui_keyboard_release_safety",
+                            "message": (
+                                "Released all held keyboard keys (including any "
+                                "non-modifier such as a letter/F-key/Escape) "
+                                "after this keyboard keyword failed. Prefer the "
+                                "atomic 'Keyboard Type <Ctrl+A>' (self-contained "
+                                "press+release) over a bare 'Keyboard Press', "
+                                "which sends key-DOWN only and MUST be paired "
+                                "with 'Keyboard Release'."
+                            ),
+                        })
+                except Exception:  # pragma: no cover - defensive
+                    pass
+            # On a SUCCESSFUL Keyboard Type / Keyboard Release, the paired key-UP
+            # already happened — clear those keys from the registry. (Press keeps
+            # its recorded keys held until an explicit Keyboard Release.)
+            if not _released_here and _kbd_kind in ("type", "release") and _kbd_seq:
+                self._record_released_keys(_kbd_seq)
+            return result
+
+    @staticmethod
+    def _desktop_keyboard_op(keyword, arguments):
+        """Return ``(kind, sequence)`` for a desktop keyboard keyword, where
+        kind is ``"press"``/``"type"``/``"release"`` and sequence is the key
+        text argument (2nd positional, or a ``text=`` named arg). Non-raising;
+        returns ``(None, None)`` when it cannot classify. change:
+        harden-platynui-stuck-key-release."""
+        try:
+            norm = str(keyword or "").lower().rsplit(".", 1)[-1].strip()
+            kind = {
+                "keyboard press": "press",
+                "keyboard type": "type",
+                "keyboard release": "release",
+            }.get(norm)
+            if kind is None:
+                return (None, None)
+            seq = None
+            args = list(arguments or [])
+            for a in args:
+                if isinstance(a, str) and a.startswith("text="):
+                    seq = a[len("text="):]
+                    break
+            if seq is None and len(args) >= 2:
+                seq = args[1]
+            return (kind, seq)
+        except Exception:  # pragma: no cover - defensive
+            return (None, None)
+
+    @staticmethod
+    def _record_pressed_keys(sequence) -> None:
+        """Record keys a desktop Press/Type is about to hold. Never raises.
+        change: harden-platynui-stuck-key-release."""
+        try:
+            from robotmcp.plugins.builtin.platynui_plugin import record_pressed_keys
+
+            record_pressed_keys(sequence)
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("record_pressed_keys failed: %s", exc)
+
+    @staticmethod
+    def _record_released_keys(sequence) -> None:
+        """Remove keys released by a desktop Release/Type from the registry.
+        Never raises. change: harden-platynui-stuck-key-release."""
+        try:
+            from robotmcp.plugins.builtin.platynui_plugin import record_released_keys
+
+            record_released_keys(sequence)
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("record_released_keys failed: %s", exc)
+
+    @staticmethod
+    def _is_steering_downgrade(result: dict) -> bool:
+        """True when a desktop keyword's success was flipped to failure by the
+        steering-confidence gate rather than a genuine execution failure
+        (change: fix-platynui-windows-runtime, F16/F2).
+
+        A steering downgrade means the native keyword DID execute (its key is
+        held as intended), so F16 must not release its modifiers. The gate only
+        downgrades in the RF-success path, so this marker uniquely identifies
+        the case."""
+        try:
+            from robotmcp.components.execution.desktop_execution_signals import (
+                SC_CONTRADICTED,
+            )
+        except Exception:  # pragma: no cover - defensive
+            SC_CONTRADICTED = "contradicted"
+        return bool(result.get("steering_confidence") == SC_CONTRADICTED)
+
+    @staticmethod
+    def _release_desktop_keys() -> None:
+        """Best-effort release of the EXACT tracked held-key set (incl.
+        non-modifiers) via the PlatynUI runtime, clearing the registry + state
+        file. Falls back to a modifier blast internally. Never raises.
+        change: harden-platynui-stuck-key-release."""
+        try:
+            from robotmcp.plugins.builtin.platynui_plugin import (
+                release_tracked_keys,
             )
 
+            release_tracked_keys()
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("desktop key release failed: %s", exc)
+
     async def _execute_keyword_serialized(
         self,
         session: ExecutionSession,
@@ -1924,6 +2104,19 @@ class KeywordExecutor:
                     )
 
                     ensure_x11_session_env()
+                    # F3 (change: fix-platynui-windows-runtime): a caller who
+                    # passes an explicit timeout_ms wants desktop query/wait
+                    # keywords to wait that long; stash it so the query-settings
+                    # default (applied in _execute_keyword_with_context) honors
+                    # it. This is PER-CALL — reset to None when absent so a
+                    # one-off long timeout never becomes a session-sticky
+                    # default that defeats the fast-fail behaviour on later
+                    # steps (the short default is restored automatically).
+                    session._platynui_query_timeout_ms = (
+                        timeout_ms
+                        if isinstance(timeout_ms, int) and timeout_ms > 0
+                        else None
+                    )
                     # D2: if a recent desktop launch marked the tree stale,
                     # refresh the cached accessibility tree before the FIRST
                     # tree-resolving keyword so a newly-launched app resolves by
@@ -2029,8 +2222,18 @@ class KeywordExecutor:
                     # the AUT window is visible/in-scope (change:
                     # platynui-focused-execution). FocusError fails fast under
                     # opt-in policy; otherwise warnings ride along on the step.
-                    _focus_outcome = self._platynui_focus_before_act(
-                        session, keyword, arguments
+                    # F14 (change: fix-platynui-windows-runtime): the focus
+                    # manager drives raw runtime.evaluate() (find/activate/
+                    # highlight the AUT window) with NO timeout knob — a broad
+                    # or busy-tree query blocks the event loop for tens of
+                    # seconds, wedging metadata calls. Offload to a worker
+                    # thread so the loop stays free; the global _execution_lock
+                    # already serializes desktop dispatch so no native
+                    # concurrency is introduced. FocusError still propagates
+                    # out of to_thread to the except below.
+                    _focus_outcome = await asyncio.to_thread(
+                        self._platynui_focus_before_act,
+                        session, keyword, arguments,
                     )
                     # Resolve a desktop Process launch/recovery executable to an
                     # absolute path against the server PATH (maintainer-report
@@ -2052,8 +2255,10 @@ class KeywordExecutor:
                     # so a success-with-no-effect can be flagged afterward
                     # (change: desktop-input-and-runtime-diagnostics). Native /
                     # non-reentrant; best-effort.
-                    _input_effect_before = self._desktop_text_count_before(
-                        keyword, arguments
+                    # F14: native CharacterCount query — also offload off the
+                    # loop (change: fix-platynui-windows-runtime).
+                    _input_effect_before = await asyncio.to_thread(
+                        self._desktop_text_count_before, keyword, arguments
                     )
             except Exception as _focus_exc:
                 from robotmcp.components.execution.platynui_focus import FocusError
@@ -2551,7 +2756,13 @@ class KeywordExecutor:
                         # but the target's CharacterCount did not change.
                         _after = None
                         if _input_effect_before is not None:
-                            _after = self._desktop_text_count_before(keyword, arguments)
+                            # F14 (change: fix-platynui-windows-runtime): the
+                            # AFTER CharacterCount probe is the same native
+                            # runtime.evaluate() as the offloaded BEFORE probe —
+                            # offload it off the loop too for symmetry.
+                            _after = await asyncio.to_thread(
+                                self._desktop_text_count_before, keyword, arguments
+                            )
                             _eh = input_effect_hint(
                                 keyword=keyword,
                                 success=True,
@@ -3089,6 +3300,90 @@ class KeywordExecutor:
             return mapped
         return None
 
+    # Short default desktop query timeout (F3). PlatynUI.BareMetal's
+    # QuerySettings default is 30s, so an honest-miss Query/wait waits the full
+    # 30s and stacks across retries (up to ~180s in the Windows eval). A short
+    # default fails fast; a caller can still request a longer wait via
+    # timeout_ms. Overridable via ROBOTMCP_PLATYNUI_QUERY_TIMEOUT_MS.
+    _DEFAULT_PLATYNUI_QUERY_TIMEOUT_MS = 1500
+
+    def _ensure_desktop_query_timeout(self, session) -> None:
+        """Give desktop PlatynUI query/wait keywords a short default timeout so
+        an honest-miss fails fast (change: fix-platynui-windows-runtime, F3).
+
+        Mirrors ``Set Query Settings scope=SUITE`` by writing a short-timeout
+        ``QuerySettings`` into ``${PLATYNUI_QUERY_SETTINGS}`` in the live RF
+        context, once per session (re-applied only if the desired value
+        changed). A caller-supplied ``timeout_ms`` (stashed on the session)
+        overrides the short default. Best-effort; never raises — on any failure
+        the library keeps its 30s default (no worse than before)."""
+        try:
+            checker = getattr(session, "is_desktop_session", None)
+            if not (callable(checker) and checker() is True):
+                return
+        except Exception:
+            return
+        try:
+            default_ms = int(
+                os.environ.get(
+                    "ROBOTMCP_PLATYNUI_QUERY_TIMEOUT_MS",
+                    str(self._DEFAULT_PLATYNUI_QUERY_TIMEOUT_MS),
+                )
+            )
+        except (ValueError, TypeError):
+            default_ms = self._DEFAULT_PLATYNUI_QUERY_TIMEOUT_MS
+        desired_ms = getattr(session, "_platynui_query_timeout_ms", None) or default_ms
+        if desired_ms <= 0:
+            return
+        if getattr(session, "_platynui_query_timeout_applied_ms", None) == desired_ms:
+            return
+        try:
+            from dataclasses import replace as _dc_replace
+
+            from robot.running.context import EXECUTION_CONTEXTS as _EC
+            from PlatynUI.BareMetal import (  # library-sanctioned mechanism
+                PLATYNUI_QUERY_SETTINGS,
+                QuerySettings,
+            )
+
+            ctx = _EC.current
+            if ctx is None:
+                return
+            variables = ctx.variables
+            name = f"${{{PLATYNUI_QUERY_SETTINGS}}}"
+            # Preserve any non-timeout query settings already in scope
+            # (retry_interval / ignore_exceptions) instead of resetting them to
+            # class defaults — only the timeout is ours to change.
+            base = None
+            try:
+                if PLATYNUI_QUERY_SETTINGS in variables:
+                    existing = variables[name]
+                    if isinstance(existing, QuerySettings):
+                        base = existing
+            except Exception:
+                base = None
+            timeout_s = desired_ms / 1000.0
+            settings = (
+                _dc_replace(base, timeout=timeout_s)
+                if base is not None
+                else QuerySettings(timeout=timeout_s)
+            )
+            # set_suite(children=True): a bare write into the SUITE store is
+            # invisible because rf-mcp already holds a live TEST scope copied
+            # from suite BEFORE the write, and PlatynUI resolves the variable
+            # via variables.current (the test scope). set_suite(children=True)
+            # both persists at SUITE (surviving per-step test-scope resets) AND
+            # propagates down to the current/test scope so the library sees it
+            # immediately (mirrors Set Query Settings scope=SUITE).
+            variables.set_suite(name, settings, children=True)
+            session._platynui_query_timeout_applied_ms = desired_ms
+            logger.debug(
+                "Applied desktop query timeout %sms via ${PLATYNUI_QUERY_SETTINGS}",
+                desired_ms,
+            )
+        except Exception as exc:  # pragma: no cover - env/internals dependent
+            logger.debug("desktop query-settings apply skipped: %s", exc)
+
     def _inject_timeout_into_arguments(
         self,
         keyword: str,
@@ -3675,6 +3970,10 @@ class KeywordExecutor:
             except Exception:
                 pass
 
+            # F3: give desktop query/wait keywords a short fast-fail timeout
+            # now that the RF context exists (no-op for non-desktop sessions).
+            self._ensure_desktop_query_timeout(session)
+
             # Execute keyword using RF native context with session variables
             result = await asyncio.to_thread(
                 self.rf_native_context.execute_keyword_with_context,