@omnixal/openclaw-nats-plugin 0.2.11 → 0.2.13

package/PLUGIN.md

@@ -94,6 +94,8 @@ Environment variables (auto-configured by setup):
 - `NATS_SIDECAR_URL` — Sidecar URL (default: `http://127.0.0.1:3104`)
 - `NATS_PLUGIN_API_KEY` — API key for sidecar auth (auto-generated)
 - `NATS_SERVERS` — NATS server URL (default: `nats://127.0.0.1:4222`)
+- `OPENCLAW_GATEWAY_URL` — Gateway HTTP URL (default: `http://127.0.0.1:18789`)
+- `OPENCLAW_HOOK_TOKEN` — Webhook token for event delivery to agent session (from `hooks.token` in gateway config)
 
 ## Requirements
 

package/cli/bun-setup.ts

@@ -7,7 +7,7 @@ import {
 } from './paths';
 import { downloadNatsServer, NATS_VERSION } from './download-nats';
 import { writeNatsConfig } from './nats-config';
-import { generateApiKey, getExistingApiKey, writeEnvVariables } from './env-writer';
+import { generateApiKey, getExistingApiKey, getExistingHookToken, writeEnvVariables } from './env-writer';
 import {
   getServiceManager, generateSystemdUnit, generateLaunchdPlist,
   installSystemdUnit, installLaunchdPlist, startService, stopService,
@@ -48,24 +48,27 @@ export async function bunSetup(): Promise<void> {
 
   // 6. Reuse existing API key or generate new one
   const apiKey = getExistingApiKey() ?? generateApiKey();
+  const hookToken = getExistingHookToken() ?? generateApiKey();
 
   // 7. Write env variables (to OpenClaw .env for hooks, and sidecar .env for the service)
   const envVars: Record<string, string> = {
     NATS_SIDECAR_URL: 'http://127.0.0.1:3104',
     NATS_PLUGIN_API_KEY: apiKey,
     NATS_SERVERS: 'nats://127.0.0.1:4222',
-    OPENCLAW_WS_URL: 'ws://127.0.0.1:18789',
+    OPENCLAW_GATEWAY_URL: 'http://127.0.0.1:18789',
+    OPENCLAW_HOOK_TOKEN: hookToken,
   };
   writeEnvVariables(envVars);
 
   // Write .env into sidecar dir so loadDotEnv picks it up
-  // Explicit localhost values override any container-level env (e.g. OPENCLAW_WS_URL=ws://openclaw:...)
+  // Explicit localhost values override any container-level env
   const sidecarEnv = [
     `PORT=3104`,
     `DB_PATH=${join(DATA_DIR, 'nats-sidecar.db')}`,
     `NATS_SERVERS=nats://127.0.0.1:4222`,
     `NATS_PLUGIN_API_KEY=${apiKey}`,
-    `OPENCLAW_WS_URL=ws://127.0.0.1:18789`,
+    `OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789`,
+    `OPENCLAW_HOOK_TOKEN=${hookToken}`,
   ].join('\n');
   writeFileSync(join(SIDECAR_DIR, '.env'), sidecarEnv, 'utf-8');
 

package/cli/docker-setup.ts

@@ -2,7 +2,7 @@ import { mkdirSync, cpSync, writeFileSync, existsSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { PLUGIN_DIR, DOCKER_DIR, DASHBOARD_DIR, STATE_FILE, type PluginState } from './paths';
-import { generateApiKey, getExistingApiKey, writeEnvVariables } from './env-writer';
+import { generateApiKey, getExistingApiKey, getExistingHookToken, writeEnvVariables } from './env-writer';
 
 /**
  * Try to copy dashboard dist into a running OpenClaw container's volume.
@@ -58,9 +58,10 @@ export async function dockerSetup(): Promise<void> {
   cpSync(templateDir, DOCKER_DIR, { recursive: true });
   cpSync(sidecarSrc, join(DOCKER_DIR, 'sidecar'), { recursive: true });
 
-  // 2. Reuse existing API key or generate new one
+  // 2. Reuse existing API key and hook token or generate new ones
   const apiKey = getExistingApiKey() ?? generateApiKey();
-  writeFileSync(join(DOCKER_DIR, '.env'), `NATS_PLUGIN_API_KEY=${apiKey}\n`);
+  const hookToken = getExistingHookToken() ?? generateApiKey();
+  writeFileSync(join(DOCKER_DIR, '.env'), `NATS_PLUGIN_API_KEY=${apiKey}\nOPENCLAW_HOOK_TOKEN=${hookToken}\n`);
 
   // 3. Build and start
   console.log('Building and starting containers...');
@@ -71,6 +72,8 @@ export async function dockerSetup(): Promise<void> {
     NATS_SIDECAR_URL: 'http://127.0.0.1:3104',
     NATS_PLUGIN_API_KEY: apiKey,
     NATS_SERVERS: 'nats://127.0.0.1:4222',
+    OPENCLAW_GATEWAY_URL: 'http://127.0.0.1:18789',
+    OPENCLAW_HOOK_TOKEN: hookToken,
   });
 
   // 5. Copy dashboard dist into OpenClaw container (host→container bridge)

package/cli/env-writer.ts

@@ -14,6 +14,13 @@ export function getExistingApiKey(): string | null {
   return match?.[1]?.trim() || null;
 }
 
+export function getExistingHookToken(): string | null {
+  if (!existsSync(OPENCLAW_ENV)) return null;
+  const content = readFileSync(OPENCLAW_ENV, 'utf-8');
+  const match = content.match(/^OPENCLAW_HOOK_TOKEN=(.+)$/m);
+  return match?.[1]?.trim() || null;
+}
+
 export function mergeEnvContent(
   existingContent: string,
   variables: Record<string, string>,

package/docker/docker-compose.yml

@@ -29,8 +29,9 @@ services:
       - PORT=3104
       - DB_PATH=/app/data/nats-sidecar.db
       - NATS_SERVERS=nats://nats:4222
-      - OPENCLAW_WS_URL=ws://host.docker.internal:18789
+      - OPENCLAW_GATEWAY_URL=http://host.docker.internal:18789
       - NATS_PLUGIN_API_KEY=${NATS_PLUGIN_API_KEY}
+      - OPENCLAW_HOOK_TOKEN=${OPENCLAW_HOOK_TOKEN}
     volumes:
       - sidecar-data:/app/data
     restart: unless-stopped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnixal/openclaw-nats-plugin",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "NATS JetStream event-driven plugin for OpenClaw",
   "license": "MIT",
   "type": "module",

package/sidecar/bun.lock

@@ -10,6 +10,7 @@
         "@onebun/envs": "^0.2.2",
         "@onebun/logger": "^0.2.1",
         "@onebun/nats": "^0.2.6",
+        "@onebun/requests": "^0.2.1",
         "arktype": "^2.2.0",
         "ulid": "^2.3.0",
       },

package/sidecar/package.json

@@ -11,7 +11,7 @@
     "typecheck": "bunx tsc --noEmit",
     "db:generate": "bunx onebun-drizzle generate",
     "db:push": "bunx onebun-drizzle push",
-    "db:studio": "bunx onebun-drizzle studio",
+    "db:studio": "bunx onebun-drizzle studio"
   },
   "dependencies": {
     "@onebun/core": "^0.2.15",
@@ -19,6 +19,7 @@
     "@onebun/envs": "^0.2.2",
     "@onebun/logger": "^0.2.1",
     "@onebun/nats": "^0.2.6",
+    "@onebun/requests": "^0.2.1",
     "arktype": "^2.2.0",
     "ulid": "^2.3.0"
   },

package/sidecar/src/config.ts

@@ -16,8 +16,8 @@ export const envSchema = {
     maxReconnectAttempts: Env.number({ default: -1, env: 'NATS_MAX_RECONNECT_ATTEMPTS' }),
   },
   gateway: {
-    wsUrl: Env.string({ default: 'ws://localhost:18789', env: 'OPENCLAW_WS_URL' }),
-    token: Env.string({ default: '', env: 'OPENCLAW_DEVICE_TOKEN' }),
+    url: Env.string({ default: 'http://localhost:18789', env: 'OPENCLAW_GATEWAY_URL' }),
+    hookToken: Env.string({ default: '', env: 'OPENCLAW_HOOK_TOKEN' }),
   },
   consumer: {
     name: Env.string({ default: 'openclaw-main', env: 'NATS_CONSUMER_NAME' }),

package/sidecar/src/consumer/consumer.controller.ts

@@ -58,7 +58,6 @@ export class ConsumerController extends BaseController {
           try {
             const injectStart = performance.now();
             await this.gatewayClient.inject({
-              to: route.target,
               message: this.formatMessage(envelope),
               eventId: envelope.id,
             });

package/sidecar/src/gateway/gateway-client.service.ts

@@ -1,12 +1,8 @@
-import { Service, BaseService, type OnModuleInit, type OnModuleDestroy } from '@onebun/core';
-import path from 'node:path';
-import { loadOrCreateIdentity, publicKeyToBase64Url, signChallenge, type DeviceIdentity } from './device-identity';
+import { Service, BaseService, type OnModuleInit } from '@onebun/core';
+import { HttpClient, isErrorResponse } from '@onebun/requests';
 
 export interface GatewayInjectPayload {
-  /** OpenClaw session key or recipient address (maps to `to` in the send frame) */
-  to: string;
   message: string;
-  /** Internal tracking metadata — NOT sent to gateway (additionalProperties: false) */
   eventId?: string;
 }
 
@@ -21,304 +17,52 @@ export class GatewayRpcError extends Error {
   }
 }
 
-interface PendingRequest {
-  resolve: () => void;
-  reject: (err: Error) => void;
-  timer: Timer;
-}
-
-const RPC_TIMEOUT_MS = 10_000;
-
 @Service()
-export class GatewayClientService extends BaseService implements OnModuleInit, OnModuleDestroy {
-  private ws: WebSocket | null = null;
-  private connected = false;
-  private connectSent = false;
-  private reconnectAttempt = 0;
-  private reconnectTimer: Timer | null = null;
+export class GatewayClientService extends BaseService implements OnModuleInit {
+  private client!: HttpClient;
+  private configured = false;
   private requestId = 0;
-  private wsUrl!: string;
-  private token!: string;
-  private identity!: DeviceIdentity;
-  private publicKeyBase64Url!: string;
-  private challengeNonce = '';
-  private pendingRequests = new Map<string, PendingRequest>();
 
   async onModuleInit(): Promise<void> {
-    this.wsUrl = this.config.get('gateway.wsUrl');
-    this.token = this.config.get('gateway.token');
-    if (this.wsUrl && this.token) {
-      const dbPath = this.config.get('database.url');
-      const identityPath = path.join(path.dirname(dbPath), 'device-identity.json');
-      this.identity = loadOrCreateIdentity(identityPath);
-      this.publicKeyBase64Url = publicKeyToBase64Url(this.identity.publicKeyPem);
-      this.logger.info('Device identity loaded', { deviceId: this.identity.deviceId });
-      this.connect();
-    } else {
-      this.logger.warn('Gateway WebSocket not configured — skipping connection (need wsUrl + deviceToken)');
-    }
-  }
-
-  private connect(): void {
-    try {
-      this.connectSent = false;
-      this.ws = new WebSocket(this.wsUrl);
-
-      this.ws.onopen = () => {
-        this.reconnectAttempt = 0;
-        this.logger.info('Gateway WebSocket opened, waiting for connect.challenge');
-      };
-
-      this.ws.onmessage = (event) => {
-        this.handleMessage(String(event.data));
-      };
-
-      this.ws.onclose = () => {
-        this.connected = false;
-        this.connectSent = false;
-        // Reject all in-flight requests immediately — don't make callers wait for timeout
-        for (const [id, pending] of this.pendingRequests) {
-          clearTimeout(pending.timer);
-          pending.reject(new Error('Gateway WebSocket closed'));
-        }
-        this.pendingRequests.clear();
-        this.scheduleReconnect();
-      };
-
-      this.ws.onerror = () => {
-        this.logger.warn('Gateway WebSocket error');
-        this.connected = false;
-      };
-    } catch (err) {
-      this.logger.warn('Failed to connect to Gateway WebSocket', err);
-      this.scheduleReconnect();
-    }
-  }
-
-  private handleMessage(data: string): void {
-    let frame: any;
-    try {
-      frame = JSON.parse(data);
-    } catch {
-      this.logger.warn(`Failed to parse WebSocket message: ${data.slice(0, 200)}`);
-      return;
-    }
-
-    // Server challenge — respond with connect frame
-    if (frame.type === 'event' && frame.event === 'connect.challenge') {
-      this.challengeNonce = frame.payload?.nonce ?? '';
-      this.logger.debug('Received connect.challenge from server', { hasNonce: !!this.challengeNonce });
-      this.sendConnectFrame();
-      return;
-    }
-
-    // Some gateway versions send an event before challenge; treat any pre-connect event as trigger
-    if (!this.connectSent && frame.type === 'event') {
-      this.logger.debug('Received event before connect sent, sending connect frame');
-      this.sendConnectFrame();
-      return;
-    }
-
-    // Successful connect response — must be hello-ok
-    if (frame.type === 'res' && frame.ok === true) {
-      const payload = frame.payload;
-      if (payload?.type === 'hello-ok') {
-        if (!this.connected) {
-          this.connected = true;
-          const grantedScopes = payload.auth?.scopes ?? [];
-          const serverVersion = payload.server?.version ?? 'unknown';
-          this.logger.info('OpenClaw handshake complete', {
-            protocol: payload.protocol,
-            serverVersion,
-            grantedScopes,
-            connId: payload.server?.connId,
-          });
-          if (grantedScopes.length > 0 && !grantedScopes.includes('operator.write')) {
-            this.logger.error(
-              `Gateway did NOT grant operator.write scope! Granted: [${grantedScopes.join(', ')}]. ` +
-              'Message delivery will fail. Rotate the device token with --scope operator.write',
-            );
-          }
-        }
-        return;
-      }
-      // Regular RPC ok response (e.g. for inject calls)
-      this.logger.debug('Received RPC ok response', { id: frame.id });
-      this.resolvePending(frame.id);
-      return;
-    }
-
-    // Error response
-    if (frame.type === 'res' && frame.ok === false) {
-      const errorCode = frame.error?.code ?? frame.error?.errorCode ?? 'UNKNOWN';
-      const errorMessage = frame.error?.message ?? frame.error?.errorMessage ?? 'Unknown gateway error';
-      this.logger.error('Gateway RPC error', { id: frame.id, errorCode, errorMessage });
-
-      // If this is a connect error, close and reconnect
-      if (frame.id?.startsWith('connect-')) {
-        this.logger.error(`Gateway rejected connection: ${errorCode} — ${errorMessage}`);
-        this.connected = false;
-        this.connectSent = false;
-        this.ws?.close();
-        return;
-      }
-
-      this.rejectPending(frame.id, new GatewayRpcError(frame.id, String(errorCode), String(errorMessage)));
-    }
-  }
-
-  private sendConnectFrame(): void {
-    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || this.connectSent) return;
-    this.connectSent = true;
-
-    const signedAt = Date.now();
-    const scopes = ['operator.read', 'operator.write'];
-    const client = {
-      id: 'gateway-client' as const,
-      displayName: 'nats-sidecar',
-      version: '1.0.0',
-      platform: 'linux',
-      mode: 'backend' as const,
-    };
-
-    const signature = signChallenge(this.identity.privateKeyPem, {
-      deviceId: this.identity.deviceId,
-      clientId: client.id,
-      clientMode: client.mode,
-      role: 'operator',
-      scopes,
-      signedAtMs: signedAt,
-      token: this.token,
-      nonce: this.challengeNonce,
-      platform: client.platform,
-    });
-
-    this.logger.info('Sending connect frame with device identity', {
-      deviceId: this.identity.deviceId,
-    });
-
-    try {
-      this.send({
-        type: 'req',
-        id: `connect-${++this.requestId}`,
-        method: 'connect',
-        params: {
-          minProtocol: 3,
-          maxProtocol: 3,
-          client,
-          role: 'operator',
-          scopes,
-          caps: [],
-          commands: [],
-          permissions: {},
-          auth: { token: this.token },
-          device: {
-            id: this.identity.deviceId,
-            publicKey: this.publicKeyBase64Url,
-            signature,
-            signedAt,
-            nonce: this.challengeNonce,
-          },
-          locale: 'en-US',
-          userAgent: 'nats-sidecar/1.0.0',
+    const gatewayUrl = this.config.get('gateway.url');
+    const hookToken = this.config.get('gateway.hookToken');
+
+    if (gatewayUrl && hookToken) {
+      this.client = new HttpClient({
+        baseUrl: gatewayUrl,
+        timeout: 10_000,
+        auth: { type: 'bearer', token: hookToken },
+        retries: {
+          max: 2,
+          backoff: 'exponential',
+          delay: 500,
+          retryOn: [502, 503, 504],
         },
       });
-    } catch (err) {
-      this.logger.error('Failed to send connect frame', err);
-      this.connectSent = false;
-    }
-  }
-
-  private send(frame: unknown): void {
-    if (this.ws?.readyState !== WebSocket.OPEN) {
-      throw new Error('WebSocket is not open');
-    }
-    try {
-      this.ws.send(JSON.stringify(frame));
-    } catch (err) {
-      this.connected = false;
-      throw new Error(`WebSocket send failed: ${err instanceof Error ? err.message : String(err)}`);
+      this.configured = true;
+      this.logger.info('Gateway webhook configured', { url: gatewayUrl });
+    } else {
+      this.logger.warn('Gateway webhook not configured — need url + hookToken');
     }
   }
 
-  private scheduleReconnect(): void {
-    if (this.reconnectTimer) return;
-    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempt), 30_000);
-    this.reconnectAttempt++;
-    this.logger.debug(`Reconnecting to Gateway in ${delay}ms (attempt ${this.reconnectAttempt})`);
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      this.connect();
-    }, delay);
-  }
-
   async inject(payload: GatewayInjectPayload): Promise<void> {
-    if (!this.isAlive()) {
-      throw new Error('Gateway WebSocket not connected');
+    if (!this.configured) {
+      throw new Error('Gateway webhook not configured');
     }
     const id = `rpc-${++this.requestId}`;
-    const promise = this.trackRequest(id);
-    this.send({
-      type: 'req',
-      id,
-      method: 'send',
-      params: {
-        to: payload.to,
-        message: payload.message,
-        idempotencyKey: payload.eventId ?? String(this.requestId),
-      },
-    });
-    return promise;
-  }
 
-  private trackRequest(id: string): Promise<void> {
-    return new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(id);
-        reject(new Error(`Gateway RPC timeout after ${RPC_TIMEOUT_MS}ms [${id}]`));
-      }, RPC_TIMEOUT_MS);
-      this.pendingRequests.set(id, { resolve, reject, timer });
+    const response = await this.client.post('/hooks/wake', {
+      text: payload.message,
+      mode: 'now',
     });
-  }
-
-  private resolvePending(id: string): void {
-    const pending = this.pendingRequests.get(id);
-    if (pending) {
-      clearTimeout(pending.timer);
-      this.pendingRequests.delete(id);
-      pending.resolve();
-    }
-  }
 
-  private rejectPending(id: string, err: Error): void {
-    const pending = this.pendingRequests.get(id);
-    if (pending) {
-      clearTimeout(pending.timer);
-      this.pendingRequests.delete(id);
-      pending.reject(err);
+    if (isErrorResponse(response)) {
+      throw new GatewayRpcError(id, String(response.code), response.message ?? response.error);
     }
   }
 
   isAlive(): boolean {
-    return this.connected && this.ws?.readyState === WebSocket.OPEN;
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-    // Reject all pending requests
-    for (const [id, pending] of this.pendingRequests) {
-      clearTimeout(pending.timer);
-      pending.reject(new Error('Gateway client shutting down'));
-    }
-    this.pendingRequests.clear();
-    if (this.ws) {
-      this.ws.close();
-      this.ws = null;
-    }
-    this.connected = false;
-    this.connectSent = false;
+    return this.configured;
   }
 }

package/sidecar/src/health/health.service.ts

@@ -44,7 +44,7 @@ export class HealthService extends BaseService {
       },
       gateway: {
         connected: this.gateway.isAlive(),
-        url: this.config.get('gateway.wsUrl'),
+        url: this.config.get('gateway.url'),
       },
       pendingCount,
       uptimeSeconds: Math.floor((Date.now() - this.startedAt) / 1000),