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

package/dist/lifecycle/kernel-lifecycle.js

@@ -0,0 +1,451 @@
+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 { SANDBOX_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable, Optional, } from "@nestjs/common";
+import { sql } from "kysely";
+import { MarketplacesService } from "../catalog/marketplaces.service.js";
+import { PluginImport } from "../catalog/plugin-import.js";
+import { ChannelJobs } from "../channels/jobs.js";
+import { ChannelOutbound } from "../channels/outbound.js";
+import { TitleQueue } from "../conversations/titles.js";
+import { migrate } from "../db/migrator.js";
+import { ExtensionBlobs } from "../extensions/blobs.js";
+import { BootstrapFailedError, BootstrapService, bootstrapManifestSha256, readBootstrapManifest, } from "../extensions/bootstrap.js";
+import { ExtensionHost } from "../extensions/host.js";
+import { ExtensionInstalls } from "../extensions/installs.js";
+import { ExtensionLifecycle } from "../extensions/lifecycle.js";
+import { ensureMigrated } from "../extensions/migrate-lock.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { ReplicaStatusStore } from "../extensions/sources.js";
+import { syncPackage } from "../extensions/sync.js";
+import { AccountsService } from "../identity/accounts.js";
+import { waitWithin } from "../infra/close-within.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
+import { KERNEL_BUS, KERNEL_LOGGER, KERNEL_POOL, REDIS } from "../infra/tokens.js";
+import { KERNEL_MIGRATIONS_DIR, KERNEL_SCHEMA } from "../kernel.js";
+import { GatewayRole } from "../roles/gateway-role.js";
+import { WorkerRole } from "../roles/worker-role.js";
+import { UsageReporter } from "../runtime/usage-report.js";
+import { sandboxConfigWarnings } from "../sandbox/sandbox.service.js";
+import { KERNEL_APP_OPTIONS } from "./tokens.js";
+/**
+ * The stop phase budgets. Each phase waits `min(its budget, what is left of the total)`, where the
+ * total is `STOP_TIMEOUT_MS` (30 s, `GracefulShutdown`) counted from the moment the shutdown
+ * began, in this order: migrate 2 s (the start's in-flight kernel migration, aborted, until its
+ * session ended) → http 10 s → runs 10 s → plugins 5 s, 27 s in all. The bus subscriber, Redis and
+ * the pool are closed after the phases by the infra modules (`onApplicationShutdown`) within what
+ * is left of the same 30 s, so the whole stop never takes longer than 30 s.
+ * The http phase is one deadline: first the listen in progress finishes (closing while listening
+ * would leave the port open), then HTTP closes, both within these 10 s; whatever is still open at
+ * the deadline is disconnected.
+ * The runs phase: this process's runs get the stop signal, stop at their next step boundary and
+ * their jobs go back to the queue; runs over the budget are left to BullMQ's stalled-job handling
+ * on another worker (spec 8.5). So when an earlier phase hangs, the extension queues still get at
+ * least 5 s to drain.
+ */
+export const STOP_BUDGET_MS = {
+    migrate: 2_000,
+    http: 10_000,
+    runs: 10_000,
+    plugins: 5_000,
+};
+/** 停机时留给渠道长连接交还租约的最少时间（与 runs 阶段并行开始，runs 用尽预算时仍保底）。 */
+const CHANNELS_STOP_MIN_MS = 2_000;
+/** runs 阶段里留给强制关闭 worker 的余量（预算的其余部分用于等运行到达步骤边界）。 */
+const RUNS_FORCE_CLOSE_MS = 500;
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/**
+ * The kernel's start order and stop phases on Nest's hooks (nest kernel spec §4).
+ *
+ * Start (`onApplicationBootstrap`, run by `app.init()`): Redis ready → kernel migrations → official
+ * marketplace sync → bootstrap → extension host load → role parts (workers, schedules, gateway) →
+ * mount extension routes → extension lifecycle reconcile → (second bootstrap pass) → config watch.
+ * {@link listen} runs only after that resolved, so nothing is served before the extensions are
+ * loaded. A stop requested meanwhile makes the sequence throw at its next checkpoint.
+ *
+ * Stop (`beforeApplicationShutdown`, or {@link stop} directly): readiness answers 503, the start is
+ * aborted, then today's phases with {@link STOP_BUDGET_MS} (HTTP, runs, channels, queues, the
+ * extension host). Redis and the pool are closed after this by the infra modules
+ * (`onApplicationShutdown`, global modules run last).
+ */
+let KernelLifecycle = class KernelLifecycle {
+    accounts;
+    configService;
+    log;
+    options;
+    pool;
+    redis;
+    kdb;
+    shutdown;
+    host;
+    registry;
+    installs;
+    blobs;
+    extensionLifecycle;
+    replicaStatus;
+    bootstrap;
+    marketplaces;
+    pluginImport;
+    bus;
+    usageReport;
+    titles;
+    channelJobs;
+    channelOutbound;
+    worker;
+    gateway;
+    /** The startup config (hot fields are read through the config service). */
+    config;
+    /** Set when the application was never set up completely: shutdown only releases connections. */
+    onlyRelease = false;
+    stopPromise;
+    /** {@link listen} was called: the start work in flight is the listen, not the start sequence. */
+    listenStarted = false;
+    listening;
+    httpApp;
+    unwatchConfig;
+    /** What the first bootstrap pass did, carried into the second one. */
+    bootstrapCarry;
+    constructor(accounts, configService, log, options, 
+    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+    pool, redis, kdb, shutdown, host, registry, installs, blobs, extensionLifecycle, replicaStatus, bootstrap, marketplaces, pluginImport, bus, 
+    // the producers closed on every role (their consumers are the worker role's)
+    usageReport, titles, channelJobs, channelOutbound, 
+    // The role modules' parts: a role module is imported only when `roles` names it, so each is
+    // present exactly when its role is (checked at the start)
+    worker, gateway) {
+        this.accounts = accounts;
+        this.configService = configService;
+        this.log = log;
+        this.options = options;
+        this.pool = pool;
+        this.redis = redis;
+        this.kdb = kdb;
+        this.shutdown = shutdown;
+        this.host = host;
+        this.registry = registry;
+        this.installs = installs;
+        this.blobs = blobs;
+        this.extensionLifecycle = extensionLifecycle;
+        this.replicaStatus = replicaStatus;
+        this.bootstrap = bootstrap;
+        this.marketplaces = marketplaces;
+        this.pluginImport = pluginImport;
+        this.bus = bus;
+        this.usageReport = usageReport;
+        this.titles = titles;
+        this.channelJobs = channelJobs;
+        this.channelOutbound = channelOutbound;
+        this.worker = worker;
+        this.gateway = gateway;
+        this.config = configService.get();
+    }
+    /** The kernel HTTP application (set up by `buildKernelApp` before `init()`). */
+    get http() {
+        if (!this.httpApp)
+            throw new Error("kernel HTTP application is not set up");
+        return this.httpApp;
+    }
+    attachHttp(http) {
+        this.httpApp = http;
+    }
+    /** The gateway role's HTTP routes (the channel webhook), when the roles include `gateway`. */
+    gatewayRoutes() {
+        return this.gateway?.routes();
+    }
+    /** The port listened on; undefined before {@link listen} resolves and after the stop. */
+    get port() {
+        return this.listening;
+    }
+    /** The application was not set up completely: its shutdown only releases connections. */
+    releaseOnly() {
+        this.onlyRelease = true;
+        this.shutdown.begin();
+    }
+    checkpoint() {
+        if (this.shutdown.isShuttingDown())
+            throw new Error("kernel stopped during start");
+    }
+    async onApplicationBootstrap() {
+        if (this.shutdown.isShuttingDown())
+            throw new Error("kernel is stopped");
+        const { config, options: opts } = this;
+        const { worker, gateway } = this;
+        if (config.roles.includes("worker") !== (worker !== undefined)) {
+            throw new Error("the worker role's module does not match the roles");
+        }
+        if (config.roles.includes("gateway") !== (gateway !== undefined)) {
+            throw new Error("the gateway role's module does not match the roles");
+        }
+        const cfg = () => this.configService.get();
+        await this.redis.connect();
+        this.checkpoint();
+        await sql `select 1`.execute(this.pool);
+        this.checkpoint();
+        // In flight for the stop: aborted when the shutdown begins, which then waits for its session to end
+        await this.shutdown.trackInFlight(migrate(config.db.url, { schema: KERNEL_SCHEMA, dir: KERNEL_MIGRATIONS_DIR }, { connectTimeoutMs: config.db.connectTimeoutMs, signal: this.shutdown.signal }));
+        this.checkpoint();
+        // official 清单来源按配置同步（幂等；每个副本启动时都做）
+        await this.marketplaces.syncOfficialFromConfig();
+        // The bootstrap plugins (spec §7), once per manifest across replicas (the Redis lock
+        // `lock:bootstrap`); a bootstrap entry named like a config-declared extension is kept
+        if (opts.bootstrap !== undefined) {
+            this.registry.declare(await ExtensionHost.declaredNames(config.extensions, {
+                ...(opts.resolveFrom !== undefined && { resolveFrom: opts.resolveFrom }),
+            }));
+        }
+        const bootstrapAgain = opts.bootstrap !== undefined && (await this.runBootstrap(opts.bootstrap.dir));
+        this.checkpoint();
+        // 配置声明 → 安装记录（C15 / C13）。安装记录的包在本副本同步到 extensionHost.dir 后导入，
+        // 与运行中的 reconcile 走同一条路径；迁移由一个副本持锁执行（ensureMigrated，C16）
+        await this.host.load({
+            config: config.extensions,
+            installs: {
+                desired: () => this.installs.desired(),
+                sync: (d) => syncPackage(cfg().extensionHost.dir, d.name, d.sha256, this.blobs, {
+                    maxBytes: cfg().packages.maxBytes,
+                }),
+                migrate: async (d, dir, signal) => d.migratedSha === d.sha256
+                    ? "migrated"
+                    : ensureMigrated({
+                        db: this.kdb.db,
+                        dbUrl: config.db.url,
+                        connectTimeoutMs: config.db.connectTimeoutMs,
+                        bus: this.bus,
+                        log: this.log,
+                        // 宿主关闭时中止（运行中 reconcile 的迁移）；停机一开始就中止（启动加载中的迁移不等宿主关闭）
+                        signal: AbortSignal.any([signal, this.shutdown.signal]),
+                        timeoutMs: cfg().extensionHost.migrationTimeoutSeconds * 1000,
+                    }, d.name, d.sha256, dir),
+            },
+        });
+        this.checkpoint();
+        const sandboxEntry = this.host
+            .list("sandbox")
+            .find((x) => x.capability === SANDBOX_EXTENSION_POINT);
+        if (sandboxEntry !== undefined) {
+            for (const w of sandboxConfigWarnings(cfg(), sandboxEntry.plugin, sandboxEntry.impl)) {
+                this.log[w.level](w.message);
+            }
+        }
+        // The role parts (nest kernel spec §4): the worker role's queue consumers and schedules (the
+        // start gate: their timers are armed at application bootstrap, but no tick runs before the
+        // worker role opens the start gate here; the runOnStart jobs run then), the gateway role's
+        // supervisor and webhook inbound
+        if (worker)
+            await worker.start(() => this.checkpoint());
+        if (gateway)
+            await gateway.start(() => this.checkpoint());
+        // Routes stay mounted and are resolved live: 503 extension.unavailable after an extension is revoked, back after it reloads (C17)
+        this.http.mountPlugins(this.host.routeTable());
+        // 订阅插件生命周期主题后补一次 reconcile（启动加载期间错过的消息，并写下第一轮心跳）
+        await this.extensionLifecycle.start();
+        this.checkpoint();
+        await this.extensionLifecycle.reconcile("startup");
+        this.checkpoint();
+        if (bootstrapAgain && opts.bootstrap !== undefined) {
+            await this.runBootstrap(opts.bootstrap.dir, true);
+            this.checkpoint();
+        }
+        if (opts.source?.watch) {
+            // 热更新：重新校验；只应用 hot 字段，其余变化 warn 并列出需重启的键；校验失败保持原配置
+            this.unwatchConfig = opts.source.watch((raw) => this.configService.apply(raw), (err) => this.log.error("config watch error", { error: err.message }));
+        }
+    }
+    /**
+     * Listens on `port` (0.0.0.0; every role listens: worker-only serves only `/healthz` and
+     * `/readyz`) after the start sequence; returns the actual port.
+     */
+    async listen(port) {
+        // A shutdown already past the http phase must never open the port afterwards
+        this.checkpoint();
+        this.listenStarted = true;
+        // In flight for the stop: closing HTTP while it listens would leave the port open
+        this.listening = await this.shutdown.trackInFlight(this.http.listen(port));
+        this.checkpoint();
+        this.log.info("kernel started", { roles: this.config.roles, port: this.listening });
+        await this.warnIfSetupPending();
+        return this.listening;
+    }
+    /**
+     * Runs the bootstrap step unless it is done for the manifest. A required entry that cannot be
+     * completed (or a missing / tampered package: then nothing was installed) stops the start, so the
+     * kernel never serves without a required plugin. A failed optional entry is logged and returns
+     * true: the start runs the step once more after the extensions loaded (a declarative entry's
+     * catalog files need the object store, which on a fresh deployment is itself a bootstrap plugin),
+     * and the next start tries again while it stays incomplete.
+     */
+    async runBootstrap(dir, final = false) {
+        const manifest = this.options.bootstrapManifest ?? (await readBootstrapManifest());
+        const bootstrap = this.bootstrap;
+        if (await bootstrap.isDone(bootstrapManifestSha256(manifest)))
+            return false;
+        try {
+            // The second pass records what the first one did (not `kept` for what it installed)
+            await bootstrap.run({
+                manifest,
+                imports: this.pluginImport,
+                ...(dir !== undefined && { dir }),
+                signal: this.shutdown.signal,
+                ...(this.bootstrapCarry !== undefined && { carry: this.bootstrapCarry }),
+            });
+            return false;
+        }
+        catch (e) {
+            if (e instanceof BootstrapFailedError && !e.requiredFailed) {
+                this.bootstrapCarry = e.results;
+                if (final) {
+                    this.log.error("bootstrap: optional plugins could not be installed; retried on the next start", { failures: e.failures });
+                }
+                else {
+                    this.log.warn("bootstrap: optional plugins could not be installed yet; retried once the extensions have loaded", { failures: e.failures });
+                }
+                return true;
+            }
+            throw e;
+        }
+    }
+    /** 部署尚无活跃企业管理员时提示去初始化；查询失败只记日志，不影响启动。 */
+    async warnIfSetupPending() {
+        try {
+            if ((await this.accounts.countEnterpriseAdmins()) === 0) {
+                this.log.warn("deployment is not set up; open the setup wizard or run `capybara admin create`");
+            }
+        }
+        catch (e) {
+            this.log.warn("cannot check whether the deployment is set up", { error: errMsg(e) });
+        }
+    }
+    async beforeApplicationShutdown() {
+        await this.stop();
+    }
+    /** Logs the end of the stop phases (Redis and the pool close right after, in the infra modules). */
+    onApplicationShutdown() {
+        if (!this.onlyRelease)
+            this.log.info("kernel stopped");
+    }
+    /**
+     * Runs the stop phases once (idempotent): the shutdown begins at once (`GracefulShutdown.begin`:
+     * readiness answers 503, the start is aborted, the SSE streams close). Closing the application
+     * calls this from `beforeApplicationShutdown`; `closeKernelApp` (the tests, the signal handlers
+     * of `startKernelApp`) calls it directly next to `app.close()`, so the shutdown
+     * begins before any module's `onModuleDestroy` runs (Nest runs those first).
+     */
+    stop() {
+        this.shutdown.begin();
+        this.stopPromise ??= this.onlyRelease ? Promise.resolve() : this.runStopPhases();
+        return this.stopPromise;
+    }
+    async runStopPhases() {
+        const log = this.log;
+        const shutdown = this.shutdown;
+        /** Waits for p within `min(budgetMs, what is left of the total)`; a timeout warns and returns false. */
+        const within = async (label, p, budgetMs = Number.POSITIVE_INFINITY) => {
+            try {
+                const done = await waitWithin(p, Math.min(budgetMs, shutdown.remainingMs()));
+                if (!done)
+                    log.warn("shutdown step timed out", { step: label });
+                return done;
+            }
+            catch (e) {
+                log.error("shutdown step failed", { step: label, err: e });
+                return false;
+            }
+        };
+        // The start is not waited for (an extension setup can be arbitrarily slow): `begin()` aborted
+        // the start's kernel migration, whose session the migrate phase waits for (the in-flight work
+        // of the start sequence); the host close aborts extension migrations and closes the ctx of a
+        // setup in progress; the other start steps exit at their checkpoints. A listen in progress is
+        // waited for in the http phase (closing while listening would leave the port open).
+        // Extension requests in progress (SSE and other long requests end on req.signal) are aborted
+        // first, otherwise they would use up the http phase
+        this.httpApp?.abortPluginRequests();
+        // Scheduled jobs (worker role): no new tick, the runs in progress get the stop signal; awaited
+        // in the runs phase (before the extension host closes: a job may call an extension)
+        const { worker, gateway } = this;
+        const scheduledStopped = worker?.stopSchedules(STOP_BUDGET_MS.http + STOP_BUDGET_MS.runs);
+        if (!this.listenStarted)
+            await shutdown.drain(STOP_BUDGET_MS.migrate);
+        this.unwatchConfig?.();
+        this.unwatchConfig = undefined;
+        gateway?.unwatch();
+        await within("webhooks-unsubscribe", (gateway?.unsubscribe() ?? Promise.resolve()).catch(() => { }), 1_000);
+        // 不再接 reconcile（进行中的那次由宿主关闭收尾）
+        await within("plugin-lifecycle", this.extensionLifecycle.stop(), 1_000);
+        // http 阶段：等 listen 与关闭 HTTP 共用一个截止时间；listen 卡满预算时关闭只剩 0ms，直接强制断开
+        const httpDeadline = Date.now() + STOP_BUDGET_MS.http;
+        if (this.listenStarted)
+            await shutdown.drain(STOP_BUDGET_MS.http);
+        const http = this.httpApp;
+        if (http && !(await within("http", http.close(), Math.max(0, httpDeadline - Date.now())))) {
+            http.closeAllConnections();
+        }
+        this.listening = undefined;
+        // runs 阶段：停止领取运行、让本进程的运行在步骤边界停下并回到队列；再关闭运行队列的生产方连接。
+        // 渠道长连接与之并行停止（中止 connect、释放租约），必须在插件关闭之前。
+        const runsDeadline = Date.now() + STOP_BUDGET_MS.runs;
+        const channelsStopped = gateway?.stopSupervisor();
+        const runsBudget = Math.min(STOP_BUDGET_MS.runs, shutdown.remainingMs()) - RUNS_FORCE_CLOSE_MS;
+        const runsDrained = worker?.drainRuns(Math.max(0, runsBudget));
+        if (runsDrained)
+            await within("runs", runsDrained, STOP_BUDGET_MS.runs);
+        const evalsDrained = worker?.drainEvals(Math.max(0, runsDeadline - Date.now() - RUNS_FORCE_CLOSE_MS));
+        if (evalsDrained) {
+            await within("evals", evalsDrained, Math.max(0, runsDeadline - Date.now()));
+        }
+        if (channelsStopped) {
+            // 至少留 2s 交还租约：否则其他副本要等租约过期（默认 30s）才能接管
+            await within("channels", channelsStopped, Math.max(CHANNELS_STOP_MIN_MS, runsDeadline - Date.now()));
+        }
+        await within("scheduled-jobs", scheduledStopped ?? Promise.resolve(), Math.max(0, runsDeadline - Date.now()));
+        await within("maintenance", worker?.closeMaintenance() ?? Promise.resolve(), Math.max(0, runsDeadline - Date.now()));
+        // titles before usage.report: a finishing title call enqueues its usage report
+        await within("titles", this.titles.stop(), Math.max(0, runsDeadline - Date.now()));
+        // usage.report: in-flight deliveries are aborted and retried by any replica; before the plugins close
+        await within("usage-report", this.usageReport.stop(), Math.max(0, runsDeadline - Date.now()));
+        // 出站投递：进行中的任务交还队列（由其他副本从 last_seq 续投），必须在插件关闭之前
+        this.channelJobs.close();
+        await within("channel-outbound", this.channelOutbound.close(), Math.max(CHANNELS_STOP_MIN_MS, runsDeadline - Date.now()));
+        await within("plugins", this.host.close(), STOP_BUDGET_MS.plugins);
+        // 删掉本副本的加载状态行（尽力而为；崩溃副本心跳过期的行由 reconcile 清理）
+        await within("plugin-status", this.replicaStatus.removeAll(), 1_000);
+    }
+};
+KernelLifecycle = __decorate([
+    Injectable(),
+    __param(0, Inject(AccountsService)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Inject(KERNEL_APP_OPTIONS)),
+    __param(4, Inject(KERNEL_POOL)),
+    __param(5, Inject(REDIS)),
+    __param(6, Inject(KernelDb)),
+    __param(7, Inject(GracefulShutdown)),
+    __param(8, Inject(ExtensionHost)),
+    __param(9, Inject(ExtensionRegistry)),
+    __param(10, Inject(ExtensionInstalls)),
+    __param(11, Inject(ExtensionBlobs)),
+    __param(12, Inject(ExtensionLifecycle)),
+    __param(13, Inject(ReplicaStatusStore)),
+    __param(14, Inject(BootstrapService)),
+    __param(15, Inject(MarketplacesService)),
+    __param(16, Inject(PluginImport)),
+    __param(17, Inject(KERNEL_BUS)),
+    __param(18, Inject(UsageReporter)),
+    __param(19, Inject(TitleQueue)),
+    __param(20, Inject(ChannelJobs)),
+    __param(21, Inject(ChannelOutbound)),
+    __param(22, Optional()),
+    __param(22, Inject(WorkerRole)),
+    __param(23, Optional()),
+    __param(23, Inject(GatewayRole))
+], KernelLifecycle);
+export { KernelLifecycle };

