Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
17.9 KB
Raw Blame
/**
 * MessageQueue — factory-only shim (Phase C).
 *
 * State has moved entirely to TaskLifecycle. This class now:
 *   1. Creates Task objects via three factory methods (unchanged API).
 *   2. Maintains taskInstanceIndex for Task-object lookup (getTask).
 *   3. Keeps a pendingQueue[] for ordering and lifecycle registration of
 *      tasks enqueued outside messageHandler (e.g. cronScheduler.executeJob).
 *   4. Delegates getStats() to TaskLifecycle.
 *   5. Subscribes to TaskLifecycle.on('transition') and re-emits legacy
 *      Node events so ActivityHub (eventWiring.ts) and cron cleanup
 *      (main.ts) continue to receive events unchanged.
 *
 * Deleted: queue[], processing, completed[], failed[], taskIndex,
 *   peek, isEmpty, isProcessing, getCurrentTask, getPendingTasks,
 *   getCompletedTasks, getFailedTasks, clearHistory, sortQueue,
 *   trimCompletedHistory, trimFailedHistory.
 */
import { EventEmitter } from 'events'
import { v4 as uuidv4 } from 'uuid'
import type { CronJob } from '../agent/types'
import type { TaskLifecycle } from '../lifecycle/taskLifecycle'
import type { TransitionEvent } from '../lifecycle/types'
import { logger } from '../logger'
import { IncomingMessage } from '../server'
import {
  AdmissionOutcome,
  QueueEvent,
  QueueEventType,
  QueueStats,
  Task,
  TaskError,
  TaskPriority,
  TaskResponsePayload,
} from './types'

/**
 * Priority weights for sorting (higher = more urgent).
 * Used by the pendingQueue for the legacy dispatch path.
 */
const PRIORITY_WEIGHTS: Record<TaskPriority, number> = {
  urgent: 4,
  high: 3,
  normal: 2,
  low: 1,
}

/**
 * MessageQueue — factory + event-forwarding shim.
 */
export class MessageQueue extends EventEmitter {
  /** Ordering queue for the legacy non-SessionProcessor dispatch path. */
  private pendingQueue: Task[] = []
  private maxQueueSize: number

  /** Task-object index: provides getTask() without requiring TaskRecord to hold the full Task. */
  private taskInstanceIndex = new Map<string, Task>()

  /**
   * Delivery-identity index for cross-delivery duplicate suppression:
   * deliveryKey (channelType:channelId:sender:messageId) → admitted task id.
   * Entries live exactly as long as the lifecycle record: purged eagerly on
   * 'record:evicted' and lazily when admit() hits a stale mapping.
   */
  private deliveryIndex = new Map<string, string>()

  /** Reverse mapping (task id → deliveryKey) so eviction can purge deliveryIndex. */
  private deliveryKeyByTaskId = new Map<string, string>()

  private lifecycle: TaskLifecycle | null = null

  constructor(_maxCompletedHistory: number = 100, maxQueueSize: number = 1000) {
    super()
    this.maxQueueSize = maxQueueSize
  }

  /**
   * Wire TaskLifecycle for stats delegation and event forwarding.
   * Re-entrant: safe to call multiple times or with a different lifecycle instance.
   * Prior listeners are detached before new ones are attached so they don't accumulate
   * (PR-193 review #4).
   */
  setLifecycle(lifecycle: TaskLifecycle): void {
    // Detach prior listeners before re-attaching (idempotent on repeated calls;
    // also correctly re-points between two different lifecycle instances).
    if (this.lifecycle) {
      this.lifecycle.off('transition', this.handleLifecycleTransition)
      this.lifecycle.off('record:evicted', this.handleRecordEvicted)
    }

    this.lifecycle = lifecycle
    lifecycle.on('transition', this.handleLifecycleTransition)

    // Mirror TaskLifecycle's TTL eviction so Task references don't leak.
    // Promoted to a named bound method so .off() can remove it (PR-193 review #4).
    lifecycle.on('record:evicted', this.handleRecordEvicted)
  }

  // ---------------------------------------------------------------------------
  // Factories
  // ---------------------------------------------------------------------------

  createTaskFromMessage(
    message: IncomingMessage,
    responseCallback?: (payload: TaskResponsePayload) => Promise<void>,
    priority: TaskPriority = 'normal'
  ): Task {
    const task: Task = {
      id: uuidv4(),
      source: 'channel',
      sourceMessage: message,
      traceContext: message.traceContext ?? null,
      priority,
      status: 'pending',
      conversationHistory: [
        {
          role: 'user',
          content: message.content,
          timestamp: new Date(message.timestamp),
        },
      ],
      createdAt: new Date(),
      responseCallback,
    }
    this.taskInstanceIndex.set(task.id, task)
    return task
  }

