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

package/dist/ctx/create-ctx.js

@@ -1,4 +1,4 @@
-import { EXTENSION_POINTS, ExtensionPermissionError, ExtensionPointUnavailableError, FILE_PREVIEW_EXTENSION_POINT, OBJECT_STORE_EXTENSION_POINT, parseExtensionPoint, validateFilePreviewProvider, validateToolSpec, } from "@capybara-hq/plugin-sdk";
+import { EXTENSION_POINTS, ExtensionPermissionError, ExtensionPointUnavailableError, FILE_PREVIEW_EXTENSION_POINT, OBJECT_STORE_EXTENSION_POINT, parseExtensionPoint, resolveUiSlots, SETUP_CHECK_ID_RE, SETUP_GUIDE_PLACES, validateFilePreviewProvider, validateToolSpec, } from "@capybara-hq/plugin-sdk";
 import { Command, ConnectionBuilder, ControlledTransactionBuilder, Kysely, TransactionBuilder, } from "kysely";
 import { conversationTopic } from "../conversations/event-log.js";
 import { kernelDb } from "../db/kernel-schema.js";
@@ -7,7 +7,7 @@ import { checkHookRegistration } from "../extensions/hooks.js";
 import { RegistrationLedger } from "../extensions/ledger.js";
 import { audit } from "../identity/audit.js";
 import { PrefixedStorage } from "../storage/storage.service.js";
-import { canUsePlace, orgUiTopic, PluginUiRegistration, } from "../ui/registry.js";
+import { canUseSlot, orgUiTopic, PLATFORM_UI_TOPIC, PluginUiRegistration, } from "../ui/registry.js";
 import { createBus } from "./bus.js";
 import { createKv } from "./kv.js";
 import { createLock } from "./lock.js";
@@ -39,6 +39,20 @@ async function currentEmbedRole(db, plugin, orgId, accountId) {
         .executeTakeFirst();
     return row?.role;
 }
