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

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/inbound.d.ts

@@ -1,7 +1,7 @@
 import type { ChannelCard, InboundEvent, InboundSender, Logger } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { ConversationsService } from "../conversations/conversations.service.js";
-import { EnvironmentsService } from "../environments/environments.service.js";
+import { DevicesService } from "../devices/devices.service.js";
 import { IdentityBinding } from "../identity/binding.js";
 import { ExternalIdentities } from "../identity/external.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -63,7 +63,7 @@ export declare class ChannelInbound {
     /** The channel queue: inbound jobs (`onEvent` only dedupes and enqueues) and deliveries. */
     private readonly jobs;
     private readonly guests;
-    private readonly environments;
+    private readonly devices;
     private readonly log;
     private readonly actions;
     constructor(kdb: KernelDb, redis: Pick<Redis, "set">, 
@@ -74,7 +74,7 @@ export declare class ChannelInbound {
     /** The channel queue: inbound jobs (`onEvent` only dedupes and enqueues) and deliveries. */
     jobs: Pick<ChannelJobs, "enqueue" | "enqueueInbound">, 
     /** 卡片操作：审批决定与提问回答（授权由这两个服务按点击者映射到的账号判定）。 */
-    approvals: Pick<ApprovalsService, "decide">, questions: Pick<QuestionsService, "answer">, guests: Pick<AnonymousGuests, "ensure">, environments: Pick<EnvironmentsService, "list" | "imDefault" | "setImDefault">, log: Pick<Logger, "warn" | "info">);
+    approvals: Pick<ApprovalsService, "decide">, questions: Pick<QuestionsService, "answer">, guests: Pick<AnonymousGuests, "ensure">, devices: Pick<DevicesService, "list" | "imDefault" | "setImDefault">, log: Pick<Logger, "warn" | "info">);
     /**
      * 插件 `onEvent`：去重并入队后返回（见类注释）。返回后插件才向平台确认；抛错时插件不确认。
      */
