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

package/dist/index.d.ts

@@ -28,7 +28,7 @@ export { ExtensionAdminOps, type ExtensionAdminOpsDeps } from "./extensions/admi
 export { ExtensionAdmin, PLUGINS_CHANGED_TOPIC } from "./extensions/admin-view.js";
 export { type ApprovalDecision, ExtensionApprovals, type PendingExtension, type PermissionSnapshot, planApprovals, snapshotCovers, withPreApproved, } from "./extensions/approvals.js";
 export { blobKey, ExtensionBlobIntegrityError, type ExtensionBlobSource, ExtensionBlobs, } from "./extensions/blobs.js";
-export { BOOTSTRAP_MANIFEST_FILE, type BootstrapEntryResult, BootstrapFailedError, type BootstrapFailure, type BootstrapResult, BootstrapService, type BootstrapServiceDeps, bootstrapManifestSha256, readBootstrapManifest, } from "./extensions/bootstrap.js";
+export { BOOTSTRAP_MANIFEST_FILE, type BootstrapEntryResult, BootstrapFailedError, type BootstrapFailure, type BootstrapResolveOptions, type BootstrapResult, BootstrapService, type BootstrapServiceDeps, 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 { assertSecretsReachable, ExtensionHost, type ExtensionLoadPlan, type InspectedExtension, type InstalledExtensionLoader, type InstallFailureReason, } from "./extensions/host.js";
@@ -53,7 +53,9 @@ export { DUMMY_PASSWORD_HASH, hashPassword, verifyPassword } from "./identity/pa
 export { type IssuedSession, REFRESH_RACE_GRACE_MS, SessionService, } from "./identity/sessions.js";
 export { DEPLOYMENT_SETTINGS, type DeploymentSettings, SettingsService, } from "./identity/settings.js";
 export { createKernel, KERNEL_MIGRATIONS_DIR, KERNEL_SCHEMA, type Kernel, type KernelOptions, type KernelRuns, migrateAll, } from "./kernel.js";
-export { createLogger, type KernelLogger, LOG_LEVELS, type LogLevel } from "./log.js";
+export { createLogger, type KernelLogger, LOG_FORMATS, LOG_LEVELS, type LogFormat, type LoggerOptions, type LogLevel, type LogOutput, } from "./log.js";
+export { createConfiguredLogger, loggerOptionsFromConfig } from "./log-config.js";
+export { type ContextJob, type JobWrapper, type LogContext, logContext, setJobWrapper, setTraceContextSource, withJobContext, withLogContext, } from "./log-context.js";
 export { type Org, OrgsService } from "./orgs/orgs.service.js";
 export { fetchNpmPackage, IntegrityMismatchError, type NpmFetchConfig, NpmFetchError, PackageTooLargeError, } from "./packages/npm.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";

package/dist/index.js

@@ -27,7 +27,7 @@ export { ExtensionAdminOps } from "./extensions/admin-ops.js";
 export { ExtensionAdmin, PLUGINS_CHANGED_TOPIC } from "./extensions/admin-view.js";
 export { ExtensionApprovals, planApprovals, snapshotCovers, withPreApproved, } from "./extensions/approvals.js";
 export { blobKey, ExtensionBlobIntegrityError, ExtensionBlobs, } from "./extensions/blobs.js";
-export { BOOTSTRAP_MANIFEST_FILE, BootstrapFailedError, BootstrapService, bootstrapManifestSha256, readBootstrapManifest, } from "./extensions/bootstrap.js";
+export { BOOTSTRAP_MANIFEST_FILE, BootstrapFailedError, BootstrapService, bootstrapManifestSha256, readBootstrapManifest, resolveBootstrapPackages, } from "./extensions/bootstrap.js";
 export { openExtensionCli } from "./extensions/cli.js";
 export { DEPLOYMENT_SECRETS_ORG, ExtensionDeploymentConfigService, mergeDeploymentConfig, PLUGIN_DEPLOYMENT_CONFIG_TOPIC, readStoredDeploymentConfig, } from "./extensions/deployment-config.js";
 export { assertSecretsReachable, ExtensionHost, } from "./extensions/host.js";
@@ -52,7 +52,9 @@ export { DUMMY_PASSWORD_HASH, hashPassword, verifyPassword } from "./identity/pa
 export { REFRESH_RACE_GRACE_MS, SessionService, } from "./identity/sessions.js";
 export { DEPLOYMENT_SETTINGS, SettingsService, } from "./identity/settings.js";
 export { createKernel, KERNEL_MIGRATIONS_DIR, KERNEL_SCHEMA, migrateAll, } from "./kernel.js";
-export { createLogger, LOG_LEVELS } from "./log.js";
+export { createLogger, LOG_FORMATS, LOG_LEVELS, } from "./log.js";
+export { createConfiguredLogger, loggerOptionsFromConfig } from "./log-config.js";
+export { logContext, setJobWrapper, setTraceContextSource, withJobContext, withLogContext, } from "./log-context.js";
 export { OrgsService } from "./orgs/orgs.service.js";
 export { fetchNpmPackage, IntegrityMismatchError, NpmFetchError, PackageTooLargeError, } from "./packages/npm.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";

package/dist/kernel.d.ts

@@ -25,7 +25,7 @@ import { type KernelHttp } from "./http/app.js";
 import { IdentityBinding } from "./identity/binding.js";
 import { ExternalIdentities } from "./identity/external.js";
 import { SsoFlow } from "./identity/sso.js";
-import { type KernelLogger } from "./log.js";
+import type { KernelLogger } from "./log.js";
 import { PricesService } from "./models/prices.js";
 import { ModelPurposesService } from "./models/purposes.js";
 import { DirectorySync } from "./orgs/directory-sync.js";
@@ -153,7 +153,7 @@ export interface Kernel {
     readonly catalog: CatalogService;
     /** Enterprise import of plugins (plugin tgz files): prepare / confirm and staging cleanup. */
     readonly pluginImport: PluginImport;
-    /** The bootstrap step (package ecosystem spec §7); `start()` runs it when given `bootstrapDir`. */
+    /** The bootstrap step (package ecosystem spec §7); `start()` runs it when given `bootstrap`. */
     readonly bootstrap: BootstrapService;
     /** Marketplaces: official / enterprise marketplaces and their refresh. */
     readonly marketplaces: MarketplacesService;
@@ -209,7 +209,7 @@ export interface KernelOptions {
     source?: ConfigSource;
     /** 解析插件裸包名的目录，默认 `process.cwd()`；相对路径按当前 cwd 解析。 */
     resolveFrom?: string;
-    /** 默认按 `config.log.level` 新建 JSON logger。 */
+    /** Defaults to a logger built from `config.log` and `config.roles` (createConfiguredLogger). */
     logger?: KernelLogger;
     /** 热更新时与来源原始值合并的环境变量，默认 `process.env`。 */
     env?: NodeJS.ProcessEnv;
@@ -223,13 +223,16 @@ export interface KernelOptions {
     /** 评测整轮回放的测试钩子。 */
     evalHooks?: EvalReplayHooks;
     /**
-     * The directory holding the bootstrap packages (`<name>-<version>.tgz`, baked into the image;
-     * package ecosystem spec §7). When given, `start()` runs the bootstrap step (see
-     * `extensions/bootstrap.ts`) before loading extensions unless it is already done for the
-     * manifest, and refuses to start when it cannot complete a required entry. Omitted: no bootstrap
-     * step (tests, or a deployment whose init container ran `capybara bootstrap`).
+     * The bootstrap step (package ecosystem spec §7, startup bootstrap spec). When given, `start()`
+     * runs it (see `extensions/bootstrap.ts`) before loading extensions unless it is already done for
+     * the manifest, and refuses to start when it cannot complete a required entry. `dir`: the
+     * optional offline directory whose `*.tgz` files are matched to the entries by sha512 (a missing
+     * directory is an empty one); entries without a matching file are downloaded from
+     * `packages.npmRegistry`. Omitted: no bootstrap step (tests, unless they ask for it).
      */
-    bootstrapDir?: string;
+    bootstrap?: {
+        dir?: string;
+    };
     /** The bootstrap manifest; default the `bootstrap.json` shipped with the kernel package. */
     bootstrapManifest?: BootstrapManifest;
     /**

package/dist/kernel.js

@@ -47,7 +47,7 @@ import { ExternalIdentities } from "./identity/external.js";
 import { SessionService } from "./identity/sessions.js";
 import { SettingsService } from "./identity/settings.js";
 import { SsoFlow } from "./identity/sso.js";
-import { createLogger } from "./log.js";
+import { createConfiguredLogger } from "./log-config.js";
 import { PricesService } from "./models/prices.js";
 import { ModelPurposesService } from "./models/purposes.js";
 import { DirectorySync } from "./orgs/directory-sync.js";
@@ -168,7 +168,7 @@ export async function createKernel(config, opts = {}) {
             throw new Error(`config field ${p} is marked hot but has no applier`);
     }
     const env = opts.env ?? process.env;
-    const log = opts.logger ?? createLogger(config.log.level);
+    const log = opts.logger ?? createConfiguredLogger(config);
     log.setLevel(config.log.level);
     log.addSecrets(secretValues(KernelConfigSchema, config));
     let current = config;
@@ -375,7 +375,7 @@ export async function createKernel(config, opts = {}) {
             // The second pass records what the first one did (not `kept` for what it installed)
             await bootstrap.run({
                 manifest,
-                dir,
+                ...(dir !== undefined && { dir }),
                 signal: startAbort.signal,
                 ...(bootstrapCarry !== undefined && { carry: bootstrapCarry }),
             });
@@ -1133,12 +1133,12 @@ export async function createKernel(config, opts = {}) {
                 // official 清单来源按配置同步（幂等；每个副本启动时都做）
                 await marketplaces.syncOfficialFromConfig();
                 // The bootstrap plugins (spec §7), once per manifest across replicas (advisory lock)
-                if (opts.bootstrapDir !== undefined) {
+                if (opts.bootstrap !== undefined) {
                     configDeclared = await ExtensionHost.declaredNames(config.extensions, {
                         ...(opts.resolveFrom !== undefined && { resolveFrom: opts.resolveFrom }),
                     });
                 }
-                const bootstrapAgain = opts.bootstrapDir !== undefined && (await runBootstrap(opts.bootstrapDir));
+                const bootstrapAgain = opts.bootstrap !== undefined && (await runBootstrap(opts.bootstrap.dir));
                 checkpoint();
                 // 配置声明 → 安装记录（C15 / C13）。安装记录的包在本副本同步到 extensionHost.dir 后导入，
                 // 与运行中的 reconcile 走同一条路径；迁移由一个副本持锁执行（ensureMigrated，C16）
@@ -1291,8 +1291,8 @@ export async function createKernel(config, opts = {}) {
                 checkpoint();
                 await extensionLifecycle.reconcile("startup");
                 checkpoint();
-                if (bootstrapAgain && opts.bootstrapDir !== undefined) {
-                    await runBootstrap(opts.bootstrapDir, true);
+                if (bootstrapAgain && opts.bootstrap !== undefined) {
+                    await runBootstrap(opts.bootstrap.dir, true);
                     checkpoint();
                 }
                 if (opts.source?.watch) {

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,32 @@
+/**
+ * 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;
+/** 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,40 @@
+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);
+}
+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;

package/dist/log-loki.js

@@ -0,0 +1,145 @@
+const PUSH_PATH = "/loki/api/v1/push";
+const PUSH_TIMEOUT_MS = 10_000;
+/** A batch is pushed right away once it reaches this many records. */
+const BATCH_SIZE = 1_000;
+const ERROR_NOTE_INTERVAL_MS = 60_000;
+function pushUrl(url) {
+    const u = new URL(url);
+    if (!u.pathname.endsWith(PUSH_PATH))
+        u.pathname = `${u.pathname.replace(/\/+$/, "")}${PUSH_PATH}`;
+    return u;
+}
+/**
+ * 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 function createLokiStream(opts) {
+    const url = pushUrl(opts.url);
+    const intervalMs = opts.intervalMs ?? 2_000;
+    const maxBuffer = opts.maxBuffer ?? 10_000;
+    const now = opts.now ?? Date.now;
+    const onError = opts.onError ?? ((m) => void process.stderr.write(`capybara: ${m}\n`));
+    // the marker keeps these pushes out of HTTP client traces (apps/capybara tracing.ts)
+    const headers = {
+        "content-type": "application/json",
+        "x-capybara-log-push": "1",
+    };
+    if (opts.username !== undefined || opts.password !== undefined) {
+        const token = Buffer.from(`${opts.username ?? ""}:${opts.password ?? ""}`).toString("base64");
+        headers.authorization = `Basic ${token}`;
+    }
+    const baseLabels = { job: "capybara", ...opts.labels, role: opts.role };
+    let buffer = [];
+    let dropped = 0;
+    let inFlight;
+    let timer;
+    let lastNote = Number.NEGATIVE_INFINITY;
+    let closed = false;
+    /** Reports at most once a minute; `message` names the Loki origin only (a URL may carry credentials). */
+    const report = (message) => {
+        const t = now();
+        if (t - lastNote < ERROR_NOTE_INTERVAL_MS)
+            return;
+        lastNote = t;
+        onError(`${message}; further Loki errors are not reported for a minute`);
+    };
+    const note = (reason) => report(`cannot push logs to Loki at ${url.origin} (${reason}); records are dropped until it recovers`);
+    const pushBatch = async (batch, lost) => {
+        const streams = new Map();
+        for (const e of batch) {
+            const values = streams.get(e.level) ?? [];
+            values.push([e.ns, e.line]);
+            streams.set(e.level, values);
+        }
+        const body = JSON.stringify({
+            streams: [...streams].map(([level, values]) => ({
+                stream: { ...baseLabels, level },
+                values,
+            })),
+        });
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers,
+                body,
+                signal: AbortSignal.timeout(PUSH_TIMEOUT_MS),
+            });
+            await res.body?.cancel();
+            if (!res.ok)
+                note(`HTTP ${res.status}`);
+            else if (lost > 0) {
+                report(`${lost} log records for Loki at ${url.origin} were dropped: the buffer was full`);
+            }
+        }
+        catch (e) {
+            note(e instanceof Error ? (e.cause instanceof Error ? e.cause.message : e.message) : "error");
+        }
+    };
+    /** Starts a push of the current buffer unless one is in flight. */
+    const kick = () => {
+        if (inFlight || buffer.length === 0)
+            return inFlight ?? Promise.resolve();
+        const batch = buffer;
+        const lost = dropped;
+        buffer = [];
+        dropped = 0;
+        inFlight = pushBatch(batch, lost).finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+    const ensureTimer = () => {
+        if (timer || closed)
+            return;
+        timer = setInterval(() => void kick(), intervalMs);
+        timer.unref();
+    };
+    return {
+        write(chunk) {
+            for (const line of chunk.split("\n")) {
+                if (line === "")
+                    continue;
+                let level = "info";
+                let ms = Date.now();
+                try {
+                    const rec = JSON.parse(line);
+                    if (typeof rec.level === "string")
+                        level = rec.level;
+                    if (typeof rec.time === "string") {
+                        const t = Date.parse(rec.time);
+                        if (!Number.isNaN(t))
+                            ms = t;
+                    }
+                }
+                catch {
+                    // not JSON: push it as is
+                }
+                buffer.push({ level, ns: `${BigInt(ms) * 1000000n}`, line });
+                if (buffer.length > maxBuffer) {
+                    buffer.shift();
+                    dropped++;
+                }
+            }
+            ensureTimer();
+            if (buffer.length >= BATCH_SIZE)
+                void kick();
+        },
+        async flush() {
+            while (inFlight || buffer.length > 0) {
+                if (inFlight)
+                    await inFlight;
+                else
+                    await kick();
+            }
+        },
+        async close() {
+            closed = true;
+            if (timer)
+                clearInterval(timer);
+            timer = undefined;
+            await this.flush();
+        },
+    };
+}

package/dist/log.d.ts

@@ -1,4 +1,5 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type LokiOptions } from "./log-loki.js";
 /** 日志级别，按严重程度递增。 */
 export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
 /** 日志级别。 */
