@downcity/agent 1.1.237 → 1.1.258

package/src/agent/{local/services/AgentSessions.ts → AgentSessions.ts}

@@ -10,6 +10,7 @@
 import fs from "fs-extra";
 import { nanoid } from "nanoid";
 import type { Tool } from "ai";
+import type { AgentModel } from "@/agent/AgentModel.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type {
   AgentCreateSessionInput,
@@ -22,25 +23,25 @@ import type {
   AgentSessionSummaryPage,
   AgentSessionSystemBlock,
 } from "@/types/agent/SessionTypes.js";
-import type { AgentModel } from "@/model/CityModelAdapter.js";
 import type { AgentSessionConstructor } from "@/types/agent/AgentOptions.js";
-import type { AgentSession, AgentSessions as AgentSessionsApi } from "@/types/agent/SessionActor.js";
+import type {
+  AgentSession,
+  AgentSessions as AgentSessionsContract,
+} 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 { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
-import { createInstructionSystemBlocks } from "@/agent/local/AgentInstructions.js";
-import type { Shell } from "@downcity/shell";
-import type { SessionApproval } from "@/types/session/SessionApproval.js";
+import type { SessionPort } from "@/types/session/SessionPort.js";
+import { createInstructionSystemBlocks } from "@/agent/AgentInstructions.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
 
 function decodeMaybe(input: string): string {
@@ -72,17 +73,6 @@ type AgentSessionsOptions = {
    */
   logger: Logger;
 
-  /**
-   * 延迟读取当前 agent context。
-   *
-   * 关键点（中文）
-   * - 装配期通过 getter 拿到 context，避免循环引用。
-   */
-  get_agent_context: () => AgentContext;
-
-  /** 延迟读取当前 Agent 挂载的 Shell Runtime。 */
-  get_shell: () => Shell | undefined;
-
   /**
    * 当前静态 instruction 文本集合。
    */
@@ -95,63 +85,46 @@ type AgentSessionsOptions = {
   get_agent_plugins: () => AgentPluginExecutionRuntime;
 
   /**
-   * 等待当前 Agent 后台能力启动完成。
+   * 等待当前 Agent 持有的长期运行时启动完成。
    */
   ensure_agent_ready: () => Promise<void>;
 
-  /**
-   * 当前默认模型实例。
-   */
-  default_model?: AgentModel;
-
-  /** 当前默认模型的稳定 ID。 */
-  default_model_id?: string;
-
-  /** 按稳定 ID 解析 Session 模型。 */
-  resolve_model?: (model_id: string) => Promise<AgentModel>;
-
   /**
    * 当前 agent 使用的本地 Session 类。
    */
   SessionClass?: AgentSessionConstructor;
+
+  /** 读取 Agent 当前持有的运行时模型实例。 */
+  get_agent_model: () => AgentModel | undefined;
 };
 
 /**
  * 本地 Agent session 管理服务。
  */
-export class AgentSessions implements AgentSessionsApi<AgentSession> {
+export class AgentSessions implements AgentSessionsContract<AgentSession> {
   private readonly agent_id: string;
   private readonly project_root: string;
   private readonly tools: Record<string, Tool>;
   private readonly logger: Logger;
-  private readonly get_agent_context: AgentSessionsOptions["get_agent_context"];
-  private readonly get_shell: AgentSessionsOptions["get_shell"];
   private readonly get_instruction: AgentSessionsOptions["get_instruction"];
   private readonly get_agent_env: AgentSessionsOptions["get_agent_env"];
   private readonly get_agent_plugins: AgentSessionsOptions["get_agent_plugins"];
   private readonly ensure_agent_ready: AgentSessionsOptions["ensure_agent_ready"];
-  private readonly default_model?: AgentModel;
-  private readonly default_model_id?: string;
-  private readonly resolve_model?: AgentSessionsOptions["resolve_model"];
   private readonly SessionClass: AgentSessionConstructor;
+  private readonly get_agent_model: AgentSessionsOptions["get_agent_model"];
   private readonly sessions_by_id = new Map<string, AgentManagedSession>();
-  private readonly configured_session_ids = new Set<string>();
 
   constructor(options: AgentSessionsOptions) {
     this.agent_id = options.agent_id;
     this.project_root = options.project_root;
     this.tools = options.tools;
     this.logger = options.logger;
-    this.get_agent_context = options.get_agent_context;
-    this.get_shell = options.get_shell;
     this.get_instruction = options.get_instruction;
     this.get_agent_env = options.get_agent_env;
     this.get_agent_plugins = options.get_agent_plugins;
     this.ensure_agent_ready = options.ensure_agent_ready;
-    this.default_model = options.default_model;
-    this.default_model_id = options.default_model_id;
-    this.resolve_model = options.resolve_model;
     this.SessionClass = options.SessionClass || Session;
+    this.get_agent_model = options.get_agent_model;
   }
 
   /**
@@ -161,6 +134,18 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
     return [...this.sessions_by_id.values()];
   }
 
+  /** 返回当前所有执行中的 Session 标识。 */
+  list_executing_session_ids(): string[] {
+    return this.list_cached_sessions()
+      .filter((session) => session.isExecuting())
+      .map((session) => session.id);
+  }
+
+  /** 返回当前执行中的 Session 数量。 */
+  get_executing_session_count(): number {
+    return this.list_executing_session_ids().length;
+  }
+
   /**
    * 把 Agent instruction 修改广播到已有 Session 的统一输入队列。
    */
@@ -212,7 +197,7 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
   /**
    * 获取或创建一个 session runtime port。
    */
-  get_session_port(session_id: string): SessionPort {
+  runtime(session_id: string): SessionPort {
     return this.get_or_create_session({
       session_id,
     }).getRuntimePort();
@@ -243,7 +228,6 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
       session_id: explicit_session_id,
     });
     await session.initialize();
-    await this.apply_session_defaults(session);
     return session;
   }
 
@@ -270,10 +254,59 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
       session_id: resolved_session_id,
     });
     await session.initialize();
-    await this.apply_session_defaults(session);
     return session;
   }
 
+  /**
+   * 永久删除一个 Session 及其全部 Agent 领域数据。
+   *
+   * 关键点（中文）
+   * - 正在执行的 Session 会先停止，避免删除后继续写入。
+   * - 该方法不处理任何 Plugin 自有数据。
+   */
+  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");
+    }
+    const cached = this.sessions_by_id.get(resolved_session_id);
+    if (cached?.isExecuting()) {
+      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);
+    this.sessions_by_id.delete(resolved_session_id);
+    return existed;
+  }
+
+  /**
+   * 清空一个 Session 的消息目录。
+   */
+  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");
+    }
+    const cached = this.sessions_by_id.get(resolved_session_id);
+    if (cached?.isExecuting()) {
+      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);
+    this.sessions_by_id.delete(resolved_session_id);
+    return existed;
+  }
+
   /**
    * 列出当前 agent 的 session 摘要页。
    */
