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

package/dist/platform/route-schemas.js

@@ -0,0 +1,63 @@
+import { ADMIN_ROUTES } from "../admin/admin.schemas.js";
+import { ADMIN_EXTENSION_ROUTES } from "../admin/extensions.schemas.js";
+import { AGENT_ROUTES } from "../agents/agents.schemas.js";
+import { AGENT_TEMPLATE_ROUTES } from "../agents/templates.schemas.js";
+import { BACKGROUND_ROUTES } from "../background/background.schemas.js";
+import { ADMIN_CATALOG_ROUTES } from "../catalog/admin-catalog.schemas.js";
+import { COMPONENT_SCOPE_ROUTES } from "../catalog/component-scope.schemas.js";
+import { MARKETPLACE_ROUTES } from "../catalog/marketplaces.schemas.js";
+import { ORG_CATALOG_ROUTES } from "../catalog/org-catalog.schemas.js";
+import { ORG_EXTENSION_ROUTES } from "../catalog/org-extension.schemas.js";
+import { ORG_PLUGIN_UPLOAD_ROUTES } from "../catalog/org-plugin-uploads.schemas.js";
+import { CHANNEL_ROUTES } from "../channels/channels.schemas.js";
+import { CONVERSATION_ROUTES } from "../conversations/conversations.schemas.js";
+import { ENVIRONMENT_ROUTES } from "../environments/environments.schemas.js";
+import { EVAL_ROUTES } from "../evals/evals.schemas.js";
+import { EXTENSION_POINT_ROUTES } from "../extensions/point-defaults.schemas.js";
+import { FILE_PREVIEWER_ROUTES } from "../files/previewers.schemas.js";
+import { ME_ROUTES } from "../identity/me.schemas.js";
+import { INBOX_ROUTES } from "../inbox/inbox.schemas.js";
+import { ORG_MODEL_ROUTES } from "../models/org-models.schemas.js";
+import { ORG_ROUTES, ORG_SETTINGS_ROUTES } from "../orgs/orgs.schemas.js";
+import { SKILL_ROUTES } from "../skills/skills.schemas.js";
+import { APPROVAL_ROUTES } from "../tools/approvals.schemas.js";
+import { CONNECTOR_ROUTES } from "../tools/connectors.schemas.js";
+/**
+ * Every route a Platform operation mirrors, from the exported `<domain>.schemas.ts` next to each
+ * controller. An operation builds its input from these (`pick` / `omit` / `extend`); the parity
+ * test in `tools/checks` compares the two. A route mirrored by a new operation adds its entry here.
+ */
+export const ROUTE_SCHEMAS = [
+    ...SKILL_ROUTES,
+    ...AGENT_ROUTES,
+    ...AGENT_TEMPLATE_ROUTES,
+    ...ORG_CATALOG_ROUTES,
+    ...ADMIN_CATALOG_ROUTES,
+    ...MARKETPLACE_ROUTES,
+    ...CONNECTOR_ROUTES,
+    ...COMPONENT_SCOPE_ROUTES,
+    ...ORG_EXTENSION_ROUTES,
+    ...CONVERSATION_ROUTES,
+    // Task 7: admin accounts, orgs, deployment settings, platform models
+    ...ADMIN_ROUTES,
+    ...ORG_ROUTES,
+    // Task 8: admin catalog, extensions, marketplaces, models, org uploads
+    ...ADMIN_EXTENSION_ROUTES,
+    ...ORG_PLUGIN_UPLOAD_ROUTES,
+    ...EXTENSION_POINT_ROUTES,
+    ...ORG_MODEL_ROUTES,
+    // Task 9: inbox and pending reads
+    ...INBOX_ROUTES,
+    ...APPROVAL_ROUTES,
+    // Task 10: channels, org settings
+    ...CHANNEL_ROUTES,
+    ...ORG_SETTINGS_ROUTES,
+    // Task 11: evals, background tasks, file previewers
+    ...EVAL_ROUTES,
+    ...BACKGROUND_ROUTES,
+    ...FILE_PREVIEWER_ROUTES,
+    // Task 11b: environments
+    ...ENVIRONMENT_ROUTES,
+    // personal preferences (run context spec §3.4)
+    ...ME_ROUTES,
+];

package/dist/roles/gateway-role.d.ts

