@downcity/agent 1.1.430 → 1.1.437

package/src/session/Session.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
  * - 对外保留稳定 Session facade，把状态、turn、view 逻辑下沉到独立 service。
- * - 内部使用 `SessionMessages` 统一管理 Active、Segment 与流式 Assistant 草稿。
+ * - 内部使用 `SessionMessages` 管理 SQLite 中的 canonical Message 聚合。
  */
 
 import { Executor } from "@executor/Executor.js";
@@ -25,7 +25,6 @@ import type {
   AgentSessionSystemSnapshot,
 } from "@/types/agent/SessionTypes.js";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
-import { resolve_system_timezone } from "@/session/storage/Metadata.js";
 import { create_runtime_session_port } from "@/session/storage/RuntimeSessionPort.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
 import type { SessionMutationSubscriber, SessionMutationUnsubscribe } from "@downcity/type";
@@ -38,37 +37,37 @@ import type {
 import type { ListSessionMessagesInput, SessionMessagePage } from "@downcity/type";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
-import type { AgentSessionCompactHandle } from "@/types/sdk/AgentSessionCompact.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
-import { create_session_compact_operation } from "@/session/runtime/SessionCompactOperation.js";
-import { run_session_history_compaction } from "@/session/runtime/SessionHistoryCompaction.js";
-import { SessionState } from "@/session/SessionState.js";
+import {
+  create_session_local_state,
+  SessionState,
+} from "@/session/SessionState.js";
 import { SessionLoop } from "@/session/SessionLoop.js";
 import { SessionQueue } from "@/session/SessionQueue.js";
-import { SessionCommand } from "@/session/SessionCommand.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
 import type { SessionOptions } from "@/types/session/SessionOptions.js";
 import type { SessionHookRuntime } from "@downcity/type";
 import { SessionInteractions } from "@/session/control/SessionInteractions.js";
 import { SessionShellApprovalAdapter } from "@/session/execution/tools/SessionShellApprovalAdapter.js";
 import { DefaultSessionComposer } from "@/session/DefaultSessionComposer.js";
-import type {
-  SessionComposer,
-  SessionCompactionPlan,
-} from "@/types/session/SessionComposer.js";
-import type { SessionCompactHistory } from "@/types/session/SessionExecution.js";
+import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import { generate_id } from "@/utils/Id.js";
 import { nanoid } from "nanoid";
 import { build_session_info } from "@/session/browse/Browse.js";
-import { ensure_session_title } from "@/session/SessionTitle.js";
-import type { SessionMessage } from "@downcity/type";
 import type { SessionActionEventInput } from "@downcity/type";
-import type { SessionCommandOptions } from "@/types/session/SessionCommand.js";
-import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
+import type {
+  AppendExternalSessionAgentMessageInput,
+  AppendExternalSessionUserMessageInput,
+} from "@/types/session/SessionMessages.js";
 import { SessionComposition } from "@/session/SessionComposition.js";
-import { relocate_fork_message_files } from "@/session/messages/SessionForkMessageFiles.js";
+import {
+  relocate_fork_message_files,
+  resolve_session_fork_messages,
+} from "@/session/messages/SessionForkMessageFiles.js";
 import { create_session_model_request_warning } from "@/session/runtime/SessionModelRequestWarning.js";
+import type { SessionContextRecoveryReason } from "@/types/session/SessionContextPolicy.js";
 
 /**
  * SDK 本地 Session。
@@ -82,14 +81,15 @@ export class Session implements AgentSession {
   readonly origin: SessionOptions["origin"];
 
   private readonly workspace_path: string;
-  private readonly store: SessionDataStore;
-  private readonly get_session_store: SessionOptions["get_session_store"];
+  private readonly store: SessionStorage;
+  private readonly create_session_store: SessionOptions["create_session_store"];
   private readonly register_forked_session: SessionOptions["register_forked_session"];
   private readonly get_tools: SessionOptions["get_tools"];
   private readonly logger: SessionOptions["logger"];
   private readonly get_managed_plugin_system_blocks: SessionOptions["get_managed_plugin_system_blocks"];
   private readonly ensure_configured_hook?: SessionOptions["ensure_configured"];
   private readonly composer: SessionComposer;
+  private readonly create_composer: () => SessionComposer;
   private readonly session_messages: SessionMessages;
   private readonly executor: Executor;
   private readonly events: SessionEventHub;
@@ -118,7 +118,7 @@ export class Session implements AgentSession {
     this.origin = options.origin;
     this.workspace_path = String(options.workspace_path || "").trim();
     this.store = options.store;
-    this.get_session_store = options.get_session_store;
+    this.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;
@@ -128,7 +128,9 @@ export class Session implements AgentSession {
     this.get_instruction_system_blocks = options.get_instruction_system_blocks;
     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");
     }
@@ -142,7 +144,7 @@ export class Session implements AgentSession {
     this.events = new SessionEventHub();
     this.session_messages = new SessionMessages({
       session_id: this.id,
-      store: this.store.messages,
+      store: this.store,
       attachment_store: this.store.attachments,
       publish: (mutation) => {
         this.events.publish(mutation);
@@ -156,14 +158,13 @@ export class Session implements AgentSession {
       session_id: this.id,
       interactions: this.session_interactions,
     });
-    this.local_state = this.create_local_state();
+    this.local_state = create_session_local_state();
     this.session_composition = new SessionComposition({
       agent_id: this.agent_id,
       session_id: this.id,
       session_origin: this.origin,
       workspace_path: this.workspace_path,
       store: this.store,
-      messages: this.session_messages,
       composer: this.composer,
       get_tools: this.get_tools,
       instruction_system_blocks: options.instruction_system_blocks,
@@ -183,7 +184,6 @@ export class Session implements AgentSession {
       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
@@ -201,7 +201,9 @@ export class Session implements AgentSession {
       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,
@@ -228,7 +230,15 @@ export class Session implements AgentSession {
         );
       })();
     }
-    await this.initialize_promise;
+    const initialize_promise = this.initialize_promise;
+    try {
+      await initialize_promise;
+    } catch (error) {
+      if (this.initialize_promise === initialize_promise) {
+        this.initialize_promise = null;
+      }
+      throw error;
+    }
     return this;
   }
 
@@ -330,7 +340,8 @@ export class Session implements AgentSession {
           publish_mutation,
         }
       : undefined;
-    this.enqueue_command({
+    this.session_loop.enqueue_command({
+      kind: "maintenance",
       execute: async () => {
         if (model_result) this.state.apply_model_config(model_result.config);
         if (security_changed && next_approval_mode) {
@@ -361,57 +372,6 @@ export class Session implements AgentSession {
     return await this.session_loop.stop();
   }
 
-  /**
-   * 把一次显式历史压缩加入当前 Session 的有序输入队列。
-   */
-  async compact(): Promise<AgentSessionCompactHandle> {
-    await this.state.ensure_runnable();
-    const compact_id = `compact:${this.id}:${generate_id()}`;
-    const operation = create_session_compact_operation({
-      compact_id,
-      run: async () => await this.session_loop.compact_history(compact_id),
-      log_error: async (error_message) => {
-        await this.logger.log("warn", "[agent] session compact command failed", {
-          session_id: this.id,
-          compact_id,
-          error: error_message,
-        });
-      },
-      publish_finish: (final_result) => {
-        this.events.publish({
-          mutation_id: nanoid(),
-          variant: "compact",
-          type: "finish",
-          session_id: this.id,
-          compact_id,
-          status: final_result.success ? "completed" : "failed",
-          compacted: final_result.compacted,
-          reason: final_result.reason,
-          created_at: Date.now(),
-          ...(final_result.error ? { error: final_result.error } : {}),
-        });
-      },
-    });
-    this.enqueue_command({
-      execute: operation.execute,
-    });
-    this.events.publish({
-      mutation_id: nanoid(),
-      variant: "compact",
-      type: "start",
-      session_id: this.id,
-      compact_id,
-      status: "queued",
-      created_at: Date.now(),
-    });
-    return operation.handle;
-  }
-
-  /** 创建一个具体 Session Command 对象并加入当前 FIFO。 */
-  private enqueue_command(options: SessionCommandOptions): void {
-    this.session_queue.enqueue_command(new SessionCommand(options));
-  }
-
   /**
    * 订阅当前 Session 的未来事件。
    */
@@ -451,44 +411,29 @@ export class Session implements AgentSession {
   async append_user_message(input: {
     text: string;
   }): Promise<void> {
-    const appended = await this.session_messages.append_external_user_message({
+    await this.append_external_user_message({
       text: String(input.text || "").trim(),
     });
-    if (!appended) return;
-    this.state.touch_metadata_in_background();
-    this.state.schedule_title_generation();
   }
 
   /**
-   * 追加一条 assistant 文本消息。
+   * 追加一条 Agent 文本消息。
    */
-  async append_assistant_message(input: {
+  async append_agent_message(input: {
     text: string;
   }): Promise<void> {
-    const appended = await this.session_messages.append_external_assistant_message({
+    await this.append_external_agent_message({
       text: String(input.text || "").trim(),
     });
-    if (appended) await this.state.touch_metadata();
   }
 
   /**
    * 读取当前 session 详情。
    */
   async get_info(): Promise<AgentSessionInfo> {
-    const [metadata, snapshot] = await Promise.all([
-      this.store.read_metadata(),
-      this.session_messages.context_snapshot(),
-    ]);
-    const metadata_with_title = metadata.title
-      ? metadata
-      : await ensure_session_title({
-          session_id: this.id,
-          store: this.store,
-          messages: snapshot.messages,
-          logger: this.logger,
-        });
+    const metadata = await this.store.read_metadata();
     const model_label = String(
-      metadata_with_title.model_label ||
+      metadata.model_label ||
       read_model_label(this.get_selected_model()) ||
       "",
     ).trim();
@@ -497,10 +442,9 @@ export class Session implements AgentSession {
       agent_id: this.agent_id,
       session_id: this.id,
       metadata: {
-        ...metadata_with_title,
+        ...metadata,
         ...(model_label ? { model_label } : {}),
       },
-      messages: snapshot.messages,
       executing: this.is_executing(),
     });
   }
@@ -536,7 +480,12 @@ export class Session implements AgentSession {
     const include_message = typeof input === "string" || input?.include_message !== false;
     const messages = await this.session_messages.list_history_messages();
     const fork_messages = message_id
-      ? this.resolve_fork_messages(messages, message_id, include_message)
+      ? resolve_session_fork_messages({
+          session_id: this.id,
+          messages,
+          message_id,
+          include_message,
+        })
       : messages;
     const action_id = `history-forking:${this.id}:${Date.now()}:${nanoid(8)}`;
     await this.emit_action_event({
@@ -582,23 +531,6 @@ export class Session implements AgentSession {
     }
   }
 
-  /** 截取 Fork 目标 Message 之前的历史，并按调用语义决定是否包含锚点。 */
-  private resolve_fork_messages(
-    messages: SessionMessage[],
-    message_id: string,
-    include_message: boolean,
-  ): SessionMessage[] {
-    const target_index = messages.findIndex(
-      (message) => message.message_id === message_id,
-    );
-    if (target_index < 0) {
-      throw new Error(
-        `Cannot fork session "${this.id}": message_id "${message_id}" not found.`,
-      );
-    }
-    return messages.slice(0, include_message ? target_index + 1 : target_index);
-  }
-
   /**
    * 返回供宿主运行时使用的 Session 端口。
    */
@@ -608,26 +540,15 @@ export class Session implements AgentSession {
       session_id: this.id,
       get_model: () => this.get_model(),
       get_executor: () => this.executor,
+      messages: async () => await this.session_messages.list_history_messages(),
       prompt: async (input) => await this.prompt(input),
       stop: async () => await this.stop(),
       subscribe: (subscriber) => this.subscribe(subscriber),
-      append_user_message: async (message_params) => {
-        const appended = await this.session_messages.append_external_user_message(
-          message_params,
-        );
-        if (!appended) return;
-        this.state.touch_metadata_in_background();
-        this.state.schedule_title_generation();
-      },
-      append_assistant_message: async (message_params) => {
-        const appended = await this.session_messages.append_external_assistant_message({
-          parts: message_params.parts,
-          text: message_params.text,
-        });
-        if (appended) await this.state.touch_metadata();
-      },
+      append_user_message: async (message_params) =>
+        await this.append_external_user_message(message_params),
+      append_agent_message: async (message_params) =>
+        await this.append_external_agent_message(message_params),
       is_executing: () => this.is_executing(),
-      context: async () => await this.session_messages.context_snapshot(),
       ensure_ready_for_execution: async () => {
         await this.ensure_ready_for_execution();
       },
@@ -654,8 +575,8 @@ export class Session implements AgentSession {
       workspace_path: this.workspace_path,
       ...(this.workspace_id ? { workspace_id: this.workspace_id } : {}),
       origin: this.origin,
-      store: this.get_session_store(session_id),
-      get_session_store: this.get_session_store,
+      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,
       get_tools: this.get_tools,
@@ -667,7 +588,7 @@ export class Session implements AgentSession {
       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,
     });
   }
 
@@ -685,18 +606,6 @@ export class Session implements AgentSession {
     return new session_class(options) as this;
   }
 
-  private create_local_state(): SessionLocalState {
-    return {
-      session_config: {},
-      effective_session_config: {},
-      configured_approval_mode: "ask",
-      created_at: Date.now(),
-      timezone: resolve_system_timezone(),
-      initialize_promise: null,
-      ensure_configured_promise: null,
-    };
-  }
-
   /** 创建只依赖统一 Composer 的 Turn Executor。 */
   private create_executor(): Executor {
     return new Executor({
@@ -707,91 +616,32 @@ export class Session implements AgentSession {
           turn_context,
           retry_count,
         ),
-      compact_history: async (input) => await this.compact_history(input),
-      get_model: () => this.get_model(),
+      recover_context: async (reason) => await this.recover_context(reason),
       logger: this.logger,
       get_hooks: () => this.get_hooks(),
       apply_system_snapshot: (input) => this.session_composition.apply_snapshot(input),
     });
   }
 
-  /** 生成并提交 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.session_composition.compose_identity(),
-        model: this.get_model(),
-        history: await this.session_messages.context_snapshot(),
-        on_model_request_failure: (notice) => {
-          this.events.publish(create_session_model_request_warning({
-            session_id: this.id,
-            turn_id: input.turn_id,
-            notice,
-          }));
-        },
-      }),
-      commit_plan: async (plan) => {
-        await this.commit_compaction_plan(plan, input.turn_id);
-      },
-      log_error: async (error_message) => {
-        await this.logger.log("warn", "[agent] session history compaction failed", {
+  /** 让 Composer 的 Context Policy 尝试推进派生上下文状态。 */
+  private async recover_context(
+    reason: SessionContextRecoveryReason,
+  ): Promise<boolean> {
+    return await this.composer.recover_context({
+      session: this.session_composition.compose_identity(),
+      model: this.get_model(),
+      storage: this.store,
+      reason,
+      on_model_request_failure: (notice) => {
+        this.events.publish(create_session_model_request_warning({
           session_id: this.id,
-          ...(input.turn_id ? { turn_id: input.turn_id } : {}),
-          error: error_message,
-        });
+          turn_id: this.session_loop.current_turn_id(),
+          notice,
+        }));
       },
     });
   }
 
-  /** 提交 Composer 生成的 Segment 压缩计划。 */
-  private async commit_compaction_plan(
-    plan: SessionCompactionPlan,
-    turn_id?: string,
-  ): Promise<void> {
-    const action_id = `compacting:${this.id}:${generate_id()}`;
-    await this.emit_action_event({
-      action_id,
-      action_type: "history-compaction",
-      title: "Compacting session messages",
-      status: "running",
-      ...(turn_id
-        ? { turn_id }
-        : {}),
-    });
-    try {
-      await this.session_messages.compact_active({
-        through_sequence: plan.through_sequence,
-        summary: plan.summary,
-      });
-      await this.emit_action_event({
-        action_id,
-        action_type: "history-compaction",
-        title: "Session messages compacted",
-        description: `Closed Active through Message ${plan.boundary_message_id}.`,
-        status: "completed",
-        ...(turn_id
-          ? { turn_id }
-          : {}),
-      });
-      await this.state.touch_metadata();
-    } catch (error) {
-      await this.emit_action_event({
-        action_id,
-        action_type: "history-compaction",
-        title: "Session messages compact failed",
-        description: error instanceof Error ? error.message : String(error),
-        status: "failed",
-        ...(turn_id
-          ? { turn_id }
-          : {}),
-      });
-      throw error;
-    }
-  }
-
   /**
    * 返回当前 Session 实际使用的模型实例。
    *
@@ -819,7 +669,27 @@ export class Session implements AgentSession {
     );
   }
 
-  /** 持久化并发布一条 canonical Action Message。 */
+  /** 追加外部 User Message，并统一触发 Metadata 与标题更新。 */
+  private async append_external_user_message(
+    input: AppendExternalSessionUserMessageInput,
+  ): Promise<void> {
+    const appended = await this.session_messages.append_external_user_message(
+      input,
+    );
+    if (!appended) return;
+    this.state.schedule_title_generation();
+  }
+
+  /** 追加外部 Assistant Message，并统一提交 Metadata。 */
+  private async append_external_agent_message(
+    input: AppendExternalSessionAgentMessageInput,
+  ): Promise<void> {
+    await this.session_messages.append_external_agent_message(
+      input,
+    );
+  }
+
+  /** 持久化并发布一条只包含 Action Part 的 canonical Agent Message。 */
   private async emit_action_event(input: SessionActionEventInput): Promise<void> {
     const action_id = String(input.action_id || "").trim() ||
       `action:${this.id}:${Date.now()}`;
@@ -831,7 +701,6 @@ export class Session implements AgentSession {
       ...(input.description ? { description: input.description } : {}),
       status: input.status,
     });
-    await this.state.touch_metadata();
   }
 
 }