@statelyai/agent 2.0.0-alpha.26 → 2.0.0-alpha.28

package/dist/{run-agent-DvDQd4If.mjs → run-agent-xNTxpt82.mjs}

@@ -1,283 +1,12 @@
-import { C as isUnboundPlaceholder, H as AgentError, I as isStandardSchema, L as resolveMachineVersion, S as getRegisteredAgentExecutionOptions, V as validateSchemaSync, c as executeAgentTextRequest, d as getCallUsage, f as isTextLogic, k as findNonSerializableContextPaths, p as normalizeGeneratorResult, u as getCallFinishReason, v as responseMessagesOf, x as getMachineIdlePredicate, y as executorBoundLogics } from "./text-logic-Bl_ZRxDi.mjs";
-import { a as isDecisionLogic, l as getAcceptedEvents, s as resolveDecision, t as AgentDecisionExhaustedError } from "./decision-DzSv1NpD.mjs";
+import { E as findNonSerializableContextPaths, N as isStandardSchema, P as resolveMachineVersion, R as validateSchemaSync, _ as responseMessagesOf, b as getRegisteredAgentExecutionOptions, d as isTextLogic, f as normalizeGeneratorResult, l as getCallFinishReason, u as getCallUsage, v as executorBoundLogics, x as isUnboundPlaceholder, z as AgentError } from "./text-logic-CIqHAmBi.mjs";
+import { a as isDecisionLogic, l as getAcceptedEvents, s as resolveDecision, t as AgentDecisionExhaustedError } from "./decision-RQ0iv0oZ.mjs";
 import { t as AGENT_USAGE_EVENT_TYPE } from "./usage-BdEjFuIi.mjs";
