@omnixal/openclaw-nats-plugin 0.2.7 → 0.2.8

package/sidecar/src/gateway/gateway-client.service.ts

@@ -11,6 +11,25 @@ export interface GatewayInjectPayload {
   };
 }
 
+export class GatewayRpcError extends Error {
+  constructor(
+    public readonly rpcId: string,
+    public readonly errorCode: string,
+    public readonly errorMessage: string,
+  ) {
+    super(`Gateway RPC error [${rpcId}]: ${errorCode} — ${errorMessage}`);
+    this.name = 'GatewayRpcError';
+  }
+}
+
+interface PendingRequest {
+  resolve: () => void;
+  reject: (err: Error) => void;
+  timer: Timer;
+}
+
+const RPC_TIMEOUT_MS = 10_000;
+
 @Service()
 export class GatewayClientService extends BaseService implements OnModuleInit, OnModuleDestroy {
   private ws: WebSocket | null = null;
@@ -21,6 +40,7 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
   private requestId = 0;
   private wsUrl!: string;
   private token!: string;
+  private pendingRequests = new Map<string, PendingRequest>();
 
   async onModuleInit(): Promise<void> {
     this.wsUrl = this.config.get('gateway.wsUrl');
@@ -49,6 +69,12 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
       this.ws.onclose = () => {
         this.connected = false;
         this.connectSent = false;
+        // Reject all in-flight requests immediately — don't make callers wait for timeout
+        for (const [id, pending] of this.pendingRequests) {
+          clearTimeout(pending.timer);
+          pending.reject(new Error('Gateway WebSocket closed'));
+        }
+        this.pendingRequests.clear();
         this.scheduleReconnect();
       };
 
@@ -97,12 +123,26 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
       }
       // Regular RPC ok response (e.g. for inject calls)
       this.logger.debug('Received RPC ok response', { id: frame.id });
+      this.resolvePending(frame.id);
       return;
     }
 
     // Error response
     if (frame.type === 'res' && frame.ok === false) {
-      this.logger.warn('Gateway RPC error', { id: frame.id, error: frame.error });
+      const errorCode = frame.error?.code ?? frame.error?.errorCode ?? 'UNKNOWN';
+      const errorMessage = frame.error?.message ?? frame.error?.errorMessage ?? 'Unknown gateway error';
+      this.logger.error('Gateway RPC error', { id: frame.id, errorCode, errorMessage });
+
+      // If this is a connect error, close and reconnect
+      if (frame.id?.startsWith('connect-')) {
+        this.logger.error(`Gateway rejected connection: ${errorCode} — ${errorMessage}`);
+        this.connected = false;
+        this.connectSent = false;
+        this.ws?.close();
+        return;
+      }
+
+      this.rejectPending(frame.id, new GatewayRpcError(frame.id, String(errorCode), String(errorMessage)));
     }
   }
 
@@ -111,7 +151,8 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
     this.connectSent = true;
     this.logger.info('Sending connect frame');
 
