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

package/dist/roles/worker-role.js

@@ -0,0 +1,144 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { ChannelsProcessor } from "../channels/channels.module.js";
+import { ChannelOutbound } from "../channels/outbound.js";
+import { TitleQueue } from "../conversations/titles.js";
+import { EvalsProcessor } from "../evals/evals.module.js";
+import { EvalWorker } from "../evals/worker.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockedIntervalScheduler } from "../infra/schedule/locked-interval.js";
+import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { MaintenanceProcessor } from "../runtime/maintenance.js";
+import { RunsProcessor, SubagentRunsProcessor, TitleProcessor, UsageReportProcessor, } from "../runtime/run-processors.js";
+import { RunWorker } from "../runtime/run-worker.js";
+import { UsageReporter } from "../runtime/usage-report.js";
+/**
+ * The worker role's parts, driven by `KernelLifecycle` at fixed points of its start order and stop
+ * phases (so they stay ordered after the extension load and before the extension host closes): the
+ * queue consumers (runs, sub-agent runs, evals, maintenance, channel deliveries, `usage.report`,
+ * titles) and the schedulers of the `@LockedCron` / `@LockedInterval` jobs. Provided only by
+ * `WorkerModule`, so a process without the worker role has none of them.
+ */
+let WorkerRole = class WorkerRole {
+    log;
+    intervals;
+    scheduledRuns;
+    runWorker;
+    evalWorker;
+    usageReport;
+    titles;
+    channelOutbound;
+    runsProcessor;
+    subagentRunsProcessor;
+    usageProcessor;
+    titleProcessor;
+    channelsProcessor;
+    evalsProcessor;
+    maintenanceProcessor;
+    /** The startup config (the roles). */
+    config;
+    /** The run worker was started: the runs phase drains it. */
+    runsStarted = false;
+    /** The eval worker was started: the runs phase drains it. */
+    evalsStarted = false;
+    constructor(config, log, intervals, scheduledRuns, runWorker, evalWorker, usageReport, titles, channelOutbound, runsProcessor, subagentRunsProcessor, usageProcessor, titleProcessor, channelsProcessor, evalsProcessor, maintenanceProcessor) {
+        this.log = log;
+        this.intervals = intervals;
+        this.scheduledRuns = scheduledRuns;
+        this.runWorker = runWorker;
+        this.evalWorker = evalWorker;
+        this.usageReport = usageReport;
+        this.titles = titles;
+        this.channelOutbound = channelOutbound;
+        this.runsProcessor = runsProcessor;
+        this.subagentRunsProcessor = subagentRunsProcessor;
+        this.usageProcessor = usageProcessor;
+        this.titleProcessor = titleProcessor;
+        this.channelsProcessor = channelsProcessor;
+        this.evalsProcessor = evalsProcessor;
+        this.maintenanceProcessor = maintenanceProcessor;
+        this.config = config.get();
+    }
+    /**
+     * Starts the queue consumers (after the extension load), then opens the schedules' start gate:
+     * the cron and interval timers were armed at application bootstrap, but every tick before this
+     * point skipped (decision R21 of the Nest kernel spec); the `@LockedInterval({ runOnStart })`
+     * jobs run now, in the background (once across replicas starting together). `checkpoint` throws
+     * when a stop began meanwhile.
+     */
+    async start(checkpoint) {
+        // both run queues' @Processor workers (built with the run config, never autorun)
+        this.runWorker.start([this.runsProcessor.worker, this.subagentRunsProcessor.worker]);
+        this.runsStarted = true;
+        this.evalWorker.start(this.evalsProcessor.worker);
+        this.evalsStarted = true;
+        // The maintenance queue: remove the retired job schedulers (idempotent, harmless when several
+        // replicas do it), then start its one consumer. A failure is only logged and does not stop the
+        // start (like the workers' connection errors): any worker replica removes them on its next start.
+        try {
+            await this.maintenanceProcessor.removeRetiredSchedulers();
+        }
+        catch (err) {
+            this.log.error("cannot register maintenance job schedulers", { err });
+        }
+        checkpoint();
+        this.maintenanceProcessor.start();
+        this.channelOutbound.startWorker(this.channelsProcessor.worker);
+        this.usageReport.startWorker(this.usageProcessor.worker);
+        this.titles.startWorker(this.titleProcessor.worker);
+        if (!this.config.roles.includes("gateway")) {
+            this.log.info("this process runs the worker role without gateway; channel long connections are held only by processes with the gateway role", { roles: this.config.roles });
+        }
+        // The gate opens: from here on ticks run; the runOnStart jobs run once now, in the background
+        this.scheduledRuns.open();
+        this.intervals.runStartJobs();
+    }
+    /**
+     * Closes the start gate and stops the schedulers (no new tick; the runs in progress get the stop
+     * signal) and returns the wait for those runs, at most `budgetMs`.
+     */
+    stopSchedules(budgetMs) {
+        return this.scheduledRuns.stop(budgetMs);
+    }
+    /** The runs phase: this process's runs stop at their next step boundary (undefined: never started). */
+    drainRuns(budgetMs) {
+        return this.runsStarted ? this.runWorker.close(budgetMs) : undefined;
+    }
+    /** The eval cases in progress stop (undefined: never started). */
+    drainEvals(budgetMs) {
+        return this.evalsStarted ? this.evalWorker.close(budgetMs) : undefined;
+    }
+    /** Closes the maintenance queue's worker. */
+    closeMaintenance() {
+        return this.maintenanceProcessor.worker.close();
+    }
+};
+WorkerRole = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelConfigService)),
+    __param(1, Inject(KERNEL_LOGGER)),
+    __param(2, Inject(LockedIntervalScheduler)),
+    __param(3, Inject(ScheduledRuns)),
+    __param(4, Inject(RunWorker)),
+    __param(5, Inject(EvalWorker)),
+    __param(6, Inject(UsageReporter)),
+    __param(7, Inject(TitleQueue)),
+    __param(8, Inject(ChannelOutbound)),
+    __param(9, Inject(RunsProcessor)),
+    __param(10, Inject(SubagentRunsProcessor)),
+    __param(11, Inject(UsageReportProcessor)),
+    __param(12, Inject(TitleProcessor)),
+    __param(13, Inject(ChannelsProcessor)),
+    __param(14, Inject(EvalsProcessor)),
+    __param(15, Inject(MaintenanceProcessor))
+], WorkerRole);
+export { WorkerRole };

