@downcity/agent 1.1.287 → 1.1.310

package/bin/session/Session.js

@@ -7,103 +7,116 @@
  * - 内部使用 `SessionMessages` 统一管理 Active、Segment 与流式 Assistant 草稿。
  */
 import { Executor } from "../executor/Executor.js";
-import { normalizeAgentModel, read_agent_model_context_window, } from "../agent/AgentModel.js";
-import { JsonlSessionMessageStore } from "../session/messages/JsonlSessionMessageStore.js";
+import { normalize_agent_model, read_agent_model_context_window, } from "../agent/AgentModel.js";
 import { SessionMessages } from "../session/SessionMessages.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 { 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 { SessionApprovalBroker } from "../session/approval/SessionApprovalBroker.js";
+import { SessionLoop } from "../session/SessionLoop.js";
+import { SessionQueue } from "../session/SessionQueue.js";
+import { SessionCommand } from "../session/SessionCommand.js";
+import { SessionInteractions } from "../session/control/SessionInteractions.js";
+import { SessionShellApprovalAdapter } from "../session/execution/tools/SessionShellApprovalAdapter.js";
 import { DefaultSessionComposer } from "../session/DefaultSessionComposer.js";
-import { generateId } from "../utils/Id.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";
 /**
  * SDK 本地 Session。
  */
 export class Session {
     id;
-    agentId;
-    project_root;
+    agent_id;
+    workspace_path;
+    store;
+    get_session_store;
     tools;
     logger;
     get_managed_plugin_system_blocks;
     ensure_configured_hook;
     composer;
-    message_store;
     session_messages;
     executor;
     events;
-    approval_broker;
+    session_interactions;
+    shell_approval_adapter;
+    /** 已被 Session 接受、等待或已经在 Step 检查点提交的审批模式。 */
+    configured_approval_mode = "ask";
     local_state;
-    get_agent_env;
+    get_workspace_env;
     get_agent_model;
     get_agent_plugins;
     get_instruction_system_blocks;
     effective_instruction_system_blocks;
     instruction_initialize_promise = null;
-    effective_agent_env;
+    effective_workspace_env;
     effective_agent_plugins;
     /** 当前 Session 首次生成后固定的完整 system snapshot。 */
     system_snapshot_blocks = null;
     /** 串行化 snapshot / syncshot 对 system 与 instruction.md 的修改。 */
     system_mutation_chain = Promise.resolve();
     state;
-    session_turn;
+    /** 当前 Session 独享的 Command FIFO。 */
+    session_queue = new SessionQueue();
+    session_loop;
     runtime_port = null;
     constructor(options) {
-        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,
@@ -117,15 +130,18 @@ export class Session {
                 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,
         });
     }
     /**
@@ -163,18 +179,8 @@ export class Session {
     async syncshot() {
         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 = {
-                sessionId: this.id,
-                injectedUserMessages: [],
-                deferredPersistedUserMessages: [],
-                pendingAssistantFileParts: [],
-            };
-            const composed = await this.composer.compose(await this.create_compose_input(run_context, 0, true));
+            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);
@@ -194,103 +200,163 @@ export class Session {
      * 写入当前 session 默认配置。
      */
     async set(input) {
-        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("; "),
+            },
+        });
     }
     /**
      * 追加一条新的 Session prompt。
      */
     async prompt(input) {
         await this.initialize_instruction();
-        return await this.session_turn.prompt(input);
+        return await this.session_loop.prompt(input);
     }
     /**
      * 停止当前 turn，并取消尚未被吸收的排队 prompt。
      */
     async stop() {
-        await this.approval_broker.expire_all();
-        return this.session_turn.stop();
+        return await this.session_loop.stop();
     }
     /**
      * 把一次显式历史压缩加入当前 Session 的有序输入队列。
      */
     async compact() {
-        await this.session_turn.compact();
+        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;
     }
-    /**
-     * 把 Agent configured state command 加入当前 Session 的统一输入队列。
-     */
-    enqueue_agent_command(command) {
-        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,
+    /** 把 Workspace env 快照加入当前 Session 的有序输入队列。 */
+    enqueue_workspace_env(input) {
+        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",
+            },
         });
     }
