package com.easyagents.agent.runtime.persistence.session;

import io.agentscope.core.state.State;

import java.util.List;
import java.util.Optional;
import java.util.Set;

/**
 * 智能体会话状态存储接口。
 * <p>
 * 该接口承接 AgentScope {@code Session} 的持久化读写能力，用于按会话键保存和恢复
 * Agent 运行过程中产生的状态，例如 memory、toolkit、plan notebook 或有状态工具数据。
 * 具体实现可以基于内存、Redis、MySQL 等存储介质。
 */
public interface AgentSessionStore {

    /**
     * 保存单个状态项。
     *
     * @param sessionKey 会话键
     * @param name 状态名称
     * @param state 状态值
     */
    void save(String sessionKey, String name, State state);

    /**
     * 保存状态列表。
     *
     * @param sessionKey 会话键
     * @param name 状态名称
     * @param states 状态列表
     */
    void saveList(String sessionKey, String name, List<? extends State> states);

    /**
     * 获取单个状态项。
     *
     * @param sessionKey 会话键
     * @param name 状态名称
     * @param type 状态类型
     * @param <T> 状态类型
     * @return 可选状态
     */
    <T extends State> Optional<T> get(String sessionKey, String name, Class<T> type);

    /**
     * 获取状态列表。
     *
     * @param sessionKey 会话键
     * @param name 状态名称
     * @param itemType 状态元素类型
     * @param <T> 状态元素类型
     * @return 状态列表
     */
    <T extends State> List<T> getList(String sessionKey, String name, Class<T> itemType);

    /**
     * 判断会话键是否存在。
     *
     * @param sessionKey 会话键
     * @return 存在时为 true
     */
    boolean exists(String sessionKey);

    /**
     * 删除指定会话键下的全部状态。
     *
     * @param sessionKey 会话键
     */
    void delete(String sessionKey);

    /**
     * 列出当前存储中的会话键。
     *
     * @return 会话键列表
     */
    Set<String> listSessionKeys();
}
