pi-agent 源码解析

graph LR
  TUI["pi-tui<br/>终端差分渲染"] --> CA
  CA["pi-coding-agent<br/>产品层：AgentSession / 扩展 / 会话 / 压缩 / 重试"] --> AG
  AG["pi-agent-core<br/>机制层：Agent / agent-loop / harness"] --> AI
  AI["pi-ai<br/>协议层：Models / Provider / 各家 API"]
  CHORD["chord<br/>应用组装运行时（独立）"] -.-> CA
  CHORD -.-> AG

classDiagram
  class UserMessage {
    role: user
    content: text 或 image 列表
    timestamp: number
  }
  class AssistantMessage {
    role: assistant
    content: text / thinking / toolCall 列表
    api / provider / model
    usage: Usage
    stopReason: StopReason
    errorMessage?: string
    timestamp: number
  }
  class ToolResultMessage {
    role: toolResult
    toolCallId: string
    toolName: string
    content: text 或 image 列表
    details?: any
    isError: boolean
    timestamp: number
  }
  class BashExecutionMessage {
    role: bashExecution
    command / output / exitCode
    excludeFromContext?: boolean
  }
  class CustomMessage {
    role: custom
    customType: string
    content
    display: boolean
    details?
  }
  class CompactionSummaryMessage {
    role: compactionSummary
    summary: string
    tokensBefore: number
  }
  class BranchSummaryMessage {
    role: branchSummary
    summary: string
    fromId: string
  }
  Message <|-- UserMessage
  Message <|-- AssistantMessage
  Message <|-- ToolResultMessage
  AgentMessage <|-- Message
  AgentMessage <|-- BashExecutionMessage
  AgentMessage <|-- CustomMessage
  AgentMessage <|-- CompactionSummaryMessage
  AgentMessage <|-- BranchSummaryMessage

classDiagram
  class Model {
    id: string
    provider: string
    api: string
    baseUrl: string
    reasoning: boolean
    contextWindow: number
    maxTokens: number
    cost: ModelCost
    compat?: 各家兼容开关
  }
  class Tool {
    name: string
    description: string
    parameters: TSchema
  }
  class AgentTool {
    label: string
    prepareArguments?(args)
    execute(toolCallId, params, signal, onUpdate)
    executionMode?: sequential 或 parallel
  }
  class AgentToolResult {
    content: text 或 image 列表
    details: T
    usage?: Usage
    addedToolNames?: string[]
    terminate?: boolean
  }
  class Context {
    systemPrompt?: string
    messages: Message[]
    tools?: Tool[]
  }
  class AgentContext {
    systemPrompt: string
    messages: AgentMessage[]
    tools?: AgentTool[]
  }
  Tool <|-- AgentTool
  AgentTool ..> AgentToolResult : execute 返回

classDiagram
  class SessionEntryBase {
    type: string
    id: string
    parentId: string | null
    timestamp: string
  }
  class SessionMessageEntry {
    type: message
    message: AgentMessage
  }
  class CompactionEntry {
    type: compaction
    summary
    firstKeptEntryId
    tokensBefore
  }
  class BranchSummaryEntry {
    type: branch_summary
    fromId
    summary
  }
  class ModelChangeEntry {
    type: model_change
    provider
    modelId
  }
  class ThinkingLevelChangeEntry {
    type: thinking_level_change
    thinkingLevel
  }
  class CustomEntry {
    type: custom
    customType
    data
  }
  class CustomMessageEntry {
    type: custom_message
    customType
    content
    display
  }
  class LabelEntry {
    type: label
    targetId
    label
  }
  class SessionInfoEntry {
    type: session_info
    name
  }
  SessionEntryBase <|-- SessionMessageEntry
  SessionEntryBase <|-- CompactionEntry
  SessionEntryBase <|-- BranchSummaryEntry
  SessionEntryBase <|-- ModelChangeEntry
  SessionEntryBase <|-- ThinkingLevelChangeEntry
  SessionEntryBase <|-- CustomEntry
  SessionEntryBase <|-- CustomMessageEntry
  SessionEntryBase <|-- LabelEntry
  SessionEntryBase <|-- SessionInfoEntry

