<?php

declare(strict_types=1);

namespace Drupal\flowdrop\DTO\Tool;

/**
 * The outcome of invoking a tool.
 *
 * Returned by {@see ToolBindingInterface::invoke()}. A tool-consuming processor
 * feeds this back into its reasoning loop (e.g. as the result of an LLM tool
 * call). A failed result is a normal, recoverable condition — the consumer is
 * expected to surface the error to its model and let it re-plan, not to crash.
 *
 * @see \Drupal\flowdrop\DTO\Tool\ToolBindingInterface
 *
 * @api
 */
interface ToolResultInterface {

  /**
   * Whether the tool ran successfully.
   *
   * @return bool
   *   TRUE on success, FALSE if the tool errored or was rejected.
   */
  public function isSuccess(): bool;

  /**
   * The tool's output data.
   *
   * @return array<string, mixed>
   *   The output of the underlying tool node (empty on failure).
   */
  public function getData(): array;

  /**
   * The error message, when the tool did not succeed.
   *
   * @return string|null
   *   A human-readable error, or NULL on success.
   */
  public function getError(): ?string;

  /**
   * Serializes the result to a plain array.
   *
   * @return array{success: bool, data: array<string, mixed>, error: string|null}
   *   The result as a plain array.
   */
  public function toArray(): array;

}
