@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/channels/inbound.d.ts

@@ -0,0 +1,120 @@
+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 { type ChannelLocale, type ChannelPhrase } from "./phrases.js";
+/** 入站消息去重键的保留时长（秒）：平台在这段时间内重投同一条消息只处理一次。 */
+export declare const MESSAGE_DEDUPE_TTL_SECONDS = 86400;
+/** Dedupe key states: the enqueue is running (`pending`) or has succeeded (`done`). */
+export declare const DEDUPE_PENDING = "pending";
+export declare const DEDUPE_DONE = "done";
+/** A `pending` key outlives a crashed enqueuer only this long, then redeliveries enqueue again. */
+export declare const DEDUPE_PENDING_TTL_SECONDS = 60;
+/** 入站消息去重键（Redis 键，不是队列名 / job id，可以含 `:`）。 */
+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 小时去重，
+ *   再排一个入站任务（`inbound-<连接>-<消息 id 哈希>`）后返回；入队失败删掉去重键并抛错（插件不确认，平台重投）。
+ *   带 `eventId` 的卡片操作同样按 `capk:channel-act:<连接>:<eventId>` 去重（任务 id 由 eventId 哈希，Ruling A26），
+ *   不带的直接入队（任务 id 随机）；`directory_changed` 只是投递一个通讯录同步任务，就地完成。
+ *   返回即「内核已持久接收」：插件此后才向平台确认。
+ * - `handle`（worker 上执行入站任务）：失败抛错由 BullMQ 指数退避重试（共 5 次；插件在本副本未加载时推迟、
+ *   回复报 auth / target_gone 时不重试）；写用户消息带 `clientMessageId = "<连接>:<消息>"`，回复带由
+ *   `<连接>-<消息 id>-reply` 哈希的幂等键，重试不会重复写 / 重复回复。步骤：
+ * 1. 连接停用、所属组织已删除或插件在该组织停用 → 什么都不做；群聊未 @ 机器人 → 忽略；
+ * 2. 发言人按 `<插件>:<租户>` + externalId 纯查找账号（不建账号、不合并），且须是连接所属组织的活跃成员；
+ *    否则按连接的未绑定策略：`bind` → 私聊回绑定卡片（群里只提示去私聊，绑定链接不能发在群里）、
+ *    已绑定但非成员回提示；`anonymous` → 仅当绑定的 agent 全组织可见、且发言人与连接同一租户时用该组织的
+ *    匿名访客（外部租户的人只能绑定），否则回提示。识别不出发言人时绝不借用连接创建者或任何人的身份；
+ * 3. 私聊 `/new` → 归档当前对话行并回「已开始新对话」；
+ * 4. 按话题找或建会话，写用户消息，记下投递目标并投递出站任务（Task 11）。A message whose text
+ *    (bot mention stripped) is `/name args` is posted as a skill invocation (phase D spec §9): the
+ *    same kernel path as the web, so the skill is resolved among the connection's agent's skills
+ *    for the bound person; a refusal (`skill.not_invocable`: unknown, not user-invocable, gone
+ *    since; `validation_failed`: over the limits) posts the text as typed, so nothing is lost.
+ * `directory_changed` → 投递通讯录同步（Task 12）；`card_action` 见 actions.ts。
+ * 边界（已接受）：同一 chat 的连续消息由不同任务并发处理，极少数情况下写入顺序可能与平台顺序不同；
+ * 处理在写入用户消息之后失败而重试时，固定话术 / 卡片回复可能再发一次。
+ */
+export declare class ChannelInbound {
+    private readonly deps;
+    private readonly actions;
+    constructor(deps: ChannelInboundDeps);
+    /**
+     * 插件 `onEvent`：去重并入队后返回（见类注释）。返回后插件才向平台确认；抛错时插件不确认。
+     */
+    onEvent(connectionId: string, e: InboundEvent): Promise<void>;
+    /**
+     * Two-state dedupe, then enqueue (the key is `pending` while the enqueue runs, `done` after it):
+     * - fresh: `SET key pending NX EX 60`, enqueue, then `SET key done EX <dedupe TTL>`; on failure the
+     *   key is deleted only if still `pending` (compare-and-delete) and the error is rethrown, so the
+     *   plugin does not ack and the platform redelivers;
+     * - duplicate seeing `done`: already queued, return (the plugin acks);
+     * - duplicate seeing `pending` (the first enqueue is still running or hangs): enqueue again with the
+     *   same deterministic job id and return only once that succeeds, else throw. BullMQ `add` with an
+     *   existing job id is a no-op, and completed inbound jobs are retained (1 h / 1000), so this does
+     *   not create a second run; it means a redelivery is never acked before the job is really queued.
+     */
+    private dedupeAndEnqueue;
+    /** 入站任务的处理（worker 上执行；失败抛错由队列重试）。 */
+    handle(connectionId: string, e: InboundEvent): Promise<void>;
+    private message;
+    /**
+     * 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`
+     * either way (an invocation input returns the written event before resolving the skill).
+     * `skillNotRun`: the skill was found but refused with `validation_failed` (too long), so the
+     * person is told it did not run (batch 4 review m2); an unknown command stays silent.
+     */
+    private post;
+    /**
+     * 第 3 步：发言人（或卡片点击者）→ 账号。按 `<插件>:<租户>` + externalId 纯查找，且须是该组织的活跃成员；
+     * 否则按连接的未绑定策略回复（绑定卡片只发在私聊里）并返回 undefined。
+     * `threadAccount` 为话题行记的账号（匿名访客为 null）。
+     */
+    resolveSpeaker(connectionId: string, row: ChannelConnectionRow, sender: InboundSender, isGroup: boolean, locale: ChannelLocale, reply: (key: ChannelPhrase, cards?: ChannelCard[]) => Promise<void>): Promise<{
+        accountId: string;
+        threadAccount: string | null;
+    } | undefined>;
+    /** 账号是该组织成员且账号未停用。 */
+    private isActiveMember;
+    /** 连接绑定的 agent 未删除且可见范围为「全组织」（匿名访客只能用这种 agent）。 */
+    private agentVisibleToOrg;
+}