classDiagram
  class Agent {
    -_state: MutableAgentState
    -listeners: Set~listener~
    -steeringQueue: PendingMessageQueue
    -followUpQueue: PendingMessageQueue
    -activeRun?: ActiveRun
    +convertToLlm
    +transformContext?
    +streamFunction: StreamFn
    +getApiKey?
    +beforeToolCall? / afterToolCall?
    +shouldStopAfterTurn?
    +prepareNextTurn? / prepareNextTurnWithContext?
    +toolExecution: sequential 或 parallel
    +subscribe(listener) unsubscribe
    +prompt(input)
    +continue()
    +steer(msg) / followUp(msg)
    +abort() / waitForIdle() / reset()
    +hasQueuedMessages()
    -runPromptMessages(messages)
    -runContinuation()
    -createContextSnapshot() AgentContext
    -createLoopConfig() AgentLoopConfig
    -runWithLifecycle(executor)
    -processEvents(event)
  }
  class MutableAgentState {
    systemPrompt: string
    model: Model
    thinkingLevel: ThinkingLevel
    tools: AgentTool[]
    messages: AgentMessage[]
    isStreaming: boolean
    streamingMessage?: AgentMessage
    pendingToolCalls: Set~string~
    errorMessage?: string
  }
  class PendingMessageQueue {
    -messages: AgentMessage[]
    +mode: all 或 one-at-a-time
    +enqueue(msg)
    +drain() AgentMessage[]
    +hasItems()
    +clear()
  }
  class ActiveRun {
    promise: Promise
    resolve()
    abortController: AbortController
  }
  class AgentLoopConfig {
    model: Model
    reasoning?: ThinkingLevel
    convertToLlm(messages)
    transformContext?(messages)
    getApiKey?(provider)
    shouldStopAfterTurn?(ctx)
    prepareNextTurn?(ctx)
    getSteeringMessages?()
    getFollowUpMessages?()
    beforeToolCall?(ctx)
    afterToolCall?(ctx)
    toolExecution?
  }
  class agent_loop_ts {
    <<module>>
    runAgentLoop(prompts, context, config, emit, signal, streamFn)
    runAgentLoopContinue(context, config, emit, signal, streamFn)
    runLoop(...)
    streamAssistantResponse(...)
    executeToolCalls(...)
    executeToolCallsSequential / Parallel
    prepareToolCall / executePreparedToolCall / finalizeExecutedToolCall
    failToolCallsFromTruncatedMessage
    createToolResultMessage
  }
  Agent *-- MutableAgentState
  Agent *-- PendingMessageQueue : 两个
  Agent o-- ActiveRun
  Agent ..> AgentLoopConfig : createLoopConfig 生成
  Agent ..> agent_loop_ts : runAgentLoop 调用
  agent_loop_ts ..> AgentLoopConfig : 只通过它做决策