package/dist/lifecycle/tokens.d.ts

@@ -0,0 +1,3 @@
+/** Injection tokens of the kernel application (`KernelModule`) itself. */
+/** The `KernelAppOptions` the application was built with. */
+export declare const KERNEL_APP_OPTIONS: unique symbol;

package/dist/lifecycle/tokens.js

@@ -0,0 +1,3 @@
+/** Injection tokens of the kernel application (`KernelModule`) itself. */
+/** The `KernelAppOptions` the application was built with. */
+export const KERNEL_APP_OPTIONS = Symbol("KERNEL_APP_OPTIONS");

package/dist/log-config.d.ts

@@ -0,0 +1,9 @@
+import type { KernelConfig } from "./config/schema.js";
+import { type KernelLogger, type LoggerOptions } from "./log.js";
+/**
+ * Logger options from the kernel config: the console format, `role` (the process's roles joined
+ * by `,`) on every record, and the Loki output when `log.loki.url` is set. `extra` overrides (tests).
+ */
+export declare function loggerOptionsFromConfig(config: KernelConfig, extra?: Partial<LoggerOptions>): LoggerOptions;
+/** The process logger as configured by `log.*` and `roles`. */
+export declare function createConfiguredLogger(config: KernelConfig): KernelLogger;

package/dist/log-config.js

