@omnixal/openclaw-nats-plugin 0.2.9 → 0.2.11

package/PLUGIN.md

@@ -53,6 +53,7 @@ Plugin hooks make lightweight HTTP calls to a NATS sidecar service for event pub
 | Subject | Trigger |
 |---|---|
 | `agent.events.gateway.startup` | Gateway starts |
+| `agent.events.gateway.stopped` | Gateway stops |
 | `agent.events.session.new` | `/new` command |
 | `agent.events.session.reset` | `/reset` command |
 | `agent.events.session.stop` | `/stop` command |
@@ -60,10 +61,13 @@ Plugin hooks make lightweight HTTP calls to a NATS sidecar service for event pub
 | `agent.events.session.ended` | Session ends |
 | `agent.events.tool.{name}.completed` | Tool succeeds |
 | `agent.events.tool.{name}.failed` | Tool fails |
+| `agent.events.message.received` | Inbound message received |
+| `agent.events.message.sent` | Message delivered |
+| `agent.events.llm.output` | LLM response received |
+| `agent.events.subagent.spawning` | Subagent about to spawn |
 | `agent.events.subagent.spawned` | Subagent created |
 | `agent.events.subagent.ended` | Subagent finished |
 | `agent.events.agent.run_ended` | Agent run completes |
-| `agent.events.message.sent` | Message delivered |
 | `agent.events.context.compacted` | Context history compressed |
 
 ## Dashboard