classDiagram
  class AgentSession {
    +agent: Agent
    +sessionManager: SessionManager
    +settingsManager: SettingsManager
    -_modelRuntime: ModelRuntime
    -_resourceLoader: ResourceLoader
    -_extensionRunner: ExtensionRunner
    -_extensionRunnerRef
    -_toolRegistry: Map~name,AgentTool~
    -_toolDefinitions: Map~name,ToolDefinitionEntry~
    -_baseToolDefinitions: Map
    -_toolPromptSnippets / _toolPromptGuidelines
    -_baseSystemPrompt: string
    -_systemPromptOverride?: string
    -_steeringMessages: string[]
    -_followUpMessages: string[]
    -_pendingNextTurnMessages: CustomMessage[]
    -_pendingCustomMessages: CustomMessage[]
    -_pendingBashMessages: BashExecutionMessage[]
    -_isAgentRunActive: boolean
    -_idleWaitPromise / _resolveIdleWait
    -_lastAssistantMessage?: AssistantMessage
    -_retryAttempt: number
    -_retryAbortController?
    -_compactionAbortController?
    -_autoCompactionAbortController?
    -_overflowRecoveryAttempted: boolean
    -_turnIndex: number
    -_eventListeners
    +prompt(text, options)
    +steer(text) / followUp(text)
    +sendCustomMessage(msg, options)
    +sendUserMessage(content, options)
    +abort() / waitForIdle()
    +compact(instructions?)
    +navigateTree(targetId, options)
    +setModel / setThinkingLevel / cycleModel
    +setActiveToolsByName(names)
    +executeBash(cmd) / recordBashResult
    +bindExtensions(bindings) / reload()
    +subscribe(listener) / dispose()
    +getContextUsage() / getSessionStats()
    -_runAgentPrompt(messages)
    -_handlePostAgentRun() boolean
    -_handleAgentEvent(event)
    -_emitExtensionEvent(event)
    -_checkCompaction(msg) boolean
    -_runAutoCompaction(reason, willRetry) boolean
    -_isRetryableError(msg) / _prepareRetry(msg)
    -_installAgentToolHooks()
    -_installAgentNextTurnRefresh()
    -_buildRuntime(options)
    -_refreshToolRegistry(options)
    -_rebuildSystemPrompt(toolNames)
  }
  class SessionManager {
    -sessionId / sessionFile / sessionDir / cwd
    -persist: boolean
    -flushed: boolean
    -fileEntries: FileEntry[]
    -byId: Map~id,SessionEntry~
    -leafId: string | null
    -labelsById: Map
    +appendMessage(msg) id
    +appendCompaction(...) id
    +appendBranchSummary / branchWithSummary
    +appendModelChange / appendThinkingLevelChange
    +appendCustomEntry / appendCustomMessageEntry
    +getBranch(fromId?) SessionEntry[]
    +buildSessionContext() SessionContext
    +getEntries() / getTree() / getEntry(id)
    +getLeafId() / branch(id) / resetLeaf()
    +create() / open() / continueRecent() / inMemory() / forkFrom()
    -_appendEntry(entry)
    -_persist(entry)
  }
  class ExtensionRunner {
    -extensions: Extension[]
    -runtime: ExtensionRuntime
    -sessionManager / modelRegistry / cwd
    -uiContext / mode
    -getModel 等十几个函数字段，bindCore 注入
    +bindCore(actions, state, providers)
    +hasHandlers(type)
    +emit(event)
    +emitToolCall(event) / emitToolResult(event)
    +emitContext(messages)
    +emitMessageEnd(event)
    +emitInput(text, images, source)
    +emitBeforeAgentStart(...)
    +emitBeforeProviderRequest(payload)
    +getAllRegisteredTools()
    +getCommand(name) / getRegisteredCommands()
    +createContext() ExtensionContext
  }
  class Extension {
    path: string
    handlers: Map~eventType, HandlerFn[]~
    tools: Map~name, RegisteredTool~
    commands: Map~name, RegisteredCommand~
    flags / shortcuts / messageRenderers
  }
  class ResourceLoader {
    <<interface>>
    getExtensions() LoadExtensionsResult
    getSkills() / getPrompts() / getThemes()
    getAgentsFiles()
    getSystemPrompt() / getAppendSystemPrompt()
    reload()
  }
  class SettingsManager {
    getRetrySettings()
    getCompactionSettings(model)
    getSteeringMode() / getFollowUpMode()
    getDefaultTools() / getBlockImages()
    getProviderRetrySettings()
  }
  class ModelRuntime {
    -models: MutableModels
    -credentials
    +getModel(provider, id)
    +hasConfiguredAuth(provider)
    +getAuth(model)
    +streamSimple(model, context, options)
    +registerProvider / refresh
  }
  class ToolDefinition {
    name / label / description
    parameters: TSchema
    promptSnippet? / promptGuidelines?
    prepareArguments?
    executionMode?
    execute(toolCallId, params, signal, onUpdate, ctx)
    renderCall? / renderResult?
  }
  AgentSession *-- Agent
  AgentSession *-- SessionManager
  AgentSession *-- SettingsManager
  AgentSession *-- ModelRuntime
  AgentSession *-- ResourceLoader
  AgentSession *-- ExtensionRunner : _buildRuntime 里 new
  ExtensionRunner o-- Extension : 多个
  Extension o-- ToolDefinition : tools
  AgentSession ..> ToolDefinition : 包装成 AgentTool 放进 agent.state.tools

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && String(event.input.command).includes("rm -rf")) {
      return { block: true, reason: "危险命令" };        // 返回格式由事件决定，见上表
    }
  });

  pi.on("session_before_switch", async (event, ctx) => {
    if (ctx.hasUI && !(await ctx.ui.confirm("切换会话？", "当前会话有未保存的内容"))) {
      return { cancel: true };
    }
  });
}

on(event: string, handler: HandlerFn): void {
  assertActive();
  const list = extension.handlers.get(event) ?? [];
  list.push(handler);
  extension.handlers.set(event, list);
}

