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

package/dist/models/enablement.js

@@ -0,0 +1,263 @@
+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, Module } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { ExtensionRegistry, ExtensionRegistryModule } from "../extensions/registry.js";
+import { audit } from "../identity/audit.js";
+import { SuperAdminLock, SuperAdminLockModule } from "../identity/super-admin.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { Cacheable, CacheEvict } from "../infra/cache/cacheable.decorator.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OrgLock, OrgLockModule } from "../orgs/org-lock.js";
+/** The key of a model in a disabled set: `provider\u0000model`. */
+export const modelKey = (provider, model) => `${provider}\u0000${model}`;
+/** How long a disabled list stays cached (s); every write evicts it after its commit. */
+const DISABLED_TTL_SECONDS = 300;
+/** The cache key of a scope's disabled list (`platform` or `org.<id>`). */
+const PLATFORM_SCOPE = "platform";
+const orgScope = (orgId) => `org.${orgId}`;
+/**
+ * Models disabled on two layers (spec B §5.3, table `model_disabled`): the platform's list (the
+ * super admin; such a model is invisible to every org) and each org's (an org admin). Every model a
+ * provider lists is enabled unless a layer disabled it; a row keys on the model id, so it applies to
+ * whichever list the org sees, and an id the list does not contain is kept harmlessly. Disabling
+ * never creates an org config copy.
+ *
+ * The lists are read from PG and cached in Redis (`@Cacheable`, evicted after the commit of each
+ * write), never in process memory. `ProviderRegistry` filters its lists and `resolve` with them;
+ * purposes check their targets with {@link isEnabled}.
+ */
+let ModelEnablement = class ModelEnablement {
+    kdb;
+    txHost;
+    cacheService;
+    extensions;
+    adminLock;
+    orgLock;
+    constructor(kdb, txHost, cacheService, extensions, adminLock, orgLock) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.cacheService = cacheService;
+        this.extensions = extensions;
+        this.adminLock = adminLock;
+        this.orgLock = orgLock;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /** One layer's disabled models (keys {@link modelKey}): the platform's (`null`) or the org's own. */
+    async disabled(orgId) {
+        return new Set(await this.disabledKeys(orgId === null ? PLATFORM_SCOPE : orgScope(orgId)));
+    }
+    async disabledKeys(scope) {
+        const orgId = scope === PLATFORM_SCOPE ? null : scope.slice("org.".length);
+        const rows = await this.rowsOf(orgId);
+        return rows.map((r) => modelKey(r.provider, r.model)).sort();
+    }
+    rowsOf(orgId, provider) {
+        let q = this.db
+            .selectFrom("model_disabled")
+            .select(["provider", "model"])
+            .where((eb) => (orgId === null ? eb("org_id", "is", null) : eb("org_id", "=", orgId)));
+        if (provider !== undefined)
+            q = q.where("provider", "=", provider);
+        return q.execute();
+    }
+    /**
+     * The extensions `orgId` explicitly turned off: a row of the org's own switch
+     * (`extension_org_configs.enabled = false`, what the org's extension or plugin switch writes when
+     * an org admin turns it off), never a required bootstrap plugin. An extension with no row for the
+     * org is not in the set (it keeps working as before: spec A §8 with B's no-breakage anti-goal).
+     * Read from PG on every call (one small query; the switch has its own writers, nothing to evict).
+     */
+    async switchedOff(orgId) {
+        const rows = await this.db
+            .selectFrom("extension_org_configs as eoc")
+            .leftJoin("extension_installs as ri", (j) => j.onRef("ri.name", "=", "eoc.plugin").on("ri.required", "=", true))
+            .select("eoc.plugin")
+            .where("eoc.org_id", "=", orgId)
+            .where("eoc.enabled", "=", false)
+            .where("ri.name", "is", null)
+            .execute();
+        return new Set(rows.map((r) => r.plugin));
+    }
+    /** Whether neither the platform nor `orgId` disabled the model (the lists only; see the class). */
+    async isEnabled(orgId, provider, model) {
+        const key = modelKey(provider, model);
+        const [platform, org] = await Promise.all([this.disabled(null), this.disabled(orgId)]);
+        return !platform.has(key) && !org.has(key);
+    }
+    /**
+     * Changes the platform's disabled ids of `provider` by `change` (super admin, re-checked under
+     * the lock): ids in neither list keep their stored state. Returns what now points at a newly
+     * disabled model, across orgs.
+     */
+    async setPlatform(provider, change, actor) {
+        await this.adminLock.lockAndAuthorize(actor.accountId);
+        return this.apply(null, provider, change, actor);
+    }
+    /**
+     * Changes the org's disabled ids of `provider` by `change` (`org.models.manage`, re-checked under
+     * the org lock): ids in neither list keep their stored state, so rows for models the org's page
+     * does not show (platform-disabled, or no longer listed) survive. Returns what in the org now
+     * points at a newly disabled model (its agents, its overrides and the deployment defaults it uses).
+     */
+    async setOrg(orgId, provider, change, actor) {
+        await this.orgLock.lockAndAuthorize(orgId, actor.accountId, "org.models.manage");
+        return this.apply(orgId, provider, change, actor);
+    }
+    async apply(orgId, provider, change, actor) {
+        if (!this.extensions.list("model-provider").some((e) => e.plugin === provider)) {
+            throw new ApiError("model.provider_not_found", `Model provider ${provider} is not installed`);
+        }
+        const disable = new Set(change.disable);
+        const both = change.enable.filter((m) => disable.has(m));
+        if (both.length > 0) {
+            throw new ApiError("validation_failed", `A model cannot be both disabled and enabled: ${[...new Set(both)].join(", ")}`);
+        }
+        const had = new Set((await this.rowsOf(orgId, provider)).map((r) => r.model));
+        const added = [...disable].filter((m) => !had.has(m)).sort();
+        const removed = [...new Set(change.enable)].filter((m) => had.has(m)).sort();
+        if (removed.length > 0) {
+            await this.db
+                .deleteFrom("model_disabled")
+                .where((eb) => (orgId === null ? eb("org_id", "is", null) : eb("org_id", "=", orgId)))
+                .where("provider", "=", provider)
+                .where("model", "in", removed)
+                .execute();
+        }
+        if (added.length > 0) {
+            await this.db
+                .insertInto("model_disabled")
+                .values(added.map((model) => ({
+                org_id: orgId,
+                provider,
+                model,
+                disabled_by: actor.accountId,
+            })))
+                .execute();
+        }
+        if (added.length > 0 || removed.length > 0) {
+            await audit(this.db, {
+                actorAccountId: actor.accountId,
+                ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+                ...(orgId !== null && { orgId }),
+                action: orgId === null ? "model.disabled_set" : "org.model_disabled_set",
+                target: provider,
+                detail: {
+                    scope: orgId === null ? "platform" : "org",
+                    disabled: added,
+                    enabled: removed,
+                },
+            });
+        }
+        return {
+            affected: {
+                agents: await this.agentsUsing(orgId, provider, added),
+                purposes: await this.purposesUsing(orgId, provider, added),
+            },
+        };
+    }
+    /** Live agents (of `orgId`, or of every org) whose current version uses one of `models`. */
+    async agentsUsing(orgId, provider, models) {
+        if (models.length === 0)
+            return [];
+        const wanted = new Set(models);
+        let q = this.db
+            .selectFrom("agents as a")
+            .innerJoin("agent_versions as v", (j) => j.onRef("v.agent_id", "=", "a.id").onRef("v.version", "=", "a.current_version"))
+            .select(["a.id", "a.org_id", "v.definition"])
+            .where("a.deleted_at", "is", null)
+            .orderBy("a.org_id")
+            .orderBy("a.id");
+        if (orgId !== null)
+            q = q.where("a.org_id", "=", orgId);
+        const out = [];
+        for (const r of await q.execute()) {
+            const def = r.definition;
+            const uses = [def?.model, def?.fallback].some((x) => {
+                const ref = x;
+                return ref?.provider === provider && typeof ref.model === "string" && wanted.has(ref.model);
+            });
+            if (uses) {
+                out.push({
+                    id: r.id,
+                    name: typeof def?.name === "string" ? def.name : r.id,
+                    orgId: r.org_id,
+                });
+            }
+        }
+        return out;
+    }
+    /**
+     * Purpose mappings targeting one of `models`: for the platform every default and override, for
+     * an org its overrides and the deployment defaults (an org that disabled a default's model has
+     * that purpose unconfigured).
+     */
+    async purposesUsing(orgId, provider, models) {
+        if (models.length === 0)
+            return [];
+        let q = this.db
+            .selectFrom("model_purpose_mappings")
+            .select(["purpose", "org_id"])
+            .where("provider", "=", provider)
+            .where("model", "in", models)
+            .orderBy("purpose")
+            .orderBy("org_id", (ob) => ob.nullsFirst());
+        if (orgId === null) {
+            return (await q.execute()).map((r) => ({ purpose: r.purpose, orgId: r.org_id }));
+        }
+        q = q.where((eb) => eb.or([eb("org_id", "is", null), eb("org_id", "=", orgId)]));
+        const rows = await q.execute();
+        // a default the org overrides is not what the org uses
+        const overridden = new Set((await this.db
+            .selectFrom("model_purpose_mappings")
+            .select("purpose")
+            .where("org_id", "=", orgId)
+            .execute()).map((r) => r.purpose));
+        return rows
+            .filter((r) => r.org_id !== null || !overridden.has(r.purpose))
+            .map((r) => ({ purpose: r.purpose, orgId: r.org_id }));
+    }
+};
+__decorate([
+    Cacheable({ key: "capk:model-disabled:#{0}", ttl: DISABLED_TTL_SECONDS })
+], ModelEnablement.prototype, "disabledKeys", null);
+__decorate([
+    Transactional(),
+    CacheEvict({ key: `capk:model-disabled:${PLATFORM_SCOPE}` })
+], ModelEnablement.prototype, "setPlatform", null);
+__decorate([
+    Transactional(),
+    CacheEvict({ key: "capk:model-disabled:org.#{0}" })
+], ModelEnablement.prototype, "setOrg", null);
+ModelEnablement = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(CacheService)),
+    __param(3, Inject(ExtensionRegistry)),
+    __param(4, Inject(SuperAdminLock)),
+    __param(5, Inject(OrgLock))
+], ModelEnablement);
+export { ModelEnablement };
+/** The one {@link ModelEnablement}: the provider registry, purposes and the controllers read it. */
+let ModelEnablementModule = class ModelEnablementModule {
+};
+ModelEnablementModule = __decorate([
+    Module({
+        imports: [ExtensionRegistryModule, SuperAdminLockModule, OrgLockModule],
+        providers: [ModelEnablement],
+        exports: [ModelEnablement],
+    })
+], ModelEnablementModule);
+export { ModelEnablementModule };

