会话记录工作集

Status：建议设计。 该页面定义剩余运行时迁移；它没有声称实施了追加驱逐或消费者切换。它不添加配置选项，也不更改架构、持久字节、保留、会话身份或权限。

存储的成绩单属于 SQLite 及其现有存储所有者。活动的 SessionManager 应保留当前上下文和有界导航事实。获取操作的较旧历史记录不得将完整历史记录安装到实时管理器中。请参阅 磁盘上的会话状态 和 工作人员 中的数据库访问。

当前边界

有界开口已按 byte/event 预算选择原始条目。管理器的条目数组和 ID 索引共享一个有效负载图，而初始模型上下文获取则分别水合重叠消息。附加和完整的历史补充可以将居民的视野扩大到超出其初始预算。所有者分别为 src/agents/sessions/ 和 src/config/sessions/ 下的 session-manager-core.ts、session-manager.ts 和 session-accessor.sqlite-active-context.ts。

该管理器由 AgentSession 和主动运行回调合法保留。减少其工作集补充了正确的运行拆卸；它不会取代运行结算或允许清除已接受的写入仍然需要的数据。

居民快照

发布一个不可变的快照，其中包含目标绑定、数据库化身、转录版本、选定的 leaf/append 游标、准入栅栏和本地管理器修订。仅保留这些条目及其所需的省略边界锚点的标头、model/thinking 设置、边界计数、当前上下文条目和导航链接。

该选择保留自定义消息、分支摘要、compaction/reset 保留、工具对、重播检查点和提示系列元数据。仅当原始视图和模型视图的表示一致时，它们才会共享冻结的有效负载；条目-ID 本身相等并不能在投影、编辑或重写后建立等效性。工作传输会创建接收方对象，因此组合采集必须避免两次发送重叠的 raw/model 有效负载。

该快照记录其 byte/event 计数和完整性。任意历史结果仍归运营所有；它们永远不会成为第二个管理器缓存。提交的追加、后缀替换、导航和重写操作必须在通知观察者之前发布有界替换。失败的写入保留旧快照。发布失败的已提交写入会通过现有的已提交写入错误路径使管理器失效；它永远不会重播。

建议的异步操作

扩展 prepareSessionTranscriptHydration 及其现有工人所有者。以下名称描述了拟议的内部合同，而不是当前的出口合同。 prepareHistoryRead同步捕获绑定目标、所有者化身、SessionTranscriptContextVersion（generation、rawSeq、updatedAt）、承认转向receipt/anchor、选定分支、追加光标和本地管理器修订。它返回的读取能力与当前所有者绑定：

type HistorySelection =  | { kind: "context"; maxBytes: number; maxEvents: number }  | { kind: "entry"; entryId: string }  | { kind: "branch-page"; leafId: string; cursor?: string; maxBytes: number; maxEvents: number }  | { kind: "navigation"; fromId: string | null; targetId: string }  | {      kind: "custom-page";      customType?: string;      cursor?: string;      maxBytes: number;      maxEvents: number;    };

read(selection, signal) 返回匹配结果和捕获的版本。上下文返回共享的 raw/model 有效负载和驻留事实。条目返回条目或明确缺席。 Branch/custom 页面返回有序事件、计数和不透明的延续；仅 complete: true 确定选择结束。自定义选择会保留历史顺序并重复，除非该自定义类型已经定义了不同的语义化简器。导航返回目标事实、共同祖先和有界 labels/child 摘要。

每个页面都会在用于读取它的同一 SQLite 快照中验证其版本。延续绑定目标、分支、版本和下一个位置；它从不遵循最新的活动分支。在获取下一页之前释放每一页，而不是累积整个记录。不要跨提供商、插件或其他异步工作持有 SQLite 事务。稍后的页面拒绝更改的版本；追加容忍的延续需要与现有的读栅栏合约分开的证明，而不是发明的历史快照存储。

prepareRewrite({ replacements, expectedVersion }, signal) 使用现有工作线程中存储的源行和锚点，返回准备句柄、源到目标映射和 byte/count 增量。它不会克隆实时管理器。 commitRewrite(handle, signal) 通过当前 writer 重新检查 writer 权限和源前提条件，然后返回已提交的 IDs/version 和有界替换上下文。取消将关闭未使用的准备工作；即使调用者停止等待，已接受的写入也会保留托管权，直到本地解决为止。在所有者关闭或工作人员退出时释放 finally 中的句柄。

