Flush 不是一次函数调用#

Agent 的首事件延迟是整条链路缓冲的总和：

这解释了一个常见现象：服务端日志显示每 20 ms 产生一次 delta，浏览器却每 1 秒成批出现。问题可能不在模型，而在压缩器或代理等到足够多字节后才转发。

Content-Type、Cache-Control: no-cache 等响应头很重要，但不能被当作“所有代理都不会缓冲”的通用开关。某些反向代理有自己的 response buffering 配置；例如 Nginx 官方文档说明可以通过 proxy_buffering 或 X-Accel-Buffering 控制其代理响应缓冲，但这不是跨基础设施标准。[23] 正确做法是在真实生产链路上测量每一跳的到达时间，而不是只测应用进程里的 write 时间。

压缩也不是无条件收益。Token delta 往往很小，压缩器为了压缩比而聚合数据，可能让节省的带宽换来更差的 TTFE。对于低带宽、高频事件，可以按短时间窗口 coalesce 后再压缩；对于首屏和控制事件，则应优先及时 flush。

连接存活与半开连接#

只要中间层在其 idle timeout 内没有看到任何字节，即使 Agent 正在本地执行工具，连接也可能被关闭。因此流式协议通常需要 heartbeat。heartbeat 的间隔应短于链路中最小的 idle timeout，并加入少量 jitter，避免大量连接同一时刻唤醒；它只证明传输通道仍可写，不能证明 Agent 有业务进展。

另一侧也存在“半开”问题：Wi-Fi 切换、NAT 状态丢失或进程崩溃后，服务端不一定立即收到一个干净的 close。很多实现直到下一次 write 失败，或 heartbeat 超时，才知道对端已经消失。因此：

• 不要把 socket close 当作 cancel 的唯一来源；
• 需要释放的连接级资源可以在断线后回收；
• 是否继续 Run，应由 Run 策略或显式 cancel 决定；
• 对昂贵的临时订阅，要设置无订阅者超时，但不能因此删除耐久状态。

传输流控不是业务流控#

TCP、HTTP/2 和 QUIC 都有各自的流量控制；HTTP/2 明确区分 stream 与 connection flow-control window，HTTP/3 则依赖 QUIC 的 stream 与 connection flow control。[21][22] 当客户端读得慢时，底层发送最终会阻塞或返回 backpressure 信号。但在信号传回应用之前，数据可能已经堆积在框架、代理和内核缓冲区中。若应用继续把每个 token delta 放入无界队列，“网络有 TCP flow control”仍然挡不住进程 OOM。

因此 HTTP Streaming 至少还需要：

• 每连接有界发送队列；
• 写入时真正 await drain，而不是无限 enqueue；
• 对可重建的 preview delta 做合并或丢弃；
• 对 approval、error、completed 等权威事件保留空间；
• 慢消费者超过阈值时主动结束连接，并返回可恢复游标。

HTTP Streaming 解决了“数据可以什么时候到”，但没有自动解决“这一段数据是什么”“断线后从哪里继续”以及“客户端是否已经处理”。SSE 正是在 HTTP body 之上增加了一套轻量、标准化的记录语法与浏览器重连行为。

EventSource 的 API 边界#

浏览器原生 EventSource 面向 GET 型订阅，不能像 fetch 那样自由设置 method、request body 和任意请求头。Cookie 鉴权可以工作，但跨域凭证、CORS 与 CSRF 策略必须一起设计；把长效 bearer token 放进 query string，则可能泄漏到访问日志、浏览器历史或监控系统。

如果产品要求 POST body、动态 Authorization header、精细错误处理或自定义二进制格式，可以使用 fetch() 读取 ReadableStream 并自行解析 SSE。代价是自动重连、retry、Last-Event-ID 和终止状态处理也要由客户端实现。此时 wire format 仍可以是 SSE，但已经不再享受完整的原生 EventSource 生命周期。

自动重连不等于事件恢复#

SSE 标准定义的是 连接重建：浏览器记住最近处理过的 SSE id，重连时通过 Last-Event-ID 告诉服务端。[7] 它没有要求服务端保存历史，更没有保证该 ID 对应耐久提交。

一个可恢复的 Agent SSE 端点至少要定义：

• id 是仅用于日志关联，还是可用于重放的 resume cursor；
• cursor 的作用域是全局、用户、Run，还是某个投影流；
• 服务端保留多少历史，压缩后如何返回 snapshot；
• 重放是 at-least-once 还是可能存在 gap；
• 客户端如何按 event_id / sequence 去重；
• Run 已完成、无权限、游标过旧时分别返回什么状态。

若事件 ID 只是随机 UUID，服务端通常无法高效回答“它之后有哪些事件”。工程上常将 SSE id 映射到 Run 内单调递增的 sequence 或不透明但可比较的日志 offset；如果内部事件经过 projection 或 coalescing，则外部 cursor 还必须对应 外部可重放流，不能直接暴露一个随后会消失的内部队列下标。

重连最容易出错的是“先查历史，再订阅实时”的窗口：

1
查询历史结束 ── gap 中产生 evt_1043 ── 实时订阅建立

此时 evt_1043 既不在历史结果中，也没有被实时订阅捕获。可靠实现通常使用以下两类方法之一：

• 直接从同一个 append-only log 按 cursor tail，历史与实时没有两个数据源；
• 先建立实时订阅并暂存新事件，再读取一个 high-water mark 以内的历史，最后按 sequence 去重、排序并切换到 live。

如果历史已被 compact，服务端不应悄悄从“现在”继续，让 UI 误以为状态完整；它应明确返回 cursor expired，并提供当前 snapshot 与新的基线 sequence。更完整的恢复语义将在后文 Event Store 与 Durable Execution 中展开。

Heartbeat 与 timeout#

SSE heartbeat 通常使用 : ping\n\n 这样的 comment。它有三个作用：

• 让代理看到响应仍有字节流动，避免 idle timeout；
• 让服务端较早通过 write error 发现断开的客户端；
• 为端到端延迟和连接健康提供观测点。

它没有三个能力：

• 不代表 Run 有进展；
• 不推进 durable sequence，也不应伪装成权威业务事件；
• 不替代客户端的“多久没有业务进展就显示 stalled”判断。

heartbeat 周期必须依据实际代理链路配置，而不是固定照抄某个秒数。太慢会被网关先关闭，太快则在数万连接下造成无意义流量与唤醒。服务端还应区分正常 EOF、客户端 cancel、代理 reset 与自身超时，避免所有断线都记录成 Agent failure。

SSE 的 flow control 边界#

