StreamingResponse.EndStream returns result

src/libraries/Builder/Microsoft.Agents.Builder/IStreamingResponse.cs

@@ -1,130 +1,142 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
-// Licensed under the MIT License.
-
-using Microsoft.Agents.Core.Models;
-using System.Collections.Generic;
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace Microsoft.Agents.Builder
-{
-    public interface IStreamingResponse
-    {
-        /// <summary>
-        /// Set IActivity that will be (optionally) used for the final streaming message.
-        /// </summary>
-        IActivity FinalMessage { get; set; }
-
-        /// <summary>
-        /// The interval in milliseconds at which intermediate messages are sent.
-        /// </summary>
-        /// <remarks>
-        /// Teams default: 1000
-        /// WebChat default: 500
-        /// </remarks>
-        int Interval { get; set; }
-
-        /// <summary>
-        /// The time in milliseconds that EndStream or Reset wait.  After this period expires, the
-        /// final message will be sent.
-        /// </summary>
-        int EndStreamTimeout { get; set; }
-
-        /// <summary>
-        /// Indicate if the current channel supports intermediate messages.
-        /// </summary>
-        /// <remarks>
-        /// Channels that don't support intermediate messages will buffer
-        /// text, and send a normal final message when EndStreamAsync is called.
-        /// </remarks>
-        bool IsStreamingChannel { get; }
-
-        /// <summary>
-        /// The buffered message.
-        /// </summary>
-        string Message { get; }
-
-        /// <summary>
-        /// Sets the "Generated by AI" Entity.
-        /// Defaults to false.
-        /// </summary>
-        bool? EnableGeneratedByAILabel { get; set; }
-
-        /// <summary>
-        /// The sensitivity label for the GeneratedByAI entity.
-        /// </summary>
-        SensitivityUsageInfo? SensitivityLabel { get; set; }
-
-        /// <summary>
-        /// The citations for the response.
-        /// </summary>
-        List<ClientCitation>? Citations { get; }
-
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using Microsoft.Agents.Core.Models;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.Builder
+{
+    public enum StreamingResponseResult
+    {
+        Success,
+        NotStarted,
+        AlreadyEnded,
+        UserCancelled,
+        Timeout,
+        Error
+    };
+
+    public interface IStreamingResponse
+    {
+        /// <summary>
+        /// Set IActivity that will be (optionally) used for the final streaming message.
+        /// </summary>
+        IActivity FinalMessage { get; set; }
+
+        /// <summary>
+        /// The interval in milliseconds at which intermediate messages are sent.
+        /// </summary>
+        /// <remarks>
+        /// Teams default: 1000
+        /// WebChat default: 500
+        /// </remarks>
+        int Interval { get; set; }
+
+        /// <summary>
+        /// The time in milliseconds that EndStream or Reset wait.  After this period expires, the
+        /// final message will be sent.
+        /// </summary>
+        int EndStreamTimeout { get; set; }
+
+        /// <summary>
+        /// Indicate if the current channel supports intermediate messages.
+        /// </summary>
+        /// <remarks>
+        /// Channels that don't support intermediate messages will buffer
+        /// text, and send a normal final message when EndStreamAsync is called.
+        /// </remarks>
+        bool IsStreamingChannel { get; }
+
+        /// <summary>
+        /// The buffered message.
+        /// </summary>
+        string Message { get; }
+
+        /// <summary>
+        /// Sets the "Generated by AI" Entity.
+        /// Defaults to false.
+        /// </summary>
+        bool? EnableGeneratedByAILabel { get; set; }
+
+        /// <summary>
+        /// The sensitivity label for the GeneratedByAI entity.
+        /// </summary>
+        SensitivityUsageInfo? SensitivityLabel { get; set; }
+
+        /// <summary>
+        /// The citations for the response.
+        /// </summary>
+        List<ClientCitation>? Citations { get; }
+
         /// <summary>
         /// Adds a citation for the response.
         /// </summary>
-        /// <param name="citation"></param>
+        /// <param name="citation"></param>
         void AddCitation(ClientCitation citation);
 
         /// <summary>
         /// Adds a citation for the response.
         /// </summary>
         /// <param name="citation"></param>
-        /// <param name="citationPosition"></param>
-        void AddCitation(Citation citation, int citationPosition);
-
-        /// <summary>
-        ///  Sets the citations for the full message.
-        /// </summary>
-        /// <param name="citations">Citations to be included in the message.</param>
-        void AddCitations(IList<Citation> citations);
-
-        /// <summary>
-        ///  Sets the citations for the full message.
-        /// </summary>
-        /// <param name="citations">Citations to be included in the message.</param>
-        void AddCitations(IList<ClientCitation> citations);
-
-        /// <summary>
-        /// Ends the stream by sending the final message to the client.
-        /// </summary>
-        /// <remarks>
-        /// Since the messages are sent on an interval, this call will block until all have been sent
-        /// before sending the final Message.
-        /// </remarks>
-        /// <returns>A Task representing the async operation</returns>
-        /// <exception cref="System.InvalidOperationException">Throws if the stream has already ended.</exception>
-        Task EndStreamAsync(CancellationToken cancellationToken = default);
-
-        bool IsStreamStarted();
-
-        /// <summary>
-        /// Queues an informative update to be sent to the client.
-        /// </summary>
-        /// <param name="text">Text of the update to send.</param>
-        /// <param name="cancellationToken"></param>
-        /// <exception cref="System.InvalidOperationException">Throws if the stream has already ended.</exception>
-        Task QueueInformativeUpdateAsync(string text, CancellationToken cancellationToken = default);
-
-        /// <summary>
-        /// Queues a chunk of partial message text to be sent to the client.
-        /// </summary>
-        /// <param name="text">Partial text of the message to send.</param>
-        /// <param name="citations">Citations to include in the message.</param>
-        /// <exception cref="System.InvalidOperationException">Throws if the stream has already ended.</exception>
-        void QueueTextChunk(string text);
-
-        /// <summary>
-        /// Reset an already used stream.  If the stream is still running, this will wait for completion.
-        /// </summary>
-        /// <param name="cancellationToken"></param>
-        /// <returns></returns>
-        Task ResetAsync(CancellationToken cancellationToken = default);
-
-        /// <summary>
-        /// Gets the number of updates sent for the stream.
-        /// </summary>
-        /// <returns>Number of updates sent so far.</returns>
-        int UpdatesSent();
-    }
+        /// <param name="citationPosition"></param>
+        void AddCitation(Citation citation, int citationPosition);
+
+        /// <summary>
+        ///  Sets the citations for the full message.
+        /// </summary>
+        /// <param name="citations">Citations to be included in the message.</param>
+        void AddCitations(IList<Citation> citations);
+
+        /// <summary>
+        ///  Sets the citations for the full message.
+        /// </summary>
+        /// <param name="citations">Citations to be included in the message.</param>
+        void AddCitations(IList<ClientCitation> citations);
+
+        /// <summary>
+        /// Ends the stream by sending the final message to the client.
+        /// </summary>
+        /// <remarks>
+        /// Since the messages are sent on an interval, this call will block until all have been sent
+        /// before sending the final Message.
+        /// </remarks>
+        /// <returns>
+        /// A Task representing the async operation. The result indicates the outcome of ending the stream,
+        /// such as Success, AlreadyEnded, Timeout, or Error.
+        /// </returns>
+        Task<StreamingResponseResult> EndStreamAsync(CancellationToken cancellationToken = default);
+
+        bool IsStreamStarted();
+
+        /// <summary>
+        /// Queues an informative update to be sent to the client.
+        /// </summary>
+        /// <param name="text">Text of the update to send.</param>
+        /// <param name="cancellationToken"></param>
+        /// <exception cref="System.InvalidOperationException">Throws if the stream has already ended.</exception>
+        Task QueueInformativeUpdateAsync(string text, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Queues a chunk of partial message text to be sent to the client.
+        /// </summary>
+        /// <param name="text">Partial text of the message to send.</param>
+        /// <param name="citations">Citations to include in the message.</param>
+        /// <exception cref="System.InvalidOperationException">Throws if the stream has already ended.</exception>
+        void QueueTextChunk(string text);
+
+        /// <summary>
+        /// Reset an already used stream.  If the stream is still running, this will wait for completion.
+        /// </summary>
+        /// <param name="cancellationToken"></param>
+        /// <returns></returns>
+        Task ResetAsync(CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets the number of updates sent for the stream.
+        /// </summary>
+        /// <returns>Number of updates sent so far.</returns>
+        int UpdatesSent();
+    }
 }