<?php

declare(strict_types=1);

/**
 * 本文件属于 DBErp 进销存系统。
 *
 * 版权所有 © 2026 北京珑大钜商科技有限公司。保留所有权利。
 *
 * 未经官方授权，不得删除、篡改或隐藏本文件中的版权声明、产品标识与来源信息。
 * 商业授权、官方更新与技术支持服务，请以珑大官方支持中心记录为准。
 *
 * @link https://support.loongdom.cn
 * @see  https://www.dberp.com.cn
 */

namespace App\Tools\Contracts;

use App\Models\User;
use App\Tools\ToolDiscoveryDescriptor;
use App\Tools\ToolExecutionContext;
use App\Tools\ToolResult;

/**
 * 未来 MCP / AI 消费者的唯一 Tool Layer 接入边界。
 *
 * 本接口不实现 MCP 协议、传输、会话，也不实现 AI 对话或模型调用。
 *
 * 约定映射：
 * - MCP tools/list、AI Tool 选择 → listTools() → ToolDiscoveryService
 * - MCP tools/call、AI Tool 调用 → callTool() → ToolExecutor
 *
 * 消费者不得：解析 Tool 实例、调用 Eloquent / Business Service、自行实现权限或降低风险等级。
 */
interface ToolConsumerBoundary
{
    /**
     * @return list<ToolDiscoveryDescriptor>
     */
    public function listTools(User $user): array;

    /**
     * @param  array<string, mixed>  $input
     */
    public function callTool(string $name, ToolExecutionContext $context, array $input = []): ToolResult;
}