on(event: "tool_call",      handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
on(event: "tool_result",    handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
on(event: "context",        handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
on(event: "message_update", handler: ExtensionHandler<MessageUpdateEvent>): void;   // 没有返回值

sequenceDiagram
  autonumber
  participant RL as ResourceLoader
  participant PM as PackageManager
  participant LD as loader.ts
  participant JT as jiti
  participant Ext as 扩展文件
  participant AS as AgentSession
  participant RN as ExtensionRunner
  RL->>PM: resolve 收集扩展路径
  PM-->>RL: 项目 .pi/extensions 仅受信任时 用户 ~/.pi/agent/extensions settings 里的包
  RL->>LD: loadExtensionsCached paths
  LD->>LD: createExtensionRuntime 动作方法都是抛错桩
  LD->>JT: createJiti 配 virtualModules 或 alias
  JT->>Ext: 现场转译 TypeScript 并 import
  Ext-->>LD: 默认导出的工厂函数
  LD->>LD: createExtension 空的 handlers tools commands 等表
  LD->>LD: createExtensionAPI 生成 pi
  LD->>Ext: await factory pi
  Ext->>LD: pi.on 写进 handlers
  Ext->>LD: pi.registerTool 写进 tools
  LD->>LD: 成功 commit 失败 discard
  LD-->>RL: extensions errors runtime
  AS->>RN: new ExtensionRunner extensions runtime
  AS->>RN: bindCore 注入真实的动作实现
  Note over AS,RN: 之后 AgentSession 在固定时机调 emit 系列

export function openrouterProvider(): Provider<"anthropic-messages" | "openai-completions"> {
  return createProvider({
    id: "openrouter",
    baseUrl: "https://openrouter.ai/api/v1",
    auth: { apiKey: envApiKeyAuth("OpenRouter API key", ["OPENROUTER_API_KEY"]), oauth: … },
    models: Object.values(OPENROUTER_MODELS),
    api: {
      "anthropic-messages": anthropicMessagesApi(),
      "openai-completions": openAICompletionsApi(),
    },
  });
}

classDiagram
  class Model {
    id string
    provider ProviderId
    api Api
    baseUrl string
    reasoning boolean
    contextWindow number
    maxTokens number
    cost ModelCost
    compat 随 api 变化的开关表
  }
  class Models {
    <<interface>>
    getProviders() Provider[]
    getProvider(id) Provider
    getModel(provider, id) Model
    getAvailable(provider) Model[]
    stream(model, context, options) AssistantMessageEventStream
    streamSimple(model, context, options) AssistantMessageEventStream
  }
  class ModelsImpl {
    -providers Map~string,Provider~
    -credentials
    +setProvider(provider)
    +deleteProvider(id)
    -requireProvider(model) Provider
    -applyAuth(model, options)
  }
  class Provider {
    <<interface>>
    id string
    name string
    baseUrl string
    auth ProviderAuth
    getModels() Model[]
    refreshModels(ctx)
    stream(model, context, options) AssistantMessageEventStream
    streamSimple(model, context, options) AssistantMessageEventStream
  }
  class CreateProviderOptions {
    id string
    baseUrl string
    auth ProviderAuth
    models Model[]
    fetchModels(ctx)
    api ProviderStreams 或 按api名的映射
  }
  class ProviderStreams {
    <<interface>>
    stream(model, context, options) AssistantMessageEventStream
    streamSimple(model, context, options) AssistantMessageEventStream
  }
  class LazyApi {
    <<lazyApi 返回值>>
    load() import 协议模块
  }
  class ApiModule {
    <<api 目录下的协议模块>>
    stream StreamFunction
    streamSimple StreamFunction
  }
  class AssistantMessageEventStream {
    push(event)
    end(result)
    asyncIterator()
    result() Promise
  }
  Models <|.. ModelsImpl
  ModelsImpl o-- Provider : 以 provider id 为键
  CreateProviderOptions ..> Provider : createProvider 返回
  Provider ..> ProviderStreams : 闭包持有 按 model.api 挑选
  ProviderStreams <|.. LazyApi
  LazyApi ..> ApiModule : 首次调用时动态 import
  ProviderStreams <|.. ApiModule : 模块本身就满足接口
  Model ..> Provider : provider 字段选服务商
  Model ..> ProviderStreams : api 字段选协议
  ApiModule ..> AssistantMessageEventStream : 返回

sequenceDiagram
  autonumber
  participant Boot as builtinModels
  participant CP as createProvider
  participant MS as ModelsImpl
  participant PV as Provider 对象
  participant LA as lazyApi 包装
  participant Mod as openai-completions.ts
  participant Net as DeepSeek 服务端
  Boot->>CP: deepseekProvider 调 createProvider id deepseek api openAICompletionsApi
  CP-->>Boot: 返回 Provider 对象 协议代码尚未加载
  Boot->>MS: setProvider provider
  Note over Boot,MS: 其余 39 家同样注册 共用 10 份协议实现
  MS->>MS: streamSimple model provider deepseek api openai-completions
  MS->>MS: requireProvider 按 model.provider 取 Provider
  MS->>MS: applyAuth 解析凭证 合并 headers
  MS->>PV: streamSimple requestModel context options
  PV->>PV: dispatch apiFor 按 model.api 取实现
  PV->>LA: streamSimple
  LA->>LA: lazyStream 先返回空外层流
  LA->>Mod: 首次调用 动态 import 模块
  Mod->>Mod: getCompat model 探测 deepseek 再叠加 model.compat
  Mod->>Mod: 按开关构造请求体 thinking 字段 max_tokens reasoning_content
  Mod->>Net: POST baseUrl chat completions
  Net-->>Mod: SSE 分片
  Mod-->>LA: 内层流事件
  LA-->>MS: 转发到外层流

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false },
      "models": [{ "id": "gpt-oss:20b", "reasoning": true }]
    }
  }
}

