// Copyright (c) Microsoft. All rights reserved.
using System.Threading;
using System.Threading.Tasks;
namespace Microsoft.Agents.AI.Workflows;
///
/// Defines an execution environment for running, streaming, and resuming workflows asynchronously, with optional
/// checkpointing and run management capabilities.
///
public interface IWorkflowExecutionEnvironment
{
///
/// Specifies whether Checkpointing is configured for this environment.
///
bool IsCheckpointingEnabled { get; }
///
/// Initiates a streaming run of the specified workflow without sending any initial input. Note that the starting
/// will not be invoked until an input message is received.
///
/// The workflow to execute. Cannot be null.
/// An optional identifier for the session. If null, a new identifier will be generated.
/// A cancellation token that can be used to cancel the streaming operation.
/// A ValueTask that represents the asynchronous operation. The result contains a StreamingRun object for accessing
/// the streamed workflow output.
ValueTask OpenStreamingAsync(Workflow workflow, string? sessionId = null, CancellationToken cancellationToken = default);
///
/// Initiates an asynchronous streaming execution using the specified input.
///
/// The returned provides methods to observe and control
/// the ongoing streaming execution. The operation will continue until the streaming execution is finished or
/// cancelled.
/// A type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the streaming run.
/// An optional unique identifier for the session. If not provided, a new identifier will be generated.
/// The to monitor for cancellation requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask RunStreamingAsync(Workflow workflow, TInput input, string? sessionId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Resumes an asynchronous streaming execution for the specified input from a checkpoint.
///
/// If the operation is cancelled via the token, the streaming execution will
/// be terminated.
/// The workflow to be executed. Must not be null.
/// The corresponding to the checkpoint from which to resume.
/// The to monitor for cancellation requests. The default is .
/// A that provides access to the results of the streaming run.
ValueTask ResumeStreamingAsync(Workflow workflow, CheckpointInfo fromCheckpoint, CancellationToken cancellationToken = default);
///
/// Initiates a non-streaming execution of the workflow with the specified input.
///
/// The workflow will run until its first halt, and the returned will capture
/// all outgoing events. Use the Run instance to resume execution with responses to outgoing events.
/// The type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the run.
/// An optional unique identifier for the session. If not provided, a new identifier will be generated.
/// The to monitor for cancellation requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask RunAsync(Workflow workflow, TInput input, string? sessionId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Resumes a non-streaming execution of the workflow from a checkpoint.
///
/// The workflow will run until its first halt, and the returned will capture
/// all outgoing events. Use the Run instance to resume execution with responses to outgoing events.
/// The workflow to be executed. Must not be null.
/// The corresponding to the checkpoint from which to resume.
/// The to monitor for cancellation requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask ResumeAsync(Workflow workflow, CheckpointInfo fromCheckpoint, CancellationToken cancellationToken = default);
}