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

package/dist/runtime/providers.js

@@ -1,20 +1,39 @@
+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 { assertValidDeclarations, EFFORT_VALUES, parseExtensionPoint, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable, Module, Optional } from "@nestjs/common";
 import { ApiError } from "../errors.js";
+import { ExtensionRegistry, ExtensionRegistryModule } from "../extensions/registry.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { Cacheable } from "../infra/cache/cacheable.decorator.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
 /** 供应商模型列表在 Redis 中的缓存时长（秒）。 */
 const MODELS_TTL_SECONDS = 600;
 /** 单个供应商 `listModels()` 的时限（毫秒）：一个卡住的供应商不拖住整个列表与解析。 */
 export const LIST_MODELS_TIMEOUT_MS = 10_000;
+/** Optional provider: the `listModels()` time limit (ms) instead of {@link LIST_MODELS_TIMEOUT_MS} (tests). */
+export const LIST_MODELS_TIMEOUT = Symbol("LIST_MODELS_TIMEOUT");
 /**
  * 列表视图（后台模型页、组织模型页）里列模型失败的供应商在这么多秒内直接标 error、不再请求（Redis，多副本共享）。
  * 只用于列表；`resolve`（运行时）照常每次请求，失败由降级梯子重试。
  */
 export const LIST_FAILURE_TTL_SECONDS = 15;
 /**
- * 键带供应商的契约主版本：插件从 `@1` 升级到 `@2` 后不会读到 `@1`（经适配）时写入的列表
- * （两者都是 `@2` 形状，按形状分辨不出来）。
- * 键还带插件版本与部署配置摘要：插件升级（参数声明可能变了）或改部署配置（如增删模型）后，
- * 各副本立即按新声明校验，不必等旧缓存 TTL 到期。摘要只是哈希，不含配置明文（secret 不进键）。
- * 旧键按 TTL 自然过期。没有版本 / 摘要的条目（测试替身）用 `-` 占位。
+ * The model list's cache key (`@Cacheable` stores it as `cache:<key>`). It carries the provider's
+ * contract major: after a plugin moves from `@1` to `@2` it never reads the list written through
+ * the `@1` adapter (both are `@2`-shaped, the shape cannot tell them apart). It also carries the
+ * plugin version and the deployment config digest: after an upgrade (the parameter declarations may
+ * have changed) or a deployment config change (models added or removed) every replica validates
+ * the new declarations at once instead of waiting for the old entry's TTL. The digest is only a
+ * hash, never config text (no secret in the key). Old keys expire by TTL. Entries without a
+ * version / digest (test doubles) use `-`.
  */
 const modelsKey = (p) => `capk:models:${p.plugin}:v${p.major}:${p.version ?? "-"}:${p.configHash ?? "-"}`;
 /** 列表视图的失败标记（{@link LIST_FAILURE_TTL_SECONDS}），与模型列表同样按版本与配置摘要区分。 */
@@ -71,31 +90,33 @@ export function adaptModelProviderV1(impl) {
         },
     };
 }
-/** 缓存里的条目必须是 `@2` 形状（旧版本内核写入的 `@1` 原始结果没有 `parameters`，视为未命中）。 */
-const isCurrentShape = (models) => Array.isArray(models) &&
-    models.every((m) => typeof m === "object" && m !== null && Array.isArray(m.parameters));
 /**
  * 模型供应商注册表：供应商即提供 `model-provider` 能力的插件（以插件名为供应商名）。
  * 同时支持 `model-provider@1`（经 {@link adaptModelProviderV1} 适配）与 `@2`；
  * 同一插件两者都提供时用 `@2`。`@2` 的 `listModels()` 结果先过 `assertValidDeclarations`，
  * 不合规的供应商不可用（不可重试）。
- * 每个供应商的模型列表（`@2` 形状）缓存在 Redis `capk:models:<provider>:v<主版本>:<插件版本>:<部署配置摘要>`（EX 600），不放进程内存，
- * 多副本共享同一份缓存。
+ * Each provider's model list (`@2`-shaped) is cached in Redis (`@Cacheable`, key
+ * `cache:capk:models:<provider>:v<major>:<plugin version>:<config digest>`, 600 s), never in
+ * process memory: every replica shares it.
  */