SSE 没有应用层 ACK。浏览器收到事件只表示字节已到达并被解析，不表示 React 已渲染、状态已持久化或用户已看到。慢客户端最终会通过 HTTP/TCP backpressure 影响 writer，但服务器仍需限制自己的每连接队列。

比较实用的优先级策略是：

• token、日志 tail、光标位置等 preview event 可以 coalesce；
• tool.started 与连续的 progress 可以只保留最新投影；
• approval、权限变化、error、completed 等状态转换不能丢；
• 超出队列上限时，关闭慢连接并让客户端从最后确认应用的 cursor 恢复。

注意“最后收到”与“最后应用”也可能不同。若 UI reducer 在主线程拥塞时已经积压了数千事件，浏览器维护的 last event ID 可能领先于 UI state。严格场景需要客户端把已应用 sequence 单独持久化，并在自管重连时使用它，而不是盲信底层接收位置。

常见失败模式#

因此：

1
SSE reconnect
2
    ≠
3
Replay
4
    ≠
5
Durable execution

SSE 最适合“控制命令走普通 HTTP，服务器持续向客户端投递事件”的结构。当客户端必须在同一连接上高频反向发送控制、输入或媒体数据时，WebSocket 的全双工语义更自然。

Frame 不是 Event#

RFC 6455 定义 text、binary、continuation 与 control frame。一个 WebSocket message 可以由多个 frame 分片；一个 frame 在 TCP 上又可能被拆成多次 read。大多数高级 WebSocket API 会替应用重组完整 message，但服务端库的最大 frame、最大 message 与内存策略可能不同。[8]

因此协议必须明确采用哪一种 record boundary，例如：

• 一个 WebSocket text message 恰好承载一个 JSON-RPC message；
• 一个 binary message 承载一个 protobuf record；
• 一个 message 内允许 batch，但 batch 自身有明确数组结构。

不要读取底层 socket 后假设“一次 read 就是一个 JSON”，也不要把 WebSocket fragmentation 当作 Agent 的 delta 语义。fragmentation 是传输实现选择；tool.output.delta 是业务协议。

Ping/Pong 与应用心跳#

WebSocket 有协议级 Ping/Pong control frame，可用于检测连接活性。许多服务端框架会自动回复 Pong；浏览器 WebSocket API 则不直接暴露发送协议 Ping 的接口，因此浏览器产品常再定义应用级 ping / pong 或周期性 server heartbeat。

两层心跳回答的问题不同：

• 协议 Ping/Pong：对端 WebSocket 栈是否仍可达；
• 应用 heartbeat：事件循环、会话处理器或 Run 订阅是否仍健康；
• progress event：Agent 是否产生了新的有意义状态。

把三者合并成一个“alive”布尔值，会让故障定位变得困难。

连接生命周期必须由应用协议补全#

WebSocket 没有像浏览器 EventSource 那样的自动重连与 Last-Event-ID。一个可恢复会话通常需要显式握手：

1. 建立 WSS / 本地 socket 连接并完成认证；
2. initialize / hello 交换协议版本、能力、最大消息大小和 heartbeat 参数；
3. 客户端以 run_id + last_applied_sequence 订阅；
4. 服务端返回 snapshot 或 replay，再进入 live；
5. 双方发送 command、event、request、response 与 ACK；
6. 断线后使用 backoff 和 jitter 重连，并重新认证与订阅。

握手成功只说明“通道建立”，不说明先前 Run 仍存在。恢复结果要显式区分：

• resumed：从 cursor 连续恢复；
• snapshot_required：历史已压缩，需要重建状态；
• run_terminal：Run 已结束，只需获取最终状态；
• run_not_found 或 forbidden：不能把它们伪装成空事件流。

代理链路并不天然更简单#

WebSocket 常通过 HTTP/1.1 Upgrade 穿过反向代理；其他 HTTP 版本有各自的承载机制，但网关、WAF、企业代理和 Serverless 平台的端到端支持并不一致。生产部署需要确认：

• Upgrade / Connection 相关头是否被正确转发；
• 最大连接时长、idle timeout 与 draining 行为；
• 负载均衡是否要求 sticky session，还是任意节点都能从共享状态恢复；
• 发布或扩缩容时，旧连接如何收到 reconnect hint；
• 中间层最大 frame / message 和速率限制；
• WebSocket 是否进入与普通 HTTP 同等的鉴权、审计和 DDoS 防护体系。

如果 WebSocket session state 只存在某一进程内存中，sticky session 只能降低问题概率，不能提供 durability。该进程重启时，连接和状态仍会一起消失。

send() 成功不等于消费成功#

WebSocket 基于可靠、有序的字节流，但“可靠”只覆盖当前连接内的数据交付。一次 send() 返回，通常只表示消息被应用或系统发送缓冲区接受，不表示对端业务逻辑已经处理，更不表示写入 Event Store。

慢消费者会在三个位置暴露：

• 浏览器的 bufferedAmount 持续增长；
• 服务端每连接 send queue 达到 high-water mark；
• 应用 ACK 的 last_applied_sequence 长时间不前进。

高可靠场景可以增加应用层 credit / ACK：

• 服务端只允许最多 N 个未确认 event；
• 客户端 reducer 应用后累计 ACK 到 sequence S；
• 服务端据此释放重放窗口或发送下一批；
• 重连从 S 继续，因此重复仍可能发生，客户端必须幂等。

ACK 的语义必须写清：是“socket 收到”“parser 解析”“state 已应用”还是“本地持久化”。定义不清的 ACK 只会制造虚假的 exactly-once。

全双工也不自动带来优先级。同一 TCP 连接严格有序，大体积 tool output 已经进入发送队列后，后来的 cancel 不能跨过这些字节。常见对策包括限制单 message 大小、将大 artifact 改为对象引用、为 control event 预留有界高优先级队列，必要时将控制面与大数据面拆成不同连接。

安全边界#

远程 WebSocket 应使用 wss://。浏览器可能在跨站 WebSocket 握手中携带 Cookie，因此服务端不能只看“有登录 Cookie”，还应校验 Origin、对象级权限与允许的子协议。非浏览器客户端没有可信 Origin，仍需 token、mTLS 或等效认证。

RFC 6455 要求客户端到服务端的 frame 使用不可预测的 masking key。[8] Masking 是 wire-level 规则，主要防止恶意脚本构造看似其他协议的字节流去污染中间代理；它不是加密、身份认证或消息完整性授权，不能替代 WSS 和应用鉴权。

长连接还会遇到普通请求较少暴露的问题：

