@omnixal/openclaw-nats-plugin 0.1.18 → 0.2.1

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

@@ -0,0 +1,78 @@
+import { Service, BaseService } from '@onebun/core';
+import { DrizzleService, eq, sql } 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[]> {
+    // drizzle type limitation: chained .where()/.orderBy() loses type info
+    let query = this.db.select().from(eventRoutes) as any;
+    if (filters?.pattern) {
+      query = query.where(eq(eventRoutes.pattern, filters.pattern));
+    } else if (filters?.target) {
+      query = query.where(eq(eventRoutes.target, filters.target));
+    }
+    return query.orderBy(eventRoutes.priority);
+  }
+
+  async findEnabled(): Promise<DbEventRoute[]> {
+    // drizzle type limitation: chained .where()/.orderBy() loses type info
+    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 upsert(route: NewEventRoute): Promise<{ route: DbEventRoute; created: boolean }> {
+    const [result] = await this.db
+      .insert(eventRoutes)
+      .values(route)
+      .onConflictDoUpdate({
+        target: eventRoutes.pattern,
+        set: {
+          target: sql`excluded.target`,
+          priority: sql`excluded.priority`,
+          enabled: sql`excluded.enabled`,
+        },
+      })
+      .returning();
+
+    const created = result.createdAt.getTime() === route.createdAt!.getTime();
+    return { route: result, created };
+  }
+
+  async recordDelivery(routeId: string, subject: string): Promise<void> {
+    await this.db.update(eventRoutes)
+      .set({
+        lastDeliveredAt: new Date(),
+        lastEventSubject: subject,
+        deliveryCount: sql`${eventRoutes.deliveryCount} + 1`,
+      })
+      .where(eq(eventRoutes.id, routeId));
+  }
+
+  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 result = await this.db
+      .select({ count: sql<number>`count(*)` })
+      .from(eventRoutes);
+    return result[0]?.count ?? 0;
+  }
+}

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

@@ -0,0 +1,73 @@
+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<{ route: DbEventRoute; created: boolean }> {
+    return this.repo.upsert({
+      id: ulid(),
+      pattern,
+      target,
+      enabled: true,
+      priority,
+      createdAt: new Date(),
+    });
+  }
+
+  async recordDelivery(routeId: string, subject: string): Promise<void> {
+    await this.repo.recordDelivery(routeId, subject);
+  }
+
+  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/sidecar/src/scheduler/scheduler.controller.ts

@@ -0,0 +1,68 @@
+import {
+  Controller, Get, Post, Patch, Delete,
+  Body, Param, BaseController,
+  UseMiddleware, Subscribe,
+  type Message,
+  type OneBunResponse,
+} from '@onebun/core';
+import { SchedulerService } from './scheduler.service';
+import { ApiKeyMiddleware } from '../auth/api-key.middleware';
+import { createCronBodySchema, type CreateCronBody } from '../validation/schemas';
+
+@Controller('/api/cron')
+@UseMiddleware(ApiKeyMiddleware)
+export class SchedulerController extends BaseController {
+  constructor(private scheduler: SchedulerService) {
+    super();
+  }
+
+  @Post()
+  async createJob(@Body(createCronBodySchema) body: CreateCronBody): Promise<OneBunResponse> {
+    if (!body.subject.startsWith('agent.events.')) {
+      return this.error('subject must start with agent.events.', 400, 400);
+    }
+    const job = await this.scheduler.add({
+      name: body.name,
+      expr: body.cron,
+      subject: body.subject,
+      payload: body.payload,
+      timezone: body.timezone,
+    });
+    return this.success(job);
+  }
+
+  @Get()
+  async listJobs(): Promise<OneBunResponse> {
+    const jobs = await this.scheduler.list();
+    return this.success(jobs);
+  }
+
+  @Patch('/:name/toggle')
+  async toggleJob(@Param('name') name: string): Promise<OneBunResponse> {
+    const result = await this.scheduler.toggle(name);
+    if (!result) return this.error('Job not found', 404, 404);
+    return this.success(result);
+  }
+
+  @Post('/:name/run')
+  async runJob(@Param('name') name: string): Promise<OneBunResponse> {
+    const fired = await this.scheduler.fireNow(name);
+    if (!fired) return this.error('Job not found', 404, 404);
+    return this.success({ fired: true });
+  }
+
+  @Delete('/:name')
+  async deleteJob(@Param('name') name: string): Promise<OneBunResponse> {
+    const deleted = await this.scheduler.remove(name);
+    if (!deleted) return this.error('Job not found', 404, 404);
+    return this.success({ deleted: true });
+  }
+
+  @Subscribe('scheduler.fire.*')
+  async handleFire(message: Message<unknown>): Promise<void> {
+    const jobName = message.pattern?.split('.').pop();
+    if (jobName) {
+      await this.scheduler.handleFire(jobName);
+    }
+  }
+}

