The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Generalize bundled plugin provisioning: `ensureBundledKubernetesPlugin` → `ensureBundledPlugins` (#10063)
Devin Foleyc4cdcc482646
diff --git a/server/src/__tests__/bundled-plugins.test.ts b/server/src/__tests__/bundled-plugins.test.tsnew file mode 100644index 0000000000..e137634c9c--- /dev/null+++ b/server/src/__tests__/bundled-plugins.test.ts@@ -0,0 +1,353 @@+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";+import os from "node:os";+import path from "node:path";+import { afterAll, describe, expect, it, vi } from "vitest";+import {+ BUNDLED_PLUGIN_CATALOG,+ DEFAULT_BUNDLED_CATALOG_ROOT,+ SELF_HOSTED_AUTO_INSTALL_KEYS,+ ensureBundledPlugins,+ resolveBundledCatalogRoot,+ resolveBundledPluginInstalls,+ type BundledPluginProvisionerDeps,+ type ResolvedBundledPlugin,+} from "../services/bundled-plugins.js";++const CATALOG_ROOT = "/app/packages/plugins";++const tempDirs: string[] = [];+function makeTempDir(prefix: string): string {+ const dir = mkdtempSync(path.join(os.tmpdir(), prefix));+ tempDirs.push(dir);+ return dir;+}++afterAll(() => {+ for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true });+});++// ---------------------------------------------------------------------------+// Catalog-root resolution (fail-to-start allowlist)+// ---------------------------------------------------------------------------++describe("resolveBundledPluginInstalls", () => {+ it("resolves known keys to paths inside the catalog root", () => {+ const resolved = resolveBundledPluginInstalls(["kubernetes", "daytona"], {+ catalogRoot: CATALOG_ROOT,+ env: {},+ enforceCatalogRoot: true,+ });+ expect(resolved).toEqual([+ {+ key: "kubernetes",+ pluginKey: "paperclip.kubernetes-sandbox-provider",+ localPath: path.join(CATALOG_ROOT, "sandbox-providers/kubernetes"),+ },+ {+ key: "daytona",+ pluginKey: "paperclip.daytona-sandbox-provider",+ localPath: path.join(CATALOG_ROOT, "sandbox-providers/daytona"),+ },+ ]);+ });++ it("throws on a key outside the bundled catalog (fail to start)", () => {+ expect(() =>+ resolveBundledPluginInstalls(["kubernetes", "not-a-bundled-plugin"], {+ catalogRoot: CATALOG_ROOT,+ env: {},+ enforceCatalogRoot: true,+ }),+ ).toThrow(/"not-a-bundled-plugin" is not in the bundled catalog.*refusing to start/);+ });++ it("names the known catalog keys in the unknown-key error", () => {+ expect(() =>+ resolveBundledPluginInstalls(["nope"], {+ catalogRoot: CATALOG_ROOT,+ env: {},+ enforceCatalogRoot: true,+ }),+ ).toThrow(new RegExp(BUNDLED_PLUGIN_CATALOG.map((entry) => entry.key).join(", ")));+ });++ it("resolves an empty key list to no installs", () => {+ expect(+ resolveBundledPluginInstalls([], {+ catalogRoot: CATALOG_ROOT,+ env: {},+ enforceCatalogRoot: true,+ }),+ ).toEqual([]);+ });++ it("throws when an env override escapes the catalog root under enforcement", () => {+ expect(() =>+ resolveBundledPluginInstalls(["kubernetes"], {+ catalogRoot: CATALOG_ROOT,+ env: { PAPERCLIP_KUBERNETES_PLUGIN_PATH: "/srv/evil/plugin" },+ enforceCatalogRoot: true,+ }),+ ).toThrow(/outside the bundled catalog root.*refusing to start/);+ });++ it("collapses `..` segments in an override before the containment check", () => {+ expect(() =>+ resolveBundledPluginInstalls(["kubernetes"], {+ catalogRoot: CATALOG_ROOT,+ env: {+ PAPERCLIP_KUBERNETES_PLUGIN_PATH: path.join(+ CATALOG_ROOT,+ "sandbox-providers/../../../../etc/kubernetes",+ ),+ },+ enforceCatalogRoot: true,+ }),+ ).toThrow(/outside the bundled catalog root/);+ });++ it("throws when a symlink inside the root points outside it under enforcement", () => {+ const outside = makeTempDir("bundled-outside-");+ const root = makeTempDir("bundled-root-");+ mkdirSync(path.join(root, "sandbox-providers"), { recursive: true });+ symlinkSync(outside, path.join(root, "sandbox-providers", "kubernetes"));+ expect(() =>+ resolveBundledPluginInstalls(["kubernetes"], {+ catalogRoot: root,+ env: {},+ enforceCatalogRoot: true,+ }),+ ).toThrow(/outside the bundled catalog root/);+ });++ it("honors the legacy kubernetes path override without enforcement (self-hosted)", () => {+ const resolved = resolveBundledPluginInstalls(["kubernetes"], {+ catalogRoot: CATALOG_ROOT,+ env: { PAPERCLIP_KUBERNETES_PLUGIN_PATH: "/somewhere/else/kubernetes" },+ enforceCatalogRoot: false,+ });+ expect(resolved).toEqual([+ {+ key: "kubernetes",+ pluginKey: "paperclip.kubernetes-sandbox-provider",+ localPath: "/somewhere/else/kubernetes",+ },+ ]);+ });++ it("honors an env override that stays inside the catalog root under enforcement", () => {+ const inside = path.join(CATALOG_ROOT, "sandbox-providers", "kubernetes");+ const resolved = resolveBundledPluginInstalls(["kubernetes"], {+ catalogRoot: CATALOG_ROOT,+ env: { PAPERCLIP_KUBERNETES_PLUGIN_PATH: inside },+ enforceCatalogRoot: true,+ });+ expect(resolved[0]!.localPath).toBe(inside);+ });++ it("dedupes repeated keys", () => {+ const resolved = resolveBundledPluginInstalls(["kubernetes", "kubernetes"], {+ catalogRoot: CATALOG_ROOT,+ env: {},+ enforceCatalogRoot: true,+ });+ expect(resolved).toHaveLength(1);+ });++ it("keeps the self-hosted default list to exactly the kubernetes bundle", () => {+ expect(SELF_HOSTED_AUTO_INSTALL_KEYS).toEqual(["kubernetes"]);+ const [entry] = resolveBundledPluginInstalls(SELF_HOSTED_AUTO_INSTALL_KEYS, {+ catalogRoot: resolveBundledCatalogRoot({}),+ env: {},+ enforceCatalogRoot: false,+ });+ // Exactly the pre-refactor default path.+ expect(entry).toEqual({+ key: "kubernetes",+ pluginKey: "paperclip.kubernetes-sandbox-provider",+ localPath: "/app/packages/plugins/sandbox-providers/kubernetes",+ });+ });++ it("covers every catalog entry with a path inside the default root", () => {+ const keys = BUNDLED_PLUGIN_CATALOG.map((entry) => entry.key);+ const resolved = resolveBundledPluginInstalls(keys, {+ catalogRoot: DEFAULT_BUNDLED_CATALOG_ROOT,+ env: {},+ enforceCatalogRoot: true,+ });+ expect(resolved).toHaveLength(BUNDLED_PLUGIN_CATALOG.length);+ });+});++describe("resolveBundledCatalogRoot", () => {+ it("defaults to the image catalog root", () => {+ expect(resolveBundledCatalogRoot({})).toBe(DEFAULT_BUNDLED_CATALOG_ROOT);+ });++ it("honors PAPERCLIP_BUNDLED_PLUGIN_ROOT", () => {+ expect(resolveBundledCatalogRoot({ PAPERCLIP_BUNDLED_PLUGIN_ROOT: "/custom/root" })).toBe(+ "/custom/root",+ );+ });+});++// ---------------------------------------------------------------------------+// ensureBundledPlugins (fail-safe installer)+// ---------------------------------------------------------------------------++function makeDeps(overrides?: {+ rows?: Record<string, { id: string; pluginKey: string; status: string } | null>;+ bundleManifestExists?: (localPath: string) => boolean;+ installError?: Error;+}) {+ const rows = overrides?.rows ?? {};+ const installedRows = new Map(Object.entries(rows));+ const installPlugin = vi.fn(async ({ localPath }: { localPath: string }) => {+ if (overrides?.installError) throw overrides.installError;+ const entry = BUNDLED_PLUGIN_CATALOG.find((candidate) =>+ localPath.endsWith(candidate.relativePath),+ );+ const pluginKey = entry?.pluginKey ?? "unknown";+ installedRows.set(pluginKey, { id: `id-${pluginKey}`, pluginKey, status: "installed" });+ return { manifest: { id: pluginKey } };+ });+ const deps: BundledPluginProvisionerDeps = {+ registry: {+ getByKey: vi.fn(async (pluginKey: string) => installedRows.get(pluginKey) ?? null),+ },+ loader: { installPlugin } as unknown as BundledPluginProvisionerDeps["loader"],+ lifecycle: { load: vi.fn(async () => undefined) },+ logger: { info: vi.fn(), error: vi.fn() },+ bundleManifestExists: overrides?.bundleManifestExists ?? (() => true),+ };+ return { deps, installPlugin };+}++const K8S: ResolvedBundledPlugin = {+ key: "kubernetes",+ pluginKey: "paperclip.kubernetes-sandbox-provider",+ localPath: path.join(CATALOG_ROOT, "sandbox-providers/kubernetes"),+};+const DAYTONA: ResolvedBundledPlugin = {+ key: "daytona",+ pluginKey: "paperclip.daytona-sandbox-provider",+ localPath: path.join(CATALOG_ROOT, "sandbox-providers/daytona"),+};++describe("ensureBundledPlugins", () => {+ it("installs and loads a missing bundled plugin", async () => {+ const { deps, installPlugin } = makeDeps();+ await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: true });+ expect(installPlugin).toHaveBeenCalledWith({ localPath: K8S.localPath });+ expect(deps.lifecycle.load).toHaveBeenCalledWith(+ "id-paperclip.kubernetes-sandbox-provider",+ );+ });++ it("skips a plugin present in any non-uninstalled state (disabled is not re-enabled)", async () => {+ for (const status of ["installed", "ready", "disabled", "error"]) {+ const { deps, installPlugin } = makeDeps({+ rows: {+ [K8S.pluginKey]: { id: "row-1", pluginKey: K8S.pluginKey, status },+ },+ });+ await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: true });+ expect(installPlugin).not.toHaveBeenCalled();+ expect(deps.lifecycle.load).not.toHaveBeenCalled();+ }+ });++ it("reinstalls a soft-uninstalled plugin in managed mode", async () => {+ const { deps, installPlugin } = makeDeps({+ rows: {+ [K8S.pluginKey]: { id: "row-1", pluginKey: K8S.pluginKey, status: "uninstalled" },+ },+ });+ await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: true });+ expect(installPlugin).toHaveBeenCalledOnce();+ });++ it("leaves a soft-uninstalled plugin alone in self-hosted mode (pre-refactor behavior)", async () => {+ const { deps, installPlugin } = makeDeps({+ rows: {+ [K8S.pluginKey]: { id: "row-1", pluginKey: K8S.pluginKey, status: "uninstalled" },+ },+ });+ await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: false });+ expect(installPlugin).not.toHaveBeenCalled();+ });++ it("skips silently when the bundle is absent on disk", async () => {+ const { deps, installPlugin } = makeDeps({ bundleManifestExists: () => false });+ await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: true });+ expect(installPlugin).not.toHaveBeenCalled();+ expect(deps.logger.error).not.toHaveBeenCalled();+ });++ it("logs and continues past a failing install, still processing later entries", async () => {+ const { deps, installPlugin } = makeDeps();+ installPlugin.mockRejectedValueOnce(new Error("disk exploded"));+ await expect(+ ensureBundledPlugins([K8S, DAYTONA], deps, { reinstallUninstalled: true }),+ ).resolves.toBeUndefined();+ expect(deps.logger.error).toHaveBeenCalledWith(+ expect.objectContaining({ pluginKey: K8S.pluginKey }),+ expect.stringContaining("continuing boot"),+ );+ // Daytona still installed after the kubernetes failure.+ expect(installPlugin).toHaveBeenCalledTimes(2);+ expect(deps.lifecycle.load).toHaveBeenCalledWith("id-paperclip.daytona-sandbox-provider");+ });++ it("never uninstalls anything: plugins absent from the list are untouched", async () => {+ const { deps, installPlugin } = makeDeps({+ rows: {+ [DAYTONA.pluginKey]: { id: "row-d", pluginKey: DAYTONA.pluginKey, status: "ready" },+ },+ });+ // Daytona was removed from the autoInstall list; only kubernetes remains.+ await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: true });+ expect(installPlugin).toHaveBeenCalledOnce();+ expect(installPlugin).toHaveBeenCalledWith({ localPath: K8S.localPath });+ // No uninstall/unload calls exist on the provisioner deps at all; daytona+ // was never queried beyond its own key and its row is untouched.+ expect(deps.lifecycle.load).toHaveBeenCalledTimes(1);+ });++ it("logs an error and does not load when install returns no manifest", async () => {+ const { deps, installPlugin } = makeDeps();+ installPlugin.mockResolvedValueOnce({ manifest: null });+ await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: true });+ expect(deps.logger.error).toHaveBeenCalledWith(+ expect.objectContaining({ pluginKey: K8S.pluginKey }),+ expect.stringContaining("manifest is missing"),+ );+ expect(deps.lifecycle.load).not.toHaveBeenCalled();+ });++ it("logs an error when the installed plugin never appears in the registry", async () => {+ const { deps, installPlugin } = makeDeps();+ (deps.registry.getByKey as ReturnType<typeof vi.fn>).mockResolvedValue(null);+ await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: true });+ expect(installPlugin).toHaveBeenCalledOnce();+ expect(deps.logger.error).toHaveBeenCalledWith(+ expect.objectContaining({ pluginKey: K8S.pluginKey }),+ expect.stringContaining("not found in registry"),+ );+ expect(deps.lifecycle.load).not.toHaveBeenCalled();+ });++ it("checks the real bundle manifest path by default (dist/manifest.js)", async () => {+ const bundleDir = makeTempDir("bundled-bundle-");+ const { deps, installPlugin } = makeDeps();+ delete deps.bundleManifestExists;+ const install = { ...K8S, localPath: bundleDir };+ await ensureBundledPlugins([install], deps, { reinstallUninstalled: true });+ expect(installPlugin).not.toHaveBeenCalled();+ mkdirSync(path.join(bundleDir, "dist"), { recursive: true });+ writeFileSync(path.join(bundleDir, "dist", "manifest.js"), "module.exports = {}\n");+ await ensureBundledPlugins([install], deps, { reinstallUninstalled: true });+ expect(installPlugin).toHaveBeenCalledOnce();+ });+});diff --git a/server/src/app.ts b/server/src/app.tsindex 26bcefd866..cca5958cae 100644--- a/server/src/app.ts+++ b/server/src/app.ts@@ -64,6 +64,12 @@ import { readBrandedStaticIndexHtml } from "./static-index-html.js";import { applyUiBranding } from "./ui-branding.js";import { logger } from "./middleware/logger.js";import { DEFAULT_LOCAL_PLUGIN_DIR, pluginLoader } from "./services/plugin-loader.js";+import {+ SELF_HOSTED_AUTO_INSTALL_KEYS,+ ensureBundledPlugins,+ resolveBundledCatalogRoot,+ resolveBundledPluginInstalls,+} from "./services/bundled-plugins.js";import { createPluginWorkerManager, type PluginWorkerManager } from "./services/plugin-worker-manager.js";import { createPluginJobScheduler } from "./services/plugin-job-scheduler.js";import { pluginJobStore } from "./services/plugin-job-store.js";@@ -170,6 +176,15 @@ export async function createApp(pluginWorkerManager?: PluginWorkerManager;betterAuthHandler?: express.RequestHandler;resolveSession?: (req: ExpressRequest) => Promise<BetterAuthSessionResult | null>;+ /**+ * `plugins.autoInstall` from the managed config (PAPERCLIP_MANAGED_CONFIG).+ * `null`/absent ⇒ self-hosted: only the built-in kubernetes bundle is+ * ensured, exactly as before. A managed list is resolved against the+ * bundled catalog fail-to-start (see services/bundled-plugins.ts).+ */+ managedPluginAutoInstall?: readonly string[] | null;+ /** Test override for the bundled plugin catalog root. */+ bundledPluginCatalogRoot?: string;},) {const app = express();@@ -536,65 +551,51 @@ export async function createApp(lifecycle,async (pluginId) => (await pluginRegistry.getById(pluginId))?.packagePath ?? null,);- // Auto-install the bundled kubernetes sandbox-provider plugin so the- // "kubernetes" sandbox provider is registered for agent runs. The plugin is- // excluded from the pnpm workspace and built standalone into the image (see- // Dockerfile), then installed here from its local path. This runs BEFORE- // loadAll() so loadAll() can activate it in the same startup pass.+ // Auto-provision bundled plugins so their providers are registered for+ // agent runs. Bundles are excluded from the pnpm+ // workspace and built standalone into the image (see Dockerfile), then+ // installed here from their local paths. This runs BEFORE loadAll() so+ // loadAll() can activate them in the same startup pass.//- // SAFETY (invariant B): this is fully fail-safe. Any failure (missing path,- // install error, load error) is caught, logged, and swallowed so the server- // ALWAYS finishes booting. A degraded boot (no kubernetes provider, agents- // cannot run) is strictly preferable to a crash loop.- const ensureBundledKubernetesPlugin = async (): Promise<void> => {- const KUBERNETES_PLUGIN_KEY = "paperclip.kubernetes-sandbox-provider";- const pluginPath =- process.env["PAPERCLIP_KUBERNETES_PLUGIN_PATH"] ??- "/app/packages/plugins/sandbox-providers/kubernetes";- try {- // Idempotent: skip if already installed (any non-uninstalled status).- const existing = await pluginRegistry.getByKey(KUBERNETES_PLUGIN_KEY);- if (existing) {- logger.info(- { pluginKey: KUBERNETES_PLUGIN_KEY, status: existing.status },- "kubernetes sandbox plugin already installed; skipping auto-install",- );- return;- }- // Skip silently when the bundle is absent (e.g. local dev or an image- // built without the plugin). Not an error condition.- if (!fs.existsSync(path.join(pluginPath, "dist", "manifest.js"))) {- logger.info(- { pluginPath },- "kubernetes sandbox plugin bundle not present; skipping auto-install",- );- return;- }- logger.info({ pluginPath }, "auto-installing bundled kubernetes sandbox plugin");- const discovered = await loader.installPlugin({ localPath: pluginPath });- if (!discovered.manifest) {- logger.error("kubernetes sandbox plugin installed but manifest is missing");- return;- }- // Transition installed -> ready and activate the worker.- const installed = await pluginRegistry.getByKey(discovered.manifest.id);- if (installed) {- await lifecycle.load(installed.id);- logger.info(- { pluginId: installed.id, pluginKey: installed.pluginKey },- "kubernetes sandbox plugin auto-installed and loaded",- );- } else {- logger.error("kubernetes sandbox plugin installed but not found in registry");- }- } catch (err) {- logger.error(- { err },- "Failed to auto-install the kubernetes sandbox plugin; continuing boot (degraded: kubernetes provider unavailable)",- );- }- };- void ensureBundledKubernetesPlugin()+ // Workers are started exactly once, by loadAll(): the `lifecycle` manager+ // above is constructed without a runtime-capable loader+ // (pluginLifecycleManager(db, { workerManager }) — no `loader` option), so+ // the lifecycle.load() that ensureBundledPlugins performs per newly+ // installed bundle only records the `ready` status and does not spawn a+ // worker (see activateReadyPlugin in services/plugin-lifecycle.ts).+ //+ // Managed instances (`plugins.autoInstall` from PAPERCLIP_MANAGED_CONFIG)+ // drive the key list from the control plane; self-hosted instances keep+ // the pre-existing behavior of ensuring only the kubernetes bundle.+ //+ // Resolution below is deliberately synchronous and NOT fail-safe: an+ // unknown key or a path escaping the bundled catalog root throws out of+ // createApp so a managed instance refuses to start (positive allowlist,+ // fail closed).+ const managedAutoInstallKeys = opts.managedPluginAutoInstall ?? null;+ const bundledCatalogRoot =+ opts.bundledPluginCatalogRoot ?? resolveBundledCatalogRoot(process.env);+ const bundledPluginInstalls = resolveBundledPluginInstalls(+ managedAutoInstallKeys ?? SELF_HOSTED_AUTO_INSTALL_KEYS,+ {+ catalogRoot: bundledCatalogRoot,+ env: process.env,+ enforceCatalogRoot: managedAutoInstallKeys !== null,+ },+ );+ // SAFETY: installation is fully fail-safe. Any failure+ // (missing bundle, install error, load error) is caught, logged, and+ // swallowed per plugin so the server ALWAYS finishes booting. A degraded+ // boot (a provider unavailable, some agents cannot run) is strictly+ // preferable to a crash loop.+ void ensureBundledPlugins(+ bundledPluginInstalls,+ { registry: pluginRegistry, loader, lifecycle, logger },+ // Managed mode reinstalls soft-uninstalled bundles (the control plane+ // owns provisioning); self-hosted leaves an operator's uninstall alone.+ // Operator-DISABLED plugins are never touched in either mode.+ { reinstallUninstalled: managedAutoInstallKeys !== null },+ ).then(() => loader.loadAll()).then((result) => {if (!result) return;diff --git a/server/src/index.ts b/server/src/index.tsindex 03f6104a3f..f89f06e98b 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -33,7 +33,10 @@ import detectPort from "detect-port";import { createApp } from "./app.js";import { loadConfig } from "./config.js";import { logger } from "./middleware/logger.js";-import { getManagedInstanceConfig } from "./services/managed-config.js";+import {+ getManagedInstanceConfig,+ type ManagedInstanceConfig,+} from "./services/managed-config.js";import { setupEnvironmentCustomImageTerminalWebSocketServer } from "./realtime/environment-custom-image-terminal-ws.js";import { setupLiveEventsWebSocketServer } from "./realtime/live-events-ws.js";import {@@ -595,8 +598,9 @@ export async function startServer(): Promise<StartedServer> {// overlays it per read. This MUST run before any instanceSettingsService(db)// construction — that constructor parses the same env, and it would otherwise// throw first, bypassing this fail-closed log path.+ let managedConfig: ManagedInstanceConfig | null;try {- const managedConfig = getManagedInstanceConfig();+ managedConfig = getManagedInstanceConfig();if (managedConfig) {logger.warn({@@ -691,6 +695,10 @@ export async function startServer(): Promise<StartedServer> {}};const pluginWorkerManager = createPluginWorkerManager();+ // Managed instances drive bundled plugin auto-install from the managed-config+ // document parsed fail-closed above (`plugins.autoInstall`). Absent env means+ // self-hosted: createApp falls back to its built-in kubernetes-only default.+ const managedPluginAutoInstall = managedConfig?.plugins.autoInstall ?? null;const app = await createApp(db as any, {uiMode,serverPort: listenPort,@@ -724,6 +732,7 @@ export async function startServer(): Promise<StartedServer> {betterAuthHandler,resolveSession,pluginWorkerManager,+ managedPluginAutoInstall,});const server = createServer(app as unknown as Parameters<typeof createServer>[0]);diff --git a/server/src/services/bundled-plugins.ts b/server/src/services/bundled-plugins.tsnew file mode 100644index 0000000000..a3c27a7e26--- /dev/null+++ b/server/src/services/bundled-plugins.ts@@ -0,0 +1,297 @@+import path from "node:path";+import fs from "node:fs";++/**+ * Bundled plugin auto-provisioning.+ *+ * Managed-cloud instances receive a `plugins.autoInstall` key list through+ * `PAPERCLIP_MANAGED_CONFIG` (parsed fail-closed at startup — see+ * `managed-config.ts`). Each key maps to a plugin bundled into+ * the release image under the bundled catalog root. Nobody "installs" on a+ * managed instance: the control plane provisions, tenants use.+ *+ * Two distinct failure postures, deliberately split:+ *+ * 1. **Resolution (this file, `resolveBundledPluginInstalls`) fails to+ * start.** An unknown key or a path that escapes the bundled catalog+ * root is a configuration/security violation — a positive allowlist,+ * not a lookup. Throwing here happens+ * synchronously inside `createApp`, before the server listens, so a bad+ * document refuses to start rather than silently widening what code can+ * be loaded into the host.+ *+ * 2. **Installation (`ensureBundledPlugins`) is fail-safe.**+ * Missing bundle on disk, install error, load error: caught, logged,+ * and swallowed per entry so the server ALWAYS finishes booting. A+ * degraded boot (one provider unavailable) is strictly preferable to a+ * crash loop across a fleet.+ *+ * Removal of a key from `autoInstall` stops future installs but never+ * auto-uninstalls: there is intentionally no uninstall+ * path anywhere in this module.+ */++/** Default location of the bundled plugin catalog inside the release image. */+export const DEFAULT_BUNDLED_CATALOG_ROOT = "/app/packages/plugins";++/**+ * Env var that relocates the bundled catalog root (dev images, tests).+ */+export const BUNDLED_CATALOG_ROOT_ENV_VAR = "PAPERCLIP_BUNDLED_PLUGIN_ROOT";++export interface BundledPluginCatalogEntry {+ /** Key the managed config's `plugins.autoInstall` list uses. */+ key: string;+ /** Manifest id / registry `pluginKey` the bundle installs as. */+ pluginKey: string;+ /** Bundle location relative to the bundled catalog root. */+ relativePath: string;+ /**+ * Legacy absolute-path override honored for compatibility (the kubernetes+ * bundle predates the catalog). Overrides are still subject to catalog+ * containment when enforcement is on.+ */+ pathOverrideEnvVar?: string;+}++/**+ * The positive allowlist of plugins the control plane may auto-provision.+ * Keys outside this table can never be installed through this path,+ * regardless of what the managed config document says.+ */+export const BUNDLED_PLUGIN_CATALOG: readonly BundledPluginCatalogEntry[] = [+ {+ key: "cloudflare",+ pluginKey: "paperclip.cloudflare-sandbox-provider",+ relativePath: "sandbox-providers/cloudflare",+ },+ {+ key: "daytona",+ pluginKey: "paperclip.daytona-sandbox-provider",+ relativePath: "sandbox-providers/daytona",+ },+ {+ key: "e2b",+ pluginKey: "paperclip.e2b-sandbox-provider",+ relativePath: "sandbox-providers/e2b",+ },+ {+ key: "exe-dev",+ pluginKey: "paperclip.exe-dev-sandbox-provider",+ relativePath: "sandbox-providers/exe-dev",+ },+ {+ key: "kubernetes",+ pluginKey: "paperclip.kubernetes-sandbox-provider",+ relativePath: "sandbox-providers/kubernetes",+ pathOverrideEnvVar: "PAPERCLIP_KUBERNETES_PLUGIN_PATH",+ },+ {+ key: "modal",+ pluginKey: "paperclip.modal-sandbox-provider",+ relativePath: "sandbox-providers/modal",+ },+ {+ key: "novita",+ pluginKey: "paperclip.novita-sandbox-provider",+ relativePath: "sandbox-providers/novita",+ },+];++/**+ * Keys ensured on a self-hosted instance (no managed config present).+ * Exactly the pre-refactor behavior: the kubernetes sandbox provider is+ * auto-installed when its bundle is present, nothing else.+ */+export const SELF_HOSTED_AUTO_INSTALL_KEYS: readonly string[] = ["kubernetes"];++export function resolveBundledCatalogRoot(+ env: Record<string, string | undefined>,+): string {+ const override = env[BUNDLED_CATALOG_ROOT_ENV_VAR]?.trim();+ return override ? override : DEFAULT_BUNDLED_CATALOG_ROOT;+}++export interface ResolvedBundledPlugin {+ key: string;+ pluginKey: string;+ /** Absolute path handed to `loader.installPlugin({ localPath })`. */+ localPath: string;+}++/**+ * Canonicalize a path for containment comparison. Symlinks are resolved+ * when the path exists so a link inside the catalog cannot point install+ * resolution at a directory outside it; nonexistent paths fall back to a+ * lexical resolve (`..` segments still collapse).+ */+function canonicalize(p: string): string {+ const resolved = path.resolve(p);+ try {+ return fs.realpathSync(resolved);+ } catch {+ return resolved;+ }+}++function isInsideRoot(candidate: string, root: string): boolean {+ const rel = path.relative(root, candidate);+ return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));+}++/**+ * Resolve auto-install keys to concrete bundle paths.+ *+ * Throws — and the instance must refuse to start — when a key is not in+ * the bundled catalog, or when `enforceCatalogRoot` is set and the+ * resolved path escapes the catalog root. Callers pass+ * `enforceCatalogRoot: true` for managed (control-plane-driven) key lists+ * and `false` for the self-hosted built-in list, where the legacy+ * kubernetes path override may point anywhere (unchanged behavior).+ */+export function resolveBundledPluginInstalls(+ keys: readonly string[],+ opts: {+ catalogRoot: string;+ env: Record<string, string | undefined>;+ enforceCatalogRoot: boolean;+ },+): ResolvedBundledPlugin[] {+ const resolved: ResolvedBundledPlugin[] = [];+ const seen = new Set<string>();+ const canonicalRoot = canonicalize(opts.catalogRoot);+ for (const key of keys) {+ if (seen.has(key)) continue;+ seen.add(key);+ const entry = BUNDLED_PLUGIN_CATALOG.find((candidate) => candidate.key === key);+ if (!entry) {+ const known = BUNDLED_PLUGIN_CATALOG.map((candidate) => candidate.key).join(", ");+ throw new Error(+ `bundled plugin auto-install key "${key}" is not in the bundled catalog (known keys: ${known}); refusing to start`,+ );+ }+ const override = entry.pathOverrideEnvVar+ ? opts.env[entry.pathOverrideEnvVar]?.trim()+ : undefined;+ const localPath = override+ ? path.resolve(override)+ : path.resolve(opts.catalogRoot, entry.relativePath);+ if (opts.enforceCatalogRoot && !isInsideRoot(canonicalize(localPath), canonicalRoot)) {+ throw new Error(+ `bundled plugin "${key}" resolves to "${localPath}", outside the bundled catalog root "${opts.catalogRoot}"; refusing to start`,+ );+ }+ resolved.push({ key: entry.key, pluginKey: entry.pluginKey, localPath });+ }+ return resolved;+}++interface RegistryPluginRow {+ id: string;+ pluginKey: string;+ status: string;+}++export interface BundledPluginProvisionerDeps {+ registry: {+ getByKey(pluginKey: string): Promise<RegistryPluginRow | null>;+ };+ loader: {+ installPlugin(options: { localPath: string }): Promise<{+ manifest: { id: string } | null;+ }>;+ };+ lifecycle: {+ load(pluginId: string): Promise<unknown>;+ };+ logger: {+ info(obj: unknown, msg?: string): void;+ error(obj: unknown, msg?: string): void;+ };+ /** Overridable for tests; defaults to checking `dist/manifest.js`. */+ bundleManifestExists?: (localPath: string) => boolean;+}++function defaultBundleManifestExists(localPath: string): boolean {+ return fs.existsSync(path.join(localPath, "dist", "manifest.js"));+}++/**+ * Ensure each resolved bundled plugin is installed and loaded.+ *+ * Same mechanism the kubernetes bundle has always used: in-process+ * `loader.installPlugin({ localPath })` at boot — no HTTP, no user, no+ * role. Fully fail-safe per entry: any disk/install/load+ * failure is caught, logged, and swallowed so boot always completes.+ *+ * Skip semantics:+ * - A plugin present in any non-uninstalled state is skipped, so an+ * operator-disabled plugin is not silently re-enabled on reboot.+ * - A soft-uninstalled plugin is reinstalled only when+ * `reinstallUninstalled` is set (managed mode, where the control plane+ * owns provisioning). Self-hosted keeps the pre-refactor behavior of+ * leaving an operator's uninstall alone.+ */+export async function ensureBundledPlugins(+ installs: readonly ResolvedBundledPlugin[],+ deps: BundledPluginProvisionerDeps,+ opts: { reinstallUninstalled: boolean },+): Promise<void> {+ const bundleManifestExists = deps.bundleManifestExists ?? defaultBundleManifestExists;+ for (const install of installs) {+ try {+ const existing = await deps.registry.getByKey(install.pluginKey);+ if (existing && (existing.status !== "uninstalled" || !opts.reinstallUninstalled)) {+ deps.logger.info(+ { pluginKey: install.pluginKey, status: existing.status },+ "bundled plugin already present; skipping auto-install",+ );+ continue;+ }+ // Skip silently when the bundle is absent (e.g. local dev or an image+ // built without the plugin). Not an error condition.+ if (!bundleManifestExists(install.localPath)) {+ deps.logger.info(+ { pluginKey: install.pluginKey, pluginPath: install.localPath },+ "bundled plugin bundle not present; skipping auto-install",+ );+ continue;+ }+ deps.logger.info(+ { pluginKey: install.pluginKey, pluginPath: install.localPath },+ "auto-installing bundled plugin",+ );+ const discovered = await deps.loader.installPlugin({ localPath: install.localPath });+ if (!discovered.manifest) {+ deps.logger.error(+ { pluginKey: install.pluginKey },+ "bundled plugin installed but manifest is missing",+ );+ continue;+ }+ // Transition installed -> ready. Whether this also starts the worker+ // depends on the injected lifecycle manager: one built with a+ // runtime-capable loader activates here; the boot-time manager in+ // app.ts is not, so at startup this only records `ready` and the+ // worker is started exactly once by the subsequent loader.loadAll().+ const installed = await deps.registry.getByKey(discovered.manifest.id);+ if (installed) {+ await deps.lifecycle.load(installed.id);+ deps.logger.info(+ { pluginId: installed.id, pluginKey: installed.pluginKey },+ "bundled plugin auto-installed and loaded",+ );+ } else {+ deps.logger.error(+ { pluginKey: install.pluginKey },+ "bundled plugin installed but not found in registry",+ );+ }+ } catch (err) {+ deps.logger.error(+ { err, pluginKey: install.pluginKey },+ "Failed to auto-install bundled plugin; continuing boot (degraded: plugin unavailable)",+ );+ }+ }+}