style(comments): strip obvious comments and label WHY/TODO/HACK in core Llm+orchestration

Extend the comment convention to the portable-core LLM client, transport, skill tools and
orchestrators (13 files): remove restate-the-code comments and section banners, tag genuine
rationale with an explicit WHY:/TODO:/HACK: prefix (first line of each block). Comment-only,
code verified unchanged. Bulk pass by gpt-5.3-spark agents, reviewed and de-duplicated by hand.

Author: NeoXider

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

@@ -33,7 +33,7 @@ private sealed class CallSkillToolProxy : LlmToolBase, IAIFunctionLlmTool, ISkil
 
             private readonly IReadOnlyCollection<string> _allowedToolNames;
 
-            // When the backing list is a live MutableSkillCatalog (skill authoring), the tool map is
+            // WHY: When the backing list is a live MutableSkillCatalog (skill authoring), the tool map is
             // rebuilt per call so a tool exposed by a just-authored skill is immediately invocable.
             private readonly bool _isLive;
             private readonly Dictionary<string, SkillToolDescriptor> _toolsByName;
@@ -60,7 +60,7 @@ private Dictionary<string, SkillToolDescriptor> ResolveToolMap()
             public override string ParametersSchema =>
                 "{\"type\":\"object\",\"properties\":{\"tool_name\":{\"type\":\"string\",\"description\":\"Skill tool name returned by read_skill.\"},\"arguments_json\":{\"type\":\"string\",\"description\":\"JSON object string with the skill tool parameters.\"}},\"required\":[\"tool_name\",\"arguments_json\"]}";
 
-            // call_skill_tool dispatches to an arbitrary resolved skill tool whose effect the outer
+            // WHY: call_skill_tool dispatches to an arbitrary resolved skill tool whose effect the outer
             // policy cannot see, so it is treated conservatively as mutating: AllowDuplicates=false so
             // ToolExecutionPolicy suppresses only a CROSS-TURN byte-identical echo (structured no-op)
             // while still allowing intra-turn repeats and never suppressing the retry of a FAILED call.
@@ -116,7 +116,7 @@ private static Dictionary<string, SkillToolDescriptor> BuildToolMap(
                     continue;
                 }
 
-                // First-registered wins (deterministic, matches the order read_skill enumerates skills).
+                // WHY: First-registered wins (deterministic, matches the order read_skill enumerates skills).
                 // Previously this was last-write-wins, so two skills exposing a same-named tool silently
                 // shadowed each other: read_skill advertised skill A's tool while call_skill_tool ran
                 // skill B's. Keeping the first and warning makes the collision visible and predictable.
@@ -206,4 +206,4 @@ private static Exception Unwrap(Exception ex)
             return ex.InnerException ?? ex;
         }
     }
-}
+}

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

@@ -96,12 +96,12 @@ public async Task<LlmCompletionResult> CompleteAsync(
             }
             catch (OperationCanceledException)
             {
-                // Cancellation is caller intent, not a backend fault — do not count it, do not swallow it.
+                // WHY: Cancellation is caller intent, not a backend fault — do not count it, do not swallow it.
                 throw;
             }
             catch (Exception ex)
             {
-                // An unexpected throw from the inner client is treated as a transient backend fault.
+                // WHY: An unexpected throw from the inner client is treated as a transient backend fault.
                 RecordFailure();
                 throw new LlmClientException(ex.Message, LlmErrorCode.ProviderError);
             }
@@ -136,7 +136,7 @@ public async IAsyncEnumerable<LlmStreamChunk> CompleteStreamingAsync(
                 while (true)
                 {
                     LlmStreamChunk chunk;
-                    // C# forbids `yield` inside a catch, so capture any inner-stream fault here and emit the
+                    // WHY: C# forbids `yield` inside a catch, so capture any inner-stream fault here and emit the
                     // terminal error chunk AFTER the try/catch instead.
                     string moveError = null;
                     try
@@ -185,7 +185,7 @@ public async IAsyncEnumerable<LlmStreamChunk> CompleteStreamingAsync(
                 await e.DisposeAsync().ConfigureAwait(false);
             }
 
-            // Classify the whole stream: a stream that produced an error chunk (or nothing at all) is a
+            // WHY: Classify the whole stream: a stream that produced an error chunk (or nothing at all) is a
             // failure; a stream that ended cleanly is a success that closes/keeps-closed the breaker.
             bool ok = sawAnyChunk && !sawTerminalFailure;
             RecordResult(ok, ok ? LlmErrorCode.None : terminalCode);
@@ -227,7 +227,7 @@ private bool TryEnter(out string rejectReason)
                     return false;
                 }
 
-                // Closed or HalfOpen: allow through (HalfOpen admits the single probe already in flight).
+                // WHY: Closed or HalfOpen: allow through (HalfOpen admits the single probe already in flight).
                 rejectReason = null;
                 return true;
             }
@@ -247,7 +247,7 @@ private void RecordResult(bool ok, LlmErrorCode code)
             }
             else
             {
-                // A caller-caused failure (auth, invalid request, context length, empty) is not the backend's
+                // WHY: A caller-caused failure (auth, invalid request, context length, empty) is not the backend's
                 // health problem — do not trip the breaker, but a half-open probe that returned such a result
                 // still means the backend is reachable, so treat it as a soft success for state purposes.
                 RecordSuccess();
@@ -273,7 +273,7 @@ private void RecordFailure()
             {
                 if (_state == State.HalfOpen)
                 {
-                    // The probe failed — re-open for another cooldown.
+                    // WHY: The probe failed — re-open for another cooldown.
                     _state = State.Open;
                     _openedAtMs = _nowMs();
                     _log?.Invoke("[CircuitBreaker] re-opened: half-open probe failed.");
@@ -311,4 +311,4 @@ private static bool IsTransientFailure(LlmErrorCode code)
         }
     }
 }
-#endif
+#endif

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

@@ -38,7 +38,7 @@ public sealed class HttpClientOpenAiTransport : IOpenAiHttpTransport
 
         private static HttpClient CreateSharedHttpClient()
         {
-            // HttpClientHandler is available on .NET Standard 2.0 (Unity's default Mono/IL2CPP profile).
+            // WHY: HttpClientHandler is available on .NET Standard 2.0 (Unity's default Mono/IL2CPP profile).
             // Bypass any system/WinINET proxy: Mono's HttpClient uses the system proxy by default, which
             // can route even 127.0.0.1 / localhost requests through a proxy or VPN filter driver. A local
             // LLM endpoint must never go through a proxy. (SocketsHttpHandler is not exposed by Unity's
@@ -54,7 +54,7 @@ private static HttpClient CreateSharedHttpClient()
             }
             catch
             {
-                /* some profiles may not support the setter; fall back to default proxy behavior */
+                // WHY: some profiles may not support the setter; fall back to default proxy behavior
             }
 
             return new HttpClient(handler) { Timeout = Timeout.InfiniteTimeSpan };
@@ -188,4 +188,4 @@ private static HttpClient GetStreamingHttpClient()
         }
     }
 }
-#endif
+#endif