• token 在连接存续期间过期，协议需要 re-auth 或受控重连；
• 单个超大 message 可造成内存放大，必须限制 message、解压后大小与嵌套深度；
• JSON schema 不应因为“连接已经认证”而跳过验证；
• permessage-deflate 等压缩会增加 CPU、内存和敏感上下文压缩侧信道风险，应按威胁模型配置；
• server-initiated request 也必须带 scope，客户端不能把任何 approval 消息都当作可信 UI 指令。

常见失败模式#

因此：

1
WebSocket
2
    ≠
3
Session durability
4
    ≠
5
Event replay
6
    ≠
7
Exactly-once command

WebSocket 的价值是给应用协议提供持续双向通道。协议仍需自行定义身份、顺序、背压、恢复与权限。

stdout 必须是协议专用通道#

stdio JSONL 最常见的故障不是网络，而是某个依赖库打印了一行 banner：

1
Debugger listening on port 9229

对人类只是日志，对协议 parser 却是非法 JSON。因而：

• stdout 只写协议 record；
• 日志、诊断、stack trace 写 stderr；
• host 必须持续 drain stderr，否则 stderr pipe 填满也会阻塞子进程；
• 多个 producer 不能无锁并发写 stdout，应由单一 serializer 排队；
• 每条 record 写完要 flush，不能依赖连接到 TTY 时的行缓冲行为。

不少语言运行时在 stdout 指向终端时采用 line buffering，指向 pipe 时却改用更大的 block buffer，所以“手动运行很流畅，IDE 中几秒一批”往往是 flush 问题，而不是 IPC 天生慢。

Pipe backpressure 会造成真实死锁#

操作系统 pipe 有有限缓冲区。当 host 停止读取 stdout，Agent 的 write 最终会阻塞。若双方都采取“先写完再读”的同步流程，就可能出现：

1
Host 等待 response
2
Agent 等待 stdout 可写
3
Host 又没有并发 drain stdout

因此 host 与 child 都需要独立的 read loop、write queue 和 dispatcher：

• read loop 持续解析 record，并按 request ID / event type 路由；
• write loop 串行化输出，达到 high-water mark 时让 producer await；
• tool output 等高频 preview 可以合并，但 control response 不应饿死；
• 大文件、截图或二进制 artifact 不宜长期 base64 塞进单行 JSON，应传路径、句柄或内容地址，并单独校验权限。

不要假设“小于某个大小的一次 write 在所有平台和所有多写者场景下一定原子”。让一个 serializer 成为 stdout 的唯一写者，才是跨平台、可维护的边界。

Process 生命周期就是一种连接生命周期#

stdio 通常把 transport 生命周期绑定到子进程：

1. host spawn child，设置 cwd、环境变量和 pipe；
2. 双方 initialize，交换协议版本与 capability；
3. 多个 request、notification 和 server-initiated request 交错；
4. host 发送 shutdown / cancel，停止接受新任务；
5. 等待有界 grace period 后关闭 stdin，必要时再终止进程；
6. child exit 后，host 消费完剩余 stdout / stderr，并将未完成 request 标记为 transport failure。

EOF 只表示对端不会再写字节，不自动说明某个 Run 成功、取消还是崩溃。进程 exit code、最后一个权威 Run event 与 stderr 诊断要分别记录。

stdio 也不天然 durable。若 Agent Runtime 就是该子进程，IDE 崩溃通常会让 pipe 关闭，子进程可能退出，也可能变成 orphan。要实现“IDE 重启后 Run 继续”，Runtime 必须升级为独立 daemon / service，并把 stdio 只作为一个客户端 adapter，或把执行状态持久化后由新进程恢复。

本地不等于可信#

本地 Agent 往往继承 host 的环境变量、工作目录和文件权限，安全影响可能高于一个受限远程连接。协议实现至少需要：

• 对 method、params、路径和 artifact handle 做 schema 与授权校验；
• 不让日志或模型文本注入协议字段；
• 限制单行长度、队列长度、请求并发和 tool output；
• 明确哪些环境变量可传给 child，避免无关密钥泄漏；
• 在多工作区 IDE 中把 session 与 workspace root 绑定；
• 对 approval response 校验对应的 pending request，而不是只匹配一个字符串 ID。

Codex App Server 的公开文档说明，其默认 transport 是基于 stdio 的 newline-delimited JSON；同时提供 WebSocket 与 Unix Socket 形态，其中当前 TCP WebSocket transport 被标记为 experimental / unsupported。[2] Grok Build 的 streaming-json 是 newline-delimited incremental events，其 ACP 模式通过 stdin/stdout 上的 JSON-RPC 工作。[5] 这些公开信息说明的是可观察协议边界，不应进一步推断产品未公开的内部进程拓扑。

stdio + JSONL 的关键价值不是“比网络更快”，而是部署简单、调试直接、天然适合本地 host-child 模型。它依旧需要严格 framing、flush、backpressure、版本协商与生命周期管理。

JSON-RPC 解决的是关联，不是流式可靠性#

JSON-RPC 2.0 定义 Request、Response、Notification 与 Error 的结构。[9] Request 带 id，Response 用同一个 id 关联；Notification 没有 id，接收方不得为其返回 Response。只要底层连接可双向发送，任意一侧都可以在不同时间扮演 requester 与 responder。

下面只是协议形态示意，不代表某一产品的精确 method 名：

1
{"jsonrpc":"2.0","id":"client:42","method":"turn/start","params":{"run_id":"run_7"}}
2
{"jsonrpc":"2.0","id":"client:42","result":{"accepted":true}}
3
{"jsonrpc":"2.0","method":"event","params":{"sequence":1042,"type":"tool.started"}}
4
{"jsonrpc":"2.0","id":"server:9","method":"approval/request","params":{"tool":"shell"}}

这里有三条不同的逻辑流：

• turn/start 的 Response 只确认命令是否被接受；
• event Notification 持续报告执行状态；
• approval/request 是服务端发起、等待客户端 Response 的反向请求。

JSON-RPC 本身没有定义：

• 消息如何在 TCP / stdio 字节流上分帧；
• notification 是否有顺序、是否能重放；
• cancellation、progress、subscription 或 heartbeat 的标准 method；
• 身份认证、授权和 capability negotiation；
• 断线后 request 是否仍执行；
• delivery 是 at-most-once、at-least-once 还是其他语义。

因此“使用 JSON-RPC”不能推出“支持 durable streaming”。应用协议仍需定义 run_id、event_id、sequence、resume cursor 和幂等命令 ID。

双向 JSON-RPC 还要处理 ID 空间。若两端都从数字 1 开始发 request，而实现既不区分消息形态、又把两个方向的 request 状态塞进同一个 map，就可能错误关联。正确实现应先区分 Request 与 Response，再为每一侧发出的 pending request 独立关联；也可以使用带角色前缀的 ID 简化诊断。无论采用哪种，同一 requester 的 ID 在其尚未完成请求集合中都必须唯一。连接断开时，不能把所有 pending request 都简单重发：只有具有幂等键、且协议允许重试的 method 才能安全重发。

