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

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

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import type { JsonSchema } from "../extensions/config-json-schema.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>;
+/**
+ * 组织的渠道连接（`/api/v1/orgs/:orgId/channels`），全部需要 `channels.manage`（admin，仅限人）。
+ * 响应只回显非密钥配置与密钥是否已设置。
+ */
+export declare class ChannelConnectionsController {
+    private readonly channels;
+    constructor(channels: ChannelConnections);
+    list(org: OrgContext): Promise<{
+        channels: ChannelConnectionView[];
+    }>;
+    schema(plugin: string): {
+        plugin: string;
+        schema: JsonSchema;
+    };
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
+        channel: ChannelConnectionView;
+    }>;
+    get(org: OrgContext, id: string): Promise<{
+        channel: ChannelConnectionView;
+    }>;
+    update(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof PatchBody>): Promise<{
+        channel: ChannelConnectionView;
+        verifySkipped: boolean;
+    }>;
+    remove(principal: Principal, org: OrgContext, id: string): Promise<void>;
+}
+export {};

package/dist/channels/connections.controller.js

@@ -0,0 +1,115 @@
+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 { 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 { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.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();
+/**
+ * 组织的渠道连接（`/api/v1/orgs/:orgId/channels`），全部需要 `channels.manage`（admin，仅限人）。
+ * 响应只回显非密钥配置与密钥是否已设置。
+ */
+let ChannelConnectionsController = class ChannelConnectionsController {
+    channels;
+    constructor(channels) {
+        this.channels = channels;
+    }
+    async list(org) {
+        return { channels: await this.channels.list(org.orgId) };
+    }
+    schema(plugin) {
+        return { plugin, schema: this.channels.jsonSchema(plugin) };
+    }
+    async create(principal, org, body) {
+        const p = requireUser(principal);
+        return {
+            channel: 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) };
+    }
+    async update(principal, org, id, body) {
+        const p = requireUser(principal);
+        // verifySkipped：插件在该组织停用时轮换凭据不调用插件校验（重新启用后按新凭据连接）
+        return this.channels.update(org.orgId, id, body, p.account.id, patTokenId(p));
+    }
+    async remove(principal, org, id) {
+        const p = requireUser(principal);
+        await this.channels.remove(org.orgId, id, p.account.id, patTokenId(p));
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("channels.manage"),
+    __param(0, CurrentOrg())
+], ChannelConnectionsController.prototype, "list", null);
+__decorate([
+    Get("schema/:plugin"),
+    OrgAction("channels.manage"),
+    __param(0, Param("plugin"))
+], ChannelConnectionsController.prototype, "schema", null);
+__decorate([
+    Post(),
+    OrgAction("channels.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(CreateBody)))
+], ChannelConnectionsController.prototype, "create", null);
+__decorate([
+    Get(":connectionId"),
+    OrgAction("channels.manage"),
+    __param(0, CurrentOrg()),
+    __param(1, Param("connectionId"))
+], ChannelConnectionsController.prototype, "get", null);
+__decorate([
+    Patch(":connectionId"),
+    OrgAction("channels.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectionId")),
+    __param(3, Body(new ZodPipe(PatchBody)))
+], ChannelConnectionsController.prototype, "update", null);
+__decorate([
+    Delete(":connectionId"),
+    HttpCode(204),
+    OrgAction("channels.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectionId"))
+], ChannelConnectionsController.prototype, "remove", null);
+ChannelConnectionsController = __decorate([
+    Controller("api/v1/orgs/:orgId/channels"),
+    __param(0, Inject(CHANNEL_CONNECTIONS))
+], ChannelConnectionsController);
+export { ChannelConnectionsController };

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

