@alfe.ai/integrations 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -264,7 +264,15 @@ interface RuntimeApplier {
  * for the eventual `getCredentials(provider)` generalisation.
  */
 interface CredentialsResolver {
-  getCredentials: (provider: string) => Promise<Record<string, unknown> | undefined>;
+  /**
+   * Resolve credentials for env interpolation. `opts.connectionId`
+   * scopes resolution to a specific connection (Custom Connections),
+   * returning a flat field map; without it, resolution is
+   * provider-scoped (the agent's primary connection for the provider).
+   */
+  getCredentials: (provider: string, opts?: {
+    connectionId?: string;
+  }) => Promise<Record<string, unknown> | undefined>;
 }
 /**
  * Daemon-level platform context exposed to `{{alfe.<key>}}` env
@@ -298,7 +306,9 @@ declare class McpApplier {
    * the daemon-hosted bundler will pick the change up via the store
    * watcher and reconcile its children.
    */
-  applyForIntegration(integrationId: string, servers: McpServerDeclaration[], mergedConfig: Record<string, unknown>): Promise<string[]>;
+  applyForIntegration(integrationId: string, servers: McpServerDeclaration[], mergedConfig: Record<string, unknown>, opts?: {
+    connectionId?: string;
+  }): Promise<string[]>;
   /**
    * Drop every entry owned by this integration. Store writes are
    * durable before `removeServersByOwner` resolves; the daemon's
@@ -314,10 +324,37 @@ declare class McpApplier {
  *
  * These define the payloads for integration lifecycle operations.
  */
+/**
+ * Embedded git pointer for a Custom Connection-driven install. When
+ * present on an install, the manager clones `manifestRepo` at
+ * `manifestCommit` and installs from the directory containing
+ * `manifestPath`, bypassing the central registry resolver (Custom
+ * Connection manifests are per-tenant and never registry-published).
+ * Defined structurally so the gateway's `DesiredCustomSource` is
+ * assignable without a cross-package import.
+ */
+interface CustomInstallSource {
+  /** Backing custom Connection — used to scope credential resolution. */
+  connectionId: string;
+  /** `https://github.com/{owner}/{repo}` clone URL. */
+  manifestRepo: string;
+  /** Path to the manifest inside the repo (its directory is the install root). */
+  manifestPath: string;
+  /** Symbolic ref the operator pinned (display/provenance only). */
+  manifestRef: string;
+  /** Blob SHA of the manifest file content (not checkout-able). */
+  manifestSha: string;
+  /** Checkout-able commit SHA to clone. */
+  manifestCommit: string;
+  /** Already-parsed-and-validated manifest blob (optional convenience). */
+  manifest?: unknown;
+}
 interface IntegrationInstallParams {
   name: string;
   version?: string;
   config?: Record<string, unknown>;
+  /** Set for Custom Connection-driven installs (clone-from-git). */
+  customSource?: CustomInstallSource;
 }
 interface IntegrationRemoveParams {
   name: string;
@@ -670,7 +707,7 @@ declare class OpenClawApplier implements RuntimeApplier {
   private skillsDir;
   private trackingPath;
   constructor(options: OpenClawApplierOptions);
-  applyPlugin(pkg: string, _installPath?: string, opts?: {
+  applyPlugin(spec: string, _installPath?: string, opts?: {
     force?: boolean;
   }): Promise<void>;
   /**
@@ -697,7 +734,7 @@ declare class OpenClawApplier implements RuntimeApplier {
    * write through the npm path with a proper tracking record.
    */
   private cleanupUntrackedExtensionInstall;
-  removePlugin(pkg: string): Promise<void>;
+  removePlugin(spec: string): Promise<void>;
   applySkill(name: string, srcPath: string): Promise<void>;
   applyClawHubSkill(slug: string): Promise<void>;
   removeClawHubSkill(slug: string): Promise<void>;
@@ -723,6 +760,13 @@ declare class OpenClawApplier implements RuntimeApplier {
 //#endregion
 //#region src/lock.d.ts
 interface RuntimePluginEntry {
+  /**
+   * The full npm install spec from the manifest (e.g. `@scope/name@1.2.3`).
+   * Consumers that key off the installed plugin's identity (file-system
+   * lookups, openclaw allowlist, cross-integration claim matching) must
+   * pass this through `stripPluginVersion` from `./plugin-spec.js` first.
+   * Only `openclaw plugins install` should receive the unstripped spec.
+   */
   package: string;
   sourceIntegration: string;
   integrationVersion: string;
@@ -785,7 +829,7 @@ interface IIntegrationManager {
     installedAt?: string;
   }[]>;
   /** Install an integration at a specific version with config */
-  install(integrationId: string, version: string, config: unknown): Promise<void>;
+  install(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource): Promise<void>;
   /** Activate an installed integration */
   activate(integrationId: string): Promise<{
     configApplied: boolean;
@@ -795,7 +839,7 @@ interface IIntegrationManager {
   /** Uninstall an integration */
   uninstall(integrationId: string): Promise<void>;
   /** Reinstall an integration — full teardown then fresh install + activate */
-  reinstall(integrationId: string, version: string, config: unknown): Promise<{
+  reinstall(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource): Promise<{
     configApplied: boolean;
   }>;
   /** Check if an integration's install directory and manifest are intact on disk */
@@ -816,13 +860,13 @@ declare class IntegrationManagerAdapter implements IIntegrationManager {
     status: string;
     installedAt?: string;
   }[]>;
-  install(integrationId: string, version: string, config: unknown): Promise<void>;
+  install(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource): Promise<void>;
   activate(integrationId: string): Promise<{
     configApplied: boolean;
   }>;
   deactivate(integrationId: string): Promise<void>;
   uninstall(integrationId: string): Promise<void>;
-  reinstall(integrationId: string, version: string, config: unknown): Promise<{
+  reinstall(integrationId: string, version: string, config: unknown, customSource?: CustomInstallSource): Promise<{
     configApplied: boolean;
   }>;
   isInstallIntact(integrationId: string): Promise<boolean>;

package/dist/index.js

@@ -1,8 +1,8 @@
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { homedir, platform, tmpdir } from "node:os";
-import { closeSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { buildConfigValidationSchema, parseManifestFile } from "@alfe.ai/integration-manifest";
 import { createLogger } from "@auriclabs/logger";
 //#region src/registry.ts
@@ -796,6 +796,26 @@ async function runHookWithContext(integrationPath, hookScript, options) {
 	return runHook(integrationPath, hookScript, buildHookEnv(options));
 }
 //#endregion
+//#region src/plugin-spec.ts
+/**
+* Plugin spec parsing.
+*
+* Manifests express plugin installs as `package: "@scope/name@version"` strings
+* (npm specifier form). The npm install command accepts the full spec, but file-
+* system checks, plugin-allowlist entries, and cross-integration claim matching
+* need the bare package name (npm stores `node_modules/<name>`, not
+* `node_modules/<name>@<ver>`).
+*
+* `stripPluginVersion` returns the bare package name from any spec, handling
+* scoped (`@scope/name@1.2.3`) and unscoped (`name@1.2.3`) forms. Specs without
+* a version are returned unchanged.
+*/
+function stripPluginVersion(spec) {
+	const at = spec.lastIndexOf("@");
+	if (at <= 0) return spec;
+	return spec.slice(0, at);
+}
+//#endregion
 //#region src/integration-manager.ts
 /**
 * Integration Manager — full lifecycle management for Alfe integrations.
@@ -848,6 +868,37 @@ function resolveInstallsForRuntime(manifest, runtime) {
 		config: runtimeSpecific?.config
 	};
 }
+/**
+* Build a clone target for a Custom Connection-driven install,
+* bypassing the central registry resolver. The manifest's directory
+* inside the repo becomes the install root (subdir extraction); the
+* checkout-able `manifestCommit` pins the clone.
+*/
+function buildCustomResolved(id, cs) {
+	if (id.includes("/") || id.includes("\\") || id.includes("..")) throw new Error(`Refusing custom integration id with path separators: ${id}`);
+	const dir = dirname(cs.manifestPath);
+	const subdir = dir === "." || dir === "" ? void 0 : dir;
+	const manifestVersion = cs.manifest?.version;
+	return {
+		id,
+		repository: cs.manifestRepo,
+		version: manifestVersion ?? "unknown",
+		commit: cs.manifestCommit,
+		subdir,
+		description: ""
+	};
+}
+/**
+* The lifecycle assumes the manifest is named `alfe-integration.yaml`.
+* Custom Connections may point at a differently-named file, so after
+* cloning we alias the actual file to the canonical name if needed.
+*/
+function ensureCanonicalManifestName(installPath, manifestPath) {
+	const canonical = join(installPath, "alfe-integration.yaml");
+	if (existsSync(canonical)) return;
+	const actual = join(installPath, basename(manifestPath));
+	if (existsSync(actual)) copyFileSync(actual, canonical);
+}
 var IntegrationManager = class {
 	log = createLogger("IntegrationManager");
 	state;
@@ -883,7 +934,7 @@ var IntegrationManager = class {
 	* They are applied during activate() via runtime appliers.
 	*/
 	async install(params) {
-		const { name, version, config } = params;
+		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) {
@@ -906,13 +957,21 @@ var IntegrationManager = class {
 			status: "installing",
 			version: version ?? "unknown",
 			installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			config: {}
+			config: {},
+			customConnectionId: customSource?.connectionId
 		});
 		try {
-			const resolved = await this.resolver.resolve(name, version);
-			this.log.info(`Resolved ${name}@${resolved.version} from ${resolved.repository}`);
+			let resolved;
+			if (customSource) {
+				resolved = buildCustomResolved(name, customSource);
+				this.log.info(`Custom Connection install: ${name} from ${resolved.repository}@${resolved.commit}`);
+			} else {
+				resolved = await this.resolver.resolve(name, version);
+				this.log.info(`Resolved ${name}@${resolved.version} from ${resolved.repository}`);
+			}
 			const installPath = await this.installer.install(resolved);
 			this.log.info(`Cloned to ${installPath}`);
+			if (customSource) ensureCanonicalManifestName(installPath, customSource.manifestPath);
 			const manifestPath = join(installPath, "alfe-integration.yaml");
 			if (!existsSync(manifestPath)) throw new Error(`No alfe-integration.yaml found in ${installPath}`);
 			const manifest = parseManifestFile(manifestPath);
@@ -939,7 +998,8 @@ var IntegrationManager = class {
 				status: "installed",
 				version: manifest.version,
 				installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-				config: config ?? {}
+				config: config ?? {},
+				customConnectionId: customSource?.connectionId
 			});
 			this.log.info(`Integration "${name}" installed successfully`);
 			return {
@@ -1097,7 +1157,7 @@ var IntegrationManager = class {
 					...secretEntries ? Object.fromEntries(secretEntries) : {}
 				};
 				this.log.info(`Applying ${String(mcpServers.length)} MCP server(s) for ${integrationId} via bundler manager`);
-				await this.mcpApplier.applyForIntegration(integrationId, mcpServers, mergedConfig);
+				await this.mcpApplier.applyForIntegration(integrationId, mcpServers, mergedConfig, { connectionId: entry.customConnectionId });
 			}
 			this.state.setStatus(integrationId, "active");
 			if (manifest.hooks.post_activate) {
@@ -1162,6 +1222,13 @@ 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)));
+			}
 			for (const [runtimeName, entries] of Object.entries(removed)) {
 				const applier = this.runtimeAppliers.get(runtimeName);
 				if (!applier) {
@@ -1172,7 +1239,13 @@ var IntegrationManager = class {
 					this.log.warn(`Runtime "${runtimeName}" is not available — skipping removal`);
 					continue;
 				}
+				const keepPlugins = claimedPluginsByRuntime.get(runtimeName) ?? /* @__PURE__ */ new Set();
+				const keepSkills = claimedSkillsByRuntime.get(runtimeName) ?? /* @__PURE__ */ new Set();
 				for (const plugin of entries.plugins) {
+					if (keepPlugins.has(stripPluginVersion(plugin.package))) {
+						this.log.info(`Keeping plugin ${plugin.package} on ${runtimeName} — still claimed by another active integration`);
+						continue;
+					}
 					this.log.info(`Removing plugin ${plugin.package} from ${runtimeName}`);
 					try {
 						await applier.removePlugin(plugin.package);
@@ -1181,6 +1254,10 @@ var IntegrationManager = class {
 					}
 				}
 				for (const skill of entries.skills) {
+					if (keepSkills.has(skill.name)) {
+						this.log.info(`Keeping skill ${skill.name} on ${runtimeName} — still claimed by another active integration`);
+						continue;
+					}
 					this.log.info(`Removing skill ${skill.name} from ${runtimeName}`);
 					try {
 						if (skill.sourcePath.startsWith("clawhub:")) await applier.removeClawHubSkill(skill.name);
@@ -1575,16 +1652,21 @@ var OpenClawApplier = class {
 		this.skillsDir = options.skillsDir ?? DEFAULT_SKILLS_DIR;
 		this.trackingPath = options.configPath ?? join(this.home, "config.json");
 	}
-	async applyPlugin(pkg, _installPath, opts) {
+	async applyPlugin(spec, _installPath, opts) {
+		const pkg = stripPluginVersion(spec);
 		await this.ensurePluginsAllow(pkg);
 		this.cleanupUntrackedExtensionInstall(pkg);
 		if (opts?.force && this.isPluginInstalled(pkg)) {
-			log$1.info({ pkg }, "Force mode — uninstalling plugin before reinstall");
+			log$1.info({
+				pkg,
+				spec
+			}, "Force mode — uninstalling plugin before reinstall");
 			try {
 				await this.removePlugin(pkg);
 			} catch (err) {
 				log$1.warn({
 					pkg,
+					spec,
 					err: err instanceof Error ? err.message : String(err)
 				}, "Failed to uninstall plugin during force reinstall — proceeding");
 			}
@@ -1593,7 +1675,7 @@ var OpenClawApplier = class {
 			const baseArgs = [
 				"plugins",
 				"install",
-				pkg,
+				spec,
 				"--force"
 			];
 			const useUnsafeFlag = pkg.startsWith("@alfe.ai/");
@@ -1615,6 +1697,7 @@ var OpenClawApplier = class {
 				if (!this.isPluginInstalled(pkg)) throw err;
 				log$1.warn({
 					pkg,
+					spec,
 					err: err instanceof Error ? err.message : String(err)
 				}, "openclaw plugins install exited with warnings but plugin is installed");
 			}
@@ -1714,12 +1797,12 @@ var OpenClawApplier = class {
 			}
 		}
 	}
-	async removePlugin(pkg) {
+	async removePlugin(spec) {
 		await execFileAsync("openclaw", [
 			"plugins",
 			"uninstall",
 			"--force",
-			pkg
+			stripPluginVersion(spec)
 		], { timeout: 3e4 });
 	}
 	applySkill(name, srcPath) {
@@ -1906,12 +1989,12 @@ var McpApplier = class {
 	* the daemon-hosted bundler will pick the change up via the store
 	* watcher and reconcile its children.
 	*/
-	async applyForIntegration(integrationId, servers, mergedConfig) {
+	async applyForIntegration(integrationId, servers, mergedConfig, opts) {
 		const owner = `integration:${integrationId}`;
 		const applied = [];
 		for (const server of servers) {
 			const id = `${integrationId}-${server.id}`;
-			const envResolved = await this.resolveEnv(server, mergedConfig);
+			const envResolved = await this.resolveEnv(server, mergedConfig, opts?.connectionId);
 			if (envResolved == null) {
 				log.info({
 					integrationId,
@@ -1937,17 +2020,19 @@ var McpApplier = class {
 		const owner = `integration:${integrationId}`;
 		return this.manager.removeServersByOwner(owner);
 	}
-	async resolveEnv(server, mergedConfig) {
+	async resolveEnv(server, mergedConfig, connectionId) {
 		if (!server.env || Object.keys(server.env).length === 0) return {};
-		const needsCredentials = server.requires_credentials;
+		const provider = server.requires_credentials;
+		const needsCredentials = Boolean(provider) || Boolean(connectionId);
 		let credentialsCache;
 		if (needsCredentials) {
 			try {
-				credentialsCache = await this.credentials.getCredentials(needsCredentials);
+				credentialsCache = await this.credentials.getCredentials(provider ?? "custom", connectionId ? { connectionId } : void 0);
 			} catch (err) {
 				log.warn({
 					err: errMsg(err),
-					provider: needsCredentials
+					provider,
+					connectionId
 				}, "Credentials fetch threw — skipping MCP registration");
 				return null;
 			}
@@ -1958,7 +2043,8 @@ var McpApplier = class {
 			const interpolated = interpolateString(value, mergedConfig, credentialsCache, this.platform);
 			if (needsCredentials && hasCredentialsPlaceholder(interpolated)) {
 				log.warn({
-					provider: needsCredentials,
+					provider,
+					connectionId,
 					key
 				}, "Credentials interpolation left a placeholder — skipping MCP registration");
 				return null;
@@ -2011,11 +2097,12 @@ var IntegrationManagerAdapter = class {
 			installedAt: i.installedAt
 		})));
 	}
-	async install(integrationId, version, config) {
+	async install(integrationId, version, config, customSource) {
 		const result = await this.manager.install({
 			name: integrationId,
 			version,
-			config
+			config,
+			customSource
 		});
 		if (!result.ok) throw new Error(result.error?.message ?? `Failed to install ${integrationId}`);
 	}
@@ -2032,11 +2119,12 @@ var IntegrationManagerAdapter = class {
 		const result = await this.manager.uninstall({ name: integrationId });
 		if (!result.ok) throw new Error(result.error?.message ?? `Failed to uninstall ${integrationId}`);
 	}
-	async reinstall(integrationId, version, config) {
+	async reinstall(integrationId, version, config, customSource) {
 		const result = await this.manager.reinstall({
 			name: integrationId,
 			version,
-			config
+			config,
+			customSource
 		});
 		if (!result.ok) throw new Error(result.error?.message ?? `Failed to reinstall ${integrationId}`);
 		return { configApplied: result.payload?.configApplied ?? false };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integrations",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,8 +13,8 @@
   },
   "dependencies": {
     "@auriclabs/logger": "^0.1.1",
-    "@alfe.ai/integration-manifest": "^0.1.0",
-    "@alfe.ai/mcp-bundler": "^0.1.1"
+    "@alfe.ai/integration-manifest": "^0.2.1",
+    "@alfe.ai/mcp-bundler": "^0.2.0"
   },
   "files": [
     "dist"