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

package/dist/channels/phrases.d.ts

@@ -0,0 +1,100 @@
+/** 组织默认语言（`orgs.settings.locale`）。 */
+export type ChannelLocale = "zh" | "en";
+/**
+ * 机器人在 IM 里说的固定话术（全部集中在这里，zh / en 同步）：按连接所属组织的默认语言选择。
+ * 模型回复不经过这里，原样转换为 IM 富文本、不翻译。
+ */
+export declare const CHANNEL_PHRASES: {
+    /** 私聊 `/new` 之后。 */
+    readonly newConversation: {
+        readonly zh: "已开始新对话";
+        readonly en: "Started a new conversation.";
+    };
+    /** 未绑定的人在私聊里发消息：附绑定卡片。 */
+    readonly bindPrompt: {
+        readonly zh: "请先绑定你的 Capybara 账号，再与我对话。";
+        readonly en: "Please link your Capybara account before chatting with me.";
+    };
+    /** 未绑定的人在群里 @ 机器人：绑定链接只在私聊里发（群里谁都能点）。 */
+    readonly bindInDm: {
+        readonly zh: "请先私聊我，绑定你的 Capybara 账号。";
+        readonly en: "Please send me a direct message to link your Capybara account first.";
+    };
+    /** 无法生成绑定链接（部署未配置 http.publicUrl）。 */
+    readonly bindUnavailable: {
+        readonly zh: "暂时无法识别你的身份，请联系管理员。";
+        readonly en: "I can't identify you yet. Please contact an administrator.";
+    };
+    /** 已绑定账号但不是该组织成员。 */
+    readonly notMember: {
+        readonly zh: "你的账号不是该组织的成员，请联系管理员。";
+        readonly en: "Your account is not a member of this organization. Please contact an administrator.";
+    };
+    /** 匿名策略下，连接绑定的 agent 不是全组织可见。 */
+    readonly anonymousNotAllowed: {
+        readonly zh: "此助手不对匿名访客开放，请联系管理员。";
+        readonly en: "This assistant is not available to anonymous guests. Please contact an administrator.";
+    };
+    /** 连接绑定的 agent 对此人不可用（可见范围不含此人、已删除）。 */
+    readonly agentUnavailable: {
+        readonly zh: "你无权使用此助手，请联系管理员。";
+        readonly en: "You don't have access to this assistant. Please contact an administrator.";
+    };
+    /** 卡片操作：点击者不是审批人 / 不是提问的发起人（或请求不在该组织）。 */
+    readonly cannotHandle: {
+        readonly zh: "你不能处理这条请求。";
+        readonly en: "You can't handle this request.";
+    };
+    /** 卡片操作：请求已被处理、已过期或已取消。 */
+    readonly alreadyHandled: {
+        readonly zh: "这条请求已经处理过了。";
+        readonly en: "This request has already been handled.";
+    };
+    /** 卡片操作：回答不符合表单，或审批范围不允许。 */
+    readonly invalidAction: {
+        readonly zh: "无法完成这个操作，请到网页上处理。";
+        readonly en: "That action isn't valid here. Please handle it on the web.";
+    };
+    /** 审批卡片的标题与随附文本。 */
+    readonly approvalTitle: {
+        readonly zh: "需要你的批准";
+        readonly en: "Approval required";
+    };
+    /** 提问卡片的随附文本。 */
+    readonly questionTitle: {
+        readonly zh: "需要你的回答";
+        readonly en: "Your input is needed";
+    };
+    /** 连接卡片的随附文本。 */
+    readonly connectTitle: {
+        readonly zh: "需要先完成连接器授权";
+        readonly en: "A connector needs to be connected first";
+    };
+    /** 部署未配置 http.publicUrl，无法给出网页链接与卡片时的退回文本。 */
+    readonly handleOnWeb: {
+        readonly zh: "有一条请求需要你到 Capybara 网页上处理。";
+        readonly en: "A request is waiting for you in Capybara on the web.";
+    };
+    /**
+     * Phase D: `/name args` named an invocable skill, but the kernel refused to render it
+     * (`validation_failed`: arguments or the rendered skill over the limits); the message was posted
+     * as typed instead (batch 4 review m2).
+     */
+    readonly skillNotRun: {
+        readonly zh: "技能没有运行：参数或技能内容过长。你的消息已按普通文本发送。";
+        readonly en: "The skill was not run: its arguments or instructions are too long. Your message was sent as plain text.";
+    };
+    /** 运行被中止（收尾挂着的草稿时附在已有文本之后）。 */
+    readonly runStopped: {
+        readonly zh: "已停止。";
+        readonly en: "Stopped.";
+    };
+    /** 运行失败。 */
+    readonly runFailed: {
+        readonly zh: "抱歉，出错了，请稍后再试。";
+        readonly en: "Sorry, something went wrong. Please try again later.";
+    };
+};
+export type ChannelPhrase = keyof typeof CHANNEL_PHRASES;
+/** 取一条话术。 */
+export declare function phrase(key: ChannelPhrase, locale: ChannelLocale): string;