sequenceDiagram
  participant M as main.ts
  participant SDK as sdk.ts<br/>createAgentSession
  participant MR as ModelRuntime
  participant SM as SessionManager
  participant AG as Agent
  participant AS as AgentSession
  participant RL as ResourceLoader
  participant ER as ExtensionRunner
  participant Mode as Interactive / RPC / Print

  M->>SDK: createAgentSession(options)
  SDK->>MR: ModelRuntime.create() 读 auth.json / models.json
  SDK->>SM: SessionManager.create / open / continueRecent
  SDK->>SDK: 决定 model 与 thinkingLevel（会话里存的 > 设置 > 首个可用）
  SDK->>AG: new Agent({ initialState, convertToLlm, streamFn, onPayload, onResponse, transformContext, steeringMode, followUpMode, ... })
  SDK->>AG: 有旧会话则 agent.state.messages = existingSession.messages
  SDK->>AS: new AgentSession({ agent, sessionManager, settingsManager, resourceLoader, modelRuntime, extensionRunnerRef, ... })
  AS->>AG: agent.subscribe(_handleAgentEvent)
  AS->>AG: agent.beforeToolCall = ... / agent.afterToolCall = ...
  AS->>AG: agent.prepareNextTurnWithContext = ...
  AS->>AS: _buildRuntime()
  AS->>RL: getExtensions()
  AS->>ER: new ExtensionRunner(extensions, runtime, cwd, sessionManager, modelRegistry)
  AS->>ER: bindCore(actions, state, providers)
  AS->>AS: _refreshToolRegistry() → setActiveToolsByName() → _rebuildSystemPrompt()
  AS->>AG: agent.state.tools = [...] / agent.state.systemPrompt = ...
  SDK-->>M: { session, extensionsResult }
  M->>Mode: runRpcMode(runtime) / new InteractiveMode(runtime).run() / runPrintMode(runtime)
  Mode->>AS: bindExtensions({ uiContext, mode, commandContextActions, ... })
  AS->>ER: emit(session_start)

