@downcity/agent 1.1.79 → 1.1.82

package/src/session/Session.ts

@@ -3,124 +3,55 @@
  *
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
- * - 统一收口消息落盘、session 级模型配置、prompt/subscribe/fork 等高层 API。
+ * - 对外保留稳定 Session facade，把状态、turn、view 逻辑下沉到独立 service。
  * - 内部继续复用 `Executor` / `JsonlSessionHistoryStore` / Composer 体系。
  */
 
-import { nanoid } from "nanoid";
-import type { Tool } from "ai";
 import { Executor } from "@executor/Executor.js";
+import type { Tool } from "ai";
 import { JsonlSessionHistoryComposer } from "@executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
 import { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
-import { extractTextFromUiMessage } from "@/executor/messages/UIMessageTransformer.js";
 import type {
   AgentSession,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
+  AgentSessionHistoryInput,
+  AgentSessionHistoryPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSystemBlock,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/AgentTypes.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
-import {
-  buildSessionSystemBlocks,
-  SessionSystemBuilder,
-} from "@/session/SessionSystemBuilder.js";
-import {
-  buildSessionHistoryPage,
-  buildSessionInfo,
-  patchSessionModelLabel,
-  readSessionMetadata,
-  resolveSystemTimezone,
-  writeSessionMetadata,
-} from "@/session/index.js";
 import {
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
   getSdkAgentSessionInflightPath,
+  resolveSystemTimezone,
+  createRuntimeSessionPort,
 } from "@/session/index.js";
+import { SessionSystemBuilder } from "@/session/SessionSystemBuilder.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
-import {
-  mapAgentEventToSessionEvent,
-  mapUiMessageChunkToAgentEvent,
-} from "@/session/SessionEventMapper.js";
-import {
-  persistSdkAssistantResult,
-  touchSessionMetadata,
-} from "@/session/index.js";
-import { createRuntimeSessionPort } from "@/session/index.js";
-import { drainDeferredPersistedUserMessages } from "@executor/SessionRunScope.js";
 import type {
   AgentSessionSubscriber,
   AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
-import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
 import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
-import { SessionPromptRuntime } from "@/session/runtime/SessionPromptRuntime.js";
-import {
-  inferAgentModelLabel,
-  normalizeAgentModel,
-} from "@/model/CityModelAdapter.js";
-import { ensureSessionTitle } from "@/session/SessionTitle.js";
-
-type SessionOptions = {
-  /**
-   * 当前 agent 稳定标识。
-   */
-  agentId: string;
-
-  /**
-   * 当前项目根目录。
-   */
-  projectRoot: string;
-
-  /**
-   * 当前 sessionId。
-   */
-  sessionId: string;
-
-  /**
-   * 当前 agent 默认工具集合。
-   */
-  tools: Record<string, Tool>;
-
-  /**
-   * 统一日志器。
-   */
-  logger: {
-    info(message: string, details?: Record<string, unknown>): void;
-    warn(message: string, details?: Record<string, unknown>): void;
-  };
-
-  /**
-   * 读取当前 SDK 调用方传入的 instruction system blocks。
-   */
-  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
-
-  /**
-   * 读取当前 agent 显式注入的受托管 plugin system blocks。
-   */
-  getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
-
-  /**
-   * 读取当前 agent 显式注册 plugin 的 system blocks。
-   */
-  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
-
-  /**
-   * 在执行前确保当前 session 已完成宿主侧默认配置。
-   *
-   * 关键点（中文）
-   * - 这里通常由 `Agent` 注入，用于补齐默认 model 等一次性装配。
-   * - 所有执行入口都应通过这里兜底，避免只在 SDK `agent.createSession()` / `agent.getSession()` 链路上做配置。
-   */
-  ensureConfigured?: (session: Session) => Promise<void>;
-};
+import { SessionStateService } from "@/session/services/SessionStateService.js";
+import { SessionTurnService } from "@/session/services/SessionTurnService.js";
+import { SessionViewService } from "@/session/services/SessionViewService.js";
+import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
+import type {
+  SessionComposerFactoryContext,
+  SessionComposerInput,
+  SessionComposerOptions,
+} from "@/types/session/SessionComposerOptions.js";
+import type { SessionCompactionComposer } from "@/executor/composer/compaction/SessionCompactionComposer.js";
+import type { SessionContextComposer } from "@/executor/composer/context/SessionContextComposer.js";
+import type { SessionHistoryComposer } from "@/executor/composer/history/SessionHistoryComposer.js";
+import type { SessionSystemComposer } from "@/executor/composer/system/SessionSystemComposer.js";
+import type { SessionOptions } from "@/types/session/SessionOptions.js";
 
 /**
  * SDK 本地 Session。
@@ -136,16 +67,15 @@ export class Session implements AgentSession {
   private readonly getManagedPluginSystemBlocks: SessionOptions["getManagedPluginSystemBlocks"];
   private readonly getPluginSystemBlocks: SessionOptions["getPluginSystemBlocks"];
   private readonly ensureConfiguredHook?: SessionOptions["ensureConfigured"];
+  private readonly composers?: SessionComposerOptions;
   private readonly historyStore: JsonlSessionHistoryStore;
-  private readonly historyComposer: JsonlSessionHistoryComposer;
+  private readonly historyComposer: SessionHistoryComposer;
   private readonly executor: Executor;
   private readonly eventHub = new SessionEventHub();
-  private readonly promptRuntime: SessionPromptRuntime;
-  private sessionConfig: AgentSessionConfigSnapshot = {};
-  private createdAt = Date.now();
-  private timezone = resolveSystemTimezone();
-  private initializePromise: Promise<this> | null = null;
-  private ensureConfiguredPromise: Promise<void> | null = null;
+  private readonly localState: SessionLocalState;
+  private readonly stateService: SessionStateService;
+  private readonly turnService: SessionTurnService;
+  private readonly viewService: SessionViewService<this>;
   private runtimePort: SessionPort | null = null;
 
   constructor(options: SessionOptions) {
@@ -158,6 +88,7 @@ export class Session implements AgentSession {
     this.getManagedPluginSystemBlocks = options.getManagedPluginSystemBlocks;
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     this.ensureConfiguredHook = options.ensureConfigured;
+    this.composers = options.composers;
     if (!this.id) {
       throw new Error("Session requires a non-empty sessionId");
     }
@@ -168,282 +99,181 @@ export class Session implements AgentSession {
       throw new Error("Session requires a non-empty projectRoot");
     }
 
-    const sessionDirPath = getSdkAgentSessionDirPath(
-      this.projectRoot,
-      this.agentId,
-      this.id,
+    this.historyStore = this.create_history_store();
+    this.localState = this.create_local_state();
+    const composer_context = this.create_composer_context();
+    this.historyComposer = this.resolve_composer(
+      this.composers?.historyComposer,
+      composer_context,
+      () =>
+        new JsonlSessionHistoryComposer({
+          store: this.historyStore,
+        }),
     );
-    const messagesDirPath = `${sessionDirPath}/messages`;
-    this.historyStore = new JsonlSessionHistoryStore({
-      rootPath: this.projectRoot,
-      agentId: this.agentId,
-      sessionId: this.id,
-      paths: {
-        sessionDirPath,
-        messagesDirPath,
-        messagesFilePath: `${messagesDirPath}/messages.jsonl`,
-        metaFilePath: `${messagesDirPath}/meta.json`,
-        archiveDirPath: getSdkAgentSessionArchiveDirPath(
-          this.projectRoot,
-          this.agentId,
-          this.id,
-        ),
-        inflightFilePath: getSdkAgentSessionInflightPath(
-          this.projectRoot,
-          this.agentId,
-          this.id,
-        ),
-      },
-    });
-    this.historyComposer = new JsonlSessionHistoryComposer({
-      store: this.historyStore,
-    });
-
+    const system_composer = this.resolve_composer(
+      this.composers?.systemComposer,
+      composer_context,
+      () =>
+        new SessionSystemBuilder({
+          agentId: this.agentId,
+          projectRoot: this.projectRoot,
+          getSessionCreatedAt: () => this.localState.createdAt,
+          getSessionTimezone: () => this.localState.timezone,
+          getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+          getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
+          getPluginSystemBlocks: this.getPluginSystemBlocks,
+        }),
+    );
+    const context_composer = this.resolve_optional_composer<
+      SessionContextComposer
+    >(this.composers?.contextComposer, composer_context);
+    const compaction_composer = this.resolve_optional_composer<
+      SessionCompactionComposer
+    >(this.composers?.compactionComposer, composer_context);
     this.executor = new Executor({
       sessionId: this.id,
       historyStore: this.historyStore,
       historyComposer: this.historyComposer,
-      getModel: () => this.sessionConfig.model,
+      getModel: () => this.localState.sessionConfig.model,
       logger: this.logger as never,
-      systemComposer: new SessionSystemBuilder({
-        agentId: this.agentId,
-        projectRoot: this.projectRoot,
-        getSessionCreatedAt: () => this.createdAt,
-        getSessionTimezone: () => this.timezone,
-        getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-        getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-        getPluginSystemBlocks: this.getPluginSystemBlocks,
-      }),
+      systemComposer: system_composer,
       getTools: () => this.tools,
+      ...(context_composer ? { contextComposer: context_composer } : {}),
+      ...(compaction_composer
+        ? { compactionComposer: compaction_composer }
+        : {}),
     });
-    this.promptRuntime = new SessionPromptRuntime({
-      sessionId: this.id,
-      publish: (event) => {
+    this.stateService = new SessionStateService({
+      agent_id: this.agentId,
+      project_root: this.projectRoot,
+      session_id: this.id,
+      history_store: this.historyStore,
+      executor: this.executor,
+      state: this.localState,
+      ensure_configured_hook: this.ensureConfiguredHook
+        ? async () => {
+            await this.ensureConfiguredHook?.(this);
+          }
+        : undefined,
+      publish_event: (event) => {
         this.eventHub.publish(event);
       },
-      createAndPersistUserMessage: async (input) => {
-        return await this.createAndPersistUserPromptMessage(input);
-      },
-      executeTurn: async ({ turnId, promptInput, onStepMerge }) => {
-        return await this.executePromptTurn({
-          turnId,
-          promptInput,
-          onStepMerge,
-        });
+    });
+    this.turnService = new SessionTurnService({
+      session_id: this.id,
+      executor: this.executor,
+      state_service: this.stateService,
+      event_hub: this.eventHub,
+    });
+    this.viewService = new SessionViewService<this>({
+      agent_id: this.agentId,
+      project_root: this.projectRoot,
+      session_id: this.id,
+      history_store: this.historyStore,
+      state_service: this.stateService,
+      is_executing: () => this.isExecuting(),
+      get_instruction_system_blocks: this.getInstructionSystemBlocks,
+      get_managed_plugin_system_blocks: this.getManagedPluginSystemBlocks,
+      get_plugin_system_blocks: this.getPluginSystemBlocks,
+      ...(this.composers?.systemComposer
+        ? { custom_system_composer: system_composer }
+        : {}),
+      create_fork_session: async (session_id) => {
+        const session = this.create_fork_session(session_id);
+        await session.initialize();
+        return {
+          session,
+          history_store: session.historyStore,
+          state_service: session.stateService,
+        };
       },
     });
   }
 
   /**
-   * 初始化当前 session 的 meta 信息与内存配置。
+   * 初始化当前 session。
    */
   async initialize(): Promise<this> {
-    if (this.initializePromise) {
-      return await this.initializePromise;
-    }
-    this.initializePromise = (async () => {
-      const metadata = await readSessionMetadata({
-        projectRoot: this.projectRoot,
-        agentId: this.agentId,
-        sessionId: this.id,
-      });
-      const createdAt =
-        typeof metadata.createdAt === "number" ? metadata.createdAt : Date.now();
-      const timezone =
-        typeof metadata.timezone === "string" && metadata.timezone.trim()
-          ? metadata.timezone.trim()
-          : resolveSystemTimezone();
-      await writeSessionMetadata({
-        projectRoot: this.projectRoot,
-        agentId: this.agentId,
-        sessionId: this.id,
-        meta: {
-          ...metadata,
-          agentId: this.agentId,
-          createdAt,
-          timezone,
-        },
-      });
-      this.createdAt = createdAt;
-      this.timezone = timezone;
-      this.sessionConfig = {
-        ...(metadata.modelLabel
-          ? { modelLabel: metadata.modelLabel }
-          : {}),
-      };
-      return this;
-    })();
-    return await this.initializePromise;
+    await this.stateService.initialize();
+    return this;
   }
 
   /**
    * 读取当前 session 配置快照。
    */
   get config(): AgentSessionConfigSnapshot {
-    return {
-      ...this.sessionConfig,
-    };
+    return this.stateService.get_config();
   }
 
   /**
    * 写入当前 session 默认配置。
    */
   async set(input: AgentSessionSetInput): Promise<void> {
-    if (input.model) {
-      this.sessionConfig.model = normalizeAgentModel(input.model);
-      this.sessionConfig.modelLabel = inferAgentModelLabel(input.model);
-      this.executor.clearExecutor();
-    }
-    await patchSessionModelLabel({
-      projectRoot: this.projectRoot,
-      agentId: this.agentId,
-      sessionId: this.id,
-      model: this.sessionConfig.model,
-    });
+    await this.stateService.set(input);
   }
 
   /**
    * 追加一条新的 Session prompt。
-   *
-   * 关键点（中文）
-   * - 这是 Session actor 模型下唯一的输入入口。
-   * - 首条输入、运行中补充输入、排到下一轮的输入，调用方式完全一致。
    */
   async prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
-    const query = String(input.query || "").trim();
-    if (!query) {
-      throw new Error("session.prompt requires a non-empty query");
-    }
-    await this.ensureRunnable();
-    return await this.promptRuntime.prompt({
-      query,
-    });
+    return await this.turnService.prompt(input);
   }
 
   /**
    * 订阅当前 Session 的未来事件。
-   *
-   * 关键点（中文）
-   * - 只广播订阅之后产生的事件。
-   * - 不做历史回放；历史仍通过 `history()` 读取。
    */
   subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
-    return this.eventHub.subscribe(subscriber);
+    return this.turnService.subscribe(subscriber);
   }
 
   /**
    * 追加一条 user 文本消息。
    */
   async appendUserMessage(input: {
-    /**
-     * 需要写入的用户文本。
-     */
     text: string;
   }): Promise<void> {
-    await this.executor.appendUserMessage({
+    await this.stateService.append_user_message({
       text: String(input.text || "").trim(),
     });
-    await this.ensureTitleFromHistory({ generate: true });
-    await this.touchMetadata();
   }
 
   /**
    * 追加一条 assistant 文本消息。
    */
   async appendAssistantMessage(input: {
-    /**
-     * 需要写入的 assistant 文本。
-     */
     text: string;
   }): Promise<void> {
-    await this.executor.appendAssistantMessage({
+    await this.stateService.append_assistant_message({
       fallbackText: String(input.text || "").trim(),
     });
-    await this.touchMetadata();
   }
 
   /**
    * 读取当前 session 详情。
    */
   async getInfo(): Promise<AgentSessionInfo> {
-    const [metadata, messages] = await Promise.all([
-      readSessionMetadata({
-        projectRoot: this.projectRoot,
-        agentId: this.agentId,
-        sessionId: this.id,
-      }),
-      this.historyStore.list(),
-    ]);
-    const metadataWithTitle = metadata.title
-      ? metadata
-      : await ensureSessionTitle({
-          projectRoot: this.projectRoot,
-          agentId: this.agentId,
-          sessionId: this.id,
-          messages,
-        });
-    return buildSessionInfo({
-      projectRoot: this.projectRoot,
-      agentId: this.agentId,
-      sessionId: this.id,
-      metadata: metadataWithTitle,
-      messages,
-      executing: this.isExecuting(),
-    });
+    return await this.viewService.get_info();
   }
 
   /**
    * 读取当前 session 历史分页。
    */
   async history(input?: AgentSessionHistoryInput): Promise<AgentSessionHistoryPage> {
-    const [session, messages] = await Promise.all([
-      this.getInfo(),
-      this.historyStore.list(),
-    ]);
-    return buildSessionHistoryPage({
-      session,
-      messages,
-      input,
-    });
+    return await this.viewService.history(input);
   }
 
   /**
-   * 读取当前 session 生效的 system prompt 文本集合。
-   *
-   * 关键点（中文）
-   * - 返回内容与实际 run 时使用的 SDK system composer 同源。
-   * - 包含 instruction/core、受托管 plugin system、显式注册 plugin system 与 session 上下文。
-   * - 返回结构化快照，不把 system prompt 写入会话历史。
+   * 读取当前 session 生效的 system 快照。
    */
   async system(): Promise<AgentSessionSystemSnapshot> {
-    const blocks = await buildSessionSystemBlocks({
-      agentId: this.agentId,
-      projectRoot: this.projectRoot,
-      sessionId: this.id,
-      createdAt: this.createdAt,
-      timezone: this.timezone,
-      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-      getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-      getPluginSystemBlocks: this.getPluginSystemBlocks,
-    });
-    return {
-      sessionId: this.id,
-      session: {
-        agentId: this.agentId,
-        sessionId: this.id,
-        projectRoot: this.projectRoot,
-        createdAt: new Date(this.createdAt).toISOString(),
-        timezone: this.timezone,
-      },
-      blocks,
-    };
+    return await this.viewService.system();
   }
 
   /**
    * 返回当前 session 是否正在执行。
    */
   isExecuting(): boolean {
-    return this.promptRuntime.isActive() || this.executor.isExecuting();
+    return this.turnService.is_prompt_runtime_active() || this.executor.isExecuting();
   }
 
   /**
@@ -456,49 +286,8 @@ export class Session implements AgentSession {
   /**
    * 从当前 session 创建一个分叉会话。
    */
-  async fork(input?: AgentSessionForkInput | string): Promise<Session> {
-    const messageId =
-      typeof input === "string"
-        ? String(input || "").trim() || undefined
-        : String(input?.messageId || "").trim() || undefined;
-    const messages = await this.historyStore.list();
-    const forkMessages =
-      !messageId
-        ? messages
-        : (() => {
-            const targetIndex = messages.findIndex(
-              (message) => String(message.id || "").trim() === messageId,
-            );
-            if (targetIndex < 0) {
-              throw new Error(
-                `Cannot fork session "${this.id}": messageId "${messageId}" not found.`,
-              );
-            }
-            return messages.slice(0, targetIndex + 1);
-          })();
-
-    const forked = new Session({
-      agentId: this.agentId,
-      projectRoot: this.projectRoot,
-      sessionId: `fork-${Date.now()}-${nanoid(8)}`,
-      tools: this.tools,
-      logger: this.logger,
-      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-      getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-      getPluginSystemBlocks: this.getPluginSystemBlocks,
-    });
-    await forked.initialize();
-    if (this.sessionConfig.model) {
-      await forked.set({
-        model: this.sessionConfig.model,
-      });
-    }
-    for (const message of forkMessages) {
-      await forked.historyStore.append(message);
-    }
-    await forked.ensureTitleFromHistory({ generate: true });
-    await forked.touchMetadata();
-    return forked;
+  async fork(input?: AgentSessionForkInput | string): Promise<this> {
+    return await this.viewService.fork(input);
   }
 
   /**
@@ -509,25 +298,19 @@ export class Session implements AgentSession {
     this.runtimePort = createRuntimeSessionPort({
       sessionId: this.id,
       getExecutor: () => this.executor.getExecutor(),
-      prompt: async (input) => {
-        return await this.prompt(input);
-      },
-      subscribe: (subscriber) => {
-        return this.subscribe(subscriber);
-      },
+      prompt: async (input) => await this.prompt(input),
+      subscribe: (subscriber) => this.subscribe(subscriber),
       clearExecutor: () => {
         this.executor.clearExecutor();
       },
       afterSessionUpdatedAsync: async () => {
         await this.executor.afterSessionUpdatedAsync();
       },
-      appendUserMessage: async (messageParams) => {
-        await this.executor.appendUserMessage(messageParams);
-        await this.ensureTitleFromHistory({ generate: true });
-        await this.touchMetadata();
+      appendUserMessage: async (message_params) => {
+        await this.stateService.append_user_message(message_params);
       },
-      appendAssistantMessage: async (messageParams) => {
-        await this.executor.appendAssistantMessage(messageParams);
+      appendAssistantMessage: async (message_params) => {
+        await this.stateService.append_assistant_message(message_params);
       },
       isExecuting: () => this.isExecuting(),
       historyStore: this.historyStore,
@@ -535,7 +318,7 @@ export class Session implements AgentSession {
         await this.ensureReadyForExecution();
       },
       touchMetadata: async () => {
-        await this.touchMetadata();
+        await this.stateService.touch_metadata();
       },
     });
     return this.runtimePort;
@@ -545,180 +328,113 @@ export class Session implements AgentSession {
    * 在执行前确保 session 已完成初始化与宿主装配。
    */
   async ensureReadyForExecution(): Promise<void> {
-    await this.initialize();
-    if (this.ensureConfiguredPromise) {
-      await this.ensureConfiguredPromise;
-      return;
-    }
-    this.ensureConfiguredPromise = (async () => {
-      if (!this.ensureConfiguredHook) return;
-      await this.ensureConfiguredHook(this);
-    })();
-    try {
-      await this.ensureConfiguredPromise;
-    } catch (error) {
-      this.ensureConfiguredPromise = null;
-      throw error;
-    }
+    await this.stateService.ensure_ready_for_execution();
   }
 
-  private async ensureRunnable(): Promise<void> {
-    await this.ensureReadyForExecution();
-    if (!this.sessionConfig.model) {
-      throw new Error(
-        `Session "${this.id}" requires a configured model. Pass model to new Agent({ model }) or call session.set({ model }) first.`,
-      );
-    }
-  }
-
-  private async touchMetadata(): Promise<void> {
-    await touchSessionMetadata({
-      projectRoot: this.projectRoot,
+  private create_fork_session(session_id: string): this {
+    return this.create_child_session({
       agentId: this.agentId,
-      sessionId: this.id,
-      sessionConfig: this.sessionConfig,
+      projectRoot: this.projectRoot,
+      sessionId: session_id,
+      tools: this.tools,
+      logger: this.logger,
+      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
+      getPluginSystemBlocks: this.getPluginSystemBlocks,
+      ensureConfigured: this.ensureConfiguredHook,
+      composers: this.composers,
     });
   }
 
-  private async ensureTitleFromHistory(input?: {
-    /**
-     * 是否允许调用模型生成标题。
-     */
-    generate?: boolean;
-  }): Promise<void> {
-    const messages = await this.historyStore.list();
-    const beforeMetadata = await readSessionMetadata({
-      projectRoot: this.projectRoot,
-      agentId: this.agentId,
-      sessionId: this.id,
-    });
-    const beforeTitle = String(beforeMetadata.title || "").trim();
-    const nextMetadata = await ensureSessionTitle({
-      projectRoot: this.projectRoot,
-      agentId: this.agentId,
-      sessionId: this.id,
-      messages,
-      ...(input?.generate ? { model: this.sessionConfig.model } : {}),
-      generate: input?.generate === true,
-    });
-    const nextTitle = String(nextMetadata.title || "").trim();
-    if (!nextTitle || nextTitle === beforeTitle) return;
-    this.eventHub.publish({
-      type: "session-title",
-      sessionId: this.id,
-      title: nextTitle,
-    });
+  /**
+   * 创建当前 Session 的同类子会话。
+   *
+   * 关键点（中文）
+   * - 默认沿用当前实例的 class，避免自定义 Session 在 fork 后退回默认实现。
+   * - 子类仍可覆盖该方法，接管更特殊的子会话创建逻辑。
+   */
+  protected create_child_session(options: SessionOptions): this {
+    const SessionClass = this.constructor as new (
+      options: SessionOptions,
+    ) => Session;
+    return new SessionClass(options) as this;
   }
 
-  private async persistAssistantResult(
-    assistantMessage: SessionMessageV1,
-  ): Promise<void> {
-    await persistSdkAssistantResult({
-      projectRoot: this.projectRoot,
+  private create_history_store(): JsonlSessionHistoryStore {
+    const session_dir_path = getSdkAgentSessionDirPath(
+      this.projectRoot,
+      this.agentId,
+      this.id,
+    );
+    const messages_dir_path = `${session_dir_path}/messages`;
+    return new JsonlSessionHistoryStore({
+      rootPath: this.projectRoot,
       agentId: this.agentId,
       sessionId: this.id,
-      sessionConfig: this.sessionConfig,
-      executor: this.executor,
-      assistantMessage,
+      paths: {
+        sessionDirPath: session_dir_path,
+        messagesDirPath: messages_dir_path,
+        messagesFilePath: `${messages_dir_path}/messages.jsonl`,
+        metaFilePath: `${messages_dir_path}/meta.json`,
+        archiveDirPath: getSdkAgentSessionArchiveDirPath(
+          this.projectRoot,
+          this.agentId,
+          this.id,
+        ),
+        inflightFilePath: getSdkAgentSessionInflightPath(
+          this.projectRoot,
+          this.agentId,
+          this.id,
+        ),
+      },
     });
   }
 
-  private async createAndPersistUserPromptMessage(
-    input: AgentSessionPromptInput,
-  ): Promise<SessionUserMessageV1> {
-    const message = this.historyStore.userText({
-      text: String(input.query || "").trim(),
-      metadata: {
-        sessionId: this.id,
-      },
-    }) as SessionUserMessageV1;
-    await this.executor.appendUserMessage({
-      message,
-    });
-    await this.ensureTitleFromHistory({ generate: true });
-    await this.touchMetadata();
-    return message;
+  private create_local_state(): SessionLocalState {
+    return {
+      sessionConfig: {},
+      createdAt: Date.now(),
+      timezone: resolveSystemTimezone(),
+      initializePromise: null,
+      ensureConfiguredPromise: null,
+    };
   }
 
-  private async executePromptTurn(input: {
-    turnId: string;
-    promptInput: AgentSessionPromptInput;
-    onStepMerge: () => Promise<SessionUserMessageV1[]>;
-  }): Promise<{
-    text: string;
-    success: boolean;
-    assistantMessage: SessionMessageV1;
-    error?: string;
-  }> {
-    const toolNameByCallId = new Map<string, string>();
-    const result = await this.executor.run({
-      query: input.promptInput.query,
-      onStepCallback: input.onStepMerge,
-      onAssistantStepCallback: async (step) => {
-        this.eventHub.publish({
-          type: "assistant-step",
-          turnId: input.turnId,
-          text: step.text,
-          stepIndex: step.stepIndex,
-          ...(step.visibility ? { visibility: step.visibility } : {}),
-        });
-      },
-      onUiMessageChunkCallback: async (chunk) => {
-        if (chunk.type === "tool-input-start") {
-          toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
-          return;
-        }
-        const event = mapUiMessageChunkToAgentEvent(chunk);
-        if (!event) return;
-        const resolvedEvent =
-          (
-            event.type === "tool-result" ||
-            event.type === "tool-error"
-          ) &&
-          event.toolName === "unknown"
-            ? {
-                ...event,
-                toolName:
-                  toolNameByCallId.get(event.toolCallId) || event.toolName,
-              }
-            : event;
-        if (
-          resolvedEvent.type === "tool-call" ||
-          resolvedEvent.type === "tool-error"
-        ) {
-          toolNameByCallId.set(
-            resolvedEvent.toolCallId,
-            resolvedEvent.toolName,
-          );
-        }
-        const sessionEvent = mapAgentEventToSessionEvent({
-          event: resolvedEvent,
-          turnId: input.turnId,
-        });
-        if (sessionEvent) {
-          this.eventHub.publish(sessionEvent);
-        }
-      },
-    });
-    await this.persistAssistantResult(result.assistantMessage);
-    await this.persistDeferredUserMessages();
+  private create_composer_context(): SessionComposerFactoryContext {
     return {
-      text: extractTextFromUiMessage(result.assistantMessage),
-      success: result.success,
-      assistantMessage: result.assistantMessage,
-      ...(result.error ? { error: result.error } : {}),
+      agentId: this.agentId,
+      projectRoot: this.projectRoot,
+      sessionId: this.id,
+      historyStore: this.historyStore,
+      getTools: () => this.tools,
+      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
+      getPluginSystemBlocks: this.getPluginSystemBlocks,
+      getSessionCreatedAt: () => this.localState.createdAt,
+      getSessionTimezone: () => this.localState.timezone,
     };
   }
 
-  private async persistDeferredUserMessages(): Promise<void> {
-    const deferredMessages = drainDeferredPersistedUserMessages(this.id);
-    for (const message of deferredMessages) {
-      await this.executor.appendUserMessage({
-        message,
-      });
-    }
-    if (deferredMessages.length > 0) {
-      await this.touchMetadata();
+  private resolve_composer<TComposer>(
+    input: SessionComposerInput<TComposer> | undefined,
+    context: SessionComposerFactoryContext,
+    create_default: () => TComposer,
+  ): TComposer {
+    const composer = this.resolve_optional_composer(input, context);
+    return composer || create_default();
+  }
+
+  private resolve_optional_composer<TComposer>(
+    input: SessionComposerInput<TComposer> | undefined,
+    context: SessionComposerFactoryContext,
+  ): TComposer | undefined {
+    if (!input) return undefined;
+    if (typeof input === "function") {
+      const create_composer = input as (
+        context: SessionComposerFactoryContext,
+      ) => TComposer;
+      return create_composer(context);
     }
+    return input;
   }
 }