`createAgentSession()` 怎样交出一个可运行会话

createAgentSession() 的名字容易让人以为它只是 new AgentSession() 的异步包装。实际函数横跨两层：先补齐调用方没有提供的依赖，再建立底层 Agent 的初始状态；最后 AgentSession 才把资源、工具、持久化和扩展钩子接上去。它返回的是“可以被调用”的会话，不会替调用方自动发送第一条 prompt。

调用方可以交进来什么

CreateAgentSessionOptions 允许覆盖 cwd、agentDir、ModelRuntime、模型与 thinking level、工具 allowlist/denylist、自定义工具、ResourceLoader、SessionManager 和 SettingsManager。CLI 在上一章已经把这些服务准备好；SDK 直接调用时，函数会自己创建默认对象。

默认路径值得单独记住。cwd 取显式 options、已有 session manager 的 cwd 或 process.cwd()；agentDir 默认来自 Pi 配置目录。若未注入，函数会创建 ModelRuntime、SettingsManager 和持久化的 SessionManager，并新建 DefaultResourceLoader 后立即 reload。测试或嵌入场景若不想落 session 文件，必须显式使用 SessionManager.inMemory()，不能把“不传 sessionManager”理解为内存模式。

恢复优先于默认值

依赖齐备后，函数先读取 sessionManager.buildSessionContext()。既有会话会尝试恢复保存的 provider/model；只有恢复失败或没有记录时，才按 settings 默认和可用 provider 选择初始模型。thinking level 也先看会话分支里的变更记录，再看 settings，最后按模型能力 clamp。这个顺序保证 resume 不会悄悄退回当前全局默认，同时用 modelFallbackMessage 暴露无法恢复的情况。

工具选择发生在创建 Agent 之前。默认 active tools 是 read、bash、edit、write；显式 tools 变成 allowlist，excludeTools 随后过滤。底层 Agent 刚创建时 tools 仍为空，它先得到 systemPrompt、model、thinkingLevel、消息转换函数、streamFn 和队列策略。真正的工具 registry 与系统提示稍后由 AgentSession 建立。

new AgentSession() 收到 Agent、三类 manager、cwd、resource loader、model runtime 和工具策略。构造函数订阅底层 Agent 事件，安装工具与 next-turn hooks，然后 _buildRuntime() 创建内置工具定义、ExtensionRunner、工具 registry 和最终 system prompt。至此，会话才同时具备 prompt()、事件订阅、持久化和扩展能力。

可以用下面的只读实验把两次构造放在同一屏里。它不会加载本机配置，也不会创建会话文件：

repo="${PI_SOURCE_DIR:-/tmp/pi-handbook-qbQTcA}"
git -C "$repo" show v0.83.0:packages/coding-agent/src/core/sdk.ts |
  nl -ba | sed -n '169,243p;245,300p;362,397p'
git -C "$repo" show v0.83.0:packages/coding-agent/src/core/agent-session.ts |
  nl -ba | sed -n '375,401p;2548,2600p'

还有一条边界暂时不要跨过去。Agent 内部保存的是 AgentMessage[]，coding-agent 还通过声明合并加入 bash execution、custom、branch summary、compaction summary 等消息；发给 provider 前，它们要经过 convertToLlm() 转成 pi-ai 的 Message[]。createAgentSession() 只把转换函数装进 Agent，没有解释消息联合类型本身。

第一部到这里交出了一份能运行的 session handle。第 6 章从 AgentMessage 边界接手：哪些消息可以留在 Agent 状态里，哪些内容会被转换后送进模型上下文。