feat: adapt codex app-server protocol updates

docs/architecture/codex_server_progress_card_cn.md

@@ -1,10 +1,10 @@
 # Codex Server 协议与 Boss 执行进度卡接入记录
 
-更新时间：`2026-05-16`
+更新时间：`2026-05-31`
 
 ## 1. Codex 最新开放协议结论
 
-2026-05-16 的最新架构判断：Boss 后续优先围绕 Codex App Server 做深度接入，但当前生产链路仍保留 `codex exec resume`，`codex mcp-server` 作为兼容 provider 候选。
+2026-05-31 的最新架构判断：Boss 后续优先围绕 Codex App Server / Remote Control 做深度接入，但当前生产链路仍保留 `codex exec resume`，`codex mcp-server` 作为兼容 provider 候选。
 
 Codex App Server 是更适合 Boss 长期接入的协议层，因为它面向富客户端和产品级集成，覆盖：
 
@@ -16,7 +16,7 @@ Codex App Server 是更适合 Boss 长期接入的协议层，因为它面向富
 - model/list、skills/list、plugin/list、app/list
 - command execution、file change、tool input、MCP tool-call approvals
 
-Boss 不能直接把 App Server 原始 Thread / Turn / Item 字段写进业务层。当前第一批已经新增 `local-agent/codex-app-server-runner.mjs`，把 App Server 的 `thread/resume | thread/start -> turn/start -> item/agentMessage/delta -> turn/completed` 映射成 Boss 的普通任务完成回写；下一批再继续把 Approval、Skill、file changes 和更细粒度 progress 归一化为 Boss 自有的 `execution_progress / approval_card / change_set / risk_event / skill_capability`。
+Boss 不能直接把 App Server 原始 Thread / Turn / Item 字段写进业务层。当前第一批已经新增 `local-agent/codex-app-server-runner.mjs`，把 App Server 的 `thread/resume | thread/start -> turn/start -> item/agentMessage/delta -> turn/completed` 映射成 Boss 的普通任务完成回写；2026-05-31 已继续把 `turn/plan/updated`、`turn/diff/updated`、`item/started|completed`、`thread/started` 这类协议事件归一化为 Boss `execution_progress` 的步骤、分支变更、产物和后台智能体。
 
 官方文档入口：`https://developers.openai.com/codex/app-server`
 
@@ -32,13 +32,23 @@ Boss 不能直接把 App Server 原始 Thread / Turn / Item 字段写进业务
 
 本机当前检测结果：
 
-- 本机 `codex --version`：`codex-cli 0.131.0-alpha.9`
-- 本机 `codex app-server --help` 已可用；本机 help 当前显示 `--listen` 支持 `stdio://`、`unix://`、`unix://PATH` 和 `off`
-- 官方文档仍提到 WebSocket 传输，但标注 experimental / unsupported；Boss 当前只把 `stdio` 作为默认接入，后续如要接 WebSocket 必须先做协议快照和灰度开关
+- 本机 `codex --version`：`codex-cli 0.135.0-alpha.1`
+- 本机 `codex app-server --help` 已可用；本机 help 当前显示 `--listen` 支持 `stdio://`、`unix://`、`unix://PATH`、`ws://IP:PORT` 和 `off`
+- 本机 `codex app-server --help` 当前已经支持 `--ws-auth capability-token|signed-bearer-token`、`--ws-token-file`、`--ws-token-sha256`、`--ws-shared-secret-file`、issuer/audience/clock-skew 等 WebSocket 认证参数
+- 本机协议快照已生成到 `docs/protocol-snapshots/codex-app-server/0.135.0-alpha.1/`，共识别 137 个协议方法；确认支持 `thread/inject_items`、`thread/rollback`、`thread/goal/*`、`turn/steer`、`command/exec`、`thread/realtime/*`、`model/list`
+- Boss 当前默认仍以 `stdio` 作为本机 agent 接入方式；`ws://127.0.0.1:<port>` 和 `unix://PATH` 本地长驻 transport 已可灰度接入，WebSocket/Unix WebSocket handshake 支持 `Authorization: Bearer <token>`；非 loopback signed bearer/JWT、自动重连和健康探测仍保留为后续增强，不直接替换当前稳定链路
+- 官方文档提示 WebSocket ingress 满载时会返回 JSON-RPC `-32001 / Server overloaded; retry later.`；Boss runner 已对该错误做最多 3 次指数退避重试，避免长驻连接瞬时拥塞直接把用户任务打失败
 - Boss 第一批只用 App Server 做任务级 provider，不直接复用 ChatGPT Mobile 到 Codex App 的官方 relay；官方移动控制链路仍属于 ChatGPT App 与 Codex App 同账号/工作区之间的产品能力，不是第三方 Boss 可以稳定依赖的私有通道
 
 下一轮再核对版本时，不要只看 npm 包版本号；必须同时读取 App Server schema / TypeScript 定义，并把 protocol snapshot 保存到 `docs/protocol-snapshots/codex-app-server/<version>/`。
 