@@ -0,0 +1,27 @@
+import { createLogger } from "./log.js";
+/**
+ * Logger options from the kernel config: the console format, `role` (the process's roles joined
+ * by `,`) on every record, and the Loki output when `log.loki.url` is set. `extra` overrides (tests).
+ */
+export function loggerOptionsFromConfig(config, extra = {}) {
+    const role = config.roles.join(",");
+    const { url, username, password, labels } = config.log.loki;
+    return {
+        format: config.log.format,
+        base: { role },
+        ...(url !== undefined && {
+            loki: {
+                url,
+                labels,
+                role,
+                ...(username !== undefined && { username }),
+                ...(password !== undefined && { password }),
+            },
+        }),
+        ...extra,
+    };
+}
+/** The process logger as configured by `log.*` and `roles`. */
+export function createConfiguredLogger(config) {
+    return createLogger(config.log.level, loggerOptionsFromConfig(config));
+}

package/dist/log-context.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Fields every log record written inside the current async context carries (`reqId` for an HTTP
+ * request, `queue` / `jobId` / `runId` for a queue job). Read by the logger's pino mixin; the
+ * context is per async call chain, never shared between requests.
+ */
+export type LogContext = Readonly<Record<string, string>>;
+/** A source of extra per-record fields, e.g. the active trace / span ids when tracing is on. */
+type ContextSource = () => Record<string, string> | undefined;
+/** The fields of the current context (plus the trace source's), or undefined outside any. */
+export declare function logContext(): LogContext | undefined;
+/**
+ * Registers the source of trace fields (`traceId` / `spanId`); set by the tracing bootstrap only
+ * when tracing is enabled, so the kernel never imports OpenTelemetry itself.
+ */
+export declare function setTraceContextSource(source: ContextSource | undefined): void;
+/** Runs `fn` with `fields` added to the current context (undefined values are skipped). */
+export declare function withLogContext<T>(fields: Record<string, string | undefined>, fn: () => T): T;
+/** Runs `fn` with no log context (a handler that must not carry its registrant's fields). */
+export declare function withoutLogContext<T>(fn: () => T): T;
+/** The part of a BullMQ job the context reads. */
+export interface ContextJob {
+    id?: string | undefined;
+    data?: unknown;
+}
+/** Hooks around every queue job (the tracing bootstrap wraps jobs in a span through this). */
+export type JobWrapper = <T>(queue: string, job: ContextJob, fn: () => Promise<T>) => Promise<T>;
+/** Registers a wrapper run around every job processor (tracing); undefined removes it. */
+export declare function setJobWrapper(wrapper: JobWrapper | undefined): void;
+/**
+ * Runs a queue job's processor with `queue`, `jobId` and, when the job data has one, `runId` in the
+ * log context (and inside the registered job wrapper, if any).
+ */
+export declare function withJobContext<T>(queue: string, job: ContextJob, fn: () => Promise<T>): Promise<T>;
+export {};

