@omnixal/openclaw-nats-plugin 0.1.0

package/sidecar/src/health/health.controller.ts

@@ -0,0 +1,15 @@
+import { Controller, Get, BaseController, type OneBunResponse } from '@onebun/core';
+import { HealthService } from './health.service';
+
+@Controller('/api/health')
+export class HealthController extends BaseController {
+  constructor(private healthService: HealthService) {
+    super();
+  }
+
+  @Get('/')
+  async getHealth(): Promise<OneBunResponse> {
+    const status = await this.healthService.getStatus();
+    return this.success(status);
+  }
+}

package/sidecar/src/health/health.module.ts

@@ -0,0 +1,13 @@
+import { Module } from '@onebun/core';
+import { HealthController } from './health.controller';
+import { HealthService } from './health.service';
+import { NatsStreamsModule } from '../nats-streams/nats-streams.module';
+import { GatewayClientModule } from '../gateway/gateway-client.module';
+import { PendingModule } from '../pending/pending.module';
+
+@Module({
+  imports: [NatsStreamsModule, GatewayClientModule, PendingModule],
+  controllers: [HealthController],
+  providers: [HealthService],
+})
+export class HealthModule {}

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

@@ -0,0 +1,51 @@
+import { Service, BaseService } from '@onebun/core';
+import { NatsAdapterService } from '../nats-streams/nats-adapter.service';
+import { GatewayClientService } from '../gateway/gateway-client.service';
+import { PendingService } from '../pending/pending.service';
+
+export interface HealthStatus {
+  nats: { connected: boolean; url: string };
+  gateway: { connected: boolean; url: string };
+  pendingCount: number;
+  uptimeSeconds: number;
+  config: {
+    streams: string[];
+    consumerName: string;
+    dedupTtlSeconds: number;
+  };
+}
+
+@Service()
+export class HealthService extends BaseService {
+  private readonly startedAt = Date.now();
+
+  constructor(
+    private nats: NatsAdapterService,
+    private gateway: GatewayClientService,
+    private pending: PendingService,
+  ) {
+    super();
+  }
+
+  async getStatus(): Promise<HealthStatus> {
+    const pendingCount = await this.pending.countPending();
+
+    return {
+      nats: {
+        connected: this.nats.isConnected(),
+        url: this.config.get('nats.servers'),
+      },
+      gateway: {
+        connected: this.gateway.isAlive(),
+        url: this.config.get('gateway.wsUrl'),
+      },
+      pendingCount,
+      uptimeSeconds: Math.floor((Date.now() - this.startedAt) / 1000),
+      config: {
+        streams: ['agent_inbound', 'agent_events', 'agent_dlq'],
+        consumerName: this.config.get('consumer.name'),
+        dedupTtlSeconds: this.config.get('dedup.ttlSeconds'),
+      },
+    };
+  }
+}

package/sidecar/src/index.ts

@@ -0,0 +1,21 @@
+import { OneBunApplication } from '@onebun/core';
+import { AppModule } from './app.module';
+import { envSchema } from './config';
+
+const app = new OneBunApplication(AppModule, {
+  development: Bun.env.NODE_ENV !== 'production',
+  envSchema,
+  envOptions: {
+    loadDotEnv: true,
+  },
+});
+
+app.start()
+  .then(() => {
+    const logger = app.getLogger({ className: 'Bootstrap' });
+    logger.info('nats-sidecar started');
+  })
+  .catch((error) => {
+    console.error('Failed to start:', error);
+    process.exit(1);
+  });

package/sidecar/src/nats-streams/nats-adapter.service.ts

