@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

package/dist/extensions/host.d.ts

@@ -1,24 +1,29 @@
-import { type ExtensionManifest, type ExtensionPointRef, type ToolHandler, type ToolSpec, type UiContribution } from "@capybara-hq/plugin-sdk";
+import { type ExtensionManifest, type ExtensionPointRef, type LocalizedName, type ToolHandler, type ToolSpec, type UiContribution } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
 import type { core } from "zod";
-import { type KernelDeps, type Route } from "../ctx/create-ctx.js";
+import type { KernelAppOptions } from "../app.js";
+import type { BusSubscriber } from "../ctx/bus.js";
+import { type Route } from "../ctx/create-ctx.js";
+import type { Keyring } from "../ctx/secrets.js";
 import type { PluginRouteTable } from "../http/plugin-dispatch.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { ModelEmbeddings } from "../models/embeddings.js";
+import { EmbedTokens } from "../ui/embed-token.js";
 import type { UiActionHandler, UiRender } from "../ui/registry.js";
-import { type PendingExtension } from "./approvals.js";
+import { ExtensionApprovals, type PendingExtension } from "./approvals.js";
+import { deploymentConfigHash } from "./config-hash.js";
+import { EffectiveConfigs } from "./effective-config.js";
 import { HookRegistry } from "./hooks.js";