package/sidecar/src/scheduler/scheduler.module.ts

@@ -0,0 +1,13 @@
+import { Module } from '@onebun/core';
+import { PublisherModule } from '../publisher/publisher.module';
+import { SchedulerRepository } from './scheduler.repository';
+import { SchedulerService } from './scheduler.service';
+import { SchedulerController } from './scheduler.controller';
+
+@Module({
+  imports: [PublisherModule],
+  controllers: [SchedulerController],
+  providers: [SchedulerRepository, SchedulerService],
+  exports: [SchedulerService],
+})
+export class SchedulerModule {}

package/sidecar/src/scheduler/scheduler.repository.ts

@@ -0,0 +1,64 @@
+import { Service, BaseService } from '@onebun/core';
+import { DrizzleService, eq, sql } from '@onebun/drizzle';
+import { cronJobs, type DbCronJob, type NewCronJob } from '../db/schema';
+
+@Service()
+export class SchedulerRepository extends BaseService {
+  constructor(private db: DrizzleService) {
+    super();
+  }
+
+  async upsert(job: NewCronJob): Promise<DbCronJob> {
+    const [result] = await this.db
+      .insert(cronJobs)
+      .values(job)
+      .onConflictDoUpdate({
+        target: cronJobs.name,
+        set: {
+          expr: sql`excluded.expr`,
+          subject: sql`excluded.subject`,
+          payload: sql`excluded.payload`,
+          timezone: sql`excluded.timezone`,
+          enabled: sql`excluded.enabled`,
+        },
+      })
+      .returning();
+    return result;
+  }
+
+  async findAll(): Promise<DbCronJob[]> {
+    // drizzle type limitation: chained .orderBy() loses type info
+    return this.db.select().from(cronJobs).orderBy(cronJobs.name) as any;
+  }
+
+  async findAllEnabled(): Promise<DbCronJob[]> {
+    // drizzle type limitation: chained .where()/.orderBy() loses type info
+    return this.db.select().from(cronJobs)
+      .where(eq(cronJobs.enabled, true))
+      .orderBy(cronJobs.name) as any;
+  }
+
+  async findByName(name: string): Promise<DbCronJob | undefined> {
+    const [result] = await this.db.select().from(cronJobs)
+      .where(eq(cronJobs.name, name));
+    return result;
+  }
+
+  async deleteByName(name: string): Promise<boolean> {
+    const result = await this.db.delete(cronJobs)
+      .where(eq(cronJobs.name, name)).returning();
+    return result.length > 0;
+  }
+
+  async setEnabled(name: string, enabled: boolean): Promise<void> {
+    await this.db.update(cronJobs)
+      .set({ enabled })
+      .where(eq(cronJobs.name, name));
+  }
+
+  async updateLastRun(name: string): Promise<void> {
+    await this.db.update(cronJobs)
+      .set({ lastRunAt: new Date() })
+      .where(eq(cronJobs.name, name));
+  }
+}

