@downcity/agent 1.1.11 → 1.1.13

package/src/sdk/SessionSystemBuilder.ts

@@ -0,0 +1,261 @@
+/**
+ * SDK Session 默认 system composer。
+ *
+ * 关键点（中文）
+ * - 面向 `Agent` SDK 的本地会话执行场景。
+ * - 注入调用方显式传入的静态 instruction、显式注入 service system 与显式注册 plugin system。
+ * - SDK 不在 system 中注入动态变量；动态上下文应由调用方放入 user message。
+ */
+
+import { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
+import { getSessionRunScope } from "@session/SessionRunScope.js";
+import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
+import type {
+  AgentSessionSystemBlock,
+  AgentSessionSystemSessionInfo,
+} from "@/sdk/AgentSdkTypes.js";
+
+/**
+ * 解析 SDK session system blocks 的输入。
+ */
+export interface BuildSessionSystemBlocksParams {
+  /**
+   * 当前 agent 的稳定标识。
+   */
+  agentId: string;
+
+  /**
+   * 当前 agent 绑定的项目根目录。
+   */
+  projectRoot: string;
+
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 session 首次创建时间（ms）。
+   */
+  createdAt: number;
+
+  /**
+   * 当前 session 初始化时解析到的系统时区。
+   */
+  timezone: string;
+
+  /**
+   * 读取当前 SDK 调用方传入的 instruction system blocks。
+   */
+  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+
+  /**
+   * 读取当前显式注入 service 的 system blocks。
+   */
+  getServiceSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 读取当前显式注册 plugin 的 system blocks。
+   */
+  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+}
+
+type SessionSystemBuilderOptions = {
+  /**
+   * 当前 agent 的稳定标识。
+   */
+  agentId: string;
+
+  /**
+   * 当前 agent 绑定的项目根目录。
+   */
+  projectRoot: string;
+
+  /**
+   * 读取当前 session 首次创建时间（ms）。
+   */
+  getSessionCreatedAt: () => number;
+
+  /**
+   * 读取当前 session 初始化时解析到的系统时区。
+   */
+  getSessionTimezone: () => string;
+
+  /**
+   * 读取当前 SDK 调用方传入的 instruction system blocks。
+   */
+  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+
+  /**
+   * 读取当前显式注册 plugin 的 system blocks。
+   */
+  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 读取当前显式注入 service 的 system blocks。
+   */
+  getServiceSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+};
+
+function normalizeSystemBlocks(
+  blocks: AgentSessionSystemBlock[],
+): AgentSessionSystemBlock[] {
+  if (!Array.isArray(blocks)) return [];
+  return blocks
+    .map((block) => {
+      const content = String(block?.content || "").trim();
+      if (!content) return null;
+      const source = block.source;
+      if (
+        source !== "core" &&
+        source !== "instruction" &&
+        source !== "service" &&
+        source !== "plugin" &&
+        source !== "session"
+      ) {
+        return null;
+      }
+      return {
+        source,
+        name: String(block.name || source).trim() || source,
+        content,
+      } satisfies AgentSessionSystemBlock;
+    })
+    .filter((block): block is AgentSessionSystemBlock => Boolean(block));
+}
+
+function createSessionInfo(
+  params: Pick<
+    BuildSessionSystemBlocksParams,
+    "agentId" | "sessionId" | "projectRoot" | "createdAt" | "timezone"
+  >,
+): AgentSessionSystemSessionInfo {
+  const createdAt = Number.isFinite(params.createdAt) ? params.createdAt : 0;
+  return {
+    agentId: String(params.agentId || "").trim(),
+    sessionId: String(params.sessionId || "").trim(),
+    projectRoot: String(params.projectRoot || "").trim(),
+    createdAt: new Date(createdAt).toISOString(),
+    timezone: String(params.timezone || "").trim() || "UTC",
+  };
+}
+
+function createSessionSystemBlock(
+  session: AgentSessionSystemSessionInfo,
+): AgentSessionSystemBlock {
+  const content = [
+    "当前会话上下文：",
+    `你正在服务 agent "${session.agentId}" 的 session "${session.sessionId}"。`,
+    `当前项目根目录是 "${session.projectRoot}"。`,
+    `本会话创建于 ${session.createdAt}，参考时区是 ${session.timezone}。`,
+    "这个创建时间是当前会话的稳定参考时间，不代表每轮运行时的当前时间。",
+    "如果用户消息中提供了新的当前时间、相对时间或其他动态上下文，应优先使用用户消息中的动态信息。",
+  ].join("\n");
+  return {
+    source: "session",
+    name: "context",
+    content,
+  };
+}
+
+/**
+ * 解析 SDK session 当前生效的 system blocks。
+ */
+export async function buildSessionSystemBlocks(
+  params: BuildSessionSystemBlocksParams,
+): Promise<AgentSessionSystemBlock[]> {
+  const agentId = String(params.agentId || "").trim();
+  const projectRoot = String(params.projectRoot || "").trim();
+  const sessionId = String(params.sessionId || "").trim();
+  const createdAt = Number(params.createdAt || 0);
+  const timezone = String(params.timezone || "").trim();
+  if (!agentId) {
+    throw new Error("buildSessionSystemBlocks requires a non-empty agentId");
+  }
+  if (!projectRoot) {
+    throw new Error("buildSessionSystemBlocks requires a non-empty projectRoot");
+  }
+  if (!sessionId) {
+    throw new Error("buildSessionSystemBlocks requires a non-empty sessionId");
+  }
+  if (!Number.isFinite(createdAt) || createdAt <= 0) {
+    throw new Error("buildSessionSystemBlocks requires a valid createdAt");
+  }
+  if (!timezone) {
+    throw new Error("buildSessionSystemBlocks requires a non-empty timezone");
+  }
+  return [
+    ...normalizeSystemBlocks(params.getInstructionSystemBlocks()),
+    ...normalizeSystemBlocks(await params.getServiceSystemBlocks()),
+    ...normalizeSystemBlocks(await params.getPluginSystemBlocks()),
+    // session block 放在最后，尽量保留前缀 system blocks 的跨 session 缓存命中。
+    createSessionSystemBlock(
+      createSessionInfo({ agentId, projectRoot, sessionId, createdAt, timezone }),
+    ),
+  ];
+}
+
+/**
+ * 解析 SDK session 当前生效的 system messages。
+ */
+export async function buildSessionSystemMessages(
+  params: BuildSessionSystemBlocksParams,
+): Promise<SessionSystemMessage[]> {
+  const blocks = await buildSessionSystemBlocks(params);
+  return blocks.map((block) => ({
+    role: "system" as const,
+    content: block.content,
+  }));
+}
+
+/**
+ * SDK Session system composer 实现。
+ */
+export class SessionSystemBuilder extends SessionSystemComposer {
+  readonly name = "sdk_prompt_system";
+
+  private readonly agentId: string;
+  private readonly projectRoot: string;
+  private readonly getSessionCreatedAt: SessionSystemBuilderOptions["getSessionCreatedAt"];
+  private readonly getSessionTimezone: SessionSystemBuilderOptions["getSessionTimezone"];
+  private readonly getInstructionSystemBlocks: SessionSystemBuilderOptions["getInstructionSystemBlocks"];
+  private readonly getServiceSystemBlocks: SessionSystemBuilderOptions["getServiceSystemBlocks"];
+  private readonly getPluginSystemBlocks: SessionSystemBuilderOptions["getPluginSystemBlocks"];
+
+  constructor(options: SessionSystemBuilderOptions) {
+    super();
+    this.agentId = String(options.agentId || "").trim();
+    this.projectRoot = String(options.projectRoot || "").trim();
+    this.getSessionCreatedAt = options.getSessionCreatedAt;
+    this.getSessionTimezone = options.getSessionTimezone;
+    this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
+    this.getServiceSystemBlocks = options.getServiceSystemBlocks;
+    this.getPluginSystemBlocks = options.getPluginSystemBlocks;
+    if (!this.agentId) {
+      throw new Error("SessionSystemBuilder requires a non-empty agentId");
+    }
+    if (!this.projectRoot) {
+      throw new Error("SessionSystemBuilder requires a non-empty projectRoot");
+    }
+  }
+
+  /**
+   * 解析本轮 SDK session system messages。
+   */
+  async resolve() {
+    const sessionId = String(getSessionRunScope()?.sessionId || "").trim();
+    if (!sessionId) {
+      throw new Error("SessionSystemBuilder.resolve requires a non-empty sessionId");
+    }
+    return await buildSessionSystemMessages({
+      agentId: this.agentId,
+      projectRoot: this.projectRoot,
+      sessionId,
+      createdAt: this.getSessionCreatedAt(),
+      timezone: this.getSessionTimezone(),
+      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getServiceSystemBlocks: this.getServiceSystemBlocks,
+      getPluginSystemBlocks: this.getPluginSystemBlocks,
+    });
+  }
+}

package/src/service/builtins/chat/runtime/ChatSession.ts

@@ -1,5 +1,5 @@
 /**
- * ChatSession：chat 专用 Session 实现。
+ * ChatSession：chat 专用 Executor 实现。
  *
  * 关键点（中文）
  * - ChatSession 在实例化时持有自己的 execution composer 实例。
@@ -7,10 +7,13 @@
  * - 外层仍只调用标准 `run(...)`；chat 语义由 ChatSession 内部收敛。
  */
 
-import { Session } from "@session/Session.js";
+import type { LanguageModel, Tool } from "ai";
+import { Executor } from "@session/Executor.js";
 import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
+import type { SessionCompactionComposer } from "@session/composer/compaction/SessionCompactionComposer.js";
+import type { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
 import type { ChatSessionExecutionComposer } from "@/service/builtins/chat/runtime/ChatSessionExecutionComposer.js";
-import type { SessionExecutor } from "@/session/types/SessionExecutor.js";
+import type { Logger } from "@/utils/logger/Logger.js";
 import type { SessionAssistantStepCallback } from "@/session/types/SessionRun.js";
 import type { SessionRunResult } from "@/session/types/SessionRun.js";
 import type { ChatSessionTurnState } from "@/service/builtins/chat/runtime/ChatSessionTypes.js";
@@ -27,17 +30,34 @@ type ChatSessionOptions = {
   historyComposer: SessionHistoryComposer;
 
   /**
-   * 当前 session 绑定的 chat execution composer。
+   * 读取当前 session 使用的模型实例。
    */
-  executionComposer: ChatSessionExecutionComposer;
+  getModel: () => LanguageModel | undefined;
+
+  /**
+   * 统一日志器。
+   */
+  logger: Logger;
+
+  /**
+   * 当前 session 对应的 compaction Composer。
+   */
+  compactionComposer: SessionCompactionComposer;
 
   /**
-   * 创建当前 session 的执行器。
+   * 当前 session 对应的 system Composer。
    */
-  createExecutor: (
-    historyComposer: SessionHistoryComposer,
-    executionComposer: ChatSessionExecutionComposer,
-  ) => SessionExecutor;
+  systemComposer: SessionSystemComposer;
+
+  /**
+   * 获取当前可用工具集合。
+   */
+  getTools: () => Record<string, Tool>;
+
+  /**
+   * 当前 session 绑定的 chat execution composer。
+   */
+  executionComposer: ChatSessionExecutionComposer;
 
   /**
    * session 更新后的异步回调。
@@ -48,7 +68,7 @@ type ChatSessionOptions = {
 /**
  * Chat 专用 Session。
  */
-export class ChatSession extends Session {
+export class ChatSession extends Executor {
   /**
    * ChatSession 持有的 composer 实例。
    */
@@ -61,8 +81,12 @@ export class ChatSession extends Session {
     super({
       sessionId: options.sessionId,
       historyComposer: options.historyComposer,
-      createExecutor: (historyComposer) =>
-        options.createExecutor(historyComposer, executionComposer),
+      getModel: options.getModel,
+      logger: options.logger,
+      compactionComposer: options.compactionComposer,
+      systemComposer: options.systemComposer,
+      getTools: options.getTools,
+      executionComposer,
       ...(options.runAfterSessionUpdated
         ? { runAfterSessionUpdated: options.runAfterSessionUpdated }
         : {}),

package/src/service/builtins/task/runtime/Runner.ts

@@ -3,7 +3,7 @@
  *
  * 职责（中文）
  * - 创建 run 目录（timestamp）。
- * - 以“干净历史”调用当前 runtime 的 LocalSessionCore（逻辑与正常 chat 一致）。
+ * - 以“干净历史”调用当前 runtime 的 Runner（逻辑与正常 chat 一致）。
  * - 协调 script / agent 两类执行主链。
  * - 把最终产物写入 run 目录的具体格式委托给 `TaskRunArtifacts.ts`。
  */

package/src/service/builtins/task/runtime/TaskRunnerSession.ts

@@ -2,7 +2,7 @@
  * TaskRunnerSession：task runner 的 session 装配模块。
  *
  * 关键点（中文）
- * - 负责构建 task 专用 LocalSessionCore / JsonlSessionHistoryComposer 运行时。
+ * - 负责构建 task 专用 Runner / JsonlSessionHistoryComposer 运行时。
  * - 负责把每轮 user/assistant 消息写入 run 目录对应的 messages.jsonl。
  * - 这些能力与任务编排逻辑解耦后，Runner 主流程会更聚焦于状态流转。
  * - 当前只有 api 执行模式。
@@ -12,7 +12,7 @@ import path from "node:path";
 import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { SessionRunResult } from "@/session/types/SessionRun.js";
 import type { TaskSessionRuntimePort } from "@/service/builtins/task/runtime/TaskRunnerTypes.js";
-import { LocalSessionCore } from "@session/executors/local/LocalSessionCore.js";
+import { Runner } from "@session/executors/local/Runner.js";
 import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
 import { JsonlSessionHistoryComposer } from "@session/composer/history/jsonl/JsonlSessionHistoryComposer.js";
 import { JsonlSessionCompactionComposer } from "@session/composer/compaction/jsonl/JsonlSessionCompactionComposer.js";
@@ -54,7 +54,7 @@ export async function appendTaskRoundUserMessage(params: {
  * 构建 task 专用 Session 运行时（独立于普通 Session 实例缓存）。
  *
  * 关键点（中文）
- * - 使用 LocalSessionCore 执行，模型来自 context.session.model（agent 级模型）。
+ * - 使用 Runner 执行，模型来自 context.session.model（agent 级模型）。
  */
 export function createTaskSessionRuntimePort(params: {
   context: AgentContext;
@@ -132,7 +132,7 @@ export function createTaskSessionRuntimePort(params: {
         sessionId: key,
         getTools: () => shellTools,
       });
-      const created = new LocalSessionCore({
+      const created = new Runner({
         model: context.session.model,
         logger: context.logger,
         historyComposer,

package/src/service/builtins/task/runtime/TaskRunnerTypes.ts

@@ -170,7 +170,7 @@ export type ScriptExecutionResult = {
  * task 运行专用的 session runtime 端口。
  *
  * 关键点（中文）
- * - task runner 不直接依赖具体 `LocalSessionExecutor` 实现。
+ * - task runner 不直接依赖具体 SDK `Session` 实现。
  * - 这里暴露的是 task 场景最小可用端口：执行器 + history Composer。
  */
 export type TaskSessionRuntimePort = {

package/src/session/{Session.ts → Executor.ts}

@@ -1,23 +1,31 @@
 /**
- * Session：单个会话实例。
+ * Executor：单个 session 的执行编排器。
  *
  * 关键点（中文）
- * - 一个 Session 只对应一个固定的 `sessionId`。
- * - 对外直接暴露 `run / appendUserMessage / appendAssistantMessage / getExecutor / getHistoryComposer`。
- * - 运行态（如 executing）直接收在实例内部，不再拆 `Facade / Runner / ExecutionRegistry`。
+ * - SDK 对外对象叫 `Session`，这里是内部执行层。
+ * - 一个 Executor 只对应一个固定的 `sessionId`。
+ * - 负责 history 写入、run scope、executing 状态与本地 Runner 的懒创建。
  */
 
+import type { LanguageModel, Tool } from "ai";
 import { SessionHistoryWriter } from "@session/composer/history/SessionHistoryWriter.js";
 import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
 import { withSessionRunScope } from "@session/SessionRunScope.js";
 import type { SessionRunScope } from "@session/SessionRunScope.js";
 import { buildSessionStepEventMessages } from "@session/messages/SessionStepEventMapper.js";
+import { JsonlSessionCompactionComposer } from "@session/composer/compaction/jsonl/JsonlSessionCompactionComposer.js";
+import { LocalSessionExecutionComposer } from "@session/composer/execution/LocalSessionExecutionComposer.js";
+import type { SessionCompactionComposer } from "@session/composer/compaction/SessionCompactionComposer.js";
+import type { SessionExecutionComposer } from "@session/composer/execution/SessionExecutionComposer.js";
+import type { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
+import { Runner } from "@session/executors/local/Runner.js";
+import type { Logger } from "@/utils/logger/Logger.js";
 import type { JsonObject } from "@/types/common/Json.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import type { SessionExecutor } from "@/session/types/SessionExecutor.js";
 import type { SessionRunResult } from "@/session/types/SessionRun.js";
 
-type SessionOptions = {
+type ExecutorOptions = {
   /**
    * 当前会话 ID。
    */
@@ -29,9 +37,34 @@ type SessionOptions = {
   historyComposer: SessionHistoryComposer;
 
   /**
-   * 创建当前 session 对应的执行器。
+   * 读取当前 session 使用的模型实例。
    */
-  createExecutor: (historyComposer: SessionHistoryComposer) => SessionExecutor;
+  getModel: () => LanguageModel | undefined;
+
+  /**
+   * 统一日志器。
+   */
+  logger: Logger;
+
+  /**
+   * 当前 session 对应的 compaction Composer。
+   */
+  compactionComposer?: SessionCompactionComposer;
+
+  /**
+   * 当前 session 对应的 system Composer。
+   */
+  systemComposer: SessionSystemComposer;
+
+  /**
+   * 获取当前可用工具集合。
+   */
+  getTools: () => Record<string, Tool>;
+
+  /**
+   * 可选自定义 execution Composer。
+   */
+  executionComposer?: SessionExecutionComposer;
 
   /**
    * session 更新后的异步回调。
@@ -40,30 +73,41 @@ type SessionOptions = {
 };
 
 /**
- * Session 单实例实现。
+ * Executor 单实例实现。
  */
-export class Session {
+export class Executor implements SessionExecutor {
   /**
    * 当前 session 标识。
    */
   readonly sessionId: string;
 
   private readonly historyComposer: SessionHistoryComposer;
-  private readonly createExecutor: SessionOptions["createExecutor"];
+  private readonly getModel: ExecutorOptions["getModel"];
+  private readonly logger: Logger;
+  private readonly compactionComposer: SessionCompactionComposer;
+  private readonly systemComposer: SessionSystemComposer;
+  private readonly getTools: ExecutorOptions["getTools"];
+  private readonly runnerExecutionComposer?: SessionExecutionComposer;
   private readonly historyWriter: SessionHistoryWriter;
 
-  private executor: SessionExecutor | null = null;
+  private runner: Runner | null = null;
   private executing = false;
 
-  constructor(options: SessionOptions) {
+  constructor(options: ExecutorOptions) {
     const sessionId = String(options.sessionId || "").trim();
     if (!sessionId) {
-      throw new Error("Session requires a non-empty sessionId");
+      throw new Error("Executor requires a non-empty sessionId");
     }
 
     this.sessionId = sessionId;
     this.historyComposer = options.historyComposer;
-    this.createExecutor = options.createExecutor;
+    this.getModel = options.getModel;
+    this.logger = options.logger;
+    this.compactionComposer =
+      options.compactionComposer || new JsonlSessionCompactionComposer();
+    this.systemComposer = options.systemComposer;
+    this.getTools = options.getTools;
+    this.runnerExecutionComposer = options.executionComposer;
     this.historyWriter = new SessionHistoryWriter({
       sessionId,
       getHistoryComposer: () => this.getHistoryComposer(),
@@ -86,26 +130,52 @@ export class Session {
   }
 
   /**
-   * 获取当前 session 的执行器。
+   * 获取当前 session 的执行端口。
+   *
+   * 关键点（中文）
+   * - 兼容 runtime/service 端口语义：Executor 自己就是执行端口。
    */
   getExecutor(): SessionExecutor {
-    if (this.executor) return this.executor;
-    const created = this.createExecutor(this.getHistoryComposer());
-    this.executor = created;
+    return this;
+  }
+
+  /**
+   * 获取或创建当前本地 Runner。
+   */
+  private getRunner(): Runner {
+    if (this.runner) return this.runner;
+    const model = this.getModel();
+    if (!model) {
+      throw new Error(
+        `Executor for session "${this.sessionId}" requires a configured model`,
+      );
+    }
+    const created = new Runner({
+      model,
+      logger: this.logger,
+      historyComposer: this.getHistoryComposer(),
+      compactionComposer: this.compactionComposer,
+      systemComposer: this.systemComposer,
+      executionComposer:
+        this.runnerExecutionComposer ||
+        new LocalSessionExecutionComposer({
+          sessionId: this.sessionId,
+          getTools: this.getTools,
+        }),
+    });
+    this.runner = created;
     return created;
   }
 
   /**
-   * 清理当前 session 的执行器缓存。
+   * 清理当前 session 的 Runner 缓存。
    *
    * 关键点（中文）
-   * - 这里只清 executor，不清 history Composer。
-   * - history 是事实源，不应随着 executor 一起丢失。
+   * - 这里只清 Runner，不清 history Composer。
+   * - history 是事实源，不应随着 Runner 一起丢失。
    */
   clearExecutor(): void {
-    const current = this.executor;
-    this.executor = null;
-    
+    this.runner = null;
   }
 
   /**
@@ -153,7 +223,7 @@ export class Session {
     if (this.executing) {
       // 关键点（中文）：同一个 Session 实例只允许一个活跃 run，
       // 否则 step 回调、scope 与执行器状态都会互相污染。
-      throw new Error("Session.run does not support concurrent execution");
+      throw new Error("Executor.run does not support concurrent execution");
     }
     const query = String(params.query || "").trim();
     const sessionRunScope: Omit<SessionRunScope, "sessionId"> = {
@@ -206,7 +276,7 @@ export class Session {
           ...sessionRunScope,
           onAssistantStepCallback: wrappedOnAssistantStepCallback,
         },
-        () => this.getExecutor().run({ query }),
+        () => this.getRunner().run({ query }),
       );
       if (persistedAssistantStepCount <= 0) return result;
 

package/src/session/composer/SessionComposer.ts

@@ -15,7 +15,7 @@ export abstract class SessionComposer {
    * 可选初始化钩子。
    *
    * 关键点（中文）
-   * - LocalSessionExecutor 启动时可统一调用。
+   * - Executor / Runner 启动时可统一调用。
    * - 无需初始化的 Composer 可不实现。
    */
   async init(): Promise<void> {

package/src/session/composer/compaction/SessionCompactionComposer.ts

@@ -30,7 +30,7 @@ export type SessionCompactionInput = {
   system: SystemModelMessage[];
 
   /**
-   * 当前重试次数（由 LocalSessionCore 递增）。
+   * 当前重试次数（由 Runner 递增）。
    */
   retryCount: number;
 };
@@ -57,7 +57,7 @@ export abstract class SessionCompactionComposer extends SessionComposer {
    *
    * 关键点（中文）
    * - 由 compaction Composer 实现侧维护错误识别策略。
-   * - LocalSessionCore 不感知具体错误文案，只按该布尔结果决定是否重试。
+   * - Runner 不感知具体错误文案，只按该布尔结果决定是否重试。
    */
   abstract shouldCompactOnError(error: unknown): boolean;
 

package/src/session/composer/execution/LocalSessionExecutionComposer.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 统一组装 tools。
- * - step 边界回调从 SessionRunScope 读取，LocalSessionCore 不直接管理来源。
+ * - step 边界回调从 SessionRunScope 读取，Runner 不直接管理来源。
  */
 
 import type { ModelMessage } from "ai";

package/src/session/composer/execution/SessionExecutionComposer.ts

@@ -65,7 +65,7 @@ export abstract class SessionExecutionComposer extends SessionComposer {
    * 构造 fallback assistant 消息。
    *
    * 关键点（中文）
- * - fallback 消息构造由 execution Composer 内部实现，LocalSessionCore 不直接依赖 history Composer。
+ * - fallback 消息构造由 execution Composer 内部实现，Runner 不直接依赖 history Composer。
    */
   abstract buildFallbackAssistantMessage(text: string): SessionMessageV1;
 }

package/src/session/composer/history/SessionHistoryComposer.ts

@@ -39,7 +39,7 @@ export type SessionHistoryPrepareInput = {
   model: LanguageModel;
 
   /**
-   * 当前重试次数（由 LocalSessionCore 递增）。
+   * 当前重试次数（由 Runner 递增）。
    */
   retryCount: number;
 };

package/src/session/composer/system/SessionSystemComposer.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 专职负责“会话上下文 -> system messages”解析。
- * - 与 tools / step 编排解耦，避免 LocalSessionCore 过载。
+ * - 与 tools / step 编排解耦，避免 Runner 过载。
  */
 
 import type { SystemModelMessage } from "ai";