这一阶段像程序开机前的“配电箱”，专门把各种配置收齐、查错、排好优先级。config.toml、钩子、MCP、profile、快捷键、运行环境、代理角色等文件先规定每种配置该怎么写。云端、管理员、用户、项目、会话线程和命令行临时改动再被读成一层层配置。合并器按规则让后来的覆盖前面的，状态栈算出最终生效值；严格检查和诊断负责指出写错的文件行列；指纹和锁文件则记录来源和快照，防止配置悄悄变了。

这一阶段像开工前的“规矩汇总台”，属于幕后支撑。它先读 requirements.toml、企业下发配置等来源，把每一层拆清楚：普通配置普通合，读文件禁令、执行规则、hook 这些安全项按专门办法追加或校验，不能被后来的配置冲掉。最后 stack 把多层叠成最终要求；执行策略部分把“哪些命令能跑”翻成机器能检查的规则，并能安全追加白名单；网络代理配置会随文件变化重载；hook 规则则保护用户自己的启用和信任选择。

这一阶段像系统的“设置柜台”，不是主循环干活儿，而是在幕后让前端和后台都能读、改、保存配置。客户端来的配置请求先到处理器，由它分发给配置读写服务；服务负责安全查看和修改设置，并说明哪些设置被更高规则盖住。修改 config.toml 时，编辑工具和 TOML 小助手会尽量保留原来的注释和排版。加载配置出错时，错误转换器把原因翻成前端看得懂的话。它还会导入外部工具的配置，迁移老用户的个性设置，并让后台服务记住自己的本地开关。

这一阶段是终端界面的“交通枢纽”，属于主干活儿的循环。用户按键、后台消息、审批请求都会先变成统一消息或命令，再由总分诊台分发。输入模块管全局快捷键；后台事件和请求模块把服务器来的通知、待审批事项放到正确位置；线程路由负责多条聊天线切换和回放；未完成交互只重放还在等人的提示。慢任务丢到后台跑，重画请求也被合并，保证界面不乱、不假死。

这一阶段是终端聊天界面最底下那块“操作台”，属于用户干活时一直陪着的主入口。输入框负责打字、粘贴、换行、光标移动、历史找回和图片附件；草稿、提示栏、弹窗状态把临时信息分开放，避免互相搅乱。斜杠命令会被拆开、提示、补全，@ 提及会搜索文件、插件和技能并弹出候选。各种列表、设置、反馈、确认窗口共用底部面板规则，像抽屉一样弹出、接键盘、办完再收起。

这一阶段是终端聊天界面的“前台大厅”，属于系统主干活儿的循环。chatwidget 主控台接住后台消息和用户按键；interaction 判断按键该交给输入框、弹窗还是任务；input_submission、input_flow、input_queue、input_restore 负责发送、排队和找回未发内容。slash_dispatch 分发 / 命令。protocol 把后台通知变成聊天记录、进度、报错。各种菜单和弹窗处理模型、用量、审查、目标、技能、连接器；rendering 最后把这些拼成完整画面。

这一阶段像主聊天旁边的一排小工具，用户需要临时操作时才接手，不是核心干活循环。cloud-tasks 三件套负责记住任务、新建任务并画出任务界面。回溯和全屏查看器让人翻旧记录、退回重改。keymap 几个文件提供改快捷键、查按键、保存配置。多智能体导航管切换和状态展示。pets 负责选宠物、预览、加载和出错兜底。剪贴板、主题选择、外部配置导入和平台小检查，则把零散入口收拾成顺手的界面流程。

这一阶段是系统的“安全门卫”，主要在工具真正执行命令、改文件、联网或放宽沙箱限制前做决定：能直接放行、必须拒绝，还是先问用户。新版 execpolicy 负责读入人写的策略、整理成规则，并按命令或网络请求逐条匹配。core 里的几个文件把这些判断接到实际工具上：命令看 exec_policy，改补丁看 safety，联网请求由 network_policy_decision 翻译成用户能懂的审批。sandboxing 则统一决定要不要审批、要不要关进“隔离间”运行。legacy 部分是旧版同类门卫，继续解析旧策略、检查程序名和参数，保证老规则还能用。

这一段像系统动手前的“安全检查岗”，属于主流程里的把关环节。mod 是总开关，判断哪些自动批准要先送审，并在连续被拒时拉保险丝。approval_request 把命令、改文件、联网、提权等动作写成统一审批单。prompt 把上下文整理给 Guardian 模型看，再读回结论。review 和 review_session 负责拉起或复用只读审查线程，按保守规则给出批准、拒绝、超时或中止。session/review 则复制必要环境并收紧权限，让这次复查不越界。

这一阶段像系统里的“门卫和传话员”，贯穿启动、运行到收尾。Hook 就是在关键时刻自动跑的小脚本。注册表和运行时先找到配置好的脚本，调度器决定哪个事件该叫谁。命令运行器负责真正执行，解析器读懂脚本吐出的 JSON，输出太长就先存临时文件。各事件处理器分别管会话开始、用户发话、工具前后、权限申请、上下文压缩和停止时的检查，最后汇总成放行、拦住、停止或补充上下文。

这一阶段像系统的“前台加保安”，发生在 Codex 正在干活儿时。模型想看更多文件、用更多环境权限，会走 request_permissions 统一登记和送审；想问真人问题，会走 request_user_input，把问题传到会话层再拿回答案。MCP 这边如果需要用户补充信息，elicitation 会判断能不能直接处理，或转给前端。执行命令、修改代码前，也分别由 exec_approval 和 patch_approval 去问用户准不准，避免机器偷偷做高风险动作。

这一阶段像“安全闸门”和“前台窗口”，主要发生在系统干活过程中。后台总调度员先判断工具能不能直接跑，要不要沙箱、审批或升级重试；MCP 模板把外部工具的风险写成用户看得懂的问题。终端界面这边负责把请求排队、弹窗、显示待处理项和最近被拦下的操作，还能收集用户回答、切换权限模式、提示 Windows 沙箱问题。hooks 联络员则帮界面向后台查询和信任检查规则。整体配合起来，就是让危险动作先说明白、再等人点头。

这一阶段是系统运行时的“门禁和值班保安”，主程序要联网、沙箱命令要读写文件时，都在这里被检查。network-proxy 的入口先把各模块摆好；state 把用户配置和管理员硬规则合成可执行状态；network_approval 负责该问人时只问一次；network_policy 和 runtime 判断请求放行还是拦下，并记日志、热更新规则。Windows 这边则给沙箱加临时可读目录、同步禁止读取规则、保护工作区特殊目录，再用 WFP 这道系统级网络关卡拦住不该去的地址。

这一阶段是系统真正“把命令跑起来”的执行通道，位于主干活儿的中段。app-server 先接住客户端请求，检查启动、输入、改窗口、终止等操作，再交给底层进程跑，并把输出送回去。TUI 的小工具把本地和远端文件、后台命令包成同一套用法。core 这边像调度室：接收用户或模型的 shell、unified-exec 请求，补好目录、环境、超时、审批、沙箱和联网规则，再调用真正的执行器；特殊 zsh 路线不合适时会退回普通执行。整体目标是能跑命令，但不让它乱跑。

这一层是统一执行命令的“发动机舱”，属于幕后支撑。上面只说“启动命令、继续输入、拿输出、停掉它”，这里负责真把进程管住。mod 和错误文件定规矩、统一说法；process 和 manager 把本机进程、远端 exec-server 进程包成同一种东西，并登记、读写、清理。spawn 负责安全启动外部程序。exec-server 里的本地和远端进程负责实际跑命令、缓存事件。pty、pipe 和 Windows 后端则像不同插头，让普通命令和交互式终端在各系统上都能接通。

这一阶段发生在系统干活时，专门管“让模型改文件”这件事，像一套带安检的维修通道。apply_patch_spec 先把补丁格式说明白；前台 handler 和 core/apply_patch 检查格式、权限，必要时请用户确认，再交给运行环境。runtime 负责审批后在沙箱里动手。parser 把补丁拆成改动清单，streaming_parser 边收边拆；invocation 先认出调用并预查路径和文件；lib 真正落盘；git-utils 借 git 试跑或应用，并整理冲突结果。

这一阶段是在真正运行外部命令前，先决定“要不要关进沙箱、怎么关”。入口和管家负责统一不同系统的做法，整理权限、目录、网络和环境变量。Linux 上有两套栏杆：bubblewrap 像临时隔离房间，Landlock/seccomp 像门禁和断网开关；相关文件会检查工具是否可用、找项目自带版本，并把普通命令改写成沙箱启动命令。Unix 的提权部分则像值班员：命令想跳出限制时，客户端先问服务端，服务端按规则决定放行、升级权限或拒绝。

这一阶段是 exec-server 的“文件管家”，属于幕后支撑部分。它让执行任务读写文件时，不是随便碰硬盘，而是走统一通道。file_read 负责把大文件一段段读，并用编号管理。fs_helper 规定读、写、建目录、删除这些请求怎么说、怎么做。fs_sandbox 把操作关进沙盒这个隔离房间。sandboxed_file_system 戴着安全手套转交给助手。local_file_system 决定本机操作走直连还是沙盒。remote_file_system 则把同一套操作发到远端服务器执行。

