package com.easyagents.agent.runtime.event;

import io.agentscope.core.hook.HookEvent;
import reactor.core.publisher.Mono;

/**
 * AgentScope Hook 事件的主线路干预器。对接 AgentScope 的原生生命周期hook
 *
 * <p>干预器允许修改 AgentScope HookEvent，因此会影响主线路执行。
 * 典型场景包括 AutoContext 在推理前改写输入消息，或后续 HITL 在推理后调用
 * {@code stopAgent()} 暂停工具执行。普通运行状态通知应使用 {@link AgentRuntimeObserver}。</p>
 * <p>警告：本干预器会影响到主线路agent 交互，谨慎使用
 * </p>
 */
public interface AgentRuntimeInterceptor {

    /**
     * 处理并返回可能被修改的 AgentScope Hook 事件。
     *
     * @param event AgentScope Hook 事件
     * @param <T> Hook 事件类型
     * @return 处理后的 Hook 事件
     */
    <T extends HookEvent> Mono<T> intercept(T event);

    /**
     * 获取干预器执行优先级。
     *
     * @return 优先级，数值越小越先执行
     */
    default int priority() {
        return 100;
    }
}
