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

package/dist/runtime/run-drafts.js

@@ -0,0 +1,230 @@
+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 { conversationTopic, EventLog, } from "../conversations/event-log.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
+import { assistantIdemKey } from "./model-call.js";
+/** How long a draft lives without a write (a step that keeps streaming keeps refreshing it). */
+export const DRAFT_TTL_SECONDS = 600;
+/** At most one write per step per window, plus the one at the end of the model stream. */
+export const DRAFT_FLUSH_MS = 200;
+/** One step's draft: `{ text, thinking }` as JSON (spec 2026-11-07 §3.2). */
+export const draftKey = (runId, step) => `capk:run-draft:${runId}:${step}`;
+/** The steps of a run that have a draft (a set, so a reader finds them without a key scan). */
+const stepsKey = (runId) => `capk:run-draft-steps:${runId}`;
+const parse = (step, v) => {
+    if (v === null)
+        return null;
+    try {
+        const d = JSON.parse(v);
+        return {
+            step,
+            text: typeof d.text === "string" ? d.text : "",
+            thinking: typeof d.thinking === "string" ? d.thinking : "",
+        };
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Live drafts (spec 2026-11-07-run-input-and-live-drafts §3.2): what each step of a running run
+ * has streamed so far, kept in Redis so a viewer that (re)connects on any replica gets the text
+ * already shown, then the deltas from there on.
+ *
+ * The writer is the process executing the run: it holds the step's draft in memory (only for the
+ * runs it executes; {@link release} drops them when the execution ends) and writes it at most once
+ * per {@link DRAFT_FLUSH_MS}: on the first delta past the window, or, when deltas stop inside it,
+ * by one trailing one-shot timer per held step (process-local, unref'd, cancelled by a write,
+ * {@link clear} and {@link release}), plus once when the model stream ends ({@link flush}). Writes are issued before the delta is published, on the same
+ * connection as the bus publish, so a viewer that sees a delta past its snapshot and asks again
+ * gets a draft at least that far whenever that delta was written. Every write refreshes the
+ * {@link DRAFT_TTL_SECONDS} TTL; {@link clear} deletes the step's draft once its
+ * `assistant_message` is logged or the step is reset. Redis failures are logged, never thrown to
+ * the run: a draft is a convenience, the log stays the truth.
+ */
+let RunDrafts = class RunDrafts {
+    redis;
+    kdb;
+    eventLog;
+    log;
+    held = new Map();
+    constructor(redis, kdb, eventLog, log) {
+        this.redis = redis;
+        this.kdb = kdb;
+        this.eventLog = eventLog;
+        this.log = log;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /** Adds a delta to the step's draft; writes it when the last write is a window old. */
+    append(runId, step, channel, text) {
+        let h = this.held.get(runId);
+        if (h?.step !== step) {
+            if (h)
+                this.drop(runId, h);
+            h = {
+                step,
+                text: "",
+                thinking: "",
+                writtenAt: Number.NEGATIVE_INFINITY,
+                dirty: false,
+                timer: undefined,
+            };
+            this.held.set(runId, h);
+        }
+        h[channel] += text;
+        h.dirty = true;
+        const elapsed = Date.now() - h.writtenAt;
+        if (elapsed >= DRAFT_FLUSH_MS)
+            this.write(runId, h);
+        else if (h.timer === undefined) {
+            // held: written when the window ends even if no delta follows (a tool input, a pause)
+            h.timer = setTimeout(() => {
+                h.timer = undefined;
+                this.flush(runId, step);
+            }, DRAFT_FLUSH_MS - elapsed).unref();
+        }
+    }
+    /** The end of the step's model stream: writes what the window still holds. */
+    flush(runId, step) {
+        const h = this.held.get(runId);
+        if (h?.step === step && h.dirty)
+            this.write(runId, h);
+    }
+    /** Deletes the step's draft (its `assistant_message` is logged, or the step starts over). */
+    clear(runId, step) {
+        const h = this.held.get(runId);
+        if (h?.step === step)
+            this.drop(runId, h);
+        this.redis
+            .multi()
+            .del(draftKey(runId, step))
+            .srem(stepsKey(runId), String(step))
+            .exec()
+            .catch((err) => this.log.warn("run draft clear failed", { runId, step, err }));
+    }
+    /**
+     * Drops what this process holds for the run (its execution here ended: finished, suspended,
+     * handed over). Redis keeps what was written: another worker may continue the run, and a step
+     * that never ended is not shown once the run is no longer running (TTL removes it).
+     */
+    release(runId) {
+        const h = this.held.get(runId);
+        if (h)
+            this.drop(runId, h);
+    }
+    /** The run's steps with a draft, by step. */
+    async read(runId) {
+        const steps = (await this.redis.smembers(stepsKey(runId)))
+            .map(Number)
+            .filter((n) => Number.isSafeInteger(n))
+            .sort((a, b) => a - b);
+        if (steps.length === 0)
+            return [];
+        const values = await this.redis.mget(steps.map((s) => draftKey(runId, s)));
+        return steps.flatMap((s, i) => parse(s, values[i] ?? null) ?? []);
+    }
+    /**
+     * The drafts a viewer of the conversation is shown: steps of its running run (or only `runId`)
+     * whose `assistant_message` is not logged. Redis is read before the log, so a step finalized
+     * meanwhile is either skipped here or its `assistant_message` reaches the viewer after the draft.
+     */
+    async live(conversationId, runId) {
+        let q = this.db
+            .selectFrom("runs")
+            .select("id")
+            .where("conversation_id", "=", conversationId)
+            .where("status", "=", "running");
+        if (runId !== undefined)
+            q = q.where("id", "=", runId);
+        const out = [];
+        for (const run of await q.execute()) {
+            for (const d of await this.read(run.id)) {
+                const final = await this.eventLog.findByIdem(conversationId, assistantIdemKey(run.id, d.step));
+                if (final === undefined)
+                    out.push({ runId: run.id, ...d });
+            }
+        }
+        return out;
+    }
+    /** Whether the run belongs to the conversation (the draft route's 404). */
+    async runOf(conversationId, runId) {
+        const row = await this.db
+            .selectFrom("runs")
+            .select("id")
+            .where("id", "=", runId)
+            .where("conversation_id", "=", conversationId)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+    drop(runId, h) {
+        clearTimeout(h.timer);
+        h.timer = undefined;
+        this.held.delete(runId);
+    }
+    write(runId, h) {
+        clearTimeout(h.timer);
+        h.timer = undefined;
+        h.writtenAt = Date.now();
+        h.dirty = false;
+        const { step } = h;
+        this.redis
+            .multi()
+            .set(draftKey(runId, step), JSON.stringify({ text: h.text, thinking: h.thinking }), "EX", DRAFT_TTL_SECONDS)
+            .sadd(stepsKey(runId), String(step))
+            .expire(stepsKey(runId), DRAFT_TTL_SECONDS)
+            .exec()
+            .catch((err) => this.log.warn("run draft write failed", { runId, step, err }));
+    }
+};
+RunDrafts = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KernelDb)),
+    __param(2, Inject(EventLog)),
+    __param(3, Inject(KERNEL_LOGGER))
+], RunDrafts);
+export { RunDrafts };
+/**
+ * The run's stream sink (one per execution of a run): publishes deltas on the conversation's topic
+ * (`conv.<id>`, shared with `{ kind: "events" }`, so a subscriber on any replica gets them) with
+ * `offset`, the characters of that channel (text or thinking) this attempt of the step streamed
+ * before the delta, and keeps the step's live draft. `step_reset` clears the draft and both
+ * offsets; `stream_end` / `step_end` only flush / clear the draft and are not published. A failed
+ * publish is only logged: deltas are drafts, the `assistant_message` in the log is the truth.
+ */
+export function streamSink(conversationId, deps) {
+    let at = { runId: "", step: -1, text: 0, thinking: 0 };
+    const publish = (msg) => deps.bus
+        .publish(conversationTopic(conversationId), msg)
+        .catch((err) => deps.log.warn("stream delta publish failed", { conversationId, err }));
+    return (d) => {
+        if (d.kind === "stream_end")
+            return deps.drafts.flush(d.runId, d.step);
+        if (d.kind === "step_end")
+            return deps.drafts.clear(d.runId, d.step);
+        if (at.runId !== d.runId || at.step !== d.step || d.kind === "step_reset") {
+            at = { runId: d.runId, step: d.step, text: 0, thinking: 0 };
+        }
+        if (d.kind === "step_reset") {
+            deps.drafts.clear(d.runId, d.step);
+            void publish({ kind: "delta", runId: d.runId, step: d.step, delta: "step_reset" });
+            return;
+        }
+        const text = d.text ?? "";
+        const offset = at[d.kind];
+        at[d.kind] += text.length;
+        deps.drafts.append(d.runId, d.step, d.kind, text);
+        void publish({ kind: "delta", runId: d.runId, step: d.step, delta: d.kind, text, offset });
+    };
+}

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>;
@@ -20,26 +19,36 @@ export interface FinishRunArgs {
     floorToTrigger?: boolean;
     /**
      * 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).
+     * 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;
-}

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

@@ -0,0 +1,46 @@
+import type { Job, Queue } from "bullmq";
+import type { ConversationKind } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+/** 内核运行队列的 BullMQ 队列名（不含 `:`；与插件队列 `cap.<插件>.<名>` 不会重名）。 */
+export declare const RUN_QUEUE_NAME = "cap-kernel-runs";
+/**
+ * Queue of sub-agent (child) runs (sub-agents spec §7.4): a replica still on a version without
+ * sub-agents never takes a child job, and child load shows apart from conversations.
+ */
+export declare const SUBAGENT_RUN_QUEUE_NAME = "cap-kernel-subagent-runs";
+/** The run queue of a conversation kind: sub-agent conversations have their own. */
+export declare const runQueueNameFor: (kind: ConversationKind) => string;
+/** 未结束的运行状态（waiting：等人处理审批 / 输入请求，没有任务、不占会话锁与配额）。 */
+export declare const ACTIVE_RUN_STATUSES: readonly ["queued", "running", "waiting"];
+/** 运行任务的数据。 */
+export interface RunJobData {
+    runId: string;
+    conversationId: string;
+}
+/** 同一触发点（会话 + 最新用户消息 seq）只投递一次。 */
+export declare const runJobId: (conversationId: string, maxUserSeq: number) => string;
+/**
+ * The producer side of the two run queues (`cap-kernel-runs`, `cap-kernel-subagent-runs`): adds
+ * run jobs under the caller's job id and looks them up. The run queue (`ensureRun`, orphan
+ * repairs), the waits (resumes) and the sub-agent dispatch enqueue through it; the run worker
+ * consumes both queues.
+ */
+export declare class RunJobs {
+    private readonly kdb;
+    private readonly queues;
+    constructor(kdb: KernelDb, runs: Queue<RunJobData>, subagentRuns: Queue<RunJobData>, log: KernelLogger);
+    /** The BullMQ queue `name` (default: conversation runs). */
+    queue(name?: string): Queue<RunJobData>;
+    /** A run job by id on the queue `name`, or undefined. */
+    getJob(jobId: string, name?: string): Promise<Job<RunJobData> | undefined>;
+    /**
+     * Enqueues a run job under the caller's job id (`ensureRun`, resumes, dispatches, repairs). The
+     * queue follows the conversation's kind (a sub-agent's runs go to
+     * {@link SUBAGENT_RUN_QUEUE_NAME}); pass `kind` when the caller knows it, else it is read.
+     */
+    enqueue(data: RunJobData, jobId: string, kind?: ConversationKind): Promise<void>;
+}
+/** The run queues' producer (the sub-agent dispatch, the run queue and the waits use it). */
+export declare class RunJobsModule {
+}

package/dist/runtime/run-jobs.js

@@ -0,0 +1,91 @@
+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 { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable, Module } from "@nestjs/common";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+/** 内核运行队列的 BullMQ 队列名（不含 `:`；与插件队列 `cap.<插件>.<名>` 不会重名）。 */
+export const RUN_QUEUE_NAME = "cap-kernel-runs";
+/**
+ * Queue of sub-agent (child) runs (sub-agents spec §7.4): a replica still on a version without
+ * sub-agents never takes a child job, and child load shows apart from conversations.
+ */
+export const SUBAGENT_RUN_QUEUE_NAME = "cap-kernel-subagent-runs";
+/** The run queue of a conversation kind: sub-agent conversations have their own. */
+export const runQueueNameFor = (kind) => kind === "subagent" ? SUBAGENT_RUN_QUEUE_NAME : RUN_QUEUE_NAME;
+/** 未结束的运行状态（waiting：等人处理审批 / 输入请求，没有任务、不占会话锁与配额）。 */
+export const ACTIVE_RUN_STATUSES = ["queued", "running", "waiting"];
+/** 同一触发点（会话 + 最新用户消息 seq）只投递一次。 */
+export const runJobId = (conversationId, maxUserSeq) => `run-${conversationId}-${maxUserSeq}`;
+/** The options of every run job: one attempt (the run's own paths handle failures), not kept. */
+const RUN_JOB_OPTIONS = { attempts: 1, removeOnComplete: true, removeOnFail: true };
+/**
+ * The producer side of the two run queues (`cap-kernel-runs`, `cap-kernel-subagent-runs`): adds
+ * run jobs under the caller's job id and looks them up. The run queue (`ensureRun`, orphan
+ * repairs), the waits (resumes) and the sub-agent dispatch enqueue through it; the run worker
+ * consumes both queues.
+ */
+let RunJobs = class RunJobs {
+    kdb;
+    queues;
+    constructor(kdb, runs, subagentRuns, log) {
+        this.kdb = kdb;
+        this.queues = { [RUN_QUEUE_NAME]: runs, [SUBAGENT_RUN_QUEUE_NAME]: subagentRuns };
+        for (const [name, q] of Object.entries(this.queues)) {
+            q.on("error", (err) => log.error("run queue error", { err, queue: name }));
+        }
+    }
+    /** The BullMQ queue `name` (default: conversation runs). */
+    queue(name = RUN_QUEUE_NAME) {
+        const q = this.queues[name];
+        if (!q)
+            throw new Error(`unknown run queue ${name}`);
+        return q;
+    }
+    /** A run job by id on the queue `name`, or undefined. */
+    getJob(jobId, name = RUN_QUEUE_NAME) {
+        return this.queue(name).getJob(jobId);
+    }
+    /**
+     * Enqueues a run job under the caller's job id (`ensureRun`, resumes, dispatches, repairs). The
+     * queue follows the conversation's kind (a sub-agent's runs go to
+     * {@link SUBAGENT_RUN_QUEUE_NAME}); pass `kind` when the caller knows it, else it is read.
+     */
+    async enqueue(data, jobId, kind) {
+        const k = kind ??
+            (await this.kdb.db
+                .selectFrom("conversations")
+                .select("kind")
+                .where("id", "=", data.conversationId)
+                .executeTakeFirst())?.kind ??
+            "chat";
+        await this.queue(runQueueNameFor(k)).add("run", data, { jobId, ...RUN_JOB_OPTIONS });
+    }
+};
+RunJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(getQueueToken(RUN_QUEUE_NAME))),
+    __param(2, Inject(getQueueToken(SUBAGENT_RUN_QUEUE_NAME))),
+    __param(3, Inject(KERNEL_LOGGER))
+], RunJobs);
+export { RunJobs };
+/** The run queues' producer (the sub-agent dispatch, the run queue and the waits use it). */
+let RunJobsModule = class RunJobsModule {
+};
+RunJobsModule = __decorate([
+    Module({
+        imports: [QueueModule.registerQueue(RUN_QUEUE_NAME, SUBAGENT_RUN_QUEUE_NAME)],
+        providers: [RunJobs],
+        exports: [RunJobs],
+    })
+], RunJobsModule);
+export { RunJobsModule };

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

