async function runLoop(
  initialContext: AgentContext,
  newMessages: AgentMessage[],
  initialConfig: AgentLoopConfig,
  signal: AbortSignal | undefined,
  emit: AgentEventSink,
  streamFn?: StreamFn,
  runtime?: AgentCoreStreamRuntimeDeps,
): Promise<void> {
  let currentContext = initialContext;
  let config = initialConfig;
  let firstTurn = true;
  // 外层循环开始前，先检查是否有 steering 消息
  let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];

  // ---- 外层循环：处理意图链 ----
  while (true) {
    let hasMoreToolCalls = true;

    // ---- 内层循环：处理因果链（工具调用链）----
    while (hasMoreToolCalls || pendingMessages.length > 0) {
      // ... 处理 pendingMessages、调用 LLM、执行工具 ...
    }

    // 内层循环结束后，检查是否有 follow-up 消息
    const followUpMessages = (await config.getFollowUpMessages?.()) || [];
    if (followUpMessages.length > 0) {
      // 有后续消息，重新进入内层循环
      pendingMessages = followUpMessages;
      continue; // 关键：continue 回到外层循环顶部，开启新轮次
    }

    break; // 没有更多消息，退出外层循环
  }
}

private readonly steeringQueue: PendingMessageQueue;
private readonly followUpQueue: PendingMessageQueue;

// 构造函数中初始化
constructor(options: AgentOptions = {}) {
  this.steeringQueue = new PendingMessageQueue(options.steeringMode ?? "one-at-a-time");
  this.followUpQueue = new PendingMessageQueue(options.followUpMode ?? "one-at-a-time");
}

// 注入 steer 消息
steer(message: AgentMessage): void {
  this.steeringQueue.enqueue(message);
}

// 注入 followUp 消息
followUp(message: AgentMessage): void {
  this.followUpQueue.enqueue(message);
}

getSteeringMessages: async () => {
  // 首次轮次跳过 steering 检查（第一次应该是处理用户输入的 prompt）
  if (skipInitialSteeringPoll) {
    skipInitialSteeringPoll = false;
    return [];
  }
  return this.steeringQueue.drain();
},
getFollowUpMessages: async () => this.followUpQueue.drain(),

drain(): AgentMessage[] {
  if (this.mode === "all") {
    const drained = this.messages.slice();
    this.messages = [];
    return drained; // 一次排空所有消息
  }
  // one-at-a-time: 每次只取第一条，剩下的留到后续轮次
  const first = this.messages[0];
  if (!first) return [];
  this.messages = this.messages.slice(1);
  return [first];
}

export function agentLoop(
  prompts: AgentMessage[],
  context: AgentContext,
  config: AgentLoopConfig,
  signal?: AbortSignal,
  streamFn?: StreamFn,
  runtime?: AgentCoreStreamRuntimeDeps,
): EventStream<AgentEvent, AgentMessage[]> {
  const stream = createAgentStream();

  // 异步执行，但立即返回 stream
  void runAgentLoop(prompts, context, config, async (event) => {
    stream.push(event); // 每产生一个事件就推入 stream
  }, signal, streamFn, runtime)
    .then((messages) => {
      stream.end(messages); // 完成后结束 stream，附带最终结果
    })
    .catch((error: unknown) => {
      pushLoopFailure(stream, config, error, signal?.aborted === true);
    });

  return stream; // 立即返回，不等待执行完毕
}

export type AgentEvent =
  | { type: "agent_start" }
  | { type: "agent_end"; messages: AgentMessage[] }
  | { type: "turn_start" }
  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
  | { type: "message_start"; message: AgentMessage }
  | { type: "message_update"; message: AgentMessage; ... }
  | { type: "message_end"; message: AgentMessage }
  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: unknown }
  | { type: "tool_execution_update"; ... }
  | { type: "tool_execution_end"; ... };

const nextTurnSnapshot = await config.prepareNextTurn?.(nextTurnContext);
if (nextTurnSnapshot) {
  currentContext = nextTurnSnapshot.context ?? currentContext;
  const nextModel = nextTurnSnapshot.model ?? config.model;
  const nextThinkingLevel = nextTurnSnapshot.thinkingLevel ?? config.thinkingLevel;

  config = Object.assign({}, config, {
    model: nextModel,
    thinkingLevel: nextThinkingLevel,
    reasoning: nextReasoning,
  });
}

