@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.4

package/dist/extensions/display-name.js

@@ -0,0 +1,77 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { ExtensionHost } from "./host.js";
+/**
+ * Extension display names (extension config forms spec §2.2), the one resolver every extension and
+ * model API uses: a config-declared extension's plugin.json (read by this replica's host at load,
+ * the same on every replica), else the installed package's `display_name`, else the live catalog
+ * item of the same name, else null. No backfill: a package stored before 0066 gets a name with its
+ * next version. Stateless; one query per call.
+ */
+let ExtensionDisplayNames = class ExtensionDisplayNames {
+    db;
+    host;
+    constructor(db, 
+    /** The config-declared extensions (they win over an install record of the same name, C15). */
+    host) {
+        this.db = db;
+        this.host = host;
+    }
+    /** One extension's display name. */
+    async get(name) {
+        return (await this.many([name])).get(name) ?? null;
+    }
+    /** The display names of `names` (each one a key, null when it has none), in one query. */
+    async many(names) {
+        const out = new Map();
+        if (names.length === 0)
+            return out;
+        const declared = new Map(this.host.declaredPlugins().map((p) => [p.name, p]));
+        const rest = [];
+        for (const n of new Set(names)) {
+            const d = declared.get(n);
+            if (d)
+                out.set(n, d.displayName);
+            else
+                rest.push(n);
+        }
+        if (rest.length === 0)
+            return out;
+        const rows = await this.db
+            .selectFrom("extension_installs")
+            .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
+            .select([
+            "extension_installs.name as name",
+            "extension_packages.display_name as display_name",
+            sql `0`.as("rank"),
+        ])
+            .where("extension_installs.name", "in", rest)
+            .unionAll((eb) => eb
+            .selectFrom("catalog_items")
+            .select(["name", "display_name", sql `1`.as("rank")])
+            .where("name", "in", rest)
+            .where("deleted_at", "is", null))
+            .execute();
+        rows.sort((a, b) => Number(a.rank) - Number(b.rank));
+        for (const n of rest) {
+            out.set(n, rows.find((r) => r.name === n && r.display_name !== null)?.display_name ?? null);
+        }
+        return out;
+    }
+};
+ExtensionDisplayNames = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ExtensionHost))
+], ExtensionDisplayNames);
+export { ExtensionDisplayNames };

package/dist/extensions/extensions.module.js

@@ -15,11 +15,13 @@ import { ExtensionApprovals } from "./approvals.js";
 import { ExtensionBlobs } from "./blobs.js";
 import { BootstrapService } from "./bootstrap.js";
 import { ExtensionDeploymentConfigService } from "./deployment-config.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle } from "./lifecycle.js";
 import { PluginApproveLock, PluginDeploymentConfigLock, PluginInstallLock } from "./locks.js";
 import { OrgExtensionConfigs } from "./org-config.js";
