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
feat(environments): expose boot-relevant drift attribution in the custom-image overview (#11751)
Nicky Leachb8a76081ece9
diff --git a/server/src/__tests__/environment-custom-images-service.test.ts b/server/src/__tests__/environment-custom-images-service.test.tsindex 335c1e6142..f3f986c406 100644--- a/server/src/__tests__/environment-custom-images-service.test.ts+++ b/server/src/__tests__/environment-custom-images-service.test.ts@@ -865,6 +865,52 @@ describeEmbeddedPostgres("environmentCustomImageService reconciliation", () => {const outOfSync = await service.getOverview({ environmentId });expect(outOfSync.activeTemplate).not.toBeNull();expect(outOfSync.activeTemplateMatchesConfig).toBe(false);+ // A boot-source field changed, so the overview attributes the drift and+ // names the field with its `from`/`to` values.+ expect(outOfSync.activeTemplateDrift?.classification).toBe("boot_source_drift");+ expect(outOfSync.activeTemplateDrift?.driftedPaths).toEqual(+ expect.arrayContaining([{ path: "image", from: "fake:base", to: "fake:other" }]),+ );+ });++ it("attributes a knob-only overview change without naming a boot-source field", async () => {+ const { environmentId } = await seed();+ const workerManager = createWorkerManager();+ const service = environmentCustomImageService(db, { pluginWorkerManager: workerManager });++ const started = await service.startSetupSession({ environmentId, actor: { userId: "user-1" } });+ await service.finishSetupSession({ sessionId: started.session.id });++ // A non-boot-relevant field changes. The fingerprint no longer matches, but+ // every boot-source value still matches, so the drift is knob-only.+ await db.update(environments)+ .set({ config: { provider: "fake-plugin", image: "fake:base", reuseLease: false, region: "eu" } })+ .where(eq(environments.id, environmentId));+ const overview = await service.getOverview({ environmentId });+ expect(overview.activeTemplateMatchesConfig).toBe(false);+ expect(overview.activeTemplateDrift?.classification).toBe("knob_only");+ expect(overview.activeTemplateDrift?.driftedPaths).toEqual([]);+ });++ it("attributes an unclassified overview drift for a legacy template with no snapshot", async () => {+ const { environmentId } = await seed();+ const service = environmentCustomImageService(db, { pluginWorkerManager: createWorkerManager() });+ // A legacy template carries no boot-relevant snapshot. The overview must+ // fail closed and give no false "safe to relink" signal.+ await db.insert(environmentCustomImageTemplates).values({+ environmentId,+ provider: "fake-plugin",+ templateKind: "snapshot",+ templateRef: "snapshot-legacy",+ sourceEnvironmentConfigFingerprint: "stale-fingerprint",+ status: "active",+ metadata: { runtimeConfigBinding: { field: "customTemplate", unsetFields: ["image"] } },+ });++ const overview = await service.getOverview({ environmentId });+ expect(overview.activeTemplate).not.toBeNull();+ expect(overview.activeTemplateDrift?.classification).toBe("unclassified");+ expect(overview.activeTemplateDrift?.driftedPaths).toEqual([]);});});@@ -1107,6 +1153,45 @@ describeEmbeddedPostgres("environmentCustomImageService relink", () => {expect(activityJson).not.toContain(promoted.template.sourceEnvironmentConfigFingerprint);});+ it("keeps secret values and the fingerprint out of the overview payload", async () => {+ const config = {+ provider: "fake-secret-plugin",+ image: "fake:base",+ apiUrl: "https://secret-endpoint.example",+ auth: "auth-secret-value",+ credentials: { secret: "cred-secret-value", region: "eu" },+ reuseLease: false,+ };+ const { environmentId } = await seed({ manifest: secretPluginManifest(), config });+ const service = environmentCustomImageService(db, { pluginWorkerManager: createWorkerManager() });++ const started = await service.startSetupSession({ environmentId, actor: { userId: "user-1" } });+ const promoted = await service.finishSetupSession({ sessionId: started.session.id });++ // A boot-source field changes, so the overview reports drift and carries the+ // drifted paths. The payload must never leak a secret value or a fingerprint.+ await db.update(environments)+ .set({ config: { ...config, image: "fake:other" } })+ .where(eq(environments.id, environmentId));+ const overview = await service.getOverview({ environmentId });+ // An excluded secret-ref path forces the fail-closed unclassified result.+ expect(overview.activeTemplateDrift?.classification).toBe("unclassified");+ // The full overview never leaks a secret value, and the server-internal+ // snapshot never reaches the template response.+ const overviewJson = JSON.stringify(overview);+ expect(overviewJson).not.toContain("secret-endpoint.example");+ expect(overviewJson).not.toContain("auth-secret-value");+ expect(overviewJson).not.toContain("cred-secret-value");+ expect(overviewJson).not.toContain("bootRelevantConfig");+ // The drift attribution carries path names and non-secret values only, never+ // a fingerprint value.+ const driftJson = JSON.stringify(overview.activeTemplateDrift);+ expect(driftJson).not.toContain(promoted.template.sourceEnvironmentConfigFingerprint);+ expect(driftJson).not.toContain("secret-endpoint.example");+ expect(driftJson).not.toContain("auth-secret-value");+ expect(driftJson).not.toContain("cred-secret-value");+ });+it("fails closed for legacy templates without a boot-relevant snapshot", async () => {const { companyId, environmentId } = await seed();const service = environmentCustomImageService(db, { pluginWorkerManager: createWorkerManager() });diff --git a/server/src/services/environment-custom-images.ts b/server/src/services/environment-custom-images.tsindex d481ebfacb..b7101ec01b 100644--- a/server/src/services/environment-custom-images.ts+++ b/server/src/services/environment-custom-images.ts@@ -52,6 +52,7 @@ import {environmentCustomImageTemplateFromRow,readEnvironmentCustomImageTemplateKind as readTemplateKind,type EnvironmentCustomImageRelinkClassification,+ type EnvironmentCustomImageDriftedPath,} from "./environment-custom-image-runtime.js";import { logActivity } from "./activity-log.js";import type { PluginWorkerManager } from "./plugin-worker-manager.js";@@ -73,10 +74,23 @@ export interface EnvironmentCustomImageOverview {* active template, or the config could not be evaluated).*/activeTemplateMatchesConfig: boolean | null;+ /**+ * Boot-relevant drift attribution for the active template. It classifies the+ * drift between the capture-time boot-relevant snapshot and the current+ * config, and lists the drifted paths with their `from`/`to` values. The UI+ * uses it to name the changed field instead of only "configuration changed".+ * `null` when there is no active template or the driver is not `sandbox`.+ */+ activeTemplateDrift: EnvironmentCustomImageActiveTemplateDrift | null;activeSession: EnvironmentCustomImageSetupSession | null;latestSession: EnvironmentCustomImageSetupSession | null;}+export interface EnvironmentCustomImageActiveTemplateDrift {+ classification: EnvironmentCustomImageRelinkClassification;+ driftedPaths: EnvironmentCustomImageDriftedPath[];+}+export type EnvironmentCustomImageReconciliation =| { action: "none" }| { action: "relinked"; template: EnvironmentCustomImageTemplate }@@ -643,21 +657,75 @@ export function environmentCustomImageService(}}+ /**+ * Computes the boot-relevant drift attribution for the active template row.+ * It reuses the relink wiring: it reads the snapshot from the row metadata,+ * resolves the current provider contract, and passes the current parsed+ * config. A driver that no longer resolves fails closed (null contract, so+ * `unclassified`). Returns `null` when there is no active template or the+ * driver is not `sandbox`.+ */+ async function computeActiveTemplateDrift(+ environment: Environment,+ activeRow: typeof environmentCustomImageTemplates.$inferSelect | null,+ ): Promise<EnvironmentCustomImageActiveTemplateDrift | null> {+ if (!activeRow) return null;+ let parsed: ReturnType<typeof parseEnvironmentDriverConfig>;+ try {+ parsed = parseEnvironmentDriverConfig(environment);+ } catch {+ return null;+ }+ if (parsed.driver !== "sandbox") return null;+ const active = environmentCustomImageTemplateFromRow(activeRow);+ // Resolve the current provider contract so the classifier can reject a+ // snapshot captured against a different binding or identity-path set. A+ // driver that no longer resolves fails closed (null contract).+ const resolvedDriver = await resolvePluginSandboxProviderDriverByKey({+ db,+ driverKey: active.provider,+ });+ const currentContract = resolvedDriver+ ? {+ binding: templateConfigBindingFromDriver({+ templateRefKind: active.templateKind,+ templateConfigBinding: resolvedDriver.driver.templateConfigBinding,+ }),+ templateIdentityPaths: resolvedDriver.driver.templateIdentityPaths ?? [],+ }+ : null;+ // The persisted snapshot is server-internal; read it from the row, not the+ // sanitized template response.+ const drift = classifyEnvironmentCustomImageBootRelevantDrift({+ bootRelevantConfig: readEnvironmentCustomImageBootRelevantConfig(activeRow.metadata),+ currentConfig: parsed.config,+ currentContract,+ });+ return {+ classification: drift.classification,+ driftedPaths: drift.driftedPaths,+ };+ }+return {getOverview: async (input: {environmentId: string;}): Promise<EnvironmentCustomImageOverview> => {const environment = await requireEnvironment(input.environmentId);- const [activeTemplate, activeSession, latestSession] = await Promise.all([- resolveActiveTemplate(db, input),+ const [activeRow, activeSession, latestSession] = await Promise.all([+ resolveActiveTemplateRow(db, input),getActiveSetupSession(input),getLatestSetupSession(input),]);+ const activeTemplate = activeRow+ ? environmentCustomImageTemplateFromRow(activeRow)+ : null;return {activeTemplate,activeTemplateMatchesConfig: activeTemplate? await templateMatchesEnvironmentConfig(environment, activeTemplate): null,+ activeTemplateDrift: await computeActiveTemplateDrift(environment, activeRow),activeSession,latestSession,};diff --git a/ui/src/api/environments.ts b/ui/src/api/environments.tsindex 46ca219291..b823ccd299 100644--- a/ui/src/api/environments.ts+++ b/ui/src/api/environments.ts@@ -20,10 +20,22 @@ export interface EnvironmentCustomImageOverview {* back to the base image until a new image is captured. `null` when unknown.*/activeTemplateMatchesConfig?: boolean | null;+ /**+ * Boot-relevant drift attribution for the active template. It names the+ * classification and the drifted paths with their `from`/`to` values, so the+ * banner can name the changed field. `null` or absent when there is no active+ * template or the driver is not `sandbox`.+ */+ activeTemplateDrift?: EnvironmentCustomImageActiveTemplateDrift | null;activeSession: EnvironmentCustomImageSetupSession | null;latestSession: EnvironmentCustomImageSetupSession | null;}+export interface EnvironmentCustomImageActiveTemplateDrift {+ classification: EnvironmentCustomImageRelinkClassification;+ driftedPaths: EnvironmentCustomImageDriftedPath[];+}+export type EnvironmentCustomImageReconciliation =| { action: "relinked"; template: EnvironmentCustomImageTemplate }| { action: "detached"; template: EnvironmentCustomImageTemplate };diff --git a/ui/src/pages/CompanyEnvironments.test.tsx b/ui/src/pages/CompanyEnvironments.test.tsxindex 13b27924eb..e99e2ea236 100644--- a/ui/src/pages/CompanyEnvironments.test.tsx+++ b/ui/src/pages/CompanyEnvironments.test.tsx@@ -1316,6 +1316,65 @@ describe("CompanyEnvironments — test provider button", () => {});});+ it("names the changed boot-source field in the out-of-sync banner for a boot-source drift", async () => {+ root = createRoot(container);+ const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });+ mockEnvironmentsApi.list.mockResolvedValue([+ { id: "env-1", name: "Daytona", driver: "sandbox", description: null, config: { provider: "daytona" } },+ ]);+ mockEnvironmentsApi.capabilities.mockResolvedValue(supportedDaytonaCapabilities());+ mockEnvironmentsApi.customImageTemplate.mockResolvedValue({+ activeTemplate: createTemplate({ id: "template-active" }),+ activeTemplateMatchesConfig: false,+ activeTemplateDrift: {+ classification: "boot_source_drift",+ driftedPaths: [{ path: "snapshot", from: "a", to: "b" }],+ },+ activeSession: null,+ latestSession: null,+ });++ await act(async () => {+ root!.render(renderCompanyEnvironments(queryClient));+ });+ await flushReact();++ await act(async () => click(editButtons(container)[0]));+ await waitForAssertion(() => {+ const dialog = getEnvironmentFormPage()!;+ expect(dialog.textContent).toContain("Not in use — Base image changed: snapshot `a` -> `b`");+ expect(dialog.textContent).not.toContain("the environment configuration changed");+ });+ });++ it("keeps the generic out-of-sync banner for an unclassified drift", async () => {+ root = createRoot(container);+ const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });+ mockEnvironmentsApi.list.mockResolvedValue([+ { id: "env-1", name: "Daytona", driver: "sandbox", description: null, config: { provider: "daytona" } },+ ]);+ mockEnvironmentsApi.capabilities.mockResolvedValue(supportedDaytonaCapabilities());+ mockEnvironmentsApi.customImageTemplate.mockResolvedValue({+ activeTemplate: createTemplate({ id: "template-active" }),+ activeTemplateMatchesConfig: false,+ activeTemplateDrift: { classification: "unclassified", driftedPaths: [{ path: "apiUrl" }] },+ activeSession: null,+ latestSession: null,+ });++ await act(async () => {+ root!.render(renderCompanyEnvironments(queryClient));+ });+ await flushReact();++ await act(async () => click(editButtons(container)[0]));+ await waitForAssertion(() => {+ const dialog = getEnvironmentFormPage()!;+ expect(dialog.textContent).toContain("Not in use — the environment configuration changed");+ expect(dialog.textContent).not.toContain("Base image changed");+ });+ });+it("does not show the out-of-sync warning when the active template matches the saved config", async () => {root = createRoot(container);const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });diff --git a/ui/src/pages/CompanyEnvironments.tsx b/ui/src/pages/CompanyEnvironments.tsxindex 570d0d0dd7..0113f2913a 100644--- a/ui/src/pages/CompanyEnvironments.tsx+++ b/ui/src/pages/CompanyEnvironments.tsx@@ -20,6 +20,7 @@ import {} from "@paperclipai/shared";import {environmentsApi,+ type EnvironmentCustomImageActiveTemplateDrift,type EnvironmentCustomImageConnectionPayload,type EnvironmentCustomImageRelinkConflict,type EnvironmentCustomImageSetupSessionResult,@@ -290,6 +291,33 @@ function formatShortId(value: string): string {return `${normalized.slice(0, 12)}…`;}+function formatBootSourceDriftValue(value: unknown): string {+ if (typeof value === "string") return value;+ if (value === null || value === undefined) return "none";+ return JSON.stringify(value);+}++/**+ * Builds the drift summary for a `boot_source_drift` overview. It names each+ * changed boot-source field with its `from` and `to` values (example: "snapshot+ * `a` -> `b`"). It uses only value-bearing paths; an excluded path carries the+ * name only, so the summary omits it. Returns `null` when no value-bearing path+ * is present, so the banner keeps the generic text.+ */+function formatBootSourceDriftSummary(+ drift: EnvironmentCustomImageActiveTemplateDrift | null | undefined,+): string | null {+ if (!drift || drift.classification !== "boot_source_drift") return null;+ const parts = drift.driftedPaths+ .filter((entry) => "from" in entry || "to" in entry)+ .map(+ (entry) =>+ `${entry.path} \`${formatBootSourceDriftValue(entry.from)}\` -> \`${formatBootSourceDriftValue(entry.to)}\``,+ );+ if (parts.length === 0) return null;+ return `Base image changed: ${parts.join("; ")}`;+}+function readConnectionCommand(payload: EnvironmentCustomImageConnectionPayload | null | undefined): string | null {return typeof payload?.command === "string" && payload.command.trim().length > 0? payload.command@@ -1129,6 +1157,7 @@ function EnvironmentImageTemplatePanel({if (activeTemplate) {const templateRef = activeTemplate.templateRef?.trim() || null;const templateOutOfSync = overview?.activeTemplateMatchesConfig === false;+ const bootSourceDriftSummary = formatBootSourceDriftSummary(overview?.activeTemplateDrift);return (<div className="mt-3 border-t border-border/60 pt-3" data-testid={`custom-image-template-state-${environment.id}`}><div className="flex flex-wrap items-start justify-between gap-3">@@ -1153,9 +1182,9 @@ function EnvironmentImageTemplatePanel({className="text-xs text-destructive"data-testid={`custom-image-template-out-of-sync-${environment.id}`}>- Not in use — the environment configuration changed since this image was- captured. Runs fall back to the base configuration until you relink this- image or capture a new one.+ {bootSourceDriftSummary+ ? `Not in use — ${bootSourceDriftSummary}. Runs fall back to the base configuration until you relink this image or capture a new one.`+ : "Not in use — the environment configuration changed since this image was captured. Runs fall back to the base configuration until you relink this image or capture a new one."}</div>) : null}</div>