<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Service\Orchestrator;

/**
 * Interface for agent execution traces.
 *
 * Captures the results and metadata of an agent node execution,
 * including iteration counts, token usage, and final output.
 *
 * @internal This interface is not part of the public API and may change without notice.
 */
interface AgentTraceInterface {

  /**
   * Gets the execution status.
   *
   * @return string
   *   The status (e.g., "completed", "failed").
   */
  public function getStatus(): string;

  /**
   * Gets the total number of iterations performed.
   *
   * @return int
   *   The iteration count.
   */
  public function getTotalIterations(): int;

  /**
   * Gets the total number of tokens used.
   *
   * @return int
   *   The token count.
   */
  public function getTotalTokensUsed(): int;

  /**
   * Gets the final answer produced by the agent.
   *
   * @return string|null
   *   The final answer, or NULL if not available.
   */
  public function getFinalAnswer(): ?string;

  /**
   * Gets the error message if execution failed.
   *
   * @return string|null
   *   The error message, or NULL if no error.
   */
  public function getErrorMessage(): ?string;

  /**
   * Converts the trace to an output array.
   *
   * @return array<string, mixed>
   *   The output data.
   */
  public function toOutput(): array;

}
