@alfe.ai/integrations 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -359,6 +359,22 @@ interface RuntimeApplier {
    * its absence and degrade gracefully.
    */
   setConfigRaw?(key: string, value: string): Promise<void>;
+  /**
+   * Optional: read a single raw config key back from the runtime, returning the
+   * scalar value as a string (or `undefined` when the key is unset / can't be
+   * read). Used by the daemon's config-reconcile pass (plan A4) to value-diff
+   * before writing (skip when equal) and to verify a write landed.
+   *
+   * MUST normalize the runtime's `config get` output to the same scalar string
+   * that `setConfigRaw` was called with (e.g. unwrap the JSON quoting OpenClaw's
+   * `config get` adds), so a `getConfigRaw(k) === want` compare is exact.
+   *
+   * Read-back can be a false negative under load (a 2-vCPU box running a
+   * `config get` while the runtime hot-reloads) — callers MUST retry with the
+   * same cadence as a write verify, never one-shot. Appliers that can't read
+   * config omit this method; callers degrade gracefully (blind set, no diff).
+   */
+  getConfigRaw?(key: string): Promise<string | undefined>;
   /** Check if this runtime is available (e.g. workspace directory exists) */
   isAvailable(): Promise<boolean>;
 }
@@ -697,6 +713,13 @@ declare class IntegrationManager {
   clear(): void;
   private checkHealth;
   private err;
+  /**
+   * Build a hook-failure message. A hook we SIGKILLed at its timeout is rendered
+   * as `(timed out after <ms>ms)` so it is visually distinguishable in Sentry
+   * from a genuine non-zero exit `(exit <code>)` — the two have very different
+   * root causes (Sentry AGENT-DAEMON-6).
+   */
+  private hookFailureMessage;
   /**
    * Compute the plugin (bare package) names and skill names still claimed by
    * SOME integration in the CURRENT lock state, keyed by runtime. Both
@@ -786,31 +809,16 @@ declare class StateManager {
 }
 //#endregion
 //#region src/hooks.d.ts
-/**
- * Hook Runner — executes integration lifecycle hook scripts.
- *
- * Hooks are scripts defined in the integration manifest. The runner
- * auto-detects the interpreter from the script's shebang line or file
- * extension (.js/.mjs → node, .py → python3, default → bash).
- *
- * Scripts run as child processes with a 30-second timeout.
- * stdout/stderr are captured and returned.
- *
- * The runner injects standard environment variables:
- * - ALFE_INTEGRATION_DIR — path to the integration install directory
- * - ALFE_STATE_DIR — path to the integration state directory (created if needed)
- * - ALFE_<NAME>_<KEY> — config values (non-secret AND secret, both injected as env vars)
- *
- * Secrets are acceptable as env vars because:
- * - Child process env is ephemeral (dies with the process)
- * - Same security model as Docker secrets / systemd credentials
- * - Never written to disk
- */
 interface HookResult {
   exitCode: number;
   stdout: string;
   stderr: string;
   timedOut: boolean;
+  /**
+   * When `timedOut` is true, the timeout ceiling (ms) that fired the SIGKILL.
+   * Lets callers render a timeout distinctly from a genuine non-zero exit.
+   */
+  timedOutAfterMs?: number;
 }
 interface HookEnvOptions {
   /** Integration name (e.g. "voice") */
@@ -857,9 +865,12 @@ declare function buildHookEnv(options: HookEnvOptions, additionalEnv?: Record<st
  * @param integrationPath - Base path of the integration (where alfe-integration.yaml lives)
  * @param hookScript - Relative path to the hook script (e.g. "scripts/activate.sh")
  * @param env - Additional environment variables to pass to the script
+ * @param timeoutMs - Timeout before the hook is SIGKILLed. Defaults to the fast
+ *   lifecycle ceiling ({@link HOOK_TIMEOUT_MS}); install-phase callers pass
+ *   {@link INSTALL_HOOK_TIMEOUT_MS}.
  * @returns Hook execution result
  */
-declare function runHook(integrationPath: string, hookScript: string, env?: Record<string, string>): Promise<HookResult>;
+declare function runHook(integrationPath: string, hookScript: string, env?: Record<string, string>, timeoutMs?: number): Promise<HookResult>;
 /**
  * Run a hook script with full integration context (config + secrets as env vars).
  *
@@ -870,9 +881,12 @@ declare function runHook(integrationPath: string, hookScript: string, env?: Reco
  * @param integrationPath - Base path of the integration
  * @param hookScript - Relative path to the hook script
  * @param options - Integration name, config, and secrets
+ * @param timeoutMs - Timeout before the hook is SIGKILLed. Defaults to the fast
+ *   lifecycle ceiling ({@link HOOK_TIMEOUT_MS}); install-phase callers pass
+ *   {@link INSTALL_HOOK_TIMEOUT_MS}.
  * @returns Hook execution result
  */
-declare function runHookWithContext(integrationPath: string, hookScript: string, options: HookEnvOptions): Promise<HookResult>;
+declare function runHookWithContext(integrationPath: string, hookScript: string, options: HookEnvOptions, timeoutMs?: number): Promise<HookResult>;
 //#endregion
 //#region src/openclaw-cli-lock.d.ts
 /**
@@ -1220,6 +1234,21 @@ declare class OpenClawApplier implements RuntimeApplier {
    * config writes trigger.
    */
   setConfigRaw(key: string, value: string): Promise<void>;
+  /**
+   * Read a single config key back — `openclaw config get <key>` — and normalize
+   * to the scalar string that `setConfigRaw` would have written. `config get`
+   * emits JSON, so a scalar comes back quoted (`"claude-sonnet-4-6"`); parse it
+   * to the raw value so a `=== want` compare in the daemon's config-reconcile
+   * pass is exact.
+   *
+   * Returns `undefined` when the key is unset, the command fails, or the runtime
+   * REDACTS the value (a sensitive key we can't compare — treat as "unknown" so
+   * the caller doesn't spuriously diff). Under the shared CLI lock so it can't
+   * interleave with a concurrent mutation. NOT self-healing on a malformed state
+   * DB — a read failure returns `undefined`, and the caller's set path (which IS
+   * healing) recovers.
+   */
+  getConfigRaw(key: string): Promise<string | undefined>;
   isAvailable(): Promise<boolean>;
   private readTracking;
   private writeTracking;
@@ -1281,6 +1310,14 @@ declare class HermesApplier implements RuntimeApplier {
    * per-integration removal accounting). Reuses the serialized queue.
    */
   setConfigRaw(key: string, value: string): Promise<void>;
+  /**
+   * Read a single config key back — `hermes config get <key>` — normalized to
+   * the scalar string `setConfigRaw` would have written (used by the daemon's
+   * config-reconcile value-diff + verify, plan A4). Returns `undefined` when the
+   * key is unset or the command fails. Serialized onto the same config queue so
+   * it can't interleave with an in-flight `hermes config set`.
+   */
+  getConfigRaw(key: string): Promise<string | undefined>;
   /**
    * 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

package/dist/index.js

@@ -746,7 +746,19 @@ var LockManager = class {
 * - Same security model as Docker secrets / systemd credentials
 * - Never written to disk
 */
+/**
+* Default timeout for lifecycle hooks (activate/health_check/uninstall). These
+* are expected to be fast; a long-running one is a bug and should be killed.
+*/
 const HOOK_TIMEOUT_MS = 3e4;
+/**
+* Timeout for install-phase hooks (pre_install/post_install). These legitimately
+* take minutes — they clone repos, run `npm install`, download binaries — so the
+* fast 30s ceiling would SIGKILL a healthy install mid-flight (Sentry
+* AGENT-DAEMON-6). Callers opt into this longer ceiling explicitly per hook type;
+* it is NOT the global default so lifecycle hooks stay fast.
+*/
+const INSTALL_HOOK_TIMEOUT_MS = 6e5;
 const INTEGRATIONS_BASE_DIR = join(homedir(), ".alfe", "integrations");
 const STATE_BASE_DIR = join(homedir(), ".alfe", "state");
 /**
@@ -848,9 +860,12 @@ function resolveInterpreter(scriptPath) {
 * @param integrationPath - Base path of the integration (where alfe-integration.yaml lives)
 * @param hookScript - Relative path to the hook script (e.g. "scripts/activate.sh")
 * @param env - Additional environment variables to pass to the script
+* @param timeoutMs - Timeout before the hook is SIGKILLed. Defaults to the fast
+*   lifecycle ceiling ({@link HOOK_TIMEOUT_MS}); install-phase callers pass
+*   {@link INSTALL_HOOK_TIMEOUT_MS}.
 * @returns Hook execution result
 */
-async function runHook(integrationPath, hookScript, env) {
+async function runHook(integrationPath, hookScript, env, timeoutMs = HOOK_TIMEOUT_MS) {
 	const scriptPath = join(integrationPath, hookScript);
 	if (!existsSync(scriptPath)) return {
 		exitCode: 0,
@@ -878,7 +893,7 @@ async function runHook(integrationPath, hookScript, env) {
 		const timer = setTimeout(() => {
 			timedOut = true;
 			proc.kill("SIGKILL");
-		}, HOOK_TIMEOUT_MS);
+		}, timeoutMs);
 		proc.stdout.on("data", (data) => {
 			stdout += data.toString();
 			if (stdout.length > 1e5) stdout = stdout.slice(0, 1e5) + "\n[truncated]";
@@ -893,7 +908,8 @@ async function runHook(integrationPath, hookScript, env) {
 				exitCode: code ?? 1,
 				stdout: stdout.trim(),
 				stderr: stderr.trim(),
-				timedOut
+				timedOut,
+				timedOutAfterMs: timedOut ? timeoutMs : void 0
 			});
 		});
 		proc.on("error", (err) => {
@@ -917,10 +933,13 @@ async function runHook(integrationPath, hookScript, env) {
 * @param integrationPath - Base path of the integration
 * @param hookScript - Relative path to the hook script
 * @param options - Integration name, config, and secrets
+* @param timeoutMs - Timeout before the hook is SIGKILLed. Defaults to the fast
+*   lifecycle ceiling ({@link HOOK_TIMEOUT_MS}); install-phase callers pass
+*   {@link INSTALL_HOOK_TIMEOUT_MS}.
 * @returns Hook execution result
 */
-async function runHookWithContext(integrationPath, hookScript, options) {
-	return runHook(integrationPath, hookScript, buildHookEnv(options));
+async function runHookWithContext(integrationPath, hookScript, options, timeoutMs = HOOK_TIMEOUT_MS) {
+	return runHook(integrationPath, hookScript, buildHookEnv(options), timeoutMs);
 }
 //#endregion
 //#region src/plugin-spec.ts
@@ -1127,8 +1146,8 @@ var IntegrationManager = class {
 			if (!installHooksSupported && (manifest.hooks.pre_install || manifest.hooks.post_install)) this.log.warn(`Integration "${name}" install hooks skipped — no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${(manifest.supported_agents ?? []).join(", ")})`);
 			if (installHooksSupported && manifest.hooks.pre_install) {
 				this.log.info(`Running pre_install hook: ${manifest.hooks.pre_install}`);
-				const hookResult = await runHook(installPath, manifest.hooks.pre_install);
-				if (hookResult.exitCode !== 0) throw new Error(`pre_install hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
+				const hookResult = await runHook(installPath, manifest.hooks.pre_install, void 0, INSTALL_HOOK_TIMEOUT_MS);
+				if (hookResult.exitCode !== 0) throw new Error(this.hookFailureMessage("pre_install hook failed", hookResult));
 			}
 			if (installHooksSupported && manifest.hooks.post_install) {
 				this.log.info(`Running post_install hook: ${manifest.hooks.post_install}`);
@@ -1137,8 +1156,8 @@ var IntegrationManager = class {
 					config: config ?? {},
 					secrets: this.secrets.get(name),
 					runtimes: [...this.runtimeAppliers.keys()]
-				});
-				if (hookResult.exitCode !== 0) throw new Error(`post_install hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
+				}, INSTALL_HOOK_TIMEOUT_MS);
+				if (hookResult.exitCode !== 0) throw new Error(this.hookFailureMessage("post_install hook failed", hookResult));
 			}
 			this.state.set(name, {
 				status: "installed",
@@ -1328,8 +1347,9 @@ var IntegrationManager = class {
 					runtimes: [...this.runtimeAppliers.keys()]
 				});
 				if (hookResult.exitCode !== 0) {
-					this.state.setStatus(integrationId, "error", `post_activate hook failed: ${hookResult.stderr || hookResult.stdout}`);
-					return this.err("POST_ACTIVATE_FAILED", `post_activate hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
+					const message = this.hookFailureMessage("post_activate hook failed", hookResult);
+					this.state.setStatus(integrationId, "error", message);
+					return this.err("POST_ACTIVATE_FAILED", message);
 				}
 			}
 			if (manifest.hooks.health_check && !runtimeSupported) this.log.warn(`Integration "${integrationId}" health_check hook skipped — no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${(supportedAgents ?? []).join(", ")})`);
@@ -1342,8 +1362,9 @@ var IntegrationManager = class {
 					runtimes: [...this.runtimeAppliers.keys()]
 				});
 				if (hookResult.exitCode !== 0) {
-					this.state.setStatus(integrationId, "error", `Health check failed: ${hookResult.stderr || hookResult.stdout}`);
-					return this.err("HEALTH_CHECK_FAILED", `Health check failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
+					const message = this.hookFailureMessage("Health check failed", hookResult);
+					this.state.setStatus(integrationId, "error", message);
+					return this.err("HEALTH_CHECK_FAILED", message);
 				}
 			}
 			this.log.info(`Integration "${integrationId}" activated`);
@@ -1485,8 +1506,8 @@ var IntegrationManager = class {
 					config: entry.config,
 					secrets: this.secrets.get(name),
 					runtimes: [...this.runtimeAppliers.keys()]
-				});
-				if (hookResult.exitCode !== 0) this.log.warn(`pre_uninstall hook failed (continuing): ${hookResult.stderr}`);
+				}, INSTALL_HOOK_TIMEOUT_MS);
+				if (hookResult.exitCode !== 0) this.log.warn(this.hookFailureMessage("pre_uninstall hook failed (continuing)", hookResult));
 			}
 			if (uninstallHooksSupported && manifest?.hooks.post_uninstall) {
 				this.log.info(`Running post_uninstall hook: ${manifest.hooks.post_uninstall}`);
@@ -1495,8 +1516,8 @@ var IntegrationManager = class {
 					config: entry.config,
 					secrets: this.secrets.get(name),
 					runtimes: [...this.runtimeAppliers.keys()]
-				});
-				if (hookResult.exitCode !== 0) this.log.warn(`post_uninstall hook failed (non-fatal): ${hookResult.stderr}`);
+				}, INSTALL_HOOK_TIMEOUT_MS);
+				if (hookResult.exitCode !== 0) this.log.warn(this.hookFailureMessage("post_uninstall hook failed (non-fatal)", hookResult));
 			}
 			if (this.installer.isInstalled(name)) {
 				await this.installer.remove(name);
@@ -1647,8 +1668,8 @@ var IntegrationManager = class {
 			if (!installHooksSupported && (newManifest.hooks.pre_install || newManifest.hooks.post_install)) this.log.warn(`Integration "${name}" upgrade install hooks skipped — no registered runtime (${[...this.runtimeAppliers.keys()].join(", ")}) is in supported_agents (${(newManifest.supported_agents ?? []).join(", ")})`);
 			if (installHooksSupported && newManifest.hooks.pre_install) {
 				this.log.info(`Running pre_install hook: ${newManifest.hooks.pre_install}`);
-				const hookResult = await runHook(this.installer.getInstallPath(name), newManifest.hooks.pre_install);
-				if (hookResult.exitCode !== 0) throw new Error(`pre_install hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
+				const hookResult = await runHook(this.installer.getInstallPath(name), newManifest.hooks.pre_install, void 0, INSTALL_HOOK_TIMEOUT_MS);
+				if (hookResult.exitCode !== 0) throw new Error(this.hookFailureMessage("pre_install hook failed", hookResult));
 			}
 			if (installHooksSupported && newManifest.hooks.post_install) {
 				this.log.info(`Running post_install hook: ${newManifest.hooks.post_install}`);
@@ -1657,8 +1678,8 @@ var IntegrationManager = class {
 					config: config ?? existing.config,
 					secrets: this.secrets.get(name),
 					runtimes: [...this.runtimeAppliers.keys()]
-				});
-				if (hookResult.exitCode !== 0) throw new Error(`post_install hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
+				}, INSTALL_HOOK_TIMEOUT_MS);
+				if (hookResult.exitCode !== 0) throw new Error(this.hookFailureMessage("post_install hook failed", hookResult));
 			}
 			await this.applyUpgradeDiffRemovals(name, oldManifest, newManifest);
 			return await this.activate(name, { forcePlugins: true });
@@ -1837,7 +1858,7 @@ var IntegrationManager = class {
 				healthy: hookResult.exitCode === 0,
 				status: entry.status,
 				version: manifest.version,
-				message: hookResult.exitCode === 0 ? "Healthy" : `Health check failed (exit ${String(hookResult.exitCode)})`,
+				message: hookResult.exitCode === 0 ? "Healthy" : hookResult.timedOut ? `Health check failed (timed out after ${String(hookResult.timedOutAfterMs ?? "?")}ms)` : `Health check failed (exit ${String(hookResult.exitCode)})`,
 				stdout: hookResult.stdout || void 0,
 				stderr: hookResult.stderr || void 0
 			};
@@ -1861,6 +1882,17 @@ var IntegrationManager = class {
 		};
 	}
 	/**
+	* Build a hook-failure message. A hook we SIGKILLed at its timeout is rendered
+	* as `(timed out after <ms>ms)` so it is visually distinguishable in Sentry
+	* from a genuine non-zero exit `(exit <code>)` — the two have very different
+	* root causes (Sentry AGENT-DAEMON-6).
+	*/
+	hookFailureMessage(label, hookResult) {
+		const reason = hookResult.timedOut ? `timed out after ${String(hookResult.timedOutAfterMs ?? "?")}ms` : `exit ${String(hookResult.exitCode)}`;
+		const output = hookResult.stderr || hookResult.stdout;
+		return output ? `${label} (${reason}): ${output}` : `${label} (${reason})`;
+	}
+	/**
 	* Compute the plugin (bare package) names and skill names still claimed by
 	* SOME integration in the CURRENT lock state, keyed by runtime. Both
 	* `deactivate` and `upgrade`'s diff-removal call this AFTER
@@ -2948,6 +2980,46 @@ var OpenClawApplier = class {
 	setConfigRaw(key, value) {
 		return this.cliLock.run(() => this.runConfigSetUnlocked([key, value]));
 	}
+	/**
+	* Read a single config key back — `openclaw config get <key>` — and normalize
+	* to the scalar string that `setConfigRaw` would have written. `config get`
+	* emits JSON, so a scalar comes back quoted (`"claude-sonnet-4-6"`); parse it
+	* to the raw value so a `=== want` compare in the daemon's config-reconcile
+	* pass is exact.
+	*
+	* Returns `undefined` when the key is unset, the command fails, or the runtime
+	* REDACTS the value (a sensitive key we can't compare — treat as "unknown" so
+	* the caller doesn't spuriously diff). Under the shared CLI lock so it can't
+	* interleave with a concurrent mutation. NOT self-healing on a malformed state
+	* DB — a read failure returns `undefined`, and the caller's set path (which IS
+	* healing) recovers.
+	*/
+	getConfigRaw(key) {
+		return this.cliLock.run(async () => {
+			try {
+				const { stdout } = await execFileAsync$1("openclaw", [
+					"config",
+					"get",
+					key
+				], { timeout: 1e4 });
+				const trimmed = stdout.trim();
+				if (!trimmed) return void 0;
+				let parsed;
+				try {
+					parsed = JSON.parse(trimmed);
+				} catch {
+					return trimmed;
+				}
+				if (parsed === null || parsed === void 0) return void 0;
+				if (parsed === OPENCLAW_REDACTED) return void 0;
+				if (typeof parsed === "string") return parsed;
+				if (typeof parsed === "number" || typeof parsed === "boolean") return String(parsed);
+				return JSON.stringify(parsed);
+			} catch {
+				return;
+			}
+		});
+	}
 	isAvailable() {
 		return Promise.resolve(existsSync(this.home));
 	}
@@ -3153,6 +3225,40 @@ var HermesApplier = class {
 		return this.runConfigSet([key, value]);
 	}
 	/**
+	* Read a single config key back — `hermes config get <key>` — normalized to
+	* the scalar string `setConfigRaw` would have written (used by the daemon's
+	* config-reconcile value-diff + verify, plan A4). Returns `undefined` when the
+	* key is unset or the command fails. Serialized onto the same config queue so
+	* it can't interleave with an in-flight `hermes config set`.
+	*/
+	getConfigRaw(key) {
+		const run = async () => {
+			try {
+				const { stdout } = await execFileAsync("hermes", [
+					"config",
+					"get",
+					key
+				], { timeout: 1e4 });
+				const trimmed = stdout.trim();
+				if (!trimmed) return void 0;
+				try {
+					const parsed = JSON.parse(trimmed);
+					if (parsed === null || parsed === void 0) return void 0;
+					if (typeof parsed === "string") return parsed;
+					if (typeof parsed === "number" || typeof parsed === "boolean") return String(parsed);
+					return JSON.stringify(parsed);
+				} catch {
+					return trimmed;
+				}
+			} catch {
+				return;
+			}
+		};
+		const result = this.configSetQueue.then(run, run);
+		this.configSetQueue = result.catch(() => void 0);
+		return result;
+	}
+	/**
 	* 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.

package/package.json

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