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

package/dist/channels/cards.d.ts

@@ -1,5 +1,5 @@
 import type { ChannelCard, FormAnswer, InputForm, OutboundMessage } from "@capybara-hq/plugin-sdk";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import type { ApprovalsService } from "../tools/approvals.service.js";
 import { type ChannelLocale } from "./phrases.js";
 /** 审批卡片里工具参数预览的最大长度（字符）。 */
@@ -24,7 +24,7 @@ export declare const conversationUrl: (base: string, conversationId: string) =>
 /** 个人连接页里某个连接器的位置（与网页 ConnectCard 的链接一致）。 */
 export declare const connectUrl: (base: string, connectorId: string) => string;
 export interface CardDeps {
-    db: KernelDb;
+    db: KernelSchemaDb;
     approvals: Pick<ApprovalsService, "describe">;
 }
 /**

package/dist/channels/channels.module.d.ts

@@ -0,0 +1,40 @@
+import { WorkerHost } from "@nestjs/bullmq";
+import { type DynamicModule } from "@nestjs/common";
+import type { Job, Worker } from "bullmq";
+import type { KernelConfig } from "../config/schema.js";
+import { type ProcessorWorkerOptions } from "../infra/queue/configured-processor.js";
+import { type ChannelJobData } from "./jobs.js";
+import { ChannelOutbound } from "./outbound.js";
+/**
+ * Channels on every role: the org's channel connections, inbound (dedupe and enqueue; the inbound
+ * jobs), the outbound delivery, the producer of the channel queue `cap-kernel-channels`, the
+ * anonymous guests. The roles' parts are the role modules': the queue's consumer
+ * ({@link ChannelWorkersModule}) and the gateway check job are the worker role's, the long-connection
+ * supervisor and the webhook inbound the gateway role's (`GatewayModule`).
+ */
+export declare class ChannelsModule {
+}
+/** The consumer of `cap-kernel-channels` (deliveries and inbound jobs): {@link ChannelOutbound}. */
+export declare class ChannelsProcessor extends WorkerHost<Worker<ChannelJobData>> {
+    private readonly outbound;
+    constructor(outbound: ChannelOutbound);
+    process(job: Job<ChannelJobData>, token?: string): Promise<void>;
+    failed(job: Job<ChannelJobData> | undefined, err: Error): void;
+    error(err: Error): void;
+}
+/**
+ * The worker options of the channel queue's consumer, from the startup config: concurrency
+ * `channels.deliveryConcurrency`, the run queue's job lock and stalled detection, and the delivery
+ * backoff (a platform's retry-after, else exponential).
+ */
+export declare function channelsProcessorOptions(config: Pick<KernelConfig, "runtime" | "channels">): ProcessorWorkerOptions;
+/**
+ * The consumer of the channel queue (concurrency `channels.deliveryConcurrency`, the run queue's job
+ * lock and stalled detection, the delivery backoff). Imported only by the worker role
+ * (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by itself:
+ * the worker role (`WorkerRole`) starts it after the extension load; `ChannelOutbound.close` closes it
+ * on stop.
+ */
+export declare class ChannelWorkersModule {
+    static forRoot(config: KernelConfig): DynamicModule;
+}

package/dist/channels/channels.module.js

