@omnixal/openclaw-nats-plugin 0.2.16 → 0.2.17

package/dashboard/src/lib/LogsPanel.svelte

@@ -2,6 +2,7 @@
   import * as Table from '$lib/components/ui/table';
   import { Badge } from '$lib/components/ui/badge';
   import { Button } from '$lib/components/ui/button';
+  import { Modal } from '$lib/components/ui/modal';
   import { type ExecutionLog, type LogFilters, getLogs } from '$lib/api';
   import { relativeAge } from '$lib/utils';
 
@@ -87,6 +88,8 @@
     }
   }
 
+  let selectedLog: ExecutionLog | null = $state(null);
+
   function parseDetail(detail: string | null): string {
     if (!detail) return '';
     try {
@@ -97,6 +100,15 @@
     }
   }
 
+  function formatDetailFull(detail: string | null): string {
+    if (!detail) return '(no detail)';
+    try {
+      return JSON.stringify(JSON.parse(detail), null, 2);
+    } catch {
+      return detail;
+    }
+  }
+
   $effect(() => {
     entityType; entityId;
     loadPage();
@@ -106,6 +118,43 @@
   let hasFilters = $derived(filterStatus !== '' || filterAction !== '' || filterSubject.trim() !== '');
 </script>
 
+{#if selectedLog}
+  <Modal
+    open={true}
+    title="Log Detail"
+    onClose={() => (selectedLog = null)}
+  >
+    {#snippet children()}
+      <div class="space-y-3">
+        <div class="grid grid-cols-2 gap-2 text-xs">
+          <div>
+            <span class="text-muted-foreground">Time:</span>
+            <span class="font-medium ml-1">{new Date(selectedLog.createdAt).toLocaleString()}</span>
+          </div>
+          <div>
+            <span class="text-muted-foreground">Action:</span>
+            <Badge variant="outline" class="ml-1">{selectedLog.action}</Badge>
+          </div>
+          <div class="col-span-2">
+            <span class="text-muted-foreground">Subject:</span>
+            <span class="font-mono font-medium ml-1">{selectedLog.subject}</span>
+          </div>
+          <div>
+            <span class="text-muted-foreground">Status:</span>
+            <Badge variant={selectedLog.success ? 'default' : 'destructive'} class="ml-1">
+              {selectedLog.success ? 'ok' : 'error'}
+            </Badge>
+          </div>
+        </div>
+        <div class="space-y-1">
+          <span class="text-xs text-muted-foreground">Payload / Detail:</span>
+          <pre class="rounded-md bg-muted p-3 text-xs font-mono overflow-auto max-h-80 whitespace-pre-wrap break-all">{formatDetailFull(selectedLog.detail)}</pre>
+        </div>
+      </div>
+    {/snippet}
+  </Modal>
+{/if}
+
 <div class="space-y-3">
   <!-- Filters -->
   <div class="flex flex-wrap items-end gap-2">
@@ -171,7 +220,7 @@
       </Table.Header>
       <Table.Body>
         {#each items as log}
-          <Table.Row>
+          <Table.Row class="cursor-pointer hover:bg-muted/50" onclick={() => (selectedLog = log)}>
             <Table.Cell class="text-xs text-muted-foreground whitespace-nowrap">
               {relativeAge(log.createdAt)}
             </Table.Cell>

package/dashboard/src/lib/RoutesPanel.svelte

@@ -17,9 +17,12 @@
 
   // Create form state
   let showForm: boolean = $state(false);
+  let formName: string = $state('');
   let formPattern: string = $state('agent.events.');
   let formTarget: string = $state('main');
   let formPriority: number = $state(5);
+  let formPayload: string = $state('');
+  let formFilter: string = $state('');
   let formError: string | null = $state(null);
   let actionError: string | null = $state(null);
   let loading: boolean = $state(false);
@@ -30,6 +33,8 @@
   let editTarget: string = $state('');
   let editPriority: number = $state(5);
   let editEnabled: boolean = $state(true);
+  let editPayload: string = $state('');
+  let editFilter: string = $state('');
   let editError: string | null = $state(null);
   let showDeleteConfirm: boolean = $state(false);
 
@@ -40,25 +45,54 @@
   }
 
   function resetForm() {
+    formName = '';
     formPattern = 'agent.events.';
     formTarget = 'main';
     formPriority = 5;
+    formPayload = '';
+    formFilter = '';
     formError = null;
     showForm = false;
   }
 
+  function parseJsonPayload(text: string): unknown | undefined {
+    const trimmed = text.trim();
+    if (!trimmed) return undefined;
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return undefined;
+    }
+  }
+
+  function formatPayload(payload: unknown): string {
+    if (payload === null || payload === undefined) return '';
+    return JSON.stringify(payload, null, 2);
+  }
+
   async function handleCreate() {
     formError = null;
     if (!isValidAgentSubject(formPattern)) {
       formError = 'Pattern must start with "agent.events." followed by at least one token and must not end with "."';
       return;
     }
+    if (formPayload.trim() && parseJsonPayload(formPayload) === undefined) {
+      formError = 'Payload must be valid JSON';
+      return;
+    }
+    if (formFilter.trim() && parseJsonPayload(formFilter) === undefined) {
+      formError = 'Filter must be valid JSON';
+      return;
+    }
     try {
       loading = true;
       await createRoute({
         pattern: formPattern,
+        name: formName.trim() || undefined,
         target: formTarget || undefined,
         priority: formPriority,
+        payload: parseJsonPayload(formPayload),
+        filter: formFilter.trim() ? (parseJsonPayload(formFilter) as any) : undefined,
       });
       resetForm();
       onRefresh();
@@ -75,6 +109,8 @@
     editTarget = route.target;
     editPriority = route.priority;
     editEnabled = route.enabled;
+    editPayload = formatPayload(route.customPayload);
+    editFilter = route.filter ? JSON.stringify(route.filter, null, 2) : '';
     editError = null;
     showDeleteConfirm = false;
   }
@@ -87,6 +123,14 @@
 
   async function handleSave() {
     if (!selectedRoute) return;
+    if (editPayload.trim() && parseJsonPayload(editPayload) === undefined) {
+      editError = 'Payload must be valid JSON';
+      return;
+    }
+    if (editFilter.trim() && parseJsonPayload(editFilter) === undefined) {
+      editError = 'Filter must be valid JSON';
+      return;
+    }
     try {
       editError = null;
       loading = true;
@@ -94,6 +138,8 @@
         target: editTarget,
         priority: editPriority,
         enabled: editEnabled,
+        payload: editPayload.trim() ? parseJsonPayload(editPayload) : null,
+        filter: editFilter.trim() ? (parseJsonPayload(editFilter) as any) : null,
       });
       closeModal();
       onRefresh();
@@ -123,7 +169,7 @@
 {#if selectedRoute}
   <Modal
     open={true}
-    title="Route: {selectedRoute.pattern}"
+    title="Route: {selectedRoute.name}"
     onClose={closeModal}
   >
     {#snippet children()}
@@ -146,7 +192,7 @@
 
         {#if showDeleteConfirm}
           <div class="rounded-md border border-destructive/50 bg-destructive/5 p-4 space-y-3">
-            <p class="text-sm">Are you sure you want to delete route <span class="font-mono font-semibold">{selectedRoute.pattern}</span>?</p>
+            <p class="text-sm">Are you sure you want to delete route <span class="font-mono font-semibold">{selectedRoute.name}</span>?</p>
             <p class="text-xs text-muted-foreground">This action cannot be undone.</p>
             <div class="flex gap-2">
               <Button variant="destructive" size="sm" onclick={handleDelete} disabled={loading}>
@@ -187,8 +233,32 @@
               </div>
             </div>
 
+            <div class="space-y-1">
+              <label class="text-xs text-muted-foreground" for="edit-payload">Custom Payload (JSON)</label>
+              <textarea
+                id="edit-payload"
+                bind:value={editPayload}
+                class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-xs font-mono resize-y min-h-16"
+                placeholder={'{"context": "value"}'}
+                rows="3"
+              ></textarea>
+            </div>
+
+            <div class="space-y-1">
+              <label class="text-xs text-muted-foreground" for="edit-filter">Filter (JSON)</label>
+              <textarea
+                id="edit-filter"
+                bind:value={editFilter}
+                class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-xs font-mono resize-y min-h-16"
+                placeholder={'{"logic": "and", "conditions": [{"field": "status", "op": "eq", "value": "active"}]}'}
+                rows="3"
+              ></textarea>
+            </div>
+
             <div class="text-xs text-muted-foreground pt-2 space-y-1">
+              <div>Pattern: <span class="font-mono font-medium text-foreground">{selectedRoute.pattern}</span></div>
               <div>Deliveries: <span class="font-medium text-foreground">{selectedRoute.deliveryCount}</span></div>
+              <div>Filtered out: <span class="font-medium text-foreground">{selectedRoute.filterDropCount}</span></div>
               <div>Last delivered: <span class="font-medium text-foreground">{selectedRoute.lastDeliveredAt ? relativeAge(new Date(selectedRoute.lastDeliveredAt).getTime()) : '\u2014'}</span></div>
               {#if selectedRoute.lastEventSubject}
                 <div>Last subject: <span class="font-mono font-medium text-foreground">{selectedRoute.lastEventSubject}</span></div>
@@ -236,15 +306,27 @@
         {#if formError}
           <div class="rounded-md bg-destructive/10 p-2 text-xs text-destructive">{formError}</div>
         {/if}
-        <div class="space-y-1">
-          <label class="text-xs text-muted-foreground" for="route-pattern">Pattern</label>
-          <input
-            id="route-pattern"
-            type="text"
-            bind:value={formPattern}
-            class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-sm"
-            placeholder="agent.events.>"
-          />
+        <div class="grid grid-cols-2 gap-3">
+          <div class="space-y-1">
+            <label class="text-xs text-muted-foreground" for="route-pattern">Pattern</label>
+            <input
+              id="route-pattern"
+              type="text"
+              bind:value={formPattern}
+              class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-sm"
+              placeholder="agent.events.>"
+            />
+          </div>
+          <div class="space-y-1">
+            <label class="text-xs text-muted-foreground" for="route-name">Name <span class="text-muted-foreground">(optional)</span></label>
+            <input
+              id="route-name"
+              type="text"
+              bind:value={formName}
+              class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-sm"
+              placeholder="auto from pattern"
+            />
+          </div>
         </div>
         <div class="grid grid-cols-2 gap-3">
           <div class="space-y-1">
@@ -269,6 +351,26 @@
             />
           </div>
         </div>
+        <div class="space-y-1">
+          <label class="text-xs text-muted-foreground" for="route-payload">Custom Payload (JSON)</label>
+          <textarea
+            id="route-payload"
+            bind:value={formPayload}
+            class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-xs font-mono resize-y min-h-16"
+            placeholder={'{"context": "value"}'}
+            rows="2"
+          ></textarea>
+        </div>
+        <div class="space-y-1">
+          <label class="text-xs text-muted-foreground" for="route-filter">Filter (JSON)</label>
+          <textarea
+            id="route-filter"
+            bind:value={formFilter}
+            class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-xs font-mono resize-y min-h-16"
+            placeholder={'{"logic": "and", "conditions": [{"field": "amount", "op": "gt", "value": 10000}]}'}
+            rows="2"
+          ></textarea>
+        </div>
         <div class="flex gap-2">
           <Button size="sm" onclick={handleCreate} disabled={loading}>
             {loading ? 'Creating...' : 'Create'}
@@ -284,6 +386,7 @@
       <Table.Root>
         <Table.Header>
           <Table.Row>
+            <Table.Head>Name</Table.Head>
             <Table.Head>Pattern</Table.Head>
             <Table.Head>Target</Table.Head>
             <Table.Head>Priority</Table.Head>
@@ -296,6 +399,12 @@
         <Table.Body>
           {#each routes as route}
             <Table.Row class="cursor-pointer hover:bg-muted/50" onclick={() => openRouteModal(route)}>
+              <Table.Cell class="font-mono text-xs">
+                {route.name}
+                {#if route.filter}
+                  <Badge variant="outline" class="ml-1 text-[10px] px-1 py-0">filter</Badge>
+                {/if}
+              </Table.Cell>
               <Table.Cell class="font-mono text-xs">{route.pattern}</Table.Cell>
               <Table.Cell>{route.target}</Table.Cell>
               <Table.Cell>

package/dashboard/src/lib/api.ts

@@ -47,12 +47,27 @@ export async function markDelivered(ids: string[]): Promise<void> {
 
 // ── Routes ──────────────────────────────────────────────────────────
 
+export interface FilterCondition {
+  field: string;
+  op: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'exists';
+  value: unknown;
+}
+
+export interface FilterExpression {
+  logic: 'and' | 'or';
+  conditions: FilterCondition[];
+}
+
 export interface EventRoute {
   id: string;
+  name: string;
   pattern: string;
   target: string;
   priority: number;
   enabled: boolean;
+  filter: FilterExpression | null;
+  filterDropCount: number;
+  customPayload: unknown;
   deliveryCount: number;
   lastDeliveredAt: string | null;
   lastEventSubject: string | null;
@@ -66,8 +81,11 @@ export async function getRoutes(): Promise<EventRoute[]> {
 
 export async function createRoute(body: {
   pattern: string;
+  name?: string;
   target?: string;
   priority?: number;
+  payload?: unknown;
+  filter?: FilterExpression;
 }): Promise<EventRoute> {
   return fetchJSON('/routes', {
     method: 'POST',
@@ -80,6 +98,8 @@ export interface UpdateRouteBody {
   target?: string;
   priority?: number;
   enabled?: boolean;
+  payload?: unknown;
+  filter?: FilterExpression | null;
 }
 
 export async function updateRoute(id: string, body: UpdateRouteBody): Promise<EventRoute> {

package/package.json

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

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

@@ -164,19 +164,31 @@ export default function (api: any) {
 
   api.registerTool({
     name: 'nats_subscribe',
-    description: 'Subscribe to events matching a pattern. Matched events will be delivered to the target session as messages.',
+    description: 'Subscribe to events matching a pattern. Matched events will be delivered to the target session as messages. Multiple subscriptions on the same pattern are possible by specifying different names with payload filters.',
     parameters: {
       type: 'object',
       properties: {
         pattern: { type: 'string', description: 'Subject pattern (exact, or wildcard with * for one level, > for all descendants)' },
+        name: { type: 'string', description: 'Unique route name (default: same as pattern). Use different names to create multiple subscriptions on the same pattern.' },
         target: { type: 'string', description: 'Session key to deliver to (default: main)' },
+        payload: { type: 'object', description: 'Additional context payload that will be merged with event data on delivery' },
+        filter: {
+          type: 'object',
+          description: 'Payload filter expression. Only events matching the filter will be delivered. Format: { logic: "and"|"or", conditions: [{ field: "dot.path", op: "eq"|"neq"|"gt"|"gte"|"lt"|"lte"|"in"|"nin"|"contains"|"exists", value: ... }] }',
+        },
       },
       required: ['pattern'],
     },
     async execute(_id: string, params: any) {
       const result = await sidecarFetch('/api/routes', {
         method: 'POST',
-        body: JSON.stringify({ pattern: params.pattern, target: params.target ?? 'main' }),
+        body: JSON.stringify({
+          pattern: params.pattern,
+          name: params.name,
+          target: params.target ?? 'main',
+          payload: params.payload,
+          filter: params.filter,
+        }),
       });
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     },
@@ -342,7 +354,7 @@ export default function (api: any) {
 
   api.registerTool({
     name: 'nats_route_update',
-    description: 'Update an existing route subscription. Can change target session, priority, or enabled status.',
+    description: 'Update an existing route subscription. Can change target session, priority, enabled status, custom payload, or filter.',
     parameters: {
       type: 'object',
       properties: {
@@ -350,6 +362,8 @@ export default function (api: any) {
         target: { type: 'string', description: 'New target session' },
         priority: { type: 'number', description: 'New priority (1-10)' },
         enabled: { type: 'boolean', description: 'Enable or disable the route' },
+        payload: { type: 'object', description: 'New custom payload to merge with event data on delivery' },
+        filter: { type: ['object', 'null'], description: 'New payload filter expression (null to clear). Format: { logic: "and"|"or", conditions: [...] }' },
       },
       required: ['id'],
     },

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

@@ -5,6 +5,7 @@ import { PendingService } from '../pending/pending.service';
 import { RouterService } from '../router/router.service';
 import { MetricsService } from '../metrics/metrics.service';
 import { LogService } from '../logs/log.service';
+import { RouteFilterService } from '../route-filter/route-filter.service';
 import type { NatsEventEnvelope } from '../publisher/envelope';
 
 @Controller('/consumer')
@@ -16,6 +17,7 @@ export class ConsumerController extends BaseController {
     private routerService: RouterService,
     private metrics: MetricsService,
     private logService: LogService,
+    private routeFilter: RouteFilterService,
   ) {
     super();
   }
@@ -55,16 +57,25 @@ export class ConsumerController extends BaseController {
       // Deliver to each matching target
       if (this.gatewayClient.isAlive()) {
         for (const route of routes) {
+          if (route.filter) {
+            const passed = this.routeFilter.evaluate(envelope.payload, route.filter);
+            if (!passed) {
+              this.logger.debug(`Event ${envelope.id} filtered out by route ${route.name} (${route.pattern})`);
+              await this.routerService.incrementFilterDropCount(route.id);
+              continue;
+            }
+          }
           try {
+            const composedPayload = this.composePayload(envelope, route);
             const injectStart = performance.now();
             await this.gatewayClient.inject({
-              message: this.formatMessage(envelope),
+              message: this.formatMessage(envelope.subject, composedPayload),
               eventId: envelope.id,
             });
             const lagMs = Math.round(performance.now() - injectStart);
             await this.routerService.recordDelivery(route.id, envelope.subject, lagMs);
             this.metrics.recordConsume(envelope.subject);
-            await this.logService.logDelivery(route.id, envelope.subject, JSON.stringify({ eventId: envelope.id, target: route.target }));
+            await this.logService.logDelivery(route.id, envelope.subject, JSON.stringify(composedPayload));
           } catch (routeErr) {
             await this.logService.logError('route', route.id, envelope.subject, routeErr);
             // Gateway rejected the request (e.g. missing scope) — store in pending, don't nack
@@ -100,7 +111,33 @@ export class ConsumerController extends BaseController {
     throw new Error('Unable to extract envelope from message');
   }
 
-  private formatMessage(envelope: NatsEventEnvelope): string {
-    return `[NATS:${envelope.subject}] ${JSON.stringify(envelope.payload)}`;
+  private composePayload(envelope: NatsEventEnvelope, route: import('../db/schema').DbEventRoute): Record<string, unknown> {
+    const eventPayload = (envelope.payload && typeof envelope.payload === 'object' && !Array.isArray(envelope.payload))
+      ? (envelope.payload as Record<string, unknown>)
+      : { data: envelope.payload };
+
+    const customPayload = (route.customPayload && typeof route.customPayload === 'object' && !Array.isArray(route.customPayload))
+      ? (route.customPayload as Record<string, unknown>)
+      : {};
+
+    let source: 'cron' | 'timer' | 'external' = 'external';
+    if ('_cron' in eventPayload) source = 'cron';
+    else if ('_timer' in eventPayload) source = 'timer';
+
+    return {
+      ...eventPayload,
+      ...customPayload,
+      _delivery: {
+        pattern: route.pattern,
+        source,
+        eventSubject: envelope.subject,
+        eventId: envelope.id,
+        deliveredAt: new Date().toISOString(),
+      },
+    };
+  }
+
+  private formatMessage(subject: string, composedPayload: Record<string, unknown>): string {
+    return `[NATS:${subject}] ${JSON.stringify(composedPayload)}`;
   }
 }

package/sidecar/src/consumer/consumer.module.ts

@@ -5,9 +5,10 @@ import { PendingModule } from '../pending/pending.module';
 import { RouterModule } from '../router/router.module';
 import { MetricsModule } from '../metrics/metrics.module';
 import { LogModule } from '../logs/log.module';
+import { RouteFilterModule } from '../route-filter/route-filter.module';
 
 @Module({
-  imports: [PreHandlersModule, PendingModule, RouterModule, MetricsModule, LogModule],
+  imports: [PreHandlersModule, PendingModule, RouterModule, MetricsModule, LogModule, RouteFilterModule],
   controllers: [ConsumerController],
 })
 export class ConsumerModule {}

package/sidecar/src/db/migrations/0008_fluffy_pestilence.sql

@@ -0,0 +1 @@
+ALTER TABLE `event_routes` ADD `custom_payload` text;

package/sidecar/src/db/migrations/0009_sour_romulus.sql

@@ -0,0 +1,6 @@
+DROP INDEX `event_routes_pattern_unique`;--> statement-breakpoint
+ALTER TABLE `event_routes` ADD `name` text NOT NULL DEFAULT '';--> statement-breakpoint
+UPDATE `event_routes` SET `name` = `pattern` WHERE `name` = '';--> statement-breakpoint
+ALTER TABLE `event_routes` ADD `filter` text;--> statement-breakpoint
+ALTER TABLE `event_routes` ADD `filter_drop_count` integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+CREATE UNIQUE INDEX `event_routes_name_idx` ON `event_routes` (`name`);