fix: gate runtime startup behind gateway_start; migrate to current plugin SDK

Lifecycle:
- Move runtime.start() and shutdown handlers out of register() into
  api.on("gateway_start", ...) and api.on("gateway_stop", ...). register()
  runs in every CLI subprocess that loads plugins (e.g. `openclaw completion`,
  `openclaw doctor`); without this gate the runtime would open a network
  connection / bind a listener every time those one-shot commands ran.
- Drop process.once("SIGTERM"/"SIGINT") in favour of the gateway_stop hook,
  which is the documented way for plugins to react to shutdown.
- Stop relying on the non-standard `api.rootDir` field (not present on the
  current OpenClawPluginApi); compute the per-plugin data directory as
  ~/.openclaw/yonexus-server and ensure it exists before use.

Plugin SDK convention update:
- Wrap default export with definePluginEntry({ id, name, description, register })
  per the current openclaw plugin authoring contract.
- Re-type the register function to accept OpenClawPluginApi instead of the
  hand-crafted { rootDir, pluginConfig, ... } shape.
- Use focused subpath imports openclaw/plugin-sdk/plugin-entry and
  openclaw/plugin-sdk/core.
- Add openclaw as a devDependency (file:/usr/lib/node_modules/openclaw) so
  tsc resolves the SDK type subpaths at build time.
- Modernize openclaw.plugin.json: drop version/entry/permissions, add
  activation.onStartup so gateway_start fires for this plugin at boot.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

package.json

@@ -32,6 +32,7 @@
   "devDependencies": {
     "@types/node": "^25.5.2",
     "typescript": "^5.6.3",
-    "vitest": "^4.1.3"
+    "vitest": "^4.1.3",
+    "openclaw": "file:/usr/lib/node_modules/openclaw"
   }
 }

plugin/core/config.ts