package/dist/roles/worker.module.d.ts

@@ -0,0 +1,14 @@
+import { type DynamicModule } from "@nestjs/common";
+import type { KernelConfig } from "../config/schema.js";
+/**
+ * The worker role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
+ * `worker`: the cron scheduler and the `@LockedInterval` scheduler (`KernelScheduleModule`, the one
+ * place `ScheduleModule.forRoot` is imported), every fixed-period job (`@LockedCron` /
+ * `@LockedInterval`, each once per tick across replicas), every queue consumer (`@Processor`: runs,
+ * sub-agent runs, `usage.report`, titles, evals, maintenance, channel deliveries) and
+ * {@link WorkerRole}, which `KernelLifecycle` drives. A process without the worker role runs no cron
+ * and no BullMQ worker (the queues' producers exist on every role).
+ */
+export declare class WorkerModule {
+    static forRoot(config: KernelConfig): DynamicModule;
+}

package/dist/roles/worker.module.js

@@ -0,0 +1,90 @@
+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 WorkerModule_1;
+import { Module } from "@nestjs/common";
+import { CatalogModule } from "../catalog/catalog.module.js";
+import { CatalogJobs } from "../catalog/jobs.js";
+import { ChannelsModule, ChannelWorkersModule } from "../channels/channels.module.js";
+import { GatewayCheckJob } from "../channels/supervisor.js";
+import { AttachmentsModule } from "../conversations/attachments.module.js";
+import { AttachmentCleanupJob } from "../conversations/attachments.service.js";
+import { TitlesModule } from "../conversations/titles.js";
+import { EvalWorkersModule } from "../evals/evals.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { PluginsReconcileJob } from "../extensions/lifecycle.js";
+import { KernelScheduleModule } from "../infra/schedule/schedule.module.js";
+import { DirectoryScanJob } from "../orgs/directory-sync.js";
+import { OffboardSweepJob } from "../orgs/offboarding.js";
+import { OrgsModule } from "../orgs/orgs.module.js";
+import { MaintenanceModule } from "../runtime/maintenance.js";
+import { RuntimeWorkersModule } from "../runtime/run-processors.js";
+import { RuntimeModule } from "../runtime/runtime.module.js";
+import { UsageReportModule, UsageSweepJob } from "../runtime/usage-report.js";
+import { WaitSweepJob } from "../runtime/waits.js";
+import { SandboxSweepJobs } from "../sandbox/jobs.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { StoragePurgeJob } from "../storage/purge.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { ToolJobs } from "../tools/jobs.js";
+import { ToolsModule } from "../tools/tools.module.js";
+import { WorkerRole } from "./worker-role.js";
+/**
+ * The worker role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
+ * `worker`: the cron scheduler and the `@LockedInterval` scheduler (`KernelScheduleModule`, the one
+ * place `ScheduleModule.forRoot` is imported), every fixed-period job (`@LockedCron` /
+ * `@LockedInterval`, each once per tick across replicas), every queue consumer (`@Processor`: runs,
+ * sub-agent runs, `usage.report`, titles, evals, maintenance, channel deliveries) and
+ * {@link WorkerRole}, which `KernelLifecycle` drives. A process without the worker role runs no cron
+ * and no BullMQ worker (the queues' producers exist on every role).
+ */
+let WorkerModule = WorkerModule_1 = class WorkerModule {
+    static forRoot(config) {
+        return {
+            module: WorkerModule_1,
+            imports: [
+                KernelScheduleModule,
+                // the queue consumers (their worker options come from the startup config)
+                RuntimeWorkersModule.forRoot(config),
+                EvalWorkersModule.forRoot(config),
+                ChannelWorkersModule.forRoot(config),
+                MaintenanceModule,
+                // the domains the fixed-period jobs call
+                RuntimeModule,
+                UsageReportModule,
+                TitlesModule,
+                AttachmentsModule,
+                StorageModule,
+                SandboxModule,
+                ToolsModule,
+                CatalogModule,
+                OrgsModule,
+                ExtensionsModule,
+                ChannelsModule,
+            ],
+            providers: [
+                WaitSweepJob,
+                UsageSweepJob,
+                AttachmentCleanupJob,
+                StoragePurgeJob,
+                SandboxSweepJobs,
+                ToolJobs,
+                CatalogJobs,
+                DirectoryScanJob,
+                OffboardSweepJob,
+                PluginsReconcileJob,
+                GatewayCheckJob,
+                WorkerRole,
+            ],
+            exports: [WorkerRole],
+        };
+    }
+};
+WorkerModule = WorkerModule_1 = __decorate([
+    Module({})
+    // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
+], WorkerModule);
+export { WorkerModule };

