Running Loops
Starting Loops
engine.start(options)
Signature (from runtime source):
1start(options: {2 loopId: string3 aggregateId: AggregateId4 actor: { type: "human" | "automation" | "ai-agent" | "system"; id: string }5 correlationId?: CorrelationId6 metadata?: Record<string, unknown>7}): Promise<LoopInstance>Behavior
- Throws if
loopIdis not registered. - Throws if an active instance already exists for the same
aggregateId(source check:status === "active"). - Creates instance with:
currentState = definition.initialStatestatus = "active"startedAttimestamp (also setsupdatedAtto the same value)- generated correlation ID when omitted
- Emits
loop.started.
Example
1import { aggregateId } from '@loop-engine/core'2 3const instance = await engine.start({4 loopId: 'scm.procurement',5 aggregateId: aggregateId('PO-001'),6 actor: { type: 'system', id: 'system:intake' },7 metadata: { source: 'erp_sync' }8})LoopInstance shape
1{2 loopId,3 aggregateId,4 currentState,5 status, "cmt">// pending | active | completed | failed | cancelled | suspended6 startedAt,7 updatedAt,8 correlationId?,9 completedAt?,10 metadata?11}Choosing aggregateId
Use your existing entity identifier:
- PO number
- order ID
- invoice number
- ticket ID
- lead ID
Same aggregateId can be reused across different loop IDs.
Same loopId + aggregateId cannot have multiple open instances.