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

package/dist/orgs/settings.controller.js

@@ -7,12 +7,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Get, Inject, Patch } from "@nestjs/common";
-import { ORG_SETTINGS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
+import { Controller, Get, Inject, Patch } from "@nestjs/common";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "./org.guard.js";
-import { OrgSettingsPatchSchema, } from "./settings.service.js";
+import { OrgSettingsPatchSchema, OrgSettingsService, } from "./settings.service.js";
+class OrgSettingsPatchBody extends createZodDto(OrgSettingsPatchSchema, "OrgSettingsPatch") {
+}
 let OrgSettingsController = class OrgSettingsController {
     settings;
     constructor(settings) {
@@ -44,10 +46,10 @@ __decorate([
     OrgAction("org.update"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, Body(new ZodPipe(OrgSettingsPatchSchema)))
+    __param(2, ZBody(OrgSettingsPatchBody))
 ], OrgSettingsController.prototype, "update", null);
 OrgSettingsController = __decorate([
     Controller("api/v1/orgs/:orgId/settings"),
-    __param(0, Inject(ORG_SETTINGS))
+    __param(0, Inject(OrgSettingsService))
 ], OrgSettingsController);
 export { OrgSettingsController };

package/dist/orgs/settings.service.d.ts

@@ -1,7 +1,10 @@
 import { type SandboxLimits } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "./org-lock.js";
 /**
  * 组织设置（`capybara.orgs.settings` jsonb）。读取宽松：缺失或非法的字段按默认值，未知键保留不动
  * （更新时与存量合并），新版本加字段不需要迁移。
@@ -102,19 +105,22 @@ export interface OrgSettingsDeployment {
 /** 把存储的 jsonb 解析为设置（宽松，见 {@link OrgSettingsSchema}）。 */
 export declare function parseOrgSettings(raw: unknown): OrgSettings;
 /** 读组织设置（每次实时读 PG，多副本下改动立即生效）；组织不存在或已删除按默认值。 */
-export declare function readOrgSettings(db: KernelDb, orgId: string): Promise<OrgSettings>;
+export declare function readOrgSettings(db: KernelSchemaDb, orgId: string): Promise<OrgSettings>;
 /** 组织设置服务：读取与修改（修改需 `org.update`，锁内实时复核角色，写审计）。 */
 export declare class OrgSettingsService {
     private readonly db;
-    /** 部署配置（校验 `sandboxEgress` 不超出部署）；省略视为部署出站 `allowlist` + 空白名单。 */
-    private readonly config?;
-    constructor(db: KernelDb, 
-    /** 部署配置（校验 `sandboxEgress` 不超出部署）；省略视为部署出站 `allowlist` + 空白名单。 */
-    config?: (() => Pick<KernelConfig, "sandbox">) | undefined);
+    readonly txHost: TransactionHost;
+    private readonly orgLock;
+    /** The deployment config (`sandboxEgress` may not exceed the deployment's). */
+    private readonly config;
+    constructor(db: KernelDb, txHost: TransactionHost, orgLock: OrgLock, 
+    /** The deployment config (`sandboxEgress` may not exceed the deployment's). */
+    config: Pick<KernelConfigService, "get">);
     /** 部署默认值（设置页展示「跟随部署」时的实际取值）。 */
     deployment(): OrgSettingsDeployment;
     /** 组织实际生效的沙箱 cpu / 内存（只读；由企业管理员在部署设置里覆盖）。 */
     sandboxLimits(orgId: string): Promise<OrgSandboxLimits>;
     get(orgId: string): Promise<OrgSettings>;
     update(orgId: string, patch: OrgSettingsPatch, actorAccountId: string, actorTokenId?: string): Promise<OrgSettings>;
+    private updateIn;
 }

package/dist/orgs/settings.service.js

@@ -1,9 +1,23 @@
+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 { validateAllowHost } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
 import { readSandboxLimitOverride } from "../identity/settings.js";
-import { lockOrgAndAuthorize } from "./org-lock.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OrgLock } from "./org-lock.js";
 /**
  * 组织设置（`capybara.orgs.settings` jsonb）。读取宽松：缺失或非法的字段按默认值，未知键保留不动
  * （更新时与存量合并），新版本加字段不需要迁移。
@@ -96,30 +110,33 @@ export async function readOrgSettings(db, orgId) {
     return parseOrgSettings(row?.settings);
 }
 /** 组织设置服务：读取与修改（修改需 `org.update`，锁内实时复核角色，写审计）。 */
-export class OrgSettingsService {
+let OrgSettingsService = class OrgSettingsService {
     db;
+    txHost;
+    orgLock;
     config;
-    constructor(db, 
-    /** 部署配置（校验 `sandboxEgress` 不超出部署）；省略视为部署出站 `allowlist` + 空白名单。 */
+    constructor(db, txHost, orgLock, 
+    /** The deployment config (`sandboxEgress` may not exceed the deployment's). */
     config) {
         this.db = db;
+        this.txHost = txHost;
+        this.orgLock = orgLock;
         this.config = config;
     }
     /** 部署默认值（设置页展示「跟随部署」时的实际取值）。 */
     deployment() {
-        const lim = this.config?.().sandbox.limits;
+        const lim = this.config.get().sandbox.limits;
         return {
-            sandboxEgress: { mode: lim?.egress ?? "allowlist", allowHosts: [...(lim?.allowHosts ?? [])] },
+            sandboxEgress: { mode: lim.egress, allowHosts: [...lim.allowHosts] },
         };
     }
     /** 组织实际生效的沙箱 cpu / 内存（只读；由企业管理员在部署设置里覆盖）。 */
     async sandboxLimits(orgId) {
-        const lim = this.config?.().sandbox.limits;
-        const override = await readSandboxLimitOverride(this.db, orgId);
+        const lim = this.config.get().sandbox.limits;
+        const override = await readSandboxLimitOverride(this.db.db, orgId);
         return {
-            // 没有部署配置（测试构造）时用 schema 默认值 1 核 / 2048 MiB
-            cpu: override?.cpu ?? lim?.cpu ?? 1,
-            memoryMb: override?.memoryMb ?? lim?.memoryMb ?? 2048,
+            cpu: override?.cpu ?? lim.cpu,
+            memoryMb: override?.memoryMb ?? lim.memoryMb,
             source: override === undefined ? "deployment" : "override",
         };
     }
@@ -139,40 +156,52 @@ export class OrgSettingsService {
             this.deployment().sandboxEgress.mode === "none") {
             throw new ApiError("org.sandbox_egress_not_allowed", "This deployment disables sandbox network access (sandbox.limits.egress is none); an organization can only set sandboxEgress to none");
         }
-        return this.db.transaction().execute(async (trx) => {
-            await lockOrgAndAuthorize(trx, orgId, actorAccountId, "org.update");
-            const row = await trx
-                .selectFrom("orgs")
-                .select("settings")
-                .where("id", "=", orgId)
-                .executeTakeFirstOrThrow();
-            const stored = asObject(row.settings);
-            const before = parseOrgSettings(stored);
-            const changes = Object.fromEntries(Object.entries(patch)
-                .filter(([, v]) => v !== undefined)
-                // null 清除 sandboxEgress：恢复跟随部署默认
-                .map(([k, v]) => [k, v === null ? undefined : v]));
-            const after = { ...before, ...changes };
-            if (after.sandboxEgress === undefined)
-                delete after.sandboxEgress;
-            if (sameSettings(before, after))
-                return before;
-            // 与存量合并：保留本版本不认识的键（清除的 sandboxEgress 不留在存量里）
-            const { sandboxEgress: _old, ...rest } = stored;
-            await trx
-                .updateTable("orgs")
-                .set({ settings: JSON.stringify({ ...rest, ...after }) })
-                .where("id", "=", orgId)
-                .execute();
-            await audit(trx, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "org.settings_updated",
-                target: orgId,
-                detail: { before, after },
-            });
-            return after;
+        return this.updateIn(orgId, patch, actorAccountId, actorTokenId);
+    }
+    async updateIn(orgId, patch, actorAccountId, actorTokenId) {
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "org.update");
+        const row = await this.db
+            .selectFrom("orgs")
+            .select("settings")
+            .where("id", "=", orgId)
+            .executeTakeFirstOrThrow();
+        const stored = asObject(row.settings);
+        const before = parseOrgSettings(stored);
+        const changes = Object.fromEntries(Object.entries(patch)
+            .filter(([, v]) => v !== undefined)
+            // null 清除 sandboxEgress：恢复跟随部署默认
+            .map(([k, v]) => [k, v === null ? undefined : v]));
+        const after = { ...before, ...changes };
+        if (after.sandboxEgress === undefined)
+            delete after.sandboxEgress;
+        if (sameSettings(before, after))
+            return before;
+        // 与存量合并：保留本版本不认识的键（清除的 sandboxEgress 不留在存量里）
+        const { sandboxEgress: _old, ...rest } = stored;
+        await this.db
+            .updateTable("orgs")
+            .set({ settings: JSON.stringify({ ...rest, ...after }) })
+            .where("id", "=", orgId)
+            .execute();
+        await audit(this.db.db, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "org.settings_updated",
+            target: orgId,
+            detail: { before, after },
         });
+        return after;
     }
-}
+};
+__decorate([
+    Transactional()
+], OrgSettingsService.prototype, "updateIn", null);
+OrgSettingsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(OrgLock)),
+    __param(3, Inject(KernelConfigService))
+], OrgSettingsService);
+export { OrgSettingsService };

