clawrelay 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# clawrelay
+
+OpenClaw channel plugin that receives forwarded messages from an always-on relay proxy (ClawRelay), dispatches them through the agent pipeline, and sends responses back over WebSocket.
+
+## How it works
+
+1. Plugin starts an HTTP + WebSocket server on a configurable port (default `7600`)
+2. The relay service connects via WebSocket at `/relay/ws` with Bearer token auth
+3. Inbound messages are dispatched through the OpenClaw agent pipeline
+4. Agent responses are sent back to the relay service over the same WebSocket connection
+
+## Installation
+
+Install from npm:
+
+```bash
+openclaw plugins install clawrelay
+```
+
+Or install from a local path during development:
+
+```bash
+openclaw plugins install ./packages/relay-channel
+```
+
+Or install from a tarball:
+
+```bash
+cd packages/relay-channel && npm pack
+openclaw plugins install clawrelay-0.1.0.tgz
+```
+
+## Gateway configuration
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "channels": {
+    "relay": {
+      "accounts": {
+        "default": {
+          "authToken": "shared-secret",
+          "port": 7600
+        }
+      }
+    }
+  },
+  "plugins": {
+    "allow": ["clawrelay"],
+    "entries": {
+      "clawrelay": { "enabled": true }
+    }
+  }
+}
+```
+
+The `authToken` must match the relay service's `SANDBOX_AUTH_TOKEN`.
+
+## Verify installation
+
+```bash
+openclaw plugins list
+openclaw plugins info clawrelay
+openclaw plugins doctor
+```
+
+## Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/relay/health` | Health check — returns `{"status":"ok","ready":true}` |
+| WS | `/relay/ws` | WebSocket endpoint for relay communication (Bearer auth required) |
+
+## Source files
+
+| File | Purpose |
+|---|---|
+| `src/index.ts` | Plugin entry point and registration |
+| `src/channel.ts` | Channel definition, account lifecycle, inbound message handler |
+| `src/inbound-server.ts` | HTTP + WebSocket server |
+| `src/runtime.ts` | OpenClaw runtime accessor |
+| `src/types.ts` | Protocol and config types |
+
+## Links
+
+- [ClawRelay](https://github.com/kylemclaren/clawrelay) — relay proxy + plugin monorepo
+- [OpenClaw Plugin Docs](https://docs.openclaw.ai/tools/plugin#plugins)

package/openclaw.plugin.json

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "clawrelay",
+  "version": "0.1.0",
+  "description": "Channel relay plugin for OpenClaw — receives messages from an always-on relay proxy",
+  "main": "src/index.ts",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kylemclaren/clawrelay.git",
+    "directory": "packages/relay-channel"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "channel": {
+      "id": "relay",
+      "label": "Channel Relay",
+      "selectionLabel": "Relay (Discord/Telegram via proxy)",
+      "docsPath": "/channels/relay",
+      "blurb": "Wake-on-message proxy for Discord/Telegram via always-on relay",
+      "aliases": ["relay"]
+    },
+    "install": {
+      "npmSpec": "clawrelay",
+      "localPath": "extensions/relay-channel",
+      "defaultChoice": "npm"
+    }
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "relay",
+    "channel",
+    "discord",
+    "telegram",
+    "proxy"
+  ],
+  "author": "Snowy Road",
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  }
+}

package/src/channel.ts