@@ -284,7 +317,7 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
       projectRoot: this.project_root,
       agentId: this.agent_id,
       input,
-      executingSessionIds: new Set(this.get_agent_context().listExecutingSessionIds()),
+      executingSessionIds: new Set(this.list_executing_session_ids()),
     });
   }
 
@@ -299,9 +332,7 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
       throw new Error("sessions.archive requires a non-empty id");
     }
 
-    const executing_session_ids = new Set(
-      this.get_agent_context().listExecutingSessionIds(),
-    );
+    const executing_session_ids = new Set(this.list_executing_session_ids());
     if (executing_session_ids.has(session_id)) {
       throw new Error(`Session "${session_id}" is currently executing`);
     }
@@ -332,7 +363,6 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
 
     // 关键点（中文）：归档后清理缓存，避免后续操作访问已移动目录。
     this.sessions_by_id.delete(session_id);
-    this.configured_session_ids.delete(session_id);
 
     return {
       sessionId: session_id,
@@ -408,73 +438,17 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
       logger: this.logger,
       getInstructionSystemBlocks: () => this.load_instruction_system_blocks(),
       getAgentEnv: () => this.get_agent_env(),
+      getAgentModel: () => this.get_agent_model(),
       get_agent_plugins: () => this.get_agent_plugins(),
       getManagedPluginSystemBlocks: async () => [],
-      getPluginSystemBlocks: async () => await this.load_plugin_system_blocks(),
       ensureConfigured: async (session) => {
         await this.ensure_agent_ready();
-        await this.apply_session_defaults(session);
-      },
-      ...(this.resolve_model ? { resolve_model: this.resolve_model } : {}),
-      list_approvals: async (session_id) => this.list_session_approvals(session_id),
-      get_approval_mode: async (session_id) => {
-        const shell = this.require_shell();
-        return shell.approval_mode({ session_id });
-      },
-      set_approval_mode: async (session_id, { mode }) => {
-        const shell = this.require_shell();
-        return shell.set_approval_mode({ session_id, mode });
-      },
-      resolve_approval: async (session_id, { approval_id, decision }) => {
-        const approval = this.list_session_approvals(session_id)
-          .find((item) => item.approval_id === approval_id);
-        if (!approval) return { success: false, approval_id, decision };
-        return decision === "approved"
-          ? await this.require_shell().approve({ approval_id })
-          : await this.require_shell().deny({ approval_id });
       },
     });
     this.sessions_by_id.set(resolved_session_id, created);
     return created;
   }
 
