@omnixal/openclaw-nats-plugin 0.1.18 → 0.2.0

package/openclaw.plugin.json

@@ -1,5 +1,6 @@
 {
   "id": "openclaw-nats-plugin",
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnixal/openclaw-nats-plugin",
-  "version": "0.1.18",
+  "version": "0.2.0",
   "description": "NATS JetStream event-driven plugin for OpenClaw",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
     "hooks/",
     "plugins/",
     "sidecar/",
+    "skills/",
     "docker/",
     "dashboard/dist/",
     "openclaw.plugin.json",

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

@@ -78,6 +78,100 @@ export default function (api: any) {
     }, { priority: 8 });
   }, { priority: 99 });
 
+  // ── Agent Tools ─────────────────────────────────────────────────
+
+  const SIDECAR_URL = process.env.NATS_SIDECAR_URL || 'http://127.0.0.1:3104';
+  const SIDECAR_KEY = process.env.NATS_PLUGIN_API_KEY || 'dev-nats-plugin-key';
+
+  const sidecarFetch = async (path: string, options: RequestInit = {}) => {
+    const res = await fetch(`${SIDECAR_URL}${path}`, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${SIDECAR_KEY}`,
+        ...options.headers,
+      },
+      signal: AbortSignal.timeout(5000),
+    });
+    return res.json();
+  };
+
+  api.registerTool({
+    name: 'nats_publish',
+    description: 'Publish an event to the NATS event bus. Use for cron triggers, custom events, task notifications.',
+    parameters: {
+      type: 'object',
+      properties: {
+        subject: { type: 'string', description: 'Event subject (must start with agent.events.)' },
+        payload: { type: 'object', description: 'Event payload data' },
+      },
+      required: ['subject', 'payload'],
+    },
+    async execute(_id: string, params: any) {
+      const result = await sidecarFetch('/api/publish', {
+        method: 'POST',
+        body: JSON.stringify({ subject: params.subject, payload: params.payload }),
+      });
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    },
+  });
+
+  api.registerTool({
+    name: 'nats_subscribe',
+    description: 'Subscribe to events matching a pattern. Matched events will be delivered to the target session as messages.',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Subject pattern (exact, or wildcard with * for one level, > for all descendants)' },
+        target: { type: 'string', description: 'Session key to deliver to (default: main)' },
+      },
+      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' }),
+      });
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    },
+  });
+
+  api.registerTool({
+    name: 'nats_unsubscribe',
+    description: 'Remove an event subscription by its ID.',
+    parameters: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Route ID to delete (from nats_subscriptions)' },
+      },
+      required: ['id'],
+    },
+    async execute(_id: string, params: any) {
+      const result = await sidecarFetch(`/api/routes/${params.id}`, { method: 'DELETE' });
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    },
+  });
+
+  api.registerTool({
+    name: 'nats_subscriptions',
+    description: 'List event subscriptions. Optionally filter by pattern or target session.',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Filter: show routes matching this pattern' },
+        target: { type: 'string', description: 'Filter: show routes delivering to this session' },
+      },
+    },
+    async execute(_id: string, params: any) {
+      const qs = new URLSearchParams();
+      if (params?.pattern) qs.set('pattern', params.pattern);
+      if (params?.target) qs.set('target', params.target);
+      const path = qs.toString() ? `/api/routes?${qs}` : '/api/routes';
+      const result = await sidecarFetch(path);
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    },
+  });
+
   // ── Dashboard UI ─────────────────────────────────────────────────
 
   api.registerHttpRoute({

package/sidecar/src/app.module.ts

@@ -7,6 +7,7 @@ import { GatewayClientModule } from './gateway/gateway-client.module';
 import { ConsumerModule } from './consumer/consumer.module';
 import { PendingModule } from './pending/pending.module';
 import { HealthModule } from './health/health.module';
+import { RouterModule } from './router/router.module';
 
 @Module({
   imports: [
@@ -26,6 +27,7 @@ import { HealthModule } from './health/health.module';
     ConsumerModule,
     PendingModule,
     HealthModule,
+    RouterModule,
   ],
 })
 export class AppModule {}

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

@@ -2,6 +2,7 @@ import { Controller, BaseController, Subscribe, OnQueueReady, type Message } fro
 import { PipelineService } from '../pre-handlers/pipeline.service';
 import { GatewayClientService } from '../gateway/gateway-client.service';
 import { PendingService } from '../pending/pending.service';
+import { RouterService } from '../router/router.service';
 import type { NatsEventEnvelope } from '../publisher/envelope';
 
 @Controller('/consumer')
@@ -10,6 +11,7 @@ export class ConsumerController extends BaseController {
     private pipeline: PipelineService,
     private gatewayClient: GatewayClientService,
     private pendingService: PendingService,
+    private routerService: RouterService,
   ) {
     super();
   }
@@ -20,7 +22,7 @@ export class ConsumerController extends BaseController {
     this.logger.info(`Queue connected, consuming as ${consumerName}`);
   }
 
-  @Subscribe('agent.inbound.>', {
+  @Subscribe('agent.events.>', {
     ackMode: 'manual',
     group: 'openclaw-main',
   })
@@ -29,29 +31,37 @@ export class ConsumerController extends BaseController {
       const envelope = this.extractEnvelope(message);
 
       const { result, ctx } = await this.pipeline.process(envelope);
-
       if (result === 'drop') {
         await message.ack();
         return;
       }
 
-      // Deliver to Gateway
+      // Check routing rules
+      const routes = await this.routerService.findMatchingRoutes(envelope.subject);
+      if (routes.length === 0) {
+        // No route — just ack (event is in JetStream for audit)
+        await message.ack();
+        return;
+      }
+
+      // Deliver to each matching target
       if (this.gatewayClient.isAlive()) {
-        await this.gatewayClient.inject({
-          target: envelope.agentTarget ?? 'main',
-          message: this.formatMessage(envelope),
-          metadata: {
-            source: 'nats',
-            eventId: envelope.id,
-            subject: envelope.subject,
-            priority: (ctx.enrichments['priority'] as number) ?? envelope.meta?.priority ?? 5,
-          },
-        });
+        for (const route of routes) {
+          await this.gatewayClient.inject({
+            target: 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,
+            },
+          });
+        }
         await message.ack();
       } else {
-        // Gateway not available — store as pending for ContextEngine pickup
         await this.pendingService.addPending(envelope);
-        await message.ack(); // ack because we stored it locally
+        await message.ack();
         this.logger.warn(`Gateway unavailable, stored pending event ${envelope.id}`);
       }
     } catch (err) {
@@ -60,29 +70,14 @@ export class ConsumerController extends BaseController {
     }
   }
 
-  /**
-   * Extract the NatsEventEnvelope from the adapter message.
-   *
-   * The JetStreamQueueAdapter wraps messages in its own envelope:
-   *   { id, pattern, data, timestamp, metadata }
-   *
-   * Our NatsEventEnvelope is inside `data` when published via PublisherService,
-   * or the raw data itself when published externally.
-   */
   private extractEnvelope(message: Message<unknown>): NatsEventEnvelope {
     const data = message.data as any;
-
-    // If the data already looks like a NatsEventEnvelope (has id, subject, payload),
-    // use it directly.
     if (data && typeof data === 'object' && 'subject' in data && 'payload' in data) {
       return data as NatsEventEnvelope;
     }
-
-    // Otherwise, treat it as a raw payload string that needs parsing
     if (typeof data === 'string') {
       return JSON.parse(data) as NatsEventEnvelope;
     }
-
     throw new Error('Unable to extract envelope from message');
   }
 

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

@@ -2,9 +2,10 @@ import { Module } from '@onebun/core';
 import { ConsumerController } from './consumer.controller';
 import { PreHandlersModule } from '../pre-handlers/pre-handlers.module';
 import { PendingModule } from '../pending/pending.module';
+import { RouterModule } from '../router/router.module';
 
 @Module({
-  imports: [PreHandlersModule, PendingModule],
+  imports: [PreHandlersModule, PendingModule, RouterModule],
   controllers: [ConsumerController],
 })
 export class ConsumerModule {}

package/sidecar/src/db/migrations/0003_wet_deathbird.sql

@@ -0,0 +1,12 @@
+CREATE TABLE `event_routes` (
+	`id` text PRIMARY KEY NOT NULL,
+	`pattern` text NOT NULL,
+	`target` text DEFAULT 'main' NOT NULL,
+	`enabled` integer DEFAULT true NOT NULL,
+	`priority` integer DEFAULT 5 NOT NULL,
+	`created_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `event_routes_pattern_unique` ON `event_routes` (`pattern`);--> statement-breakpoint
+CREATE INDEX `event_routes_pattern_idx` ON `event_routes` (`pattern`);--> statement-breakpoint
+CREATE INDEX `event_routes_target_idx` ON `event_routes` (`target`);

package/sidecar/src/db/migrations/meta/0003_snapshot.json

@@ -0,0 +1,194 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "cb92737c-c257-4b58-bbf0-798ab1494961",
+  "prevId": "3836f3c7-1186-453d-bb01-c2f5e58a1f4f",
+  "tables": {
+    "dedup_events": {
+      "name": "dedup_events",
+      "columns": {
+        "event_id": {
+          "name": "event_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "seen_at": {
+          "name": "seen_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "dedup_events_seen_at_idx": {
+          "name": "dedup_events_seen_at_idx",
+          "columns": [
+            "seen_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "event_routes": {
+      "name": "event_routes",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "pattern": {
+          "name": "pattern",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "target": {
+          "name": "target",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'main'"
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": true
+        },
+        "priority": {
+          "name": "priority",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 5
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "event_routes_pattern_unique": {
+          "name": "event_routes_pattern_unique",
+          "columns": [
+            "pattern"
+          ],
+          "isUnique": true
+        },
+        "event_routes_pattern_idx": {
+          "name": "event_routes_pattern_idx",
+          "columns": [
+            "pattern"
+          ],
+          "isUnique": false
+        },
+        "event_routes_target_idx": {
+          "name": "event_routes_target_idx",
+          "columns": [
+            "target"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "pending_events": {
+      "name": "pending_events",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_key": {
+          "name": "session_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "payload": {
+          "name": "payload",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "priority": {
+          "name": "priority",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 5
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "delivered_at": {
+          "name": "delivered_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/sidecar/src/db/migrations/meta/_journal.json

@@ -22,6 +22,13 @@
       "when": 1773334582658,
       "tag": "0002_common_stellaris",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1773938595817,
+      "tag": "0003_wet_deathbird",
+      "breakpoints": true
     }
   ]
 }

package/sidecar/src/db/schema.ts

@@ -20,3 +20,18 @@ export const pendingEvents = sqliteTable('pending_events', {
 
 export type DbPendingEvent = typeof pendingEvents.$inferSelect;
 export type NewPendingEvent = typeof pendingEvents.$inferInsert;
+
+export const eventRoutes = sqliteTable('event_routes', {
+  id:        text('id').primaryKey(),
+  pattern:   text('pattern').notNull().unique(),
+  target:    text('target').notNull().default('main'),
+  enabled:   integer('enabled', { mode: 'boolean' }).notNull().default(true),
+  priority:  integer('priority').notNull().default(5),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+}, (table) => [
+  index('event_routes_pattern_idx').on(table.pattern),
+  index('event_routes_target_idx').on(table.target),
+]);
+
+export type DbEventRoute = typeof eventRoutes.$inferSelect;
+export type NewEventRoute = typeof eventRoutes.$inferInsert;

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

@@ -49,7 +49,7 @@ export class HealthService extends BaseService {
       pendingCount,
       uptimeSeconds: Math.floor((Date.now() - this.startedAt) / 1000),
       config: {
-        streams: ['agent_inbound', 'agent_events', 'agent_dlq'],
+        streams: ['agent_events', 'agent_dlq'],
         consumerName: this.config.get('consumer.name'),
         dedupTtlSeconds: this.config.get('dedup.ttlSeconds'),
       },

package/sidecar/src/index.ts

@@ -23,11 +23,6 @@ const app = new OneBunApplication(AppModule, {
         replicas: 1,
       },
       streams: [
-        {
-          name: 'agent_inbound',
-          subjects: ['agent.inbound.>'],
-          retention: 'workqueue',
-        },
         {
           name: 'agent_events',
           subjects: ['agent.events.>'],

package/sidecar/src/publisher/publisher.controller.ts

@@ -12,8 +12,8 @@ export class PublisherController extends BaseController {
 
   @Post()
   async publish(@Body(publishBodySchema) body: PublishBody): Promise<OneBunResponse> {
-    if (!body.subject.startsWith('agent.events.')) {
-      return this.error('subject must start with agent.events.', 400, 400);
+    if (!body.subject.startsWith('agent.')) {
+      return this.error('subject must start with agent.', 400, 400);
     }
     await this.publisherService.publish(body.subject, body.payload, body.meta);
     return this.success({ published: true });

package/sidecar/src/router/router.controller.ts

@@ -0,0 +1,68 @@
+import {
+  Controller,
+  Get,
+  Post,
+  Delete,
+  Body,
+  Param,
+  Query,
+  BaseController,
+  UseMiddleware,
+  type OneBunResponse,
+} from '@onebun/core';
+import { type } from 'arktype';
+import { RouterService } from './router.service';
+import { ApiKeyMiddleware } from '../auth/api-key.middleware';
+
+const createRouteBody = type({
+  pattern: 'string',
+  'target?': 'string',
+  'priority?': 'number',
+});
+
+type CreateRouteBody = typeof createRouteBody.infer;
+
+@Controller('/api/routes')
+@UseMiddleware(ApiKeyMiddleware)
+export class RouterController extends BaseController {
+  constructor(private routerService: RouterService) {
+    super();
+  }
+
+  @Get('/status')
+  async getStatus(): Promise<OneBunResponse> {
+    const status = await this.routerService.status();
+    return this.success(status);
+  }
+
+  @Get()
+  async getRoutes(@Query() query: Record<string, string>): Promise<OneBunResponse> {
+    const filters: { pattern?: string; target?: string } = {};
+    if (query?.pattern) filters.pattern = query.pattern;
+    if (query?.target) filters.target = query.target;
+    const routes = await this.routerService.listRoutes(filters);
+    return this.success(routes);
+  }
+
+  @Post()
+  async createRoute(@Body(createRouteBody) body: CreateRouteBody): Promise<OneBunResponse> {
+    if (!body.pattern.startsWith('agent.events.')) {
+      return this.error('pattern must start with agent.events.', 400, 400);
+    }
+    const route = await this.routerService.subscribe(
+      body.pattern,
+      body.target ?? 'main',
+      body.priority ?? 5,
+    );
+    return this.success(route);
+  }
+
+  @Delete('/:id')
+  async deleteRoute(@Param('id') id: string): Promise<OneBunResponse> {
+    const deleted = await this.routerService.deleteById(id);
+    if (!deleted) {
+      return this.error('Route not found', 404, 404);
+    }
+    return this.success({ deleted: true });
+  }
+}

package/sidecar/src/router/router.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@onebun/core';
+import { RouterRepository } from './router.repository';
+import { RouterService } from './router.service';
+import { RouterController } from './router.controller';
+
+@Module({
+  controllers: [RouterController],
+  providers: [RouterRepository, RouterService],
+  exports: [RouterService],
+})
+export class RouterModule {}

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

@@ -0,0 +1,46 @@
+import { Service, BaseService } from '@onebun/core';
+import { DrizzleService, eq } from '@onebun/drizzle';
+import { eventRoutes, type DbEventRoute, type NewEventRoute } from '../db/schema';
+
+@Service()
+export class RouterRepository extends BaseService {
+  constructor(private db: DrizzleService) {
+    super();
+  }
+
+  async findAll(filters?: { pattern?: string; target?: string }): Promise<DbEventRoute[]> {
+    let query = this.db.select().from(eventRoutes);
+    if (filters?.pattern) {
+      query = query.where(eq(eventRoutes.pattern, filters.pattern)) as any;
+    } else if (filters?.target) {
+      query = query.where(eq(eventRoutes.target, filters.target)) as any;
+    }
+    return query.orderBy(eventRoutes.priority) as any;
+  }
+
+  async findEnabled(): Promise<DbEventRoute[]> {
+    return this.db.select().from(eventRoutes)
+      .where(eq(eventRoutes.enabled, true))
+      .orderBy(eventRoutes.priority) as any;
+  }
+
+  async create(route: NewEventRoute): Promise<DbEventRoute> {
+    const [created] = await this.db.insert(eventRoutes).values(route).returning();
+    return created;
+  }
+
+  async deleteById(id: string): Promise<boolean> {
+    const result = await this.db.delete(eventRoutes).where(eq(eventRoutes.id, id)).returning();
+    return result.length > 0;
+  }
+
+  async deleteByPattern(pattern: string): Promise<boolean> {
+    const result = await this.db.delete(eventRoutes).where(eq(eventRoutes.pattern, pattern)).returning();
+    return result.length > 0;
+  }
+
+  async count(): Promise<number> {
+    const rows = await this.db.select().from(eventRoutes);
+    return rows.length;
+  }
+}

package/sidecar/src/router/router.service.ts

@@ -0,0 +1,65 @@
+import { Service, BaseService } from '@onebun/core';
+import { RouterRepository } from './router.repository';
+import type { DbEventRoute } from '../db/schema';
+import { ulid } from 'ulid';
+
+@Service()
+export class RouterService extends BaseService {
+  constructor(private repo: RouterRepository) {
+    super();
+  }
+
+  /** NATS-style pattern matching: exact, * (one level), > (all descendants) */
+  matchPattern(pattern: string, subject: string): boolean {
+    const patParts = pattern.split('.');
+    const subParts = subject.split('.');
+
+    for (let i = 0; i < patParts.length; i++) {
+      if (patParts[i] === '>') {
+        return i < subParts.length; // > must match at least one token after
+      }
+      if (patParts[i] === '*') {
+        if (i >= subParts.length) return false;
+        continue;
+      }
+      if (i >= subParts.length || patParts[i] !== subParts[i]) return false;
+    }
+
+    return patParts.length === subParts.length;
+  }
+
+  async findMatchingRoutes(subject: string): Promise<DbEventRoute[]> {
+    const routes = await this.repo.findEnabled();
+    return routes
+      .filter(r => this.matchPattern(r.pattern, subject))
+      .sort((a, b) => a.priority - b.priority);
+  }
+
+  async listRoutes(filters?: { pattern?: string; target?: string }): Promise<DbEventRoute[]> {
+    return this.repo.findAll(filters);
+  }
+
+  async subscribe(pattern: string, target: string = 'main', priority: number = 5): Promise<DbEventRoute> {
+    return this.repo.create({
+      id: ulid(),
+      pattern,
+      target,
+      enabled: true,
+      priority,
+      createdAt: new Date(),
+    });
+  }
+
+  async unsubscribe(pattern: string): Promise<boolean> {
+    return this.repo.deleteByPattern(pattern);
+  }
+
+  async deleteById(id: string): Promise<boolean> {
+    return this.repo.deleteById(id);
+  }
+
+  async status(): Promise<{ configured: boolean; count: number }> {
+    const count = await this.repo.count();
+    return { configured: count > 0, count };
+  }
+}

package/skills/nats-events/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: nats-events
+description: Event-driven patterns for NATS. Use when the agent needs to publish events, subscribe to event patterns, set up cron-based triggers, or react to incoming NATS messages. Triggers on any mention of NATS, events, subscriptions, cron scheduling, or event-driven workflows.
+---
+
+# NATS Event Bus
+
+You have access to a NATS JetStream event bus via four tools:
+
+| Tool | Purpose |
+|---|---|
+| `nats_publish` | Publish an event (subject + payload) |
+| `nats_subscribe` | Create a routing rule (pattern -> session) |
+| `nats_unsubscribe` | Remove a routing rule by ID |
+| `nats_subscriptions` | List routing rules (optional filters: pattern, target) |
+
+## Bootstrap
+
+Before first use, check if subscriptions are configured:
+
+1. Call `nats_subscriptions` with no arguments
+2. If the list is **non-empty** — setup is complete, proceed with your task
+3. If **empty** — run initial setup:
+
+```
+nats_subscribe(pattern: "agent.events.cron.>",      target: "main")
+nats_subscribe(pattern: "agent.events.subagent.>",   target: "main")
+nats_subscribe(pattern: "agent.events.hook.>",       target: "main")
+nats_subscribe(pattern: "agent.events.custom.>",     target: "main")
+```
+
+Do NOT repeat bootstrap if subscriptions already exist.
+
+## Event-Driven Rules
+
+1. **Never poll** — subscribe to events and react when they arrive as messages in your session
+2. **Cron is OK** but must go through NATS: cron job calls `nats-cron-trigger.sh` -> event published -> delivered to your session -> you react
+3. **Every scheduled task** = cron entry calling `nats-cron-trigger.sh` + subscription on that subject
+4. **Incoming events** arrive as chat messages formatted `[NATS:<subject>] <payload>`
+
+## Creating Cron Tasks
+
+Always use the bundled script — never invoke LLM from cron:
+
+```bash
+# Step 1: Subscribe to the event
+nats_subscribe(pattern: "agent.events.cron.daily-report", target: "main")
+
+# Step 2: Create cron entry using the trigger script
+# The script is at: <plugin-dir>/skills/nats-events/scripts/nats-cron-trigger.sh
+*/30 * * * * /path/to/nats-cron-trigger.sh agent.events.cron.check-revenue '{"task":"check_revenue"}'
+0 9 * * * /path/to/nats-cron-trigger.sh agent.events.cron.daily-report '{"task":"daily_report"}'
+```
+
+The script only needs `NATS_SIDECAR_URL` and `NATS_PLUGIN_API_KEY` environment variables.
+
+## Subject Hierarchy
+
+| Pattern | Use for |
+|---|---|
+| `agent.events.cron.*` | Scheduled task triggers |
+| `agent.events.subagent.spawned` | Subagent started |
+| `agent.events.subagent.ended` | Subagent completed |
+| `agent.events.hook.*` | External webhook triggers |
+| `agent.events.session.*` | Session lifecycle |
+| `agent.events.tool.*` | Tool execution results |
+| `agent.events.gateway.*` | Gateway startup/restart |
+| `agent.events.custom.*` | Your custom events |
+
+## Pattern Matching
+
+- Exact: `agent.events.cron.daily-report` — matches only this subject
+- `*` — one level: `agent.events.cron.*` matches `agent.events.cron.daily` but not `agent.events.cron.reports.weekly`
+- `>` — all descendants: `agent.events.cron.>` matches everything under `agent.events.cron.`
+
+## Examples
+
+**React to subagent completion:**
+```
+nats_subscribe(pattern: "agent.events.subagent.ended", target: "main")
+# When subagent finishes, you receive: [NATS:agent.events.subagent.ended] {"subagentId":...,"result":...}
+```
+
+**Publish a custom event for external consumers:**
+```
+nats_publish(subject: "agent.events.custom.report-ready", payload: {"reportUrl": "https://..."})
+```
+
+**Schedule a recurring task:**
+```
+nats_subscribe(pattern: "agent.events.cron.hourly-check", target: "main")
+# Then create crontab: 0 * * * * nats-cron-trigger.sh agent.events.cron.hourly-check '{}'
+```

package/skills/nats-events/scripts/nats-cron-trigger.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# nats-cron-trigger.sh — Publish a NATS event from cron (no LLM involved).
+#
+# Usage:
+#   nats-cron-trigger.sh <subject> [payload_json]
+#
+# Examples:
+#   nats-cron-trigger.sh agent.events.cron.daily-report
+#   nats-cron-trigger.sh agent.events.cron.check-revenue '{"task":"check_revenue"}'
+#
+# Environment:
+#   NATS_SIDECAR_URL    — Sidecar HTTP URL  (default: http://127.0.0.1:3104)
+#   NATS_PLUGIN_API_KEY — Bearer token       (required)
+
+set -euo pipefail
+
+SUBJECT="${1:?Usage: nats-cron-trigger.sh <subject> [payload_json]}"
+PAYLOAD="${2:-"{}"}"
+SIDECAR="${NATS_SIDECAR_URL:-http://127.0.0.1:3104}"
+
+if [ -z "${NATS_PLUGIN_API_KEY:-}" ]; then
+  echo "Error: NATS_PLUGIN_API_KEY is not set" >&2
+  exit 1
+fi
+
+exec curl -sf -X POST "${SIDECAR}/api/publish" \
+  -H "Authorization: Bearer ${NATS_PLUGIN_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d "{\"subject\":\"${SUBJECT}\",\"payload\":${PAYLOAD}}"