From 417802ca872e719f32ad447d7e69a8b77a802fd3 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Thu, 19 Nov 2026 09:26:06 -0800 Subject: [PATCH] fix(plugins): refresh unchanged-version bundle descriptions (#22295) Refresh known display descriptions in same-version bundled plugin registrations only when every behavioral field matches. Compare manifests in their persisted JSON form and await bundle reconciliation before final volume-free package qualification. Verified 77 focused tests, server typechecking, and all 59 successful PR checks. Greptile 5/5 with no unresolved review comments. Co-Authored-By: Paperclip --- doc/plugins/DISTRIBUTION-PLUGINS.md | 8 +++ .../__tests__/bundled-plugin-package.test.ts | 11 ++++ server/src/__tests__/bundled-plugins.test.ts | 55 +++++++++++++++++++ .../cloud-configuration-qualification.test.ts | 33 +++++++++++ server/src/app.ts | 6 +- server/src/index.ts | 4 +- server/src/services/bundled-plugin-package.ts | 6 +- server/src/services/bundled-plugins.ts | 26 ++++++++- .../cloud-configuration-qualification.ts | 2 + 9 files changed, 146 insertions(+), 5 deletions(-) create mode 100644 server/src/__tests__/cloud-configuration-qualification.test.ts diff --git a/doc/plugins/DISTRIBUTION-PLUGINS.md b/doc/plugins/DISTRIBUTION-PLUGINS.md index 28e8476a953..b77cbaa8a86 100644 --- a/doc/plugins/DISTRIBUTION-PLUGINS.md +++ b/doc/plugins/DISTRIBUTION-PLUGINS.md @@ -5,6 +5,14 @@ built-in catalog. The operator owns the image and trusts its plugin code. This is packaging and activation policy, not a sandbox or entitlement system. Ordinary self-hosted images need no catalog and keep their existing behavior. +Built-in Core plugins also refresh stored display descriptions at startup when +the installed version matches the image. This covers the plugin description, +environment-driver descriptions, and direct config-property help text. All other +manifest fields must match, including permissions, entrypoints, schema rules, +and default values. Pending approval and uninstall states retain their existing +behavior. This refresh updates metadata without restarting a worker. Volume-free +qualification still requires the complete stored manifest to match the image. + ## Image layout Use `distribution/catalog.json` beneath `PAPERCLIP_BUNDLED_PLUGIN_ROOT` diff --git a/server/src/__tests__/bundled-plugin-package.test.ts b/server/src/__tests__/bundled-plugin-package.test.ts index 367006a2c65..3fb557ee989 100644 --- a/server/src/__tests__/bundled-plugin-package.test.ts +++ b/server/src/__tests__/bundled-plugin-package.test.ts @@ -5,6 +5,7 @@ import { bundledImageFixture } from "./helpers/bundled-image-fixture.js"; import { createBundledPluginPackageResolver } from "../services/bundled-plugin-package.js"; import { BUNDLED_PLUGIN_CATALOG, resolveBundledPluginInstalls } from "../services/bundled-plugins.js"; import { readDistributionPluginCatalog } from "../services/distribution-plugin-catalog.js"; +import { pluginManifestValidator } from "../services/plugin-manifest-validator.js"; import boxd from "../../../packages/plugins/sandbox-providers/boxd/src/manifest.js"; import createos from "../../../packages/plugins/sandbox-providers/createos/src/manifest.js"; @@ -39,6 +40,16 @@ describe("bundled image package identity", () => { expect(resolver.inspect(registration, manifest)).toMatchObject({ compatible: true, identity: { kind: "bundled_image", catalogKey: "fixture", pluginKey: manifest.id, version: "1.0.0" } }); }); + it("compares parsed optional fields in the JSON form that registrations store", () => { + const { resolver, registration, manifest } = fixture(); + const parsed = pluginManifestValidator().parseOrThrow({ ...manifest, capabilities: kubernetes.capabilities, environmentDrivers: kubernetes.environmentDrivers }); + expect(Object.hasOwn(parsed.environmentDrivers![0]!, "supportsLoginPty")).toBe(true); + const stored = JSON.parse(JSON.stringify(parsed)); + expect(Object.hasOwn(stored.environmentDrivers[0], "supportsLoginPty")).toBe(false); + expect(resolver.inspect({ ...registration, manifestJson: stored }, parsed)).toMatchObject({ compatible: true }); + expect(resolver.inspect({ ...registration, manifestJson: stored }, { ...parsed, description: "changed" })).toMatchObject({ compatible: false }); + }); + it("rejects mismatched package names, versions, identity and escaping entrypoints", () => { const { resolver, registration } = fixture(); for (const update of [ diff --git a/server/src/__tests__/bundled-plugins.test.ts b/server/src/__tests__/bundled-plugins.test.ts index fb755a476c7..937248aac29 100644 --- a/server/src/__tests__/bundled-plugins.test.ts +++ b/server/src/__tests__/bundled-plugins.test.ts @@ -2,6 +2,8 @@ import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node import os from "node:os"; import path from "node:path"; import { afterAll, describe, expect, it, vi } from "vitest"; +import { pluginManifestValidator } from "../services/plugin-manifest-validator.js"; +import kubernetes from "../../../packages/plugins/sandbox-providers/kubernetes/src/manifest.js"; import { BUNDLED_PLUGIN_CATALOG, DEFAULT_BUNDLED_CATALOG_ROOT, @@ -415,6 +417,59 @@ describe("ensureBundledPlugins", () => { ); }); + it.each(["plugin", "driver", "setting"] as const)("refreshes only a %s description for an existing Core bundle at the same version", async (field) => { + const previous = { ...makeManifest(DAYTONA.pluginKey, "0.1.0"), description: "Old plugin description", + environmentDrivers: [{ driverKey: "daytona", kind: "sandbox_provider" as const, displayName: "Daytona", description: "Old driver description", + configSchema: { type: "object", properties: { autoStopInterval: { type: "number", description: "Old setting description" } } } }] }; + const manifest = structuredClone(previous); + if (field === "plugin") manifest.description = "New plugin description"; + if (field === "driver") manifest.environmentDrivers[0]!.description = "New driver description"; + if (field === "setting") manifest.environmentDrivers[0]!.configSchema.properties.autoStopInterval.description = "New setting description"; + const { deps, loadManifest, update, installPlugin } = makeDeps({ rows: { [DAYTONA.pluginKey]: { + id: "row-daytona", pluginKey: DAYTONA.pluginKey, status: "ready", version: "0.1.0", manifestJson: previous, + } } }); + loadManifest.mockResolvedValue(manifest); + await ensureBundledPlugins([DAYTONA], deps, { reinstallUninstalled: false }); + expect(update).toHaveBeenCalledExactlyOnceWith("row-daytona", { version: "0.1.0", manifest }); + expect(installPlugin).not.toHaveBeenCalled(); + }); + + it("refreshes a parsed Core bundle against a JSON-persisted registration without repeated writes", async () => { + const manifest = pluginManifestValidator().parseOrThrow(kubernetes); + const stored = JSON.parse(JSON.stringify(manifest)); stored.description = "Previous help text"; + const { deps, loadManifest, update } = makeDeps({ rows: { [K8S.pluginKey]: { + id: "row-kubernetes", pluginKey: K8S.pluginKey, status: "ready", version: manifest.version, manifestJson: stored, + } } }); + loadManifest.mockResolvedValue(manifest); + await ensureBundledPlugins([K8S], deps, { reinstallUninstalled: false }); + expect(update).toHaveBeenCalledExactlyOnceWith("row-kubernetes", { version: manifest.version, manifest }); + const unchanged = makeDeps({ rows: { [K8S.pluginKey]: { + id: "row-kubernetes", pluginKey: K8S.pluginKey, status: "ready", version: manifest.version, manifestJson: JSON.parse(JSON.stringify(manifest)), + } } }); + unchanged.loadManifest.mockResolvedValue(manifest); + await ensureBundledPlugins([K8S], unchanged.deps, { reinstallUninstalled: false }); + expect(unchanged.update).not.toHaveBeenCalled(); + }); + + it.each(["capability", "entrypoint", "schema", "default", "pending-approval", "uninstalled"] as const)("does not treat a %s change as description-only", async (change) => { + const previous = { ...makeManifest(DAYTONA.pluginKey, "0.1.0"), description: "Old description", + entrypoints: { worker: "dist/worker.js" }, + environmentDrivers: [{ driverKey: "daytona", kind: "sandbox_provider" as const, displayName: "Daytona", + configSchema: { type: "object", properties: { config: { type: "object", default: { description: "old runtime value" } } } } }] }; + const manifest = structuredClone(previous); manifest.description = "New description"; + if (change === "capability") manifest.capabilities = ["issues.read"]; + if (change === "entrypoint") manifest.entrypoints.worker = "dist/other.js"; + if (change === "schema") manifest.environmentDrivers[0]!.configSchema.properties.config.type = "string"; + if (change === "default") manifest.environmentDrivers[0]!.configSchema.properties.config.default.description = "new runtime value"; + const { deps, loadManifest, update } = makeDeps({ rows: { [DAYTONA.pluginKey]: { + id: "row-daytona", pluginKey: DAYTONA.pluginKey, status: change === "pending-approval" ? "upgrade_pending" : change === "uninstalled" ? "uninstalled" : "ready", + version: "0.1.0", manifestJson: previous, + } } }); + loadManifest.mockResolvedValue(manifest); + await ensureBundledPlugins([DAYTONA], deps, { reinstallUninstalled: false }); + expect(update).not.toHaveBeenCalled(); + }); + it("does not reconcile when the persisted version already matches the bundle", async () => { const { deps, update } = makeDeps({ rows: { diff --git a/server/src/__tests__/cloud-configuration-qualification.test.ts b/server/src/__tests__/cloud-configuration-qualification.test.ts new file mode 100644 index 00000000000..b618d160b9a --- /dev/null +++ b/server/src/__tests__/cloud-configuration-qualification.test.ts @@ -0,0 +1,33 @@ +import { beforeEach, expect, it, vi } from "vitest"; +import { qualifyCloudConfigurationForCurrentImage } from "../services/cloud-configuration-qualification.js"; + +const { qualify } = vi.hoisted(() => ({ qualify: vi.fn() })); +vi.mock("../services/cloud-configuration-migration.js", () => ({ cloudConfigurationMigrationService: () => ({ qualify }) })); +vi.mock("../services/plugin-loader.js", () => ({ pluginLoader: () => ({ loadManifest: async () => null }) })); + +beforeEach(() => { qualify.mockReset(); }); + +it("waits for a delayed bundled manifest update before qualifying a volume-free image", async () => { + let release!: () => void; + let manifestUpdated = false; + const manifestsReady = new Promise(resolve => { release = () => { manifestUpdated = true; resolve(); }; }); + qualify.mockImplementation(async () => { + expect(manifestUpdated).toBe(true); + return { configurationPackagesEligible: true }; + }); + const result = qualifyCloudConfigurationForCurrentImage({} as Parameters[0], { + runtimeEnv: { PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "tenant-fixture" }, bundledManifestsReady: manifestsReady, + }); + await Promise.resolve(); + expect(qualify).not.toHaveBeenCalled(); + release(); + await expect(result).resolves.toMatchObject({ configurationPackagesEligible: true }); + expect(qualify).toHaveBeenCalledTimes(1); +}); + +it("does not qualify when bundled manifest reconciliation rejects", async () => { + await expect(qualifyCloudConfigurationForCurrentImage({} as Parameters[0], { + runtimeEnv: { PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "tenant-fixture" }, bundledManifestsReady: Promise.reject(new Error("refresh failed")), + })).rejects.toThrow("refresh failed"); + expect(qualify).not.toHaveBeenCalled(); +}); diff --git a/server/src/app.ts b/server/src/app.ts index 87591afcd81..c89df4ef844 100644 --- a/server/src/app.ts +++ b/server/src/app.ts @@ -1451,7 +1451,7 @@ export async function createApp( // that must not outrun plugin availability — managed sandbox environments // (`applyManagedEnvironments`) run before the heartbeat resumes queued // runs — can sequence on it. It never rejects. - const bundledPluginsStartup = ensureBundledPlugins( + const bundledPluginManifestsReady = ensureBundledPlugins( bundledPluginInstalls, { registry: pluginRegistry, loader, lifecycle, logger }, // Managed mode reinstalls soft-uninstalled bundles (the control plane @@ -1459,7 +1459,9 @@ export async function createApp( // Disabled plugins never start automatically. Added distribution permissions // still enter upgrade_pending so enabling them requires an operator decision. { reinstallUninstalled: managedAutoInstallKeys !== null, preservePackagePath: managedAutoInstallKeys !== null }, - ) + ); + app.locals.bundledPluginManifestsReady = trackIdleWork(bundledPluginManifestsReady); + const bundledPluginsStartup = bundledPluginManifestsReady .then(() => loader.loadAll()) .then((result) => { if (!result) return; diff --git a/server/src/index.ts b/server/src/index.ts index fa076227efc..f5e5b79cedb 100644 --- a/server/src/index.ts +++ b/server/src/index.ts @@ -2160,7 +2160,9 @@ async function startServerWithDatabaseTeardown( } if (deploymentListenUrl !== null) { - const qualification = await startupTimeline.precondition("cloud_configuration", () => qualifyCloudConfigurationForCurrentImage(db as any)); + const qualification = await startupTimeline.precondition("cloud_configuration", () => qualifyCloudConfigurationForCurrentImage(db as any, { + bundledManifestsReady: app.locals.bundledPluginManifestsReady, + })); if (qualification && !qualification.configurationPackagesEligible) { throw new Error(`Volume-free server packages are not eligible: ${qualification.blockers.map(blocker => blocker.code).join(", ")}`); } diff --git a/server/src/services/bundled-plugin-package.ts b/server/src/services/bundled-plugin-package.ts index 25367bcacec..0e7d814b030 100644 --- a/server/src/services/bundled-plugin-package.ts +++ b/server/src/services/bundled-plugin-package.ts @@ -7,6 +7,10 @@ import { assertDistributionManifestCapabilities } from "./distribution-plugin-ca export type BundledPluginRegistration = Pick; +export function pluginManifestJson(manifest: PaperclipPluginManifestV1): PaperclipPluginManifestV1 { + return JSON.parse(JSON.stringify(manifest)) as PaperclipPluginManifestV1; +} + export interface BundledPluginPackageIdentity { kind: "bundled_image"; catalogKey: string; @@ -88,7 +92,7 @@ export function createBundledPluginPackageResolver(installs: readonly ResolvedBu const install = byKey.get(plugin.pluginKey)!; if (!verifiedManifest) return { compatible: false, pluginKey: plugin.pluginKey, code: "missing_manifest_evidence", reason: "Image manifest evidence is required" }; assertManifest(install, verifiedManifest); - if (!isDeepStrictEqual(verifiedManifest, plugin.manifestJson)) throw new Error("Approved plugin manifest does not match the image"); + if (!isDeepStrictEqual(pluginManifestJson(verifiedManifest), pluginManifestJson(plugin.manifestJson))) throw new Error("Approved plugin manifest does not match the image"); return { compatible: true, identity: { kind: "bundled_image", catalogKey: install.key, pluginKey: plugin.pluginKey, packageName: plugin.packageName, version: plugin.version, diff --git a/server/src/services/bundled-plugins.ts b/server/src/services/bundled-plugins.ts index cb59fa5cbae..04576779629 100644 --- a/server/src/services/bundled-plugins.ts +++ b/server/src/services/bundled-plugins.ts @@ -2,6 +2,7 @@ import path from "node:path"; import fs from "node:fs"; import { isDeepStrictEqual } from "node:util"; import { isCloudManagedInstance } from "./cloud-instance.js"; +import { pluginManifestJson } from "./bundled-plugin-package.js"; import type { PaperclipPluginManifestV1 } from "@paperclipai/shared"; import { assertDistributionManifestCapabilities, readDistributionPluginCatalog, type DistributionPlugin } from "./distribution-plugin-catalog.js"; @@ -257,6 +258,26 @@ function defaultBundleManifestExists(localPath: string): boolean { return fs.existsSync(path.join(localPath, "dist", "manifest.js")); } +function withoutDisplayDescriptions(manifest: PaperclipPluginManifestV1): unknown { + const copy = pluginManifestJson(manifest) as unknown as Record; + const removeDescription = (value: unknown) => { + if (value && typeof value === "object" && !Array.isArray(value)) { + const object = value as Record; + if (typeof object.description === "string") delete object.description; + } + }; + removeDescription(copy); + if (Array.isArray(copy.environmentDrivers)) for (const driver of copy.environmentDrivers) { + removeDescription(driver); + const schema = driver?.configSchema; + removeDescription(schema); + if (schema?.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)) { + for (const property of Object.values(schema.properties)) removeDescription(property); + } + } + return copy; +} + /** * Reconcile a present bundled plugin's persisted manifest with the shipped * bundle. The bundle is part of the release image, so its manifest is the @@ -294,7 +315,10 @@ async function reconcileBundledPluginManifest( } const rebindPackage = !preservePackagePath && install.distribution && existing.packagePath !== install.localPath && existing.status !== "uninstalled"; const refreshDistribution = install.distribution && !isDeepStrictEqual(bundleManifest, existing.manifestJson); - if (bundleManifest.version === existing.version && !rebindPackage && !requiresApproval && !refreshDistribution) return; + const refreshDescriptions = !install.distribution && !["uninstalled", "upgrade_pending"].includes(existing.status) && + !isDeepStrictEqual(pluginManifestJson(bundleManifest), pluginManifestJson(existing.manifestJson)) && + isDeepStrictEqual(withoutDisplayDescriptions(bundleManifest), withoutDisplayDescriptions(existing.manifestJson)); + if (bundleManifest.version === existing.version && !rebindPackage && !requiresApproval && !refreshDistribution && !refreshDescriptions) return; await deps.registry.update(existing.id, { version: bundleManifest.version, manifest: bundleManifest, diff --git a/server/src/services/cloud-configuration-qualification.ts b/server/src/services/cloud-configuration-qualification.ts index c96c97ae8e5..d505deb59bd 100644 --- a/server/src/services/cloud-configuration-qualification.ts +++ b/server/src/services/cloud-configuration-qualification.ts @@ -10,9 +10,11 @@ import { pluginLoader } from "./plugin-loader.js"; export async function qualifyCloudConfigurationForCurrentImage(db: Db, options: { runtimeEnv?: CloudInstanceEnv; expectedPackageEvidenceDigest?: string; + bundledManifestsReady?: Promise; } = {}) { const env = options.runtimeEnv ?? process.env; if (!isCloudManagedInstance(env)) return null; + await options.bundledManifestsReady; const service = cloudConfigurationMigrationService(db, { runtimeEnv: env }); const catalogRoot = resolveBundledCatalogRoot(env); let installs: ResolvedBundledPlugin[];