agent-session 模块分析1. 模块定位与文件范围该模块位于packages/coding-agent/src/core，不是单一文件，而是一组协同组件：核心实现E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\agent-session.tsAgentSession主类约 4023 行负责 agent 生命周期、消息处理、扩展、队列、重试、压缩、Bash、工具、模型和上下文管理E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\agent-session-services.ts创建 cwd 绑定的运行时服务负责ModelRuntime、SettingsManager、ResourceLoader的组装E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\agent-session-runtime.ts管理当前AgentSession实例及其替换负责 new/resume/fork/import、生命周期 teardown 和重新绑定E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\sdk.tscreateAgentSession()工厂将模型、认证、资源、工具、低层Agent和SessionManager组装成AgentSessionE:\Workspace\TypeScript\pi\packages\coding-agent\src\core\session-manager.tsJSONL 会话持久化会话树、分支、叶节点、上下文投影、压缩边界和上下文编辑直接依赖的核心实现E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\compaction\compaction.tstoken 估算压缩切点计算压缩准备和总结调用的底层逻辑E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\compaction\index.ts压缩相关 API 汇总E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\messages.tsAgentMessage、自定义消息、Bash 消息、压缩消息的转换E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\extensions\index.ts扩展事件、工具、边界钩子和上下文接口E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\model-runtime.ts模型和认证运行时E:\Workspace\TypeScript\pi\packages\coding-agent\src\core\resource-loader.tsskills、prompt template、system prompt、extensions 等资源加载本次分析未修改任何文件。2. 设计初衷2.1AgentSession的定位AgentSession是所有运行模式共享的会话抽象，文件头部已经明确说明其职责：文件：agent-session.ts行：1-14它被 interactive、print、RPC 等不同模式共用。模式本身只负责输入输出层，AgentSession负责：持有低层Agent将 agent 事件同步到会话持久化对外发布统一的 session 事件管理模型和 thinking level管理 steering/follow-up 消息执行手动和自动压缩执行和记录 Bash管理扩展生命周期支持会话树导航、fork、resume 和 session replacement维护 canonical session projection，确保实际发送给模型的上下文来自会话树，而不是临时内存数组核心设计可以概括为：低层 Agent ├─ 负责模型调用、工具调用、流式循环和队列 └─ 发出 AgentEvent AgentSession ├─ 接收 AgentEvent ├─ 转换并持久化到 SessionManager ├─ 调用 ExtensionRunner ├─ 处理 retry / compaction / boundary └─ 向 UI/RPC 暴露 AgentSessionEvent SessionManager ├─ 维护 append-only JSONL ├─ 维护 session tree ├─ 解析当前 leaf 分支 └─ 生成模型可见 projection2.2 为什么需要独立的AgentSessionRuntimeAgentSession本身代表“一个正在运行的会话”，而AgentSessionRuntime代表“当前会话及其可替换运行环境”。这样可以把以下两种生命周期分开：单个 session 内部：prompttool callretrycompactionqueue当前 session 被替换：/new/resume/fork/import文件：agent-session-runtime.ts行：67-72替换时先让旧 session settle、保存中断状态、触发 shutdown，再销毁旧对象并创建新对象，避免旧扩展上下文、旧事件订阅和旧 UI 引用泄漏。3. 总体对象关系3.1 创建链路入口是：sdk.ts:175createAgentSession()主要流程：createAgentSession() ├─ 解析 cwd / agentDir ├─ 创建 ModelRuntime ├─ 创建 SettingsManager ├─ 创建或复用 SessionManager ├─ 创建并 reload ResourceLoader ├─ 从 SessionManager 恢复已有 context ├─ 恢复或选择 Model ├─ 恢复或计算 ThinkingLevel ├─ 计算初始工具集合 ├─ 创建底层 Agent ├─ 写入初始 model/thinking 元数据 └─ new AgentSession(...)关键代码：sdk.ts:175-190：基础服务创建sdk.ts:193-228：恢复 session context 和 modelsdk.ts:231-256：恢复/选择 thinking levelsdk.ts:258-265：工具 allowlist/denylist 和默认工具sdk.ts:380-415：创建底层Agentsdk.ts:417-428：写入 session 元数据sdk.ts:430-445：创建AgentSession3.2 分层职责ModelRuntime负责：模型注册provider 注册auth 查询provider 刷新流式请求AgentSession不直接猜测 API key 或 endpoint，而是通过：agent-session.ts:455-493_getRequiredRequestAuth()agent-session.ts:495-522_getSummarizationRequestAuth()取得请求模型和认证信息。Agent来自@earendil-works/pi-agent-core，负责：promptcontinueabortagent looptool executionsteering queuefollow-up queueAgentEventAgentSession通过构造函数订阅：agent-session.ts:435-448SessionManager负责：JSONL 文件session headerentry appendsession treeleaf pointercontext projectionExtensionRunner负责：扩展事件分发扩展工具slash commandsession lifecycle hookturn_end/agent_before_settleboundary自定义 compaction自定义 branch summary4. 核心类型和数据结构4.1AgentSessionEvent文件：agent-session.ts:163-205它在低层AgentEvent基础上增加 session 级别事件：Agent 事件透传除agent_end外，基本继承AgentEvent。agent_end被扩展为：{type:"agent_end";messages:AgentMessage[];willRetry:boolean;}这样 UI 可以知道当前 agent 结束是否会自动 retry。Session 专属事件agent_settled所有 agent/extension 后处理完成queue_update当前 steering/follow-up 队列compaction_startcompaction_endentry_appendedsession_info_changedthinking_level_changedauto_retry_startauto_retry_endsummarization retry 事件bash_execution_update这套事件是 UI、RPC 和其他运行模式的主要观察接口。4.2AgentSessionConfig文件：agent-session.ts:220-252主要字段：字段用途agent低层 agentsessionManagersession 持久化和上下文树settingsManager配置与行为开关cwd当前工作目录scopedModelsmodel cycling 范围resourceLoaderprompt/skill/extension/system promptcustomToolsSDK 外部注册的工具modelRuntime模型和认证运行时cacheWarmerprompt cache 预热initialActiveToolNames初始激活工具allowedToolNames工具 allowlistexcludedToolNames工具 denylistbaseToolsOverride自定义基础工具extensionRunnerRef对外暴露当前 ExtensionRunnersessionStartEventsession 启动原因4.3AgentSession的主要状态变量定义位置：agent-session.ts:331-413Agent 生命周期状态_isAgentRunActive是否正在执行 agent run 或后续 continuation_agentRunAbortRequested当前 agent run 是否要求终止_idleWaitPromise_resolveIdleWaitwaitForIdle()使用的等待机制队列状态_steeringMessages运行期间插入、优先影响下一次请求的消息_followUpMessages当前 turn 完成后再处理的消息_pendingNextTurnMessages作为下一次 prompt context 注入的 custom message_pendingCustomMessages运行期间产生、但要等待当前工具结果完成后才能持久化的 custom message压缩状态_compactionAbortController手动压缩_autoCompactionAbortController自动压缩_overflowRecoveryAttempted单次上下文溢出只允许一次 compact-and-retry总结和重试状态_branchSummaryAbortControllertree navigation 的 branch summary_retryAbortControlleragent retry 的 backoff 等待_retryAttempt当前 retry 次数Bash 状态_bashAbortControllers所有正在运行的 Bash_pendingBashMessagesstreaming 期间暂存的 Bash 结果扩展和 boundary 状态_extensionRunner_tur