Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* TaskLifecycle — single-writer service for task state transitions.
*/
import { EventEmitter } from 'events'
import type { Task } from '../queue/types'
import {
CanonicalReason,
LEGAL_TRANSITIONS,
MAX_HISTORY_PER_TASK,
QueueStats,
TaskRecord,
TaskStatus,
Transition,
TransitionEvent,
TransitionOutcome,
TransitionPayload,
isTerminal,
} from './types'
/**
* TTL for terminal task records. Matches REPORTER_TTL_MS in
* sseProgressReporter.ts. Records are evicted lazily on the next
* state-touching call (get/getStatus/isTerminal/getStats) after
* the TTL has elapsed.
*/
const TERMINAL_RECORD_TTL_MS = 5 * 60 * 1000
export class TaskLifecycle extends EventEmitter {
private records = new Map<string, TaskRecord>()
/**
* Timestamp of the last completed stale-record scan (epoch ms).
* Used by cleanupStaleRecords() to debounce O(N) scans.
*/
private _lastCleanupAt = 0
/** Minimum interval between stale-record scans. */
private static readonly CLEANUP_DEBOUNCE_MS = 30_000
constructor() {
super()
// M10: One subscriber per active task is expected under the dispatcher
// pattern (spec §4.4). Disable Node's default 10-listener warning so it
// doesn't false-positive during bursts of concurrent tasks.
this.setMaxListeners(0)
}
/**
* Create a TaskRecord with status='pending' and emit transition(null → pending, 'created').
* Idempotent: registering an existing id is a no-op (no record overwrite, no emission).
* Under the single-admission contract (MessageQueue.admit is the only
* production registration point), a call that lands here is a genuine
* duplicate delivery — log it truthfully and loudly with the prior state.
*/
register(task: Task): void {
const existing = this.records.get(task.id)
if (existing) {
console.warn(
`[TaskLifecycle] duplicate registration suppressed — id already registered: ${task.id} (status=${existing.status})`
)
return
}
const now = new Date()
const record: TaskRecord = {
id: task.id,
status: 'pending',
reason: null,
history: [{ from: null, to: 'pending', reason: 'created', at: now }],
submittedBy: task.sourceMessage?.sender ?? null,
submittedChannelType: task.sourceMessage?.channelType ?? null,
submittedChannelId: task.sourceMessage?.channelId ?? null,
// Admission already replaced `attachments` with the validated list.
acceptedAttachmentIds:
task.sourceMessage?.attachments?.map(attachment => attachment.id) ?? [],
// Admission set the resolutions; a caller-supplied value never reaches here.
acceptedFileReferenceIds:
task.sourceMessage?.fileReferenceResolutions?.map(r => r.reference.id) ?? [],
traceContext: task.traceContext ?? null,
createdAt: now,
}
this.records.set(task.id, record)
this.emitTransition({
taskId: task.id,
from: null,
to: 'pending',
reason: 'created',
at: now,
})
}
/**
* Atomic transition. Eligibility check + mutation + emit in one sync block.
* Node single-threaded → no locks needed.
*/
transition(
taskId: string,
to: TaskStatus,
reason: CanonicalReason,
payload?: TransitionPayload
): TransitionOutcome {
const record = this.records.get(taskId)
if (!record) {
return { kind: 'not_found' }
}
const from = record.status
if (isTerminal(from)) {
return { kind: 'already_terminal', state: from }
}
const allowed = LEGAL_TRANSITIONS.get(from)
if (!allowed || !allowed.has(to)) {
return { kind: 'illegal', from, to }
}
// Apply mutation
const now = new Date()
record.status = to
record.reason = reason
if (to === 'processing' && !record.dispatchedAt) {
record.dispatchedAt = now
}
if (isTerminal(to)) {
record.terminalAt = now
}
if (payload?.error !== undefined) record.error = payload.error
if (payload?.response !== undefined) record.response = payload.response
if (payload?.attachments !== undefined) record.attachments = payload.attachments
// Append history (capped). `history` is readonly in the public type; cast to mutable here.
const historyMut = record.history as Transition[]
historyMut.push({ from, to, reason, at: now })
if (historyMut.length > MAX_HISTORY_PER_TASK) {
historyMut.shift()
}
// Emit
this.emitTransition({
taskId: taskId,
from,
to,
reason,
at: now,
error: payload?.error,
response: payload?.response,
attachments: payload?.attachments,
})
return { kind: 'applied', from, to, reason }
}
/**
* Shutdown drain — cancel every non-terminal task with reason='system_shutdown'.
* See spec §5.7. If a future feature needs bulk-cancel with a different reason,
* add a separate method rather than widening this one.
*/
drainNonTerminal(): number {
let drained = 0
for (const record of this.records.values()) {
if (!isTerminal(record.status)) {
const outcome = this.transition(record.id, 'cancelled', 'system_shutdown')
if (outcome.kind === 'applied') drained++
}
}
return drained
}
get(taskId: string): TaskRecord | null {
this.cleanupStaleRecords()
return this.records.get(taskId) ?? null
}
isTerminal(taskId: string): boolean {
this.cleanupStaleRecords()
const r = this.records.get(taskId)
return r ? isTerminal(r.status) : false
}
getStatus(taskId: string): TaskStatus | null {
this.cleanupStaleRecords()
return this.records.get(taskId)?.status ?? null
}
getStats(): QueueStats {
this.cleanupStaleRecords()
const stats: QueueStats = {
pending: 0,
processing: 0,
completed: 0,
failed: 0,
cancelled: 0,
total: 0,
}
for (const r of this.records.values()) {
stats.total++
if (r.status === 'pending') stats.pending++
if (r.status === 'processing') stats.processing++
if (r.status === 'waiting_approval') stats.processing++ // waiting_approval counts as in-flight
if (r.status === 'completed') stats.completed++
if (r.status === 'failed') stats.failed++
if (r.status === 'cancelled') stats.cancelled++
}
return stats
}
/**
* Evict terminal records whose terminalAt exceeds TERMINAL_RECORD_TTL_MS.
* Runs lazily in read paths (get/getStatus/isTerminal/getStats) — NEVER
* in transition(), preserving Invariant I2 atomicity.
* Emits 'record:evicted' for each evicted record so subscribers
* (e.g. MessageQueue) can mirror the cleanup.
*
* Debounced: at 500+ concurrent tasks with dashboard polling plus
* dispatch-path getStatus calls, running an O(N) scan on every read
* adds ~250ms/sec of CPU overhead. The 30s debounce batches all scan
* work into at most 2 passes per minute. Eviction precision drops from
* "exact 5min" to "5min–5.5min" — still strictly bounded by the TTL.
*/
private cleanupStaleRecords(): void {
const now = Date.now()
if (now - this._lastCleanupAt < TaskLifecycle.CLEANUP_DEBOUNCE_MS) return
this._lastCleanupAt = now
for (const [id, record] of this.records) {
if (record.terminalAt && now - record.terminalAt.getTime() > TERMINAL_RECORD_TTL_MS) {
this.records.delete(id)
// Notify subscribers (MessageQueue shim uses this to evict its taskInstanceIndex)
this.emit('record:evicted', { taskId: id })
}
}
}
private emitTransition(event: TransitionEvent): void {
console.log(
JSON.stringify({
event: 'transition_emitted',
taskId: event.taskId,
from: event.from,
to: event.to,
reason: event.reason,
at: event.at.toISOString(),
})
)
this.emit('transition', event)
}
}