<?php

declare(strict_types=1);

namespace Drupal\flowdrop\Plugin\FlowDropNodeProcessor;

use Drupal\flowdrop\DTO\Tool\ToolCollectionInterface;

/**
 * Interface for processors that consume tools wired via tool_availability.
 *
 * Implement this when a node (e.g. an agent / LLM reasoning step) needs to
 * discover and call the tool nodes connected to it. The runtime resolves those
 * connections into a {@see ToolCollectionInterface} and injects it via
 * setTools() before process()/resume() is called — mirroring how
 * {@see ExecutionContextAwareInterface} injects the execution context.
 *
 * Presence of this interface is also the signal — detected by class via
 * instanceof/is_subclass_of, without instantiation — that a node legitimately
 * accepts tool_availability edges. The compiler uses it to validate tool wiring
 * and the editor uses it to decide whether to render tool handles.
 *
 * Use {@see ToolsAwareTrait} for the standard implementation.
 *
 * @see \Drupal\flowdrop\DTO\Tool\ToolCollectionInterface
 * @see \Drupal\flowdrop\Plugin\FlowDropNodeProcessor\ToolsAwareTrait
 * @see \Drupal\flowdrop\Plugin\FlowDropNodeProcessor\ExecutionContextAwareInterface
 *
 * @api
 */
interface ToolsAwareInterface {

  /**
   * Sets the tools available to this processor.
   *
   * Called by the runtime before execute() is invoked, when the node has
   * connected tools. Store the collection for use in process()/resume().
   *
   * @param \Drupal\flowdrop\DTO\Tool\ToolCollectionInterface $tools
   *   The tools wired to this node.
   */
  public function setTools(ToolCollectionInterface $tools): void;

}
