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

package/dist/channels/connections.service.js

@@ -8,16 +8,18 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
-import { CHANNEL_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { isIP } from "node:net";
+import { CHANNEL_EXTENSION_POINT, missingInboundModeFields, } 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";
 import { toIssues } from "../extensions/config-issues.js";
-import { configToJsonSchema } from "../extensions/config-json-schema.js";
+import { configMessages, describeConfigUiProblems, safeConfigFormSchema, } from "../extensions/config-json-schema.js";
 import { enabledExtensionsByOrg } from "../extensions/enabled.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
@@ -27,11 +29,35 @@ import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { KERNEL_BUS, KERNEL_LOGGER, KEYRING, REDIS } from "../infra/tokens.js";
 import { createRedactor } from "../log.js";
+import { isForbiddenAddress, isLoopbackHost, normalizeHost } from "../net/public-address.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { readOrgSettings } from "../orgs/settings.service.js";
 import { adaptToFeatures } from "./features.js";
 import { ChannelJobs } from "./jobs.js";
 import { webhookBase, webhookUrlOf } from "./webhook-url.js";
+/**
+ * A public https address: https, and the host is not loopback, a private / link-local / reserved
+ * IP, `localhost`, `*.localhost`, `*.local`, `*.internal` or a single label (no DNS lookup).
+ */
+export function isPublicHttpsUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (u.protocol !== "https:")
+        return false;
+    const host = normalizeHost(u.hostname);
+    if (isLoopbackHost(host))
+        return false;
+    if (isIP(host) !== 0)
+        return !isForbiddenAddress(host);
+    if (!host.includes("."))
+        return false;
+    return ![".localhost", ".local", ".internal"].some((s) => host.endsWith(s));
+}
 /** 内核 secrets 命名空间（插件名不能取 `kernel`）。 */
 const SECRETS_NAMESPACE = "kernel";
 /** 连接配置里全部密钥字段存成一行：`{ 点路径: 值 }` 的 JSON。 */
