fix: UE 5.8 survival -- Capability Ladder + bAllowAnyRemoteFunctionCall (v0.3.1)

CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-07-08 — 5.8 survival: the Capability Ladder
+
+The bridge was **silently broken on UE 5.8**: 5.8 defaults
+`RemoteControlSettings.bAllowAnyRemoteFunctionCall` to False, which blocks every
+`/remote/object/call` with HTTP 400 *"not allowed by remote control settings"*.
+So `execute_python` and every codegen tool failed live while `ue_status` and the
+mock-only CI stayed green — connectivity was measured, capability never was.
+
+### Fixed
+- **`bAllowAnyRemoteFunctionCall=True`** in `Config/DefaultRemoteControl.ini` —
+  the one line that unblocks every tool on 5.8 (localhost-only, single-trusted-
+  operator; the bridge already permits arbitrary Python exec over RC).
+- The Remote Control error **body is no longer swallowed** — the clients returned
+  only `"Client error '400 '"`; they now preserve the RC response body that says
+  *why* (`remote_control/async_client.py`, `sync_client.py`).
+
+### Added — the Capability Ladder (so this can't recur silently)
+- **`ue_preflight`** MCP tool + `ue_health_check(deep=true)`: a runtime probe that
+  separates *reachable* (a GET) from *permitted* / *capable* (a real function
+  call) / *round-trip* (the full Python path), stops at the first failure, and
+  returns the **named cause + one-line fix** with the raw RC body as evidence
+  (`remote_control/preflight.py`).
+- A **diagnosis map** (error signature → cause → fix); every future live failure
+  becomes a rule.
+- `tests/test_preflight.py` — 13 tests including the golden **failure** test: the
+  5.8 block must surface as rung `Permitted` naming `bAllowAnyRemoteFunctionCall`.
+
+### Notes
+- The mock suite proves the ladder's logic; a live 5.8 editor round-trip
+  (`ue_preflight`) is still the only proof of end-to-end capability. The config
+  fix is evidence-based (engine header `RemoteControlSettings.h:351` + the exact
+  error body).
+
 ## [0.3.0] - 2026-07-07 — UE ↔ X3D round-trip harness
 
 A new, self-contained `x3d_bridge/` package: a lossless UE↔X3D serialization

Config/DefaultRemoteControl.ini

@@ -25,3 +25,11 @@ bAllowConsoleCommandRemoteExecution=False
 ; .planning/PRODUCTION_READINESS_REPORT.md. The server is already localhost-only
 ; by default, which is the primary network-exposure mitigation.
 bRestrictServerAccess=False
+
+; REQUIRED on UE 5.8+ -- 5.8 added bAllowAnyRemoteFunctionCall (default False),
+; which blocks EVERY /remote/object/call. Without this, all codegen tools 400
+; with "not allowed by remote control settings" -- the bridge worked on 5.7
+; (where remote function calls were allowed) and silently broke on 5.8. Safe
+; under the bridge's localhost-only, single-trusted-operator model, which
+; already permits arbitrary Python execution over Remote Control.
+bAllowAnyRemoteFunctionCall=True

remote_control/__init__.py

@@ -7,10 +7,19 @@
 from .circuit_breaker import CircuitBreaker
 from .codegen import _CodeGen
 from .constants import BASE_URL, TIMEOUT
+from .preflight import (
+    Diagnosis,
+    PreflightResult,
+    diagnose,
+    http_error_detail,
+    preflight,
+)
 from .sync_client import UnrealRemoteControl
 
 __all__ = [
     "BASE_URL", "TIMEOUT",
     "CircuitBreaker", "_CodeGen",
     "UnrealRemoteControl", "AsyncUnrealRemoteControl",
+    # capability preflight
+    "preflight", "diagnose", "http_error_detail", "PreflightResult", "Diagnosis",
 ]

remote_control/async_client.py

@@ -22,6 +22,7 @@
     _poll_result_async,
     _prepare_execution,
 )
+from .preflight import http_error_detail
 
 
 class AsyncUnrealRemoteControl:
