<?php

declare(strict_types=1);

namespace Drupal\flowdrop\DTO\Tool;

/**
 * A single tool offered to a tool-consuming processor.
 *
 * A binding is a narrow, just-in-time projection of a tool node: enough for a
 * model to discover and call it (name, description, input schema), plus a way
 * to actually run it ({@see self::invoke()}), without exposing the workflow
 * graph to the processor.
 *
 * Identity: {@see self::getName()} is the stable, model-facing handle (derived
 * from the node label); {@see self::getNodeId()} is the internal routing key,
 * never shown to the model. The two are distinct on purpose.
 *
 * @see \Drupal\flowdrop\DTO\Tool\ToolCollectionInterface
 *
 * @api
 */
interface ToolBindingInterface {

  /**
   * The model-facing tool name (e.g. for an LLM tool manifest).
   *
   * @return string
   *   A unique, schema-safe name within the consumer's tool set.
   */
  public function getName(): string;

  /**
   * The internal routing key — the tool node's ID.
   *
   * @return string
   *   The node ID. Not part of the model-facing contract.
   */
  public function getNodeId(): string;

  /**
   * The tool description shown to the model.
   *
   * @return string
   *   A human-readable description.
   */
  public function getDescription(): string;

  /**
   * The JSON-Schema describing the tool's arguments.
   *
   * @return array<string, mixed>
   *   The parameter schema of the underlying tool node.
   */
  public function getInputSchema(): array;

  /**
   * A human-readable title for logs and traces.
   *
   * Carries the "<label> (<nodeId>)" form, which is unsafe as a tool name but
   * useful for debugging. Not shown to the model.
   *
   * @return string
   *   The display title.
   */
  public function getDisplayTitle(): string;

  /**
   * The neutral tool definition: name, description and input schema.
   *
   * @return array{name: string, description: string, input_schema: array<string, mixed>}
   *   The definition, ready to adapt into a provider-specific tool manifest.
   */
  public function toDefinition(): array;

  /**
   * Runs the tool and returns its result.
   *
   * Routes through the orchestrator-owned invoker, which authorizes the call
   * against the consumer's allow-list and validates the arguments before
   * execution.
   *
   * @param array<string, mixed> $args
   *   The tool arguments.
   *
   * @return \Drupal\flowdrop\DTO\Tool\ToolResultInterface
   *   The result of running the tool.
   */
  public function invoke(array $args): ToolResultInterface;

}
