Update Post-Session Analysis Prompt (#389)

Author: MikeAlhayek

.github/copilot-instructions.md

@@ -51,6 +51,8 @@ gulp rebuild
 dotnet build -c Release -warnaserror /p:TreatWarningsAsErrors=true /p:RunAnalyzers=true /p:NuGetAudit=false
 ```
 
+**Important for Copilot skills**: In a fresh environment, build the project early and then check for newly generated skills under `.agents\skills`. One of the packages can create `.agents\skills` on the first build, and those generated skills may contain important, up-to-date capabilities that are not visible before the build runs.
+
 **If build fails with NU1301 errors** about `nuget.cloudsmith.io`, this is expected in restricted environments. Document this limitation rather than attempting workarounds.
 
 #### Unit Tests (Requires Successful Build)
@@ -201,6 +203,7 @@ tests/
 - **MCP Server**: `CrestApps.OrchardCore.AI.Mcp` - exposes Orchard Core content as MCP resources
 - **AI Agents**: `CrestApps.OrchardCore.AI.Agent` - defines reusable AI agents/tools
 - **Provider modules**: `CrestApps.OrchardCore.OpenAI`, `CrestApps.OrchardCore.OpenAI.Azure`, `CrestApps.OrchardCore.Ollama`, `CrestApps.OrchardCore.AzureAIInference`
+- **AI Prompt Templates**: Never hardcode AI system prompts or prompt-style recovery instructions in C# code. Store them in `AITemplates/Prompts/*.md`, add a constant in `AITemplateIds`, and render them through `IAITemplateService`.
 
 ### Working with Omnichannel Modules
 - **Base Module**: `CrestApps.OrchardCore.Omnichannel` - unified communication layer
@@ -279,6 +282,7 @@ If CloudSmith is inaccessible, only asset builds and code analysis are possible.
 - **Code Analysis**: `AnalysisLevel` is set to `latest-Recommended`
 - **Implicit usings**: Enabled globally
 - **Date/time**: Never use `DateTime.UtcNow`. Always inject `IClock` in the constructor (e.g., `IClock clock`) and store it as `private readonly IClock _clock = clock;`, then call `_clock.UtcNow` in methods
+- **Localization extraction**: When using `ILocalizer`, the property/variable must be named `S`, and localized strings must use the literal pattern `S["This is a localized string"]`. Do not use variables inside the brackets because extraction tooling looks specifically for `S["..."]`.
 - **One type per file**: Every public type must live in its own file. The file name must always match the type name (e.g., `MyService.cs` for `class MyService`)
 - **sealed classes**: Seal all classes by default (`sealed class`), **except** ViewModel classes that are consumed by any Orchard Core display driver — those must remain unsealed because the framework creates runtime proxies for them and proxies cannot be created from sealed types
 
@@ -549,4 +553,4 @@ After completing any code change, always clean up:
 - [Orchard Core GitHub](https://github.com/OrchardCMS/OrchardCore)
 - [Project Repository](https://github.com/CrestApps/CrestApps.OrchardCore)
 - [Contributing Guidelines](.github/CONTRIBUTING.md)
-- [MIT License](https://opensource.org/licenses/MIT)
+- [MIT License](https://opensource.org/licenses/MIT)

src/Core/CrestApps.OrchardCore.AI.Chat.Core/Hubs/AIChatHub.cs

@@ -427,6 +427,10 @@ private async Task ProcessChatPromptAsync(ChannelWriter<CompletionPartialMessage
 
         (var chatSession, var isNew) = await GetSessionAsync(services, sessionId, profile, prompt);
 
+        // Ensure the caller joins the session group as soon as the effective session is known,
+        // even when the session was created implicitly by SendMessage streaming.
+        await Groups.AddToGroupAsync(Context.ConnectionId, GetSessionGroupName(chatSession.SessionId), cancellationToken);
+
         var utcNow = clock.UtcNow;
 
         // Handle session reopen if closed.

src/Core/CrestApps.OrchardCore.AI.Chat.Interactions.Core/Hubs/ChatInteractionHub.cs

@@ -410,6 +410,10 @@ private async Task HandlePromptAsync(ChannelWriter<CompletionPartialMessage> wri
 
             prompt = prompt.Trim();
 
+            // Ensure the caller joins the interaction group before any deferred webhook
+            // notifications or live-agent messages are delivered.
+            await Groups.AddToGroupAsync(Context.ConnectionId, GetInteractionGroupName(interaction.ItemId), cancellationToken);
+
             var promptStore = services.GetRequiredService<IChatInteractionPromptStore>();
             var handlerResolver = services.GetRequiredService<IChatResponseHandlerResolver>();
             var citationCollector = services.GetRequiredService<CitationReferenceCollector>();

src/Core/CrestApps.OrchardCore.AI.Core/Models/DefaultAIDeploymentSettings.cs

@@ -8,6 +8,12 @@ namespace CrestApps.OrchardCore.AI.Core.Models;
 /// </summary>
 public sealed class DefaultAIDeploymentSettings
 {
+    /// <summary>
+    /// Gets or sets the default chat deployment identifier.
+    /// Used globally for chat sessions and chat interactions when no specific chat deployment is configured.
+    /// </summary>
+    public string DefaultChatDeploymentId { get; set; }
+
     /// <summary>
     /// Gets or sets the default utility deployment identifier.
     /// Used globally for auxiliary tasks such as planning, intent detection,

src/Core/CrestApps.OrchardCore.AI.Core/Services/DefaultAIDeploymentManager.cs

@@ -124,10 +124,12 @@ private async ValueTask<string> GetGlobalDefaultIdAsync(AIDeploymentType type)
 
         return type switch
         {
+            AIDeploymentType.Chat => settings.DefaultChatDeploymentId,
             AIDeploymentType.Utility => settings.DefaultUtilityDeploymentId,
             AIDeploymentType.Embedding => settings.DefaultEmbeddingDeploymentId,
             AIDeploymentType.Image => settings.DefaultImageDeploymentId,
             AIDeploymentType.SpeechToText => settings.DefaultSpeechToTextDeploymentId,
+            AIDeploymentType.TextToSpeech => settings.DefaultTextToSpeechDeploymentId,
             _ => null,
         };
     }

src/Core/CrestApps.OrchardCore.AI.Core/Services/DefaultSpeechVoicePresenter.cs

@@ -43,15 +43,18 @@ public async Task<IEnumerable<SelectListItem>> GetVoiceMenuItemsAsync(string dep
             var speechVoices = await _clientFactory.GetSpeechVoicesAsync(deployment);
 
             var supportedCultures = await _localizationService.GetSupportedCulturesAsync();
-            var supportedSet = new HashSet<string>(supportedCultures, StringComparer.OrdinalIgnoreCase);
+            var supportedSet = SpeechVoiceLocalizationHelper.CreateAllowedCultures(
+                supportedCultures,
+                CultureInfo.CurrentCulture,
+                CultureInfo.CurrentUICulture);
 
             var voices = new List<SelectListItem>();
 
             foreach (var voiceGroup in speechVoices
-                .Where(v => string.IsNullOrEmpty(v.Language) || supportedSet.Contains(v.Language))
+                .Where(v => SpeechVoiceLocalizationHelper.IsLanguageAllowed(v.Language, supportedSet))
                 .OrderBy(v => v.Language)
                 .ThenBy(v => v.Name)
-                .GroupBy(v => GetCultureDisplayName(v.Language) ?? "Unknown"))
+                .GroupBy(v => SpeechVoiceLocalizationHelper.GetCultureDisplayName(v.Language) ?? "Unknown"))
             {
                 var group = new SelectListGroup { Name = voiceGroup.Key };
 
@@ -71,20 +74,4 @@ public async Task<IEnumerable<SelectListItem>> GetVoiceMenuItemsAsync(string dep
         }
     }
 
-    private static string GetCultureDisplayName(string language)
-    {
-        if (string.IsNullOrEmpty(language))
-        {
-            return null;
-        }
-
-        try
-        {
-            return CultureInfo.GetCultureInfo(language).DisplayName;
-        }
-        catch (CultureNotFoundException)
-        {
-            return language;
-        }
-    }
 }

src/Core/CrestApps.OrchardCore.AI.Core/Services/PostSessionProcessingService.cs

@@ -389,32 +389,39 @@ private async Task<Dictionary<string, PostSessionResult>> ProcessWithToolsAsync(
             _logger.LogDebug(
                 "Post-session tools raw response for session '{SessionId}': '{ResponseText}'.",
                 sessionId,
-                responseText?.Length > 2000 ? responseText[..2000] + "..." : responseText ?? "(empty)");
+                CreateResponseLogPreview(responseText));
         }
 
-        if (string.IsNullOrEmpty(responseText))
+        if (!string.IsNullOrEmpty(responseText))
         {
-            if (_logger.IsEnabled(LogLevel.Debug))
+            var result = TryParsePostSessionResponse(sessionId, responseText);
+
+            if (result?.Tasks != null && result.Tasks.Count > 0)
             {
-                _logger.LogDebug(
-                    "Post-session tools response for session '{SessionId}' has no final text content. Tools may have executed as side effects.",
-                    sessionId);
+                return ApplyResults(tasks, result.Tasks);
             }
-
-            return null;
+        }
+        else if (_logger.IsEnabled(LogLevel.Debug))
+        {
+            _logger.LogDebug(
+                "Post-session tools response for session '{SessionId}' has no final text content. Attempting structured recovery from tool messages.",
+                sessionId);
         }
 
-        // Try to parse the response as structured JSON using multiple strategies.
-        var result = TryParsePostSessionResponse(sessionId, responseText);
+        var recoveredResults = await TryRecoverStructuredToolsResponseAsync(
+            sessionId,
+            chatClient,
+            messages,
+            response.Messages,
+            tasks,
+            cancellationToken);
 
-        if (result?.Tasks != null && result.Tasks.Count > 0)
+        if (recoveredResults is not null && recoveredResults.Count > 0)
         {
-            return ApplyResults(tasks, result.Tasks);
+            return recoveredResults;
         }
 
-        // Fallback: when the model produces text but no structured task results,
-        // use the response text as the value for semantic tasks.
-        return TryExtractFromResponseText(sessionId, tasks, responseText);
+        return CreateFailedResults(sessionId, tasks, responseText);
     }
 
     /// <summary>
@@ -513,66 +520,134 @@ private PostSessionProcessingResponse TryParsePostSessionResponse(string session
         return null;
     }
 
-    /// <summary>
-    /// Fallback: when the model returns text that cannot be parsed as structured JSON,
-    /// use the response text directly as the value for semantic tasks.
-    /// Only applies when all pending tasks are semantic type.
-    /// </summary>
-    private Dictionary<string, PostSessionResult> TryExtractFromResponseText(
+    private async Task<Dictionary<string, PostSessionResult>> TryRecoverStructuredToolsResponseAsync(
         string sessionId,
+        IChatClient chatClient,
+        List<ChatMessage> requestMessages,
+        IList<ChatMessage> responseMessages,
         List<PostSessionTask> tasks,
-        string responseText)
+        CancellationToken cancellationToken)
     {
-        var semanticTasks = tasks.Where(t => t.Type == PostSessionTaskType.Semantic).ToList();
+        var followUpMessages = new List<ChatMessage>(requestMessages);
+        var trailingAssistantText = responseMessages?
+            .LastOrDefault(message => message.Role == ChatRole.Assistant && !string.IsNullOrWhiteSpace(message.Text));
 
-        if (semanticTasks.Count == 0)
+        if (responseMessages is not null)
+        {
+            foreach (var responseMessage in responseMessages)
+            {
+                if (ReferenceEquals(responseMessage, trailingAssistantText))
+                {
+                    continue;
+                }
+
+                followUpMessages.Add(responseMessage);
+            }
+        }
+
+        if (_logger.IsEnabled(LogLevel.Debug))
+        {
+            _logger.LogDebug(
+                "Attempting structured recovery for post-session tool response on session '{SessionId}' using the original post-session analysis context. TaskCount={TaskCount}.",
+                sessionId,
+                tasks.Count);
+        }
+
+        var response = await chatClient.GetResponseAsync<PostSessionProcessingResponse>(followUpMessages, new ChatOptions
+        {
+            Temperature = 0f,
+        }, null, cancellationToken);
+
+        var recoveryResponseText = response.Messages?
+            .LastOrDefault(message => message.Role == ChatRole.Assistant && !string.IsNullOrWhiteSpace(message.Text))
+            ?.Text?.Trim();
+
+        if (_logger.IsEnabled(LogLevel.Debug))
+        {
+            _logger.LogDebug(
+                "Post-session structured recovery raw response for session '{SessionId}': '{ResponseText}'.",
+                sessionId,
+                CreateResponseLogPreview(recoveryResponseText));
+        }
+
+        PostSessionProcessingResponse result;
+
+        try
+        {
+            result = response.Result;
+        }
+        catch (InvalidOperationException)
         {
             if (_logger.IsEnabled(LogLevel.Debug))
             {
                 _logger.LogDebug(
-                    "Post-session response for session '{SessionId}' produced no structured results and has no semantic tasks for text fallback.",
+                    "Structured recovery for post-session tool response on session '{SessionId}' did not return JSON content.",
                     sessionId);
             }
 
             return null;
         }
-
-        // For a single semantic task, use the entire response text as its value.
-        if (semanticTasks.Count == 1 && tasks.Count == 1)
+        catch (JsonException)
         {
-            var task = semanticTasks[0];
-            var now = _clock.UtcNow;
-
             if (_logger.IsEnabled(LogLevel.Debug))
             {
                 _logger.LogDebug(
-                    "Post-session task '{TaskName}' for session '{SessionId}' using response text as fallback value (length={Length}).",
-                    task.Name,
-                    sessionId,
-                    responseText.Length);
+                    "Structured recovery for post-session tool response on session '{SessionId}' returned invalid JSON content.",
+                    sessionId);
             }
 
-            return new Dictionary<string, PostSessionResult>(StringComparer.OrdinalIgnoreCase)
+            return null;
+        }
+
+        if (result?.Tasks is null || result.Tasks.Count == 0)
+        {
+            if (_logger.IsEnabled(LogLevel.Debug))
             {
-                [task.Name] = new PostSessionResult
-                {
-                    Name = task.Name,
-                    Value = responseText,
-                    Status = PostSessionTaskResultStatus.Succeeded,
-                    ProcessedAtUtc = now,
-                },
-            };
+                _logger.LogDebug(
+                    "Structured recovery for post-session tool response on session '{SessionId}' returned no task results.",
+                    sessionId);
+            }
+
+            return null;
         }
 
         if (_logger.IsEnabled(LogLevel.Debug))
         {
             _logger.LogDebug(
-                "Post-session response for session '{SessionId}' produced no structured results. Cannot apply text fallback to {TaskCount} tasks.",
+                "Structured recovery for post-session tool response on session '{SessionId}' succeeded with {TaskCount} task result(s).",
                 sessionId,
-                tasks.Count);
+                result.Tasks.Count);
         }
 
-        return null;
+        return ApplyResults(tasks, result.Tasks);
+    }
+
+    private Dictionary<string, PostSessionResult> CreateFailedResults(
+        string sessionId,
+        List<PostSessionTask> tasks,
+        string responseText)
+    {
+        var now = _clock.UtcNow;
+        var errorMessage = string.IsNullOrWhiteSpace(responseText)
+            ? "Tool execution completed, but the AI response did not contain the required structured JSON results."
+            : "The AI response could not be parsed as structured JSON after tool execution.";
+
+        _logger.LogWarning(
+            "Post-session tool response for session '{SessionId}' failed structured parsing. Marking {TaskCount} task(s) as failed. ResponseLength={ResponseLength}.",
+            sessionId,
+            tasks.Count,
+            responseText?.Length ?? 0);
+
+        return tasks.ToDictionary(
+            task => task.Name,
+            task => new PostSessionResult
+            {
+                Name = task.Name,
+                Status = PostSessionTaskResultStatus.Failed,
+                ErrorMessage = errorMessage,
+                ProcessedAtUtc = now,
+            },
+            StringComparer.OrdinalIgnoreCase);
     }
 
     /// <summary>
@@ -607,6 +682,20 @@ private static string ExtractJsonObject(string text)
         return text[start..(end + 1)];
     }
 
+    private static string CreateResponseLogPreview(string responseText)
+    {
+        if (string.IsNullOrEmpty(responseText))
+        {
+            return "(empty)";
+        }
+
+        var normalized = responseText
+            .Replace("\r", "\\r", StringComparison.Ordinal)
+            .Replace("\n", "\\n", StringComparison.Ordinal);
+
+        return normalized.Length > 2000 ? normalized[..2000] + "..." : normalized;
+    }
+
     private Dictionary<string, PostSessionResult> ApplyResults(
         List<PostSessionTask> tasks,
         List<PostSessionTaskResult> results)