@@ -0,0 +1,133 @@
+import { Service, BaseService, type OnModuleInit, type OnModuleDestroy } from '@onebun/core';
+import type { Subscription, MessageHandler, SubscribeOptions, PublishOptions } from '@onebun/core';
+import { JetStreamQueueAdapter, type JetStreamAdapterOptions } from '@onebun/nats';
+
+/**
+ * Manages the JetStreamQueueAdapter lifecycle with graceful degradation.
+ *
+ * When NATS is unavailable, the service runs in degraded mode:
+ * publish and subscribe operations are silently dropped with warnings.
+ *
+ * Also ensures additional streams (agent_events, agent_dlq) exist.
+ */
+@Service()
+export class NatsAdapterService extends BaseService implements OnModuleInit, OnModuleDestroy {
+  private adapter: JetStreamQueueAdapter | null = null;
+  private _connected = false;
+
+  async onModuleInit(): Promise<void> {
+    const servers = this.config.get('nats.servers');
+    const reconnectTimeWait = this.config.get('nats.reconnectDelayMs');
+    const maxReconnectAttempts = this.config.get('nats.maxReconnectAttempts');
+    const ackWaitMs = this.config.get('consumer.ackWaitMs');
+    const maxDeliver = this.config.get('consumer.maxDeliver');
+
+    const options: JetStreamAdapterOptions = {
+      servers,
+      maxReconnectAttempts,
+      reconnectTimeWait,
+      stream: 'agent_inbound',
+      createStream: true,
+      streamConfig: {
+        subjects: ['agent.inbound.>'],
+        retention: 'workqueue',
+        storage: 'file',
+        replicas: 1,
+      },
+      consumerConfig: {
+        ackWait: ackWaitMs * 1_000_000, // ms → ns
+        maxDeliver,
+      },
+    };
+
+    this.adapter = new JetStreamQueueAdapter(options);
+
+    try {
+      await this.adapter.connect();
+      this._connected = true;
+      await this.ensureExtraStreams();
+      this.logger.info('NATS JetStream connected');
+    } catch (err: any) {
+      this.logger.warn(`NATS connection failed, running in degraded mode: ${err?.message}`);
+      this.adapter = null;
+      this._connected = false;
+    }
+  }
+
+  isConnected(): boolean {
+    return this._connected && this.adapter !== null && this.adapter.isConnected();
+  }
+
+  async publish<T>(pattern: string, data: T, options?: PublishOptions): Promise<string | null> {
+    if (!this.adapter || !this.isConnected()) {
+      this.logger.warn(`NATS not connected, dropping publish to ${pattern}`);
+      return null;
+    }
+    return await this.adapter.publish(pattern, data, options);
+  }
+
+  async subscribe<T>(
+    pattern: string,
+    handler: MessageHandler<T>,
+    options?: SubscribeOptions,
+  ): Promise<Subscription | null> {
+    if (!this.adapter || !this.isConnected()) {
+      this.logger.warn(`NATS not connected, cannot subscribe to ${pattern}`);
+      return null;
+    }
+    return await this.adapter.subscribe(pattern, handler, options);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.adapter) {
+      await this.adapter.disconnect();
+      this.logger.info('NATS JetStream disconnected');
+    }
+  }
+
+  private async ensureExtraStreams(): Promise<void> {
+    try {
+      const nc = (this.adapter as any)?.client?.getConnection?.();
+      if (!nc) {
+        this.logger.warn('Cannot access NATS connection for stream creation');
+        return;
+      }
+
+      const jsModule = await import('@nats-io/jetstream');
+      const jsm = await jsModule.jetstreamManager(nc);
+
+      const SEVEN_DAYS_NS = 7 * 24 * 60 * 60 * 1e9;
+
+      await this.ensureStream(jsm, {
+        name: 'agent_events',
+        subjects: ['agent.events.>'],
+        retention: 'limits',
+        max_age: SEVEN_DAYS_NS,
+        storage: 'file',
+        num_replicas: 1,
+      });
+
+      await this.ensureStream(jsm, {
+        name: 'agent_dlq',
+        subjects: ['agent.dlq.>'],
+        retention: 'limits',
+        max_age: SEVEN_DAYS_NS,
+        storage: 'file',
+        num_replicas: 1,
+      });
+
+      this.logger.info('Additional JetStream streams ensured (agent_events, agent_dlq)');
+    } catch (err: any) {
+      this.logger.warn(`Failed to ensure extra streams: ${err?.message}`);
+    }
+  }
+
+  private async ensureStream(jsm: any, config: Record<string, any>): Promise<void> {
+    try {
+      await jsm.streams.info(config.name);
+      await jsm.streams.update(config.name, config);
+    } catch {
+      await jsm.streams.add(config);
+    }
+  }
+}

