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

package/dist/channels/connections.service.js

@@ -1,18 +1,37 @@
+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 { 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 { queryEnabledPlugins } from "../ctx/create-ctx.js";
 import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
-import { configToJsonSchema } from "../extensions/config-json-schema.js";
+import { toIssues } from "../extensions/config-issues.js";
+import { configMessages, describeConfigUiProblems, safeConfigFormSchema, } from "../extensions/config-json-schema.js";
 import { enabledExtensionsByOrg } from "../extensions/enabled.js";
-import { toIssues } from "../extensions/org-config.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";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+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 { lockOrgAndAuthorize } from "../orgs/org-lock.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";
 /** 内核 secrets 命名空间（插件名不能取 `kernel`）。 */
 const SECRETS_NAMESPACE = "kernel";
@@ -81,6 +100,7 @@ const COLUMNS = [
     "last_error",
     "bot_user_id",
     "tenant_id",
+    "guide_ack",
     "created_by",
     "created_at",
     "updated_at",
@@ -91,17 +111,62 @@ const COLUMNS = [
  * （命名空间 `kernel`，键 `channels:<id>:config`）。写操作在组织行锁内实时复核 `channels.manage`，写审计；
  * 改动提交后经内核 bus 广播 `channel.changed`，持有该连接的副本据此断开（下一轮扫描按新配置重连）。
  */
-export class ChannelConnections {
-    deps;
-    constructor(deps) {
-        this.deps = deps;
+let ChannelConnections = class ChannelConnections {
+    db;
+    orgLock;
+    keyring;
+    registry;
+    bus;
+    redis;
+    jobs;
+    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, 
+    /** A connection that can deliver again catches up its conversations (`resumeConnection`). */
+    jobs, 
+    /** `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, 
+    /** The setup guide acks (spec 2026-11-08-plugin-setup-guides-design.md §6). */
+    guides) {
+        this.db = db;
+        this.orgLock = orgLock;
+        this.keyring = keyring;
+        this.registry = registry;
+        this.bus = bus;
+        this.redis = redis;
+        this.jobs = jobs;
+        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)),
+            // an org disabling an extension drops that extension's channel connections at once (the
+            // supervisor's periodic re-check is the fallback)
+            events.on("extension.org-disabled", ({ orgId, plugin }) => this.notifyOrgChanged(orgId, plugin)),
+        ];
+    }
+    /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
+    onApplicationShutdown() {
+        for (const off of this.unsubscribe)
+            off();
     }
     /** The extension's `channel@1`; not loaded or not provided -> `extension.not_found`. */
     channel(plugin) {
         return this.channelEntry(plugin).impl;
     }
     channelEntry(plugin) {
-        const e = this.deps.host
+        const e = this.registry
             .list("channel")
             .find((x) => x.plugin === plugin && x.capability === CHANNEL_EXTENSION_POINT);
         if (!e)
@@ -110,18 +175,50 @@ export class ChannelConnections {
     }
     /** The extension is not enabled in this organization -> `extension.not_enabled`. */
     async assertEnabled(orgId, plugin) {
-        if (!(await queryEnabledPlugins(this.deps.db, orgId)).has(plugin)) {
+        if (!(await queryEnabledPlugins(this.db.db, orgId)).has(plugin)) {
             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;
     }
@@ -141,10 +238,10 @@ export class ChannelConnections {
     reportSecrets(schema, config) {
         const values = secretValues(schema, config);
         if (values.length > 0)
-            this.deps.onSecrets?.(values);
+            this.log.addOrgSecrets(values);
     }
-    async assertAgent(t, orgId, agentId) {
-        const a = await t
+    async assertAgent(orgId, agentId) {
+        const a = await this.db
             .selectFrom("agents")
             .select("id")
             .where("id", "=", agentId)
@@ -155,7 +252,7 @@ export class ChannelConnections {
             throw new ApiError("agent.not_found", "Agent not found");
     }
     async readSecrets(orgId, id) {
-        const raw = await createSecrets(this.deps.db, this.deps.keyring, SECRETS_NAMESPACE).get(orgId, connectionSecretKey(id));
+        const raw = await createSecrets(this.db.db, this.keyring, SECRETS_NAMESPACE).get(orgId, connectionSecretKey(id));
         return raw === null ? {} : JSON.parse(raw);
     }
     view(r, setPaths) {
@@ -185,6 +282,7 @@ export 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,
@@ -193,8 +291,7 @@ export class ChannelConnections {
         };
     }
     webhookBase() {
-        const config = this.deps.config?.();
-        return config === undefined ? undefined : webhookBase(config);
+        return webhookBase(this.config.get());
     }
     /**
      * Switching to webhook mode needs a plugin that implements `Channel.webhook` and a configured
@@ -212,7 +309,7 @@ export class ChannelConnections {
         return this.view(row, new Set(Object.keys(await this.readSecrets(row.org_id, row.id))));
     }
     live(orgId) {
-        return this.deps.db
+        return this.db
             .selectFrom("channel_connections")
             .select(COLUMNS)
             .where("org_id", "=", orgId)
@@ -234,51 +331,80 @@ export class ChannelConnections {
         await this.assertEnabled(orgId, input.plugin);
         const schema = channel.connectionSchema;
         const full = this.parse(input.plugin, schema, input.config);
-        await this.assertAgent(this.deps.db, orgId, input.agentId);
+        await this.assertAgent(orgId, input.agentId);
         const verified = await this.verify(channel, full);
         const id = randomUUID();
         const { plain, secrets } = split(schema, full);
-        const row = await this.deps.db.transaction().execute(async (t) => {
-            await lockOrgAndAuthorize(t, orgId, actorAccountId, "channels.manage");
-            await this.assertAgent(t, orgId, input.agentId);
-            if (Object.keys(secrets).length > 0) {
-                await createSecrets(t, this.deps.keyring, SECRETS_NAMESPACE).set(orgId, connectionSecretKey(id), JSON.stringify(secrets));
-            }
-            const inserted = await t
-                .insertInto("channel_connections")
-                .values({
-                id,
-                org_id: orgId,
-                plugin: input.plugin,
-                name: input.name,
-                agent_id: input.agentId,
-                config: JSON.stringify(plain),
-                unbound_policy: input.unboundPolicy ?? "bind",
-                bot_user_id: verified.botUserId,
-                tenant_id: verified.tenantId,
-                created_by: actorAccountId,
-            })
-                .returning(COLUMNS)
-                .executeTakeFirstOrThrow();
-            await audit(t, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "channel.created",
-                target: id,
-                detail: { plugin: input.plugin, agentId: input.agentId },
-            });
-            return inserted;
+        // 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 row = await this.insertIn({
+            orgId,
+            id,
+            input,
+            plain,
+            secrets,
+            verified,
+            guideAck,
+            actorAccountId,
+            actorTokenId,
         });
         this.reportSecrets(schema, full);
         await this.changed(id, false);
         return this.view(row, new Set(Object.keys(secrets)));
     }
+    /** The rows of {@link create}, in their own transaction (the caller publishes after the commit). */
+    async insertIn(a) {
+        const { orgId, id, input, actorAccountId, actorTokenId } = a;
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "channels.manage");
+        await this.assertAgent(orgId, input.agentId);
+        if (Object.keys(a.secrets).length > 0) {
+            await createSecrets(this.db.db, this.keyring, SECRETS_NAMESPACE).set(orgId, connectionSecretKey(id), JSON.stringify(a.secrets));
+        }
+        const inserted = await this.db
+            .insertInto("channel_connections")
+            .values({
+            id,
+            org_id: orgId,
+            plugin: input.plugin,
+            name: input.name,
+            agent_id: input.agentId,
+            config: JSON.stringify(a.plain),
+            unbound_policy: input.unboundPolicy ?? "bind",
+            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)
+            .executeTakeFirstOrThrow();
+        await audit(this.db.db, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "channel.created",
+            target: id,
+            detail: { plugin: input.plugin, agentId: input.agentId },
+        });
+        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();
@@ -288,7 +414,7 @@ export class ChannelConnections {
         if (patch.config !== undefined) {
             const channel = this.channel(current.plugin);
             // 插件在该组织停用时也允许轮换（泄露的密钥要能立刻换掉），但不调用插件 verify：重新启用后长连接按新凭据连接
-            const enabled = (await queryEnabledPlugins(this.deps.db, orgId)).has(current.plugin);
+            const enabled = (await queryEnabledPlugins(this.db.db, orgId)).has(current.plugin);
             const schema = channel.connectionSchema;
             const before = await this.readSecrets(orgId, id);
             const next = structuredClone(patch.config);
@@ -310,55 +436,26 @@ export class ChannelConnections {
         if (modeChanged && patch.inboundMode === "webhook")
             this.assertWebhookAvailable(current.plugin);
         if (patch.agentId !== undefined)
-            await this.assertAgent(this.deps.db, orgId, patch.agentId);
-        const row = await this.deps.db.transaction().execute(async (t) => {
-            await lockOrgAndAuthorize(t, orgId, actorAccountId, "channels.manage");
-            if (patch.agentId !== undefined)
-                await this.assertAgent(t, orgId, patch.agentId);
-            if (rotated) {
-                const secrets = createSecrets(t, this.deps.keyring, SECRETS_NAMESPACE);
-                if (Object.keys(rotated.secrets).length > 0) {
-                    await secrets.set(orgId, connectionSecretKey(id), JSON.stringify(rotated.secrets));
-                }
-                else {
-                    await secrets.delete(orgId, connectionSecretKey(id));
-                }
-            }
-            const updated = await t
-                .updateTable("channel_connections")
-                .set({
-                ...(patch.name !== undefined && { name: patch.name }),
-                ...(patch.agentId !== undefined && { agent_id: patch.agentId }),
-                ...(patch.unboundPolicy !== undefined && { unbound_policy: patch.unboundPolicy }),
-                ...(patch.status !== undefined && { status: patch.status }),
-                ...(patch.inboundMode !== undefined && { inbound_mode: patch.inboundMode }),
-                ...(rotated && { config: JSON.stringify(rotated.plain) }),
-                // 跳过了 verify：机器人 id 与租户保留原值（重新启用后插件按新凭据连接，入站以连接行的租户判断外部人员）
-                ...(verified && { bot_user_id: verified.botUserId, tenant_id: verified.tenantId }),
-                ...((rotated || patch.status === "active") && { last_error: null }),
-                updated_at: sql `now()`,
-            })
-                .where("id", "=", id)
-                .where("org_id", "=", orgId)
-                .where("deleted_at", "is", null)
-                .returning(COLUMNS)
-                .executeTakeFirst();
-            if (!updated)
-                throw notFound();
-            await audit(t, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "channel.updated",
-                target: id,
-                detail: {
-                    changed: [
-                        ...Object.keys(patch).filter((k) => k !== "config" && patch[k] !== undefined),
-                        ...(rotated ? ["config"] : []),
-                    ],
-                },
-            });
-            return updated;
+            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-08-plugin-setup-guides-design.md §6)
+        const guideAck = modeChanged &&
+            patch.inboundMode !== undefined &&
+            !(await this.guides.ackDrifted(current.plugin, current.guide_ack ?? null))
+            ? await this.guides.currentAck(current.plugin, 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);
@@ -366,50 +463,153 @@ export class ChannelConnections {
         if (rotated ||
             patch.status === "active" ||
             (modeChanged && patch.inboundMode === "long_connection")) {
-            await this.deps.redis
+            await this.redis
                 .del(channelBackoffKey(id), channelFailsKey(id))
-                .catch((err) => this.deps.log.warn("cannot clear channel backoff", { err }));
+                .catch((err) => this.log.warn("cannot clear channel backoff", { err }));
         }
         // A mode switch also reconnects: the holder drops the long connection when going to webhook (F9)
         await this.changed(id, rotated !== undefined || patch.status !== undefined || modeChanged);
         if ((rotated || patch.status === "active") && row.status === "active") {
-            await this.deps
-                .onResume?.(id)
-                .catch((err) => this.deps.log.warn("cannot resume channel deliveries", { err }));
+            await this.jobs
+                .resumeConnection(id)
+                .catch((err) => this.log.warn("cannot resume channel deliveries", { err }));
         }
         return { channel: await this.viewOf(row), verifySkipped };
     }
-    /** 删除（软删除，同一事务删掉密钥）；持有长连接的副本收到广播后断开。 */
-    async remove(orgId, id, actorAccountId, actorTokenId) {
-        await this.deps.db.transaction().execute(async (t) => {
-            await lockOrgAndAuthorize(t, orgId, actorAccountId, "channels.manage");
-            const r = await t
-                .updateTable("channel_connections")
-                .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
-                .where("id", "=", id)
-                .where("org_id", "=", orgId)
-                .where("deleted_at", "is", null)
-                .executeTakeFirst();
-            if (r.numUpdatedRows === 0n)
-                throw notFound();
-            await createSecrets(t, this.deps.keyring, SECRETS_NAMESPACE).delete(orgId, connectionSecretKey(id));
-            await audit(t, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "channel.deleted",
-                target: id,
-            });
+    /** 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, auditDetail } = a;
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "channels.manage");
+        if (patch.agentId !== undefined)
+            await this.assertAgent(orgId, patch.agentId);
+        if (rotated) {
+            const secrets = createSecrets(this.db.db, this.keyring, SECRETS_NAMESPACE);
+            if (Object.keys(rotated.secrets).length > 0) {
+                await secrets.set(orgId, connectionSecretKey(id), JSON.stringify(rotated.secrets));
+            }
+            else {
+                await secrets.delete(orgId, connectionSecretKey(id));
+            }
+        }
+        const updated = await this.db
+            .updateTable("channel_connections")
+            .set({
+            ...(patch.name !== undefined && { name: patch.name }),
+            ...(patch.agentId !== undefined && { agent_id: patch.agentId }),
+            ...(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 }),
+            ...((rotated || patch.status === "active") && { last_error: null }),
+            updated_at: sql `now()`,
+        })
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .returning(COLUMNS)
+            .executeTakeFirst();
+        if (!updated)
+            throw notFound();
+        await audit(this.db.db, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "channel.updated",
+            target: id,
+            detail: {
+                changed: [
+                    ...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 template 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`.
+     */
+    async ackGuide(orgId, id, hash, actorAccountId, actorTokenId) {
+        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);
+        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, 
+    /** 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, auditDetail) {
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "channels.manage");
+        const r = await this.db
+            .updateTable("channel_connections")
+            .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (r.numUpdatedRows === 0n)
+            throw notFound();
+        await createSecrets(this.db.db, this.keyring, SECRETS_NAMESPACE).delete(orgId, connectionSecretKey(id));
+        await audit(this.db.db, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "channel.deleted",
+            target: id,
+            ...(auditDetail !== undefined && { detail: auditDetail }),
+        });
+    }
     /** 提交后广播；失败只记日志（持有方每轮续租时也会复核连接状态）。 */
     async changed(connectionId, reconnect) {
         try {
-            await this.deps.bus.publish(CHANNEL_CHANGED_TOPIC, { connectionId, reconnect });
+            await this.bus.publish(CHANNEL_CHANGED_TOPIC, { connectionId, reconnect });
         }
         catch (err) {
-            this.deps.log.warn("channel.changed publish failed", { connectionId, err });
+            this.log.warn("channel.changed publish failed", { connectionId, err });
         }
     }
     /**
@@ -417,10 +617,10 @@ export class ChannelConnections {
      * `pluginEnabled` 为插件此刻是否在该组织启用（入站与卡片操作每次都实时复核）。
      */
     async row(id) {
-        const r = await this.deps.db
+        const r = await this.db
             .selectFrom("channel_connections as c")
             .innerJoin("orgs", "orgs.id", "c.org_id")
-            .leftJoin(enabledExtensionsByOrg(this.deps.db).as("p"), (j) => j.onRef("p.plugin", "=", "c.plugin").onRef("p.org_id", "=", "c.org_id"))
+            .leftJoin(enabledExtensionsByOrg(this.db.db).as("p"), (j) => j.onRef("p.plugin", "=", "c.plugin").onRef("p.org_id", "=", "c.org_id"))
             .select([
             "c.id",
             "c.org_id",
@@ -453,7 +653,7 @@ export class ChannelConnections {
      * 持有长连接的副本立即断开（扫描复核只是兜底）。只广播，失败只记日志。
      */
     async notifyOrgChanged(orgId, plugin) {
-        let q = this.deps.db
+        let q = this.db.db
             .selectFrom("channel_connections")
             .select("id")
             .where("org_id", "=", orgId)
@@ -465,7 +665,7 @@ export class ChannelConnections {
             rows = await q.execute();
         }
         catch (err) {
-            this.deps.log.warn("cannot list channel connections to notify", { orgId, err });
+            this.log.warn("cannot list channel connections to notify", { orgId, err });
             return;
         }
         for (const r of rows)
@@ -485,7 +685,7 @@ export class ChannelConnections {
         const entry = this.channelEntry(row.plugin);
         const channel = entry.impl;
         await this.assertEnabled(row.orgId, row.plugin);
-        const stored = await this.deps.db
+        const stored = await this.db
             .selectFrom("channel_connections")
             .select("config")
             .where("id", "=", id)
@@ -504,31 +704,64 @@ export class ChannelConnections {
      */
     async outbound(connectionId) {
         const { row, channel, config } = await this.runtime(connectionId);
-        // 组织语言随每次发送 / 更新交给插件（Ruling A22）；本次会话内不变
-        const { locale } = await readOrgSettings(this.deps.db, row.orgId);
+        // 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([
+    Transactional({ propagation: "requires_new" })
+], ChannelConnections.prototype, "insertIn", null);
+__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);
+ChannelConnections = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(OrgLock)),
+    __param(2, Inject(KEYRING)),
+    __param(3, Inject(ExtensionRegistry)),
+    __param(4, Inject(KERNEL_BUS)),
+    __param(5, Inject(REDIS)),
+    __param(6, Inject(ChannelJobs)),
+    __param(7, Inject(KernelConfigService)),
+    __param(8, Inject(KernelEvents)),
+    __param(9, Inject(KERNEL_LOGGER)),
+    __param(10, Inject(TransactionHost)),
+    __param(11, Inject(PluginGuides))
+], ChannelConnections);
+export { ChannelConnections };