knowledge-session-state-and-context

## Module Structure 该域负责把一次会话的权威事实、活动运行时与各端读模型分开：持久事实进入 JSONL，运行时持有互斥与恢复状态，TUI/Web/ACP 从相同事实投影，模型上下文则可在不破坏完整历史的前提下压缩。 ### Directory Layout - `packages/cli/src/context/`：事件模型、持久存储、上下文组装、压缩与 Token 预算 - `packages/cli/src/agent/runtime/`：Session 所有权、活动轮次 mailbox、恢复和私有 artifact - `packages/cli/src/services/SessionService.ts`：会话目录、加载、分叉、回退、归档与导出编排 - `packages/cli/src/services/SessionInteractionService.ts`：持久交互请求、响应和崩溃恢复 - `packages/cli/src/memory/`：跨会话项目记忆与压缩后巩固 ### Key Entry Points - `SessionRuntime.initialize()` in `packages/cli/src/agent/runtime/SessionRuntime.ts`：获取会话所有权并执行恢复 - `PersistentStore` in `packages/cli/src/context/storage/PersistentStore.ts`：将领域动作转换为有序事件 - `SessionService` in `packages/cli/src/services/SessionService.ts`：面向 CLI、Web 与 ACP 的持久会话服务 - `CompactionService.compact()` in `packages/cli/src/context/CompactionService.ts`：生成并约束模型可见替换上下文 ## Gotchas - `sessionId` 不是全局身份；省略 `projectPath` 的查找可能因多个工作区同名而拒绝，跨端路由必须保持 `sessionId + canonical projectPath` 复合身份 (`packages/cli/src/services/SessionService.ts`, `packages/cli/src/server/sessionRef.ts`) - Runtime、TUI store、Web store 和 SQLite 都不是持久真相，修复恢复问题时必须从 materialized JSONL 重新推导，不能把某个内存快照写回当作权威 (`packages/cli/src/context/storage/PersistentStore.ts`, `packages/cli/src/context/storage/sqlite/projection.ts`) - rewind 与 compaction 都保留原始 transcript：前者通过 `session_rewound` 改变有效事件，后者通过 replacement checkpoint 改变模型可见上下文；直接截断 JSONL 会同时破坏审计、导出和断点续传 (`packages/cli/src/services/sessionRewind.ts`, `packages/cli/src/services/SessionService.ts`) - durable inbox、prompt artifact 等 sidecar 不是独立会话真相；它们必须通过 transcript 中的 acknowledgement、message metadata 或生命周期事件对账后才能删除或重放 (`packages/cli/src/agent/runtime/DurableSteeringInbox.ts`, `packages/cli/src/agent/runtime/UserPromptArtifactStore.ts`) - 会话恢复必须先取得 `SessionLease` 再修复 orphan 进程、工具调用和 turn；颠倒顺序会让两个进程同时“恢复”同一条父链 (`packages/cli/src/agent/runtime/SessionRuntime.ts`, `packages/cli/src/agent/runtime/SessionLease.ts`, `git:46145c53`) ## Architecture - 写路径为 `SessionRuntime/SessionService -> ContextManager/PersistentStore -> SessionEventLog -> JSONLStore`，事件落盘并取得 seq 后才允许发布给各 surface (`packages/cli/src/agent/runtime/SessionRuntime.ts`, `packages/cli/src/context/ContextManager.ts`, `packages/cli/src/context/events/SessionEventLog.ts`) - 读路径有三种不同投影：完整可见历史供 UI/导出，replacement checkpoint 之后的上下文供模型，SQLite materialization 供目录与搜索；三者不能互相替代 (`packages/cli/src/services/SessionService.ts`, `packages/cli/src/context/storage/sqlite/projection.ts`) - 活动轮次采用“双账本”恢复：inbox 保存尚未确认的输入，JSONL 保存 turn/tool/interaction 事实；启动时通过 message ID 和终态 receipt 对账形成 exactly-once continuation (`packages/cli/src/agent/runtime/DurableSteeringInbox.ts`, `packages/cli/src/context/storage/PersistentStore.ts`) - 跨端一致性依赖同一事件语义而非同一 UI reducer：TUI 使用共享 conversation reducer，Web 消费 SSE 投影，ACP 消费顺序化 update，但都以已提交 JSONL 生命周期为恢复边界 (`packages/cli/src/store/slices/sessionSlice.ts`, `packages/cli/web/src/store/session/handlers/eventHandlers.ts`, `packages/cli/src/acp/Session.ts`) ## Decisions - 项目从多套 surface 事件系统收敛为 append-only committed events 加 ephemeral deltas，以换取可重放、可断点续传和持久化先于可见性的统一契约 (`packages/cli/src/context/events/SessionEventLog.ts`, `git:c776d496`) - SQLite 被刻意定义为可删除、可重建、失败开放的读缓存，而不是第二写模型，因此绕过 event log 的历史写入仍能被拉取式同步捕获 (`packages/cli/src/context/storage/sqlite/projection.ts`, `git:1f856671`) - ContextManager 已从状态容器收缩为 PersistentStore 的薄门面，压缩、过滤和记忆均由独立服务拥有，新增上下文行为不应重新塞回 ContextManager (`packages/cli/src/context/ContextManager.ts`, `git:a074815b`) ## Conventions - 需要“只允许一个胜者”的生命周期转换使用 `commitValidated` 或 `commitValidatedBatch`，在同一 per-file 队列内读取最新事实、校验并追加 (`packages/cli/src/context/events/SessionEventLog.ts`, `packages/cli/src/context/storage/JSONLStore.ts`) - 所有恢复与目录聚合先调用 `materializeSessionEvents()`，确保历史中的多次 rewind 按顺序生效后再计算 turn、interaction、搜索或 metadata (`packages/cli/src/services/sessionRewind.ts`, `packages/cli/src/services/SessionService.ts`) - UI 可见性、模型可见性和持久性是三个独立维度；例如 token handoff 可持久但不对客户端广播，delta 可广播但不持久 (`packages/cli/src/context/TokenBudgetHandoff.ts`, `packages/cli/src/context/events/SessionEventLog.ts`) ## Child Knowledge Nodes - `./durable-transcript-and-event-projection/SKILL.md`：修改 JSONL 提交、seq、replay、SQLite 或 TUI/Web 事件投影时进入 - `./session-catalog-fork-rewind-and-export/SKILL.md`：修改目录分页、归档、恢复、分叉、回退、搜索或 Markdown 导出时进入 - `./active-turn-interactions-and-recovery/SKILL.md`：修改 turn 互斥、steering、持久交互、崩溃恢复、旁路问答或用户 Shell 时进入 - `./context-compaction-token-budget-and-memory/SKILL.md`：修改上下文组装、压缩策略、Token handoff、工具结果预算或 Auto Memory 时进入