+/**
+ * Whether the account is, right now, an active super admin (one query): what a platform embed
+ * token and the platform refresh stream re-check.
+ */
+export async function currentPlatformAccount(db, accountId) {
+    const row = await kernelDb(db)
+        .selectFrom("accounts")
+        .select("accounts.id")
+        .where("accounts.id", "=", accountId)
+        .where("accounts.status", "=", "active")
+        .where("accounts.is_super_admin", "=", true)
+        .executeTakeFirst();
+    return row !== undefined;
+}
 /** `ui.invalidate` 目标的一条查询：插件在该组织启用，且（带对话时）对话属于该组织。 */
 async function invalidateTargetOk(db, plugin, orgId, conversationId) {
     const k = kernelDb(db);
@@ -146,6 +160,7 @@ function guardBuilder(builder, plugin) {
 const noProviders = (deps) => ({
     providers: () => [],
     enabledPlugins: (orgId) => queryEnabledPlugins(deps.db, orgId),
+    configOk: async () => true,
 });
 /**
  * 插件实例的部署配置（已校验）：`ctx.config` 是读它的 getter。hot 字段改动时宿主替换 `value`（C10），
@@ -163,10 +178,13 @@ export class LiveConfig {
  * `deploymentConfig` may be a {@link LiveConfig} (shared by the instance, replaceable in place);
  * otherwise a fixed value is wrapped.
  * - Granted automatically: `kv`, `lock`, `bus`, `queue`, `log`, `db`, `config`, `provide`;
- * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`; `http.route`
+ * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`, `models`
+ *   only with `permissions.models` (and only its `embedding` purposes, through `deps.models`); `http.route`
  *   only the method + path declared in `permissions.http`; `tools.register` only names declared in
- *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` (during
- *   setup only); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
+ *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` or
+ *   `permissions.ui.components` (a component's server view; during setup only); `setup.check` only
+ *   ids declared in `permissions.setupChecks` (during setup only, `place` and `run` read once and
+ *   frozen); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
  *   replicas; `ui.verifyEmbedToken` checks an embed token the kernel signed: `claims.plugin` must be
  *   this extension, the extension still enabled in that org and the caller still an active member of
  *   the org (org not deleted); returns the current role;
@@ -217,6 +235,24 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             plugins: async () => [name],
         }).forPlugin(name)
         : undefined;
+    // ctx.models: only with permissions.models; the broker accepts only the purposes declared there
+    // with kind embedding (spec B §5.4), aborted by this instance's signal
+    // a frozen copy: the approved manifest, not an object the extension could change later
+    const declaredModels = Object.freeze(structuredClone(perms.models ?? []).map((m) => Object.freeze(m)));
+    const modelsApi = declaredModels.length > 0
+        ? {
+            embed: async (req) => {
+                if (!deps.models)
+                    throw new Error(`plugin ${name}: ctx.models is not available`);
+                return deps.models.embed(name, declaredModels, req, lifecycle.signal, deps.hooks);
+            },
+            describe: async (req) => {
+                if (!deps.models)
+                    throw new Error(`plugin ${name}: ctx.models is not available`);
+                return deps.models.describe(name, declaredModels, req);
+            },
+        }
+        : undefined;
     const declaredRoutes = new Set((perms.http ?? []).map((r) => `${r.method} ${r.path}`));
     const declaredTools = new Set(perms.tools ?? []);
     const declaredHooks = new Set(perms.hooks ?? []);
@@ -227,8 +263,13 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
         ...(manifest.optional ?? []),
     ]);
     const uiReg = new PluginUiRegistration(manifest, deny);
+    const declaredSetupChecks = new Set(perms.setupChecks ?? []);
+    const setupChecks = new Map();
     const embedTokens = deps.embedTokens;
-    const uiPlaces = new Map((manifest.ui ?? []).map((c) => [c.id, c.place]));
+    const uiResolution = resolveUiSlots(manifest.ui);
+    const uiSlots = new Map(uiResolution.resolved.map((r) => [r.contribution.id, r.slot]));
+    /** Ids of the extension's `platform.page` contributions (their invalidate takes no orgId). */
+    const platformUi = new Set([...uiSlots].filter(([, s]) => s.id === "platform.page").map(([id]) => id));
     /** 校验能力可取用（非 brokered、已在清单声明），返回其登记信息。 */
     const checkExtensionPoint = (ref) => {
         const capName = parseExtensionPoint(ref).name;
@@ -260,12 +301,21 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             throw new ExtensionPointUnavailableError(`extension point ${ref} has no provider`);
         return { info, chosen };
     };
-    /** 组织视角过滤提供方：orgScoped 能力只留该组织已启用的（每次查询，不缓存）。 */
+    /**
+     * The org's view of the providers: an orgScoped point keeps only those the org enabled (queried
+     * every time, not cached), and every point drops those whose effective config is not valid in
+     * the org (layering spec A §6: a call on behalf of an org never reaches such a provider).
+     */
     const forOrg = async (orgScoped, orgId, entries) => {
-        if (!orgScoped || entries.length === 0)
+        if (entries.length === 0)
             return entries;
-        const enabled = await extensionPointAccess.enabledPlugins(orgId);
-        return entries.filter((e) => enabled.has(e.plugin));
+        let out = entries;
+        if (orgScoped) {
+            const enabled = await extensionPointAccess.enabledPlugins(orgId);
+            out = out.filter((e) => enabled.has(e.plugin));
+        }
+        const ok = await Promise.all(out.map((e) => extensionPointAccess.configOk(orgId, e.plugin)));
+        return out.filter((_, i) => ok[i]);
     };
     const listAll = (ref) => {
         const info = checkExtensionPoint(ref);
@@ -280,7 +330,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             return (async () => {
                 const { info, chosen } = pick(ref, provider);
                 if ((await forOrg(info.orgScoped, orgId, [chosen])).length === 0) {
-                    throw new ExtensionPointUnavailableError(`extension point ${ref} provider ${chosen.plugin} is not enabled in organization ${orgId}`);
+                    throw new ExtensionPointUnavailableError(`extension point ${ref} provider ${chosen.plugin} is not available in organization ${orgId} (not enabled there, or its configuration is not valid there)`);
                 }
                 return chosen.impl;
             })();
@@ -399,6 +449,49 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
                 });
             },
         },
