@alfe.ai/integrations 0.3.1 → 0.3.2

package/dist/index.d.ts

@@ -697,6 +697,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 +793,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 +849,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 +865,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
 /**

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

package/package.json

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