mcpforunityserver 8.5.0__py3-none-any.whl → 8.7.0__py3-none-any.whl

services/tools/manage_asset.py

@@ -12,6 +12,7 @@ from services.tools import get_unity_instance_from_context
 from services.tools.utils import parse_json_payload, coerce_int
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
+from services.tools.preflight import preflight
 
 
 @mcp_for_unity_tool(
@@ -47,6 +48,12 @@ async def manage_asset(
 ) -> dict[str, Any]:
     unity_instance = get_unity_instance_from_context(ctx)
 
+    # Best-effort guard: if Unity is compiling/reloading or known external changes are pending,
+    # wait/refresh to avoid stale reads and flaky timeouts.
+    gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+    if gate is not None:
+        return gate.model_dump()
+
     def _parse_properties_string(raw: str) -> tuple[dict[str, Any] | None, str | None]:
         try:
             parsed = json.loads(raw)

services/tools/manage_gameobject.py

@@ -8,6 +8,7 @@ from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 from services.tools.utils import coerce_bool, parse_json_payload, coerce_int
+from services.tools.preflight import preflight
 
 
 @mcp_for_unity_tool(
@@ -92,6 +93,10 @@ async def manage_gameobject(
     # Removed session_state import
     unity_instance = get_unity_instance_from_context(ctx)
 
+    gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+    if gate is not None:
+        return gate.model_dump()
+
     if action is None:
         return {
             "success": False,

services/tools/manage_scene.py

@@ -6,6 +6,7 @@ from services.tools import get_unity_instance_from_context
 from services.tools.utils import coerce_int, coerce_bool
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
+from services.tools.preflight import preflight
 
 
 @mcp_for_unity_tool(
@@ -40,6 +41,9 @@ async def manage_scene(
     # Get active instance from session state
     # Removed session_state import
     unity_instance = get_unity_instance_from_context(ctx)
+    gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+    if gate is not None:
+        return gate.model_dump()
     try:
         coerced_build_index = coerce_int(build_index, default=None)
         coerced_super_size = coerce_int(screenshot_super_size, default=None)

services/tools/preflight.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any
+
+from models import MCPResponse
+
+
+def _in_pytest() -> bool:
+    # Integration tests in this repo stub transports and do not run against a live Unity editor.
+    # Preflight must be a no-op in that environment to avoid breaking the existing test suite.
+    return bool(os.environ.get("PYTEST_CURRENT_TEST"))
+
+
+def _busy(reason: str, retry_after_ms: int) -> MCPResponse:
+    return MCPResponse(
+        success=False,
+        error="busy",
+        message=reason,
+        hint="retry",
+        data={"reason": reason, "retry_after_ms": int(retry_after_ms)},
+    )
+
+
+async def preflight(
+    ctx,
+    *,
+    requires_no_tests: bool = False,
+    wait_for_no_compile: bool = False,
+    refresh_if_dirty: bool = False,
+    max_wait_s: float = 30.0,
+) -> MCPResponse | None:
+    """
+    Server-side preflight guard used by tools so they behave safely even if the client never reads resources.
+
+    Returns:
+      - MCPResponse busy/retry payload when the tool should not proceed right now
+      - None when the tool should proceed normally
+    """
+    if _in_pytest():
+        return None
+
+    # Load canonical v2 state (server enriches advice + staleness).
+    try:
+        from services.resources.editor_state_v2 import get_editor_state_v2
+        state_resp = await get_editor_state_v2(ctx)
+        state = state_resp.model_dump() if hasattr(state_resp, "model_dump") else state_resp
+    except Exception:
+        # If we cannot determine readiness, fall back to proceeding (tools already contain retry logic).
+        return None
+
+    if not isinstance(state, dict) or not state.get("success", False):
+        # Unknown state; proceed rather than blocking (avoids false positives when Unity is reachable but status isn't).
+        return None
+
+    data = state.get("data")
+    if not isinstance(data, dict):
+        return None
+
+    # Optional refresh-if-dirty
+    if refresh_if_dirty:
+        assets = data.get("assets")
+        if isinstance(assets, dict) and assets.get("external_changes_dirty") is True:
+            try:
+                from services.tools.refresh_unity import refresh_unity
+                await refresh_unity(ctx, mode="if_dirty", scope="all", compile="request", wait_for_ready=True)
+            except Exception:
+                # Best-effort only; fall through to normal tool dispatch.
+                pass
+
+    # Tests running: fail fast for tools that require exclusivity.
+    if requires_no_tests:
+        tests = data.get("tests")
+        if isinstance(tests, dict) and tests.get("is_running") is True:
+            return _busy("tests_running", 5000)
+
+    # Compilation: optionally wait for a bounded time.
+    if wait_for_no_compile:
+        deadline = time.monotonic() + float(max_wait_s)
+        while True:
+            compilation = data.get("compilation") if isinstance(data, dict) else None
+            is_compiling = isinstance(compilation, dict) and compilation.get("is_compiling") is True
+            is_domain_reload_pending = isinstance(compilation, dict) and compilation.get("is_domain_reload_pending") is True
+            if not is_compiling and not is_domain_reload_pending:
+                break
+            if time.monotonic() >= deadline:
+                return _busy("compiling", 500)
+            await asyncio.sleep(0.25)
+
+            # Refresh state for the next loop iteration.
+            try:
+                from services.resources.editor_state_v2 import get_editor_state_v2
+                state_resp = await get_editor_state_v2(ctx)
+                state = state_resp.model_dump() if hasattr(state_resp, "model_dump") else state_resp
+                data = state.get("data") if isinstance(state, dict) else None
+                if not isinstance(data, dict):
+                    return None
+            except Exception:
+                return None
+
+    # Staleness: if the snapshot is stale, proceed (tools will still run), but callers that read resources can back off.
+    # In future we may make this strict for some tools.
+    return None
+
+

services/tools/read_console.py

@@ -45,8 +45,18 @@ async def read_console(
     if isinstance(action, str):
         action = action.lower()
 
-    # Coerce count defensively (string/float -> int)
-    count = coerce_int(count)
+    # Coerce count defensively (string/float -> int).
+    # Important: leaving count unset previously meant "return all console entries", which can be extremely slow
+    # (and can exceed the plugin command timeout when Unity has a large console).
+    # To keep the tool responsive by default, we cap the default to a reasonable number of most-recent entries.
+    # If a client truly wants everything, it can pass count="all" (or count="*") explicitly.
+    if isinstance(count, str) and count.strip().lower() in ("all", "*"):
+        count = None
+    else:
+        count = coerce_int(count)
+
+    if action == "get" and count is None:
+        count = 200
 
     # Prepare parameters for the C# handler
     params_dict = {

services/tools/refresh_unity.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+
+from models import MCPResponse
+from services.registry import mcp_for_unity_tool
+from services.tools import get_unity_instance_from_context
+import transport.unity_transport as unity_transport
+from transport.legacy.unity_connection import async_send_command_with_retry
+from services.state.external_changes_scanner import external_changes_scanner
+
+
+@mcp_for_unity_tool(
+    description="Request a Unity asset database refresh and optionally a script compilation. Can optionally wait for readiness."
+)
+async def refresh_unity(
+    ctx: Context,
+    mode: Annotated[Literal["if_dirty", "force"], "Refresh mode"] = "if_dirty",
+    scope: Annotated[Literal["assets", "scripts", "all"], "Refresh scope"] = "all",
+    compile: Annotated[Literal["none", "request"], "Whether to request compilation"] = "none",
+    wait_for_ready: Annotated[bool, "If true, wait until editor_state.advice.ready_for_tools is true"] = True,
+) -> MCPResponse | dict[str, Any]:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    params: dict[str, Any] = {
+        "mode": mode,
+        "scope": scope,
+        "compile": compile,
+        "wait_for_ready": bool(wait_for_ready),
+    }
+
+    recovered_from_disconnect = False
+    response = await unity_transport.send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "refresh_unity",
+        params,
+    )
+
+    # Option A: treat disconnects / retry hints as recoverable when wait_for_ready is true.
+    # Unity can legitimately disconnect during refresh/compile/domain reload, so callers should not
+    # interpret that as a hard failure (#503-style loops).
+    if isinstance(response, dict) and not response.get("success", True):
+        hint = response.get("hint")
+        err = (response.get("error") or response.get("message") or "")
+        is_retryable = (hint == "retry") or ("disconnected" in str(err).lower())
+        if (not wait_for_ready) or (not is_retryable):
+            return MCPResponse(**response)
+        recovered_from_disconnect = True
+
+    # Optional server-side wait loop (defensive): if Unity tool doesn't wait or returns quickly,
+    # poll the canonical editor_state v2 resource until ready or timeout.
+    if wait_for_ready:
+        timeout_s = 60.0
+        start = time.monotonic()
+        from services.resources.editor_state_v2 import get_editor_state_v2
+
+        while time.monotonic() - start < timeout_s:
+            state_resp = await get_editor_state_v2(ctx)
+            state = state_resp.model_dump() if hasattr(state_resp, "model_dump") else state_resp
+            data = (state or {}).get("data") if isinstance(state, dict) else None
+            advice = (data or {}).get("advice") if isinstance(data, dict) else None
+            if isinstance(advice, dict) and advice.get("ready_for_tools") is True:
+                break
+            await asyncio.sleep(0.25)
+
+    # After readiness is restored, clear any external-dirty flag for this instance so future tools can proceed cleanly.
+    try:
+        from services.resources.editor_state_v2 import _infer_single_instance_id
+
+        inst = unity_instance or await _infer_single_instance_id(ctx)
+        if inst:
+            external_changes_scanner.clear_dirty(inst)
+    except Exception:
+        pass
+
+    if recovered_from_disconnect:
+        return MCPResponse(
+            success=True,
+            message="Refresh recovered after Unity disconnect/retry; editor is ready.",
+            data={"recovered_from_disconnect": True},
+        )
+
+    return MCPResponse(**response) if isinstance(response, dict) else response
+
+

services/tools/run_tests.py

@@ -10,6 +10,7 @@ from services.tools import get_unity_instance_from_context
 from services.tools.utils import coerce_int
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
+from services.tools.preflight import preflight
 
 
 class RunTestsSummary(BaseModel):
@@ -34,7 +35,7 @@ class RunTestsTestResult(BaseModel):
 class RunTestsResult(BaseModel):
     mode: str
     summary: RunTestsSummary
-    results: list[RunTestsTestResult]
+    results: list[RunTestsTestResult] | None = None
 
 
 class RunTestsResponse(MCPResponse):
@@ -42,7 +43,7 @@ class RunTestsResponse(MCPResponse):
 
 
 @mcp_for_unity_tool(
-    description="Runs Unity tests for the specified mode"
+    description="Runs Unity tests synchronously (blocks until complete). Prefer run_tests_async for non-blocking execution with progress polling."
 )
 async def run_tests(
     ctx: Context,
@@ -52,9 +53,15 @@ async def run_tests(
     group_names: Annotated[list[str] | str, "Same as test_names, except it allows for Regex"] | None = None,
     category_names: Annotated[list[str] | str, "NUnit category names to filter by (tests marked with [Category] attribute)"] | None = None,
     assembly_names: Annotated[list[str] | str, "Assembly names to filter tests by"] | None = None,
-) -> RunTestsResponse:
+    include_failed_tests: Annotated[bool, "Include details for failed/skipped tests only (default: false)"] = False,
+    include_details: Annotated[bool, "Include details for all tests (default: false)"] = False,
+) -> RunTestsResponse | MCPResponse:
     unity_instance = get_unity_instance_from_context(ctx)
 
+    gate = await preflight(ctx, requires_no_tests=True, wait_for_no_compile=True, refresh_if_dirty=True)
+    if isinstance(gate, MCPResponse):
+        return gate
+
     # Coerce string or list to list of strings
     def _coerce_string_list(value) -> list[str] | None:
         if value is None:
@@ -88,6 +95,26 @@ async def run_tests(
     if assembly_names_list:
         params["assemblyNames"] = assembly_names_list
 
+    # Add verbosity parameters
+    if include_failed_tests:
+        params["includeFailedTests"] = True
+    if include_details:
+        params["includeDetails"] = True
+
     response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "run_tests", params)
-    await ctx.info(f'Response {response}')
+
+    # If Unity indicates a run is already active, return a structured "busy" response rather than
+    # letting clients interpret this as a generic failure (avoids #503 retry loops).
+    if isinstance(response, dict) and not response.get("success", True):
+        err = (response.get("error") or response.get("message") or "").strip()
+        if "test run is already in progress" in err.lower():
+            return MCPResponse(
+                success=False,
+                error="tests_running",
+                message=err,
+                hint="retry",
+                data={"reason": "tests_running", "retry_after_ms": 5000},
+            )
+        return MCPResponse(**response)
+
     return RunTestsResponse(**response) if isinstance(response, dict) else response

services/tools/test_jobs.py

@@ -0,0 +1,94 @@
+"""Async Unity Test Runner jobs: start + poll."""
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+
+from models import MCPResponse
+from services.registry import mcp_for_unity_tool
+from services.tools import get_unity_instance_from_context
+from services.tools.preflight import preflight
+import transport.unity_transport as unity_transport
+from transport.legacy.unity_connection import async_send_command_with_retry
+
+
+@mcp_for_unity_tool(description="Starts a Unity test run asynchronously and returns a job_id immediately. Preferred over run_tests for long-running suites. Poll with get_test_job for progress.")
+async def run_tests_async(
+    ctx: Context,
+    mode: Annotated[Literal["EditMode", "PlayMode"], "Unity test mode to run"] = "EditMode",
+    test_names: Annotated[list[str] | str, "Full names of specific tests to run"] | None = None,
+    group_names: Annotated[list[str] | str, "Same as test_names, except it allows for Regex"] | None = None,
+    category_names: Annotated[list[str] | str, "NUnit category names to filter by"] | None = None,
+    assembly_names: Annotated[list[str] | str, "Assembly names to filter tests by"] | None = None,
+    include_failed_tests: Annotated[bool, "Include details for failed/skipped tests only (default: false)"] = False,
+    include_details: Annotated[bool, "Include details for all tests (default: false)"] = False,
+) -> dict[str, Any] | MCPResponse:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    gate = await preflight(ctx, requires_no_tests=True, wait_for_no_compile=True, refresh_if_dirty=True)
+    if isinstance(gate, MCPResponse):
+        return gate
+
+    def _coerce_string_list(value) -> list[str] | None:
+        if value is None:
+            return None
+        if isinstance(value, str):
+            return [value] if value.strip() else None
+        if isinstance(value, list):
+            result = [str(v).strip() for v in value if v and str(v).strip()]
+            return result if result else None
+        return None
+
+    params: dict[str, Any] = {"mode": mode}
+    if (t := _coerce_string_list(test_names)):
+        params["testNames"] = t
+    if (g := _coerce_string_list(group_names)):
+        params["groupNames"] = g
+    if (c := _coerce_string_list(category_names)):
+        params["categoryNames"] = c
+    if (a := _coerce_string_list(assembly_names)):
+        params["assemblyNames"] = a
+    if include_failed_tests:
+        params["includeFailedTests"] = True
+    if include_details:
+        params["includeDetails"] = True
+
+    response = await unity_transport.send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "run_tests_async",
+        params,
+    )
+
+    if isinstance(response, dict) and not response.get("success", True):
+        return MCPResponse(**response)
+    return response if isinstance(response, dict) else MCPResponse(success=False, error=str(response)).model_dump()
+
+
+@mcp_for_unity_tool(description="Polls an async Unity test job by job_id.")
+async def get_test_job(
+    ctx: Context,
+    job_id: Annotated[str, "Job id returned by run_tests_async"],
+    include_failed_tests: Annotated[bool, "Include details for failed/skipped tests only (default: false)"] = False,
+    include_details: Annotated[bool, "Include details for all tests (default: false)"] = False,
+) -> dict[str, Any] | MCPResponse:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    params: dict[str, Any] = {"job_id": job_id}
+    if include_failed_tests:
+        params["includeFailedTests"] = True
+    if include_details:
+        params["includeDetails"] = True
+
+    response = await unity_transport.send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_test_job",
+        params,
+    )
+    if isinstance(response, dict) and not response.get("success", True):
+        return MCPResponse(**response)
+    return response if isinstance(response, dict) else MCPResponse(success=False, error=str(response)).model_dump()
+
+

transport/plugin_hub.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import os
 import time
 import uuid
 from typing import Any
@@ -12,6 +13,7 @@ from starlette.endpoints import WebSocketEndpoint
 from starlette.websockets import WebSocket
 
 from core.config import config
+from models.models import MCPResponse
 from transport.plugin_registry import PluginRegistry
 from transport.models import (
     WelcomeMessage,
@@ -28,6 +30,10 @@ from transport.models import (
 logger = logging.getLogger("mcp-for-unity-server")
 
 
+class PluginDisconnectedError(RuntimeError):
+    """Raised when a plugin WebSocket disconnects while commands are in flight."""
+
+
 class PluginHub(WebSocketEndpoint):
     """Manages persistent WebSocket connections to Unity plugins."""
 
@@ -35,10 +41,15 @@ class PluginHub(WebSocketEndpoint):
     KEEP_ALIVE_INTERVAL = 15
     SERVER_TIMEOUT = 30
     COMMAND_TIMEOUT = 30
+    # Fast-path commands should never block the client for long; return a retry hint instead.
+    # This helps avoid the Cursor-side ~30s tool-call timeout when Unity is compiling/reloading
+    # or is throttled while unfocused.
+    _FAST_FAIL_COMMANDS: set[str] = {"read_console", "get_editor_state", "ping"}
 
     _registry: PluginRegistry | None = None
     _connections: dict[str, WebSocket] = {}
-    _pending: dict[str, asyncio.Future] = {}
+    # command_id -> {"future": Future, "session_id": str}
+    _pending: dict[str, dict[str, Any]] = {}
     _lock: asyncio.Lock | None = None
     _loop: asyncio.AbstractEventLoop | None = None
 
@@ -95,6 +106,21 @@ class PluginHub(WebSocketEndpoint):
                 (sid for sid, ws in cls._connections.items() if ws is websocket), None)
             if session_id:
                 cls._connections.pop(session_id, None)
+                # Fail-fast any in-flight commands for this session to avoid waiting for COMMAND_TIMEOUT.
+                pending_ids = [
+                    command_id
+                    for command_id, entry in cls._pending.items()
+                    if entry.get("session_id") == session_id
+                ]
+                for command_id in pending_ids:
+                    entry = cls._pending.get(command_id)
+                    future = entry.get("future") if isinstance(entry, dict) else None
+                    if future and not future.done():
+                        future.set_exception(
+                            PluginDisconnectedError(
+                                f"Unity plugin session {session_id} disconnected while awaiting command_result"
+                            )
+                        )
                 if cls._registry:
                     await cls._registry.unregister(session_id)
                 logger.info(
@@ -108,6 +134,39 @@ class PluginHub(WebSocketEndpoint):
         websocket = await cls._get_connection(session_id)
         command_id = str(uuid.uuid4())
         future: asyncio.Future = asyncio.get_running_loop().create_future()
+        # Compute a per-command timeout:
+        # - fast-path commands: short timeout (encourage retry)
+        # - long-running commands (e.g., run_tests): allow caller to request a longer timeout via params
+        unity_timeout_s = float(cls.COMMAND_TIMEOUT)
+        server_wait_s = float(cls.COMMAND_TIMEOUT)
+        if command_type in cls._FAST_FAIL_COMMANDS:
+            try:
+                fast_timeout = float(os.environ.get("UNITY_MCP_FAST_COMMAND_TIMEOUT", "3"))
+            except Exception:
+                fast_timeout = 3.0
+            unity_timeout_s = fast_timeout
+            server_wait_s = fast_timeout
+        else:
+            # Common tools pass a requested timeout in seconds (e.g., run_tests(timeout_seconds=900)).
+            requested = None
+            try:
+                if isinstance(params, dict):
+                    requested = params.get("timeout_seconds", None)
+                    if requested is None:
+                        requested = params.get("timeoutSeconds", None)
+            except Exception:
+                requested = None
+
+            if requested is not None:
+                try:
+                    requested_s = float(requested)
+                    # Clamp to a sane upper bound to avoid accidental infinite hangs.
+                    requested_s = max(1.0, min(requested_s, 60.0 * 60.0))
+                    unity_timeout_s = max(unity_timeout_s, requested_s)
+                    # Give the server a small cushion beyond the Unity-side timeout to account for transport overhead.
+                    server_wait_s = max(server_wait_s, requested_s + 5.0)
+                except Exception:
+                    pass
 
         lock = cls._lock
         if lock is None:
@@ -117,18 +176,35 @@ class PluginHub(WebSocketEndpoint):
             if command_id in cls._pending:
                 raise RuntimeError(
                     f"Duplicate command id generated: {command_id}")
-            cls._pending[command_id] = future
+            cls._pending[command_id] = {"future": future, "session_id": session_id}
 
         try:
             msg = ExecuteCommandMessage(
                 id=command_id,
                 name=command_type,
                 params=params,
-                timeout=cls.COMMAND_TIMEOUT,
+                timeout=unity_timeout_s,
             )
-            await websocket.send_json(msg.model_dump())
-            result = await asyncio.wait_for(future, timeout=cls.COMMAND_TIMEOUT)
-            return result
+            try:
+                await websocket.send_json(msg.model_dump())
+            except Exception as exc:
+                # If send fails (socket already closing), fail the future so callers don't hang.
+                if not future.done():
+                    future.set_exception(exc)
+                raise
+            try:
+                result = await asyncio.wait_for(future, timeout=server_wait_s)
+                return result
+            except PluginDisconnectedError as exc:
+                return MCPResponse(success=False, error=str(exc), hint="retry").model_dump()
+            except asyncio.TimeoutError:
+                if command_type in cls._FAST_FAIL_COMMANDS:
+                    return MCPResponse(
+                        success=False,
+                        error=f"Unity did not respond to '{command_type}' within {server_wait_s:.1f}s; please retry",
+                        hint="retry",
+                    ).model_dump()
+                raise
         finally:
             async with lock:
                 cls._pending.pop(command_id, None)
@@ -245,7 +321,8 @@ class PluginHub(WebSocketEndpoint):
             return
 
         async with lock:
-            future = cls._pending.get(command_id)
+            entry = cls._pending.get(command_id)
+        future = entry.get("future") if isinstance(entry, dict) else None
         if future and not future.done():
             future.set_result(result)
 
@@ -364,6 +441,40 @@ class PluginHub(WebSocketEndpoint):
         params: dict[str, Any],
     ) -> dict[str, Any]:
         session_id = await cls._resolve_session_id(unity_instance)
+
+        # During domain reload / immediate reconnect windows, the plugin may be connected but not yet
+        # ready to process execute commands on the Unity main thread (which can be further delayed when
+        # the Unity Editor is unfocused). For fast-path commands, we do a bounded readiness probe using
+        # a main-thread ping command (handled by TransportCommandDispatcher) rather than waiting on
+        # register_tools (which can be delayed by EditorApplication.delayCall).
+        if command_type in cls._FAST_FAIL_COMMANDS and command_type != "ping":
+            try:
+                max_wait_s = float(os.environ.get("UNITY_MCP_SESSION_READY_WAIT_SECONDS", "6"))
+            except Exception:
+                max_wait_s = 6.0
+            max_wait_s = max(0.0, min(max_wait_s, 30.0))
+            if max_wait_s > 0:
+                deadline = time.monotonic() + max_wait_s
+                while time.monotonic() < deadline:
+                    try:
+                        probe = await cls.send_command(session_id, "ping", {})
+                    except Exception:
+                        probe = None
+
+                    # The Unity-side dispatcher responds with {status:"success", result:{message:"pong"}}
+                    if isinstance(probe, dict) and probe.get("status") == "success":
+                        result = probe.get("result") if isinstance(probe.get("result"), dict) else {}
+                        if result.get("message") == "pong":
+                            break
+                    await asyncio.sleep(0.1)
+                else:
+                    # Not ready within the bounded window: return retry hint without sending.
+                    return MCPResponse(
+                        success=False,
+                        error=f"Unity session not ready for '{command_type}' (ping not answered); please retry",
+                        hint="retry",
+                    ).model_dump()
+
         return await cls.send_command(session_id, command_type, params)
 
     # ------------------------------------------------------------------