@downcity/agent 1.1.408 → 1.1.437

package/src/session/Session.ts

@@ -4,18 +4,16 @@
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
  * - 对外保留稳定 Session facade，把状态、turn、view 逻辑下沉到独立 service。
- * - 内部使用 `SessionMessages` 统一管理 Active、Segment 与流式 Assistant 草稿。
+ * - 内部使用 `SessionMessages` 管理 SQLite 中的 canonical Message 聚合。
  */
 
 import { Executor } from "@executor/Executor.js";
-import type { ModelClient } from "@downcity/type";
-import type { RuntimeTool as Tool } from "@downcity/type";
 import {
-  infer_agent_model_label,
-  normalize_agent_model,
-  read_agent_model_context_window,
-  type AgentModel,
-} from "@/agent/AgentModel.js";
+  type ModelClient,
+  read_model_context_window,
+  read_model_label,
+  type RuntimeTool as Tool,
+} from "@downcity/type";
 import { SessionMessages } from "@/session/SessionMessages.js";
 import type {
   AgentSessionConfigSnapshot,
@@ -24,56 +22,52 @@ import type {
   AgentSessionStatus,
   AgentSessionSetInput,
   AgentSessionSetOptions,
-  AgentSessionSystemBlock,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/SessionTypes.js";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
-import { resolve_system_timezone } from "@/session/storage/Metadata.js";
 import { create_runtime_session_port } from "@/session/storage/RuntimeSessionPort.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
-import type { SessionMutationSubscriber, SessionMutationUnsubscribe } from "@/types/session/SessionMutation.js";
+import type { SessionMutationSubscriber, SessionMutationUnsubscribe } from "@downcity/type";
 import type {
   RespondSessionInteractionInput,
   SessionApprovalMode,
   SessionInteractionResult,
   SessionPendingInteraction,
-} from "@/types/session/SessionInteraction.js";
-import type { ListSessionMessagesInput, SessionMessagePage } from "@/types/session/SessionMessage.js";
+} from "@downcity/type";
+import type { ListSessionMessagesInput, SessionMessagePage } from "@downcity/type";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
-import type { AgentSessionCompactHandle } from "@/types/sdk/AgentSessionCompact.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
-import { create_session_compact_operation } from "@/session/runtime/SessionCompactOperation.js";
-import { run_session_history_compaction } from "@/session/runtime/SessionHistoryCompaction.js";
-import { create_session_plugin_execution_context } from "@/session/runtime/SessionTurnContext.js";
-import { SessionState } from "@/session/SessionState.js";
+import {
+  create_session_local_state,
+  SessionState,
+} from "@/session/SessionState.js";
 import { SessionLoop } from "@/session/SessionLoop.js";
 import { SessionQueue } from "@/session/SessionQueue.js";
-import { SessionCommand } from "@/session/SessionCommand.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
 import type { SessionOptions } from "@/types/session/SessionOptions.js";
-import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
+import type { SessionHookRuntime } from "@downcity/type";
 import { SessionInteractions } from "@/session/control/SessionInteractions.js";
 import { SessionShellApprovalAdapter } from "@/session/execution/tools/SessionShellApprovalAdapter.js";
 import { DefaultSessionComposer } from "@/session/DefaultSessionComposer.js";
-import type {
-  SessionComposer,
-  SessionComposeIdentity,
-  SessionCompactionPlan,
-  SessionComposeInput,
-  SessionStepInput,
-} from "@/types/session/SessionComposer.js";
-import type { SessionCompactHistory } from "@/types/session/SessionExecution.js";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
+import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import { generate_id } from "@/utils/Id.js";
 import { nanoid } from "nanoid";
 import { build_session_info } from "@/session/browse/Browse.js";
-import { ensure_session_title } from "@/session/SessionTitle.js";
-import type { SessionMessage } from "@/types/session/SessionMessage.js";
-import type { SessionActionEventInput } from "@/types/session/SessionAction.js";
-import type { SessionCommandOptions } from "@/types/session/SessionCommand.js";
-import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
+import type { SessionActionEventInput } from "@downcity/type";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
+import type {
+  AppendExternalSessionAgentMessageInput,
+  AppendExternalSessionUserMessageInput,
+} from "@/types/session/SessionMessages.js";
+import { SessionComposition } from "@/session/SessionComposition.js";
+import {
+  relocate_fork_message_files,
+  resolve_session_fork_messages,
+} from "@/session/messages/SessionForkMessageFiles.js";
+import { create_session_model_request_warning } from "@/session/runtime/SessionModelRequestWarning.js";
+import type { SessionContextRecoveryReason } from "@/types/session/SessionContextPolicy.js";
 
 /**
  * SDK 本地 Session。
@@ -84,16 +78,18 @@ export class Session implements AgentSession {
   /** 当前 Session 创建时绑定的 Workspace ID。 */
   readonly workspace_id?: string;
   /** 当前 Session 的创建来源。 */
-  readonly origin?: SessionOptions["origin"];
+  readonly origin: SessionOptions["origin"];
 
   private readonly workspace_path: string;
-  private readonly store: SessionDataStore;
-  private readonly get_session_store: SessionOptions["get_session_store"];
-  private readonly tools: Record<string, Tool>;
+  private readonly store: SessionStorage;
+  private readonly create_session_store: SessionOptions["create_session_store"];
+  private readonly register_forked_session: SessionOptions["register_forked_session"];
+  private readonly get_tools: SessionOptions["get_tools"];
   private readonly logger: SessionOptions["logger"];
   private readonly get_managed_plugin_system_blocks: SessionOptions["get_managed_plugin_system_blocks"];
   private readonly ensure_configured_hook?: SessionOptions["ensure_configured"];
   private readonly composer: SessionComposer;
+  private readonly create_composer: () => SessionComposer;
   private readonly session_messages: SessionMessages;
   private readonly executor: Executor;
   private readonly events: SessionEventHub;
@@ -102,19 +98,13 @@ export class Session implements AgentSession {
   private readonly local_state: SessionLocalState;
   private readonly get_workspace_env: SessionOptions["get_workspace_env"];
   private readonly get_agent_model: SessionOptions["get_agent_model"];
-  private readonly get_agent_plugins: SessionOptions["get_agent_plugins"];
+  private readonly get_hooks: SessionOptions["get_hooks"];
   private readonly get_instruction_system_blocks:
     SessionOptions["get_instruction_system_blocks"];
-  private effective_instruction_system_blocks: AgentSessionSystemBlock[];
   /** 当前 Session 的一次性初始化任务，避免缓存实例被重复恢复运行时状态。 */
   private initialize_promise: Promise<void> | null = null;
-  private instruction_initialize_promise: Promise<void> | null = null;
-  private effective_workspace_env: Record<string, string>;
-  private effective_agent_plugins: AgentPluginExecutionRuntime;
-  /** 当前 Session 首次生成后固定的完整 system snapshot。 */
-  private system_snapshot_blocks: AgentSessionSystemBlock[] | null = null;
-  /** 串行化 snapshot / syncshot 对 system 与 instruction.md 的修改。 */
-  private system_mutation_chain: Promise<void> = Promise.resolve();
+  /** 当前 Session 的 system snapshot 与 Step 组装边界。 */
+  private readonly session_composition: SessionComposition;
   private readonly state: SessionState;
   /** 当前 Session 独享的 Command FIFO。 */
   private readonly session_queue = new SessionQueue();
@@ -128,21 +118,19 @@ export class Session implements AgentSession {
     this.origin = options.origin;
     this.workspace_path = String(options.workspace_path || "").trim();
     this.store = options.store;
-    this.get_session_store = options.get_session_store;
-    this.tools = options.tools;
+    this.create_session_store = options.create_session_store;
+    this.register_forked_session = options.register_forked_session;
+    this.get_tools = options.get_tools;
     this.logger = options.logger;
     this.get_workspace_env = options.get_workspace_env;
     this.get_agent_model = options.get_agent_model;
-    this.get_agent_plugins = options.get_agent_plugins;
+    this.get_hooks = options.get_hooks;
     this.get_instruction_system_blocks = options.get_instruction_system_blocks;
-    this.effective_instruction_system_blocks = options
-      .instruction_system_blocks
-      .map((block) => ({ ...block }));
-    this.effective_workspace_env = { ...options.get_workspace_env() };
-    this.effective_agent_plugins = options.get_agent_plugins();
     this.get_managed_plugin_system_blocks = options.get_managed_plugin_system_blocks;
     this.ensure_configured_hook = options.ensure_configured;
-    this.composer = options.composer || new DefaultSessionComposer();
+    this.create_composer = options.create_composer ||
+      (() => new DefaultSessionComposer());
+    this.composer = this.create_composer();
     if (!this.id) {
       throw new Error("Session requires a non-empty session_id");
     }
@@ -156,7 +144,7 @@ export class Session implements AgentSession {
     this.events = new SessionEventHub();
     this.session_messages = new SessionMessages({
       session_id: this.id,
-      store: this.store.messages,
+      store: this.store,
       attachment_store: this.store.attachments,
       publish: (mutation) => {
         this.events.publish(mutation);
@@ -170,14 +158,32 @@ export class Session implements AgentSession {
       session_id: this.id,
       interactions: this.session_interactions,
     });
-    this.local_state = this.create_local_state();
+    this.local_state = create_session_local_state();
+    this.session_composition = new SessionComposition({
+      agent_id: this.agent_id,
+      session_id: this.id,
+      session_origin: this.origin,
+      workspace_path: this.workspace_path,
+      store: this.store,
+      composer: this.composer,
+      get_tools: this.get_tools,
+      instruction_system_blocks: options.instruction_system_blocks,
+      get_instruction_system_blocks: this.get_instruction_system_blocks,
+      get_hooks: this.get_hooks,
+      get_workspace_env: this.get_workspace_env,
+      get_managed_plugin_system_blocks: this.get_managed_plugin_system_blocks,
+      get_model: () => this.get_model(),
+      get_model_context_window: () => this.get_model_context_window(),
+      get_created_at: () => this.local_state.created_at,
+      get_timezone: () => this.local_state.timezone,
+      logger: this.logger,
+    });
     this.executor = this.create_executor();
     this.state = new SessionState({
       agent_id: this.agent_id,
       session_id: this.id,
       origin: this.origin,
       store: this.store,
-      messages: this.session_messages,
       state: this.local_state,
       logger: this.logger,
       ensure_configured_hook: this.ensure_configured_hook
@@ -192,9 +198,12 @@ export class Session implements AgentSession {
     });
     this.session_loop = new SessionLoop({
       session_id: this.id,
+      session_origin: this.origin,
       workspace_path: this.workspace_path,
       executor: this.executor,
-      compact_history: async (input) => await this.compact_history(input),
+      maintain_context: async () => {
+        await this.recover_context("usage_pressure");
+      },
       state: this.state,
       events: this.events,
       logger: this.logger,
@@ -212,7 +221,7 @@ export class Session implements AgentSession {
     if (!this.initialize_promise) {
       this.initialize_promise = (async () => {
         await Promise.all([
-          this.initialize_instruction(),
+          this.session_composition.initialize(),
           this.session_messages.initialize(),
           this.state.initialize(),
         ]);
@@ -221,7 +230,15 @@ export class Session implements AgentSession {
         );
       })();
     }
-    await this.initialize_promise;
+    const initialize_promise = this.initialize_promise;
+    try {
+      await initialize_promise;
+    } catch (error) {
+      if (this.initialize_promise === initialize_promise) {
+        this.initialize_promise = null;
+      }
+      throw error;
+    }
     return this;
   }
 
@@ -229,40 +246,23 @@ export class Session implements AgentSession {
    * 把当前 Session 首次生成后固定的完整 system 显式固化到 instruction.md。
    *
    * 关键点（中文）
-   * - 包含 instruction、SDK core、plugin system 与 Session context。
+   * - 包含 instruction、SDK core、Plugin system 与 Session context。
    * - 多个 system block 按原顺序合并为一个 Markdown 文档。
    */
   async snapshot(): Promise<void> {
-    await this.run_system_mutation(async () => {
-      const system_snapshot = await this.system();
-      await this.write_system_snapshot(system_snapshot.blocks);
-    });
+    await this.session_composition.snapshot();
   }
 
   /**
-   * 使用 Agent 当前 instruction 与 plugin 重新生成一次完整 system。
+   * 使用 Agent 当前 instruction 与 Plugin 重新生成一次完整 system。
    *
    * 关键点（中文）
-   * - 只替换内存 snapshot，不改变 plugin execution view。
+   * - 只替换内存 snapshot，不改变 Plugin execution view。
    * - instruction.md 已存在时同步覆盖；不存在时不自动创建。
    * - 当前已经发出的 provider 请求不受影响，后续 step 使用新 snapshot。
    */
   async syncshot(): Promise<void> {
-    await this.run_system_mutation(async () => {
-      await this.initialize_instruction();
-      const should_persist = await this.store.has_instruction();
-      const composed = await this.composer.compose(
-        await this.create_compose_input(undefined, 0, true),
-      );
-      const next_blocks = resolve_composed_system_blocks(composed);
-
-      if (should_persist) {
-        await this.write_system_snapshot(next_blocks);
-      }
-      this.effective_instruction_system_blocks =
-        this.get_instruction_system_blocks().map((block) => ({ ...block }));
-      this.system_snapshot_blocks = next_blocks;
-    });
+    await this.session_composition.syncshot();
   }
 
   /**
@@ -340,7 +340,8 @@ export class Session implements AgentSession {
           publish_mutation,
         }
       : undefined;
-    this.enqueue_command({
+    this.session_loop.enqueue_command({
+      kind: "maintenance",
       execute: async () => {
         if (model_result) this.state.apply_model_config(model_result.config);
         if (security_changed && next_approval_mode) {
@@ -360,7 +361,7 @@ export class Session implements AgentSession {
    * 追加一条新的 Session prompt。
    */
   async prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
-    await this.initialize_instruction();
+    await this.session_composition.initialize();
     return await this.session_loop.prompt(input);
   }
 
@@ -371,97 +372,6 @@ export class Session implements AgentSession {
     return await this.session_loop.stop();
   }
 
-  /**
-   * 把一次显式历史压缩加入当前 Session 的有序输入队列。
-   */
-  async compact(): Promise<AgentSessionCompactHandle> {
-    await this.state.ensure_runnable();
-    const compact_id = `compact:${this.id}:${generate_id()}`;
-    const operation = create_session_compact_operation({
-      compact_id,
-      run: async () => await this.session_loop.compact_history(compact_id),
-      log_error: async (error_message) => {
-        await this.logger.log("warn", "[agent] session compact command failed", {
-          session_id: this.id,
-          compact_id,
-          error: error_message,
-        });
-      },
-      publish_finish: (final_result) => {
-        this.events.publish({
-          mutation_id: nanoid(),
-          variant: "compact",
-          type: "finish",
-          session_id: this.id,
-          compact_id,
-          status: final_result.success ? "completed" : "failed",
-          compacted: final_result.compacted,
-          reason: final_result.reason,
-          created_at: Date.now(),
-          ...(final_result.error ? { error: final_result.error } : {}),
-        });
-      },
-    });
-    this.enqueue_command({
-      execute: operation.execute,
-    });
-    this.events.publish({
-      mutation_id: nanoid(),
-      variant: "compact",
-      type: "start",
-      session_id: this.id,
-      compact_id,
-      status: "queued",
-      created_at: Date.now(),
-    });
-    return operation.handle;
-  }
-
-  /** 把 Workspace env 快照加入当前 Session 的有序输入队列。 */
-  enqueue_workspace_env(input: {
-    /** 当前 Workspace env 修改的稳定标识。 */
-    command_id: string;
-    /** 下一 Session Step 使用的完整环境变量快照。 */
-    env: Record<string, string>;
-  }): void {
-    this.enqueue_command({
-      execute: async () => {
-        this.effective_workspace_env = { ...input.env };
-      },
-      completion: {
-        type: "action",
-        id: `agent-env:${this.id}:${input.command_id}`,
-        title: "Workspace environment updated",
-      },
-    });
-  }
-
-  /** 把 Agent Plugin 执行视图加入当前 Session 的有序输入队列。 */
-  enqueue_agent_plugins(input: {
-    /** 当前 Plugin 修改的稳定标识。 */
-    command_id: string;
-    /** 当前 Plugin 修改的用户可读标题。 */
-    title: string;
-    /** 下一 Session Step 使用的 Plugin 执行视图。 */
-    plugins: AgentPluginExecutionRuntime;
-  }): void {
-    this.enqueue_command({
-      execute: async () => {
-        this.effective_agent_plugins = input.plugins;
-      },
-      completion: {
-        type: "action",
-        id: `agent-plugins:${this.id}:${input.command_id}`,
-        title: input.title,
-      },
-    });
-  }
-
-  /** 创建一个具体 Session Command 对象并加入当前 FIFO。 */
-  private enqueue_command(options: SessionCommandOptions): void {
-    this.session_queue.enqueue_command(new SessionCommand(options));
-  }
-
   /**
    * 订阅当前 Session 的未来事件。
    */
@@ -501,45 +411,30 @@ export class Session implements AgentSession {
   async append_user_message(input: {
     text: string;
   }): Promise<void> {
-    const appended = await this.session_messages.append_external_user_message({
+    await this.append_external_user_message({
       text: String(input.text || "").trim(),
     });
-    if (!appended) return;
-    this.state.touch_metadata_in_background();
-    this.state.schedule_title_generation();
   }
 
   /**
-   * 追加一条 assistant 文本消息。
+   * 追加一条 Agent 文本消息。
    */
-  async append_assistant_message(input: {
+  async append_agent_message(input: {
     text: string;
   }): Promise<void> {
-    const appended = await this.session_messages.append_external_assistant_message({
+    await this.append_external_agent_message({
       text: String(input.text || "").trim(),
     });
-    if (appended) await this.state.touch_metadata();
   }
 
   /**
    * 读取当前 session 详情。
    */
   async get_info(): Promise<AgentSessionInfo> {
-    const [metadata, snapshot] = await Promise.all([
-      this.store.read_metadata(),
-      this.session_messages.context_snapshot(),
-    ]);
-    const metadata_with_title = metadata.title
-      ? metadata
-      : await ensure_session_title({
-          session_id: this.id,
-          store: this.store,
-          messages: snapshot.messages,
-          logger: this.logger,
-        });
+    const metadata = await this.store.read_metadata();
     const model_label = String(
-      metadata_with_title.model_label ||
-      infer_agent_model_label(this.get_selected_model()) ||
+      metadata.model_label ||
+      read_model_label(this.get_selected_model()) ||
       "",
     ).trim();
     return build_session_info({
@@ -547,10 +442,9 @@ export class Session implements AgentSession {
       agent_id: this.agent_id,
       session_id: this.id,
       metadata: {
-        ...metadata_with_title,
+        ...metadata,
         ...(model_label ? { model_label } : {}),
       },
-      messages: snapshot.messages,
       executing: this.is_executing(),
     });
   }
@@ -566,20 +460,7 @@ export class Session implements AgentSession {
    * 读取当前 session 生效的 system 快照。
    */
   async system(): Promise<AgentSessionSystemSnapshot> {
-    await this.initialize_instruction();
-    const composed = await this.compose_for_view();
-    const blocks = resolve_composed_system_blocks(composed);
-    return {
-      session_id: this.id,
-      session: {
-        agent_id: this.agent_id,
-        session_id: this.id,
-        project_root: this.workspace_path,
-        created_at: new Date(this.state.get_created_at()).toISOString(),
-        timezone: this.state.get_timezone(),
-      },
-      blocks,
-    };
+    return await this.session_composition.read();
   }
 
   /**
@@ -599,7 +480,12 @@ export class Session implements AgentSession {
     const include_message = typeof input === "string" || input?.include_message !== false;
     const messages = await this.session_messages.list_history_messages();
     const fork_messages = message_id
-      ? this.resolve_fork_messages(messages, message_id, include_message)
+      ? resolve_session_fork_messages({
+          session_id: this.id,
+          messages,
+          message_id,
+          include_message,
+        })
       : messages;
     const action_id = `history-forking:${this.id}:${Date.now()}:${nanoid(8)}`;
     await this.emit_action_event({
@@ -622,7 +508,9 @@ export class Session implements AgentSession {
       const approval_mode = this.state.get_approval_mode();
       await forked.state.set_approval_mode(approval_mode);
       forked.shell_approval_adapter.set_effective_mode(approval_mode);
-      await forked.session_messages.import_messages(fork_messages);
+      const relocated_messages = await relocate_fork_message_files(fork_messages, this.store.attachments, forked.store.attachments);
+      await forked.session_messages.import_messages(relocated_messages);
+      this.register_forked_session(forked);
       await this.emit_action_event({
         action_id,
         action_type: "history-fork",
@@ -643,25 +531,8 @@ export class Session implements AgentSession {
     }
   }
 
-  /** 截取 Fork 目标 Message 之前的历史，并按调用语义决定是否包含锚点。 */
-  private resolve_fork_messages(
-    messages: SessionMessage[],
-    message_id: string,
-    include_message: boolean,
-  ): SessionMessage[] {
-    const target_index = messages.findIndex(
-      (message) => message.message_id === message_id,
-    );
-    if (target_index < 0) {
-      throw new Error(
-        `Cannot fork session "${this.id}": message_id "${message_id}" not found.`,
-      );
-    }
-    return messages.slice(0, include_message ? target_index + 1 : target_index);
-  }
-
   /**
-   * 返回供受托管 plugin 使用的 session 端口。
+   * 返回供宿主运行时使用的 Session 端口。
    */
   get_runtime_port(): SessionPort {
     if (this.runtime_port) return this.runtime_port;
@@ -669,26 +540,15 @@ export class Session implements AgentSession {
       session_id: this.id,
       get_model: () => this.get_model(),
       get_executor: () => this.executor,
+      messages: async () => await this.session_messages.list_history_messages(),
       prompt: async (input) => await this.prompt(input),
       stop: async () => await this.stop(),
       subscribe: (subscriber) => this.subscribe(subscriber),
-      append_user_message: async (message_params) => {
-        const appended = await this.session_messages.append_external_user_message(
-          message_params,
-        );
-        if (!appended) return;
-        this.state.touch_metadata_in_background();
-        this.state.schedule_title_generation();
-      },
-      append_assistant_message: async (message_params) => {
-        const appended = await this.session_messages.append_external_assistant_message({
-          parts: message_params.parts,
-          text: message_params.text,
-        });
-        if (appended) await this.state.touch_metadata();
-      },
+      append_user_message: async (message_params) =>
+        await this.append_external_user_message(message_params),
+      append_agent_message: async (message_params) =>
+        await this.append_external_agent_message(message_params),
       is_executing: () => this.is_executing(),
-      context: async () => await this.session_messages.context_snapshot(),
       ensure_ready_for_execution: async () => {
         await this.ensure_ready_for_execution();
       },
@@ -705,7 +565,7 @@ export class Session implements AgentSession {
    * 在执行前确保 session 已完成初始化与宿主装配。
    */
   async ensure_ready_for_execution(): Promise<void> {
-    await this.initialize_instruction();
+    await this.session_composition.initialize();
     await this.state.ensure_ready_for_execution();
   }
 
@@ -713,21 +573,22 @@ export class Session implements AgentSession {
     return this.create_child_session({
       agent_id: this.agent_id,
       workspace_path: this.workspace_path,
-      store: this.get_session_store(session_id),
-      get_session_store: this.get_session_store,
+      ...(this.workspace_id ? { workspace_id: this.workspace_id } : {}),
+      origin: this.origin,
+      store: this.create_session_store(session_id),
+      create_session_store: this.create_session_store,
+      register_forked_session: this.register_forked_session,
       session_id: session_id,
-      tools: this.tools,
+      get_tools: this.get_tools,
       logger: this.logger,
-      instruction_system_blocks: this.effective_instruction_system_blocks.map(
-        (block) => ({ ...block }),
-      ),
+      instruction_system_blocks: this.session_composition.instruction_blocks(),
       get_instruction_system_blocks: this.get_instruction_system_blocks,
       get_workspace_env: this.get_workspace_env,
-      get_agent_plugins: this.get_agent_plugins,
+      get_hooks: this.get_hooks,
       get_managed_plugin_system_blocks: this.get_managed_plugin_system_blocks,
       ensure_configured: this.ensure_configured_hook,
       get_agent_model: this.get_agent_model,
-      composer: this.composer,
+      create_composer: this.create_composer,
     });
   }
 
@@ -745,264 +606,53 @@ export class Session implements AgentSession {
     return new session_class(options) as this;
   }
 
-  /** 恢复显式固化的完整 system snapshot；文件不存在时等待首次生成。 */
-  private async initialize_instruction(): Promise<void> {
-    if (!this.instruction_initialize_promise) {
-      this.instruction_initialize_promise = (async () => {
-        const persisted_instruction = await this.store.read_instruction();
-        if (persisted_instruction === null) return;
-
-        const instruction = persisted_instruction.trim();
-        this.system_snapshot_blocks = instruction
-          ? [{
-              source: "instruction" as const,
-              name: "snapshot",
-              content: instruction,
-            }]
-          : [];
-        const stable_system_blocks = this.effective_instruction_system_blocks
-          .filter((block) => block.source !== "instruction")
-          .map((block) => ({ ...block }));
-        this.effective_instruction_system_blocks = [
-          ...(instruction
-            ? [{
-                source: "instruction" as const,
-                name: "agent",
-                content: instruction,
-              }]
-            : []),
-          ...stable_system_blocks,
-        ];
-      })();
-    }
-    await this.instruction_initialize_promise;
-  }
-
-  private create_local_state(): SessionLocalState {
-    return {
-      session_config: {},
-      effective_session_config: {},
-      configured_approval_mode: "ask",
-      created_at: Date.now(),
-      timezone: resolve_system_timezone(),
-      initialize_promise: null,
-      ensure_configured_promise: null,
-    };
-  }
-
   /** 创建只依赖统一 Composer 的 Turn Executor。 */
   private create_executor(): Executor {
     return new Executor({
       session_id: this.id,
       composer: this.composer,
       get_compose_input: async (turn_context, retry_count) =>
-        await this.create_compose_input(turn_context, retry_count),
-      compact_history: async (input) => await this.compact_history(input),
-      get_model: () => this.get_model(),
+        await this.session_composition.create_compose_input(
+          turn_context,
+          retry_count,
+        ),
+      recover_context: async (reason) => await this.recover_context(reason),
       logger: this.logger,
-      get_plugins: () => this.effective_agent_plugins,
-      apply_system_snapshot: (input) => this.apply_system_snapshot(input),
+      get_hooks: () => this.get_hooks(),
+      apply_system_snapshot: (input) => this.session_composition.apply_snapshot(input),
     });
   }
 
-  /** 为 Composer 创建当前 Step 的只读 Session 快照。 */
-  private async create_compose_input(
-    turn_context: SessionTurnContext | undefined,
-    retry_count: number,
-    refresh_system = false,
-  ): Promise<SessionComposeInput> {
-    const instruction_system_blocks = refresh_system
-      ? this.get_instruction_system_blocks().map((block) => ({ ...block }))
-      : this.effective_instruction_system_blocks.map((block) => ({ ...block }));
-    // 关键点（中文）：Plugin system 本身参与 Compose，必须先让它看到当前检查点
-    // 已确定的 env 与 instruction；Executor 会在 Compose 返回后提交最终 Step 快照。
-    turn_context?.step.commit({
-      workspace_env: this.effective_workspace_env,
-      agent_systems: instruction_system_blocks.map((block) => block.content),
-    });
-    const plugin_execution_context =
-      turn_context?.step.plugin_execution_context() ||
-      create_session_plugin_execution_context({
-        session_id: this.id,
-        project_root: this.workspace_path,
-        workspace_env: this.effective_workspace_env,
-        agent_systems: this.effective_instruction_system_blocks.map(
-          (block) => block.content,
-        ),
-      });
-    const plugin_system_blocks = this.system_snapshot_blocks && !refresh_system
-      ? []
-      : refresh_system
-        ? await this.get_agent_plugins().system_blocks(plugin_execution_context)
-        : turn_context?.step.plugins
-          ? await turn_context.step.plugins.system_blocks(
-              plugin_execution_context,
-            )
-          : await this.effective_agent_plugins.system_blocks(
-              plugin_execution_context,
-            );
-    return {
-      session: this.create_compose_identity(),
-      state: {
-        model: this.get_model(),
-        model_context_window: this.get_model_context_window(),
-        env: Object.freeze({ ...this.effective_workspace_env }),
-        systems: Object.freeze(
-          instruction_system_blocks.map((block) => block.content),
-        ),
-        tools: Object.freeze({ ...this.tools }),
-        instruction_system_blocks,
-        managed_plugin_system_blocks:
-          this.system_snapshot_blocks && !refresh_system
-            ? []
-            : await this.get_managed_plugin_system_blocks(),
-        plugin_system_blocks,
-      },
-      history: await this.session_messages.context_snapshot(),
-      turn: {
-        ...(turn_context
-          ? { turn_id: turn_context.session.turn_id }
-          : {}),
-        retry_count,
-      },
-    };
-  }
-
-  /** 创建 Composer 共用的稳定 Session 身份快照。 */
-  private create_compose_identity(): SessionComposeIdentity {
-    return {
-      agent_id: this.agent_id,
-      session_id: this.id,
-      project_root: this.workspace_path,
-      created_at: this.local_state.created_at,
-      timezone: this.local_state.timezone,
-    };
-  }
-
-  /** 生成并提交 canonical 历史压缩；该职责不进入 Executor。 */
-  private async compact_history(
-    input: Parameters<SessionCompactHistory>[0],
-  ): ReturnType<SessionCompactHistory> {
-    return await run_session_history_compaction({
-      turn_id: input.turn_id,
-      create_plan: async () => await this.composer.compact({
-        session: this.create_compose_identity(),
-        model: this.get_model(),
-        history: await this.session_messages.context_snapshot(),
-      }),
-      commit_plan: async (plan) => {
-        await this.commit_compaction_plan(plan, input.turn_id);
-      },
-      log_error: async (error_message) => {
-        await this.logger.log("warn", "[agent] session history compaction failed", {
+  /** 让 Composer 的 Context Policy 尝试推进派生上下文状态。 */
+  private async recover_context(
+    reason: SessionContextRecoveryReason,
+  ): Promise<boolean> {
+    return await this.composer.recover_context({
+      session: this.session_composition.compose_identity(),
+      model: this.get_model(),
+      storage: this.store,
+      reason,
+      on_model_request_failure: (notice) => {
+        this.events.publish(create_session_model_request_warning({
           session_id: this.id,
-          ...(input.turn_id ? { turn_id: input.turn_id } : {}),
-          error: error_message,
-        });
+          turn_id: this.session_loop.current_turn_id(),
+          notice,
+        }));
       },
     });
   }
 
-  /** 使用统一 Composer 生成只读 system/history 查询结果。 */
-  private async compose_for_view(): Promise<SessionStepInput> {
-    const composed = await this.composer.compose(
-      await this.create_compose_input(undefined, 0),
-    );
-    return this.apply_system_snapshot(composed);
-  }
-
-  /** 固定或应用当前 Session 的 system snapshot。 */
-  private apply_system_snapshot(input: SessionStepInput): SessionStepInput {
-    if (!this.system_snapshot_blocks) {
-      this.system_snapshot_blocks = resolve_composed_system_blocks(input);
-    }
-
-    return {
-      ...input,
-      system: this.system_snapshot_blocks.map((block) => ({
-        role: "system" as const,
-        content: block.content,
-      })),
-      system_blocks: this.system_snapshot_blocks.map((block) => ({ ...block })),
-    };
-  }
-
-  /** 串行执行一次 Session system 修改。 */
-  private async run_system_mutation(
-    operation: () => Promise<void>,
-  ): Promise<void> {
-    const next = this.system_mutation_chain.then(operation, operation);
-    this.system_mutation_chain = next.catch(() => undefined);
-    await next;
-  }
-
-  /** 把指定完整 system blocks 原子写入 instruction.md。 */
-  private async write_system_snapshot(
-    blocks: readonly AgentSessionSystemBlock[],
-  ): Promise<void> {
-    await this.store.write_instruction(
-      blocks.map((block) => block.content).join("\n\n"),
-    );
-  }
-
-  /** 提交 Composer 生成的 Segment 压缩计划。 */
-  private async commit_compaction_plan(
-    plan: SessionCompactionPlan,
-    turn_id?: string,
-  ): Promise<void> {
-    const action_id = `compacting:${this.id}:${generate_id()}`;
-    await this.emit_action_event({
-      action_id,
-      action_type: "history-compaction",
-      title: "Compacting session messages",
-      status: "running",
-      ...(turn_id
-        ? { turn_id }
-        : {}),
-    });
-    try {
-      await this.session_messages.compact_active({
-        through_sequence: plan.through_sequence,
-        summary: plan.summary,
-      });
-      await this.emit_action_event({
-        action_id,
-        action_type: "history-compaction",
-        title: "Session messages compacted",
-        description: `Closed Active through Message ${plan.boundary_message_id}.`,
-        status: "completed",
-        ...(turn_id
-          ? { turn_id }
-          : {}),
-      });
-      await this.state.touch_metadata();
-    } catch (error) {
-      await this.emit_action_event({
-        action_id,
-        action_type: "history-compaction",
-        title: "Session messages compact failed",
-        description: error instanceof Error ? error.message : String(error),
-        status: "failed",
-        ...(turn_id
-          ? { turn_id }
-          : {}),
-      });
-      throw error;
-    }
-  }
-
   /**
    * 返回当前 Session 实际使用的模型实例。
    *
    * 解析顺序固定为 Session 覆盖模型，其次回退到 Agent 模型。
    */
   get_model(): ModelClient | undefined {
-    const model = this.get_selected_model();
-    return model ? normalize_agent_model(model) : undefined;
+    return this.get_selected_model();
   }
 
-  /** 按 Session 优先、Agent 兜底规则读取当前配置的 AgentModel。 */
-  private get_selected_model(): AgentModel | undefined {
+  /** 按 Session 优先、Agent 兜底规则读取当前配置的 ModelClient。 */
+  private get_selected_model(): ModelClient | undefined {
     return (
       this.local_state.effective_session_config.model ||
       this.local_state.session_config.model ||
@@ -1015,11 +665,31 @@ export class Session implements AgentSession {
     return (
       this.local_state.effective_session_config.model_context_window ||
       this.local_state.session_config.model_context_window ||
-      read_agent_model_context_window(this.get_selected_model())
+      read_model_context_window(this.get_selected_model())
+    );
+  }
+
+  /** 追加外部 User Message，并统一触发 Metadata 与标题更新。 */
+  private async append_external_user_message(
+    input: AppendExternalSessionUserMessageInput,
+  ): Promise<void> {
+    const appended = await this.session_messages.append_external_user_message(
+      input,
+    );
+    if (!appended) return;
+    this.state.schedule_title_generation();
+  }
+
+  /** 追加外部 Assistant Message，并统一提交 Metadata。 */
+  private async append_external_agent_message(
+    input: AppendExternalSessionAgentMessageInput,
+  ): Promise<void> {
+    await this.session_messages.append_external_agent_message(
+      input,
     );
   }
 
-  /** 持久化并发布一条 canonical Action Message。 */
+  /** 持久化并发布一条只包含 Action Part 的 canonical Agent Message。 */
   private async emit_action_event(input: SessionActionEventInput): Promise<void> {
     const action_id = String(input.action_id || "").trim() ||
       `action:${this.id}:${Date.now()}`;
@@ -1031,38 +701,6 @@ export class Session implements AgentSession {
       ...(input.description ? { description: input.description } : {}),
       status: input.status,
     });
-    await this.state.touch_metadata();
-  }
-
-}
-
-/** 把自定义 Composer 的 system content 转为可展示文本。 */
-function stringify_system_content(content: unknown): string {
-  if (typeof content === "string") return content.trim();
-  if (content === null || content === undefined) return "";
-  try {
-    return JSON.stringify(content);
-  } catch {
-    return String(content || "").trim();
   }
-}
 
-/** 以实际模型输入为准，保留仍与其一致的 system block 来源信息。 */
-function resolve_composed_system_blocks(
-  composed: SessionStepInput,
-): AgentSessionSystemBlock[] {
-  const declared_blocks = composed.system_blocks || [];
-  return composed.system.flatMap((message, index) => {
-    const content = stringify_system_content(message.content);
-    if (!content) return [];
-    const declared = declared_blocks[index];
-    if (declared && declared.content.trim() === content) {
-      return [{ ...declared, content }];
-    }
-    return [{
-      source: "session" as const,
-      name: `custom_system:${index + 1}`,
-      content,
-    }];
-  });
 }