+        // Setup checks (setup guides v2 §10.2): only during setup, only ids declared in
+        // permissions.setupChecks (an undeclared or malformed id is a denial, audited); the kernel's
+        // SetupChecksService runs them (bounded, cached, redacted).
+        setup: {
+            check(id, def) {
+                if (toolsSealed) {
+                    throw new Error(`plugin ${name}: setup.check is only allowed during setup; setup has completed`);
+                }
+                if (typeof id !== "string" || !SETUP_CHECK_ID_RE.test(id) || !declaredSetupChecks.has(id)) {
+                    // the item names the id only when it has the id shape (an audit row never carries
+                    // arbitrary extension text)
+                    deny(`permissions.setupChecks ${typeof id === "string" && SETUP_CHECK_ID_RE.test(id) ? id : "(invalid id)"}`);
+                }
+                if (setupChecks.has(id)) {
+                    throw new Error(`plugin ${name}: duplicate setup check "${id}"`);
+                }
+                if (typeof def !== "object" || def === null) {
+                    throw new Error(`plugin ${name}: setup check "${id}" needs a definition object`);
+                }
+                // read once: what runs later is exactly what was checked here
+                const place = def.place;
+                const run = def.run;
+                if (!SETUP_GUIDE_PLACES.includes(place)) {
+                    throw new Error(`plugin ${name}: setup check "${id}" place must be one of ${SETUP_GUIDE_PLACES.join(", ")}`);
+                }
+                if (typeof run !== "function") {
+                    throw new Error(`plugin ${name}: setup check "${id}" run must be a function`);
+                }
+                const check = Object.freeze({
+                    place: place,
+                    run: run,
+                });
+                setupChecks.set(id, check);
+                ledger.add({
+                    kind: "setup.check",
+                    key: id,
+                    dispose: async () => {
+                        if (setupChecks.get(id) === check)
+                            setupChecks.delete(id);
+                    },
+                });
+            },
+        },
         hooks: {
             on(mount, handler, opts) {
                 if (toolsSealed) {
@@ -453,9 +546,15 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
                 });
             },
             // 目标先核对（一条查询）：插件在 orgId 启用；带对话时对话属于 orgId。不满足就只记 debug、不发
-            // （插件拿着过期或别的组织的 id 调用不是错误，但不能借它往别的组织的流里发刷新）
+            // （插件拿着过期或别的组织的 id 调用不是错误，但不能借它往别的组织的流里发刷新）。A `platform.page`
+            // contribution takes no orgId and refreshes the platform stream (super admins only)
             async invalidate(target) {
-                const t = uiReg.target(target);
+                const t = uiReg.target(target, platformUi);
+                const msg = { kind: "ui", plugin: name, contribution: t.contribution };
+                if (t.scope === "platform") {
+                    await kernelBus.publish(PLATFORM_UI_TOPIC, msg);
+                    return;
+                }
                 if (!(await invalidateTargetOk(deps.db, name, t.orgId, t.conversationId))) {
                     deps.log.debug?.("plugin ui invalidate ignored: plugin not enabled or conversation not in org", {
                         plugin: name,
@@ -465,22 +564,33 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
                     });
                     return;
                 }
-                const msg = { kind: "ui", plugin: name, contribution: t.contribution };
                 await kernelBus.publish(t.conversationId !== undefined
                     ? conversationTopic(t.conversationId)
                     : orgUiTopic(t.orgId), msg);
             },
             // 只认签给本插件、未过期、未篡改的令牌（见 ui/embed-token.ts）；再用一条查询核对此刻：本插件仍在该组织
             // 启用、组织未删除、账号 active 且仍是成员（每次查 PG、不缓存：停用插件、离职、停用账号后已签出的令牌立即失效）。
-            // 返回的 role 是此刻的角色；组织页面的令牌在调用者已降为 guest 时失效（A38）。其余一律 null
+            // 返回的 role 是此刻的角色；令牌在此刻的角色低于贡献所在位置的 minRole 时失效（A38, UI slots spec §7）。
+            // A platform token: the contribution is a `platform.page` and the account is still an active
+            // super admin. A token of one scope never verifies for the other's slots. 其余一律 null
             async verifyEmbedToken(token) {
                 const claims = embedTokens.verify(token, name);
                 if (claims === null)
                     return null;
-                const role = await currentEmbedRole(deps.db, name, claims.orgId, claims.accountId);
-                if (role === undefined)
+                const slot = uiSlots.get(claims.contribution);
+                if (claims.scope === "platform") {
+                    if (slot?.id !== "platform.page")
+                        return null;
+                    return (await currentPlatformAccount(deps.db, claims.accountId)) ? claims : null;
+                }
+                if (claims.scope !== "org" || claims.orgId === undefined)
+                    return null;
+                // the contribution's slot as loaded now: never `platform.page` through an org token, and the
+                // current role still meets the slot's minRole (a demoted caller's token stops working)
+                if (slot === undefined || slot.id === "platform.page")
                     return null;
-                if (!canUsePlace(uiPlaces.get(claims.contribution) ?? "page", role))
+                const role = await currentEmbedRole(deps.db, name, claims.orgId, claims.accountId);
+                if (role === undefined || !canUseSlot(slot, role))
                     return null;
                 return { ...claims, role };
             },
@@ -492,14 +602,15 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             if (provided.has(extensionPoint)) {
                 throw new Error(`plugin ${name}: extension point ${extensionPoint} provided more than once`);
             }
