@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/inbox/platform-inbox.service.js

@@ -0,0 +1,263 @@
+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 { sql } from "kysely";
+import { CatalogService } from "../catalog/catalog.service.js";
+import { CatalogRequestsService } from "../catalog/requests.service.js";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/** The most items one platform inbox read returns. */
+export const PLATFORM_INBOX_MAX_ITEMS = 100;
+/** The most open scope sync failures one read takes. */
+export const SCOPE_SYNC_FAILURES_LIST_MAX = 200;
+/**
+ * A platform components migration run unfinished this long after its start is stuck (its worker
+ * stopped mid-run; a run takes seconds, and the next one starts at the next worker start or day).
+ */
+export const MIGRATION_RUN_STUCK_MS = 60 * 60_000;
+/** Plugin install statuses of a plugin that is on in the org. */
+const LIVE_INSTALL = ["installing", "installed", "upgrading"];
+/**
+ * The super admin's inbox (plugin scope spec §5.1 rule 5, §13.5): what waits on the platform,
+ * gathered from the sources the admin pages read (the 待确认 tab's requests and permission
+ * confirmations), plus the scope sync's open failures and the platform components migration's
+ * latest run. Stateless, read live from PG.
+ */
+let PlatformInboxService = class PlatformInboxService {
+    requests;
+    catalog;
+    kdb;
+    constructor(requests, catalog, kdb) {
+        this.requests = requests;
+        this.catalog = catalog;
+        this.kdb = kdb;
+    }
+    async list() {
+        const [requests, requestCount, pending, failures, failureCount, run, notices, noticeCount] = await Promise.all([
+            this.requests.listDeployment(),
+            this.requests.countPendingDeployment(),
+            this.catalog.list({ pending: true }),
+            this.scopeSyncFailures(),
+            this.countScopeSyncFailures(),
+            this.migrationRun(),
+            this.notices(),
+            this.countNotices(),
+        ]);
+        const all = [
+            ...requests.map((r) => ({
+                type: "catalog_request",
+                id: r.id,
+                createdAt: r.createdAt,
+                request: r,
+            })),
+            ...pending.map((i) => ({
+                type: i.owner.kind === "org" ? "org_upload_pending" : "permission_confirmation",
+                id: i.id,
+                createdAt: i.updatedAt,
+                item: i,
+            })),
+            ...failures.map((f) => ({
+                type: "scope_sync_failed",
+                id: `${f.item.id}/${f.org.id}`,
+                createdAt: f.failedAt,
+                failure: f,
+            })),
+            ...notices.map((n) => ({
+                type: "ownership_transferred",
+                id: n.id,
+                createdAt: n.createdAt,
+                notice: n,
+            })),
+            ...(run === null
+                ? []
+                : [
+                    {
+                        type: "platform_migration",
+                        id: run.id,
+                        createdAt: run.finishedAt ?? run.startedAt,
+                        run,
+                    },
+                ]),
+        ];
+        // newest first; equal times by id (a stable order)
+        all.sort((a, b) => a.createdAt !== b.createdAt
+            ? a.createdAt < b.createdAt
+                ? 1
+                : -1
+            : a.id < b.id
+                ? -1
+                : a.id > b.id
+                    ? 1
+                    : 0);
+        const total = requestCount + pending.length + failureCount + (run === null ? 0 : 1) + noticeCount;
+        const items = all.slice(0, PLATFORM_INBOX_MAX_ITEMS);
+        return { items, truncated: total > items.length, total };
+    }
+    /**
+     * How many items wait (the sidebar's count): the same sources, counted where they can be (the
+     * requests and the failures; the permission confirmations are the catalog's pending list).
+     */
+    async count() {
+        const [requests, pending, failures, run, notices] = await Promise.all([
+            this.requests.countPendingDeployment(),
+            this.catalog.list({ pending: true }),
+            this.countScopeSyncFailures(),
+            this.migrationRun(),
+            this.countNotices(),
+        ]);
+        return requests + pending.length + failures + (run === null ? 0 : 1) + notices;
+    }
+    async countNotices() {
+        const r = await this.kdb.db
+            .selectFrom("platform_notices")
+            .select(sql `count(*)`.as("n"))
+            .where("dismissed_at", "is", null)
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** The open platform notices, newest first, at most {@link PLATFORM_INBOX_MAX_ITEMS}. */
+    async notices() {
+        const rows = await this.kdb.db
+            .selectFrom("platform_notices")
+            .select(["id", "kind", "detail", "created_at"])
+            .where("dismissed_at", "is", null)
+            .orderBy("created_at", "desc")
+            .orderBy("id")
+            .limit(PLATFORM_INBOX_MAX_ITEMS)
+            .execute();
+        return rows.map((r) => ({
+            id: r.id,
+            kind: r.kind,
+            createdAt: r.created_at.toISOString(),
+            detail: r.detail,
+        }));
+    }
+    /**
+     * A super admin dismisses a platform notice (for every super admin). Dismissing one already
+     * dismissed is fine; no notice with that id -> `inbox.notice_not_found`.
+     */
+    async dismissNotice(accountId, id) {
+        if (!UUID_RE.test(id))
+            throw new ApiError("inbox.notice_not_found", "Notice not found");
+        const r = await this.kdb.db
+            .updateTable("platform_notices")
+            .set({ dismissed_at: sql `now()`, dismissed_by: accountId })
+            .where("id", "=", id)
+            .where("dismissed_at", "is", null)
+            .executeTakeFirst();
+        if (r.numUpdatedRows > 0n)
+            return;
+        const exists = await this.kdb.db
+            .selectFrom("platform_notices")
+            .select("id")
+            .where("id", "=", id)
+            .executeTakeFirst();
+        if (!exists)
+            throw new ApiError("inbox.notice_not_found", "Notice not found");
+    }
+    /**
+     * The open failures still worth a look, joined to their item and org: of a live item and org,
+     * and the pair still differs in the failed direction (a person may have converged it meanwhile):
+     * an install failure while the org has no live install of the item; an uninstall or dependencies
+     * failure while it has one.
+     */
+    failureRows() {
+        return this.kdb.db
+            .selectFrom("plugin_scope_sync_failures as f")
+            .innerJoin("catalog_items as i", "i.id", "f.item_id")
+            .innerJoin("orgs as o", "o.id", "f.org_id")
+            .where("i.deleted_at", "is", null)
+            .where("o.deleted_at", "is", null)
+            .where((eb) => {
+            const live = eb.exists(eb
+                .selectFrom("plugin_installs as p")
+                .select("p.id")
+                .whereRef("p.org_id", "=", "f.org_id")
+                .whereRef("p.item_id", "=", "f.item_id")
+                .where("p.status", "in", [...LIVE_INSTALL]));
+            return eb.or([
+                eb.and([eb("f.op", "=", "install"), eb.not(live)]),
+                eb.and([eb("f.op", "in", ["uninstall", "dependencies"]), live]),
+            ]);
+        });
+    }
+    async countScopeSyncFailures() {
+        const r = await this.failureRows()
+            .select(sql `count(*)`.as("n"))
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** The open scope sync failures ({@link failureRows}), newest first. */
+    async scopeSyncFailures() {
+        const rows = await this.failureRows()
+            .select([
+            "f.item_id",
+            "i.name as item_name",
+            "i.display_name",
+            "f.org_id",
+            "o.name as org_name",
+            "f.op",
+            "f.code",
+            "f.message",
+            "f.failed_at",
+        ])
+            .orderBy("f.failed_at", "desc")
+            .orderBy("f.item_id")
+            .orderBy("f.org_id")
+            .limit(SCOPE_SYNC_FAILURES_LIST_MAX)
+            .execute();
+        return rows.map((r) => ({
+            item: { id: r.item_id, name: r.item_name, displayName: r.display_name },
+            org: { id: r.org_id, name: r.org_name },
+            op: r.op,
+            code: r.code,
+            message: r.message,
+            failedAt: r.failed_at.toISOString(),
+        }));
+    }
+    /**
+     * The latest migration run when it needs a look (see {@link MigrationRunView}); null when it
+     * finished without failed items, is still running, or there was none. An earlier run's failure
+     * is not shown: each run tries every unwritten item again.
+     */
+    async migrationRun() {
+        const run = await this.kdb.db
+            .selectFrom("platform_migration_runs")
+            .select(["id", "started_at", "finished_at", "stats"])
+            .orderBy("started_at", "desc")
+            .orderBy("id", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        if (run === undefined)
+            return null;
+        const failed = run.stats.itemsFailed;
+        const itemsFailed = Array.isArray(failed)
+            ? failed.filter((x) => typeof x === "string")
+            : [];
+        const stuck = run.finished_at === null && run.started_at.getTime() < Date.now() - MIGRATION_RUN_STUCK_MS;
+        if (!stuck && (run.finished_at === null || itemsFailed.length === 0))
+            return null;
+        return {
+            id: run.id,
+            startedAt: run.started_at.toISOString(),
+            finishedAt: run.finished_at?.toISOString() ?? null,
+            stuck,
+            itemsFailed,
+        };
+    }
+};
+PlatformInboxService = __decorate([
+    Injectable(),
+    __param(0, Inject(CatalogRequestsService)),
+    __param(1, Inject(CatalogService)),
+    __param(2, Inject(KernelDb))
+], PlatformInboxService);
+export { PlatformInboxService };
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/dist/inbox/platform-notices.d.ts

@@ -0,0 +1,19 @@
+import type { OwnedRef } from "../catalog/ownership.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+export type PlatformNoticeKind = "ownership_transferred";
+/** The `detail` of each platform notice kind. */
+export interface PlatformNoticeDetails {
+    /** A deleted org's (or owner's) shared item now belongs to the platform. */
+    ownership_transferred: {
+        ref: OwnedRef;
+        name: string;
+        fromOrg: {
+            id: string;
+            name: string;
+        };
+        reason: "owner_deleted" | "org_deleted";
+        /** How many other orgs use it. */
+        usedBy: number;
+    };
+}
+export declare function addPlatformNotice<K extends PlatformNoticeKind>(db: KernelSchemaDb, kind: K, detail: PlatformNoticeDetails[K]): Promise<void>;

package/dist/inbox/platform-notices.js

@@ -0,0 +1,9 @@
+// Platform notices (`platform_notices`, plugin scope phase 3, ruling P3-22): what the super admins
+// are told, until any one of them dismisses it. Written in the caller's transaction.
+import { randomUUID } from "node:crypto";
+export async function addPlatformNotice(db, kind, detail) {
+    await db
+        .insertInto("platform_notices")
+        .values({ id: randomUUID(), kind, detail: JSON.stringify(detail) })
+        .execute();
+}

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { type ApprovalDecision, ExtensionApprovals, type PendingExtension, type
 export { blobKey, ExtensionBlobIntegrityError, type ExtensionBlobSource, ExtensionBlobs, } from "./extensions/blobs.js";
 export { BOOTSTRAP_MANIFEST_FILE, type BootstrapEntryResult, BootstrapFailedError, type BootstrapFailure, type BootstrapResolveOptions, type BootstrapResult, BootstrapService, bootstrapManifestSha256, readBootstrapManifest, resolveBootstrapPackages, } from "./extensions/bootstrap.js";
 export { type ExtensionCli, openExtensionCli } from "./extensions/cli.js";
-export { DEPLOYMENT_SECRETS_ORG, type DeploymentConfigField, type DeploymentConfigView, ExtensionDeploymentConfigService, mergeDeploymentConfig, PLUGIN_DEPLOYMENT_CONFIG_TOPIC, readStoredDeploymentConfig, } from "./extensions/deployment-config.js";
+export { DEPLOYMENT_SECRETS_ORG, type DeploymentConfigField, type DeploymentConfigView, ExtensionDeploymentConfigService, mergeDeploymentConfig, PLUGIN_DEPLOYMENT_CONFIG_TOPIC, readStoredDeploymentConfig, type SecretEntry, } from "./extensions/deployment-config.js";
 export { assertSecretsReachable, ExtensionHost, type ExtensionLoadPlan, type InspectedExtension, type InstalledExtensionLoader, type InstallFailureReason, } from "./extensions/host.js";
 export { ExtensionUnloadedError, type InflightEntry, InflightTracker, PLUGIN_UNLOADED_TOOL_ERROR, type TrackOptions, trackCalls, } from "./extensions/inflight.js";
 export { type DesiredExtension, type ExtensionInstallRow, ExtensionInstalls, type IngestSource, type PackageReview, } from "./extensions/installs.js";
@@ -71,4 +71,4 @@ export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
 export { SANDBOX_LOCK_TTL_MS, SandboxService, type SandboxUseInfo, } from "./sandbox/sandbox.service.js";
 export { MAX_STORAGE_KEY_BYTES, StorageKeyError, } from "./storage/prefix.js";
 export { PrefixedStorage, StorageService, type StorageSource, } from "./storage/storage.service.js";
-export { SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";
+export { SANDBOX_RESTARTED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";

package/dist/index.js

@@ -67,4 +67,4 @@ export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
 export { SANDBOX_LOCK_TTL_MS, SandboxService, } from "./sandbox/sandbox.service.js";
 export { MAX_STORAGE_KEY_BYTES, StorageKeyError, } from "./storage/prefix.js";
 export { PrefixedStorage, StorageService, } from "./storage/storage.service.js";
-export { SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";
+export { SANDBOX_RESTARTED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";

package/dist/infra/cli/kernel-cli.module.js

@@ -13,6 +13,7 @@ import { NestFactory } from "@nestjs/core";
 import { Redis } from "ioredis";
 import { createBus } from "../../ctx/bus.js";
 import { KERNEL_APP_OPTIONS } from "../../lifecycle/tokens.js";
+import { CacheModule } from "../cache/cache.module.js";
 import { ConfigModule } from "../config/config.module.js";
 import { KernelConfigService } from "../config/kernel-config.service.js";
 import { DatabaseModule } from "../database/database.module.js";
@@ -20,6 +21,7 @@ import { KernelEventsModule } from "../events/kernel-events.js";
 import { GracefulShutdownModule } from "../lifecycle/graceful-shutdown.module.js";
 import { LockModule } from "../lock/lock.module.js";
 import { LoggingModule } from "../logging/logging.module.js";
+import { QueueModule } from "../queue/queue.module.js";
 import { KERNEL_BUS, KERNEL_LOGGER, REDIS, REDIS_SUBSCRIBER } from "../tokens.js";
 /** How long the CLI's Redis connection may take before a command fails (a publish only warns). */
 const CLI_REDIS_CONNECT_TIMEOUT_MS = 3_000;
@@ -108,7 +110,13 @@ let KernelCliModule = KernelCliModule_1 = class KernelCliModule {
                 ConfigModule.forRoot(config, opts.env !== undefined ? { env: opts.env } : {}),
                 GracefulShutdownModule,
                 DatabaseModule.forRoot(),
-                ...(opts.redis === false ? [] : [CliRedisModule, LockModule]),
+                // QueueModule's root gives the queues a command's modules register (the catalog's scope
+                // sync and maintenance queues) the configured Redis; without it BullMQ would connect to
+                // its default 127.0.0.1:6379
+                // CacheModule: `@Cacheable` providers of the domain modules (EffectiveConfigs) need it
+                ...(opts.redis === false
+                    ? []
+                    : [CliRedisModule, LockModule, CacheModule, QueueModule.forRoot()]),
                 KernelEventsModule,
                 ...opts.modules,
             ],

package/dist/infra/config/kernel-config.service.js

@@ -30,11 +30,32 @@ const HOT_APPLIERS = {
     "hooks.timeoutMs": () => { },
     // SandboxService reads the shared-lease cap at every acquisition.
     "sandbox.maxConcurrentCommands": () => { },
+    // The environments service reads the personal limit at every create.
+    "environments.maxPersonal": () => { },
     // Sub-agent limits are read at every dispatch, child step and tool resolution.
-    "subagents.maxConcurrentPerRun": () => { },
+    "subagents.maxDepth": () => { },
+    "subagents.maxConcurrentPerConversation": () => { },
     "subagents.maxDispatchesPerRun": () => { },
     "subagents.maxTokensPerRun": () => { },
+    // The web tools read these limits through the config service on every call.
+    "web.search.maxResults": () => { },
+    "web.fetch.maxPageChars": () => { },
+    "web.fetch.maxAnswerTokens": () => { },
+    "web.fetch.cacheSeconds": () => { },
+    "web.fetch.timeoutMs": () => { },
 };
+/**
+ * Environment variables of renamed config keys, with their replacements: warned about once when
+ * the service starts (agent map spec §6: `subagents.maxConcurrentPerRun` became
+ * `subagents.maxConcurrentPerConversation`). A retired file or Nacos key cannot be told here: the
+ * schema strips unknown keys before the kernel receives its config.
+ */
+const RETIRED_ENV = [
+    [
+        "CAPYBARA_SUBAGENTS__MAX_CONCURRENT_PER_RUN",
+        "CAPYBARA_SUBAGENTS__MAX_CONCURRENT_PER_CONVERSATION",
+    ],
+];
 const HOT_PATHS = configFields(KernelConfigSchema)
     .filter((f) => f.meta?.hot)
     .map((f) => f.path);
@@ -55,6 +76,11 @@ let KernelConfigService = class KernelConfigService {
         this.env = input.env ?? process.env;
         log.setLevel(input.config.log.level);
         log.addSecrets(secretValues(KernelConfigSchema, input.config));
+        for (const [old, now] of RETIRED_ENV) {
+            if (this.env[old] !== undefined) {
+                log.warn(`${old} is no longer read and is ignored; set ${now} instead`, { env: old });
+            }
+        }
     }
     get() {
         return this.current;

package/dist/infra/database/database.module.js

@@ -66,6 +66,7 @@ let DatabaseModule = class DatabaseModule {
                     const { db } = config.get();
                     return createDb(db.url, db.poolMax, (err) => log.error("pg idle client error", { err }), {
                         connectTimeoutMs: db.connectTimeoutMs,
+                        idleTimeoutMs: db.idleTimeoutMs,
                         onClientError: (err) => log.warn("pg client error", { err }),
                     });
                 },

package/dist/infra/database/xact-lock.d.ts

@@ -4,7 +4,7 @@ import { TransactionHost } from "./transaction-host.js";
  * Transaction-scoped advisory locks (decision R9 of the Nest kernel spec): `pg_advisory_xact_lock`
  * is transaction semantics, like `FOR UPDATE`. It is held by the caller's transaction and released
  * at its COMMIT or ROLLBACK, so it serializes writers whose invariant is checked inside that same
- * transaction ("never zero active enterprise admins", "set up once", "one account per external
+ * transaction ("never zero active super admins", "set up once", "one account per external
  * identity"). The one place that takes such a lock; `propagation: "mandatory"` makes a call outside
  * a transaction (where the lock would be released at once) throw.
  */

package/dist/infra/database/xact-lock.js

@@ -16,7 +16,7 @@ import { Transactional } from "./transactional.decorator.js";
  * Transaction-scoped advisory locks (decision R9 of the Nest kernel spec): `pg_advisory_xact_lock`
  * is transaction semantics, like `FOR UPDATE`. It is held by the caller's transaction and released
  * at its COMMIT or ROLLBACK, so it serializes writers whose invariant is checked inside that same
- * transaction ("never zero active enterprise admins", "set up once", "one account per external
+ * transaction ("never zero active super admins", "set up once", "one account per external
  * identity"). The one place that takes such a lock; `propagation: "mandatory"` makes a call outside
  * a transaction (where the lock would be released at once) throw.
  */

package/dist/infra/events/kernel-events.d.ts

@@ -72,12 +72,29 @@ export interface KernelEventMap {
         runId: string;
     };
     /**
-     * `ensureRun` marked an orphaned run failed (after the commit): the waits stop its active
-     * sub-agents at once. A lost event is repaired by the wait sweep (children of finished runs).
+     * `ensureRun` marked an orphaned run failed (after the commit): the waits stop its active fork
+     * sub-agent at once (background sub-agents keep running, agent map spec §5.4). A lost event is
+     * repaired by the wait sweep (fork children of finished runs).
      */
     "run.orphaned": {
         runId: string;
     };
+    /**
+     * A sub-agent's `subagent_delivery` was appended to its parent conversation (after the commit;
+     * `SubagentDeliveries`). Waking an idle parent follows it; a lost event is re-derived by the
+     * next `ensureRun` (a message, the end of a run, a page opening).
+     */
+    "subagent.delivered": {
+        conversationId: string;
+    };
+    /**
+     * A background task of the conversation finished (after the commit of its
+     * `background_task_finished` event). `BackgroundWake` asks the run queue for a wake run; a lost
+     * event is re-derived by the next `ensureRun` (a message, the end of a run, a page opening).
+     */
+    "background_task.finished": {
+        conversationId: string;
+    };
 }
 type Handler<K extends keyof KernelEventMap> = (payload: KernelEventMap[K]) => Promise<void> | void;
 /** Typed in-process event emitter; handlers run in order, a failing one is logged and skipped. */

package/dist/infra/lifecycle/process-guards.js

@@ -39,6 +39,10 @@ export function createFatalRecorder(deps) {
     let recent = [];
     let open = false;
     return (kind, err) => {
+        // Exiting already: log nothing more. A failing log write (EPIPE on a dead stdout) raises the
+        // next event itself; logging it again would keep the process busy forever and starve the exit.
+        if (open)
+            return;
         try {
             const t = now();
             recent = recent.filter((x) => t - x < GUARD_CIRCUIT_WINDOW_MS);

package/dist/infra/logging/logging.module.d.ts

@@ -6,8 +6,10 @@ export interface LoggingModuleOptions {
     logger?: KernelLogger;
 }
 /**
- * Provides the process logger as `KERNEL_LOGGER`. The logger is created before the Nest context
- * (it must exist for startup errors), so it is passed in or derived from the startup config here.
+ * Provides the process logger as `KERNEL_ROOT_LOGGER` and, as `KERNEL_LOGGER`, one child per injecting
+ * class with `context` = the class name (the `[context=…]` of the pretty output; octok's
+ * per-class Nest logger context). The logger is created before the Nest context (it must exist for
+ * startup errors), so it is passed in or derived from the startup config here.
  */
 export declare class LoggingModule {
     static forRoot(config: KernelConfig, opts?: LoggingModuleOptions): DynamicModule;

package/dist/infra/logging/logging.module.js

@@ -5,12 +5,15 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var LoggingModule_1;
-import { Global, Module } from "@nestjs/common";
+import { Global, Module, Scope } from "@nestjs/common";
+import { INQUIRER } from "@nestjs/core";
 import { createConfiguredLogger } from "../../log-config.js";
-import { KERNEL_LOGGER } from "../tokens.js";
+import { KERNEL_LOGGER, KERNEL_ROOT_LOGGER } from "../tokens.js";
 /**
- * Provides the process logger as `KERNEL_LOGGER`. The logger is created before the Nest context
- * (it must exist for startup errors), so it is passed in or derived from the startup config here.
+ * Provides the process logger as `KERNEL_ROOT_LOGGER` and, as `KERNEL_LOGGER`, one child per injecting
+ * class with `context` = the class name (the `[context=…]` of the pretty output; octok's
+ * per-class Nest logger context). The logger is created before the Nest context (it must exist for
+ * startup errors), so it is passed in or derived from the startup config here.
  */
 let LoggingModule = LoggingModule_1 = class LoggingModule {
     static forRoot(config, opts = {}) {
@@ -21,8 +24,16 @@ let LoggingModule = LoggingModule_1 = class LoggingModule {
         return {
             module: LoggingModule_1,
             global: true,
-            providers: [{ provide: KERNEL_LOGGER, useValue: logger }],
-            exports: [KERNEL_LOGGER],
+            providers: [
+                { provide: KERNEL_ROOT_LOGGER, useValue: logger },
+                {
+                    provide: KERNEL_LOGGER,
+                    scope: Scope.TRANSIENT,
+                    inject: [KERNEL_ROOT_LOGGER, INQUIRER],
+                    useFactory: (root, inquirer) => contextLogger(root, inquirer),
+                },
+            ],
+            exports: [KERNEL_ROOT_LOGGER, KERNEL_LOGGER],
         };
     }
 };
@@ -32,3 +43,10 @@ LoggingModule = LoggingModule_1 = __decorate([
     // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
 ], LoggingModule);
 export { LoggingModule };
+/** The child of `root` for the class instance `inquirer`; `root` itself for a factory provider. */
+function contextLogger(root, inquirer) {
+    const name = inquirer?.constructor?.name;
+    return typeof name === "string" && name !== "" && name !== "Object"
+        ? root.child({ context: name })
+        : root;
+}

package/dist/infra/queue/add-job-once.d.ts

@@ -0,0 +1,14 @@
+import { type JobsOptions } from "bullmq";
+import type { Redis } from "ioredis";
+/** One job to add: its name, data and options (a deterministic `jobId` makes the add idempotent). */
+export interface OneJob<T> {
+    name: string;
+    data: T;
+    opts: JobsOptions;
+}
+/**
+ * Adds one job to a kernel queue from a process that hosts no queue of its own (a CLI command),
+ * over the caller's Redis connection (left open), with BullMQ's default key prefix like the
+ * kernel's queues. The queue handle is closed again before returning.
+ */
+export declare function addJobOnce<T>(connection: Redis, queue: string, job: OneJob<T>): Promise<void>;

package/dist/infra/queue/add-job-once.js

@@ -0,0 +1,16 @@
+import { Queue } from "bullmq";
+/**
+ * Adds one job to a kernel queue from a process that hosts no queue of its own (a CLI command),
+ * over the caller's Redis connection (left open), with BullMQ's default key prefix like the
+ * kernel's queues. The queue handle is closed again before returning.
+ */
+export async function addJobOnce(connection, queue, job) {
+    const q = new Queue(queue, { connection });
+    try {
+        // biome-ignore lint/suspicious/noExplicitAny: BullMQ's name and data generics do not line up here
+        await q.add(job.name, job.data, job.opts);
+    }
+    finally {
+        await q.close();
+    }
+}

package/dist/infra/queue/redis-connection.d.ts

@@ -1,4 +1,10 @@
 import type { RedisOptions } from "bullmq";
+/**
+ * TCP keepalive of every long-lived kernel Redis connection: probes start after 10 s idle (the OS
+ * default is 2 hours), so a connection a dropped network left half-open is found and reconnected
+ * before a command waits on it, not at the next write (EPIPE).
+ */
+export declare const REDIS_KEEPALIVE_MS = 10000;
 /**
  * BullMQ connection options from the kernel's Redis URL, the same connection the hand-made
  * `new Redis(url, { maxRetriesPerRequest: null })` workers use: BullMQ requires

package/dist/infra/queue/redis-connection.js

@@ -1,3 +1,9 @@
+/**
+ * TCP keepalive of every long-lived kernel Redis connection: probes start after 10 s idle (the OS
+ * default is 2 hours), so a connection a dropped network left half-open is found and reconnected
+ * before a command waits on it, not at the next write (EPIPE).
+ */
+export const REDIS_KEEPALIVE_MS = 10_000;
 /**
  * BullMQ connection options from the kernel's Redis URL, the same connection the hand-made
  * `new Redis(url, { maxRetriesPerRequest: null })` workers use: BullMQ requires
@@ -14,5 +20,6 @@ export function bullConnectionOptions(url) {
         ...(db !== undefined && Number.isInteger(db) && { db }),
         ...(u.protocol === "rediss:" && { tls: {} }),
         maxRetriesPerRequest: null,
+        keepAlive: REDIS_KEEPALIVE_MS,
     };
 }

package/dist/infra/redis/redis.module.js

@@ -14,6 +14,7 @@ import { closeWithin } from "../close-within.js";
 import { KernelConfigService } from "../config/kernel-config.service.js";
 import { GracefulShutdownModule } from "../lifecycle/graceful-shutdown.module.js";
 import { GracefulShutdown } from "../lifecycle/graceful-shutdown.service.js";
+import { REDIS_KEEPALIVE_MS } from "../queue/redis-connection.js";
 import { KERNEL_BUS, KERNEL_LOGGER, REDIS, REDIS_SUBSCRIBER } from "../tokens.js";
 /**
  * Closes the bus subscriber, then the main connection, at the end of the shutdown
@@ -64,7 +65,10 @@ RedisModule = __decorate([
                 provide: REDIS,
                 inject: [KernelConfigService, KERNEL_LOGGER],
                 useFactory: (config, log) => {
-                    const redis = new Redis(config.get().redis.url, { lazyConnect: true });
+                    const redis = new Redis(config.get().redis.url, {
+                        lazyConnect: true,
+                        keepAlive: REDIS_KEEPALIVE_MS,
+                    });
                     redis.on("error", (err) => log.error("redis connection error", { err }));
                     return redis;
                 },
@@ -72,7 +76,7 @@ RedisModule = __decorate([
             {
                 provide: REDIS_SUBSCRIBER,
                 inject: [KernelConfigService, KERNEL_LOGGER],
-                useFactory: (config, log) => createBusSubscriber(() => new Redis(config.get().redis.url), log),
+                useFactory: (config, log) => createBusSubscriber(() => new Redis(config.get().redis.url, { keepAlive: REDIS_KEEPALIVE_MS }), log),
             },
             {
                 provide: KERNEL_BUS,

package/dist/infra/tokens.d.ts

@@ -1,6 +1,11 @@
 /** Injection tokens of the global infra modules. */
-/** The process logger (`KernelLogger`). */
+/**
+ * A class's logger (`KernelLogger`): the process logger with `context` set to the injecting class's
+ * name. Transient, so `app.get` cannot resolve it; use `KERNEL_ROOT_LOGGER` outside an injection.
+ */
 export declare const KERNEL_LOGGER: unique symbol;
+/** The process logger itself (`KernelLogger`), without a context. */
+export declare const KERNEL_ROOT_LOGGER: unique symbol;
 /** The startup input of `KernelConfigService`: `{ config, env }`. */
 export declare const KERNEL_CONFIG_INPUT: unique symbol;
 /** The Kysely pool, untyped (`Kysely<any>`); infra only, services inject `KernelDb`. */