style(comments): strip obvious what-comments, keep only XML/TODO/HACK/WHY

Remove section-divider banners, empty // lines, and comments that merely restate the next
line (e.g. repeated 'Resolve and cache required local values'). Comment cleanup only — no code
or logic changed. Genuine rationale kept and tagged with an explicit WHY: prefix (lifecycle
ordering, SSE park/drain race, Hermes/Qwen XML template, shared Lua-CSharp stack instance).
Bulk pass by gpt-5.3-spark agents, WHY-comments audited and restored by hand.

Author: NeoXider

Assets/CoreAI/Runtime/Core/Features/Llm/LoggingLlmClientDecorator.cs

@@ -149,7 +149,6 @@ public async Task<LlmCompletionResult> CompleteAsync(
                     }
                     catch (LlmClientException retryEx) when (IsRetryableHttpError(retryEx, out httpWait))
                     {
-                        // will retry again if attempts remain
                     }
                     catch (Exception nonRetryEx)
                     {
@@ -177,7 +176,6 @@ public async Task<LlmCompletionResult> CompleteAsync(
                 }
             }
 
-            // apply the same retry policy as for LlmClientException above.
             if (result != null &&
                 !result.Ok &&
                 IsRetryableFailureResult(result, out int httpWaitFromResult) &&
@@ -214,7 +212,6 @@ public async Task<LlmCompletionResult> CompleteAsync(
                     }
                     catch (LlmClientException retryEx) when (IsRetryableHttpError(retryEx, out httpWait))
                     {
-                        // continue loop
                     }
                     catch (Exception)
                     {
@@ -867,4 +864,4 @@ private static string Preview(string text, int maxChars)
             return t.Substring(0, maxChars) + $"... [+{t.Length - maxChars} chars]";
         }
     }
-}
+}

Assets/CoreAI/Runtime/Core/Features/Llm/SmartToolCallingChatClient.cs

@@ -98,8 +98,6 @@ public SmartToolCallingChatClient(MEAI.IChatClient innerClient, ILog logger, ICo
                 while (true)
                 {
                     iteration++;
-
-                    // === Max roundtrip safety valve ===
                     // Per-request override wins when supplied (null = inherit global; 0 = unlimited).
                     int maxRoundtrips = _maxRoundtripsOverride ?? _settings.MaxToolCallRoundtrips;
                     if (maxRoundtrips > 0 && iteration > maxRoundtrips)
@@ -230,8 +228,6 @@ public SmartToolCallingChatClient(MEAI.IChatClient innerClient, ILog logger, ICo
                                 BuildMissingRequiredToolInstruction(requiredToolName)));
                             continue;
                         }
-
-                        // === Empty response mid-task ===
                         // A COMPLETELY empty response (no text, no tool call) after this same request has
                         // already executed at least one SUCCESSFUL tool call is the model trailing off
                         // mid-task, not a deliberate "I'm done" - unlike a text-only response, which is
@@ -267,8 +263,6 @@ public SmartToolCallingChatClient(MEAI.IChatClient innerClient, ILog logger, ICo
                             _logger.Info(
                                 $"[SmartToolCall] Iteration {iteration}: Text response, stopping.", LogTag.Llm);
                         }
-
-                        // === Max response chars truncation ===
                         int maxResponseChars = _settings.MaxResponseChars;
                         if (maxResponseChars > 0)
                         {
@@ -341,8 +335,6 @@ await policy.ExecuteBatchAsync(toolCalls, iterationOptions, cancellationToken)
                     MEAI.ChatMessage toolTurn = new(MEAI.ChatRole.Tool, batch.Results);
                     messages.Add(assistantTurn);
                     messages.Add(toolTurn);
-
-                    // === Error-feedback lifecycle ===
                     // Track all-failed iterations as removable error feedback; once an iteration
                     // succeeds, drop the obsolete failed pairs (whole Assistant+Tool pairs, so
                     // tool-call / tool-result pairing stays OpenAI-valid).
@@ -362,8 +354,6 @@ await policy.ExecuteBatchAsync(toolCalls, iterationOptions, cancellationToken)
                                 LogTag.Llm);
                         }
                     }
-
-                    // === Tool call history truncation ===
                     // Prevent unbounded message growth during long tool-calling loops.
                     // Only count tool-related messages (Assistant with FunctionCallContent + Tool result).
                     int maxHistoryMsgs = _settings.MaxToolCallHistoryMessages;
@@ -451,7 +441,6 @@ internal static bool TryExtractToolCallsFromText(
                 }
                 catch
                 {
-                    // skip malformed matches
                 }
             }
 
@@ -753,4 +742,4 @@ private static void AttachCumulativeUsage(MEAI.ChatResponse response, MEAI.Usage
         }
     }
 }
-#endif
+#endif

Assets/CoreAI/Runtime/Core/Features/Llm/ToolExecutionPolicy.cs