-import { _ as getUsageFromEvents, b as replay, f as canonicalEventJson, g as getSnapshotStateHash, h as getLogExecutionId, l as agentCallOccurrence, o as AgentMachineVersionMismatchError, p as createReplayEntry, t as AgentEventLogConflictError, v as initEntry, x as validateReplayEntries } from "./event-log-store-Ba2fsc4E.mjs";
-import { createActor, createAsyncLogic, getNextTransitions, initialTransition, isMachineSnapshot, transition } from "xstate";
-//#region src/steps.ts
-/**
-* The step API: the pure `(state, event) => (nextState, requests)` view of an
-* agent machine. An {@link AgentStep} is a snapshot plus the model requests
-* the machine is now waiting on; nothing here executes anything. A host
-* resolves each request however it likes ({@link executeAgentRequest},
-* `resolveDecision`, a queue, a durable workflow, a replayed log) and feeds
-* the result back with {@link resolveAgentStep} or {@link rejectAgentStep}.
-* `runAgent` is the in-process host built for the common case.
-* @module
-*/
-/** @internal Normalizes current and legacy XState invoke effect shapes. */
-function getInvokeEffectMetadata(action) {
-	if (action.type === "@xstate.spawn") return action;
-	if (action.type === "xstate.spawnChild") {
-		const params = action.params;
-		return params ? {
-			...params,
-			logic: action.logic
-		} : void 0;
-	}
-	if (action.type === "@xstate.start" && typeof action.src === "string") return action;
-}
-/**
-* The invokes a snapshot is still waiting on, lowered to the same spawn-effect
-* shape {@link getAgentRequests} reads. Derived from the snapshot's live
-* children rather than the last transition's actions, so a state that invokes
-* several actors at once (an `invoke: [...]` array, or parallel regions each
-* invoking) keeps reporting the siblings after the first one settles —
-* including when the settled invoke's `onDone` is targetless and starts
-* nothing new.
-*
-* Entries are ordered by invoke id, so a walker that resolves one invoke per
-* step is deterministic.
-*
-* @internal
-*/
-function getPendingInvokes(snapshot) {
-	const children = snapshot.children ?? {};
-	return Object.keys(children).sort().flatMap((id) => {
-		const child = children[id];
-		const childSnapshot = child?.getSnapshot?.();
-		if (!child || childSnapshot?.status !== "active") return [];
-		return [{
-			type: "@xstate.spawn",
-			id,
-			src: child.src,
-			input: childSnapshot.input,
-			logic: child.logic
-		}];
-	});
-}
-/**
-* Scans a set of executable actions (as returned by xstate's `transition`/
-* `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
-* lowers each into an {@link AgentStepRequest}. Pass `options.machine` to
-* pre-fill `schemas`/`actors` from the machine's registered `setupAgent`
-* options instead of passing them by hand.
-* `options.snapshot` is required to resolve a decision's candidate events
-* (intersecting declared `allowedEvents` with what's currently legal) — omit
-* it and decision requests report an empty `events` list.
-*
-* @internal
-*/
-function getAgentRequests(actions, { machine, ...options } = {}) {
-	if (machine) options = {
-		...getRegisteredAgentExecutionOptions(machine),
-		...options
-	};
-	return actions.flatMap((action) => {
-		const params = getInvokeEffectMetadata(action);
-		if (!params || typeof params.src !== "string") return [];
-		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
-		const registeredLogic = isTextLogic(params.logic) || isDecisionLogic(params.logic) ? params.logic : options.actors?.[params.src];
-		if (isDecisionLogic(registeredLogic)) {
-			const decisionRequest = registeredLogic.request(params.input);
-			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
-			const events = options.snapshot ? getAcceptedEvents(options.snapshot, {
-				events: options.events,
-				schemas: options.schemas,
-				eventTypes: allowedEventTypes
-			}) : [];
-			return [{
-				...decisionRequest,
-				id: params.id,
-				events
-			}];
-		}
-		const textLogic = isTextLogic(registeredLogic) ? registeredLogic : void 0;
-		const input = textLogic ? textLogic.request(params.input) : void 0;
-		if (!input) return [];
-		return [{
-			kind: "text",
-			id: params.id,
-			src: params.src,
-			...textLogic ? { mode: textLogic.mode } : {},
-			input,
-			tools: input.tools ?? {},
-			events: []
-		}];
-	});
-}
-/**
-* Builds the canonical `xstate.done.actor` event xstate's `transition()`
-* expects to resolve a spawned invoke — including the child session identity
-* that rejects a stale completion from an earlier incarnation.
-*
-* @internal
-*/
-function doneEvent(snapshot, request, output) {
-	const id = typeof request === "string" ? request : request.id;
-	const child = snapshot.children[id];
-	return {
-		type: "xstate.done.actor",
-		actorId: id,
-		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {},
-		output
-	};
-}
-/**
-* The `xstate.error.actor` counterpart of {@link doneEvent} — the event a
-* failed invoke delivers, which `onError` transitions observe. Carries the
-* same child session identity, so xstate does not discard it as stale.
-*
-* @internal
-*/
-function errorEvent(snapshot, request, error) {
-	const id = typeof request === "string" ? request : request.id;
-	const child = snapshot.children[id];
-	return {
-		type: "xstate.error.actor",
-		actorId: id,
-		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {},
-		error
-	};
-}
-/**
-* Applies a request's `output` as a done event (or, with `outcome: 'error'`,
-* its `output` as the invoke's error) via `transition(...)`, returning the raw
-* `[snapshot, actions]` tuple. Lower-level than {@link resolveAgentStep} /
-* {@link rejectAgentStep} — those helpers wrap this and also run
-* {@link getAgentRequests} to produce the next {@link AgentStep}.
-*
-* @internal
-*/
-function transitionResult(logic, snapshot, request, output, outcome = "output") {
-	const event = outcome === "error" ? errorEvent(snapshot, request, output) : doneEvent(snapshot, request, output);
-	const result = transition(logic, snapshot, event);
-	applyFinalStateOutput(logic, result[0], event);
-	return result;
-}
-/**
-* Starts a machine and returns its first {@link AgentStep} — the step-path
-* equivalent of `initialTransition` plus request discovery. Begins the
-* durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
-* (via {@link executeAgentRequest} for `kind: 'text'`, or
-* {@link resolveDecision} for `kind: 'decision'`), then advance with
-* {@link resolveAgentStep} or {@link transitionAgentStep}.
-*/
-function initialAgentStep(machine, input, options) {
-	const [snapshot, actions] = initialTransition(machine, input);
-	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
-}
-/**
-* Applies an externally-sent event (e.g. a decision's chosen event, or a
-* human's reply) and returns the next {@link AgentStep}. Accepts **either**
-* a raw snapshot **or** a prior `AgentStep` as the second argument —
-* `.snapshot` is unwrapped automatically, so callers can thread the whole
-* step object through without manually plucking the snapshot out.
-*/
-function transitionAgentStep(machine, snapshotOrStep, event, options) {
-	const [nextSnapshot, actions] = transition(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, event);
-	return createAgentStep(machine, nextSnapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
-}
-/**
-* Applies a resolved text request's output (a `kind: 'text'`
-* {@link AgentRequest} — not a decision) as a done event and returns the
-* next {@link AgentStep}. For decisions, resolve with `resolveDecision`
-* (which returns a {@link ChosenEvent}) and apply it with
-* {@link transitionAgentStep} instead — a decision has no output value of
-* its own to feed here.
-*/
-function resolveAgentStep(machine, step, request, output, options) {
-	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, output);
-	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
-}
-/**
-* Rejects a pending invoke — the failure counterpart of
-* {@link resolveAgentStep}. Delivers `error` as the invoke's
-* `xstate.error.actor` event, so the machine takes that invoke's `onError`
-* transition and returns the next {@link AgentStep}. With no `onError` in
-* scope the returned step's snapshot has `status: 'error'`, exactly as a live
-* run's failed invoke does.
-*
-* A durable host replays a failed call with this: the log says the call
-* failed, so the replay rejects the invoke instead of resolving it. Scripted
-* playthroughs use it too — see `simulateAgent`'s `script.errors`.
-*
-* `error` can be any value. An `Error` instance is the usual one, but a plain
-* object (`{ code: 'truncated' }`) reaches the `onError` transition as
-* `event.error` untouched, so a machine that branches on a failure code is
-* testable without constructing a provider's error class.
-*/
-function rejectAgentStep(machine, step, request, error, options) {
-	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, error, "error");
-	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
-}
-/**
-* Resolves one **text** request ({@link AgentRequest}, from
-* {@link AgentStep.requests}) against a host's {@link AgentRequestExecutors}
-* — merges the request's tools, dispatches to `generateText`/`streamText`
-* per `mode`, and validates the result against the request's
-* `outputSchema` if present. **Text-only**: passing a `kind: 'decision'`
-* request throws, directing the caller to `resolveDecision(request,
-* executors, ...)` instead. Returns the invoke's output — `{ result,
-* messages }`, ready for {@link resolveAgentStep} — plus the `raw` executor
-* result (tool calls, usage, finish reason).
-*/
-async function executeAgentRequest(request, executors) {
-	if (request.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors, ...) instead.");
-	assertTextExecutor(request, executors);
-	const { result, raw } = await executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
-	return {
-		result: request.input.outputSchema ? validateSchemaSync(request.input.outputSchema, result) : result,
-		messages: responseMessagesOf(raw),
-		raw
-	};
-}
-function assertTextExecutor(request, executors) {
-	const mode = request.mode ?? "generate";
-	const kind = mode === "stream" ? "streamText" : "generateText";
-	if (!(mode === "stream" ? executors.streamText : executors.generateText)) throw new Error(`this step's text request '${request.src}' needs a '${kind}' executor but none was provided.`);
-}
-function createAgentStep(machine, snapshot, actions, options) {
-	applyFinalStateOutput(machine, snapshot);
-	return {
-		snapshot,
-		actions,
-		requests: getAgentRequests(getPendingInvokes(snapshot), {
-			...options,
-			snapshot
-		}),
-		done: snapshot.status === "done"
-	};
-}
-function resolveStateValueConfig(config, value) {
-	if (typeof value === "string") return config.states?.[value];
-	if (!value || typeof value !== "object") return;
-	for (const [key, childValue] of Object.entries(value)) {
-		const childConfig = config.states?.[key];
-		if (!childConfig) continue;
-		if (childConfig.type === "final") return childConfig;
-		const nested = resolveStateValueConfig(childConfig, childValue);
-		if (nested) return nested;
-	}
-}
-function applyFinalStateOutput(logic, snapshot, event) {
-	const machineSnapshot = snapshot;
-	if (machineSnapshot.status !== "done" || machineSnapshot.output !== void 0 || !("config" in logic)) return;
-	const config = logic.config;
-	if (!config) return;
-	const output = resolveStateValueConfig(config, machineSnapshot.value)?.output;
-	if (output === void 0) return;
-	machineSnapshot.output = typeof output === "function" ? output({
-		context: machineSnapshot.context,
-		event
-	}) : output;
-}
-function isAgentStep(value) {
-	return !!value && typeof value === "object" && "snapshot" in value && "actions" in value && "requests" in value;
-}
-//#endregion
+import { _ as getUsageFromEvents, b as replay, f as canonicalEventJson, g as getSnapshotStateHash, h as getLogExecutionId, l as agentCallOccurrence, o as AgentMachineVersionMismatchError, p as createReplayEntry, t as AgentEventLogConflictError, v as initEntry, x as validateReplayEntries } from "./event-log-store-2pAFiWuc.mjs";
+import { createAsyncLogic, getNextTransitions, isMachineSnapshot, stopActor } from "xstate";
+import { createDurable } from "xstate/durable";
 //#region src/run-agent.ts
 /**
-* Thrown by {@link runAgent} when a resume is given BOTH an `events` log and a
+* Thrown by {@link AgentRuntime.start} when a resume is given BOTH an `events` log and a
 * `snapshot` that claims a position in that log (`agentMeta.logIndex`), and the
 * two disagree about the state at that position. The log is the source of
 * truth, so this is a host bug (a snapshot cached from a different lineage, or
@@ -286,7 +15,7 @@ function isAgentStep(value) {
 */
 var AgentSnapshotDivergedError = class extends AgentError {
 	constructor(expected, actual, logIndex) {
-		super("snapshot-diverged", `runAgent: the resume snapshot disagrees with the event log at index ${logIndex}: the log replays to state hash '${expected}', the snapshot hashes '${actual}'.`);
+		super("snapshot-diverged", `createAgentRuntime: the resume snapshot disagrees with the event log at index ${logIndex}: the log replays to state hash '${expected}', the snapshot hashes '${actual}'.`);
 		this.expected = expected;
 		this.actual = actual;
 		this.logIndex = logIndex;
@@ -309,7 +38,7 @@ function readAgentMeta(snapshot) {
 * The version of the {@link AgentTraceEvent} envelope every trace event carries
 * as `schemaVersion`. Bumped only on a breaking change to the envelope or any
 * payload shape, so a consumer can gate on it. Emitted identically by
-* {@link runAgent}, {@link provideExecutors}' `onTrace`, and
+* {@link createAgentRuntime}, {@link provideExecutors}' `onTrace`, and
 * {@link traceTransitions}.
 */
 const AGENT_TRACE_SCHEMA_VERSION = 1;
@@ -403,7 +132,7 @@ function serializeTraceEvent(event, options = {}) {
 let nextRunAgentTraceId = 1;
 /**
 * Thrown into the invoke that would have made the call once
-* {@link RunAgentOptions.maxModelCalls} is spent. It reaches the machine
+* {@link AgentRuntimeOptions.maxModelCalls} is spent. It reaches the machine
 * through the normal error channel, so an invoke's `onError` can branch on it
 * (`error.code === 'max-model-calls'`, the same string the settled result's
 * `cause` uses) and route to a degraded/finish state instead of failing the
@@ -420,7 +149,7 @@ var AgentMaxModelCallsExceededError = class extends AgentError {
 	/** The budget that was exceeded (`options.maxModelCalls`). */
 	maxModelCalls;
 	constructor(maxModelCalls) {
-		super("max-model-calls", `runAgent exceeded maxModelCalls (${maxModelCalls}). Raise the budget, or handle it in the invoke's onError (error.code === 'max-model-calls').`);
+		super("max-model-calls", `The run exceeded maxModelCalls (${maxModelCalls}). Raise the budget, or handle it in the invoke's onError (error.code === 'max-model-calls').`);
 		this.name = "AgentMaxModelCallsExceededError";
 		this.maxModelCalls = maxModelCalls;
 	}
@@ -467,12 +196,12 @@ function isStateMachineLogic(logic) {
 }
 /**
 * Fails fast (throws) at bind time — before any actor runs — when the
-* machine invokes an agent actor `runAgent` cannot execute. See §3.2 point 2.
+* machine invokes an agent actor the runtime cannot execute. See §3.2 point 2.
 *
 * Recurses into invoked child state machines (arbitrarily deep). A child
 * machine's agent requests reached through string-keyed invoke srcs DO inherit
-* the parent runAgent's `generateText`/`streamText`/`decide` executors —
-* runAgent rebinds them with the same host-backed wrappers (see
+* the parent run's `generateText`/`streamText`/`decide` executors —
+* the runtime rebinds them with the same host-backed wrappers (see
 * {@link rebindChildMachine}) — so the only remaining bind-time errors are: a
 * required executor kind missing entirely (naming the invoke chain and src),
 * and an unbound request reached through a direct-object invoke src that can't
@@ -498,11 +227,11 @@ function assertMachineBindable(machine, effectiveSources, executors, ctx) {
 				assertChildMachineBindable(src, src, stateName, executors, ctx);
 				continue;
 			}
-			if ((isTextLogic(src) || isDecisionLogic(src)) && !executorBoundLogics.has(src)) throw new Error(`runAgent: ${where} '${stateName}' invokes a direct-object actor logic (kind: '${src.kind}'). Direct-object invoke srcs cannot be rebound by runAgent — either call '.withExecutor(...)' on the logic before invoking it, or register it as a string-keyed actor source instead (machine.provide({ actors: { name: logic } })) and invoke it by name.`);
+			if ((isTextLogic(src) || isDecisionLogic(src)) && !executorBoundLogics.has(src)) throw new Error(`createAgentRuntime: ${where} '${stateName}' invokes a direct-object actor logic (kind: '${src.kind}'). Direct-object invoke srcs cannot be rebound by the agent runtime — either call '.withExecutor(...)' on the logic before invoking it, or register it as a string-keyed actor source instead (machine.provide({ actors: { name: logic } })) and invoke it by name.`);
 			continue;
 		}
 		const logic = effectiveSources[src];
-		if (logic === void 0) throw new Error(`runAgent: ${where} '${stateName}' invokes unregistered actor source '${src}'. Provide it via machine.provide({ actors: { '${src}': ... } }) or runAgent(machine, { actors: { '${src}': ... } }).`);
+		if (logic === void 0) throw new Error(`createAgentRuntime: ${where} '${stateName}' invokes unregistered actor source '${src}'. Provide it via machine.provide({ actors: { '${src}': ... } }) or createAgentRuntime(machine, { actors: { '${src}': ... } }).`);
 		if (isStateMachineLogic(logic)) {
 			assertChildMachineBindable(logic, src, stateName, executors, ctx);
 			continue;
@@ -510,17 +239,17 @@ function assertMachineBindable(machine, effectiveSources, executors, ctx) {
 		if (isDecisionLogic(logic)) {
 			if (executorBoundLogics.has(logic)) continue;
 			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, "decision");
-			if (!executors.decide) throw new Error(`runAgent: ${where} '${stateName}' invokes decision source '${src}' but no 'decide' executor was provided to runAgent(...).`);
+			if (!executors.decide) throw new Error(`createAgentRuntime: ${where} '${stateName}' invokes decision source '${src}' but no 'decide' executor was provided to createAgentRuntime(...).`);
 			continue;
 		}
 		if (isTextLogic(logic)) {
 			if (executorBoundLogics.has(logic)) continue;
 			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, logic.mode === "stream" ? "streaming text" : "text");
-			if (logic.mode === "stream" && !executors.streamText) throw new Error(`runAgent: ${where} '${stateName}' invokes streaming text source '${src}' but no 'streamText' executor was provided to runAgent(...).`);
-			if (logic.mode !== "stream" && !executors.generateText) throw new Error(`runAgent: ${where} '${stateName}' invokes text source '${src}' but no 'generateText' executor was provided to runAgent(...).`);
+			if (logic.mode === "stream" && !executors.streamText) throw new Error(`createAgentRuntime: ${where} '${stateName}' invokes streaming text source '${src}' but no 'streamText' executor was provided to createAgentRuntime(...).`);
+			if (logic.mode !== "stream" && !executors.generateText) throw new Error(`createAgentRuntime: ${where} '${stateName}' invokes text source '${src}' but no 'generateText' executor was provided to createAgentRuntime(...).`);
 			continue;
 		}
-		if (isUnboundPlaceholder(logic)) throw new Error(`runAgent: ${where} '${stateName}' invokes actor source '${src}', which has no host execution. Provide it via machine.provide({ actors: { '${src}': ... } }) or runAgent(machine, { actors: { '${src}': ... } }).`);
+		if (isUnboundPlaceholder(logic)) throw new Error(`createAgentRuntime: ${where} '${stateName}' invokes actor source '${src}', which has no host execution. Provide it via machine.provide({ actors: { '${src}': ... } }) or createAgentRuntime(machine, { actors: { '${src}': ... } }).`);
 	}
 }
 /** Descends the bind-time walk into an invoked child state machine, guarding
@@ -538,14 +267,14 @@ function assertChildMachineBindable(childMachine, childSrc, stateName, executors
 	});
 }
 /** The loud bind-time error for an unbound agent request reached under a
-* direct-object invoke src, which runAgent cannot rebind (only string-keyed
+* direct-object invoke src, which the runtime cannot rebind (only string-keyed
 * sources can be swapped via `.provide`). Names the invoke chain AND the
 * request src, and spells out the `.withExecutor`/string-keyed remedy. Note:
 * requests reachable through string-keyed srcs at any depth DO inherit
-* runAgent's executors — this error is only for the unrebindable direct-object
+* the runtime's executors — this error is only for the unrebindable direct-object
 * case. */
 function unrebindableChildRequestError(childPath, stateName, requestSrc, kind) {
-	return /* @__PURE__ */ new Error(`runAgent: child machine '${childPath}' (state '${stateName}') invokes ${kind} source '${requestSrc}', which has no host execution and is reached through a direct-object invoke src that runAgent cannot rebind. Requests reached through string-keyed actor sources inherit runAgent's generateText/streamText/decide executors automatically; a direct-object child machine does not. Either bind the request with its own executor (requestLogic.withExecutor(...)), or register the child as a string-keyed actor source (machine.provide({ actors: { <child>: childMachine } })) and invoke it by name.`);
+	return /* @__PURE__ */ new Error(`createAgentRuntime: child machine '${childPath}' (state '${stateName}') invokes ${kind} source '${requestSrc}', which has no host execution and is reached through a direct-object invoke src that the agent runtime cannot rebind. Requests reached through string-keyed actor sources inherit the agent runtime's generateText/streamText/decide executors automatically; a direct-object child machine does not. Either bind the request with its own executor (requestLogic.withExecutor(...)), or register the child as a string-keyed actor source (machine.provide({ actors: { <child>: childMachine } })) and invoke it by name.`);
 }
 /**
 * True when the snapshot's active states declare a transition that would
@@ -562,8 +291,8 @@ function declaresUsageTransition(snapshot) {
 /**
 * Builds the ONE place a trace payload is emitted: it hands the payload to the
 * envelope-stamping trace sink and, from that same payload, invokes the sugar
-* callbacks that are projections of it — {@link RunAgentOptions.onChunk},
-* {@link RunAgentOptions.onResult}, {@link RunAgentOptions.onTransition}. Each
+* callbacks that are projections of it — {@link AgentRuntimeOptions.onChunk},
+* {@link AgentRuntimeOptions.onResult}, {@link AgentRuntimeOptions.onTransition}. Each
 * keeps its historical position relative to the trace: `onResult` fires just
 * BEFORE its `request.end`, `onChunk`/`onTransition` just AFTER their
 * `stream.chunk`/`machine.transition`. Sugar dispatch never depends on whether
@@ -610,13 +339,15 @@ function selfIdAndSrc(self) {
 * root actor as a fallback.
 */
 function invokingActorOf(self, runCtx) {
-	return self?._parent ?? runCtx.actorHolder.actorRef;
+	const parent = self?._parent;
+	if (parent !== void 0 && parent._parent !== void 0) return parent;
+	return runCtx.actorHolder.actorRef ?? parent;
 }
 /**
 * The shared text/stream emission helper: binds a {@link TextLogic} to
 * `runCtx`'s executor and constructs the `request.start` / `stream.chunk` /
 * `request.end` (incl. the lifted `reasoning`) / `request.error` trace payloads.
-* Used by both `runAgent` and `provideExecutors` so the two paths produce
+* Used by both `createAgentRuntime` and `provideExecutors` so the two paths produce
 * identical event shapes by construction. @internal
 */
 function bindTextLogic(logic, runCtx) {
@@ -750,11 +481,11 @@ function createCountingDecide(runCtx, self) {
 	};
 }
 /**
-* Builds the decision actor logic runAgent installs in place of a
+* Builds the decision actor logic the runtime installs in place of a
 * `DecisionLogic`/`agent.decide` source. `DecisionLogic.withExecutor(...)`
 * can only swap the innermost per-attempt executor — the `resolveDecision(...)`
 * call (and its `canTake`) is hardwired inside the original logic's `run`.
-* To supply `canTake` (mode-3, §2.6), runAgent instead builds a fresh async
+* To supply `canTake` (mode-3, §2.6), the runtime instead builds a fresh async
 * logic here that calls `resolveDecision` itself, reusing `logic.request(...)`
 * to build the request the same way the original logic would have.
 *
@@ -822,7 +553,7 @@ function rootActorOf(self) {
 	while (ref?._parent) ref = ref._parent;
 	return ref;
 }
-/** The per-root envelope state, minted on first use (runId `run_<n>`, matching runAgent). */
+/** The per-root envelope state, minted on first use (runId `run_<n>`, matching the runtime). */
 function rootTraceState(root) {
 	let state = rootTraceRegistry.get(root);
 	if (!state) {
@@ -862,7 +593,7 @@ function provideTraceSink(onTrace) {
 }
 /**
 * A minimal {@link RunAgentBindContext} for `provideExecutors` (uncontrolled
-* `createActor`): the same wrappers runAgent installs, MINUS the run-scoped
+* `createActor`): the same wrappers the runtime installs, MINUS the run-scoped
 * model-call counter. `consumeModelCall` is a no-op (no budget), and
 * `actorHolder.actorRef` is left undefined — the wrappers read the invoking
 * actor off `self._parent`, always present under a live `createActor` tree.
@@ -871,7 +602,7 @@ function provideTraceSink(onTrace) {
 *
 * `recordUsage` has no run-level aggregate to fold into here (there is no
 * run), so it does one thing: deliver the reserved `@agent.usage` event, gated
-* exactly like runAgent's — see {@link deliverUsageEvent}.
+* exactly like the runtime's — see {@link deliverUsageEvent}.
 */
 function provideBindContext(machine, executors, options) {
 	const traceSink = provideTraceSink(options.onTrace);
@@ -899,7 +630,7 @@ function provideBindContext(machine, executors, options) {
 /**
 * The single reserved-`@agent.usage` DELIVERY seam, shared by both bind paths:
 * after a bound call settles with reported usage, send the prebuilt `event` to
-* the machine actor `resolveActorRef` names — the run's root actor on the `runAgent` path,
+* the machine actor `resolveActorRef` names — the run's root actor on the `createAgentRuntime` path,
 * the settling request actor's `self._parent` (always the invoking machine
 * under a live `createActor` tree) on the `provideExecutors` path.
 *
@@ -929,7 +660,7 @@ function deliverUsageEvent(event, resolveActorRef, onDropped) {
 }
 /**
 * Host-binds one text/stream source for {@link provideExecutors} using the SAME
-* emission helper as `runAgent` ({@link bindTextLogic}), so a bound
+* emission helper as `createAgentRuntime` ({@link bindTextLogic}), so a bound
 * text request emits request.start/stream.chunk/request.end/request.error with
 * identical shapes. @internal
 */
@@ -938,16 +669,16 @@ function bindTextForProvide(machine, logic, executors, options) {
 }
 /**
 * Host-binds one `DecisionLogic`/`agent.decide` source for
-* {@link provideExecutors}: runAgent's decision wrapper (snapshot-driven
+* {@link provideExecutors}: the runtime's decision wrapper (snapshot-driven
 * candidate events, `canTake`, auto-delivery of the chosen event) with the same
-* request-level tracing runAgent emits, minus run-scoped counting. @internal
+* request-level tracing the runtime emits, minus run-scoped counting. @internal
 */
 function bindDecisionForProvide(machine, logic, executors, options) {
 	return bindDecisionLogic(logic, provideBindContext(machine, executors, options));
 }
 /**
 * Recursively binds an invoked child state machine for {@link provideExecutors},
-* with the same semantics `runAgent` applies ({@link rebindChildMachine}):
+* with the same semantics `createAgentRuntime` applies ({@link rebindChildMachine}):
 * string-keyed text/decision sources at any depth inherit the host executors,
 * a source that carries its own executor is left alone, and a cycle is
 * returned as-is. Each machine in the tree is bound with its own registered
@@ -975,13 +706,13 @@ function resolveMachineInput(machine, input) {
 	try {
 		return validateSchemaSync(schema, input);
 	} catch (error) {
-		throw new AgentError("invalid-machine-input", `runAgent: machine input failed validation against the declared input schema: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		throw new AgentError("invalid-machine-input", `createAgentRuntime: machine input failed validation against the declared input schema: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
 }
 /**
 * Recursively rebinds an invoked child machine's own agent sources with the
-* SAME host-backed wrappers runAgent applies to the top-level machine, so a
-* child's text/stream/decision requests inherit runAgent's executors and
+* SAME host-backed wrappers the runtime applies to the top-level machine, so a
+* child's text/stream/decision requests inherit the runtime's executors and
 * participate in maxModelCalls counting, onTrace/onChunk/onResult exactly like
 * parent requests. Returns the child machine to invoke: a `.provide`-rebound
 * copy when any inner source needed wrapping, else the original untouched.
@@ -1016,31 +747,66 @@ function rebindChildMachine(childMachine, runCtx, visited, ctxFor) {
 	return Object.keys(wrapped).length > 0 ? childMachine.provide({ actors: wrapped }) : childMachine;
 }
 /**
-* Runs an agent machine to completion or idle: a `createActor` host that
-* binds `options`' host executors onto the machine's `agent.*`/`TextLogic`/
-* `DecisionLogic` actor sources, starts (or resumes) the actor, and drives
-* it until it settles — {@link RunAgentResult} `done | idle | error`. Unlike
-* the step helpers ({@link initialAgentStep} etc — a pure
-* transition-at-a-time path for durable hosts), `runAgent` owns a live actor
-* internally; there is no continuation callback, so **idle always settles**
-* and the caller resumes explicitly by passing the settled `{ snapshot,
-* event }` back in. The actor is stopped on every settle path (`done`,
-* `idle`, and `error` alike) — resume is always by snapshot, never by
-* holding a reference to a live actor.
+* The blocking host: opens the run, delivers `event` if given, then applies
+* every event that arrives until the run is quiescent, and returns the
+* outcome. A request handler or durable engine writes the same loop with its
+* own stop policy; this one is for scripts and tests.
+*/
+async function runToQuiescence(runtime, init = {}) {
+	let [state, effects] = await runtime.start(init);
+	await runtime.execute(effects);
+	if (init.event !== void 0 && state.status === "active") {
+		[state, effects] = runtime.transition(state, init.event);
+		await runtime.execute(effects);
+	}
+	for (let event; event = await runtime.nextEvent();) {
+		[state, effects] = runtime.transition(state, event);
+		await runtime.execute(effects);
+	}
+	return runtime.finish();
+}
+/**
+* Entry-by-entry check that the caller's `events` IS the store's thread. Equal
+* lengths prove nothing: a fork, a rolled-back replay, or a concurrent writer
+* that appended and truncated all produce a divergent log of the same size,
+* and appending this run's entries onto it would splice two lineages together.
+*/
+function assertThreadMatchesEvents(threadId, stored, events) {
+	for (let index = 0; index < stored.length; index++) {
+		const storedEntry = stored[index];
+		const givenEntry = events[index];
+		const storedHash = storedEntry.verification?.stateHash;
+		const givenHash = givenEntry.verification?.stateHash;
+		if (!(storedEntry.id === givenEntry.id && storedEntry.index === givenEntry.index && canonicalEventJson(storedEntry.event) === canonicalEventJson(givenEntry.event) && (storedHash === void 0 || givenHash === void 0 || storedHash === givenHash))) throw new AgentError("event-log-conflict", `createAgentRuntime: the given \`events\` diverge from thread "${threadId}" at index ${index} (stored entry '${storedEntry.id}', given '${givenEntry.id}') — the log passed in is not this thread's log.`);
+	}
+}
+const QUIESCENT = Symbol("quiescent");
+/**
+* Creates the helpers for one run of `machine`: executors bound to its
+* requests, the write-ahead log, traces, the budget, and a mailbox over
+* XState's durable transition loop (`xstate/durable`). See
+* {@link AgentRuntime} for the loop a host writes around it, and
+* {@link runToQuiescence} for the blocking host. {@link AgentRuntime.finish}
+* stops whatever is still running on every settle path (`done`, `idle`, and
+* `error` alike) — resume is always by snapshot (or log), never by holding a
+* reference to a live actor.
 *
-* Binding happens **before** the actor starts: every invoke the machine
+* Binding happens **before** any actor starts: every invoke the machine
 * could reach is walked and checked against the effective actor sources
 * (`options.actors` merged onto the machine), so a missing
 * `streamText`/`decide` executor or any other unbound actor source throws
-* immediately — a bind-time error, not a mid-run failure.
+* synchronously from this call — a bind-time error, not a mid-run failure.
 *
 * @example
 * ```ts
 * const executors = createAiSdkExecutors({ models });
-* let r = await runAgent(machine, { input, executors });
+* let r = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
 * while (r.status === 'idle') {
 *   const event = await promptUser(getAcceptedEvents(r.snapshot));
-*   r = await runAgent(machine, { snapshot: r.snapshot, event, executors });
+*   r = await runToQuiescence(createAgentRuntime(machine, { executors }), {
+*     snapshot: r.snapshot,
+*     event,
+*   });
 * }
 * if (r.status !== 'done') throw new Error(`Run did not complete: ${r.status}`);
 * console.log(r.output);
@@ -1050,46 +816,13 @@ function rebindChildMachine(childMachine, runCtx, visited, ctxFor) {
 * an adapter's set: `createAiSdkExecutors` from '@statelyai/agent/ai-sdk' or
 * `createOpenAiExecutors` from '@statelyai/agent/openai' supply all three.
 */
-async function runAgent(machine, options) {
-	const store = options.store;
-	if (store === void 0) return createAgentSession(machine, options).settled();
-	const threadId = options.threadId;
-	if (threadId === void 0 || threadId === "") throw new AgentError("missing-thread-id", "runAgent: `threadId` is required when `store` is given — it names the log thread to read and append to.");
-	if (options.events !== void 0) {
-		const storedThread = await store.read(threadId);
-		if (storedThread.length !== options.events.length) throw new AgentEventLogConflictError(threadId, options.events.length, storedThread.length);
-		assertThreadMatchesEvents(threadId, storedThread, options.events);
-		return createAgentSession(machine, options).settled();
-	}
-	const stored = await store.read(threadId);
-	return createAgentSession(machine, stored.length > 0 ? {
-		...options,
-		events: stored
-	} : options).settled();
-}
-/**
-* Entry-by-entry check that the caller's `events` IS the store's thread. Equal
-* lengths prove nothing: a fork, a rolled-back replay, or a concurrent writer
-* that appended and truncated all produce a divergent log of the same size,
-* and appending this run's entries onto it would splice two lineages together.
-*/
-function assertThreadMatchesEvents(threadId, stored, events) {
-	for (let index = 0; index < stored.length; index++) {
-		const storedEntry = stored[index];
-		const givenEntry = events[index];
-		const storedHash = storedEntry.verification?.stateHash;
-		const givenHash = givenEntry.verification?.stateHash;
-		if (!(storedEntry.id === givenEntry.id && storedEntry.index === givenEntry.index && canonicalEventJson(storedEntry.event) === canonicalEventJson(givenEntry.event) && (storedHash === void 0 || givenHash === void 0 || storedHash === givenHash))) throw new AgentError("event-log-conflict", `runAgent: the given \`events\` diverge from thread "${threadId}" at index ${index} (stored entry '${storedEntry.id}', given '${givenEntry.id}') — the log passed in is not this thread's log.`);
-	}
-}
-function createAgentSession(machine, options) {
+function createAgentRuntime(machine, options = {}) {
 	const maxModelCalls = options.maxModelCalls ?? 100;
 	let modelCallCount = 0;
 	let budgetExceeded = false;
 	let warnedNonSerializable = false;
 	const runId = `run_${nextRunAgentTraceId++}`;
 	let traceSeq = 0;
-	const resolvedInput = resolveMachineInput(machine, options.input);
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
 	const machineVersion = resolveMachineVersion(machine);
 	const onTrace = createTraceDispatch({
@@ -1116,11 +849,10 @@ function createAgentSession(machine, options) {
 		}
 		modelCallCount += 1;
 	};
-	const cycleGate = { isResolved: () => false };
 	const logEntries = [];
 	const store = options.store;
 	const threadId = options.threadId;
-	if (store !== void 0 && (threadId === void 0 || threadId === "")) throw new AgentError("missing-thread-id", "runAgent: `threadId` is required when `store` is given — it names the log thread to read and append to.");
+	if (store !== void 0 && (threadId === void 0 || threadId === "")) throw new AgentError("missing-thread-id", "createAgentRuntime: `threadId` is required when `store` is given — it names the log thread to read and append to.");
 	let journalChain = Promise.resolve();
 	let journalPending = 0;
 	let journalError;
@@ -1136,7 +868,10 @@ function createAgentSession(machine, options) {
 			});
 		}).catch((error) => {
 			journalError ??= error;
-			failRunOnJournalError(error);
+			stopRun({
+				cause: "journal",
+				error
+			});
 		}).finally(() => {
 			journalPending--;
 		});
@@ -1162,19 +897,10 @@ function createAgentSession(machine, options) {
 		while (journalPending > 0) await journalChain;
 		if (journalError !== void 0) throw journalError;
 	};
-	const failRunOnJournalError = (error) => {
-		if (settled) return;
-		settle({
-			status: "error",
-			cause: "journal",
-			error,
-			snapshot: actor.getSnapshot()
-		});
-	};
 	let resumedLogLength = 0;
 	let logExecutionId;
 	const verificationEnabled = options.verification !== false;
-	let lastRootSnapshot;
+	let current;
 	let logMachine = machine;
 	let loggingEnabled = true;
 	const appendLogEntry = (event, snapshot) => {
@@ -1190,7 +916,6 @@ function createAgentSession(machine, options) {
 		return entry;
 	};
 	const usageEntrySnapshot = () => {
-		const current = lastRootSnapshot;
 		if (current && (current.status !== "active" || !declaresUsageTransition(current))) return current;
 	};
 	const recordUsage = (usage, source = {}) => {
@@ -1199,24 +924,18 @@ function createAgentSession(machine, options) {
 			...source,
 			usage
 		};
-		const journal = { event };
-		pendingUsageJournal = journal;
-		try {
-			deliverUsageEvent(event, () => actorHolder.actorRef, (dropped) => {
-				if (!cycleGate.isResolved()) return false;
-				onTrace({
-					type: "usage.dropped",
-					event: dropped,
-					reason: "settled"
-				});
-				return true;
+		let delivered = false;
+		deliverUsageEvent(event, () => rootFacade(() => delivered = true), (dropped) => {
+			if (!finished) return false;
+			onTrace({
+				type: "usage.dropped",
+				event: dropped,
+				reason: "settled"
 			});
-		} finally {
-			pendingUsageJournal = void 0;
-		}
-		if (journal.entry === void 0) appendLogEntry(event, usageEntrySnapshot());
+			return true;
+		});
+		if (!delivered) appendLogEntry(event, usageEntrySnapshot());
 	};
-	let pendingUsageJournal;
 	const runUsage = () => ({
 		...getUsageFromEvents(logEntries.slice(resumedLogLength)),
 		modelCalls: modelCallCount
@@ -1231,14 +950,21 @@ function createAgentSession(machine, options) {
 		}
 		if (offending.length === 0) return;
 		warnedNonSerializable = true;
-		console.warn(`runAgent: context holds value(s) that will not survive snapshot persist/resume (JSON round-trip): ${offending.join(", ")}. Persist only JSON-serializable context, or convert these before the run settles.`);
+		console.warn(`createAgentRuntime: context holds value(s) that will not survive snapshot persist/resume (JSON round-trip): ${offending.join(", ")}. Persist only JSON-serializable context, or convert these before the run settles.`);
 	};
 	const provided = machine.provide({ actors: options.actors });
 	logMachine = provided;
 	const effectiveSources = provided.sources.actors;
 	const executors = { ...options.executors };
 	assertBindable(provided, effectiveSources, executors);
-	const actorHolder = { actorRef: void 0 };
+	const rootFacade = (onSend) => ({
+		getSnapshot: () => current,
+		send: (event) => {
+			onSend?.();
+			enqueue(event);
+		}
+	});
+	const actorHolder = { actorRef: rootFacade() };
 	const runCtx = {
 		generateText: executors.generateText,
 		streamText: executors.streamText,
@@ -1268,328 +994,446 @@ function createAgentSession(machine, options) {
 		}
 	}
 	const boundMachine = provided.provide({ actors: wrappedSources });
-	const isIdle = getMachineIdlePredicate(machine) ?? isAgentIdle;
-	const isIntentionalIdle = (snapshot) => isIdle(snapshot);
-	const resumeEvents = options.events;
-	let effectiveSnapshot = options.snapshot;
-	/** Deferred until after the illegal-resume check, so a rejected resume emits no entries. */
-	let seedInitEntry;
-	const restoredPersistedSnapshot = () => {
-		try {
-			const restored = logMachine.restoreSnapshot(options.snapshot);
-			return logMachine.getPersistedSnapshot(restored);
-		} catch {
-			return;
-		}
+	const mailbox = [];
+	let wake;
+	const fromMailbox = /* @__PURE__ */ new WeakSet();
+	let stopReason;
+	let started = false;
+	let finished = false;
+	let ignoredEvent;
+	const enqueue = (event) => {
+		if (finished) return;
+		fromMailbox.add(event);
+		const waiting = wake;
+		if (waiting) {
+			wake = void 0;
+			waiting(event);
+		} else mailbox.push(event);
 	};
-	/**
-	* Appends the log's reserved first entry, trying each candidate `init` in
-	* turn and, for each, an unverified entry if the hash cannot be computed.
-	* A machine or snapshot that defeats every attempt leaves the run WITHOUT a
-	* log rather than failing it: `runAgent` predates the log, and an exotic
-	* machine that cannot be folded must still run.
-	*/
-	const appendInitEntry = (candidates, metadata) => {
-		for (const init of candidates) for (const verification of verificationEnabled ? [true, false] : [false]) try {
-			const entry = initEntry(logMachine, init, {
-				machineVersion,
-				verification,
-				metadata
+	const inProcessTimers = options.timers === void 0 || options.timers === "in-process";
+	const timerHandles = /* @__PURE__ */ new Map();
+	const timerKey = (source, id) => `${source?.address ?? "(root)"}::${id}`;
+	const armTimer = (source, isRoot, id, delay) => {
+		if (isRoot && !inProcessTimers) {
+			options.timers.schedule({
+				id,
+				delay
 			});
-			logEntries.push(entry);
-			journalEntry(entry);
-			options.onEvent?.(entry);
 			return;
+		}
+		const key = timerKey(isRoot ? void 0 : source, id);
+		clearTimeout(timerHandles.get(key));
+		timerHandles.set(key, setTimeout(() => {
+			timerHandles.delete(key);
+			const timerEvent = {
+				type: "xstate.timer",
+				id
+			};
+			if (isRoot) enqueue(timerEvent);
+			else source?.send(timerEvent);
+			recheck();
+		}, delay));
+	};
+	const childrenBusy = (snapshot) => Object.values(snapshot?.children ?? {}).some((child) => {
+		const childSnapshot = child?.getSnapshot?.();
+		if (childSnapshot?.status !== "active") return false;
+		return isMachineSnapshot(childSnapshot) ? childrenBusy(childSnapshot) : true;
+	});
+	const workInFlight = () => childrenBusy(current) || inProcessTimers && timerHandles.size > 0;
+	let recheckScheduled = false;
+	const recheck = () => {
+		if (wake === void 0 || recheckScheduled) return;
+		if (stopReason === void 0 && workInFlight()) return;
+		recheckScheduled = true;
+		setTimeout(() => {
+			recheckScheduled = false;
+			if (wake !== void 0 && (stopReason !== void 0 || !workInFlight())) {
+				const waiting = wake;
+				wake = void 0;
+				waiting(QUIESCENT);
+			}
+		}, 0);
+	};
+	const stopChildren = (snapshot) => {
+		for (const child of Object.values(snapshot?.children ?? {})) try {
+			if (child) stopActor(child);
 		} catch {}
-		loggingEnabled = false;
+		for (const handle of timerHandles.values()) clearTimeout(handle);
+		timerHandles.clear();
 	};
-	/** Init forms for a snapshot resume, most faithful first. */
-	const snapshotInitCandidates = () => {
-		const restored = restoredPersistedSnapshot();
-		return [...restored !== void 0 ? [{ snapshot: restored }] : [], { snapshot: options.snapshot }];
+	let persistedAtStop;
+	const stopRun = (reason) => {
+		if (finished || stopReason !== void 0) return;
+		stopReason = reason;
+		try {
+			persistedAtStop = current && boundMachine.getPersistedSnapshot(current);
+		} catch {}
+		stopChildren(current);
+		recheck();
 	};
-	if (resumeEvents !== void 0 && resumeEvents.length > 0) {
-		validateReplayEntries(resumeEvents);
-		const tail = resumeEvents[resumeEvents.length - 1];
-		const inheritedExecutionId = getLogExecutionId(resumeEvents);
-		if (resumeEvents[0].machineId !== machineId) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
-			machineId,
-			machineVersion
-		}, {
-			machineId: resumeEvents[0].machineId,
-			machineVersion: tail.machineVersion
+	const onAbort = () => stopRun({
+		cause: "aborted",
+		error: options.signal?.reason ?? /* @__PURE__ */ new Error("Aborted")
+	});
+	const emitFromRoot = (event) => {
+		onTrace({
+			type: "emit",
+			event
 		});
-		if (tail.machineVersion === machineVersion) {
-			logEntries.push(...resumeEvents);
-			resumedLogLength = logEntries.length;
-			logExecutionId = inheritedExecutionId;
-			const cachedMeta = readAgentMeta(options.snapshot);
-			const tailStateHash = tail.verification?.stateHash;
-			if (!(options.snapshot !== void 0 && inheritedExecutionId !== void 0 && cachedMeta?.logId === inheritedExecutionId && cachedMeta.logIndex === resumeEvents.length && tailStateHash !== void 0 && hashResumeSnapshot(options.snapshot) === tailStateHash)) {
-				const cachedIndex = cachedMeta?.logIndex;
-				if (options.snapshot !== void 0 && typeof cachedIndex === "number" && cachedIndex >= 1 && cachedIndex <= resumeEvents.length && resumeEvents[cachedIndex - 1].verification?.stateHash !== void 0) {
-					const expected = getSnapshotStateHash(replay(logMachine, resumeEvents.slice(0, cachedIndex), {
-						machineVersion,
-						verify: false
-					}).persistedSnapshot);
-					const actual = hashResumeSnapshot(options.snapshot);
-					if (expected !== actual) throw new AgentSnapshotDivergedError(expected, actual, cachedIndex);
-				}
-				effectiveSnapshot = replay(logMachine, resumeEvents, {
-					machineVersion,
-					verify: true
-				}).persistedSnapshot;
-			}
-		} else {
-			if (options.snapshot === void 0) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
-				machineId,
-				machineVersion
-			}, {
-				machineId: tail.machineId,
-				machineVersion: tail.machineVersion
-			});
-			const bridgeMeta = readAgentMeta(options.snapshot);
-			if (inheritedExecutionId === void 0 || bridgeMeta?.logId !== inheritedExecutionId) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
-				machineId,
-				machineVersion
-			}, {
-				machineId: tail.machineId,
-				machineVersion: tail.machineVersion
+		const on = options.on ?? {};
+		on[event.type]?.(event);
+		if (event.type !== "*") on["*"]?.(event);
+	};
+	const inspect = options.inspect === void 0 ? void 0 : (event) => {
+		if (typeof options.inspect === "function") options.inspect(event);
+		else options.inspect?.next?.(event);
+	};
+	let execution;
+	execution = createDurable(boundMachine, {
+		startActor: (actor) => {
+			actor.subscribe({
+				next: recheck,
+				complete: recheck,
+				error: recheck
 			});
-			const bridgeTailHash = tail.verification?.stateHash;
-			const bridgeSnapshotHash = hashResumeSnapshot(options.snapshot);
-			if (bridgeMeta.logIndex !== resumeEvents.length) throw new AgentSnapshotDivergedError(bridgeTailHash ?? "(unrecorded)", bridgeSnapshotHash, resumeEvents.length);
-			if (bridgeTailHash !== void 0 && bridgeSnapshotHash !== bridgeTailHash) throw new AgentSnapshotDivergedError(bridgeTailHash, bridgeSnapshotHash, resumeEvents.length);
-			logExecutionId = inheritedExecutionId;
-			const migratedFrom = {
-				machineVersion: tail.machineVersion,
-				logIndex: resumeEvents.length
-			};
-			seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
-				...logExecutionId !== void 0 ? { executionId: logExecutionId } : {},
-				migratedFrom
+			actor.start();
+		},
+		enqueueRootEvent: (_source, event) => enqueue(event),
+		executeAction: (action, _metadata, runtime) => action.exec(runtime),
+		waitForEvent: () => {
+			const queued = mailbox.shift();
+			if (queued !== void 0) return queued;
+			if (stopReason !== void 0 || finished || !workInFlight()) return QUIESCENT;
+			return new Promise((resolve) => {
+				wake = resolve;
 			});
+		},
+		emitEvent: (source, event) => {
+			if (source.address === execution.rootAddress) emitFromRoot(event);
+			else source._emit?.(event);
+		},
+		scheduleTimer: (source, id, delay) => {
+			armTimer(source, source.address === execution.rootAddress, id, delay);
+		},
+		cancelTimer: (source, id) => {
+			const isRoot = source.address === execution.rootAddress;
+			if (isRoot && !inProcessTimers) {
+				options.timers.cancel(id);
+				return;
+			}
+			const key = timerKey(isRoot ? void 0 : source, id);
+			clearTimeout(timerHandles.get(key));
+			timerHandles.delete(key);
+		},
+		cancelAllTimers: (source) => {
+			const prefix = timerKey(source.address === execution.rootAddress ? void 0 : source, "");
+			for (const [key, handle] of timerHandles) if (key.startsWith(prefix)) {
+				clearTimeout(handle);
+				timerHandles.delete(key);
+			}
 		}
-	} else if (options.snapshot !== void 0) {
-		logExecutionId = crypto.randomUUID();
-		seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), { executionId: logExecutionId });
-	} else {
-		logExecutionId = crypto.randomUUID();
-		seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], { executionId: logExecutionId });
-	}
-	const resumedHistory = [...logEntries];
-	const siteCallCounts = /* @__PURE__ */ new Map();
-	const mintedCallKeys = /* @__PURE__ */ new WeakMap();
-	runCtx.callKey = (siteId, self) => {
-		if (logExecutionId === void 0) return;
-		const memoized = self === void 0 ? void 0 : mintedCallKeys.get(self);
-		if (memoized !== void 0) return memoized;
-		const startedHere = siteCallCounts.get(siteId) ?? 0;
-		siteCallCounts.set(siteId, startedHere + 1);
-		const key = `${logExecutionId}:${siteId}#${agentCallOccurrence(resumedHistory, siteId) + startedHere}`;
-		if (self !== void 0) mintedCallKeys.set(self, key);
-		return key;
-	};
-	const resumeEventToSend = options.event;
-	let ignoredEvent;
-	seedInitEntry?.();
-	let settled = false;
-	let journalAtSettle;
-	cycleGate.isResolved = () => settled;
-	let lastResult;
-	const waiters = [];
-	let idleTimer;
-	let actor;
-	let actorStarted = false;
-	let deliveringResumeEvent = resumeEventToSend !== void 0;
-	const settle = (outcome) => {
-		if (settled) return;
-		settled = true;
-		let persistedSnapshot;
-		let persistenceError;
-		if (actorStarted && outcome.status !== "done") try {
-			persistedSnapshot = actor.getPersistedSnapshot();
-		} catch (error) {
-			persistenceError = error;
-		}
-		const logIndexAtSettle = logEntries.length;
-		journalAtSettle = journalChain;
-		const persist = () => {
-			if (persistenceError !== void 0) throw persistenceError;
-			persistedSnapshot ??= actor.getPersistedSnapshot();
-			persistedSnapshot.agentMeta = {
-				machineId,
-				version: machineVersion,
-				...logExecutionId !== void 0 ? { logId: logExecutionId } : {},
-				logIndex: logIndexAtSettle
-			};
-			return persistedSnapshot;
-		};
-		const result = {
-			...outcome,
-			events: [...logEntries],
-			persist,
-			drain: drainJournal,
-			usage: runUsage(),
-			...ignoredEvent !== void 0 ? { ignored: ignoredEvent } : {}
-		};
-		if (idleTimer !== void 0) clearTimeout(idleTimer);
+	}, inspect ? { inspect } : void 0);
+	const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
+	const commit = (snapshot, event) => {
+		current = snapshot;
 		onTrace({
-			type: "run.end",
-			...outcome
-		});
-		if (options.signal) options.signal.removeEventListener("abort", onAbort);
-		actor.stop();
-		lastResult = result;
-		for (const resolve of waiters.splice(0)) resolve(result);
-	};
-	const onAbort = () => {
-		settle({
-			status: "error",
-			cause: "aborted",
-			error: options.signal?.reason ?? /* @__PURE__ */ new Error("Aborted"),
-			snapshot: actor.getSnapshot()
-		});
-	};
-	const settleIdle = (current) => {
-		warnNonSerializableContext(current);
-		settle({
-			status: "idle",
-			snapshot: current
+			type: "machine.transition",
+			snapshot,
+			event
 		});
 	};
-	const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
-	const scheduleIdleCheck = () => {
-		if (idleTimer !== void 0) clearTimeout(idleTimer);
-		idleTimer = setTimeout(() => {
-			idleTimer = void 0;
-			if (settled) return;
-			const current = actor.getSnapshot();
-			if (isIntentionalIdle(current) && isIdleSnapshot(current)) settleIdle(current);
-		}, 0);
+	/** True for a child completion/failure whose child is no longer running under the current state. */
+	const isStaleChildEvent = (event) => {
+		if (!event.type.startsWith("xstate.done.actor") && !event.type.startsWith("xstate.error.actor")) return false;
+		const { sessionId, actorId } = event;
+		return !Object.values(current?.children ?? {}).some((child) => sessionId !== void 0 ? child?.sessionId === sessionId : child?.id === actorId);
 	};
-	actor = createActor(boundMachine, {
-		input: resolvedInput,
-		snapshot: effectiveSnapshot,
-		inspect: (event) => {
-			if (typeof options.inspect === "function") options.inspect(event);
-			else options.inspect?.next?.(event);
-			if (event.type !== "@xstate.transition" || event.actorRef !== actor.ref) return;
-			if (settled) return;
-			const snapshot = event.snapshot;
-			lastRootSnapshot = snapshot;
-			if (resumeEventToSend !== void 0 && event.event === resumeEventToSend && event.microsteps.length === 0 && event.actions.length === 0 && event.sent.length === 0) ignoredEvent = resumeEventToSend;
-			if (pendingUsageJournal !== void 0 && event.event === pendingUsageJournal.event) pendingUsageJournal.entry = appendLogEntry(event.event, snapshot);
-			else if (event.event.type !== "@xstate.init" && (event.sourceRef !== event.actorRef || event.event.type === "xstate.timer")) appendLogEntry(event.event, snapshot);
+	return {
+		async start(init = {}) {
+			if (started) throw new AgentError("runtime-started", "createAgentRuntime: `start` was already called.");
+			started = true;
+			let resumeEvents = init.events;
+			if (store !== void 0) {
+				const storedThread = await store.read(threadId);
+				if (resumeEvents !== void 0) {
+					if (storedThread.length !== resumeEvents.length) throw new AgentEventLogConflictError(threadId, resumeEvents.length, storedThread.length);
+					assertThreadMatchesEvents(threadId, storedThread, resumeEvents);
+				} else if (storedThread.length > 0) resumeEvents = storedThread;
+			}
+			const resolvedInput = resolveMachineInput(machine, init.input);
+			let effectiveSnapshot = init.snapshot;
+			let seedInitEntry;
+			const restoredPersistedSnapshot = () => {
+				try {
+					const restored = logMachine.restoreSnapshot(init.snapshot);
+					return logMachine.getPersistedSnapshot(restored);
+				} catch {
+					return;
+				}
+			};
+			/**
+			* Appends the log's reserved first entry, trying each candidate `init`
+			* in turn and, for each, an unverified entry if the hash cannot be
+			* computed. A machine or snapshot that defeats every attempt leaves the
+			* run WITHOUT a log rather than failing it.
+			*/
+			const appendInitEntry = (candidates, metadata) => {
+				for (const candidate of candidates) for (const verification of verificationEnabled ? [true, false] : [false]) try {
+					const entry = initEntry(logMachine, candidate, {
+						machineVersion,
+						verification,
+						metadata
+					});
+					logEntries.push(entry);
+					journalEntry(entry);
+					options.onEvent?.(entry);
+					return;
+				} catch {}
+				loggingEnabled = false;
+			};
+			/** Init forms for a snapshot resume, most faithful first. */
+			const snapshotInitCandidates = () => {
+				const restored = restoredPersistedSnapshot();
+				return [...restored !== void 0 ? [{ snapshot: restored }] : [], { snapshot: init.snapshot }];
+			};
+			if (resumeEvents !== void 0 && resumeEvents.length > 0) {
+				validateReplayEntries(resumeEvents);
+				const tail = resumeEvents[resumeEvents.length - 1];
+				const inheritedExecutionId = getLogExecutionId(resumeEvents);
+				if (resumeEvents[0].machineId !== machineId) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
+					machineId,
+					machineVersion
+				}, {
+					machineId: resumeEvents[0].machineId,
+					machineVersion: tail.machineVersion
+				});
+				if (tail.machineVersion === machineVersion) {
+					logEntries.push(...resumeEvents);
+					resumedLogLength = logEntries.length;
+					logExecutionId = inheritedExecutionId;
+					const cachedMeta = readAgentMeta(init.snapshot);
+					const tailStateHash = tail.verification?.stateHash;
+					if (!(init.snapshot !== void 0 && inheritedExecutionId !== void 0 && cachedMeta?.logId === inheritedExecutionId && cachedMeta.logIndex === resumeEvents.length && tailStateHash !== void 0 && hashResumeSnapshot(init.snapshot) === tailStateHash)) {
+						const cachedIndex = cachedMeta?.logIndex;
+						if (init.snapshot !== void 0 && typeof cachedIndex === "number" && cachedIndex >= 1 && cachedIndex <= resumeEvents.length && resumeEvents[cachedIndex - 1].verification?.stateHash !== void 0) {
+							const expected = getSnapshotStateHash(replay(logMachine, resumeEvents.slice(0, cachedIndex), {
+								machineVersion,
+								verify: false
+							}).persistedSnapshot);
+							const actual = hashResumeSnapshot(init.snapshot);
+							if (expected !== actual) throw new AgentSnapshotDivergedError(expected, actual, cachedIndex);
+						}
+						effectiveSnapshot = replay(logMachine, resumeEvents, {
+							machineVersion,
+							verify: true
+						}).persistedSnapshot;
+					}
+				} else {
+					if (init.snapshot === void 0) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
+						machineId,
+						machineVersion
+					}, {
+						machineId: tail.machineId,
+						machineVersion: tail.machineVersion
+					});
+					const bridgeMeta = readAgentMeta(init.snapshot);
+					if (inheritedExecutionId === void 0 || bridgeMeta?.logId !== inheritedExecutionId) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
+						machineId,
+						machineVersion
+					}, {
+						machineId: tail.machineId,
+						machineVersion: tail.machineVersion
+					});
+					const bridgeTailHash = tail.verification?.stateHash;
+					const bridgeSnapshotHash = hashResumeSnapshot(init.snapshot);
+					if (bridgeMeta.logIndex !== resumeEvents.length) throw new AgentSnapshotDivergedError(bridgeTailHash ?? "(unrecorded)", bridgeSnapshotHash, resumeEvents.length);
+					if (bridgeTailHash !== void 0 && bridgeSnapshotHash !== bridgeTailHash) throw new AgentSnapshotDivergedError(bridgeTailHash, bridgeSnapshotHash, resumeEvents.length);
+					logExecutionId = inheritedExecutionId;
+					const migratedFrom = {
+						machineVersion: tail.machineVersion,
+						logIndex: resumeEvents.length
+					};
+					seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
+						...logExecutionId !== void 0 ? { executionId: logExecutionId } : {},
+						migratedFrom
+					});
+				}
+			} else if (init.snapshot !== void 0) {
+				logExecutionId = crypto.randomUUID();
+				seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), { executionId: logExecutionId });
+			} else {
+				logExecutionId = crypto.randomUUID();
+				seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], { executionId: logExecutionId });
+			}
+			const resumedHistory = [...logEntries];
+			const siteCallCounts = /* @__PURE__ */ new Map();
+			const mintedCallKeys = /* @__PURE__ */ new WeakMap();
+			runCtx.callKey = (siteId, self) => {
+				if (logExecutionId === void 0) return;
+				const memoized = self === void 0 ? void 0 : mintedCallKeys.get(self);
+				if (memoized !== void 0) return memoized;
+				const startedHere = siteCallCounts.get(siteId) ?? 0;
+				siteCallCounts.set(siteId, startedHere + 1);
+				const key = `${logExecutionId}:${siteId}#${agentCallOccurrence(resumedHistory, siteId) + startedHere}`;
+				if (self !== void 0) mintedCallKeys.set(self, key);
+				return key;
+			};
+			seedInitEntry?.();
+			const resumeEvent = init.event;
 			onTrace({
-				type: "machine.transition",
-				snapshot,
-				event: event.event
+				type: "run.start",
+				...resolvedInput !== void 0 ? { input: resolvedInput } : {},
+				...effectiveSnapshot !== void 0 ? { snapshot: effectiveSnapshot } : {},
+				...resumeEvent !== void 0 ? { event: resumeEvent } : {}
 			});
-			if (snapshot.status === "done") {
-				settle({
-					status: "done",
-					output: snapshot.output,
-					snapshot
-				});
-				return;
+			if (options.signal) if (options.signal.aborted) stopReason = {
+				cause: "aborted",
+				error: options.signal.reason ?? /* @__PURE__ */ new Error("Aborted")
+			};
+			else options.signal.addEventListener("abort", onAbort);
+			let snapshot;
+			let effects = [];
+			const initEvent = {
+				type: "@xstate.init",
+				...resolvedInput !== void 0 ? { input: resolvedInput } : {}
+			};
+			if (effectiveSnapshot === void 0) [snapshot, effects] = execution.initialTransition(resolvedInput);
+			else {
+				try {
+					[snapshot, effects] = execution.restore(effectiveSnapshot);
+				} catch (error) {
+					try {
+						current = execution.initialTransition(resolvedInput)[0];
+					} catch {
+						current = {
+							status: "error",
+							error,
+							context: void 0
+						};
+					}
+					stopReason ??= {
+						cause: "machine",
+						error
+					};
+					return [current, []];
+				}
+				current = snapshot;
 			}
-			if (snapshot.status === "error") {
-				settle({
-					status: "error",
-					cause: runErrorCause(snapshot.error),
-					error: snapshot.error,
-					snapshot
+			commit(snapshot, initEvent);
+			return [snapshot, effects];
+		},
+		transition(state, event) {
+			if (finished) throw new AgentError("runtime-finished", "createAgentRuntime: the run has finished; start a new runtime to continue.");
+			if (stopReason !== void 0) return [state, []];
+			const [next, effects] = execution.transition(state, event);
+			if (!fromMailbox.has(event) && next === state && effects.length === 0) ignoredEvent = event;
+			appendLogEntry(event, next);
+			commit(next, event);
+			return [next, effects];
+		},
+		async execute(effects) {
+			if (stopReason !== void 0 || finished || effects.length === 0) return;
+			try {
+				await execution.executeEffects(effects);
+			} catch (error) {
+				stopRun({
+					cause: "machine",
+					error
 				});
-				return;
 			}
-			if (snapshot.status === "stopped") {
-				settle({
-					status: "error",
-					cause: "stopped",
-					error: /* @__PURE__ */ new Error("Actor stopped externally."),
+			recheck();
+		},
+		async nextEvent() {
+			for (;;) {
+				if (finished || stopReason !== void 0 || current?.status !== "active") return;
+				const event = await execution.waitForEvent();
+				if (event === QUIESCENT || stopReason !== void 0) return;
+				if (isStaleChildEvent(event)) continue;
+				return event;
+			}
+		},
+		async finish() {
+			if (finished) throw new AgentError("runtime-finished", "createAgentRuntime: `finish` was already called.");
+			const snapshot = current;
+			let outcome;
+			if (stopReason !== void 0) outcome = {
+				status: "error",
+				cause: stopReason.cause === "machine" ? runErrorCause(stopReason.error) : stopReason.cause,
+				error: stopReason.error,
+				snapshot
+			};
+			else if (snapshot.status === "done") outcome = {
+				status: "done",
+				output: snapshot.output,
+				snapshot
+			};
+			else if (snapshot.status === "error") outcome = {
+				status: "error",
+				cause: runErrorCause(snapshot.error),
+				error: snapshot.error,
+				snapshot
+			};
+			else if (snapshot.status === "stopped") outcome = {
+				status: "error",
+				cause: "stopped",
+				error: /* @__PURE__ */ new Error("Actor stopped externally."),
+				snapshot
+			};
+			else {
+				warnNonSerializableContext(snapshot);
+				outcome = {
+					status: "idle",
 					snapshot
-				});
-				return;
+				};
 			}
-			if (!deliveringResumeEvent && isIntentionalIdle(snapshot) && isIdleSnapshot(snapshot)) {
-				queueMicrotask(() => {
-					if (settled) return;
-					const current = actor.getSnapshot();
-					if (isIntentionalIdle(current) && isIdleSnapshot(current)) settleIdle(current);
-					else scheduleIdleCheck();
-				});
-				return;
+			let persistedSnapshot = persistedAtStop;
+			let persistenceError;
+			if (outcome.status !== "done" && persistedSnapshot === void 0) try {
+				persistedSnapshot = boundMachine.getPersistedSnapshot(snapshot);
+			} catch (error) {
+				persistenceError = error;
 			}
-			scheduleIdleCheck();
-		}
-	});
-	actorHolder.actorRef = actor;
-	actor.subscribe({ error: () => {} });
-	actor.on("*", (event) => {
-		onTrace({
-			type: "emit",
-			event
-		});
-	});
-	for (const [type, handler] of Object.entries(options.on ?? {})) if (typeof handler === "function") actor.on(type, handler);
-	const sessionApi = { settled: async () => {
-		const result = settled && lastResult !== void 0 ? lastResult : await new Promise((resolve) => {
-			waiters.push(resolve);
-		});
-		await journalAtSettle;
-		return result;
-	} };
-	if (options.signal) {
-		if (options.signal.aborted) {
-			settle({
-				status: "error",
-				cause: "aborted",
-				error: options.signal.reason ?? /* @__PURE__ */ new Error("Aborted"),
-				snapshot: actor.getSnapshot()
+			const logIndexAtSettle = logEntries.length;
+			const persist = () => {
+				if (persistenceError !== void 0) throw persistenceError;
+				persistedSnapshot ??= boundMachine.getPersistedSnapshot(snapshot);
+				persistedSnapshot.agentMeta = {
+					machineId,
+					version: machineVersion,
+					...logExecutionId !== void 0 ? { logId: logExecutionId } : {},
+					logIndex: logIndexAtSettle
+				};
+				return persistedSnapshot;
+			};
+			finished = true;
+			const journalAtSettle = journalChain;
+			const result = {
+				...outcome,
+				events: [...logEntries],
+				persist,
+				drain: drainJournal,
+				usage: runUsage(),
+				...ignoredEvent !== void 0 ? { ignored: ignoredEvent } : {}
+			};
+			onTrace({
+				type: "run.end",
+				...outcome
 			});
-			return sessionApi;
+			options.signal?.removeEventListener("abort", onAbort);
+			stopChildren(snapshot);
+			if (wake !== void 0) {
+				const waiting = wake;
+				wake = void 0;
+				waiting(QUIESCENT);
+			}
+			await journalAtSettle;
+			return result;
 		}
-		options.signal.addEventListener("abort", onAbort);
-	}
-	onTrace({
-		type: "run.start",
-		...resolvedInput !== void 0 ? { input: resolvedInput } : {},
-		...effectiveSnapshot !== void 0 ? { snapshot: effectiveSnapshot } : {},
-		...resumeEventToSend !== void 0 ? { event: resumeEventToSend } : {}
-	});
-	actorStarted = true;
-	actor.start();
-	if (!settled) {
-		const startedSnapshot = actor.getSnapshot();
-		lastRootSnapshot ??= startedSnapshot;
-		if (startedSnapshot.status === "done") settle({
-			status: "done",
-			output: startedSnapshot.output,
-			snapshot: startedSnapshot
-		});
-		else if (startedSnapshot.status === "error") settle({
-			status: "error",
-			cause: runErrorCause(startedSnapshot.error),
-			error: startedSnapshot.error,
-			snapshot: startedSnapshot
-		});
-		else if (startedSnapshot.status === "stopped") settle({
-			status: "error",
-			cause: "stopped",
-			error: /* @__PURE__ */ new Error("Actor stopped externally."),
-			snapshot: startedSnapshot
-		});
-	}
-	if (resumeEventToSend && !settled) {
-		deliveringResumeEvent = false;
-		actor.send(resumeEventToSend);
-	}
-	return sessionApi;
+	};
 }
 /**
 * Wraps a `(snapshot, actorRef) => void` handler into a function usable as
-* {@link RunAgentOptions.inspect}: it filters the raw inspection stream to
+* {@link AgentRuntimeOptions.inspect}: it filters the raw inspection stream to
 * `@xstate.transition` events and hands the handler the typed
 * {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
 * transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
@@ -1614,12 +1458,12 @@ function inspectTransitions(handler) {
 * const actor = createActor(bound, { inspect: traceTransitions(onTrace) });
 * ```
 *
-* Only ROOT-actor transitions are traced (matching `runAgent`'s
+* Only ROOT-actor transitions are traced (matching the runtime's
 * `machine.transition`); child-actor transitions are ignored. Attribute the
 * event via its envelope `runId`.
 *
 * By design this path has NO `run.start`/`run.end` events: `createActor` has no
-* run boundary the way `runAgent` does, so the stream starts at the actor's
+* run boundary the way `createAgentRuntime` does, so the stream starts at the actor's
 * first transition. It also does NOT emit `emit` trace events: in this xstate
 * build emitted events are delivered through `actor.on(...)`, not the inspection
 * protocol, so they are not observable from an `inspect` handler — subscribe
@@ -1637,26 +1481,14 @@ function traceTransitions(onTrace) {
 		}));
 	};
 }
-function isIdleSnapshot(snapshot) {
-	if (snapshot.status !== "active") return false;
-	if (Object.values(snapshot.children ?? {}).some((child) => {
-		const childSnapshot = child?.getSnapshot?.();
-		if (childSnapshot?.status !== "active") return false;
-		if (isMachineSnapshot(childSnapshot)) return !isIdleSnapshot(childSnapshot);
-		return true;
-	})) return false;
-	return !getNextTransitions(snapshot).some((transitionDef) => transitionDef.eventType === "" || transitionDef.eventType.startsWith("xstate.after"));
-}
 /**
-* Default machine-owned idle signal used by {@link runAgent}: an active
+* Whether a snapshot is asking the outside world for something: an active
 * snapshot that accepts an external event anywhere in its active hierarchy,
 * or declares interaction metadata on an active state.
 *
-* Compose this in `setupAgent({ isIdle })` when the application has additional
-* wait states: `isIdle: (snapshot) => isAgentIdle(snapshot) || snapshot.hasTag('waiting')`.
-* Pending work and active invoked children are checked separately by the
-* runner, so this function only answers whether the state is an intentional
-* external wait.
+* The runtime does not use this to stop; a run settles when nothing is in
+* flight. Use it once the run is quiescent, to tell a human wait (render
+* `getInteraction(snapshot)`) from a machine that is simply stuck.
 */
 function isAgentIdle(snapshot) {
 	if (snapshot.status !== "active") return false;
@@ -1666,4 +1498,4 @@ function isAgentIdle(snapshot) {
 	}) || getAcceptedEvents(snapshot).length > 0;
 }
 //#endregion
-export { rejectAgentStep as _, bindDecisionForProvide as a, inspectTransitions as c, runAgent as d, serializeTraceEvent as f, initialAgentStep as g, getPendingInvokes as h, bindChildMachineForProvide as i, isAgentIdle as l, executeAgentRequest as m, AgentMaxModelCallsExceededError as n, bindTextForProvide as o, traceTransitions as p, AgentSnapshotDivergedError as r, getConfiguredInvokeSrcs as s, AGENT_TRACE_SCHEMA_VERSION as t, isStateMachineLogic as u, resolveAgentStep as v, transitionAgentStep as y };
+export { bindDecisionForProvide as a, getConfiguredInvokeSrcs as c, isStateMachineLogic as d, runToQuiescence as f, bindChildMachineForProvide as i, inspectTransitions as l, traceTransitions as m, AgentMaxModelCallsExceededError as n, bindTextForProvide as o, serializeTraceEvent as p, AgentSnapshotDivergedError as r, createAgentRuntime as s, AGENT_TRACE_SCHEMA_VERSION as t, isAgentIdle as u };