feat: add command gateway for multi-agent concurrent access

MCPForUnity/Editor/Constants/EditorPrefKeys.cs

@@ -66,5 +66,7 @@ internal static class EditorPrefKeys
         internal const string ApiKey = "MCPForUnity.ApiKey";
 
         internal const string BatchExecuteMaxCommands = "MCPForUnity.BatchExecute.MaxCommands";
+        internal const string GatewayJobLogging = "MCPForUnity.Gateway.JobLogging";
+        internal const string GatewayJobLogPath = "MCPForUnity.Gateway.JobLogPath";
     }
 }

MCPForUnity/Editor/Helpers/AssetPathUtility.cs

@@ -103,6 +103,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/Tools/BatchExecute.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Threading.Tasks;
 using MCPForUnity.Editor.Constants;
 using MCPForUnity.Editor.Helpers;
@@ -51,6 +52,14 @@ public static async Task<object> HandleCommand(JObject @params)
                     $"A maximum of {maxCommands} commands are allowed per batch (configurable in MCP Tools window, hard max {AbsoluteMaxCommandsPerBatch}).");
             }
 
+            // --- Async gateway path ---
+            bool isAsync = @params.Value<bool?>("async") ?? false;
+            if (isAsync)
+            {
+                return HandleAsyncSubmit(@params, commandsToken);
+            }
+
+            // --- Legacy synchronous path (unchanged) ---
             bool failFast = @params.Value<bool?>("failFast") ?? false;
             bool parallelRequested = @params.Value<bool?>("parallel") ?? false;
             int? maxParallel = @params.Value<int?>("maxParallelism");
@@ -231,5 +240,84 @@ private static JObject NormalizeParameterKeys(JObject source)
         }
 
         private static string ToCamelCase(string key) => StringCaseUtility.ToCamelCase(key);
+
+        /// <summary>
+        /// Handle async batch submission. Queues commands via CommandGateway and returns
+        /// a ticket (for non-instant batches) or results inline (for instant batches).
+        /// </summary>
+        private static object HandleAsyncSubmit(JObject @params, JArray commandsToken)
+        {
+            bool atomic = @params.Value<bool?>("atomic") ?? false;
+            string agent = @params.Value<string>("agent") ?? "anonymous";
+            string label = @params.Value<string>("label") ?? "";
+
+            var commands = new List<BatchCommand>();
+            foreach (var token in commandsToken)
+            {
+                if (token is not JObject cmdObj) continue;
+                string toolName = cmdObj["tool"]?.ToString();
+                if (string.IsNullOrWhiteSpace(toolName)) continue;
+
+                var rawParams = cmdObj["params"] as JObject ?? new JObject();
+                var cmdParams = NormalizeParameterKeys(rawParams);
+
+                var toolTier = CommandRegistry.GetToolTier(toolName);
+                var effectiveTier = CommandClassifier.Classify(toolName, toolTier, cmdParams);
+
+                commands.Add(new BatchCommand { Tool = toolName, Params = cmdParams, Tier = effectiveTier, CausesDomainReload = CommandClassifier.CausesDomainReload(toolName, cmdParams) });
+            }
+
+            if (commands.Count == 0)
+            {
+                return new ErrorResponse("No valid commands in async batch.");
+            }
+
+            var job = CommandGatewayState.Queue.Submit(agent, label, atomic, commands);
+
+            if (job.Tier == ExecutionTier.Instant)
+            {
+                // Execute inline, return results directly
+                foreach (var cmd in commands)
+                {
+                    try
+                    {
+                        var result = CommandRegistry.InvokeCommandAsync(cmd.Tool, cmd.Params)
+                            .ConfigureAwait(true).GetAwaiter().GetResult();
+                        job.Results.Add(result);
+                    }
+                    catch (Exception ex)
+                    {
+                        job.Results.Add(new ErrorResponse(ex.Message));
+                        if (atomic)
+                        {
+                            job.Status = JobStatus.Failed;
+                            job.Error = ex.Message;
+                            job.CompletedAt = DateTime.UtcNow;
+                            return new ErrorResponse($"Instant batch failed at command '{cmd.Tool}': {ex.Message}",
+                                new { ticket = job.Ticket, results = job.Results });
+                        }
+                    }
+                }
+                job.Status = JobStatus.Done;
+                job.CompletedAt = DateTime.UtcNow;
+                return new SuccessResponse("Batch completed (instant).",
+                    new { ticket = job.Ticket, results = job.Results });
+            }
+
+            // Non-instant: return ticket for polling
+            return new PendingResponse(
+                $"Batch queued as {job.Ticket}. Poll with poll_job.",
+                pollIntervalSeconds: 2.0,
+                data: new
+                {
+                    ticket = job.Ticket,
+                    status = job.Status.ToString().ToLowerInvariant(),
+                    position = CommandGatewayState.Queue.GetAheadOf(job.Ticket).Count,
+                    tier = job.Tier.ToString().ToLowerInvariant(),
+                    agent,
+                    label,
+                    atomic
+                });
+        }
     }
 }

