using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Text.Json.Serialization;

namespace ModelContextProtocol.Protocol;

/// <summary>
/// Represents an MCP task, which is a durable state machine carrying information
/// about the underlying execution state of a request.
/// </summary>
/// <remarks>
/// <para>
/// Tasks are useful for representing expensive computations and batch processing requests.
/// Each task is uniquely identifiable by a receiver-generated task ID.
/// </para>
/// <para>
/// Tasks follow a defined lifecycle through the <see cref="Status"/> property. They begin
/// in the <see cref="McpTaskStatus.Working"/> status and may transition through various states
/// before reaching a terminal status (<see cref="McpTaskStatus.Completed"/>, <see cref="McpTaskStatus.Failed"/>,
/// or <see cref="McpTaskStatus.Cancelled"/>).
/// </para>
/// <para>
/// See the <see href="https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/draft/basic/utilities/tasks.mdx">tasks specification</see> for details.
/// </para>
/// </remarks>
[DebuggerDisplay("{DebuggerDisplay,nq}")]
[Experimental(Experimentals.Tasks_DiagnosticId, UrlFormat = Experimentals.Tasks_Url)]
public sealed class McpTask
{
    /// <summary>
    /// Gets or sets the unique identifier for the task.
    /// </summary>
    /// <remarks>
    /// Task IDs are generated by the receiver when creating a task and must be unique
    /// among all tasks controlled by that receiver.
    /// </remarks>
    [JsonPropertyName("taskId")]
    public required string TaskId { get; set; }

    /// <summary>
    /// Gets or sets the current state of the task execution.
    /// </summary>
    [JsonPropertyName("status")]
    public required McpTaskStatus Status { get; set; }

    /// <summary>
    /// Gets or sets an optional human-readable message describing the current state.
    /// </summary>
    /// <remarks>
    /// This message can be present for any status, including error details for failed tasks.
    /// </remarks>
    [JsonPropertyName("statusMessage")]
    public string? StatusMessage { get; set; }

    /// <summary>
    /// Gets or sets the ISO 8601 timestamp when the task was created.
    /// </summary>
    /// <remarks>
    /// Receivers must include this timestamp in all task responses to indicate when
    /// the task was created.
    /// </remarks>
    [JsonPropertyName("createdAt")]
    public required DateTimeOffset CreatedAt { get; set; }

    /// <summary>
    /// Gets or sets the ISO 8601 timestamp when the task status was last updated.
    /// </summary>
    /// <remarks>
    /// Receivers must include this timestamp in all task responses to indicate when
    /// the task was last updated.
    /// </remarks>
    [JsonPropertyName("lastUpdatedAt")]
    public required DateTimeOffset LastUpdatedAt { get; set; }

    /// <summary>
    /// Gets or sets the time to live (retention duration) from creation before the task may be deleted.
    /// </summary>
    /// <remarks>
    /// <para>
    /// A null value indicates unlimited lifetime. After a task's TTL lifetime has elapsed,
    /// receivers may delete the task and its results, regardless of the task status.
    /// </para>
    /// <para>
    /// Receivers may override the requested TTL duration and must include the actual TTL
    /// duration (or null for unlimited) in task responses.
    /// </para>
    /// </remarks>
    [JsonPropertyName("ttl")]
    [JsonConverter(typeof(TimeSpanMillisecondsConverter))]
    public TimeSpan? TimeToLive { get; set; }

    /// <summary>
    /// Gets or sets the suggested time between status checks.
    /// </summary>
    /// <remarks>
    /// Requestors should respect this value when provided to avoid excessive polling.
    /// This value is optional and may not be present in all task responses.
    /// </remarks>
    [JsonPropertyName("pollInterval")]
    [JsonConverter(typeof(TimeSpanMillisecondsConverter))]
    public TimeSpan? PollInterval { get; set; }

    private string DebuggerDisplay => $"Task {TaskId}: {Status}" + (StatusMessage != null ? $" - {StatusMessage}" : "");
}