feat: selectable pairing-notify provider (discord optional, add fabric)

Pairing-code delivery was hardwired to Discord DM (notifyBotToken +
adminUserId required). Make the provider config-selectable.

- core/config.ts: add notifyProvider ("discord"|"fabric", default
  "discord" for back-compat); discord fields required only for discord;
  add fabric block (centerApiBase/apiKey/guildNodeId/channelId) required
  only for fabric
- notifications/types.ts: neutral PairingNotificationService interface
  (DiscordNotificationService kept as back-compat alias)
- notifications/fabric.ts: post the pairing message to a Fabric channel
  (agent/login -> guild token -> POST messages); self-contained, no
  Fabric plugin dependency
- notifications/factory.ts: select provider from config
- core/runtime.ts: wire via factory
- openclaw.plugin.json: notifyProvider enum + fabric object; drop
  notifyBotToken/adminUserId from required (conditional in code)
- tests: fabric notifier + provider-selection config (80 passing)

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.Server OpenClaw plugin scaffold",
   "type": "module",
   "main": "dist/plugin/index.js",
+  "openclaw": {
+    "extensions": ["./dist/Yonexus.Server/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,7 +1,22 @@
+export type NotifyProvider = "discord" | "fabric";
+
+export interface FabricNotifyConfig {
+  centerApiBase: string;
+  apiKey: string;
+  guildNodeId: string;
+  channelId: string;
+}
+
 export interface YonexusServerConfig {
   followerIdentifiers: string[];
-  notifyBotToken: string;
+  /** Pairing-code delivery provider. Default: "discord" (back-compat). */
-  adminUserId: string;
+  notifyProvider: NotifyProvider;
+  /** Required only when notifyProvider === "discord". */
+  notifyBotToken?: string;
+  /** Required only when notifyProvider === "discord". */
+  adminUserId?: string;
+  /** Required only when notifyProvider === "fabric". */
+  fabric?: FabricNotifyConfig;
   listenHost?: string;
   listenPort: number;
   publicWsUrl?: string;
@@ -35,7 +50,7 @@ function normalizeOptionalString(value: unknown): string | undefined {
 }
 
 function isValidPort(value: unknown): value is number {
-  return Number.isInteger(value) && value >= 1 && value <= 65535;
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
 }
 
 function isValidWsUrl(value: string): boolean {
@@ -59,26 +74,57 @@ 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) {
     issues.push("followerIdentifiers must not contain duplicates");
   }
 
-  const notifyBotToken = source.notifyBotToken;
+  const rawNotifyProvider = source.notifyProvider;
-  if (!isNonEmptyString(notifyBotToken)) {
+  let notifyProvider: NotifyProvider = "discord";
-    issues.push("notifyBotToken is required");
+  if (rawNotifyProvider === undefined || rawNotifyProvider === null) {
+    notifyProvider = "discord";
+  } else if (rawNotifyProvider === "discord" || rawNotifyProvider === "fabric") {
+    notifyProvider = rawNotifyProvider;
+  } else {
+    issues.push('notifyProvider must be "discord" or "fabric"');
   }
 
-  const adminUserId = source.adminUserId;
+  // Discord fields — required only for the discord provider.
-  if (!isNonEmptyString(adminUserId)) {
+  const rawNotifyBotToken = source.notifyBotToken;
-    issues.push("adminUserId is required");
+  const rawAdminUserId = source.adminUserId;
+  if (notifyProvider === "discord") {
+    if (!isNonEmptyString(rawNotifyBotToken)) {
+      issues.push('notifyBotToken is required when notifyProvider is "discord"');
+    }
+    if (!isNonEmptyString(rawAdminUserId)) {
+      issues.push('adminUserId is required when notifyProvider is "discord"');
+    }
   }
 
-  const listenPort = source.listenPort;
+  // Fabric fields — required only for the fabric provider.
-  if (!isValidPort(listenPort)) {
+  let fabric: FabricNotifyConfig | undefined;
+  if (notifyProvider === "fabric") {
+    const f = (source.fabric && typeof source.fabric === "object"
+      ? source.fabric
+      : {}) as Record<string, unknown>;
+    const centerApiBase = normalizeOptionalString(f.centerApiBase);
+    const apiKey = normalizeOptionalString(f.apiKey);
+    const guildNodeId = normalizeOptionalString(f.guildNodeId);
+    const channelId = normalizeOptionalString(f.channelId);
+    if (!centerApiBase) issues.push("fabric.centerApiBase is required when notifyProvider is \"fabric\"");
+    if (!apiKey) issues.push("fabric.apiKey is required when notifyProvider is \"fabric\"");
+    if (!guildNodeId) issues.push("fabric.guildNodeId is required when notifyProvider is \"fabric\"");
+    if (!channelId) issues.push("fabric.channelId is required when notifyProvider is \"fabric\"");
+    if (centerApiBase && apiKey && guildNodeId && channelId) {
+      fabric = { centerApiBase, apiKey, guildNodeId, channelId };
+    }
+  }
+
+  const rawListenPort = source.listenPort;
+  if (!isValidPort(rawListenPort)) {
     issues.push("listenPort must be an integer between 1 and 65535");
   }
 
@@ -93,10 +139,18 @@ export function validateYonexusServerConfig(raw: unknown): YonexusServerConfig {
     throw new YonexusServerConfigError(issues);
   }
 
+  const listenPort = rawListenPort as number;
+
   return {
     followerIdentifiers,
-    notifyBotToken: notifyBotToken.trim(),
+    notifyProvider,
-    adminUserId: adminUserId.trim(),
+    notifyBotToken: isNonEmptyString(rawNotifyBotToken)
+      ? rawNotifyBotToken.trim()
+      : undefined,
+    adminUserId: isNonEmptyString(rawAdminUserId)
+      ? rawAdminUserId.trim()
+      : undefined,
+    fabric,
     listenHost,
     listenPort,
     publicWsUrl

plugin/core/persistence.ts

@@ -79,6 +79,9 @@ export interface ClientRecord {
   /** Last successful authentication timestamp (UTC unix seconds) */
   lastAuthenticatedAt?: number;
 
+  /** Last successful pairing timestamp (UTC unix seconds) */
+  pairedAt?: number;
+
   /**
    * Recent nonces used in authentication attempts.
    * This is a rolling window that may be cleared on restart.
@@ -151,6 +154,7 @@ export interface SerializedClientRecord {
   status: ClientLivenessStatus;
   lastHeartbeatAt?: number;
   lastAuthenticatedAt?: number;
+  pairedAt?: number;
   createdAt: number;
   updatedAt: number;
   // Note: recentNonces and recentHandshakeAttempts are intentionally
@@ -203,6 +207,7 @@ export function serializeClientRecord(record: ClientRecord): SerializedClientRec
     status: record.status,
     lastHeartbeatAt: record.lastHeartbeatAt,
     lastAuthenticatedAt: record.lastAuthenticatedAt,
+    pairedAt: record.pairedAt,
     createdAt: record.createdAt,
     updatedAt: record.updatedAt
   };

plugin/core/runtime.ts

@@ -38,20 +38,22 @@ 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";
-import {
+import type { PairingNotificationService } from "../notifications/types.js";
-  createDiscordNotificationService,
+import { createNotificationService } from "../notifications/factory.js";
-  type DiscordNotificationService
-} from "../notifications/discord.js";
 import { safeErrorMessage } from "./logging.js";
+import type { ServerRuleRegistry } from "./rules.js";
 
 export interface YonexusServerRuntimeOptions {
   config: YonexusServerConfig;
   store: YonexusServerStore;
   transport: ServerTransport;
+  notificationService?: PairingNotificationService;
+  ruleRegistry?: ServerRuleRegistry;
+  onClientAuthenticated?: (identifier: string) => void;
   now?: () => number;
   sweepIntervalMs?: number;
 }
@@ -66,7 +68,7 @@ export class YonexusServerRuntime {
   private readonly now: () => number;
   private readonly registry: ServerRegistry;
   private readonly pairingService: PairingService;
-  private readonly notificationService: DiscordNotificationService;
+  private readonly notificationService: PairingNotificationService;
   private readonly sweepIntervalMs: number;
   private sweepTimer: NodeJS.Timeout | null = null;
   private started = false;
@@ -80,10 +82,9 @@ export class YonexusServerRuntime {
     };
     this.sweepIntervalMs = options.sweepIntervalMs ?? 30_000;
     this.pairingService = createPairingService({ now: this.now });
-    this.notificationService = createDiscordNotificationService({
+    this.notificationService =
-      botToken: options.config.notifyBotToken,
+      options.notificationService ??
-      adminUserId: options.config.adminUserId
+      createNotificationService(options.config);
-    });
   }
 
   get state(): ServerLifecycleState {
@@ -444,7 +445,7 @@ export class YonexusServerRuntime {
     );
     record.recentHandshakeAttempts.push(now);
 
-    if (record.recentHandshakeAttempts.length > AUTH_MAX_ATTEMPTS_PER_WINDOW) {
+    if (record.recentHandshakeAttempts.length >= AUTH_MAX_ATTEMPTS_PER_WINDOW) {
       await this.triggerRePairRequired(connection, record, envelope.requestId, "rate_limited");
       return;
     }
@@ -540,7 +541,10 @@ export class YonexusServerRuntime {
       session.lastActivityAt = now;
       session.publicKey = publicKey;
     }
-    this.options.transport.promoteToAuthenticated(identifier, connection.ws);
+    const promoted = this.options.transport.promoteToAuthenticated(identifier, connection.ws);
+    if (promoted) {
+      this.options.onClientAuthenticated?.(identifier);
+    }
     this.options.transport.sendToConnection(
       { ...connection, identifier },
       encodeBuiltin(
@@ -610,6 +614,11 @@ export class YonexusServerRuntime {
       this.pairingService.markNotificationFailed(record);
     }
 
+    // Persist immediately so the pairing code is readable from disk (e.g. via CLI)
+    if (!reusePending) {
+      await this.persist();
+    }
+
     this.options.transport.sendToConnection(
       connection,
       encodeBuiltin(
@@ -617,7 +626,7 @@ export class YonexusServerRuntime {
           {
             identifier: record.identifier,
             expiresAt: request.expiresAt,
-            ttlSeconds: this.pairingService.getRemainingTtl(record),
+            ttlSeconds: request.ttlSeconds,
             adminNotification: notified ? "sent" : "failed",
             codeDelivery: "out_of_band"
           },
@@ -625,22 +634,8 @@ export class YonexusServerRuntime {
         )
       )
     );
-
+    // Pairing remains pending regardless of notification status.
-    if (!notified) {
+    // The admin can retrieve the pairing code via the server CLI command.
-      this.options.transport.sendToConnection(
-        connection,
-        encodeBuiltin(
-          buildPairFailed(
-            {
-              identifier: record.identifier,
-              reason: "admin_notification_failed"
-            },
-            { requestId, timestamp: this.now() }
-          )
-        )
-      );
-      this.pairingService.clearPairingState(record);
-    }
   }
 
   private async handleHeartbeat(
@@ -929,16 +924,8 @@ export class YonexusServerRuntime {
       const parsed = parseRuleMessage(raw);
       const rewritten = `${parsed.ruleIdentifier}::${senderIdentifier}::${parsed.content}`;
 
-      // TODO: Dispatch to registered rules via rule registry
-      // For now, just log the rewritten message
-      // this.ruleRegistry.dispatch(rewritten);
-
-      // Update last activity
       session.lastActivityAt = this.now();
-
+      this.options.ruleRegistry?.dispatch(rewritten);
-      // Future: dispatch to rule registry
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      void rewritten;
     } catch (error) {
       // Malformed rule message
       this.options.transport.sendToConnection(

plugin/core/transport.ts

@@ -186,6 +186,16 @@ export class YonexusServerTransport implements ServerTransport {
       this._connections.delete(identifier);
     }
 
+    // Also close any OTHER temp connections that claimed the same identifier.
+    // This handles the case where a second hello came in with the same identifier
+    // while the first was still in the temp/pairing phase.
+    for (const [otherWs, otherTemp] of this.tempConnections.entries()) {
+      if (otherWs !== ws && otherTemp.assignedIdentifier === identifier) {
+        otherWs.close(1008, "Connection replaced by new authenticated session");
+        this.tempConnections.delete(otherWs);
+      }
+    }
+
     // Remove from temp connections
     this.tempConnections.delete(ws);
 
@@ -229,22 +239,24 @@ export class YonexusServerTransport implements ServerTransport {
 
     ws.on("message", (data: RawData) => {
       const message = data.toString("utf8");
-      // Try to get identifier from temp connections first, then authenticated connections
+      // If this ws is still in temp state, use tempConn directly.
-      let identifier: string | null = null;
+      // Never fall through to _connections — it may hold a stale entry for the
-      const tempData = this.tempConnections.get(ws);
+      // same identifier from a previously-authenticated session that hasn't
-      if (tempData) {
+      // finished closing yet, which would cause promoteToAuthenticated to receive
-        identifier = tempData.assignedIdentifier;
+      // the wrong WebSocket and silently fail.
-      }
+      if (this.tempConnections.has(ws)) {
-      if (!identifier) {
+        this.options.onMessage(tempConn, message);
-        for (const [id, conn] of this._connections) {
+        return;
-          if (conn.ws === ws) {
-            identifier = id;
-            break;
-          }
-        }
       }
 
-      const connection = identifier ? this._connections.get(identifier) ?? tempConn : tempConn;
+      // ws has been promoted — find it in authenticated connections
+      let connection: ClientConnection = tempConn;
+      for (const [, conn] of this._connections) {
+        if (conn.ws === ws) {
+          connection = conn;
+          break;
+        }
+      }
       this.options.onMessage(connection, message);
     });
 

plugin/index.ts

@@ -30,33 +30,203 @@ export {
   type YonexusServerStore
 } from "./core/store.js";
 
+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";
+import { createYonexusServerRuntime } from "./core/runtime.js";
+import { createServerRuleRegistry, YonexusServerRuleRegistry } from "./core/rules.js";
+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";
+const _REGISTRY_KEY  = "_yonexusServerRegistry";
+const _CALLBACKS_KEY = "_yonexusServerOnAuthCallbacks";
+
 export interface YonexusServerPluginManifest {
   readonly name: "Yonexus.Server";
   readonly version: string;
   readonly description: string;
 }
 
-export interface YonexusServerPluginRuntime {
-  readonly hooks: readonly [];
-  readonly commands: readonly [];
-  readonly tools: readonly [];
-}
-
 const manifest: YonexusServerPluginManifest = {
   name: "Yonexus.Server",
   version: "0.1.0",
   description: "Yonexus central hub plugin for cross-instance OpenClaw communication"
 };
 
-export function createYonexusServerPlugin(): YonexusServerPluginRuntime {
+export function createYonexusServerPlugin(api: OpenClawPluginApi): void {
-  return {
+  const stateFilePath = path.join(PLUGIN_DATA_DIR, "state.json");
-    hooks: [],
+
-    commands: [],
+  // Register CLI regardless of whether the gateway is already running.
-    tools: []
+  // The CLI process is a separate invocation that reads from the persisted state file.
+  api.registerCli?.(({ program }) => {
+    const group = program
+      .command("yonexus-server")
+      .description("Yonexus.Server management");
+
+    group
+      .command("pair-code <identifier>")
+      .description("Show the pending pairing code for a device awaiting confirmation")
+      .action((identifier: string) => {
+        let raw: ServerPersistenceData;
+        try {
+          raw = JSON.parse(fs.readFileSync(stateFilePath, "utf8")) as ServerPersistenceData;
+        } catch {
+          console.error("Error: could not read server state. Is the gateway running?");
+          process.exit(1);
+        }
+
+        const client = raw.clients?.find((c) => c.identifier === identifier);
+        if (!client) {
+          console.error(`Error: identifier "${identifier}" not found in server registry.`);
+          process.exit(1);
+        }
+        if (client.pairingStatus !== "pending" || !client.pairingCode) {
+          const status = client.pairingStatus;
+          console.error(`Error: no pending pairing for "${identifier}" (status: ${status}).`);
+          process.exit(1);
+        }
+        if (client.pairingExpiresAt && Math.floor(Date.now() / 1000) > client.pairingExpiresAt) {
+          console.error(`Error: pairing for "${identifier}" has expired.`);
+          process.exit(1);
+        }
+
+        const expiresIn = client.pairingExpiresAt
+          ? Math.max(0, client.pairingExpiresAt - Math.floor(Date.now() / 1000))
+          : 0;
+        const mm = String(Math.floor(expiresIn / 60)).padStart(2, "0");
+        const ss = String(expiresIn % 60).padStart(2, "0");
+
+        console.log(`Identifier : ${client.identifier}`);
+        console.log(`Pairing code : ${client.pairingCode}`);
+        console.log(`Expires in : ${mm}m ${ss}s`);
+      });
+
+    group
+      .command("list-pending")
+      .description("List all identifiers with a pending pairing code")
+      .action(() => {
+        let raw: ServerPersistenceData;
+        try {
+          raw = JSON.parse(fs.readFileSync(stateFilePath, "utf8")) as ServerPersistenceData;
+        } catch {
+          console.error("Error: could not read server state. Is the gateway running?");
+          process.exit(1);
+        }
+
+        const now = Math.floor(Date.now() / 1000);
+        const pending = (raw.clients ?? []).filter(
+          (c) => c.pairingStatus === "pending" && c.pairingCode && (!c.pairingExpiresAt || now <= c.pairingExpiresAt)
+        );
+
+        if (pending.length === 0) {
+          console.log("No pending pairings.");
+          return;
+        }
+        for (const c of pending) {
+          const expiresIn = c.pairingExpiresAt ? Math.max(0, c.pairingExpiresAt - now) : 0;
+          const mm = String(Math.floor(expiresIn / 60)).padStart(2, "0");
+          const ss = String(expiresIn % 60).padStart(2, "0");
+          console.log(`  ${c.identifier}  (expires in ${mm}m ${ss}s)`);
+        }
+      });
+  }, { commands: ["yonexus-server"] });
+
+  // 1. Ensure shared state survives hot-reload — only initialise when absent
+  if (!(_G[_REGISTRY_KEY] instanceof YonexusServerRuleRegistry)) {
+    _G[_REGISTRY_KEY] = createServerRuleRegistry();
+  }
+  if (!Array.isArray(_G[_CALLBACKS_KEY])) {
+    _G[_CALLBACKS_KEY] = [];
+  }
+
+  const ruleRegistry                  = _G[_REGISTRY_KEY] as YonexusServerRuleRegistry;
+  const onClientAuthenticatedCallbacks = _G[_CALLBACKS_KEY] as Array<(identifier: string) => void>;
+
+  // 2. Refresh the cross-plugin API object every call so that sendRule closure
+  //    always reads the live transport from globalThis.
+  _G["__yonexusServer"] = {
+    ruleRegistry,
+    sendRule: (identifier: string, ruleId: string, content: string): boolean =>
+      (_G[_TRANSPORT_KEY] as ServerTransport | undefined)?.send(identifier, encodeRuleMessage(ruleId, content)) ?? false,
+    onClientAuthenticated: onClientAuthenticatedCallbacks
   };
+
+  // 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 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;
+
+    fs.mkdirSync(PLUGIN_DATA_DIR, { recursive: true });
+
+    const config = validateYonexusServerConfig(api.pluginConfig);
+    const store = createYonexusServerStore(stateFilePath);
+
+    // runtimeRef is local; transport is stored in globalThis so sendRule closures stay valid
+    let runtimeRef: ReturnType<typeof createYonexusServerRuntime> | null = null;
+    const transport = createServerTransport({
+      config,
+      onMessage: (conn, msg) => {
+        runtimeRef?.handleMessage(conn, msg).catch((err: unknown) => {
+          console.error("[yonexus-server] message handler error:", err);
+        });
+      },
+      onDisconnect: (identifier) => {
+        if (identifier && runtimeRef) {
+          runtimeRef.handleDisconnect(identifier);
+        }
+      }
+    });
+    _G[_TRANSPORT_KEY] = transport;
+
+    const runtime = createYonexusServerRuntime({
+      config,
+      store,
+      transport,
+      ruleRegistry,
+      onClientAuthenticated: (identifier) => {
+        for (const cb of onClientAuthenticatedCallbacks) cb(identifier);
+      }
+    });
+    runtimeRef = runtime;
+    _G["_yonexusServerRuntime"] = runtime;
+
+    runtime.start().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);
+    });
+  });
 }
 
-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,
@@ -95,5 +265,11 @@ export {
   type DiscordNotificationService,
   type DiscordNotificationConfig
 } from "./notifications/discord.js";
+export type { PairingNotificationService } from "./notifications/types.js";
+export {
+  createFabricNotificationService,
+  type FabricNotificationConfig
+} from "./notifications/fabric.js";
+export { createNotificationService } from "./notifications/factory.js";
 
 export { manifest };

plugin/notifications/discord.ts

@@ -5,15 +5,14 @@
  */
 
 import type { PairingRequest } from "../services/pairing.js";
+import type { PairingNotificationService } from "./types.js";
 import { redactPairingCode, safeErrorMessage } from "../core/logging.js";
 
-export interface DiscordNotificationService {
+/**
-  /**
+ * Back-compat alias. The Discord notifier is one provider implementing
-   * Send a pairing code notification to the admin user.
+ * the neutral {@link PairingNotificationService} contract.
-   * @returns Whether the notification was sent successfully
+ */
-   */
+export type DiscordNotificationService = PairingNotificationService;
-  sendPairingNotification(request: PairingRequest): Promise<boolean>;
-}
 
 export interface DiscordNotificationConfig {
   botToken: string;
@@ -42,7 +41,7 @@ interface CreateDmChannelResponse {
 interface SendDiscordDirectMessageOptions {
   config: DiscordNotificationConfig;
   message: string;
-  fetcher?: DiscordFetch;
+  fetcher: DiscordFetch;
 }
 
 const DISCORD_API_BASE_URL = "https://discord.com/api/v10";

plugin/notifications/fabric.ts

@@ -0,0 +1,156 @@
+/**
+ * Yonexus Server - Fabric Notification Service
+ *
+ * Sends pairing notifications to a human admin via a Fabric channel.
+ *
+ * Flow:
+ * 1. Exchange the Center API key for a user session
+ *    (POST {centerApiBase}/auth/agent/login → user + guild tokens)
+ * 2. Resolve the target guild's endpoint + access token by guildNodeId
+ * 3. POST the formatted pairing message to the configured channel
+ *    ({guildEndpoint}/api/channels/{channelId}/messages)
+ *
+ * Self-contained (global fetch) and dependency-free, mirroring the
+ * Discord notifier; it does not import the Fabric.OpenclawPlugin.
+ */
+
+import type { PairingRequest } from "../services/pairing.js";
+import type { PairingNotificationService } from "./types.js";
+import { formatPairingMessage } from "./discord.js";
+import { redactPairingCode, safeErrorMessage } from "../core/logging.js";
+
+export interface FabricNotificationConfig {
+  /** Fabric Center API base, e.g. http://localhost:7001/api */
+  centerApiBase: string;
+  /** Fabric Center API key (fak_…) for the notifier identity */
+  apiKey: string;
+  /** Target guild node id the admin channel lives on */
+  guildNodeId: string;
+  /** Channel id (a Fabric channel the admin watches) */
+  channelId: string;
+}
+
+interface FabricSession {
+  user: { id: string };
+  guilds: Array<{ nodeId: string; endpoint: string }>;
+  guildAccessTokens: Array<{ guildNodeId: string; token: string }>;
+}
+
+export interface FabricApiResponse {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}
+
+export type FabricFetch = (
+  input: string,
+  init?: { method?: string; headers?: Record<string, string>; body?: string }
+) => Promise<FabricApiResponse>;
+
+/**
+ * Create a Fabric notification service backed by the Fabric Center +
+ * Guild REST API.
+ */
+export function createFabricNotificationService(
+  config: FabricNotificationConfig,
+  options: { fetcher?: FabricFetch } = {}
+): PairingNotificationService {
+  const fetcher = options.fetcher ?? getDefaultFetch();
+
+  return {
+    async sendPairingNotification(request: PairingRequest): Promise<boolean> {
+      if (
+        !config.centerApiBase.trim() ||
+        !config.apiKey.trim() ||
+        !config.guildNodeId.trim() ||
+        !config.channelId.trim()
+      ) {
+        console.error("[Yonexus.Server] Fabric notification misconfigured", {
+          hasCenterApiBase: Boolean(config.centerApiBase.trim()),
+          hasApiKey: Boolean(config.apiKey.trim()),
+          hasGuildNodeId: Boolean(config.guildNodeId.trim()),
+          hasChannelId: Boolean(config.channelId.trim())
+        });
+        return false;
+      }
+
+      try {
+        const base = config.centerApiBase.replace(/\/+$/, "");
+        const loginRes = await fetcher(`${base}/auth/agent/login`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ apiKey: config.apiKey })
+        });
+        if (!loginRes.ok) {
+          throw new Error(`agent/login failed with status ${loginRes.status}`);
+        }
+        const session = (await loginRes.json()) as FabricSession;
+
+        const endpoint = session.guilds
+          .find((g) => g.nodeId === config.guildNodeId)
+          ?.endpoint?.replace(/\/+$/, "");
+        const token = session.guildAccessTokens.find(
+          (t) => t.guildNodeId === config.guildNodeId
+        )?.token;
+        if (!endpoint || !token) {
+          throw new Error(
+            `notifier identity is not a member of guild ${config.guildNodeId}`
+          );
+        }
+
+        const msgRes = await fetcher(
+          `${endpoint}/api/channels/${config.channelId}/messages`,
+          {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${token}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              content: formatPairingMessage(request),
+              authorUserId: session.user.id
+            })
+          }
+        );
+        if (!msgRes.ok) {
+          throw new Error(`message post failed with status ${msgRes.status}`);
+        }
+        await msgRes.json();
+
+        console.log("[Yonexus.Server] Pairing notification sent via Fabric", {
+          identifier: request.identifier,
+          pairingCode: redactPairingCode(request.pairingCode),
+          expiresAt: request.expiresAt,
+          ttlSeconds: request.ttlSeconds,
+          guildNodeId: config.guildNodeId,
+          channelId: config.channelId
+        });
+        return true;
+      } catch (error) {
+        console.error(
+          "[Yonexus.Server] Failed to send Fabric pairing notification",
+          {
+            identifier: request.identifier,
+            pairingCode: redactPairingCode(request.pairingCode),
+            guildNodeId: config.guildNodeId,
+            channelId: config.channelId,
+            error: safeErrorMessage(error)
+          }
+        );
+        return false;
+      }
+    }
+  };
+}
+
+function getDefaultFetch(): FabricFetch {
+  if (typeof fetch !== "function") {
+    throw new Error("Global fetch is not available in this runtime");
+  }
+  return (input, init) =>
+    fetch(input, {
+      method: init?.method,
+      headers: init?.headers,
+      body: init?.body
+    }) as Promise<FabricApiResponse>;
+}

plugin/notifications/factory.ts

@@ -0,0 +1,30 @@
+/**
+ * Yonexus Server - Pairing notification provider factory.
+ *
+ * Selects the notification provider from config (`notifyProvider`).
+ * Discord is the default for backward compatibility.
+ */
+
+import type { YonexusServerConfig } from "../core/config.js";
+import type { PairingNotificationService } from "./types.js";
+import { createDiscordNotificationService } from "./discord.js";
+import { createFabricNotificationService } from "./fabric.js";
+
+export function createNotificationService(
+  config: YonexusServerConfig
+): PairingNotificationService {
+  if (config.notifyProvider === "fabric") {
+    if (!config.fabric) {
+      throw new Error(
+        'Yonexus.Server: notifyProvider is "fabric" but fabric config is missing'
+      );
+    }
+    return createFabricNotificationService(config.fabric);
+  }
+
+  // Default / "discord"
+  return createDiscordNotificationService({
+    botToken: config.notifyBotToken ?? "",
+    adminUserId: config.adminUserId ?? ""
+  });
+}

plugin/notifications/types.ts

@@ -0,0 +1,18 @@
+/**
+ * Yonexus Server - Pairing notification provider interface.
+ *
+ * A provider delivers the out-of-band pairing code to a human admin.
+ * Implementations: Discord DM (`./discord.ts`), Fabric channel
+ * (`./fabric.ts`). The provider is selected by config (see
+ * `core/config.ts` `notifyProvider`).
+ */
+
+import type { PairingRequest } from "../services/pairing.js";
+
+export interface PairingNotificationService {
+  /**
+   * Send a pairing code notification to the admin.
+   * @returns Whether the notification was sent successfully.
+   */
+  sendPairingNotification(request: PairingRequest): Promise<boolean>;
+}

plugin/openclaw.plugin.json

@@ -1,15 +1,39 @@
 {
+  "id": "yonexus-server",
   "name": "Yonexus.Server",
-  "version": "0.1.0",
   "description": "Yonexus central hub plugin for cross-instance OpenClaw communication",
-  "entry": "dist/plugin/index.js",
+  "activation": {
-  "permissions": [],
+    "onStartup": true
-  "config": {
+  },
-    "followerIdentifiers": [],
+  "commandAliases": [
-    "notifyBotToken": "",
+    { "name": "yonexus-server" }
-    "adminUserId": "",
+  ],
-    "listenHost": "0.0.0.0",
+  "configSchema": {
-    "listenPort": 8787,
+    "type": "object",
-    "publicWsUrl": ""
+    "additionalProperties": false,
+    "properties": {
+      "followerIdentifiers": {
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "notifyProvider": { "type": "string", "enum": ["discord", "fabric"] },
+      "notifyBotToken": { "type": "string" },
+      "adminUserId": { "type": "string" },
+      "fabric": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "centerApiBase": { "type": "string" },
+          "apiKey": { "type": "string" },
+          "guildNodeId": { "type": "string" },
+          "channelId": { "type": "string" }
+        },
+        "required": ["centerApiBase", "apiKey", "guildNodeId", "channelId"]
+      },
+      "listenHost": { "type": "string" },
+      "listenPort": { "type": "number" },
+      "publicWsUrl": { "type": "string" }
+    },
+    "required": ["listenPort"]
   }
 }

plugin/types/ws.d.ts

@@ -0,0 +1,21 @@
+declare module "ws" {
+  export type RawData = Buffer | ArrayBuffer | Buffer[] | string;
+
+  export class WebSocket {
+    static readonly OPEN: number;
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on(event: "message", listener: (data: RawData) => void): this;
+    on(event: "close", listener: (code: number, reason: Buffer) => void): this;
+    on(event: "error", listener: (error: Error) => void): this;
+  }
+
+  export class WebSocketServer {
+    constructor(options: { host?: string; port: number });
+    on(event: "error", listener: (error: Error) => void): this;
+    on(event: "listening", listener: () => void): this;
+    on(event: "connection", listener: (ws: WebSocket, req: import("http").IncomingMessage) => void): this;
+    close(callback?: () => void): void;
+  }
+}

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)) {
@@ -29,9 +63,17 @@ 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"));
-  console.log(`Installed ${pluginName} to ${targetDir}`);
+  fs.copyFileSync(path.join(repoRoot, "package.json"), path.join(targetDir, "package.json"));
+  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/fabric-notification.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  createFabricNotificationService,
+  type FabricFetch
+} from "../plugin/notifications/fabric.js";
+import { validateYonexusServerConfig } from "../plugin/core/config.js";
+
+const request = {
+  identifier: "client-a",
+  pairingCode: "PAIR-1234-CODE",
+  expiresAt: 1_710_000_300,
+  ttlSeconds: 300,
+  createdAt: 1_710_000_000
+};
+
+const fabricConfig = {
+  centerApiBase: "http://center.local/api",
+  apiKey: "fak_test",
+  guildNodeId: "guild-node-1",
+  channelId: "chan-1"
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("Fabric notification service", () => {
+  it("logs in, resolves the guild token, and posts the pairing message", async () => {
+    const fetcher = vi
+      .fn<FabricFetch>()
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          user: { id: "u-1" },
+          guilds: [{ nodeId: "guild-node-1", endpoint: "http://guild.local" }],
+          guildAccessTokens: [{ guildNodeId: "guild-node-1", token: "gtok" }]
+        })
+      })
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({}) });
+
+    const svc = createFabricNotificationService(fabricConfig, { fetcher });
+    const ok = await svc.sendPairingNotification(request);
+
+    expect(ok).toBe(true);
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(fetcher.mock.calls[0][0]).toBe("http://center.local/api/auth/agent/login");
+    expect(fetcher.mock.calls[1][0]).toBe(
+      "http://guild.local/api/channels/chan-1/messages"
+    );
+    const msgInit = fetcher.mock.calls[1][1]!;
+    expect(msgInit.headers?.Authorization).toBe("Bearer gtok");
+    expect(msgInit.body).toContain("PAIR-1234-CODE");
+  });
+
+  it("returns false when the notifier is not a member of the guild", async () => {
+    const fetcher = vi.fn<FabricFetch>().mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ user: { id: "u-1" }, guilds: [], guildAccessTokens: [] })
+    });
+
+    const svc = createFabricNotificationService(fabricConfig, { fetcher });
+    expect(await svc.sendPairingNotification(request)).toBe(false);
+  });
+
+  it("returns false when config is incomplete", async () => {
+    const fetcher = vi.fn<FabricFetch>();
+    const svc = createFabricNotificationService(
+      { ...fabricConfig, apiKey: "" },
+      { fetcher }
+    );
+    expect(await svc.sendPairingNotification(request)).toBe(false);
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+});
+
+describe("notifyProvider config selection", () => {
+  it("defaults to discord and still requires discord fields", () => {
+    expect(() =>
+      validateYonexusServerConfig({ listenPort: 8080 })
+    ).toThrowError(/notifyBotToken is required/);
+  });
+
+  it("does not require discord fields when provider is fabric", () => {
+    const cfg = validateYonexusServerConfig({
+      followerIdentifiers: [],
+      listenPort: 8080,
+      notifyProvider: "fabric",
+      fabric: fabricConfig
+    });
+    expect(cfg.notifyProvider).toBe("fabric");
+    expect(cfg.fabric).toEqual(fabricConfig);
+    expect(cfg.notifyBotToken).toBeUndefined();
+  });
+
+  it("requires fabric fields when provider is fabric", () => {
+    expect(() =>
+      validateYonexusServerConfig({ listenPort: 8080, notifyProvider: "fabric" })
+    ).toThrowError(/fabric\.centerApiBase is required/);
+  });
+
+  it("rejects an unknown provider", () => {
+    expect(() =>
+      validateYonexusServerConfig({ listenPort: 8080, notifyProvider: "sms" })
+    ).toThrowError(/notifyProvider must be/);
+  });
+});

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 {

tests/state-recovery.test.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { createYonexusServerRuntime } from "../plugin/core/runtime.js";
+import { createMockNotificationService } from "../plugin/notifications/discord.js";
 import {
   createYonexusServerStore,
   loadServerStore,
@@ -90,6 +91,7 @@ describe("YNX-1105e: Server state recovery", () => {
       },
       store,
       transport: firstTransport.transport,
+      notificationService: createMockNotificationService(),
       now: () => now
     });
 
@@ -145,6 +147,7 @@ describe("YNX-1105e: Server state recovery", () => {
       },
       store,
       transport: secondTransport.transport,
+      notificationService: createMockNotificationService(),
       now: () => now
     });
 

tsconfig.json

@@ -4,7 +4,7 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "outDir": "dist",
-    "rootDir": ".",
+    "rootDir": "..",
     "strict": true,
     "skipLibCheck": true,
     "esModuleInterop": true,
@@ -15,7 +15,9 @@
   },
   "include": [
     "plugin/**/*.ts",
-    "servers/**/*.ts"
+    "plugin/**/*.d.ts",
+    "servers/**/*.ts",
+    "../Yonexus.Protocol/src/**/*.ts"
   ],
   "exclude": [
     "dist",