@@ -99,6 +125,7 @@ const COLUMNS = [
     "last_error",
     "bot_user_id",
     "tenant_id",
+    "guide_ack",
     "created_by",
     "created_at",
     "updated_at",
@@ -120,7 +147,10 @@ let ChannelConnections = class ChannelConnections {
     config;
     log;
     txHost;
+    guides;
     unsubscribe;
+    /** `<plugin>@<version>` whose invalid connection hints were warned about (a log dedupe only). */
+    hintsWarned = new Set();
     constructor(db, 
     /** The org row lock (orgs/org-lock.ts): joins the transaction of the write. */
     orgLock, keyring, registry, bus, redis, 
@@ -129,7 +159,9 @@ let ChannelConnections = class ChannelConnections {
     /** `channels.webhookBaseUrl`: without it webhook mode is unavailable. */
     config, events, 
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
-    log, txHost) {
+    log, txHost, 
+    /** The setup guide acks (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    guides) {
         this.db = db;
         this.orgLock = orgLock;
         this.keyring = keyring;
@@ -140,6 +172,7 @@ let ChannelConnections = class ChannelConnections {
         this.config = config;
         this.log = log;
         this.txHost = txHost;
+        this.guides = guides;
         this.unsubscribe = [
             // a deleted org's channel connections drop their long connections at once
             events.on("org.deleted", ({ orgId }) => this.notifyOrgChanged(orgId)),
@@ -171,14 +204,46 @@ let ChannelConnections = class ChannelConnections {
             throw new ApiError("extension.not_enabled", `Extension ${plugin} is not enabled for this organization`);
         }
     }
-    /** `connectionSchema` 的 JSON Schema（同组织插件配置的转换：密钥字段带 `x-secret`、不输出取值）。 */
+    /**
+     * The connection schema's form JSON Schema (secret fields carry `x-secret`, no values), a copy.
+     * Never throws: when even the plain conversion fails, an empty object schema (a save is still
+     * validated here).
+     */
     jsonSchema(plugin) {
-        return configToJsonSchema(this.channel(plugin).connectionSchema);
+        const entry = this.channelEntry(plugin);
+        const r = this.formSchema(plugin, entry.version, entry.impl.connectionSchema);
+        return r ? structuredClone(r.schema) : { type: "object" };
+    }
+    /**
+     * The connection schema's form JSON Schema; invalid hints are stripped and warned about once per
+     * `<plugin>@<version>` on this replica (spec §4.1: the connection level is checked at its first
+     * conversion, not at load). Never throws: a hint conversion that throws serves the plain schema,
+     * else null, with one warning per schema.
+     */
+    formSchema(plugin, version, schema) {
+        const r = safeConfigFormSchema(schema, "connection", (err, fallback) => this.log.warn("the channel connection form schema could not be built with its UI hints; hints dropped", { plugin, version, schema: fallback, err }));
+        const key = `${plugin}@${version}`;
+        if (r && r.problems.length > 0 && !this.hintsWarned.has(key)) {
+            this.hintsWarned.add(key);
+            this.log.warn("extension config UI hints are invalid and ignored", {
+                plugin,
+                version,
+                detail: describeConfigUiProblems("connection", r.problems),
+            });
+        }
+        return r;
+    }
+    /** The loaded version of a channel extension, for warnings ("unknown" when not provided). */
+    versionOf(plugin) {
+        return (this.registry
+            .list("channel")
+            .find((x) => x.plugin === plugin && x.capability === CHANNEL_EXTENSION_POINT)?.version ??
+            "unknown");
     }
     parse(plugin, schema, config) {
         const r = schema.safeParse(config);
         if (!r.success) {
-            throw new ApiError("extension.config_invalid", `Invalid channel connection config for extension ${plugin}`, toIssues(r.error));
+            throw new ApiError("extension.config_invalid", `Invalid channel connection config for extension ${plugin}`, toIssues(r.error, configMessages(this.formSchema(plugin, this.versionOf(plugin), schema)?.schema)));
         }
         return r.data;
     }
@@ -242,6 +307,7 @@ let ChannelConnections = class ChannelConnections {
             lastError: r.last_error,
             botUserId: r.bot_user_id,
             tenantId: r.tenant_id,
+            guideAck: r.guide_ack ?? null,
             config: r.config ?? {},
             secrets: paths.map((path) => ({ path, set: setPaths.has(path) })),
             createdBy: r.created_by,
@@ -264,6 +330,38 @@ let ChannelConnections = class ChannelConnections {
             throw new ApiError("channel.webhook_unavailable", "Webhook inbound needs channels.webhookBaseUrl to be configured");
         }
     }
+    /**
+     * The fields the inbound mode requires (`x-ui.inboundModes`, channel inbound mode fields spec
+     * §3) must have a value in `full` (the parsed config, stored secrets included): 400
+     * `extension.config_invalid` with one issue per missing field otherwise. A plugin without the
+     * hint passes.
+     */
+    assertModeFields(plugin, schema, mode, full) {
+        const js = this.formSchema(plugin, this.versionOf(plugin), schema)?.schema;
+        if (js === undefined)
+            return;
+        const missing = missingInboundModeFields(js, mode, (field) => {
+            const v = getPath(full, field);
+            return v !== undefined && v !== null && v !== "";
+        });
+        if (missing.length === 0)
+            return;
+        throw new ApiError("extension.config_invalid", `Invalid channel connection config for extension ${plugin}`, missing.map((field) => ({
+            path: field,
+            segments: [field],
+            message: `required in ${mode} mode`,
+        })));
+    }
+    /** Whether the plugin's connections can use webhook inbound (spec §4); `extension.not_found`. */
+    inboundInfo(plugin) {
+        const webhookSupported = this.channel(plugin).webhook !== undefined;
+        const base = this.webhookBase();
+        return {
+            webhookSupported,
+            webhookAvailable: webhookSupported && base !== undefined,
+            webhookPublic: webhookSupported && base !== undefined && isPublicHttpsUrl(base),
+        };
+    }
     async viewOf(row) {
         return this.view(row, new Set(Object.keys(await this.readSecrets(row.org_id, row.id))));
     }
@@ -290,10 +388,16 @@ let ChannelConnections = class ChannelConnections {
         await this.assertEnabled(orgId, input.plugin);
         const schema = channel.connectionSchema;
         const full = this.parse(input.plugin, schema, input.config);
+        const mode = input.inboundMode ?? "long_connection";
+        if (mode === "webhook")
+            this.assertWebhookAvailable(input.plugin);
+        this.assertModeFields(input.plugin, schema, mode, full);
         await this.assertAgent(orgId, input.agentId);
         const verified = await this.verify(channel, full);
         const id = randomUUID();
         const { plain, secrets } = split(schema, full);
+        // the guide the 新建渠道 page showed: the plugin's current one, for the mode picked there
+        const guideAck = await this.guides.currentAck(input.plugin, "channel-connection", { mode });
         const row = await this.insertIn({
             orgId,
             id,
@@ -301,6 +405,7 @@ let ChannelConnections = class ChannelConnections {
             plain,
             secrets,
             verified,
+            guideAck,
             actorAccountId,
             actorTokenId,
         });
@@ -326,8 +431,10 @@ let ChannelConnections = class ChannelConnections {
             agent_id: input.agentId,
             config: JSON.stringify(a.plain),
             unbound_policy: input.unboundPolicy ?? "bind",
+            inbound_mode: input.inboundMode ?? "long_connection",
             bot_user_id: a.verified.botUserId,
             tenant_id: a.verified.tenantId,
+            guide_ack: a.guideAck === null ? null : JSON.stringify(a.guideAck),
             created_by: actorAccountId,
         })
             .returning(COLUMNS)
@@ -338,15 +445,32 @@ let ChannelConnections = class ChannelConnections {
             orgId,
             action: "channel.created",
             target: id,
-            detail: { plugin: input.plugin, agentId: input.agentId },
+            detail: {
+                plugin: input.plugin,
+                agentId: input.agentId,
+                inboundMode: input.inboundMode ?? "long_connection",
+            },
         });
         return inserted;
     }
+    /** The read-only refusals of {@link update} that need no write (the Platform tool's precheck). */
+    async checkUpdate(orgId, id, patch) {
+        const current = await this.live(orgId).where("id", "=", id).executeTakeFirst();
+        if (!current)
+            throw notFound();
+        if (patch.agentId !== undefined)
+            await this.assertAgent(orgId, patch.agentId);
+        if (patch.inboundMode === "webhook" && patch.inboundMode !== current.inbound_mode) {
+            this.assertWebhookAvailable(current.plugin);
+        }
+    }
     /**
      * 修改名称、agent、未绑定策略、启停，或轮换凭据（新配置同样先 `verify`，失败什么都不改）。
      * 插件在该组织停用时仍可轮换凭据，此时不 verify，返回 `verifySkipped: true`。
      */
-    async update(orgId, id, patch, actorAccountId, actorTokenId) {
+    async update(orgId, id, patch, actorAccountId, actorTokenId, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail) {
         const current = await this.live(orgId).where("id", "=", id).executeTakeFirst();
         if (!current)
             throw notFound();
@@ -377,16 +501,38 @@ let ChannelConnections = class ChannelConnections {
         const modeChanged = patch.inboundMode !== undefined && patch.inboundMode !== current.inbound_mode;
         if (modeChanged && patch.inboundMode === "webhook")
             this.assertWebhookAvailable(current.plugin);
+        if (rotated || modeChanged) {
+            // the fields the effective mode requires (spec §3): the new config, else the stored one
+            const schema = this.channel(current.plugin).connectionSchema;
+            const full = rotated?.full ?? {
+                ...(current.config ?? {}),
+                ...(await this.readSecrets(orgId, id)),
+            };
+            this.assertModeFields(current.plugin, schema, patch.inboundMode ?? current.inbound_mode, full);
+        }
         if (patch.agentId !== undefined)
             await this.assertAgent(orgId, patch.agentId);
+        // 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-09-setup-guides-v2-design.md §11)
+        const guideAck = modeChanged &&
+            patch.inboundMode !== undefined &&
+            !(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,
             id,
             patch,
             rotated,
             verified,
+            guideAck,
             actorAccountId,
             actorTokenId,
+            auditDetail,
         });
         if (rotated)
             this.reportSecrets(rotated.schema, rotated.full);
@@ -409,7 +555,7 @@ let ChannelConnections = class ChannelConnections {
     }
     /** The rows of {@link update}, in their own transaction (the caller publishes after the commit). */
     async updateIn(a) {
-        const { orgId, id, patch, rotated, verified, actorAccountId, actorTokenId } = a;
+        const { orgId, id, patch, rotated, verified, actorAccountId, actorTokenId, auditDetail } = a;
         await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "channels.manage");
         if (patch.agentId !== undefined)
             await this.assertAgent(orgId, patch.agentId);
@@ -430,6 +576,9 @@ let ChannelConnections = class ChannelConnections {
             ...(patch.unboundPolicy !== undefined && { unbound_policy: patch.unboundPolicy }),
             ...(patch.status !== undefined && { status: patch.status }),
             ...(patch.inboundMode !== undefined && { inbound_mode: patch.inboundMode }),
+            ...(a.guideAck !== undefined && {
+                guide_ack: a.guideAck === null ? null : JSON.stringify(a.guideAck),
+            }),
             ...(rotated && { config: JSON.stringify(rotated.plain) }),
             // 跳过了 verify：机器人 id 与租户保留原值（重新启用后插件按新凭据连接，入站以连接行的租户判断外部人员）
             ...(verified && { bot_user_id: verified.botUserId, tenant_id: verified.tenantId }),
@@ -454,17 +603,69 @@ let ChannelConnections = class ChannelConnections {
                     ...Object.keys(patch).filter((k) => k !== "config" && patch[k] !== undefined),
                     ...(rotated ? ["config"] : []),
                 ],
+                ...auditDetail,
             },
         });
         return updated;
     }
+    /**
+     * 「我已更新应用」: records the plugin's current channel-connection guide for the connection's
+     * 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, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
+     */
+    async ackGuide(org, id, hash, actorAccountId, actorTokenId) {
+        const { orgId } = org;
+        const current = await this.live(orgId).where("id", "=", id).executeTakeFirst();
+        if (!current)
+            throw notFound();
+        // 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");
+        }
+        if (ack.hash !== hash) {
+            throw new ApiError("channel.guide_changed", "The plugin's setup guide changed since it was shown; review the new guide first");
+        }
+        const row = await this.ackIn(orgId, id, ack, actorAccountId, actorTokenId);
+        return this.viewOf(row);
+    }
+    /** The row of {@link ackGuide}, in its own transaction. */
+    async ackIn(orgId, id, ack, actorAccountId, actorTokenId) {
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "channels.manage");
+        const row = await this.db
+            .updateTable("channel_connections")
+            .set({ guide_ack: JSON.stringify(ack), updated_at: sql `now()` })
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .returning(COLUMNS)
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        await audit(this.db.db, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "channel.guide_confirmed",
+            target: id,
+            detail: { guideId: ack.guideId, version: ack.version },
+        });
+        return row;
+    }
     /** 删除（软删除，同一事务删掉密钥）；持有长连接的副本收到广播后断开。 */