package/sidecar/src/nats-streams/nats-streams.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@onebun/core';
+import { NatsAdapterService } from './nats-adapter.service';
+
+@Module({
+  providers: [NatsAdapterService],
+  exports: [NatsAdapterService],
+})
+export class NatsStreamsModule {}

package/sidecar/src/pending/pending.controller.ts

@@ -0,0 +1,24 @@
+import { Controller, Get, Post, Body, Param, BaseController, UseMiddleware, type OneBunResponse } from '@onebun/core';
+import { PendingService } from './pending.service';
+import { ApiKeyMiddleware } from '../auth/api-key.middleware';
+import { markDeliveredBodySchema, type MarkDeliveredBody } from '../validation/schemas';
+
+@Controller('/api/pending')
+@UseMiddleware(ApiKeyMiddleware)
+export class PendingController extends BaseController {
+  constructor(private pendingService: PendingService) {
+    super();
+  }
+
+  @Get('/:sessionKey')
+  async fetchPending(@Param('sessionKey') sessionKey: string): Promise<OneBunResponse> {
+    const events = await this.pendingService.fetchPending(sessionKey);
+    return this.success(events);
+  }
+
+  @Post('/mark-delivered')
+  async markDelivered(@Body(markDeliveredBodySchema) body: MarkDeliveredBody): Promise<OneBunResponse> {
+    await this.pendingService.markDelivered(body.ids);
+    return this.success({ marked: body.ids.length });
+  }
+}

package/sidecar/src/pending/pending.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@onebun/core';
+import { PendingController } from './pending.controller';
+import { PendingService } from './pending.service';
+import { PendingRepository } from './pending.repository';
+
+@Module({
+  controllers: [PendingController],
+  providers: [PendingService, PendingRepository],
+  exports: [PendingService],
+})
+export class PendingModule {}

package/sidecar/src/pending/pending.repository.ts

@@ -0,0 +1,62 @@
+import { Service, BaseService } from '@onebun/core';
+import { DrizzleService, eq, and, isNull, inArray, lt, desc, sql } from '@onebun/drizzle';
+import { pendingEvents, type DbPendingEvent } from '../db/schema';
+
+@Service()
+export class PendingRepository extends BaseService {
+  constructor(private db: DrizzleService) {
+    super();
+  }
+
+  async addPending(event: {
+    id: string;
+    sessionKey: string;
+    subject: string;
+    payload: unknown;
+    priority: number;
+  }): Promise<void> {
+    await this.db
+      .insert(pendingEvents)
+      .values({
+        id: event.id,
+        sessionKey: event.sessionKey,
+        subject: event.subject,
+        payload: event.payload,
+        priority: event.priority,
+        createdAt: new Date(),
+      })
+      .onConflictDoNothing();
+  }
+
+  async fetchPending(sessionKey: string): Promise<DbPendingEvent[]> {
+    return this.db
+      .select()
+      .from(pendingEvents)
+      .where(and(eq(pendingEvents.sessionKey, sessionKey), isNull(pendingEvents.deliveredAt)))
+      .orderBy(desc(pendingEvents.priority));
+  }
+
+  async markDelivered(ids: string[]): Promise<void> {
+    if (ids.length === 0) return;
+    await this.db
+      .update(pendingEvents)
+      .set({ deliveredAt: new Date() })
+      .where(inArray(pendingEvents.id, ids));
+  }
+
+  async countPending(): Promise<number> {
+    const result = await this.db
+      .select({ count: sql<number>`count(*)` })
+      .from(pendingEvents)
+      .where(isNull(pendingEvents.deliveredAt));
+    return result[0]?.count ?? 0;
+  }
+
+  async cleanup(ttlSeconds: number): Promise<number> {
+    const cutoff = new Date(Date.now() - ttlSeconds * 1000);
+    const result = await this.db
+      .delete(pendingEvents)
+      .where(and(lt(pendingEvents.deliveredAt, cutoff))) as unknown as { changes: number };
+    return result.changes;
+  }
+}