package/dist/channels/inbound.js

@@ -0,0 +1,332 @@
+import { randomUUID } from "node:crypto";
+import { ApiError } from "../errors.js";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { parseSlashCommand } from "../skills/invoke.js";
+import { ChannelCardActions } from "./actions.js";
+import { idempotencyKey, inboundJobId } from "./outbound.js";
+import { phrase } from "./phrases.js";
+import { archiveThread, ensureAnonymousGuest, 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`). */
+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 键，可以含 `:`）。 */
+export const actionDedupeKey = (connectionId, eventId) => `capk:channel-act:${connectionId}:${eventId}`;
+/**
+ * 渠道入站（Ruling A21：持久化处理）。
+ * - `onEvent`（插件 `connect` 的回调，必须快）：消息按 `capk:channel-msg:<连接>:<消息>` `SET NX` 24 小时去重，
+ *   再排一个入站任务（`inbound-<连接>-<消息 id 哈希>`）后返回；入队失败删掉去重键并抛错（插件不确认，平台重投）。
+ *   带 `eventId` 的卡片操作同样按 `capk:channel-act:<连接>:<eventId>` 去重（任务 id 由 eventId 哈希，Ruling A26），
+ *   不带的直接入队（任务 id 随机）；`directory_changed` 只是投递一个通讯录同步任务，就地完成。
+ *   返回即「内核已持久接收」：插件此后才向平台确认。
+ * - `handle`（worker 上执行入站任务）：失败抛错由 BullMQ 指数退避重试（共 5 次；插件在本副本未加载时推迟、
+ *   回复报 auth / target_gone 时不重试）；写用户消息带 `clientMessageId = "<连接>:<消息>"`，回复带由
+ *   `<连接>-<消息 id>-reply` 哈希的幂等键，重试不会重复写 / 重复回复。步骤：
+ * 1. 连接停用、所属组织已删除或插件在该组织停用 → 什么都不做；群聊未 @ 机器人 → 忽略；
+ * 2. 发言人按 `<插件>:<租户>` + externalId 纯查找账号（不建账号、不合并），且须是连接所属组织的活跃成员；
+ *    否则按连接的未绑定策略：`bind` → 私聊回绑定卡片（群里只提示去私聊，绑定链接不能发在群里）、
+ *    已绑定但非成员回提示；`anonymous` → 仅当绑定的 agent 全组织可见、且发言人与连接同一租户时用该组织的
+ *    匿名访客（外部租户的人只能绑定），否则回提示。识别不出发言人时绝不借用连接创建者或任何人的身份；
+ * 3. 私聊 `/new` → 归档当前对话行并回「已开始新对话」；
+ * 4. 按话题找或建会话，写用户消息，记下投递目标并投递出站任务（Task 11）。A message whose text
+ *    (bot mention stripped) is `/name args` is posted as a skill invocation (phase D spec §9): the
+ *    same kernel path as the web, so the skill is resolved among the connection's agent's skills
+ *    for the bound person; a refusal (`skill.not_invocable`: unknown, not user-invocable, gone
+ *    since; `validation_failed`: over the limits) posts the text as typed, so nothing is lost.
+ * `directory_changed` → 投递通讯录同步（Task 12）；`card_action` 见 actions.ts。
+ * 边界（已接受）：同一 chat 的连续消息由不同任务并发处理，极少数情况下写入顺序可能与平台顺序不同；
+ * 处理在写入用户消息之后失败而重试时，固定话术 / 卡片回复可能再发一次。
+ */
+export class ChannelInbound {
+    deps;
+    actions;
+    constructor(deps) {
+        this.deps = deps;
+        this.actions = new ChannelCardActions({
+            db: deps.db,
+            connections: deps.connections,
+            approvals: deps.approvals,
+            questions: deps.questions,
+            outbound: deps.outbound,
+            resolveSpeaker: (...args) => this.resolveSpeaker(...args),
+        });
+    }
+    /**
+     * 插件 `onEvent`：去重并入队后返回（见类注释）。返回后插件才向平台确认；抛错时插件不确认。
+     */
+    async onEvent(connectionId, e) {
+        if (e.type === "directory_changed")
+            return this.handle(connectionId, e);
+        if (e.type === "card_action") {
+            if (e.eventId === undefined) {
+                // 平台没给事件 id：无法识别重投，每次都处理（重复的审批 / 回答由服务回「已处理」）
+                await this.deps.queue.enqueueInbound(connectionId, e, `inbound-${connectionId}-a${randomUUID()}`);
+                return;
+            }
+            return this.dedupeAndEnqueue(connectionId, e, actionDedupeKey(connectionId, e.eventId), inboundJobId(connectionId, `act:${e.eventId}`));
+        }
+        return this.dedupeAndEnqueue(connectionId, e, messageDedupeKey(connectionId, e.messageId), inboundJobId(connectionId, e.messageId));
+    }
+    /**
+     * Two-state dedupe, then enqueue (the key is `pending` while the enqueue runs, `done` after it):
+     * - fresh: `SET key pending NX EX 60`, enqueue, then `SET key done EX <dedupe TTL>`; on failure the
+     *   key is deleted only if still `pending` (compare-and-delete) and the error is rethrown, so the
+     *   plugin does not ack and the platform redelivers;
+     * - duplicate seeing `done`: already queued, return (the plugin acks);
+     * - duplicate seeing `pending` (the first enqueue is still running or hangs): enqueue again with the
+     *   same deterministic job id and return only once that succeeds, else throw. BullMQ `add` with an
+     *   existing job id is a no-op, and completed inbound jobs are retained (1 h / 1000), so this does
+     *   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);
+            // 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")
+                return;
+        }
+        // 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);
+        }
+        catch (err) {
+            await redis.eval(DEL_IF_PENDING, 1, key, DEDUPE_PENDING).catch(() => { });
+            throw err;
+        }
+        await 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);
+            if (row?.status === "active" && row.pluginEnabled) {
+                await this.deps.directorySync.enqueue(row.orgId, row.plugin);
+            }
+            return;
+        }
+        if (e.type === "card_action") {
+            await this.actions.handle(connectionId, e);
+            return;
+        }
+        await this.message(connectionId, e);
+    }
+    async message(connectionId, e) {
+        const { db, connections } = this.deps;
+        const row = await connections.row(connectionId);
+        // 连接停用、组织已删除或插件在该组织停用（停用广播与长连接断开之间仍可能有事件到达）：什么都不做
+        if (row?.status !== "active" || !row.pluginEnabled)
+            return;
+        const isGroup = e.target.chatType === "group";
+        if (isGroup && !e.mentionsBot)
+            return;
+        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);
+        // 回复带幂等键：任务重试时平台不会重复显示（一条消息至多一句回复）
+        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 speaker = await this.resolveSpeaker(connectionId, row, e.sender, isGroup, locale, reply);
+        if (speaker === undefined)
+            return;
+        const { accountId, threadAccount } = speaker;
+        const k = {
+            connectionId,
+            chatId: e.target.chatId,
+            threadKey,
+            accountId: threadAccount,
+        };
+        if (!isGroup && e.text.trim().toLowerCase() === "/new") {
+            await archiveThread(db, k);
+            await reply("newConversation");
+            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;
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.code === "agent.not_found") {
+                    await reply("agentUnavailable");
+                    return;
+                }
+                throw err;
+            }
+            conversationId = await insertThread(db, k, created);
+            if (conversationId !== created) {
+                // 同一话题的另一条消息抢先建好了：删掉刚建、还没有任何事件的空会话
+                await db
+                    .deleteFrom("conversations")
+                    .where("id", "=", created)
+                    .where("last_seq", "=", "0")
+                    .execute();
+            }
+        }
+        let seq;
+        try {
+            const posted = await this.post(row.orgId, conversationId, accountId, {
+                text: e.text,
+                clientMessageId: `${connectionId}:${e.messageId}`,
+            });
+            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", {
+                    connectionId,
+                    messageId: e.messageId,
+                    err,
+                }));
+            }
+        }
+        catch (err) {
+            // agent 已对此人不可用（改了可见范围 / 已删除）：会话按不存在处理
+            if (err instanceof ApiError && err.code === "conversation.not_found") {
+                await reply("agentUnavailable");
+                return;
+            }
+            throw err;
+        }
+        await db
+            .insertInto("channel_deliveries")
+            .values({
+            conversation_id: conversationId,
+            connection_id: connectionId,
+            target: JSON.stringify(replyTarget),
+            last_seq: seq,
+        })
+            .onConflict((oc) => oc.column("conversation_id").doUpdateSet({
+            connection_id: connectionId,
+            target: JSON.stringify(replyTarget),
+            updated_at: new Date(),
+        }))
+            .execute();
+        await this.deps.outbound.enqueue(conversationId);
+    }
+    /**
+     * 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`
+     * either way (an invocation input returns the written event before resolving the skill).
+     * `skillNotRun`: the skill was found but refused with `validation_failed` (too long), so the
+     * person is told it did not run (batch 4 review m2); an unknown command stays silent.
+     */
+    async post(orgId, conversationId, accountId, input) {
+        const cmd = parseSlashCommand(input.text.trimStart());
+        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 } });
+                return { event, skillNotRun };
+            }
+            catch (err) {
+                if (!(err instanceof ApiError) ||
+                    (err.code !== "skill.not_invocable" && err.code !== "validation_failed")) {
+                    throw err;
+                }
+                if (err.code === "validation_failed") {
+                    skillNotRun = true;
+                    this.deps.log.info("IM skill invocation posted as text", {
+                        conversationId,
+                        skill: cmd.name,
+                        reason: err.message,
+                    });
+                }
+            }
+        }
+        const event = await this.deps.conversations.postUserMessage(orgId, conversationId, accountId, input);
+        return { event, skillNotRun };
+    }
+    /**
+     * 第 3 步：发言人（或卡片点击者）→ 账号。按 `<插件>:<租户>` + externalId 纯查找，且须是该组织的活跃成员；
+     * 否则按连接的未绑定策略回复（绑定卡片只发在私聊里）并返回 undefined。
+     * `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);
+        if (bound !== undefined && (await this.isActiveMember(row.orgId, bound))) {
+            return { accountId: bound, threadAccount: bound };
+        }
+        // 外部租户的人（外部联系人、共享频道里的其他企业，或连接还没有租户）只能绑定，不按匿名访客处理
+        const external = row.tenantId === null || sender.tenantId !== row.tenantId;
+        if (row.unboundPolicy === "anonymous" && !external) {
+            if (!(await this.agentVisibleToOrg(row.orgId, row.agentId))) {
+                await reply("anonymousNotAllowed");
+                return undefined;
+            }
+            return { accountId: await ensureAnonymousGuest(db, row.orgId), threadAccount: null };
+        }
+        if (bound !== undefined) {
+            await reply("notMember");
+            return undefined;
+        }
+        if (isGroup) {
+            await reply("bindInDm");
+            return undefined;
+        }
+        let url;
+        try {
+            url = await this.deps.binding.createBindToken({
+                connectionId,
+                identity: {
+                    source,
+                    externalId: sender.externalId,
+                    tenantId: sender.tenantId,
+                    emailVerified: false,
+                    // 绑定确认页显示平台给的显示名（没有时用 externalId）
+                    displayName: sender.displayName?.trim() || sender.externalId,
+                },
+            });
+        }
+        catch (err) {
+            this.deps.log.warn("cannot create channel bind link", { connectionId, err });
+            await reply("bindUnavailable");
+            return undefined;
+        }
+        await reply("bindPrompt", [{ kind: "bind", url, text: phrase("bindPrompt", locale) }]);
+        return undefined;
+    }
+    /** 账号是该组织成员且账号未停用。 */
+    async isActiveMember(orgId, accountId) {
+        const r = await this.deps.db
+            .selectFrom("memberships")
+            .innerJoin("accounts", "accounts.id", "memberships.account_id")
+            .select("memberships.role")
+            .where("memberships.org_id", "=", orgId)
+            .where("memberships.account_id", "=", accountId)
+            .where("accounts.status", "=", "active")
+            .executeTakeFirst();
+        return r !== undefined;
+    }
+    /** 连接绑定的 agent 未删除且可见范围为「全组织」（匿名访客只能用这种 agent）。 */
+    async agentVisibleToOrg(orgId, agentId) {
+        const r = await this.deps.db
+            .selectFrom("agents")
+            .select("id")
+            .where("id", "=", agentId)
+            .where("org_id", "=", orgId)
+            .where("visibility", "=", "org")
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return r !== undefined;
+    }
+}

