feat(llm): player-facing error text separate from diagnostics; v6.9.0

A failed LLM call has two audiences and used to get one string. CoreAiChatPanel
pasted `exception.Message` into the transcript, so a player read
`❌ HTTP error 403: {"error":{"message":"..."}}` — transport prefix plus a JSON
blob, truncated at the exception cap — while the log got that same short string
and never saw the provider body.

LlmErrorPresentation (portable core) splits them:

- ToUserMessage(ex) — one sentence for the bubble. A message the BACKEND authored
  for the player wins, parsed out of LlmClientException.ProviderErrorBody: a
  gateway that already says "the teacher is unavailable, try again in a minute"
  knows the product better than this library. Otherwise a phrase per LlmErrorCode,
  with the provider's retry window folded into the RateLimited text.
- ToDiagnosticText(ex) — typed code, HTTP status, retry hint and the raw body, for
  the log line next to the exception itself.

Guardrails: JSON dumps, stack traces and bodies over 400 chars are diagnostics,
not UI text, and fall back to the typed phrase; a 401 body reaches neither the
player nor the log, because providers echo the submitted key back in
invalid-credentials responses (same redaction the HTTP adapters already apply).

CoreAiChatPanel now logs before it renders, and exposes ResolveErrorMessage /
ResolveStreamErrorMessage as protected virtual hooks next to ResolveTimeoutMessage,
so a game can localize the text without being able to hide diagnostics. Errors
arriving inside a stream chunk are logged too and lose the "HTTP error 500:" prefix.

Verified: LlmErrorPresentationEditModeTests 8/8 (run standalone against the built
CoreAI.Core, since the editor holds the project lock); dotnet build gates on a clean
worktree — CoreAI.Core, CoreAI.Source and CoreAI.Core.Tests, 0 errors. Full EditMode
suite runs on next editor start. All six packages bumped in lockstep.

Author: NeoXider

Assets/CoreAI/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [6.9.0] - 2026-07-29
+
+One failure, two audiences: a sentence for the player, everything for the log.
+
+### Added
+
+- **`LlmErrorPresentation`** (portable core, no Unity types). Turns a failed LLM call into the two
+  strings it always needed:
+  - `ToUserMessage(exception)` — one readable sentence for a chat bubble. A message the BACKEND
+    authored for the player wins (parsed from `error.message` in `LlmClientException.ProviderErrorBody`),
+    because a gateway that already says "the teacher is unavailable, try again in a minute" knows the
+    product better than this library. Otherwise a phrase per `LlmErrorCode` is used — with the
+    provider's retry window folded into the `RateLimited` text.
+  - `ToDiagnosticText(exception)` — typed code, HTTP status, retry hint and the raw provider body,
+    for the log line next to the exception itself.
+  - `ExtractProviderMessage` / `StripHttpErrorPrefix` are public: hosts that render errors themselves
+    reuse the same parsing instead of string-matching `"HTTP error "`.
+- Guardrails, all covered by `LlmErrorPresentationEditModeTests`:
+  - JSON dumps, stack traces and bodies longer than `MaxUserMessageLength` (400) are diagnostics, not
+    UI text — they fall back to the typed phrase, so a player never reads `{"error":{...}}`.
+  - **A 401 body reaches neither the player nor the log.** Providers echo the submitted key back in
+    invalid-credentials responses, so the redaction the HTTP adapters already apply to log lines now
+    applies here too (`body=[redacted auth error body]`; the bubble shows the "sign in again" phrase).
+
 ## [6.8.3] - 2026-07-29
 
 The real fix for "mods spawn nothing in a build", and a correction: 6.8.2 blamed the wrong cause.

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

