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

package/dist/channels/channels.schemas.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+const Config = z.record(z.string().max(200), z.unknown());
+const Policy = z.enum(["bind", "anonymous"]);
+export const ChannelCreateSchema = z
+    .object({
+    plugin: z.string().min(1).max(214),
+    name: z.string().trim().min(1).max(100),
+    agentId: z.string().min(1).max(100),
+    config: Config,
+    unboundPolicy: Policy.optional(),
+})
+    .strict();
+export const ChannelPatchSchema = z
+    .object({
+    name: z.string().trim().min(1).max(100).optional(),
+    agentId: z.string().min(1).max(100).optional(),
+    unboundPolicy: Policy.optional(),
+    status: z.enum(["active", "disabled"]).optional(),
+    // webhook needs plugin support and channels.webhookBaseUrl (409 channel.webhook_unavailable)
+    inboundMode: z.enum(["long_connection", "webhook"]).optional(),
+    config: Config.optional(),
+})
+    .strict();
+/** 「我已更新应用」: the template hash of the setup guide the person was shown. */
+export const ChannelGuideAckSchema = z
+    .object({ hash: z.string().regex(/^[0-9a-f]{64}$/) })
+    .strict();
+export const ChannelPathParams = z.object({ connectionId: z.string().min(1).max(100) });
+export const CHANNEL_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/channels" },
+    { route: "GET /api/v1/orgs/:orgId/channels/:connectionId", params: ChannelPathParams },
+    {
+        route: "PATCH /api/v1/orgs/:orgId/channels/:connectionId",
+        params: ChannelPathParams,
+        body: ChannelPatchSchema,
+    },
+    { route: "DELETE /api/v1/orgs/:orgId/channels/:connectionId", params: ChannelPathParams },
+];

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

@@ -1,59 +1,66 @@
-import { z } from "zod";
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import type { z } from "zod";
 import type { JsonSchema } from "../extensions/config-json-schema.js";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+import { type ConnectionGuideState, PluginGuides, type SetupGuideRef } from "../extensions/plugin-guides.js";