@@ -291,7 +291,6 @@ private bool TryBuildDuplicateSignature(MEAI.FunctionCallContent fc, out string
             }
             catch
             {
-                /* swallow */
             }
 
             signature = $"{canonicalName}({argsSig})";
@@ -405,7 +404,6 @@ public async Task<ToolCallResult> ExecuteSingleAsync(
             MEAI.ChatOptions chatOptions,
             CancellationToken cancellationToken)
         {
-            // === Kilo-style repair: fix wrong casing before lookup ===
             MEAI.FunctionCallContent repairedFc = TryRepairToolName(fc);
             if (repairedFc == null)
             {
@@ -422,8 +420,6 @@ public async Task<ToolCallResult> ExecuteSingleAsync(
             }
 
             fc = repairedFc;
-
-            // === Parse-error guard: never invoke a tool with malformed/truncated argument JSON ===
             // The streaming accumulator surfaces unparseable tool-call arguments by injecting a
             // ParseErrorKey marker instead of dropping them. Such args are bogus, so short-circuit
             // here (before invoking the real tool) and ask the model to resend complete JSON.
@@ -503,8 +499,6 @@ public async Task<ToolCallResult> ExecuteSingleAsync(
 
                 ILlmAsyncMarshaler marshaler =
                     _settings.ToolInvocationMarshaler ?? PassThroughLlmAsyncMarshaler.Instance;
-
-                // === Per-tool timeout: wrap cancellation token ===
                 int toolTimeoutMs = _settings.DefaultToolTimeoutMs;
                 object result;
                 if (toolTimeoutMs > 0)
@@ -551,8 +545,6 @@ await aiFunc.InvokeAsync(args, cancellationToken).ConfigureAwait(false),
                 sw.Stop();
                 string resultText = NormalizeToolResultText(result);
                 bool succeeded = IsToolResultSuccess(resultText);
-
-                // === Tool result truncation ===
                 int maxResultChars = _settings.MaxToolResultChars;
                 if (maxResultChars > 0 && resultText.Length > maxResultChars)
                 {
@@ -1882,3 +1874,4 @@ private static bool ContainsLegacySuccessFalse(string text)
     }
 }
 #endif
+

Assets/CoreAI/Runtime/Core/Features/Orchestration/LlmToolCallTextExtractor.cs

@@ -14,12 +14,9 @@ public static class LlmToolCallTextExtractor
     {
         private static readonly Regex CodeBlockRegex = new(@"```[\s\S]*?```", RegexOptions.Compiled);
 
-        // Hermes / Qwen-Agent XML tool-call template emitted by many local GGUF models when native
-        // tool_calls is empty, e.g.:
-        //   <tool_call><function=call_skill_tool>
-        //     <parameter=tool_name>craft_item</parameter>
-        //     <parameter=arguments_json>{"item":"Flame Sword"}</parameter>
-        //   </function></tool_call>
+        // WHY: matches the Hermes / Qwen-Agent XML tool-call template many local GGUF models emit when native
+        // tool_calls is empty, e.g. <function=call_skill_tool><parameter=tool_name>craft_item</parameter>
+        // <parameter=arguments_json>{"item":"Flame Sword"}</parameter></function>.
         private static readonly Regex XmlFunctionRegex = new(
             @"<function\s*=\s*([^>\s]+)\s*>(.*?)</function>",
             RegexOptions.Compiled | RegexOptions.Singleline | RegexOptions.IgnoreCase);
@@ -67,14 +64,11 @@ public static bool TryExtract(string text, out List<Match> matches, out string c
             List<(int Start, int Length)> spans = FindBalancedToolCallSpans(searchText);
             if (spans.Count == 0)
             {
-                // Hermes/Qwen-Agent XML tool-call template (common local-model fallback when native
-                // tool_calls is empty) before function-call syntax and memory pseudo-write.
                 if (TryExtractXmlToolCallSyntax(text, out matches, out cleanedText))
                 {
                     return true;
                 }
 
-                // Try function-call syntax before memory pseudo-write.
                 if (TryExtractFunctionCallSyntax(text, out matches, out cleanedText))
                 {
                     return true;
@@ -104,14 +98,13 @@ public static bool TryExtract(string text, out List<Match> matches, out string c
                 {
                     JObject json = JObject.Parse(original);
                     name = json["name"]?.ToString()?.Trim();
-                    // Support both "arguments" and "arguments_json" (Qwen3.5 via LLMUnity).
+                    // WHY: "arguments_json" is the Qwen3.5-via-LLMUnity spelling; accept it alongside "arguments".
                     JToken args = json["arguments"] ?? json["arguments_json"];
                     if (string.IsNullOrWhiteSpace(name) || args == null)
                     {
                         continue;
                     }
 
-                    // If args is a string ("arguments_json": "{...}"), parse it as JSON.
                     if (args.Type == JTokenType.String)
                     {
                         string argsStr = args.ToString();
@@ -437,13 +430,9 @@ private static bool TryExtractFunctionCallSyntax(string text, out List<Match> ma
             string funcName = m.Groups[1].Value;
             string rawArgs = m.Groups[2].Value.Trim();
 
-            // Build arguments JSON from the raw args string.
-            // Handle: read_skill("Alchemy"), read_skill(Crafting),
-            //         call_skill_tool("get_recipes", '{"item":"sword"}')
             Dictionary<string, object> argsDict = new();
             if (!string.IsNullOrEmpty(rawArgs))
             {
-                // Try to parse as JSON first (e.g. {"skill_name": "Alchemy"})
                 if (rawArgs.StartsWith("{"))
                 {
                     try
@@ -458,7 +447,6 @@ private static bool TryExtractFunctionCallSyntax(string text, out List<Match> ma
                 }
                 else
                 {
-                    // Split by comma for multi-arg: call_skill_tool("get_recipes", '{"item":"sword"}')
                     string[] parts = SplitFunctionArgs(rawArgs);
                     if (funcName == "call_skill_tool" && parts.Length >= 2)
                     {
@@ -601,7 +589,6 @@ private static string StripQuotes(string s)
 
         private static string[] SplitFunctionArgs(string argsStr)
         {
-            // Simple split respecting quotes and braces.
             List<string> parts = new();
             int depth = 0;
             bool inQuote = false;
@@ -654,4 +641,4 @@ private static string[] SplitFunctionArgs(string argsStr)
             return parts.ToArray();
         }
     }
-}
+}

Assets/CoreAIMods/Runtime/Composition/CoreAiModsInstaller.cs

@@ -67,8 +67,8 @@ public static void RegisterCoreAiMods(
             // IBundledModSource entries (StreamingAssets, Addressables, remote) to extend the set.
             builder.Register<IBundledModSource>(_ => new ResourcesBundledModSource(), Lifetime.Singleton);
 
-            // Build the whole Lua-CSharp stack once from container services (sandbox + gameplay bindings +
-            // persistent runtime + one-off executor), sharing one bindings instance across both surfaces.
+            // WHY: one Lua-CSharp stack shared across both surfaces, so persistent runtime and one-off executor
+            // resolve the same sandbox + gameplay bindings instance rather than diverging copies.
             builder.Register(c => LuaCsModRuntimeFactory.Create(new LuaCsModStackOptions
             {
                 Logger = c.Resolve<IGameLogger>(),
@@ -87,14 +87,10 @@ public static void RegisterCoreAiMods(
                 OneOffCapabilities = oneOffCapabilities
             }), Lifetime.Singleton);
 
-            // Facades over the stack: the persistent runtime as the VM-agnostic ILuaModRuntime (manage_mods +
-            // auto-repair) and its concrete type (rehydrate + tick), and the one-off executor as ILuaExecutor.
             builder.Register(c => c.Resolve<LuaCsModStack>().Runtime, Lifetime.Singleton)
                 .AsSelf().As<ILuaModRuntime>();
             builder.Register(c => c.Resolve<LuaCsModStack>().ToolExecutor, Lifetime.Singleton)
                 .As<LuaTool.ILuaExecutor>();
-            // The shared logic-override slots both surfaces register through, so a host (e.g. a demo that
-            // declares gameplay formula slots) resolves the same instance every mod's logic_define writes to.
             builder.Register(c => c.Resolve<LuaCsModStack>().GameplayBindings.LogicSlots, Lifetime.Singleton)
                 .AsSelf();
 
@@ -168,9 +164,6 @@ void RehydrateAndStartTicking()
                 }
             });
 
-            // Native tool-calling path for the built-in Programmer role: execute_lua + manage_mods over the
-            // same Lua-CSharp sandbox and gameplay bindings. Hosts that attach their own tools per role
-            // override via AgentMemoryPolicy.
             builder.RegisterBuildCallback(container =>
             {
                 try
@@ -185,9 +178,6 @@ void RehydrateAndStartTicking()
                     policy.AddToolForRole(BuiltInAgentRoleIds.Programmer,
                         new LuaModsLlmTool(container.Resolve<ILuaModRuntime>(), settings, log, scriptCapabilities));
 
-                    // Full Lua reference on demand (read_skill) so the system prompt stays small.
-                    // A Resources/AgentSkills/LuaModding TextAsset overrides the built-in text, same
-                    // convention as the AgentPrompts/System overrides.
                     TextAsset skillOverride = Resources.Load<TextAsset>("AgentSkills/LuaModding");
                     policy.AddSkillForRole(BuiltInAgentRoleIds.Programmer, SkillSet.FromTextContent(
                         BuiltInLuaModdingSkillText.SkillName,