@ezshine/waifusmy 1.0.0

package/README.md

@@ -0,0 +1,163 @@
+# OpenClaw Channel Plugin - WaifusMy
+
+[OpenClaw](https://github.com/openclaw/openclaw) Channel Plugin for connecting to WaifusMy desktop companion app.
+
+## Overview
+
+This plugin enables OpenClaw to connect to the WaifusMy desktop application via a WebSocket relay server, allowing the AI agent to send and receive messages through the WaifusMy companion.
+
+```
+OpenClaw Agent ◄──Gateway──► WaifusMy Plugin (this project)
+                            │
+                        WSS (outbound connection)
+                            ▼
+                Relay Server (wss://api.waifus.my)
+                            │
+                        WSS
+                            ▼
+              Tauri Desktop App (user's computer)
+```
+
+## Installation
+
+```bash
+cd ~/.openclaw/extensions/
+git clone https://github.com/ezshine/clawplugin-waifusmy.git
+cd clawplugin-waifusmy
+npm install
+```
+
+## Configuration
+
+Add the following to your OpenClaw configuration file (`~/.openclaw/config.yaml` or similar):
+
+```yaml
+channels:
+  waifusmy:
+    enabled: true
+    api_key: "waifu_key_xxxxxx"                           # Your WaifusMy API key
+    relay_url: "wss://waifus-relay.ezshine.workers.dev/ws"  # Optional, has default
+```
+
+## Features
+
+- **WebSocket Connection**: Maintains persistent connection to WaifusMy relay server
+- **Automatic Reconnection**: Exponential on backoff reconnection disconnect
+- **Heartbeat**: Regular ping/pong to keep connection alive
+- **Message Forwarding**: 
+  - Receives messages from WaifusMy desktop app
+  - Sends AI responses back to the app
+- **Simple DM**: Direct message communication (no group support yet)
+
+## Requirements
+
+- OpenClaw instance
+- WaifusMy desktop application with API key
+- Network access to `wss://api.waifus.my`
+
+## Development
+
+### Project Structure
+
+```
+openclaw-channel-waifusmy/
+├── package.json          # NPM package configuration
+├── tsconfig.json         # TypeScript configuration
+├── index.ts              # Plugin entry point
+├── src/
+│   ├── channel.ts        # Main channel implementation
+│   └── types.ts          # TypeScript type definitions
+└── README.md             # This file
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Testing
+
+The plugin can be tested using a WebSocket client to simulate the relay server:
+
+```bash
+# Using wscat
+npm install -g wscat
+wscat -c wss://api.waifus.my/api/channel/ws
+
+# Then send auth message:
+{"type": "auth", "api_key": "your_key", "role": "plugin"}
+```
+
+## WebSocket Protocol
+
+### Outbound (Plugin → Server)
+
+**Authentication:**
+```json
+{
+  "type": "auth",
+  "api_key": "waifu_key_xxx",
+  "role": "app"
+}
+```
+
+**Send Message:**
+```json
+{
+  "type": "message",
+  "id": "uuid",
+  "text": "AI response",
+  "ts": 1739577601000
+}
+```
+
+**Heartbeat:**
+```json
+{ "type": "ping" }
+```
+
+### Inbound (Server → Plugin)
+
+**Auth Success:**
+```json
+{
+  "type": "auth_ok",
+  "peer_online": true
+}
+```
+
+**Auth Error:**
+```json
+{
+  "type": "auth_error",
+  "error": "Invalid API key"
+}
+```
+
+**User Message:**
+```json
+{
+  "type": "message",
+  "id": "msg_uuid",
+  "text": "User's message",
+  "ts": 1739577600000
+}
+```
+
+**Peer Status:**
+```json
+{
+  "type": "peer_status",
+  "online": true/false
+}
+```
+
+**Heartbeat Response:**
+```json
+{ "type": "pong" }
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,21 @@
+/**
+ * WaifusMy Channel Plugin Entry Point
+ *
+ * Registers the WaifusMy channel plugin with OpenClaw.
+ */
+
+import type { ChannelPlugin, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { waifusmyPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "waifusmy",
+  name: "WaifusMy",
+  description: "OpenClaw channel plugin for WaifusMy desktop companion app",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    api.registerChannel({ plugin: waifusmyPlugin as ChannelPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "waifusmy",
+  "channels": ["waifusmy"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@ezshine/waifusmy",
+  "version": "1.0.0",
+  "description": "OpenClaw channel plugin for WaifusMy desktop companion app",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json"
+  ],
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.0.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/channel.ts

@@ -0,0 +1,469 @@
+/**
+ * WaifusMy Channel Implementation
+ *
+ * Connects OpenClaw to WaifusMy desktop companion app via WebSocket relay server.
+ */
+
+import type {
+  ChannelPlugin,
+  ChannelMeta,
+  ChannelCapabilities,
+  ChannelId,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk";
+import { getChatChannelMeta, buildChannelConfigSchema, DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type {
+  WaifusMyConfig,
+  WaifusMyInboundMessage,
+  WaifusMyOutboundMessage,
+  WaifusMyMessage,
+  WaifusMyAuth,
+  WaifusMyAuthOk,
+  WaifusMyAuthError,
+  WaifusMyPeerStatus,
+  ResolvedWaifusMyAccount,
+} from "./types.js";
+import { WaifusMyConfigSchema } from "./types.js";
+
+// Channel metadata
+const meta: ChannelMeta = getChatChannelMeta("waifusmy");
+
+// Global runtime reference
+let waifusmyRuntime: WaifusMyRuntime | null = null;
+
+// Runtime interface
+interface WaifusMyRuntime {
+  account: ResolvedWaifusMyAccount | null;
+  ws: WebSocket | null;
+  reconnectAttempts: number;
+  maxReconnectAttempts: number;
+  reconnectDelay: number;
+  maxReconnectDelay: number;
+  connected: boolean;
+  authenticated: boolean;
+  peerOnline: boolean;
+  messageHandler: ((msg: WaifusMyMessage) => void) | null;
+  abortSignal: AbortSignal | null;
+}
+
+// Get runtime or create new one
+function getRuntime(): WaifusMyRuntime {
+  if (!waifusmyRuntime) {
+    waifusmyRuntime = {
+      account: null,
+      ws: null,
+      reconnectAttempts: 0,
+      maxReconnectAttempts: 10,
+      reconnectDelay: 1000,
+      maxReconnectDelay: 30000,
+      connected: false,
+      authenticated: false,
+      peerOnline: false,
+      messageHandler: null,
+      abortSignal: null,
+    };
+  }
+  return waifusmyRuntime;
+}
+
+// Reset runtime
+function resetRuntime(): void {
+  const runtime = getRuntime();
+  if (runtime.ws) {
+    runtime.ws.close();
+    runtime.ws = null;
+  }
+  runtime.connected = false;
+  runtime.authenticated = false;
+  runtime.reconnectAttempts = 0;
+  runtime.reconnectDelay = 1000;
+}
+
+// Set message handler (called from gateway)
+export function setWaifusMyMessageHandler(
+  handler: (msg: WaifusMyMessage) => void
+): void {
+  const runtime = getRuntime();
+  runtime.messageHandler = handler;
+}
+
+// Set abort signal
+export function setWaifusMyAbortSignal(signal: AbortSignal): void {
+  const runtime = getRuntime();
+  runtime.abortSignal = signal;
+  signal.addEventListener("abort", () => {
+    console.log("[waifusmy] Abort signal received, closing connection");
+    resetRuntime();
+  });
+}
+
+// WebSocket connection
+function connectWebSocket(account: ResolvedWaifusMyAccount): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const runtime = getRuntime();
+    runtime.account = account;
+
+    console.log(`[waifusmy] Connecting to ${account.config.relay_url}`);
+
+    try {
+      runtime.ws = new WebSocket(account.config.relay_url);
+
+      runtime.ws.onopen = () => {
+        console.log("[waifusmy] WebSocket connected");
+        runtime.connected = true;
+        runtime.reconnectAttempts = 0;
+        runtime.reconnectDelay = 1000;
+
+        // Send authentication
+        const authMsg: WaifusMyAuth = {
+          type: "auth",
+          api_key: account.config.api_key,
+          role: "app",
+        };
+        runtime.ws?.send(JSON.stringify(authMsg));
+        console.log("[waifusmy] Sent auth message");
+      };
+
+      runtime.ws.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data) as WaifusMyInboundMessage;
+          handleInboundMessage(data);
+        } catch (err) {
+          console.error("[waifusmy] Failed to parse message:", err);
+        }
+      };
+
+      runtime.ws.onerror = (error) => {
+        console.error("[waifusmy] WebSocket error:", error);
+      };
+
+      runtime.ws.onclose = () => {
+        console.log("[waifusmy] WebSocket closed");
+        runtime.connected = false;
+        runtime.authenticated = false;
+
+        // Attempt reconnection if not aborted
+        if (!runtime.abortSignal?.aborted) {
+          attemptReconnect(account);
+        }
+      };
+
+      resolve();
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+// Handle inbound messages
+function handleInboundMessage(msg: WaifusMyInboundMessage): void {
+  const runtime = getRuntime();
+
+  switch (msg.type) {
+    case "auth_ok":
+      console.log("[waifusmy] Authentication successful, peer online:", msg.peer_online);
+      runtime.authenticated = true;
+      runtime.peerOnline = msg.peer_online;
+      break;
+
+    case "auth_error":
+      console.error("[waifusmy] Authentication failed:", msg.error);
+      runtime.authenticated = false;
+      break;
+
+    case "message":
+      console.log("[waifusmy] Received message:", msg.id, msg.text.substring(0, 50));
+      // Forward to message handler for gateway processing
+      if (runtime.messageHandler) {
+        runtime.messageHandler(msg);
+      }
+      break;
+
+    case "peer_status":
+      console.log("[waifusmy] Peer status changed, online:", msg.online);
+      runtime.peerOnline = msg.online;
+      break;
+
+    case "pong":
+      // Heartbeat response received
+      break;
+
+    default:
+      console.log("[waifusmy] Unknown message type:", (msg as any).type);
+  }
+}
+
+// Exponential backoff reconnection
+function attemptReconnect(account: ResolvedWaifusMyAccount): void {
+  const runtime = getRuntime();
+
+  if (runtime.reconnectAttempts >= runtime.maxReconnectAttempts) {
+    console.error("[waifusmy] Max reconnection attempts reached");
+    return;
+  }
+
+  runtime.reconnectAttempts++;
+  const delay = Math.min(
+    runtime.reconnectDelay * Math.pow(2, runtime.reconnectAttempts - 1),
+    runtime.maxReconnectDelay
+  );
+
+  console.log(
+    `[waifusmy] Reconnecting in ${delay}ms (attempt ${runtime.reconnectAttempts}/${runtime.maxReconnectAttempts})`
+  );
+
+  setTimeout(() => {
+    if (!runtime.abortSignal?.aborted) {
+      connectWebSocket(account).catch((err) => {
+        console.error("[waifusmy] Reconnection failed:", err);
+      });
+    }
+  }, delay);
+}
+
+// Send outbound message
+export async function sendWaifusMyMessage(text: string): Promise<{ channel: string; messageId: string }> {
+  const runtime = getRuntime();
+
+  if (!runtime.ws || !runtime.connected || !runtime.authenticated) {
+    throw new Error("WaifusMy not connected or authenticated");
+  }
+
+  const message: WaifusMyMessage = {
+    type: "message",
+    id: crypto.randomUUID(),
+    text,
+    ts: Date.now(),
+  };
+
+  runtime.ws.send(JSON.stringify(message));
+  console.log("[waifusmy] Sent message:", message.id);
+
+  return { channel: "waifusmy", messageId: message.id };
+}
+
+// Start heartbeat ping
+let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+
+function startHeartbeat(): void {
+  if (heartbeatInterval) {
+    clearInterval(heartbeatInterval);
+  }
+
+  heartbeatInterval = setInterval(() => {
+    const runtime = getRuntime();
+    if (runtime.ws && runtime.connected) {
+      runtime.ws.send(JSON.stringify({ type: "ping" }));
+    }
+  }, 30000); // Ping every 30 seconds
+}
+
+function stopHeartbeat(): void {
+  if (heartbeatInterval) {
+    clearInterval(heartbeatInterval);
+    heartbeatInterval = null;
+  }
+}
+
+// The channel plugin
+export const waifusmyPlugin: ChannelPlugin<ResolvedWaifusMyAccount> = {
+  id: "waifusmy",
+  meta: {
+    ...meta,
+    id: "waifusmy" as ChannelId,
+    label: "WaifusMy",
+    selectionLabel: "WaifusMy Desktop Companion",
+    detailLabel: "WaifusMy",
+    docsPath: "/channels/waifusmy",
+    docsLabel: "waifusmy",
+    blurb: "Connect to WaifusMy desktop companion app",
+    systemImage: "desktopcomputer",
+    quickstartAllowFrom: false,
+  },
+  capabilities: {
+    chatTypes: ["direct"],
+    reactions: false,
+    threads: false,
+    media: false,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.waifusmy"] },
+  configSchema: buildChannelConfigSchema(WaifusMyConfigSchema),
+  config: {
+    listAccountIds: (_cfg) => [DEFAULT_ACCOUNT_ID],
+    resolveAccount: (cfg, accountId) => {
+      const waifusmyConfig = cfg.channels?.waifusmy as WaifusMyConfig | undefined;
+      const resolvedId = accountId ?? DEFAULT_ACCOUNT_ID;
+
+      if (!waifusmyConfig) {
+        return {
+          accountId: resolvedId,
+          name: "WaifusMy",
+          enabled: false,
+          config: { enabled: false, api_key: "", relay_url: "wss://waifus-relay.ezshine.workers.dev/ws" },
+          apiKey: "",
+          relayUrl: "wss://waifus-relay.ezshine.workers.dev/ws",
+          tokenSource: "none" as const,
+        };
+      }
+
+      return {
+        accountId: resolvedId,
+        name: "WaifusMy",
+        enabled: waifusmyConfig.enabled ?? true,
+        config: waifusmyConfig,
+        apiKey: waifusmyConfig.api_key ?? "",
+        relayUrl: waifusmyConfig.relay_url ?? "wss://waifus-relay.ezshine.workers.dev/ws",
+        tokenSource: waifusmyConfig.api_key ? ("config" as const) : ("none" as const),
+      };
+    },
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    setAccountEnabled: ({ cfg, accountId, enabled }) => {
+      const current = (cfg.channels?.waifusmy ?? {}) as Partial<WaifusMyConfig>;
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          waifusmy: {
+            ...current,
+            enabled,
+          },
+        },
+      };
+    },
+    deleteAccount: ({ cfg }) => {
+      const { waifusmy: _waifusmy, ...restChannels } = cfg.channels ?? {};
+      return {
+        ...cfg,
+        channels: restChannels,
+      };
+    },
+    isConfigured: (account) => {
+      return Boolean(account.config.api_key?.trim());
+    },
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.config.api_key?.trim()),
+      tokenSource: account.tokenSource,
+    }),
+    resolveAllowFrom: () => [],
+    formatAllowFrom: ({ allowFrom }) => allowFrom,
+  },
+  security: {
+    resolveDmPolicy: () => ({
+      policy: "open" as const,
+      allowFrom: [],
+      policyPath: "channels.waifusmy.dmPolicy",
+      allowFromPath: "channels.waifusmy.",
+      approveHint: undefined,
+      normalizeEntry: (raw) => raw,
+    }),
+    collectWarnings: () => [],
+  },
+  outbound: {
+    deliveryMode: "direct",
+    sendText: async ({ text }) => {
+      return sendWaifusMyMessage(text);
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      connected: snapshot.runtime?.connected ?? false,
+      authenticated: snapshot.runtime?.authenticated ?? false,
+      peerOnline: snapshot.runtime?.peerOnline ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+    }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.config.api_key?.trim()),
+      tokenSource: account.tokenSource,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      runtime: {
+        connected: waifusmyRuntime?.connected ?? false,
+        authenticated: waifusmyRuntime?.authenticated ?? false,
+        peerOnline: waifusmyRuntime?.peerOnline ?? false,
+      },
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+
+      console.log(`[waifusmy] Starting gateway for account: ${account.accountId}`);
+
+      if (!account.config.api_key?.trim()) {
+        throw new Error("WaifusMy API key not configured");
+      }
+
+      // Set abort signal
+      setWaifusMyAbortSignal(ctx.abortSignal);
+
+      // Set message handler to forward to gateway
+      setWaifusMyMessageHandler((msg) => {
+        // Create inbound message for gateway
+        ctx.log?.info(`[waifusmy] Processing inbound message: ${msg.id}`);
+
+        // The message handler should inject into gateway's message pipeline
+        // This is typically done via runtime.handleInboundMessage or similar
+        if (ctx.runtime?.onInboundMessage) {
+          ctx.runtime.onInboundMessage({
+            channel: "waifusmy",
+            messageId: msg.id,
+            text: msg.text,
+            senderId: "user",
+            timestamp: msg.ts,
+            chatType: "direct",
+          });
+        }
+      });
+
+      // Connect to WebSocket
+      await connectWebSocket(account);
+      startHeartbeat();
+
+      ctx.log?.info("[waifusmy] Gateway started successfully");
+
+      return {
+        running: true,
+        mode: "websocket",
+      };
+    },
+    logoutAccount: async ({ accountId, cfg }) => {
+      stopHeartbeat();
+      resetRuntime();
+
+      const { waifusmy: _waifusmy, ...restChannels } = cfg.channels ?? {};
+      const newCfg = {
+        ...cfg,
+        channels: restChannels,
+      };
+
+      return {
+        cleared: true,
+        loggedOut: true,
+      };
+    },
+  },
+};
+
+// Export types for external use
+export type { WaifusMyConfig, WaifusMyMessage };

