@downcity/agent 1.1.74 → 1.1.81

package/src/agent/local/services/AgentLifecycleService.ts

@@ -0,0 +1,187 @@
+/**
+ * AgentLifecycleService：本地 Agent 生命周期服务。
+ *
+ * 关键点（中文）
+ * - 统一管理 plugins、ActionSchedule 与本机 RPC 的启动/停止。
+ * - 该服务只负责长期后台能力生命周期，不负责 session 构造与运行时装配。
+ * - facade 通过它暴露 `start()` / `stop()` 语义，避免生命周期状态散落在 Agent 主类中。
+ */
+
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type {
+  AgentRpcBinding,
+  AgentRpcStartOptions,
+  AgentSessionCollection,
+  AgentStartOptions,
+  AgentStartResult,
+  AgentStopResult,
+} from "@/types/agent/AgentTypes.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { ActionScheduleRuntimeHandle } from "@/plugin/core/ActionScheduleRuntime.js";
+import { startActionScheduleRuntime } from "@/plugin/core/ActionScheduleRuntime.js";
+import { startAllPlugins, stopAllPlugins } from "@/plugin/core/Manager.js";
+import { startRpcServer } from "@/rpc/Server.js";
+import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+
+type AgentLifecycleServiceOptions = {
+  /**
+   * 当前统一日志器。
+   */
+  logger: Logger;
+
+  /**
+   * 当前 agent context。
+   */
+  agent_context: AgentContext;
+
+  /**
+   * 当前 session collection。
+   */
+  session_collection: AgentSessionCollection;
+
+  /**
+   * 读取当前 agent runtime。
+   */
+  get_runtime: () => AgentRuntime;
+};
+
+/**
+ * 本地 Agent 生命周期服务。
+ */
+export class AgentLifecycleService {
+  private readonly logger: Logger;
+  private readonly agent_context: AgentContext;
+  private readonly session_collection: AgentSessionCollection;
+  private readonly get_runtime: AgentLifecycleServiceOptions["get_runtime"];
+
+  private plugins_started = false;
+  private action_schedule_runtime: ActionScheduleRuntimeHandle | null = null;
+  private start_promise: Promise<AgentStartResult> | null = null;
+  private rpc_binding: AgentRpcBinding | null = null;
+
+  constructor(options: AgentLifecycleServiceOptions) {
+    this.logger = options.logger;
+    this.agent_context = options.agent_context;
+    this.session_collection = options.session_collection;
+    this.get_runtime = options.get_runtime;
+  }
+
+  /**
+   * 启动当前 agent 实例的长期运行能力。
+   */
+  async start(options?: AgentStartOptions): Promise<AgentStartResult> {
+    if (this.start_promise) {
+      return await this.start_promise;
+    }
+    this.start_promise = (async () => {
+      const should_start_plugins = options?.plugins !== false;
+      if (should_start_plugins) {
+        await this.ensure_plugins_started();
+      }
+      const rpc_binding =
+        options?.rpc === false || options?.rpc === undefined
+          ? undefined
+          : await this.start_rpc(options.rpc);
+      return {
+        ...(rpc_binding ? { rpc: rpc_binding } : {}),
+        pluginsStarted: this.plugins_started,
+      };
+    })();
+    try {
+      return await this.start_promise;
+    } catch (error) {
+      this.start_promise = null;
+      throw error;
+    }
+  }
+
+  /**
+   * 停止当前 agent 实例的长期运行能力。
+   */
+  async stop(): Promise<AgentStopResult> {
+    const plugins_started = this.plugins_started;
+    const rpc_started = this.rpc_binding !== null;
+
+    if (plugins_started) {
+      await this.stop_action_schedule_runtime();
+      await stopAllPlugins(this.agent_context);
+      this.plugins_started = false;
+    }
+
+    if (rpc_started) {
+      await this.stop_rpc();
+    }
+
+    this.start_promise = null;
+
+    return {
+      rpcStopped: rpc_started,
+      pluginsStopped: plugins_started,
+    };
+  }
+
+  private async ensure_plugins_started(): Promise<void> {
+    if (this.plugins_started) return;
+    const lifecycle = await startAllPlugins(this.agent_context);
+    this.plugins_started = true;
+    for (const item of lifecycle.results) {
+      if (!item.success) {
+        this.logger.error(
+          `Plugin start failed: ${item.plugin?.name || "unknown"} - ${item.error || "unknown error"}`,
+        );
+      }
+    }
+    await this.ensure_action_schedule_runtime_started();
+  }
+
+  private async ensure_action_schedule_runtime_started(): Promise<void> {
+    if (this.action_schedule_runtime) return;
+    try {
+      this.action_schedule_runtime = await startActionScheduleRuntime(
+        this.agent_context,
+      );
+    } catch (error) {
+      this.logger.error(`ActionSchedule start failed: ${String(error)}`);
+    }
+  }
+
+  private async stop_action_schedule_runtime(): Promise<void> {
+    const runtime = this.action_schedule_runtime;
+    this.action_schedule_runtime = null;
+    runtime?.stop();
+  }
+
+  private async start_rpc(
+    options?: AgentRpcStartOptions,
+  ): Promise<AgentRpcBinding> {
+    if (this.rpc_binding) {
+      return this.rpc_binding;
+    }
+    const host = String(options?.host || "127.0.0.1").trim() || "127.0.0.1";
+    const port =
+      typeof options?.port === "number" && Number.isInteger(options.port)
+        ? options.port
+        : 15314;
+    const server = await startRpcServer({
+      host,
+      port,
+      sessionCollection: this.session_collection,
+      getAgentContext: () => this.agent_context,
+      getAgentRuntime: () => this.get_runtime(),
+    });
+    this.rpc_binding = {
+      url: `rpc://${host}:${port}`,
+      host,
+      port,
+      server,
+    };
+    return this.rpc_binding;
+  }
+
+  private async stop_rpc(): Promise<void> {
+    if (!this.rpc_binding) return;
+    const current = this.rpc_binding;
+    this.rpc_binding = null;
+    await current.server.stop();
+  }
+}

