mcpforunityserver 9.3.0b20260129121506__py3-none-any.whl → 9.3.0b20260131004250__py3-none-any.whl

services/resources/tests.py

@@ -4,6 +4,7 @@ from pydantic import BaseModel, Field
 from fastmcp import Context
 
 from models import MCPResponse
+from models.unity_response import parse_resource_response
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
@@ -53,7 +54,7 @@ async def get_tests(ctx: Context) -> GetTestsResponse | MCPResponse:
         "get_tests",
         {},
     )
-    return GetTestsResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, GetTestsResponse)
 
 
 @mcp_for_unity_resource(
@@ -84,4 +85,4 @@ async def get_tests_for_mode(
         "get_tests_for_mode",
         {"mode": mode},
     )
-    return GetTestsResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, GetTestsResponse)

services/resources/unity_instances.py

@@ -7,7 +7,7 @@ from fastmcp import Context
 from services.registry import mcp_for_unity_resource
 from transport.legacy.unity_connection import get_unity_connection_pool
 from transport.plugin_hub import PluginHub
-from transport.unity_transport import _current_transport
+from core.config import config
 
 
 @mcp_for_unity_resource(
@@ -36,10 +36,13 @@ async def unity_instances(ctx: Context) -> dict[str, Any]:
     await ctx.info("Listing Unity instances")
 
     try:
-        transport = _current_transport()
+        transport = (config.transport_mode or "stdio").lower()
         if transport == "http":
             # HTTP/WebSocket transport: query PluginHub
-            sessions_data = await PluginHub.get_sessions()
+            # In remote-hosted mode, filter sessions by user_id
+            user_id = ctx.get_state(
+                "user_id") if config.http_remote_hosted else None
+            sessions_data = await PluginHub.get_sessions(user_id=user_id)
             sessions = sessions_data.sessions
 
             instances = []

services/resources/windows.py

@@ -2,6 +2,7 @@ from pydantic import BaseModel
 from fastmcp import Context
 
 from models import MCPResponse
+from models.unity_response import parse_resource_response
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
 from transport.unity_transport import send_with_unity_instance
@@ -44,4 +45,4 @@ async def get_windows(ctx: Context) -> WindowsResponse | MCPResponse:
         "get_windows",
         {}
     )
-    return WindowsResponse(**response) if isinstance(response, dict) else response
+    return parse_resource_response(response, WindowsResponse)

services/tools/set_active_instance.py

@@ -8,7 +8,7 @@ from services.registry import mcp_for_unity_tool
 from transport.legacy.unity_connection import get_unity_connection_pool
 from transport.unity_instance_middleware import get_unity_instance_middleware
 from transport.plugin_hub import PluginHub
