@alfe.ai/openclaw 0.0.27 → 0.0.29

package/README.md

@@ -44,6 +44,30 @@ Alfe Cloud ←—— WebSocket ——→ alfe-gateway daemon (always-on)
 The plugin is a thin IPC client. All heavy lifting (cloud connection, auth,
 protocol translation) is handled by the daemon.
 
+## Plugin Registration Modes
+
+OpenClaw calls `activate(api)` in different modes. Plugins that start persistent
+resources (IPC connections, WebSockets, timers) **must** guard against CLI metadata
+mode to avoid zombie connections during commands like `openclaw plugins list`:
+
+```typescript
+// OpenClaw always provides api.runtime (even as empty {} in CLI mode),
+// so checking api.runtime truthiness does NOT work.
+if (api.registrationMode === 'cli-metadata') {
+  log.debug('CLI metadata mode — skipping resource init');
+  return;
+}
+```
+
+Register tools **before** this guard so they're available for CLI introspection.
+
+| Mode | Context | Persistent resources? |
+|---|---|---|
+| `"full"` | Gateway run, plugin enabled | Yes |
+| `"setup-runtime"` | Gateway run, channel setup | Yes |
+| `"setup-only"` | Gateway run, setup-only channels | Yes |
+| `"cli-metadata"` | CLI commands | **No** |
+
 ## Note
 
 Integration management (install, remove, configure, health) is handled by

package/dist/plugin.d.cts

@@ -17,7 +17,7 @@ interface PluginLogger {
 }
 interface PluginApi {
   logger: PluginLogger;
-  runtime?: unknown;
+  registrationMode?: 'full' | 'setup-only' | 'setup-runtime' | 'cli-metadata';
   config?: {
     plugins?: {
       entries?: Record<string, {

package/dist/plugin.d.ts

@@ -17,7 +17,7 @@ interface PluginLogger {
 }
 interface PluginApi {
   logger: PluginLogger;
-  runtime?: unknown;
+  registrationMode?: 'full' | 'setup-only' | 'setup-runtime' | 'cli-metadata';
   config?: {
     plugins?: {
       entries?: Record<string, {

package/dist/plugin2.cjs

@@ -3180,7 +3180,6 @@ const plugin = {
 	version: "0.1.0",
 	activate(api) {
 		const log = api.logger;
-		const isGatewayMode = !!api.runtime;
 		let cfg = null;
 		try {
 			cfg = (0, _alfe_ai_config.resolveConfig)();
@@ -3195,8 +3194,8 @@ const plugin = {
 			for (const tool of tools) api.registerTool(tool);
 			log.info(`Registered ${String(tools.length)} integration tools: ${tools.map((t) => t.name).join(", ")}`);
 		}
-		if (!isGatewayMode) {
-			log.debug("Management command context — skipping IPC connection init");
+		if (api.registrationMode === "cli-metadata") {
+			log.debug("CLI metadata mode — skipping IPC connection init");
 			return;
 		}
 		if (globalThis.__alfeOpenclawPluginActivated === true) {

package/dist/plugin2.js

@@ -3182,7 +3182,6 @@ const plugin = {
 	version: "0.1.0",
 	activate(api) {
 		const log = api.logger;
-		const isGatewayMode = !!api.runtime;
 		let cfg = null;
 		try {
 			cfg = resolveConfig();
@@ -3197,8 +3196,8 @@ const plugin = {
 			for (const tool of tools) api.registerTool(tool);
 			log.info(`Registered ${String(tools.length)} integration tools: ${tools.map((t) => t.name).join(", ")}`);
 		}
-		if (!isGatewayMode) {
-			log.debug("Management command context — skipping IPC connection init");
+		if (api.registrationMode === "cli-metadata") {
+			log.debug("CLI metadata mode — skipping IPC connection init");
 			return;
 		}
 		if (globalThis.__alfeOpenclawPluginActivated === true) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/openclaw",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "OpenClaw plugin for Alfe — connects to local gateway daemon via IPC for integration management",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
     "@auriclabs/logger": "^0.1.1",
     "@sinclair/typebox": "^0.34.48",
     "@alfe.ai/agent-api-client": "^0.0.7",
-    "@alfe.ai/config": "^0.0.7"
+    "@alfe.ai/config": "^0.0.8"
   },
   "files": [
     "dist",