@omnixal/openclaw-nats-plugin 0.2.0 → 0.2.2

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

@@ -5,22 +5,21 @@ description: Event-driven patterns for NATS. Use when the agent needs to publish
 
 # NATS Event Bus
 
-You have access to a NATS JetStream event bus via four tools:
+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) |
+| `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, 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:
+Before first use, set up default subscriptions. This is idempotent — safe to run multiple times:
 
 ```
 nats_subscribe(pattern: "agent.events.cron.>",      target: "main")
@@ -29,30 +28,45 @@ 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>`
+1. **Never poll** — subscribe to events and react when they arrive as messages
+2. **Incoming events** arrive as chat messages formatted `[NATS:<subject>] <payload>`
 
-## Creating Cron Tasks
+## Scheduling Events (Cron)
 
-Always use the bundled script — never invoke LLM from cron:
+Use `nats_cron_add` for scheduled events. This fires directly without waking the LLM:
 
-```bash
-# Step 1: Subscribe to the event
-nats_subscribe(pattern: "agent.events.cron.daily-report", target: "main")
+```
+# 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")
+```
 
-# 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"}'
+Don't forget to also subscribe to the cron subject so you receive the events:
+```
+nats_subscribe(pattern: "agent.events.cron.>", target: "main")
 ```
 
-The script only needs `NATS_SIDECAR_URL` and `NATS_PLUGIN_API_KEY` environment variables.
+**Alternative (environments with system crontab):** Use `nats-cron-trigger.sh` script.
 
 ## Subject Hierarchy
 
@@ -78,16 +92,15 @@ The script only needs `NATS_SIDECAR_URL` and `NATS_PLUGIN_API_KEY` environment v
 **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:**
+**Publish a custom event:**
 ```
 nats_publish(subject: "agent.events.custom.report-ready", payload: {"reportUrl": "https://..."})
 ```
 
-**Schedule a recurring task:**
+**Set up daily workflow:**
 ```
-nats_subscribe(pattern: "agent.events.cron.hourly-check", target: "main")
-# Then create crontab: 0 * * * * nats-cron-trigger.sh agent.events.cron.hourly-check '{}'
+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"})
 ```