Add Prompt Source Handler (#378)

Author: MikeAlhayek

$PROFILE.txt

@@ -0,0 +1 @@
+export COPILOT_CUSTOM_INSTRUCTIONS_DIRS=./copilot-cli

.envrc

@@ -5,7 +5,7 @@ on:
     branches:
       - main
     tags:
-      - 'v*.*.*'
+      - 'v[0-9]+.[0-9]+.0'
   workflow_dispatch:
 
 permissions:
@@ -40,9 +40,13 @@ jobs:
       - name: Create versioned docs on tag push
         if: startsWith(github.ref, 'refs/tags/v')
         run: |
-          VERSION="${GITHUB_REF#refs/tags/v}"
-          echo "Creating docs version ${VERSION}"
-          npx docusaurus docs:version "${VERSION}"
+          FULL_VERSION="${GITHUB_REF#refs/tags/v}"
+          # Extract major.minor for the doc version (e.g., v3.1.0 -> 3.1.x)
+          MAJOR="$(echo "$FULL_VERSION" | cut -d. -f1)"
+          MINOR="$(echo "$FULL_VERSION" | cut -d. -f2)"
+          DOC_VERSION="${MAJOR}.${MINOR}.x"
+          echo "Creating docs version ${DOC_VERSION}"
+          npx docusaurus docs:version "${DOC_VERSION}"
 
       - name: Build site
         run: npm run build

.github/workflows/deploy_docs.yml

@@ -15,6 +15,7 @@
   </Folder>
   <Folder Name="/Core/">
     <Project Path="src/Core/CrestApps.Azure.Core/CrestApps.Azure.Core.csproj" />
+    <Project Path="src/Core/CrestApps.OrchardCore.AI.Chat.Core/CrestApps.OrchardCore.AI.Chat.Core.csproj" />
     <Project Path="src/Core/CrestApps.OrchardCore.AI.Chat.Interactions.Core/CrestApps.OrchardCore.AI.Chat.Interactions.Core.csproj" />
     <Project Path="src/Core/CrestApps.OrchardCore.AI.Core/CrestApps.OrchardCore.AI.Core.csproj" />
     <Project Path="src/Core/CrestApps.OrchardCore.AI.Mcp.Core/CrestApps.OrchardCore.AI.Mcp.Core.csproj" />

CrestApps.OrchardCore.slnx

@@ -0,0 +1,42 @@
+using CrestApps.OrchardCore.AI.Models;
+
+namespace CrestApps.OrchardCore.AI;
+
+/// <summary>
+/// Defines a pluggable handler responsible for processing chat prompts and producing responses.
+/// Implementations may generate responses in real time (streaming) or defer them
+/// for asynchronous delivery (e.g., via webhook from a third-party agent platform).
+/// </summary>
+/// <remarks>
+/// <para>The default implementation routes prompts through the AI orchestration pipeline.
+/// Custom implementations can route prompts to external systems such as live-agent
+/// platforms (e.g., Genesys, Twilio Flex) or any other backend capable of handling
+/// human-to-human or hybrid conversations.</para>
+///
+/// <para>The active handler for a session is determined by
+/// <see cref="AIChatSession.ResponseHandlerName"/> or
+/// <see cref="ChatInteraction.ResponseHandlerName"/>. An AI function or external
+/// event can change this value mid-conversation to transfer the chat to a different handler.</para>
+/// </remarks>
+public interface IChatResponseHandler
+{
+    /// <summary>
+    /// Gets the unique technical name of this handler (e.g., <c>"AI"</c>, <c>"Genesys"</c>).
+    /// </summary>
+    string Name { get; }
+
+    /// <summary>
+    /// Processes a chat prompt and returns a result indicating whether the response
+    /// is available immediately (streaming) or will be delivered later (deferred).
+    /// </summary>
+    /// <param name="context">The context describing the prompt, session, and connection details.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>
+    /// A <see cref="ChatResponseHandlerResult"/> that is either streaming (contains an
+    /// <see cref="IAsyncEnumerable{T}"/> of updates) or deferred (the hub will not wait
+    /// for a response).
+    /// </returns>
+    Task<ChatResponseHandlerResult> HandleAsync(
+        ChatResponseHandlerContext context,
+        CancellationToken cancellationToken = default);
+}

.github/copilot-cli-instructions.md copilot-cli/commiting.instructions.md.github/copilot-cli-instructions.md renamed to copilot-cli/commiting.instructions.md

@@ -0,0 +1,39 @@
+using CrestApps.OrchardCore.AI.Models;
+
+namespace CrestApps.OrchardCore.AI;
+
+/// <summary>
+/// Resolves the appropriate <see cref="IChatResponseHandler"/> for a chat session based
+/// on the configured handler name.
+/// </summary>
+/// <remarks>
+/// Resolution order: explicit name → default AI handler.
+/// When <paramref name="handlerName"/> is <see langword="null"/> or empty, the built-in AI
+/// handler is returned. When a name is specified but no matching handler is found,
+/// implementations should fall back to the default AI handler.
+/// When <paramref name="chatMode"/> is <see cref="ChatMode.Conversation"/>,
+/// the AI handler is always returned regardless of the requested name because
+/// conversation mode requires the AI orchestration pipeline for speech-to-text
+/// and text-to-speech integration.
+/// </remarks>
+public interface IChatResponseHandlerResolver
+{
+    /// <summary>
+    /// Resolves a chat response handler by name.
+    /// </summary>
+    /// <param name="handlerName">
+    /// The handler name, or <see langword="null"/> / empty for the default AI handler.
+    /// </param>
+    /// <param name="chatMode">
+    /// The active chat mode. When set to <see cref="ChatMode.Conversation"/>, the
+    /// built-in AI handler is always returned regardless of <paramref name="handlerName"/>.
+    /// </param>
+    /// <returns>The resolved <see cref="IChatResponseHandler"/> instance.</returns>
+    IChatResponseHandler Resolve(string handlerName = null, ChatMode chatMode = ChatMode.TextInput);
+
+    /// <summary>
+    /// Gets all registered <see cref="IChatResponseHandler"/> instances.
+    /// </summary>
+    /// <returns>An enumerable of all registered handlers.</returns>
+    IEnumerable<IChatResponseHandler> GetAll();
+}

src/Abstractions/CrestApps.OrchardCore.AI.Abstractions/IChatResponseHandler.cs

@@ -61,6 +61,14 @@ public sealed class AIChatSession : Entity
     /// </summary>
     public ChatSessionStatus Status { get; set; }
 
+    /// <summary>
+    /// Gets or sets the technical name of the <see cref="IChatResponseHandler"/> currently
+    /// handling prompts for this session. When <see langword="null"/> or empty, the default
+    /// AI handler is used. This value can be changed mid-conversation (e.g., by an AI
+    /// function that transfers the chat to a live-agent platform).
+    /// </summary>
+    public string ResponseHandlerName { get; set; }
+
     /// <summary>
     /// Gets or sets the extracted data fields for this session.
     /// Keys are field names from the data extraction configuration.

src/Abstractions/CrestApps.OrchardCore.AI.Abstractions/IChatResponseHandlerResolver.cs

@@ -0,0 +1,17 @@
+namespace CrestApps.OrchardCore.AI.Models;
+
+/// <summary>
+/// Identifies the type of chat context a <see cref="ChatResponseHandlerContext"/> represents.
+/// </summary>
+public enum ChatContextType
+{
+    /// <summary>
+    /// The context is for an <see cref="AIChatSession"/> managed by the AI Chat module.
+    /// </summary>
+    AIChatSession,
+
+    /// <summary>
+    /// The context is for a <see cref="ChatInteraction"/> managed by the Chat Interactions module.
+    /// </summary>
+    ChatInteraction,
+}

src/Abstractions/CrestApps.OrchardCore.AI.Abstractions/Models/AIChatSession.cs

@@ -107,6 +107,14 @@ private string _deploymentIdBackingField
     /// </summary>
     public string OrchestratorName { get; set; }
 
+    /// <summary>
+    /// Gets or sets the technical name of the <see cref="IChatResponseHandler"/> currently
+    /// handling prompts for this interaction. When <see langword="null"/> or empty, the default
+    /// AI handler is used. This value can be changed mid-conversation (e.g., by an AI
+    /// function that transfers the chat to a live-agent platform).
+    /// </summary>
+    public string ResponseHandlerName { get; set; }
+
     /// <summary>
     /// Gets or sets the list of AI tool names to use.
     /// </summary>