package/dashboard/src/lib/EventsReferenceModal.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+  import { Modal } from '$lib/components/ui/modal';
+  import * as Table from '$lib/components/ui/table';
+
+  interface Props {
+    open: boolean;
+    onClose: () => void;
+  }
+
+  let { open, onClose }: Props = $props();
+
+  const events = [
+    { subject: 'agent.events.gateway.startup', trigger: 'Gateway started', payload: '{}' },
+    { subject: 'agent.events.gateway.stopped', trigger: 'Gateway stopped', payload: '{ reason }' },
+    { subject: 'agent.events.session.new', trigger: '/new command', payload: '{ sessionKey, command }' },
+    { subject: 'agent.events.session.reset', trigger: '/reset command', payload: '{ sessionKey, command }' },
+    { subject: 'agent.events.session.stop', trigger: '/stop command', payload: '{ sessionKey, command }' },
+    { subject: 'agent.events.session.started', trigger: 'Session began', payload: '{ sessionKey, sessionId, channel }' },
+    { subject: 'agent.events.session.ended', trigger: 'Session ended', payload: '{ sessionKey, sessionId, channel }' },
+    { subject: 'agent.events.agent.run_ended', trigger: 'Agent run completed', payload: '{ sessionKey, runId, messageCount }' },
+    { subject: 'agent.events.tool.{name}.completed', trigger: 'Tool succeeded', payload: '{ sessionKey, toolName, durationMs }' },
+    { subject: 'agent.events.tool.{name}.failed', trigger: 'Tool failed', payload: '{ sessionKey, toolName, durationMs }' },
+    { subject: 'agent.events.message.received', trigger: 'Inbound message', payload: '{ from, content, metadata }' },
+    { subject: 'agent.events.message.sent', trigger: 'Message delivered', payload: '{ sessionKey, to, success, error }' },
+    { subject: 'agent.events.llm.output', trigger: 'LLM response', payload: '{ provider, model, usage }' },
+    { subject: 'agent.events.subagent.spawning', trigger: 'Subagent creating', payload: '{ childSessionKey, agentId, label, mode }' },
+    { subject: 'agent.events.subagent.spawned', trigger: 'Subagent created', payload: '{ sessionKey, subagentId, task }' },
+    { subject: 'agent.events.subagent.ended', trigger: 'Subagent finished', payload: '{ sessionKey, subagentId, result, durationMs }' },
+    { subject: 'agent.events.context.compacted', trigger: 'Context compressed', payload: '{ sessionKey }' },
+    { subject: 'agent.events.cron.*', trigger: 'Cron trigger', payload: '(user-defined)' },
+    { subject: 'agent.events.custom.*', trigger: 'Custom event', payload: '(user-defined)' },
+  ];
+</script>
+
+<Modal {open} title="Events Reference" {onClose} class="max-w-3xl">
+  <div class="max-h-[60vh] overflow-y-auto -mx-6 px-6">
+    <p class="text-xs text-muted-foreground mb-3">
+      All events published by the NATS plugin. Each event also includes a <code class="text-xs">timestamp</code> field.
+    </p>
+    <Table.Root>
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Subject</Table.Head>
+          <Table.Head>Trigger</Table.Head>
+          <Table.Head>Payload</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {#each events as ev}
+          <Table.Row>
+            <Table.Cell class="font-mono text-xs whitespace-nowrap">{ev.subject}</Table.Cell>
+            <Table.Cell class="text-xs">{ev.trigger}</Table.Cell>
+            <Table.Cell class="font-mono text-xs text-muted-foreground">{ev.payload}</Table.Cell>
+          </Table.Row>
+        {/each}
+      </Table.Body>
+    </Table.Root>
+  </div>
+</Modal>

package/dashboard/src/lib/MetricsPanel.svelte

@@ -1,15 +1,19 @@
 <script lang="ts">
   import * as Table from '$lib/components/ui/table';
   import { Badge } from '$lib/components/ui/badge';
+  import { Button } from '$lib/components/ui/button';
   import * as Card from '$lib/components/ui/card';
   import type { SubjectMetric } from '$lib/api';
   import { relativeAge } from '$lib/utils';
+  import CircleHelp from '@lucide/svelte/icons/circle-help';
+  import EventsReferenceModal from './EventsReferenceModal.svelte';
 
   interface Props {
     metrics: SubjectMetric[];
   }
 
   let { metrics }: Props = $props();
+  let showEventsRef = $state(false);
 
   let totalPublished = $derived(metrics.reduce((acc, m) => acc + m.published, 0));
   let totalConsumed = $derived(metrics.reduce((acc, m) => acc + m.consumed, 0));
@@ -17,7 +21,12 @@
 
 <Card.Root>
   <Card.Header class="pb-2">
-    <Card.Title class="text-sm font-medium">Queue Metrics</Card.Title>
+    <div class="flex items-center justify-between">
+      <Card.Title class="text-sm font-medium">Queue Metrics</Card.Title>
+      <Button variant="ghost" size="icon-sm" onclick={() => showEventsRef = true} title="Events reference">
+        <CircleHelp size={14} />
+      </Button>
+    </div>
   </Card.Header>
   <Card.Content>
     <div class="flex items-center gap-2 mb-3">
@@ -58,3 +67,5 @@
     {/if}
   </Card.Content>
 </Card.Root>
+
+<EventsReferenceModal open={showEventsRef} onClose={() => showEventsRef = false} />

package/dashboard/src/lib/components/ui/modal/modal.svelte

@@ -8,6 +8,7 @@
     onClose: () => void;
     children: Snippet;
     actions?: Snippet;
+    class?: string;
   }
 
   let {
@@ -16,6 +17,7 @@
     onClose,
     children,
     actions,
+    class: className,
   }: Props = $props();
 
   function handleKeydown(e: KeyboardEvent) {
@@ -31,7 +33,7 @@
   >
     <!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
     <div class="fixed inset-0" onclick={onClose}></div>
-    <div class="relative z-10 w-full max-w-lg rounded-lg border bg-background p-6 shadow-lg">
+    <div class="relative z-10 w-full {className ?? 'max-w-lg'} rounded-lg border bg-background p-6 shadow-lg">
       <div class="flex items-center justify-between mb-4">
         <h3 class="text-lg font-semibold">{title}</h3>
         <Button variant="ghost" size="icon-sm" onclick={onClose}>

package/package.json

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

package/plugins/nats-context-engine/index.ts

@@ -78,6 +78,52 @@ export default function (api: any) {
     }, { priority: 8 });
   }, { priority: 99 });
 