package/dist/runtime/abort.js

@@ -1,3 +1,14 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { KERNEL_BUS, REDIS } from "../infra/tokens.js";
 /** 中止广播的内核 bus 主题。 */
 export const RUN_ABORT_TOPIC = "run.abort";
 /** 中止标记的保留时长（秒）。 */
@@ -15,7 +26,7 @@ const parseStored = (stored) => {
  * 跨副本中止（spec 4.3「中止信号经 Redis 广播」）：`request` 先写标记键再广播；
  * `watch` 先订阅、再检查一次标记键，订阅之前发出的中止也不会丢。
  */
-export class RunAbort {
+let RunAbort = class RunAbort {
     redis;
     bus;
     constructor(redis, bus) {
@@ -68,4 +79,10 @@ export class RunAbort {
         }
         return unsubscribe;
     }
-}
+};
+RunAbort = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KERNEL_BUS))
+], RunAbort);
+export { RunAbort };

package/dist/runtime/checkpointer.d.ts

@@ -1,6 +1,7 @@
 import type { RunnableConfig } from "@langchain/core/runnables";
 import { BaseCheckpointSaver, type ChannelVersions, type Checkpoint, type CheckpointListOptions, type CheckpointMetadata, type CheckpointTuple, type PendingWrite } from "@langchain/langgraph-checkpoint";