-export class ProviderRegistry {
+let ProviderRegistry = class ProviderRegistry {
     host;
+    cacheService;
     kv;
     log;
-    opts;
-    constructor(host, kv, log, opts = {}) {
+    listTimeoutMs;
+    constructor(host, cacheService, kv, log, 
+    /** The `listModels()` time limit. */
+    listTimeoutMs = LIST_MODELS_TIMEOUT_MS) {
         this.host = host;
+        this.cacheService = cacheService;
         this.kv = kv;
         this.log = log;
-        this.opts = opts;
+        this.listTimeoutMs = listTimeoutMs;
     }
     /** `listModels()` 加时限（到时按失败处理，供应商的调用留在后台、结果丢弃）。 */
     async listModelsWithTimeout(impl) {
-        const ms = this.opts.listTimeoutMs ?? LIST_MODELS_TIMEOUT_MS;
+        const ms = this.listTimeoutMs;
         let timer;
         const call = Promise.resolve().then(() => impl.listModels());
         call.catch(() => { });
@@ -141,15 +162,12 @@ export class ProviderRegistry {
             impl: major === 2 ? impl : adaptModelProviderV1(impl),
         }));
     }
-    async models(p) {
+    models(p) {
+        return this.validatedModels(modelsKey(p), p);
+    }
+    /** The provider's validated model list, cached under `key` (see {@link modelsKey}). */
+    async validatedModels(_key, p) {
         const { plugin: provider, major, impl } = p;
-        const key = modelsKey(p);
-        const cached = await this.kv.get(key);
-        if (cached !== null) {
-            const parsed = JSON.parse(cached);
-            if (isCurrentShape(parsed))
-                return parsed;
-        }
         let models;
         try {
             models = await this.listModelsWithTimeout(impl);
@@ -168,7 +186,6 @@ export class ProviderRegistry {
                 throw e;
             }
         }
-        await this.kv.set(key, JSON.stringify(models), "EX", MODELS_TTL_SECONDS);
         return models;
     }
     /** 每个已安装供应商及其模型（按插件加载顺序）；列模型失败或声明不合规的供应商跳过并记 warn。 */
@@ -221,4 +238,28 @@ export class ProviderRegistry {
         }
         return { provider: p.impl, info };
     }
-}
+};
+__decorate([
+    Cacheable({ key: "#{0}", ttl: MODELS_TTL_SECONDS })
+], ProviderRegistry.prototype, "validatedModels", null);
+ProviderRegistry = __decorate([
+    Injectable(),
+    __param(0, Inject(ExtensionRegistry)),
+    __param(1, Inject(CacheService)),
+    __param(2, Inject(REDIS)),
+    __param(3, Inject(KERNEL_LOGGER)),
+    __param(4, Optional()),
+    __param(4, Inject(LIST_MODELS_TIMEOUT))
+], ProviderRegistry);
+export { ProviderRegistry };
+/** The model provider registry (one instance; the models and agents domains read it). */
+let ProvidersModule = class ProvidersModule {
+};
+ProvidersModule = __decorate([
+    Module({
+        imports: [ExtensionRegistryModule],
+        providers: [ProviderRegistry],
+        exports: [ProviderRegistry],
+    })
+], ProvidersModule);
+export { ProvidersModule };

package/dist/runtime/quota.d.ts

@@ -1,6 +1,7 @@
 import type { Redis } from "ioredis";
-import type { KernelConfig } from "../config/schema.js";
 import type { SettingsService } from "../identity/settings.js";