+import { ExtensionPointDefaults } from "./point-defaults.js";
 import { ExtensionRegistryModule } from "./registry.js";
 import { ReplicaStatusStore } from "./sources.js";
 /**
@@ -52,8 +54,10 @@ ExtensionsModule = __decorate([
             ExtensionLifecycle,
             ExtensionAdmin,
             ExtensionAdminOps,
+            ExtensionDisplayNames,
             ExtensionDeploymentConfigService,
             OrgExtensionConfigs,
+            ExtensionPointDefaults,
             BootstrapService,
         ],
         exports: [
@@ -68,8 +72,10 @@ ExtensionsModule = __decorate([
             ExtensionLifecycle,
             ExtensionAdmin,
             ExtensionAdminOps,
+            ExtensionDisplayNames,
             ExtensionDeploymentConfigService,
             OrgExtensionConfigs,
+            ExtensionPointDefaults,
             BootstrapService,
         ],
     })

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 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 { KernelAppOptions } from "../app.js";
@@ -46,6 +46,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 +86,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 {
@@ -191,6 +195,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 +219,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
@@ -290,6 +301,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).
@@ -356,6 +372,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;
     /**

package/dist/extensions/host.js

@@ -30,10 +30,11 @@ import { EmbedTokens } from "../ui/embed-token.js";
 import { ExtensionApprovals, planApprovals, readSnapshots, withPreApproved, } from "./approvals.js";
 import { ExtensionBlobIntegrityError } from "./blobs.js";
 import { toIssues } from "./config-issues.js";
+import { configFormSchema, describeConfigUiProblems } from "./config-json-schema.js";
 import { HookRegistry } from "./hooks.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ImportTracker, importExtensionModule, ManifestMismatchError, matchesSection, setupInstance, warnUpgrades, } from "./instance.js";
-import { permissionSetOfSection, readMigrationSql } from "./package.js";
+import { declaredDisplayName, permissionSetOfSection, readMigrationSql } from "./package.js";
 import { blockingKeys, computePermissionSet, UI_VIEW_KEY_PREFIX, } from "./permission-set.js";
 import { ExtensionRegistry } from "./registry.js";
 import { ExtensionResolveError, resolveExtensions } from "./resolve.js";
@@ -298,12 +299,18 @@ let ExtensionHost = class ExtensionHost {
         for (const manifest of ordered)
             assertSecretsReachable(manifest);
         const sets = await permissionSets(ordered, dirs);
-        return ordered.map((manifest) => ({
-            source: "config",
-            manifest,
-            dir: dirs.get(manifest.name),
-            permissions: sets.get(manifest.name),
-        }));
+        const out = [];
+        for (const manifest of ordered) {
+            const dir = dirs.get(manifest.name);
+            out.push({
+                source: "config",
+                manifest,
+                dir,
+                permissions: sets.get(manifest.name),
+                displayName: (await declaredDisplayName(dir, manifest.name)).displayName ?? null,
+            });
+        }
+        return out;
     }
     /**
      * M-1: plugin → mount points where deployment state expects `policy` hooks. A per-replica copy of PG
@@ -351,6 +358,11 @@ let ExtensionHost = class ExtensionHost {
     retiring = new Map();
     /** 配置声明插件的清单与权限集合（含未加载的；后台列表与网页批准用）。 */
     declaredInfo = new Map();
+    /**
+     * 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).
+     */
+    declaredDisplayNames = new Map();
     /** 导入过的插件名 → 来源与包（含未加载的；重名被跳过的一方不在这里）。 */
     sources = new Map();
     didLoad = false;