-from transport.unity_transport import _current_transport
+from core.config import config
 
 
 @mcp_for_unity_tool(
@@ -21,11 +21,14 @@ async def set_active_instance(
         ctx: Context,
         instance: Annotated[str, "Target instance (Name@hash or hash prefix)"]
 ) -> dict[str, Any]:
-    transport = _current_transport()
+    transport = (config.transport_mode or "stdio").lower()
 
     # Discover running instances based on transport
     if transport == "http":
-        sessions_data = await PluginHub.get_sessions()
+        # In remote-hosted mode, filter sessions by user_id
+        user_id = ctx.get_state(
+            "user_id") if config.http_remote_hosted else None
+        sessions_data = await PluginHub.get_sessions(user_id=user_id)
         sessions = sessions_data.sessions
         instances = []
         for session_id, session in sessions.items():

transport/legacy/unity_connection.py

@@ -306,8 +306,10 @@ class UnityConnection:
         for attempt in range(attempts + 1):
             try:
                 # Ensure connected (handshake occurs within connect())
+                t_conn_start = time.time()
                 if not self.sock and not self.connect():
                     raise ConnectionError("Could not connect to Unity")
+                logger.info("[TIMING-STDIO] connect took %.3fs command=%s", time.time() - t_conn_start, command_type)
 
                 # Build payload
                 if command_type == 'ping':
@@ -324,12 +326,14 @@ class UnityConnection:
                     with contextlib.suppress(Exception):
                         logger.debug(
                             f"send {len(payload)} bytes; mode={mode}; head={payload[:32].decode('utf-8', 'ignore')}")
+                    t_send_start = time.time()
                     if self.use_framing:
                         header = struct.pack('>Q', len(payload))
                         self.sock.sendall(header)
                         self.sock.sendall(payload)
                     else:
                         self.sock.sendall(payload)
+                    logger.info("[TIMING-STDIO] sendall took %.3fs command=%s", time.time() - t_send_start, command_type)
 
                     # During retry bursts use a short receive timeout and ensure restoration
                     restore_timeout = None
@@ -337,7 +341,9 @@ class UnityConnection:
                         restore_timeout = self.sock.gettimeout()
                         self.sock.settimeout(1.0)
                     try:
+                        t_recv_start = time.time()
                         response_data = self.receive_full_response(self.sock)
+                        logger.info("[TIMING-STDIO] receive took %.3fs command=%s len=%d", time.time() - t_recv_start, command_type, len(response_data))
                         with contextlib.suppress(Exception):
                             logger.debug(
                                 f"recv {len(response_data)} bytes; mode={mode}")
@@ -419,7 +425,8 @@ class UnityConnection:
 
                     # Cap backoff depending on state
                     if status and status.get('reloading'):
-                        cap = 0.8
+                        # Domain reload can take 10-20s; use longer waits
+                        cap = 5.0
                     elif fast_error:
                         cap = 0.25
                     else:
@@ -761,22 +768,36 @@ def send_command_with_retry(
     Uses config.reload_retry_ms and config.reload_max_retries by default. Preserves the
     structured failure if retries are exhausted.
     """
+    t_retry_start = time.time()
+    logger.info("[TIMING-STDIO] send_command_with_retry START command=%s", command_type)
+    t_get_conn = time.time()
     conn = get_unity_connection(instance_id)
+    logger.info("[TIMING-STDIO] get_unity_connection took %.3fs command=%s", time.time() - t_get_conn, command_type)
     if max_retries is None:
         max_retries = getattr(config, "reload_max_retries", 40)
     if retry_ms is None:
         retry_ms = getattr(config, "reload_retry_ms", 250)
+    # Default to 20s to handle domain reloads (which can take 10-20s after tests or script changes).
+    #
+    # NOTE: This wait can impact agentic workflows where domain reloads happen
+    # frequently (e.g., after test runs, script compilation). The 20s default
+    # balances handling slow reloads vs. avoiding unnecessary delays.
+    #
+    # TODO: Make this more deterministic by detecting Unity's actual reload state
+    # rather than blindly waiting up to 20s. See Issue #657.
+    #
+    # Configurable via: UNITY_MCP_RELOAD_MAX_WAIT_S (default: 20.0, max: 20.0)
     try:
         max_wait_s = float(os.environ.get(
-            "UNITY_MCP_RELOAD_MAX_WAIT_S", "2.0"))
+            "UNITY_MCP_RELOAD_MAX_WAIT_S", "20.0"))
     except ValueError as e:
-        raw_val = os.environ.get("UNITY_MCP_RELOAD_MAX_WAIT_S", "2.0")
+        raw_val = os.environ.get("UNITY_MCP_RELOAD_MAX_WAIT_S", "20.0")
         logger.warning(
-            "Invalid UNITY_MCP_RELOAD_MAX_WAIT_S=%r, using default 2.0: %s",
+            "Invalid UNITY_MCP_RELOAD_MAX_WAIT_S=%r, using default 20.0: %s",
             raw_val, e)
-        max_wait_s = 2.0
-    # Clamp to [0, 30] to prevent misconfiguration from causing excessive waits
-    max_wait_s = max(0.0, min(max_wait_s, 30.0))
+        max_wait_s = 20.0
+    # Clamp to [0, 20] to prevent misconfiguration from causing excessive waits
+    max_wait_s = max(0.0, min(max_wait_s, 20.0))
 
     # If retry_on_reload=False, disable connection-level retries too (issue #577)
     # Commands that trigger compilation/reload shouldn't retry on disconnect
@@ -847,6 +868,7 @@ def send_command_with_retry(
             instance_id or "default",
             waited,
         )
+    logger.info("[TIMING-STDIO] send_command_with_retry DONE total=%.3fs command=%s", time.time() - t_retry_start, command_type)
     return response
 
 

transport/models.py

@@ -23,6 +23,11 @@ class ExecuteCommandMessage(BaseModel):
     params: dict[str, Any]
     timeout: float
 
+
+class PingMessage(BaseModel):
+    """Server-initiated ping to detect dead connections."""
+    type: str = "ping"
+
 # Incoming (Plugin -> Server)
 
 

transport/plugin_hub.py

@@ -7,18 +7,21 @@ import logging
 import os
 import time
 import uuid
-from typing import Any
+from typing import Any, ClassVar
 
 from starlette.endpoints import WebSocketEndpoint
 from starlette.websockets import WebSocket
 
 from core.config import config
+from core.constants import API_KEY_HEADER
 from models.models import MCPResponse
 from transport.plugin_registry import PluginRegistry
+from services.api_key_service import ApiKeyService
 from transport.models import (
     WelcomeMessage,
     RegisteredMessage,
     ExecuteCommandMessage,
+    PingMessage,
     RegisterMessage,
     RegisterToolsMessage,
     PongMessage,
@@ -27,7 +30,7 @@ from transport.models import (
     SessionDetails,
 )
 
-logger = logging.getLogger("mcp-for-unity-server")
+logger = logging.getLogger(__name__)
 
 
 class PluginDisconnectedError(RuntimeError):
@@ -38,6 +41,22 @@ class NoUnitySessionError(RuntimeError):
     """Raised when no Unity plugins are available."""
 
 
+class InstanceSelectionRequiredError(RuntimeError):
+    """Raised when the caller must explicitly select a Unity instance."""
+
+    _SELECTION_REQUIRED = (
+        "Unity instance selection is required. "
+        "Call set_active_instance with Name@hash from mcpforunity://instances."
+    )
+    _MULTIPLE_INSTANCES = (
+        "Multiple Unity instances are connected. "
+        "Call set_active_instance with Name@hash from mcpforunity://instances."
+    )
+
+    def __init__(self, message: str | None = None):
+        super().__init__(message or self._SELECTION_REQUIRED)
+
+
 class PluginHub(WebSocketEndpoint):
     """Manages persistent WebSocket connections to Unity plugins."""
 
@@ -45,6 +64,10 @@ class PluginHub(WebSocketEndpoint):
     KEEP_ALIVE_INTERVAL = 15
     SERVER_TIMEOUT = 30
     COMMAND_TIMEOUT = 30
+    # Server-side ping interval (seconds) - how often to send pings to Unity
+    PING_INTERVAL = 10
+    # Max time (seconds) to wait for pong before considering connection dead
+    PING_TIMEOUT = 20
     # Timeout (seconds) for fast-fail commands like ping/read_console/get_editor_state.
     # Keep short so MCP clients aren't blocked during Unity compilation/reload/unfocused throttling.
     FAST_FAIL_TIMEOUT = 2.0
@@ -60,6 +83,10 @@ class PluginHub(WebSocketEndpoint):
     _pending: dict[str, dict[str, Any]] = {}
     _lock: asyncio.Lock | None = None
     _loop: asyncio.AbstractEventLoop | None = None
+    # session_id -> last pong timestamp (monotonic)
+    _last_pong: ClassVar[dict[str, float]] = {}
+    # session_id -> ping task
+    _ping_tasks: ClassVar[dict[str, asyncio.Task]] = {}
 
     @classmethod
     def configure(
@@ -77,6 +104,50 @@ class PluginHub(WebSocketEndpoint):
         return cls._registry is not None and cls._lock is not None
 
     async def on_connect(self, websocket: WebSocket) -> None:
+        # Validate API key in remote-hosted mode (fail closed)
+        if config.http_remote_hosted:
+            if not ApiKeyService.is_initialized():
+                logger.debug(
+                    "WebSocket connection rejected: auth service not initialized")
+                await websocket.close(code=1013, reason="Try again later")
+                return
+
+            api_key = websocket.headers.get(API_KEY_HEADER)
+
+            if not api_key:
+                logger.debug("WebSocket connection rejected: API key required")
+                await websocket.close(code=4401, reason="API key required")
+                return
+
+            service = ApiKeyService.get_instance()
+            result = await service.validate(api_key)
+
+            if not result.valid:
+                # Transient auth failures are retryable (1013)
+                if result.error and any(
+                    indicator in result.error.lower()
+                    for indicator in ("unavailable", "timeout", "service error")
+                ):
+                    logger.debug(
+                        "WebSocket connection rejected: auth service unavailable")
+                    await websocket.close(code=1013, reason="Try again later")
+                    return
+
+                logger.debug("WebSocket connection rejected: invalid API key")
+                await websocket.close(code=4403, reason="Invalid API key")
+                return
+
+            # Both valid and user_id must be present to accept
+            if not result.user_id:
+                logger.debug(
+                    "WebSocket connection rejected: validated key missing user_id")
+                await websocket.close(code=4403, reason="Invalid API key")
+                return
+
+            # Store user_id in websocket state for later use during registration
+            websocket.state.user_id = result.user_id
+            websocket.state.api_key_metadata = result.metadata
+
         await websocket.accept()
         msg = WelcomeMessage(
             serverTimeout=self.SERVER_TIMEOUT,
@@ -114,12 +185,20 @@ 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)
+                # Stop the ping loop for this session
+                ping_task = cls._ping_tasks.pop(session_id, None)
+                if ping_task and not ping_task.done():
+                    ping_task.cancel()
+                # Clean up last pong tracking
+                cls._last_pong.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
                 ]
+                if pending_ids:
+                    logger.debug(f"Cancelling {len(pending_ids)} pending commands for disconnected session")
                 for command_id in pending_ids:
                     entry = cls._pending.get(command_id)
                     future = entry.get("future") if isinstance(
@@ -217,10 +296,15 @@ class PluginHub(WebSocketEndpoint):
                 cls._pending.pop(command_id, None)
 
     @classmethod
-    async def get_sessions(cls) -> SessionList:
+    async def get_sessions(cls, user_id: str | None = None) -> SessionList:
+        """Get all active plugin sessions.
+
+        Args:
+            user_id: If provided (remote-hosted mode), only return sessions for this user.
+        """
         if cls._registry is None:
             return SessionList(sessions={})
-        sessions = await cls._registry.list_sessions()
+        sessions = await cls._registry.list_sessions(user_id=user_id)
         return SessionList(
             sessions={
                 session_id: SessionDetails(
@@ -286,15 +370,31 @@ class PluginHub(WebSocketEndpoint):
             raise ValueError(
                 "Plugin registration missing project_hash")
 
+        # Get user_id from websocket state (set during API key validation)
+        user_id = getattr(websocket.state, "user_id", None)
+
         session_id = str(uuid.uuid4())
         # Inform the plugin of its assigned session ID
         response = RegisteredMessage(session_id=session_id)
         await websocket.send_json(response.model_dump())
 
-        session = await registry.register(session_id, project_name, project_hash, unity_version, project_path)
+        session = await registry.register(session_id, project_name, project_hash, unity_version, project_path, user_id=user_id)
         async with lock:
             cls._connections[session.session_id] = websocket
-        logger.info(f"Plugin registered: {project_name} ({project_hash})")
+            # Initialize last pong time and start ping loop for this session
+            cls._last_pong[session_id] = time.monotonic()
+            # Cancel any existing ping task for this session (shouldn't happen, but be safe)
+            old_task = cls._ping_tasks.pop(session_id, None)
+            if old_task and not old_task.done():
+                old_task.cancel()
+            # Start the server-side ping loop
+            ping_task = asyncio.create_task(cls._ping_loop(session_id, websocket))
+            cls._ping_tasks[session_id] = ping_task
+
+        if user_id:
+            logger.info(f"Plugin registered: {project_name} ({project_hash}) for user {user_id}")
+        else:
+            logger.info(f"Plugin registered: {project_name} ({project_hash})")
 
     async def _handle_register_tools(self, websocket: WebSocket, payload: RegisterToolsMessage) -> None:
         cls = type(self)
@@ -354,11 +454,77 @@ class PluginHub(WebSocketEndpoint):
     async def _handle_pong(self, payload: PongMessage) -> None:
         cls = type(self)
         registry = cls._registry
+        lock = cls._lock
         if registry is None:
             return
         session_id = payload.session_id
         if session_id:
             await registry.touch(session_id)
+            # Record last pong time for staleness detection (under lock for consistency)
+            if lock is not None:
+                async with lock:
+                    cls._last_pong[session_id] = time.monotonic()
+
+    @classmethod
+    async def _ping_loop(cls, session_id: str, websocket: WebSocket) -> None:
+        """Server-initiated ping loop to detect dead connections.
+
+        Sends periodic pings to the Unity client. If no pong is received within
+        PING_TIMEOUT seconds, the connection is considered dead and closed.
+        This helps detect connections that die silently (e.g., Windows OSError 64).
+        """
+        logger.debug(f"[Ping] Starting ping loop for session {session_id}")
+        try:
+            while True:
+                await asyncio.sleep(cls.PING_INTERVAL)
+
+                # Check if we're still supposed to be running and get last pong time (under lock)
+                lock = cls._lock
+                if lock is None:
+                    break
+                async with lock:
+                    if session_id not in cls._connections:
+                        logger.debug(f"[Ping] Session {session_id} no longer in connections, stopping ping loop")
+                        break
+                    # Read last pong time under lock for consistency
+                    last_pong = cls._last_pong.get(session_id, 0)
+
+                # Check staleness: has it been too long since we got a pong?
+                elapsed = time.monotonic() - last_pong
+                if elapsed > cls.PING_TIMEOUT:
+                    logger.warning(
+                        f"[Ping] Session {session_id} stale: no pong for {elapsed:.1f}s "
+                        f"(timeout={cls.PING_TIMEOUT}s). Closing connection."
+                    )
+                    try:
+                        await websocket.close(code=1001)  # Going away
+                    except Exception as close_ex:
+                        logger.debug(f"[Ping] Error closing stale websocket: {close_ex}")
+                    break
+
+                # Send a ping to the client
+                try:
+                    ping_msg = PingMessage()
+                    await websocket.send_json(ping_msg.model_dump())
+                    logger.debug(f"[Ping] Sent ping to session {session_id}")
+                except Exception as send_ex:
+                    # Send failed - connection is dead
+                    logger.warning(
+                        f"[Ping] Failed to send ping to session {session_id}: {send_ex}. "
+                        "Connection likely dead."
+                    )
+                    try:
+                        await websocket.close(code=1006)  # Abnormal closure
+                    except Exception:
+                        pass
+                    break
+
+        except asyncio.CancelledError:
+            logger.debug(f"[Ping] Ping loop cancelled for session {session_id}")
+        except Exception as ex:
+            logger.warning(f"[Ping] Ping loop error for session {session_id}: {ex}")
+        finally:
+            logger.debug(f"[Ping] Ping loop ended for session {session_id}")
 
     @classmethod
     async def _get_connection(cls, session_id: str) -> WebSocket:
@@ -375,30 +541,45 @@ class PluginHub(WebSocketEndpoint):
     # Session resolution helpers
     # ------------------------------------------------------------------
     @classmethod
-    async def _resolve_session_id(cls, unity_instance: str | None) -> str:
+    async def _resolve_session_id(cls, unity_instance: str | None, user_id: str | None = None) -> str:
         """Resolve a project hash (Unity instance id) to an active plugin session.
 
         During Unity domain reloads the plugin's WebSocket session is torn down
         and reconnected shortly afterwards. Instead of failing immediately when
         no sessions are available, we wait for a bounded period for a plugin
         to reconnect so in-flight MCP calls can succeed transparently.
+
+        Args:
+            unity_instance: Target instance (Name@hash or hash)
+            user_id: User ID from API key validation (for remote-hosted mode session isolation)
         """
         if cls._registry is None:
             raise RuntimeError("Plugin registry not configured")
 
-        # Bound waiting for Unity sessions so calls fail fast when editors are not ready.
+        # Bound waiting for Unity sessions. Default to 20s to handle domain reloads
+        # (which can take 10-20s after test runs or script changes).
+        #
+        # NOTE: This wait can impact agentic workflows where domain reloads happen
+        # frequently (e.g., after test runs, script compilation). The 20s default
+        # balances handling slow reloads vs. avoiding unnecessary delays.
+        #
+        # TODO: Make this more deterministic by detecting Unity's actual reload state
+        # (e.g., via status file, heartbeat, or explicit "reloading" signal from Unity)
+        # rather than blindly waiting up to 20s. See Issue #657.
+        #
+        # Configurable via: UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S (default: 20.0, max: 20.0)
         try:
             max_wait_s = float(
-                os.environ.get("UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S", "2.0"))
+                os.environ.get("UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S", "20.0"))
         except ValueError as e:
             raw_val = os.environ.get(
-                "UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S", "2.0")
+                "UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S", "20.0")
             logger.warning(
-                "Invalid UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S=%r, using default 2.0: %s",
+                "Invalid UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S=%r, using default 20.0: %s",
                 raw_val, e)
-            max_wait_s = 2.0
-        # Clamp to [0, 30] to prevent misconfiguration from causing excessive waits
-        max_wait_s = max(0.0, min(max_wait_s, 30.0))
+            max_wait_s = 20.0
+        # Clamp to [0, 20] to prevent misconfiguration from causing excessive waits
+        max_wait_s = max(0.0, min(max_wait_s, 20.0))
         retry_ms = float(getattr(config, "reload_retry_ms", 250))
         sleep_seconds = max(0.05, min(0.25, retry_ms / 1000.0))
 
@@ -411,24 +592,35 @@ class PluginHub(WebSocketEndpoint):
             else:
                 target_hash = unity_instance
 
-        async def _try_once() -> tuple[str | None, int]:
+        async def _try_once() -> tuple[str | None, int, bool]:
+            explicit_required = config.http_remote_hosted
             # Prefer a specific Unity instance if one was requested
             if target_hash:
-                session_id = await cls._registry.get_session_id_by_hash(target_hash)
-                sessions = await cls._registry.list_sessions()
-                return session_id, len(sessions)
+                # In remote-hosted mode with user_id, use user-scoped lookup
+                if config.http_remote_hosted and user_id:
+                    session_id = await cls._registry.get_session_id_by_hash(target_hash, user_id)
+                    sessions = await cls._registry.list_sessions(user_id=user_id)
+                else:
+                    session_id = await cls._registry.get_session_id_by_hash(target_hash)
+                    sessions = await cls._registry.list_sessions(user_id=user_id)
+                return session_id, len(sessions), explicit_required
 
             # No target provided: determine if we can auto-select
-            sessions = await cls._registry.list_sessions()
+            # In remote-hosted mode, filter sessions by user_id
+            sessions = await cls._registry.list_sessions(user_id=user_id)
             count = len(sessions)
             if count == 0:
-                return None, count
+                return None, count, explicit_required
+            if explicit_required:
+                return None, count, explicit_required
             if count == 1:
-                return next(iter(sessions.keys())), count
+                return next(iter(sessions.keys())), count, explicit_required
             # Multiple sessions but no explicit target is ambiguous
-            return None, count
+            return None, count, explicit_required
 
-        session_id, session_count = await _try_once()
+        session_id, session_count, explicit_required = await _try_once()
+        if session_id is None and explicit_required and not target_hash and session_count > 0:
+            raise InstanceSelectionRequiredError()
         deadline = time.monotonic() + max_wait_s
         wait_started = None
 
@@ -436,10 +628,10 @@ class PluginHub(WebSocketEndpoint):
         # wait politely for a session to appear before surfacing an error.
         while session_id is None and time.monotonic() < deadline:
             if not target_hash and session_count > 1:
-                raise RuntimeError(
-                    "Multiple Unity instances are connected. "
-                    "Call set_active_instance with Name@hash from mcpforunity://instances."
-                )
+                raise InstanceSelectionRequiredError(
+                    InstanceSelectionRequiredError._MULTIPLE_INSTANCES)
+            if session_id is None and explicit_required and not target_hash and session_count > 0:
+                raise InstanceSelectionRequiredError()
             if wait_started is None:
                 wait_started = time.monotonic()
                 logger.debug(
@@ -448,7 +640,7 @@ class PluginHub(WebSocketEndpoint):
                     max_wait_s,
                 )
             await asyncio.sleep(sleep_seconds)
-            session_id, session_count = await _try_once()
+            session_id, session_count, explicit_required = await _try_once()
 
         if session_id is not None and wait_started is not None:
             logger.debug(
@@ -457,10 +649,11 @@ class PluginHub(WebSocketEndpoint):
                 unity_instance or "default",
             )
         if session_id is None and not target_hash and session_count > 1:
-            raise RuntimeError(
-                "Multiple Unity instances are connected. "
-                "Call set_active_instance with Name@hash from mcpforunity://instances."
-            )
+            raise InstanceSelectionRequiredError(
+                InstanceSelectionRequiredError._MULTIPLE_INSTANCES)
+
+        if session_id is None and explicit_required and not target_hash and session_count > 0:
+            raise InstanceSelectionRequiredError()
 
         if session_id is None:
             logger.warning(
@@ -481,9 +674,18 @@ class PluginHub(WebSocketEndpoint):
         unity_instance: str | None,
         command_type: str,
         params: dict[str, Any],
+        user_id: str | None = None,
     ) -> dict[str, Any]:
+        """Send a command to a Unity instance.
+
+        Args:
+            unity_instance: Target instance (Name@hash or hash)
+            command_type: Command type to execute
+            params: Command parameters
+            user_id: User ID for session isolation in remote-hosted mode
+        """
         try:
-            session_id = await cls._resolve_session_id(unity_instance)
+            session_id = await cls._resolve_session_id(unity_instance, user_id=user_id)
         except NoUnitySessionError:
             logger.debug(
                 "Unity session unavailable; returning retry: command=%s instance=%s",
@@ -513,7 +715,7 @@ class PluginHub(WebSocketEndpoint):
                     "Invalid UNITY_MCP_SESSION_READY_WAIT_SECONDS=%r, using default 6.0: %s",
                     raw_val, e)
                 max_wait_s = 6.0
-            max_wait_s = max(0.0, min(max_wait_s, 30.0))
+            max_wait_s = max(0.0, min(max_wait_s, 20.0))
             if max_wait_s > 0:
                 deadline = time.monotonic() + max_wait_s
                 while time.monotonic() < deadline: