# Codex Server 协议与 Boss 执行进度卡接入记录

更新时间：`2026-06-04`

## 1. Codex 最新开放协议结论

2026-05-31 的最新架构判断：Boss 后续优先围绕 Codex App Server / Remote Control 做深度接入，但当前生产链路仍保留 `codex exec resume`，`codex mcp-server` 作为兼容 provider 候选。

2026-06-04 按官方文档与本机 `codex-cli 0.136.0-alpha.2` 复核后的口径：`codex app-server` 是 Boss 直接控制 Codex 线程、turn、审批、进度事件和治理动作的主协议；`codex remote-control` 是带 remote-control 能力的本机 App Server daemon 管理入口；`codex mcp-server` 是让其他 Agent / MCP 客户端把 Codex 当工具调用的兼容入口；`features.multi_agent` 提供 `spawn_agent / send_input / resume_agent / wait_agent / close_agent` 这类主控调度子 Agent 的能力，但不等同于任意两个历史线程官方原生 P2P 私聊。Boss 产品口径继续固定为“Boss Broker + App Server read / inject / start / steer / rollback 的受控线程协作”。

Codex App Server 是更适合 Boss 长期接入的协议层，因为它面向富客户端和产品级集成，覆盖：

- authentication
- conversation history
- approvals
- streamed agent events
- Thread / Turn / Item
- model/list、skills/list、skills/extraRoots/set、hooks/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 的普通任务完成回写。

2026-05-31 已继续把 `turn/plan/updated`、`turn/diff/updated`、`item/started|completed`、`thread/started` 这类协议事件归一化为 Boss `execution_progress` 的步骤、分支变更、产物和后台智能体。同日第二批补齐 `item/*/requestApproval`、`item/autoApprovalReview/*`、`guardianWarning`、`serverRequest/resolved` 和 `item/fileChange/patchUpdated` 的安全摘要映射，APP 只展示审批状态、风险提醒和文件路径，不展示完整命令、diff、系统提示词或密钥。第三批已把 `thread/status/changed` 与 `thread/realtime/*` 归一成 `executionProgress.threadStatus / realtime`，APP 只展示活跃/等待审批/等待用户输入、realtime 文本摘要、音频片段计数和关闭/错误原因；第四批已把 `model/rerouted`、`thread/tokenUsage/updated`、`mcpServer/startupStatus/updated` 和 `remoteControl/status/changed` 归一成 `executionProgress.modelRoute / tokenUsage / mcpServers / remoteControl`，用于 APP “运行状态”区块。

