@downcity/agent 1.1.408 → 1.1.437

package/bin/session/Session.js

@@ -4,28 +4,25 @@
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
  * - 对外保留稳定 Session facade，把状态、turn、view 逻辑下沉到独立 service。
- * - 内部使用 `SessionMessages` 统一管理 Active、Segment 与流式 Assistant 草稿。
+ * - 内部使用 `SessionMessages` 管理 SQLite 中的 canonical Message 聚合。
  */
 import { Executor } from "../executor/Executor.js";
-import { infer_agent_model_label, normalize_agent_model, read_agent_model_context_window, } from "../agent/AgentModel.js";
-import { SessionMessages } from "./SessionMessages.js";
-import { resolve_system_timezone } from "./storage/Metadata.js";
-import { create_runtime_session_port } from "./storage/RuntimeSessionPort.js";
-import { SessionEventHub } from "./runtime/SessionEventHub.js";
-import { create_session_compact_operation } from "./runtime/SessionCompactOperation.js";
-import { run_session_history_compaction } from "./runtime/SessionHistoryCompaction.js";
-import { create_session_plugin_execution_context } from "./runtime/SessionTurnContext.js";
-import { SessionState } from "./SessionState.js";
-import { SessionLoop } from "./SessionLoop.js";
-import { SessionQueue } from "./SessionQueue.js";
-import { SessionCommand } from "./SessionCommand.js";
-import { SessionInteractions } from "./control/SessionInteractions.js";
-import { SessionShellApprovalAdapter } from "./execution/tools/SessionShellApprovalAdapter.js";
-import { DefaultSessionComposer } from "./DefaultSessionComposer.js";
+import { read_model_context_window, read_model_label, } from "@downcity/type";
+import { SessionMessages } from "../session/SessionMessages.js";
+import { create_runtime_session_port } from "../session/storage/RuntimeSessionPort.js";
+import { SessionEventHub } from "../session/runtime/SessionEventHub.js";
+import { create_session_local_state, SessionState, } from "../session/SessionState.js";
+import { SessionLoop } from "../session/SessionLoop.js";
+import { SessionQueue } from "../session/SessionQueue.js";
+import { SessionInteractions } from "../session/control/SessionInteractions.js";
+import { SessionShellApprovalAdapter } from "../session/execution/tools/SessionShellApprovalAdapter.js";
+import { DefaultSessionComposer } from "../session/DefaultSessionComposer.js";
 import { generate_id } from "../utils/Id.js";
 import { nanoid } from "nanoid";
-import { build_session_info } from "./browse/Browse.js";
-import { ensure_session_title } from "./SessionTitle.js";
+import { build_session_info } from "../session/browse/Browse.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";
 /**
  * SDK 本地 Session。
  */
@@ -38,12 +35,14 @@ export class Session {
     origin;
     workspace_path;
     store;
-    get_session_store;
-    tools;
+    create_session_store;
+    register_forked_session;
+    get_tools;
     logger;
     get_managed_plugin_system_blocks;
     ensure_configured_hook;
     composer;
+    create_composer;
     session_messages;
     executor;
     events;
@@ -52,18 +51,12 @@ export class Session {
     local_state;
     get_workspace_env;
     get_agent_model;
-    get_agent_plugins;
+    get_hooks;
     get_instruction_system_blocks;
-    effective_instruction_system_blocks;
     /** 当前 Session 的一次性初始化任务，避免缓存实例被重复恢复运行时状态。 */
     initialize_promise = null;
-    instruction_initialize_promise = null;
-    effective_workspace_env;
-    effective_agent_plugins;
-    /** 当前 Session 首次生成后固定的完整 system snapshot。 */
-    system_snapshot_blocks = null;
-    /** 串行化 snapshot / syncshot 对 system 与 instruction.md 的修改。 */
-    system_mutation_chain = Promise.resolve();
+    /** 当前 Session 的 system snapshot 与 Step 组装边界。 */
+    session_composition;
     state;
     /** 当前 Session 独享的 Command FIFO。 */
     session_queue = new SessionQueue();
@@ -76,21 +69,19 @@ export class Session {
         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");
         }
@@ -103,7 +94,7 @@ export class Session {
         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);
@@ -117,14 +108,32 @@ export class Session {
             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
@@ -139,9 +148,12 @@ export class Session {
         });
         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,
@@ -158,50 +170,45 @@ export class Session {
         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(),
                 ]);
                 this.shell_approval_adapter.set_effective_mode(this.state.get_approval_mode());
             })();
         }
-        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;
     }
     /**
      * 把当前 Session 首次生成后固定的完整 system 显式固化到 instruction.md。
      *
      * 关键点（中文）
-     * - 包含 instruction、SDK core、plugin system 与 Session context。
+     * - 包含 instruction、SDK core、Plugin system 与 Session context。
      * - 多个 system block 按原顺序合并为一个 Markdown 文档。
      */
     async snapshot() {
-        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() {
-        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();
     }
     /**
      * 读取当前 session 配置快照。
@@ -270,7 +277,8 @@ export class Session {
                 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);
@@ -289,7 +297,7 @@ export class Session {
      * 追加一条新的 Session prompt。
      */
     async prompt(input) {
-        await this.initialize_instruction();
+        await this.session_composition.initialize();
         return await this.session_loop.prompt(input);
     }
     /**
@@ -298,81 +306,6 @@ export class Session {
     async stop() {
         return await this.session_loop.stop();
     }
-    /**
-     * 把一次显式历史压缩加入当前 Session 的有序输入队列。
-     */
-    async 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;
-    }
-    /** 把 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",
-            },
-        });
-    }
-    /** 把 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 的未来事件。
      */
