<?php

declare(strict_types=1);

namespace Drupal\flowdrop_session\DTO;

/**
 * Handle returned by the chat-turn verb.
 *
 * Returned by executeTurn() on
 * {@see \Drupal\flowdrop_session\Service\SessionTurnServiceInterface}.
 *
 * A turn is the user-message-initiated unit: it ends at *any* pipeline
 * stop, and the status says why. An input pause ends the turn
 * (awaiting_input — the input request is the assistant's reply for this
 * turn); a budget/other pause ends it too (paused). The next user message
 * starts a new turn, so turnId↔pipelineId is N:1 across resumes.
 *
 * - sessionId           — the session the turn ran on.
 * - userMessageId       — the persisted user message; doubles as the turn
 *                         id ("id of the message that initiated the turn").
 * - pipelineId          — the pipeline executing this turn. NULL on the
 *                         async paths (queued/running): the pipeline entity
 *                         is created after the HTTP response, and the
 *                         session turn events carry it once started.
 * - status              — queued | running | completed | awaiting_input |
 *                         paused | failed. Snapshot at return time; follow
 *                         the turn events for changes.
 * - assistantMessageIds — assistant messages written back during the turn.
 *                         Filled only on wait paths; empty otherwise.
 */
final class TurnResult {

  public const STATUS_QUEUED = 'queued';
  public const STATUS_RUNNING = 'running';
  public const STATUS_COMPLETED = 'completed';
  public const STATUS_AWAITING_INPUT = 'awaiting_input';
  public const STATUS_PAUSED = 'paused';
  public const STATUS_FAILED = 'failed';

  /**
   * Constructs a turn result.
   *
   * @param string $sessionId
   *   The session id.
   * @param string $userMessageId
   *   The user message id (= turn id).
   * @param string|null $pipelineId
   *   The pipeline id, when known.
   * @param string $status
   *   One of the STATUS_* constants.
   * @param array<int, string> $assistantMessageIds
   *   Assistant message ids written back during the turn.
   */
  public function __construct(
    public readonly string $sessionId,
    public readonly string $userMessageId,
    public readonly ?string $pipelineId,
    public readonly string $status,
    public readonly array $assistantMessageIds = [],
  ) {}

}