package/src/types.ts

@@ -0,0 +1,95 @@
+/**
+ * WaifusMy Channel Types
+ */
+
+import type { z } from "zod";
+import { z } from "zod";
+
+// WebSocket message types from the relay server
+export const WaifusMyAuthSchema = z.object({
+  type: z.literal("auth"),
+  api_key: z.string(),
+  role: z.literal("plugin"),
+});
+
+export const WaifusMyAuthOkSchema = z.object({
+  type: z.literal("auth_ok"),
+  peer_online: z.boolean(),
+});
+
+export const WaifusMyAuthErrorSchema = z.object({
+  type: z.literal("auth_error"),
+  error: z.string(),
+});
+
+export const WaifusMyMessageSchema = z.object({
+  type: z.literal("message"),
+  id: z.string(),
+  text: z.string(),
+  ts: z.number(),
+});
+
+export const WaifusMyPeerStatusSchema = z.object({
+  type: z.literal("peer_status"),
+  online: z.boolean(),
+});
+
+export const WaifusMyPingSchema = z.object({
+  type: z.literal("ping"),
+});
+
+export const WaifusMyPongSchema = z.object({
+  type: z.literal("pong"),
+});
+
+export type WaifusMyAuth = z.infer<typeof WaifusMyAuthSchema>;
+export type WaifusMyAuthOk = z.infer<typeof WaifusMyAuthOkSchema>;
+export type WaifusMyAuthError = z.infer<typeof WaifusMyAuthErrorSchema>;
+export type WaifusMyMessage = z.infer<typeof WaifusMyMessageSchema>;
+export type WaifusMyPeerStatus = z.infer<typeof WaifusMyPeerStatusSchema>;
+export type WaifusMyPing = z.infer<typeof WaifusMyPingSchema>;
+export type WaifusMyPong = z.infer<typeof WaifusMyPongSchema>;
+
+export type WaifusMyInboundMessage =
+  | WaifusMyAuthOk
+  | WaifusMyAuthError
+  | WaifusMyMessage
+  | WaifusMyPeerStatus
+  | WaifusMyPong;
+
+export type WaifusMyOutboundMessage =
+  | WaifusMyAuth
+  | WaifusMyMessage
+  | WaifusMyPing;
+
+// Configuration schema
+export const WaifusMyConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  api_key: z.string().min(1, "API key is required"),
+  relay_url: z.string().url().default("wss://waifus-relay.ezshine.workers.dev/ws"),
+});
+
+export type WaifusMyConfig = z.infer<typeof WaifusMyConfigSchema>;
+
+// Resolved account type
+export interface ResolvedWaifusMyAccount {
+  accountId: string;
+  name: string;
+  enabled: boolean;
+  config: WaifusMyConfig;
+  apiKey: string;
+  relayUrl: string;
+  tokenSource: "config" | "none";
+}
+
+// Runtime state
+export interface WaifusMyRuntime {
+  ws: WebSocket | null;
+  reconnectAttempts: number;
+  maxReconnectAttempts: number;
+  reconnectDelay: number;
+  maxReconnectDelay: number;
+  connected: boolean;
+  authenticated: boolean;
+  peerOnline: boolean;
+}