@@ -93,6 +94,19 @@ async def call_function(self, object_path: str, function_name: str, params: dict
         r.raise_for_status()
         return r.json()
 
+    async def _probe_call(self, path: str, method: str = "GET", payload: dict | None = None):
+        """Low-level RC call for the capability preflight: returns
+        (status, body, exc) and never raises, so the ladder can inspect the
+        real status code and response body instead of a swallowed exception."""
+        try:
+            if method == "GET":
+                r = await self._client.get(path)
+            else:
+                r = await self._client.put(path, json=payload)
+            return r.status_code, r.text, None
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            return None, "", e
+
     async def execute_python(self, code: str) -> dict:
         metrics.inc("requests.total")
         if not self._cb.allow_request():
@@ -112,8 +126,13 @@ async def execute_python(self, code: str) -> dict:
             self._cb.record_failure()
             metrics.inc("requests.error")
             metrics.record_latency("execute_python", time.time() - t0)
-            logger.error("UE5 connection failed: %s", e)
-            return {"result": None, "output": "", "error": f"Connection failed: {e}"}
+            # Preserve the Remote Control response body -- the bare str() of an
+            # HTTPStatusError is "Client error '400 '" and drops the reason
+            # (e.g. "not allowed by remote control settings"). Run ue_preflight
+            # for a named cause + fix.
+            detail = http_error_detail(e)
+            logger.error("UE5 remote call failed: %s", detail)
+            return {"result": None, "output": "", "error": detail}
         except Exception:
             # Non-connection fault (e.g. local file I/O in _prepare_execution): don't
             # trip the breaker, but release any HALF_OPEN probe slot we acquired so the

remote_control/execution.py

@@ -99,7 +99,14 @@ def _prepare_execution(temp_dir: str, code: str) -> tuple[str, str, str]:
 
 
 def _build_exec_payload(script_file: str) -> dict:
-    """Build the Remote Control call payload for script execution."""
+    """Build the Remote Control call payload for script execution.
+
+    Note: on UE 5.8 this (and every /remote/object/call) is rejected with HTTP
+    400 "not allowed by remote control settings" unless the project sets
+    bAllowAnyRemoteFunctionCall=True -- a 5.8 security default that silently
+    broke the bridge (it worked on 5.7). The fix lives in
+    Config/DefaultRemoteControl.ini, not here.
+    """
     return {
         "objectPath": "/Script/Engine.Default__KismetSystemLibrary",
         "functionName": "ExecuteConsoleCommand",

remote_control/preflight.py

@@ -0,0 +1,193 @@
+"""
+preflight.py
+
+The Capability Ladder: a runtime probe that answers "can the bridge actually
+EXECUTE against the editor?" -- not merely "is it reachable?" -- and turns any
+failure into a named cause plus a one-line fix.
+
+Why this exists: connectivity, permission, and capability are THREE different
+properties, and the bridge only ever measured the first. `ue_status` does a GET;
+the circuit breaker only sees connection errors; the mock test suite never makes
+a real Remote Control call. So the bridge can report "connected" and pass CI
+while every codegen tool 400s live -- exactly what UE 5.8 caused by defaulting
+`bAllowAnyRemoteFunctionCall` to False. This probe measures the other two
+properties, and preserves the RC error body the client otherwise discards, so a
+silent "400 " becomes an actionable diagnosis.
+
+Provides:
+- preflight(rc) -> PreflightResult : the ladder (Reachable -> Permitted -> Capable -> RoundTrip)
+- diagnose(status, body, exc) -> Diagnosis : error signature -> cause + fix
+- http_error_detail(exc) -> str : rich error string INCLUDING the RC response body
+- PreflightResult, Diagnosis, RUNGS
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+# The rungs, cheapest -> deepest. The probe stops at the first red.
+RUNGS = ("Reachable", "Permitted", "Capable", "RoundTrip")
+
+# A pure, side-effect-free engine function. It doubles as the Permitted probe
+# (does the call get rejected?) and the Capable probe (does a value round-trip?).
+_PROBE_OBJECT = "/Script/Engine.Default__KismetSystemLibrary"
+_PROBE_FUNCTION = "GetEngineVersion"
+
+
+@dataclass
+class Diagnosis:
+    cause: str
+    fix: str
+
+
+@dataclass
+class PreflightResult:
+    ok: bool
+    rung: str  # Reachable | Permitted | Capable | RoundTrip | OK
+    cause: str = ""
+    fix: str = ""
+    evidence: str = ""  # raw status + body, for the operator
+    engine_version: str = ""
+
+
+def http_error_detail(exc: Exception) -> str:
+    """Rich detail from an httpx error, INCLUDING the Remote Control response body.
+
+    The bare str() of an httpx.HTTPStatusError is "Client error '400 ' for url ..."
+    -- it drops the JSON body that says *why*. This keeps it, so a caller can see
+    (and diagnose) the actual reason.
+    """
+    resp = getattr(exc, "response", None)
+    if resp is not None:
+        try:
+            body = (resp.text or "").strip()
+        except Exception:
+            body = ""
+        return f"HTTP {resp.status_code}: {body}" if body else f"HTTP {resp.status_code}"
+    return f"{type(exc).__name__}: {exc}"
+
+
+def diagnose(status: int | None, body: str | None, exc: Exception | None) -> Diagnosis:
+    """Map a Remote Control failure signature to a named cause + one-line fix.
+
+    Extend by adding a branch: every hard-won live failure should become a rule
+    here so the next occurrence self-explains.
+    """
+    b = (body or "").lower()
+
+    if exc is not None:
+        return Diagnosis(
+            f"Remote Control is unreachable ({type(exc).__name__}).",
+            "Open the UE editor with the Remote Control plugin enabled and its Web "
+            "Server started on :30010.",
+        )
+
+    if status == 400 and "not allowed by remote control settings" in b:
+        if "python" in b:
+            return Diagnosis(
+                "Remote Python execution is disabled "
+                "(RemoteControlSettings.bEnableRemotePythonExecution = False).",
+                "Set bEnableRemotePythonExecution=True in the project's "
+                "Config/DefaultRemoteControl.ini; restart the editor.",
+            )
+        return Diagnosis(
+            "UE 5.8 blocks remote function calls by default "
+            "(RemoteControlSettings.bAllowAnyRemoteFunctionCall = False).",
+            "Set bAllowAnyRemoteFunctionCall=True in Config/DefaultRemoteControl.ini "
+            "(or Project Settings -> Plugins -> Remote Control -> Security -> "
+            "'Allow Any Remote Function Call'); restart the editor.",
+        )
+
+    if status in (401, 403) or "passphrase" in b:
+        return Diagnosis(
+            "Remote Control requires a passphrase (bRestrictServerAccess = True).",
+            "Set bRestrictServerAccess=False, or configure the MCP client to send "
+            "the passphrase.",
+        )
+
+    if status == 404:
+        return Diagnosis(
+            "The target object or function is not remotely accessible.",
+            "Verify the objectPath/functionName; some engine objects (e.g. settings "
+            "CDOs) cannot be reached remotely.",
+        )
+
+    return Diagnosis(
+        f"Unrecognized Remote Control failure (HTTP {status}).",
+        "Inspect the evidence body and add a diagnose() rule for this signature.",
+    )
+
+
+def _evidence(status: int | None, body: str | None, exc: Exception | None) -> str:
+    if exc is not None:
+        return f"{type(exc).__name__}: {exc}"
+    return f"HTTP {status}: {(body or '').strip()}"
+
+
+def _extract_return_value(body: str) -> str:
+    """Pull the scalar return value out of an RC /remote/object/call response."""
+    try:
+        data = json.loads(body)
+    except (json.JSONDecodeError, TypeError):
+        return ""
+    if isinstance(data, dict):
+        # RC names the return "ReturnValue"; fall back to the first non-empty string.
+        if isinstance(data.get("ReturnValue"), str):
+            return data["ReturnValue"]
+        for value in data.values():
+            if isinstance(value, str) and value:
+                return value
+    return ""
+
+
+async def preflight(rc) -> PreflightResult:
+    """Run the capability ladder against a Remote Control client.
+
+    `rc` must provide:
+        async _probe_call(path, method="GET", payload=None) -> (status|None, body, exc|None)
+        async execute_python(code) -> {"result", "output", "error"}
+
+    Stops at the first failed rung and returns a named cause + fix.
+    """
+    # Rung 0 -- Reachable
+    status, body, exc = await rc._probe_call("/remote/info", "GET")
+    if exc is not None or status != 200:
+        d = diagnose(status, body, exc)
+        return PreflightResult(False, "Reachable", d.cause, d.fix, _evidence(status, body, exc))
+
+    # Rungs 1+2 -- Permitted (does the call get rejected?) and Capable (does a value return?)
+    status, body, exc = await rc._probe_call(
+        "/remote/object/call",
+        "PUT",
+        {"objectPath": _PROBE_OBJECT, "functionName": _PROBE_FUNCTION},
+    )
+    if exc is not None or status != 200:
+        rung = "Reachable" if exc is not None else "Permitted"
+        d = diagnose(status, body, exc)
+        return PreflightResult(False, rung, d.cause, d.fix, _evidence(status, body, exc))
+
+    version = _extract_return_value(body)
+    if not version:
+        return PreflightResult(
+            False,
+            "Capable",
+            "A remote function call was permitted but returned no value.",
+            "Unexpected Remote Control response shape; check the RC/engine version.",
+            _evidence(status, body, None),
+        )
+
+    # Rung 3 -- RoundTrip (the full write -> exec -> poll -> result Python path)
+    result = await rc.execute_python('print("RESULT: PREFLIGHT_OK")')
+    if result.get("result") != "PREFLIGHT_OK":
+        return PreflightResult(
+            False,
+            "RoundTrip",
+            "Function calls work, but the Python write->exec->poll result path failed.",
+            "Check the Python Editor Script Plugin and the temp-script directory; "
+            "see remote_control/execution.py.",
+            str(result.get("error") or result),
+            engine_version=version,
+        )
+
+    return PreflightResult(True, "OK", engine_version=version)

remote_control/sync_client.py

@@ -22,6 +22,7 @@
     _poll_result_sync,
     _prepare_execution,
 )
+from .preflight import http_error_detail
 
 
 class UnrealRemoteControl:
@@ -104,8 +105,10 @@ def execute_python(self, code: str) -> dict:
             self._cb.record_failure()
             metrics.inc("requests.error")
             metrics.record_latency("execute_python", time.time() - t0)
-            logger.error("UE5 connection failed: %s", e)
-            return {"result": None, "output": "", "error": f"Connection failed: {e}"}
+            # Preserve the Remote Control response body (see async_client / preflight).
+            detail = http_error_detail(e)
+            logger.error("UE5 remote call failed: %s", detail)
+            return {"result": None, "output": "", "error": detail}
         except Exception:
             # Non-connection fault (e.g. local file I/O in _prepare_execution): don't
             # trip the breaker, but release any HALF_OPEN probe slot we acquired so the