feat: add command gateway for multi-agent concurrent access

MCPForUnity/Editor/Constants/EditorPrefKeys.cs

@@ -68,6 +68,8 @@ internal static class EditorPrefKeys
 
         internal const string AutoStartOnLoad = "MCPForUnity.AutoStartOnLoad";
         internal const string BatchExecuteMaxCommands = "MCPForUnity.BatchExecute.MaxCommands";
+        internal const string GatewayJobLogging = "MCPForUnity.Gateway.JobLogging";
+        internal const string GatewayJobLogPath = "MCPForUnity.Gateway.JobLogPath";
         internal const string LogRecordEnabled = "MCPForUnity.LogRecordEnabled";
 
         internal const string ExecuteCodeCompiler = "MCPForUnity.ExecuteCode.Compiler";

MCPForUnity/Editor/Helpers/AssetPathUtility.cs

@@ -107,6 +107,14 @@ public static string GetMcpPackageRootPath()
         {
             try
             {
+                // WSL workaround: when the package lives on a WSL UNC path and Unity
+                // runs on Windows, UXML/USS files cannot be parsed from the UNC path.
+                // UIAssetSync copies them to Assets/MCPForUnityUI/ on domain reload.
+                if (UIAssetSync.NeedsSync())
+                {
+                    return UIAssetSync.SyncedBasePath;
+                }
+
                 // Try Package Manager first (registry and local installs)
                 var packageInfo = PackageInfo.FindForAssembly(typeof(AssetPathUtility).Assembly);
                 if (packageInfo != null && !string.IsNullOrEmpty(packageInfo.assetPath))

MCPForUnity/Editor/Helpers/UIAssetSync.cs

@@ -0,0 +1,121 @@
+using UnityEditor;
+using UnityEngine;
+using System.IO;
+
+namespace MCPForUnity.Editor.Helpers
+{
+    /// <summary>
+    /// Automatically copies UXML and USS files from WSL package directories to a local
+    /// <c>Assets/MCPForUnityUI/</c> folder on every domain reload, preserving directory structure.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>Problem:</b> Unity's UXML/USS importer on Windows cannot properly parse files
+    /// when packages live on a WSL2 filesystem (UNC paths like <c>\\wsl$\...</c>). The
+    /// VisualTreeAsset loads but CloneTree produces an empty tree.
+    /// </para>
+    /// <para>
+    /// <b>Solution:</b> On startup, this class copies all UI asset files to
+    /// <c>Assets/MCPForUnityUI/</c> and <see cref="AssetPathUtility.GetMcpPackageRootPath"/>
+    /// returns this fallback path when WSL is detected.
+    /// </para>
+    /// </remarks>
+    [InitializeOnLoad]
+    static class UIAssetSync
+    {
+        /// <summary>Destination folder under the Unity project for synced UI assets.</summary>
+        internal const string SyncedBasePath = "Assets/MCPForUnityUI";
+
+        /// <summary>
+        /// Relative paths from package root to UXML and USS files that need syncing.
+        /// </summary>
+        private static readonly string[] k_UIAssetPaths =
+        {
+            "Editor/Windows/MCPForUnityEditorWindow.uxml",
+            "Editor/Windows/MCPForUnityEditorWindow.uss",
+            "Editor/Windows/MCPSetupWindow.uxml",
+            "Editor/Windows/MCPSetupWindow.uss",
+            "Editor/Windows/EditorPrefs/EditorPrefItem.uxml",
+            "Editor/Windows/EditorPrefs/EditorPrefsWindow.uxml",
+            "Editor/Windows/EditorPrefs/EditorPrefsWindow.uss",
+            "Editor/Windows/Components/Common.uss",
+            "Editor/Windows/Components/Connection/McpConnectionSection.uxml",
+            "Editor/Windows/Components/ClientConfig/McpClientConfigSection.uxml",
+            "Editor/Windows/Components/Validation/McpValidationSection.uxml",
+            "Editor/Windows/Components/Advanced/McpAdvancedSection.uxml",
+            "Editor/Windows/Components/Tools/McpToolsSection.uxml",
+            "Editor/Windows/Components/Resources/McpResourcesSection.uxml",
+            "Editor/Windows/Components/Queue/McpQueueSection.uxml",
+            "Editor/Windows/Components/Queue/McpQueueSection.uss",
+        };
+
+        static UIAssetSync()
+        {
+            if (!NeedsSync())
+                return;
+
+            string packageRoot = GetPackagePhysicalRoot();
+            if (string.IsNullOrEmpty(packageRoot))
+                return;
+
+            bool anyUpdated = false;
+
+            foreach (string relativePath in k_UIAssetPaths)
+            {
+                string sourcePath = Path.Combine(packageRoot, relativePath);
+                if (!File.Exists(sourcePath))
+                    continue;
+
+                string sourceContent = File.ReadAllText(sourcePath);
+
+                string destPath = Path.GetFullPath(Path.Combine(SyncedBasePath, relativePath));
+                string destDir = Path.GetDirectoryName(destPath);
+
+                if (!string.IsNullOrEmpty(destDir) && !Directory.Exists(destDir))
+                    Directory.CreateDirectory(destDir);
+
+                if (File.Exists(destPath) && File.ReadAllText(destPath) == sourceContent)
+                    continue;
+
+                File.WriteAllText(destPath, sourceContent);
+                Debug.Log($"[UIAssetSync] Updated {relativePath}");
+                anyUpdated = true;
+            }
+
+            if (anyUpdated)
+                AssetDatabase.Refresh();
+        }
+
+        /// <summary>
+        /// Returns true when the MCP package lives on a WSL UNC path and Unity runs on Windows.
+        /// </summary>
+        internal static bool NeedsSync()
+        {
+            if (Application.platform != RuntimePlatform.WindowsEditor)
+                return false;
+
+            string packageRoot = GetPackagePhysicalRoot();
+            if (string.IsNullOrEmpty(packageRoot))
+                return false;
+
+            return packageRoot.StartsWith(@"\\wsl", System.StringComparison.OrdinalIgnoreCase);
+        }
+
+        /// <summary>
+        /// Gets the physical (filesystem) root path of the MCP package.
+        /// </summary>
+        private static string GetPackagePhysicalRoot()
+        {
+            var packageInfo = UnityEditor.PackageManager.PackageInfo.FindForAssembly(
+                typeof(UIAssetSync).Assembly);
+            if (packageInfo != null && !string.IsNullOrEmpty(packageInfo.resolvedPath))
+                return packageInfo.resolvedPath;
+
+            // Fallback: resolve the virtual asset path
+            if (packageInfo != null && !string.IsNullOrEmpty(packageInfo.assetPath))
+                return Path.GetFullPath(packageInfo.assetPath);
+
+            return null;
+        }
+    }
+}

MCPForUnity/Editor/MenuItems/MCPForUnityMenu.cs

@@ -1,4 +1,5 @@
 using MCPForUnity.Editor.Setup;
+using MCPForUnity.Editor.Tools;
 using MCPForUnity.Editor.Windows;
 using UnityEditor;
 using UnityEngine;
@@ -26,11 +27,22 @@ public static void ShowSetupWindow()
             SetupWindowService.ShowSetupWindow();
         }
 
-
         [MenuItem("Window/MCP For Unity/Edit EditorPrefs", priority = 3)]
         public static void ShowEditorPrefsWindow()
         {
             EditorPrefsWindow.ShowWindow();
         }
+
+        /// <summary>
+        /// Emergency flush: cancels all queued/running MCP commands and clears stuck test jobs.
+        /// Use when the editor appears frozen due to a stuck MCP queue.
+        /// Shortcut: Ctrl+Shift+F5 (Cmd+Shift+F5 on Mac)
+        /// </summary>
+        [MenuItem("Window/MCP For Unity/Emergency Flush Queue %#&F5", priority = 100)]
+        public static void EmergencyFlushQueue()
+        {
+            CommandGatewayState.EmergencyFlush();
+            Debug.LogWarning("[MCP] Emergency flush completed. Queue cleared, stuck test jobs removed.");
+        }
     }
 }