2026-06-01 第五批已把 `thread/goal/updated|cleared`、`thread/settings/updated` 和 `thread/compacted` 归一成 `executionProgress.threadGoal / threadSettings / compaction`，用于 APP “线程配置”区块；第六批已把 `account/updated`、`account/rateLimits/updated`、`model/verification`、`warning`、`configWarning`、`deprecationNotice` 归一成 `executionProgress.accountStatus / modelVerification / warnings`；第七批已把官方 `ThreadItem.collabToolCall` 归一成 `executionProgress.threadCollaboration`，并按官方建议把新版 `ThreadItem.contextCompaction` 映射回 `executionProgress.compaction`；第八批已把 `mcpToolCall`、`dynamicToolCall`、`webSearch`、`imageView`、`enteredReviewMode`、`exitedReviewMode` 和 `commandExecution` 归一成 `executionProgress.toolActivities`；第九批已把官方 `ThreadItem.plan` 的最终 `item/completed` 文本映射为 `executionProgress.steps`，并把 `ThreadItem.reasoning.summary` 映射为 `executionProgress.reasoningSummary`；第十批已把 `ThreadItem.imageGeneration` 安全映射为 `executionProgress.toolActivities` 的图像生成活动和 `executionProgress.artifacts` 的图片产物；第十一批已把 `hook/started|completed` 安全映射为 `executionProgress.toolActivities` 的钩子活动，供 APP 以“钩子”轻卡展示企业治理和插件生命周期状态；第十二批已把 `windowsSandbox/setupCompleted` 安全映射为 `executionProgress.windowsSandbox`，供 APP 在“运行状态”里展示 Windows 沙箱准备状态、setup mode 和脱敏错误摘要；第十三批已把 heartbeat discovery 扩展到 `experimentalFeature/list`、`collaborationMode/list`、`permissionProfile/list` 和 `mcpServerStatus/list`，供设备详情、APP 和 PC 后台看到实验特性、协作模式、权限 Profile 与 MCP 服务摘要；第十四批已把 `account/read`、`account/rateLimits/read`、`config/read`、`configRequirements/read` 和 `externalAgentConfig/detect` 纳入 heartbeat discovery，用于展示账号、套餐、额度、App 配置、托管要求和外部 Agent 迁移候选摘要；第十五批已把 `thread/list` 和 `thread/loaded/list` 纳入 heartbeat discovery，用于展示线程总数、已加载线程、活跃线程、归档线程和非归档可见线程轻量目录；第十六批已把 `thread/turns/list` 纳入 heartbeat discovery，用于展示总轮次、运行中轮次、完成轮次和每个非归档线程的最近 turn 状态摘要；第十七批已按 `codex-cli 0.136.0-alpha.2` 补齐 `skills/extraRoots/set`，支持把企业共享 Skill 根下发给 App Server 后再拉取 `skills/list`，并把新版 `ThreadItem.collabToolCall.receiverThreadIds / agentsStates` 安全映射成目标数量和 agent 状态集合；第十八批已把 `hooks/list` 纳入 heartbeat discovery，用于展示本机 Codex hook 数、启用数、信任状态和 warning/error 计数；第十九批已新增线程操作能力摘要，用于展示 `thread/archive / thread/unarchive / thread/fork / thread/compact/start / thread/rollback / thread/name/set / thread/metadata/update / thread/shellCommand / thread/unsubscribe / turn/interrupt / turn/steer` 这类动作是否进入 Boss 受控能力目录；第二十批已新增插件治理能力摘要，用于展示 `plugin/install / plugin/uninstall / plugin/read / plugin/skill/read / plugin/share/*` 这类动作是否进入 Boss 受控能力目录；第二十一批已新增账号与配置治理能力摘要，用于展示 `account/login/* / account/logout / account/chatgptAuthTokens/refresh / account/sendAddCreditsNudgeEmail / config/value/write / config/batchWrite / config/mcpServer/reload / skills/config/write` 这类动作是否进入 Boss 受控能力目录；第二十二批已新增文件系统与命令会话治理能力摘要，用于展示 `fs/readFile / fs/writeFile / fs/remove / fs/watch / command/exec/write / command/exec/terminate` 这类动作是否进入 Boss 受控能力目录；第二十三批已新增外部 Agent 迁移、Marketplace 和实验特性治理能力摘要，用于展示 `externalAgentConfig/import / marketplace/add / marketplace/remove / marketplace/upgrade / experimentalFeature/enablement/set` 这类动作是否进入 Boss 受控能力目录；第二十四批已新增审查、Windows 沙箱和文件搜索事件能力摘要，用于展示 `review/start / windowsSandbox/readiness / windowsSandbox/setupStart / fuzzyFileSearch/session*` 是否进入 Boss 受控能力目录；第二十五批已新增 MCP、用户交互和 Guardian 治理能力摘要，用于展示 `mcpServer/oauth/login / mcpServer/tool/call / mcpServer/elicitation/request / item/tool/requestUserInput / thread/approveGuardianDeniedAction` 是否进入 Boss 受控能力目录；第二十六批已新增运行事件、扩展事件和线程生命周期事件能力摘要，用于展示 `process/outputDelta / process/exited / rawResponseItem/completed / skills/changed / plugin/installed / thread/started|closed|archived|unarchived|name/updated` 是否进入 Boss 受控能力目录；第二十七批已新增流式增量事件能力摘要，用于展示 `item/agentMessage/delta / item/plan/delta / item/reasoning/*Delta / item/mcpToolCall/progress / command/exec/outputDelta / item/commandExecution/terminalInteraction / item/fileChange/outputDelta` 是否进入 Boss 受控能力目录。2026-06-03 已把这些流式 delta 从“能力目录”继续接入到任务执行态 `executionProgress.streamEvents`，APP 只显示 agent / plan / reasoning / MCP / command / terminal / file 的片段计数，不保存原始增量文本、命令输出、推理正文或文件输出。

2026-06-03 第二十八批已把 heartbeat `thread/turns/list` 从 `itemsView=notLoaded` 升级为 `itemsView=summary`，但只提取最终 `agentMessage` 安全摘要，并合并到 `projectCandidates.recentAssistantMessages`；服务端据此把 Codex Desktop 自己产生的新最终回复反向同步到 Boss APP 对应会话、preview、lastMessageAt 和未读数。