+import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import type { ChannelConnections, ChannelConnectionView } from "./connections.service.js";
-declare const CreateBody: z.ZodObject<{
-    plugin: z.ZodString;
-    name: z.ZodString;
-    agentId: z.ZodString;
-    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    unboundPolicy: z.ZodOptional<z.ZodEnum<{
-        anonymous: "anonymous";
-        bind: "bind";
-    }>>;
-}, z.core.$strict>;
-declare const PatchBody: z.ZodObject<{
-    name: z.ZodOptional<z.ZodString>;
-    agentId: z.ZodOptional<z.ZodString>;
-    unboundPolicy: z.ZodOptional<z.ZodEnum<{
-        anonymous: "anonymous";
-        bind: "bind";
-    }>>;
-    status: z.ZodOptional<z.ZodEnum<{
-        active: "active";
-        disabled: "disabled";
-    }>>;
-    inboundMode: z.ZodOptional<z.ZodEnum<{
-        long_connection: "long_connection";
-        webhook: "webhook";
-    }>>;
-    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strict>;
+import { ChannelCreateSchema as CreateBody, ChannelGuideAckSchema as GuideAckBody, ChannelPatchSchema as PatchBody } from "./channels.schemas.js";
+import { ChannelConnections, type ChannelConnectionView } from "./connections.service.js";
+/**
+ * A connection as the org's pages show it: its plugin's display name (null when it has none) and
+ * the URL of its plugin's icon on the org's catalog route (null without one, or when the org may
+ * not see the plugin's catalog item; maintainer decision 2026-11-08), and its plugin's setup guide
+ * with the drift since the connection was set up (`setupGuide`, `guideDrift`; spec
+ * 2026-11-08-plugin-setup-guides-design.md §6).
+ */
+export type ChannelConnectionPage = ChannelConnectionView & ConnectionGuideState & {
+    pluginDisplayName: LocalizedName | null;
+    pluginIcon: string | null;
+};
 /**
  * 组织的渠道连接（`/api/v1/orgs/:orgId/channels`），全部需要 `channels.manage`（admin，仅限人）。
  * 响应只回显非密钥配置与密钥是否已设置。
  */
 export declare class ChannelConnectionsController {
     private readonly channels;
-    constructor(channels: ChannelConnections);
+    private readonly displayNames;
+    private readonly icons;
+    private readonly guides;
+    constructor(channels: ChannelConnections, displayNames: ExtensionDisplayNames, icons: PluginIcons, guides: PluginGuides);
+    /** The connections with their plugins' display names, icons and guides (batched reads). */
+    private withPlugins;
+    private withPlugin;
     list(org: OrgContext): Promise<{
-        channels: ChannelConnectionView[];
+        channels: ChannelConnectionPage[];
     }>;
-    schema(plugin: string): {
+    /**
+     * The connection form's JSON Schema, and where the plugin's setup guide is (`guide`, null when
+     * the plugin has none the org may see): 新建渠道 shows it once the plugin is picked.
+     */
+    schema(org: OrgContext, plugin: string): Promise<{
         plugin: string;
         schema: JsonSchema;
-    };
+        guide: Omit<SetupGuideRef, "version"> | null;
+    }>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
-        channel: ChannelConnectionView;
+        channel: ChannelConnectionPage;
     }>;
     get(org: OrgContext, id: string): Promise<{
-        channel: ChannelConnectionView;
+        channel: ChannelConnectionPage;
     }>;
     update(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof PatchBody>): Promise<{
-        channel: ChannelConnectionView;
+        channel: ChannelConnectionPage;
         verifySkipped: boolean;
     }>;
+    /**
+     * 「我已更新应用」: the person updated the platform app to the plugin's current setup guide
+     * (`{ hash }` of the guide shown) -> 200 `{ channel }`; 409 `channel.guide_changed` when the guide
+     * moved on since, 404 `catalog.guide_not_found` without a guide.
+     */
+    ackGuide(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof GuideAckBody>): Promise<{
+        channel: ChannelConnectionPage;
+    }>;
     remove(principal: Principal, org: OrgContext, id: string): Promise<void>;
 }
-export {};

package/dist/channels/connections.controller.js

