Struct Session 

pub struct Session { /* private fields */ }

运行时会话 — 一次 Agent 对话的完整内存状态。

由 Session::new() 创建，通过方法驱动消息追加、状态转换和用量累计。

Examples

use katu_agent::session::Session;
use katu_core::{AgentDefinition, AgentRole, ModelId};

let agent = AgentDefinition::new("build", AgentRole::Primary)
    .with_max_steps(50);

let session = Session::new(agent, ModelId::new("gpt-4o"));

assert!(session.status().is_idle());
assert_eq!(session.step_count(), 0);
assert!(session.messages().next().is_none());

Implementations

impl Session

pub fn new(agent: AgentDefinition, model_id: ModelId) -> Self

创建新会话。

Arguments

• agent — Agent 静态配置
• model_id — 初始模型标识

pub fn with_context_window(self, context_window: u64) -> Self

设置 context window 大小（模型最大 token）。

pub fn with_compaction_config(self, config: CompactionConfig) -> Self

设置上下文压缩配置。

pub fn with_cancel_token(self, token: CancellationToken) -> Self

注入已有的取消令牌。

impl Session

pub fn id(&self) -> &SessionId

会话 ID。

pub fn agent(&self) -> &AgentDefinition

Agent 静态配置。

pub fn model_id(&self) -> &ModelId

当前使用的模型。

pub fn set_model_id(&mut self, model_id: ModelId)

切换模型。

impl Session

pub fn messages(&self) -> impl Iterator<Item = &Message>

消息迭代器。

pub fn message_count(&self) -> usize

消息总数。

pub fn last_role(&self) -> Option<Role>

最后一条消息的角色。

pub fn last_assistant(&self) -> Option<&AssistantMessage>

最后一条 Assistant 消息。

pub fn has_pending_tool_calls(&self) -> bool

最后一条 Assistant 消息是否包含工具调用。

pub fn push_user(&mut self, content: impl Into<UserContent>)

追加用户消息。

pub fn push_assistant(&mut self, message: AssistantMessage)

追加 Assistant 消息并累加用量。

pub fn push_tool_results(&mut self, results: Vec<ToolResultMessage>)

批量追加工具结果消息。

pub fn push_message(&mut self, message: Message)

追加任意消息（用于恢复等场景）。

pub fn replace_messages(&mut self, messages: Vec<Message>)

替换全部消息（用于压缩后重建上下文）。

pub fn message_slice(&self) -> &[Message]

消息切片引用。

pub fn truncate_tool_result( &mut self, index: usize, truncation_msg: &str, max_chars: usize, )

截断指定索引处的 ToolResult 消息内容。

用于 Prune 阶段截断旧工具输出，释放 token 空间。 如果索引处不是 ToolResult 消息，静默忽略。

impl Session

pub fn status(&self) -> SessionStatus

当前运行状态。

pub fn cancel_token(&self) -> &CancellationToken

取消令牌引用（共享给 StreamConsumer / ToolExecutor）。

pub fn begin_run(&mut self)

标记进入运行状态。

Panics

如果当前不是 Idle 状态则 panic（调用方应先检查）。

pub fn end_run(&mut self)

标记一轮结束，回到空闲状态。

pub fn cancel(&mut self)

取消当前执行。

pub fn reset_after_cancel(&mut self)

从取消状态恢复为空闲（准备下一轮）。

impl Session

pub fn step_count(&self) -> u32

当前步数。

pub fn increment_step(&mut self) -> u32

递增步数，返回新步数。

pub fn max_steps(&self) -> u32

最大步数限制（来自 AgentDefinition 或默认值）。

pub fn is_over_step_limit(&self) -> bool

是否已达到步数上限。

impl Session

pub fn total_usage(&self) -> &Usage

累计 token 用量。

impl Session

pub fn context_tokens(&self) -> u64

当前上下文 token 估计。

pub fn context_window(&self) -> u64

模型 context window 大小。

pub fn compaction_config(&self) -> &CompactionConfig

压缩配置。

pub fn set_context_tokens(&mut self, tokens: u64)

更新上下文 token 计数（由外部 token 计数器设置）。

pub fn budget_state(&self) -> TokenBudgetState

计算当前 token 预算状态。

pub fn should_compact(&self) -> bool

是否应触发自动压缩。

pub fn compaction_state(&self) -> &CompactionState

压缩运行时状态引用。

pub fn compaction_state_mut(&mut self) -> &mut CompactionState

压缩运行时状态可变引用。

impl Session

pub fn created_at(&self) -> DateTime<Utc>

创建时间。

pub fn updated_at(&self) -> DateTime<Utc>

最后更新时间。