<?php

/**
 * Tool Error Handler
 *
 * @package Aisentic\Agent
 */

namespace Aisentic\Agent;

defined( 'ABSPATH' ) || exit;

use Aisentic\Util\Log;
use NeuronAI\Exceptions\ToolRunsExceededException;
use NeuronAI\Tools\ToolInterface;

/**
 * Turns a failing tool into a tool result the model can read.
 *
 * NeuronAI's ToolNode re-throws any tool exception when no error handler is
 * registered, so one bad tool call ends the SSE stream on a generic "something
 * went wrong" and the merchant loses everything the agent had already gathered.
 *
 * This is a class rather than a closure on purpose. The handler is stored on the
 * ToolNode, and a write tool awaiting approval raises a WorkflowInterrupt that
 * Transient_Workflow_Persistence must `serialize()` — PHP refuses to serialize a
 * Closure, which would break every approval flow. A stateless invokable object
 * serializes cleanly.
 */
class Tool_Error_Handler {

	/**
	 * Map a tool failure to the text the model receives as that tool's result.
	 *
	 * @param \Throwable    $e    The failure.
	 * @param ToolInterface $tool The tool that failed.
	 * @return string
	 */
	public function __invoke( \Throwable $e, ToolInterface $tool ): string {
		$name = $tool->getName();

		Log::error(
			'Tool execution failed',
			[
				'tool'  => $name,
				'type'  => get_class( $e ),
				'error' => $e->getMessage(),
			]
		);

		// The repeat guard means the model is looping. Steering it to answer is
		// the difference between a partial answer and no answer at all.
		if ( $e instanceof ToolRunsExceededException ) {
			return sprintf(
				'You have already called `%s` the maximum number of times this turn, and it will not run again. Answer now using the results you already have, and say plainly which part you could not confirm. Do not call it again, and do not rephrase the same request into another tool call.',
				$name
			);
		}

		// A bad argument is the model's own mistake, so the detail goes back to
		// it: that is exactly what lets the retry be correct.
		if ( $e instanceof \TypeError || $e instanceof \ArgumentCountError || $e instanceof \InvalidArgumentException ) {
			return sprintf(
				'The call to `%s` had invalid arguments: %s. Fix the arguments and call it once more.',
				$name,
				$e->getMessage()
			);
		}

		// Anything else is an internal fault. The message can carry queries, file
		// paths or credentials, so it stays in the log.
		return sprintf(
			'The tool `%s` failed for an internal reason and did not return anything. Do not retry it. Continue with the information you already have and tell the user which step did not complete.',
			$name
		);
	}
}