Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* 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)
}
}