package/sidecar/src/scheduler/scheduler.service.ts

@@ -0,0 +1,138 @@
+import { Service, BaseService, QueueService, OnModuleInit } from '@onebun/core';
+import { SchedulerRepository } from './scheduler.repository';
+import { PublisherService } from '../publisher/publisher.service';
+import { ulid } from 'ulid';
+
+interface AddJobInput {
+  name: string;
+  expr: string;
+  subject: string;
+  payload?: unknown;
+  timezone?: string;
+}
+
+@Service()
+export class SchedulerService extends BaseService implements OnModuleInit {
+  constructor(
+    private repo: SchedulerRepository,
+    private queueService: QueueService,
+    private publisher: PublisherService,
+  ) {
+    super();
+  }
+
+  private get scheduler() {
+    return this.queueService.getScheduler();
+  }
+
+  async onModuleInit(): Promise<void> {
+    const jobs = await this.repo.findAllEnabled();
+    for (const job of jobs) {
+      this.scheduler.addCronJob(
+        job.name,
+        job.expr,
+        `scheduler.fire.${job.name}`,
+      );
+    }
+    if (jobs.length > 0) {
+      this.logger.info(`Restored ${jobs.length} cron jobs from DB`);
+    }
+  }
+
+  async add(input: AddJobInput) {
+    const job = await this.repo.upsert({
+      id: ulid(),
+      name: input.name,
+      expr: input.expr,
+      subject: input.subject,
+      payload: input.payload ?? null,
+      timezone: input.timezone ?? 'UTC',
+      enabled: true,
+      createdAt: new Date(),
+    });
+
+    if (this.scheduler.hasJob(input.name)) {
+      // Remove and re-add to update the cron expression
+      this.scheduler.removeJob(input.name);
+    }
+    this.scheduler.addCronJob(
+      input.name,
+      input.expr,
+      `scheduler.fire.${input.name}`,
+    );
+
+    this.logger.info(`Cron job '${input.name}' registered: ${input.expr} -> ${input.subject}`);
+    return job;
+  }
+
+  async remove(name: string): Promise<boolean> {
+    const deleted = await this.repo.deleteByName(name);
+    if (this.scheduler.hasJob(name)) {
+      this.scheduler.removeJob(name);
+    }
+    return deleted;
+  }
+
+  async list() {
+    const dbJobs = await this.repo.findAll();
+    return dbJobs.map(job => {
+      const runtime = this.scheduler.getJob(job.name);
+      return {
+        ...job,
+        nextRun: runtime?.nextRun ?? null,
+        isRunning: runtime?.isRunning ?? false,
+      };
+    });
+  }
+
+  async toggle(name: string) {
+    const job = await this.repo.findByName(name);
+    if (!job) return null;
+
+    const newEnabled = !job.enabled;
+    await this.repo.setEnabled(name, newEnabled);
+
+    if (newEnabled) {
+      this.scheduler.addCronJob(
+        name,
+        job.expr,
+        `scheduler.fire.${name}`,
+      );
+      this.logger.info(`Cron job '${name}' enabled`);
+    } else {
+      if (this.scheduler.hasJob(name)) {
+        this.scheduler.removeJob(name);
+      }
+      this.logger.info(`Cron job '${name}' disabled`);
+    }
+
+    return this.repo.findByName(name);
+  }
+
+  async fireNow(name: string): Promise<boolean> {
+    const job = await this.repo.findByName(name);
+    if (!job) return false;
+
+    const base = (job.payload && typeof job.payload === 'object' && !Array.isArray(job.payload))
+      ? (job.payload as Record<string, unknown>)
+      : {};
+    const payload = { ...base, _cron: { jobName: job.name, firedAt: new Date().toISOString(), manual: true } };
+    await this.publisher.publish(job.subject, payload);
+    await this.repo.updateLastRun(name);
+    this.logger.info(`Cron job '${name}' manually fired -> ${job.subject}`);
+    return true;
+  }
+
+  async handleFire(jobName: string): Promise<void> {
+    const job = await this.repo.findByName(jobName);
+    if (!job || !job.enabled) return;
+
+    const base = (job.payload && typeof job.payload === 'object' && !Array.isArray(job.payload))
+      ? (job.payload as Record<string, unknown>)
+      : {};
+    const payload = { ...base, _cron: { jobName: job.name, firedAt: new Date().toISOString() } };
+    await this.publisher.publish(job.subject, payload);
+    await this.repo.updateLastRun(job.name);
+    this.logger.debug(`Cron fired: ${job.name} -> ${job.subject}`);
+  }
+}

