<?php

/**
 * Approvable Tool Contract
 *
 * @package Aisentic\Contracts
 */

namespace Aisentic\Contracts;

defined( 'ABSPATH' ) || exit;

/**
 * Interface for tools that require explicit human approval before execution.
 *
 * Tools implementing this interface are registered with NeuronAI's native
 * ToolApproval middleware by Abstract_Agent::middleware(). When the agent tries
 * to run one, the workflow raises a WorkflowInterrupt that pauses execution
 * until the user approves or rejects the action via the /chat/approve endpoint.
 */
interface Approvable_Tool_Contract {

	/**
	 * Human-readable label shown as the card header in the approval UI.
	 * Example: "Create Eventin Event"
	 *
	 * @return string
	 */
	public function get_approval_label(): string;

	/**
	 * One-line summary of what this specific invocation will do.
	 * Must read from $this->getInputs() (available via NeuronAI\Tools\Tool).
	 * Example: "Create event \"Tech Conference\" on 2025-06-15 09:00–17:00 (UTC)"
	 *
	 * @return string
	 */
	public function format_approval_summary(): string;

	/**
	 * Human-readable version of the tool inputs for the approval card.
	 * Resolve any IDs to names/titles so the card is understandable at a glance.
	 * Example: replace event_id => 5 with event => "Tech Conference 2025 (ID: 5)"
	 *
	 * @return array
	 */
	public function get_approval_inputs(): array;
}