package/dist/models/models.module.d.ts

@@ -1,3 +1,7 @@
-/** Model prices and model purposes. */
+/**
+ * Model prices, model purposes, the model disabled lists and the `ctx.models` embeddings broker.
+ * Below the extension host (the host injects {@link ModelEmbeddings} for `ctx.models`): it must not
+ * import `ExtensionsModule`.
+ */
 export declare class ModelsModule {
 }

package/dist/models/models.module.js

@@ -9,16 +9,28 @@ import { ExtensionRegistryModule } from "../extensions/registry.js";
 import { IdentityModule } from "../identity/identity.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { ProvidersModule } from "../runtime/providers.js";
+import { ModelEmbeddings } from "./embeddings.js";
+import { ModelEnablementModule } from "./enablement.js";
 import { PricesService } from "./prices.js";
 import { ModelPurposesService } from "./purposes.js";
-/** Model prices and model purposes. */
+/**
+ * Model prices, model purposes, the model disabled lists and the `ctx.models` embeddings broker.
+ * Below the extension host (the host injects {@link ModelEmbeddings} for `ctx.models`): it must not
+ * import `ExtensionsModule`.
+ */
 let ModelsModule = class ModelsModule {
 };
 ModelsModule = __decorate([
     Module({
-        imports: [ExtensionRegistryModule, IdentityModule, OrgLockModule, ProvidersModule],
-        providers: [PricesService, ModelPurposesService],
-        exports: [PricesService, ModelPurposesService],
+        imports: [
+            ExtensionRegistryModule,
+            IdentityModule,
+            OrgLockModule,
+            ProvidersModule,
+            ModelEnablementModule,
+        ],
+        providers: [PricesService, ModelPurposesService, ModelEmbeddings],
+        exports: [PricesService, ModelPurposesService, ModelEnablementModule, ModelEmbeddings],
     })
 ], ModelsModule);
 export { ModelsModule };

