第4章：Agent Loop —— Task / Turn / Step 三级循环

Task（任务）
 └── Turn（轮次） ← run_turn，一个 loop
      └── Sampling Request（采样请求） ← run_sampling_request，又一个 loop（重试）
           └── try_run_sampling_request ← 一次真实的模型请求 + 流式消费 + 工具执行

pub(crate) trait SessionTask: Send + Sync + 'static {
    fn kind(&self) -> TaskKind;
    fn span_name(&self) -> &'static str;
    fn run(self: Arc<Self>, session: Arc<Session>, ctx: Arc<TurnContext>,
           input: Vec<TurnInput>, cancellation_token: CancellationToken)
        -> impl Future<Output = SessionTaskResult> + Send;
    fn abort(&self, session: Arc<Session>, ctx: Arc<TurnContext>)
        -> impl Future<Output = ()> + Send { /* 默认空实现 */ }
}

pub async fn spawn_task<T: SessionTask>(…) {
    self.abort_all_tasks(TurnAbortReason::Replaced).await;
    self.clear_connector_selection().await;
    self.start_task(…).await;
}

pub(crate) struct RunningTask {
    pub(crate) done: Arc<Notify>,
    pub(crate) kind: TaskKind,
    pub(crate) task: Arc<dyn AnySessionTask>,
    pub(crate) cancellation_token: CancellationToken,
    pub(crate) handle: AbortOnDropHandle<()>,
    pub(crate) turn_context: Arc<TurnContext>,
    …
}

pub(crate) async fn run_turn(
    sess: Arc<Session>,
    turn_context: Arc<TurnContext>,
    input: Vec<TurnInput>,
    prewarmed_client_session: Option<ModelClientSession>,
    cancellation_token: CancellationToken,
) -> CodexResult<Option<String>> {

pub(crate) struct StepContext {
    pub(crate) turn: Arc<TurnContext>,
    pub(crate) model_info: Arc<ModelInfo>,              // 这次用哪个模型、什么能力
    pub(crate) reasoning_effort: Option<ReasoningEffort>,
    pub(crate) reasoning_summary: ReasoningSummary,
    pub(crate) service_tier: Option<String>,
    pub(crate) approval_policy: AskForApproval,         // 这次的审批策略
    pub(crate) approvals_reviewer: ApprovalsReviewer,   // 谁来审批（人 or Guardian）
    pub(crate) session_telemetry: SessionTelemetry,
    pub(crate) environments: TurnEnvironmentSnapshot,
    pub(crate) selected_capability_roots: Vec<ResolvedSelectedCapabilityRoot>,
    pub(crate) executor_capability_discovery: Option<Arc<ExecutorCapabilityDiscoverySnapshot>>,
    pub(crate) mcp: Arc<McpBinding>,                    // 这次绑定的 MCP 连接与目录
    pub(crate) tool_router: Arc<ToolRouter>,            // 这次广告出去、也用来执行的工具集
    pub(crate) loaded_agents_md: Option<Arc<LoadedAgentsMd>>,  // 这次看到的 AGENTS.md
}

① 取待处理输入（用户在模型跑的时候插的话）
    ↓
② 跑钩子并记录输入
    ↓
③ 记录 rollout 预算提醒 / 当前时间提醒
    ↓
④ 拿 step_context（首圈复用入场时冻的，之后按需重建）
    ↓
⑤ run_sampling_request ← 真正的模型交互在这里
    ↓
⑥ 看结果决定：压缩？继续？停？

let needs_follow_up = model_needs_follow_up || has_pending_input;
let token_limit_reached = token_status.token_limit_reached;

let should_roll_over = needs_follow_up
    && (sess.take_new_context_window_request().await || token_limit_reached);

if should_roll_over {
    run_auto_compact(…, CompactionReason::ContextLimit, CompactionPhase::MidTurn).await?;
    continue;                       // 压缩完接着跑
}

if !needs_follow_up {
    let stop_outcome = run_turn_stop_hooks(…).await;
    if stop_outcome.should_block { …; continue; }   // Stop 钩子把它拽回来了
    if stop_outcome.should_stop { break; }
    break;                          // 正常结束
}
continue;                           // 模型还要继续

sess.send_event(&turn_context, EventMsg::Warning(WarningEvent {
    message: "Stop hook requested continuation without a prompt; ignoring the block.".to_string(),
})).await;

let max_retries = turn_context.provider.info().stream_max_retries();
let mut retry_state = ResponsesStreamRetryState::default();
loop {
    let prompt = build_prompt(prompt_input, step_context.as_ref(), base_instructions.clone());
    let err = match try_run_sampling_request(…).await {
        Ok(output) => return Ok((output, original_input.unwrap_or(prompt.input))),
        Err(err) => match err.details() {
            CodexErrorDetails::ContextWindowExceeded => { … return Err(err); }   // 不重试
            CodexErrorDetails::UsageLimitReached(e) => { … return Err(err); }    // 不重试
            _ => err,
        },
    };
    if !err.is_retryable() { return Err(err); }
    handle_retryable_response_stream_error(&mut retry_state, max_retries, err, …).await?;
    turn_context.turn_timing_state.record_sampling_retry();
}

let prompt_input = if let Some(input) = initial_input.take() {
    input
} else {
    sess.clone_history().await.for_prompt(&step_context.model_info.input_modalities)
};

let pending_input = if can_drain_pending_input {
    sess.input_queue.get_pending_input(&sess.active_turn).await.0
} else {
    Vec::new()
};

cd codex/codex-rs

# 1. 主循环全文（400 行，值得完整读一遍）
sed -n '153,590p' core/src/session/turn.rs

# 2. SessionTask trait 与四个实现
sed -n '176,220p' core/src/tasks/mod.rs
ls core/src/tasks/

# 3. StepContext 的 14 个字段
cat core/src/session/step_context.rs

# 4. 采样层的重试逻辑
sed -n '1340,1440p' core/src/session/turn.rs

# 5. 找出所有 TODO —— 原作者还没想清楚的地方
grep -rn 'TODO' core/src/session/ | head -20

codex exec "列出当前目录的文件" --json 2>&1 | head -40