rulvar API reference

---

rulvar API reference / @rulvar/core / ExternalRegistry

Class: ExternalRegistry

Defined in: packages/core/src/engine/external.ts:61

Per-run registry of open external suspensions plus the run's activity counter: when every in-flight branch is blocked on suspensions (activity zero, waiters open), the run quiesces into outcome 'suspended'.

Constructors

Constructor

new ExternalRegistry(replayer): ExternalRegistry;

Defined in: packages/core/src/engine/external.ts:69

Parameters

Parameter	Type
replayer	Replayer

Returns

ExternalRegistry

Methods

awaitApproval()

awaitApproval(options): Promise<ApprovalDecision>;

Defined in: packages/core/src/engine/external.ts:212

Tool-approval suspension (M3-T03): journals (or re-matches) the suspended approval entry keyed by (toolName, input) in the agent's child scope and parks until a resolution closes it. The ask verdict is journaled together with the turn checkpoint; on resume an already-resolved entry applies its decision immediately and is never re-suspended.

Parameters

Parameter	Type	Description
options	{ input: Json; onPending?: (entry, replayed) => void; risk?: string; scope: string; spanId: string; toolName: string; }	-
options.input	Json	-
options.onPending?	(entry, replayed) => void	Called with the suspended entry once it is open (live or re-parked).
options.risk?	string	-
options.scope	string	-
options.spanId	string	-
options.toolName	string	-

Returns

Promise<ApprovalDecision>

---

awaitDecision()

awaitDecision(options): Promise<{
  entryRef: number;
  value: Json;
}>;

Defined in: packages/core/src/engine/external.ts:289

Flavor B escalation suspension (M3-T07): the escalate tool suspends the agent on the SAME machinery as approvals (kind 'approval', toolName 'escalate') with a journaled deadlineAt so deadlines survive resume; the resolution VALUE is the raw EscalationDecision. A timeout is expressed as a resolution by 'timeout' through the arbiter; first-closing-wins guarantees the defaultDecision and a racing live decision never both apply.

Parameters

Parameter	Type
options	{ deadlineAt: string; input: Json; onPending?: (entry, replayed) => void; scope: string; spanId: string; toolName: string; }
options.deadlineAt	string
options.input	Json
options.onPending?	(entry, replayed) => void
options.scope	string
options.spanId	string
options.toolName	string

Returns

Promise<{ entryRef: number; value: Json; }>

---

awaitExternal()

awaitExternal(
   scope, 
   spanId, 
   key, 
options?): Promise<Json>;

Defined in: packages/core/src/engine/external.ts:142

ctx.awaitExternal: journal (or re-match) the suspended entry and park until a resolution wins the first-closing-wins fold.

Parameters

Parameter	Type
scope	string
spanId	string
key	string
options?	{ prompt?: string; schema?: SchemaSpec; }
options.prompt?	string
options.schema?	SchemaSpec

Returns

Promise&lt;Json&gt;

---

enter()

enter(): () => void;

Defined in: packages/core/src/engine/external.ts:74

Wraps every non-suspension async operation (agents, steps).

Returns

() => void

---

onQuiesce()

onQuiesce(listener): void;

Defined in: packages/core/src/engine/external.ts:103

Parameters

Parameter	Type
listener	(pending) => void

Returns

void

---

pending()

pending(): PendingExternal[];

Defined in: packages/core/src/engine/external.ts:107

Returns

PendingExternal[]

---

resolveExternal()

resolveExternal(key, value): Promise<ResolutionOutcome>;

Defined in: packages/core/src/engine/external.ts:374

RunHandle.resolveExternal: the live path validates BEFORE append and throws InvalidResolutionError without journaling; a winning attempt settles the waiting promise in place.

Parameters

Parameter	Type
key	string
value	Json

Returns

Promise&lt;ResolutionOutcome&gt;

---

submitResolution()

submitResolution(entryRef, attempt): Promise<ResolutionOutcome>;

Defined in: packages/core/src/engine/external.ts:354

Submits a resolution attempt for a parked suspension and, when it wins the first-closing-wins fold, settles the in-process waiter with the value (timers and engine-side deciders use this; operator resolutions ride resolveExternal).

Parameters

Parameter	Type
entryRef	number
attempt	ResolutionAttempt

Returns

Promise&lt;ResolutionOutcome&gt;

---

approvalKey()

static approvalKey(entryRef): string;

Defined in: packages/core/src/engine/external.ts:117

The synthesized resolveExternal key of an approval suspension.

Parameters

Parameter	Type
entryRef	number

Returns

string