+  // ── Gateway stop ───────────────────────────────────────────────
+
+  api.on('gateway_stop', (event: any) => {
+    void publishToSidecar('agent.events.gateway.stopped', {
+      reason: event.reason,
+      timestamp: new Date().toISOString(),
+    });
+  }, { priority: 99 });
+
+  // ── Message received ─────────────────────────────────────────────
+
+  api.on('message_received', (event: any) => {
+    void publishToSidecar('agent.events.message.received', {
+      from: event.from,
+      content: event.content,
+      metadata: event.metadata,
+      timestamp: new Date().toISOString(),
+    });
+  }, { priority: 99 });
+
+  // ── LLM output ───────────────────────────────────────────────────
+
+  api.on('llm_output', (event: any) => {
+    void publishToSidecar('agent.events.llm.output', {
+      sessionKey: event.sessionId,
+      runId: event.runId,
+      provider: event.provider,
+      model: event.model,
+      usage: event.usage,
+      timestamp: new Date().toISOString(),
+    });
+  }, { priority: 99 });
+
+  // ── Subagent spawning ────────────────────────────────────────────
+
+  api.on('subagent_spawning', (event: any) => {
+    void publishToSidecar('agent.events.subagent.spawning', {
+      childSessionKey: event.childSessionKey,
+      agentId: event.agentId,
+      label: event.label,
+      mode: event.mode,
+      timestamp: new Date().toISOString(),
+    });
+    return { status: 'ok' };
+  }, { priority: 99 });
+
   // ── Agent Tools ─────────────────────────────────────────────────
 
   const SIDECAR_URL = process.env.NATS_SIDECAR_URL || 'http://127.0.0.1:3104';

package/sidecar/src/config.ts