@@ -0,0 +1,54 @@
+import type { ExtensionContext } from "@capybara-hq/plugin-sdk";
+import { ChannelSupervisor } from "../channels/supervisor.js";
+import { ChannelWebhooks } from "../channels/webhook.js";
+import { DeviceGateway } from "../devices/device-gateway.js";
+import { ExtensionHost } from "../extensions/host.js";
+import type { GatewayRoutes } from "../http/gateway-routes.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+/**
+ * The gateway role's parts, driven by `KernelLifecycle` at fixed points of its start order and
+ * stop phases: the channel long-connection supervisor (leader election and share) and the webhook
+ * inbound (its raw Fastify route, {@link routes}, and its runtime cache's invalidation), and the
+ * device connections ({@link DeviceGateway}, `GET /device/connect`). Provided
+ * only by `GatewayModule`, so a process without the gateway role has none of them.
+ */
+export declare class GatewayRole {
+    private readonly config;
+    private readonly host;
+    private readonly bus;
+    private readonly supervisor;
+    private readonly webhooks;
+    private readonly devices;
+    /** The supervisor's subscription to extension instance changes. */
+    private unwatchPlugins;
+    private unwatchWebhooks;
+    /** The webhook cache's `channel.changed` subscription (a field: a test replaces it). */
+    private unsubscribeWebhooks;
+    /** The supervisor was started: the runs phase stops it. */
+    private supervisorStarted;
+    constructor(config: KernelConfigService, host: ExtensionHost, bus: Pick<ExtensionContext["bus"], "subscribe">, supervisor: ChannelSupervisor, webhooks: ChannelWebhooks, devices: DeviceGateway);
+    /**
+     * The gateway role's HTTP routes (the channel webhook, the device connection), registered when
+     * the app is built.
+     */
+    routes(): GatewayRoutes;
+    /**
+     * Starts the supervisor and the webhook cache invalidation (after the extension load).
+     * `checkpoint` throws when a stop began meanwhile.
+     */
+    start(checkpoint: () => void): Promise<void>;
+    /** Stops watching extension instance changes (the stop's first step). */
+    unwatch(): void;
+    /** Ends the webhook cache's `channel.changed` subscription. */
+    unsubscribe(): Promise<void>;
+    /**
+     * Closes the device connections (1001) and hands their leases back, before the HTTP server
+     * closes (the machines reconnect to another gateway replica).
+     */
+    stopDevices(): Promise<void>;
+    /**
+     * The runs phase: the supervisor aborts its connects and hands back its leases (undefined: never
+     * started).
+     */
+    stopSupervisor(): Promise<void> | undefined;
+}

package/dist/roles/gateway-role.js

@@ -0,0 +1,118 @@
+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 { CHANNEL_CHANGED_TOPIC } from "../channels/connections.service.js";
+import { ChannelSupervisor } from "../channels/supervisor.js";
+import { ChannelWebhooks } from "../channels/webhook.js";
+import { DeviceGateway } from "../devices/device-gateway.js";
+import { ExtensionHost } from "../extensions/host.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KERNEL_BUS } from "../infra/tokens.js";
+/**
+ * The gateway role's parts, driven by `KernelLifecycle` at fixed points of its start order and
+ * stop phases: the channel long-connection supervisor (leader election and share) and the webhook
+ * inbound (its raw Fastify route, {@link routes}, and its runtime cache's invalidation), and the
+ * device connections ({@link DeviceGateway}, `GET /device/connect`). Provided
+ * only by `GatewayModule`, so a process without the gateway role has none of them.
+ */
+let GatewayRole = class GatewayRole {
+    config;
+    host;
+    bus;
+    supervisor;
+    webhooks;
+    devices;
+    /** The supervisor's subscription to extension instance changes. */
+    unwatchPlugins;
+    unwatchWebhooks;
+    /** The webhook cache's `channel.changed` subscription (a field: a test replaces it). */
+    unsubscribeWebhooks;
+    /** The supervisor was started: the runs phase stops it. */
+    supervisorStarted = false;
+    constructor(config, host, bus, supervisor, webhooks, devices) {
+        this.config = config;
+        this.host = host;
+        this.bus = bus;
+        this.supervisor = supervisor;
+        this.webhooks = webhooks;
+        this.devices = devices;
+    }
+    /**
+     * The gateway role's HTTP routes (the channel webhook, the device connection), registered when
+     * the app is built.
+     */
+    routes() {
+        const config = this.config.get();
+        return {
+            webhooks: this.webhooks,
+            webhookMaxBodyBytes: config.channels.webhookMaxBodyBytes,
+            devices: {
+                gateway: this.devices,
+                maxFrameBytes: config.environments.device.maxFrameBytes,
+            },
+        };
+    }
+    /**
+     * Starts the supervisor and the webhook cache invalidation (after the extension load).
+     * `checkpoint` throws when a stop began meanwhile.
+     */
+    async start(checkpoint) {
+        const supervisor = this.supervisor;
+        this.supervisorStarted = true;
+        await supervisor.start();
+        // An extension instance revoked or replaced: hand back the long connections it holds and
+        // elect again on the new instance (C17)
+        this.unwatchPlugins = this.host.onChange((plugin) => supervisor.pluginChanged(plugin));
+        checkpoint();
+        // The webhook runtime cache is read-through only: drop entries on every connection change and
+        // whenever a plugin instance changes
+        const webhooks = this.webhooks;
+        this.unsubscribeWebhooks = await this.bus.subscribe(CHANNEL_CHANGED_TOPIC, (payload) => {
+            const id = payload?.connectionId;
+            if (typeof id === "string")
+                webhooks.invalidate(id);
+        });
+        this.unwatchWebhooks = this.host.onChange(() => webhooks.invalidateAll());
+        checkpoint();
+    }
+    /** Stops watching extension instance changes (the stop's first step). */
+    unwatch() {
+        this.unwatchPlugins?.();
+        this.unwatchWebhooks?.();
+    }
+    /** Ends the webhook cache's `channel.changed` subscription. */
+    unsubscribe() {
+        return this.unsubscribeWebhooks?.() ?? Promise.resolve();
+    }
+    /**
+     * Closes the device connections (1001) and hands their leases back, before the HTTP server
+     * closes (the machines reconnect to another gateway replica).
+     */
+    stopDevices() {
+        return this.devices.stop();
+    }
+    /**
+     * The runs phase: the supervisor aborts its connects and hands back its leases (undefined: never
+     * started).
+     */
+    stopSupervisor() {
+        return this.supervisorStarted ? this.supervisor.stop() : undefined;
+    }
+};
+GatewayRole = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelConfigService)),
+    __param(1, Inject(ExtensionHost)),
+    __param(2, Inject(KERNEL_BUS)),
+    __param(3, Inject(ChannelSupervisor)),
+    __param(4, Inject(ChannelWebhooks)),
+    __param(5, Inject(DeviceGateway))
+], GatewayRole);
+export { GatewayRole };