@@ -0,0 +1,294 @@
+// Relay Channel Plugin Definition
+
+import type { RelayAccount, RelayInboundMessage, RelayOutboundMessage, ReplyFn } from './types.js';
+import { InboundServer } from './inbound-server.js';
+import { getRelayRuntime } from './runtime.js';
+
+const CHANNEL_ID = 'relay' as const;
+
+// Store active inbound servers per account
+const servers = new Map<string, InboundServer>();
+
+export function createRelayChannel(api: any) {
+  const logger = api.logger;
+
+  const channel = {
+    id: CHANNEL_ID,
+
+    meta: {
+      id: CHANNEL_ID,
+      label: 'Channel Relay',
+      selectionLabel: 'Relay (Discord/Telegram via proxy)',
+      docsPath: '/channels/relay',
+      blurb: 'Wake-on-message proxy for Discord/Telegram via always-on relay',
+      aliases: ['relay'],
+    },
+
+    capabilities: {
+      chatTypes: ['direct', 'group'],
+      media: {
+        images: false,
+        audio: false,
+        video: false,
+        documents: false,
+      },
+      reactions: false,
+      threads: false,
+      mentions: false,
+    },
+
+    config: {
+      listAccountIds: (cfg: any) => {
+        return Object.keys(cfg.channels?.relay?.accounts ?? {});
+      },
+
+      resolveAccount: (cfg: any, accountId?: string): RelayAccount | undefined => {
+        const accounts = cfg.channels?.relay?.accounts ?? {};
+        const id = accountId ?? 'default';
+        const account = accounts[id];
+        if (!account) return undefined;
+
+        return {
+          accountId: id,
+          authToken: account.authToken,
+          port: account.port ?? 7600,
+          enabled: account.enabled !== false,
+        };
+      },
+    },
+
+    gateway: {
+      startAccount: async (ctx: any) => {
+        const account = ctx.account as RelayAccount;
+        const accountId = account.accountId ?? 'default';
+
+        logger.info(`[clawrelay] startAccount called for ${accountId}`);
+
+        if (!account.enabled) {
+          logger.info(`[clawrelay] Account ${accountId} not enabled, skipping`);
+          return;
+        }
+
+        if (servers.has(accountId)) {
+          logger.warn(`[clawrelay] Server already running for ${accountId}, skipping`);
+          return;
+        }
+
+        const server = new InboundServer({
+          port: account.port,
+          authToken: account.authToken,
+          logger: ctx.log ?? logger,
+          onMessage: (message: RelayInboundMessage, reply: ReplyFn) => {
+            handleRelayInbound({
+              message,
+              reply,
+              account,
+              config: ctx.cfg,
+              log: ctx.log ?? logger,
+            }).catch((err) => {
+              const errMsg = err instanceof Error ? err.message : String(err);
+              (ctx.log ?? logger).error(`[clawrelay] Failed to process inbound: ${errMsg}`);
+              // Best-effort error response over WS
+              reply({
+                messageId: message.messageId,
+                content: `[Relay Plugin] Error processing message: ${errMsg}`,
+                replyToMessageId: message.messageId,
+              });
+            });
+          },
+        });
+
+        servers.set(accountId, server);
+
+        // Listen for abort signal
+        if (ctx.abortSignal) {
+          ctx.abortSignal.addEventListener('abort', () => {
+            (ctx.log ?? logger).info(`[clawrelay] Received abort signal for ${accountId}`);
+            const srv = servers.get(accountId);
+            if (srv) {
+              srv.stop();
+              servers.delete(accountId);
+            }
+          }, { once: true });
+        }
+
+        try {
+          await server.start();
+          (ctx.log ?? logger).info(`[clawrelay] Server started for ${accountId} on port ${account.port}`);
+        } catch (err) {
+          (ctx.log ?? logger).error(`[clawrelay] Failed to start server for ${accountId}: ${err}`);
+          servers.delete(accountId);
+        }
+      },
+
+      stopAccount: async (ctx: any) => {
+        const accountId = ctx.account?.accountId ?? 'default';
+        const server = servers.get(accountId);
+        if (server) {
+          await server.stop();
+          servers.delete(accountId);
+          (ctx.log ?? logger).info(`[clawrelay] Server stopped for ${accountId}`);
+        }
+      },
+    },
+
+    outbound: {
+      deliveryMode: 'direct' as const,
+
+      sendText: async ({
+        text,
+        chatId,
+        accountId,
+        cfg,
+      }: {
+        text: string;
+        chatId: string;
+        accountId?: string;
+        cfg: any;
+      }) => {
+        // Outbound via sendText is not the primary path for relay-channel.
+        // The main response path is via WebSocket reply.
+        // This exists for completeness if OpenClaw core needs to send proactively.
+        logger.warn(`[clawrelay] sendText called for chatId=${chatId} — relay-channel uses WS for responses`);
+        return { ok: false, error: 'Relay channel uses WebSocket for responses, not sendText' };
+      },
+    },
+
+    status: {
+      getHealth: (accountId: string) => {
+        const server = servers.get(accountId);
+        if (!server) {
+          return { status: 'disconnected', message: 'Server not running' };
+        }
+        return { status: 'connected', message: 'Server listening (HTTP + WS)' };
+      },
+    },
+  };
+
+  return channel;
+}
+
+
+// --- Inbound message handler using OpenClaw runtime ---
+
+function resolveSessionKey(message: RelayInboundMessage): string {
+  if (message.chatType === 'direct') {
+    return `relay:${message.platform}:dm:${message.senderId}`;
+  }
+  return `relay:${message.platform}:${message.guildId ?? 'unknown'}:${message.channelId}`;
+}
+
+function resolvePeerId(message: RelayInboundMessage): string {
+  if (message.chatType === 'direct') {
+    return `relay:${message.platform}:dm:${message.senderId}`;
+  }
+  return `relay:${message.platform}:${message.guildId ?? 'unknown'}:${message.channelId}`;
+}
+
+async function handleRelayInbound(params: {
+  message: RelayInboundMessage;
+  reply: ReplyFn;
+  account: RelayAccount;
+  config: any;
+  log: any;
+}): Promise<void> {
+  const { message, reply, account, config, log } = params;
+
+  let core;
+  try {
+    core = getRelayRuntime();
+  } catch (err) {
+    log?.error(`[clawrelay] Runtime not initialized: ${err}`);
+    return;
+  }
+
+  const peerId = resolvePeerId(message);
+
+  // Resolve agent route
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+    peer: {
+      kind: message.chatType === 'direct' ? 'direct' : 'group',
+      id: peerId,
+    },
+  });
+
+  // Resolve session store path
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+
+  // Format envelope
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+
+  const fromLabel = `${message.platform}:${message.senderName}`;
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: `relay:${message.platform}`,
+    from: fromLabel,
+    timestamp: message.timestamp,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: message.content,
+  });
+
+  // Build finalized message context
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    BodyForAgent: body,
+    RawBody: message.content,
+    CommandBody: message.content,
+    From: peerId,
+    To: peerId,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: message.chatType,
+    ConversationLabel: fromLabel,
+    SenderName: message.senderName,
+    SenderId: message.senderId,
+    GroupSubject: message.groupName ?? message.channelId,
+    Provider: CHANNEL_ID,
+    Surface: CHANNEL_ID,
+    Timestamp: message.timestamp,
+    OriginatingChannel: CHANNEL_ID,
+    OriginatingTo: peerId,
+  });
+
+  // Record inbound session
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err: unknown) => {
+      log?.error(`[clawrelay] Failed updating session meta: ${String(err)}`);
+    },
+  });
+
+  // Dispatch reply — triggers agent processing and delivers response via WS
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config,
+    dispatcherOptions: {
+      deliver: async (payload: { text?: string }) => {
+        const text = payload.text ?? '';
+        if (!text.trim()) return;
+
+        reply({
+          messageId: message.messageId,
+          content: text,
+          replyToMessageId: message.messageId,
+        });
+      },
+      onError: (err: unknown, info: { kind: string }) => {
+        log?.error(`[clawrelay] ${info.kind} reply failed: ${String(err)}`);
+      },
+    },
+  });
+
+  log?.info(`[clawrelay] Processed message ${message.messageId} from ${message.senderName}`);
+}

