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

package/dist/conversations/titles.js

@@ -1,12 +1,30 @@
+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 { isModelError, } from "@capybara-hq/plugin-sdk";
-import { Queue, Worker } from "bullmq";
+import { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable, Module } from "@nestjs/common";
 import { sql } from "kysely";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { ExtensionHost } from "../extensions/host.js";
 import { audit } from "../identity/audit.js";
-import { withJobContext } from "../log-context.js";
-import { PurposeAttemptError } from "../models/purposes.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";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ModelsModule } from "../models/models.module.js";
+import { ModelPurposesService, PurposeAttemptError } from "../models/purposes.js";
 import { fireObserve, hookDeniedAudit, hookDeniedEvent, hookRequestOf, } from "../runtime/hook-calls.js";
-import { bullConnection } from "../runtime/run-queue.js";
+import { UsageReporter, UsageReportModule } from "../runtime/usage-report.js";
 import { HIDDEN_FORMAT_RE } from "../text.js";
+import { EventLog, EventLogModule } from "./event-log.js";
 import { typedInvocation } from "./events.js";
 /**
  * Model-generated conversation titles (UI refresh B, spec §5.1 "Titles").
@@ -228,23 +246,7 @@ export async function runTitleJob(d, conversationId, attempt) {
     if (sent && d.hooks)
         observeTitle(d, scope, sent, out, null, signal);
     const title = cleanTitle(textOf(out.content));
-    const { written, usage } = await d.db.transaction().execute(async (t) => {
-        // Append first: it locks the conversation row FOR UPDATE before this transaction touches it.
-        // Updating the title first held the row FOR NO KEY UPDATE, which lets in another
-        // transaction's foreign key check (FOR KEY SHARE, e.g. inserting an approval); the append's
-        // FOR UPDATE then waited for that one while it waited for the title row: 40P01
-        const [ev] = await d.eventLog.append(conversationId, [usageEvent(attempt, out)], t);
-        const row = title === null
-            ? undefined
-            : await t
-                .updateTable("conversations")
-                .set({ title, title_source: "generated" })
-                .where("id", "=", conversationId)
-                .where("title_source", "is", null)
-                .returning("id")
-                .executeTakeFirst();
-        return { written: row !== undefined, usage: ev };
-    });
+    const { written, usage } = await d.writes.writeResult(conversationId, attempt, out, title);
     if (usage) {
         await d.eventLog.notify(conversationId, usage.seq);
         void d.usageReport?.enqueue(conversationId, usage.seq);
@@ -313,7 +315,7 @@ async function checkTitleHooks(d, scope, target, request, signal) {
     };
     const entry = hookDeniedAudit(site, hookDeniedEvent(site, "model.request", verdict, { step: 0, attempt: 1 }).payload, verdict);
     entry.detail = { ...entry.detail, purpose: "title" };
-    await d.db.transaction().execute((t) => audit(t, entry));
+    await d.writes.auditDenied(entry);
     d.log.warn("conversation title blocked by a policy hook", {
         conversationId: scope.conversationId,
         plugin: verdict.plugin,
@@ -344,31 +346,118 @@ function observeTitle(d, scope, sent, out, err, signal) {
         ...(out === null && { errorCode: errorCodeOf(err) }),
     }, signal, d.log);
 }
+/**
+ * One title attempt's work ({@link runTitleJob}) over the injected services, with its writes in
+ * transactions of their own: the title with the call's usage event, and a policy denial's audit row.
+ */
+let TitleGenerator = class TitleGenerator {
+    kdb;
+    eventLog;
+    purposes;
+    host;
+    usageReport;
+    log;
+    txHost;
+    constructor(kdb, eventLog, purposes, 
+    /** The title call fires the plugin hooks (`model.request`, `model.response`). */
+    host, usageReport, log, txHost) {
+        this.kdb = kdb;
+        this.eventLog = eventLog;
+        this.purposes = purposes;
+        this.host = host;
+        this.usageReport = usageReport;
+        this.log = log;
+        this.txHost = txHost;
+    }
+    /** One attempt ({@link runTitleJob}); `signal` aborts the call (the worker stopping). */
+    run(conversationId, attempt, signal) {
+        const kdb = this.kdb;
+        const hooks = this.host?.hooks;
+        return runTitleJob({
+            get db() {
+                return kdb.db;
+            },
+            eventLog: this.eventLog,
+            purposes: this.purposes,
+            log: this.log,
+            ...(hooks !== undefined && { hooks }),
+            ...(this.usageReport !== undefined && { usageReport: this.usageReport }),
+            ...(signal !== undefined && { signal }),
+            writes: this,
+        }, conversationId, attempt);
+    }
+    /**
+     * Appends the call's `usage` event and writes the title while `title_source IS NULL` (a rename
+     * wins), in one transaction.
+     */
+    async writeResult(conversationId, attempt, out, title) {
+        // Append first: it locks the conversation row FOR UPDATE before this transaction touches it.
+        // Updating the title first held the row FOR NO KEY UPDATE, which lets in another
+        // transaction's foreign key check (FOR KEY SHARE, e.g. inserting an approval); the append's
+        // FOR UPDATE then waited for that one while it waited for the title row: 40P01
+        const [ev] = await this.eventLog.appendIn(conversationId, [usageEvent(attempt, out)]);
+        const row = title === null
+            ? undefined
+            : await this.kdb.db
+                .updateTable("conversations")
+                .set({ title, title_source: "generated" })
+                .where("id", "=", conversationId)
+                .where("title_source", "is", null)
+                .returning("id")
+                .executeTakeFirst();
+        return { written: row !== undefined, usage: ev };
+    }
+    /** The `hook.denied` audit row of a denied title call. */
+    async auditDenied(entry) {
+        await audit(this.kdb.db, entry);
+    }
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], TitleGenerator.prototype, "writeResult", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], TitleGenerator.prototype, "auditDenied", null);
+TitleGenerator = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(ModelPurposesService)),
+    __param(3, Inject(ExtensionHost)),
+    __param(4, Inject(UsageReporter)),
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(TransactionHost))
+], TitleGenerator);
+export { TitleGenerator };
 /**
  * The title queue: `maybeEnqueue` on any role (called by the run worker after a completed run),
- * the worker on the `worker` role. One attempt per job, no BullMQ retries: the next completed run
- * enqueues the next attempt.
+ * consumed on the `worker` role by its `@Processor`. One attempt per job, no BullMQ retries: the
+ * next completed run enqueues the next attempt.
  */