@@ -7,62 +7,94 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, } from "@nestjs/common";
-import { z } from "zod";
-import { CHANNEL_CONNECTIONS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post } from "@nestjs/common";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+import { PluginGuides, } from "../extensions/plugin-guides.js";
+import { orgIconScope, PluginIcons } from "../extensions/plugin-icons.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
-const Config = z.record(z.string().max(200), z.unknown());
-const Policy = z.enum(["bind", "anonymous"]);
-const CreateBody = z
-    .object({
-    plugin: z.string().min(1).max(214),
-    name: z.string().trim().min(1).max(100),
-    agentId: z.string().min(1).max(100),
-    config: Config,
-    unboundPolicy: Policy.optional(),
-})
-    .strict();
-const PatchBody = z
-    .object({
-    name: z.string().trim().min(1).max(100).optional(),
-    agentId: z.string().min(1).max(100).optional(),
-    unboundPolicy: Policy.optional(),
-    status: z.enum(["active", "disabled"]).optional(),
-    // webhook needs plugin support and channels.webhookBaseUrl (409 channel.webhook_unavailable)
-    inboundMode: z.enum(["long_connection", "webhook"]).optional(),
-    config: Config.optional(),
-})
-    .strict();
+import { ChannelCreateSchema as CreateBody, ChannelGuideAckSchema as GuideAckBody, ChannelPatchSchema as PatchBody, } from "./channels.schemas.js";
+import { ChannelConnections } from "./connections.service.js";
+class ChannelCreateBody extends createZodDto(CreateBody, "ChannelCreateBody") {
+}
+class ChannelPatchBody extends createZodDto(PatchBody, "ChannelPatchBody") {
+}
+class ChannelGuideAckBody extends createZodDto(GuideAckBody, "ChannelGuideAckBody") {
+}
 /**
  * 组织的渠道连接（`/api/v1/orgs/:orgId/channels`），全部需要 `channels.manage`（admin，仅限人）。
  * 响应只回显非密钥配置与密钥是否已设置。
  */
 let ChannelConnectionsController = class ChannelConnectionsController {
     channels;
-    constructor(channels) {
+    displayNames;
+    icons;
+    guides;
+    constructor(channels, displayNames, icons, guides) {
         this.channels = channels;
+        this.displayNames = displayNames;
+        this.icons = icons;
+        this.guides = guides;
+    }
+    /** The connections with their plugins' display names, icons and guides (batched reads). */
+    async withPlugins(org, views) {
+        const plugins = views.map((v) => v.plugin);
+        const [names, icons, guides] = await Promise.all([
+            this.displayNames.many(plugins),
+            this.icons.many(plugins, orgIconScope(org)),
+            this.guides.connectionStates(views, org),
+        ]);
+        return views.map((v) => ({
+            ...v,
+            pluginDisplayName: names.get(v.plugin) ?? null,
+            pluginIcon: icons.get(v.plugin) ?? null,
+            setupGuide: guides.get(v.id)?.setupGuide ?? null,
+            guideDrift: guides.get(v.id)?.guideDrift ?? null,
+        }));
+    }
+    async withPlugin(org, view) {
+        const [page] = await this.withPlugins(org, [view]);
+        return page;
     }
     async list(org) {
-        return { channels: await this.channels.list(org.orgId) };
+        return { channels: await this.withPlugins(org, await this.channels.list(org.orgId)) };
     }
-    schema(plugin) {
-        return { plugin, schema: this.channels.jsonSchema(plugin) };
+    /**
+     * The connection form's JSON Schema, and where the plugin's setup guide is (`guide`, null when
+     * the plugin has none the org may see): 新建渠道 shows it once the plugin is picked.
+     */
+    async schema(org, plugin) {
+        const schema = this.channels.jsonSchema(plugin);
+        const g = (await this.guides.channelGuides([plugin], org)).get(plugin);
+        return { plugin, schema, guide: g ? { itemId: g.itemId, guideId: g.guideId } : null };
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
         return {
-            channel: await this.channels.create(org.orgId, body, p.account.id, patTokenId(p)),
+            channel: await this.withPlugin(org, await this.channels.create(org.orgId, body, p.account.id, patTokenId(p))),
         };
     }
     async get(org, id) {
-        return { channel: await this.channels.get(org.orgId, id) };
+        return { channel: await this.withPlugin(org, await this.channels.get(org.orgId, id)) };
     }
     async update(principal, org, id, body) {
         const p = requireUser(principal);
-        // verifySkipped：插件在该组织停用时轮换凭据不调用插件校验（重新启用后按新凭据连接）
-        return this.channels.update(org.orgId, id, body, p.account.id, patTokenId(p));
+        // verifySkipped: with the plugin off in the org, rotated credentials are not verified by the
+        // plugin (it connects with them once it is on again)
+        const r = await this.channels.update(org.orgId, id, body, p.account.id, patTokenId(p));
+        return { ...r, channel: await this.withPlugin(org, r.channel) };
+    }
+    /**
+     * 「我已更新应用」: the person updated the platform app to the plugin's current setup guide
+     * (`{ hash }` of the guide shown) -> 200 `{ channel }`; 409 `channel.guide_changed` when the guide
+     * moved on since, 404 `catalog.guide_not_found` without a guide.
+     */
+    async ackGuide(principal, org, id, body) {
+        const p = requireUser(principal);
+        const view = await this.channels.ackGuide(org.orgId, id, body.hash, p.account.id, patTokenId(p));
+        return { channel: await this.withPlugin(org, view) };
     }
     async remove(principal, org, id) {
         const p = requireUser(principal);
@@ -77,14 +109,15 @@ __decorate([
 __decorate([
     Get("schema/:plugin"),
     OrgAction("channels.manage"),
-    __param(0, Param("plugin"))
+    __param(0, CurrentOrg()),
+    __param(1, Param("plugin"))
 ], ChannelConnectionsController.prototype, "schema", null);
 __decorate([
     Post(),
     OrgAction("channels.manage"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, Body(new ZodPipe(CreateBody)))
+    __param(2, ZBody(ChannelCreateBody))
 ], ChannelConnectionsController.prototype, "create", null);
 __decorate([
     Get(":connectionId"),
@@ -98,8 +131,17 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("connectionId")),
-    __param(3, Body(new ZodPipe(PatchBody)))
+    __param(3, ZBody(ChannelPatchBody))
 ], ChannelConnectionsController.prototype, "update", null);
+__decorate([
+    Post(":connectionId/guide-ack"),
+    HttpCode(200),
+    OrgAction("channels.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectionId")),
+    __param(3, ZBody(ChannelGuideAckBody))
+], ChannelConnectionsController.prototype, "ackGuide", null);
 __decorate([
     Delete(":connectionId"),
     HttpCode(204),
@@ -110,6 +152,9 @@ __decorate([
 ], ChannelConnectionsController.prototype, "remove", null);
 ChannelConnectionsController = __decorate([
     Controller("api/v1/orgs/:orgId/channels"),
-    __param(0, Inject(CHANNEL_CONNECTIONS))
+    __param(0, Inject(ChannelConnections)),
+    __param(1, Inject(ExtensionDisplayNames)),
+    __param(2, Inject(PluginIcons)),
+    __param(3, Inject(PluginGuides))
 ], ChannelConnectionsController);
 export { ChannelConnectionsController };

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

@@ -1,11 +1,19 @@
-import { type Channel, type ChannelTarget, type ExtensionContext, type Logger, type OutboundMessage } from "@capybara-hq/plugin-sdk";
+import { type Channel, type ChannelTarget, type ExtensionContext, type OutboundMessage } from "@capybara-hq/plugin-sdk";
+import { type OnApplicationShutdown } from "@nestjs/common";
 import type { Redis } from "ioredis";
-import type { KernelConfig } from "../config/schema.js";
 import { type Keyring } from "../ctx/secrets.js";
-import type { KernelDb } from "../db/kernel-schema.js";
 import { type JsonSchema } from "../extensions/config-json-schema.js";
-import type { ExtensionHost } from "../extensions/host.js";
 import type { InflightTracker } from "../extensions/inflight.js";
+import { type GuideAck, PluginGuides } from "../extensions/plugin-guides.js";
+import { ExtensionRegistry } from "../extensions/registry.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 { KernelEvents } from "../infra/events/kernel-events.js";
+import { type KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { ChannelJobs } from "./jobs.js";
+import type { ChannelLocale } from "./phrases.js";
 /** 连接配置里全部密钥字段存成一行：`{ 点路径: 值 }` 的 JSON。 */
 export declare const connectionSecretKey: (connectionId: string) => string;
 /**
@@ -40,6 +48,11 @@ export interface ChannelConnectionView {
     lastError: string | null;
     botUserId: string | null;
     tenantId: string | null;
+    /**
+     * The plugin's setup guide the connection was last set up with (recorded on create, on a mode
+     * switch and by `guide-ack`); null when unknown.
+     */
+    guideAck: GuideAck | null;
     config: Record<string, unknown>;
     secrets: {
         path: string;
@@ -78,36 +91,65 @@ export interface UpdateChannelInput {
     inboundMode?: InboundMode | undefined;
     config?: Record<string, unknown> | undefined;
 }
-export interface ChannelConnectionsDeps {
-    db: KernelDb;
-    keyring: Keyring;
-    host: Pick<ExtensionHost, "list">;
-    bus: ExtensionContext["bus"];
-    redis: Redis;
-    log: Pick<Logger, "warn">;
-    /** 连接重新可投递（轮换凭据 / 重新启用）后调用；内核传出站的 `resumeConnection`（补投落下的会话）。 */
-    onResume?: (connectionId: string) => Promise<void>;
-    /** 经手（写入或解密读出）的密钥值；内核传 `log.addOrgSecrets` 使其在日志中打码。 */
-    onSecrets?: (values: string[]) => void;
-    /** Current config (`channels.webhookBaseUrl`); without it webhook mode is unavailable. */
-    config?: () => Pick<KernelConfig, "channels" | "tools">;
-}
 /**
  * 组织的渠道连接（spec：渠道连接属于组织，bot 凭据 + 绑定的 agent）。框架无关。
  * 非密钥配置存 `channel_connections.config`；密钥字段整体加密存 `capybara.secrets`
  * （命名空间 `kernel`，键 `channels:<id>:config`）。写操作在组织行锁内实时复核 `channels.manage`，写审计；
  * 改动提交后经内核 bus 广播 `channel.changed`，持有该连接的副本据此断开（下一轮扫描按新配置重连）。
  */
-export declare class ChannelConnections {
-    private readonly deps;
-    constructor(deps: ChannelConnectionsDeps);
+export declare class ChannelConnections implements OnApplicationShutdown {
+    private readonly db;
+    /** The org row lock (orgs/org-lock.ts): joins the transaction of the write. */
+    private readonly orgLock;
+    private readonly keyring;
+    private readonly registry;
+    private readonly bus;
+    private readonly redis;
+    /** A connection that can deliver again catches up its conversations (`resumeConnection`). */
+    private readonly jobs;
+    /** `channels.webhookBaseUrl`: without it webhook mode is unavailable. */
+    private readonly config;
+    /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
+    private readonly log;
+    readonly txHost: TransactionHost;
+    /** The setup guide acks (spec 2026-11-08-plugin-setup-guides-design.md §6). */
+    private readonly guides;
+    private readonly unsubscribe;
+    /** `<plugin>@<version>` whose invalid connection hints were warned about (a log dedupe only). */
+    private readonly hintsWarned;
+    constructor(db: KernelDb, 
+    /** The org row lock (orgs/org-lock.ts): joins the transaction of the write. */
+    orgLock: Pick<OrgLock, "lockAndAuthorize">, keyring: Keyring, registry: Pick<ExtensionRegistry, "list">, bus: ExtensionContext["bus"], redis: Pick<Redis, "del">, 
+    /** A connection that can deliver again catches up its conversations (`resumeConnection`). */
+    jobs: Pick<ChannelJobs, "resumeConnection">, 
+    /** `channels.webhookBaseUrl`: without it webhook mode is unavailable. */
+    config: Pick<KernelConfigService, "get">, events: Pick<KernelEvents, "on">, 
+    /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
+    log: Pick<KernelLogger, "warn" | "addOrgSecrets">, txHost: TransactionHost, 
+    /** The setup guide acks (spec 2026-11-08-plugin-setup-guides-design.md §6). */
+    guides: Pick<PluginGuides, "currentAck" | "ackDrifted">);
+    /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
+    onApplicationShutdown(): void;
     /** The extension's `channel@1`; not loaded or not provided -> `extension.not_found`. */
     channel(plugin: string): Channel;
     private channelEntry;
     /** The extension is not enabled in this organization -> `extension.not_enabled`. */
     private assertEnabled;
-    /** `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: string): JsonSchema;
+    /**
+     * 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.
+     */
+    private formSchema;
+    /** The loaded version of a channel extension, for warnings ("unknown" when not provided). */
+    private versionOf;
     private parse;
     private verify;
     private reportSecrets;
@@ -126,16 +168,37 @@ export declare class ChannelConnections {
     get(orgId: string, id: string): Promise<ChannelConnectionView>;
     /** 新建：插件须提供 channel@1 且在该组织启用；配置按 `connectionSchema` 校验；先 `verify`，失败不落库。 */
     create(orgId: string, input: CreateChannelInput, actorAccountId: string, actorTokenId?: string): Promise<ChannelConnectionView>;
+    /** The rows of {@link create}, in their own transaction (the caller publishes after the commit). */
+    private insertIn;
+    /** The read-only refusals of {@link update} that need no write (the Platform tool's precheck). */
+    checkUpdate(orgId: string, id: string, patch: UpdateChannelInput): Promise<void>;
     /**
      * 修改名称、agent、未绑定策略、启停，或轮换凭据（新配置同样先 `verify`，失败什么都不改）。
      * 插件在该组织停用时仍可轮换凭据，此时不 verify，返回 `verifySkipped: true`。
      */
-    update(orgId: string, id: string, patch: UpdateChannelInput, actorAccountId: string, actorTokenId?: string): Promise<{
+    update(orgId: string, id: string, patch: UpdateChannelInput, actorAccountId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<{
         channel: ChannelConnectionView;
         verifySkipped: boolean;
     }>;
+    /** The rows of {@link update}, in their own transaction (the caller publishes after the commit). */
+    private updateIn;
+    /**
+     * 「我已更新应用」: records the plugin's current channel-connection guide for the connection's
+     * mode as the one it is set up with. `hash` is the template hash of the guide the person was
+     * 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`.
+     */
+    ackGuide(orgId: string, id: string, hash: string, actorAccountId: string, actorTokenId?: string): Promise<ChannelConnectionView>;
+    /** The row of {@link ackGuide}, in its own transaction. */
+    private ackIn;
     /** 删除（软删除，同一事务删掉密钥）；持有长连接的副本收到广播后断开。 */
-    remove(orgId: string, id: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    remove(orgId: string, id: string, actorAccountId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<void>;
+    /** The rows of {@link remove}, in their own transaction (the caller publishes after the commit). */
+    private removeIn;
     /** 提交后广播；失败只记日志（持有方每轮续租时也会复核连接状态）。 */
     private changed;
     /**
@@ -168,8 +231,12 @@ export declare class ChannelConnections {
      * `redact` 按该连接的密钥打码（插件异常信息写进 `last_error` 前使用）。
      */
     outbound(connectionId: string): Promise<ChannelOutboundSession>;
-    /** 经连接的插件直接发一条消息（入站处理回绑定卡片、固定话术，卡片操作回说明）；`idempotencyKey` 原样交给插件。 */
-    send(connectionId: string, target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string): Promise<{
+    /**
+     * 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).
+     */
+    send(connectionId: string, target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string, locale?: ChannelLocale): Promise<{
         messageId: string;
     }>;
 }
@@ -178,10 +245,14 @@ export interface ChannelOutboundSession {
     row: ChannelConnectionRow;
     features: Channel["features"];
     redact: (s: string) => string;
-    /** `idempotencyKey` 原样交给插件（见 `ChannelSendArgs.idempotencyKey`）。 */
-    send(target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string): Promise<{
+    /**
+     * `idempotencyKey` is passed through (see `ChannelSendArgs.idempotencyKey`); `locale` is the
+     * recipient's language for the extension's own wording and the card text fallback (default: the
+     * org's).
+     */
+    send(target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string, locale?: ChannelLocale): Promise<{
         messageId: string;
     }>;
-    /** 只在 `features.edit` 为 true 时调用。 */
-    update(target: ChannelTarget, messageId: string, message: OutboundMessage, idempotencyKey?: string): Promise<void>;
+    /** Called only when `features.edit` is true; `locale` as for `send`. */
+    update(target: ChannelTarget, messageId: string, message: OutboundMessage, idempotencyKey?: string, locale?: ChannelLocale): Promise<void>;
 }