package/dist/channels/outbound.d.ts

@@ -0,0 +1,140 @@
+import { type InboundEvent, type Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import type { KernelConfig } from "../config/schema.js";
+import { type EventLog } from "../conversations/event-log.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { StreamBus } from "../runtime/stream.js";
+import type { ApprovalsService } from "../tools/approvals.service.js";
+import type { QuestionsService } from "../tools/questions.service.js";
+import type { ChannelConnections } from "./connections.service.js";
+import type { ChannelOutboundScheduler } from "./inbound.js";
+import { type ChannelLocale } from "./phrases.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;
+/**
+ * 投递锁被占时怎么办：读不到持有者（刚被释放）→ 再取一次；是自己上一次（已崩溃、被 stalled 重新投递）的尝试 →
+ * 推迟重试等它过期；别的任务 → 直接结束（它会读到新事件，结束时还会复核）。
+ */
+export declare function busyLockAction(holder: string | null, owner: string): "retry" | "requeue" | "drop";
+/** 草稿收尾的方式：运行失败加失败说明、中止加「已停止」，其余不改草稿内容。 */
+export type DraftClosing = "failed" | "stopped" | "none";
+/**
+ * 收尾草稿时写入的文本：`failed` / `stopped` 为「已有文本 + 空行 + 说明」（不知道已有文本时只有说明）；
+ * `none` 返回 undefined（保留草稿原样，只清掉草稿 id）。
+ */
+export declare function closingText(prior: string | undefined, how: DraftClosing, locale: ChannelLocale): string | undefined;
+/** 按会话互斥的投递锁（Redis 键前缀；值为 `<job id>.<随机>`，TTL = `runtime.jobLockMs`）。 */
+export declare const DELIVER_LOCK_PREFIX = "capk:channel-deliver:";
+/** 草稿更新的最小间隔（毫秒）；渠道声明了更大的 `features.minEditIntervalMs` 时取后者。 */
+export declare const DRAFT_INTERVAL_MS = 1000;
+/** 可重试失败（限流、5xx、网络、超时）的总尝试次数。 */
+export declare const DELIVER_ATTEMPTS = 8;
+/** 同一事件不可重试地失败这么多次后跳过它（Ruling A14）。 */
+export declare const POISON_FAILURES = 3;
+/** 入站任务名。 */
+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;
+/** BullMQ 退避：平台给了等待时长就用它，否则指数退避。 */
+export declare function deliverBackoff(attemptsMade: number, err?: Error): number;
+export interface ChannelOutboundDeps {
+    db: KernelDb;
+    redis: Redis;
+    redisUrl: string;
+    bus: StreamBus;
+    eventLog: Pick<EventLog, "readAfter">;
+    connections: Pick<ChannelConnections, "outbound">;
+    approvals: Pick<ApprovalsService, "describe">;
+    questions: Pick<QuestionsService, "forCall">;
+    config: () => KernelConfig;
+    log: Pick<Logger, "error" | "warn" | "info">;
+    /** 入站任务的处理（worker 上执行 `ChannelInbound.handle`）；失败抛错由 BullMQ 重试。 */
+    inbound?: (connectionId: string, e: InboundEvent) => Promise<void>;
+}
+/**
+ * 渠道出站投递：把会话日志里 `channel_deliveries.last_seq` 之后的内容按序投到 IM。
+ * - 生产方（任意角色）：`enqueue(conversationId)` 投递 `deliver-<会话>-<当前 seq>` 任务（会话没有投递目标时什么都不做）。
+ *   内核在会话每次追加事件后都调用它（事件日志的 notify 钩子），运行开始时也调用。
+ * - Worker（只在 worker 角色）：每个任务先取按会话互斥的投递锁，订阅 `conv.<id>` 后补读日志；运行进入 waiting /
+ *   终态且日志读完，或追上后 `channels.deliveryIdleMs` 内没有新的总线消息，任务就结束（不长期占并发槽）。
+ *   锁被别的任务持有 → 本任务直接结束：持有者会读到新事件，且它结束时（释放锁之后）复核日志是否有新内容，有就再排一个任务；
+ *   锁被自己上一次（已崩溃的）尝试占着 → 推迟重试，等锁过期。
+ *   崩溃后 BullMQ stalled 机制把任务交给其他副本，从 `last_seq` 续投；每投递一个事件就在同一事务里推进 `last_seq`
+ *   并记下 IM 消息 id（草稿 id、卡片消息 id），已投递的不会重发。
+ *   审批 / 提问卡片在发送之前先记一行 `pending`（T5a），卡片一出现就被点击也能通过 Ruling A13 的核对；
+ *   推进 `last_seq` 的事务再补上消息 id、改为 `sent`。崩溃后续投的副本用同一个幂等键重发。
+ * 同一队列还承载入站任务（`inbound`，Ruling A21）：由 `enqueueInbound` 排入，worker 调用 `deps.inbound` 处理，
+ * 失败按 BullMQ 指数退避重试。
+ * 状态全部在 PG / Redis；进程内只有本任务自己的订阅、草稿节流时刻与等待定时器（本进程持有的资源）。
+ */
+export declare class ChannelOutbound implements ChannelOutboundScheduler {
+    private readonly d;
+    private queue;
+    private queueConn;
+    private worker;
+    private workerConn;
+    private closed;
+    /** 停机：进行中的任务在下一个检查点交还队列（由其他副本续投）。 */
+    private readonly stopping;
+    private readonly lock;
+    constructor(d: ChannelOutboundDeps);
+    /** 会话有 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>;
+    /** 启动 Worker（只在含 `worker` 角色的进程）。任务锁与 stalled 检测沿用运行队列的配置。 */
+    startWorker(): void;
+    close(): Promise<void>;
+    private getQueue;
+    private requeue;
+    private process;
+    /** 本副本没有加载连接的插件：推迟重试（不消耗重试次数），排队超过上限才放弃。 */
+    private pluginPending;
+    /**
+     * 入站任务：失败抛出由 BullMQ 重试；插件在本副本未加载 → 推迟重试（同出站）；回复时插件报凭据失效 /
+     * 目标已不存在 → 不重试（`UnrecoverableError`）。最后一次也失败时记错误日志（消息丢失，平台已确认过）。
+     */
+    private processInbound;
+    private deliver;
+    /** 会话日志当前的最后位置（会话不存在时 undefined）。 */
+    private lastSeq;
+    /** 日志比 `seen` 更新时再排一个任务。 */
+    private followUp;
+    /** 不可重试（或重试用尽）的发送失败：记连接 `last_error`（已打码）。 */
+    private recordError;
+}