@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/channels/inbound.d.ts

@@ -1,13 +1,18 @@
 import type { ChannelCard, InboundEvent, InboundSender, Logger } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
-import type { ConversationsService } from "../conversations/conversations.service.js";
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { IdentityBinding } from "../identity/binding.js";
-import type { ExternalIdentities } from "../identity/external.js";
-import type { ApprovalsService } from "../tools/approvals.service.js";
-import type { QuestionsService } from "../tools/questions.service.js";
-import type { ChannelConnectionRow, ChannelConnections } from "./connections.service.js";
+import { ConversationsService } from "../conversations/conversations.service.js";
+import { EnvironmentsService } from "../environments/environments.service.js";
+import { IdentityBinding } from "../identity/binding.js";
+import { ExternalIdentities } from "../identity/external.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { DirectorySync } from "../orgs/directory-sync.js";
+import { ApprovalsService } from "../tools/approvals.service.js";
+import { QuestionsService } from "../tools/questions.service.js";
+import { type ChannelConnectionRow, ChannelConnections } from "./connections.service.js";
+import { ChannelJobs } from "./jobs.js";
 import { type ChannelLocale, type ChannelPhrase } from "./phrases.js";
+import { AnonymousGuests } from "./threads.js";
 /** 入站消息去重键的保留时长（秒）：平台在这段时间内重投同一条消息只处理一次。 */
 export declare const MESSAGE_DEDUPE_TTL_SECONDS = 86400;
 /** Dedupe key states: the enqueue is running (`pending`) or has succeeded (`done`). */
@@ -19,35 +24,6 @@ export declare const DEDUPE_PENDING_TTL_SECONDS = 60;
 export declare const messageDedupeKey: (connectionId: string, messageId: string) => string;
 /** 带平台事件 id 的卡片点击的去重键（Ruling A26，Redis 键，可以含 `:`）。 */
 export declare const actionDedupeKey: (connectionId: string, eventId: string) => string;
