<?php

declare(strict_types=1);

namespace Drupal\flowdrop\Service\Tool;

use Drupal\flowdrop\DTO\Tool\ToolResultInterface;

/**
 * Executes a single tool node on behalf of a tool-consuming processor.
 *
 * This is the security boundary for tool calls. Because the tool name/args
 * ultimately originate from an LLM (attacker-influenceable via prompt
 * injection), invocation must NOT be trusted to the consuming processor.
 *
 * An implementation is created **scoped to one consumer node**, capturing an
 * allow-list derived from that node's outgoing `tool_availability` edges (plus
 * the execution context). Every call re-checks the requested node against that
 * allow-list, so a processor can never reach a node the workflow author did not
 * wire as one of its tools — even if it bypasses {@see ToolBindingInterface}.
 *
 * @see \Drupal\flowdrop\DTO\Tool\ToolBindingInterface::invoke()
 *
 * @api
 */
interface ToolInvokerInterface {

  /**
   * Invokes a tool node and returns its result.
   *
   * @param string $nodeId
   *   The tool node to run. Implementations MUST reject any node that is not in
   *   the scoped allow-list (an integrity violation, not a recoverable error).
   * @param array<string, mixed> $args
   *   The arguments for the tool, validated against the node's parameter schema
   *   before execution.
   *
   * @return \Drupal\flowdrop\DTO\Tool\ToolResultInterface
   *   The result of running the tool.
   */
  public function invokeTool(string $nodeId, array $args): ToolResultInterface;

}