@@ -0,0 +1,128 @@
+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); }
+};
+var ChannelWorkersModule_1;
+import { OnWorkerEvent, WorkerHost } from "@nestjs/bullmq";
+import { Inject, Injectable, Module } from "@nestjs/common";
+import { ConversationsModule } from "../conversations/conversations.module.js";
+import { EventLogModule } from "../conversations/event-log.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { IdentityModule } from "../identity/identity.module.js";
+import { configuredProcessor, } from "../infra/queue/configured-processor.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { runJob } from "../infra/queue/run-job.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { OrgsModule } from "../orgs/orgs.module.js";
+import { RuntimeModule } from "../runtime/runtime.module.js";
+import { ToolsModule } from "../tools/tools.module.js";
+import { ChannelConnections } from "./connections.service.js";
+import { ChannelInbound } from "./inbound.js";
+import { CHANNEL_QUEUE_NAME, ChannelJobs } from "./jobs.js";
+import { ChannelOutbound, deliverBackoff } from "./outbound.js";
+import { AnonymousGuestLock, AnonymousGuests } from "./threads.js";
+/**
+ * Channels on every role: the org's channel connections, inbound (dedupe and enqueue; the inbound
+ * jobs), the outbound delivery, the producer of the channel queue `cap-kernel-channels`, the
+ * anonymous guests. The roles' parts are the role modules': the queue's consumer
+ * ({@link ChannelWorkersModule}) and the gateway check job are the worker role's, the long-connection
+ * supervisor and the webhook inbound the gateway role's (`GatewayModule`).
+ */
+let ChannelsModule = class ChannelsModule {
+};
+ChannelsModule = __decorate([
+    Module({
+        imports: [
+            EventLogModule,
+            ExtensionsModule,
+            IdentityModule,
+            OrgLockModule,
+            OrgsModule,
+            ToolsModule,
+            ConversationsModule,
+            RuntimeModule,
+            QueueModule.registerQueue(CHANNEL_QUEUE_NAME),
+        ],
+        providers: [
+            ChannelJobs,
+            ChannelConnections,
+            AnonymousGuestLock,
+            AnonymousGuests,
+            ChannelInbound,
+            ChannelOutbound,
+        ],
+        exports: [ChannelJobs, ChannelConnections, AnonymousGuests, ChannelInbound, ChannelOutbound],
+    })
+], ChannelsModule);
+export { ChannelsModule };
+/** The consumer of `cap-kernel-channels` (deliveries and inbound jobs): {@link ChannelOutbound}. */
+let ChannelsProcessor = class ChannelsProcessor extends WorkerHost {
+    outbound;
+    constructor(outbound) {
+        super();
+        this.outbound = outbound;
+    }
+    process(job, token) {
+        return runJob(CHANNEL_QUEUE_NAME, job, () => this.outbound.process(job, token));
+    }
+    failed(job, err) {
+        this.outbound.onFailed(job, err);
+    }
+    error(err) {
+        this.outbound.onError(err);
+    }
+};
+__decorate([
+    OnWorkerEvent("failed")
+], ChannelsProcessor.prototype, "failed", null);
+__decorate([
+    OnWorkerEvent("error")
+], ChannelsProcessor.prototype, "error", null);
+ChannelsProcessor = __decorate([
+    Injectable(),
+    __param(0, Inject(ChannelOutbound))
+], ChannelsProcessor);
+export { ChannelsProcessor };
+/**
+ * The worker options of the channel queue's consumer, from the startup config: concurrency
+ * `channels.deliveryConcurrency`, the run queue's job lock and stalled detection, and the delivery
+ * backoff (a platform's retry-after, else exponential).
+ */
+export function channelsProcessorOptions(config) {
+    return {
+        concurrency: config.channels.deliveryConcurrency,
+        lockDuration: config.runtime.jobLockMs,
+        stalledInterval: config.runtime.stalledIntervalMs,
+        maxStalledCount: 3,
+        settings: { backoffStrategy: (n, _type, err) => deliverBackoff(n, err) },
+    };
+}
+/**
+ * The consumer of the channel queue (concurrency `channels.deliveryConcurrency`, the run queue's job
+ * lock and stalled detection, the delivery backoff). Imported only by the worker role
+ * (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by itself:
+ * the worker role (`WorkerRole`) starts it after the extension load; `ChannelOutbound.close` closes it
+ * on stop.
+ */
+let ChannelWorkersModule = ChannelWorkersModule_1 = class ChannelWorkersModule {
+    static forRoot(config) {
+        return {
+            module: ChannelWorkersModule_1,
+            imports: [ChannelsModule],
+            providers: [
+                configuredProcessor(ChannelsProcessor, CHANNEL_QUEUE_NAME, channelsProcessorOptions(config)),
+            ],
+            exports: [ChannelsProcessor],
+        };
+    }
+};
+ChannelWorkersModule = ChannelWorkersModule_1 = __decorate([
+    Module({})
+    // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
+], ChannelWorkersModule);
+export { ChannelWorkersModule };

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

@@ -2,7 +2,7 @@ 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";
+import { ChannelConnections, type ChannelConnectionView } from "./connections.service.js";
 declare const CreateBody: z.ZodObject<{
     plugin: z.ZodString;
     name: z.ZodString;

package/dist/channels/connections.controller.js

@@ -7,12 +7,13 @@ 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 { 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 { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ChannelConnections } from "./connections.service.js";
 const Config = z.record(z.string().max(200), z.unknown());
 const Policy = z.enum(["bind", "anonymous"]);
 const CreateBody = z
@@ -35,6 +36,10 @@ const PatchBody = z
     config: Config.optional(),
 })
     .strict();
+class ChannelCreateBody extends createZodDto(CreateBody, "ChannelCreateBody") {
+}
+class ChannelPatchBody extends createZodDto(PatchBody, "ChannelPatchBody") {
+}
 /**
  * 组织的渠道连接（`/api/v1/orgs/:orgId/channels`），全部需要 `channels.manage`（admin，仅限人）。
  * 响应只回显非密钥配置与密钥是否已设置。
@@ -84,7 +89,7 @@ __decorate([
     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,7 +103,7 @@ __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([
     Delete(":connectionId"),
@@ -110,6 +115,6 @@ __decorate([
 ], ChannelConnectionsController.prototype, "remove", null);
 ChannelConnectionsController = __decorate([
     Controller("api/v1/orgs/:orgId/channels"),
-    __param(0, Inject(CHANNEL_CONNECTIONS))
+    __param(0, Inject(ChannelConnections))
 ], ChannelConnectionsController);
 export { ChannelConnectionsController };

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

@@ -1,11 +1,17 @@
-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 { 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";
 /** 连接配置里全部密钥字段存成一行：`{ 点路径: 值 }` 的 JSON。 */
 export declare const connectionSecretKey: (connectionId: string) => string;
 /**
@@ -78,29 +84,39 @@ 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;
+    private readonly unsubscribe;
+    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);
+    /** 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;
@@ -126,6 +142,8 @@ 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;
     /**
      * 修改名称、agent、未绑定策略、启停，或轮换凭据（新配置同样先 `verify`，失败什么都不改）。
      * 插件在该组织停用时仍可轮换凭据，此时不 verify，返回 `verifySkipped: true`。
@@ -134,8 +152,12 @@ export declare class ChannelConnections {
         channel: ChannelConnectionView;
         verifySkipped: boolean;
     }>;
+    /** The rows of {@link update}, in their own transaction (the caller publishes after the commit). */
+    private updateIn;
     /** 删除（软删除，同一事务删掉密钥）；持有长连接的副本收到广播后断开。 */
     remove(orgId: string, id: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    /** The rows of {@link remove}, in their own transaction (the caller publishes after the commit). */
+    private removeIn;
     /** 提交后广播；失败只记日志（持有方每轮续租时也会复核连接状态）。 */
     private changed;
     /**