@alfe.ai/gateway 0.2.1 → 0.2.3

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 { HermesApplier, HermesMcpSync, IntegrationManager, IntegrationManagerAdapter, McpApplier, OpenClawApplier } from "@alfe.ai/integrations";
+import { HermesApplier, HermesMcpSync, IntegrationManager, IntegrationManagerAdapter, McpApplier, NoopOpenClawCliLock, OpenClawApplier, SerialOpenClawCliLock } 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";
@@ -5257,6 +5257,79 @@ function isIPCResponse(msg) {
 /** Current IPC protocol version */
 const PROTOCOL_VERSION = 1;
 //#endregion
+//#region src/runtime-gate.ts
+const log$3 = logger$1.child({ component: "RuntimeGate" });
+var RuntimeGate = class {
+	depth = 0;
+	wasRunning = false;
+	constructor(getRuntime) {
+		this.getRuntime = getRuntime;
+	}
+	/**
+	* Suspend the runtime child. Only the outermost call (depth 0 → 1) actually
+	* stops it; nested calls just bump the refcount. Remembers whether the child
+	* was running so `resume()` doesn't spuriously start a runtime that was never
+	* up (e.g. autoStartRuntime=false).
+	*/
+	async suspend() {
+		if (this.depth++ > 0) return;
+		const rp = this.getRuntime();
+		this.wasRunning = rp?.isRunning ?? false;
+		if (rp && this.wasRunning) {
+			log$3.info("Suspending runtime for mutating reconcile (avoid concurrent SQLite writers)");
+			await rp.stop();
+		}
+	}
+	/**
+	* Resume the runtime child. Only the outermost call (depth 1 → 0) actually
+	* restarts it, and only if it was running when we suspended. This subsumes
+	* the old post-reconcile "restart if plugins changed" step — bringing the
+	* runtime back is exactly what a restart-after-reconcile did.
+	*/
+	resume() {
+		if (--this.depth > 0) return Promise.resolve();
+		if (this.depth < 0) this.depth = 0;
+		const rp = this.getRuntime();
+		if (rp && this.wasRunning) {
+			log$3.info("Resuming runtime after mutating reconcile");
+			rp.resume();
+		}
+		this.wasRunning = false;
+		return Promise.resolve();
+	}
+	/**
+	* Out-of-band restart request (e.g. `alfe.config_set`, Hermes MCP sync).
+	* Deferred while a suspend is active — the pending `resume()` will bring the
+	* runtime back with fresh config, so restarting mid-suspend would just fight
+	* the gate (and risk spawning the runtime while a CLI mutation is still
+	* writing the DB).
+	*/
+	requestRestart() {
+		if (this.depth > 0) {
+			log$3.info("Runtime restart requested while suspended — deferring to pending resume");
+			return;
+		}
+		const rp = this.getRuntime();
+		if (rp) rp.restart().catch((err) => {
+			log$3.error({ err: err instanceof Error ? err.message : String(err) }, "Failed to restart runtime");
+		});
+	}
+};
+/**
+* A gate that never touches the runtime — for runtimes that don't share the
+* single-writer SQLite hazard, or for tests. `suspend`/`resume` are no-ops and
+* `requestRestart` does nothing.
+*/
+var NoopRuntimeGate = class {
+	suspend() {
+		return Promise.resolve();
+	}
+	resume() {
+		return Promise.resolve();
+	}
+	requestRestart() {}
+};
+//#endregion
 //#region src/reconciliation.ts
 const log$2 = logger$1.child({ component: "Reconciliation" });
 /**
@@ -5271,13 +5344,50 @@ const MAX_ERROR_ACTIVATE_ATTEMPTS = 3;
 var ReconciliationEngine = class {
 	/** Consecutive re-activation attempts for an intact error-state integration, keyed by id. */
 	activateAttempts = /* @__PURE__ */ new Map();
-	constructor(manager) {
+	/**
+	* Whether this reconcile pass has already suspended the runtime. Reset at the
+	* start of every {@link reconcile} call. The runtime is suspended lazily on
+	* the first mutating branch (install / reinstall / activate / removal-of-
+	* existing) so an all-`up_to_date` pass never touches the runtime.
+	*/
+	suspended = false;
+	/**
+	* @param manager The integration manager to converge.
+	* @param gate    Runtime gate used to suspend the runtime child around
+	*                mutating branches so `openclaw` CLI subprocesses don't write
+	*                `~/.openclaw/state/openclaw.sqlite` concurrently with a live
+	*                `openclaw gateway run` (see runtime-gate.ts). Defaults to a
+	*                no-op gate for runtimes/tests that don't need protection.
+	*/
+	constructor(manager, gate = new NoopRuntimeGate()) {
 		this.manager = manager;
+		this.gate = gate;
+	}
+	/**
+	* Suspend the runtime on the first mutating branch of a reconcile pass.
+	* Idempotent within a pass — subsequent mutating branches are covered by the
+	* single suspend held until the `finally` in {@link reconcile}.
+	*/
+	async ensureSuspended() {
+		if (!this.suspended) {
+			this.suspended = true;
+			await this.gate.suspend();
+		}
+	}
+	/**
+	* Resume the runtime if this pass suspended it. Called from `reconcile()`'s
+	* `finally`. Kept as a method (rather than an inline `if (this.suspended)`)
+	* so the mutation performed by {@link ensureSuspended} in a different method
+	* isn't narrowed away by control-flow analysis at the callsite.
+	*/
+	async resumeIfSuspended() {
+		if (this.suspended) await this.gate.resume();
 	}
 	/**
 	* Reconcile local state against desired state from cloud.
 	*/
 	async reconcile(desiredIntegrations) {
+		this.suspended = false;
 		const report = {
 			results: [],
 			installed: [],
@@ -5296,15 +5406,20 @@ var ReconciliationEngine = class {
 		}
 		const localMap = new Map(localIntegrations.map((i) => [i.id, i]));
 		const desiredMap = new Map(desiredIntegrations.map((d) => [d.integrationId, d]));
-		for (const desired of desiredIntegrations) if (desired.desiredStatus === "active") await this.reconcileActive(desired, localMap.get(desired.integrationId), report);
-		else await this.reconcileRemoved(desired.integrationId, localMap.get(desired.integrationId), report);
-		for (const local of localIntegrations) if (!desiredMap.has(local.id)) await this.reconcileRemoved(local.id, local, report);
+		try {
+			for (const desired of desiredIntegrations) if (desired.desiredStatus === "active") await this.reconcileActive(desired, localMap.get(desired.integrationId), report);
+			else await this.reconcileRemoved(desired.integrationId, localMap.get(desired.integrationId), report);
+			for (const local of localIntegrations) if (!desiredMap.has(local.id)) await this.reconcileRemoved(local.id, local, report);
+		} finally {
+			await this.resumeIfSuspended();
+		}
 		return report;
 	}
 	async reconcileActive(desired, local, report) {
 		const id = desired.integrationId;
 		try {
 			if (!local) {
+				await this.ensureSuspended();
 				log$2.info(`Installing ${id}@${desired.version}`);
 				await this.manager.install(id, desired.version, desired.config, desired.customSource);
 				report.installed.push(id);
@@ -5319,6 +5434,7 @@ var ReconciliationEngine = class {
 				return;
 			}
 			if (local.version !== desired.version && desired.version !== "" && local.version !== "unknown") {
+				await this.ensureSuspended();
 				log$2.info(`Upgrading ${id}: ${local.version} → ${desired.version}`);
 				if ((await this.manager.reinstall(id, desired.version, desired.config, desired.customSource)).configApplied) report.configApplied = true;
 				report.installed.push(id);
@@ -5332,6 +5448,7 @@ var ReconciliationEngine = class {
 			}
 			if (local.status === "error") {
 				if (desired.reinstallRequestedAt && local.installedAt && desired.reinstallRequestedAt > local.installedAt) {
+					await this.ensureSuspended();
 					log$2.info(`Reinstalling ${id} from error state (requested: ${desired.reinstallRequestedAt}, installed: ${local.installedAt})`);
 					this.manager.resetReinstallAttempts(id);
 					this.activateAttempts.delete(id);
@@ -5361,6 +5478,7 @@ var ReconciliationEngine = class {
 						});
 						return;
 					}
+					await this.ensureSuspended();
 					log$2.info(`Auto-reinstalling ${id} — install directory is corrupted or missing (attempt ${String(attempts + 1)}/3)`);
 					this.manager.incrementReinstallAttempts(id);
 					try {
@@ -5393,6 +5511,7 @@ var ReconciliationEngine = class {
 				const activateAttempts = this.activateAttempts.get(id) ?? 0;
 				if (activateAttempts < MAX_ERROR_ACTIVATE_ATTEMPTS) {
 					this.activateAttempts.set(id, activateAttempts + 1);
+					await this.ensureSuspended();
 					log$2.info(`Re-activating ${id} from error state (attempt ${String(activateAttempts + 1)}/${String(MAX_ERROR_ACTIVATE_ATTEMPTS)})`);
 					try {
 						if ((await this.manager.activate(id)).configApplied) report.configApplied = true;
@@ -5434,6 +5553,7 @@ var ReconciliationEngine = class {
 				return;
 			}
 			if (local.status !== "active") {
+				await this.ensureSuspended();
 				log$2.info(`Activating ${id}`);
 				if ((await this.manager.activate(id)).configApplied) report.configApplied = true;
 				report.activated.push(id);
@@ -5445,6 +5565,7 @@ var ReconciliationEngine = class {
 				return;
 			}
 			if (desired.reinstallRequestedAt && local.installedAt && desired.reinstallRequestedAt > local.installedAt) {
+				await this.ensureSuspended();
 				log$2.info(`Reinstall requested for ${id} (requested: ${desired.reinstallRequestedAt}, installed: ${local.installedAt})`);
 				this.manager.resetReinstallAttempts(id);
 				this.activateAttempts.delete(id);
@@ -5489,6 +5610,7 @@ var ReconciliationEngine = class {
 			return;
 		}
 		try {
+			await this.ensureSuspended();
 			log$2.info(`Removing ${id}`);
 			if (local.status === "active") {
 				await this.manager.deactivate(id);
@@ -5576,8 +5698,16 @@ var CloudClient = class {
 	setOnReconciliationComplete(handler) {
 		this.onReconciliationComplete = handler;
 	}
-	setIntegrationManager(manager) {
-		this.reconciliationEngine = new ReconciliationEngine(manager);
+	/**
+	* Set the integration manager (and optionally the runtime gate) for
+	* reconciliation. When set, the cloud client handles DESIRED_STATE messages
+	* automatically. The gate is passed to the ReconciliationEngine so mutating
+	* reconcile branches suspend the runtime child around runtime-CLI mutations
+	* (avoids concurrent SQLite writers — see runtime-gate.ts). Resuming the
+	* runtime after a mutating pass subsumes the old post-reconcile restart.
+	*/
+	setIntegrationManager(manager, gate) {
+		this.reconciliationEngine = new ReconciliationEngine(manager, gate);
 	}
 	/**
 	* Start the cloud connection with auto-reconnect.
@@ -5813,7 +5943,6 @@ var CloudClient = class {
 		}, "Cloud: reconciliation complete");
 		const reportMsg = createReconciliationReport(report.results);
 		this.send(reportMsg);
-		if ((report.installed.length > 0 || report.uninstalled.length > 0 || report.configApplied) && this.onRuntimeRestartNeeded) this.onRuntimeRestartNeeded();
 		this.onReconciliationComplete?.();
 	}
 	send(msg) {
@@ -21772,6 +21901,17 @@ var RuntimeProcess = class {
 		});
 	}
 	/**
+	* Resume after a suspend (stop). `start()` alone is a no-op while stopped
+	* because `stop()` latches `this.stopped = true`; resume clears that latch,
+	* resets the crash backoff, and re-spawns. Used by the RuntimeGate to bring
+	* the runtime back after a mutating reconcile branch has finished.
+	*/
+	resume() {
+		this.stopped = false;
+		this.backoffMs = BACKOFF_INITIAL_MS;
+		this.start();
+	}
+	/**
 	* Restart the runtime process (stop then start with fresh backoff).
 	*/
 	async restart() {
@@ -22054,13 +22194,15 @@ async function approvePendingScopeUpgrades(opts) {
 function startPairingApprovalPoller(opts) {
 	const stateDir = resolveStateDir(opts.stateDir);
 	const intervalMs = opts.intervalMs ?? 3e4;
-	const exec = opts.exec ?? (async (file, args, { timeout }) => {
+	const cliLock = opts.cliLock ?? new NoopOpenClawCliLock();
+	const rawExec = opts.exec ?? (async (file, args, { timeout }) => {
 		const { stdout, stderr } = await execFileAsync$2(file, args, { timeout });
 		return {
 			stdout,
 			stderr
 		};
 	});
+	const exec = (file, args, execOpts) => cliLock.run(() => rawExec(file, args, execOpts));
 	const pendingPath = join(stateDir, "devices", "pending.json");
 	let lastSeenMtime = null;
 	let stopped = false;
@@ -22165,6 +22307,7 @@ const defaultOpenclaw = {
 async function runOpenclawMcpCleanup(opts) {
 	const sentinelPath = opts.sentinelPath ?? DEFAULT_SENTINEL_PATH;
 	const openclaw = opts.openclaw ?? defaultOpenclaw;
+	const cliLock = opts.cliLock ?? new NoopOpenClawCliLock();
 	if (existsSync(sentinelPath)) {
 		opts.logger.debug({ sentinel: sentinelPath }, "openclaw.json mcp.servers cleanup already ran — skipping");
 		return;
@@ -22195,7 +22338,7 @@ async function runOpenclawMcpCleanup(opts) {
 			return;
 		}
 		for (const key of toUnset) try {
-			await openclaw.unsetServer(key);
+			await cliLock.run(() => openclaw.unsetServer(key));
 			opts.logger.info({ key }, "Cleaned up stale openclaw.json#mcp.servers entry");
 		} catch (err) {
 			opts.logger.warn({
@@ -22548,11 +22691,13 @@ async function startDaemon() {
 		logger$1.info({ connected }, "Cloud connection state changed");
 		ipcServer?.broadcastEvent("cloud.status", { connected });
 	});
+	const openclawCliLock = new SerialOpenClawCliLock();
 	const runtimeAppliers = /* @__PURE__ */ new Map();
 	for (const [name, runtimeCfg] of Object.entries(config.runtimes)) if (name === "openclaw") {
 		runtimeAppliers.set(name, new OpenClawApplier({
 			home: runtimeCfg.workspace,
-			agentWorkspace: runtimeCfg.agentWorkspace
+			agentWorkspace: runtimeCfg.agentWorkspace,
+			cliLock: openclawCliLock
 		}));
 		logger$1.info({
 			runtime: name,
@@ -22601,7 +22746,8 @@ async function startDaemon() {
 	}
 	if (config.runtime === "openclaw") await runOpenclawMcpCleanup({
 		manager: mcpManager,
-		logger: logger$1
+		logger: logger$1,
+		cliLock: openclawCliLock
 	}).catch((err) => {
 		logger$1.warn({ err: err instanceof Error ? err.message : String(err) }, "openclaw.json mcp.servers cleanup threw — startup continues");
 	});
@@ -22619,14 +22765,11 @@ async function startDaemon() {
 		}
 	});
 	const integrationAdapter = new IntegrationManagerAdapter(integrationManager);
-	cloudClient.setIntegrationManager(integrationAdapter);
+	const runtimeGate = new RuntimeGate(() => runtimeProcess);
+	cloudClient.setIntegrationManager(integrationAdapter, runtimeGate);
 	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");
-			});
-		}
+		logger$1.info("Runtime state changed — requesting runtime restart");
+		runtimeGate.requestRestart();
 	};
 	cloudClient.setRuntimeRestartNeededHandler(requestRuntimeRestart);
 	if (config.runtime === "hermes") {
@@ -22676,7 +22819,10 @@ async function startDaemon() {
 			runtimeProcess.start();
 			logger$1.debug("Runtime process started");
 			if (config.runtime === "openclaw") {
-				stopPairingApprovalPoller = startPairingApprovalPoller({ log: logger$1 });
+				stopPairingApprovalPoller = startPairingApprovalPoller({
+					log: logger$1,
+					cliLock: openclawCliLock
+				});
 				logger$1.debug("Pairing approval poller started");
 			}
 		} else logger$1.warn({ runtime: config.runtime }, "No runtime config found — skipping runtime start");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/gateway",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Alfe local gateway daemon — persistent control plane for agent integrations",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
     "@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/integrations": "^0.2.6",
     "@alfe.ai/mcp-bundler": "^0.2.2"
   },
   "license": "UNLICENSED",