  createTaskFromCron(
    cronJobId: string,
    content: string,
    origin?: CronJob['origin'],
    priority: TaskPriority = 'normal'
  ): Task {
    const task: Task = {
      id: uuidv4(),
      source: 'cron',
      cronJobId,
      sourceMessage: origin
        ? {
            channelType: origin.channelType,
            channelId: origin.channelId,
            sender: origin.sender,
            content: '',
            timestamp: new Date().toISOString(),
            messageId: `cron-${cronJobId}-${Date.now()}`,
            hostRef: '',
          }
        : undefined,
      priority,
      status: 'pending',
      conversationHistory: [
        {
          role: 'system',
          content: `Scheduled task triggered: ${cronJobId}`,
          timestamp: new Date(),
        },
        {
          role: 'user',
          content,
          timestamp: new Date(),
        },
      ],
      createdAt: new Date(),
    }
    this.taskInstanceIndex.set(task.id, task)
    return task
  }

  createInternalTask(content: string, priority: TaskPriority = 'low'): Task {
    const task: Task = {
      id: uuidv4(),
      source: 'internal',
      priority,
      status: 'pending',
      conversationHistory: [
        {
          role: 'system',
          content: 'Internal system task',
          timestamp: new Date(),
        },
        {
          role: 'user',
          content,
          timestamp: new Date(),
        },
      ],
      createdAt: new Date(),
    }
    this.taskInstanceIndex.set(task.id, task)
    return task
  }

  // ---------------------------------------------------------------------------
  // Admission sink — single registration point + duplicate suppression.
  // Production callers: messageHandler (channel, via admit) and
  // cronScheduler.executeJob (via the enqueue facade).
  // SessionProcessor is the sole execution engine; dequeue() is test-only.
  // ---------------------------------------------------------------------------

  /**
   * Delivery identity for cross-delivery duplicate suppression. Only tasks
   * carrying a non-empty client-supplied messageId participate — tasks
   * without a sourceMessage (internal) or with an empty messageId never dedupe.
   */
  static deliveryKeyOf(msg: IncomingMessage | undefined): string | null {
    if (!msg) return null
    const messageId = msg.messageId?.trim()
    if (!messageId) return null
    return `${msg.channelType}:${msg.channelId}:${msg.sender}:${messageId}`
  }

  /** Read-only replay check before model-selection side effects. */
  hasAdmittedDelivery(message: IncomingMessage): boolean {
    const key = MessageQueue.deliveryKeyOf(message)
    if (!key || !this.lifecycle) return false
    const id = this.deliveryIndex.get(key)
    return id !== undefined && this.lifecycle.getStatus(id) !== null
  }