-  private require_shell(): Shell {
-    const shell = this.get_shell();
-    if (!shell) throw new Error("Session shell is not configured");
-    return shell;
-  }
-
-  private list_session_approvals(session_id: string): SessionApproval[] {
-    return (this.get_shell()?.approvals() || [])
-      .filter((approval) => approval.session_id === session_id)
-      .map((approval) => ({
-        approval_id: approval.approval_id,
-        session_id,
-        ...(approval.turn_id ? { turn_id: approval.turn_id } : {}),
-        ...(approval.tool_call_id ? { tool_call_id: approval.tool_call_id } : {}),
-        tool_name: approval.tool_name,
-        command: approval.cmd,
-        cwd: approval.cwd,
-        reason: approval.reason,
-        operation: approval.operation,
-        created_at: approval.created_at,
-      }));
-  }
-
-  private async apply_session_defaults(
-    session: AgentManagedSession,
-  ): Promise<void> {
-    if (this.configured_session_ids.has(session.id)) return;
-    const persisted_model_id = String(session.config.modelId || "").trim();
-    if (!persisted_model_id && this.default_model) {
-      await session.set({
-        model: this.default_model,
-        ...(this.default_model_id ? { modelId: this.default_model_id } : {}),
-      });
-    }
-    this.configured_session_ids.add(session.id);
-  }
-
   private load_instruction_system_blocks(): AgentSessionSystemBlock[] {
     return createInstructionSystemBlocks(
       this.get_instruction(),
@@ -482,7 +456,4 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
     );
   }
 
-  private async load_plugin_system_blocks(): Promise<AgentSessionSystemBlock[]> {
-    return await this.get_agent_context().plugins.systemBlocks();
-  }
 }

package/src/agent/AgentState.ts