-    this.send({
+    try {
+      this.send({
       type: 'req',
       id: `connect-${++this.requestId}`,
       method: 'connect',
@@ -126,7 +167,7 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
           mode: 'backend',
         },
         role: 'operator',
-        scopes: ['operator.read'],
+        scopes: ['operator.read', 'operator.write'],
         caps: [],
         commands: [],
         permissions: {},
@@ -135,11 +176,21 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
         userAgent: 'nats-sidecar/1.0.0',
       },
     });
+    } catch (err) {
+      this.logger.error('Failed to send connect frame', err);
+      this.connectSent = false;
+    }
   }
 
   private send(frame: unknown): void {
-    if (this.ws?.readyState === WebSocket.OPEN) {
+    if (this.ws?.readyState !== WebSocket.OPEN) {
+      throw new Error('WebSocket is not open');
+    }
+    try {
       this.ws.send(JSON.stringify(frame));
+    } catch (err) {
+      this.connected = false;
+      throw new Error(`WebSocket send failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 
@@ -158,9 +209,11 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
     if (!this.isAlive()) {
       throw new Error('Gateway WebSocket not connected');
     }
+    const id = `rpc-${++this.requestId}`;
+    const promise = this.trackRequest(id);
     this.send({
       type: 'req',
-      id: `rpc-${++this.requestId}`,
+      id,
       method: 'send',
       params: {
         target: payload.target,
@@ -169,6 +222,35 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
         idempotencyKey: payload.metadata?.eventId ?? String(this.requestId),
       },
     });
+    return promise;
+  }
+
+  private trackRequest(id: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`Gateway RPC timeout after ${RPC_TIMEOUT_MS}ms [${id}]`));
+      }, RPC_TIMEOUT_MS);
+      this.pendingRequests.set(id, { resolve, reject, timer });
+    });
+  }
+
+  private resolvePending(id: string): void {
+    const pending = this.pendingRequests.get(id);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pendingRequests.delete(id);
+      pending.resolve();
+    }
+  }
+
+  private rejectPending(id: string, err: Error): void {
+    const pending = this.pendingRequests.get(id);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pendingRequests.delete(id);
+      pending.reject(err);
+    }
   }
 
   isAlive(): boolean {
@@ -180,6 +262,12 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
+    // Reject all pending requests
+    for (const [id, pending] of this.pendingRequests) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('Gateway client shutting down'));
+    }
+    this.pendingRequests.clear();
     if (this.ws) {
       this.ws.close();
       this.ws = null;

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

@@ -35,7 +35,6 @@ export class RouterController extends BaseController {
   @Get('/health')
   async getRoutesHealth(): Promise<OneBunResponse> {
     const routes = await this.routerService.listRoutes();
-    const now = Date.now();
     const result = routes.map(r => ({
       id: r.id,
       pattern: r.pattern,
@@ -45,7 +44,7 @@ export class RouterController extends BaseController {
       lastDeliveredAt: r.lastDeliveredAt?.toISOString() ?? null,
       lastEventSubject: r.lastEventSubject ?? null,
       deliveryCount: r.deliveryCount ?? 0,
-      lagMs: r.lastDeliveredAt ? now - r.lastDeliveredAt.getTime() : null,
+      lagMs: r.lastDeliveryLagMs ?? null,
     }));
     return this.success(result);
   }

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

@@ -57,12 +57,13 @@ export class RouterRepository extends BaseService {
     return result ?? null;
   }
 
-  async recordDelivery(routeId: string, subject: string): Promise<void> {
+  async recordDelivery(routeId: string, subject: string, lagMs: number): Promise<void> {
     await this.db.update(eventRoutes)
       .set({
         lastDeliveredAt: new Date(),
         lastEventSubject: subject,
         deliveryCount: sql`${eventRoutes.deliveryCount} + 1`,
+        lastDeliveryLagMs: lagMs,
       })
       .where(eq(eventRoutes.id, routeId));
   }

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

@@ -58,8 +58,8 @@ export class RouterService extends BaseService {
     return this.repo.updateById(id, fields);
   }
 
-  async recordDelivery(routeId: string, subject: string): Promise<void> {
-    await this.repo.recordDelivery(routeId, subject);
+  async recordDelivery(routeId: string, subject: string, lagMs: number): Promise<void> {
+    await this.repo.recordDelivery(routeId, subject, lagMs);
   }
 
   async unsubscribe(pattern: string): Promise<boolean> {

package/sidecar/src/scheduler/scheduler.controller.ts

@@ -14,6 +14,7 @@ import { ApiKeyMiddleware } from '../auth/api-key.middleware';
 import {
   createCronBodySchema, type CreateCronBody,
   updateCronBodySchema, type UpdateCronBody,
+  createTimerBodySchema, type CreateTimerBody,
   isValidAgentSubject,
 } from '../validation/schemas';
 
@@ -92,6 +93,37 @@ export class SchedulerController extends BaseController {
     return this.success({ deleted: true });
   }
 
+  // ── Timer Endpoints ──────────────────────────────────────────────
+
+  @Post('/timer')
+  async createTimer(@Body(createTimerBodySchema) body: CreateTimerBody): Promise<OneBunResponse> {
+    if (!isValidAgentSubject(body.subject)) {
+      return this.error('subject must start with "agent.events." followed by at least one token and must not end with "."', 400, 400);
+    }
+    const timer = await this.scheduler.addTimer({
+      name: body.name,
+      delayMs: body.delayMs,
+      subject: body.subject,
+      payload: body.payload,
+    });
+    return this.success(timer);
+  }
+
+  @Get('/timer')
+  async listTimers(): Promise<OneBunResponse> {
+    const timers = await this.scheduler.listTimers();
+    return this.success(timers);
+  }
+
+  @Delete('/timer/:name')
+  async cancelTimer(@Param('name') name: string): Promise<OneBunResponse> {
+    const deleted = await this.scheduler.cancelTimer(name);
+    if (!deleted) return this.error('Timer not found', 404, 404);
+    return this.success({ deleted: true });
+  }
+
+  // ── Queue Handlers ────────────────────────────────────────────────
+
   @Subscribe('scheduler.fire.*', { group: 'scheduler-handler' })
   async handleFire(message: Message<unknown>): Promise<void> {
     const jobName = message.pattern?.split('.').pop();
@@ -99,4 +131,12 @@ export class SchedulerController extends BaseController {
       await this.scheduler.handleFire(jobName);
     }
   }
+
+  @Subscribe('scheduler.timer.*', { group: 'scheduler-handler' })
+  async handleTimerFire(message: Message<unknown>): Promise<void> {
+    const timerName = message.pattern?.split('.').pop();
+    if (timerName) {
+      await this.scheduler.handleTimerFire(timerName);
+    }
+  }
 }

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

@@ -1,6 +1,6 @@
 import { Service, BaseService } from '@onebun/core';
-import { DrizzleService, eq, sql } from '@onebun/drizzle';
-import { cronJobs, type DbCronJob, type NewCronJob } from '../db/schema';
+import { DrizzleService, eq, sql, and, lte } from '@onebun/drizzle';
+import { cronJobs, timerJobs, type DbCronJob, type NewCronJob, type DbTimerJob, type NewTimerJob } from '../db/schema';
 
 @Service()
 export class SchedulerRepository extends BaseService {
@@ -69,4 +69,51 @@ export class SchedulerRepository extends BaseService {
       .set({ lastRunAt: new Date() })
       .where(eq(cronJobs.name, name));
   }
+
+  // ── Timer Jobs ──────────────────────────────────────────────────────
+
+  async createTimer(timer: NewTimerJob): Promise<DbTimerJob> {
+    const [result] = await this.db
+      .insert(timerJobs)
+      .values(timer)
+      .onConflictDoUpdate({
+        target: timerJobs.name,
+        set: {
+          subject: sql`excluded.subject`,
+          payload: sql`excluded.payload`,
+          delayMs: sql`excluded.delay_ms`,
+          fireAt: sql`excluded.fire_at`,
+          fired: sql`0`,
+        },
+      })
+      .returning();
+    return result;
+  }
+
+  async findPendingTimers(): Promise<DbTimerJob[]> {
+    return this.db.select().from(timerJobs)
+      .where(eq(timerJobs.fired, false)) as any;
+  }
+
+  async findTimerByName(name: string): Promise<DbTimerJob | undefined> {
+    const [result] = await this.db.select().from(timerJobs)
+      .where(eq(timerJobs.name, name));
+    return result;
+  }
+
+  async markTimerFired(name: string): Promise<void> {
+    await this.db.update(timerJobs)
+      .set({ fired: true })
+      .where(eq(timerJobs.name, name));
+  }
+
+  async deleteTimerByName(name: string): Promise<boolean> {
+    const result = await this.db.delete(timerJobs)
+      .where(eq(timerJobs.name, name)).returning();
+    return result.length > 0;
+  }
+
+  async findAllTimers(): Promise<DbTimerJob[]> {
+    return this.db.select().from(timerJobs).orderBy(timerJobs.fireAt) as any;
+  }
 }

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

@@ -12,6 +12,13 @@ interface AddJobInput {
   timezone?: string;
 }
 
+interface AddTimerInput {
+  name: string;
+  delayMs: number;
+  subject: string;
+  payload?: unknown;
+}
+
 @Service()
 export class SchedulerService extends BaseService {
   private _queueReady = false;
@@ -51,6 +58,30 @@ export class SchedulerService extends BaseService {
     } catch (err) {
       this.logger.error('Failed to restore cron jobs', err);
     }
+
+    try {
+      const timers = await this.repo.findPendingTimers();
+      let restored = 0;
+      for (const timer of timers) {
+        const remaining = timer.fireAt.getTime() - Date.now();
+        if (remaining <= 0) {
+          // Timer expired during downtime — fire immediately
+          await this.fireTimer(timer.name);
+        } else {
+          this.scheduler.addTimeoutJob(
+            `timer.${timer.name}`,
+            remaining,
+            `scheduler.timer.${timer.name}`,
+          );
+          restored++;
+        }
+      }
+      if (restored > 0) {
+        this.logger.info(`Restored ${restored} pending timers from DB`);
+      }
+    } catch (err) {
+      this.logger.error('Failed to restore timers', err);
+    }
   }
 
   async add(input: AddJobInput) {
@@ -201,4 +232,80 @@ export class SchedulerService extends BaseService {
       this.logger.error(`Cron fire failed: ${job.name}`, err);
     }
   }
+
+  // ── Timer (one-shot delayed) Jobs ─────────────────────────────────
+
+  async addTimer(input: AddTimerInput) {
+    const fireAt = new Date(Date.now() + input.delayMs);
+    const timer = await this.repo.createTimer({
+      id: ulid(),
+      name: input.name,
+      subject: input.subject,
+      payload: input.payload ?? null,
+      delayMs: input.delayMs,
+      fireAt,
+      fired: false,
+      createdAt: new Date(),
+    });
+
+    const schedulerName = `timer.${input.name}`;
+    if (this.scheduler.hasJob(schedulerName)) {
+      this.scheduler.removeJob(schedulerName);
+    }
+    this.scheduler.addTimeoutJob(
+      schedulerName,
+      input.delayMs,
+      `scheduler.timer.${input.name}`,
+    );
+
+    this.logger.info(`Timer '${input.name}' set: ${input.delayMs}ms -> ${input.subject}`);
+    return { ...timer, fireAt: timer.fireAt.getTime(), createdAt: timer.createdAt.getTime() };
+  }
+
+  async cancelTimer(name: string): Promise<boolean> {
+    const deleted = await this.repo.deleteTimerByName(name);
+    const schedulerName = `timer.${name}`;
+    if (this.scheduler.hasJob(schedulerName)) {
+      this.scheduler.removeJob(schedulerName);
+    }
+    return deleted;
+  }
+
+  async listTimers() {
+    const timers = await this.repo.findAllTimers();
+    return timers.map(t => ({
+      ...t,
+      fireAt: t.fireAt.getTime(),
+      createdAt: t.createdAt.getTime(),
+      remainingMs: t.fired ? 0 : Math.max(0, t.fireAt.getTime() - Date.now()),
+    }));
+  }
+
+  async fireTimer(name: string): Promise<void> {
+    const timer = await this.repo.findTimerByName(name);
+    if (!timer || timer.fired) return;
+
+    if (!this._queueReady) {
+      this.logger.warn(`Timer '${name}' fire skipped — queue not ready`);
+      return;
+    }
+
+    try {
+      const base = (timer.payload && typeof timer.payload === 'object' && !Array.isArray(timer.payload))
+        ? (timer.payload as Record<string, unknown>)
+        : {};
+      const payload = { ...base, _timer: { name: timer.name, firedAt: new Date().toISOString() } };
+      await this.publisher.publish(timer.subject, payload);
+      await this.repo.markTimerFired(name);
+      await this.logService.logDelivery(timer.id, timer.subject, JSON.stringify({ type: 'timer', name }));
+      this.logger.info(`Timer fired: ${name} -> ${timer.subject}`);
+    } catch (err) {
+      await this.logService.logError('timer', timer.id, timer.subject, err);
+      this.logger.error(`Timer fire failed: ${name}`, err);
+    }
+  }
+
+  async handleTimerFire(timerName: string): Promise<void> {
+    await this.fireTimer(timerName);
+  }
 }

package/sidecar/src/validation/schemas.ts

@@ -54,6 +54,15 @@ export const updateCronBodySchema = type({
 
 export type UpdateCronBody = typeof updateCronBodySchema.infer;
 
+export const createTimerBodySchema = type({
+  name: 'string',
+  delayMs: 'number > 0',
+  subject: 'string',
+  'payload?': 'unknown',
+});
+
+export type CreateTimerBody = typeof createTimerBodySchema.infer;
+
 /** Validate that subject has content after 'agent.events.' prefix and doesn't end with '.' */
 export function isValidAgentSubject(subject: string): boolean {
   if (!subject.startsWith('agent.events.')) return false;

package/skills/nats-events/SKILL.md

@@ -1,22 +1,41 @@
 ---
 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.
+description: Event-driven patterns for NATS. Use when the agent needs to publish events, subscribe to event patterns, set up cron-based triggers, manage timers, or react to incoming NATS messages. Triggers on any mention of NATS, events, subscriptions, cron scheduling, timers, or event-driven workflows.
 ---
 
 # NATS Event Bus
 
 You have access to a NATS JetStream event bus via these tools:
 
+## Core 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_route_update` | Update a route (target, priority, enabled) by ID |
+
+## Cron (Recurring) Tools
+
+| Tool | Purpose |
+|---|---|
 | `nats_cron_add` | Schedule a recurring NATS event (no LLM wake) |
+| `nats_cron_update` | Update a cron job (schedule, subject, payload, timezone, enabled) |
+| `nats_cron_toggle` | Toggle a cron job on/off |
+| `nats_cron_run` | Manually fire a cron job right now |
 | `nats_cron_remove` | Remove a scheduled cron job |
 | `nats_cron_list` | List all scheduled cron jobs |
 
+## Timer (One-Shot Delayed) Tools
+
+| Tool | Purpose |
+|---|---|
+| `nats_timer_set` | Set a one-shot delayed event (fires once after delay) |
+| `nats_timer_cancel` | Cancel a pending timer |
+| `nats_timer_list` | List all timers with remaining time |
+
 ## Bootstrap
 
 Before first use, set up default subscriptions. This is idempotent — safe to run multiple times:
@@ -26,6 +45,7 @@ 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")
+nats_subscribe(pattern: "agent.events.timer.>",      target: "main")
 ```
 
 ## Event-Driven Rules
@@ -46,33 +66,76 @@ nats_cron_add(
   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" }
-)
+# Update the schedule to 10am
+nats_cron_update(name: "daily-report", cron: "0 10 * * *")
+
+# Temporarily disable
+nats_cron_toggle(name: "daily-report")
+
+# Fire manually right now (doesn't affect schedule)
+nats_cron_run(name: "daily-report")
 
 # List all scheduled jobs
 nats_cron_list()
 
 # Remove a job
-nats_cron_remove(name: "hourly-check")
+nats_cron_remove(name: "daily-report")
 ```
 
-Don't forget to also subscribe to the cron subject so you receive the events:
+## Timers (Delayed One-Shot Events)
+
+Use `nats_timer_set` for delayed self-pings, reminders, or deferred checks. Timers survive sidecar restarts.
+
 ```
-nats_subscribe(pattern: "agent.events.cron.>", target: "main")
+# Check deploy status in 5 minutes
+nats_timer_set(
+  name: "check-deploy",
+  delayMs: 300000,
+  subject: "agent.events.timer.check-deploy",
+  payload: { "task": "verify_deployment", "deployId": "abc123" }
+)
+
+# Set a 1-hour reminder
+nats_timer_set(
+  name: "followup-reminder",
+  delayMs: 3600000,
+  subject: "agent.events.timer.reminder",
+  payload: { "task": "followup", "context": "check sales" }
+)
+
+# Cancel a timer
+nats_timer_cancel(name: "check-deploy")
+
+# List pending timers
+nats_timer_list()
 ```
 
-**Alternative (environments with system crontab):** Use `nats-cron-trigger.sh` script.
+Don't forget to subscribe to timer events:
+```
+nats_subscribe(pattern: "agent.events.timer.>", target: "main")
+```
+
+## Managing Routes
+
+```
+# List current routes
+nats_subscriptions()
+
+# Update a route's priority or target
+nats_route_update(id: "01ABC...", priority: 8)
+nats_route_update(id: "01ABC...", enabled: false)
+nats_route_update(id: "01ABC...", target: "worker-2")
+
+# Remove a route
+nats_unsubscribe(id: "01ABC...")
+```
 
 ## Subject Hierarchy
 
 | Pattern | Use for |
 |---|---|
 | `agent.events.cron.*` | Scheduled task triggers |
+| `agent.events.timer.*` | Delayed one-shot triggers |
 | `agent.events.subagent.spawned` | Subagent started |
 | `agent.events.subagent.ended` | Subagent completed |
 | `agent.events.hook.*` | External webhook triggers |
@@ -104,3 +167,9 @@ nats_publish(subject: "agent.events.custom.report-ready", payload: {"reportUrl":
 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"})
 ```
+
+**Delayed check after action:**
+```
+nats_subscribe(pattern: "agent.events.timer.>", target: "main")
+nats_timer_set(name: "verify-action", delayMs: 60000, subject: "agent.events.timer.verify", payload: {"check": "result"})
+```