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

package/dist/channels/outbound.d.ts

@@ -1,30 +1,18 @@
-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 ChannelTarget, type Logger } from "@capybara-hq/plugin-sdk";
+import { type Job, type Worker } from "bullmq";
+import { EventLog } from "../conversations/event-log.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 { ConversationLock } from "../runtime/conversation-lock.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 { ApprovalsService } from "../tools/approvals.service.js";
+import { QuestionsService } from "../tools/questions.service.js";
+import { ChannelConnections } from "./connections.service.js";
+import { ChannelInbound } from "./inbound.js";
+import { type ChannelJobData, ChannelJobs } from "./jobs.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;
+export { CHANNEL_QUEUE_NAME, DELIVER_ATTEMPTS, DELIVER_JOB, DELIVER_PRIORITY, deliverJobId, followUpJobId, INBOUND_ATTEMPTS, INBOUND_JOB, INBOUND_PRIORITY, idempotencyKey, inboundJobId, } from "./jobs.js";
 /**
  * 投递锁被占时怎么办：读不到持有者（刚被释放）→ 再取一次；是自己上一次（已崩溃、被 stalled 重新投递）的尝试 →
  * 推迟重试等它过期；别的任务 → 直接结束（它会读到新事件，结束时还会复核）。
@@ -41,46 +29,29 @@ export declare function closingText(prior: string | undefined, how: DraftClosing
 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>;
+/** One `last_seq` advance of a delivery (see {@link ChannelOutbound.advanceIn}). */
+export interface DeliveryAdvance {
+    conversationId: string;
+    /** The `last_seq` this delivery wrote last: the update applies only while it is still there. */
+    persisted: number;
+    seq: number;
+    draft?: string | null;
+    card?: {
+        kind: "approval" | "question";
+        id: string;
+        messageId: string;
+        connectionId: string;
+        target: ChannelTarget;
+    };
 }
 /**
  * 渠道出站投递：把会话日志里 `channel_deliveries.last_seq` 之后的内容按序投到 IM。
- * - 生产方（任意角色）：`enqueue(conversationId)` 投递 `deliver-<会话>-<当前 seq>` 任务（会话没有投递目标时什么都不做）。
- *   内核在会话每次追加事件后都调用它（事件日志的 notify 钩子），运行开始时也调用。
- * - Worker（只在 worker 角色）：每个任务先取按会话互斥的投递锁，订阅 `conv.<id>` 后补读日志；运行进入 waiting /
+ * - 生产方（任意角色）：{@link ChannelJobs}（`deliver-<会话>-<当前 seq>` 任务；会话没有投递目标时什么都不做）。
+ * - Worker（只在 worker 角色，经 `@Processor`）：每个任务先取按会话互斥的投递锁，订阅 `conv.<id>` 后补读日志；运行进入 waiting /
  *   终态且日志读完，或追上后 `channels.deliveryIdleMs` 内没有新的总线消息，任务就结束（不长期占并发槽）。
  *   锁被别的任务持有 → 本任务直接结束：持有者会读到新事件，且它结束时（释放锁之后）复核日志是否有新内容，有就再排一个任务；
  *   锁被自己上一次（已崩溃的）尝试占着 → 推迟重试，等锁过期。
@@ -88,41 +59,43 @@ export interface ChannelOutboundDeps {
  *   并记下 IM 消息 id（草稿 id、卡片消息 id），已投递的不会重发。
  *   审批 / 提问卡片在发送之前先记一行 `pending`（T5a），卡片一出现就被点击也能通过 Ruling A13 的核对；
  *   推进 `last_seq` 的事务再补上消息 id、改为 `sent`。崩溃后续投的副本用同一个幂等键重发。
- * 同一队列还承载入站任务（`inbound`，Ruling A21）：由 `enqueueInbound` 排入，worker 调用 `deps.inbound` 处理，
- * 失败按 BullMQ 指数退避重试。
+ * 同一队列还承载入站任务（`inbound`，Ruling A21）：由 {@link ChannelJobs.enqueueInbound} 排入，worker 调用
+ * {@link ChannelInbound.handle} 处理，失败按 BullMQ 指数退避重试。
  * 状态全部在 PG / Redis；进程内只有本任务自己的订阅、草稿节流时刻与等待定时器（本进程持有的资源）。
  */
-export declare class ChannelOutbound implements ChannelOutboundScheduler {
-    private readonly d;
-    private queue;
-    private queueConn;
+export declare class ChannelOutbound {
+    private readonly kdb;
+    /** 入站任务的处理（worker 上执行 `ChannelInbound.handle`）；失败抛错由 BullMQ 重试。 */
+    private readonly inbound;
+    private readonly jobs;
+    private readonly config;
+    private readonly log;
+    readonly txHost: TransactionHost;
     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>;
+    private readonly d;
+    constructor(kdb: KernelDb, bus: StreamBus, eventLog: Pick<EventLog, "readAfter">, 
+    /** The conversation lock provider; delivery takes it under its own key prefix. */
+    lock: Pick<ConversationLock, "scoped">, connections: Pick<ChannelConnections, "outbound">, approvals: Pick<ApprovalsService, "describe">, questions: Pick<QuestionsService, "forCall">, 
+    /** 入站任务的处理（worker 上执行 `ChannelInbound.handle`）；失败抛错由 BullMQ 重试。 */
+    inbound: Pick<ChannelInbound, "handle">, jobs: Pick<ChannelJobs, "enqueue">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "error" | "warn" | "info">, txHost: TransactionHost);
     /**
-     * 连接重新可投递（轮换了凭据 / 重新启用）：给该连接投递进度落后于会话日志的会话各排一个出站任务，
-     * 补投停用或凭据失效期间落下的内容（不必等下一条消息）。
+     * Starts consuming (worker role only): `worker` is the `@Processor` worker of the channel queue
+     * (its job lock and stalled detection follow the run queue's config).
      */
-    resumeConnection(connectionId: string): Promise<void>;
-    /** 启动 Worker（只在含 `worker` 角色的进程）。任务锁与 stalled 检测沿用运行队列的配置。 */
-    startWorker(): void;
+    startWorker(worker: Worker<ChannelJobData>): void;
+    /** The worker's `error` event. */
+    onError(err: Error): void;
+    /** The worker's `failed` event (a requeue for later is not a failure). */
+    onFailed(job: Job<ChannelJobData> | undefined, err: Error): void;
+    /** Stops: the jobs in flight are handed back at their next checkpoint, the worker closes. */
     close(): Promise<void>;
-    private getQueue;
     private requeue;
-    private process;
+    /** One job of the channel queue (the `@Processor` calls it): a delivery or an inbound event. */
+    process(job: Job<ChannelJobData>, token: string | undefined): Promise<void>;
     /** 本副本没有加载连接的插件：推迟重试（不消耗重试次数），排队超过上限才放弃。 */
     private pluginPending;
     /**
@@ -137,4 +110,9 @@ export declare class ChannelOutbound implements ChannelOutboundScheduler {
     private followUp;
     /** 不可重试（或重试用尽）的发送失败：记连接 `last_error`（已打码）。 */
     private recordError;
+    /**
+     * 推进 `last_seq`（同一事务记下草稿 / 卡片消息 id，清零失败计数）。以「仍是 `persisted`」为条件：
+     * 被别人推进过（投递锁丢失后另一实例接手）返回 false，什么都不写。
+     */
+    advanceIn(a: DeliveryAdvance): Promise<boolean>;
 }