@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/extensions/host.d.ts

@@ -1,4 +1,4 @@
-import { type ExtensionManifest, type ExtensionPointRef, type ToolHandler, type ToolSpec, type UiContribution } from "@capybara-hq/plugin-sdk";
+import { type DroppedUiContribution, type ExtensionManifest, type ExtensionPointRef, type LocalizedName, type ToolHandler, type ToolSpec, type UiContribution, type UiSlotSpec } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import type { core } from "zod";
 import type { KernelAppOptions } from "../app.js";
@@ -10,9 +10,12 @@ 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 { 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, ExtensionInstalls } from "./installs.js";
@@ -20,19 +23,19 @@ import { type ExtensionInstance } from "./instance.js";
 import { type PermissionSet } from "./permission-set.js";
 import { type ExtensionPointEntry, ExtensionRegistry } from "./registry.js";
 import { type ExtensionSource, ReplicaStatusStore } from "./sources.js";
+export { deploymentConfigHash };
 /**
- * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
- * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
- * 给需要「配置变了就失效」的缓存键用（如模型列表）。密钥不参与摘要：不加盐的短摘要写进 Redis 键名后，
- * 低熵密钥可被离线猜测、泄露的密钥可被确认；代价是轮换密钥不会让缓存失效（缓存内容本来就不该依赖密钥）。
- * 没有部署配置 schema 时无从得知哪些是密钥，摘要不按配置区分。同一份配置在各副本上得到同一摘要。
- * 函数自己按 schema 遮蔽，调用方不必（也不能忘记）先打码。
+ * One item of {@link ExtensionHost.uiContributions}: a UI contribution from the manifest whose slot
+ * resolved at load (dropped ones never appear), with its registered view / action (a view's or a
+ * component's; embeds have none).
  */
-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;
+    /** The catalog slot the contribution resolved to (from `slot`, or the deprecated `place`). */
+    slot: UiSlotSpec;
+    /** For a slot with anchors: the anchor it goes after (see `resolveUiSlots`). */
+    after?: string;
     render?: UiRender;
     action?: UiActionHandler;
 }
@@ -46,6 +49,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`），
@@ -84,6 +89,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 {
@@ -108,6 +115,11 @@ export declare class ExtensionHost {
     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
@@ -175,6 +187,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 用，含待配置而未加载的）。 */
@@ -191,6 +208,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;
@@ -210,6 +232,8 @@ export declare class ExtensionHost {
     private readonly configValidity;
     /** 已告警过的「部署配置不合法」（插件名 → 说明；每个周期都会重新判定，同一说明只告警一次）。 */
     private readonly configWarned;
+    /** `<name>@<version>` whose invalid config UI hints were warned about (a log dedupe only). */
+    private readonly configUiWarned;
     /**
      * 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
@@ -233,7 +257,14 @@ export declare class ExtensionHost {
      */
     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">);
+    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`). */
@@ -290,6 +321,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).
@@ -322,6 +358,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
@@ -356,11 +399,24 @@ 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;
     /**
      * 写本副本的加载状态；失败只记 warn（状态是给后台看的，不影响加载）。这一行的版本没加载成（failed / pending）
      * 而本副本仍有别的版本在跑时，记下那个版本（`servingVersion`，后台同时显示「新版失败、旧版仍在服务」）。
+     * `servingSha256` is the package this replica actually serves for the plugin (client code follows
+     * it, client extensions spec §9.3): the row's own package when loaded; for a failed / pending row
+     * the package of the instance still running here (an older one, or the row's own package when it
+     * stays loaded, e.g. beside a provider conflict), else null.
      */
     private writeStatus;
     /**
@@ -450,6 +506,8 @@ export declare class ExtensionHost {
      * 配置声明的插件启动时不设时限（见 {@link load}）。
      */
     private setup;
+    /** Logs once per load what slot resolution left out or flagged (UI slots spec §3.2). */
+    private logUiResolution;
     /** 取能力实现：单选能力无需 providerName，多选能力必须指定。 */
     get<T>(capability: ExtensionPointRef, providerName?: string): T;
     /**
@@ -464,6 +522,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（如未加载的安装记录：调用方改用包内静态清单）。
@@ -477,12 +542,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[];
     /** 已加载插件的清单（按加载顺序，即依赖拓扑序）。 */
@@ -530,6 +621,8 @@ export declare class ExtensionHost {
      * 是否在某组织启用由调用方另查（每次查询，不缓存）。
      */
     uiContributions(): LoadedUiContribution[];
+    /** The UI contributions the loaded extension left out at load (UI slots spec §3.2); `[]` when not loaded. */
+    uiDropped(name: string): DroppedUiContribution[];
     /** 串行执行生命周期操作（unload / reload 互不交错）；宿主关闭后拒绝。 */
     private serial;
     /**