Core src 运行时、会话、策略和状态测试

fn user_message(text: &str) -> ResponseItem

作用：造一条“用户说了某段话”的测试消息。测试里不用每次手写完整结构，直接传文本就能得到标准用户输入。

数据流：输入一段字符串 → 把它放进 ResponseItem::Message，角色设成 user，内容设成输入文本 → 返回这条可放进历史记录的用户消息，不改动外部状态。

调用关系：它是很多回滚、重放和任务拒绝测试的造数工具；这些测试用它快速拼出对话历史，再交给 Session 的相关流程验证。

调用图：被 8 处调用（recompute_token_usage_uses_session_base_instructions, thread_rollback_persists_marker_and_replays_cumulatively, thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay, thread_rollback_restores_cleared_reference_context_item_after_compaction, try_start_turn_if_idle_rejects_active_review_turn_without_injecting, try_start_turn_if_idle_rejects_active_turn_without_injecting, try_start_turn_if_idle_rejects_pending_trigger_turn_without_injecting, try_start_turn_if_idle_rejects_plan_mode_without_injecting）；外部调用 1 个（vec!）。

fn assistant_message(text: &str) -> ResponseItem

作用：造一条“助手回复了某段话”的测试消息。它让测试能方便地构造一段已有的助手输出。

数据流：输入一段字符串 → 包装成角色为 assistant、内容为输出文本的 ResponseItem → 返回测试用的助手消息。

调用关系：它被线程回滚和历史重放相关测试调用，用来模拟旧对话里助手已经说过的话。

调用图：被 3 处调用（thread_rollback_persists_marker_and_replays_cumulatively, thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay, thread_rollback_restores_cleared_reference_context_item_after_compaction）；外部调用 1 个（vec!）。

fn test_session_telemetry_without_metadata() -> SessionTelemetry

作用：创建一个不带账号等个人元数据的测试遥测对象。遥测就是记录指标和事件的工具，这里用于检查指标是否正确产生。

数据流：函数内部创建内存里的指标导出器和 MetricsClient → 创建 SessionTelemetry，并关掉用户提示记录和元数据标签 → 返回可在测试中读取指标的遥测对象。

调用关系：它被技能指标测试调用，测试用它收集线程启动时的指标，再检查描述长度、启用技能数量等统计是否正确。

调用图：调用 4 个内部函数（new, new, in_memory, new）；被 2 处调用（emit_thread_start_skill_metrics_records_description_truncated_chars_without_omitted_skills, emit_thread_start_skill_metrics_records_enabled_kept_and_truncated_values）；外部调用 2 个（default, env!）。

