@downcity/agent 1.1.129 → 1.1.148

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

@@ -2,15 +2,14 @@
  * AgentAssemblyService：本地 Agent 装配服务。
  *
  * 关键点（中文）
- * - 统一装配 logger、config、env、runtime、context 与 plugin registry。
+ * - 统一装配 logger、config、env、context 与 plugin registry。
  * - 该服务只负责一次性长期对象装配，不负责 session 缓存和生命周期启动。
  * - session/lifecycle service 通过它暴露的长期对象协作，避免在 facade 中重复拼装。
  */
 
 import type { LanguageModel, Tool } from "ai";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+import { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type { AgentOptions } from "@/types/agent/AgentTypes.js";
@@ -25,9 +24,9 @@ import {
   createAgentPluginRegistry,
 } from "@/agent/local/AgentPluginFactory.js";
 import {
-  createAgentContext,
-  createAgentRuntime,
-} from "@/agent/local/AgentRuntimeFactory.js";
+  createAgentPathRuntime,
+  createAgentPluginConfigRuntime,
+} from "@/agent/local/AgentRuntimeAssembly.js";
 import {
   plugin_tools,
   setPluginToolRuntime,
@@ -114,11 +113,6 @@ export interface AgentAssemblyResult {
    */
   plugins: AgentPlugins;
 
-  /**
-   * 当前 agent runtime。
-   */
-  runtime: AgentRuntime;
-
   /**
    * 当前 agent context。
    */
@@ -165,46 +159,59 @@ export class AgentAssemblyService {
 
     const logger = new Logger();
     logger.bindProjectRoot(path);
+    // 关键点（中文）
+    // - 这里产出的 env 是 agent 全生命周期共享的 mutable 对象引用。
+    // - context / shell 都持有同一引用；后续 `agent.setEnv()` 会原地修改它。
     const env = resolveAgentEnv(path, this.options.env);
     const instruction = normalizeInstructionInput(this.options.instruction);
     const config = this.load_config(id, path);
     const plugin_instances = new Map<string, BasePlugin>();
 
-    const runtime = createAgentRuntime({
-      agent_id: id,
-      project_root: path,
-      logger,
-      config,
-      env,
-      systems: instruction,
-      plugin_instances,
-      get_session_port: this.get_session_port,
-      list_cached_sessions: this.list_cached_sessions,
-    });
-
     this.register_plugins(plugin_instances, this.options.plugins || []);
 
-    let agent_context!: AgentContext;
+    // 关键点（中文）
+    // - plugin_registry 仍然延迟读取 agent_context（避免循环依赖）。
+    // - context 一构造完就赋值，registry 第一次读 get_context 时已经是非空。
+    let agent_context: AgentContext | undefined;
     const plugin_registry = createAgentPluginRegistry({
       plugins: [...plugin_instances.values()],
-      get_context: () => agent_context,
+      get_context: () => {
+        if (!agent_context) {
+          throw new Error("AgentContext is not assembled yet");
+        }
+        return agent_context;
+      },
     });
     const plugins = plugin_registry;
     if (this.should_register_plugin_call_tool(plugin_instances)) {
       tools.plugin_call = tools.plugin_call || plugin_tools.plugin_call;
     }
-    agent_context = createAgentContext({
-      runtime,
-      project_root: path,
+    const resolve_session_model = this.resolve_session_model;
+    const paths = createAgentPathRuntime(path, id);
+    const pluginConfig = createAgentPluginConfigRuntime(path);
+    agent_context = new AgentContext({
+      cwd: path,
+      rootPath: path,
       logger,
       config,
       env,
       systems: instruction,
-      plugin_instances,
+      paths,
+      pluginConfig,
+      pluginInstances: plugin_instances,
+      session: {
+        get: (session_id) => this.get_session_port(session_id),
+        listExecutingSessionIds: () =>
+          this.list_cached_sessions()
+            .filter((session) => session.isExecuting())
+            .map((session) => session.id),
+        getExecutingSessionCount: () =>
+          this.list_cached_sessions()
+            .filter((session) => session.isExecuting()).length,
+        resolveModel: async (session_id) =>
+          await resolve_session_model(session_id),
+      },
       plugins,
-      get_session_port: this.get_session_port,
-      resolve_session_model: async (session_id) =>
-        await this.resolve_session_model(session_id),
     });
     const shell = this.options.shell;
     if (shell) {
@@ -216,7 +223,7 @@ export class AgentAssemblyService {
         emit_event: (event) => {
           const session_id = String(event.session_id || "").trim();
           if (!session_id) return;
-          agent_context.session.get(session_id).publishEvent(event as unknown as AgentSessionEvent);
+      agent_context!.session.get(session_id).publishEvent(event as unknown as AgentSessionEvent);
         },
       });
       Object.assign(tools, shell.tools);
@@ -234,8 +241,7 @@ export class AgentAssemblyService {
       plugin_instances,
       plugin_registry,
       plugins,
-      runtime,
-      agent_context,
+      agent_context: agent_context!,
       ...(shell ? { shell } : {}),
     };
   }

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

@@ -0,0 +1,116 @@
+/**
+ * AgentBackgroundService：本地 Agent 后台能力生命周期服务。
+ *
+ * 关键点（中文）
+ * - 统一管理 plugins 与 ActionSchedule 的启动 / 停止。
+ * - 在 Agent 构造阶段自动启动后台能力，调用方通过 `await agent.ready()` 等待启动完成。
+ * - RPC / HTTP 等 transport 不再属于 Agent 内部职责，由 `@downcity/server` 等外部包按需挂载。
+ */
+
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.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 type { Shell } from "@downcity/shell";
+
+type AgentBackgroundServiceOptions = {
+  /**
+   * 当前统一日志器。
+   */
+  logger: Logger;
+
+  /**
+   * 当前 agent context。
+   */
+  agent_context: AgentContext;
+
+  /**
+   * 读取当前 agent 挂载的 Shell。
+   */
+  get_shell?: () => Shell | undefined;
+};
+
+/**
+ * 本地 Agent 后台能力生命周期服务。
+ *
+ * 关键点（中文）
+ * - 构造时自动触发 plugin lifecycle 与 ActionSchedule 启动。
+ * - 失败由 logger.error 记录，不抛错；调用方通过 `ready()` 等待启动完成。
+ */
+export class AgentBackgroundService {
+  private readonly logger: Logger;
+  private readonly agent_context: AgentContext;
+  private readonly get_shell: AgentBackgroundServiceOptions["get_shell"];
+
+  private plugins_started = false;
+  private action_schedule_runtime: ActionScheduleRuntimeHandle | null = null;
+  private ready_promise: Promise<void> | null = null;
+
+  constructor(options: AgentBackgroundServiceOptions) {
+    this.logger = options.logger;
+    this.agent_context = options.agent_context;
+    this.get_shell = options.get_shell;
+    // 关键点（中文）：Agent 构造完成即触发后台启动，不再要求外部显式 `start()`。
+    this.ready_promise = this.boot();
+  }
+
+  /**
+   * 等待后台能力启动完成。
+   */
+  async ready(): Promise<void> {
+    if (!this.ready_promise) return;
+    await this.ready_promise;
+  }
+
+  /**
+   * 释放当前 Agent 的后台能力。
+   */
+  async dispose(): Promise<void> {
+    if (this.ready_promise) {
+      await this.ready_promise.catch(() => undefined);
+      this.ready_promise = null;
+    }
+    if (this.plugins_started) {
+      await this.stop_action_schedule_runtime();
+      await stopAllPlugins(this.agent_context);
+      this.plugins_started = false;
+    }
+    await this.get_shell?.()?.dispose();
+  }
+
+  private async boot(): Promise<void> {
+    await this.ensure_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();
+  }
+}

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

@@ -13,6 +13,11 @@ import type { Tool } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type {
   AgentCreateSessionInput,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentListSessionsInput,
   AgentManagedSession,
   AgentModel,
@@ -24,16 +29,26 @@ import type {
 } from "@/types/agent/AgentTypes.js";
 import { Session } from "@/session/Session.js";
 import {
+  getSdkAgentArchivedSessionDirPath,
+  getSdkAgentArchivedSessionsDirPath,
   getSdkAgentSessionDirPath,
+  listArchivedAgentSessionSummaryPage,
   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";
 
+function decodeMaybe(input: string): string {
+  try {
+    return decodeURIComponent(input);
+  } catch {
+    return input;
+  }
+}
+
 type AgentSessionManagerOptions = {
   /**
    * 当前 agent 稳定标识。
@@ -55,13 +70,11 @@ type AgentSessionManagerOptions = {
    */
   logger: Logger;
 
-  /**
-   * 当前 agent runtime。
-   */
-  runtime: AgentRuntime;
-
   /**
    * 延迟读取当前 agent context。
+   *
+   * 关键点（中文）
+   * - 装配期通过 getter 拿到 context，避免循环引用。
    */
   get_agent_context: () => AgentContext;
 
@@ -94,7 +107,6 @@ export class AgentSessionManager {
   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>;
@@ -109,16 +121,18 @@ export class AgentSessionManager {
     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),
+      create_session: async (input) => await this.create_session(input),
+      get_session: async (session_id) => await this.get_session(session_id),
+      list_sessions: async (input) => await this.list_sessions(input),
+      archive_session: async (input) => await this.archive_session(input),
+      archive_sessions: async (input) => await this.archive_sessions(input),
+      clean_archive: async () => await this.clean_archive(),
     };
   }
 
@@ -180,7 +194,7 @@ export class AgentSessionManager {
   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");
+      throw new Error("get_session requires a non-empty sessionId");
     }
     const session_dir_path = getSdkAgentSessionDirPath(
       this.project_root,
@@ -211,10 +225,110 @@ export class AgentSessionManager {
       projectRoot: this.project_root,
       agentId: this.agent_id,
       input,
-      executingSessionIds: new Set(this.runtime.listExecutingSessionIds()),
+      executingSessionIds: new Set(this.get_agent_context().listExecutingSessionIds()),
     });
   }
 
+  /**
+   * 归档单个 session。
+   */
+  async archive_session(
+    input: AgentArchiveSessionInput,
+  ): Promise<AgentArchiveSessionResult> {
+    const session_id = String(input?.id || "").trim();
+    if (!session_id) {
+      throw new Error("archive_session requires a non-empty id");
+    }
+
+    const executing_session_ids = new Set(
+      this.get_agent_context().listExecutingSessionIds(),
+    );
+    if (executing_session_ids.has(session_id)) {
+      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);
+
+    // 关键点（中文）：归档后清理缓存，避免后续操作访问已移动目录。
+    this.sessions_by_id.delete(session_id);
+    this.configured_session_ids.delete(session_id);
+
+    return {
+      sessionId: session_id,
+      archivedAt: Date.now(),
+    };
+  }
+
+  /**
+   * 列出当前 agent 的已归档 session 摘要页。
+   */
+  async archive_sessions(
+    input?: AgentArchiveSessionsInput,
+  ): Promise<AgentArchiveSessionsResult> {
+    return await listArchivedAgentSessionSummaryPage({
+      projectRoot: this.project_root,
+      agentId: this.agent_id,
+      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,
+    };
+  }
+
   private get_or_create_session(input?: {
     /**
      * 可选指定 session id。

package/src/agent/remote/RemoteAgent.ts

@@ -8,9 +8,7 @@
  */
 
 import type {
-  AgentCreateSessionInput,
-  AgentListSessionsInput,
-  AgentSessionSummaryPage,
+  AgentSessionCollection,
   RemoteAgentPluginActionInput,
   RemoteAgentPluginActionResult,
   RemoteAgentOptions,
@@ -42,37 +40,6 @@ export class RemoteAgent {
     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);
-  }
-
   /**
    * 执行远程 Agent runtime 内的 plugin action。
    *
@@ -153,4 +120,28 @@ export class RemoteAgent {
   async close(): Promise<void> {
     await this.transport.close?.();
   }
+
+  /**
+   * 返回当前远程 session collection 入口。
+   *
+   * 关键点（中文）
+   * - `RemoteAgentTransport` 只负责协议传输，不直接等价于 `AgentSessionCollection`。
+   * - 这里把 transport 包装为 `AgentSessionCollection`，`create_session` / `get_session` 返回 `RemoteSession` 实例。
+   */
+  session_collection(): AgentSessionCollection {
+    return {
+     create_session: async (input) => {
+       const info = await this.transport.create_session(input);
+        return new RemoteSession(this.transport, info);
+      },
+      get_session: async (session_id) => {
+        const info = await this.transport.get_info(session_id);
+        return new RemoteSession(this.transport, info);
+      },
+      list_sessions: async (input) => await this.transport.list_sessions(input),
+      archive_session: async (input) => await this.transport.archive_session(input),
+      archive_sessions: async (input) => await this.transport.archive_sessions(input),
+      clean_archive: async () => await this.transport.clean_archive(),
+    };
+  }
 }

package/src/agent/remote/RemoteSession.ts

@@ -7,14 +7,16 @@
  */
 
 import type {
+  AgentSession,
+  AgentSessionConfigSnapshot,
   AgentSessionForkInput,
   AgentSessionHistoryInput,
   AgentSessionHistoryPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSystemSnapshot,
-  RemoteAgentSession,
 } from "@/types/agent/AgentTypes.js";
+import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
   AgentSessionEvent,
   AgentSessionSubscriber,
@@ -50,8 +52,10 @@ type RemoteTurnLifecycle = {
 /**
  * 远程 Session 客户端。
  */
-export class RemoteSession implements RemoteAgentSession {
+export class RemoteSession implements AgentSession {
   readonly id: string;
+  readonly agentId: string;
+  readonly config: AgentSessionConfigSnapshot;
 
   private readonly transport: RemoteSessionTransport;
   private readonly event_hub = new SessionEventHub();
@@ -62,9 +66,12 @@ export class RemoteSession implements RemoteAgentSession {
   private event_subscriber_count = 0;
   private event_subscription: TransportSubscription | null = null;
 
-  constructor(transport: RemoteSessionTransport, session_id: string) {
+  constructor(transport: RemoteSessionTransport, info: AgentSessionInfo) {
     this.transport = transport;
-    this.id = session_id;
+    this.id = info.sessionId;
+    this.agentId = info.agentId;
+    // 远程 session 不暴露服务端模型实例，config 返回空快照。
+    this.config = {} as AgentSessionConfigSnapshot;
   }
 
   /**
@@ -98,6 +105,14 @@ export class RemoteSession implements RemoteAgentSession {
     return create_turn_handle(lifecycle);
   }
 
+  /**
+   * 停止当前远程 session turn，并取消未吸收队列。
+   */
+  async stop(): Promise<AgentSessionStopResult> {
+    await this.ensure_event_pump();
+    return await this.transport.stop(this.id);
+  }
+
   /**
    * 订阅当前远程 session 的 future 事件。
    */
@@ -134,9 +149,9 @@ export class RemoteSession implements RemoteAgentSession {
   /**
    * 分叉远程 session。
    */
-  async fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession> {
+  async fork(input?: AgentSessionForkInput | string): Promise<AgentSession> {
     const info = await this.transport.fork(this.id, input);
-    return new RemoteSession(this.transport, info.sessionId);
+    return new RemoteSession(this.transport, info);
   }
 
   private async ensure_event_pump(): Promise<void> {

package/src/agent/remote/RemoteTransport.ts

@@ -9,12 +9,18 @@
 import type {
   AgentCreateSessionInput,
   AgentListSessionsInput,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentSessionForkInput,
   AgentSessionHistoryInput,
   AgentSessionHistoryPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
+  AgentSessionStopResult,
   RemoteAgentPluginActionInput,
   RemoteAgentPluginActionResult,
 } from "@/types/agent/AgentTypes.js";
@@ -48,6 +54,8 @@ export type RemoteSessionTransport = {
     session_id: string,
     input: AgentSessionPromptInput,
   ): Promise<{ id: string }>;
+  /** 停止当前 session turn，并取消未吸收队列。 */
+  stop(session_id: string): Promise<AgentSessionStopResult>;
   /** 订阅 session 事件。 */
   subscribe(params: {
     session_id: string;
@@ -76,6 +84,12 @@ export type RemoteAgentTransport = RemoteSessionTransport & {
   create_session(input?: AgentCreateSessionInput): Promise<AgentSessionInfo>;
   /** 列出 sessions。 */
   list_sessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
+  /** 归档 session。 */
+  archive_session(input: AgentArchiveSessionInput): Promise<AgentArchiveSessionResult>;
+  /** 列出已归档 sessions。 */
+  archive_sessions(input?: AgentArchiveSessionsInput): Promise<AgentArchiveSessionsResult>;
+  /** 清空归档 sessions。 */
+  clean_archive(): Promise<AgentCleanArchiveResult>;
   /** 执行远程 Agent runtime 内的 plugin action。 */
   run_plugin_action(
     input: RemoteAgentPluginActionInput,