@@ -95,13 +95,13 @@ export declare class ChannelInbound {
     handle(connectionId: string, e: InboundEvent): Promise<void>;
     private message;
     /**
-     * Direct-message `/env` (environments spec §4.2 item 8): lists the person's usable environments,
+     * Direct-message `/device` (environments spec §4.2 item 8): lists the person's usable devices,
      * or with a name sets the IM default their next new conversation is bound to. The name matches
-     * case-insensitively against each label (`environmentLabel`: a former default demoted by a
-     * provider switch answers to e.g. "Personal (Docker sandbox)"); the default environment also
-     * answers to 个人环境 / Personal.
+     * case-insensitively against each label (`deviceLabel`: a former default demoted by a
+     * provider switch answers to e.g. "Personal (Docker sandbox)"); the default device also
+     * answers to 个人设备 / Personal.
      */
-    private envCommand;
+    private deviceCommand;
     /**
      * Posts the person's message: `/name args` as a skill invocation when the kernel accepts it, else
      * as typed (phase D spec §9). A retry of the job finds the first write by `clientMessageId`

package/dist/channels/inbound.js

@@ -11,8 +11,8 @@ import { randomUUID } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
 import { ConversationsService } from "../conversations/conversations.service.js";
 import { imSenderContext, recipientLocale, } from "../conversations/message-context.js";
-import { EnvironmentsService } from "../environments/environments.service.js";
-import { DEFAULT_ENVIRONMENT_ALIASES, environmentLabel } from "../environments/label.js";
+import { DevicesService } from "../devices/devices.service.js";
+import { DEFAULT_DEVICE_ALIASES, deviceLabel } from "../devices/label.js";
 import { ApiError } from "../errors.js";
 import { IdentityBinding } from "../identity/binding.js";
 import { ExternalIdentities } from "../identity/external.js";
@@ -75,7 +75,7 @@ let ChannelInbound = class ChannelInbound {
     directorySync;
     jobs;
     guests;
-    environments;
+    devices;
     log;
     actions;
     constructor(kdb, redis, 
@@ -86,7 +86,7 @@ let ChannelInbound = class ChannelInbound {
     /** The channel queue: inbound jobs (`onEvent` only dedupes and enqueues) and deliveries. */
     jobs, 
     /** 卡片操作：审批决定与提问回答（授权由这两个服务按点击者映射到的账号判定）。 */
-    approvals, questions, guests, environments, log) {
+    approvals, questions, guests, devices, log) {
         this.kdb = kdb;
         this.redis = redis;
         this.locks = locks;
@@ -97,7 +97,7 @@ let ChannelInbound = class ChannelInbound {
         this.directorySync = directorySync;
         this.jobs = jobs;
         this.guests = guests;
-        this.environments = environments;
+        this.devices = devices;
         this.log = log;
         this.actions = new ChannelCardActions({
             get db() {
@@ -216,16 +216,16 @@ let ChannelInbound = class ChannelInbound {
             await reply("newConversation");
             return;
         }
-        const envCommand = !isGroup && threadAccount !== null ? parseEnvCommand(e.text) : null;
-        if (envCommand !== null) {
-            await this.envCommand(row.orgId, accountId, envCommand.name, locale, replyText);
+        const deviceCommand = !isGroup && threadAccount !== null ? parseDeviceCommand(e.text) : null;
+        if (deviceCommand !== null) {
+            await this.deviceCommand(row.orgId, accountId, deviceCommand.name, locale, replyText);
             return;
         }
         let conversationId = await findThread(db, k);
         if (conversationId === undefined) {
             let created;
             try {
-                // bound to the person's IM default environment, else their default (environments spec
+                // bound to the person's IM default device, else their default (environments spec
                 // §4.2 item 8); an anonymous sender's stays unbound (no sandbox)
                 created = (await this.conversations.create(row.orgId, accountId, row.agentId, { im: true }))
                     .id;
@@ -294,49 +294,49 @@ let ChannelInbound = class ChannelInbound {
         await this.jobs.enqueue(conversationId);
     }
     /**
-     * Direct-message `/env` (environments spec §4.2 item 8): lists the person's usable environments,
+     * Direct-message `/device` (environments spec §4.2 item 8): lists the person's usable devices,
      * or with a name sets the IM default their next new conversation is bound to. The name matches
-     * case-insensitively against each label (`environmentLabel`: a former default demoted by a
-     * provider switch answers to e.g. "Personal (Docker sandbox)"); the default environment also
-     * answers to 个人环境 / Personal.
+     * case-insensitively against each label (`deviceLabel`: a former default demoted by a
+     * provider switch answers to e.g. "Personal (Docker sandbox)"); the default device also
+     * answers to 个人设备 / Personal.
      */
-    async envCommand(orgId, accountId, name, locale, replyText) {
-        const { items, defaultId } = await this.environments.list(orgId, accountId);
+    async deviceCommand(orgId, accountId, name, locale, replyText) {
+        const { items, defaultId } = await this.devices.list(orgId, accountId);
         const usable = items.filter((v) => v.available);
-        const labelOf = (v) => environmentLabel(v, locale);
-        const current = (await this.environments.imDefault(orgId, accountId)) ?? defaultId;
+        const labelOf = (v) => deviceLabel(v, locale);
+        const current = (await this.devices.imDefault(orgId, accountId)) ?? defaultId;
         const list = usable
-            .map((v) => `- ${labelOf(v)}${v.id === current ? phrase("envCurrent", locale) : ""}`)
+            .map((v) => `- ${labelOf(v)}${v.id === current ? phrase("deviceCurrent", locale) : ""}`)
             .join("\n");
         const fill = (key, vars) => phrase(key, locale).replace(/\{(\w+)\}/g, (m, k) => vars[k] ?? m);
         if (usable.length === 0)
-            return replyText(phrase("envNone", locale));
+            return replyText(phrase("deviceNone", locale));
         if (name === null)
-            return replyText(fill("envList", { list }));
+            return replyText(fill("deviceList", { list }));
         const wanted = name.toLowerCase();
         const is = (v) => labelOf(v).toLowerCase() === wanted;
         // a name the person gave wins over a generated label, and both over the default's aliases
         const hit = usable.find((v) => v.name !== null && is(v)) ??
             usable.find(is) ??
-            usable.find((v) => v.isDefault && DEFAULT_ENVIRONMENT_ALIASES.includes(wanted));
+            usable.find((v) => v.isDefault && DEFAULT_DEVICE_ALIASES.includes(wanted));
         if (hit === undefined) {
             const unavailable = items.find((v) => !v.available && is(v));
             if (unavailable !== undefined) {
-                return replyText(fill("envUnavailable", { name: labelOf(unavailable), list }));
+                return replyText(fill("deviceUnavailable", { name: labelOf(unavailable), list }));
             }
-            return replyText(fill("envUnknown", { name, list }));
+            return replyText(fill("deviceUnknown", { name, list }));
         }
         try {
-            await this.environments.setImDefault(orgId, accountId, hit.id);
+            await this.devices.setImDefault(orgId, accountId, hit.id);
         }
         catch (err) {
             // deleted or made unusable since the list was read
-            if (err instanceof ApiError && err.code.startsWith("environment.")) {
-                return replyText(fill("envUnknown", { name, list }));
+            if (err instanceof ApiError && err.code.startsWith("device.")) {
+                return replyText(fill("deviceUnknown", { name, list }));
             }
             throw err;
         }
-        return replyText(fill("envSwitched", { name: labelOf(hit) }));
+        return replyText(fill("deviceSwitched", { name: labelOf(hit) }));
     }
     /**
      * Posts the person's message: `/name args` as a skill invocation when the kernel accepts it, else
@@ -464,13 +464,13 @@ ChannelInbound = __decorate([
     __param(9, Inject(ApprovalsService)),
     __param(10, Inject(QuestionsService)),
     __param(11, Inject(AnonymousGuests)),
-    __param(12, Inject(EnvironmentsService)),
+    __param(12, Inject(DevicesService)),
     __param(13, Inject(KERNEL_LOGGER))
 ], ChannelInbound);
 export { ChannelInbound };
-/** `/env` or `/env <name>` (the exact command word, case-insensitive); anything else is null. */
-function parseEnvCommand(text) {
-    const m = /^\/env(?:\s+([\s\S]*))?$/i.exec(text.trim());
+/** `/device` or `/device <name>` (the exact command word, case-insensitive); anything else is null. */
+function parseDeviceCommand(text) {
+    const m = /^\/device(?:\s+([\s\S]*))?$/i.exec(text.trim());
     if (m === null)
         return null;
     const name = m[1]?.trim();

package/dist/channels/phrases.d.ts

@@ -11,33 +11,33 @@ export declare const CHANNEL_PHRASES: {
         readonly zh: "已开始新对话";
         readonly en: "Started a new conversation.";
     };
-    /** 私聊 `/env`：列出可用环境（`{list}` 每行一个，当前的带标记）。 */
-    readonly envList: {
-        readonly zh: "你的环境：\n{list}\n发送 /env <名称> 选择下一个新对话使用的环境。";
-        readonly en: "Your environments:\n{list}\nSend /env <name> to choose the one your next new conversation uses.";
-    };
-    /** 私聊 `/env <名称>` 之后（`{name}` 是环境名）。 */
-    readonly envSwitched: {
-        readonly zh: "下一个新对话将使用环境「{name}」，发送 /new 开始。";
-        readonly en: "Your next new conversation will use the environment “{name}”; send /new to start one.";
-    };
-    /** 私聊 `/env <名称>` 没有匹配的可用环境（`{list}` 同 envList）。 */
-    readonly envUnknown: {
-        readonly zh: "没有找到名为「{name}」的环境。你的环境：\n{list}";
-        readonly en: "No environment named “{name}”. Your environments:\n{list}";
-    };
-    /** `/env <name>` names an existing environment that is unavailable now (`{list}` as in envList). */
-    readonly envUnavailable: {
-        readonly zh: "环境「{name}」当前不可用（它的文件由未启用的沙箱提供方保存）。你的环境：\n{list}";
-        readonly en: "The environment “{name}” is unavailable: its files are kept by a sandbox provider that is not active. Your environments:\n{list}";
-    };
-    /** 私聊 `/env` 时此人没有可用环境（部署没有云沙箱）。 */
-    readonly envNone: {
-        readonly zh: "你目前没有可用的环境。";
-        readonly en: "You have no usable environments.";
-    };
-    /** 环境列表里当前 IM 默认环境的标记。 */
-    readonly envCurrent: {
+    /** Direct message `/device`: lists the usable devices (`{list}` one per line, the current one marked). */
+    readonly deviceList: {
+        readonly zh: "你的设备：\n{list}\n发送 /device <名称> 选择下一个新对话使用的设备。";
+        readonly en: "Your devices:\n{list}\nSend /device <name> to choose the one your next new conversation uses.";
+    };
+    /** After a direct message `/device <name>` (`{name}` is the device's name). */
+    readonly deviceSwitched: {
+        readonly zh: "下一个新对话将使用设备「{name}」，发送 /new 开始。";
+        readonly en: "Your next new conversation will use the device “{name}”; send /new to start one.";
+    };
+    /** `/device <name>` matches no usable device (`{list}` as in deviceList). */
+    readonly deviceUnknown: {
+        readonly zh: "没有找到名为「{name}」的设备。你的设备：\n{list}";
+        readonly en: "No device named “{name}”. Your devices:\n{list}";
+    };
+    /** `/device <name>` names an existing device that is unavailable now (`{list}` as in deviceList). */
+    readonly deviceUnavailable: {
+        readonly zh: "设备「{name}」当前不可用（它的文件由未启用的沙箱提供方保存）。你的设备：\n{list}";
+        readonly en: "The device “{name}” is unavailable: its files are kept by a sandbox provider that is not active. Your devices:\n{list}";
+    };
+    /** Direct message `/device` when the person has no usable device (no cloud sandbox in the deployment). */
+    readonly deviceNone: {
+        readonly zh: "你目前没有可用的设备。";
+        readonly en: "You have no usable devices.";
+    };
+    /** The mark of the current IM default device in the device list. */
+    readonly deviceCurrent: {
         readonly zh: "（当前）";
         readonly en: " (current)";
     };

package/dist/channels/phrases.js

@@ -6,33 +6,33 @@
 export const CHANNEL_PHRASES = {
     /** 私聊 `/new` 之后。 */
     newConversation: { zh: "已开始新对话", en: "Started a new conversation." },
-    /** 私聊 `/env`：列出可用环境（`{list}` 每行一个，当前的带标记）。 */
-    envList: {
-        zh: "你的环境：\n{list}\n发送 /env <名称> 选择下一个新对话使用的环境。",
-        en: "Your environments:\n{list}\nSend /env <name> to choose the one your next new conversation uses.",
-    },
-    /** 私聊 `/env <名称>` 之后（`{name}` 是环境名）。 */
-    envSwitched: {
-        zh: "下一个新对话将使用环境「{name}」，发送 /new 开始。",
-        en: "Your next new conversation will use the environment \u201c{name}\u201d; send /new to start one.",
-    },
-    /** 私聊 `/env <名称>` 没有匹配的可用环境（`{list}` 同 envList）。 */
-    envUnknown: {
-        zh: "没有找到名为「{name}」的环境。你的环境：\n{list}",
-        en: "No environment named \u201c{name}\u201d. Your environments:\n{list}",
-    },
-    /** `/env <name>` names an existing environment that is unavailable now (`{list}` as in envList). */
-    envUnavailable: {
-        zh: "环境「{name}」当前不可用（它的文件由未启用的沙箱提供方保存）。你的环境：\n{list}",
-        en: "The environment \u201c{name}\u201d is unavailable: its files are kept by a sandbox provider that is not active. Your environments:\n{list}",
-    },
-    /** 私聊 `/env` 时此人没有可用环境（部署没有云沙箱）。 */
-    envNone: {
-        zh: "你目前没有可用的环境。",
-        en: "You have no usable environments.",
-    },
-    /** 环境列表里当前 IM 默认环境的标记。 */
-    envCurrent: { zh: "（当前）", en: " (current)" },
+    /** Direct message `/device`: lists the usable devices (`{list}` one per line, the current one marked). */
+    deviceList: {
+        zh: "你的设备：\n{list}\n发送 /device <名称> 选择下一个新对话使用的设备。",
+        en: "Your devices:\n{list}\nSend /device <name> to choose the one your next new conversation uses.",
+    },
+    /** After a direct message `/device <name>` (`{name}` is the device's name). */
+    deviceSwitched: {
+        zh: "下一个新对话将使用设备「{name}」，发送 /new 开始。",
+        en: "Your next new conversation will use the device \u201c{name}\u201d; send /new to start one.",
+    },
+    /** `/device <name>` matches no usable device (`{list}` as in deviceList). */
+    deviceUnknown: {
+        zh: "没有找到名为「{name}」的设备。你的设备：\n{list}",
+        en: "No device named \u201c{name}\u201d. Your devices:\n{list}",
+    },
+    /** `/device <name>` names an existing device that is unavailable now (`{list}` as in deviceList). */
+    deviceUnavailable: {
+        zh: "设备「{name}」当前不可用（它的文件由未启用的沙箱提供方保存）。你的设备：\n{list}",
+        en: "The device \u201c{name}\u201d is unavailable: its files are kept by a sandbox provider that is not active. Your devices:\n{list}",
+    },
+    /** Direct message `/device` when the person has no usable device (no cloud sandbox in the deployment). */
+    deviceNone: {
+        zh: "你目前没有可用的设备。",
+        en: "You have no usable devices.",
+    },
+    /** The mark of the current IM default device in the device list. */
+    deviceCurrent: { zh: "（当前）", en: " (current)" },
     /** 未绑定的人在私聊里发消息：附绑定卡片。 */
     bindPrompt: {
         zh: "请先绑定你的 Capybara 账号，再与我对话。",

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/config/docs.js

@@ -82,7 +82,7 @@ export function renderConfigDocs(schema) {
         "| `CAPYBARA_WEB_OBJECT_STORE_URL` | Object storage on the web origin: the object store's address as web reaches it (e.g. `http://seaweedfs-s3:8333`). When set, web proxies `/<bucket>/**` (and `/<bucket>` itself for POST only) there, so browsers upload attachments (presigned POST) and download attachments and artifacts (presigned GET) through web; set the object-store extension's `publicEndpoint` to the web origin with `forcePathStyle: true`. Only GET, HEAD and POST; the path is forwarded unchanged; cookies and authorization are not forwarded; responses carry `X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox`; uploads are capped at `CAPYBARA_WEB_MAX_PACKAGE_BYTES`. Unset (default): off |",
         "| `CAPYBARA_WEB_OBJECT_STORE_BUCKET` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the bucket, equal to the object-store extension's `bucket` (it is the first path segment web proxies) |",
         "| `CAPYBARA_WEB_OBJECT_STORE_PUBLIC_HOST` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the host of the extension's `publicEndpoint` (a host such as `capybara.example.com`, or that URL). Sent upstream as `Host` instead of the incoming one, because presigned URLs sign the host they were issued for and front proxies rewrite it |",
-        "| `CAPYBARA_WEB_GATEWAY_URL` | Connected machines on the web origin: a `gateway` replica's address as web reaches it (an http(s) URL, e.g. `http://gateway:8080`). WebSocket upgrades on exactly `/device/connect` are forwarded to it (`capybara-device` connects at `<http.publicUrl>/device/connect`). Unset, they go to `CAPYBARA_KERNEL_URL` (the kernel runs every role unless the deployment splits them), so only deployments with separate gateway replicas set it (compose does). A malformed value stops the web tier at startup |",
+        "| `CAPYBARA_WEB_GATEWAY_URL` | Local devices on the web origin: a `gateway` replica's address as web reaches it (an http(s) URL, e.g. `http://gateway:8080`). WebSocket upgrades on exactly `/device/connect` are forwarded to it (`capybara-device` connects at `<http.publicUrl>/device/connect`). Unset, they go to `CAPYBARA_KERNEL_URL` (the kernel runs every role unless the deployment splits them), so only deployments with separate gateway replicas set it (compose does). A malformed value stops the web tier at startup |",
         "| `CAPYBARA_DEV_UI` | When set to `1`, production builds also serve the `/dev/ui` component catalog page (off by default) |",
         "",
     ].join("\n");

package/dist/config/schema.d.ts

@@ -219,9 +219,9 @@ export declare const KernelConfigSchema: z.ZodObject<{
             allowHosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
-    environments: z.ZodPrefault<z.ZodObject<{
+    devices: z.ZodPrefault<z.ZodObject<{
         maxPersonal: z.ZodDefault<z.ZodNumber>;
-        device: z.ZodPrefault<z.ZodObject<{
+        local: z.ZodPrefault<z.ZodObject<{
             reconnectGraceSeconds: z.ZodDefault<z.ZodNumber>;
             leaseTtlMs: z.ZodDefault<z.ZodNumber>;
             authCodeTtlSeconds: z.ZodDefault<z.ZodNumber>;