@omnixal/openclaw-nats-plugin 0.2.3 → 0.2.5

package/PLUGIN.md

@@ -68,14 +68,17 @@ Plugin hooks make lightweight HTTP calls to a NATS sidecar service for event pub
 
 ## Dashboard
 
-The plugin includes a web dashboard at `/nats-dashboard` on the Gateway.
+The plugin includes a web dashboard at `/nats-dashboard` on the Gateway. Auto-refreshes every 5 seconds. API calls are proxied through the Gateway (no direct sidecar access needed from the browser).
 
-It shows:
-- **Health status** — NATS server, Gateway WebSocket, and sidecar connectivity
-- **Pending events** — queued inbound events with priority and age
-- **Configuration** — streams, consumer name, dedup TTL
+Features:
+- **Health** — NATS server, Gateway, sidecar connectivity, uptime, pending queue size, stream configuration
+- **Routes** — full CRUD for event routing rules; pattern matching with `*` and `>` wildcards, priority, target session, delivery counters and lag
+- **Cron Jobs** — full CRUD, pause/resume, run-now; shows next run time, last run status, timezone support
+- **Execution Logs** — per-route and per-cron logs (deliveries, fires, errors) with pagination and filters (status, action type, subject substring)
+- **Metrics** — per-subject publish/consume counters with last activity timestamps
+- **Pending Events** — queued inbound events with priority and age
 
-The dashboard auto-refreshes every 5 seconds. API calls are proxied through the Gateway (no direct sidecar access needed from the browser).
+Click any route or cron job row to open a detail modal with editing and a logs tab.
 
 Build the dashboard (required after install):
 

package/README.md

@@ -36,7 +36,14 @@ Setup auto-detects your runtime (Bun or Docker) and configures NATS server + sid
 
 ## Dashboard
 
-Built-in web UI at `/nats-dashboard` on the Gateway. Shows NATS/Gateway/sidecar health, pending event queue, and configuration. Auto-refreshes every 5 seconds.
+Built-in web UI at `/nats-dashboard` on the Gateway. Auto-refreshes every 5 seconds.
+
+- **Health** — NATS server, Gateway, sidecar connectivity, uptime, pending queue size
+- **Routes** — create, edit, delete event routing rules (pattern matching with `*` and `>` wildcards, priority, target session)
+- **Cron Jobs** — create, edit, delete, pause/resume, run-now; shows next run time and last run status
+- **Execution Logs** — per-route and per-cron delivery/fire/error logs with pagination and filters (status, action, subject)
+- **Metrics** — per-subject publish/consume counters
+- **Pending Events** — queued inbound events with priority and age
 
 ## Architecture
 
@@ -52,6 +59,10 @@ OpenClaw Gateway
 NATS Sidecar (OneBun service, port 3104)
   ├── Publisher   → receives events via HTTP, publishes to JetStream
   ├── Consumer    → subscribes to JetStream, delivers to Gateway
+  ├── Router      → pattern-based event routing (exact, *, >)
+  ├── Scheduler   → cron job management with persistent SQLite storage
+  ├── Logs        → execution log recording (deliveries, fires, errors)
+  ├── Metrics     → per-subject publish/consume counters
   ├── Dedup       → idempotency key deduplication
   ├── Filter      → subject allowlist/blocklist
   ├── Pending     → SQLite queue for inbound events

package/dashboard/src/lib/CronPanel.svelte

@@ -3,14 +3,17 @@
   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 LogsPanel from '$lib/LogsPanel.svelte';
   import {
     type CronJob,
     createCronJob,
     deleteCronJob,
     toggleCronJob,
     runCronJobNow,
+    updateCronJob,
   } from '$lib/api';