这一层是 Windows 上“把外部命令关进小房间再启动”的幕后支撑。lib、unified_exec 和 TUI 帮手接住上层请求，决定开不开沙箱、走普通还是提权通道。setup、identity 和错误报告准备专用账号、目录、运行文件和失败记录。ACL、token、审计、防火墙像门锁和保安，限制文件和网络。最后 spawn、process、runner、管道、假终端和 stdio_bridge 开进程、接输入输出，并负责等待、超时或杀掉它。

这一阶段是把 MCP（让 Codex 接外部工具和资料的协议）真正接进系统，属于运行中一直在幕后支撑的部分。配置和插件先登记哪些服务器能用，连接管理器像总接线员一样启动它们、收集工具和资源。工具整理层负责改名、去重、决定哪些给模型看。会话层在模型调用时检查参数、上传文件、必要时问用户或处理登录过期。资源工具则负责列清单、读内容。扩展层最后把这些能力和事件统一送到应用服务器。

这一阶段像插件和连接器的“应用商店加仓库管理员”，属于系统运行时的幕后支撑，也给命令行和聊天界面提供入口。它先从插件市场、本地目录、Git 仓库或远端服务找货源，再读取 plugin.json 清单，检查路径和格式是否安全。加载器把技能、工具服务器、应用声明和钩子整理给主程序用。管理器负责安装、卸载、升级、缓存同步和分享。连接器策略会判断外部应用能不能用、是否要确认。最后，推荐工具和安装请求工具把可装内容展示出来，但真正安装前仍要让用户点头。

这一阶段像系统的“工具大厅”，主要在对话进行中默默支撑模型干活。开局先由排班表决定哪些工具能露面，哪些只后台用。动态工具和扩展工具负责把外部临时能力、插件能力接进来。code-mode 让模型能跑一小段代码并等待结果。网页搜索、图片生成、记忆、技能、目标等扩展各自提供具体本事。工具搜索、看图片、查剩余上下文这些小帮手，则像标签、放大镜和油表，帮助模型安全地找到、使用、控制这些工具。

这一阶段像应用服务器里的“前台导购和搜索台”，客户端来问有哪些应用、想快速找文件，都由这里接住。connectors 里的几个文件先把各路连接器名单整理干净：过滤掉不该露出的，合并重复的，补齐名字、图标、说明和插件信息。apps_processor 再把登录状态、工作区配置和插件列表串起来，返回用户真正能看到的应用。fuzzy_file_search 则负责文件模糊搜索，既能查一次，也能在用户边输入时边推送新结果。

这一阶段是幕后打地基的公共协议，不直接跑代码，而是先把“大家怎么说话”定好。lib.rs 像总入口，把常用东西摆到门口。description.rs 给工具写说明，并检查 exec 的特殊配置。response.rs 规定结果里文字、图片怎么装。runtime.rs 规定运行代码、拿输出的消息格式。session.rs 则定下会话从创建、执行、等待到停止的整套规矩，让本地或远程执行器都能按同一份合同配合。

这一阶段像系统对外说话的“统一话术本”，属于幕后支撑公共部分。lib.rs 是总入口，把各类能力集中摆好；common.rs 规定请求、回复、流式消息和参数的通用信封；error.rs 把各种失败统一包装，方便上层处理。实时 WebSocket 协议文件规定长连接里每句话的格式和版本解析。images.rs、search.rs 则分别给图片生成/编辑和搜索请求结果做标准表格。它们配合起来，保证程序和外部服务收发数据时不乱套。

这一阶段像给扩展和插件准备的“插座说明书”，属于幕后支撑，不直接干主流程活儿。扩展 API 先规定能借宿主做什么，比如创建子代理、发事件、往当前对话塞内容、保存自己的小数据。贡献者接口说明插件能在哪些时刻插手：线程、工具调用、对话回合、MCP 配置等。记忆库、用户指令、IDE 上下文也统一了数据样子。hooks 部分则规定钩子怎么声明、触发、返回结果，并加载命令格式模板，让外部脚本按同一套规矩安全接入。

这个阶段像后台的“说明书和表格库”，不直接干活，而是让模型、前端、后端和外部工具说同一种话。它规定工具调用时要带什么信息、接口里长什么样，再把执行结果翻译成系统能继续用的格式。提问用户、申请权限、更新计划、查剩余对话容量、跑命令、目标、技能、网页搜索、MCP 调用，都在这里有固定模板和字段名。这样各零件交接时不靠猜，少传错、少看错，也方便日志、审批和钩子稳定接上。

这一阶段像系统的“接线图”，不是亲自干活，而是规定各方怎么说话。exec-server 的连接入口把 WebSocket、认证连接、标准输入输出这些路统一包起来；进程编号用专门的小盒子，避免拿错。协议文件规定启动进程、读写文件、报错等消息长什么样；exec 事件规定运行过程怎么对外汇报。沙盒和提权部分则约好被拦截命令、环境变量、输入输出和退出结果怎么传，让普通进程、提权进程和外部客户端能安全配合。

这一阶段不是系统开机或干活的主循环，而是幕后用的“记账格式”。它规定追踪记录该怎么写，方便不同模块按同一套说法交换数据。session 文件像登记簿，说明一次运行和智能体线程是进行中、成功、失败还是被打断。runtime 文件像流水账模板，记录模型执行、工具调用、终端操作、压缩历史和多智能体通信。payload 文件像附件索引，大请求、大响应、大日志不塞进主记录，只留下外部文件地址。三者配合，把一次运行的过程轻量、清楚地保存下来。

这一阶段像全系统共用的“文字工具箱”，不是主流程，而是在后台帮各处把内容变得安全、短、好读。数字和耗时会改成 12,345、250ms 这类顺眼写法；JSON、标签、UUID、代码位置等字符串会被整理，中文表情也能转成安全写法。长文本、命令输出、对话历史和终端路径会保留头尾再剪短，防止塞爆屏幕或模型。命令行会隐藏环境变量真值，并安全生成 resume 命令；网页搜索动作会翻成人话；严格模板负责替换变量并抓出填错。

这个阶段是幕后工具箱，专管“文字还没收完就要先看懂”的情况。数据常一小块一小块来，utf8_stream先把字节安全拼成文字，line_buffer再按换行凑整行。stream_text定好边显示边抽取隐藏内容的规矩；inline_hidden_tag抓内联暗号，tagged_line_parser切出带标签的块。table_detect认 Markdown 表格，mention_codec保住提及背后的真实指向，citations整理记忆引用。lib.rs像柜台，把工具统一交给别处用。

这一阶段是终端界面的幕后排版工，不管业务，只保证文字画得稳。render 和 line_utils 管边距、空行、加前缀等基础小活；width 算正文还剩多宽。ansi-escape 处理颜色加粗，truncation 负责截短长行。Markdown 合并器保留原文位置，链接模块让可点击链接不扰乱排版。wrapping 和 live_wrap 按真实宽度换行，尽量不断网址；scrollable_diff 让长文本和 diff 能安全滚动。

这一阶段不是主流程干活儿，而是终端界面背后的“装配台”。底层文字能排好后，这里负责把它变得好看、好懂、好操作：颜色和样式保证不同背景下看得清，统一宽度和可渲染零件让文字、空白、横竖布局像积木一样拼起来。页脚、弹窗、选项卡、选择列表和滚动状态负责提示用户按什么、当前选哪项。状态、目标、技能、迁移清单、连接信息和历史记录则把机器数据整理成人能读的短句，并避免警告刷屏或敏感地址泄露。

这一阶段是给终端界面“加动态”的幕后工具箱，不是主流程本身，而是让等待、检查、引导这些时刻更好看也更稳。motion 像总开关，统一决定能不能用闪烁、发光等动效，用户不想看动画时就换成安静可读的显示。shimmer 负责文字扫光，让“正在运行”更醒目。ascii_animation 负责字符小动画该播哪一帧，frames 则把动画素材提前装进程序里。doctor 的 progress 只在合适时临时显示检查进度，避免污染最终报告。

这一阶段不是系统开机或干活的主循环，而是幕后“验收口令”的测试区。它专门检查服务端和客户端在网上传的话是不是一直长一个样。common_tests 看 JSON-RPC 返回里哪些放正文、哪些另发事件；remote_control_tests 查远程控制参数和结果变成 JSON 后字段对不对；v2/tests 覆盖大量 v2 请求、响应、通知，防止兼容性被改坏；schema_fixtures 则把当前代码生成的协议说明书和仓库里存的文件对照，提醒别忘了更新。

这一阶段是幕后质检，不是正式对用户干活。它给后台服务、通信通道和测试客户端做体检：pid、版本、更新测试防止服务状态认错、该重启不重启；socket 和消息测试确认本机连接安全、握手收发正常、慢客户端不拖全局；远程控制用假服务器查配对、撤销和重试。测试客户端能启动服务、发消息、模拟审批，再配合假接口和埋点工具，核对插件安装、启用、卸载记录是否完整。

这一阶段不是用户平时会看到的主流程，而是幕后“质检车间”。一部分测试直接检查 app-server 的关键小零件：配置迁移会不会搬丢东西，config.toml 读写会不会乱改，启动参数能不能生效，追踪链路能不能接上，远程控制、线程处理、会话摘要在出错和边角情况里是否靠谱。另一部分是集成测试的公用道具：假登录、假配置、假模型服务器、假分析服务器、假回复、假历史会话和假客户端，让测试像真跑服务一样检查，又不用碰真实外部服务。最后几个入口文件把这些测试登记成套件，方便一次跑全。

