Packages

@loop-engine/actors

@loop-engine/actors models all five actor categories and provides transition authorization + evidence utilities.

Install

1npm install @loop-engine/actors

Actor types

1interface HumanActor extends ActorRef {
2  type: "human"
3  sessionId: string
4}
5 
6interface AutomationActor extends ActorRef {
7  type: "automation"
8  serviceId: string
9}
10 
11interface AIAgentActor extends ActorRef {
12  type: "ai-agent"
13  agentId: string
14  gatewaySessionId: string
15  recommendedBy?: string
16}
17 
18interface WebhookActor extends ActorRef {
19  type: "webhook"
20  source: string
21}
22 
23interface SystemActor extends ActorRef {
24  type: "system"
25}

Authorization

1canActorExecuteTransition(
2  actor: Actor,
3  transition: TransitionSpec,
4  constraints?: AIActorConstraints
5): { authorized: boolean; requiresApproval: boolean; reason?: string }

canActorExecuteTransition() validates transition.allowedActors and optional AI safety constraints (requiresHumanApprovalFor, maxConsecutiveAITransitions, and canExecuteTransitions).

1import { canActorExecuteTransition } from "@loop-engine/actors"
2 
3const auth = canActorExecuteTransition(agentActor, transition)
4if (!auth.authorized) {
5  console.log(auth.reason)
6}

Evidence building

1buildActorEvidence(actor: Actor, baseEvidence: Evidence): Evidence

The helper always adds:

actor_type
actor_id

For ai-agent it also adds ai_agent_id and preserves ai_confidence and ai_reasoning when present.

1import { buildActorEvidence } from "@loop-engine/actors"
2 
3const evidence = buildActorEvidence(aiActor, {
4  ai_confidence: 0.82,
5  ai_reasoning: "Demand spike at DC-East",
6  recommended_qty: 500
7})