@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/runtime/providers.d.ts

@@ -0,0 +1,86 @@
+import { type ExtensionPointRef, type Logger, type ModelInfo, type ModelProvider, type ModelProviderV1 } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import type { ModelRef } from "../agents/definition.js";
+import { ApiError } from "../errors.js";
+/** 单个供应商 `listModels()` 的时限（毫秒）：一个卡住的供应商不拖住整个列表与解析。 */
+export declare const LIST_MODELS_TIMEOUT_MS = 10000;
+/**
+ * 列表视图（后台模型页、组织模型页）里列模型失败的供应商在这么多秒内直接标 error、不再请求（Redis，多副本共享）。
+ * 只用于列表；`resolve`（运行时）照常每次请求，失败由降级梯子重试。
+ */
+export declare const LIST_FAILURE_TTL_SECONDS = 15;
+/** The host view the registry needs: a subset of `ExtensionHost.list` (version and digest optional, for test doubles). */
+export interface ProviderHost {
+    list(extensionPointName: string): {
+        plugin: string;
+        capability: ExtensionPointRef;
+        impl: unknown;
+        version?: string;
+        configHash?: string;
+    }[];
+}
+/** 一个供应商在后台的视图：供应商名即插件名；`status: "error"` 时 `models` 为空、`error` 为内核的说明。 */
+export interface ProviderStatus {
+    provider: string;
+    plugin: string;
+    status: "ok" | "error";
+    error?: string;
+    models: ModelInfo[];
+}
+/**
+ * 供应商的 `listModels()` 失败（上游不可用等）。仍是 `agent.model_unavailable`，HTTP 调用方照常
+ * 得到该错误码；运行时（`runModelStep`）据此类型把它当作可重试的失败交给降级梯子，
+ * 与「供应商未安装 / 模型不存在 / 参数声明不合规」（不可重试）区分开。
+ */
+export declare class ProviderListError extends ApiError {
+    readonly provider: string;
+    constructor(provider: string, cause: unknown);
+}
+/**
+ * 把 `model-provider@1` 实现包成 `@2`：
+ * - `listModels`：`parameters` 由 `capabilities.effort` 推导（为真时只有 effort 旋钮，否则为空）；
+ * - `stream`：`params.effort` 映射为 `req.effort`，其余参数丢弃（`@1` 没有对应字段）；
+ *   没有 `params.effort` 时保留请求自带的 `effort`。
+ */
+export declare function adaptModelProviderV1(impl: ModelProviderV1): ModelProvider;
+/**
+ * 模型供应商注册表：供应商即提供 `model-provider` 能力的插件（以插件名为供应商名）。
+ * 同时支持 `model-provider@1`（经 {@link adaptModelProviderV1} 适配）与 `@2`；
+ * 同一插件两者都提供时用 `@2`。`@2` 的 `listModels()` 结果先过 `assertValidDeclarations`，
+ * 不合规的供应商不可用（不可重试）。
+ * 每个供应商的模型列表（`@2` 形状）缓存在 Redis `capk:models:<provider>:v<主版本>:<插件版本>:<部署配置摘要>`（EX 600），不放进程内存，
+ * 多副本共享同一份缓存。
+ */
+export declare class ProviderRegistry {
+    private readonly host;
+    private readonly kv;
+    private readonly log?;
+    private readonly opts;
+    constructor(host: ProviderHost, kv: Redis, log?: Pick<Logger, "warn"> | undefined, opts?: {
+        listTimeoutMs?: number;
+    });
+    /** `listModels()` 加时限（到时按失败处理，供应商的调用留在后台、结果丢弃）。 */
+    private listModelsWithTimeout;
+    /** 每个插件取一个实现（`@2` 优先），按插件首次出现的顺序；不支持的主版本记 warn 后忽略。 */
+    private providers;
+    private models;
+    /** 每个已安装供应商及其模型（按插件加载顺序）；列模型失败或声明不合规的供应商跳过并记 warn。 */
+    list(): Promise<{
+        provider: string;
+        models: ModelInfo[];
+    }[]>;
+    /**
+     * 每个已安装供应商及其状态（按插件加载顺序，后台用）：列模型失败（含超过 {@link LIST_MODELS_TIMEOUT_MS}）或声明
+     * 不合规的标 `error`、`models` 为空，不影响其他供应商；列模型失败的在 {@link LIST_FAILURE_TTL_SECONDS} 秒内不再请求。`error` 只是内核自己的英文说明（不透出上游错误原文，原文记 warn 日志）。
+     */
+    listWithStatus(): Promise<ProviderStatus[]>;
+    /**
+     * 解析模型引用，返回 `@2` 形状的供应商实现（`@1` 已适配）与模型信息。
+     * 供应商未安装、模型不存在或参数声明不合规 → `agent.model_unavailable`；
+     * 供应商 `listModels()` 失败 → `ProviderListError`（同一错误码，运行时视为可重试）。
+     */
+    resolve(ref: ModelRef): Promise<{
+        provider: ModelProvider;
+        info: ModelInfo;
+    }>;
+}