@@ -0,0 +1,225 @@
+using System;
+using Newtonsoft.Json.Linq;
+
+namespace CoreAI.Ai
+{
+    /// <summary>
+    /// Turns an LLM failure into two different strings: one for the PLAYER and one for the LOG.
+    ///
+    /// WHY: chat UIs used to paste <c>exception.Message</c> straight into the transcript, so a player
+    /// saw <c>HTTP error 403: {"error":{"message":"..."}}</c> — technical, often truncated, and useless
+    /// to them — while the log got the same short string and lost the provider body. This type splits
+    /// the two audiences:
+    /// <list type="bullet">
+    /// <item><see cref="ToUserMessage(Exception, string)"/> — one readable sentence. A server-authored
+    ///   message wins (a gateway that already says "the teacher is unavailable, try again in a minute"
+    ///   knows the product better than this library); otherwise a per-<see cref="LlmErrorCode"/>
+    ///   phrase is used.</item>
+    /// <item><see cref="ToDiagnosticText"/> — everything worth keeping: error code, HTTP status,
+    ///   retry hint and the raw provider body.</item>
+    /// </list>
+    /// Portable core: no Unity types, so the same mapping is available to any host or headless test.
+    /// </summary>
+    public static class LlmErrorPresentation
+    {
+        /// <summary>Fallback shown when nothing more specific is known.</summary>
+        public const string DefaultUserMessage = "The assistant is unavailable right now. Please try again in a moment.";
+
+        /// <summary>Longest server-authored message that is shown to the player as-is.</summary>
+        public const int MaxUserMessageLength = 400;
+
+        /// <summary>One readable sentence for the chat bubble. Never returns null or empty.</summary>
+        public static string ToUserMessage(Exception exception, string fallback = null)
+        {
+            if (exception is LlmClientException llmException)
+            {
+                return ToUserMessage(llmException, fallback);
+            }
+
+            if (exception is OperationCanceledException)
+            {
+                return ForErrorCode(LlmErrorCode.Cancelled);
+            }
+
+            return Coalesce(fallback, DefaultUserMessage);
+        }
+
+        /// <summary>One readable sentence for the chat bubble, from a typed LLM failure.</summary>
+        public static string ToUserMessage(LlmClientException exception, string fallback = null)
+        {
+            if (exception == null)
+            {
+                return Coalesce(fallback, DefaultUserMessage);
+            }
+
+            // WHY: a 401 body can echo the submitted key/token back (providers do this), so its text
+            // never reaches the transcript — the player gets the "sign in again" phrase instead.
+            // Same rule as the redaction in the HTTP adapters; see MeaiOpenAiChatClient.BuildHttpException.
+            if (IsAuthFailure(exception))
+            {
+                return Coalesce(fallback, ForErrorCode(LlmErrorCode.AuthExpired));
+            }
+
+            // A gateway/provider message aimed at the player wins over any built-in phrase.
+            string authored = ExtractProviderMessage(exception.ProviderErrorBody);
+            if (string.IsNullOrWhiteSpace(authored))
+            {
+                authored = StripHttpErrorPrefix(exception.Message);
+            }
+
+            if (IsPresentableToPlayer(authored))
+            {
+                return authored.Trim();
+            }
+
+            return Coalesce(fallback, ForErrorCode(exception.ErrorCode, exception.RetryAfterSeconds));
+        }
+
+        /// <summary>Built-in phrase for a failure category; used when nobody authored a better one.</summary>
+        public static string ForErrorCode(LlmErrorCode errorCode, int? retryAfterSeconds = null)
+        {
+            string retryHint = retryAfterSeconds.HasValue && retryAfterSeconds.Value > 0
+                ? $" Try again in {retryAfterSeconds.Value} s."
+                : "";
+
+            switch (errorCode)
+            {
+                case LlmErrorCode.Timeout:
+                    return "The assistant took too long to answer. Please try again.";
+                case LlmErrorCode.Cancelled:
+                    return "The request was stopped.";
+                case LlmErrorCode.EmptyResponse:
+                    return "The assistant returned an empty answer. Please try again.";
+                case LlmErrorCode.AuthExpired:
+                    return "The session has expired. Please sign in again.";
+                case LlmErrorCode.QuotaExceeded:
+                    return "The assistant quota for this account is used up.";
+                case LlmErrorCode.RateLimited:
+                    return "Too many requests to the assistant right now." + retryHint;
+                case LlmErrorCode.BackendUnavailable:
+                    return "The assistant is unavailable right now. Please try again in a moment.";
+                case LlmErrorCode.InvalidRequest:
+                    return "The assistant could not process this request.";
+                case LlmErrorCode.RoutingError:
+                    return "No assistant backend is configured. Please tell the maintainer.";
+                case LlmErrorCode.ContextLengthExceeded:
+                    return "The conversation got too long for the model. Start a new chat or shorten the message.";
+                default:
+                    return DefaultUserMessage;
+            }
+        }
+
+        /// <summary>
+        /// Everything worth writing to the log: category, HTTP status, retry hint and the raw provider
+        /// body. Callers should log this ALONGSIDE the exception itself (which carries the stack trace).
+        /// </summary>
+        public static string ToDiagnosticText(Exception exception)
+        {
+            if (!(exception is LlmClientException llmException))
+            {
+                return exception == null ? "" : exception.ToString();
+            }
+
+            string status = llmException.HttpStatus.HasValue ? $" http={llmException.HttpStatus.Value}" : "";
+            string retry = llmException.RetryAfterSeconds.HasValue
+                ? $" retryAfter={llmException.RetryAfterSeconds.Value}s"
+                : "";
+            // Same redaction rule as the HTTP adapters: an auth-failure body can contain the key
+            // that was just sent, and logs travel further than the process.
+            string body;
+            if (string.IsNullOrWhiteSpace(llmException.ProviderErrorBody))
+            {
+                body = "";
+            }
+            else if (IsAuthFailure(llmException))
+            {
+                body = " body=[redacted auth error body]";
+            }
+            else
+            {
+                body = $" body={llmException.ProviderErrorBody}";
+            }
+
+            return $"code={llmException.ErrorCode}{status}{retry} message={llmException.Message}{body}";
+        }
+
+        /// <summary>Reads <c>error.message</c> (OpenAI-compatible shape) out of a raw provider body.</summary>
+        public static string ExtractProviderMessage(string providerErrorBody)
+        {
+            if (string.IsNullOrWhiteSpace(providerErrorBody))
+            {
+                return "";
+            }
+
+            try
+            {
+                JObject parsed = JObject.Parse(providerErrorBody);
+                string message = parsed["error"]?["message"]?.ToString();
+                if (string.IsNullOrWhiteSpace(message))
+                {
+                    message = parsed["message"]?.ToString() ?? parsed["detail"]?.ToString();
+                }
+
+                return string.IsNullOrWhiteSpace(message) ? "" : message.Trim();
+            }
+            catch (Exception)
+            {
+                // Not JSON (HTML error page, proxy text, truncated body) — the caller falls back to
+                // the exception message, so a parse failure must never surface as a second error.
+                return "";
+            }
+        }
+
+        /// <summary>
+        /// Drops the <c>HTTP error 403: </c> prefix that HTTP adapters put in front of the provider text,
+        /// so a message authored for the player is not shown with transport noise in front of it.
+        /// </summary>
+        public static string StripHttpErrorPrefix(string message)
+        {
+            if (string.IsNullOrWhiteSpace(message))
+            {
+                return "";
+            }
+
+            const string marker = "HTTP error ";
+            if (!message.StartsWith(marker, StringComparison.OrdinalIgnoreCase))
+            {
+                return message.Trim();
+            }
+
+            int separator = message.IndexOf(':', marker.Length);
+            return separator < 0 || separator + 1 >= message.Length
+                ? message.Trim()
+                : message.Substring(separator + 1).Trim();
+        }
+
+        /// <summary>
+        /// Is this string something a player should read? JSON dumps, stack traces and novel-length
+        /// bodies are diagnostics, not UI text — those fall back to the built-in phrase.
+        /// </summary>
+        private static bool IsPresentableToPlayer(string message)
+        {
+            if (string.IsNullOrWhiteSpace(message) || message.Length > MaxUserMessageLength)
+            {
+                return false;
+            }
+
+            string trimmed = message.Trim();
+            char first = trimmed[0];
+            if (first == '{' || first == '[' || first == '<')
+            {
+                return false;
+            }
+
+            return !trimmed.Contains("\n at ", StringComparison.Ordinal)
+                   && !trimmed.Contains("Exception:", StringComparison.Ordinal);
+        }
+
+        /// <summary>401-class failure: its body is treated as secret-bearing everywhere.</summary>
+        private static bool IsAuthFailure(LlmClientException exception) =>
+            exception.HttpStatus == 401 || exception.ErrorCode == LlmErrorCode.AuthExpired;
+
+        private static string Coalesce(string preferred, string fallback) =>
+            string.IsNullOrWhiteSpace(preferred) ? fallback : preferred.Trim();
+    }
+}

