@downcity/agent 1.1.287 → 1.1.310

package/src/session/Session.ts

@@ -10,165 +10,163 @@
 import { Executor } from "@executor/Executor.js";
 import type { LanguageModel, Tool } from "ai";
 import {
-  normalizeAgentModel,
+  normalize_agent_model,
   read_agent_model_context_window,
   type AgentModel,
 } from "@/agent/AgentModel.js";
-import { JsonlSessionMessageStore } from "@/session/messages/JsonlSessionMessageStore.js";
 import { SessionMessages } from "@/session/SessionMessages.js";
 import type {
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
   AgentSessionInfo,
+  AgentSessionStatus,
   AgentSessionSetInput,
   AgentSessionSystemBlock,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/SessionTypes.js";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
-import {
-  getSdkAgentSessionAssistantMessagePath,
-  getSdkAgentSessionDirPath,
-} from "@/session/storage/Paths.js";
-import { resolveSystemTimezone } from "@/session/storage/Metadata.js";
-import { createRuntimeSessionPort } from "@/session/storage/RuntimeSessionPort.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 "@/types/session/SessionMutation.js";
-import type {
-  ResolveSessionApprovalInput,
-  SessionApproval,
-  SessionApprovalModeSnapshot,
-  SessionApprovalResult,
-  SetSessionApprovalModeInput,
-} from "@/types/session/SessionApproval.js";
-import type {
-  ListSessionMessagesInput,
-  SessionMessagePage,
-} from "@/types/session/SessionMessage.js";
+  RespondSessionInteractionInput,
+  SessionApprovalMode,
+  SessionInteractionResult,
+  SessionPendingInteraction,
+} from "@/types/session/SessionInteraction.js";
+import type { ListSessionMessagesInput, SessionMessagePage } from "@/types/session/SessionMessage.js";
 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 { SessionTurn } from "@/session/SessionTurn.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 {
-  AgentSessionCommand,
-  SessionQueueCommand,
-} from "@/types/session/SessionQueue.js";
 import type { SessionOptions } from "@/types/session/SessionOptions.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
-import { SessionApprovalBroker } from "@/session/approval/SessionApprovalBroker.js";
+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 { SessionRunContext } from "@/types/executor/SessionRunContext.js";
-import { generateId } from "@/utils/Id.js";
+import type { SessionCompactHistory } from "@/types/session/SessionExecution.js";
+import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
+import { generate_id } from "@/utils/Id.js";
 import { nanoid } from "nanoid";
-import { buildSessionInfo } from "@/session/browse/Browse.js";
-import { ensureSessionTitle } from "@/session/SessionTitle.js";
-import { readSessionMetadata } from "@/session/storage/Metadata.js";
-import {
-  has_session_instruction,
-  read_session_instruction,
-  write_session_instruction,
-} from "@/session/storage/Instruction.js";
+import { build_session_info } from "@/session/browse/Browse.js";
+import { ensure_session_title } from "@/session/SessionTitle.js";
 import { to_executor_history } from "@/session/messages/SessionMessageCodec.js";
 import type { SessionMessage } from "@/types/session/SessionMessage.js";