package/src/agent/local/services/AgentSessionManager.ts

@@ -0,0 +1,291 @@
+/**
+ * AgentSessionManager：本地 Agent session 管理服务。
+ *
+ * 关键点（中文）
+ * - 统一管理 session 缓存、创建、恢复、默认配置注入与 session collection。
+ * - 该服务只负责 session 生命周期与查询，不负责 plugin / RPC 启停。
+ * - Session 对象创建细节集中在这里，避免 facade 和 lifecycle 重复依赖 Session 构造逻辑。
+ */
+
+import fs from "fs-extra";
+import { nanoid } from "nanoid";
+import type { Tool } from "ai";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type {
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentManagedSession,
+  AgentModel,
+  AgentSession,
+  AgentSessionCollection,
+  AgentSessionConstructor,
+  AgentSessionSummaryPage,
+  AgentSessionSystemBlock,
+} from "@/types/agent/AgentTypes.js";
+import { Session } from "@/session/Session.js";
+import {
+  getSdkAgentSessionDirPath,
+  listAgentSessionSummaryPage,
+} from "@/session/index.js";
+import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
+import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
+import { isPluginEnabled } from "@/plugin/core/Activation.js";
+import { createInstructionSystemBlocks } from "@/agent/local/AgentInstructions.js";
+
+type AgentSessionManagerOptions = {
+  /**
+   * 当前 agent 稳定标识。
+   */
+  agent_id: string;
+
+  /**
+   * 当前项目根目录。
+   */
+  project_root: string;
+
+  /**
+   * 当前 agent 默认工具集合。
+   */
+  tools: Record<string, Tool>;
+
+  /**
+   * 当前统一日志器。
+   */
+  logger: Logger;
+
+  /**
+   * 当前 agent runtime。
+   */
+  runtime: AgentRuntime;
+
+  /**
+   * 延迟读取当前 agent context。
+   */
+  get_agent_context: () => AgentContext;
+
+  /**
+   * 当前静态 instruction 文本集合。
+   */
+  get_instruction: () => string[];
+
+  /**
+   * 当前 plugin 实例集合。
+   */
+  plugin_instances: Map<string, BasePlugin>;
+
+  /**
+   * 当前默认模型实例。
+   */
+  default_model?: AgentModel;
+
+  /**
+   * 当前 agent 使用的本地 Session 类。
+   */
+  SessionClass?: AgentSessionConstructor;
+};
+
+/**
+ * 本地 Agent session 管理服务。
+ */
+export class AgentSessionManager {
+  private readonly agent_id: string;
+  private readonly project_root: string;
+  private readonly tools: Record<string, Tool>;
+  private readonly logger: Logger;
+  private readonly runtime: AgentRuntime;
+  private readonly get_agent_context: AgentSessionManagerOptions["get_agent_context"];
+  private readonly get_instruction: AgentSessionManagerOptions["get_instruction"];
+  private readonly plugin_instances: Map<string, BasePlugin>;
+  private readonly default_model?: AgentModel;
+  private readonly SessionClass: AgentSessionConstructor;
+  private readonly sessions_by_id = new Map<string, AgentManagedSession>();
+  private readonly configured_session_ids = new Set<string>();
+  private readonly session_collection: AgentSessionCollection;
+
+  constructor(options: AgentSessionManagerOptions) {
+    this.agent_id = options.agent_id;
+    this.project_root = options.project_root;
+    this.tools = options.tools;
+    this.logger = options.logger;
+    this.runtime = options.runtime;
+    this.get_agent_context = options.get_agent_context;
+    this.get_instruction = options.get_instruction;
+    this.plugin_instances = options.plugin_instances;
+    this.default_model = options.default_model;
+    this.SessionClass = options.SessionClass || Session;
+    this.session_collection = {
+      createSession: async (input) => await this.create_session(input),
+      getSession: async (session_id) => await this.get_session(session_id),
+      listSessions: async (input) => await this.list_sessions(input),
+    };
+  }
+
+  /**
+   * 返回当前缓存的 session 实例。
+   */
+  list_cached_sessions(): AgentManagedSession[] {
+    return [...this.sessions_by_id.values()];
+  }
+
+  /**
+   * 返回对外暴露的 session collection。
+   */
+  get_session_collection(): AgentSessionCollection {
+    return this.session_collection;
+  }
+
+  /**
+   * 获取或创建一个 session runtime port。
+   */
+  get_session_port(session_id: string): SessionPort {
+    return this.get_or_create_session({
+      session_id,
+    }).getRuntimePort();
+  }
+
+  /**
+   * 新建一个 session。
+   */
+  async create_session(
+    input?: AgentCreateSessionInput,
+  ): Promise<AgentSession> {
+    const explicit_session_id =
+      String(input?.sessionId || "").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,
+          ),
+        )))
+    ) {
+      throw new Error(`Session "${explicit_session_id}" already exists`);
+    }
+    const session = this.get_or_create_session({
+      session_id: explicit_session_id,
+    });
+    await session.initialize();
+    await this.apply_session_defaults(session);
+    return session;
+  }
+
+  /**
+   * 获取一个已存在的 session。
+   */
+  async get_session(session_id: string): Promise<AgentSession> {
+    const resolved_session_id = String(session_id || "").trim();
+    if (!resolved_session_id) {
+      throw new Error("getSession requires a non-empty sessionId");
+    }
+    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))
+    ) {
+      throw new Error(`Session "${resolved_session_id}" not found`);
+    }
+    const session = this.get_or_create_session({
+      session_id: resolved_session_id,
+    });
+    await session.initialize();
+    await this.apply_session_defaults(session);
+    return session;
+  }
+
+  /**
+   * 列出当前 agent 的 session 摘要页。
+   */
+  async list_sessions(
+    input?: AgentListSessionsInput,
+  ): Promise<AgentSessionSummaryPage> {
+    return await listAgentSessionSummaryPage({
+      projectRoot: this.project_root,
+      agentId: this.agent_id,
+      input,
+      executingSessionIds: new Set(this.runtime.listExecutingSessionIds()),
+    });
+  }
+
+  private get_or_create_session(input?: {
+    /**
+     * 可选指定 session id。
+     */
+    session_id?: string;
+
+  }): 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);
+    if (cached) return cached;
+
+    const created = new this.SessionClass({
+      agentId: this.agent_id,
+      projectRoot: this.project_root,
+      sessionId: resolved_session_id,
+      tools: this.tools,
+      logger: this.logger,
+      getInstructionSystemBlocks: () => this.load_instruction_system_blocks(),
+      getManagedPluginSystemBlocks: async () => [],
+      getPluginSystemBlocks: async () => await this.load_plugin_system_blocks(),
+      ensureConfigured: async (session) => {
+        await this.apply_session_defaults(session);
+      },
+    });
+    this.sessions_by_id.set(resolved_session_id, created);
+    return created;
+  }
+
+  private async apply_session_defaults(
+    session: AgentManagedSession,
+  ): Promise<void> {
+    if (this.configured_session_ids.has(session.id)) return;
+    if (this.default_model) {
+      await session.set({
+        model: this.default_model,
+      });
+    }
+    this.configured_session_ids.add(session.id);
+  }
+
+  private load_instruction_system_blocks(): AgentSessionSystemBlock[] {
+    return createInstructionSystemBlocks(
+      this.get_instruction(),
+      this.project_root,
+    );
+  }
+
+  private async load_plugin_system_blocks(): Promise<AgentSessionSystemBlock[]> {
+    const context = this.get_agent_context();
+    const out: AgentSessionSystemBlock[] = [];
+    for (const plugin of this.plugin_instances.values()) {
+      if (typeof plugin.system !== "function") continue;
+      try {
+        if (!isPluginEnabled({ plugin, context })) continue;
+        if (typeof plugin.availability === "function") {
+          const availability = await plugin.availability(context);
+          if (!availability.available) continue;
+        }
+        const text = String(await plugin.system(context)).trim();
+        if (!text) continue;
+        out.push({
+          source: "plugin",
+          name: plugin.name,
+          content: text,
+        });
+      } catch {
+        // 单个 plugin system 失败不应阻断 SDK session 主链路。
+      }
+    }
+    return out;
+  }
+}