package/dist/overrides.d.ts

@@ -0,0 +1,56 @@
+import type { NestInterceptor } from "@nestjs/common";
+import { APP_INTERCEPTOR } from "@nestjs/core";
+import { CHANNEL_WEBHOOK_TIMINGS, type ChannelWebhookTimings } from "./channels/webhook.js";
+import type { EvalReplayHooks } from "./evals/run-replay.js";
+import { EVAL_REPLAY_HOOKS } from "./evals/worker.js";
+import { BOOTSTRAP_LOCK_TTL } from "./extensions/bootstrap.js";
+import { FILE_PREVIEW_TIMEOUT } from "./files/previewers.js";
+import { LIST_MODELS_TIMEOUT } from "./runtime/providers.js";
+import { AGENT_LOOP_FACTORY, type AgentLoopFactory } from "./runtime/run-steps.js";
+import { RUN_HOOKS, type RunHooks } from "./runtime/run-worker.js";
+import { USAGE_REPORT_RETRY, type UsageReportRetry } from "./runtime/usage-report.js";
+import { SANDBOX_LEASE_TIMINGS, type SandboxLeaseTimings } from "./sandbox/leases.js";
+import { TOOL_PIPELINE_HOOKS, type ToolPipelineHooks } from "./tools/pipeline.js";
+import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
+/**
+ * The value each seam token takes. Every token is an optional provider the kernel itself never
+ * provides (its consumer falls back to the production default):
+ *
+ * - `AGENT_LOOP_FACTORY`: the agent loop runs execute (default the LangGraph loop);
+ * - `RUN_HOOKS`: the run worker's hooks;
+ * - `EVAL_REPLAY_HOOKS`: the hooks of the eval full-run replay and the judge;
+ * - `TOOL_PIPELINE_HOOKS`: the tool pipeline's hooks and policy decision;
+ * - `BOOTSTRAP_LOCK_TTL`, `FILE_PREVIEW_TIMEOUT`, `LIST_MODELS_TIMEOUT`, `USAGE_REPORT_RETRY`,
+ *   `SANDBOX_LEASE_TIMINGS`, `CHANNEL_WEBHOOK_TIMINGS`: shorter timings;
+ * - `EMBED_TOKEN_CLOCK`: the clock embed tokens are issued and checked with;
+ * - `APP_INTERCEPTOR`: one more global interceptor (a probe of the matched routes).
+ */
+interface KernelSeams {
+    [AGENT_LOOP_FACTORY]: AgentLoopFactory;
+    [RUN_HOOKS]: RunHooks;
+    [EVAL_REPLAY_HOOKS]: EvalReplayHooks;
+    [TOOL_PIPELINE_HOOKS]: ToolPipelineHooks;
+    [BOOTSTRAP_LOCK_TTL]: number;
+    [FILE_PREVIEW_TIMEOUT]: number;
+    [LIST_MODELS_TIMEOUT]: number;
+    [USAGE_REPORT_RETRY]: UsageReportRetry;
+    [SANDBOX_LEASE_TIMINGS]: Partial<SandboxLeaseTimings>;
+    [CHANNEL_WEBHOOK_TIMINGS]: Partial<ChannelWebhookTimings>;
+    [EMBED_TOKEN_CLOCK]: () => number;
+    [APP_INTERCEPTOR]: NestInterceptor;
+}
+/**
+ * A seam of the kernel's own tests (`KernelAppOptions.overrides`): a value for one of the named
+ * seam tokens of {@link KernelSeams}. Domain classes cannot be replaced this way. The tokens are
+ * not exported from the package, and `@capybara-hq/testing`'s `startTestKernel` takes no
+ * overrides (decision R22 of the Nest kernel spec).
+ */
+export type KernelOverride = {
+    [K in keyof KernelSeams]: {
+        provide: K;
+        useValue: KernelSeams[K];
+    };
+}[keyof KernelSeams];
+/** The tokens {@link KernelOverride} may name; any other token is refused when the application is built. */
+export declare const KERNEL_OVERRIDE_TOKENS: ReadonlySet<unknown>;
+export {};