在返回任何结果之前，请重新检查取消和当前读取权限。在发布之前，还要重新检查目标绑定、导航修订和转录本版本。捕获的令牌不是当前权限。在事务准入时和提交之前立即写入重新检查实时权限。现有的 SQLite 准入和外部提交新鲜度规则仍然是架构和连接验证的唯一所有者。

结果区分了已完成的选择、精确条目缺失、版本冲突、所有者丢失、取消和超大事件拒绝。缺少上下文或撤销所有者绝不是空洞的成功读取。无效的过时读取可能会被其操作所有者重新获取；不确定或已完成的写入必须通过其收据进行协调，切勿作为新的突变重试。

超大条目和清理

严格的字节预算不能同时保留任意完整的行。 session-manager-retained-data.test.ts 暴露了具体的冲突：以 4,096 字节预算打开的管理器后来附加了 5 个 MiB 自定义负载。同步 removeTrailingEntries 必须删除中止的助手，准确保留该自定义有效负载，修复其父级，并使 getEntry 与存储保持一致。这些断言并不能证明每个方法都是已发布的 SDK 合约，但它们确实确立了无条件驱逐会改变的行为。

不要逐出自定义行并报告从不完整的驻留后缀成功进行零删除清理。零删除需要证明所选后缀不匹配。等待的清理必须获取足够的版本防护后缀事实来解析谓词边界，当谓词不需要有效负载时在存储所有者中保留自定义字节。检查自定义数据的任意调用者谓词需要显式操作大小的获取或版本化的 API 更改；假设它们不能序列化到工作器查询中。

超大的原始采集必须有明确的结果，而不是默默地截断字节或跳过事件。保留现有的严格读者拒绝和仅模型溢出投影规则。任何临时的完整活动例外必须与居民预算分开衡量。不要强加新的存储内容上限来使内存断言通过。

消费者割接

packages/agent-core 中的纯算法保留显式准备的输入。他们无法访问数据库或对边界进行竞争性解释。

SDK 和隐身迁移边界

当前的 ReadonlySessionManager 公开了同步 entry/branch/tree 读卡器。 ProviderReplaySessionStateV2仍然继承同步getCustomEntries； provider迁移添加等待的写入，而不是等待的历史读取。同步读取器已存在于已发布的稳定 v2026.9.5 源中。对导出的读卡器表面及其完整性保证进行完整审核仍然是必要的。在更改交付的签名、完整性保证或兼容性窗口之前，请验证该证据并获得 SDK-owner 接受。传统的完整同步数组合约也不能承诺普遍有界的驻留。不要默默地将其重新定义为部分窗口或在没有经过验证的公共合同和移除边界的情况下保留内部双胞胎。

生产隐身模式将继续使用其确切的流程拥有的数据库，直到激活现有的共享工作线程迁移。切勿打开另一个 :memory: 数据库来满足读取。捕获当前所有者并拒绝其 closure/replacement. 此设计不会激活迁移或更改隐身到期、重新启动丢失或保留。

第一片和完成证据

从工作人员拥有的重写获取和提交的上下文发布开始，将重放修复和工具结果截断一起迁移。删除他们的克隆管理器准备路径；仅在发货的 SDK 审核需要时才保留兼容性。此私有切片不完成任意树或扩展历史访问，并且不得声明通用内存限制。

冻结已发布的存储有效负载并使用替换对象进行清理、编辑和显式重写。逐出仅删除引用：它不会编辑已发布的提示前缀、删除存储的事件或更改现有的稳定提示刷新规则。压缩保留了其明确的上下文替换作用。

证明必须涵盖 2k/10k/50k 历史记录、1,000 个提交的追加、超大自定义清理、省略分支导航和重写历史记录。分别测量管理器、主隔离、工作器和瞬态操作保留；通过并发会话测试实际网关延迟并通过实际运行结算进行释放。练习修订更改、等待后 target/authority 丢失、隐身所有者关闭、取消和发布前提交失败。保留压缩、重放、编辑和提示字节行为。这些进程本地投影不会产生模式或更新迁移；早期的代码读取相同的存储字节。