export function agentLoopContinue(...): EventStream<...> {
  if (context.messages.length === 0) {
    throw new Error("Cannot continue: no messages in context");
  }
  if (context.messages[context.messages.length - 1].role === "assistant") {
    throw new Error("Cannot continue from message role: assistant");
  }
  // ...
}

async continue(): Promise<void> {
  const lastMessage = this.mutableState.messages[this.mutableState.messages.length - 1];
  if (lastMessage.role === "assistant") {
    const queuedSteering = this.steeringQueue.drain();
    if (queuedSteering.length > 0) {
      await this.runPromptMessages(queuedSteering, { skipInitialSteeringPoll: true });
      return;
    }
    const queuedFollowUps = this.followUpQueue.drain();
    if (queuedFollowUps.length > 0) {
      await this.runPromptMessages(queuedFollowUps);
      return;
    }
    throw new Error("Cannot continue from message role: assistant");
  }
  await this.runContinuation();
}

function createMutableAgentState(
  initialState?: Partial<Omit<AgentState, "pendingToolCalls" | "isStreaming" | "streamingMessage" | "errorMessage">>,
): MutableAgentState {
  let tools = initialState?.tools?.slice() ?? []; // 注意 .slice()！
  let messages = initialState?.messages?.slice() ?? []; // 注意 .slice()！

  return {
    get tools() { return tools; },
    set tools(nextTools: AgentTool[]) {
      tools = nextTools.slice(); // 每次 set 都 .slice() 创建新数组
    },
    get messages() { return messages; },
    set messages(nextMessages: AgentMessage[]) {
      messages = nextMessages.slice(); // 每次 set 都 .slice() 创建新数组
    },
    // ...
  };
}

const myTools = agent.state.tools;
myTools.push(newTool); // ❌ 直接修改了内部数组！

private createContextSnapshot(): AgentContext {
  return {
    systemPrompt: this.mutableState.systemPrompt,
    messages: this.mutableState.messages.slice(), // 拷贝
    tools: this.mutableState.tools.slice(),       // 拷贝
  };
}

private async processEvents(event: AgentEvent): Promise<void> {
  // 第一步：根据事件类型更新内部状态
  switch (event.type) {
    case "agent_start":
    case "turn_start":
    case "tool_execution_update":
      break; // 这些事件不需要更新状态

    case "message_start":
      this.mutableState.streamingMessage = event.message;
      break;

    case "message_end":
      this.mutableState.streamingMessage = undefined;
      this.mutableState.messages.push(event.message); // 消息正式加入历史
      break;

    case "tool_execution_start":
      const pendingToolCalls = new Set(this.mutableState.pendingToolCalls);
      pendingToolCalls.add(event.toolCallId);
      this.mutableState.pendingToolCalls = pendingToolCalls;
      break;

    case "tool_execution_end":
      const pendingToolCalls = new Set(this.mutableState.pendingToolCalls);
      pendingToolCalls.delete(event.toolCallId);
      this.mutableState.pendingToolCalls = pendingToolCalls;
      break;
    // ...
  }

  // 第二步：再广播给外部监听器
  for (const listener of this.listeners) {
    await listener(event, signal);
  }
}

const pendingToolCalls = new Set(this.mutableState.pendingToolCalls);
pendingToolCalls.add(event.toolCallId);
this.mutableState.pendingToolCalls = pendingToolCalls;

type ActiveRun = {
  promise: Promise<void>;
  resolve: () => void;
  abortController: AbortController;
};

waitForIdle(): Promise<void> {
  return this.activeRun?.promise ?? Promise.resolve();
}

// processEvents 中，agent_end 事件的处理
case "agent_end":
  this.mutableState.streamingMessage = undefined;
  break;

// ...然后广播给外部监听器...

// finishRun 在 runWithLifecycle 的 finally 块中调用
private finishRun(): void {
  this.mutableState.isStreaming = false;
  this.mutableState.streamingMessage = undefined;
  this.mutableState.pendingToolCalls = new Set<string>();
  this.activeRun?.resolve(); // 通知 waitForIdle() 的调用者
  this.activeRun = undefined;
}

