🔁 runLoop 主循环 ★

// Effect.fn("SessionPrompt.run") 是 Effect 的命名函数封装
const runLoop: (sessionID: SessionID) => Effect.Effect<SessionV1.WithParts> =
  Effect.fn("SessionPrompt.run")(function* (sessionID: SessionID) {
    const ctx = yield* InstanceState.context   // 获取运行上下文
    let structured: unknown
    let step = 0                                // 步数计数器（对应 F3 的步数上限）
    const session = yield* sessions.get(sessionID).pipe(Effect.orDie)

    while (true) {                              // ★ 主循环！对应 F3 的 Agent 循环
      yield* status.set(sessionID, { type: "busy" })
      // ... 每轮的逻辑（下面逐段拆解）
    }

    yield* compaction.prune({ sessionID }).pipe(Effect.ignore, Effect.forkIn(scope))
    return yield* lastAssistant(sessionID)
  })

while (true) {
  yield* status.set(sessionID, { type: "busy" })   // 标记会话为忙碌

  // ① 读取过滤后的消息历史（LG2 的 messages 列表，对应 Checkpointer 加载）
  let msgs = yield* MessageV2.filterCompactedEffect(sessionID)

  // ② 找出最新的 user / assistant 消息
  const { user: lastUser, assistant: lastAssistant,
          finished: lastFinished, tasks } = MessageV2.latest(msgs)

  // ③ 判断最后的 assistant 是否还有未处理工具调用
  const hasToolCalls =
    lastAssistantMsg?.parts.some(
      (part) => part.type === "tool"
        && !part.metadata?.providerExecuted
        && !isOrphanedInterruptedTool(part),
    ) ?? false

  // ★ 退出条件：assistant 已 finish + 不是 tool-calls + 没有待执行工具 + user 在前
  if (
    lastAssistant?.finish &&                              // 模型说停了
    !["tool-calls"].includes(lastAssistant.finish) &&     // 且不是因为要调工具
    !hasToolCalls &&                                      // 且没有待执行工具
    lastUser.id < lastAssistant.id                        // 且 assistant 是最新的
  ) {
    // （处理孤儿中断工具的边缘情况...）
    yield* Effect.logInfo("exiting loop", { "session.id": sessionID })
    break                          // ★ 退出循环！对应 AgentFinish
  }

  step++                          // 步数 +1（F3 的步数计数）

  const task = tasks.pop()   // 取出待处理任务

  // ① 子任务（task 工具派生的子 agent）
  if (task?.type === "subtask") {
    yield* handleSubtask({ task, model, lastUser, sessionID, session, msgs })
    continue                  // 处理完进入下一轮
  }

  // ② 上下文压缩任务（token 溢出时触发，对应 F2 的记忆管理）
  if (task?.type === "compaction") {
    const result = yield* compaction.process({ messages: msgs, ... })
    if (result === "stop") break
    continue
  }

  // ③ 自动检测 token 溢出 → 触发 compaction
  if (lastFinished && lastFinished.summary !== true
      && (yield* compaction.isOverflow({ tokens: lastFinished.tokens, model }))) {
    yield* compaction.create({ sessionID, ..., auto: true })
    continue
  }

  // ① 取 agent 配置（提示 + 模型 + 权限，对应 LG8 的 agent 定义）
  const agent = yield* agents.get(lastUser.agent)
  const maxSteps = agent.steps ?? Infinity     // 步数上限（F3 的停止条件②）
  const isLastStep = step >= maxSteps

  // ② 应用 plan 模式提醒等
  msgs = yield* SessionReminders.apply({ messages: msgs, agent, session })

  // ③ 创建空 assistant 消息（待填充）
  const msg: SessionV1.Assistant = { role: "assistant", ... }
  yield* sessions.updateMessage(msg)

  // ④ 创建 processor handle（处理 LLM 流事件）
  const handle = yield* processor.create({ assistantMessage: msg, sessionID, model })

  // ⑤ 主逻辑
  const outcome = yield* Effect.gen(function* () {
    // 解析工具（OC3 详讲：把 Tool.Def 包成 AI SDK tool）
    const tools = yield* SessionTools.resolve({ agent, session, model, processor: handle, ... })

    // 组装 system prompt（OC5：env + instructions + mcp + skills）
    const [skills, env, instructions, mcpInstructions, modelMsgs] = yield* Effect.all([
      sys.skills(agent), sys.environment(model), instruction.system(),
      sys.mcp(agent, session.permission), MessageV2.toModelMessagesEffect(msgs, model),
    ])
    const system = [...env, ...instructions, ...(mcpInstructions ? [mcpInstructions] : []),
                     ...(skills ? [skills] : [])]

    // ★ 调用 LLM！handle.process 内部调 LLM.Service.stream（OC1 的双运行时）
    const result = yield* handle.process({
      user: lastUser, agent, permission: session.permission,
      system, messages: [...modelMsgs, ...(isLastStep ? [MAX_STEPS_PROMPT] : [])],
      tools, model,
    })

    // 根据 result 决定 break 还是 continue
    if (result === "stop") return "break"
    if (result === "compact") {
      yield* compaction.create({ sessionID, ..., auto: true, overflow: !handle.message.finish })
    }
    return "continue"
  })

  if (outcome === "break") break    // 退出
  continue                          // 否则进入下一轮

// 1. yield* —— Effect 版的 await（在生成器里）
const agent = yield* agents.get(lastUser.agent)

// 2. Effect.gen —— 把生成器变成 Effect（类似 async function）
const outcome = yield* Effect.gen(function* () { ... })

// 3. Effect.all —— 并发执行多个 Effect（对应 RunnableParallel）
const [skills, env, instructions, mcpInstructions, modelMsgs] =
  yield* Effect.all([sys.skills(agent), sys.environment(model), ...])

// 4. .pipe(Effect.onInterrupt(...)) —— 中断时的清理（对应 AbortController）
const handle = yield* processor.create({...})
  .pipe(Effect.onInterrupt(() => finalizeInterruptedAssistant))

// 5. Effect.forkIn —— 后台异步执行（不阻塞主循环）
yield* title({...}).pipe(Effect.ignore, Effect.forkIn(scope))

const loop = Effect.fn("SessionPrompt.loop")(function* (input) {
  // ensureRunning：如果该 session 已有循环在跑，排队等待
  // 这保证了【单会话串行】，不会并发修改状态
  return yield* state.ensureRunning(
    input.sessionID,
    lastAssistant(input.sessionID),
    runLoop(input.sessionID),   // 真正的 runLoop
  )
})