-import type { KernelDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
 /**
  * LangGraph checkpoint saver，存在内核 schema 的 `lg_checkpoints` / `lg_checkpoint_writes` 里（0007_checkpoints.sql）。
  *
@@ -10,12 +11,16 @@ import type { KernelDb } from "../db/kernel-schema.js";
  * - 所有状态都在 PG 里，不持有进程内状态，任意副本都能续跑。
  */
 export declare class KyselyCheckpointSaver extends BaseCheckpointSaver {
-    private readonly db;
-    constructor(db: KernelDb);
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, txHost: TransactionHost);
+    /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
+    private get db();
     getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
     list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
     put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions: ChannelVersions): Promise<RunnableConfig>;
     putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string, taskPath?: string): Promise<void>;
+    private insertWrites;
     deleteThread(threadId: string): Promise<void>;
     /**
      * 一轮运行结束后调用：根命名空间（`checkpoint_ns = ''`）下只保留最新一个 checkpoint 及其 writes，

package/dist/runtime/checkpointer.js

@@ -1,5 +1,18 @@
+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 { BaseCheckpointSaver, compareWritesSortKeys, copyCheckpoint, getCheckpointId, maxChannelVersion, TASKS, WRITES_IDX_MAP, writesSortKey, } from "@langchain/langgraph-checkpoint";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
 const CHECKPOINT_COLUMNS = [
     "thread_id",
     "checkpoint_ns",
@@ -20,11 +33,17 @@ const idC = sql `checkpoint_id collate "C"`;
  * - thread_id 约定为 runId。
  * - 所有状态都在 PG 里，不持有进程内状态，任意副本都能续跑。
  */