package/dist/log-context.js

@@ -0,0 +1,44 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+let traceSource;
+/** The fields of the current context (plus the trace source's), or undefined outside any. */
+export function logContext() {
+    const own = storage.getStore();
+    const trace = traceSource?.();
+    if (!trace)
+        return own;
+    return own ? { ...own, ...trace } : trace;
+}
+/**
+ * Registers the source of trace fields (`traceId` / `spanId`); set by the tracing bootstrap only
+ * when tracing is enabled, so the kernel never imports OpenTelemetry itself.
+ */
+export function setTraceContextSource(source) {
+    traceSource = source;
+}
+/** Runs `fn` with `fields` added to the current context (undefined values are skipped). */
+export function withLogContext(fields, fn) {
+    const next = { ...storage.getStore() };
+    for (const [k, v] of Object.entries(fields))
+        if (v !== undefined)
+            next[k] = v;
+    return storage.run(next, fn);
+}
+/** Runs `fn` with no log context (a handler that must not carry its registrant's fields). */
+export function withoutLogContext(fn) {
+    return storage.exit(fn);
+}
+let jobWrapper;
+/** Registers a wrapper run around every job processor (tracing); undefined removes it. */
+export function setJobWrapper(wrapper) {
+    jobWrapper = wrapper;
+}
+/**
+ * Runs a queue job's processor with `queue`, `jobId` and, when the job data has one, `runId` in the
+ * log context (and inside the registered job wrapper, if any).
+ */
+export function withJobContext(queue, job, fn) {
+    const data = job.data;
+    const runId = typeof data?.runId === "string" ? data.runId : undefined;
+    return withLogContext({ queue, jobId: job.id, runId }, () => jobWrapper ? jobWrapper(queue, job, fn) : fn());
+}