package/dist/runtime/providers.js

@@ -0,0 +1,224 @@
+import { assertValidDeclarations, EFFORT_VALUES, parseExtensionPoint, } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+/** 供应商模型列表在 Redis 中的缓存时长（秒）。 */
+const MODELS_TTL_SECONDS = 600;
+/** 单个供应商 `listModels()` 的时限（毫秒）：一个卡住的供应商不拖住整个列表与解析。 */
+export const LIST_MODELS_TIMEOUT_MS = 10_000;
+/**
+ * 列表视图（后台模型页、组织模型页）里列模型失败的供应商在这么多秒内直接标 error、不再请求（Redis，多副本共享）。
+ * 只用于列表；`resolve`（运行时）照常每次请求，失败由降级梯子重试。
+ */
+export const LIST_FAILURE_TTL_SECONDS = 15;
+/**
+ * 键带供应商的契约主版本：插件从 `@1` 升级到 `@2` 后不会读到 `@1`（经适配）时写入的列表
+ * （两者都是 `@2` 形状，按形状分辨不出来）。
+ * 键还带插件版本与部署配置摘要：插件升级（参数声明可能变了）或改部署配置（如增删模型）后，
+ * 各副本立即按新声明校验，不必等旧缓存 TTL 到期。摘要只是哈希，不含配置明文（secret 不进键）。
+ * 旧键按 TTL 自然过期。没有版本 / 摘要的条目（测试替身）用 `-` 占位。
+ */
+const modelsKey = (p) => `capk:models:${p.plugin}:v${p.major}:${p.version ?? "-"}:${p.configHash ?? "-"}`;
+/** 列表视图的失败标记（{@link LIST_FAILURE_TTL_SECONDS}），与模型列表同样按版本与配置摘要区分。 */
+const listFailedKey = (p) => `capk:models-failed:${p.plugin}:v${p.major}:${p.version ?? "-"}:${p.configHash ?? "-"}`;
+const CAPABILITY = "model-provider";
+/**
+ * 供应商的 `listModels()` 失败（上游不可用等）。仍是 `agent.model_unavailable`，HTTP 调用方照常
+ * 得到该错误码；运行时（`runModelStep`）据此类型把它当作可重试的失败交给降级梯子，
+ * 与「供应商未安装 / 模型不存在 / 参数声明不合规」（不可重试）区分开。
+ */
+export class ProviderListError extends ApiError {
+    provider;
+    constructor(provider, cause) {
+        super("agent.model_unavailable", `Model provider ${provider} failed to list its models`);
+        this.provider = provider;
+        this.name = "ProviderListError";
+        this.cause = cause;
+    }
+}
+/**
+ * `@1` 适配层为 `capabilities.effort` 为真的模型补的 effort 旋钮：五档，不给默认值
+ * （各家 API 的默认值不同；给了默认值会让未设置 effort 的 agent 每次都静默发送它）。
+ */
+const V1_EFFORT_KNOB = {
+    key: "effort",
+    standard: "effort",
+    schema: { type: "string", enum: [...EFFORT_VALUES] },
+    label: { zh: "思考深度", en: "Effort" },
+};
+/**
+ * 把 `model-provider@1` 实现包成 `@2`：
+ * - `listModels`：`parameters` 由 `capabilities.effort` 推导（为真时只有 effort 旋钮，否则为空）；
+ * - `stream`：`params.effort` 映射为 `req.effort`，其余参数丢弃（`@1` 没有对应字段）；
+ *   没有 `params.effort` 时保留请求自带的 `effort`。
+ */
+export function adaptModelProviderV1(impl) {
+    return {
+        async listModels() {
+            const models = await impl.listModels();
+            return models.map((m) => ({
+                ...m,
+                parameters: m.capabilities.effort ? [structuredClone(V1_EFFORT_KNOB)] : [],
+            }));
+        },
+        stream(req, opts) {
+            // `@1` 没有 toolChoice：不传（旧插件按自己的默认处理）
+            const { params, toolChoice: _toolChoice, ...rest } = req;
+            const out = rest;
+            const effort = params?.effort;
+            if (typeof effort === "string" && EFFORT_VALUES.includes(effort)) {
+                out.effort = effort;
+            }
+            return impl.stream(out, opts);
+        },
+    };
+}
+/** 缓存里的条目必须是 `@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），不放进程内存，
+ * 多副本共享同一份缓存。
+ */
+export class ProviderRegistry {
+    host;
+    kv;
+    log;
+    opts;
+    constructor(host, kv, log, opts = {}) {
+        this.host = host;
+        this.kv = kv;
+        this.log = log;
+        this.opts = opts;
+    }
+    /** `listModels()` 加时限（到时按失败处理，供应商的调用留在后台、结果丢弃）。 */
+    async listModelsWithTimeout(impl) {
+        const ms = this.opts.listTimeoutMs ?? LIST_MODELS_TIMEOUT_MS;
+        let timer;
+        const call = Promise.resolve().then(() => impl.listModels());
+        call.catch(() => { });
+        try {
+            return await Promise.race([
+                call,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`listModels timed out after ${ms}ms`)), ms);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** 每个插件取一个实现（`@2` 优先），按插件首次出现的顺序；不支持的主版本记 warn 后忽略。 */
+    providers() {
+        const chosen = new Map();
+        for (const p of this.host.list(CAPABILITY)) {
+            const { major } = parseExtensionPoint(p.capability);
+            if (major !== 1 && major !== 2) {
+                this.log?.warn("unsupported model-provider major version; ignored", {
+                    provider: p.plugin,
+                    capability: p.capability,
+                });
+                continue;
+            }
+            const prev = chosen.get(p.plugin);
+            if (!prev || major > prev.major) {
+                chosen.set(p.plugin, {
+                    major,
+                    impl: p.impl,
+                    version: p.version,
+                    configHash: p.configHash,
+                });
+            }
+        }
+        return [...chosen].map(([plugin, { major, impl, version, configHash }]) => ({
+            plugin,
+            major,
+            version,
+            configHash,
+            impl: major === 2 ? impl : adaptModelProviderV1(impl),
+        }));
+    }
+    async models(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);
+        }
+        catch (err) {
+            throw new ProviderListError(provider, err);
+        }
+        if (major === 2) {
+            try {
+                for (const m of models)
+                    assertValidDeclarations(provider, m.parameters);
+            }
+            catch (err) {
+                const e = new ApiError("agent.model_unavailable", `Model provider ${provider} declared invalid model parameters`);
+                e.cause = err;
+                throw e;
+            }
+        }
+        await this.kv.set(key, JSON.stringify(models), "EX", MODELS_TTL_SECONDS);
+        return models;
+    }
+    /** 每个已安装供应商及其模型（按插件加载顺序）；列模型失败或声明不合规的供应商跳过并记 warn。 */
+    async list() {
+        return (await this.listWithStatus()).flatMap((p) => p.status === "ok" ? [{ provider: p.provider, models: p.models }] : []);
+    }
+    /**
+     * 每个已安装供应商及其状态（按插件加载顺序，后台用）：列模型失败（含超过 {@link LIST_MODELS_TIMEOUT_MS}）或声明
+     * 不合规的标 `error`、`models` 为空，不影响其他供应商；列模型失败的在 {@link LIST_FAILURE_TTL_SECONDS} 秒内不再请求。`error` 只是内核自己的英文说明（不透出上游错误原文，原文记 warn 日志）。
+     */
+    async listWithStatus() {
+        const providers = this.providers();
+        const settled = await Promise.allSettled(providers.map(async (p) => {
+            // 刚失败过的供应商：短时间内直接标 error，不再等它（每个供应商另有时限）
+            if ((await this.kv.get(listFailedKey(p))) !== null) {
+                throw new ProviderListError(p.plugin, new Error("listModels failed recently"));
+            }
+            try {
+                return await this.models(p);
+            }
+            catch (err) {
+                if (err instanceof ProviderListError) {
+                    await this.kv.set(listFailedKey(p), "1", "EX", LIST_FAILURE_TTL_SECONDS);
+                }
+                throw err;
+            }
+        }));
+        return settled.map((r, i) => {
+            const provider = providers[i].plugin;
+            if (r.status === "fulfilled") {
+                return { provider, plugin: provider, status: "ok", models: r.value };
+            }
+            this.log?.warn("model provider listModels failed; skipped", { provider, err: r.reason });
+            const error = r.reason instanceof ApiError
+                ? r.reason.message
+                : `Model provider ${provider} failed to list its models`;
+            return { provider, plugin: provider, status: "error", error, models: [] };
+        });
+    }
+    /**
+     * 解析模型引用，返回 `@2` 形状的供应商实现（`@1` 已适配）与模型信息。
+     * 供应商未安装、模型不存在或参数声明不合规 → `agent.model_unavailable`；
+     * 供应商 `listModels()` 失败 → `ProviderListError`（同一错误码，运行时视为可重试）。
+     */
+    async resolve(ref) {
+        const p = this.providers().find((x) => x.plugin === ref.provider);
+        const info = p && (await this.models(p)).find((m) => m.id === ref.model);
+        if (!p || !info) {
+            throw new ApiError("agent.model_unavailable", `Model ${ref.provider}/${ref.model} is not available`);
+        }
+        return { provider: p.impl, info };
+    }
+}

