@capybara-hq/kernel 0.1.0-rc.12 → 0.1.0-rc.14

package/dist/conversations/{environment-status.d.ts → device-status.d.ts}

@@ -1,24 +1,24 @@
-import { EnvironmentsService, type EnvironmentView } from "../environments/environments.service.js";
+import { DevicesService, type DeviceView } from "../devices/devices.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { ConversationAccess } from "./access.js";
 import { ConversationsService } from "./conversations.service.js";
 /**
- * The environment a conversation works in, for its page (environments spec §9: shown read only):
+ * The device a conversation works in, for its page (environments spec §9: shown read only):
  * a conversation the viewer may not see → `conversation.not_found`. A sub-agent shows its root
- * conversation's environment. Null while the conversation is unbound, or when its environment is
+ * conversation's device. Null while the conversation is unbound, or when its device is
  * deleted or no longer its owner's (its sandbox tools then fail).
  */
-export declare class ConversationEnvironmentStatus {
+export declare class ConversationDeviceStatus {
     /** Who may see the conversation (the rule of its event stream). */
     private readonly access;
-    /** The conversation whose environment it works in: a sub-agent's root, else itself. */
+    /** The conversation whose device it works in: a sub-agent's root, else itself. */
     private readonly conversations;
-    private readonly environments;
+    private readonly devices;
     private readonly db;
     constructor(
     /** Who may see the conversation (the rule of its event stream). */
     access: Pick<ConversationAccess, "isAccessible">, 
-    /** The conversation whose environment it works in: a sub-agent's root, else itself. */
-    conversations: Pick<ConversationsService, "sandboxConversationOf">, environments: Pick<EnvironmentsService, "get">, db: KernelDb);
-    get(orgId: string, conversationId: string, viewerAccountId: string): Promise<EnvironmentView | null>;
+    /** The conversation whose device it works in: a sub-agent's root, else itself. */
+    conversations: Pick<ConversationsService, "sandboxConversationOf">, devices: Pick<DevicesService, "get">, db: KernelDb);
+    get(orgId: string, conversationId: string, viewerAccountId: string): Promise<DeviceView | null>;
 }

package/dist/conversations/{environment-status.js → device-status.js}

@@ -8,31 +8,31 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Inject, Injectable } from "@nestjs/common";
-import { EnvironmentsService } from "../environments/environments.service.js";
+import { DevicesService } from "../devices/devices.service.js";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { UUID_RE } from "../ui/registry.js";
 import { ConversationAccess } from "./access.js";
 import { ConversationsService } from "./conversations.service.js";
 /**
- * The environment a conversation works in, for its page (environments spec §9: shown read only):
+ * The device a conversation works in, for its page (environments spec §9: shown read only):
  * a conversation the viewer may not see → `conversation.not_found`. A sub-agent shows its root
- * conversation's environment. Null while the conversation is unbound, or when its environment is
+ * conversation's device. Null while the conversation is unbound, or when its device is
  * deleted or no longer its owner's (its sandbox tools then fail).
  */
