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 <noreply@paperclip.ing>
This commit is contained in:
Devin FoleyandPaperclip authored and GitHub committed 2026-11-19 09:26:06 -08:00
1 parent b7177db6aa
commit 417802ca87
9 files changed
+146 -5

No files matched your search

+8
View File
@@ -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`
@@ -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 [
@@ -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: {
@@ -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<void>(resolve => { release = () => { manifestUpdated = true; resolve(); }; });
qualify.mockImplementation(async () => {
expect(manifestUpdated).toBe(true);
return { configurationPackagesEligible: true };
});
const result = qualifyCloudConfigurationForCurrentImage({} as Parameters<typeof qualifyCloudConfigurationForCurrentImage>[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<typeof qualifyCloudConfigurationForCurrentImage>[0], {
runtimeEnv: { PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "tenant-fixture" }, bundledManifestsReady: Promise.reject(new Error("refresh failed")),
})).rejects.toThrow("refresh failed");
expect(qualify).not.toHaveBeenCalled();
});
+4 -2
View File
@@ -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;
+3 -1
View File
@@ -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(", ")}`);
}
@@ -7,6 +7,10 @@ import { assertDistributionManifestCapabilities } from "./distribution-plugin-ca
export type BundledPluginRegistration = Pick<PluginRecord, "pluginKey" | "packageName" | "version" | "manifestJson">;
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,
+25 -1
View File
@@ -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<string, unknown>;
const removeDescription = (value: unknown) => {
if (value && typeof value === "object" && !Array.isArray(value)) {
const object = value as Record<string, unknown>;
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,
@@ -10,9 +10,11 @@ import { pluginLoader } from "./plugin-loader.js";
export async function qualifyCloudConfigurationForCurrentImage(db: Db, options: {
runtimeEnv?: CloudInstanceEnv;
expectedPackageEvidenceDigest?: string;
bundledManifestsReady?: Promise<unknown>;
} = {}) {
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[];