线程和会话编排

fn set_thread_manager_test_mode_for_tests(enabled: bool)

作用：打开或关闭线程管理器的测试模式。测试模式会启用一些只给自动化测试用的行为，比如记录提交过的操作。

数据流：进去一个布尔值，表示是否启用测试模式 → 它把这个值写进一个全局开关 → 之后新建 ThreadManager 时会读到这个开关，并决定是否启用测试辅助功能。

调用关系：它被测试辅助代码和测试构造函数调用；正式业务流程不应该依赖它。

调用图：被 3 处调用（set_thread_manager_test_mode, with_models_provider_for_tests, with_models_provider_home_and_state_for_tests）。

fn should_use_test_thread_manager_behavior() -> bool

作用：读取当前是否处于线程管理器测试模式。它是测试开关的查询口。

数据流：不需要输入 → 从全局原子布尔值里读取当前状态 → 返回 true 或 false，告诉调用者要不要启用测试行为。

调用关系：ThreadManager::new 和测试构造函数会用它来决定是否创建操作日志。

调用图：被 2 处调用（new, with_models_provider_home_and_state_for_tests）。

fn drop(&mut self)

作用：测试结束时自动删除临时的 Codex 主目录。它像临时工走之前把房间打扫干净。

数据流：对象被释放时带着一个目录路径 → 调用系统删除整个目录树 → 不返回结果，删除失败也被忽略，避免测试清理影响主流程。

调用关系：它是 Rust 的 Drop 钩子，在 TempCodexHomeGuard 生命周期结束时自动触发；测试构造函数会把它挂在线程管理器上。

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

fn from(value: usize) -> Self

作用：把旧代码传入的数字转换成新的 fork 快照方式。这样老调用点不用立刻全部改写。

数据流：进去一个 usize 数字 → 把它解释成“在第 n 条用户消息前截断” → 输出 ForkSnapshot::TruncateBeforeNthUserMessage。

调用关系：ThreadManager::fork_thread 和 fork_thread_from_history 接受 Into<ForkSnapshot>，所以旧的数字参数会通过这里自动转换。

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

fn build_models_manager(
    config: &Config,
    auth_manager: Arc<AuthManager>,
) -> SharedModelsManager

作用：根据配置和登录信息创建模型列表管理器。它让线程管理器知道有哪些 AI 模型可用、如何刷新这些模型信息。

数据流：进去配置和认证管理器 → 先按配置创建模型服务提供方，再用 Codex 主目录和模型目录配置生成模型管理器 → 返回一个共享的模型管理器。

调用关系：ThreadManager::new 在启动时调用它，把模型能力放进共享状态里，之后 list_models 等接口会使用这个管理器。

调用图：被 1 处调用（new）；外部调用 1 个（create_model_provider）。

fn thread_store_from_config(
    config: &Config,
    state_db: Option<StateDbHandle>,
) -> Arc<dyn ThreadStore>

作用：根据配置决定线程历史存在哪里：本地持久化，或只存在内存里。没有这个选择，恢复旧对话和测试隔离都会很麻烦。

数据流：进去项目配置和可选状态数据库 → 如果配置是本地存储，就创建本地线程库，必要时启动压缩后台任务；如果是内存存储，就按 id 拿一个内存库 → 返回统一的 ThreadStore 接口。

调用关系：上层启动或测试准备线程管理器时会调用它；后续所有读写历史、更新元数据都会通过返回的存储对象完成。

调用图：调用 3 个内部函数（for_id, new, from_config）；被 2 处调用（build_prompt_input, tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtrees_closed）；外部调用 2 个（new, spawn_rollout_compression_worker）。