async function streamAssistantResponse(
  context: AgentContext,
  config: AgentLoopConfig,
  signal: AbortSignal | undefined,
  emit: AgentEventSink,
  streamFn?: StreamFn,
  runtime?: AgentCoreStreamRuntimeDeps,
): Promise<AssistantMessage> {
  // 第1层：transformContext - 上下文管理
  let messages = context.messages;
  if (config.transformContext) {
    messages = await config.transformContext(messages, signal); // AgentMessage[] → AgentMessage[]
  }

  // 第2层：convertToLlm - 协议适配
  const llmMessages = await config.convertToLlm(messages); // AgentMessage[] → Message[]

  // 构建 LLM 请求
  const llmContext: Context = {
    systemPrompt: context.systemPrompt,
    messages: llmMessages,
    tools: context.tools,
  };
  // ...调用 LLM ...
}

// convertToLlm 默认不做任何特殊转换
this.convertToLlm = options.convertToLlm ?? defaultConvertToLlm;

// transformContext 默认不存在（undefined），即不进行上下文变换
this.transformContext = options.transformContext;

function defaultConvertToLlm(messages: AgentMessage[]): Message[] {
  return messages as Message[];
}

export interface ContextEngine {
  readonly info: ContextEngineInfo;

  // ★ 必需方法 ★
  ingest(params: { sessionId: string; message: AgentMessage; ... }): Promise<IngestResult>;
  assemble(params: { sessionId: string; messages: AgentMessage[]; tokenBudget?: number; ... }): Promise<AssembleResult>;

  // ☆ 可选方法 ☆
  bootstrap?(params: { ... }): Promise<BootstrapResult>;
  maintain?(params: { ... }): Promise<ContextEngineMaintenanceResult>;
  ingestBatch?(params: { ... }): Promise<IngestBatchResult>;
  afterTurn?(params: { ... }): Promise<void>;
  compact?(params: { ... }): Promise<CompactResult>;
  prepareSubagentSpawn?(params: { ... }): Promise<SubagentSpawnPreparation | undefined>;
  onSubagentEnded?(params: { ... }): Promise<void>;
  dispose?(): Promise<void>;
}

export class LegacyContextEngine implements ContextEngine {
  readonly info: ContextEngineInfo = {
    id: "legacy",
    name: "Legacy Context Engine",
    version: "1.0.0",
  };

  async ingest(_params: { ... }): Promise<IngestResult> {
    // No-op: SessionManager handles message persistence
    return { ingested: false };
  }

  async assemble(params: { ... }): Promise<AssembleResult> {
    // Pass-through: just return messages as-is
    return {
      messages: params.messages,
      estimatedTokens: 0, // Caller handles estimation
    };
  }

  async compact(params: { ... }): Promise<CompactResult> {
    return await delegateCompactionToRuntime(params); // 委托给运行时
  }

  async dispose(): Promise<void> {
    // Nothing to clean up
  }
}

export type ContextEngineInfo = {
  id: string;
  name: string;
  version: string;
  supportedOperations?: ContextEngineOperation[];
  hostCapabilities?: ContextEngineHostCapability[];
  hostRequirements?: ContextEngineHostRequirements[];
};

尝试创建配置的引擎 → 失败则隔离 → 降级到默认引擎 → 默认引擎不可用则抛异常

export type AssembleResult = {
  messages: AgentMessage[];
  estimatedTokens: number;
  promptAuthority?: "assembled" | "preassembly_may_overflow";
  systemPromptAddition?: string;
  contextProjection?: ContextEngineProjection;
};

export type SubagentSpawnPreparation = {
  rollback?: () => Promise<void>;
};

async function prepareContextEngineSubagentSpawn(params: { ... }): Promise<...> {
  const rollbacks: Array<() => Promise<void>> = [];

  // 步骤1：准备 ContextEngine
  const enginePrep = await contextEngine.prepareSubagentSpawn?.({
    parentSessionKey,
    childSessionKey,
    contextMode,
    // ...
  });
  if (enginePrep?.rollback) {
    rollbacks.push(enginePrep.rollback); // 注册补偿操作
  }

  // 如果后续步骤失败，执行所有已注册的 rollback
  // ...
}

