pi-agent 源码解析

graph LR
  TUI["pi-tui<br/>终端差分渲染"] --> CA
  CA["pi-coding-agent<br/>产品层：AgentSession / 扩展 / 会话 / 压缩 / 重试"] --> AG
  CA --> CM["pi-codemode<br/>脚本解释器"]
  CA --> MCP["pi-mcp<br/>MCP 客户端"]
  AG["pi-agent-core<br/>机制层：Agent / agent-loop"] --> AI
  AI["pi-ai<br/>协议层：Models / Provider / 各家 API"]
  DU["pi-durable<br/>持久化 harness（实验）"] --> AI
  DU --> CHORD["chord<br/>对象运行时 + 可复制状态"]
  ENV["pi-env<br/>远程执行环境"] --> DU

classDiagram
  class SystemMessage {
    role: system
    content: string 或 text 列表
    sections?: 名字 → 文本或 null
    toolsAdded?: Tool[]
    toolsRemoved?: 工具名列表
    timestamp: number
  }
  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 <|-- SystemMessage
  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
    structuredContent?: JSON
    isError?: boolean
    usage?: Usage
    terminate?: boolean
  }
  class Context {
    systemPrompt?: string
    messages: Message[]
    tools?: Tool[]
  }
  class TranscriptContext {
    messages: Message[]
    只能由 normalizeContext 生成
  }
  class AgentContext {
    messages: AgentMessage[]
    tools?: AgentTool[]
  }
  Tool <|-- AgentTool
  AgentTool ..> AgentToolResult : execute 返回
  Context ..> TranscriptContext : normalizeContext

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
    systemMessage?: 压缩时刻完整的提示词和工具
  }
  class ContextEditEntry {
    type: context_edit
    targetId
    replacement: 新 content 或 null
  }
  class UsageEntry {
    type: usage
    kind / provider / model
    usage
  }
  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
  SessionEntryBase <|-- ContextEditEntry
  SessionEntryBase <|-- UsageEntry

sequenceDiagram
  participant AS as AgentSession
  participant AG as Agent
  participant L as agent-loop.ts
  participant P as 协议模块

  Note over AG: 新会话：initialState 的 systemPrompt 和 tools<br/>变成开头那条 system 消息
  AS->>AS: prompt()：_preparePromptAndToolLoadout(options)
  AS->>AS: buildSystemPromptSections → 和当前回放结果逐段 diff
  AS->>AG: 有变化：在本次消息最前面放一条 {sections: 补丁}
  AG->>L: runAgentLoop(messages, context)
  L->>L: declareToolChanges：比较“记录里声明的工具”和 context.tools
  L->>L: 有差异：把 toolsAdded / toolsRemoved 填进那条 system 消息，<br/>没有就新插一条
  L->>P: normalizeContext({ messages })
  alt 模型支持对话中途的 system 消息
    P->>P: 原地保留，工具增加用原生的 tool_addition 之类的块
  else 不支持
    P->>P: collapseSystemMessages：回放成一条放到最前面
  end