sequenceDiagram
  participant UI as InteractiveMode
  participant AS as AgentSession
  participant ER as ExtensionRunner
  participant AG as Agent
  participant L as agent-loop.ts
  participant SF as streamFn → ModelRuntime → Provider → api
  participant SM as SessionManager

  UI->>AS: prompt(text)
  AS->>AS: 以 "/" 开头？_tryExecuteExtensionCommand → 命中就 return
  AS->>AS: 正在压缩？抛错
  AS->>ER: emitInput(text) → handled / transform / 原样
  AS->>AS: _expandSkillCommand + expandPromptTemplate
  AS->>AS: isStreaming？→ _queueSteer / _queueFollowUp → return
  AS->>AS: 校验模型与鉴权
  AS->>AS: _checkCompaction(上一条 assistant, false)
  AS->>AS: messages = [UserMessage, ...pendingNextTurnMessages]
  AS->>ER: emitBeforeAgentStart(...) → 追加 custom 消息 / 临时系统提示词
  AS->>AG: agent.state.systemPrompt = override ?? base
  AS->>AS: _runAgentPrompt(messages)
  AS->>AG: agent.prompt(messages)
  AG->>AG: runWithLifecycle：activeRun、isStreaming=true
  AG->>L: runAgentLoop(messages, createContextSnapshot(), createLoopConfig(), processEvents, signal, streamFunction)
  L-->>AG: emit(agent_start) / turn_start / message_start+end(每条 prompt)
  AG->>AS: _handleAgentEvent(每个事件)
  AS->>ER: _emitExtensionEvent
  AS->>UI: _emit（订阅者）
  AS->>SM: message_end 时 appendMessage
  loop runLoop 内层：每一轮
    L->>L: 第二轮起 config.prepareNextTurn(lastTurn) → 可能压缩、刷新提示词/工具/模型
    L->>L: 注入 pendingMessages（steer）
    L->>SF: streamAssistantResponse：transformContext → convertToLlm → getApiKey → streamFunction(model, llmContext, options)
    SF-->>L: AssistantMessageEvent 流：start / *_delta / done
    L-->>AG: emit(message_start / message_update... / message_end)
    L->>L: stopReason error/aborted？→ emit turn_end, agent_end, return
    L->>L: 有 toolCall？stopReason=="length" → 整批作废；否则 executeToolCalls（§8）
    L-->>AG: emit(turn_end)
    L->>L: config.shouldStopAfterTurn？→ agent_end, return
    L->>L: pendingMessages = config.getSteeringMessages()
  end
  L->>L: 内层退出：config.getFollowUpMessages() 非空 → 回内层；否则 emit(agent_end)
  AG->>AG: finishRun：isStreaming=false，通知等待方运行结束
  AG-->>AS: agent.prompt 返回
  AS->>AS: while (await _handlePostAgentRun()) agent.continue()  （§10）
  AS->>AS: finally：清 override、flush bash/custom 消息、_emitAgentSettled
  AS->>ER: emit(agent_settled)
  AS->>UI: _emit(agent_settled)

this._isAgentRunActive = true;
try {
  await this.agent.prompt(messages);
  while (await this._handlePostAgentRun()) {   // §10：重试 / 压缩 / 队列里还有东西
    await this.agent.continue();
  }
} finally {
  this._systemPromptOverride = undefined;      // 临时提示词只活一次运行
  this._flushPendingBashMessages();
  this._flushPendingCustomMessages();
  await this._emitAgentSettled();              // agent_settled 事件；在 waitForIdle 上等着的调用方此时返回
}

let currentContext = initialContext;            // 快照，循环内可以换（prepareNextTurn）
let config = initialConfig;                     // 同上，可以换模型/思考等级
let lastCompletedTurn;                          // 上一轮的结果，给 prepareNextTurn 用
let pendingMessages = await config.getSteeringMessages?.() || [];   // 开局先拉一次：用户可能在等待时已经打了字

while (true) {                                  // 外层：处理 followUp
  let hasMoreToolCalls = true;

  while (hasMoreToolCalls || pendingMessages.length > 0) {   // 内层：处理工具轮次和 steer
    if (lastCompletedTurn) {                    // 不是第一轮
      const next = await config.prepareNextTurn?.(lastCompletedTurn);
      if (next) { currentContext = next.context ?? currentContext; config = {...config, model, reasoning}; }
      if (pendingMessages.length === 0)         // 只有上一次没拉到才补拉
        pendingMessages = await config.getSteeringMessages?.() || [];
      await emit({ type: "turn_start" });
    }

    for (const m of pendingMessages) {          // 把 steer 注入上下文
      emit(message_start); emit(message_end); currentContext.messages.push(m); newMessages.push(m);
    }
    pendingMessages = [];

    const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFunction);
    newMessages.push(message);

    if (message.stopReason === "error" || message.stopReason === "aborted") {
      emit(turn_end); emit(agent_end); return;  // 循环不重试，交给产品层
    }

    const toolCalls = message.content.filter(c => c.type === "toolCall");
    hasMoreToolCalls = false;
    if (toolCalls.length > 0) {
      const batch = message.stopReason === "length"
        ? await failToolCallsFromTruncatedMessage(toolCalls, emit)           // 整批作废
        : await executeToolCalls(currentContext, message, config, signal, emit);
      toolResults.push(...batch.messages);
      hasMoreToolCalls = !batch.terminate;
      for (const r of toolResults) { currentContext.messages.push(r); newMessages.push(r); }
    }

    await emit({ type: "turn_end", message, toolResults });
    lastCompletedTurn = { message, toolResults, context: currentContext, newMessages };

    if (await config.shouldStopAfterTurn?.(lastCompletedTurn)) { emit(agent_end); return; }

    pendingMessages = await config.getSteeringMessages?.() || [];
  }

  const followUps = await config.getFollowUpMessages?.() || [];
  if (followUps.length > 0) { pendingMessages = followUps; continue; }       // 回内层
  break;
}
await emit({ type: "agent_end", messages: newMessages });