package/dist/overrides.js

@@ -0,0 +1,30 @@
+import { APP_INTERCEPTOR } from "@nestjs/core";
+import { CHANNEL_WEBHOOK_TIMINGS } from "./channels/webhook.js";
+import { EVAL_REPLAY_HOOKS } from "./evals/worker.js";
+import { BOOTSTRAP_LOCK_TTL } from "./extensions/bootstrap.js";
+import { FILE_PREVIEW_TIMEOUT } from "./files/previewers.js";
+import { LIST_MODELS_TIMEOUT } from "./runtime/providers.js";
+import { AGENT_LOOP_FACTORY } from "./runtime/run-steps.js";
+import { RUN_HOOKS } from "./runtime/run-worker.js";
+import { USAGE_REPORT_RETRY } from "./runtime/usage-report.js";
+import { SANDBOX_LEASE_TIMINGS } from "./sandbox/leases.js";
+import { TOOL_PIPELINE_HOOKS } from "./tools/pipeline.js";
+import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
+const SEAM_TOKENS = [
+    AGENT_LOOP_FACTORY,
+    RUN_HOOKS,
+    EVAL_REPLAY_HOOKS,
+    TOOL_PIPELINE_HOOKS,
+    BOOTSTRAP_LOCK_TTL,
+    FILE_PREVIEW_TIMEOUT,
+    LIST_MODELS_TIMEOUT,
+    USAGE_REPORT_RETRY,
+    SANDBOX_LEASE_TIMINGS,
+    CHANNEL_WEBHOOK_TIMINGS,
+    EMBED_TOKEN_CLOCK,
+    APP_INTERCEPTOR,
+];
+const allSeamsListed = true;
+void allSeamsListed;
+/** The tokens {@link KernelOverride} may name; any other token is refused when the application is built. */
+export const KERNEL_OVERRIDE_TOKENS = new Set(SEAM_TOKENS);

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

