【实现】 Agent Loop 重构 Phase 6：Runtime Event v5、Gateway 与 TUI v2

[wynxing]

关联 RFC / 架构

• 父架构 RFC：【架构】 重构 NeoCode Agent Loop：Workflow Orchestrator、统一 AgentLoop 与上下文隔离 #721
• 阶段：Phase 6
• 前置依赖：【实现】 Agent Loop 重构 Phase 1：Workflow 领域模型与持久化 #723 的 Workflow snapshot/event sequence；与 RFC: NeoCode TUI v2 — Ghost Console 独立实现 #660 TUI v2、【提案】 为计划模式补齐 Gateway 计划审批 RPC #688 Plan 审批、RFC: Runtime Hook 能力完善与开发体验优化（单一真源 / 契约闭环 / lint+dry-run+trace） #679 Hooks 协调。

目标问题

Runtime Event v4 只能描述线性 Run 和单个 subagent 生命周期，缺少 workflow/node/artifact 层级、幂等 event_id 与可重放 sequence。客户端无法在断线后恢复任务图，也无法稳定展示并行 Explore、审批、replan 和 needs_recovery。

实现设计（How）

• 发布 Runtime Event payload v5，envelope 增加 event_id、workflow_id、node_id、parent_node_id 和 Workflow 内单调 sequence。
• 增加 workflow、node、artifact、approval、recovery、node compact 事件；现有 agent/tool/permission/budget/usage/hook/checkpoint 事件携带节点归属。
• Gateway 新增 getWorkflow、resolveWorkflowApproval、resolveWorkflowRecovery、listWorkflowEvents RPC。
• 状态与事件同事务持久化；Gateway 重连先取 snapshot，再从 sequence 增量重放。
• TUI v2 reducer 保存 Workflow/Node map、依赖、活动节点、审批/权限/恢复状态和 last sequence；使用 event_id 去重并检测缺口。
• TUI v1 固定 v4 且目录冻结，本阶段不修改 internal/tui/；正式 v5 切换后停止支持 TUI v1。
• Runtime 不双发 v4/v5；切换作为明确 breaking change。

影响模块：Runtime event contracts、Gateway contracts/RPC/relay/docs、TUI v2 gateway/reducer/view 和协议生成示例。

边界与非目标：Gateway 不推导 Workflow 状态；TUI v2 不导入 Runtime/Session；不建立 v4 投影层；不修改 TUI v1。

任务拆解

• 定义 v5 envelope、事件类型和 payload schema 单一真源。
• 把现有 provider/tool/permission/budget/hook 事件绑定 workflow/node。
• 实现 Workflow snapshot 与增量事件查询接口。
• 实现审批和恢复决议 RPC、ACL、错误映射、metrics 与文档。
• 实现 Gateway stream 重连和 sequence replay。
• 扩展 TUI v2 client contract、reducer 和 Workflow/Node 展示状态。
• 实现审批、权限等待、replan、恢复和失败的 TUI v2 交互。
• 更新 RPC reference、contract matrix、生成示例和 breaking change 说明。
• 明确默认启动/发布文档指向 cmd/neocode-tuiv2。

测试与验证（Done）

• 正常路径：Workflow 创建、路由、并行节点、审批、执行、验收和终止事件顺序正确。
• 边界条件：重复 event_id、sequence 缺口、空 parent、快速路径无 Explore 和多个并行节点。
• 异常分支：stale revision、approval 非 pending、recovery 非 pending、ACL 拒绝和 Runtime 超时映射稳定。
• 重连路径：snapshot + replay 恢复到相同 reducer 状态，乱序事件触发重新同步而非猜测。
• TUI v2 边界：不 import runtime/session/repository/SQLite，不直接执行工具。
• 协议：Runtime 只发 v5；TUI v1 文件无修改；文档明确 breaking change。
• Go 与 TUI v2 测试通过，新增修改逻辑达到 100% 覆盖目标。

风险与回滚

• 风险：v5 切换导致旧客户端立即失效。先完成 TUI v2 conformance 和发布指引，再切换 Runtime。
• 风险：事件与状态不一致。事件 sequence 与状态迁移同事务，Gateway 只中继持久化事实。
• 风险：Reducer 遇到缺口产生错误 UI。检测缺口后重新请求 snapshot。
• 回滚：正式切换前可回退 v5 入口；切换后按完整版本回滚，不在 Runtime 内长期维护 v4 双发。