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

package/dist/runtime/maintenance.d.ts

@@ -1,80 +1,56 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
-import { type Job, type JobsOptions } from "bullmq";
-import type { KernelDb } from "../db/kernel-schema.js";
+import { WorkerHost } from "@nestjs/bullmq";
+import type { Job, Queue, Worker } from "bullmq";
+import { OwnedPluginCleanup } from "../catalog/owned-plugin-cleanup.js";
+import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
+import type { KernelLogger } from "../log.js";
+import { DirectorySync } from "../orgs/directory-sync.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { ToolDrift } from "../tools/drift.js";
+import { RunQueue } from "./run-queue.js";
+import { Waits } from "./waits.js";
+export { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
+/** The maintenance worker's concurrency (as the hand-made worker had). */
+export declare 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` and
+ * `sandbox-reset-files` → {@link SandboxService}, `drift-connector` → {@link ToolDrift}, `directory-sync` →
+ * {@link DirectorySync}, `bg-wake` → {@link RunQueue.ensureRun}, `owned-plugin-cleanup` →
+ * {@link OwnedPluginCleanup}). 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 declare const MAINTENANCE_QUEUE_NAME = "cap-kernel-maintenance";
-/** 输出存档清理：任务名、job scheduler id（不含 `:`）、周期与每批删除行数。 */
-export declare const OUTPUT_CLEANUP_JOB = "output-cleanup";
-export declare const OUTPUT_CLEANUP_SCHEDULER_ID = "output-cleanup-hourly";
-export declare const OUTPUT_CLEANUP_EVERY_MS = 3600000;
-export declare 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 declare const MARKETPLACES_REFRESH_JOB = "catalogs-refresh";
-export declare 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 declare const PLUGIN_STAGING_CLEANUP_JOB = "app-staging-cleanup";
-export declare const PLUGIN_STAGING_CLEANUP_SCHEDULER_ID = "app-staging-cleanup-hourly";
-export declare const PLUGIN_STAGING_CLEANUP_EVERY_MS = 3600000;
-/** 维护任务的处理函数（`token` 供 `moveToDelayed` 等使用）。 */
-export type MaintenanceHandler = (job: Job, token: string | undefined) => Promise<void>;
-/** 由其他模块登记的周期任务（如漂移检测）：scheduler id 与任务名不含 `:`，周期在登记时读取。 */
-export interface MaintenanceSchedule {
-    id: string;
-    name: string;
-    everyMs: () => number;
-}
-/**
- * 删除已过期（`expires_at < now()`）的输出存档，每批 `batch` 行，直到删完；返回删除的总行数。
- * 每批一条独立语句（不开长事务）；多个 worker 同时清理时 `SKIP LOCKED` 互不等待。
- */
-export declare function deleteExpiredOutputs(db: KernelDb, batch?: number): Promise<number>;
-export interface MaintenanceDeps {
-    db: KernelDb;
-    redisUrl: string;
-    log: Pick<Logger, "error" | "warn" | "info">;
+export declare class MaintenanceProcessor extends WorkerHost<Worker> {
+    private readonly waits;
+    private readonly sandbox;
+    private readonly drift;
+    private readonly directory;
+    private readonly runs;
+    private readonly ownedCleanup;
+    private readonly scheduled;
+    private readonly log;
+    private readonly queue;
+    constructor(waits: Pick<Waits, "processTimeout">, sandbox: Pick<SandboxService, "destroyEnvironment" | "resetFileSystem">, drift: Pick<ToolDrift, "check">, directory: Pick<DirectorySync, "runSyncJob">, runs: Pick<RunQueue, "ensureRun">, ownedCleanup: Pick<OwnedPluginCleanup, "run">, scheduled: Pick<ScheduledRuns, "runNow">, log: Pick<KernelLogger, "error" | "warn">, queue: Pick<Queue, "removeJobScheduler">);
+    /**
+     * 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(): Promise<void>;
+    process(job: Job, token?: string): Promise<void>;
+    /** Starts consuming (worker role, after the extensions loaded; built with `autorun: false`). */
+    start(): void;
+    private dispatch;
+    failed(job: Job | undefined, err: Error): void;
+    error(err: Error): void;
 }
 /**
- * 维护队列的生产方与（worker 角色上的）唯一 Worker。状态都在 Redis / PG，没有进程内定时器：
- * 周期任务用 BullMQ job scheduler（`upsertJobScheduler` 幂等，多副本重复调用只有一个 scheduler）。
+ * 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.
  */
-export declare class Maintenance {
-    private readonly d;
-    private queue;
-    private queueConn;
-    private worker;
-    private workerConn;
-    private closed;
-    private readonly handlers;
-    private readonly schedules;
-    constructor(d: MaintenanceDeps);
-    /** 登记某个任务名的处理函数（构造期调用；Worker 启动前后都可）。 */
-    handle(name: string, fn: MaintenanceHandler): void;
-    /** 登记一个周期任务（构造期调用；`ensureSchedules` 时一并 upsert）。 */
-    schedule(s: MaintenanceSchedule): void;
-    /** 投递一个维护任务。 */
-    add(name: string, data: unknown, opts: JobsOptions): Promise<void>;
-    /** 登记周期任务的 job scheduler（幂等；worker 角色启动时调用）。 */
-    ensureSchedules(): Promise<void>;
-    /** 启动维护队列的 Worker（只在含 `worker` 角色的进程）。 */
-    startWorker(): void;
-    close(): Promise<void>;
-    private getQueue;
-    private process;
+export declare class MaintenanceModule {
 }

package/dist/runtime/maintenance.js

@@ -1,148 +1,177 @@
-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 { BG_WAKE_JOB } from "../background/wake-rules.js";
+import { OWNED_PLUGIN_CLEANUP_JOB } from "../catalog/job-ids.js";
+import { OwnedPluginCleanup, OwnedPluginCleanupModule } from "../catalog/owned-plugin-cleanup.js";
+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, runSandboxResetFiles, SANDBOX_DESTROY_FOR_JOB, SANDBOX_RESET_FILES_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 { RunQueue } from "./run-queue.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` and
+ * `sandbox-reset-files` → {@link SandboxService}, `drift-connector` → {@link ToolDrift}, `directory-sync` →
+ * {@link DirectorySync}, `bg-wake` → {@link RunQueue.ensureRun}, `owned-plugin-cleanup` →
+ * {@link OwnedPluginCleanup}). 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;
+    runs;
+    ownedCleanup;
+    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, runs, ownedCleanup, scheduled, log, queue) {
+        super();
+        this.waits = waits;
+        this.sandbox = sandbox;
+        this.drift = drift;
+        this.directory = directory;
+        this.runs = runs;
+        this.ownedCleanup = ownedCleanup;
+        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 SANDBOX_RESET_FILES_JOB:
+                await runSandboxResetFiles(this.sandbox, 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;
+            // the end of a conversation's wake window (background Bash spec §3)
+            case BG_WAKE_JOB: {
+                // fired before the window ended (clock skew): it reschedules under its next retry id
+                const { conversationId, retry } = job.data;
+                await this.runs.ensureRun(conversationId, { wakeRetry: (retry ?? 0) + 1 });
+                return;
+            }
+            // a removed org-owned plugin's extension (plugin scope phase 3, P3-20)
+            case OWNED_PLUGIN_CLEANUP_JOB:
+                await this.ownedCleanup.run(job.data.itemId);
+                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(RunQueue)),
+    __param(5, Inject(OwnedPluginCleanup)),
+    __param(6, Inject(ScheduledRuns)),
+    __param(7, Inject(KERNEL_LOGGER)),
+    __param(8, 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,
+            // the removed org plugins' cleanup and its daily sweep (worker-only through this module)
+            OwnedPluginCleanupModule,
+            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,39 +1,59 @@
-import { type ContentBlock, type Logger, type ModelProvider, type ModelRequest, type ModelStreamEvent, type ModelUsage, type StopReason } from "@capybara-hq/plugin-sdk";
+import { type ContentBlock, type Logger, 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 { AppendEvent, EventLog } from "../conversations/event-log.js";
+import { type ConversationEvent } from "../conversations/events.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 BoundProvider, 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.";
-/** 所用模型不支持工具（`capabilities.tools` 为 false）时的提醒（模型可见，英文）。 */
-export declare const TOOLS_UNSUPPORTED_REMINDER = "Tools are unavailable for this model. Answer without calling tools.";
+/**
+ * The tail reminder of a sub-agent's final call once its tree used its token budget (model-visible,
+ * English; sub-agents spec §8.3): the child hands back what it found instead of ending with nothing.
+ */
+export declare const BUDGET_WRAP_UP_REMINDER: string;
+/** Why a run makes its final, tool-less call: its step limit, or its tree's token budget. */
+export type WrapUpReason = "max_steps" | "budget";
+export { TOOLS_UNSUPPORTED_REMINDER } from "./context/reminders.js";
 /** 不可用工具提醒的前缀（模型可见，英文）。 */
 export declare const TOOLS_UNAVAILABLE_PREFIX = "The following tools are unavailable in this run: ";
 /** 本 run 中此前有工具不可用、现在全部恢复时的提醒（模型可见，英文）。 */
 export declare const TOOLS_AVAILABLE_AGAIN = "All previously unavailable tools are available again.";
 /** 不可用工具提醒：`The following tools are unavailable in this run: <ref> (<reason>), ...`。 */
 export declare function toolsUnavailableReminder(unavailable: readonly UnavailableTool[]): string;
-/** 流式增量的出口（推给前端等订阅方）；`step_reset` 表示丢弃本步已推出的增量、重新开始。 */
+/**
+ * `run_failed` message of a model request denied by a policy hook (user-facing, never model-visible);
+ * also the message of the `model.hook_denied` error a denied `ctx.models.embed` call rejects with.
+ */
+export declare const modelDeniedText: (plugin: string, reason: string) => string;
+/**
+ * 流式增量的出口（推给前端等订阅方）；`step_reset` 表示丢弃本步已推出的增量、重新开始。
+ * `stream_end` (the step's model stream completed) and `step_end` (the step's `assistant_message`
+ * is logged) carry no delta: the run worker's sink writes and then clears the step's live draft on
+ * them (spec 2026-11-07 §3.2) and publishes neither.
+ */
 export type StreamSink = (delta: {
-    kind: "text" | "thinking" | "step_reset";
+    kind: "text" | "thinking" | "step_reset" | "stream_end" | "step_end";
     runId: string;
     step: number;
     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）。未提供时媒体引用一律按「不再可用」处理。
@@ -91,9 +111,12 @@ export interface ModelStepInput {
     conversationKind?: ConversationKindForHooks;
     /** A sub-agent's run: where it was dispatched from (hook payloads carry it as `parent`). */
     parent?: SubagentParent;
+    /** A sub-agent's run without a live parent (a child case's eval replay, `LoopContext`). */
+    subagent?: boolean;
     /**
-     * A sub-agent's run (phase C): the parent run whose `subagent_tokens_used` counts every usage
-     * event this step writes (step, wrap-up and compaction calls; spec §8.3).
+     * A sub-agent's run (phase C): the parent run whose budget run's `subagent_tokens_used` counts
+     * every usage event this step writes (step, wrap-up and compaction calls; spec §8.3, agent map
+     * spec §6).
      */
     parentRunId?: string;
     /**
@@ -146,8 +169,31 @@ export declare function runModelStep(deps: ModelStepDeps, input: ModelStepInput)
  * 单轮收尾：到达步数上限时调用一次。写入收尾 `reminder`（位于请求末尾）；照常带工具（历史里有工具调用时
  * 部分供应商要求请求声明工具，也保持缓存前缀稳定），但 `toolChoice: "none"`——模型只能回复文本。
  * 其余与 `runModelStep` 相同（幂等、降级、中止）。
+ *
+ * `reason: "budget"`: a sub-agent whose tree used its token budget makes this one call to hand back
+ * what it found (sub-agents spec §8.3); it is not stopped by the budget again (one call over).
+ */
+export declare function runFinalWrapUp(deps: ModelStepDeps, input: ModelStepInput, reason?: WrapUpReason): Promise<ModelStepResult>;
+/**
+ * Appends a model call's events (its reply or compaction outcome with its `usage`; also the usage
+ * of a `WebFetch` extraction call, `tools/builtins/web/extract.ts`). For a
+ * sub-agent's run (`input.parentRunId`) in one transaction that also adds the tokens of the usage
+ * events it newly wrote to the budget run's `subagent_tokens_used` (sub-agents spec §8.3): a usage
+ * event already in the log (an idempotent hit after a crash) adds nothing, so each call counts
+ * exactly once.
  */
-export declare function runFinalWrapUp(deps: ModelStepDeps, input: ModelStepInput): Promise<ModelStepResult>;
+export declare function appendCounted(deps: {
+    eventLog: Pick<EventLog, "append" | "notify">;
+    stepLog: Pick<StepLog, "appendCounted">;
+}, input: {
+    conversationId: string;
+    parentRunId?: string | undefined;
+    /** The run's budget window (agent map spec §6), when known; else the parent run's. */
+    budgetRunId?: string | undefined;
+    parent?: {
+        budgetRunId?: string | undefined;
+    } | undefined;
+}, events: AppendEvent[]): Promise<ConversationEvent[]>;
 /** {@link assembleModelRequest} 的输入。 */
 export interface AssembleModelRequestInput extends Omit<BuildModelRequestInput, "tools"> {
     /** 本步解析出的工具；模型不支持工具（`capabilities.tools` 为 false）时不带。 */
@@ -171,6 +217,6 @@ export declare function assembleModelRequest(input: AssembleModelRequestInput):
  * 外部 `signal` 触发 → `StepAborted`。每次 `next()` 都与停止信号竞速，供应商不响应 signal 也不会卡住。
  * 运行时与评测单步回放（`evals/step-replay.ts`）、评委共用。
  */
-export declare function consumeModelStream(provider: ModelProvider, request: ModelRequest, idleMs: number, signal: AbortSignal, onDelta: (ev: Exclude<ModelStreamEvent, {
+export declare function consumeModelStream(provider: BoundProvider, request: ModelRequest, idleMs: number, signal: AbortSignal, onDelta: (ev: Exclude<ModelStreamEvent, {
     type: "message_complete";
 }>) => void): Promise<StreamOutcome>;