package tech.easyflow.agent.runtime.hitl;

import com.easyagents.agent.runtime.event.AgentRuntimeEvent;
import tech.easyflow.agent.entity.AgentHitlPending;
import tech.easyflow.core.runtime.ChatRuntimeContext;

import java.math.BigInteger;
import java.util.List;

/**
 * Agent 工具审批 pending 持久化服务。
 */
public interface AgentHitlPendingService {

    /**
     * 从 TOOL_APPROVAL_REQUIRED 事件创建或刷新 pending。
     *
     * @param requestId 请求 ID
     * @param chatContext 聊天上下文
     * @param event 运行时事件
     */
    void recordApprovalRequired(String requestId, ChatRuntimeContext chatContext, AgentRuntimeEvent event);

    /**
     * 批准并原子消费 pending。
     *
     * @param resumeToken 恢复令牌
     * @param operatorId 操作人 ID
     * @return pending 记录
     */
    AgentHitlPending approve(String resumeToken, BigInteger operatorId);

    /**
     * 拒绝并原子消费 pending。
     *
     * @param resumeToken 恢复令牌
     * @param operatorId 操作人 ID
     * @param reason 拒绝原因
     * @return pending 记录
     */
    AgentHitlPending reject(String resumeToken, BigInteger operatorId, String reason);

    /**
     * 取消指定请求的 pending。
     *
     * @param requestId 请求 ID
     * @param reason 取消原因
     */
    void cancelByRequestId(String requestId, String reason);

    /**
     * 删除指定聊天会话的 pending。
     *
     * @param chatSessionId 聊天会话 ID
     */
    void deleteByChatSessionId(BigInteger chatSessionId);

    /**
     * 删除指定运行会话的 pending。
     *
     * @param runtimeSessionId 运行会话 ID
     */
    void deleteByRuntimeSessionId(String runtimeSessionId);

    /**
     * 过期 pending 并返回被过期的记录。
     *
     * @param limit 每批数量
     * @return 过期记录
     */
    List<AgentHitlPending> expirePending(int limit);
}
