@k2b/cloud 0.15.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -99,7 +99,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.12.1",
     "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.6.2",
+    "@k2b/ui": "0.6.3",
     "@k2b/stdlib": "0.26.0",
     "@k2b/sync": "6.5.0",
     "@nats-io/transport-node": "3.4.0",

package/scripts/build.ts

@@ -18,6 +18,8 @@
  *   public/<id>/app.css  Tailwind, if the app has src/styles/app.css
  *   public/<id>/...      anything from <appDir>/public/
  *   assets/...           anything from <appDir>/src/assets/ (appAssetPath)
+ *   cli/<name>/...       `cld` plugin per `defineApp({ cli })` module: cli.js,
+ *                        references/*.md, manifest.json
  *
  * If the app needs additional artefacts (core's global.css, logo, katex),
  * it ships a `scripts/build-extras.ts` that this script runs at the end.
@@ -131,6 +133,7 @@ try {
       __CLOUD_SYNC_VERSION__: JSON.stringify(syncVersion),
       __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./pdf-render/worker.js"),
       __CLOUD_APP_ASSETS__: JSON.stringify("./assets/"),
+      __CLOUD_CLI_PLUGINS__: JSON.stringify("./cli/"),
     },
     plugins: [(app?.plugin ?? plugin)()],
   });
@@ -175,6 +178,14 @@ if (existsSync(appAssets)) {
   await cp(appAssets, resolve(dist, "assets"), { recursive: true });
 }
 
+// `cld` plugins: one self-contained module bundle plus references per module.
+// Imported after the app config so the framework sees the APP_DIR set above.
+const { buildCliPlugin, writeCliPlugin } = await import("../src/_internal/cli-plugins");
+for (const [name, declaration] of Object.entries(app?.meta.cli ?? {})) {
+  const plugin = await buildCliPlugin({ appDir, appId, name, declaration, version });
+  await writeCliPlugin(resolve(dist, "cli", name), plugin);
+}
+
 if (appId !== "core" && app) {
   await writeAppFavicon({
     publicDir: distPublic,

package/src/_internal/cli-plugins.ts

@@ -0,0 +1,248 @@
+/**
+ * `cld` plugins served by the application that owns them.
+ *
+ * `defineApp({ cli })` names each CLI module and the paths of its source and
+ * skill references. The production build bundles every module into one
+ * self-contained ESM file and writes it with its references and manifest to
+ * `dist/cli/<name>/`. At run time the application serves those files under
+ * `/cli/plugins/<name>/`; in development it builds them from source on first
+ * request. Only authenticated callers allowed by `cli.plugins.access` get any
+ * of them.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Glob } from "bun";
+import { type Context, Hono } from "hono";
+import { every } from "hono/combine";
+import { createMiddleware } from "hono/factory";
+import {
+  CLOUD_CLI_API_VERSION,
+  CLOUD_CLI_MODULE_NAME,
+  CLOUD_CLI_PLUGIN_ENTRY,
+  CLOUD_CLI_PLUGIN_ROUTE,
+  CLOUD_CLI_REFERENCE_INDEX,
+  type CloudCliPluginFile,
+  type CloudCliPluginManifest,
+  cloudCliPluginDigest,
+  isCloudCliPluginFilePath,
+  parseCloudCliPluginManifest,
+  sha512Hex,
+  validateCloudCliModule,
+} from "../cli/plugin";
+import { env } from "../config/env";
+import type { AppCliModules } from "../contracts/app";
+import { type AuthContext, auth } from "../server/middleware/auth";
+import { logger } from "../services/logging";
+import { get } from "../services/settings";
+import { buildMetadata } from "./build-metadata";
+
+/** Set by `scripts/build.ts`; the bundle lives next to `dist/cli/`. */
+declare const __CLOUD_CLI_PLUGINS__: string | undefined;
+
+export const CLI_PLUGIN_ACCESS_SETTING = "cli.plugins.access";
+
+/** Reject names and paths that cannot become a served plugin. Returns the module names. */
+export const validateAppCliModules = (appId: string, cli: AppCliModules | undefined): string[] => {
+  const names = Object.keys(cli ?? {});
+  for (const name of names) {
+    if (!CLOUD_CLI_MODULE_NAME.test(name)) throw new Error(`App "${appId}" declares CLI module "${name}"; use a kebab-case name`);
+    const declaration = cli?.[name];
+    for (const key of ["module", "references"] as const) {
+      const path = declaration?.[key];
+      if (typeof path !== "string" || path === "" || isAbsolute(path)) {
+        throw new Error(`App "${appId}" CLI module "${name}" needs a relative ${key} path`);
+      }
+    }
+  }
+  return names;
+};
+
+export type BuiltCliPlugin = {
+  manifest: CloudCliPluginManifest;
+  files: ReadonlyMap<string, Uint8Array<ArrayBuffer>>;
+};
+
+const referenceFiles = async (directory: string): Promise<Map<string, Uint8Array<ArrayBuffer>>> => {
+  const files = new Map<string, Uint8Array<ArrayBuffer>>();
+  for await (const path of new Glob("**/*").scan({ cwd: directory, onlyFiles: true, dot: true })) {
+    const name = `references/${path.split(sep).join("/")}`;
+    if (!isCloudCliPluginFilePath(name)) throw new Error(`CLI reference ${path} must be a Markdown file with a plain name`);
+    files.set(name, new Uint8Array(await readFile(join(directory, path))));
+  }
+  if (!files.has(CLOUD_CLI_REFERENCE_INDEX)) throw new Error(`CLI references in ${directory} need an index.md`);
+  return files;
+};
+
+/**
+ * Bundle one CLI module and collect its references. The bundle carries every
+ * dependency, including its own copy of `@k2b/cloud/cli`, because `cld`
+ * installs no plugin dependencies.
+ */
+export const buildCliPlugin = async (params: {
+  appDir: string;
+  appId: string;
+  name: string;
+  declaration: { module: string; references: string };
+  version: string;
+}): Promise<BuiltCliPlugin> => {
+  const { appDir, appId, name, declaration, version } = params;
+  const result = await Bun.build({
+    entrypoints: [resolve(appDir, declaration.module)],
+    target: "bun",
+    format: "esm",
+    minify: true,
+    // Playwright references this optional BiDi adapter lazily; Cloud uses CDP.
+    external: ["chromium-bidi/*"],
+  });
+  if (!result.success) {
+    throw new Error(`CLI module "${name}" failed to bundle:\n${result.logs.map((log) => String(log)).join("\n")}`);
+  }
+  if (result.outputs.length !== 1 || result.outputs[0]!.kind !== "entry-point") {
+    throw new Error(`CLI module "${name}" must bundle into one file; it produced ${result.outputs.length}`);
+  }
+  const files = new Map<string, Uint8Array<ArrayBuffer>>([
+    [CLOUD_CLI_PLUGIN_ENTRY, new Uint8Array(await result.outputs[0]!.arrayBuffer())],
+    ...(await referenceFiles(resolve(appDir, declaration.references))),
+  ]);
+  const list: CloudCliPluginFile[] = [...files]
+    .map(([path, bytes]) => ({ path, size: bytes.byteLength, sha512: sha512Hex(bytes) }))
+    .sort((left, right) => (left.path < right.path ? -1 : 1));
+  return {
+    manifest: {
+      apiVersion: CLOUD_CLI_API_VERSION,
+      name,
+      app: appId,
+      version,
+      entry: CLOUD_CLI_PLUGIN_ENTRY,
+      digest: cloudCliPluginDigest(list),
+      files: list,
+    },
+    files,
+  };
+};
+
+/** Write a built plugin to `<directory>/`, then import it once to check its default export. */
+export const writeCliPlugin = async (directory: string, plugin: BuiltCliPlugin): Promise<void> => {
+  for (const [path, bytes] of plugin.files) {
+    await mkdir(dirname(join(directory, path)), { recursive: true });
+    await writeFile(join(directory, path), bytes);
+  }
+  await writeFile(join(directory, "manifest.json"), `${JSON.stringify(plugin.manifest, null, 2)}\n`);
+  const loaded: unknown = await import(pathToFileURL(join(directory, CLOUD_CLI_PLUGIN_ENTRY)).href);
+  const module = validateCloudCliModule(typeof loaded === "object" && loaded !== null ? (loaded as { default?: unknown }).default : null);
+  if (module.name !== plugin.manifest.name) {
+    throw new Error(`CLI module declared as "${plugin.manifest.name}" exports the name "${module.name}"`);
+  }
+};
+
+type ServedCliPlugin = {
+  manifest: CloudCliPluginManifest;
+  read: (path: string) => Promise<Uint8Array<ArrayBuffer>>;
+};
+
+const builtPluginsDirectory = (): string | null =>
+  typeof __CLOUD_CLI_PLUGINS__ === "string" ? fileURLToPath(new URL(__CLOUD_CLI_PLUGINS__, import.meta.url)) : null;
+
+const loadBuiltPlugin = async (root: string, name: string): Promise<ServedCliPlugin> => {
+  const directory = join(root, name);
+  const manifest = parseCloudCliPluginManifest(JSON.parse(await readFile(join(directory, "manifest.json"), "utf8")));
+  return { manifest, read: async (path) => new Uint8Array(await readFile(join(directory, path))) };
+};
+
+const buildSourcePlugin = async (appId: string, name: string, declaration: { module: string; references: string }) => {
+  const plugin = await buildCliPlugin({
+    appDir: env.APP_DIR ?? process.cwd(),
+    appId,
+    name,
+    declaration,
+    version: buildMetadata.version,
+  });
+  return { manifest: plugin.manifest, read: async (path: string) => plugin.files.get(path)! };
+};
+
+/** Resolves served plugins: prebuilt files in production, a cached source build in development. */
+const createPluginSource = (appId: string, cli: AppCliModules, root: string | null) => {
+  const cache = new Map<string, Promise<ServedCliPlugin>>();
+  return (name: string): Promise<ServedCliPlugin> | null => {
+    const declaration = Object.hasOwn(cli, name) ? cli[name] : undefined;
+    if (!declaration) return null;
+    let pending = cache.get(name);
+    if (!pending) {
+      pending = root ? loadBuiltPlugin(root, name) : buildSourcePlugin(appId, name, declaration);
+      // A failed source build is retried on the next request instead of being cached.
+      pending.catch(() => cache.delete(name));
+      cache.set(name, pending);
+    }
+    return pending;
+  };
+};
+
+/**
+ * Access rule for every plugin route, the list included: an authenticated
+ * caller (session, OAuth token, or API key) with `read` scope when OAuth is
+ * used, and no guest account unless `cli.plugins.access` is `all_users`. A
+ * service account without a delegated user is not a guest.
+ */
+export const requireCliPluginAccess = every(
+  auth.requireRole("authenticated"),
+  auth.requireOAuthScope("read"),
+  createMiddleware<AuthContext>(async (c, next) => {
+    const access = await get<string>(CLI_PLUGIN_ACCESS_SETTING);
+    if (access !== "all_users" && c.get("user")?.profile === "guest") {
+      return c.json({ code: "FORBIDDEN", message: "CLI plugins are available to full accounts only" }, 403);
+    }
+    return next();
+  }),
+);
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".js": "text/javascript; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+};
+
+const privateHeaders = { "cache-control": "private, no-store", "x-content-type-options": "nosniff" } as const;
+
+/**
+ * Framework-owned plugin routes of one application, mounted at
+ * `/cli/plugins`. The gateway reaches them through the `/cli/plugins/<name>`
+ * prefixes `defineApp` adds to the application's routes.
+ */
+export const createCliPluginRoutes = (appId: string, cli: AppCliModules, builtRoot = builtPluginsDirectory()) => {
+  const source = createPluginSource(appId, cli, builtRoot);
+  const log = logger("cli-plugins");
+  const served = async (c: Context<AuthContext>): Promise<ServedCliPlugin | Response> => {
+    const pending = source(c.req.param("name") ?? "");
+    if (!pending) return c.json({ code: "NOT_FOUND", message: "CLI plugin not found" }, 404);
+    try {
+      return await pending;
+    } catch (error) {
+      log.error("CLI plugin unavailable", {
+        appId,
+        name: c.req.param("name"),
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return c.json({ code: "UNAVAILABLE", message: "CLI plugin is unavailable" }, 503);
+    }
+  };
+  return new Hono<AuthContext>()
+    .get("/:name/manifest.json", requireCliPluginAccess, async (c) => {
+      const plugin = await served(c);
+      if (plugin instanceof Response) return plugin;
+      return c.json(plugin.manifest, 200, privateHeaders);
+    })
+    .get("/:name/*", requireCliPluginAccess, async (c) => {
+      const plugin = await served(c);
+      if (plugin instanceof Response) return plugin;
+      const prefix = `${CLOUD_CLI_PLUGIN_ROUTE}/${plugin.manifest.name}/`;
+      const path = c.req.path.startsWith(prefix) ? c.req.path.slice(prefix.length) : "";
+      if (!plugin.manifest.files.some((file) => file.path === path)) {
+        return c.json({ code: "NOT_FOUND", message: "CLI plugin file not found" }, 404);
+      }
+      const bytes = await plugin.read(path);
+      return c.body(bytes, 200, { ...privateHeaders, "content-type": CONTENT_TYPES[path.slice(path.lastIndexOf("."))]! });
+    });
+};
+
+/** The gateway prefixes of an application's plugin routes. */
+export const cliPluginRoutePrefixes = (names: readonly string[]): string[] => names.map((name) => `${CLOUD_CLI_PLUGIN_ROUTE}/${name}`);

package/src/_internal/define-app.ts

@@ -17,10 +17,12 @@ import { routes } from "@k2b/ssr/hono";
 import type { Sync } from "@k2b/sync";
 import { type Context, type Handler, Hono } from "hono";
 import { generateSpecs } from "hono-openapi";
+import { CLOUD_CLI_PLUGIN_ROUTE } from "../cli/plugin";
 import { env } from "../config/env";
 import type {
   AppAdminNavigationGroup,
   AppAppearance,
+  AppCliModules,
   AppLifecycle,
   AppMeta,
   AppPresentationCatalog,
@@ -69,6 +71,7 @@ import { compileAppPresentation } from "./app-presentation";
 import { readBoundedJson } from "./bounded-json";
 import { appRuntimeMetadata } from "./build-metadata";
 import { compileCapabilities, invokeCompiledCapability, reviewCompiledCapability, serializeCapabilityProviderResult } from "./capabilities";
+import { cliPluginRoutePrefixes, createCliPluginRoutes, validateAppCliModules } from "./cli-plugins";
 import { createHeartbeat } from "./heartbeat";
 import { compileHelp } from "./help";
 import { createPageResponses } from "./page-responses";
@@ -197,6 +200,18 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
    * `/api/<id>` entry in `routes`).
    */
   openapi?: string;
+  /**
+   * `cld` modules this app serves as plugins, keyed by module name
+   * (`cld <name>`). Paths are relative to the application directory:
+   *
+   *   cli: { inventory: { module: "src/cli.ts", references: "src/cli-references" } }
+   *
+   * The production build bundles each module with its skill references into
+   * the image; the framework serves them under `/cli/plugins/<name>/` to
+   * authenticated callers that `cli.plugins.access` allows, and adds that
+   * prefix to the app's gateway routes.
+   */
+  cli?: AppCliModules;
   /**
    * Project root used for SSR component IDs and development assets.
    * Defaults to `process.cwd()`. Override only if you run the entrypoint
@@ -305,6 +320,7 @@ export const defineApp = <
   configurePostgresApplicationName(opts.id);
   const isDevelopment = env.IS_DEVELOPMENT;
   const notifications = bindNotificationDefinitions(opts.id, opts.notifications);
+  const cliModules = validateAppCliModules(opts.id, opts.cli);
 
   // ── 0. Register declared settings into the runtime registry ──────────
   // SETTINGS_MAP is the single source of truth for validation in store.ts
@@ -392,13 +408,14 @@ export const defineApp = <
         links: group.links.map((link) => ({ ...link })),
       }),
     ),
-    routes: [...opts.routes],
+    routes: [...opts.routes, ...cliPluginRoutePrefixes(cliModules)],
     nav: opts.nav,
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
     widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
+    cli: opts.cli,
   };
   const meta: AppMeta = { ...baseMeta, presentation: compileAppPresentation(baseMeta, opts.presentation) };
 
@@ -492,6 +509,7 @@ export const defineApp = <
         widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
         settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
         openapi: advertiseOpenapi ? opts.openapi : undefined,
+        cliModules: cliModules.length > 0 ? cliModules : undefined,
       };
 
       // Heartbeat
@@ -554,6 +572,7 @@ export const defineApp = <
       //   /api/_internal/capabilities/v1/* when capabilities are declared
       //   /api/_internal/widgets/v1/*     when widget handlers are bound
       //   /_internal/sync/*       process-local sync operations (admin only)
+      //   /cli/plugins/<name>/*   `cld` plugins, when `cli` modules are declared
       //   <opts.openapi>          OpenAPI JSON spec, when both opts.openapi
       //                            and startOpts.openapi are set
       const ssrMountPath = config.basePath ? `${config.basePath}/_ssr` : "/_ssr";
@@ -582,6 +601,8 @@ export const defineApp = <
         })
         .route("/_internal/sync", createSyncOpsRoutes(getProcessSync));
 
+      if (opts.cli && cliModules.length > 0) server.route(CLOUD_CLI_PLUGIN_ROUTE, createCliPluginRoutes(meta.id, opts.cli));
+
       if (compiledHelp) {
         const pageBase = compiledHelp.summary.pageBase;
         const centralPageBase = `/help/apps/${encodeURIComponent(meta.id)}`;

package/src/_internal/registry-validation.ts

@@ -1,3 +1,4 @@
+import { CLOUD_CLI_MODULE_NAME } from "../cli/plugin";
 import type { AppRegistryEntry } from "../contracts/registry";
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -112,6 +113,12 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
     }
   }
   if (value.settingKeys !== undefined && !isStringArray(value.settingKeys)) return invalid("settingKeys", "an array of strings");
+  if (
+    value.cliModules !== undefined &&
+    (!isStringArray(value.cliModules) || value.cliModules.some((name) => !CLOUD_CLI_MODULE_NAME.test(name)))
+  ) {
+    return invalid("cliModules", "an array of CLI module names");
+  }
   if (value.capabilities !== undefined) {
     if (
       !isRecord(value.capabilities) ||

package/src/access/PrincipalPicker.tsx

@@ -78,8 +78,12 @@ export default function PrincipalPicker(props: {
             description:
               e.serviceAccount.kind === "user_delegated"
                 ? t().userBoundServiceAccount
-                : [e.serviceAccount.appId, e.serviceAccount.resourceType, e.serviceAccount.resourceId].filter(Boolean).join(" · "),
-            icon: "ti ti-key",
+                : e.serviceAccount.kind === "agent"
+                  ? t().agentServiceAccount
+                  : e.serviceAccount.kind === "standalone"
+                    ? t().standaloneServiceAccount
+                    : [e.serviceAccount.appId, e.serviceAccount.resourceType, e.serviceAccount.resourceId].filter(Boolean).join(" · "),
+            icon: e.serviceAccount.kind === "agent" ? "ti ti-robot" : "ti ti-key",
           });
       }
     }

package/src/access/messages.ts

@@ -15,6 +15,8 @@ export const accessMessages = i18n.define({
       removeAccessConfirm: ({ name }: { name: string }) => `Remove access for ${name}?`,
       removeAccess: "Remove access",
       userBoundServiceAccount: "User-bound service account",
+      standaloneServiceAccount: "Service account",
+      agentServiceAccount: "Agent",
       noDirectGrants: "No direct access granted yet.",
       addAll: "Add user, group, service account, or audience…",
       addService: "Add user, group, or service account…",
@@ -72,6 +74,8 @@ export const accessMessages = i18n.define({
       removeAccessConfirm: ({ name }) => `Zugriff für ${name} entfernen?`,
       removeAccess: "Zugriff entfernen",
       userBoundServiceAccount: "Benutzergebundenes Dienstkonto",
+      standaloneServiceAccount: "Dienstkonto",
+      agentServiceAccount: "Agent",
       noDirectGrants: "Noch kein direkter Zugriff erteilt.",
       addAll: "Benutzer, Gruppe, Dienstkonto oder Zielgruppe hinzufügen…",
       addService: "Benutzer, Gruppe oder Dienstkonto hinzufügen…",

package/src/account/EntitySearch.tsx

@@ -33,7 +33,7 @@ export type EntitySearchPrincipal =
       type: "service_account";
       serviceAccountId: string;
       name: string;
-      kind: "user_delegated" | "resource_bound";
+      kind: "user_delegated" | "resource_bound" | "standalone" | "agent";
       appId: string | null;
       resourceType: string | null;
       resourceId: string | null;
@@ -102,7 +102,7 @@ type ApiGroup = {
 type ApiServiceAccount = {
   id: string;
   name: string;
-  kind: "user_delegated" | "resource_bound";
+  kind: "user_delegated" | "resource_bound" | "standalone" | "agent";
   appId: string | null;
   resourceType: string | null;
   resourceId: string | null;
@@ -290,12 +290,16 @@ const EntitySearch = (props: EntitySearchProps) => {
             <For each={serviceAccounts()}>
               {(serviceAccount) => (
                 <ResultRow
-                  icon="ti-key"
+                  icon={serviceAccount.kind === "agent" ? "ti-robot" : "ti-key"}
                   title={serviceAccount.name}
                   subtitle={
                     serviceAccount.kind === "user_delegated"
                       ? "User-bound service account"
-                      : [serviceAccount.appId, serviceAccount.resourceType, serviceAccount.resourceId].filter(Boolean).join(" · ")
+                      : serviceAccount.kind === "agent"
+                        ? "Agent"
+                        : serviceAccount.kind === "standalone"
+                          ? "Service account"
+                          : [serviceAccount.appId, serviceAccount.resourceType, serviceAccount.resourceId].filter(Boolean).join(" · ")
                   }
                   disabled={props.disabled}
                   onSelect={() =>

package/src/account/avatar-upload-dialog.tsx

@@ -22,6 +22,7 @@ export type AvatarUploadDialogOptions = {
     removeFailed: string;
     replaceDrop: string;
     chooseDrop: string;
+    formats: string;
     cropHint: string;
     removing: string;
     remove: string;
@@ -149,13 +150,13 @@ function AvatarUploadDialog(props: AvatarUploadDialogOptions & { close: (saved?:
               disabled={saving() || removing()}
               busy={processing()}
               error={error}
-              icon="ti-photo-plus"
+              icon="ti ti-photo-plus"
               title={
                 sourceFile()
                   ? (props.messages?.replaceDrop ?? "Drop another image or click to replace")
                   : (props.messages?.chooseDrop ?? "Drop image or click to choose")
               }
-              subtitle="PNG, JPEG, or WebP"
+              subtitle={props.messages?.formats ?? "PNG, JPEG, or WebP"}
               hint={props.messages?.cropHint ?? "Adjust the crop, then save."}
               onDrop={handleFiles}
             />

package/src/ai/pdf-render.ts

@@ -39,8 +39,17 @@ export async function renderPdfPages(bytes: Uint8Array, pages: number[] = [1], s
         stdin: new Blob([JSON.stringify({ pdf: Buffer.from(bytes).toString("base64"), pages })]),
         stdout: "pipe",
         stderr: "ignore",
-        // The decoder needs no application credentials or runtime configuration.
-        env: { PATH: process.env.PATH, LANG: "C.UTF-8" },
+        // No application credentials or configuration reach the decoder, only fixed
+        // thread pool sizes: the Bun work pool, canvas tokio runtime, and JSC GC
+        // markers otherwise grow with the host's cores, and RLIMIT_DATA also counts
+        // each thread's stack and allocator memory.
+        env: {
+          PATH: process.env.PATH,
+          LANG: "C.UTF-8",
+          UV_THREADPOOL_SIZE: "2",
+          TOKIO_WORKER_THREADS: "2",
+          BUN_JSC_numberOfGCMarkers: "2",
+        },
       },
     );
     const stop = () => child.kill("SIGKILL");