package/dist/roles/gateway.module.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The gateway role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
+ * `gateway`: the channel long-connection supervisor, the webhook inbound (served as a raw Fastify
+ * route, `http/gateway-routes.ts`), the device connections ({@link DeviceGateway}, `GET
+ * /device/connect`) and {@link GatewayRole}, which `KernelLifecycle` drives. It runs
+ * no cron and no queue consumer (those are the worker role's).
+ */
+export declare class GatewayModule {
+}

package/dist/roles/gateway.module.js

@@ -0,0 +1,31 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { ChannelsModule } from "../channels/channels.module.js";
+import { ChannelSupervisor } from "../channels/supervisor.js";
+import { ChannelWebhooks } from "../channels/webhook.js";
+import { DeviceGateway } from "../devices/device-gateway.js";
+import { DevicesModule } from "../devices/devices.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { GatewayRole } from "./gateway-role.js";
+/**
+ * The gateway role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
+ * `gateway`: the channel long-connection supervisor, the webhook inbound (served as a raw Fastify
+ * route, `http/gateway-routes.ts`), the device connections ({@link DeviceGateway}, `GET
+ * /device/connect`) and {@link GatewayRole}, which `KernelLifecycle` drives. It runs
+ * no cron and no queue consumer (those are the worker role's).
+ */
+let GatewayModule = class GatewayModule {
+};
+GatewayModule = __decorate([
+    Module({
+        imports: [ChannelsModule, ExtensionsModule, DevicesModule],
+        providers: [ChannelSupervisor, ChannelWebhooks, DeviceGateway, GatewayRole],
+        exports: [GatewayRole],
+    })
+], GatewayModule);
+export { GatewayModule };

package/dist/roles/worker-role.d.ts

@@ -0,0 +1,65 @@
+import { PluginScopeSyncProcessor } from "../catalog/scope-sync.js";
+import { ChannelsProcessor } from "../channels/channels.module.js";
+import { ChannelOutbound } from "../channels/outbound.js";
+import { TitleQueue } from "../conversations/titles.js";
+import { EvalsProcessor } from "../evals/evals.module.js";
+import { EvalWorker } from "../evals/worker.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockedIntervalScheduler } from "../infra/schedule/locked-interval.js";
+import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
+import type { KernelLogger } from "../log.js";
+import { MaintenanceProcessor } from "../runtime/maintenance.js";
+import { RunsProcessor, SubagentRunsProcessor, TitleProcessor, UsageReportProcessor } from "../runtime/run-processors.js";
+import { RunWorker } from "../runtime/run-worker.js";
+import { UsageReporter } from "../runtime/usage-report.js";
+/**
+ * The worker role's parts, driven by `KernelLifecycle` at fixed points of its start order and stop
+ * phases (so they stay ordered after the extension load and before the extension host closes): the
+ * queue consumers (runs, sub-agent runs, evals, maintenance, the plugin scope sync, channel
+ * deliveries, `usage.report`, titles) and the schedulers of the `@LockedCron` / `@LockedInterval` jobs. Provided only by
+ * `WorkerModule`, so a process without the worker role has none of them.
+ */
+export declare class WorkerRole {
+    private readonly log;
+    private readonly intervals;
+    private readonly scheduledRuns;
+    private readonly runWorker;
+    private readonly evalWorker;
+    private readonly usageReport;
+    private readonly titles;
+    private readonly channelOutbound;
+    private readonly runsProcessor;
+    private readonly subagentRunsProcessor;
+    private readonly usageProcessor;
+    private readonly titleProcessor;
+    private readonly channelsProcessor;
+    private readonly evalsProcessor;
+    private readonly maintenanceProcessor;
+    private readonly scopeProcessor;
+    /** The startup config (the roles). */
+    private readonly config;
+    /** The run worker was started: the runs phase drains it. */
+    private runsStarted;
+    /** The eval worker was started: the runs phase drains it. */
+    private evalsStarted;
+    constructor(config: KernelConfigService, log: KernelLogger, intervals: LockedIntervalScheduler, scheduledRuns: ScheduledRuns, runWorker: RunWorker, evalWorker: EvalWorker, usageReport: UsageReporter, titles: TitleQueue, channelOutbound: ChannelOutbound, runsProcessor: RunsProcessor, subagentRunsProcessor: SubagentRunsProcessor, usageProcessor: UsageReportProcessor, titleProcessor: TitleProcessor, channelsProcessor: ChannelsProcessor, evalsProcessor: EvalsProcessor, maintenanceProcessor: MaintenanceProcessor, scopeProcessor: PluginScopeSyncProcessor);
+    /**
+     * Starts the queue consumers (after the extension load), then opens the schedules' start gate:
+     * the cron and interval timers were armed at application bootstrap, but every tick before this
+     * point skipped (decision R21 of the Nest kernel spec); the `@LockedInterval({ runOnStart })`
+     * jobs run now, in the background (once across replicas starting together). `checkpoint` throws
+     * when a stop began meanwhile.
+     */
+    start(checkpoint: () => void): Promise<void>;
+    /**
+     * Closes the start gate and stops the schedulers (no new tick; the runs in progress get the stop
+     * signal) and returns the wait for those runs, at most `budgetMs`.
+     */
+    stopSchedules(budgetMs: number): Promise<void>;
+    /** The runs phase: this process's runs stop at their next step boundary (undefined: never started). */
+    drainRuns(budgetMs: number): Promise<void> | undefined;
+    /** The eval cases in progress stop (undefined: never started). */
+    drainEvals(budgetMs: number): Promise<void> | undefined;
+    /** Closes the maintenance queue's worker and the plugin scope sync's (it stops between pairs). */
+    closeMaintenance(): Promise<void>;
+}

package/dist/roles/worker-role.js

@@ -0,0 +1,151 @@
+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 { PluginScopeSyncProcessor } from "../catalog/scope-sync.js";
+import { ChannelsProcessor } from "../channels/channels.module.js";
+import { ChannelOutbound } from "../channels/outbound.js";
+import { TitleQueue } from "../conversations/titles.js";
+import { EvalsProcessor } from "../evals/evals.module.js";
+import { EvalWorker } from "../evals/worker.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockedIntervalScheduler } from "../infra/schedule/locked-interval.js";
+import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { MaintenanceProcessor } from "../runtime/maintenance.js";
+import { RunsProcessor, SubagentRunsProcessor, TitleProcessor, UsageReportProcessor, } from "../runtime/run-processors.js";
+import { RunWorker } from "../runtime/run-worker.js";
+import { UsageReporter } from "../runtime/usage-report.js";
+/**
+ * The worker role's parts, driven by `KernelLifecycle` at fixed points of its start order and stop
+ * phases (so they stay ordered after the extension load and before the extension host closes): the
+ * queue consumers (runs, sub-agent runs, evals, maintenance, the plugin scope sync, channel
+ * deliveries, `usage.report`, titles) and the schedulers of the `@LockedCron` / `@LockedInterval` jobs. Provided only by
+ * `WorkerModule`, so a process without the worker role has none of them.
+ */
+let WorkerRole = class WorkerRole {
+    log;
+    intervals;
+    scheduledRuns;
+    runWorker;
+    evalWorker;
+    usageReport;
+    titles;
+    channelOutbound;
+    runsProcessor;
+    subagentRunsProcessor;
+    usageProcessor;
+    titleProcessor;
+    channelsProcessor;
+    evalsProcessor;
+    maintenanceProcessor;
+    scopeProcessor;
+    /** The startup config (the roles). */
+    config;
+    /** The run worker was started: the runs phase drains it. */
+    runsStarted = false;
+    /** The eval worker was started: the runs phase drains it. */
+    evalsStarted = false;
+    constructor(config, log, intervals, scheduledRuns, runWorker, evalWorker, usageReport, titles, channelOutbound, runsProcessor, subagentRunsProcessor, usageProcessor, titleProcessor, channelsProcessor, evalsProcessor, maintenanceProcessor, scopeProcessor) {
+        this.log = log;
+        this.intervals = intervals;
+        this.scheduledRuns = scheduledRuns;
+        this.runWorker = runWorker;
+        this.evalWorker = evalWorker;
+        this.usageReport = usageReport;
+        this.titles = titles;
+        this.channelOutbound = channelOutbound;
+        this.runsProcessor = runsProcessor;
+        this.subagentRunsProcessor = subagentRunsProcessor;
+        this.usageProcessor = usageProcessor;
+        this.titleProcessor = titleProcessor;
+        this.channelsProcessor = channelsProcessor;
+        this.evalsProcessor = evalsProcessor;
+        this.maintenanceProcessor = maintenanceProcessor;
+        this.scopeProcessor = scopeProcessor;
+        this.config = config.get();
+    }
+    /**
+     * Starts the queue consumers (after the extension load), then opens the schedules' start gate:
+     * the cron and interval timers were armed at application bootstrap, but every tick before this
+     * point skipped (decision R21 of the Nest kernel spec); the `@LockedInterval({ runOnStart })`
+     * jobs run now, in the background (once across replicas starting together). `checkpoint` throws
+     * when a stop began meanwhile.
+     */
+    async start(checkpoint) {
+        // both run queues' @Processor workers (built with the run config, never autorun)
+        this.runWorker.start([this.runsProcessor.worker, this.subagentRunsProcessor.worker]);
+        this.runsStarted = true;
+        this.evalWorker.start(this.evalsProcessor.worker);
+        this.evalsStarted = true;
+        // The maintenance queue: remove the retired job schedulers (idempotent, harmless when several
+        // replicas do it), then start its one consumer. A failure is only logged and does not stop the
+        // start (like the workers' connection errors): any worker replica removes them on its next start.
+        try {
+            await this.maintenanceProcessor.removeRetiredSchedulers();
+        }
+        catch (err) {
+            this.log.error("cannot register maintenance job schedulers", { err });
+        }
+        checkpoint();
+        this.maintenanceProcessor.start();
+        this.scopeProcessor.start();
+        this.channelOutbound.startWorker(this.channelsProcessor.worker);
+        this.usageReport.startWorker(this.usageProcessor.worker);
+        this.titles.startWorker(this.titleProcessor.worker);
+        if (!this.config.roles.includes("gateway")) {
+            this.log.info("this process runs the worker role without gateway; channel long connections are held only by processes with the gateway role", { roles: this.config.roles });
+        }
+        // The gate opens: from here on ticks run; the runOnStart jobs run once now, in the background
+        this.scheduledRuns.open();
+        this.intervals.runStartJobs();
+        // Every plugin's scope converges once per worker start (a failed or lost sync is retried)
+        this.scopeProcessor.resync();
+    }
+    /**
+     * Closes the start gate and stops the schedulers (no new tick; the runs in progress get the stop
+     * signal) and returns the wait for those runs, at most `budgetMs`.
+     */
+    stopSchedules(budgetMs) {
+        return this.scheduledRuns.stop(budgetMs);
+    }
+    /** The runs phase: this process's runs stop at their next step boundary (undefined: never started). */
+    drainRuns(budgetMs) {
+        return this.runsStarted ? this.runWorker.close(budgetMs) : undefined;
+    }
+    /** The eval cases in progress stop (undefined: never started). */
+    drainEvals(budgetMs) {
+        return this.evalsStarted ? this.evalWorker.close(budgetMs) : undefined;
+    }
+    /** Closes the maintenance queue's worker and the plugin scope sync's (it stops between pairs). */
+    async closeMaintenance() {
+        await Promise.all([this.maintenanceProcessor.worker.close(), this.scopeProcessor.close()]);
+    }
+};
+WorkerRole = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelConfigService)),
+    __param(1, Inject(KERNEL_LOGGER)),
+    __param(2, Inject(LockedIntervalScheduler)),
+    __param(3, Inject(ScheduledRuns)),
+    __param(4, Inject(RunWorker)),
+    __param(5, Inject(EvalWorker)),
+    __param(6, Inject(UsageReporter)),
+    __param(7, Inject(TitleQueue)),
+    __param(8, Inject(ChannelOutbound)),
+    __param(9, Inject(RunsProcessor)),
+    __param(10, Inject(SubagentRunsProcessor)),
+    __param(11, Inject(UsageReportProcessor)),
+    __param(12, Inject(TitleProcessor)),
+    __param(13, Inject(ChannelsProcessor)),
+    __param(14, Inject(EvalsProcessor)),
+    __param(15, Inject(MaintenanceProcessor)),
+    __param(16, Inject(PluginScopeSyncProcessor))
+], WorkerRole);
+export { WorkerRole };

