fix(plugins): enforce minimum host versions for installable plugins (#52094)

vincentkoc · web-flow · commit 3ce5a8366a67 · 2026-03-22T09:12:08.000-07:00
* fix(plugins): enforce min host versions

* fix(plugins): tighten min host version validation

* chore(plugins): trim dead min host version code

* fix(plugins): handle malformed min host metadata

* fix(plugins): key manifest cache by host version
diff --git a/extensions/bluebubbles/package.json b/extensions/bluebubbles/package.json
@@ -42,7 +42,8 @@
     "install": {
       "npmSpec": "@openclaw/bluebubbles",
       "localPath": "extensions/bluebubbles",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "release": {
       "publishToNpm": true
diff --git a/extensions/discord/package.json b/extensions/discord/package.json
@@ -39,7 +39,8 @@
     "install": {
       "npmSpec": "@openclaw/discord",
       "localPath": "extensions/discord",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "bundle": {
       "stageRuntimeDependencies": true
diff --git a/extensions/feishu/package.json b/extensions/feishu/package.json
@@ -41,7 +41,8 @@
     "install": {
       "npmSpec": "@openclaw/feishu",
       "localPath": "extensions/feishu",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "bundle": {
       "stageRuntimeDependencies": true
diff --git a/extensions/googlechat/package.json b/extensions/googlechat/package.json
@@ -40,7 +40,8 @@
     "install": {
       "npmSpec": "@openclaw/googlechat",
       "localPath": "extensions/googlechat",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     }
   }
 }
diff --git a/extensions/irc/package.json b/extensions/irc/package.json
@@ -10,6 +10,9 @@
     "extensions": [
       "./index.ts"
     ],
+    "install": {
+      "minHostVersion": ">=2026.3.14"
+    },
     "setupEntry": "./setup-entry.ts",
     "channel": {
       "id": "irc",
diff --git a/extensions/line/package.json b/extensions/line/package.json
@@ -33,7 +33,8 @@
     "install": {
       "npmSpec": "@openclaw/line",
       "localPath": "extensions/line",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     }
   }
 }
diff --git a/extensions/matrix/package.json b/extensions/matrix/package.json
@@ -40,7 +40,8 @@
     "install": {
       "npmSpec": "@openclaw/matrix",
       "localPath": "extensions/matrix",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "releaseChecks": {
       "rootDependencyMirrorAllowlist": [
diff --git a/extensions/mattermost/package.json b/extensions/mattermost/package.json
@@ -35,7 +35,8 @@
     "install": {
       "npmSpec": "@openclaw/mattermost",
       "localPath": "extensions/mattermost",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     }
   }
 }
diff --git a/extensions/memory-lancedb/package.json b/extensions/memory-lancedb/package.json
@@ -15,7 +15,8 @@
     "install": {
       "npmSpec": "@openclaw/memory-lancedb",
       "localPath": "extensions/memory-lancedb",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "release": {
       "publishToNpm": true
diff --git a/extensions/msteams/package.json b/extensions/msteams/package.json
@@ -39,7 +39,8 @@
     "install": {
       "npmSpec": "@openclaw/msteams",
       "localPath": "extensions/msteams",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "release": {
       "publishToNpm": true
diff --git a/extensions/nextcloud-talk/package.json b/extensions/nextcloud-talk/package.json
@@ -39,7 +39,8 @@
     "install": {
       "npmSpec": "@openclaw/nextcloud-talk",
       "localPath": "extensions/nextcloud-talk",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "release": {
       "publishToNpm": true
diff --git a/extensions/nostr/package.json b/extensions/nostr/package.json
@@ -36,7 +36,8 @@
     "install": {
       "npmSpec": "@openclaw/nostr",
       "localPath": "extensions/nostr",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "release": {
       "publishToNpm": true
diff --git a/extensions/synology-chat/package.json b/extensions/synology-chat/package.json
@@ -23,7 +23,8 @@
     "install": {
       "npmSpec": "@openclaw/synology-chat",
       "localPath": "extensions/synology-chat",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     }
   }
 }
diff --git a/extensions/tlon/package.json b/extensions/tlon/package.json
@@ -39,7 +39,8 @@
     "install": {
       "npmSpec": "@openclaw/tlon",
       "localPath": "extensions/tlon",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     }
   }
 }
diff --git a/extensions/twitch/package.json b/extensions/twitch/package.json
@@ -13,6 +13,9 @@
     "extensions": [
       "./index.ts"
     ],
+    "install": {
+      "minHostVersion": ">=2026.3.14"
+    },
     "channel": {
       "id": "twitch",
       "label": "Twitch",
diff --git a/extensions/voice-call/package.json b/extensions/voice-call/package.json
@@ -24,6 +24,9 @@
     "extensions": [
       "./index.ts"
     ],
+    "install": {
+      "minHostVersion": ">=2026.3.14"
+    },
     "release": {
       "publishToNpm": true
     }
diff --git a/extensions/whatsapp/package.json b/extensions/whatsapp/package.json
@@ -35,7 +35,8 @@
     "install": {
       "npmSpec": "@openclaw/whatsapp",
       "localPath": "extensions/whatsapp",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "release": {
       "publishToNpm": true
diff --git a/extensions/zalo/package.json b/extensions/zalo/package.json
@@ -39,7 +39,8 @@
     "install": {
       "npmSpec": "@openclaw/zalo",
       "localPath": "extensions/zalo",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "release": {
       "publishToNpm": true
diff --git a/extensions/zalouser/package.json b/extensions/zalouser/package.json
@@ -40,7 +40,8 @@
     "install": {
       "npmSpec": "@openclaw/zalouser",
       "localPath": "extensions/zalouser",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.14"
     },
     "release": {
       "publishToNpm": true
diff --git a/scripts/lib/bundled-extension-manifest.ts b/scripts/lib/bundled-extension-manifest.ts
@@ -1,12 +1,16 @@
+import { validateMinHostVersion } from "../../src/plugins/min-host-version.ts";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
 export type ExtensionPackageJson = {
   name?: string;
   version?: string;
   dependencies?: Record<string, string>;
   optionalDependencies?: Record<string, string>;
   openclaw?: {
-    install?: {
-      npmSpec?: string;
-    };
+    install?: unknown;
   };
 };
 
@@ -17,14 +21,25 @@ export function collectBundledExtensionManifestErrors(extensions: BundledExtensi
 
   for (const extension of extensions) {
     const install = extension.packageJson.openclaw?.install;
+    if (install !== undefined && !isRecord(install)) {
+      errors.push(
+        `bundled extension '${extension.id}' manifest invalid | openclaw.install must be an object`,
+      );
+      continue;
+    }
+    const hasNpmSpec = isRecord(install) && "npmSpec" in install;
     if (
-      install &&
+      hasNpmSpec &&
       (!install.npmSpec || typeof install.npmSpec !== "string" || !install.npmSpec.trim())
     ) {
       errors.push(
         `bundled extension '${extension.id}' manifest invalid | openclaw.install.npmSpec must be a non-empty string`,
       );
     }
+    const minHostVersionError = validateMinHostVersion(install?.minHostVersion);
+    if (minHostVersionError) {
+      errors.push(`bundled extension '${extension.id}' manifest invalid | ${minHostVersionError}`);
+    }
   }
 
   return errors;
diff --git a/src/plugins/install-min-host-version-guardrails.test.ts b/src/plugins/install-min-host-version-guardrails.test.ts
@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { isAtLeast, parseSemver } from "../infra/runtime-guard.js";
+import { parseMinHostVersionRequirement } from "./min-host-version.js";
+
+const MIN_HOST_VERSION_BASELINE = "2026.3.14";
+const PLUGIN_MANIFEST_PATHS_REQUIRING_MIN_HOST_VERSION = [
+  "extensions/bluebubbles/package.json",
+  "extensions/discord/package.json",
+  "extensions/feishu/package.json",
+  "extensions/googlechat/package.json",
+  "extensions/irc/package.json",
+  "extensions/line/package.json",
+  "extensions/matrix/package.json",
+  "extensions/mattermost/package.json",
+  "extensions/memory-lancedb/package.json",
+  "extensions/msteams/package.json",
+  "extensions/nextcloud-talk/package.json",
+  "extensions/nostr/package.json",
+  "extensions/synology-chat/package.json",
+  "extensions/tlon/package.json",
+  "extensions/twitch/package.json",
+  "extensions/voice-call/package.json",
+  "extensions/whatsapp/package.json",
+  "extensions/zalo/package.json",
+  "extensions/zalouser/package.json",
+] as const;
+
+type PackageJsonLike = {
+  openclaw?: {
+    install?: {
+      minHostVersion?: string;
+    };
+  };
+};
+
+describe("install minHostVersion guardrails", () => {
+  it("requires published plugins that depend on new sdk subpaths to declare a host floor", () => {
+    const baseline = parseSemver(MIN_HOST_VERSION_BASELINE);
+    expect(baseline).not.toBeNull();
+    if (!baseline) {
+      return;
+    }
+
+    for (const relativePath of PLUGIN_MANIFEST_PATHS_REQUIRING_MIN_HOST_VERSION) {
+      const manifest = JSON.parse(
+        fs.readFileSync(path.resolve(relativePath), "utf-8"),
+      ) as PackageJsonLike;
+      const requirement = parseMinHostVersionRequirement(
+        manifest.openclaw?.install?.minHostVersion,
+      );
+
+      expect(
+        requirement,
+        `${relativePath} should declare openclaw.install.minHostVersion`,
+      ).not.toBeNull();
+      if (!requirement) {
+        continue;
+      }
+      const minimum = parseSemver(requirement.minimumLabel);
+      expect(minimum, `${relativePath} should use a parseable semver floor`).not.toBeNull();
+      if (!minimum) {
+        continue;
+      }
+      expect(
+        isAtLeast(minimum, baseline),
+        `${relativePath} should require at least OpenClaw ${MIN_HOST_VERSION_BASELINE}`,
+      ).toBe(true);
+    }
+  });
+});
diff --git a/src/plugins/install.test.ts b/src/plugins/install.test.ts
diff --git a/src/plugins/install.ts b/src/plugins/install.ts
diff --git a/src/plugins/manifest-registry.test.ts b/src/plugins/manifest-registry.test.ts
diff --git a/src/plugins/manifest-registry.ts b/src/plugins/manifest-registry.ts
diff --git a/src/plugins/manifest.ts b/src/plugins/manifest.ts
diff --git a/src/plugins/min-host-version.test.ts b/src/plugins/min-host-version.test.ts
diff --git a/src/plugins/min-host-version.ts b/src/plugins/min-host-version.ts
diff --git a/test/release-check.test.ts b/test/release-check.test.ts

Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,8 @@`
`40`	`40`	`"install": {`
`41`	`41`	`"npmSpec": "@openclaw/googlechat",`
`42`	`42`	`"localPath": "extensions/googlechat",`
`43`		`- "defaultChoice": "npm"`
	`43`	`+ "defaultChoice": "npm",`
	`44`	`+ "minHostVersion": ">=2026.3.14"`
`44`	`45`	`}`
`45`	`46`	`}`
`46`	`47`	`}`
Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,8 @@`
`33`	`33`	`"install": {`
`34`	`34`	`"npmSpec": "@openclaw/line",`
`35`	`35`	`"localPath": "extensions/line",`
`36`		`- "defaultChoice": "npm"`
	`36`	`+ "defaultChoice": "npm",`
	`37`	`+ "minHostVersion": ">=2026.3.14"`
`37`	`38`	`}`
`38`	`39`	`}`
`39`	`40`	`}`
Original file line number	Diff line number	Diff line change
`@@ -35,7 +35,8 @@`
`35`	`35`	`"install": {`
`36`	`36`	`"npmSpec": "@openclaw/mattermost",`
`37`	`37`	`"localPath": "extensions/mattermost",`
`38`		`- "defaultChoice": "npm"`
	`38`	`+ "defaultChoice": "npm",`
	`39`	`+ "minHostVersion": ">=2026.3.14"`
`39`	`40`	`}`
`40`	`41`	`}`
`41`	`42`	`}`