这一阶段像给 app-server 做一次上线前总彩排，不写新功能，而是把客户端从连上来、登录、读配置，到真正对话、调工具、保存记录都跑一遍。认证和配置先检查门禁和开机设置；传输和协议确认 WebSocket、退出、握手这些“通道规矩”靠谱；插件、MCP 和工具测试外接能力能装、能用、能收场；thread、turn 等测试则盯住会话档案和每轮对话的状态，确保前端看到的、数据库存的、磁盘写的都一致。

这一阶段不是系统真正“干活”的代码，而是给核心运行时做体检的测试区，属于幕后守门员。它从一次会话怎么启动、恢复、压缩历史，到模型输出怎么变成消息，再到代理线程、子任务、插件改写、图片和实时对话交接，都逐项检查。另一大块盯安全：命令能不能跑、文件能不能改、联网和工具调用要不要审批，Guardian 和执行策略是否拦得住。还有状态、Git、Shell、配置迁移等杂项检查，确保前台聊天顺畅，后台边界不乱。

这一阶段主要是给“工具调用”和“统一执行命令”做验收，属于幕后质检，不是开机或关机。它像一套安全检查台：先校对各类工具的说明书，保证模型按正确格式调用；再检查路由、注册表、追踪记录，确保工具不被派错、漏记；同时盯住补丁、命令、联网、沙箱和审批，防止越权。最后用 unified-exec 的测试模拟本地和远程跑命令、超时、截断输出、清理进程，保证真正干活时稳住。

这一阶段不是系统真正“干活”的功能，而是给 core 做端到端测试的后台脚手架。all.rs 和 suite/mod.rs 像总开关，把分散测试接起来并做好开场伪装。common 里的工具箱负责临时目录、环境判断、进程等待、可信 hooks、追踪检查、上下文快照等杂活。另一些文件搭假服务器、假 Codex 会话和干净的 codex-exec，让测试不用连真实服务、不碰用户环境，也能稳定复现各种流程。

这一阶段是 Core 的“全流程体检”，主要在幕后验证一次对话从发起、请求模型、执行工具到保存状态都不会掉链子。传输套件查网络通道和模型服务能不能稳定收发；历史套件管聊天记忆、压缩和恢复；请求套件负责把提示词和模型选对；协作套件检查子助手和远程环境别乱跑；审批、权限和 hooks 像门卫，拦住危险动作；工具套件则验 shell、插件、MCP、图片等能力能用且不越权。整体就是确保用户看到的运行过程顺、准、安全。

这一阶段是在给 apply-patch 这个独立命令行小工具做“上机验收”，属于幕后保证质量的测试部分。all.rs 和 mod.rs 像点名册，把真正的测试都登记进来。cli.rs 检查用户把补丁写在命令里，或从标准输入喂进去时，能不能正确改文件。tool.rs 像功能清单，逐项验证新增、修改、移动、删除和报错提示。scenarios.rs 则按真实案例跑完整流程，只看最后文件夹是不是变成该有的样子。

这一阶段像是给 codex 命令行入口做总验收，属于系统跑起来后面向用户的外壳检查。它会实际敲各种命令，看反应对不对：app-server、exec-server 要能拦住写错的配置；delete、update、debug 命令不能走错流程；features 检查功能开关和配置提示；plugin 和 marketplace 测插件安装源的增删升级；MCP 命令要正确读写服务器配置；最后还有少量真人真机测试，确认真连服务时也能跑通。

这一阶段不是程序正式干活，而是给 codex-exec 这个命令行工具做“出厂检查”。它从用户最外层能碰到的地方下手：先测终端参数会不会读错，尤其是 resume、目录、配置和提示词；再测服务端事件能不能正确翻成人看的文字、JSON 或 JSONL；还会检查会话能否保存和恢复，标准输入、AGENTS.md、输出格式要求有没有带上；最后盯住认证头、审批策略、MCP 启动失败、hooks、服务器报错退出码，以及打补丁改文件流程，确保这些零件合在一起时，用户看到的行为稳定可靠。

这一阶段不是系统正式干活儿，而是给“能不能执行命令”的安全门做体检。当前测试会直接跑 execpolicy check，看它是否用 JSON 正确回答放行、提醒或禁止，也检查网络规则。旧版测试像一套老题库：good、bad 先查默认规则的大方向，cp、ls、pwd、head、sed 等再逐个盯常见命令的参数细节。all 和 mod 负责把这些题目串起来一起跑，防止新旧策略被改坏。

这一阶段不是程序给用户干活的主流程，而是开发者用来“验收登录系统”的试车场。all.rs 和 mod.rs 像总开关，把各项测试集中跑起来。令牌、个人令牌、Bedrock Key、存储和通用认证测试，检查凭证能不能认对、存好、删干净。命令行、设备码、浏览器登录服务器测试，模拟真实登录。刷新和登出测试则盯住过期续签和退出清理，防止账号状态留下隐患。

这一阶段是给 codex MCP server 这个可执行程序做端到端体检，属于幕后保证质量的测试部分。all.rs 和 mod.rs 像总开关，把整套测试串起来。common/lib.rs 提供公共工具箱；mcp_process.rs 真正启动服务器子进程，用 JSON-RPC 这种“按格式传纸条”的方式对话；mock_model_server.rs 和 responses.rs 假扮外部 AI，并吐出预设流式回复。最后 codex_tool.rs 检查危险命令、代码补丁和用户指令传递是否都按规矩走。

这一阶段不是系统真正干活的主流程，而是幕后“质检台”，专门检查分析埋点和遥测数据靠不靠谱。入口和目录文件负责把测试接进来；harness 像假监控台，方便造指标、取结果、核对内容。各类 otel 测试检查名字标签是否合法、耗时和计数是否写对、快照和导出是否正常、敏感内容有没有走错通道。analytics、server、core、state 的测试则盯住事件收集、开关行为、任务指标、日志过滤，防止数据丢、错、脏。

这一阶段主要是在幕后做“体检”，不是用户真正干活的主循环。它反复检查配置这条链路：本地、系统、企业云端和项目配置怎么读取、排序、合并，写错时能不能报清楚；再检查权限、网络、沙箱、hooks 小脚本、功能开关和提示文字有没有按安全规则生效。还有一批测试专门造假环境、假云端、假文件，像试车场一样模拟升级、缓存损坏、路径差异和额度不足，防止改代码时把用户设置或安全边界弄坏。

这一阶段不是系统开机或干活的主流程，而是一大块“质检台”。它用假目录、假市场、假服务器和临时仓库，反复检查插件能不能安全发现、安装、加载、分享和推荐；扩展接口能不能按顺序接入；技能会不会被正确找到、隐藏、点名调用；MCP 这种外部工具服务器能不能按配置连接、授权和过滤；最后还核对各种工具说明转换成接口格式时不丢字段、不乱改。它们合在一起，防止外接能力这条链路被改坏。

这一阶段像后台质检车间，不直接给用户干活，而是反复检查“和外部服务说话”这套底座稳不稳。模型配置和缓存测试管模型名单、默认值、登录后刷新；API、登录、证书和代理测试管请求地址、身份、重试和安全连接；协议、提示词、工具测试管错误说明、文字编码、模板和参数别变形；WebSocket、HTTP、Unix socket 等测试管消息能顺利收发。假客户端和假服务器则像演练道具，让这些检查不用真连云端也能跑。

这一阶段主要是幕后“质检”和测试工具，不是用户直接看到的主流程。它像给系统做体检：先用假事件搭出现场，检查 rollout 追踪能不能把模型回复、工具调用、终端、子代理和对话历史整理清楚；再测记忆功能能不能启动、写盘、引用、清理资源；还会检查状态数据库、消息历史、线程存储、外部代理账本和会话记录文件。重点是保证断电、文件坏掉、压缩、改名、旧格式等麻烦情况里，记录不丢、不串、不乱删。

这一阶段不是程序开机、干活或关机的主流程，而是在幕后给公共小工具做“体检”。它用自动测试反复检查两类容易出错的基础能力：一类看路径和 file: URI 能不能互相转对，覆盖 Windows、Unix、特殊字符、坏输入等坑；另一类看给 API 用的路径字符串会不会被误解。还有一组测试专盯长输出截断，确保文字、emoji、图片、加密内容混在一起时，截得安全、可读，也会正确提示被截短。

This stage is the behind-the-scenes configuration workshop. It runs during startup and whenever Codex needs to rebuild its settings. First, schema files define what valid settings look like: config_toml, profile_toml, hook_config, mcp_types, tui_keymap, environment_toml, agent_roles, and schema cover normal settings, reusable profiles, hooks, MCP servers, keyboard shortcuts, execution environments, agent roles, and tests around those shapes. Next, strict_config and diagnostics check files carefully and explain mistakes with exact line and column locations.

The loading side gathers settings from many places. loader/mod is the main coordinator. layer_io and macos read administrator-managed settings. cloud_config_bundle, cloud_config_layers, and cloud validation turn cloud-delivered policy into ordinary layers. thread_config adds per-session settings, and overrides converts command-line flags into the same TOML-like shape.