-/** 通讯录同步的投递接口（实现见 orgs/directory-sync.ts：按 (组织, 插件) 每分钟去重的维护队列任务）。 */
-export interface DirectorySyncScheduler {
-    /** 返回值（如 job id）不使用。 */
-    enqueue(orgId: string, plugin: string): Promise<unknown>;
-}
-/** 出站投递的投递接口（实现见 outbound.ts：把会话的新事件按 `channel_deliveries.last_seq` 续投到 IM）。 */
-export interface ChannelOutboundScheduler {
-    enqueue(conversationId: string): Promise<void>;
-}
-/** 入站任务的投递接口（实现见 outbound.ts：同一队列 `cap-kernel-channels` 的 `inbound` 任务）。 */
-export interface ChannelInboundQueue {
-    enqueueInbound(connectionId: string, event: InboundEvent, jobId: string): Promise<void>;
-}
-export interface ChannelInboundDeps {
-    db: KernelDb;
-    redis: Redis;
-    connections: Pick<ChannelConnections, "row" | "send">;
-    conversations: Pick<ConversationsService, "create" | "postUserMessage">;
-    external: Pick<ExternalIdentities, "findAccount">;
-    binding: Pick<IdentityBinding, "createBindToken">;
-    directorySync: DirectorySyncScheduler;
-    outbound: ChannelOutboundScheduler;
-    /** 入站任务队列（`onEvent` 只去重并入队，处理在 worker 上执行 {@link ChannelInbound.handle}）。 */
-    queue: ChannelInboundQueue;
-    /** 卡片操作：审批决定与提问回答（授权由这两个服务按点击者映射到的账号判定）。 */
-    approvals: Pick<ApprovalsService, "decide">;
-    questions: Pick<QuestionsService, "answer">;
-    log: Pick<Logger, "warn" | "info">;
-}
 /**
  * 渠道入站（Ruling A21：持久化处理）。
  * - `onEvent`（插件 `connect` 的回调，必须快）：消息按 `capk:channel-msg:<连接>:<消息>` `SET NX` 24 小时去重，
@@ -74,9 +50,31 @@ export interface ChannelInboundDeps {
  * 处理在写入用户消息之后失败而重试时，固定话术 / 卡片回复可能再发一次。
  */
 export declare class ChannelInbound {
-    private readonly deps;
+    private readonly kdb;
+    private readonly redis;
+    /** The two-state dedupe markers (`lease` / `holderOf` / `releaseIf`; keys unchanged). */
+    private readonly locks;
+    private readonly connections;
+    private readonly conversations;
+    private readonly external;
+    private readonly binding;
+    /** 通讯录同步的投递（按 (组织, 插件) 每分钟去重的维护队列任务）。 */
+    private readonly directorySync;
+    /** The channel queue: inbound jobs (`onEvent` only dedupes and enqueues) and deliveries. */
+    private readonly jobs;
+    private readonly guests;
+    private readonly environments;
+    private readonly log;
     private readonly actions;
-    constructor(deps: ChannelInboundDeps);
+    constructor(kdb: KernelDb, redis: Pick<Redis, "set">, 
+    /** The two-state dedupe markers (`lease` / `holderOf` / `releaseIf`; keys unchanged). */
+    locks: Pick<LockService, "lease" | "holderOf" | "releaseIf">, connections: Pick<ChannelConnections, "row" | "send">, conversations: Pick<ConversationsService, "create" | "postUserMessage">, external: Pick<ExternalIdentities, "findAccount">, binding: Pick<IdentityBinding, "createBindToken">, 
+    /** 通讯录同步的投递（按 (组织, 插件) 每分钟去重的维护队列任务）。 */
+    directorySync: Pick<DirectorySync, "enqueue">, 
+    /** 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">);
     /**
      * 插件 `onEvent`：去重并入队后返回（见类注释）。返回后插件才向平台确认；抛错时插件不确认。
      */
@@ -96,6 +94,14 @@ export declare class ChannelInbound {
     /** 入站任务的处理（worker 上执行；失败抛错由队列重试）。 */
     handle(connectionId: string, e: InboundEvent): Promise<void>;
     private message;
+    /**
+     * Direct-message `/env` (environments spec §4.2 item 8): lists the person's usable environments,
+     * 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.
+     */
+    private envCommand;
     /**
      * 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

@@ -1,11 +1,33 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 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 { ApiError } from "../errors.js";
-import { readOrgSettings } from "../orgs/settings.service.js";
+import { IdentityBinding } from "../identity/binding.js";
+import { ExternalIdentities } from "../identity/external.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
+import { DirectorySync } from "../orgs/directory-sync.js";
 import { parseSlashCommand } from "../skills/invoke.js";
+import { ApprovalsService } from "../tools/approvals.service.js";
+import { QuestionsService } from "../tools/questions.service.js";
 import { ChannelCardActions } from "./actions.js";
-import { idempotencyKey, inboundJobId } from "./outbound.js";
+import { ChannelConnections } from "./connections.service.js";
+import { ChannelJobs, idempotencyKey, inboundJobId } from "./jobs.js";
 import { phrase } from "./phrases.js";
-import { archiveThread, ensureAnonymousGuest, findThread, insertThread, threadKeyOf, } from "./threads.js";
+import { AnonymousGuests, archiveThread, findThread, insertThread, threadKeyOf, } from "./threads.js";
 /** 入站消息去重键的保留时长（秒）：平台在这段时间内重投同一条消息只处理一次。 */
 export const MESSAGE_DEDUPE_TTL_SECONDS = 86_400;
 /** Dedupe key states: the enqueue is running (`pending`) or has succeeded (`done`). */
@@ -13,11 +35,6 @@ export const DEDUPE_PENDING = "pending";
 export const DEDUPE_DONE = "done";
 /** A `pending` key outlives a crashed enqueuer only this long, then redeliveries enqueue again. */
 export const DEDUPE_PENDING_TTL_SECONDS = 60;
-/** Deletes KEYS[1] only while it still holds ARGV[1] (a failed enqueue must not drop `done`). */
-const DEL_IF_PENDING = `if redis.call("GET", KEYS[1]) == ARGV[1] then
-  return redis.call("DEL", KEYS[1])
-end
-return 0`;
 /** 入站消息去重键（Redis 键，不是队列名 / job id，可以含 `:`）。 */
 export const messageDedupeKey = (connectionId, messageId) => `capk:channel-msg:${connectionId}:${messageId}`;
 /** 带平台事件 id 的卡片点击的去重键（Ruling A26，Redis 键，可以含 `:`）。 */
@@ -47,17 +64,49 @@ export const actionDedupeKey = (connectionId, eventId) => `capk:channel-act:${co
  * 边界（已接受）：同一 chat 的连续消息由不同任务并发处理，极少数情况下写入顺序可能与平台顺序不同；
  * 处理在写入用户消息之后失败而重试时，固定话术 / 卡片回复可能再发一次。
  */
-export class ChannelInbound {
-    deps;
+let ChannelInbound = class ChannelInbound {
+    kdb;
+    redis;
+    locks;
+    connections;
+    conversations;
+    external;
+    binding;
+    directorySync;
+    jobs;
+    guests;
+    environments;
+    log;
     actions;
-    constructor(deps) {
-        this.deps = deps;
+    constructor(kdb, redis, 
+    /** The two-state dedupe markers (`lease` / `holderOf` / `releaseIf`; keys unchanged). */
+    locks, connections, conversations, external, binding, 
+    /** 通讯录同步的投递（按 (组织, 插件) 每分钟去重的维护队列任务）。 */
+    directorySync, 
+    /** The channel queue: inbound jobs (`onEvent` only dedupes and enqueues) and deliveries. */
+    jobs, 
+    /** 卡片操作：审批决定与提问回答（授权由这两个服务按点击者映射到的账号判定）。 */
+    approvals, questions, guests, environments, log) {
+        this.kdb = kdb;
+        this.redis = redis;
+        this.locks = locks;
+        this.connections = connections;
+        this.conversations = conversations;
+        this.external = external;
+        this.binding = binding;
+        this.directorySync = directorySync;
+        this.jobs = jobs;
+        this.guests = guests;
+        this.environments = environments;
+        this.log = log;
         this.actions = new ChannelCardActions({
-            db: deps.db,
-            connections: deps.connections,
-            approvals: deps.approvals,
-            questions: deps.questions,
-            outbound: deps.outbound,
+            get db() {
+                return kdb.db;
+            },
+            connections,
+            approvals,
+            questions,
+            outbound: jobs,
             resolveSpeaker: (...args) => this.resolveSpeaker(...args),
         });
     }
@@ -70,7 +119,7 @@ export class ChannelInbound {
         if (e.type === "card_action") {
             if (e.eventId === undefined) {
                 // 平台没给事件 id：无法识别重投，每次都处理（重复的审批 / 回答由服务回「已处理」）
-                await this.deps.queue.enqueueInbound(connectionId, e, `inbound-${connectionId}-a${randomUUID()}`);
+                await this.jobs.enqueueInbound(connectionId, e, `inbound-${connectionId}-a${randomUUID()}`);
                 return;
             }
             return this.dedupeAndEnqueue(connectionId, e, actionDedupeKey(connectionId, e.eventId), inboundJobId(connectionId, `act:${e.eventId}`));
@@ -89,10 +138,9 @@ export class ChannelInbound {
      *   not create a second run; it means a redelivery is never acked before the job is really queued.
      */
     async dedupeAndEnqueue(connectionId, e, key, jobId) {
-        const { redis, queue } = this.deps;
-        const fresh = await redis.set(key, DEDUPE_PENDING, "EX", DEDUPE_PENDING_TTL_SECONDS, "NX");
-        if (fresh !== "OK") {
-            const state = await redis.get(key);
+        const fresh = await this.locks.lease(key, DEDUPE_PENDING, DEDUPE_PENDING_TTL_SECONDS * 1000);
+        if (!fresh) {
+            const state = await this.locks.holderOf(key);
             // Ack only a known-queued event ("1" = key from the pre-two-state code during a rolling
             // upgrade); pending, or a key that vanished meanwhile (failed attempt, TTL), enqueues again
             if (state === DEDUPE_DONE || state === "1")
@@ -101,20 +149,21 @@ export class ChannelInbound {
         // Accepted edge: if the completed-job cap evicts the original job within the pending window,
         // the re-add below runs the event twice (a duplicate run, never a loss)
         try {
-            await queue.enqueueInbound(connectionId, e, jobId);
+            await this.jobs.enqueueInbound(connectionId, e, jobId);
         }
         catch (err) {
-            await redis.eval(DEL_IF_PENDING, 1, key, DEDUPE_PENDING).catch(() => { });
+            // a failed enqueue must not drop `done` (compare-and-delete)
+            await this.locks.releaseIf(key, DEDUPE_PENDING).catch(() => { });
             throw err;
         }
-        await redis.set(key, DEDUPE_DONE, "EX", MESSAGE_DEDUPE_TTL_SECONDS);
+        await this.redis.set(key, DEDUPE_DONE, "EX", MESSAGE_DEDUPE_TTL_SECONDS);
     }
     /** 入站任务的处理（worker 上执行；失败抛错由队列重试）。 */
     async handle(connectionId, e) {
         if (e.type === "directory_changed") {
-            const row = await this.deps.connections.row(connectionId);
+            const row = await this.connections.row(connectionId);
             if (row?.status === "active" && row.pluginEnabled) {
-                await this.deps.directorySync.enqueue(row.orgId, row.plugin);
+                await this.directorySync.enqueue(row.orgId, row.plugin);
             }
             return;
         }
@@ -125,7 +174,8 @@ export class ChannelInbound {
         await this.message(connectionId, e);
     }
     async message(connectionId, e) {
-        const { db, connections } = this.deps;
+        const db = this.kdb.db;
+        const connections = this.connections;
         const row = await connections.row(connectionId);
         // 连接停用、组织已删除或插件在该组织停用（停用广播与长连接断开之间仍可能有事件到达）：什么都不做
         if (row?.status !== "active" || !row.pluginEnabled)
@@ -136,16 +186,25 @@ export class ChannelInbound {
         const threadKey = threadKeyOf(e.target, e.sender.externalId, e.messageId);
         // 群里回在话题里（新话题以这条消息为根）
         const replyTarget = isGroup ? { ...e.target, threadId: threadKey } : e.target;
-        const { locale } = await readOrgSettings(db, row.orgId);
+        // the sender's zone and language as the platform gives them (run context spec §3.4)
+        const im = imSenderContext(e.sender);
+        // kernel text speaks the person's language (maintainer decision 2026-11-08): before the
+        // speaker is known, the platform's language, else the org's
+        let locale = await recipientLocale(db, { orgId: row.orgId, im: im.locale });
         // 回复带幂等键：任务重试时平台不会重复显示（一条消息至多一句回复）
         const replyKey = idempotencyKey(`${connectionId}-${e.messageId}-reply`);
-        const reply = async (key, cards) => {
-            await connections.send(connectionId, replyTarget, { text: phrase(key, locale), ...(cards !== undefined && { cards }) }, replyKey);
+        const replyText = async (text, cards) => {
+            await connections.send(connectionId, replyTarget, { text, ...(cards !== undefined && { cards }) }, replyKey, locale);
         };
+        const reply = (key, cards) => replyText(phrase(key, locale), cards);
         const speaker = await this.resolveSpeaker(connectionId, row, e.sender, isGroup, locale, reply);
         if (speaker === undefined)
             return;
         const { accountId, threadAccount } = speaker;
+        // a bound person without a platform language: their latest web message's, else the org's
+        if (im.locale === undefined && threadAccount !== null) {
+            locale = await recipientLocale(db, { orgId: row.orgId, accountId: threadAccount });
+        }
         const k = {
             connectionId,
             chatId: e.target.chatId,
@@ -157,11 +216,19 @@ export 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);
+            return;
+        }
         let conversationId = await findThread(db, k);
         if (conversationId === undefined) {
             let created;
             try {
-                created = (await this.deps.conversations.create(row.orgId, accountId, row.agentId)).id;
+                // bound to the person's IM default environment, 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;
             }
             catch (err) {
                 if (err instanceof ApiError && err.code === "agent.not_found") {
@@ -185,12 +252,17 @@ export class ChannelInbound {
             const posted = await this.post(row.orgId, conversationId, accountId, {
                 text: e.text,
                 clientMessageId: `${connectionId}:${e.messageId}`,
+                // run context spec §7: an anonymous guest is named by their IM profile name; a bound
+                // person by their account's name (the kernel reads it)
+                ...(threadAccount === null &&
+                    e.sender.displayName !== undefined && { senderName: e.sender.displayName }),
+                im,
             });
             seq = posted.event.seq;
             // best-effort (batch 5 review m4): a failed note must not fail the job before the thread
             // is bound for the agent's reply below
             if (posted.skillNotRun) {
-                await reply("skillNotRun").catch((err) => this.deps.log.warn("cannot send the skill-not-run note", {
+                await reply("skillNotRun").catch((err) => this.log.warn("cannot send the skill-not-run note", {
                     connectionId,
                     messageId: e.messageId,
                     err,
@@ -219,7 +291,52 @@ export class ChannelInbound {
             updated_at: new Date(),
         }))
             .execute();
-        await this.deps.outbound.enqueue(conversationId);
+        await this.jobs.enqueue(conversationId);
+    }
+    /**
+     * Direct-message `/env` (environments spec §4.2 item 8): lists the person's usable environments,
+     * 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.
+     */
+    async envCommand(orgId, accountId, name, locale, replyText) {
+        const { items, defaultId } = await this.environments.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 list = usable
+            .map((v) => `- ${labelOf(v)}${v.id === current ? phrase("envCurrent", 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));
+        if (name === null)
+            return replyText(fill("envList", { 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));
+        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("envUnknown", { name, list }));
+        }
+        try {
+            await this.environments.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 }));
+            }
+            throw err;
+        }
+        return replyText(fill("envSwitched", { name: labelOf(hit) }));
     }
     /**
      * Posts the person's message: `/name args` as a skill invocation when the kernel accepts it, else
@@ -233,7 +350,11 @@ export class ChannelInbound {
         let skillNotRun = false;
         if (cmd !== null) {
             try {
-                const event = await this.deps.conversations.postUserMessage(orgId, conversationId, accountId, { ...input, text: cmd.args, skill: { name: cmd.name } });
+                const event = await this.conversations.postUserMessage(orgId, conversationId, accountId, {
+                    ...input,
+                    text: cmd.args,
+                    skill: { name: cmd.name },
+                });
                 return { event, skillNotRun };
             }
             catch (err) {
@@ -243,7 +364,7 @@ export class ChannelInbound {
                 }
                 if (err.code === "validation_failed") {
                     skillNotRun = true;
-                    this.deps.log.info("IM skill invocation posted as text", {
+                    this.log.info("IM skill invocation posted as text", {
                         conversationId,
                         skill: cmd.name,
                         reason: err.message,
@@ -251,7 +372,7 @@ export class ChannelInbound {
                 }
             }
         }
-        const event = await this.deps.conversations.postUserMessage(orgId, conversationId, accountId, input);
+        const event = await this.conversations.postUserMessage(orgId, conversationId, accountId, input);
         return { event, skillNotRun };
     }
     /**
@@ -260,9 +381,8 @@ export class ChannelInbound {
      * `threadAccount` 为话题行记的账号（匿名访客为 null）。
      */
     async resolveSpeaker(connectionId, row, sender, isGroup, locale, reply) {
-        const { db } = this.deps;
         const source = `${row.plugin}:${sender.tenantId}`;
-        const bound = await this.deps.external.findAccount(source, sender.externalId);
+        const bound = await this.external.findAccount(source, sender.externalId);
         if (bound !== undefined && (await this.isActiveMember(row.orgId, bound))) {
             return { accountId: bound, threadAccount: bound };
         }
@@ -273,7 +393,7 @@ export class ChannelInbound {
                 await reply("anonymousNotAllowed");
                 return undefined;
             }
-            return { accountId: await ensureAnonymousGuest(db, row.orgId), threadAccount: null };
+            return { accountId: await this.guests.ensure(row.orgId), threadAccount: null };
         }
         if (bound !== undefined) {
             await reply("notMember");
@@ -285,7 +405,7 @@ export class ChannelInbound {
         }
         let url;
         try {
-            url = await this.deps.binding.createBindToken({
+            url = await this.binding.createBindToken({
                 connectionId,
                 identity: {
                     source,
@@ -298,7 +418,7 @@ export class ChannelInbound {
             });
         }
         catch (err) {
-            this.deps.log.warn("cannot create channel bind link", { connectionId, err });
+            this.log.warn("cannot create channel bind link", { connectionId, err });
             await reply("bindUnavailable");
             return undefined;
         }
@@ -307,7 +427,7 @@ export class ChannelInbound {
     }
     /** 账号是该组织成员且账号未停用。 */
     async isActiveMember(orgId, accountId) {
-        const r = await this.deps.db
+        const r = await this.kdb
             .selectFrom("memberships")
             .innerJoin("accounts", "accounts.id", "memberships.account_id")
             .select("memberships.role")
@@ -319,7 +439,7 @@ export class ChannelInbound {
     }
     /** 连接绑定的 agent 未删除且可见范围为「全组织」（匿名访客只能用这种 agent）。 */
     async agentVisibleToOrg(orgId, agentId) {
-        const r = await this.deps.db
+        const r = await this.kdb
             .selectFrom("agents")
             .select("id")
             .where("id", "=", agentId)
@@ -329,4 +449,30 @@ export class ChannelInbound {
             .executeTakeFirst();
         return r !== undefined;
     }
+};
+ChannelInbound = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(REDIS)),
+    __param(2, Inject(LockService)),
+    __param(3, Inject(ChannelConnections)),
+    __param(4, Inject(ConversationsService)),
+    __param(5, Inject(ExternalIdentities)),
+    __param(6, Inject(IdentityBinding)),
+    __param(7, Inject(DirectorySync)),
+    __param(8, Inject(ChannelJobs)),
+    __param(9, Inject(ApprovalsService)),
+    __param(10, Inject(QuestionsService)),
+    __param(11, Inject(AnonymousGuests)),
+    __param(12, Inject(EnvironmentsService)),
+    __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());
+    if (m === null)
+        return null;
+    const name = m[1]?.trim();
+    return { name: name ? name : null };
 }

package/dist/channels/job-ids.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The channel gateway check's job name and the maintenance job scheduler id it had before it
+ * became a `@LockedCron` job: an upgraded deployment still has the
+ * scheduler in Redis, so the worker removes it at start (`RETIRED_SCHEDULER_IDS`). A leaf module:
+ * the maintenance worker imports it without the channel providers.
+ */
+/** The gateway check's job name (`@LockedCron`). */
+export declare const GATEWAY_CHECK_JOB = "channel-gateway-check";
+/** The gateway check's old scheduler (every minute). */
+export declare const GATEWAY_CHECK_SCHEDULER_ID = "channel-gateway-check-every";

package/dist/channels/job-ids.js

@@ -0,0 +1,10 @@
+/**
+ * The channel gateway check's job name and the maintenance job scheduler id it had before it
+ * became a `@LockedCron` job: an upgraded deployment still has the
+ * scheduler in Redis, so the worker removes it at start (`RETIRED_SCHEDULER_IDS`). A leaf module:
+ * the maintenance worker imports it without the channel providers.
+ */
+/** The gateway check's job name (`@LockedCron`). */
+export const GATEWAY_CHECK_JOB = "channel-gateway-check";
+/** The gateway check's old scheduler (every minute). */
+export const GATEWAY_CHECK_SCHEDULER_ID = "channel-gateway-check-every";

package/dist/channels/jobs.d.ts

@@ -0,0 +1,85 @@
+import type { InboundEvent, Logger } from "@capybara-hq/plugin-sdk";
+import { type OnApplicationShutdown } from "@nestjs/common";
+import type { Queue } from "bullmq";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+/** 渠道队列（出站投递与入站任务，不含 `:`），只在 worker 角色上消费。 */
+export declare const CHANNEL_QUEUE_NAME = "cap-kernel-channels";
+/** 投递任务名。 */
+export declare const DELIVER_JOB = "deliver";
+/** 投递任务 id（不含 `:`）：同一会话、同一日志位置只排一个任务。 */
+export declare const deliverJobId: (conversationId: string, seq: number) => string;
+/**
+ * 结束后复核排的任务 id：每次唯一（带随机后缀，不含 `:`）。不能复用 `deliver-<会话>-<seq>`——同 id 的任务
+ * 可能正因锁被占而即将直接结束，BullMQ 会把新任务去重进它，于是没人投递。
+ */
+export declare const followUpJobId: (conversationId: string, seq: number) => string;
+/**
+ * 发给插件的幂等键（Ruling A15）：把逻辑键（如 `<会话>-<seq>`）做 sha256，取 base64url 的前 32 个字符——
+ * 稳定、只含 `[A-Za-z0-9_-]`，满足常见平台的长度限制。
+ */
+export declare function idempotencyKey(raw: string): string;
+/** 可重试失败（限流、5xx、网络、超时）的总尝试次数。 */
+export declare const DELIVER_ATTEMPTS = 8;
+export interface DeliverJobData {
+    conversationId: string;
+}
+/** 入站任务（Ruling A21）：插件 `onEvent` 收到的事件，原样排进队列由 worker 处理。 */
+export interface InboundJobData {
+    connectionId: string;
+    event: InboundEvent;
+}
+export type ChannelJobData = DeliverJobData | InboundJobData;
+/** 入站任务名。 */
+export declare const INBOUND_JOB = "inbound";
+/**
+ * BullMQ 优先级（数字越小越先）：入站任务先于出站投递任务——投递任务可能占着并发槽等输出，
+ * 用户发来的消息不能排在它们后面。
+ */
+export declare const INBOUND_PRIORITY = 1;
+export declare const DELIVER_PRIORITY = 10;
+/** 入站任务的总尝试次数（处理失败由 BullMQ 指数退避重试：1s、2s、4s、8s）。 */
+export declare const INBOUND_ATTEMPTS = 5;
+/**
+ * 入站消息的任务 id（不含 `:`）：`inbound-<连接>-<sha256(消息 id) 的 base64url 前 22 位>`。同一条消息只排一个任务
+ * （已完成的任务保留一段时间，期间重复入队被 BullMQ 忽略）。
+ */
+export declare const inboundJobId: (connectionId: string, messageId: string) => string;
+/**
+ * The producer side of the channel queue `cap-kernel-channels` (any role): delivery jobs for a
+ * conversation with an IM target, inbound jobs (Ruling A21), and the catch-up of a connection that
+ * can deliver again. Its consumer is {@link ChannelOutbound} through the `@Processor` of the worker
+ * role. Delivery jobs follow the kernel's domain events (spec §3b): every published log advance
+ * (`conversation.event-appended`), a run starting here (`run.started`), a stopped wait
+ * (`run.wait-stopped`), a decided approval and an answered question (their cards change). Each is
+ * lost-tolerant: the next append enqueues again, and a finished delivery job re-checks the log.
+ */
+export declare class ChannelJobs implements OnApplicationShutdown {
+    private readonly db;
+    private readonly queue;
+    private readonly log;
+    /** Stopped (the stop's channel-outbound phase): enqueues do nothing, inbound enqueues throw. */
+    private closed;
+    private readonly unsubscribe;
+    constructor(db: KernelDb, queue: Queue<ChannelJobData>, events: Pick<KernelEvents, "on">, log: Pick<Logger, "warn" | "error">);
+    /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
+    onApplicationShutdown(): void;
+    /** 会话有 IM 投递目标时排一个出站任务，不等入队完成；失败只记日志。 */
+    private enqueueSoon;
+    /** 会话有 IM 投递目标时投递一个出站任务（同一日志位置重复调用只排一个）；已关闭时什么都不做。 */
+    enqueue(conversationId: string, opts?: {
+        followUp?: boolean;
+    }): Promise<void>;
+    /**
+     * 排一个入站任务（Ruling A21，同一队列 `cap-kernel-channels`）：处理失败按 {@link INBOUND_ATTEMPTS} 次指数退避重试。
+     * 已关闭时抛错（调用方据此让插件不确认、由平台重投）。
+     */
+    enqueueInbound(connectionId: string, event: InboundEvent, jobId: string): Promise<void>;
+    /**
+     * 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
+     * 补投停用或凭据失效期间落下的内容（不必等下一条消息）。
+     */
+    resumeConnection(connectionId: string): Promise<void>;
+    /** No more jobs from this process (the stop's channel-outbound phase). Idempotent. */
+    close(): void;
+}