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

package/bootstrap.json

@@ -1,21 +1,25 @@
 {
   "$schema": "https://capybarahq.com/schemas/bootstrap.v1.schema.json",
   "schemaVersion": 1,
+  "marketplace": {
+    "url": "https://github.com/capybara-hq/plugins.git",
+    "commit": "08e336dafe124615622534683887120c81ec416b"
+  },
   "plugins": [
     {
       "name": "openai-compatible",
-      "source": "workspace",
-      "path": "plugins/openai-compatible",
+      "source": "npm",
+      "npm": "@capybara-hq/plugin-openai-compatible",
       "version": "0.1.0-rc.0",
-      "integrity": "sha512-LSPFl9BK9xLShBzfUBu0NZvSG/0JyE2tJL2Hrv3QEdCFxmU4xPy1SlvKtzOEanftSuTR5eEVX13VvVYXrpo7Mw==",
+      "integrity": "sha512-NYyjRfC2U6bAjjlFU0rmJuDs3IyuAwektV9KLBpnFcDVRDfRgBpcSBV/jp0tzXhv9ee5MWqzOKN20WNdKWO9fQ==",
       "required": true
     },
     {
       "name": "object-store-s3",
-      "source": "workspace",
-      "path": "plugins/object-store-s3",
+      "source": "npm",
+      "npm": "@capybara-hq/plugin-object-store-s3",
       "version": "0.1.0-rc.0",
-      "integrity": "sha512-8vYvq0EyrEfvJwgx67nSEbFW9rnO+uaP/gtL6Esqh3I1XEJEmMJnSH0LgcsD5zFQRiDe/ND0Ij3EnWBWVTr0UQ==",
+      "integrity": "sha512-jFbstLMsMeZ3EqGEm/5OnYWm4aGM9nIw71DmIuPu/frk4/Y+nTnaBWgT1SUDEr6NbFb34V31NIVNMJSoxmvMww==",
       "required": true
     }
   ]

package/dist/channels/outbound.js

@@ -4,6 +4,7 @@ import { DelayedError, Queue, UnrecoverableError, Worker } from "bullmq";
 import { sql } from "kysely";
 import { conversationTopic, } from "../conversations/event-log.js";
 import { ApiError } from "../errors.js";
+import { withJobContext } from "../log-context.js";
 import { readOrgSettings } from "../orgs/settings.service.js";
 import { ConversationLock } from "../runtime/conversation-lock.js";
 import { bullConnection } from "../runtime/run-queue.js";
@@ -206,7 +207,7 @@ export class ChannelOutbound {
             return;
         const { jobLockMs, stalledIntervalMs } = this.d.config().runtime;
         this.workerConn = bullConnection(this.d.redisUrl, this.d.log);
-        this.worker = new Worker(CHANNEL_QUEUE_NAME, (job, token) => this.process(job, token), {
+        this.worker = new Worker(CHANNEL_QUEUE_NAME, (job, token) => withJobContext(CHANNEL_QUEUE_NAME, job, () => this.process(job, token)), {
             connection: this.workerConn,
             concurrency: this.d.config().channels.deliveryConcurrency,
             lockDuration: jobLockMs,

package/dist/config/schema.d.ts

@@ -72,6 +72,9 @@ export declare const KernelConfigSchema: z.ZodObject<{
         npmToken: z.ZodOptional<z.ZodString>;
         maxBytes: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    bootstrap: z.ZodPrefault<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
     catalog: z.ZodPrefault<z.ZodObject<{
         staleInstallMinutes: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
@@ -211,13 +214,24 @@ export declare const KernelConfigSchema: z.ZodObject<{
         usageReportConcurrency: z.ZodDefault<z.ZodNumber>;
         usageReportKeepHours: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
-    log: z.ZodDefault<z.ZodObject<{
+    log: z.ZodPrefault<z.ZodObject<{
         level: z.ZodDefault<z.ZodEnum<{
             debug: "debug";
             error: "error";
             info: "info";
             warn: "warn";
         }>>;
+        format: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            json: "json";
+            pretty: "pretty";
+        }>>;
+        loki: z.ZodPrefault<z.ZodObject<{
+            url: z.ZodOptional<z.ZodURL>;
+            username: z.ZodOptional<z.ZodString>;
+            password: z.ZodOptional<z.ZodString>;
+            labels: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type KernelConfig = z.infer<typeof KernelConfigSchema>;

package/dist/config/schema.js

@@ -1,7 +1,7 @@
 import { isIP } from "node:net";
 import { DOCUMENT_MEDIA_TYPES, IMAGE_MEDIA_TYPES, validateAllowHost, } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
-import { LOG_LEVELS } from "../log.js";
+import { LOG_FORMATS, LOG_LEVELS } from "../log.js";
 import { noProxyEntryProblem, proxyUrlProblem } from "../net/proxy.js";
 import { privateHostEntryProblem } from "../net/public-address.js";
 /**
@@ -277,6 +277,17 @@ export const KernelConfigSchema = z.object({
         })),
     })
         .prefault({}),
+    bootstrap: z
+        .object({
+        dir: z
+            .string()
+            .min(1)
+            .default("bootstrap")
+            .meta(meta({
+            description: "Offline directory for the bootstrap plugins, resolved against the working directory (/app/bootstrap in the image): a .tgz file here whose sha512 matches a pinned plugin is installed instead of downloading it from packages.npmRegistry",
+        })),
+    })
+        .prefault({}),
     catalog: z
         .object({
         staleInstallMinutes: z
@@ -936,7 +947,7 @@ export const KernelConfigSchema = z.object({
             .min(1)
             .default("capybara-sandbox:latest")
             .meta(meta({
-            description: "Image for conversation sandboxes, used by the Docker sandbox extension (built from plugins/sandbox-docker/image/Dockerfile; pre-pull it on every Docker node). The E2B extension ignores it and uses its own template setting",
+            description: "Image for conversation sandboxes, used by the Docker sandbox extension (built from plugins/sandbox-docker/image of capybara-hq/plugins, e.g. by the compose sandbox profile; pre-pull it on every Docker node). The E2B extension ignores it and uses its own template setting",
         })),
         lockWaitSeconds: z
             .number()
@@ -1146,6 +1157,36 @@ export const KernelConfigSchema = z.object({
             .enum(LOG_LEVELS)
             .default("info")
             .meta(meta({ hot: true, description: "Log level" })),
+        format: z
+            .enum(LOG_FORMATS)
+            .default("auto")
+            .meta(meta({
+            description: "Console log format: pretty (one readable line per record, colored on a terminal), json (one JSON line per record) or auto (pretty when stdout is a terminal, else json, so containers log JSON)",
+        })),
+        loki: z
+            .object({
+            url: z
+                .url({ protocol: /^https?$/ })
+                .optional()
+                .meta(meta({
+                description: "Loki base URL (e.g. http://loki:3100) or its full push URL; when set, every log record is also pushed there (batched, JSON lines). Unset: nothing is sent",
+            })),
+            username: z
+                .string()
+                .optional()
+                .meta(meta({ description: "Loki basic auth user name" })),
+            password: z
+                .string()
+                .optional()
+                .meta(meta({ secret: true, description: "Loki basic auth password" })),
+            labels: z
+                .record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.string())
+                .default({})
+                .meta(meta({
+                description: 'Extra Loki stream labels, e.g. {"env":"prod"}; every stream also has job (capybara unless set here), role (the process\'s roles) and level',
+            })),
+        })
+            .prefault({}),
     })
-        .default({ level: "info" }),
+        .prefault({}),
 });

package/dist/conversations/titles.js

@@ -2,6 +2,7 @@ import { isModelError, } from "@capybara-hq/plugin-sdk";
 import { Queue, Worker } from "bullmq";
 import { sql } from "kysely";
 import { audit } from "../identity/audit.js";
+import { withJobContext } from "../log-context.js";
 import { PurposeAttemptError } from "../models/purposes.js";
 import { fireObserve, hookDeniedAudit, hookDeniedEvent, hookRequestOf, } from "../runtime/hook-calls.js";
 import { bullConnection } from "../runtime/run-queue.js";
@@ -383,7 +384,7 @@ export class TitleQueue {
             return;
         const { jobLockMs, stalledIntervalMs } = this.d.config().runtime;
         this.workerConn = bullConnection(this.d.redisUrl, this.d.log);
-        this.worker = new Worker(TITLE_QUEUE, (j) => this.process(j), {
+        this.worker = new Worker(TITLE_QUEUE, (j) => withJobContext(TITLE_QUEUE, j, () => this.process(j)), {
             connection: this.workerConn,
             concurrency: 4,
             lockDuration: jobLockMs,

package/dist/ctx/queue.js

@@ -1,5 +1,6 @@
 import { Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
+import { withJobContext } from "../log-context.js";
 import { assertNamespace } from "./namespace.js";
 /** 未注入 logger 时的兜底：输出到 stderr。 */
 const consoleLog = {
@@ -60,7 +61,7 @@ export function createQueue(redisUrl, namespace, opts) {
                 return;
             const st = { n: 0, idle: [] };
             active.set(name, st);
-            const worker = new Worker(queueName(name), async (job) => {
+            const worker = new Worker(queueName(name), (job) => withJobContext(queueName(name), job, async () => {
                 st.n += 1;
                 try {
                     await handler(job.data);
@@ -71,7 +72,7 @@ export function createQueue(redisUrl, namespace, opts) {
                         for (const w of st.idle.splice(0))
                             w();
                 }
-            }, 
+            }), 
             // 撤销插件实例时到点仍未完成的任务被强制留在队列里（锁过期后按 stalled 交回），新实例再执行一次：
             // 任务是至少一次。stalled 次数放宽到 3，连续几次撤销 / 升级不至于把任务判为失败
             { connection: newConn(), concurrency: o?.concurrency ?? 1, maxStalledCount: 3 });

package/dist/errors.d.ts

@@ -61,6 +61,7 @@ export declare const ERROR_CODES: {
     readonly "extension.not_disabled": 409;
     readonly "packages.npm_failed": 502;
     readonly "bootstrap.integrity_mismatch": 500;
+    readonly "bootstrap.download_failed": 502;
     readonly "bootstrap.missing_file": 500;
     readonly "catalog.invalid_manifest": 422;
     readonly "catalog.legacy_format": 422;

package/dist/errors.js

@@ -61,6 +61,7 @@ export const ERROR_CODES = {
     "extension.not_disabled": 409,
     "packages.npm_failed": 502,
     "bootstrap.integrity_mismatch": 500,
+    "bootstrap.download_failed": 502,
     "bootstrap.missing_file": 500,
     "catalog.invalid_manifest": 422,
     "catalog.legacy_format": 422,

package/dist/evals/worker.js

@@ -6,6 +6,7 @@ import { sql } from "kysely";
 import { loadTemplates } from "../agents/templates.js";
 import { ApiError } from "../errors.js";
 import { ExtensionUnloadedError } from "../extensions/inflight.js";
+import { withJobContext } from "../log-context.js";
 import { PurposeAttemptError } from "../models/purposes.js";
 import { MediaUnavailableError, RunError } from "../runtime/model-call.js";
 import { ProviderListError } from "../runtime/providers.js";
@@ -149,7 +150,7 @@ export class EvalWorker {
             return;
         const { runtime, evals } = this.d.config();
         this.conn = bullConnection(this.d.redisUrl, this.d.log);
-        this.worker = new Worker(EVAL_QUEUE_NAME, (job, token) => this.process(job, token), {
+        this.worker = new Worker(EVAL_QUEUE_NAME, (job, token) => withJobContext(EVAL_QUEUE_NAME, job, () => this.process(job, token)), {
             name: `${hostname()}-${process.pid}`,
             connection: this.conn,
             concurrency: evals.workerConcurrency,

package/dist/extensions/bootstrap.d.ts

@@ -2,18 +2,25 @@ import { type BootstrapManifest, type Logger } from "@capybara-hq/plugin-sdk";
 import { type PluginImport } from "../catalog/plugin-import.js";
 import type { KernelConfig } from "../config/schema.js";
 import type { KernelDb } from "../db/kernel-schema.js";
+import { fetchNpmPackage } from "../packages/npm.js";
 import type { ExtensionAdminOps } from "./admin-ops.js";
 import type { ExtensionInstalls } from "./installs.js";
 import type { ExtensionSource } from "./sources.js";
 /**
- * The bootstrap step (package ecosystem spec §7): installs the plugins pinned by the bootstrap
- * manifest (`packages/kernel/bootstrap.json`) from the tgz files baked into the image. It replaced
- * the builtin extensions.
+ * The bootstrap step (package ecosystem spec §7, startup bootstrap spec): installs the plugins
+ * pinned by the bootstrap manifest (`packages/kernel/bootstrap.json`). It replaced the builtin
+ * extensions.
  *
- * - Every file (`<dir>/<name>-<version>.tgz`) is checked against the entry's sha512 before anything
- *   is read or written; a missing file is `bootstrap.missing_file`, a mismatch
- *   `bootstrap.integrity_mismatch` (both name the plugin), and then nothing is written. It never
- *   touches the network.
+ * - When the run is already done for the manifest nothing is read: no directory, no network, so a
+ *   restart of an installed deployment never needs npm.
+ * - Otherwise, inside the lock and before anything is written, every entry's tgz is obtained
+ *   ({@link resolveBootstrapPackages}): a `*.tgz` file of the optional offline directory whose
+ *   sha512 equals the entry's `integrity` (the file name does not matter), else the npm download
+ *   of a `source: "npm"` entry (`packages.npmRegistry` / `npmToken` / `maxBytes`, verified against
+ *   the pin only). A workspace entry without a matching file is `bootstrap.missing_file`, a failed
+ *   download `bootstrap.download_failed`, a download that differs from the pin
+ *   `bootstrap.integrity_mismatch` (all name the plugin), and then nothing is written. Downloading
+ *   inside the lock means a fleet starting together downloads once.
  * - The whole run holds the session advisory lock `capybara.bootstrap` on a connection of its own
  *   (taken with `pg_try_advisory_lock` in a backoff loop that observes the signal, and closed
  *   afterwards, so the lock never outlives the run): when several replicas start together only one
@@ -49,8 +56,8 @@ import type { ExtensionSource } from "./sources.js";
  *   loses `required` -> `required_cleared`.
  * A failed entry does not stop the others; the run then throws {@link BootstrapFailedError} naming
  * them. The packages are kept in PG (`blob_store = 'pg'`), so installing an extension never needs
- * the object store (object-store-s3 is itself a bootstrap plugin); a declarative plugin's catalog
- * files do.
+ * the object store (object-store-s3 is itself a bootstrap plugin) and the directory and npm are
+ * never needed again; a declarative plugin's catalog files do need the object store.
  */
 /** The bootstrap manifest that ships with the kernel package. */
 export declare const BOOTSTRAP_MANIFEST_FILE: string;
@@ -89,6 +96,27 @@ export declare class BootstrapFailedError extends Error {
 export declare function bootstrapManifestSha256(manifest: BootstrapManifest): string;
 /** Reads and parses a bootstrap manifest file; an invalid one throws with its problems. */
 export declare function readBootstrapManifest(file?: string): Promise<BootstrapManifest>;
+/** What {@link resolveBootstrapPackages} needs from the kernel config. */
+export interface BootstrapResolveOptions {
+    /**
+     * The offline directory: every `*.tgz` directly in it is matched to the entries by sha512.
+     * Omitted or missing: no offline packages.
+     */
+    dir?: string;
+    config: Pick<KernelConfig, "packages">;
+    signal?: AbortSignal;
+    log?: Pick<Logger, "warn">;
+    /** The npm download (default {@link fetchNpmPackage}; tests replace it). */
+    fetch?: typeof fetchNpmPackage;
+}
+/**
+ * Obtains every entry's tgz, checked against its pinned sha512: from the offline directory when a
+ * file there has that sha512, else (a `source: "npm"` entry) downloaded from the npm registry and
+ * verified against the pin (the packument's `dist.integrity` is not consulted). Throws an
+ * {@link ApiError} naming the plugin for the first entry it cannot obtain
+ * (`bootstrap.missing_file`, `bootstrap.download_failed`, `bootstrap.integrity_mismatch`).
+ */
+export declare function resolveBootstrapPackages(manifest: BootstrapManifest, o: BootstrapResolveOptions): Promise<Map<string, Uint8Array>>;
 export interface BootstrapServiceDeps {
     db: KernelDb;
     /** The lock connection is opened separately (and closed after every run). */
@@ -119,7 +147,8 @@ export declare class BootstrapService {
      */
     run(o: {
         manifest: BootstrapManifest;
-        dir: string;
+        /** The offline directory (see {@link resolveBootstrapPackages}); omitted: npm only. */
+        dir?: string;
         signal?: AbortSignal;
         carry?: readonly BootstrapEntryResult[];
     }): Promise<BootstrapResult>;
@@ -131,8 +160,6 @@ export declare class BootstrapService {
     private locked;
     /** The entry names the last completed run handled (undefined before any run completed). */
     private lastRunNames;
-    /** Reads every entry's file and checks its sha512 (before the lock: nothing is written yet). */
-    private verifyFiles;
     private entry;
     /** A declarative plugin: catalog only. Returns false when that version is already imported. */
     private importOnly;

package/dist/extensions/bootstrap.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { bootstrapFileName, parseBootstrapManifest, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
+import { parseBootstrapManifest, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
 import { sql } from "kysely";
 import pg from "pg";
 import semver from "semver";
@@ -11,18 +11,25 @@ import { PluginPackageError, readPluginPackage } from "../catalog/plugin-package
 import { pgConnectOptions } from "../db/pool.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
+import { fetchNpmPackage, IntegrityMismatchError, NpmFetchError, PackageTooLargeError, } from "../packages/npm.js";
 import { writeSnapshot } from "./approvals.js";
 import { ExtensionPackageError, permissionSetOfPackage, readExtensionPackage } from "./package.js";
 import { diffPermissions } from "./permission-set.js";
 /**
- * The bootstrap step (package ecosystem spec §7): installs the plugins pinned by the bootstrap
- * manifest (`packages/kernel/bootstrap.json`) from the tgz files baked into the image. It replaced
- * the builtin extensions.
+ * The bootstrap step (package ecosystem spec §7, startup bootstrap spec): installs the plugins
+ * pinned by the bootstrap manifest (`packages/kernel/bootstrap.json`). It replaced the builtin
+ * extensions.
  *
- * - Every file (`<dir>/<name>-<version>.tgz`) is checked against the entry's sha512 before anything
- *   is read or written; a missing file is `bootstrap.missing_file`, a mismatch
- *   `bootstrap.integrity_mismatch` (both name the plugin), and then nothing is written. It never
- *   touches the network.
+ * - When the run is already done for the manifest nothing is read: no directory, no network, so a
+ *   restart of an installed deployment never needs npm.
+ * - Otherwise, inside the lock and before anything is written, every entry's tgz is obtained
+ *   ({@link resolveBootstrapPackages}): a `*.tgz` file of the optional offline directory whose
+ *   sha512 equals the entry's `integrity` (the file name does not matter), else the npm download
+ *   of a `source: "npm"` entry (`packages.npmRegistry` / `npmToken` / `maxBytes`, verified against
+ *   the pin only). A workspace entry without a matching file is `bootstrap.missing_file`, a failed
+ *   download `bootstrap.download_failed`, a download that differs from the pin
+ *   `bootstrap.integrity_mismatch` (all name the plugin), and then nothing is written. Downloading
+ *   inside the lock means a fleet starting together downloads once.
  * - The whole run holds the session advisory lock `capybara.bootstrap` on a connection of its own
  *   (taken with `pg_try_advisory_lock` in a backoff loop that observes the signal, and closed
  *   afterwards, so the lock never outlives the run): when several replicas start together only one
@@ -58,8 +65,8 @@ import { diffPermissions } from "./permission-set.js";
  *   loses `required` -> `required_cleared`.
  * A failed entry does not stop the others; the run then throws {@link BootstrapFailedError} naming
  * them. The packages are kept in PG (`blob_store = 'pg'`), so installing an extension never needs
- * the object store (object-store-s3 is itself a bootstrap plugin); a declarative plugin's catalog
- * files do.
+ * the object store (object-store-s3 is itself a bootstrap plugin) and the directory and npm are
+ * never needed again; a declarative plugin's catalog files do need the object store.
  */
 /** The bootstrap manifest that ships with the kernel package. */
 export const BOOTSTRAP_MANIFEST_FILE = fileURLToPath(new URL("../../bootstrap.json", import.meta.url));
@@ -95,6 +102,101 @@ export async function readBootstrapManifest(file = BOOTSTRAP_MANIFEST_FILE) {
     return parsed;
 }
 const integrityOf = (bytes) => `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
+/**
+ * Obtains every entry's tgz, checked against its pinned sha512: from the offline directory when a
+ * file there has that sha512, else (a `source: "npm"` entry) downloaded from the npm registry and
+ * verified against the pin (the packument's `dist.integrity` is not consulted). Throws an
+ * {@link ApiError} naming the plugin for the first entry it cannot obtain
+ * (`bootstrap.missing_file`, `bootstrap.download_failed`, `bootstrap.integrity_mismatch`).
+ */
+export async function resolveBootstrapPackages(manifest, o) {
+    const out = new Map();
+    if (manifest.plugins.length === 0)
+        return out;
+    const { npmRegistry, npmToken, maxBytes } = o.config.packages;
+    const offline = o.dir !== undefined ? await scanOfflineDir(o.dir, maxBytes, o.log) : new Map();
+    const fetchPackage = o.fetch ?? fetchNpmPackage;
+    const signal = o.signal ?? new AbortController().signal;
+    const where = o.dir !== undefined ? o.dir : "the bootstrap directory (config bootstrap.dir)";
+    for (const e of manifest.plugins) {
+        signal.throwIfAborted();
+        const found = offline.get(e.integrity);
+        if (found !== undefined) {
+            out.set(e.name, found);
+            continue;
+        }
+        if (e.source === "workspace") {
+            throw new ApiError("bootstrap.missing_file", `Bootstrap plugin ${e.name} ${e.version}: no file in ${where} has its pinned sha512 (${e.integrity.slice(0, 19)}…), and a workspace entry cannot be downloaded; put its package tgz (pnpm pack-plugin ${e.path}) in that directory`);
+        }
+        const registry = registryOrigin(npmRegistry);
+        const offlineHint = `to install offline, put the package tgz (npm pack ${e.npm}@${e.version}, any file name) in ${where}`;
+        try {
+            const r = await fetchPackage({ registry: npmRegistry, ...(npmToken !== undefined && { token: npmToken }), maxBytes }, e.npm, e.version, signal, { expectedIntegrity: e.integrity });
+            out.set(e.name, r.bytes);
+        }
+        catch (err) {
+            if (signal.aborted)
+                throw err;
+            if (err instanceof IntegrityMismatchError) {
+                throw new ApiError("bootstrap.integrity_mismatch", `Bootstrap plugin ${e.name} ${e.version}: the package ${e.npm}@${e.version} downloaded from ${registry} does not match its pinned sha512 (expected ${e.integrity.slice(0, 19)}…, got ${err.actual.slice(0, 19)}…); refusing to install anything`);
+            }
+            const reason = err instanceof NpmFetchError || err instanceof PackageTooLargeError
+                ? err.message
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            throw new ApiError("bootstrap.download_failed", `Bootstrap plugin ${e.name} ${e.version}: cannot download ${e.npm}@${e.version} from ${registry} (${reason}); ${offlineHint}, or set packages.npmRegistry to a reachable mirror`);
+        }
+    }
+    return out;
+}
+/** The registry's origin, for messages (never its credentials or path). */
+function registryOrigin(registry) {
+    try {
+        return new URL(registry).origin;
+    }
+    catch {
+        return "the configured npm registry";
+    }
+}
+/**
+ * The `*.tgz` files directly in `dir` by their sha512 integrity. A missing directory is an empty
+ * one; a file larger than `maxBytes` is skipped with a warning.
+ */
+async function scanOfflineDir(dir, maxBytes, log) {
+    const out = new Map();
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return out;
+        throw err;
+    }
+    for (const name of names.sort()) {
+        if (!name.endsWith(".tgz"))
+            continue;
+        const file = join(dir, name);
+        const st = await stat(file).catch(() => undefined);
+        if (!st?.isFile())
+            continue;
+        if (st.size > maxBytes) {
+            log?.warn("bootstrap: a file in the bootstrap directory exceeds packages.maxBytes; skipped", {
+                file,
+                size: st.size,
+                maxBytes,
+            });
+            continue;
+        }
+        const bytes = new Uint8Array(await readFile(file));
+        const integrity = integrityOf(bytes);
+        if (!out.has(integrity))
+            out.set(integrity, bytes);
+    }
+    return out;
+}
 /** The advisory lock around a whole run. */
 const LOCK_KEY = "capybara.bootstrap";
 export class BootstrapService {
@@ -120,16 +222,30 @@ export class BootstrapService {
      */
     async run(o) {
         const manifestSha256 = bootstrapManifestSha256(o.manifest);
-        const files = await this.verifyFiles(o.manifest, o.dir);
-        return this.locked(o.signal, async () => {
+        const recorded = async () => {
             const done = await this.d.db
                 .selectFrom("bootstrap_runs")
                 .select("results")
                 .where("manifest_sha256", "=", manifestSha256)
                 .executeTakeFirst();
-            if (done) {
-                return { manifestSha256, results: done.results };
-            }
+            return done && { manifestSha256, results: done.results };
+        };
+        // Done: no lock, no directory, no network
+        const before = await recorded();
+        if (before)
+            return before;
+        return this.locked(o.signal, async () => {
+            // Another replica may have finished it while this one waited for the lock
+            const done = await recorded();
+            if (done)
+                return done;
+            // Every package is obtained and checked before the first write
+            const files = await resolveBootstrapPackages(o.manifest, {
+                ...(o.dir !== undefined && { dir: o.dir }),
+                config: this.d.config(),
+                ...(o.signal !== undefined && { signal: o.signal }),
+                log: this.d.log,
+            });
             const handled = await this.lastRunNames();
             const results = [];
             const failures = [];
@@ -225,28 +341,6 @@ export class BootstrapService {
             .filter((r) => r.action !== "required_cleared")
             .map((r) => r.name));
     }
-    /** Reads every entry's file and checks its sha512 (before the lock: nothing is written yet). */
-    async verifyFiles(manifest, dir) {
-        const out = new Map();
-        for (const e of manifest.plugins) {
-            const file = join(dir, bootstrapFileName(e));
-            let bytes;
-            try {
-                bytes = new Uint8Array(await readFile(file));
-            }
-            catch (err) {
-                if (err.code !== "ENOENT")
-                    throw err;
-                throw new ApiError("bootstrap.missing_file", `Bootstrap plugin ${e.name} ${e.version}: ${file} is missing; the image must carry every package bootstrap.json pins`);
-            }
-            const actual = integrityOf(bytes);
-            if (actual !== e.integrity) {
-                throw new ApiError("bootstrap.integrity_mismatch", `Bootstrap plugin ${e.name} ${e.version}: ${file} does not match its pinned sha512 (expected ${e.integrity.slice(0, 19)}…, got ${actual.slice(0, 19)}…); refusing to install anything`);
-            }
-            out.set(e.name, bytes);
-        }
-        return out;
-    }
     async entry(e, bytes, handled) {
         const pkg = await readPluginPackage(bytes, {
             maxBytes: this.d.config().packages.maxBytes,

package/dist/http/app.js

@@ -5,12 +5,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import "reflect-metadata";
+import { randomUUID } from "node:crypto";
 import fastifyCookie from "@fastify/cookie";
 import { Module } from "@nestjs/common";
 import { APP_FILTER, NestFactory } from "@nestjs/core";
 import { FastifyAdapter } from "@nestjs/platform-fastify";
 import { ApiError, errorBody } from "../errors.js";
 import { authorizeEnterpriseAdmin } from "../identity/auth.guard.js";
+import { withLogContext } from "../log-context.js";
 import { ErrorFilter, redactPath } from "./error.filter.js";
 import { registerGatewayRoutes } from "./gateway.module.js";
 import { HealthController } from "./health.controller.js";
@@ -37,6 +39,48 @@ export const PACKAGE_UPLOAD_ROUTES = new Set([
 function fastifyTrustProxy(tp) {
     return typeof tp === "number" ? (_addr, hop) => hop < tp : tp;
 }
+const REQUEST_ID = /^[A-Za-z0-9._-]{1,128}$/;
+/** Paths without an access log line (probes). */
+const QUIET_PATHS = new Set(["/healthz", "/readyz"]);
+/** The request id: a valid incoming `x-request-id`, else a random one. */
+function requestId(req) {
+    const h = req.headers["x-request-id"];
+    return typeof h === "string" && REQUEST_ID.test(h) ? h : randomUUID();
+}
+/**
+ * Request ids and the access log. Every request runs in a log context with its `reqId` (records
+ * logged while handling it carry it) and answers with `x-request-id` (set on the raw response, so
+ * hijacked SSE streams carry it too). One access line per request when the response is done:
+ * `info`, except event streams (`debug`, when they close) and the probes (none).
+ */
+function registerRequestLog(fastify, log) {
+    fastify.addHook("onRequest", (req, reply, done) => {
+        reply.raw.setHeader("x-request-id", req.id);
+        const started = performance.now();
+        const path = req.url.split("?")[0] ?? "";
+        let logged = false;
+        const accessLine = () => {
+            if (logged || QUIET_PATHS.has(path))
+                return;
+            logged = true;
+            const type = String(reply.raw.getHeader("content-type") ?? "");
+            const fields = {
+                method: req.method,
+                url: redactPath(req.url),
+                status: reply.raw.statusCode,
+                ms: Math.round(performance.now() - started),
+                reqId: req.id,
+            };
+            if (type.startsWith("text/event-stream"))
+                log.debug?.("request", fields);
+            else
+                log.info("request", fields);
+        };
+        reply.raw.once("finish", accessLine);
+        reply.raw.once("close", accessLine);
+        withLogContext({ reqId: req.id }, done);
+    });
+}
 /** 允许较大请求体的路由（Fastify 路由模板，只读常量表）及其上限。 */
 const LARGE_BODY_ROUTES = new Set([
     "/api/v1/orgs/:orgId/connectors",
@@ -67,10 +111,16 @@ function rootModule(opts) {
  * 插件加载前 `/plugins/*` 一律 404。未匹配的内核路由同样返回 404 错误信封。
  */
 export async function createHttpApp(opts) {
-    const app = await NestFactory.create(rootModule(opts), new FastifyAdapter({ trustProxy: fastifyTrustProxy(opts.trustProxy ?? false) }), { logger: new NestLogAdapter(opts.log), abortOnError: false });
+    const app = await NestFactory.create(rootModule(opts), new FastifyAdapter({
+        trustProxy: fastifyTrustProxy(opts.trustProxy ?? false),
+        // x-request-id is read by requestId() (validated), never trusted as is
+        requestIdHeader: false,
+        genReqId: requestId,
+    }), { logger: new NestLogAdapter(opts.log), abortOnError: false });
     // Cookie 解析（会话 Cookie）；必须在 init 之前注册
     await app.register(fastifyCookie);
     const fastify = app.getHttpAdapter().getInstance();
+    registerRequestLog(fastify, opts.log);
     const replicaId = opts.replicaId;
     if (replicaId !== undefined) {
         // 直接设在原始响应上：hijack 后自己 writeHead 的 SSE 流也会带上（writeHead 合并已 setHeader 的头）