@alfe.ai/integrations 0.2.10 → 0.3.0

package/dist/index.d.ts

@@ -230,6 +230,37 @@ declare class Installer {
    * Clone monorepo to a temp dir, extract the subdir to the install path, discard the clone.
    */
   private cloneAndExtractSubdir;
+  /**
+   * Stage a new clone into a transient `.staging-<id>-<rand>` directory under
+   * the base path, WITHOUT touching the live install dir. Runs the same
+   * clone/extract + shared-package + local-dependency install as `install()`,
+   * but leaves the result parked so the caller can swap it in near-atomically
+   * via `commitStaged()`.
+   *
+   * This is the "prepare" half of a diff-based in-place upgrade: the clone +
+   * `npm install` are the slow, network-bound steps and MUST happen while the
+   * runtime is still live (outside the suspension window). Staging under the
+   * base path keeps the eventual `renameSync` on the SAME filesystem so the
+   * swap is near-atomic.
+   *
+   * Before staging, sweeps any orphaned `.staging-*` directories left by a
+   * daemon that was killed mid-upgrade. On any failure the staging dir is
+   * cleaned up (try/finally) so a failed prepare leaves no partial clone.
+   */
+  stage(resolved: ResolvedIntegration): Promise<string>;
+  /**
+   * Commit a previously-staged clone: remove the live install dir and rename
+   * the staged dir into its place. Same-filesystem `renameSync` makes the swap
+   * near-atomic (no window where the install dir is half-populated). Called
+   * inside the runtime-suspension window during a diff-based upgrade.
+   */
+  commitStaged(name: string, stagedPath: string): void;
+  /**
+   * Remove any orphaned `.staging-*` directories under the base path. Called at
+   * the start of `stage()` so a daemon killed mid-upgrade doesn't accumulate
+   * partial clones. Best-effort — a failed removal is logged and skipped.
+   */
+  private sweepStagingDirs;
   /**
    * Update an installed integration to a new version.
    * Removes old install and does a fresh clone.
@@ -383,6 +414,20 @@ declare class McpApplier {
    * bundler reconciles via the store watcher.
    */
   removeForIntegration(integrationId: string): Promise<string[]>;
+  /**
+   * Prune servers owned by this integration whose id is NOT in `keepIds`.
+   * Used by the diff-based upgrade to drop MCP declarations the NEW manifest
+   * no longer includes, while leaving the still-declared servers (and their
+   * working env/credentials) untouched — `applyForIntegration` re-runs
+   * afterwards and refreshes the kept ones idempotently.
+   *
+   * `keepIds` are the manifest's DECLARED ids (`${integrationId}-${server.id}`),
+   * not the ids that successfully applied: a transient credential failure that
+   * skipped a re-registration must not cause prune to delete a server the new
+   * manifest still wants. Pure JSON-store writes — no CLI lock needed. Returns
+   * the ids actually removed.
+   */
+  pruneForIntegration(integrationId: string, keepIds: string[]): Promise<string[]>;
   private resolveEnv;
 }
 //#endregion
