session.compact()

session.compact() 用于显式请求压缩当前 Session 历史。

const compact = await session.compact();
const result = await compact.finished;

if (!result.success) {
  console.error(result.error);
}
await session.prompt({ query: "基于压缩后的历史继续" });

本地 AgentSession 与远程 RemoteAgentSession 都支持这个方法。

队列语义

await session.compact() 返回一个 Handle，表示 command 已通过校验并进入 Session 有序输入队列。handle.result 在运行中为 null；await handle.finished 会等待摘要生成和 canonical 历史重写真正结束。

• Session 空闲时，command 在下一次 prompt() turn 开始前执行
• turn 运行中时，command 在下一个 Session step 检查点执行
• 如果当前 turn 在下一个检查点前结束，command 会保留到下一个 turn
• compact command、配置 command 和 steer prompt 严格保持入队顺序
• 单独调用 compact() 不会创建 turn，也不会主动发起 provider 请求

运行中执行 compact 前，SDK 会先收口当前 Assistant 草稿。canonical history 重写完成后，下一次 provider 调用会重新加载历史，不会继续使用压缩前的内存消息。

观察执行结果

压缩过程通过正常的 Session timeline 发布 action message：

• 准备摘要和归档时为 running
• canonical history 替换完成后为 completed
• 模型、composer 或存储操作失败时为 failed

如果当前没有可压缩的 active record，Session 会产生一条 completed action，说明不需要压缩。

Handle 的稳定结果包含：

• compact_id：本次显式压缩标识
• success：请求是否成功结束；没有可压缩内容同样为 true
• compacted：是否实际生成并提交了压缩计划
• reason：compacted | nothing_to_compact | compact_failed
• error：失败时的错误文本

subscribe() 仍会发布 compact 生命周期 Mutation 和 timeline action，适合驱动 UI；业务代码应优先等待 handle.finished，不需要从 Action Message 反推完成状态。

自动压缩与显式压缩

Provider 真实 usage 达到上下文阈值时，自动压缩仍会正常运行。session.compact() 复用同一个 compaction composer、存储事务和 action message，只是向 Session 队列增加一次显式请求。

Summary、Active 历史和恢复行为见 元数据与落盘。