-            if (extensionPoint === FILE_PREVIEW_EXTENSION_POINT)
-                checkFilePreviewProvider(manifest, impl);
-            provided.set(extensionPoint, impl);
+            const served = extensionPoint === FILE_PREVIEW_EXTENSION_POINT
+                ? checkFilePreviewProvider(manifest, impl, uiResolution, deps.log)
+                : impl;
+            provided.set(extensionPoint, served);
             ledger.add({
                 kind: "provide",
                 key: extensionPoint,
                 dispose: async () => {
-                    if (provided.get(extensionPoint) === impl)
+                    if (provided.get(extensionPoint) === served)
                         provided.delete(extensionPoint);
                 },
             });
@@ -518,8 +629,10 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
         provided,
         registeredTools,
         registeredHooks,
+        uiResolution,
         uiViews: uiReg.views,
         uiActions: uiReg.actions,
+        setupChecks,
         ledger,
         async beginDispose(deadline) {
             drainDeadline = deadline;
@@ -551,7 +664,8 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             return closing;
         },
     };
-    // 声明了 secrets / storage 时是普通属性；未声明时是不可枚举的抛错 getter——展开 / 打印 ctx 不会触发越权与审计
+    // secrets / storage / models: a plain property when declared; otherwise a non-enumerable getter
+    // that throws, so spreading or printing ctx triggers no denial and no audit
     const gated = (key, api) => {
         if (api) {
             Object.assign(ctx, { [key]: api });
@@ -565,26 +679,52 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
     };
     gated("secrets", secretsApi);
     gated("storage", storageApi);
+    gated("models", modelsApi);
     return ctx;
 }
 /**
  * A `file-preview@1` provider must be valid when it is provided (setup fails otherwise): the shape
  * ({@link validateFilePreviewProvider}), and every `embed` names a ui contribution of this extension
- * with `kind: "embed"` and `place: "file-preview"`.
+ * with `kind: "embed"` that resolved to the slot `file.preview` (from `slot` or the deprecated
+ * `place`). A previewer whose embed names an embed contribution dropped at load (unknown slot or
+ * slot version, UI slots spec §3.2) is left out instead, with one warn per load: the returned
+ * provider is what the kernel serves.
  */
-function checkFilePreviewProvider(manifest, impl) {
+function checkFilePreviewProvider(manifest, impl, ui, log) {
     const problems = validateFilePreviewProvider(impl);
-    if (problems.length === 0) {
-        const embeds = new Set((manifest.ui ?? [])
-            .filter((c) => c.kind === "embed" && c.place === "file-preview")
-            .map((c) => c.id));
-        impl.previewers.forEach((p, i) => {
-            if (p.embed !== undefined && !embeds.has(p.embed)) {
-                problems.push(`previewers[${i}].embed "${p.embed}" is not a ui contribution { kind: "embed", place: "file-preview" }`);
-            }
-        });
+    if (problems.length > 0) {
+        throw new Error(`plugin ${manifest.name}: invalid ${FILE_PREVIEW_EXTENSION_POINT} provider: ${problems.join("; ")}`);
     }
+    const embeds = new Set(ui.resolved
+        .filter((r) => r.contribution.kind === "embed" && r.slot.id === "file.preview")
+        .map((r) => r.contribution.id));
+    const droppedEmbeds = new Map(ui.dropped
+        .filter((d) => manifest.ui?.some((c) => c.id === d.id && c.kind === "embed"))
+        .map((d) => [d.id, d]));
+    const provider = impl;
+    const kept = [];
+    const dropped = [];
+    provider.previewers.forEach((p, i) => {
+        if (p.embed === undefined || embeds.has(p.embed)) {
+            kept.push(p);
+            return;
+        }
+        const d = droppedEmbeds.get(p.embed);
+        if (d !== undefined) {
+            dropped.push({ previewer: p.id, embed: p.embed, ref: d.ref, reason: d.reason });
+            return;
+        }
+        problems.push(`previewers[${i}].embed "${p.embed}" is not a ui contribution { kind: "embed", slot: "file.preview" }`);
+    });
     if (problems.length > 0) {
         throw new Error(`plugin ${manifest.name}: invalid ${FILE_PREVIEW_EXTENSION_POINT} provider: ${problems.join("; ")}`);
     }
+    if (dropped.length === 0)
+        return impl;
+    log.warn("plugin file previewers dropped", {
+        plugin: manifest.name,
+        version: manifest.version,
+        previewers: dropped,
+    });
+    return { ...provider, previewers: kept };
 }