+import type { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import type { LeaseHandle, LockService } from "../infra/lock/lock.service.js";
 /** 组织配额租约的默认时长（毫秒）：持有方每 `leaseMs / 3` 续租一次。 */
 export declare const ORG_QUOTA_LEASE_MS = 60000;
 /** 运行配额的键前缀（`capk:org-runs:<orgId>`）；评测运行用 {@link EVAL_QUOTA_PREFIX}。 */
@@ -11,19 +12,32 @@ export declare const EVAL_QUOTA_PREFIX = "capk:org-evals:";
  * 组织级运行并发配额（spec 4.3）：Redis ZSET `<keyPrefix><orgId>`（默认 `capk:org-runs:<orgId>`），
  * 成员 runId（评测为 jobId）、分数为租约到期时间。
  * 持有方崩溃时不 `leave`，成员在租约到期后被下一次 `tryEnter` 清理，名额不泄漏。
+ * One instance per key prefix, provided under {@link RUN_QUOTA} / {@link EVAL_QUOTA}.
  */
 export declare class OrgQuota {
     private readonly redis;
     private readonly keyPrefix;
-    constructor(redis: Redis, keyPrefix?: string);
+    private readonly locks?;
+    constructor(redis: Redis, keyPrefix?: string, locks?: LockService | undefined);
     private key;
     tryEnter(orgId: string, runId: string, limit: number, leaseMs?: number): Promise<boolean>;
     /** 续期；成员已过期被清理 → false。 */
     renew(orgId: string, runId: string, leaseMs?: number): Promise<boolean>;
     leave(orgId: string, runId: string): Promise<void>;
+    /**
+     * Takes a slot ({@link tryEnter}) and keeps it while held: renewed every `leaseMs / 3` by the
+     * lock service's watchdog; `release()` leaves. Undefined when the organization is at its limit.
+     * A slot that could not be renewed (it expired meanwhile) aborts `lost` with one WARN; the
+     * holder may go on (the slot is a fair-share limit, not mutual exclusion).
+     */
+    enter(orgId: string, runId: string, limit: number, leaseMs?: number): Promise<LeaseHandle | undefined>;
 }
+/** The organization run quota (`capk:org-runs:<orgId>`). */
+export declare const RUN_QUOTA: unique symbol;
+/** The organization eval quota (`capk:org-evals:<orgId>`). */
+export declare const EVAL_QUOTA: unique symbol;
 /**
  * 组织的运行并发上限：部署设置 `runConcurrencyOverrides[orgId]`，没有则用 `runtime.orgConcurrency`
  * （热更新字段，每次经 `config()` 读当前值）。
  */
-export declare function orgRunLimit(settings: Pick<SettingsService, "get">, config: () => KernelConfig, orgId: string): Promise<number>;
+export declare function orgRunLimit(settings: Pick<SettingsService, "get">, config: Pick<KernelConfigService, "get">, orgId: string): Promise<number>;

package/dist/runtime/quota.js

@@ -38,13 +38,16 @@ return 0
  * 组织级运行并发配额（spec 4.3）：Redis ZSET `<keyPrefix><orgId>`（默认 `capk:org-runs:<orgId>`），
  * 成员 runId（评测为 jobId）、分数为租约到期时间。
  * 持有方崩溃时不 `leave`，成员在租约到期后被下一次 `tryEnter` 清理，名额不泄漏。
+ * One instance per key prefix, provided under {@link RUN_QUOTA} / {@link EVAL_QUOTA}.
  */
 export class OrgQuota {
     redis;
     keyPrefix;
-    constructor(redis, keyPrefix = RUN_QUOTA_PREFIX) {
+    locks;
+    constructor(redis, keyPrefix = RUN_QUOTA_PREFIX, locks) {
         this.redis = redis;
         this.keyPrefix = keyPrefix;
+        this.locks = locks;
     }
     key(orgId) {
         return `${this.keyPrefix}${orgId}`;
@@ -59,12 +62,34 @@ export class OrgQuota {
     async leave(orgId, runId) {
         await this.redis.zrem(this.key(orgId), runId);
     }
+    /**
+     * Takes a slot ({@link tryEnter}) and keeps it while held: renewed every `leaseMs / 3` by the
+     * lock service's watchdog; `release()` leaves. Undefined when the organization is at its limit.
+     * A slot that could not be renewed (it expired meanwhile) aborts `lost` with one WARN; the
+     * holder may go on (the slot is a fair-share limit, not mutual exclusion).
+     */
+    async enter(orgId, runId, limit, leaseMs = ORG_QUOTA_LEASE_MS) {
+        const locks = this.locks;
+        if (!locks)
+            throw new Error("OrgQuota.enter needs the lock service");
+        const sentAt = Date.now();
+        if (!(await this.tryEnter(orgId, runId, limit, leaseMs)))
+            return undefined;
+        return locks.keepAlive(`${this.key(orgId)}/${runId}`, leaseMs, {
+            renew: () => this.renew(orgId, runId, leaseMs),
+            release: () => this.leave(orgId, runId),
+        }, sentAt);
+    }
 }
+/** The organization run quota (`capk:org-runs:<orgId>`). */
+export const RUN_QUOTA = Symbol("RUN_QUOTA");
+/** The organization eval quota (`capk:org-evals:<orgId>`). */
+export const EVAL_QUOTA = Symbol("EVAL_QUOTA");
 /**
  * 组织的运行并发上限：部署设置 `runConcurrencyOverrides[orgId]`，没有则用 `runtime.orgConcurrency`
  * （热更新字段，每次经 `config()` 读当前值）。
  */
 export async function orgRunLimit(settings, config, orgId) {
     const { runConcurrencyOverrides } = await settings.get();
-    return runConcurrencyOverrides[orgId] ?? config().runtime.orgConcurrency;
+    return runConcurrencyOverrides[orgId] ?? config.get().runtime.orgConcurrency;
 }

package/dist/runtime/retired-schedulers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Job scheduler ids of the maintenance queue's fixed-period jobs before they became `@LockedCron` /
+ * `@LockedInterval` jobs: an upgraded deployment still has them in Redis, so a starting worker
+ * role removes them (else BullMQ keeps firing a job no handler knows). Each id
+ * comes from its domain's leaf `job-ids.ts`, so this module imports no domain code.
+ */
+export declare const RETIRED_SCHEDULER_IDS: readonly string[];

package/dist/runtime/retired-schedulers.js

@@ -0,0 +1,31 @@
+import { MARKETPLACES_REFRESH_SCHEDULER_ID, PLUGIN_STAGING_CLEANUP_SCHEDULER_ID, } from "../catalog/job-ids.js";
+import { GATEWAY_CHECK_SCHEDULER_ID } from "../channels/job-ids.js";
+import { ATTACHMENT_CLEANUP_SCHEDULER_ID } from "../conversations/job-ids.js";
+import { PLUGINS_RECONCILE_SCHEDULER_ID } from "../extensions/job-ids.js";
+import { DIRECTORY_SCAN_SCHEDULER_ID, OFFBOARD_SWEEP_SCHEDULER_ID } from "../orgs/job-ids.js";
+import { SANDBOX_DESTROY_SCHEDULER_ID, SANDBOX_SUSPEND_SCHEDULER_ID } from "../sandbox/job-ids.js";
+import { STORAGE_PURGE_SCHEDULER_ID } from "../storage/job-ids.js";
+import { DRIFT_SCHEDULER_ID, OUTPUT_CLEANUP_SCHEDULER_ID } from "../tools/job-ids.js";
+import { USAGE_SWEEP_SCHEDULER_ID, WAIT_SWEEP_SCHEDULER_ID } from "./job-ids.js";
+/**
+ * Job scheduler ids of the maintenance queue's fixed-period jobs before they became `@LockedCron` /
+ * `@LockedInterval` jobs: an upgraded deployment still has them in Redis, so a starting worker
+ * role removes them (else BullMQ keeps firing a job no handler knows). Each id
+ * comes from its domain's leaf `job-ids.ts`, so this module imports no domain code.
+ */
+export const RETIRED_SCHEDULER_IDS = [
+    STORAGE_PURGE_SCHEDULER_ID,
+    DIRECTORY_SCAN_SCHEDULER_ID,
+    OFFBOARD_SWEEP_SCHEDULER_ID,
+    PLUGINS_RECONCILE_SCHEDULER_ID,
+    MARKETPLACES_REFRESH_SCHEDULER_ID,
+    PLUGIN_STAGING_CLEANUP_SCHEDULER_ID,
+    DRIFT_SCHEDULER_ID,
+    OUTPUT_CLEANUP_SCHEDULER_ID,
+    ATTACHMENT_CLEANUP_SCHEDULER_ID,
+    WAIT_SWEEP_SCHEDULER_ID,
+    USAGE_SWEEP_SCHEDULER_ID,
+    GATEWAY_CHECK_SCHEDULER_ID,
+    SANDBOX_SUSPEND_SCHEDULER_ID,
+    SANDBOX_DESTROY_SCHEDULER_ID,
+];

package/dist/runtime/run-control.d.ts

@@ -0,0 +1,33 @@
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import type { KernelLogger } from "../log.js";
+import { RunAbort } from "./abort.js";
+import { RunQueue } from "./run-queue.js";
+import { Waits } from "./waits.js";
+/**
+ * Starting and stopping runs from outside the run worker: the conversations API (a message, a
+ * stop), the conversation queue and offboarding (a departed member's runs, `by: null`).
+ */
+export declare class RunControl {
+    private readonly queue;
+    private readonly waits;
+    private readonly abort;
+    private readonly events;
+    private readonly log;
+    constructor(queue: Pick<RunQueue, "ensureRun" | "abortIfOrphaned">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren">, abort: Pick<RunAbort, "request">, events: KernelEvents, log: Pick<KernelLogger, "error">);
+    /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
+    ensureRun(conversationId: string): Promise<string | null>;
+    /**
+     * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
+     * 否则返回 false。A stopped sub-agent then reports to its parent at once, and a stopped parent
+     * stops its children (sub-agents spec §12).
+     */
+    abortIfOrphaned(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    /**
+     * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
+     * 运行已不是 waiting（例如刚被续跑）→ false. Either way its approval / question cards may have
+     * changed: `run.wait-stopped` lets the channel outbound update them.
+     */
+    abortWaiting(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    /** 请求中止运行（广播到所有副本）。 */
+    requestAbort(runId: string, byAccountId: string | null): Promise<void>;
+}

package/dist/runtime/run-control.js

@@ -0,0 +1,77 @@
+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 { KernelEvents } from "../infra/events/kernel-events.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { RunAbort } from "./abort.js";
+import { RunQueue } from "./run-queue.js";
+import { Waits } from "./waits.js";
+/**
+ * Starting and stopping runs from outside the run worker: the conversations API (a message, a
+ * stop), the conversation queue and offboarding (a departed member's runs, `by: null`).
+ */
+let RunControl = class RunControl {
+    queue;
+    waits;
+    abort;
+    events;
+    log;
+    constructor(queue, waits, abort, events, log) {
+        this.queue = queue;
+        this.waits = waits;
+        this.abort = abort;
+        this.events = events;
+        this.log = log;
+    }
+    /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
+    ensureRun(conversationId) {
+        return this.queue.ensureRun(conversationId);
+    }
+    /**
+     * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
+     * 否则返回 false。A stopped sub-agent then reports to its parent at once, and a stopped parent
+     * stops its children (sub-agents spec §12).
+     */
+    async abortIfOrphaned(conversationId, runId, byAccountId) {
+        const r = await this.queue.abortIfOrphaned(conversationId, runId, byAccountId);
+        if (r) {
+            await this.waits
+                .childFinished(runId)
+                .catch((err) => this.log.error("cannot report finished sub-agent run to its parent", { runId, err }));
+            await this.waits
+                .stopChildren(runId, null)
+                .catch((err) => this.log.error("cannot stop the sub-agents of a run", { runId, err }));
+        }
+        return r;
+    }
+    /**
+     * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
+     * 运行已不是 waiting（例如刚被续跑）→ false. Either way its approval / question cards may have
+     * changed: `run.wait-stopped` lets the channel outbound update them.
+     */
+    async abortWaiting(conversationId, runId, byAccountId) {
+        const r = await this.waits.abortWaiting(conversationId, runId, byAccountId);
+        await this.events.emit("run.wait-stopped", { conversationId, runId });
+        return r;
+    }
+    /** 请求中止运行（广播到所有副本）。 */
+    requestAbort(runId, byAccountId) {
+        return this.abort.request(runId, byAccountId);
+    }
+};
+RunControl = __decorate([
+    Injectable(),
+    __param(0, Inject(RunQueue)),
+    __param(1, Inject(Waits)),
+    __param(2, Inject(RunAbort)),
+    __param(3, Inject(KernelEvents)),
+    __param(4, Inject(KERNEL_LOGGER))
+], RunControl);
+export { RunControl };

package/dist/runtime/run-finish.d.ts

@@ -1,7 +1,6 @@
-import { type Transaction } from "kysely";
-import type { AppendEvent, EventLog } from "../conversations/event-log.js";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-type KernelTrx = Transaction<KernelDatabase>;
+import { type AppendEvent, EventLog } from "../conversations/event-log.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
 /** 运行的终态。 */
 export type TerminalStatus = "completed" | "failed" | "aborted";
 export declare const TERMINAL_STATUSES: ReadonlySet<string>;
@@ -22,24 +21,34 @@ export interface FinishRunArgs {
      * Runs in the transaction once the run is known not to be terminal, before the terminal event:
      * a parent's open `agent` calls get their results here (sub-agents spec §12, review m1).
      */
-    beforeTerminal?: (t: KernelTrx) => Promise<void>;
+    beforeTerminal?: () => Promise<void>;
 }
 /**
- * 在事务 `t` 内写运行的终态：会话行锁 → 运行仍未结束才写终态事件、推进 `consumed_seq`、更新 `runs.status`。
- * 返回终态事件的 seq；运行已是终态（例如已被其他副本标记失败）→ 返回 null，什么都不写。
- *
- * `consumed_seq = GREATEST(consumed_seq, consumed, runs.trigger_seq)`：不回退，且失败 / 中止 / 完成都至少
- * 消费到触发该运行的消息——否则结束时的 ensureRun 会对同一条消息无限重试（失败）或卡住会话。
- * 超时（`floorToTrigger: false`）只取 `GREATEST(consumed_seq, consumed)`：没吸收的消息留给下一轮（R34）。
- * 加锁顺序与 `RunQueue.ensureRun` 一致（先会话行、后 runs 行），不会互相死锁。
- * 调用方在提交后对非 null 的返回值调用 `eventLog.notify`。
+ * Writes runs' terminal states (one instance; the run worker, the run queue's orphan repairs, the
+ * waits and the eval replays finish runs through it).
  */
-export declare function finishRunIn(t: KernelTrx, eventLog: EventLog, a: FinishRunArgs): Promise<number | null>;
+export declare class RunFinish {
+    private readonly kdb;
+    private readonly eventLog;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, eventLog: EventLog, txHost: TransactionHost);
+    /**
+     * 在调用方的事务内写运行的终态：会话行锁 → 运行仍未结束才写终态事件、推进 `consumed_seq`、更新 `runs.status`。
+     * 返回终态事件的 seq；运行已是终态（例如已被其他副本标记失败）→ 返回 null，什么都不写。
+     *
+     * `consumed_seq = GREATEST(consumed_seq, consumed, runs.trigger_seq)`：不回退，且失败 / 中止 / 完成都至少
+     * 消费到触发该运行的消息——否则结束时的 ensureRun 会对同一条消息无限重试（失败）或卡住会话。
+     * 超时（`floorToTrigger: false`）只取 `GREATEST(consumed_seq, consumed)`：没吸收的消息留给下一轮（R34）。
+     * 加锁顺序与 `RunQueue.ensureRun` 一致（先会话行、后 runs 行），不会互相死锁。
+     * 调用方在提交后对非 null 的返回值调用 {@link notifyFinished}。
+     */
+    finishIn(a: FinishRunArgs): Promise<number | null>;
+    /** 自开事务写终态并在提交后发布会话通知；返回值同 {@link finishIn}。 */
+    finish(a: FinishRunArgs): Promise<number | null>;
+    private finishOwn;
+}
 /**
  * After a terminal event committed: notify the log, and for a failed or stopped run also send
  * `changed: queue` (the queue may have paused).
  */
 export declare function notifyFinished(eventLog: Pick<EventLog, "notify" | "publishChanged">, conversationId: string, toSeq: number, status: TerminalStatus): Promise<void>;
-/** 自开事务写终态并在提交后发布会话通知；返回值同 {@link finishRunIn}。 */
-export declare function finishRun(db: KernelDb, eventLog: EventLog, a: FinishRunArgs): Promise<number | null>;
-export {};

package/dist/runtime/run-finish.js

@@ -1,56 +1,110 @@
+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 { sql } from "kysely";
+import { EventLog } from "../conversations/event-log.js";
 import { pauseQueueIn } from "../conversations/queue.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
 export const TERMINAL_STATUSES = new Set([
     "completed",
     "failed",
     "aborted",
 ]);
 /**
- * 在事务 `t` 内写运行的终态：会话行锁 → 运行仍未结束才写终态事件、推进 `consumed_seq`、更新 `runs.status`。
- * 返回终态事件的 seq；运行已是终态（例如已被其他副本标记失败）→ 返回 null，什么都不写。
- *
- * `consumed_seq = GREATEST(consumed_seq, consumed, runs.trigger_seq)`：不回退，且失败 / 中止 / 完成都至少
- * 消费到触发该运行的消息——否则结束时的 ensureRun 会对同一条消息无限重试（失败）或卡住会话。
- * 超时（`floorToTrigger: false`）只取 `GREATEST(consumed_seq, consumed)`：没吸收的消息留给下一轮（R34）。
- * 加锁顺序与 `RunQueue.ensureRun` 一致（先会话行、后 runs 行），不会互相死锁。
- * 调用方在提交后对非 null 的返回值调用 `eventLog.notify`。
+ * Writes runs' terminal states (one instance; the run worker, the run queue's orphan repairs, the
+ * waits and the eval replays finish runs through it).
  */
-export async function finishRunIn(t, eventLog, a) {
-    await t
-        .selectFrom("conversations")
-        .select("id")
-        .where("id", "=", a.conversationId)
-        .forUpdate()
-        .executeTakeFirst();
-    const run = await t
-        .selectFrom("runs")
-        .select("status")
-        .where("id", "=", a.runId)
-        .forUpdate()
-        .executeTakeFirst();
-    if (!run || TERMINAL_STATUSES.has(run.status))
-        return null;
-    await a.beforeTerminal?.(t);
-    const [ev] = await eventLog.append(a.conversationId, [{ ...a.event, runId: a.runId, idemKey: `${a.event.type}:${a.runId}` }], t);
-    await t
-        .updateTable("conversations")
-        .set({
-        consumed_seq: a.floorToTrigger === false
-            ? sql `GREATEST(consumed_seq, ${a.consumed ?? 0}::bigint)`
-            : sql `GREATEST(consumed_seq, ${a.consumed ?? 0}::bigint, (SELECT r.trigger_seq FROM capybara.runs r WHERE r.id = ${a.runId}))`,
-    })
-        .where("id", "=", a.conversationId)
-        .execute();
-    await t
-        .updateTable("runs")
-        .set({ status: a.status, finished_at: sql `now()` })
-        .where("id", "=", a.runId)
-        .execute();
-    // a failed or stopped run pauses the queued messages until the person resumes (spec §5.7)
-    if (a.status !== "completed")
-        await pauseQueueIn(t, a.conversationId);
-    return ev.seq;
-}
+let RunFinish = class RunFinish {
+    kdb;
+    eventLog;
+    txHost;
+    constructor(kdb, eventLog, txHost) {
+        this.kdb = kdb;
+        this.eventLog = eventLog;
+        this.txHost = txHost;
+    }
+    /**
+     * 在调用方的事务内写运行的终态：会话行锁 → 运行仍未结束才写终态事件、推进 `consumed_seq`、更新 `runs.status`。
+     * 返回终态事件的 seq；运行已是终态（例如已被其他副本标记失败）→ 返回 null，什么都不写。
+     *
+     * `consumed_seq = GREATEST(consumed_seq, consumed, runs.trigger_seq)`：不回退，且失败 / 中止 / 完成都至少
+     * 消费到触发该运行的消息——否则结束时的 ensureRun 会对同一条消息无限重试（失败）或卡住会话。
+     * 超时（`floorToTrigger: false`）只取 `GREATEST(consumed_seq, consumed)`：没吸收的消息留给下一轮（R34）。
+     * 加锁顺序与 `RunQueue.ensureRun` 一致（先会话行、后 runs 行），不会互相死锁。
+     * 调用方在提交后对非 null 的返回值调用 {@link notifyFinished}。
+     */
+    async finishIn(a) {
+        const t = this.kdb.db;
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", a.conversationId)
+            .forUpdate()
+            .executeTakeFirst();
+        const run = await t
+            .selectFrom("runs")
+            .select("status")
+            .where("id", "=", a.runId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!run || TERMINAL_STATUSES.has(run.status))
+            return null;
+        await a.beforeTerminal?.();
+        const [ev] = await this.eventLog.appendIn(a.conversationId, [
+            { ...a.event, runId: a.runId, idemKey: `${a.event.type}:${a.runId}` },
+        ]);
+        await t
+            .updateTable("conversations")
+            .set({
+            consumed_seq: a.floorToTrigger === false
+                ? sql `GREATEST(consumed_seq, ${a.consumed ?? 0}::bigint)`
+                : sql `GREATEST(consumed_seq, ${a.consumed ?? 0}::bigint, (SELECT r.trigger_seq FROM capybara.runs r WHERE r.id = ${a.runId}))`,
+        })
+            .where("id", "=", a.conversationId)
+            .execute();
+        await t
+            .updateTable("runs")
+            .set({ status: a.status, finished_at: sql `now()` })
+            .where("id", "=", a.runId)
+            .execute();
+        // a failed or stopped run pauses the queued messages until the person resumes (spec §5.7)
+        if (a.status !== "completed")
+            await pauseQueueIn(t, a.conversationId);
+        return ev.seq;
+    }
+    /** 自开事务写终态并在提交后发布会话通知；返回值同 {@link finishIn}。 */
+    async finish(a) {
+        const toSeq = await this.finishOwn(a);
+        if (toSeq !== null)
+            await notifyFinished(this.eventLog, a.conversationId, toSeq, a.status);
+        return toSeq;
+    }
+    finishOwn(a) {
+        return this.finishIn(a);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], RunFinish.prototype, "finishIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], RunFinish.prototype, "finishOwn", null);
+RunFinish = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(TransactionHost))
+], RunFinish);
+export { RunFinish };
 /**
  * After a terminal event committed: notify the log, and for a failed or stopped run also send
  * `changed: queue` (the queue may have paused).
@@ -60,10 +114,3 @@ export async function notifyFinished(eventLog, conversationId, toSeq, status) {
     if (status !== "completed")
         await eventLog.publishChanged(conversationId, "queue");
 }
-/** 自开事务写终态并在提交后发布会话通知；返回值同 {@link finishRunIn}。 */
-export async function finishRun(db, eventLog, a) {
-    const toSeq = await db.transaction().execute((t) => finishRunIn(t, eventLog, a));
-    if (toSeq !== null)
-        await notifyFinished(eventLog, a.conversationId, toSeq, a.status);
-    return toSeq;
-}