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

package/dist/platform/registry.js

@@ -0,0 +1,111 @@
+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 { Injectable } from "@nestjs/common";
+import { tokenize } from "../tools/builtins/tool-search.js";
+import { OPERATION_ID, operationDomain, PLATFORM_DOMAINS, } from "./operation.js";
+/** A word of an operation id weighs more than a word of its description (like ToolSearch). */
+const ID_WEIGHT = 2;
+/** The shortest query term that also matches as a word's prefix (`skill` → `skills`). */
+const MIN_PREFIX = 3;
+const DOMAIN_IDS = new Set(PLATFORM_DOMAINS.map((d) => d.id));
+const byId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+/** A query term matches a word when equal, or as its prefix when long enough. */
+const matches = (words, term) => {
+    if (words.has(term))
+        return true;
+    if (term.length < MIN_PREFIX)
+        return false;
+    for (const w of words)
+        if (w.startsWith(term))
+            return true;
+    return false;
+};
+/**
+ * The `Platform` tool's operations (spec §7). Domain providers add theirs with {@link register}
+ * from `onModuleInit` (ruling P2: this module imports no domain module); a bad batch throws and
+ * registers nothing, so a mistake fails the kernel's start.
+ */
+let PlatformOperations = class PlatformOperations {
+    ops = new Map();
+    /**
+     * Adds `ops`. Throws on an id not shaped `<domain>.<verb>`, a domain outside
+     * {@link PLATFORM_DOMAINS}, a duplicate id (in the batch or already registered), or a write
+     * (`confirm` other than `read`) without `summary`.
+     */
+    register(ops) {
+        const seen = new Set();
+        for (const op of ops) {
+            if (!OPERATION_ID.test(op.id)) {
+                throw new Error(`Platform operation id "${op.id}" is not shaped <domain>.<verb>`);
+            }
+            if (!DOMAIN_IDS.has(operationDomain(op.id))) {
+                throw new Error(`Platform operation "${op.id}" names an unknown domain`);
+            }
+            if (seen.has(op.id) || this.ops.has(op.id)) {
+                throw new Error(`duplicate Platform operation "${op.id}"`);
+            }
+            if (op.confirm !== "read" && op.summary === undefined) {
+                throw new Error(`Platform operation "${op.id}" is a write without a summary`);
+            }
+            seen.add(op.id);
+        }
+        for (const op of ops)
+            this.ops.set(op.id, op);
+    }
+    domains() {
+        return PLATFORM_DOMAINS;
+    }
+    /** The domain's operations, sorted by id. */
+    inDomain(domain) {
+        return this.all().filter((op) => operationDomain(op.id) === domain);
+    }
+    get(id) {
+        return this.ops.get(id) ?? null;
+    }
+    /** Every operation, sorted by id. */
+    all() {
+        return [...this.ops.values()].sort(byId);
+    }
+    /**
+     * Keyword search (deterministic, like ToolSearch's): per distinct query term,
+     * `idf × (ID_WEIGHT if in the id + 1 if in the description)`; a term also matches a word it is a
+     * prefix of. Zero scores are dropped; ties go by id.
+     */
+    search(query, limit) {
+        const terms = [...new Set(tokenize(query))];
+        if (terms.length === 0)
+            return [];
+        const docs = this.all().map((op) => ({
+            op,
+            id: new Set(tokenize(op.id)),
+            desc: new Set(tokenize(op.description)),
+        }));
+        const n = docs.length;
+        const idf = new Map();
+        for (const term of terms) {
+            const df = docs.filter((d) => matches(d.id, term) || matches(d.desc, term)).length;
+            idf.set(term, df === 0 ? 0 : Math.log(1 + n / df));
+        }
+        return docs
+            .map((d) => {
+            let score = 0;
+            for (const term of terms) {
+                const w = (matches(d.id, term) ? ID_WEIGHT : 0) + (matches(d.desc, term) ? 1 : 0);
+                score += w * (idf.get(term) ?? 0);
+            }
+            return { op: d.op, score };
+        })
+            .filter((x) => x.score > 0)
+            .sort((a, b) => (b.score !== a.score ? b.score - a.score : byId(a.op, b.op)))
+            .slice(0, limit)
+            .map((x) => x.op);
+    }
+};
+PlatformOperations = __decorate([
+    Injectable()
+], PlatformOperations);
+export { PlatformOperations };

package/dist/platform/route-schemas.d.ts

@@ -0,0 +1,18 @@
+import type { z } from "zod";
+/**
+ * The zod schemas one HTTP route validates (spec §14.5 item 3), as its controller uses them:
+ * `route` is the `check:platform-ops` key (`POST /api/v1/orgs/:orgId/skills`), `params` its path
+ * params but `:orgId` (the conversation's org, never an operation field).
+ */
+export interface RouteSchemas {
+    route: string;
+    body?: z.ZodType;
+    query?: z.ZodType;
+    params?: z.ZodType;
+}
+/**
+ * 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 declare const ROUTE_SCHEMAS: readonly RouteSchemas[];

package/dist/platform/route-schemas.js

@@ -0,0 +1,66 @@
+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 { THEME_ROUTES } from "../themes/themes.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,
+    // themes (themes spec §9)
+    ...THEME_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;
+}