package/dist/runtime/quota.d.ts

@@ -0,0 +1,29 @@
+import type { Redis } from "ioredis";
+import type { KernelConfig } from "../config/schema.js";
+import type { SettingsService } from "../identity/settings.js";
+/** 组织配额租约的默认时长（毫秒）：持有方每 `leaseMs / 3` 续租一次。 */
+export declare const ORG_QUOTA_LEASE_MS = 60000;
+/** 运行配额的键前缀（`capk:org-runs:<orgId>`）；评测运行用 {@link EVAL_QUOTA_PREFIX}。 */
+export declare const RUN_QUOTA_PREFIX = "capk:org-runs:";
+/** 评测运行的组织并发配额（C7）：`capk:org-evals:<orgId>`，成员为评测任务的 jobId。 */
+export declare const EVAL_QUOTA_PREFIX = "capk:org-evals:";
+/**
+ * 组织级运行并发配额（spec 4.3）：Redis ZSET `<keyPrefix><orgId>`（默认 `capk:org-runs:<orgId>`），
+ * 成员 runId（评测为 jobId）、分数为租约到期时间。
+ * 持有方崩溃时不 `leave`，成员在租约到期后被下一次 `tryEnter` 清理，名额不泄漏。
+ */
+export declare class OrgQuota {
+    private readonly redis;
+    private readonly keyPrefix;
+    constructor(redis: Redis, keyPrefix?: string);
+    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>;
+}
+/**
+ * 组织的运行并发上限：部署设置 `runConcurrencyOverrides[orgId]`，没有则用 `runtime.orgConcurrency`
+ * （热更新字段，每次经 `config()` 读当前值）。
+ */
+export declare function orgRunLimit(settings: Pick<SettingsService, "get">, config: () => KernelConfig, orgId: string): Promise<number>;

