@downcity/agent 1.1.438 → 1.1.446

package/src/agent/AgentSessions.ts

@@ -3,12 +3,12 @@
  *
  * 关键点（中文）
  * - 统一管理 session 缓存、创建、恢复、默认配置注入与列表查询。
- * - 该服务只负责 Session 生命周期与查询，不负责 Plugin / RPC 启停。
+ * - 该服务只负责 Session 生命周期与查询，不负责 Power / RPC 启停。
  * - Session 对象创建细节集中在这里，避免 facade 和 lifecycle 重复依赖 Session 构造逻辑。
  */
 
 import { nanoid } from "nanoid";
-import type { ModelClient, RuntimeTool as Tool } from "@downcity/type";
+import type { ModelClient, AgentTool as Tool } from "@downcity/type";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type {
   AgentCreateSessionInput,
@@ -31,8 +31,8 @@ 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 { DefaultSessionComposer } from "@/session/DefaultSessionComposer.js";
-import type { SessionHookRuntime } from "@downcity/type";
+import { DefaultSessionComposer } from "@/session/input/composer/DefaultSessionComposer.js";
+import type { ToolHookSet } from "@downcity/type";
 import type { SessionStore } from "@/types/store/SessionStore.js";
 import type { SessionStorage } from "@/types/store/SessionStorage.js";
 import type { WorkspaceRuntime } from "@downcity/type";
@@ -45,6 +45,16 @@ type AgentSessionsOptions = {
    */
   agent_id: string;
 
+  /**
+   * 当前 agent 用户可见名称；为空时回退到 agent_id。
+   */
+  agent_name: string;
+
+  /**
+   * 当前 agent 一句话能力描述；进入工具与扩展的调用环境。
+   */
+  agent_description: string;
+
   /**
    * 按 Session 解析执行上下文。
    *
@@ -57,7 +67,8 @@ type AgentSessionsOptions = {
     logger: Logger;
     get_tools: () => Record<string, Tool>;
     get_workspace_env: () => Record<string, string>;
-    get_hooks: () => SessionHookRuntime;
+    get_workspace: () => WorkspaceRuntime | undefined;
+    get_hooks: () => ToolHookSet;
     store: SessionStore;
   };
 
@@ -71,24 +82,16 @@ type AgentSessionsOptions = {
    */
   get_instruction: () => string[];
 
-  /**
-   * 等待当前 Agent 持有的长期运行时启动完成。
-   */
-  ensure_agent_ready: () => Promise<void>;
-
   /**
    * 当前 agent 使用的本地 Session 类。
    */
   session_class?: AgentSessionConstructor;
 
-  /** 为每个 Session 创建独立 Composer 的工厂。 */
-  create_session_composer?: () => SessionComposer;
+  /** 当前 Agent 使用的 Session Composer；其所有 Session 共享该实例。 */
+  session_composer?: SessionComposer;
 
   /** 读取 Agent 当前持有的运行时模型实例。 */
   get_agent_model: () => ModelClient | undefined;
-
-  /** Session 创建或恢复后的内部路由登记回调。 */
-  on_session_routed?: (session_id: string, sessions: AgentSessions) => void;
 };
 
 /**
@@ -96,27 +99,26 @@ type AgentSessionsOptions = {
  */
 export class AgentSessions implements AgentSessionsContract<AgentSession> {
   private readonly agent_id: string;
+  private readonly agent_name: string;
+  private readonly agent_description: string;
   private readonly resolve_session_context: AgentSessionsOptions["resolve_session_context"];
   private readonly logger: Logger;
   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 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>();
 
   constructor(options: AgentSessionsOptions) {
     this.agent_id = options.agent_id;
+    this.agent_name = options.agent_name;
+    this.agent_description = options.agent_description;
     this.resolve_session_context = options.resolve_session_context;
     this.logger = options.logger;
     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.session_composer = options.session_composer ?? new DefaultSessionComposer();
     this.get_agent_model = options.get_agent_model;
-    this.on_session_routed = options.on_session_routed;
   }
 
   /**
@@ -201,7 +203,6 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
         context.workspace_id,
       ),
     });
-    this.on_session_routed?.(session.id, this);
     await session.initialize();
     return session;
   }
@@ -254,7 +255,6 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       origin: persisted_origin,
       storage,
     });
-    this.on_session_routed?.(resolved_session_id, this);
     await session.initialize();
     return session;
   }
@@ -264,7 +264,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
    *
    * 关键点（中文）
    * - 正在执行的 Session 会先停止，避免删除后继续写入。
-   * - 该方法不处理任何 Plugin 自有数据。
+   * - 该方法不处理任何 Power 自有数据。
    */
   async remove(session_id: string, origin_type = "chat"): Promise<boolean> {
     const resolved_session_id = String(session_id || "").trim();
@@ -427,6 +427,8 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     const context = this.resolve_session_context(input?.workspace);
     const created = new this.session_class({
       agent_id: this.agent_id,
+      agent_name: this.agent_name,
+      agent_description: this.agent_description,
       workspace_path: context.workspace_path,
       ...(context.workspace_id ? { workspace_id: context.workspace_id } : {}),
       origin,
@@ -436,21 +438,41 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       session_id: resolved_session_id,
       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),
+      instruction_system_blocks: this.load_instruction_system_blocks(),
+      get_instruction_system_blocks: () => this.load_instruction_system_blocks(),
       get_workspace_env: () => context.get_workspace_env(),
+      get_workspace: () => context.get_workspace(),
       get_agent_model: () => this.get_agent_model(),
       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();
-      },
+      composer: this.session_composer,
     });
     this.sessions_by_id.set(cache_key, created);
     return created;
   }
 