2026-06-04 第二十九批已按本机 `codex-cli 0.136.0-alpha.2` 重新生成协议快照，manifest 扩展到 151 个 method，并新增 schema 暴露的 `ThreadItem` 类型矩阵。当前 schema 确认 `app/list`、`app/list/updated`、`configRequirements/read`、`mcpServerStatus/list` 和 `ThreadItem.contextCompaction`，但未声明 `collaborationMode/list`、`thread/turns/list` 或 `ThreadItem.collabToolCall`；Boss 因此新增 `threadCollaborationSummary`，在设备详情页明确展示 Boss Broker 可用、协作事件 handler 可用、协作模式数量和“非原生私聊”状态，避免把线程协作误做成无监管 P2P。

同日第二十九批追加 `protocolDriftSummary`：runner 会把 discovery errors 归一成 method 级失败探针，把官方文档跟进项固定展示为 `collaborationMode/list`、`thread/turns/list`、`ThreadItem.collabToolCall`，并把当前兜底策略显示为 Boss Broker + App Server 注入/执行。APP/后台只展示“协议漂移：兼容/告警 · 失败探针 N 个 · 文档跟进 N 项 · Boss Broker 兜底”，不展示错误原文、线程 ID、用户正文或内部 prompt。

除用于 Boss APP 会话反向同步的最终 `agentMessage` 安全摘要外，`thread/realtime/sdp`、音频 base64、原始 realtime item、remote installationId、thread settings 的 `cwd`、compaction `turnId`、collaboration settings 内部 prompt、collabToolCall 源/目标线程 ID、`receiverThreadIds`、`agentsStates.message`、共享 Skill 根绝对路径、hook key/command/sourcePath/statusMessage/hash/error message、tool arguments/result/contentItems、web URL token、命令正文/输出、raw reasoning `content`、reasoning item id、imageGeneration 原始 result/revisedPrompt、hook id/sourcePath/statusMessage/entries、Windows sandbox sourcePath/samplePaths、本地绝对路径、permission profile 文件规则、MCP resource URI、账号邮箱、API key、完整 config、外部 Agent 迁移描述、turn id、turn items、turn 内容、用户正文、原始模型输出和未清洗的 MCP 错误不入账。

官方文档入口：`https://developers.openai.com/codex/app-server`

当前仍可作为 Boss 兼容集成入口的是 Codex CLI MCP server：

- 启动命令：`codex mcp-server`
- Inspector 调试：`npx @modelcontextprotocol/inspector codex mcp-server`
- 官方 MCP 工具：
  - `codex`：启动一个 Codex 会话，入参包含 `prompt / approval-policy / base-instructions / config / cwd / include-plan-tool / model / profile / sandbox`
  - `codex-reply`：继续一个 Codex 会话，入参包含 `prompt / threadId`，`conversationId` 只是兼容别名
- 线程续写应使用 `tools/call` 返回里的 `structuredContent.threadId`
- 现代 MCP 客户端主要读取 `structuredContent`；`content` 只作为旧客户端兼容输出

本机当前检测结果：