-  import { relativeAge } from '$lib/utils';
+  import { relativeAge, isValidAgentSubject } from '$lib/utils';
 
   interface Props {
     jobs: CronJob[];
@@ -19,6 +22,7 @@
 
   let { jobs, onRefresh }: Props = $props();
 
+  // Create form
   let showForm = $state(false);
   let formName = $state('');
   let formCron = $state('0 9 * * *');
@@ -29,6 +33,17 @@
   let actionError: string | null = $state(null);
   let loading = $state(false);
 
+  // Modal state
+  let selectedJob: CronJob | null = $state(null);
+  let activeTab: 'details' | 'logs' = $state('details');
+  let editCron = $state('');
+  let editSubject = $state('');
+  let editPayload = $state('');
+  let editTimezone = $state('');
+  let editEnabled = $state(true);
+  let editError: string | null = $state(null);
+  let showDeleteConfirm = $state(false);
+
   function formatNextRun(iso: string): string {
     try {
       return new Date(iso).toLocaleString();
@@ -55,8 +70,8 @@
       return;
     }
 
-    if (!formSubject.startsWith('agent.events.')) {
-      formError = 'Subject must start with agent.events.';
+    if (!isValidAgentSubject(formSubject)) {
+      formError = 'Subject must start with "agent.events." followed by at least one token and must not end with "."';
       return;
     }
 
@@ -86,37 +101,209 @@
     }
   }
 
-  async function handleToggle(name: string) {
+  function openJobModal(job: CronJob) {
+    selectedJob = job;
+    activeTab = 'details';
+    editCron = job.expr;
+    editSubject = job.subject;
+    editPayload = job.payload ? JSON.stringify(job.payload, null, 2) : '{}';
+    editTimezone = job.timezone;
+    editEnabled = job.enabled;
+    editError = null;
+    showDeleteConfirm = false;
+  }
+
+  function closeModal() {
+    selectedJob = null;
+    editError = null;
+    showDeleteConfirm = false;
+  }
+
+  async function handleSave() {
+    if (!selectedJob) return;
+
+    if (!isValidAgentSubject(editSubject)) {
+      editError = 'Subject must start with "agent.events." followed by at least one token';
+      return;
+    }
+
+    let parsedPayload: unknown;
+    try {
+      parsedPayload = JSON.parse(editPayload);
+    } catch {
+      editError = 'Invalid JSON payload';
+      return;
+    }
+
+    try {
+      editError = null;
+      loading = true;
+      await updateCronJob(selectedJob.name, {
+        cron: editCron,
+        subject: editSubject,
+        payload: parsedPayload,
+        timezone: editTimezone,
+        enabled: editEnabled,
+      });
+      closeModal();
+      onRefresh();
+    } catch (e: any) {
+      editError = e.message;
+    } finally {
+      loading = false;
+    }
+  }
+
+  async function handleToggle(name: string, e: MouseEvent) {
+    e.stopPropagation();
     try {
       actionError = null;
       await toggleCronJob(name);
       onRefresh();
-    } catch (e: any) {
-      actionError = e.message;
+    } catch (err: any) {
+      actionError = err.message;
     }
   }
 
-  async function handleRun(name: string) {
+  async function handleRun(name: string, e: MouseEvent) {
+    e.stopPropagation();
     try {
       actionError = null;
       await runCronJobNow(name);
       onRefresh();
-    } catch (e: any) {
-      actionError = e.message;
+    } catch (err: any) {
+      actionError = err.message;
     }
   }
 
-  async function handleDelete(name: string) {
+  async function handleDelete() {
+    if (!selectedJob) return;
     try {
-      actionError = null;
-      await deleteCronJob(name);
+      editError = null;
+      loading = true;
+      await deleteCronJob(selectedJob.name);
+      closeModal();
       onRefresh();
     } catch (e: any) {
-      actionError = e.message;
+      editError = e.message;
+    } finally {
+      loading = false;
     }
   }
 </script>
 
+{#if selectedJob}
+  <Modal
+    open={true}
+    title="Cron Job: {selectedJob.name}"
+    onClose={closeModal}
+  >
+    {#snippet children()}
+      <!-- Tabs -->
+      <div class="flex gap-1 border-b mb-4">
+        <button
+          class="px-3 py-1.5 text-sm font-medium border-b-2 transition-colors {activeTab === 'details' ? 'border-primary text-foreground' : 'border-transparent text-muted-foreground hover:text-foreground'}"
+          onclick={() => (activeTab = 'details')}
+        >Details</button>
+        <button
+          class="px-3 py-1.5 text-sm font-medium border-b-2 transition-colors {activeTab === 'logs' ? 'border-primary text-foreground' : 'border-transparent text-muted-foreground hover:text-foreground'}"
+          onclick={() => (activeTab = 'logs')}
+        >Logs</button>
+      </div>
+
+      {#if activeTab === 'details'}
+        {#if editError}
+          <div class="rounded-md bg-destructive/10 p-2 text-xs text-destructive mb-3">{editError}</div>
+        {/if}
+
+        {#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 cron job <span class="font-mono font-semibold">{selectedJob.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}>
+                {loading ? 'Deleting...' : 'Confirm Delete'}
+              </Button>
+              <Button variant="outline" size="sm" onclick={() => (showDeleteConfirm = false)}>Cancel</Button>
+            </div>
+          </div>
+        {:else}
+          <div class="space-y-3">
+            <div class="space-y-1">
+              <label class="text-xs text-muted-foreground" for="edit-cron">Cron Expression</label>
+              <input
+                id="edit-cron"
+                type="text"
+                bind:value={editCron}
+                class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-sm font-mono"
+              />
+            </div>
+            <div class="space-y-1">
+              <label class="text-xs text-muted-foreground" for="edit-subject">Subject</label>
+              <input
+                id="edit-subject"
+                type="text"
+                bind:value={editSubject}
+                class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-sm font-mono"
+              />
+            </div>
+            <div class="space-y-1">
+              <label class="text-xs text-muted-foreground" for="edit-payload">Payload (JSON)</label>
+              <textarea
+                id="edit-payload"
+                bind:value={editPayload}
+                rows="3"
+                class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-sm font-mono"
+              ></textarea>
+            </div>
+            <div class="grid grid-cols-2 gap-3">
+              <div class="space-y-1">
+                <label class="text-xs text-muted-foreground" for="edit-tz">Timezone</label>
+                <input
+                  id="edit-tz"
+                  type="text"
+                  bind:value={editTimezone}
+                  class="w-full rounded-md border border-input bg-background px-3 py-1.5 text-sm"
+                />
+              </div>
+              <div class="space-y-1">
+                <label for="edit-job-enabled" class="text-xs text-muted-foreground">Enabled</label>
+                <div class="flex items-center gap-2 pt-1">
+                  <input id="edit-job-enabled" type="checkbox" bind:checked={editEnabled} />
+                  <label for="edit-job-enabled" class="text-sm">{editEnabled ? 'Active' : 'Disabled'}</label>
+                </div>
+              </div>
+            </div>
+
+            <div class="text-xs text-muted-foreground pt-2 space-y-1">
+              <div>Last run: <span class="font-medium text-foreground">{selectedJob.lastRunAt ? relativeAge(selectedJob.lastRunAt) : '\u2014'}</span></div>
+              <div>Next run: <span class="font-medium text-foreground">{selectedJob.nextRun ? formatNextRun(selectedJob.nextRun) : '\u2014'}</span></div>
+            </div>
+          </div>
+        {/if}
+      {:else}
+        <LogsPanel entityType="cron" entityId={selectedJob.id} />
+      {/if}
+    {/snippet}
+
+    {#snippet actions()}
+      {#if activeTab === 'details' && !showDeleteConfirm}
+        <div class="flex w-full justify-between">
+          <Button variant="ghost" size="sm" class="text-destructive" onclick={() => (showDeleteConfirm = true)}>
+            Delete
+          </Button>
+          <div class="flex gap-2">
+            <Button variant="outline" size="sm" onclick={closeModal}>Cancel</Button>
+            <Button size="sm" onclick={handleSave} disabled={loading}>
+              {loading ? 'Saving...' : 'Save'}
+            </Button>
+          </div>
+        </div>
+      {/if}
+    {/snippet}
+  </Modal>
+{/if}
+
 <Card.Root>
   <Card.Header class="pb-2">
     <div class="flex items-center justify-between">
@@ -207,12 +394,12 @@
             <Table.Head>Enabled</Table.Head>
             <Table.Head>Last Run</Table.Head>
             <Table.Head>Next Run</Table.Head>
-            <Table.Head class="w-40"></Table.Head>
+            <Table.Head class="w-32"></Table.Head>
           </Table.Row>
         </Table.Header>
         <Table.Body>
           {#each jobs as job}
-            <Table.Row>
+            <Table.Row class="cursor-pointer hover:bg-muted/50" onclick={() => openJobModal(job)}>
               <Table.Cell class="font-mono text-xs">{job.name}</Table.Cell>
               <Table.Cell class="font-mono">{job.expr}</Table.Cell>
               <Table.Cell class="font-mono text-xs">{job.subject}</Table.Cell>
@@ -223,27 +410,19 @@
                 </Badge>
               </Table.Cell>
               <Table.Cell class="text-xs text-muted-foreground">
-                {job.lastRunAt ? relativeAge(job.lastRunAt) : '—'}
+                {job.lastRunAt ? relativeAge(job.lastRunAt) : '\u2014'}
               </Table.Cell>
               <Table.Cell class="text-xs text-muted-foreground">
-                {job.nextRun ? formatNextRun(job.nextRun) : '—'}
+                {job.nextRun ? formatNextRun(job.nextRun) : '\u2014'}
               </Table.Cell>
               <Table.Cell>
                 <div class="flex gap-1">
-                  <Button variant="ghost" size="sm" onclick={() => handleToggle(job.name)}>
+                  <Button variant="ghost" size="sm" onclick={(e: MouseEvent) => handleToggle(job.name, e)}>
                     {job.enabled ? 'Pause' : 'Resume'}
                   </Button>
-                  <Button variant="outline" size="sm" onclick={() => handleRun(job.name)}>
+                  <Button variant="outline" size="sm" onclick={(e: MouseEvent) => handleRun(job.name, e)}>
                     Run
                   </Button>
-                  <Button
-                    variant="ghost"
-                    size="sm"
-                    class="text-destructive"
-                    onclick={() => handleDelete(job.name)}
-                  >
-                    Delete
-                  </Button>
                 </div>
               </Table.Cell>
             </Table.Row>

package/dashboard/src/lib/LogsPanel.svelte

@@ -0,0 +1,211 @@
+<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 { type ExecutionLog, type LogFilters, getLogs } from '$lib/api';
+  import { relativeAge } from '$lib/utils';
+
+  interface Props {
+    entityType: string;
+    entityId: string;
+  }
+
+  let { entityType, entityId }: Props = $props();
+
+  let items: ExecutionLog[] = $state([]);
+  let total: number = $state(0);
+  let page: number = $state(0);
+  let loading = $state(false);
+  let error: string | null = $state(null);
+
+  // Filters
+  let filterStatus: '' | 'true' | 'false' = $state('');
+  let filterAction: string = $state('');
+  let filterSubject: string = $state('');
+
+  const PAGE_SIZE = 20;
+
+  let prevEntity = $state('');
+  $effect(() => {
+    const key = `${entityType}:${entityId}`;
+    if (key !== prevEntity) {
+      prevEntity = key;
+      page = 0;
+      filterStatus = '';
+      filterAction = '';
+      filterSubject = '';
+    }
+  });
+
+  function buildFilters(): LogFilters | undefined {
+    const f: LogFilters = {};
+    if (filterStatus === 'true') f.success = true;
+    else if (filterStatus === 'false') f.success = false;
+    if (filterAction) f.action = filterAction;
+    if (filterSubject.trim()) f.subject = filterSubject.trim();
+    return Object.keys(f).length > 0 ? f : undefined;
+  }
+
+  async function loadPage() {
+    loading = true;
+    error = null;
+    try {
+      const result = await getLogs(entityType, entityId, PAGE_SIZE, page * PAGE_SIZE, buildFilters());
+      items = result.items;
+      total = result.total;
+    } catch (e: any) {
+      error = e.message;
+    } finally {
+      loading = false;
+    }
+  }
+
+  function applyFilters() {
+    page = 0;
+    loadPage();
+  }
+
+  function resetFilters() {
+    filterStatus = '';
+    filterAction = '';
+    filterSubject = '';
+    page = 0;
+    loadPage();
+  }
+
+  function prevPage() {
+    if (page > 0) {
+      page--;
+      loadPage();
+    }
+  }
+
+  function nextPage() {
+    if ((page + 1) * PAGE_SIZE < total) {
+      page++;
+      loadPage();
+    }
+  }
+
+  function parseDetail(detail: string | null): string {
+    if (!detail) return '';
+    try {
+      const parsed = JSON.parse(detail);
+      return parsed.message || parsed.target || JSON.stringify(parsed);
+    } catch {
+      return detail;
+    }
+  }
+
+  $effect(() => {
+    entityType; entityId;
+    loadPage();
+  });
+
+  let totalPages = $derived(Math.max(1, Math.ceil(total / PAGE_SIZE)));
+  let hasFilters = $derived(filterStatus !== '' || filterAction !== '' || filterSubject.trim() !== '');
+</script>
+
+<div class="space-y-3">
+  <!-- Filters -->
+  <div class="flex flex-wrap items-end gap-2">
+    <div class="space-y-1">
+      <label for="log-filter-status" class="text-xs text-muted-foreground">Status</label>
+      <select
+        id="log-filter-status"
+        bind:value={filterStatus}
+        class="rounded-md border border-input bg-background px-2 py-1 text-xs"
+      >
+        <option value="">All</option>
+        <option value="true">Success</option>
+        <option value="false">Error</option>
+      </select>
+    </div>
+    <div class="space-y-1">
+      <label for="log-filter-action" class="text-xs text-muted-foreground">Action</label>
+      <select
+        id="log-filter-action"
+        bind:value={filterAction}
+        class="rounded-md border border-input bg-background px-2 py-1 text-xs"
+      >
+        <option value="">All</option>
+        <option value="delivery">delivery</option>
+        <option value="fire">fire</option>
+        <option value="error">error</option>
+        <option value="skip">skip</option>
+      </select>
+    </div>
+    <div class="space-y-1">
+      <label for="log-filter-subject" class="text-xs text-muted-foreground">Subject</label>
+      <input
+        id="log-filter-subject"
+        type="text"
+        bind:value={filterSubject}
+        placeholder="substring..."
+        class="rounded-md border border-input bg-background px-2 py-1 text-xs w-36"
+        onkeydown={(e: KeyboardEvent) => e.key === 'Enter' && applyFilters()}
+      />
+    </div>
+    <Button variant="outline" size="sm" onclick={applyFilters} disabled={loading}>Filter</Button>
+    {#if hasFilters}
+      <Button variant="ghost" size="sm" onclick={resetFilters}>Clear</Button>
+    {/if}
+  </div>
+
+  {#if error}
+    <div class="rounded-md bg-destructive/10 p-2 text-xs text-destructive">{error}</div>
+  {/if}
+
+  {#if items.length === 0 && !loading}
+    <p class="text-xs text-muted-foreground py-2">No logs{hasFilters ? ' matching filters' : ''}</p>
+  {:else}
+    <Table.Root>
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Time</Table.Head>
+          <Table.Head>Action</Table.Head>
+          <Table.Head>Subject</Table.Head>
+          <Table.Head>Status</Table.Head>
+          <Table.Head>Detail</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {#each items as log}
+          <Table.Row>
+            <Table.Cell class="text-xs text-muted-foreground whitespace-nowrap">
+              {relativeAge(log.createdAt)}
+            </Table.Cell>
+            <Table.Cell>
+              <Badge variant="outline">{log.action}</Badge>
+            </Table.Cell>
+            <Table.Cell class="font-mono text-xs">{log.subject}</Table.Cell>
+            <Table.Cell>
+              <Badge variant={log.success ? 'default' : 'destructive'}>
+                {log.success ? 'ok' : 'error'}
+              </Badge>
+            </Table.Cell>
+            <Table.Cell class="text-xs text-muted-foreground max-w-48 truncate" title={parseDetail(log.detail)}>
+              {parseDetail(log.detail)}
+            </Table.Cell>
+          </Table.Row>
+        {/each}
+      </Table.Body>
+    </Table.Root>
+
+    <!-- Pagination -->
+    <div class="flex items-center justify-between pt-1">
+      <span class="text-xs text-muted-foreground">
+        {total} log{total === 1 ? '' : 's'}{hasFilters ? ' (filtered)' : ''}
+      </span>
+      <div class="flex items-center gap-2">
+        <Button variant="outline" size="sm" onclick={prevPage} disabled={page === 0 || loading}>
+          Prev
+        </Button>
+        <span class="text-xs text-muted-foreground">{page + 1} / {totalPages}</span>
+        <Button variant="outline" size="sm" onclick={nextPage} disabled={(page + 1) * PAGE_SIZE >= total || loading}>
+          Next
+        </Button>
+      </div>
+    </div>
+  {/if}
+</div>