@downcity/agent 1.1.287 → 1.1.310

package/src/agent/AgentSessions.ts

@@ -7,7 +7,6 @@
  * - Session 对象创建细节集中在这里，避免 facade 和 lifecycle 重复依赖 Session 构造逻辑。
  */
 
-import fs from "fs-extra";
 import { nanoid } from "nanoid";
 import type { Tool } from "ai";
 import type { AgentModel } from "@/agent/AgentModel.js";
@@ -30,27 +29,10 @@ import type {
 } from "@/types/agent/SessionActor.js";
 import type { AgentManagedSession } from "@/types/session/SessionOptions.js";
 import { Session } from "@/session/Session.js";
-import {
-  getSdkAgentArchivedSessionDirPath,
-  getSdkAgentArchivedSessionsDirPath,
-  getSdkAgentSessionDirPath,
-  getSdkAgentSessionMessagesDirPath,
-} from "@/session/storage/Paths.js";
-import {
-  listArchivedAgentSessionSummaryPage,
-  listAgentSessionSummaryPage,
-} from "@/session/browse/Browse.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
-import { createInstructionSystemBlocks } from "@/agent/AgentInstructions.js";
+import { create_instruction_system_blocks } from "@/agent/AgentInstructions.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
-
-function decodeMaybe(input: string): string {
-  try {
-    return decodeURIComponent(input);
-  } catch {
-    return input;
-  }
-}
+import type { AgentStore } from "@/types/store/AgentStore.js";
 
 type AgentSessionsOptions = {
   /**
@@ -61,7 +43,10 @@ type AgentSessionsOptions = {
   /**
    * 当前项目根目录。
    */
-  project_root: string;
+  workspace_path: string;
+
+  /** 当前 Agent 独享的领域持久化入口。 */
+  store: AgentStore;
 
   /**
    * 当前 agent 默认工具集合。
@@ -78,8 +63,8 @@ type AgentSessionsOptions = {
    */
   get_instruction: () => string[];
 
-  /** 延迟读取当前 Agent configured env。 */
-  get_agent_env: () => Record<string, string>;
+  /** 延迟读取当前 Workspace configured env。 */
+  get_workspace_env: () => Record<string, string>;
 
   /** 创建当前 configured Plugin registry 的 Session step 执行视图。 */
   get_agent_plugins: () => AgentPluginExecutionRuntime;
@@ -92,7 +77,7 @@ type AgentSessionsOptions = {
   /**
    * 当前 agent 使用的本地 Session 类。
    */
-  SessionClass?: AgentSessionConstructor;
+  session_class?: AgentSessionConstructor;
 
   /** 读取 Agent 当前持有的运行时模型实例。 */
   get_agent_model: () => AgentModel | undefined;
@@ -103,27 +88,29 @@ type AgentSessionsOptions = {
  */
 export class AgentSessions implements AgentSessionsContract<AgentSession> {
   private readonly agent_id: string;
-  private readonly project_root: string;
+  private readonly workspace_path: string;
+  private readonly store: AgentStore;
   private readonly tools: Record<string, Tool>;
   private readonly logger: Logger;
   private readonly get_instruction: AgentSessionsOptions["get_instruction"];
-  private readonly get_agent_env: AgentSessionsOptions["get_agent_env"];
+  private readonly get_workspace_env: AgentSessionsOptions["get_workspace_env"];
   private readonly get_agent_plugins: AgentSessionsOptions["get_agent_plugins"];
   private readonly ensure_agent_ready: AgentSessionsOptions["ensure_agent_ready"];
-  private readonly SessionClass: AgentSessionConstructor;
+  private readonly session_class: AgentSessionConstructor;
   private readonly get_agent_model: AgentSessionsOptions["get_agent_model"];
   private readonly sessions_by_id = new Map<string, AgentManagedSession>();
 
   constructor(options: AgentSessionsOptions) {
     this.agent_id = options.agent_id;
-    this.project_root = options.project_root;
+    this.workspace_path = options.workspace_path;
+    this.store = options.store;
     this.tools = options.tools;
     this.logger = options.logger;
     this.get_instruction = options.get_instruction;
-    this.get_agent_env = options.get_agent_env;
+    this.get_workspace_env = options.get_workspace_env;
     this.get_agent_plugins = options.get_agent_plugins;
     this.ensure_agent_ready = options.ensure_agent_ready;
-    this.SessionClass = options.SessionClass || Session;
+    this.session_class = options.session_class || Session;
     this.get_agent_model = options.get_agent_model;
   }
 
@@ -137,7 +124,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   /** 返回当前所有执行中的 Session 标识。 */
   list_executing_session_ids(): string[] {
     return this.list_cached_sessions()
-      .filter((session) => session.isExecuting())
+      .filter((session) => session.is_executing())
       .map((session) => session.id);
   }
 
@@ -151,8 +138,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
    */
   broadcast_env(env: Record<string, string>, command_id: string): void {
     for (const session of this.sessions_by_id.values()) {
-      session.enqueue_agent_command({
-        type: "env",
+      session.enqueue_workspace_env({
         command_id,
         env: { ...env },
       });
@@ -168,8 +154,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     plugins: AgentPluginExecutionRuntime;
   }): void {
     for (const session of this.sessions_by_id.values()) {
-      session.enqueue_agent_command({
-        type: "plugins",
+      session.enqueue_agent_plugins({
         command_id: input.command_id,
         title: input.title,
         plugins: input.plugins,
@@ -181,7 +166,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
    * 获取或创建一个 session runtime port。
    */
   runtime(session_id: string): SessionPort {
-    return this.get_or_create_session({ session_id }).getRuntimePort();
+    return this.get_or_create_session({ session_id }).get_runtime_port();
   }
 
   /**
@@ -191,17 +176,11 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     input?: AgentCreateSessionInput,
   ): Promise<AgentSession> {
     const explicit_session_id =
-      String(input?.sessionId || "").trim() || undefined;
+      String(input?.session_id || "").trim() || undefined;
     if (
       explicit_session_id &&
       (this.sessions_by_id.has(explicit_session_id) ||
-        (await fs.pathExists(
-          getSdkAgentSessionDirPath(
-            this.project_root,
-            this.agent_id,
-            explicit_session_id,
-          ),
-        )))
+        (await this.store.has_session(explicit_session_id)))
     ) {
       throw new Error(`Session "${explicit_session_id}" already exists`);
     }
@@ -218,16 +197,11 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   async get(session_id: string): Promise<AgentSession> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
-      throw new Error("sessions.get requires a non-empty sessionId");
+      throw new Error("sessions.get requires a non-empty session_id");
     }
-    const session_dir_path = getSdkAgentSessionDirPath(
-      this.project_root,
-      this.agent_id,
-      resolved_session_id,
-    );
     if (
       !this.sessions_by_id.has(resolved_session_id) &&
-      !(await fs.pathExists(session_dir_path))
+      !(await this.store.has_session(resolved_session_id))
     ) {
       throw new Error(`Session "${resolved_session_id}" not found`);
     }
@@ -248,19 +222,13 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   async remove(session_id: string): Promise<boolean> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
-      throw new Error("sessions.remove requires a non-empty sessionId");
+      throw new Error("sessions.remove requires a non-empty session_id");
     }
     const cached = this.sessions_by_id.get(resolved_session_id);
-    if (cached?.isExecuting()) {
+    if (cached?.is_executing()) {
       await cached.stop();
     }
-    const session_dir_path = getSdkAgentSessionDirPath(
-      this.project_root,
-      this.agent_id,
-      resolved_session_id,
-    );
-    const existed = await fs.pathExists(session_dir_path);
-    if (existed) await fs.remove(session_dir_path);
+    const existed = await this.store.remove_session(resolved_session_id);
     this.sessions_by_id.delete(resolved_session_id);
     return existed;
   }
@@ -271,19 +239,13 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   async clear_messages(session_id: string): Promise<boolean> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
-      throw new Error("sessions.clear_messages requires a non-empty sessionId");
+      throw new Error("sessions.clear_messages requires a non-empty session_id");
     }
     const cached = this.sessions_by_id.get(resolved_session_id);
-    if (cached?.isExecuting()) {
+    if (cached?.is_executing()) {
       throw new Error(`Session "${resolved_session_id}" is currently executing`);
     }
-    const messages_dir_path = getSdkAgentSessionMessagesDirPath(
-      this.project_root,
-      this.agent_id,
-      resolved_session_id,
-    );
-    const existed = await fs.pathExists(messages_dir_path);
-    if (existed) await fs.remove(messages_dir_path);
+    const existed = await this.store.clear_session_messages(resolved_session_id);
     this.sessions_by_id.delete(resolved_session_id);
     return existed;
   }
@@ -294,12 +256,10 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   async list(
     input?: AgentListSessionsInput,
   ): Promise<AgentSessionSummaryPage> {
-    return await listAgentSessionSummaryPage({
-      projectRoot: this.project_root,
-      agentId: this.agent_id,
+    return await this.store.list_sessions(
       input,
-      executingSessionIds: new Set(this.list_executing_session_ids()),
-    });
+      new Set(this.list_executing_session_ids()),
+    );
   }
 
   /**
@@ -318,37 +278,9 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       throw new Error(`Session "${session_id}" is currently executing`);
     }
 
-    const source_path = getSdkAgentSessionDirPath(
-      this.project_root,
-      this.agent_id,
-      session_id,
-    );
-    if (!(await fs.pathExists(source_path))) {
-      throw new Error(`Session "${session_id}" not found`);
-    }
-
-    const target_path = getSdkAgentArchivedSessionDirPath(
-      this.project_root,
-      this.agent_id,
-      session_id,
-    );
-    if (await fs.pathExists(target_path)) {
-      throw new Error(`Archived session "${session_id}" already exists`);
-    }
-
-    await fs.ensureDir(getSdkAgentArchivedSessionsDirPath(
-      this.project_root,
-      this.agent_id,
-    ));
-    await fs.move(source_path, target_path);
-
-    // 关键点（中文）：归档后清理缓存，避免后续操作访问已移动目录。
+    const result = await this.store.archive_session(session_id);
     this.sessions_by_id.delete(session_id);
-
-    return {
-      sessionId: session_id,
-      archivedAt: Date.now(),
-    };
+    return result;
   }
 
   /**
@@ -357,46 +289,14 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   async archived(
     input?: AgentArchiveSessionsInput,
   ): Promise<AgentArchiveSessionsResult> {
-    return await listArchivedAgentSessionSummaryPage({
-      projectRoot: this.project_root,
-      agentId: this.agent_id,
-      input,
-    });
+    return await this.store.list_archived_sessions(input);
   }
 
   /**
    * 永久清空已归档 session。
    */
   async clean_archive(): Promise<AgentCleanArchiveResult> {
-    const archived_root = getSdkAgentArchivedSessionsDirPath(
-      this.project_root,
-      this.agent_id,
-    );
-    if (!(await fs.pathExists(archived_root))) {
-      return {
-        removedSessionIds: [],
-      };
-    }
-
-    const entries = await fs.readdir(archived_root, { withFileTypes: true });
-    const removed_session_ids: string[] = [];
-
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const session_id = decodeMaybe(entry.name);
-      if (!session_id) continue;
-      const session_path = getSdkAgentArchivedSessionDirPath(
-        this.project_root,
-        this.agent_id,
-        session_id,
-      );
-      await fs.remove(session_path);
-      removed_session_ids.push(session_id);
-    }
-
-    return {
-      removedSessionIds: removed_session_ids,
-    };
+    return await this.store.clean_archive();
   }
 
   private get_or_create_session(input?: {
@@ -411,19 +311,21 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     const cached = this.sessions_by_id.get(resolved_session_id);
     if (cached) return cached;
 
-    const created = new this.SessionClass({
-      agentId: this.agent_id,
-      projectRoot: this.project_root,
-      sessionId: resolved_session_id,
+    const created = new this.session_class({
+      agent_id: this.agent_id,
+      workspace_path: this.workspace_path,
+      store: this.store.session(resolved_session_id),
+      get_session_store: (session_id) => this.store.session(session_id),
+      session_id: resolved_session_id,
       tools: this.tools,
       logger: this.logger,
       instruction_system_blocks: this.load_instruction_system_blocks(),
       get_instruction_system_blocks: () => this.load_instruction_system_blocks(),
-      getAgentEnv: () => this.get_agent_env(),
-      getAgentModel: () => this.get_agent_model(),
+      get_workspace_env: () => this.get_workspace_env(),
+      get_agent_model: () => this.get_agent_model(),
       get_agent_plugins: () => this.get_agent_plugins(),
-      getManagedPluginSystemBlocks: async () => [],
-      ensureConfigured: async (session) => {
+      get_managed_plugin_system_blocks: async () => [],
+      ensure_configured: async (session) => {
         await this.ensure_agent_ready();
       },
     });
@@ -432,9 +334,9 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   }
 
   private load_instruction_system_blocks(): AgentSessionSystemBlock[] {
-    return createInstructionSystemBlocks(
+    return create_instruction_system_blocks(
       this.get_instruction(),
-      this.project_root,
+      this.workspace_path,
     );
   }
 

package/src/agent/AgentState.ts

@@ -2,23 +2,18 @@
  * AgentState：本地 Agent 长期运行状态与生命周期。
  *
  * 职责说明（中文）
- * - 统一连接 PluginRegistry、AgentContext、AgentSessions 与共享 tools。
+ * - 统一连接 PluginRegistry 与 PluginContext。
  * - 持有 Plugin lifecycle 与 ActionSchedule 的启动状态。
  * - Agent 构造完成后立即开始启动，调用方通过 `ready()` 等待。
- * - Agent 释放时统一停止 ActionSchedule、Plugin lifecycle 与 Shell。
+ * - Agent 释放时统一停止 ActionSchedule 与 Plugin lifecycle。
  * - RPC / HTTP 等 transport 不属于 AgentState，由上游宿主独立管理。
  */
 
-import type { Shell } from "@downcity/shell";
-import type { Tool } from "ai";
-import type { AgentContext } from "@/agent/AgentContext.js";
-import type { AgentSessions } from "@/agent/AgentSessions.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
 import type { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
 import type { AgentStateOptions } from "@/types/agent/AgentState.js";
-import { createPluginTools } from "@executor/tools/plugin/PluginToolDefinition.js";
-import { generateId } from "@/utils/Id.js";
 import {
-  startActionScheduleRuntime,
+  start_action_schedule_runtime,
   type ActionScheduleRuntimeHandle,
 } from "@/plugin/core/ActionScheduleRuntime.js";
 
@@ -27,20 +22,11 @@ import {
  */
 export class AgentState {
   /** 当前 Agent 共用的执行上下文。 */
-  private readonly context: AgentContext;
+  private readonly context: PluginContext;
 
   /** 当前 Agent 唯一的 PluginRegistry 实例。 */
   private readonly plugins: PluginRegistry;
 
-  /** 当前 Agent 唯一的 Session 集合。 */
-  private readonly sessions: AgentSessions;
-
-  /** 当前 Agent 与 Session 共享的可变工具集合。 */
-  private readonly tools: Record<string, Tool>;
-
-  /** 当前 Agent 持有的可选 Shell 实例。 */
-  private readonly shell?: Shell;
-
   /** Plugin lifecycle 与 ActionSchedule 的唯一启动 Promise。 */
   private readonly ready_promise: Promise<void>;
 
@@ -53,15 +39,7 @@ export class AgentState {
   constructor(options: AgentStateOptions) {
     this.context = options.context;
     this.plugins = options.plugins;
-    this.sessions = options.sessions;
-    this.tools = options.tools;
-    this.shell = options.shell;
-
     this.plugins.bind_context(this.context);
-    this.ensure_plugin_tools();
-    this.plugins.set_change_listener(({ type, plugin_name }) => {
-      this.handle_plugin_change(type, plugin_name);
-    });
     this.ready_promise = this.start_runtime();
   }
 
@@ -80,10 +58,9 @@ export class AgentState {
     this.action_schedule_runtime?.stop();
     this.action_schedule_runtime = null;
     if (this.plugins_started) {
-      await this.context.plugins.unregisterAll();
+      await this.context.plugins.unregister_all();
       this.plugins_started = false;
     }
-    await this.shell?.dispose();
   }
 
   /**
@@ -95,7 +72,7 @@ export class AgentState {
    * - ActionSchedule 启动失败不阻断 Agent ready。
    */
   private async start_runtime(): Promise<void> {
-    const snapshots = await this.plugins.startAll();
+    const snapshots = await this.plugins.start_all();
     this.plugins_started = true;
     for (const item of snapshots) {
       if (item.status === "error") {
@@ -106,7 +83,7 @@ export class AgentState {
     }
 
     try {
-      this.action_schedule_runtime = await startActionScheduleRuntime(
+      this.action_schedule_runtime = await start_action_schedule_runtime(
         this.context,
       );
     } catch (error) {
@@ -116,36 +93,4 @@ export class AgentState {
     }
   }
 
-  /**
-   * 确保带 action 的 PluginRegistry 已连接通用调用工具。
-   *
-   * 关键点（中文）
-   * - 初始 Plugin 与运行中动态注册 Plugin 统一走这里。
-   * - 只补充缺失工具，不覆盖调用方提供的同名自定义工具。
-   * - tools 是 AgentSessions 与 Session 共享引用，原地写入会立即对现有 Session 生效。
-   */
-  private ensure_plugin_tools(): void {
-    if (!this.plugins.list().some((plugin) => plugin.actions.length > 0)) {
-      return;
-    }
-    const plugin_tools = createPluginTools({ plugins: this.plugins });
-    this.tools.plugin_read = this.tools.plugin_read || plugin_tools.plugin_read;
-    this.tools.plugin_call = this.tools.plugin_call || plugin_tools.plugin_call;
-  }
-
-  /**
-   * 处理 PluginRegistry 修改后的 Agent 运行时同步。
-   */
-  private handle_plugin_change(
-    type: "register" | "unregister",
-    plugin_name: string,
-  ): void {
-    this.ensure_plugin_tools();
-    const verb = type === "register" ? "registered" : "unregistered";
-    this.sessions.broadcast_plugins({
-      command_id: generateId(),
-      title: `Agent plugin ${plugin_name} ${verb}`,
-      plugins: this.plugins.execution_view(),
-    });
-  }
 }