@alfe.ai/integrations 0.1.6 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { IntegrationManifest, IntegrationStateEntry, IntegrationStatus, IntegrationsStateFile, McpServerDeclaration, PluginInstall, SkillInstall } from "@alfe.ai/integration-manifest";
-import { Manager } from "@alfe.ai/mcp-bundler";
+import { Manager, StoredServerEntry } from "@alfe.ai/mcp-bundler";
 
 //#region src/registry.d.ts
 
@@ -308,6 +308,18 @@ interface RuntimeApplier {
   applyConfig(integrationId: string, config: Record<string, unknown>): Promise<void>;
   /** Remove config previously applied by an integration */
   removeConfig(integrationId: string): Promise<void>;
+  /**
+   * Optional: write a single raw config key/value directly to the runtime,
+   * bypassing the per-integration removal accounting that `applyConfig`
+   * maintains. Used by the daemon's `alfe.config_set` cloud-command so it can
+   * route per-runtime instead of shelling the runtime CLI directly.
+   *
+   * MUST NOT funnel through `applyConfig` — a raw single-key set is untracked
+   * and must not corrupt an integration's tracked config contribution.
+   * Appliers that can't honour a raw write omit this method; callers detect
+   * its absence and degrade gracefully.
+   */
+  setConfigRaw?(key: string, value: string): Promise<void>;
   /** Check if this runtime is available (e.g. workspace directory exists) */
   isAvailable(): Promise<boolean>;
 }
@@ -842,11 +854,238 @@ declare class OpenClawApplier implements RuntimeApplier {
    * then removes them via `openclaw config unset`.
    */
   removeConfig(integrationId: string): Promise<void>;
+  /**
+   * Raw single-key config write — `openclaw config set <key> <value>`.
+   *
+   * Deliberately bypasses the `_integrations` tracking that `applyConfig`
+   * maintains: this is a fire-and-forget write for the `alfe.config_set`
+   * cloud-command, not an integration contribution, so it must NOT be
+   * recorded for later `removeConfig` teardown. Reuses the serialized +
+   * retried queue so it can't interleave with the hot-reload that integration
+   * config writes trigger.
+   */
+  setConfigRaw(key: string, value: string): Promise<void>;
   isAvailable(): Promise<boolean>;
   private readTracking;
   private writeTracking;
 }
 //#endregion