Finally, state, merge, and fingerprint stack all layers in priority order, normalize names, remember where values came from, and detect changes. config_lock can save and later compare the exact resolved configuration, making runs repeatable.

This stage is behind-the-scenes setup work. Before Codex starts running commands, it reads requirements.toml and other managed sources, then builds one clear rule set for what is allowed. config_requirements defines these high-level limits and keeps track of where each setting came from, so errors can point to the right source. requirements_layers/mod is the entry point for this combining system. layer cleans one raw requirements layer and separates normal settings from special ones, like execution policy, hooks, permissions, and sandbox rules. stack then assembles all layers into the final result.

Some fields need safer merging than simple “last one wins.” permissions keeps every denied read path from every layer. hooks combines hook event lists while preventing unsafe hook directory conflicts. rules preserves rule priority, keeping higher-priority rules first.

Execution policy is the command safety rulebook. requirements_exec_policy parses and validates it from requirements.toml. amend safely adds new allow or deny lines when a user approves something. network_proxy_loader turns config and policy into live network proxy settings and reloads them when files change. hooks/config_rules decides which saved hook settings are trusted enough to use.

This stage is the system’s configuration “service desk.” It sits behind the main app and daemon, letting clients read settings, change them safely, import old settings, and get understandable errors when configuration loading fails. The app server request processor is the front desk: it accepts configuration requests, reports policy rules, applies changes, and refreshes running work so new settings take effect. The service layer behind it checks whether requested edits are valid, writes them to the right files, and warns when another configuration layer will override them.

The core edit code is the careful pen. It updates the user’s config.toml file, a human-editable settings file, while preserving formatting where possible and writing atomically, meaning it avoids leaving a half-written broken file. Its document helpers convert between TOML text and typed settings. Error handling turns configuration failures into clear JSON-RPC replies, with special guidance for cloud bundle sign-in problems. Migration code imports Claude-style agent settings and adds a default personality only when safe. The daemon settings file separately saves its small remote-control option as JSON.

This stage is the TUI’s main traffic system during normal use. It sits between the user, the screen, the app server, and multiple chat threads. app_event_sender gives other UI code a simple way to send actions into the main loop. app_command defines the allowed kinds of actions, so messages have clear meaning. event_dispatch is the central switchboard: it receives each event and sends it to the right handler.

User key presses go through input, which handles global shortcuts such as switching threads, opening views, clearing the screen, or backing out with Escape. frame_requester asks for screen redraws in a careful way, combining repeated requests so the UI does not waste work.

Messages from the app server go through app_server_events. Server requests that need a later user answer are tracked by app_server_requests. pending_interactive_replay remembers which prompts are still unresolved when a thread is replayed. thread_routing keeps events and actions tied to the correct conversation thread. background_requests runs slower server queries off to the side, then returns their results as normal app events.

This stage is the control center for the terminal app’s bottom pane, where the user types messages, chooses suggestions, answers prompts, and changes small settings. It is part of the main work loop. The bottom pane decides whether each key press belongs to the chat composer, a popup, a modal form, or an interrupt action.

At its core are the shared bottom-pane view contract, the pane controller, the reusable composer widget, and the text area. These keep typing, cursor movement, wrapping, paste detection, Vim-style edits, attachments, draft text, footer hints, and popup state working together. History files add Up/Down recall and Ctrl+R search. Slash-command files parse commands like “/status”, decide which ones are allowed, show suggestions, and run the chosen command.

Mention and search pieces power “@” style insertion. They build searchable candidates from files, skills, and plugins, filter them, and draw the popup and footer. Reusable picker views provide lists, multi-select menus, and search panels. The remaining popup views handle settings, skills, memories, hooks, custom prompts, feedback, app-link requests, server questions, and user-input overlays, all using the same bottom-pane machinery.

This stage is the main control room for the terminal chat screen. It runs during normal use, after startup, while the user is talking to the agent. The central chat widget keeps the transcript, input box, status messages, popups, and streaming replies in sync. Rendering turns that state into terminal rows. Protocol files listen for server events and turn them into visible changes, such as approvals, tool prompts, review results, and notices.

User input passes through several gates. Interaction handles keys, paste, images, copy, interrupt, and quit. Input submission and input flow decide whether text is sent now, queued, treated as a slash command, or held until the current turn finishes. The queue and restore code protect drafts, rejected messages, steering instructions, and attachments from being lost.

Other parts add focused features. Slash dispatch runs commands like /new or /diff. Skills, connectors, IDE context, goals, hooks, usage, tokens, reviews, model popups, plan implementation, and reasoning shortcuts build the small menus and actions around chat. Interrupt and notification helpers make sure prompts and alerts appear in a useful order.

This stage covers special side flows in the terminal interface. These are not the main chat loop, but popups, pickers, previews, and helpers that users open while working. The cloud-tasks files form a small app inside the app: one file stores the task list, selected row, popups, and loaded details; another stores the “new task” form; the UI file draws the list, editor, overlays, confirmations, and spinners.

Several files support navigation through complex conversations. Agent navigation and multi-agent display keep agent threads in a stable order, show readable status rows, and let users switch agents. Backtrack lets a user return to an earlier prompt and roll the conversation back. Pager overlays show long transcripts or help pages.

Other files customize the interface. The keymap files provide the shortcut editor, action catalog, searchable picker, and keypress inspector. Theme picker previews and saves color themes. Pet files handle selecting, previewing, drawing, disabling, and cleaning up the companion pet.

Finally, platform actions, clipboard paste, and external import flows connect the app to the outside world: operating-system checks, pasted images or paths, and importing settings from Claude Code.

This stage is the system’s safety gate. It works behind the scenes whenever a shell command, code patch, network request, or sandbox change is about to happen. Its job is to answer: allow it, block it, or ask the user first.

The newer execpolicy library is the main rule engine. Its front door exposes the useful pieces. Its parser reads policy files written in a small Starlark-based language, meaning a simple scripting format for rules. The rule and policy files define what rules look like, check examples, match commands or hosts, and produce allow, deny, or prompt decisions.

The core files connect those decisions to real tools. sandboxing defines the shared approval and sandbox contract. exec_policy loads and updates command and network rules. network_policy_decision turns network events into clear approval prompts and saved rules. safety does the same kind of gatekeeping for file-writing patches.

The legacy execpolicy library keeps older rule formats working. It parses old policies, matches program arguments, checks per-program rules, validates examples, and ensures commands cannot read or write outside approved folders.

This stage is a behind-the-scenes safety checkpoint in the main work loop. Before Codex takes a risky action, such as running a command, changing files, using the network, or calling an external MCP tool, Guardian may review it instead of immediately asking the user. It acts like a careful supervisor beside the main worker.

The front door in guardian/mod.rs decides when Guardian can automatically allow or deny a request, and includes a safety brake if too many actions are rejected. approval_request.rs describes the kinds of actions that may need approval and reshapes them for prompts, logs, safety checks, and conversation records. prompt.rs builds the message sent to the Guardian reviewer and reads the reviewer’s structured JSON answer.

The review itself runs as a separate mini-session. session/review.rs sets up that special review turn with its own model, limits, tools, and user-interface signal. review_session.rs manages whether to reuse an existing reviewer or start a temporary one, then handles timeouts and cancellation. Finally, review.rs turns the reviewer’s decision into an approved, denied, timed-out, or aborted result for the session, interface, and analytics.

This stage is the system’s checkpoint network. It runs user-configured hooks, which are small external commands, at key moments in the conversation: session start, prompt submit, tool use, permission checks, compaction, and stopping. The registry and engine module are the front desk. They build the hook system, list hooks, preview them, and route events to the right runner, while still supporting the older notify path. Discovery finds hook definitions in config, policy, and plugins, then checks whether they are trusted. The dispatcher chooses which hooks match an event. The command runner starts those hooks as real processes, sends them JSON input, and captures results. The output parser turns their printed text into decisions the system understands, and output spill saves oversized output to a temp file with a short preview. The runtime connects all this back to the main conversation, progress reporting, telemetry, and added context. Event handlers apply the decisions: start and prompt hooks may add context or stop work; pre- and post-tool hooks may block, rewrite, warn, or continue; permission hooks approve or deny; compaction hooks guard history shrinking; stop hooks decide whether to end, block, or continue.

This stage is the front desk for requests that need a human or policy decision. It sits in the main work loop, when the assistant or an outside MCP integration needs permission, confirmation, or extra information before continuing. MCP means “Model Context Protocol,” a way for other tools to connect to Codex.

The permission request handler lets the model ask for broader access, such as using a file or action that is currently blocked. It checks the request, connects it to the correct workspace, and sends it into the session’s approval path. The user input handler does a similar job when the assistant must pause and ask the human a question, then returns the answer as tool output.

For MCP traffic, elicitation decides whether an outside request is safe to accept, must be rejected by policy, or should be forwarded for review. The exec approval code asks an MCP client before running a shell command. The patch approval code asks before applying code edits. Together, these pieces normalize many kinds of “may I?” and “please answer” moments into the same review machinery.

This stage sits in the main work loop, whenever the assistant wants to do something that may affect the user’s machine or data. The core orchestrator is the traffic controller: it checks whether a tool needs permission, chooses a safety sandbox, runs the tool, and may ask again with broader access if the sandbox blocks it. MCP tool approval templates turn external tool-server requests into plain questions instead of raw names and JSON.