-    async remove(orgId, id, actorAccountId, actorTokenId) {
-        await this.removeIn(orgId, id, actorAccountId, actorTokenId);
+    async remove(orgId, id, actorAccountId, actorTokenId, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail) {
+        await this.removeIn(orgId, id, actorAccountId, actorTokenId, auditDetail);
         await this.changed(id, true);
     }
     /** The rows of {@link remove}, in their own transaction (the caller publishes after the commit). */
-    async removeIn(orgId, id, actorAccountId, actorTokenId) {
+    async removeIn(orgId, id, actorAccountId, actorTokenId, auditDetail) {
         await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "channels.manage");
         const r = await this.db
             .updateTable("channel_connections")
@@ -482,6 +683,7 @@ let ChannelConnections = class ChannelConnections {
             orgId,
             action: "channel.deleted",
             target: id,
+            ...(auditDetail !== undefined && { detail: auditDetail }),
         });
     }
     /** 提交后广播；失败只记日志（持有方每轮续租时也会复核连接状态）。 */
@@ -552,6 +754,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 ->
@@ -585,32 +823,37 @@ let ChannelConnections = class ChannelConnections {
      */
     async outbound(connectionId) {
         const { row, channel, config } = await this.runtime(connectionId);
-        // 组织语言随每次发送 / 更新交给插件（Ruling A22）；本次会话内不变
+        // the language handed to the extension with each send / update (Ruling A22): the recipient's
+        // when the caller gives it (IM language is per person, run context spec §3.4), else the org's
         const { locale } = await readOrgSettings(this.db.db, row.orgId);
         return {
             row,
             features: channel.features,
             redact: createRedactor(secretValues(channel.connectionSchema, config), 4),
-            send: (target, message, idempotencyKey) => channel.send({
+            send: (target, message, idempotencyKey, to = locale) => channel.send({
                 config,
-                ...adaptToFeatures(channel.features, target, message, locale),
+                ...adaptToFeatures(channel.features, target, message, to),
                 signal: AbortSignal.timeout(PLUGIN_CALL_TIMEOUT_MS),
-                locale,
+                locale: to,
                 ...(idempotencyKey !== undefined && { idempotencyKey }),
             }),
-            update: (target, messageId, message, idempotencyKey) => channel.update({
+            update: (target, messageId, message, idempotencyKey, to = locale) => channel.update({
                 config,
-                ...adaptToFeatures(channel.features, target, message, locale),
+                ...adaptToFeatures(channel.features, target, message, to),
                 messageId,
                 signal: AbortSignal.timeout(PLUGIN_CALL_TIMEOUT_MS),
-                locale,
+                locale: to,
                 ...(idempotencyKey !== undefined && { idempotencyKey }),
             }),
         };
     }
-    /** 经连接的插件直接发一条消息（入站处理回绑定卡片、固定话术，卡片操作回说明）；`idempotencyKey` 原样交给插件。 */
-    async send(connectionId, target, message, idempotencyKey) {
-        return (await this.outbound(connectionId)).send(target, message, idempotencyKey);
+    /**
+     * Sends one message through the connection's extension (inbound replies: bind cards, fixed
+     * phrases, card-action notes); `idempotencyKey` is passed through as is, `locale` is the
+     * recipient's language (else the org's).
+     */
+    async send(connectionId, target, message, idempotencyKey, locale) {
+        return (await this.outbound(connectionId)).send(target, message, idempotencyKey, locale);
     }
 };
 __decorate([
@@ -619,6 +862,9 @@ __decorate([
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], ChannelConnections.prototype, "updateIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], ChannelConnections.prototype, "ackIn", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], ChannelConnections.prototype, "removeIn", null);
@@ -634,6 +880,7 @@ ChannelConnections = __decorate([
     __param(7, Inject(KernelConfigService)),
     __param(8, Inject(KernelEvents)),
     __param(9, Inject(KERNEL_LOGGER)),
-    __param(10, Inject(TransactionHost))
+    __param(10, Inject(TransactionHost)),
+    __param(11, Inject(PluginGuides))
 ], ChannelConnections);
 export { ChannelConnections };

package/dist/channels/inbound.d.ts

@@ -1,6 +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 { 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";
@@ -62,6 +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 devices;
     private readonly log;
     private readonly actions;
     constructor(kdb: KernelDb, redis: Pick<Redis, "set">, 
@@ -72,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">, 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`：去重并入队后返回（见类注释）。返回后插件才向平台确认；抛错时插件不确认。
      */
@@ -92,6 +94,14 @@ export declare class ChannelInbound {
     /** 入站任务的处理（worker 上执行；失败抛错由队列重试）。 */
     handle(connectionId: string, e: InboundEvent): Promise<void>;
     private message;
+    /**
+     * 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 (`deviceLabel`: a former default demoted by a
+     * provider switch answers to e.g. "Personal (Docker sandbox)"); the default device also
+     * answers to 个人设备 / Personal.
+     */
+    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`