-export class KyselyCheckpointSaver extends BaseCheckpointSaver {
-    db;
-    constructor(db) {
+let KyselyCheckpointSaver = class KyselyCheckpointSaver extends BaseCheckpointSaver {
+    kdb;
+    txHost;
+    constructor(kdb, txHost) {
         super();
-        this.db = db;
+        this.kdb = kdb;
+        this.txHost = txHost;
+    }
+    /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
+    get db() {
+        return this.kdb.db;
     }
     async getTuple(config) {
         const threadId = config.configurable?.thread_id;
@@ -130,34 +149,33 @@ export class KyselyCheckpointSaver extends BaseCheckpointSaver {
         // 特殊 channel（错误、中断等，idx < 0）以最后一次为准；普通 write 已存在则保留先写入的。
         const special = rows.filter((r) => r.idx < 0);
         const regular = rows.filter((r) => r.idx >= 0);
+        await this.insertWrites(regular, special);
+    }
+    async insertWrites(regular, special) {
         const key = ["thread_id", "checkpoint_ns", "checkpoint_id", "task_id", "idx"];
-        await this.db.transaction().execute(async (trx) => {
-            if (regular.length > 0) {
-                await trx
-                    .insertInto("lg_checkpoint_writes")
-                    .values(regular)
-                    .onConflict((oc) => oc.columns(key).doNothing())
-                    .execute();
-            }
-            if (special.length > 0) {
-                await trx
-                    .insertInto("lg_checkpoint_writes")
-                    .values(special)
-                    .onConflict((oc) => oc.columns(key).doUpdateSet((eb) => ({
-                    channel: eb.ref("excluded.channel"),
-                    value_type: eb.ref("excluded.value_type"),
-                    value: eb.ref("excluded.value"),
-                    task_path: eb.ref("excluded.task_path"),
-                })))
-                    .execute();
-            }
-        });
+        if (regular.length > 0) {
+            await this.db
+                .insertInto("lg_checkpoint_writes")
+                .values(regular)
+                .onConflict((oc) => oc.columns(key).doNothing())
+                .execute();
+        }
+        if (special.length > 0) {
+            await this.db
+                .insertInto("lg_checkpoint_writes")
+                .values(special)
+                .onConflict((oc) => oc.columns(key).doUpdateSet((eb) => ({
+                channel: eb.ref("excluded.channel"),
+                value_type: eb.ref("excluded.value_type"),
+                value: eb.ref("excluded.value"),
+                task_path: eb.ref("excluded.task_path"),
+            })))
+                .execute();
+        }
     }
     async deleteThread(threadId) {
-        await this.db.transaction().execute(async (trx) => {
-            await trx.deleteFrom("lg_checkpoint_writes").where("thread_id", "=", threadId).execute();
-            await trx.deleteFrom("lg_checkpoints").where("thread_id", "=", threadId).execute();
-        });
+        await this.db.deleteFrom("lg_checkpoint_writes").where("thread_id", "=", threadId).execute();
+        await this.db.deleteFrom("lg_checkpoints").where("thread_id", "=", threadId).execute();
     }
     /**
      * 一轮运行结束后调用：根命名空间（`checkpoint_ns = ''`）下只保留最新一个 checkpoint 及其 writes，
@@ -166,31 +184,30 @@ export class KyselyCheckpointSaver extends BaseCheckpointSaver {
      * 保留下来的 checkpoint 的 parent_checkpoint_id 原样保留（父 checkpoint 已不存在）。
      */
     async pruneToLatest(threadId) {
-        return this.db.transaction().execute(async (trx) => {
-            const latest = await trx
-                .selectFrom("lg_checkpoints")
-                .select("checkpoint_id")
-                .where("thread_id", "=", threadId)
-                .where("checkpoint_ns", "=", "")
-                .orderBy(sql `${idC} desc`)
-                .limit(1)
-                .executeTakeFirst();
-            if (!latest)
-                return 0;
-            await trx
-                .deleteFrom("lg_checkpoint_writes")
-                .where("thread_id", "=", threadId)
-                .where("checkpoint_ns", "=", "")
-                .where(idC, "<", latest.checkpoint_id)
-                .execute();
-            const res = await trx
-                .deleteFrom("lg_checkpoints")
-                .where("thread_id", "=", threadId)
-                .where("checkpoint_ns", "=", "")
-                .where(idC, "<", latest.checkpoint_id)
-                .executeTakeFirst();
-            return Number(res.numDeletedRows);
-        });
+        const db = this.db;
+        const latest = await db
+            .selectFrom("lg_checkpoints")
+            .select("checkpoint_id")
+            .where("thread_id", "=", threadId)
+            .where("checkpoint_ns", "=", "")
+            .orderBy(sql `${idC} desc`)
+            .limit(1)
+            .executeTakeFirst();
+        if (!latest)
+            return 0;
+        await db
+            .deleteFrom("lg_checkpoint_writes")
+            .where("thread_id", "=", threadId)
+            .where("checkpoint_ns", "=", "")
+            .where(idC, "<", latest.checkpoint_id)
+            .execute();
+        const res = await db
+            .deleteFrom("lg_checkpoints")
+            .where("thread_id", "=", threadId)
+            .where("checkpoint_ns", "=", "")
+            .where(idC, "<", latest.checkpoint_id)
+            .executeTakeFirst();
+        return Number(res.numDeletedRows);
     }
     async toTuple(row, metadata) {
         const { thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id } = row;
@@ -240,4 +257,19 @@ export class KyselyCheckpointSaver extends BaseCheckpointSaver {
         checkpoint.channel_versions[TASKS] =
             versions.length > 0 ? maxChannelVersion(...versions) : this.getNextVersion(undefined);
     }
-}
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], KyselyCheckpointSaver.prototype, "insertWrites", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], KyselyCheckpointSaver.prototype, "deleteThread", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], KyselyCheckpointSaver.prototype, "pruneToLatest", null);
+KyselyCheckpointSaver = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost))
+], KyselyCheckpointSaver);
+export { KyselyCheckpointSaver };