+当前“线程和线程之间可以直接对话”的产品判断：
+
+- Codex 已经有更强的 thread coordination、subagent thread spawn、`thread/fork`、`thread/read`、`thread/inject_items`、`turn/start`、`turn/steer` 等能力。
+- 但这不等同于任意两个 Codex 线程官方原生 P2P 互聊。更稳的理解是：一个上层 orchestrator 可以读取线程 A、把必要上下文注入线程 B、再启动或 steer 线程 B 的 turn。
+- Boss 应该把这层做成自己的 `Inter-Thread Broker`：用户看到的是“线程协作 / 主 Agent 协调”，底层实现由 App Server provider 完成 read / inject / start / steer / rollback，并把过程写入审计与进度卡。
+- 2026-05-31 已落地第一版 runner 能力：当任务携带 `intentCategory=thread_collaboration`、`sourceCodexThreadRef` 和 `targetCodexThreadRef` 时，`local-agent/codex-app-server-runner.mjs` 会执行 `thread/read(source) -> thread/inject_items(target) -> turn/start(target)`，并只注入受控摘要，不注入系统提示词、设备密钥或内部调度字段。
+
 ## 2. Boss 当前采用的接入策略
 
 短期不直接依赖 Codex Desktop 私有 UI 结构，也不把 Codex CLI 原始 stderr/stdout 泄露给 APP。
@@ -63,6 +73,12 @@ APP 展示结构对齐截图：
 - `生成结果`：从执行结果里提取文件、图片、APK、文档等产物名
 - `后台智能体`：预留 OMX / Hermes / explorer 等多智能体来源展示
 
+UI 参考：
+
+- image2 生成稿：`design/image2/boss-app-codex-app-server-progress-card-20260531.png`
+- 当前生成稿保持微信效率型：顶部保留项目目标 / 版本记录固定入口，聊天区只展示最终用户消息和结构化进度卡，进度卡分为 `进度 / 分支详情 / 生成结果 / 后台智能体`
+- 后续 Android / Web 继续按该稿收口，不新增无关功能，不把协议字段、系统提示词或执行 envelope 暴露给用户
+
 ## 3. 安全边界
 
 进度卡只允许展示用户可见摘要：
@@ -97,10 +113,17 @@ APP 展示结构对齐截图：
 - `local-agent` 新增 `Codex App Server` runner，boss-agent 默认打开；`conversation_reply / dispatch_execution` 会先尝试 App Server，任务尚未真正启动 turn 时允许回退 CLI，turn 已启动后不再重复下发，避免双写同一线程
 - `local-agent` 新增 `Codex Computer Use -> CUA Driver` 桌面控制级 fallback：远程控制这台电脑时默认先通过 Codex Computer Use 执行，失败后再走 Boss 既有 CUA Driver runtime
 - `device-heartbeat` 设备能力新增 `codexAppServer`，用于前台和后台知道该设备是否具备 App Server provider