@@ -17,7 +17,7 @@ export const envSchema = {
   },
   gateway: {
     wsUrl: Env.string({ default: 'ws://localhost:18789', env: 'OPENCLAW_WS_URL' }),
-    token: Env.string({ default: '', env: 'OPENCLAW_SIDECAR_DEVICE_TOKEN' }),
+    token: Env.string({ default: '', env: 'OPENCLAW_DEVICE_TOKEN' }),
   },
   consumer: {
     name: Env.string({ default: 'openclaw-main', env: 'NATS_CONSUMER_NAME' }),

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

@@ -58,14 +58,9 @@ export class ConsumerController extends BaseController {
           try {
             const injectStart = performance.now();
             await this.gatewayClient.inject({
-              target: route.target,
+              to: route.target,
               message: this.formatMessage(envelope),
-              metadata: {
-                source: 'nats',
-                eventId: envelope.id,
-                subject: envelope.subject,
-                priority: (ctx.enrichments['priority'] as number) ?? envelope.meta?.priority ?? 5,
-              },
+              eventId: envelope.id,
             });
             const lagMs = Math.round(performance.now() - injectStart);
             await this.routerService.recordDelivery(route.id, envelope.subject, lagMs);

package/sidecar/src/gateway/device-identity.ts

@@ -0,0 +1,146 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface DeviceIdentity {
+  deviceId: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+}
+
+interface StoredIdentity {
+  version: 1;
+  deviceId: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+  createdAtMs: number;
+}
+
+export interface SignChallengeParams {
+  deviceId: string;
+  clientId: string;
+  clientMode: string;
+  role: string;
+  scopes: string[];
+  signedAtMs: number;
+  token: string;
+  nonce: string;
+  platform?: string;
+  deviceFamily?: string;
+}
+
+/** Ed25519 SPKI DER prefix (12 bytes) before the 32-byte raw public key */
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+function base64UrlEncode(buf: Buffer): string {
+  return buf.toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/g, '');
+}
+
+/** Extract raw 32-byte Ed25519 public key from PEM-encoded SPKI */
+function derivePublicKeyRaw(publicKeyPem: string): Buffer {
+  const key = crypto.createPublicKey(publicKeyPem);
+  const spki = key.export({ type: 'spki', format: 'der' }) as Buffer;
+  if (
+    spki.length === ED25519_SPKI_PREFIX.length + 32 &&
+    spki.subarray(0, ED25519_SPKI_PREFIX.length).equals(ED25519_SPKI_PREFIX)
+  ) {
+    return spki.subarray(ED25519_SPKI_PREFIX.length);
+  }
+  return spki;
+}
+
+/** Derive deviceId as SHA-256(rawPublicKey).hex — matches OpenClaw's deriveDeviceIdFromPublicKey */
+function fingerprintPublicKey(publicKeyPem: string): string {
+  const raw = derivePublicKeyRaw(publicKeyPem);
+  return crypto.createHash('sha256').update(raw).digest('hex');
+}
+
+/** Normalize metadata for auth payload — ASCII lowercase + trim (matches OpenClaw's normalizeDeviceMetadataForAuth) */
+function normalizeMetadata(value?: string | null): string {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  if (!trimmed) return '';
+  return trimmed.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
+}
+
+/** Generate a new Ed25519 keypair and derive device identity */
+export function generateIdentity(): DeviceIdentity {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
+  const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+  const deviceId = fingerprintPublicKey(publicKeyPem);
+  return { deviceId, publicKeyPem, privateKeyPem };
+}
+
+/** Load existing device identity from file, or generate and persist a new one */
+export function loadOrCreateIdentity(filePath: string): DeviceIdentity {
+  try {
+    if (fs.existsSync(filePath)) {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      const parsed = JSON.parse(raw) as StoredIdentity;
+      if (
+        parsed?.version === 1 &&
+        typeof parsed.deviceId === 'string' &&
+        typeof parsed.publicKeyPem === 'string' &&
+        typeof parsed.privateKeyPem === 'string'
+      ) {
+        // Re-derive deviceId to handle corrupted stored IDs
+        const derivedId = fingerprintPublicKey(parsed.publicKeyPem);
+        return {
+          deviceId: derivedId,
+          publicKeyPem: parsed.publicKeyPem,
+          privateKeyPem: parsed.privateKeyPem,
+        };
+      }
+    }
+  } catch {
+    // fall through to regenerate
+  }
+
+  const identity = generateIdentity();
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const stored: StoredIdentity = {
+    version: 1,
+    deviceId: identity.deviceId,
+    publicKeyPem: identity.publicKeyPem,
+    privateKeyPem: identity.privateKeyPem,
+    createdAtMs: Date.now(),
+  };
+  fs.writeFileSync(filePath, `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600 });
+  return identity;
+}
+
+/** Get base64url-encoded raw public key (for the connect frame device.publicKey field) */
+export function publicKeyToBase64Url(publicKeyPem: string): string {
+  return base64UrlEncode(derivePublicKeyRaw(publicKeyPem));
+}
+
+/**
+ * Build v3 signature payload and sign it with Ed25519 private key.
+ * Returns base64url-encoded signature.
+ *
+ * v3 payload format: v3|deviceId|clientId|clientMode|role|scopes|signedAtMs|token|nonce|platform|deviceFamily
+ */
+export function signChallenge(privateKeyPem: string, params: SignChallengeParams): string {
+  const scopes = params.scopes.join(',');
+  const token = params.token ?? '';
+  const platform = normalizeMetadata(params.platform);
+  const deviceFamily = normalizeMetadata(params.deviceFamily);
+  const payload = [
+    'v3',
+    params.deviceId,
+    params.clientId,
+    params.clientMode,
+    params.role,
+    scopes,
+    String(params.signedAtMs),
+    token,
+    params.nonce,
+    platform,
+    deviceFamily,
+  ].join('|');
+
+  const key = crypto.createPrivateKey(privateKeyPem);
+  const sig = crypto.sign(null, Buffer.from(payload, 'utf8'), key);
+  return base64UrlEncode(sig);
+}

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

@@ -1,14 +1,13 @@
 import { Service, BaseService, type OnModuleInit, type OnModuleDestroy } from '@onebun/core';
+import path from 'node:path';
+import { loadOrCreateIdentity, publicKeyToBase64Url, signChallenge, type DeviceIdentity } from './device-identity';
 
 export interface GatewayInjectPayload {
-  target: string;
+  /** OpenClaw session key or recipient address (maps to `to` in the send frame) */
+  to: string;
   message: string;
-  metadata?: {
-    source: 'nats';
-    eventId: string;
-    subject: string;
-    priority: number;
-  };
+  /** Internal tracking metadata — NOT sent to gateway (additionalProperties: false) */
+  eventId?: string;
 }
 
 export class GatewayRpcError extends Error {
@@ -40,12 +39,20 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
   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)');
@@ -99,7 +106,8 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
 
     // Server challenge — respond with connect frame
     if (frame.type === 'event' && frame.event === 'connect.challenge') {
-      this.logger.debug('Received connect.challenge from server');
+      this.challengeNonce = frame.payload?.nonce ?? '';
+      this.logger.debug('Received connect.challenge from server', { hasNonce: !!this.challengeNonce });
       this.sendConnectFrame();
       return;
     }
@@ -162,33 +170,59 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
   private sendConnectFrame(): void {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN || this.connectSent) return;
     this.connectSent = true;
-    this.logger.info('Sending connect frame');
+
+    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: {
-          id: 'gateway-client',
-          displayName: 'nats-sidecar',
-          version: '1.0.0',
-          platform: 'linux',
-          mode: 'backend',
+        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',
         },
-        role: 'operator',
-        scopes: ['operator.read', 'operator.write'],
-        caps: [],
-        commands: [],
-        permissions: {},
-        auth: { token: this.token },
-        locale: 'en-US',
-        userAgent: 'nats-sidecar/1.0.0',
-      },
-    });
+      });
     } catch (err) {
       this.logger.error('Failed to send connect frame', err);
       this.connectSent = false;
@@ -229,10 +263,9 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
       id,
       method: 'send',
       params: {
-        target: payload.target,
+        to: payload.to,
         message: payload.message,
-        metadata: payload.metadata,
-        idempotencyKey: payload.metadata?.eventId ?? String(this.requestId),
+        idempotencyKey: payload.eventId ?? String(this.requestId),
       },
     });
     return promise;

package/sidecar/src/logs/log.repository.ts

@@ -56,7 +56,7 @@ export class LogRepository extends BaseService {
       .select({ count: sql<number>`count(*)` })
       .from(executionLogs)
       .where(this.buildWhereConditions(filters));
-    return result[0]?.count ?? 0;
+    return (result[0] as unknown as { count: number })?.count ?? 0;
   }
 
   async findRecent(limit: number = 20): Promise<DbExecutionLog[]> {

package/sidecar/src/logs/log.service.ts

@@ -58,7 +58,7 @@ export class LogService extends BaseService {
     }
   }
 
-  async logError(entityType: 'route' | 'cron', entityId: string, subject: string, error: unknown): Promise<void> {
+  async logError(entityType: 'route' | 'cron' | 'timer', entityId: string, subject: string, error: unknown): Promise<void> {
     try {
       const detail = error instanceof Error
         ? JSON.stringify({ message: error.message, stack: error.stack })

package/sidecar/src/pending/pending.repository.ts

@@ -49,7 +49,7 @@ export class PendingRepository extends BaseService {
       .select({ count: sql<number>`count(*)` })
       .from(pendingEvents)
       .where(isNull(pendingEvents.deliveredAt));
-    return result[0]?.count ?? 0;
+    return (result[0] as unknown as { count: number })?.count ?? 0;
   }
 
   async cleanup(ttlSeconds: number): Promise<number> {

package/sidecar/src/router/router.repository.ts

@@ -82,6 +82,6 @@ export class RouterRepository extends BaseService {
     const result = await this.db
       .select({ count: sql<number>`count(*)` })
       .from(eventRoutes);
-    return result[0]?.count ?? 0;
+    return (result[0] as unknown as { count: number })?.count ?? 0;
   }
 }