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

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` 仍预留，插件暂不能调用。
  */
 /**
@@ -35,25 +37,32 @@ export declare const KERNEL_PURPOSES: readonly [{
         readonly zh: "会话标题";
         readonly en: "Conversation titles";
     };
+}, {
+    readonly purpose: "web_fetch";
+    readonly kind: "chat";
+    readonly label: {
+        readonly zh: "网页提取";
+        readonly en: "Web page extraction";
+    };
 }, {
     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";
     };
 }];
@@ -75,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<{
@@ -121,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;
@@ -129,17 +149,52 @@ 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 checks {@link set} runs before writing, nothing written: an unknown purpose, and a target
+     * model the scope cannot use, of another kind, or with invalid params (the Platform tool's
+     * precheck, so a known failure never reaches the confirmation card).
+     */
+    validate(orgId: string | null, purpose: string, target: PurposeTarget | null): Promise<void>;
+    /** The mapping write of {@link set}, under the super admin or org lock. */
     private write;
-    /** 设置（或 `null` 清除）部署默认；只有企业管理员（事务内复核）。 */
-    setDefault(purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string): Promise<PurposeView>;
+    /** 设置（或 `null` 清除）部署默认；只有超级管理员（事务内复核）。 */
+    setDefault(purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): 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`。 */
+    setOrg(orgId: string, purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): Promise<PurposeView>;
+    /**
+     * 生效的映射：组织覆盖，否则部署默认；都没有 → `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;
+    /**
+     * The limits of the model a {@link chat} call on `purpose` would use now (the same mapping and
+     * `fallback` rule): its context window and output cap, so a caller can size its request (e.g.
+     * the `WebFetch` page) before the call. Fails as `chat` does before sending.
+     */
+    chatLimits(orgId: string, purpose: string, opts?: {
+        fallback?: PurposeTarget;
+    }): Promise<{
+        contextWindow: number;
+        maxOutputTokens: number;
+    }>;
     /**
      * 按用途发一次对话请求：解析映射、按目标模型的声明宽松处理参数（补默认值，与运行时一致），用 `consumeModelStream`
      * 收完（只有流空闲看门狗）。输出上限取 `min(req.maxOutputTokens, 目标模型的 maxOutputTokens)`。
@@ -147,10 +202,13 @@ export declare class ModelPurposesService {
      * `opts.fallback`: the target used when the purpose is not mapped (`model.unconfigured`).
      * `opts.beforeSend`: called with the resolved target and the final request just before sending;
      * what it throws is thrown as is (a pre-send failure, e.g. a denied `model.request` hook).
+     * `opts.paramDefaults`: values for parameters the target does not set, kept only where the
+     * target model declares the key and the value fits it (e.g. `thinking: "off"` for a short call).
      */
     chat(orgId: string, purpose: string, req: Omit<ModelRequest, "model" | "params">, signal: AbortSignal, opts?: {
         fallback?: PurposeTarget;
         beforeSend?: (target: ModelRef, request: ModelRequest) => Promise<void>;
+        paramDefaults?: Record<string, ParamValue>;
     }): Promise<{
         content: ContentBlock[];
         stopReason: StopReason;

package/dist/models/purposes.js

@@ -14,7 +14,7 @@ import { ModelRef, paramIssues } from "../agents/definition.js";
 import { ApiError } from "../errors.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.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";
@@ -27,9 +27,11 @@ import { ProviderListError, 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` 仍预留，插件暂不能调用。
  */
 /**
@@ -41,22 +43,36 @@ export const KERNEL_PURPOSES = [
     { purpose: "eval", kind: "chat", label: { zh: "评测评委", en: "Eval judge" } },
     /** Conversation titles (UI refresh B); unmapped → the conversation's current chat model. */
     { purpose: "title", kind: "chat", label: { zh: "会话标题", en: "Conversation titles" } },
+    /**
+     * The `WebFetch` extraction call (web tools spec §5); unmapped → the calling conversation's
+     * current chat model (a sub-agent's call: the sub-agent's).
+     */
+    { purpose: "web_fetch", kind: "chat", label: { zh: "网页提取", en: "Web page extraction" } },
     {
         purpose: "subagent_fast",
         kind: "chat",
-        label: { zh: "子代理：快速", en: "Sub-agent: fast" },
+        label: { zh: "子智能体：快速", en: "Sub-agent: fast" },
     },
     {
         purpose: "subagent_standard",
         kind: "chat",
-        label: { zh: "子代理：标准", en: "Sub-agent: standard" },
+        label: { zh: "子智能体：标准", en: "Sub-agent: standard" },
     },
     {
         purpose: "subagent_capable",
         kind: "chat",
-        label: { zh: "子代理：最强", en: "Sub-agent: capable" },
+        label: { zh: "子智能体：最强", en: "Sub-agent: capable" },
     },
 ];
+/** {@link PurposeListing}s of `views`, the display names read in one call. */
+export async function withDeclaredByNames(views, names) {
+    const plugins = views.map((v) => v.declaredBy).filter((d) => d !== "kernel");
+    const found = await names.many(plugins);
+    return views.map((v) => ({
+        ...v,
+        declaredByName: v.declaredBy === "kernel" ? null : (found.get(v.declaredBy) ?? null),
+    }));
+}
 /** `PUT …/model-purposes/:purpose` 的 body：设映射，或 `target: null` 清除。 */
 export const PURPOSE_PUT = z
     .object({
@@ -175,11 +191,17 @@ let ModelPurposesService = class ModelPurposesService {
     async list(orgId) {
         return this.views(this.declared(), orgId);
     }
-    /** 校验目标：模型可解析（部署范围）、参数按它的声明严格通过。 */
-    async check(target) {
+    /**
+     * 校验目标：模型可解析且启用（an org's override for the org, a deployment default in the
+     * platform view）、its kind is the purpose's `kind`、参数按它的声明严格通过。
+     */
+    async check(orgId, target, kind) {
         let info;
         try {
-            ({ info } = await this.providers.resolve(target.model));
+            info =
+                orgId === null
+                    ? await this.providers.platformInfo(target.model, { kind: "callable" })
+                    : (await this.providers.resolve(orgId, target.model, { kind: "callable" })).info;
         }
         catch (e) {
             if (e instanceof ProviderListError)
@@ -189,20 +211,38 @@ let ModelPurposesService = class ModelPurposesService {
             }
             throw e;
         }
+        if (info.kind !== kind) {
+            throw invalid([
+                {
+                    path: "target.model",
+                    message: `this purpose needs ${kind === "embedding" ? "an" : "a"} ${kind} model, not ${info.kind}`,
+                },
+            ]);
+        }
         const issues = paramIssues("target.params", info.parameters, target.params);
         if (issues.length > 0)
             throw invalid(issues);
     }
-    async set(orgId, purpose, target, actor, actorTokenId) {
+    async set(orgId, purpose, target, actor, actorTokenId, auditDetail) {
         const decl = this.find(purpose);
         if (target)
-            await this.check(target);
-        await this.write(orgId, purpose, target, actor, actorTokenId);
+            await this.check(orgId, target, decl.kind);
+        await this.write(orgId, purpose, target, actor, actorTokenId, auditDetail);
         const [view] = await this.views([decl], orgId ?? undefined);
         return view;
     }
-    /** The mapping write of {@link set}, under the enterprise admin or org lock. */
-    async write(orgId, purpose, target, actor, actorTokenId) {
+    /**
+     * The checks {@link set} runs before writing, nothing written: an unknown purpose, and a target
+     * model the scope cannot use, of another kind, or with invalid params (the Platform tool's
+     * precheck, so a known failure never reaches the confirmation card).
+     */
+    async validate(orgId, purpose, target) {
+        const decl = this.find(purpose);
+        if (target)
+            await this.check(orgId, target, decl.kind);
+    }
+    /** The mapping write of {@link set}, under the super admin or org lock. */
+    async write(orgId, purpose, target, actor, actorTokenId, auditDetail) {
         if (orgId === null)
             await this.adminLock.lockAndAuthorize(actor);
         else
@@ -235,25 +275,71 @@ let ModelPurposesService = class ModelPurposesService {
             ...(orgId !== null && { orgId }),
             action: "model.purpose_mapped",
             target: purpose,
-            detail: { scope: orgId === null ? "deployment" : "org", target },
+            detail: { scope: orgId === null ? "deployment" : "org", target, ...auditDetail },
         });
     }
-    /** 设置（或 `null` 清除）部署默认；只有企业管理员（事务内复核）。 */
-    setDefault(purpose, target, actor, actorTokenId) {
-        return this.set(null, purpose, target, actor, actorTokenId);
+    /** 设置（或 `null` 清除）部署默认；只有超级管理员（事务内复核）。 */
+    setDefault(purpose, target, actor, actorTokenId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
+        return this.set(null, purpose, target, actor, actorTokenId, auditDetail);
     }
     /** 设置（或 `null` 清除）组织覆盖；事务内锁组织并复核 `org.models.manage`。 */
-    setOrg(orgId, purpose, target, actor, actorTokenId) {
-        return this.set(orgId, purpose, target, actor, actorTokenId);
+    setOrg(orgId, purpose, target, actor, actorTokenId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
+        return this.set(orgId, purpose, target, actor, actorTokenId, auditDetail);
     }
-    /** 生效的映射：组织覆盖，否则部署默认；都没有 → `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.
+     */
     async resolve(orgId, purpose) {
-        const [view] = await this.views([this.find(purpose)], orgId);
+        const decl = this.find(purpose);
+        const [view] = await this.views([decl], orgId);
         if (!view?.effective) {
             throw new ApiError("model.unconfigured", `No model is configured for the "${purpose}" purpose`);
         }
+        try {
+            await this.providers.resolve(orgId, view.effective.model, { kind: decl.kind });
+        }
+        catch (e) {
+            if (e instanceof ProviderListError)
+                return view.effective;
+            if (e instanceof ApiError && e.code === "agent.model_unavailable") {
+                throw new ApiError("model.unconfigured", `The model configured for the "${purpose}" purpose is not available in this organization`);
+            }
+            throw e;
+        }
         return view.effective;
     }
+    /** The target a {@link chat} call on `purpose` uses: the mapping, else `fallback` when unmapped. */
+    async chatTarget(orgId, purpose, fallback) {
+        try {
+            return await this.resolve(orgId, purpose);
+        }
+        catch (e) {
+            if (!(e instanceof ApiError && e.code === "model.unconfigured") || !fallback)
+                throw e;
+            return fallback;
+        }
+    }
+    /**
+     * The limits of the model a {@link chat} call on `purpose` would use now (the same mapping and
+     * `fallback` rule): its context window and output cap, so a caller can size its request (e.g.
+     * the `WebFetch` page) before the call. Fails as `chat` does before sending.
+     */
+    async chatLimits(orgId, purpose, opts = {}) {
+        const target = await this.chatTarget(orgId, purpose, opts.fallback);
+        const { info } = await this.providers.resolve(orgId, target.model);
+        return { contextWindow: info.contextWindow, maxOutputTokens: info.maxOutputTokens };
+    }
     /**
      * 按用途发一次对话请求：解析映射、按目标模型的声明宽松处理参数（补默认值，与运行时一致），用 `consumeModelStream`
      * 收完（只有流空闲看门狗）。输出上限取 `min(req.maxOutputTokens, 目标模型的 maxOutputTokens)`。
@@ -261,22 +347,17 @@ let ModelPurposesService = class ModelPurposesService {
      * `opts.fallback`: the target used when the purpose is not mapped (`model.unconfigured`).
      * `opts.beforeSend`: called with the resolved target and the final request just before sending;
      * what it throws is thrown as is (a pre-send failure, e.g. a denied `model.request` hook).
+     * `opts.paramDefaults`: values for parameters the target does not set, kept only where the
+     * target model declares the key and the value fits it (e.g. `thinking: "off"` for a short call).
      */
     async chat(orgId, purpose, req, signal, opts = {}) {
-        let target;
-        try {
-            target = await this.resolve(orgId, purpose);
-        }
-        catch (e) {
-            if (!(e instanceof ApiError && e.code === "model.unconfigured") || !opts.fallback)
-                throw e;
-            target = opts.fallback;
-        }
-        const { provider, info } = await this.providers.resolve(target.model);
+        const target = await this.chatTarget(orgId, purpose, opts.fallback);
+        const { provider, info } = await this.providers.resolve(orgId, target.model);
         const request = {
             ...req,
             model: info.id,
-            params: sanitizeParams(info.parameters, target.params).value,
+            // undeclared or unfitting defaults are dropped like any other parameter
+            params: sanitizeParams(info.parameters, { ...opts.paramDefaults, ...target.params }).value,
             // 输出上限不超过目标模型自己的上限（与运行时 assembleModelRequest 一致）
             maxOutputTokens: Math.min(req.maxOutputTokens, info.maxOutputTokens),
         };
@@ -311,7 +392,7 @@ ModelPurposesService = __decorate([
     __param(2, Inject(KernelConfigService)),
     __param(3, Inject(ProviderRegistry)),
     __param(4, Inject(TransactionHost)),
-    __param(5, Inject(EnterpriseAdminLock)),
+    __param(5, Inject(SuperAdminLock)),
     __param(6, Inject(OrgLock))
 ], ModelPurposesService);
 export { ModelPurposesService };

package/dist/orgs/directory-sync.d.ts

@@ -1,5 +1,6 @@
 import type { Queue } from "bullmq";
 import type { Redis } from "ioredis";
+import { EffectiveConfigs } from "../extensions/effective-config.js";
 import { OrgExtensionConfigs } from "../extensions/org-config.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { ExternalIdentities } from "../identity/external.js";
@@ -35,9 +36,11 @@ export declare const DIRECTORY_MAX_PAGES = 10000;
 export type DirectorySyncTrigger = "schedule" | "changed" | "manual";
 /**
  * 不同步的原因（陈旧任务、插件已停用 / 配置不再有效、组织已删除、另一同步在跑；`not_configured`：插件的
- * `Directory.configured` 说这份组织配置没配好通讯录，Ruling A28，静默跳过）。
+ * `Directory.configured` 说这份组织配置没配好通讯录，Ruling A28，静默跳过）。`needs_config`: the
+ * extension's effective deployment config for the org is not valid (layering spec A §6): skipped
+ * silently like `not_configured`; the org admin sees the extension as needing configuration.
  */
-export type DirectorySkipReason = "plugin_unavailable" | "org_not_found" | "not_enabled" | "config_invalid" | "not_configured" | "locked";
+export type DirectorySkipReason = "plugin_unavailable" | "org_not_found" | "not_enabled" | "config_invalid" | "not_configured" | "needs_config" | "locked";
 export type DirectorySyncResult = {
     status: "skipped";
     reason: DirectorySkipReason;
@@ -122,18 +125,23 @@ export declare class DirectorySync {
     private readonly redis;
     private readonly registry;
     private readonly orgConfigs;
+    private readonly effective;
     private readonly external;
     private readonly offboarding;
     private readonly orgLock;
     private readonly queue;
     readonly lockService: LockService;
     readonly log: KernelLogger;
-    constructor(db: KernelDb, txHost: TransactionHost, redis: Redis, registry: Pick<ExtensionRegistry, "list">, orgConfigs: Pick<OrgExtensionConfigs, "get">, external: Pick<ExternalIdentities, "resolve">, offboarding: Pick<Offboarding, "offboard" | "afterOffboard">, orgLock: OrgLock, queue: Pick<Queue, "add">, lockService: LockService, log: KernelLogger);
+    constructor(db: KernelDb, txHost: TransactionHost, redis: Redis, registry: Pick<ExtensionRegistry, "list">, orgConfigs: Pick<OrgExtensionConfigs, "get">, effective: Pick<EffectiveConfigs, "get">, external: Pick<ExternalIdentities, "resolve">, offboarding: Pick<Offboarding, "offboard" | "afterOffboard">, orgLock: OrgLock, queue: Pick<Queue, "add">, lockService: LockService, log: KernelLogger);
     /** A `directory-sync` job (dispatched by `MaintenanceProcessor`). */
     runSyncJob(data: SyncJobData): Promise<void>;
     /** 插件提供的 `directory@1`；未加载或不提供时 undefined。 */
     private provider;
-    /** The org exists, the extension provides a directory, is enabled in the org and its org config satisfies the schema (reuses the `OrgExtensionConfigs.get` validation). */
+    /**
+     * The org exists, the extension provides a directory, is enabled in the org, its org config
+     * satisfies the schema (reuses the `OrgExtensionConfigs.get` validation) and its effective
+     * deployment config for the org is valid (layering spec A §6).
+     */
     private eligible;
     /**
      * 投递一次 `directory_changed` 同步（按分钟桶去重）；返回 job id。入站 `directory_changed` 经
@@ -146,7 +154,8 @@ export declare class DirectorySync {
      * Manual trigger by an admin: re-checks `org.members.manage` live under the org row lock, then that
      * the extension can sync (does not provide a directory -> `extension.not_found`, not enabled ->
      * `extension.not_enabled`, config no longer valid -> `extension.config_invalid`, the extension says
-     * the directory is not configured -> `directory.not_configured`, Ruling A28), and enqueues a sync
+     * the directory is not configured -> `directory.not_configured`, Ruling A28; the effective config
+     * is not valid in the org -> `extension.needs_config`, layering spec A §6), and enqueues a sync
      * job with a unique id.
      */
     request(orgId: string, plugin: string, actorAccountId: string, actorTokenId?: string): Promise<{

package/dist/orgs/directory-sync.js

@@ -12,6 +12,7 @@ import { DIRECTORY_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../errors.js";
+import { EffectiveConfigs } from "../extensions/effective-config.js";
 import { enabledExtensionsByOrg } from "../extensions/enabled.js";
 import { OrgExtensionConfigs } from "../extensions/org-config.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
@@ -80,6 +81,8 @@ export function directorySyncJobId(orgId, plugin, trigger, now = new Date()) {
             return `${base}-manual-${randomUUID()}`;
     }
 }
+/** Skips that log nothing and enqueue nothing: Ruling A28 and an org needing configuration. */
+const silentSkip = (reason) => reason === "not_configured" || reason === "needs_config";
 /** 组织已删除（同步途中）：停止本轮。 */
 class OrgGone extends Error {
 }
@@ -122,18 +125,20 @@ let DirectorySync = class DirectorySync {
     redis;
     registry;
     orgConfigs;
+    effective;
     external;
     offboarding;
     orgLock;
     queue;
     lockService;
     log;
-    constructor(db, txHost, redis, registry, orgConfigs, external, offboarding, orgLock, queue, lockService, log) {
+    constructor(db, txHost, redis, registry, orgConfigs, effective, external, offboarding, orgLock, queue, lockService, log) {
         this.db = db;
         this.txHost = txHost;
         this.redis = redis;
         this.registry = registry;
         this.orgConfigs = orgConfigs;
+        this.effective = effective;
         this.external = external;
         this.offboarding = offboarding;
         this.orgLock = orgLock;
@@ -144,8 +149,8 @@ let DirectorySync = class DirectorySync {
     /** A `directory-sync` job (dispatched by `MaintenanceProcessor`). */
     async runSyncJob(data) {
         const r = await this.sync(data.orgId, data.plugin, data);
-        // 通讯录未配置（Ruling A28）静默跳过
-        if (r.status === "skipped" && r.reason !== "not_configured") {
+        // 通讯录未配置（Ruling A28）and an org needing configuration (spec A §6) are skipped silently
+        if (r.status === "skipped" && !silentSkip(r.reason)) {
             this.log.info("directory sync skipped", {
                 orgId: data.orgId,
                 plugin: data.plugin,
@@ -159,7 +164,11 @@ let DirectorySync = class DirectorySync {
             .list("directory")
             .find((e) => e.plugin === plugin && e.capability === DIRECTORY_EXTENSION_POINT)?.impl;
     }
-    /** The org exists, the extension provides a directory, is enabled in the org and its org config satisfies the schema (reuses the `OrgExtensionConfigs.get` validation). */
+    /**
+     * The org exists, the extension provides a directory, is enabled in the org, its org config
+     * satisfies the schema (reuses the `OrgExtensionConfigs.get` validation) and its effective
+     * deployment config for the org is valid (layering spec A §6).
+     */
     async eligible(orgId, plugin) {
         const directory = this.provider(plugin);
         if (!directory)
@@ -186,11 +195,21 @@ let DirectorySync = class DirectorySync {
         }
         if (!cfg?.enabled)
             return { ok: false, reason: "not_enabled" };
+        let effective;
+        try {
+            effective = await this.effective.get(orgId, plugin);
+        }
+        catch (err) {
+            this.log.warn("directory sync: cannot read the effective config", { orgId, plugin, err });
+            return { ok: false, reason: "config_invalid" };
+        }
+        if (!effective.ok)
+            return { ok: false, reason: "needs_config" };
         // Ruling A28：插件说通讯录没配好（组织只用它的别的能力）→ 不同步；插件实现出错按未配置处理
         if (directory.configured !== undefined) {
             let configured = false;
             try {
-                configured = directory.configured(cfg.config) === true;
+                configured = directory.configured(cfg.config, effective.config) === true;
             }
             catch {
                 configured = false;
@@ -198,7 +217,7 @@ let DirectorySync = class DirectorySync {
             if (!configured)
                 return { ok: false, reason: "not_configured" };
         }
-        return { ok: true, directory, orgConfig: cfg.config };
+        return { ok: true, directory, orgConfig: cfg.config, config: effective.config };
     }
     /**
      * 投递一次 `directory_changed` 同步（按分钟桶去重）；返回 job id。入站 `directory_changed` 经
@@ -207,7 +226,7 @@ let DirectorySync = class DirectorySync {
      */
     async enqueue(orgId, plugin, now = new Date()) {
         const e = await this.eligible(orgId, plugin);
-        if (!e.ok && e.reason === "not_configured")
+        if (!e.ok && silentSkip(e.reason))
             return undefined;
         return this.addJob(orgId, plugin, "changed", directorySyncJobId(orgId, plugin, "changed", now));
     }
@@ -234,7 +253,8 @@ let DirectorySync = class DirectorySync {
      * Manual trigger by an admin: re-checks `org.members.manage` live under the org row lock, then that
      * the extension can sync (does not provide a directory -> `extension.not_found`, not enabled ->
      * `extension.not_enabled`, config no longer valid -> `extension.config_invalid`, the extension says
-     * the directory is not configured -> `directory.not_configured`, Ruling A28), and enqueues a sync
+     * the directory is not configured -> `directory.not_configured`, Ruling A28; the effective config
+     * is not valid in the org -> `extension.needs_config`, layering spec A §6), and enqueues a sync
      * job with a unique id.
      */
     async request(orgId, plugin, actorAccountId, actorTokenId) {
@@ -252,6 +272,8 @@ let DirectorySync = class DirectorySync {
                     throw new ApiError("extension.config_invalid", `Invalid organization config for extension ${plugin}`);
                 case "not_configured":
                     throw new ApiError("directory.not_configured", `The directory of extension ${plugin} is not configured for this organization`);
+                case "needs_config":
+                    throw new ApiError("extension.needs_config", `Extension ${plugin} needs configuration in this organization`);
             }
         }
         const jobId = await this.addJob(orgId, plugin, "manual", directorySyncJobId(orgId, plugin, "manual"), { accountId: actorAccountId, tokenId: actorTokenId });
@@ -324,7 +346,7 @@ let DirectorySync = class DirectorySync {
         // 锁丢了（续租失败、过期后被他人取得）：停止本轮，不再移除任何人
         const signal = lease.lost;
         try {
-            return await this.run(orgId, plugin, e.directory, e.orgConfig, signal, opts);
+            return await this.run(orgId, plugin, e.directory, e.orgConfig, e.config, signal, opts);
         }
         finally {
             await lease.release().catch(() => { });
@@ -346,7 +368,7 @@ let DirectorySync = class DirectorySync {
             this.log.warn("directory sync: cannot enqueue follow-up sync", { orgId, plugin, err });
         }
     }
-    async run(orgId, plugin, directory, orgConfig, signal, opts) {
+    async run(orgId, plugin, directory, orgConfig, config, signal, opts) {
         const source = `directory:${plugin}`;
         const counts = { added: 0, removed: 0, skippedLastOwner: 0, failed: 0, total: 0 };
         /** 本轮仍在职的账号（只在本次任务内使用）。 */
@@ -363,6 +385,7 @@ let DirectorySync = class DirectorySync {
                 signal.throwIfAborted();
                 const r = await directory.listMembers({
                     orgConfig,
+                    config,
                     ...(cursor !== undefined && { cursor }),
                     signal: AbortSignal.any([signal, AbortSignal.timeout(DIRECTORY_PAGE_TIMEOUT_MS)]),
                 });
@@ -409,7 +432,7 @@ let DirectorySync = class DirectorySync {
             if (!still.ok) {
                 partial = true;
                 // 途中通讯录配置被清空（Ruling A28）：照样不移除，但不记警告
-                if (still.reason !== "not_configured") {
+                if (!silentSkip(still.reason)) {
                     this.log.warn("directory sync: plugin no longer eligible before removals", {
                         orgId,
                         plugin,
@@ -609,12 +632,13 @@ DirectorySync = __decorate([
     __param(2, Inject(REDIS)),
     __param(3, Inject(ExtensionRegistry)),
     __param(4, Inject(OrgExtensionConfigs)),
-    __param(5, Inject(ExternalIdentities)),
-    __param(6, Inject(Offboarding)),
-    __param(7, Inject(OrgLock)),
-    __param(8, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
-    __param(9, Inject(LockService)),
-    __param(10, Inject(KERNEL_LOGGER))
+    __param(5, Inject(EffectiveConfigs)),
+    __param(6, Inject(ExternalIdentities)),
+    __param(7, Inject(Offboarding)),
+    __param(8, Inject(OrgLock)),
+    __param(9, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(10, Inject(LockService)),
+    __param(11, Inject(KERNEL_LOGGER))
 ], DirectorySync);
 export { DirectorySync };
 /** The hourly directory scan ({@link DirectorySync.scan}), once per tick across replicas; a worker-role job (`WorkerModule`). */