@lobu/gateway 3.0.5 → 3.0.6

package/src/gateway/job-router.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env bun
+
+import { createLogger } from "@lobu/core";
+import type { IMessageQueue } from "../infrastructure/queue";
+import type { ISessionManager } from "../session";
+import type { WorkerConnectionManager } from "./connection-manager";
+
+const logger = createLogger("worker-job-router");
+
+interface PendingJob {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timeout: NodeJS.Timeout;
+  jobId: string;
+}
+
+/**
+ * Routes jobs from queues to workers via SSE connections
+ * Manages job acknowledgments and timeouts
+ */
+export class WorkerJobRouter {
+  private pendingJobs: Map<string, PendingJob> = new Map(); // In-memory timeouts only
+
+  constructor(
+    private queue: IMessageQueue,
+    private connectionManager: WorkerConnectionManager,
+    _sessionManager: ISessionManager
+  ) {}
+
+  /**
+   * Register a worker to receive jobs from its deployment queue
+   * Each worker listens on its own queue: thread_message_{deploymentName}
+   *
+   * Note: This is idempotent - BullMQ's queue.work() handles duplicate registrations gracefully.
+   * Safe to call multiple times (e.g., on worker reconnection or gateway restart).
+   */
+  async registerWorker(deploymentName: string): Promise<void> {
+    const queueName = `thread_message_${deploymentName}`;
+
+    // Create queue if it doesn't exist
+    await this.queue.createQueue(queueName);
+
+    // Register job handler (idempotent - BullMQ handles duplicates)
+    // Start paused so jobs aren't consumed before the SSE connection is live.
+    // The caller must call resumeWorker() after SSE connects.
+    await this.queue.work(
+      queueName,
+      async (job: unknown) => {
+        await this.handleJob(deploymentName, job);
+      },
+      { startPaused: true }
+    );
+
+    logger.info(`Registered worker for queue ${queueName}`);
+  }
+
+  /**
+   * Pause the BullMQ worker when SSE connection is lost
+   * This prevents jobs from being processed when worker can't receive them
+   */
+  async pauseWorker(deploymentName: string): Promise<void> {
+    const queueName = `thread_message_${deploymentName}`;
+    await this.queue.pauseWorker(queueName);
+    logger.info(
+      `Paused job processing for ${deploymentName} - worker disconnected`
+    );
+  }
+
+  /**
+   * Resume the BullMQ worker when SSE connection is established
+   * Jobs will now be processed and sent to the worker
+   */
+  async resumeWorker(deploymentName: string): Promise<void> {
+    const queueName = `thread_message_${deploymentName}`;
+    await this.queue.resumeWorker(queueName);
+    logger.info(
+      `Resumed job processing for ${deploymentName} - worker connected`
+    );
+  }
+
+  /**
+   * Handle a job from the queue and route it to the worker.
+   *
+   * Sends the job via SSE and waits for a delivery receipt from the worker.
+   * If the worker doesn't acknowledge within the timeout, the job is retried
+   * by BullMQ. This prevents jobs from being silently lost when sent to a
+   * stale SSE connection (e.g., after a container dies without cleanly closing TCP).
+   */
+  private async handleJob(deploymentName: string, job: unknown): Promise<void> {
+    const connection = this.connectionManager.getConnection(deploymentName);
+
+    if (!connection) {
+      logger.warn(
+        `No connection for deployment ${deploymentName}, job will be retried`
+      );
+      throw new Error("Worker not connected");
+    }
+
+    // Extract job data and ID
+    const jobData = (job as { data?: unknown }).data;
+    const jobId =
+      (job as { id?: string }).id ||
+      `job-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+
+    // Send job to worker via SSE with jobId wrapped in payload
+    const jobPayload =
+      typeof jobData === "object" && jobData !== null
+        ? { payload: jobData, jobId: jobId }
+        : { payload: { data: jobData }, jobId: jobId };
+
+    const sent = this.connectionManager.sendSSE(
+      connection.writer,
+      "job",
+      jobPayload
+    );
+    if (!sent) {
+      logger.warn(
+        `SSE write failed for job ${jobId} to ${deploymentName}, will retry`
+      );
+      throw new Error("SSE write failed - worker connection may be dead");
+    }
+    this.connectionManager.touchConnection(deploymentName);
+
+    // Wait for delivery receipt from worker. If the SSE connection is stale
+    // (container dead but TCP not yet closed), the worker will never ack and
+    // BullMQ will retry the job after the timeout.
+    await this.awaitDeliveryReceipt(jobId, deploymentName);
+  }
+
+  /**
+   * Wait for the worker to acknowledge receipt of a job.
+   * Rejects after timeout so BullMQ retries the job.
+   */
+  private awaitDeliveryReceipt(
+    jobId: string,
+    deploymentName: string
+  ): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingJobs.delete(jobId);
+        logger.warn(
+          `Job ${jobId} delivery receipt timeout - worker ${deploymentName} may be dead`
+        );
+        reject(
+          new Error(
+            `Delivery receipt timeout for job ${jobId} - worker may be dead`
+          )
+        );
+      }, 5000); // 5 second timeout for delivery receipt
+
+      this.pendingJobs.set(jobId, {
+        resolve: () => {
+          clearTimeout(timeout);
+          resolve();
+        },
+        reject: (err: Error) => {
+          clearTimeout(timeout);
+          reject(err);
+        },
+        timeout,
+        jobId,
+      });
+    });
+  }
+
+  /**
+   * Acknowledge job completion from worker
+   * Called when worker sends HTTP response
+   */
+  acknowledgeJob(jobId: string): void {
+    const pendingJob = this.pendingJobs.get(jobId);
+    if (pendingJob) {
+      clearTimeout(pendingJob.timeout);
+      pendingJob.resolve(undefined);
+      this.pendingJobs.delete(jobId);
+      logger.debug(`Job ${jobId} acknowledged`);
+    } else {
+      logger.warn(`Received acknowledgment for unknown job ${jobId}`);
+    }
+  }
+
+  /**
+   * Get number of pending jobs
+   */
+  getPendingJobCount(): number {
+    return this.pendingJobs.size;
+  }
+
+  /**
+   * Shutdown job router
+   */
+  shutdown(): void {
+    // Reject all pending jobs
+    for (const [jobId, pendingJob] of this.pendingJobs.entries()) {
+      clearTimeout(pendingJob.timeout);
+      pendingJob.reject(new Error("Job router shutting down"));
+      logger.debug(`Rejected pending job ${jobId} due to shutdown`);
+    }
+    this.pendingJobs.clear();
+  }
+}

package/src/gateway-main.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env bun
+
+import {
+  type AgentAccessStore,
+  type AgentConfigStore,
+  type AgentConnectionStore,
+  createLogger,
+  type SystemSkillEntry,
+} from "@lobu/core";
+import type { GatewayConfig } from "./config";
+import { type PlatformAdapter, platformRegistry } from "./platform";
+import { UnifiedThreadResponseConsumer } from "./platform/unified-thread-consumer";
+import { CoreServices } from "./services/core-services";
+
+const logger = createLogger("gateway");
+
+/**
+ * Main Gateway class that orchestrates all platform adapters
+ *
+ * Architecture:
+ * - CoreServices: Platform-agnostic services (Redis, MCP, Anthropic)
+ * - PlatformAdapters: Platform-specific integrations (Slack, Discord, etc.)
+ *
+ * Lifecycle:
+ * 1. Gateway initializes CoreServices
+ * 2. Platforms register themselves via registerPlatform()
+ * 3. Gateway calls initialize() on each platform with CoreServices
+ * 4. Gateway calls start() on each platform
+ */
+export interface GatewayOptions {
+  /** Agent settings + metadata store. Defaults to InMemoryAgentStore. */
+  configStore?: AgentConfigStore;
+  /** Connections + channel bindings store. Defaults to InMemoryAgentStore. */
+  connectionStore?: AgentConnectionStore;
+  /** Grants + user-agent associations store. Defaults to InMemoryAgentStore. */
+  accessStore?: AgentAccessStore;
+  /** Provide system skills programmatically (skips file loading). */
+  systemSkills?: SystemSkillEntry[];
+}
+
+export class Gateway {
+  private coreServices: CoreServices;
+  private platforms: Map<string, PlatformAdapter> = new Map();
+  private unifiedConsumer?: UnifiedThreadResponseConsumer;
+  private isRunning = false;
+
+  constructor(
+    private readonly config: GatewayConfig,
+    options?: GatewayOptions
+  ) {
+    this.coreServices = new CoreServices(config, {
+      configStore: options?.configStore,
+      connectionStore: options?.connectionStore,
+      accessStore: options?.accessStore,
+      systemSkills: options?.systemSkills,
+    });
+  }
+
+  /**
+   * Register a platform adapter
+   * Platforms register themselves via dependency injection
+   *
+   * @param platform - Platform adapter to register
+   * @returns This gateway for chaining
+   */
+  registerPlatform(platform: PlatformAdapter): this {
+    if (this.platforms.has(platform.name)) {
+      throw new Error(`Platform ${platform.name} is already registered`);
+    }
+
+    this.platforms.set(platform.name, platform);
+    // Also register in global platform registry for deployment managers
+    platformRegistry.register(platform);
+    logger.debug(`Platform registered: ${platform.name}`);
+    return this;
+  }
+
+  /**
+   * Start the gateway
+   * 1. Initialize core services
+   * 2. Initialize all platforms
+   * 3. Register instruction providers from platforms
+   * 4. Start all platforms
+   */
+  async start(): Promise<void> {
+    logger.debug("Starting gateway...");
+
+    // 1. Initialize core services (Redis, MCP, Anthropic, etc.)
+    await this.coreServices.initialize();
+
+    // 2. Initialize each platform with core services
+    for (const [name, platform] of this.platforms) {
+      logger.debug(`Initializing platform: ${name}`);
+      await platform.initialize(this.coreServices);
+    }
+
+    // 3. Register instruction providers from platforms
+    const instructionService = this.coreServices.getInstructionService();
+    if (instructionService) {
+      for (const [name, platform] of this.platforms) {
+        if (platform.getInstructionProvider) {
+          const provider = platform.getInstructionProvider();
+          if (provider) {
+            instructionService.registerPlatformProvider(name, provider);
+          }
+        }
+      }
+    }
+
+    // 4. Start all platforms
+    for (const [name, platform] of this.platforms) {
+      logger.debug(`Starting platform: ${name}`);
+      await platform.start();
+    }
+
+    // 5. Start unified thread response consumer
+    // Single consumer routes responses to platforms via registry
+    this.unifiedConsumer = new UnifiedThreadResponseConsumer(
+      this.coreServices.getQueue(),
+      platformRegistry
+    );
+    await this.unifiedConsumer.start();
+
+    this.isRunning = true;
+  }
+
+  /**
+   * Stop the gateway gracefully
+   * 1. Stop unified consumer if running
+   * 2. Stop all platforms
+   * 3. Shutdown core services
+   */
+  async stop(): Promise<void> {
+    logger.info("Stopping gateway...");
+
+    // Stop unified consumer if running
+    if (this.unifiedConsumer) {
+      logger.info("Stopping unified thread response consumer");
+      try {
+        await this.unifiedConsumer.stop();
+      } catch (error) {
+        logger.error("Failed to stop unified consumer:", error);
+      }
+    }
+
+    // Stop all platforms
+    for (const [name, platform] of this.platforms) {
+      logger.info(`Stopping platform: ${name}`);
+      try {
+        await platform.stop();
+      } catch (error) {
+        logger.error(`Failed to stop platform ${name}:`, error);
+      }
+    }
+
+    // Shutdown core services
+    await this.coreServices.shutdown();
+
+    this.isRunning = false;
+    logger.info("✅ Gateway stopped");
+  }
+
+  /**
+   * Get gateway status
+   */
+  getStatus(): {
+    isRunning: boolean;
+    platforms: string[];
+    config: Partial<GatewayConfig>;
+  } {
+    return {
+      isRunning: this.isRunning,
+      platforms: Array.from(this.platforms.keys()),
+      config: {
+        queues: this.config.queues,
+      },
+    };
+  }
+
+  /**
+   * Get core services (for platform adapters during initialization)
+   */
+  getCoreServices(): CoreServices {
+    return this.coreServices;
+  }
+
+  /**
+   * Get platform registry (for routes that need to access platform adapters)
+   */
+  getPlatformRegistry() {
+    return platformRegistry;
+  }
+
+  /**
+   * Get unified thread response consumer (for wiring Chat SDK response bridge)
+   */
+  getUnifiedConsumer() {
+    return this.unifiedConsumer;
+  }
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+
+/**
+ * Main entry point for Lobu Gateway
+ *
+ * When run directly (CLI mode): starts the gateway server.
+ * When imported as a library (embedded mode): exports Gateway, config builders,
+ * and the Hono app factory for mounting on a host server.
+ */
+
+// ── Primary API ─────────────────────────────────────────────────────────────
+
+export { Lobu, type LobuAgentConfig, type LobuConfig } from "./lobu";
+
+// ── Advanced (for custom setups) ────────────────────────────────────────────
+
+export { createGatewayApp, startGatewayServer } from "./cli/gateway";
+export {
+  type AgentConfig,
+  buildGatewayConfig,
+  type GatewayConfig,
+} from "./config";
+export { Gateway, type GatewayOptions } from "./gateway-main";
+export { CoreServices } from "./services/core-services";
+export { InMemoryAgentStore } from "./stores/in-memory-agent-store";
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export type {
+  AgentAccessStore,
+  AgentConfigStore,
+  AgentConnectionStore,
+  AgentMetadata,
+  AgentSettings,
+  AgentStore,
+} from "@lobu/core";
+
+// ── CLI mode (run directly, not when imported as library) ───────────────────
+if (require.main === module) {
+  import("./cli");
+}

package/src/infrastructure/queue/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Queue infrastructure
+ * Redis-based message queue using BullMQ
+ */
+
+export { QueueProducer } from "./queue-producer";
+export { RedisQueue, type RedisQueueConfig } from "./redis-queue";
+export type {
+  IMessageQueue,
+  QueueJob,
+  ThreadResponsePayload,
+} from "./types";

package/src/infrastructure/queue/queue-producer.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+
+import {
+  type AgentMcpConfig,
+  createLogger,
+  type NetworkConfig,
+  type NixConfig,
+} from "@lobu/core";
+import type { IMessageQueue } from "./types";
+
+const logger = createLogger("queue-producer");
+
+/**
+ * Job type for queue messages
+ * - message: Standard agent message execution
+ * - exec: Direct command execution in sandbox
+ */
+export type JobType = "message" | "exec";
+
+/**
+ * Universal message payload for all queue stages
+ * Used by: Slack events → Queue → Message Consumer → Job Router → Worker
+ */
+export interface MessagePayload {
+  // Core identifiers (used by gateway for routing)
+  userId: string; // Platform user ID
+  conversationId: string; // Conversation ID (must be root conversation ID)
+  messageId: string; // Individual message ID
+  channelId: string; // Platform channel ID
+  teamId: string; // Team/workspace ID (required for all platforms)
+  agentId: string; // Agent/session ID for isolation (universal identifier)
+
+  // Bot & platform info (passed through to worker)
+  botId: string; // Bot identifier
+  platform: string; // Platform name
+
+  // Message content (used by worker)
+  messageText: string; // The actual message text
+
+  // Platform-specific data (used by worker for context)
+  platformMetadata: Record<string, any>;
+
+  // Agent configuration (used by worker)
+  agentOptions: Record<string, any>;
+
+  // Per-agent network configuration for sandbox isolation
+  networkConfig?: NetworkConfig;
+
+  // Per-agent MCP configuration (additive to global MCPs)
+  mcpConfig?: AgentMcpConfig;
+
+  // Nix environment configuration for agent workspace
+  nixConfig?: NixConfig;
+
+  // Job type (default: "message")
+  jobType?: JobType;
+
+  // Exec-specific fields (only used when jobType === "exec")
+  execId?: string; // Unique ID for exec job (for response routing)
+  execCommand?: string; // Command to execute
+  execCwd?: string; // Working directory for command
+  execEnv?: Record<string, string>; // Additional environment variables
+  execTimeout?: number; // Timeout in milliseconds
+}
+
+/**
+ * Queue producer for dispatching messages to Redis queues
+ * Handles both direct_message and thread_message queues with bot isolation
+ */
+export class QueueProducer {
+  private queue: IMessageQueue;
+  private isInitialized = false;
+
+  constructor(queue: IMessageQueue) {
+    this.queue = queue;
+  }
+
+  /**
+   * Initialize the queue producer
+   * Creates required queues
+   */
+  async start(): Promise<void> {
+    try {
+      // Create the messages queue if it doesn't exist
+      await this.queue.createQueue("messages");
+      this.isInitialized = true;
+      logger.debug("Queue producer initialized");
+    } catch (error) {
+      logger.error("Failed to initialize queue producer:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Stop the queue producer (no-op since queue lifecycle is managed externally)
+   */
+  async stop(): Promise<void> {
+    this.isInitialized = false;
+    logger.debug("Queue producer stopped");
+  }
+
+  /**
+   * Enqueue any message (direct or thread) to the single 'messages' queue
+   * Orchestrator will determine if it needs to create a deployment or route to existing thread
+   */
+  async enqueueMessage(
+    payload: MessagePayload,
+    options?: {
+      priority?: number;
+      retryLimit?: number;
+      retryDelay?: number;
+      expireInSeconds?: number;
+    }
+  ): Promise<string> {
+    if (!this.isInitialized) {
+      throw new Error("Queue producer is not initialized");
+    }
+
+    try {
+      // All messages go to the single 'messages' queue
+      const jobId = await this.queue.send("messages", payload, {
+        priority: options?.priority || 0,
+        retryLimit: options?.retryLimit || 3,
+        retryDelay: options?.retryDelay || 30,
+        expireInSeconds: options?.expireInSeconds || 300, // 5 minutes = 300 seconds
+        singletonKey: `message-${payload.platform}-${payload.channelId}-${payload.conversationId}-${String(payload.messageId || Date.now()).replace(/:/g, "-")}`, // Prevent duplicates within canonical conversation identity
+      });
+
+      logger.info(
+        `Enqueued message job ${jobId} for user ${payload.userId}, conversation ${payload.conversationId}`
+      );
+      return jobId || "job-sent";
+    } catch (error) {
+      logger.error(
+        `Failed to enqueue message for user ${payload.userId}:`,
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Check if producer is initialized
+   */
+  isHealthy(): boolean {
+    return this.isInitialized && this.queue.isHealthy();
+  }
+}