The terminal UI then makes those decisions visible. Approval events store requests in a safe displayable form, while the approval overlay shows the actual pop-up and sends back approve or deny. Tool requests puts these decisions into the chat screen. Permission popups and the permissions menu let users choose or change how much freedom the assistant has, including reviewing automatic denials. Auto-review denials keeps a recent list of blocked actions with readable labels. Pending thread approvals warns when background agent threads are waiting. Request user input handles structured questions and typed answers. Windows sandbox prompts guide Windows users through safe setup. Hooks RPC checks server-side hooks and records the user’s trust choices.

This stage is shared execution-time protection. It sits behind tool runs and approval-gated actions, making sure decisions about network access and sandbox safety are actually enforced while commands are running.

The network proxy pieces act like a guarded doorway to the internet. The library front door exposes the proxy parts other code may use. Its state builder turns requested settings into safe live settings, rejecting anything that would break central limits. The approval code handles “unknown host” cases by asking the right reviewer, remembering session-wide answers, and returning clear errors when access is denied. The network policy code decides allow, deny, or ask, and records why. The runtime is the proxy’s live rulebook: it checks hosts, HTTP methods, Unix sockets, and interception hooks, reloads changes, and logs blocked requests.

The Windows sandbox pieces enforce similar limits at the operating-system level. One file grants safe extra read access when needed. Others track and clean up read-deny rules, make protected workspace folders read-only, and install Windows Filtering Platform firewall rules. The setup wrapper applies that network lockdown defensively and records whether it worked.

This stage is the system’s command-running control room. It sits in the main work loop, where user or assistant requests become real programs running on the computer, but with checks and safety rules in between.

On the app-server side, command_exec_processor.rs, command_exec.rs, and process_exec_processor.rs translate client messages into process actions: start a command, send input, resize a terminal, stop it, watch its output, and clean up afterward. The TUI helpers, fs.rs and workspace_command.rs, let the text interface ask the app server to read or write files and run small workspace commands, whether the workspace is local or remote.

In core, exec.rs is the actual child-process runner, while sandboxing/mod.rs packages commands for restricted execution. user_shell.rs runs explicit user shell commands and records their progress. The shell handlers and runtimes check permissions, prepare environments, emit progress, support cancellation and hooks, and then launch commands safely. unified_exec.rs and exec_command.rs provide a newer single front door for execution requests. zsh_fork_backend.rs adds a special supported zsh path when needed.

This stage is the low-level machinery that lets the system run interactive commands, keep them alive, talk to them, and stop them safely. It sits behind the main tool loop: when a command is approved, these pieces turn that request into a real process and stream its output back.

The unified_exec front door defines the shared request shapes, limits, and helpers, while its errors file gives the whole area one clear failure language. process and process_manager are the control room: they start commands, reuse sessions, collect output, send later input, track exits, cancel work, and clean up. The write_stdin handler is the small inlet that sends more text into an already-running command.

On the exec-server side, process defines the common process contract. local_process runs commands on the server machine, and remote_process makes a remote command look local. spawn is the safe doorway for launching programs with the right folder, environment, network, and input/output setup.

The pty utilities provide the actual plumbing: pipes for simple programs, PTYs, or “fake terminals,” for interactive ones, process groups for cleanup, and Windows ConPTY bridges for terminal behavior on Windows.

This stage is the editing engine for the system. It is used during the main work loop when the assistant wants to change files. First, apply_patch_spec defines the “apply_patch” tool: its name, description, and the exact patch format the assistant must use. The parser and streaming_parser read that patch text. The normal parser waits for the whole patch and turns it into clear actions like add, delete, update, or move a file. The streaming parser can understand the patch while it is still arriving, so progress can be shown early.

The invocation code decides whether some command text is truly an apply_patch request, not just an ordinary shell command. The core apply-patch library then performs the actual file edits and records what succeeded or failed. The core handlers and runtime adapters act like safety gates: they validate the request, check policy, ask for user approval if needed, choose the right sandboxed environment, run the edit, and report results. For Git-based patches, git-utils applies them through Git and explains which files applied, skipped, or conflicted.

This stage is shared behind-the-scenes support for running commands safely on Unix systems. It sits just before a tool or shell command is launched. Its job is to choose the right sandbox, rewrite the launch request, and, when needed, ask for permission to run with more power.

The sandboxing front door and manager provide the common entry point. They hide Linux and macOS differences, decide if a sandbox is needed, and turn a normal command into a sandbox-ready one. On Linux, the Bubblewrap and Landlock pieces check what sandbox tools are available, build the restricted filesystem and network rules, and start the helper process. The launcher picks a system Bubblewrap if possible, or a bundled copy if not, and reports clear setup problems.

The shell-escalation pieces handle commands that may need extra permission. A patched Unix shell can ask an escalation server what to do. The policy says allow, deny, or escalate. The client and server carry that request and connect it to the real process launcher. The runtime files prepare shells, environments, sandbox inputs, and the special Unix shell path that ties approval and sandboxing together.

This stage is shared behind-the-scenes support for the exec server when it needs to work with files. The exec server may be running commands locally, in a restricted sandbox, or on another machine, but the rest of the system should be able to ask for simple actions like read, write, list, copy, or delete.

The local file system layer is the front desk for files on the same machine. It either performs the action directly or sends it through a sandbox, which is a locked-down area that limits which paths can be touched. The sandboxed file system layer is the safe version of those same operations, enforcing the sandbox rules. The filesystem sandbox runner starts helper work inside that restricted space and carefully controls what environment and file access the helper receives.

The helper protocol is the messenger format for filesystem actions. It turns requests into real file operations and turns results or failures back into replies. Remote file system support uses a similar idea to make files on another machine look local. File-read support handles long reads in small chunks, tracking open reads and rejecting unsafe or stale requests.

This stage is the Windows-only machinery that prepares a safe “guest room” for commands and then starts them inside it. The public entry points choose the right sandbox path: the newer elevated runner or the older legacy runner, while the TUI asks for the requested sandbox level. Setup code creates or refreshes sandbox Windows users, stores and checks their identity, reports setup errors, hides those users from normal Windows screens, and fixes access to bundled runtime tools. Permission code edits Windows access-control lists, which are file permission rules, to allow workspace writes, deny reads to sensitive paths, and reduce risky “Everyone can write” folders. Token and desktop code decide what powers and screen environment the child process gets. Firewall and WFP rule code block or narrow network access. Spawn preparation turns the requested read, write, and network policy into these concrete Windows settings. Process-launch code then creates the command with the right user, environment, pipes, and optional ConPTY fake terminal. The elevated runner uses locked-down named pipes to talk to its child, and the stdio bridge connects the sandboxed program back to the user’s terminal until it exits.

This stage is the bridge between Codex and MCP, the Model Context Protocol, which lets outside programs offer tools, files, and other resources to the assistant. It is mostly behind-the-scenes support used during session startup and the main work loop. The app-server and ext/mcp files register MCP as an extension, discover MCP servers from plugins, and pass extension events to the right client. The codex-mcp library defines what an MCP server is, builds usable server configs, supports hosted Codex Apps, and keeps user app-tool caches separate. Its connection manager is the switchboard: it starts servers, checks readiness, collects tools and resources, and routes calls. Resource clients and handlers let the model list templates, list resources, and read one resource in a consistent way. Tool preparation code filters and renames tools, limits what the model sees, adapts file inputs, and uploads local files when a tool expects hosted files. Tool-call code checks permissions, asks for approval, records results, and reports back. Session and skill-dependency code connect MCP servers to each user session, refresh them when needed, and handle login prompts safely.

This stage is the plugin “supply chain” for Codex. It is shared support used during startup, tool discovery, installation, and user interaction. The core plugin files define the public API, read plugin.json manifests safely, load installed plugins into skills, apps, hooks, MCP servers, and telemetry, and coordinate installs, removals, cache refreshes, and marketplace rules. Marketplace files add, validate, upgrade, and remove catalogs from local folders or Git, while remote bundle and remote service files download, sync, install, uninstall, share, and check out plugins from ChatGPT-backed services, including older APIs.

Connector files decide which app connectors and tools are visible, enabled, and safe enough to run, combining login state, user settings, managed policy, and tool safety hints. Discovery and mention files find plugins the user may want, or ones the user explicitly referenced in chat. Install-suggestion tool files let the assistant list possible plugins and ask for user approval before installing. Finally, the CLI and terminal UI provide the human control panels: commands and popups for adding marketplaces, browsing plugins, installing, disabling, upgrading, and removing them.

This stage is shared support for the model’s “extra hands.” On each turn, spec_plan builds the tool menu and the router that runs the chosen tool. hosted_spec adds provider-side abilities like web search or image creation. Dynamic-tool files adapt tools supplied during the conversation, while extension_tools lets installed extensions behave like built-in tools and report progress.

Several helper tools make the menu easier to use: tool_search lets the model find hidden tools by text, view_image loads an image file for inspection, get_context_remaining reports remaining conversation space, and small spec files describe plan updates, new contexts, and worker-agent jobs.

Code mode is the long-running script area. Its runtime prepares a safe JavaScript world, callbacks let scripts talk back to Rust, and execute/wait tools start, monitor, or stop script cells.