  /**
   * Single admission sink for task execution.
   *
   * Rejects duplicates BEFORE any registration or queueing:
   *   1. duplicate_task_id — the id already has a lifecycle record.
   *   2. duplicate_delivery — the same delivery identity
   *      (channelType:channelId:sender:messageId) was already admitted under a
   *      different task id whose lifecycle record is still live.
   * Then applies the legacy queue-full bound, and finally admits: mirrors
   * task.status, pushes to the ordering queue, registers the lifecycle record
   * (Invariant I12: registration precedes the caller's SessionProcessor
   * dispatch), and records the delivery identity.
   *
   * Fail-loud: every suppression is logged with the task id, delivery key and
   * prior state — duplicates are never silently swallowed and never re-run.
   */
  admit(task: Task): AdmissionOutcome {
    const deliveryKey = MessageQueue.deliveryKeyOf(task.sourceMessage)

    if (this.lifecycle) {
      // Each prior record is read once and handed to the caller, which answers
      // the duplicate from it without a second lifecycle read.
      const prior = this.lifecycle.get(task.id)
      if (prior !== null) {
        logger.warn(
          { taskId: task.id, priorStatus: prior.status },
          'duplicate delivery suppressed: task already registered'
        )
        return {
          admitted: false,
          reason: 'duplicate_task_id',
          priorTaskId: task.id,
          prior,
        }
      }

      if (deliveryKey) {
        const priorTaskId = this.deliveryIndex.get(deliveryKey)
        if (priorTaskId && priorTaskId !== task.id) {
          const priorDelivery = this.lifecycle.get(priorTaskId)
          if (priorDelivery !== null) {
            logger.warn(
              { taskId: task.id, priorTaskId, priorStatus: priorDelivery.status },
              'duplicate delivery suppressed: delivery already admitted'
            )
            // The duplicate Task object will never run — drop its instance-index
            // entry (it has no lifecycle record, so eviction would never reap it).
            this.taskInstanceIndex.delete(task.id)
            return {
              admitted: false,
              reason: 'duplicate_delivery',
              priorTaskId,
              prior: priorDelivery,
            }
          }
          // The prior record was TTL-evicted — the mapping is stale. Purge it
          // and admit this delivery as new work.
          this.deliveryIndex.delete(deliveryKey)
          this.deliveryKeyByTaskId.delete(priorTaskId)
        }
      }
    }

    if (this.pendingQueue.length >= this.maxQueueSize) {
      logger.warn({ taskId: task.id, maxQueueSize: this.maxQueueSize }, 'Task rejected: queue full')
      this.emitEvent('queue:full', task)
      // C1: queue_full is NOT a no-op — the caller (messageHandler) still
      // registers this task's lifecycle record and dispatches it via
      // SessionProcessor (legacy contract). So it DOES execute, and its
      // delivery identity must be recorded here; otherwise a same-messageId
      // wake-retry would find no deliveryIndex entry, admit as new work, and
      // run a SECOND execution (incl. MCP tool side-effects). Recording it now
      // makes the retry dedup deterministically (duplicate_delivery), matching
      // the admitted-path behavior. The mapping resolves against the record the
      // caller registers immediately after this returns.
      if (this.lifecycle && deliveryKey && !this.deliveryIndex.has(deliveryKey)) {
        this.deliveryIndex.set(deliveryKey, task.id)
        this.deliveryKeyByTaskId.set(task.id, deliveryKey)
      }
      return { admitted: false, reason: 'queue_full' }
    }

    // eslint-disable-next-line no-restricted-syntax -- Phase C shim: TaskLifecycle is the authoritative writer; this mirrors task.status for legacy consumers (spec §4.2)
    task.status = 'pending'
    this.pendingQueue.push(task)
    this.pendingQueue.sort((a, b) => {
      const diff = PRIORITY_WEIGHTS[b.priority] - PRIORITY_WEIGHTS[a.priority]
      return diff !== 0 ? diff : a.createdAt.getTime() - b.createdAt.getTime()
    })

    // Single registration point (Invariant I12): admission is the only place a
    // production task acquires its lifecycle record. A register() that lands on
    // an existing id can only be a duplicate — admit() rejected those above.
    this.lifecycle?.register(task)
    if (this.lifecycle && deliveryKey) {
      this.deliveryIndex.set(deliveryKey, task.id)
      this.deliveryKeyByTaskId.set(task.id, deliveryKey)
    }

    logger.info({ taskId: task.id, source: task.source, priority: task.priority }, 'Task admitted')
    // task:added is forwarded from lifecycle transition (null→pending) via handleLifecycleTransition.
    // Emit it directly here too for callers that set up lifecycle AFTER enqueue (e.g. tests).
    if (!this.lifecycle) {
      this.emitEvent('task:added', task)
    }
    return { admitted: true }
  }

  /**
   * Legacy boolean facade over admit(). Production caller: cronScheduler.executeJob
   * (cron messageIds are unique per fire, so cron never trips delivery dedupe).
   * messageHandler uses admit() directly so it can suppress duplicates loudly.
   */
  enqueue(task: Task): boolean {
    return this.admit(task).admitted
  }

  /**
   * Dequeue the next pending task for the legacy (non-SessionProcessor) dispatch path.
   * Transitions lifecycle to 'processing' and updates task.status.
   */
  dequeue(): Task | null {
    if (this.pendingQueue.length === 0) return null

    const task = this.pendingQueue.shift()!
    // eslint-disable-next-line no-restricted-syntax -- Phase C shim: TaskLifecycle is the authoritative writer; this mirrors task.status for legacy consumers (spec §4.2)
    task.status = 'processing'
    task.startedAt = new Date()
    this.lifecycle?.transition(task.id, 'processing', 'dispatched')

    logger.info({ taskId: task.id }, 'Task dequeued for processing')
    // task:started is forwarded from lifecycle transition via handleLifecycleTransition.
    if (!this.lifecycle) {
      this.emitEvent('task:started', task)
    }

    if (this.pendingQueue.length === 0) {
      this.emitEvent('queue:empty')
    }

    return task
  }