ACP 把 Agent Session 语义放到 JSON-RPC 之上#

ACP 官方协议概览把通信模型定义为 JSON-RPC methods 与 notifications，并在典型 Prompt Turn 中使用 session/prompt、session/update 与 session/cancel；公开的 Grok Build 文档则展示了这套模式在 stdin/stdout 上的实现，其中 session/prompt 返回 completion metadata，assistant 文本以 session/update chunk 到达。[5][28] 这类设计的重要点不在 method 的字符串名称，而在于：

• prompt 是一个有明确 session 身份的命令；
• update 是会话执行期间的增量通知；
• host 与 Agent 可以在同一双向通道中完成请求、更新和交互；
• session 语义独立于 stdio，理论上可映射到其他 transport。

本文只依据公开接口讨论这种协议形态，不把未公开的内部队列、持久化或调度实现写成产品事实。尤其不能因为出现 session 一词，就自动推断它支持跨进程重启、任意时长 replay 或 exactly-once。

IPC / Unix Socket 只改变可达范围#

Unix domain socket 避开 TCP 端口，通过文件系统命名空间或平台相关地址连接本机进程。对 stream socket 而言，它仍然只是有序字节流，仍需 newline、length prefix、WebSocket message 等 framing。recv() 返回一次的 bytes 不等于一条 JSON-RPC message。

Codex App Server 的公开文档显示，其 Unix Socket transport 在 socket 上承载 WebSocket 连接，而 TCP WebSocket 则是另一种监听形态。[2] 这很好地说明了分层：Unix Socket 规定“进程如何在本机相遇”，WebSocket 规定 message transport，JSON-RPC 规定 request / response / notification。

本地 socket 的工程问题主要包括：

• socket path 的目录权限与所有者；
• stale socket file 在进程崩溃后如何安全清理；
• 是否允许多个客户端，以及每个客户端的订阅与配额；
• 服务重启后旧客户端如何重新发现 endpoint；
• 平台支持的 peer credential 是否用于加强身份校验；
• Windows 上是否需要 Named Pipe 或 loopback TCP adapter；
• 大量本地事件下的 send queue、最大 message 与慢消费者处理。

“只监听 localhost”也不是完整认证。共享机器上的其他用户、低权限进程、浏览器到 loopback 的请求以及被劫持的插件，都可能访问本地 endpoint。应优先使用权限受控的 socket directory / Named Pipe ACL；使用 loopback TCP 时还应增加随机 bearer token 或等效握手，并防止非预期 Origin。

协议错误与传输错误要分开#

一个成熟客户端至少要区分：

把所有异常都包装成一个 connection_lost，会让客户端既无法安全恢复，也无法向用户解释任务到底发生了什么。

9.1.1 实时系统的天然矛盾#

1
Preview Plane                         Authoritative Plane
2
-------------                         -------------------
3
低延迟                                完整且已验证
4
可能缺片、重复、乱序                  有稳定身份和 durable cursor
5
允许合并或丢弃                        不允许静默丢失
6
只影响临时展示                        驱动恢复、审计和最终状态

Preview 不是“低质量 Event Store”，而是明确的 scratch layer。推荐使用 preview_id + subject_id + preview_seq + base_revision，让客户端知道片段属于哪个临时对象，以及最终事件应替换哪一层 overlay。

9.1.2 Anthropic 的公开范例：Preview 是 scratch buffer，Buffered Event 才是 record#

[公开事实] Anthropic Managed Agents 文档说明：event_start 与 event_delta 用于低延迟预览；preview 是 best-effort display aid；buffered agent.message 才是 authoritative record；负载下 delta 可以被丢弃，且 preview 不持久化、断线后不可补取，但完整 buffered event history 可以读取。[12]

其公开语义可以抽象为：

1
                 Agent Output
2
                 /          \
3
       preview delta       buffered final
4
            │                    │
5
      scratch overlay       durable record
6
            └──── reconcile ─────┘

这里的关键不是具体事件名，而是协议明确承认：用户可能没看到全部动画片段，但最终记录仍然完整。

9.1.3 Codex 的公开范例：item/started、delta 与 item/completed#

[公开事实] Codex App Server 在工作单元开始时发送 item/started，执行中发送各类 delta，结束时以 item/completed 给出最终 Item；官方建议把 completed Item 作为 authoritative state。[2]

1
item/started
2
    ↓
3
item/.../delta       # 临时进度
4
    ↓
5
item/completed       # 最终对象

这与 Preview / Authoritative 分层具有相同核心：delta 优化等待体验，completed object 负责校正最终事实。

9.1.4 为什么不能持久化所有 Token Delta#

把每个 token、terminal chunk 和 diff fragment 都作为同等级永久记录，会造成写放大、索引膨胀、replay 变慢、查询噪音以及 reducer 重建成本上升。更合理的耐久度层级是：

不是所有高频数据都必须丢弃。若 terminal 原始输出本身具有审计价值，可以把它分块写入 blob/object storage，并在权威完成事件中保存内容引用；Event Log 只保留索引和边界，而不是数万个字符级行项目。

9.1.5 临时展示必须有明确提交边界#

实时性不要求每一个实时片段都成为系统事实；最终一致性要求每个临时对象都有明确的提交、替换或废弃边界。

仅说“最终会一致”还不够，协议必须定义如何一致。

9.1.6 Preview Commit Protocol：从临时片段到最终事实#

以下是**[设计建议]**的最小提交协议：

1
1. begin preview(subject_id, preview_id, base_revision)
2
2. emit preview.delta(preview_id, preview_seq=N)       # best effort
3
3. Runtime 形成完整结果并完成验证
4
4. 在一个 durable commit 中：
5
      compare subject revision
6
      update authoritative state
7
      append final event
8
      write outbox record
9
5. commit 成功后发布 final event
10
6. Client 按 subject_id / preview_id 删除 overlay，以 final payload 替换

服务端应使用两种不同 API，避免开发者误把 preview 当权威事实：

1
publishPreview(delta)                       # 可以失败或被丢弃
2
appendAuthoritative(expectedRevision, fact) # 成功意味着 durable commit

客户端 reducer 可以近似写成：

1
onPreview(p):
2
    if p.preview_seq <= overlay[p.preview_id].last_seq: return
3
    if sequence has a gap: overlay[p.preview_id].incomplete = true
4
    append_to_overlay(p)
5