-import { type InflightTracker } from "./inflight.js";
-import type { DesiredExtension } from "./installs.js";
+import type { InflightTracker } from "./inflight.js";
+import { type DesiredExtension, ExtensionInstalls } 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;
+import { type ExtensionPointEntry, ExtensionRegistry } from "./registry.js";
+import { type ExtensionSource, ReplicaStatusStore } from "./sources.js";
+export { deploymentConfigHash };
 /** 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;
@@ -26,18 +31,7 @@ export interface LoadedUiContribution {
     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;
-}
+export type { ExtensionPointEntry } from "./registry.js";
 /** One item of {@link ExtensionHost.inspect}. */
 export interface InspectedExtension {
     /** Always `config`: the startup config `extensions` list. */
@@ -47,6 +41,8 @@ export interface InspectedExtension {
     dir: string;
     /** 规范化的权限集合，见 {@link computePermissionSet}。 */
     permissions: PermissionSet;
+    /** The plugin.json `displayName` of the module's plugin directory, if any. */
+    displayName: LocalizedName | null;
 }
 /**
  * 插件两级配置 schema 中的每个 `secret()` 都必须标在对象路径的字段上（见 `unreachableSecrets`），
@@ -85,6 +81,8 @@ export interface DeclaredExtensionInfo {
     configurable: boolean;
     /** 启动配置里的部署配置按 schema 校验通过（没有 schema 时恒为 true）。 */
     configValid: boolean;
+    /** The plugin.json `displayName` of the module's plugin directory, if any. */
+    displayName: LocalizedName | null;
 }
 /** The extension sources of {@link ExtensionHost.load}, loaded in this order (see {@link ExtensionSource}). */
 export interface ExtensionLoadPlan {
@@ -95,8 +93,25 @@ export interface ExtensionLoadPlan {
 }
 /** 插件宿主：解析、校验配置、迁移、setup，并登记插件提供的能力与路由。 */
 export declare class ExtensionHost {
-    private readonly deps;
-    private readonly extensionConfig;
+    /** The process's extension registry (one provider, shared with other domains). */
+    private readonly registry;
+    /**
+     * The deployment's desired state (one way, spec §3): install record names (with the
+     * config-declared ones the extensions "known to the deployment": routes of one not active on
+     * this replica answer 503, an unknown name 404; cached {@link KNOWN_NAMES_TTL_MS}) and each
+     * extension's effective deployment config (the startup config plus the fields stored in PG, C10).
+     */
+    private readonly installs;
+    private readonly approvals;
+    /** This replica's load status table (`extension_replica_status`): every load result writes a row. */
+    private readonly status;
+    private readonly config;
+    private readonly log;
+    /**
+     * Each hook call's effective config for its organization, and the providers excluded from an
+     * org's point resolution (layering spec A §6).
+     */
+    private readonly effective;
     /**
      * 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
@@ -134,8 +149,6 @@ export declare class ExtensionHost {
     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.
@@ -157,10 +170,6 @@ export declare class ExtensionHost {
     private readonly imports;
     /** 串行化 unload / reload（同一时刻只做一件，依赖方的连锁处理不交错）。 */
     private lifecycle;
-    private readonly drainMs;
-    private readonly disposeTimeoutMs;
-    private readonly reloadSetupTimeoutMs;
-    private readonly installedNames;
     /** 安装记录里的插件名缓存（TTL + 注册表变化时作废）。 */
     private installedCache;
     /** 本次因权限待批准（或依赖待批准插件）而未加载的插件。 */
@@ -170,6 +179,11 @@ export declare class ExtensionHost {
      * 安装记录不在这里：每次 converge 都按 PG 期望状态重新判定。
      */
     private readonly pendingActivations;
+    /**
+     * The load parameters of each config-declared extension that loaded: when its deployment config
+     * is cleared and the rest is invalid it goes back to {@link pendingActivations} (pending config).
+     */
+    private readonly declaredActivations;
     /** 安装记录准备好的候选（按插件名；sha 变了就作废）。 */
     private readonly prepared;
     /** 闸门放行后导入过的安装记录真实清单（按插件名；部署配置 schema 用，含待配置而未加载的）。 */
@@ -186,6 +200,11 @@ export declare class ExtensionHost {
     private readonly retiring;
     /** 配置声明插件的清单与权限集合（含未加载的；后台列表与网页批准用）。 */
     private readonly declaredInfo;
+    /**
+     * Config-declared extensions' display names, read from their plugin directory's plugin.json at
+     * load (from the startup config, the same on every replica; never written elsewhere).
+     */
+    private readonly declaredDisplayNames;
     /** 导入过的插件名 → 来源与包（含未加载的；重名被跳过的一方不在这里）。 */
     private readonly sources;
     private didLoad;
@@ -199,53 +218,61 @@ export declare class ExtensionHost {
     /** 已创建、尚未登记（setup 进行中）的 ctx：close() 时立即关闭，不等 setup 返回。 */
     private settingUp;
     private readonly resolveFrom;
-    private readonly onSecrets;
-    private readonly autoApprove;
-    private readonly status;
-    private readonly storedConfig;
+    /** What every extension's `ctx` is built from (kernel side only; nothing Nest crosses into `ctx`). */
+    private readonly deps;
     /** 配置声明插件的部署配置最近一次判定是否合法（后台列表用；没判定过时按启动配置校验）。 */
     private readonly configValidity;
     /** 已告警过的「部署配置不合法」（插件名 → 说明；每个周期都会重新判定，同一说明只告警一次）。 */
     private readonly configWarned;
+    /** `<name>@<version>` whose invalid config UI hints were warned about (a log dedupe only). */
+    private readonly configUiWarned;
     /**
-     * @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>;
-    });
+     * The host builds each extension's `ctx` from the injected kernel services: the pool for
+     * `ctx.db` on the extension's schema, Redis for `kv` / `lock` / `bus` and the queues, the
+     * keyring for `secrets`. The config is read per call (`extensionConfig`, the drain and setup
+     * time limits, `extensionPermissions.autoApprove`).
+     *
+     * `KERNEL_APP_OPTIONS.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.
+     */
+    constructor(
+    /** The process's extension registry (one provider, shared with other domains). */
+    registry: ExtensionRegistry, 
+    /**
+     * The deployment's desired state (one way, spec §3): install record names (with the
+     * config-declared ones the extensions "known to the deployment": routes of one not active on
+     * this replica answer 503, an unknown name 404; cached {@link KNOWN_NAMES_TTL_MS}) and each
+     * extension's effective deployment config (the startup config plus the fields stored in PG, C10).
+     */
+    installs: ExtensionInstalls, approvals: ExtensionApprovals, 
+    /** This replica's load status table (`extension_replica_status`): every load result writes a row. */
+    status: ReplicaStatusStore, config: KernelConfigService, kdb: KernelDb, redis: Redis, busSubscriber: BusSubscriber, keyring: Keyring, embedTokens: EmbedTokens, locks: LockService, log: KernelLogger, options: Pick<KernelAppOptions, "resolveFrom">, 
+    /**
+     * Each hook call's effective config for its organization, and the providers excluded from an
+     * org's point resolution (layering spec A §6).
+     */
+    effective: Pick<EffectiveConfigs, "get">, 
+    /** `ctx.models`: the embeddings broker (spec B §5.4). */
+    models: Pick<ModelEmbeddings, "embed" | "describe">);
+    /** The startup config's `extensionConfig` (file / Nacos merged with env). */
+    private get extensionConfig();
+    /** `extensionPermissions.autoApprove` (development and trials only; see `planApprovals`). */
+    private get autoApprove();
+    /** In-flight calls of a revoked instance are drained within this (`extensionHost.drainSeconds`). */
+    private drainMs;
+    /** An extension's `dispose()` time limit (`extensionHost.disposeTimeoutSeconds`). */
+    private disposeTimeoutMs;
+    /** `setup` time limit of a reload in a running process (`extensionHost.reloadSetupTimeoutSeconds`). */
+    private reloadSetupTimeoutMs;
+    /**
+     * Records the config-declared extensions the CLI inspected (the CLI loads none): their names,
+     * manifests and permission sets for {@link declared} / {@link declaredPlugins}, and whether
+     * their deployment config is valid (the CLI merges and checks it like a replica would).
+     */
+    noteInspected(inspected: InspectedExtension[], configValid: ReadonlyMap<string, boolean>): void;
     /**
      * Imports each extension module (default export) and initializes them in dependency order; may be
      * called only once. An array is the same as `{ config: [...] }`.
@@ -286,6 +313,11 @@ export declare class ExtensionHost {
      * `plugin host closed during load` at the next checkpoint.
      */
     load(plan: string[] | ExtensionLoadPlan): Promise<void>;
+    /**
+     * Records each config-declared extension's display name from its plugin directory's plugin.json
+     * (spec §2.2); an invalid plugin.json only warns (no display name).
+     */
+    private noteDisplayNames;
     /**
      * 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).
@@ -302,7 +334,7 @@ export declare class ExtensionHost {
      * 插件此刻的部署配置（未校验）：启动配置补上 PG 里保存的字段（C10，见构造参数 `deploymentConfig`）。
      */
     private rawConfigOf;
-    /** 把一份已校验部署配置里的密钥值交给 onSecrets（日志打码）。 */
+    /** 把一份已校验部署配置里的密钥值登记到日志打码。 */
     private reportSecrets;
     /**
      * 安装记录收敛到 PG 期望状态（启动第 3 步与运行中的 {@link converge} 共用，C16）；`desired` 为期望启用的记录。
@@ -318,6 +350,13 @@ export declare class ExtensionHost {
      * 返回启用的安装记录在静态清单里声明提供的能力（启动第 4 步据此判断待定还是缺提供方）。
      */
     private applyInstalls;
+    /**
+     * Marks the losers of the single-provider election pending / conflict, naming the winner; after
+     * this pass loaded what it could, so a winner not loaded here (failed, pending) is known: the
+     * election stays (replicas must agree), but the loser's detail says the point has no running
+     * provider and the admin view warns about it.
+     */
+    private noteLosers;
     /**
      * 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
@@ -352,6 +391,15 @@ export declare class ExtensionHost {
      * - 缺的能力没有任何提供方 → 与此前一样抛错（内核启动失败）。
      */
     private loadDeferred;
+    /**
+     * Checks the config UI hints of a loaded module's deployment and org schemas (spec §4.1). Invalid
+     * hints never fail the load: the form schemas drop their `x-ui` (`configFormSchema`), one warning
+     * per `<name>@<version>` is logged, and the returned text goes into the status detail (null when
+     * every hint is valid). The packer refuses such a package; this covers hand-made ones. It never
+     * throws (it runs after the instance is active, before its status row is written): a conversion
+     * that throws is warned about and reported in the detail the same way.
+     */
+    private checkConfigUi;
     /** 给已有状态行补说明；失败只记 warn。 */
     private noteStatus;
     /**
@@ -460,6 +508,13 @@ export declare class ExtensionHost {
      * （如 `identity-source@1` 的登录配置）；未加载返回 undefined。不得回显到响应或日志。
      */
     deploymentConfig(plugin: string): unknown;
+    /**
+     * The raw (unparsed) deployment config of a running extension: the startup config merged with
+     * the PG values, as the host reads it before parsing (secrets included; never echo it). An org
+     * copy is applied to this and parsed once (layering spec A §6), so schema transforms are not
+     * run twice. Without a running instance, the stored values without a schema.
+     */
+    rawDeploymentConfig(plugin: string): Promise<unknown>;
     /**
      * 本副本拿得到的插件清单里的部署级 schema（生效实例 → 配置声明 → 安装记录准备好的候选）；
      * 都没有返回 undefined（如未加载的安装记录：调用方改用包内静态清单）。
@@ -473,12 +528,38 @@ export declare class ExtensionHost {
     /**
      * 部署配置保存后（`kernel.plugin-deployment-config`）本副本重读并校验（C10；与 unload / reload 串行）：
      * - 插件没在本副本生效 → `not_loaded`（配置声明的刷新后台的合法性判定；待配置的由 reconcile 加载）；
-     * - 不合法 → `invalid`：保持当前值，告警；
+     * - 不合法 → `invalid`：保持当前值，告警；但 PG 里已没有保存的配置（超级管理员清空了，`DELETE
+     *   /api/v1/admin/extensions/:name/config`）、剩下的来源（启动配置、默认值）又不够时 → `unloaded`：卸下实例、
+     *   记为待配置（pending / config），依赖方连锁；重新配好后由 reconcile 加载；
      * - 没变 → `unchanged`；只改了 hot 字段 → `hot`：就地替换，插件经 `ctx.config` 读到新值，不重新 setup；
      * - 改了非 hot 字段 → `reload`：用新配置重新加载实例（先新后旧，排空在途调用），依赖方连锁；
      *   重新加载失败旧实例保留（`reload_failed`，记 error）。
      */
-    applyDeploymentConfig(plugin: string): Promise<"not_loaded" | "invalid" | "unchanged" | "hot" | "reload" | "reload_failed">;
+    applyDeploymentConfig(plugin: string): Promise<"not_loaded" | "invalid" | "unloaded" | "unchanged" | "hot" | "reload" | "reload_failed">;
+    /** PG holds no deployment config for the plugin (it was cleared); a read error counts as no. */
+    private clearedInPg;
+    /**
+     * Unloads an extension whose deployment config was cleared and is now missing or invalid (in
+     * the host's serial queue): drains it, records pending / config (a config-declared one goes back
+     * to {@link pendingActivations}; an install record is decided again on every converge) and
+     * cascades to its dependents. It loads again without a restart once it is configured.
+     */
+    private unloadForMissingConfig;
+    /**
+     * Records an extension that is not loaded as pending configuration: a config-declared one goes
+     * back to {@link pendingActivations} (a later save loads it); an install record is decided again
+     * on every converge.
+     */
+    private markPendingConfig;
+    /**
+     * Before an extension unloaded for a dependency comes back ({@link cascade}): re-reads its
+     * deployment config, which may have been saved or cleared while it was down (applyDeploymentConfig
+     * only records validity then), and refreshes its load parameters, so it never returns on a stale
+     * config or revoked secrets. Returns false when the config is now missing or invalid and PG holds
+     * none: the extension is left pending configuration instead. A read error, or an invalid config
+     * that is still stored, keeps the previous config (as for a loaded extension).
+     */
+    private refreshConfigForRestore;
     /** 本次未加载、等待批准权限的插件（含因 `requires` 只能由它们满足而未加载的插件），按依赖拓扑序。 */
     pending(): PendingExtension[];
     /** 已加载插件的清单（按加载顺序，即依赖拓扑序）。 */