  /**
   * Mark a task completed. Transitions lifecycle; updates task.status.
   * Called by stateMachine.executeTask onComplete callback.
   */
  completeTask(task: Task): void {
    // eslint-disable-next-line no-restricted-syntax -- Phase C shim: TaskLifecycle is the authoritative writer; this mirrors task.status for legacy consumers (spec §4.2)
    task.status = 'completed'
    task.completedAt = new Date()
    this.lifecycle?.transition(task.id, 'completed', 'natural', {
      response: task.result?.response,
    })

    logger.info({ taskId: task.id }, 'Task completed')
    // task:completed forwarded via handleLifecycleTransition.
    if (!this.lifecycle) {
      this.emitEvent('task:completed', task)
    }

    if (this.pendingQueue.length === 0) {
      this.emitEvent('queue:drained')
    }
  }

  /**
   * Mark a task failed. No retries — LLM SDK handles retries internally.
   * Called by stateMachine.handleTaskFailure.
   */
  failTask(task: Task, error: TaskError): void {
    // eslint-disable-next-line no-restricted-syntax -- Phase C shim: TaskLifecycle is the authoritative writer; this mirrors task.status for legacy consumers (spec §4.2)
    task.status = 'failed'
    task.error = error
    task.completedAt = new Date()
    this.lifecycle?.transition(task.id, 'failed', `error:${error.code}`, { error })

    logger.info({ taskId: task.id, code: error.code }, 'Task failed')
    // task:failed forwarded via handleLifecycleTransition.
    if (!this.lifecycle) {
      this.emitEvent('task:failed', task)
    }
  }

  /**
   * Check if there are any pending tasks in the ordering queue.
   * Used by stateMachine.start/resume (legacy dispatch path).
   */
  isEmpty(): boolean {
    if (this.lifecycle) {
      return this.lifecycle.getStats().pending === 0
    }
    return this.pendingQueue.length === 0
  }

  // ---------------------------------------------------------------------------
  // Task lookup
  // ---------------------------------------------------------------------------

  /**
   * Look up a Task object by ID. Returns null if not found.
   * TaskLifecycle stores TaskRecord (status/history); this returns the full Task.
   */
  getTask(taskId: string): Task | null {
    return this.taskInstanceIndex.get(taskId) ?? null
  }

  // ---------------------------------------------------------------------------
  // Stats (delegated to lifecycle)
  // ---------------------------------------------------------------------------

  /**
   * Queue statistics. Delegates to lifecycle when wired, falls back to local state.
   * Legacy shape: 5 fields (no 'cancelled'). Consumers like /v1/runtime/status
   * expect this shape.
   */
  getStats(): QueueStats {
    if (this.lifecycle) {
      const s = this.lifecycle.getStats()
      return {
        pending: s.pending,
        processing: s.processing,
        completed: s.completed,
        failed: s.failed,
        total: s.total,
      }
    }
    return {
      pending: this.pendingQueue.length,
      processing: 0,
      completed: 0,
      failed: 0,
      total: this.pendingQueue.length,
    }
  }

  // ---------------------------------------------------------------------------
  // Event forwarding (C.1)
  // ---------------------------------------------------------------------------

  /** Bound handler for TaskLifecycle 'record:evicted' — named so .off() can remove it (PR-193 review #4). */
  private handleRecordEvicted = (ev: { taskId: string }): void => {
    this.taskInstanceIndex.delete(ev.taskId)
    const deliveryKey = this.deliveryKeyByTaskId.get(ev.taskId)
    if (deliveryKey !== undefined) {
      this.deliveryKeyByTaskId.delete(ev.taskId)
      if (this.deliveryIndex.get(deliveryKey) === ev.taskId) {
        this.deliveryIndex.delete(deliveryKey)
      }
    }
  }

  private handleLifecycleTransition = (ev: TransitionEvent): void => {
    const task = this.taskInstanceIndex.get(ev.taskId)
    if (!task) return

    if (ev.from === null && ev.to === 'pending') {
      this.emitEvent('task:added', task)
    } else if (ev.to === 'processing' && ev.reason === 'dispatched') {
      this.emitEvent('task:started', task)
    } else if (ev.to === 'completed') {
      this.emitEvent('task:completed', task)
    } else if (ev.to === 'failed') {
      this.emitEvent('task:failed', task)
    } else if (ev.to === 'cancelled') {
      this.emitEvent('task:cancelled', task)
    }
    // Intermediate transitions (processing ↔ waiting_approval) not forwarded.
  }

  private emitEvent(type: QueueEventType, task?: Task): void {
    const event: QueueEvent = { type, task, timestamp: new Date() }
    this.emit(type, event)
    this.emit('event', event)
  }
}