package/src/inbound-server.ts

@@ -0,0 +1,144 @@
+// Relay Server - HTTP health + WebSocket server for relay communication
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http';
+import { WebSocketServer, WebSocket } from 'ws';
+import type { RelayInboundMessage, RelayOutboundMessage, WsEnvelope, ReplyFn } from './types.js';
+
+export interface InboundServerOptions {
+  port: number;
+  authToken: string;
+  onMessage: (message: RelayInboundMessage, reply: ReplyFn) => void;
+  logger?: any;
+}
+
+export class InboundServer {
+  private server: Server | null = null;
+  private wss: WebSocketServer | null = null;
+  private options: InboundServerOptions;
+
+  constructor(options: InboundServerOptions) {
+    this.options = options;
+  }
+
+  start(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const server = createServer((req, res) => this.handleRequest(req, res));
+
+      // Create WebSocket server attached to the HTTP server
+      const wss = new WebSocketServer({ noServer: true });
+
+      wss.on('connection', (ws) => {
+        this.options.logger?.info('[clawrelay] WebSocket client connected');
+
+        ws.on('message', (data) => {
+          try {
+            const envelope: WsEnvelope = JSON.parse(data.toString());
+
+            if (envelope.type === 'message') {
+              const message = envelope.payload as RelayInboundMessage;
+
+              if (!message.messageId || !message.content) {
+                this.options.logger?.warn('[clawrelay] WS message missing required fields');
+                return;
+              }
+
+              // Create reply function that sends response back over this WS connection
+              const reply: ReplyFn = (response: RelayOutboundMessage) => {
+                if (ws.readyState === WebSocket.OPEN) {
+                  const responseEnvelope: WsEnvelope = { type: 'response', payload: response };
+                  ws.send(JSON.stringify(responseEnvelope));
+                } else {
+                  this.options.logger?.error(`[clawrelay] Cannot reply — WS not open (state=${ws.readyState})`);
+                }
+              };
+
+              this.options.onMessage(message, reply);
+            } else {
+              this.options.logger?.warn(`[clawrelay] Unexpected WS message type: ${(envelope as any).type}`);
+            }
+          } catch (err) {
+            this.options.logger?.error(`[clawrelay] Failed to parse WS message: ${err}`);
+          }
+        });
+
+        ws.on('close', (code, reason) => {
+          this.options.logger?.info(`[clawrelay] WebSocket client disconnected: ${code} ${reason.toString()}`);
+        });
+
+        ws.on('error', (err) => {
+          this.options.logger?.error(`[clawrelay] WebSocket error: ${err.message}`);
+        });
+      });
+
+      // Handle HTTP upgrade for WebSocket connections
+      server.on('upgrade', (req, socket, head) => {
+        const url = req.url ?? '';
+
+        if (url !== '/relay/ws') {
+          socket.destroy();
+          return;
+        }
+
+        // Verify auth token
+        const authHeader = req.headers['authorization'];
+        const expected = `Bearer ${this.options.authToken}`;
+        if (authHeader !== expected) {
+          this.options.logger?.warn('[clawrelay] WS upgrade rejected: invalid auth');
+          socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+          socket.destroy();
+          return;
+        }
+
+        wss.handleUpgrade(req, socket, head, (ws) => {
+          wss.emit('connection', ws, req);
+        });
+      });
+
+      server.on('error', reject);
+      server.listen(this.options.port, () => {
+        this.server = server;
+        this.wss = wss;
+        this.options.logger?.info(`[clawrelay] Server listening on port ${this.options.port} (HTTP + WS)`);
+        resolve();
+      });
+    });
+  }
+
+  stop(): Promise<void> {
+    return new Promise((resolve) => {
+      // Close all WebSocket connections
+      if (this.wss) {
+        for (const client of this.wss.clients) {
+          client.close();
+        }
+        this.wss.close();
+        this.wss = null;
+      }
+
+      if (!this.server) {
+        resolve();
+        return;
+      }
+      this.server.close(() => {
+        this.server = null;
+        this.options.logger?.info('[clawrelay] Server stopped');
+        resolve();
+      });
+    });
+  }
+
+  private handleRequest(req: IncomingMessage, res: ServerResponse) {
+    if (req.method === 'GET' && req.url === '/relay/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        status: 'ok',
+        ready: true,
+        wsClients: this.wss?.clients.size ?? 0,
+      }));
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Not found' }));
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// clawrelay - Channel Relay Plugin
+//
+// Receives forwarded messages from an always-on relay service and processes
+// them through the standard OpenClaw channel pipeline.
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { createRelayChannel } from './channel.js';
+import { setRelayRuntime } from './runtime.js';
+
+const plugin = {
+  id: 'clawrelay',
+  name: 'clawrelay',
+  description: 'Channel relay plugin — receives messages from an always-on relay proxy',
+  configSchema: emptyPluginConfigSchema(),
+
+  register(api: OpenClawPluginApi) {
+    const logger = api.logger;
+
+    logger.info('[clawrelay] Registering relay channel plugin');
+
+    // Store runtime for use across modules
+    setRelayRuntime(api.runtime);
+
+    // Create and register the channel
+    const channel = createRelayChannel(api);
+    api.registerChannel({ plugin: channel });
+
+    logger.info('[clawrelay] Relay channel plugin registered');
+  },
+};
+
+export default plugin;