fn new(
        config: &Config,
        auth_manager: Arc<AuthManager>,
        session_source: SessionSource,
        environment_manager: Arc<EnvironmentManager>,
        extensions: Arc<ExtensionR

作用：创建正式运行用的 ThreadManager。它把认证、模型、环境、插件、技能、线程存储等零件装到同一个管理器里。

数据流：进去配置、认证管理器、环境管理器、扩展、存储、统计客户端等依赖 → 创建线程表、广播通道、插件管理器、MCP 管理器、技能管理器和模型管理器 → 返回一个可用的 ThreadManager。

调用关系：这是生产代码最主要的构造入口；后续 start、resume、fork、shutdown 等操作都依赖这里组装好的 ThreadManagerState。

调用图：调用 5 个内部函数（new_with_options, new_with_restriction_product, new_with_extensions, build_models_manager, should_use_test_thread_manager_behavior）；被 17 处调用（build_prompt_input, explicit_installation_id_skips_codex_home_file, interrupted_fork_snapshot_does_not_synthesize_turn_id_for_legacy_history, interrupted_fork_snapshot_preserves_explicit_turn_id, interrupted_fork_snapshot_uses_persisted_mid_turn_history_without_live_source, new_uses_active_provider_for_model_refresh, resume_active_thread_from_rollout_returns_running_thread, resume_and_fork_do_not_restore_thread_environments_from_rollout, resume_stopped_thread_from_rollout_preserves_thread_source, resume_stopped_thread_from_rollout_spawns_new_thread (+7 more)）；外部调用 7 个（clone, new, new, new, bundled_skills_enabled, restriction_product, channel）。

fn with_models_provider_for_tests(
        auth: CodexAuth,
        provider: ModelProviderInfo,
    ) -> Self

作用：为集成测试创建一个带假模型提供方的 ThreadManager。它会自动使用临时目录，避免污染用户真实数据。

数据流：进去测试认证信息和模型提供方信息 → 开启测试模式，创建临时 Codex 主目录和默认测试环境管理器 → 返回一个带清理守卫的 ThreadManager。

调用关系：测试辅助函数会调用它；它继续委托给 with_models_provider_and_home_for_tests 完成具体组装。

调用图：调用 2 个内部函数（set_thread_manager_test_mode_for_tests, default_for_tests）；被 2 处调用（thread_manager_with_models_provider, thread_manager）；外部调用 5 个（new, with_models_provider_and_home_for_tests, format!, temp_dir, create_dir_all）。

fn with_models_provider_and_home_for_tests(
        auth: CodexAuth,
        provider: ModelProviderInfo,
        codex_home: PathBuf,
        environment_manager: Arc<EnvironmentManager>,
    ) -> Se

作用：为测试创建 ThreadManager，但允许指定 Codex 主目录。这样测试可以检查某个目录下的存储行为。

数据流：进去测试认证、模型提供方、目录路径和环境管理器 → 默认不传状态数据库 → 调用更底层的测试构造函数并返回结果。

调用关系：多个测试场景使用它；它只是薄包装，真正工作交给 with_models_provider_home_and_state_for_tests。

调用图：被 10 处调用（interrupted_v2_agent_is_lost_after_residency_eviction, residency_slot_reservation_unloads_oldest_idle_v2_agent, resume_agent_releases_slot_after_resume_failure, resume_agent_respects_max_threads_limit, spawn_agent_limit_shared_across_clones, spawn_agent_releases_slot_after_shutdown, spawn_agent_respects_max_threads_limit, thread_manager_with_models_provider_and_home, shutdown_all_threads_bounded_submits_shutdown_to_every_thread, start_thread_keeps_internal_threads_hidden_from_normal_lookups）；外部调用 1 个（with_models_provider_home_and_state_for_tests）。

fn with_models_provider_home_and_state_for_tests(
        auth: CodexAuth,
        provider: ModelProviderInfo,
        codex_home: PathBuf,
        environment_manager: Arc<EnvironmentManager>,

作用：测试版 ThreadManager 的完整构造函数，还能带状态数据库。它用于需要模拟线程树、恢复、限制等复杂场景的测试。

数据流：进去测试认证、模型提供方、目录、环境管理器和可选状态库 → 创建假 AuthManager、本地线程存储、模型管理器、插件、MCP、技能等 → 返回测试用 ThreadManager。

调用关系：更简单的测试构造函数会调用它；它与 ThreadManager::new 类似，但所有依赖都偏向测试安全和可控。

调用图：调用 8 个内部函数（new_with_options, new_with_restriction_product, new, set_thread_manager_test_mode_for_tests, should_use_test_thread_manager_behavior, from_auth_for_testing, new, from_absolute_path_checked）；被 6 处调用（new_with_config, list_agent_subtree_thread_ids_finds_live_descendants_of_unloaded_root, resume_agent_from_rollout_does_not_reopen_v2_descendants, resume_thread_subagent_restores_stored_nickname_and_role, thread_manager_with_models_provider_home_and_state, multi_agent_v2_interrupt_agent_accepts_unloaded_task_name_target）；外部调用 10 个（clone, new, new, clone, new, channel, empty_extension_registry, create_model_provider, panic!, new_v4）。

fn session_source(&self) -> SessionSource

作用：返回这个管理器默认的会话来源。会话来源用来区分是普通执行、子代理，还是其他入口创建的线程。

数据流：不需要输入 → 从共享状态里复制 session_source → 返回给调用者。

调用关系：外部需要了解当前管理器创建线程的默认身份时会用它。

fn auth_manager(&self) -> Arc<AuthManager>

作用：拿到认证管理器。认证管理器保存登录状态和 API 认证方式。

数据流：不需要输入 → 克隆共享指针 Arc，也就是多处可安全共享的引用 → 返回认证管理器给调用者。

调用关系：其他模块需要登录信息或认证模式时会通过这个 getter 取走。

fn skills_manager(&self) -> Arc<SkillsManager>

作用：拿到技能管理器。技能可以理解成系统内置或用户提供的一组能力包。

数据流：不需要输入 → 从状态里克隆技能管理器指针 → 返回给调用者。

调用关系：register_thread_config 等配置注册流程会使用它，把技能能力接到线程配置里。

调用图：被 1 处调用（register_thread_config）。

fn plugins_manager(&self) -> Arc<PluginsManager>

作用：拿到插件管理器。插件管理器负责让外部插件参与 Codex 的能力扩展。

数据流：不需要输入 → 从状态里克隆插件管理器指针 → 返回给需要注册或查询插件的代码。

调用关系：register_thread_config 会调用它；线程启动时也会把同一个插件管理器传给 Codex。

调用图：被 1 处调用（register_thread_config）。

fn mcp_manager(&self) -> Arc<McpManager>

作用：拿到 MCP 管理器。MCP 是一种让外部工具或服务接入模型的协议，这里负责它们的统一入口。

数据流：不需要输入 → 克隆状态里的 MCP 管理器 → 返回共享引用。

调用关系：需要访问 MCP 工具链的上层代码会用它；线程启动时也会把它交给 Codex。

fn environment_manager(&self) -> Arc<EnvironmentManager>

作用：拿到环境管理器。环境管理器知道线程可以在哪些运行环境里执行命令或工具。

数据流：不需要输入 → 从状态中克隆环境管理器指针 → 返回给调用者。

调用关系：register_thread_config 等流程会用它；默认环境选择和环境校验也依赖它。

调用图：被 1 处调用（register_thread_config）。

fn default_environment_selections(
        &self,
        cwd: &AbsolutePathBuf,
    ) -> Vec<TurnEnvironmentSelection>

作用：根据当前工作目录生成默认运行环境选择。这样新线程不必每次都手动指定环境。

数据流：进去一个当前目录 cwd → 调用环境选择工具，结合环境管理器算出默认列表 → 返回一组 TurnEnvironmentSelection。

调用关系：这是对 default_thread_environment_selections 的简单封装，给外部提供统一入口。

调用图：调用 1 个内部函数（default_thread_environment_selections）。

fn validate_environment_selections(
        &self,
        environments: &[TurnEnvironmentSelection],
    ) -> CodexResult<()>

作用：检查用户指定的运行环境是否合理。它会防止同一个环境重复出现，也会拦下不存在的环境 id。

数据流：进去一组环境选择 → 用集合记录已见过的 id，逐个检查重复和是否能在环境管理器里找到 → 成功返回空结果，失败返回 InvalidRequest 错误。

调用关系：resolve_turn_environment_selections 会调用它，在真正启动线程前挡住错误请求。

调用图：被 1 处调用（resolve_turn_environment_selections）；外部调用 4 个（with_capacity, format!, InvalidRequest, len）。

fn get_models_manager(&self) -> SharedModelsManager

作用：返回模型管理器，供外部直接做更细的模型相关操作。

数据流：不需要输入 → 克隆共享模型管理器指针 → 返回它。

调用关系：它是一个访问口；ThreadManager::list_models 和 list_collaboration_modes 则是更常用的简化接口。

async fn list_models(&self, refresh_strategy: RefreshStrategy) -> Vec<ModelPreset>

作用：列出当前可用的模型预设。调用者可以选择是否刷新模型列表。

数据流：进去刷新策略 → 交给模型管理器异步获取模型列表 → 返回 ModelPreset 列表。

调用关系：前端或命令行需要展示可选模型时会调用它；实际数据来自 build_models_manager 创建的模型管理器。

fn list_collaboration_modes(&self) -> Vec<CollaborationModeMask>

作用：列出当前模型支持的协作模式。协作模式描述模型是否支持某些多代理或协同能力。

数据流：不需要输入 → 查询模型管理器保存的协作模式信息 → 返回模式列表。

调用关系：它直接依赖模型管理器，通常用于配置界面或能力判断。

async fn list_thread_ids(&self) -> Vec<ThreadId>

作用：列出当前内存里正在跟踪的普通线程 id。内部线程会被过滤掉，不展示给用户。

数据流：不需要输入 → 委托给 ThreadManagerState::list_thread_ids → 返回线程 id 列表。

调用关系：外部想知道当前有哪些活跃线程时会用它；真正读取线程表的逻辑在状态对象里。

fn subscribe_thread_created(&self) -> broadcast::Receiver<ThreadId>

作用：订阅“新线程创建”通知。之后有线程创建时，订阅者能收到线程 id。

数据流：不需要输入 → 从广播通道创建一个接收器 → 返回给调用者。

调用关系：监听型组件会用它；ThreadManagerState::notify_thread_created 会往这个通道发消息。

async fn get_thread(&self, thread_id: ThreadId) -> CodexResult<Arc<CodexThread>>

作用：按线程 id 找到正在内存里运行的线程。找不到或是内部线程时会报错。

数据流：进去线程 id → 委托状态对象查线程表 → 返回 CodexThread 的共享引用，或 ThreadNotFound 错误。

调用关系：spawn_subagent、update_thread_metadata 和测试断言会调用它；底层逻辑在 ThreadManagerState::get_thread。

调用图：被 3 处调用（assert_thread_not_loaded, spawn_subagent, update_thread_metadata）。

async fn update_thread_metadata(
        &self,
        thread_id: ThreadId,
        patch: ThreadMetadataPatch,
        include_archived: bool,
    ) -> CodexResult<StoredThread>

作用：更新线程的元数据，比如标题、归档状态之类的信息。它兼顾正在运行的线程和已经卸载的冷线程。

数据流：进去线程 id、补丁内容和是否包含已归档线程 → 如果线程正在运行，就通过 CodexThread 更新，保证和实时历史写入顺序一致；否则直接更新线程存储 → 返回更新后的 StoredThread 或错误。

调用关系：这是外部更新元数据的统一入口；它先试 get_thread，失败后才走 thread_store。

调用图：调用 1 个内部函数（get_thread）；外部调用 2 个（format!, InvalidRequest）。

async fn list_agent_subtree_thread_ids(
        &self,
        thread_id: ThreadId,
    ) -> CodexResult<Vec<ThreadId>>

作用：列出某个线程以及它创建出来的所有子代理线程。它能同时看数据库里的历史关系和内存里的活关系。

数据流：进去根线程 id → 先把根 id 放入结果，再从状态数据库读取已记录的子孙线程，再从 AgentControl 查询当前活着的子树 → 去重后返回完整列表。

调用关系：需要关闭、展示或操作一个代理树时会用它；它调用 agent_control，把实时代理关系也纳入结果。

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

async fn start_thread(&self, config: Config) -> CodexResult<NewThread>

作用：用最简单的方式开启一个全新线程。调用者只需要给配置，不需要关心工具和历史。

数据流：进去 Config → 包装成没有动态工具的启动请求 → 调用 start_thread_with_tools → 返回 NewThread。

调用关系：这是普通新建对话的便捷入口；它把工作交给更通用的 start_thread_with_tools。

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

async fn start_thread_with_tools(
        &self,
        config: Config,
        dynamic_tools: Vec<codex_protocol::dynamic_tools::DynamicToolSpec>,
    ) -> CodexResult<NewThread>

作用：开启一个新线程，并额外带上一批动态工具。动态工具是运行时临时提供给模型使用的工具说明。

数据流：进去 Config 和工具列表 → 根据 cwd 计算默认环境，组装 StartThreadOptions，初始历史设为 New → 调用 start_thread_with_options。

调用关系：ThreadManager::start_thread 调用它；它继续把复杂启动流程交给 start_thread_with_options。

调用图：调用 2 个内部函数（default_thread_environment_selections, start_thread_with_options）；被 1 处调用（start_thread）；外部调用 2 个（pin, default）。

async fn start_thread_with_options(
        &self,
        options: StartThreadOptions,
    ) -> CodexResult<NewThread>

作用：按完整选项启动线程。它允许调用者指定历史、来源、工具、环境、追踪信息等。

数据流：进去 StartThreadOptions → 默认不是 fork 来源 → 调用 start_thread_with_options_and_fork_source → 返回新线程。

调用关系：start_thread_with_tools 使用它；需要更细控制线程创建的代码也可以走这里。

调用图：调用 1 个内部函数（start_thread_with_options_and_fork_source）；被 1 处调用（start_thread_with_tools）。

async fn start_thread_with_options_and_fork_source(
        &self,
        options: StartThreadOptions,
        forked_from_thread_id: Option<ThreadId>,
    ) -> CodexResult<NewThread>

作用：启动线程时额外记录它是否来自某个被 fork 的线程。fork 是从旧对话复制历史开新分支。

数据流：进去启动选项和可选 fork 来源 id → 从历史里推断恢复来源，补齐 session_source 和 thread_source → 调用状态对象的 spawn_thread_with_source 创建线程。

调用关系：start_thread_with_options 和 spawn_subagent 都会调用它；它是公开启动选项和底层 spawn 之间的桥。

调用图：调用 1 个内部函数（agent_control）；被 2 处调用（spawn_subagent, start_thread_with_options）；外部调用 2 个（clone, pin）。

async fn spawn_subagent(
        &self,
        forked_from_thread_id: ThreadId,
        mut options: StartThreadOptions,
    ) -> CodexResult<NewThread>

作用：从已有线程的历史里创建一个子代理线程。子代理像主任务派出去的分身，会继承一段上下文再继续工作。

数据流：进去被 fork 的线程 id 和启动选项 → 找到源线程，确保历史已落盘并刷完，读取完整历史 → 把历史转成可恢复格式，再按“被中断快照”生成 fork 历史 → 启动新线程并记录来源。

调用关系：它调用 get_thread、stored_thread_to_initial_history、fork_history_from_snapshot，最后回到 start_thread_with_options_and_fork_source。

调用图：调用 5 个内部函数（from_config_and_version, get_thread, start_thread_with_options_and_fork_source, fork_history_from_snapshot, stored_thread_to_initial_history）。

async fn resume_thread_from_rollout(
        &self,
        config: Config,
        rollout_path: PathBuf,
        auth_manager: Arc<AuthManager>,
        parent_trace: Option<W3cTraceContext>,
    )

作用：从 rollout 文件路径恢复一个旧线程。rollout 可以理解成对话过程的持久化记录。

数据流：进去配置、rollout 路径、认证管理器和追踪信息 → 先从路径读取初始历史 → 调用 resume_thread_with_history 真正恢复线程 → 返回 NewThread。

调用关系：resume_conversation 会调用它；读取历史的细节在 initial_history_from_rollout_path。

调用图：调用 2 个内部函数（initial_history_from_rollout_path, resume_thread_with_history）；被 1 处调用（resume_conversation）；外部调用 1 个（pin）。

async fn resume_thread_with_history(
        &self,
        config: Config,
        initial_history: InitialHistory,
        auth_manager: Arc<AuthManager>,
        parent_trace: Option<W3cTraceContex

作用：用已经准备好的历史恢复线程。它适合历史不一定来自路径、而是调用者已经拿到的情况。

数据流：进去配置、初始历史、认证管理器和追踪信息 → 计算默认环境，从历史里推断会话来源和线程来源 → 调用状态对象 spawn_thread_with_source → 返回恢复后的线程。

调用关系：resume_thread_from_rollout 会调用它；它和新建线程共用同一套底层 spawn 流程。

调用图：调用 3 个内部函数（default_thread_environment_selections, agent_control, get_resumed_session_sources）；被 1 处调用（resume_thread_from_rollout）；外部调用 3 个（pin, new, default）。

async fn start_thread_with_user_shell_override_for_tests(
        &self,
        config: Config,
        user_shell_override: crate::shell::Shell,
    ) -> CodexResult<NewThread>

作用：测试专用：启动新线程时强行指定用户 shell。shell 是执行命令用的外壳程序，比如 bash 或 zsh。

数据流：进去配置和测试指定的 shell → 计算默认环境，组装新线程启动参数，并把 shell override 传到底层 → 返回新线程。

调用关系：测试辅助入口 start_thread_with_user_shell_override 会调用它；正式业务不应使用。

调用图：调用 2 个内部函数（default_thread_environment_selections, agent_control）；被 1 处调用（start_thread_with_user_shell_override）；外部调用 4 个（clone, pin, new, default）。

async fn resume_thread_from_rollout_with_user_shell_override_for_tests(
        &self,
        config: Config,
        rollout_path: PathBuf,
        auth_manager: Arc<AuthManager>,
        user_shell

作用：测试专用：从 rollout 恢复线程，同时强行指定 shell。它用来验证不同 shell 下恢复逻辑是否正确。

数据流：进去配置、rollout 路径、认证管理器和 shell → 读取历史、计算默认环境、推断来源 → 调用底层 spawn_thread_with_source，并传入 shell override。

调用关系：测试辅助入口会调用它；它复用了 initial_history_from_rollout_path 和底层恢复流程。

调用图：调用 3 个内部函数（default_thread_environment_selections, agent_control, initial_history_from_rollout_path）；被 1 处调用（resume_thread_from_rollout_with_user_shell_override）；外部调用 3 个（pin, new, default）。

async fn remove_thread(&self, thread_id: &ThreadId) -> Option<Arc<CodexThread>>

作用：把某个线程从管理器的内存表里移除。注意这不一定立刻销毁线程，因为别处可能还持有共享引用。

数据流：进去线程 id 引用 → 获取线程表写锁并删除对应项 → 返回被删除的线程引用，或 None。

调用关系：外部或测试需要手动卸载线程时会用它；状态对象里也有一个类似的 remove_thread。

async fn shutdown_all_threads_bounded(&self, timeout: Duration) -> ThreadShutdownReport

作用：在限定时间内并发关闭所有正在跟踪的线程。它能告诉调用者哪些关好了、哪些提交关闭失败、哪些超时。

数据流：进去超时时长 → 拿到当前线程快照，对每个线程并发调用 shutdown_and_wait，并套上超时 → 汇总报告，移除成功关闭的线程，排序后返回 ThreadShutdownReport。

调用关系：程序退出或测试清理时会调用它；没有按时关闭的线程会留在表里，方便之后重试或排查。

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

async fn fork_thread(
        &self,
        snapshot: S,
        config: Config,
        path: PathBuf,
        thread_source: Option<ThreadSource>,
        parent_trace: Option<W3cTraceContext>,

作用：从某个 rollout 路径读取历史，并按指定快照方式复制出新线程。它是从磁盘历史 fork 的入口。

数据流：进去快照规则、配置、路径、线程来源和追踪信息 → 读取路径对应的 InitialHistory → 调用 fork_thread_from_history → 返回新线程。

调用关系：外部 fork_thread API 会调用它；它把文件读取和实际 fork 分开处理。

调用图：调用 2 个内部函数（fork_thread_from_history, initial_history_from_rollout_path）；被 1 处调用（fork_thread）；外部调用 1 个（into）。

async fn initial_history_from_rollout_path(
        &self,
        rollout_path: PathBuf,
    ) -> CodexResult<InitialHistory>

作用：把一个 rollout 路径转成线程启动能用的初始历史。它负责从线程存储里把历史记录读出来。

数据流：进去 rollout 路径 → 通过 thread_store 按路径读取线程，并要求包含历史 → 调用 stored_thread_to_initial_history 转换格式 → 返回 InitialHistory。

调用关系：resume_thread_from_rollout、fork_thread 和测试恢复入口都会调用它。

调用图：调用 1 个内部函数（stored_thread_to_initial_history）；被 3 处调用（fork_thread, resume_thread_from_rollout, resume_thread_from_rollout_with_user_shell_override_for_tests）；外部调用 1 个（clone）。

async fn fork_thread_from_history(
        &self,
        snapshot: S,
        config: Config,
        history: InitialHistory,
        thread_source: Option<ThreadSource>,
        parent_trace: Optio

作用：从已经加载好的历史 fork 出一个新线程。调用者不必再提供 rollout 路径。

数据流：进去快照规则、配置、历史、线程来源和追踪信息 → 把快照参数转成 ForkSnapshot → 调用 fork_thread_with_initial_history → 返回新线程。

调用关系：fork_thread 会在读完历史后调用它；它是历史已在手时的 fork 入口。

调用图：调用 1 个内部函数（fork_thread_with_initial_history）；被 1 处调用（fork_thread）；外部调用 1 个（into）。

async fn fork_thread_with_initial_history(
        &self,
        snapshot: ForkSnapshot,
        config: Config,
        history: InitialHistory,
        thread_source: Option<ThreadSource>,

作用：执行真正的 fork 准备工作：判断来源、处理多代理版本、裁剪历史，再启动新线程。

数据流：进去快照规则、配置、历史、来源和追踪信息 → 推断 forked_from_thread_id，决定多代理版本，生成中断标记，按快照规则改写历史，计算默认环境 → 调用状态对象 spawn_thread 创建新线程。

调用关系：fork_thread_from_history 调用它；它使用 fork_history_from_snapshot 来处理历史切分。

调用图：调用 5 个内部函数（default_thread_environment_selections, from_config_and_version, agent_control, fork_history_from_snapshot, forked_from_id）；被 1 处调用（fork_thread_from_history）；外部调用 4 个（clone, pin, new, default）。

fn agent_control(&self) -> AgentControl

作用：创建一个 AgentControl 控制柄。它让代理相关代码能通过弱引用回到线程管理器状态，而不强行延长生命周期。

数据流：不需要输入 → 把 ThreadManagerState 的 Arc 降级成 weak 弱引用 → 创建并返回 AgentControl。

调用关系：启动线程、恢复线程、fork 和列子树时都会用它，把代理控制能力交给 Codex 或子代理流程。

调用图：调用 1 个内部函数（new）；被 6 处调用（fork_thread_with_initial_history, list_agent_subtree_thread_ids, resume_thread_from_rollout_with_user_shell_override_for_tests, resume_thread_with_history, start_thread_with_options_and_fork_source, start_thread_with_user_shell_override_for_tests）；外部调用 1 个（downgrade）。

fn captured_ops(&self) -> Vec<(ThreadId, Op)>

作用：测试专用：取出测试模式下记录过的线程操作。用于断言系统有没有向线程提交预期命令。

数据流：不需要输入 → 如果存在操作日志并能加锁，就复制日志内容；否则返回空列表 → 不改变状态。

调用关系：只有测试编译时存在；记录动作发生在 ThreadManagerState::send_op。

fn state_db(&self) -> Option<StateDbHandle>

作用：返回可选的状态数据库句柄。状态数据库保存线程生成关系等跨会话状态。

数据流：不需要输入 → 克隆 state_db 里的句柄 → 返回 Some 或 None。

调用关系：ThreadManager::list_agent_subtree_thread_ids 会用它读取已持久化的子孙线程关系。

async fn list_thread_ids(&self) -> Vec<ThreadId>

作用：列出当前加载在内存里的用户可见线程 id。内部线程不会出现在结果里。

数据流：不需要输入 → 读线程表，过滤掉 session_source 标记为内部的线程 → 收集并返回 id 列表。

调用关系：ThreadManager::list_thread_ids 委托它完成实际查询。

async fn list_live_thread_spawn_edges(&self) -> Vec<(ThreadId, ThreadId)>

作用：列出当前内存中活着的父子线程关系。它只看已加载线程，不读取数据库。

数据流：不需要输入 → 扫描线程表，跳过内部线程，找出 SubAgent::ThreadSpawn 类型的线程 → 返回父线程 id 到子线程 id 的边列表。

调用关系：代理控制或诊断代码可以用它了解当前活跃的线程树。

async fn get_thread(&self, thread_id: ThreadId) -> CodexResult<Arc<CodexThread>>

作用：在线程表里按 id 找线程，并屏蔽内部线程。它是状态层最基础的查找函数。

数据流：进去线程 id → 读锁查看 HashMap → 如果找到且不是内部线程，返回共享线程；否则返回 ThreadNotFound。

调用关系：send_op、user_instructions_for_spawn、initial_multi_agent_version_for_spawn 和 parent_rollout_thread_trace_for_source 都依赖它。

调用图：被 4 处调用（initial_multi_agent_version_for_spawn, parent_rollout_thread_trace_for_source, send_op, user_instructions_for_spawn）；外部调用 1 个（ThreadNotFound）。

async fn read_stored_thread(
        &self,
        params: ReadThreadParams,
    ) -> CodexResult<StoredThread>

作用：从线程存储里读取某个持久化线程，并把存储层错误翻译成 Codex 层错误。

数据流：进去 ReadThreadParams → 调用 thread_store.read_thread → 如果成功返回 StoredThread；如果是未找到或非法请求，转换成更适合上层的 CodexErr。

调用关系：这是状态层读取冷线程的统一工具，避免上层直接处理 ThreadStoreError 的细节。

async fn send_op(&self, thread_id: ThreadId, op: Op) -> CodexResult<String>

作用：向指定线程提交一个操作。操作 Op 可以理解成发给对话线程的一条命令或输入。

数据流：进去线程 id 和 Op → 先找到线程；如果测试日志开启，就记录一份；再调用 thread.submit → 返回提交 id 或错误。

调用关系：AgentControl 或其他调度代码会通过它给线程发命令；captured_ops 会读取它在测试模式下留下的日志。

调用图：调用 1 个内部函数（get_thread）；外部调用 1 个（clone）。

async fn remove_thread(&self, thread_id: &ThreadId) -> Option<Arc<CodexThread>>

作用：从状态对象的线程表里删除线程。它是底层版本的移除入口。

数据流：进去线程 id 引用 → 获取写锁，从 HashMap 删除对应线程 → 返回被删线程或 None。

调用关系：代理控制或内部清理代码可使用它；公开层也有 ThreadManager::remove_thread。

async fn effective_multi_agent_version_for_spawn(
        &self,
        initial_history: &InitialHistory,
        session_source: Option<&SessionSource>,
        parent_thread_id: Option<ThreadId>,

作用：决定新线程应该使用哪个多代理版本。多代理版本会影响子代理和中断标记的格式。

数据流：进去历史、来源、父线程 id、fork 来源 id 和配置 → 先尝试从历史或父线程继承版本；如果没有，就用配置里的特性开关算默认版本 → 返回最终版本。

调用关系：fork_thread_with_initial_history 会调用它；它内部依赖 initial_multi_agent_version_for_spawn。

调用图：调用 1 个内部函数（initial_multi_agent_version_for_spawn）。

async fn initial_multi_agent_version_for_spawn(
        &self,
        initial_history: &InitialHistory,
        session_source: Option<&SessionSource>,
        parent_thread_id: Option<ThreadId>,

作用：尝试从已有上下文推断新线程要继承的多代理版本。它优先尊重父线程、恢复历史或 fork 来源。

数据流：进去初始历史、可选会话来源、父线程 id、fork 来源 id → 找出可能继承的线程 id，查找该线程的版本 → 调用 resolve_multi_agent_version 合并历史和继承信息 → 返回可选版本。

调用关系：effective_multi_agent_version_for_spawn 和 spawn_thread_with_source 都会调用它，保证启动时版本选择一致。

调用图：调用 2 个内部函数（resolve_multi_agent_version, get_thread）；被 2 处调用（effective_multi_agent_version_for_spawn, spawn_thread_with_source）。

async fn user_instructions_for_spawn(
        &self,
        session_source: &SessionSource,
        parent_thread_id: Option<ThreadId>,
        forked_from_thread_id: Option<ThreadId>,
    ) -> Loade

作用：决定新线程启动时使用哪些用户指令。用户指令是用户预先写好的偏好或规则。

数据流：进去会话来源、父线程 id 和 fork 来源 id → 如果是根线程，就从 provider 重新加载用户指令；如果是子代理，就尽量从父线程的实时会话继承 → 返回指令和警告列表。

调用关系：spawn_thread_with_source 在真正创建 Codex 前调用它；这样子代理不会随便重新加载一套不同指令。

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

async fn spawn_new_thread(
        &self,
        config: Config,
        agent_control: AgentControl,
    ) -> CodexResult<NewThread>

作用：状态层的新线程便捷入口，使用默认会话来源且没有历史。

数据流：进去配置和 AgentControl → 补齐默认来源、无父线程、无 fork 来源等参数 → 调用 spawn_new_thread_with_source → 返回 NewThread。

调用关系：内部代理或控制流程可以用它快速启动根线程；更复杂情况走 spawn_new_thread_with_source。

调用图：调用 1 个内部函数（spawn_new_thread_with_source）；外部调用 2 个（pin, clone）。

async fn spawn_new_thread_with_source(
        &self,
        config: Config,
        agent_control: AgentControl,
        session_source: SessionSource,
        parent_thread_id: Option<ThreadId>,

作用：状态层的新线程启动入口，允许指定会话来源、父线程、继承环境和执行策略。

数据流：进去配置、控制柄、来源、父子关系、指标名、继承环境等 → 如果没传环境，就计算默认环境 → 调用 spawn_thread_with_source，以 InitialHistory::New 启动。

调用关系：spawn_new_thread 调用它；它把“新线程”这种情况转换成通用 spawn。

调用图：调用 1 个内部函数（spawn_thread_with_source）；被 1 处调用（spawn_new_thread）；外部调用 4 个（clone, pin, new, default）。

async fn resume_thread_with_history_with_source(
        &self,
        options: ResumeThreadWithHistoryOptions,
    ) -> CodexResult<NewThread>

作用：状态层的恢复线程入口，允许指定来源和继承信息。它常用于代理恢复场景。

数据流：进去 ResumeThreadWithHistoryOptions → 拆出配置、历史、控制柄、来源、父线程和继承信息 → 计算默认环境和 thread_source → 调用 spawn_thread_with_source。

调用关系：代理控制相关流程可调用它；它和公开的 resume_thread_with_history 类似，但参数更适合内部使用。

调用图：调用 2 个内部函数（default_thread_environment_selections, spawn_thread_with_source）；外部调用 4 个（clone, pin, new, default）。

async fn fork_thread_with_source(
        &self,
        config: Config,
        initial_history: InitialHistory,
        agent_control: AgentControl,
        session_source: SessionSource,
        th

作用：状态层的 fork 入口，允许指定会话来源、父线程、fork 来源和继承资源。

数据流：进去配置、初始历史、控制柄、来源、父子关系、继承环境等 → 补齐默认环境 → 调用 spawn_thread_with_source 创建线程。

调用关系：内部代理或多代理流程需要 fork 时会用它；真正创建逻辑仍集中在 spawn_thread_with_source。

调用图：调用 1 个内部函数（spawn_thread_with_source）；外部调用 4 个（clone, pin, new, default）。

async fn spawn_thread(
        &self,
        config: Config,
        initial_history: InitialHistory,
        auth_manager: Arc<AuthManager>,
        agent_control: AgentControl,
        parent_threa

作用：以管理器默认会话来源启动一个线程。它是通用 spawn 的一层简化包装。

数据流：进去配置、历史、认证、控制柄、父线程、fork 来源、工具、追踪、环境等 → 填入默认 session_source 和无继承环境策略 → 调用 spawn_thread_with_source。

调用关系：ThreadManager 的 fork 和测试启动入口会调用它；它把参数转给最底层的 spawn_thread_with_source。

调用图：调用 1 个内部函数（spawn_thread_with_source）；外部调用 2 个（pin, clone）。

async fn spawn_thread_with_source(
        &self,
        config: Config,
        initial_history: InitialHistory,
        auth_manager: Arc<AuthManager>,
        agent_control: AgentControl,

作用：这是创建或恢复线程的核心函数。它负责处理重复恢复、用户指令、版本继承、追踪上下文，然后真正启动 Codex。

数据流：进去完整启动参数 → 如果是恢复已有运行线程，就直接返回现有线程；否则加载或继承用户指令，准备父 trace 和多代理版本，调用 Codex::spawn → 再调用 finalize_thread_spawn 注册线程并返回 NewThread。

调用关系：几乎所有 start、resume、fork、subagent 流程最终都会走到这里；它把准备工作交给 user_instructions_for_spawn、initial_multi_agent_version_for_spawn、parent_rollout_thread_trace_for_source 和 finalize_thread_spawn。

调用图：调用 5 个内部函数（spawn, finalize_thread_spawn, initial_multi_agent_version_for_spawn, parent_rollout_thread_trace_for_source, user_instructions_for_spawn）；被 4 处调用（fork_thread_with_source, resume_thread_with_history_with_source, spawn_new_thread_with_source, spawn_thread）；外部调用 6 个（clone, pin, clone, format!, matches!, InvalidRequest）。

async fn finalize_thread_spawn(
        &self,
        codex: Codex,
        thread_id: ThreadId,
        session_source: SessionSource,
    ) -> CodexResult<NewThread>

作用：完成线程启动后的最后验收和登记。它要求 Codex 发出的第一个事件必须是 SessionConfigured。

数据流：进去刚启动的 Codex、线程 id 和会话来源 → 读取第一个事件，确认是正确的配置事件 → 创建 CodexThread 并插入线程表；如果 id 已存在，就关闭重复 Codex 并返回错误。

调用关系：spawn_thread_with_source 在 Codex::spawn 成功后调用它；它保证外部拿到的线程已经有可靠的 session_configured 信息。

调用图：调用 3 个内部函数（new, next_event, shutdown_and_wait）；被 1 处调用（spawn_thread_with_source）；外部调用 4 个（new, format!, InvalidRequest, warn!）。

fn notify_thread_created(&self, thread_id: ThreadId)

作用：向订阅者广播某个线程已经创建。广播失败不会影响主流程。

数据流：进去线程 id → 发送到 thread_created_tx 广播通道 → 不关心是否有接收者或发送是否成功。

调用关系：创建通知的生产者会调用它；subscribe_thread_created 返回的接收器会收到这里发出的 id。

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

async fn parent_rollout_thread_trace_for_source(
        &self,
        session_source: &SessionSource,
        initial_history: &InitialHistory,
    ) -> codex_rollout_trace::ThreadTraceContext

作用：为新建子代理准备父线程的 rollout 追踪上下文。追踪上下文用于把父子线程的历史记录串成一棵树。

数据流：进去会话来源和初始历史 → 如果不是新建的 ThreadSpawn 子代理，或是恢复历史，就返回禁用追踪；否则查找父线程并复制它的 rollout trace，查不到也返回禁用 → 输出 ThreadTraceContext。

调用关系：spawn_thread_with_source 在创建 Codex 前调用它；它依赖 get_thread，但失败不会阻止子线程创建。

调用图：调用 2 个内部函数（get_thread, disabled）；被 1 处调用（spawn_thread_with_source）；外部调用 1 个（matches!）。

fn stored_thread_to_initial_history(
    stored_thread: StoredThread,
    rollout_path: Option<PathBuf>,
) -> CodexResult<InitialHistory>

作用：把存储层读出来的 StoredThread 转成启动线程用的 InitialHistory。它要求存储结果必须带历史内容。

数据流：进去 StoredThread 和可选 rollout 路径 → 检查 history 是否存在；不存在就报 Fatal → 把线程 id、历史条目和 rollout 路径包装成 InitialHistory::Resumed。

调用关系：initial_history_from_rollout_path 和 spawn_subagent 都会调用它，把持久化数据接到启动流程。

调用图：被 2 处调用（initial_history_from_rollout_path, spawn_subagent）；外部调用 1 个（Resumed）。

fn thread_store_rollout_read_error(err: ThreadStoreError) -> CodexErr

作用：把按 rollout 路径读取线程时的存储错误翻译成 Codex 错误。这样上层不用理解存储库的内部错误类型。

数据流：进去 ThreadStoreError → 未找到转成 ThreadNotFound，非法请求转成 InvalidRequest，其他错误转成 Fatal → 返回 CodexErr。

调用关系：initial_history_from_rollout_path 在读取失败时使用它。

调用图：外部调用 4 个（format!, Fatal, InvalidRequest, ThreadNotFound）。

fn thread_store_metadata_update_error(thread_id: ThreadId, err: ThreadStoreError) -> CodexErr

作用：把更新线程元数据时的存储错误翻译成 Codex 错误。它会特别处理“不支持更新”这种情况。

数据流：进去线程 id 和 ThreadStoreError → 根据错误类别转换成 ThreadNotFound、InvalidRequest、UnsupportedOperation 或 Fatal → 返回 CodexErr。

调用关系：ThreadManager::update_thread_metadata 在运行线程或冷线程更新失败时都会用它包装错误。

调用图：外部调用 5 个（format!, Fatal, InvalidRequest, ThreadNotFound, UnsupportedOperation）。

fn truncate_before_nth_user_message(
    history: InitialHistory,
    n: usize,
    snapshot_state: &SnapshotTurnState,
) -> InitialHistory

作用：生成一个在第 n 条用户消息之前截断的 fork 历史。它用于从旧对话的某个点开新分支。

数据流：进去历史、用户消息序号 n 和当前快照是否处于半回合状态 → 找出所有用户消息位置；如果 n 越界且历史还在半回合，就切掉未完成回合；否则按第 n 条用户消息前截断 → 空历史返回 New，非空返回 Forked。

调用关系：fork_history_from_snapshot 在 TruncateBeforeNthUserMessage 模式下调用它；它依赖 truncation 工具找用户消息位置。

调用图：调用 1 个内部函数（get_rollout_items）；被 1 处调用（fork_history_from_snapshot）；外部调用 3 个（Forked, truncate_rollout_before_nth_user_message_from_start, user_message_positions_in_rollout）。

fn snapshot_turn_state(history: &InitialHistory) -> SnapshotTurnState

作用：判断一段历史是不是停在“半个回合”中。半个回合是用户发话后，系统还没完整结束或中断的状态。

数据流：进去 InitialHistory → 取出 rollout 条目，用 ThreadHistoryBuilder 重建回合状态 → 如果有明确活跃回合且还在进行中，记录 turn_id 和起点；否则用最后一条用户消息后是否有完成或中断事件来判断 → 返回 SnapshotTurnState。

调用关系：fork_history_from_snapshot 先调用它，再决定 fork 时是直接截断还是补一个中断边界。

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

fn fork_history_from_snapshot(
    snapshot: ForkSnapshot,
    history: InitialHistory,
    interrupted_marker: InterruptedTurnHistoryMarker,
) -> InitialHistory

作用：按指定快照规则把原历史改造成 fork 用历史。它处理“截断到某条用户消息前”和“像现在被中断一样复制”两种模式。

数据流：进去 ForkSnapshot、原始历史和中断标记配置 → 先判断历史是否半回合；截断模式交给 truncate_before_nth_user_message；中断模式会把恢复历史转成 fork 历史，并在半回合时追加中断边界 → 返回新的 InitialHistory。

调用关系：fork_thread_with_initial_history 和 spawn_subagent 都调用它；追加中断事件的细节交给 append_interrupted_boundary。

调用图：调用 3 个内部函数（append_interrupted_boundary, snapshot_turn_state, truncate_before_nth_user_message）；被 2 处调用（fork_thread_with_initial_history, spawn_subagent）；外部调用 1 个（Forked）。

fn append_interrupted_boundary(
    history: InitialHistory,
    turn_id: Option<String>,
    interrupted_marker: InterruptedTurnHistoryMarker,
) -> InitialHistory

作用：给 fork 历史末尾补上和真实中断一样的记录。这样新分支不会误以为上一个回合还在继续。

数据流：进去历史、可选 turn_id 和中断标记配置 → 创建 TurnAborted 事件，必要时先追加一个响应标记 → 把这些条目加入历史，最终返回 InitialHistory::Forked。

调用关系：fork_history_from_snapshot 在 Interrupted 模式且发现历史半回合时调用它；它复用 interrupted_turn_history_marker，保持和真实中断路径一致。

调用图：调用 1 个内部函数（interrupted_turn_history_marker）；被 1 处调用（fork_history_from_snapshot）；外部调用 6 个（new, TurnAborted, Forked, push, EventMsg, ResponseItem）。

fn default_thread_environment_selections(
    environment_manager: &EnvironmentManager,
    cwd: &AbsolutePathBuf,
) -> Vec<TurnEnvironmentSelection>

作用：生成一轮对话默认要使用的环境列表。它把环境管理器里的默认环境编号，配上当前工作目录，变成后面能解析的选择项。

数据流：输入是环境管理器和当前目录 → 它读取管理器给出的默认环境编号，并把当前目录转成路径 URI（一种可表示本地或远程路径的格式）→ 输出一组 TurnEnvironmentSelection，每个选择都包含环境编号和工作目录。

调用关系：它通常在新建、恢复或派生线程时先被调用，用来给 ThreadEnvironments 提供初始选择。它自己只问 default_environment_ids 要编号，不真正连接环境。

调用图：调用 1 个内部函数（default_environment_ids）；被 7 处调用（default_environment_selections, fork_thread_with_initial_history, resume_thread_from_rollout_with_user_shell_override_for_tests, resume_thread_with_history, start_thread_with_tools, start_thread_with_user_shell_override_for_tests, resume_thread_with_history_with_source）。

fn new(
        environment_manager: Arc<EnvironmentManager>,
        local_shell: Shell,
        shell_snapshot: ShellSnapshot,
        current: TurnEnvironmentSnapshot,
    ) -> Self

作用：创建一个保存“当前环境快照”的容器。它把环境管理器、本地 shell、shell 快照工具和已有快照装起来，供后续更新和读取。

数据流：输入是环境管理器、本地命令行外壳、shell 快照器和当前快照 → 它把当前快照包装成一个已经完成的异步任务 → 输出 ThreadEnvironments 实例，里面已经有一份可读取的初始快照。

调用关系：会在会话或测试搭建时调用。之后 update_selections 会替换里面的快照任务，snapshot 会读取这个任务的结果。

调用图：被 7 处调用（latest_environment_update_wins_while_previous_resolution_is_pending, local_environment_uses_configured_shell, resolve_turn_environments, new, make_session_and_context, make_session_and_context_with_auth_config_home_and_rx, resolved_environments_for_configuration）；外部调用 2 个（from_pointee, ready）。

fn update_selections(&self, environments: &[TurnEnvironmentSelection])

作用：把新的环境选择应用到当前线程。它不会卡住调用者，而是启动后台任务去解析新选择，并让“最新一次更新”成为之后读取的目标。

数据流：输入是一组新的 TurnEnvironmentSelection → 它先尽量拿到上一份已完成快照，以便复用已有环境；然后复制需要的信息，启动异步解析任务 → 它更新内部的 snapshot_task，之后 snapshot 会等这次新任务完成。

调用关系：外部在用户切换环境或线程初始化时调用它。它把真正解析工作交给 resolve_snapshot，并通过 tokio 后台任务运行；这样即使旧解析还卡着，新的选择也能覆盖旧的读取入口。

调用图：外部调用 9 个（clone, new, load, store, resolve_snapshot, clone, clone, to_vec, spawn）。

async fn resolve_snapshot(
        environment_manager: Arc<EnvironmentManager>,
        local_shell: Shell,
        shell_snapshot: ShellSnapshot,
        current: TurnEnvironmentSnapshot,
        en

作用：把一批环境选择解析成一份完整快照。它负责去重、复用旧结果，并跳过无法解析的环境。

数据流：输入是环境管理器、本地 shell、shell 快照器、上一份快照和新的选择列表 → 它按顺序处理选择，重复的环境编号只保留第一次；如果旧快照里已有同编号同目录的环境就直接复用，否则调用 resolve_selection 新建 → 输出 TurnEnvironmentSnapshot，里面只有成功解析的环境。

调用关系：它由 update_selections 启动的后台任务调用。遇到单个环境失败时只记录警告，不中断整个快照生成。

调用图：外部调用 4 个（with_capacity, resolve_selection, with_capacity, warn!）。

async fn resolve_selection(
        environment_manager: &EnvironmentManager,
        local_shell: &Shell,
        shell_snapshot: &ShellSnapshot,
        selected_environment: &TurnEnvironmentSelecti

作用：把一个具体的环境选择变成真正可用的 TurnEnvironment。它会找到环境对象，确定应该用哪个 shell，并启动 shell 快照构建。

数据流：输入是环境管理器、本地 shell、shell 快照器和一个选择项 → 它用环境编号查找环境；远程环境会询问远端信息来推断 shell，本地环境直接使用配置好的本地 shell；然后创建 TurnEnvironment，并在后台准备 shell 快照 → 成功时输出 TurnEnvironment，失败时返回错误。

调用关系：resolve_snapshot 在需要新建环境时调用它。它会调用环境管理器的 get_environment，也会使用 Shell::from_environment_shell_info 解释远程返回的 shell 信息，并把 shell 快照构建任务交给 tokio 执行。

调用图：调用 3 个内部函数（new, from_environment_shell_info, get_environment）；外部调用 4 个（clone, clone, spawn, warn!）。

async fn snapshot(&self) -> TurnEnvironmentSnapshot

作用：读取当前这份环境快照。如果后台解析还没完成，它会等待完成后再返回。

数据流：输入是 ThreadEnvironments 自身 → 它取出当前保存的异步快照任务并等待结果 → 输出 TurnEnvironmentSnapshot，不直接改变环境选择。

调用关系：后续需要运行命令、找主环境或拿文件系统的地方会调用它。它读取的是 update_selections 最近一次存进去的任务。

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

fn environment_manager(&self) -> Arc<EnvironmentManager>

作用：拿到内部保存的环境管理器。调用者可以继续用它查询或操作可用环境。

数据流：输入是 ThreadEnvironments 自身 → 它克隆 Arc（共享引用计数指针，可以安全共享同一个对象）→ 输出同一个 EnvironmentManager 的共享句柄。

调用关系：这是一个简单的访问口。它不解析环境，只把 ThreadEnvironments 里持有的管理器交给需要的人。

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

fn primary(&self) -> Option<&TurnEnvironment>

作用：取出快照里的第一个环境，也就是默认的主环境。很多地方会把第一个环境当作最重要、最先使用的那个。

数据流：输入是一份环境快照 → 它查看环境列表的第一个元素 → 如果有环境就返回引用，没有就返回空。

调用关系：primary_environment 和 primary_filesystem 都通过它找主环境。它体现了“选择列表顺序很重要”的规则。

调用图：被 2 处调用（primary_environment, primary_filesystem）。

fn local(&self) -> Option<&TurnEnvironment>

作用：在快照里找一个本地环境。需要明确在本机执行或读取本机信息时会用到它。

数据流：输入是一份环境快照 → 它从前到后检查每个环境是否不是远程环境 → 找到第一个本地环境就返回，否则返回空。

调用关系：这是快照上的便捷查询函数。它不创建环境，只在已有清单里筛选。

fn primary_environment(&self) -> Option<Arc<codex_exec_server::Environment>>

作用：测试用的辅助函数，用来拿到主环境背后的 Environment 对象。它方便测试比较是不是同一个环境实例。

数据流：输入是一份快照 → 它先调用 primary 找主环境，再克隆里面的共享 Environment 指针 → 输出主环境对象的共享句柄，或空。

调用关系：只在测试编译时存在。它依赖 primary，所以主环境的定义仍然是列表第一个。

调用图：调用 1 个内部函数（primary）。

fn to_selections(&self) -> Vec<TurnEnvironmentSelection>

作用：把已经解析好的环境快照重新变回选择列表。测试或保存状态时，可以用它检查当前快照对应哪些环境编号和目录。

数据流：输入是一份快照 → 它遍历每个 TurnEnvironment，并调用它自己的 selection 方法 → 输出一组 TurnEnvironmentSelection。

调用关系：测试经常用它确认解析结果是否符合预期。它是“解析后的环境”到“可记录的选择项”的反向转换。

fn primary_filesystem(&self) -> Option<Arc<dyn ExecutorFileSystem>>

作用：拿到主环境的文件系统接口。后续如果要预热插件或读取主环境里的文件，就需要这个入口。

数据流：输入是一份快照 → 它先调用 primary 找主环境，再从主环境对象里取文件系统 → 输出文件系统的共享接口，或空。

调用关系：warm_plugins_and_skills_for_session_init 会用它在会话初始化时准备插件和技能。它把调用者从“先找主环境再取文件系统”的细节里解放出来。

调用图：调用 1 个内部函数（primary）；被 1 处调用（warm_plugins_and_skills_for_session_init）。

fn single_local_environment(&self) -> Option<&TurnEnvironment>

作用：确认快照里“只有一个环境，而且它是本地环境”。只有满足这个严格条件时才返回它。

数据流：输入是一份快照 → 它检查列表是否刚好一个元素，再检查这个环境不是远程 → 条件都满足就返回该环境，否则返回空。

调用关系：single_local_environment_cwd 会调用它。这个严格判断是为了避免在多环境或远程环境场景下误把路径当成本机路径。

调用图：被 1 处调用（single_local_environment_cwd）。

fn single_local_environment_cwd(&self) -> Option<AbsolutePathBuf>

作用：在兼容老代码时使用：如果当前只有一个本地环境，就把它的工作目录转成本机绝对路径。

数据流：输入是一份快照 → 它先调用 single_local_environment 确认只有一个本地环境；再把 PathUri 转成 AbsolutePathBuf（本机绝对路径）→ 成功则输出路径，不满足条件或转换失败就返回空。

调用关系：这是过渡用的兼容入口。注释里也说明，未来更多地方改用 PathUri 后，这种转换就可以删掉。

调用图：调用 1 个内部函数（single_local_environment）。

async fn resolve_turn_environments(
        environment_manager: Arc<EnvironmentManager>,
        selections: &[TurnEnvironmentSelection],
    ) -> Arc<ThreadEnvironments>

作用：测试用的小工具：给一组选择，快速建好 ThreadEnvironments 并等它解析完成。

数据流：输入是环境管理器和选择列表 → 它创建 ThreadEnvironments，使用默认用户 shell 和禁用的 shell 快照器；然后调用 update_selections 并等待 snapshot 完成 → 输出可继续检查的 ThreadEnvironments。

调用关系：多个测试复用它，避免每个测试都重复搭建异步环境解析流程。它覆盖的是正式的 new、update_selections 和 snapshot 路线。

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

fn test_runtime_paths() -> ExecServerRuntimePaths

作用：测试用的小工具：构造执行服务器需要的运行时路径。它让测试环境知道当前可执行文件在哪里。

数据流：输入为空 → 它读取当前测试进程的可执行文件路径，并传给 ExecServerRuntimePaths::new → 输出测试可用的运行时路径配置。

调用关系：涉及远程环境或执行服务器的测试会调用它。它只是准备测试依赖，不参与正式运行逻辑。

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

async fn default_thread_environment_selections_use_manager_default_id()

作用：验证默认环境选择会使用环境管理器给出的默认编号。这里的场景是测试管理器默认指向远程环境。

数据流：输入是测试创建出的当前目录和环境管理器 → 它调用 default_thread_environment_selections → 断言输出正好是远程环境编号加当前目录 URI。

调用关系：它直接测试 default_thread_environment_selections，确保线程启动时默认选项不会乱用别的环境。

调用图：调用 3 个内部函数（create_for_tests, current_dir, from_abs_path）；外部调用 2 个（assert_eq!, test_runtime_paths）。

async fn toml_default_thread_environment_selections_include_local_and_remote()

作用：验证从 environments.toml 配置读环境时，默认选择会同时包含本地和远程环境。

数据流：输入是临时目录里的 environments.toml 和当前目录 → 它从配置目录创建 EnvironmentManager，再生成默认选择 → 断言结果先有本地环境，再有远程环境，并且目录相同。

调用关系：它覆盖配置文件影响默认环境列表的情况。这样可以防止配置加载后默认环境顺序或内容被改坏。

调用图：调用 3 个内部函数（from_codex_home, current_dir, from_abs_path）；外部调用 4 个（assert_eq!, test_runtime_paths, write, tempdir）。

async fn default_thread_environment_selections_empty_when_default_disabled()

作用：验证如果环境功能被关闭，默认选择就是空列表。这样不会偷偷启用任何执行环境。

数据流：输入是一个没有环境的 EnvironmentManager → 它调用 default_thread_environment_selections → 断言输出为空。

调用关系：它测试 default_thread_environment_selections 的禁用场景，保证没有默认环境时线程不会凭空创建环境。

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

async fn local_environment_uses_configured_shell()

作用：验证本地环境会使用外部配置好的 shell，而不是随便重新猜一个。shell 就是运行命令的程序，比如 zsh 或 bash。

数据流：输入是一个指定为 zsh 的本地 shell 和本地环境选择 → 它创建 ThreadEnvironments，更新选择并读取快照 → 断言主环境里保存的 shell 就是配置的那个。

调用关系：它测试 resolve_selection 处理本地环境的分支。这个测试保证用户配置的命令行外壳会被尊重。

调用图：调用 5 个内部函数（new, disabled, default_for_tests, current_dir, from_abs_path）；外部调用 4 个（new, assert_eq!, default, from）。

async fn resolve_environment_selections_keeps_first_duplicate_id()

作用：验证同一个环境编号出现多次时，只保留第一次。这样同一环境不会因为重复选择而被加入两遍。

数据流：输入是两个同编号但目录不同的本地环境选择 → 它解析这些选择 → 断言最终快照只保留第一个选择。

调用关系：它测试 resolve_snapshot 的去重规则。这个规则防止调用者传入重复项时造成混乱。

调用图：调用 3 个内部函数（default_for_tests, current_dir, from_abs_path）；外部调用 3 个（new, assert_eq!, resolve_turn_environments）。

async fn resolved_environment_selections_use_first_selection_as_primary()

作用：验证解析后的第一个选择会成为主环境。主环境会被很多后续功能优先使用，所以顺序必须可靠。

数据流：输入是一个本地环境选择和指定工作目录 → 它解析后读取快照 → 断言 primary 的环境编号、工作目录和 shell 都符合预期。

调用关系：它测试 resolve_snapshot 保持选择顺序，以及 primary 的语义。它还间接确认 shell 信息能正确解析出来。

调用图：调用 3 个内部函数（default_for_tests, current_dir, from_abs_path）；外部调用 4 个（clone, new, assert_eq!, resolve_turn_environments）。

async fn unresolved_environment_selections_are_skipped()

作用：验证不存在的环境编号会被跳过，而不会让所有环境解析失败。

数据流：输入是一个缺失环境选择和一个正常本地环境选择 → 它解析选择列表 → 断言最终只剩正常本地环境。

调用关系：它测试 resolve_snapshot 对 resolve_selection 错误的处理方式。这个行为能让部分配置坏掉时系统仍尽量可用。

调用图：调用 3 个内部函数（default_for_tests, current_dir, from_abs_path）；外部调用 3 个（new, assert_eq!, resolve_turn_environments）。

async fn latest_environment_update_wins_while_previous_resolution_is_pending()

作用：验证如果旧的远程解析还卡着，后来的本地环境更新仍然能赢。也就是说，用户最新选择不会被慢吞吞的旧任务覆盖。

数据流：输入是一个会挂起连接的远程环境选择，然后再输入本地环境选择 → 它先启动远程解析并等连接发生，再调用 update_selections 改成本地 → 最终 snapshot 返回本地选择。

调用关系：它测试 update_selections 的并发更新设计。ArcSwap 保存的是最新任务，所以 snapshot 会跟随最后一次更新。

调用图：调用 6 个内部函数（new, default_user_shell, disabled, create_for_tests_with_local, current_dir, from_abs_path）；外部调用 9 个（new, assert_eq!, default, test_runtime_paths, format!, from_ref, from_secs, bind, timeout）。

async fn matching_environment_id_and_cwd_reuse_resolved_environment()

作用：验证环境编号和工作目录都没变时，会复用已经解析好的环境；目录变了才重新解析。

数据流：输入是一个远程环境选择 → 它先解析一次，再修改管理器里的远程地址；随后用相同选择更新，检查仍复用旧 Environment；再改工作目录更新，检查这次变成新 Environment → 输出是断言结果。

调用关系：它测试 resolve_snapshot 的复用逻辑。复用可以减少不必要的远程连接，但目录变化必须触发重新创建，避免用错工作目录。

调用图：调用 3 个内部函数（create_for_tests, current_dir, from_abs_path）；外部调用 6 个（clone, new, assert!, resolve_turn_environments, test_runtime_paths, from_ref）。

async fn single_local_environment_cwd_requires_exactly_one_local_environment()

作用：验证 single_local_environment_cwd 只有在“刚好一个本地环境”时才返回路径。远程环境或多个环境时都不能返回本机路径。

数据流：输入分别是单一本地快照、单一远程快照、以及本地加远程的多环境快照 → 它调用 single_local_environment_cwd → 断言只有单一本地场景返回当前目录，另外两种都返回空。

调用关系：它测试 single_local_environment 和 single_local_environment_cwd 的安全边界。这个边界避免多环境时代码误以为某个 URI 一定是本机路径。

调用图：调用 4 个内部函数（create_for_tests, default_for_tests, current_dir, from_abs_path）；外部调用 5 个（clone, new, assert_eq!, resolve_turn_environments, vec!）。

fn new(reason: TryStartTurnIfIdleRejectionReason, input: Vec<ResponseItem>) -> Self

作用：创建一个“空闲自动启动失败”的错误对象。它不仅说明为什么失败，还把原始输入原封不动带回去，方便调用方稍后重试或记录。

数据流：进去的是失败原因和本来要交给模型看的输入项；函数把它们装进 TryStartTurnIfIdleError；出来的是一个包含原因和原输入的错误值，不改动外部状态。

调用关系：它由 try_start_turn_if_idle 这类空闲启动流程在拒绝自动任务时使用，是把底层拒绝原因包装成稳定错误的收口。

调用图：被 1 处调用（try_start_turn_if_idle）。

fn reason(&self) -> TryStartTurnIfIdleRejectionReason

作用：读取这次空闲自动启动为什么被拒绝。调用方可以据此决定是等会儿再试、直接丢弃，还是提示用户。

数据流：进去的是这个错误对象本身；函数只读取里面保存的 reason；出来的是一个固定的拒绝原因，不消耗错误对象，也不改任何状态。

调用关系：它通常在拿到 TryStartTurnIfIdleError 后被上层代码调用，用来理解 try_start_turn_if_idle 为什么没能启动。

fn into_input(self) -> Vec<ResponseItem>

作用：把失败时没能提交的原始输入取回来。这样失败不会让模型输入丢失。

数据流：进去的是整个错误对象；函数消耗这个错误对象，取出其中保存的输入列表；出来的是原来的 ResponseItem 列表，不做修改。

调用关系：它接在 try_start_turn_if_idle 失败之后使用，让插件或调用方可以重试、丢弃或写日志，而不是把输入困在错误里。

fn cwd(&self) -> &AbsolutePathBuf

作用：返回这个线程当前认为的工作目录，也就是命令和文件操作默认从哪里开始。工作目录像“当前所在文件夹”，很多安全和路径判断都靠它。

数据流：进去的是配置快照；函数读取 environments 里的 legacy_fallback_cwd；出来的是这个目录的引用，不复制也不修改配置。

调用关系：它会被恢复线程、比较配置差异、从快照生成设置，以及 sandbox_policy 使用，属于很多配置判断的基础小入口。

调用图：被 4 处调用（build_thread_from_snapshot, collect_resume_override_mismatches, thread_settings_from_config_snapshot, sandbox_policy）。

fn environment_selections(&self) -> &[TurnEnvironmentSelection]

作用：返回这个线程可用的运行环境选择列表。外部代码可以看出这一轮可能在哪些环境里执行。

数据流：进去的是配置快照；函数读取 environments.environments；出来的是环境选择列表的只读切片，不改任何内容。

调用关系：它是读取 ThreadConfigSnapshot 的便捷方法，供需要展示或检查运行环境的代码使用。

fn sandbox_policy(&self) -> SandboxPolicy

作用：根据线程的权限配置和当前工作目录，算出实际的沙盒策略。沙盒就是给程序活动范围加围栏，防止它随便读写或执行危险操作。

数据流：进去的是配置快照；函数先通过 cwd 取工作目录，再把权限配置和目录交给沙盒兼容函数计算；出来的是 SandboxPolicy，不保存到快照里。

调用关系：它在比较恢复时的配置差异时会被调用，用来判断当前权限配置会对应怎样的实际执行限制。

调用图：调用 1 个内部函数（cwd）；被 1 处调用（collect_resume_override_mismatches）；外部调用 1 个（compatibility_sandbox_policy_for_permission_profile）。

fn new(
        codex: Codex,
        session_configured: SessionConfiguredEvent,
        rollout_path: Option<PathBuf>,
        session_source: SessionSource,
    ) -> Self

作用：创建一个新的 CodexThread，把底层 Codex、会话配置、记录路径和来源信息包在一起。没有这一步，外部就没有统一的线程操作入口。

数据流：进去的是底层 Codex、SessionConfiguredEvent、可选 rollout 路径和会话来源；函数把它们存进结构体，并把离线询问计数初始化为 0；出来的是新的 CodexThread。

调用关系：它由 finalize_thread_spawn 在线程真正生成完后调用，是线程从底层会话变成对外对象的最后装配步骤。

调用图：被 1 处调用（finalize_thread_spawn）；外部调用 1 个（new）。

async fn submit(&self, op: Op) -> CodexResult<String>

作用：向线程提交一个操作，比如用户输入、控制命令或其他协议动作。它是很多上层流程最常用的投递入口。

数据流：进去的是一个 Op 操作；函数原样交给底层 Codex.submit；出来的是提交编号或错误，底层队列会因此收到新工作。

调用关系：提交线程设置、实时会话开关、请求捕获、用户输入、队列消息和运行一轮等流程都会用它；它自己主要把活交给 Codex。

调用图：调用 1 个内部函数（submit）；被 8 处调用（submit_thread_settings, close_realtime_conversation, start_realtime_conversation, capture_from_requests, submit_user_input, submit_queue_only_agent_mail, submit_user_input, run_turn）。

fn session_telemetry(&self) -> SessionTelemetry

作用：取出这个线程的遥测句柄。遥测就是运行时统计和日志，用来观察系统表现、排查问题。

数据流：进去的是线程对象；函数读取底层 session services 里的 session_telemetry 并克隆一份句柄；出来的是可继续使用的 SessionTelemetry。

调用关系：它给需要记录线程级生产数据的外部路径使用，不让调用方直接进入更大的 session 内部。

async fn shutdown_and_wait(&self) -> CodexResult<()>

作用：请求线程关闭，并等待它真的收尾结束。用于保证后台任务、队列和资源不是半途被硬切。

数据流：进去的是线程对象；函数把关闭请求交给 Codex.shutdown_and_wait；出来的是成功或 Codex 错误，底层会话状态会走向终止。

调用关系：它是关闭流程的对外入口，真正的关闭细节由底层 Codex 执行。

调用图：调用 1 个内部函数（shutdown_and_wait）。

async fn wait_until_terminated(&self)

作用：只等待底层会话循环已经结束，不主动发起关闭。适合已经触发关闭后，另一个地方想等它完全停下。

数据流：进去的是线程对象；函数等待 session_loop_termination 这个异步完成信号；出来时没有返回值，只表示底层循环已经终止。

调用关系：loop_agent 会用它等待代理线程结束，避免外层循环在线程还没停稳时继续推进。

调用图：被 1 处调用（loop_agent）。

async fn emit_thread_resume_lifecycle(&self)

作用：在线程恢复时通知所有插件式扩展：这个线程又回来了。这样扩展可以恢复自己存在会话或线程里的附加数据。

数据流：进去的是线程对象；函数遍历扩展提供的线程生命周期贡献者，把 session_store 和 thread_store 传给它们的 on_thread_resume；出来没有返回值，但扩展可能更新自己的数据。

调用关系：它处在线程恢复流程中，像广播通知一样逐个叫醒扩展；每个扩展收到通知后自行处理恢复工作。

async fn emit_thread_idle_lifecycle_if_idle(&self)

作用：如果线程现在真的空闲，就触发“线程空闲”的生命周期通知。插件可以借这个时机做不打扰用户的后台工作。

数据流：进去的是线程对象；函数把判断和触发动作交给 session.emit_thread_idle_lifecycle_if_idle；出来没有直接结果，可能引发扩展回调。

调用关系：emit_resume_goal_snapshot_and_continue 会调用它，让恢复后的线程在合适时机继续空闲相关工作。

调用图：被 1 处调用（emit_resume_goal_snapshot_and_continue）。

async fn ensure_rollout_materialized(&self)

作用：确保线程的 rollout 记录已经落成实际可用的存储。rollout 可以理解为这段会话的执行记录。

数据流：进去的是线程对象；函数调用底层 session.ensure_rollout_materialized；出来没有返回值，但底层可能创建或准备好记录文件。

调用关系：这是隐藏的内部辅助入口，给需要确保记录存在的流程使用，实际工作由 Session 完成。

async fn flush_rollout(&self) -> std::io::Result<()>

作用：把当前 rollout 记录刷到磁盘或持久层，减少崩溃时丢记录的风险。

数据流：进去的是线程对象；函数调用 session.flush_rollout；出来是 I/O 成功或失败结果，持久化记录可能被更新。

调用关系：它是线程层面的保存按钮，底层写入细节由 Session 管。

async fn submit_with_trace(
        &self,
        op: Op,
        trace: Option<W3cTraceContext>,
    ) -> CodexResult<String>

作用：提交一个操作，同时带上追踪信息。追踪信息像快递单号，可以把一次请求经过的不同模块串起来排查。

数据流：进去的是 Op 和可选 W3cTraceContext；函数交给 Codex.submit_with_trace；出来的是提交编号或错误，底层收到带追踪上下文的新操作。

调用关系：submit_core_op 会用它提交核心操作，让请求链路的追踪信息能继续传到 Codex 内部。

调用图：调用 1 个内部函数（submit_with_trace）；被 2 处调用（submit_core_op, submit_core_op）。

async fn submit_user_input_with_client_user_message_id(
        &self,
        op: Op,
        trace: Option<W3cTraceContext>,
        client_user_message_id: Option<String>,
    ) -> CodexResult<Stri

作用：提交用户输入，并保留客户端给这条用户消息的编号。提交前还会先确认当前线程有执行容量，避免把任务塞进已经不该执行的状态。

数据流：进去的是操作、可选追踪信息和可选客户端消息编号；函数先让 agent_control 检查这个操作能不能执行，再交给底层提交；出来的是提交编号或错误，队列中会出现一条带客户端标识的用户输入。

调用关系：它是更严格的用户输入入口，比普通 submit 多了执行容量检查，随后把实际投递交给 Codex。

调用图：调用 1 个内部函数（submit_user_input_with_client_user_message_id）。

async fn set_thread_memory_mode(&self, mode: ThreadMemoryMode) -> anyhow::Result<()>

作用：保存这个线程以后是否允许生成记忆。记忆模式会影响系统以后能不能从这条线程里提炼长期信息。

数据流：进去的是 ThreadMemoryMode；函数交给 Codex.set_thread_memory_mode；出来是成功或错误，底层持久状态可能被更新。

调用关系：它是线程记忆资格设置的公开入口，具体保存逻辑在 Codex 里。

调用图：调用 1 个内部函数（set_thread_memory_mode）。

async fn steer_input(
        &self,
        input: Vec<UserInput>,
        additional_context: BTreeMap<String, AdditionalContextEntry>,
        expected_turn_id: Option<&str>,
        client_user_me

作用：把额外用户输入送进正在进行的对话轮次，用来“转向”当前回复。比如模型还在工作时，用户补充一句要求。

数据流：进去的是用户输入列表、额外上下文、期望的 turn 编号、客户端消息编号和元数据；函数交给 Codex.steer_input；出来是成功编号或 SteerInputError，当前活跃轮次可能收到新信息。

调用关系：steer_user_input 会调用它；它本身不做转向细节，而是把信息交给底层 Codex 判断能不能注入当前轮次。

调用图：调用 1 个内部函数（steer_input）；被 1 处调用（steer_user_input）。

async fn inject_if_running(
        &self,
        items: Vec<ResponseItem>,
    ) -> Result<(), Vec<ResponseItem>>

作用：如果当前线程正有一轮模型在跑，就把一些模型可见内容塞进去；如果没有在跑，就把原内容退回。

数据流：进去的是 ResponseItem 列表；函数调用 session.inject_if_running；成功时这些内容被注入当前轮次，失败时原列表作为 Err 返回且不被改动。

调用关系：这是只拿到 CodexThread 的调用方通向 Session 注入能力的桥，常用于扩展或后台事件想补充当前模型上下文。

async fn try_start_turn_if_idle(
        &self,
        items: Vec<ResponseItem>,
    ) -> Result<(), TryStartTurnIfIdleError>

作用：只在线程真正空闲、没有用户任务排队、也不是计划模式时，才启动一个自动模型轮次。它防止插件在不合适的时候抢先开新回复。

数据流：进去的是模型可见的 ResponseItem 列表；函数交给 session.try_start_turn_if_idle 做空闲检查和启动；成功时新轮次开始，失败时返回带原因和原输入的 TryStartTurnIfIdleError。

调用关系：这是扩展在 on_thread_idle 里想自动发起工作时必须走的入口，保证用户触发的任务永远优先。

async fn set_app_server_client_info(
        &self,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<String>,
        mcp_elicitations_auto_deny: bool,
    ) -

作用：记录连接到这个线程的 app-server 客户端信息，以及 MCP 询问是否自动拒绝。这样底层可以按客户端能力和策略运行。

数据流：进去的是客户端名称、版本和是否自动拒绝 MCP elicitation 的开关；函数交给 Codex.set_app_server_client_info；出来是约束检查结果，底层客户端状态可能更新。

调用关系：同名上层接口会调用它；它是 app-server 把客户端身份和行为偏好传进线程的入口。

调用图：调用 1 个内部函数（set_app_server_client_info）；被 2 处调用（set_app_server_client_info, set_app_server_client_info）。

async fn preview_thread_settings_overrides(
        &self,
        overrides: CodexThreadSettingsOverrides,
    ) -> ConstraintResult<ThreadConfigSnapshot>

作用：预览一组线程设置改动会变成什么样，但不真正提交。像改配置前先点“预览”，看是否符合限制。

数据流：进去的是 CodexThreadSettingsOverrides；函数先调用 thread_settings_update 把覆盖项整理成 SessionSettingsUpdate，再交给 session.preview_settings；出来是配置快照或约束错误，线程实际设置不被改变。

调用关系：build_thread_settings_overrides 会用它检查用户想改的线程设置；它把整理覆盖项的工作交给 thread_settings_update。

调用图：调用 1 个内部函数（thread_settings_update）；被 1 处调用（build_thread_settings_overrides）。

async fn thread_settings_update(
        &self,
        overrides: CodexThreadSettingsOverrides,
    ) -> SessionSettingsUpdate

作用：把外部传来的零散设置覆盖项，整理成底层 Session 能理解的一包设置更新。

数据流：进去的是 CodexThreadSettingsOverrides；函数拆开每个可选字段，如果没明确给 collaboration_mode，就从当前会话模式结合模型和推理力度变化算一个；出来是 SessionSettingsUpdate。

调用关系：它只被 preview_thread_settings_overrides 调用，是预览配置前的格式转换和默认值补齐步骤。

调用图：被 1 处调用（preview_thread_settings_overrides）；外部调用 1 个（default）。

async fn submit_with_id(&self, sub: Submission) -> CodexResult<()>

作用：提交一个已经带有编号的 Submission。注释说明这是临时入口，未来打算移除。

数据流：进去的是 Submission；函数交给 Codex.submit_with_id；出来是成功或 Codex 错误，底层队列按这个既有编号接收提交。

调用关系：它是少数需要自带提交编号的内部路径使用的桥，实际投递仍由 Codex 完成。

调用图：调用 1 个内部函数（submit_with_id）。

async fn next_event(&self) -> CodexResult<Event>

作用：读取线程产生的下一个事件。事件可以是模型输出、状态变化、工具结果等，是外部观察线程进展的主要方式。

数据流：进去的是线程对象；函数等待 Codex.next_event；出来是一个 Event 或错误，底层事件流被向前消费一步。

调用关系：提交线程设置、等待事件、等待 MCP 服务和运行一轮等流程都会调用它，用来从线程里取下一条消息。

调用图：调用 1 个内部函数（next_event）；被 4 处调用（submit_thread_settings, wait_for_event_with_timeout, wait_for_mcp_server, run_turn）。

async fn agent_status(&self) -> AgentStatus

作用：查询当前代理状态，比如是否空闲、忙碌或处于其他状态。外部循环用它判断接下来该不该继续等或提交任务。

数据流：进去的是线程对象；函数调用 Codex.agent_status；出来是 AgentStatus，不改变线程。

调用关系：loop_agent 会调用它观察代理状态；真正状态来源在底层 Codex。

调用图：调用 1 个内部函数（agent_status）；被 1 处调用（loop_agent）。

async fn list_background_terminals(&self) -> Vec<BackgroundTerminalInfo>

作用：列出线程里还在后台运行的终端进程。这样前端或控制层能看到哪些命令还没结束。

数据流：进去的是线程对象；函数读取 session.list_background_terminals；出来是 BackgroundTerminalInfo 列表，包含条目编号、进程编号、命令和目录。

调用关系：它是查看后台终端的线程级入口，实际进程清单由 Session 维护。

async fn terminate_background_terminal(&self, process_id: i32) -> bool

作用：按进程编号终止一个后台终端。用于用户或系统想停掉还在跑的命令。

数据流：进去的是 process_id；函数交给 session.terminate_background_terminal；出来是布尔值，表示是否找到并尝试终止了对应进程。

调用关系：它和 list_background_terminals 配套，一个负责看，一个负责停；具体杀进程逻辑在 Session 内部。

fn subscribe_status(&self) -> watch::Receiver<AgentStatus>

作用：订阅代理状态变化。订阅就像打开一个状态通知频道，以后状态变了可以收到更新。

数据流：进去的是线程对象；函数克隆 agent_status 的 watch 接收器；出来是 watch::Receiver，调用方可继续监听状态变化。

调用关系：它给内部需要实时观察状态的组件使用，不需要反复主动调用 agent_status。

async fn token_usage_info(&self) -> Option<TokenUsageInfo>

作用：读取这个线程当前缓存的完整 token 用量。token 可以粗略理解为模型读写文字时计费和限额用的小单位。

数据流：进去的是线程对象；函数读取 session.token_usage_info；出来是可选 TokenUsageInfo，不修改状态。

调用关系：send_thread_token_usage_update_to_connection 会调用它，把恢复或分叉后的完整用量发给连接方，避免只发总量而漏掉上一轮明细。

调用图：被 1 处调用（send_thread_token_usage_update_to_connection）。

async fn inject_user_message_without_turn(&self, message: String)

作用：记录一条用户身份的前缀消息，但不开始新的用户回合。适合补充上下文，而不是让系统以为用户又发起了一轮对话。

数据流：进去的是一段文本；函数把它包装成 role 为 user 的 ResponseItem::Message，再调用 session.inject_no_new_turn；出来没有返回值，线程记录里多了这条消息但没有新 turn 边界。

调用关系：它是内部辅助入口，用于需要补写用户消息但不能触发新轮次的场景。

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

async fn inject_response_items(&self, items: Vec<ResponseItem>) -> CodexResult<()>

作用：把原始 Responses API 项目写进线程记录，但不启动新轮次。它用于导入或补录模型可见内容。

数据流：进去的是 ResponseItem 列表；如果为空，直接返回 InvalidRequest；否则创建默认 turn 上下文，必要时记录并设置参考上下文项，再注入这些项目并刷新 rollout；出来是成功或错误，记录文件可能被写入。

调用关系：它比普通注入更完整，会确保上下文和持久记录同步；具体注入和刷盘由 Session 完成。

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

fn rollout_path(&self) -> Option<PathBuf>

作用：返回这个线程 rollout 记录文件的位置。调用方可以据此找到会话记录存在哪里。

数据流：进去的是线程对象；函数克隆保存的可选 PathBuf；出来是路径副本或 None，不改状态。

调用关系：build_thread_from_loaded_snapshot 会用它在从快照重建线程视图时拿到记录路径。

调用图：被 1 处调用（build_thread_from_loaded_snapshot）。

fn session_configured(&self) -> SessionConfiguredEvent

作用：返回线程创建时的会话配置事件副本。这个事件包含线程编号等基础配置信息。

数据流：进去的是线程对象；函数克隆 session_configured；出来是 SessionConfiguredEvent 副本，不影响原值。

调用关系：加载恢复来源和从快照构建线程时会调用它，用来取得线程的固定配置事实。

调用图：被 2 处调用（load_thread_from_resume_source_or_send_internal, build_thread_from_loaded_snapshot）；外部调用 1 个（clone）。

fn is_running(&self) -> bool

作用：判断这个线程底层的提交通道是否还开着。通道关了，通常表示线程不能再正常接收新操作。

数据流：进去的是线程对象；函数检查 codex.tx_sub 是否关闭；出来是 true 或 false，不改任何状态。

调用关系：它是一个轻量健康检查，供需要避免往已关闭线程投递工作的内部代码使用。

async fn guardian_trunk_rollout_path(&self) -> Option<PathBuf>

作用：读取 guardian review 相关主干 rollout 路径。可以理解为审查流程对应的原始记录位置。

数据流：进去的是线程对象；函数询问 session.guardian_review_session.trunk_rollout_path；出来是可选路径。

调用关系：它把审查会话里的路径信息通过 CodexThread 暴露出来，避免外部直接进入 guardian_review_session。

async fn load_history(
        &self,
        include_archived: bool,
    ) -> ThreadStoreResult<StoredThreadHistory>

作用：从线程存储里读取历史记录。include_archived 决定是否连已归档内容一起读。

数据流：进去的是 include_archived；函数先从 session 取得可持久化的 live_thread，失败就转成 ThreadStoreError::Internal，再调用 load_history；出来是 StoredThreadHistory 或存储错误。

调用关系：apply_thread_read_store_fields 会调用它补齐线程历史字段；它负责把当前运行线程连接到持久化存储。

调用图：被 1 处调用（apply_thread_read_store_fields）。

async fn read_thread(
        &self,
        include_archived: bool,
        include_history: bool,
    ) -> ThreadStoreResult<StoredThread>

作用：读取线程的存储版整体信息，可以选择是否包含归档内容和历史。用于把运行中的线程变成可展示或可返回的数据。

数据流：进去的是 include_archived 和 include_history 两个开关；函数先拿 live_thread，失败转内部存储错误，再调用 read_thread；出来是 StoredThread 或错误。

调用关系：它是读取线程存储视图的入口，底层具体怎么读由 live_thread 对象完成。

async fn update_thread_metadata(
        &self,
        patch: ThreadMetadataPatch,
        include_archived: bool,
    ) -> ThreadStoreResult<StoredThread>

作用：更新线程的元数据，比如标题、标记或其他非正文信息。patch 表示只改其中一部分。

数据流：进去的是 ThreadMetadataPatch 和 include_archived；函数先取得 live_thread，失败转成存储内部错误，再调用 update_metadata；出来是更新后的 StoredThread 或错误。

调用关系：它把外部的元数据修改请求接到线程存储层，保证修改的是当前这条 live thread。

fn state_db(&self) -> Option<StateDbHandle>

作用：返回这个线程关联的状态数据库句柄，如果有的话。状态数据库用于保存恢复目标、线程关系等运行状态。

数据流：进去的是线程对象；函数调用 Codex.state_db；出来是可选 StateDbHandle，不修改状态。

调用关系：pending_resume_goal_state 和 persist_thread_spawn_edge_for_source 会用它读取或记录恢复、派生线程相关状态。

调用图：调用 1 个内部函数（state_db）；被 2 处调用（pending_resume_goal_state, persist_thread_spawn_edge_for_source）。

async fn config_snapshot(&self) -> ThreadConfigSnapshot

作用：获取当前线程配置的快照。快照就是把当前设置拍一张照片，之后可以用来展示、比较或生成覆盖项。

数据流：进去的是线程对象；函数调用 Codex.thread_config_snapshot；出来是 ThreadConfigSnapshot。

调用关系：加载实时线程视图、恢复线程、构造环境覆盖和构造设置覆盖时都会调用它，是很多配置相关流程的基础。

调用图：调用 1 个内部函数（thread_config_snapshot）；被 4 处调用（load_live_thread_view, load_thread_from_resume_source_or_send_internal, build_environment_override, build_thread_settings_overrides）。

async fn instruction_sources(&self) -> Vec<AbsolutePathBuf>

作用：返回这条线程加载模型指令时用到的文件路径。这样可以解释模型行为是受哪些说明文件影响的。

数据流：进去的是线程对象；函数调用 Codex.instruction_sources；出来是路径列表。

调用关系：它给需要展示或审计指令来源的调用方使用，底层来源信息由 Codex 保存。

调用图：调用 1 个内部函数（instruction_sources）。

async fn config(&self) -> Arc<crate::config::Config>

作用：读取当前线程使用的完整配置对象。返回的是共享引用计数指针 Arc，可以多人安全持有同一份配置。

数据流：进去的是线程对象；函数等待 session.get_config；出来是 Arc<Config>，不直接修改配置。

调用关系：build_refresh_config 会调用它，以当前配置为基础构造新的运行时配置。

调用图：被 1 处调用（build_refresh_config）。

async fn runtime_mcp_config(&self, config: &crate::config::Config) -> codex_mcp::McpConfig

作用：根据当前线程的扩展数据，解析出运行时 MCP 配置。MCP 是让模型访问外部工具和资源的一套接口。

数据流：进去的是一个 Config 引用；函数交给 session.runtime_mcp_config；出来是 McpConfig，其中可能包含线程级扩展后的工具配置。

调用关系：build_refresh_config 会调用它，确保刷新配置时 MCP 运行设置也按当前线程数据重新计算。

调用图：被 1 处调用（build_refresh_config）。

fn multi_agent_version(&self) -> Option<MultiAgentVersion>

作用：返回当前线程使用的多代理协议版本，如果有的话。多代理指多个代理协同工作的模式。

数据流：进去的是线程对象；函数读取 session.multi_agent_version；出来是可选 MultiAgentVersion。

调用关系：ensure_direct_input_allowed 和 is_resident_candidate 会用它判断当前线程是否允许某些输入方式或是否适合作为常驻线程。

调用图：被 2 处调用（ensure_direct_input_allowed, is_resident_candidate）。

async fn refresh_runtime_config(&self, next_config: crate::config::Config)

作用：用调用方给的新配置刷新线程的运行时用户配置层。线程自己的层级设置和会话启动时固定的设置不会被重置。

数据流：进去的是新的 Config；函数交给 session.refresh_runtime_config；出来没有返回值，底层运行时配置状态会更新。

调用关系：它是配置热刷新入口，适合外部配置变化后让已存在的线程跟上新配置。

async fn environment_selections(&self) -> Vec<TurnEnvironmentSelection>

作用：读取线程当前的环境选择列表。调用方可以知道后续执行可能选哪些环境。

数据流：进去的是线程对象；函数调用 Codex.thread_environment_selections；出来是 TurnEnvironmentSelection 列表。

调用关系：它是线程级环境读取入口，和 ThreadConfigSnapshot::environment_selections 类似，但直接从活线程读取最新值。

调用图：调用 1 个内部函数（thread_environment_selections）。

async fn read_mcp_resource(
        &self,
        server: &str,
        uri: &str,
    ) -> anyhow::Result<serde_json::Value>

作用：从指定 MCP 服务器读取一个资源，并把结果转成通用 JSON。JSON 是常见的数据格式，方便前端或接口直接传输。

数据流：进去的是服务器名和资源 uri；函数创建 ReadResourceRequestParams，调用 session.read_resource，再用 serde_json 转成 Value；出来是 JSON 值或错误。

调用关系：它是线程对外读取 MCP 资源的桥，具体资源访问由 Session 和对应 MCP 服务器完成。

调用图：外部调用 2 个（new, to_value）。

async fn call_mcp_tool(
        &self,
        server: &str,
        tool: &str,
        arguments: Option<serde_json::Value>,
        meta: Option<serde_json::Value>,
    ) -> anyhow::Result<CallTool

作用：调用指定 MCP 服务器上的某个工具。工具可以是搜索、读文件、查数据库等外部能力。

数据流：进去的是服务器名、工具名、可选参数和可选元信息；函数交给 session.call_tool；出来是 CallToolResult 或错误，外部工具可能被实际执行。

调用关系：它是线程层面的 MCP 工具调用入口，负责把调用请求转给当前会话的 MCP 运行环境。

fn enabled(&self, feature: Feature) -> bool

作用：检查某个功能开关是否启用。功能开关用于控制新能力是否对当前线程开放。

数据流：进去的是 Feature；函数调用 Codex.enabled；出来是 true 或 false，不修改状态。

调用关系：它让上层代码在走某条新流程前先问线程是否支持该功能，判断逻辑由 Codex 提供。

调用图：调用 1 个内部函数（enabled）。

async fn increment_out_of_band_elicitation_count(&self) -> CodexResult<u64>

作用：把“带外询问”的计数加一，并在从 0 变成 1 时暂停相关会话状态。带外询问可以理解为不在普通对话轮次里的额外提问。

数据流：进去的是线程对象；函数先锁住计数器，防止两个异步任务同时改同一个数字；如果加一溢出就返回 Fatal 错误；成功后返回新计数，若原来是 0 还会把会话的带外询问暂停状态设为 true。

调用关系：它和 decrement_out_of_band_elicitation_count 配套使用，保证只要还有带外询问没结束，线程就保持暂停状态。

async fn decrement_out_of_band_elicitation_count(&self) -> CodexResult<u64>

作用：把“带外询问”的计数减一，并在减到 0 时解除暂停。它防止询问结束后线程一直停着不动。

数据流：进去的是线程对象；函数锁住计数器，如果已经是 0 就返回 InvalidRequest；否则减一并返回新计数，若现在变成 0，就把会话的带外询问暂停状态设为 false。

调用关系：它必须和 increment_out_of_band_elicitation_count 成对出现，是带外询问生命周期的收尾动作。

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

fn to_error_event(&self) -> ErrorEvent

作用：把“追加引导输入失败”的内部错误，翻译成外部客户端能看懂的错误事件。这样调用方不会只看到一个程序内部枚举，而是能得到明确的人话提示。

数据流：进去的是一个 SteerInputError，例如没有活跃回合、回合编号不匹配、当前回合不能被引导、输入为空；函数按类型生成 ErrorEvent，里面放错误消息和错误分类；出来的是可发送给客户端的错误事件，不改动其他状态。

调用关系：它位于 steer input 的失败出口附近。当会话拒绝新的引导输入时，外层可以用它把失败原因包装成协议事件；内部只用格式化文本，不再把活儿交给复杂流程。

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

fn resolve_multi_agent_version(
    conversation_history: &InitialHistory,
    inherited_multi_agent_version: Option<MultiAgentVersion>,
) -> Option<MultiAgentVersion>

作用：决定这个线程要使用哪个多代理版本。多代理就是一个主代理可以派生子代理协作；版本决定它们能用的沟通方式。

数据流：进去的是初始对话历史和从父线程继承来的版本；函数先尊重“禁用”设置，再看历史里是否记录过版本，再看继承值，最后对老的恢复/分叉线程默认给 V1；出来的是一个可选版本。

调用关系：它在 Codex::spawn_internal 创建会话时被调用，也用于计算派生线程的初始版本。它替启动流程解决兼容老线程的问题。

调用图：调用 1 个内部函数（get_multi_agent_version）；被 2 处调用（spawn_internal, initial_multi_agent_version_for_spawn）。

async fn spawn(args: CodexSpawnArgs) -> CodexResult<CodexSpawnOk>

作用：这是外部启动一个 Codex 线程的入口。它先处理追踪信息，再交给真正的内部启动流程。

数据流：进去的是 CodexSpawnArgs，里面有配置、历史、各种管理器和可选父追踪；函数检查父追踪是否合法，创建一个 tracing span（一次操作的追踪标签），把父子追踪接起来；出来的是 CodexSpawnOk，里面有可用的 Codex 对象和线程 id。

调用关系：交互运行、线程派生和测试都会调用它。它不亲自组装会话细节，而是把整理后的参数交给 Codex::spawn_internal，并把整个启动过程包进可观测的追踪里。

调用图：被 3 处调用（run_codex_thread_interactive, guardian_subagent_does_not_inherit_parent_exec_policy_rules, spawn_thread_with_source）；外部调用 5 个（spawn_internal, context_from_w3c_trace_context, set_parent_from_w3c_trace_context, info_span!, warn!）。

async fn spawn_internal(args: CodexSpawnArgs) -> CodexResult<CodexSpawnOk>

作用：真正把一个 Codex 会话搭起来。它像开店前准备：摆好收银台、员工、规则、库存、监控和后门通道，然后启动后台工作循环。

数据流：进去的是完整启动参数；函数建立提交通道和事件通道，加载或继承执行策略，选择模型和基础提示词，决定多代理版本，组装 SessionConfiguration，创建 Session，再启动 submission_loop 后台任务；出来的是包含 Codex 句柄和 thread_id 的启动结果。

调用关系：Codex::spawn 调它。它会调用 resolve_multi_agent_version、get_service_tier、session_permission_profile_state_from_config、Session::new 和 submission_loop，是整个文件里启动阶段的核心编排点。

调用图：调用 9 个内部函数（default, load, get_service_tier, submission_loop, resolve_multi_agent_version, new, session_loop_termination_from_handle, session_permission_profile_state_from_config, new）；外部调用 11 个（clone, new, pin, bounded, unbounded, is_guardian_reviewer_source, info_span!, matches!, from_config, spawn (+1 more)）。

async fn submit(&self, op: Op) -> CodexResult<String>

作用：给会话提交一个操作，比如用户输入、批准命令或关闭。它是最常用的简化入口。

数据流：进去的是 Op 操作；函数不给它附加外部追踪，直接转给 submit_with_trace；出来的是这次提交的唯一 id。

调用关系：很多处理函数和关闭流程都会用它。它把普通提交统一导向 Codex::submit_with_trace。

调用图：调用 1 个内部函数（submit_with_trace）；被 8 处调用（handle_exec_approval, handle_patch_approval, handle_request_permissions, handle_request_user_input, shutdown_delegate, submit, interrupt_and_drain_turn, shutdown_and_wait）。

async fn submit_with_trace(
        &self,
        op: Op,
        trace: Option<W3cTraceContext>,
    ) -> CodexResult<String>

作用：提交一个操作，同时可以带上调用链追踪信息。追踪信息方便之后排查“这件事从哪里发起”。

数据流：进去的是 Op 和可选 W3C trace context（跨系统追踪用的一串标识）；函数生成 UUID 作为提交 id，打包成 Submission；出来的是 id，并把提交送入内部队列。

调用关系：Codex::submit 会调用它；它再把实际发送交给 Codex::submit_with_id。

调用图：调用 1 个内部函数（submit_with_id）；被 2 处调用（submit_with_trace, submit）；外部调用 1 个（now_v7）。

async fn submit_user_input_with_client_user_message_id(
        &self,
        op: Op,
        trace: Option<W3cTraceContext>,
        client_user_message_id: Option<String>,
    ) -> CodexResult<Stri

作用：专门提交用户输入，并保留客户端自己的消息 id。这样外部界面可以把自己发出的消息和 Codex 内部处理结果对上号。

数据流：进去的是用户输入类 Op、追踪信息和客户端消息 id；函数确认操作确实是用户输入，生成内部提交 id，组成 Submission；出来的是内部 id，并把提交放进队列。

调用关系：它用于需要消息对账的用户输入路径。真正发送仍交给 Codex::submit_with_id。

调用图：调用 1 个内部函数（submit_with_id）；被 1 处调用（submit_user_input_with_client_user_message_id）；外部调用 2 个（now_v7, debug_assert!）。

async fn submit_with_id(&self, mut sub: Submission) -> CodexResult<()>

作用：把已经打包好的提交真正塞进会话的输入队列。它是提交链路的最后一站。

数据流：进去的是 Submission；如果里面没有追踪信息，就从当前执行环境补一份；然后发送到 tx_sub 通道；成功没有返回内容，失败说明内部代理已经死了。

调用关系：submit_with_trace 和 submit_user_input_with_client_user_message_id 都依赖它。后台 submission_loop 会从这个通道取活儿干。

调用图：被 3 处调用（submit_with_id, submit_user_input_with_client_user_message_id, submit_with_trace）；外部调用 2 个（send, current_span_w3c_trace_context）。

async fn set_thread_memory_mode(
        &self,
        mode: codex_protocol::protocol::ThreadMemoryMode,
    ) -> anyhow::Result<()>

作用：修改当前线程的记忆模式，并把这个选择保存下来。记忆模式决定线程以后如何保留或使用记忆。

数据流：进去的是 ThreadMemoryMode；函数把模式和当前 session 交给持久化处理函数；出来是成功或失败结果，成功时线程记录被更新。

调用关系：外部设置线程记忆时调用它。它不自己写存储，而是交给 handlers::persist_thread_memory_mode_update。

调用图：调用 1 个内部函数（persist_thread_memory_mode_update）；被 1 处调用（set_thread_memory_mode）。

async fn shutdown_and_wait(&self) -> CodexResult<()>

作用：请求会话关闭，并等后台循环真的停下来。它避免外部以为关了、内部其实还在跑。

数据流：进去没有额外数据；函数提交 Op::Shutdown，如果内部已经死了也当作可接受，然后等待 session_loop_termination；出来是关闭成功或其他错误。

调用关系：shutdown、线程派生收尾等流程会用它。它通过 Codex::submit 发关机命令，再等待 spawn_internal 创建的后台任务结束。

调用图：调用 1 个内部函数（submit）；被 3 处调用（shutdown_and_wait, shutdown, finalize_thread_spawn）；外部调用 1 个（clone）。

async fn next_event(&self) -> CodexResult<Event>

作用：从会话里取下一条事件。外部界面靠它知道模型说了什么、工具执行到哪了、有没有错误。

数据流：进去没有参数；函数从 rx_event 事件通道等待一条 Event；出来是事件，若通道关闭则报内部代理死亡。

调用关系：事件消费循环、关闭代理和派生线程收尾会调用它。事件由 Session::send_event_raw 或 deliver_event_raw 写入通道。

调用图：调用 1 个内部函数（recv）；被 4 处调用（shutdown_delegate, next_event, interrupt_and_drain_turn, finalize_thread_spawn）。

async fn steer_input(
        &self,
        input: Vec<UserInput>,
        additional_context: BTreeMap<String, AdditionalContextEntry>,
        expected_turn_id: Option<&str>,
        client_user_me

作用：在一个正在进行的回合里追加“引导输入”。这像用户在助手还没结束时补充一句“等等，按这个方向来”。

数据流：进去的是用户输入、额外上下文、期望回合 id、客户端消息 id 和元数据；函数原样转给 Session::steer_input；出来是提交 id，或 SteerInputError。

调用关系：外部 steer_input 接口会用它。它只是 Codex 外壳到 Session 内核的转接层。

调用图：被 1 处调用（steer_input）。

async fn set_app_server_client_info(
        &self,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<String>,
        mcp_elicitations_auto_deny: bool,
    ) -

作用：记录连接到本线程的应用服务器客户端信息，并设置 MCP 询问是否自动拒绝。MCP 可理解为外部工具/服务接入协议。

数据流：进去的是客户端名称、版本和是否自动拒绝 MCP elicitation（外部服务向用户追问）；函数更新会话设置，再调整 MCP 连接管理器；出来是约束检查结果。

调用关系：上层应用服务器接入线程后会调用它。它内部使用 Session::update_settings，并直接通知 MCP 管理器。

调用图：被 1 处调用（set_app_server_client_info）；外部调用 1 个（default）。

async fn agent_status(&self) -> AgentStatus

作用：读取当前代理的最新状态，比如初始化中、运行中、完成或出错。

数据流：进去无参数；函数从 watch 通道里借出当前值并克隆；出来是 AgentStatus，不改变状态。

调用关系：外部状态查询接口会调用它。状态由事件投递流程和子代理完成流程更新。

调用图：被 1 处调用（agent_status）；外部调用 1 个（borrow）。

async fn thread_config_snapshot(&self) -> ThreadConfigSnapshot

作用：拿到当前线程配置的一份快照。快照适合给 UI 展示或给外部检查，而不是直接修改内部配置。

数据流：进去无参数；函数锁住 session 状态，读取 session_configuration 并生成 ThreadConfigSnapshot；出来是快照。

调用关系：config_snapshot 接口会调用它。它只读 Session 状态，不触发配置变更。

调用图：被 1 处调用（config_snapshot）。

async fn instruction_sources(&self) -> Vec<AbsolutePathBuf>

作用：列出本线程加载过哪些指令文件来源。这样用户能知道助手遵循的额外说明来自哪里。

数据流：进去无参数；函数读取 loaded_agents_md，如果有就取出 sources；出来是路径列表，没有则为空列表。

调用关系：instruction_sources 查询接口会用它。它从 Session 配置状态中取资料。

调用图：被 1 处调用（instruction_sources）。

async fn thread_environment_selections(&self) -> Vec<TurnEnvironmentSelection>

作用：查询线程当前选了哪些运行环境。运行环境可以理解为代码在哪个工作区或沙箱里执行。

数据流：进去无参数；函数读取 session_configuration 的环境选择并复制成列表；出来是 TurnEnvironmentSelection 列表。

调用关系：environment_selections 接口会调用它。它只读当前 Session 配置。

调用图：被 1 处调用（environment_selections）。

fn state_db(&self) -> Option<state_db::StateDbHandle>

作用：取得会话状态数据库的句柄，如果这个线程启用了状态数据库的话。句柄就是后续读写数据库用的入口。

数据流：进去无参数；函数转问 Session::state_db；出来是可选 StateDbHandle。

调用关系：state_db 查询接口会调用它。它把 Codex 外壳请求转给 Session。

调用图：被 1 处调用（state_db）。

fn enabled(&self, feature: Feature) -> bool

作用：判断某个功能开关是否在当前线程启用。功能开关用于灰度或实验功能。

数据流：进去的是 Feature；函数询问 session；出来是 true 或 false。

调用关系：enabled 查询接口会调用它。具体判断逻辑在 Session 的 feature 状态里。

调用图：被 1 处调用（enabled）。

fn get_service_tier(
    configured_service_tier: Option<String>,
    fast_mode_enabled: bool,
    model_info: &ModelInfo,
) -> Option<String>

作用：决定是否把服务档位传给模型请求。服务档位可以理解为请求模型时选择的服务等级。

数据流：进去的是配置里的档位、快速模式是否开启、模型信息；如果没开快速模式就返回空，否则只保留默认档位或模型支持的档位；出来是可选字符串。

调用关系：Codex::spawn_internal 在组装 SessionConfiguration 时调用它，避免把模型不支持的档位发出去。

调用图：被 1 处调用（spawn_internal）。

fn session_permission_profile_state_from_config(
    config: &Config,
) -> CodexResult<PermissionProfileState>

作用：从配置里取出线程启动时的权限档案状态。权限档案决定哪些操作需要批准、沙箱如何限制等。

数据流：进去的是 Config；函数读取 config.permissions.permission_profile_state 并克隆；出来是 PermissionProfileState。

调用关系：Codex::spawn_internal 用它把配置中的权限信息放进 SessionConfiguration。

调用图：被 1 处调用（spawn_internal）。

fn completed_session_loop_termination() -> SessionLoopTermination

作用：制造一个“已经结束”的会话循环结束信号。主要用于测试或不需要真实后台任务的场景。

数据流：进去无参数；函数创建一个立即完成的 future，并包装成可共享对象；出来是 SessionLoopTermination。

调用关系：测试 review session 会用它。它不等待真实任务，只提供符合接口的假结束句柄。

调用图：被 1 处调用（test_review_session）；外部调用 1 个（ready）。

fn session_loop_termination_from_handle(
    handle: JoinHandle<()>,
) -> SessionLoopTermination

作用：把后台任务句柄包装成一个可等待的结束信号。外部只关心“什么时候停”，不用直接碰 tokio 任务句柄。

数据流：进去的是 JoinHandle；函数创建异步块等待这个任务结束，并转成共享 future；出来是 SessionLoopTermination。

调用关系：Codex::spawn_internal 启动 submission_loop 后调用它；Codex::shutdown_and_wait 后面会等待这个信号。

调用图：被 1 处调用（spawn_internal）。

async fn thread_title_from_thread_store(
    live_thread: Option<&LiveThread>,
    thread_store: &Arc<dyn ThreadStore>,
    conversation_id: ThreadId,
) -> Option<String>

作用：从线程存储里读取一个适合展示的线程标题。它会避免把空标题或和预览文字重复的标题拿出来。

数据流：进去的是可选 live_thread、线程存储和 conversation_id；函数优先从 live_thread 读，否则从 ThreadStore 读；取 name，去掉空白，并确认它不等于 preview；出来是可选标题。

调用关系：它是线程展示信息的辅助函数。本段没有显示调用方，但它连接了实时线程对象和持久线程仓库。

async fn app_server_client_metadata(&self) -> AppServerClientMetadata

作用：读取当前应用服务器客户端的名称和版本。用于事件、请求或诊断时标明是谁在连接这个会话。

数据流：进去无参数；函数锁住状态，复制 app_server_client_name 和 app_server_client_version；出来是 AppServerClientMetadata。

调用关系：它给需要客户端元数据的内部流程使用，数据来源通常由 Codex::set_app_server_client_info 写入。

fn managed_network_proxy_active_for_permission_profile(
        permission_profile: &PermissionProfile,
    ) -> bool

作用：判断某个权限档案下是否应该启用托管网络代理。网络代理像一道门卫，能拦截或允许联网请求。

数据流：进去的是 PermissionProfile；函数只要看到不是 Disabled 就返回 true；出来是布尔值。

调用关系：它是网络代理相关判断的基础小工具，供会话启动或权限变化时使用。

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

fn build_model_client_beta_features_header(config: &Config) -> Option<String>

作用：把启用的实验功能整理成发给模型客户端的请求头。请求头可以理解为随请求附带的一行说明。

数据流：进去的是 Config；函数遍历功能表，挑出需要告诉模型客户端且已启用的功能 key，用逗号拼起来；如果没有则返回 None，否则返回字符串。

调用关系：模型客户端创建请求时会用这种信息。它把本地功能开关转换成模型服务能识别的标记。

async fn start_managed_network_proxy(
        spec: &crate::config::NetworkProxySpec,
        exec_policy: &codex_execpolicy::Policy,
        permission_profile: &PermissionProfile,
        network_po

作用：启动托管网络代理，并把运行时地址记录下来。它让会话里的网络请求能经过统一的允许/拒绝规则。

数据流：进去的是代理配置、执行策略、权限档案、可选决策器和观察器、需求开关及审计信息；函数先把执行策略中的网络规则合并进代理配置，再启动代理，读取 HTTP 和 SOCKS 地址；出来是已启动代理和会话可用的代理运行信息。

调用关系：权限变化刷新流程会调用它。它把 NetworkProxySpec 的规则加工后交给 start_proxy。

调用图：调用 2 个内部函数（start_proxy, with_exec_policy_network_rules）。

async fn refresh_managed_network_proxy_for_current_permission_profile(&self)

作用：当权限档案变化时，刷新或启动网络代理。这样新权限会立刻影响后续联网，而不是等下次重启。

数据流：进去无参数；函数拿刷新锁，读取当前配置和权限，重算代理规则，合并执行策略网络规则；如果代理已存在就在线更新，否则启动新代理并保存；出来无显式结果，失败只记警告。

调用关系：Session::update_settings 发现权限档案变化后调用它。它会调用 Session::start_managed_network_proxy，并更新 services.network_proxy。

调用图：被 1 处调用（update_settings）；外部调用 4 个（new, start_managed_network_proxy, error!, warn!）。

async fn codex_home(&self) -> AbsolutePathBuf

作用：读取当前会话的 Codex 主目录。这个目录通常放配置、策略和持久化资料。

数据流：进去无参数；函数锁住状态，克隆 codex_home 路径；出来是 AbsolutePathBuf。

调用关系：需要找本地配置或写入策略文件的流程会用它。

fn subscribe_out_of_band_elicitation_pause_state(&self) -> watch::Receiver<bool>

作用：订阅“带外询问是否暂停”的状态。带外询问指不是普通对话流里的额外追问。

数据流：进去无参数；函数从 watch 通道创建一个接收者；出来是能持续收到 bool 状态变化的 Receiver。

调用关系：需要监听暂停/恢复的组件会调用它。状态由 set_out_of_band_elicitation_pause_state 更新。

fn set_out_of_band_elicitation_pause_state(&self, paused: bool)

作用：设置带外询问是否暂停，并通知所有订阅者。

数据流：进去的是 paused 布尔值；函数替换 watch 通道里的当前值；出来无返回，订阅者会收到新状态。

调用关系：控制带外询问流程的地方会调用它；订阅端通过 subscribe_out_of_band_elicitation_pause_state 得到变化。

fn get_tx_event(&self) -> Sender<Event>

作用：拿到事件发送通道的副本。这样内部其他组件也能向外部事件流发消息。

数据流：进去无参数；函数克隆 tx_event；出来是 Sender<Event>。

调用关系：需要直接发送事件的内部模块会用它。正常事件路径更多通过 send_event 或 send_event_raw。

fn state_db(&self) -> Option<state_db::StateDbHandle>

作用：返回当前会话的状态数据库句柄，如果有启用。数据库句柄是后续读写状态的入口。

数据流：进去无参数；函数克隆 services.state_db；出来是可选 StateDbHandle。

调用关系：Codex::state_db 会转调它，外部查询可以从 Codex 层拿到这个句柄。

fn live_thread_for_persistence(
        &self,
        operation: &str,
    ) -> anyhow::Result<&LiveThread>

作用：取得用于持久化的 live thread；如果持久化没启用，就给出明确错误。live thread 可理解为正在写入的对话录像对象。

数据流：进去的是操作名称；函数调用 live_thread，如果没有就生成“无法执行该操作”的错误；出来是 LiveThread 引用或错误。

调用关系：需要强制写入线程持久化的流程会用它。它依赖 Session::live_thread。

调用图：调用 1 个内部函数（live_thread）。

fn live_thread(&self) -> Option<&LiveThread>

作用：查看当前会话有没有连接到实时持久化线程对象。

数据流：进去无参数；函数返回 services.live_thread 的引用；出来是可选 LiveThread。

调用关系：flush_rollout、persist_rollout_items、try_ensure_rollout_materialized 等持久化流程都会用它。

调用图：被 5 处调用（current_rollout_path, flush_rollout, live_thread_for_persistence, persist_rollout_items, try_ensure_rollout_materialized）。

async fn flush_rollout(&self) -> std::io::Result<()>

作用：把已写入的对话录像刷到存储里。它像保存文档，避免缓冲区里的内容还没落盘。

数据流：进去无参数；如果有 live_thread 就调用 flush 并把错误转成 io::Error，没有则什么都不做；出来是 IO 结果。

调用关系：record_initial_history 在恢复或分叉后会调用它，确保初始化历史尽快稳定保存。

调用图：调用 1 个内部函数（live_thread）；被 1 处调用（record_initial_history）。

async fn try_ensure_rollout_materialized(&self) -> std::io::Result<()>

作用：尽力确保对话录像真正形成文件或持久记录。materialized 可以理解为“从内存里的临时东西变成可保存的实体”。

数据流：进去无参数；如果有 live_thread 就调用 persist；出来是 IO 结果，没有 live_thread 时成功返回。

调用关系：ensure_rollout_materialized 包装它，后者负责吞掉错误并记录警告。

调用图：调用 1 个内部函数（live_thread）；被 1 处调用（ensure_rollout_materialized）。

async fn ensure_rollout_materialized(&self)

作用：保证对话录像被持久化，但不让失败打断主流程。它适合在记录历史时做“尽量保存”。

数据流：进去无参数；函数调用 try_ensure_rollout_materialized，失败就写警告；出来无返回。

调用关系：hook_transcript_path、record_initial_history 和记录用户提示时会调用它。

调用图：调用 1 个内部函数（try_ensure_rollout_materialized）；被 3 处调用（hook_transcript_path, record_initial_history, record_user_prompt_and_emit_turn_item）；外部调用 1 个（warn!）。

fn next_internal_sub_id(&self) -> String

作用：生成一个内部自动提交 id，当前用于自动压缩这类系统发起的输入。

数据流：进去无参数；函数用原子计数器加一，拼成 auto-compact-数字；出来是字符串 id。

调用关系：route_realtime_text_input 调用它，为实时文本输入造一个内部回合编号。

调用图：被 1 处调用（route_realtime_text_input）；外部调用 1 个（format!）。

async fn route_realtime_text_input(self: &Arc<Self>, text: String)

作用：把实时通道来的文本当作普通用户输入送进会话。实时通道可能来自语音或流式界面。

数据流：进去的是文本；函数生成内部 id，把文本包成 Op::UserInput，并调用 user_input_or_turn_inner；出来无显式结果，输入会进入正常处理流程。

调用关系：实时输入层会调用它。它把实时世界接到普通用户输入处理器。

调用图：调用 2 个内部函数（next_internal_sub_id, user_input_or_turn_inner）；外部调用 2 个（default, vec!）。

async fn get_total_token_usage(&self) -> i64

作用：读取当前累计 token 用量。token 可以粗略理解为模型处理文本时计费和计量的小片段。

数据流：进去无参数；函数锁状态，根据是否包含服务器推理用量计算总数；出来是 i64 数字。

调用关系：用量展示或压缩判断会用它。它从 SessionState 里读历史统计。

async fn auto_compact_window_snapshot(&self) -> AutoCompactWindowSnapshot

作用：获取自动压缩窗口的当前快照。自动压缩用于在对话太长时缩短上下文。

数据流：进去无参数；函数锁状态并调用 auto_compact_window_snapshot；出来是 AutoCompactWindowSnapshot。

调用关系：需要展示或判断压缩状态的流程会调用它。

async fn estimated_tokens_after_last_model_generated_item(&self) -> i64

作用：估算最近一次模型生成内容之后又新增了多少 token。用于判断上下文增长情况。

数据流：进去无参数；函数读取历史对象的估算值；出来是 i64。

调用关系：压缩和用量监控相关流程会用它。

async fn total_token_usage(&self) -> Option<TokenUsage>

作用：返回完整的 token 使用统计，如果当前还没有统计则返回空。

数据流：进去无参数；函数从状态里取 token_info，并提取 total_token_usage；出来是可选 TokenUsage。

调用关系：UI 或报告模块可用它显示总用量。

async fn token_usage_info(&self) -> Option<TokenUsageInfo>

作用：读取更完整的 token 用量信息，不只总数。它保留模型请求统计所需的结构化数据。

数据流：进去无参数；函数锁状态并返回 token_info；出来是可选 TokenUsageInfo。

调用关系：统计展示、恢复会话后的用量同步等流程会用它。

async fn get_estimated_token_count(
        &self,
        turn_context: &TurnContext,
    ) -> Option<i64>

作用：按某个回合上下文估算当前历史会消耗多少 token。

数据流：进去的是 TurnContext；函数锁状态，让 history 根据该上下文估算 token；出来是可选 i64。

调用关系：模型调用前、压缩判断前可能会调用它。

async fn get_base_instructions(&self) -> BaseInstructions

作用：读取当前会话的基础指令。基础指令就是每次给模型的底层说明，决定助手的大方向。

数据流：进去无参数；函数锁状态并复制 base_instructions 文本；出来是 BaseInstructions。

调用关系：apply_rollout_reconstruction 和 recompute_token_usage 会调用它，用来重建或估算上下文。

调用图：被 2 处调用（apply_rollout_reconstruction, recompute_token_usage）。

async fn merge_connector_selection(
        &self,
        connector_ids: HashSet<String>,
    ) -> HashSet<String>

作用：把新的连接器选择合并进当前选择。连接器可以理解为可用外部数据源或服务。

数据流：进去是一组 connector id；函数锁住状态并合并；出来是合并后的 HashSet。

调用关系：连接器选择更新流程会用它，实际状态改动由 SessionState 完成。

async fn get_connector_selection(&self) -> HashSet<String>

作用：读取当前选中的连接器集合。

数据流：进去无参数；函数锁状态并取出当前集合；出来是 HashSet<String>。

调用关系：需要展示或使用连接器选择的流程会调用它。

async fn clear_connector_selection(&self)

作用：清空当前连接器选择。

数据流：进去无参数；函数锁住状态并调用 clear_connector_selection；出来无返回，内部集合被清空。

调用关系：重置连接器选择或开始新上下文时会用它。

async fn record_initial_history(&self, conversation_history: InitialHistory)

作用：在线程启动时把已有历史接回当前会话。它负责处理新线程、清空线程、恢复线程和分叉线程的不同情况。

数据流：进去的是 InitialHistory；函数判断是否已有用户回合，设置“下一回合是否第一回合”，对恢复/分叉历史重建上下文、填充 token 信息、保存或刷写 rollout，并在模型变更时发警告；出来无返回，但会修改状态和持久化内容。

调用关系：Session 初始化流程会调用它。它会调用 apply_rollout_reconstruction、flush_rollout、persist_rollout_items、ensure_rollout_materialized 和 send_event。

调用图：调用 7 个内部函数（apply_rollout_reconstruction, ensure_rollout_materialized, flush_rollout, persist_rollout_items, send_event, set_previous_turn_settings, initial_history_has_prior_user_turns）；外部调用 4 个（last_token_info_from_rollout, format!, Warning, warn!）。

async fn apply_rollout_reconstruction(
        &self,
        turn_context: &TurnContext,
        rollout_items: &[RolloutItem],
    ) -> Option<PreviousTurnSettings>

作用：把保存过的对话录像重建成当前内存里的历史。这样恢复或分叉线程时，模型能接上以前的上下文。

数据流：进去的是 TurnContext 和 rollout_items；函数重建 history、上次回合设置、参考上下文项和窗口 id，必要时处理旧图片，然后替换状态里的历史，并按配置估算压缩窗口前缀 token；出来是 previous_turn_settings。

调用关系：record_initial_history 在恢复和分叉时调用它。它还会调用 get_base_instructions、clone_history 和 set_auto_compact_window_estimated_prefill_for_scope。

调用图：调用 4 个内部函数（prepare_response_items, clone_history, get_base_instructions, set_auto_compact_window_estimated_prefill_for_scope）；被 1 处调用（record_initial_history）；外部调用 1 个（matches!）。

async fn set_auto_compact_window_estimated_prefill_for_scope(
        &self,
        turn_context: &TurnContext,
        tokens: i64,
    )

作用：在特定压缩计数模式下，记录自动压缩窗口前面已经占用的 token 数。

数据流：进去的是 TurnContext 和 token 数；函数先检查配置是否是 BodyAfterPrefix，不是就退出；是的话锁状态写入估算前缀；出来无返回。

调用关系：apply_rollout_reconstruction 和 recompute_token_usage 会调用它，用于保持自动压缩计算准确。

调用图：被 2 处调用（apply_rollout_reconstruction, recompute_token_usage）；外部调用 1 个（matches!）。

fn last_token_info_from_rollout(rollout_items: &[RolloutItem]) -> Option<TokenUsageInfo>

作用：从对话录像里找出最后一次记录的 token 用量信息。恢复线程时可立刻显示旧用量。

数据流：进去的是 rollout_items；函数从后往前找 TokenCount 事件并克隆其中 info；出来是可选 TokenUsageInfo。

调用关系：record_initial_history 在恢复或分叉时调用它，把历史用量塞回当前状态。

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

async fn previous_turn_settings(&self) -> Option<PreviousTurnSettings>

作用：读取上一个回合使用的设置。它用于判断本回合是否需要告诉模型“设置变了”。

数据流：进去无参数；函数锁状态并取 previous_turn_settings；出来是可选 PreviousTurnSettings。

调用关系：构造上下文更新时会用到这类信息；本段还提供 set_previous_turn_settings 来写入。

async fn set_previous_turn_settings(
        &self,
        previous_turn_settings: Option<PreviousTurnSettings>,
    )

作用：保存上一个回合的设置，供下个回合比较。

数据流：进去的是可选 PreviousTurnSettings；函数锁状态并写入；出来无返回。

调用关系：record_initial_history 会调用它；后续 build_settings_update_items 会读取类似状态。

调用图：被 1 处调用（record_initial_history）。

async fn update_settings(
        &self,
        updates: SessionSettingsUpdate,
    ) -> ConstraintResult<()>

作用：在线程运行中更新会话设置，比如客户端信息、环境选择或权限。它会检查约束，不能随便改坏配置。

数据流：进去的是 SessionSettingsUpdate；函数尝试应用到 session_configuration，记录新旧配置，必要时更新环境选择，通知扩展配置变化；如果权限档案变了，还刷新网络代理；出来是成功或约束错误。

调用关系：Codex::set_app_server_client_info 等运行时设置入口会调用它。它会调用 emit_config_changed_contributors 和 refresh_managed_network_proxy_for_current_permission_profile。

调用图：调用 2 个内部函数（emit_config_changed_contributors, refresh_managed_network_proxy_for_current_permission_profile）；外部调用 1 个（warn!）。

async fn preview_settings(
        &self,
        updates: &SessionSettingsUpdate,
    ) -> ConstraintResult<ThreadConfigSnapshot>

作用：预览一组设置改动会得到什么线程配置快照，但不真正写入。适合 UI 在用户确认前展示结果。

数据流：进去的是设置更新引用；函数在当前配置上试应用，成功则转成 ThreadConfigSnapshot；出来是快照或约束错误，不改变状态。

调用关系：配置预览接口会调用它。它和 update_settings 使用同一套 apply 校验，但不落地。

async fn set_session_startup_prewarm(
        &self,
        startup_prewarm: SessionStartupPrewarmHandle,
    )

作用：保存启动预热句柄。预热通常是提前准备模型或资源，减少第一次响应延迟。

数据流：进去的是 SessionStartupPrewarmHandle；函数锁状态并保存；出来无返回。

调用关系：启动过程或预热管理流程会调用它；take_session_startup_prewarm 会把它取走。

async fn take_session_startup_prewarm(&self) -> Option<SessionStartupPrewarmHandle>

作用：取出并清掉启动预热句柄，表示这个预热资源要被消费了。

数据流：进去无参数；函数锁状态并 take；出来是可选 SessionStartupPrewarmHandle，状态里对应值被清空。

调用关系：真正开始使用预热资源的流程会调用它。

async fn get_config(&self) -> std::sync::Arc<Config>

作用：读取会话启动时保留的原始配置对象。名字里提示不要随便用，是因为线程里还有更适合的运行时配置视图。

数据流：进去无参数；函数锁状态并克隆 Arc<Config>；出来是共享配置指针。

调用关系：需要访问底层配置的内部流程会调用它，尤其是还没拆到更细接口的旧代码。

async fn user_instructions(&self) -> Option<codex_extension_api::UserInstructions>

作用：读取从 AGENTS.md 等指令文件中加载到的用户指令。

数据流：进去无参数；函数锁状态，查看 loaded_agents_md，并提取 user_instructions；出来是可选 UserInstructions。

调用关系：需要把用户指令交给模型或扩展的流程会调用它。

async fn provider(&self) -> ModelProviderInfo

作用：读取当前模型提供商信息。提供商就是模型服务来自哪里、该怎么连接。

数据流：进去无参数；函数锁状态并克隆 provider；出来是 ModelProviderInfo。

调用关系：模型请求构造和诊断信息会用它。

async fn refresh_runtime_config(&self, next_config: Config)

作用：在会话不中断的情况下刷新运行时配置。它主要更新用户配置层，同时保留线程启动时已有的局部覆盖。

数据流：进去的是新的 Config 快照；函数把用户层替换进当前配置，重算工具建议配置，通知扩展配置变化，清空技能和插件缓存，重建 hooks（钩子，某些时机自动执行的小程序），最后确认配置没被更新覆盖后发布 hooks；出来无返回，但运行时配置和缓存会变。

调用关系：reload_user_config_layer 会调用它；有外部已准备好配置快照时也应优先用它。它会调用 emit_config_changed_contributors 和 build_hooks_for_config。

调用图：调用 3 个内部函数（resolve_tool_suggest_config_from_layer_stack, emit_config_changed_contributors, build_hooks_for_config）；被 1 处调用（reload_user_config_layer）；外部调用 3 个（clone, new, ptr_eq）。

fn emit_config_changed_contributors(
        &self,
        previous_config: Option<&Config>,
        new_config: Option<&Config>,
    )

作用：通知扩展：会话配置变了。扩展可以据此更新自己依赖的行为。

数据流：进去的是可选旧配置和新配置；如果任一为空或两者相同就退出；否则遍历 config_contributors，调用 on_config_changed；出来无返回。

调用关系：update_settings 和 refresh_runtime_config 都会调用它。它是配置变化向扩展传播的统一出口。

调用图：被 2 处调用（refresh_runtime_config, update_settings）。

async fn reload_user_config_layer(&self)

作用：从本地配置文件重新加载用户配置层，并刷新当前会话。它是旧式本地热重载路径。

数据流：进去无参数；函数找出用户配置 toml 文件路径，逐个读取和解析，文件不存在就当空配置；然后把这些用户配置层合并进当前配置，重算工具建议配置，最后调用 refresh_runtime_config；出来无返回，读取或解析失败会记录警告并停止。

调用关系：本地配置重载命令会调用它。它把文件 IO 转换成 Config 后交给 refresh_runtime_config。

调用图：调用 2 个内部函数（resolve_tool_suggest_config_from_layer_stack, refresh_runtime_config）；外部调用 6 个（default, with_capacity, read_to_string, Table, vec!, warn!）。

async fn build_settings_update_items(
        &self,
        reference_context_item: Option<&TurnContextItem>,
        current_context: &TurnContext,
    ) -> Vec<ResponseItem>

作用：生成要写进模型上下文的“设置变化说明”。当 shell、权限或人格等变了，模型需要知道。

数据流：进去的是参考上下文项和当前 TurnContext；函数读取上回合设置、当前 shell 和执行策略，再调用 context_manager 的构造函数；出来是一组 ResponseItem。

调用关系：record_context_updates_and_set_reference_context_item 会调用它。它把 Session 状态整理后交给 context_manager::updates::build_settings_update_items。

调用图：调用 2 个内部函数（build_settings_update_items, user_shell）；被 1 处调用（record_context_updates_and_set_reference_context_item）。

fn track_turn_codex_error(&self, turn_context: &TurnContext, error: &CodexErr)

作用：把某个回合里的 Codex 错误记录到分析系统。这样后续可以统计和排查错误。

数据流：进去的是 TurnContext 和 CodexErr；函数把线程 id、回合 id 和错误转成 TurnCodexErrorFact，交给 analytics_events_client；出来无返回。

调用关系：回合失败处理时会调用它。它不改变会话状态，只上报分析事件。

调用图：调用 1 个内部函数（from_codex_err）。

async fn send_event(&self, turn_context: &TurnContext, msg: EventMsg)

作用：发送一条面向外部的会话事件，并顺带完成记录、状态更新、实时同步和兼容旧事件等工作。它是事件出口的主入口。

数据流：进去的是 TurnContext 和 EventMsg；函数记录终止错误、写追踪，把消息包装成 Event 发出，必要时通知父代理、同步实时文本、结束实时交接，并生成旧协议事件继续发送；出来无返回，但事件会被持久化并送到 rx_event。

调用关系：很多地方用它发警告、工具项开始/完成、模型校验和审批请求。它内部调用 send_event_raw、maybe_notify_parent_of_terminal_turn、maybe_mirror_event_text_to_realtime 等。

调用图：调用 5 个内部函数（maybe_clear_realtime_handoff_for_event, maybe_mirror_event_text_to_realtime, maybe_notify_parent_of_terminal_turn, send_event_raw, show_raw_agent_reasoning）；被 13 处调用（emit_model_verification, emit_turn_item_completed, emit_turn_item_started, emit_turn_moderation_metadata, maybe_warn_on_server_model_mismatch, notify_stream_error, record_initial_history, request_command_approval, request_patch_approval, request_permissions_for_environment (+3 more)）；外部调用 1 个（clone）。

async fn maybe_notify_parent_of_terminal_turn(
        &self,
        turn_context: &TurnContext,
        msg: &EventMsg,
    )

作用：当 V2 多代理里的子代理回合结束时，通知父代理结果。这样父代理不用轮询，也能知道孩子干完了或失败了。

数据流：进去的是 TurnContext 和事件消息；函数只处理 V2、子代理、TurnComplete 或 TurnAborted；根据终止错误或事件得出 AgentStatus，若是最终状态就转发给父线程；出来无返回。

调用关系：send_event 每次发事件后会调用它。它会在合适时调用 forward_child_completion_to_parent。

调用图：调用 2 个内部函数（is_final, forward_child_completion_to_parent）；被 1 处调用（send_event）；外部调用 3 个（agent_status_from_event, matches!, Errored）。

async fn forward_child_completion_to_parent(
        &self,
        turn_context: &TurnContext,
        parent_thread_id: ThreadId,
        child_agent_path: &codex_protocol::AgentPath,
        status

作用：把子代理完成消息真正发给父线程，并在追踪开启时记录这次代理间通信。

数据流：进去的是回合上下文、父线程 id、子代理路径和状态；函数从子路径推导父代理路径，格式化完成消息，构造 InterAgentCommunication，发给 agent_control；成功后可写入 rollout trace；出来无返回，失败只打 debug 日志。

调用关系：maybe_notify_parent_of_terminal_turn 调它。它把 Session 的子代理状态交给 agent_control 发送到父线程。

调用图：调用 3 个内部函数（format_inter_agent_completion_message, as_str, new）；被 1 处调用（maybe_notify_parent_of_terminal_turn）；外部调用 3 个（new, debug!, clone）。

async fn maybe_mirror_event_text_to_realtime(&self, msg: &EventMsg)

作用：把某些事件里的文字同步到实时对话通道。这样实时界面能听到或看到普通事件流里的文本。

数据流：进去的是 EventMsg；函数先提取可同步文本，确认实时会话正在运行，再调用 handoff_out；出来无返回，失败只记 debug。

调用关系：send_event 会调用它。它连接普通事件系统和 conversation 实时通道。

调用图：调用 1 个内部函数（realtime_text_for_event）；被 1 处调用（send_event）；外部调用 1 个（debug!）。

async fn maybe_clear_realtime_handoff_for_event(&self, msg: &EventMsg)

作用：当一个回合完成时，结束实时通道的交接状态。避免下一段实时输出接到旧回合后面。

数据流：进去的是 EventMsg；如果不是 TurnComplete 就返回；否则调用 handoff_complete，并清掉 active handoff；出来无返回。

调用关系：send_event 每次发事件后会调用它。它和 maybe_mirror_event_text_to_realtime 一起维护实时输出生命周期。

调用图：被 1 处调用（send_event）；外部调用 2 个（debug!, matches!）。

async fn send_event_raw(&self, event: Event)

作用：发送一条已经包装好的 Event，并把它写入对话录像。raw 表示它不再做 send_event 那些额外包装判断。

数据流：进去的是 Event；函数把事件消息变成 RolloutItem 持久化，记录协议追踪，再交给 deliver_event_raw；出来无返回。

调用关系：send_event 和 build_initial_context 会调用它。它把事件持久化和实际投递串起来。

调用图：调用 2 个内部函数（deliver_event_raw, persist_rollout_items）；被 2 处调用（build_initial_context, send_event）；外部调用 1 个（vec!）。

async fn deliver_event_raw(&self, event: Event)

作用：把事件真正送进事件通道，并更新最后已知代理状态。

数据流：进去的是 Event；函数尝试从消息推导 AgentStatus 并写入 watch 通道，然后发送到 tx_event；如果接收端已关，只记录 debug；出来无返回。

调用关系：send_event_raw 调用它。Codex::next_event 的接收端会从同一通道拿到这些事件。

调用图：被 1 处调用（send_event_raw）；外部调用 2 个（agent_status_from_event, debug!）。

async fn emit_turn_item_started(&self, turn_context: &TurnContext, item: &TurnItem)

作用：发出“某个回合项目开始了”的事件。回合项目可能是用户消息、模型消息或工具调用等。

数据流：进去的是 TurnContext 和 TurnItem；函数复制 item，补上线程 id、回合 id 和开始时间，包装成 ItemStartedEvent 并发送；出来无返回。

调用关系：记录响应项或用户提示时会调用它。它通过 send_event 进入统一事件流程。

调用图：调用 2 个内部函数（send_event, now_unix_timestamp_ms）；被 2 处调用（record_response_item_and_emit_turn_item, record_user_prompt_and_emit_turn_item）；外部调用 2 个（clone, ItemStarted）。

async fn emit_turn_item_completed(
        &self,
        turn_context: &TurnContext,
        item: TurnItem,
    )

作用：发出“某个回合项目完成了”的事件，并记录首个模型输出耗时等指标。

数据流：进去的是 TurnContext 和 TurnItem；函数先记录 TTFM 指标，再补上完成时间并发送 ItemCompletedEvent；出来无返回。

调用关系：记录响应项或用户提示完成时调用它。它通过 send_event 分发事件。

调用图：调用 3 个内部函数（send_event, now_unix_timestamp_ms, record_turn_ttfm_metric）；被 2 处调用（record_response_item_and_emit_turn_item, record_user_prompt_and_emit_turn_item）；外部调用 1 个（ItemCompleted）。

async fn persist_execpolicy_amendment(
        &self,
        amendment: &ExecPolicyAmendment,
    ) -> Result<(), ExecPolicyUpdateError>

作用：把执行策略的新增批准规则保存下来，并更新当前执行策略。执行策略就是决定哪些命令能跑、哪些要问用户的规则。

数据流：进去的是 ExecPolicyAmendment；函数读取 codex_home，然后调用 exec_policy.append_amendment_and_update；出来是成功或 ExecPolicyUpdateError。

调用关系：用户批准某类命令后会调用它。后续命令检查会使用更新后的执行策略。

async fn turn_context_for_sub_id(&self, sub_id: &str) -> Option<Arc<TurnContext>>

作用：根据回合 id 找到当前活跃回合的上下文。上下文里有模型、配置、状态等本回合资料。

数据流：进去的是 sub_id；函数查看 active_turn，如果正在运行的任务 id 匹配，就克隆 TurnContext；出来是可选 Arc<TurnContext>。

调用关系：记录执行策略或网络策略变更消息时会调用它，以便把说明注入到正确回合。

调用图：被 2 处调用（record_execpolicy_amendment_message, record_network_policy_amendment_message）。

async fn active_turn_context_and_cancellation_token(
        &self,
    ) -> Option<(Arc<TurnContext>, CancellationToken)>

作用：取得当前活跃回合上下文和一个可取消它的令牌。取消令牌像一个遥控开关，可以通知任务停下。

数据流：进去无参数；函数锁 active_turn，若有任务就克隆 TurnContext，并从任务取消令牌派生子令牌；出来是可选二元组。

调用关系：需要中断或附加控制当前回合的内部流程会用它。

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

async fn record_execpolicy_amendment_message(
        &self,
        sub_id: &str,
        amendment: &ExecPolicyAmendment,
    )

作用：把“已保存命令批准规则”这件事写进当前对话上下文。这样模型以后知道用户已经允许了某类命令。

数据流：进去的是 sub_id 和 ExecPolicyAmendment；函数把命令格式化成允许前缀，构造 ApprovedCommandPrefixSaved 消息，找到对应回合上下文，然后 inject_no_new_turn 注入；出来无返回。

调用关系：执行策略规则保存后会调用它。它依赖 turn_context_for_sub_id，并把消息交给 inject_no_new_turn。

调用图：调用 4 个内部函数（into, new, turn_context_for_sub_id, format_allow_prefixes）；外部调用 2 个（vec!, warn!）。

async fn persist_network_policy_amendment(
        &self,
        amendment: &NetworkPolicyAmendment,
        network_approval_context: &NetworkApprovalContext,
    ) -> anyhow::Result<()>

作用：保存用户对某个网络域名的允许或拒绝规则，并尽量立刻更新运行中的网络代理。

数据流：进去的是 NetworkPolicyAmendment 和审批上下文；函数拿刷新锁，校验域名和被批准域名一致，生成执行策略网络规则；若代理已运行就更新允许/拒绝列表，再把规则写入 exec_policy；出来是成功或错误。

调用关系：网络访问审批通过后会调用它。它会调用 validated_network_policy_amendment_host，并更新 services.network_proxy 和 exec_policy。

调用图：调用 1 个内部函数（execpolicy_network_rule_amendment）；外部调用 1 个（validated_network_policy_amendment_host）。

fn validated_network_policy_amendment_host(
        amendment: &NetworkPolicyAmendment,
        network_approval_context: &NetworkApprovalContext,
    ) -> anyhow::Result<String>

作用：确认要保存的网络规则域名，确实就是用户刚批准的域名。它防止把 A 域名的批准偷偷写成 B 域名。

数据流：进去的是 amendment 和审批上下文；函数标准化两个 host 后比较，不一致就报错，一致就返回标准化 host；出来是 host 字符串或错误。

调用关系：persist_network_policy_amendment 在写入任何规则前调用它，是网络权限安全检查的一道门。

调用图：外部调用 2 个（anyhow!, normalize_host）。

async fn record_network_policy_amendment_message(
        &self,
        sub_id: &str,
        amendment: &NetworkPolicyAmendment,
    )

作用：把“已保存网络规则”这件事注入当前对话。这样模型知道某个域名之后已被允许或拒绝。

数据流：进去的是 sub_id 和 NetworkPolicyAmendment；函数构造 NetworkRuleSaved 消息，找到当前回合上下文，并用 inject_no_new_turn 注入；出来无返回。

调用关系：网络策略保存后会调用它。它和 record_execpolicy_amendment_message 类似，都是把外部批准结果写回模型可见上下文。

调用图：调用 3 个内部函数（into, new, turn_context_for_sub_id）；外部调用 1 个（vec!）。

async fn request_command_approval(
        &self,
        turn_context: &TurnContext,
        call_id: String,
        approval_id: Option<String>,
        command: Vec<String>,
        cwd: AbsoluteP

作用：在命令真正执行前，向用户或审核界面请求批准。它用于拦住可能有风险的命令，等到明确同意、拒绝或中止后再继续。

数据流：输入是一条命令、工作目录、原因、网络或执行策略相关补充信息，以及本轮上下文 → 它先把一个“等待审批的回执通道”登记到当前轮状态里，再整理命令展示信息和可选审批按钮，最后发出 ExecApprovalRequest 事件 → 输出是一个 ReviewDecision，也就是批准、拒绝、终止等决定；如果等不到回复，就当作 Abort。

调用关系：它先通过 parse_command 把命令变成更适合展示的形式，再用 send_event 把审批请求送出去。之后 notify_approval 会根据 approval_id 找到这里登记的等待项，把审批结果送回来。

调用图：调用 3 个内部函数（send_event, now_unix_timestamp_ms, parse_command）；外部调用 3 个（channel, ExecApprovalRequest, warn!）。

async fn request_patch_approval(
        &self,
        turn_context: &TurnContext,
        call_id: String,
        changes: HashMap<PathBuf, FileChange>,
        reason: Option<String>,
        gran

作用：在应用文件补丁前，请用户批准这些文件改动。它让系统能先展示“哪些文件会变、怎么变”，再决定是否动手。

数据流：输入是补丁调用编号、文件改动集合、原因和可能授予的根目录 → 它登记一个等待审批的通道，然后发送 ApplyPatchApprovalRequest 事件 → 输出不是立刻的决定，而是一个接收器，调用方之后可以从里面等到 ReviewDecision。

调用关系：它和 request_command_approval 的模式类似：先登记等待项，再发事件。后续用户回应会通过 notify_approval 回到同一个 pending approval 表里。

调用图：调用 2 个内部函数（send_event, now_unix_timestamp_ms）；外部调用 3 个（channel, ApplyPatchApprovalRequest, warn!）。

async fn request_permissions_for_environment(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        call_id: String,
        args: RequestPermissionsArgs,
        environment: Tur

作用：当模型或工具想临时获得更多权限时，这个函数负责发起权限申请。它会根据当前审批策略判断是否需要问人、问 Guardian 审核器，还是直接给默认空权限。

数据流：输入是申请编号、申请的权限、目标环境、取消信号和本轮上下文 → 它先检查审批策略；如果不允许申请或目录不是本机路径，就返回空权限；如果走 Guardian，就创建审核请求并等待结果；否则登记等待响应并发 RequestPermissions 事件 → 输出是标准化后的 RequestPermissionsResponse，或者取消时输出 None；如果批准，还会把权限记录到本轮或整场会话状态里。

调用关系：request_permissions_for_cwd 会先把当前目录包装成环境选择，再调用它。它内部可能把活交给 Guardian 审核流程，也会调用 normalize_request_permissions_response 防止返回超出申请范围的权限，并调用 record_granted_request_permissions_for_turn 保存结果。

调用图：调用 3 个内部函数（record_granted_request_permissions_for_turn, send_event, now_unix_timestamp_ms）；被 1 处调用（request_permissions_for_cwd）；外部调用 12 个（clone, clone, normalize_request_permissions_response, default, new_guardian_review_id, routes_approval_to_guardian, spawn_approval_request_review, channel, RequestPermissions, clone (+2 more)）。

async fn request_permissions_for_cwd(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        call_id: String,
        args: RequestPermissionsArgs,
        cwd: AbsolutePathBuf,

作用：这是按当前工作目录申请权限的便捷入口。调用方只给一个 cwd，它会找到对应环境，再交给真正的权限申请流程。

数据流：输入是权限申请参数、工作目录、调用编号和取消信号 → 它从本轮环境列表里找指定环境，没有指定就用主环境，并把 cwd 写进环境选择 → 输出来自 request_permissions_for_environment；如果找不到环境，就返回空权限响应。

调用关系：它是 request_permissions_for_environment 的前置包装器，主要负责把“一个目录”转换成“一个可审批的运行环境”。

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

async fn request_user_input(
        &self,
        turn_context: &TurnContext,
        call_id: String,
        args: RequestUserInputArgs,
    ) -> Option<RequestUserInputResponse>

作用：在模型运行到一半需要用户补充回答时，向前端发出提问。它让系统可以暂停等待用户，而不是随便猜。

数据流：输入是调用编号、本轮上下文和要问的问题 → 它把等待用户回答的通道登记到当前轮状态，标记本轮请求过用户输入，然后发送 RequestUserInput 事件 → 输出是用户回答；如果通道断了，就返回 None。

调用关系：它发出的请求会由前端展示给用户。用户回答回来后，notify_user_input_response 会找到这里登记的通道并把答案送回来。

调用图：调用 1 个内部函数（send_event）；外部调用 3 个（channel, RequestUserInput, warn!）。

async fn notify_user_input_response(
        &self,
        sub_id: &str,
        response: RequestUserInputResponse,
    )

作用：把用户对中途提问的回答送回正在等待的流程。它相当于把前端交回来的答卷塞回原来的等待点。

数据流：输入是 turn 的 sub_id 和用户回答 → 它从当前轮状态里移除对应的等待项 → 如果找到了，就把回答发送给 request_user_input；如果没找到，只记录警告，不改变主流程。

调用关系：它是 request_user_input 的配对回调。前者登记等待，后者在用户实际回复时解除等待。

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

async fn notify_request_permissions_response(
        &self,
        call_id: &str,
        response: RequestPermissionsResponse,
    )

作用：接收前端或外部审核给出的权限申请结果，并把结果送回等待中的申请。它还会做安全收口，避免审批结果给出比申请更多的权限。

数据流：输入是权限申请 call_id 和审批响应 → 它找到并移除对应的 pending request，按环境目录标准化权限；如果目录不适合本机处理，则降级为空权限 → 它记录被授予的权限，然后把响应发回等待者；找不到等待项时只警告。

调用关系：它对应 request_permissions_for_environment 中非 Guardian 路径登记的等待项。它会调用 normalize_request_permissions_response 和 record_granted_request_permissions_for_turn，保证权限既安全又被状态记住。

调用图：调用 1 个内部函数（record_granted_request_permissions_for_turn）；外部调用 3 个（normalize_request_permissions_response, default, warn!）。

fn normalize_request_permissions_response(
        requested_permissions: RequestPermissionProfile,
        response: RequestPermissionsResponse,
        cwd: &Path,
    ) -> RequestPermissionsRespons

作用：清洗权限审批结果，防止返回不合理或超范围的权限。它是权限系统里的“安全闸门”。

数据流：输入是原本申请的权限、审批返回的权限和当前目录 → 如果响应要求“严格自动审查”但范围却是整场会话，就直接降为空权限；如果没有授予权限就原样返回；否则把申请权限和响应权限取交集 → 输出一份不会超过原申请范围的响应。

调用关系：request_permissions_for_environment 和 notify_request_permissions_response 都会在拿到审批结果后调用它，再决定是否记录权限。

调用图：调用 1 个内部函数（intersect_permission_profiles）；外部调用 3 个（default, into, matches!）。

async fn record_granted_request_permissions_for_turn(
        &self,
        response: &RequestPermissionsResponse,
        environment_id: &str,
        originating_turn_state: Option<&Arc<Mutex<crat

作用：把已经批准的权限记下来，方便后续同一轮或同一会话复用。它区分“只本轮有效”和“整场会话有效”。

数据流：输入是权限响应、环境编号和原始 turn 状态 → 如果没有权限就直接结束；如果范围是 Turn，就写入本轮状态，并可能开启严格自动审查；如果范围是 Session，就写入会话全局状态 → 输出为空，但状态被更新。

调用关系：它被 request_permissions_for_environment 和 notify_request_permissions_response 调用，作为审批完成后的落账步骤。

调用图：被 2 处调用（notify_request_permissions_response, request_permissions_for_environment）。

async fn granted_turn_permissions(
        &self,
        environment_id: &str,
    ) -> Option<AdditionalPermissionProfile>

作用：查询某个环境在当前轮已经拿到的临时权限。调用者可用它判断是否还需要再次申请。

数据流：输入是环境编号 → 它读取当前活跃 turn 的状态 → 输出该环境的本轮附加权限；如果没有活跃轮或没记录，就返回 None。

调用关系：它不主动触发审批，只是给执行或权限判断逻辑查看当前轮已批准的结果。

async fn strict_auto_review_enabled_for_turn(&self) -> bool

作用：查询当前轮是否开启了严格自动审查。这个标志通常来自权限审批结果，用来让后续行为更谨慎。

数据流：没有业务输入 → 它读取当前活跃 turn 的状态 → 输出 true 或 false；没有活跃轮时返回 false。

调用关系：它读取 record_granted_request_permissions_for_turn 可能写入的 turn 状态，供后续检查逻辑使用。

async fn granted_session_permissions(
        &self,
        environment_id: &str,
    ) -> Option<AdditionalPermissionProfile>

作用：查询某个环境在整场会话里已经拿到的权限。它用于跨多轮复用已批准的会话级权限。

数据流：输入是环境编号 → 它读取会话全局状态 → 输出该环境的会话级附加权限；没有则返回 None。

调用关系：它和 granted_turn_permissions 相对应，一个看全局会话，一个看当前轮。

async fn notify_dynamic_tool_response(&self, call_id: &str, response: DynamicToolResponse)

作用：把动态工具调用的结果送回等待中的调用点。动态工具可以理解为运行时才决定使用的外部能力。

数据流：输入是工具调用 call_id 和工具响应 → 它从当前轮状态里移除对应等待项 → 找到就发送响应，找不到就记录警告。

调用关系：它配合之前登记的 pending dynamic tool 使用，职责和 notify_approval、notify_user_input_response 类似，都是把异步回复送回原等待处。

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

async fn notify_approval(&self, approval_id: &str, decision: ReviewDecision)

作用：接收用户或审核器对某个审批请求的决定，并唤醒等待中的命令或补丁流程。

数据流：输入是 approval_id 和 ReviewDecision → 它从当前轮状态中移除 pending approval → 找到就把决定发给等待者；没找到就警告。

调用关系：它是 request_command_approval 和 request_patch_approval 的回传入口。审批请求先在那里登记，最终在这里完成闭环。

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

fn prepare_conversation_items_for_history(
        &self,
        turn_context: &TurnContext,
        items: &'a [ResponseItem],
    ) -> Cow<'a, [ResponseItem]>

作用：在把对话项写入历史前，按功能开关决定是否先处理图片。主要是为了让历史里的图片尺寸适合后续使用。

数据流：输入是本轮上下文和一组 ResponseItem → 如果没有开启 ResizeAllImages，就借用原数据；如果开启，就复制一份并调用 prepare_response_items 处理 → 输出可能是原切片，也可能是处理后的新列表。

调用关系：record_conversation_items 和 record_inter_agent_communication 在写历史前会调用它，保证进入历史的数据格式符合当前功能设置。

调用图：调用 1 个内部函数（prepare_response_items）；被 2 处调用（record_conversation_items, record_inter_agent_communication）；外部调用 3 个（Borrowed, Owned, to_vec）。

fn response_item_from_user_input(
        &self,
        turn_context: &TurnContext,
        input: Vec<UserInput>,
    ) -> ResponseItem

作用：把用户输入转换成模型历史能保存的 ResponseItem。它还会根据图片处理功能决定图片现在处理还是稍后处理。

数据流：输入是本轮上下文和用户输入列表 → 它检查 ResizeAllImages 功能，选择图片处理方式，然后用 ResponseInputItem::from_user_input 包装 → 输出一个 ResponseItem。

调用关系：record_user_prompt_and_emit_turn_item 会用它把用户消息写入对话历史，同时另外保留 UI 需要的展示细节。

调用图：调用 2 个内部函数（from_user_input, from）；被 1 处调用（record_user_prompt_and_emit_turn_item）。

async fn record_conversation_items(
        &self,
        turn_context: &TurnContext,
        items: &[ResponseItem],
    )

作用：把一批对话内容正式写进会话历史、持久化记录，并通知外部。它是“这段对话真的发生了”的记账入口。

数据流：输入是本轮上下文和 ResponseItem 列表 → 它先准备图片等内容，再写入内存历史，然后持久化为 rollout 记录，最后逐条发送 RawResponseItem 事件 → 输出为空，但历史、磁盘记录和外部事件都更新。

调用关系：record_response_item_and_emit_turn_item、record_user_prompt_and_emit_turn_item、record_context_updates_and_set_reference_context_item 都会调用它。它内部再调用 persist_rollout_response_items 和 send_raw_response_items。

调用图：调用 3 个内部函数（persist_rollout_response_items, prepare_conversation_items_for_history, send_raw_response_items）；被 3 处调用（record_context_updates_and_set_reference_context_item, record_response_item_and_emit_turn_item, record_user_prompt_and_emit_turn_item）；外部调用 2 个（as_ref, iter）。

async fn record_inter_agent_communication(
        &self,
        turn_context: &TurnContext,
        communication: InterAgentCommunication,
    )

作用：记录代理之间的通信内容，让多代理协作过程也进入历史和持久化日志。这样恢复会话时不会丢掉代理互相说过什么。

数据流：输入是一条 InterAgentCommunication 和本轮上下文 → 它把通信转成模型输入项，按历史规则处理，写入状态，持久化为 InterAgentCommunication rollout 项，并发送原始响应项事件 → 输出为空，但历史和日志被更新。

调用关系：它复用 prepare_conversation_items_for_history 和 send_raw_response_items，但持久化时使用专门的 RolloutItem::InterAgentCommunication。

调用图：调用 4 个内部函数（persist_rollout_items, prepare_conversation_items_for_history, send_raw_response_items, to_model_input_item）；外部调用 2 个（InterAgentCommunication, from_ref）。

async fn maybe_warn_on_server_model_mismatch(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        server_model: String,
    ) -> bool

作用：检查服务器实际使用的模型是否和用户请求的模型一致。如果不一致，它会向用户发出明确警告。

数据流：输入是服务器报告的模型名和本轮上下文 → 它把请求模型和服务器模型都转成小写比较；一致则返回 false；不一致则记录日志，发送 ModelReroute 事件和 Warning 事件 → 输出 true 表示发生了模型改道。

调用关系：它用 send_event 通知前端模型被重新路由。这个函数把底层服务器事实转成用户能看到的提示。

调用图：调用 1 个内部函数（send_event）；外部调用 5 个（format!, info!, ModelReroute, Warning, warn!）。

async fn emit_model_verification(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        verifications: Vec<ModelVerification>,
    )

作用：发送模型验证结果事件。它让外部界面或客户端知道这轮请求涉及哪些模型验证信息。

数据流：输入是一组 ModelVerification 和本轮上下文 → 它包装成 ModelVerificationEvent → 通过 send_event 发出，状态本身不改变。

调用关系：它是一个事件出口，专门把模型验证信息从会话内部送到外部订阅者。

调用图：调用 1 个内部函数（send_event）；外部调用 1 个（ModelVerification）。

async fn emit_turn_moderation_metadata(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        metadata: TurnModerationMetadataEvent,
    )

作用：发送本轮的审核或安全元数据。元数据可以理解为给这轮对话贴上的安全相关标签或说明。

数据流：输入是 TurnModerationMetadataEvent 和本轮上下文 → 它包装进 EventMsg::TurnModerationMetadata → 通过 send_event 发出。

调用关系：它和 emit_model_verification 类似，是把内部安全信息传给外部的事件出口。

调用图：调用 1 个内部函数（send_event）；外部调用 1 个（TurnModerationMetadata）。

async fn replace_history(
        &self,
        items: Vec<ResponseItem>,
        reference_context_item: Option<TurnContextItem>,
    )

作用：用一套新的对话历史替换当前历史。它通常用于恢复、压缩或重建上下文后的状态切换。

数据流：输入是新的 ResponseItem 列表和可选的参考上下文项 → 它锁住会话状态并调用 replace_history → 输出为空，但内存中的历史被整体替换。

调用关系：它只改内存状态，不负责持久化；需要持久化压缩结果时会用 replace_compacted_history。

async fn replace_compacted_history(
        &self,
        items: Vec<ResponseItem>,
        reference_context_item: Option<TurnContextItem>,
        compacted_item: CompactedItem,
    )

作用：用压缩后的历史替换当前历史，并把这次压缩写进持久化记录。它用于对话太长时“打包整理”上下文。

数据流：输入是替换后的历史、参考上下文项和压缩记录 → 它先替换内存历史，再持久化 Compacted 项；如果有参考上下文，也一起持久化；最后标记下一次会话开始来源是 Compact → 输出为空，但历史和 rollout 日志都更新。

调用关系：它调用 persist_rollout_items 写入压缩痕迹，比 replace_history 多了持久化和后续 hook 来源标记。

调用图：调用 1 个内部函数（persist_rollout_items）；外部调用 2 个（Compacted, TurnContext）。

async fn persist_rollout_response_items(&self, items: &[ResponseItem])

作用：把普通 ResponseItem 转成可持久化的 rollout 项并写入。rollout 可以理解为会话过程的流水账。

数据流：输入是一组 ResponseItem → 它逐个克隆并包装成 RolloutItem::ResponseItem → 交给 persist_rollout_items 写入存储。

调用关系：record_conversation_items 会调用它。它自己不接触磁盘细节，而是把写入交给 persist_rollout_items。

调用图：调用 1 个内部函数（persist_rollout_items）；被 1 处调用（record_conversation_items）；外部调用 1 个（iter）。

fn enabled(&self, feature: Feature) -> bool

作用：快速查询某个功能开关是否打开。调用方用它决定某些新能力或实验功能要不要生效。

数据流：输入是 Feature 枚举值 → 它读取 Session 持有的 features → 输出 true 或 false。

调用关系：这是一个简单的功能开关查询入口，给会话内部或附近模块使用。

fn features(&self) -> ManagedFeatures

作用：返回当前会话的功能开关集合副本。调用者可以自己进一步查询多个开关。

数据流：没有业务输入 → 它克隆 ManagedFeatures → 输出这份功能开关对象。

调用关系：它是 Session 对功能配置的访问器，不做额外判断。

async fn collaboration_mode(&self) -> CollaborationMode

作用：读取当前会话的协作模式。协作模式会影响提示词和多代理协作方式。

数据流：没有业务输入 → 它读取会话状态里的 session_configuration.collaboration_mode → 输出其克隆值。

调用关系：build_initial_context 会把协作模式转成模型可见的说明；这个函数提供运行时查询。

fn multi_agent_version(&self) -> Option<MultiAgentVersion>

作用：查看会话已经确定的多代理版本。多代理版本就是多代理协作协议或实现方案的版本。

数据流：没有业务输入 → 它读取一次性初始化的 multi_agent_version → 输出 Some 版本或 None。

调用关系：resolve_multi_agent_version_for_model 会先调用它，如果已经定过版本就不再重新选择。

调用图：被 1 处调用（resolve_multi_agent_version_for_model）。

fn set_multi_agent_version_if_unset(
        &self,
        multi_agent_version: MultiAgentVersion,
    ) -> MultiAgentVersion

作用：如果多代理版本还没定，就设置它；如果已经定了，就保持原值。这样同一会话不会中途换协议。

数据流：输入是候选 MultiAgentVersion → 它通过 get_or_init 只在未设置时写入 → 输出最终使用的版本。

调用关系：resolve_multi_agent_version_for_model 在选出默认版本后调用它，保证选择只发生一次。

调用图：被 1 处调用（resolve_multi_agent_version_for_model）。

fn resolve_multi_agent_version_for_model(
        &self,
        model_info: &ModelInfo,
        config: &Config,
    ) -> MultiAgentVersion

作用：根据模型信息和配置决定本会话使用哪个多代理版本。它避免每轮都重新猜版本。

数据流：输入是 ModelInfo 和 Config → 它先看会话是否已有版本；没有则优先用模型指定版本，否则用配置按功能推导出的版本 → 输出最终版本，并在会话中固定下来。

调用关系：它调用 multi_agent_version 和 set_multi_agent_version_if_unset，承担“选一次并缓存”的角色。

调用图：调用 2 个内部函数（multi_agent_version, set_multi_agent_version_if_unset）。

async fn send_raw_response_items(&self, turn_context: &TurnContext, items: &[ResponseItem])

作用：把原始对话项逐条发给外部监听者。外部界面可据此同步显示或记录模型看到的内容。

数据流：输入是本轮上下文和 ResponseItem 列表 → 它遍历每一项，包装成 RawResponseItemEvent → 逐条 send_event。

调用关系：record_conversation_items 和 record_inter_agent_communication 在写完历史后调用它，让外部也知道新内容。

调用图：调用 1 个内部函数（send_event）；被 2 处调用（record_conversation_items, record_inter_agent_communication）；外部调用 1 个（RawResponseItem）。

async fn build_initial_context(
        &self,
        turn_context: &TurnContext,
    ) -> Vec<ResponseItem>

作用：生成一轮对话开始时模型需要看的初始背景。它把权限规则、环境、插件、技能、协作模式、用户说明等整理成模型消息。

数据流：输入是本轮 TurnContext → 它读取会话状态中的参考上下文、上一轮设置、基础指令和压缩窗口；再按配置和功能开关收集权限说明、开发者说明、应用连接器、技能、插件、扩展贡献内容、环境信息和 token 预算等 → 输出一组 ResponseItem，作为要注入模型上下文的初始消息。

调用关系：maybe_start_new_context_window 和 record_context_updates_and_set_reference_context_item 会调用它。它是上下文拼装中心，会向连接器、插件、扩展、技能系统拿材料，然后拼成模型可读的消息。

调用图：调用 19 个内部函数（list_accessible_and_enabled_connectors_from_manager, from_connectors, from_plugins, from, from_collaboration_mode, from_turn_context, new, new, build_contextual_user_message, build_developer_update_item (+9 more)）；被 2 处调用（maybe_start_new_context_window, record_context_updates_and_set_reference_context_item）；外部调用 9 个（new, new, with_capacity, with_capacity, build_available_skills, default_skill_metadata_budget, is_guardian_reviewer_source, Warning, vec!）。

async fn persist_rollout_items(&self, items: &[RolloutItem])

作用：把会话流水账项写入当前 live thread。它是很多记录操作最终落盘的公共出口。

数据流：输入是一组 RolloutItem → 它先找当前 live_thread；如果存在，就调用 append_items 写入；失败则记录错误 → 输出为空，成功时持久化存储增加新记录。

调用关系：record_conversation_items、record_inter_agent_communication、replace_compacted_history、maybe_start_new_context_window、record_context_updates_and_set_reference_context_item 等都会间接或直接调用它。

调用图：调用 1 个内部函数（live_thread）；被 7 处调用（maybe_start_new_context_window, persist_rollout_response_items, record_context_updates_and_set_reference_context_item, record_initial_history, record_inter_agent_communication, replace_compacted_history, send_event_raw）；外部调用 1 个（error!）。

async fn clone_history(&self) -> ContextManager

作用：复制当前对话历史管理器。它让调用方可以在不直接改原状态的情况下查看或计算历史。

数据流：没有业务输入 → 它锁住状态并克隆历史 → 输出 ContextManager 副本。

调用关系：apply_rollout_reconstruction 和 recompute_token_usage 会用它，前者用于重建，后者用于重新估算 token 用量。

调用图：被 2 处调用（apply_rollout_reconstruction, recompute_token_usage）。

async fn current_window_id(&self) -> String

作用：生成当前上下文窗口的唯一标识。它把线程编号和自动压缩窗口编号拼在一起。

数据流：没有业务输入 → 它读取当前 auto_compact_window_id 和 thread_id → 输出形如“thread:window”的字符串。

调用关系：它为日志、追踪或上下文窗口识别提供一个稳定名字。

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

async fn advance_auto_compact_window_id(&self) -> u64

作用：推进自动压缩窗口编号。每次开启新窗口时需要新的编号，避免混淆不同阶段的上下文。

数据流：没有业务输入 → 它锁住状态并调用 advance_auto_compact_window_id → 输出新的窗口编号。

调用关系：它属于上下文窗口生命周期控制的一部分，和 maybe_start_new_context_window 的窗口切换概念配套。

async fn request_new_context_window(&self)

作用：标记“接下来要开一个新的上下文窗口”。这像先按下一个开关，真正切换会在稍后的检查点发生。

数据流：没有业务输入 → 它锁住状态并设置新窗口请求标记 → 输出为空。

调用关系：maybe_start_new_context_window 会读取这个请求标记，如果确实有请求，就真正替换历史并持久化。

async fn maybe_start_new_context_window(
        &self,
        turn_context: &TurnContext,
    ) -> Option<u64>

作用：如果之前请求过新上下文窗口，就真正开始一个新窗口。它会用初始上下文替换历史，并记录一次压缩事件。

数据流：输入是本轮上下文 → 它先尝试从状态里领取一个新窗口编号；没有请求则返回 None；有请求则构建初始上下文，替换历史，持久化 Compacted 和 TurnContext 项，标记会话开始来源为 Compact，重新计算 token → 输出 Some(window_id)。

调用关系：它调用 build_initial_context、persist_rollout_items 和 recompute_token_usage，是上下文窗口切换的执行者。

调用图：调用 4 个内部函数（build_initial_context, persist_rollout_items, recompute_token_usage, to_turn_context_item）；外部调用 3 个（new, Compacted, TurnContext）。

async fn reference_context_item(&self) -> Option<TurnContextItem>

作用：读取当前用于计算上下文差异的参考项。它帮助系统知道上一轮的基线是什么。

数据流：没有业务输入 → 它读取状态里的 reference_context_item → 输出可选 TurnContextItem。

调用关系：record_context_updates_and_set_reference_context_item 会更新这个基线；这个函数提供只读访问。

async fn record_context_updates_and_set_reference_context_item(
        &self,
        turn_context: &TurnContext,
    )

作用：在每轮开始时记录该给模型看的上下文更新，并刷新差异计算基线。它避免每轮都重复塞完整背景，节省 token。

数据流：输入是本轮上下文 → 如果还没有参考上下文，就构建完整初始上下文；否则只构建设置差异项；有内容就写入对话历史；无论有没有内容，都持久化新的 TurnContextItem，并把它设为新的参考基线 → 输出为空。

调用关系：它会调用 build_initial_context 或 build_settings_update_items，再用 record_conversation_items 和 persist_rollout_items 记录结果。

调用图：调用 5 个内部函数（build_initial_context, build_settings_update_items, persist_rollout_items, record_conversation_items, to_turn_context_item）；外部调用 1 个（TurnContext）。

async fn update_token_usage_info(
        &self,
        turn_context: &TurnContext,
        token_usage: Option<&TokenUsage>,
    )

作用：更新 token 用量信息，并通知外部当前 token 状态。token 是模型上下文长度和计费/限额相关的重要计量。

数据流：输入是本轮上下文和可选 TokenUsage → 它先记录用量，再发送 TokenCount 事件 → 输出为空，状态和外部显示都更新。

调用关系：它是 token 用量更新的高层入口，内部依次调用 record_token_usage_info 和 send_token_count_event。

调用图：调用 2 个内部函数（record_token_usage_info, send_token_count_event）。

async fn record_token_usage_info(
        &self,
        turn_context: &TurnContext,
        token_usage: Option<&TokenUsage>,
    )

作用：把服务器返回的 token 用量写入会话状态，并通知扩展。扩展可以基于用量做自己的统计或提示。

数据流：输入是本轮上下文和可选 TokenUsage → 有用量时，它更新状态里的 token_info；若配置要求，还会记录自动压缩所需的服务器预填信息；随后把 token_info 发给所有 token_usage_contributors → 输出为空。

调用关系：它被 update_token_usage_info 调用，只负责记录和扩展回调，不负责发 TokenCount 事件。

调用图：调用 1 个内部函数（model_context_window）；被 1 处调用（update_token_usage_info）；外部调用 1 个（matches!）。

async fn recompute_token_usage(&self, turn_context: &TurnContext)

作用：在历史被替换或压缩后，重新估算当前上下文占用了多少 token。这样界面和自动压缩判断不会用旧数字。

数据流：输入是本轮上下文 → 它复制历史，读取基础指令，估算总 token；估算失败则退出；成功后更新状态里的 token_info，设置自动压缩相关预填估算，并发送 TokenCount 事件 → 输出为空。

调用关系：maybe_start_new_context_window 在切换新窗口后会调用它。它还调用 clone_history、get_base_instructions、set_auto_compact_window_estimated_prefill_for_scope 和 send_token_count_event。

调用图：调用 5 个内部函数（clone_history, get_base_instructions, send_token_count_event, set_auto_compact_window_estimated_prefill_for_scope, model_context_window）；被 1 处调用（maybe_start_new_context_window）；外部调用 1 个（default）。

async fn update_rate_limits(
        &self,
        turn_context: &TurnContext,
        new_rate_limits: RateLimitSnapshot,
    )

作用：更新当前速率限制信息，并让外部同步看到。速率限制可以理解为服务端允许你在一段时间内用多少资源。

数据流：输入是本轮上下文和新的 RateLimitSnapshot → 它写入速率限制状态，然后发送 TokenCount 事件，因为该事件同时携带 token 和限额信息 → 输出为空。

调用关系：它是速率限制更新入口，内部调用 record_rate_limits_info 和 send_token_count_event。

调用图：调用 2 个内部函数（record_rate_limits_info, send_token_count_event）。

async fn record_rate_limits_info(&self, new_rate_limits: RateLimitSnapshot)

作用：把新的速率限制快照写进会话状态。它只记账，不负责通知外部。

数据流：输入是 RateLimitSnapshot → 它锁住状态并 set_rate_limits → 输出为空，状态被替换为新限额。

调用关系：update_rate_limits 会先调用它，再发事件通知外部。

调用图：被 1 处调用（update_rate_limits）。

async fn mcp_dependency_prompted(&self) -> HashSet<String>

作用：读取已经提示过用户的 MCP 依赖名称集合。MCP 可以理解为外部工具/服务连接协议，这里避免重复提示同一依赖。

数据流：没有业务输入 → 它读取状态里的 mcp_dependency_prompted 集合 → 输出 HashSet<String>。

调用关系：它和 record_mcp_dependency_prompted 配套，一个读已提示列表，一个写入新提示记录。

async fn record_mcp_dependency_prompted(&self, names: I)

作用：记录哪些 MCP 依赖已经提示过用户。这样后续不会一遍遍打扰用户。

数据流：输入是一批依赖名称 → 它锁住状态并合并记录 → 输出为空，已提示集合变大。

调用关系：它是 mcp_dependency_prompted 的写入端，供依赖检查或启动流程在提示后调用。

async fn set_server_reasoning_included(&self, included: bool)

作用：记录服务器响应里是否包含推理内容。这个标志会影响后续显示或处理服务端推理信息的方式。

数据流：输入是布尔值 included → 它写入会话状态 → 输出为空。

调用关系：它提供一个简单状态开关，供收到服务器能力或响应特征后更新。

async fn send_token_count_event(&self, turn_context: &TurnContext)

作用：向外部发送当前 token 用量和速率限制信息。前端可用它更新进度、剩余上下文或限额显示。

数据流：输入是本轮上下文 → 它读取状态中的 token_info 和 rate_limits，包装成 TokenCountEvent → 通过 send_event 发出。

调用关系：recompute_token_usage、set_total_tokens_full、update_rate_limits、update_token_usage_info 都会调用它，是 token/限额信息的统一通知出口。

调用图：调用 1 个内部函数（send_event）；被 4 处调用（recompute_token_usage, set_total_tokens_full, update_rate_limits, update_token_usage_info）；外部调用 1 个（TokenCount）。

async fn set_total_tokens_full(&self, turn_context: &TurnContext)

作用：把 token 使用状态标记为已经占满上下文窗口，并立即通知外部。它用于明确告诉系统“空间满了”。

数据流：输入是本轮上下文 → 如果能取得模型上下文窗口，就把状态设置为满额；然后发送 TokenCount 事件 → 输出为空。

调用关系：它调用 send_token_count_event，和正常 token 更新共用同一个外部通知通道。

调用图：调用 2 个内部函数（send_token_count_event, model_context_window）。

async fn record_response_item_and_emit_turn_item(
        &self,
        turn_context: &TurnContext,
        response_item: ResponseItem,
    )

作用：记录一个模型或系统响应项，并在能解析成 turn item 时发出开始和完成事件。turn item 可以理解为前端展示的一小块对话进度。

数据流：输入是本轮上下文和一个 ResponseItem → 它先写入历史和持久化记录；再尝试解析成 TurnItem；如果成功，就依次发 started 和 completed 事件 → 输出为空。

调用关系：它调用 record_conversation_items 完成记账，再调用 emit_turn_item_started 和 emit_turn_item_completed 通知 UI 生命周期。

调用图：调用 3 个内部函数（emit_turn_item_completed, emit_turn_item_started, record_conversation_items）；外部调用 2 个（parse_turn_item, from_ref）。

async fn record_user_prompt_and_emit_turn_item(
        &self,
        turn_context: &TurnContext,
        input: &[UserInput],
        client_id: Option<String>,
    )

作用：记录用户发来的提示词，并发出前端可展示的用户消息事件。它特别保留 UI 需要的富文本片段，不让它们在转换成历史项时丢掉。

数据流：输入是用户输入列表、本轮上下文和可选客户端消息 id → 它把输入转成 ResponseItem 写入历史；再直接从原始 UserInput 构造 UserMessageItem，附上 client_id，发 started/completed 事件；最后确保 rollout 已经 materialized → 输出为空。

调用关系：它调用 response_item_from_user_input、record_conversation_items、emit_turn_item_started、emit_turn_item_completed 和 ensure_rollout_materialized，是用户消息进入系统的关键记录点。

调用图：调用 6 个内部函数（emit_turn_item_completed, emit_turn_item_started, ensure_rollout_materialized, record_conversation_items, response_item_from_user_input, new）；外部调用 3 个（to_vec, UserMessage, from_ref）。

async fn notify_stream_error(
        &self,
        turn_context: &TurnContext,
        message: impl Into<String>,
        codex_error: CodexErr,
    )

作用：当响应流断开或出错时，向外部发送清楚的错误事件。这样用户不会只看到沉默或卡住。

数据流：输入是本轮上下文、面向用户的错误消息和 CodexErr → 它提取详细错误文本和 HTTP 状态码，包装成 StreamErrorEvent → 通过 send_event 发出。

调用关系：它把底层网络/响应流错误转换成会话事件，供前端或调用方展示和处理。

调用图：调用 2 个内部函数（send_event, http_status_code_value）；外部调用 3 个（into, to_string, StreamError）。

async fn steer_input(
        &self,
        input: Vec<UserInput>,
        additional_context: BTreeMap<String, AdditionalContextEntry>,
        expected_turn_id: Option<&str>,
        client_user_me

作用：在一个普通回合还在运行时，追加用户输入来“ steering（引导）”当前任务。比如模型正在工作，用户又补一句要求，它会把这句放进当前轮输入队列。

数据流：输入是用户输入、附加上下文、期望的 turn_id、客户端消息 id 和可选响应 API 元数据 → 它确认当前有活跃普通任务，检查 turn_id 是否匹配，拒绝空输入；然后合并附加上下文，写入元数据，把附加上下文和用户输入放进 pending input 队列 → 输出当前活跃 turn_id；各种不满足条件会返回 SteerInputError。

调用关系：它直接操作 active_turn、state.additional_context 和 input_queue。它不会自己记录历史，而是把新输入排队给当前活跃 turn 后续消费。

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

async fn record_memory_citation_for_turn(&self, sub_id: &str)

作用：标记某一轮出现过 memory citation，也就是引用过记忆内容。这个标记可用于后续展示或统计。

数据流：输入是 sub_id → 它通过 input_queue 找到对应 turn_state；找不到就结束；找到后把 has_memory_citation 设为 true → 输出为空。

调用关系：它依赖 input_queue 根据 sub_id 找到当前或相关 turn 状态，是一个小的状态标记函数。

async fn interrupt_task(self: &Arc<Self>)

作用：处理中断请求，停止当前正在运行的任务。比如用户按了停止按钮时，就需要走这里。

数据流：没有业务输入 → 它记录日志，检查是否有活跃 turn，然后调用 abort_all_tasks 以 Interrupted 原因终止任务；如果本来没有活跃 turn，还会取消 MCP 启动 → 输出为空。

调用关系：它是会话中断入口，会把实际停止工作交给 abort_all_tasks，并在空闲但 MCP 正启动时调用 cancel_mcp_startup。

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

fn hooks(&self) -> Arc<Hooks>

作用：读取当前 hooks 配置对象。hooks 可以理解为某些时机自动运行的外部脚本或插件回调。

数据流：没有业务输入 → 它从 services 中加载 hooks 的 Arc 指针 → 输出 Hooks 的共享引用。

调用关系：它是会话访问 hook 系统的简单入口；build_hooks_for_config 负责构造 Hooks。

fn user_shell(&self) -> Arc<shell::Shell>

作用：返回用户 shell 配置。shell 就是运行命令时使用的命令解释器，比如 bash、zsh 或类似环境。

数据流：没有业务输入 → 它克隆 services.user_shell 的 Arc → 输出共享的 Shell 对象。

调用关系：build_initial_context 和 build_settings_update_items 会用它把环境信息写进模型上下文。

调用图：被 2 处调用（build_initial_context, build_settings_update_items）；外部调用 1 个（clone）。

async fn current_rollout_path(&self) -> anyhow::Result<Option<PathBuf>>

作用：查询当前会话流水账文件在本地的路径。这个路径可给 hook 或外部工具读取 transcript。

数据流：没有业务输入 → 它先找 live_thread；没有则返回 Ok(None)；有则询问 local_rollout_path 并把错误转成 anyhow 错误 → 输出可选 PathBuf。

调用关系：hook_transcript_path 会调用它，并在需要前先确保 rollout 已经落地。

调用图：调用 1 个内部函数（live_thread）；被 1 处调用（hook_transcript_path）。

async fn hook_transcript_path(&self) -> Option<PathBuf>

作用：给 hook 系统准备 transcript 文件路径。它先确保会话记录已经实际生成，再返回路径。

数据流：没有业务输入 → 它调用 ensure_rollout_materialized，然后调用 current_rollout_path；成功就返回路径，失败就警告并返回 None → 输出可选 PathBuf。

调用关系：它是 hooks 获取会话记录位置的安全包装，避免 hook 去读一个还没生成的文件。

调用图：调用 2 个内部函数（current_rollout_path, ensure_rollout_materialized）；外部调用 1 个（warn!）。

async fn take_pending_session_start_source(
        &self,
    ) -> Option<codex_hooks::SessionStartSource>

作用：取走并清空待处理的会话开始来源。来源可说明这次启动是普通开始、压缩后继续等。

数据流：没有业务输入 → 它锁住状态并调用 take_pending_session_start_source → 输出可选 SessionStartSource，同时状态中的待处理值被消费掉。

调用关系：replace_compacted_history 和 maybe_start_new_context_window 会设置 Compact 来源；这个函数在后续需要触发 hook 或记录来源时取出来。

fn show_raw_agent_reasoning(&self) -> bool

作用：查询是否允许显示原始代理推理内容。原始推理可能比较敏感，所以由配置控制。

数据流：没有业务输入 → 它读取 services.show_raw_agent_reasoning → 输出布尔值。

调用关系：send_event 会调用它，决定事件发送时是否包含或展示原始推理信息。

调用图：被 1 处调用（send_event）。

fn emit_subagent_session_started(
    analytics_events_client: &AnalyticsEventsClient,
    client_metadata: AppServerClientMetadata,
    session_id: SessionId,
    thread_id: ThreadId,
    parent_thre

作用：记录一个子代理线程启动的分析事件。子代理可以理解为主任务派出去帮忙的另一个小助手。

数据流：输入是分析客户端、客户端元数据、会话和线程 id、父线程 id、线程配置和子代理来源 → 它先确认客户端名称和版本都存在；缺少就跳过并警告；存在则生成当前时间，把各种 id 和配置转成字符串，调用 track_subagent_thread_started 上报 → 输出为空。

调用关系：run_codex_thread_interactive 会在启动子代理线程时调用它。它不参与会话业务决策，只负责分析埋点。

调用图：调用 1 个内部函数（track_subagent_thread_started）；被 1 处调用（run_codex_thread_interactive）；外部调用 4 个（now, to_string, to_string, warn!）。

async fn build_hooks_for_config(
    config: &Config,
    plugins_manager: &PluginsManager,
    environment: Option<&TurnEnvironment>,
) -> Hooks

作用：根据配置、插件和当前环境构造 Hooks 对象。它把旧的 notify 命令、插件 hook、shell 参数和信任设置合成一套可执行的 hook 配置。

数据流：输入是 Config、PluginsManager 和可选 TurnEnvironment → 它从环境 shell 推导 hook 执行程序和参数，读取插件配置并加载插件结果，取出插件 hook 来源和警告，然后创建 HooksConfig 并构造 Hooks → 输出 Hooks。

调用关系：refresh_runtime_config 会调用它，在运行时配置刷新时重建 hook 系统。它会向 plugins_manager 查询插件，再把结果交给 Hooks::new。

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

fn cwd(&self) -> &AbsolutePathBuf

作用：返回这个会话默认工作的目录，也就是模型或工具在没有特别指定环境时，会把哪里当作“当前文件夹”。别人需要知道项目根在哪里时会用它。

数据流：进去的是这份会话配置本身 → 它从环境选择配置里取出 legacy_fallback_cwd 这个备用当前目录 → 出来的是一个目录引用，不复制也不修改任何东西。

调用关系：Session::new 启动会话时会用它记录和检查工作目录；apply 更新配置时用它判断目录有没有变；sandbox_policy 用它把权限围栏套到正确目录上；build_effective_session_config 也会拿它生成最终配置。

调用图：被 4 处调用（new, apply, sandbox_policy, build_effective_session_config）。

fn environment_selections(&self) -> &[TurnEnvironmentSelection]

作用：返回这个会话保存的环境选择列表。环境可以理解成“这一轮对话要在哪个工作空间或运行环境里办事”。

数据流：进去的是会话配置 → 它读取 environments 里的 environments 列表 → 出来的是这组环境选择的只读引用，不改变配置。

调用关系：Session::new 会在启动时把这些选择交给环境管理器；resolved_environments_for_configuration 会用它把配置里的选择解析成真正可用的运行环境。

调用图：被 2 处调用（new, resolved_environments_for_configuration）。

fn codex_home(&self) -> &AbsolutePathBuf

作用：返回这个会话存放 Codex 自己状态文件的目录。比如配置、缓存、会话数据等都可能围绕这个目录工作。

数据流：进去的是会话配置 → 它直接取出 codex_home 字段 → 出来的是这个目录的只读引用，没有副作用。

调用关系：这是一个简单的访问口，让其他代码不用直接碰字段；当外部需要知道 Codex 的家目录时，可以从这里拿。

fn permission_profile_state(&self) -> &PermissionProfileState

作用：返回当前权限配置的完整状态。权限配置决定模型和工具能读写哪些文件、能不能联网、当前启用的是哪套权限档案。

数据流：进去的是会话配置 → 它取出 permission_profile_state → 出来的是只读引用，不做计算、不改状态。

调用关系：Session::new 在发出会话配置事件时会间接用到这类权限信息；其他需要查看权限状态的流程通过这个入口保持一致，避免绕过统一规则。

fn permission_profile(&self) -> PermissionProfile

作用：生成当前真正生效的权限档案。它不只是拿原始配置，还会把“项目根目录”这种占位权限换成当前会话里的真实工作区目录。

数据流：进去的是会话配置和里面保存的工作区根目录列表 → 它先从 permission_profile_state 取出权限档案，再把其中的项目根占位符替换成 workspace_roots → 出来的是一份可直接执行的权限档案副本。

调用关系：Session::new 用它告诉前端和网络代理当前权限；sandbox_policy、file_system_sandbox_policy、thread_config_snapshot、build_per_turn_config、make_turn_context、new_turn_context_from_configuration 都会用它，保证每一轮执行看到的是同一套权限解释。

调用图：调用 1 个内部函数（permission_profile）；被 7 处调用（new, file_system_sandbox_policy, sandbox_policy, thread_config_snapshot, build_per_turn_config, make_turn_context, new_turn_context_from_configuration）。

fn active_permission_profile(&self) -> Option<ActivePermissionProfile>

作用：返回当前正在使用的命名权限档案，如果有的话。它回答的是“用户现在选中的是哪套权限模板”。

数据流：进去的是会话配置 → 它向 permission_profile_state 查询活动权限档案 → 出来的是一个可选结果；没有活动档案时就是空。

调用关系：Session::new 会把这个信息发给界面；thread_config_snapshot 也会把它放进线程配置快照，方便恢复或展示当前权限来源。

调用图：调用 1 个内部函数（active_permission_profile）；被 2 处调用（new, thread_config_snapshot）。

fn profile_workspace_roots(&self) -> &[AbsolutePathBuf]

作用：返回权限档案自己声明的工作区根目录列表。它用于说明某套权限模板本来想绑定到哪些项目目录。

数据流：进去的是会话配置 → 它从 permission_profile_state 读取 profile_workspace_roots → 出来的是目录列表引用，不修改内容。

调用关系：thread_config_snapshot 会把这些目录写进快照，让外部看到权限档案和工作区之间的对应关系。

调用图：调用 1 个内部函数（profile_workspace_roots）；被 1 处调用（thread_config_snapshot）。

fn apply_permission_profile_to_permissions(
        &self,
        permissions: &mut crate::config::Permissions,
    )

作用：把会话当前的权限档案状态写进另一份 Permissions 配置里。这样按轮次生成配置时，不会丢掉会话里已经调整过的权限。

数据流：进去的是会话配置和一份可修改的 Permissions → 它复制当前 permission_profile_state，并调用目标对象的设置方法 → 出来时目标 Permissions 已经带上同一份权限状态，函数本身不返回值。

调用关系：build_per_turn_config 会调用它，把线程级别的权限同步到每一轮实际执行用的配置中。它把“会话配置”这边的决定传给“执行配置”那边。

调用图：调用 1 个内部函数（set_permission_profile_state）；被 1 处调用（build_per_turn_config）；外部调用 1 个（clone）。

fn set_permission_profile_for_tests(
        &mut self,
        permission_profile: PermissionProfile,
    ) -> ConstraintResult<()>

作用：这是测试专用入口，用来强行给会话配置设置一套旧格式的权限档案。正常运行代码不会依赖它。

数据流：进去的是可修改的会话配置和一份权限档案 → 它把这份档案交给 permission_profile_state 的旧格式设置方法 → 出来的是成功或约束错误；成功时配置里的权限状态被改掉。

调用关系：它只在测试编译时存在，方便测试代码快速搭出某种权限场景，而不用走完整的用户配置流程。

调用图：调用 1 个内部函数（set_legacy_permission_profile）。

fn sandbox_policy(&self) -> SandboxPolicy

作用：把当前权限档案转换成旧接口能理解的沙箱策略。沙箱策略就是“安全围栏说明书”，告诉执行命令时哪些地方可以碰、哪些不可以。

数据流：进去的是会话配置 → 它先拿到当前 permission_profile，再读取 cwd 作为目录参照，然后调用兼容转换函数 → 出来的是一份 SandboxPolicy，不改原配置。

调用关系：apply 更新配置时会用它比较旧沙箱和新权限之间的关系；Session::new 也会通过它记录启动时的权限信息。它是新权限系统和旧沙箱接口之间的桥。

调用图：调用 2 个内部函数（cwd, permission_profile）；被 1 处调用（apply）；外部调用 1 个（compatibility_sandbox_policy_for_permission_profile）。

fn file_system_sandbox_policy(&self) -> FileSystemSandboxPolicy

作用：取出当前文件系统层面的安全规则，也就是哪些文件夹能读、哪些能写、哪些要禁止。

数据流：进去的是会话配置 → 它先生成当前 permission_profile，再从里面取文件系统沙箱策略 → 出来的是 FileSystemSandboxPolicy。

调用关系：apply 会用它判断权限更新时是否需要重新计算文件访问规则，尤其是在工作目录变化时避免把可写范围指到错误地方。

调用图：调用 1 个内部函数（permission_profile）；被 1 处调用（apply）。

fn network_sandbox_policy(&self) -> NetworkSandboxPolicy

作用：取出当前网络访问规则，也就是工具能不能联网、能访问哪些网络资源。

数据流：进去的是会话配置 → 它从 permission_profile_state 的原始权限档案中读取网络沙箱策略 → 出来的是 NetworkSandboxPolicy，不改变配置。

调用关系：apply 在处理权限或旧沙箱更新时会用它保留现有网络规则，防止只改目录时把联网设置意外重置。

调用图：调用 1 个内部函数（permission_profile）；被 1 处调用（apply）。

fn thread_config_snapshot(&self) -> ThreadConfigSnapshot

作用：把当前会话配置打包成一张“线程配置快照”。快照就像拍照，方便界面展示、日志记录或后续恢复时知道当时的设置。

数据流：进去的是会话配置 → 它收集模型、服务档位、审批策略、权限档案、环境、工作区、推理强度、人格偏好、线程来源等信息 → 出来的是 ThreadConfigSnapshot；原配置不变。

调用关系：它会调用 permission_profile、active_permission_profile、profile_workspace_roots 等小入口，把分散字段整理成一个完整视图。需要向外报告线程当前配置时，会用这个快照。

调用图：调用 6 个内部函数（value, active_permission_profile, permission_profile, profile_workspace_roots, model, reasoning_effort）；外部调用 3 个（clone, clone, clone）。

fn apply(&self, updates: &SessionSettingsUpdate) -> ConstraintResult<Self>

作用：根据一份更新请求，生成一份新的会话配置。它像“改配置的安全柜台”，负责检查哪些能改、怎么改，以及权限变化会不会破坏安全边界。

数据流：进去的是当前配置和 SessionSettingsUpdate → 它先复制当前配置，再逐项应用模型模式、摘要、服务档位、人格、审批、Windows 沙箱、环境、工作区、权限档案、旧沙箱和客户端信息等更新；遇到不合法约束就返回错误 → 出来的是新的 SessionConfiguration，原来的配置保持不动。

调用关系：它内部会调用 cwd、sandbox_policy、file_system_sandbox_policy、network_sandbox_policy 和 set_permission_profile_projection 等方法。它位于“用户或客户端想改设置”和“会话真正采用新设置”之间，负责把变更变成安全一致的新配置。

调用图：调用 10 个内部函数（active, cwd, file_system_sandbox_policy, network_sandbox_policy, sandbox_policy, from_request_value, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_preserving_deny_entries, from）；外部调用 2 个（new, with_capacity）。

fn set_permission_profile_projection(
        &mut self,
        permission_profile: PermissionProfile,
        active_permission_profile: Option<ActivePermissionProfile>,
        profile_workspace_ro

作用：把一份高层权限档案翻译成运行时真正使用的文件和网络规则，并写回配置状态。它负责让“权限模板”落地成能执行的安全规则。

数据流：进去的是可修改的会话配置、一份权限档案、可选的活动权限档案、工作区根目录，以及可选的旧文件规则 → 它提取执行强度，拆出文件和网络规则，必要时保留原有的拒绝读取限制，再组装成权限快照 → 出来的是成功或错误；成功时 permission_profile_state 被更新。

调用关系：apply 在用户显式更新 permission_profile 时调用它。它把权限更新里最容易出错的翻译工作集中到一处，避免外面直接改多个字段导致不一致。

调用图：调用 6 个内部函数（active_with_profile_workspace_roots, legacy, set_permission_profile_snapshot, enforcement, from_runtime_permissions_with_enforcement, to_runtime_permissions）。

async fn warm_plugins_and_skills_for_session_init(
    config: Arc<Config>,
    plugins_manager: Arc<PluginsManager>,
    skills_manager: Arc<SkillsManager>,
    turn_environments: &TurnEnvironmentSna

作用：在会话刚启动时提前加载插件和技能，并收集加载失败的信息。这样用户真正开始用工具时，很多准备工作已经做完，出错也能早点暴露。

数据流：进去的是配置、插件管理器、技能管理器和当前环境快照 → 它取主文件系统，按配置找出可用插件，再根据插件带来的技能目录加载技能 → 出来的是技能加载错误列表；插件和技能管理器内部可能完成缓存或预热。

调用关系：Session::new 在启动流程中调用它，并把失败的技能加载记录到日志里。它是会话启动阶段“准备扩展能力”的一环。

调用图：调用 1 个内部函数（primary_filesystem）；被 1 处调用（new）。

fn thread_id(&self) -> ThreadId

作用：返回这个会话对应的具体线程编号。线程可以理解成一条具体对话线，恢复历史或区分子任务时都靠它识别。

数据流：进去的是 Session → 它直接读取 thread_id 字段 → 出来的是 ThreadId 值，不修改会话。

调用关系：这是给其他模块查身份用的小入口。需要知道“当前这条对话线是谁”时，可以调用它，而不用直接访问字段。

fn session_id(&self) -> SessionId

作用：返回根线程和它的子线程共同使用的会话编号。它比 thread_id 更像“一整组相关对话”的总编号。

数据流：进去的是 Session → 它向 services.agent_control 查询 session_id → 出来的是 SessionId，不改变状态。

调用关系：Session::new 会在建立 agent_control 时安排好这个编号；之后外部需要按整组会话归类事件、子代理或控制关系时，会通过这个方法拿到统一身份。

async fn new(
        mut session_configuration: SessionConfiguration,
        config: Arc<Config>,
        user_instructions: Option<codex_extension_api::UserInstructions>,
        installation_id: S

作用：创建并启动一个完整会话。它不是简单分配一个对象，而是把历史、认证、环境、权限、插件、MCP 工具、网络代理、遥测和前端事件都一起准备好。

数据流：进去的是会话配置、全局配置、用户说明、认证管理器、模型管理器、执行策略、事件通道、历史来源、插件和技能管理器、MCP 管理器、扩展、环境管理器、线程存储、追踪信息等大量启动材料 → 它并行做线程持久化、状态库读取、认证和 MCP 配置准备，然后选择线程编号，加载项目说明，预热插件技能，检查配置锁，启动网络代理，创建服务集合和 Session 对象，发出 SessionConfigured 事件，安装 MCP 连接管理器，记录初始历史 → 出来的是 Arc<Session>；如果中途失败，会丢弃未提交的线程初始化，避免留下半成品状态。

调用关系：spawn_internal、测试辅助创建函数和相关测试会调用它来真正开会话。它会把许多具体工作交给别的模块，比如 LiveThread 创建或恢复历史、ModelClient 建模型客户端、McpConnectionManager 启动工具连接、warm_plugins_and_skills_for_session_init 预热技能。它是本文件最核心的启动编排器。

调用图：调用 34 个内部函数（new, new, new_uninitialized_with_permission_profile, new, new, session_id, with_session_id, new, new, new (+15 more)）；被 4 处调用（spawn_internal, 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）；外部调用 39 个（clone, downgrade, new, new, pin, new, default, default, default, new (+15 more)）。

fn new() -> Self

作用：创建一个空的输入队列。新会话开始时需要它来保存之后到来的用户输入和代理消息。

数据流：进去不需要任何参数 → 它建立一个活动通知通道，默认状态是“邮箱活动”，再准备一个空的邮箱消息队列 → 出来一个可以被会话共享使用的 InputQueue。

调用关系：它是整个输入队列的起点。测试代码和会话创建流程会先调用它，之后其他函数才会往里面放消息、订阅通知或取走输入。

调用图：被 8 处调用（input_queue_drains_mailbox_in_delivery_order, input_queue_notifies_mailbox_subscribers, input_queue_notifies_steer_subscribers, input_queue_reports_already_pending_steer, input_queue_tracks_pending_trigger_turn_mail, new, make_session_and_context, make_session_and_context_with_auth_config_home_and_rx）；外部调用 3 个（new, new, channel）。

async fn subscribe_activity(
        &self,
        turn_state: Option<&Mutex<TurnState>>,
    ) -> (
        watch::Receiver<InputQueueActivity>,
        Option<InputQueueActivity>,
    )

作用：让外部监听这个输入队列的“新动静”。它还会顺手告诉调用者：现在是不是已经有没处理的用户引导或邮箱消息。

数据流：进去一个可选的当前轮状态 → 它先创建一个监听器，再检查当前轮里有没有用户输入；如果没有，再检查邮箱队列有没有消息 → 出来一个监听器，以及一个可选的当前待处理活动类型。

调用关系：它会调用 InputQueue::has_pending_mailbox_items 来判断邮箱是否已有积压。外部调度流程可以用它决定是继续睡眠，还是马上处理已有输入。

调用图：调用 1 个内部函数（has_pending_mailbox_items）；外部调用 1 个（subscribe）。

async fn enqueue_mailbox_communication(
        &self,
        communication: InterAgentCommunication,
    )

作用：把一封代理之间的通信消息放进邮箱队列。这样消息不会丢，稍后会按顺序交给会话处理。

数据流：进去一条 InterAgentCommunication，也就是代理发给代理的消息 → 它拿锁打开邮箱队列，把消息追加到队尾，然后发出“邮箱有活动”的通知 → 队列变长，监听者会被提醒。

调用关系：它是邮箱消息进入 InputQueue 的入口。放入消息后，它通过通知通道提醒订阅者，后续通常由检查或取输入的流程把这些消息交给当前轮。

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

async fn has_pending_mailbox_items(&self) -> bool

作用：快速回答一个问题：邮箱里现在有没有还没处理的消息。

数据流：进去不需要额外数据，只读取内部邮箱队列 → 它拿锁查看队列是否为空 → 出来 true 或 false，不改动队列。

调用关系：InputQueue::subscribe_activity 和 InputQueue::has_pending_input 会用它做判断：如果没有当前轮输入，但邮箱里有东西，就说明系统仍然有活要干。

调用图：被 2 处调用（has_pending_input, subscribe_activity）。

async fn has_trigger_turn_mailbox_items(&self) -> bool

作用：检查邮箱里有没有会“唤醒一轮对话”的消息。有些代理邮件只是普通信息，有些则明确要求触发处理。

数据流：进去不需要参数，只读取邮箱队列 → 它逐封查看消息的 trigger_turn 标记 → 只要发现一封需要触发轮次的邮件，就返回 true，否则返回 false。

调用关系：调用图里没有显示它调用本文件其他函数。它通常作为调度判断用：决定邮箱消息是否强到需要启动或唤醒一轮处理。

async fn drain_mailbox_input_items(&self) -> Vec<TurnInput>

作用：一次性取走邮箱里所有待处理消息，并把它们包装成当前轮可处理的输入。

数据流：进去不需要参数，只操作内部邮箱队列 → 它拿锁把队列从头到尾清空，每封代理邮件都变成 TurnInput::InterAgentCommunication → 出来一个按原顺序排列的输入列表，邮箱队列被清空。

调用关系：InputQueue::get_pending_input 会调用它。当当前轮允许接收邮箱消息时，get_pending_input 会把这些邮件和当前轮已有输入合并后交出去。

调用图：被 1 处调用（get_pending_input）。

async fn turn_state_for_sub_id(
        &self,
        active_turn: &Mutex<Option<ActiveTurn>>,
        sub_id: &str,
    ) -> Option<Arc<Mutex<TurnState>>>

作用：根据一个子会话 ID 找到当前活动轮次的状态。这样只有匹配的那一轮才会被改动，避免改错对象。

数据流：进去当前活动轮的共享容器和一个 sub_id → 它拿锁查看当前是否有活动轮，再比较活动轮任务里的 sub_id 是否一致 → 如果匹配，出来当前轮状态的共享引用；不匹配或没有活动轮就出来 None。

调用关系：InputQueue::defer_mailbox_delivery_to_next_turn 和 InputQueue::accept_mailbox_delivery_for_current_turn 都先调用它定位正确的 TurnState，然后才改变邮箱投递策略。

调用图：被 2 处调用（accept_mailbox_delivery_for_current_turn, defer_mailbox_delivery_to_next_turn）。

async fn clear_pending(&self, active_turn: &ActiveTurn)

作用：清掉当前轮里还没处理的等待者和输入。通常用于一轮被取消、结束或需要重置时，避免旧东西影响后续处理。

数据流：进去一个当前活动轮 → 它锁住该轮状态，清空等待中的唤醒点，再清空当前轮 pending_input 里的所有输入 → 出来没有返回值，但当前轮的积压内容被清干净。

调用关系：调用图里没有显示它调用本文件其他函数。它直接操作 TurnState，属于清理当前轮内部状态的工具。

async fn defer_mailbox_delivery_to_next_turn(
        &self,
        active_turn: &Mutex<Option<ActiveTurn>>,
        sub_id: &str,
    )

作用：把邮箱消息的投递推迟到下一轮。这样当前轮如果不适合被代理邮件打断，就不会被强行插入新消息。

数据流：进去当前活动轮容器和 sub_id → 它先用 InputQueue::turn_state_for_sub_id 找到匹配的轮状态；如果找不到就什么也不做；如果当前轮已经有待处理输入，也不改；否则把邮箱投递阶段设成“下一轮” → 当前轮会暂时拒收邮箱消息。

调用关系：它依赖 InputQueue::turn_state_for_sub_id 防止改错轮次。它本身不取走邮箱消息，只改变 TurnState 里的投递策略，让之后的取输入流程按这个策略办。

调用图：调用 1 个内部函数（turn_state_for_sub_id）。

async fn accept_mailbox_delivery_for_current_turn(
        &self,
        active_turn: &Mutex<Option<ActiveTurn>>,
        sub_id: &str,
    )

作用：允许当前这一轮接收邮箱消息。之前被推迟的邮箱投递，可以通过它重新打开。

数据流：进去当前活动轮容器和 sub_id → 它先找到匹配的轮状态；找不到就返回；找到后把工作交给 InputQueue::accept_mailbox_delivery_for_turn_state → 对应轮次的邮箱投递许可被打开。

调用关系：它先调用 InputQueue::turn_state_for_sub_id 定位轮次，再调用 InputQueue::accept_mailbox_delivery_for_turn_state 做实际修改。它是按 sub_id 操作当前轮的安全入口。

调用图：调用 2 个内部函数（accept_mailbox_delivery_for_turn_state, turn_state_for_sub_id）。

async fn accept_mailbox_delivery_for_turn_state(
        &self,
        turn_state: &Mutex<TurnState>,
    )

作用：直接把某个 TurnState 设置为“本轮可以收邮箱消息”。这是更底层的版本，调用者已经拿到了具体轮状态。

数据流：进去一个 TurnState 的锁 → 它锁住状态并调用状态自己的接受邮箱投递方法 → 出来没有返回值，但该轮的邮箱投递标记被更新。

调用关系：InputQueue::accept_mailbox_delivery_for_current_turn 会调用它。它不负责找是哪一轮，只负责对已经给定的 TurnState 执行修改。

调用图：被 1 处调用（accept_mailbox_delivery_for_current_turn）。

async fn extend_pending_input_and_accept_mailbox_delivery_for_turn_state(
        &self,
        turn_state: &Mutex<TurnState>,
        input: Vec<TurnInput>,
    )

作用：给某一轮追加待处理输入，并同时允许这一轮接收邮箱消息。常见场景是用户又发来了引导内容，需要马上提醒系统处理。

数据流：进去一个 TurnState 和一批 TurnInput → 它锁住轮状态，把这批输入追加到 pending_input 后面，再打开本轮邮箱投递许可；解锁后发送“用户引导有活动”的通知 → 当前轮多了新输入，监听者也会收到提醒。

调用关系：测试里用它验证 Steer 通知。它会通过通知通道发出 InputQueueActivity::Steer，让订阅者知道现在不是普通邮箱消息，而是有用户侧输入需要处理。

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

async fn extend_pending_input_for_turn_state(
        &self,
        turn_state: &Mutex<TurnState>,
        input: Vec<TurnInput>,
    )

作用：只给某一轮追加待处理输入，不额外发送活动通知，也不改变邮箱投递许可。

数据流：进去一个 TurnState 和一批 TurnInput → 它锁住轮状态，把输入追加到 pending_input 队尾 → 出来没有返回值，但该轮的待处理输入变多。

调用关系：调用图里没有显示它调用本文件其他函数。它适合那些调用者自己会处理通知或投递策略、这里只想安静地塞入输入的场景。

async fn take_pending_input_for_turn_state(
        &self,
        turn_state: &Mutex<TurnState>,
    ) -> Vec<TurnInput>

作用：把某一轮已经排队的输入全部取走。取走后，这些输入就不再留在该轮队列里。

数据流：进去一个 TurnState → 它锁住状态，把 pending_input.items 从开头整体切出来 → 出来这批 TurnInput，原来的 pending_input 变为空。

调用关系：调用图里没有显示它调用本文件其他函数。它是一个针对指定 TurnState 的低层取件方法，和 InputQueue::get_pending_input 相比，它不自动合并邮箱消息。

async fn get_pending_input(
        &self,
        active_turn: &Mutex<Option<ActiveTurn>>,
    ) -> Vec<TurnInput>

作用：取出现在应该交给处理流程的所有输入。它会同时考虑当前轮自己的输入，以及当前轮是否允许接收邮箱消息。

数据流：进去当前活动轮容器 → 它先在一个受锁保护的步骤里取走当前轮 pending_input，并读取本轮是否允许收邮箱；如果不允许，就只返回当前轮输入；如果允许，就再清空邮箱队列，把邮箱消息接到后面 → 出来一批要处理的 TurnInput，相关队列里的这些内容被移走。

调用关系：它会调用 InputQueue::drain_mailbox_input_items 来取邮箱消息。它是输入真正从队列流向会话处理流程的关键出口。

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

async fn has_pending_input(&self, active_turn: &Mutex<Option<ActiveTurn>>) -> bool

作用：判断当前是否有任何输入值得处理。它会同时看当前轮输入和邮箱消息，但会尊重当前轮是否允许收邮箱。

数据流：进去当前活动轮容器 → 它先看当前轮 pending_input 是否为空，并读取本轮邮箱投递许可；如果当前轮已有输入，直接返回 true；如果不允许收邮箱，返回 false；否则再检查邮箱队列 → 出来 true 或 false，不取走任何输入。

调用关系：它会调用 InputQueue::has_pending_mailbox_items。调度器可以先用它做轻量检查，确认有活之后再调用 InputQueue::get_pending_input 真正取走内容。

调用图：调用 1 个内部函数（has_pending_mailbox_items）。

fn has_user_input(&self) -> bool

作用：检查当前轮待处理输入里有没有真正来自用户的输入。这个判断用来区分“用户引导”和普通代理邮件。

数据流：进去不需要参数，只读取当前 TurnInputQueue 的 items → 它逐项查看是否有 TurnInput::UserInput → 有就返回 true，没有就返回 false，队列内容不变。

调用关系：InputQueue::subscribe_activity 会通过当前轮状态里的 pending_input 使用它。如果发现已有用户输入，订阅者会立即得到 Steer 这种活动提示。

fn make_mail(
        author: AgentPath,
        recipient: AgentPath,
        content: &str,
        trigger_turn: bool,
    ) -> InterAgentCommunication

作用：测试用的小工厂函数，用来快速造一封代理之间的消息。这样每个测试不用重复写一大段创建邮件的代码。

数据流：进去作者路径、收件人路径、正文和是否触发轮次的标记 → 它把正文转成字符串，并调用 InterAgentCommunication 的创建方法 → 出来一封可放进邮箱队列的测试邮件。

调用关系：多个测试会调用它来准备邮箱消息。它让测试重点放在队列行为上，而不是放在怎么构造消息对象上。

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

async fn input_queue_notifies_mailbox_subscribers()

作用：验证邮箱收到新消息时，订阅者真的会被通知。没有这个保证，外部调度器可能不知道有新邮件到了。

数据流：进去没有外部输入 → 测试创建 InputQueue 并订阅活动，确认一开始没有待处理活动；随后构造并放入两封邮箱消息；最后等待通知并检查通知类型 → 测试通过表示邮箱活动能正确广播。

调用关系：它调用 InputQueue::new 创建队列，并使用 tests::make_mail 准备消息。它覆盖的是 InputQueue::enqueue_mailbox_communication 发出 Mailbox 通知这条路径。

调用图：调用 3 个内部函数（new, root, try_from）；外部调用 2 个（assert_eq!, make_mail）。

async fn input_queue_notifies_steer_subscribers()

作用：验证给当前轮追加用户输入时，订阅者会收到“用户引导”通知。这样系统能优先知道用户又插话或补充要求了。

数据流：进去没有外部输入 → 测试创建队列和默认 TurnState，先订阅活动；然后追加一条用户文本输入；最后等待通知并确认类型是 Steer → 测试通过表示用户侧输入能正确唤醒监听者。

调用关系：它调用 InputQueue::new 和 TurnState 的默认构造，并通过 InputQueue::extend_pending_input_and_accept_mailbox_delivery_for_turn_state 触发通知。

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

async fn input_queue_reports_already_pending_steer()

作用：验证如果订阅前已经有用户输入积压，订阅时也能立刻看见这个事实。这样监听者不会错过早到的输入。

数据流：进去没有外部输入 → 测试先创建队列和轮状态，再提前塞入一条用户输入；之后才订阅活动；最后检查返回的 pending_activity 是 Steer → 测试通过表示旧积压也会被报告。

调用关系：它调用 InputQueue::new，并用 InputQueue::extend_pending_input_and_accept_mailbox_delivery_for_turn_state 先制造积压，再检查 InputQueue::subscribe_activity 的即时判断。

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

async fn input_queue_drains_mailbox_in_delivery_order()

作用：验证邮箱消息被取出时保持原来的投递顺序，并且取完后邮箱会变空。顺序错了，代理之间的对话就可能乱套。

数据流：进去没有外部输入 → 测试创建两封不同方向的邮件，按顺序放入队列；然后一次性取走邮箱输入；最后比较取出的列表顺序，并确认邮箱已空 → 测试通过表示 drain 行为正确。

调用关系：它调用 InputQueue::new 和 tests::make_mail 准备场景，重点覆盖 InputQueue::drain_mailbox_input_items 的顺序和清空效果。

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

async fn input_queue_tracks_pending_trigger_turn_mail()

作用：验证队列能分辨邮箱里是否有“需要触发一轮处理”的邮件。这关系到系统该不该被一封邮件唤醒。

数据流：进去没有外部输入 → 测试先放入一封不触发轮次的邮件，确认检查结果为 false；再放入一封 trigger_turn 为 true 的邮件，确认检查结果变成 true → 测试通过表示触发标记能被正确发现。

调用关系：它调用 InputQueue::new 和 tests::make_mail 构造两种邮件，重点覆盖 InputQueue::has_trigger_turn_mailbox_items 的判断。

调用图：调用 3 个内部函数（new, root, try_from）；外部调用 2 个（assert!, make_mail）。

async fn inject_if_running(
        &self,
        input: Vec<ResponseItem>,
    ) -> Result<(), Vec<ResponseItem>>

作用：这个函数尝试把一批新消息塞进当前正在运行的会话轮次里。它不会自己开新任务；如果现在没有正在运行的轮次，就把原消息退回给调用者。

数据流：进去的是一组 ResponseItem。函数先拿到 active_turn 这把锁，看当前有没有活跃轮次；有的话，就把这些消息包装成 TurnInput，追加到这个轮次对应的输入队列里，然后返回成功。没有活跃轮次时，它什么也不改，把原来的消息作为错误结果返回，表示“没人可塞”。

调用关系：它是“能塞就塞”的基础工具。Session::inject_no_new_turn 会先调用它：如果成功，事情结束；如果失败，inject_no_new_turn 再改走“只记录、不启动”的路线。

调用图：被 1 处调用（inject_no_new_turn）。

async fn try_start_turn_if_idle(
        self: &Arc<Self>,
        input: Vec<ResponseItem>,
    ) -> Result<(), TryStartTurnIfIdleError>

作用：这个函数是在系统空闲时，尝试为后台或扩展发来的内容新开一轮普通工作。它像一个门卫：只有确认没有用户排队、没有任务在跑、也不是 Plan 模式，才允许开工。

数据流：进去的是一组要处理的 ResponseItem。函数先过滤空输入；再检查输入队列里有没有用户或客户端触发的新轮次、当前协作模式是不是 Plan、当前是否已有活跃任务。都没问题时，它会先“预占”一个空的活跃轮次，创建新的轮次上下文和唯一子 ID，再反复检查中途有没有更高优先级的用户工作插进来。最后确认预占还有效后，把输入放进该轮次队列，创建 RegularTask 并启动任务。若任何检查失败，它会返回带原因和原输入的错误，必要时清掉刚才的预占位置。

调用关系：它是扩展发起“空闲时自动做点事”的共同入口。过程中它会创建错误对象、生成新的 UUID、创建普通任务，并在发现抢占或模式变化时调用 Session::clear_reserved_idle_turn 把临时占位撤掉，避免留下一个看似忙碌但其实没任务的会话。

调用图：调用 3 个内部函数（new, clear_reserved_idle_turn, new）；外部调用 3 个（clone, new, new_v4）。

async fn clear_reserved_idle_turn(&self, turn_state: &Arc<tokio::sync::Mutex<TurnState>>)

作用：这个函数专门清理 try_start_turn_if_idle 预先占住、但后来发现不能用的空闲轮次。它防止系统误以为还有一个任务正在准备执行。

数据流：进去的是一个 turn_state，也就是要核对的轮次状态指针。函数拿到 active_turn 锁后，只在三个条件都满足时清空它：当前确实有活跃轮次、这个轮次还没有真正启动任务、它的状态对象和传进来的正是同一个。判断“是不是同一个”用的是指针相等，也就是确认不是长得像，而是同一份对象。

调用关系：它只服务于 Session::try_start_turn_if_idle。try_start_turn_if_idle 在发现用户工作插队、进入 Plan 模式、或者预占位置被别人改动时，会请它收拾现场。

调用图：被 1 处调用（try_start_turn_if_idle）；外部调用 1 个（ptr_eq）。

async fn inject_no_new_turn(
        &self,
        items: Vec<ResponseItem>,
        current_turn_context: Option<&TurnContext>,
    )

作用：这个函数用于接收一些消息，但明确保证不会因此启动新一轮工作。能塞进正在跑的任务就塞；塞不进去就只写进会话记录里。

数据流：进去的是一组 ResponseItem，以及可选的当前轮次上下文。它先调用 Session::inject_if_running；如果当前有活跃轮次，消息进入该轮次输入队列，函数结束。如果没有活跃轮次，它会使用传入的上下文；没有传入时就临时创建一个默认上下文，然后把这些消息记录到对话历史里，不启动任务。

调用关系：它是“只注入或记录，不开新活”的安全入口。它把第一步交给 Session::inject_if_running，失败后自己负责找一个合适的 TurnContext，再调用会话记录能力保存内容。

调用图：调用 1 个内部函数（inject_if_running）。

async fn install_mcp_connection_manager(
        &self,
        manager: McpConnectionManager,
    ) -> Result<()>

作用：把新的 MCP 连接管理器装进当前会话里，并确认必须连接的 MCP 服务器都能用。这样会话启动阶段需要外部工具时，能通过正确的管理器去连接，而不是用旧的或空的状态。

数据流：输入是一个新的 McpConnectionManager。函数先用 Arc::new 之类的共享包装把它变成可被多处安全持有的对象，再替换掉 SessionServices 里当前保存的 MCP 管理器。随后它读取刚装进去的管理器，让它检查必需服务器；如果检查通过，返回成功；如果服务器缺失或不可用，就返回错误。

调用关系：它通常在会话启动、重新配置 MCP，或准备外部工具连接时由上层启动流程调用。它先把管理器放进会话共享状态，再把后续检查交给这个管理器自己完成；这样其他同时启动的步骤如果需要 MCP，也能拿到同一份最新的连接管理器。

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

fn new(session_configuration: SessionConfiguration) -> Self

作用：创建一份全新的会话状态。新会话开始时需要一个干净但完整的“总账”，这里会把历史、自动压缩窗口、集合和队列都准备好。

数据流：进去的是会话配置；函数用它填入 session_configuration，并新建空历史、空权限表、空连接器集合、空待处理启动来源队列等；出来的是一个 SessionState，其中 next_turn_is_first 被设为 true，表示下一轮是第一轮。

调用关系：它是会话状态的起点，会被会话创建流程和多处测试使用，例如 make_session_and_context、带认证配置的创建流程，以及检查速率限制、连接器选择、替换历史等行为的测试。它内部把初始化工作交给 ContextManager、AutoCompactWindow 和标准集合的 new/default。

调用图：调用 2 个内部函数（new, new）；被 12 处调用（new, make_session_and_context, make_session_and_context_with_auth_config_home_and_rx, set_rate_limits_retains_previous_credits, set_rate_limits_updates_plan_type_when_present, clear_connector_selection_removes_entries, merge_connector_selection_deduplicates_entries, replace_history_clears_auto_compact_window_prefill, set_rate_limits_carries_account_metadata_from_codex_to_codex_other, set_rate_limits_defaults_limit_id_to_codex_when_missing (+2 more)）；外部调用 4 个（new, new, new, default）。

fn record_items(&mut self, items: I, policy: TruncationPolicy)

作用：把新的模型回复或会话条目记进历史。这样后续对话才能知道前面发生过什么。

数据流：进去的是一批 ResponseItem 和一个截断策略；函数把这些交给 history.record_items，由历史管理器按策略保存或裁剪；出来没有单独返回值，但会话历史被更新了。

调用关系：它是外部流程写入聊天历史的入口，自己不判断怎么裁剪，而是把具体保存工作交给 ContextManager 的 record_items。

调用图：调用 1 个内部函数（record_items）。

fn previous_turn_settings(&self) -> Option<PreviousTurnSettings>

作用：取出上一轮普通用户请求使用过的设置。后续轮次可以沿用这些设置，避免恢复会话或压缩上下文后忘记模型相关选择。

数据流：进去不需要参数；函数读取 previous_turn_settings，并复制一份返回；原状态不变。

调用关系：会话流程在准备下一轮请求时会查它，用来知道上一轮的模型或实时处理设置。

fn set_previous_turn_settings(
        &mut self,
        previous_turn_settings: Option<PreviousTurnSettings>,
    )

作用：保存上一轮普通用户请求的设置。它相当于给下一轮留一张便签。

数据流：进去的是一个可能存在的 PreviousTurnSettings；函数直接覆盖状态里的 previous_turn_settings；出来没有返回值，但这份设置会留给之后读取。

调用关系：通常在一轮用户请求确定设置后调用，之后 previous_turn_settings 会把它读出来给后续轮次使用。

fn set_next_turn_is_first(&mut self, value: bool)

作用：手动设置“下一轮是不是第一轮”的标记。某些恢复或重置场景需要重新校准这个判断。

数据流：进去的是 true 或 false；函数把 next_turn_is_first 改成这个值；出来没有返回值。

调用关系：它给会话控制流程提供一个开关，后续 take_next_turn_is_first 会读取并消费这个标记。

fn take_next_turn_is_first(&mut self) -> bool

作用：询问下一轮是否是第一轮，并且问完就把标记清掉。它像一次性门票，用过后就不能再当第一轮。

数据流：进去不需要参数；函数先读出 next_turn_is_first，然后把它设为 false；返回刚才读到的值。

调用关系：会话开始处理用户轮次时会用它判断是否要执行第一轮专属行为。它和 set_next_turn_is_first 配合，一个设置标记，一个消费标记。

fn clone_history(&self) -> ContextManager

作用：复制当前聊天历史。调用者想查看或加工历史，但不想直接改原件时会用它。

数据流：进去不需要参数；函数读取 history 并克隆一份；返回这份独立的 ContextManager 副本，原历史不变。

调用关系：它把复制工作交给 ContextManager 的 clone。会话流程需要拿历史快照时会调用它。

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

fn replace_history(
        &mut self,
        items: Vec<ResponseItem>,
        reference_context_item: Option<TurnContextItem>,
    )

作用：用一批新条目整体替换当前历史。常见于恢复会话、压缩上下文之后重建历史。

数据流：进去的是新的 ResponseItem 列表，以及一个可选的参考上下文条目；函数先让 history.replace 换掉旧历史，再设置参考上下文条目，最后清掉自动压缩窗口里的预填令牌记录；出来没有返回值，但历史和压缩窗口状态都变了。

调用关系：它把历史替换交给 ContextManager，把预填清理交给 AutoCompactWindow。测试 replace_history_clears_auto_compact_window_prefill 会关注它是否在替换历史时同步清理压缩窗口。

调用图：调用 3 个内部函数（replace, set_reference_context_item, clear_prefill）。

fn set_token_info(&mut self, info: Option<TokenUsageInfo>)

作用：直接设置当前历史里的令牌用量信息。令牌可以粗略理解为模型读写文字时的计数单位。

数据流：进去的是可选的 TokenUsageInfo；函数把它交给 history.set_token_info 保存；出来没有返回值，但历史里的用量信息被覆盖。

调用关系：它是会话状态对外提供的简单转发口，真正保存由 ContextManager 完成。

调用图：调用 1 个内部函数（set_token_info）。

fn set_reference_context_item(&mut self, item: Option<TurnContextItem>)

作用：设置一个“参考上下文条目”。它用于标记当前历史是围绕哪段上下文建立的。

数据流：进去的是一个可选 TurnContextItem；函数把它交给 history.set_reference_context_item；出来没有返回值，但历史管理器里对应标记被更新。

调用关系：它把工作交给 ContextManager。需要重建或标记上下文来源的流程会调用它。

调用图：调用 1 个内部函数（set_reference_context_item）。

fn reference_context_item(&self) -> Option<TurnContextItem>

作用：读取当前保存的参考上下文条目。调用者可以用它判断现在的历史参照了哪段上下文。

数据流：进去不需要参数；函数从 history.reference_context_item 取值；返回一个可能存在的 TurnContextItem。

调用关系：它是 set_reference_context_item 的读取搭档，具体数据仍由 ContextManager 保管。

调用图：调用 1 个内部函数（reference_context_item）。

fn update_token_info_from_usage(
        &mut self,
        usage: &TokenUsage,
        model_context_window: Option<i64>,
    )

作用：根据一次模型调用返回的实际用量，更新会话里的令牌统计。这样系统能知道上下文窗口还剩多少空间。

数据流：进去的是 TokenUsage 和可选的模型上下文窗口大小；函数把它们交给 history.update_token_info 计算并保存；出来没有返回值，但令牌信息更新了。

调用关系：模型返回用量后，会话流程会用它刷新统计。它不自己算细节，而是交给 ContextManager。

调用图：调用 1 个内部函数（update_token_info）。

fn ensure_auto_compact_window_server_prefill_from_usage(
        &mut self,
        usage: &TokenUsage,
    )

作用：用服务器看到的用量，补齐自动压缩窗口里的“预填”记录。预填可以理解为模型开始回答前已经占用的上下文。

数据流：进去的是 TokenUsage；函数交给 auto_compact_window.ensure_server_observed_prefill_from_usage；出来没有返回值，但自动压缩窗口可能记录了服务器观察到的预填数量。

调用关系：它属于自动压缩准备流程，具体判断和记录由 AutoCompactWindow 完成。

调用图：调用 1 个内部函数（ensure_server_observed_prefill_from_usage）。

fn set_auto_compact_window_estimated_prefill(&mut self, tokens: i64)

作用：给自动压缩窗口设置一个估算的预填令牌数。服务器还没给准数时，可以先用估算值。

数据流：进去的是令牌数量 tokens；函数写入 auto_compact_window.set_estimated_prefill；出来没有返回值，但窗口的估算预填被更新。

调用关系：它被需要预估上下文占用的流程调用，细节交给 AutoCompactWindow 保存。

调用图：调用 1 个内部函数（set_estimated_prefill）。

fn auto_compact_window_snapshot(&self) -> AutoCompactWindowSnapshot

作用：拿到自动压缩窗口当前状态的一张快照。快照就是只读照片，方便展示或判断，不直接改原状态。

数据流：进去不需要参数；函数调用 auto_compact_window.snapshot；返回 AutoCompactWindowSnapshot。

调用关系：会话流程或状态汇报需要查看压缩窗口情况时会用它，实际生成快照由 AutoCompactWindow 完成。

调用图：调用 1 个内部函数（snapshot）。

fn auto_compact_window_id(&self) -> u64

作用：读取当前自动压缩窗口的编号。编号用来区分这是第几段上下文窗口。

数据流：进去不需要参数；函数从 auto_compact_window.window_id 读取；返回一个数字编号。

调用关系：它给外部流程提供窗口身份信息，具体编号存在 AutoCompactWindow 里。

调用图：调用 1 个内部函数（window_id）。

fn set_auto_compact_window_id(&mut self, window_id: u64)

作用：手动设置自动压缩窗口编号。恢复会话或同步状态时，可能需要把编号调到指定值。

数据流：进去的是 window_id；函数交给 auto_compact_window.set_window_id 保存；出来没有返回值。

调用关系：它服务于会话恢复或状态同步流程，编号的实际保存由 AutoCompactWindow 负责。

调用图：调用 1 个内部函数（set_window_id）。

fn advance_auto_compact_window_id(&mut self) -> u64

作用：把自动压缩窗口编号往前推进一格，并返回新编号。换到新上下文窗口时会用到。

数据流：进去不需要参数；函数调用 auto_compact_window.advance_window_id；返回推进后的窗口编号，同时内部编号已更新。

调用关系：它是切换上下文窗口时的工具。start_new_context_window_if_requested 也会在真正开始新窗口时做同样的推进动作。

调用图：调用 1 个内部函数（advance_window_id）。

fn request_new_context_window(&mut self)

作用：登记一个“需要新上下文窗口”的请求。它只是先举手，不马上切换。

数据流：进去不需要参数；函数调用 auto_compact_window.request_new_context_window；出来没有返回值，但内部请求标记被设上。

调用关系：当系统发现当前上下文该换了时会调用它。稍后 start_new_context_window_if_requested 会检查这个请求并真正执行切换。

调用图：调用 1 个内部函数（request_new_context_window）。

fn start_new_context_window_if_requested(&mut self) -> Option<u64>

作用：如果之前有人请求新上下文窗口，就真正开始一个新窗口；如果没人请求，就什么也不做。

数据流：进去不需要参数；函数先从 auto_compact_window.take_new_context_window_request 取走请求标记；如果没有请求，返回 None；如果有，就推进窗口编号、清掉预填记录，并返回新的窗口编号。

调用关系：它是 request_new_context_window 的执行端。它把检查请求、推进编号、清理预填这些动作串起来，核心动作仍由 AutoCompactWindow 完成。

调用图：调用 3 个内部函数（advance_window_id, clear_prefill, take_new_context_window_request）。

fn token_info(&self) -> Option<TokenUsageInfo>

作用：读取当前令牌用量信息。调用者可以用它判断上下文占用情况。

数据流：进去不需要参数；函数从 history.token_info 取出信息；返回一个可能存在的 TokenUsageInfo。

调用关系：它是令牌信息的基础读取口，也会被 token_info_and_rate_limits 调用，用来和速率限制一起打包返回。

调用图：调用 1 个内部函数（token_info）；被 1 处调用（token_info_and_rate_limits）。

fn set_rate_limits(&mut self, snapshot: RateLimitSnapshot)

作用：保存最新的速率限制快照。速率限制就是服务端规定的使用额度、频率或套餐边界。

数据流：进去的是新的 RateLimitSnapshot；函数先调用 merge_rate_limit_fields，把新快照和旧快照合并，补上新快照缺失的额度、套餐等字段；然后存到 latest_rate_limits。

调用关系：服务端返回新的限制信息时会调用它。它依赖 merge_rate_limit_fields 防止新快照不完整时覆盖掉旧的有用信息；相关测试会检查额度和套餐信息是否正确保留或更新。

调用图：调用 1 个内部函数（merge_rate_limit_fields）。

fn token_info_and_rate_limits(
        &self,
    ) -> (Option<TokenUsageInfo>, Option<RateLimitSnapshot>)

作用：一次性取出令牌用量和速率限制。界面或状态上报通常两样都要看，所以这里打包给出去。

数据流：进去不需要参数；函数先调用 token_info 取令牌信息，再复制 latest_rate_limits；返回二者组成的一对值。

调用关系：它站在状态查询的出口位置，把 token_info 的结果和本文件保存的速率限制合在一起给调用者。

调用图：调用 1 个内部函数（token_info）。

fn set_token_usage_full(&mut self, context_window: i64)

作用：把令牌使用情况标记为已经占满上下文窗口。也就是告诉系统：这段上下文空间已经没有余量了。

数据流：进去的是上下文窗口大小 context_window；函数交给 history.set_token_usage_full；出来没有返回值，但历史里的用量状态会被设为满。

调用关系：当系统判断上下文已满时会调用它。具体如何记录满载状态由 ContextManager 完成。

调用图：调用 1 个内部函数（set_token_usage_full）。

fn get_total_token_usage(&self, server_reasoning_included: bool) -> i64

作用：计算当前总令牌用量。参数决定是否把服务器的推理内容也算进去。

数据流：进去的是 server_reasoning_included 这个布尔值；函数把它传给 history.get_total_token_usage；返回一个总令牌数。

调用关系：需要做窗口判断、显示用量或触发压缩时会查它。计算细节由 ContextManager 负责。

调用图：调用 1 个内部函数（get_total_token_usage）。

fn set_server_reasoning_included(&mut self, included: bool)

作用：记录服务器推理内容是否应该计入会话状态。这个开关会影响后续令牌统计口径。

数据流：进去的是 included；函数把 server_reasoning_included 改成这个值；出来没有返回值。

调用关系：会话流程根据服务端能力或配置设置它，之后 server_reasoning_included 会读取这个口径。

fn server_reasoning_included(&self) -> bool

作用：读取当前是否把服务器推理内容算进去。调用者用它保持统计口径一致。

数据流：进去不需要参数；函数返回 server_reasoning_included 当前值；状态不变。

调用关系：它和 set_server_reasoning_included 配套使用，常用于需要决定令牌计算方式的地方。

fn record_mcp_dependency_prompted(&mut self, names: I)

作用：记录哪些 MCP 依赖已经提醒过用户。MCP 可以理解为外部工具/服务接入的一套协议；这里避免同一个依赖反复弹提醒。

数据流：进去的是一批依赖名称；函数把这些名称加入 mcp_dependency_prompted 这个集合；出来没有返回值，重复名称会自然去重。

调用关系：当系统已经提示过某些 MCP 依赖后会调用它。之后 mcp_dependency_prompted 可以取出这份集合做判断。

fn mcp_dependency_prompted(&self) -> HashSet<String>

作用：读取已经提示过的 MCP 依赖名称。调用者可以据此决定不要重复打扰用户。

数据流：进去不需要参数；函数复制 mcp_dependency_prompted 集合并返回；原集合不变。

调用关系：它是 record_mcp_dependency_prompted 的读取端，供提示流程查询历史提示记录。

fn set_session_startup_prewarm(
        &mut self,
        startup_prewarm: SessionStartupPrewarmHandle,
    )

作用：保存启动时预热好的会话资源。预热就像饭店提前备菜，真正要用时可以更快。

数据流：进去的是 SessionStartupPrewarmHandle；函数把它包成 Some 存到 startup_prewarm；出来没有返回值。

调用关系：会话初始化完成预热后会调用它。稍后 take_session_startup_prewarm 会把这份预热资源取走使用。

fn take_session_startup_prewarm(&mut self) -> Option<SessionStartupPrewarmHandle>

作用：取走启动预热资源，并从状态里清空。这样同一份预热资源不会被重复使用。

数据流：进去不需要参数；函数对 startup_prewarm 执行 take；返回原来的预热句柄或 None，同时内部字段变成 None。

调用关系：它是 set_session_startup_prewarm 的消费端。会话真正需要使用预热结果时会调用它。

fn merge_connector_selection(&mut self, connector_ids: I) -> HashSet<String>

作用：把新的连接器编号加入当前已选择的连接器集合，并返回合并后的结果。连接器可以理解为外部数据源或工具入口。

数据流：进去的是一批 connector_ids；函数把它们加入 active_connector_selection 这个集合，重复编号会自动去掉；返回合并后的集合副本。

调用关系：当用户或系统追加选择连接器时会调用它。测试 merge_connector_selection_deduplicates_entries 会关注它是否正确去重。

fn get_connector_selection(&self) -> HashSet<String>

作用：读取当前会话里选中的连接器集合。调用者可以知道接下来应该启用哪些外部入口。

数据流：进去不需要参数；函数复制 active_connector_selection 并返回；原集合不变。

调用关系：它给请求准备流程或界面展示提供当前选择，通常和 merge_connector_selection、clear_connector_selection 配合使用。

fn clear_connector_selection(&mut self)

作用：清空当前记录的连接器选择。需要重置选择时用它。

数据流：进去不需要参数；函数清空 active_connector_selection；出来没有返回值，之后读取会得到空集合。

调用关系：当会话或某个流程需要重新选择连接器时会调用它。测试 clear_connector_selection_removes_entries 会检查清空是否生效。

fn queue_pending_session_start_source(
        &mut self,
        value: codex_hooks::SessionStartSource,
    )

作用：把一个待处理的会话启动来源排进队列。队列像排队取号，先来的会先被取走。

数据流：进去的是一个 SessionStartSource；函数用 push_back 把它放到 pending_session_start_sources 队尾；出来没有返回值。

调用关系：启动钩子或会话初始化流程发现新的启动来源时会调用它。之后 take_pending_session_start_source 会按顺序取出。

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

fn take_pending_session_start_source(
        &mut self,
    ) -> Option<codex_hooks::SessionStartSource>

作用：从待处理启动来源队列里取出最早的一项。取出后它就不在队列里了。

数据流：进去不需要参数；函数用 pop_front 从队头取值；返回一个 SessionStartSource 或 None，同时队列少一项。

调用关系：处理启动来源的流程会调用它。它和 queue_pending_session_start_source 配合，形成先进先出的处理顺序。

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

fn record_granted_permissions(
        &mut self,
        environment_id: &str,
        permissions: AdditionalPermissionProfile,
    )

作用：记录某个环境已经授予的额外权限。环境可以理解为一次运行或工具执行所在的隔离空间。

数据流：进去的是 environment_id 和一份 AdditionalPermissionProfile；函数先取出这个环境旧的权限，再调用 merge_permission_profiles 合并旧权限和新权限；如果合并结果存在，就按环境编号存回表里。

调用关系：当用户或策略给某个环境放行了额外权限时会调用它。它把权限合并规则交给 sandboxing 里的 merge_permission_profiles，避免新权限覆盖掉旧权限。

调用图：调用 1 个内部函数（merge_permission_profiles）。

fn granted_permissions(
        &self,
        environment_id: &str,
    ) -> Option<AdditionalPermissionProfile>

作用：读取某个环境已经拿到的额外权限。后续执行命令或工具前可以用它判断是否已经放行。

数据流：进去的是 environment_id；函数在 granted_permissions_by_environment_id 里查找并复制结果；返回权限配置或 None。

调用关系：它是 record_granted_permissions 的查询端，供执行环境准备或权限检查流程使用。

fn merge_rate_limit_fields(
    previous: Option<&RateLimitSnapshot>,
    mut snapshot: RateLimitSnapshot,
) -> RateLimitSnapshot

作用：合并新旧速率限制信息，专门处理“新快照缺字段”的情况。这样不会因为服务端这次少给了套餐或额度字段，界面和逻辑就丢掉旧信息。

数据流：进去的是上一份 RateLimitSnapshot（可选）和新的 snapshot；函数先给缺失的 limit_id 填默认值 codex，再把缺失的 credits、individual_limit、plan_type 从旧快照补回来；返回补全后的新快照。

调用关系：它只被 SessionState::set_rate_limits 调用，是保存速率限制前的清洗步骤。set_rate_limits 负责存结果，它负责让结果尽量完整。

调用图：被 1 处调用（set_rate_limits）。

fn new() -> Self

作用：创建一个全新的自动压缩窗口状态。新状态从窗口编号 0 开始，没有待处理的新窗口请求，也还不知道窗口起点占了多少 token。

数据流：进去没有额外输入 → 它把窗口编号设为 0，把“需要新窗口”的标记设为否，把预填 token 基准设为空 → 出来一个干净的 AutoCompactWindow 状态对象。

调用关系：它通常在更大的状态对象初始化时被调用，也被测试用来搭一个最小场景。后面的窗口编号、请求标记、token 基准，都是在这个初始状态上逐步改出来的。

调用图：被 2 处调用（tracks_prefill_and_window_boundaries, new）。

fn clear_prefill(&mut self)

作用：清掉当前记录的预填 token 基准。换历史记录或真正开始新上下文窗口时，需要把旧窗口的起点信息丢掉，免得影响新窗口。

数据流：进去的是当前窗口状态 → 它只把 prefill_input_tokens 这一项设为空 → 出来还是同一个状态对象，但已经不再记得旧的输入 token 起点。

调用关系：它会被 replace_history 和 start_new_context_window_if_requested 使用。也就是说，当历史被替换，或系统响应“开新窗口”的请求时，会先把旧基准清理掉。

调用图：被 2 处调用（replace_history, start_new_context_window_if_requested）。

fn window_id(&self) -> u64

作用：读取当前自动压缩窗口的编号。外部需要知道“现在是哪一轮窗口”时会用它。

数据流：进去的是当前窗口状态 → 它查看里面保存的 window_id → 返回这个数字，不改动任何状态。

调用关系：它被 auto_compact_window_id 这个更外层的读取接口调用。外部代码不用直接碰内部字段，而是通过这个小入口拿到窗口编号。

调用图：被 1 处调用（auto_compact_window_id）。

fn set_window_id(&mut self, window_id: u64)

作用：手动设置当前窗口编号。它用于外层状态需要恢复、同步或指定窗口编号的时候。

数据流：进去一个新的窗口编号和当前状态 → 它把状态里的 window_id 改成传入的值 → 出来是同一个状态对象，但窗口编号已经更新。

调用关系：它被 set_auto_compact_window_id 调用。也就是更外层的状态管理代码收到“设置窗口编号”的需求后，把具体改字段的事交给这里。

调用图：被 1 处调用（set_auto_compact_window_id）。

fn advance_window_id(&mut self) -> u64

作用：进入下一轮自动压缩窗口，并顺手清掉“需要新窗口”的请求标记。它表示请求已经被消费，窗口确实往前走了一步。

数据流：进去的是当前窗口状态 → 它把 window_id 加 1；如果数字已经到上限，就用安全的饱和加法避免溢出；同时把 new_context_window_requested 设为否 → 返回更新后的窗口编号。

调用关系：它被 advance_auto_compact_window_id 和 start_new_context_window_if_requested 调用。前者是直接推进窗口，后者是在发现确实有人请求新窗口时推进窗口。

调用图：被 2 处调用（advance_auto_compact_window_id, start_new_context_window_if_requested）。

fn request_new_context_window(&mut self)

作用：记录一个“请在合适时机开新上下文窗口”的请求。它只是插一面小旗，不立刻做切换。

数据流：进去的是当前窗口状态 → 它把 new_context_window_requested 改成 true → 出来同一个状态对象，但里面多了一个待处理的新窗口请求。

调用关系：它被 request_new_context_window 这个外层接口调用。之后 start_new_context_window_if_requested 会来检查这面小旗，并决定是否真正开新窗口。

调用图：被 1 处调用（request_new_context_window）。

fn take_new_context_window_request(&mut self) -> bool

作用：取出并清空“是否请求了新上下文窗口”这个标记。它像取信箱里的信：取走后信箱就空了，避免同一个请求被处理两次。

数据流：进去的是当前窗口状态 → 它先记下 new_context_window_requested 当前是 true 还是 false，然后把这个标记改回 false → 返回刚才记下的结果。

调用关系：它被 start_new_context_window_if_requested 调用。这个外层流程会用返回值判断是否要开新窗口；无论结果如何，请求标记都已经被消费掉。

调用图：被 1 处调用（start_new_context_window_if_requested）。

fn ensure_server_observed_prefill_from_usage(&mut self, usage: &TokenUsage)

作用：用服务器真实报告的用量，记录当前窗口开始时的输入 token 基准。真实值比本地估算更可信，所以一旦有了真实值，就不会再被后来的估算或第二次真实采样覆盖。

数据流：进去的是当前窗口状态和一次 TokenUsage（服务器报告的 token 用量）→ 如果已经有 ServerObserved，也就是真实服务器基准，它直接不动；否则取 usage.input_tokens，负数按 0 处理，存成服务器观察到的基准 → 出来状态里有了更可靠的预填输入 token 数。

调用关系：它被 ensure_auto_compact_window_server_prefill_from_usage 调用，通常发生在收到服务器返回的 token 用量之后。它会构造 ServerObserved 这种内部标记，并用 matches! 判断当前是否已经有真实值。

调用图：被 1 处调用（ensure_auto_compact_window_server_prefill_from_usage）；外部调用 2 个（ServerObserved, matches!）。

fn set_estimated_prefill(&mut self, tokens: i64)

作用：在还没有服务器真实用量时，先放一个本地估算的输入 token 基准。这样系统不用干等服务器，也能先大致计算窗口增长。

数据流：进去的是当前窗口状态和估算 token 数 → 如果状态里已经有服务器真实基准，就什么都不改；否则把传入数字按不小于 0 处理后，存成 Estimated 估算基准 → 出来状态可能多了一个估算起点。

调用关系：它被 set_auto_compact_window_estimated_prefill 调用。它和 ensure_server_observed_prefill_from_usage 配合：先用估算顶上，等服务器真实值来了再让真实值接管。

调用图：被 1 处调用（set_auto_compact_window_estimated_prefill）；外部调用 2 个（Estimated, matches!）。

fn snapshot(&self) -> AutoCompactWindowSnapshot

作用：把当前窗口状态中对外有用的部分打包成一个快照。快照就是一张只读的小纸条，方便外部查看当前预填 token 基准。

数据流：进去的是当前窗口状态 → 它查看 prefill_input_tokens，不管这个数来自服务器真实值还是本地估算，都取出里面的数字；如果没有记录就保持为空 → 返回 AutoCompactWindowSnapshot。

调用关系：它被 auto_compact_window_snapshot 调用。外层代码需要查看状态时，通过这个函数拿到简化后的结果，而不是直接了解内部的 ServerObserved 和 Estimated 区别。

调用图：被 1 处调用（auto_compact_window_snapshot）。

fn tracks_prefill_and_window_boundaries()

作用：这是这个文件的自测，确认窗口编号、请求标记、估算基准和服务器真实基准都按预期工作。它防止以后改代码时不小心破坏这些小规则。

数据流：进去没有外部输入 → 它创建一个新窗口，依次设置编号、请求新窗口、推进窗口、设置估算 token、再用服务器用量覆盖估算，并尝试用后续值覆盖服务器真实值 → 通过断言检查每一步结果是否正确；它不产出业务结果，只在测试失败时报警。

调用关系：它调用 AutoCompactWindow::new，并使用 assert_eq!、assert! 这类测试断言，还用 TokenUsage::default 补齐测试数据。它相当于把这个文件的关键规则串起来跑一遍。

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

fn from_config_and_version(
        config: &Config,
        multi_agent_version: MultiAgentVersion,
    ) -> Self

作用：根据配置和多智能体协议版本，决定“上一轮被打断”这件事要不要写进对话历史，以及用哪种身份写。这样后续模型能知道前一轮不是自然结束，而是被人打断了。

数据流：进去的是全局配置和 MultiAgentVersion（多智能体协议版本）→ 先看配置是否允许写中断提示，不允许就返回 Disabled → 如果允许，V2 版本返回 Developer，否则返回 ContextualUser。

调用关系：当任务真正被打断时，Session::handle_task_abort 会用它选择标记格式；创建分叉线程和子智能体快照时也会用同一套判断，保证真实中断和复制出来的历史看起来一致。

调用图：被 3 处调用（handle_task_abort, fork_thread_with_initial_history, spawn_subagent）。

fn interrupted_turn_history_marker(
    marker: InterruptedTurnHistoryMarker,
) -> Option<ResponseItem>

作用：把“中断标记类型”变成模型能看到的一条对话内容。没有这一步，模型后面可能不知道上一轮为什么突然没了下文。

数据流：进去的是 Disabled、ContextualUser 或 Developer 这三种选择之一→ Disabled 直接没有输出→ ContextualUser 生成一条带上下文的用户片段→ Developer 生成一条 developer 身份的消息→ 出来是可选的 ResponseItem，也就是可放进对话历史的一项内容。

调用关系：Session::handle_task_abort 在用户打断任务后调用它，把标记写入历史；append_interrupted_boundary 和测试/辅助标记函数也复用它，避免不同地方生成的中断提示不一致。

调用图：调用 2 个内部函数（into, new）；被 4 处调用（handle_task_abort, append_interrupted_boundary, contextual_user_interrupted_marker, developer_interrupted_marker）；外部调用 1 个（vec!）。

fn emit_turn_network_proxy_metric(
    session_telemetry: &SessionTelemetry,
    network_proxy_active: bool,
    tmp_mem: (&str, &str),
)

作用：记录这一轮结束时网络代理是否处于开启状态。这个指标能帮助开发者判断某些慢、失败或网络行为是否和代理有关。

数据流：进去的是遥测对象、网络代理是否开启、以及一个临时内存功能标签→ 把布尔值转成 true/false 字符串→ 调用 counter 给 TURN_NETWORK_PROXY_METRIC 计数一次。

调用关系：Session::on_task_finished 在回合正常结束时读取网络代理状态，然后调用它把结果写入统一遥测系统。

调用图：调用 1 个内部函数（counter）；被 1 处调用（on_task_finished）。

fn emit_turn_memory_metric(
    session_telemetry: &SessionTelemetry,
    feature_enabled: bool,
    config_enabled: bool,
    has_citations: bool,
)

作用：记录这一轮记忆功能的状态：功能开没开、配置让不让用、这一轮有没有引用记忆。这样能看出记忆功能是否真的参与了回答。

数据流：进去的是遥测对象、功能开关、配置开关、是否有记忆引用→ 计算 read_allowed，也就是功能和配置都允许才算能读记忆→ 用 bool_tag 把布尔值变成标签→ 输出是一条计数指标，没有普通返回值。

调用关系：Session::on_task_finished 在回合结束收集完本轮状态后调用它；它内部把布尔值格式化的活交给 bool_tag。

调用图：调用 2 个内部函数（bool_tag, counter）；被 1 处调用（on_task_finished）。

fn emit_compact_metric(
    session_telemetry: &SessionTelemetry,
    compact_type: &'static str,
    manual: bool,
)

作用：记录一次“压缩上下文”任务发生了。压缩上下文可以理解成把很长的对话整理变短，方便模型继续接着聊。

数据流：进去的是遥测对象、压缩类型、是否人工触发→ 用 bool_tag 把 manual 转成 true/false 标签→ 给 codex.task.compact 这个指标计数一次。

调用关系：自动压缩流程 run_auto_compact 会调用它；它不做压缩本身，只负责把“发生过一次压缩”告诉统计系统。

调用图：调用 2 个内部函数（bool_tag, counter）；被 1 处调用（run_auto_compact）。

fn bool_tag(value: bool) -> &'static str

作用：把程序里的 true/false 变成指标系统喜欢的字符串标签。它很小，但能让不同指标都用同一种写法。

数据流：进去一个布尔值→ 如果是真就变成 "true"，否则变成 "false"→ 返回这个静态字符串，不改动其他东西。

调用关系：emit_turn_memory_metric 和 emit_compact_metric 都用它来生成遥测标签，避免每个地方自己写一套 true/false 转换。

调用图：被 2 处调用（emit_compact_metric, emit_turn_memory_metric）。

fn new(session: Arc<Session>, turn_extension_data: Arc<ExtensionData>) -> Self

作用：创建一个给任务使用的轻量上下文。它把任务常用的会话对象和扩展数据打包在一起，避免任务到处直接摸完整 Session。

数据流：进去的是共享的 Session 和本回合的 ExtensionData（扩展插件可用的数据）→ 存进 SessionTaskContext → 出来一个新的上下文对象。

调用关系：Session::start_task 在启动任务前创建它，交给任务运行；Session::handle_task_abort 在调用任务自己的 abort 清理逻辑前也会重新创建它。

调用图：被 2 处调用（handle_task_abort, start_task）。

fn clone_session(&self) -> Arc<Session>

作用：给任务一份共享会话引用，让任务能发事件、读服务或做会话级操作。这里的 clone 不是复制整个会话，而是多拿一个指向同一会话的安全指针。

数据流：进去的是上下文本身→ 克隆内部 Arc<Session>（Arc 是线程间共享指针）→ 返回同一个 Session 的新引用，不改变会话内容。

调用关系：后台任务跑完时会用它重新拿到 Session，然后刷新记录、发送完成事件和做收尾。

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

fn turn_extension_data(&self) -> Arc<ExtensionData>

作用：取出本回合的扩展数据，给任务或扩展功能使用。这样任务不用知道扩展数据藏在会话的哪个角落。

数据流：进去的是上下文本身→ 克隆内部 Arc<ExtensionData>→ 返回同一份扩展数据的共享引用。

调用关系：它是 SessionTaskContext 暴露给各类任务的便捷取口；调用图里没有显示本文件内直接调用，但任务实现可以通过它拿扩展相关信息。

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

fn auth_manager(&self) -> Arc<AuthManager>

作用：给任务拿登录和认证管理器。比如任务需要访问需要身份的服务时，就能从这里拿到统一的认证入口。

数据流：进去的是上下文本身→ 从 Session 的 services 里取 auth_manager，并克隆共享指针→ 返回 AuthManager 的共享引用。

调用关系：这是任务运行时可用的服务出口之一；它把任务和 Session 内部服务布局隔开，让任务只拿自己需要的东西。

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

fn models_manager(&self) -> SharedModelsManager

作用：给任务拿模型管理器，也就是负责模型列表、选择和相关状态的共享组件。任务需要知道或切换模型信息时会用到它。

数据流：进去的是上下文本身→ 从 Session 的 services 里取 models_manager，并克隆共享指针→ 返回模型管理器的共享引用。

调用关系：它服务于具体 SessionTask 的实现；本文件只提供通道，不直接决定模型怎么用。

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

fn abort(
        &self,
        session: Arc<SessionTaskContext>,
        ctx: Arc<TurnContext>,
    ) -> impl std::future::Future<Output = ()> + Send

作用：这是任务被取消后的默认清理钩子。默认什么都不做，但某些任务可以重写它，比如关闭资源或发额外通知。

数据流：进去的是任务上下文和回合上下文→ 默认实现只是接收它们并丢弃→ 返回完成信号，不产生额外输出也不改状态。

调用关系：T::abort 这个适配层会把调用转到这里；Session::handle_task_abort 在取消任务、等待片刻并强制终止后台句柄后，会调用任务的 abort 做最后清理。

调用图：被 1 处调用（abort）。

fn kind(&self) -> TaskKind

作用：把具体任务的 kind 方法转成统一接口上的 kind 方法。这样调度器不需要知道任务到底是 RegularTask、ReviewTask 还是别的类型。

数据流：进去的是某个实现了 SessionTask 的具体任务→ 调用它自己的 kind→ 返回 TaskKind，也就是任务类别。

调用关系：Session::start_task 把具体任务包成 AnySessionTask 后，会通过这个适配方法取得任务类别，用于记录 RunningTask 和遥测。

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

fn span_name(&self) -> &'static str

作用：把具体任务的追踪名称取出来，给后台任务的日志和链路追踪使用。追踪名称就像给这一段后台工作贴的标签。

数据流：进去的是具体任务→ 调用它自己的 span_name→ 返回一个静态字符串名称。

调用关系：Session::start_task 会用它创建 tracing span（追踪跨度，用来把一段异步工作串起来看），方便之后查日志和性能。

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

fn run(
        self: Arc<Self>,
        session: Arc<SessionTaskContext>,
        ctx: Arc<TurnContext>,
        input: Vec<TurnInput>,
        cancellation_token: CancellationToken,
    ) -> BoxFutu

作用：把具体任务的异步运行过程包装成统一的 BoxFuture。BoxFuture 可以理解成“装进盒子里的未来结果”，让不同任务看起来像同一种形状。

数据流：进去的是具体任务、任务上下文、回合上下文、输入和取消令牌→ 调用具体 SessionTask::run→ 用 Box::pin 固定成统一返回类型→ 输出一个最终可能带有最后助手消息的异步结果。

调用关系：Session::start_task 在 tokio 后台任务里调用 AnySessionTask::run，实际就会走到这里，再转交给具体任务实现。

调用图：外部调用 2 个（pin, run）。

fn abort(
        &'a self,
        session: Arc<SessionTaskContext>,
        ctx: Arc<TurnContext>,
    ) -> BoxFuture<'a, ()>

作用：把具体任务的取消清理过程包装成统一的异步接口。这样调度器可以用同一种方式清理任何任务。

数据流：进去的是具体任务、任务上下文和回合上下文→ 调用 SessionTask::abort，也就是具体任务重写的清理逻辑或默认空操作→ 包装成 BoxFuture 返回。

调用关系：Session::handle_task_abort 通过 AnySessionTask 调用 abort 时会走到这里，然后真正交给任务自己的 abort 实现。

调用图：调用 1 个内部函数（abort）；外部调用 1 个（pin）。

async fn spawn_task(
        self: &Arc<Self>,
        turn_context: Arc<TurnContext>,
        input: Vec<TurnInput>,
        task: T,
    )

作用：启动一个新任务，并先把旧任务停掉。它保证同一个会话不会同时有两个主要回合任务互相抢状态。

数据流：进去的是回合上下文、输入和一个任务→ 先用 Replaced 原因中止所有现有任务→ 清掉连接器选择→ 再调用 Session::start_task 真正启动新任务。

调用关系：外部想发起一个新的会话任务时会用它；它把“先清旧，再开新”的规矩交给 abort_all_tasks 和 start_task 分别完成。

调用图：调用 2 个内部函数（abort_all_tasks, start_task）。

async fn start_task(
        self: &Arc<Self>,
        turn_context: Arc<TurnContext>,
        input: Vec<TurnInput>,
        task: T,
    )

作用：真正把一个回合任务放到后台跑起来。它是本文件最核心的启动器，负责建状态、建取消令牌、建追踪信息、登记 RunningTask。

数据流：进去的是回合上下文、输入和具体任务→ 把任务包装成统一接口→ 标记回合开始时间和起始 token 用量→ 准备取消令牌、完成通知、任务状态和扩展数据→ 用 tokio::spawn 开一个后台异步任务→ 后台任务运行具体 task.run，结束后刷新记录并调用 on_task_finished→ 最后把 RunningTask 保存到 active_turn。

调用关系：Session::spawn_task 和 maybe_start_turn_for_pending_work_with_sub_id 都会调用它。它启动的后台任务完成后，会回到 Session::on_task_finished 做统一收尾。

调用图：调用 1 个内部函数（new）；被 2 处调用（maybe_start_turn_for_pending_work_with_sub_id, spawn_task）；外部调用 15 个（new, clone, new, new, now, new, kind, span_name, debug_assert!, format! (+5 more)）。

async fn maybe_start_turn_for_pending_work(self: &Arc<Self>)

作用：当会话空闲但队列里有“需要触发一轮”的待办输入时，自动开一轮普通任务。它避免后台邮件或待处理消息一直躺着没人理。

数据流：进去的是 Session→ 生成一个新的随机 sub_id（本轮编号）→ 调用 maybe_start_turn_for_pending_work_with_sub_id→ 自己不直接启动任务。

调用关系：Session::abort_all_tasks 和 Session::abort_turn_if_active 在因 Interrupted 中断后会调用它，看看是否该立刻处理队列里新的触发项。

调用图：调用 1 个内部函数（maybe_start_turn_for_pending_work_with_sub_id）；被 2 处调用（abort_all_tasks, abort_turn_if_active）；外部调用 1 个（new_v4）。

async fn maybe_start_turn_for_pending_work_with_sub_id(
        self: &Arc<Self>,
        sub_id: String,
    )

作用：用指定的回合编号，在合适条件下为待办工作启动一轮普通对话任务。它会先确认真的有触发项，而且当前没有任务在跑。

数据流：进去的是 Session 和 sub_id→ 检查输入队列里有没有 trigger_turn 邮件项，没有就返回→ 再检查 active_turn 是否为空，不空也返回→ 创建默认回合上下文，可能发出未知模型警告→ 调用 start_task 启动 RegularTask，输入为空。

调用关系：maybe_start_turn_for_pending_work 负责生成 sub_id 后调用它；它最终把活交给 Session::start_task。

调用图：调用 3 个内部函数（default, start_task, new）；被 1 处调用（maybe_start_turn_for_pending_work）；外部调用 1 个（new）。

async fn abort_all_tasks(self: &Arc<Self>, reason: TurnAbortReason)

作用：中止当前会话里的所有正在运行任务。用户发起新请求、替换任务或手动打断时，需要它把旧回合干净地停下来。

数据流：进去的是中止原因→ 从 active_turn 里拿走当前回合→ 如果有任务，就调用 handle_task_abort 取消和收尾→ 发出回合中止生命周期事件→ 清掉本回合挂起输入→ 如果原因是 Interrupted，再尝试启动待办工作→ 没有普通返回值，但会改变 active_turn、输入队列和对外事件。

调用关系：Session::spawn_task 在启动新任务前会调用它。它内部用 take_active_turn 取走当前状态，再把具体中止细节交给 handle_task_abort。

调用图：调用 3 个内部函数（handle_task_abort, maybe_start_turn_for_pending_work, take_active_turn）；被 1 处调用（spawn_task）；外部调用 1 个（clone）。

async fn abort_turn_if_active(
        self: &Arc<Self>,
        turn_id: &str,
        reason: TurnAbortReason,
    ) -> bool

作用：只在指定 turn_id 正好是当前运行回合时，才中止它。这样可以避免误伤别的回合。

数据流：进去的是 turn_id 和中止原因→ 锁住 active_turn 检查当前任务的 sub_id 是否匹配→ 不匹配返回 false→ 匹配就拿走 active_turn，调用 handle_task_abort，发中止生命周期事件，清挂起输入→ 如果是 Interrupted，再尝试启动待办工作→ 返回 true 表示确实中止了。

调用关系：它是更精确的中止入口；和 abort_all_tasks 一样，真正取消任务的细节交给 handle_task_abort。

调用图：调用 2 个内部函数（handle_task_abort, maybe_start_turn_for_pending_work）；外部调用 1 个（clone）。

async fn on_task_finished(
        self: &Arc<Self>,
        turn_context: Arc<TurnContext>,
        last_agent_message: Option<String>,
    )

作用：统一处理任务正常结束后的收尾。它会发完成事件、记录用量和性能、处理排队输入，并把会话标记为空闲。

数据流：进去的是回合上下文和可选的最后助手消息→ 取消 git 补充信息任务→ 从 active_turn 取下已完成任务并分离后台句柄→ 取出本轮期间积累的待处理输入并通过 hook 检查→ 统计工具调用数、token 用量、网络代理、记忆引用和耗时→ 发送 TurnComplete 事件→ 清理保护器状态→ 如果确认当前 active_turn 就是这轮，置为空并可能发线程空闲生命周期事件。

调用关系：Session::start_task 创建的后台任务在 run 返回后会调用它。它会调用 inspect_pending_input、record_additional_contexts、record_pending_input，以及 emit_turn_network_proxy_metric 和 emit_turn_memory_metric 来完成附加收尾。

调用图：调用 5 个内部函数（inspect_pending_input, record_additional_contexts, record_pending_input, emit_turn_memory_metric, emit_turn_network_proxy_metric）；外部调用 5 个（ptr_eq, current, try_from, TurnComplete, warn!）。

async fn take_active_turn(&self) -> Option<ActiveTurn>

作用：把当前 active_turn 整个取出来，并把 Session 里的位置清空。它像把值班台上的当前工单拿走，后面才能安全处理或替换。

数据流：进去的是 Session→ 锁住 active_turn→ 调用 take 把 Option 里的 ActiveTurn 移出→ 返回可能存在的 ActiveTurn，同时 Session 内部 active_turn 变成 None。

调用关系：Session::abort_all_tasks 用它先把当前回合从共享状态中移除，再继续执行中止逻辑，减少别的流程同时看到半中止状态的机会。

调用图：被 1 处调用（abort_all_tasks）。

async fn close_unified_exec_processes(&self)

作用：关闭所有统一执行管理器里的后台进程。通俗说，就是把会话里还开着的后台终端或命令进程一起收掉。

数据流：进去的是 Session→ 找到 services.unified_exec_manager→ 调用 terminate_all_processes→ 没有返回业务数据，但会请求终止所有相关进程。

调用关系：它是会话级清理入口；本文件不继续下放到具体任务，而是直接把关闭进程的工作交给 unified_exec_manager。

async fn list_background_terminals(&self) -> Vec<BackgroundTerminalInfo>

作用：列出当前会话里还在后台运行的终端进程。前端或调用方可以用它展示“有哪些命令还没停”。

数据流：进去的是 Session→ 向 unified_exec_manager 请求进程列表→ 返回 BackgroundTerminalInfo 列表，每项描述一个后台终端。

调用关系：它是查看后台终端状态的查询入口；实际收集进程信息的工作由 unified_exec_manager 完成。

async fn terminate_background_terminal(&self, process_id: i32) -> bool

作用：按进程号终止某一个后台终端。用户想关掉某个长时间运行的命令时会用到它。

数据流：进去的是 process_id 进程号→ 交给 unified_exec_manager 尝试终止对应进程→ 返回布尔值，表示是否成功找到并发起终止。

调用关系：它和 list_background_terminals 配套：先列出后台终端，再按某个 process_id 调用这里关闭指定进程。

async fn handle_task_abort(self: &Arc<Self>, task: RunningTask, reason: TurnAbortReason)

作用：执行一次任务中止的完整流程。它不是简单杀掉任务，而是先通知任务取消、等它短暂自我收尾，再做强制停止、写历史标记、发中止事件。

数据流：进去的是 RunningTask 和中止原因→ 如果取消令牌已经取消就直接返回→ 取消令牌发信号→ 停掉 git 补充任务→ 最多等待 100 毫秒让任务自己完成→ 仍没完就 abort 后台句柄→ 创建 SessionTaskContext 并调用任务自己的 abort 清理→ 如果是 Interrupted，就根据配置和版本生成中断历史标记，写入对话并刷新落盘→ 记录完成时间和性能画像→ 发送 TurnAborted 事件→ 清理保护器状态。

调用关系：Session::abort_all_tasks 和 Session::abort_turn_if_active 都把具体中止工作交给它。它会调用 InterruptedTurnHistoryMarker::from_config_and_version 和 interrupted_turn_history_marker 来决定是否给模型留下“刚才被打断”的说明。

调用图：调用 3 个内部函数（from_config_and_version, new, interrupted_turn_history_marker）；被 2 处调用（abort_all_tasks, abort_turn_if_active）；外部调用 7 个（clone, new, TurnAborted, select!, from_ref, trace!, warn!）。

fn default() -> Self

作用：创建一个“当前没有任务”的默认活动轮次。系统启动新会话或测试时需要一个干净的起点，先把任务位置空出来，同时准备好一份可共享的本轮状态。

数据流：进去没有额外输入 → 它把 task 设成 None，并新建一个带互斥锁的 TurnState；互斥锁就是一把锁，防止多个异步任务同时改同一份状态 → 出来一个 ActiveTurn，表示当前还没有正在跑的任务，但已经有地方记录之后这一轮的临时信息。

调用关系：很多请求处理和测试会从这里开始拿到一个空的 ActiveTurn。后续真正开始执行任务时，别的流程会把 RunningTask 填进去，并通过里面的 turn_state 记录审批、权限、输入等等待事项。

调用图：被 17 处调用（handle_request_permissions_uses_tool_call_id_for_round_trip, codex_apps_auth_elicitation_feature_enabled_requests_elicitation, prompt_mode_waits_for_approval_when_annotations_do_not_require_approval, enable_strict_auto_review_for_turn_uses_originating_turn, request_permissions_guardian_review_stops_when_cancelled, request_permissions_routes_to_guardian_when_reviewer_is_enabled, shell_command_allows_sticky_turn_permissions_without_inline_request_permissions_feature, strict_auto_review_turn_grant_forces_guardian_for_shell_command_policy_skip, notify_request_permissions_response_ignores_unmatched_call_id, record_granted_request_permissions_for_turn_uses_originating_turn (+7 more)）；外部调用 3 个（new, new, default）。

fn insert_pending_approval(
        &mut self,
        key: String,
        tx: oneshot::Sender<ReviewDecision>,
    ) -> Option<oneshot::Sender<ReviewDecision>>

作用：登记一个还在等待回复的审批请求。比如系统要执行某个可能有风险的动作，需要用户或审查器点头，这个函数就把“等谁回复”先记下来。

数据流：进去一个 key 和一个 oneshot 发送端；oneshot 可以理解成一次性传话筒，只能传回一次结果 → 它把发送端放进 pending_approvals 这张表里 → 出来的是同一个 key 下原来旧的发送端，如果有的话，同时状态表被更新。

调用关系：当某个流程发起审批时会调用它保存等待通道。等审批结果回来时，配套的 TurnState::remove_pending_approval 会把通道取出，再把决定送回给当初等待的任务。

fn remove_pending_approval(
        &mut self,
        key: &str,
    ) -> Option<oneshot::Sender<ReviewDecision>>

作用：取出并移除一个正在等待的审批请求。它通常用在审批结果回来了之后，保证同一个审批不会被重复处理。

数据流：进去一个 key → 它到 pending_approvals 表里查找并删除这一项 → 出来是对应的一次性发送端，如果没找到就返回空；状态里也不再保留这个审批等待项。

调用关系：它和 TurnState::insert_pending_approval 配对使用。发起审批时先插入，收到审批结果时取出，然后外部流程用取出的通道把 ReviewDecision 送回去。

fn clear_pending_waiters(&mut self)

作用：一次性清掉这一轮里所有还在等回复的临时请求。通常用于一轮被取消、结束或需要收尾时，避免旧的等待项遗留到后面造成混乱。

数据流：进去不需要参数 → 它清空审批、权限申请、用户输入、外部服务询问、动态工具回复这几类等待表 → 出来没有返回值，但 TurnState 里这些未完成等待项都被移除。

调用关系：这是本轮状态的清场动作。其他地方如果决定当前任务不再继续，就会用它把各种待回复通道都丢掉，防止之后迟到的回复误伤新一轮流程。

fn insert_pending_request_permissions(
        &mut self,
        key: String,
        pending_request_permissions: PendingRequestPermissions,
    ) -> Option<PendingRequestPermissions>

作用：登记一个还在等待结果的权限申请。比如工具想访问某个环境或做某个敏感操作，系统需要先把申请挂起来等审查结果。

数据流：进去一个 key 和 PendingRequestPermissions；后者里面有回复通道、申请的权限内容、目标环境 → 它把这份申请放进 pending_request_permissions 表 → 出来是同 key 下被替换掉的旧申请，如果存在的话。

调用关系：权限请求发起方会先调用它存档。等权限审查结果回来时，TurnState::remove_pending_request_permissions 会把对应申请取出来，并用里面的通道把结果交回给等待的执行流程。

fn remove_pending_request_permissions(
        &mut self,
        key: &str,
    ) -> Option<PendingRequestPermissions>

作用：取出并移除一个权限申请等待项。这样权限回复到达后，系统能找到原来那次申请，并且不会重复处理。

数据流：进去一个 key → 它从 pending_request_permissions 表中删除匹配项 → 出来是原来的 PendingRequestPermissions，如果没有对应申请就返回空；状态表随之少掉这一项。

调用关系：它是 TurnState::insert_pending_request_permissions 的收尾动作。权限审查流程收到结果后用它找到申请，再把 RequestPermissionsResponse 送回给原先等待的任务。

fn insert_pending_user_input(
        &mut self,
        key: String,
        tx: oneshot::Sender<RequestUserInputResponse>,
    ) -> Option<oneshot::Sender<RequestUserInputResponse>>

作用：登记一个正在等待用户补充输入的请求。比如系统需要用户再确认一句话、补一个参数，就用它记录“这个问题还没答”。

数据流：进去一个 key 和一次性回复通道 → 它把通道放进 pending_user_input 表 → 出来是旧的同 key 通道，如果之前已经有一项；状态里新增或替换了这次等待用户输入的记录。

调用关系：当系统向用户发出补充输入请求时调用它。用户真正回答后，TurnState::remove_pending_user_input 会取出对应通道，把 RequestUserInputResponse 送回给等待的那段流程。

fn remove_pending_user_input(
        &mut self,
        key: &str,
    ) -> Option<oneshot::Sender<RequestUserInputResponse>>

作用：取出并移除一个等待用户输入的请求。它让用户的回答能准确回到当初提出问题的地方。

数据流：进去一个 key → 它在 pending_user_input 表里找到并删除对应项 → 出来是一次性回复通道，如果找不到就返回空；状态里不再记录这次用户输入等待。

调用关系：它和 TurnState::insert_pending_user_input 成对出现。一个负责挂号等回答，一个负责在回答来了之后取号并传回结果。

fn insert_pending_elicitation(
        &mut self,
        server_name: String,
        request_id: RequestId,
        tx: oneshot::Sender<ElicitationResponse>,
    ) -> Option<oneshot::Sender<Elicitat

作用：登记一个外部服务正在向系统“追问信息”的请求。这里的 elicitation 可以理解成某个连接的服务需要再问用户或系统一个问题，答案稍后才回来。

数据流：进去服务名、请求编号和一次性回复通道 → 它用“服务名 + 请求编号”当作复合钥匙，把通道存进 pending_elicitations 表 → 出来是旧的同钥匙通道，如果原来已有一项。

调用关系：当外部服务发起询问时，这个函数负责把等待关系记住。等回答回来时，TurnState::remove_pending_elicitation 会按同样的服务名和请求编号找到它。

fn remove_pending_elicitation(
        &mut self,
        server_name: &str,
        request_id: &RequestId,
    ) -> Option<oneshot::Sender<ElicitationResponse>>

作用：取出并移除一个外部服务询问的等待项。它用服务名和请求编号一起定位，避免不同服务或不同问题互相串线。

数据流：进去服务名和请求编号 → 它把这两个值组成查找钥匙，到 pending_elicitations 表里删除对应项；过程中会复制请求编号用于查表 → 出来是对应的一次性回复通道，找不到则为空。

调用关系：它接在 TurnState::insert_pending_elicitation 后面使用。外部服务的回答抵达时，系统靠它找到当时挂起的询问，再把 ElicitationResponse 交回去。

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

fn insert_pending_dynamic_tool(
        &mut self,
        key: String,
        tx: oneshot::Sender<DynamicToolResponse>,
    ) -> Option<oneshot::Sender<DynamicToolResponse>>

作用：登记一个动态工具的未完成调用。动态工具可以理解成运行时临时接入或变化的工具，它的结果不是马上到，所以要先记账。

数据流：进去一个 key 和一次性回复通道 → 它把通道存入 pending_dynamic_tools 表 → 出来是同 key 下原先的通道，如果存在；状态中记录了这个工具调用正在等待结果。

调用关系：动态工具被调用时会用它保存等待通道。工具结果回来后，TurnState::remove_pending_dynamic_tool 负责取出通道，把 DynamicToolResponse 传回等待者。

fn remove_pending_dynamic_tool(
        &mut self,
        key: &str,
    ) -> Option<oneshot::Sender<DynamicToolResponse>>

作用：取出并移除一个动态工具的等待项。这样工具结果回来时可以准确送达，而且同一结果不会被处理两次。

数据流：进去一个 key → 它从 pending_dynamic_tools 表中删除对应记录 → 出来是保存的回复通道，如果没有找到就返回空；状态里这次工具等待被清除。

调用关系：它是 TurnState::insert_pending_dynamic_tool 的配套收尾函数。动态工具完成后，外部流程调用它找到等待者，再把结果发回去。

fn accept_mailbox_delivery_for_current_turn(&mut self)

作用：把邮箱消息接收状态切回“可以并入当前轮”。简单说，就是告诉系统：接下来收到的子消息还能算进这一轮对话里。

数据流：进去没有参数 → 它调用 TurnState::set_mailbox_delivery_phase，把阶段设为 CurrentTurn → 出来没有返回值，但 mailbox_delivery_phase 被改成允许当前轮接收邮箱消息。

调用关系：它是一个更好读的快捷按钮，内部把实际设置工作交给 TurnState::set_mailbox_delivery_phase。某些后续明确属于同一轮的动作出现时，会用它重新打开当前轮的消息合并。

调用图：调用 1 个内部函数（set_mailbox_delivery_phase）。

fn accepts_mailbox_delivery_for_current_turn(&self) -> bool

作用：询问当前这一轮是否还接收邮箱消息。调用者可以用它决定迟到的子消息是马上并入当前请求，还是留到下一轮再处理。

数据流：进去没有参数，只读取当前状态 → 它检查 mailbox_delivery_phase 是否等于 CurrentTurn → 出来一个布尔值：true 表示还能并入当前轮，false 表示应该留给后面的轮次。

调用关系：消息分发或输入整理流程会在决定是否吸收邮箱消息前问它。它不改状态，只提供判断结果；状态本身由 TurnState::set_mailbox_delivery_phase 或 TurnState::accept_mailbox_delivery_for_current_turn 改。

fn set_mailbox_delivery_phase(&mut self, phase: MailboxDeliveryPhase)

作用：直接设置邮箱消息属于当前轮还是下一轮。它是控制“迟到消息怎么归类”的核心开关。

数据流：进去一个 MailboxDeliveryPhase，表示 CurrentTurn 或 NextTurn → 它把 mailbox_delivery_phase 字段改成这个值 → 出来没有返回值，但之后消息分发看到的规则会变。

调用关系：TurnState::accept_mailbox_delivery_for_current_turn 会调用它把阶段设回 CurrentTurn。其他流程也可以用它在当前轮已经输出最终内容后切到 NextTurn，避免继续扩展一个已经展示给用户的回答。

调用图：被 1 处调用（accept_mailbox_delivery_for_current_turn）。

fn record_granted_permissions(
        &mut self,
        environment_id: &str,
        permissions: AdditionalPermissionProfile,
    )

作用：记录这一轮在某个环境里已经获得的新权限，并和旧权限合并。这样同一轮后续操作可以复用刚刚批准过的权限，不必反复问。

数据流：进去一个环境 ID 和一份新增权限 → 它先取出这个环境之前已记录的权限，再调用 merge_permission_profiles 把旧权限和新权限合在一起 → 如果合并后有结果，就把它按环境 ID 存回 granted_permissions_by_environment_id。

调用关系：权限申请通过后会调用它更新本轮权限账本。后续工具或审查流程可以用 TurnState::granted_permissions 查询这些已批准权限，判断是否还需要再申请。

调用图：调用 1 个内部函数（merge_permission_profiles）。

fn granted_permissions(
        &self,
        environment_id: &str,
    ) -> Option<AdditionalPermissionProfile>

作用：查询某个环境在这一轮里已经拿到的额外权限。它让后续操作知道“之前已经批准过什么”。

数据流：进去一个环境 ID → 它到 granted_permissions_by_environment_id 表里查找对应权限，并复制一份返回 → 出来是一份 AdditionalPermissionProfile，如果这个环境还没有记录则为空；它不会改动状态。

调用关系：它通常跟 TurnState::record_granted_permissions 配合。前者负责写入权限账本，后者负责在工具调用或权限判断时读取这本账。

fn enable_strict_auto_review(&mut self)

作用：打开这一轮的严格自动审查模式。打开后，后续判断会把这一轮当成需要更谨慎审查的流程来处理。

数据流：进去没有参数 → 它把 strict_auto_review_enabled 设为 true → 出来没有返回值，但 TurnState 之后会记住这个开关已经打开。

调用关系：当某个入口或策略决定本轮必须严格审查时会调用它。后续流程通过 TurnState::strict_auto_review_enabled 查询这个开关，再决定是否走更严格的审查路线。

fn strict_auto_review_enabled(&self) -> bool

作用：查看这一轮是否已经启用严格自动审查。它给后续权限或工具执行判断提供一个简单的是/否信号。

数据流：进去没有参数，只读取当前状态 → 它返回 strict_auto_review_enabled 的当前值 → 出来一个布尔值；不会修改任何状态。

调用关系：它和 TurnState::enable_strict_auto_review 配套。一个负责打开开关，一个负责让其他流程在需要时检查这个开关。

fn invoke_tool(
        &'a self,
        _invocation: CodeModeNestedToolCall,
        cancellation_token: CancellationToken,
    ) -> ToolInvocationFuture<'a>

作用：这是默认的“工具调用处理器”。当代码里想调用外部工具，但外面没有真正提供工具时，它会一直等到取消，然后返回“不可用”的错误。

数据流：进去的是一次工具调用信息和一个取消令牌（一种通知任务该停下来的信号）→ 它不真正执行工具，只等待取消信号 → 出来的是错误文字，说明代码模式里的嵌套工具不可用。

调用关系：run_cell_control 在收到 RuntimeEvent::ToolCall 时会通过 delegate 调用工具；如果会话用的是默认代理，就会走到这里，最后把错误送回运行时。

调用图：外部调用 2 个（pin, cancelled）。

fn notify(
        &'a self,
        _call_id: String,
        _cell_id: CellId,
        _text: String,
        _cancellation_token: CancellationToken,
    ) -> NotificationFuture<'a>

作用：这是默认的“通知处理器”。代码发出的通知在没有外部接收者时，会被安全地当成成功处理掉。

数据流：进去的是调用编号、代码单元编号、通知文字和取消令牌 → 它不保存也不转发这些内容 → 出来是成功结果，不改动任何状态。

调用关系：run_cell_control 收到 RuntimeEvent::Notify 时会调用 delegate.notify；默认代理让通知不会因为没人接收而打断代码执行。

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

fn cell_closed(&self, _cell_id: &CellId)

作用：这是默认的“代码单元关闭提醒”。它什么也不做，用来保证即使没人关心关闭事件，流程也能正常结束。

数据流：进去的是已关闭的 cell_id → 它不读取额外信息，也不修改状态 → 没有返回值。

调用关系：run_cell_control 在清理完一个代码单元后会通知 delegate；默认代理接到通知后直接忽略。

fn create_session(
        &'a self,
        delegate: Arc<dyn CodeModeSessionDelegate>,
    ) -> CodeModeSessionProviderFuture<'a>

作用：它创建一个本进程内的代码模式会话。也就是说，不启动远程服务，直接在当前程序里组装 CodeModeService。

数据流：进去的是一个 delegate，也就是外部工具和通知的接收者 → 它用这个 delegate 构造 CodeModeService，并包装成通用会话接口 → 出来的是一个可共享的会话对象。

调用关系：上层需要新建代码模式会话时会调用 provider；它把真正的会话工作交给 CodeModeService::with_delegate。

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

fn new() -> Self

作用：创建一个最简单的代码模式服务，不连接任何真实外部工具。测试和不需要工具的场景会直接用它。

数据流：没有输入 → 它准备一个默认的 NoopCodeModeSessionDelegate → 出来是新的 CodeModeService，里面有空的共享值表、空的代码单元表和从 1 开始的编号器。

调用关系：它是 with_delegate 的简化入口；大量测试用它快速搭出一个可运行的会话。

调用图：被 29 处调用（date_locale_string_formats_with_icu_data, execute_to_pending_excludes_delayed_timeout_tool_calls_until_wait, execute_to_pending_identifies_tool_calls_in_paused_frontier, execute_to_pending_returns_completed_for_synchronous_results, execute_to_pending_returns_once_the_runtime_is_quiescent, generated_image_helper_appends_image_and_output_hint, image_helper_accepts_low_detail, image_helper_accepts_raw_mcp_image_block_with_original_detail, image_helper_rejects_raw_mcp_result_container, image_helper_rejects_unsupported_detail (+15 more)）；外部调用 2 个（new, with_delegate）。

fn with_delegate(delegate: Arc<dyn CodeModeSessionDelegate>) -> Self

作用：创建一个带外部代理的代码模式服务。这个代理负责接收通知、执行代码里发起的工具调用、知道代码单元何时关闭。

数据流：进去的是 delegate → 它初始化内部共享状态，包括 stored_values、cells、shutting_down 标记和 next_cell_id → 出来是可用于执行代码的 CodeModeService。

调用关系：InProcessCodeModeSessionProvider::create_session 和 CodeModeService::new 都依赖它；带真实工具能力的会话会从这里开始。

调用图：被 5 处调用（create_session, natural_completion_cleans_up_callbacks_before_responding, repeated_termination_is_rejected_while_callback_cleanup_is_pending, termination_cancels_pending_callbacks_before_responding, new）；外部调用 5 个（new, new, new, new, new）。

fn allocate_cell_id(&self) -> CellId

作用：给每次代码执行分配一个新的编号。这样 wait 或 terminate 才知道要找哪一个正在跑的代码单元。

数据流：它读取内部的递增数字 → 原子地加 1，避免并发时拿到重复编号 → 出来是字符串形式的 CellId。

调用关系：execute 和 execute_to_pending 在启动新代码单元前都会先调用它，然后把编号传给 start_cell。

调用图：调用 1 个内部函数（new）；被 2 处调用（execute, execute_to_pending）。

async fn execute_to_pending(
        &self,
        request: ExecuteRequest,
    ) -> Result<ExecuteToPendingOutcome, String>

作用：启动代码，并等到它“结束”或“暂时没事可做”。这适合想知道代码当前是否卡在等待工具、定时器或异步任务的场景。

数据流：进去的是 ExecuteRequest，里面有源码、工具列表、输出限制等 → 它分配 cell_id，启动运行时，并让运行时在 pending 状态暂停 → 出来是 Completed 最终结果，或者 Pending 暂停信息。

调用关系：它把启动工作交给 start_cell；后续 run_cell_control 会在运行时进入 Pending 或 Result 时把结果通过一次性通道送回来。

调用图：调用 2 个内部函数（allocate_cell_id, start_cell）；外部调用 2 个（ExecuteToPending, channel）。

async fn start_cell(
        &self,
        cell_id: CellId,
        request: ExecuteRequest,
        initial_response_tx: CellResponseSender,
        initial_yield_time_ms: Option<u64>,
        pendi

作用：真正启动一个代码单元。它把请求、共享值、消息通道和取消信号都接好，然后把运行时和控制循环同时安排起来。

数据流：进去的是 cell_id、执行请求、初始响应通道、是否设置初始让出时间、pending 模式 → 它复制当前共享值，启动底层运行时，把 cell handle 登记到 cells 表，再启动 run_cell_control → 成功时返回空结果，失败时返回错误文字。

调用关系：execute 和 execute_to_pending 都靠它开工；它调用 spawn_runtime 创建底层执行环境，并把后续所有事件处理交给 run_cell_control。

调用图：调用 2 个内部函数（spawn_runtime, run_cell_control）；被 2 处调用（execute, execute_to_pending）；外部调用 8 个（clone, new, new, new, clone, format!, unbounded_channel, spawn）。