@downcity/agent 1.1.228 → 1.1.236

package/src/plugin/core/PluginRegistry.ts

@@ -13,6 +13,8 @@ import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
 import type {
   AgentPlugins,
+  AgentPluginExecutionLease,
+  AgentPluginExecutionRuntime,
   PluginAvailability,
   PluginActionReadView,
   PluginReadView,
@@ -45,6 +47,9 @@ function create_record(plugin: Plugin): PluginRuntimeRecord {
     updated_at: current_time,
     chain: Promise.resolve(),
     lifecycle_started: false,
+    active_execution_leases: 0,
+    retired: false,
+    retirement_started: false,
   };
 }
 
@@ -101,6 +106,15 @@ export class PluginRegistry implements AgentPlugins {
 
   private readonly records = new Map<string, PluginRuntimeRecord>();
 
+  private readonly retired_records = new Set<PluginRuntimeRecord>();
+
+  private change_listener?: (input: {
+    /** 当前修改是注册还是卸载。 */
+    type: "register" | "unregister";
+    /** 当前修改的 plugin 名称。 */
+    plugin_name: string;
+  }) => void;
+
   constructor(params: {
     contextResolver: ContextResolver;
     hookRegistry: HookRegistry;
@@ -111,6 +125,13 @@ export class PluginRegistry implements AgentPlugins {
     this.pluginInstances = params.pluginInstances;
   }
 
+  /**
+   * 设置 Agent 内部配置修改监听器。
+   */
+  set_change_listener(listener: PluginRegistry["change_listener"]): void {
+    this.change_listener = listener;
+  }
+
   /**
    * 注册单个 plugin。
    *
@@ -134,6 +155,7 @@ export class PluginRegistry implements AgentPlugins {
 
     try {
       await this.start_record(record);
+      this.change_listener?.({ type: "register", plugin_name: key });
       return to_plugin_snapshot(record);
     } catch (error) {
       this.unregister_hooks(key);
@@ -167,7 +189,12 @@ export class PluginRegistry implements AgentPlugins {
   }
 
   /**
-   * 卸载指定 plugin。
+   * 从 configured registry 卸载指定 plugin。
+   *
+   * 关键点（中文）
+   * - configured registry、hooks 与直接调用入口立即移除。
+   * - lifecycle.stop 等当前活跃 Session step 的 execution lease 全部释放后执行。
+   * - 该方法返回配置修改结果，不等待仍在运行的 step 结束。
    */
   async unregister(pluginName: string): Promise<boolean> {
     const key = normalize_plugin_name(pluginName);
@@ -175,10 +202,11 @@ export class PluginRegistry implements AgentPlugins {
     const record = this.records.get(key);
     if (!record) return false;
 
-    await this.stop_record(record);
     this.unregister_hooks(key);
     this.records.delete(key);
     this.pluginInstances.delete(key);
+    this.retire_record(record);
+    this.change_listener?.({ type: "unregister", plugin_name: key });
     return true;
   }
 
@@ -205,6 +233,10 @@ export class PluginRegistry implements AgentPlugins {
     for (const name of Array.from(this.records.keys())) {
       await this.unregister(name);
     }
+    const retirements = Array.from(this.retired_records)
+      .map((record) => record.retirement_promise)
+      .filter((promise): promise is Promise<void> => Boolean(promise));
+    await Promise.all(retirements);
   }
 
   /**
@@ -381,11 +413,25 @@ export class PluginRegistry implements AgentPlugins {
     plugin?: string;
     action?: string;
   }): PluginReadView | { plugins: PluginView[] } {
+    return this.read_from_records(this.records, params);
+  }
+
+  /**
+   * 从指定记录视图读取 plugin/action metadata。
+   */
+  private read_from_records(
+    records: ReadonlyMap<string, PluginRuntimeRecord>,
+    params: { plugin?: string; action?: string },
+  ): PluginReadView | { plugins: PluginView[] } {
     const pluginName = normalize_plugin_name(params.plugin || "");
     if (!pluginName) {
-      return { plugins: this.list() };
+      return {
+        plugins: Array.from(records.values())
+          .map((record) => toPluginView(record.plugin))
+          .sort((left, right) => left.name.localeCompare(right.name)),
+      };
     }
-    const plugin = this.get(pluginName);
+    const plugin = records.get(pluginName)?.plugin || null;
     if (!plugin) {
       return {
         name: pluginName,
@@ -470,8 +516,22 @@ export class PluginRegistry implements AgentPlugins {
     action: string;
     payload?: JsonValue;
   }): Promise<PluginActionResult<JsonValue>> {
+    return await this.run_action_from_records(this.records, params);
+  }
+
+  /**
+   * 从指定记录视图运行 plugin action。
+   */
+  private async run_action_from_records(
+    records: ReadonlyMap<string, PluginRuntimeRecord>,
+    params: {
+      plugin: string;
+      action: string;
+      payload?: JsonValue;
+    },
+  ): Promise<PluginActionResult<JsonValue>> {
     const key = normalize_plugin_name(params.plugin);
-    const record = this.records.get(key);
+    const record = records.get(key);
     if (!record) {
       return {
         success: false,
@@ -536,9 +596,18 @@ export class PluginRegistry implements AgentPlugins {
    * 读取当前生效的 plugin system blocks。
    */
   async systemBlocks(): Promise<AgentSessionSystemBlock[]> {
+    return await this.system_blocks_from_records(this.records);
+  }
+
+  /**
+   * 从指定记录视图解析 plugin system blocks。
+   */
+  private async system_blocks_from_records(
+    records: ReadonlyMap<string, PluginRuntimeRecord>,
+  ): Promise<AgentSessionSystemBlock[]> {
     const context = this.contextResolver();
     const out: AgentSessionSystemBlock[] = [];
-    for (const record of this.records.values()) {
+    for (const record of records.values()) {
       const plugin = record.plugin;
       if (record.state !== "ready") continue;
       if (typeof plugin.system !== "function") continue;
@@ -560,4 +629,116 @@ export class PluginRegistry implements AgentPlugins {
     }
     return out;
   }
+
+  /**
+   * 创建当前 configured registry 的 Session step 执行视图。
+   */
+  execution_view(): AgentPluginExecutionRuntime {
+    const records = new Map(this.records);
+    return {
+      read: (params) => this.read_from_records(records, params),
+      runAction: async (params) =>
+        await this.run_action_from_records(records, params),
+      systemBlocks: async () =>
+        await this.system_blocks_from_records(records),
+      acquire: () => this.acquire_execution_view(records),
+    };
+  }
+
+  /**
+   * 为单次 Session step 获取 Plugin execution lease。
+   */
+  private acquire_execution_view(
+    records: ReadonlyMap<string, PluginRuntimeRecord>,
+  ): AgentPluginExecutionLease {
+    const leased_records = new Map<string, PluginRuntimeRecord>();
+    for (const [name, record] of records) {
+      if (
+        record.retired ||
+        record.state !== "ready" ||
+        !record.lifecycle_started
+      ) {
+        continue;
+      }
+      record.active_execution_leases += 1;
+      leased_records.set(name, record);
+    }
+
+    let released = false;
+    return {
+      read: (params) => this.read_from_records(leased_records, params),
+      runAction: async (params) =>
+        await this.run_action_from_records(leased_records, params),
+      systemBlocks: async () =>
+        await this.system_blocks_from_records(leased_records),
+      release: async () => {
+        if (released) return;
+        released = true;
+        const retirements: Promise<void>[] = [];
+        for (const record of leased_records.values()) {
+          record.active_execution_leases = Math.max(
+            0,
+            record.active_execution_leases - 1,
+          );
+          this.try_finalize_retired_record(record);
+          if (record.retired && record.retirement_promise) {
+            retirements.push(record.retirement_promise);
+          }
+        }
+        await Promise.all(retirements);
+      },
+    };
+  }
+
+  /**
+   * 把已移出 configured registry 的 Plugin 标记为等待释放。
+   */
+  private retire_record(record: PluginRuntimeRecord): void {
+    if (record.retired) return;
+    record.retired = true;
+    let resolve_retirement!: () => void;
+    record.retirement_promise = new Promise<void>((resolve) => {
+      resolve_retirement = resolve;
+    });
+    record.resolve_retirement = resolve_retirement;
+    this.retired_records.add(record);
+    this.try_finalize_retired_record(record);
+  }
+
+  /**
+   * 在最后一个 execution lease 释放后停止退休 Plugin。
+   */
+  private try_finalize_retired_record(record: PluginRuntimeRecord): void {
+    if (
+      !record.retired ||
+      record.retirement_started ||
+      record.active_execution_leases > 0
+    ) {
+      return;
+    }
+    record.retirement_started = true;
+    void (async () => {
+      try {
+        await this.stop_record(record);
+      } catch (error) {
+        update_record_state(record, "error", String(error));
+        try {
+          await this.contextResolver().logger.log(
+            "error",
+            "[plugin] lifecycle.stop failed after execution release",
+            {
+              plugin: record.plugin.name,
+              error: String(error),
+            },
+          );
+        } catch {
+          // 退休清理不能因日志失败再次中断。
+        }
+      } finally {
+        this.retired_records.delete(record);
+        record.resolve_retirement?.();
+        delete record.resolve_retirement;
+      }
+    })();
+  }
 }

package/src/rpc/Client.ts

@@ -217,6 +217,18 @@ export class RpcClient {
     return data.result;
   }
 
+  /**
+   * 把一次显式历史压缩加入远程 Session 的有序输入队列。
+   */
+  async compact_session(session_id: string): Promise<void> {
+    await this.request<{ queued: true }>({
+      method: "sdk.sessions.compact",
+      params: {
+        sessionId: session_id,
+      },
+    });
+  }
+
   /**
    * 读取 session records。
    */

package/src/session/Session.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
  * - 对外保留稳定 Session facade，把状态、turn、view 逻辑下沉到独立 service。
- * - 内部继续复用 `Executor` / `JsonlSessionHistoryStore` / Composer 体系。
+ * - 内部使用 `SessionRecorder` 统一管理 Active、Segment 与流式 Assistant 草稿。
  */
 
 import { Executor } from "@executor/Executor.js";
@@ -55,6 +55,7 @@ import { SessionStateService } from "@/session/services/SessionStateService.js";
 import { SessionTurnService } from "@/session/services/SessionTurnService.js";
 import { SessionViewService } from "@/session/services/SessionViewService.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
+import type { AgentSessionCommand } from "@/types/session/SessionQueueCommand.js";
 import type {
   SessionComposerFactoryContext,
   SessionComposerInput,
@@ -65,6 +66,7 @@ import type { SessionContextComposer } from "@/executor/composer/context/Session
 import type { SessionHistoryComposer } from "@/executor/composer/history/SessionHistoryComposer.js";
 import type { SessionSystemComposer } from "@/executor/composer/system/SessionSystemComposer.js";
 import type { SessionOptions } from "@/types/session/SessionOptions.js";
+import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
 
 /**
  * SDK 本地 Session。
@@ -92,6 +94,11 @@ export class Session implements AgentSession {
   private readonly set_approval_mode_hook: SessionOptions["set_approval_mode"];
   private readonly resolve_approval_hook: SessionOptions["resolve_approval"];
   private readonly localState: SessionLocalState;
+  private readonly getAgentEnv: SessionOptions["getAgentEnv"];
+  private readonly get_agent_plugins: SessionOptions["get_agent_plugins"];
+  private effective_instruction_system_blocks: AgentSessionSystemBlock[];
+  private effective_agent_env: Record<string, string>;
+  private effective_agent_plugins: AgentPluginExecutionRuntime;
   private readonly stateService: SessionStateService;
   private readonly turnService: SessionTurnService;
   private readonly viewService: SessionViewService<this>;
@@ -104,6 +111,13 @@ export class Session implements AgentSession {
     this.tools = options.tools;
     this.logger = options.logger;
     this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
+    this.getAgentEnv = options.getAgentEnv;
+    this.get_agent_plugins = options.get_agent_plugins;
+    this.effective_instruction_system_blocks = options
+      .getInstructionSystemBlocks()
+      .map((block) => ({ ...block }));
+    this.effective_agent_env = { ...options.getAgentEnv() };
+    this.effective_agent_plugins = options.get_agent_plugins();
     this.getManagedPluginSystemBlocks = options.getManagedPluginSystemBlocks;
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     this.ensureConfiguredHook = options.ensureConfigured;
@@ -187,9 +201,11 @@ export class Session implements AgentSession {
       state_service: this.stateService,
       logger: this.logger,
       is_executing: () => this.isExecuting(),
-      get_instruction_system_blocks: this.getInstructionSystemBlocks,
+      get_instruction_system_blocks: () =>
+        this.effective_instruction_system_blocks.map((block) => ({ ...block })),
       get_managed_plugin_system_blocks: this.getManagedPluginSystemBlocks,
-      get_plugin_system_blocks: this.getPluginSystemBlocks,
+      get_plugin_system_blocks: async () =>
+        await this.effective_agent_plugins.systemBlocks(),
       ...(this.composers?.systemComposer
         ? { custom_system_composer: system_composer }
         : {}),
@@ -226,7 +242,10 @@ export class Session implements AgentSession {
    * 写入当前 session 默认配置。
    */
   async set(input: AgentSessionSetInput): Promise<void> {
-    await this.stateService.set(input);
+    const configured = await this.stateService.set(input);
+    if (configured.command) {
+      this.turnService.enqueue_command(configured.command);
+    }
   }
 
   /**
@@ -243,6 +262,55 @@ export class Session implements AgentSession {
     return await this.turnService.stop();
   }
 
+  /**
+   * 把一次显式历史压缩加入当前 Session 的有序输入队列。
+   */
+  async compact(): Promise<void> {
+    await this.turnService.compact();
+  }
+
+  /**
+   * 把 Agent configured state command 加入当前 Session 的统一输入队列。
+   */
+  enqueue_agent_command(command: AgentSessionCommand): void {
+    this.turnService.enqueue_command({
+      type: "command",
+      command_id: command.command_id,
+      scope: "agent",
+      execute: async ({ turn_id }) => {
+        if (command.type === "instruction") {
+          this.effective_instruction_system_blocks = command
+            .instruction_blocks
+            .map((block) => ({ ...block }));
+          await this.stateService.emit_config_action_event({
+            id: `agent-instruction:${this.id}:${command.command_id}`,
+            title: "Agent instruction updated",
+            state: "completed",
+            turnId: turn_id,
+          });
+          return;
+        }
+        if (command.type === "env") {
+          this.effective_agent_env = { ...command.env };
+          await this.stateService.emit_config_action_event({
+            id: `agent-env:${this.id}:${command.command_id}`,
+            title: "Agent environment updated",
+            state: "completed",
+            turnId: turn_id,
+          });
+          return;
+        }
+        this.effective_agent_plugins = command.plugins;
+        await this.stateService.emit_config_action_event({
+          id: `agent-plugins:${this.id}:${command.command_id}`,
+          title: command.title,
+          state: "completed",
+          turnId: turn_id,
+        });
+      },
+    });
+  }
+
   /**
    * 订阅当前 Session 的未来事件。
    */
@@ -388,8 +456,11 @@ export class Session implements AgentSession {
       tools: this.tools,
       logger: this.logger,
       getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getAgentEnv: this.getAgentEnv,
+      get_agent_plugins: this.get_agent_plugins,
       getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-      getPluginSystemBlocks: this.getPluginSystemBlocks,
+      getPluginSystemBlocks: async () =>
+        await this.effective_agent_plugins.systemBlocks(),
       ensureConfigured: this.ensureConfiguredHook,
       composers: this.composers,
       list_approvals: this.list_approvals,
@@ -422,7 +493,7 @@ export class Session implements AgentSession {
     const messages_dir_path = `${session_dir_path}/messages`;
     return new JsonlSessionMessageStore({
       session_id: this.id,
-      file_path: `${messages_dir_path}/messages.jsonl`,
+      file_path: `${messages_dir_path}/active.jsonl`,
       assistant_message_file_path: getSdkAgentSessionAssistantMessagePath(
         this.projectRoot,
         this.agentId,
@@ -441,6 +512,7 @@ export class Session implements AgentSession {
   private create_local_state(): SessionLocalState {
     return {
       sessionConfig: {},
+      effective_session_config: {},
       createdAt: Date.now(),
       timezone: resolveSystemTimezone(),
       initializePromise: null,
@@ -455,9 +527,11 @@ export class Session implements AgentSession {
       sessionId: this.id,
       historyStore: this.historyStore,
       getTools: () => this.tools,
-      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getInstructionSystemBlocks: () =>
+        this.effective_instruction_system_blocks.map((block) => ({ ...block })),
       getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-      getPluginSystemBlocks: this.getPluginSystemBlocks,
+      getPluginSystemBlocks: async () =>
+        await this.effective_agent_plugins.systemBlocks(),
       getSessionCreatedAt: () => this.localState.createdAt,
       getSessionTimezone: () => this.localState.timezone,
     };
@@ -482,9 +556,11 @@ export class Session implements AgentSession {
         projectRoot: this.projectRoot,
         getSessionCreatedAt: () => this.localState.createdAt,
         getSessionTimezone: () => this.localState.timezone,
-        getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+        getInstructionSystemBlocks: () =>
+          this.effective_instruction_system_blocks.map((block) => ({ ...block })),
         getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-        getPluginSystemBlocks: this.getPluginSystemBlocks,
+        getPluginSystemBlocks: async () =>
+          await this.effective_agent_plugins.systemBlocks(),
       }),
     );
   }
@@ -516,10 +592,20 @@ export class Session implements AgentSession {
       sessionId: this.id,
       historyStore: this.historyStore,
       historyComposer: this.historyComposer,
-      getModel: () => this.localState.sessionConfig.model,
+      getModel: () =>
+        this.localState.effective_session_config.model ||
+        this.localState.sessionConfig.model,
+      get_model_context_window: () =>
+        this.localState.effective_session_config.model
+          ? this.localState.effective_session_config.model_context_window
+          : this.localState.sessionConfig.model_context_window,
       logger: this.logger,
       systemComposer: system_composer,
       getTools: () => this.tools,
+      getEnv: () => ({ ...this.effective_agent_env }),
+      get_systems: () =>
+        this.effective_instruction_system_blocks.map((block) => block.content),
+      get_plugins: () => this.effective_agent_plugins,
       ...(context_composer ? { contextComposer: context_composer } : {}),
       ...(compaction_composer
         ? { compactionComposer: compaction_composer }

package/src/session/SessionSystemBuilder.ts

@@ -253,7 +253,10 @@ export class SessionSystemBuilder implements SessionSystemComposer {
       timezone: this.getSessionTimezone(),
       getInstructionSystemBlocks: this.getInstructionSystemBlocks,
       getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
-      getPluginSystemBlocks: this.getPluginSystemBlocks,
+      getPluginSystemBlocks: async () =>
+        run_context.agentPlugins
+          ? await run_context.agentPlugins.systemBlocks()
+          : await this.getPluginSystemBlocks(),
     });
   }
 }