package/src/runtime.ts

@@ -0,0 +1,16 @@
+// Relay Channel Runtime - Store PluginRuntime reference for use across modules
+
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setRelayRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getRelayRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Relay runtime not initialized");
+  }
+  return runtime;
+}

package/src/types.ts

@@ -0,0 +1,37 @@
+// Relay Channel Protocol Types
+
+export interface RelayAccount {
+  accountId: string;
+  authToken: string;
+  port: number;
+  enabled?: boolean;
+}
+
+// Inbound message from relay service -> plugin
+export interface RelayInboundMessage {
+  messageId: string;
+  platform: string;
+  channelId: string;
+  guildId?: string;
+  senderId: string;
+  senderName: string;
+  content: string;
+  chatType: 'group' | 'direct';
+  groupName?: string;
+  timestamp: number;
+}
+
+// Outbound response from plugin -> relay service
+export interface RelayOutboundMessage {
+  messageId: string;
+  content: string;
+  replyToMessageId?: string;
+}
+
+// WebSocket protocol envelope
+export type WsEnvelope =
+  | { type: 'message'; payload: RelayInboundMessage }
+  | { type: 'response'; payload: RelayOutboundMessage };
+
+// Reply function passed to message handlers
+export type ReplyFn = (response: RelayOutboundMessage) => void;