package/src/agent/remote/RemoteAgent.ts

@@ -0,0 +1,76 @@
+/**
+ * Agent remote：统一远程 SDK 客户端。
+ *
+ * 关键点（中文）
+ * - 对外只暴露一个 `url` 入口，不向用户暴露 transport 细节。
+ * - 当前内部支持 `http/https` 与 `rpc` 两种访问方式。
+ * - `RemoteAgent` 只负责远程访问，不重复实现第二套会话编排器。
+ */
+
+import type {
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentSessionSummaryPage,
+  RemoteAgentOptions,
+  RemoteAgentSession,
+} from "@/types/agent/AgentTypes.js";
+import type { RemoteAgentTransport } from "@/agent/remote/RemoteTransport.js";
+import { RemoteSession } from "@/agent/remote/RemoteSession.js";
+import { create_remote_agent_transport } from "@/agent/remote/TransportFactory.js";
+
+/**
+ * RemoteAgent：远程 Agent 客户端。
+ */
+export class RemoteAgent {
+  private readonly transport: RemoteAgentTransport;
+
+  constructor(options: RemoteAgentOptions) {
+    const url = String(options.url || "").trim();
+    if (!url) {
+      throw new Error("RemoteAgent requires a non-empty url");
+    }
+    this.transport = create_remote_agent_transport(url, options.token);
+  }
+
+  /**
+   * 新建一个远程 session。
+   */
+  async createSession(
+    input?: AgentCreateSessionInput,
+  ): Promise<RemoteAgentSession> {
+    const info = await this.transport.create_session(input);
+    return new RemoteSession(this.transport, info.sessionId);
+  }
+
+  /**
+   * 获取一个已存在的远程 session。
+   */
+  async getSession(sessionId: string): Promise<RemoteAgentSession> {
+    const resolved_session_id = String(sessionId || "").trim();
+    if (!resolved_session_id) {
+      throw new Error("getSession requires a non-empty sessionId");
+    }
+    const info = await this.transport.get_info(resolved_session_id);
+    return new RemoteSession(this.transport, info.sessionId);
+  }
+
+  /**
+   * 列出远程 agent 的 session 摘要页。
+   */
+  async listSessions(
+    input?: AgentListSessionsInput,
+  ): Promise<AgentSessionSummaryPage> {
+    return await this.transport.list_sessions(input);
+  }
+
+  /**
+   * 关闭远程 transport。
+   *
+   * 关键点（中文）
+   * - `rpc://` 会关闭底层长连接。
+   * - `http://` / `https://` 没有常驻连接，调用时是安全 no-op。
+   */
+  async close(): Promise<void> {
+    await this.transport.close?.();
+  }
+}