+- 新增 `scripts/codex-app-server-protocol-snapshot.mjs`，可把本机 Codex App Server 的 help、JSON Schema、TypeScript bindings 和方法清单生成到 `docs/protocol-snapshots/codex-app-server/<version>/`
+- `local-agent/codex-app-server-runner.mjs` 已吸收 App Server 协议进度事件，并把 plan、diff、artifact、subagent 归一成 Boss `executionProgress`，服务端 complete 回写会与本地 Git/GitHub 进度合并，不再覆盖协议原生进度
+- 新增实时进度入口 `POST /api/v1/master-agent/tasks/[taskId]/progress`，设备端可在任务执行中持续刷新同一张 `execution_progress` 卡；`local-agent` 的 App Server runner 已在收到协议进度事件时调用该接口，complete 仍携带最终进度作为兜底
+- 新增服务端线程协作入口 `POST /api/v1/projects/[projectId]/thread-collaboration`，由 Boss 校验源/目标项目权限并创建 `intentCategory=thread_collaboration` 的 `conversation_reply` 任务；设备端继续通过 App Server runner 执行 `thread/read -> thread/inject_items -> turn/start`，避免把“线程互通”误做成无监管 P2P
+- 新增活跃 turn 干预：任务携带 `targetCodexTurnId` / `targetTurnId` 时，App Server runner 会调用 `turn/steer`，并把 `turnControl=steer`、`turnId` 写回执行结果；没有活跃 turn id 时仍使用 `turn/start`
+- `getCodexAppServerRunnerConfig` 已识别 `codexAppServerTransport` / `BOSS_CODEX_APP_SERVER_TRANSPORT`、`codexAppServerUrl` / `BOSS_CODEX_APP_SERVER_URL`、`codexAppServerAuthTokenFile` / `BOSS_CODEX_APP_SERVER_AUTH_TOKEN_FILE`；`local-agent/codex-app-server-runner.mjs` 现已支持 `stdio`、`ws://127.0.0.1:<port>` 与 `unix://PATH` 三种 JSON-RPC transport，默认仍是 stdio，ws/unix 适合作为同机长驻 App Server 灰度路径
+- 新增 App Server 过载退避：单个 JSON-RPC 请求收到 `-32001` 或 `retry later` 文案时，会在同一个任务生命周期内重试，超出上限后才进入失败/CLI fallback 判定
 
 后续建议按两步继续：
 
-1. 把当前 runner 提升为完整 `CodexAppServerBackendAdapter`：继续补 Approval / file change / skill / app / browser / computer-use 事件映射，但保持 feature flag 默认关闭。
-2. 新增 `CodexMcpBackendAdapter`：让 `codex mcp-server` 成为 `ExecutionBackend` 的兼容实现，用于 App Server 不可用或只需要轻量会话时。
-3. 增加任务级 live progress API：`POST /api/v1/master-agent/tasks/[taskId]/progress`，让本地 agent 在执行中也能实时刷新进度卡，而不是只在 claim / complete 两个节点更新。
-4. 建立协议快照目录和兼容测试：每次 Codex 协议升级时生成 schema、跑映射测试、灰度打开新 capability，避免把某个 Codex 版本写死到 APP 或后台。
+1. 把当前 runner 提升为完整 `CodexAppServerBackendAdapter`：继续补 Approval / file change patch / skill / plugin / app / MCP tool / realtime 事件映射，但保持 feature flag 默认关闭。
+2. 完善长驻 transport 灰度：`ws://127.0.0.1:<port>`、`unix://PATH` 和 bearer token handshake 已可用，下一步补 signed bearer JWT 的 issuer / audience 校验联调、断线重连和健康探测；失败自动回退 stdio。
+3. 新增 `CodexMcpBackendAdapter`：让 `codex mcp-server` 成为 `ExecutionBackend` 的兼容实现，用于 App Server 不可用或只需要轻量会话时。
+4. 每次 Codex 协议升级时生成 schema、跑映射测试、灰度打开新 capability，避免把某个 Codex 版本写死到 APP 或后台。