-let ConversationEnvironmentStatus = class ConversationEnvironmentStatus {
+let ConversationDeviceStatus = class ConversationDeviceStatus {
     access;
     conversations;
-    environments;
+    devices;
     db;
     constructor(
     /** Who may see the conversation (the rule of its event stream). */
     access, 
-    /** The conversation whose environment it works in: a sub-agent's root, else itself. */
-    conversations, environments, db) {
+    /** The conversation whose device it works in: a sub-agent's root, else itself. */
+    conversations, devices, db) {
         this.access = access;
         this.conversations = conversations;
-        this.environments = environments;
+        this.devices = devices;
         this.db = db;
     }
     async get(orgId, conversationId, viewerAccountId) {
@@ -40,32 +40,32 @@ let ConversationEnvironmentStatus = class ConversationEnvironmentStatus {
             !(await this.access.isAccessible(orgId, conversationId, viewerAccountId))) {
             throw new ApiError("conversation.not_found", "Conversation not found");
         }
-        // a sub-agent works in its root conversation's environment (at every depth)
+        // a sub-agent works in its root conversation's device (at every depth)
         const root = await this.conversations.sandboxConversationOf(orgId, conversationId);
         const conv = await this.db
             .selectFrom("conversations")
-            .select(["account_id", "environment_id"])
+            .select(["account_id", "device_id"])
             .where("id", "=", root)
             .where("org_id", "=", orgId)
             .executeTakeFirst();
-        if (!conv?.environment_id)
+        if (!conv?.device_id)
             return null;
         try {
-            // the environment as its owner sees it (only the owner may use a personal environment)
-            return await this.environments.get(orgId, conv.account_id, conv.environment_id);
+            // the device as its owner sees it (only the owner may use a personal device)
+            return await this.devices.get(orgId, conv.account_id, conv.device_id);
         }
         catch (e) {
-            if (e instanceof ApiError && e.code === "environment.not_found")
+            if (e instanceof ApiError && e.code === "device.not_found")
                 return null;
             throw e;
         }
     }
 };
-ConversationEnvironmentStatus = __decorate([
+ConversationDeviceStatus = __decorate([
     Injectable(),
     __param(0, Inject(ConversationAccess)),
     __param(1, Inject(ConversationsService)),
-    __param(2, Inject(EnvironmentsService)),
+    __param(2, Inject(DevicesService)),
     __param(3, Inject(KernelDb))
-], ConversationEnvironmentStatus);
-export { ConversationEnvironmentStatus };
+], ConversationDeviceStatus);
+export { ConversationDeviceStatus };

package/dist/conversations/event-log.d.ts

@@ -132,7 +132,7 @@ export declare class EventLog {
     findByIdem(conversationId: string, idemKey: string): Promise<ConversationEvent | undefined>;
     /**
      * The conversation's latest event of `type` (by seq); undefined without one. `skills_catalog`
-     * (0025) and `environment_paths` (0094) have partial indexes that answer it directly; other
+     * (0025) and `device_paths` (0094) have partial indexes that answer it directly; other
      * types scan the conversation's events backwards on the (conversation_id, seq) key, the whole
      * conversation when it has none.
      */

package/dist/conversations/event-log.js

@@ -246,7 +246,7 @@ let EventLog = class EventLog {
     }
     /**
      * The conversation's latest event of `type` (by seq); undefined without one. `skills_catalog`
-     * (0025) and `environment_paths` (0094) have partial indexes that answer it directly; other
+     * (0025) and `device_paths` (0094) have partial indexes that answer it directly; other
      * types scan the conversation's events backwards on the (conversation_id, seq) key, the whole
      * conversation when it has none.
      */

package/dist/conversations/events.d.ts

@@ -516,7 +516,7 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         removed: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"environment_paths">;
+    type: z.ZodLiteral<"device_paths">;
     payload: z.ZodObject<{
         roots: z.ZodObject<{
             workspace: z.ZodString;

package/dist/conversations/events.js

@@ -447,10 +447,10 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
      * The directories of the instance a sandbox tool call entered, when they differ from the
      * defaults (environments spec §13.1: a connected machine's real paths). Written once per
      * conversation and roots, before that call's result. **Model-visible**: rendered at its position
-     * as a system message (`environmentPathsText`); a summary covering it is followed by the latest
+     * as a system message (`devicePathsText`); a summary covering it is followed by the latest
      * one again.
      */
-    ev("environment_paths", z.object({
+    ev("device_paths", z.object({
         roots: z.object({
             workspace: z.string().min(1).max(4096),
             skills: z.string().min(1).max(4096),

package/dist/ctx/create-ctx.d.ts

@@ -1,4 +1,4 @@
-import { type ExtensionContext, type ExtensionManifest, type ExtensionPointRef, type Logger, type ToolHandler, type ToolSpec } from "@capybara-hq/plugin-sdk";
+import { type ExtensionContext, type ExtensionManifest, type ExtensionPointRef, type Logger, resolveUiSlots, type SetupCheckArgs, type SetupGuidePlace, type ToolHandler, type ToolSpec } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { Kysely } from "kysely";
 import { type RegisteredHook } from "../extensions/hooks.js";
@@ -52,6 +52,15 @@ export type RegisteredTool = {
     spec: ToolSpec;
     handler: ToolHandler;
 };
+/**
+ * A setup check registered through `ctx.setup.check`: `place` and `run` read once from the
+ * definition at registration and frozen, so the extension cannot swap them afterwards (a getter
+ * on the definition runs once, at registration, never when a check runs).
+ */
+export type RegisteredSetupCheck = Readonly<{
+    place: SetupGuidePlace;
+    run: (args: SetupCheckArgs) => Promise<unknown>;
+}>;
 /** 插件经 `ctx.extensionPoints` 取用其他插件能力时，内核注入的访问接口。 */
 export interface ExtensionPointAccess {
     /** 已加载（setup 完成）的提供方，按加载顺序；按完整引用（含主版本）精确匹配。 */
@@ -72,8 +81,15 @@ export interface ExtensionPointAccess {
  * required bootstrap plugins, see `extensions/enabled.ts`), not cached.
  */
 export declare function queryEnabledPlugins(db: Kysely<any>, orgId: string): Promise<Set<string>>;
+/**
+ * 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 declare function currentPlatformAccount(db: KernelDeps["db"], accountId: string): Promise<boolean>;
 /** 插件的 PG schema 名：`plugin_<name>`，name 中的 `-` 换成 `_`。 */
 export declare function pluginSchemaName(name: string): string;
+/** What {@link resolveUiSlots} returns for a manifest. */
+export type UiResolution = ReturnType<typeof resolveUiSlots>;
 /** 内核视角的插件 ctx：插件契约之外还带宿主要用的登记信息与关闭方法。 */
 export type KernelExtensionContext = ExtensionContext & {
     /** 本实例的登记账（C17）：每次登记记一笔，撤销时逐项撤销。 */
@@ -92,11 +108,17 @@ export type KernelExtensionContext = ExtensionContext & {
     registeredTools: RegisteredTool[];
     /** Hooks registered through `ctx.hooks.on` (registration order). */
     registeredHooks: RegisteredHook[];
+    /** The manifest's `ui` resolved against the slot catalog once per load (UI slots spec §3.2). */
+    uiResolution: UiResolution;
     /** 经 `ctx.ui.view` 注册的视图（按贡献 id）。 */
     uiViews: ReadonlyMap<string, UiRender>;
     /** 经 `ctx.ui.action` 注册的动作处理函数（按贡献 id）。 */
     uiActions: ReadonlyMap<string, UiActionHandler>;
-    /** setup 结束后调用：此后 `tools.register`、`ui.view`、`ui.action`、`hooks.on` 抛错。 */
+    /** Setup checks registered through `ctx.setup.check`, by id. */
+    setupChecks: ReadonlyMap<string, RegisteredSetupCheck>;
+    /**
+     * setup 结束后调用：此后 `tools.register`、`ui.view`、`ui.action`、`hooks.on`、`setup.check` 抛错。
+     */
     sealTools(): void;
     /** 中止 signal、封账并逐项撤销仍在账上的登记、关闭队列连接（幂等）。 */
     close(): Promise<void>;
@@ -119,7 +141,8 @@ export declare class LiveConfig {
  *   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
+ *   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;

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);
@@ -168,7 +182,8 @@ export class LiveConfig {
  *   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
+ *   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;
@@ -247,8 +262,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;
@@ -428,6 +448,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) {
@@ -482,9 +545,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,
@@ -494,22 +563,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;
-                if (!canUsePlace(uiPlaces.get(claims.contribution) ?? "page", role))
+                // 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;
+                const role = await currentEmbedRole(deps.db, name, claims.orgId, claims.accountId);
+                if (role === undefined || !canUseSlot(slot, role))
                     return null;
                 return { ...claims, role };
             },
@@ -521,14 +601,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);
                 },
             });
@@ -547,8 +628,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;
@@ -601,21 +684,46 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
 /**
  * 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 };
 }

package/dist/db/kernel-schema.d.ts

@@ -257,8 +257,8 @@ export interface ConversationsTable {
     deleted_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
     /** 0074: levels below the root conversation (0 = a root; a sub-agent's is its parent's + 1). */
     subagent_depth: ColumnType<number, number | undefined, number>;
-    /** 0088: the environment the conversation runs in; null = not chosen yet. */
-    environment_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /** 0088, renamed in 0105: the device the conversation runs in; null = not chosen yet. */
+    device_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
 /** 0060: an org's order of file-preview@1 previewers (UI refresh B Task 11). */
 export interface FilePreviewersTable {
@@ -419,6 +419,11 @@ export interface ConnectorsTable {
     template_tool_policies: ColumnType<Record<string, "allow" | "ask" | "deny"> | null, string | null | undefined, string | null>;
     /** 0081: the platform connector template this connector was made from (null = none). */
     platform_template_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /**
+     * 0106: the setup guide of its connector template it was last set up with (`{ guideId, version,
+     * hash, mode: null }`); null when unknown (custom connectors, connectors before 0106).
+     */
+    guide_ack: ColumnType<GuideAckJson | null, string | null | undefined, string | null>;
 }
 /**
  * 0104: a member's own policy for one tool of a personal-credential connector, for calls made with
@@ -567,12 +572,16 @@ export interface LgCheckpointWritesTable {
     task_path: Generated<string>;
 }
 /** 0018_channels.sql：组织的渠道连接（非密钥配置；密钥在 secrets `channels:<id>:config`）。 */
-/** `channel_connections.guide_ack` (0099): the setup guide a connection was set up with. */
+/**
+ * `channel_connections.guide_ack` (0099) and `connectors.guide_ack` (0106): the setup guide a
+ * target was set up with; `hash` is the v2 drift hash (`setupGuideHash`, admin audience) of
+ * `mode` (null for a place without modes).
+ */
 export interface GuideAckJson {
     guideId: string;
     version: string;
     hash: string;
-    mode: string;
+    mode: string | null;
 }
 export interface ChannelConnectionsTable {
     id: string;
@@ -783,8 +792,8 @@ export interface BackgroundTasksTable {
     read_offset: ColumnType<string, number | string | undefined, number | string>;
     /** Set while a stop is under way (0072); the poller skips such a task. */
     stopping_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
-    /** 0088: the environment the task runs in. */
-    environment_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /** 0088, renamed in 0105: the device the task runs in. */
+    device_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
 /** 0023_sandboxes.sql: the legacy per-conversation sandbox; kept only for the cleanup job (0088). */
 export interface LegacySandboxesTable {
@@ -818,26 +827,29 @@ type InstanceHandle = ColumnType<{
     id: string;
     [k: string]: unknown;
 } | null, string | null | undefined, string | null>;
-/** 0088_environments.sql: a long-lived environment (one instance plus a kept file system). */
-export interface EnvironmentsTable {
+/**
+ * 0088_environments.sql, renamed in 0105: a device. A cloud device is one instance plus a kept file
+ * system; a local device is a person's machine (device_machines).
+ */
+export interface DevicesTable {
     id: string;
     org_id: string;
     owner_kind: "personal";
     owner_account_id: string;
     name: ColumnType<string | null, string | null | undefined, string | null>;
     is_default: ColumnType<boolean, boolean | undefined, boolean>;
-    /** 0093: `device` is a connected machine (environment_machines). */
-    source: "cloud" | "device";
+    /** 0093, renamed in 0105: `local` is a person's machine (device_machines). */
+    source: "cloud" | "local";
     provider: ColumnType<string | null, string | null | undefined, string | null>;
-    /** 0096: the provider a demoted default was demoted from; null for every other environment. */
+    /** 0096: the provider a demoted default was demoted from; null for every other device. */
     demoted_from_provider: ColumnType<string | null, string | null | undefined, string | null>;
     created_at: Ts;
     updated_at: Ts;
     deleted_at: TsNullable;
 }
-/** 0088_environments.sql: the instance and file system of an environment (replaces sandboxes). */
-export interface EnvironmentInstancesTable {
-    environment_id: string;
+/** 0088_environments.sql, renamed in 0105: the instance and file system of a device. */
+export interface DeviceInstancesTable {
+    device_id: string;
     org_id: string;
     provider: ColumnType<string | null, string | null | undefined, string | null>;
     /** The provider's `FileSystemHandle`; null before the file system exists or after a reset. */
@@ -862,13 +874,13 @@ export interface EnvironmentInstancesTable {
     sweep_failed_at: TsNullable;
 }
 /**
- * 0093_connected_environments.sql: the machine connected to a `device` environment. At most one
- * unrevoked row per environment; revoking sets `revoked_at` and keeps the row.
+ * 0093_connected_environments.sql, renamed in 0105: the machine of a local device. At most one
+ * unrevoked row per device; revoking sets `revoked_at` and keeps the row.
  */
-export interface EnvironmentMachinesTable {
+export interface DeviceMachinesTable {
     id: Generated<string>;
     org_id: string;
-    environment_id: string;
+    device_id: string;
     account_id: string;
     /** A hash of the machine credential, never the credential itself. */
     credential_hash: string;
@@ -884,11 +896,11 @@ export interface EnvironmentMachinesTable {
     created_at: Ts;
     revoked_at: TsNullable;
 }
-/** 0088_environments.sql: the environment a member's new conversations use by default. */
-export interface EnvironmentDefaultsTable {
+/** 0088_environments.sql, renamed in 0105: the device a member's new conversations use by default. */
+export interface DeviceDefaultsTable {
     org_id: string;
     account_id: string;
-    environment_id: string;
+    device_id: string;
     updated_at: Ts;
 }
 /** pg numeric：驱动读出为字符串（精确小数），读取方自行 `Number()`。 */
@@ -1170,10 +1182,10 @@ export interface KernelDatabase {
     directory_exclusions: DirectoryExclusionsTable;
     attachments: AttachmentsTable;
     sandboxes: LegacySandboxesTable;
-    environments: EnvironmentsTable;
-    environment_instances: EnvironmentInstancesTable;
-    environment_defaults: EnvironmentDefaultsTable;
-    environment_machines: EnvironmentMachinesTable;
+    devices: DevicesTable;
+    device_instances: DeviceInstancesTable;
+    device_defaults: DeviceDefaultsTable;
+    device_machines: DeviceMachinesTable;
     background_tasks: BackgroundTasksTable;
     skills: SkillsTable;
     skill_versions: SkillVersionsTable;