@downcity/agent 1.1.408 → 1.1.437

package/src/plugin/core/PluginRegistry.ts

@@ -1,888 +0,0 @@
-/**
- * Agent plugin runtime。
- *
- * 关键点（中文）
- * - Plugin 只属于 Agent：注册即生效，卸载即不可见。
- * - 注册时自动启动 plugin lifecycle；卸载时自动停止 plugin lifecycle。
- * - action、system、hook、resolve 都统一以“已注册且 ready”为生效边界。
- */
-
-import { to_plugin_view } from "@/plugin/core/PluginCatalog.js";
-import { HookRegistry } from "@/plugin/core/HookRegistry.js";
-import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
-import type {
-  AgentPlugins,
-  AgentPluginExecutionLease,
-  AgentPluginExecutionRuntime,
-  PluginAvailability,
-  PluginActionReadView,
-  PluginReadView,
-  PluginView,
-} from "@/types/plugin/PluginRuntime.js";
-import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-import type { AgentPluginContext } from "@/types/plugin/AgentPluginContext.js";
-import type { JsonValue } from "@/types/common/Json.js";
-import type {
-  PluginRuntimeRecord,
-  PluginSnapshot,
-} from "@/types/plugin/PluginState.js";
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
-import type { SessionInteractionPort } from "@/types/session/SessionInteraction.js";
-import { execute_plugin_action } from "@/plugin/core/PluginActionExecution.js";
-import type { RuntimeTool as Tool } from "@downcity/type";
-import { create_plugin_tools } from "@/plugin/tool/PluginTools.js";
-import type {
-  PluginRegistryChange,
-  PluginRegistrySubscriber,
-  PluginRegistryUnsubscribe,
-} from "@/types/plugin/PluginRegistry.js";
-
-function now_ms(): number {
-  return Date.now();
-}
-
-function normalize_plugin_name(plugin_name: string): string {
-  return String(plugin_name || "").trim();
-}
-
-/** 为当前 Workspace 的指定 Plugin 创建专属运行时 Context。 */
-type PluginContextFactory = (
-  plugin_name: string,
-) => PluginContext;
-
-function create_record(plugin: Plugin): PluginRuntimeRecord {
-  const current_time = now_ms();
-  return {
-    plugin,
-    state: "initializing",
-    registered_at: current_time,
-    updated_at: current_time,
-    chain: Promise.resolve(),
-    lifecycle_started: false,
-    active_execution_leases: 0,
-    retired: false,
-    retirement_started: false,
-  };
-}
-
-function to_plugin_snapshot(record: PluginRuntimeRecord): PluginSnapshot {
-  const plugin = record.plugin;
-  const last_error = String(record.last_error || "").trim();
-  return {
-    name: plugin.name,
-    title: String(plugin.title || plugin.name || "").trim(),
-    description: String(plugin.description || "").trim(),
-    status: record.state,
-    registered_at: record.registered_at,
-    updated_at: record.updated_at,
-    ...(last_error ? { last_error } : {}),
-  };
-}
-
-function update_record_state(
-  record: PluginRuntimeRecord,
-  state: PluginRuntimeRecord["state"],
-  error?: string,
-): void {
-  record.state = state;
-  record.updated_at = now_ms();
-  const normalized_error = String(error || "").trim();
-  if (normalized_error) {
-    record.last_error = normalized_error;
-  } else {
-    delete record.last_error;
-  }
-}
-
-async function run_serial(
-  record: PluginRuntimeRecord,
-  step: () => Promise<void> | void,
-): Promise<void> {
-  const next = record.chain.then(() => Promise.resolve(step()));
-  record.chain = next.then(
-    () => undefined,
-    () => undefined,
-  );
-  await next;
-}
-
-/**
- * PluginRegistry：Agent plugin 注册、卸载与调用实现。
- */
-export class PluginRegistry {
-  private readonly hookRegistry: HookRegistry;
-
-  private readonly records = new Map<string, PluginRuntimeRecord>();
-
-  /** 当前 Registry 所属 Agent 的生命周期上下文。 */
-  private readonly agent_context: AgentPluginContext;
-
-  /** Agent 当前已进入 Workspace 的 Plugin Context 工厂。 */
-  private readonly workspace_context_factories = new Map<string, PluginContextFactory>();
-
-  /** 初始 Plugin lifecycle 的唯一启动流程。 */
-  private initial_start_promise?: Promise<PluginSnapshot[]>;
-
-  private readonly retired_records = new Set<PluginRuntimeRecord>();
-
-  /** Plugin 配置变化订阅器。 */
-  private readonly change_subscribers = new Set<PluginRegistrySubscriber>();
-
-  constructor(agent_context: AgentPluginContext, plugins: Plugin[] = []) {
-    this.agent_context = agent_context;
-    this.hookRegistry = new HookRegistry({
-      is_plugin_ready: (plugin_name) => this.is_ready(plugin_name),
-    });
-    for (const plugin of plugins) {
-      this.mount(plugin);
-    }
-  }
-
-  /** 订阅 Plugin 配置的后续变化。 */
-  subscribe_change(
-    subscriber: PluginRegistrySubscriber,
-  ): PluginRegistryUnsubscribe {
-    this.change_subscribers.add(subscriber);
-    return () => {
-      this.change_subscribers.delete(subscriber);
-    };
-  }
-
-  /** 绑定当前 Workspace 的 Plugin Context 工厂。 */
-  bind_workspace_context(
-    context: PluginContext,
-    factory: PluginContextFactory,
-  ): void {
-    this.workspace_context_factories.set(context.workspace_id, factory);
-  }
-
-  /** 解除当前 Workspace 的 Plugin Context 工厂。 */
-  unbind_workspace_context(context: PluginContext): void {
-    this.workspace_context_factories.delete(context.workspace_id);
-  }
-
-  /** 返回指定 Plugin 的运行时 Context；未绑定工厂时回退到传入 Context。 */
-  plugin_context(context: PluginContext, plugin_name: string): PluginContext {
-    const key = normalize_plugin_name(plugin_name);
-    return this.workspace_context_factories.get(context.workspace_id)?.(key) || context;
-  }
-
-  /**
-   * 返回当前 Registry 向 Agent 提供的 Plugin Tools。
-   *
-   * 关键点（中文）
-   * - 没有任何 Action 时不暴露空壳 Tool。
-   * - Tool 闭包绑定当前 Registry，动态 Plugin 变化无需重建 bridge。
-   */
-  tools(context: PluginContext): Record<string, Tool> {
-    if (!this.list().some((plugin) => plugin.actions.length > 0)) return {};
-    return { ...create_plugin_tools({ plugins: this.contextual(context) }) };
-  }
-
-  /**
-   * 创建绑定当前 Session Workspace 上下文的 Plugin 调用面。
-   *
-   * Registry 只保存 Agent 注册的 Plugin；Action、Hook、System 与 availability 在
-   * 调用时显式使用这里捕获的 Workspace Context。
-   */
-  contextual(context: PluginContext): AgentPlugins {
-    return {
-      register: async (plugin) => await this.register(plugin),
-      unregister: async (plugin_name) => await this.unregister(plugin_name),
-      start_all: async () => await this.start_all(),
-      unregister_all: async () => await this.unregister_all(),
-      has: (plugin_name) => this.has(plugin_name),
-      get: (plugin_name) => this.get(plugin_name),
-      status: (plugin_name) => this.status(plugin_name),
-      snapshots: () => this.snapshots(),
-      list: () => this.list(),
-      read: (params) => this.read(params),
-      availability: async (plugin_name) =>
-        await this.availability(context, plugin_name),
-      run_action: async (params) =>
-        await this.run_action({ context, ...params }),
-      system_blocks: async (execution_context) =>
-        await this.system_blocks(context, execution_context),
-      pipeline: async (point_name, value) =>
-        await this.pipeline(context, point_name, value),
-      guard: async (point_name, value) =>
-        await this.guard(context, point_name, value),
-      effect: async (point_name, value) =>
-        await this.effect(context, point_name, value),
-      resolve: async (point_name, value) =>
-        await this.resolve(context, point_name, value),
-    };
-  }
-
-  /**
-   * 注册单个 plugin。
-   *
-   * 说明（中文）
-   * - 同名注册表示替换：先卸载旧实例，再注册并启动新实例。
-   * - 如果新实例启动失败，会自动回滚为未注册状态并抛错。
-   */
-  async register(plugin: Plugin): Promise<PluginSnapshot> {
-    const key = normalize_plugin_name(plugin.name);
-    if (!key) {
-      throw new Error("Plugin name is required");
-    }
-    if (this.records.has(key)) {
-      await this.unregister(key);
-    }
-
-    const record = create_record(plugin);
-    this.records.set(key, record);
-    this.register_hooks(plugin);
-
-    try {
-      await this.start_record(record);
-      this.publish_change({ type: "register", plugin_name: key });
-      return to_plugin_snapshot(record);
-    } catch (error) {
-      this.unregister_hooks(key);
-      this.records.delete(key);
-      await this.stop_record(record).catch(() => undefined);
-      throw error;
-    }
-  }
-
-  /**
-   * 同步挂载 plugin 元信息。
-   *
-   * 说明（中文）
-   * - 仅供 Agent 构造期使用，避免构造函数里 await。
-   * - 后续 `start_all()` 会统一启动这些初始 plugin。
-   */
-  mount(plugin: Plugin): PluginSnapshot {
-    const key = normalize_plugin_name(plugin.name);
-    if (!key) {
-      throw new Error("Plugin name is required");
-    }
-    if (this.records.has(key)) {
-      throw new Error(`Plugin already registered: ${key}`);
-    }
-
-    const record = create_record(plugin);
-    this.records.set(key, record);
-    this.register_hooks(plugin);
-    return to_plugin_snapshot(record);
-  }
-
-  /**
-   * 从 configured registry 卸载指定 plugin。
-   *
-   * 关键点（中文）
-   * - configured registry、hooks 与直接调用入口立即移除。
-   * - lifecycle.stop 等当前活跃 Session step 的 execution lease 全部释放后执行。
-   * - 该方法返回配置修改结果，不等待仍在运行的 step 结束。
-   */
-  async unregister(plugin_name: string): Promise<boolean> {
-    const key = normalize_plugin_name(plugin_name);
-    if (!key) return false;
-    const record = this.records.get(key);
-    if (!record) return false;
-
-    this.unregister_hooks(key);
-    this.records.delete(key);
-    this.retire_record(record);
-    this.publish_change({ type: "unregister", plugin_name: key });
-    return true;
-  }
-
-  /** 将 Plugin 配置变化发布给 Agent 等持有者。 */
-  private publish_change(change: PluginRegistryChange): void {
-    for (const subscriber of this.change_subscribers) {
-      try {
-        subscriber(change);
-      } catch {
-        // 观察者失败不能回滚已经完成的 Plugin 配置修改。
-      }
-    }
-  }
-
-  /**
-   * 启动全部已挂载 plugin。
-   */
-  async start_all(): Promise<PluginSnapshot[]> {
-    this.initial_start_promise ??= this.start_initial_records();
-    return await this.initial_start_promise;
-  }
-
-  /** 串行启动构造期挂载的 Plugin，并隔离单个 lifecycle 失败。 */
-  private async start_initial_records(): Promise<PluginSnapshot[]> {
-    const initial_records = [...this.records.values()];
-    for (const record of initial_records) {
-      try {
-        await this.start_record(record);
-      } catch {
-        // 关键点（中文）：单个 Plugin 启动失败只影响自身，不能阻断其他 Plugin 与 Agent ready。
-      }
-    }
-    return initial_records.map(to_plugin_snapshot);
-  }
-
-  /** 确保任何异步 Plugin 执行都发生在初始 lifecycle 启动完成后。 */
-  private async ensure_initial_started(): Promise<void> {
-    await this.start_all();
-  }
-
-  /**
-   * 卸载全部 plugin。
-   */
-  async unregister_all(): Promise<void> {
-    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);
-  }
-
-  /**
-   * 判断 plugin 是否已注册且 ready。
-   */
-  is_ready(plugin_name: string): boolean {
-    const record = this.records.get(normalize_plugin_name(plugin_name));
-    return Boolean(record && record.state === "ready");
-  }
-
-  /**
-   * 读取单个 plugin 快照。
-   */
-  status(plugin_name: string): PluginSnapshot | null {
-    const record = this.records.get(normalize_plugin_name(plugin_name));
-    return record ? to_plugin_snapshot(record) : null;
-  }
-
-  /**
-   * 判断 plugin 是否已注册。
-   */
-  has(plugin_name: string): boolean {
-    return this.records.has(normalize_plugin_name(plugin_name));
-  }
-
-  private register_hooks(plugin: Plugin): void {
-    const key = normalize_plugin_name(plugin.name);
-    for (const [hookName, handlers] of Object.entries(
-      plugin.hooks?.pipeline || {},
-    )) {
-      for (const handler of handlers) {
-        this.hookRegistry.pipeline(hookName, key, handler);
-      }
-    }
-
-    for (const [hookName, handlers] of Object.entries(
-      plugin.hooks?.guard || {},
-    )) {
-      for (const handler of handlers) {
-        this.hookRegistry.guard(hookName, key, handler);
-      }
-    }
-
-    for (const [hookName, handlers] of Object.entries(
-      plugin.hooks?.effect || {},
-    )) {
-      for (const handler of handlers) {
-        this.hookRegistry.effect(hookName, key, handler);
-      }
-    }
-
-    for (const [point_name, handler] of Object.entries(plugin.resolves || {})) {
-      this.hookRegistry.resolve(point_name, key, handler);
-    }
-  }
-
-  private unregister_hooks(plugin_name: string): void {
-    this.hookRegistry.unregister_plugin(plugin_name);
-  }
-
-  private async start_record(
-    record: PluginRuntimeRecord,
-  ): Promise<void> {
-    if (record.lifecycle_started) {
-      update_record_state(record, "ready");
-      return;
-    }
-    await run_serial(record, async () => {
-      if (record.lifecycle_started) {
-        update_record_state(record, "ready");
-        return;
-      }
-      try {
-        await record.plugin.lifecycle?.start?.(this.agent_context);
-        record.lifecycle_started = true;
-        update_record_state(record, "ready");
-      } catch (error) {
-        update_record_state(record, "error", String(error));
-        throw error;
-      }
-    });
-  }
-
-  private async stop_record(record: PluginRuntimeRecord): Promise<void> {
-    await run_serial(record, async () => {
-      if (!record.lifecycle_started) return;
-      const errors: unknown[] = [];
-      try {
-        try {
-          await record.plugin.lifecycle?.stop?.(this.agent_context);
-        } catch (error) {
-          errors.push(error);
-        }
-      } finally {
-        record.lifecycle_started = false;
-        record.updated_at = now_ms();
-      }
-      if (errors.length > 0) {
-        throw new AggregateError(errors, `Plugin cleanup failed: ${record.plugin.name}`);
-      }
-    });
-  }
-
-  /**
-   * 运行 pipeline 点。
-   */
-  async pipeline<T = JsonValue>(
-    context: PluginContext,
-    point_name: string,
-    value: T,
-  ): Promise<T> {
-    await this.ensure_initial_started();
-    return this.hookRegistry.pipelineValue(
-      context,
-      point_name,
-      value,
-      (plugin_name) => this.plugin_context(context, plugin_name),
-    );
-  }
-
-  /**
-   * 运行 guard 点。
-   */
-  async guard<T = JsonValue>(
-    context: PluginContext,
-    point_name: string,
-    value: T,
-  ): Promise<void> {
-    await this.ensure_initial_started();
-    return this.hookRegistry.guardValue(
-      context,
-      point_name,
-      value,
-      (plugin_name) => this.plugin_context(context, plugin_name),
-    );
-  }
-
-  /**
-   * 运行 effect 点。
-   */
-  async effect<T = JsonValue>(
-    context: PluginContext,
-    point_name: string,
-    value: T,
-  ): Promise<void> {
-    await this.ensure_initial_started();
-    return this.hookRegistry.effectValue(
-      context,
-      point_name,
-      value,
-      (plugin_name) => this.plugin_context(context, plugin_name),
-    );
-  }
-
-  /**
-   * 运行 resolve 点。
-   */
-  async resolve<TInput = JsonValue, TOutput = JsonValue>(
-    context: PluginContext,
-    point_name: string,
-    value: TInput,
-  ): Promise<TOutput> {
-    await this.ensure_initial_started();
-    return this.hookRegistry.resolveValue<TInput, TOutput>(
-      context,
-      point_name,
-      value,
-      (plugin_name) => this.plugin_context(context, plugin_name),
-    );
-  }
-
-  /**
-   * 获取单个 plugin 定义。
-   */
-  get(plugin_name: string): Plugin | null {
-    return this.records.get(normalize_plugin_name(plugin_name))?.plugin || null;
-  }
-
-  /**
-   * 列出全部 plugin 概览视图。
-   */
-  list(): PluginView[] {
-    return Array.from(this.records.values())
-      .map((record) => to_plugin_view(record.plugin))
-      .sort((a, b) => a.name.localeCompare(b.name));
-  }
-
-  /**
-   * 列出全部 plugin 注册快照。
-   */
-  snapshots(): PluginSnapshot[] {
-    return Array.from(this.records.values())
-      .map((record) => to_plugin_snapshot(record))
-      .sort((a, b) => a.name.localeCompare(b.name));
-  }
-
-  /**
-   * 读取 action metadata。
-   */
-  private readAction(
-    action_name: string,
-    action: NonNullable<Plugin["actions"]>[string],
-  ): PluginActionReadView {
-    return {
-      name: action_name,
-      description: String(action.description || "").trim(),
-      has_input_schema: Boolean(action.input_schema),
-      ...(action.input_schema?.json_schema
-        ? { input_schema: action.input_schema.json_schema }
-        : {}),
-      ...(action.examples ? { examples: action.examples } : {}),
-      has_command: Boolean(action.command),
-      has_api: Boolean(action.api),
-    };
-  }
-
-  /**
-   * 读取 plugin / action metadata。
-   */
-  read(params: {
-    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 plugin_name = normalize_plugin_name(params.plugin || "");
-    if (!plugin_name) {
-      return {
-        plugins: Array.from(records.values())
-          .map((record) => to_plugin_view(record.plugin))
-          .sort((left, right) => left.name.localeCompare(right.name)),
-      };
-    }
-    const plugin = records.get(plugin_name)?.plugin || null;
-    if (!plugin) {
-      throw new Error(`Unknown plugin: ${plugin_name}`);
-    }
-    const action_name = normalize_plugin_name(params.action || "");
-    if (action_name && !plugin.actions?.[action_name]) {
-      throw new Error(`Unknown action: ${plugin_name}.${action_name}`);
-    }
-    const actions = Object.entries(plugin.actions || {})
-      .filter(([name]) => !action_name || name === action_name)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([name, action]) => this.readAction(name, action));
-    return {
-      name: plugin.name,
-      title: String(plugin.title || plugin.name || "").trim(),
-      description: String(plugin.description || "").trim(),
-      actions,
-    };
-  }
-
-  /**
-   * 检查 plugin 可用性。
-   */
-  async availability(
-    context: PluginContext,
-    plugin_name: string,
-  ): Promise<PluginAvailability> {
-    await this.ensure_initial_started();
-    const key = normalize_plugin_name(plugin_name);
-    const record = this.records.get(key);
-    if (!record) {
-      return {
-        enabled: false,
-        available: false,
-        reasons: [`Unknown plugin: ${plugin_name}`],
-      };
-    }
-
-    if (record.state !== "ready") {
-      return {
-        enabled: true,
-        available: false,
-        reasons: [record.last_error || `Plugin "${record.plugin.name}" is not ready`],
-      };
-    }
-
-    if (record.plugin.availability) {
-      return await record.plugin.availability(this.plugin_context(context, key));
-    }
-
-    return {
-      enabled: true,
-      available: true,
-      reasons: [],
-    };
-  }
-
-  /**
-   * 运行 plugin action。
-   */
-  async run_action(params: {
-    context: PluginContext;
-    plugin: string;
-    action: string;
-    payload?: JsonValue;
-    execution_context?: PluginExecutionContext;
-    interactions?: SessionInteractionPort;
-  }): Promise<PluginActionResult<JsonValue>> {
-    await this.ensure_initial_started();
-    return await this.run_action_from_records(this.records, params.context, params);
-  }
-
-  /**
-   * 从指定记录视图运行 plugin action。
-   */
-  private async run_action_from_records(
-    records: ReadonlyMap<string, PluginRuntimeRecord>,
-    context: PluginContext,
-    params: {
-      plugin: string;
-      action: string;
-      payload?: JsonValue;
-      execution_context?: PluginExecutionContext;
-      interactions?: SessionInteractionPort;
-    },
-  ): Promise<PluginActionResult<JsonValue>> {
-    const key = normalize_plugin_name(params.plugin);
-    const record = records.get(key);
-    if (!record) {
-      return {
-        success: false,
-        error: `Unknown plugin: ${params.plugin}`,
-        message: `Unknown plugin: ${params.plugin}`,
-      };
-    }
-
-    const action_name = normalize_plugin_name(params.action);
-    if (!action_name) {
-      return {
-        success: false,
-        error: "action is required",
-        message: "action is required",
-      };
-    }
-
-    if (record.state !== "ready") {
-      return {
-        success: false,
-        error: `Plugin "${record.plugin.name}" is not ready`,
-        message: `Plugin "${record.plugin.name}" is not ready`,
-      };
-    }
-
-    const action = record.plugin.actions?.[action_name];
-    if (!action) {
-      return {
-        success: false,
-        error: `Plugin "${record.plugin.name}" does not implement action "${action_name}"`,
-        message: `Plugin "${record.plugin.name}" does not implement action "${action_name}"`,
-      };
-    }
-
-    return await execute_plugin_action({
-      context: this.plugin_context(context, record.plugin.name),
-      plugin_name: record.plugin.name,
-      action_name,
-      action,
-      payload: (params.payload ?? {}) as JsonValue,
-      ...(params.execution_context
-        ? { snapshot: params.execution_context }
-        : {}),
-      ...(params.interactions ? { interactions: params.interactions } : {}),
-    });
-  }
-
-  /**
-   * 读取当前生效的 plugin system blocks。
-   */
-  async system_blocks(
-    context: PluginContext,
-    execution_context?: PluginExecutionContext,
-  ): Promise<AgentSessionSystemBlock[]> {
-    await this.ensure_initial_started();
-    return await this.system_blocks_from_records(
-      this.records,
-      context,
-      execution_context,
-    );
-  }
-
-  /**
-   * 从指定记录视图解析 plugin system blocks。
-   */
-  private async system_blocks_from_records(
-    records: ReadonlyMap<string, PluginRuntimeRecord>,
-    context: PluginContext,
-    execution_context?: PluginExecutionContext,
-  ): Promise<AgentSessionSystemBlock[]> {
-    const out: AgentSessionSystemBlock[] = [];
-    for (const record of records.values()) {
-      const plugin = record.plugin;
-      if (record.state !== "ready") continue;
-      if (typeof plugin.system !== "function") continue;
-      try {
-        if (typeof plugin.availability === "function") {
-          const plugin_context = this.plugin_context(context, plugin.name);
-          const availability = await plugin.availability(plugin_context);
-          if (!availability.available) continue;
-        }
-        const text = String(
-          await plugin.system(
-            this.plugin_context(context, plugin.name),
-            execution_context,
-          ),
-        ).trim();
-        if (!text) continue;
-        out.push({
-          source: "plugin",
-          name: plugin.name,
-          content: text,
-        });
-      } catch {
-        // 单个 plugin system 失败不应阻断 session 主链路。
-      }
-    }
-    return out;
-  }
-
-  /**
-   * 创建当前 configured registry 的 Session step 执行视图。
-   */
-  execution_view(context: PluginContext): AgentPluginExecutionRuntime {
-    const records = new Map(this.records);
-    return {
-      read: (params) => this.read_from_records(records, params),
-      run_action: async (params) =>
-        await this.run_action_from_records(records, context, params),
-      system_blocks: async (execution_context) =>
-        await this.system_blocks_from_records(records, context, execution_context),
-      acquire: () => this.acquire_execution_view(records, context),
-    };
-  }
-
-  /**
-   * 为单次 Session step 获取 Plugin execution lease。
-   */
-  private acquire_execution_view(
-    records: ReadonlyMap<string, PluginRuntimeRecord>,
-    context: PluginContext,
-  ): 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),
-      run_action: async (params) =>
-        await this.run_action_from_records(leased_records, context, params),
-      system_blocks: async (execution_context) =>
-        await this.system_blocks_from_records(
-          leased_records,
-          context,
-          execution_context,
-        ),
-      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 () => {
-      const logger = this.agent_context.logger;
-      try {
-        await this.stop_record(record);
-      } catch (error) {
-        update_record_state(record, "error", String(error));
-        try {
-          await 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;
-      }
-    })();
-  }
-}