@@ -370,6 +382,8 @@ let ExtensionHost = class ExtensionHost {
     configValidity = new Map();
     /** 已告警过的「部署配置不合法」（插件名 → 说明；每个周期都会重新判定，同一说明只告警一次）。 */
     configWarned = new Map();
+    /** `<name>@<version>` whose invalid config UI hints were warned about (a log dedupe only). */
+    configUiWarned = new Set();
     /**
      * 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
@@ -461,6 +475,8 @@ let ExtensionHost = class ExtensionHost {
                 manifest: p.manifest,
                 set: p.permissions,
             });
+            if (p.displayName)
+                this.declaredDisplayNames.set(p.manifest.name, p.displayName);
             const valid = configValid.get(p.manifest.name);
             if (valid !== undefined)
                 this.configValidity.set(p.manifest.name, valid);
@@ -516,6 +532,7 @@ let ExtensionHost = class ExtensionHost {
         this.installLoader = p.installs;
         const entries = await importEntries(p.config ?? [], this.resolveFrom);
         await this.claimNames(entries);
+        await this.noteDisplayNames(entries);
         const dirs = new Map(entries.map((e) => [e.manifest.name, e.dir]));
         const urls = new Map(entries.map((e) => [e.manifest.name, e.url]));
         // 有安装记录时：配置声明的插件若 requires 只能由安装记录满足，先挑出来，等安装记录加载完再解析与加载
@@ -584,6 +601,23 @@ let ExtensionHost = class ExtensionHost {
             });
         }
     }
+    /**
+     * 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).
+     */
+    async noteDisplayNames(entries) {
+        for (const e of entries) {
+            const { displayName, problem } = await declaredDisplayName(e.dir, e.manifest.name);
+            if (displayName)
+                this.declaredDisplayNames.set(e.manifest.name, displayName);
+            if (problem !== undefined) {
+                this.log.warn("plugin.json of a config-declared extension is invalid; no display name", {
+                    plugin: e.manifest.name,
+                    problem,
+                });
+            }
+        }
+    }
     /**
      * 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).
@@ -1032,6 +1066,39 @@ let ExtensionHost = class ExtensionHost {
             });
         }
     }
+    /**
+     * 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.
+     */
+    checkConfigUi(manifest) {
+        const parts = [];
+        for (const level of ["deployment", "org"]) {
+            const schema = manifest.config?.[level];
+            if (!schema)
+                continue;
+            try {
+                const { problems } = configFormSchema(schema, level);
+                if (problems.length > 0)
+                    parts.push(describeConfigUiProblems(level, problems));
+            }
+            catch (err) {
+                parts.push(`${level} config UI hints could not be checked (${err instanceof Error ? err.message : String(err)})`);
+            }
+        }
+        if (parts.length === 0)
+            return null;
+        const detail = parts.join("; ");
+        const key = `${manifest.name}@${manifest.version}`;
+        if (!this.configUiWarned.has(key)) {
+            this.configUiWarned.add(key);
+            this.log.warn("extension config UI hints are invalid and ignored: its config forms show plain fields", { plugin: manifest.name, version: manifest.version, detail });
+        }
+        return detail;
+    }
     /** 给已有状态行补说明；失败只记 warn。 */
     async noteStatus(plugin, detail) {
         try {
@@ -1247,7 +1314,12 @@ let ExtensionHost = class ExtensionHost {
         this.unloadedForDependency.delete(name);
         const old = this.registry.activate(inst);
         this.loggedFailures.delete(name);
-        await this.writeStatus({ ...base, state: "loaded", reason: null, detail: null });
+        await this.writeStatus({
+            ...base,
+            state: "loaded",
+            reason: null,
+            detail: this.checkConfigUi(manifest),
+        });
         if (old)
             this.retire(old);
         return inst;
@@ -1294,6 +1366,7 @@ let ExtensionHost = class ExtensionHost {
                 configurable: schema !== undefined,
                 configValid: this.configValidity.get(name) ??
                     (schema ? schema.safeParse(this.extensionConfig[name] ?? {}).success : true),
+                displayName: this.declaredDisplayNames.get(name) ?? null,
             };
         });
     }
@@ -1947,7 +2020,7 @@ let ExtensionHost = class ExtensionHost {
             source: inst.source,
             state: "loaded",
             reason: null,
-            detail: null,
+            detail: this.checkConfigUi(spec.manifest),
         });
         if (old)
             await this.disposeQuietly(old, drainMs);

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