The extension registry is the sign-up sheet. Web search, image generation, goals, memories, and skills plug into it. Memories safely list, read, search, and write local notes. Skills gather packages from the host, executor, orchestrator, or remote service, then expose safe list and read tools.

This stage is part of the app server’s main work: answering client requests when a user wants to discover apps, connectors, or files. It acts like a front desk that gathers information from several shelves, cleans it up, and returns a usable list.

The connector helpers prepare app discovery data. accessible.rs takes raw connector tools and turns them into user-facing apps, grouping duplicates and adding friendly names and descriptions. filter.rs decides what should be visible, hiding blocked connectors and avoiding suggestions for apps the user already has. merge.rs combines several connector lists into one best version, keeping the strongest name, description, logo, install link, and access state.

apps_processor.rs is the coordinator. It receives app-list requests from clients, checks whether app access is allowed, pulls data from cached and live sources, reports progress, and returns results in pages.

fuzzy_file_search.rs supports searching files and folders by approximate text matches, like typing a few letters into an editor’s “open file” box. It can run a single search or maintain a live session that updates as the query changes.

This stage is shared behind-the-scenes support. It does not run code itself. Instead, it defines the public “contract” that other parts of the system agree to use when they talk about code mode. Think of it like the standard set of forms and labels used by everyone in an office.

The crate front door, lib.rs, gathers the important names from the internal files and re-exports them so other code can import them from one simple place. description.rs explains the available code-mode tools in human-readable text, including TypeScript-style examples, and reads small settings placed at the top of JavaScript input. response.rs defines common result content, such as text and images, and keeps their JSON shape consistent. runtime.rs defines the request and response messages exchanged with the runtime, the worker that actually executes code cells and reports progress or final results. session.rs defines the longer-lived session contract: how to start code, wait for answers, call tools, send updates, and shut everything down cleanly.

This stage is the public “language” of the Codex API layer. It is shared behind-the-scenes support used whenever the program sends requests to external services or reads their replies. Instead of each caller inventing its own message format, these files define the agreed shapes of those messages.

The library front door, lib.rs, decides what parts of this API package are visible to the rest of the codebase. common.rs provides the everyday forms for the Responses API: requests, responses, streamed events, and extra metadata such as tracing details used to follow a request through the system. error.rs gives all API code one common way to describe failures, such as bad requests, network trouble, or rate limits.

The remaining files cover specific transports or features. protocol.rs defines realtime WebSocket messages, which are two-way live messages, and selects the right parser for different protocol versions. images.rs defines image generation and editing payloads. search.rs defines request and reply formats for web, image, finance, weather, sports, time, and page-navigation searches.

This stage is shared behind-the-scenes support for people who add plugins, extensions, or hooks. It defines the stable “contracts” they can rely on, so outside code does not need to know the host’s private machinery. The extension API front doors gather and re-export the public pieces. Capability files describe powers the host may give an extension: starting a subagent, sending events, or adding extra items to the model’s current turn, with safe no-op versions when unsupported. Contributor files define the callback data for MCP server changes, thread and turn lifecycle moments, tool calls, and turn input. The main contributors file lists the plug-in points themselves. State gives extensions a safe typed storage box, and user instructions define how startup instruction text is reported. Goal events package goal changes in the standard event form. The memories backend defines a storage contract, while IDE context describes editor-provided file and selection data for the terminal UI. The hooks files define declared hook handlers, event modules, shared hook types, JSON wire formats, schema generation, and schema loading, making hook commands predictable and checkable.

This stage is shared behind-the-scenes support. It defines the “contracts” for tools and protocol messages: the agreed shapes of data that the model, Codex core, extensions, hooks, MCP clients, and user interfaces pass to each other. Like blank forms, these schemas say what fields are allowed, what names to use, and how results should be reported safely.

The tools files describe model-visible calls: generic tool inputs, tool-call packages, OpenAI Responses API tool specs, shell tools, context-count tools, user-input tools, goal tools, web search, skills, and MCP Codex session tools. They do not usually perform the work; they describe how to ask for it. The core context and code-mode adapter files translate real tool results, including text, images, commands, patches, and MCP outputs, into shared messages for the model, logs, hooks, and code mode. The protocol files define common payloads for permission requests, human questions, plan updates, and MCP approval labels, so Rust, JSON schemas, and generated TypeScript stay in agreement. Small support files forward shared errors and keep hook tool names consistent.

This stage defines the “wire models” for parts of the system that talk across a boundary. A wire model is the exact shape of messages sent between programs, processes, or tools, usually as JSON or another stream format. These files are shared behind-the-scenes support: they do not run the main agent themselves, but they make sure both sides of a conversation agree on what each message means.

The exec-server files describe how clients connect to an executor, how running processes are named, and what requests and replies look like for starting commands, reading output, accessing files, or making HTTP calls. The exec events file defines the JSON-lines event stream produced by codex exec, so outside tools can follow an agent run step by step. The Unix escalation protocol defines the messages exchanged when a shell command may need different sandbox permissions. The Windows framed IPC file does the same for communication with an elevated command runner, and also wraps messages into length-marked packets so they can be read safely from a stream.

This stage provides shared behind-the-scenes data models rather than main work-loop behavior. It defines the common “forms” that other parts of the system fill in when they record or read rollout traces. A rollout trace is a saved history of what an agent did, useful for debugging, review, or replay.

The session model describes the overall run. It records whether a rollout is still active or finished, which agent threads joined in, and the start and end times of pieces of runtime work. This is like the cover sheet and timeline for a job.

The runtime model describes the events inside that job: code cells, tool calls, terminal commands, checkpoints where context was compacted, and links between trace objects. It gives the trace system a shared vocabulary for the moving parts of execution.

The payload model keeps the trace lightweight. Instead of putting large raw logs or request and response bodies directly into the main records, it stores small references that point to those larger payloads elsewhere in the rollout bundle.

This stage is shared behind-the-scenes support for making text safe, short, and easy to read across the project. It is like a set of measuring cups and labels used by many kitchens, not the main cooking itself.

The string utilities clean and convert text safely. They can produce ASCII-only JSON for places that may reject Unicode, shorten long strings without breaking emoji or non-English characters, and prepare safe metric tags or terminal-friendly code links. Number and elapsed-time formatters turn raw values into labels people can scan, like “12,000”, “12K”, or “1m 15s”. CLI helpers display environment variable names without leaking their values, and build copy-safe “resume” commands for old threads.

Several tools keep text from overwhelming the system. Output truncation preserves useful beginning and ending context, while response-history trimming keeps conversations within a reusable size budget. The strict template helper fills placeholders such as “{{ name }}” and catches missing or mistaken fields. Web search formatting and TUI text helpers turn actions, paths, JSON, and long tool output into compact readable labels for narrow displays.

This stage is shared behind-the-scenes support for reading text that arrives in pieces, such as live assistant output or process logs. Its job is to turn messy chunks into clean, useful events without losing hidden information. The stream-parser front door gathers these helpers for the rest of the project. Its common result model separates visible text from hidden parts, like citations or metadata, so the app can show only what users should see while still keeping machine-readable details. The UTF-8 stream reader safely joins raw bytes into text even when one character is split across chunks. The line buffer does a similar job for process output, waiting until a full newline-ended line is ready. Other parsers remove inline hidden tags, detect tagged blocks that start and end on their own lines, and extract structured memory citations. The table detector recognizes Markdown tables and code fences so display and cleanup code agree. The mention codec turns user-friendly tool mentions into stored links and back again. Together, these pieces act like filters on a conveyor belt for streamed text.

This stage is shared behind-the-scenes support for drawing text in the terminal interface. It is used whenever the app needs to show output, Markdown, diffs, links, or styled lines inside a limited screen area.

The geometry helper in render/mod.rs lets drawing code add padding inside a rectangle, like leaving margins in a page. line_utils.rs prepares display lines so they can be safely stored, copied, and given prefixes. width.rs checks whether there is any usable space left after those prefixes. ansi-escape/src/lib.rs converts colored terminal output into drawable text and expands tabs so columns line up.

Several files then shape text to fit. line_truncation.rs measures and cuts styled text without splitting wide characters such as emoji. wrapping.rs wraps rich terminal text while preserving styling, indentation, byte positions, and whole clickable URLs. live_wrap.rs does similar wrapping for incoming plain text. markdown_text_merge.rs joins adjacent Markdown text pieces after parsing so rendering sees smoother text. terminal_hyperlinks.rs keeps link targets separate from visible words until the final drawing step. scrollable_diff.rs uses these pieces to show wrapped diffs and messages with a valid scroll position.

This stage is shared behind-the-scenes support for the terminal user interface. It sits above the low-level text drawing code and prepares what the user will see: colors, labels, rows, popups, footers, and status text. The color, style, chart palette, and spacing files choose readable colors, symbols, and margins so screens stay consistent on different terminals. The renderable building blocks let text and containers report their size and draw themselves.

Several files shape common controls. Key hints make shortcuts display consistently. Scroll state, selection rows, selection popups, and selection tabs keep lists, tabs, highlights, wrapping, and disabled choices predictable. The footer, action-required title, and popup constants build the bottom-pane messages that guide the user.

