@alfe.ai/integrations 0.2.6 → 0.2.8

package/dist/index.d.ts

@@ -870,6 +870,11 @@ declare class OpenClawApplier implements RuntimeApplier {
    * acquires it ONCE at the top and calls only `*Unlocked` helpers inside.
    */
   private cliLock;
+  /**
+   * Monotonic-ish guard for the state-DB self-heal — timestamp of the last heal
+   * this instance performed (0 = never). See HEAL_MIN_INTERVAL_MS.
+   */
+  private lastHealAt;
   constructor(options: OpenClawApplierOptions);
   /**
    * Convenience: `openclaw config set <args>`, UNLOCKED + retried.
@@ -913,6 +918,46 @@ declare class OpenClawApplier implements RuntimeApplier {
    * on the first success, false once all attempts are exhausted.
    */
   private verifyApplied;
+  /**
+   * `openclaw <args>` with automatic malformed-state-DB self-heal. On a
+   * malformed-DB failure (see isMalformedStateDbError): quarantine + recreate the
+   * state DB (healMalformedStateDb), then retry the ORIGINAL command exactly
+   * once. If the heal is rate-limited/failed, or the single retry also fails, the
+   * error propagates unchanged — callers keep their existing failure semantics
+   * (retry loops, install-tolerance checks, log.warn) as if healing never ran.
+   *
+   * Assumes the shared CLI lock is already held by the calling public method: the
+   * heal runs INSIDE the same locked section as the failed command. NEVER
+   * re-acquires the non-re-entrant `cliLock`.
+   *
+   * Runtime-alive safety: reconcile-path callers run under the gateway's
+   * RuntimeGate (runtime stopped), but the `setConfigRaw` hook (daemon
+   * `alfe.config_set`) can heal while `openclaw gateway run` still holds the DB.
+   * That is safe by fd/inode decoupling, not by exclusivity: renameSync is
+   * inode-level, the live runtime keeps writing its orphaned inode (discarded on
+   * its next restart — the state DB is disposable), and the recreated DB gets
+   * fresh -wal/-shm files the old process never attaches to.
+   */
+  private execOpenClawHealing;
+  /**
+   * Quarantine the corrupt OpenClaw state DB and recreate it. Never throws
+   * (logs + returns whether the heal succeeded). Rate-limited to one attempt per
+   * HEAL_MIN_INTERVAL_MS so a heal→re-corrupt→heal loop can't thrash the box.
+   *
+   * Steps (human-verified against a live managed agent): rename
+   * `state/openclaw.sqlite{,-wal,-shm}` aside with a `.quarantined-<ISO>` suffix
+   * (keep for forensics; -wal/-shm may be absent), then run `openclaw plugins
+   * list` to rebuild the DB via OpenClaw's migration framework (slow on a 2-vCPU
+   * box — 90s budget). Assumes the caller holds `cliLock` (see
+   * execOpenClawHealing for the runtime-alive rename semantics).
+   *
+   * A SUCCESSFUL heal consumes the full rate-limit window (a fresh DB exists for
+   * the runtime to re-corrupt — that loop is what the window prevents). A FAILED
+   * heal only gets the short cooldown: no fresh DB was produced, and a full
+   * window would strand the box with the main DB quarantined and no recreate for
+   * 10 minutes.
+   */
+  private healMalformedStateDb;
   applyPlugin(spec: string, _installPath?: string, opts?: {
     force?: boolean;
   }): Promise<void>;
@@ -951,6 +996,16 @@ declare class OpenClawApplier implements RuntimeApplier {
    * plugins under 2026.5+, which made force-mode skip its uninstall step.
    */
   private isPluginInstalled;
+  /**
+   * Best-effort read of the installed version of a plugin, or `undefined` when
+   * it can't be determined. Reads the version from the installed package's
+   * package.json under the npm registry path OpenClaw 2026.5+ installs to
+   * (`~/.openclaw/npm/node_modules/<pkg>/package.json`) — the same root
+   * `isPluginInstalled` checks. 2026.4 extensions-dir installs have no
+   * stable package.json version here and return `undefined` (callers fail
+   * open to the safe reinstall path).
+   */
+  private installedPluginVersion;
   /**
    * Remove an extensions/ install that has no matching record in
    * plugins/installs.json. OpenClaw 2026.5+ tracks installs via the records

package/dist/index.js

@@ -2,7 +2,7 @@ import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import { basename, dirname, join } from "node:path";
 import { homedir, platform, tmpdir } from "node:os";
-import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { buildConfigValidationSchema, parseManifestFile } from "@alfe.ai/integration-manifest";
 import { createLogger } from "@auriclabs/logger";
 import { parseDocument } from "yaml";
@@ -856,6 +856,22 @@ function stripPluginVersion(spec) {
 	if (at <= 0) return spec;
 	return spec.slice(0, at);
 }
+/**
+* Return the pinned version from a plugin spec, or `undefined` when the spec
+* carries no version (bare package name). Mirror of `stripPluginVersion`: the
+* version is everything after the LAST '@' when that '@' sits at index > 0
+* (i.e. it's a real version delimiter, not the scope's leading '@').
+*
+* Used by the force-mode reinstall path to compare the pinned version against
+* the installed one so an already-current plugin can skip a ~45s
+* uninstall+reinstall cycle.
+*/
+function pluginSpecVersion(spec) {
+	const at = spec.lastIndexOf("@");
+	if (at <= 0) return void 0;
+	const version = spec.slice(at + 1);
+	return version.length > 0 ? version : void 0;
+}
 //#endregion
 //#region src/integration-manager.ts
 /**
@@ -1729,16 +1745,86 @@ const BUNDLED_BASELINE_ALLOW = ["browser"];
 const CONFIG_SET_RETRIES$1 = 3;
 const CONFIG_SET_RETRY_DELAY_MS$1 = 750;
 /**
+* Max `openclaw config get` spawns in flight at once during the batch
+* verify-after-write. A naive `Promise.all(leaves.map(...))` fires one CLI
+* process per leaf simultaneously — a 36-leaf model-provider batch on a 2-vCPU
+* box means 36 concurrent `config get`s, each needing ~1.9s of CPU, so every
+* process blows its own 10s timeout and the verify reports false even when the
+* write actually landed. A small pool keeps the read-backs honest under load.
+*/
+const VERIFY_GET_CONCURRENCY = 4;
+/**
 * Sentinel OpenClaw returns from `config get` in place of a sensitive value —
 * the key IS set, OpenClaw is just hiding it. Verify-after-write must treat a
 * read-back of this as "present/matches" rather than a mismatch (see
 * `configValueMatches`).
 */
 const OPENCLAW_REDACTED = "__OPENCLAW_REDACTED__";
+/**
+* OpenClaw's gateway runtime deterministically truncates its own WAL-mode state
+* DB (`<home>/state/openclaw.sqlite`) ~50s after boot: the page_count header
+* shrinks while btree/freelist entries still reference pages past the new end.
+* Once corrupt, EVERY `openclaw` CLI invocation that walks the freelist dies at
+* startup with this exact phrase (printed to STDOUT, exit 1), which kills every
+* `plugins install` during activation. Upstream (no fix, suggests exactly this
+* quarantine-and-recreate recovery): https://github.com/openclaw/openclaw/issues/71689.
+* `doctor --fix` does NOT detect it. The state DB is disposable — plugin installs
+* live in `<home>/npm/node_modules` + the on-disk registry, so quarantine + any
+* CLI command rebuilds it via migrations with no meaningful loss.
+*/
+const MALFORMED_STATE_DB_PHRASE = "database disk image is malformed";
+/**
+* Rate-limit the state-DB self-heal to ONE attempt per applier instance per
+* window so a heal→corrupt→heal loop (the runtime re-corrupts the fresh DB ~50s
+* later) can't thrash the box. Wall-clock `Date.now()` is fine here — this is
+* runtime daemon code, not a workflow script.
+*/
+const HEAL_MIN_INTERVAL_MS = 600 * 1e3;
+/**
+* Cooldown after a FAILED heal attempt. A failed heal produced no fresh DB, so
+* the full HEAL_MIN_INTERVAL_MS lockout is unjustified (it would strand the box
+* with the main DB quarantined and no recreate); a short cooldown just stops a
+* tight retry loop from hammering rename/recreate.
+*/
+const FAILED_HEAL_COOLDOWN_MS = 60 * 1e3;
+/**
+* True when an execFile rejection carries the malformed-state-DB signature.
+* OpenClaw prints the reason to STDOUT (not stderr), and Node's execFile error
+* embeds the argv in `message`, so all three streams are checked. The phrase is
+* specific enough to match on directly (case-insensitive).
+*/
+function isMalformedStateDbError(err) {
+	if (!(err instanceof Error)) return false;
+	const e = err;
+	return `${e.message}\n${e.stderr ?? ""}\n${e.stdout ?? ""}`.toLowerCase().includes(MALFORMED_STATE_DB_PHRASE);
+}
 const delay$1 = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
 /**
+* Run `fn` over `items` with at most `limit` invocations in flight at once,
+* preserving result order. A tiny local pool (no new dependency) so the batch
+* verify-after-write doesn't stampede one `openclaw config get` per leaf — see
+* VERIFY_GET_CONCURRENCY.
+*
+* NOTE: relies on `fn` never rejecting (configValueMatches catches internally).
+* A throwing `fn` would reject the pool while sibling workers keep draining
+* items in the background — don't wire a throwing `fn` in here.
+*/
+async function mapWithConcurrency(items, limit, fn) {
+	const results = new Array(items.length);
+	let cursor = 0;
+	const worker = async () => {
+		while (cursor < items.length) {
+			const index = cursor++;
+			results[index] = await fn(items[index]);
+		}
+	};
+	const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+	await Promise.all(workers);
+	return results;
+}
+/**
 * Asymmetric structural containment for verify-after-write: is every field we
 * INTENDED present in the ACTUAL read-back with our value? `actual` may carry
 * EXTRA keys that `intended` does not.
@@ -1781,19 +1867,70 @@ function deepSubset(intended, actual) {
 function redactConfigSetTarget(args) {
 	return `openclaw config ${args.slice(0, 2).join(" ")}`.trim();
 }
+/** Cap a captured stream so a runaway OpenClaw dump can't bloat errorMessage. */
+const ERROR_STREAM_MAX = 400;
+function truncateForError(s) {
+	return s.length > ERROR_STREAM_MAX ? `${s.slice(0, ERROR_STREAM_MAX)}… (truncated)` : s;
+}
+/**
+* Collect the value strings a `config set` argv carries so they can be scrubbed
+* out of OpenClaw's own output. OpenClaw validation errors can echo the
+* offending VALUE back in their diagnostic text, so stdout/stderr must be
+* treated as value-bearing, not just the argv. For `{path, value}` batch
+* entries only the `value` side is collected — redacting the path out of
+* "invalid path models.providers…" would gut the diagnostic.
+*/
+function collectArgvValues(args) {
+	const out = [];
+	const collect = (v) => {
+		if (typeof v === "string") {
+			if (v.length >= 4) out.push(v);
+		} else if (Array.isArray(v)) v.forEach(collect);
+		else if (v !== null && typeof v === "object") {
+			const o = v;
+			if (typeof o.path === "string" && "value" in o) collect(o.value);
+			else Object.values(o).forEach(collect);
+		}
+	};
+	for (const token of args.slice(2)) {
+		if (token.startsWith("--")) continue;
+		try {
+			collect(JSON.parse(token));
+		} catch {
+			collect(token);
+		}
+	}
+	return out.sort((a, b) => b.length - a.length);
+}
+/** Replace every occurrence of the argv-derived values in a captured stream. */
+function scrubStream(s, values) {
+	let out = s;
+	for (const v of values) if (out.includes(v)) out = out.split(v).join("[REDACTED]");
+	return out;
+}
 /**
 * 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` (openclaw's own error text).
+* redacted target, the exit code, `stderr`, and `stdout`.
+*
+* OpenClaw prints its own error text to STDOUT (not stderr), so on a genuine
+* failure `stderr` is often empty and the real cause is in stdout — surfacing
+* only stderr left days of bare "(exit 1)" in the logs. We include a truncated
+* stdout too — but scrubbed first: OpenClaw's error text can echo the offending
+* value, so both streams are run through `scrubStream` with the argv values
+* before anything reaches the dashboard-visible errorMessage.
 */
 function configSetErrorMessage(err, args) {
 	const target = redactConfigSetTarget(args);
 	if (err instanceof Error) {
 		const e = err;
-		const stderr = typeof e.stderr === "string" ? e.stderr.trim() : "";
+		const values = collectArgvValues(args);
+		const stderr = typeof e.stderr === "string" ? scrubStream(e.stderr.trim(), values) : "";
+		const stdout = typeof e.stdout === "string" ? scrubStream(e.stdout.trim(), values) : "";
 		const code = e.code !== void 0 ? ` (exit ${e.code})` : "";
-		return stderr ? `${target} failed${code}: ${stderr}` : `${target} failed${code}`;
+		const details = [stderr, stdout ? `stdout: ${truncateForError(stdout)}` : ""].filter(Boolean).join("; ");
+		return details ? `${target} failed${code}: ${details}` : `${target} failed${code}`;
 	}
 	return `${target} failed: ${String(err)}`;
 }
@@ -1826,6 +1963,11 @@ var OpenClawApplier = class {
 	* acquires it ONCE at the top and calls only `*Unlocked` helpers inside.
 	*/
 	cliLock;
+	/**
+	* Monotonic-ish guard for the state-DB self-heal — timestamp of the last heal
+	* this instance performed (0 = never). See HEAL_MIN_INTERVAL_MS.
+	*/
+	lastHealAt = 0;
 	constructor(options) {
 		const home = options.home ?? options.workspace;
 		if (!home) throw new Error("OpenClawApplier requires `home` (or legacy `workspace`) option");
@@ -1864,7 +2006,7 @@ var OpenClawApplier = class {
 		const timeout = opts.timeout ?? 1e4;
 		let lastErr;
 		for (let attempt = 0; attempt <= this.configSetRetries; attempt++) try {
-			await execFileAsync$1("openclaw", ["config", ...args], { timeout });
+			await this.execOpenClawHealing(["config", ...args], { timeout });
 			return;
 		} catch (err) {
 			lastErr = err;
@@ -1911,6 +2053,99 @@ var OpenClawApplier = class {
 		}
 		return false;
 	}
+	/**
+	* `openclaw <args>` with automatic malformed-state-DB self-heal. On a
+	* malformed-DB failure (see isMalformedStateDbError): quarantine + recreate the
+	* state DB (healMalformedStateDb), then retry the ORIGINAL command exactly
+	* once. If the heal is rate-limited/failed, or the single retry also fails, the
+	* error propagates unchanged — callers keep their existing failure semantics
+	* (retry loops, install-tolerance checks, log.warn) as if healing never ran.
+	*
+	* Assumes the shared CLI lock is already held by the calling public method: the
+	* heal runs INSIDE the same locked section as the failed command. NEVER
+	* re-acquires the non-re-entrant `cliLock`.
+	*
+	* Runtime-alive safety: reconcile-path callers run under the gateway's
+	* RuntimeGate (runtime stopped), but the `setConfigRaw` hook (daemon
+	* `alfe.config_set`) can heal while `openclaw gateway run` still holds the DB.
+	* That is safe by fd/inode decoupling, not by exclusivity: renameSync is
+	* inode-level, the live runtime keeps writing its orphaned inode (discarded on
+	* its next restart — the state DB is disposable), and the recreated DB gets
+	* fresh -wal/-shm files the old process never attaches to.
+	*/
+	async execOpenClawHealing(args, opts = {}) {
+		try {
+			await execFileAsync$1("openclaw", args, opts);
+			return;
+		} catch (err) {
+			if (!isMalformedStateDbError(err)) throw err;
+			log$3.warn({ args: args.slice(0, 2) }, "openclaw CLI failed with a malformed state DB — attempting self-heal then one retry");
+			if (!await this.healMalformedStateDb()) throw err;
+			await execFileAsync$1("openclaw", args, opts);
+		}
+	}
+	/**
+	* Quarantine the corrupt OpenClaw state DB and recreate it. Never throws
+	* (logs + returns whether the heal succeeded). Rate-limited to one attempt per
+	* HEAL_MIN_INTERVAL_MS so a heal→re-corrupt→heal loop can't thrash the box.
+	*
+	* Steps (human-verified against a live managed agent): rename
+	* `state/openclaw.sqlite{,-wal,-shm}` aside with a `.quarantined-<ISO>` suffix
+	* (keep for forensics; -wal/-shm may be absent), then run `openclaw plugins
+	* list` to rebuild the DB via OpenClaw's migration framework (slow on a 2-vCPU
+	* box — 90s budget). Assumes the caller holds `cliLock` (see
+	* execOpenClawHealing for the runtime-alive rename semantics).
+	*
+	* A SUCCESSFUL heal consumes the full rate-limit window (a fresh DB exists for
+	* the runtime to re-corrupt — that loop is what the window prevents). A FAILED
+	* heal only gets the short cooldown: no fresh DB was produced, and a full
+	* window would strand the box with the main DB quarantined and no recreate for
+	* 10 minutes.
+	*/
+	async healMalformedStateDb() {
+		const now = Date.now();
+		if (now - this.lastHealAt < HEAL_MIN_INTERVAL_MS) {
+			log$3.warn({ sinceLastHealMs: now - this.lastHealAt }, "openclaw state DB malformed but a heal ran within the rate-limit window — skipping to avoid a heal→corrupt→heal loop");
+			return false;
+		}
+		this.lastHealAt = now;
+		const stateDir = join(this.home, "state");
+		const stamp = new Date(now).toISOString().replaceAll(":", "-");
+		const quarantined = [];
+		try {
+			for (const name of [
+				"openclaw.sqlite",
+				"openclaw.sqlite-wal",
+				"openclaw.sqlite-shm"
+			]) {
+				const src = join(stateDir, name);
+				if (!existsSync(src)) continue;
+				const dest = `${src}.quarantined-${stamp}`;
+				renameSync(src, dest);
+				quarantined.push(dest);
+			}
+			if (quarantined.length === 0) {
+				log$3.warn({ stateDir }, "malformed openclaw state DB reported but no state/openclaw.sqlite* files found to quarantine");
+				this.lastHealAt = now - HEAL_MIN_INTERVAL_MS + FAILED_HEAL_COOLDOWN_MS;
+				return false;
+			}
+			log$3.warn({
+				stateDir,
+				quarantined
+			}, "quarantined malformed openclaw state DB — recreating via `openclaw plugins list` (upstream openclaw/openclaw#71689)");
+			await execFileAsync$1("openclaw", ["plugins", "list"], { timeout: 9e4 });
+			log$3.warn({ stateDir }, "recreated openclaw state DB after quarantine");
+			return true;
+		} catch (err) {
+			log$3.warn({
+				stateDir,
+				quarantined,
+				err: err instanceof Error ? err.message : String(err)
+			}, "failed to heal malformed openclaw state DB — leaving quarantined files for forensics");
+			this.lastHealAt = now - HEAL_MIN_INTERVAL_MS + FAILED_HEAL_COOLDOWN_MS;
+			return false;
+		}
+	}
 	applyPlugin(spec, _installPath, opts) {
 		return this.cliLock.run(() => this.applyPluginLocked(spec, opts));
 	}
@@ -1919,9 +2154,21 @@ var OpenClawApplier = class {
 		await this.ensurePluginsAllowUnlocked(pkg);
 		this.cleanupUntrackedExtensionInstall(pkg);
 		if (opts?.force && this.isPluginInstalled(pkg)) {
+			const pinnedVersion = pluginSpecVersion(spec);
+			const installedVersion = this.installedPluginVersion(pkg);
+			if (pinnedVersion && installedVersion && installedVersion === pinnedVersion) {
+				log$3.info({
+					pkg,
+					spec,
+					version: installedVersion
+				}, "Force mode — installed version already matches pinned spec, skipping uninstall+reinstall");
+				return;
+			}
 			log$3.info({
 				pkg,
-				spec
+				spec,
+				installedVersion,
+				pinnedVersion
 			}, "Force mode — uninstalling plugin before reinstall");
 			try {
 				await this.removePluginUnlocked(pkg);
@@ -1944,12 +2191,12 @@ var OpenClawApplier = class {
 			const args = useUnsafeFlag ? [...baseArgs, "--dangerously-force-unsafe-install"] : baseArgs;
 			try {
 				try {
-					await execFileAsync$1("openclaw", args, { timeout: 6e4 });
+					await this.execOpenClawHealing(args, { timeout: 6e4 });
 				} catch (err) {
 					const errText = err instanceof Error ? `${err.message}\n${err.stderr ?? ""}` : String(err);
 					if (useUnsafeFlag && errText.includes("unknown option")) {
 						log$3.info({ pkg }, "OpenClaw does not support --dangerously-force-unsafe-install, retrying without");
-						await execFileAsync$1("openclaw", baseArgs, { timeout: 6e4 });
+						await this.execOpenClawHealing(baseArgs, { timeout: 6e4 });
 					} else throw err;
 				}
 			} catch (err) {
@@ -2039,6 +2286,25 @@ var OpenClawApplier = class {
 		return readdirSync(extensionsDir).some((dir) => dir.startsWith(prefix) && /^[0-9a-f]+$/i.test(dir.slice(prefix.length)));
 	}
 	/**
+	* Best-effort read of the installed version of a plugin, or `undefined` when
+	* it can't be determined. Reads the version from the installed package's
+	* package.json under the npm registry path OpenClaw 2026.5+ installs to
+	* (`~/.openclaw/npm/node_modules/<pkg>/package.json`) — the same root
+	* `isPluginInstalled` checks. 2026.4 extensions-dir installs have no
+	* stable package.json version here and return `undefined` (callers fail
+	* open to the safe reinstall path).
+	*/
+	installedPluginVersion(pkg) {
+		const pkgJsonPath = join(this.home, "npm", "node_modules", ...pkg.split("/"), "package.json");
+		if (!existsSync(pkgJsonPath)) return void 0;
+		try {
+			const data = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+			return typeof data.version === "string" ? data.version : void 0;
+		} catch {
+			return;
+		}
+	}
+	/**
 	* Remove an extensions/ install that has no matching record in
 	* plugins/installs.json. OpenClaw 2026.5+ tracks installs via the records
 	* file — a leftover dir from 2026.4 is invisible to `openclaw plugins
@@ -2092,11 +2358,12 @@ var OpenClawApplier = class {
 	* path). Never call outside a locked section.
 	*/
 	async removePluginUnlocked(spec) {
-		await execFileAsync$1("openclaw", [
+		const pkg = stripPluginVersion(spec);
+		await this.execOpenClawHealing([
 			"plugins",
 			"uninstall",
 			"--force",
-			stripPluginVersion(spec)
+			pkg
 		], { timeout: 3e4 });
 	}
 	applySkill(name, srcPath) {
@@ -2192,10 +2459,10 @@ var OpenClawApplier = class {
 				"--batch-json",
 				JSON.stringify(leaves),
 				"--replace"
-			]);
+			], { timeout: Math.min(Math.max(3e4, leaves.length * 2e3), 12e4) });
 		} catch (err) {
 			if (await this.verifyApplied(async () => {
-				return (await Promise.all(leaves.map((l) => this.configValueMatches(l.path, l.value)))).every(Boolean);
+				return (await mapWithConcurrency(leaves, VERIFY_GET_CONCURRENCY, (l) => this.configValueMatches(l.path, l.value))).every(Boolean);
 			})) log$3.warn({ count: leaves.length }, "openclaw config set --batch-json exited non-zero but config landed — continuing");
 			else {
 				log$3.error({

package/package.json

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