package/sidecar/src/pending/pending.service.ts

@@ -0,0 +1,38 @@
+import { Service, BaseService } from '@onebun/core';
+import { PendingRepository } from './pending.repository';
+import type { NatsEventEnvelope } from '../publisher/envelope';
+import type { DbPendingEvent } from '../db/schema';
+
+@Service()
+export class PendingService extends BaseService {
+  constructor(private repo: PendingRepository) {
+    super();
+  }
+
+  async addPending(envelope: NatsEventEnvelope): Promise<void> {
+    await this.repo.addPending({
+      id: envelope.id,
+      sessionKey: envelope.sessionKey ?? 'default',
+      subject: envelope.subject,
+      payload: envelope.payload,
+      priority: envelope.meta?.priority ?? 5,
+    });
+  }
+
+  async fetchPending(sessionKey: string): Promise<DbPendingEvent[]> {
+    return this.repo.fetchPending(sessionKey);
+  }
+
+  async markDelivered(ids: string[]): Promise<void> {
+    return this.repo.markDelivered(ids);
+  }
+
+  async countPending(): Promise<number> {
+    return this.repo.countPending();
+  }
+
+  async cleanup(): Promise<number> {
+    const ttl = this.config.get('dedup.ttlSeconds');
+    return this.repo.cleanup(ttl);
+  }
+}

package/sidecar/src/pre-handlers/dedup.handler.ts

@@ -0,0 +1,22 @@
+import { Service, BaseService } from '@onebun/core';
+import { DedupService } from '../dedup/dedup.service';
+import type { NatsEventEnvelope } from '../publisher/envelope';
+import type { PreHandler, PipelineContext } from './pre-handler.interface';
+
+@Service()
+export class DedupHandler extends BaseService implements PreHandler {
+  name = 'dedup';
+
+  constructor(private dedupService: DedupService) {
+    super();
+  }
+
+  async handle(msg: NatsEventEnvelope, _ctx: PipelineContext): Promise<'pass' | 'drop'> {
+    const isDup = await this.dedupService.isDuplicate(msg.id, msg.subject);
+    if (isDup) {
+      this.logger.debug(`Dropping duplicate event ${msg.id}`);
+      return 'drop';
+    }
+    return 'pass';
+  }
+}

package/sidecar/src/pre-handlers/enrich.handler.ts

@@ -0,0 +1,14 @@
+import { Service, BaseService } from '@onebun/core';
+import type { NatsEventEnvelope } from '../publisher/envelope';
+import type { PreHandler, PipelineContext } from './pre-handler.interface';
+
+@Service()
+export class EnrichHandler extends BaseService implements PreHandler {
+  name = 'enrich';
+
+  async handle(msg: NatsEventEnvelope, ctx: PipelineContext): Promise<'pass' | 'drop'> {
+    ctx.enrichments['processedAt'] = new Date().toISOString();
+    ctx.enrichments['source'] = msg.source;
+    return 'pass';
+  }
+}

package/sidecar/src/pre-handlers/filter.handler.ts