@@ -0,0 +1,187 @@
+import { type Channel, type ChannelTarget, type ExtensionContext, type Logger, type OutboundMessage } from "@capybara-hq/plugin-sdk";
+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";
+/** 连接配置里全部密钥字段存成一行：`{ 点路径: 值 }` 的 JSON。 */
+export declare const connectionSecretKey: (connectionId: string) => string;
+/**
+ * 连接被改动的内核 bus 主题，payload `{ connectionId, reconnect }`：`reconnect` 为 true（启停、删除、轮换凭据）时
+ * 持有长连接的副本断开、交还租约；改名 / agent / 未绑定策略不需要重连（入站每条消息都实时读连接行）。
+ */
+export declare const CHANNEL_CHANGED_TOPIC = "channel.changed";
+/** Redis：连接失败后的退避标记与连续失败次数（任一副本都据此决定何时重试）。 */
+export declare const channelBackoffKey: (id: string) => string;
+export declare const channelFailsKey: (id: string) => string;
+export type UnboundPolicy = "bind" | "anonymous";
+export type ChannelStatus = "active" | "disabled" | "error";
+/** How inbound events arrive: a long connection held by a gateway replica (default), or webhooks. */
+export type InboundMode = "long_connection" | "webhook";
+/** 对外的连接视图：`config` 只含非密钥字段，密钥只回显「是否已设置」。 */
+export interface ChannelConnectionView {
+    id: string;
+    orgId: string;
+    plugin: string;
+    name: string;
+    agentId: string;
+    unboundPolicy: UnboundPolicy;
+    status: ChannelStatus;
+    inboundMode: InboundMode;
+    /** The plugin implements `Channel.webhook`, so the connection can switch to webhook mode. */
+    webhookSupported: boolean;
+    /**
+     * The callback URL to register with the platform (`<channels.webhookBaseUrl>/channels/webhook/<id>`);
+     * null when the plugin has no webhook support or `channels.webhookBaseUrl` is not configured.
+     */
+    webhookUrl: string | null;
+    lastError: string | null;
+    botUserId: string | null;
+    tenantId: string | null;
+    config: Record<string, unknown>;
+    secrets: {
+        path: string;
+        set: boolean;
+    }[];
+    createdBy: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** 运行时用到的连接行。 */
+export interface ChannelConnectionRow {
+    id: string;
+    orgId: string;
+    plugin: string;
+    agentId: string;
+    unboundPolicy: UnboundPolicy;
+    status: ChannelStatus;
+    inboundMode: InboundMode;
+    tenantId: string | null;
+    /** 插件此刻在该组织启用。 */
+    pluginEnabled: boolean;
+}
+export interface CreateChannelInput {
+    plugin: string;
+    name: string;
+    agentId: string;
+    config: Record<string, unknown>;
+    unboundPolicy?: UnboundPolicy | undefined;
+}
+/** `config` 里的密钥字段：缺省 = 保留原值、`null` = 清除、其他值 = 新值（同组织插件配置）。 */
+export interface UpdateChannelInput {
+    name?: string | undefined;
+    agentId?: string | undefined;
+    unboundPolicy?: UnboundPolicy | undefined;
+    status?: "active" | "disabled" | undefined;
+    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);
+    /** 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`、不输出取值）。 */
+    jsonSchema(plugin: string): JsonSchema;
+    private parse;
+    private verify;
+    private reportSecrets;
+    private assertAgent;
+    private readSecrets;
+    private view;
+    private webhookBase;
+    /**
+     * Switching to webhook mode needs a plugin that implements `Channel.webhook` and a configured
+     * `channels.webhookBaseUrl` (otherwise there is no URL to give the platform): 409 otherwise.
+     */
+    private assertWebhookAvailable;
+    private viewOf;
+    private live;
+    list(orgId: string): Promise<ChannelConnectionView[]>;
+    get(orgId: string, id: string): Promise<ChannelConnectionView>;
+    /** 新建：插件须提供 channel@1 且在该组织启用；配置按 `connectionSchema` 校验；先 `verify`，失败不落库。 */
+    create(orgId: string, input: CreateChannelInput, actorAccountId: string, actorTokenId?: string): Promise<ChannelConnectionView>;
+    /**
+     * 修改名称、agent、未绑定策略、启停，或轮换凭据（新配置同样先 `verify`，失败什么都不改）。
+     * 插件在该组织停用时仍可轮换凭据，此时不 verify，返回 `verifySkipped: true`。
+     */
+    update(orgId: string, id: string, patch: UpdateChannelInput, actorAccountId: string, actorTokenId?: string): Promise<{
+        channel: ChannelConnectionView;
+        verifySkipped: boolean;
+    }>;
+    /** 删除（软删除，同一事务删掉密钥）；持有长连接的副本收到广播后断开。 */
+    remove(orgId: string, id: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    /** 提交后广播；失败只记日志（持有方每轮续租时也会复核连接状态）。 */
+    private changed;
+    /**
+     * 运行时读连接行：连接未删除且所属组织未删除（组织软删除后它的机器人什么都不做）；不存在返回 undefined。
+     * `pluginEnabled` 为插件此刻是否在该组织启用（入站与卡片操作每次都实时复核）。
+     */
+    row(id: string): Promise<ChannelConnectionRow | undefined>;
+    /**
+     * 组织被删除 / 停用了某插件之后：给该组织（该插件）的每个连接广播 `channel.changed { reconnect: true }`，
+     * 持有长连接的副本立即断开（扫描复核只是兜底）。只广播，失败只记日志。
+     */
+    notifyOrgChanged(orgId: string, plugin?: string): Promise<void>;
+    /**
+     * The extension implementation and full config a connection needs to run (decrypted secrets
+     * included, validated against `connectionSchema`). Connection missing / deleted ->
+     * `channel.not_found`; extension not loaded -> `extension.not_found`; not enabled in the org ->
+     * `extension.not_enabled`; the stored config no longer satisfies the schema (after an extension
+     * upgrade) -> `extension.config_invalid`. Never echoed into responses or logs.
+     */
+    runtime(id: string): Promise<{
+        row: ChannelConnectionRow;
+        channel: Channel;
+        config: unknown;
+        /** The plugin instance's in-flight count (webhook calls enter it, so an upgrade drains them). */
+        inflight?: InflightTracker;
+    }>;
+    /**
+     * 出站会话：解密一次连接配置，之后经插件发 / 改消息（每次调用 15s 超时）。目标与消息先按渠道的
+     * `features` 调整（不支持卡片的退回为文本、不支持话题的去掉 threadId，Ruling A33，见 features.ts）。出站投递任务在一次任务内复用它；
+     * `redact` 按该连接的密钥打码（插件异常信息写进 `last_error` 前使用）。
+     */
+    outbound(connectionId: string): Promise<ChannelOutboundSession>;
+    /** 经连接的插件直接发一条消息（入站处理回绑定卡片、固定话术，卡片操作回说明）；`idempotencyKey` 原样交给插件。 */
+    send(connectionId: string, target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string): Promise<{
+        messageId: string;
+    }>;
+}
+/** {@link ChannelConnections.outbound} 的返回值。 */
+export interface ChannelOutboundSession {
+    row: ChannelConnectionRow;
+    features: Channel["features"];
+    redact: (s: string) => string;
+    /** `idempotencyKey` 原样交给插件（见 `ChannelSendArgs.idempotencyKey`）。 */
+    send(target: ChannelTarget, message: OutboundMessage, idempotencyKey?: string): Promise<{
+        messageId: string;
+    }>;
+    /** 只在 `features.edit` 为 true 时调用。 */
+    update(target: ChannelTarget, messageId: string, message: OutboundMessage, idempotencyKey?: string): Promise<void>;
+}