/**
 * Agent plugin runtime。
 *
 * 关键点（中文）
 * - Plugin 只属于 Agent：注册即生效，卸载即不可见。
 * - 注册时自动启动 plugin lifecycle；卸载时自动停止 plugin lifecycle。
 * - action、system、hook、resolve 都统一以“已注册且 ready”为生效边界。
 */
import type { Plugin } from "../../types/plugin/PluginDefinition.js";
import type { PluginActionResult } from "../../types/plugin/PluginAction.js";
import type { AgentPlugins, AgentPluginExecutionRuntime, PluginAvailability, 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 { PluginSnapshot } from "../../types/plugin/PluginState.js";
import type { PluginExecutionContext } from "../../types/plugin/PluginExecutionContext.js";
import type { SessionInteractionPort } from "../../types/session/SessionInteraction.js";
import type { RuntimeTool as Tool } from "@downcity/type";
import type { PluginRegistrySubscriber, PluginRegistryUnsubscribe } from "../../types/plugin/PluginRegistry.js";
/** 为当前 Workspace 的指定 Plugin 创建专属运行时 Context。 */
type PluginContextFactory = (plugin_name: string) => PluginContext;
/**
 * PluginRegistry：Agent plugin 注册、卸载与调用实现。
 */
export declare class PluginRegistry {
    private readonly hookRegistry;
    private readonly records;
    /** 当前 Registry 所属 Agent 的生命周期上下文。 */
    private readonly agent_context;
    /** Agent 当前已进入 Workspace 的 Plugin Context 工厂。 */
    private readonly workspace_context_factories;
    /** 初始 Plugin lifecycle 的唯一启动流程。 */
    private initial_start_promise?;
    private readonly retired_records;
    /** Plugin 配置变化订阅器。 */
    private readonly change_subscribers;
    constructor(agent_context: AgentPluginContext, plugins?: Plugin[]);
    /** 订阅 Plugin 配置的后续变化。 */
    subscribe_change(subscriber: PluginRegistrySubscriber): PluginRegistryUnsubscribe;
    /** 绑定当前 Workspace 的 Plugin Context 工厂。 */
    bind_workspace_context(context: PluginContext, factory: PluginContextFactory): void;
    /** 解除当前 Workspace 的 Plugin Context 工厂。 */
    unbind_workspace_context(context: PluginContext): void;
    /** 返回指定 Plugin 的运行时 Context；未绑定工厂时回退到传入 Context。 */
    plugin_context(context: PluginContext, plugin_name: string): PluginContext;
    /**
     * 返回当前 Registry 向 Agent 提供的 Plugin Tools。
     *
     * 关键点（中文）
     * - 没有任何 Action 时不暴露空壳 Tool。
     * - Tool 闭包绑定当前 Registry，动态 Plugin 变化无需重建 bridge。
     */
    tools(context: PluginContext): Record<string, Tool>;
    /**
     * 创建绑定当前 Session Workspace 上下文的 Plugin 调用面。
     *
     * Registry 只保存 Agent 注册的 Plugin；Action、Hook、System 与 availability 在
     * 调用时显式使用这里捕获的 Workspace Context。
     */
    contextual(context: PluginContext): AgentPlugins;
    /**
     * 注册单个 plugin。
     *
     * 说明（中文）
     * - 同名注册表示替换：先卸载旧实例，再注册并启动新实例。
     * - 如果新实例启动失败，会自动回滚为未注册状态并抛错。
     */
    register(plugin: Plugin): Promise<PluginSnapshot>;
    /**
     * 同步挂载 plugin 元信息。
     *
     * 说明（中文）
     * - 仅供 Agent 构造期使用，避免构造函数里 await。
     * - 后续 `start_all()` 会统一启动这些初始 plugin。
     */
    mount(plugin: Plugin): PluginSnapshot;
    /**
     * 从 configured registry 卸载指定 plugin。
     *
     * 关键点（中文）
     * - configured registry、hooks 与直接调用入口立即移除。
     * - lifecycle.stop 等当前活跃 Session step 的 execution lease 全部释放后执行。
     * - 该方法返回配置修改结果，不等待仍在运行的 step 结束。
     */
    unregister(plugin_name: string): Promise<boolean>;
    /** 将 Plugin 配置变化发布给 Agent 等持有者。 */
    private publish_change;
    /**
     * 启动全部已挂载 plugin。
     */
    start_all(): Promise<PluginSnapshot[]>;
    /** 串行启动构造期挂载的 Plugin，并隔离单个 lifecycle 失败。 */
    private start_initial_records;
    /** 确保任何异步 Plugin 执行都发生在初始 lifecycle 启动完成后。 */
    private ensure_initial_started;
    /**
     * 卸载全部 plugin。
     */
    unregister_all(): Promise<void>;
    /**
     * 判断 plugin 是否已注册且 ready。
     */
    is_ready(plugin_name: string): boolean;
    /**
     * 读取单个 plugin 快照。
     */
    status(plugin_name: string): PluginSnapshot | null;
    /**
     * 判断 plugin 是否已注册。
     */
    has(plugin_name: string): boolean;
    private register_hooks;
    private unregister_hooks;
    private start_record;
    private stop_record;
    /**
     * 运行 pipeline 点。
     */
    pipeline<T = JsonValue>(context: PluginContext, point_name: string, value: T): Promise<T>;
    /**
     * 运行 guard 点。
     */
    guard<T = JsonValue>(context: PluginContext, point_name: string, value: T): Promise<void>;
    /**
     * 运行 effect 点。
     */
    effect<T = JsonValue>(context: PluginContext, point_name: string, value: T): Promise<void>;
    /**
     * 运行 resolve 点。
     */
    resolve<TInput = JsonValue, TOutput = JsonValue>(context: PluginContext, point_name: string, value: TInput): Promise<TOutput>;
    /**
     * 获取单个 plugin 定义。
     */
    get(plugin_name: string): Plugin | null;
    /**
     * 列出全部 plugin 概览视图。
     */
    list(): PluginView[];
    /**
     * 列出全部 plugin 注册快照。
     */
    snapshots(): PluginSnapshot[];
    /**
     * 读取 action metadata。
     */
    private readAction;
    /**
     * 读取 plugin / action metadata。
     */
    read(params: {
        plugin?: string;
        action?: string;
    }): PluginReadView | {
        plugins: PluginView[];
    };
    /**
     * 从指定记录视图读取 plugin/action metadata。
     */
    private read_from_records;
    /**
     * 检查 plugin 可用性。
     */
    availability(context: PluginContext, plugin_name: string): Promise<PluginAvailability>;
    /**
     * 运行 plugin action。
     */
    run_action(params: {
        context: PluginContext;
        plugin: string;
        action: string;
        payload?: JsonValue;
        execution_context?: PluginExecutionContext;
        interactions?: SessionInteractionPort;
    }): Promise<PluginActionResult<JsonValue>>;
    /**
     * 从指定记录视图运行 plugin action。
     */
    private run_action_from_records;
    /**
     * 读取当前生效的 plugin system blocks。
     */
    system_blocks(context: PluginContext, execution_context?: PluginExecutionContext): Promise<AgentSessionSystemBlock[]>;
    /**
     * 从指定记录视图解析 plugin system blocks。
     */
    private system_blocks_from_records;
    /**
     * 创建当前 configured registry 的 Session step 执行视图。
     */
    execution_view(context: PluginContext): AgentPluginExecutionRuntime;
    /**
     * 为单次 Session step 获取 Plugin execution lease。
     */
    private acquire_execution_view;
    /**
     * 把已移出 configured registry 的 Plugin 标记为等待释放。
     */
    private retire_record;
    /**
     * 在最后一个 execution lease 释放后停止退休 Plugin。
     */
    private try_finalize_retired_record;
}
export {};
//# sourceMappingURL=PluginRegistry.d.ts.map