<?php
/**
 * Validated Tool Approval Middleware
 *
 * @package Aisentic\Agent\Middleware
 */

declare(strict_types=1);

namespace Aisentic\Agent\Middleware;

use NeuronAI\Agent\Tools\ToolRejectionHandler;
use NeuronAI\Agent\Middleware\ToolApproval;
use NeuronAI\Tools\ToolInterface;

defined( 'ABSPATH' ) || exit;

/**
 * Tool-approval gate that refuses to card a call it already knows cannot run.
 *
 * NeuronAI validates required parameters inside Tool::execute(), which happens
 * only after the human decision comes back. A model that omits a required
 * argument therefore produces a perfectly normal approval card; the admin
 * approves it, and the resume throws MissingCallbackParameter — the turn dies
 * with a generic "something went wrong", the model never learns what it got
 * wrong, and the admin approved an action that never had a chance of running.
 *
 * This subclass checks the same required-parameter rule up front. A malformed
 * call is dropped from the approval list and its callback swapped for a
 * handler that reports the missing arguments to the model, so the model can
 * re-issue a correct call in the same turn instead of dead-ending.
 *
 * One deliberate deviation from ToolApproval: an empty configured tool list
 * means "gate nothing" here, where the parent reads it as "gate everything".
 * The argument check has to run on every agent — the public storefront chat
 * has no approvable tools at all, and a malformed call there aborts the stream
 * exactly as it does in the admin — so this middleware is registered
 * unconditionally, and inheriting the parent's reading would silently put an
 * approval card in front of every shopper-facing tool call.
 */
class Validated_Tool_Approval extends ToolApproval {

	/**
	 * Neutralize malformed calls, then gate whatever remains.
	 *
	 * @param ToolInterface[] $tools Tools from the current tool-call message.
	 * @return ToolInterface[]
	 */
	protected function filterToolsRequiringApproval( array $tools ): array { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Overrides a vendor method.
		$runnable = [];

		foreach ( $tools as $tool ) {
			$missing = self::missing_required_inputs( $tool );

			if ( [] === $missing ) {
				$runnable[] = $tool;
				continue;
			}

			self::neutralize( $tool, $missing );
		}

		if ( [] === $this->tools ) {
			return [];
		}

		return parent::filterToolsRequiringApproval( $runnable );
	}

	/**
	 * Required properties the model left out of the call entirely.
	 *
	 * Matches Tool::execute()'s own rule (array_key_exists, not empty) so this
	 * flags exactly the calls that would have thrown, and nothing else — an
	 * explicit null or empty string is the tool's own business to validate.
	 *
	 * @param ToolInterface $tool Tool to inspect.
	 * @return string[] Missing required property names.
	 */
	private static function missing_required_inputs( ToolInterface $tool ): array {
		$inputs  = $tool->getInputs();
		$missing = [];

		foreach ( $tool->getProperties() as $property ) {
			if ( $property->isRequired() && ! array_key_exists( $property->getName(), $inputs ) ) {
				$missing[] = $property->getName();
			}
		}

		return $missing;
	}

	/**
	 * Turn a malformed call into a corrective tool result.
	 *
	 * The missing keys are backfilled with null purely so Tool::execute() gets
	 * past its own required-parameter check and reaches the callback — without
	 * them it throws before any callback runs and the turn is lost again.
	 *
	 * @param ToolInterface $tool    Tool to neutralize.
	 * @param string[]      $missing Missing required property names.
	 * @return void
	 */
	private static function neutralize( ToolInterface $tool, array $missing ): void {
		$tool->setInputs( array_merge( array_fill_keys( $missing, null ), $tool->getInputs() ) );

		$message = sprintf(
			/* translators: 1: tool name, 2: comma-separated list of argument names. */
			__( 'TOOL NOT EXECUTED. The call to "%1$s" was missing required argument(s): %2$s. Nothing was created or changed. Re-issue the call with every required argument filled in, asking the user for any value you cannot determine.', 'aisentic' ),
			$tool->getName(),
			implode( ', ', $missing )
		);

		$tool->setCallable( new ToolRejectionHandler( $message ) );
	}
}