-export class TitleQueue {
-    d;
+let TitleQueue = class TitleQueue {
+    kdb;
     queue;
-    queueConn;
+    generator;
+    log;
     worker;
-    workerConn;
     closed = false;
     stopping = new AbortController();
-    constructor(d) {
-        this.d = d;
+    constructor(kdb, queue, generator, log) {
+        this.kdb = kdb;
+        this.queue = queue;
+        this.generator = generator;
+        this.log = log;
+        queue.on("error", (err) => this.log.error("title queue error", { err }));
     }
     /** Enqueues the next title attempt when one is due. Never throws (logs instead). */
     async maybeEnqueue(conversationId) {
         if (this.closed)
             return;
         try {
-            const attempt = await titleAttemptDue(this.d.db, conversationId);
+            const attempt = await titleAttemptDue(this.kdb.db, conversationId);
             if (attempt === null)
                 return;
-            await this.getQueue().add(JOB, { conversationId, attempt }, {
+            await this.queue.add(JOB, { conversationId, attempt }, {
                 jobId: titleJobId(conversationId, attempt),
                 attempts: 1,
                 removeOnComplete: true,
@@ -376,48 +465,55 @@ export class TitleQueue {
             });
         }
         catch (err) {
-            this.d.log.warn("cannot enqueue conversation title", { conversationId, err });
+            this.log.warn("cannot enqueue conversation title", { conversationId, err });
         }
     }
-    startWorker() {
+    /** Starts consuming (worker role only): `worker` is the `@Processor` worker of {@link TITLE_QUEUE}. */
+    startWorker(worker) {
         if (this.worker || this.closed)
             return;
-        const { jobLockMs, stalledIntervalMs } = this.d.config().runtime;
-        this.workerConn = bullConnection(this.d.redisUrl, this.d.log);
-        this.worker = new Worker(TITLE_QUEUE, (j) => withJobContext(TITLE_QUEUE, j, () => this.process(j)), {
-            connection: this.workerConn,
-            concurrency: 4,
-            lockDuration: jobLockMs,
-            stalledInterval: stalledIntervalMs,
-            maxStalledCount: 1,
-        });
-        this.worker.on("error", (err) => this.d.log.error("title worker error", { err }));
+        this.worker = worker;
+        void worker.run().catch((err) => this.log.error("title worker error", { err }));
+    }
+    /** The worker's `error` event. */
+    onError(err) {
+        this.log.error("title worker error", { err });
     }
+    /** One title job (the `@Processor` calls it). */
     async process(j) {
-        await runTitleJob({ ...this.d, signal: this.stopping.signal }, j.data.conversationId, j.data.attempt);
+        await this.generator.run(j.data.conversationId, j.data.attempt, this.stopping.signal);
     }
+    /** Stops: no more enqueues, the call in flight is aborted, the worker closes. */
     async stop() {
         this.closed = true;
         this.stopping.abort();
         const w = this.worker;
         this.worker = undefined;
         await w?.close().catch(() => { });
-        const q = this.queue;
-        this.queue = undefined;
-        await q?.close().catch(() => { });
-        for (const c of [this.workerConn, this.queueConn]) {
-            if (c)
-                await c.quit().catch(() => c.disconnect());
-        }
-        this.workerConn = undefined;
-        this.queueConn = undefined;
     }
-    getQueue() {
-        if (!this.queue) {
-            this.queueConn = bullConnection(this.d.redisUrl, this.d.log);
-            this.queue = new Queue(TITLE_QUEUE, { connection: this.queueConn });
-            this.queue.on("error", (err) => this.d.log.error("title queue error", { err }));
-        }
-        return this.queue;
-    }
-}
+};
+TitleQueue = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(getQueueToken(TITLE_QUEUE))),
+    __param(2, Inject(TitleGenerator)),
+    __param(3, Inject(KERNEL_LOGGER))
+], TitleQueue);
+export { TitleQueue };
+/** Conversation titles: the queue and the job (consumed on the worker role). */
+let TitlesModule = class TitlesModule {
+};
+TitlesModule = __decorate([
+    Module({
+        imports: [
+            EventLogModule,
+            ModelsModule,
+            ExtensionsModule,
+            UsageReportModule,
+            QueueModule.registerQueue(TITLE_QUEUE),
+        ],
+        providers: [TitleGenerator, TitleQueue],
+        exports: [TitleQueue],
+    })
+], TitlesModule);
+export { TitlesModule };

package/dist/ctx/bus.js

@@ -1,3 +1,5 @@
+import { runOutsideTransaction } from "../infra/database/transaction-host.js";
+import { withoutLogContext } from "../log-context.js";
 import { assertNamespace } from "./namespace.js";
 /** 未注入 logger 时的兜底：输出到 stderr。 */
 const consoleLog = {
@@ -19,9 +21,13 @@ export function createBusSubscriber(subFactory, log = consoleLog) {
             return conn;
         const c = subFactory();
         c.on("message", (channel, message) => {
-            for (const h of [...(channels.get(channel)?.handlers ?? [])]) {
-                invokeIsolated(log, channel, () => h(message));
-            }
+            // the connection's callbacks carry the async context of the first subscribe (a request's
+            // log fields, possibly an open transaction): every handler starts from an empty one
+            runOutsideTransaction(() => withoutLogContext(() => {
+                for (const h of [...(channels.get(channel)?.handlers ?? [])]) {
+                    invokeIsolated(log, channel, () => h(message));
+                }
+            }));
         });
         c.on("error", (err) => log.error("bus subscriber connection error", { err }));
         conn = c;

package/dist/ctx/create-ctx.d.ts

@@ -3,6 +3,8 @@ import type { Redis } from "ioredis";
 import { Kysely } from "kysely";
 import { type RegisteredHook } from "../extensions/hooks.js";
 import { RegistrationLedger } from "../extensions/ledger.js";
+import type { LockService } from "../infra/lock/lock.service.js";
+import type { EmbedTokens } from "../ui/embed-token.js";
 import { type UiActionHandler, type UiRender } from "../ui/registry.js";
 import { type BusSubscriber } from "./bus.js";
 import { type Keyring } from "./secrets.js";
@@ -13,9 +15,13 @@ export interface KernelDeps {
     /** PG 建立连接的超时（迁移器的独立连接使用）。 */
     connectTimeoutMs?: number;
     redis: Redis;
+    /** The kernel's lock primitives (`ctx.lock`, the dedupe markers). */
+    locks: Pick<LockService, "lease" | "renew" | "releaseIf">;
     busSubscriber: BusSubscriber;
     redisUrl: string;
     keyring: Keyring;
+    /** Verifies embed tokens (`ctx.ui` embed requests; the one `EmbedTokens` provider). */
+    embedTokens: Pick<EmbedTokens, "verify">;
     runWorkers: boolean;
     /** 内核 logger（`debug` 可选：插件 Logger 没有它，测试可不给）。 */
     log: Logger & {

package/dist/ctx/create-ctx.js

@@ -6,8 +6,7 @@ import { enabledExtensionsQuery, isExtensionEnabled } from "../extensions/enable
 import { checkHookRegistration } from "../extensions/hooks.js";
 import { RegistrationLedger } from "../extensions/ledger.js";
 import { audit } from "../identity/audit.js";
-import { StorageService } from "../storage/storage.service.js";
-import { EmbedTokens } from "../ui/embed-token.js";
+import { PrefixedStorage } from "../storage/storage.service.js";
 import { canUsePlace, orgUiTopic, PluginUiRegistration, } from "../ui/registry.js";
 import { createBus } from "./bus.js";
 import { createKv } from "./kv.js";
@@ -58,16 +57,15 @@ async function invalidateTargetOk(db, plugin, orgId, conversationId) {
 /** 越权审计去重键的 TTL：同一插件同一项在此期间只记一次。 */
 const DENIAL_DEDUPE_TTL_SECONDS = 30 * 24 * 3600;
 /**
- * Records one `extension.permission_denied` audit, deduplicated per (extension, item) through Redis
- * `SET NX EX` (once across replicas). When the audit write fails, the dedup key is removed (the next
+ * Records one `extension.permission_denied` audit, deduplicated per (extension, item) through a
+ * Redis marker set unless present (`LockService.lease`; once across replicas). When the audit write fails, the dedup key is removed (the next
  * violation tries again) and a warning is logged; nothing is thrown to the extension (it already got
  * an ExtensionPermissionError).
  */
 async function recordDenial(deps, plugin, item) {
     const key = `capk:plugin-permission-denied:${plugin}:${item}`;
     try {
-        const first = await deps.redis.set(key, "1", "EX", DENIAL_DEDUPE_TTL_SECONDS, "NX");
-        if (first !== "OK")
+        if (!(await deps.locks.lease(key, "1", DENIAL_DEDUPE_TTL_SECONDS * 1000)))
             return;
         try {
             await audit(kernelDb(deps.db), {
@@ -195,7 +193,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
     const lifecycle = new AbortController();
     /** 撤销时队列 worker 排空的截止时刻（epoch 毫秒）；undefined = 一直等（停机路径）。 */
     let drainDeadline;
-    const lock = createLock(deps.redis, name);
+    const lock = createLock(deps.locks, name);
     const tag = (fields) => ({ ...fields, plugin: name });
     let closing;
     const perms = manifest.permissions ?? {};
@@ -214,7 +212,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
     // 键加前缀 plugins/<name>/<orgId>/。没有提供方时各方法 reject storage.unavailable
     // （宿主不会加载这样的插件，见 approvals.ts；单独构造 ctx 的测试会走到这里）
     const storageApi = perms.storage
-        ? new StorageService({
+        ? new PrefixedStorage({
             provider: () => extensionPointAccess.providers(OBJECT_STORE_EXTENSION_POINT)[0]?.impl,
             plugins: async () => [name],
         }).forPlugin(name)
@@ -229,7 +227,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
         ...(manifest.optional ?? []),
     ]);
     const uiReg = new PluginUiRegistration(manifest, deny);
-    const embedTokens = new EmbedTokens(deps.keyring);
+    const embedTokens = deps.embedTokens;
     const uiPlaces = new Map((manifest.ui ?? []).map((c) => [c.id, c.place]));
     /** 校验能力可取用（非 brokered、已在清单声明），返回其登记信息。 */
     const checkExtensionPoint = (ref) => {

package/dist/ctx/lock.d.ts

@@ -1,4 +1,8 @@
 import type { ExtensionContext } from "@capybara-hq/plugin-sdk";
-import type { Redis } from "ioredis";
-/** 创建带命名空间的 ctx.lock：键为 `cap:<namespace>:lock:<key>`，token 比对保证只操作自己持有的锁。 */
-export declare function createLock(redis: Redis, namespace: string): ExtensionContext["lock"];
+import type { LockService } from "../infra/lock/lock.service.js";
+/**
+ * Builds a namespaced `ctx.lock` on the kernel's lock primitives (`LockService.lease / renew /
+ * releaseIf`): key `cap:<namespace>:lock:<key>`, a random token per acquisition, so renew and
+ * release only touch a lock this holder still owns. The extension renews it itself (no timer).
+ */
+export declare function createLock(locks: Pick<LockService, "lease" | "renew" | "releaseIf">, namespace: string): ExtensionContext["lock"];

package/dist/ctx/lock.js

@@ -1,19 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { assertNamespace } from "./namespace.js";
-const RENEW = `
-if redis.call('GET', KEYS[1]) == ARGV[1] then
-  return redis.call('PEXPIRE', KEYS[1], ARGV[2])
-end
-return 0
-`;
-const RELEASE = `
-if redis.call('GET', KEYS[1]) == ARGV[1] then
-  return redis.call('DEL', KEYS[1])
-end
-return 0
-`;
-/** 创建带命名空间的 ctx.lock：键为 `cap:<namespace>:lock:<key>`，token 比对保证只操作自己持有的锁。 */
-export function createLock(redis, namespace) {
+/**
+ * Builds a namespaced `ctx.lock` on the kernel's lock primitives (`LockService.lease / renew /
+ * releaseIf`): key `cap:<namespace>:lock:<key>`, a random token per acquisition, so renew and
+ * release only touch a lock this holder still owns. The extension renews it itself (no timer).
+ */
+export function createLock(locks, namespace) {
     assertNamespace(namespace);
     return {
         async acquire(key, opts) {
@@ -23,15 +15,12 @@ export function createLock(redis, namespace) {
             }
             const redisKey = `cap:${namespace}:lock:${key}`;
             const token = randomUUID();
-            const ok = await redis.set(redisKey, token, "PX", ttlMs, "NX");
-            if (ok !== "OK")
+            if (!(await locks.lease(redisKey, token, ttlMs)))
                 return null;
             return {
-                async renew() {
-                    return Number(await redis.eval(RENEW, 1, redisKey, token, ttlMs)) === 1;
-                },
+                renew: () => locks.renew(redisKey, token, ttlMs),
                 async release() {
-                    await redis.eval(RELEASE, 1, redisKey, token);
+                    await locks.releaseIf(redisKey, token);
                 },
             };
         },

package/dist/ctx/secrets.d.ts

@@ -1,5 +1,7 @@
 import type { ExtensionContext } from "@capybara-hq/plugin-sdk";
 import type { Kysely } from "kysely";
+import type { KernelDb } from "../infra/database/kernel-db.js";
+import type { TransactionHost } from "../infra/database/transaction-host.js";
 /** 主密钥环：current 用于新包装，previous 仅用于解包。原始密钥只存在于闭包内。 */
 export interface Keyring {
     readonly currentId: string;
@@ -40,6 +42,12 @@ export type KernelSecrets = ExtensionContext["secrets"] & {
  * `db` 可以是 Kysely 事务：此时读写（含首次创建组织数据密钥）都在该事务内。
  */
 export declare function createSecrets(db: AnyDb, keyring: Keyring, namespace: string): KernelSecrets;
-/** 把非当前主密钥包装的数据密钥改用当前主密钥重新包装，返回处理条数。 */
-export declare function rewrapDataKeys(db: AnyDb, keyring: Keyring): Promise<number>;
+/**
+ * 把非当前主密钥包装的数据密钥改用当前主密钥重新包装，返回处理条数。One transaction over the given
+ * handles (`KernelDb` + its `TransactionHost`, as `DatabaseModule` provides them).
+ */
+export declare function rewrapDataKeys(handles: {
+    db: Pick<KernelDb, "db">;
+    txHost: Pick<TransactionHost, "run">;
+}, keyring: Keyring): Promise<number>;
 export {};

package/dist/ctx/secrets.js

@@ -142,9 +142,13 @@ export function createSecrets(db, keyring, namespace) {
         },
     };
 }
-/** 把非当前主密钥包装的数据密钥改用当前主密钥重新包装，返回处理条数。 */
-export async function rewrapDataKeys(db, keyring) {
-    return db.transaction().execute(async (trx) => {
+/**
+ * 把非当前主密钥包装的数据密钥改用当前主密钥重新包装，返回处理条数。One transaction over the given
+ * handles (`KernelDb` + its `TransactionHost`, as `DatabaseModule` provides them).
+ */
+export async function rewrapDataKeys(handles, keyring) {
+    return handles.txHost.run(async () => {
+        const trx = handles.db.db;
         const rows = await trx
             .withSchema("capybara")
             .selectFrom("org_data_keys")

package/dist/db/kernel-schema.d.ts

@@ -269,7 +269,7 @@ export interface RunsTable {
     /** 0054: when this run's `subagents` wait expires (set while it waits on sub-agents). */
     wait_expires_at: TsNullable;
 }
-/** 0053: one row per sub-agent dispatch (an `agent` call of a parent run). */
+/** 0053: one row per sub-agent dispatch (an `Agent` call of a parent run). */
 export interface SubagentDispatchesTable {
     parent_run_id: string;
     parent_call_id: string;
@@ -400,7 +400,7 @@ export interface ApprovalsTable {
     /** 0056: the reason given with a denial (null without one). */
     deny_reason: Generated<string | null>;
 }
-/** 0010_tools.sql：ask_user 提问。 */
+/** 0010_tools.sql：AskUserQuestion 提问。 */
 export interface QuestionsTable {
     id: string;
     org_id: string;
@@ -1116,7 +1116,7 @@ export interface PluginInstallComponentsTable {
      */
     dropped: ColumnType<boolean, boolean | undefined, boolean>;
 }
-export type KernelDb = Kysely<KernelDatabase>;
+export type KernelSchemaDb = Kysely<KernelDatabase>;
 /** 把无类型的 Kysely 实例收窄成内核 schema 视图（`capybara`）。 */
-export declare function kernelDb(db: Kysely<any>): KernelDb;
+export declare function kernelDb(db: Kysely<any>): KernelSchemaDb;
 export {};

package/dist/db/pool.d.ts

@@ -18,4 +18,9 @@ export declare function pgConnectOptions(cfg: {
  */
 export declare function createDb(url: string, poolMax: number, onError?: (err: Error) => void, opts?: {
     connectTimeoutMs?: number | undefined;
+    /**
+     * Error of a client while it is checked out: pg-pool drops its own listener on checkout, so
+     * without this a backend killed between two statements is an uncaught exception.
+     */
+    onClientError?: ((err: Error) => void) | undefined;
 }): Kysely<any>;

package/dist/db/pool.js

@@ -24,5 +24,6 @@ export function createDb(url, poolMax, onError = (err) => console.error("[db] id
         ...pgConnectOptions(opts),
     });
     pool.on("error", onError);
+    pool.on("connect", (client) => client.on("error", opts.onClientError ?? onError));
     return new Kysely({ dialect: new PostgresDialect({ pool }) });
 }

package/dist/errors.d.ts

@@ -8,6 +8,7 @@ export declare const ERROR_CODES: {
     readonly validation_failed: 400;
     readonly forbidden: 403;
     readonly conflict: 409;
+    readonly "lock.acquire_failed": 409;
     readonly payload_too_large: 413;
     readonly unsupported_media_type: 415;
     readonly rate_limited: 429;

package/dist/errors.js

@@ -8,6 +8,7 @@ export const ERROR_CODES = {
     validation_failed: 400,
     forbidden: 403,
     conflict: 409,
+    "lock.acquire_failed": 409,
     payload_too_large: 413,
     unsupported_media_type: 415,
     rate_limited: 429,

package/dist/evals/budget.d.ts

@@ -1,5 +1,7 @@
 import type { ModelUsage } from "@capybara-hq/plugin-sdk";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
 /**
  * 评测运行的 token 预算（C7）：`eval_runs.tokens_used` 在 PG 里原子累加，达到 `token_cap` 的同一条语句把
  * 状态置为 `capped`；worker 每次请求前查 {@link runActive}，不活跃就不再发新请求。在途请求可以越过上限，
@@ -13,7 +15,7 @@ export declare const usageTokens: (u: ModelUsage) => number;
  * 累加用量：`UPDATE … RETURNING`，累加后 ≥ 上限且运行仍在执行 → 同一语句置 `capped`、记 `finished_at`。
  * 运行已不在（被删）时返回 `{ used: 0, capped: true }`，调用方同样停下。
  */
-export declare function consumeTokens(db: KernelDb, runId: string, tokens: number): Promise<{
+export declare function consumeTokens(db: KernelSchemaDb, runId: string, tokens: number): Promise<{
     used: number;
     capped: boolean;
 }>;
@@ -27,35 +29,54 @@ export declare const TOO_MANY_ERRORS: {
  * 同一语句置 `failed`、记原因与 `finished_at`；成功 → 清零。返回运行是否因此被熔断。
  * 多个任务并发时「连续」按写入顺序计（近似），足以挡住「每个请求都失败」的运行。
  */
-export declare function recordOutcome(db: KernelDb, runId: string, ok: boolean, maxConsecutive: number): Promise<{
+export declare function recordOutcome(db: KernelSchemaDb, runId: string, ok: boolean, maxConsecutive: number): Promise<{
     tripped: boolean;
 }>;
 /**
  * 运行停下（取消 / 越限 / 熔断 / 删除评测集）时：还在等评委的结果（`judge_status = 'pending'`）记 `skipped`，
  * 否则这些用例永远算不上做完。给了 `caseId` 只处理该用例。在途的评委请求做完后写不进来（条件是 pending），用量照样计入。
  */
-export declare function skipPendingJudges(db: KernelDb, runId: string, caseId?: string): Promise<void>;
-/**
- * 重算 `cases_done` = 结果全部结束、且没有等评委的结果的用例数（幂等：任务重做不会重复计数），达到 `cases_total` 且运行仍在执行 →
- * `completed`。先锁运行行再数（READ COMMITTED 下新语句看得到其他任务已提交的结果），并发完成的任务不会互相覆盖。
- * worker 每做完一个用例、取消、入队失败时都调用。在事务里调用时锁随事务释放。
- */
-export declare function recountCases(db: KernelDb, runId: string): Promise<void>;
+export declare function skipPendingJudges(db: KernelSchemaDb, runId: string, caseId?: string): Promise<void>;
 /**
  * 运行仍在执行（queued / running），且所属组织与评测集的 agent 都没有删除：取消、达到上限、已结束、运行行已删除、
  * 组织或 agent 已删除都为 false（删除组织 / agent 时会显式取消运行，这里再兜一次底，挡住删除与请求之间的竞争）。
  */
-export declare function runActive(db: KernelDb, runId: string): Promise<boolean>;
+export declare function runActive(db: KernelSchemaDb, runId: string): Promise<boolean>;
 /**
- * 删除组织或 agent 时（调用方的事务内）取消其在执行的评测运行：运行置 `cancelled`，未开始的结果 `skipped`、
- * 等评委的记 `skipped`，重算进度，每个运行写审计 `eval.run_cancelled`（detail 带原因）。在途请求做完后写不进新的请求
- * （worker 每次请求前查 {@link runActive}）。运行创建者离开组织不取消（Ruling S1-b：管理员的评测运行是组织的工作）。
+ * The eval run bookkeeping that needs a transaction: the progress recount (it locks the run row)
+ * and the cancellation of an org's or agent's runs when it is deleted. One provider, shared by the
+ * evals, the agents and the orgs.
  */
-export declare function cancelEvalRuns(trx: KernelDb, scope: {
-    orgId: string;
-    agentId?: string;
-}, actor: {
-    accountId: string;
-    tokenId?: string;
-}, reason: "org_deleted" | "agent_deleted"): Promise<string[]>;
+export declare class EvalBudget {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, txHost: TransactionHost);
+    /**
+     * 重算 `cases_done` = 结果全部结束、且没有等评委的结果的用例数（幂等：任务重做不会重复计数），达到 `cases_total` 且运行仍在执行 →
+     * `completed`。先锁运行行再数（READ COMMITTED 下新语句看得到其他任务已提交的结果），并发完成的任务不会互相覆盖。
+     * worker 每做完一个用例、取消、入队失败时都调用。Joins the caller's transaction (the lock is released with it),
+     * else runs in its own.
+     */
+    recountCases(runId: string): Promise<void>;
+    /**
+     * 删除组织或 agent 时（调用方的事务内）取消其在执行的评测运行：运行置 `cancelled`，未开始的结果 `skipped`、
+     * 等评委的记 `skipped`，重算进度，每个运行写审计 `eval.run_cancelled`（detail 带原因）。在途请求做完后写不进新的请求
+     * （worker 每次请求前查 {@link runActive}）。运行创建者离开组织不取消（Ruling S1-b：管理员的评测运行是组织的工作）。
+     */
+    cancelRuns(scope: {
+        orgId: string;
+        agentId?: string;
+    }, actor: {
+        accountId: string;
+        tokenId?: string;
+    }, reason: "org_deleted" | "agent_deleted"): Promise<string[]>;
+    /**
+     * A run that stopped (cancelled, its set deleted): its results not started yet are `skipped`,
+     * the pending judges too, and the progress is recounted, in the caller's transaction.
+     */
+    skipRun(runId: string): Promise<void>;
+}
+/** {@link EvalBudget} on its own: the agents and the orgs import it without the evals. */
+export declare class EvalBudgetModule {
+}
 export declare const addUsage: (a: ModelUsage, b: ModelUsage) => ModelUsage;