@@ -0,0 +1,43 @@
+import type { ExtensionContext } from "@capybara-hq/plugin-sdk";
+import { ChannelSupervisor } from "../channels/supervisor.js";
+import { ChannelWebhooks } from "../channels/webhook.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). 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;
+    /** 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);
+    /** The gateway role's HTTP routes (the channel webhook), 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>;
+    /**
+     * 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,98 @@
+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 { 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). Provided
+ * only by `GatewayModule`, so a process without the gateway role has none of them.
+ */
+let GatewayRole = class GatewayRole {
+    config;
+    host;
+    bus;
+    supervisor;
+    webhooks;
+    /** 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) {
+        this.config = config;
+        this.host = host;
+        this.bus = bus;
+        this.supervisor = supervisor;
+        this.webhooks = webhooks;
+    }
+    /** The gateway role's HTTP routes (the channel webhook), registered when the app is built. */
+    routes() {
+        return {
+            webhooks: this.webhooks,
+            webhookMaxBodyBytes: this.config.get().channels.webhookMaxBodyBytes,
+        };
+    }
+    /**
+     * 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();
+    }
+    /**
+     * 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))
+], GatewayRole);
+export { GatewayRole };

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

@@ -0,0 +1,8 @@
+/**
+ * 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`) 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,28 @@
+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 { 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`) 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],
+        providers: [ChannelSupervisor, ChannelWebhooks, GatewayRole],
+        exports: [GatewayRole],
+    })
+], GatewayModule);
+export { GatewayModule };

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

@@ -0,0 +1,63 @@
+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, 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;
+    /** 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);
+    /**
+     * 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. */
+    closeMaintenance(): Promise<void>;
+}