Other helpers turn internal data into friendly display models. Warning logic avoids repeated chat warnings. Migration, goal, skill, status, and remote-connection helpers convert raw settings, paths, counts, times, server details, and skill metadata into short readable text. History cells provide reusable transcript pieces, including wrapped text and links.

This stage is shared behind-the-scenes support for making the command-line interface feel alive without getting in the way. It is used while the program is running, especially when the interface needs to show that work is happening.

The motion file is the central switchboard for small movement effects, such as loading dots or animated highlights. It also respects reduced-motion settings, meaning users who prefer less animation still see clear, steady feedback. The shimmer file supplies one of those effects: it breaks text into styled pieces and changes their brightness over time, like a light sweeping across a sign. The ASCII animation file is the frame driver. It decides which text-art picture to show next and asks the interface to redraw at the right moments. The frames file is the art library, packaging those pictures and their normal playback speed into the program. Finally, the doctor progress file shows temporary “checking…” messages during health checks, sending them somewhere safe so they do not mix into the final report or JSON output.

This stage is a behind-the-scenes safety check for the project’s communication rules. It does not run the app’s main work. Instead, it makes sure the messages sent between the app server and its clients keep the same shape over time. That “wire format” is the agreed JSON layout used on the network, like a shared form both sides know how to fill in.

The common protocol tests check how client response data becomes JSON-RPC response parts. JSON-RPC is a simple request-and-response message style using JSON. These tests confirm when a response should also create an internal client response object, and when it should remain only a plain JSON-RPC result.

The version 2 remote-control tests focus on remote-control messages, checking that Rust data structures turn into exactly the expected JSON and can be read back correctly. The broader version 2 protocol tests cover app-server messages, older accepted JSON shapes, and conversions to and from core Codex protocol types.

Finally, the schema fixture test compares generated protocol schemas with the checked-in copies, catching accidental protocol changes.

This stage is the safety net around the app server’s background service, its communication pipes, and its special test client. It is shared behind-the-scenes support: it does not run the product itself, but it proves that startup, messaging, updates, and test-only tools behave correctly.

The daemon tests check the background server’s “PID file,” a small record saying which process is running. They cover starting, stopping, stale records, launch arguments, log reading, managed install version checks, and update decisions. One key rule is protected: if the updater program itself changes, that is more urgent than an ordinary version change.

The transport tests check how clients connect and receive messages. Unix-socket tests cover local WebSocket connections, socket-file protection, message forwarding, and avoiding double startup races. Other transport tests make sure messages go only to suitable clients and that one slow client cannot block the rest. Remote-control tests check pairing, client listing, revoking, refreshed authentication, and useful error details.

The test-client files provide a realistic command-line client, fake local HTTP service, and plugin analytics checks, including smoke tests for install, update, use, and removal events.

This stage is shared test support for the app server. It is not part of the running product path; it is the safety net used while building and changing the server. The unit tests check important behaviors inside the app-server crate: importing external agent settings without losing or duplicating data, managing config files safely, accepting command-line overrides, keeping tracing links across JSON-RPC requests, refreshing runtime state after config migration, reporting remote-control errors clearly, preserving conversation thread state, and creating summaries from the right user message.

The integration-test helpers act like a small pretend world around the server. They provide fake analytics, authentication files, config files, model lists, saved sessions, and AI service responses, so tests can run without real accounts, networks, or production services. The mock model server and test app-server client let tests start a real server process, send JSON-RPC commands, read replies, and shut it down cleanly. Finally, the suite index files are the test runner’s table of contents, gathering the right test groups so they compile and run together.

This stage is the broad end-to-end test bench for the app server. It treats the server like a real client would: start it, connect to it, send requests, run conversations, use tools, and check that the answers and side effects are correct. It is mostly about the server’s public behavior, not small internal parts.

One group tests the basic “front desk”: login, accounts, rate limits, configuration, startup handshakes, model discovery, safe file and process access, and remote-control pairing. Another group tests the live connection pipes, such as WebSockets, authentication, reconnects, shutdown behavior, desktop proof tokens, experimental features, and realtime text or audio sessions.

A third group checks extensions: plugins, marketplace installs, connector apps, hooks, skills, MCP tool servers, shell commands, file search, image generation, sleep, and web search. These tests make sure outside tools appear only when allowed and run safely.

The final group follows the conversation lifecycle: creating threads, running turns, interrupting work, asking permissions, saving history, summarizing, reviewing code, reopening sessions, and deleting or archiving old work.

This stage is a behind-the-scenes safety net for the core runtime. It does not add user features itself. Instead, these tests check that the main conversation engine starts, runs turns, saves state, resumes later, and shuts work down safely. The session tests cover conversation setup, history, settings refresh, hooks, metrics, network rules, plan-mode messages, user shell commands, and worker-failure messages. Rollout, thread, history, compaction, event-mapping, stream, image, and client-request tests make sure saved or streaming conversation data is cleaned, shortened, restored, and sent to APIs in the right shape. Agent tests cover parent and child agents: spawning, roles, registries, delegation, concurrency limits, memory residency, cancellation, and resuming agent trees. Guardian, MCP, execution-policy, sandbox, and patch-safety tests check the permission system that decides what commands, tools, and file edits may run. State, metadata, timing, diff-tracking, Git, shell, AGENTS.md, personality migration, and realtime tests check supporting records and environment details. Together, these tests act like gauges around the engine, warning when lifecycle, safety, or saved-state behavior changes unexpectedly.

This stage is a broad safety check for Codex’s tool system, the behind-the-scenes machinery that lets the model edit files, run commands, ask the user, call external MCP tools, manage sub-agents, and use hosted features like web search or image generation. Most files here are tests that protect the public “tool contract”: the exact names, descriptions, inputs, and outputs the model or outside clients depend on. That includes specs for shell, patching, MCP resources, multi-agent tools, user input, plugin installs, hosted tools, and agent jobs.

Other tests check the moving parts that execute those tools. The registry finds and runs tools. The router sends each requested call to the right local, MCP, dynamic, or extension handler. Context and trace tests make sure results and history are recorded clearly. Approval, sandboxing, network, command-canonicalization, and runtime tests guard the rules for when commands or file edits are allowed. The test synchronization tool helps timing-sensitive tests coordinate reliably. Finally, the unified-exec tests cover the newer command runner: streaming output, long-running processes, remote exec servers, timeouts, cleanup, and safe shutdown.

This stage is shared behind-the-scenes support for testing the core crate. It is not a feature being tested; it is the workshop that lets all the feature tests run safely and repeatably. The main entry files, all.rs and suite/mod.rs, gather the integration tests into one runnable test program and let that program pretend to be helper binaries when needed. The common toolbox supplies temporary folders, default settings, sandbox checks, hook approval setup, tracing setup, and helpers for waiting on background processes. Other helpers decide whether tests run locally, in Docker, or through Wine, and prepare special zsh fork tests when that path is available. Several files build fake outside services: mock Codex Apps, OpenAI Responses and Models APIs, WebSocket or HTTP replies, and controlled Server-Sent Event streams. Snapshot helpers turn large request data into stable readable text. The Codex test builders create a complete fake conversation world, while the exec helper runs codex-exec without touching real user files. Together, these pieces make end-to-end tests reliable, isolated, and understandable.

This stage is a large end-to-end test area for Codex’s live user sessions. It checks the main work loop and the shared support around it: sending requests to AI models, receiving streamed replies, remembering conversation state, choosing models, using tools, asking for approvals, and working with helper agents or remote machines.

The transport suites test the “wires” to model providers, including HTTP, WebSocket, realtime, retries, headers, quotas, and streamed responses. The history and persistence suites test Codex’s memory: saving sessions, compacting long chats, resuming, forking, and restoring tool logs. The prompt and model-selection suites check that each model request is packed with the right instructions, context, tools, and limits. The multi-agent suites test child agents, delegation, shared limits, job queues, and remote environments. The approvals and hooks suites test safety gates that pause, block, review, or modify actions. The tool and runtime item suites test shell commands, patches, plugins, external app tools, images, searches, and the user-visible event stream. Together, these tests prove the whole session behaves safely and predictably.

This stage checks the standalone apply-patch program from the outside, as if it were being used by a real person in a terminal. It is part of the project’s testing support, not the normal startup or work loop. Its job is to prove that the finished executable accepts patch input correctly and leaves the filesystem in the right state.

The suite starts in all.rs, which acts like the front door and loads the shared test tree. mod.rs is the table of contents. It selects the test groups to run and leaves out one group on Windows where the behavior does not apply. cli.rs focuses on command-line use: it runs apply_patch with patch text passed either as an argument or through standard input, then checks that files are created or changed. tool.rs goes deeper into real folder effects, testing edits, overwrites, renames, deletes, and clear failures for bad patches. scenarios.rs runs complete example patches and compares the final folder contents with the expected results.

This stage checks the front door of the Codex command-line program. These are integration tests, meaning they run commands much like a real user would and check the visible results: exit codes, printed text, JSON output, and saved configuration files. The app-server and exec-server tests make sure strict config mode rejects unknown settings instead of ignoring mistakes. The delete test confirms Codex will not ask for deletion confirmation when the target session is missing. The update test makes sure debug builds fail clearly instead of dropping into the normal prompt. Debug tests cover clearing stored memories safely and printing model lists as valid JSON. Feature tests check command-line feature flags and config writing. Plugin tests cover plugin commands, marketplace add, remove, and upgrade behavior, including local folders, cleanup, and error messages. MCP tests cover adding, listing, getting, and removing MCP server entries, including hiding secrets in friendly output while preserving full JSON data. Finally, the live CLI smoke test can exercise the real program against the OpenAI API, but it is normally skipped to avoid network cost and outside-service failures.