@@ -560,6 +605,40 @@ declare class IntegrationManager {
    * If not currently installed, does a normal install + activate.
    */
   reinstall(params: IntegrationInstallParams): Promise<ManagerResponse>;
+  /**
+   * Upgrade an integration to a new version IN PLACE, diff-based, so unchanged
+   * plugins are skipped and the clone + npm work happens BEFORE the runtime is
+   * suspended. This is the fast path for a version bump — `reinstall()` stays
+   * the destructive escape hatch (full uninstall → install → activate) for
+   * repair.
+   *
+   * `opts.onBeforeRuntimeMutation` is the deferred-suspend seam: invoked exactly
+   * once, immediately before the first step that mutates the runtime (Phase 2's
+   * commit). RuntimeGate ownership stays in the gateway; the manager stays
+   * runtime-agnostic.
+   *
+   * Phases:
+   *  0. Guards — no state entry → install + activate; a stale `installing`
+   *     status (daemon killed mid-install) → reinstall recovery; install not
+   *     intact / old manifest unparseable → delegate to `reinstall()` (repair
+   *     stays destructive). Every fallback that can shell the openclaw CLI
+   *     invokes `opts.onBeforeRuntimeMutation` first (at most once — each
+   *     returns before Phase 2's seam).
+   *  1. Prepare (runtime live) — resolve new version, `installer.stage()` the
+   *     clone + npm into `.staging-*`, canonicalize a custom-source manifest on
+   *     the STAGED dir. State untouched (stays active@old) on failure here.
+   *  2. Commit — suspend seam, `installer.commitStaged()` swap, parse new
+   *     manifest + depends_on, `state.update()` (NOT full-replace) preserving
+   *     customConnectionId + refreshing installedAt + NOT touching secrets, run
+   *     new-manifest pre/post_install hooks (gated on supported_agents).
+   *  3. Diff removals — tear down only plugins/skills/config/MCP the NEW
+   *     manifest dropped (and no sibling integration still claims).
+   *  4. Activate with `forcePlugins` — the applier's version-match skip makes
+   *     unchanged plugins nearly free; only changed pins pay the reinstall cost.
+   */
+  upgrade(params: IntegrationInstallParams, opts?: {
+    onBeforeRuntimeMutation?: () => Promise<void>;
+  }): Promise<ManagerResponse>;
   /**
    * Run health checks for one or all integrations.
    */
@@ -610,6 +689,30 @@ declare class IntegrationManager {
   clear(): void;
   private checkHealth;
   private err;
+  /**
+   * Compute the plugin (bare package) names and skill names still claimed by
+   * SOME integration in the CURRENT lock state, keyed by runtime. Both
+   * `deactivate` and `upgrade`'s diff-removal call this AFTER
+   * `lockManager.removeEntries(id)` so "still claimed" means "claimed by
+   * another integration" — the applier must NOT physically remove a plugin/
+   * skill another active integration's manifest still lists.
+   *
+   * Plugin claims match on bare package name (via `stripPluginVersion`) so two
+   * integrations pinning the same plugin at different versions still keep the
+   * one file-system install alive when only one is removed.
+   */
+  private claimedEntriesByRuntime;
+  /**
+   * Phase 3 of `upgrade`: tear down ONLY the plugins/skills/config/MCP servers
+   * the NEW manifest dropped, leaving everything the new version still declares
+   * (and everything a sibling integration still claims) in place. Phase 4's
+   * `activate` re-applies and re-locks the new set immediately after.
+   *
+   * `removeEntries` clears this integration's lock rows and returns what it had;
+   * a candidate removal is skipped when it is EITHER (a) still declared by the
+   * new manifest, or (b) still claimed by another integration.
+   */
+  private applyUpgradeDiffRemovals;
   /**
    * True when the manifest's `supported_agents` (if declared) intersects the
    * registered runtime appliers. Hooks and MCP registration run once per
@@ -1060,6 +1163,18 @@ declare class OpenClawApplier implements RuntimeApplier {
    */
   removeConfig(integrationId: string): Promise<void>;
   private removeConfigLocked;
+  /**
+   * Drop a set of dotted keys from a dot-free parent object via read-drop-write,
+   * UNLOCKED. If the parent becomes empty, `config unset` it; otherwise
+   * `--replace` the shrunk map (siblings survive because they remain in
+   * `remaining`). Warn-tolerant — a failed drop of an already-gone key must not
+   * fail the caller. Shared by `removeConfig` (whole-integration teardown) and
+   * `applyConfig`'s stale-key diff (per-key removal between manifest versions).
+   *
+   * Assumes the shared CLI lock is already held by the calling public method —
+   * the lock is NOT re-entrant, so this stays an `*Unlocked` internal.
+   */
+  private dropSubtreeKeysUnlocked;
   /**
    * Raw single-key config write — `openclaw config set <key> <value>`.
    *
@@ -1402,8 +1517,10 @@ interface IIntegrationManager {
   }[]>;
   /** Install an integration at a specific version with config */
   install(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource): Promise<void>;
-  /** Activate an installed integration */
-  activate(integrationId: string): Promise<{
+  /** Activate an installed integration. `opts.forcePlugins` forces version-drift reinstall of already-installed plugins. */
+  activate(integrationId: string, opts?: {
+    forcePlugins?: boolean;
+  }): Promise<{
     configApplied: boolean;
   }>;
   /** Deactivate a running integration */
@@ -1414,6 +1531,18 @@ interface IIntegrationManager {
   reinstall(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource): Promise<{
     configApplied: boolean;
   }>;
+  /**
+   * Upgrade an integration to a new version IN PLACE (diff-based). Unchanged
+   * plugins are skipped and the clone + npm work happens before the runtime is
+   * suspended. `opts.onBeforeRuntimeMutation` is the deferred-suspend seam:
+   * invoked exactly once, immediately before the first runtime mutation, so the
+   * gateway can defer the RuntimeGate suspend past the slow clone/npm steps.
+   */
+  upgrade(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource, opts?: {
+    onBeforeRuntimeMutation?: () => Promise<void>;
+  }): Promise<{
+    configApplied: boolean;
+  }>;
   /** Check if an integration's install directory and manifest are intact on disk */
   isInstallIntact(integrationId: string): Promise<boolean>;
   /** Get the number of consecutive auto-reinstall attempts */
@@ -1433,7 +1562,9 @@ declare class IntegrationManagerAdapter implements IIntegrationManager {
     installedAt?: string;
   }[]>;
   install(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource): Promise<void>;
-  activate(integrationId: string): Promise<{
+  activate(integrationId: string, opts?: {
+    forcePlugins?: boolean;
+  }): Promise<{
     configApplied: boolean;
   }>;
   deactivate(integrationId: string): Promise<void>;
@@ -1441,6 +1572,11 @@ declare class IntegrationManagerAdapter implements IIntegrationManager {
   reinstall(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource): Promise<{
     configApplied: boolean;
   }>;
+  upgrade(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource, opts?: {
+    onBeforeRuntimeMutation?: () => Promise<void>;
+  }): Promise<{
+    configApplied: boolean;
+  }>;
   isInstallIntact(integrationId: string): Promise<boolean>;
   getReinstallAttempts(integrationId: string): number;
   incrementReinstallAttempts(integrationId: string): void;

package/dist/index.js

@@ -1,5 +1,6 @@
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
+import { randomBytes } from "node:crypto";
 import { basename, dirname, join } from "node:path";
 import { homedir, platform, tmpdir } from "node:os";
 import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
@@ -156,6 +157,13 @@ const log$4 = createLogger("Installer");
 const INTEGRATIONS_DIR = join(homedir(), ".alfe", "integrations");
 const GIT_TIMEOUT_MS = 6e4;
 const NPM_TIMEOUT_MS = 6e4;
+/**
+* Dot-prefix for the transient staging directories used by the diff-based
+* in-place upgrade (`stage()` → `commitStaged()`). Dot-prefixed so `list()`
+* (and the daemon reconcile that consumes it) never mistakes a half-cloned
+* staging dir for a real integration install.
+*/
+const STAGING_PREFIX = ".staging-";
 /** Shared @alfe.ai packages available to all integration hooks */
 const SHARED_PACKAGES = {
 	"@alfe.ai/config": "latest",
@@ -267,6 +275,81 @@ var Installer = class {
 		}
 	}
 	/**
+	* Stage a new clone into a transient `.staging-<id>-<rand>` directory under
+	* the base path, WITHOUT touching the live install dir. Runs the same
+	* clone/extract + shared-package + local-dependency install as `install()`,
+	* but leaves the result parked so the caller can swap it in near-atomically
+	* via `commitStaged()`.
+	*
+	* This is the "prepare" half of a diff-based in-place upgrade: the clone +
+	* `npm install` are the slow, network-bound steps and MUST happen while the
+	* runtime is still live (outside the suspension window). Staging under the
+	* base path keeps the eventual `renameSync` on the SAME filesystem so the
+	* swap is near-atomic.
+	*
+	* Before staging, sweeps any orphaned `.staging-*` directories left by a
+	* daemon that was killed mid-upgrade. On any failure the staging dir is
+	* cleaned up (try/finally) so a failed prepare leaves no partial clone.
+	*/
+	async stage(resolved) {
+		mkdirSync(this.basePath, { recursive: true });
+		this.sweepStagingDirs();
+		const stagingPath = join(this.basePath, `${STAGING_PREFIX}${resolved.id}-${randomBytes(6).toString("hex")}`);
+		if (existsSync(stagingPath)) rmSync(stagingPath, {
+			recursive: true,
+			force: true
+		});
+		try {
+			if (resolved.subdir) await this.cloneAndExtractSubdir(resolved, stagingPath);
+			else await this.cloneDirect(resolved, stagingPath);
+			await this.ensureSharedPackages();
+			await this.installLocalDependencies(stagingPath);
+			return stagingPath;
+		} catch (err) {
+			if (existsSync(stagingPath)) rmSync(stagingPath, {
+				recursive: true,
+				force: true
+			});
+			throw err;
+		}
+	}
+	/**
+	* Commit a previously-staged clone: remove the live install dir and rename
+	* the staged dir into its place. Same-filesystem `renameSync` makes the swap
+	* near-atomic (no window where the install dir is half-populated). Called
+	* inside the runtime-suspension window during a diff-based upgrade.
+	*/
+	commitStaged(name, stagedPath) {
+		const installPath = this.getInstallPath(name);
+		if (existsSync(installPath)) rmSync(installPath, {
+			recursive: true,
+			force: true
+		});
+		renameSync(stagedPath, installPath);
+	}
+	/**
+	* Remove any orphaned `.staging-*` directories under the base path. Called at
+	* the start of `stage()` so a daemon killed mid-upgrade doesn't accumulate
+	* partial clones. Best-effort — a failed removal is logged and skipped.
+	*/
+	sweepStagingDirs() {
+		if (!existsSync(this.basePath)) return;
+		for (const entry of readdirSync(this.basePath, { withFileTypes: true })) {
+			if (!entry.isDirectory() || !entry.name.startsWith(STAGING_PREFIX)) continue;
+			try {
+				rmSync(join(this.basePath, entry.name), {
+					recursive: true,
+					force: true
+				});
+			} catch (err) {
+				log$4.warn({
+					dir: entry.name,
+					err: err instanceof Error ? err.message : String(err)
+				}, "Failed to sweep orphaned staging dir");
+			}
+		}
+	}
+	/**
 	* Update an installed integration to a new version.
 	* Removes old install and does a fresh clone.
 	*/
@@ -351,6 +434,7 @@ var Installer = class {
 		const installed = [];
 		for (const entry of entries) {
 			if (!entry.isDirectory()) continue;
+			if (entry.name.startsWith(".")) continue;
 			const integrationPath = join(this.basePath, entry.name);
 			const manifestPath = join(integrationPath, "alfe-integration.yaml");
 			if (!existsSync(manifestPath)) continue;
@@ -1297,13 +1381,7 @@ var IntegrationManager = class {
 		this.log.info(`Deactivating integration: ${integrationId}`);
 		try {
 			const removed = this.lockManager.removeEntries(integrationId);
-			const remaining = this.lockManager.read();
-			const claimedPluginsByRuntime = /* @__PURE__ */ new Map();
-			const claimedSkillsByRuntime = /* @__PURE__ */ new Map();
-			for (const [rtName, state] of Object.entries(remaining.runtimes)) {
-				claimedPluginsByRuntime.set(rtName, new Set(state.plugins.map((p) => stripPluginVersion(p.package))));
-				claimedSkillsByRuntime.set(rtName, new Set(state.skills.map((s) => s.name)));
-			}
+			const { plugins: claimedPluginsByRuntime, skills: claimedSkillsByRuntime } = this.claimedEntriesByRuntime();
 			for (const [runtimeName, entries] of Object.entries(removed)) {
 				const applier = this.runtimeAppliers.get(runtimeName);
 				if (!applier) {
@@ -1469,6 +1547,132 @@ var IntegrationManager = class {
 		}
 	}
 	/**
+	* Upgrade an integration to a new version IN PLACE, diff-based, so unchanged
+	* plugins are skipped and the clone + npm work happens BEFORE the runtime is
+	* suspended. This is the fast path for a version bump — `reinstall()` stays
+	* the destructive escape hatch (full uninstall → install → activate) for
+	* repair.
+	*
+	* `opts.onBeforeRuntimeMutation` is the deferred-suspend seam: invoked exactly
+	* once, immediately before the first step that mutates the runtime (Phase 2's
+	* commit). RuntimeGate ownership stays in the gateway; the manager stays
+	* runtime-agnostic.
+	*
+	* Phases:
+	*  0. Guards — no state entry → install + activate; a stale `installing`
+	*     status (daemon killed mid-install) → reinstall recovery; install not
+	*     intact / old manifest unparseable → delegate to `reinstall()` (repair
+	*     stays destructive). Every fallback that can shell the openclaw CLI
+	*     invokes `opts.onBeforeRuntimeMutation` first (at most once — each
+	*     returns before Phase 2's seam).
+	*  1. Prepare (runtime live) — resolve new version, `installer.stage()` the
+	*     clone + npm into `.staging-*`, canonicalize a custom-source manifest on
+	*     the STAGED dir. State untouched (stays active@old) on failure here.
+	*  2. Commit — suspend seam, `installer.commitStaged()` swap, parse new
+	*     manifest + depends_on, `state.update()` (NOT full-replace) preserving
+	*     customConnectionId + refreshing installedAt + NOT touching secrets, run
+	*     new-manifest pre/post_install hooks (gated on supported_agents).
+	*  3. Diff removals — tear down only plugins/skills/config/MCP the NEW
+	*     manifest dropped (and no sibling integration still claims).
+	*  4. Activate with `forcePlugins` — the applier's version-match skip makes
+	*     unchanged plugins nearly free; only changed pins pay the reinstall cost.
+	*/
+	async upgrade(params, opts) {
+		const { name, version, config, customSource } = params;
+		if (!name) return this.err("INVALID_PARAMS", "Integration name is required");
+		const existing = this.state.get(name);
+		if (!existing) {
+			await opts?.onBeforeRuntimeMutation?.();
+			const installResult = await this.install(params);
+			if (!installResult.ok) return installResult;
+			return this.activate(name, { forcePlugins: true });
+		}
+		if (existing.status === "installing") {
+			this.log.warn(`Integration "${name}" has a stale "installing" status (daemon likely killed mid-install) — recovering via reinstall`);
+			await opts?.onBeforeRuntimeMutation?.();
+			return this.reinstall(params);
+		}
+		const oldManifestPath = join(this.installer.getInstallPath(name), "alfe-integration.yaml");
+		let oldManifest = null;
+		if (existsSync(oldManifestPath)) try {
+			oldManifest = parseManifestFile(oldManifestPath);
+		} catch {
+			oldManifest = null;
+		}
+		if (!oldManifest) {
+			this.log.warn(`Integration "${name}" install not intact or old manifest unparseable — delegating to reinstall`);
+			await opts?.onBeforeRuntimeMutation?.();
+			return this.reinstall(params);
+		}
+		this.log.info(`Upgrading integration: ${name}${version ? `@${version}` : ""}`);
+		let stagedPath;
+		try {
+			let resolved;
+			if (customSource) {
+				resolved = buildCustomResolved(name, customSource);
+				this.log.info(`Custom Connection upgrade: ${name} from ${resolved.repository}@${resolved.commit}`);
+			} else {
+				resolved = await this.resolver.resolve(name, version, { fresh: true });
+				this.log.info(`Resolved ${name}@${resolved.version} from ${resolved.repository}`);
+			}
+			stagedPath = await this.installer.stage(resolved);
+			if (customSource) ensureCanonicalManifestName(stagedPath, customSource.manifestPath);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			this.log.error(`Failed to prepare upgrade for "${name}": ${message}`);
+			return this.err("UPGRADE_FAILED", message);
+		}
+		try {
+			await opts?.onBeforeRuntimeMutation?.();
+			this.installer.commitStaged(name, stagedPath);
+			const newManifestPath = join(this.installer.getInstallPath(name), "alfe-integration.yaml");
+			if (!existsSync(newManifestPath)) throw new Error(`No alfe-integration.yaml found after commit for "${name}"`);
+			const newManifest = parseManifestFile(newManifestPath);
+			this.log.info(`Upgrade manifest validated: ${newManifest.id}@${newManifest.version}`);
+			for (const dep of newManifest.depends_on) {
+				const depState = this.state.get(dep);
+				if (!depState || depState.status === "error") throw new Error(`Dependency "${dep}" is not installed. Install it first: alfe integration install ${dep}`);
+			}
+			this.state.update(name, {
+				status: "installed",
+				version: newManifest.version,
+				installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				config: config ?? existing.config,
+				customConnectionId: customSource?.connectionId ?? existing.customConnectionId
+			});
+			const installHooksSupported = this.manifestSupportsRegisteredRuntime(newManifest);
+			if (!installHooksSupported && (newManifest.hooks.pre_install || newManifest.hooks.post_install)) this.log.warn(`Integration "${name}" upgrade install hooks skipped — no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${(newManifest.supported_agents ?? []).join(", ")})`);
+			if (installHooksSupported && newManifest.hooks.pre_install) {
+				this.log.info(`Running pre_install hook: ${newManifest.hooks.pre_install}`);
+				const hookResult = await runHook(this.installer.getInstallPath(name), newManifest.hooks.pre_install);
+				if (hookResult.exitCode !== 0) throw new Error(`pre_install hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
+			}
+			if (installHooksSupported && newManifest.hooks.post_install) {
+				this.log.info(`Running post_install hook: ${newManifest.hooks.post_install}`);
+				const hookResult = await runHookWithContext(this.installer.getInstallPath(name), newManifest.hooks.post_install, {
+					integrationName: name,
+					config: config ?? existing.config,
+					secrets: this.secrets.get(name),
+					runtimes: [...this.runtimeAppliers.keys()]
+				});
+				if (hookResult.exitCode !== 0) throw new Error(`post_install hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
+			}
+			await this.applyUpgradeDiffRemovals(name, oldManifest, newManifest);
+			return await this.activate(name, { forcePlugins: true });
+		} catch (err) {
+			try {
+				if (existsSync(stagedPath)) rmSync(stagedPath, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+			const message = err instanceof Error ? err.message : String(err);
+			this.log.error(`Failed to upgrade "${name}": ${message}`);
+			this.state.setStatus(name, "error", message);
+			return this.err("UPGRADE_FAILED", message);
+		}
+	}
+	/**
 	* Run health checks for one or all integrations.
 	*/
 	async health(params) {
@@ -1654,6 +1858,101 @@ var IntegrationManager = class {
 		};
 	}
 	/**
+	* Compute the plugin (bare package) names and skill names still claimed by
+	* SOME integration in the CURRENT lock state, keyed by runtime. Both
+	* `deactivate` and `upgrade`'s diff-removal call this AFTER
+	* `lockManager.removeEntries(id)` so "still claimed" means "claimed by
+	* another integration" — the applier must NOT physically remove a plugin/
+	* skill another active integration's manifest still lists.
+	*
+	* Plugin claims match on bare package name (via `stripPluginVersion`) so two
+	* integrations pinning the same plugin at different versions still keep the
+	* one file-system install alive when only one is removed.
+	*/
+	claimedEntriesByRuntime() {
+		const remaining = this.lockManager.read();
+		const plugins = /* @__PURE__ */ new Map();
+		const skills = /* @__PURE__ */ new Map();
+		for (const [rtName, state] of Object.entries(remaining.runtimes)) {
+			plugins.set(rtName, new Set(state.plugins.map((p) => stripPluginVersion(p.package))));
+			skills.set(rtName, new Set(state.skills.map((s) => s.name)));
+		}
+		return {
+			plugins,
+			skills
+		};
+	}
+	/**
+	* Phase 3 of `upgrade`: tear down ONLY the plugins/skills/config/MCP servers
+	* the NEW manifest dropped, leaving everything the new version still declares
+	* (and everything a sibling integration still claims) in place. Phase 4's
+	* `activate` re-applies and re-locks the new set immediately after.
+	*
+	* `removeEntries` clears this integration's lock rows and returns what it had;
+	* a candidate removal is skipped when it is EITHER (a) still declared by the
+	* new manifest, or (b) still claimed by another integration.
+	*/
+	async applyUpgradeDiffRemovals(integrationId, oldManifest, newManifest) {
+		const removed = this.lockManager.removeEntries(integrationId);
+		const { plugins: claimedPluginsByRuntime, skills: claimedSkillsByRuntime } = this.claimedEntriesByRuntime();
+		for (const [runtimeName, entries] of Object.entries(removed)) {
+			const applier = this.runtimeAppliers.get(runtimeName);
+			if (!applier) {
+				this.log.warn(`No applier for runtime "${runtimeName}" — cannot diff-remove entries`);
+				continue;
+			}
+			if (!await applier.isAvailable()) {
+				this.log.warn(`Runtime "${runtimeName}" is not available — skipping upgrade diff removal`);
+				continue;
+			}
+			const { plugins: newPlugins, skills: newSkills, config: newRuntimeConfig } = resolveInstallsForRuntime(newManifest, runtimeName);
+			const keepPluginsNew = new Set(newPlugins.map((p) => stripPluginVersion(p.package)));
+			const keepSkillsNew = new Set(newSkills.map((s) => s.clawhub ?? s.path?.split("/").pop() ?? "unknown"));
+			const keepPluginsOther = claimedPluginsByRuntime.get(runtimeName) ?? /* @__PURE__ */ new Set();
+			const keepSkillsOther = claimedSkillsByRuntime.get(runtimeName) ?? /* @__PURE__ */ new Set();
+			for (const plugin of entries.plugins) {
+				const bare = stripPluginVersion(plugin.package);
+				if (keepPluginsNew.has(bare) || keepPluginsOther.has(bare)) continue;
+				this.log.info(`Upgrade: removing dropped plugin ${plugin.package} from ${runtimeName}`);
+				try {
+					await applier.removePlugin(plugin.package);
+				} catch (err) {
+					this.log.warn(`Failed to remove dropped plugin ${plugin.package} from ${runtimeName}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}
+			for (const skill of entries.skills) {
+				if (keepSkillsNew.has(skill.name) || keepSkillsOther.has(skill.name)) continue;
+				this.log.info(`Upgrade: removing dropped skill ${skill.name} from ${runtimeName}`);
+				try {
+					if (skill.sourcePath.startsWith("clawhub:")) await applier.removeClawHubSkill(skill.name);
+					else await applier.removeSkill(skill.name);
+				} catch (err) {
+					this.log.warn(`Failed to remove dropped skill ${skill.name} from ${runtimeName}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}
+			const oldRuntimeConfig = resolveInstallsForRuntime(oldManifest, runtimeName).config;
+			const oldHadConfig = Boolean(oldRuntimeConfig && Object.keys(oldRuntimeConfig).length > 0);
+			const newHasConfig = Boolean(newRuntimeConfig && Object.keys(newRuntimeConfig).length > 0);
+			if (oldHadConfig && !newHasConfig) {
+				this.log.info(`Upgrade: removing gone config for ${integrationId} from ${runtimeName}`);
+				try {
+					await applier.removeConfig(integrationId);
+				} catch (err) {
+					this.log.warn(`Failed to remove gone config for ${integrationId} from ${runtimeName}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}
+		}
+		if (this.mcpApplier) {
+			const keepIds = (newManifest.mcp_servers ?? []).map((s) => `${integrationId}-${s.id}`);
+			this.log.info(`Upgrade: pruning MCP servers for ${integrationId} (keeping ${String(keepIds.length)} declared)`);
+			try {
+				await this.mcpApplier.pruneForIntegration(integrationId, keepIds);
+			} catch (err) {
+				this.log.warn(`Failed to prune MCP servers for ${integrationId}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}
+	}
+	/**
 	* True when the manifest's `supported_agents` (if declared) intersects the
 	* registered runtime appliers. Hooks and MCP registration run once per
 	* integration (not per runtime), so they must use this aggregate check —
@@ -2460,10 +2759,29 @@ var OpenClawApplier = class {
 	async applyConfigLocked(integrationId, config) {
 		const tracking = this.readTracking();
 		const integrations = tracking._integrations ?? {};
+		const previous = integrations[integrationId];
+		const { leaves, subtreesByParent } = partitionEntries(flattenConfig(config));
+		if (previous && typeof previous === "object" && !Array.isArray(previous)) {
+			const prev = partitionEntries(flattenConfig(previous));
+			const nextLeafPaths = new Set(leaves.map((l) => l.path));
+			const staleLeaves = prev.leaves.filter((l) => !nextLeafPaths.has(l.path));
+			for (const { path } of staleLeaves) try {
+				await this.runConfigCommandUnlocked(["unset", path]);
+			} catch (err) {
+				log$3.warn({
+					err: err instanceof Error ? err.message : String(err),
+					path
+				}, "Failed to unset stale config leaf during applyConfig diff");
+			}
+			for (const [parentPath, prevKvs] of prev.subtreesByParent) {
+				const nextKvs = subtreesByParent.get(parentPath);
+				const goneKeys = [...prevKvs.keys()].filter((k) => !nextKvs?.has(k));
+				if (goneKeys.length > 0) await this.dropSubtreeKeysUnlocked(parentPath, new Set(goneKeys));
+			}
+		}
 		integrations[integrationId] = config;
 		tracking._integrations = integrations;
 		this.writeTracking(tracking);
-		const { leaves, subtreesByParent } = partitionEntries(flattenConfig(config));
 		for (const [parentPath, dottedKvs] of subtreesByParent) {
 			const merged = { ...await readParentObject(parentPath) };
 			for (const [k, v] of dottedKvs) merged[k] = v;
@@ -2530,28 +2848,40 @@ var OpenClawApplier = class {
 				path
 			}, "Failed to unset config via openclaw config unset");
 		}
-		for (const [parentPath, dottedKvs] of subtreesByParent) {
-			const existing = await readParentObject(parentPath);
-			const remaining = Object.fromEntries(Object.entries(existing).filter(([k]) => !dottedKvs.has(k)));
-			if (Object.keys(existing).length === 0) continue;
-			try {
-				if (Object.keys(remaining).length === 0) await this.runConfigCommandUnlocked(["unset", parentPath]);
-				else await this.runConfigSetUnlocked([
-					parentPath,
-					JSON.stringify(remaining),
-					"--replace"
-				]);
-			} catch (err) {
-				log$3.warn({
-					err: err instanceof Error ? err.message : String(err),
-					parentPath
-				}, "Failed to update parent config during remove");
-			}
-		}
+		for (const [parentPath, dottedKvs] of subtreesByParent) await this.dropSubtreeKeysUnlocked(parentPath, new Set(dottedKvs.keys()));
 		tracking._integrations = Object.fromEntries(Object.entries(integrations).filter(([key]) => key !== integrationId));
 		this.writeTracking(tracking);
 	}
 	/**
+	* Drop a set of dotted keys from a dot-free parent object via read-drop-write,
+	* UNLOCKED. If the parent becomes empty, `config unset` it; otherwise
+	* `--replace` the shrunk map (siblings survive because they remain in
+	* `remaining`). Warn-tolerant — a failed drop of an already-gone key must not
+	* fail the caller. Shared by `removeConfig` (whole-integration teardown) and
+	* `applyConfig`'s stale-key diff (per-key removal between manifest versions).
+	*
+	* Assumes the shared CLI lock is already held by the calling public method —
+	* the lock is NOT re-entrant, so this stays an `*Unlocked` internal.
+	*/
+	async dropSubtreeKeysUnlocked(parentPath, dottedKeys) {
+		const existing = await readParentObject(parentPath);
+		if (Object.keys(existing).length === 0) return;
+		const remaining = Object.fromEntries(Object.entries(existing).filter(([k]) => !dottedKeys.has(k)));
+		try {
+			if (Object.keys(remaining).length === 0) await this.runConfigCommandUnlocked(["unset", parentPath]);
+			else await this.runConfigSetUnlocked([
+				parentPath,
+				JSON.stringify(remaining),
+				"--replace"
+			]);
+		} catch (err) {
+			log$3.warn({
+				err: err instanceof Error ? err.message : String(err),
+				parentPath
+			}, "Failed to update parent config during subtree key drop");
+		}
+	}
+	/**
 	* Raw single-key config write — `openclaw config set <key> <value>`.
 	*
 	* Deliberately bypasses the `_integrations` tracking that `applyConfig`
@@ -2692,10 +3022,32 @@ var HermesApplier = class {
 	async applyConfig(integrationId, config) {
 		const tracking = this.readTracking();
 		const integrations = tracking._integrations ?? {};
+		const previous = integrations[integrationId];
+		const { leaves, subtreesByParent } = partitionEntries(flattenConfig(config));
+		if (previous && typeof previous === "object" && !Array.isArray(previous)) {
+			const prev = partitionEntries(flattenConfig(previous));
+			const nextLeafPaths = new Set(leaves.map((l) => l.path));
+			const staleLeafPaths = prev.leaves.filter((l) => !nextLeafPaths.has(l.path)).map((l) => l.path);
+			if (staleLeafPaths.length > 0) try {
+				await this.deleteConfigKeys(staleLeafPaths);
+			} catch (err) {
+				log$2.warn({
+					err: err instanceof Error ? err.message : String(err),
+					integrationId
+				}, "Failed to delete stale Hermes config keys during applyConfig diff");
+			}
+			const staleSubtreeParents = [...prev.subtreesByParent].filter(([parent, prevKvs]) => {
+				const nextKvs = subtreesByParent.get(parent);
+				return [...prevKvs.keys()].some((k) => !nextKvs?.has(k));
+			}).map(([parent]) => parent);
+			if (staleSubtreeParents.length > 0) log$2.warn({
+				integrationId,
+				parents: staleSubtreeParents
+			}, "Hermes applyConfig diff: skipping stale dotted-key subtree(s) — OpenClaw-plugin-shaped config does not apply to Hermes");
+		}
 		integrations[integrationId] = config;
 		tracking._integrations = integrations;
 		this.writeTracking(tracking);
-		const { leaves, subtreesByParent } = partitionEntries(flattenConfig(config));
 		if (subtreesByParent.size > 0) log$2.warn({
 			integrationId,
 			parents: [...subtreesByParent.keys()]
@@ -3191,6 +3543,31 @@ var McpApplier = class {
 		const owner = `integration:${integrationId}`;
 		return this.manager.removeServersByOwner(owner);
 	}
+	/**
+	* Prune servers owned by this integration whose id is NOT in `keepIds`.
+	* Used by the diff-based upgrade to drop MCP declarations the NEW manifest
+	* no longer includes, while leaving the still-declared servers (and their
+	* working env/credentials) untouched — `applyForIntegration` re-runs
+	* afterwards and refreshes the kept ones idempotently.
+	*
+	* `keepIds` are the manifest's DECLARED ids (`${integrationId}-${server.id}`),
+	* not the ids that successfully applied: a transient credential failure that
+	* skipped a re-registration must not cause prune to delete a server the new
+	* manifest still wants. Pure JSON-store writes — no CLI lock needed. Returns
+	* the ids actually removed.
+	*/
+	async pruneForIntegration(integrationId, keepIds) {
+		const owner = `integration:${integrationId}`;
+		const keep = new Set(keepIds);
+		const removed = [];
+		for (const { id, entry } of this.manager.listServers()) {
+			if (entry.owner !== owner) continue;
+			if (keep.has(id)) continue;
+			await this.manager.removeServer(id, { expectedOwner: owner });
+			removed.push(id);
+		}
+		return removed;
+	}
 	async resolveEnv(server, mergedConfig, connectionId) {
 		if (!server.env || Object.keys(server.env).length === 0) return {};
 		const provider = server.requires_credentials;
@@ -3277,8 +3654,8 @@ var IntegrationManagerAdapter = class {
 		});
 		if (!result.ok) throw new Error(result.error?.message ?? `Failed to install ${integrationId}`);
 	}
-	async activate(integrationId) {
-		const result = await this.manager.activate(integrationId);
+	async activate(integrationId, opts) {
+		const result = await this.manager.activate(integrationId, opts);
 		if (!result.ok) throw new Error(result.error?.message ?? `Failed to activate ${integrationId}`);
 		return { configApplied: result.payload?.configApplied ?? false };
 	}
@@ -3300,6 +3677,16 @@ var IntegrationManagerAdapter = class {
 		if (!result.ok) throw new Error(result.error?.message ?? `Failed to reinstall ${integrationId}`);
 		return { configApplied: result.payload?.configApplied ?? false };
 	}
+	async upgrade(integrationId, version, config, customSource, opts) {
+		const result = await this.manager.upgrade({
+			name: integrationId,
+			version,
+			config,
+			customSource
+		}, opts);
+		if (!result.ok) throw new Error(result.error?.message ?? `Failed to upgrade ${integrationId}`);
+		return { configApplied: result.payload?.configApplied ?? false };
+	}
 	isInstallIntact(integrationId) {
 		return Promise.resolve(this.manager.isInstallIntact(integrationId));
 	}

package/package.json

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