export async function summarizeInStages(params: { ... }): Promise<string> {
  const { messages } = params;
  if (messages.length === 0) {
    return params.previousSummary ?? DEFAULT_SUMMARY_FALLBACK;
  }

  // 第一步：规划分块策略
  const plan = await buildStageSplitPlanWithWorker({
    messages,
    maxChunkTokens: params.maxChunkTokens,
    parts: params.parts,
    minMessagesForSplit: params.minMessagesForSplit,
    signal: params.signal,
  });

  // 单块模式：直接走单次摘要
  if (plan.mode === "single") {
    return summarizeWithFallback(params);
  }

  // 多块模式：Map → Reduce
  const partialSummaries: string[] = [];
  for (const chunk of plan.chunks) {
    // === Map 阶段 ===
    partialSummaries.push(
      await summarizeWithFallback({ ...params, messages: chunk, previousSummary: undefined }),
    );
  }

  // === Reduce 阶段 ===
  const summaryMessages: AgentMessage[] = partialSummaries.map((summary) => ({
    role: "user",
    content: summary,
    timestamp: Date.now(),
  }));

  return summarizeWithFallback({ ...params, messages: summaryMessages, customInstructions: mergeInstructions });
}

export async function buildStageSplitPlanWithWorker(params: { ... }): Promise<StageSplitPlan> {
  const messages = sanitizeCompactionMessages(params.messages);

  // 消息太少时，直接在主线程计算（避免启动 Worker 的开销）
  if (!shouldUsePlanningWorker(messages.length)) {
    return buildStageSplitPlan(params);
  }

  // 消息太多时，交给 Worker 线程计算（不阻塞主线程）
  const value = await runWithUnavailableFallback({
    input: { kind: "stageSplit", messages, maxChunkTokens: params.maxChunkTokens, ... },
    signal: params.signal,
    fallback: () => ({ kind: "stageSplit" as const, ...buildStageSplitPlan(params) }),
    isExpected: (valueResult): valueResult is ... => valueResult.kind === "stageSplit",
  });
  return value.mode === "split" ? { mode: "split", chunks: value.chunks } : { mode: "single" };
}

// 调用方传入 reserveTokens
const summary = await summarizeInStages({
  messages,
  model: params.model,
  reserveTokens: SYSTEM_PROMPT_TOKENS + TOOL_DEFINITION_TOKENS + OUTPUT_BUFFER_TOKENS,
  maxChunkTokens: params.maxChunkTokens,
  // ...
});

function resolveSummaryReserveTokens(
  requestedReserveTokens: number,
  model: NonNullable<Parameters<typeof summarizeInStages>[0]["model"]>,
): number {
  const requested = Math.max(1, Math.floor(requestedReserveTokens));
  const modelMaxTokens = model.maxTokens;
  // 如果模型有 maxTokens 限制，预留空间不能超过模型能力
  // ...
}

export async function summarizeInStages(params: {
  // ...
  previousSummary?: string; // 前一次的摘要
}): Promise<string>

function buildPreviousSummaryMessage(previousSummary: string): AgentMessage {
  return {
    role: "user" as const,
    content: [
      {
        type: "text" as const,
        text: `Previous compaction summary to re-distill with the current conversation. ` +
              `Prune stale, duplicate, or superseded details instead of preserving it verbatim.\n\n` +
              previousSummary,
      },
    ],
    timestamp: Date.now(),
  };
}

export function hashToolCall(toolName: string, params: unknown): string {
  return `${toolName}:${digestStable(params)}`;
}

function digestStable(value: unknown): string {
  const serialized = stableStringify(value);   // 确定性序列化
  return createHash("sha256").update(serialized).digest("hex");  // SHA-256 哈希
}

function hashToolOutcome(
  toolName: string,
  params: unknown,
  result: ToolResult,
): string {
  // 对易变字段做特殊处理：去掉时间戳、随机ID等
  return createHash("sha256")
    .update(toolName)
    .update(digestStable(stripVolatileSendIds(params)))
    .update(digestStable(stripVolatileTimestamps(result)))
    .digest("hex");
}

type LoopDetectionResult =
  | { stuck: false }
  | {
      stuck: true;
      level: "warning" | "critical";
      detector: LoopDetectorKind;
      count: number;
      message: string;
      pairedToolName?: string;
      warningKey?: string;
    };