package/dist/log-loki.d.ts

@@ -0,0 +1,34 @@
+/** Loki output of the kernel logger (`log.loki.*`). */
+export interface LokiOptions {
+    /** Loki base URL (`http://loki:3100`) or the full push URL (`…/loki/api/v1/push`). */
+    url: string;
+    username?: string;
+    password?: string;
+    /** Extra stream labels; `role` and `level` are always the record's own. */
+    labels: Record<string, string>;
+    /** The `role` label: the process's roles joined by `,`. */
+    role: string;
+    /** Push interval in ms; default 2000. */
+    intervalMs?: number;
+    /** Records kept while Loki is slow or down; the oldest are dropped beyond it. Default 10000. */
+    maxBuffer?: number;
+    /** Where push failures are reported (at most once per minute); default stderr. */
+    onError?: (message: string) => void;
+    /** Clock for the error rate limit (tests). */
+    now?: () => number;
+}
+/** A pino destination that batches records and pushes them to Loki. */
+export interface LokiStream {
+    write(line: string): void;
+    /** Pushes everything buffered (waits for a push in flight first). Never rejects. */
+    flush(): Promise<void>;
+    /** Flushes and stops the interval. */
+    close(): Promise<void>;
+}
+/**
+ * Batches JSON log lines and POSTs them to Loki's push API (JSON body), one stream per level with
+ * the labels `{ job: "capybara", ...labels, role, level }`. Pushing never blocks or throws into the
+ * caller: a failed push drops its batch and is reported to `onError` at most once per minute; while
+ * Loki is down at most `maxBuffer` records are kept. The interval timer is unref'd.
+ */
+export declare function createLokiStream(opts: LokiOptions): LokiStream;