agent-context 0.1.2

//! 请求者 → AgentContext 的请求消息与参数。
//!
//! 以 `Request` 前缀命名，与 [`super::outbound`] 中的 `Notify` 前缀对应。

use crate::role::Role;

// ---------------------------------------------------------------------------
// 变更消息
// ---------------------------------------------------------------------------

/// 追加一条消息到 incremental 区末尾。Reply = `()`。
///
/// 通知所有订阅者 [`super::NotifyChange::Appended`]。
pub struct RequestAppend<M> {
    /// 要追加的消息
    pub message: M,
}

/// 批量追加消息到 incremental 区。Reply = `()`。
///
/// 每条消息单独通知所有订阅者 [`super::NotifyChange::Appended`]。
pub struct RequestExtend<M> {
    /// 要批量追加的消息列表
    pub messages: Vec<M>,
}

/// 替换 incremental 区指定索引的消息。Reply = `Result<(), AgentError>`。
///
/// 仅对 incremental 区有效。通知所有订阅者 [`super::NotifyChange::Updated`]。
pub struct RequestUpdate<M> {
    /// incremental 区索引
    pub index: usize,
    /// 新消息
    pub message: M,
}

/// 在 incremental 区指定索引插入消息。Reply = `Result<(), AgentError>`。
///
/// 通知所有订阅者 [`super::NotifyChange::Inserted`]。
pub struct RequestInsert<M> {
    /// incremental 区插入位置
    pub index: usize,
    /// 要插入的消息
    pub message: M,
}

/// 移除 incremental 区指定索引的消息。Reply = `Result<(), AgentError>`。
///
/// 通知所有订阅者 [`super::NotifyChange::Removed`]。
pub struct RequestRemove {
    /// incremental 区索引
    pub index: usize,
}

/// 弹出 incremental 区最后一条消息。Reply = `Option<Message>`。
///
/// 通知所有订阅者 [`super::NotifyChange::Popped`]。
pub struct RequestPop;

/// 按角色保留 incremental 区消息，其余移除。Reply = `()`。
///
/// 通知所有订阅者 [`super::NotifyChange::Retained`]。
pub struct RequestRetain {
    /// 要保留的角色
    pub role: Role,
}

/// 清空整个 incremental 区。Reply = `()`。
///
/// 通知所有订阅者 [`super::NotifyChange::Cleared`]。
pub struct RequestClear;

// ---------------------------------------------------------------------------
// 查询消息
// ---------------------------------------------------------------------------

/// 获取三区总消息数。Reply = `usize`。
pub struct RequestLen;

/// 检查三区是否全部为空。Reply = `bool`。
pub struct RequestIsEmpty;

/// 按全局索引获取消息。Reply = `Option<Message>`。
///
/// 索引按 immutable → compressed → incremental 顺序计算。
/// 越界返回 `None`。
pub struct RequestGet(pub usize);

/// 获取三区全部消息的拼接结果。Reply = `Vec<Message>`。
///
/// 顺序：immutable → compressed → incremental。
pub struct RequestMessages;

/// 获取 immutable 区的消息副本。Reply = `Vec<Message>`。
pub struct RequestImmutable;

/// 获取 compressed 区的消息副本。Reply = `Vec<Message>`。
pub struct RequestCompressed;

/// 获取 incremental 区的消息副本。Reply = `Vec<Message>`。
pub struct RequestIncremental;

/// 按角色筛选三区全部消息。Reply = `Vec<Message>`。
pub struct RequestFindByRole(pub Role);

// ---------------------------------------------------------------------------
// 对话消息
// ---------------------------------------------------------------------------

/// 非流式对话。Reply = `Result<Response, AgentError>`。
///
/// 发送前根据 [`crate::CommonOpts`] 检查上下文是否已满，满则自动压缩或返回错误。
/// 然后拼接三区消息 + scratch，发送给后端 LLM。
/// 成功后自动将响应消息存入 incremental 区，通知所有订阅者 [`super::NotifyChange::Appended`]。
pub struct RequestSend<O> {
    /// 传递给后端 `send()` 的请求选项
    pub opts: O,
}

/// 流式对话。Reply = `Result<AgentSendStream, AgentError>`。
///
/// 发送前根据 [`crate::CommonOpts`] 检查上下文是否已满，满则自动压缩或返回错误。
/// 然后拼接三区消息 + scratch，发送给后端 LLM。
pub struct RequestSendStream<O> {
    /// 传递给后端 `send_stream()` 的请求选项
    pub opts: O,
}

// ---------------------------------------------------------------------------
// 压缩消息
// ---------------------------------------------------------------------------

/// 压缩策略参数。
#[derive(Debug, Clone)]
pub enum CompressStrategy {
    /// 摘要压缩：保留最近 `keep` 条，将更早的消息交由后端 LLM 生成摘要存入 compressed 区。
    Summarize {
        /// 保留的最新消息条数
        keep: usize,
        /// 自定义摘要提示词，`None` 时使用内置默认提示词
        prompt: Option<String>,
    },
}

/// 触发上下文压缩。Reply = `Result<(), AgentError>`。
///
/// 根据 [`CompressStrategy`] 对 incremental 区执行压缩。
/// 摘要由后端 LLM 生成，通过 `opts` 传递请求选项。
/// 也可通过 [`crate::CommonOpts::auto_compress`] 在 [`RequestSend`]/[`RequestSendStream`] 时自动触发。
pub struct RequestCompress<O> {
    /// 压缩策略
    pub strategy: CompressStrategy,
    /// 传递给后端 `send()` 的请求选项
    pub opts: O,
}

// ---------------------------------------------------------------------------
// 工具消息
// ---------------------------------------------------------------------------

/// 估算三区全部消息的 token 数量。Reply = `usize`。
///
/// 委托给后端的 [`estimate_tokens`](crate::ContextBackend::estimate_tokens)。
/// 失败时降级返回 0。
pub struct RequestEstimateTokens;

/// 将三区全部消息导出为 JSONL 字符串，每行一条 JSON。Reply = `Result<String, AgentError>`。
///
/// 消息按 immutable → compressed → incremental 顺序输出。
pub struct RequestToJsonl;

/// 从 JSONL 字符串加载消息到 incremental 区。Reply = `Result<(), AgentError>`。
///
/// 每行一条 JSON，空行跳过。解析失败或触发 `preserve_reasoning` 时返回错误。
/// 加载的消息逐条通知所有订阅者 [`super::NotifyChange::Appended`]。
pub struct RequestFromJsonl {
    /// JSONL 字符串，每行一条消息
    pub jsonl: String,
}