@alfe.ai/integrations 0.3.0 → 0.3.1

package/dist/index.d.ts

@@ -314,9 +314,17 @@ declare class Installer {
 interface RuntimeApplier {
   /** The runtime identifier (e.g. 'openclaw', 'nanoclaw') */
   readonly runtime: string;
-  /** Install a plugin package into this runtime */
+  /**
+   * Install a plugin package into this runtime.
+   *
+   * `opts.integrationId` identifies the owning integration so the applier can
+   * distinguish a legitimate same-integration pin bump from a cross-integration
+   * pin conflict (two integrations pinning the same plugin at different
+   * versions). See `OpenClawApplier`'s first-writer-wins guard.
+   */
   applyPlugin(pkg: string, integrationInstallPath: string, opts?: {
     force?: boolean;
+    integrationId?: string;
   }): Promise<void>;
   /**
    * Optional: pre-trust an integration's full plugin set in one write before
@@ -995,6 +1003,24 @@ declare class OpenClawApplier implements RuntimeApplier {
    * this instance performed (0 = never). See HEAL_MIN_INTERVAL_MS.
    */
   private lastHealAt;
+  /**
+   * Cross-integration plugin-pin claims made during THIS process lifetime,
+   * keyed by bare package name. `applyPlugin` is now version-aware for both
+   * force and non-force callers — it actively reinstalls a plugin whose
+   * installed version differs from the pinned spec (previously the non-force
+   * path keyed only on bare-name presence and silently ignored a pin bump). If
+   * two integrations pin the SAME plugin at DIFFERENT versions, that
+   * version-aware reinstall would make them fight — each reconcile pass
+   * uninstall+reinstalls the other's version forever. This map records the
+   * first-applied pin per package so a later, divergent pin from a DIFFERENT
+   * integration is refused (first-writer-wins) with a WARN instead of thrashing.
+   * A later apply from the SAME integration (a legitimate pin bump across an
+   * upgrade) is NOT a conflict and proceeds. Cleared per-package on
+   * `removePlugin`, and wholesale on daemon restart. Convention is single-owner
+   * per plugin (see the `alfe` manifest note) — this only turns a convention
+   * violation into a stable warning.
+   */
+  private readonly appliedPluginPins;
   constructor(options: OpenClawApplierOptions);
   /**
    * Convenience: `openclaw config set <args>`, UNLOCKED + retried.
@@ -1080,8 +1106,16 @@ declare class OpenClawApplier implements RuntimeApplier {
   private healMalformedStateDb;
   applyPlugin(spec: string, _installPath?: string, opts?: {
     force?: boolean;
+    integrationId?: string;
   }): Promise<void>;
   private applyPluginLocked;
+  /**
+   * Record the pin a caller just applied for a package, keyed by bare name, so
+   * a later divergent pin from a DIFFERENT integration in this process can be
+   * refused (first-writer-wins). Bare (versionless) pins are untrackable and
+   * ignored — they can't conflict on version. See `appliedPluginPins`.
+   */
+  private recordPluginPin;
   /**
    * Ensure one or more plugins are in plugins.allow in openclaw.json, UNLOCKED.
    * Uses `openclaw config set` to avoid clobbering OpenClaw's own file format.

package/dist/index.js

@@ -1271,7 +1271,10 @@ var IntegrationManager = class {
 				for (const plugin of plugins) {
 					this.log.info(`Applying plugin ${plugin.package} to ${runtimeName}`);
 					try {
-						await applier.applyPlugin(plugin.package, installPath, { force: opts?.forcePlugins });
+						await applier.applyPlugin(plugin.package, installPath, {
+							force: opts?.forcePlugins,
+							integrationId
+						});
 					} catch (err) {
 						const msg = err instanceof Error ? err.message : String(err);
 						this.log.error(`Failed to apply plugin ${plugin.package}: ${msg}`);
@@ -2301,6 +2304,24 @@ var OpenClawApplier = class {
 	* this instance performed (0 = never). See HEAL_MIN_INTERVAL_MS.
 	*/
 	lastHealAt = 0;
+	/**
+	* Cross-integration plugin-pin claims made during THIS process lifetime,
+	* keyed by bare package name. `applyPlugin` is now version-aware for both
+	* force and non-force callers — it actively reinstalls a plugin whose
+	* installed version differs from the pinned spec (previously the non-force
+	* path keyed only on bare-name presence and silently ignored a pin bump). If
+	* two integrations pin the SAME plugin at DIFFERENT versions, that
+	* version-aware reinstall would make them fight — each reconcile pass
+	* uninstall+reinstalls the other's version forever. This map records the
+	* first-applied pin per package so a later, divergent pin from a DIFFERENT
+	* integration is refused (first-writer-wins) with a WARN instead of thrashing.
+	* A later apply from the SAME integration (a legitimate pin bump across an
+	* upgrade) is NOT a conflict and proceeds. Cleared per-package on
+	* `removePlugin`, and wholesale on daemon restart. Convention is single-owner
+	* per plugin (see the `alfe` manifest note) — this only turns a convention
+	* violation into a stable warning.
+	*/
+	appliedPluginPins = /* @__PURE__ */ new Map();
 	constructor(options) {
 		const home = options.home ?? options.workspace;
 		if (!home) throw new Error("OpenClawApplier requires `home` (or legacy `workspace`) option");
@@ -2484,25 +2505,43 @@ var OpenClawApplier = class {
 	}
 	async applyPluginLocked(spec, opts) {
 		const pkg = stripPluginVersion(spec);
+		const pinnedVersion = pluginSpecVersion(spec);
+		const claim = this.appliedPluginPins.get(pkg);
+		if (pinnedVersion !== void 0 && claim !== void 0 && claim.version !== pinnedVersion && claim.integrationId !== opts?.integrationId) {
+			log$3.warn({
+				pkg,
+				requestedVersion: pinnedVersion,
+				keptVersion: claim.version,
+				requestedBy: opts?.integrationId,
+				ownedBy: claim.integrationId
+			}, "Conflicting plugin pin across integrations — keeping the first-applied version (first-writer-wins)");
+			return;
+		}
 		await this.ensurePluginsAllowUnlocked(pkg);
 		this.cleanupUntrackedExtensionInstall(pkg);
-		if (opts?.force && this.isPluginInstalled(pkg)) {
-			const pinnedVersion = pluginSpecVersion(spec);
+		if (this.isPluginInstalled(pkg)) {
 			const installedVersion = this.installedPluginVersion(pkg);
-			if (pinnedVersion && installedVersion && installedVersion === pinnedVersion) {
-				log$3.info({
+			const versionsComparable = pinnedVersion !== void 0 && installedVersion !== void 0;
+			if (versionsComparable && installedVersion === pinnedVersion) {
+				if (opts?.force) log$3.info({
 					pkg,
 					spec,
 					version: installedVersion
 				}, "Force mode — installed version already matches pinned spec, skipping uninstall+reinstall");
+				this.recordPluginPin(pkg, pinnedVersion, opts?.integrationId);
+				return;
+			}
+			if (!(versionsComparable && installedVersion !== pinnedVersion) && !opts?.force) {
+				this.recordPluginPin(pkg, pinnedVersion, opts?.integrationId);
 				return;
 			}
 			log$3.info({
 				pkg,
 				spec,
 				installedVersion,
-				pinnedVersion
-			}, "Force mode — uninstalling plugin before reinstall");
+				pinnedVersion,
+				force: opts?.force ?? false
+			}, "Reinstalling plugin to converge on the pinned version");
 			try {
 				await this.removePluginUnlocked(pkg);
 			} catch (err) {
@@ -2510,7 +2549,7 @@ var OpenClawApplier = class {
 					pkg,
 					spec,
 					err: err instanceof Error ? err.message : String(err)
-				}, "Failed to uninstall plugin during force reinstall — proceeding");
+				}, "Failed to uninstall plugin before reinstall — proceeding");
 			}
 		}
 		if (!this.isPluginInstalled(pkg)) {
@@ -2547,6 +2586,20 @@ var OpenClawApplier = class {
 				setTimeout(r, 500);
 			});
 		}
+		this.recordPluginPin(pkg, pinnedVersion, opts?.integrationId);
+	}
+	/**
+	* Record the pin a caller just applied for a package, keyed by bare name, so
+	* a later divergent pin from a DIFFERENT integration in this process can be
+	* refused (first-writer-wins). Bare (versionless) pins are untrackable and
+	* ignored — they can't conflict on version. See `appliedPluginPins`.
+	*/
+	recordPluginPin(pkg, version, integrationId) {
+		if (version === void 0) return;
+		this.appliedPluginPins.set(pkg, {
+			version,
+			integrationId
+		});
 	}
 	/**
 	* Ensure one or more plugins are in plugins.allow in openclaw.json, UNLOCKED.
@@ -2692,6 +2745,7 @@ var OpenClawApplier = class {
 	*/
 	async removePluginUnlocked(spec) {
 		const pkg = stripPluginVersion(spec);
+		this.appliedPluginPins.delete(pkg);
 		await this.execOpenClawHealing([
 			"plugins",
 			"uninstall",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integrations",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",