@downcity/agent 1.1.408 → 1.1.437

package/src/agent/AgentSessions.ts

@@ -3,13 +3,12 @@
  *
  * 关键点（中文）
  * - 统一管理 session 缓存、创建、恢复、默认配置注入与列表查询。
- * - 该服务只负责 session 生命周期与查询，不负责 plugin / RPC 启停。
+ * - 该服务只负责 Session 生命周期与查询，不负责 Plugin / RPC 启停。
  * - Session 对象创建细节集中在这里，避免 facade 和 lifecycle 重复依赖 Session 构造逻辑。
  */
 
 import { nanoid } from "nanoid";
-import type { RuntimeTool as Tool } from "@downcity/type";
-import type { AgentModel } from "@/agent/AgentModel.js";
+import type { ModelClient, RuntimeTool as Tool } from "@downcity/type";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type {
   AgentCreateSessionInput,
@@ -30,11 +29,15 @@ import type {
 import type { AgentManagedSession } from "@/types/session/SessionOptions.js";
 import { Session } from "@/session/Session.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
+import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import { create_instruction_system_blocks } from "@/agent/AgentInstructions.js";
-import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
+import { DefaultSessionComposer } from "@/session/DefaultSessionComposer.js";
+import type { SessionHookRuntime } from "@downcity/type";
 import type { SessionStore } from "@/types/store/SessionStore.js";
-import type { WorkspaceBase } from "@downcity/workspace";
-import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
+import type { WorkspaceRuntime } from "@downcity/type";
+import type { SessionOrigin } from "@downcity/type";
+import { normalize_session_origin, normalize_session_origin_type } from "@downcity/type";
 
 type AgentSessionsOptions = {
   /**
@@ -48,13 +51,13 @@ type AgentSessionsOptions = {
    * AgentSessions 是 Agent 唯一的 Session 集合；Workspace 相关能力不能
    * 固定在集合实例上，而应在创建或恢复单个 Session 时解析。
    */
-  resolve_session_context: (workspace?: WorkspaceBase) => {
+  resolve_session_context: (workspace?: WorkspaceRuntime) => {
     workspace_path: string;
     workspace_id?: string;
     logger: Logger;
-    tools: Record<string, Tool>;
+    get_tools: () => Record<string, Tool>;
     get_workspace_env: () => Record<string, string>;
-    get_agent_plugins: () => AgentPluginExecutionRuntime;
+    get_hooks: () => SessionHookRuntime;
     store: SessionStore;
   };
 
@@ -78,8 +81,11 @@ type AgentSessionsOptions = {
    */
   session_class?: AgentSessionConstructor;
 
+  /** 为每个 Session 创建独立 Composer 的工厂。 */
+  create_session_composer?: () => SessionComposer;
+
   /** 读取 Agent 当前持有的运行时模型实例。 */
-  get_agent_model: () => AgentModel | undefined;
+  get_agent_model: () => ModelClient | undefined;
 
   /** Session 创建或恢复后的内部路由登记回调。 */
   on_session_routed?: (session_id: string, sessions: AgentSessions) => void;
@@ -95,6 +101,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   private readonly get_instruction: AgentSessionsOptions["get_instruction"];
   private readonly ensure_agent_ready: AgentSessionsOptions["ensure_agent_ready"];
   private readonly session_class: AgentSessionConstructor;
+  private readonly create_session_composer: () => SessionComposer;
   private readonly get_agent_model: AgentSessionsOptions["get_agent_model"];
   private readonly on_session_routed?: AgentSessionsOptions["on_session_routed"];
   private readonly sessions_by_id = new Map<string, AgentManagedSession>();
@@ -106,6 +113,8 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     this.get_instruction = options.get_instruction;
     this.ensure_agent_ready = options.ensure_agent_ready;
     this.session_class = options.session_class || Session;
+    this.create_session_composer = options.create_session_composer ||
+      (() => new DefaultSessionComposer());
     this.get_agent_model = options.get_agent_model;
     this.on_session_routed = options.on_session_routed;
   }
@@ -117,12 +126,16 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     return [...this.sessions_by_id.values()];
   }
 
-  /** 返回当前所有执行中的 Session 标识；可按 Workspace 限定。 */
-  list_executing_session_ids(workspace_id?: string): string[] {
+  /** 返回当前所有执行中的 Session 标识；可按 Workspace 与来源分区限定。 */
+  list_executing_session_ids(workspace_id?: string, origin_type?: string): string[] {
+    const resolved_origin_type = origin_type
+      ? normalize_session_origin_type(origin_type)
+      : undefined;
     return this.list_cached_sessions()
       .filter((session) =>
         session.is_executing()
         && (!workspace_id || session.workspace_id === workspace_id)
+        && (!resolved_origin_type || session.origin.type === resolved_origin_type)
       )
       .map((session) => session.id);
   }
@@ -149,50 +162,21 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     }
   }
 
-  /**
-   * 把 Agent env 修改广播到已有 Session 的统一输入队列。
-   */
-  broadcast_env(env: Record<string, string>, command_id: string, workspace_id?: string): void {
-    for (const session of this.sessions_by_id.values()) {
-      if (workspace_id && session.workspace_id !== workspace_id) continue;
-      session.enqueue_workspace_env({
-        command_id,
-        env: { ...env },
-      });
-    }
-  }
-
-  /**
-   * 把 Plugin registry 修改广播到已有 Session 的统一输入队列。
-   */
-  broadcast_plugins(input: {
-    command_id: string;
-    title: string;
-    plugins: AgentPluginExecutionRuntime;
-    workspace_id?: string;
-  }): void {
-    for (const session of this.sessions_by_id.values()) {
-      if (input.workspace_id && session.workspace_id !== input.workspace_id) continue;
-      session.enqueue_agent_plugins({
-        command_id: input.command_id,
-        title: input.title,
-        plugins: input.plugins,
-      });
-    }
-  }
-
   /**
    * 获取已缓存 Session 的 runtime port。
    *
    * runtime 是执行层的内部投影，不负责创建 Session。需要创建时必须
    * 通过 `create()` 获取内部生成的 ID；需要恢复时必须先调用 `get()`。
    */
-  runtime(session_id: string): SessionPort {
+  runtime(session_id: string, origin_type = "chat"): SessionPort {
     const resolved_session_id = String(session_id || "").trim();
-    const session = this.sessions_by_id.get(resolved_session_id);
+    const resolved_origin_type = normalize_session_origin_type(origin_type);
+    const session = this.sessions_by_id.get(
+      this.session_cache_key(resolved_session_id, resolved_origin_type),
+    );
     if (!session) {
       throw new Error(
-        `Session "${resolved_session_id}" is not loaded; call sessions.get(session_id) first`,
+        `Session "${resolved_session_id}" is not loaded from origin "${resolved_origin_type}"; call sessions.get(session_id, origin_type) first`,
       );
     }
     return session.get_runtime_port();
@@ -202,11 +186,20 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
    * 新建一个 session。
    */
   async create(
-    input?: AgentCreateSessionInput & { workspace?: WorkspaceBase; origin?: SessionOrigin },
+    input?: AgentCreateSessionInput & { workspace?: WorkspaceRuntime },
   ): Promise<AgentSession> {
+    const origin = normalize_session_origin(input?.origin);
+    const session_id = `session-${Date.now()}-${nanoid(8)}`;
+    const context = this.resolve_session_context(input?.workspace);
     const session = this.get_or_create_session({
+      session_id,
       workspace: input?.workspace,
-      origin: input?.origin,
+      origin,
+      storage: context.store.create_session(
+        session_id,
+        origin,
+        context.workspace_id,
+      ),
     });
     this.on_session_routed?.(session.id, this);
     await session.initialize();
@@ -218,25 +211,30 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
    */
   async get(
     session_id: string,
-    input?: { workspace?: WorkspaceBase; origin?: SessionOrigin },
+    origin_type = "chat",
+    input?: { workspace?: WorkspaceRuntime },
   ): Promise<AgentSession> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
       throw new Error("sessions.get requires a non-empty session_id");
     }
-    const store = this.resolve_session_context(input?.workspace).store;
+    const resolved_origin_type = normalize_session_origin_type(origin_type);
+    const cache_key = this.session_cache_key(resolved_session_id, resolved_origin_type);
+    const context = this.resolve_session_context(input?.workspace);
+    const store = context.store;
     if (
-      !this.sessions_by_id.has(resolved_session_id) &&
-      !(await store.has_session(resolved_session_id))
+      !this.sessions_by_id.has(cache_key) &&
+      !(await store.has_session(resolved_session_id, resolved_origin_type))
     ) {
-      throw new Error(`Session "${resolved_session_id}" not found`);
+      throw new Error(
+        `Session "${resolved_session_id}" not found in origin "${resolved_origin_type}"`,
+      );
     }
-    const persisted_metadata = await store
-      .session(resolved_session_id, input?.workspace?.id)
-      .read_metadata();
+    const storage = await store.open_session(resolved_session_id, resolved_origin_type);
+    const persisted_metadata = await storage.read_metadata();
     const persisted_workspace_id = String(persisted_metadata.workspace_id || "").trim() || undefined;
     const persisted_origin = persisted_metadata.origin;
-    const cached = this.sessions_by_id.get(resolved_session_id);
+    const cached = this.sessions_by_id.get(cache_key);
     const requested_workspace_id = String(input?.workspace?.id || "").trim() || undefined;
     if (persisted_workspace_id !== requested_workspace_id) {
       throw new Error(
@@ -250,13 +248,11 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
         `Session "${resolved_session_id}" is already bound to Workspace "${cached.workspace_id || ""}"`,
       );
     }
-    if (input?.origin && JSON.stringify(persisted_origin || { type: "user" }) !== JSON.stringify(input.origin)) {
-      throw new Error(`Session "${resolved_session_id}" has a different origin`);
-    }
     const session = this.get_or_create_session({
       session_id: resolved_session_id,
       workspace: input?.workspace,
-      origin: input?.origin || persisted_origin,
+      origin: persisted_origin,
+      storage,
     });
     this.on_session_routed?.(resolved_session_id, this);
     await session.initialize();
@@ -270,36 +266,46 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
    * - 正在执行的 Session 会先停止，避免删除后继续写入。
    * - 该方法不处理任何 Plugin 自有数据。
    */
-  async remove(session_id: string): Promise<boolean> {
+  async remove(session_id: string, origin_type = "chat"): Promise<boolean> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
       throw new Error("sessions.remove requires a non-empty session_id");
     }
-    const cached = this.sessions_by_id.get(resolved_session_id);
+    const resolved_origin_type = normalize_session_origin_type(origin_type);
+    const cache_key = this.session_cache_key(resolved_session_id, resolved_origin_type);
+    const cached = this.sessions_by_id.get(cache_key);
     if (cached?.is_executing()) {
       await cached.stop();
     }
     cached?.dispose_title_generation?.();
-    const existed = await this.resolve_session_context().store.remove_session(resolved_session_id);
-    this.sessions_by_id.delete(resolved_session_id);
+    const existed = await this.resolve_session_context().store.remove_session(
+      resolved_session_id,
+      resolved_origin_type,
+    );
+    this.sessions_by_id.delete(cache_key);
     return existed;
   }
 
   /**
    * 清空一个 Session 的消息目录。
    */
-  async clear_messages(session_id: string): Promise<boolean> {
+  async clear_messages(session_id: string, origin_type = "chat"): Promise<boolean> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
       throw new Error("sessions.clear_messages requires a non-empty session_id");
     }
-    const cached = this.sessions_by_id.get(resolved_session_id);
+    const resolved_origin_type = normalize_session_origin_type(origin_type);
+    const cache_key = this.session_cache_key(resolved_session_id, resolved_origin_type);
+    const cached = this.sessions_by_id.get(cache_key);
     if (cached?.is_executing()) {
       throw new Error(`Session "${resolved_session_id}" is currently executing`);
     }
     cached?.dispose_title_generation?.();
-    const existed = await this.resolve_session_context().store.clear_session_messages(resolved_session_id);
-    this.sessions_by_id.delete(resolved_session_id);
+    const existed = await this.resolve_session_context().store.clear_session_messages(
+      resolved_session_id,
+      resolved_origin_type,
+    );
+    this.sessions_by_id.delete(cache_key);
     return existed;
   }
 
@@ -309,9 +315,10 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   async list(
     input?: AgentListSessionsInput,
   ): Promise<AgentSessionSummaryPage> {
+    const origin_type = normalize_session_origin_type(input?.origin_type ?? "chat");
     return await this.resolve_session_context().store.list_sessions(
-      input,
-      new Set(this.list_executing_session_ids()),
+      { ...(input || {}), origin_type },
+      new Set(this.list_executing_session_ids(undefined, origin_type)),
     );
   }
 
@@ -325,15 +332,17 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     if (!session_id) {
       throw new Error("sessions.archive requires a non-empty id");
     }
+    const origin_type = normalize_session_origin_type(input.origin_type ?? "chat");
+    const cache_key = this.session_cache_key(session_id, origin_type);
 
-    const executing_session_ids = new Set(this.list_executing_session_ids());
-    if (executing_session_ids.has(session_id)) {
+    const cached = this.sessions_by_id.get(cache_key);
+    if (cached?.is_executing()) {
       throw new Error(`Session "${session_id}" is currently executing`);
     }
 
-    const result = await this.resolve_session_context().store.archive_session(session_id);
-    this.sessions_by_id.get(session_id)?.dispose_title_generation?.();
-    this.sessions_by_id.delete(session_id);
+    const result = await this.resolve_session_context().store.archive_session(session_id, origin_type);
+    cached?.dispose_title_generation?.();
+    this.sessions_by_id.delete(cache_key);
     return result;
   }
 
@@ -353,20 +362,66 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     return await this.resolve_session_context().store.clean_archive();
   }
 
+  /**
+   * 把 Session 重新绑定到另一个 Workspace。
+   *
+   * 关键点（中文）
+   * - 只改写 session_state 中的 workspace_id 并清掉运行时缓存；
+   * - 之后用新 Workspace 恢复时不再触发严格的 workspace 归属校验。
+   */
+  async workspace(
+    session_id: string,
+    workspace: WorkspaceRuntime,
+  ): Promise<AgentSession> {
+    const resolved_session_id = String(session_id || "").trim();
+    if (!resolved_session_id) {
+      throw new Error("sessions.workspace requires a non-empty session_id");
+    }
+    const resolved_origin_type = normalize_session_origin_type("chat");
+    const cache_key = this.session_cache_key(resolved_session_id, resolved_origin_type);
+    const cached = this.sessions_by_id.get(cache_key);
+    if (cached?.is_executing()) {
+      throw new Error(`Session "${resolved_session_id}" is currently executing`);
+    }
+    const context = this.resolve_session_context(workspace);
+    if (!(await context.store.has_session(resolved_session_id, resolved_origin_type))) {
+      throw new Error(`Session "${resolved_session_id}" not found`);
+    }
+    const store = await context.store.open_session(
+      resolved_session_id,
+      resolved_origin_type,
+    );
+    const metadata = await store.read_metadata();
+    if (metadata.agent_id !== this.agent_id) {
+      throw new Error(`Session "${resolved_session_id}" belongs to another Agent`);
+    }
+    await store.write_metadata({
+      ...metadata,
+      workspace_id: context.workspace_id,
+    });
+    this.sessions_by_id.delete(cache_key);
+    cached?.dispose_title_generation?.();
+    return await this.get(resolved_session_id, resolved_origin_type, { workspace });
+  }
+
   private get_or_create_session(input?: {
     /**
      * 可选指定 session id。
      */
     session_id?: string;
     /** 当前 Session 可选使用的 Workspace。 */
-    workspace?: WorkspaceBase;
+    workspace?: WorkspaceRuntime;
     /** 当前 Session 的创建来源。 */
     origin?: SessionOrigin;
+    /** 已由集合层创建或打开的单 Session Storage。 */
+    storage?: SessionStorage;
   }): AgentManagedSession {
-    const resolved_session_id =
-      String(input?.session_id || "").trim() ||
-      `session-${Date.now()}-${nanoid(8)}`;
-    const cached = this.sessions_by_id.get(resolved_session_id);
+    const resolved_session_id = String(
+      input?.session_id || input?.storage?.session_id || "",
+    ).trim() || `session-${Date.now()}-${nanoid(8)}`;
+    const origin = normalize_session_origin(input?.origin);
+    const cache_key = this.session_cache_key(resolved_session_id, origin.type);
+    const cached = this.sessions_by_id.get(cache_key);
     if (cached) return cached;
 
     const context = this.resolve_session_context(input?.workspace);
@@ -374,26 +429,47 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       agent_id: this.agent_id,
       workspace_path: context.workspace_path,
       ...(context.workspace_id ? { workspace_id: context.workspace_id } : {}),
-      ...(input?.origin ? { origin: input.origin } : {}),
-      store: context.store.session(resolved_session_id, context.workspace_id),
-      get_session_store: (session_id) => context.store.session(session_id, context.workspace_id),
+      origin,
+      store: input?.storage || context.store.create_session(resolved_session_id, origin, context.workspace_id),
+      create_session_store: (session_id) => context.store.create_session(session_id, origin, context.workspace_id),
+      register_forked_session: (session) => this.register_forked_session(session),
       session_id: resolved_session_id,
-      tools: context.tools,
+      get_tools: () => context.get_tools(),
       logger: context.logger,
       instruction_system_blocks: this.load_instruction_system_blocks(context.workspace_path),
       get_instruction_system_blocks: () => this.load_instruction_system_blocks(context.workspace_path),
       get_workspace_env: () => context.get_workspace_env(),
       get_agent_model: () => this.get_agent_model(),
-      get_agent_plugins: () => context.get_agent_plugins(),
+      get_hooks: () => context.get_hooks(),
       get_managed_plugin_system_blocks: async () => [],
+      create_composer: this.create_session_composer,
       ensure_configured: async (session) => {
         await this.ensure_agent_ready();
       },
     });
-    this.sessions_by_id.set(resolved_session_id, created);
+    this.sessions_by_id.set(cache_key, created);
     return created;
   }
 
+  /** 接管 fork 产生的 Session，确保后续读取与执行使用同一运行时实例。 */
+  private register_forked_session(session: AgentManagedSession): void {
+    if (session.agent_id !== this.agent_id) {
+      throw new Error(`Cannot register Session "${session.id}" for another Agent`);
+    }
+    const cache_key = this.session_cache_key(session.id, session.origin.type);
+    const cached = this.sessions_by_id.get(cache_key);
+    if (cached && cached !== session) {
+      throw new Error(`Session "${session.id}" already has another runtime instance`);
+    }
+    this.sessions_by_id.set(cache_key, session);
+    this.on_session_routed?.(session.id, this);
+  }
+
+  /** 返回来源分区内唯一的 Session 运行时缓存键。 */
+  private session_cache_key(session_id: string, origin_type: string): string {
+    return `${origin_type}\u0000${session_id}`;
+  }
+
   private load_instruction_system_blocks(workspace_path: string): AgentSessionSystemBlock[] {
     return create_instruction_system_blocks(
       this.get_instruction(),