Assets/CoreAI/Runtime/Core/Features/Llm/LlmErrorPresentation.cs.meta

@@ -0,0 +1,138 @@
+using System;
+using CoreAI.Ai;
+using NUnit.Framework;
+
+namespace CoreAI.Core.Tests.EditMode
+{
+    /// <summary>
+    /// Guards the split between the string a PLAYER reads and the string a LOG keeps
+    /// (<see cref="LlmErrorPresentation"/>): a backend-authored message must survive to the chat
+    /// bubble, raw JSON/stack noise must not, and a 401 body must never leave the log — it can echo
+    /// the key that was just submitted.
+    /// </summary>
+    public sealed class LlmErrorPresentationEditModeTests
+    {
+        [Test]
+        public void UserMessage_PrefersBackendAuthoredMessageFromProviderBody()
+        {
+            LlmClientException exception = new(
+                "HTTP error 403: Teacher is unavailable: AI service answered 403.",
+                LlmErrorCode.ProviderError,
+                403,
+                null,
+                "{\"error\":{\"code\":\"ai_upstream_error\",\"message\":\"Teacher is unavailable, try again in a minute.\"}}");
+
+            Assert.AreEqual(
+                "Teacher is unavailable, try again in a minute.",
+                LlmErrorPresentation.ToUserMessage(exception));
+        }
+
+        [Test]
+        public void UserMessage_StripsHttpPrefixWhenBodyIsNotJson()
+        {
+            LlmClientException exception = new(
+                "HTTP error 502: Upstream gateway is down.",
+                LlmErrorCode.BackendUnavailable,
+                502,
+                null,
+                "<html>502 Bad Gateway</html>");
+
+            Assert.AreEqual("Upstream gateway is down.", LlmErrorPresentation.ToUserMessage(exception));
+        }
+
+        [Test]
+        public void UserMessage_FallsBackToTypedPhraseWhenTextIsDiagnosticNoise()
+        {
+            LlmClientException exception = new(
+                "HTTP error 500: {\"error\":{\"metadata\":{\"raw\":\"...\"}}}",
+                LlmErrorCode.BackendUnavailable,
+                500,
+                null,
+                "{\"error\":{\"metadata\":{\"raw\":\"...\"}}}");
+
+            string message = LlmErrorPresentation.ToUserMessage(exception);
+
+            Assert.AreEqual(LlmErrorPresentation.ForErrorCode(LlmErrorCode.BackendUnavailable), message);
+            StringAssert.DoesNotContain("{", message);
+        }
+
+        [Test]
+        public void UserMessage_NeverEchoesAuthFailureBody()
+        {
+            LlmClientException exception = new(
+                "HTTP error 401: invalid api key sk-secret-value",
+                LlmErrorCode.AuthExpired,
+                401,
+                null,
+                "{\"error\":{\"message\":\"Invalid API key sk-secret-value\"}}");
+
+            string message = LlmErrorPresentation.ToUserMessage(exception);
+
+            Assert.AreEqual(LlmErrorPresentation.ForErrorCode(LlmErrorCode.AuthExpired), message);
+            StringAssert.DoesNotContain("sk-secret-value", message);
+        }
+
+        [Test]
+        public void UserMessage_UsesRetryHintWhenProviderSuppliedOne()
+        {
+            LlmClientException exception = new(
+                "HTTP error 429: {\"error\":{}}",
+                LlmErrorCode.RateLimited,
+                429,
+                14,
+                "{\"error\":{}}");
+
+            StringAssert.Contains("14", LlmErrorPresentation.ToUserMessage(exception));
+        }
+
+        [Test]
+        public void UserMessage_HandlesPlainExceptionsAndCancellation()
+        {
+            Assert.AreEqual(
+                LlmErrorPresentation.DefaultUserMessage,
+                LlmErrorPresentation.ToUserMessage(new InvalidOperationException("boom")));
+            Assert.AreEqual(
+                LlmErrorPresentation.ForErrorCode(LlmErrorCode.Cancelled),
+                LlmErrorPresentation.ToUserMessage(new OperationCanceledException()));
+            Assert.AreEqual("Custom fallback.", LlmErrorPresentation.ToUserMessage(null, "Custom fallback."));
+        }
+
+        [Test]
+        public void DiagnosticText_KeepsEverythingExceptAuthBodies()
+        {
+            LlmClientException providerError = new(
+                "HTTP error 403: blocked",
+                LlmErrorCode.ProviderError,
+                403,
+                7,
+                "{\"error\":{\"message\":\"blocked\"}}");
+
+            string diagnostics = LlmErrorPresentation.ToDiagnosticText(providerError);
+
+            StringAssert.Contains("code=ProviderError", diagnostics);
+            StringAssert.Contains("http=403", diagnostics);
+            StringAssert.Contains("retryAfter=7s", diagnostics);
+            StringAssert.Contains("\"message\":\"blocked\"", diagnostics);
+
+            LlmClientException authError = new(
+                "HTTP error 401: invalid key",
+                LlmErrorCode.AuthExpired,
+                401,
+                null,
+                "{\"error\":{\"message\":\"Invalid API key sk-secret-value\"}}");
+
+            string redacted = LlmErrorPresentation.ToDiagnosticText(authError);
+
+            StringAssert.Contains("[redacted auth error body]", redacted);
+            StringAssert.DoesNotContain("sk-secret-value", redacted);
+        }
+
+        [Test]
+        public void StripHttpErrorPrefix_LeavesOrdinaryTextAlone()
+        {
+            Assert.AreEqual("Model is overloaded.", LlmErrorPresentation.StripHttpErrorPrefix("Model is overloaded."));
+            Assert.AreEqual("Model is overloaded.", LlmErrorPresentation.StripHttpErrorPrefix("HTTP error 503: Model is overloaded."));
+            Assert.AreEqual("", LlmErrorPresentation.StripHttpErrorPrefix(null));
+        }
+    }
+}