@@ -0,0 +1,60 @@
+import { WorkerHost } from "@nestjs/bullmq";
+import { type DynamicModule } from "@nestjs/common";
+import type { Job, Worker } from "bullmq";
+import type { KernelConfig } from "../config/schema.js";
+import { TitleQueue } from "../conversations/titles.js";
+import { type RunJobData } from "./run-jobs.js";
+import { RunWorker } from "./run-worker.js";
+import { UsageReporter, type UsageReportJob } from "./usage-report.js";
+type RunResult = Awaited<ReturnType<RunWorker["process"]>>;
+/** The consumer of `cap-kernel-runs` (conversation runs): {@link RunWorker}. */
+export declare class RunsProcessor extends WorkerHost<Worker<RunJobData, RunResult>> {
+    private readonly runs;
+    constructor(runs: RunWorker);
+    process(job: Job<RunJobData>, token?: string): Promise<RunResult>;
+    completed(job: Job<RunJobData>, result: RunResult): void;
+    failed(job: Job<RunJobData> | undefined, err: Error): void;
+    error(err: Error): void;
+}
+/** The consumer of `cap-kernel-subagent-runs` (sub-agent runs, spec §7.4): {@link RunWorker}. */
+export declare class SubagentRunsProcessor extends WorkerHost<Worker<RunJobData, RunResult>> {
+    private readonly runs;
+    constructor(runs: RunWorker);
+    process(job: Job<RunJobData>, token?: string): Promise<RunResult>;
+    completed(job: Job<RunJobData>, result: RunResult): void;
+    failed(job: Job<RunJobData> | undefined, err: Error): void;
+    error(err: Error): void;
+}
+/** The consumer of `cap-kernel-usage-report`: {@link UsageReporter}. */
+export declare class UsageReportProcessor extends WorkerHost<Worker<UsageReportJob>> {
+    private readonly reporter;
+    constructor(reporter: UsageReporter);
+    process(job: Job<UsageReportJob>, token?: string): Promise<void>;
+    failed(job: Job<UsageReportJob> | undefined, err: Error): void;
+    error(err: Error): void;
+}
+/** The consumer of `cap-kernel-titles`: {@link TitleQueue}. */
+export declare class TitleProcessor extends WorkerHost<Worker<{
+    conversationId: string;
+    attempt: number;
+}>> {
+    private readonly titles;
+    constructor(titles: TitleQueue);
+    process(job: Job<{
+        conversationId: string;
+        attempt: number;
+    }>): Promise<void>;
+    error(err: Error): void;
+}
+/**
+ * The runtime's queue consumers: the run worker on both run queues, `usage.report` deliveries and
+ * conversation titles. Imported only by the worker role (`WorkerModule`), so other roles get no
+ * processor and no BullMQ worker. Their worker options come from the startup config (concurrency
+ * per queue, the run queues' job lock and stalled detection, which the usage and title workers
+ * follow). The workers never start by themselves: the worker role (`WorkerRole`) starts them after
+ * the extensions loaded, and pauses them on stop.
+ */
+export declare class RuntimeWorkersModule {
+    static forRoot(config: KernelConfig): DynamicModule;
+}
+export {};