sequenceDiagram
  participant L as runLoop
  participant X as executeToolCalls
  participant P as prepareToolCall
  participant AS as AgentSession.beforeToolCall
  participant ER as ExtensionRunner
  participant T as AgentTool.execute
  participant F as finalizeExecutedToolCall
  participant AS2 as AgentSession.afterToolCall

  L->>X: executeToolCalls(context, assistantMessage, config, signal, emit)
  X->>X: config.toolExecution=="sequential" 或任一工具 executionMode=="sequential" → 串行；否则并行
  loop 每个 toolCall（准备阶段永远串行）
    X-->>L: emit(tool_execution_start)
    X->>P: prepareToolCall
    P->>P: 按名字在 context.tools 找工具；找不到 → immediate 错误结果
    P->>P: tool.prepareArguments?(args) → validateToolArguments(tool, call)
    P->>AS: config.beforeToolCall({ assistantMessage, toolCall, args, context })
    AS->>ER: hasHandlers("tool_call")? emitToolCall(...)
    ER-->>AS: { block, reason, terminate }? 或 undefined
    AS-->>P: 同上
    P-->>X: block → immediate 错误结果（可带 terminate）；否则 prepared
  end
  par 并行模式下每个 prepared 同时执行
    X->>T: execute(toolCallId, args, signal, onUpdate)
    T-->>X: onUpdate(partial) → emit(tool_execution_update)
    T-->>X: AgentToolResult 或 throw
    X->>F: finalizeExecutedToolCall
    F->>AS2: config.afterToolCall({ ..., result, isError })
    AS2->>ER: emitToolResult → 可覆盖 content/details/isError
    AS2->>AS2: normalizeToolResultImages
    F-->>X: 合并后的结果
    X-->>L: emit(tool_execution_end)  （完成顺序）
  end
  X->>X: 按 assistant 消息里的原始顺序 createToolResultMessage
  X-->>L: emit(message_start/message_end) 每条 toolResult（原始顺序）
  X-->>L: { messages, terminate: 全部结果都 terminate 才为 true }

execute(toolCallId, { path, edits }, signal, onUpdate, ctx)
  absolutePath = resolveToCwd(path, ctx.cwd || cwd)
  withFileMutationQueue(absolutePath, async () => {     // 同一文件的写串行化
    access → readFile → 去 BOM → 统一成 LF
    applyEditsToNormalizedContent(content, edits)      // 每个 oldText 必须唯一匹配
    还原换行 + BOM → writeFile
    return { content: [text "Successfully replaced N block(s)"], details: { diff, patch, firstChangedLine } }
  })

sequenceDiagram
  participant UI as InteractiveMode
  participant AS as AgentSession
  participant AG as Agent
  participant Q as PendingMessageQueue
  participant L as runLoop

  UI->>AS: prompt(text, { streamingBehavior: "steer" })
  AS->>AS: isStreaming 为真 → _queueSteer(text)
  AS->>AS: _steeringMessages.push(text)（给 UI 显示）
  AS->>UI: _emit(queue_update)
  AS->>AG: agent.steer({ role: "user", content, timestamp })
  AG->>Q: steeringQueue.enqueue(msg)
  Note over L: 当前轮工具执行完
  L->>AG: config.getSteeringMessages()
  AG->>Q: steeringQueue.drain()（one-at-a-time：只给一条）
  Q-->>L: [msg]
  L->>L: 下一轮开头注入 context.messages
  L-->>AG: emit(message_start, msg)
  AG->>AS: _handleAgentEvent(message_start, role=user)
  AS->>AS: 在 _steeringMessages 里找到同文本 → 删除 → _emit(queue_update)

