App Server

codex-rs/app-server 是桌面 app、IDE 或其他宿主与 core runtime 之间的 JSON-RPC 服务层。它不是简单把请求透传到 ThreadManager，而是承担连接初始化、能力协商、请求串行化、外部认证刷新、文件/搜索/环境辅助服务、线程订阅和事件转发。

MessageProcessor

codex-rs/app-server/src/message_processor.rs 的 MessageProcessor 聚合了一组 request processor：

Processor 职责
InitializeRequestProcessor 建立连接会话，记录 client name/version、experimental API、表单 elicitation 能力
ThreadRequestProcessor thread start/read/list/resume/delete/archive/search
TurnRequestProcessor turn start/steer/interrupt、thread settings update、realtime、review
McpRequestProcessor MCP server refresh、elicitation、资源相关请求
PluginRequestProcessor、MarketplaceRequestProcessor 插件启用、安装、marketplace 管理
ConfigRequestProcessor 配置读取、写入和错误上报
EnvironmentRequestProcessor executor environment 管理
FsRequestProcessor、GitRequestProcessor、SearchRequestProcessor 文件、Git、搜索辅助能力
AccountRequestProcessor 登录、账号、token refresh

这是一种“薄协议、厚 processor”的架构：JSON-RPC 只负责消息形态，具体业务分发在 processor 中维护。

连接初始化

ConnectionSessionState 使用 OnceLock 保存初始化后的连接能力：

  • experimental API 是否开启。
  • client opt-out 的 notification methods。
  • app server client name/version。
  • 是否需要 attestation。
  • 是否支持 OpenAI form elicitation。

这样后续 processor 可以根据连接能力决定是否走新协议、是否发通知、是否允许某些交互。

请求串行化

MessageProcessor 持有 RequestSerializationQueues。这类队列解决 app-server 中常见的竞态：同一 thread 的 start/steer/interrupt/settings update 不能随意并发，否则会破坏 session state 或 UI 订阅顺序。

外部认证刷新

ExternalAuthRefreshBridge 把 core/login 层的 token refresh 请求转成 app-server 发给客户端的 server request：

  1. core 发现 ChatGPT token 需要刷新。
  2. app-server 发送 ChatgptAuthTokensRefresh。
  3. 等待客户端返回新 token。
  4. 超时或 JSON-RPC error 会转成 IO error。

这个设计让 core 不需要知道桌面 app 如何拿到新 token。

Thread 与 Turn Processor

ThreadRequestProcessor 处理 thread list/read/resume 等生命周期。它在 resume 时会比较请求 overrides 和当前 live thread snapshot，避免用户以为运行中的线程设置被热替换。

TurnRequestProcessor 处理：

  • turn_start
  • turn_steer
  • turn_interrupt
  • thread_settings_update
  • realtime start/append/stop
  • review start
  • thread_inject_items

其中 turn_start 会构造 CodexThreadSettingsOverrides，并将 app-server 协议中的 sandbox、approval、model、service tier、collaboration mode、multi-agent mode、personality 等映射回 core 类型。

Dynamic Tools 校验

app-server 支持客户端传入 dynamic tool spec，但 thread_processor.rs 会校验：

  • tool name 非空。
  • name/namespace 只能包含 ASCII 字母数字、_、-。
  • name、namespace、namespace description 有长度上限。
  • 不能占用 Responses API 保留 namespace，例如 web、python、image_gen、tool_search 等。

这避免宿主传入的 dynamic tools 覆盖核心工具或破坏 Responses API 工具命名规则。

可学习的设计

App Server 层的重点是把“客户端连接”从“agent runtime”中拆开：

  • core 只关心 thread、turn、tools。
  • app-server 关心 JSON-RPC、连接能力、认证刷新、请求串行化。
  • processor 让每类业务有独立边界，减少一个巨大 dispatcher 的复杂度。