lt.events

lt.events delivers Long Tail events to in-process callbacks. Events arrive from the same publish calls that feed Socket.IO and NATS, as direct function calls. See Agents and events for the event families and transports.

on

// One verb on one role's queue
const unsub = lt.events.on('system.escalation.reviewer.*.claimed', (event) => {
  console.log('claimed:', event.escalationId, 'role:', event.role);
});

// Every escalation event on every role
lt.events.on('system.escalation.>', (event) => {
  metrics.increment(event.type.split('.').pop()!);
});

// Every event
lt.events.on('*', (event) => {
  auditLog.append(event);
});

// Unsubscribe when done
unsub();

Subscribe to events whose subject matches a pattern. Returns an unsubscribe function.

Parameters

Field	Type	Required	Description
pattern	LTEventType | '*' | string	Yes	Subject or pattern to match
callback	(event: LTEvent) => void	Yes	Called for each matching event. A callback that throws does not affect other subscribers

Pattern matching

Subjects are dot-separated tokens. Patterns follow NATS rules:

Pattern	Matches
system.workflow.wf-123.completed	That exact subject
system.task.*.failed	* matches exactly one token: every task’s failed event
system.escalation.reviewer.>	> matches the rest: every escalation event on the reviewer queue
*	Every event

Returns: () => void. Call it to unsubscribe.

Auth: Not required.

Event subjects

System events carry their resource ids in the subject. Escalation subjects put the role (the queue) first, so a subscription can follow one queue, one verb across queues, or one row across role hops.

Family	Subject
task	system.task.{taskId}.{created | started | completed | escalated | failed}
escalation	system.escalation.{role}.{escalationId}.{created | resolved | claimed | released | cancelled | reassigned | expired | updated}
workflow	system.workflow.{workflowId}.{started | completed | failed}
activity	system.activity.{workflowId}.{activityName}.{started | completed | failed}
milestone	system.milestone.{workflowId}
knowledge	system.knowledge.{domain}.{stored | deleted}
file	system.file.{stored | deleted}
agent	system.agent.{agentName}.{started | completed | failed | status_changed | triggers_changed}
oauth	system.oauth.grant.revoked
custom	app.*, published by your own code and tools

LTEvent fields

Only type and timestamp are always present. The other fields are added by the families that populate them.

Field	Type	Description
type	string	The subject
timestamp	string	ISO 8601 timestamp
id	string?	Idempotency key, minted on publish when omitted
source	string?	Producer tag, such as interceptor
data	Record<string, any>?	The topic-specific payload
workflowId	string?	Workflow instance (workflow, task, escalation and activity events)
workflowName	string?	Workflow function name
taskQueue	string?	Task queue the workflow ran on
taskId	string?	Task ID, when orchestrated
escalationId	string?	Escalation ID (escalation events)
role	string?	Escalation role (escalation events)
originId	string?	Root process lineage
status	string?	Lifecycle status after this event
activityName	string?	Activity step name (activity events)
milestones	LTMilestone[]?	Milestones (milestone and task events)
assignedAtCreation	boolean?	On claimed: true when the row was created already assigned