package/dist/runtime/quota.js

@@ -0,0 +1,70 @@
+/** 组织配额租约的默认时长（毫秒）：持有方每 `leaseMs / 3` 续租一次。 */
+export const ORG_QUOTA_LEASE_MS = 60_000;
+/** 运行配额的键前缀（`capk:org-runs:<orgId>`）；评测运行用 {@link EVAL_QUOTA_PREFIX}。 */
+export const RUN_QUOTA_PREFIX = "capk:org-runs:";
+/** 评测运行的组织并发配额（C7）：`capk:org-evals:<orgId>`，成员为评测任务的 jobId。 */
+export const EVAL_QUOTA_PREFIX = "capk:org-evals:";
+/** 毫秒级当前时间取 Redis 服务器时钟，各副本一致。 */
+const NOW = `
+local t = redis.call('TIME')
+local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+`;
+/**
+ * 先清理过期成员；已在集合中（同一 runId 再次进入）→ 续期；否则计数小于上限才加入。
+ * 成员为 runId，分数为租约到期时间（毫秒）。整个键 PEXPIRE leaseMs*2。
+ */
+const TRY_ENTER = `${NOW}
+local lease = tonumber(ARGV[3])
+redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now)
+if redis.call('ZSCORE', KEYS[1], ARGV[1]) or redis.call('ZCARD', KEYS[1]) < tonumber(ARGV[2]) then
+  redis.call('ZADD', KEYS[1], now + lease, ARGV[1])
+  redis.call('PEXPIRE', KEYS[1], lease * 2)
+  return 1
+end
+return 0
+`;
+/** 成员仍在（未过期）才续期。 */
+const RENEW = `${NOW}
+local lease = tonumber(ARGV[2])
+redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now)
+if redis.call('ZSCORE', KEYS[1], ARGV[1]) then
+  redis.call('ZADD', KEYS[1], now + lease, ARGV[1])
+  redis.call('PEXPIRE', KEYS[1], lease * 2)
+  return 1
+end
+return 0
+`;
+/**
+ * 组织级运行并发配额（spec 4.3）：Redis ZSET `<keyPrefix><orgId>`（默认 `capk:org-runs:<orgId>`），
+ * 成员 runId（评测为 jobId）、分数为租约到期时间。
+ * 持有方崩溃时不 `leave`，成员在租约到期后被下一次 `tryEnter` 清理，名额不泄漏。
+ */
+export class OrgQuota {
+    redis;
+    keyPrefix;
+    constructor(redis, keyPrefix = RUN_QUOTA_PREFIX) {
+        this.redis = redis;
+        this.keyPrefix = keyPrefix;
+    }
+    key(orgId) {
+        return `${this.keyPrefix}${orgId}`;
+    }
+    async tryEnter(orgId, runId, limit, leaseMs = ORG_QUOTA_LEASE_MS) {
+        return (Number(await this.redis.eval(TRY_ENTER, 1, this.key(orgId), runId, limit, leaseMs)) === 1);
+    }
+    /** 续期；成员已过期被清理 → false。 */
+    async renew(orgId, runId, leaseMs = ORG_QUOTA_LEASE_MS) {
+        return Number(await this.redis.eval(RENEW, 1, this.key(orgId), runId, leaseMs)) === 1;
+    }
+    async leave(orgId, runId) {
+        await this.redis.zrem(this.key(orgId), runId);
+    }
+}
+/**
+ * 组织的运行并发上限：部署设置 `runConcurrencyOverrides[orgId]`，没有则用 `runtime.orgConcurrency`
+ * （热更新字段，每次经 `config()` 读当前值）。
+ */
+export async function orgRunLimit(settings, config, orgId) {
+    const { runConcurrencyOverrides } = await settings.get();
+    return runConcurrencyOverrides[orgId] ?? config().runtime.orgConcurrency;
+}

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