classDiagram
  class Agent {
    -_state: MutableAgentState
    -listeners: Set~listener~
    -steeringQueue: PendingMessageQueue
    -followUpQueue: PendingMessageQueue
    -activeRun?: ActiveRun
    +convertToLlm
    +transformContext?
    +streamFunction: StreamFn
    +getApiKey?
    +onPayload? / onResponse? / onProviderStreamEvent?
    +beforeToolCall? / afterToolCall?
    +finishTurn?
    +prepareRequest?
    +prepareNextTurn? / prepareNextTurnWithContext?
    +toolExecution: sequential 或 parallel
    +subscribe(listener) unsubscribe
    +prompt(input)
    +continue()
    +steer(msg) / followUp(msg)
    +abort() / waitForIdle() / reset()
    +hasQueuedMessages() / peekQueuedMessages()
    -runPromptMessages(messages)
    -runContinuation()
    -createContextSnapshot() AgentContext
    -createLoopConfig() AgentLoopConfig
    -runWithLifecycle(executor)
    -processEvents(event)
  }
  class MutableAgentState {
    systemPrompt: string（只读，从 messages 回放）
    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[]
    +peek() AgentMessage[]
    +hasItems()
    +clear()
  }
  class ActiveRun {
    promise: Promise
    resolve()
    abortController: AbortController
  }
  class AgentLoopConfig {
    model: Model
    reasoning?: ThinkingLevel
    convertToLlm(messages)
    transformContext?(messages)
    getApiKey?(provider)
    finishTurn?(turn) end 或 continue
    prepareRequest?(request)
    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(...)
    declareToolChanges(context, pending)
    streamAssistantResponse(...)
    executeToolCalls(...)
    executeToolCallsSequential / Parallel
    prepareToolCall / executePreparedToolCall / finalizeExecutedToolCall
    failToolCallsFromTruncatedMessage
    createToolResultMessage
    runToolCall(toolCall, options)
  }
  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
    -_hiddenDeclarations: Set
    -_baseSystemPromptOptions
    -_runSystemPromptOptions?
    -_cacheWarmer?: CacheWarmer
    -_steeringMessages: string[]
    -_followUpMessages: string[]
    -_pendingNextTurnMessages: CustomMessage[]
    -_pendingCustomMessages: CustomMessage[]
    -_pendingBashMessages: BashExecutionMessage[]
    -_isAgentRunActive: boolean
    -_idleWaitPromise / _resolveIdleWait
    -_lastAssistantMessage?: AssistantMessage
    -_retryAttempt: number
    -_retryAbortController?
    -_compactionAbortController?
    -_autoCompactionAbortController?
    -_overflowRecoveryAttempted: boolean
    -_failedResponse?: AssistantMessage
    -_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()
    -_startRun(trigger)
    -_prepareRun(trigger) messages
    -_handlePostAgentRun() boolean
    -_runBeforeSettleBoundary() boolean
    -_handleAgentEvent(event)
    -_emitExtensionEvent(event)
    -_checkCompaction(msg) boolean
    -_runAutoCompaction(reason, willRetry) boolean
    -_isRetryableError(msg) / _prepareRetry(msg)
    -_omitRecoveryAttempt(msg)
    -_installAgentToolHooks()
    -_installAgentNextTurnRefresh()
    -_installAgentRequestProjection()
    -_installAgentBoundaryHooks()
    -_buildRuntime(options)
    -_refreshToolRegistry(options)
    -_applyToolLoadout(names)
    -_rebuildSystemPrompt(toolNames)
    -_preparePromptAndToolLoadout(options) SystemMessage
  }
  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
    +appendContextEdit(targetId, replacement) id
    +appendUsage(...)
    +getBranch(fromId?) SessionEntry[]
    +buildSessionProjection() SessionProjection
    +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)
    +emitBoundary(event, preview)
    +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
    outputSchema?
    exposure?: direct / model-only / codemode / deferred / hidden
    defaultActive?
    prepareLoadout?(loadout)
    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 registeredHandler: HandlerFn = (...args) => handler(...args);   // 包一层，同一个函数注册两次也能分别取消
  const list = extension.handlers.get(event) ?? [];
  list.push(registeredHandler);
  extension.handlers.set(event, list);
  return () => { /* 从 handlers 表里删掉 registeredHandler */ };
}

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
    generateImages(model, context, options)
    classify(model, context, options)
  }
  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, TranscriptContext, options) AssistantMessageEventStream
    streamSimple(model, TranscriptContext, 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: 其余 41 家同样注册 聊天模型共用 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->>SDK: new CacheWarmer(...)
  SDK->>AG: new Agent({ initialState: { model, thinkingLevel, messages: 旧会话的 messages }, convertToLlm, streamFn, onPayload, onResponse, onProviderStreamEvent, transformContext, ... })
  SDK->>AS: new AgentSession({ agent, sessionManager, settingsManager, resourceLoader, modelRuntime, cacheWarmer, extensionRunnerRef, ... })
  AS->>AG: agent.subscribe(_handleAgentEvent)
  AS->>AG: agent.beforeToolCall / afterToolCall = ...
  AS->>AG: agent.prepareNextTurnWithContext = ...
  AS->>AG: agent.prepareRequest = ...（从会话投影上下文）
  AS->>AG: agent.finishTurn = ...（turn_end 边界）
  AS->>AG: agent.transformContext 外面再套两层（隐藏声明、强制提示词）
  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 = [...]；提示词只算出 _baseSystemPromptOptions，等第一次 prompt 时才写成 system 消息
  AS->>AS: 恢复的会话且用默认工具集：重放分支工具增删，合入后来注册的扩展工具，再应用 modifiers
  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: _startRun({ messageType: "user", prompt, images })
  AS->>AS: _prepareRun：_checkCompaction(上一条 assistant, false)
  AS->>ER: emitBeforeAgentStart(trigger, ...) → 改提示词参数 / 追加 custom 消息
  AS->>AS: messages = [UserMessage, ...pendingNextTurnMessages, ...custom]
  AS->>AS: _preparePromptAndToolLoadout：提示词有变化就在最前面加一条 system 消息
  AS->>SM: flush 准备期间攒下的 bash / custom 消息
  AS->>AG: agent.prompt(messages)
  AG->>AG: runWithLifecycle：activeRun、isStreaming=true
  AG->>L: runAgentLoop(messages, createContextSnapshot(), createLoopConfig(), processEvents, signal, streamFunction)
  L->>L: declareToolChanges(prompts)：工具有变化就补进 system 消息
  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: 注入 prepareNextTurn 给的消息和 pendingMessages（steer），先过 declareToolChanges
    L->>AS: config.prepareRequest → 用 SessionManager 投影替换上下文
    L->>SF: streamAssistantResponse：transformContext → convertToLlm → normalizeContext → 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？→ finishTurn（结果忽略）、emit turn_end, agent_end, return
    L->>L: 有 toolCall？stopReason=="length" → 整批作废；否则 executeToolCalls（§8）
    L->>AS: config.finishTurn(turn) → 扩展的 turn_end 边界
    L-->>AG: emit(turn_end)
    L->>L: 决定是 end？→ agent_end, return
    L->>L: pendingMessages = config.getSteeringMessages()
  end
  L->>L: 内层退出：config.getFollowUpMessages() 非空 → 回内层；finishTurn 要求过 continue → 再跑一轮；否则 emit(agent_end)
  AG->>AG: finishRun：isStreaming=false，通知等待方运行结束
  AG-->>AS: agent.prompt 返回
  AS->>AS: 循环：_handlePostAgentRun() 为真就 agent.continue()；为假再问 agent_before_settle 边界（§10）
  AS->>AS: finally：清 _runSystemPromptOptions、flush bash/custom 消息、_emitAgentSettled
  AS->>ER: emit(agent_settled)
  AS->>UI: _emit(agent_settled)

this._isAgentRunActive = true;
const messages = await this._prepareRun(trigger);   // 出错就复位状态、flush、抛出
this._flushPendingBashMessages();
this._flushPendingCustomMessages();
try {
  await this.agent.prompt(messages);
  while (!this._agentRunAbortRequested) {
    if (await this._handlePostAgentRun()) {        // §10：重试 / 压缩 / 队列里还有东西
      await this.agent.continue();
      continue;
    }
    if (!(await this._runBeforeSettleBoundary())) break;   // 扩展的 agent_before_settle 可以要求再跑
    await this.agent.continue();
  }
} finally {
  this._runSystemPromptOptions = undefined;        // 这次运行的提示词参数只活一次运行
  this._flushPendingBashMessages();
  this._flushPendingCustomMessages();
  await this._emitAgentSettled();                  // agent_settled 事件；在 waitForIdle 上等着的调用方此时返回
}

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

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

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

    // 先补上工具变化，再把这些消息注入上下文
    for (const m of declareToolChanges(currentContext, [...preparedMessages, ...pendingMessages])) {
      emit(message_start); emit(message_end); currentContext.messages.push(m); newMessages.push(m);
    }
    pendingMessages = [];

    const update = await config.prepareRequest?.({ context: currentContext, model, thinkingLevel }, signal);
    if (update) { currentContext = update.context ?? currentContext; config = {...config, model, reasoning}; }

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

    if (message.stopReason === "error" || message.stopReason === "aborted") {
      await config.finishTurn?.({ message, toolResults: [], ... });   // 照样调，但结果不看
      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); }
    }

    lastCompletedTurn = { message, toolResults, context: currentContext, newMessages };
    const decision = await config.finishTurn?.(lastCompletedTurn, signal);   // 在 turn_end 之前
    await emit({ type: "turn_end", message, toolResults });

    if (decision?.action === "end") { emit(agent_end); return; }

    explicitContinuation = decision?.action === "continue";
    pendingMessages = await config.getSteeringMessages?.() || [];
    if (hasMoreToolCalls || pendingMessages.length > 0) explicitContinuation = false;  // 本来就要继续
  }

  const followUps = await config.getFollowUpMessages?.() || [];
  if (followUps.length > 0) { pendingMessages = followUps; continue; }       // 回内层
  if (explicitContinuation) { explicitContinuation = false; continue; }      // finishTurn 要求的那一次
  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 }