会话转录工作集

状态：提议的设计。 本页定义一项剩余的运行时迁移； 它并不声称追加驱逐或消费者切换已实现。 它不新增配置选项，也不更改模式、持久化字节、保留策略、会话身份或权限。

规范转录属于 SQLite 及其现有存储所有者。 活动的 SessionManager 应保留当前上下文和有界导航事实。 为某个操作获取较早历史时，不得将完整历史安装到活动管理器中。 参见磁盘上的会话状态 和worker 中的数据库访问。

当前边界¶

有界打开已按字节/事件预算选择原始条目。管理器的 条目数组和 ID 索引共享一个载荷图，而初始模型上下文 获取会单独水合重叠消息。追加和完整历史水合可能使驻留视图超出其打开预算。 所有者分别是 src/agents/sessions/ 下的 session-manager-core.ts、session-manager.ts， 以及 src/config/sessions/ 下的 session-accessor.sqlite-active-context.ts。

管理器被 AgentSession 和活动运行回调合法保留。 缩减其工作集是对正确运行拆除的补充；它不替代 运行结算，也不允许清除已接受写入仍需要的数据。

驻留快照¶

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

选择保留自定义消息、分支摘要、压缩/重置保留、工具对、重放检查点和 prompt 系列元数据。原始视图和 模型视图仅在它们的表示一致时共享冻结载荷； 仅凭条目 ID 相等不足以在投影、删节或重写后建立等价性。 worker 传输会在接收端创建对象，因此组合获取必须避免两次发送重叠的原始/模型载荷。

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

提议的异步操作¶

扩展 prepareSessionTranscriptHydration 及其现有 worker 所有者。 以下名称描述的是提议的内部契约，而非当前导出。 prepareHistoryRead 同步捕获绑定目标、所有者化身、 SessionTranscriptContextVersion（generation、rawSeq、updatedAt）、已准入的 回合回执/锚点、选定分支、追加游标和本地管理器修订。 其返回的读取能力绑定到该活动所有者：

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) 返回匹配结果和捕获的版本。 上下文返回共享的原始/模型载荷和驻留事实。条目返回一个 条目或显式缺失。分支/自定义页面返回有序事件、计数 和不透明续传；只有 complete: true 才确立选择的结束。 自定义选择保留历史顺序和重复项，除非该自定义类型已定义不同的语义归约器。导航 返回目标事实、公共祖先和有界标签/子摘要。

每个页面都在用于读取它的同一 SQLite 快照内验证其版本。 续传绑定目标、分支、版本和下一位置；它 绝不跟随最新活动分支。在获取下一页之前释放每个页面， 而不是累积整个转录。不要跨 provider、插件或其他异步工作持有 SQLite 事务。后续页面 会拒绝已更改的版本；追加容错续传需要来自现有读取围栏契约的独立证明， 而不是发明历史快照存储。

prepareRewrite({ replacements, expectedVersion }, signal) 在现有 worker 中使用规范 源行和锚点，返回准备句柄、源到目标映射以及字节/计数增量。它不克隆活动 管理器。commitRewrite(handle, signal) 通过当前写入器重新检查写入器权限和源 前置条件，然后返回已提交 ID/版本和有界替换上下文。取消会关闭未使用的准备； 已接受的写入保留保管权，直到原生结算，即使其调用方 停止等待。在 finally 中以及所有者关闭或 worker 退出时释放句柄。

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

结果区分已完成选择、精确条目缺失、版本冲突、 所有者丢失、取消和超大事件拒绝。缺失上下文或已撤销的所有者绝不是空的成功读取。无影响的过期读取可由其操作所有者重新获取；不确定或已完成的写入必须 通过其回执进行协调，绝不能作为新变更重试。

超大条目与清理¶

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

不要驱逐自定义行，并从一个不完整的驻留后缀报告成功的零移除清理。零移除需要证明所选 后缀没有匹配项。等待的清理必须获取足够多带版本边界的后缀事实，以解析谓词边界，并在谓词不需要负载时，在存储所有者中保留自定义字节。任意检查自定义数据的调用方谓词需要显式的按操作大小的获取，或经过版本化的 API 变更；不能假设它们可以被序列化到 worker 查询中。

超大原始获取必须有显式结果，而不是静默截断字节或跳过事件。保留现有严格读取器拒绝 和仅模型溢出投影规则。任何临时完整事件异常必须与驻留预算分开计量。不要为了通过内存断言而施加新的 存储内容上限。

消费者切换¶

packages/agent-core 中的纯算法保持显式的已准备输入。 它们不会获得数据库访问权限或对边界的竞争性解释。

SDK 与隐身模式迁移边界¶

当前 ReadonlySessionManager 暴露同步的条目/分支/树读取器。 ProviderReplaySessionStateV2 仍然继承同步的 getCustomEntries； provider 迁移 添加的是等待的写入，而不是等待的历史读取。同步读取器已经 存在于已发布的稳定 v2026.9.5 源代码中。对导出的 读取器表面及其完整性保证的完整审计仍然是必要的。 在更改已发布的签名、完整性保证或兼容性窗口之前，验证该证据并获得 SDK 所有者接受。遗留的完整 同步数组契约不能同时承诺普遍有界的驻留。 不要将其静默重新定义为部分窗口，或在没有经过验证的公共契约和移除边界的情况下保留内部孪生。

生产隐身模式继续使用其精确的进程拥有的数据库，直到 现有规范 worker 迁移激活。永远不要打开另一个 :memory: 数据库来满足读取。捕获当前所有者并拒绝其 关闭/替换。此设计不会激活该迁移，也不会更改 隐身模式过期、重启丢失或保留。

第一切片与完成证据¶

从由 worker 拥有的重写获取和已提交上下文发布开始，同时迁移重放修复和工具结果截断。移除它们的克隆管理器准备路径；仅在已发布 SDK 审计要求时保留兼容性。此私有切片不会完成任意树或扩展历史访问，也不得声称具有通用内存边界。

冻结已发布的规范负载，并使用替换对象进行消毒、删节和显式重写。驱逐仅丢弃引用：它不会编辑已发布的提示前缀、删除已存储事件，或更改现有的稳定提示刷新规则。压缩保留其显式上下文替换角色。

证明必须覆盖 2k/10k/50k 历史、1,000 次已提交追加、超大自定义清理、省略分支导航和重写历史。分别测量 manager、main-isolate、worker 和瞬态操作的保留量；使用并发会话测试实际 Gateway 延迟，并通过真实运行结算发布。演练修订变更、await 之后的目标/权限丢失、隐身所有者闭包、取消以及发布前提交失败。保留压缩、重放、删节和提示字节行为。这些进程本地投影不会导致模式或更新迁移；早期代码读取相同的已存储字节。