@@ -0,0 +1,45 @@
+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>;
+/** 运行的终态。 */
+export type TerminalStatus = "completed" | "failed" | "aborted";
+export declare const TERMINAL_STATUSES: ReadonlySet<string>;
+export interface FinishRunArgs {
+    conversationId: string;
+    runId: string;
+    status: TerminalStatus;
+    /** loop 吸收到的位置；null 表示未知（仍至少推进到触发消息）。 */
+    consumed: number | null;
+    /** 终态事件（run_finished / run_failed / run_aborted），幂等键为 `<type>:<runId>`。 */
+    event: Pick<AppendEvent, "type" | "payload">;
+    /**
+     * consumed_seq 是否至少推进到 `runs.trigger_seq`，默认 true（失败、中止、完成）。
+     * 超时（max_duration）传 false：loop 没吸收的消息没有被回复，必须留给下一轮（R34）。
+     */
+    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).
+     */
+    beforeTerminal?: (t: KernelTrx) => 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`。
+ */
+export declare function finishRunIn(t: KernelTrx, eventLog: EventLog, a: FinishRunArgs): Promise<number | null>;
+/**
+ * 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

@@ -0,0 +1,69 @@
+import { sql } from "kysely";
+import { pauseQueueIn } from "../conversations/queue.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`。
+ */
+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;
+}
+/**
+ * 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 async function notifyFinished(eventLog, conversationId, toSeq, status) {
+    await eventLog.notify(conversationId, toSeq);
+    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-queue.d.ts

@@ -0,0 +1,121 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { Redis } from "ioredis";
+import { type Transaction } from "kysely";
+import type { EventLog } from "../conversations/event-log.js";
+import type { ConversationKind, KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { RunAbortDetail } from "./abort.js";
+import type { KyselyCheckpointSaver } from "./checkpointer.js";
+import type { ConversationLock } from "./conversation-lock.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;
+/** 运行任务的数据。 */
+export interface RunJobData {
+    runId: string;
+    conversationId: string;
+}
+/** 同一触发点（会话 + 最新用户消息 seq）只投递一次。 */
+export declare const runJobId: (conversationId: string, maxUserSeq: number) => string;
+/** 未结束的运行状态（waiting：等人处理审批 / 输入请求，没有任务、不占会话锁与配额）。 */
+export declare const ACTIVE_RUN_STATUSES: readonly ["queued", "running", "waiting"];
+type KernelTrx = Transaction<KernelDatabase>;
+/** What an orphan repair does for a parent's sub-agents (wired by the kernel). */
+export interface OrphanSubagents {
+    /** `ToolPipeline.stopOpenAgentCalls`: the run's open `agent` call results, in `t`. */
+    stopOpenCalls(t: KernelTrx, runId: string): Promise<{
+        fire: () => void;
+    }>;
+    /** `stopChildren(runId, null)`: after the commit, its active children stop. */
+    stopChildren(runId: string): Promise<unknown>;
+}
+/** BullMQ 连接要求 maxRetriesPerRequest 为 null（Worker 的阻塞连接）；Queue 复用同样的配置。 */
+export declare function bullConnection(redisUrl: string, log: Pick<Logger, "error">): Redis;
+/**
+ * 运行队列（生产方）：`ensureRun` 在会话有未消费的用户消息、且没有进行中的运行时插入 `runs` 行并投递任务。
+ * 「是否已有运行」以 PG 为准（会话行锁内检查 `runs` 中的 queued / running），并参考会话锁的持有者；
+ * 多副本并发调用对同一会话串行化，同一时刻至多一个未结束的运行。
+ */
+export declare class RunQueue {
+    private readonly db;
+    private readonly eventLog;
+    private readonly lock;
+    private readonly redisUrl;
+    private readonly log;
+    /** 运行以孤儿结束（标记失败 / 直接中止）后删除它的 checkpoint thread（thread_id = runId）。 */
+    private readonly checkpoints?;
+    /** Sub-agent cleanup when an orphan repair ends a parent run (sub-agents spec §12). */
+    private readonly subagents?;
+    private readonly queues;
+    private conn;
+    private closed;
+    constructor(db: KernelDb, eventLog: EventLog, lock: Pick<ConversationLock, "holder">, redisUrl: string, log: Pick<Logger, "error" | "warn">, 
+    /** 运行以孤儿结束（标记失败 / 直接中止）后删除它的 checkpoint thread（thread_id = runId）。 */
+    checkpoints?: Pick<KyselyCheckpointSaver, "deleteThread"> | undefined, 
+    /** Sub-agent cleanup when an orphan repair ends a parent run (sub-agents spec §12). */
+    subagents?: OrphanSubagents | undefined);
+    /**
+     * The `beforeTerminal` of an orphan repair: writes the run's open `agent` call results in `t`;
+     * `fire()` runs their observe hooks after the commit (review m1).
+     */
+    private stopOpenCalls;
+    /** The BullMQ queue `name` (default: conversation runs); both share one connection. */
+    private getQueue;
+    /**
+     * 有未消费的用户消息（最新 user_message 的 seq > `consumed_seq`）、会话锁无人持有、
+     * 且没有 queued / running / waiting 的运行时：插入 `runs`（queued）并投递任务，返回 runId；否则返回 null。
+     *
+     * 孤儿清理（R29，按需进行，没有定时器）：已有的 queued / running 运行若 BullMQ 任务已不存在、
+     * 会话锁也无人持有（queued 的还要超过宽限期），说明没有任何 worker 会再执行它——写
+     * `run_failed { code: "run.orphaned" }` 把它标记为失败（consumed_seq 推进到它的触发消息），
+     * 再按常规判断是否起新一轮，并删除它的 checkpoint thread。会话因此不会永远卡在「有运行」。
+     * 除了写入消息后，打开 SSE、读事件、运行结束后也会调用它（幂等），孤儿因此在有人查看时就被清理。
+     *
+     * agent 已软删除的会话不起新运行（孤儿清理照常进行）。
+     */
+    ensureRun(conversationId: string): Promise<string | null>;
+    /**
+     * Enqueues a run job under the caller's job id (resumes, dispatches, repairs), with the same
+     * options as {@link ensureRun}. 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>;
+    /**
+     * 中止一个孤儿运行（`POST .../abort` 用）：运行仍是 queued / running、会话锁无人持有、BullMQ 任务已不存在
+     * （queued 的还要超过宽限期，判定同 {@link ensureRun} 的孤儿清理）时，没有任何 worker 会收到中止广播——
+     * 直接写 `run_aborted`、status 置为 aborted、consumed_seq 至少推进到触发消息，返回 true。
+     * 不是孤儿（有人在执行或即将执行）或运行已结束 → 返回 false，由调用方走广播中止。
+     */
+    abortIfOrphaned(conversationId: string, runId: string, byAccountId: string | null, detail?: RunAbortDetail): Promise<boolean>;
+    /**
+     * Repairs an orphaned run of a conversation nobody else repairs on demand (a sub-agent's: no
+     * `ensureRun` ever runs for it; sub-agents spec §7.5), with the same orphan test as
+     * {@link ensureRun}: the conversation lock is free, the run is still `queued` / `running`, its
+     * job is gone, and a `queued` one is past the grace period.
+     * - `queued` (the dispatch or resume committed, its enqueue was lost) → enqueued again under its
+     *   own job id (`runs.job_id`, else the trigger's), so concurrent repairs on several replicas
+     *   still leave one job: `"requeued"`;
+     * - `running` (its worker died without a terminal state and BullMQ dropped the job) → marked
+     *   failed `run.orphaned`; the caller reports it to the parent: `"failed"`.
+     * Not an orphan, or already finished → null.
+     */
+    repairOrphan(conversationId: string, runId: string): Promise<"requeued" | "failed" | null>;
+    /** 会话当前未结束的运行（调用方已持有会话行锁）。 */
+    private activeRun;
+    /**
+     * 未结束的运行是否已是孤儿（调用方已确认会话锁无人持有）：waiting → 否（等人处理，本来就没有任务，
+     * 由人工决定或超时任务续跑）；queued 且仍在宽限期内 → 否（任务可能还没投递）；BullMQ 任务（续跑任务按
+     * `runs.job_id`）仍存在 → 否；否则是。
+     */
+    private isOrphan;
+    /** 删除已结束运行的 checkpoint thread（失败只记日志）。 */
+    private dropCheckpoints;
+    private deleteQueued;
+    close(): Promise<void>;
+}
+export {};