package/dist/runtime/conversation-lock.d.ts

@@ -1,12 +1,11 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
-import type { Redis } from "ioredis";
+import { LockService } from "../infra/lock/lock.service.js";
 /** 会话运行锁的默认 TTL（毫秒）：持有方每 `ttlMs / 3` 续租一次。 */
 export declare const CONVERSATION_LOCK_TTL_MS = 30000;
 /** 本进程持有的会话运行锁。 */
 export interface Lease {
     readonly conversationId: string;
     readonly runId: string;
-    /** 续租时发现锁已不属于自己（过期后被他人取得）；此后不再续租。 */
+    /** 续租时发现锁已不属于自己（过期后被他人取得，或续租一直失败到过期）；此后不再续租。 */
     readonly lost: boolean;
     /** 立即续租一次；锁已不属于自己 → false（并标记 lost）。 */
     renew(): Promise<boolean>;
@@ -18,16 +17,17 @@ export interface Lease {
     onLost(cb: () => void): void;
 }
 /**
- * 会话级运行锁（spec 4.3「同一会话同一时刻只跑一轮」）：Redis 键 `capk:conv-run:<id>`，值为 runId，
- * 带 TTL；持有期间由本进程的定时器每 `ttlMs / 3` 续租（本进程持有的锁的续租，允许的进程内定时器）。
- * 持有方崩溃时停止续租，锁在 TTL 后过期，其他副本可以取得。
+ * A per-conversation lease on {@link LockService.hold}: key `<prefix><conversationId>`, value the
+ * holder's run id (other replicas read it with {@link holder}), renewed every TTL/3 by the lock
+ * service while held; a crashed holder's key expires within the TTL and another replica can take
+ * it. Built by {@link ConversationLock} (the run lock) and its {@link ConversationLock.scoped}
+ * views (the same lock for another purpose, e.g. the channel delivery `capk:channel-deliver:`).
+ * A loss is logged once, by the lock service (`lock lost`, with the key).
  */
-export declare class ConversationLock {
-    private readonly redis;
-    private readonly log?;
+export declare class ConversationLeases {
+    protected readonly locks: LockService;
     private readonly keyPrefix;
-    /** `keyPrefix`：同样语义、按会话互斥的其他用途用别的前缀（如渠道出站投递 `capk:channel-deliver:`）。 */
-    constructor(redis: Redis, log?: Pick<Logger, "warn"> | undefined, keyPrefix?: string);
+    constructor(locks: LockService, keyPrefix: string);
     private lockKey;
     acquire(conversationId: string, runId: string, ttlMs?: number): Promise<Lease | null>;
     /**
@@ -38,3 +38,12 @@ export declare class ConversationLock {
     /** 当前持有者的 runId；无人持有 → null。 */
     holder(conversationId: string): Promise<string | null>;
 }
+/**
+ * 会话级运行锁（spec 4.3「同一会话同一时刻只跑一轮」）：Redis 键 `capk:conv-run:<id>`，值为 runId，
+ * 带 TTL，由 {@link LockService} 每 TTL/3 续租。持有方崩溃时停止续租，锁在 TTL 后过期，其他副本可以取得。
+ */
+export declare class ConversationLock extends ConversationLeases {
+    constructor(locks: LockService);
+    /** The same per-conversation lease under another key prefix (another purpose). */
+    scoped(keyPrefix: string): ConversationLeases;
+}