-import type {
-  SessionActionRecordInputV1,
-  SessionActionRecordV1,
-} from "@/executor/types/SessionRecords.js";
+import type { SessionActionRecordInputV1 } from "@/executor/types/SessionRecords.js";
+import type { SessionCommandOptions } from "@/types/session/SessionCommand.js";
+import type { SessionStore } from "@/types/store/SessionStore.js";
 
 /**
  * SDK 本地 Session。
  */
 export class Session implements AgentSession {
   readonly id: string;
-  readonly agentId: string;
+  readonly agent_id: string;
 
-  private readonly project_root: string;
+  private readonly workspace_path: string;
+  private readonly store: SessionStore;
+  private readonly get_session_store: SessionOptions["get_session_store"];
   private readonly tools: Record<string, Tool>;
   private readonly logger: SessionOptions["logger"];
-  private readonly get_managed_plugin_system_blocks: SessionOptions["getManagedPluginSystemBlocks"];
-  private readonly ensure_configured_hook?: SessionOptions["ensureConfigured"];
+  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 message_store: JsonlSessionMessageStore;
   private readonly session_messages: SessionMessages;
   private readonly executor: Executor;
   private readonly events: SessionEventHub;
-  private readonly approval_broker: SessionApprovalBroker;
+  private readonly session_interactions: SessionInteractions;
+  private readonly shell_approval_adapter: SessionShellApprovalAdapter;
+  /** 已被 Session 接受、等待或已经在 Step 检查点提交的审批模式。 */
+  private configured_approval_mode: SessionApprovalMode = "ask";
   private readonly local_state: SessionLocalState;
-  private readonly get_agent_env: SessionOptions["getAgentEnv"];
-  private readonly get_agent_model: SessionOptions["getAgentModel"];
+  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_instruction_system_blocks:
     SessionOptions["get_instruction_system_blocks"];
   private effective_instruction_system_blocks: AgentSessionSystemBlock[];
   private instruction_initialize_promise: Promise<void> | null = null;
-  private effective_agent_env: Record<string, string>;
+  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();
   private readonly state: SessionState;
-  private readonly session_turn: SessionTurn;
+  /** 当前 Session 独享的 Command FIFO。 */
+  private readonly session_queue = new SessionQueue();
+  private readonly session_loop: SessionLoop;
   private runtime_port: SessionPort | null = null;
 
   constructor(options: SessionOptions) {
-    this.id = String(options.sessionId || "").trim();
-    this.agentId = String(options.agentId || "").trim();
-    this.project_root = String(options.projectRoot || "").trim();
+    this.id = String(options.session_id || "").trim();
+    this.agent_id = String(options.agent_id || "").trim();
+    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.logger = options.logger;
-    this.get_agent_env = options.getAgentEnv;
-    this.get_agent_model = options.getAgentModel;
+    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_instruction_system_blocks = options.get_instruction_system_blocks;
     this.effective_instruction_system_blocks = options
       .instruction_system_blocks
       .map((block) => ({ ...block }));
-    this.effective_agent_env = { ...options.getAgentEnv() };
+    this.effective_workspace_env = { ...options.get_workspace_env() };
     this.effective_agent_plugins = options.get_agent_plugins();
-    this.get_managed_plugin_system_blocks = options.getManagedPluginSystemBlocks;
-    this.ensure_configured_hook = options.ensureConfigured;
+    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();
     if (!this.id) {
-      throw new Error("Session requires a non-empty sessionId");
+      throw new Error("Session requires a non-empty session_id");
     }
-    if (!this.agentId) {
-      throw new Error("Session requires a non-empty agentId");
+    if (!this.agent_id) {
+      throw new Error("Session requires a non-empty agent_id");
     }
-    if (!this.project_root) {
-      throw new Error("Session requires a non-empty project_root");
+    if (!this.workspace_path) {
+      throw new Error("Session requires a non-empty workspace_path");
     }
 
     this.events = new SessionEventHub();
-    this.message_store = this.create_message_store();
     this.session_messages = new SessionMessages({
       session_id: this.id,
-      store: this.message_store,
+      store: this.store.messages,
       publish: (mutation) => {
         this.events.publish(mutation);
       },
     });
-    this.approval_broker = new SessionApprovalBroker({
+    this.session_interactions = new SessionInteractions({
       session_id: this.id,
       messages: this.session_messages,
     });
+    this.shell_approval_adapter = new SessionShellApprovalAdapter({
+      session_id: this.id,
+      interactions: this.session_interactions,
+    });
     this.local_state = this.create_local_state();
     this.executor = this.create_executor();
     this.state = new SessionState({
-      agent_id: this.agentId,
-      project_root: this.project_root,
+      agent_id: this.agent_id,
       session_id: this.id,
+      store: this.store,
       messages: this.session_messages,
       state: this.local_state,
       logger: this.logger,
@@ -182,16 +180,18 @@ export class Session implements AgentSession {
         this.events.publish(event);
       },
     });
-    this.session_turn = new SessionTurn({
+    this.session_loop = new SessionLoop({
       session_id: this.id,
-      project_root: this.project_root,
+      workspace_path: this.workspace_path,
       executor: this.executor,
+      compact_history: async (input) => await this.compact_history(input),
       state: this.state,
       events: this.events,
+      logger: this.logger,
       messages: this.session_messages,
-      approvals: this.approval_broker,
-      apply_command: async (command, turn_id) =>
-        await this.apply_queue_command(command, turn_id),
+      interactions: this.session_interactions,
+      shell_approval_gateway: this.shell_approval_adapter,
+      queue: this.session_queue,
     });
   }
 
@@ -232,19 +232,9 @@ export class Session implements AgentSession {
   async syncshot(): Promise<void> {
     await this.run_system_mutation(async () => {
       await this.initialize_instruction();
-      const should_persist = await has_session_instruction({
-        project_root: this.project_root,
-        agent_id: this.agentId,
-        session_id: this.id,
-      });
-      const run_context: SessionRunContext = {
-        sessionId: this.id,
-        injectedUserMessages: [],
-        deferredPersistedUserMessages: [],
-        pendingAssistantFileParts: [],
-      };
+      const should_persist = await this.store.has_instruction();
       const composed = await this.composer.compose(
-        await this.create_compose_input(run_context, 0, true),
+        await this.create_compose_input(undefined, 0, true),
       );
       const next_blocks = resolve_composed_system_blocks(composed);
 
@@ -268,10 +258,50 @@ export class Session implements AgentSession {
    * 写入当前 session 默认配置。
    */
   async set(input: AgentSessionSetInput): Promise<void> {
-    const configured = await this.state.set(input);
-    if (configured.command) {
-      this.session_turn.enqueue_command(configured.command);
+    if (!input.model && !input.security) {
+      throw new Error("session.set requires model or security");
+    }
+    const requested_approval_mode = input.security?.approval_mode;
+    if (
+      requested_approval_mode !== undefined &&
+      requested_approval_mode !== "ask" &&
+      requested_approval_mode !== "always-allow"
+    ) {
+      throw new Error("security.approval_mode must be ask or always-allow");
+    }
+    const model_config = input.model
+      ? await this.state.set_model(input.model)
+      : undefined;
+    const next_approval_mode = requested_approval_mode;
+    const security_changed = Boolean(
+      next_approval_mode && next_approval_mode !== this.configured_approval_mode,
+    );
+    if (next_approval_mode !== undefined) {
+      this.configured_approval_mode = next_approval_mode;
     }
+    if (!model_config && !security_changed) return;
+    const changed_fields = [
+      ...(model_config
+        ? [`model: ${String(model_config.model_label || "configured")}`]
+        : []),
+      ...(security_changed
+        ? [`security.approval_mode: ${String(next_approval_mode)}`]
+        : []),
+    ];
+    this.enqueue_command({
+      execute: async () => {
+        if (model_config) this.state.apply_model_config(model_config);
+        if (security_changed && next_approval_mode) {
+          this.shell_approval_adapter.set_effective_mode(next_approval_mode);
+        }
+      },
+      completion: {
+        type: "action",
+        id: `session-config:${this.id}:${Date.now()}:${generate_id()}`,
+        title: "Session configuration updated",
+        description: changed_fields.join("; "),
+      },
+    });
   }
 
   /**
@@ -279,78 +309,105 @@ export class Session implements AgentSession {
    */
   async prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
     await this.initialize_instruction();
-    return await this.session_turn.prompt(input);
+    return await this.session_loop.prompt(input);
   }
 
   /**
    * 停止当前 turn，并取消尚未被吸收的排队 prompt。
    */
   async stop(): Promise<AgentSessionStopResult> {
-    await this.approval_broker.expire_all();
-    return this.session_turn.stop();
+    return await this.session_loop.stop();
   }
 
   /**
    * 把一次显式历史压缩加入当前 Session 的有序输入队列。
    */
-  async compact(): Promise<void> {
-    await this.session_turn.compact();
+  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 configured state command 加入当前 Session 的统一输入队列。
-   */
-  enqueue_agent_command(command: AgentSessionCommand): void {
-    if (command.type === "env") {
-      this.session_turn.enqueue_command({
-        type: "agent_env",
-        command_id: command.command_id,
-        env: command.env,
-      });
-      return;
-    }
-    this.session_turn.enqueue_command({
-      type: "agent_plugins",
-      command_id: command.command_id,
-      title: command.title,
-      plugins: command.plugins,
+  /** 把 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,
+      },
     });
   }
 
-  /** 在 Step 检查点提交明确的 Session/Agent 状态命令。 */
-  private async apply_queue_command(
-    command: Exclude<SessionQueueCommand, { type: "compact" }>,
-    turn_id: string,
-  ): Promise<void> {
-    if (command.type === "session_model") {
-      await this.state.apply_model_command(command);
-      if (command.action_id && command.action_title) {
-        await this.emit_config_action_event({
-          id: command.action_id,
-          title: command.action_title,
-          state: "completed",
-          turnId: turn_id,
-        });
-      }
-      return;
-    }
-    if (command.type === "agent_env") {
-      this.effective_agent_env = { ...command.env };
-      await this.emit_config_action_event({
-        id: `agent-env:${this.id}:${command.command_id}`,
-        title: "Agent environment updated",
-        state: "completed",
-        turnId: turn_id,
-      });
-      return;
-    }
-    this.effective_agent_plugins = command.plugins;
-    await this.emit_config_action_event({
-      id: `agent-plugins:${this.id}:${command.command_id}`,
-      title: command.title,
-      state: "completed",
-      turnId: turn_id,
-    });
+  /** 创建一个具体 Session Command 对象并加入当前 FIFO。 */
+  private enqueue_command(options: SessionCommandOptions): void {
+    this.session_queue.enqueue_command(new SessionCommand(options));
   }
 
   /**
@@ -362,24 +419,28 @@ export class Session implements AgentSession {
     return this.events.subscribe(subscriber);
   }
 
-  /** 列出当前 Session 的 pending 工具审批。 */
-  async approvals(): Promise<SessionApproval[]> {
-    return this.approval_broker.list();
+  /** 列出当前 Session 正在等待用户响应的 Interaction。 */
+  async interactions(): Promise<SessionPendingInteraction[]> {
+    return this.session_interactions.list();
   }
 
-  /** 读取当前 Session 的工具审批模式。 */
-  async approval_mode(): Promise<SessionApprovalModeSnapshot> {
-    return this.approval_broker.get_mode();
-  }
-
-  /** 更新当前 Session 的工具审批模式。 */
-  async set_approval_mode(input: SetSessionApprovalModeInput): Promise<SessionApprovalModeSnapshot> {
-    return this.approval_broker.set_mode(input.mode);
+  /** 读取当前 Session 的运行与安全状态。 */
+  async status(): Promise<AgentSessionStatus> {
+    const active_turn_id = this.session_loop.current_turn_id();
+    return {
+      session_id: this.id,
+      state: active_turn_id || this.executor.is_executing() ? "running" : "idle",
+      ...(active_turn_id ? { active_turn_id } : {}),
+      security: {
+        approval_mode: this.configured_approval_mode,
+        effective_approval_mode: this.shell_approval_adapter.get_effective_mode(),
+      },
+    };
   }
 
-  /** 处理当前 Session 的 pending 工具审批。 */
-  async resolve_approval(input: ResolveSessionApprovalInput): Promise<SessionApprovalResult> {
-    return await this.approval_broker.resolve(input);
+  /** 提交当前 Session 的 Interaction 用户响应。 */
+  async respond(input: RespondSessionInteractionInput): Promise<SessionInteractionResult> {
+    return await this.session_interactions.respond(input);
   }
 
   /**
@@ -413,30 +474,25 @@ export class Session implements AgentSession {
    */
   async get_info(): Promise<AgentSessionInfo> {
     const [metadata, snapshot] = await Promise.all([
-      readSessionMetadata({
-        projectRoot: this.project_root,
-        agentId: this.agentId,
-        sessionId: this.id,
-      }),
+      this.store.read_metadata(),
       this.session_messages.context_snapshot(),
     ]);
     const records = to_executor_history(this.id, snapshot);
     const metadata_with_title = metadata.title
       ? metadata
-      : await ensureSessionTitle({
-          projectRoot: this.project_root,
-          agentId: this.agentId,
-          sessionId: this.id,
+      : await ensure_session_title({
+          session_id: this.id,
+          store: this.store,
           messages: records,
           logger: this.logger,
         });
-    return buildSessionInfo({
-      projectRoot: this.project_root,
-      agentId: this.agentId,
-      sessionId: this.id,
+    return build_session_info({
+      project_root: this.workspace_path,
+      agent_id: this.agent_id,
+      session_id: this.id,
       metadata: metadata_with_title,
       messages: records,
-      executing: this.isExecuting(),
+      executing: this.is_executing(),
     });
   }
 
@@ -455,12 +511,12 @@ export class Session implements AgentSession {
     const composed = await this.compose_for_view();
     const blocks = resolve_composed_system_blocks(composed);
     return {
-      sessionId: this.id,
+      session_id: this.id,
       session: {
-        agentId: this.agentId,
-        sessionId: this.id,
-        projectRoot: this.project_root,
-        createdAt: new Date(this.state.get_created_at()).toISOString(),
+        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,
@@ -470,8 +526,8 @@ export class Session implements AgentSession {
   /**
    * 返回当前 session 是否正在执行。
    */
-  isExecuting(): boolean {
-    return this.session_turn.is_active() || this.executor.isExecuting();
+  is_executing(): boolean {
+    return this.session_loop.is_active() || this.executor.is_executing();
   }
 
   /**
@@ -480,7 +536,7 @@ export class Session implements AgentSession {
   async fork(input?: AgentSessionForkInput | string): Promise<this> {
     const message_id = typeof input === "string"
       ? String(input || "").trim() || undefined
-      : String(input?.messageId || "").trim() || undefined;
+      : String(input?.message_id || "").trim() || undefined;
     const messages = await this.session_messages.list_history_messages();
     const fork_messages = message_id
       ? this.resolve_fork_messages(messages, message_id)
@@ -499,10 +555,8 @@ export class Session implements AgentSession {
       await forked.initialize();
       const session_config = this.state.get_config();
       if (session_config.model) {
-        await forked.state.set(
-          { model: session_config.model },
-          { emit_action: false },
-        );
+        const forked_config = await forked.state.set_model(session_config.model);
+        forked.state.apply_model_config(forked_config);
       }
       await forked.session_messages.import_messages(fork_messages);
       await this.emit_action_event({
@@ -533,7 +587,7 @@ export class Session implements AgentSession {
     );
     if (target_index < 0) {
       throw new Error(
-        `Cannot fork session "${this.id}": messageId "${message_id}" not found.`,
+        `Cannot fork session "${this.id}": message_id "${message_id}" not found.`,
       );
     }
     return messages.slice(0, target_index + 1);
@@ -542,12 +596,12 @@ export class Session implements AgentSession {
   /**
    * 返回供受托管 plugin 使用的 session 端口。
    */
-  getRuntimePort(): SessionPort {
+  get_runtime_port(): SessionPort {
     if (this.runtime_port) return this.runtime_port;
-    this.runtime_port = createRuntimeSessionPort({
-      sessionId: this.id,
-      getModel: () => this.get_model(),
-      getExecutor: () => this.executor.getExecutor(),
+    this.runtime_port = create_runtime_session_port({
+      session_id: this.id,
+      get_model: () => this.get_model(),
+      get_executor: () => this.executor,
       prompt: async (input) => await this.prompt(input),
       stop: async () => await this.stop(),
       subscribe: (subscriber) => this.subscribe(subscriber),
@@ -562,14 +616,14 @@ export class Session implements AgentSession {
       append_assistant_message: async (message_params) => {
         const appended = await this.session_messages.append_external_assistant_message({
           message: message_params.message,
-          fallback_text: message_params.fallbackText,
+          fallback_text: message_params.fallback_text,
         });
         if (appended) await this.state.touch_metadata();
       },
-      isExecuting: () => this.isExecuting(),
+      is_executing: () => this.is_executing(),
       context: async () => await this.session_messages.context_snapshot(),
-      ensureReadyForExecution: async () => {
-        await this.ensureReadyForExecution();
+      ensure_ready_for_execution: async () => {
+        await this.ensure_ready_for_execution();
       },
     });
     return this.runtime_port;
@@ -578,27 +632,29 @@ export class Session implements AgentSession {
   /**
    * 在执行前确保 session 已完成初始化与宿主装配。
    */
-  async ensureReadyForExecution(): Promise<void> {
+  async ensure_ready_for_execution(): Promise<void> {
     await this.initialize_instruction();
     await this.state.ensure_ready_for_execution();
   }
 
   private create_fork_session(session_id: string): this {
     return this.create_child_session({
-      agentId: this.agentId,
-      projectRoot: this.project_root,
-      sessionId: session_id,
+      agent_id: this.agent_id,
+      workspace_path: this.workspace_path,
+      store: this.get_session_store(session_id),
+      get_session_store: this.get_session_store,
+      session_id: session_id,
       tools: this.tools,
       logger: this.logger,
       instruction_system_blocks: this.effective_instruction_system_blocks.map(
         (block) => ({ ...block }),
       ),
       get_instruction_system_blocks: this.get_instruction_system_blocks,
-      getAgentEnv: this.get_agent_env,
+      get_workspace_env: this.get_workspace_env,
       get_agent_plugins: this.get_agent_plugins,
-      getManagedPluginSystemBlocks: this.get_managed_plugin_system_blocks,
-      ensureConfigured: this.ensure_configured_hook,
-      getAgentModel: this.get_agent_model,
+      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,
     });
   }
@@ -611,21 +667,17 @@ export class Session implements AgentSession {
    * - 子类仍可覆盖该方法，接管更特殊的子会话创建逻辑。
    */
   protected create_child_session(options: SessionOptions): this {
-    const SessionClass = this.constructor as new (
+    const session_class = this.constructor as new (
       options: SessionOptions,
     ) => Session;
-    return new SessionClass(options) as this;
+    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 read_session_instruction({
-          project_root: this.project_root,
-          agent_id: this.agentId,
-          session_id: this.id,
-        });
+        const persisted_instruction = await this.store.read_instruction();
         if (persisted_instruction === null) return;
 
         const instruction = persisted_instruction.trim();
@@ -654,30 +706,12 @@ export class Session implements AgentSession {
     await this.instruction_initialize_promise;
   }
 
-  private create_message_store(): JsonlSessionMessageStore {
-    const session_dir_path = getSdkAgentSessionDirPath(
-      this.project_root,
-      this.agentId,
-      this.id,
-    );
-    const messages_dir_path = `${session_dir_path}/messages`;
-    return new JsonlSessionMessageStore({
-      session_id: this.id,
-      file_path: `${messages_dir_path}/active.jsonl`,
-      assistant_message_file_path: getSdkAgentSessionAssistantMessagePath(
-        this.project_root,
-        this.agentId,
-        this.id,
-      ),
-    });
-  }
-
   private create_local_state(): SessionLocalState {
     return {
       session_config: {},
       effective_session_config: {},
       created_at: Date.now(),
-      timezone: resolveSystemTimezone(),
+      timezone: resolve_system_timezone(),
       initialize_promise: null,
       ensure_configured_promise: null,
     };
@@ -686,13 +720,12 @@ export class Session implements AgentSession {
   /** 创建只依赖统一 Composer 的 Turn Executor。 */
   private create_executor(): Executor {
     return new Executor({
-      sessionId: this.id,
+      session_id: this.id,
       composer: this.composer,
-      get_compose_input: async (run_context, retry_count) =>
-        await this.create_compose_input(run_context, retry_count),
-      commit_compaction: async (plan, run_context) =>
-        await this.commit_compaction_plan(plan, run_context),
-      getModel: () => this.get_model(),
+      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(),
       logger: this.logger,
       get_plugins: () => this.effective_agent_plugins,
       apply_system_snapshot: (input) => this.apply_system_snapshot(input),
@@ -701,32 +734,46 @@ export class Session implements AgentSession {
 
   /** 为 Composer 创建当前 Step 的只读 Session 快照。 */
   private async create_compose_input(
-    run_context: SessionRunContext,
+    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().systemBlocks(run_context)
-        : run_context.agentPlugins
-          ? await run_context.agentPlugins.systemBlocks(run_context)
-          : await this.effective_agent_plugins.systemBlocks(run_context);
+        ? 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: {
-        agent_id: this.agentId,
-        session_id: this.id,
-        project_root: this.project_root,
-        created_at: this.local_state.created_at,
-        timezone: this.local_state.timezone,
-      },
+      session: this.create_compose_identity(),
       state: {
         model: this.get_model(),
         model_context_window: this.get_model_context_window(),
-        env: Object.freeze({ ...this.effective_agent_env }),
+        env: Object.freeze({ ...this.effective_workspace_env }),
         systems: Object.freeze(
           instruction_system_blocks.map((block) => block.content),
         ),
@@ -740,22 +787,53 @@ export class Session implements AgentSession {
       },
       history: await this.session_messages.context_snapshot(),
       turn: {
-        ...(run_context.turnId ? { turn_id: run_context.turnId } : {}),
+        ...(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", {
+          session_id: this.id,
+          ...(input.turn_id ? { turn_id: input.turn_id } : {}),
+          error: error_message,
+        });
+      },
+    });
+  }
+
   /** 使用统一 Composer 生成只读 system/history 查询结果。 */
   private async compose_for_view(): Promise<SessionStepInput> {
-    const run_context: SessionRunContext = {
-      sessionId: this.id,
-      injectedUserMessages: [],
-      deferredPersistedUserMessages: [],
-      pendingAssistantFileParts: [],
-    };
     const composed = await this.composer.compose(
-      await this.create_compose_input(run_context, 0),
+      await this.create_compose_input(undefined, 0),
     );
     return this.apply_system_snapshot(composed);
   }
@@ -789,25 +867,24 @@ export class Session implements AgentSession {
   private async write_system_snapshot(
     blocks: readonly AgentSessionSystemBlock[],
   ): Promise<void> {
-    await write_session_instruction({
-      project_root: this.project_root,
-      agent_id: this.agentId,
-      session_id: this.id,
-      instruction: blocks.map((block) => block.content).join("\n\n"),
-    });
+    await this.store.write_instruction(
+      blocks.map((block) => block.content).join("\n\n"),
+    );
   }
 
   /** 提交 Composer 生成的 Segment 压缩计划。 */
   private async commit_compaction_plan(
     plan: SessionCompactionPlan,
-    run_context: SessionRunContext,
+    turn_id?: string,
   ): Promise<void> {
-    const action_id = `compacting:${this.id}:${generateId()}`;
+    const action_id = `compacting:${this.id}:${generate_id()}`;
     await this.emit_action_event({
       id: action_id,
       title: "Compacting session messages",
       state: "running",
-      ...(run_context.turnId ? { turnId: run_context.turnId } : {}),
+      ...(turn_id
+        ? { turn_id }
+        : {}),
     });
     try {
       await this.session_messages.compact_active({
@@ -821,7 +898,9 @@ export class Session implements AgentSession {
           ? `Closed Active through Message ${plan.boundary_message_id} with deterministic fallback Summary.`
           : `Closed Active through Message ${plan.boundary_message_id}.`,
         state: "completed",
-        ...(run_context.turnId ? { turnId: run_context.turnId } : {}),
+        ...(turn_id
+          ? { turn_id }
+          : {}),
       });
       await this.state.touch_metadata();
     } catch (error) {
@@ -830,7 +909,9 @@ export class Session implements AgentSession {
         title: "Session messages compact failed",
         description: error instanceof Error ? error.message : String(error),
         state: "failed",
-        ...(run_context.turnId ? { turnId: run_context.turnId } : {}),
+        ...(turn_id
+          ? { turn_id }
+          : {}),
       });
       throw error;
     }
@@ -843,7 +924,7 @@ export class Session implements AgentSession {
    */
   get_model(): LanguageModel | undefined {
     const model = this.get_selected_model();
-    return model ? normalizeAgentModel(model) : undefined;
+    return model ? normalize_agent_model(model) : undefined;
   }
 
   /** 按 Session 优先、Agent 兜底规则读取当前配置的 AgentModel。 */
@@ -877,40 +958,13 @@ export class Session implements AgentSession {
       metadata: {
         v: 1,
         ts: Date.now(),
-        sessionId: this.id,
-        ...(input.turnId ? { turnId: input.turnId } : {}),
+        session_id: this.id,
+        ...(input.turn_id ? { turn_id: input.turn_id } : {}),
       },
     });
     await this.state.touch_metadata();
   }
 
-  /** 尽力记录配置 Action，不让 timeline 故障反向改变已提交配置。 */
-  private async emit_config_action_event(
-    input: SessionActionRecordInputV1 | SessionActionRecordV1,
-  ): Promise<boolean> {
-    try {
-      await this.emit_action_event({
-        id: input.id,
-        title: input.title,
-        description: input.description,
-        state: input.state,
-        turnId: "turnId" in input ? input.turnId : input.metadata?.turnId,
-      });
-      return true;
-    } catch (error) {
-      try {
-        await this.logger.log("warn", "[agent] config action persistence failed", {
-          sessionId: this.id,
-          actionId: String(input.id || ""),
-          error: error instanceof Error ? error.message : String(error),
-        });
-      } catch {
-        // 配置已提交，日志失败也不能反向改变 effective state。
-      }
-      return false;
-    }
-  }
-
 }
 
 /** 把自定义 Composer 的 system content 转为可展示文本。 */