Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* TaskLifecycle types.
*/
/**
* MIGRATION NOTE: `TaskStatus` and `QueueStats` are also exported from
* `../queue/types.ts`. These duplicates are intentional during Phase A (dual-write
* parity). The queue/types copies will be removed in Phase C when MessageQueue
* shrinks to a factory-only shim (spec §4.2, §9.3). DO NOT import from
* `../queue/types` for new code — always import from `./types`.
*/
import type { Attachment, TraceContextV1 } from '../core/types'
import type { TaskError } from '../queue/types'
export type TaskStatus =
| 'pending'
| 'processing'
| 'waiting_approval'
| 'completed'
| 'failed'
| 'cancelled'
export type CanonicalReason =
| 'created'
| 'dispatched'
| 'user_requested'
| 'system_shutdown'
| 'approval_timeout' // reserved — see spec §3.4
| 'natural'
| 'denied_by_user'
| `error:${string}` // e.g. 'error:LLM_INSUFFICIENT_QUOTA'
export const TERMINAL_STATES: ReadonlySet<TaskStatus> = new Set([
'completed',
'failed',
'cancelled',
])
export function isTerminal(status: TaskStatus): boolean {
return TERMINAL_STATES.has(status)
}
/**
* Legal state transitions. Key = from, value = set of allowed `to`.
* Anything not in this map → IllegalTransition.
*/
export const LEGAL_TRANSITIONS: ReadonlyMap<TaskStatus, ReadonlySet<TaskStatus>> = new Map([
['pending', new Set<TaskStatus>(['processing', 'cancelled'])],
['processing', new Set<TaskStatus>(['waiting_approval', 'completed', 'failed', 'cancelled'])],
['waiting_approval', new Set<TaskStatus>(['processing', 'completed', 'cancelled'])],
['completed', new Set<TaskStatus>()],
['failed', new Set<TaskStatus>()],
['cancelled', new Set<TaskStatus>()],
])
export interface Transition {
from: TaskStatus | null // null on initial register
to: TaskStatus
reason: CanonicalReason
at: Date
}
export interface TaskRecord {
id: string
status: TaskStatus
reason: CanonicalReason | null
history: readonly Transition[] // capped at MAX_HISTORY_PER_TASK — cast to mutable only inside TaskLifecycle
/**
* The sender identity that submitted this task (task.sourceMessage.sender).
* Null for internal/cron tasks that have no sourceMessage.
* Used for ownership checks on runtime reads/cancel.
*/
submittedBy: string | null
submittedChannelType: string | null
submittedChannelId: string | null
/**
* Ids of the incoming attachments admitted with this task (#666). A replayed
* delivery answers with them, exactly like the first response did.
*/
acceptedAttachmentIds: readonly string[]
/** Ids of the structured file references resolved for this task (#666). */
acceptedFileReferenceIds: readonly string[]
traceContext: TraceContextV1 | null
createdAt: Date
dispatchedAt?: Date
terminalAt?: Date
error?: TaskError
response?: string
attachments?: Attachment[]
}
export const MAX_HISTORY_PER_TASK = 20
export type TransitionOutcome =
| { kind: 'applied'; from: TaskStatus | null; to: TaskStatus; reason: CanonicalReason }
| { kind: 'already_terminal'; state: TaskStatus }
| { kind: 'illegal'; from: TaskStatus; to: TaskStatus }
| { kind: 'not_found' }
export interface TransitionEvent {
taskId: string
from: TaskStatus | null
to: TaskStatus
reason: CanonicalReason
at: Date
error?: TaskError
response?: string
attachments?: Attachment[]
}
export interface TransitionPayload {
error?: TaskError
response?: string
attachments?: Attachment[]
}
export interface QueueStats {
pending: number
processing: number
completed: number
failed: number
cancelled: number
total: number
}