@@ -0,0 +1,151 @@
+/**
+ * AgentState：本地 Agent 长期运行状态与生命周期。
+ *
+ * 职责说明（中文）
+ * - 统一连接 PluginRegistry、AgentContext、AgentSessions 与共享 tools。
+ * - 持有 Plugin lifecycle 与 ActionSchedule 的启动状态。
+ * - Agent 构造完成后立即开始启动，调用方通过 `ready()` 等待。
+ * - Agent 释放时统一停止 ActionSchedule、Plugin lifecycle 与 Shell。
+ * - 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 { 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,
+  type ActionScheduleRuntimeHandle,
+} from "@/plugin/core/ActionScheduleRuntime.js";
+
+/**
+ * 本地 Agent 长期运行状态。
+ */
+export class AgentState {
+  /** 当前 Agent 共用的执行上下文。 */
+  private readonly context: AgentContext;
+
+  /** 当前 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>;
+
+  /** Plugin lifecycle 是否已经完成启动流程。 */
+  private plugins_started = false;
+
+  /** 当前 Agent 持有的 ActionSchedule 轮询运行时。 */
+  private action_schedule_runtime: ActionScheduleRuntimeHandle | null = null;
+
+  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();
+  }
+
+  /**
+   * 等待当前 Agent 持有的长期运行时启动完成。
+   */
+  async ready(): Promise<void> {
+    await this.ready_promise;
+  }
+
+  /**
+   * 释放当前 Agent 持有的长期运行时对象。
+   */
+  async dispose(): Promise<void> {
+    await this.ready_promise.catch(() => undefined);
+    this.action_schedule_runtime?.stop();
+    this.action_schedule_runtime = null;
+    if (this.plugins_started) {
+      await this.context.plugins.unregisterAll();
+      this.plugins_started = false;
+    }
+    await this.shell?.dispose();
+  }
+
+  /**
+   * 启动 Plugin lifecycle 与 ActionSchedule。
+   *
+   * 关键点（中文）
+   * - Plugin lifecycle 先启动，避免到期任务调用未就绪的 Plugin。
+   * - 单个 Plugin 启动失败由 PluginRegistry 隔离，只记录错误并继续启动 Agent。
+   * - ActionSchedule 启动失败不阻断 Agent ready。
+   */
+  private async start_runtime(): Promise<void> {
+    const snapshots = await this.plugins.startAll();
+    this.plugins_started = true;
+    for (const item of snapshots) {
+      if (item.status === "error") {
+        this.context.logger.error(
+          `Plugin start failed: ${item.name} - ${item.last_error || "unknown error"}`,
+        );
+      }
+    }
+
+    try {
+      this.action_schedule_runtime = await startActionScheduleRuntime(
+        this.context,
+      );
+    } catch (error) {
+      this.context.logger.error(
+        `ActionSchedule start failed: ${String(error)}`,
+      );
+    }
+  }
+
+  /**
+   * 确保带 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(),
+    });
+  }
+}

package/src/config/Paths.ts

@@ -67,39 +67,6 @@ export function getDowncityProfileOtherPath(cwd: string): string {
   return path.join(getDowncityProfileDirPath(cwd), "other.md");
 }
 
-/**
- * Memory 根目录（V2）。
- *
- * 关键点（中文）
- * - `.downcity/memory` 为跨会话记忆目录。
- * - 当前仅供本模块内部继续拼接长期记忆与每日记忆路径。
- */
-function getDowncityMemoryDirPath(cwd: string): string {
-  return path.join(getDowncityDirPath(cwd), "memory");
-}
-
-/**
- * 长期记忆文件路径（V2）。
- */
-export function getDowncityMemoryLongTermPath(cwd: string): string {
-  return path.join(getDowncityMemoryDirPath(cwd), "MEMORY.md");
-}
-
-/**
- * 每日记忆目录路径（V2）。
- */
-export function getDowncityMemoryDailyDirPath(cwd: string): string {
-  return path.join(getDowncityMemoryDirPath(cwd), "daily");
-}
-
-/**
- * 每日记忆文件路径（V2）。
- */
-export function getDowncityMemoryDailyPath(cwd: string, date: string): string {
-  const fileName = `${String(date || "").trim() || "unknown-date"}.md`;
-  return path.join(getDowncityMemoryDailyDirPath(cwd), fileName);
-}
-
 /**
  * Plugin Schedule JSONL 路径。
  *
@@ -272,61 +239,3 @@ export function getDowncityTasksDirPath(cwd: string): string {
 export function getDowncityDebugDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), ".debug");
 }
-
-/**
- * Chat 元信息目录（由 chat plugin runtime 维护）。
- *
- * 关键点（中文）
- * - 该目录存放 `sessionId -> chat` 的最近映射快照
- * - 与 core session messages 分离，避免把平台路由细节耦合进 core
- * - 当前仅供本模块内部继续拼接 chat 会话与 meta 子目录。
- */
-function getDowncityChatDirPath(cwd: string): string {
-  return path.join(getDowncityDirPath(cwd), "chat");
-}
-
-/**
- * Channel 目录（channel -> sessionId 映射）。
- *
- * 关键点（中文）
- * - 专门承载渠道目标与内部 sessionId 的映射关系。
- * - 与 `chat/` 审计事件目录分离，避免职责混淆。
- */
-export function getDowncityChannelDirPath(cwd: string): string {
-  return path.join(getDowncityDirPath(cwd), "channel");
-}
-
-/**
- * Channel 元信息文件路径。
- *
- * 关键点（中文）
- * - 采用单文件 JSON（`meta.json`）存储映射表与最近路由信息。
- */
-export function getDowncityChannelMetaPath(cwd: string): string {
-  return path.join(getDowncityChannelDirPath(cwd), "meta.json");
-}
-
-/**
- * Chat 会话目录（按 sessionId 组织）。
- *
- * 关键点（中文）
- * - 用于存放聊天事件流（history.jsonl）等审计向数据。
- * - 与 `chat/meta` 分离，避免路由快照与事件流混在一起。
- */
-export function getDowncityChatSessionDirPath(cwd: string, sessionId: string): string {
-  return path.join(
-    getDowncityChatDirPath(cwd),
-    encodeURIComponent(String(sessionId || "").trim()),
-  );
-}
-
-/**
- * Chat 事件流文件路径（JSONL）。
- *
- * 关键点（中文）
- * - 每行一条 chat 事件（当前为 inbound）。
- * - 设计为 append-only，便于审计与回放。
- */
-export function getDowncityChatHistoryPath(cwd: string, sessionId: string): string {
-  return path.join(getDowncityChatSessionDirPath(cwd, sessionId), "history.jsonl");
-}