6
onAuthoritative(e):
7
    if durable_cursor_already_applied(e.cursor): return
8
    state = reduce(state, e)
9
    delete overlay linked to e.subject.id / e.payload.preview_id
10
    persist_applied_cursor(e.cursor)

注意：final payload 不必等于所有 delta 的字符串拼接。服务端可能修复 partial JSON、过滤不安全内容、压缩推理摘要或因取消而提交部分结果。客户端必须替换，不能只在 preview 尾部继续追加。

9.2.1 多生产者：统一事实写入边界#

生产者只表达领域事实，但不能任意 emit({type: string})。推荐由 typed producer API 负责：

• schema validation 与版本标记；
• 补齐 scope、subject、trace 和 security context；
• 检查当前状态是否允许该事实；
• 为权威事件执行 append，而不是 fire-and-forget；
• 为 preview 实施大小、频率和优先级限制。

最危险的错误是双写：

1
update run_state succeeds
2
publish run.completed fails

如果权威状态与 Event Log 位于同一数据库，可在同一事务中更新 state、append event 并写 outbox；提交后的 publisher 再将 outbox 投递到实时总线。AWS 对 Transactional Outbox 的公开说明正是用同一事务消除 database update 与 event notification 的 dual-write 裂缝，并明确提醒 Publisher 可能重发，消费者仍需幂等。[17] 如果 Event Log 本身就是状态源，则 append 成功后由投影更新 read model。两种方式都比“先改状态，再尽力发通知”更可恢复。

外部工具副作用无法与本地数据库形成普通 ACID 事务。此时要持久化 operation intent/idempotency key，调用外部系统，再记录 result；崩溃后的 recovery worker 查询外部结果或进入 outcome unknown，而不是假装本地事务覆盖了网络另一端。

9.2.2 多消费者：隔离可靠性与消费速度#

同一事件可被 UI Projector、Event Store、Trace Collector、Metrics Aggregator、Audit Logger 和 Debugger 消费，但它们不能共享一个会相互阻塞的无界回调链。

[设计建议] 为不同消费者建立独立 bounded subscription：

1
durable writer slow  → 对权威 append 施加背压或拒绝新工作
2
metrics exporter slow → 批量、采样或短时丢弃 telemetry
3
one UI slow          → 断开该订阅，保留其 durable cursor
4
audit sink slow      → 使用独立可靠 spool，不允许静默跳过安全事实

“事件化解耦”不意味着没有契约。每个 consumer 仍需声明可接受版本、delivery semantics、最大 lag、失败重试和 poison event 处理。否则只是把同步耦合变成不可见的队列堆积。

9.2.3 Claude Code 社区分析中的异步生成器链#

[社区研究，非官方事实] how-claude-code-works 明确声明其为独立研究。其对约 2026 年 3 月底源码快照的分析认为，Claude Code 核心 query() 使用 async function*，持续 yield assistant、progress、stream event 和 tool result；用户体验分析描述了从 API SSE、callModel()、query()、QueryEngine、REPL 到终端渲染的生成器链路。[13][14]

这不能证明 Claude Code 当前或完整内部架构，但很好地说明了本地数据面的典型模式：

1
Push Source → Async Decode → Runtime State Machine → Yield Semantic Event → UI Projection

Async generator 提供自然的顺序和取消传播，但多消费者扇出、慢消费者隔离与 durable replay 仍需要额外机制；不能因为使用 yield 就认为已经拥有 Event Store。

9.3.1 为什么连接不能成为任务生命线#

如果连接关闭就杀死 Agent，浏览器刷新、IDE 重启、设备休眠、手机切网或代理超时都会摧毁长时任务。正确模型是：连接只是观察和控制 Persistent Run 的窗口；是否因无观察者而暂停，应是显式产品策略，而不是 socket 生命周期的偶然副作用。

[公开事实] Cursor 说明 Cloud Agent 在设备休眠或网络掉线后仍继续运行，并支持之后 reconnect。[4] xAI Agent Dashboard 的公开页面足以证明多 Session 并行、状态排序与 Subagent 汇总，但本文不据此推断其断线持续执行或恢复协议。[10]

9.3.2 Durable Run 的最小组成#

一个可恢复 Run 至少需要：

1
{
2
  "run_id": "run_123",
3
  "status": "waiting_input",
4
  "revision": 47,
5
  "durable_cursor": "cur_1024",
6
  "checkpoint_ref": "snapshot_900",
7
  "waiting_on": {"kind": "approval", "id": "apr_7"},
8
  "worker_lease": {"epoch": 12, "owner": "worker_9", "expires_at": "..."},
9
  "updated_at": "..."
10
}

此外还需要任务图、已提交工具 operation、取消状态、审批状态、外部资源引用和足以继续运行的 context/checkpoint。仅保存聊天 transcript，通常不足以恢复正在等待的工具或子 Agent。

Worker crash recovery 还必须防止“双执行者”：

1
1. 新 worker 获取 lease，lease epoch 从 12 增为 13
2
2. 所有权威提交都携带 epoch=13
3
3. 旧 worker 即使恢复网络，其 epoch=12 的提交也被拒绝

这种 fencing token 比单纯 heartbeat 更关键。Heartbeat 能发现可能失效的 worker，epoch 才能阻止旧 owner 在网络分区后继续写入。

9.3.3 Disconnect 不等于 Stop#

1
Client Disconnect
2
      ↓
3
Transport Lost ───────────────┐
4
                             │ no implicit transition
5
Run Supervisor: running ─────┘

cancel、pause 与 detach 应是三个不同命令：

• detach：关闭观察连接，Run 不变；
• pause：在安全边界停止推进，保留可恢复状态；
• cancel：请求终止并执行必要清理，最终产生 terminal event。

如果系统支持“最后一个客户端离开后自动取消”，也应由显式 retention/ownership policy 触发并记录原因，而不是把 TCP FIN 当作业务命令。

9.3.4 Reconnect：不能只“重新订阅现在”#

重连协议必须避免 replay/live race。一个可行的**[设计建议]**流程是：

1
Client → resume(run_id, last_cursor, supported_schema_versions)
2

3
Server:
4
  1. 重新鉴权，并验证 cursor 属于该 tenant/run/projection
5
  2. 读取 latest compatible snapshot（如需要）
6
  3. 从 durable log 确定 high-watermark H
7
  4. 发送 snapshot + (snapshot.cursor, H] 的权威事件
8
  5. 从 durable log 订阅 H 之后的事件
9
  6. 发送 sync.completed(H)，再进入 live 模式

