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

package/dist/catalog/plugin-upgrade.js

@@ -20,6 +20,7 @@ import { ExtensionAdminOps } from "../extensions/admin-ops.js";
 import { ExtensionBlobs } from "../extensions/blobs.js";
 import { permissionSetOfPackage, readExtensionPackage } from "../extensions/package.js";
 import { blockingKeys, diffPermissions } from "../extensions/permission-set.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
 import { SuperAdminLock } from "../identity/super-admin.js";
@@ -143,11 +144,14 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
     connectors;
     sync;
     log;
+    guides;
     constructor(kdb, txHost, adminLock, itemLock, orgLock, locks, storage, registry, ops, 
     /** Reads the target's extension package (its permissions, for `needsApproval`). */
     blobs, config, platform, 
     /** Template dependencies (the deployed connector kinds). */
-    installer, connectors, sync, log) {
+    installer, connectors, sync, log, 
+    /** The connector template guides an update changes (the preview's `guideChanges`). */
+    guides) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.adminLock = adminLock;
@@ -164,13 +168,21 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
         this.connectors = connectors;
         this.sync = sync;
         this.log = log;
+        this.guides = guides;
     }
     get db() {
         return this.kdb.db;
     }
     /** The update preview (see the class comment); writes nothing. */
     async preview(itemId, version) {
-        return previewOf(await this.diff(itemId, version));
+        return this.withGuideChanges(await this.diff(itemId, version));
+    }
+    /** The preview of a diff with the template guides it changes. */
+    async withGuideChanges(d) {
+        return {
+            ...previewOf(d),
+            guideChanges: await this.guides.templateGuideChanges(d.itemId, d.from, d.to),
+        };
     }
     /**
      * The update preview of a new version of an org's own plugin (ruling P3-12): the item must be
@@ -186,7 +198,7 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
         if (staged !== undefined && staged.version !== version) {
             throw new Error(`internal: previewForOwner got the staged target of version ${staged.version} for version ${version}`);
         }
-        const preview = previewOf(await this.diff(itemId, version, {
+        const preview = await this.withGuideChanges(await this.diff(itemId, version, {
             owner: { orgId },
             ...(staged !== undefined && { target: staged }),
         }));
@@ -1502,10 +1514,11 @@ PlatformPluginUpdater = __decorate([
     __param(12, Inject(PluginInstaller)),
     __param(13, Inject(ConnectorsService)),
     __param(14, Inject(PluginScopeSync)),
-    __param(15, Inject(KERNEL_LOGGER))
+    __param(15, Inject(KERNEL_LOGGER)),
+    __param(16, Inject(PluginGuides))
 ], PlatformPluginUpdater);
 export { PlatformPluginUpdater };
-/** The preview of a diff. */
+/** The preview of a diff (without `guideChanges`, which reads PG). */
 function previewOf(d) {
     return {
         itemId: d.itemId,

package/dist/channels/connections.controller.d.ts

@@ -13,7 +13,7 @@ import { ChannelConnections, type ChannelConnectionView } from "./connections.se
  * the URL of its plugin's icon on the org's catalog route (null without one, or when the org may
  * not see the plugin's catalog item; maintainer decision 2026-11-08), and its plugin's setup guide
  * with the drift since the connection was set up (`setupGuide`, `guideDrift`; spec
- * 2026-11-08-plugin-setup-guides-design.md §6).
+ * 2026-11-09-setup-guides-v2-design.md §11).
  */
 export type ChannelConnectionPage = ChannelConnectionView & ConnectionGuideState & {
     pluginDisplayName: LocalizedName | null;

package/dist/channels/connections.controller.js

@@ -93,7 +93,7 @@ let ChannelConnectionsController = class ChannelConnectionsController {
      */
     async ackGuide(principal, org, id, body) {
         const p = requireUser(principal);
-        const view = await this.channels.ackGuide(org.orgId, id, body.hash, p.account.id, patTokenId(p));
+        const view = await this.channels.ackGuide({ orgId: org.orgId, role: org.role }, id, body.hash, p.account.id, patTokenId(p));
         return { channel: await this.withPlugin(org, view) };
     }
     async remove(principal, org, id) {

package/dist/channels/connections.service.d.ts

@@ -12,6 +12,7 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { type KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
+import type { OrgRole } from "../orgs/roles.js";
 import { ChannelJobs } from "./jobs.js";
 import type { ChannelLocale } from "./phrases.js";
 /** 连接配置里全部密钥字段存成一行：`{ 点路径: 值 }` 的 JSON。 */
@@ -112,7 +113,7 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
     private readonly log;
     readonly txHost: TransactionHost;
-    /** The setup guide acks (spec 2026-11-08-plugin-setup-guides-design.md §6). */
+    /** The setup guide acks (spec 2026-11-09-setup-guides-v2-design.md §11). */
     private readonly guides;
     private readonly unsubscribe;
     /** `<plugin>@<version>` whose invalid connection hints were warned about (a log dedupe only). */
@@ -126,7 +127,7 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     config: Pick<KernelConfigService, "get">, events: Pick<KernelEvents, "on">, 
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
     log: Pick<KernelLogger, "warn" | "addOrgSecrets">, txHost: TransactionHost, 
-    /** The setup guide acks (spec 2026-11-08-plugin-setup-guides-design.md §6). */
+    /** The setup guide acks (spec 2026-11-09-setup-guides-v2-design.md §11). */
     guides: Pick<PluginGuides, "currentAck" | "ackDrifted">);
     /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
     onApplicationShutdown(): void;
@@ -186,11 +187,15 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     private updateIn;
     /**
      * 「我已更新应用」: records the plugin's current channel-connection guide for the connection's
-     * mode as the one it is set up with. `hash` is the template hash of the guide the person was
+     * mode as the one it is set up with. `hash` is the drift hash of the guide the person was
      * shown; when the plugin has moved on since, 409 `channel.guide_changed` (show the new guide
-     * first). A plugin without a guide -> 404 `catalog.guide_not_found`.
+     * first). A plugin without a guide, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
      */
-    ackGuide(orgId: string, id: string, hash: string, actorAccountId: string, actorTokenId?: string): Promise<ChannelConnectionView>;
+    ackGuide(org: {
+        orgId: string;
+        role: OrgRole;
+    }, id: string, hash: string, actorAccountId: string, actorTokenId?: string): Promise<ChannelConnectionView>;
     /** The row of {@link ackGuide}, in its own transaction. */
     private ackIn;
     /** 删除（软删除，同一事务删掉密钥）；持有长连接的副本收到广播后断开。 */
@@ -211,6 +216,18 @@ export declare class ChannelConnections implements OnApplicationShutdown {
      * 持有长连接的副本立即断开（扫描复核只是兜底）。只广播，失败只记日志。
      */
     notifyOrgChanged(orgId: string, plugin?: string): Promise<void>;
+    /**
+     * For setup checks (setup guides v2 §10.4): the input revision of a live connection of the org
+     * on `plugin`: the `updated_at` of its row and of its secrets row (ISO), never a value. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`.
+     */
+    checkRevision(orgId: string, plugin: string, id: string): Promise<string>;
+    /**
+     * For setup checks (setup guides v2 §10.8): the stored secret values of a live connection of the
+     * org on `plugin` (every secret field, decrypted), what a check's result is redacted by. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`. Never echo them.
+     */
+    checkSecrets(orgId: string, plugin: string, id: string): Promise<string[]>;
     /**
      * The extension implementation and full config a connection needs to run (decrypted secrets
      * included, validated against `connectionSchema`). Connection missing / deleted ->

package/dist/channels/connections.service.js

@@ -11,7 +11,7 @@ import { randomUUID } from "node:crypto";
 import { CHANNEL_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
-import { configFields, getPath, secretValues } from "../config/fields.js";
+import { configFields, getPath, secretScalars, secretValues } from "../config/fields.js";
 import { queryEnabledPlugins } from "../ctx/create-ctx.js";
 import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
@@ -135,7 +135,7 @@ let ChannelConnections = class ChannelConnections {
     config, events, 
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
     log, txHost, 
-    /** The setup guide acks (spec 2026-11-08-plugin-setup-guides-design.md §6). */
+    /** The setup guide acks (spec 2026-11-09-setup-guides-v2-design.md §11). */
     guides) {
         this.db = db;
         this.orgLock = orgLock;
@@ -336,7 +336,9 @@ let ChannelConnections = class ChannelConnections {
         const id = randomUUID();
         const { plain, secrets } = split(schema, full);
         // the guide the 新建渠道 page showed: the plugin's current one, for the default mode
-        const guideAck = await this.guides.currentAck(input.plugin, "long_connection");
+        const guideAck = await this.guides.currentAck(input.plugin, "channel-connection", {
+            mode: "long_connection",
+        });
         const row = await this.insertIn({
             orgId,
             id,
@@ -440,11 +442,13 @@ let ChannelConnections = class ChannelConnections {
         // A mode switch sets the platform app up for the new mode: the guide of that mode is the one
         // on the page. Only an ack without drift moves on: a drifted one stays until the person
         // confirms through guide-ack, so switching modes never clears the update notice (spec
-        // 2026-11-08-plugin-setup-guides-design.md §6)
+        // 2026-11-09-setup-guides-v2-design.md §11)
         const guideAck = modeChanged &&
             patch.inboundMode !== undefined &&
-            !(await this.guides.ackDrifted(current.plugin, current.guide_ack ?? null))
-            ? await this.guides.currentAck(current.plugin, patch.inboundMode)
+            !(await this.guides.ackDrifted(current.plugin, "channel-connection", current.guide_ack ?? null))
+            ? await this.guides.currentAck(current.plugin, "channel-connection", {
+                mode: patch.inboundMode,
+            })
             : undefined;
         const row = await this.updateIn({
             orgId,
@@ -533,15 +537,21 @@ let ChannelConnections = class ChannelConnections {
     }
     /**
      * 「我已更新应用」: records the plugin's current channel-connection guide for the connection's
-     * mode as the one it is set up with. `hash` is the template hash of the guide the person was
+     * mode as the one it is set up with. `hash` is the drift hash of the guide the person was
      * shown; when the plugin has moved on since, 409 `channel.guide_changed` (show the new guide
-     * first). A plugin without a guide -> 404 `catalog.guide_not_found`.
+     * first). A plugin without a guide, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
      */
-    async ackGuide(orgId, id, hash, actorAccountId, actorTokenId) {
+    async ackGuide(org, id, hash, actorAccountId, actorTokenId) {
+        const { orgId } = org;
         const current = await this.live(orgId).where("id", "=", id).executeTakeFirst();
         if (!current)
             throw notFound();
-        const ack = await this.guides.currentAck(current.plugin, current.inbound_mode);
+        // the guide read's visibility: an item the org's catalog does not show has no guide to ack
+        const ack = await this.guides.currentAck(current.plugin, "channel-connection", {
+            mode: current.inbound_mode,
+            org,
+        });
         if (ack === null) {
             throw new ApiError("catalog.guide_not_found", "The plugin has no channel setup guide");
         }
@@ -671,6 +681,42 @@ let ChannelConnections = class ChannelConnections {
         for (const r of rows)
             await this.changed(r.id, true);
     }
+    /**
+     * For setup checks (setup guides v2 §10.4): the input revision of a live connection of the org
+     * on `plugin`: the `updated_at` of its row and of its secrets row (ISO), never a value. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`.
+     */
+    async checkRevision(orgId, plugin, id) {
+        const row = await this.live(orgId)
+            .where("id", "=", id)
+            .where("plugin", "=", plugin)
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        const secretRow = await this.db
+            .selectFrom("secrets")
+            .select("updated_at")
+            .where("namespace", "=", SECRETS_NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where("key", "=", connectionSecretKey(id))
+            .executeTakeFirst();
+        const iso = (d) => new Date(d).toISOString();
+        return `${iso(row.updated_at)}|${secretRow ? iso(secretRow.updated_at) : "-"}`;
+    }
+    /**
+     * For setup checks (setup guides v2 §10.8): the stored secret values of a live connection of the
+     * org on `plugin` (every secret field, decrypted), what a check's result is redacted by. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`. Never echo them.
+     */
+    async checkSecrets(orgId, plugin, id) {
+        const row = await this.live(orgId)
+            .where("id", "=", id)
+            .where("plugin", "=", plugin)
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        return secretScalars(Object.values(await this.readSecrets(orgId, id)));
+    }
     /**
      * The extension implementation and full config a connection needs to run (decrypted secrets
      * included, validated against `connectionSchema`). Connection missing / deleted ->

package/dist/channels/webhook.d.ts

@@ -1,4 +1,6 @@
 import type { ChannelWebhookRequest, ChannelWebhookResponse, Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { LockService } from "../infra/lock/lock.service.js";
 import { ChannelConnections } from "./connections.service.js";
 import { ChannelInbound } from "./inbound.js";
 /**
@@ -19,6 +21,10 @@ export interface ChannelWebhookTimings {
 export declare const CHANNEL_WEBHOOK_TIMINGS: unique symbol;
 /** Most connections whose runtime is cached in one process. */
 export declare const WEBHOOK_RUNTIME_CACHE_MAX = 1000;
+/** How long a connection's last accepted webhook is remembered (`capybara:webhook-received`). */
+export declare const WEBHOOK_SEEN_TTL_SECONDS: number;
+/** When the gateway last accepted a verified webhook for the connection (ISO time, TTL 7 days). */
+export declare const webhookSeenKey: (connectionId: string) => string;
 /**
  * Headers every webhook response carries; a plugin cannot override them (the body is never meant to
  * be rendered or sniffed by a browser).
@@ -49,6 +55,10 @@ export declare const WEBHOOK_SECURITY_HEADERS: Readonly<Record<string, string>>;
  *   for it (`extensionHost.drainSeconds`) before `dispose`; past that the call is aborted → 503
  *   `channel.webhook_retry`.
  * Every response carries {@link WEBHOOK_SECURITY_HEADERS}.
+ * - An accepted `events` result (every event handed to `onEvent`) sets the marker
+ *   {@link webhookSeenKey} (the setup check `capybara:webhook-received`), at most once a minute per
+ *   connection (`LockService.lease`, `SET NX` with a 60 s TTL, on a minute key), in Redis with a TTL, never in PG; a Redis error
+ *   never fails the request.
  *
  * The decrypted runtime (plugin implementation + config) is cached per connection for a few seconds
  * (bounded, process local), so unauthenticated requests stay cheap before the signature check. It is
@@ -60,6 +70,9 @@ export declare class ChannelWebhooks {
     private readonly connections;
     private readonly inbound;
     private readonly log;
+    /** The minute gate of the seen marker (`SET NX` with a TTL). */
+    private readonly locks;
+    private readonly redis;
     private readonly runtimes;
     /** Bumped by {@link invalidateAll}: a fetch started before the bump is not stored. */
     private generation;
@@ -67,12 +80,19 @@ export declare class ChannelWebhooks {
     private readonly handleTimeoutMs;
     /** How long a connection's runtime is reused; 0 disables the cache. */
     private readonly runtimeCacheMs;
-    constructor(connections: Pick<ChannelConnections, "row" | "runtime">, inbound: Pick<ChannelInbound, "onEvent">, log: Pick<Logger, "warn">, timings?: Partial<ChannelWebhookTimings>);
+    constructor(connections: Pick<ChannelConnections, "row" | "runtime">, inbound: Pick<ChannelInbound, "onEvent">, log: Pick<Logger, "warn">, 
+    /** The minute gate of the seen marker (`SET NX` with a TTL). */
+    locks: Pick<LockService, "lease">, redis: Pick<Redis, "set">, timings?: Partial<ChannelWebhookTimings>);
     /** Drops the cached runtime of one connection (on `channel.changed`). */
     invalidate(connectionId: string): void;
     /** Drops every cached runtime (a plugin was replaced, revoked or reloaded). */
     invalidateAll(): void;
     handle(connectionId: string, request: ChannelWebhookRequest, signal: AbortSignal): Promise<ChannelWebhookResponse>;
+    /**
+     * Records that a verified webhook arrived for the connection: the minute gate first (`NX`), then
+     * the marker, both with a TTL. Failures are logged and swallowed (the platform got its ack).
+     */
+    private markSeen;
     private runtime;
     private respond;
     private respondBefore;

package/dist/channels/webhook.js

@@ -10,7 +10,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Injectable, Optional } from "@nestjs/common";
 import { ApiError, errorBody } from "../errors.js";
 import { ExtensionUnloadedError } from "../extensions/inflight.js";
-import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
 import { ChannelConnections } from "./connections.service.js";
 import { ChannelInbound } from "./inbound.js";
 /**
@@ -24,6 +25,12 @@ export const WEBHOOK_RUNTIME_CACHE_MS = 5_000;
 export const CHANNEL_WEBHOOK_TIMINGS = Symbol("CHANNEL_WEBHOOK_TIMINGS");
 /** Most connections whose runtime is cached in one process. */
 export const WEBHOOK_RUNTIME_CACHE_MAX = 1_000;
+/** How long a connection's last accepted webhook is remembered (`capybara:webhook-received`). */
+export const WEBHOOK_SEEN_TTL_SECONDS = 7 * 24 * 3600;
+/** When the gateway last accepted a verified webhook for the connection (ISO time, TTL 7 days). */
+export const webhookSeenKey = (connectionId) => `capk:channel-webhook-seen:${connectionId}`;
+/** The minute gate of {@link webhookSeenKey}: the marker is written at most once a minute. */
+const webhookSeenMinuteKey = (connectionId, minute) => `capk:channel-webhook-seen-min:${connectionId}:${minute}`;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * Headers every webhook response carries; a plugin cannot override them (the body is never meant to
@@ -99,6 +106,10 @@ function raceAbort(p, signal) {
  *   for it (`extensionHost.drainSeconds`) before `dispose`; past that the call is aborted → 503
  *   `channel.webhook_retry`.
  * Every response carries {@link WEBHOOK_SECURITY_HEADERS}.
+ * - An accepted `events` result (every event handed to `onEvent`) sets the marker
+ *   {@link webhookSeenKey} (the setup check `capybara:webhook-received`), at most once a minute per
+ *   connection (`LockService.lease`, `SET NX` with a 60 s TTL, on a minute key), in Redis with a TTL, never in PG; a Redis error
+ *   never fails the request.
  *
  * The decrypted runtime (plugin implementation + config) is cached per connection for a few seconds
  * (bounded, process local), so unauthenticated requests stay cheap before the signature check. It is
@@ -110,6 +121,8 @@ let ChannelWebhooks = class ChannelWebhooks {
     connections;
     inbound;
     log;
+    locks;
+    redis;
     runtimes = new Map();
     /** Bumped by {@link invalidateAll}: a fetch started before the bump is not stored. */
     generation = 0;
@@ -117,10 +130,14 @@ let ChannelWebhooks = class ChannelWebhooks {
     handleTimeoutMs;
     /** How long a connection's runtime is reused; 0 disables the cache. */
     runtimeCacheMs;
-    constructor(connections, inbound, log, timings = {}) {
+    constructor(connections, inbound, log, 
+    /** The minute gate of the seen marker (`SET NX` with a TTL). */
+    locks, redis, timings = {}) {
         this.connections = connections;
         this.inbound = inbound;
         this.log = log;
+        this.locks = locks;
+        this.redis = redis;
         this.handleTimeoutMs = timings.handleTimeoutMs ?? WEBHOOK_HANDLE_TIMEOUT_MS;
         this.runtimeCacheMs = timings.runtimeCacheMs ?? WEBHOOK_RUNTIME_CACHE_MS;
     }
@@ -136,6 +153,21 @@ let ChannelWebhooks = class ChannelWebhooks {
     async handle(connectionId, request, signal) {
         return secure(await this.respond(connectionId, request, signal));
     }
+    /**
+     * Records that a verified webhook arrived for the connection: the minute gate first (`NX`), then
+     * the marker, both with a TTL. Failures are logged and swallowed (the platform got its ack).
+     */
+    async markSeen(connectionId) {
+        try {
+            const minute = Math.floor(Date.now() / 60_000);
+            if (!(await this.locks.lease(webhookSeenMinuteKey(connectionId, minute), "1", 60_000)))
+                return;
+            await this.redis.set(webhookSeenKey(connectionId), new Date().toISOString(), "EX", WEBHOOK_SEEN_TTL_SECONDS);
+        }
+        catch (err) {
+            this.log.warn("cannot record the channel webhook marker", { connectionId, err });
+        }
+    }
     async runtime(connectionId, deadline) {
         const ttl = this.runtimeCacheMs;
         const now = Date.now();
@@ -255,6 +287,7 @@ let ChannelWebhooks = class ChannelWebhooks {
                         return retryLater();
                     }
                 }
+                await this.markSeen(connectionId);
                 return sanitize(result.ack);
             }
         }
@@ -267,8 +300,10 @@ ChannelWebhooks = __decorate([
     __param(0, Inject(ChannelConnections)),
     __param(1, Inject(ChannelInbound)),
     __param(2, Inject(KERNEL_LOGGER)),
-    __param(3, Optional()),
-    __param(3, Inject(CHANNEL_WEBHOOK_TIMINGS))
+    __param(3, Inject(LockService)),
+    __param(4, Inject(REDIS)),
+    __param(5, Optional()),
+    __param(5, Inject(CHANNEL_WEBHOOK_TIMINGS))
 ], ChannelWebhooks);
 export { ChannelWebhooks };
 /** Generic codes for the statuses a plugin may reject with (same as the HTTP error filter's). */

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

@@ -1,4 +1,4 @@
-import { type ExtensionContext, type ExtensionManifest, type ExtensionPointRef, type Logger, resolveUiSlots, 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 完成）的提供方，按加载顺序；按完整引用（含主版本）精确匹配。 */
@@ -105,7 +114,11 @@ export type KernelExtensionContext = ExtensionContext & {
     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>;
@@ -128,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, resolveUiSlots, 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";
@@ -182,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;
@@ -261,6 +262,8 @@ 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 uiResolution = resolveUiSlots(manifest.ui);
     const uiSlots = new Map(uiResolution.resolved.map((r) => [r.contribution.id, r.slot]));
@@ -445,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) {
@@ -585,6 +631,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
         uiResolution,
         uiViews: uiReg.views,
         uiActions: uiReg.actions,
+        setupChecks,
         ledger,
         async beginDispose(deadline) {
             drainDeadline = deadline;

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

@@ -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;

package/dist/errors.d.ts

@@ -159,6 +159,8 @@ export declare const ERROR_CODES: {
     readonly "catalog.not_deployed": 409;
     readonly "catalog.icon_not_found": 404;
     readonly "catalog.guide_not_found": 404;
+    /** The check is not in the setup guide rendered for that mode and audience (setup guides v2 §10.3). */
+    readonly "catalog.check_not_found": 404;
     readonly "marketplace.not_found": 404;
     readonly "marketplace.entry_not_found": 404;
     readonly "marketplace.fetch_failed": 502;
@@ -246,6 +248,8 @@ export declare const ERROR_CODES: {
     readonly "background_task.output_unavailable": 409;
     readonly "connector.not_found": 404;
     readonly "connector.slug_taken": 409;
+    /** The connector template's setup guide moved on since the person was shown it (guide-ack). */
+    readonly "connector.guide_changed": 409;
     readonly "connector.kind_unavailable": 409;
     readonly "connector.connect_failed": 502;
     readonly "connector.tool_not_found": 404;

package/dist/errors.js

@@ -159,6 +159,8 @@ export const ERROR_CODES = {
     "catalog.not_deployed": 409,
     "catalog.icon_not_found": 404,
     "catalog.guide_not_found": 404,
+    /** The check is not in the setup guide rendered for that mode and audience (setup guides v2 §10.3). */
+    "catalog.check_not_found": 404,
     "marketplace.not_found": 404,
     "marketplace.entry_not_found": 404,
     "marketplace.fetch_failed": 502,
@@ -246,6 +248,8 @@ export const ERROR_CODES = {
     "background_task.output_unavailable": 409,
     "connector.not_found": 404,
     "connector.slug_taken": 409,
+    /** The connector template's setup guide moved on since the person was shown it (guide-ack). */
+    "connector.guide_changed": 409,
     "connector.kind_unavailable": 409,
     "connector.connect_failed": 502,
     "connector.tool_not_found": 404,