<?php

declare(strict_types=1);

namespace Drupal\flowdrop_session\Event;

use Symfony\Contracts\EventDispatcher\Event;

/**
 * Fired when a chat turn stops — for any reason.
 *
 * Part of the documented session turn event contract
 * (docs/reference/api/session-turn-events.md). A turn ends at any
 * pipeline stop and the status says why:
 * - completed       — the workflow ran to the end; assistantMessageIds
 *                     carries the write-backs.
 * - awaiting_input  — the workflow asked the user something (HITL). The
 *                     input request is the assistant's reply for this
 *                     turn; answering it resumes the same pipeline but is
 *                     a new interaction, not this turn.
 * - paused          — the pipeline stopped on a budget/signal pause;
 *                     pausedReason says which. The resume is a
 *                     Pause-signal resolution, not chat input.
 * - failed          — execution failed; the session carries the error
 *                     bubble.
 *
 * This is the signal that replaces polling: post a turn, wait for the
 * completed event with your sessionId + turnId.
 *
 * Payload evolution is additive-only: fields are never removed or
 * renamed within 1.x.
 *
 * @api
 */
final class SessionTurnCompletedEvent extends Event {

  /**
   * The event name.
   */
  public const string NAME = 'flowdrop_session.turn.completed';

  public const string STATUS_COMPLETED = 'completed';
  public const string STATUS_AWAITING_INPUT = 'awaiting_input';
  public const string STATUS_PAUSED = 'paused';
  public const string STATUS_FAILED = 'failed';

  /**
   * Constructs a new SessionTurnCompletedEvent.
   *
   * @param string $sessionId
   *   The session entity id the turn ran on.
   * @param string $turnId
   *   The turn id — the id of the user message that initiated the turn.
   * @param string|null $pipelineId
   *   The pipeline entity id, or NULL when execution failed before a
   *   pipeline entity was created.
   * @param string $status
   *   One of the STATUS_* constants.
   * @param array<int, string> $assistantMessageIds
   *   Assistant message ids written back during the turn, in
   *   conversation order.
   * @param string|null $pausedReason
   *   The PausedReason value for STATUS_PAUSED; NULL otherwise.
   */
  public function __construct(
    public readonly string $sessionId,
    public readonly string $turnId,
    public readonly ?string $pipelineId,
    public readonly string $status,
    public readonly array $assistantMessageIds = [],
    public readonly ?string $pausedReason = NULL,
  ) {}

}