package/sidecar/src/validation/schemas.ts

@@ -17,3 +17,21 @@ export const markDeliveredBodySchema = type({
 });
 
 export type MarkDeliveredBody = typeof markDeliveredBodySchema.infer;
+
+export const createRouteBodySchema = type({
+  pattern: 'string',
+  'target?': 'string',
+  'priority?': 'number',
+});
+
+export type CreateRouteBody = typeof createRouteBodySchema.infer;
+
+export const createCronBodySchema = type({
+  name: 'string',
+  cron: 'string',
+  subject: 'string',
+  'payload?': 'unknown',
+  'timezone?': 'string',
+});
+
+export type CreateCronBody = typeof createCronBodySchema.infer;

package/skills/nats-events/SKILL.md

@@ -0,0 +1,106 @@
+---
+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 these tools:
+
+| Tool | Purpose |
+|---|---|
+| `nats_publish` | Publish an event (subject + payload) |
+| `nats_subscribe` | Create a routing rule (pattern -> session) — idempotent, safe to repeat |
+| `nats_unsubscribe` | Remove a routing rule by ID |
+| `nats_subscriptions` | List routing rules (optional filters: pattern, target) |
+| `nats_cron_add` | Schedule a recurring NATS event (no LLM wake) |
+| `nats_cron_remove` | Remove a scheduled cron job |
+| `nats_cron_list` | List all scheduled cron jobs |
+
+## Bootstrap
+
+Before first use, set up default subscriptions. This is idempotent — safe to run multiple times:
+
+```
+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")
+```
+
+## Event-Driven Rules
+
+1. **Never poll** — subscribe to events and react when they arrive as messages
+2. **Incoming events** arrive as chat messages formatted `[NATS:<subject>] <payload>`
+
+## Scheduling Events (Cron)
+
+Use `nats_cron_add` for scheduled events. This fires directly without waking the LLM:
+
+```
+# Schedule a daily report trigger at 9am UTC
+nats_cron_add(
+  name: "daily-report",
+  cron: "0 9 * * *",
+  subject: "agent.events.cron.daily-report",
+  payload: { "task": "daily_report" }
+)
+
+# Schedule hourly revenue check
+nats_cron_add(
+  name: "hourly-check",
+  cron: "0 * * * *",
+  subject: "agent.events.cron.check-revenue",
+  payload: { "task": "check_revenue" }
+)
+
+# List all scheduled jobs
+nats_cron_list()
+
+# Remove a job
+nats_cron_remove(name: "hourly-check")
+```
+
+Don't forget to also subscribe to the cron subject so you receive the events:
+```
+nats_subscribe(pattern: "agent.events.cron.>", target: "main")
+```
+
+**Alternative (environments with system crontab):** Use `nats-cron-trigger.sh` script.
+
+## 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")
+```
+
+**Publish a custom event:**
+```
+nats_publish(subject: "agent.events.custom.report-ready", payload: {"reportUrl": "https://..."})
+```
+
+**Set up daily workflow:**
+```
+nats_subscribe(pattern: "agent.events.cron.daily-report", target: "main")
+nats_cron_add(name: "daily-report", cron: "0 9 * * *", subject: "agent.events.cron.daily-report", payload: {"task": "report"})
+```

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}}"