@capybara-hq/kernel 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/extensions/host.d.ts

@@ -10,9 +10,11 @@ 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";
@@ -21,15 +23,7 @@ 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";
-/**
- * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
- * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
- * 给需要「配置变了就失效」的缓存键用（如模型列表）。密钥不参与摘要：不加盐的短摘要写进 Redis 键名后，
- * 低熵密钥可被离线猜测、泄露的密钥可被确认；代价是轮换密钥不会让缓存失效（缓存内容本来就不该依赖密钥）。
- * 没有部署配置 schema 时无从得知哪些是密钥，摘要不按配置区分。同一份配置在各副本上得到同一摘要。
- * 函数自己按 schema 遮蔽，调用方不必（也不能忘记）先打码。
- */
-export declare function deploymentConfigHash(schema: core.$ZodType | undefined, config: unknown): string;
+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;
@@ -185,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 用，含待配置而未加载的）。 */
@@ -255,7 +254,9 @@ export declare class ExtensionHost {
      * 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">);
+    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`). */
@@ -520,12 +521,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[];
     /** 已加载插件的清单（按加载顺序，即依赖拓扑序）。 */

package/dist/extensions/host.js

@@ -7,14 +7,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { EXTENSION_POINT_CARDINALITY, parseExtensionPoint, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
-import { changedPaths, configFields, getPath, secretValues, setPath, unreachableSecrets, } from "../config/fields.js";
+import { changedPaths, configFields, secretValues, unreachableSecrets } from "../config/fields.js";
 import { pluginSchemaName, queryEnabledPlugins, } from "../ctx/create-ctx.js";
 import { kernelDb } from "../db/kernel-schema.js";
 import { migrate } from "../db/migrator.js";
@@ -25,10 +24,12 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { LockService } from "../infra/lock/lock.service.js";
 import { KERNEL_LOGGER, KEYRING, REDIS, REDIS_SUBSCRIBER } from "../infra/tokens.js";
 import { KERNEL_APP_OPTIONS } from "../lifecycle/tokens.js";
+import { ModelEmbeddings } from "../models/embeddings.js";
 import { packagePath } from "../packages/tgz.js";
 import { EmbedTokens } from "../ui/embed-token.js";
 import { ExtensionApprovals, planApprovals, readSnapshots, withPreApproved, } from "./approvals.js";
 import { ExtensionBlobIntegrityError } from "./blobs.js";
+import { deploymentConfigHash } from "./config-hash.js";
 import { toIssues } from "./config-issues.js";
 import { configFormSchema, describeConfigUiProblems } from "./config-json-schema.js";
 import { EffectiveConfigs } from "./effective-config.js";
@@ -42,42 +43,7 @@ import { ExtensionRegistry } from "./registry.js";
 import { ExtensionResolveError, resolveExtensions } from "./resolve.js";
 import { ReplicaStatusStore, } from "./sources.js";
 import { PackageShaMismatchError, packageRootOf } from "./sync.js";
-/** 键排序后的 JSON（对象键顺序不影响结果）；undefined 字段与 JSON.stringify 一样省略。 */
-const canonicalJson = (v) => {
-    if (Array.isArray(v))
-        return `[${v.map((x) => (x === undefined ? "null" : canonicalJson(x))).join(",")}]`;
-    if (v !== null && typeof v === "object") {
-        const entries = Object.entries(v)
-            .filter(([, x]) => x !== undefined)
-            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-        return `{${entries.map(([k, x]) => `${JSON.stringify(k)}:${canonicalJson(x)}`).join(",")}}`;
-    }
-    return JSON.stringify(v) ?? "null";
-};
-/** 遮蔽 secret 字段后参与摘要的固定占位值。 */
-const SECRET_PLACEHOLDER = "<secret>";
-/**
- * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
- * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
- * 给需要「配置变了就失效」的缓存键用（如模型列表）。密钥不参与摘要：不加盐的短摘要写进 Redis 键名后，
- * 低熵密钥可被离线猜测、泄露的密钥可被确认；代价是轮换密钥不会让缓存失效（缓存内容本来就不该依赖密钥）。
- * 没有部署配置 schema 时无从得知哪些是密钥，摘要不按配置区分。同一份配置在各副本上得到同一摘要。
- * 函数自己按 schema 遮蔽，调用方不必（也不能忘记）先打码。
- */
-export function deploymentConfigHash(schema, config) {
-    let redacted = null;
-    if (schema) {
-        redacted = structuredClone(config);
-        if (redacted !== null && typeof redacted === "object") {
-            for (const f of configFields(schema)) {
-                if (f.meta?.secret && getPath(redacted, f.path) !== undefined) {
-                    setPath(redacted, f.path, SECRET_PLACEHOLDER);
-                }
-            }
-        }
-    }
-    return createHash("sha256").update(canonicalJson(redacted)).digest("hex").slice(0, 16);
-}
+export { deploymentConfigHash };
 const CLOSED_DURING_LOAD = "plugin host closed during load";
 /** 停机时等进行中的 unload / reload 的上限（之后直接关闭 setup 中的 ctx、撤销其余实例）。 */
 const CLOSE_LIFECYCLE_WAIT_MS = 2_000;
@@ -345,6 +311,11 @@ let ExtensionHost = class ExtensionHost {
      * 安装记录不在这里：每次 converge 都按 PG 期望状态重新判定。
      */
     pendingActivations = new Map();
+    /**
+     * 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).
+     */
+    declaredActivations = new Map();
     /** 安装记录准备好的候选（按插件名；sha 变了就作废）。 */
     prepared = new Map();
     /** 闸门放行后导入过的安装记录真实清单（按插件名；部署配置 schema 用，含待配置而未加载的）。 */
@@ -415,7 +386,9 @@ let ExtensionHost = class ExtensionHost {
      * Each hook call's effective config for its organization, and the providers excluded from an
      * org's point resolution (layering spec A §6).
      */
-    effective) {
+    effective, 
+    /** `ctx.models`: the embeddings broker (spec B §5.4). */
+    models) {
         this.registry = registry;
         this.installs = installs;
         this.approvals = approvals;
@@ -424,6 +397,16 @@ let ExtensionHost = class ExtensionHost {
         this.log = log;
         this.effective = effective;
         const c = config.get();
+        this.hooks = new HookRegistry({
+            instances: () => this.registry.all(),
+            current: (plugin) => this.registry.current(plugin),
+            expectedPolicy: (mount) => this.expectedPolicy(mount),
+            enabledPlugins: (orgId) => this.enabledPlugins(orgId),
+            effectiveConfig: (orgId, plugin) => effective.get(orgId, plugin),
+            locks,
+            config: () => ({ hooks: { timeoutMs: this.config.get().hooks.timeoutMs } }),
+            log,
+        });
         this.deps = {
             db: kdb.pool,
             dbUrl: c.db.url,
@@ -433,20 +416,13 @@ let ExtensionHost = class ExtensionHost {
             redisUrl: c.redis.url,
             keyring,
             embedTokens,
+            models,
+            // ctx.models.embed fires model.request through the same registry (spec B §5.4)
+            hooks: this.hooks,
             locks,
             runWorkers: c.roles.includes("worker"),
             log,
         };
-        this.hooks = new HookRegistry({
-            instances: () => this.registry.all(),
-            current: (plugin) => this.registry.current(plugin),
-            expectedPolicy: (mount) => this.expectedPolicy(mount),
-            enabledPlugins: (orgId) => this.enabledPlugins(orgId),
-            effectiveConfig: (orgId, plugin) => effective.get(orgId, plugin),
-            locks,
-            config: () => ({ hooks: { timeoutMs: this.config.get().hooks.timeoutMs } }),
-            log,
-        });
         this.registry.onChange(() => {
             this.installedCache = undefined;
         });
@@ -1323,6 +1299,8 @@ let ExtensionHost = class ExtensionHost {
         }
         // 升级：替换加载参数（之后的依赖方连锁与 reload 用新版本），先登记新实例、再撤销旧实例
         this.specs.set(name, spec);
+        if (a.source !== "install")
+            this.declaredActivations.set(name, a);
         this.unloadedForDependency.delete(name);
         const old = this.registry.activate(inst);
         this.loggedFailures.delete(name);
@@ -1753,7 +1731,9 @@ let ExtensionHost = 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）。
@@ -1792,6 +1772,10 @@ let ExtensionHost = class ExtensionHost {
             }
             const r = parseLoadGate(schema, raw);
             if (!r.success) {
+                if (await this.clearedInPg(plugin)) {
+                    await this.unloadForMissingConfig(inst, toIssues(r.error));
+                    return "unloaded";
+                }
                 this.log.warn("plugin deployment config changed but is invalid on this replica; keeping the current config", {
                     plugin,
                     detail: toIssues(r.error)
@@ -1841,6 +1825,95 @@ let ExtensionHost = class ExtensionHost {
             return "reload";
         });
     }
+    /** PG holds no deployment config for the plugin (it was cleared); a read error counts as no. */
+    async clearedInPg(plugin) {
+        try {
+            return !(await this.installs.hasStoredDeploymentConfig(plugin));
+        }
+        catch (err) {
+            this.log.warn("cannot read whether the plugin has a stored deployment config", {
+                plugin,
+                err,
+            });
+            return false;
+        }
+    }
+    /**
+     * 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.
+     */
+    async unloadForMissingConfig(inst, issues) {
+        const plugin = inst.name;
+        const drainMs = this.drainMs();
+        const gone = await this.doUnload(plugin, drainMs, null);
+        if (!gone)
+            return;
+        await this.markPendingConfig({ plugin, version: gone.version, sha256: gone.sha256, source: gone.source }, issues, "extension unloaded: its deployment config was cleared and what remains is missing or invalid (set it in the admin console or the startup config; it loads without a restart)");
+        await this.cascade(gone.manifest.provides, drainMs);
+    }
+    /**
+     * 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.
+     */
+    async markPendingConfig(p, issues, message) {
+        const detail = issues.map((i) => `${i.path || "<root>"}: ${i.message}`).join("; ");
+        const declared = this.declaredActivations.get(p.plugin);
+        if (p.source !== "install") {
+            this.configValidity.set(p.plugin, false);
+            if (declared)
+                this.pendingActivations.set(p.plugin, { ...declared, fatal: false });
+        }
+        this.configWarned.set(p.plugin, detail);
+        this.log.warn(message, { plugin: p.plugin, source: p.source, detail });
+        await this.writeStatus({ ...p, state: "pending", reason: "config", detail });
+    }
+    /**
+     * 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).
+     */
+    async refreshConfigForRestore(name, spec) {
+        const schema = spec.manifest.config?.deployment;
+        if (!schema)
+            return true;
+        let raw;
+        try {
+            raw = await this.rawConfigOf(name, schema);
+        }
+        catch (err) {
+            this.log.error("cannot read the stored deployment config of plugin; restoring it on its previous config", { plugin: name, err });
+            return true;
+        }
+        const r = parseLoadGate(schema, raw);
+        if (!r.success) {
+            if (!(await this.clearedInPg(name)))
+                return true;
+            await this.markPendingConfig({
+                plugin: name,
+                version: spec.manifest.version,
+                sha256: spec.sha256,
+                source: spec.source,
+            }, toIssues(r.error), "extension not restored after its dependency came back: its deployment config was cleared and what remains is missing or invalid (set it in the admin console or the startup config; it loads without a restart)");
+            return false;
+        }
+        if (spec.source !== "install")
+            this.configValidity.set(name, true);
+        if (changedPaths(schema, spec.config, r.data).length > 0) {
+            this.reportSecrets(schema, r.data);
+            this.specs.set(name, {
+                ...spec,
+                config: r.data,
+                configHash: deploymentConfigHash(schema, r.data),
+            });
+        }
+        return true;
+    }
     /** 本次未加载、等待批准权限的插件（含因 `requires` 只能由它们满足而未加载的插件），按依赖拓扑序。 */
     pending() {
         return structuredClone(this.pendingPlugins);
@@ -2118,6 +2191,10 @@ let ExtensionHost = class ExtensionHost {
                 const available = providedNow();
                 if (!(spec.manifest.requires ?? []).every((c) => available.has(c)))
                     continue;
+                if (!(await this.refreshConfigForRestore(name, spec))) {
+                    this.unloadedForDependency.delete(name);
+                    continue;
+                }
                 try {
                     await this.doReload(name, drainMs);
                     progress = true;
@@ -2201,6 +2278,7 @@ ExtensionHost = __decorate([
     __param(10, Inject(LockService)),
     __param(11, Inject(KERNEL_LOGGER)),
     __param(12, Inject(KERNEL_APP_OPTIONS)),
-    __param(13, Inject(EffectiveConfigs))
+    __param(13, Inject(EffectiveConfigs)),
+    __param(14, Inject(ModelEmbeddings))
 ], ExtensionHost);
 export { ExtensionHost };

package/dist/extensions/installs.d.ts

@@ -107,6 +107,11 @@ export declare class ExtensionInstalls {
      * the fields of `schema` when it is given.
      */
     effectiveDeploymentConfig(plugin: string, fileValue: unknown, schema?: core.$ZodType): Promise<unknown>;
+    /**
+     * Whether PG holds a deployment config row for the extension (a super admin saved one and has
+     * not cleared it since; `DELETE /api/v1/admin/extensions/:name/config` removes it).
+     */
+    hasStoredDeploymentConfig(plugin: string): Promise<boolean>;
     /** Every install record's extension name (any desired state). */
     installedNames(): Promise<string[]>;
     /**

package/dist/extensions/installs.js

@@ -76,6 +76,18 @@ let ExtensionInstalls = class ExtensionInstalls {
         const fields = schema ? configFields(schema).map((f) => f.path) : undefined;
         return mergeDeploymentConfig(stored, fileValue, fields);
     }
+    /**
+     * Whether PG holds a deployment config row for the extension (a super admin saved one and has
+     * not cleared it since; `DELETE /api/v1/admin/extensions/:name/config` removes it).
+     */
+    async hasStoredDeploymentConfig(plugin) {
+        const row = await this.db
+            .selectFrom("extension_deployment_configs")
+            .select("plugin")
+            .where("plugin", "=", plugin)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
     /** Every install record's extension name (any desired state). */
     async installedNames() {
         const rows = await this.db.selectFrom("extension_installs").select("name").execute();

package/dist/extensions/org-config.d.ts

@@ -11,7 +11,8 @@ import { type JsonSchema } from "./config-json-schema.js";
 import { EffectiveConfigs } from "./effective-config.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
-import { type PermissionGroup } from "./permission-view.js";
+import { type DeploymentExtensionStatus, type PermissionGroup } from "./permission-view.js";
+import { ExtensionAvailability, type ExtensionUnavailableReason } from "./unavailable.js";
 export { type ConfigIssue, toIssues };
 /** 组织视角下一个已加载插件的状态；`config` 永远不含密钥字段，密钥只回显「是否已设置」。 */
 export interface OrgExtensionView {
@@ -35,6 +36,16 @@ export interface OrgExtensionView {
      * 组织的启用开关保留不变（不能修改），其余字段为空。
      */
     available: boolean;
+    /**
+     * The extension's status on the deployment, as the admin console derives it
+     * (`deriveExtensionStatus`): `enabled` when it is loaded here; otherwise why not.
+     */
+    status: DeploymentExtensionStatus;
+    /**
+     * Only when unavailable: why it cannot be used (spec §14.5 item 4), e.g.
+     * `needs_deployment_config`. State only, never a config value or field name.
+     */
+    reason?: ExtensionUnavailableReason;
     /**
      * A required bootstrap plugin: enabled in every org (`enabled` is always true) and cannot be
      * disabled here (`extension.required`); its org config, when it has one, can still be set.
@@ -121,6 +132,8 @@ export declare class OrgExtensionConfigs {
     private readonly log;
     /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
     private readonly effective;
+    /** Why an installed extension is not loaded (`status` / `reason` of the unavailable ones). */
+    private readonly availability;
     /** Test seam only: a deterministic interleaving point after the config rows are read, before the secrets. */
     afterConfigRowRead: (() => Promise<void>) | undefined;
     constructor(kdb: KernelDb, txHost: TransactionHost, keyring: Keyring, host: ExtensionHost, 
@@ -133,7 +146,9 @@ export declare class OrgExtensionConfigs {
     /** Secret values handled (written or decrypted) are masked in the logs after the commit. */
     log: KernelLogger, 
     /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
-    effective: EffectiveConfigs);
+    effective: EffectiveConfigs, 
+    /** Why an installed extension is not loaded (`status` / `reason` of the unavailable ones). */
+    availability: ExtensionAvailability);
     /** The kernel-schema handle of the current transaction. */
     private get db();
     /** 把一份组织配置里的密钥值登记到日志打码（无密钥时无操作）；调用方须在事务提交后调用。 */

package/dist/extensions/org-config.js

@@ -29,8 +29,9 @@ import { enabledExtensionsQuery, requiredExtensions } from "./enabled.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { fieldLevels } from "./org-levels.js";
-import { permissionGroups } from "./permission-view.js";
+import { permissionGroups, } from "./permission-view.js";
 import { itemLocked, pluginItemsOf } from "./plugin-items.js";
+import { ExtensionAvailability } from "./unavailable.js";
 export { toIssues };
 /** 内核自己的 secrets 命名空间（plugin-sdk 把 `kernel` 列为保留插件名，插件不会与之相撞）。 */
 const SECRETS_NAMESPACE = "kernel";
@@ -104,6 +105,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
     events;
     log;
     effective;
+    availability;
     /** Test seam only: a deterministic interleaving point after the config rows are read, before the secrets. */
     afterConfigRowRead;
     constructor(kdb, txHost, keyring, host, 
@@ -116,7 +118,9 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
     /** Secret values handled (written or decrypted) are masked in the logs after the commit. */
     log, 
     /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
-    effective) {
+    effective, 
+    /** Why an installed extension is not loaded (`status` / `reason` of the unavailable ones). */
+    availability) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.keyring = keyring;
@@ -126,6 +130,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
         this.events = events;
         this.log = log;
         this.effective = effective;
+        this.availability = availability;
     }
     /** The kernel-schema handle of the current transaction. */
     get db() {
@@ -154,7 +159,16 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             name: r.name,
             version: r.version,
         }));
-        return this.withLayers(orgId, await this.listSnapshot(orgId, installed));
+        const views = await this.listSnapshot(orgId, installed);
+        const why = await this.availability.unavailable(views.filter((v) => !v.available).map((v) => v.plugin));
+        for (const v of views) {
+            const u = why.get(v.plugin);
+            if (v.available || u === undefined || u.status === null)
+                continue;
+            v.status = u.status;
+            v.reason = u.reason;
+        }
+        return this.withLayers(orgId, views);
     }
     /**
      * Fills `overrideState` and the platform half of `needsConfig` (spec A §6) for the views of
@@ -219,6 +233,9 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             permissions: [],
             orgConfigSchema: null,
             available: false,
+            // filled in by `list` from the replicas' reports
+            status: "converging",
+            reason: "loading",
             required: required.has(i.name),
             ...scopeFields(items.get(i.name), required.has(i.name)),
             overrideState: "none",
@@ -619,6 +636,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             permissions: permissionGroups(this.permissionsOf(m.name)),
             orgConfigSchema: schema ? this.formSchema(m.name, m.version, schema) : null,
             available: true,
+            status: "enabled",
             required,
             ...scopeFields(items, required),
             overrideState: [...fieldLevels(m.config?.deployment).values()].includes("override")
@@ -682,7 +700,8 @@ OrgExtensionConfigs = __decorate([
     __param(5, Inject(ExtensionInstalls)),
     __param(6, Inject(KernelEvents)),
     __param(7, Inject(KERNEL_LOGGER)),
-    __param(8, Inject(EffectiveConfigs))
+    __param(8, Inject(EffectiveConfigs)),
+    __param(9, Inject(ExtensionAvailability))
 ], OrgExtensionConfigs);
 export { OrgExtensionConfigs };
 /**

package/dist/extensions/point-defaults.controller.d.ts

@@ -1,13 +1,8 @@
-import { z } from "zod";
+import type { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { ExtensionPointDefaults, type OrgPointDefaultView } from "./point-defaults.js";
-declare const PointParams: z.ZodObject<{
-    point: z.ZodString;
-}, z.core.$strip>;
-declare const DefaultBody: z.ZodObject<{
-    extension: z.ZodString;
-}, z.core.$strict>;
+import { ExtensionPointDefaultBody as DefaultBody, ExtensionPointParams as PointParams } from "./point-defaults.schemas.js";
 /**
  * The org default provider of `org-default` extension points (web tools spec §6):
  * - `GET /api/v1/orgs/:orgId/extension-points` (`org.extensions.manage`) → `{ points }`: each
@@ -31,4 +26,3 @@ export declare class ExtensionPointDefaultsController {
     }>;
     setDefault(principal: Principal, org: OrgContext, { point }: z.infer<typeof PointParams>, body: z.infer<typeof DefaultBody>): Promise<void>;
 }
-export {};

package/dist/extensions/point-defaults.controller.js

@@ -8,14 +8,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, HttpCode, Inject, Put } from "@nestjs/common";
-import { z } from "zod";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { ExtensionPointDefaults } from "./point-defaults.js";
-const PointParams = z.object({ point: z.string().min(1).max(100) });
-const DefaultBody = z.object({ extension: z.string().min(1).max(214) }).strict();
+import { ExtensionPointDefaultBody as DefaultBody, ExtensionPointParams as PointParams, } from "./point-defaults.schemas.js";
 class ExtensionPointParamsDto extends createZodDto(PointParams, "ExtensionPointParams") {
 }
 class ExtensionPointDefaultBodyDto extends createZodDto(DefaultBody, "ExtensionPointDefaultBody") {

package/dist/extensions/point-defaults.d.ts

@@ -62,7 +62,9 @@ export declare class ExtensionPointDefaults {
      * the point is an `org-default` one and the extension provides it (loaded here) and is enabled
      * in the org. Audited as `extension_point.default_set`.
      */
-    setDefault(orgId: string, point: string, extension: string, actorId: string): Promise<void>;
+    setDefault(orgId: string, point: string, extension: string, actorId: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): Promise<void>;
     /** The candidates of `point` in `orgId`, by extension name. */
     private candidates;
     private choose;

package/dist/extensions/point-defaults.js

@@ -100,7 +100,9 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
      * the point is an `org-default` one and the extension provides it (loaded here) and is enabled
      * in the org. Audited as `extension_point.default_set`.
      */
-    async setDefault(orgId, point, extension, actorId) {
+    async setDefault(orgId, point, extension, actorId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
         const db = this.kdb.db;
         if (!hasSelection(point)) {
             throw new ApiError("validation_failed", `${point} is not an extension point with an organization default`);
@@ -123,7 +125,7 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
             orgId,
             action: "extension_point.default_set",
             target: point,
-            detail: { point, extension },
+            detail: { point, extension, ...auditDetail },
         });
     }
     /** The candidates of `point` in `orgId`, by extension name. */

package/dist/extensions/point-defaults.schemas.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const ExtensionPointParams: z.ZodObject<{
+    point: z.ZodString;
+}, z.core.$strip>;
+export declare const ExtensionPointDefaultBody: z.ZodObject<{
+    extension: z.ZodString;
+}, z.core.$strict>;
+export declare const EXTENSION_POINT_ROUTES: readonly RouteSchemas[];

package/dist/extensions/point-defaults.schemas.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export const ExtensionPointParams = z.object({ point: z.string().min(1).max(100) });
+export const ExtensionPointDefaultBody = z
+    .object({ extension: z.string().min(1).max(214) })
+    .strict();
+export const EXTENSION_POINT_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/extension-points" },
+    { route: "GET /api/v1/orgs/:orgId/extension-points/available" },
+    {
+        route: "PUT /api/v1/orgs/:orgId/extension-points/:point/default",
+        params: ExtensionPointParams,
+        body: ExtensionPointDefaultBody,
+    },
+];

package/dist/extensions/state.module.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The extension state the model domain reads below the host: the install records with their
+ * packages and approvals, and each extension's effective config per org. Apart from
+ * `ExtensionsModule` so the model provider registry (and the `ctx.models` broker the host injects)
+ * can depend on it without a module cycle (writing-kernel-api: a cycle is cut by moving the shared
+ * part into its own provider both sides inject). `ExtensionsModule` re-exports it.
+ */
+export declare class ExtensionStateModule {
+}