fn find_metric(resource_metrics: &'a ResourceMetrics, name: &str) -> &'a Metric

作用：从一包测试指标里按名字找出某个指标。找不到就直接让测试失败。

数据流：输入 ResourceMetrics 和指标名 → 遍历所有 scope 里的 metric → 找到同名指标就返回引用；找不到就 panic，让测试报错。

调用关系：它是 histogram_sum 的底层查找工具；histogram_sum 先靠它拿到指标，再读取直方图数值。

调用图：被 1 处调用（histogram_sum）；外部调用 2 个（scope_metrics, panic!）。

fn histogram_sum(resource_metrics: &ResourceMetrics, name: &str) -> u64

作用：读取某个直方图指标的总和。直方图可以理解成“分桶统计”，这里测试只关心所有值加起来是多少。

数据流：输入指标集合和指标名 → 用 find_metric 找到指标 → 确认它是浮点直方图且只有一个数据点 → 返回四舍五入后的总和数字。

调用关系：它依赖 find_metric；在指标类测试里用来把底层复杂的指标格式变成一个好比较的整数。

调用图：调用 1 个内部函数（find_metric）；外部调用 2 个（assert_eq!, panic!）。

fn skill_message(text: &str) -> ResponseItem

作用：造一条包含技能内容的用户消息。技能在这里也是以用户输入文本的形式放入历史里。

数据流：输入技能文本 → 包装成 role 为 user、content 为 InputText 的 ResponseItem → 返回这条测试消息。

调用关系：它服务于技能和应用提及解析测试，让测试可以放入一段像 <skill>...</skill> 的文本后检查解析结果。

调用图：外部调用 1 个（vec!）。

async fn regular_turn_emits_turn_started_with_trace_id_without_waiting_for_startup_prewarm()

作用：验证普通对话轮次会立刻发出“轮次已开始”事件，并带上追踪 ID，不会被启动预热卡住。追踪 ID 用来把一次请求在不同系统里的日志串起来。

数据流：先设置一个带 W3C trace 信息的父 span → 创建 session 和 turn context → 放入一个永远等不到完成的启动预热任务 → 启动普通任务 → 从事件通道读到 TurnStarted，并确认 turn_id 和 trace_id 正确，最后中止任务。

调用关系：它调用测试会话创建工具和 test_model_client_session；重点检查 Session::spawn_task 在预热未完成时仍先通知外部“轮次开始”。

调用图：调用 5 个内部函数（make_session_and_context_with_rx, test_model_client_session, new, new, install_test_tracing）；外部调用 10 个（clone, new, assert!, assert_eq!, info_span!, panic!, from_millis, now, spawn, timeout）。

async fn request_mcp_server_elicitation_auto_accepts_when_auto_deny_is_enabled()

作用：验证 MCP 服务器请求用户确认时，如果开启了自动拒绝模式，这里会直接生成一个自动接受的空响应且不发给前端。MCP 可以理解成外部工具服务器协议。

数据流：创建 session → 把 MCP elicitation 设置为 auto_deny → 构造一个表单请求 → 调用 request_mcp_server_elicitation → 得到 Accept 和空内容，同时 sent 为 false，事件通道也没有新消息。

调用关系：它直接测试 Session 处理 MCP elicitation 的分支，确保自动策略不会让界面弹出请求。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 5 个（String, assert!, assert_eq!, json!, from_value）。

async fn interrupting_regular_turn_waiting_on_startup_prewarm_emits_turn_aborted()

作用：验证普通轮次即使正在等启动预热，被用户打断时也会发出“轮次已中止”事件。这样界面不会一直以为任务还在跑。

数据流：创建 session 和一个卡住的预热任务 → 启动普通任务 → 先确认收到 TurnStarted → 调用 abort_all_tasks → 再确认收到原始标记事件和 TurnAborted，且原因、完成时间和耗时都存在。

调用关系：它和预热相关的启动测试配套，检查 Session 的中止流程能正确通知事件通道。

调用图：调用 4 个内部函数（make_session_and_context_with_rx, test_model_client_session, new, new）；外部调用 10 个（clone, new, assert!, assert_eq!, panic!, from_millis, from_secs, now, spawn, timeout）。

fn test_model_client_session() -> crate::client::ModelClientSession

作用：创建一个测试用的模型客户端会话。模型客户端会话代表一次能和模型服务通信的连接上下文。

数据流：函数内部固定一个合法线程 ID → 用 OpenAI provider 信息创建 ModelClient → 调用 new_session → 返回可用于测试的 ModelClientSession。

调用关系：它被启动预热相关测试放进异步任务里，用来模拟预热最终会产出的模型会话。

调用图：调用 3 个内部函数（new, create_openai_provider, try_from）；被 2 处调用（interrupting_regular_turn_waiting_on_startup_prewarm_emits_turn_aborted, regular_turn_emits_turn_started_with_trace_id_without_waiting_for_startup_prewarm）。

fn developer_input_texts(items: &[ResponseItem]) -> Vec<&str>

作用：从一批消息里抽出 developer 角色的所有输入文本。developer 消息通常是系统给模型的开发者指令。

数据流：输入 ResponseItem 列表 → 只保留 role 为 developer 的消息 → 展开其中 InputText 内容 → 返回字符串切片列表。

调用关系：它被初始上下文和设置更新测试使用，用来检查生成给模型的开发者指令里到底包含了哪些文字。

调用图：被 9 处调用（build_initial_context_omits_default_image_save_location_with_image_history, build_initial_context_omits_default_image_save_location_without_image_history, build_initial_context_restates_realtime_start_when_reference_context_is_missing, build_initial_context_trims_skill_metadata_from_context_window_budget, build_initial_context_uses_previous_realtime_state, build_initial_context_uses_previous_turn_settings_for_realtime_end, build_settings_update_items_emits_realtime_end_when_session_stops_being_live, build_settings_update_items_emits_realtime_start_when_session_becomes_live, build_settings_update_items_uses_previous_turn_settings_for_realtime_end）；外部调用 1 个（iter）。

fn developer_message_texts(items: &[ResponseItem]) -> Vec<Vec<&str>>

作用：按消息分组提取 developer 消息里的文本。和 developer_input_texts 不同，它保留“每条 developer 消息各有哪些文本”的层次。

数据流：输入消息列表 → 找到每条 developer 消息 → 抽出每条消息里的 InputText → 返回 Vec<Vec<&str>>，外层是一条条消息，内层是该消息的文本片段。

调用关系：它用于检查多代理提示、扩展提示片段等是否作为独立 developer 消息出现，而不是只看扁平文本。

调用图：被 6 处调用（build_initial_context_adds_multi_agent_v2_root_usage_hint_as_developer_message, build_initial_context_adds_multi_agent_v2_subagent_usage_hint_as_developer_message, build_initial_context_includes_prompt_fragments_from_extensions, build_initial_context_omits_multi_agent_v2_usage_hints_when_feature_disabled, build_initial_context_omits_multi_agent_v2_usage_hints_when_hint_disabled, build_initial_context_omits_prompt_fragments_without_extension_state）；外部调用 1 个（iter）。

fn user_input_texts(items: &[ResponseItem]) -> Vec<&str>

作用：从一批消息里抽出用户角色的输入文本。测试用它检查环境变化等内容是否被放进用户可见上下文。

数据流：输入 ResponseItem 列表 → 过滤 role 为 user 的消息 → 展开 InputText 内容 → 返回所有用户文本。

调用关系：它被设置更新相关测试调用，用来确认网络、时间等环境项该出现时出现、不该出现时不出现。

调用图：被 3 处调用（build_settings_update_items_emits_environment_item_for_network_changes, build_settings_update_items_emits_environment_item_for_time_changes, build_settings_update_items_omits_environment_item_when_disabled）；外部调用 1 个（iter）。

fn write_project_hooks(dot_codex: &Path) -> std::io::Result<()>

作用：在测试项目的 .codex 目录里写一个 hooks.json。hook 可以理解成某些事件发生时自动运行的命令。

数据流：输入 .codex 目录路径 → 创建目录 → 写入一个 SessionStart hook，命令是 echo hello from hook → 返回文件写入结果。

调用关系：它被项目 hook 信任测试调用，用来准备一个项目层 hook，再验证只有可信项目里的 hook 才会被加载。

调用图：被 2 处调用（session_start_hooks_only_load_from_trusted_project_layers, session_start_hooks_require_project_trust_without_config_toml）；外部调用 3 个（join, create_dir_all, write）。

async fn write_project_trust_config(
    codex_home: &Path,
    trusted_projects: &[(&Path, TrustLevel)],
) -> std::io::Result<()>

作用：写一份测试用的用户配置，标记哪些项目是可信的。没有信任信息时，项目 hook 不应该随便执行。

数据流：输入 codex_home 和项目信任列表 → 把每个项目路径转成配置 key，并写入 trust_level → 序列化成 config.toml → 异步写入磁盘。

调用关系：它和 write_project_hooks 一起服务于 hook 信任测试：一个准备 hook 文件，一个准备信任配置。

调用图：被 2 处调用（session_start_hooks_only_load_from_trusted_project_layers, session_start_hooks_require_project_trust_without_config_toml）；外部调用 5 个（default, iter, join, write, to_string）。

async fn preview_session_start_hooks(
    config: &crate::config::Config,
) -> std::io::Result<Vec<codex_protocol::protocol::HookRunSummary>>

作用：用给定配置预览 SessionStart hook 会运行哪些。预览只看结果，不真正执行命令。

数据流：输入 Config → 创建启用 hook 功能的 Hooks 对象 → 构造一次会话启动请求 → 返回 preview_session_start 的摘要列表。

调用关系：它是测试 hook 加载行为的便利入口，把配置层栈交给 Hooks 后检查会话启动 hook 是否会被识别。

调用图：调用 2 个内部函数（new, new）；外部调用 1 个（default）。

fn test_tool_runtime(session: Arc<Session>, turn_context: Arc<TurnContext>) -> ToolCallRuntime

作用：创建测试用的工具调用运行环境。工具运行环境把工具路由、会话、当前轮次和变更追踪器绑在一起。

数据流：输入 Session 和 TurnContext → 从 turn context 创建 ToolRouter → 创建 TurnDiffTracker 的互斥锁（一把锁，防止并发乱改）→ 返回 ToolCallRuntime。

调用关系：它被工具输出、工具取消和邮箱投递相关测试调用，为工具执行流程搭一个最小可用环境。

调用图：调用 3 个内部函数（new, from_turn_context, new）；被 4 处调用（handle_output_item_done_records_image_save_history_message, handle_output_item_done_skips_image_save_message_when_save_fails, shell_tool_cancellation_waits_for_runtime_cleanup, tool_calls_reopen_mailbox_delivery_for_current_turn）；外部调用 4 个（new, default, new, new）。

fn make_connector(id: &str, name: &str) -> AppInfo

作用：造一个测试用的应用连接器信息。连接器就是某个外部应用或服务的入口，比如 calendar。

数据流：输入 id 和 name → 填入 AppInfo 的必要字段，其他字段为空或默认可访问、已启用 → 返回 AppInfo。

调用关系：它被技能文本提及应用的测试使用，让解析函数有一份“已知应用列表”可以匹配。

调用图：外部调用 1 个（new）。

fn assistant_message_stream_parsers_can_be_seeded_from_output_item_added_text()

作用：验证助手流式解析器可以先吃一段已有文本，再继续解析后续增量，并正确识别记忆引用标签。

数据流：创建解析器 → 先 seed 文本 hello 和半截 citation 标签 → 再 parse_delta 补上标签结尾和正文 → finish 收尾 → 断言可见文本是 hello 与 world，引用是 doc1。

调用关系：它直接测试 AssistantMessageStreamParsers，确保输出项新增事件和后续增量事件之间的标签能接上。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn assistant_message_stream_parsers_seed_buffered_prefix_stays_out_of_finish_tail()

作用：验证解析器遇到半截标签前缀时，不会把这段缓存错误地在结束时当成正文吐出来。

数据流：先 seed 到 hello 和半截 <oai-mem- → 后续 delta 补完整 citation → finish 收尾 → 检查最终只有 hello 和 world 可见，引用为 doc，尾巴为空。

调用关系：它补充覆盖 AssistantMessageStreamParsers 的边界情况，防止跨片段标签污染用户可见文本。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn assistant_message_stream_parsers_seed_plan_parser_across_added_and_delta_boundaries()

作用：验证计划模式下，<proposed_plan> 标签即使被切在两段消息之间，也能被解析成计划片段。

数据流：创建 plan_mode 为 true 的解析器 → seed 一段 Intro 和半截 proposed 标签 → delta 补完整计划、步骤和 Outro → finish → 检查普通文本、计划开始、计划内容、计划结束这些片段顺序正确。

调用关系：它测试 AssistantMessageStreamParsers 的计划解析能力，保证流式输出切片不会破坏计划展示。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert!, assert_eq!）。

fn validated_network_policy_amendment_host_allows_normalized_match()

作用：验证网络策略修改里的主机名经过规范化后能正确匹配已批准主机。比如大小写、末尾点和端口不该导致误拒绝。

数据流：构造 host 为 ExAmPlE.Com.:443 的规则和 example.com 的审批上下文 → 调用 Session::validated_network_policy_amendment_host → 得到规范化后的 example.com。

调用关系：它直接测试 Session 的网络策略校验函数，确保用户批准的同一主机不会因为写法不同被当成不同目标。

调用图：外部调用 2 个（assert_eq!, validated_network_policy_amendment_host）。

fn validated_network_policy_amendment_host_rejects_mismatch()

作用：验证网络策略修改不能拿一个主机的批准去改另一个主机。这样可以防止权限被偷换。

数据流：构造 evil.example.com 的规则和 api.example.com 的审批上下文 → 调用校验函数 → 预期返回错误，并检查错误信息提到主机不匹配。

调用关系：它和正常匹配测试成对出现，固定 Session 网络审批的安全边界。

调用图：外部调用 2 个（assert!, validated_network_policy_amendment_host）。

async fn start_managed_network_proxy_applies_execpolicy_network_rules() -> anyhow::Result<()>

作用：验证启动受管网络代理时，会把执行策略里的网络允许规则应用进去。受管网络代理就是统一控制工具网络访问的本地代理。

数据流：创建 workspace-write 权限和代理规格 → 在执行策略里允许 example.com 的 HTTPS → 启动代理 → 读取当前配置 → 确认允许域名只有 example.com。

调用关系：它测试 Session::start_managed_network_proxy 如何合并执行策略，确保工具运行时能按策略访问指定域名。

调用图：调用 2 个内部函数（from_config_and_constraints, workspace_write）；外部调用 5 个（assert_eq!, empty, start_managed_network_proxy, default, default）。

async fn start_managed_network_proxy_ignores_invalid_execpolicy_network_rules() -> anyhow::Result<()>

作用：验证当管理约束要求只能使用指定域名时，执行策略里额外的网络规则会被忽略。

数据流：创建只允许 managed.example.com 的网络约束 → 执行策略另加 example.com → 启动代理 → 检查最终允许域名仍是 managed.example.com。

调用关系：它保护受管配置的优先级，确保 Session 启动代理时不会让低优先级规则绕过管理员要求。

调用图：调用 2 个内部函数（from_config_and_constraints, workspace_write）；外部调用 7 个（default, assert_eq!, empty, start_managed_network_proxy, default, default, from）。

async fn managed_network_proxy_decider_survives_full_access_start() -> anyhow::Result<()>

作用：验证即使用全访问权限启动受管网络代理，后续切回受限权限时，网络决策器仍然有效。决策器就是遇到不确定请求时负责判断放行还是拦截的组件。

数据流：用全访问权限启动代理并装入一个会计数且返回 ask 的决策器 → 重新按 workspace-write 权限应用配置 → 通过代理请求 example.com → 读取 HTTP 响应 → 确认被 403 拦截，且决策器被调用一次。

调用关系：它覆盖 Session 启动和重新应用代理配置的连续场景，防止权限模式切换后丢掉网络审批逻辑。

调用图：调用 2 个内部函数（from_config_and_constraints, workspace_write）；外部调用 14 个（clone, new, default, from_secs, from_utf8_lossy, assert!, assert_eq!, empty, start_managed_network_proxy, default (+4 more)）。

async fn new_turn_refreshes_managed_network_proxy_for_sandbox_change() -> anyhow::Result<()>

作用：验证新一轮对话改变沙箱权限时，受管网络代理配置会刷新。沙箱权限决定工具能不能访问文件和网络等资源。

数据流：先启动一个包含 .example.com 和 evil.com 的代理 → 把它塞进 session 状态 → 开启新轮次并把沙箱改成 DangerFullAccess → 再读代理配置 → 确认 evil.com 被移除，只剩要求里的 .example.com。

调用关系：它测试 Session::new_turn_with_sub_id 对权限变化的响应，确保每轮对话使用的网络规则跟当前沙箱一致。

调用图：调用 3 个内部函数（from_config_and_constraints, make_session_and_context, workspace_write）；外部调用 9 个（new, default, assert_eq!, empty, start_managed_network_proxy, default, default, from, vec!）。

async fn danger_full_access_turns_do_not_expose_managed_network_proxy() -> anyhow::Result<()>

作用：验证危险全访问模式下，新轮次不会把受管网络代理暴露给 turn context。全访问意味着不通过这套受管网络约束。

数据流：创建启用网络代理的配置，但权限设为 Disabled 全访问 → 创建 session → 开默认轮次 → 检查 turn_context.network 是空。

调用关系：它和 workspace-write 的正向测试对照，确认 Session 不会在全访问模式下错误套用代理。

调用图：调用 2 个内部函数（from_config_and_constraints, make_session_with_config）；外部调用 3 个（default, assert!, default）。

async fn danger_full_access_tool_attempts_do_not_enforce_managed_network() -> anyhow::Result<()>

作用：验证全访问模式下，工具执行尝试不会强制使用受管网络。这里用一个探针工具记录运行时收到的开关值。

数据流：定义 ProbeToolRuntime，在 run 时记录 attempt.enforce_managed_network → 创建全访问 session 且配置里有网络要求 → 新建轮次并确认没有 network → 用 ToolOrchestrator 跑探针工具 → 确认记录值是 false。

调用关系：它测试工具编排器和 Session 生成的 turn context 如何配合，确保全访问工具不会被错误加上受管网络限制。

调用图：调用 4 个内部函数（from_config_and_constraints, make_session_with_config, new, plain）；外部调用 6 个（clone, default, default, assert!, assert_eq!, default）。

async fn workspace_write_turns_continue_to_expose_managed_network_proxy() -> anyhow::Result<()>

作用：验证 workspace-write 权限下，新轮次仍然会带上受管网络代理。workspace-write 是比较受控的工作区写权限模式。

数据流：创建启用网络代理的 workspace-write 配置 → 创建 session → 开默认轮次 → 检查 turn_context.network 存在。

调用关系：它和全访问不暴露代理的测试形成对照，说明只有该受管的权限模式才会把代理交给工具。

调用图：调用 3 个内部函数（from_config_and_constraints, make_session_with_config, workspace_write）；外部调用 3 个（default, assert!, default）。

async fn user_shell_commands_do_not_inherit_managed_network_proxy() -> anyhow::Result<()>

作用：验证用户手动运行的 shell 命令不会继承受管网络代理环境变量。这样用户自己的命令不会被会话工具网络策略意外影响。

数据流：创建带受管网络代理的 session 和轮次 → 执行一个打印 HTTP_PROXY 的用户 shell 命令 → 从事件通道等到命令结束 → 确认退出码为 0，输出是 not-set。

调用关系：它测试 execute_user_shell_command 和 Session 网络环境的边界：工具可用代理，但用户独立命令不应自动套用。

调用图：调用 3 个内部函数（from_config_and_constraints, make_session_with_config_and_rx, workspace_write）；外部调用 7 个（clone, new, default, assert!, assert_eq!, execute_user_shell_command, default）。

async fn get_base_instructions_no_user_content()

作用：验证基础指令只来自模型配置，不混入用户内容。基础指令就是每次发给模型的底层行为说明。

数据流：读取内置模型列表和提示文件 → 对多个模型 slug 取出模型信息 → 把模型 base_instructions 写入 session 状态 → 调用 get_base_instructions → 确认返回文本等于模型配置里的基础指令。

调用关系：它检查 Session::get_base_instructions 的来源是否干净，避免用户内容或别的上下文污染基础提示。

调用图：调用 2 个内部函数（test_config, make_session_and_context）；外部调用 4 个（assert_eq!, bundled_models_response, include_str!, vec!）。

async fn reload_user_config_layer_updates_effective_apps_config()

作用：验证重新加载用户配置后，应用配置会反映最新文件内容。

数据流：在 codex_home 写入 config.toml，关闭 calendar 应用和破坏性功能 → 调用 reload_user_config_layer → 读取当前配置并解析 apps 表 → 确认 calendar.enabled 为 false，destructive_enabled 为 false。

调用关系：它测试 Session 运行中重载用户配置的能力，保证外部改配置文件后应用开关会更新。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 5 个（assert!, assert_eq!, deserialize, create_dir_all, write）。

async fn reload_user_config_layer_updates_base_and_selected_profile_layers()

作用：验证用户配置重载会同时更新基础配置和当前选中的 profile 配置。profile 可以理解成一套命名配置方案。

数据流：写基础 config.toml 和 work.config.toml → 构建使用 work profile 的配置并放进 session → 修改两个文件 → 调用 reload_user_config_layer → 检查当前用户配置文件仍是 profile 文件，合并结果里 model 来自 profile-new，approval_policy 来自新基础配置 never。

调用关系：它覆盖 ConfigBuilder、配置层栈和 Session 重载流程的配合，防止 profile 用户修改后不生效。

调用图：调用 3 个内部函数（without_managed_config_for_tests, without_managed_config_for_tests, make_session_and_context）；外部调用 4 个（new, assert_eq!, create_dir_all, write）。

async fn reload_user_config_layer_refreshes_hooks() -> anyhow::Result<()>

作用：验证用户配置重载后，hook 列表也会刷新，并且只有被信任的 hook 才会出现在预览里。

数据流：创建启用 hook 功能的 session → 准备一个用户 hook 配置 → 先确认当前预览为空 → 用 list_hooks 算出 hook key 和 hash，并构造带 trusted_hash 的配置写入文件 → reload_user_config_layer → 再预览 SessionStart hook，确认有 1 个。

调用关系：它测试 Session、codex_hooks 和配置层栈的联动，确保运行中信任 hook 后无需重启也能生效。

调用图：调用 1 个内部函数（make_session_with_config）；外部调用 9 个（assert!, assert_eq!, list_hooks, default, from_value, json!, create_dir_all, write, to_string）。

async fn refresh_runtime_config_refreshes_hooks() -> anyhow::Result<()>

作用：验证直接刷新运行时配置时，hook 对象也会跟着更新。这和从磁盘重载类似，但入口不同。

数据流：在 session 原始配置中启用 hook 功能 → 写入带可信 hash 的用户 hook 配置 → 先确认当前 hooks 预览为空 → load_latest_config_for_session 得到新配置 → refresh_runtime_config → 确认预览里出现 1 个 hook。

调用关系：它测试 Session::refresh_runtime_config 的副作用，确保刷新配置不只是改字段，也会重建 hooks 运行组件。

调用图：调用 2 个内部函数（load_latest_config_for_session, make_session_and_context）；外部调用 12 个（new, assert!, assert_eq!, try_from, version_for_toml, format!, from_value, json!, create_dir_all, write (+2 more)）。

async fn reload_user_config_layer_updates_effective_tool_suggest_config()

作用：验证重载用户配置会更新工具建议的禁用列表。工具建议用于决定哪些连接器或插件不应被推荐。

数据流：写入 tool_suggest.disabled_tools，其中 connector id 带空格、plugin id 正常 → 调用 reload_user_config_layer → 读取配置 → 确认 connector id 被修剪成 calendar，plugin 保持 slack@openai-curated。

调用关系：它固定用户配置到 Session 有效配置的转换行为，尤其是工具 ID 的清理规则。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 3 个（assert_eq!, create_dir_all, write）。

async fn refresh_runtime_config_updates_runtime_refreshable_fields_and_keeps_session_static_settings()

作用：验证运行时刷新只更新允许热更新的字段，同时保留会话启动时固定的设置。热更新就是不重启也能改的配置。

数据流：写入 apps 和 tool_suggest 配置 → 读取原始 session 配置 → 加载新配置后故意修改 model 和 notify → refresh_runtime_config → 确认 apps、tool_suggest 已更新，但 model 和 notify 仍保持原值。

调用关系：它测试 Session::refresh_runtime_config 的边界，防止会话中途把模型等静态设置偷偷换掉。

调用图：调用 2 个内部函数（load_latest_config_for_session, make_session_and_context）；外部调用 6 个（assert!, assert_eq!, deserialize, create_dir_all, write, vec!）。

fn collect_explicit_app_ids_from_skill_items_includes_linked_mentions()

作用：验证技能文本里用链接形式提到应用时，能收集到对应应用 ID。

数据流：准备 calendar 连接器和一条包含 $calendar(app://calendar) 的技能消息 → 调用 collect_explicit_app_ids_from_skill_items → 得到包含 calendar 的集合。

调用关系：它测试技能上下文和应用连接器的匹配逻辑，确保明确链接不会被漏掉。

调用图：外部调用 3 个（new, assert_eq!, vec!）。

fn collect_explicit_app_ids_from_skill_items_resolves_unambiguous_plain_mentions()

作用：验证技能文本里简单写 $calendar，且没有歧义时，也能解析成 calendar 应用。

数据流：准备 calendar 连接器和包含 use $calendar 的技能消息 → 传入空的技能名冲突表 → 调用解析函数 → 返回 calendar 集合。

调用关系：它补充测试非链接写法，保证用户或技能作者用简写时也能关联应用。

调用图：外部调用 3 个（new, assert_eq!, vec!）。

fn collect_explicit_app_ids_from_skill_items_skips_plain_mentions_with_skill_conflicts()

作用：验证当 $calendar 同时可能是技能名时，不会把普通提及误判成应用。这样可以避免歧义。

数据流：准备 calendar 连接器和包含 $calendar 的技能消息 → 提供一个 skill_name_counts_lower，表示 calendar 也是技能名 → 调用解析函数 → 返回空集合。

调用关系：它和无歧义解析测试配套，固定 collect_explicit_app_ids_from_skill_items 在冲突时更保守的规则。

调用图：外部调用 3 个（from, assert_eq!, vec!）。

async fn reconstruct_history_matches_live_compactions()

作用：验证从 rollout 日志重建历史时，结果和真实运行中的压缩历史一致。rollout 可以理解成保存下来的会话流水账。

数据流：创建 session 和样例 rollout → 新建一个重建用 turn → 调用 reconstruct_history_from_rollout → 比较重建 history 和预期一致，并确认 window_id 为 2。

调用关系：它测试 Session 的历史恢复算法，保证恢复旧会话时和当时在线压缩得到的历史相同。

调用图：调用 2 个内部函数（make_session_and_context, sample_rollout）；外部调用 1 个（assert_eq!）。

async fn reconstruct_history_uses_replacement_history_verbatim()

作用：验证压缩项里如果带了 replacement_history，就原样使用它，不再重新拼装。replacement_history 是压缩后用来替代旧历史的一整段记录。

数据流：构造一个 Compacted rollout 项，里面有 summary 和 stale developer instructions 组成的 replacement_history，window_id 为 42 → 调用 reconstruct_history_from_rollout → 确认 history 完全等于 replacement_history，window_id 为 42。

调用关系：它固定重建逻辑的优先级：压缩记录已经给出替代历史时，Session 不应自作主张修改。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 2 个（assert_eq!, vec!）。

async fn record_initial_history_reconstructs_resumed_transcript()

作用：验证恢复会话时，record_initial_history 会把保存的 transcript 重建进当前历史。

数据流：创建样例 rollout 和预期历史 → 调用 record_initial_history，传入 InitialHistory::Resumed → 从 session 状态读取历史 → 确认 raw_items 等于预期。

调用关系：它测试 Session 启动恢复流程，把 reconstruct_history_from_rollout 的结果真正安装到会话状态里。

调用图：调用 3 个内部函数（make_session_and_context, sample_rollout, default）；外部调用 3 个（from, assert_eq!, Resumed）。

async fn resize_all_images_prepares_failures_before_history_insertion()

作用：验证开启“调整所有图片”功能后，坏的图片数据在写入历史前会被替换成说明文字。这样历史里不会保存无法处理的脏图片。

数据流：创建启用 ResizeAllImages 的 session → 构造工具输出，包含文字、坏 base64 图片和正常 URL 图片 → record_conversation_items → 读取历史 → 确认坏图片变成“image content omitted...”文本，正常 URL 图片保留。

调用关系：它测试 Session 记录对话项前的图片预处理，防止后续历史、恢复或发送模型时再遇到坏图片。

调用图：调用 2 个内部函数（make_session_and_context_with_auth_and_config_and_rx, from_api_key）；外部调用 5 个（new, assert_eq!, ContentItems, from_ref, vec!）。

async fn resize_all_images_prepares_resumed_history_before_installing_it()

作用：验证恢复旧历史时，也会先处理坏图片再放进当前会话历史。

数据流：创建启用 ResizeAllImages 的 session → 构造一条恢复历史，包含坏 base64 图片和 keep me 文本 → record_initial_history 恢复它 → 读取历史 → 确认坏图片被替换成说明文字，文本保留。

调用关系：它补充覆盖恢复入口，确保图片清理不只发生在新记录的消息上，也发生在旧 transcript 装载时。

调用图：调用 3 个内部函数（make_session_and_context_with_auth_and_config_and_rx, from_api_key, default）；外部调用 5 个（from, new, assert_eq!, Resumed, vec!）。

fn resolve_multi_agent_version_handles_unset_and_legacy_history()

作用：验证多代理版本的推断规则。多代理版本决定会话是否以及如何支持多个代理协作。

数据流：分别构造新会话、恢复空历史、带继承版本、带 session meta、forked 历史等场景 → 调用 resolve_multi_agent_version → 检查返回 None、V1、V2 或 Disabled 是否符合预期。

调用关系：它直接测试版本解析函数，保证旧历史默认按 V1 处理，明确元数据或继承值时按规则覆盖。

调用图：调用 1 个内部函数（default）；外部调用 1 个（assert_eq!）。

async fn record_initial_history_new_defers_initial_context_until_first_turn()

作用：验证全新会话记录初始历史时，不会立刻塞入初始上下文，而是等第一轮真正需要时再做。

数据流：创建 session → 调用 record_initial_history(InitialHistory::New) → 读取历史、reference_context_item 和 previous_turn_settings → 确认历史为空，上下文项为空，上一轮设置为空。

调用关系：它测试 Session 新会话启动的懒加载行为，避免在还没开始对话时提前污染历史。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 2 个（assert!, assert_eq!）。

fn session_meta_item(
    thread_id: ThreadId,
    multi_agent_version: Option<MultiAgentVersion>,
) -> RolloutItem

作用：造一条测试用的会话元数据 rollout 项。元数据里主要放线程 ID 和多代理版本。

数据流：输入 ThreadId 和可选 MultiAgentVersion → 填进 SessionMetaLine，其他元数据用默认值，git 为空 → 返回 RolloutItem::SessionMeta。

调用关系：它被多代理版本解析测试使用，用来模拟旧 transcript 里保存过的 session meta 行。

调用图：调用 1 个内部函数（default）；外部调用 1 个（SessionMeta）。

async fn resumed_history_injects_initial_context_on_first_context_update_only()

作用：验证恢复历史后，初始上下文只会在第一次上下文更新时注入一次，不会重复追加。

数据流：恢复样例 rollout 到 session → 确认初始历史等于预期 → 第一次 record_context_updates_and_set_reference_context_item 后构造 initial_context 并追加到预期，检查历史一致 → 第二次再调用同一函数，确认历史没有变化。

调用关系：它测试恢复会话后的上下文补种流程，防止每次上下文更新都重复把初始说明塞进历史。

调用图：调用 3 个内部函数（make_session_and_context, sample_rollout, default）；外部调用 3 个（from, assert_eq!, Resumed）。

async fn record_initial_history_seeds_token_info_from_rollout()

作用：验证恢复历史时，会从 rollout 里的 token 统计事件中取最后一个有效统计值。token 是模型处理文本的大致计量单位。

数据流：在样例 rollout 后追加多个 TokenCount 事件，其中有空 info 和两个有效 info → record_initial_history 恢复 → 读取 session token_info → 确认保存的是最后一个有效的 info2。

调用关系：它测试 Session 恢复 token 计数状态的逻辑，保证恢复后界面或后续预算计算能接着旧统计走。

调用图：调用 3 个内部函数（make_session_and_context, sample_rollout, default）；外部调用 5 个（from, assert_eq!, TokenCount, Resumed, EventMsg）。

async fn recompute_token_usage_uses_session_base_instructions()

作用：这个测试确认重新计算令牌用量时，用的是会话里当前保存的基础指令，而不是模型默认指令。令牌可以粗略理解成模型读写文字时计费和限长用的小单位。

数据流：测试先创建一个会话和回合上下文，再把会话的基础指令改成一段很长的特殊文字。然后放入一条用户消息，分别按“会话指令”和“模型默认指令”估算令牌数，确认两者不同。最后调用重新计算功能，检查会话状态里记录的实际令牌数变成按会话指令算出的值。

调用关系：它通过 make_session_and_context 搭出测试场景，通过 user_message 放入聊天内容，最后直接验证 session.recompute_token_usage 的行为。这个测试保护的是令牌统计流程，避免配置被改后统计仍沿用旧规则。

调用图：调用 2 个内部函数（make_session_and_context, user_message）；外部调用 3 个（assert_eq!, assert_ne!, from_ref）。

async fn recompute_token_usage_updates_model_context_window()

作用：这个测试确认重新计算令牌用量时，也会顺手更新模型的上下文窗口大小。上下文窗口就是模型一次最多能看多少内容的容量上限。

数据流：测试先在会话状态里放一个旧的上下文窗口值 258400，再把当前回合里的模型窗口改成 128000。调用重新计算后，它读取会话保存的 token_info，确认里面的 model_context_window 已经变成新的 128000。

调用关系：它直接覆盖 session.recompute_token_usage 在更新 token_info 时的附带行为。这样后续依赖窗口大小做截断或显示的代码，不会拿到过期数据。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 2 个（assert_eq!, default）。

async fn record_token_usage_info_notifies_extension_contributors()

作用：这个测试确认每次记录令牌用量时，注册的扩展插件都会收到通知，而且能拿到会话、线程、当前回合三层数据。

数据流：测试先定义一个假的令牌记录插件，把收到的内容存进共享列表。然后创建会话，注册这个插件，并在会话级和线程级数据仓库里放入标记。接着连续记录两次令牌用量。最后检查插件收到了两条记录：第一条是首次用量，第二条是累计后的总用量，并且插件确实看到了两层标记。

调用关系：它围绕 session.record_token_usage_info 展开，模拟扩展系统里的 TokenUsageContributor。这个测试保证主流程更新用量时，不只是自己记账，也会把账单同步给外部扩展。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 7 个（clone, new, new, assert_eq!, new, new, vec!）。

async fn turn_start_lifecycle_exposes_turn_metadata_and_token_baseline()

作用：这个测试确认一个新回合开始时，扩展插件能看到回合编号、协作模式，以及回合开始前已有的令牌用量。

数据流：测试先准备一个假的“回合生命周期”插件，用来记录 on_turn_start 收到的数据。它给会话设置一份已有令牌用量，然后启动一个不会自己结束的任务。任务开始时应触发回合开始回调。最后测试中止任务，并检查插件只收到一条记录，里面包含正确的会话编号、线程编号、回合编号、协作模式和令牌基线。

调用关系：它通过 sess.spawn_task 触发真实的回合启动路径，再用 abort_all_tasks 收尾。这个测试保证扩展能在回合刚开始时拿到足够上下文，而不是等事情发生后才补通知。

调用图：调用 2 个内部函数（make_session_and_context, set_total_token_usage）；外部调用 6 个（clone, new, new, assert_eq!, new, new）。

async fn turn_error_lifecycle_exposes_error_and_stores()

作用：这个测试确认回合报错时，扩展插件能收到错误类型，也能访问会话级和线程级的数据仓库。

数据流：测试创建一个假的生命周期插件，专门记录 on_turn_error 的输入。随后给会话注册插件，并放入会话级、线程级标记。调用 emit_turn_error_lifecycle 发出一个 UsageLimitExceeded 错误后，测试检查插件记录里有正确的三层编号、回合编号、错误信息，并且能看到那些标记。

调用关系：它直接测试 session.emit_turn_error_lifecycle 这条错误通知路径。这个测试保护的是异常流程，确保出错时扩展仍能拿到完整现场。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 6 个（clone, new, new, assert_eq!, new, new）。

async fn config_change_contributor_observes_effective_config_changes()

作用：这个测试确认配置真的发生变化时，配置扩展插件能看到变化前和变化后的有效配置。

数据流：测试先注册一个配置记录插件。然后第一次通过 update_settings 改模型，插件应看到模型从旧值变新值。接着测试把用户配置文件写到磁盘，里面禁用了两个工具，再刷新运行时配置。插件应看到禁用工具列表从旧值变成清洗后的新值，比如去掉 id 两边空格。最后检查两次记录都完整且能访问数据仓库。

调用关系：它覆盖两条配置变化路径：运行中的设置更新，以及从配置文件重新加载。它把 load_latest_config_for_session、update_settings 和 refresh_runtime_config 串起来，确认最终通知的是“真正生效”的配置。

调用图：调用 2 个内部函数（load_latest_config_for_session, make_session_and_context）；外部调用 10 个（clone, new, default, new, assert_eq!, new, create_dir_all, write, new, vec!）。

async fn record_initial_history_reconstructs_forked_transcript()

作用：这个测试确认从已有线程分叉时，系统能把传入的历史记录重建成正确的聊天历史。

数据流：测试先生成一份样例 rollout。rollout 可以理解成保存在线程日志里的事件流水。然后用 InitialHistory::Forked 把它交给 record_initial_history。最后读取会话内存里的历史，确认它和预期重建结果完全一样。

调用关系：它专门测试 session.record_initial_history 对分叉历史的处理。这个功能是线程分叉能继续对话的基础。

调用图：调用 2 个内部函数（make_session_and_context, sample_rollout）；外部调用 2 个（assert_eq!, Forked）。

async fn session_configured_reports_permission_profile_for_external_sandbox() -> anyhow::Result<()>

作用：这个测试确认当会话使用外部沙盒时，对外报告的权限配置仍然明确写成“外部沙盒”，不会被错误压扁成别的权限类型。

数据流：测试启动一个模拟服务器，配置一个外部沙盒策略和对应的权限档案。构建测试会话后，它读取 session_configured 事件里的 permission_profile，确认和预期的外部权限档案一致。

调用关系：它通过 test_codex 搭建接近真实启动的会话配置流程。这个测试保护客户端看到的权限信息，避免 UI 或调用方误判沙盒能力。

调用图：调用 2 个内部函数（start_mock_server, test_codex）；外部调用 1 个（assert_eq!）。

async fn session_permission_profile_rebinds_runtime_workspace_roots() -> anyhow::Result<()>

作用：这个测试确认“工作区可写目录”这种运行时路径不会被永久写死，而是会随着会话工作区变化重新绑定。

数据流：测试先创建配置，其中旧工作区根目录被加入可写范围。它检查从配置生成的权限状态本身仍保留符号化的工作区规则，不直接写死旧路径。然后把这个状态放进会话配置，确认旧根目录当前可写。接着应用一次设置更新，把工作区根目录改成新路径。最后确认新路径可写，旧路径不再可写。

调用关系：它测试 SessionConfiguration.apply 和权限档案状态之间的配合。这个测试防止用户切换工作区后，旧目录还意外保留写权限。

调用图：调用 2 个内部函数（make_session_configuration_for_tests, new）；外部调用 7 个（default, new, assert!, default, test_path_buf, new, vec!）。

async fn fork_startup_context_then_first_turn_diff_snapshot() -> anyhow::Result<()>

作用：这个测试用快照确认：从一个已有线程分叉后，第一次请求模型时带上的上下文、审批策略变化和协作模式变化都正确。

数据流：测试先让初始线程完成一轮对话，并强制把 rollout 写到磁盘。然后用不同审批策略从这个 rollout 分叉出新线程。分叉后提交一条新用户输入，并在该回合里切到计划模式、设置新的开发者指令和审批策略。测试捕获发给模拟模型服务器的第一条请求，格式化成可读快照，再和保存的快照比对。

调用关系：它串起模拟服务器、真实提交用户输入、线程分叉和请求快照检查。这个测试更像端到端验收，保护分叉启动上下文不会悄悄改变。

调用图：调用 7 个内部函数（allow_any, default, format_labeled_requests_snapshot, mount_sse_once, sse, start_mock_server, test_codex）；外部调用 4 个（default, wait_for_event, clone_current, vec!）。

async fn record_initial_history_forked_hydrates_previous_turn_settings()

作用：这个测试确认从分叉历史恢复时，系统能从上一轮的上下文里取回模型等设置，但不会把旧对话内容直接塞进当前历史。

数据流：测试手工构造一个包含 TurnStarted、UserMessage、TurnContext、TurnComplete 的分叉 rollout，其中 TurnContext 记录了上一轮使用的模型。调用 record_initial_history 后，它检查 previous_turn_settings 已恢复为上一轮模型和实时状态；同时检查当前聊天历史为空；还检查 reference_context_item 保存了那份上一轮上下文。

调用关系：它测试 InitialHistory::Forked 的特殊恢复规则。这个规则让分叉线程知道自己继承了什么设置，但又能从干净的当前历史开始。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 3 个（assert_eq!, Forked, vec!）。

async fn thread_rollback_drops_last_turn_from_history()

作用：这个测试确认线程回滚一轮时，会从内存历史里删掉最后一轮对话，并清理上一轮设置和参考上下文。

数据流：测试先给会话接上持久化文件，再构造初始上下文、第一轮、第二轮的完整历史，并把这些内容写入 rollout。随后设置一些会过期的 previous_turn_settings 和 reference_context_item。调用 thread_rollback 回滚 1 轮后，测试等待回滚事件，检查历史只剩初始上下文加第一轮，旧设置被清空，并且持久化日志里写入了 ThreadRolledBack 标记。

调用关系：它通过 handlers::thread_rollback 走真实回滚入口，并用 wait_for_thread_rolled_back 验证对外事件。这个测试保证内存状态和磁盘日志一起被更新。

调用图：调用 5 个内部函数（thread_rollback, attach_thread_persistence, make_session_and_context_with_rx, wait_for_thread_rolled_back, get_rollout_history）；外部调用 6 个（get_mut, new, assert!, assert_eq!, panic!, vec!）。

async fn thread_rollback_clears_history_when_num_turns_exceeds_existing_turns()

作用：这个测试确认如果要求回滚的轮数超过已有对话轮数，系统不会崩溃，而是尽量回到只剩初始上下文的状态。

数据流：测试构造一个只有一轮用户消息的历史并写入持久化。然后请求回滚 99 轮。回滚完成后，它检查发出的事件仍记录请求的 99，内存历史则只保留初始上下文。

调用关系：它测试 handlers::thread_rollback 的过量回滚场景。这个边界情况很重要，因为用户或客户端可能传入比实际更多的回滚轮数。

调用图：调用 4 个内部函数（thread_rollback, attach_thread_persistence, make_session_and_context_with_rx, wait_for_thread_rolled_back）；外部调用 4 个（get_mut, new, assert_eq!, vec!）。

async fn thread_rollback_fails_without_persisted_thread_history()

作用：这个测试确认没有持久化线程历史时，线程回滚会明确失败，而不是凭空猜测该删什么。

数据流：测试创建会话但不接持久化日志，只把初始上下文记到内存历史。调用 thread_rollback 后，它等待失败事件，检查错误消息是“thread rollback requires persisted thread history”，错误类型也是 ThreadRollbackFailed，并确认内存历史没有被改动。

调用关系：它保护 handlers::thread_rollback 的前置条件：回滚必须依赖磁盘上的事件流水重放。没有这个日志，系统宁可失败也不冒险破坏历史。

调用图：调用 3 个内部函数（thread_rollback, make_session_and_context_with_rx, wait_for_thread_rollback_failed）；外部调用 1 个（assert_eq!）。

async fn thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay()

作用：这个测试确认回滚后，上一轮设置和参考上下文不是沿用旧内存值，而是从持久化日志重新播放得出。

数据流：测试手工写入两轮完整 rollout：第一轮正常，第二轮是将被回滚的轮次，并故意把当前内存历史和 previous_turn_settings 设成过期假数据。回滚 1 轮后，系统重放日志，只留下第一轮用户和助手消息。测试检查 previous_turn_settings 恢复成第一轮模型信息，reference_context_item 也恢复成第一轮上下文。

调用关系：它验证 handlers::thread_rollback 内部的“从日志重放恢复状态”机制。这个测试防止回滚后留下旧状态，导致下一轮请求带错模型或上下文。

调用图：调用 6 个内部函数（thread_rollback, assistant_message, attach_thread_persistence, make_session_and_context_with_rx, user_message, wait_for_thread_rolled_back）；外部调用 11 个（get_mut, default, new, assert_eq!, TurnComplete, TurnStarted, UserMessage, EventMsg, ResponseItem, TurnContext (+1 more)）。

async fn thread_rollback_restores_cleared_reference_context_item_after_compaction()

作用：这个测试确认如果历史曾经被压缩，回滚后会恢复到压缩后的历史窗口，并正确处理参考上下文和窗口编号。

数据流：测试写入一段 rollout：第一轮正常，接着有一次压缩，压缩项带有替换后的历史和窗口编号 7，然后第三段是将被回滚的回合。它先把内存历史设成过期内容，并设置一个过期窗口编号 99。回滚 1 轮后，测试检查历史变成压缩项里的 replacement_history，参考上下文为空，当前窗口编号结尾变成 :7。

调用关系：它测试回滚和压缩历史之间的配合。压缩像把旧账本汇总成一页摘要，这个测试确保回滚不会把账本翻回错误页。

调用图：调用 6 个内部函数（thread_rollback, assistant_message, attach_thread_persistence, make_session_and_context_with_rx, user_message, wait_for_thread_rolled_back）；外部调用 13 个（get_mut, default, new, assert!, assert_eq!, TurnComplete, TurnStarted, UserMessage, Compacted, EventMsg (+3 more)）。

async fn thread_rollback_persists_marker_and_replays_cumulatively()

作用：这个测试确认连续回滚会累计生效，并且每次回滚都会在持久化日志里留下标记。

数据流：测试写入三轮完整 rollout。然后连续调用两次 thread_rollback，每次回滚 1 轮，并分别等待成功事件。最后检查内存历史只剩第一轮的用户和助手消息；再读取 rollout 文件，统计 ThreadRolledBack 标记，确认有两个。

调用关系：它测试 handlers::thread_rollback 多次执行时的累计效果。这个测试保证日志不是只记录最后一次状态，而是保留每次回滚动作。

调用图：调用 7 个内部函数（thread_rollback, assistant_message, attach_thread_persistence, make_session_and_context_with_rx, user_message, wait_for_thread_rolled_back, get_rollout_history）；外部调用 11 个（get_mut, default, new, assert_eq!, panic!, TurnComplete, TurnStarted, UserMessage, EventMsg, ResponseItem (+1 more)）。

async fn thread_rollback_fails_when_turn_in_progress()

作用：这个测试确认当有一轮对话正在进行时，系统拒绝回滚，避免一边生成回答一边删除历史。

数据流：测试先记录初始上下文，然后手动把 active_turn 设成正在进行。调用 thread_rollback 后，它等待失败事件，确认错误类型是 ThreadRollbackFailed，并检查历史保持不变。

调用关系：它保护 handlers::thread_rollback 的并发安全。active_turn 像门口挂着“正在施工”的牌子，回滚必须等施工结束。

调用图：调用 4 个内部函数（thread_rollback, make_session_and_context_with_rx, wait_for_thread_rollback_failed, default）；外部调用 1 个（assert_eq!）。

async fn thread_rollback_fails_when_num_turns_is_zero()

作用：这个测试确认请求回滚 0 轮会被当作无效请求并失败。

数据流：测试记录初始上下文后，调用 thread_rollback，num_turns 传 0。它等待失败事件，检查错误消息是“num_turns must be >= 1”，错误类型是 ThreadRollbackFailed，并确认历史没有变化。

调用关系：它测试 handlers::thread_rollback 的输入校验。这样调用方传错参数时，系统会给出清楚错误，而不是做一个意义不明的空操作。

调用图：调用 3 个内部函数（thread_rollback, make_session_and_context_with_rx, wait_for_thread_rollback_failed）；外部调用 1 个（assert_eq!）。

async fn set_rate_limits_retains_previous_credits()

作用：这个测试确认更新限流信息时，如果新数据没带余额信息，系统会保留旧的余额和套餐信息。

数据流：测试先创建一份 SessionState，并设置一份初始 RateLimitSnapshot，其中有额度窗口、credits 余额和 plan_type 套餐。然后再设置一份更新数据，这次有新的限流窗口，但 credits 和 plan_type 为空。最后检查 state.latest_rate_limits：窗口变成新的，余额和套餐仍沿用旧的。

调用关系：它直接测试 SessionState.set_rate_limits 的合并规则。这个规则很实用，因为服务端有时只发部分字段，客户端不能因为缺字段就把余额显示清空。

调用图：调用 5 个内部函数（build_test_config, new, construct_model_info_offline_for_tests, get_model_offline_for_tests, new）；外部调用 6 个（clone, new, new, assert_eq!, from_config, tempdir）。

async fn set_rate_limits_updates_plan_type_when_present()

作用：这个测试确认更新限流信息时，如果新数据明确带了新的套餐类型，系统会采用新套餐，同时仍保留没更新的余额。

数据流：测试先设置一份初始限流快照，套餐是 Plus，余额存在。然后设置第二份快照，套餐变成 Pro，但余额为空。最后检查最新状态：限流窗口使用新值，plan_type 变成 Pro，credits 仍保留初始余额。

调用关系：它和 set_rate_limits_retains_previous_credits 互补，覆盖“字段缺失就保留”和“字段出现就更新”两种情况。核心被测对象仍是 SessionState.set_rate_limits。

调用图：调用 5 个内部函数（build_test_config, new, construct_model_info_offline_for_tests, get_model_offline_for_tests, new）；外部调用 6 个（clone, new, new, assert_eq!, from_config, tempdir）。

fn prefers_structured_content_when_present()

作用：这个测试确认 MCP 工具调用结果里如果有结构化内容，就优先把结构化内容返回给模型，而不是普通文本内容。MCP 可以理解成外部工具接入协议。

数据流：测试构造一个 McpCallToolResult：content 里放了应被忽略的文本，structured_content 里放 JSON 对象。调用 into_function_call_output_payload 后，检查输出正文是这个 JSON 对象序列化后的字符串，success 是 true。

调用关系：它测试工具结果转换函数 into_function_call_output_payload。这个规则让模型拿到机器更容易理解的结构化结果，而不是退回到文本列表。

调用图：外部调用 5 个（assert_eq!, json!, Text, to_string, vec!）。

async fn includes_timed_out_message()

作用：这个测试确认命令执行超时时，格式化给用户或模型看的输出里会明确写出超时信息。

数据流：测试构造一个 ExecToolCallOutput，里面有聚合输出“Command output”，耗时 1 秒，并标记 timed_out 为 true。调用 format_exec_output_str 后，检查结果以“command timed out after 1000 milliseconds”开头，然后跟着原命令输出。

调用关系：它测试命令工具输出的格式化逻辑。这样调用方不会只看到一段输出，却不知道命令其实是超时结束的。

调用图：调用 3 个内部函数（make_session_and_context, format_exec_output_str, new）；外部调用 3 个（from_secs, new, assert_eq!）。

async fn turn_context_with_model_updates_model_fields()

作用：这个测试确认把回合上下文切换到另一个模型时，相关字段会一起更新，而不是只改一个名字。

数据流：测试先创建会话和回合上下文，并把 reasoning_effort 设成 Minimal。然后调用 with_model 切换到 gpt-5.4。它再从模型管理器拿到这个模型的预期信息，并检查更新后的配置模型名、协作模式模型名、model_info、推理强度、配置里的推理强度、截断策略都同步到了新模型应有的值。

调用关系：它测试 TurnContext.with_model 和 models_manager 的配合。这个测试防止换模型后，仍沿用旧模型的窗口、截断或推理强度设置。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 1 个（assert_eq!）。

fn falls_back_to_content_when_structured_is_null()

作用：这个测试确认 MCP 工具结果里的 structured_content 如果只是 JSON 的 null，就当作没有结构化内容，改用普通 content。

数据流：测试构造一个 McpCallToolResult，content 里有 hello 和 world 两段文本，structured_content 是 Null。调用转换函数后，检查输出正文是 content 列表序列化后的字符串，success 是 true。

调用关系：它补充测试 into_function_call_output_payload 的降级规则。这样工具误传 null 时，系统仍能把可用文本结果交出去。

调用图：外部调用 4 个（assert_eq!, Text, to_string, vec!）。

fn success_flag_reflects_is_error_true()

作用：这个测试确认 MCP 工具结果标记 is_error 为 true 时，最终输出里的 success 会变成 false。

数据流：测试构造一个工具结果：structured_content 是错误消息 JSON，is_error 是 true。调用 into_function_call_output_payload 后，检查正文是错误 JSON 字符串，同时 success 是 false。

调用关系：它测试工具结果转换时的成功失败标记。这样上层模型或客户端不必猜正文是不是错误，可以直接看 success。

调用图：外部调用 5 个（assert_eq!, json!, Text, to_string, vec!）。

fn success_flag_true_with_no_error_and_content_used()

作用：测试一个工具调用结果在没有报错时，会被转换成“成功”的函数输出。它确认文本内容不会丢，而且成功标记会变成 true。

数据流：输入是一个假的 McpCallToolResult，里面有一段文本 alpha，is_error 明确是 false。函数把它转换成 FunctionCallOutputPayload，再手工拼出期望结果。最后比较两边是否完全一样；它不改外部状态。

调用关系：这是一个独立断言测试，专门盯住工具结果到函数输出载荷的转换规则。它借助 text_block 形状相同的 JSON 文本块，防止转换逻辑以后被改坏。

调用图：外部调用 4 个（assert_eq!, Text, to_string, vec!）。

async fn wait_for_thread_rolled_back(rx: &async_channel::Receiver<Event>) -> ThreadRolledBackEvent

作用：在异步测试里等待“线程已经回滚”的事件。它像在收件箱里等一封指定主题的信，等到了就返回。

数据流：输入是事件接收器 rx。函数最多等 2 秒，不断从 rx 收事件；如果事件消息是 ThreadRolledBack，就取出里面的回滚信息返回；其他事件会被跳过。超时或通道断开会让测试失败。

调用关系：多个线程回滚测试会调用它，先触发回滚操作，再用它确认系统真的发出了成功回滚事件。它不负责发起回滚，只负责在事件流里捞出正确结果。

调用图：调用 1 个内部函数（recv）；被 5 处调用（thread_rollback_clears_history_when_num_turns_exceeds_existing_turns, thread_rollback_drops_last_turn_from_history, thread_rollback_persists_marker_and_replays_cumulatively, thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay, thread_rollback_restores_cleared_reference_context_item_after_compaction）；外部调用 3 个（from_secs, now, timeout）。

async fn wait_for_thread_rollback_failed(rx: &async_channel::Receiver<Event>) -> ErrorEvent

作用：在异步测试里等待“线程回滚失败”的错误事件。它用于确认非法回滚场景确实失败，而不是静默成功。

数据流：输入是事件接收器 rx。函数在 2 秒内反复收事件，只接受 Error 事件，并且错误类型必须是 ThreadRollbackFailed；匹配后返回错误内容，其他事件忽略。等不到就让测试失败。

调用关系：回滚参数为 0、当前有任务进行中、没有持久化历史等失败场景会调用它。它把事件流里的失败信号交给测试继续检查。

调用图：调用 1 个内部函数（recv）；被 3 处调用（thread_rollback_fails_when_num_turns_is_zero, thread_rollback_fails_when_turn_in_progress, thread_rollback_fails_without_persisted_thread_history）；外部调用 3 个（from_secs, now, timeout）。

async fn attach_thread_persistence(session: &mut Session) -> PathBuf

作用：给测试 Session 挂上线程持久化能力，也就是让会话历史能落到本地文件里。没有它，很多回滚和重放测试就没有真实的历史文件可查。

数据流：输入是一个可修改的 Session。函数读取 Session 的配置，创建 LiveThread，填入当前目录、模型提供方、记忆模式等元信息；然后把 LiveThread 放回 Session，确保 rollout 文件被创建并刷新到磁盘。输出是当前 rollout 文件路径，同时修改了 Session 的持久化服务状态。

调用关系：需要测试历史保存、回滚、上下文重放的用例会先调用它。它把普通测试会话升级成带历史文件的会话，后续测试再基于这个文件检查系统行为。

调用图：调用 2 个内部函数（default, create）；被 9 处调用（cached_guardian_subagent_exposes_its_rollout_path, record_context_updates_and_set_reference_context_item_persists_baseline_without_emitting_diffs, record_context_updates_and_set_reference_context_item_persists_full_reinjection_to_rollout, record_context_updates_and_set_reference_context_item_persists_split_file_system_policy_to_rollout, thread_rollback_clears_history_when_num_turns_exceeds_existing_turns, thread_rollback_drops_last_turn_from_history, thread_rollback_persists_marker_and_replays_cumulatively, thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay, thread_rollback_restores_cleared_reference_context_item_after_compaction）；外部调用 6 个（clone, new, current_rollout_path, ensure_rollout_materialized, flush_rollout, get_config）。

fn text_block(s: &str) -> serde_json::Value

作用：生成一个测试用的文本 JSON 块。它让测试不用每次手写同样的 JSON 结构。

数据流：输入是一段字符串 s。函数把它包成 { type: "text", text: s } 这样的 JSON 值并返回；不读取也不修改外部状态。

调用关系：工具输出转换测试会用它造内容。它是小型测试辅助函数，保证测试数据格式统一。

调用图：外部调用 1 个（json!）。

async fn build_test_config(codex_home: &Path) -> Config

作用：创建一份适合测试用的默认配置。它把配置目录指向临时目录，避免测试污染用户真实配置。

数据流：输入是 codex_home 路径。函数用测试专用的 ConfigBuilder 构造配置，把 codex_home 写进去，然后异步加载并返回 Config；如果加载失败，测试直接失败。

调用关系：很多测试会话构造函数都会先调用它。它是测试世界里的“默认配置工厂”，让后续 Session、SessionConfiguration 都从一致的起点开始。

调用图：调用 1 个内部函数（without_managed_config_for_tests）；被 8 处调用（make_session_and_context, make_session_and_context_with_auth_config_home_and_rx, make_session_configuration_for_tests, make_session_with_config_and_rx, make_session_with_history_source_and_agent_control_and_rx, session_new_fails_when_zsh_fork_enabled_without_packaged_zsh, set_rate_limits_retains_previous_credits, set_rate_limits_updates_plan_type_when_present）；外部调用 1 个（to_path_buf）。

fn session_telemetry(
    conversation_id: ThreadId,
    config: &Config,
    model_info: &ModelInfo,
    session_source: SessionSource,
) -> SessionTelemetry

作用：为测试会话创建遥测信息。遥测就是记录会话来源、模型等统计信息，测试里用假账号和固定字段来避免依赖真实用户。

数据流：输入包括会话/线程 ID、配置、模型信息和会话来源。函数选出离线测试模型名，填入测试邮箱、认证模式、来源标识等字段，输出一个 SessionTelemetry。

调用关系：测试构造完整 Session 或 TurnContext 时会调用它。后面的事件上报和模型请求上下文会拿这份遥测信息当会话身份说明。

调用图：调用 2 个内部函数（get_model_offline_for_tests, new）；被 2 处调用（make_session_and_context, make_session_and_context_with_auth_config_home_and_rx）。

fn model_with_default_service_tier(default_service_tier: Option<&str>) -> ModelInfo

作用：造一个带服务档位信息的测试模型。服务档位可以理解成“处理优先级套餐”，比如 Fast。

数据流：输入是可选的默认服务档位字符串。函数先按 gpt-5.4 造模型信息，再把支持的档位设成 Fast，并把默认档位设成输入值。输出是 ModelInfo。

调用关系：服务档位选择规则的多组测试都用它准备模型。这样每个测试只关注“配置怎么选”，不用重复搭模型数据。

调用图：调用 1 个内部函数（model_info_from_slug）；被 6 处调用（get_service_tier_does_not_default_when_model_has_no_default, get_service_tier_does_not_use_model_default_when_absent_and_fast_mode_enabled, get_service_tier_does_not_use_model_default_when_fast_mode_disabled, get_service_tier_drops_unsupported_configured_tier_when_fast_mode_enabled, get_service_tier_ignores_configured_tier_when_fast_mode_disabled, get_service_tier_keeps_supported_explicit_tier）；外部调用 1 个（vec!）。

fn get_service_tier_does_not_use_model_default_when_absent_and_fast_mode_enabled()

作用：测试即使模型有默认 Fast 档位，只要用户没显式配置，系统也不会自动使用它。

数据流：函数先造一个默认档位为 Fast 的模型，再调用 get_service_tier，传入“没有配置档位”和“fast mode 开启”。期望输出是 None，表示请求里不带服务档位。

调用关系：它验证 get_service_tier 的一条边界规则：模型默认值不能擅自变成用户请求。它依赖 model_with_default_service_tier 准备测试模型。

调用图：调用 1 个内部函数（model_with_default_service_tier）；外部调用 1 个（assert_eq!）。

fn get_service_tier_does_not_use_model_default_when_fast_mode_disabled()

作用：测试 fast mode 关闭时，模型自带默认档位也不会被使用。

数据流：函数创建默认 Fast 的模型，调用 get_service_tier，传入没有用户配置且 fast mode 关闭。返回应为 None。

调用关系：它和前一个测试一起确认：无论 fast mode 开不开，都不会因为模型有默认档位就自动发服务档位。

调用图：调用 1 个内部函数（model_with_default_service_tier）；外部调用 1 个（assert_eq!）。

fn get_service_tier_keeps_supported_explicit_tier()

作用：测试用户明确选择了模型支持的服务档位时，系统会保留这个选择。

数据流：输入场景是模型支持 Fast，用户也配置 Fast，并且 fast mode 开启。函数调用 get_service_tier 后，期望得到 Fast 对应的请求值。

调用关系：它验证 get_service_tier 的正常路径：显式、合法、当前模式允许的配置应该被带到请求里。

调用图：调用 1 个内部函数（model_with_default_service_tier）；外部调用 1 个（assert_eq!）。

fn get_service_tier_does_not_default_when_model_has_no_default()

作用：测试模型没有默认服务档位时，系统不会自己编一个默认值。

数据流：函数造一个没有 default_service_tier 的模型，调用 get_service_tier，传入没有用户配置且 fast mode 开启。结果应为 None。

调用关系：它保护服务档位逻辑不要过度推断。模型没说默认值、用户也没说，就不发送档位。

调用图：调用 1 个内部函数（model_with_default_service_tier）；外部调用 1 个（assert_eq!）。

fn get_service_tier_drops_unsupported_configured_tier_when_fast_mode_enabled()

作用：测试 fast mode 开启时，不受模型支持的服务档位会被丢弃。这样请求不会带上后端不认识或不允许的值。

数据流：函数用一个只支持 Fast 的模型，分别传 unsupported、Flex 和 default 请求值。前两个期望返回 None，default 请求值被允许保留。

调用关系：它检查 get_service_tier 对“用户配置了但不合法”的过滤行为。这个测试防止错误档位一路传到模型服务。

调用图：调用 1 个内部函数（model_with_default_service_tier）；外部调用 1 个（assert_eq!）。

fn get_service_tier_ignores_configured_tier_when_fast_mode_disabled()

作用：测试 fast mode 关闭时，不管用户配置什么服务档位，都不会使用。

数据流：函数用同一个模型，分别传 Fast、default、unsupported 和 None。每次调用 get_service_tier 都应返回 None。

调用关系：它确认 fast mode 是服务档位生效的总开关。即使配置看起来合法，只要开关关了就不带档位。

调用图：调用 1 个内部函数（model_with_default_service_tier）；外部调用 1 个（assert_eq!）。

async fn session_settings_null_service_tier_update_uses_default_service_tier()

作用：测试设置更新里把 service_tier 传成 null 时，会被解释为“使用默认服务档位请求值”。

数据流：函数先创建测试 SessionConfiguration，再应用一个 service_tier 为 Some(None) 的更新。输出是更新后的配置；断言 service_tier 变成默认请求值。

调用关系：它直接测试 SessionConfiguration.apply 的兼容规则。客户端传 null 时，系统不是清空，而是转成约定的默认档位值。

调用图：调用 1 个内部函数（make_session_configuration_for_tests）；外部调用 2 个（default, assert_eq!）。

async fn session_settings_legacy_fast_service_tier_update_uses_priority_request_value()

作用：测试老写法 fast 会被转换成新的 Fast 请求值。这样旧客户端仍能正常工作。

数据流：函数创建测试配置，应用 service_tier 为 "fast" 的更新。结果中的 service_tier 应等于 ServiceTier::Fast 的正式请求字符串。

调用关系：它验证 SessionConfiguration.apply 的向后兼容处理。老字段进入后，会被翻译成新协议使用的值。

调用图：调用 1 个内部函数（make_session_configuration_for_tests）；外部调用 2 个（default, assert_eq!）。

async fn make_session_configuration_for_tests() -> SessionConfiguration

作用：创建一份完整的测试用 SessionConfiguration。它像给测试会话填一张“启动表”，包含模型、权限、工作目录、指令等。

数据流：函数创建临时 codex_home，加载测试配置，构造离线模型信息和协作模式，再把配置里的权限、目录、指令、人格、沙箱等级等字段整理成 SessionConfiguration 返回。

调用关系：大量测试会调用它作为起点，然后只改自己关心的字段。它内部依赖 build_test_config、离线模型信息和 Windows 沙箱配置转换。

调用图：调用 4 个内部函数（build_test_config, construct_model_info_offline_for_tests, get_model_offline_for_tests, new）；被 24 处调用（lock_contains_prompts_and_materializes_features, lock_skips_session_values_when_model_catalog_fields_are_not_saved, lock_validation_can_ignore_codex_version_mismatch, lock_validation_ignores_removed_apps_mcp_path_override, lock_validation_rejects_codex_version_mismatch_by_default, lock_validation_reports_config_diff, active_profile_update_rebuilds_network_proxy_config, emit_subagent_session_started_includes_fork_lineage_from_session_configuration, session_configuration_apply_permission_profile_accepts_direct_write_roots, session_configuration_apply_permission_profile_preserves_existing_deny_read_entries (+14 more)）；外部调用 5 个（clone, new, new, from_config, tempdir）。

async fn emit_subagent_session_started_includes_fork_lineage_from_session_configuration()

作用：测试子代理启动埋点里包含父线程 ID 和 fork 来源线程 ID。这样后台分析能看出子会话是从哪里分出来的。

数据流：函数启动一个假的 HTTP 服务器接收埋点，创建测试认证和 AnalyticsEventsClient，构造父线程、fork 来源线程、子线程，再触发 emit_subagent_session_started。随后轮询服务器收到的请求，找到 codex_thread_initialized 事件，断言里面的 parent_thread_id 和 forked_from_thread_id 正确。

调用关系：它验证埋点发送函数和 SessionConfiguration 快照之间的配合。测试不连真实网络，而是用 wiremock 假服务器收请求。

调用图：调用 6 个内部函数（new, make_session_configuration_for_tests, from_auth_for_testing, create_dummy_chatgpt_auth_for_testing, from, new）；外部调用 9 个（from_millis, from_secs, given, start, new, assert_eq!, from_slice, sleep, timeout）。

async fn resolved_environments_for_configuration(
    session_configuration: &SessionConfiguration,
) -> (Arc<EnvironmentManager>, TurnEnvironmentSnapshot)

作用：根据 SessionConfiguration 解析出测试用运行环境快照。运行环境可以理解成“这一轮命令要在哪个文件系统和 shell 里跑”。

数据流：输入是 SessionConfiguration。函数创建测试 EnvironmentManager 和 ThreadEnvironments，使用默认 shell、禁用 shell 快照，再把配置里的环境选择应用进去。输出环境管理器和当前环境快照。

调用关系：构造测试 Session 和 TurnContext 时会调用它。它把配置里的抽象环境选择，变成后续 turn 可以直接使用的环境对象。

调用图：调用 5 个内部函数（new, environment_selections, default_user_shell, disabled, default_for_tests）；被 2 处调用（make_session_and_context, make_session_and_context_with_auth_config_home_and_rx）；外部调用 3 个（clone, new, default）。

async fn session_configuration_apply_preserves_profile_file_system_policy_on_cwd_only_update()

作用：测试只改当前工作目录时，不会把权限配置里的文件系统规则弄丢。尤其是配置档案里的读写限制要继续保留。

数据流：函数先建测试配置和临时目录，设置一个工作区写权限沙箱，以及一个包含“项目根可写、docs 可读”的文件系统策略。然后只更新 cwd。输出的新配置应保留原本物化后的文件系统沙箱策略。

调用关系：它测试 SessionConfiguration.apply 在 cwd-only 更新时的权限保持逻辑。没有这个保护，换目录可能意外放宽或丢失文件访问限制。

调用图：调用 6 个内部函数（make_session_configuration_for_tests, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, restricted, from, new）；外部调用 6 个（default, new, assert_eq!, create_dir_all, tempdir, vec!）。

async fn session_configuration_apply_permission_profile_preserves_existing_deny_read_entries()

作用：测试更新权限档案时，已有的“禁止读取”规则不会被冲掉。比如禁止读 .env 文件这种安全规则必须留下。

数据流：函数先设置一个已有文件系统策略，里面加上 deny 条目和扫描深度。再用新的 permission_profile 更新配置。结果应该基于请求策略重建，但保留原来的 deny 条目和 glob_scan_max_depth。

调用关系：它验证 SessionConfiguration.apply 合并权限时的安全优先原则：新配置可以更新权限，但不能悄悄删除已有的拒绝读取规则。

调用图：调用 6 个内部函数（make_session_configuration_for_tests, from_runtime_permissions, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, new）；外部调用 5 个（default, new, new_workspace_write_policy, assert_eq!, tempdir）。

async fn session_configuration_apply_permission_profile_accepts_direct_write_roots()

作用：测试权限更新可以接受直接指定的绝对写入目录。也就是说，不一定只能写当前工作区，也能明确允许某个外部目录。

数据流：函数创建一个外部临时目录，把它作为 FileSystemSandboxPolicy 里的写入路径，再转成 PermissionProfile 应用到会话配置。结果应同时保留 permission_profile、文件系统策略，并生成包含该写入根的旧式 SandboxPolicy。

调用关系：它检查新权限模型和旧沙箱模型之间的转换。测试确保直接写入根不会在 apply 时被拒绝或误删。

调用图：调用 5 个内部函数（make_session_configuration_for_tests, from_runtime_permissions, restricted, new, from_absolute_path）；外部调用 6 个（default, new, assert_eq!, canonicalize_preserving_symlinks, tempdir, vec!）。

async fn session_configuration_apply_rebinds_symbolic_profile_to_updated_workspace_roots()

作用：测试使用符号规则“项目根”的权限档案，在工作区根目录改变后会重新绑定到新目录。

数据流：函数设置旧 workspace root，再创建一个权限策略，允许写 Special project_roots。应用更新时同时换成新 workspace root，并设置 active profile 信息。结果应允许写新根、不允许写旧根，并保存 active profile 和 profile workspace roots。

调用关系：它验证符号路径不是固定死的真实路径，而是会跟随新的 workspace_roots 重新解释。SessionConfiguration.apply 负责完成这个重绑定。

调用图：调用 4 个内部函数（new, make_session_configuration_for_tests, from_runtime_permissions, restricted）；外部调用 5 个（default, assert!, assert_eq!, tempdir, vec!）。

async fn session_configuration_apply_retargets_implicit_workspace_root_on_cwd_update()

作用：测试当当前目录改变时，隐含的工作区根会从旧目录转向新目录，同时保留额外工作区根。

数据流：函数把旧 cwd 和额外目录设为 workspace_roots，并设置允许写项目根的策略。随后只更新 cwd 到新目录。结果的 workspace_roots 应变成新目录加额外目录；权限允许写新目录和额外目录，不再允许写旧目录。

调用关系：它测试 cwd 更新和 workspace_roots 自动调整的配合。这样用户切项目后，权限会跟着新项目走，而不是还指向旧项目。

调用图：调用 4 个内部函数（make_session_configuration_for_tests, from_runtime_permissions, restricted, new）；外部调用 6 个（default, new, assert!, assert_eq!, tempdir, vec!）。

async fn active_profile_update_rebuilds_network_proxy_config() -> std::io::Result<()>

作用：测试切换活动权限档案时，网络代理配置也会重新计算。否则用户切到“允许联网并带代理”的档案，实际请求可能仍然没有代理。

数据流：函数写入一份临时 config.toml，里面有 locked-down 和 web-enabled 两个权限档案，后者带代理地址。先加载默认 locked 配置确认没有该代理，再加载选中 web-enabled 的配置。然后把测试 SessionConfiguration 从 locked 更新到 selected profile，最后检查更新后的原始配置里代理地址变成 127.0.0.1:43128 且 socks 关闭。

调用关系：它覆盖 SessionConfiguration.apply 对 active_permission_profile 的副作用：不仅权限对象要变，依赖该档案生成的网络代理配置也要同步刷新。

调用图：调用 1 个内部函数（make_session_configuration_for_tests）；外部调用 13 个（clone, new, default, assert!, assert_eq!, assert_ne!, Access, default, from, write (+3 more)）。

async fn new_default_turn_uses_config_aware_skills_for_role_overrides()

作用：测试创建新默认 turn 时，会按子角色覆盖后的配置来决定技能是否启用。turn 可以理解成一次用户请求的执行轮次。

数据流：函数先创建会话，在 codex_home 下写一个 demo 技能，并确认父配置下技能启用。接着写一个角色配置文件，把这个技能设为 disabled，再把角色应用到 child_config，并放进 Session 状态。最后创建新默认 turn，检查同一个技能仍能被发现，但启用状态变成 false。

调用关系：它验证角色配置、技能加载和 Session.new_default_turn_with_sub_id 的衔接。重点是新 turn 要看当前会话配置，而不是继续沿用旧的父配置。

调用图：调用 2 个内部函数（apply_role_to_config, make_session_and_context）；外部调用 8 个（clone, new, new, assert_eq!, skills_load_input_from_config, format!, create_dir_all, write）。

async fn session_configuration_apply_retargets_legacy_workspace_root_on_cwd_update()

作用：测试旧式 workspace-write 沙箱在 cwd 改变时，会把隐含可写根转到新 cwd。

数据流：函数设置原 cwd、workspace_roots 和旧式 WorkspaceWrite 沙箱转换出的文件系统策略。然后只把 cwd 更新到另一个项目目录。结果 workspace_roots 应只包含新项目，新项目可写，旧项目不可写。

调用关系：它保护旧配置格式的兼容行为。即使权限来自 legacy sandbox policy，SessionConfiguration.apply 也要正确迁移隐含工作区。

调用图：调用 6 个内部函数（make_session_configuration_for_tests, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, from, new）；外部调用 6 个（default, new, assert!, assert_eq!, tempdir, vec!）。

async fn session_configuration_apply_preserves_absolute_cwd_write_root_on_cwd_update()

作用：测试如果权限里明确写着旧 cwd 的绝对路径，那么改 cwd 时不能把它误当成“当前工作区”来重定向。

数据流：函数创建 repo-a 和 repo-b，把权限设成根目录可读、repo-a 绝对路径可写。然后更新 cwd 到 repo-b。结果文件系统策略必须原样保留：repo-a 仍可写，repo-b 不会因为成为新 cwd 就自动可写。

调用关系：它区分两种权限：符号工作区规则会跟 cwd 变，绝对路径规则不会。SessionConfiguration.apply 必须保持这个边界。

调用图：调用 4 个内部函数（make_session_configuration_for_tests, from_runtime_permissions_with_enforcement, restricted, new）；外部调用 7 个（default, new, assert!, assert_eq!, create_dir_all, tempdir, vec!）。

async fn session_update_settings_does_not_rewrite_sticky_environment_cwds()

作用：测试更新会话设置时，不会改写已有环境选择里“固定住”的工作目录。

数据流：函数创建会话，取出当前环境列表并保存期望值，再把会话 cwd 更新到 project，同时把原环境列表传回去。更新后检查 SessionConfiguration 的 cwd 已变，但环境列表没变；再创建下一轮 turn，确认实际 turn 仍使用原来的环境 cwd。

调用关系：它测试 Session.update_settings 和 new_default_turn 的配合。会话主 cwd 可以更新，但已有显式环境的 cwd 不能被偷偷重写。

调用图：调用 2 个内部函数（make_session_and_context, new）；外部调用 3 个（default, assert_eq!, create_dir_all）。

async fn relative_cwd_update_without_environments_resolves_under_session_cwd()

作用：测试没有显式环境列表时，更新 cwd 能正确落到会话当前目录下的目标路径，并保持环境列表为空。

数据流：函数先把 SessionConfiguration 的 environments 列表清空，记住原 cwd，创建原 cwd/project 目录。然后用 TurnEnvironmentSelections 更新到这个目录且不带环境。结果配置里的 cwd 变成该目录，环境选择仍为空。

调用关系：它检查 Session.update_settings 对“只有 cwd、没有环境”的简单路径。这个场景不能误造环境，也不能解析错目录。

调用图：调用 2 个内部函数（make_session_and_context, new）；外部调用 5 个（default, new, assert!, assert_eq!, create_dir_all）。

async fn environment_settings_preserve_explicit_primary_cwd()

作用：测试如果环境里已经明确指定了自己的 cwd，更新会话主 cwd 时不能覆盖它。

数据流：函数创建一个显式 local 环境，cwd 指向 original/environment。然后把会话主 cwd 更新到 original/project，同时带回原环境列表。结果会话 cwd 变成 project，但第一个环境的 cwd 仍是 environment。

调用关系：它和 sticky environment 测试一起保护环境选择的独立性。Session.update_settings 只该改用户要求改的主 cwd，不该改显式环境。

调用图：调用 2 个内部函数（make_session_and_context, new）；外部调用 4 个（default, assert_eq!, create_dir_all, vec!）。

async fn absolute_cwd_update_with_turn_environment_is_allowed()

作用：测试创建新 turn 时，如果同时给了绝对 cwd 和对应的显式环境，这是允许的。

数据流：函数从当前会话 cwd 下创建 absolute-turn 目录，然后调用 new_turn_with_sub_id，传入该绝对目录和一个 local 环境。返回的 TurnContext 应使用这个 cwd，配置里的 cwd 也相同，并且有一个 turn 环境。

调用关系：它验证 Session.new_turn_with_sub_id 对单轮设置更新的接受规则。明确给出环境时，绝对路径 cwd 不应被错误拒绝。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, new）；外部调用 4 个（default, assert_eq!, create_dir_all, vec!）。

async fn session_new_fails_when_zsh_fork_enabled_without_packaged_zsh()

作用：测试启用 zsh fork 功能但没有可用的打包 zsh 时，Session 启动会失败并给出清楚错误。

数据流：函数创建测试配置，打开 ShellZshFork 特性，把 zsh_path 设成 None，然后手工准备认证、模型、插件、MCP、技能、环境、线程存储等 Session::new 需要的依赖。调用 Session::new 后应得到错误；最后检查错误文本包含“没有 packaged zsh fork”。

调用关系：它覆盖 Session::new 的启动前置检查。这个测试防止系统在缺少必要 shell 组件时继续启动，之后才在执行命令时出更难懂的错误。

调用图：调用 17 个内部函数（new, new, default, new, new, build_test_config, models_manager_with_provider, default_for_tests, new, from_auth_for_testing (+7 more)）；外部调用 12 个（clone, new, new, assert!, unbounded, default, default, format!, panic!, from_config (+2 more)）。

async fn make_session_and_context() -> (Session, TurnContext)

作用：创建一套可直接用于测试的 Session 和 TurnContext。它是很多测试的“搭舞台”函数。

数据流：函数创建事件通道、临时配置、认证、模型管理器、执行策略、会话配置、环境管理器、插件/技能/MCP 管理器、模型客户端等一整套依赖。然后加载插件和技能，调用 Session::make_turn_context 生成 turn 上下文，最后手工组装 Session 并连同 TurnContext 返回。

调用关系：大量会话行为测试都会调用它，而不是自己重复造这些复杂对象。它把 build_test_config、session_telemetry、resolved_environments_for_configuration 和各种服务拼成一个完整测试会话。

调用图：调用 33 个内部函数（new, new, new_uninitialized_with_permission_profile, new, new, new, new, default, new, new (+15 more)）；被 269 处调用（process_compacted_history_with_test_session, test_review_params, build_guardian_prompt_includes_parent_turn_denied_reads, build_guardian_prompt_items_includes_parent_session_id, guardian_review_request_layout_matches_model_visible_request_snapshot, guardian_test_session_and_turn_with_base_url, routes_approval_to_guardian_allows_granular_review_policy, routes_approval_to_guardian_can_use_app_reviewer_override, routes_approval_to_guardian_requires_guardian_reviewer, hook_run_analytics_payload_falls_back_to_turn_context_id (+15 more)）；外部调用 28 个（clone, new, new, new, default, new, from, new, new, from_pointee (+15 more)）。

async fn make_session_with_config(
    mutator: impl FnOnce(&mut Config),
) -> anyhow::Result<Arc<Session>>

作用：用一个修改函数创建自定义配置的测试 Session。测试可以只写“我要怎么改配置”，不用关心底层搭建细节。

数据流：输入是 mutator，一个会修改 Config 的闭包。函数把它交给 make_session_with_config_and_rx，拿到 Session 和事件接收器后丢掉接收器，只返回 Arc<Session> 或错误。

调用关系：需要自定义配置但不关心事件流的测试会调用它。它是 make_session_with_config_and_rx 的简化包装。

调用图：调用 1 个内部函数（make_session_with_config_and_rx）；被 5 处调用（danger_full_access_tool_attempts_do_not_enforce_managed_network, danger_full_access_turns_do_not_expose_managed_network_proxy, reload_user_config_layer_refreshes_hooks, shell_tool_cancellation_waits_for_runtime_cleanup, workspace_write_turns_continue_to_expose_managed_network_proxy）。

async fn load_latest_config_for_session(session: &Session) -> Config

作用：从某个 Session 的配置目录重新加载最新配置。它用于测试运行时刷新配置是否真的读到了磁盘上的新内容。

数据流：输入是 Session 引用。函数先读取当前 Session 配置，拿到 codex_home 和 cwd，再用默认 ConfigBuilder 从这个目录重新 build 一份 Config。输出是最新加载的配置。

调用关系：配置刷新相关测试会调用它，把会话当前配置和磁盘最新配置做对照。它不修改 Session，只负责重新读配置文件。

调用图：被 3 处调用（config_change_contributor_observes_effective_config_changes, refresh_runtime_config_refreshes_hooks, refresh_runtime_config_updates_runtime_refreshable_fields_and_keeps_session_static_settings）；外部调用 2 个（default, get_config）。

async fn make_session_with_config_and_rx(
    mutator: impl FnOnce(&mut Config),
) -> anyhow::Result<(Arc<Session>, async_channel::Receiver<Event>)>

作用：创建一个测试用的 Session，并把它发出的事件接收器一起返回。测试可以传入一个小函数修改配置，用来模拟不同启动条件。

数据流：进去的是一个配置修改函数 → 它先建临时目录和测试配置，再补上假 API Key、模型信息、插件、技能、环境和线程存储等零件 → 出来的是一个可共享的会话对象，以及一个能收到会话事件的通道；它不会使用真实用户目录。

调用关系：这是测试准备工具，被 make_session_with_config 和 user_shell_commands_do_not_inherit_managed_network_proxy 这类测试拿来快速搭好会话。它最后把所有准备好的零件交给 Session::new。

调用图：调用 17 个内部函数（new, new, default, new, new, build_test_config, models_manager_with_provider, default_for_tests, new, from_auth_for_testing (+7 more)）；被 2 处调用（make_session_with_config, user_shell_commands_do_not_inherit_managed_network_proxy）；外部调用 10 个（clone, new, new, unbounded, default, default, from_config, tempdir, vec!, channel）。

async fn make_session_with_history_source_and_agent_control_and_rx(
    initial_history: InitialHistory,
    session_source: SessionSource,
    agent_control: AgentControl,
) -> anyhow::Result<(Arc<Se

作用：创建一个带“历史来源”和“代理控制信息”的测试会话。它专门服务于恢复旧会话、子代理继承会话编号这类测试。

数据流：进去的是初始历史、会话来源和代理控制设置 → 它构造临时配置，打开临时状态库，拼好模型、环境、权限、插件、技能等会话配置 → 出来的是新建好的 Session 和事件接收器；同时把传入的历史和控制信息真正塞进 Session::new。

调用关系：resumed_root_session_uses_thread_id_as_session_id 和 resumed_subagent_session_keeps_inherited_session_id 会调用它。它和前一个辅助函数很像，但重点是测试“恢复”和“继承编号”。

调用图：调用 18 个内部函数（new, new, default, new, new, build_test_config, models_manager_with_provider, default_for_tests, new, from_auth_for_testing (+8 more)）；被 2 处调用（resumed_root_session_uses_thread_id_as_session_id, resumed_subagent_session_keeps_inherited_session_id）；外部调用 10 个（clone, new, new, clone, unbounded, default, from_config, tempdir, vec!, channel）。

async fn resumed_root_session_uses_thread_id_as_session_id()

作用：确认恢复一个普通根会话时，会话编号会直接使用线程编号。这样旧对话重新打开后，对外看到的身份不会乱。

数据流：进去的是一个新生成的 thread_id，并把它放进恢复历史里 → 测试创建恢复会话，读取 session.thread_id 和 session.session_id，再接收 SessionConfigured 事件 → 断言对象内部和事件里的 thread_id、session_id 都一致。

调用关系：测试框架运行它。它通过 make_session_with_history_source_and_agent_control_and_rx 搭环境，然后检查 Session::new 发出的配置事件是否符合恢复规则。

调用图：调用 2 个内部函数（make_session_with_history_source_and_agent_control_and_rx, new）；外部调用 5 个（new, assert_eq!, default, panic!, Resumed）。

async fn resumed_subagent_session_keeps_inherited_session_id()

作用：确认恢复子代理会话时，线程编号可以是自己的，但 session_id 要继续沿用父会话的编号。这样多个子任务仍能被归到同一个上层会话下。

数据流：进去的是父线程编号、父 session_id、子线程编号和子代理来源信息 → 它创建一个恢复会话，并通过 AgentControl 传入继承的 session_id → 出来通过断言确认 thread_id 是子线程，session_id 是父会话，事件里也同样如此。

调用关系：测试框架运行它。它依赖 make_session_with_history_source_and_agent_control_and_rx 创建带子代理来源的会话，用来覆盖和根会话不同的编号规则。

调用图：调用 3 个内部函数（make_session_with_history_source_and_agent_control_and_rx, from, new）；外部调用 6 个（new, SubAgent, assert_eq!, default, panic!, Resumed）。

async fn notify_request_permissions_response_ignores_unmatched_call_id()

作用：确认如果收到一个找不到对应请求编号的权限回复，系统会忽略它。这样外部发错或过期的回复不会误开权限。

数据流：进去的是一个不存在的 call_id 和一份允许网络的权限回复 → 它让会话处理这份回复 → 出来检查当前轮次没有获得任何权限，也就是回复没有产生副作用。

调用关系：测试框架运行它。它用 make_session_and_context 建会话，然后直接调用 session.notify_request_permissions_response，检查防错行为。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 2 个（default, assert_eq!）。

async fn record_granted_request_permissions_for_turn_uses_originating_turn()

作用：确认“本轮有效”的权限会记录到最初发起申请的那一轮，而不是后来变成当前活动的那一轮。这样异步回复回来晚了，也不会记错地方。

数据流：进去的是两个不同的 ActiveTurn 和一份允许网络的权限 → 它先保存发起申请那一轮的状态，再切换当前活动轮次，然后记录权限时明确传入原始轮次状态 → 出来只有原始轮次有权限，当前轮次和会话级权限都没有。

调用关系：测试框架运行它。它直接验证 session.record_granted_request_permissions_for_turn 在异步场景下使用传入的 originating_turn_state，而不是盲目使用 session.active_turn。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 3 个（clone, default, assert_eq!）。

async fn request_permission_grants_are_environment_keyed()

作用：确认权限是按环境编号分别保存的。比如 remote 环境拿到的权限，不能自动变成本地 local 环境也有。

数据流：进去的是一份网络权限和环境名 remote → 它先按本轮范围记录，再读取 remote 和 local 的权限；随后又按整个会话范围记录 remote → 出来 remote 有权限，local 没权限，说明权限没有串环境。

调用关系：测试框架运行它。它覆盖 record_granted_request_permissions_for_turn 和 granted_session_permissions 这类读取接口，保证环境隔离。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 3 个（clone, default, assert_eq!）。

async fn enable_strict_auto_review_for_turn_uses_originating_turn()

作用：确认“严格自动审核”这个开关也会打到最初发起请求的轮次上。它和权限一样，不能因为回复晚到就影响错轮次。

数据流：进去的是原始轮次状态，以及一份 strict_auto_review 为 true 的权限回复 → 它记录这份回复 → 出来原始轮次状态里的严格自动审核标记变为开启。

调用关系：测试框架运行它。它和 record_granted_request_permissions_for_turn_uses_originating_turn 检查同一类异步归属问题，只是对象从权限变成了审核开关。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 3 个（clone, default, assert!）。

fn strict_auto_review_session_scope_grants_no_permissions()

作用：确认如果用户请求的是“整个会话范围”的严格自动审核，系统会把它规范化为不给任何权限。这样一个危险的长期授权不会被误接受。

数据流：进去的是一份网络权限，以及 scope 为 Session、strict_auto_review 为 true 的回复 → 它调用 Session::normalize_request_permissions_response 做规范化 → 出来变成空权限、本轮范围、不开启严格自动审核。

调用关系：测试框架运行它。它直接测试 Session 的回复规范化规则，不需要启动完整异步会话。

调用图：外部调用 4 个（default, assert_eq!, normalize_request_permissions_response, new）。

async fn request_permissions_emits_event_when_granular_policy_allows_requests()

作用：确认当细粒度审批策略允许工具申请权限时，系统会真的发出一个权限请求事件，并等待外部回复。

数据流：进去的是一轮会话、允许 request_permissions 的审批策略、一个申请网络权限的 call_id → 它异步调用 request_permissions_for_environment，另一边从事件通道收到 RequestPermissions 事件，再模拟外部批准 → 出来请求函数返回同一份批准回复。

调用关系：测试框架运行它。它把 session.request_permissions_for_environment、事件通道和 notify_request_permissions_response 串起来，验证完整的申请-通知-回复流程。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, default）；外部调用 11 个（clone, get_mut, new, new, from_secs, default, Granular, assert_eq!, panic!, spawn (+1 more)）。

async fn request_permissions_tool_resolves_relative_paths_against_selected_environment()

作用：确认 request_permissions 工具里的相对文件路径，会按被选中的环境目录来解释，而不是按默认目录乱拼。

数据流：进去的是一个 remote 环境，它的工作目录被改到 request-permissions-environment；工具参数里申请写入 relative.txt → 处理器把相对路径展开成 remote 环境目录下的绝对路径，并发出权限请求事件 → 测试回复批准后，工具调用正常结束。

调用关系：测试框架运行它。它通过 RequestPermissionsHandler.handle 走工具入口，验证工具层到 session 权限请求层之间的路径转换。

调用图：调用 6 个内部函数（make_session_and_context_with_rx, new, default, new, plain, from_abs_path）；外部调用 15 个（clone, get_mut, new, new, default, from_secs, Granular, assert_eq!, json!, panic! (+5 more)）。

async fn request_permissions_tool_rejects_unknown_environment_id()

作用：确认工具如果指定了不存在的环境编号，会被明确拒绝。这样模型或调用方不能对一个不存在的执行环境申请权限。

数据流：进去的是 environment_id 为 missing 的工具调用参数 → RequestPermissionsHandler.handle 查找环境失败 → 出来是一个返回给模型的错误文本：unknown turn environment id missing。

调用关系：测试框架运行它。它直接走 RequestPermissionsHandler，验证错误会以 FunctionCallError::RespondToModel 的形式返回，而不是继续发权限事件。

调用图：调用 3 个内部函数（make_session_and_context, new, plain）；外部调用 6 个（new, new, assert_eq!, json!, panic!, new）。

async fn request_permissions_response_materializes_session_cwd_grants_before_recording()

作用：确认权限回复里像“项目根目录”这种特殊路径，在记录成会话级权限前会先变成实际目录。这样后续执行时拿到的是清楚的真实路径。

数据流：进去的是申请写入 project_roots 的权限请求 → 系统发出 RequestPermissions 事件，并带上本轮 cwd → 测试模拟批准后，回复被规范化为对这个 cwd 的读写根授权，并记录到会话级权限里。

调用关系：测试框架运行它。它串起 request_permissions_for_environment、notify_request_permissions_response 和 granted_session_permissions，重点验证特殊路径落地。

调用图：调用 3 个内部函数（make_session_and_context_with_rx, default, from_read_write_roots）；外部调用 12 个（clone, get_mut, new, new, default, from_secs, Granular, assert_eq!, panic!, spawn (+2 more)）。

async fn request_permissions_is_auto_denied_when_granular_policy_blocks_tool_requests()

作用：确认细粒度审批策略禁止工具申请权限时，系统会自动拒绝，而且不打扰外部界面。这样策略关掉后不会弹出无意义的请求。

数据流：进去的是 request_permissions=false 的审批配置和一份网络权限申请 → session.request_permissions_for_environment 直接生成空权限回复 → 出来没有事件从通道发出，返回值表示本轮空授权。

调用关系：测试框架运行它。它验证审批策略在权限请求入口处生效，和允许时会发事件的测试形成对照。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, default）；外部调用 7 个（get_mut, new, new, default, Granular, assert!, assert_eq!）。

async fn submit_with_id_captures_current_span_trace_context()

作用：确认提交操作时，如果当前代码处在一个追踪 span 里，提交内容会带上这段追踪信息。追踪信息可以理解成快递单号，用来把跨模块的一次请求串起来。

数据流：进去的是一个带 W3C Trace Context 的当前 span，以及一个没有 trace 的 Submission → codex.submit_with_id 在提交前读取当前 span 的追踪上下文并填进 Submission → 出来从提交通道收到的对象带有 expected_trace。

调用关系：测试框架运行它。它构造 Codex 的提交通道，安装测试追踪，再验证 submit_with_id 会自动补 trace。

调用图：调用 2 个内部函数（make_session_and_context, install_test_tracing）；外部调用 7 个（new, assert!, assert_eq!, bounded, unbounded, info_span!, channel）。

async fn new_default_turn_captures_current_span_trace_id()

作用：确认创建默认新轮次时，会把当前追踪编号记进 TurnContext。这样一轮对话后续的日志和后台任务能和入口请求对上。

数据流：进去的是当前 span 中的 trace_id → session.new_default_turn 创建 TurnContext → 出来 turn_context.trace_id 等于当前 span 的 trace_id。

调用关系：测试框架运行它。它直接调用 session.new_default_turn，验证会话生成轮次上下文时会读取 tracing 当前上下文。

调用图：调用 2 个内部函数（make_session_and_context, install_test_tracing）；外部调用 4 个（current, assert!, assert_eq!, info_span!）。

fn submission_dispatch_span_prefers_submission_trace_context()

作用：确认分发提交时，如果 Submission 自己带了追踪信息，就优先用它，而不是用周围环境的追踪信息。

数据流：进去的是一个 ambient 外层 trace 和一个 submission 自带 trace → submission_dispatch_span 根据提交创建分发 span → 出来的 span trace_id 等于 submission 自带的 55，而不是外层的 33。

调用关系：测试框架运行它。它直接测试 submission_dispatch_span 的选择规则，保证跨服务传来的 trace 不会被本地环境覆盖。

调用图：调用 1 个内部函数（install_test_tracing）；外部调用 3 个（assert!, assert_eq!, info_span!）。

fn submission_dispatch_span_uses_debug_for_realtime_audio()

作用：确认实时音频提交使用 DEBUG 级别的追踪 span。DEBUG 是较低的日志级别，避免高频音频帧把普通日志刷爆。

数据流：进去的是一个 RealtimeConversationAudio 提交，里面有一小段假音频帧 → submission_dispatch_span 创建分发 span → 出来检查这个 span 的日志级别是 DEBUG。

调用关系：测试框架运行它。它单独验证 submission_dispatch_span 对高频实时音频这种特殊操作的降噪处理。

调用图：调用 1 个内部函数（install_test_tracing）；外部调用 2 个（assert_eq!, RealtimeConversationAudio）。

fn op_kind_for_input_and_context_ops()

作用：确认 Op 这个操作枚举能给用户输入和线程设置返回稳定的字符串类型名。这样的名字通常会被日志、指标或分发逻辑使用。

数据流：进去的是 UserInput 和 ThreadSettings 两种操作值 → 调用它们的 kind 方法 → 出来分别得到 user_input 和 thread_settings。

调用关系：测试框架运行它。它直接覆盖 Op::kind 的基础约定，防止字符串名字被误改。

调用图：外部调用 1 个（assert_eq!）。

async fn user_turn_updates_approvals_reviewer()

作用：确认用户发起一轮对话时，如果线程设置里指定了审批复核人，Session 的配置会随之更新。

数据流：进去的是一条用户文本 hello，以及 thread_settings 里 approvals_reviewer=AutoReview → handlers::user_input_or_turn 处理这次输入并应用设置 → 出来 session.state 中的 session_configuration.approvals_reviewer 变成 AutoReview。

调用关系：测试框架运行它。它走 handlers::user_input_or_turn，验证用户输入入口不仅提交内容，也会更新会话设置。

调用图：调用 3 个内部函数（user_input_or_turn, make_session_and_context_with_rx, local_selections）；外部调用 3 个（default, assert_eq!, vec!）。

async fn turn_environments_set_primary_environment()

作用：确认新一轮如果指定了环境选择，第一项会成为主环境，并且这个选择会保存给后续默认轮次继续使用。

数据流：进去的是一个 selected 目录和只包含这个目录的环境列表 → session.new_turn_with_sub_id 创建新 TurnContext → 出来该环境成为 primary，turn_context.cwd 和 config.cwd 都是 selected，并且 session 服务里保存的主环境会被默认轮次继承。

调用关系：测试框架运行它。它测试 new_turn_with_sub_id、turn_environments 服务和 new_default_turn 之间的环境传递。

调用图：调用 3 个内部函数（make_session_and_context_with_rx, new, try_from）；外部调用 4 个（default, assert!, assert_eq!, vec!）。

async fn default_turn_does_not_overlay_legacy_fallback_cwd_onto_stored_thread_environments()

作用：确认默认新轮次不会把老的兜底 cwd 强行盖到已经保存的线程环境上。这样用户之前选过的环境目录不会被旧逻辑悄悄覆盖。

数据流：进去的是服务和会话配置里已保存的 selected 环境 → session.new_default_turn 创建默认轮次 → 出来轮次仍使用 selected 作为环境 cwd 和 config.cwd，而不是回到 session 原始 cwd。

调用关系：测试框架运行它。它直接设置 turn_environments 服务和 session_configuration，然后检查 new_default_turn 是否尊重已保存环境。

调用图：调用 3 个内部函数（make_session_and_context_with_rx, local, try_from）；外部调用 3 个（assert!, assert_eq!, vec!）。

async fn default_turn_honors_empty_stored_thread_environments()

作用：确认如果保存的线程环境列表明确为空，默认新轮次也应该没有主环境。空列表不是“没设置”，而是“清空环境”。

数据流：进去的是空的环境选择，以及状态里空的 environments → session.new_default_turn 创建轮次 → 出来 primary 为 None，turn_environments 为空，但 cwd 仍保留 session 的基础 cwd 作为兼容字段。

调用关系：测试框架运行它。它验证 new_default_turn 能区分“没有环境”和“用旧 cwd 兜底”这两件事。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 3 个（new, assert!, assert_eq!）。

async fn primary_environment_uses_first_turn_environment()

作用：确认多个轮次环境存在时，主环境就是列表里的第一个。这个规则简单但重要，因为很多默认操作都依赖主环境。

数据流：进去的是已有的第一个环境，再手动追加一个 second 环境和它自己的 cwd → 调用 primary 并检查列表内容 → 出来 primary 仍是第一个环境，第二个环境的 cwd 保持为 second 路径。

调用关系：测试框架运行它。它主要验证 TurnEnvironmentSelections.primary 的约定，以及附加环境不会改变主环境。

调用图：调用 3 个内部函数（make_session_and_context, new, from_abs_path）；外部调用 2 个（clone, assert_eq!）。

async fn empty_turn_environments_clear_primary_environment()

作用：确认一轮设置里传入空环境列表，会清掉主环境。这样用户或上层系统可以明确表示本轮没有可用执行环境。

数据流：进去的是 environments=空列表 的 SessionSettingsUpdate → session.new_turn_with_sub_id 创建新轮次 → 出来 primary 为 None，环境列表为空，cwd 保持为会话基础 cwd。

调用关系：测试框架运行它。它通过 new_turn_with_sub_id 验证环境清空请求会生效，而不是被默认环境自动补回。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, new）；外部调用 4 个（default, assert!, assert_eq!, vec!）。

async fn spawn_task_turn_span_inherits_dispatch_trace_context()

作用：确认会话里启动的任务会继承提交分发时的追踪上下文。这样从外部请求到内部任务的日志能连成一条线。

数据流：进去的是一个带 trace 的提交分发 span，以及一个会记录当前 trace 的测试任务 → session.spawn_task 在该 span 中启动任务 → 出来任务捕获到的 trace_id 和提交 trace_id 一样，但 span_id 不同，说明是同一条链路里的新子步骤。

调用关系：测试框架运行它。它自定义一个 TraceCaptureTask，交给 session.spawn_task，再等 TurnComplete 事件确认任务跑完。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, install_test_tracing）；外部调用 11 个（clone, new, from_secs, assert!, assert_eq!, assert_ne!, context_from_w3c_trace_context, new, timeout, info_span! (+1 more)）。

async fn shutdown_complete_does_not_append_to_thread_store_after_shutdown()

作用：确认关闭完成后，不会再往线程存储里追加内容。关闭就像把账本合上，之后不应该再偷偷写一笔。

数据流：进去的是一个带内存线程存储的会话和已创建的 LiveThread → handlers::shutdown 执行关闭 → 出来检查线程存储只发生 create_thread 和 shutdown_thread，没有额外 append。

调用关系：测试框架运行它。它把 session 的 thread_store 换成可统计调用次数的 InMemoryThreadStore，然后验证 shutdown 的持久化行为。

调用图：调用 3 个内部函数（make_session_and_context, default, create）；外部调用 6 个（clone, new, new, assert!, assert_eq!, default）。

async fn submission_loop_channel_close_emits_thread_stop_lifecycle()

作用：确认提交通道关闭时，submission_loop 会触发线程停止生命周期回调。生命周期回调就是给插件的“线程结束通知”。

数据流：进去的是一个马上关闭的提交通道，以及注册了 on_thread_stop 的扩展记录器 → submission_loop 发现通道关闭并收尾 → 出来记录器被调用一次，并能看到会话级和线程级扩展数据。

调用关系：测试框架运行它。它构造扩展注册表，关闭 tx_sub 后调用 submission_loop，验证线程停止通知没有漏发。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 6 个（clone, new, assert_eq!, bounded, new, new）。

async fn submission_loop_channel_close_aborts_active_turn_before_thread_stop_lifecycle()

作用：确认提交通道关闭时，如果还有正在跑的轮次，会先中断轮次，再通知线程停止。顺序很重要：先停手头任务，再宣布整条线程结束。

数据流：进去的是一个永不结束的测试任务和一个关闭的提交通道 → submission_loop 收尾时先触发 turn_abort，再触发 thread_stop → 出来记录到的调用顺序正好是 turn_abort、thread_stop。

调用关系：测试框架运行它。它通过扩展记录器同时监听轮次中止和线程停止，验证 submission_loop 的关闭顺序。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 7 个（clone, new, new, assert_eq!, bounded, new, new）。

async fn shutdown_and_wait_allows_multiple_waiters()

作用：确认多个调用方可以同时等待同一次关闭完成。这样界面层或服务层重复调用关闭等待时，不会互相打架。

数据流：进去的是一个 Codex 对象和两个并发 shutdown_and_wait 调用 → 第一个发送 Shutdown 提交，后台模拟会话循环稍后结束 → 出来两个等待者都正常返回成功。

调用关系：测试框架运行它。它用一个假的 session loop handle 配合 Codex.shutdown_and_wait，验证等待关闭的共享机制。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 9 个（clone, new, from_millis, assert_eq!, bounded, unbounded, spawn, sleep, channel）。

async fn shutdown_and_wait_waits_when_shutdown_is_already_in_progress()

作用：确认关闭已经在进行时，再调用 shutdown_and_wait 会继续等到会话循环真正结束，而不是提前返回。

数据流：进去的是一个提交接收端已关闭、但 session loop 还被 oneshot 卡住的 Codex → 调用 shutdown_and_wait 后先观察它没有完成 → 再发送完成信号 → 出来等待者才成功结束。

调用关系：测试框架运行它。它模拟“关闭请求已经发不出去或已开始，但后台循环还没停”的情况，验证 shutdown_and_wait 仍以 session loop 结束为准。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 10 个（clone, new, from_millis, assert!, bounded, unbounded, spawn, channel, sleep, channel）。

async fn shutdown_and_wait_shuts_down_cached_guardian_subagent()

作用：验证父会话关闭时，缓存起来的 guardian 子代理也会一起收到关闭命令。guardian 可以理解成负责复核或守门的辅助代理。

数据流：它先创建父会话和子会话，把子会话塞进父会话的 guardian 缓存里；然后调用父 Codex 的关闭并等待；最后检查子会话的接收通道里确实来了一个 Shutdown 操作。

调用关系：这个测试用 make_session_and_context 搭测试会话，用 submission_loop 跑父会话循环，再通过 shutdown_and_wait 触发整条关闭链路，确保父子会话不会留下后台任务。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 8 个（clone, new, assert_eq!, bounded, unbounded, spawn, channel, channel）。

async fn cached_guardian_subagent_exposes_its_rollout_path()

作用：验证缓存的 guardian 子代理如果有持久化记录路径，父会话能把这个路径暴露出来。rollout path 可以理解成对话过程的保存文件位置。

数据流：它给子会话挂上线程持久化，得到一个保存路径；再把子 Codex 放进父会话的 guardian 缓存；最后读取 trunk_rollout_path，确认返回的就是子会话那条路径。

调用关系：这个测试依赖 attach_thread_persistence 制造可保存的子会话，检查 GuardianReviewSessionManager 对外提供路径的行为。

调用图：调用 2 个内部函数（attach_thread_persistence, make_session_and_context）；外部调用 6 个（new, assert_eq!, bounded, unbounded, spawn, channel）。

async fn shutdown_and_wait_shuts_down_tracked_ephemeral_guardian_review()

作用：验证临时登记的 guardian review 会话也会在父会话关闭时被关掉。ephemeral 的意思是临时的、不长期缓存的。

数据流：它创建父子两个会话，把子 Codex 登记成临时 guardian review；父会话执行 shutdown_and_wait 后，子会话通道应收到 Shutdown；测试用一次性信号确认这件事发生了。

调用关系：它和缓存 guardian 的关闭测试相似，但走的是 register_ephemeral_for_test 这条登记路径，覆盖另一种子代理生命周期。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 8 个（clone, new, assert_eq!, bounded, unbounded, spawn, channel, channel）。

async fn make_session_and_context_with_auth_and_config_and_rx(
    auth: CodexAuth,
    dynamic_tools: Vec<DynamicToolSpec>,
    configure_config: F,
) -> (
    Arc<Session>,
    Arc<TurnContext>,

作用：这是测试用的便捷工厂，用指定认证、动态工具和配置改动，快速造出一个会话、一个轮次上下文和一个事件接收器。

数据流：输入认证信息、动态工具列表和一个修改配置的函数；它先创建临时 codex_home 目录；再把这些交给更底层的 make_session_and_context_with_auth_config_home_and_rx；输出可共享的 Session、TurnContext 和事件 Receiver。

调用关系：很多测试不想关心目录准备细节，所以会调用它；它把真正繁琐的组装工作转交给 make_session_and_context_with_auth_config_home_and_rx。

调用图：调用 1 个内部函数（make_session_and_context_with_auth_config_home_and_rx）；被 5 处调用（build_initial_context_omits_multi_agent_v2_usage_hints_when_hint_disabled, make_multi_agent_v2_usage_hint_test_session, make_session_and_context_with_dynamic_tools_and_rx, resize_all_images_prepares_failures_before_history_insertion, resize_all_images_prepares_resumed_history_before_installing_it）；外部调用 1 个（tempdir）。

async fn make_session_and_context_with_auth_config_home_and_rx(
    auth: CodexAuth,
    dynamic_tools: Vec<DynamicToolSpec>,
    codex_home: &Path,
    configure_config: F,
) -> (
    Arc<Session>,

作用：这是本段测试里最完整的会话搭建器，用来模拟一个足够真实、但不需要联网的测试会话。

数据流：它接收认证、动态工具、测试目录和配置修改函数；内部创建配置、认证管理器、模型信息、服务集合、环境、插件、技能、事件通道和会话状态；最后返回一个可运行的 Session、对应的 TurnContext，以及用来观察事件的接收器。

调用关系：它是多个测试辅助函数的底座；上层工厂只包装参数，它负责把 Session::make_turn_context、SessionServices、模型客户端、技能加载等零件装成一台测试用会话机器。

调用图：调用 32 个内部函数（new, new, new_uninitialized_with_permission_profile, new, new, new, new, default, new, new (+15 more)）；被 1 处调用（make_session_and_context_with_auth_and_config_and_rx）；外部调用 26 个（clone, new, new, new, default, new, from, new, from_pointee, from (+15 more)）。

async fn make_session_and_context_with_dynamic_tools_and_rx(
    dynamic_tools: Vec<DynamicToolSpec>,
) -> (
    Arc<Session>,
    Arc<TurnContext>,
    async_channel::Receiver<Event>,
)

作用：这是更简单的测试工厂，专门用来创建带动态工具的默认测试会话。

数据流：输入动态工具列表；它使用固定的测试 API Key 和默认配置；输出 Session、TurnContext 和事件接收器。

调用关系：它调用 make_session_and_context_with_auth_and_config_and_rx，供需要事件通道或动态工具的测试复用。

调用图：调用 2 个内部函数（make_session_and_context_with_auth_and_config_and_rx, from_api_key）；被 4 处调用（make_session_and_context_with_rx, assert_failed_apply_patch_tracks_committed_delta, invalidation_emits_empty_turn_diff, net_zero_patch_emits_empty_turn_diff）。

async fn make_session_and_context_with_rx() -> (
    Arc<Session>,
    Arc<TurnContext>,
    async_channel::Receiver<Event>,
)

作用：这是最常用的测试工厂之一，用默认设置创建会话并额外返回事件接收器。

数据流：它不接收业务参数；内部传入空的动态工具列表；返回 Session、TurnContext 和事件 Receiver。

调用关系：许多测试只需要一个普通会话和事件流时会调用它，它再委托给 make_session_and_context_with_dynamic_tools_and_rx。

调用图：调用 1 个内部函数（make_session_and_context_with_dynamic_tools_and_rx）；被 68 处调用（delegated_mcp_guardian_abort_returns_synthetic_decline_answer, delegated_mcp_user_reviewer_returns_none_without_metadata, forward_events_cancelled_while_send_blocked_shuts_down_delegate, forward_ops_preserves_submission_trace_context, handle_exec_approval_uses_call_id_for_guardian_review_and_approval_id_for_reply, handle_request_permissions_uses_tool_call_id_for_round_trip, run_codex_thread_interactive_respects_pre_cancelled_spawn, test_review_session, cancelled_guardian_review_emits_terminal_abort_without_warning, guardian_review_surfaces_responses_api_errors_in_rejection_reason (+15 more)）；外部调用 1 个（new）。

async fn refresh_mcp_servers_is_deferred_until_next_turn()

作用：验证 MCP 服务器刷新请求不会立刻打断当前状态，而是等到下一轮处理时才执行。MCP 是一种让模型调用外部工具的协议。

数据流：它先取旧的启动取消令牌，手动放入一份待刷新配置；确认旧令牌还没取消；调用 refresh_mcp_servers_if_requested 后，旧令牌应被取消，待刷新配置被清空，并生成新的未取消令牌。

调用关系：这个测试直接检查 Session 的延迟刷新入口，确保配置变更被排队到下一轮，而不是随手立即执行。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 3 个（assert!, json!, to_value）。

async fn spawn_task_does_not_update_previous_turn_settings_for_non_run_turn_tasks()

作用：验证启动非正式“运行一轮”的任务时，不会误改上一轮对话设置。

数据流：它把 previous_turn_settings 设为空，启动一个永不结束的普通任务，然后中断所有任务；最后确认 previous_turn_settings 仍然是空。

调用关系：它通过 spawn_task 和 abort_all_tasks 覆盖任务生命周期，防止后台任务污染真正轮次的状态记录。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 3 个（clone, assert_eq!, vec!）。

async fn build_settings_update_items_emits_environment_item_for_network_changes()

作用：验证网络权限变化时，会生成一段新的环境上下文给模型看。

数据流：它从旧上下文复制出新上下文，往配置层里加入允许和拒绝的域名；调用 build_settings_update_items；最后从生成的用户文本里确认出现了包含允许 api.example.com、拒绝 blocked.example.com 的 network 片段。

调用关系：它检查 Session 的设置差异生成逻辑，确保网络约束变化能被传给后续模型请求。

调用图：调用 4 个内部函数（new, new, make_session_and_context, user_input_texts）；外部调用 4 个（new, default, assert!, from）。

async fn environment_context_uses_session_shell_when_environment_shell_is_absent()

作用：验证环境自己没声明 shell 时，会退回使用会话级别的 shell；如果环境声明了 shell，则优先用环境自己的。

数据流：它把会话 shell 设成 PowerShell，并清空各环境的 shell；渲染环境上下文后应看到 powershell；再给主环境设置 cmd，重新渲染后应看到 cmd。

调用关系：它测试 EnvironmentContext::from_turn_context 的取值优先级，避免模型收到错误的命令行环境说明。

调用图：调用 2 个内部函数（from_turn_context, make_session_and_context）；外部调用 3 个（new, from, assert!）。

async fn build_settings_update_items_emits_environment_item_for_time_changes()

作用：验证日期或时区变化时，会生成环境上下文更新。

数据流：它在新上下文里设置 current_date 和 timezone；调用 build_settings_update_items；最后确认生成文本包含对应日期和时区标签。

调用关系：它覆盖设置差异里的时间信息分支，保证模型能知道当前时间背景变了。

调用图：调用 2 个内部函数（make_session_and_context, user_input_texts）；外部调用 2 个（new, assert!）。

async fn build_settings_update_items_omits_environment_item_when_disabled()

作用：验证配置关闭环境上下文后，即使环境信息变化，也不会再生成环境上下文。

数据流：它把 include_environment_context 设为 false，并改动日期；调用 build_settings_update_items；最后确认所有用户文本都不含 environment_context。

调用关系：它检查配置开关是否真正控制了 Session 的上下文注入行为。

调用图：调用 2 个内部函数（make_session_and_context, user_input_texts）；外部调用 2 个（new, assert!）。

async fn build_settings_update_items_emits_realtime_start_when_session_becomes_live()

作用：验证会话从非实时变成实时状态时，会生成一条开发者提示告诉模型实时对话开始了。

数据流：它把当前上下文的 realtime_active 设为 true；构建设置更新；最后在开发者文本里查找 realtime_conversation 标记。

调用关系：它测试 build_settings_update_items 对实时状态从关到开的差异处理。

调用图：调用 2 个内部函数（developer_input_texts, make_session_and_context）；外部调用 2 个（new, assert!）。

async fn build_settings_update_items_emits_realtime_end_when_session_stops_being_live()

作用：验证实时会话结束时，会生成一条说明结束原因的开发者提示。

数据流：它让旧上下文处于实时状态，新上下文变成非实时；构建更新项；最后确认开发者文本里有 Reason: inactive。

调用关系：它覆盖实时状态从开到关的差异处理，和实时开始测试形成一对。

调用图：调用 2 个内部函数（developer_input_texts, make_session_and_context）；外部调用 1 个（assert!）。

async fn build_settings_update_items_uses_previous_turn_settings_for_realtime_end()

作用：验证当前参考上下文里缺少实时状态时，系统还能用 previous_turn_settings 判断实时会话已经结束。

数据流：它把旧上下文项的 realtime_active 清空，但在会话里记录上一轮 realtime_active 为 true；当前上下文为 false；构建更新后应看到结束提示。

调用关系：它检查 build_settings_update_items 不只依赖上下文项，也会参考 Session 保存的上一轮设置。

调用图：调用 2 个内部函数（developer_input_texts, make_session_and_context）；外部调用 1 个（assert!）。

async fn build_initial_context_uses_previous_realtime_state()

作用：验证初始上下文会说明当前实时状态，但在恢复已有参考上下文时不会重复说明。

数据流：它先把 turn_context 标成实时并构建初始上下文，确认有 realtime_conversation；再把同样的上下文项存成参考基线；重新构建时确认不再重复出现该提示。

调用关系：它测试 build_initial_context 和 SessionState 里的 reference context 如何配合，避免重复给模型塞相同信息。

调用图：调用 2 个内部函数（developer_input_texts, make_session_and_context）；外部调用 1 个（assert!）。

async fn make_multi_agent_v2_usage_hint_test_session(
    enable_multi_agent_v2: bool,
) -> (Arc<Session>, Arc<TurnContext>)

作用：这是多代理 v2 使用提示相关测试的专用工厂。

数据流：输入是否启用 MultiAgentV2；它创建默认会话，并按需打开功能开关，同时写入根代理提示和子代理提示文本；输出 Session 和 TurnContext。

调用关系：后面的多代理提示测试都通过它准备统一环境，减少重复配置代码。

调用图：调用 2 个内部函数（make_session_and_context_with_auth_and_config_and_rx, from_api_key）；被 3 处调用（build_initial_context_adds_multi_agent_v2_root_usage_hint_as_developer_message, build_initial_context_adds_multi_agent_v2_subagent_usage_hint_as_developer_message, build_initial_context_omits_multi_agent_v2_usage_hints_when_feature_disabled）；外部调用 1 个（new）。

fn contribute(
        &'a self,
        _session_store: &'a codex_extension_api::ExtensionData,
        thread_store: &'a codex_extension_api::ExtensionData,
    ) -> std::pin::Pin<
        Box<dyn s

作用：这是一个测试用扩展贡献者，用来模拟扩展往提示词里加一段开发者规则。

数据流：它读取线程级扩展数据；如果里面有 PromptExtensionTestState，就返回一个内容为 prompt extension enabled 的开发者提示片段；否则返回空列表。

调用关系：prompt_extension_test_registry 会注册它，随后初始上下文相关测试用它验证扩展提示是否按状态出现。

调用图：外部调用 1 个（pin）。

fn prompt_extension_test_registry() -> Arc<codex_extension_api::ExtensionRegistry<crate::config::Config>>

作用：创建一个只包含测试提示贡献者的扩展注册表。

数据流：它新建扩展注册表构建器，注册 PromptExtensionTestContributor，然后构建并包进 Arc 共享指针里返回。

调用关系：扩展提示的两个测试会把它塞到 session.services.extensions 中，用来替换默认扩展系统。

调用图：调用 1 个内部函数（new）；被 2 处调用（build_initial_context_includes_prompt_fragments_from_extensions, build_initial_context_omits_prompt_fragments_without_extension_state）；外部调用 1 个（new）。

async fn build_initial_context_includes_prompt_fragments_from_extensions()

作用：验证当扩展状态存在时，初始上下文会包含扩展贡献的开发者提示。

数据流：它给会话装上测试扩展注册表，并在线程扩展数据里插入状态；构建初始上下文；最后确认开发者消息里有 prompt extension enabled。

调用关系：它把 prompt_extension_test_registry 和 PromptExtensionTestContributor 串起来，检查 build_initial_context 会收集扩展提示片段。

调用图：调用 3 个内部函数（developer_message_texts, make_session_and_context, prompt_extension_test_registry）；外部调用 1 个（assert!）。

async fn build_initial_context_omits_prompt_fragments_without_extension_state()

作用：验证没有扩展状态时，扩展贡献者不会凭空添加提示。

数据流：它只安装测试扩展注册表，但不插入 PromptExtensionTestState；构建初始上下文；最后确认开发者消息里没有 prompt extension enabled。

调用关系：它和“包含扩展提示”的测试配对，证明扩展提示受线程状态控制。

调用图：调用 3 个内部函数（developer_message_texts, make_session_and_context, prompt_extension_test_registry）；外部调用 1 个（assert!）。

async fn build_initial_context_adds_multi_agent_v2_root_usage_hint_as_developer_message()

作用：验证启用多代理 v2 且当前是根线程时，会加入根代理使用提示。

数据流：它创建启用 MultiAgentV2 的测试会话；构建初始上下文；最后确认开发者消息有 Root guidance，且没有 Subagent guidance。

调用关系：它使用 make_multi_agent_v2_usage_hint_test_session，检查 build_initial_context 对根代理场景的分支。

调用图：调用 2 个内部函数（developer_message_texts, make_multi_agent_v2_usage_hint_test_session）；外部调用 1 个（assert!）。

async fn build_initial_context_adds_multi_agent_v2_subagent_usage_hint_as_developer_message()

作用：验证启用多代理 v2 且当前是子代理线程时，会加入子代理使用提示。

数据流：它创建启用功能的会话，把 session_source 改成 SubAgent；构建初始上下文；最后确认只出现 Subagent guidance，不出现 Root guidance。

调用关系：它手动调整 Session 状态和 TurnContext，让 build_initial_context 走子代理路径。

调用图：调用 4 个内部函数（developer_message_texts, make_multi_agent_v2_usage_hint_test_session, try_from, new）；外部调用 3 个（get_mut, SubAgent, assert!）。

async fn build_initial_context_omits_multi_agent_v2_usage_hints_when_feature_disabled()

作用：验证多代理 v2 功能没打开时，不会加入任何多代理使用提示。

数据流：它创建未启用 MultiAgentV2 的测试会话；构建初始上下文；最后确认根提示和子提示都没有出现。

调用关系：它和启用功能的两个测试形成对照，保证功能开关有效。

调用图：调用 2 个内部函数（developer_message_texts, make_multi_agent_v2_usage_hint_test_session）；外部调用 1 个（assert!）。

async fn build_initial_context_omits_multi_agent_v2_usage_hints_when_hint_disabled()

作用：验证即使多代理 v2 功能打开，只要 usage hint 开关关闭，也不会加入使用提示。

数据流：它创建会话时启用 MultiAgentV2，但把 multi_agent_v2.usage_hint_enabled 设为 false，并配置两种提示文本；构建初始上下文后确认两者都没有出现。

调用关系：它直接使用通用会话工厂改配置，覆盖“功能开但提示关闭”的细分开关。

调用图：调用 3 个内部函数（developer_message_texts, make_session_and_context_with_auth_and_config_and_rx, from_api_key）；外部调用 2 个（new, assert!）。

async fn build_initial_context_omits_default_image_save_location_with_image_history()

作用：验证即使历史里已有图片生成记录，初始上下文也不会再塞默认图片保存位置说明。

数据流：它把一条已完成的 ImageGenerationCall 放进历史；构建初始上下文；最后确认开发者文本不含 Generated images are saved to。

调用关系：它保护图片相关提示不要在初始上下文里重复或过度出现。

调用图：调用 2 个内部函数（developer_input_texts, make_session_and_context）；外部调用 2 个（assert!, vec!）。

async fn build_initial_context_omits_default_image_save_location_without_image_history()

作用：验证没有图片历史时，初始上下文同样不会出现默认图片保存位置说明。

数据流：它创建普通会话并直接构建初始上下文；读取开发者文本；确认不含 Generated images are saved to。

调用关系：它和有图片历史的测试一起确认该默认说明已经不会由 build_initial_context 注入。

调用图：调用 2 个内部函数（developer_input_texts, make_session_and_context）；外部调用 1 个（assert!）。

async fn build_initial_context_trims_skill_metadata_from_context_window_budget()

作用：验证技能说明太多、模型上下文窗口太小时，初始上下文会把技能元数据裁掉，而且不会把预算警告直接塞给模型。

数据流：它给 turn_context 放入两个技能，并把模型上下文窗口设得很小；构建初始上下文；最后确认开发者文本里既没有预算超限警告，也没有技能条目。

调用关系：它检查 build_initial_context 和 build_available_skills 的配合，确保给模型看的内容被预算限制住。

调用图：调用 3 个内部函数（developer_input_texts, make_session_and_context, new）；外部调用 4 个（new, assert!, default, vec!）。

fn emit_thread_start_skill_metrics_records_enabled_kept_and_truncated_values()

作用：验证线程开始时渲染技能，如果预算太小，会正确记录“启用多少、保留多少、截断多少”等指标。

数据流：它创建测试遥测对象和一个技能，用 1 个字符的预算渲染技能；得到超预算警告；再读取指标快照，确认启用为 1、保留为 0、截断为 1、描述截断字符数为 4。

调用关系：它直接调用 build_available_skills，并通过 SkillRenderSideEffects::ThreadStart 检查遥测打点。

调用图：调用 1 个内部函数（test_session_telemetry_without_metadata）；外部调用 4 个（assert_eq!, default, Characters, vec!）。

fn emit_thread_start_skill_metrics_records_description_truncated_chars_without_omitted_skills()

作用：验证没有遗漏技能、只是描述被缩短时，也会记录被截掉的描述字符数。

数据流：它创建两个带描述的技能，计算刚好容纳技能行但放不下完整描述的预算；渲染后确认遗漏数量为 0、描述截断字符数为 8；再检查指标里截断技能数为 0、描述截断字符数为 8。

调用关系：它补充覆盖 build_available_skills 的另一种裁剪情况：技能还在，但说明变短了。

调用图：调用 1 个内部函数（test_session_telemetry_without_metadata）；外部调用 5 个（assert_eq!, default, Characters, test_path_buf, vec!）。

async fn build_initial_context_emits_thread_start_skill_warning_on_repeated_builds()

作用：验证初始上下文反复构建时，技能预算超限警告每次都会通过事件发出去。

数据流：它创建带事件接收器的会话，设置两个技能和很小的上下文窗口；第一次 build_initial_context 后从事件通道收到警告；第二次再构建后也应再次收到同样警告。

调用关系：它把 build_initial_context、事件通道和技能预算警告连起来，确认警告不是只发一次。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, new）；外部调用 7 个（into_inner, new, from_secs, assert!, default, timeout, vec!）。

async fn handle_output_item_done_records_image_save_history_message()

作用：验证图片生成结果保存成功时，历史里会先记录一条“图片保存在哪里”的说明，再记录图片生成项本身。

数据流：它准备一个 base64 结果为 foo 的图片生成项，调用 handle_output_item_done；之后读取会话历史，确认有保存说明和原始图片项；再检查磁盘上确实写出了内容为 foo 的文件。

调用关系：它通过 HandleOutputCtx 调用输出处理逻辑，覆盖图片生成完成后的保存和历史记录流程。

调用图：调用 6 个内部函数（into, new, make_session_and_context, test_tool_runtime, image_generation_artifact_path, new）；外部调用 6 个（clone, new, new, assert_eq!, remove_file, vec!）。

async fn handle_output_item_done_skips_image_save_message_when_save_fails()

作用：验证图片保存失败时，不会把“保存位置”说明写进历史，但图片生成项本身仍然会完成记录。

数据流：它构造一个无法正确解码的图片结果，调用 handle_output_item_done；之后检查历史只有原始图片项，并确认预期保存路径不存在。

调用关系：它和保存成功测试配对，确认错误情况下不会向用户或模型留下假的保存说明。

调用图：调用 4 个内部函数（make_session_and_context, test_tool_runtime, image_generation_artifact_path, new）；外部调用 7 个（clone, new, new, assert!, assert_eq!, remove_file, vec!）。

async fn build_initial_context_uses_previous_turn_settings_for_realtime_end()

作用：验证构建初始上下文时，也能根据上一轮设置判断实时会话已经结束。

数据流：它把 previous_turn_settings 设为上一轮 realtime_active 为 true，而当前 turn_context 默认非实时；构建初始上下文；最后确认开发者文本包含 Reason: inactive。

调用关系：它覆盖 build_initial_context 使用 previous_turn_settings 的路径，和设置更新里的实时结束测试相呼应。

调用图：调用 2 个内部函数（developer_input_texts, make_session_and_context）；外部调用 1 个（assert!）。

async fn build_initial_context_restates_realtime_start_when_reference_context_is_missing()

作用：验证没有参考上下文时，即使上一轮设置也说实时已开启，初始上下文仍会重新说明当前实时正在进行。

数据流：它把当前 turn_context 标为实时，也把 previous_turn_settings 标为实时；构建初始上下文；最后确认仍包含 realtime_conversation。

调用关系：它确保 build_initial_context 在缺少 reference context 的恢复场景下不会漏掉实时状态说明。

调用图：调用 2 个内部函数（developer_input_texts, make_session_and_context）；外部调用 1 个（assert!）。

fn file_system_policy_with_unreadable_glob(turn_context: &TurnContext) -> FileSystemSandboxPolicy

作用：这是测试辅助函数，用来基于当前轮次的文件系统沙盒策略，再额外加一条禁止读取 .env 文件的通配规则。

数据流：输入 TurnContext；它先从旧式沙盒策略转换出新的 FileSystemSandboxPolicy；再把当前目录下所有 .env 文件的 GlobPattern 加成 Deny；返回修改后的策略。

调用关系：后面的权限和 rollout 持久化测试用它制造一个“和默认策略不同”的文件系统策略。

调用图：调用 2 个内部函数（sandbox_policy, from_legacy_sandbox_policy_for_cwd）；被 2 处调用（record_context_updates_and_set_reference_context_item_persists_split_file_system_policy_to_rollout, turn_context_item_stores_split_file_system_sandbox_policy_when_different）；外部调用 1 个（format!）。

async fn turn_context_item_uses_turn_context_comp_hash_snapshot()

作用：验证 TurnContext 转成可保存的上下文项时，使用的是 TurnContext 自己保存的 comp_hash 快照，而不是模型信息里的值。

数据流：它分别给 turn_context.comp_hash 和 turn_context.model_info.comp_hash 设置不同字符串；转换成 turn_context_item；确认结果取的是 turn-context-hash。

调用关系：它检查 TurnContext::to_turn_context_item 的字段来源，防止恢复上下文时用错版本指纹。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 1 个（assert_eq!）。

async fn turn_context_item_omits_legacy_equivalent_file_system_sandbox_policy()

作用：验证如果文件系统沙盒策略和旧权限配置等价，就不在上下文项里额外存一份策略。

数据流：它创建默认会话并转换 TurnContext；确认 file_system_sandbox_policy 是 None，同时 permission_profile 正常保存。

调用关系：它让 to_turn_context_item 避免存重复数据，只在需要时记录拆分后的文件系统策略。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 1 个（assert_eq!）。

async fn turn_context_item_stores_split_file_system_sandbox_policy_when_different()

作用：验证文件系统沙盒策略和默认权限不一样时，上下文项会明确保存这份单独策略。

数据流：它用 file_system_policy_with_unreadable_glob 生成额外拒绝 .env 的策略，并把 permission_profile 更新成使用该策略；转换上下文项后，确认其中保存了这份文件系统策略和权限配置。

调用关系：它和省略等价策略的测试配对，确认 to_turn_context_item 只在策略有差异时写入。

调用图：调用 3 个内部函数（file_system_policy_with_unreadable_glob, make_session_and_context, from_runtime_permissions_with_enforcement）；外部调用 1 个（assert_eq!）。

async fn record_context_updates_and_set_reference_context_item_injects_full_context_when_baseline_missing()

作用：验证没有旧的参考上下文时，记录上下文更新会把完整初始上下文写进历史，并设置新的参考项。

数据流：它创建会话后直接调用 record_context_updates_and_set_reference_context_item；读取历史应等于 build_initial_context 的结果；再确认 reference_context_item 等于当前 TurnContext 转出的项。

调用关系：它检查 Session 在第一次建立上下文基线时的行为，确保历史和内部参考状态同步。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 1 个（assert_eq!）。

async fn record_context_updates_and_set_reference_context_item_reinjects_full_context_after_clear()

作用：验证参考上下文被清掉后，再记录上下文会重新注入完整上下文，而不会只写差异。

数据流：它先写入一条压缩摘要，再记录上下文；随后手动清空参考项并把历史恢复成只有摘要；再次记录上下文后，历史应变成摘要加完整初始上下文。

调用关系：它模拟压缩或恢复后基线丢失的情况，检查 record_context_updates_and_set_reference_context_item 能自我修复。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 3 个（assert_eq!, from_ref, vec!）。

async fn record_context_updates_and_set_reference_context_item_persists_baseline_without_emitting_diffs()

作用：验证当只需要更新参考基线、不需要给模型发差异时，系统仍会把新的上下文项持久化到 rollout 记录里。

数据流：它先设置旧参考上下文，再切换到另一个模型上下文；确认 build_settings_update_items 没有生成更新项；调用记录函数后，历史仍为空，但 reference_context_item 变成新上下文；刷新 rollout 后，从文件里读到的新 TurnContext 也应匹配。

调用关系：它把上下文基线、历史、线程持久化和 RolloutRecorder 串起来，防止“没消息可发”时漏存新基线。

调用图：调用 3 个内部函数（attach_thread_persistence, make_session_and_context, get_rollout_history）；外部调用 2 个（assert_eq!, panic!）。

async fn record_context_updates_and_set_reference_context_item_persists_split_file_system_policy_to_rollout()

作用：验证拆分出来的文件系统沙盒策略会被写进 rollout 持久化记录。

数据流：它给 turn_context 加上额外拒绝 .env 的文件系统策略，挂上线程持久化；记录上下文并刷新 rollout；最后从保存文件里找 TurnContext，确认其中的 file_system_sandbox_policy 就是那份策略。

调用关系：它复用 file_system_policy_with_unreadable_glob，专门检查权限细节不会在持久化过程中丢失。

调用图：调用 5 个内部函数（attach_thread_persistence, file_system_policy_with_unreadable_glob, make_session_and_context, from_runtime_permissions_with_enforcement, get_rollout_history）；外部调用 2 个（assert_eq!, panic!）。

async fn build_initial_context_prepends_model_switch_message()

作用：验证上一轮模型和当前模型不同时，初始上下文最前面会加一条模型切换说明。

数据流：它把 previous_turn_settings 的 model 设成 previous-regular-model；构建初始上下文；检查第一条消息是 developer 角色，并且文本里包含 model_switch 标签。

调用关系：它检查 build_initial_context 对模型切换的提示顺序，确保模型先看到“已经换模型”这个重要背景。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 3 个（assert!, assert_eq!, panic!）。

async fn record_context_updates_and_set_reference_context_item_persists_full_reinjection_to_rollout()

作用：测试切换模型后，新的完整上下文会被写进 rollout 记录里。这样以后恢复线程时，不会拿旧模型或旧设置继续跑。

数据流：它先创建一个会话和旧上下文，再换成另一个模型生成新上下文，并打开线程持久化。然后写入一条种子消息、清空参考上下文、记录上一轮设置，再调用上下文更新逻辑。最后它从磁盘 rollout 里读回历史，确认里面保存的 TurnContext 和当前新上下文完全一致。

调用关系：这个测试通过 attach_thread_persistence 准备可落盘的线程，通过 make_session_and_context 构造测试会话，最后用 RolloutRecorder::get_rollout_history 验证 record_context_updates_and_set_reference_context_item 的结果。它关注的是会话恢复链路里“上下文是否真的持久化”这一环。

调用图：调用 3 个内部函数（attach_thread_persistence, make_session_and_context, get_rollout_history）；外部调用 6 个（default, new, assert_eq!, panic!, UserMessage, EventMsg）。

async fn run_user_shell_command_does_not_set_reference_context_item()

作用：测试用户单独执行 shell 命令时，不会把这次命令误当成下一轮对话的参考上下文。shell 命令只是临时任务，不应该污染聊天状态。

数据流：它创建带事件接收器的会话，先把参考上下文清空。然后运行一条 echo shell 命令，等待收到 TurnComplete 表示任务结束。最后检查 session.reference_context_item 仍然是空的。

调用关系：这个测试直接调用 handlers::run_user_shell_command，并监听会话发出的事件。它保护的是独立 shell 任务和正常聊天轮次之间的边界。

调用图：调用 2 个内部函数（run_user_shell_command, make_session_and_context_with_rx）；外部调用 5 个（from_secs, assert!, matches!, now, timeout）。

async fn realtime_conversation_list_voices_emits_builtin_list()

作用：测试实时语音接口会返回内置的语音名单和默认语音。这样客户端打开语音选择器时能拿到稳定结果。

数据流：它创建会话和事件接收器，调用 realtime_conversation_list_voices。随后读取一条事件，取出 voices 字段，和预期的 v1、v2 语音列表以及默认值逐项比较。

调用关系：这个测试覆盖 handlers::realtime_conversation_list_voices 的输出事件。它确保会话层不用访问外部服务，也能给客户端发出固定的语音能力清单。

调用图：调用 2 个内部函数（realtime_conversation_list_voices, make_session_and_context_with_rx）；外部调用 2 个（assert_eq!, panic!）。

fn kind(&self) -> TaskKind

作用：告诉测试框架这个假任务是普通任务。普通任务代表正常的一轮对话，而不是审核或压缩之类的特殊轮次。

数据流：它不读取外部输入，只返回 TaskKind::Regular。调用前后没有状态变化。

调用关系：CompletingTask 被 task_finish_emits_thread_idle_lifecycle_after_active_turn_clears 使用，用来模拟一个会立刻结束的正常任务。会话调度器通过 kind 判断它属于哪类轮次。

fn span_name(&self) -> &'static str

作用：给这个假任务提供一个追踪名字，方便日志或测试追踪里识别它。这里的名字表示“正在完成的会话任务”。

数据流：它不接收业务数据，直接返回固定字符串 session_task.completing。没有副作用。

调用关系：会话任务运行框架会在创建追踪 span（可理解为一段可观察的运行记录）时使用这个名字。

async fn run(
        self: Arc<Self>,
        _session: Arc<SessionTaskContext>,
        _ctx: Arc<TurnContext>,
        _input: Vec<TurnInput>,
        _cancellation_token: CancellationToken,
    )

作用：模拟一个马上完成、且没有最后回复内容的任务。它用来测试任务结束后的收尾流程。

数据流：它收到会话、上下文、输入和取消令牌，但都不使用。执行后直接返回 None，表示没有最后的助手消息，也不改动会话。

调用关系：这个假任务由 spawn_task 启动，随后会话会走 on_task_finished 一类的完成流程。测试用它观察线程空闲生命周期钩子是否被触发。

fn kind(&self) -> TaskKind

作用：返回这个永不结束假任务被设置成的任务类型。测试可以把它伪装成普通、审核或压缩任务。

数据流：它读取 self.kind，然后原样返回。不会修改任何东西。

调用关系：多个测试用 NeverEndingTask 制造“活跃轮次还没结束”的场景，会话调度器靠这个 kind 决定是否允许追加输入或如何取消。

fn span_name(&self) -> &'static str

作用：给永不结束的假任务起一个固定追踪名。这样日志里能看出这是测试用的卡住任务。

数据流：它直接返回 session_task.never_ending，不读取也不改动状态。

调用关系：会话任务框架运行 NeverEndingTask 时会使用这个名字做运行追踪。

async fn run(
        self: Arc<Self>,
        _session: Arc<SessionTaskContext>,
        _ctx: Arc<TurnContext>,
        _input: Vec<TurnInput>,
        cancellation_token: CancellationToken,
    ) -

作用：模拟一个一直不结束的任务，用来测试取消、打断和活跃轮次保护。它可以选择听取消信号，也可以故意无视取消。

数据流：它接收取消令牌。如果 listen_to_cancellation_token 为真，就等待取消信号，然后返回 None；否则每 60 秒睡一次，永远循环。它不产出内容。

调用关系：很多测试通过 spawn_task 启动它，制造“当前有任务占着”的状态。abort_all_tasks、steer_input、try_start_turn_if_idle 等流程都会在这种场景下被验证。

调用图：外部调用 3 个（cancelled, from_secs, sleep）。

fn kind(&self) -> TaskKind

作用：声明这个 guardian 测试任务是普通任务。它虽然会触发审核拒绝，但轮次类型仍按普通对话处理。

数据流：它不读外部数据，直接返回 TaskKind::Regular。没有状态改动。

调用关系：guardian_auto_review_interrupts_after_three_consecutive_denials 用它来模拟普通任务里连续被 guardian 拒绝的情况。

fn span_name(&self) -> &'static str

作用：给这个会触发 guardian 拒绝的假任务提供追踪名。这个名字帮助区分测试里的任务来源。

数据流：它直接返回 session_task.guardian_denied_approval，不产生副作用。

调用关系：会话任务运行框架用它标记这类测试任务的运行片段。

async fn run(
        self: Arc<Self>,
        session: Arc<SessionTaskContext>,
        ctx: Arc<TurnContext>,
        _input: Vec<TurnInput>,
        cancellation_token: CancellationToken,
    ) ->

作用：故意连续记录三次 guardian 拒绝，然后等待被取消。它用来测试“连续拒绝三次就打断当前轮”的保护开关。

数据流：它拿到会话和轮次上下文，克隆出 Session，循环三次调用 record_guardian_denial_for_test。之后等待取消令牌触发，最后返回 None。

调用关系：guardian_auto_review_interrupts_after_three_consecutive_denials 启动这个任务。guardian 子系统记录拒绝后，会话应该发出 TurnAborted 事件。

调用图：外部调用 2 个（cancelled, record_guardian_denial_for_test）。

async fn guardian_auto_review_interrupts_after_three_consecutive_denials()

作用：测试自动 guardian 审查连续拒绝三次后，会打断当前对话轮。这样系统不会在被安全检查反复否决时继续执行。

数据流：它创建会话，准备一条用户输入，启动 GuardianDeniedApprovalTask。然后从事件通道里等 TurnAborted 事件，并确认打断原因是 Interrupted。

调用关系：它依赖 GuardianDeniedApprovalTask 主动制造三次拒绝。测试目标是 guardian 记录拒绝后触发的会话中断流程。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 7 个（clone, new, assert_eq!, TurnAborted, from_secs, timeout, vec!）。

async fn guardian_helper_review_interrupts_after_three_consecutive_denials()

作用：测试来自辅助审核线程的 guardian 拒绝也能触发三次中断规则。也就是说，不管拒绝从主任务还是旁路 helper 来，都要保护当前轮。

数据流：它先启动一个会听取消信号的 NeverEndingTask 保持轮次活跃。然后另起一个线程，在线程里的 Tokio 运行时中记录三次 guardian 拒绝。最后等待 TurnAborted 事件，并确认原因是 Interrupted。

调用关系：它把 NeverEndingTask 当作正在运行的对话，把 record_guardian_denial_for_test 放到 helper 线程里执行。这样验证跨线程的 guardian 事件仍会正确影响 Session。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 8 个（clone, from_secs, new, assert_eq!, TurnAborted, spawn, timeout, vec!）。

async fn abort_regular_task_emits_marker_before_turn_aborted()

作用：测试强制打断普通任务时，系统会先给模型历史放入“本轮已中止”的标记，再通知客户端 TurnAborted。顺序很重要，因为模型下次要知道上一轮为什么断了。

数据流：它启动一个无视取消的 NeverEndingTask，然后调用 abort_all_tasks。接着从事件通道读取第一条 RawResponseItem 标记事件，再读取 TurnAborted，并确认没有多余事件。

调用关系：它覆盖 abort_all_tasks 对普通任务的强制中断路径。RawResponseItem 是写给模型看的历史项，TurnAborted 是发给客户端看的状态事件。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 7 个（clone, assert!, assert_eq!, panic!, from_secs, timeout, vec!）。

async fn abort_gracefully_emits_marker_before_turn_aborted()

作用：测试任务愿意响应取消时，也仍然先写入中止标记，再发 TurnAborted。无论是温和取消还是强制取消，客户端和模型看到的顺序都应一致。

数据流：它启动一个会监听取消令牌的 NeverEndingTask，调用 abort_all_tasks。然后确认先收到 RawResponseItem，再收到 TurnAborted，最后通道里没有额外事件。

调用关系：它和 abort_regular_task_emits_marker_before_turn_aborted 配对，分别验证“任务不配合取消”和“任务配合取消”两条路径。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 7 个（clone, assert!, assert_eq!, panic!, from_secs, timeout, vec!）。

async fn task_finish_emits_turn_item_lifecycle_for_leftover_pending_user_input()

作用：测试一轮任务结束时，如果中途还有用户追加输入没处理，系统会把它写入历史，并按完整生命周期发事件。这样迟到的用户输入不会丢。

数据流：它启动一个卡住的普通任务，清空早期事件。然后通过 steer_input 追加一条带文本标记的用户输入，再手动触发 on_task_finished。之后检查历史里有这条用户消息，并依次收到 RawResponseItem、ItemStarted、ItemCompleted、旧版 UserMessage、TurnComplete。

调用关系：这个测试连接了 steer_input、输入队列、on_task_finished、历史记录和事件广播。它确保任务收尾时会把 pending input 当成正式用户消息补齐。

调用图：调用 2 个内部函数（new, make_session_and_context_with_rx）；外部调用 6 个（clone, default, assert!, from_secs, timeout, vec!）。

async fn task_finish_emits_thread_idle_lifecycle_after_active_turn_clears()

作用：测试任务结束后，系统先清掉活跃轮次，再触发“线程空闲”生命周期钩子。扩展插件看到线程空闲时，应该拿到正确的线程信息。

数据流：它定义一个 ThreadIdleRecorder，记录 on_thread_idle 被调用次数并发信号。然后把它注册进扩展系统，启动会立即完成的 CompletingTask，等待 idle 信号，最后确认调用一次且 active_turn 已为空。

调用关系：CompletingTask 负责快速结束，扩展注册表负责接收线程生命周期通知。这个测试验证 Session 的收尾顺序和扩展回调时机。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 10 个（clone, new, from_secs, new, assert!, assert_eq!, bounded, new, new, timeout）。

async fn thread_idle_lifecycle_waits_for_trigger_turn_mailbox_work()

作用：测试如果邮箱里还有会触发下一轮的代理消息，线程不能被认为已经空闲。否则插件可能误以为工作完成了。

数据流：它注册一个会计数的 ThreadIdleRecorder，然后往 input_queue 放入 trigger_turn 为真的 InterAgentCommunication。调用 emit_thread_idle_lifecycle_if_idle 后，确认计数仍是 0。

调用关系：它直接验证 emit_thread_idle_lifecycle_if_idle 会查看 input_queue。只要还有“会触发轮次”的邮箱消息，线程空闲钩子就不能运行。

调用图：调用 3 个内部函数（make_session_and_context, root, new）；外部调用 6 个（clone, new, new, assert_eq!, new, new）。

async fn try_start_turn_if_idle_rejects_active_turn_without_injecting()

作用：测试当前已有活跃轮次时，try_start_turn_if_idle 不会偷偷塞入新输入。拒绝时还必须把原输入原样还给调用方。

数据流：它启动一个活跃的 NeverEndingTask，然后尝试用 synthetic idle input 自动开始新轮。函数返回 Busy 错误，错误里带回原输入，同时输入队列保持空。最后中断任务清理现场。

调用关系：这个测试覆盖 try_start_turn_if_idle 在“会话正忙”时的保护逻辑，防止自动输入混进正在运行的轮次。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, user_message）；外部调用 4 个（clone, new, assert_eq!, vec!）。

async fn try_start_turn_if_idle_rejects_plan_mode_without_injecting()

作用：测试计划模式下不会自动开始空闲轮次。计划模式通常需要更谨慎的用户确认，不能后台自启动。

数据流：它把会话协作模式改成 Plan，再调用 try_start_turn_if_idle。结果应是 PlanMode 拒绝，原输入被退回，active_turn 仍为空，输入队列也没有新内容。

调用关系：它验证 try_start_turn_if_idle 会读取 session_configuration.collaboration_mode，并在计划模式下直接拒绝。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, user_message）；外部调用 3 个（assert!, assert_eq!, vec!）。

async fn try_start_turn_if_idle_rejects_pending_trigger_turn_without_injecting()

作用：测试邮箱里已有触发下一轮的消息时，自动空闲输入不能抢先开新轮。否则代理消息和用户输入的顺序会乱。

数据流：它先往 input_queue 放一个 trigger_turn 邮箱消息。再调用 try_start_turn_if_idle，得到 PendingTriggerTurn 拒绝，原输入被退回，active_turn 仍为空，邮箱触发消息仍保留。

调用关系：它连接 input_queue 的 trigger-turn 状态和 try_start_turn_if_idle 的准入检查。重点是保证排队中的代理工作优先级不被破坏。

调用图：调用 4 个内部函数（make_session_and_context_with_rx, user_message, root, new）；外部调用 4 个（new, assert!, assert_eq!, vec!）。

async fn try_start_turn_if_idle_rejects_active_review_turn_without_injecting()

作用：测试活跃的是审核轮次时，也不能自动塞入空闲输入。审核轮次虽然不是普通聊天，但同样占用会话。

数据流：它启动一个 TaskKind::Review 的 NeverEndingTask，然后调用 try_start_turn_if_idle。结果是 Busy，输入原样返回，输入队列为空。最后中断任务。

调用关系：它和普通活跃轮次测试类似，但专门覆盖 Review 任务，确保 busy 判断不只看普通任务。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, user_message）；外部调用 4 个（clone, new, assert_eq!, vec!）。

async fn steer_input_requires_active_turn()

作用：测试 steer_input 必须在有活跃轮次时才能追加输入。没有正在进行的对话，就没有地方可以“插话”。

数据流：它创建一个没有活跃任务的会话，尝试追加一段 steer 文本。调用返回 NoActiveTurn 错误，不会写入输入队列。

调用关系：这个测试覆盖 steer_input 的第一道门槛：必须存在 active_turn。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 3 个（default, assert!, vec!）。

async fn steer_input_enforces_expected_turn_id()

作用：测试追加输入时如果指定了期望轮次 ID，系统会严格核对。这样客户端不会把输入误加到另一轮对话里。

数据流：它启动一个普通活跃任务，然后用不同的 expected_turn_id 调用 steer_input。结果返回 ExpectedTurnMismatch，并带出 expected 和 actual 两个 ID。

调用关系：它验证 steer_input 对 active_turn.sub_id 的检查。这个保护对多客户端或异步 UI 很重要。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 5 个（clone, default, assert_eq!, panic!, vec!）。

async fn steer_input_rejects_non_regular_turns()

作用：测试审核轮次和压缩轮次不能被用户插话。只有普通对话轮次才允许 steer_input。

数据流：它分别启动 Review 和 Compact 两类 NeverEndingTask，然后尝试追加 steer 文本。每次都应返回 ActiveTurnNotSteerable，并说明是哪种不可插话轮次。最后中断任务。

调用关系：它覆盖 steer_input 对 TaskKind 的判断，避免把用户输入混入审核或上下文压缩这些内部流程。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 3 个（default, assert_eq!, vec!）。

async fn steer_input_returns_active_turn_id()

作用：测试成功追加输入后，steer_input 会返回当前活跃轮次的 ID。调用方可以用这个 ID 确认输入确实进了哪一轮。

数据流：它启动普通活跃任务，然后用匹配的 turn_id 调用 steer_input。函数返回 tc.sub_id，并且输入队列显示有 pending input。

调用关系：它验证 steer_input 的成功路径：校验通过、输入入队、把活跃轮次 ID 回传给调用方。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 5 个（clone, default, assert!, assert_eq!, vec!）。

async fn abort_empty_active_turn_preserves_pending_input()

作用：测试一个没有真正任务的活跃轮次被中止时，已经挂在这个轮次状态上的待处理输入不会丢。中止清状态，但不应该吞消息。

数据流：它手动创建 ActiveTurn，拿到 turn_state，然后给这个状态塞入一条 pending ResponseItem。调用 abort_all_tasks 后，active_turn 被清空，但再从同一 turn_state 取 pending input 时还能取回原消息。

调用关系：这个测试覆盖 abort_all_tasks 对空 active_turn 的特殊情况，重点是 input_queue 的 pending input 生命周期。

调用图：调用 1 个内部函数（make_session_and_context_with_rx）；外部调用 4 个（clone, assert!, assert_eq!, vec!）。

async fn set_total_token_usage(sess: &Session, total_token_usage: TokenUsage)

作用：这是测试辅助函数，用来给会话写入一个总 token 用量基线。token 可以理解为模型计费和上下文长度使用的基本单位。

数据流：它接收 Session 和 TokenUsage，锁住 session.state，把 TokenUsageInfo 写进去：total_token_usage 用传入值，last_token_usage 用默认值，model_context_window 为空。

调用关系：它被 turn_start_lifecycle_exposes_turn_metadata_and_token_baseline 调用，用于提前布置测试状态。它本身不验证行为，只负责准备数据。

调用图：被 1 处调用（turn_start_lifecycle_exposes_turn_metadata_and_token_baseline）；外部调用 1 个（default）。

async fn queue_only_mailbox_mail_waits_for_next_turn_after_answer_boundary()

作用：测试当前轮已经越过“回答边界”后，普通邮箱消息不会再插进当前轮，而是等下一轮。这样模型已经开始收尾的回答不会被突然改输入。

数据流：它启动活跃普通任务，调用 defer_mailbox_delivery_to_next_turn 标记当前轮不再接收邮箱消息，然后入队一个 trigger_turn 为 false 的通信。检查当前轮没有 pending input；中止当前任务后，再检查这条通信出现在下一轮可取的输入里。

调用关系：它验证 input_queue 在 answer boundary 之后的缓冲规则。abort_all_tasks 清掉当前轮后，队列才把消息交给下一轮。

调用图：调用 4 个内部函数（make_session_and_context_with_rx, root, try_from, new）；外部调用 4 个（clone, new, assert!, assert_eq!）。

async fn trigger_turn_mailbox_mail_waits_for_next_turn_after_answer_boundary()

作用：测试会触发新轮的邮箱消息在回答边界之后也不能塞回当前轮。它应该保留为下一轮触发源。

数据流：它启动活跃任务，设置邮箱递送延后到下一轮，再入队 trigger_turn 为真的通信。当前轮没有 pending input；中止任务后，队列仍报告有 trigger-turn 邮箱项。

调用关系：它和 queue_only_mailbox_mail_waits_for_next_turn_after_answer_boundary 配对，覆盖 trigger_turn=true 的邮箱消息路径。

调用图：调用 4 个内部函数（make_session_and_context_with_rx, root, try_from, new）；外部调用 3 个（clone, new, assert!）。

async fn steered_input_reopens_mailbox_delivery_for_current_turn()

作用：测试用户在回答边界后又追加输入时，会重新打开当前轮的邮箱递送。因为用户明确继续这一轮，相关代理消息也可以一起送进来。

数据流：它先让当前轮延后邮箱递送，并缓存一条邮箱通信。随后调用 steer_input 追加 follow up。最后读取 pending input，确认先有用户追加输入，再有缓存的代理通信。

调用关系：它连接 steer_input 和 input_queue 的邮箱延后机制。用户插话会把“留到下一轮”的普通邮箱消息重新带回当前轮。

调用图：调用 4 个内部函数（make_session_and_context_with_rx, root, try_from, new）；外部调用 5 个（clone, default, new, assert_eq!, vec!）。

async fn stale_defer_mailbox_delivery_does_not_override_steered_input()

作用：测试用户追加输入已经重新打开邮箱递送后，过期的延后请求不能再把它关掉。这样旧状态不会覆盖新动作。

数据流：它先延后邮箱、入队通信、再 steer_input 追加用户输入，让通信进入当前轮 pending input。随后再次调用 defer_mailbox_delivery_to_next_turn，最后确认 pending input 没被改坏，仍然包含用户输入和通信。

调用关系：这个测试保护 input_queue 的时序逻辑，防止迟来的 defer 调用覆盖 steer_input 已经做出的决定。

调用图：调用 4 个内部函数（make_session_and_context_with_rx, root, try_from, new）；外部调用 5 个（clone, default, new, assert_eq!, vec!）。

async fn tool_calls_reopen_mailbox_delivery_for_current_turn()

作用：测试模型发起工具调用后，也会重新打开当前轮的邮箱递送。工具调用意味着当前轮还在继续处理，可以接收之前缓存的代理消息。

数据流：它启动活跃任务，延后邮箱递送并缓存一条通信。然后构造一个 test_tool 的 FunctionCall，交给 handle_output_item_done 处理。处理结果显示需要 follow-up 且有工具 future，同时 pending input 中出现缓存通信。

调用关系：它验证 handle_output_item_done 处理工具调用时会影响 input_queue。这个行为和 steer_input 类似，都会让当前轮重新接收邮箱消息。

调用图：调用 6 个内部函数（make_session_and_context_with_rx, test_tool_runtime, new, root, try_from, new）；外部调用 6 个（clone, new, new, new, assert!, assert_eq!）。

async fn abort_review_task_emits_exited_then_aborted_and_records_history()

作用：测试审核任务被打断时，客户端先收到“退出审核模式”，再收到“轮次中止”，并且模型历史里仍记录中止标记。顺序和历史记录都很关键。

数据流：它启动 ReviewTask，随后 abort_all_tasks。然后在事件流中寻找 ExitedReviewMode 和 TurnAborted，确认前者出现且早于后者。最后检查会话历史里有一条用户消息包含 <turn_aborted> 类型的中止标记。

调用关系：它覆盖 ReviewTask 的取消路径、事件广播顺序和历史写入。ExitedReviewMode 面向客户端 UI，turn aborted marker 面向后续模型上下文。

调用图：调用 2 个内部函数（make_session_and_context_with_rx, new）；外部调用 7 个（clone, assert!, assert_eq!, from_secs, now, timeout, vec!）。

async fn fatal_tool_error_stops_turn_and_reports_error()

作用：测试工具收到不兼容的调用格式时，会返回致命错误，而不是继续当前轮。这样坏的工具调用不会被悄悄吞掉。

数据流：它从会话加载工具列表，建立 ToolRouter，然后构造一个 CustomToolCall 形式的 shell_command，但 payload 不符合要求。dispatch_tool_call_with_code_mode_result 返回 FunctionCallError::Fatal，消息说明 shell_command payload 不兼容。

调用关系：它验证 ToolRouter::build_tool_call 和 dispatch_tool_call_with_code_mode_result 的错误路径。目标是确认工具层能把严重格式错误上报给会话流程。

调用图：调用 4 个内部函数（make_session_and_context_with_rx, build_tool_call, from_turn_context, new）；外部调用 8 个（clone, new, new, default, new, assert_eq!, panic!, new）。

async fn sample_rollout(
    session: &Session,
    _turn_context: &TurnContext,
) -> (Vec<RolloutItem>, Vec<ResponseItem>)

作用：这是测试辅助函数，用来造一份包含初始上下文、用户/助手消息和两次压缩记录的 rollout 样本。它让多个恢复历史相关测试有同一份标准材料。

数据流：它接收 Session 和 TurnContext，创建 rollout_items 和 live_history。先构造初始上下文，必要时补上 personality_spec；再依次加入用户消息、助手回复、压缩摘要、更多消息。每加入一项都同步更新 live_history 和 rollout_items，最后返回 rollout 条目列表和压缩后的实时历史。

调用关系：它被 reconstruct_history_matches_live_compactions、record_initial_history_reconstructs_forked_transcript、record_initial_history_reconstructs_resumed_transcript 等测试复用。它模拟真实会话被压缩和恢复时的历史形态。

调用图：调用 4 个内部函数（into, build_compacted_history, new, new）；被 5 处调用（reconstruct_history_matches_live_compactions, record_initial_history_reconstructs_forked_transcript, record_initial_history_reconstructs_resumed_transcript, record_initial_history_seeds_token_info_from_rollout, resumed_history_injects_initial_context_on_first_context_update_only）；外部调用 7 个（new, build_initial_context, new_default_turn, Compacted, ResponseItem, once, vec!）。

async fn rejects_escalated_permissions_when_policy_not_on_request()

作用：测试旧版 shell_command 在审批策略不是 OnRequest 时，会拒绝请求提升权限。提升权限就是让命令跳出更安全的沙箱限制，必须受策略控制。

数据流：它把 turn_context 的 approval_policy 设为 OnFailure，然后调用 ShellCommandHandler，payload 里要求 RequireEscalated 并给出理由。结果应返回 RespondToModel 错误，告诉模型当前策略下不能请求提升权限；同时确认没有授予权限。随后它改成非提升权限路径，确认同一命令不会因为刚才的拒绝而被污染。

调用关系：它覆盖 ShellCommandHandler、exec_policy 和 granted_turn_permissions 的配合。重点是安全策略：不允许时要早拒绝，且拒绝不影响普通执行判断。

调用图：调用 4 个内部函数（make_session_and_context, from, new, plain）；外部调用 10 个（clone, get_mut, new, new, assert!, format!, panic!, assert_eq!, json!, new）。

async fn shell_tool_cancellation_waits_for_runtime_cleanup() -> anyhow::Result<()>

作用：测试 shell 工具被取消时，会等子进程执行清理逻辑后再结束。否则临时文件、进程或外部资源可能残留。

数据流：它创建允许直接执行命令的会话，生成一个脚本：启动后写 ready，收到 TERM 信号后写 cleanup。测试启动工具调用，等 ready 文件出现后取消令牌，再等待工具任务结束，最后确认 cleanup 文件内容是 cleaned。

调用关系：它通过 test_tool_runtime 运行 shell_command 工具，使用 CancellationToken 模拟用户打断。这个测试保护工具运行时的取消和清理顺序。

调用图：调用 3 个内部函数（make_session_with_config, test_tool_runtime, build_tool_call）；外部调用 13 个（clone, new, new, from_millis, from_secs, bail!, assert_eq!, format!, json!, new (+3 more)）。

async fn unified_exec_rejects_escalated_permissions_when_policy_not_on_request()

作用：测试统一执行工具 exec_command 也遵守同样的提升权限策略。新旧执行入口不能有安全规则差异。

数据流：它把审批策略设为 OnFailure，调用 ExecCommandHandler，payload 要求 RequireEscalated。结果返回 RespondToModel 错误，内容说明当前策略下不能请求提升权限。

调用关系：它对应 rejects_escalated_permissions_when_policy_not_on_request，但覆盖 ExecCommandHandler 这条统一执行路径，确保安全规则一致。

调用图：调用 4 个内部函数（make_session_and_context, default, new, plain）；外部调用 8 个（clone, new, new, format!, panic!, assert_eq!, json!, new）。

async fn session_start_hooks_only_load_from_trusted_project_layers() -> std::io::Result<()>

作用：测试会话启动钩子只从受信任的项目配置层加载。钩子是启动时会运行的脚本或动作，来源不可信就很危险。

数据流：它创建临时 home、项目根目录和嵌套目录，在根和嵌套 .codex 下都写 hooks。然后只把 nested 标成 Trusted，构建配置并列出 hooks。结果只发现 nested 的 hooks.json，trust_status 是 Untrusted，preview_session_start_hooks 不实际返回可运行钩子。

调用关系：它连接 ConfigBuilder、项目信任配置、codex_hooks::list_hooks 和 preview_session_start_hooks。重点是验证配置层筛选和信任状态不会让上层不可信钩子混进来。

调用图：调用 3 个内部函数（write_project_hooks, write_project_trust_config, from_absolute_path）；外部调用 8 个（assert!, assert_eq!, list_hooks, default, default, create_dir_all, write, tempdir）。

async fn session_start_hooks_require_project_trust_without_config_toml() -> std::io::Result<()>

作用：测试即使项目没有 config.toml，启动钩子也必须依赖项目信任状态。未知或不信任项目不能加载钩子，信任项目才会发现钩子。

数据流：它创建一个带 .git 和 .codex/hooks.json 的项目，但不写 config.toml。然后分别用 unknown、untrusted、trusted 三种信任配置构建会话配置，列出 hooks。前两种期望 0 个，trusted 期望 1 个，并确认预览启动钩子仍为空。

调用关系：它验证项目信任配置和 codex_hooks::list_hooks 的关系，特别覆盖没有 config.toml 的项目。这个测试防止只因为目录里有 hooks.json 就加载启动钩子。

调用图：调用 2 个内部函数（write_project_hooks, write_project_trust_config）；外部调用 11 个（new, assert!, assert_eq!, list_hooks, default, format!, default, create_dir_all, write, tempdir (+1 more)）。

fn expect_text_output(output: &T) -> String

作用：这个小工具函数把一次工具调用的结果转成普通文字，方便测试直接检查里面有没有想要的内容。没有它，每个测试都要重复写一堆拆包装的代码。

数据流：输入是一份工具输出对象。它先把输出转换成协议里的“函数调用输出”格式，再从输出正文里取出文本；如果拿到的不是函数输出，它就直接让测试失败。结果是一段字符串，供后面的断言检查。

调用关系：它服务于多个命令执行相关测试。那些测试先调用 shell 命令处理器，拿到结果后交给 expect_text_output，再检查结果里是否包含例如“hi”这样的命令输出。

调用图：被 3 处调用（guardian_allows_shell_command_additional_permissions_requests_past_policy_validation, shell_command_allows_sticky_turn_permissions_without_inline_request_permissions_feature, strict_auto_review_turn_grant_forces_guardian_for_shell_command_policy_skip）；外部调用 2 个（to_response_item, panic!）。

async fn request_permissions_routes_to_guardian_when_reviewer_is_enabled()

作用：这个测试确认：当开启 Guardian 自动审核时，权限申请不会直接等用户批准，而是会发给 Guardian 审核。它验证的是权限申请路线有没有走对。

数据流：测试先启动一个假的服务器，让它假装 Guardian 返回“允许”。接着创建会话和回合上下文，打开“按请求审批”和 Guardian 功能，并申请本回合联网权限。最后它检查返回结果是允许、权限被记录到当前回合里，并且假的服务器确实收到包含 request_permissions 和申请理由的请求。

调用关系：它模拟真实的权限申请流程，核心调用会落到 session.request_permissions_for_environment。假的模型服务器通过 mount_sse_once 提供 Guardian 的流式回答，测试最后用请求日志确认系统真的把活交给了 Guardian。

调用图：调用 5 个内部函数（default, models_manager_with_provider, mount_sse_once, sse, start_mock_server）；外部调用 11 个（clone, new, new, from_secs, default, assert!, assert_eq!, create_model_provider, format!, timeout (+1 more)）。

async fn request_permissions_guardian_review_stops_when_cancelled()

作用：这个测试确认：Guardian 审核如果还没完成，外部取消信号一来，权限申请会及时停止。它防止系统在用户取消后还傻等审核结果，或者错误地授予权限。

数据流：测试搭了一个会故意延迟 60 秒才回复的假 Guardian。然后发起联网权限申请，并等待系统发出“Guardian 已开始评估”的事件。随后触发取消令牌，检查任务很快结束、返回 None，并且没有把任何权限写进当前回合。

调用关系：它把权限申请放进 tokio 异步任务里跑，另一边监听事件频道，确认 Guardian 流程已启动后再取消。这个测试重点覆盖 request_permissions_for_environment 和取消令牌之间的配合。

调用图：调用 6 个内部函数（default, models_manager_with_provider, mount_response_once, sse, sse_response, start_mock_server）；外部调用 13 个（clone, get_mut, new, new, from_secs, default, assert_eq!, create_model_provider, format!, matches! (+3 more)）。

async fn guardian_allows_shell_command_additional_permissions_requests_past_policy_validation()

作用：这个测试确认：传统 shell 命令如果声明需要额外权限，并且 Guardian 同意，就可以通过前置校验并真正执行。它防止权限申请已经被审核通过，却仍被本地校验误拦。

数据流：测试准备一个会返回“允许”的假 Guardian，打开 Guardian 审核和执行权限申请功能，然后构造一个 echo hi 命令，附带“需要额外联网权限”的申请。命令处理器执行后，测试把输出转成文本，并确认里面有 hi。

调用关系：它使用 ShellCommandHandler 走真实的 shell 工具处理路径，过程中会间接触发权限审核。最后通过 expect_text_output 读取命令输出，证明 Guardian 放行后命令确实跑起来了。

调用图：调用 8 个内部函数（expect_text_output, models_manager_with_provider, from, new, mount_sse_once, sse, start_mock_server, plain）；外部调用 11 个（clone, new, new, assert!, cfg!, codex_linux_sandbox_exe_or_skip!, create_model_provider, format!, json!, new (+1 more)）。

async fn strict_auto_review_turn_grant_forces_guardian_for_shell_command_policy_skip()

作用：这个测试确认：如果某个回合拿到的是“严格自动审核”的临时权限，即使命令看起来可以跳过普通策略检查，也仍然要经过 Guardian。它防止严格模式被错误当成永久免审通行证。

数据流：测试先手动给当前回合记录一份严格自动审核的联网权限，再设置 shell 命令 echo hi。执行命令后，它确认命令输出正常，同时检查假 Guardian 收到的请求里包含 echo hi，说明这次命令确实被重新审核过。

调用关系：它把已授权权限写入 active turn 的状态，再通过 ShellCommandHandler 执行命令。expect_text_output 用来检查输出，假的服务器请求日志用来确认 Guardian 没有被绕过。

调用图：调用 9 个内部函数（expect_text_output, default, models_manager_with_provider, from, new, mount_sse_once, sse, start_mock_server, plain）；外部调用 10 个（clone, new, new, default, assert!, create_model_provider, format!, json!, new, vec!）。

async fn guardian_allows_unified_exec_additional_permissions_requests_past_policy_validation()

作用：这个测试检查新版统一执行工具的参数校验：如果声明要额外权限，却没说清楚具体要网络还是文件权限，系统应该拒绝。名字里说 Guardian 放行，但实际断言的是缺少 additional_permissions 时必须报错。

数据流：测试创建会话，打开 Guardian 审核和执行权限申请功能，然后调用 exec_command，参数里写了 with_additional_permissions，但没有提供 additional_permissions。结果应该不是成功执行，而是返回给模型的一段明确错误文字。

调用关系：它走 ExecCommandHandler 的处理路径，重点不在假 Guardian，而在工具参数进入执行前的验证。测试用 assert_eq 检查错误提示完全符合预期，防止以后错误信息或校验规则被无意改坏。

调用图：调用 3 个内部函数（default, new, plain）；外部调用 7 个（clone, new, new, assert_eq!, panic!, json!, new）。

async fn process_compacted_history_preserves_separate_guardian_developer_message()

作用：这个测试确认：压缩对话历史时，Guardian 专用的开发者提示会被保留下来，而且不会和旧的开发者消息混在一起。它防止 Guardian 在长对话压缩后丢掉自己的安全规则。

数据流：测试把会话来源设成 Guardian 子代理，并把 Guardian 的策略提示放进当前上下文。然后传入一段压缩后的历史，里面故意包含一条过期的 developer 消息。处理完成后，它收集所有 developer 消息，确认旧消息被移除，并且最后一条是新的 Guardian 策略。

调用关系：它直接调用 compact_remote::process_compacted_history，这是对话历史压缩后的整理步骤。guardian_policy_prompt 提供 Guardian 应该使用的提示词，测试确保这个提示在压缩流程里仍然单独存在。

调用图：调用 1 个内部函数（process_compacted_history）；外部调用 6 个（SubAgent, assert!, assert_eq!, guardian_policy_prompt, Other, vec!）。

async fn shell_command_allows_sticky_turn_permissions_without_inline_request_permissions_feature()

作用：这个测试确认：即使没有开启“命令里直接申请额外权限”的功能，只要当前回合已经有粘住的临时权限，shell 命令也不应该因为缺少内联申请而被误拒。这里的“粘住”就是本回合内已经批准过、后续还能继续用的权限。

数据流：测试先开启请求权限工具，并手动往当前回合状态里写入联网权限。之后执行 echo hi 命令，不在命令参数里再写 additional_permissions。如果成功，它检查输出包含 hi；如果返回给模型一个错误，也确认错误不是“额外权限被禁用”。

调用关系：它直接改 active turn 的内部状态来模拟之前已经授权过的情况，然后走 ShellCommandHandler。expect_text_output 只在命令成功时用来读取输出；如果失败，测试重点确认失败原因不是权限校验误伤。

调用图：调用 5 个内部函数（expect_text_output, default, from, new, plain）；外部调用 8 个（clone, new, new, default, assert!, panic!, json!, new）。

async fn guardian_subagent_does_not_inherit_parent_exec_policy_rules()

作用：这个测试确认：Guardian 作为子代理启动时，不会继承父会话的命令执行策略规则。这样 Guardian 审核别人的请求时，不会被父会话项目里的本地规则误限制。

数据流：测试先创建临时项目，并写入一条规则：禁止 rm 命令。它验证父执行策略确实会禁止 rm。然后用这份策略作为“继承策略”启动一个 Guardian 子代理。最后检查子代理自己的执行策略对 rm 的判断是允许，而不是继承父规则的禁止。

调用关系：它先用 ExecPolicyManager::load 读取父项目规则，再通过 Codex::spawn 启动一个 session_source 为 Guardian 的子代理。测试的核心关系是：父会话有禁令，但 Guardian 子代理启动时必须把这类父策略隔离开。

调用图：调用 13 个内部函数（new, new, new, load, new, spawn, models_manager_with_provider, default_for_tests, from_auth_for_testing, from_api_key (+3 more)）；外部调用 16 个（clone, new, default, new, default, SubAgent, assert_eq!, empty_extension_registry, default, default (+6 more)）。

fn contribute(
        &'a self,
        _thread_store: &'a ExtensionData,
        _turn_store: &'a ExtensionData,
        item: &'a mut TurnItem,
    ) -> codex_extension_api::ExtensionFuture<'a, Res

作用：这是测试里做出来的一个假插件方法，用来证明插件确实能改写助手消息。它看到当前回合项是助手消息时，就把消息内容替换成固定的一句话。

数据流：进去的是扩展数据、当前回合数据，以及一个可修改的回合项；它不使用前两个数据，只检查这个回合项是不是助手消息；如果是，就把里面的文字列表改成只包含“plan contributed assistant text”，最后返回成功，表示插件处理完了。

调用关系：它由测试注册到扩展系统里，真正调用它的是计划模式处理助手输出的流程。测试函数 plan_mode_uses_contributed_turn_item_for_last_agent_message 依靠它来制造一个明显的改写效果，然后验证主流程有没有采用这个改写结果。

调用图：外部调用 2 个（pin, vec!）。

fn assistant_output_text(text: &str) -> ResponseItem

作用：这是一个测试小工具，用来快速造出一条“助手输出文字”的模拟数据。有人写测试时不用手动拼一大段结构，只要给一句文字就能得到一条像真实助手回复一样的数据。

数据流：进去的是一段普通字符串；它把这段字符串放进一个 ResponseItem::Message 结构里，设置好消息编号、角色是 assistant、内容是输出文字；出来的是一条可交给会话处理流程的模拟助手消息。

调用关系：它被 plan_mode_uses_contributed_turn_item_for_last_agent_message 调用，用来准备测试输入。它本身不参与业务判断，只负责把“原始助手文本”包装成系统能识别的消息格式。

调用图：被 1 处调用（plan_mode_uses_contributed_turn_item_for_last_agent_message）；外部调用 1 个（vec!）。

async fn plan_mode_uses_contributed_turn_item_for_last_agent_message()

作用：这是核心测试，验证计划模式在记录最后一条助手消息时，会使用扩展插件改写后的内容，而不是原始内容。它保证扩展系统和计划模式的消息处理流程是接通的。

数据流：开始时它创建一个测试会话和回合上下文；然后注册 RewriteAgentMessageContributor 这个假插件；再准备扩展数据、计划模式状态、空的“最后助手消息”变量，以及一条原始助手输出。接着它把这些交给计划模式的助手消息完成处理函数。处理结束后，它检查结果确实被处理了，并且最后助手消息从原文变成了插件写入的“plan contributed assistant text”。

调用关系：它是这个文件的测试入口。它先调用 make_session_and_context 搭测试环境，调用 assistant_output_text 准备输入，再让 handle_assistant_item_done_in_plan_mode 跑完整流程。流程中会触发已注册的 RewriteAgentMessageContributor::contribute，最后这个测试用断言确认整条链路按预期工作。

调用图：调用 5 个内部函数（make_session_and_context, new, assistant_output_text, new, new）；外部调用 3 个（new, assert!, assert_eq!）。

fn user_message(text: &str) -> ResponseItem

作用：这个小工具用一段文字快速做出一条“用户说的话”。测试里反复需要造用户消息，用它可以少写很多重复结构。

数据流：输入一段普通文本 → 把它包进 ResponseItem::Message，并标成 role 为 user、内容类型为输入文本 → 返回一条可放进历史记录里的用户消息，不改动外部状态。

调用关系：它是测试数据的零件工厂。多个回滚重建测试会调用它来摆出“用户发了一句话”的场景，然后把结果交给会话重建逻辑，最后用断言检查这条消息该不该留下。

调用图：被 3 处调用（reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_completed_turns, reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_incomplete_turn, reconstruct_history_rollback_skips_non_user_turns_for_history_and_metadata）；外部调用 1 个（vec!）。

fn assistant_message(text: &str) -> ResponseItem

作用：这个小工具用一段文字快速做出一条“助手回复”。测试里用它来模拟模型已经回答过的内容。

数据流：输入一段回复文字 → 把它包进 ResponseItem::Message，并标成 role 为 assistant、内容类型为输出文本 → 返回一条助手消息，不改动外部状态。

调用关系：它和 user_message 配套使用，帮测试拼出一轮完整对话。回滚、跳过非用户轮次、跨代理轮次等测试会用它来制造预期历史，再和重建结果比较。

调用图：被 4 处调用（reconstruct_history_rollback_counts_inter_agent_assistant_turns, reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_completed_turns, reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_incomplete_turn, reconstruct_history_rollback_skips_non_user_turns_for_history_and_metadata）；外部调用 1 个（vec!）。

fn inter_agent_assistant_message(text: &str) -> ResponseItem

作用：这个小工具制造一条特殊的助手消息，内容其实是“代理之间通信”的 JSON 字符串。它用来测试多代理场景下，系统能不能把这种隐藏在文本里的指令当成特殊轮次处理。

数据流：输入一段通信文字 → 创建一个从根代理发给 worker 子代理的 InterAgentCommunication（代理间通信对象）→ 把它转成 JSON，再塞进助手输出消息里 → 返回这条特殊助手消息。

调用关系：只有跨代理回滚测试会调用它。它先造出一条看起来像助手消息、实际表示代理指令的记录，再交给历史重建逻辑，确认回滚计数会把这种助手触发的轮次也算进去。

调用图：调用 2 个内部函数（root, new）；被 1 处调用（reconstruct_history_rollback_counts_inter_agent_assistant_turns）；外部调用 2 个（new, vec!）。

async fn record_initial_history_reconstructs_typed_inter_agent_message()

作用：这个测试确认：恢复旧会话时，如果历史里已经有结构化的代理间通信消息，系统会把它正确转换成模型输入历史。简单说，就是多代理消息不会在恢复时变形。

数据流：先创建测试会话和一个 InterAgentCommunication → 把它作为恢复历史传给 session.record_initial_history → 再读取会话内部历史 → 期望里面正好是这条通信消息转换后的模型输入项。

调用关系：它直接测试 record_initial_history 的恢复入口。测试先用 make_session_and_context 搭好假会话，再把构造好的恢复历史交给会话，最后用 assert_eq 检查会话状态。

调用图：调用 4 个内部函数（make_session_and_context, root, new, default）；外部调用 5 个（from, new, assert_eq!, Resumed, vec!）。

async fn record_initial_history_resumed_bare_turn_context_does_not_hydrate_previous_turn_settings()

作用：这个测试确认：如果恢复记录里只有孤零零的 TurnContextItem，系统不会误以为它代表上一轮有效对话。这样可以避免把无上下文的旧设置错误套到新会话上。

数据流：先造一个带旧模型名的 TurnContextItem → 只把这一项作为恢复历史写入会话 → 查询 previous_turn_settings 和 reference_context_item → 期望二者都是空。

调用关系：它验证 record_initial_history 对“裸上下文记录”的防误判。make_session_and_context 提供基础会话，record_initial_history 负责读取历史，断言负责确认没有错误填充上一轮设置。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 5 个（from, assert!, assert_eq!, Resumed, vec!）。

async fn record_initial_history_resumed_hydrates_previous_turn_settings_from_lifecycle_turn_with_missing_turn_context_id()

作用：这个测试确认：即使 TurnContextItem 自己缺少 turn_id，只要它夹在明确的轮次开始和结束事件之间，系统仍能把它识别为上一轮设置来源。

数据流：先造一个旧 TurnContextItem，并故意清掉它自己的 turn_id → 用 TurnStarted、UserMessage、TurnContext、TurnComplete 组成完整轮次 → 恢复到会话 → 期望 previous_turn_settings 里有旧模型、压缩哈希和实时状态。

调用关系：它测试恢复逻辑能根据外层生命周期事件补足上下文含义。record_initial_history 读入这串事件后，应该把 TurnContextItem 和正在进行的轮次关联起来。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 4 个（from, assert_eq!, Resumed, vec!）。

async fn reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_completed_turns()

作用：这个测试确认：回滚已完成的轮次时，聊天历史和“上一轮设置”会一起退回到同一个位置。不会出现消息退回了，但模型设置还停在被回滚轮次上的错位情况。

数据流：构造两轮完整对话，第二轮随后被 ThreadRolledBack 回滚 → 调用 reconstruct_history_from_rollout → 得到重建结果 → 期望只保留第一轮消息，并且 previous_turn_settings 和 reference_context_item 也指向第一轮。

调用关系：它直接测试 reconstruct_history_from_rollout。user_message 和 assistant_message 用来造消息，测试会话调用重建函数，assert_eq 检查历史和元数据是否同步。

调用图：调用 3 个内部函数（assistant_message, user_message, make_session_and_context）；外部调用 2 个（assert_eq!, vec!）。

async fn reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_incomplete_turn()

作用：这个测试确认：如果第二轮还没完成就被回滚，系统也会把它从历史和元数据里一起拿掉。这样未完成的半截对话不会污染恢复结果。

数据流：构造第一轮完整对话，再构造第二轮只开始、有用户消息、但没完成 → 加入回滚一轮事件 → 调用重建 → 期望只剩第一轮用户和助手消息，上一轮设置也来自第一轮。

调用关系：它覆盖“未完成轮次回滚”的分支。辅助函数造出消息，reconstruct_history_from_rollout 做真正重建，断言检查结果没有留下第二轮痕迹。

调用图：调用 3 个内部函数（assistant_message, user_message, make_session_and_context）；外部调用 2 个（assert_eq!, vec!）。

async fn reconstruct_history_rollback_skips_non_user_turns_for_history_and_metadata()

作用：这个测试确认：回滚按“用户发起的轮次”来算，不应该被没有用户消息的后台轮次消耗掉。这样用户点回滚一轮时，回滚的是用户真正看到的一轮对话。

数据流：构造第一轮用户对话、第二轮用户对话、再加一个没有 UserMessage 的独立助手轮次 → 发出回滚一轮事件 → 调用重建 → 期望第二轮用户对话被回滚，只保留第一轮，元数据也回到第一轮。

调用关系：它测试回滚计数规则。standalone 的非用户轮次被放在最后，用来确认 reconstruct_history_from_rollout 不会把它当成用户轮次来扣数。

调用图：调用 3 个内部函数（assistant_message, user_message, make_session_and_context）；外部调用 2 个（assert_eq!, vec!）。

async fn reconstruct_history_rollback_counts_inter_agent_assistant_turns()

作用：这个测试确认：由代理间助手指令触发的轮次，在回滚时也要算作可回滚的一轮。多代理系统里，这类轮次虽然不是普通用户输入，但仍会推进对话状态。

数据流：先构造一轮普通用户对话 → 再构造一轮包含 inter_agent_assistant_message 的助手指令轮次和 worker 回复 → 加入回滚一轮 → 调用重建 → 期望只剩普通用户对话，代理指令轮次被移除。

调用关系：它把 inter_agent_assistant_message 造出的特殊消息交给 reconstruct_history_from_rollout。测试重点是确认回滚逻辑能识别这种“助手发起但有轮次意义”的记录。

调用图：调用 3 个内部函数（assistant_message, inter_agent_assistant_message, make_session_and_context）；外部调用 2 个（assert_eq!, vec!）。

async fn reconstruct_history_rollback_clears_history_and_metadata_when_exceeding_user_turns()

作用：这个测试确认：如果要求回滚的轮次数超过实际存在的用户轮次，系统会清空历史和相关元数据。也就是“退过头了”时，不留下半吊子的参考信息。

数据流：构造唯一一轮用户对话 → 加入 ThreadRolledBack，要求回滚 99 轮 → 调用重建 → 返回的 history 为空，previous_turn_settings 为空，reference_context_item 也为空。

调用关系：它测试 reconstruct_history_from_rollout 的边界情况。没有调用消息辅助函数，而是直接造 rollout 项，最后用断言确认所有恢复基准都被清掉。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 3 个（assert!, assert_eq!, vec!）。

async fn record_initial_history_resumed_rollback_skips_only_user_turns()

作用：这个测试确认：恢复旧会话时，回滚事件只跳过用户轮次，不会因为中间有一个没有用户消息的后台轮次而少回滚。这样恢复后的设置不会被后台任务误导。

数据流：构造一个用户轮次和一个没有 UserMessage 的独立任务轮次 → 加入回滚一轮事件 → 交给 record_initial_history → 查询会话的 previous_turn_settings 和 reference_context_item → 期望都为空，因为唯一用户轮次被回滚了。

调用关系：它测试 record_initial_history 内部调用的重建规则。make_session_and_context 建会话，Resumed 包装旧历史，record_initial_history 负责恢复并更新会话状态。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 5 个（from, assert!, assert_eq!, Resumed, vec!）。

async fn record_initial_history_resumed_rollback_drops_incomplete_user_turn_compaction_metadata()

作用：这个测试确认：被回滚的未完成用户轮次如果发生过历史压缩，压缩留下的元数据不能影响最终参考上下文。否则系统可能拿被撤销的轮次当新基准。

数据流：先构造一轮已完成的有效对话上下文 → 再构造一轮未完成用户轮次，其中包含 Compacted 压缩记录 → 加入回滚一轮 → 恢复历史 → 期望上一轮设置和参考上下文仍来自第一轮。

调用关系：它走 record_initial_history 的恢复路径，重点盯住压缩记录和回滚记录一起出现时的处理。断言检查会话最终保存的设置没有被未完成轮次覆盖。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 4 个（from, assert_eq!, Resumed, vec!）。

async fn record_initial_history_resumed_bare_turn_context_does_not_seed_reference_context_item()

作用：这个测试确认：只有一个孤立的 TurnContextItem 时，不能把它当作 reference_context_item。参考上下文必须来自能证明它属于某个有效轮次的记录。

数据流：把当前 turn_context 转成 TurnContextItem → 单独作为恢复历史传给 record_initial_history → 查询 reference_context_item → 期望为空。

调用关系：它和裸 TurnContext 不填充上一轮设置的测试相呼应，只专门检查 reference_context_item。record_initial_history 是被测入口。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 4 个（from, assert!, Resumed, vec!）。

async fn record_initial_history_resumed_does_not_seed_reference_context_item_after_compaction()

作用：这个测试确认：如果裸 TurnContextItem 后面紧跟历史压缩，系统不会拿压缩前的上下文当参考。压缩相当于重写了聊天记忆，旧基准不能随便沿用。

数据流：构造一个 TurnContextItem，再加一个带 replacement_history 的 Compacted 项 → 恢复到会话 → 查询 previous_turn_settings 和 reference_context_item → 期望都为空。

调用关系：它测试 record_initial_history 对压缩事件的清理效果。Compacted 记录是关键输入，用来确认恢复逻辑不会越过压缩继续信任旧上下文。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 5 个（from, assert!, assert_eq!, Resumed, vec!）。

async fn reconstruct_history_legacy_compaction_without_replacement_history_does_not_inject_current_initial_context()

作用：这个测试确认：旧格式的压缩记录没有 replacement_history 时，系统不会偷偷把当前会话的初始上下文塞进历史。它只应该把旧摘要当成一条用户消息保留下来。

数据流：构造压缩前的用户消息和助手回复，再加一个没有 replacement_history 的 legacy Compacted 摘要 → 调用重建 → 期望历史里是原用户消息和摘要用户消息，reference_context_item 为空。

调用关系：它直接测试 reconstruct_history_from_rollout 对旧压缩格式的兼容。这里不用 record_initial_history，避免会话状态干扰，专看重建结果。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 3 个（assert!, assert_eq!, vec!）。

async fn reconstruct_history_legacy_compaction_without_replacement_history_clears_later_reference_context_item()

作用：这个测试确认：遇到旧格式压缩后，即使后面又出现了 TurnContextItem，也不能建立参考上下文。旧压缩缺少替换历史，说明上下文边界不可靠。

数据流：先放一条用户消息和旧格式 Compacted → 后面再放一轮带 TurnContextItem 的用户轮次 → 调用重建 → 期望 reference_context_item 仍然为空。

调用关系：它测试 reconstruct_history_from_rollout 的保守策略。后面的 TurnContextItem 看似可用，但因为前面有 legacy 压缩，重建逻辑必须避免建立错误基准。

调用图：调用 1 个内部函数（make_session_and_context）；外部调用 2 个（assert!, vec!）。

async fn record_initial_history_resumed_turn_context_after_compaction_reestablishes_reference_context_item()

作用：这个测试确认：带 replacement_history 的现代压缩会先清掉旧基准，但如果同一有效轮次后面又出现 TurnContextItem，它可以重新建立参考上下文。

数据流：构造一个用户轮次：开始、用户消息、现代 Compacted、随后 TurnContextItem、完成 → 恢复到会话 → 期望 previous_turn_settings 和 reference_context_item 都来自压缩后的 TurnContextItem。

调用关系：它测试 record_initial_history 对“压缩后重新建立基准”的处理。Compacted 先让旧参考失效，后面的 TurnContextItem 再成为新的可靠来源。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 4 个（from, assert_eq!, Resumed, vec!）。

async fn record_initial_history_resumed_aborted_turn_without_id_clears_active_turn_for_compaction_accounting()

作用：这个测试确认：一个正在进行的轮次如果收到没有 turn_id 的中止事件，系统应把当前活跃轮次清掉。这样后续压缩不会被错误归到这个已经中止的轮次上。

数据流：先构造一轮已完成的有效上下文 → 再构造一轮开始、有用户消息、随后 TurnAborted 但没有 turn_id → 后面放一个 Compacted → 恢复历史 → 期望上一轮设置仍来自已完成轮次，但 reference_context_item 被清空。

调用关系：它测试 record_initial_history 处理异常中止和压缩统计的配合。TurnAborted 没有 id 是关键情况，恢复逻辑必须把活跃轮次状态安全关闭。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 5 个（from, assert!, assert_eq!, Resumed, vec!）。

async fn record_initial_history_resumed_unmatched_abort_preserves_active_turn_for_later_turn_context()

作用：这个测试确认：如果中止事件带的 turn_id 和当前活跃轮次对不上，不能误把当前轮次关掉。后面出现的 TurnContextItem 仍应归到当前轮次。

数据流：先构造一轮旧的已完成上下文 → 再开始一个 current-turn 用户轮次 → 插入一个指向 other-turn 的 TurnAborted → 随后放 current-turn 的 TurnContextItem 和完成事件 → 恢复历史 → 期望上一轮设置和参考上下文来自 current-turn。

调用关系：它测试 record_initial_history 对中止事件的匹配规则。只有匹配当前 turn_id 的中止才应影响活跃轮次；不匹配的中止应被忽略。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 4 个（from, assert_eq!, Resumed, vec!）。

async fn record_initial_history_resumed_trailing_incomplete_turn_compaction_clears_reference_context_item()

作用：这个测试确认：如果日志末尾有一轮未完成用户轮次，并且它发生了压缩，参考上下文要被清空。因为最后状态已经被压缩改写，但没有完整轮次来重新确认基准。

数据流：先构造一轮已完成的有效上下文 → 再构造末尾未完成轮次：开始、用户消息、Compacted → 恢复历史 → 期望 previous_turn_settings 保留前一轮设置，但 reference_context_item 为空。

调用关系：它测试 record_initial_history 面对“日志到这里断了”的情况。压缩发生在未完成轮次里，所以恢复逻辑不能继续信任前一轮参考上下文。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 5 个（from, assert!, assert_eq!, Resumed, vec!）。

async fn record_initial_history_resumed_trailing_incomplete_turn_preserves_turn_context_item()

作用：这个测试确认：日志末尾的未完成轮次如果已经写下 TurnContextItem，系统仍可以用它作为上一轮设置和参考上下文。未完成不一定无效，关键是有没有可靠上下文记录。

数据流：构造一个开始了、有用户消息、有 TurnContextItem、但没有完成事件的轮次 → 恢复到会话 → 期望 previous_turn_settings 和 reference_context_item 都来自这个 TurnContextItem。

调用关系：它测试 record_initial_history 对尾部未完成轮次的宽容处理。和带压缩的尾部未完成测试相反，这里没有压缩破坏基准，所以 TurnContextItem 可以保留。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 4 个（from, assert_eq!, Resumed, vec!）。

async fn record_initial_history_resumed_replaced_incomplete_compacted_turn_clears_reference_context_item()

作用：这个测试确认：一个未完成且发生过压缩的轮次，如果后来被新的 TurnStarted 顶替，旧轮次不能继续提供参考上下文。这样可以避免把已经被新轮次替换的半截状态当成有效基准。

数据流：先构造一轮已完成的有效上下文 → 再构造一个未完成用户轮次并加入 Compacted → 随后出现新的 TurnStarted，表示旧未完成轮次被替换 → 恢复历史 → 期望 previous_turn_settings 仍是旧已完成轮次，但 reference_context_item 为空。

调用关系：它测试 record_initial_history 对连续 TurnStarted 的处理。新的轮次开始会让前一个未完成压缩轮次失去资格，恢复逻辑必须清掉参考上下文。

调用图：调用 2 个内部函数（make_session_and_context, default）；外部调用 5 个（from, assert!, assert_eq!, Resumed, vec!）。

fn meta(value: Value) -> Option<Meta>

作用：这个小工具函数把一段 JSON 值包装成测试里需要的 Meta 元数据。它要求传进来的必须是 JSON 对象，也就是一组键值对；如果不是，就直接让测试失败。

数据流：进去的是一个 JSON 值 → 它先检查这个值是不是对象 → 如果是，就把里面的键值对装进 Meta 并返回 Some；如果不是对象，就触发 panic，让测试立刻报错。

调用关系：它是测试造数据时的基础零件。guardian_meta 会用它来生成标准 Guardian 元数据；一些测试也会直接调用它，故意构造缺字段或形状不完整的元数据，来检查正式逻辑会不会拒绝这些请求。

调用图：被 3 处调用（guardian_elicitation_review_request_declines_unsupported_opt_in_shapes, guardian_elicitation_review_request_requires_opt_in, guardian_meta）；外部调用 1 个（panic!）。

fn guardian_meta(tool_params: Option<Value>) -> Option<Meta>

作用：这个函数帮测试快速生成一份“这是 Guardian MCP 工具调用审批”的标准元数据。它像填好大部分内容的表格，只允许测试按需补上工具参数。

数据流：进去的是可选的 tool_params，也就是工具调用参数 → 它先创建一份包含审批类型、请求类型、连接器名字、工具名字等字段的 JSON 对象 → 如果传了工具参数，就把它放进 tool_params 字段 → 最后交给 meta 包装成 Meta。

调用关系：多个测试用它来搭建“看起来合法、已经选择走 Guardian 审批”的请求。它内部把真正包装 Meta 的工作交给 meta，然后这些元数据会被 form_request 放进 MCP 表单请求里。

调用图：调用 1 个内部函数（meta）；被 3 处调用（guardian_elicitation_review_request_builds_mcp_tool_call, guardian_elicitation_review_request_declines_unsupported_opt_in_shapes, guardian_elicitation_review_request_defaults_missing_tool_params）；外部调用 1 个（json!）。

fn form_request(meta: Option<Meta>) -> ElicitationReviewRequest

作用：这个函数帮测试生成一个 MCP 表单式审批请求。它把服务器名、请求编号、提示语和元数据拼成一份完整请求，省得每个测试重复写一大段样板。

数据流：进去的是可选的 Meta 元数据 → 它创建一个服务器名为 browser-use、请求编号为 7 的 ElicitationReviewRequest → 请求内容是一个表单确认请求，提示语是“Allow origin?”，并带一个空的表单 schema → 出来的是完整的测试请求对象。

调用关系：它是多条测试的共同造数入口。测试先用 meta 或 guardian_meta 准备元数据，再交给 form_request 生成请求，之后再把请求送进被测的 guardian_elicitation_review_request 等正式函数。

调用图：被 4 处调用（guardian_elicitation_review_request_builds_mcp_tool_call, guardian_elicitation_review_request_declines_unsupported_opt_in_shapes, guardian_elicitation_review_request_defaults_missing_tool_params, guardian_elicitation_review_request_requires_opt_in）；外部调用 2 个（builder, Number）。

fn guardian_elicitation_review_request_builds_mcp_tool_call()

作用：这个测试确认：当 MCP 请求带着完整的 Guardian 工具调用审批信息时，系统会正确生成 Guardian 的 MCP 工具调用审批请求。它重点检查工具名、参数、连接器信息这些关键字段有没有丢。

数据流：它先用 guardian_meta 造出带 origin 参数的元数据，再用 form_request 做成 MCP 请求 → 然后调用被测逻辑 guardian_elicitation_review_request → 最后逐项检查输出：审批 ID、服务器、工具名、参数、连接器名称和工具标题都必须符合预期。

调用关系：这是主路径测试，也就是最正常、最应该成功的场景。它依赖 guardian_meta 和 form_request 造请求，然后检验正式转换函数能不能产出 GuardianApprovalRequest::McpToolCall。

调用图：调用 2 个内部函数（form_request, guardian_meta）；外部调用 3 个（assert_eq!, json!, panic!）。

fn guardian_elicitation_review_request_defaults_missing_tool_params()

作用：这个测试确认：如果请求声明了要走 Guardian 工具调用审批，但没有提供工具参数，系统会把参数当成空对象，而不是报错或变成空值。

数据流：它先用 guardian_meta 生成不带 tool_params 的元数据，再用 form_request 包成请求 → 调用 guardian_elicitation_review_request → 从结果里取出 arguments 字段 → 检查它是 Some({})，也就是“有参数，只是空的”。

调用关系：它覆盖主路径里的一个边角情况。和成功构建测试一样，它用 guardian_meta 与 form_request 搭数据，但重点不是所有字段，而是缺少 tool_params 时的默认行为。

调用图：调用 2 个内部函数（form_request, guardian_meta）；外部调用 2 个（assert_eq!, panic!）。

fn plugin_install_elicitation_telemetry_metadata_requires_install_tool_suggestion()

作用：这个测试确认：只有“建议安装插件”的 MCP 提示请求，才会被提取成插件安装遥测信息。遥测可以理解成给系统记录事件用的数据，方便之后统计或排查。

数据流：它先造一个 suggest_type 为 install 的插件建议事件 → 调用 plugin_install_elicitation_telemetry_metadata → 检查能得到插件类型、插件 ID、插件名称。接着它再造一个 suggest_type 为 enable 的事件 → 再次调用同一个函数 → 检查结果是 None，表示这不是安装事件，不该记录成安装遥测。

调用关系：这个测试不走 form_request 那套 Guardian 工具调用路径，而是直接构造 EventMsg::ElicitationRequest。它专门保护遥测提取逻辑，确保只有安装建议会被算作插件安装相关事件。

调用图：外部调用 4 个（String, assert_eq!, json!, ElicitationRequest）。

fn guardian_elicitation_review_request_requires_opt_in()

作用：这个测试确认：请求光说自己是 MCP 工具调用还不够，还必须明确带上正确的 Guardian 审批请求标记。没有这个“选择加入”标记，系统就不会把它交给 Guardian。

数据流：它用 meta 构造一份缺少 codex_request_type 的元数据，再用 form_request 做成 MCP 请求 → 调用 guardian_elicitation_review_request → 检查结果是 NotRequested，也就是系统认为这不是一个真正要求 Guardian 审批的请求。

调用关系：它测试的是安全入口条件。它调用 meta 和 form_request 来做一个“不完整但看起来有点像”的请求，用来确认正式逻辑不会误判、不会随便启动 Guardian 审批流程。

调用图：调用 2 个内部函数（form_request, meta）；外部调用 2 个（assert_eq!, json!）。

fn guardian_elicitation_review_request_declines_unsupported_opt_in_shapes()

作用：这个测试确认：就算请求声明要走 Guardian 审批，只要请求形状不被支持，系统也会拒绝，而不是勉强处理。这里的“形状”包括请求类型、表单内容、关键字段是否齐全。

数据流：它依次构造三类问题请求：一种是 URL 式请求，不是支持的表单式请求；一种是表单里要求额外字段 confirmed；一种是缺少 tool_name → 每个请求都会被送进 guardian_elicitation_review_request → 测试检查结果都属于 Decline，表示系统明确拒绝处理。

调用关系：它是安全边界测试。它会用 guardian_meta、meta、form_request 以及 schema 构造工具，专门制造不受支持的输入，确认正式转换逻辑在这些情况下会保守地拒绝。

调用图：调用 3 个内部函数（form_request, guardian_meta, meta）；外部调用 6 个（new, builder, Boolean, assert!, json!, Number）。

fn guardian_decisions_map_to_elicitation_responses_without_session_state()

作用：这个测试确认：即使没有额外会话状态，Guardian 的审批结果也能被稳定转换成 MCP 响应。比如批准就是接受，拒绝或超时就是拒绝，取消就是取消。

数据流：它分别传入 Approved、Denied、TimedOut、Abort 四种 Guardian 决定，以及可选的拒绝说明 → 调用 mcp_elicitation_response_from_guardian_decision_parts → 检查输出的 ElicitationResponse 是否有正确的 action、content 和 meta；超时时还要带上标准超时说明。

调用关系：它检查的是审批链路的返回方向。前面的测试关注 MCP 请求如何变成 Guardian 请求；这个测试关注 Guardian 决定如何变回 MCP 能理解的响应，保证整条审批闭环能正确结束。

调用图：外部调用 1 个（assert_eq!）。

async fn merge_connector_selection_deduplicates_entries()

作用：这个测试确认：把连接器选择合并进会话状态时，重复的名字只会保留一份。这样用户或系统重复传入同一个连接器时，不会让状态里出现一堆重复项。

数据流：进去的是一份测试用会话配置，以及三个连接器名字，其中 calendar 出现了两次。测试先用配置创建一个新的 SessionState，然后把这些名字合并进去。出来的结果应该是一个集合，只包含 calendar 和 drive 各一次；测试用断言检查实际结果和预期完全一样。

调用关系：测试运行器启动这个异步测试后，它先调用 make_session_configuration_for_tests 准备一份安全的假配置，再调用 SessionState::new 创建状态对象。核心动作交给状态对象的合并选择逻辑完成，最后用 assert_eq! 做验收。

调用图：调用 2 个内部函数（make_session_configuration_for_tests, new）；外部调用 1 个（assert_eq!）。

async fn clear_connector_selection_removes_entries()

作用：这个测试确认：调用清空连接器选择后，之前保存的连接器会全部消失。它防止用户明明取消了选择，系统却还继续带着旧连接器工作。

数据流：进去的是测试会话配置和一个临时加入的 calendar 连接器。测试先建出 SessionState，再把 calendar 合并进去，接着调用清空方法。出来时再读取连接器选择，应该是一个空集合；断言负责确认确实没有残留。

调用关系：它和上一条测试一样，先靠 make_session_configuration_for_tests 和 SessionState::new 搭好测试场景。不同的是，它关注的是清理动作：先制造一条旧数据，再检查 clear_connector_selection 是否把这条数据彻底拿掉。

调用图：调用 2 个内部函数（make_session_configuration_for_tests, new）；外部调用 1 个（assert_eq!）。

async fn set_rate_limits_defaults_limit_id_to_codex_when_missing()

作用：这个测试确认：设置速率限制时，如果传入的数据没有写明是哪一种限制，系统会默认把它当作 codex。速率限制就是一段时间内能用多少服务的规则；默认值能避免后续代码因为缺少编号而判断不清。

数据流：进去的是一份没有 limit_id 的 RateLimitSnapshot，也就是一张“限额快照”。里面有主要窗口的使用比例、窗口分钟数、重置时间，但没有说明限制编号。测试把它写入 SessionState 后，再读取 latest_rate_limits，期望看到 limit_id 被补成 codex。

调用关系：测试先调用 make_session_configuration_for_tests 准备配置，再用 SessionState::new 建状态。真正被检查的是 SessionState 的 set_rate_limits 行为；assert_eq! 最后确认缺失的编号有没有被自动补上。

调用图：调用 2 个内部函数（make_session_configuration_for_tests, new）；外部调用 1 个（assert_eq!）。

async fn replace_history_clears_auto_compact_window_prefill()

作用：这个测试确认：替换整段对话历史时，自动压缩窗口的预填 token 估算会被清空。token 可以理解成模型阅读文本时用的小块计数；历史都换了，旧的估算就不能再拿来用。

数据流：进去的是一个新会话状态，先人为设置 auto compact 的预估预填数量为 100。随后测试用空历史替换当前历史，并且不提供参考上下文项。出来时读取 auto_compact_window_snapshot，预期里面的 prefill_input_tokens 变成 None，表示旧估算已经失效并被清掉。

调用关系：这个测试由测试运行器调用。它先通过 make_session_configuration_for_tests 和 SessionState::new 搭环境，再用设置预填值的方法制造旧状态，然后调用 replace_history 触发清理。最后通过 auto_compact_window_snapshot 观察结果，并用 assert_eq! 对比。

调用图：调用 2 个内部函数（make_session_configuration_for_tests, new）；外部调用 2 个（new, assert_eq!）。

async fn set_rate_limits_defaults_to_codex_when_limit_id_missing_after_other_bucket()

作用：这个测试确认：即使之前保存过 codex_other 这类别的限额桶，下一次如果新数据没带 limit_id，也仍然要默认成 codex，而不是沿用旧桶。这样可以避免旧状态误导新限额数据。

数据流：进去先是一份明确标成 codex_other 的限额快照，随后又进去一份没有 limit_id 的新限额快照。测试先把 codex_other 写入状态，再写入缺少编号的新快照。出来时读取 latest_rate_limits，预期 limit_id 是 codex，说明系统没有被之前的 codex_other 带偏。

调用关系：它先用 make_session_configuration_for_tests 和 SessionState::new 建好测试对象。整个故事分两步：先放入一个“旧桶”，再放入一个“没写桶名的新数据”。被验证的仍是 set_rate_limits 的默认规则，最后 assert_eq! 检查最终编号。

调用图：调用 2 个内部函数（make_session_configuration_for_tests, new）；外部调用 1 个（assert_eq!）。

async fn set_rate_limits_carries_account_metadata_from_codex_to_codex_other()

作用：这个测试确认：从 codex 限额切到 codex_other 限额时，如果新快照没有带账户信息，系统会沿用之前已有的账户信息。账户信息包括余额、消费控制上限、套餐类型等，丢了会让界面或判断变得不完整。

数据流：进去先是一份 codex 快照，里面有使用比例、余额 credits、个人消费上限 individual_limit、套餐 plan_type。然后进去一份 codex_other 快照，它有新的限额窗口，但没有余额、消费上限和套餐。测试把两份快照依次写入状态。出来的 latest_rate_limits 应该使用 codex_other 的新限额窗口，同时保留前一份 codex 快照里的账户元数据。

调用关系：测试运行时先通过 make_session_configuration_for_tests 和 SessionState::new 搭出空状态。它连续两次调用 set_rate_limits，模拟服务端先给完整账号信息、后给另一个限额桶的局部信息。最后用 assert_eq! 检查最终快照是不是把“新的桶信息”和“旧的账号信息”正确拼在了一起。

调用图：调用 2 个内部函数（make_session_configuration_for_tests, new）；外部调用 1 个（assert_eq!）。

fn error_completion_message_stays_below_manual_review_threshold()

作用：这个测试确认：当子代理带着超长错误信息结束时，生成出来的完成消息仍然会被控制在安全长度内，并且还保留告诉用户下一步该做什么的提示。

数据流：进去的是一个根代理路径、一个子代理路径，以及一段被故意放大到很长的错误状态文字。测试把这些交给完成消息生成函数，拿到一段最终消息；然后用近似 token 计数检查它够不够短，再检查里面是否包含固定的错误后续动作提示。出来的结果不是业务数据，而是测试通过或失败：通过表示长度控制和关键提示都正常，失败表示有人改代码时破坏了这个保证。

调用关系：这个函数在测试运行时由测试框架自动调用。它先用 root 和 try_from 准备两个代理路径，再用 Errored 构造一个错误状态，随后把这些交给 format_inter_agent_completion_message 生成实际消息，最后用断言检查消息长度和内容。它不是正常产品流程的一部分，而是给生成提示消息的逻辑加一道防线。

调用图：调用 2 个内部函数（root, try_from）；外部调用 3 个（assert!, Errored, format_inter_agent_completion_message）。

async fn process_compacted_history_with_test_session(
    compacted_history: Vec<ResponseItem>,
    previous_turn_settings: Option<&PreviousTurnSettings>,
) -> (Vec<ResponseItem>, Vec<ResponseItem>)

作用：这是测试用的小帮手，用来快速搭一个假的会话环境，然后把一份压缩后的历史交给真实处理函数跑一遍。这样每个测试不用重复写创建会话、设置上一轮参数这些准备工作。

数据流：进去的是一段压缩后的消息列表，以及可选的上一轮设置；它先创建测试会话和上下文，再把上一轮设置放进会话，接着生成系统当前应该有的初始上下文，最后调用压缩历史处理函数；出来的是处理后的历史，以及那份初始上下文，方便测试拿来对比。

调用关系：多个异步测试都会先找它搭舞台。它内部把工作交给 make_session_and_context 创建测试会话，再交给 process_compacted_history 做真正的历史刷新。调用它的测试主要关心旧消息该删什么、新上下文该插到哪里。

调用图：调用 2 个内部函数（process_compacted_history, make_session_and_context）；被 6 处调用（process_compacted_history_drops_legacy_warnings, process_compacted_history_drops_non_user_content_messages, process_compacted_history_inserts_context_before_last_real_user_message_only, process_compacted_history_reinjects_full_initial_context, process_compacted_history_reinjects_model_switch_message, process_compacted_history_replaces_developer_messages）。

fn user_message(text: &str) -> ResponseItem

作用：这是测试里造“普通用户消息”的小工具。它让测试代码不用每次手写一大段消息结构，只要给一句文本就能得到一条用户消息。

数据流：进去的是一段文字；它把这段文字包成 ResponseItem::Message，角色设为 user，内容设为输入文本；出来的是一条可放进聊天历史里的用户消息，其他字段保持空值。

调用关系：process_compacted_history_drops_legacy_warnings 用它来制造几条旧警告和一条真实用户消息。它只负责造测试数据，不参与真实压缩逻辑。

调用图：被 1 处调用（process_compacted_history_drops_legacy_warnings）；外部调用 1 个（vec!）。

fn compacted_user_message(text: &str) -> CompactedUserMessage

作用：这是测试里造“压缩阶段记录的用户消息”的小工具。它把普通文字包装成 CompactedUserMessage，方便测试压缩历史构建函数。

数据流：进去的是一段文字；它把文字放到 message 字段里，并把 metadata 设为空；出来的是一条压缩用的用户消息对象。

调用关系：build_token_limited_compacted_history_truncates_overlong_user_messages 用它制造一条特别长的用户消息，再交给 build_compacted_history_with_limit 检查是否会被截断。

调用图：被 1 处调用（build_token_limited_compacted_history_truncates_overlong_user_messages）。

fn content_items_to_text_joins_non_empty_segments()

作用：这个测试确认：把多段文本内容合成一段文字时，空文本会被跳过，非空文本会用换行连起来。

数据流：进去的是一组内容片段，其中有 hello、空字符串和 world；测试调用 content_items_to_text；出来应该是 Some("hello\nworld")，说明空段没参与拼接。

调用关系：它直接检查 content_items_to_text 的行为。这个函数的正确性会影响后面很多测试，因为测试常用它从消息内容里取出可读文字。

调用图：外部调用 2 个（assert_eq!, vec!）。

fn content_items_to_text_ignores_image_only_content()

作用：这个测试确认：如果一条内容只有图片，没有文字，那么系统不会硬把它当成文本消息。

数据流：进去的是一组只包含图片链接的内容片段；测试调用 content_items_to_text；出来应该是 None，表示没有可提取的文字。

调用关系：它直接约束 content_items_to_text 的边界行为，避免图片内容在压缩或过滤时被误判成用户文本。

调用图：外部调用 2 个（assert_eq!, vec!）。

fn collect_user_messages_extracts_user_text_only()

作用：这个测试确认：收集用户消息时，只拿用户角色的文字，不拿助手消息，也不拿无关类型的项目。

数据流：进去的是三项历史：一条助手消息、一条用户消息、一个 Other；测试调用 collect_user_messages；出来只应该有用户说的 first。

调用关系：它检查 collect_user_messages 的基本筛选能力。这个能力是构建压缩历史的前置步骤，因为压缩时只应该整理真正的用户输入。

调用图：外部调用 2 个（assert_eq!, vec!）。

fn collect_user_messages_filters_session_prefix_entries()

作用：这个测试确认：系统自动塞进会话开头的说明，比如 AGENTS.md 指令和环境信息，不会被当作用户真正说的话。

数据流：进去的是三条 user 角色消息：项目指令、环境上下文、真实用户消息；测试调用 collect_user_messages；出来只剩 real user message。

调用关系：它检查 collect_user_messages 对“看起来像用户消息、其实是系统上下文”的过滤规则。这能避免压缩历史时把自动说明重复保存。

调用图：外部调用 2 个（assert_eq!, vec!）。

fn collect_user_messages_filters_legacy_warnings()

作用：这个测试确认：一些老版本系统自动发出的警告文字，不会被当成用户消息保存进压缩历史。

数据流：进去的是三条旧警告和一条真实用户消息；测试调用 collect_user_messages；出来只应该包含 real user message。

调用关系：它检查 collect_user_messages 对遗留警告的过滤能力。这样旧系统提示不会污染后续对话摘要。

调用图：外部调用 2 个（assert_eq!, vec!）。

fn build_token_limited_compacted_history_truncates_overlong_user_messages()

作用：这个测试确认：如果用户消息长到超过限制，构建压缩历史时会截短它，而不是把超大文本原样塞进去。

数据流：进去的是一个很小的 token 限制、一条重复很多次的超长用户文本，以及摘要 SUMMARY；测试调用 build_compacted_history_with_limit；出来应该有两条消息：第一条是被截断并带有“tokens truncated”提示的用户消息，第二条是完整摘要。

调用关系：它先用 compacted_user_message 造长消息，再把活交给 build_compacted_history_with_limit。它保护的是压缩历史的大小控制，避免长消息继续撑爆上下文。

调用图：调用 1 个内部函数（compacted_user_message）；外部调用 6 个（new, assert!, assert_eq!, panic!, from_ref, build_compacted_history_with_limit）。

fn build_token_limited_compacted_history_appends_summary_message()

作用：这个测试确认：构建压缩历史时，摘要文本会作为最后一条用户消息追加进去。

数据流：进去的是空初始上下文、一条用户消息和 summary text；测试调用 build_compacted_history；出来的历史不应为空，并且最后一项的文字必须等于 summary text。

调用关系：它检查 build_compacted_history 的核心输出形状。摘要放在末尾很重要，因为后续模型读取历史时通常会把最后的总结当作最新压缩结果。

调用图：外部调用 5 个（new, assert!, assert_eq!, panic!, vec!）。

fn build_compacted_history_preserves_user_message_metadata()

作用：这个测试确认：用户消息自带的元数据不会在构建压缩历史时丢失。元数据可以理解为消息的小标签，比如属于哪一轮对话。

数据流：进去的是一条带 turn_id 为 turn-1 的压缩用户消息，以及一段摘要；测试调用 build_compacted_history；出来的第一条历史仍然带 turn-1，而摘要消息没有这个 turn_id。

调用关系：它检查 build_compacted_history 对附加信息的保留。这样后续追踪对话轮次时，不会因为压缩而丢掉线索。

调用图：外部调用 2 个（new, assert_eq!）。

fn should_use_remote_compact_task_for_azure_provider()

作用：这个测试确认：当模型提供方是 Azure 时，系统会选择使用远程压缩任务。

数据流：进去的是一个手工构造的 Azure 模型提供方配置；测试调用 should_use_remote_compact_task；出来应该是真，表示要走远程压缩。

调用关系：它直接检查 should_use_remote_compact_task 的选择规则。这个规则决定压缩任务是在本地做，还是交给远端服务做。

调用图：外部调用 1 个（assert!）。

async fn process_compacted_history_replaces_developer_messages()

作用：这个测试确认：压缩历史里旧的 developer 消息会被新的初始上下文替换。developer 消息可以理解为给模型看的系统级操作说明。

数据流：进去的是一段历史，里面夹着两条过期 developer 消息和一条用户摘要；测试通过 process_compacted_history_with_test_session 处理；出来应该是当前会话的新初始上下文，再加上那条用户摘要，旧 developer 内容不再保留。

调用关系：它调用测试帮手搭会话，真正的刷新工作由 process_compacted_history 完成。这个测试保证权限、人格等开发者指令不会沿用旧版本。

调用图：调用 1 个内部函数（process_compacted_history_with_test_session）；外部调用 2 个（assert_eq!, vec!）。

async fn process_compacted_history_reinjects_full_initial_context()

作用：这个测试确认：即使压缩历史里只有摘要，系统也会重新补上完整的初始上下文。

数据流：进去的是一条用户摘要；测试处理后拿到 refreshed 和 expected 初始上下文；出来应该等于“当前初始上下文 + 摘要消息”。

调用关系：它通过 process_compacted_history_with_test_session 调用真实处理流程。它验证的是压缩恢复时不能只带摘要，还必须带上当前运行所需的规则和环境。

调用图：调用 1 个内部函数（process_compacted_history_with_test_session）；外部调用 2 个（assert_eq!, vec!）。

async fn process_compacted_history_drops_non_user_content_messages()

作用：这个测试确认：压缩历史里的项目说明、环境上下文、中断记录、旧开发者指令等自动内容会被丢掉，只留下真正有用的用户摘要。

数据流：进去的是多条看起来像 user 的系统内容、一条 summary、以及一条旧 developer 消息；测试调用处理流程；出来应该是新的初始上下文加 summary，不包含那些自动生成的旧内容。

调用关系：它通过 process_compacted_history_with_test_session 进入真实处理函数。这个测试覆盖的是“清理旧上下文垃圾”的场景，防止恢复后的历史重复或过期。

调用图：调用 1 个内部函数（process_compacted_history_with_test_session）；外部调用 2 个（assert_eq!, vec!）。

async fn process_compacted_history_drops_legacy_warnings()

作用：这个测试确认：处理压缩历史时，会丢掉旧版本留下的警告消息，但保留最新的真实用户消息。

数据流：进去的是三条旧警告和一条 latest user；测试调用处理流程；出来应该是当前初始上下文加 latest user，不包含警告。

调用关系：它用 user_message 快速造消息，再用 process_compacted_history_with_test_session 跑完整流程。它和收集用户消息的警告过滤测试互相补充，一个测小函数，一个测完整流程。

调用图：调用 2 个内部函数（process_compacted_history_with_test_session, user_message）；外部调用 2 个（assert_eq!, vec!）。

async fn process_compacted_history_inserts_context_before_last_real_user_message_only()

作用：这个测试确认：重新插入初始上下文时，要插在最后一条真实用户消息前面，而不是插到摘要前或随便插。

数据流：进去的是 older user、一条带 SUMMARY_PREFIX 的摘要消息、latest user；测试处理后；出来应该保持 older user 和摘要在前，然后插入初始上下文，最后才是 latest user。

调用关系：它通过 process_compacted_history_with_test_session 调真实流程，重点验证插入位置。这个位置很关键，因为最新用户请求前必须有最新规则，模型才能按当前规则回答。

调用图：调用 1 个内部函数（process_compacted_history_with_test_session）；外部调用 2 个（assert_eq!, vec!）。

async fn process_compacted_history_reinjects_model_switch_message()

作用：这个测试确认：如果上一轮用的是不同模型，系统会在初始上下文里重新加入模型切换提示。

数据流：进去的是一条摘要，以及 previous_turn_settings，里面写着上一轮模型名；处理后，测试先检查初始上下文第一条 developer 消息含有 <model_switch>，再确认最终历史是初始上下文加摘要。

调用关系：它调用 process_compacted_history_with_test_session，并把上一轮设置传进去。真实流程会根据这些设置生成模型切换说明，让模型知道对话是从另一个模型接过来的。

调用图：调用 1 个内部函数（process_compacted_history_with_test_session）；外部调用 4 个（assert!, assert_eq!, panic!, vec!）。

fn insert_initial_context_before_last_real_user_or_summary_keeps_summary_last()

作用：这个测试确认：当历史末尾是压缩摘要时，插入新的初始上下文不能把摘要挤到中间乱掉；摘要仍然要留在最后。

数据流：进去的是 older user、latest user、summary 三条历史，以及一条新的 developer 上下文；测试调用 insert_initial_context_before_last_real_user_or_summary；出来应该是 older user、developer 上下文、latest user、summary。

调用关系：它直接测试插入初始上下文的辅助函数。这个函数是压缩历史恢复流程里的排版工，负责把新规则放到合适位置，同时保持摘要的特殊末尾位置。

调用图：外部调用 2 个（assert_eq!, vec!）。

fn insert_initial_context_before_last_real_user_or_summary_keeps_compaction_last()

作用：这个测试确认：如果历史最后是一条加密压缩内容，插入初始上下文时也不能把这条压缩内容挪走；它仍然留在最后。

数据流：进去的是一条 Compaction 加密压缩记录，以及一条新的 developer 上下文；测试调用 insert_initial_context_before_last_real_user_or_summary；出来应该先是 developer 上下文，最后仍是原来的 Compaction。

调用关系：它直接检查插入辅助函数对特殊 Compaction 项的处理。这样恢复历史时，系统补充新规则的同时，不会破坏压缩记录本身的位置。

调用图：外部调用 2 个（assert_eq!, vec!）。

fn assistant_msg(text: &str) -> ResponseItem

作用：造一条助手发出的普通文字消息，方便测试里反复使用。它让测试不用每次手写完整的消息结构。

数据流：输入一段文字 → 包成角色为 assistant、内容为输出文本的 ResponseItem → 返回这条假助手消息，不改动外部状态。

调用关系：多个测试用它搭建历史记录，例如过滤消息、回滚用户轮次、旧版多智能体消息判断等；它只是测试数据工厂，不再把活交给项目里的核心逻辑。

调用图：被 3 处调用（drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns, filters_non_api_messages, legacy_inter_agent_assistant_messages_are_not_turn_boundaries）；外部调用 1 个（vec!）。

fn inter_agent_assistant_msg(text: &str) -> ResponseItem

作用：造一条“助手发给另一个智能体”的消息，用来测试多智能体协作场景。多智能体就是一个主助手把任务交给另一个助手或 worker。

数据流：输入文字 → 先创建一段带作者、接收者和内容的 InterAgentCommunication，再序列化成 JSON 字符串 → 包成 assistant 消息返回。

调用关系：多智能体边界相关测试会调用它，然后把生成的消息交给 is_user_turn_boundary、for_prompt 或 drop_last_n_user_turns 检查。

调用图：调用 2 个内部函数（root, new）；被 3 处调用（drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns, for_prompt_preserves_inter_agent_assistant_messages, inter_agent_assistant_messages_are_turn_boundaries）；外部调用 2 个（new, vec!）。

fn create_history_with_items(items: Vec<ResponseItem>) -> ContextManager

作用：用一批假历史项快速创建 ContextManager。ContextManager 可以理解为“对话历史账本”。

数据流：输入 ResponseItem 列表 → 新建历史管理器，并用固定的 10000 token 裁剪策略记录这些项 → 返回装好数据的历史对象。

调用关系：大多数测试都从这里开始搭建场景；它调用 ContextManager::new 和 record_items，把测试数据送进真正的历史记录逻辑。

调用图：调用 1 个内部函数（new）；被 38 处调用（drop_last_n_user_turns_clears_reference_context_for_mixed_developer_context_bundles, drop_last_n_user_turns_ignores_session_prefix_user_messages, drop_last_n_user_turns_preserves_prefix, drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns, drop_last_n_user_turns_trims_context_updates_above_rolled_back_turn, estimate_token_count_with_base_instructions_uses_provided_text, for_prompt_clears_image_generation_result_when_images_are_unsupported, for_prompt_preserves_image_generation_calls_when_images_are_supported, for_prompt_preserves_inter_agent_assistant_messages, for_prompt_strips_images_when_model_does_not_support_images (+15 more)）；外部调用 1 个（Tokens）。

fn user_msg(text: &str) -> ResponseItem

作用：造一条用户发出的普通输出文本消息，供测试使用。

数据流：输入文字 → 包成角色为 user、内容为 OutputText 的 ResponseItem → 返回这条用户消息。

调用关系：过滤、token 追加计算等测试用它构造用户发言，再交给历史管理器记录或估算。

调用图：被 3 处调用（filters_non_api_messages, items_after_last_model_generated_tokens_include_user_and_tool_output, total_token_usage_includes_all_items_after_last_model_generated_item）；外部调用 1 个（vec!）。

fn user_input_text_msg(text: &str) -> ResponseItem

作用：造一条用户输入文本消息，和 user_msg 的内容类型不同，用来覆盖更接近用户输入的格式。

数据流：输入文字 → 包成角色为 user、内容为 InputText 的 ResponseItem → 返回测试消息。

调用关系：回滚用户轮次等测试用它模拟真实用户指令、环境上下文、技能说明等前缀内容。

调用图：被 1 处调用（drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns）；外部调用 1 个（vec!）。

fn developer_msg(text: &str) -> ResponseItem

作用：造一条开发者指令消息。开发者指令可以理解为比普通用户话更像“系统给助手的工作规则”。

数据流：输入文字 → 包成角色为 developer、内容为 InputText 的 ResponseItem → 返回这条开发者消息。

调用关系：主要用于测试回滚时上下文更新和开发者指令是否被正确保留或裁掉。

调用图：外部调用 1 个（vec!）。

fn developer_msg_with_fragments(texts: &[&str]) -> ResponseItem

作用：造一条由多段文字组成的开发者消息，用来测试一条消息里混有不同性质指令的情况。

数据流：输入多个文字片段 → 每段变成一个 InputText 内容块 → 合成一条 developer 消息返回。

调用关系：混合开发者上下文包的测试会用它，检查回滚时遇到混合内容是否清掉参考上下文。

fn reference_context_item() -> TurnContextItem

作用：造一个固定的回合上下文快照。它像拍了一张“当前工作目录、日期、权限、沙箱策略”等运行环境的照片。

数据流：不接收业务输入 → 填好 cwd、日期、审批策略、只读沙箱、模型名等字段 → 返回 TurnContextItem。

调用关系：回滚相关测试把它塞进历史管理器，再验证 drop_last_n_user_turns 后这个参考上下文该保留还是该清空。

调用图：被 2 处调用（drop_last_n_user_turns_clears_reference_context_for_mixed_developer_context_bundles, drop_last_n_user_turns_trims_context_updates_above_rolled_back_turn）；外部调用 2 个（from, new_read_only_policy）。

fn custom_tool_call_output(call_id: &str, output: &str) -> ResponseItem

作用：造一条自定义工具的输出消息。工具输出就是模型调用外部工具后返回的结果。

数据流：输入调用编号和输出文字 → 把文字包成 FunctionCallOutputPayload → 返回 CustomToolCallOutput。

调用关系：token 使用量相关测试用它放在助手最后一次输出之后，确认这些新工具结果会被补算进总 token。

调用图：调用 1 个内部函数（from_text）；被 2 处调用（items_after_last_model_generated_tokens_include_user_and_tool_output, total_token_usage_includes_all_items_after_last_model_generated_item）。

fn reasoning_msg(text: &str) -> ResponseItem

作用：造一条明文推理消息，用来测试历史是否保留模型的 reasoning 项。reasoning 可以理解为模型的思考记录或摘要。

数据流：输入推理文字 → 同时放入固定 summary 和内容正文 → 返回 Reasoning 类型的 ResponseItem。

调用关系：过滤非 API 消息的测试用它确认 Reasoning 不会像系统消息那样被丢掉。

调用图：被 1 处调用（filters_non_api_messages）；外部调用 2 个（new, vec!）。

fn reasoning_with_encrypted_content(len: usize) -> ResponseItem

作用：造一条只有加密内容长度的推理消息，用来测试推理 token 的估算。加密内容看不到原文，只能按长度估。

数据流：输入长度 → 生成对应长度的字符串作为 encrypted_content → 返回没有明文 content 的 Reasoning 项。

调用关系：非最后用户轮次推理 token 的测试用它构造多段推理，再检查统计函数如何忽略或计算它们。

调用图：外部调用 2 个（new, vec!）。

fn truncate_exec_output(content: &str) -> String

作用：把很长的命令执行输出截短到测试规定的 token 上限。这样模型不会被一大坨日志撑爆上下文。

数据流：输入完整输出文本 → 用 2500 token 的裁剪策略调用 truncate_text → 返回可能被加了“truncated”提示的文本。

调用关系：命令输出格式化相关测试都先调用它，再用 assert_truncated_message_matches 验证裁剪标记、保留头尾和删除数量。

调用图：被 4 处调用（format_exec_output_marks_byte_truncation_without_omitted_lines, format_exec_output_prefers_line_marker_when_both_limits_exceeded, format_exec_output_reports_omitted_lines_and_keeps_head_and_tail, format_exec_output_truncates_large_error）；外部调用 2 个（truncate_text, Tokens）。

fn approx_token_count_for_text(text: &str) -> i64

作用：用一个很粗略的方法估算文字 token 数，方便测试比较长短差异。

数据流：输入文本 → 按大约每 4 个字符一个 token 计算，并安全转成 i64 → 返回估算值。

调用关系：基础指令 token 估算测试用它算出短指令和长指令之间应有的差值。

调用图：被 1 处调用（estimate_token_count_with_base_instructions_uses_provided_text）；外部调用 1 个（try_from）。

fn filters_non_api_messages()

作用：测试历史记录会丢掉不该发给 API 的消息，但保留该保留的推理、用户和助手消息。

数据流：先放入 system、reasoning 和 Other，再放入 user、assistant → 读取 raw_items → 断言最终只剩 reasoning、user、assistant。

调用关系：它调用 assistant_msg、reasoning_msg、user_msg 造数据，然后直接验证 ContextManager::record_items 的过滤行为。

调用图：调用 3 个内部函数（assistant_msg, reasoning_msg, user_msg）；外部调用 4 个（assert_eq!, default, Tokens, vec!）。

fn non_last_reasoning_tokens_return_zero_when_no_user_messages()

作用：测试如果历史里没有用户消息，那么“非最后一轮的推理 token”应当是 0。

数据流：输入一条加密推理历史 → 创建历史管理器 → 调 get_non_last_reasoning_items_tokens 并断言返回 0。

调用关系：它通过 create_history_with_items 进入历史逻辑，专门守住没有用户轮次时的边界情况。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn non_last_reasoning_tokens_ignore_entries_after_last_user()

作用：测试统计旧推理 token 时，不要把最后一个用户消息之后的新推理算进去。

数据流：构造推理、用户、推理、用户、推理的序列 → 建历史 → 统计非最后轮推理 token → 断言结果只包含应计的旧推理。

调用关系：它用 create_history_with_items 搭场景，验证 ContextManager 的 reasoning token 统计规则。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn items_after_last_model_generated_tokens_include_user_and_tool_output()

作用：测试最后一次模型输出之后，新来的用户消息和工具输出都会被视为新增内容。

数据流：构造 assistant 后接 user 和 custom tool output → 找出最后模型生成项之后的项目 → 估算 token 并比对预期。

调用关系：它用 user_msg 和 custom_tool_call_output 造尾部内容，验证 items_after_last_model_generated_item 的范围。

调用图：调用 3 个内部函数（create_history_with_items, custom_tool_call_output, user_msg）；外部调用 2 个（assert_eq!, vec!）。

fn items_after_last_model_generated_tokens_are_zero_without_model_generated_items()

作用：测试如果历史里还没有模型生成的内容，就不要把用户消息当成“最后模型输出之后的新增项”来算。

数据流：只放一条用户消息 → 查询最后模型生成项之后的列表并求 token → 断言为 0。

调用关系：它通过 create_history_with_items 检查一个没有助手输出的起步状态。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn inter_agent_assistant_messages_are_turn_boundaries()

作用：测试新版多智能体 assistant 消息会被当成一个用户轮次边界。轮次边界就是“从这里开始算一轮新指令”。

数据流：创建多智能体 assistant 消息 → 调 is_user_turn_boundary → 断言结果为真。

调用关系：它用 inter_agent_assistant_msg 造标准格式消息，直接检查边界识别函数。

调用图：调用 1 个内部函数（inter_agent_assistant_msg）；外部调用 1 个（assert!）。

fn for_prompt_preserves_inter_agent_assistant_messages()

作用：测试发给模型的 prompt 历史不会丢掉多智能体 assistant 消息。

数据流：创建一条多智能体消息并记录进历史 → 分别读取 raw_items 和 for_prompt → 断言都保留原消息。

调用关系：它连接 create_history_with_items 和 for_prompt，验证整理 prompt 时不会误删协作指令。

调用图：调用 2 个内部函数（create_history_with_items, inter_agent_assistant_msg）；外部调用 2 个（assert_eq!, vec!）。

fn drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns()

作用：测试回滚最后一轮用户指令时，多智能体 assistant 消息也算一轮可回滚的指令。

数据流：构造普通用户轮次和多智能体轮次 → 删除最后 1 个用户轮次 → 断言只剩第一轮。

调用关系：它用多个消息工厂搭历史，然后把核心动作交给 drop_last_n_user_turns。

调用图：调用 4 个内部函数（assistant_msg, create_history_with_items, inter_agent_assistant_msg, user_input_text_msg）；外部调用 2 个（assert_eq!, vec!）。

fn legacy_inter_agent_assistant_messages_are_not_turn_boundaries()

作用：测试旧格式的多智能体文字不会被误认为新版轮次边界。

数据流：创建一条看起来像旧格式协议的普通 assistant 文本 → 调 is_user_turn_boundary → 断言为假。

调用关系：它用 assistant_msg 造旧文本，保护边界识别逻辑不要过度匹配。

调用图：调用 1 个内部函数（assistant_msg）；外部调用 1 个（assert!）。

fn total_token_usage_includes_all_items_after_last_model_generated_item()

作用：测试总 token 用量会把 API 已报告的用量和最后模型输出后的本地新增项加在一起。

数据流：先记录 assistant 并写入总 token 100 → 再记录用户和工具输出 → 调 get_total_token_usage → 断言等于 100 加新增项估算。

调用关系：它验证 update_token_info、record_items 和新增项估算之间的配合。

调用图：调用 3 个内部函数（create_history_with_items, custom_tool_call_output, user_msg）；外部调用 4 个（default, assert_eq!, Tokens, vec!）。

fn for_prompt_strips_images_when_model_does_not_support_images()

作用：测试模型不支持图片输入时，prompt 里的图片会被文字占位提示替换；支持图片时则保留原图。

数据流：构造用户图片、函数输出图片、自定义工具输出图片 → 用纯文本 modality 调 for_prompt → 断言图片变成说明文字；再用默认 modality 断言图片保留。

调用关系：它直接验证 for_prompt 对输入能力的适配，避免把模型看不懂的图片发过去。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 4 个（assert!, assert_eq!, panic!, vec!）。

fn for_prompt_preserves_image_generation_calls_when_images_are_supported()

作用：测试当模型支持图片时，图片生成调用的结果不会被清空。

数据流：构造 ImageGenerationCall 和用户消息 → 创建历史 → 用默认输入能力生成 prompt → 断言图片生成项完整保留。

调用关系：它验证 for_prompt 在支持图像的模型路径上不破坏图像生成记录。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn for_prompt_clears_image_generation_result_when_images_are_unsupported()

作用：测试当模型不支持图片时，图片生成调用里的图片结果会被清空，只保留调用信息。

数据流：构造用户请求和已完成的图片生成结果 → 用纯文本能力生成 prompt → 断言 result 变成空字符串。

调用关系：它验证 for_prompt 的降级行为，避免把不能处理的图片数据塞给纯文本模型。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn estimate_token_count_with_base_instructions_uses_provided_text()

作用：测试估算 token 时确实使用传入的基础指令文本，而不是固定值或忽略它。

数据流：创建相同历史，分别传短基础指令和长基础指令 → 得到两个估算 → 断言差值等于文本长度带来的估算差。

调用关系：它调用 approx_token_count_for_text 计算预期差异，检查 ContextManager 的基础指令计数入口。

调用图：调用 2 个内部函数（approx_token_count_for_text, create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn remove_first_item_removes_matching_output_for_function_call()

作用：测试删除第一项如果删掉函数调用，也会一起删掉匹配的函数输出。

数据流：构造 FunctionCall 和同 call_id 的 FunctionCallOutput → 删除第一项 → 断言历史为空。

调用关系：它验证 remove_first_item 不会留下孤零零的工具输出。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn remove_first_item_removes_matching_call_for_output()

作用：测试第一项是函数输出时，也会删除后面匹配的函数调用。

数据流：构造输出在前、调用在后的配对 → 删除第一项 → 断言两者都被移除。

调用关系：它覆盖配对项顺序反过来的情况，仍然走 remove_first_item。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn replace_last_turn_images_replaces_tool_output_images()

作用：测试最后一轮里的工具输出图片可以被替换成错误文字，比如图片无效时给模型一个说明。

数据流：构造用户消息和带图片的函数输出 → 调 replace_last_turn_images("Invalid image") → 断言图片内容变成 InputText。

调用关系：它验证图片修复路径只改最后一轮工具输出中的图片。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 3 个（assert!, assert_eq!, vec!）。

fn replace_last_turn_images_does_not_touch_user_images()

作用：测试替换最后一轮图片时，不会改用户自己上传的图片。

数据流：构造只有用户图片的历史 → 调 replace_last_turn_images → 返回 false，并断言历史不变。

调用关系：它保护用户原始输入不被工具输出修复逻辑误伤。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 3 个（assert!, assert_eq!, vec!）。

fn remove_first_item_handles_local_shell_pair()

作用：测试删除本地 shell 调用时，会连同对应输出一起删除。shell 调用就是在本机执行命令。

数据流：构造 LocalShellCall 和同 call_id 的 FunctionCallOutput → 调 remove_first_item → 断言历史为空。

调用关系：它把本地命令这种特殊工具调用也纳入 remove_first_item 的配对删除规则。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn drop_last_n_user_turns_preserves_prefix()

作用：测试回滚用户轮次时，会保留会话开头的前缀内容。

数据流：构造前缀 assistant、两轮用户和助手 → 删除最后 1 轮或很多轮 → 断言前缀始终留下，用户轮次按要求删掉。

调用关系：它验证 drop_last_n_user_turns 不会把会话启动时的固定上下文一起清掉。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn drop_last_n_user_turns_ignores_session_prefix_user_messages()

作用：测试某些看起来像用户消息的会话前缀不会被当成普通用户轮次删除。

数据流：构造环境上下文、AGENTS 指令、技能、用户 shell 命令、子代理通知等前缀，再加两轮真实对话 → 回滚 1、2、3 轮 → 断言前缀保留。

调用关系：它验证 drop_last_n_user_turns 能区分“初始化材料”和“真实用户提问”。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn drop_last_n_user_turns_trims_context_updates_above_rolled_back_turn()

作用：测试回滚上一轮时，会剪掉那一轮上方的临时上下文更新，但保留更早的持久开发者说明。

数据流：构造第一轮、开发者说明、回滚标记、环境差异和第二轮 → 设置参考上下文 → 回滚最后一轮 → 断言只剩早期内容和应保留的开发者说明。

调用关系：它用 reference_context_item 配合 drop_last_n_user_turns，检查回滚时上下文快照是否仍正确。

调用图：调用 3 个内部函数（create_history_with_items, reference_context_item, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn drop_last_n_user_turns_clears_reference_context_for_mixed_developer_context_bundles()

作用：测试如果开发者消息里混有临时权限说明和持久插件说明，回滚后会清掉参考上下文，避免上下文含糊。

数据流：构造第一轮、混合开发者消息、环境差异和第二轮 → 设置参考上下文 → 回滚最后一轮 → 断言只剩第一轮且 reference_context_item 为空。

调用关系：它使用 developer_msg_with_fragments 和 reference_context_item，验证保守处理混合上下文的规则。

调用图：调用 3 个内部函数（create_history_with_items, reference_context_item, default_input_modalities）；外部调用 3 个（assert!, assert_eq!, vec!）。

fn remove_first_item_handles_custom_tool_pair()

作用：测试删除自定义工具调用时，会一起删除对应的自定义工具输出。

数据流：构造 CustomToolCall 和同 call_id 的 CustomToolCallOutput → 调 remove_first_item → 断言历史为空。

调用关系：它让 remove_first_item 的配对删除规则覆盖自定义工具类型。

调用图：调用 1 个内部函数（create_history_with_items）；外部调用 2 个（assert_eq!, vec!）。

fn normalization_retains_local_shell_outputs()

作用：测试历史规范化不会误删本地 shell 的正常输出。

数据流：构造 LocalShellCall 和对应输出 → 调 for_prompt 触发整理后的视图 → 断言输出仍然存在。

调用关系：它检查 normalize/for_prompt 路径不要把合法命令输出当孤儿项删除。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn record_items_truncates_function_call_output_content()

作用：测试记录函数调用输出时，太长的内容会按 token 限制截短，并保留 turn_id 元数据。

数据流：构造超长 FunctionCallOutput → 用 1000 token 策略 record_items → 断言存入内容被截短、含 truncated 标记，且 turn_id 没丢。

调用关系：它直接测试 ContextManager::record_items 对普通函数输出的保护性裁剪。

调用图：调用 1 个内部函数（new）；外部调用 6 个（assert!, assert_eq!, assert_ne!, panic!, Text, Tokens）。

fn record_items_truncates_custom_tool_call_output_content()

作用：测试自定义工具输出太长时也会被截短。

数据流：构造超长 CustomToolCallOutput → record_items → 检查保存的文本不同于原文，并包含裁剪提示。

调用关系：它和函数输出裁剪测试成对存在，覆盖自定义工具输出路径。

调用图：调用 2 个内部函数（new, from_text）；外部调用 5 个（assert!, assert_eq!, assert_ne!, panic!, Tokens）。

fn record_items_respects_custom_token_limit()

作用：测试 record_items 会尊重调用者给的更小 token 上限。

数据流：用 10 token 策略记录一段很长函数输出 → 读取保存内容 → 断言里面有 tokens truncated 标记。

调用关系：它验证裁剪策略不是写死的，而是由传入的 TruncationPolicy 控制。

调用图：调用 1 个内部函数（new）；外部调用 4 个（assert!, panic!, Text, Tokens）。

fn assert_truncated_message_matches(message: &str, line: &str, expected_removed: usize)

作用：检查被截短的文本是否符合统一格式，并确认删除的 token 数正确。

数据流：输入截短消息、预期开头行和预期删除数量 → 生成正则表达式匹配消息 → 验证正文长度和 removed 数字。

调用关系：命令输出裁剪测试都把结果交给它做统一验收；它内部调用 truncated_message_pattern。

调用图：调用 1 个内部函数（truncated_message_pattern）；被 4 处调用（format_exec_output_marks_byte_truncation_without_omitted_lines, format_exec_output_prefers_line_marker_when_both_limits_exceeded, format_exec_output_reports_omitted_lines_and_keeps_head_and_tail, format_exec_output_truncates_large_error）；外部调用 3 个（new, assert!, assert_eq!）。

fn truncated_message_pattern(line: &str) -> String

作用：生成一个用来匹配截短提示的正则表达式。正则表达式就是按规则找文字的“小筛子”。

数据流：输入应保留的开头行 → 先转义特殊字符 → 拼出能捕获正文和删除 token 数的匹配模式。

调用关系：只被 assert_truncated_message_matches 使用，帮助测试识别 truncate_text 的输出格式。

调用图：被 1 处调用（assert_truncated_message_matches）；外部调用 2 个（format!, escape）。

fn format_exec_output_truncates_large_error()

作用：测试非常长的错误输出会被截短，而不是完整塞进历史。

数据流：生成重复很多次的错误行 → 调 truncate_exec_output → 验证格式和删除数量，并确认结果不同于原文。

调用关系：它通过 truncate_exec_output 测实际裁剪，再交给 assert_truncated_message_matches 检查。

调用图：调用 2 个内部函数（assert_truncated_message_matches, truncate_exec_output）；外部调用 1 个（assert_ne!）。

fn format_exec_output_marks_byte_truncation_without_omitted_lines()

作用：测试单行过长导致截短时，不应该出现“省略了若干行”的提示。

数据流：生成一条超长单行 → 截短 → 验证 token 删除数量，并断言没有 omitted 字样。

调用关系：它覆盖字节/长度限制触发但没有删行的特殊情况。

调用图：调用 2 个内部函数（assert_truncated_message_matches, truncate_exec_output）；外部调用 2 个（assert!, assert_ne!）。

fn format_exec_output_returns_original_when_within_limits()

作用：测试输出不长时，裁剪函数应该原样返回。

数据流：生成较短内容 → 调截短函数的等价路径 → 断言返回值和输入完全一样。

调用关系：它保护 truncate_text 不要对正常大小的内容做多余修改。

调用图：外部调用 1 个（assert_eq!）。

fn format_exec_output_reports_omitted_lines_and_keeps_head_and_tail()

作用：测试很多行的输出被截短时，会保留开头和结尾，方便读者知道前因后果。

数据流：生成 2000 行内容 → 截短 → 验证截短标记，并断言第一行和最后一行的线索都还在。

调用关系：它确认 truncate_exec_output 的“保头保尾”策略。

调用图：调用 2 个内部函数（assert_truncated_message_matches, truncate_exec_output）；外部调用 2 个（assert!, format!）。

fn format_exec_output_prefers_line_marker_when_both_limits_exceeded()

作用：测试当行数和大小都超限时，裁剪提示采用预期的格式。

数据流：生成既多行又每行很长的内容 → 截短 → 用统一检查函数验证删除 token 数。

调用关系：它覆盖多个限制同时触发时的优先规则。

调用图：调用 2 个内部函数（assert_truncated_message_matches, truncate_exec_output）。

fn normalize_adds_missing_output_for_function_call()

作用：测试发布版里历史规范化会给缺少输出的函数调用补一个 aborted 输出。

数据流：构造只有 FunctionCall 的历史 → normalize_history → 断言后面补上 FunctionCallOutput("aborted")。

调用关系：它在非 debug 构建下运行，验证线上容错会修补不完整工具调用。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_adds_missing_output_for_custom_tool_call()

作用：测试发布版里自定义工具调用缺输出时会自动补 aborted。

数据流：构造只有 CustomToolCall 的历史 → normalize_history → 断言补上 CustomToolCallOutput。

调用关系：它覆盖自定义工具的规范化修补路径，只在非 debug 下启用。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_adds_missing_output_for_local_shell_call_with_id()

作用：测试发布版里本地 shell 调用有 call_id 但没输出时，会补一个 aborted 输出。

数据流：构造只有 LocalShellCall 的历史 → normalize_history → 断言补上对应 FunctionCallOutput。

调用关系：它检查本地命令调用也能被规范化逻辑修复。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_removes_orphan_function_call_output()

作用：测试发布版里没有对应函数调用的函数输出会被删除。

数据流：构造孤立 FunctionCallOutput → normalize_history → 断言历史为空。

调用关系：它验证规范化会清理孤儿输出，避免发给模型一段没来由的结果。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_removes_orphan_custom_tool_call_output()

作用：测试发布版里没有对应调用的自定义工具输出会被删除。

数据流：构造孤立 CustomToolCallOutput → normalize_history → 断言被清空。

调用关系：它让孤儿清理规则覆盖自定义工具输出。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_mixed_inserts_and_removals()

作用：测试发布版规范化能同时处理缺输出和孤儿输出。

数据流：构造一个缺输出函数调用、一个孤儿输出、一个缺输出自定义工具、一个缺输出 shell 调用 → normalize_history → 断言补该补的、删该删的。

调用关系：它是综合场景，验证 normalize_history 多条规则一起工作时顺序正确。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_adds_missing_output_for_function_call_inserts_output()

作用：测试通用规范化路径会给缺少输出的函数调用插入 aborted 输出。

数据流：构造只有 FunctionCall 的历史 → 调 normalize_history → 断言插入对应 FunctionCallOutput。

调用关系：它和条件编译版本类似，用来保证当前构建下这个插入行为存在。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_adds_missing_output_for_tool_search_call()

作用：测试工具搜索调用缺少输出时，会补一个空的搜索输出。

数据流：构造 ToolSearchCall → normalize_history → 断言后面出现 ToolSearchOutput，状态和执行端匹配、工具列表为空。

调用关系：它把工具搜索这种调用类型纳入规范化补全规则。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_adds_missing_output_for_custom_tool_call_panics_in_debug()

作用：测试 debug 模式下，自定义工具调用缺输出会直接 panic。panic 可以理解为测试期故意报错，逼开发者修正问题。

数据流：构造缺输出 CustomToolCall → 调 normalize_history → 预期程序在测试中崩溃。

调用关系：它只在 debug 构建启用，和发布版自动修复测试形成对照。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 1 个（vec!）。

fn normalize_adds_missing_output_for_local_shell_call_with_id_panics_in_debug()

作用：测试 debug 模式下，本地 shell 调用缺输出会 panic。

数据流：构造带 call_id 但无输出的 LocalShellCall → normalize_history → 预期 panic。

调用关系：它帮助开发阶段尽早发现不完整的命令调用记录。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 1 个（vec!）。

fn normalize_removes_orphan_function_call_output_panics_in_debug()

作用：测试 debug 模式下，孤立函数输出会 panic，而不是悄悄删除。

数据流：构造没有匹配调用的 FunctionCallOutput → normalize_history → 预期 panic。

调用关系：它和发布版清理孤儿输出的行为相对，强调开发期严格检查。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 1 个（vec!）。

fn normalize_removes_orphan_custom_tool_call_output_panics_in_debug()

作用：测试 debug 模式下，孤立自定义工具输出会 panic。

数据流：构造孤立 CustomToolCallOutput → normalize_history → 预期 panic。

调用关系：它确保开发环境不会掩盖自定义工具调用配对错误。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 1 个（vec!）。

fn normalize_removes_orphan_client_tool_search_output()

作用：测试发布版里客户端执行的孤立工具搜索输出会被删除。

数据流：构造 execution 为 client 的孤立 ToolSearchOutput → normalize_history → 断言历史为空。

调用关系：它验证客户端工具搜索输出必须有对应调用。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_removes_orphan_client_tool_search_output_panics_in_debug()

作用：测试 debug 模式下，客户端工具搜索孤儿输出会 panic。

数据流：构造孤立 client ToolSearchOutput → normalize_history → 预期 panic。

调用关系：它和发布版自动删除形成对照，保证开发期更严格。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 1 个（vec!）。

fn normalize_keeps_server_tool_search_output_without_matching_call()

作用：测试服务端执行的工具搜索输出即使没有本地匹配调用，也会保留。

数据流：构造 execution 为 server 的 ToolSearchOutput → normalize_history → 断言原样保留。

调用关系：它说明规范化规则区分 client 和 server，因为服务端结果可能本来就没有本地调用记录。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 2 个（assert_eq!, vec!）。

fn normalize_mixed_inserts_and_removals_panics_in_debug()

作用：测试 debug 模式下，混合的不完整调用和孤儿输出会触发 panic。

数据流：构造缺输出函数调用、孤儿函数输出、缺输出自定义工具和缺输出 shell → normalize_history → 预期 panic。

调用关系：它是 debug 严格检查的综合场景，防止多种历史损坏被忽略。

调用图：调用 2 个内部函数（create_history_with_items, default_input_modalities）；外部调用 1 个（vec!）。

fn image_data_url_payload_does_not_dominate_message_estimate()

作用：测试消息里的 base64 图片不会按原始超长字符串完整计入可见字节估算。

数据流：构造带 100000 字符图片 payload 的用户消息 → 算原始 JSON 长度和模型可见估算 → 断言估算用固定图片成本替代原 payload。

调用关系：它验证 estimate_response_item_model_visible_bytes 对普通消息图片的特殊估算。

调用图：外部调用 5 个（assert!, assert_eq!, format!, to_string, vec!）。

fn image_data_url_payload_does_not_dominate_function_call_output_estimate()

作用：测试函数输出里的 base64 图片也不会把估算撑得过大。

数据流：构造含图片内容项的 FunctionCallOutput → 比较原始长度和估算长度 → 断言 payload 被固定图片成本替换。

调用关系：它覆盖函数输出内容项里的图片估算路径。

调用图：调用 1 个内部函数（from_content_items）；外部调用 5 个（assert!, assert_eq!, format!, to_string, vec!）。

fn image_data_url_payload_does_not_dominate_custom_tool_call_output_estimate()

作用：测试自定义工具输出里的 base64 图片同样按图片成本估算，而不是按字符串长度。

数据流：构造含图片的 CustomToolCallOutput → 计算 raw_len 和 estimated → 断言估算低于原始长度且符合公式。

调用关系：它覆盖自定义工具输出内容项的图片估算路径。

调用图：调用 1 个内部函数（from_content_items）；外部调用 5 个（assert!, assert_eq!, format!, to_string, vec!）。

fn non_base64_image_urls_are_unchanged()

作用：测试普通网址或文件路径图片不会被当成内联 base64 图片改估算。

数据流：构造 https 图片消息和 file 图片函数输出 → 估算可见字节 → 断言等于原始 JSON 长度。

调用关系：它保护估算逻辑只处理真正的 base64 data URL。

调用图：调用 1 个内部函数（from_content_items）；外部调用 2 个（assert_eq!, vec!）。

fn encrypted_function_output_uses_plaintext_byte_estimate()

作用：测试加密函数输出会用估算出的明文字节长度替代加密字符串长度。

数据流：构造含 encrypted_content 的 FunctionCallOutput → 计算原始长度、估算长度和预期替换长度 → 断言一致。

调用关系：它验证 estimate_encrypted_function_output_length 和整体字节估算的配合。

调用图：调用 1 个内部函数（from_content_items）；外部调用 3 个（assert_eq!, to_string, vec!）。

fn data_url_without_base64_marker_is_unchanged()

作用：测试 data URL 如果没有 base64 标记，就不会被图片 payload 规则处理。

数据流：构造 data:image/svg+xml 但非 base64 的图片消息 → 估算字节 → 断言等于原始 JSON 长度。

调用关系：它防止估算逻辑误判非 base64 的 data URL。

调用图：外部调用 2 个（assert_eq!, vec!）。

fn non_image_base64_data_url_is_unchanged()

作用：测试虽然是 base64 data URL，但不是 image 类型时，不会套用图片估算规则。

数据流：构造 data:application/octet-stream;base64 的内容 → 估算字节 → 断言等于原始长度。

调用关系：它确保只有图片媒体类型才会被当作图片成本处理。

调用图：调用 1 个内部函数（from_content_items）；外部调用 4 个（assert_eq!, format!, to_string, vec!）。

fn mixed_case_data_url_markers_are_adjusted()

作用：测试 DATA 和 BASE64 大小写混用时，仍能识别为图片 data URL。

数据流：构造大写标记的 data:image/png;BASE64 URL → 估算字节 → 断言 payload 被替换成固定图片成本。

调用关系：它验证图片 URL 识别大小写不敏感。

调用图：外部调用 4 个（assert_eq!, format!, to_string, vec!）。

fn multiple_inline_images_apply_multiple_fixed_costs()

作用：测试一条消息里有多张内联图片时，每张图片都会单独计一次固定成本。

数据流：构造含两张 base64 图片的消息 → 算原始长度、payload 总长和估算 → 断言估算加了两份图片成本。

调用关系：它覆盖多图片场景，防止只处理第一张或少算。

调用图：外部调用 4 个（assert_eq!, format!, to_string, vec!）。

fn original_detail_images_scale_with_dimensions()

作用：测试 original 细节等级的图片会按图片尺寸估算成本，而不是固定成本。

数据流：生成 2304x864 PNG 图片并转 base64 → 放进 FunctionCallOutput → 估算字节 → 断言按 32 像素 patch 数得出预期成本。

调用关系：它验证原始细节图片的尺寸解析和 patch 计费启发式。patch 可理解为把图片切成小格来估算成本。

调用图：调用 2 个内部函数（from_content_items, new）；外部调用 7 个（from_pixel, new, assert_eq!, format!, Rgba, to_string, vec!）。

fn original_detail_images_are_capped_at_max_patch_count()

作用：测试 original 图片太大时，估算成本会被最大 patch 数封顶。

数据流：生成 3201x3201 PNG → 转 base64 并估算 → 断言成本不超过 ORIGINAL_IMAGE_MAX_PATCHES 对应字节数。

调用关系：它保护超大图片不会让估算无限增长。

调用图：调用 2 个内部函数（from_content_items, new）；外部调用 8 个（from_pixel, new, assert_eq!, format!, try_from, Luma, to_string, vec!）。

fn original_detail_webp_images_scale_with_dimensions()

作用：测试 WebP 格式的 original 图片也能按尺寸估算成本。

数据流：生成和 PNG 测试同尺寸的 WebP → 放进输出项 → 估算字节 → 断言得到同样的尺寸成本。

调用关系：它确认尺寸估算不只支持 PNG，也支持 WebP。

调用图：调用 2 个内部函数（from_content_items, new）；外部调用 7 个（from_pixel, new, assert_eq!, format!, Rgba, to_string, vec!）。

fn text_only_items_unchanged()

作用：测试纯文本消息的可见字节估算就是原始 JSON 长度，不会被图片或加密规则影响。

数据流：构造 assistant 纯文本消息 → 估算可见字节并计算原始长度 → 断言两者相等。

调用关系：它作为基准测试，说明特殊估算只作用于图片和加密内容等特殊情况。

调用图：外部调用 3 个（assert_eq!, to_string, vec!）。