<?php
/**
 * Companion Tool Search Middleware
 *
 * @package Aisentic\Agent\Middleware
 */

declare(strict_types=1);

namespace Aisentic\Agent\Middleware;

use NeuronAI\Agent\Events\AIInferenceEvent;
use NeuronAI\Agent\Middleware\ToolSearchMiddleware;
use NeuronAI\Tools\ToolInterface;

defined( 'ABSPATH' ) || exit;

/**
 * Tool discovery that also loads the tools a discovered tool tells the model to call.
 *
 * Integration tools routinely name a sibling in their own description — the
 * Pointics create-channel tool opens with "Call pointics-list-channel-building-blocks
 * first for live trigger, integration, calculation, and condition vocabularies."
 * Plain tool_search injects only the tools its query matched, so the model reads
 * that instruction, calls a tool that was never loaded, and NeuronAI's
 * findTool() throws ProviderException — which aborts the whole stream rather
 * than returning a result the model could recover from.
 *
 * Any pool tool named in a discovered tool's description is therefore loaded
 * alongside it. Resolution is deliberately one level deep: a companion's own
 * companions are not pulled in, so a cluster of tools that reference each other
 * cannot drag the entire pool into context and undo the point of lazy loading.
 */
class Companion_Tool_Search_Middleware extends ToolSearchMiddleware {

	/**
	 * Discovered tools, plus any pool tool their descriptions name.
	 *
	 * @param AIInferenceEvent $event Inference event carrying the tool results.
	 * @return ToolInterface[]
	 */
	protected function extractDiscoveredTools( AIInferenceEvent $event ): array { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid -- Overrides a vendor method.
		$discovered = parent::extractDiscoveredTools( $event );

		if ( [] === $discovered ) {
			return $discovered;
		}

		$seen = [];
		foreach ( $discovered as $tool ) {
			$seen[ $tool->getName() ] = true;
		}

		foreach ( $discovered as $tool ) {
			foreach ( $this->companions( $tool ) as $companion ) {
				if ( ! isset( $seen[ $companion->getName() ] ) ) {
					$seen[ $companion->getName() ] = true;
					$discovered[]                  = $companion;
				}
			}
		}

		return $discovered;
	}

	/**
	 * Pool tools whose name appears in the given tool's description.
	 *
	 * The name must stand alone: matching on a bare substring would make
	 * "pointics-list-channels" pull in "pointics-list-channel-building-blocks"
	 * and vice versa, since one name is a prefix of the other.
	 *
	 * @param ToolInterface $tool Tool whose description is scanned.
	 * @return ToolInterface[]
	 */
	private function companions( ToolInterface $tool ): array {
		$description = (string) $tool->getDescription();

		if ( '' === $description ) {
			return [];
		}

		$companions = [];

		foreach ( $this->toolPool as $candidate ) { // phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase -- Vendor property name.
			$name = $candidate->getName();

			if ( $name === $tool->getName() ) {
				continue;
			}

			if ( preg_match( '/(?<![a-z0-9_-])' . preg_quote( $name, '/' ) . '(?![a-z0-9_-])/i', $description ) ) {
				$companions[] = $candidate;
			}
		}

		return $companions;
	}
}