@omnixal/openclaw-nats-plugin 0.2.10 → 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.10",
+  "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/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/gateway-client.service.ts

@@ -3,14 +3,11 @@ 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 {
@@ -266,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;
   }
 }