- 本机 `codex --version`：`codex-cli 0.136.0-alpha.2`
- 本机 `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 认证参数
- 本机 `codex remote-control --help` 已可用；它会管理“带 remote control enabled 的 App Server daemon”，当前 boss-agent 状态页已把 `codexRemoteControlEnabled / codexRemoteControlCommand / codexRemoteControlArgs` 归一成 `Codex Remote Control` 摘要，但状态页刷新不会自动执行 `start`
- 本机 `codex mcp-server --help` 已可用；它用于把 Codex 暴露为 stdio MCP server，后续进入 `CodexMcpBackendAdapter` 兼容 provider，而不是替代 App Server 主链
- 本机协议快照已生成到 `docs/protocol-snapshots/codex-app-server/0.136.0-alpha.2/`，共识别 151 个协议方法；确认支持 `thread/inject_items`、`thread/rollback`、`thread/archive`、`thread/unarchive`、`thread/fork`、`thread/compact/start`、`thread/name/set`、`thread/metadata/update`、`thread/shellCommand`、`thread/unsubscribe`、`thread/goal/*`、`turn/steer`、`turn/interrupt`、`command/exec`、`command/exec/write`、`command/exec/resize`、`command/exec/terminate`、`command/exec/outputDelta`、`process/outputDelta|exited`、`rawResponseItem/completed`、`thread/realtime/*`、`thread/started|closed|archived|unarchived|name/updated`、`item/agentMessage/delta`、`item/plan/delta`、`item/reasoning/*Delta`、`item/mcpToolCall/progress`、`item/commandExecution/terminalInteraction`、`item/fileChange/outputDelta`、`account/*`、`model/verification`、`configWarning`、`deprecationNotice`、`model/list`、`skills/changed`、`skills/extraRoots/set`、`hooks/list`、`plugin/installed`、`plugin/install`、`plugin/uninstall`、`plugin/read`、`plugin/skill/read`、`plugin/share/*`、`config/value/write`、`config/batchWrite`、`config/mcpServer/reload`、`skills/config/write`、`fs/*`、`externalAgentConfig/import`、`marketplace/add|remove|upgrade`、`experimentalFeature/enablement/set`、`review/start`、`windowsSandbox/readiness|setupStart`、`fuzzyFileSearch/session*`、`mcpServer/oauth*`、`mcpServer/resource/read`、`mcpServer/tool/call`、`mcpServer/elicitation/request`、`item/tool/requestUserInput` 和 `thread/approveGuardianDeniedAction`
- 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 heartbeat 已新增 App Server 能力发现缓存：按 `codexAppServerDiscoveryTtlMs` 拉取 `model/list`、`modelProvider/capabilities/read`、`skills/list`、`hooks/list`、`plugin/list`、`app/list`、`experimentalFeature/list`、`collaborationMode/list`、`permissionProfile/list`、`mcpServerStatus/list`、`account/read`、`account/rateLimits/read`、`config/read`、`configRequirements/read`、`externalAgentConfig/detect`、`thread/list`、`thread/loaded/list` 和 `thread/turns/list`；配置了 `codexAppServerSkillExtraRoots` / `BOSS_CODEX_APP_SERVER_SKILL_EXTRA_ROOTS` 时，会先调用 `skills/extraRoots/set` 再拉取 `skills/list`，归一成设备 `capabilities.codexAppServer.metadata`；发现失败只记录 warn，不阻塞心跳。MCP discovery 使用 `detail=toolsAndAuthOnly`，turn discovery 固定 `itemsView=summary`，账号、配置、线程、Hook 和 Skill extra root discovery 只保留安全摘要；turn discovery 只额外保留最终 `agentMessage` 摘要，并会合并进 `projectCandidates.recentAssistantMessages` 用于 Codex Desktop 回复反向同步，不保存邮箱、resource URI、工具参数、完整 config、本地路径、迁移描述、用户正文、reasoning 原文、命令输出、原始 items、内部 prompt、系统提示词、hook 命令或共享 Skill 根绝对路径。
- 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。

当前实现采用 Boss 自有结构化消息：

- 新消息类型：`execution_progress`
- 服务端字段：`Message.executionProgress`
- 触发范围：
  - 普通单线程对话：用户在 Boss APP 指定线程里发消息
  - 主 Agent 托管线程：托管消息实际派到目标 Codex 线程时
  - 群聊确认下发：后续目标线程执行单会复用同一张卡
- 生命周期：
  - 任务入队：创建进度卡
  - local-agent 认领：更新为 running
  - local-agent 完成：更新同一张卡为 completed / failed

APP 展示结构对齐截图：

- `进度`：步骤列表，显示已完成 / 进行中 / 待处理 / 失败
- `安全提醒`：展示 Guardian warning 的用户可读摘要
- `审批状态`：展示命令 / 文件 / 权限审批与自动复核状态
- `文件变更`：展示 App Server patchUpdated 中的文件路径和变更类型，不展示 diff
- `线程状态`：展示 `active / idle / systemError / notLoaded` 以及 `waitingOnApproval / waitingOnUserInput`
- `实时状态`：展示 realtime 启动、同步、关闭或错误状态，附带安全清洗后的 transcript 预览和计数
- `线程配置`：展示 thread goal、模型 / provider、审批 / 沙箱、协作模式和上下文压缩状态
- `线程协作`：展示运行时兼容 `collabToolCall` 事件或 Boss Broker 协作摘要的工具名、执行状态、目标类型、目标数量和智能体状态集合，不展示源/目标线程 ID、`receiverThreadIds`、prompt 或 agent 私有消息；本机 schema 未声明该 item 时，APP 只显示 Boss 受控协作状态，不显示“原生线程互聊”
- `协议漂移`：展示 App Server discovery 的兼容/告警状态、失败探针数量、官方文档跟进项数量和 Boss Broker 兜底策略，不展示错误原文、线程 ID、用户正文或内部 prompt
- `工具活动`：展示 MCP / dynamic tool / web search / image view / image generation / hook / Review / command 的类型、名称、状态和安全摘要，不展示参数、结果、URL token、命令正文、命令输出、图像生成原始 result/revised prompt 或 hook 原始输出
- `思考摘要`：展示 Codex 官方 reasoning `summary` 和状态，不展示 raw reasoning `content`、item id 或密钥
- `流式增量`：展示 agent 回复片段、计划片段、思考片段、MCP 进度、命令输出片段、终端交互和文件输出片段计数，不展示原始 delta、命令输出、推理正文或文件输出
- `运行状态`：展示模型重路由、上下文用量、MCP 启动状态、远控连接状态和 Windows 沙箱准备状态
- `分支详情`：变更行、Git 操作、GitHub CLI 可用状态
- `生成结果`：从执行结果里提取文件、图片、APK、文档等产物名
- `后台智能体`：预留 OMX / Hermes / explorer 等多智能体来源展示

UI 参考：

- image2 生成稿：`design/image2/boss-app-codex-app-server-progress-card-20260531.png`
- 当前生成稿保持微信效率型：顶部保留项目目标 / 版本记录固定入口，聊天区只展示最终用户消息和结构化进度卡，进度卡分为 `进度 / 线程状态 / 实时状态 / 线程配置 / 线程协作 / 工具活动 / 思考摘要 / 账号状态 / 运行状态 / 安全提醒 / 审批状态 / 文件变更 / 分支详情 / 生成结果 / 后台智能体`
- 后续 Android / Web 继续按该稿收口，不新增无关功能，不把协议字段、系统提示词或执行 envelope 暴露给用户

## 3. 安全边界

进度卡只允许展示用户可见摘要：

- 不展示系统提示词
- 不展示完整执行 prompt
- 不展示设备 token、账号密钥、内部工作目录调度说明
- 不展示 Codex CLI 启动 envelope、sandbox、approval、session id、MCP 启动日志
- `RemoteRuntimeAdapter` 仍会先拦截只读环境提示和 Codex envelope 泄漏，再进入消息账本

## 4. 历史引用项目最新状态

本次按 GitHub 最新元数据核对过的项目：

| 项目 | 最新状态 | 对 Boss 的可借鉴点 |
| --- | --- | --- |
| `openai/codex` | `rust-v0.129.0`，2026-05-07 发布；main 在 2026-05-08 仍有提交 | 后续优先补 `codex mcp-server` 长驻适配器；参考 ThreadStore、turn metadata、app-server protocol v3 方向，不再只靠 `codex exec resume` |
| `Yeachan-Heo/oh-my-codex` | `v0.16.2`，2026-05-08 发布 | `$ultragoal` 聚合目标、commit-shared wiki / compaction、state/session isolation、Codex native hook setup 值得同步到 Boss 的任务目标与进度卡 |
| `ultraworkers/claw-code` | main 最新提交 2026-05-06；原 `instructkr/claw-code` 已指向该仓库；暂无 GitHub release | 继续保留抽象后端，不写死版本；重点观察 skills help routing、push_output_block、Rust harness 更新 |
| `NousResearch/hermes-agent` | `v2026.5.7 / v0.13.0`，Tenacity Release | Durable Multi-Agent Kanban、heartbeat / reclaim / zombie detection、goal lock、checkpoints v2 可作为 Boss 主 Agent 长任务可靠性升级参考 |
| `iflytek/skillhub` | `v0.2.6`，2026-04-29 发布；main 2026-05-08 仍更新 | Skill 订阅通知、OIDC 登录、S3 IAM、namespace CSV 批量成员导入，适合 Boss 企业 Skill 治理后台后续吸收 |
| `openclaw/openclaw` | `v2026.5.7`，2026-05-07 发布；main 2026-05-08 仍更新 | Telegram allowlist、polling watchdog、deliverySucceeded、Codex approval 去重、provider/model callback 修复，可用于 Boss Telegram 网关和远程审批 |
| `goldmar/openclaw-code-agent` | `v4.2.3`，2026-05-08 发布 | OpenClaw + Codex coding agent 的 session lifecycle、wake routing、worktree/PR policy，可作为 Boss “聊天控制桌面 Codex 开发”的旁路参考 |

## 5. 下一步建议

第一阶段已经落地：

- Boss 消息账本新增 `execution_progress`
- Android 原生聊天页新增结构化进度卡
- local-agent 完成回写会补 Git diff、GitHub CLI 状态和产物名
- `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 进度合并，不再覆盖协议原生进度
- `local-agent/codex-app-server-runner.mjs` 已把 App Server 审批、Guardian warning 和 file-change patch 事件归一成 `executionProgress.approvals / warnings / fileChanges`；服务端和 Android 原生进度卡已支持展示，且测试覆盖了密钥和 diff 不外泄
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `thread/status/changed`、`thread/realtime/started|transcript|outputAudio|itemAdded|error|closed` 归一成 `executionProgress.threadStatus / realtime`；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 SDP、音频原始数据和 raw item 不外泄
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `model/rerouted`、`thread/tokenUsage/updated`、`mcpServer/startupStatus/updated`、`remoteControl/status/changed` 归一成 `executionProgress.modelRoute / tokenUsage / mcpServers / remoteControl`；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 installationId 和密钥不外泄
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `thread/goal/updated|cleared`、`thread/settings/updated`、`thread/compacted` 归一成 `executionProgress.threadGoal / threadSettings / compaction`；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 cwd、turnId、内部 prompt 不外泄
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `account/updated`、`account/rateLimits/updated`、`model/verification`、`warning`、`configWarning`、`deprecationNotice` 归一成 `executionProgress.accountStatus / modelVerification / warnings`；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖配置路径、turnId 和密钥不外泄
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `ThreadItem.collabToolCall` 和 `ThreadItem.contextCompaction` 归一成 `executionProgress.threadCollaboration / compaction`；新版 `receiverThreadIds / agentsStates` 只归一为目标数量与 agent 状态集合；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖源/目标线程 ID、内部 prompt、agent 私有消息、turnId 和密钥不外泄
- `local-agent/codex-app-server-runner.mjs` 已新增 `threadCollaborationSummary` 能力摘要：当前 Boss Broker 和运行时 `collabToolCall` handler 可用，但本机 0.136.0-alpha.2 schema 没有声明 `ThreadItem.collabToolCall`，所以产品口径固定为“Boss 受控线程协作”，不承诺 Codex 原生线程私聊。
- `local-agent/codex-app-server-runner.mjs` 已新增 `protocolDriftSummary` 协议漂移摘要：当前会输出 `driftLevel / failedProbeCount / runtimeFailureMethods / docFollowupItems / fallbackStrategy`，设备详情页展示“协议漂移”卡片；测试覆盖兼容态、文档跟进项和 Boss Broker 兜底文案。
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `mcpToolCall`、`dynamicToolCall`、`webSearch`、`imageView`、`enteredReviewMode`、`exitedReviewMode`、`commandExecution` 归一成 `executionProgress.toolActivities`；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 tool arguments/result、URL token、命令正文/输出、本地路径和密钥不外泄
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `ThreadItem.plan` 与 `ThreadItem.reasoning.summary` 归一成 `executionProgress.steps / reasoningSummary`；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 raw reasoning content、reasoning item id 和密钥不外泄
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `ThreadItem.imageGeneration` 归一成 `executionProgress.toolActivities / artifacts`；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 revisedPrompt、result、item id、本地绝对路径和密钥不外泄
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `hook/started|completed` 归一成 `executionProgress.toolActivities`；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 hook id、sourcePath、statusMessage、entries、本地绝对路径和密钥不外泄
- `local-agent/codex-app-server-runner.mjs` 已把 App Server `windowsSandbox/setupCompleted` 归一成 `executionProgress.windowsSandbox`；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 setup error 中的 token、本地 Windows 路径和 sourcePath 不外泄
- 新增实时进度入口 `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
- 新增 Boss APP 用户消息镜像到 Codex App Server 线程历史：普通 `conversation_reply` 任务已复用 `mirrorBossUserMessageToCodexDesktop` 标记；设备端通过 App Server runner 执行 `thread/resume -> thread/inject_items(user message) -> turn/start`，让 APP 发起的用户输入进入 Codex Desktop 同一线程的模型可见历史。执行结果只返回 `threadHistorySync` 安全摘要，不回写消息 ID、用户原文、内部 prompt 或 App Server 原始 item。
- 新增活跃 turn 干预：任务携带 `targetCodexTurnId` / `targetTurnId` 时，App Server runner 会调用 `turn/steer`，并把 `turnControl=steer`、`turnId` 写回执行结果；没有活跃 turn id 时仍使用 `turn/start`
- 新增活跃 turn 中断：用户或管理员通过任务取消接口把任务转为 `canceled` 后，设备端会轮询 `GET /api/v1/master-agent/tasks/[taskId]/control-state`；如果当前任务已经启动 App Server turn，runner 会在同一个 JSON-RPC 连接上调用 `turn/interrupt`，并把返回的 `interrupted` 处理成干净取消，不再把用户主动取消误判成 runtime failure
- 新增受控线程回滚：服务端入口 `POST /api/v1/projects/[projectId]/thread-rollback` 会创建 `intentCategory=thread_rollback` 任务；设备端通过 App Server 调用 `thread/rollback`，只返回“已回滚最近 N 轮”的用户可见摘要，不启动新 turn，不保存 App Server 返回的 thread/turn/items。该能力只回滚 Codex 线程历史，不自动还原本地文件变更，后续如需文件级撤回必须另走 Git / 文件快照恢复链路。
- 新增受控线程压缩：服务端入口 `POST /api/v1/projects/[projectId]/thread-compact` 会创建 `intentCategory=thread_compact` 任务；设备端通过 App Server 调用 `thread/compact/start`，只返回“已发起上下文压缩”的用户可见摘要，不启动普通 turn，不保存 contextCompaction item 的原始字段。该能力只压缩 Codex 线程上下文，不代表代码修改、文件恢复或版本发布完成。
- 新增受控线程归档 / 恢复：服务端入口 `POST /api/v1/projects/[projectId]/thread-archive` 会创建 `intentCategory=thread_archive|thread_unarchive` 任务；设备端通过 App Server 直接调用 `thread/archive` 或 `thread/unarchive`，不先 resume 已归档线程，不启动普通 turn，不保存 App Server 返回的 thread 原始字段。该能力只改变 Codex 线程生命周期状态，不代表代码修改、文件恢复或版本发布完成。
- 新增受控线程改名：服务端入口复用 `POST /api/v1/projects/[projectId]/rename` 的 `mode=thread` 分支；本地 Boss 会话标题先更新，再创建 `intentCategory=thread_rename` 任务；设备端通过 App Server 直接调用 `thread/name/set`，不先 resume 线程，不启动普通 turn，不保存 App Server 返回的 thread 原始字段。该能力只同步 Codex 线程显示名，不代表代码修改、文件恢复或版本发布完成。
- 新增受控线程目标同步：服务端入口复用 `POST /api/v1/projects/[projectId]/goals`；本地 Boss 项目目标先更新，再对已绑定 `codexThreadRef` 的单线程创建 `intentCategory=thread_goal_sync` 任务；设备端通过 App Server 直接调用 `thread/goal/set`，不启动普通 turn，不保存 App Server 原始 goal payload。该能力只同步 Codex 线程目标和状态，不代表代码修改、文件恢复或版本发布完成。
- 新增受控线程 Git 元数据同步：服务端入口 `POST /api/v1/projects/[projectId]/thread-metadata` 会创建 `intentCategory=thread_metadata_sync` 任务；设备端通过 App Server 直接调用 `thread/metadata/update`，不启动普通 turn，不保存 App Server 原始 thread payload。当前只允许 patch `gitInfo.sha / branch / originUrl`，用于同步分支、提交和远端仓库信息。
- 新增受控线程分叉：服务端入口 `POST /api/v1/projects/[projectId]/thread-fork` 会创建 `intentCategory=thread_fork` 任务；设备端通过 App Server 直接调用 `thread/fork`，不启动普通 turn，不保存 App Server 返回的 path、cwd、turns 或 instructionSources。当前只返回新线程 id/name/preview/status/ephemeral，且不允许远程覆盖 model、sandbox、instructions 或 config。
- `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 判定
- 新增 App Server capability discovery：`local-agent` 会把可用模型、默认/快速/深度模型建议、provider 能力、Skill、Plugin、App 摘要写入设备 heartbeat；Web 设备详情已显示 App Server、模型和扩展数量，为后续 APP/后台模型配置页提供真实数据来源
- 新增 App Server 共享 Skill 根下发：配置 `codexAppServerSkillExtraRoots` 或 `BOSS_CODEX_APP_SERVER_SKILL_EXTRA_ROOTS` 后，runner 会在 discovery 阶段调用 `skills/extraRoots/set`，再刷新 `skills/list`；设备详情页展示“共享 Skill 根：N 个 · 已下发/下发失败”，metadata 只保存数量、basename 和状态，不保存绝对路径
- 新增 App Server Hook 治理 discovery：runner 会调用 `hooks/list` 并写入 `hookSummary`，设备详情页展示“Hook：N 个 · 启用 N 个 · 警告 N 个”；metadata 只保存计数、事件名和 handler 类型，不保存 hook key、command、sourcePath、statusMessage、hash、error message 或本地路径
- 新增 App Server 线程操作能力摘要：runner 写入 `threadActionSummary`，设备详情页展示“线程操作：N 项”；该字段只来自安全 catalog 和协议快照，不在 heartbeat 中调用任何会改变线程状态的 API，后续真正执行这些动作必须走用户显式指令、RBAC、审批和审计链路。
- 新增 App Server 线程协作口径摘要：runner 写入 `threadCollaborationSummary`，设备详情页展示“线程协作：Boss Broker 可用/不可用 · 协作事件可处理/不可处理 · N 种模式 · 原生私聊/非原生私聊”；该字段只来自当前 runner 能力、heartbeat discovery 和协议快照，不在 heartbeat 中向线程注入内容。
- 新增 App Server 协议漂移摘要：runner 写入 `protocolDriftSummary`，设备详情页展示“协议漂移：兼容/告警 · 失败探针 N 个 · 文档跟进 N 项 · Boss Broker 兜底”；该字段只保留 method 级失败摘要和跟进项，不保存原始错误、线程 ID 或用户内容。
- 新增 App Server 插件治理能力摘要：runner 写入 `pluginGovernanceSummary`，设备详情页展示“插件治理：N 项”；该字段只来自安全 catalog 和协议快照，不在 heartbeat 中调用插件安装、卸载或共享 API，后续真正执行这些动作必须走用户显式指令、RBAC、审批和审计链路。
- 新增 App Server 账号与配置治理能力摘要：runner 写入 `accountGovernanceSummary / configGovernanceSummary`，设备详情页展示“账号治理 / 配置治理”；这些字段只来自安全 catalog 和协议快照，不在 heartbeat 中调用账号登录、退出、令牌刷新、配置写入、MCP 重载或 Skill config 写入 API，后续真正执行这些动作必须走用户显式指令、RBAC、审批和审计链路。
- 新增 App Server 文件系统与命令会话治理能力摘要：runner 写入 `fileSystemGovernanceSummary / commandSessionSummary`，设备详情页展示“文件治理 / 命令会话”；这些字段只来自安全 catalog 和协议快照，不在 heartbeat 中调用文件读写、删除、监听、stdin 写入、PTY resize 或 terminate API，后续真正执行这些动作必须走用户显式指令、RBAC、审批、租约和审计链路。
- 新增 App Server 外部 Agent 迁移、Marketplace 和实验特性治理能力摘要：runner 写入 `externalAgentGovernanceSummary / marketplaceGovernanceSummary / experimentalFeatureGovernanceSummary`，设备详情页展示“迁移治理 / 市场治理 / 实验特性治理”；这些字段只来自安全 catalog 和协议快照，不在 heartbeat 中调用 external-agent 导入、marketplace 写操作或实验特性启用 API，后续真正执行这些动作必须走用户显式指令、RBAC、审批和审计链路。
- 新增 App Server 审查、Windows 沙箱和文件搜索事件能力摘要：runner 写入 `reviewGovernanceSummary / windowsSandboxGovernanceSummary / fuzzyFileSearchSummary`，设备详情页展示“审查治理 / Windows 沙箱 / 文件搜索事件”；这些字段只来自安全 catalog 和协议快照，不在 heartbeat 中调用审查启动、沙箱设置或文件搜索动作，后续真正执行这些动作必须走用户显式指令、RBAC、审批和审计链路。
- 新增 App Server MCP、用户交互和 Guardian 治理能力摘要：runner 写入 `mcpGovernanceSummary / userInteractionGovernanceSummary / guardianGovernanceSummary`，设备详情页展示“MCP 治理 / 用户交互 / Guardian 治理”；这些字段只来自安全 catalog 和协议快照，不在 heartbeat 中调用 MCP OAuth、MCP tool/resource、用户输入请求或 Guardian denied action 放行动作，后续真正执行这些动作必须走用户显式指令、RBAC、审批和审计链路。
- 新增 App Server 运行事件、扩展事件和线程生命周期事件能力摘要：runner 写入 `runtimeEventSummary / extensionEventSummary / threadLifecycleEventSummary`，设备详情页展示“运行事件 / 扩展事件 / 线程生命周期”；这些字段只来自安全 catalog 和协议快照，不在 heartbeat 中主动触发 process、raw response、Skill、Plugin 或线程生命周期事件，后续真正执行这些动作必须走用户显式指令、RBAC、审批和审计链路。
- 新增 App Server 流式增量事件能力摘要：runner 写入 `streamDeltaEventSummary`，设备详情页展示“流式增量”；该字段只来自安全 catalog 和协议快照，用于确认 agent delta、plan delta、reasoning delta、MCP progress、command output、terminal interaction 和 file output 已进入可治理目录，不保存原始增量文本、命令输出、推理正文或文件输出。

后续建议按两步继续：

1. 把当前 runner 提升为完整 `CodexAppServerBackendAdapter`：继续补 MCP tool / account / rate-limit / config 事件映射，并把 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 或后台。