关键是第 3 至 5 步必须无缝。如果底层 log 支持 subscribe(after=H)，即使订阅建立稍晚也可补齐；如果只有内存 fan-out，则必须先注册 live buffer，再读取 high-watermark/replay，最后去重合并。简单地“先查数据库，再连 WebSocket”会在两个动作之间丢事件。

Cursor 应被视为 opaque token。服务端可以在其中编码 partition、projection version 或签名；客户端只负责原样保存和回传。若 cursor 已超出 retention 或 projection schema 不兼容，应返回明确的 resume.reset_required，附带新 snapshot，而不是从当前 live point 悄悄继续。

[公开事实] Cursor/Notion 的案例提到 SSE Run 可在连接中断后从 last event resume。[4] Anthropic Managed Agents 的 preview 不重放，重连后通过 event history 获取断线期间的 buffered authoritative events。[12] 两者共同体现：恢复的是权威状态，不是每个临时动画帧。

9.3.5 Replay 与 Debugging#

“Replay”至少有三种完全不同的含义：

前两者可以相对确定；Re-execution 通常不确定，因为模型输出、网络 API、文件系统和时间都可能变化，而且重复执行工具可能造成副作用。调试界面必须清楚标注是在“播放记录”还是“重新执行”，不能把两者都叫 Replay。

同样需要严谨区分 Event Streaming 与 Event Sourcing。严格 Event Sourcing 要求业务状态由权威事件重建；许多 Agent 系统实际依赖：

1
Event History + State Snapshot + External Tool State + Content Blobs

因此，**[统一抽象]**可以说现代 Durable Agent 越来越采用事件溯源思想，但不能仅因存在事件流就断言某产品实现了完整 Event Sourcing。Microsoft 对 Event Sourcing 的公开说明也把 immutable append-only event、replay、materialized view 与 snapshot 作为一组相关但职责不同的机制，并提醒 event store 不等同于 message broker。[16]

9.3.6 Snapshot、Compaction 与 Tombstone#

长 Run 不应每次从 evt_1 重放到 evt_100000：

1
Current State = Snapshot(through_cursor=C90000)
2
              + Authoritative Events(C90000, current]

可靠 snapshot 至少包含：

1
run_id
2
through_cursor / through_sequence
3
aggregate_revision
4
reducer_version
5
minimum_event_schema_version
6
state_checksum
7
created_at

Snapshot 必须对应一个已提交的权威边界。先读取 state、稍后再猜一个 cursor，可能把某事件既包含在 snapshot 中又重放一次，或两边都漏掉。解决方法是同事务生成，或使用 MVCC/read barrier 保证 state 与 high-watermark 一致。

Compaction 也不是简单删除旧事件。推荐区分：

• 可折叠：字符 delta、周期性 progress、被最终对象完整覆盖的临时块；
• 需保留或转入审计层：审批决定、外部副作用、权限变更、终态、失败原因；
• 可外置：大段 terminal output、截图、模型完整内容，Event Log 保存 hash 与 content_ref；
• 有引用约束：仍被后续 causation_ids、Artifact provenance 或审计记录引用的事件不能无痕消失。

压缩或删除 durable range 时，应写入可验证的 tombstone/compaction manifest，而不是制造无法解释的 cursor 空洞。Manifest 至少记录被替换的 cursor range、替代 snapshot 或 summary 的引用与 hash、压缩原因、策略版本和执行时间。它带来三条规则：旧 cursor 若落入已压缩区间，服务端返回 reset_required 并指向兼容 snapshot；后续事件若仍引用被压缩 event，应保留最小 identity/causality tombstone；“因保留策略删除 payload”和“业务实体被删除”是两种不同事实，不能共用一个含义模糊的 tombstone。

对于合规删除，可以清除或加密销毁敏感 payload，同时保留不含敏感内容的序列边界、类型和删除证明；是否允许这样做取决于具体法规和产品政策。架构上必须承认：审计不可变性与数据删除权可能冲突，需要显式 retention class，而不是承诺所有事件永久不可删除。

当 reducer 或 schema 升级时，可以重建新 snapshot；如果旧事件已被压缩到不足以用新 reducer 重建，就必须把 snapshot 本身视为长期兼容资产，并维护 snapshot upcaster。这是 compaction 会引入的真实技术债务。

10.1.1 同一事件，不同投影#

同一个 tool.execution.started 可以被投影为：

服务端和客户端都可以有 projection。服务端适合维护跨设备共享的 Run summary、待审批索引和分页时间线；客户端适合维护 viewport、展开状态和 preview overlay。二者不应争夺同一权威字段：服务端 run.status 是事实投影，客户端 isExpanded 是纯展示状态。

一个权威 reducer 应尽量满足纯函数性质：

1
reduce(state, event) -> new_state
2

3
约束：
4
- 不读取当前时间、随机数或网络
5
- 不调用工具或再次产生外部副作用
6
- 相同 snapshot + 相同有序事件得到相同结果
7
- 重复 event_id 不改变结果
8
- 只接受兼容 schema，未知关键事实显式失败

伪代码如下：

1
project(snapshot, durable_events):
2
    assert snapshot.reducer_version is supported
3
    state = upcast(snapshot.state)
4
    cursor = snapshot.through_cursor
5

6
    for event in durable_events:
7
        if event.cursor <= cursor: continue
8
        event = upcast(event)
9
        state = handler[event.type](state, event)
10
        cursor = event.cursor
11

12
    return {state, cursor, reducer_version}

这里的 <= 是协议层可比较关系的简写；若 cursor 是完全 opaque，比较和去重由 stream client 库完成，业务 reducer 不应自行解析。

Preview 不进入上述权威 fold，而作为 overlay：

1
Rendered View = Projected Authoritative State + Ephemeral Preview Overlay

final event 到达时先推进权威状态，再删除对应 overlay。这样即使 preview 缺片、乱序或在刷新时消失，read model 仍可由 durable history 重建。

10.1.2 为什么这是产品扩展性的关键#

稳定的 semantic protocol 允许同一 Runtime 支持 CLI、Desktop、IDE Extension、Web Dashboard、远程控制和调试器，而无需让执行核心知道每个界面的组件结构。

Projection 自身也需要版本治理：

• 保存 projection_name、projection_version 和 through_cursor；
• 部署新 reducer 时从兼容 snapshot 或 Event Log 建立 shadow projection；
• 校验关键计数、终态和 checksum 后再切换读流量；
• projector 崩溃后从自身 cursor 重放，而不是从“现在”继续；
• 对 poison event 隔离并告警，不能跳过关键状态转换后继续给出看似正常的 UI。

若客户端收到比自身更新的非关键事件，可以保留 cursor 并以 generic timeline item 降级；若未知事件可能改变权限、终态或 Approval，则必须要求升级或重新获取服务器生成的 snapshot，不能 silent ignore。

