@alfe.ai/gateway 0.1.5 → 0.2.1

package/README.md

@@ -161,3 +161,8 @@ See `src/protocol.ts` for full type definitions.
 
 - Dashboard integration management (backend wired, UI in progress)
 - Voice migration to integration model (`packages/openclaw-voice/` exists, not yet full integration)
+
+## Links
+
+- 🌐 Website: <https://alfe.ai>
+- 📚 Docs: <https://docs.alfe.ai>

package/dist/health.js

@@ -12,7 +12,7 @@ import crypto from "crypto";
 import { parse } from "smol-toml";
 import WebSocket from "ws";
 import { createConnection, createServer } from "node:net";
-import { IntegrationManager, IntegrationManagerAdapter, McpApplier, OpenClawApplier } from "@alfe.ai/integrations";
+import { HermesApplier, HermesMcpSync, IntegrationManager, IntegrationManagerAdapter, McpApplier, OpenClawApplier } from "@alfe.ai/integrations";
 import { AgentApiClient } from "@alfe.ai/agent-api-client";
 import { Manager, McpBundler, defaultConnect } from "@alfe.ai/mcp-bundler";
 import stream, { Readable } from "stream";
@@ -495,6 +495,15 @@ var AuthService = class {
 	getSubscriptionStatus() {
 		return this.client.request(`${this.prefix}/subscription`);
 	}
+	/**
+	* Mint a short-lived, single-use Clerk sign-in token for the calling user so
+	* a native client can hand its logged-in session to the web dashboard
+	* (`${dashboard}/handoff?__clerk_ticket=<token>`). Server mints only for the
+	* authenticated user — never a caller-supplied id.
+	*/
+	createHandoffToken() {
+		return this.client.request(`${this.prefix}/handoff-token`, { method: "POST" });
+	}
 	applyForStartup(input) {
 		return this.client.request(`${this.prefix}/subscription/apply-startup`, {
 			method: "POST",
@@ -566,10 +575,8 @@ var AuthService = class {
 //#region ../../packages-internal/api-client/dist/services/integrations.js
 var IntegrationsService = class {
 	client;
-	voiceClient;
-	constructor(client, voiceClient) {
+	constructor(client) {
 		this.client = client;
-		this.voiceClient = voiceClient;
 	}
 	listScopedInstalls(scope, scopeId) {
 		const params = new URLSearchParams({
@@ -618,8 +625,11 @@ var IntegrationsService = class {
 		});
 	}
 	listIntegrations(agentId, options) {
-		const qs = options?.includeInherited ? "?includeInherited=true" : "";
-		return this.client.request(`/integrations/agents/${agentId}${qs}`);
+		const params = new URLSearchParams();
+		if (options?.includeInherited) params.set("includeInherited", "true");
+		if (options?.effective) params.set("effective", "true");
+		const qs = params.toString();
+		return this.client.request(`/integrations/agents/${agentId}${qs ? `?${qs}` : ""}`);
 	}
 	installIntegration(agentId, data) {
 		return this.client.request(`/integrations/agents/${agentId}`, {
@@ -651,10 +661,6 @@ var IntegrationsService = class {
 			body: JSON.stringify({ agentId })
 		});
 	}
-	listVoices() {
-		if (this.voiceClient) return this.voiceClient.request("/api/voices");
-		return this.client.request("/integrations/voices");
-	}
 	getDiscordGuildChannels(guildId) {
 		return this.client.request(`/discord/guilds/${encodeURIComponent(guildId)}/channels`);
 	}
@@ -4480,7 +4486,17 @@ enumValues({
 });
 enumValues({
 	OpenClaw: "openclaw",
-	NanoClaw: "nanoclaw"
+	NanoClaw: "nanoclaw",
+	Hermes: "hermes"
+});
+const TTS_MODELS = enumValues({
+	ElevenLabsTurbo: "elevenlabs-turbo",
+	ElevenLabsStandard: "elevenlabs-standard"
+});
+object({
+	voiceId: string().regex(/^[A-Za-z0-9]{8,64}$/).optional(),
+	ttsModel: _enum(TTS_MODELS).optional(),
+	enabled: boolean().optional()
 });
 enumValues({
 	Org: "org",
@@ -4768,10 +4784,12 @@ const NotificationType = {
 	SubscriptionCancelled: "subscription.cancelled",
 	SubscriptionPastDue: "subscription.past_due",
 	BalanceThresholdWarning: "balance.threshold.warning",
+	PlatformTierPriceIncrease: "platform.tier_price_increase",
 	AgentCreated: "agent.created",
 	AgentProvisionFailed: "agent.provision.failed",
 	AgentBillingSuspended: "agent.billing.suspended",
 	AgentDisconnectedExtended: "agent.disconnected.extended",
+	BrowserTakeoverRequested: "browser_takeover_requested",
 	InviteCreated: "onboarding.invite.created",
 	OrgClaimed: "onboarding.org.claimed",
 	TeamMemberAdded: "team.member.added",
@@ -4788,7 +4806,7 @@ const RecipientStrategy = {
 	TenantAdmins: "tenant_admins",
 	SpecificUser: "specific_user"
 };
-NotificationType.PaymentSucceeded, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.PaymentFailed, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationChannel.Sms, NotificationType.TopUpCompleted, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.AutoRechargeCompleted, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationType.AutoRechargeFailed, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationChannel.Sms, NotificationType.SubscriptionCreated, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationType.SubscriptionCancelled, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.SubscriptionPastDue, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationChannel.Sms, NotificationType.BalanceThresholdWarning, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.AgentCreated, NotificationCategory.Agents, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.AgentProvisionFailed, NotificationCategory.Agents, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.AgentBillingSuspended, NotificationCategory.Agents, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.AgentDisconnectedExtended, NotificationCategory.Agents, RecipientStrategy.TenantAdmins, NotificationChannel.Push, NotificationType.InviteCreated, NotificationCategory.System, RecipientStrategy.SpecificUser, NotificationChannel.Email, NotificationType.OrgClaimed, NotificationCategory.System, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.TeamMemberAdded, NotificationCategory.Team, RecipientStrategy.SpecificUser, NotificationChannel.Email, NotificationChannel.Push, NotificationType.ProjectMemberAdded, NotificationCategory.Team, RecipientStrategy.SpecificUser, NotificationChannel.Email, NotificationChannel.Push, NotificationType.IntegrationInstalled, NotificationCategory.Integrations, RecipientStrategy.TenantAdmins, NotificationChannel.Push, NotificationType.IntegrationRemoved, NotificationCategory.Integrations, RecipientStrategy.TenantAdmins, NotificationChannel.Push;
+NotificationType.PaymentSucceeded, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.PaymentFailed, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationChannel.Sms, NotificationType.TopUpCompleted, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.AutoRechargeCompleted, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationType.AutoRechargeFailed, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationChannel.Sms, NotificationType.SubscriptionCreated, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationType.SubscriptionCancelled, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.SubscriptionPastDue, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationChannel.Sms, NotificationType.BalanceThresholdWarning, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.PlatformTierPriceIncrease, NotificationCategory.Billing, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationType.AgentCreated, NotificationCategory.Agents, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.AgentProvisionFailed, NotificationCategory.Agents, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.AgentBillingSuspended, NotificationCategory.Agents, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.AgentDisconnectedExtended, NotificationCategory.Agents, RecipientStrategy.TenantAdmins, NotificationChannel.Push, NotificationType.BrowserTakeoverRequested, NotificationCategory.Agents, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.InviteCreated, NotificationCategory.System, RecipientStrategy.SpecificUser, NotificationChannel.Email, NotificationType.OrgClaimed, NotificationCategory.System, RecipientStrategy.TenantAdmins, NotificationChannel.Email, NotificationChannel.Push, NotificationType.TeamMemberAdded, NotificationCategory.Team, RecipientStrategy.SpecificUser, NotificationChannel.Email, NotificationChannel.Push, NotificationType.ProjectMemberAdded, NotificationCategory.Team, RecipientStrategy.SpecificUser, NotificationChannel.Email, NotificationChannel.Push, NotificationType.IntegrationInstalled, NotificationCategory.Integrations, RecipientStrategy.TenantAdmins, NotificationChannel.Push, NotificationType.IntegrationRemoved, NotificationCategory.Integrations, RecipientStrategy.TenantAdmins, NotificationChannel.Push;
 //#endregion
 //#region src/config.ts
 /**
@@ -4965,17 +4983,33 @@ async function loadManagedConfig() {
 		agentId: identity.agentId,
 		orgId: identity.orgId,
 		runtime: identity.runtime,
-		runtimes: identity.runtime === "openclaw" ? (() => {
-			const home = join(homedir(), ".openclaw");
-			return { openclaw: {
-				workspace: home,
-				agentWorkspace: deriveAgentWorkspace("openclaw", home)
-			} };
-		})() : {},
+		runtimes: buildManagedRuntimes(identity.runtime),
 		autoStartRuntime: true
 	};
 }
 /**
+* Build the managed-mode `runtimes` map for a single resolved runtime.
+* Returns an empty map for unknown runtimes (the daemon then skips runtime
+* start rather than crashing).
+*/
+function buildManagedRuntimes(runtime) {
+	if (runtime === "openclaw") {
+		const home = join(homedir(), ".openclaw");
+		return { openclaw: {
+			workspace: home,
+			agentWorkspace: deriveAgentWorkspace("openclaw", home)
+		} };
+	}
+	if (runtime === "hermes") {
+		const home = join(homedir(), ".hermes");
+		return { hermes: {
+			workspace: home,
+			agentWorkspace: deriveAgentWorkspace("hermes", home)
+		} };
+	}
+	return {};
+}
+/**
 * Load full daemon configuration.
 * Reads config.toml, validates the API key, resolves agent identity,
 * and parses runtime configurations.
@@ -4994,6 +5028,7 @@ async function loadDaemonConfig() {
 	const identity = await resolveAgentIdentity(alfeConfig.api_key, apiEndpoint);
 	const gatewayWsUrl = alfeConfig.gateway_url ?? deriveGatewayWsUrl(apiEndpoint);
 	const runtimes = await loadRuntimeConfigs();
+	const runtime = alfeConfig.runtime ?? identity.runtime;
 	return {
 		apiKey: alfeConfig.api_key,
 		apiEndpoint,
@@ -5002,7 +5037,7 @@ async function loadDaemonConfig() {
 		pidPath: PID_PATH,
 		agentId: identity.agentId,
 		orgId: identity.orgId,
-		runtime: identity.runtime,
+		runtime,
 		runtimes,
 		autoStartRuntime: alfeConfig.auto_start_runtime ?? true
 	};
@@ -5029,6 +5064,7 @@ async function fetchAgentConfig(apiKey, apiEndpoint) {
 		const wsResult = await wsResponse.json();
 		const templateKey = wsResult.data?.templateKey;
 		const defaultModel = wsResult.data?.defaultModel ?? void 0;
+		const installedFrom = wsResult.data?.installedFrom;
 		if (!templateKey) {
 			logger$1.debug("No templateKey in workspace response");
 			return defaultModel ? {
@@ -5036,8 +5072,14 @@ async function fetchAgentConfig(apiKey, apiEndpoint) {
 				files: {}
 			} : null;
 		}
-		logger$1.debug({ templateKey }, "Fetching template files...");
-		const filesResponse = await fetch(`${apiEndpoint}/templates/${encodeURIComponent(templateKey)}/files`, {
+		const pinnedVersion = installedFrom?.templateKey === templateKey ? installedFrom.version : void 0;
+		const filesUrl = new URL(`${apiEndpoint}/templates/${encodeURIComponent(templateKey)}/files`);
+		if (pinnedVersion !== void 0) filesUrl.searchParams.set("version", String(pinnedVersion));
+		logger$1.debug({
+			templateKey,
+			version: pinnedVersion
+		}, "Fetching template files...");
+		const filesResponse = await fetch(filesUrl.toString(), {
 			method: "GET",
 			headers: { "Authorization": `Bearer ${apiKey}` }
 		});
@@ -5049,16 +5091,18 @@ async function fetchAgentConfig(apiKey, apiEndpoint) {
 				files: {}
 			};
 		}
-		const filesResult = await filesResponse.json();
-		const fileCount = Object.keys(filesResult.data?.files ?? {}).length;
+		const files = (await filesResponse.json()).data?.files ?? {};
+		const fileCount = Object.keys(files).length;
 		logger$1.debug({
 			templateKey,
+			version: pinnedVersion,
 			fileCount
 		}, "Template files fetched");
 		return {
 			templateKey,
 			defaultModel,
-			files: filesResult.data?.files ?? {}
+			files,
+			personaFiles: Object.keys(files)
 		};
 	} catch (err) {
 		logger$1.debug({ err: err instanceof Error ? err.message : String(err) }, "fetchAgentConfig failed");
@@ -21617,6 +21661,10 @@ var RuntimeProcess = class {
 					"--allow-unconfigured"
 				]
 			};
+			case "hermes": return {
+				command: "hermes",
+				args: ["gateway", "run"]
+			};
 			default: throw new Error(`Unsupported runtime: ${this.options.runtime}`);
 		}
 	}
@@ -22195,6 +22243,12 @@ let startedAt;
 let integrationManager;
 let mcpBundler = null;
 let mcpManagerRef = null;
+/**
+* Hermes-only MCP store consumer (Approach B). Mirrors the runtime-agnostic MCP
+* store into ~/.hermes/config.yaml. Null for openclaw agents (never constructed)
+* and for managed/self-hosted runtimes other than hermes.
+*/
+let hermesMcpSync = null;
 let aiProxyServer = null;
 let runtimeProcess = null;
 let aiProxyUrl = null;
@@ -22207,6 +22261,12 @@ let resolvedRuntimeVersion;
 let upgradingRuntime = false;
 let stopPairingApprovalPoller = null;
 /**
+* Module-level handle on the runtime appliers built during start(), so the
+* module-scoped command handler can route `alfe.config_set` to the active
+* runtime's applier (mirrors `mcpManagerRef`). Null until start() builds it.
+*/
+let runtimeAppliersRef = null;
+/**
 * Resolve the installed @alfe.ai/cli version.
 *
 * Strategy (in order):
@@ -22281,15 +22341,44 @@ async function getCliVersion() {
 	logger$1.debug("Could not resolve @alfe.ai/cli version");
 }
 /**
-* Resolve the installed runtime (OpenClaw) version.
-* Runs `openclaw --version` and returns the trimmed output.
+* Per-runtime "print installed version" commands. Local to the gateway — we do
+* NOT import the CLI's `detectRuntime` (`@alfe.ai/gateway` must not depend on
+* `@alfe.ai/cli`). Unknown runtimes resolve to `undefined` (never throw) so the
+* connection-status report degrades gracefully instead of crashing.
+*/
+const RUNTIME_VERSION_COMMANDS = {
+	openclaw: {
+		command: "openclaw",
+		args: ["--version"]
+	},
+	hermes: {
+		command: "hermes",
+		args: ["version"]
+	}
+};
+/**
+* Pure resolver (exported for tests) — the per-runtime version command, or
+* `undefined` for an unknown runtime.
+*/
+function resolveRuntimeVersionCommand(runtime) {
+	return RUNTIME_VERSION_COMMANDS[runtime];
+}
+/**
+* Resolve the installed runtime version by running the per-runtime version
+* command and returning the trimmed stdout. An unknown runtime (no command in
+* the map) returns `undefined` without spawning — it must never throw.
 */
-async function getRuntimeVersion() {
+async function getRuntimeVersion(runtime) {
+	const cmd = resolveRuntimeVersionCommand(runtime);
+	if (!cmd) {
+		logger$1.debug({ runtime }, "No version command for runtime — skipping version detection");
+		return;
+	}
 	try {
-		const { stdout } = await execFileAsync("openclaw", ["--version"]);
+		const { stdout } = await execFileAsync(cmd.command, cmd.args);
 		return stdout.trim() || void 0;
 	} catch {
-		logger$1.debug("Could not resolve openclaw runtime version");
+		logger$1.debug({ runtime }, "Could not resolve runtime version");
 		return;
 	}
 }
@@ -22437,7 +22526,7 @@ async function startDaemon() {
 		await flushAndExit(1);
 	}
 	resolvedCliVersion = await getCliVersion();
-	resolvedRuntimeVersion = await getRuntimeVersion();
+	resolvedRuntimeVersion = await getRuntimeVersion(config.runtime);
 	logger$1.info({
 		cliVersion: resolvedCliVersion,
 		runtimeVersion: resolvedRuntimeVersion
@@ -22470,7 +22559,14 @@ async function startDaemon() {
 			home: runtimeCfg.workspace,
 			agentWorkspace: runtimeCfg.agentWorkspace
 		}, "Registered OpenClaw runtime applier");
+	} else if (name === "hermes") {
+		runtimeAppliers.set(name, new HermesApplier({ home: runtimeCfg.workspace }));
+		logger$1.info({
+			runtime: name,
+			home: runtimeCfg.workspace
+		}, "Registered Hermes runtime applier");
 	} else logger$1.warn({ runtime: name }, "Unknown runtime type — skipping");
+	runtimeAppliersRef = runtimeAppliers;
 	const integrationsService = new IntegrationsService(new AlfeApiClient({
 		apiBaseUrl: config.apiEndpoint,
 		getToken: () => Promise.resolve(config.apiKey)
@@ -22485,22 +22581,25 @@ async function startDaemon() {
 		logger: logger$1,
 		idleTtlMs: 0
 	}, { connect: defaultConnect });
-	await mcpManager.loadIntoBundler(mcpBundler);
-	const warmBundler = (reason) => {
-		if (!mcpBundler) return;
-		mcpBundler.warmup().catch((err) => {
-			logger$1.warn({
-				err: err instanceof Error ? err.message : String(err),
-				reason
-			}, "MCP bundler warmup failed");
+	if (config.runtime === "hermes") logger$1.info("Hermes runtime — daemon MCP bundler left idle (store mirrored to config.yaml by HermesMcpSync)");
+	else {
+		await mcpManager.loadIntoBundler(mcpBundler);
+		const warmBundler = (reason) => {
+			if (!mcpBundler) return;
+			mcpBundler.warmup().catch((err) => {
+				logger$1.warn({
+					err: err instanceof Error ? err.message : String(err),
+					reason
+				}, "MCP bundler warmup failed");
+			});
+		};
+		warmBundler("startup");
+		mcpManager.onChange(() => {
+			warmBundler("store change");
 		});
-	};
-	warmBundler("startup");
-	mcpManager.onChange(() => {
-		warmBundler("store change");
-	});
-	logger$1.info("MCP bundler attached to manager — warming children");
-	await runOpenclawMcpCleanup({
+		logger$1.info("MCP bundler attached to manager — warming children");
+	}
+	if (config.runtime === "openclaw") await runOpenclawMcpCleanup({
 		manager: mcpManager,
 		logger: logger$1
 	}).catch((err) => {
@@ -22521,14 +22620,27 @@ async function startDaemon() {
 	});
 	const integrationAdapter = new IntegrationManagerAdapter(integrationManager);
 	cloudClient.setIntegrationManager(integrationAdapter);
-	cloudClient.setRuntimeRestartNeededHandler(() => {
+	const requestRuntimeRestart = () => {
 		if (runtimeProcess) {
 			logger$1.info("Runtime state changed — restarting runtime");
 			runtimeProcess.restart().catch((err) => {
 				logger$1.error({ err: err instanceof Error ? err.message : String(err) }, "Failed to restart runtime");
 			});
 		}
-	});
+	};
+	cloudClient.setRuntimeRestartNeededHandler(requestRuntimeRestart);
+	if (config.runtime === "hermes") {
+		const hermesCfg = config.runtimes[config.runtime];
+		if (hermesCfg) {
+			hermesMcpSync = new HermesMcpSync({
+				manager: mcpManager,
+				home: hermesCfg.workspace,
+				apiKey: config.apiKey,
+				requestRestart: requestRuntimeRestart
+			});
+			hermesMcpSync.start();
+		}
+	}
 	cloudClient.setOnReconciliationComplete(() => {
 		try {
 			const activeCommands = integrationManager.getActiveCommands();
@@ -22583,6 +22695,10 @@ async function startDaemon() {
 			await runtimeProcess.stop();
 			logger$1.debug("Runtime process stopped");
 		}
+		if (hermesMcpSync) {
+			hermesMcpSync.stop();
+			hermesMcpSync = null;
+		}
 		if (mcpBundler) {
 			logger$1.debug("Stopping MCP bundler...");
 			await mcpBundler.dispose();
@@ -22671,17 +22787,28 @@ async function handleCloudCommand(command) {
 				message: "Runtime upgrade already in progress"
 			}
 		};
-		const version = command.payload?.version ?? "2026.6.8";
+		const payload = command.payload;
+		const runtime = config.runtime;
+		const version = payload?.version ?? (runtime === "openclaw" ? "2026.6.8" : void 0);
 		upgradingRuntime = true;
 		setTimeout(() => {
 			(async () => {
 				try {
 					const { upgradeRuntime } = await import("./runtime-upgrade.js");
-					if ((await upgradeRuntime(version, runtimeProcess)).success) {
-						resolvedRuntimeVersion = await getRuntimeVersion();
-						if (!resolvedRuntimeVersion) logger$1.warn({ requestedVersion: version }, "Could not detect runtime version after upgrade — using requested version");
-						logger$1.info({ runtimeVersion: resolvedRuntimeVersion ?? version }, "Runtime version updated after upgrade");
-						cloudClient.updateRuntimeVersionAndReRegister(resolvedRuntimeVersion ?? version);
+					if ((await upgradeRuntime(runtime, version, runtimeProcess)).success) {
+						resolvedRuntimeVersion = await getRuntimeVersion(runtime);
+						const reportedVersion = resolvedRuntimeVersion ?? version;
+						if (!resolvedRuntimeVersion) logger$1.warn({
+							runtime,
+							requestedVersion: version
+						}, "Could not detect runtime version after upgrade");
+						if (reportedVersion) {
+							logger$1.info({
+								runtime,
+								runtimeVersion: reportedVersion
+							}, "Runtime version updated after upgrade");
+							cloudClient.updateRuntimeVersionAndReRegister(reportedVersion);
+						} else logger$1.warn({ runtime }, "No runtime version to report after upgrade — skipping re-register");
 					}
 				} catch (err) {
 					logger$1.error({ err: err instanceof Error ? err.message : String(err) }, "Runtime upgrade failed");
@@ -22696,6 +22823,7 @@ async function handleCloudCommand(command) {
 			status: "ok",
 			result: {
 				upgrading: true,
+				runtime,
 				version
 			}
 		};
@@ -22776,17 +22904,30 @@ async function handleCloudCommand(command) {
 				message: "alfe.config_set requires key and value"
 			}
 		};
+		const runtime = config.runtime;
+		const applier = runtimeAppliersRef?.get(runtime);
+		if (!applier || typeof applier.setConfigRaw !== "function") {
+			const message = `No runtime applier supports config_set for runtime "${runtime}"`;
+			logger$1.warn({
+				runtime,
+				key
+			}, message);
+			return {
+				type: "COMMAND_ACK",
+				commandId: command.commandId,
+				status: "error",
+				result: {
+					code: "CONFIG_SET_UNSUPPORTED",
+					message
+				}
+			};
+		}
 		try {
-			await execFileAsync("openclaw", [
-				"config",
-				"set",
-				key,
-				value
-			], { timeout: 1e4 });
+			await applier.setConfigRaw(key, value);
 			logger$1.info({
-				key,
-				value
-			}, "Applied config via openclaw config set");
+				runtime,
+				key
+			}, "Applied config via runtime applier setConfigRaw");
 			return {
 				type: "COMMAND_ACK",
 				commandId: command.commandId,
@@ -22800,9 +22941,9 @@ async function handleCloudCommand(command) {
 			const message = err instanceof Error ? err.message : String(err);
 			logger$1.error({
 				err: message,
-				key,
-				value
-			}, "Failed to apply config via openclaw");
+				runtime,
+				key
+			}, "Failed to apply config via runtime applier");
 			return {
 				type: "COMMAND_ACK",
 				commandId: command.commandId,

package/dist/runtime-upgrade.js

@@ -3,40 +3,87 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 //#region src/runtime-upgrade.ts
 /**
-* Runtime upgrade — npm install then cycle the RuntimeProcess.
+* Runtime upgrade — install/update the runtime binary then cycle the RuntimeProcess.
 *
 * Unlike CLI upgrade (which exits the daemon for systemd restart),
 * runtime upgrade keeps the daemon running and just restarts the child process.
 *
-* Flow:
+* Flow (generic across runtimes):
 *   1. Stop the RuntimeProcess child (SIGTERM + grace period)
-*   2. npm install -g openclaw@{version}
+*   2. Run the per-runtime upgrade command (see `resolveUpgradeCommand`)
 *   3. Restart the RuntimeProcess child
 *
-* On npm failure, the runtime is restarted on the old version.
+* On install failure, the runtime is restarted on the old version.
 */
 const execFileAsync = promisify(execFile);
-async function upgradeRuntime(version, runtimeProcess) {
-	logger.info({ version }, "Upgrading OpenClaw runtime...");
+/**
+* Resolve the per-runtime upgrade command.
+*
+* - `openclaw`: `npm install -g openclaw@<version>` — version-pinned (unchanged).
+* - `hermes`:   `hermes update --yes` — Hermes self-updates from its own channel.
+*               A pinned version does not map to a Hermes CLI flag, so the
+*               `version` arg is intentionally ignored on this branch.
+*
+* Returns `undefined` for an unknown runtime (or openclaw with no version),
+* which the caller treats as a failed upgrade (restart on the old version).
+*/
+function resolveUpgradeCommand(runtime, version) {
+	switch (runtime) {
+		case "openclaw":
+			if (!version) return void 0;
+			return {
+				command: "npm",
+				args: [
+					"install",
+					"-g",
+					`openclaw@${version}`
+				]
+			};
+		case "hermes": return {
+			command: "hermes",
+			args: ["update", "--yes"]
+		};
+		default: return;
+	}
+}
+async function upgradeRuntime(runtime, version, runtimeProcess) {
+	const cmd = resolveUpgradeCommand(runtime, version);
+	if (!cmd) {
+		const message = `No upgrade command for runtime '${runtime}'`;
+		logger.error({
+			runtime,
+			version
+		}, message);
+		return {
+			success: false,
+			runtime,
+			version,
+			error: message
+		};
+	}
+	logger.info({
+		runtime,
+		version
+	}, "Upgrading runtime...");
 	if (runtimeProcess) {
 		logger.info("Stopping runtime for upgrade...");
 		await runtimeProcess.stop();
 	}
 	try {
-		const { stdout, stderr } = await execFileAsync("npm", [
-			"install",
-			"-g",
-			`openclaw@${version}`
-		], { timeout: 12e4 });
-		if (stdout) logger.debug({ stdout: stdout.trim() }, "npm install stdout");
-		if (stderr) logger.debug({ stderr: stderr.trim() }, "npm install stderr");
-		logger.info({ version }, "OpenClaw runtime upgraded successfully");
+		const { stdout, stderr } = await execFileAsync(cmd.command, cmd.args, { timeout: 12e4 });
+		if (stdout) logger.debug({ stdout: stdout.trim() }, "runtime upgrade stdout");
+		if (stderr) logger.debug({ stderr: stderr.trim() }, "runtime upgrade stderr");
+		logger.info({
+			runtime,
+			version
+		}, "Runtime upgraded successfully");
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		logger.error({
 			err: message,
+			runtime,
 			version
-		}, "Runtime upgrade npm install failed");
+		}, "Runtime upgrade install command failed");
 		if (runtimeProcess) try {
 			logger.info("Restarting runtime on previous version after failed upgrade...");
 			await runtimeProcess.restart();
@@ -46,6 +93,7 @@ async function upgradeRuntime(version, runtimeProcess) {
 		}
 		return {
 			success: false,
+			runtime,
 			version,
 			error: message
 		};
@@ -56,6 +104,7 @@ async function upgradeRuntime(version, runtimeProcess) {
 	}
 	return {
 		success: true,
+		runtime,
 		version
 	};
 }

package/dist/src/index.d.ts

@@ -60,6 +60,18 @@ interface AgentWorkspaceConfig {
   templateKey?: string;
   defaultModel?: string;
   files: Record<string, string>;
+  /**
+   * Filenames within `files` that are agent-owned persona files (SOUL.md,
+   * IDENTITY.md, AGENTS.md, USER.md, BOOTSTRAP.md, …). The consumer
+   * (`writeWorkspaceFiles`) seeds these ONLY IF ABSENT so an agent's own edits
+   * — restored by the openclaw-sync backup on a fresh VM — are never clobbered
+   * by a setup-time re-seed. Filenames NOT in this set keep overwrite-on-write
+   * semantics. The templates `/files` endpoint returns persona files
+   * exclusively today, so `fetchAgentConfig` populates this with every key; the
+   * field is threaded explicitly rather than assumed so a future workspace-file
+   * source can mix persona (seed-if-missing) and non-persona (overwrite) files.
+   */
+  personaFiles?: string[];
 }
 declare const ALFE_DIR: string;
 declare const SOCKET_PATH: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/gateway",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Alfe local gateway daemon — persistent control plane for agent integrations",
   "type": "module",
   "bin": {
@@ -22,14 +22,22 @@
     "pino-roll": "^1.2.0",
     "smol-toml": ">=1.6.1",
     "ws": "^8.18.0",
-    "@alfe.ai/agent-api-client": "^0.2.3",
-    "@alfe.ai/ai-proxy-local": "^0.0.10",
-    "@alfe.ai/config": "^0.0.9",
-    "@alfe.ai/integration-manifest": "^0.2.1",
-    "@alfe.ai/integrations": "^0.1.6",
-    "@alfe.ai/mcp-bundler": "^0.2.1"
+    "@alfe.ai/agent-api-client": "^0.4.0",
+    "@alfe.ai/ai-proxy-local": "^0.0.12",
+    "@alfe.ai/config": "^0.2.0",
+    "@alfe.ai/integration-manifest": "^0.3.1",
+    "@alfe.ai/integrations": "^0.2.4",
+    "@alfe.ai/mcp-bundler": "^0.2.2"
   },
   "license": "UNLICENSED",
+  "homepage": "https://alfe.ai",
+  "author": "Alfe (https://alfe.ai)",
+  "keywords": [
+    "alfe",
+    "ai-agents",
+    "agent",
+    "llm"
+  ],
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",