package/dist/models/prices.d.ts

@@ -1,10 +1,10 @@
 import type { ModelUsage } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 /**
- * 一个模型的价格（C2）：每百万 token，币种为部署设置 `priceCurrency`。由企业管理员录入，插件不声明价格。
+ * 一个模型的价格（C2）：每百万 token，币种为部署设置 `priceCurrency`。由超级管理员录入，插件不声明价格。
  * 缓存读 / 写价为 null 时按输入价计。
  */
 export interface ModelPrice {
@@ -40,13 +40,13 @@ export declare class PricesService {
     private readonly db;
     readonly txHost: TransactionHost;
     private readonly adminLock;
-    constructor(db: KernelDb, txHost: TransactionHost, adminLock: EnterpriseAdminLock);
+    constructor(db: KernelDb, txHost: TransactionHost, adminLock: SuperAdminLock);
     /** 全部价格，按 provider、model 排序。 */
     list(): Promise<ModelPrice[]>;
     /** 价格表（按 {@link priceKey} 查）。 */
     table(): Promise<PriceTable>;
     /**
-     * 设置或删除（`price: null`）一个模型的价格：事务内取企业管理员锁并复核发起人仍是活跃企业管理员
+     * 设置或删除（`price: null`）一个模型的价格：事务内取超级管理员锁并复核发起人仍是活跃超级管理员
      * （否则 `forbidden`），写审计 `model_price.updated` / `model_price.deleted`。
      */
     put(input: ModelPrice | {
@@ -54,6 +54,6 @@ export declare class PricesService {
         model: string;
         price: null;
     }, actorAccountId: string, actorTokenId?: string): Promise<void>;
-    /** The write of {@link put}, under the enterprise admin lock. */
+    /** The write of {@link put}, under the super admin lock. */
     private write;
 }

package/dist/models/prices.js

@@ -11,7 +11,7 @@ import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
@@ -87,7 +87,7 @@ let PricesService = class PricesService {
         return new Map((await this.list()).map((p) => [priceKey(p.provider, p.model), p]));
     }
     /**
-     * 设置或删除（`price: null`）一个模型的价格：事务内取企业管理员锁并复核发起人仍是活跃企业管理员
+     * 设置或删除（`price: null`）一个模型的价格：事务内取超级管理员锁并复核发起人仍是活跃超级管理员
      * （否则 `forbidden`），写审计 `model_price.updated` / `model_price.deleted`。
      */
     async put(input, actorAccountId, actorTokenId) {
@@ -97,7 +97,7 @@ let PricesService = class PricesService {
         }
         await this.write(check.data, actorAccountId, actorTokenId);
     }
-    /** The write of {@link put}, under the enterprise admin lock. */
+    /** The write of {@link put}, under the super admin lock. */
     async write(v, actorAccountId, actorTokenId) {
         await this.adminLock.lockAndAuthorize(actorAccountId);
         const target = `${v.provider}/${v.model}`;
@@ -144,6 +144,6 @@ PricesService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
-    __param(2, Inject(EnterpriseAdminLock))
+    __param(2, Inject(SuperAdminLock))
 ], PricesService);
 export { PricesService };

package/dist/models/purposes.controller.d.ts

@@ -1,6 +1,7 @@
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import { ModelPurposesService, type PurposePut, type PurposeTarget, type PurposeView } from "./purposes.js";
+import { ModelPurposesService, type PurposeListing, type PurposePut, type PurposeTarget } from "./purposes.js";
 /** body 的目标（参数缺省为 `{}`）。 */
 export declare const purposeTargetOf: (b: PurposePut) => PurposeTarget | null;
 /**
@@ -9,11 +10,12 @@ export declare const purposeTargetOf: (b: PurposePut) => PurposeTarget | null;
  */
 export declare class ModelPurposesController {
     private readonly purposes;
-    constructor(purposes: ModelPurposesService);
+    private readonly displayNames;
+    constructor(purposes: ModelPurposesService, displayNames: ExtensionDisplayNames);
     list(principal: Principal, org: OrgContext): Promise<{
-        purposes: PurposeView[];
+        purposes: PurposeListing[];
     }>;
     put(principal: Principal, org: OrgContext, purpose: string, body: PurposePut): Promise<{
-        purpose: PurposeView;
+        purpose: PurposeListing;
     }>;
 }

package/dist/models/purposes.controller.js

@@ -8,10 +8,11 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, Inject, Param, Put } from "@nestjs/common";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
-import { ModelPurposesService, PurposePutDto, } from "./purposes.js";
+import { ModelPurposesService, PurposePutDto, withDeclaredByNames, } from "./purposes.js";
 /** body 的目标（参数缺省为 `{}`）。 */
 export const purposeTargetOf = (b) => b.target === null ? null : { model: b.target.model, params: b.target.params ?? {} };
 /**
@@ -20,18 +21,22 @@ export const purposeTargetOf = (b) => b.target === null ? null : { model: b.targ
  */
 let ModelPurposesController = class ModelPurposesController {
     purposes;
-    constructor(purposes) {
+    displayNames;
+    constructor(purposes, displayNames) {
         this.purposes = purposes;
+        this.displayNames = displayNames;
     }
     async list(principal, org) {
         requireUser(principal);
-        return { purposes: await this.purposes.list(org.orgId) };
+        return {
+            purposes: await withDeclaredByNames(await this.purposes.list(org.orgId), this.displayNames),
+        };
     }
     async put(principal, org, purpose, body) {
         const p = requireUser(principal);
-        return {
-            purpose: await this.purposes.setOrg(org.orgId, purpose, purposeTargetOf(body), p.account.id, patTokenId(p)),
-        };
+        const view = await this.purposes.setOrg(org.orgId, purpose, purposeTargetOf(body), p.account.id, patTokenId(p));
+        const [listing] = await withDeclaredByNames([view], this.displayNames);
+        return { purpose: listing };
     }
 };
 __decorate([
@@ -50,6 +55,7 @@ __decorate([
 ], ModelPurposesController.prototype, "put", null);
 ModelPurposesController = __decorate([
     Controller("api/v1/orgs/:orgId/model-purposes"),
-    __param(0, Inject(ModelPurposesService))
+    __param(0, Inject(ModelPurposesService)),
+    __param(1, Inject(ExtensionDisplayNames))
 ], ModelPurposesController);
 export { ModelPurposesController };

package/dist/models/purposes.d.ts

@@ -1,8 +1,8 @@
-import { type ContentBlock, type ModelRequest, type ModelUsage, type ParamValue, type StopReason } from "@capybara-hq/plugin-sdk";
+import { type ContentBlock, type LocalizedName, type ModelRequest, type ModelUsage, type ParamValue, type StopReason } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import { ModelRef } from "../agents/definition.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -11,9 +11,11 @@ import { ProviderRegistry } from "../runtime/providers.js";
 /**
  * 模型用途映射（C9）：内核与插件按「用途」取模型，不在代码里写死模型。
  * - 用途 = 内核用途 {@link KERNEL_PURPOSES}（目前只有评委 `eval`），或已加载插件 `permissions.models` 声明的；
- * - 映射 = 部署默认（`org_id` 为 null，企业管理员设）+ 组织覆盖（组织管理员设，`org.models.manage`）；
+ * - 映射 = 部署默认（`org_id` 为 null，超级管理员设）+ 组织覆盖（组织管理员设，`org.models.manage`）；
  *   生效的映射先取组织覆盖、再取部署默认，都没有 → `model.unconfigured`；
- * - 目标模型按部署范围解析（与运行时一致），参数按目标模型自己的声明严格校验；不做模型白名单；
+ * - a target's kind must equal the purpose's kind; an org's override must be enabled in the org on
+ *   save (a deployment default: not disabled on the platform), and an effective target disabled in
+ *   the org (by either layer) counts as unconfigured there (spec B §5.3)；参数按目标模型自己的声明严格校验；
  * - 每次都查 PG，不在进程内缓存（多副本下改映射立即生效）。`ctx.models` 仍预留，插件暂不能调用。
  */
 /**
@@ -46,21 +48,21 @@ export declare const KERNEL_PURPOSES: readonly [{
     readonly purpose: "subagent_fast";
     readonly kind: "chat";
     readonly label: {
-        readonly zh: "子代理：快速";
+        readonly zh: "子智能体：快速";
         readonly en: "Sub-agent: fast";
     };
 }, {
     readonly purpose: "subagent_standard";
     readonly kind: "chat";
     readonly label: {
-        readonly zh: "子代理：标准";
+        readonly zh: "子智能体：标准";
         readonly en: "Sub-agent: standard";
     };
 }, {
     readonly purpose: "subagent_capable";
     readonly kind: "chat";
     readonly label: {
-        readonly zh: "子代理：最强";
+        readonly zh: "子智能体：最强";
         readonly en: "Sub-agent: capable";
     };
 }];
@@ -82,6 +84,17 @@ export interface PurposeView {
     override: PurposeTarget | null;
     effective: PurposeTarget | null;
 }
+/**
+ * A purpose as the purpose APIs return it: the view plus the declaring extension's display name
+ * (`null` for a kernel purpose, or an extension without one), so a page names the extension.
+ */
+export interface PurposeListing extends PurposeView {
+    declaredByName: LocalizedName | null;
+}
+/** {@link PurposeListing}s of `views`, the display names read in one call. */
+export declare function withDeclaredByNames(views: PurposeView[], names: {
+    many(names: string[]): Promise<Map<string, LocalizedName | null>>;
+}): Promise<PurposeListing[]>;
 /** `PUT …/model-purposes/:purpose` 的 body：设映射，或 `target: null` 清除。 */
 export declare const PURPOSE_PUT: z.ZodObject<{
     target: z.ZodNullable<z.ZodObject<{
@@ -128,7 +141,7 @@ export declare class ModelPurposesService {
     readonly txHost: TransactionHost;
     private readonly adminLock;
     private readonly orgLock;
-    constructor(db: KernelDb, extensions: ExtensionRegistry, config: KernelConfigService, providers: Pick<ProviderRegistry, "resolve">, txHost: TransactionHost, adminLock: EnterpriseAdminLock, orgLock: OrgLock);
+    constructor(db: KernelDb, extensions: ExtensionRegistry, config: KernelConfigService, providers: Pick<ProviderRegistry, "resolve" | "platformInfo">, txHost: TransactionHost, adminLock: SuperAdminLock, orgLock: OrgLock);
     /** 全部已声明的用途：内核的在前，其后按插件加载顺序。 */
     private declared;
     private find;
@@ -136,16 +149,28 @@ export declare class ModelPurposesService {
     private views;
     /** 全部用途与映射；不给 `orgId` = 部署级视图（`override` 一律为 null）。 */
     list(orgId?: string): Promise<PurposeView[]>;
-    /** 校验目标：模型可解析（部署范围）、参数按它的声明严格通过。 */
+    /**
+     * 校验目标：模型可解析且启用（an org's override for the org, a deployment default in the
+     * platform view）、its kind is the purpose's `kind`、参数按它的声明严格通过。
+     */
     private check;
     private set;
-    /** The mapping write of {@link set}, under the enterprise admin or org lock. */
+    /** The mapping write of {@link set}, under the super admin or org lock. */
     private write;
-    /** 设置（或 `null` 清除）部署默认；只有企业管理员（事务内复核）。 */
+    /** 设置（或 `null` 清除）部署默认；只有超级管理员（事务内复核）。 */
     setDefault(purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string): Promise<PurposeView>;
     /** 设置（或 `null` 清除）组织覆盖；事务内锁组织并复核 `org.models.manage`。 */
     setOrg(orgId: string, purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string): Promise<PurposeView>;
-    /** 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。 */
+    /**
+     * 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。
+     * An effective target the org cannot use counts as unconfigured there (spec B §5.3): checked in
+     * the registry's org view, so a model the platform or the org disabled, a provider off or needing
+     * configuration in the org, a model gone from the org's list or of another kind than the purpose
+     * all give `model.unconfigured`. A provider whose list fails (`ProviderListError`) keeps the
+     * mapping: the call that follows resolves the model again and fails there, retryably, so paths
+     * that only read the mapping (sub-agent tiers, eval start, `ctx.models.describe`) do not fail on
+     * a transient list error.
+     */
     resolve(orgId: string, purpose: string): Promise<PurposeTarget>;
     /** The target a {@link chat} call on `purpose` uses: the mapping, else `fallback` when unmapped. */
     private chatTarget;