MCPForUnity/Editor/Services/TestJobManager.cs

@@ -220,7 +220,7 @@ private static void TryRestoreFromSessionState()
                         if (currentJob.Status == TestJobStatus.Running)
                         {
                             long now = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
-                            long staleCutoffMs = 5 * 60 * 1000; // 5 minutes
+                            long staleCutoffMs = 60 * 1000; // 60 seconds
                             if (now - currentJob.LastUpdateUnixMs > staleCutoffMs)
                             {
                                 McpLog.Warn($"[TestJobManager] Clearing stale job {_currentJobId} (last update {(now - currentJob.LastUpdateUnixMs) / 1000}s ago)");

MCPForUnity/Editor/Services/Transport/TransportCommandDispatcher.cs

@@ -63,7 +63,20 @@ public void TrySetCanceled()
         }
 
         private static readonly Dictionary<string, PendingCommand> Pending = new();
+        /// <summary>
+        /// Maps command JSON content hash → pending ID for deduplication.
+        /// When a duplicate command arrives while an identical one is still pending,
+        /// the duplicate shares the original's TaskCompletionSource instead of queueing again.
+        /// </summary>
+        private static readonly Dictionary<string, string> ContentHashToPendingId = new();
         private static readonly object PendingLock = new();
+        /// <summary>
+        /// Maximum age of a pending command that is still eligible for dedup matching.
+        /// If the original command hangs (stuck gateway job, lost transport, etc.) waiters
+        /// must not pile up indefinitely on a dead TaskCompletionSource — after this
+        /// window, new identical commands create a fresh pending entry instead.
+        /// </summary>
+        private static readonly TimeSpan DedupTtl = TimeSpan.FromSeconds(60);
         private static bool updateHooked;
         private static bool initialised;
 
@@ -96,6 +109,50 @@ public static Task<string> ExecuteCommandJsonAsync(string commandJson, Cancellat
 
             EnsureInitialised();
 
+            // --- Deduplication: if an identical command is already pending, share its result ---
+            var contentHash = ComputeContentHash(commandJson);
+
+            lock (PendingLock)
+            {
+                if (contentHash != null
+                    && ContentHashToPendingId.TryGetValue(contentHash, out var existingId)
+                    && Pending.TryGetValue(existingId, out var existingPending)
+                    && !existingPending.CancellationToken.IsCancellationRequested
+                    && (DateTime.UtcNow - existingPending.QueuedAt) < DedupTtl)
+                {
+                    McpLog.Info($"[Dispatcher] Dedup: identical command already pending (id={existingId}). Sharing result.");
+                    // Propagate the NEW caller's cancellation into a linked waiter so each dedup
+                    // waiter can bail independently. Without this, a cancelled caller still blocks
+                    // on the original command's TCS — which is the root cause of stall-under-load.
+                    if (cancellationToken.CanBeCanceled)
+                    {
+                        var waiterTcs = new TaskCompletionSource<string>(TaskCreationOptions.RunContinuationsAsynchronously);
+                        var waiterReg = cancellationToken.Register(() => waiterTcs.TrySetCanceled(cancellationToken));
+                        existingPending.CompletionSource.Task.ContinueWith(t =>
+                        {
+                            waiterReg.Dispose();
+                            if (t.IsCanceled) waiterTcs.TrySetCanceled();
+                            else if (t.IsFaulted) waiterTcs.TrySetException(t.Exception!.InnerExceptions);
+                            else waiterTcs.TrySetResult(t.Result);
+                        }, TaskScheduler.Default);
+                        return waiterTcs.Task;
+                    }
+                    return existingPending.CompletionSource.Task;
+                }
+                // Stale dedup entry (TTL exceeded or cancelled original): drop the mapping
+                // so the code below creates a fresh PendingCommand instead of piling onto
+                // a dead TCS.
+                if (contentHash != null
+                    && ContentHashToPendingId.TryGetValue(contentHash, out var staleId)
+                    && Pending.TryGetValue(staleId, out var stalePending)
+                    && (stalePending.CancellationToken.IsCancellationRequested
+                        || (DateTime.UtcNow - stalePending.QueuedAt) >= DedupTtl))
+                {
+                    McpLog.Warn($"[Dispatcher] Dedup entry stale for id={staleId} (age={(DateTime.UtcNow - stalePending.QueuedAt).TotalSeconds:F0}s). Releasing hash for fresh dispatch.");
+                    ContentHashToPendingId.Remove(contentHash);
+                }
+            }
+
             var id = Guid.NewGuid().ToString("N");
             var tcs = new TaskCompletionSource<string>(TaskCreationOptions.RunContinuationsAsynchronously);
 
@@ -108,6 +165,8 @@ public static Task<string> ExecuteCommandJsonAsync(string commandJson, Cancellat
             lock (PendingLock)
             {
                 Pending[id] = pending;
+                if (contentHash != null)
+                    ContentHashToPendingId[contentHash] = id;
             }
 
             // Proactively wake up the main thread execution loop. This improves responsiveness
@@ -362,6 +421,54 @@ private static void ProcessCommand(string id, PendingCommand pending)
                 }
 
                 var logType = resourceMeta != null ? "resource" : toolMeta != null ? "tool" : "unknown";
+
+                // --- Tier-aware dispatch ---
+                var declaredTier = CommandRegistry.GetToolTier(command.type);
+                var effectiveTier = CommandClassifier.Classify(command.type, declaredTier, parameters);
+
+                if (effectiveTier != ExecutionTier.Instant)
+                {
+                    // Route Smooth/Heavy through the gateway queue for tier-aware scheduling,
+                    // heavy exclusivity, domain-reload guards, and CancellationToken support.
+                    var job = CommandGatewayState.Queue.SubmitSingle(command.type, parameters, "transport");
+                    var gatewaySw = McpLogRecord.IsEnabled ? System.Diagnostics.Stopwatch.StartNew() : null;
+
+                    async void AwaitGateway()
+                    {
+                        try
+                        {
+                            var gatewayResult = await CommandGatewayState.AwaitJob(job);
+                            gatewaySw?.Stop();
+                            if (gatewayResult is IMcpResponse mcpResp && !mcpResp.Success)
+                            {
+                                McpLogRecord.Log(command.type, parameters, logType, "ERROR", gatewaySw?.ElapsedMilliseconds ?? 0, (gatewayResult as ErrorResponse)?.Error);
+                                var errResponse = new { status = "error", result = gatewayResult, _queue = new { ticket = job.Ticket, tier = job.Tier.ToString().ToLowerInvariant(), queued = true } };
+                                pending.TrySetResult(JsonConvert.SerializeObject(errResponse));
+                            }
+                            else
+                            {
+                                McpLogRecord.Log(command.type, parameters, logType, "SUCCESS", gatewaySw?.ElapsedMilliseconds ?? 0, null);
+                                var okResponse = new { status = "success", result = gatewayResult, _queue = new { ticket = job.Ticket, tier = job.Tier.ToString().ToLowerInvariant(), queued = true } };
+                                pending.TrySetResult(JsonConvert.SerializeObject(okResponse));
+                            }
+                        }
+                        catch (Exception ex)
+                        {
+                            gatewaySw?.Stop();
+                            McpLogRecord.Log(command.type, parameters, logType, "ERROR", gatewaySw?.ElapsedMilliseconds ?? 0, ex.Message);
+                            pending.TrySetResult(SerializeError(ex.Message, command.type, ex.StackTrace));
+                        }
+                        finally
+                        {
+                            EditorApplication.delayCall += () => RemovePending(id, pending);
+                        }
+                    }
+
+                    AwaitGateway();
+                    return;
+                }
+
+                // --- Instant tier: execute directly (existing path) ---
                 var sw = McpLogRecord.IsEnabled ? System.Diagnostics.Stopwatch.StartNew() : null;
                 var result = CommandRegistry.ExecuteCommand(command.type, parameters, pending.CompletionSource);
 
@@ -412,8 +519,8 @@ private static void ProcessCommand(string id, PendingCommand pending)
                 }
                 McpLogRecord.Log(command.type, parameters, logType, syncLogStatus, sw?.ElapsedMilliseconds ?? 0, syncLogError);
 
-                var response = new { status = "success", result };
-                pending.TrySetResult(JsonConvert.SerializeObject(response));
+                var directResponse = new { status = "success", result };
+                pending.TrySetResult(JsonConvert.SerializeObject(directResponse));
                 RemovePending(id, pending);
             }
             catch (Exception ex)