@@ -1,24 +1,32 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { OrgExtensionConfigs, type OrgExtensionView } from "./org-config.js";
 declare const PutBody: z.ZodObject<{
     enabled: z.ZodOptional<z.ZodBoolean>;
     config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     force: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+/** One extension of the org list: the org view plus the plugin's display name. */
+export type OrgExtensionItem = OrgExtensionView & {
+    displayName: LocalizedName | null;
+};
 /**
  * Org-level extension enablement and config (`/api/v1/orgs/:orgId/extensions`); responses echo only
  * non-secret config and whether each secret is set.
  */
 export declare class OrgExtensionConfigsController {
     private readonly configs;
-    constructor(configs: OrgExtensionConfigs);
+    private readonly displayNames;
+    constructor(configs: OrgExtensionConfigs, displayNames: ExtensionDisplayNames);
+    /** The org's extensions (also the channel plugin options: those providing `channel@1`). */
     list(org: OrgContext): Promise<{
-        extensions: OrgExtensionView[];
+        extensions: OrgExtensionItem[];
     }>;
     put(principal: Principal, org: OrgContext, extension: string, body: z.infer<typeof PutBody>): Promise<{
-        extension: OrgExtensionView;
+        extension: OrgExtensionItem;
     }>;
 }
 export {};

package/dist/extensions/org-config.controller.js

@@ -13,6 +13,7 @@ import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principa
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { OrgExtensionConfigs } from "./org-config.js";
 const PutBody = z
     .object({
@@ -29,17 +30,23 @@ class OrgExtensionPutBody extends createZodDto(PutBody, "OrgExtensionPutBody") {
  */
 let OrgExtensionConfigsController = class OrgExtensionConfigsController {
     configs;
-    constructor(configs) {
+    displayNames;
+    constructor(configs, displayNames) {
         this.configs = configs;
+        this.displayNames = displayNames;
     }
+    /** The org's extensions (also the channel plugin options: those providing `channel@1`). */
     async list(org) {
-        return { extensions: await this.configs.list(org.orgId) };
+        const views = await this.configs.list(org.orgId);
+        const names = await this.displayNames.many(views.map((v) => v.plugin));
+        return {
+            extensions: views.map((v) => ({ ...v, displayName: names.get(v.plugin) ?? null })),
+        };
     }
     async put(principal, org, extension, body) {
         const p = requireUser(principal);
-        return {
-            extension: await this.configs.put(org.orgId, extension, body, p.account.id, patTokenId(p)),
-        };
+        const view = await this.configs.put(org.orgId, extension, body, p.account.id, patTokenId(p));
+        return { extension: { ...view, displayName: await this.displayNames.get(view.plugin) } };
     }
 };
 __decorate([
@@ -57,6 +64,7 @@ __decorate([
 ], OrgExtensionConfigsController.prototype, "put", null);
 OrgExtensionConfigsController = __decorate([
     Controller("api/v1/orgs/:orgId/extensions"),
-    __param(0, Inject(OrgExtensionConfigs))
+    __param(0, Inject(OrgExtensionConfigs)),
+    __param(1, Inject(ExtensionDisplayNames))
 ], OrgExtensionConfigsController);
 export { OrgExtensionConfigsController };

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

@@ -166,6 +166,12 @@ export declare class OrgExtensionConfigs {
     private manifest;
     private permissionsOf;
     private view;
+    /**
+     * The org schema's form JSON Schema, a copy (`x-ui` stripped when its hints are invalid; the host
+     * warns at load). Never throws: a hint conversion that throws serves the plain schema, or null
+     * (one warning per schema on this replica), so one hand-made package cannot fail the org's list.
+     */
+    private formSchema;
     /** 该组织在 `kernel` 命名空间下已设置的插件配置密钥键（不解密）。 */
     private setSecretKeys;
 }

package/dist/extensions/org-config.js

@@ -22,7 +22,7 @@ import { KernelEvents } from "../infra/events/kernel-events.js";
 import { KERNEL_LOGGER, KEYRING } from "../infra/tokens.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { toIssues } from "./config-issues.js";
-import { configToJsonSchema } from "./config-json-schema.js";
+import { configMessages, safeConfigFormSchema } from "./config-json-schema.js";
 import { enabledExtensionsQuery, requiredExtensions } from "./enabled.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
@@ -31,16 +31,6 @@ export { toIssues };
 /** 内核自己的 secrets 命名空间（plugin-sdk 把 `kernel` 列为保留插件名，插件不会与之相撞）。 */
 const SECRETS_NAMESPACE = "kernel";
 const secretKey = (plugin, path) => `plugin-config:${plugin}:${path}`;
-/** 清单不可变：每个组织级 schema 的 JSON Schema 转换结果按 schema 对象缓存（只读、无跨请求状态）。 */
-const jsonSchemaCache = new WeakMap();
-function orgJsonSchema(schema) {
-    let js = jsonSchemaCache.get(schema);
-    if (!js) {
-        js = configToJsonSchema(schema);
-        jsonSchemaCache.set(schema, js);
-    }
-    return structuredClone(js);
-}
 const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** 按点路径设值，缺失的中间对象自动创建；中间节点不是对象时放弃（交给 schema 校验报错）。 */
 function setDeep(obj, path, value) {
@@ -258,7 +248,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             if (input.config !== undefined || enabled) {
                 const r = schema.safeParse(next);
                 if (!r.success) {
-                    throw new ApiError("extension.config_invalid", `Invalid organization config for extension ${plugin}`, toIssues(r.error));
+                    throw new ApiError("extension.config_invalid", `Invalid organization config for extension ${plugin}`, toIssues(r.error, configMessages(this.formSchema(plugin, manifest.version, schema))));
                 }
                 next = r.data;
             }
@@ -523,11 +513,20 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             config,
             secrets: paths.map((p) => ({ path: p, set: setKeys.has(secretKey(m.name, p)) })),
             permissions: permissionGroups(this.permissionsOf(m.name)),
-            orgConfigSchema: schema ? orgJsonSchema(schema) : null,
+            orgConfigSchema: schema ? this.formSchema(m.name, m.version, schema) : null,
             available: true,
             required,
         };
     }
+    /**
+     * The org schema's form JSON Schema, a copy (`x-ui` stripped when its hints are invalid; the host
+     * warns at load). Never throws: a hint conversion that throws serves the plain schema, or null
+     * (one warning per schema on this replica), so one hand-made package cannot fail the org's list.
+     */
+    formSchema(plugin, version, schema) {
+        const r = safeConfigFormSchema(schema, "org", (err, fallback) => this.log.warn("the org config form schema could not be built with its UI hints; hints dropped", { plugin, version, schema: fallback, err }));
+        return r ? structuredClone(r.schema) : null;
+    }
     /** 该组织在 `kernel` 命名空间下已设置的插件配置密钥键（不解密）。 */
     async setSecretKeys(db, orgId) {
         const rows = await db

package/dist/extensions/package.d.ts

@@ -1,4 +1,4 @@
-import { type PluginExtensionSection } from "@capybara-hq/plugin-sdk";
+import { type LocalizedName, type PluginExtensionSection } from "@capybara-hq/plugin-sdk";
 import { ApiError } from "../errors.js";
 import { HOST_ZOD_VERSION, type PackageTgzLimits } from "../packages/tgz.js";
 import { type PermissionSet } from "./permission-set.js";
@@ -57,6 +57,8 @@ export interface ExtensionPackage {
     size: number;
     packageJson: Record<string, unknown>;
     section: ExtensionPackageSection;
+    /** The plugin.json `displayName`, when the plugin has one. */
+    displayName?: LocalizedName;
     files: {
         path: string;
         size: number;
@@ -105,6 +107,17 @@ export declare function readMigrationSql(root: string, section: Pick<PluginExten
     file: string;
     sql: string;
 }[]>;
+/**
+ * The plugin.json `displayName` of the plugin a config-declared extension module belongs to: the
+ * `.capybara-plugin/plugin.json` beside the nearest `package.json` above the module's directory
+ * `dir`. Nothing when there is no such file or it names another plugin than the extension `name`
+ * (a module inside some other plugin's directory); `problem` when it cannot be read or is not a
+ * valid plugin.json (the extension then has no display name of its own).
+ */
+export declare function declaredDisplayName(dir: string, name: string): Promise<{
+    displayName?: LocalizedName;
+    problem?: string;
+}>;
 /**
  * Unpacks the package into `dir` (dropping the `package/` prefix). `dir` must not exist or be empty;
  * the unpack rules and limits are the same as {@link readExtensionPackage} (paths, file types, entry

package/dist/extensions/package.js

@@ -1,6 +1,6 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, posix, relative, resolve as resolvePath } from "node:path";
-import { checkEntryImports, isSafePackagePath, PLUGIN_MANIFEST_FILE, } from "@capybara-hq/plugin-sdk";
+import { dirname, join, posix, relative, resolve as resolvePath } from "node:path";
+import { checkEntryImports, isSafePackagePath, PLUGIN_MANIFEST_FILE, parsePluginManifest, } from "@capybara-hq/plugin-sdk";
 import { init as lexerInit, parse as lexerParse } from "es-module-lexer";
 import { PluginPackageError, readPluginPackage } from "../catalog/plugin-package.js";
 import { pluginSchemaName } from "../ctx/create-ctx.js";
@@ -159,6 +159,7 @@ export async function readExtensionPackage(bytes, opts) {
         size: plugin.size,
         packageJson: plugin.packageJson,
         section: { ...ext, name: manifest.name, version: manifest.version },
+        ...(manifest.displayName !== undefined && { displayName: manifest.displayName }),
         files: [...files].map(([path, data]) => ({ path, size: data.byteLength })),
         migrationSql,
     };
@@ -206,6 +207,54 @@ export async function readMigrationSql(root, section) {
         out.push({ file, sql: await readFile(resolvePath(dir, file), "utf8") });
     return out;
 }
+/**
+ * The plugin.json `displayName` of the plugin a config-declared extension module belongs to: the
+ * `.capybara-plugin/plugin.json` beside the nearest `package.json` above the module's directory
+ * `dir`. Nothing when there is no such file or it names another plugin than the extension `name`
+ * (a module inside some other plugin's directory); `problem` when it cannot be read or is not a
+ * valid plugin.json (the extension then has no display name of its own).
+ */
+export async function declaredDisplayName(dir, name) {
+    let root;
+    for (let d = resolvePath(dir);;) {
+        try {
+            await readFile(join(d, "package.json"));
+            root = d;
+            break;
+        }
+        catch {
+            // none here: go up
+        }
+        const up = dirname(d);
+        if (up === d)
+            return {};
+        d = up;
+    }
+    let text;
+    try {
+        text = await readFile(join(root, PLUGIN_MANIFEST_FILE), "utf8");
+    }
+    catch {
+        return {};
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (e) {
+        return { problem: `${PLUGIN_MANIFEST_FILE} is not valid JSON: ${errMsg(e)}` };
+    }
+    // another plugin's plugin.json (valid or not) says nothing about this extension
+    const named = json?.name;
+    if (typeof named === "string" && named !== name)
+        return {};
+    const m = parsePluginManifest(json);
+    if ("errors" in m)
+        return { problem: m.errors.slice(0, 3).join("; ") };
+    if (m.name !== name)
+        return {};
+    return m.displayName === undefined ? {} : { displayName: m.displayName };
+}
 /**
  * Unpacks the package into `dir` (dropping the `package/` prefix). `dir` must not exist or be empty;
  * the unpack rules and limits are the same as {@link readExtensionPackage} (paths, file types, entry

package/dist/extensions/permission-view.d.ts

@@ -1,3 +1,4 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
 import { type PermissionSet } from "./permission-set.js";
 import type { ExtensionSource } from "./sources.js";
 /**
@@ -65,6 +66,8 @@ export declare function extensionNeedsAction(status: DeploymentExtensionStatus):
 /** One item of the admin extension list (`GET /api/v1/admin/extensions`). */
 export interface AdminExtensionView {
     name: string;
+    /** The plugin's display name (`ExtensionDisplayNames`); null when it has none. */
+    displayName: LocalizedName | null;
     version: string;
     source: ExtensionSource;
     /** 安装记录的包；配置声明为 null。 */

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

@@ -0,0 +1,34 @@
+import { 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>;
+/**
+ * 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
+ *   point with its candidate providers, the stored default and the effective provider;
+ * - `PUT /api/v1/orgs/:orgId/extension-points/:point/default` `{ extension }`
+ *   (`org.extensions.manage`) → 204;
+ * - `GET /api/v1/orgs/:orgId/extension-points/available` (`agents.use`) → `{ points }`: whether
+ *   each point has a provider now, without extension names (for the agent form).
+ */
+export declare class ExtensionPointDefaultsController {
+    private readonly points;
+    constructor(points: ExtensionPointDefaults);
+    list(org: OrgContext): Promise<{
+        points: OrgPointDefaultView[];
+    }>;
+    available(org: OrgContext): Promise<{
+        points: {
+            point: string;
+            available: boolean;
+        }[];
+    }>;
+    setDefault(principal: Principal, org: OrgContext, { point }: z.infer<typeof PointParams>, body: z.infer<typeof DefaultBody>): Promise<void>;
+}
+export {};