@@ -404,52 +337,34 @@ export class Session {
      * 追加一条 user 文本消息。
      */
     async append_user_message(input) {
-        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) {
-        const appended = await this.session_messages.append_external_assistant_message({
+    async append_agent_message(input) {
+        await this.append_external_agent_message({
             text: String(input.text || "").trim(),
         });
-        if (appended)
-            await this.state.touch_metadata();
     }
     /**
      * 读取当前 session 详情。
      */
     async get_info() {
-        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 model_label = String(metadata_with_title.model_label ||
-            infer_agent_model_label(this.get_selected_model()) ||
+        const metadata = await this.store.read_metadata();
+        const model_label = String(metadata.model_label ||
+            read_model_label(this.get_selected_model()) ||
             "").trim();
         return build_session_info({
             project_root: this.workspace_path,
             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(),
         });
     }
@@ -463,20 +378,7 @@ export class Session {
      * 读取当前 session 生效的 system 快照。
      */
     async system() {
-        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();
     }
     /**
      * 返回当前 session 是否正在执行。
@@ -494,7 +396,12 @@ export class Session {
         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({
@@ -515,7 +422,9 @@ export class Session {
             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",
@@ -536,16 +445,8 @@ export class Session {
             throw error;
         }
     }
-    /** 截取 Fork 目标 Message 之前的历史，并按调用语义决定是否包含锚点。 */
-    resolve_fork_messages(messages, message_id, include_message) {
-        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() {
         if (this.runtime_port)
@@ -554,26 +455,13 @@ export class Session {
             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();
             },
@@ -588,26 +476,29 @@ export class Session {
      * 在执行前确保 session 已完成初始化与宿主装配。
      */
     async ensure_ready_for_execution() {
-        await this.initialize_instruction();
+        await this.session_composition.initialize();
         await this.state.ensure_ready_for_execution();
     }
     create_fork_session(session_id) {
         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,
         });
     }
     /**
@@ -621,223 +512,43 @@ export class Session {
         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 this.store.read_instruction();
-                if (persisted_instruction === null)
-                    return;
-                const instruction = persisted_instruction.trim();
-                this.system_snapshot_blocks = instruction
-                    ? [{
-                            source: "instruction",
-                            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",
-                                name: "agent",
-                                content: instruction,
-                            }]
-                        : []),
-                    ...stable_system_blocks,
-                ];
-            })();
-        }
-        await this.instruction_initialize_promise;
-    }
-    create_local_state() {
-        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。 */
     create_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(),
+            get_compose_input: async (turn_context, retry_count) => 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 快照。 */
-    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().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 身份快照。 */
-    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", {
+    /** 让 Composer 的 Context Policy 尝试推进派生上下文状态。 */
+    async recover_context(reason) {
+        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 查询结果。 */
-    async compose_for_view() {
-        const composed = await this.composer.compose(await this.create_compose_input(undefined, 0));
-        return this.apply_system_snapshot(composed);
-    }
-    /** 固定或应用当前 Session 的 system snapshot。 */
-    apply_system_snapshot(input) {
-        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",
-                content: block.content,
-            })),
-            system_blocks: this.system_snapshot_blocks.map((block) => ({ ...block })),
-        };
-    }
-    /** 串行执行一次 Session system 修改。 */
-    async run_system_mutation(operation) {
-        const next = this.system_mutation_chain.then(operation, operation);
-        this.system_mutation_chain = next.catch(() => undefined);
-        await next;
-    }
-    /** 把指定完整 system blocks 原子写入 instruction.md。 */
-    async write_system_snapshot(blocks) {
-        await this.store.write_instruction(blocks.map((block) => block.content).join("\n\n"));
-    }
-    /** 提交 Composer 生成的 Segment 压缩计划。 */
-    async commit_compaction_plan(plan, turn_id) {
-        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() {
-        const model = this.get_selected_model();
-        return model ? normalize_agent_model(model) : undefined;
+        return this.get_selected_model();
     }
-    /** 按 Session 优先、Agent 兜底规则读取当前配置的 AgentModel。 */
+    /** 按 Session 优先、Agent 兜底规则读取当前配置的 ModelClient。 */
     get_selected_model() {
         return (this.local_state.effective_session_config.model ||
             this.local_state.session_config.model ||
@@ -847,9 +558,20 @@ export class Session {
     get_model_context_window() {
         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()));
     }
-    /** 持久化并发布一条 canonical Action Message。 */
+    /** 追加外部 User Message，并统一触发 Metadata 与标题更新。 */
+    async append_external_user_message(input) {
+        const appended = await this.session_messages.append_external_user_message(input);
+        if (!appended)
+            return;
+        this.state.schedule_title_generation();
+    }
+    /** 追加外部 Assistant Message，并统一提交 Metadata。 */
+    async append_external_agent_message(input) {
+        await this.session_messages.append_external_agent_message(input);
+    }
+    /** 持久化并发布一条只包含 Action Part 的 canonical Agent Message。 */
     async emit_action_event(input) {
         const action_id = String(input.action_id || "").trim() ||
             `action:${this.id}:${Date.now()}`;
@@ -861,38 +583,6 @@ export class Session {
             ...(input.description ? { description: input.description } : {}),
             status: input.status,
         });
-        await this.state.touch_metadata();
     }
 }
-/** 把自定义 Composer 的 system content 转为可展示文本。 */
-function stringify_system_content(content) {
-    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) {
-    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",
-                name: `custom_system:${index + 1}`,
-                content,
-            }];
-    });
-}
 //# sourceMappingURL=Session.js.map