This stage is the safety check for codex-exec, the command-line program people run to ask Codex to do work. It is behind-the-scenes support, run by tests to make sure startup options, the main request flow, and failure exits behave reliably. The CLI and main tests check that flags, configuration options, and resume prompts are read the way users expect. The library tests cover deeper defaults such as logging, permissions, review setup, prompt decoding, and session startup. The event processor tests check how server messages become user-visible output: readable text for humans, JSONL lines for streaming tools, and simpler JSON events for automation. The integration suite then tests the whole machine assembled: extra writable directories, AGENTS instruction files, API keys and Originator headers, JSON output schemas, stdin prompts, approval modes, ephemeral sessions, hooks, required MCP tool startup failures, patch application, resume behavior, server error exit codes, and real streaming against a mock server. Together these tests make sure codex-exec is predictable for both people and scripts.

This stage is behind-the-scenes safety checking for the execution policy, the part of the system that decides whether a shell command may run, must be blocked, or needs user approval. It is not the main work loop itself; it is the test harness that proves the rules behave as expected.

The current tests check both the policy engine and its command-line face. One test runs codex execpolicy check and confirms it reports JSON correctly when a rule blocks something risky like git push. Another checks policy files directly, making sure commands are sorted into allowed, denied, forbidden, or prompt-needed results.

The legacy tests act like an older library of examples that must still pass. A top-level test file and module list gather the suite. “Good” and “bad” command lists protect broad expectations. Command-specific tests then inspect known Unix tools: cp, head, ls, pwd, literal subcommands, and narrow safe forms of sed. Together they form a regression net, catching accidental changes that would make the policy too strict or too loose.

This stage is the safety net for the login system. It runs during testing, not during normal use, and checks the full journey of signing in, staying signed in, and signing out. The test entry files gather the separate test modules so Rust can run them as one suite.

The smaller auth tests check the building blocks: whether different token text formats are recognized, whether personal access tokens fetch complete user data, whether API keys and environment settings are accepted safely, and whether Amazon Bedrock credentials can replace older OpenAI-style credentials. Storage tests make sure saved logins can move between files, memory, and the system keyring, which is the operating system’s secure password store.

The larger workflow tests act more like rehearsals. Command-line login tests check API-key and device-code login, where a terminal asks the user to approve access in a browser. Browser-server end-to-end tests exercise the local login server from the outside. Refresh tests confirm expired ChatGPT tokens are renewed without overwriting newer data. Logout tests ensure remote revocation is attempted and local credentials are cleaned up even if revocation fails.

This stage tests the MCP server as a real program, not just as separate pieces. It belongs to the “prove the system works end to end” part of the story. The tests start the codex MCP server as a child process, send it JSON-RPC messages, and check the replies. JSON-RPC is a simple request-and-response format written as JSON.

The test entry point, all.rs, gathers the integration tests so Rust can run them together. suite/mod.rs points to the codex_tool tests, like a small table of contents. common/lib.rs provides shared test tools, including a way to turn raw JSON replies into normal Rust values.

mcp_process.rs is the main wiring harness. It starts the server, talks to it, and shuts it down cleanly. mock_model_server.rs plays the role of the remote AI model, returning prepared answers instead of making real network calls. responses.rs builds those prepared streamed answers. Finally, codex_tool.rs uses all of these pieces to check real codex tool behavior, including permission prompts, approved file changes, and instruction forwarding.

This stage is a behind-the-scenes safety check for observability: the code that records what the system is doing. “Telemetry” means measurements, logs, and traces that help developers understand sessions without inspecting them by hand. The OpenTelemetry test entry files, tests.rs and suite/mod.rs, assemble the test suite, while harness/mod.rs provides an in-memory fake metrics collector. The validation, timing, send, snapshot, runtime_summary, manager_metrics, export-routing, and HTTP loopback tests check that metrics reject bad input, record durations, flush correctly, can be read immediately, summarize runtime activity, carry the right labels, route sensitive details safely, and can be exported to a local fake collector. The analytics client tests check that app-server activity becomes the right analytics events, with batching and privacy limits. The app-server analytics tests decide when analytics should run and provide HTTP capture helpers. Core task and utility tests verify telemetry tags for proxy use, memory, compaction, feedback, authentication failures, and thread names. The main core OpenTelemetry test checks session logs and traces. The state log filter test keeps noisy low-level SDK messages out of the user-facing log database.

This stage is a safety check area for Codex’s behind-the-scenes rules: how it reads settings, applies policy, and builds the environment before real work begins. The configuration tests check that TOML and JSON files are parsed, merged, edited, and rejected correctly when they contain typos, old names, unsafe values, or conflicting profiles. Cloud-config tests add the organization-managed layer: they build fake bundles, load cached or downloaded settings, verify signatures and account ownership, and make sure enterprise rules override user settings in the right order.

Other tests cover the policy machinery. Permission, sandbox, Windows sandbox, Bubblewrap, and network proxy tests make sure file access, internet access, and approval prompts are safe and predictable. Feature-flag and tool-config tests check which experimental or model-dependent abilities turn on. Hook, prompt, MCP, instruction, and memory-guard tests verify the smaller “control panels” around tools, user instructions, external servers, and quota safety. Environment, path, Git, and test-runner tests ensure commands run with the right variables, paths, and platform assumptions. Together, these tests keep startup choices and safety boundaries from drifting silently.

This stage is the test safety net for Codex’s add-on system. It covers the parts that let Codex find extra abilities, load them safely, show them to users, and turn them into tools the model can call. The plugin tests build fake home folders, marketplaces, caches, and executor file systems, then check discovery, loading, storage, curated startup syncing, remote sharing, app routing, mentions, rendering, and install requests. The skills tests do the same for skill folders: they check selection by user input, loading from user, project, plugin, and system locations, caching, enable rules, and safe executor-owned file access. The extension tests protect the public extension interface and specific extensions such as goals, image generation, and memories. The MCP tests cover Model Context Protocol, a standard way for Codex to talk to external tool servers, including configuration, catalogs, connection caching, hosted apps, executor plugins, and real client/server calls. The tool tests make sure tool definitions, schemas, search text, code-mode forms, and API JSON stay stable. Together, these tests keep the add-on “plugboard” predictable and safe.

This stage is a behind-the-scenes test bench for the parts of the system that talk to services, choose AI models, build prompts, and move data over the network. It is not the main user workflow; it is the safety lab that keeps that workflow reliable.

The model tests check provider settings, built-in defaults, user overrides, collaboration presets, model caching, and offline test model data. Together they make sure the app picks and describes models without stale data or unsafe limits. The client and login tests check HTTP requests, authentication tokens, headers, error translation, certificates, rate-limit calls, and model-list fetching, using fake servers instead of real ones. Streaming tests cover server-sent events and realtime WebSocket sessions, including retries, audio flow, and clean shutdowns.

Prompt and tool tests protect the exact text and schemas sent to AI models, including reviews, goals, memory prompts, image detail, and JSON Schema cleanup. Protocol, code-mode, RMCP, proxy, socket, TLS, and mock-cloud-task tests check error messages, streamed output, retries, authorization recovery, blocked requests, local sockets, security setup, and fake service behavior.

This stage is the project’s safety net for saved history and recovery. It is not the main user-facing work loop. Instead, it checks the behind-the-scenes machinery that records conversations, rebuilds them later, and keeps stored state usable after mistakes or damage.

The rollout trace tests feed fake event logs into the trace “reducer,” which is the part that turns noisy raw events into a clean replay of a session. They cover conversations, model calls, cancellations, code cells, terminal commands, child agents, protocol events, and thread tracing. The rollout storage tests then check the files and indexes that keep past sessions searchable, compressible, repairable, and linked to saved metadata.

The state and external-agent tests check the small databases and ledgers that remember threads, imported agent sessions, and completed configuration imports. Recovery tests make sure broken database files are moved aside safely.

The memories tests cover startup, prompt text, citations, file naming, cleanup, and workspace diffs. Message-history and thread-store helpers check that saved messages and fake local thread data can be read, appended, trimmed, and reused reliably in tests.

This stage is a behind-the-scenes safety check for shared utility code. It is not part of startup, the main work loop, or shutdown. Instead, it makes sure small helper libraries behave correctly before other parts of the system rely on them.

The output truncation tests check the helper that shortens large results. This is like trimming a long receipt while keeping the important warning labels intact. The tests cover plain long text, mixed text and images, encrypted content, line limits, token estimates, and odd edge cases, so shortened output stays predictable and safe.

The PathUri tests protect the type that represents local file paths as file:// addresses. They verify converting, saving, loading, joining, and parsing paths on Unix, Windows, and unusual inputs.

The API path string tests check compatibility with an older path format. They make sure file URIs can move to and from that format, including spaces, percent-escaped characters, network shares, and invalid text. Together, these tests keep path handling and output trimming reliable across the whole project.