-    /** 在 Step 检查点提交明确的 Session/Agent 状态命令。 */
-    async apply_queue_command(command, turn_id) {
-        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,
+    /** 把 Agent Plugin 执行视图加入当前 Session 的有序输入队列。 */
+    enqueue_agent_plugins(input) {
+        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。 */
+    enqueue_command(options) {
+        this.session_queue.enqueue_command(new SessionCommand(options));
+    }
     /**
      * 订阅当前 Session 的未来事件。
      */
     subscribe(subscriber) {
         return this.events.subscribe(subscriber);
     }
-    /** 列出当前 Session 的 pending 工具审批。 */
-    async approvals() {
-        return this.approval_broker.list();
+    /** 列出当前 Session 正在等待用户响应的 Interaction。 */
+    async interactions() {
+        return this.session_interactions.list();
     }
-    /** 读取当前 Session 的工具审批模式。 */
-    async approval_mode() {
-        return this.approval_broker.get_mode();
-    }
-    /** 更新当前 Session 的工具审批模式。 */
-    async set_approval_mode(input) {
-        return this.approval_broker.set_mode(input.mode);
+    /** 读取当前 Session 的运行与安全状态。 */
+    async status() {
+        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) {
-        return await this.approval_broker.resolve(input);
+    /** 提交当前 Session 的 Interaction 用户响应。 */
+    async respond(input) {
+        return await this.session_interactions.respond(input);
     }
     /**
      * 追加一条 user 文本消息。
@@ -319,30 +385,25 @@ export class Session {
      */
     async get_info() {
         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(),
         });
     }
     /**
@@ -359,12 +420,12 @@ export class Session {
         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,
@@ -373,8 +434,8 @@ export class Session {
     /**
      * 返回当前 session 是否正在执行。
      */
-    isExecuting() {
-        return this.session_turn.is_active() || this.executor.isExecuting();
+    is_executing() {
+        return this.session_loop.is_active() || this.executor.is_executing();
     }
     /**
      * 从当前 session 创建一个分叉会话。
@@ -382,7 +443,7 @@ export class Session {
     async fork(input) {
         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)
@@ -399,7 +460,8 @@ export class Session {
             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({
@@ -424,20 +486,20 @@ export class Session {
     resolve_fork_messages(messages, message_id) {
         const target_index = messages.findIndex((message) => message.message_id === message_id);
         if (target_index < 0) {
-            throw new Error(`Cannot fork session "${this.id}": messageId "${message_id}" not found.`);
+            throw new Error(`Cannot fork session "${this.id}": message_id "${message_id}" not found.`);
         }
         return messages.slice(0, target_index + 1);
     }
     /**
      * 返回供受托管 plugin 使用的 session 端口。
      */
-    getRuntimePort() {
+    get_runtime_port() {
         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),
@@ -451,15 +513,15 @@ export class Session {
             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;
@@ -467,24 +529,26 @@ export class Session {
     /**
      * 在执行前确保 session 已完成初始化与宿主装配。
      */
-    async ensureReadyForExecution() {
+    async ensure_ready_for_execution() {
         await this.initialize_instruction();
         await this.state.ensure_ready_for_execution();
     }
     create_fork_session(session_id) {
         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,
         });
     }
@@ -496,18 +560,14 @@ export class Session {
      * - 子类仍可覆盖该方法，接管更特殊的子会话创建逻辑。
      */
     create_child_session(options) {
-        const SessionClass = this.constructor;
-        return new SessionClass(options);
+        const session_class = this.constructor;
+        return new session_class(options);
     }
     /** 恢复显式固化的完整 system snapshot；文件不存在时等待首次生成。 */
     async initialize_instruction() {
         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();
@@ -535,21 +595,12 @@ export class Session {
         }
         await this.instruction_initialize_promise;
     }
-    create_message_store() {
-        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),
-        });
-    }
     create_local_state() {
         return {
             session_config: {},
             effective_session_config: {},
             created_at: Date.now(),
-            timezone: resolveSystemTimezone(),
+            timezone: resolve_system_timezone(),
             initialize_promise: null,
             ensure_configured_promise: null,
         };
@@ -557,40 +608,47 @@ export class Session {
     /** 创建只依赖统一 Composer 的 Turn Executor。 */
     create_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),
         });
     }
     /** 为 Composer 创建当前 Step 的只读 Session 快照。 */
-    async create_compose_input(run_context, retry_count, refresh_system = false) {
+    async create_compose_input(turn_context, retry_count, refresh_system = false) {
         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)),
                 tools: Object.freeze({ ...this.tools }),
                 instruction_system_blocks,
@@ -601,20 +659,47 @@ export class Session {
             },
             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 身份快照。 */
+    create_compose_identity() {
+        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。 */
+    async compact_history(input) {
+        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 查询结果。 */
     async compose_for_view() {
-        const run_context = {
-            sessionId: this.id,
-            injectedUserMessages: [],
-            deferredPersistedUserMessages: [],
-            pendingAssistantFileParts: [],
-        };
-        const composed = await this.composer.compose(await this.create_compose_input(run_context, 0));
+        const composed = await this.composer.compose(await this.create_compose_input(undefined, 0));
         return this.apply_system_snapshot(composed);
     }
     /** 固定或应用当前 Session 的 system snapshot。 */
@@ -639,21 +724,18 @@ export class Session {
     }
     /** 把指定完整 system blocks 原子写入 instruction.md。 */
     async write_system_snapshot(blocks) {
-        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 压缩计划。 */
-    async commit_compaction_plan(plan, run_context) {
-        const action_id = `compacting:${this.id}:${generateId()}`;
+    async commit_compaction_plan(plan, turn_id) {
+        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({
@@ -667,7 +749,9 @@ export class Session {
                     ? `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();
         }
@@ -677,7 +761,9 @@ export class Session {
                 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;
         }
@@ -689,7 +775,7 @@ export class Session {
      */
     get_model() {
         const model = this.get_selected_model();
-        return model ? normalizeAgentModel(model) : undefined;
+        return model ? normalize_agent_model(model) : undefined;
     }
     /** 按 Session 优先、Agent 兜底规则读取当前配置的 AgentModel。 */
     get_selected_model() {
@@ -716,38 +802,12 @@ export class Session {
             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 故障反向改变已提交配置。 */
-    async emit_config_action_event(input) {
-        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 转为可展示文本。 */
 function stringify_system_content(content) {