work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-remove-websocket-runtime-transport.md

@@ -0,0 +1,364 @@
+# SPEC: Remove WebSocket Runtime Transport
+
+更新时间：2026-03-17  
+状态：Ready for implementation  
+Owner：work-ally engineering  
+相关文档：
+- `docs/planning/SPEC-bridge-app-server-protocol-alignment.md`
+- `docs/planning/SPEC-runtime-connection-and-turn-recovery-semantics.md`
+- `docs/issues/resolved/ANALYSIS-codex-app-server-transport-disconnect-semantics-2026-03-14.md`
+
+## 1. Summary
+
+本 spec 的目标很直接：
+
+> 把 `work-ally` 中 `bridge <-> Codex App Server` 的 websocket transport 整条链删干净，改成本机默认 `stdio` child-process transport。
+
+理由也很直接：
+
+1. websocket 在官方语义里不是默认稳定基线，而是 experimental transport
+2. 对当前产品来说，它没有提供独立产品能力
+3. 它却引入了额外的 runtime-host 进程、listen 地址、端口分配、重连状态机、health/state 文件、排障面和测试面
+4. 既然 bridge 的最终正确性已经转向 pull-primary + ledger，那么 websocket 不再承担真相职责；此时继续保留它，只剩复杂度成本
+
+本次改动不是“顺手优化 transport”，而是一次架构收口：
+
+1. bridge 直接拉起 `codex app-server --listen stdio://`
+2. bridge 通过 stdio 双向 JSON-RPC 与其通信
+3. 删除 runtime-host websocket 守护、listen URL 分配和对应运维概念
+4. 保留 pull-primary、ledger、approval/user-input、final-reply redelivery 等上层语义不变
+
+一句话：**功能不变，transport 变薄，稳定性与可维护性上升。**
+
+## 2. 背景
+
+前一轮协议对齐已经收口了一个关键判断：
+
+1. bridge 不该再把 transport 生命周期误判成任务真相
+2. 最终结果应继续以 `thread/read(includeTurns=true)` 为 pull-primary 真相源
+3. 在线事件只作为实时体验增强和协议事实缓存
+
+这意味着 websocket 已经从“正确性基石”降级为“运输层实现细节”。
+
+既然如此，就要继续追问一句：
+
+> 这个实现细节本身还有没有独立价值？
+
+当前答案是：没有。
+
+当前 websocket 链条带来的额外复杂度包括：
+
+1. `runtime-host` 独立后台进程
+2. `WORK_ALLY_CODEX_LISTEN` / `listenUrl` / runtime.env / health.json
+3. 端口选择、冲突重试、allocator lock
+4. websocket connect/close/reconnect 状态机
+5. shell 验证依赖 loopback listen
+6. 运维文档里大量 `runtime-host listen` / `runtime-host` 状态说明
+
+这些东西并不提升用户能力，只是在维护 transport 本身。
+
+## 3. 问题定义
+
+当前 websocket transport 的问题不是“偶尔断一下”，而是它形成了一整条本不该存在的产品内部子系统。
+
+### 3.1 多出来的进程层
+
+当前本机路径是：
+
+1. `ally start`
+2. 启动 `runtime-host` 后台进程
+3. `runtime-host` 以 `codex app-server --listen ws://127.0.0.1:PORT` 运行
+4. bridge 再通过 websocket 连接它
+
+这让产品多了一层无谓的进程边界。
+
+### 3.2 多出来的地址层
+
+当前为了 websocket，需要维护：
+
+1. listen URL 选择
+2. runtime 状态文件中的 `WORK_ALLY_CODEX_LISTEN`
+3. health 中的 `listen`
+4. 用户侧 `ally status` 中的 `runtime-host listen`
+
+这些都不是用户需要的产品概念。
+
+### 3.3 多出来的故障层
+
+当前 transport 一旦出问题，系统就多出一整类本可避免的故障：
+
+1. loopback listen 失败
+2. 端口冲突
+3. runtime-host 活着但 websocket 会话失效
+4. reconnect 行为与 pull-primary 叠加后的复杂语义
+
+### 3.4 多出来的测试层
+
+当前 shell 与 unit 测试里不得不覆盖：
+
+1. listen URL 选择
+2. runtime-host 存活
+3. websocket close/reconnect
+4. probe/ping-pong 依赖 listen 地址
+
+这会拖慢门禁，也让测试地图偏离真正要守的产品合同。
+
+## 4. 为什么现在做
+
+现在适合做，而不是以后。
+
+1. 前一轮协议语义已经先收好了，transport 可以单独切，不会再和任务语义混改
+2. 当前产品还处于内部打磨期，可以接受一次 clean break
+3. 如果继续拖，更多 shell、desktop、文档、运营口径都会继续建立在 `runtime-host/ws` 之上
+4. 这个复杂度没有业务价值，越早删越好
+
+## 5. 目标
+
+本次改动必须达成以下目标：
+
+1. bridge 默认直接使用 `stdio` transport 与 `codex app-server` 通信
+2. bridge 负责拉起和管理自己的 runtime child process，不再依赖 websocket listen 地址
+3. 删除 `WORK_ALLY_CODEX_LISTEN`、runtime listen state、port allocator 这条链
+4. 删除 `runtime-host` 作为单独后台服务的概念；用户运维口径只保留 bridge / supervisor / autosave
+5. pull-primary、approval、user-input、redelivery、ledger 等上层行为保持不变
+6. shell / unit / integration 门禁同步迁移到 stdio 主路径
+7. 文档、README、status 输出、runbook 不再暴露 websocket/runtime-host listen 概念
+
+## 6. 非目标
+
+这次明确不做：
+
+1. 不改变 Feishu 通道实现
+2. 不重写 approval / user-input / session-store 语义
+3. 不把 bridge 和 Codex 变成远程分布式架构
+4. 不在本期保留 websocket 作为并行 fallback transport
+5. 不为了兼容旧状态而长期保留 runtime-host 双轨逻辑
+
+原则：**不搞双轨长期并存。**
+
+## 7. 新模型
+
+### 7.1 运行模型
+
+新模型应改为：
+
+1. `ally start`
+2. `supervisor` 拉起 `bridge`
+3. `bridge` 内部按需启动 `codex app-server --listen stdio://`
+4. `CodexRuntimeClient` 通过子进程 `stdin/stdout` 做 JSON-RPC
+
+也就是说，runtime 不再是 bridge 外面的“另一个服务”，而是 bridge 直接管理的本地 child process。
+
+### 7.2 生命周期
+
+1. bridge 启动时，先拉起 app-server child
+2. bridge 停止时，一并停止 child
+3. child 异常退出时，bridge 将其视为 runtime transport failure，并继续沿现有 pull-primary / recovery 语义处理
+4. supervisor 不再单独托管 runtime-host，只托管 bridge 与 assistant-autosave
+
+### 7.3 健康语义
+
+对用户和运维侧只保留：
+
+1. `bridge` 是否运行
+2. bridge 内部 runtime 是否 healthy
+
+不再单独输出：
+
+1. `runtime-host pid`
+2. `runtime-host listen`
+3. `WORK_ALLY_CODEX_LISTEN`
+
+必要时 bridge health 可以包含：
+
+1. `runtime_status: healthy|degraded|stopped`
+2. `runtime_reason`
+
+但这属于 bridge 内部健康事实，不再暴露为独立 transport 面板。
+
+## 8. 机制设计
+
+### 8.1 Runtime Client 抽象
+
+`CodexRuntimeClient` 需要从“websocket client”重构为“app-server transport client”。
+
+最小拆分：
+
+1. 保留 JSON-RPC 协议逻辑、turn state、pull-primary、approval/user-input 解析
+2. 替换底层 transport：
+   - 从 `WebSocket` 读写
+   - 改为 child process `stdin/stdout` 读写
+3. `connect()` 的含义从“建立 ws 连接”变成“确保 child process 已存在且 initialize 完成”
+4. `disconnect()` 的含义从“关闭 websocket”变成“停止 child process 并清理 pending request”
+
+### 8.2 Child Process 管理
+
+bridge 内部需要：
+
+1. `spawn('codex', ['app-server', '--listen', 'stdio://'])`
+2. 绑定 `stdin/stdout/stderr`
+3. 逐行读取 stdout JSONL
+4. stderr 只进日志，不作为协议通道
+5. 子进程退出时统一走 runtime disconnect/recovery 逻辑
+
+### 8.3 配置模型
+
+删除：
+
+1. `runtime.listenUrl`
+2. `WORK_ALLY_CODEX_LISTEN`
+3. runtime.env 中的 listen state
+
+保留：
+
+1. `runtime.mode`
+2. `approvalPolicy`
+3. `sandboxMode`
+4. assistant `codexHome`
+
+如需显式 transport 配置，最多保留内部字段：
+
+1. `runtime.transport = stdio`
+
+但默认不需要暴露给用户。
+
+### 8.4 Shell / Supervisor / Status
+
+需要同步修改：
+
+1. `internal/modules/runtime/start.sh`
+   - 不再启动独立 runtime-host
+   - bridge 启动前不再做 listen URL 分配
+2. `internal/modules/runtime/supervisor.sh`
+   - 不再维护 runtime-host 子进程
+3. `internal/modules/runtime/status.sh`
+   - 删除 `runtime-host listen`
+   - 删除 runtime-host 独立 pid/health 展示
+   - 只展示 bridge 与其内部 runtime 健康
+4. `internal/lib/common.sh`
+   - 删除 runtime listen state / allocator / healthcheck shell 路径
+
+### 8.5 Probe / Ping-Pong 工具
+
+`runtime/host/*.ts` 这些 websocket/listen probe 脚本需要改造或删除。
+
+建议：
+
+1. 保留“真实 codex app-server 探针”这个能力
+2. 但探针改成直接走 stdio child-process，而不是依赖外部 listen URL
+3. `find-open-listen-url.ts` 可直接删除
+
+## 9. 用户与维护者可见变化
+
+### 9.1 用户侧
+
+用户不应感知功能变化。
+
+仍然保持：
+
+1. `ally start`
+2. `ally stop`
+3. `ally status`
+
+用户侧变化只体现在：
+
+1. 少一层无意义的 runtime-host 概念
+2. 少一类 transport/listen/端口相关故障
+
+### 9.2 维护者侧
+
+维护者会看到：
+
+1. `ally status` 不再显示 `runtime-host listen`
+2. runbook 不再教人看 `WORK_ALLY_CODEX_LISTEN`
+3. shell 验证不再依赖 loopback listen 权限
+
+## 10. 验收标准
+
+### 10.1 功能行为
+
+1. 普通 Feishu / fake channel 对话仍可完成完整 turn
+2. approval / user-input / `/stop` / recovery / redelivery 行为不回归
+3. routines 仍可调用真实 Codex runtime
+
+### 10.2 架构行为
+
+1. 仓库主链路中不再依赖 websocket listen URL
+2. `runtime-host` 不再作为独立后台服务存在
+3. `WORK_ALLY_CODEX_LISTEN` 不再是默认主路径配置
+4. `find-open-listen-url.ts`、port allocator、runtime.env listen state 被清理
+
+### 10.3 文档行为
+
+1. README / quickstart / runbook / troubleshooting 不再把 websocket runtime-host 当默认模型
+2. 测试地图同步反映 stdio 主路径
+
+### 10.4 自动化门禁
+
+至少通过：
+
+1. `node --test tests/unit/runtime/**/*.test.mjs tests/unit/session/**/*.test.mjs tests/integration/session/**/*.test.mjs`
+2. 相关 shell smoke（尤其 `tests/shell/codex-runtime.sh`、`tests/shell/status-health.sh`、`tests/shell/smoke.sh`）
+3. 必要时更新 `tests/fixtures/empty-work-ally-home/releases/stable/`
+
+## 11. 子任务拆解
+
+### A. Runtime client transport 改造
+
+1. 抽离 JSON-RPC codec 与 transport
+2. 用 stdio child-process 替换 websocket transport
+3. 保持现有 runTurn / pull-primary / approval / user-input / recoverTurnResult 接口不变
+
+### B. Runtime lifecycle 清理
+
+1. 删除 runtime-host listen state
+2. 删除 allocator / runtime.env listen
+3. 删除独立 runtime-host supervisor 管理
+
+### C. Shell / probe / status 收口
+
+1. 重写真实 codex runtime shell 测试为 stdio 模式
+2. 重写 probe/ping-pong 工具
+3. 更新 `ally status` 输出
+
+### D. 文档与测试地图收口
+
+1. README
+2. user quickstart
+3. ops runbook / troubleshooting
+4. test coverage map
+
+## 12. 风险
+
+### 风险 1：child-process 管理不当导致 bridge 停止时残留 Codex 进程
+
+应对：
+
+1. 明确 `disconnect()` / process exit cleanup
+2. shell 测试补 stop/restart 场景
+
+### 风险 2：stdio JSONL 处理有边界差异
+
+应对：
+
+1. 先做最小真实 probe
+2. 保持现有 fake runtime 和高密度 unit/integration 测试不动，上层接口不变
+
+### 风险 3：status/runbook 一次没清干净，留下旧口径
+
+应对：
+
+1. 全仓 `rg websocket|listenUrl|runtime-host listen|WORK_ALLY_CODEX_LISTEN`
+2. 逐项清理 shipped 文档
+
+## 13. 完成定义
+
+只有同时满足以下条件，才算这次“删干净”：
+
+1. bridge 默认运行不再依赖 websocket listen URL
+2. `runtime-host` 独立后台服务已从默认模型删除
+3. `CodexRuntimeClient` 已以 stdio child-process 为主路径
+4. shell、unit、integration 测试已更新并通过
+5. README / runbook / status / troubleshooting 已无旧 websocket 主模型口径
+6. 用户不需要知道 `listen`、端口、runtime-host 这些中间概念
+