09. 状态、事件与可观测性¶
Codex 在运行过程中持续产生结构化状态。模型文本、推理内容、命令开始、命令输出、补丁结果、差异更新、审批请求、token 用量和轮次完成都会形成事件。事件用于实时展示，持久化记录用于会话恢复，状态数据库用于跨会话索引和后台任务。
实时事件¶
会话在轮次运行过程中发出事件。事件描述运行时当前发生的事实，例如轮次开始、条目开始、助手文本增量、工具输出、差异更新、错误、轮次完成。
实时事件使客户端能够展示智能体正在执行的步骤。终端界面用事件更新界面，一次性执行用事件输出终端文本，外部客户端用事件同步任务状态。
实时事件还承担交互协调。审批请求、用户中断、工具输出和轮次完成通过事件向客户端暴露，客户端再将用户响应转回 Session 队列。事件流因此是用户介入智能体循环的通道。
通知协议¶
app-server 将核心事件转换成稳定通知。客户端消费 turn/started、item/started、item/agentMessage/delta、item/completed、turn/diff/updated、thread/tokenUsage/updated、turn/completed 和 error 等通知。
通知隔离了客户端和核心内部实现。客户端无需理解任务调度、工具任务或历史管理，只需要按协议更新展示状态。
通知还稳定了不同客户端之间的语义。终端界面、一次性执行和外部集成都可以从同一条目生命周期推导状态，即使各自展示方式不同。协议事件比解析助手文本可靠，因为命令、差异、审批和错误都有独立结构。
持久化记录¶
持久化记录（rollout）保存会话恢复所需的关键记录。记录包括会话元信息、模型响应条目、压缩替换历史、轮次上下文和重要事件。
恢复时，运行时需要恢复历史、上下文基线、动态工具、记忆模式和会话元数据。分叉从旧会话某个历史点创建新会话，也需要依赖持久化记录中的恢复材料。
持久化记录因此不是普通日志，而是模型现场的恢复记录。
持久化记录中的压缩记录尤其重要。压缩会替换旧历史，恢复时必须按替换历史重建模型窗口，而不是简单追加摘要。轮次上下文记录则用于恢复上下文基线和设置差异。
线程存储¶
线程存储（thread-store）负责线程的持久化读写。它保存线程和对应持久化记录，支持创建、追加、刷新、恢复和读取历史。
持久化记录说明会话中发生了什么，线程存储负责这些记录保存在哪里以及如何读取。客户端读取线程历史时，服务端会从线程存储和回放逻辑中重建线程、轮次和条目视图。
线程存储抽象使本地和远程持久化可以共享上层语义。会话只需追加持久化条目，读取侧再将持久化记录重建为协议对象。
状态数据库¶
状态数据库保存跨会话索引和后台任务状态。长期记忆处理状态、目标状态、子智能体派生关系和线程元数据都属于这类信息。
状态数据库不替代持久化记录。持久化记录保存顺序历史，状态数据库保存便于查询和后台任务协调的状态。
长期记忆后台任务体现了二者的配合。状态数据库记录哪些线程或持久化记录可处理、处理到哪个阶段；实际可提炼内容仍来自持久化记录中保存的会话历史。
事件与持久化的交叉¶
部分事件只用于实时展示，部分事件也会进入持久化记录。轮次上下文、响应条目、压缩、重要错误和完成状态都可能影响恢复、分叉或历史回放。
事件变更可能同时影响终端界面展示、一次性执行输出、外部客户端协议、历史回放、token 用量和长期记忆后台处理。因此事件系统是运行时的结构化记录层，而不是普通日志。
事件顺序同样重要。条目开始必须早于条目完成，工具输出增量必须关联到正确条目，轮次完成必须在工具和待处理输入收束后发出。顺序错误会导致客户端界面、历史回放和恢复状态不一致。
命令执行示例¶
模型请求运行测试时，状态层会产生一组事件：命令条目开始、标准输出/标准错误增量、条目完成、可能的差异更新、token 用量更新和后续轮次完成。
这些事件让客户端展示命令正在运行、输出正在返回、任务仍在推进。命令结果同时写入历史，使模型后续能够基于真实输出继续采样。
命令输出事件和历史中的工具输出相关但不等价。事件面向实时展示，可以是流式增量；历史需要的是可恢复的最终工具结果。两者由同一次工具执行产生，但服务不同消费方。
可观测性的作用¶
实时事件支持用户审批、中断和进度观察。结构化条目支持客户端可靠展示命令和差异。持久化记录支持恢复和分叉。状态数据库支持长期记忆、目标和子智能体等跨会话功能。
状态系统将智能体运行过程变成可观察、可回放、可恢复的结构化任务记录。