package/dist/channels/phrases.js

@@ -0,0 +1,81 @@
+/**
+ * 机器人在 IM 里说的固定话术（全部集中在这里，zh / en 同步）：按连接所属组织的默认语言选择。
+ * 模型回复不经过这里，原样转换为 IM 富文本、不翻译。
+ */
+export const CHANNEL_PHRASES = {
+    /** 私聊 `/new` 之后。 */
+    newConversation: { zh: "已开始新对话", en: "Started a new conversation." },
+    /** 未绑定的人在私聊里发消息：附绑定卡片。 */
+    bindPrompt: {
+        zh: "请先绑定你的 Capybara 账号，再与我对话。",
+        en: "Please link your Capybara account before chatting with me.",
+    },
+    /** 未绑定的人在群里 @ 机器人：绑定链接只在私聊里发（群里谁都能点）。 */
+    bindInDm: {
+        zh: "请先私聊我，绑定你的 Capybara 账号。",
+        en: "Please send me a direct message to link your Capybara account first.",
+    },
+    /** 无法生成绑定链接（部署未配置 http.publicUrl）。 */
+    bindUnavailable: {
+        zh: "暂时无法识别你的身份，请联系管理员。",
+        en: "I can't identify you yet. Please contact an administrator.",
+    },
+    /** 已绑定账号但不是该组织成员。 */
+    notMember: {
+        zh: "你的账号不是该组织的成员，请联系管理员。",
+        en: "Your account is not a member of this organization. Please contact an administrator.",
+    },
+    /** 匿名策略下，连接绑定的 agent 不是全组织可见。 */
+    anonymousNotAllowed: {
+        zh: "此助手不对匿名访客开放，请联系管理员。",
+        en: "This assistant is not available to anonymous guests. Please contact an administrator.",
+    },
+    /** 连接绑定的 agent 对此人不可用（可见范围不含此人、已删除）。 */
+    agentUnavailable: {
+        zh: "你无权使用此助手，请联系管理员。",
+        en: "You don't have access to this assistant. Please contact an administrator.",
+    },
+    /** 卡片操作：点击者不是审批人 / 不是提问的发起人（或请求不在该组织）。 */
+    cannotHandle: { zh: "你不能处理这条请求。", en: "You can't handle this request." },
+    /** 卡片操作：请求已被处理、已过期或已取消。 */
+    alreadyHandled: {
+        zh: "这条请求已经处理过了。",
+        en: "This request has already been handled.",
+    },
+    /** 卡片操作：回答不符合表单，或审批范围不允许。 */
+    invalidAction: {
+        zh: "无法完成这个操作，请到网页上处理。",
+        en: "That action isn't valid here. Please handle it on the web.",
+    },
+    /** 审批卡片的标题与随附文本。 */
+    approvalTitle: { zh: "需要你的批准", en: "Approval required" },
+    /** 提问卡片的随附文本。 */
+    questionTitle: { zh: "需要你的回答", en: "Your input is needed" },
+    /** 连接卡片的随附文本。 */
+    connectTitle: { zh: "需要先完成连接器授权", en: "A connector needs to be connected first" },
+    /** 部署未配置 http.publicUrl，无法给出网页链接与卡片时的退回文本。 */
+    handleOnWeb: {
+        zh: "有一条请求需要你到 Capybara 网页上处理。",
+        en: "A request is waiting for you in Capybara on the web.",
+    },
+    /**
+     * Phase D: `/name args` named an invocable skill, but the kernel refused to render it
+     * (`validation_failed`: arguments or the rendered skill over the limits); the message was posted
+     * as typed instead (batch 4 review m2).
+     */
+    skillNotRun: {
+        zh: "技能没有运行：参数或技能内容过长。你的消息已按普通文本发送。",
+        en: "The skill was not run: its arguments or instructions are too long. Your message was sent as plain text.",
+    },
+    /** 运行被中止（收尾挂着的草稿时附在已有文本之后）。 */
+    runStopped: { zh: "已停止。", en: "Stopped." },
+    /** 运行失败。 */
+    runFailed: {
+        zh: "抱歉，出错了，请稍后再试。",
+        en: "Sorry, something went wrong. Please try again later.",
+    },
+};
+/** 取一条话术。 */
+export function phrase(key, locale) {
+    return CHANNEL_PHRASES[key][locale];
+}