@@ -431,6 +538,7 @@ private static void CancelPending(string id, CancellationToken token)
             {
                 if (Pending.Remove(id, out pending))
                 {
+                    CleanContentHash(id);
                     UnhookUpdateIfIdle();
                 }
             }
@@ -444,12 +552,48 @@ private static void RemovePending(string id, PendingCommand pending)
             lock (PendingLock)
             {
                 Pending.Remove(id);
+                CleanContentHash(id);
                 UnhookUpdateIfIdle();
             }
 
             pending.Dispose();
         }
 
+        /// <summary>
+        /// Remove the content hash entry that points to the given pending ID.
+        /// Must be called under PendingLock.
+        /// </summary>
+        private static void CleanContentHash(string pendingId)
+        {
+            string hashToRemove = null;
+            foreach (var kvp in ContentHashToPendingId)
+            {
+                if (kvp.Value == pendingId)
+                {
+                    hashToRemove = kvp.Key;
+                    break;
+                }
+            }
+            if (hashToRemove != null)
+                ContentHashToPendingId.Remove(hashToRemove);
+        }
+
+        /// <summary>
+        /// Compute a stable content hash for command deduplication.
+        /// Returns null for non-JSON commands (e.g., "ping") which are cheap enough to not need dedup.
+        /// </summary>
+        private static string ComputeContentHash(string commandJson)
+        {
+            if (string.IsNullOrWhiteSpace(commandJson)) return null;
+            var trimmed = commandJson.Trim();
+            if (!trimmed.StartsWith("{")) return null; // Skip non-JSON (ping, etc.)
+
+            // Use the raw JSON string as the hash key. Retries from the same client produce
+            // byte-identical JSON, so this is both fast and correct for the dedup use case.
+            // For very large payloads, a proper hash could be used, but MCP commands are small.
+            return trimmed;
+        }
+
         private static string SerializeError(string message, string commandType = null, string stackTrace = null)
         {
             var errorResponse = new