@@ -59,8 +59,8 @@ export function validateYonexusServerConfig(raw: unknown): YonexusServerConfig {
         .filter((value) => value.length > 0)
     : [];
 
-  if (!Array.isArray(rawIdentifiers) || followerIdentifiers.length === 0) {
+  if (!Array.isArray(rawIdentifiers)) {
-    issues.push("followerIdentifiers must contain at least one non-empty identifier");
+    issues.push("followerIdentifiers must be an array");
   }
 
   if (new Set(followerIdentifiers).size !== followerIdentifiers.length) {

plugin/core/runtime.ts

@@ -38,7 +38,7 @@ import {
   type ClientRecord,
   type ServerRegistry
 } from "./persistence.js";
-import { verifySignature } from "../../../Yonexus.Client/plugin/crypto/keypair.js";
+import { verifySignature } from "../../../Yonexus.Protocol/src/crypto.js";
 import type { YonexusServerStore } from "./store.js";
 import { type ClientConnection, type ServerTransport } from "./transport.js";
 import { createPairingService, type PairingService } from "../services/pairing.js";

plugin/index.ts

@@ -32,6 +32,9 @@ export {
 
 import path from "node:path";
 import fs from "node:fs";
+import os from "node:os";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import { validateYonexusServerConfig } from "./core/config.js";
 import { createYonexusServerStore } from "./core/store.js";
 import { createServerTransport, type ServerTransport } from "./core/transport.js";
@@ -40,6 +43,8 @@ import { createServerRuleRegistry, YonexusServerRuleRegistry } from "./core/rule
 import { encodeRuleMessage } from "../../Yonexus.Protocol/src/index.js";
 import type { ServerPersistenceData } from "./core/persistence.js";
 
+const PLUGIN_DATA_DIR = path.join(os.homedir(), ".openclaw", "yonexus-server");
+
 const _G = globalThis as Record<string, unknown>;
 const _STARTED_KEY   = "_yonexusServerStarted";
 const _TRANSPORT_KEY = "_yonexusServerTransport";
@@ -58,14 +63,8 @@ const manifest: YonexusServerPluginManifest = {
   description: "Yonexus central hub plugin for cross-instance OpenClaw communication"
 };
 
-export function createYonexusServerPlugin(api: {
+export function createYonexusServerPlugin(api: OpenClawPluginApi): void {
-  rootDir: string;
+  const stateFilePath = path.join(PLUGIN_DATA_DIR, "state.json");
-  pluginConfig: unknown;
-  registrationMode?: string;  // "full" (gateway) | "cli-metadata" | "setup-only" | "setup-runtime"
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  registerCli?: (registrar: (ctx: { program: any }) => void, opts?: { commands?: string[] }) => void;
-}): void {
-  const stateFilePath = path.join(api.rootDir, "state.json");
 
   // Register CLI regardless of whether the gateway is already running.
   // The CLI process is a separate invocation that reads from the persisted state file.
@@ -162,60 +161,72 @@ export function createYonexusServerPlugin(api: {
     onClientAuthenticated: onClientAuthenticatedCallbacks
   };
 
-  // 3. Start the runtime only once — the globalThis flag survives hot-reload
+  // 3. Runtime startup — only fire when the gateway boots, not eagerly during
-  if (_G[_STARTED_KEY]) return;
+  //    register() inside one-shot CLI subprocesses (e.g. `openclaw completion`).
-  _G[_STARTED_KEY] = true;
+  //    Without this gate, every CLI invocation that loads plugins would try to
+  //    bind the WebSocket listener; EADDRINUSE recovery handled the gateway-
+  //    already-running case but a genuine first-bind in a subprocess would
+  //    keep that process alive forever.
+  api.on("gateway_start", () => {
+    if (_G[_STARTED_KEY]) return;
+    _G[_STARTED_KEY] = true;
 
-  const config = validateYonexusServerConfig(api.pluginConfig);
+    fs.mkdirSync(PLUGIN_DATA_DIR, { recursive: true });
-  const store = createYonexusServerStore(stateFilePath);
 
-  // runtimeRef is local; transport is stored in globalThis so sendRule closures stay valid
+    const config = validateYonexusServerConfig(api.pluginConfig);
-  let runtimeRef: ReturnType<typeof createYonexusServerRuntime> | null = null;
+    const store = createYonexusServerStore(stateFilePath);
-  const transport = createServerTransport({
+
-    config,
+    // runtimeRef is local; transport is stored in globalThis so sendRule closures stay valid
-    onMessage: (conn, msg) => {
+    let runtimeRef: ReturnType<typeof createYonexusServerRuntime> | null = null;
-      runtimeRef?.handleMessage(conn, msg).catch((err: unknown) => {
+    const transport = createServerTransport({
-        console.error("[yonexus-server] message handler error:", err);
+      config,
-      });
+      onMessage: (conn, msg) => {
-    },
+        runtimeRef?.handleMessage(conn, msg).catch((err: unknown) => {
-    onDisconnect: (identifier) => {
+          console.error("[yonexus-server] message handler error:", err);
-      if (identifier && runtimeRef) {
+        });
-        runtimeRef.handleDisconnect(identifier);
+      },
+      onDisconnect: (identifier) => {
+        if (identifier && runtimeRef) {
+          runtimeRef.handleDisconnect(identifier);
+        }
       }
-    }
+    });
-  });
+    _G[_TRANSPORT_KEY] = transport;
-  _G[_TRANSPORT_KEY] = transport;
 
-  const runtime = createYonexusServerRuntime({
+    const runtime = createYonexusServerRuntime({
-    config,
+      config,
-    store,
+      store,
-    transport,
+      transport,
-    ruleRegistry,
+      ruleRegistry,
-    onClientAuthenticated: (identifier) => {
+      onClientAuthenticated: (identifier) => {
-      for (const cb of onClientAuthenticatedCallbacks) cb(identifier);
+        for (const cb of onClientAuthenticatedCallbacks) cb(identifier);
-    }
+      }
-  });
+    });
-  runtimeRef = runtime;
+    runtimeRef = runtime;
+    _G["_yonexusServerRuntime"] = runtime;
 
-  const shutdown = (): void => {
+    runtime.start().catch((err: unknown) => {
-    runtime.stop().catch((err: unknown) => {
+      const code = (err as NodeJS.ErrnoException | undefined)?.code;
+      if (code !== "EADDRINUSE") {
+        console.error("[yonexus-server] failed to start:", err);
+      }
+    });
+  });
+
+  api.on("gateway_stop", () => {
+    const runtime = _G["_yonexusServerRuntime"] as ReturnType<typeof createYonexusServerRuntime> | undefined;
+    runtime?.stop().catch((err: unknown) => {
       console.error("[yonexus-server] shutdown error:", err);
     });
-  };
-  process.once("SIGTERM", shutdown);
-  process.once("SIGINT", shutdown);
-
-  runtime.start().catch((err: unknown) => {
-    // EADDRINUSE means the gateway is already running (e.g. this is a CLI invocation).
-    // Any other error is a real problem worth logging.
-    const code = (err as NodeJS.ErrnoException | undefined)?.code;
-    if (code !== "EADDRINUSE") {
-      console.error("[yonexus-server] failed to start:", err);
-    }
   });
 }
 
-export default createYonexusServerPlugin;
+export default definePluginEntry({
+  id: "yonexus-server",
+  name: "Yonexus.Server",
+  description: "Yonexus central hub plugin for cross-instance OpenClaw communication",
+  register: createYonexusServerPlugin,
+});
 export {
   createServerTransport,
   YonexusServerTransport,

plugin/openclaw.plugin.json

@@ -1,10 +1,13 @@
 {
   "id": "yonexus-server",
   "name": "Yonexus.Server",
-  "version": "0.1.0",
   "description": "Yonexus central hub plugin for cross-instance OpenClaw communication",
-  "entry": "./dist/Yonexus.Server/plugin/index.js",
+  "activation": {
-  "permissions": [],
+    "onStartup": true
+  },
+  "commandAliases": [
+    { "name": "yonexus-server" }
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -19,6 +22,6 @@
       "listenPort": { "type": "number" },
       "publicWsUrl": { "type": "string" }
     },
-    "required": ["followerIdentifiers", "notifyBotToken", "adminUserId", "listenPort"]
+    "required": ["notifyBotToken", "adminUserId", "listenPort"]
   }
 }

scripts/install.mjs

@@ -3,6 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { execSync } from "node:child_process";
 
 const args = process.argv.slice(2);
 const mode = args.includes("--install") ? "install" : args.includes("--uninstall") ? "uninstall" : null;
@@ -15,9 +16,42 @@ if (!mode) {
 }
 
 const repoRoot = path.resolve(import.meta.dirname, "..");
-const pluginName = "Yonexus.Server";
+const pluginId = "yonexus-server";
 const sourceDist = path.join(repoRoot, "dist");
-const targetDir = path.join(profilePath, "plugins", pluginName);
+const targetDir = path.join(profilePath, "plugins", pluginId);
+
+function oc(cmd) {
+  try {
+    return execSync(`openclaw ${cmd}`, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch (e) {
+    console.error(`  ⚠ openclaw ${cmd}: ${e.stderr?.trim() || e.message}`);
+    return null;
+  }
+}
+
+function ensureInArray(configKey, value) {
+  const raw = oc(`config get ${configKey}`);
+  if (!raw) return;
+  const arr = JSON.parse(raw);
+  if (!arr.includes(value)) {
+    arr.push(value);
+    oc(`config set ${configKey} '${JSON.stringify(arr)}' --json`);
+    console.log(`  ✓ ${configKey} includes ${value}`);
+  } else {
+    console.log(`  ✓ ${configKey} already includes ${value}`);
+  }
+}
+
+function removeFromArray(configKey, value) {
+  const raw = oc(`config get ${configKey}`);
+  if (!raw) return;
+  const arr = JSON.parse(raw);
+  const filtered = arr.filter(v => v !== value);
+  if (filtered.length !== arr.length) {
+    oc(`config set ${configKey} '${JSON.stringify(filtered)}' --json`);
+    console.log(`  ✓ Removed ${value} from ${configKey}`);
+  }
+}
 
 if (mode === "install") {
   if (!fs.existsSync(sourceDist)) {
@@ -30,9 +64,16 @@ if (mode === "install") {
   fs.cpSync(sourceDist, path.join(targetDir, "dist"), { recursive: true });
   fs.copyFileSync(path.join(repoRoot, "plugin", "openclaw.plugin.json"), path.join(targetDir, "openclaw.plugin.json"));
   fs.copyFileSync(path.join(repoRoot, "package.json"), path.join(targetDir, "package.json"));
-  console.log(`Installed ${pluginName} to ${targetDir}`);
+  console.log(`  ✓ Plugin files → ${targetDir}`);
+
+  ensureInArray("plugins.load.paths", targetDir);
+  ensureInArray("plugins.allow", pluginId);
+  console.log(`Installed ${pluginId} to ${targetDir}`);
   process.exit(0);
 }
 
+// uninstall
 fs.rmSync(targetDir, { recursive: true, force: true });
-console.log(`Removed ${pluginName} from ${targetDir}`);
+removeFromArray("plugins.load.paths", targetDir);
+removeFromArray("plugins.allow", pluginId);
+console.log(`Removed ${pluginId} from ${targetDir}`);

tests/auth-failures.test.ts

@@ -10,7 +10,7 @@ import { createYonexusServerRuntime } from "../plugin/core/runtime.js";
 import type { ClientRecord } from "../plugin/core/persistence.js";
 import type { YonexusServerStore } from "../plugin/core/store.js";
 import type { ClientConnection, ServerTransport } from "../plugin/core/transport.js";
-import { generateKeyPair, signMessage } from "../../Yonexus.Client/plugin/crypto/keypair.js";
+import { generateKeyPair, signMessage } from "../../Yonexus.Protocol/src/crypto.js";
 
 function createMockSocket() {
   return { close: vi.fn() } as unknown as ClientConnection["ws"];

tests/runtime-flow.test.ts

@@ -17,7 +17,7 @@ import { createYonexusServerRuntime } from "../plugin/core/runtime.js";
 import type { ClientRecord } from "../plugin/core/persistence.js";
 import type { YonexusServerStore } from "../plugin/core/store.js";
 import type { ClientConnection, ServerTransport } from "../plugin/core/transport.js";
-import { generateKeyPair, signMessage, verifySignature } from "../../Yonexus.Client/plugin/crypto/keypair.js";
+import { generateKeyPair, signMessage, verifySignature } from "../../Yonexus.Protocol/src/crypto.js";
 
 function createMockSocket() {
   return {