@@ -0,0 +1,39 @@
+import { Service, BaseService } from '@onebun/core';
+import type { NatsEventEnvelope } from '../publisher/envelope';
+import type { PreHandler, PipelineContext } from './pre-handler.interface';
+
+interface FilterRule {
+  subjectPattern: string;
+  action: 'pass' | 'drop';
+  priority: number;
+}
+
+@Service()
+export class FilterHandler extends BaseService implements PreHandler {
+  name = 'filter';
+
+  private rules: FilterRule[] = [];
+
+  async handle(msg: NatsEventEnvelope, _ctx: PipelineContext): Promise<'pass' | 'drop'> {
+    for (const rule of this.rules) {
+      if (this.matchSubject(msg.subject, rule.subjectPattern)) {
+        return rule.action;
+      }
+    }
+    return 'pass'; // default: pass everything
+  }
+
+  matchSubject(subject: string, pattern: string): boolean {
+    // NATS-style subject matching:
+    // '*' matches a single token, '>' matches one or more tokens at the end
+    const subjectParts = subject.split('.');
+    const patternParts = pattern.split('.');
+    for (let i = 0; i < patternParts.length; i++) {
+      if (patternParts[i] === '>') return true; // matches rest
+      if (i >= subjectParts.length) return false;
+      if (patternParts[i] === '*') continue; // matches single token
+      if (patternParts[i] !== subjectParts[i]) return false;
+    }
+    return subjectParts.length === patternParts.length;
+  }
+}

package/sidecar/src/pre-handlers/pipeline.service.ts

@@ -0,0 +1,38 @@
+import { Service, BaseService } from '@onebun/core';
+import type { NatsEventEnvelope } from '../publisher/envelope';
+import type { PreHandler, PipelineContext } from './pre-handler.interface';
+import { DedupHandler } from './dedup.handler';
+import { FilterHandler } from './filter.handler';
+import { EnrichHandler } from './enrich.handler';
+import { PriorityHandler } from './priority.handler';
+
+@Service()
+export class PipelineService extends BaseService {
+  constructor(
+    private dedupHandler: DedupHandler,
+    private filterHandler: FilterHandler,
+    private enrichHandler: EnrichHandler,
+    private priorityHandler: PriorityHandler,
+  ) {
+    super();
+  }
+
+  async process(envelope: NatsEventEnvelope): Promise<{ result: 'pass' | 'drop'; ctx: PipelineContext }> {
+    const ctx: PipelineContext = { enrichments: {} };
+    const handlers: PreHandler[] = [
+      this.dedupHandler,
+      this.filterHandler,
+      this.enrichHandler,
+      this.priorityHandler,
+    ];
+
+    for (const handler of handlers) {
+      const result = await handler.handle(envelope, ctx);
+      if (result === 'drop') {
+        this.logger.debug(`Pipeline dropped by ${handler.name}`, { id: envelope.id });
+        return { result: 'drop', ctx };
+      }
+    }
+    return { result: 'pass', ctx };
+  }
+}

package/sidecar/src/pre-handlers/pre-handler.interface.ts

@@ -0,0 +1,10 @@
+import type { NatsEventEnvelope } from '../publisher/envelope';
+
+export interface PipelineContext {
+  enrichments: Record<string, unknown>;
+}
+
+export interface PreHandler {
+  name: string;
+  handle(msg: NatsEventEnvelope, ctx: PipelineContext): Promise<'pass' | 'drop'>;
+}

package/sidecar/src/pre-handlers/pre-handlers.module.ts

@@ -0,0 +1,14 @@
+import { Module } from '@onebun/core';
+import { DedupModule } from '../dedup/dedup.module';
+import { PipelineService } from './pipeline.service';
+import { DedupHandler } from './dedup.handler';
+import { FilterHandler } from './filter.handler';
+import { EnrichHandler } from './enrich.handler';
+import { PriorityHandler } from './priority.handler';
+
+@Module({
+  imports: [DedupModule],
+  providers: [PipelineService, DedupHandler, FilterHandler, EnrichHandler, PriorityHandler],
+  exports: [PipelineService],
+})
+export class PreHandlersModule {}

package/sidecar/src/pre-handlers/priority.handler.ts

@@ -0,0 +1,14 @@
+import { Service, BaseService } from '@onebun/core';
+import type { NatsEventEnvelope } from '../publisher/envelope';
+import type { PreHandler, PipelineContext } from './pre-handler.interface';
+
+@Service()
+export class PriorityHandler extends BaseService implements PreHandler {
+  name = 'priority';
+
+  async handle(msg: NatsEventEnvelope, ctx: PipelineContext): Promise<'pass' | 'drop'> {
+    const raw = msg.meta?.priority ?? 5;
+    ctx.enrichments['priority'] = Math.max(1, Math.min(10, raw));
+    return 'pass';
+  }
+}

