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

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 {};

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

@@ -0,0 +1,71 @@
+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 { 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();
+class ExtensionPointParamsDto extends createZodDto(PointParams, "ExtensionPointParams") {
+}
+class ExtensionPointDefaultBodyDto extends createZodDto(DefaultBody, "ExtensionPointDefaultBody") {
+}
+/**
+ * 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).
+ */
+let ExtensionPointDefaultsController = class ExtensionPointDefaultsController {
+    points;
+    constructor(points) {
+        this.points = points;
+    }
+    async list(org) {
+        return { points: await this.points.list(org.orgId) };
+    }
+    async available(org) {
+        return { points: await this.points.available(org.orgId) };
+    }
+    async setDefault(principal, org, { point }, body) {
+        const p = requireUser(principal);
+        await this.points.setDefault(org.orgId, point, body.extension, p.account.id);
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentOrg())
+], ExtensionPointDefaultsController.prototype, "list", null);
+__decorate([
+    Get("available"),
+    OrgAction("agents.use"),
+    __param(0, CurrentOrg())
+], ExtensionPointDefaultsController.prototype, "available", null);
+__decorate([
+    Put(":point/default"),
+    HttpCode(204),
+    OrgAction("org.extensions.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ExtensionPointParamsDto)),
+    __param(3, ZBody(ExtensionPointDefaultBodyDto))
+], ExtensionPointDefaultsController.prototype, "setDefault", null);
+ExtensionPointDefaultsController = __decorate([
+    Controller("api/v1/orgs/:orgId/extension-points"),
+    __param(0, Inject(ExtensionPointDefaults))
+], ExtensionPointDefaultsController);
+export { ExtensionPointDefaultsController };

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

@@ -0,0 +1,64 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { OrgExtensionConfigs } from "./org-config.js";
+import { ExtensionRegistry } from "./registry.js";
+/** The outcome of {@link ExtensionPointDefaults.resolve}. */
+export type PointResolution<T> = {
+    ok: true;
+    extension: string;
+    impl: T;
+    orgConfig: unknown;
+} | {
+    ok: false;
+    reason: "none" | "ambiguous";
+};
+/** One `org-default` extension point of an org (the admin view). */
+export interface OrgPointDefaultView {
+    point: string;
+    /** The extensions that could serve the org now, by name. */
+    candidates: string[];
+    /** The stored default, also when it is not a candidate now. */
+    default: string | null;
+    /** The extension a call would use now; null when there is none or the choice is ambiguous. */
+    effective: string | null;
+}
+/**
+ * The org default provider of an `org-default` extension point (web tools spec §6). Per call,
+ * never cached in process: the candidates are the providers loaded on this replica that are
+ * enabled in the org, whose org config is valid and whose `configured()` (when present) does not
+ * return false. One candidate is used as is; several need the org's stored default
+ * (`capybara.org_extension_point_defaults`), else the choice is ambiguous. A stored default that
+ * is not a candidate (disabled, uninstalled, unconfigured) stays and counts again once it is one.
+ */
+export declare class ExtensionPointDefaults {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly registry;
+    private readonly orgConfigs;
+    private readonly log;
+    constructor(kdb: KernelDb, txHost: TransactionHost, registry: Pick<ExtensionRegistry, "list">, orgConfigs: Pick<OrgExtensionConfigs, "get">, log: KernelLogger);
+    /**
+     * The provider of `point` (the name without the major, e.g. `web-search`) for `orgId`, with the
+     * org's decrypted config to pass back to it. Throws when the point has no `selection`.
+     */
+    resolve<T>(orgId: string, point: string): Promise<PointResolution<T>>;
+    /** Every `org-default` point with its candidates, stored default and effective provider. */
+    list(orgId: string): Promise<OrgPointDefaultView[]>;
+    /** Whether each `org-default` point has a provider for the org now (no extension names). */
+    available(orgId: string): Promise<{
+        point: string;
+        available: boolean;
+    }[]>;
+    /**
+     * Stores `extension` as the org's default provider of `point`. 400 `validation_failed` unless
+     * 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>;
+    /** The candidates of `point` in `orgId`, by extension name. */
+    private candidates;
+    private choose;
+    /** The org's stored defaults, point → extension. */
+    private storedDefaults;
+}