package/dist/channels/supervisor.d.ts

@@ -0,0 +1,182 @@
+import type { ExtensionContext, InboundEvent, Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import { type ChannelConnections } from "./connections.service.js";
+/** 长连接租约键（内核锁）：值为持有方的随机 token。 */
+export declare const channelLeaseKey: (connectionId: string) => string;
+/**
+ * Gateway heartbeats, one ZSET per channel plugin (Ruling R3): members are process replica ids of the
+ * gateways that have that plugin loaded, scores the Redis server time (ms) of the member's last
+ * lease-renewal round. Live = score > server now - `leaseTtlMs`. Per plugin, so a gateway that cannot
+ * load a plugin does not count toward that plugin's share.
+ */
+export declare const gatewayReplicasKey: (plugin: string) => string;
+/** Bus topic published after an over-share replica handed a connection back (claim-only nudge). */
+export declare const CHANNEL_HANDOFF_TOPIC = "channel.handoff";
+/**
+ * Handoff marker written when an over-share replica gives a connection back: value = that replica's
+ * id, PX = 2 x `scanIntervalMs`. The releasing replica does not claim the connection while it exists.
+ */
+export declare const channelHandoffKey: (connectionId: string) => string;
+/** Rate-limit key of the "no live gateway" warning (one line per check interval, cluster-wide). */
+export declare const gatewayMissingWarnedKey = "capk:gateway-missing-warned";
+/**
+ * Upper bound of the connections one gateway replica holds: `ceil(runnable / live) + slack`, with
+ * `live < 1` treated as 1. With `rank` (this replica's index among the live replicas sorted by id)
+ * the remainder goes to the lowest ranks only, so the per-replica targets add up to exactly
+ * `runnable + live * slack`: with slack 0, 4 connections on 3 replicas split 2 / 1 / 1 instead of
+ * leaving a newcomer with nothing next to two replicas that each sit at the ceiling. Rank 0 (the
+ * default) gets the full ceiling.
+ */
+export declare function shareTarget(runnable: number, live: number, slack: number, rank?: number): number;
+/** Live heartbeat members of each plugin (Redis server clock). */
+export declare function liveGateways(redis: Redis, plugins: string[], ttlMs: number): Promise<Map<string, string[]>>;
+export interface ChannelSupervisorDeps {
+    db: KernelDb;
+    redis: Redis;
+    bus: ExtensionContext["bus"];
+    connections: Pick<ChannelConnections, "runtime">;
+    /** 本进程已加载、提供 `channel@1` 的插件名（内核传 `host.list("channel")`）。 */
+    localPlugins: () => string[];
+    onEvent(connectionId: string, e: InboundEvent): Promise<void>;
+    config: () => Pick<KernelConfig, "channels">;
+    log: Pick<Logger, "warn" | "error">;
+    /**
+     * This process's replica id (`newReplicaId()` in kernel.ts), the member of the gateway heartbeat
+     * ZSET. Not `http.replicaId`, which is optional and may repeat across replicas.
+     */
+    replicaId: string;
+    /** Called at the start of every scan round (`claimOnly` for handoff nudges); for tests / metrics. */
+    onScan?: (claimOnly: boolean) => void;
+}
+/**
+ * 渠道长连接选主（runs only on the gateway role）。每个副本两个各自独立的循环，周期都是 `channels.scanIntervalMs`（默认 10s）：
+ * - 续租循环：为本进程持有的连接续租（`capk:channel-lease:<id>`，TTL `channels.leaseTtlMs` 默认 30s）。
+ *   它不做任何可能慢的事（不等交还、不查库），一个插件迟迟不退出不会拖慢其他连接的续租。
+ * - 扫描循环：复核持有的连接仍为 active、未删除且插件在该组织启用（不满足就交还，交还不阻塞本轮），
+ *   再扫描无人持有的这类连接，`SET NX PX` 取到租约的副本调用插件 `connect`（传 `signal`）。
+ * 续租失败（租约已丢）→ 立即中止，不释放（已不是自己的）；Redis 出错时，自上次续租成功起满 `TTL - 扫描周期`
+ * 仍续不上就按丢失处理（赶在租约可能被别的副本拿走之前断开）。连接被停用 / 删除 / 改配置（内核 bus `channel.changed`，
+ * 或扫描时复核发现）→ 中止、等 `connect` 返回后释放租约，下一轮任一副本按新配置重连；取得租约到 `connect` 开始之间
+ * 收到的重连广播会被记下，开始后立即交还。
+ * `connect` 抛错或提前返回 → 记 `last_error`，在 Redis 写退避标记（指数退避，上限 5 分钟），释放租约后由任一副本重试。
+ * Fair share (E11-B): the renewal loop also writes this replica's heartbeat into `capk:gateway-replicas`;
+ * each scan computes this replica's target from the runnable count and the live replicas
+ * (`shareTarget`), stops claiming at the target and, when above it, gives back one connection per
+ * round (the most recently connected) with a handoff marker. Exactly one holder per connection is
+ * still guaranteed by the lease alone; the share only decides who claims.
+ * 停机时中止全部长连接并释放租约，并等进行中的 `onEvent`（入队）结束。持有的长连接、租约 token 与定时器都是「本进程持有的资源」，
+ * 跨副本的状态（租约、退避、失败计数）都在 Redis。
+ */
+export declare class ChannelSupervisor {
+    private readonly deps;
+    private readonly held;
+    /** 已取得租约、正在读配置准备 `connect` 的连接；值为期间是否收到了重连广播。 */
+    private readonly connecting;
+    /** 正在交还（已中止、等 `connect` 返回）的连接 → 租约 token：等待期间照常续租，交还完成才释放。 */
+    private readonly settling;
+    /** 进行中的交还（`stop()` 要等它们全部结束）。 */
+    private readonly releasing;
+    /** 进行中的 `onEvent`（去重 + 入队，很快）：`stop()` 等它们结束，插件才不会在内核关闭队列之后才拿到结果。 */
+    private readonly inflight;
+    private readonly loops;
+    private stopped;
+    private unsubscribe;
+    private unsubscribeHandoff;
+    /** Scans run one at a time (periodic and nudged), so share counts are never raced. */
+    private scanChain;
+    /** Plugins this replica heartbeats for (to ZREM when a plugin goes away and on stop). */
+    private heartbeated;
+    /** A claim-only scan is queued and has not started yet: further nudges until then are dropped. */
+    private claimQueued;
+    constructor(deps: ChannelSupervisorDeps);
+    start(): Promise<void>;
+    /** Runs `fn` after any scan in progress. */
+    private exclusive;
+    /** 周期循环：上一轮结束后隔 `scanIntervalMs` 再跑下一轮；首轮立即执行。 */
+    private loop;
+    private renewAll;
+    /**
+     * Writes this replica's heartbeat into the ZSET of every channel plugin loaded here (trimming
+     * members older than one TTL; the keys expire too) and leaves the ZSETs of plugins no longer
+     * loaded. Uses the Redis server clock.
+     */
+    private heartbeat;
+    /**
+     * This replica's share target per plugin for the round. Live replicas of a plugin are its
+     * heartbeat members newer than one TTL plus this replica itself (its own heartbeat may not be
+     * written yet on the first round).
+     */
+    private targets;
+    private heldOf;
+    /**
+     * Gives back the most recently connected connection of `plugin`, leaving a handoff marker first;
+     * once its lease is released, nudges the other replicas to claim it.
+     */
+    private handOff;
+    /** After-release callback: tells the other replicas a connection of `plugin` is free to claim. */
+    private nudge;
+    private afterRenew;
+    /**
+     * 可以持有的连接：active、未删除、所属组织未删除、插件在该组织启用（组织停用插件 / 删除组织时持有方据此断开），
+     * 且插件在本进程已加载——滚动升级期间还没有该插件的副本根本不考虑它（不取租约、不记失败），留给有插件的副本。
+     */
+    private runnable;
+    /**
+     * 持有的连接仍须可持有（bus 广播是尽力而为，这里兜底）。交还不等待：交还要等插件 `connect` 返回（至多 SETTLE_MS），
+     * 不能让一个迟迟不退出的插件拖住扫描。
+     */
+    private recheckHeld;
+    /**
+     * One scan round, per channel plugin (Ruling R3): above that plugin's share, give back one of its
+     * connections (never more, so this replica does not drop below its target) and claim none of it;
+     * otherwise claim unheld ones up to the target. `claimOnly` (a handoff nudge) never gives back.
+     */
+    private scan;
+    /** 已取得租约：读配置并在后台跑插件的 `connect`。 */
+    private connect;
+    /** 记下进行中的 `onEvent`，原样返回（结果与异常都交给插件）。 */
+    private track;
+    /** 记录失败：`last_error`、连续失败计数与退避标记（都跨副本可见）。 */
+    private failed;
+    /** 租约已丢：中止，不释放（已不是自己的）。 */
+    private drop;
+    /** 后台交还，记入 `releasing` 供 `stop()` 等待；`after` runs once the lease is released. */
+    private releaseInBackground;
+    /** 主动交还：中止，等 `connect` 返回（至多 SETTLE_MS）后释放租约；超时则让租约自然过期，避免两边同时在线。 */
+    private release;
+    private releaseLease;
+    /**
+     * 本进程的插件实例变了（撤销、替换为新实例；内核接 `host.onChange`，C17）：交还该插件持有的全部长连接
+     * （中止旧实例的 `connect`、等它返回后释放租约）。插件仍在本进程（新实例）时，下一轮扫描由任一副本按新实例重新选主；
+     * 已撤销则本副本不再考虑它（`localPlugins` 里没有了）。
+     */
+    pluginChanged(plugin: string): void;
+    /** 停机：停止扫描，中止全部长连接并释放租约。幂等。 */
+    stop(): Promise<void>;
+}
+/** Maintenance job that warns when channel connections need a gateway and none is live (Ruling R1). */
+export declare const GATEWAY_CHECK_JOB = "channel-gateway-check";
+export declare const GATEWAY_CHECK_SCHEDULER_ID = "channel-gateway-check-every";
+export declare const GATEWAY_CHECK_EVERY_MS = 60000;
+/**
+ * Runs on the worker role (maintenance queue), per channel plugin (Ruling R3): when a plugin has
+ * active connections (not deleted, org not deleted, plugin enabled for the org; long connection or
+ * webhook mode, Ruling R4) but no gateway replica with that plugin loaded has a heartbeat newer than
+ * one lease TTL (Redis server clock), nobody holds those long connections or answers their webhooks.
+ * - Logs one `warn` (naming the plugins) per interval at most across the cluster: a Redis
+ *   `SET NX PX` rate limit a little shorter than the job period, so a duplicated job or several
+ *   worker replicas do not repeat it while each period still gets its line.
+ * - Silent before `graceUntil` (this process's start + one lease TTL), so a fresh cluster does not
+ *   warn before the gateways' first heartbeat.
+ * Returns whether it warned.
+ */
+export declare function checkGatewayPresence(deps: {
+    db: KernelDb;
+    redis: Redis;
+    config: () => Pick<KernelConfig, "channels">;
+    log: Pick<Logger, "warn">;
+    everyMs?: number;
+    graceUntil?: number;
+}): Promise<boolean>;