package/sidecar/src/publisher/envelope.ts

@@ -0,0 +1,36 @@
+import { ulid } from 'ulid';
+
+export interface EnvelopeMeta {
+  priority?: number;
+  traceId?: string;
+  correlationId?: string;
+}
+
+export interface NatsEventEnvelope {
+  id: string;
+  subject: string;
+  timestamp: string;
+  source: string;
+  sessionKey?: string;
+  agentTarget?: string;
+  payload: unknown;
+  meta?: EnvelopeMeta;
+}
+
+export function createEnvelope(
+  subject: string,
+  payload: unknown,
+  meta?: EnvelopeMeta,
+  options?: { sessionKey?: string; agentTarget?: string; source?: string },
+): NatsEventEnvelope {
+  return {
+    id: ulid(),
+    subject,
+    timestamp: new Date().toISOString(),
+    source: options?.source ?? 'openclaw-plugin',
+    sessionKey: options?.sessionKey,
+    agentTarget: options?.agentTarget,
+    payload,
+    meta: meta ? { priority: meta.priority ?? 5, ...meta } : { priority: 5 },
+  };
+}

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

@@ -0,0 +1,21 @@
+import { Controller, Post, Body, BaseController, UseMiddleware, type OneBunResponse } from '@onebun/core';
+import { PublisherService } from './publisher.service';
+import { ApiKeyMiddleware } from '../auth/api-key.middleware';
+import { publishBodySchema, type PublishBody } from '../validation/schemas';
+
+@Controller('/api/publish')
+@UseMiddleware(ApiKeyMiddleware)
+export class PublisherController extends BaseController {
+  constructor(private publisherService: PublisherService) {
+    super();
+  }
+
+  @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);
+    }
+    await this.publisherService.publish(body.subject, body.payload, body.meta);
+    return this.success({ published: true });
+  }
+}

package/sidecar/src/publisher/publisher.module.ts

@@ -0,0 +1,12 @@
+import { Module } from '@onebun/core';
+import { PublisherService } from './publisher.service';
+import { PublisherController } from './publisher.controller';
+import { NatsStreamsModule } from '../nats-streams/nats-streams.module';
+
+@Module({
+  imports: [NatsStreamsModule],
+  controllers: [PublisherController],
+  providers: [PublisherService],
+  exports: [PublisherService],
+})
+export class PublisherModule {}

package/sidecar/src/publisher/publisher.service.ts

@@ -0,0 +1,20 @@
+import { Service, BaseService } from '@onebun/core';
+import { NatsAdapterService } from '../nats-streams/nats-adapter.service';
+import { createEnvelope, type EnvelopeMeta } from './envelope';
+
+@Service()
+export class PublisherService extends BaseService {
+  constructor(private natsAdapter: NatsAdapterService) {
+    super();
+  }
+
+  async publish(subject: string, payload: unknown, meta?: EnvelopeMeta): Promise<void> {
+    if (!this.natsAdapter.isConnected()) {
+      this.logger.warn(`NATS not connected, dropping publish to ${subject}`);
+      return;
+    }
+    const envelope = createEnvelope(subject, payload, meta);
+    await this.natsAdapter.publish(subject, envelope);
+    this.logger.debug(`Published to ${subject}`, { id: envelope.id });
+  }
+}

package/sidecar/src/validation/schemas.ts

@@ -0,0 +1,19 @@
+import { type } from 'arktype';
+
+export const publishBodySchema = type({
+  subject: 'string',
+  payload: 'unknown',
+  'meta?': {
+    'priority?': 'number',
+    'traceId?': 'string',
+    'correlationId?': 'string',
+  },
+});
+
+export type PublishBody = typeof publishBodySchema.infer;
+
+export const markDeliveredBodySchema = type({
+  ids: 'string[]',
+});
+
+export type MarkDeliveredBody = typeof markDeliveredBodySchema.infer;