@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/extensions/host.d.ts

@@ -0,0 +1,577 @@
+import { type ExtensionManifest, type ExtensionPointRef, type ToolHandler, type ToolSpec, type UiContribution } from "@capybara-hq/plugin-sdk";
+import type { core } from "zod";
+import { type KernelDeps, type Route } from "../ctx/create-ctx.js";
+import type { PluginRouteTable } from "../http/plugin-dispatch.js";
+import type { UiActionHandler, UiRender } from "../ui/registry.js";
+import { type PendingExtension } from "./approvals.js";
+import { HookRegistry } from "./hooks.js";
+import { type InflightTracker } from "./inflight.js";
+import type { DesiredExtension } from "./installs.js";
+import { type ExtensionInstance } from "./instance.js";
+import { type PermissionSet } from "./permission-set.js";
+import type { ExtensionSource, ReplicaStatusStore } from "./sources.js";
+/**
+ * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
+ * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
+ * 给需要「配置变了就失效」的缓存键用（如模型列表）。密钥不参与摘要：不加盐的短摘要写进 Redis 键名后，
+ * 低熵密钥可被离线猜测、泄露的密钥可被确认；代价是轮换密钥不会让缓存失效（缓存内容本来就不该依赖密钥）。
+ * 没有部署配置 schema 时无从得知哪些是密钥，摘要不按配置区分。同一份配置在各副本上得到同一摘要。
+ * 函数自己按 schema 遮蔽，调用方不必（也不能忘记）先打码。
+ */
+export declare function deploymentConfigHash(schema: core.$ZodType | undefined, config: unknown): string;
+/** One item of {@link ExtensionHost.uiContributions}: a UI contribution from the manifest with its registered view / action (embeds have none). */
+export interface LoadedUiContribution {
+    plugin: string;
+    contribution: UiContribution;
+    render?: UiRender;
+    action?: UiActionHandler;
+}
+/** One item of {@link ExtensionHost.list}. */
+export interface ExtensionPointEntry {
+    plugin: string;
+    capability: ExtensionPointRef;
+    impl: unknown;
+    /** 插件清单的 version。 */
+    version: string;
+    /** 部署配置摘要，见 {@link deploymentConfigHash}。 */
+    configHash: string;
+    /** 提供方实例的在途计数（connector / sandbox / model-provider 的 `impl` 已经包成计入它的代理）。 */
+    inflight: InflightTracker;
+}
+/** One item of {@link ExtensionHost.inspect}. */
+export interface InspectedExtension {
+    /** Always `config`: the startup config `extensions` list. */
+    source: "config";
+    manifest: ExtensionManifest;
+    /** 插件模块所在目录（`migrations` 相对它解析）。 */
+    dir: string;
+    /** 规范化的权限集合，见 {@link computePermissionSet}。 */
+    permissions: PermissionSet;
+}
+/**
+ * 插件两级配置 schema 中的每个 `secret()` 都必须标在对象路径的字段上（见 `unreachableSecrets`），
+ * 否则内核无法把它单独加密存储 / 打码、会按明文保存与回显——此时拒绝加载并点名插件与路径。
+ */
+export declare function assertSecretsReachable(manifest: ExtensionManifest): void;
+/**
+ * The load entry for install records (C13 / C16): the records desired enabled, syncing to local disk
+ * (returns the entry URL) and migrating under the lock. Implemented by the kernel with
+ * `ExtensionInstalls` + `syncPackage` + `ensureMigrated`; the host calls it only after the
+ * config-declared extensions have loaded (the package may be in object storage, so the object-store
+ * extension must be ready).
+ */
+export interface InstalledExtensionLoader {
+    desired(): Promise<DesiredExtension[]>;
+    sync(d: DesiredExtension): Promise<string>;
+    /**
+     * 该包的迁移（`dir` 为审阅过的 `capybara.migrations` 的绝对路径，没有迁移时为 undefined）：
+     * 已迁移或本副本持锁迁移完成 → `migrated`；别的副本正在迁移 → `busy`（记 pending / migration，等
+     * `plugins.migrated` 或下一个周期）；迁移出错时抛出。见 `ensureMigrated`。`signal` 在宿主关闭时中止（结束迁移会话）。
+     */
+    migrate(d: DesiredExtension, dir: string | undefined, signal: AbortSignal): Promise<"migrated" | "busy">;
+}
+/**
+ * 安装记录加载失败的原因（写进副本状态行的 `reason`，`detail` 只写错误消息）：同步失败、包字节与 sha256 不符、
+ * 导入失败、模块清单与审阅过的静态清单不符、setup 失败、迁移失败。
+ */
+export type InstallFailureReason = "sync_failed" | "sha_mismatch" | "import_failed" | "manifest_mismatch" | "setup_failed" | "migration_failed";
+/** One item of {@link ExtensionHost.declaredPlugins}. */
+export interface DeclaredExtensionInfo {
+    name: string;
+    source: "config";
+    version: string;
+    permissions: PermissionSet;
+    /** 清单有部署级配置 schema。 */
+    configurable: boolean;
+    /** 启动配置里的部署配置按 schema 校验通过（没有 schema 时恒为 true）。 */
+    configValid: boolean;
+}
+/** The extension sources of {@link ExtensionHost.load}, loaded in this order (see {@link ExtensionSource}). */
+export interface ExtensionLoadPlan {
+    /** The startup config `extensions` list. */
+    config?: string[];
+    /** 安装记录。 */
+    installs?: InstalledExtensionLoader;
+}
+/** 插件宿主：解析、校验配置、迁移、setup，并登记插件提供的能力与路由。 */
+export declare class ExtensionHost {
+    private readonly deps;
+    private readonly extensionConfig;
+    /**
+     * Only resolves extensions and runs migrations in dependency order: no deployment config check, no
+     * setup, no Redis (for `capybara migrate`). Like `load()` it checks secret markers first
+     * (`assertSecretsReachable`); if any extension has a problem, none is migrated.
+     * Returns every extension that declares migrations, with the files applied this time.
+     * The same permission snapshot gate as `load()`: extensions pending approval (and those whose
+     * `requires` only they satisfy) are not migrated and are reported through `onPending`; needs the
+     * kernel migrations to have run (reads `extension_permission_snapshots`). With `autoApprove` all are
+     * migrated and no snapshot is written (`load()` writes snapshots).
+     */
+    static migrateOnly(specifiers: string[], opts: {
+        dbUrl: string;
+        resolveFrom?: string;
+        connectTimeoutMs?: number;
+        autoApprove?: boolean;
+        onPending?: (pending: PendingExtension[]) => void;
+    }): Promise<{
+        plugin: string;
+        schema: string;
+        applied: string[];
+    }[]>;
+    /**
+     * The names of the config-declared extensions (`specifiers`, the startup config `extensions`
+     * list): imports their modules only (the same modules `load()` imports next, from Node's module
+     * cache). The kernel passes them to the bootstrap step before loading, so a bootstrap entry of
+     * the same name is kept and gets no install record (config wins, C15).
+     */
+    static declaredNames(specifiers: string[], opts?: {
+        resolveFrom?: string;
+    }): Promise<Set<string>>;
+    /**
+     * 只导入、校验并按依赖排序插件，计算各自的权限集合；不迁移、不调用 setup、不连数据库与 Redis
+     * （供 `capybara extensions review / approve`）。返回依赖拓扑序。
+     */
+    static inspect(specifiers: string[], opts?: {
+        resolveFrom?: string;
+    }): Promise<InspectedExtension[]>;
+    /** 本进程生效的插件实例（C17）：消费方每次实时取，不缓存实现对象。 */
+    private readonly registry;
+    /**
+     * M-1: plugin → mount points where deployment state expects `policy` hooks. A per-replica copy of PG
+     * deployment state (like the registry), rebuilt on every load / converge, never written elsewhere.
+     */
+    private policyExpected;
+    /**
+     * Runs the hooks of this process's active plugin instances (resolved from the registry on every
+     * call, so an upgrade fires only the new generation; calls go through each instance's in-flight
+     * tracker and are drained on revocation). Organization enablement is {@link enabledPlugins}.
+     */
+    readonly hooks: HookRegistry;
+    /** 加载成功过的插件的加载参数（同进程重新加载用；撤销后保留，`unavailable` 据此判断）。 */
+    private readonly specs;
+    /** 因必需能力没了而随提供方卸下的插件：提供方回来后重新加载。 */
+    private readonly unloadedForDependency;
+    /** 每个插件已产生的实例代数。 */
+    private readonly generations;
+    /** 本进程导入过的模块入口（不同入口数超过阈值时告警：旧代码留在内存直到重启）。 */
+    private readonly imports;
+    /** 串行化 unload / reload（同一时刻只做一件，依赖方的连锁处理不交错）。 */
+    private lifecycle;
+    private readonly drainMs;
+    private readonly disposeTimeoutMs;
+    private readonly reloadSetupTimeoutMs;
+    private readonly installedNames;
+    /** 安装记录里的插件名缓存（TTL + 注册表变化时作废）。 */
+    private installedCache;
+    /** 本次因权限待批准（或依赖待批准插件）而未加载的插件。 */
+    private readonly pendingPlugins;
+    /**
+     * 待批准（或运行中加载失败）的配置声明插件的加载参数：{@link activatePending} / {@link converge} 据此重试。
+     * 安装记录不在这里：每次 converge 都按 PG 期望状态重新判定。
+     */
+    private readonly pendingActivations;
+    /** 安装记录准备好的候选（按插件名；sha 变了就作废）。 */
+    private readonly prepared;
+    /** 闸门放行后导入过的安装记录真实清单（按插件名；部署配置 schema 用，含待配置而未加载的）。 */
+    private readonly importedManifests;
+    /** 本副本写过状态行的安装记录插件（停用 / 卸载后把未加载的那行标为 unloaded）。 */
+    private readonly installRows;
+    /** 启用的安装记录按静态清单声明提供的能力（最近一次 {@link applyInstalls}；待定插件的 blockedBy 用）。 */
+    private installProvides;
+    /** 已记过 error 日志的加载失败（插件名 → `<sha>:<原因>`；加载成功后清掉）。 */
+    private readonly loggedFailures;
+    /** 已告警过的「安装记录与配置声明重名」（每个名字只告警一次）。 */
+    private readonly warnedConflicts;
+    /** 升级时被替换、后台排空中的旧实例（close() 等它们，最多 lifecycleWaitMs）。 */
+    private readonly retiring;
+    /** 配置声明插件的清单与权限集合（含未加载的；后台列表与网页批准用）。 */
+    private readonly declaredInfo;
+    /** 导入过的插件名 → 来源与包（含未加载的；重名被跳过的一方不在这里）。 */
+    private readonly sources;
+    private didLoad;
+    /** load() 的安装记录入口（{@link converge} 据此按 PG 期望状态收敛）。 */
+    private installLoader;
+    private closed;
+    /** close() 时中止进行中的插件迁移。 */
+    private readonly abort;
+    /** 进行中的插件迁移（close() 等它结束，保证迁移连接不比宿主活得久）。 */
+    private migrating;
+    /** 已创建、尚未登记（setup 进行中）的 ctx：close() 时立即关闭，不等 setup 返回。 */
+    private settingUp;
+    private readonly resolveFrom;
+    private readonly onSecrets;
+    private readonly autoApprove;
+    private readonly status;
+    private readonly storedConfig;
+    /** 配置声明插件的部署配置最近一次判定是否合法（后台列表用；没判定过时按启动配置校验）。 */
+    private readonly configValidity;
+    /** 已告警过的「部署配置不合法」（插件名 → 说明；每个周期都会重新判定，同一说明只告警一次）。 */
+    private readonly configWarned;
+    /**
+     * @param opts.resolveFrom The directory bare package names are resolved from, default
+     * `process.cwd()`; a relative path is made absolute against the cwd at construction.
+     * Absolute paths and `file:` URL extension specifiers are used as they are;
+     * bare package names are resolved with `createRequire(<resolveFrom>/noop.js).resolve`, so an
+     * extension package's exports must expose the `default` (or `require`) condition.
+     * @param opts.autoApprove Approve extension permissions automatically (config
+     * `extensionPermissions.autoApprove`, development and trials only): extensions needing approval write a
+     * snapshot with source auto and load as usual. Default false: extensions pending approval do not
+     * load (see {@link pending}).
+     * @param opts.status This replica's load status table (`extension_replica_status`): every
+     * extension's load result writes a row.
+     */
+    constructor(deps: KernelDeps, extensionConfig?: Record<string, unknown>, opts?: {
+        resolveFrom?: string;
+        onSecrets?: (values: string[]) => void;
+        autoApprove?: boolean;
+        status?: ReplicaStatusStore;
+        /** 撤销实例时在途调用的排空时限（毫秒），默认 30s；内核传 `extensionHost.drainSeconds`。 */
+        drainMs?: () => number;
+        /** 插件 `dispose()` 的时限（毫秒），默认 10s；内核传 `extensionHost.disposeTimeoutSeconds`。 */
+        disposeTimeoutMs?: () => number;
+        /** 运行中重新加载时 setup 的时限（毫秒），默认 60s；内核传 `extensionHost.reloadSetupTimeoutSeconds`。 */
+        reloadSetupTimeoutMs?: () => number;
+        /** Hook time limit in milliseconds, default 5 s; the kernel passes `hooks.timeoutMs` (hot). */
+        hookTimeoutMs?: () => number;
+        /**
+         * 安装记录里的插件名（T11 安装记录，任何 desired_state）：与配置声明的一起构成「部署已知」的插件，
+         * 不在本副本生效时它们的路由返回 503，完全未知的名字 404。缓存 {@link KNOWN_NAMES_TTL_MS}。
+         */
+        installedNames?: () => Promise<string[]>;
+        /**
+         * The extension's effective deployment config (C10): the startup config (`fileValue`, file /
+         * Nacos merged with env) plus the fields stored in PG
+         * (`ExtensionDeploymentConfigService.effective`), not validated yet. Without it only the startup
+         * config is used.
+         */
+        deploymentConfig?: (plugin: string, fileValue: unknown, schema: core.$ZodType | undefined) => Promise<unknown>;
+    });
+    /**
+     * Imports each extension module (default export) and initializes them in dependency order; may be
+     * called only once. An array is the same as `{ config: [...] }`.
+     *
+     * Order (C15 / C13; the bootstrap plugins that replaced builtin extensions are install records):
+     * 1. Config-declared extensions: not loaded while pending approval; an invalid deployment config is
+     *    recorded `pending` (reason config, C10) and the kernel starts as usual; a failed
+     *    migration or setup throws and the kernel fails to start.
+     *    When an extension point in `requires` did not load because its provider is pending
+     *    configuration or similar, it is recorded pending (dependency) and converge loads it once the
+     *    provider has loaded.
+     * Deployment config = the startup config (`extensionConfig`) plus the fields stored in PG (constructor
+     *    parameter `deploymentConfig`, C10).
+     *    A config-declared extension whose `requires` can
+     *    only be satisfied by an install record is set aside and resolved and loaded after step 2
+     *    together with the loaded extensions (step 3; still unsatisfied -> it throws as before).
+     * 2. Install records (`plan.installs`): synced to local disk, the permission set computed from the
+     *    reviewed static manifest and migration SQL, dependencies resolved together with the existing
+     *    extensions, then the same permission gate in topological order; only after passing is the module
+     *    imported and the static manifest checked (name and `capybara.manifest` must both match,
+     *    otherwise failed / manifest_mismatch), so no extension code runs before approval; migration
+     *    directories come only from the reviewed `capybara.migrations`; a failure at any step only marks
+     *    that extension failed (or pending), the rest go on. On a name clash with a
+     *    config-declared extension the latter wins, with a warning.
+     * Every extension's result is written to this replica's `extension_replica_status` (when `status`
+     * was given at construction).
+     * Instances that loaded are registered in the registry (C17): from then on {@link unload} /
+     * {@link reload} revoke or reload them in this process.
+     *
+     * When a config-declared extension's (trusted) setup never returns, load() (and so the
+     * kernel's `start()`) hangs forever: the kernel sets no timeout for them; `close()` / the kernel's
+     * `stop()` still close that extension's ctx right away and free its resources. Install records are
+     * not trusted: at startup their setup is also limited by `extensionHost.reloadSetupTimeoutSeconds`
+     * (timeout -> failed / setup_failed) and migrations by `extensionHost.migrationTimeoutSeconds` (see
+     * `ensureMigrated`).
+     * When the host is `close()`d during load: running migrations are aborted, the ctx in setup is closed
+     * right away (its queue's define / add then throw `queue is closed`), and load() throws
+     * `plugin host closed during load` at the next checkpoint.
+     */
+    load(plan: string[] | ExtensionLoadPlan): Promise<void>;
+    /**
+     * Config-declared extensions also take their name (I4, an addition to Ruling P3): the
+     * name is inserted into `extension_name_owners` with its npm package name (left alone when present).
+     * After it is removed from the config list, no other npm package can install an extension of the
+     * same name and take over its data, secrets and approvals. A failed write only warns.
+     */
+    private claimNames;
+    /**
+     * 启动时按拓扑序加载：权限闸门放行、但 `requires` 的能力此刻没有生效的提供方（提供方待配置等没加载成）→
+     * 改为待定（dependency，blockedBy 点名待定的提供方），提供方加载后由 {@link converge} 一并加载。
+     */
+    private blockedByUnloaded;
+    /**
+     * 插件此刻的部署配置（未校验）：启动配置补上 PG 里保存的字段（C10，见构造参数 `deploymentConfig`）。
+     */
+    private rawConfigOf;
+    /** 把一份已校验部署配置里的密钥值交给 onSecrets（日志打码）。 */
+    private reportSecrets;
+    /**
+     * 安装记录收敛到 PG 期望状态（启动第 3 步与运行中的 {@link converge} 共用，C16）；`desired` 为期望启用的记录。
+     * 1. 不再期望启用的（停用 / 卸载）：卸下（排空在途调用），未加载但写过状态行的标为 unloaded；
+     * 2. 期望启用、本副本已在目标包上的：不动；
+     * 3. 其余：准备候选（同步 → 按静态清单与迁移 SQL 算权限集合；失败记 failed：`sync_failed` / `sha_mismatch`），
+     *    与生效的插件一起按依赖拓扑序逐个处理：权限闸门（新增权限待批准 → pending / approval，旧实例照常）、
+     *    必需能力（此刻没有生效的提供方 → pending / dependency）、导入模块并核对静态清单（`import_failed` /
+     *    `manifest_mismatch`；闸门放行之前不导入）、部署配置、
+     *    持锁迁移（busy → pending / migration）、setup，成功后登记新实例（先加载新、再撤销旧：旧实例在后台排空后撤销）；
+     *    任何一步失败旧实例保留，记 failed（`migration_failed` / `setup_failed`）。
+     * 4. 运行中（非启动）：对变了的能力做依赖方连锁（本轮刚加载的除外），此前因依赖卸下的插件随之补回。
+     * 返回启用的安装记录在静态清单里声明提供的能力（启动第 4 步据此判断待定还是缺提供方）。
+     */
+    private applyInstalls;
+    /**
+     * The load candidate of an install record: sync it locally, then compute the permission set from
+     * the reviewed static manifest and the package's migration SQL (the same algorithm as
+     * `permissionSetOfPackage` at review; the migrations directory comes only from
+     * `extension.migrations`). Does not import the module: that happens after the permission gate
+     * ({@link importInstalled}). A failure is recorded as failed (`sync_failed` / `sha_mismatch`, the
+     * detail is the error message only, e.g. the legacy-format message for a pre-0.1.0 package) and
+     * returns undefined. The result for a package never changes, so successes are cached by sha (a
+     * reconcile cycle does not unpack again).
+     */
+    private prepare;
+    /**
+     * 权限闸门放行后导入安装记录的真实模块（模块顶层代码此时才执行）并核对：密钥标记、与审阅过的静态清单一致
+     * （名字、版本、能力、权限、界面、配置字段；不一致抛 {@link ManifestMismatchError}）。同一入口 URL 由 Node 模块缓存，
+     * 重复调用不重复执行顶层代码。导入限 `extensionHost.reloadSetupTimeoutSeconds`（与 setup 同一时限）：顶层代码
+     * 永不结束时记 failed / import_failed，不卡住启动与 reconcile（挂住的模块留在内存里，下次导入同样超时）。
+     */
+    private importInstalled;
+    /**
+     * 安装记录加载失败的 error 日志：每个周期都会重试，同一个包、同一个原因只记一次（状态行每次照写）。
+     */
+    private logFailure;
+    /** 记下（替换同名的）待定插件，供 {@link pending} 列出。 */
+    private notePending;
+    /** 从待定清单里去掉。 */
+    private dropPending;
+    /**
+     * 第 4 步：第 2 步挑出来的配置声明插件（`requires` 只能由安装记录满足）。与已加载的插件一起解析依赖：
+     * - 满足的按拓扑序走同一道权限闸门后加载（出错直接抛，与其他配置声明插件一致）；
+     * - 缺的能力有启用的安装记录声明提供、只是它没加载成（待批准 / 失败）→ 待定（pending，原因 dependency），
+     *   与「配置声明插件依赖待批准的配置声明插件」一致，内核照常启动；
+     * - 缺的能力没有任何提供方 → 与此前一样抛错（内核启动失败）。
+     */
+    private loadDeferred;
+    /** 给已有状态行补说明；失败只记 warn。 */
+    private noteStatus;
+    /**
+     * 写本副本的加载状态；失败只记 warn（状态是给后台看的，不影响加载）。这一行的版本没加载成（failed / pending）
+     * 而本副本仍有别的版本在跑时，记下那个版本（`servingVersion`，后台同时显示「新版失败、旧版仍在服务」）。
+     */
+    private writeStatus;
+    /**
+     * 加载一个插件：权限闸门结论、部署配置、迁移、setup、登记。`fatal` 时（配置声明）出错直接抛；
+     * 否则（安装记录）记 failed 后返回。部署配置不合法时（任何来源）只记 pending（reason config），不抛（C10）。
+     * 已有同名实例时（升级）：新实例登记后旧实例才撤销（后台排空在途调用）；新实例没加载成时旧实例保持不变。
+     * 返回新登记的实例（没有加载时返回 undefined）。
+     */
+    private activate;
+    /**
+     * 后台撤销被替换的旧实例（排空在途调用，最多 `extensionHost.drainSeconds`）：不挡住本副本后续的生命周期操作。
+     * close() 等它们（最多 lifecycleWaitMs）。
+     */
+    private retire;
+    /** 记下配置声明插件的清单与权限集合（安装记录不在这里）。 */
+    private noteDeclared;
+    /**
+     * 配置声明的插件（含待批准、待配置而未加载的）：权限集合（{@link computePermissionSet}）、
+     * 部署配置此刻是否合法（按清单的 deployment schema 校验启动配置）。按导入顺序。
+     */
+    declaredPlugins(): DeclaredExtensionInfo[];
+    /**
+     * 在本副本加载此刻能加载的待定配置声明插件（批准之后，或运行中加载失败后的重试），见 {@link converge}。
+     * 与 unload / reload 串行。返回本次加载的插件名。
+     */
+    activatePending(): Promise<string[]>;
+    /**
+     * 本副本收敛到部署的期望状态（T14 reconcile 的一步，与 unload / reload 串行）：
+     * 1. 待定的配置声明插件（批准后、或运行中加载失败的）按此刻的快照与生效的提供方重试；
+     * 2. 安装记录按 PG 期望状态收敛（见 {@link applyInstalls}：停用 / 卸载的卸下，换包的先加载新再撤销旧，
+     *    失败的每次重试），之后做依赖方连锁；
+     * 3. 再试一次第 1 步（安装记录提供的能力可能放行了依赖它的配置声明插件）。
+     * 读不到安装记录时只做第 1 步并抛错（调用方记日志，下一个周期再来）。
+     */
+    converge(): Promise<void>;
+    /**
+     * Refreshes {@link policyExpected} from deployment state (M-1):
+     * config-declared plugins and enabled installs (`desired`) from their approved permission snapshot.
+     * `desired` undefined (install records unreadable) keeps the previous install entries.
+     * `shrinkOnly`: only remove entries (a plugin no longer desired or approved), never add new ones.
+     */
+    private refreshPolicyExpectations;
+    /**
+     * Plugins that deployment state expects to run `policy` hooks on the mount point (M-1): enabled and
+     * approved, with the mount in `permissions.policyHooks`. In-process, no I/O (see
+     * {@link refreshPolicyExpectations}); the hook registry fails calls closed for those not loaded here.
+     */
+    expectedPolicy(mount: string): string[];
+    /**
+     * 待定的配置声明插件（{@link pendingActivations}）：重读快照，按启动时同一套判定（{@link planApprovals}，
+     * 另加「必需能力此刻要有生效的提供方」）逐个处理；能加载的走与启动相同的加载流程（部署配置、迁移、setup，
+     * setup 时限 `extensionHost.reloadSetupTimeoutSeconds`），失败只记 failed、留着下次重试（T13 → T14 交接）；
+     * 仍被依赖阻塞的改记 pending / dependency。反复直到不动点（加载一个可能放行依赖它的），
+     * 最后对新提供的能力做依赖方连锁（与 {@link reload} 相同）。
+     */
+    private activatePendingNow;
+    /**
+     * 待批准插件此刻的判定：已生效的（同名实例除外：升级时按新权限集合比对快照）视为已批准；必需能力没有生效的
+     * 提供方时仍待定（dependency）。`providers` 给出能力 → 声明提供它但没生效的安装记录（填 blockedBy）。
+     */
+    private decidePending;
+    /** 仍不能加载的待批准插件：原因变了（如已批准、只剩依赖阻塞）时更新待批准清单与副本状态。 */
+    private stillPending;
+    /** 插件的来源（导入过的；未知返回 undefined）。 */
+    sourceOf(plugin: string): ExtensionSource | undefined;
+    /** 配置声明的插件名 → 来源（安装包不能与它们重名）。 */
+    declared(): Map<string, ExtensionSource>;
+    /**
+     * Extensions enabled in the org: `extension_org_configs.enabled` plus every required bootstrap
+     * plugin (see `enabled.ts`); queried every time, not cached.
+     * Cost (M-4): hooks call this on every run, so one PG query per model attempt and per tool call.
+     * Acceptable for now; if a cache is ever added, give it a short TTL so an org disabling a plugin
+     * takes effect quickly.
+     */
+    enabledPlugins(orgId: string): Promise<Set<string>>;
+    /**
+     * The access behind an extension's `ctx.extensionPoints`: only active instances in the registry
+     * (dependencies load in topological order, so the depended-on are ready first); org enablement is
+     * read from `extension_org_configs` every time, not cached. Resolved live on every call: once a
+     * provider is revoked it is no longer returned.
+     */
+    private readonly extensionPointAccess;
+    private get loadDeps();
+    /**
+     * 按加载参数建一个新实例（setup 期间的 ctx 记在 `settingUp`，close() 时立即关闭）。
+     * `timeoutMs`（运行中重新加载）：setup 超时或宿主被关闭时关闭这个 ctx 并抛错；迟到完成的实例随即撤销。
+     * 配置声明的插件启动时不设时限（见 {@link load}）。
+     */
+    private setup;
+    /** 取能力实现：单选能力无需 providerName，多选能力必须指定。 */
+    get<T>(capability: ExtensionPointRef, providerName?: string): T;
+    /**
+     * 列出提供某能力（任意主版本）的所有插件及实现；`capability` 为完整引用（含主版本），
+     * 同一插件提供多个主版本时各占一项，由调用方按主版本选择。
+     * 每项带插件版本与部署配置摘要（{@link deploymentConfigHash}），供调用方做「插件升级 / 改配置即失效」的缓存键。
+     * 实时取自注册表：调用方不要缓存实现对象（插件撤销 / 升级后旧实现不再有效）。
+     */
+    list(extensionPointName: string): ExtensionPointEntry[];
+    /**
+     * 已加载插件的部署配置（已按清单 schema 校验，含密钥），供内核调用该插件的能力时作为 `config` 传回
+     * （如 `identity-source@1` 的登录配置）；未加载返回 undefined。不得回显到响应或日志。
+     */
+    deploymentConfig(plugin: string): unknown;
+    /**
+     * 本副本拿得到的插件清单里的部署级 schema（生效实例 → 配置声明 → 安装记录准备好的候选）；
+     * 都没有返回 undefined（如未加载的安装记录：调用方改用包内静态清单）。
+     */
+    deploymentSchema(plugin: string): {
+        version: string;
+        schema: core.$ZodType | undefined;
+    } | undefined;
+    /** 在本副本生效、声明了部署级配置的插件。 */
+    configurablePlugins(): string[];
+    /**
+     * 部署配置保存后（`kernel.plugin-deployment-config`）本副本重读并校验（C10；与 unload / reload 串行）：
+     * - 插件没在本副本生效 → `not_loaded`（配置声明的刷新后台的合法性判定；待配置的由 reconcile 加载）；
+     * - 不合法 → `invalid`：保持当前值，告警；
+     * - 没变 → `unchanged`；只改了 hot 字段 → `hot`：就地替换，插件经 `ctx.config` 读到新值，不重新 setup；
+     * - 改了非 hot 字段 → `reload`：用新配置重新加载实例（先新后旧，排空在途调用），依赖方连锁；
+     *   重新加载失败旧实例保留（`reload_failed`，记 error）。
+     */
+    applyDeploymentConfig(plugin: string): Promise<"not_loaded" | "invalid" | "unchanged" | "hot" | "reload" | "reload_failed">;
+    /** 本次未加载、等待批准权限的插件（含因 `requires` 只能由它们满足而未加载的插件），按依赖拓扑序。 */
+    pending(): PendingExtension[];
+    /** 已加载插件的清单（按加载顺序，即依赖拓扑序）。 */
+    manifests(): ExtensionManifest[];
+    /** 已加载插件的权限集合（加载时计算，清单不可变）；未加载返回 undefined。 */
+    permissionSet(plugin: string): PermissionSet | undefined;
+    /** 生效的插件实例；未加载 / 已撤销返回 undefined。 */
+    current(plugin: string): ExtensionInstance | undefined;
+    /** 生效的插件实例（按加载顺序）。 */
+    instances(): ExtensionInstance[];
+    /**
+     * Route gate: the extension belongs to this deployment (config-declared, or an install
+     * record in PG) but is not active on this replica right now -> true, and its `/plugins/<name>/*` and
+     * `/plugin-ui/<name>/*` answer 503 `extension.unavailable` (the routes stay mounted and only gate);
+     * active, or a completely unknown name -> false (unknown is a plain 404). Looks only at what the
+     * deployment knows, not at this process's load history. Install record names are cached for
+     * {@link KNOWN_NAMES_TTL_MS} and invalidated on registry changes; when they cannot be read the name
+     * counts as unknown (404).
+     */
+    unavailable(plugin: string): Promise<boolean>;
+    /**
+     * 作废路由闸门的安装记录名字缓存（收到 `kernel.plugins.changed` 时各副本调用：卸载 / 新装后不等 TTL）。
+     */
+    invalidateKnownNames(): void;
+    /** 安装记录里的插件名（缓存，见 {@link unavailable}）。 */
+    private installed;
+    /** Subscribes to registry changes (activated / replaced / removed, the argument is the extension name): this process only, see {@link ExtensionRegistry.onChange}. */
+    onChange(listener: (name: string) => void): () => void;
+    /** 插件路由表（给 HTTP 的插件转发用）：实时路由、注册表版本、闸门与变化通知（中止该插件进行中的请求）。 */
+    routeTable(): PluginRouteTable;
+    /** 所有插件注册的 HTTP 路由（路径已带 `/plugins/<name>` 前缀）。 */
+    routes(): Route[];
+    /**
+     * 所有插件经 `ctx.tools.register` 注册的工具（按加载顺序、注册顺序），附带实例的在途计数：
+     * 执行时经 `inflight.run` 调用 handler，实例撤销时排空 / 中止。
+     */
+    tools(): {
+        plugin: string;
+        spec: ToolSpec;
+        handler: ToolHandler;
+        inflight: InflightTracker;
+    }[];
+    /**
+     * 已加载插件清单里的界面贡献（按加载顺序、清单顺序），附带 setup 期间注册的视图 render / 动作处理函数。
+     * 是否在某组织启用由调用方另查（每次查询，不缓存）。
+     */
+    uiContributions(): LoadedUiContribution[];
+    /** 串行执行生命周期操作（unload / reload 互不交错）；宿主关闭后拒绝。 */
+    private serial;
+    /**
+     * 撤销一个插件（本副本，C17）：从注册表摘下（此后新请求取不到它）、排空在途调用（最多 `drainMs`，
+     * 默认 `extensionHost.drainSeconds`）、逐项撤销登记、调插件 `dispose`（最多 `extensionHost.disposeTimeoutSeconds`）。连锁：
+     * - `requires` 它提供的能力、且该能力已没有其他提供方的插件随之卸下（状态 `unloaded`、原因 `dependency`），
+     *   提供方回来后（{@link reload}）自动重新加载；
+     * - 其余 `requires` / `optional` 它提供的能力的插件（含间接依赖）在本副本按拓扑序各重新加载一次。
+     * 返回卸下的插件名（含连锁卸下的）；插件不在注册表时返回空数组。宿主关闭后拒绝。
+     */
+    unload(plugin: string, opts?: {
+        drainMs?: number;
+    }): Promise<string[]>;
+    /**
+     * 用同一份加载参数（同一模块入口、部署配置与权限）新建一个实例并原子替换（同进程重新加载 / 撤销后重新启用）：
+     * 新实例 setup 成功后才登记（setup 最多 `extensionHost.reloadSetupTimeoutSeconds`），旧实例随后撤销（排空在途调用）；
+     * setup 失败或超时时旧实例保持不变并抛错。依赖它的插件在本副本按拓扑序各重新加载一次；此前因它卸下的依赖方重新加载。
+     * 同一入口的重新加载不新增模块代码；升级到新入口（T14）的模块代码留在内存直到进程重启，不同入口数超过阈值时告警。
+     * 宿主关闭后拒绝。
+     */
+    reload(plugin: string, opts?: {
+        drainMs?: number;
+    }): Promise<ExtensionInstance>;
+    /** 摘下并撤销一个实例（不做连锁）；不在注册表时返回 undefined。 */
+    private doUnload;
+    /** 新建实例并原子替换、撤销旧实例（不做连锁）。 */
+    private doReload;
+    /** 生效实例按依赖拓扑排序（解析不了时退回注册表顺序）。 */
+    private topoOrder;
+    /**
+     * 提供方实例变了（撤销 / 替换）之后的连锁：先一次性收集受影响的插件（`requires` / `optional` 这些能力的，
+     * 以及间接依赖它们的——菱形依赖只收一次），再按拓扑序逐个处理：必需能力已无提供方的卸下（dependency），
+     * 其余重新加载一次。最后把此前因依赖卸下、现在能满足的插件加回来。返回连锁卸下的插件名。
+     * `skip`：本轮刚加载的插件（已按新的提供方 setup，不再重新加载）。
+     */
+    private cascade;
+    /** 撤销实例；失败只记 error（已从注册表摘下，不影响其余）。 */
+    private disposeQuietly;
+    /**
+     * 按加载顺序（拓扑序）逆序串行撤销各插件：依赖方先于被依赖方。停机路径：不排空在途调用（运行此时已停），
+     * 队列 worker 等进行中的任务结束。调用后宿主进入 closed 状态（幂等），此后 unload / reload 拒绝。
+     * 进行中的 `load()`：迁移被中止并等其连接结束，setup 中的 ctx 被立即关闭（不等 setup 返回），load() 随后在检查点放弃。
+     * 进行中的 unload / reload 最多等 `lifecycleWaitMs`（默认 2s；卡住的 setup / dispose 不拖住停机），
+     * 之后关闭 setup 中的 ctx、撤销其余实例。单个插件关闭失败记 error 后继续关闭其余插件。
+     */
+    close(opts?: {
+        lifecycleWaitMs?: number;
+    }): Promise<void>;
+}