export const WARNING_THRESHOLD = 10;           // 10次 → warning
export const UNKNOWN_TOOL_THRESHOLD = 10;      // 10次未知工具 → critical
export const CRITICAL_THRESHOLD = 20;          // 20次 → critical
export const GLOBAL_CIRCUIT_BREAKER_THRESHOLD = 30; // 30次 → 全局断路器

type LoopDetectorKind =
  | "generic_repeat"
  | "unknown_tool_repeat"
  | "known_poll_no_progress"
  | "global_circuit_breaker"
  | "ping_pong";

const callerDepth = getSubagentDepthFromSessionStore(requesterInternalKey, { cfg });
const maxSpawnDepth =
  cfg.agents?.defaults?.subagents?.maxSpawnDepth ?? DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH;

// 关键：深度限制检查
if (callerDepth >= maxSpawnDepth) {
  return {
    status: "forbidden",
    error: `sessions_spawn is not allowed at this depth (current depth: ${callerDepth}, max: ${maxSpawnDepth})`,
  };
}

const maxChildren =
  cfg.agents?.defaults?.subagents?.maxChildrenPerAgent ?? DEFAULT_SUBAGENT_MAX_CHILDREN_PER_AGENT;
const activeChildren = countActiveRunsForSession(requesterInternalKey);
if (activeChildren >= maxChildren) {
  return {
    status: "forbidden",
    error: `sessions_spawn has reached max active children for this session (${activeChildren}/${maxChildren})`,
  };
}

function resolveSubagentRoleForDepth(params: {
  depth: number;
  maxSpawnDepth?: number;
}): SubagentSessionRole {
  const depth = resolveNonNegativeIntegerOption(params.depth, 0);
  const maxSpawnDepth = resolveIntegerOption(params.maxSpawnDepth, DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH, { min: 1 });

  if (depth <= 0) {
    return "main";       // 根 Agent：完整权限
  }
  return depth < maxSpawnDepth ? "orchestrator" : "leaf";  // 中间层 / 叶子节点
}

export function resolveSubagentCapabilities(params: { depth: number; maxSpawnDepth?: number }) {
  const role = resolveSubagentRoleForDepth(params);
  const controlScope = resolveSubagentControlScopeForRole(role);
  return {
    depth,
    role,
    controlScope,
    canSpawn: role === "main" || role === "orchestrator",
    // ...
  };
}

prepareSubagentSpawn?(params: {
  parentSessionKey: string;
  childSessionKey: string;
  contextMode?: "isolated" | "fork";  // 关键参数
  // ...
}): Promise<SubagentSpawnPreparation | undefined>;

private createContextSnapshot(): AgentContext {
  return {
    systemPrompt: this.mutableState.systemPrompt,
    messages: this.mutableState.messages.slice(),  // 数组拷贝
    tools: this.mutableState.tools.slice(),         // 数组拷贝
  };
}

agentLoop(prompts, context, config, signal, streamFn, runtime)
//                              ↑ 关键参数

// Agent 类中
private async runWithLifecycle(executor: (signal: AbortSignal) => Promise<void>): Promise<void> {
  const abortController = new AbortController();
  // ...
  this.activeRun = { promise, resolve: resolvePromise, abortController };

  try {
    await executor(abortController.signal);  // 把 signal 传递给整个执行链
  } catch (error) {
    await this.handleRunFailure(error, abortController.signal.aborted);
  } finally {
    this.finishRun();
  }
}

private async handleRunFailure(error: unknown, aborted: boolean): Promise<void> {
  const failureMessage = {
    role: "assistant",
    content: [{ type: "text", text: "" }],
    stopReason: aborted ? "aborted" : "error",  // 区分中断和错误
    errorMessage: error instanceof Error ? error.message : String(error),
    timestamp: Date.now(),
  } satisfies AgentMessage;
  // 仍然通过正常事件流发布
  await this.processEvents({ type: "message_start", message: failureMessage });
  await this.processEvents({ type: "message_end", message: failureMessage });
  await this.processEvents({ type: "turn_end", message: failureMessage, toolResults: [] });
  await this.processEvents({ type: "agent_end", messages: [failureMessage] });
}

// agent-loop.ts 第 610 行
if (signal?.aborted) {
  break;  // 工具执行中检测到中断，立即停止
}