[公开事实] Codex App Server 允许远程 TUI 通过 WebSocket 连接同一 App Server，这是 Runtime 与 Presentation 分离的公开例子。[2]

10.2.1 Coalescing：合并连续片段#

对相同 (run_id, item_id, stream) 的连续 delta，在一个大小或时间窗口内合并为一次网络/渲染更新。窗口必须在以下边界强制 flush：对象终结、流类型改变、高优先级事件到达、权限级别改变、buffer 达到上限。

Coalescing 不应跨 subject 合并，也不应丢失可检测性。合并块可以记录 first_offset、last_offset、source_count 和 truncated，这样排障时能区分“生产者只产生一次输出”和“中间层合并了一百次输出”。

10.2.2 Grouping：折叠同类工作#

连续读取 A、B、C 三个文件可以展示为“已读取 3 个文件”，但原始子项仍应可展开，失败项不能被成功计数掩盖。Grouping key 通常包含 event type、task/agent、phase 和 security class；跨 Agent 或跨权限边界分组会造成归属和授权混乱。

[社区研究，非官方事实] Claude Code 社区分析描述了同类型工具调用的分组渲染，用于减少视觉噪音。[14]

10.2.3 Semantic Progress Projection：生成可行动进度#

底层 grep → read → read 可以投影成“正在分析认证模块”，但这一层最容易产生虚假确定性。[设计建议] 优先由显式 Task、Plan step、Tool category 和 Artifact 状态确定性推导，并保留 provenance：

1
{
2
  "progress_key": "task_auth_analysis",
3
  "label": "正在分析认证模块",
4
  "phase": "running",
5
  "derived_from": ["evt_301", "evt_302", "evt_303"],
6
  "projection_version": 4
7
}

如果进度文案由模型概括，应标记为 heuristic summary，不能用它驱动权限、重试或完成判定。task.completed 只能来自权威状态机，不能因为摘要写了“完成”就被推断出来。

10.2.4 为什么“更多事件”不等于“更透明”#

真正的透明度要求信息 Relevant、Timely、Actionable、Understandable。产品层至少应同时保留三种视图：

• 当前阶段：用户第一眼知道 Run 在执行、等待、失败还是终结；
• 可行动项：Approval、Input Request、冲突和失败置顶，不被 token 洪流淹没；
• 可展开证据：需要时可以查看命令、Diff、来源事件和完整 Artifact。

Aggregation 必须遵守“不得掩盖终态、失败、安全决策和数据缺失”的不变量。例如 terminal output 被截断时，UI 必须显示 truncated；十个并行任务九成成功时，不能聚合成“全部完成”。

Agent UI 的竞争力不在于展示多少 Raw Event，而在于能否把 Execution Graph 压缩成可验证、可行动的 Progress Model。

10.3.1 事件生产者比 UI 快#

假设 test runner 每秒产生数千个小 stdout chunk。若每个 chunk 都触发独立 frame、JSON parse、store update 和 React render，系统会在业务工作尚未饱和前先被调度、GC 和重绘开销拖垮。

生产系统应为每一跳定义：

1
queue capacity
2
high / low watermark
3
maximum event age
4
batch size / flush boundary
5
overflow action
6
upstream feedback mechanism

高低两个 watermark 用于 hysteresis：达到 high 后进入降级，只有降到 low 才恢复，避免负载在阈值附近频繁切换策略。

10.3.2 不同事件需要不同流控手段#

不同技术解决不同问题：Buffer 吸收短峰值；Batch 降低每条固定开销；Throttle 限制更新频率；Coalesce 保留最新或连续内容；Sample 用于 telemetry；Drop 只适用于允许降级的数据；Admission Control 则在系统没有执行容量时拒绝新 Run。

[设计建议] 按事件类别定义 QoS，而不是给整个连接一个统一策略：

P0/P1 的“不能丢”不意味着必须无限堆在每个 WebSocket 的内存队列里。正确方式是先确保 durable source，再让过慢订阅者携 cursor 断开重连。无界 per-client queue 会把一个慢浏览器变成服务器 OOM。

[公开事实] Anthropic Managed Agents 把 preview delta 定义为 best-effort，并允许负载下 shedding delta，而完整 agent.message 仍作为权威记录。[12] Codex App Server 的 WebSocket 模式公开使用 bounded queue；request ingress 满时拒绝新请求并返回 overload，客户端需以指数退避和 jitter 重试。[2] 前者体现数据面降级，后者体现控制面/admission 限流。

10.3.3 Backpressure 不只是“队列变长”#

每种生产者的阻塞能力不同：

• Model API 可以通过暂停读取施加有限 TCP backpressure，但过久可能触发上游超时；
• 本地命令的 stdout/stderr 必须持续 drain，否则可能阻塞被执行进程；
• durable writer 变慢时继续无限接收权威事实会耗尽内存，应降低并发或停止接纳新 Run；
• SSE 没有应用层双向 credit，可通过批量、心跳、断开与 cursor 恢复控制；
• WebSocket 可增加 credit/window update，但协议必须防止客户端虚报容量；
• Renderer 应以固定帧率或调度批次消费 preview，而不是让网络事件直接触发重绘。

系统还需要 noisy-neighbor 隔离。队列和 token budget 至少按 tenant、Run 或 connection 设配额，并使用公平调度；否则一个输出海量日志的 Run 会推迟另一个 Run 的 Approval。

10.3.4 事件优先级必须对应资源策略#

优先级必须落实到资源预留和 overflow action，而不仅是 envelope 中的标签。例如可以为 P0/P1 保留独立队列容量，在 P3 拥塞时采用以下次序：

1. 丢弃 P4；
2. 延长 P3 coalescing 窗口，并优先丢最旧 preview；
3. 将 P2 变为 latest-value 更新；
4. 断开持续落后的订阅者，返回最后 durable cursor；
5. durable writer 或 Run supervisor 饱和时，拒绝新 Run，而不是牺牲已接受 Run 的终态记录。

任何丢弃都应可观察：preview_dropped_total、每连接 queue depth、oldest event age、projection lag、durable append latency 和 forced resync 次数都应进入 metrics。客户端若发现 preview gap，应显示“实时输出已省略”或等待 final，不能悄悄拼接出看似连续的内容。

11.1.1 不要强求不存在的全局业务顺序#

建议将顺序需求分层：

数据库可能为了存储方便给所有事件分配全局 offset，但该 offset 仍只是提交顺序。把它当成业务因果会导致错误，例如独立 Research Agent 的结果只是更早写入数据库，并不意味着 Code Agent 读取过它。

