feat: make notifyBotToken/adminUserId optional

The client never sends pairing notifications (the server does); these
Discord fields were required but unused. Make them optional + drop from
the config schema's required list. Back-compat: still accepted if set.

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

package-lock.json

@@ -12,10 +12,14 @@
       },
       "devDependencies": {
         "@types/node": "^25.5.2",
+        "openclaw": "file:/usr/lib/node_modules/openclaw",
         "typescript": "^5.6.3",
         "vitest": "^4.1.3"
       }
     },
+    "../../../../../usr/lib/node_modules/openclaw": {
+      "dev": true
+    },
     "node_modules/@emnapi/core": {
       "version": "1.9.1",
       "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.9.1.tgz",
@@ -914,6 +918,10 @@
       ],
       "license": "MIT"
     },
+    "node_modules/openclaw": {
+      "resolved": "../../../../../usr/lib/node_modules/openclaw",
+      "link": true
+    },
     "node_modules/pathe": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",

package.json

@@ -5,6 +5,9 @@
   "description": "Yonexus.Client OpenClaw plugin scaffold",
   "type": "module",
   "main": "dist/plugin/index.js",
+  "openclaw": {
+    "extensions": ["./dist/Yonexus.Client/plugin/index.js"]
+  },
   "files": [
     "dist",
     "plugin",
@@ -29,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

@@ -1,8 +1,12 @@
 export interface YonexusClientConfig {
   mainHost: string;
   identifier: string;
-  notifyBotToken: string;
-  adminUserId: string;
+  /**
+   * Optional. The client never sends pairing notifications (the server
+   * does); accepted for back-compat but no longer required.
+   */
+  notifyBotToken?: string;
+  adminUserId?: string;
 }
 
 export class YonexusClientConfigError extends Error {
@@ -44,15 +48,9 @@ export function validateYonexusClientConfig(raw: unknown): YonexusClientConfig {
     issues.push("identifier is required");
   }
 
+  // Optional (back-compat): the client does not send notifications.
   const rawNotifyBotToken = source.notifyBotToken;
-  if (!isNonEmptyString(rawNotifyBotToken)) {
-    issues.push("notifyBotToken is required");
-  }
-
   const rawAdminUserId = source.adminUserId;
-  if (!isNonEmptyString(rawAdminUserId)) {
-    issues.push("adminUserId is required");
-  }
 
   if (issues.length > 0) {
     throw new YonexusClientConfigError(issues);
@@ -60,13 +58,15 @@ export function validateYonexusClientConfig(raw: unknown): YonexusClientConfig {
 
   const mainHost = (rawMainHost as string).trim();
   const identifier = (rawIdentifier as string).trim();
-  const notifyBotToken = (rawNotifyBotToken as string).trim();
-  const adminUserId = (rawAdminUserId as string).trim();
 
   return {
     mainHost,
     identifier,
-    notifyBotToken,
-    adminUserId
+    notifyBotToken: isNonEmptyString(rawNotifyBotToken)
+      ? rawNotifyBotToken.trim()
+      : undefined,
+    adminUserId: isNonEmptyString(rawAdminUserId)
+      ? rawAdminUserId.trim()
+      : undefined
   };
 }

plugin/core/runtime.ts

@@ -29,6 +29,7 @@ import {
 } from "./state.js";
 import { generateNonce, signMessage } from "../crypto/keypair.js";
 import type { ClientConnectionState, ClientTransport } from "./transport.js";
+import type { ClientRuleRegistry } from "./rules.js";
 
 export type YonexusClientPhase =
   | "idle"
@@ -44,6 +45,8 @@ export interface YonexusClientRuntimeOptions {
   config: YonexusClientConfig;
   transport: ClientTransport;
   stateStore: YonexusClientStateStore;
+  ruleRegistry?: ClientRuleRegistry;
+  onAuthenticated?: () => void;
   now?: () => number;
 }
 
@@ -118,6 +121,7 @@ export class YonexusClientRuntime {
     }
 
     if (!isBuiltinMessage(raw)) {
+      this.options.ruleRegistry?.dispatch(raw);
       return;
     }
 
@@ -159,6 +163,7 @@ export class YonexusClientRuntime {
       };
       await this.options.stateStore.save(this.clientState);
       this.phase = "authenticated";
+      this.options.onAuthenticated?.();
       return;
     }
 
@@ -177,7 +182,17 @@ export class YonexusClientRuntime {
 
   handleTransportStateChange(state: ClientConnectionState): void {
     if (state === "connected") {
-      this.sendHello();
+      // Reload state from disk before hello so that any secret written by an
+      // external process (e.g. a pairing script) is picked up on reconnect.
+      this.options.stateStore.load(this.options.config.identifier).then((fresh) => {
+        if (fresh) {
+          this.clientState = { ...this.clientState, ...fresh };
+        }
+        this.sendHello();
+      }).catch(() => {
+        // If reload fails, proceed with in-memory state
+        this.sendHello();
+      });
     }
 
     if (state === "disconnected") {
@@ -259,7 +274,10 @@ export class YonexusClientRuntime {
       adminNotification: payload.adminNotification
     };
     this.lastPairingFailure = undefined;
-    this.phase = payload.adminNotification === "sent" ? "waiting_pair_confirm" : "pair_required";
+    // Always wait for the pairing code regardless of notification status.
+    // When adminNotification is "failed", the admin can retrieve the code
+    // via the server CLI command and deliver it through an alternate channel.
+    this.phase = "waiting_pair_confirm";
   }
 
   private async handlePairSuccess(envelope: TypedBuiltinEnvelope<"pair_success">): Promise<void> {
@@ -316,6 +334,12 @@ export class YonexusClientRuntime {
     }
 
     this.lastPairingFailure = payload.reason;
+    // If the server lost our session (race condition), re-announce via hello
+    // so the server creates a new session and we can retry auth.
+    if (payload.reason === "not_paired" && hasClientSecret(this.clientState)) {
+      this.sendHello();
+      return;
+    }
     this.phase = "auth_required";
   }
 

plugin/index.ts

@@ -39,31 +39,113 @@ export {
   type ClientRuleProcessor
 } from "./core/rules.js";
 
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { validateYonexusClientConfig } from "./core/config.js";
+import { createYonexusClientStateStore } from "./core/state.js";
+import { createClientTransport } from "./core/transport.js";
+import { createYonexusClientRuntime, type YonexusClientRuntime } from "./core/runtime.js";
+import { createClientRuleRegistry, YonexusClientRuleRegistry } from "./core/rules.js";
+
+const _G = globalThis as Record<string, unknown>;
+const _STARTED_KEY   = "_yonexusClientStarted";
+const _RUNTIME_KEY   = "_yonexusClientRuntime";
+const _REGISTRY_KEY  = "_yonexusClientRegistry";
+const _CALLBACKS_KEY = "_yonexusClientOnAuthCallbacks";
+
+const PLUGIN_DATA_DIR = path.join(os.homedir(), ".openclaw", "yonexus-client");
+
 export interface YonexusClientPluginManifest {
   readonly name: "Yonexus.Client";
   readonly version: string;
   readonly description: string;
 }
 
-export interface YonexusClientPluginRuntime {
-  readonly hooks: readonly [];
-  readonly commands: readonly [];
-  readonly tools: readonly [];
-}
-
 const manifest: YonexusClientPluginManifest = {
   name: "Yonexus.Client",
   version: "0.1.0",
   description: "Yonexus client plugin for cross-instance OpenClaw communication"
 };
 
-export function createYonexusClientPlugin(): YonexusClientPluginRuntime {
-  return {
-    hooks: [],
-    commands: [],
-    tools: []
+export function createYonexusClientPlugin(api: OpenClawPluginApi): void {
+  // 1. Ensure shared state survives hot-reload — only initialise when absent
+  if (!(_G[_REGISTRY_KEY] instanceof YonexusClientRuleRegistry)) {
+    _G[_REGISTRY_KEY] = createClientRuleRegistry();
+  }
+  if (!Array.isArray(_G[_CALLBACKS_KEY])) {
+    _G[_CALLBACKS_KEY] = [];
+  }
+
+  const ruleRegistry         = _G[_REGISTRY_KEY] as YonexusClientRuleRegistry;
+  const onAuthenticatedCallbacks = _G[_CALLBACKS_KEY] as Array<() => void>;
+
+  // 2. Refresh the cross-plugin API object every call so that sendRule / submitPairingCode
+  //    closures always read the live runtime from globalThis.
+  _G["__yonexusClient"] = {
+    ruleRegistry,
+    sendRule: (ruleId: string, content: string): boolean =>
+      (_G[_RUNTIME_KEY] as YonexusClientRuntime | undefined)?.sendRuleMessage(ruleId, content) ?? false,
+    submitPairingCode: (code: string): boolean =>
+      (_G[_RUNTIME_KEY] as YonexusClientRuntime | undefined)?.submitPairingCode(code) ?? false,
+    onAuthenticated: onAuthenticatedCallbacks
   };
+
+  // 3. Runtime startup — only fire when the gateway boots, not eagerly during
+  //    register() inside one-shot CLI subprocesses (e.g. `openclaw completion`).
+  //    Without this gate, every CLI invocation that loads plugins would open
+  //    a WebSocket to the Yonexus server.
+  api.on("gateway_start", () => {
+    if (_G[_STARTED_KEY]) return;
+    _G[_STARTED_KEY] = true;
+
+    fs.mkdirSync(PLUGIN_DATA_DIR, { recursive: true });
+
+    const config = validateYonexusClientConfig(api.pluginConfig);
+    const stateStore = createYonexusClientStateStore(path.join(PLUGIN_DATA_DIR, "state.json"));
+
+    const transport = createClientTransport({
+      config,
+      onMessage: (msg) => {
+        (_G[_RUNTIME_KEY] as YonexusClientRuntime | undefined)?.handleMessage(msg).catch((err: unknown) => {
+          console.error("[yonexus-client] message handler error:", err);
+        });
+      },
+      onStateChange: (state) => {
+        (_G[_RUNTIME_KEY] as YonexusClientRuntime | undefined)?.handleTransportStateChange(state);
+      }
+    });
+
+    const runtime = createYonexusClientRuntime({
+      config,
+      transport,
+      stateStore,
+      ruleRegistry,
+      onAuthenticated: () => {
+        for (const cb of onAuthenticatedCallbacks) cb();
+      }
+    });
+    _G[_RUNTIME_KEY] = runtime;
+
+    runtime.start().catch((err: unknown) => {
+      console.error("[yonexus-client] failed to start:", err);
+    });
+  });
+
+  api.on("gateway_stop", () => {
+    const runtime = _G[_RUNTIME_KEY] as YonexusClientRuntime | undefined;
+    runtime?.stop().catch((err: unknown) => {
+      console.error("[yonexus-client] shutdown error:", err);
+    });
+  });
 }
 
-export default createYonexusClientPlugin;
+export default definePluginEntry({
+  id: "yonexus-client",
+  name: "Yonexus.Client",
+  description: "Yonexus client plugin for cross-instance OpenClaw communication",
+  register: createYonexusClientPlugin,
+});
 export { manifest };

plugin/openclaw.plugin.json

@@ -1,13 +1,19 @@
 {
+  "id": "yonexus-client",
   "name": "Yonexus.Client",
-  "version": "0.1.0",
   "description": "Yonexus client plugin for cross-instance OpenClaw communication",
-  "entry": "dist/plugin/index.js",
-  "permissions": [],
-  "config": {
-    "mainHost": "",
-    "identifier": "",
-    "notifyBotToken": "",
-    "adminUserId": ""
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "mainHost": { "type": "string" },
+      "identifier": { "type": "string" },
+      "notifyBotToken": { "type": "string" },
+      "adminUserId": { "type": "string" }
+    },
+    "required": ["mainHost", "identifier"]
   }
 }

scripts/install.mjs

@@ -29,6 +29,7 @@ if (mode === "install") {
   fs.rmSync(targetDir, { recursive: true, force: true });
   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}`);
   process.exit(0);
 }