+//#region src/appliers/hermes-applier.d.ts
+interface HermesApplierOptions {
+  /**
+   * Path to the Hermes home directory (e.g. ~/.hermes) — where config.yaml,
+   * .env, and plugins/ live. For Hermes, home == workspace.
+   */
+  home?: string;
+  /**
+   * @deprecated Use `home`. Kept for parity with OpenClawApplier's option shape —
+   * when set, used as `home`.
+   */
+  workspace?: string;
+  /** Path to the per-integration tracking file (defaults to {home}/.alfe-integrations.json) */
+  configPath?: string;
+  /** Max retries for a transient `hermes config set/unset` failure (default 3) */
+  configSetRetries?: number;
+  /** Backoff between `hermes config` retries, ms (default 750; set 0 in tests) */
+  configSetRetryDelayMs?: number;
+}
+declare class HermesApplier implements RuntimeApplier {
+  readonly runtime = "hermes";
+  private home;
+  private trackingPath;
+  private configSetRetries;
+  private configSetRetryDelayMs;
+  /** Serializes all `hermes config` writes so they never interleave. */
+  private configSetQueue;
+  constructor(options?: HermesApplierOptions);
+  /**
+   * Apply integration config to the Hermes runtime via `hermes config set`.
+   *
+   * Each leaf is applied as `hermes config set <dotted.key> <value>`. Each
+   * integration's config contribution is tracked in the tracking file so it can
+   * be cleanly removed later (mirrors OpenClawApplier's `_integrations`).
+   */
+  applyConfig(integrationId: string, config: Record<string, unknown>): Promise<void>;
+  /**
+   * Remove config previously applied by an integration.
+   *
+   * Reads the tracking file to find which keys this integration set, then
+   * removes each via `hermes config unset`. Clears the tracking entry.
+   */
+  removeConfig(integrationId: string): Promise<void>;
+  /**
+   * Raw single-key config write — `hermes config set <key> <value>`.
+   *
+   * Deliberately bypasses the `_integrations` tracking that `applyConfig`
+   * maintains: this is a fire-and-forget write for the `alfe.config_set`
+   * cloud-command, NOT an integration contribution, so it must not be recorded
+   * for later `removeConfig` teardown (doing so would corrupt the
+   * per-integration removal accounting). Reuses the serialized queue.
+   */
+  setConfigRaw(key: string, value: string): Promise<void>;
+  /**
+   * Apply a plugin. The `@alfe.ai/openclaw-*` npm plugins are OpenClaw-specific
+   * (they carry the `openclaw` peer dep) and do NOT apply to Hermes — log + skip
+   * them. The manager catches per-plugin, so a skip here is a correct no-op.
+   *
+   * A genuine Hermes-native plugin spec (git URL / pip / local dir) would
+   * `hermes plugins install` then `hermes plugins enable`; no manifest declares
+   * one in Phase 1, so this path is a real attempt (not faked) but untrodden.
+   */
+  applyPlugin(spec: string): Promise<void>;
+  /**
+   * Remove a plugin. OpenClaw-specific npm plugins were never installed into
+   * Hermes (applyPlugin skipped them), so removal is a no-op log. A native
+   * Hermes plugin would be disabled via `hermes plugins`.
+   */
+  removePlugin(spec: string): Promise<void>;
+  applySkill(name: string): Promise<void>;
+  removeSkill(name: string): Promise<void>;
+  applyClawHubSkill(slug: string): Promise<void>;
+  removeClawHubSkill(slug: string): Promise<void>;
+  isAvailable(): Promise<boolean>;
+  /** Convenience: `hermes config set <args>`, serialized + retried. */
+  private runConfigSet;
+  /**
+   * Unset a single config key. The unset verb is isolated HERE so there is one
+   * place to change if the spike proves `hermes config unset` is unavailable.
+   *
+   * FALLBACK (do NOT pre-build): if `hermes config unset` does not exist, the
+   * substitute is `hermes config set <key> ""` (clear the value) or a
+   * read-merge-write of config.yaml. Not implemented now — `unset` is the
+   * documented verb; confirm in the Phase-0 spike before adding a fallback.
+   * TODO(phase-0 spike): confirm `hermes config unset <key>` exists.
+   */
+  private unsetConfigKey;
+  /**
+   * Run `hermes config <args>` (set/unset), serialized against every other
+   * config write and retried with backoff. Throws an Error whose (scrubbed)
+   * message includes stderr after retries are exhausted, so the real cause
+   * propagates to the integration errorMessage without leaking the value.
+   */
+  private runConfigCommand;
+  private readTracking;
+  private writeTracking;
+}
+//#endregion
+//#region src/appliers/hermes-mcp-sync.d.ts
+/**
+ * The slice of the bundler `Manager` this consumer needs. Kept structural (not a
+ * concrete-class dependency) so it stays trivially testable and so the consumer
+ * can never reach for producer-side mutation methods — it is read-only over the
+ * store plus a change subscription.
+ */
+interface McpStoreReader {
+  onChange(cb: () => void): () => void;
+  listServers(): {
+    id: string;
+    entry: StoredServerEntry;
+  }[];
+}
+interface HermesMcpSyncOptions {
+  /** The runtime-agnostic MCP store manager (read + onChange). */
+  manager: McpStoreReader;
+  /** Hermes home (== workspace == ~/.hermes). config.yaml + .env live here. */
+  home?: string;
+  /**
+   * The `ALFE_API_KEY` value to write into `~/.hermes/.env` so the
+   * `${ALFE_API_KEY}` refs in mirrored server envs resolve. In managed mode this
+   * is the daemon's own api key; self-hosted threads it explicitly. When absent,
+   * the `.env` write is skipped and a warning is logged (the servers would then
+   * start in zero-accounts degraded mode).
+   */
+  apiKey?: string;
+  /**
+   * Trigger a runtime reload after a real change. MUST be the SAME callback the
+   * daemon wires into `setRuntimeRestartNeededHandler` — there is exactly one
+   * restart path. No-op when the runtime isn't running yet (the initial sync
+   * writes config.yaml before Hermes starts, so no restart is needed then).
+   */
+  requestRestart?: () => void;
+  /** Override config.yaml path (defaults to {home}/config.yaml). For tests. */
+  configPath?: string;
+  /** Override .env path (defaults to {home}/.env). For tests. */
+  envPath?: string;
+  /**
+   * Override the sidecar that records which `mcp_servers` ids this sync wrote
+   * (defaults to {home}/.alfe-mcp-synced.json). Used so removals survive daemon
+   * restarts and so we NEVER delete user-authored `mcp_servers` entries.
+   */
+  trackingPath?: string;
+  /**
+   * Trailing debounce (ms) used to coalesce a burst of store mutations (one
+   * integration install fires `addServer` once per server) into a single
+   * config.yaml write + restart, avoiding a restart storm. Default 250; set 0 in
+   * tests. The initial sync in `start()` is always immediate.
+   */
+  debounceMs?: number;
+}
+/**
+ * Read-merge-write mirror of the MCP store into `~/.hermes/config.yaml`.
+ *
+ * Ownership / removal model: every entry returned by `manager.listServers()`
+ * comes from the Alfe store (its `owner` is `integration:<id>` / `cli` /
+ * `manual`) and is therefore Alfe-owned — these are the ids we write. User
+ * authored `mcp_servers` entries live ONLY in config.yaml and never appear in
+ * the store, so we never touch them. To know which config.yaml ids to REMOVE
+ * when a server leaves the store, we persist the set of ids we last wrote to a
+ * sidecar (`.alfe-mcp-synced.json`) and only ever delete from that set — exactly
+ * how the bundler store tracks `_ownedOpenclawKeys` for its openclaw.json mirror.
+ */
+declare class HermesMcpSync {
+  private readonly manager;
+  private readonly home;
+  private readonly apiKey?;
+  private readonly requestRestart?;
+  private readonly configPath;
+  private readonly envPath;
+  private readonly trackingPath;
+  private readonly debounceMs;
+  /** Ids of `mcp_servers` entries this sync last wrote — the removal set. */
+  private syncedIds;
+  /** Serializes syncs so two onChange-driven runs can't interleave file writes. */
+  private queue;
+  private unsubscribe?;
+  private debounceTimer?;
+  private started;
+  constructor(opts: HermesMcpSyncOptions);
+  /**
+   * Begin mirroring: load the prior removal set, run one immediate sync (so
+   * config.yaml reflects the current store before Hermes first starts), then
+   * subscribe to store changes (debounced). Idempotent.
+   */
+  start(): void;
+  /** Stop subscribing and cancel any pending debounced sync. Idempotent. */
+  stop(): void;
+  /**
+   * Mirror the current store into config.yaml + .env exactly once. Public so the
+   * daemon (and tests) can await a deterministic sync. Serialized against any
+   * other in-flight sync.
+   */
+  syncOnce(): Promise<void>;
+  private schedule;
+  private syncNow;
+  private computeDesired;
+  /**
+   * Transform a stored entry into a Hermes `mcp_servers` entry. SPIKE-PENDING
+   * SEAM #3 lives here — the schema shape. stdio entries get `ALFE_API_KEY`
+   * injected; remote entries pass through (Hermes supports `url`-based MCP).
+   */
+  private toHermesEntry;
+  private withAlfeApiKey;
+  /** Read-merge-write `~/.hermes/.env` to set ALFE_API_KEY without clobbering other keys. */
+  private ensureEnvApiKey;
+  private loadSyncedIds;
+  private persistSyncedIds;
+}
+/**
+ * Set `KEY=value` in a `.env`-style file, preserving every other line (comments,
+ * blank lines, unrelated keys) and order. Returns whether the file changed. Not
+ * a full dotenv parser — it only matches simple `KEY=` lines, which is all
+ * `~/.hermes/.env` ever holds.
+ */
+declare function upsertEnvVar(envPath: string, key: string, value: string): boolean;
+//#endregion
 //#region src/lock.d.ts
 interface RuntimePluginEntry {
   /**
@@ -866,9 +1105,29 @@ interface RuntimeSkillEntry {
   sourceIntegration: string;
   integrationVersion: string;
 }
+/**
+ * Records that an integration applied runtime *config* (via the applier's
+ * `applyConfig`) to a runtime — even when it contributed no plugins/skills.
+ *
+ * Without this, a config-only integration left no lock entry for its runtime,
+ * so `removeEntries` returned nothing for it and `deactivate` never drove
+ * `applier.removeConfig(...)` — leaking the applied config on removal. The
+ * applier itself owns the actual config payload (e.g. OpenClaw's tracking
+ * file); the lock only needs to know which integration touched which runtime.
+ */
+interface RuntimeConfigEntry {
+  sourceIntegration: string;
+  integrationVersion: string;
+}
 interface RuntimeDesiredState {
   plugins: RuntimePluginEntry[];
   skills: RuntimeSkillEntry[];
+  /**
+   * Integrations that applied config to this runtime. Optional for
+   * back-compat with lock files written before this field existed — always
+   * read it as `state.config ?? []`.
+   */
+  config?: RuntimeConfigEntry[];
 }
 interface RuntimeLockFile {
   version: 1;
@@ -888,15 +1147,26 @@ declare class LockManager {
   write(lock: RuntimeLockFile): void;
   /**
    * Add entries for an integration activation in a specific runtime.
+   *
+   * Pass `opts.configApplied` when the integration applied runtime config so
+   * the contribution is recorded even if it ships no plugins/skills — this is
+   * what lets a config-only integration be torn down on deactivate.
    */
-  addEntries(runtime: string, integrationId: string, version: string, plugins: PluginInstall[], skills: SkillInstall[], installPath: string): void;
+  addEntries(runtime: string, integrationId: string, version: string, plugins: PluginInstall[], skills: SkillInstall[], installPath: string, opts?: {
+    configApplied?: boolean;
+  }): void;
   /**
    * Remove all entries for a given integration across all runtimes.
    * Returns what was removed, keyed by runtime.
+   *
+   * A runtime is included in the result when the integration contributed
+   * plugins, skills, OR config there — so `deactivate` drives
+   * `applier.removeConfig` even for a config-only integration.
    */
   removeEntries(integrationId: string): Record<string, {
     plugins: RuntimePluginEntry[];
     skills: RuntimeSkillEntry[];
+    config: RuntimeConfigEntry[];
   }>;
   /**
    * Get the full desired state for a specific runtime.
@@ -964,4 +1234,4 @@ declare class IntegrationManagerAdapter implements IIntegrationManager {
   resetReinstallAttempts(integrationId: string): void;
 }
 //#endregion
-export { type CredentialsResolver, DEFAULT_REGISTRY_TTL_MS, type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, type LoadOptions, LockManager, McpApplier, type McpApplierOptions, OpenClawApplier, type OpenClawApplierOptions, type PlatformContext, Registry, type RegistryEntry, type RegistryFetcher, type RegistryIndex, type RegistryOptions, RegistryResolveError, type ResolveOptions, type ResolvedIntegration, Resolver, type RuntimeApplier, type RuntimeDesiredState, type RuntimeLockFile, type RuntimePluginEntry, type RuntimeSkillEntry, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };
+export { type CredentialsResolver, DEFAULT_REGISTRY_TTL_MS, HermesApplier, type HermesApplierOptions, HermesMcpSync, type HermesMcpSyncOptions, type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, type LoadOptions, LockManager, McpApplier, type McpApplierOptions, type McpStoreReader, OpenClawApplier, type OpenClawApplierOptions, type PlatformContext, Registry, type RegistryEntry, type RegistryFetcher, type RegistryIndex, type RegistryOptions, RegistryResolveError, type ResolveOptions, type ResolvedIntegration, Resolver, type RuntimeApplier, type RuntimeConfigEntry, type RuntimeDesiredState, type RuntimeLockFile, type RuntimePluginEntry, type RuntimeSkillEntry, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext, upsertEnvVar };

package/dist/index.js

@@ -5,6 +5,8 @@ import { homedir, platform, tmpdir } from "node:os";
 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";
+import { parseDocument } from "yaml";
+import { toServerConfig } from "@alfe.ai/mcp-bundler";
 //#region src/registry.ts
 /** Default cache TTL — refetch the registry index after this many ms. */
 const DEFAULT_REGISTRY_TTL_MS = 6e4;
@@ -149,8 +151,8 @@ var Resolver = class {
 * are installed at the root integrations directory so all hook scripts
 * can resolve them via Node's upward module resolution.
 */
-const execFileAsync$1 = promisify(execFile);
-const log$2 = createLogger("Installer");
+const execFileAsync$2 = promisify(execFile);
+const log$4 = createLogger("Installer");
 const INTEGRATIONS_DIR = join(homedir(), ".alfe", "integrations");
 const GIT_TIMEOUT_MS = 6e4;
 const NPM_TIMEOUT_MS = 6e4;
@@ -211,12 +213,12 @@ var Installer = class {
 	*/
 	async cloneDirect(resolved, installPath) {
 		try {
-			await execFileAsync$1("git", [
+			await execFileAsync$2("git", [
 				"clone",
 				resolved.repository,
 				installPath
 			], { timeout: GIT_TIMEOUT_MS });
-			await execFileAsync$1("git", ["checkout", resolved.commit], {
+			await execFileAsync$2("git", ["checkout", resolved.commit], {
 				cwd: installPath,
 				timeout: GIT_TIMEOUT_MS
 			});
@@ -237,12 +239,12 @@ var Installer = class {
 		const subdir = resolved.subdir;
 		const tempDir = mkdtempSync(join(tmpdir(), `alfe-clone-${resolved.id}-`));
 		try {
-			await execFileAsync$1("git", [
+			await execFileAsync$2("git", [
 				"clone",
 				resolved.repository,
 				tempDir
 			], { timeout: GIT_TIMEOUT_MS });
-			await execFileAsync$1("git", ["checkout", resolved.commit], {
+			await execFileAsync$2("git", ["checkout", resolved.commit], {
 				cwd: tempDir,
 				timeout: GIT_TIMEOUT_MS
 			});
@@ -312,7 +314,7 @@ var Installer = class {
 			dependencies: { ...SHARED_PACKAGES }
 		};
 		writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf-8");
-		log$2.info("Installing shared @alfe.ai packages for integration hooks");
+		log$4.info("Installing shared @alfe.ai packages for integration hooks");
 		await this.runNpmInstall(this.basePath);
 		this.sharedPackagesReady = true;
 	}
@@ -322,12 +324,12 @@ var Installer = class {
 	*/
 	async installLocalDependencies(installPath) {
 		if (!existsSync(join(installPath, "package.json"))) return;
-		log$2.info({ path: installPath }, "Installing integration-specific npm dependencies");
+		log$4.info({ path: installPath }, "Installing integration-specific npm dependencies");
 		await this.runNpmInstall(installPath);
 	}
 	async runNpmInstall(cwd) {
 		try {
-			await execFileAsync$1("npm", [
+			await execFileAsync$2("npm", [
 				"install",
 				"--production",
 				"--no-audit",
@@ -564,12 +566,17 @@ var LockManager = class {
 	}
 	/**
 	* Add entries for an integration activation in a specific runtime.
+	*
+	* Pass `opts.configApplied` when the integration applied runtime config so
+	* the contribution is recorded even if it ships no plugins/skills — this is
+	* what lets a config-only integration be torn down on deactivate.
 	*/
-	addEntries(runtime, integrationId, version, plugins, skills, installPath) {
+	addEntries(runtime, integrationId, version, plugins, skills, installPath, opts) {
 		const lock = this.read();
 		if (!(runtime in lock.runtimes)) lock.runtimes[runtime] = {
 			plugins: [],
-			skills: []
+			skills: [],
+			config: []
 		};
 		const state = lock.runtimes[runtime];
 		for (const plugin of plugins) if (!state.plugins.some((p) => p.package === plugin.package && p.sourceIntegration === integrationId)) state.plugins.push({
@@ -587,11 +594,22 @@ var LockManager = class {
 				integrationVersion: version
 			});
 		}
+		if (opts?.configApplied) {
+			state.config ??= [];
+			if (!state.config.some((c) => c.sourceIntegration === integrationId)) state.config.push({
+				sourceIntegration: integrationId,
+				integrationVersion: version
+			});
+		}
 		this.write(lock);
 	}
 	/**
 	* Remove all entries for a given integration across all runtimes.
 	* Returns what was removed, keyed by runtime.
+	*
+	* A runtime is included in the result when the integration contributed
+	* plugins, skills, OR config there — so `deactivate` drives
+	* `applier.removeConfig` even for a config-only integration.
 	*/
 	removeEntries(integrationId) {
 		const lock = this.read();
@@ -599,12 +617,15 @@ var LockManager = class {
 		for (const [runtime, state] of Object.entries(lock.runtimes)) {
 			const removedPlugins = state.plugins.filter((p) => p.sourceIntegration === integrationId);
 			const removedSkills = state.skills.filter((s) => s.sourceIntegration === integrationId);
-			if (removedPlugins.length > 0 || removedSkills.length > 0) removed[runtime] = {
+			const removedConfig = (state.config ?? []).filter((c) => c.sourceIntegration === integrationId);
+			if (removedPlugins.length > 0 || removedSkills.length > 0 || removedConfig.length > 0) removed[runtime] = {
 				plugins: removedPlugins,
-				skills: removedSkills
+				skills: removedSkills,
+				config: removedConfig
 			};
 			state.plugins = state.plugins.filter((p) => p.sourceIntegration !== integrationId);
 			state.skills = state.skills.filter((s) => s.sourceIntegration !== integrationId);
+			if (state.config) state.config = state.config.filter((c) => c.sourceIntegration !== integrationId);
 		}
 		this.write(lock);
 		return removed;
@@ -1163,18 +1184,22 @@ var IntegrationManager = class {
 					this.log.info(`Applying skill ${skillName} to ${runtimeName}`);
 					await applier.applySkill(skillName, srcPath);
 				}
+				let runtimeConfigApplied = false;
 				if (runtimeConfig && Object.keys(runtimeConfig).length > 0) {
 					const agentConfig = entry.config;
 					const interpolatedConfig = interpolateSelfConfig(runtimeConfig, agentConfig);
 					this.log.info(`Applying config for ${integrationId} to ${runtimeName}`);
 					await applier.applyConfig(integrationId, interpolatedConfig);
 					configApplied = true;
+					runtimeConfigApplied = true;
 				}
 				const appliedPlugins = plugins.filter((p) => !pluginFailures.includes(p.package));
-				if (appliedPlugins.length > 0 || skills.length > 0) this.lockManager.addEntries(runtimeName, integrationId, manifest.version, appliedPlugins, skills, installPath);
+				if (appliedPlugins.length > 0 || skills.length > 0 || runtimeConfigApplied) this.lockManager.addEntries(runtimeName, integrationId, manifest.version, appliedPlugins, skills, installPath, { configApplied: runtimeConfigApplied });
 			}
 			const mcpServers = manifest.mcp_servers ?? [];
-			if (mcpServers.length > 0) if (!this.mcpApplier) this.log.warn(`Integration "${integrationId}" declares ${String(mcpServers.length)} mcp_server(s) but no mcpApplier is wired — skipping MCP registration`);
+			const runtimeSupportsMcp = !supportedAgents || supportedAgents.length === 0 || [...this.runtimeAppliers.keys()].some((r) => supportedAgents.includes(r));
+			if (mcpServers.length > 0 && !runtimeSupportsMcp) this.log.warn(`Integration "${integrationId}" declares ${String(mcpServers.length)} mcp_server(s) but no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${supportedAgents.join(", ")}) — skipping MCP registration`);
+			else if (mcpServers.length > 0) if (!this.mcpApplier) this.log.warn(`Integration "${integrationId}" declares ${String(mcpServers.length)} mcp_server(s) but no mcpApplier is wired — skipping MCP registration`);
 			else {
 				const secretEntries = this.secrets.get(integrationId);
 				const mergedConfig = {
@@ -1592,6 +1617,54 @@ var IntegrationManager = class {
 	}
 };
 //#endregion
+//#region src/appliers/config-flatten.ts
+function flattenConfig(obj, prefix = "") {
+	const entries = [];
+	for (const [key, val] of Object.entries(obj)) {
+		if (key.includes(".")) {
+			entries.push({
+				kind: "subtree",
+				parentPath: prefix,
+				dottedKey: key,
+				value: val
+			});
+			continue;
+		}
+		const path = prefix ? `${prefix}.${key}` : key;
+		if (val !== null && typeof val === "object" && !Array.isArray(val)) entries.push(...flattenConfig(val, path));
+		else entries.push({
+			kind: "leaf",
+			path,
+			value: val
+		});
+	}
+	return entries;
+}
+function partitionEntries(entries) {
+	const leaves = [];
+	const subtreesByParent = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (entry.kind === "leaf") {
+			leaves.push({
+				path: entry.path,
+				value: entry.value
+			});
+			continue;
+		}
+		if (!entry.parentPath) throw new Error(`config-flatten: top-level config keys containing dots are not supported (key: "${entry.dottedKey}")`);
+		let bucket = subtreesByParent.get(entry.parentPath);
+		if (!bucket) {
+			bucket = /* @__PURE__ */ new Map();
+			subtreesByParent.set(entry.parentPath, bucket);
+		}
+		bucket.set(entry.dottedKey, entry.value);
+	}
+	return {
+		leaves,
+		subtreesByParent
+	};
+}
+//#endregion
 //#region src/appliers/openclaw-applier.ts
 /**
 * OpenClawApplier — applies plugins, skills, and config to the OpenClaw runtime.
@@ -1602,8 +1675,8 @@ var IntegrationManager = class {
 * config file (openclaw.json) without clobbering. Per-integration tracking
 * is stored in a separate tracking file (config.json) for clean removal.
 */
-const execFileAsync = promisify(execFile);
-const log$1 = createLogger("OpenClawApplier");
+const execFileAsync$1 = promisify(execFile);
+const log$3 = createLogger("OpenClawApplier");
 const DEFAULT_SKILLS_DIR = join(homedir(), ".alfe", "skills");
 /**
 * Bundled OpenClaw plugins that ship inside the runtime (not installed as npm
@@ -1627,9 +1700,9 @@ const BUNDLED_BASELINE_ALLOW = ["browser"];
 * chain and retry transient failures with a short backoff so the reload has
 * time to settle between writes.
 */
-const CONFIG_SET_RETRIES = 3;
-const CONFIG_SET_RETRY_DELAY_MS = 750;
-const delay = (ms) => new Promise((resolve) => {
+const CONFIG_SET_RETRIES$1 = 3;
+const CONFIG_SET_RETRY_DELAY_MS$1 = 750;
+const delay$1 = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
 /**
@@ -1657,55 +1730,9 @@ function configSetErrorMessage(err, args) {
 	}
 	return `${target} failed: ${String(err)}`;
 }
-function flattenConfig(obj, prefix = "") {
-	const entries = [];
-	for (const [key, val] of Object.entries(obj)) {
-		if (key.includes(".")) {
-			entries.push({
-				kind: "subtree",
-				parentPath: prefix,
-				dottedKey: key,
-				value: val
-			});
-			continue;
-		}
-		const path = prefix ? `${prefix}.${key}` : key;
-		if (val !== null && typeof val === "object" && !Array.isArray(val)) entries.push(...flattenConfig(val, path));
-		else entries.push({
-			kind: "leaf",
-			path,
-			value: val
-		});
-	}
-	return entries;
-}
-function partitionEntries(entries) {
-	const leaves = [];
-	const subtreesByParent = /* @__PURE__ */ new Map();
-	for (const entry of entries) {
-		if (entry.kind === "leaf") {
-			leaves.push({
-				path: entry.path,
-				value: entry.value
-			});
-			continue;
-		}
-		if (!entry.parentPath) throw new Error(`OpenClawApplier: top-level config keys containing dots are not supported (key: "${entry.dottedKey}")`);
-		let bucket = subtreesByParent.get(entry.parentPath);
-		if (!bucket) {
-			bucket = /* @__PURE__ */ new Map();
-			subtreesByParent.set(entry.parentPath, bucket);
-		}
-		bucket.set(entry.dottedKey, entry.value);
-	}
-	return {
-		leaves,
-		subtreesByParent
-	};
-}
 async function readParentObject(parentPath) {
 	try {
-		const { stdout } = await execFileAsync("openclaw", [
+		const { stdout } = await execFileAsync$1("openclaw", [
 			"config",
 			"get",
 			parentPath
@@ -1732,8 +1759,8 @@ var OpenClawApplier = class {
 		this.agentWorkspace = options.agentWorkspace ?? join(home, "workspace");
 		this.skillsDir = options.skillsDir ?? DEFAULT_SKILLS_DIR;
 		this.trackingPath = options.configPath ?? join(this.home, "config.json");
-		this.configSetRetries = options.configSetRetries ?? CONFIG_SET_RETRIES;
-		this.configSetRetryDelayMs = options.configSetRetryDelayMs ?? CONFIG_SET_RETRY_DELAY_MS;
+		this.configSetRetries = options.configSetRetries ?? CONFIG_SET_RETRIES$1;
+		this.configSetRetryDelayMs = options.configSetRetryDelayMs ?? CONFIG_SET_RETRY_DELAY_MS$1;
 	}
 	/** Convenience: `openclaw config set <args>`, serialized + retried. */
 	runConfigSet(setArgs, opts = {}) {
@@ -1754,11 +1781,11 @@ var OpenClawApplier = class {
 		const run = async () => {
 			let lastErr;
 			for (let attempt = 0; attempt <= this.configSetRetries; attempt++) try {
-				await execFileAsync("openclaw", ["config", ...args], { timeout });
+				await execFileAsync$1("openclaw", ["config", ...args], { timeout });
 				return;
 			} catch (err) {
 				lastErr = err;
-				if (attempt < this.configSetRetries && this.configSetRetryDelayMs > 0) await delay(this.configSetRetryDelayMs * 2 ** attempt);
+				if (attempt < this.configSetRetries && this.configSetRetryDelayMs > 0) await delay$1(this.configSetRetryDelayMs * 2 ** attempt);
 			}
 			throw new Error(configSetErrorMessage(lastErr, args));
 		};
@@ -1771,14 +1798,14 @@ var OpenClawApplier = class {
 		await this.ensurePluginsAllow(pkg);
 		this.cleanupUntrackedExtensionInstall(pkg);
 		if (opts?.force && this.isPluginInstalled(pkg)) {
-			log$1.info({
+			log$3.info({
 				pkg,
 				spec
 			}, "Force mode — uninstalling plugin before reinstall");
 			try {
 				await this.removePlugin(pkg);
 			} catch (err) {
-				log$1.warn({
+				log$3.warn({
 					pkg,
 					spec,
 					err: err instanceof Error ? err.message : String(err)
@@ -1796,12 +1823,12 @@ var OpenClawApplier = class {
 			const args = useUnsafeFlag ? [...baseArgs, "--dangerously-force-unsafe-install"] : baseArgs;
 			try {
 				try {
-					await execFileAsync("openclaw", args, { timeout: 6e4 });
+					await execFileAsync$1("openclaw", args, { timeout: 6e4 });
 				} catch (err) {
 					const errText = err instanceof Error ? `${err.message}\n${err.stderr ?? ""}` : String(err);
 					if (useUnsafeFlag && errText.includes("unknown option")) {
-						log$1.info({ pkg }, "OpenClaw does not support --dangerously-force-unsafe-install, retrying without");
-						await execFileAsync("openclaw", baseArgs, { timeout: 6e4 });
+						log$3.info({ pkg }, "OpenClaw does not support --dangerously-force-unsafe-install, retrying without");
+						await execFileAsync$1("openclaw", baseArgs, { timeout: 6e4 });
 					} else throw err;
 				}
 			} catch (err) {
@@ -1809,7 +1836,7 @@ var OpenClawApplier = class {
 					setTimeout(r, 500);
 				});
 				if (!this.isPluginInstalled(pkg)) throw err;
-				log$1.warn({
+				log$3.warn({
 					pkg,
 					spec,
 					err: err instanceof Error ? err.message : String(err)
@@ -1832,7 +1859,7 @@ var OpenClawApplier = class {
 		const wanted = Array.isArray(pkgs) ? pkgs : [pkgs];
 		let currentAllow = [];
 		try {
-			const { stdout } = await execFileAsync("openclaw", [
+			const { stdout } = await execFileAsync$1("openclaw", [
 				"config",
 				"get",
 				"plugins.allow"
@@ -1846,7 +1873,7 @@ var OpenClawApplier = class {
 		try {
 			await this.runConfigSet(["plugins.allow", JSON.stringify(updated)]);
 		} catch (err) {
-			log$1.warn({
+			log$3.warn({
 				err: err instanceof Error ? err.message : String(err),
 				pkgs: wanted
 			}, "Failed to set plugins.allow via openclaw config set");
@@ -1910,12 +1937,12 @@ var OpenClawApplier = class {
 					recursive: true,
 					force: true
 				});
-				log$1.info({
+				log$3.info({
 					pkg,
 					removed: fullPath
 				}, "Removed untracked extensions/ install — will reinstall via npm path");
 			} catch (err) {
-				log$1.warn({
+				log$3.warn({
 					pkg,
 					removed: fullPath,
 					err: err instanceof Error ? err.message : String(err)
@@ -1924,7 +1951,7 @@ var OpenClawApplier = class {
 		}
 	}
 	async removePlugin(spec) {
-		await execFileAsync("openclaw", [
+		await execFileAsync$1("openclaw", [
 			"plugins",
 			"uninstall",
 			"--force",
@@ -1938,21 +1965,21 @@ var OpenClawApplier = class {
 		return Promise.resolve();
 	}
 	async applyClawHubSkill(slug) {
-		log$1.info({ slug }, "Installing skill from ClawHub");
+		log$3.info({ slug }, "Installing skill from ClawHub");
 		try {
-			await execFileAsync("openclaw", [
+			await execFileAsync$1("openclaw", [
 				"skills",
 				"install",
 				slug
 			], { timeout: 6e4 });
-			log$1.info({ slug }, "ClawHub skill installed");
+			log$3.info({ slug }, "ClawHub skill installed");
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			if (msg.includes("already exists") || msg.includes("Skill already exists")) {
-				log$1.info({ slug }, "ClawHub skill already installed (skipped)");
+				log$3.info({ slug }, "ClawHub skill already installed (skipped)");
 				return;
 			}
-			log$1.error({
+			log$3.error({
 				slug,
 				err: msg
 			}, "ClawHub skill install failed");
@@ -1965,7 +1992,7 @@ var OpenClawApplier = class {
 				recursive: true,
 				force: true
 			});
-			log$1.info({ slug }, "ClawHub skill removed");
+			log$3.info({ slug }, "ClawHub skill removed");
 		}
 		return Promise.resolve();
 	}
@@ -1996,7 +2023,7 @@ var OpenClawApplier = class {
 			try {
 				await this.runConfigSet([parentPath, JSON.stringify(merged)]);
 			} catch (err) {
-				log$1.error({
+				log$3.error({
 					err: err instanceof Error ? err.message : String(err),
 					parentPath
 				}, "Failed to set config subtree via openclaw config set");
@@ -2006,7 +2033,7 @@ var OpenClawApplier = class {
 		if (leaves.length > 0) try {
 			await this.runConfigSet(["--batch-json", JSON.stringify(leaves)]);
 		} catch (err) {
-			log$1.error({
+			log$3.error({
 				err: err instanceof Error ? err.message : String(err),
 				batch: leaves
 			}, "Failed to set config via openclaw config set --batch-json");
@@ -2028,7 +2055,7 @@ var OpenClawApplier = class {
 		for (const { path } of leaves) try {
 			await this.runConfigCommand(["unset", path]);
 		} catch (err) {
-			log$1.warn({
+			log$3.warn({
 				err: err instanceof Error ? err.message : String(err),
 				path
 			}, "Failed to unset config via openclaw config unset");
@@ -2041,7 +2068,7 @@ var OpenClawApplier = class {
 				if (Object.keys(remaining).length === 0) await this.runConfigCommand(["unset", parentPath]);
 				else await this.runConfigSet([parentPath, JSON.stringify(remaining)]);
 			} catch (err) {
-				log$1.warn({
+				log$3.warn({
 					err: err instanceof Error ? err.message : String(err),
 					parentPath
 				}, "Failed to update parent config during remove");
@@ -2050,9 +2077,292 @@ var OpenClawApplier = class {
 		tracking._integrations = Object.fromEntries(Object.entries(integrations).filter(([key]) => key !== integrationId));
 		this.writeTracking(tracking);
 	}
+	/**
+	* Raw single-key config write — `openclaw config set <key> <value>`.
+	*
+	* Deliberately bypasses the `_integrations` tracking that `applyConfig`
+	* maintains: this is a fire-and-forget write for the `alfe.config_set`
+	* cloud-command, not an integration contribution, so it must NOT be
+	* recorded for later `removeConfig` teardown. Reuses the serialized +
+	* retried queue so it can't interleave with the hot-reload that integration
+	* config writes trigger.
+	*/
+	setConfigRaw(key, value) {
+		return this.runConfigSet([key, value]);
+	}
+	isAvailable() {
+		return Promise.resolve(existsSync(this.home));
+	}
+	readTracking() {
+		if (!existsSync(this.trackingPath)) return {};
+		try {
+			return JSON.parse(readFileSync(this.trackingPath, "utf-8"));
+		} catch {
+			return {};
+		}
+	}
+	writeTracking(config) {
+		mkdirSync(join(this.trackingPath, ".."), { recursive: true });
+		writeFileSync(this.trackingPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+	}
+};
+//#endregion
+//#region src/appliers/hermes-applier.ts
+/**
+* HermesApplier — applies integration config (and, later, native plugins) to
+* the Hermes runtime (Nous Research's Python agent).
+*
+* Hermes config lives in `~/.hermes/config.yaml` (YAML) and is mutated via the
+* `hermes config set/unset <dotted.key> <value>` CLI — we never write the YAML
+* file directly (mirrors the OpenClaw rule of letting the runtime own its own
+* config format). Per-integration contributions are tracked in a separate file
+* (`~/.hermes/.alfe-integrations.json`) so removal is precise.
+*
+* Scope (Phase 1, MCP-first hybrid):
+*  - config: SUPPORTED — consumes `installs.runtimes.hermes.config` (the AI-proxy
+*    routing keys: model.provider/base_url/api_key/model, etc.).
+*  - plugins: the `@alfe.ai/openclaw-*` npm plugins are OpenClaw-specific and are
+*    log-and-skipped here; a real Hermes-native plugin spec (git/pip/dir) would
+*    `hermes plugins install`/`enable`, but no manifest declares one yet.
+*  - skills: no-op (Hermes ships built-in skills; ClawHub is OpenClaw-only) —
+*    deferred to a later per-capability phase.
+*  - MCP: NOT handled here. MCP delivery for Hermes is a later phase (config-only
+*    `mcp_servers:` via the runtime-agnostic store consumer). This applier owns
+*    config + plugins only.
+*/
+const execFileAsync = promisify(execFile);
+const log$2 = createLogger("HermesApplier");
+const DEFAULT_HERMES_HOME$1 = join(homedir(), ".hermes");
+/**
+* Hermes config writes are serialized through one promise chain so concurrent
+* `applyConfig` calls (the manager can fan out across integrations) never
+* interleave their `hermes config set` writes against the same config.yaml.
+*
+* Whether Hermes hot-reloads config.yaml on each write — the way OpenClaw does,
+* which forced a retry/backoff there — is NOT yet spike-confirmed. We keep a
+* modest retry as a precaution; if the spike proves Hermes writes are
+* synchronous and race-free, the retry count can drop to 0 without API change.
+*/
+const CONFIG_SET_RETRIES = 3;
+const CONFIG_SET_RETRY_DELAY_MS = 750;
+const delay = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+/** `@alfe.ai/openclaw-*` packages are OpenClaw-specific plugins — not Hermes. */
+function isOpenClawPlugin(spec) {
+	return stripPluginVersion(spec).startsWith("@alfe.ai/openclaw-");
+}
+/**
+* Serialize a config value for `hermes config set <key> <value>`. Strings pass
+* through verbatim (the proxy routing keys — provider/base_url/api_key/model —
+* are all strings, including `${ALFE_API_KEY}` env refs). Non-strings are
+* JSON-encoded so booleans/numbers/objects survive the CLI round-trip.
+*/
+function stringifyConfigValue(value) {
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+/**
+* Describe a `config set/unset` target WITHOUT leaking values. The value
+* argument can be a secret (`model.api_key`), so it must never reach the
+* integration's user-facing `errorMessage`. Keep only the program + verb + key.
+*/
+function redactConfigTarget(args) {
+	return `hermes config ${args.slice(0, 2).join(" ")}`.trim();
+}
+/**
+* Build a diagnosable BUT scrubbed message from an execFile rejection. Node's
+* execFile error `message` is "Command failed: <full argv>" — which for
+* `config set` embeds the value payload — so we never surface it. We keep the
+* redacted target, the exit code, and `stderr` (hermes' own error text).
+*/
+function configErrorMessage(err, args) {
+	const target = redactConfigTarget(args);
+	if (err instanceof Error) {
+		const e = err;
+		const stderr = typeof e.stderr === "string" ? e.stderr.trim() : "";
+		const code = e.code !== void 0 ? ` (exit ${e.code})` : "";
+		return stderr ? `${target} failed${code}: ${stderr}` : `${target} failed${code}`;
+	}
+	return `${target} failed: ${String(err)}`;
+}
+var HermesApplier = class {
+	runtime = "hermes";
+	home;
+	trackingPath;
+	configSetRetries;
+	configSetRetryDelayMs;
+	/** Serializes all `hermes config` writes so they never interleave. */
+	configSetQueue = Promise.resolve();
+	constructor(options = {}) {
+		this.home = options.home ?? options.workspace ?? DEFAULT_HERMES_HOME$1;
+		this.trackingPath = options.configPath ?? join(this.home, ".alfe-integrations.json");
+		this.configSetRetries = options.configSetRetries ?? CONFIG_SET_RETRIES;
+		this.configSetRetryDelayMs = options.configSetRetryDelayMs ?? CONFIG_SET_RETRY_DELAY_MS;
+	}
+	/**
+	* Apply integration config to the Hermes runtime via `hermes config set`.
+	*
+	* Each leaf is applied as `hermes config set <dotted.key> <value>`. Each
+	* integration's config contribution is tracked in the tracking file so it can
+	* be cleanly removed later (mirrors OpenClawApplier's `_integrations`).
+	*/
+	async applyConfig(integrationId, config) {
+		const tracking = this.readTracking();
+		const integrations = tracking._integrations ?? {};
+		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()]
+		}, "Hermes applyConfig: skipping dotted-key subtree(s) — OpenClaw-plugin-shaped config does not apply to Hermes");
+		for (const { path, value } of leaves) try {
+			await this.runConfigSet([path, stringifyConfigValue(value)]);
+		} catch (err) {
+			log$2.error({
+				err: err instanceof Error ? err.message : String(err),
+				key: path
+			}, "Failed to set config via hermes config set");
+			throw err;
+		}
+	}
+	/**
+	* Remove config previously applied by an integration.
+	*
+	* Reads the tracking file to find which keys this integration set, then
+	* removes each via `hermes config unset`. Clears the tracking entry.
+	*/
+	async removeConfig(integrationId) {
+		const tracking = this.readTracking();
+		const integrations = tracking._integrations ?? {};
+		if (!(integrationId in integrations)) return;
+		const integrationConfig = integrations[integrationId];
+		const { leaves } = partitionEntries(flattenConfig(integrationConfig));
+		for (const { path } of leaves) try {
+			await this.unsetConfigKey(path);
+		} catch (err) {
+			log$2.warn({
+				err: err instanceof Error ? err.message : String(err),
+				key: path
+			}, "Failed to unset config via hermes config unset");
+		}
+		tracking._integrations = Object.fromEntries(Object.entries(integrations).filter(([key]) => key !== integrationId));
+		this.writeTracking(tracking);
+	}
+	/**
+	* Raw single-key config write — `hermes config set <key> <value>`.
+	*
+	* Deliberately bypasses the `_integrations` tracking that `applyConfig`
+	* maintains: this is a fire-and-forget write for the `alfe.config_set`
+	* cloud-command, NOT an integration contribution, so it must not be recorded
+	* for later `removeConfig` teardown (doing so would corrupt the
+	* per-integration removal accounting). Reuses the serialized queue.
+	*/
+	setConfigRaw(key, value) {
+		return this.runConfigSet([key, value]);
+	}
+	/**
+	* Apply a plugin. The `@alfe.ai/openclaw-*` npm plugins are OpenClaw-specific
+	* (they carry the `openclaw` peer dep) and do NOT apply to Hermes — log + skip
+	* them. The manager catches per-plugin, so a skip here is a correct no-op.
+	*
+	* A genuine Hermes-native plugin spec (git URL / pip / local dir) would
+	* `hermes plugins install` then `hermes plugins enable`; no manifest declares
+	* one in Phase 1, so this path is a real attempt (not faked) but untrodden.
+	*/
+	async applyPlugin(spec) {
+		if (isOpenClawPlugin(spec)) {
+			log$2.info({ spec }, "Hermes applyPlugin: skipping OpenClaw-specific npm plugin (not a Hermes plugin)");
+			return;
+		}
+		log$2.info({ spec }, "Hermes applyPlugin: installing native Hermes plugin");
+		await execFileAsync("hermes", [
+			"plugins",
+			"install",
+			spec
+		], { timeout: 6e4 });
+		await execFileAsync("hermes", [
+			"plugins",
+			"enable",
+			spec
+		], { timeout: 3e4 });
+	}
+	/**
+	* Remove a plugin. OpenClaw-specific npm plugins were never installed into
+	* Hermes (applyPlugin skipped them), so removal is a no-op log. A native
+	* Hermes plugin would be disabled via `hermes plugins`.
+	*/
+	async removePlugin(spec) {
+		if (isOpenClawPlugin(spec)) {
+			log$2.info({ spec }, "Hermes removePlugin: skipping OpenClaw-specific npm plugin (was never installed on Hermes)");
+			return;
+		}
+		log$2.info({ spec }, "Hermes removePlugin: disabling native Hermes plugin");
+		await execFileAsync("hermes", [
+			"plugins",
+			"disable",
+			spec
+		], { timeout: 3e4 });
+	}
+	applySkill(name) {
+		log$2.info({ name }, "Hermes applySkill: no-op (Hermes built-in skills; deferred)");
+		return Promise.resolve();
+	}
+	removeSkill(name) {
+		log$2.info({ name }, "Hermes removeSkill: no-op (Hermes built-in skills; deferred)");
+		return Promise.resolve();
+	}
+	applyClawHubSkill(slug) {
+		log$2.info({ slug }, "Hermes applyClawHubSkill: no-op (ClawHub is OpenClaw-only)");
+		return Promise.resolve();
+	}
+	removeClawHubSkill(slug) {
+		log$2.info({ slug }, "Hermes removeClawHubSkill: no-op (ClawHub is OpenClaw-only)");
+		return Promise.resolve();
+	}
 	isAvailable() {
 		return Promise.resolve(existsSync(this.home));
 	}
+	/** Convenience: `hermes config set <args>`, serialized + retried. */
+	runConfigSet(setArgs) {
+		return this.runConfigCommand(["set", ...setArgs]);
+	}
+	/**
+	* Unset a single config key. The unset verb is isolated HERE so there is one
+	* place to change if the spike proves `hermes config unset` is unavailable.
+	*
+	* FALLBACK (do NOT pre-build): if `hermes config unset` does not exist, the
+	* substitute is `hermes config set <key> ""` (clear the value) or a
+	* read-merge-write of config.yaml. Not implemented now — `unset` is the
+	* documented verb; confirm in the Phase-0 spike before adding a fallback.
+	* TODO(phase-0 spike): confirm `hermes config unset <key>` exists.
+	*/
+	unsetConfigKey(key) {
+		return this.runConfigCommand(["unset", key]);
+	}
+	/**
+	* Run `hermes config <args>` (set/unset), serialized against every other
+	* config write and retried with backoff. Throws an Error whose (scrubbed)
+	* message includes stderr after retries are exhausted, so the real cause
+	* propagates to the integration errorMessage without leaking the value.
+	*/
+	runConfigCommand(args) {
+		const run = async () => {
+			let lastErr;
+			for (let attempt = 0; attempt <= this.configSetRetries; attempt++) try {
+				await execFileAsync("hermes", ["config", ...args], { timeout: 1e4 });
+				return;
+			} catch (err) {
+				lastErr = err;
+				if (attempt < this.configSetRetries && this.configSetRetryDelayMs > 0) await delay(this.configSetRetryDelayMs * 2 ** attempt);
+			}
+			throw new Error(configErrorMessage(lastErr, args));
+		};
+		const result = this.configSetQueue.then(run, run);
+		this.configSetQueue = result.catch(() => void 0);
+		return result;
+	}
 	readTracking() {
 		if (!existsSync(this.trackingPath)) return {};
 		try {
@@ -2067,6 +2377,265 @@ var OpenClawApplier = class {
 	}
 };
 //#endregion
+//#region src/appliers/hermes-mcp-sync.ts
+/**
+* HermesMcpSync — Hermes-only CONSUMER of the runtime-agnostic MCP store
+* (Approach B: config.yaml mirror).
+*
+* Background: `McpApplier` writes resolved MCP servers (command/args/env, with
+* `{{config}}`/`{{credentials}}` already interpolated at apply time) into the
+* runtime-agnostic bundler store at `~/.alfe/mcp/servers.json`. OpenClaw consumes
+* that store over IPC (the daemon hosts the bundler children and the openclaw
+* plugin reaches them). Hermes cannot consume over IPC — it reads MCP servers
+* from its own `~/.hermes/config.yaml` under the top-level `mcp_servers:` key and
+* spawns the children itself. So Hermes needs its own consumer that mirrors the
+* store into `config.yaml`.
+*
+* This class is the parallel to OpenClaw's IPC consumption: it subscribes to
+* `manager.onChange()` and, **only when the active runtime is hermes** (the
+* daemon only constructs it for hermes agents), read-merge-writes the store into
+* `~/.hermes/config.yaml`, preserving user-authored `mcp_servers` and every other
+* config key.
+*
+* Two cross-cutting responsibilities make the mirrored servers actually work:
+*
+*  1. `ALFE_API_KEY` injection. The Alfe MCP servers (`@alfe.ai/<provider>-mcp`)
+*     fetch their real provider credentials from the Alfe API at startup using
+*     `ALFE_API_KEY`. For OpenClaw the daemon spawns the children, so they
+*     inherit `ALFE_API_KEY` from the daemon's own `process.env`. Hermes spawns
+*     the children itself in a separate process tree, so they would NOT inherit
+*     it — without it they start in a silent zero-accounts degraded mode. We
+*     therefore inject an `ALFE_API_KEY` reference into every mirrored stdio
+*     server's env and write the actual secret into `~/.hermes/.env`
+*     (read-merge-write, never clobbering other keys).
+*
+*  2. Restart. Writing `config.yaml` is assumed to require a runtime reload (vs a
+*     hot-reload) — SPIKE-PENDING — so after a real change we trigger the EXISTING
+*     runtime-restart path (the same callback the daemon's
+*     `setRuntimeRestartNeededHandler` uses), never a second restart mechanism.
+*
+* The daemon gates its own bundler OFF for hermes (skips `loadIntoBundler` +
+* `warmup`) so the store is a pure ledger and the MCP children are spawned ONLY
+* by Hermes — avoiding a double-spawn of every server.
+*/
+const log$1 = createLogger("HermesMcpSync");
+const DEFAULT_HERMES_HOME = join(homedir(), ".hermes");
+/**
+* SPIKE-PENDING SEAM #1 — `${VAR}` interpolation from `~/.hermes/.env`.
+*
+* We inject `ALFE_API_KEY=${ALFE_API_KEY}` into every Alfe-owned stdio server's
+* env and put the real value in `~/.hermes/.env`. This assumes Hermes
+* interpolates `${VAR}` references in `mcp_servers.<id>.env` from `.env` at spawn
+* time. TODO(phase-0 spike): confirm. If Hermes does NOT interpolate, the
+* fallback (NOT built here) is to write the literal `ALFE_API_KEY` VALUE inline
+* into each `mcp_servers.<id>.env` and skip the `.env` file entirely — change
+* `withAlfeApiKey()` + `ensureEnvApiKey()` together in that one case.
+*/
+const ALFE_API_KEY_ENV_REF = "${ALFE_API_KEY}";
+const DEFAULT_DEBOUNCE_MS = 250;
+/**
+* Read-merge-write mirror of the MCP store into `~/.hermes/config.yaml`.
+*
+* Ownership / removal model: every entry returned by `manager.listServers()`
+* comes from the Alfe store (its `owner` is `integration:<id>` / `cli` /
+* `manual`) and is therefore Alfe-owned — these are the ids we write. User
+* authored `mcp_servers` entries live ONLY in config.yaml and never appear in
+* the store, so we never touch them. To know which config.yaml ids to REMOVE
+* when a server leaves the store, we persist the set of ids we last wrote to a
+* sidecar (`.alfe-mcp-synced.json`) and only ever delete from that set — exactly
+* how the bundler store tracks `_ownedOpenclawKeys` for its openclaw.json mirror.
+*/
+var HermesMcpSync = class {
+	manager;
+	home;
+	apiKey;
+	requestRestart;
+	configPath;
+	envPath;
+	trackingPath;
+	debounceMs;
+	/** Ids of `mcp_servers` entries this sync last wrote — the removal set. */
+	syncedIds = /* @__PURE__ */ new Set();
+	/** Serializes syncs so two onChange-driven runs can't interleave file writes. */
+	queue = Promise.resolve();
+	unsubscribe;
+	debounceTimer;
+	started = false;
+	constructor(opts) {
+		this.manager = opts.manager;
+		this.home = opts.home ?? DEFAULT_HERMES_HOME;
+		this.apiKey = opts.apiKey;
+		this.requestRestart = opts.requestRestart;
+		this.configPath = opts.configPath ?? join(this.home, "config.yaml");
+		this.envPath = opts.envPath ?? join(this.home, ".env");
+		this.trackingPath = opts.trackingPath ?? join(this.home, ".alfe-mcp-synced.json");
+		this.debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+	}
+	/**
+	* Begin mirroring: load the prior removal set, run one immediate sync (so
+	* config.yaml reflects the current store before Hermes first starts), then
+	* subscribe to store changes (debounced). Idempotent.
+	*/
+	start() {
+		if (this.started) return;
+		this.started = true;
+		this.loadSyncedIds();
+		this.syncOnce().catch((err) => {
+			log$1.warn({ err: errMsg$1(err) }, "Hermes MCP sync: initial sync failed");
+		});
+		this.unsubscribe = this.manager.onChange(() => {
+			this.schedule();
+		});
+		log$1.info({ configPath: this.configPath }, "Hermes MCP sync started — mirroring store into config.yaml");
+	}
+	/** Stop subscribing and cancel any pending debounced sync. Idempotent. */
+	stop() {
+		if (this.unsubscribe) {
+			this.unsubscribe();
+			this.unsubscribe = void 0;
+		}
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = void 0;
+		}
+		this.started = false;
+	}
+	/**
+	* Mirror the current store into config.yaml + .env exactly once. Public so the
+	* daemon (and tests) can await a deterministic sync. Serialized against any
+	* other in-flight sync.
+	*/
+	syncOnce() {
+		const run = () => {
+			this.syncNow();
+			return Promise.resolve();
+		};
+		const result = this.queue.then(run, run);
+		this.queue = result.catch(() => void 0);
+		return result;
+	}
+	schedule() {
+		if (this.debounceMs <= 0) {
+			this.syncOnce().catch((err) => {
+				log$1.warn({ err: errMsg$1(err) }, "Hermes MCP sync failed");
+			});
+			return;
+		}
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		this.debounceTimer = setTimeout(() => {
+			this.debounceTimer = void 0;
+			this.syncOnce().catch((err) => {
+				log$1.warn({ err: errMsg$1(err) }, "Hermes MCP sync failed");
+			});
+		}, this.debounceMs);
+		this.debounceTimer.unref();
+	}
+	syncNow() {
+		const desired = this.computeDesired();
+		const desiredIds = new Set(desired.keys());
+		const doc = parseDocument(existsSync(this.configPath) ? readFileSync(this.configPath, "utf-8") : "");
+		const before = doc.toString();
+		for (const [id, entry] of desired) doc.setIn(["mcp_servers", id], entry);
+		for (const id of this.syncedIds) if (!desiredIds.has(id)) doc.deleteIn(["mcp_servers", id]);
+		const after = doc.toString();
+		let changed = before !== after;
+		if (changed) {
+			mkdirSync(dirname(this.configPath), { recursive: true });
+			writeFileSync(this.configPath, after, "utf-8");
+			log$1.info({
+				added: [...desiredIds],
+				removed: [...this.syncedIds].filter((id) => !desiredIds.has(id))
+			}, "Hermes MCP sync: config.yaml mcp_servers updated");
+		}
+		this.syncedIds = desiredIds;
+		this.persistSyncedIds();
+		if (desiredIds.size > 0 && this.ensureEnvApiKey()) changed = true;
+		if (changed) this.requestRestart?.();
+	}
+	computeDesired() {
+		const desired = /* @__PURE__ */ new Map();
+		for (const { id, entry } of this.manager.listServers()) desired.set(id, this.toHermesEntry(entry));
+		return desired;
+	}
+	/**
+	* Transform a stored entry into a Hermes `mcp_servers` entry. SPIKE-PENDING
+	* SEAM #3 lives here — the schema shape. stdio entries get `ALFE_API_KEY`
+	* injected; remote entries pass through (Hermes supports `url`-based MCP).
+	*/
+	toHermesEntry(entry) {
+		const cfg = toServerConfig(entry);
+		if ("command" in cfg) {
+			const out = { command: cfg.command };
+			if (cfg.args && cfg.args.length > 0) out.args = cfg.args;
+			out.env = this.withAlfeApiKey(cfg.env);
+			if (cfg.cwd) out.cwd = cfg.cwd;
+			return out;
+		}
+		const out = { url: cfg.url };
+		if (cfg.transport) out.transport = cfg.transport;
+		if (cfg.headers) out.headers = cfg.headers;
+		return out;
+	}
+	withAlfeApiKey(env) {
+		const merged = { ...env ?? {} };
+		if (!("ALFE_API_KEY" in merged)) merged.ALFE_API_KEY = ALFE_API_KEY_ENV_REF;
+		return merged;
+	}
+	/** Read-merge-write `~/.hermes/.env` to set ALFE_API_KEY without clobbering other keys. */
+	ensureEnvApiKey() {
+		if (!this.apiKey) {
+			log$1.warn("Hermes MCP sync: no ALFE_API_KEY available — mirrored MCP servers will start in zero-accounts degraded mode");
+			return false;
+		}
+		return upsertEnvVar(this.envPath, "ALFE_API_KEY", this.apiKey);
+	}
+	loadSyncedIds() {
+		if (!existsSync(this.trackingPath)) return;
+		try {
+			const data = JSON.parse(readFileSync(this.trackingPath, "utf-8"));
+			if (Array.isArray(data.syncedIds)) this.syncedIds = new Set(data.syncedIds.filter((x) => typeof x === "string"));
+		} catch {}
+	}
+	persistSyncedIds() {
+		try {
+			mkdirSync(dirname(this.trackingPath), { recursive: true });
+			writeFileSync(this.trackingPath, JSON.stringify({ syncedIds: [...this.syncedIds] }, null, 2) + "\n", "utf-8");
+		} catch (err) {
+			log$1.warn({ err: errMsg$1(err) }, "Hermes MCP sync: failed to persist synced-id sidecar");
+		}
+	}
+};
+/**
+* Set `KEY=value` in a `.env`-style file, preserving every other line (comments,
+* blank lines, unrelated keys) and order. Returns whether the file changed. Not
+* a full dotenv parser — it only matches simple `KEY=` lines, which is all
+* `~/.hermes/.env` ever holds.
+*/
+function upsertEnvVar(envPath, key, value) {
+	const desiredLine = `${key}=${value}`;
+	const existing = existsSync(envPath) ? readFileSync(envPath, "utf-8") : "";
+	const lines = existing.length > 0 ? existing.replace(/\n$/, "").split("\n") : [];
+	const keyRe = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+	const idx = lines.findIndex((line) => keyRe.exec(line)?.[1] === key);
+	let out;
+	let changed;
+	if (idx === -1) {
+		out = [...lines, desiredLine];
+		changed = true;
+	} else {
+		changed = lines[idx] !== desiredLine;
+		out = lines.map((line, i) => i === idx ? desiredLine : line);
+	}
+	if (changed) {
+		mkdirSync(dirname(envPath), { recursive: true });
+		writeFileSync(envPath, out.join("\n") + "\n", "utf-8");
+	}
+	return changed;
+}
+function errMsg$1(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
 //#region src/appliers/mcp-applier.ts
 const log = createLogger("McpApplier");
 const CONFIG_TEMPLATE_RE = /\{\{config\.([a-zA-Z0-9_]+)\}\}/g;
@@ -2246,4 +2815,4 @@ var IntegrationManagerAdapter = class {
 	}
 };
 //#endregion
-export { DEFAULT_REGISTRY_TTL_MS, Installer, InstallerError, IntegrationManager, IntegrationManagerAdapter, LockManager, McpApplier, OpenClawApplier, Registry, RegistryResolveError, Resolver, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };
+export { DEFAULT_REGISTRY_TTL_MS, HermesApplier, HermesMcpSync, Installer, InstallerError, IntegrationManager, IntegrationManagerAdapter, LockManager, McpApplier, OpenClawApplier, Registry, RegistryResolveError, Resolver, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext, upsertEnvVar };

package/package.json

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