@@ -11,7 +12,7 @@ export interface KernelLogger extends Logger {
     setLevel(level: string): void;
     /**
      * 登记部署方（运维）给的密钥值：内核配置与插件部署级配置里的 secret 字段。此后日志消息与字段里出现这些值都替换为
-     * `[REDACTED]`（顶层的 `ts` / `level` 不打码）。字符串与数字（转成字符串）登记，布尔不登记；
+     * `[REDACTED]`（顶层的 `time` / `level` 不打码）。字符串与数字（转成字符串）登记，布尔不登记；
      * 数组与对象递归展开其中的标量；短于 4 个字符的值不登记（会误伤普通文本）。
      * 数值字段的字符串形式等于已登记值时同样打码。
      */
@@ -27,6 +28,8 @@ export interface KernelLogger extends Logger {
      * 报错说明）之前用。
      */
     redact(text: string): string;
+    /** Waits until buffered records reached every output (Loki); never rejects. Call before exit. */
+    flush(): Promise<void>;
 }
 /**
  * 用与 logger 相同的匹配器打码任意文本（工具结果等不经过日志的内容用）：展开规则同 `addOrgSecrets`
@@ -34,15 +37,43 @@ export interface KernelLogger extends Logger {
  * 不得小于匹配器的分桶前缀长度 4）。没有可用的值时原样返回。
  */
 export declare function createRedactor(values: readonly unknown[], minLength?: number): (s: string) => string;
-/**
- * 创建结构化 JSON logger：每条日志写一行 `{ ts, level, msg, ...fields }`。
- * 字段不能覆盖 ts / level / msg；Error 序列化为 name / message / stack；
- * 经 `addSecrets` 登记的部署方密钥在消息与字段的任何字符串里都被打码；经 `addOrgSecrets` 登记的组织来源密钥
- * 只在字段里打码，不动顶层 msg；顶层 ts / level 从不打码。
- * `opts.orgSecretCapacity` 为组织来源密钥集合的容量（测试用）；`opts.onMatcherBuild` 在每次重建匹配器时调用（测试用）。
- */
-export declare function createLogger(level?: string, opts?: {
+/** Console format: `pretty` (pino-pretty, one line per record), `json`, or `auto` (pretty on a TTY). */
+export declare const LOG_FORMATS: readonly ["auto", "pretty", "json"];
+/** Console format. */
+export type LogFormat = (typeof LOG_FORMATS)[number];
+/** A minimal writable the console output goes to (`process.stdout` by default). */
+export interface LogOutput {
+    write(chunk: string): unknown;
+}
+/** Options of {@link createLogger}. */
+export interface LoggerOptions {
+    /**
+     * Receives every record as one JSON line (no trailing newline) instead of the console; the
+     * console format is ignored. Used by tests and embedders that collect records themselves.
+     */
     write?: (line: string) => void;
+    /** Console format; default `auto`. */
+    format?: LogFormat;
+    /** Console stream; default `process.stdout`. */
+    out?: LogOutput;
+    /** Whether the console is a terminal (picks `auto` and colors); default `process.stdout.isTTY`. */
+    isTTY?: boolean;
+    /** Also push every record to Loki. */
+    loki?: LokiOptions;
+    /** Fields on every record (e.g. `role`); log calls cannot overwrite them. */
+    base?: Record<string, string>;
+    /** Capacity of the org secret set (tests). */
     orgSecretCapacity?: number;
+    /** Called on every matcher rebuild (tests). */
     onMatcherBuild?: () => void;
-}): KernelLogger;
+}
+/**
+ * Creates the kernel logger on pino. Each record is `{ time, level, msg, ...base, ...fields }` with
+ * `level` the label and `time` ISO 8601; fields cannot overwrite time / level / msg or the base
+ * fields; an Error becomes name / message / stack (and cause). Redaction happens before pino, so
+ * every output sees the same redacted record: deployment secrets (`addSecrets`) in msg and every
+ * field string, org secrets (`addOrgSecrets`) in fields only; level and time are never redacted.
+ * The console gets pino-pretty or JSON lines per `opts.format`; `opts.write` replaces the console
+ * with a JSON line sink.
+ */
+export declare function createLogger(level?: string, opts?: LoggerOptions): KernelLogger;