sequenceDiagram
  participant AS as AgentSession
  participant AG as Agent
  participant SM as SessionManager
  participant C as compaction.ts

  AS->>AS: msg = _lastAssistantMessage（用完清空）
  alt msg 是可重试错误且重试预算没用完
    AS->>AS: _prepareRetry：_retryAttempt++，emit(auto_retry_start)
    AS->>AG: agent.state.messages = 去掉末尾那条 error 消息
    AS->>AS: sleep(baseDelayMs * 2^(attempt-1))，可被 abortRetry 打断
    AS-->>AS: return true → agent.continue()
  else 需要压缩
    AS->>AS: _checkCompaction(msg)
    AS->>SM: getBranch() 拿当前路径条目
    AS->>C: prepareCompaction(entries, settings) → { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, fileOps, ... }
    AS->>AS: emit(compaction_start)；session_before_compact 让扩展接管或取消
    AS->>C: compact(preparation, model, apiKey, ...) → 调模型生成摘要，附文件操作清单
    AS->>SM: appendCompaction(summary, firstKeptEntryId, tokensBefore, ...)
    AS->>SM: buildSessionContext() → 新的 messages
    AS->>AG: agent.state.messages = 新 messages
    AS->>AS: emit(compaction_end)
    AS-->>AS: return willRetry 或 agent.hasQueuedMessages()
  else 队列里还有扩展在 agent_end 里塞的消息
    AS-->>AS: return agent.hasQueuedMessages()
  end

flowchart TD
  A["buildSessionPath(entries, leafId, byId)<br/>从叶子沿 parentId 走到根，反转"] --> B["buildContextEntries<br/>找路径上最后一个 compaction 条目 C"]
  B -->|没有 C| D["返回整条路径"]
  B -->|有 C| E["[C] + 从 C.firstKeptEntryId 到 C 之前的条目 + C 之后的全部条目"]
  D --> F["sessionEntryToContextMessages<br/>message → 原消息；compaction → CompactionSummaryMessage；branch_summary → BranchSummaryMessage；custom_message → CustomMessage；其他 → 空"]
  E --> F
  F --> G["buildSessionContext<br/>{ messages, thinkingLevel, model }"]

classDiagram
  class AgentHarness {
    <<interface>>
    lane(name, context) AgentLane
    lanes() / getTools / setTools
    getStreamOptions / setStreamOptions
    getRetryPolicy / getCompactionSettings
    getSteeringMode / getFollowUpMode
    close()
  }
  class AgentLane {
    <<interface>>
    prompt(text|messages, context) RunResult
    skill(name) / promptFromTemplate(name)
    accept(request) OperationAdmissionResult
    drive(options) DriveResult
    requestAbort(operationId)
    steer / followUp / nextRun (message) QueueResult
    cancelQueued(entryId)
    compact() / navigateTree(targetId) / resume() / abort()
    getTipId() / findEntries() / appendMessage()
    getModel / setModel / getThinkingLevel / setActiveTools
    watch() WatchHandle~LaneSnapshot~
  }
  class Harness {
    session: Session
    models: Models
    hooks: HookRegistry
    events: HarnessEventBus
    -configStore
    -buildLane(name, state) Lane
  }
  class Lane {
    name: string
    session / models / hooks
    state: LaneState
    activeDrive?: Drive
    +command(fn) 串行化状态变更
    +drive(options)
    -acceptRun / acceptCompaction / acceptNavigation
    -enqueue(kind, input)
  }
  class LaneState {
    tipId: string | null
    configuration: LaneConfiguration
    inbox: InboxItem[]
    lastOperationId
    operation: Operation | null
  }
  class Drive {
    operationId
    completion: Promise~DriveOutcome~
    gate: Gate
    context: Context
    settle() / fail() / beginAbort() / closeGate()
  }
  class Operation {
    meta: OperationMeta
    state: OperationState，at 是状态名
  }
  class HookRegistry {
    on(name, handler)
    has(name)
    runWithGate / runToolWithGate
    -invokeAllFailClosed / invokeAll / firstStructural
  }
  AgentHarness <|.. Harness
  AgentLane <|.. Lane
  Harness o-- Lane : 多条泳道
  Harness *-- HookRegistry
  Lane *-- LaneState
  Lane o-- Drive
  LaneState o-- Operation