@omnixal/openclaw-nats-plugin 0.1.0

package/sidecar/src/consumer/consumer.service.ts

@@ -0,0 +1,113 @@
+import { Service, BaseService, type OnModuleInit, type OnModuleDestroy } from '@onebun/core';
+import type { Message, Subscription } from '@onebun/core';
+import { NatsAdapterService } from '../nats-streams/nats-adapter.service';
+import { PipelineService } from '../pre-handlers/pipeline.service';
+import { GatewayClientService } from '../gateway/gateway-client.service';
+import { PendingService } from '../pending/pending.service';
+import type { NatsEventEnvelope } from '../publisher/envelope';
+
+@Service()
+export class ConsumerService extends BaseService implements OnModuleInit, OnModuleDestroy {
+  private subscription: Subscription | null = null;
+
+  constructor(
+    private natsAdapter: NatsAdapterService,
+    private pipeline: PipelineService,
+    private gatewayClient: GatewayClientService,
+    private pendingService: PendingService,
+  ) {
+    super();
+  }
+
+  async onModuleInit(): Promise<void> {
+    if (!this.natsAdapter.isConnected()) {
+      this.logger.warn('NATS not connected, consumer will not start');
+      return;
+    }
+
+    try {
+      const consumerName = this.config.get('consumer.name');
+      this.subscription = await this.natsAdapter.subscribe(
+        'agent.inbound.>',
+        (message: Message<unknown>) => this.handleInbound(message),
+        { ackMode: 'manual', group: consumerName },
+      );
+      this.logger.info(`Consuming from agent_inbound as ${consumerName}`);
+    } catch (err: any) {
+      this.logger.warn(`Failed to start consumer: ${err?.message}`);
+    }
+  }
+
+  private async handleInbound(message: Message<unknown>): Promise<void> {
+    try {
+      const envelope = this.extractEnvelope(message);
+
+      const { result, ctx } = await this.pipeline.process(envelope);
+
+      if (result === 'drop') {
+        await message.ack();
+        return;
+      }
+
+      // Deliver to Gateway
+      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,
+          },
+        });
+        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
+        this.logger.warn(`Gateway unavailable, stored pending event ${envelope.id}`);
+      }
+    } catch (err) {
+      this.logger.error('Failed to process message', err);
+      await message.nack(true);
+    }
+  }
+
+  /**
+   * 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');
+  }
+
+  private formatMessage(envelope: NatsEventEnvelope): string {
+    return `[NATS:${envelope.subject}] ${JSON.stringify(envelope.payload)}`;
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.subscription) {
+      await this.subscription.unsubscribe();
+      this.subscription = null;
+    }
+  }
+}

package/sidecar/src/db/migrations/0000_complete_mulholland_black.sql

@@ -0,0 +1,5 @@
+CREATE TABLE `dedup_events` (
+	`event_id` text PRIMARY KEY NOT NULL,
+	`subject` text NOT NULL,
+	`seen_at` integer NOT NULL
+);

package/sidecar/src/db/migrations/0001_high_psylocke.sql

@@ -0,0 +1,9 @@
+CREATE TABLE `pending_events` (
+	`id` text PRIMARY KEY NOT NULL,
+	`session_key` text NOT NULL,
+	`subject` text NOT NULL,
+	`payload` text,
+	`priority` integer DEFAULT 5 NOT NULL,
+	`created_at` integer NOT NULL,
+	`delivered_at` integer
+);

package/sidecar/src/db/migrations/0002_common_stellaris.sql

@@ -0,0 +1 @@
+CREATE INDEX `dedup_events_seen_at_idx` ON `dedup_events` (`seen_at`);

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

@@ -0,0 +1,49 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "2749e002-09ea-408a-ace2-896e42924606",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "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": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

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

@@ -0,0 +1,109 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "6903e64d-62a4-48c6-a1e7-beacac0755ae",
+  "prevId": "2749e002-09ea-408a-ace2-896e42924606",
+  "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": {},
+      "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/0002_snapshot.json

@@ -0,0 +1,117 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "3836f3c7-1186-453d-bb01-c2f5e58a1f4f",
+  "prevId": "6903e64d-62a4-48c6-a1e7-beacac0755ae",
+  "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": {}
+    },
+    "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

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1773321063387,
+      "tag": "0000_complete_mulholland_black",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1773329422050,
+      "tag": "0001_high_psylocke",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1773334582658,
+      "tag": "0002_common_stellaris",
+      "breakpoints": true
+    }
+  ]
+}

package/sidecar/src/db/schema.ts

@@ -0,0 +1,22 @@
+import { sqliteTable, text, integer, index } from '@onebun/drizzle/sqlite';
+
+export const dedupEvents = sqliteTable('dedup_events', {
+  eventId: text('event_id').primaryKey(),
+  subject: text('subject').notNull(),
+  seenAt: integer('seen_at', { mode: 'timestamp_ms' }).notNull(),
+}, (table) => [
+  index('dedup_events_seen_at_idx').on(table.seenAt),
+]);
+
+export const pendingEvents = sqliteTable('pending_events', {
+  id: text('id').primaryKey(),
+  sessionKey: text('session_key').notNull(),
+  subject: text('subject').notNull(),
+  payload: text('payload', { mode: 'json' }).$type<unknown>(),
+  priority: integer('priority').notNull().default(5),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  deliveredAt: integer('delivered_at', { mode: 'timestamp_ms' }),
+});
+
+export type DbPendingEvent = typeof pendingEvents.$inferSelect;
+export type NewPendingEvent = typeof pendingEvents.$inferInsert;

package/sidecar/src/dedup/dedup.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@onebun/core';
+import { DedupService } from './dedup.service';
+import { DedupRepository } from './dedup.repository';
+
+@Module({
+  providers: [DedupService, DedupRepository],
+  exports: [DedupService],
+})
+export class DedupModule {}

package/sidecar/src/dedup/dedup.repository.ts

@@ -0,0 +1,29 @@
+import { Service, BaseService } from '@onebun/core';
+import { DrizzleService, eq, lt } from '@onebun/drizzle';
+import { dedupEvents } from '../db/schema';
+
+@Service()
+export class DedupRepository extends BaseService {
+  constructor(private db: DrizzleService) {
+    super();
+  }
+
+  async isDuplicate(eventId: string): Promise<boolean> {
+    const rows = await this.db.select().from(dedupEvents).where(eq(dedupEvents.eventId, eventId)).limit(1);
+    return rows.length > 0;
+  }
+
+  async markSeen(eventId: string, subject: string): Promise<void> {
+    await this.db.insert(dedupEvents).values({
+      eventId,
+      subject,
+      seenAt: new Date(),
+    }).onConflictDoNothing();
+  }
+
+  async cleanup(ttlSeconds: number): Promise<number> {
+    const cutoff = new Date(Date.now() - ttlSeconds * 1000);
+    const result = await this.db.delete(dedupEvents).where(lt(dedupEvents.seenAt, cutoff)) as unknown as { changes: number };
+    return result.changes;
+  }
+}

package/sidecar/src/dedup/dedup.service.ts

@@ -0,0 +1,38 @@
+import { Service, BaseService, type OnModuleInit, type OnModuleDestroy } from '@onebun/core';
+import { DedupRepository } from './dedup.repository';
+
+@Service()
+export class DedupService extends BaseService implements OnModuleInit, OnModuleDestroy {
+  private ttlSeconds!: number;
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+
+  constructor(private repo: DedupRepository) {
+    super();
+  }
+
+  async onModuleInit(): Promise<void> {
+    this.ttlSeconds = this.config.get('dedup.ttlSeconds');
+    const cleanupIntervalMs = this.config.get('dedup.cleanupIntervalMs');
+
+    await this.cleanup();
+    this.cleanupTimer = setInterval(() => this.cleanup(), cleanupIntervalMs);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+  }
+
+  async isDuplicate(eventId: string, subject: string): Promise<boolean> {
+    const duplicate = await this.repo.isDuplicate(eventId);
+    if (duplicate) return true;
+    await this.repo.markSeen(eventId, subject);
+    return false;
+  }
+
+  async cleanup(): Promise<number> {
+    return this.repo.cleanup(this.ttlSeconds);
+  }
+}

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

@@ -0,0 +1,8 @@
+import { Module } from '@onebun/core';
+import { GatewayClientService } from './gateway-client.service';
+
+@Module({
+  providers: [GatewayClientService],
+  exports: [GatewayClientService],
+})
+export class GatewayClientModule {}

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

@@ -0,0 +1,131 @@
+import { Service, BaseService, type OnModuleInit, type OnModuleDestroy } from '@onebun/core';
+
+export interface GatewayInjectPayload {
+  target: string;
+  message: string;
+  metadata?: {
+    source: 'nats';
+    eventId: string;
+    subject: string;
+    priority: number;
+  };
+}
+
+@Service()
+export class GatewayClientService extends BaseService implements OnModuleInit, OnModuleDestroy {
+  private ws: WebSocket | null = null;
+  private connected = false;
+  private reconnectAttempt = 0;
+  private reconnectTimer: Timer | null = null;
+  private requestId = 0;
+  private wsUrl!: string;
+  private token!: string;
+
+  async onModuleInit(): Promise<void> {
+    this.wsUrl = this.config.get('gateway.wsUrl');
+    this.token = this.config.get('gateway.token');
+    if (this.wsUrl) {
+      this.connect();
+    }
+  }
+
+  private connect(): void {
+    try {
+      const url = this.token ? `${this.wsUrl}?token=${this.token}` : this.wsUrl;
+      this.ws = new WebSocket(url);
+
+      this.ws.onopen = () => {
+        this.logger.info('Gateway WebSocket connected');
+        this.reconnectAttempt = 0;
+        this.sendConnect();
+      };
+
+      this.ws.onmessage = (event) => {
+        this.handleMessage(event);
+      };
+
+      this.ws.onclose = () => {
+        this.connected = false;
+        this.scheduleReconnect();
+      };
+
+      this.ws.onerror = () => {
+        this.logger.warn('Gateway WebSocket error');
+        this.connected = false;
+      };
+    } catch {
+      this.logger.warn('Failed to connect to Gateway WebSocket');
+      this.scheduleReconnect();
+    }
+  }
+
+  private handleMessage(event: { data: unknown }): void {
+    try {
+      const frame = JSON.parse(String(event.data));
+      if (frame.type === 'res' && frame.ok) {
+        this.connected = true;
+      }
+    } catch {
+      // ignore parse errors
+    }
+  }
+
+  private sendConnect(): void {
+    this.send({
+      type: 'req',
+      id: ++this.requestId,
+      method: 'connect',
+      params: {},
+    });
+  }
+
+  private send(frame: unknown): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(frame));
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) return;
+    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempt), 30000);
+    this.reconnectAttempt++;
+    this.logger.debug(`Reconnecting to Gateway in ${delay}ms (attempt ${this.reconnectAttempt})`);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+
+  async inject(payload: GatewayInjectPayload): Promise<void> {
+    if (!this.isAlive()) {
+      throw new Error('Gateway WebSocket not connected');
+    }
+    this.send({
+      type: 'req',
+      id: ++this.requestId,
+      method: 'send',
+      params: {
+        target: payload.target,
+        message: payload.message,
+        metadata: payload.metadata,
+        idempotencyKey: payload.metadata?.eventId ?? String(this.requestId),
+      },
+    });
+  }
+
+  isAlive(): boolean {
+    return this.connected && this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.connected = false;
+  }
+}