MCPForUnity/Editor/Tools/BatchJob.cs

@@ -0,0 +1,47 @@
+using System;
+using System.Collections.Generic;
+using Newtonsoft.Json.Linq;
+
+namespace MCPForUnity.Editor.Tools
+{
+    public enum JobStatus { Queued, Running, Done, Failed, Cancelled }
+
+    /// <summary>
+    /// Represents a queued batch of MCP commands with ticket tracking.
+    /// </summary>
+    public class BatchJob
+    {
+        public string Ticket { get; set; }
+        public string Agent { get; set; }
+        public string Label { get; set; }
+        public bool Atomic { get; set; }
+        public ExecutionTier Tier { get; set; }
+        public bool CausesDomainReload { get; set; }
+        public JobStatus Status { get; set; } = JobStatus.Queued;
+
+        public List<BatchCommand> Commands { get; set; } = new();
+        public List<object> Results { get; set; } = new();
+        public int CurrentIndex { get; set; }
+        public string Error { get; set; }
+
+        public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
+        public DateTime? CompletedAt { get; set; }
+
+        public int UndoGroup { get; set; } = -1;
+    }
+
+    public class BatchCommand
+    {
+        public string Tool { get; set; }
+        public JObject Params { get; set; }
+        public ExecutionTier Tier { get; set; }
+        public bool CausesDomainReload { get; set; }
+    }
+
+    public class AgentStats
+    {
+        public int Active { get; set; }
+        public int Queued { get; set; }
+        public int Completed { get; set; }
+    }
+}

MCPForUnity/Editor/Tools/CommandClassifier.cs

@@ -0,0 +1,89 @@
+using Newtonsoft.Json.Linq;
+
+namespace MCPForUnity.Editor.Tools
+{
+    /// <summary>
+    /// Refines a tool's ExecutionTier based on action-level parameters.
+    /// Tools declare a base tier via [McpForUnityTool(Tier=...)]; this classifier
+    /// can promote or demote based on specific action strings or param values.
+    /// </summary>
+    public static class CommandClassifier
+    {
+        /// <summary>
+        /// Classify a single command. Returns the effective tier after action-level overrides.
+        /// </summary>
+        public static ExecutionTier Classify(string toolName, ExecutionTier attributeTier, JObject @params)
+        {
+            if (@params == null) return attributeTier;
+
+            string action = @params.Value<string>("action");
+
+            return toolName switch
+            {
+                "manage_scene" => ClassifyManageScene(action, attributeTier),
+                "refresh_unity" => ClassifyRefreshUnity(@params, attributeTier),
+                "manage_editor" => ClassifyManageEditor(action, attributeTier),
+                _ => attributeTier
+            };
+        }
+
+        /// <summary>
+        /// Classify a batch of commands. Returns the highest (most restrictive) tier.
+        /// </summary>
+        public static ExecutionTier ClassifyBatch(
+            (string toolName, ExecutionTier attributeTier, JObject @params)[] commands)
+        {
+            var max = ExecutionTier.Instant;
+            foreach (var (toolName, attributeTier, @params) in commands)
+            {
+                var tier = Classify(toolName, attributeTier, @params);
+                if (tier > max) max = tier;
+            }
+            return max;
+        }
+
+        /// <summary>
+        /// Returns true if the given command would trigger a domain reload (compilation or play mode entry).
+        /// </summary>
+        public static bool CausesDomainReload(string toolName, JObject @params)
+        {
+            if (@params == null) return false;
+
+            return toolName switch
+            {
+                "refresh_unity" => @params.Value<string>("compile") != "none",
+                "manage_editor" => @params.Value<string>("action") == "play",
+                _ => false
+            };
+        }
+
+        static ExecutionTier ClassifyManageScene(string action, ExecutionTier fallback)
+        {
+            return action switch
+            {
+                "get_hierarchy" or "get_active" or "get_build_settings" or "screenshot"
+                    => ExecutionTier.Instant,
+                "create" or "load" or "save"
+                    => ExecutionTier.Heavy,
+                _ => fallback
+            };
+        }
+
+        static ExecutionTier ClassifyRefreshUnity(JObject @params, ExecutionTier fallback)
+        {
+            string compile = @params.Value<string>("compile");
+            if (compile == "none") return ExecutionTier.Smooth;
+            return fallback; // Heavy by default
+        }
+
+        static ExecutionTier ClassifyManageEditor(string action, ExecutionTier fallback)
+        {
+            return action switch
+            {
+                "telemetry_status" or "telemetry_ping" => ExecutionTier.Instant,
+                "play" or "pause" or "stop" => ExecutionTier.Heavy,
+                _ => fallback
+            };
+        }
+    }
+}