package/dist/roles/worker.module.d.ts

@@ -0,0 +1,14 @@
+import { type DynamicModule } from "@nestjs/common";
+import type { KernelConfig } from "../config/schema.js";
+/**
+ * The worker role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
+ * `worker`: the cron scheduler and the `@LockedInterval` scheduler (`KernelScheduleModule`, the one
+ * place `ScheduleModule.forRoot` is imported), every fixed-period job (`@LockedCron` /
+ * `@LockedInterval`, each once per tick across replicas), every queue consumer (`@Processor`: runs,
+ * sub-agent runs, `usage.report`, titles, evals, maintenance, channel deliveries, the plugin scope sync) and
+ * {@link WorkerRole}, which `KernelLifecycle` drives. A process without the worker role runs no cron
+ * and no BullMQ worker (the queues' producers exist on every role).
+ */
+export declare class WorkerModule {
+    static forRoot(config: KernelConfig): DynamicModule;
+}

package/dist/roles/worker.module.js

@@ -0,0 +1,106 @@
+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 WorkerModule_1;
+import { Module } from "@nestjs/common";
+import { BackgroundModule } from "../background/background.module.js";
+import { BackgroundTaskPollJob } from "../background/poll.job.js";
+import { CatalogModule } from "../catalog/catalog.module.js";
+import { CatalogJobs } from "../catalog/jobs.js";
+import { PlatformMigration } from "../catalog/platform-migration.js";
+import { PluginScopeWorkersModule } from "../catalog/scope-sync-workers.js";
+import { ChannelsModule, ChannelWorkersModule } from "../channels/channels.module.js";
+import { GatewayCheckJob } from "../channels/supervisor.js";
+import { AttachmentsModule } from "../conversations/attachments.module.js";
+import { AttachmentCleanupJob } from "../conversations/attachments.service.js";
+import { EventLogModule } from "../conversations/event-log.js";
+import { TitlesModule } from "../conversations/titles.js";
+import { LegacySandboxCleanupJob } from "../environments/legacy-cleanup.job.js";
+import { EvalWorkersModule } from "../evals/evals.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { PluginsReconcileJob } from "../extensions/lifecycle.js";
+import { InitialPasswordCleanupJob } from "../identity/initial-passwords.job.js";
+import { KernelScheduleModule } from "../infra/schedule/schedule.module.js";
+import { DirectoryScanJob } from "../orgs/directory-sync.js";
+import { OffboardSweepJob } from "../orgs/offboarding.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { OrgsModule } from "../orgs/orgs.module.js";
+import { MaintenanceModule } from "../runtime/maintenance.js";
+import { RuntimeWorkersModule } from "../runtime/run-processors.js";
+import { RuntimeModule } from "../runtime/runtime.module.js";
+import { UsageReportModule, UsageSweepJob } from "../runtime/usage-report.js";
+import { WaitSweepJob } from "../runtime/waits.js";
+import { SandboxSweepJobs } from "../sandbox/jobs.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { StoragePurgeJob } from "../storage/purge.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { ToolJobs } from "../tools/jobs.js";
+import { ToolsModule } from "../tools/tools.module.js";
+import { WorkerRole } from "./worker-role.js";
+/**
+ * The worker role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
+ * `worker`: the cron scheduler and the `@LockedInterval` scheduler (`KernelScheduleModule`, the one
+ * place `ScheduleModule.forRoot` is imported), every fixed-period job (`@LockedCron` /
+ * `@LockedInterval`, each once per tick across replicas), every queue consumer (`@Processor`: runs,
+ * sub-agent runs, `usage.report`, titles, evals, maintenance, channel deliveries, the plugin scope sync) and
+ * {@link WorkerRole}, which `KernelLifecycle` drives. A process without the worker role runs no cron
+ * and no BullMQ worker (the queues' producers exist on every role).
+ */
+let WorkerModule = WorkerModule_1 = class WorkerModule {
+    static forRoot(config) {
+        return {
+            module: WorkerModule_1,
+            imports: [
+                KernelScheduleModule,
+                // the queue consumers (their worker options come from the startup config)
+                RuntimeWorkersModule.forRoot(config),
+                EvalWorkersModule.forRoot(config),
+                ChannelWorkersModule.forRoot(config),
+                MaintenanceModule,
+                PluginScopeWorkersModule,
+                // the domains the fixed-period jobs call
+                RuntimeModule,
+                UsageReportModule,
+                TitlesModule,
+                AttachmentsModule,
+                StorageModule,
+                SandboxModule,
+                BackgroundModule,
+                EventLogModule,
+                ToolsModule,
+                CatalogModule,
+                OrgsModule,
+                OrgLockModule,
+                ExtensionsModule,
+                ChannelsModule,
+            ],
+            providers: [
+                WaitSweepJob,
+                UsageSweepJob,
+                AttachmentCleanupJob,
+                StoragePurgeJob,
+                SandboxSweepJobs,
+                LegacySandboxCleanupJob,
+                BackgroundTaskPollJob,
+                ToolJobs,
+                InitialPasswordCleanupJob,
+                CatalogJobs,
+                PlatformMigration,
+                DirectoryScanJob,
+                OffboardSweepJob,
+                PluginsReconcileJob,
+                GatewayCheckJob,
+                WorkerRole,
+            ],
+            exports: [WorkerRole],
+        };
+    }
+};
+WorkerModule = WorkerModule_1 = __decorate([
+    Module({})
+    // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
+], WorkerModule);
+export { WorkerModule };

package/dist/runtime/abort.js

@@ -1,3 +1,14 @@
+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 { KERNEL_BUS, REDIS } from "../infra/tokens.js";
 /** 中止广播的内核 bus 主题。 */
 export const RUN_ABORT_TOPIC = "run.abort";
 /** 中止标记的保留时长（秒）。 */
@@ -15,7 +26,7 @@ const parseStored = (stored) => {
  * 跨副本中止（spec 4.3「中止信号经 Redis 广播」）：`request` 先写标记键再广播；
  * `watch` 先订阅、再检查一次标记键，订阅之前发出的中止也不会丢。
  */
-export class RunAbort {
+let RunAbort = class RunAbort {
     redis;
     bus;
     constructor(redis, bus) {
@@ -68,4 +79,10 @@ export class RunAbort {
         }
         return unsubscribe;
     }
-}
+};
+RunAbort = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KERNEL_BUS))
+], RunAbort);
+export { RunAbort };