pub(crate) struct Session { // 会话本体：一个 thread 的运行时容器，全局唯一、不可克隆    pub(crate) thread_id: ThreadId, // "thread"=对话线程；session 是它的执行体，ID 贯穿事件与日志    pub(super) tx_event: Sender<Event>, // 事件出口：所有 UI 可见事件都从这条 channel 流出    pub(super) agent_status: watch::Sender<AgentStatus>, // 状态广播（PendingInit/Running…）：订阅者随时取最新值    pub(super) state: Mutex<SessionState>, // 可变会话状态（历史、token 账本）——唯一需要锁的"大脑"    pub(super) thread_settings_persistence: Semaphore, // 串行化设置提交与持久化，存储 I/O 不阻塞运行时读    pub(super) features: ManagedFeatures, // 特性开关：注释明确"会话生命周期内不变"    pub(crate) active_turn: Mutex<Option<ActiveTurn>>, // 当前正在跑的 turn（至多一个）——单任务约束的落点    pub(crate) input_queue: InputQueue, // 排队中的用户输入：turn 运行中可插入（steering）    pub(crate) services: SessionServices, // 共享服务集合：exec policy、MCP、网络代理等依赖}

pub(crate) fn spawn( // 对外入口：隐藏具体启动 future，调用方只拿到 BoxFuture    args: SessionSpawnArgs, // 40+ 个启动依赖打包成一个参数结构体（config、auth、models_manager…）) -> BoxFuture<'static, CodexResult<(Arc<Self>, SessionIo)>> { // 返回 (会话本体, I/O 端点) 二元组    Box::pin(async move {        let parent_trace = match args.parent_trace { // 父级 W3C trace carrier：跨进程串联分布式追踪            Some(trace) => {                if codex_otel::context_from_w3c_trace_context(&trace).is_some() { // 先校验格式合法                    Some(trace) // 合法才继承——防止脏数据污染 span 树                } else {                    warn!("ignoring invalid thread spawn trace carrier"); // 非法就降级为无父级：只告警，不失败                    None                }            }            None => None,        };        let thread_spawn_span = info_span!("thread_spawn", otel.name = "thread_spawn"); // 本次启动的根 span        if let Some(trace) = parent_trace.as_ref() {            let _ = set_parent_from_w3c_trace_context(&thread_spawn_span, trace); // 把父 trace 挂到本 span        }        Self::spawn_internal(SessionSpawnArgs { parent_trace, ..args }) // 真正初始化在 spawn_internal（40+ 步）            .instrument(thread_spawn_span) // 整个初始化过程都记在这个 span 下            .await    })}

let base_instructions = config // 三级优先级：显式配置 > 历史继承 > 模型模板    .base_instructions    .clone()    .or_else(|| conversation_history.get_base_instructions().map(|s| s.text)) // resume/fork 时沿用原会话指令，保证行为连续    .unwrap_or_else(|| model_info.get_model_instructions(config.personality)); // 都没有才用模型自带模板（按 personality 渲染）

base_instructions 三级优先级（mod.rs L718-722）

▼

▼

pub(crate) struct SessionState { // 会话级可变状态：从 Session 上拆出来的"账本区"    pub(crate) session_configuration: SessionConfiguration, // 当前生效的配置快照（可被设置更新整体替换）    pub(crate) history: ContextManager, // 对话历史 + token 信息——上下文管理的核心（第 13 讲主角）    pub(crate) latest_rate_limits: Option<RateLimitSnapshot>, // 最近一次限流快照，供 UI 展示剩余额度    previous_turn_settings: Option<PreviousTurnSettings>, // 上一个常规 turn 的设置：跨 turn 的模型/realtime 衔接依据    auto_compact_window: AutoCompactWindow, // 自动压缩窗口计数与预填状态（第 14 讲主角）    pub(crate) reasoning_effort_pin: ReasoningEffortPin, // effort 钉住机制：prewarm/采样后固定，防中途漂移    pub(crate) startup_prewarm: Option<SessionStartupPrewarmHandle>, // 启动预热句柄：首个 turn 直接复用，省冷启动    granted_permissions_by_environment_id: HashMap<String, AdditionalPermissionProfile>, // 按环境累计的已授权权限（审批通过后只增不减）}

pub(super) async fn submission_loop( // 会话主循环：所有 Op 的唯一串行入口    sess: Arc<Session>, // 会话本体，Arc 共享给每个 handler    config: Arc<Config>, // 启动时的配置快照，供需要原始配置的分支使用    rx_sub: Receiver<Submission>, // 有界 channel；发送端全 drop → recv Err → 循环退出、会话终结) {    let mut shutdown_received = false; // Op::Shutdown 置位后跳出主循环（文件尾处理）    while let Ok(sub) = rx_sub.recv().await { // 阻塞等下一个提交——所有操作天然串行，无并发竞态        let dispatch_span = submission_dispatch_span(&sub); // 每个 op 一个 span：追踪里能看到完整分发链        let should_exit = async {            match sub.op { // 一个大 match 覆盖全部操作类型（以下节选）                Op::Interrupt => { // 用户按 Esc / UI 点停止                    interrupt(&sess).await; // 取消当前 turn：cancellation token + 清 pending waiters                    false // 中断不退出会话，继续等下一个 op                }                Op::TurnInput { request, mode, reply } => { // steering：turn 运行中插入新输入                    let result = turn_input::handle(&sess, *request, mode, sub.id.clone()).await; // 只做路由决定（入队 or 拒绝）                    let _ = reply.send(result); // oneshot 回传结果，调用方不阻塞等待执行                    false                }            };        }.instrument(dispatch_span).await;    }}

pub struct TurnContext { // 一个 turn 的冻结快照：turn 内所有请求共享同一份"世界观"    pub(crate) sub_id: String, // 提交 ID：事件、审批、日志都靠它对齐到这次 turn    pub config: Arc<Config>, // 本 turn 生效的配置（含 token budget 解析结果）    pub(crate) initial_settings: Arc<ResolvedStepSettings>, // 冻结的初始设置——legacy 消费者读这份    pub(super) current_settings: ArcSwap<ResolvedStepSettings>, // 可原子替换的设置快照：turn 中改模型/effort 走这里    pub(crate) environments: TurnEnvironmentSnapshot, // 本 turn 选定的执行环境（cwd、沙箱、权限）    #[deprecated(note = "use the selected turn environment cwd instead")]    pub(crate) cwd: AbsolutePathBuf, // 会话级工作目录：相对路径与沙箱策略都基于它解析    pub(crate) network: Option<NetworkProxy>, // 网络代理句柄：有则走白名单代理，无则直连/禁网    pub(crate) dynamic_tools: Vec<DynamicToolSpec>, // 动态工具定义：thread 启动时定死并持久化到 rollout    pub(crate) turn_metadata_state: Arc<TurnMetadataState>, // 遥测元数据：session/thread/sub_id、权限画像等    pub(crate) terminal_error: Arc<Mutex<Option<ErrorEvent>>>, // turn 级终态错误：首个致命错误落这里，供 UI 收尾展示}

let mut per_turn_config = per_turn_config; // 拷贝一份 turn 私有配置，后续修改不影响会话级let configured_token_budget = per_turn_config.token_budget.clone(); // 先记下用户显式配置的 budget（供 sparse patch 用）let use_model_token_budget_defaults = // TokenBudget 特性开 && 用户没写任何显式设置 → 才允许吃模型默认值    per_turn_config.features.enabled(Feature::TokenBudget)        && !has_explicit_settings(&per_turn_config);per_turn_config.token_budget = resolve_token_budget( // 三级解析：显式配置 > 模型默认 > 无 budget    configured_token_budget.as_ref(),    use_model_token_budget_defaults,    model_info,);if step_settings.reasoning_effort() == Some(&ReasoningEffort::Persistent) { // Persistent effort：跨 turn 保持，需补时间提醒默认值    super::time_reminder::apply_persistent_defaults(&mut per_turn_config);}per_turn_config.service_tier = step_settings.service_tier.clone(); // service tier 以设置快照为准（已按模型能力过滤）let permission_profile = environments.permission_profile_or_else(|| { // 环境级权限优先；没选环境才回退配置里的    per_turn_config.permissions.effective_permission_profile()});

pub(super) async fn new_turn_with_sub_id_if( // 带准入谓词的 turn 构造：should_start 决定"要不要开这个 turn"    &self,    sub_id: String,    updates: SessionSettingsUpdate, // 本次提交携带的设置更新（模型、effort、审批策略…）    options: NewTurnContextOptions,    should_start: impl FnOnce(&SessionConfiguration, &SessionConfiguration) -> bool + Send, // (旧配置,新配置)->是否放行；必须快且无副作用) -> CodexResult<Option<(Arc<TurnContext>, ThreadSettingsSnapshot)>> {    let commit = match self.update_settings_if(updates, should_start).await { // ① 先原子提交设置（锁内完成）        Ok(Some(commit)) => commit,        Ok(None) => return Ok(None), // 谓词拒绝：不构造 turn，也不报错——静默跳过是合法路径        Err(error) => { /* …发 ErrorEvent 给 UI 并返回 InvalidRequest（节选） */ }    };    let mut configuration = commit.configuration; // ② 拿到已提交的配置快照（此时锁已释放）    if let Some(service_tier) = service_tier_for_turn { // turn 级 tier 覆盖：只改这份拷贝，不落线程设置        Arc::make_mut(&mut configuration.step_settings).service_tier = Some(service_tier);    }    let turn_context = self.new_turn_from_configuration(sub_id, configuration, options) // ③ 锁外构造 TurnContext（重活不占锁）        .await;    Ok(Some((turn_context, commit.snapshot)))}

async fn update_settings_if( // 设置提交的唯一入口：锁内校验+替换，锁外做副作用    &self,    updates: SessionSettingsUpdate, // 本次要应用的稀疏更新（模型、effort、审批策略…）    should_commit: impl FnOnce(&SessionConfiguration, &SessionConfiguration) -> bool + Send, // (旧配置,新配置)->是否放行；必须快且无副作用) -> ConstraintResult<Option<SessionSettingsCommit>> {    let notify_config_contributors = !self.services.extensions.config_contributors().is_empty(); // 有扩展订阅配置变化 → 锁外要发通知    let (commit, previous_config, new_config, permission_profile_changed, mcp_inputs_changed) = {        let mut state = self.state.lock().await; // ── 锁内段开始：临界区只做纯数据操作        let updated = match self.apply_session_settings(&state.session_configuration, &updates) { // 应用更新 + managed 约束校验            Ok(updated) => updated,            Err(err) => { warn!("rejected session settings update: {err}"); return Err(err); } // 违反企业约束 → 直接拒绝，不半提交        };        if !should_commit(&state.session_configuration, &updated) { return Ok(None); } // 准入谓词在锁内跑：看到的必是最新状态        let permission_profile_changed = /* …比较新旧权限画像（节选） */; // 变了 → 锁外要重建网络代理        state.session_configuration = updated; // 原子替换会话配置——下一把锁拿到的就是新值        let commit = SessionSettingsCommit { configuration: ..., snapshot: ... }; // 提交结果 + 持久化快照一起带出临界区    }; // ── 锁在这里释放：后面的 I/O 不再阻塞任何读状态的人    self.emit_config_changed_contributors(previous_config.as_ref(), new_config.as_ref()); // 副作用①：通知扩展配置已变    if permission_profile_changed { self.refresh_managed_network_proxy_for_current_permission_profile().await; } // 副作用②：权限变了 → 重建代理规则    if mcp_inputs_changed { self.schedule_mcp_prewarm(); } // 副作用③：MCP 输入变了 → 预热连接    Ok(Some(commit))}

pub(crate) struct StepSettings { // "选了什么"：用户/客户端的原始选择，可被 sparse update 修改    pub(crate) collaboration_mode: CollaborationMode, // 模型 + reasoning effort（协作模式）    pub(crate) reasoning_summary: Option<ReasoningSummary>, // None = 跟随钉住模型的默认值    pub(crate) service_tier: Option<String>, // 归一化后的请求 tier；解析时再按模型能力过滤    pub(crate) approval_policy: Constrained<AskForApproval>, // 审批策略：Constrained 包装保证只能取 managed 允许的值}pub(crate) struct ResolvedStepSettings { // "实际发什么"：选择 + 钉住的模型元数据 → 请求级有效值（不可变快照）    selected: Arc<StepSettings>, // 保留原始选择：后续 sparse patch 基于它合并，不能从 effective 值反推    pub(crate) model_info: Arc<ModelInfo>, // 钉住的模型元数据（上下文窗口、默认 effort…）    pub(crate) reasoning_summary: ReasoningSummary, // 有效值 = 配置值 or 模型默认    pub(crate) service_tier: Option<String>, // 有效 tier：按 feature + 模型支持过滤后的结果}

pub(super) async fn apply_update( // 稀疏更新：只改请求的字段，其余继承；模型没变就复用元数据（省一次目录查询）    &self,    update: &StepSettingsUpdate,    constraints: &StepSettingsConstraints<'_>,    models_manager: &dyn ModelsManager,    overrides: &ModelInfoOverrides,    personality_enabled: bool,    fast_mode_enabled: bool,) -> ConstraintResult<Self> {    let selected = self.selected.apply(update, constraints)?; // ① 合并 + 约束校验（含 auto-review 强制项）    let model_info = if selected.collaboration_mode.model() == self.selected.collaboration_mode.model() // 模型没变…        && selected.personality == self.selected.personality // …且 personality 没变    {        Arc::clone(&self.model_info) // → 直接复用旧元数据：避免重复查 models manager    } else {        Arc::new(selected.resolve_model_info(models_manager, overrides, personality_enabled).await) // 变了才重新解析 ModelInfo    };    let mut next = Self::new(Arc::new(selected), model_info, fast_mode_enabled); // ② 从新选择 + 元数据推导有效值    next.mcp_approvals_reviewer_override = update.approvals_reviewer.or(self.mcp_approvals_reviewer_override); // MCP reviewer 覆盖：新值优先，否则继承    Ok(next)}

pub(crate) struct ActiveTurn { // "当前正在跑的 turn"——Session 注释：一个会话至多 1 个运行任务    pub(crate) task: Option<RunningTask>, // None = 空闲；Some = 有任务在跑（Regular/Review/Compact）    pub(crate) turn_state: Arc<Mutex<TurnState>>, // turn 级可变状态：pending 审批、输入队列…}pub(crate) struct RunningTask { // 运行中任务的"档案袋"：取消、等待、遥测全挂这里    pub(crate) done: Arc<Notify>, // 任务完成信号：等 turn 结束的调用方被 notify 唤醒    pub(crate) kind: TaskKind, // Regular / Review / Compact——决定收尾逻辑差异    pub(crate) task: Arc<dyn AnySessionTask>, // 具体执行体（trait object）：turn loop、review、compact 都实现它    pub(crate) cancellation_token: CancellationToken, // 取消令牌：Interrupt op 从这里扇出到所有子任务    pub(crate) handle: AbortOnDropHandle<()>, // drop 即 abort——会话销毁时兜底杀掉残留任务    pub(crate) turn_context: Arc<TurnContext>, // 该 turn 的冻结快照（事件、日志靠 sub_id 对齐）}pub(crate) struct TurnState { // turn 内所有"等待外部回答"的挂起点集中登记处    pending_approvals: HashMap<String, oneshot::Sender<ReviewDecision>>, // 工具审批：key=call id，用户决定后 send 唤醒执行方    pending_user_input: HashMap<String, oneshot::Sender<AcceptedUserInputResponse>>, // request_user_input 挂起等待    pending_elicitations: HashMap<(String, RequestId), oneshot::Sender<ElicitationResponse>>, // MCP elicitation：(server, req_id) 双键定位    pub(crate) pending_input: TurnInputQueue, // steering 输入队列：turn 运行中插入、下个请求边界消费    mailbox_delivery_phase: MailboxDeliveryPhase, // CurrentTurn/NextTurn 状态机：子 agent 邮件何时并入（见源码注释）}

turn 准入路径（本讲主线）

▼

▼

▼

▼