+  /**
+   * 释放一个空闲 Session 的运行时实例。
+   *
+   * 关键点（中文）
+   * - 只释放内存实例；消息与元数据都在 Store 中，下次 `get()` 会重新恢复。
+   * - 正在执行的 Session 不释放：执行上下文与取消信号都在实例上，丢掉会让 Turn 失去归属。
+   * - 返回是否真的释放。调用方必须先自行解除对该实例的订阅，否则重新 `get()` 会拿到新实例
+   *   而旧订阅仍然挂在被丢弃的实例上。
+   */
+  release(session_id: string, origin_type = "chat"): boolean {
+    const resolved_session_id = String(session_id || "").trim();
+    if (!resolved_session_id) return false;
+    const cache_key = this.session_cache_key(
+      resolved_session_id,
+      normalize_session_origin_type(origin_type),
+    );
+    const cached = this.sessions_by_id.get(cache_key);
+    if (!cached || cached.is_executing()) return false;
+    cached.dispose_title_generation?.();
+    this.sessions_by_id.delete(cache_key);
+    return true;
+  }
+
   /** 接管 fork 产生的 Session，确保后续读取与执行使用同一运行时实例。 */
   private register_forked_session(session: AgentManagedSession): void {
     if (session.agent_id !== this.agent_id) {
@@ -462,7 +484,6 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       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 运行时缓存键。 */
@@ -470,11 +491,12 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     return `${origin_type}\u0000${session_id}`;
   }
 
-  private load_instruction_system_blocks(workspace_path: string): AgentSessionSystemBlock[] {
-    return create_instruction_system_blocks(
-      this.get_instruction(),
-      workspace_path,
-    );
+  private load_instruction_system_blocks(): AgentSessionSystemBlock[] {
+    return create_instruction_system_blocks({
+      agent_id: this.agent_id,
+      agent_name: this.agent_name,
+      instruction: this.get_instruction(),
+    });
   }
 
 }

package/src/group/Group.ts

@@ -2,7 +2,7 @@
 
 import { AiDispatchStrategy } from "@/types/group/DispatchStrategy.js";
 import type { DispatchStrategy } from "@/types/group/DispatchStrategy.js";
-import type { ModelClient, StorageProvider } from "@downcity/type";
+import type { ModelClient, StorageProvider, CityRuntime } from "@downcity/type";
 import type { GroupContract, GroupOptions } from "@/types/group/Group.js";
 import type { Agent } from "@/agent/Agent.js";
 import { GroupSessions } from "@/group/GroupSessions.js";
@@ -20,14 +20,12 @@ export class Group implements GroupContract {
   readonly dispatch_strategy: DispatchStrategy;
   readonly sessions: GroupSessions;
 
-  /** 未加入宿主时使用的隔离进程内存储。 */
+  /** 未加入容器时使用的隔离进程内存储。 */
   private storage_provider: StorageProvider = new AgentMemoryStorageProvider();
-  /** 当前 Group 所属宿主。 */
-  private storage_owner?: object;
+  /** 当前绑定的容器运行环境；独立运行时为空。 */
+  private host?: CityRuntime;
   /** 延迟创建的 GroupSession 持久化 Store。 */
   private session_store?: GroupSessionStore;
-  /** 是否已经在无宿主存储中创建或恢复过 Session。 */
-  private memory_session_started = false;
 
   constructor(options: GroupOptions) {
     this.id = String(options.id || "").trim();
@@ -47,26 +45,31 @@ export class Group implements GroupContract {
     this.sessions = new GroupSessions(this);
   }
 
-  /** 将宿主存储装配到 Group；必须在使用 GroupSessions 前完成。 */
-  attach(owner: object, storage_provider: StorageProvider): void {
-    if (this.storage_owner) {
-      if (this.storage_owner === owner) return;
-      throw new Error(`Group "${this.id}" already belongs to another host`);
+  /**
+   * 绑定容器运行环境；必须在创建或恢复 GroupSession 前完成。
+   *
+   * 关键点（中文）
+   * - 与 Agent 使用同一套绑定语义：只收下容器推送的存储能力，不持有容器引用。
+   */
+  bind(host: CityRuntime): void {
+    if (this.host) {
+      if (this.host === host) return;
+      throw new Error(`Group "${this.id}" is already bound to another container`);
     }
-    if (this.memory_session_started || this.session_store) {
+    if (this.session_store) {
       throw new Error(
-        `Group "${this.id}" already used standalone storage; attach it before using GroupSessions`,
+        `Group "${this.id}" already used standalone storage; bind it before using GroupSessions`,
       );
     }
-    this.storage_owner = owner;
-    this.storage_provider = storage_provider;
+    this.host = host;
+    this.storage_provider = host.storage;
   }
 
-  /** 解除指定宿主的存储装配并释放当前 Store。 */
-  async detach(owner: object): Promise<void> {
-    if (this.storage_owner !== owner) return;
+  /** 解除容器绑定并释放当前 Store，主体回到独立运行状态。 */
+  async unbind(): Promise<void> {
+    if (!this.host) return;
     await this.dispose_session_store();
-    this.storage_owner = undefined;
+    this.host = undefined;
     this.storage_provider = new AgentMemoryStorageProvider();
   }
 
@@ -82,11 +85,6 @@ export class Group implements GroupContract {
     return this.session_store;
   }
 
-  /** 标记 Group 已经创建或恢复过 Session。 */
-  mark_session_started(): void {
-    if (!this.storage_owner) this.memory_session_started = true;
-  }
-
   /** 释放当前 GroupSession Store。 */
   async dispose_session_store(): Promise<void> {
     await this.session_store?.dispose();
@@ -95,6 +93,11 @@ export class Group implements GroupContract {
 
   /** 释放 Group 所拥有的全部群聊上下文。 */
   async dispose(): Promise<void> {
+    if (this.host) {
+      throw new Error(
+        `Group "${this.id}" is bound to a container; release it with city.groups.remove(id)`,
+      );
+    }
     await this.sessions.dispose();
   }
 }

package/src/group/GroupSession.ts

@@ -28,8 +28,8 @@ import {
 } from "@/group/GroupDispatchRuntime.js";
 import type { GroupDispatchResult } from "@/types/group/GroupDispatch.js";
 import { normalize_session_title } from "@/session/storage/Metadata.js";
-import { generate_session_title } from "@/session/SessionTitle.js";
-import { SessionTitleTask } from "@/session/runtime/SessionTitleTask.js";
+import { generate_session_title } from "@/session/loop/SessionTitle.js";
+import { SessionTitleTask } from "@/session/loop/SessionTitleTask.js";
 
 const max_auto_dispatch_count = 32;
 
@@ -710,12 +710,16 @@ export class GroupSession implements GroupSessionContract {
   private subscribe_member_session(agent_id: string, session: AgentSession): void {
     this.member_session_unsubscribes.get(agent_id)?.();
     this.member_session_unsubscribes.set(agent_id, session.subscribe((mutation) => {
-      if (mutation.variant !== "part" || mutation.type !== "interaction") return;
-      if (mutation.part.status === "pending") {
-        this.interaction_sessions.set(mutation.part.interaction_id, session);
-        this.publish_event({ type: "interaction", agent_id, request: mutation.part.request });
-      } else {
-        this.interaction_sessions.delete(mutation.part.interaction_id);
+      if (mutation.variant !== "part" || mutation.type !== "tool") return;
+      // Interaction 属于 Tool Part；同一次 Tool 更新可能同时出现新增与终结的 Interaction。
+      for (const interaction of mutation.part.interactions ?? []) {
+        const registered = this.interaction_sessions.has(interaction.interaction_id);
+        if (interaction.status === "pending" && !registered) {
+          this.interaction_sessions.set(interaction.interaction_id, session);
+          this.publish_event({ type: "interaction", agent_id, request: interaction.request });
+        } else if (interaction.status !== "pending" && registered) {
+          this.interaction_sessions.delete(interaction.interaction_id);
+        }
       }
     }));
   }

package/src/group/GroupSessions.ts

@@ -4,8 +4,12 @@ import { nanoid } from "nanoid";
 import { GroupSession } from "@/group/GroupSession.js";
 import type { Group } from "@/group/Group.js";
 import type { WorkspaceRuntime } from "@downcity/type";
+import type { GroupSessionHistoryMeta } from "@/types/group/GroupSessionStore.js";
 import type {
   GroupSession as GroupSessionContract,
+  GroupSessionArchiveListInput,
+  GroupSessionArchiveResult,
+  GroupSessionCleanArchiveResult,
   GroupSessionCreateInput,
   GroupSessionGetInput,
   GroupSessionListInput,
@@ -27,7 +31,6 @@ export class GroupSessions implements GroupSessionsContract {
     const session = this.create_runtime_session(`group-session-${Date.now()}-${nanoid(8)}`, input?.workspace);
     const store = this.group.get_session_store();
     await session.initialize(store.session(session.id));
-    this.group.mark_session_started();
     this.sessions_by_id.set(session.id, session);
     return session;
   }
@@ -46,30 +49,14 @@ export class GroupSessions implements GroupSessionsContract {
     if (!(await store.has_session(resolved_session_id))) return null;
     const session = this.create_runtime_session(resolved_session_id, input?.workspace);
     await session.initialize(store.session(resolved_session_id));
-    this.group.mark_session_started();
     this.sessions_by_id.set(session.id, session);
     return session;
   }
 
-  /** 恢复当前 Group 的全部群聊上下文。 */
+  /** 恢复当前 Group 的全部群聊上下文（不含已归档）。 */
   async list(input?: GroupSessionListInput): Promise<readonly GroupSessionSummary[]> {
-    const store = this.group.get_session_store();
-    const metadata = await store.list_session_metadata();
-    if (metadata.length > 0) this.group.mark_session_started();
-    const workspace_id = String(input?.workspace_id || "").trim() || undefined;
-    const filtered_metadata = workspace_id
-      ? metadata.filter((item) => item.workspace_id === workspace_id)
-      : metadata;
-    return filtered_metadata.map((item) => ({
-      id: item.session_id,
-      group_id: item.group_id,
-      created_at: item.created_at,
-      updated_at: item.updated_at,
-      message_count: item.message_count,
-      ...(item.workspace_id ? { workspace_id: item.workspace_id } : {}),
-      ...(item.title ? { title: item.title } : {}),
-      ...(item.preview_text ? { preview_text: item.preview_text } : {}),
-    }));
+    const metadata = await this.group.get_session_store().list_session_metadata();
+    return to_summaries(metadata, input?.workspace_id);
   }
 
   /** 释放并删除指定群聊上下文及其持久化数据。 */
@@ -83,6 +70,53 @@ export class GroupSessions implements GroupSessionsContract {
     return session;
   }
 
+  /**
+   * 归档指定群聊上下文：从活动区迁入归档区。
+   *
+   * 与 `remove` 的区别是**可逆性**：归档只是收起来，数据仍在归档区；
+   * 而 `remove` 是永久删除。
+   *
+   * 归档前必须 `dispose` 运行时实例：否则内存里的实例会继续往旧路径（活动区）写，
+   * 而那份目录已经不存在了。`dispose` 失败不阻止归档——实例已经跑不起来了，
+   * 而用户想归档的意图不该因此落空。
+   */
+  async archive(session_id: string): Promise<GroupSessionArchiveResult> {
+    const resolved_session_id = String(session_id || "").trim();
+    if (!resolved_session_id) throw new Error("GroupSessions.archive requires a non-empty session_id");
+    const cached = this.sessions_by_id.get(resolved_session_id);
+    if (cached) {
+      await cached.dispose();
+      this.sessions_by_id.delete(resolved_session_id);
+    }
+    return await this.group.get_session_store().archive_session(resolved_session_id);
+  }
+
+  /** 列出已归档的群聊上下文摘要。 */
+  async archived(input?: GroupSessionArchiveListInput): Promise<readonly GroupSessionSummary[]> {
+    const metadata = await this.group.get_session_store().list_archived_session_metadata();
+    return to_summaries(metadata, input?.workspace_id);
+  }
+
+  /** 永久清空当前 Group 的全部归档。 */
+  async clean_archive(): Promise<GroupSessionCleanArchiveResult> {
+    return await this.group.get_session_store().clean_archive();
+  }
+
+  /**
+   * 永久删除当前 Group 的全部群聊数据（活动区 + 归档区）。
+   *
+   * 它服务于「Group 被删除」：Group 是群聊的**所有者**，所有者消失时它拥有的数据
+   * 不该继续存在。与 `dispose` 的区别：那个只释放运行时实例，数据仍在磁盘上。
+   *
+   * 先释放运行时实例再删目录：实例还活着时删掉它的数据目录，
+   * 之后任何写入都会落到一个已经不存在的位置。
+   */
+  async purge(): Promise<void> {
+    await Promise.allSettled([...this.sessions_by_id.values()].map((session) => session.dispose()));
+    this.sessions_by_id.clear();
+    await this.group.get_session_store().purge();
+  }
+
   /** 释放 Group 所有群聊上下文。 */
   async dispose(): Promise<void> {
     await Promise.allSettled([...this.sessions_by_id.values()].map((session) => session.dispose()));
@@ -103,3 +137,28 @@ export class GroupSessions implements GroupSessionsContract {
     });
   }
 }
+
+/**
+ * 把 metadata 投影成列表摘要，并按 Workspace 过滤。
+ *
+ * 活动列表与归档列表共用这一段：两处各写一遍必然分叉，
+ * 而分叉的表现是「归档后摘要少了字段」这类很难一眼看出的差异。
+ */
+function to_summaries(
+  metadata: readonly GroupSessionHistoryMeta[],
+  workspace_id_input?: string,
+): readonly GroupSessionSummary[] {
+  const workspace_id = String(workspace_id_input || "").trim() || undefined;
+  return metadata
+    .filter((item) => !workspace_id || item.workspace_id === workspace_id)
+    .map((item) => ({
+      id: item.session_id,
+      group_id: item.group_id,
+      created_at: item.created_at,
+      updated_at: item.updated_at,
+      message_count: item.message_count,
+      ...(item.workspace_id ? { workspace_id: item.workspace_id } : {}),
+      ...(item.title ? { title: item.title } : {}),
+      ...(item.preview_text ? { preview_text: item.preview_text } : {}),
+    }));
+}

package/src/group/storage/LocalGroupSessionDataStore.ts

@@ -35,6 +35,14 @@ export class LocalGroupSessionDataStore implements GroupSessionDataStore {
     session_id: string;
     /** 所属 Group 标识。 */
     group_id: string;
+    /**
+     * 当前 Session 所在的存储区。
+     *
+     * 默认 `active`（`sessions/`）；归档后的 Session 住在 `archived-sessions/`。
+     * 区由调用方给而不是在这里判断：DataStore 只负责“某个目录里的一个 Session”，
+     * 该在哪个区是集合层的事。
+     */
+    area?: "active" | "archived";
   }) {
     this.files = options.files;
     this.group_id = options.group_id;
@@ -42,7 +50,7 @@ export class LocalGroupSessionDataStore implements GroupSessionDataStore {
     if (!this.session_id) throw new Error("GroupSession store requires a non-empty session_id");
     this.session_root_path = path.join(
       path.resolve(options.storage_root_path),
-      "sessions",
+      options.area === "archived" ? "archived-sessions" : "sessions",
       encodeURIComponent(this.session_id),
     );
     this.metadata_file_path = path.join(this.session_root_path, "meta.json");