只有确实需要检测并发更新时，才考虑 Lamport clock、vector clock 或版本向量；它们会增加 envelope、合并和持久化成本。大多数 Agent UI 使用“单聚合 revision + durable playback cursor + 显式 cause edges”已经足够。

11.1.2 局部顺序与因果关系需要哪些字段#

最小字段集合通常包括 run_id、agent_id、task_id、subject.id/revision、partition cursor、correlation_id、causation_ids 和 trace context。还应保留 occurred_at 与 recorded_at，但只用于人类时间线和延迟分析，不用于状态转换合法性。

因果关系应满足：

• cause 已存在或可由同批事务验证；
• 同一因果图不能形成环；
• join event 可以有多个 causes；
• retry attempt 关联原 operation，而不是伪装成原事件的重复投递；
• 补偿事件指向被补偿事实，并保留原事实，不做历史覆盖。

11.1.3 因果关系示例与共享资源冲突#

1
{
2
  "event_id": "evt_test_started",
3
  "type": "task.started",
4
  "scope": {"run_id": "run_1", "task_id": "integration_test"},
5
  "causality": {
6
    "correlation_id": "corr_run_1",
7
    "causation_ids": [
8
      "evt_code_artifact_verified",
9
      "evt_environment_ready"
10
    ]
11
  }
12
}

UI 可以按时间、Agent、Task 或因果树展示同一组事实。Scheduler 则应根据 task dependency state 决定是否启动测试，而不是扫描 UI 时间线。

还要注意：事件顺序不能自动解决共享资源冲突。两个 Agent 都基于 file revision 7 生成 patch，即使事件被排成先后，第二个 patch 仍可能覆盖第一个。文件提交必须检查 base hash/revision，并选择拒绝、rebase、merge 或人工决策。Ordering 记录冲突发生的顺序，Concurrency Control 才决定冲突如何处理。

11.2.1 Client Reducer：从权威事实构建视图状态#

客户端通常维护两层：

1
{
2
  "authoritative": {
3
    "cursor": "cur_1024",
4
    "items": {
5
      "item_1": {"revision": 4, "status": "completed", "output": "..."}
6
    }
7
  },
8
  "preview": {
9
    "preview_item_2": {"last_seq": 19, "incomplete": false, "text": "..."}
10
  }
11
}

Reducer 需要处理重复、旧 revision、final reconciliation 与 resync：

1
applyAuthoritative(event):
2
    reject wrong run/tenant
3
    if cursor already applied: return
4
    if event.subject.revision is stale: quarantine or ignore by contract
5
    if required base revision is missing: request snapshot/resync
6
    authoritative = pureReduce(authoritative, event)
7
    remove superseded preview
8
    persist cursor after state commit

“persist cursor after state commit”很重要。若先保存 cursor 再更新本地 state，客户端崩溃后会跳过尚未应用的事件；本地数据库可将 state 与 cursor 放在同一事务中。纯内存 UI 则在重启后从服务器 snapshot 重新开始。

11.2.2 为什么 Delta 不能直接等同 State#

Delta 必须声明操作语义。append bytes、replace range、JSON Patch 与“最新 progress value”不能共用模糊的 data 字段。建议为可应用 delta 指定：

1
operation: append | replace | patch | latest_value
2
base_revision / byte_offset
3
preview_seq
4
content_encoding

若 base revision 或 byte offset 不匹配，客户端不能继续盲拼，应把 overlay 标记 incomplete、请求局部 snapshot 或等待 authoritative final。Finalization 规则还要说明：完成事件是包含完整对象，还是仅声明某个 blob 已封存。二者都会影响重连时所需数据。

服务端的 aggregate state 负责授权和执行；客户端 reducer 只负责可视化。即使恶意客户端把本地 approval.status 改成 approved，也不能让 Runtime 越过等待状态。

12.1.1 Event Redaction：在进入通用 Backbone 前分级#

最安全的秘密是从未进入通用 event payload 的秘密。OWASP Logging Cheat Sheet 明确要求访问令牌、认证密码、数据库连接串和加密密钥等不应直接记录，并要求对事件数据做格式校验、编码与清洗以防 log injection。[26] [设计建议] 使用分层处理：

1. 生产者按结构化 schema 标记 secret、PII、credential 和 workspace-sensitive 字段；
2. 在进入通用 backbone 前将秘密替换为 opaque reference 或固定 redaction token；
3. 若业务必须保留原值，写入独立加密 blob store，Event 只保存受 ACL 控制的 content_ref；
4. 针对 local UI、remote UI、telemetry、audit export 生成不同 redacted view；
5. 对非结构化 stdout 再使用 pattern scanner 作为第二道防线，但不能把 regex 当成唯一秘密识别机制。

建议维护数据级别并使其随派生链传播：

Projection 和 aggregation 不能降低 classification，除非经过明确 redaction transform。否则原事件虽然被遮蔽，派生的 progress 文案或 error message 仍可能重新泄漏路径和 token。

12.1.2 权限事件必须对应服务端状态转换#

approval.required 必须对应服务端 Runtime 的 waiting state。Approval response 至少校验用户权限、Run/tenant 归属、approval ID、subject revision、action digest、decision scope、expiry 和单次使用状态。

高风险操作可把 Approval 视为一个受限 capability：只允许在指定 Run、指定 action digest、指定资源和有效期内使用。命令参数在审批后改变时，旧 capability 立即失效。权限被管理员撤销后，已有长连接也必须在控制命令和敏感事件读取时重新授权，而不是只在 WebSocket 建立时检查一次。

12.1.3 Replay、Snapshot 与 Artifact 的读取权限#

能读取 live stream 不应自动意味着能下载完整历史；能看摘要也不一定能看原始命令输出。订阅、catch-up replay、snapshot、Artifact blob 和 audit export 都需要资源级授权，并在每次恢复时重新验证。

还需要处理以下边界：

• tenant/run ID 不能只由客户端传入后直接拼查询条件，应由授权上下文绑定；
• cursor 应签名或在服务端查表，防止被篡改为其他 Run 的位置；
• 撤销访问后，历史缓存、预签名 blob URL 和本地离线副本要有明确失效策略；
• retention/deletion 必须覆盖 Event Log、snapshot、projection、outbox、trace、backup 和外置 blob；
• 审计记录本身包含 actor、命令和资源，也属于敏感数据。

最后，事件 payload 是不可信输入。工具输出可能包含 ANSI 控制序列、恶意 Markdown/HTML、伪造链接或超长单行；UI 应进行 escaping、长度限制和安全 link handling。显示 command.stdout 绝不等于允许它调用终端控制接口。