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

package/dist/runtime/maintenance.js

@@ -1,148 +1,150 @@
-import { Queue, Worker } from "bullmq";
-import { sql } from "kysely";
-import { withJobContext } from "../log-context.js";
-import { bullConnection } from "./run-queue.js";
+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, OnWorkerEvent, WorkerHost } from "@nestjs/bullmq";
+import { Inject, Injectable, Module } from "@nestjs/common";
+import { configuredProcessor } from "../infra/queue/configured-processor.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { removeRetiredSchedulers } from "../infra/queue/retired-schedulers.js";
+import { runJob } from "../infra/queue/run-job.js";
+import { KernelScheduleModule } from "../infra/schedule/schedule.module.js";
+import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { DIRECTORY_SYNC_JOB, DirectorySync } from "../orgs/directory-sync.js";
+import { OrgsModule } from "../orgs/orgs.module.js";
+import { runSandboxDestroyFor, SANDBOX_DESTROY_FOR_JOB } from "../sandbox/jobs.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { ToolDrift } from "../tools/drift.js";
+import { DRIFT_CONNECTOR_JOB } from "../tools/job-ids.js";
+import { ToolsModule } from "../tools/tools.module.js";
+import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
+import { RETIRED_SCHEDULER_IDS } from "./retired-schedulers.js";
+import { RuntimeModule } from "./runtime.module.js";
+import { WAIT_TIMEOUT_JOB, Waits } from "./waits.js";
+export { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
+/** The maintenance worker's concurrency (as the hand-made worker had). */
+export const MAINTENANCE_CONCURRENCY = 5;
 /**
- * 内核维护队列（不含 `:`）：等待超时任务（`wait-timeout`，见 waits.ts）与周期性维护（输出存档清理、
- * 工具漂移检测（见 tools/drift.ts）、等待兜底扫描（`wait-sweep`，见 waits.ts）、沙箱的空闲休眠与不活跃销毁
- * （见 sandbox/lifecycle.ts）等）。整个队列只有一个 Worker（只在 `worker` 角色上启动），
- * 按任务名分派给登记的处理函数。
- * 与运行队列分开：运行 worker 的处理函数、stalled / 失败处理都按「一个任务 = 一次运行」设计；
- * 维护任务短、无会话锁与配额。
+ * The one consumer of `cap-kernel-maintenance` (decision R11 of the Nest kernel spec): dispatches
+ * each one-off job by name to its domain (`wait-timeout` → {@link Waits}, `sandbox-destroy-for` →
+ * {@link SandboxService}, `drift-connector` → {@link ToolDrift}, `directory-sync` →
+ * {@link DirectorySync}). The name of a periodic job (a `@LockedCron` / `@LockedInterval` job,
+ * such as `sandbox-suspend-idle`) runs that job's body once ({@link ScheduledRuns.runNow}), as the
+ * maintenance handlers did when those jobs were schedulers on this queue: an operator's or a
+ * test's one-off run, not a second schedule (decision R23 of the Nest kernel spec). Any other
+ * name is warned and completes. The producers are the domains' own (same names, ids and options).
  */
-export const MAINTENANCE_QUEUE_NAME = "cap-kernel-maintenance";
-/** 输出存档清理：任务名、job scheduler id（不含 `:`）、周期与每批删除行数。 */
-export const OUTPUT_CLEANUP_JOB = "output-cleanup";
-export const OUTPUT_CLEANUP_SCHEDULER_ID = "output-cleanup-hourly";
-export const OUTPUT_CLEANUP_EVERY_MS = 3_600_000;
-export const OUTPUT_CLEANUP_BATCH = 1000;
-/**
- * Periodic marketplace refresh (C26): job name and job scheduler id (no `:`), every
- * `marketplaces.refreshIntervalMinutes`. One scheduler for all replicas; the handler refreshes each
- * enabled marketplace in turn (see catalog/marketplaces.service.ts). The values keep their old
- * names: the scheduler id is stored in Redis, and renaming it would leave the old scheduler behind.
- */
-export const MARKETPLACES_REFRESH_JOB = "catalogs-refresh";
-export const MARKETPLACES_REFRESH_SCHEDULER_ID = "catalogs-refresh-every";
-/**
- * Cleanup of plugin (app bundle) import staging (T25, F-AE): job name and job scheduler id (no
- * `:`), hourly; deletes expired (24-hour) staging rows and their object storage prefixes (see
- * catalog/plugin-import.ts `PluginImport.cleanupExpired`). The values keep their old names: the
- * scheduler id is stored in Redis, so renaming it would leave the old scheduler behind.
- */
-export const PLUGIN_STAGING_CLEANUP_JOB = "app-staging-cleanup";
-export const PLUGIN_STAGING_CLEANUP_SCHEDULER_ID = "app-staging-cleanup-hourly";
-export const PLUGIN_STAGING_CLEANUP_EVERY_MS = 3_600_000;
-/**
- * 删除已过期（`expires_at < now()`）的输出存档，每批 `batch` 行，直到删完；返回删除的总行数。
- * 每批一条独立语句（不开长事务）；多个 worker 同时清理时 `SKIP LOCKED` 互不等待。
- */
-export async function deleteExpiredOutputs(db, batch = OUTPUT_CLEANUP_BATCH) {
-    let total = 0;
-    for (;;) {
-        const r = await db
-            .deleteFrom("tool_outputs")
-            .where("id", "in", db
-            .selectFrom("tool_outputs")
-            .select("id")
-            .where("expires_at", "<", sql `now()`)
-            .limit(batch)
-            .forUpdate()
-            .skipLocked())
-            .executeTakeFirst();
-        const n = Number(r.numDeletedRows);
-        total += n;
-        if (n < batch)
-            return total;
-    }
-}
-/**
- * 维护队列的生产方与（worker 角色上的）唯一 Worker。状态都在 Redis / PG，没有进程内定时器：
- * 周期任务用 BullMQ job scheduler（`upsertJobScheduler` 幂等，多副本重复调用只有一个 scheduler）。
- */
-export class Maintenance {
-    d;
+let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
+    waits;
+    sandbox;
+    drift;
+    directory;
+    scheduled;
+    log;
     queue;
-    queueConn;
-    worker;
-    workerConn;
-    closed = false;
-    handlers = new Map();
-    schedules = [];
-    constructor(d) {
-        this.d = d;
-        this.handle(OUTPUT_CLEANUP_JOB, async () => {
-            const n = await deleteExpiredOutputs(d.db);
-            if (n > 0)
-                d.log.info("expired tool outputs deleted", { count: n });
-        });
-    }
-    /** 登记某个任务名的处理函数（构造期调用；Worker 启动前后都可）。 */
-    handle(name, fn) {
-        this.handlers.set(name, fn);
+    constructor(waits, sandbox, drift, directory, scheduled, log, queue) {
+        super();
+        this.waits = waits;
+        this.sandbox = sandbox;
+        this.drift = drift;
+        this.directory = directory;
+        this.scheduled = scheduled;
+        this.log = log;
+        this.queue = queue;
     }
-    /** 登记一个周期任务（构造期调用；`ensureSchedules` 时一并 upsert）。 */
-    schedule(s) {
-        this.schedules.push(s);
+    /**
+     * Removes the retired job schedulers (`RETIRED_SCHEDULER_IDS`, runtime/retired-schedulers.ts): every fixed-period
+     * maintenance job is a `@LockedCron` / `@LockedInterval` now. Idempotent; called once when a
+     * worker role starts.
+     */
+    removeRetiredSchedulers() {
+        return removeRetiredSchedulers(this.queue, RETIRED_SCHEDULER_IDS);
     }
-    /** 投递一个维护任务。 */
-    async add(name, data, opts) {
-        await this.getQueue().add(name, data, opts);
-    }
-    /** 登记周期任务的 job scheduler（幂等；worker 角色启动时调用）。 */
-    async ensureSchedules() {
-        await this.getQueue().upsertJobScheduler(OUTPUT_CLEANUP_SCHEDULER_ID, { every: OUTPUT_CLEANUP_EVERY_MS }, {
-            name: OUTPUT_CLEANUP_JOB,
-            data: {},
-            opts: { removeOnComplete: true, removeOnFail: 100 },
-        });
-        for (const s of this.schedules) {
-            await this.getQueue().upsertJobScheduler(s.id, { every: s.everyMs() }, { name: s.name, data: {}, opts: { removeOnComplete: true, removeOnFail: 100 } });
-        }
+    process(job, token) {
+        return runJob(MAINTENANCE_QUEUE_NAME, job, () => this.dispatch(job, token));
     }
-    /** 启动维护队列的 Worker（只在含 `worker` 角色的进程）。 */
-    startWorker() {
-        if (this.worker || this.closed)
-            return;
-        this.workerConn = bullConnection(this.d.redisUrl, this.d.log);
-        this.worker = new Worker(MAINTENANCE_QUEUE_NAME, (job, token) => withJobContext(MAINTENANCE_QUEUE_NAME, job, () => this.process(job, token)), {
-            connection: this.workerConn,
-            concurrency: 5,
-        });
-        this.worker.on("error", (err) => this.d.log.error("maintenance worker error", { err }));
-        this.worker.on("failed", (job, err) => this.d.log.error("maintenance job failed", { name: job?.name, jobId: job?.id, err }));
+    /** Starts consuming (worker role, after the extensions loaded; built with `autorun: false`). */
+    start() {
+        void this.worker.run().catch((err) => this.error(err));
     }
-    async close() {
-        this.closed = true;
-        const w = this.worker;
-        const q = this.queue;
-        this.worker = undefined;
-        this.queue = undefined;
-        await w?.close().catch(() => { });
-        await q?.close().catch(() => { });
-        for (const c of [this.workerConn, this.queueConn]) {
-            if (c)
-                await c.quit().catch(() => c.disconnect());
+    async dispatch(job, token) {
+        switch (job.name) {
+            case WAIT_TIMEOUT_JOB:
+                await this.waits.processTimeout(job, token);
+                return;
+            case SANDBOX_DESTROY_FOR_JOB:
+                await runSandboxDestroyFor(this.sandbox, this.log, job);
+                return;
+            case DRIFT_CONNECTOR_JOB: {
+                const { orgId, connectorId, trigger } = job.data;
+                await this.drift.check(orgId, connectorId, trigger);
+                return;
+            }
+            case DIRECTORY_SYNC_JOB:
+                await this.directory.runSyncJob(job.data);
+                return;
+            default:
+                if (await this.scheduled.runNow(job.name))
+                    return;
+                this.log.warn("unknown maintenance job", { name: job.name, jobId: job.id });
         }
-        this.workerConn = undefined;
-        this.queueConn = undefined;
     }
-    getQueue() {
-        if (this.closed)
-            throw new Error("maintenance queue is closed");
-        if (!this.queue) {
-            this.queueConn = bullConnection(this.d.redisUrl, this.d.log);
-            this.queue = new Queue(MAINTENANCE_QUEUE_NAME, { connection: this.queueConn });
-            this.queue.on("error", (err) => this.d.log.error("maintenance queue error", { err }));
-        }
-        return this.queue;
+    failed(job, err) {
+        this.log.error("maintenance job failed", { name: job?.name, jobId: job?.id, err });
     }
-    async process(job, token) {
-        const fn = this.handlers.get(job.name);
-        if (!fn) {
-            this.d.log.warn("unknown maintenance job", { name: job.name, jobId: job.id });
-            return;
-        }
-        await fn(job, token);
+    error(err) {
+        this.log.error("maintenance worker error", { err });
     }
-}
+};
+__decorate([
+    OnWorkerEvent("failed")
+], MaintenanceProcessor.prototype, "failed", null);
+__decorate([
+    OnWorkerEvent("error")
+], MaintenanceProcessor.prototype, "error", null);
+MaintenanceProcessor = __decorate([
+    Injectable(),
+    __param(0, Inject(Waits)),
+    __param(1, Inject(SandboxService)),
+    __param(2, Inject(ToolDrift)),
+    __param(3, Inject(DirectorySync)),
+    __param(4, Inject(ScheduledRuns)),
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
+], MaintenanceProcessor);
+export { MaintenanceProcessor };
+/**
+ * The maintenance queue's consumer: {@link MaintenanceProcessor}. Imported only by the worker role
+ * (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by
+ * itself: the worker role (`WorkerRole`) removes the retired job schedulers and starts it after the
+ * extensions loaded.
+ */
+let MaintenanceModule = class MaintenanceModule {
+};
+MaintenanceModule = __decorate([
+    Module({
+        imports: [
+            // the periodic jobs' bodies (a periodic job's name enqueued here runs it once)
+            KernelScheduleModule,
+            RuntimeModule,
+            SandboxModule,
+            ToolsModule,
+            OrgsModule,
+            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
+        ],
+        providers: [
+            configuredProcessor(MaintenanceProcessor, MAINTENANCE_QUEUE_NAME, {
+                concurrency: MAINTENANCE_CONCURRENCY,
+            }),
+        ],
+        exports: [MaintenanceProcessor],
+    })
+], MaintenanceModule);
+export { MaintenanceModule };

package/dist/runtime/model-call.d.ts

@@ -1,14 +1,15 @@
 import { type ContentBlock, type Logger, type ModelProvider, type ModelRequest, type ModelStreamEvent, type ModelUsage, type StopReason } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../agents/definition.js";
-import type { KernelConfig } from "../config/schema.js";
 import type { EventLog } from "../conversations/event-log.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import type { ToolRegistry, UnavailableTool } from "../tools/registry.js";
 import { type BuildModelRequestInput, type MediaBytes, type MediaInfo, type ModelCallMeta, type RequestTool } from "./context/build.js";
 import { type ConversationKindForHooks, type HookRunner } from "./hook-calls.js";
 import type { SubagentParent } from "./loop.js";
 import { MediaCache } from "./media-cache.js";
 import { type ProviderRegistry } from "./providers.js";
+import type { StepLog } from "./step-log.js";
 import type { UsageReporter } from "./usage-report.js";
 /** 单轮收尾的尾部提醒（模型可见，英文；spec 6 轮次额度收尾）。 */
 export declare const WRAP_UP_REMINDER = "Step limit reached. Do not call tools. Summarize what you found and what remains for the user.";
@@ -28,12 +29,14 @@ export type StreamSink = (delta: {
     text?: string;
 }) => void;
 export interface ModelStepDeps {
-    db: KernelDb;
+    db: KernelSchemaDb;
     eventLog: EventLog;
+    /** The step's transactional writes (a model call with its tool specs, a denial with its audit row, a sub-agent's counted usage). */
+    stepLog: Pick<StepLog, "appendCounted" | "appendAudited" | "appendWithSpecs">;
     registry: Pick<ProviderRegistry, "resolve">;
     /** 工具注册表：每步开始时解析 agent 引用的工具（状态可能在步骤之间变化）。 */
     tools: Pick<ToolRegistry, "forAgent">;
-    config: () => KernelConfig;
+    config: Pick<KernelConfigService, "get">;
     log: Logger;
     /**
      * 会话附件（构建请求时解析日志里的媒体引用；见 AttachmentsService）。未提供时媒体引用一律按「不再可用」处理。

package/dist/runtime/model-call.js

@@ -1,12 +1,8 @@
 import { isModelError, isRetryableKind, ModelError, sanitizeParams, } from "@capybara-hq/plugin-sdk";
-import { sql } from "kysely";
 import { MEDIA_EXCLUDED_MAX_IDS } from "../conversations/events.js";
 import { ApiError } from "../errors.js";
-import { usageTokens } from "../evals/budget.js";
 import { ExtensionUnloadedError } from "../extensions/inflight.js";
-import { audit } from "../identity/audit.js";
 import { hasInvocation, skillLoadOffered } from "../skills/catalog.js";
-import { recordToolSpecs } from "../tools/specs.js";
 import { buildModelRequest, latestSummary, mediaRefs, planMedia, } from "./context/build.js";
 import { acceptSummary, buildCompactionRequest, compactionBackoff, compactionPlan, shouldCompact, } from "./context/compaction.js";
 import { guardToolPairs } from "./context/pairing.js";
@@ -114,7 +110,7 @@ async function runStep(deps, input, wrapUp) {
         }
         return existing;
     }
-    const runtime = deps.config().runtime;
+    const runtime = deps.config.get().runtime;
     /** 本次尝试已流出的文本；中止时写进 aborted 的 assistant_message。 */
     const streamed = { text: "" };
     try {
@@ -145,7 +141,7 @@ async function runStep(deps, input, wrapUp) {
                 looked: new Set(),
                 info: new Map(),
                 bytes: new Map(),
-                run: input.mediaCache ?? new MediaCache(deps.config().attachments.requestMediaBytes),
+                run: input.mediaCache ?? new MediaCache(deps.config.get().attachments.requestMediaBytes),
             },
         };
         const beforeCompaction = events.length;
@@ -240,29 +236,7 @@ async function appendCounted(deps, input, events) {
     const { conversationId, parentRunId } = input;
     if (parentRunId === undefined)
         return deps.eventLog.append(conversationId, events);
-    const out = await deps.db.transaction().execute(async (t) => {
-        // the conversation row lock the append takes anyway, taken first to read the seq before it
-        const before = await t
-            .selectFrom("conversations")
-            .select("last_seq")
-            .where("id", "=", conversationId)
-            .forUpdate()
-            .executeTakeFirstOrThrow();
-        const written = await deps.eventLog.append(conversationId, events, t);
-        const fresh = written.filter((e) => e.seq > Number(before.last_seq));
-        let tokens = 0;
-        for (const e of fresh)
-            if (e.type === "usage")
-                tokens += usageTokens(e.payload);
-        if (tokens > 0) {
-            await t
-                .updateTable("runs")
-                .set({ subagent_tokens_used: sql `subagent_tokens_used + ${tokens}` })
-                .where("id", "=", parentRunId)
-                .execute();
-        }
-        return { written, toSeq: fresh.length > 0 ? Math.max(...fresh.map((e) => e.seq)) : null };
-    });
+    const out = await deps.stepLog.appendCounted(conversationId, parentRunId, events);
     if (out.toSeq !== null)
         await deps.eventLog.notify(conversationId, out.toSeq);
     return out.written;
@@ -401,7 +375,7 @@ function buildRequest(deps, events, input, info, params, runtime, tools, wrapUp)
         ...(wrapUp && { toolChoice: "none" }),
         mediaInfo: tools.media.info,
         media: tools.media.bytes,
-        mediaBudgetBytes: deps.config().attachments.requestMediaBytes,
+        mediaBudgetBytes: deps.config.get().attachments.requestMediaBytes,
         defaultMaxOutputTokens: runtime.maxOutputTokens,
     });
     return {
@@ -434,7 +408,7 @@ async function loadMedia(deps, input, events, info, tools) {
         for (const id of look)
             cache.looked.add(id);
     }
-    const budget = deps.config().attachments.requestMediaBytes;
+    const budget = deps.config.get().attachments.requestMediaBytes;
     const plan = planMedia(events, info, cache.info, budget);
     const runKey = (id) => MediaCache.key(id, cache.info.get(id), plan.caps.get(id));
     const need = [];
@@ -589,11 +563,7 @@ async function maybeCompact(deps, input, events, runtime, tools) {
                 plugin: verdict.plugin,
                 cause: verdict.cause,
             });
-            const written = await deps.db.transaction().execute(async (t) => {
-                const out = await deps.eventLog.append(conversationId, [failed], t);
-                await audit(t, entry);
-                return out;
-            });
+            const written = await deps.stepLog.appendAudited(conversationId, [failed], entry);
             if (written.length > 0) {
                 await deps.eventLog.notify(conversationId, Math.max(...written.map((e) => e.seq)));
             }
@@ -783,29 +753,26 @@ async function ladder(deps, input, events, runtime, tools, wrapUp, streamed) {
             // 请求里的工具定义（含目录里的）按指纹存进 tool_specs，与 model_call 同一事务
             // （请求可由日志 + tool_specs 还原）
             const sent = new Set([...meta.tools, ...(meta.catalog ?? [])].map((t) => t.specHash));
-            const written = await deps.db.transaction().execute(async (t) => {
-                await recordToolSpecs(t, tools.list.filter((x) => sent.has(x.specHash)));
-                return deps.eventLog.append(conversationId, [
-                    {
-                        type: "model_call",
-                        runId,
-                        idemKey: idem.modelCall(runId, step, attempt),
-                        payload: {
-                            step,
-                            attempt,
-                            provider: rung.ref.provider,
-                            model: rung.ref.model,
-                            fallback: rung.fallback,
-                            request: {
-                                ...meta,
-                                maxOutputTokens: request.maxOutputTokens,
-                                ...(params.dropped.length > 0 && { droppedParams: params.dropped }),
-                                estimatedInputTokens: estimate,
-                            },
+            const written = await deps.stepLog.appendWithSpecs(conversationId, tools.list.filter((x) => sent.has(x.specHash)), [
+                {
+                    type: "model_call",
+                    runId,
+                    idemKey: idem.modelCall(runId, step, attempt),
+                    payload: {
+                        step,
+                        attempt,
+                        provider: rung.ref.provider,
+                        model: rung.ref.model,
+                        fallback: rung.fallback,
+                        request: {
+                            ...meta,
+                            maxOutputTokens: request.maxOutputTokens,
+                            ...(params.dropped.length > 0 && { droppedParams: params.dropped }),
+                            estimatedInputTokens: estimate,
                         },
                     },
-                ], t);
-            });
+                },
+            ]);
             await deps.eventLog.notify(conversationId, Math.max(...written.map((e) => e.seq)));
             sentAt = Date.now();
             const outcome = await consumeModelStream(provider, request, info.streamIdleTimeoutMs ?? runtime.streamIdleMs, signal, (ev) => {

package/dist/runtime/providers.d.ts

@@ -2,8 +2,11 @@ import { type ExtensionPointRef, type Logger, type ModelInfo, type ModelProvider
 import type { Redis } from "ioredis";
 import type { ModelRef } from "../agents/definition.js";
 import { ApiError } from "../errors.js";
+import { CacheService } from "../infra/cache/cache.service.js";
 /** 单个供应商 `listModels()` 的时限（毫秒）：一个卡住的供应商不拖住整个列表与解析。 */
 export declare const LIST_MODELS_TIMEOUT_MS = 10000;
+/** Optional provider: the `listModels()` time limit (ms) instead of {@link LIST_MODELS_TIMEOUT_MS} (tests). */
+export declare const LIST_MODELS_TIMEOUT: unique symbol;
 /**
  * 列表视图（后台模型页、组织模型页）里列模型失败的供应商在这么多秒内直接标 error、不再请求（Redis，多副本共享）。
  * 只用于列表；`resolve`（运行时）照常每次请求，失败由降级梯子重试。
@@ -48,22 +51,27 @@ export declare function adaptModelProviderV1(impl: ModelProviderV1): ModelProvid
  * 同时支持 `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 declare class ProviderRegistry {
     private readonly host;
+    readonly cacheService: CacheService;
     private readonly kv;
     private readonly log?;
-    private readonly opts;
-    constructor(host: ProviderHost, kv: Redis, log?: Pick<Logger, "warn"> | undefined, opts?: {
-        listTimeoutMs?: number;
-    });
+    /** The `listModels()` time limit. */
+    private readonly listTimeoutMs;
+    constructor(host: ProviderHost, cacheService: CacheService, kv: Redis, log?: Pick<Logger, "warn"> | undefined, 
+    /** The `listModels()` time limit. */
+    listTimeoutMs?: number);
     /** `listModels()` 加时限（到时按失败处理，供应商的调用留在后台、结果丢弃）。 */
     private listModelsWithTimeout;
     /** 每个插件取一个实现（`@2` 优先），按插件首次出现的顺序；不支持的主版本记 warn 后忽略。 */
     private providers;
     private models;
+    /** The provider's validated model list, cached under `key` (see {@link modelsKey}). */
+    private validatedModels;
     /** 每个已安装供应商及其模型（按插件加载顺序）；列模型失败或声明不合规的供应商跳过并记 warn。 */
     list(): Promise<{
         provider: string;
@@ -84,3 +92,6 @@ export declare class ProviderRegistry {
         info: ModelInfo;
     }>;
 }
+/** The model provider registry (one instance; the models and agents domains read it). */
+export declare class ProvidersModule {
+}