@statelyai/agent 2.0.0-alpha.19 → 2.0.0-alpha.21

package/dist/{decision-t26zsnSR.cjs → decision-BnTCsuJv.cjs}

@@ -168,7 +168,7 @@ function toolMessage(content) {
 * ```
 */
 function getStateMeta(snapshot) {
-	const nodes = snapshot._nodes;
+	const nodes = snapshot.nodes;
 	const depthById = new Map(nodes?.map((node) => [node.id, node.path.length]));
 	const depth = (id) => depthById.get(id) ?? id.split(".").length;
 	const entries = Object.entries(snapshot.getMeta()).filter((entry) => entry[1] != null).sort(([a], [b]) => depth(a) - depth(b) || (a < b ? -1 : a > b ? 1 : 0));
@@ -424,7 +424,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 				messages: ({ input }) => input.messages,
 				tools: ({ input }) => input.tools,
 				toolChoice: ({ input }) => input.toolChoice,
-				reasoning: ({ input }) => input.reasoning,
+				includeReasoning: ({ input }) => input.includeReasoning,
 				temperature: ({ input }) => input.temperature,
 				maxOutputTokens: ({ input }) => input.maxOutputTokens,
 				topP: ({ input }) => input.topP,
@@ -496,7 +496,7 @@ function createTextLogic(config, execute) {
 			tools: resolveTextLogicValue(config.tools, args),
 			toolChoice: resolveTextLogicValue(config.toolChoice, args),
 			outputSchema: schemas.output,
-			reasoning: resolveTextLogicValue(config.reasoning, args),
+			includeReasoning: resolveTextLogicValue(config.includeReasoning, args),
 			temperature: resolveTextLogicValue(config.temperature, args),
 			maxOutputTokens: resolveTextLogicValue(config.maxOutputTokens, args),
 			topP: resolveTextLogicValue(config.topP, args),
@@ -643,7 +643,7 @@ function buildEnvelopeSchema(inner, options = {}) {
 */
 function parseStructuredEnvelope(request, value) {
 	if (!request.outputSchema) throw new Error("parseStructuredEnvelope: the request declares no outputSchema.");
-	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning }), value);
+	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.includeReasoning }), value);
 }
 /**
 * Merges request-declared and call-site `tools`, dispatches to the
@@ -1048,12 +1048,24 @@ Object.defineProperty(exports, "DECIDE_ACTOR", {
 		return DECIDE_ACTOR;
 	}
 });
+Object.defineProperty(exports, "GENERATE_TEXT_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return GENERATE_TEXT_ACTOR;
+	}
+});
 Object.defineProperty(exports, "INTERPRET_SOURCE", {
 	enumerable: true,
 	get: function() {
 		return INTERPRET_SOURCE;
 	}
 });
+Object.defineProperty(exports, "STREAM_TEXT_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return STREAM_TEXT_ACTOR;
+	}
+});
 Object.defineProperty(exports, "USER_INPUT_ACTOR", {
 	enumerable: true,
 	get: function() {

package/dist/{decision-DsIkEuHz.mjs → decision-JWx6n3xR.mjs}

@@ -167,7 +167,7 @@ function toolMessage(content) {
 * ```
 */
 function getStateMeta(snapshot) {
-	const nodes = snapshot._nodes;
+	const nodes = snapshot.nodes;
 	const depthById = new Map(nodes?.map((node) => [node.id, node.path.length]));
 	const depth = (id) => depthById.get(id) ?? id.split(".").length;
 	const entries = Object.entries(snapshot.getMeta()).filter((entry) => entry[1] != null).sort(([a], [b]) => depth(a) - depth(b) || (a < b ? -1 : a > b ? 1 : 0));
@@ -423,7 +423,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 				messages: ({ input }) => input.messages,
 				tools: ({ input }) => input.tools,
 				toolChoice: ({ input }) => input.toolChoice,
-				reasoning: ({ input }) => input.reasoning,
+				includeReasoning: ({ input }) => input.includeReasoning,
 				temperature: ({ input }) => input.temperature,
 				maxOutputTokens: ({ input }) => input.maxOutputTokens,
 				topP: ({ input }) => input.topP,
@@ -495,7 +495,7 @@ function createTextLogic(config, execute) {
 			tools: resolveTextLogicValue(config.tools, args),
 			toolChoice: resolveTextLogicValue(config.toolChoice, args),
 			outputSchema: schemas.output,
-			reasoning: resolveTextLogicValue(config.reasoning, args),
+			includeReasoning: resolveTextLogicValue(config.includeReasoning, args),
 			temperature: resolveTextLogicValue(config.temperature, args),
 			maxOutputTokens: resolveTextLogicValue(config.maxOutputTokens, args),
 			topP: resolveTextLogicValue(config.topP, args),
@@ -642,7 +642,7 @@ function buildEnvelopeSchema(inner, options = {}) {
 */
 function parseStructuredEnvelope(request, value) {
 	if (!request.outputSchema) throw new Error("parseStructuredEnvelope: the request declares no outputSchema.");
-	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning }), value);
+	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.includeReasoning }), value);
 }
 /**
 * Merges request-declared and call-site `tools`, dispatches to the
@@ -1029,4 +1029,4 @@ async function resolveDecision(request, executors, options = {}) {
 	throw new AgentDecisionExhaustedError(attempts);
 }
 //#endregion
-export { isUnboundPlaceholder as A, getMachineStructuralHash as B, parseStructuredEnvelope as C, getMachineIdlePredicate as D, executorBoundLogics as E, djb2Hex as F, toolMessage as G, isStandardSchema as H, findNonSerializableContextPaths as I, userMessage as K, getAgentMessages as L, machineStaticTransitionTargets as M, missingActor as N, getMachineStaticTransitionTargets as O, assistantMessage as P, getJsonSchema as R, parseOutput as S, agentExecutionOptions as T, resolveMachineVersion as U, getStateMeta as V, systemMessage as W, getAgentOutputMode as _, resolveDecision as a, normalizeGeneratorResult as b, AGENT_USAGE_TOKEN_FIELDS as c, USER_INPUT_ACTOR as d, bindRequestExecutor as f, executeAgentTextRequest as g, createTextLogic as h, renderDecisionAttempts as i, machineIdlePredicates as j, getRegisteredAgentExecutionOptions as k, DECIDE_ACTOR as l, builtinTextActors as m, createDecideActor as n, getAcceptedEvents as o, buildEnvelopeSchema as p, validateSchemaSync as q, isDecisionLogic as r, parseAgentEvent as s, AgentDecisionExhaustedError as t, INTERPRET_SOURCE as u, getCallUsage as v, userInputActor as w, parseModelRef as x, isTextLogic as y, getJsonSchemaSync as z };
+export { getMachineStaticTransitionTargets as A, getJsonSchema as B, parseModelRef as C, agentExecutionOptions as D, userInputActor as E, missingActor as F, resolveMachineVersion as G, getMachineStructuralHash as H, assistantMessage as I, userMessage as J, systemMessage as K, djb2Hex as L, isUnboundPlaceholder as M, machineIdlePredicates as N, executorBoundLogics as O, machineStaticTransitionTargets as P, findNonSerializableContextPaths as R, normalizeGeneratorResult as S, parseStructuredEnvelope as T, getStateMeta as U, getJsonSchemaSync as V, isStandardSchema as W, validateSchemaSync as Y, createTextLogic as _, resolveDecision as a, getCallUsage as b, AGENT_USAGE_TOKEN_FIELDS as c, INTERPRET_SOURCE as d, STREAM_TEXT_ACTOR as f, builtinTextActors as g, buildEnvelopeSchema as h, renderDecisionAttempts as i, getRegisteredAgentExecutionOptions as j, getMachineIdlePredicate as k, DECIDE_ACTOR as l, bindRequestExecutor as m, createDecideActor as n, getAcceptedEvents as o, USER_INPUT_ACTOR as p, toolMessage as q, isDecisionLogic as r, parseAgentEvent as s, AgentDecisionExhaustedError as t, GENERATE_TEXT_ACTOR as u, executeAgentTextRequest as v, parseOutput as w, isTextLogic as x, getAgentOutputMode as y, getAgentMessages as z };

package/dist/index.cjs

@@ -1,10 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_errors = require("./errors-DUBBzRLP.cjs");
-const require_setup_agent = require("./setup-agent-BFA4VKpN.cjs");
-const require_decision = require("./decision-t26zsnSR.cjs");
+const require_setup_agent = require("./setup-agent-91FSuZbB.cjs");
+const require_decision = require("./decision-BnTCsuJv.cjs");
 const require_event_log_store = require("./event-log-store-a_TKy1gk.cjs");
 require("./validate.cjs");
 let xstate = require("xstate");
+let xstate_durable = require("xstate/durable");
 //#region src/internal/state-request-pass.ts
 async function runTextPhase(stateRequest, baseMessages, deps) {
 	const { model, system } = stateRequest;
@@ -286,7 +287,7 @@ function serializeTraceEvent(event, options = {}) {
 	return out;
 }
 function snapshotNodes(snapshot) {
-	return (snapshot._nodes ?? []).map((raw) => {
+	return (snapshot.nodes ?? []).map((raw) => {
 		const node = raw;
 		return {
 			id: node.id ?? "",
@@ -569,9 +570,13 @@ function invokingActorOf(self, runCtx) {
 * identical event shapes by construction. @internal
 */
 function bindTextLogic(logic, runCtx) {
-	return logic.withExecutor(async ({ request, self: selfArg, signal }) => {
+	return logic.withExecutor(async ({ request: rawRequest, self: selfArg, signal }) => {
 		const self = selfArg;
 		const { id, src } = selfIdAndSrc(self);
+		const request = rawRequest.name === void 0 && src !== "" && src !== "agent.generateText" && src !== "agent.streamText" ? {
+			...rawRequest,
+			name: src
+		} : rawRequest;
 		const executor = logic.mode === "stream" ? runCtx.streamText : runCtx.generateText;
 		if (!executor) throw new Error(`No '${logic.mode === "stream" ? "streamText" : "generateText"}' executor provided.`);
 		const requestWithTools = {
@@ -1161,6 +1166,7 @@ function createAgentSession(machine, options, lifecycle) {
 		const aligned = Object.assign(Object.create(Object.getPrototypeOf(effectiveSnapshot)), effectiveSnapshot);
 		if (machineOwnVersion === void 0) delete aligned.version;
 		else aligned.version = machineOwnVersion;
+		delete aligned.machine;
 		effectiveSnapshot = aligned;
 	}
 	const priorMessages = require_decision.getAgentMessages(effectiveSnapshot);
@@ -2084,8 +2090,8 @@ function lintAgentMachine(machine, options = {}) {
 	return diagnostics;
 }
 /**
-* Thrown by `lintAgentMachine(machine, { throw: true })` when lint finds
-* failing diagnostics.
+* Thrown by `lintAgentMachine(machine, { throw: true })` (and its
+* {@link assertAgentMachine} alias) when lint finds failing diagnostics.
 * `diagnostics` holds the findings; the message lists them one per finding,
 * so a test runner's failure output reads like the CLI's lint report.
 */
@@ -2098,6 +2104,26 @@ var AgentLintError = class extends require_errors.AgentError {
 		this.diagnostics = diagnostics;
 	}
 };
+/**
+* Asserts a machine passes {@link lintAgentMachine}: returns silently when
+* clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
+* otherwise — sugar for `lintAgentMachine(machine, { ...options, throw: true })`.
+* Fails on error-severity findings; set `warnings: true` to fail on warnings
+* too. The one-liner for tests and generation loops:
+*
+* @example
+* ```ts
+* test('agent machine is structurally sound', () => {
+*   assertAgentMachine(machine);
+* });
+* ```
+*/
+function assertAgentMachine(machine, options = {}) {
+	lintAgentMachine(machine, {
+		...options,
+		throw: true
+	});
+}
 function pendingInvokes(step) {
 	const out = [];
 	for (const action of step.actions) {
@@ -2124,6 +2150,21 @@ function takeFromQueue(channel, src) {
 * the real transition logic. Returns the terminal `status`, final `snapshot`,
 * and a `trail` of every step taken.
 *
+* Decisions run through the live run's own validation/retry core,
+* {@link resolveDecision}, with the script standing in for the model: each
+* attempt consumes the next queued {@link ChosenEvent} for that src, so an
+* unknown, payload-invalid, or guard-rejected event is NOT silently swallowed
+* — the next queued decision is tried, exactly as a live run re-asks the
+* model. The decision logic's `maxRetries` caps attempts as it would live;
+* when retries continue past the end of the queue, the last queued decision
+* repeats (a scripted model that insists). The repeat applies only within one
+* decision request's retries — each new decision request must have its own
+* queued entry, or the dry-script error throws as usual. Exhausting all
+* attempts delivers
+* the resulting {@link AgentDecisionExhaustedError} to the machine as the
+* decision invoke's error (so an `onError` transition observes it, as it
+* would live); with no `onError` to catch it, it is thrown.
+*
 * Throws a descriptive error when the script runs dry mid-request, naming the
 * pending request's kind, src, and id so the missing scripted response is
 * obvious.
@@ -2132,7 +2173,10 @@ function takeFromQueue(channel, src) {
 * ```ts
 * const { status, snapshot } = simulateAgent(machine, {
 *   input: { topic: 'state machines' },
-*   script: { decisions: { 'agent.decide': [{ type: 'END' }] } },
+*   script: {
+*     decisions: { 'agent.decide': [{ type: 'ESCALATE' }] },
+*     events: [{ type: 'APPROVE' }], // crosses the human gate
+*   },
 * });
 * ```
 */
@@ -2141,11 +2185,12 @@ async function simulateAgent(machine, options) {
 	const script = {
 		text: mapValues(options.script.text ?? {}, (arr) => [...arr]),
 		decisions: mapValues(options.script.decisions ?? {}, (arr) => [...arr]),
-		invokes: mapValues(options.script.invokes ?? {}, (arr) => [...arr])
+		invokes: mapValues(options.script.invokes ?? {}, (arr) => [...arr]),
+		events: [...options.script.events ?? []]
 	};
 	if (options.script.userInput?.length) script.invokes[USER_INPUT_SRC] = [...options.script.userInput, ...script.invokes[USER_INPUT_SRC] ?? []];
 	let step = require_setup_agent.initialAgentStep(machine, options.input);
-	const trail = [];
+	const trail = [{ state: step.snapshot.value }];
 	for (let i = 0; i < maxSteps; i++) {
 		if (step.done) return {
 			status: "done",
@@ -2155,14 +2200,10 @@ async function simulateAgent(machine, options) {
 		const request = step.requests[0];
 		if (request) {
 			if (request.kind === "decision") {
-				const decisionSrc = new Map(pendingInvokes(step).map((invoke) => [invoke.id, invoke.src])).get(request.id) ?? request.id;
-				const taken = takeFromQueue(script.decisions, decisionSrc);
-				if (!taken.found) throw scriptDryError("decision", decisionSrc, request.id, request);
-				step = require_setup_agent.transitionAgentStep(machine, step, taken.value);
-				trail.push({
-					state: step.snapshot.value,
-					appliedEvent: taken.value
-				});
+				const invokeMeta = findInvokeMetadata(step, request.id);
+				const src = invokeMeta?.src ?? request.id;
+				const decisionSrc = src in (script.decisions ?? {}) ? src : request.id in (script.decisions ?? {}) ? request.id : src;
+				step = await applyScriptedDecision(machine, step, request, decisionSrc, invokeMeta?.logic, script, trail);
 				continue;
 			}
 			const taken = takeFromQueue(script.text, request.src);
@@ -2193,6 +2234,18 @@ async function simulateAgent(machine, options) {
 			});
 			continue;
 		}
+		const external = script.events;
+		if (external.length > 0) {
+			const event = external.shift();
+			if (!step.snapshot.can(event)) throw new Error(`simulateAgent: scripted external event '${event.type}' cannot be taken in state ${JSON.stringify(step.snapshot.value)} (no handler, or its guard rejected it). A live run's send would be silently dropped here; fix the script's \`events\` queue.`);
+			step = require_setup_agent.transitionAgentStep(machine, step, event);
+			trail.push({
+				state: step.snapshot.value,
+				appliedEvent: event,
+				external: true
+			});
+			continue;
+		}
 		return {
 			status: "idle",
 			snapshot: step.snapshot,
@@ -2205,6 +2258,66 @@ async function simulateAgent(machine, options) {
 		trail
 	};
 }
+async function applyScriptedDecision(machine, step, request, decisionSrc, invokeLogic, script, trail) {
+	const dequeued = [];
+	const decide = async () => {
+		const taken = takeFromQueue(script.decisions, decisionSrc);
+		if (taken.found) {
+			dequeued.push(taken.value);
+			return { event: taken.value };
+		}
+		if (dequeued.length === 0) throw scriptDryError("decision", decisionSrc, request.id, request);
+		return { event: dequeued[dequeued.length - 1] };
+	};
+	const maxRetries = (require_decision.isDecisionLogic(invokeLogic) ? invokeLogic : resolveRegisteredDecisionLogic(machine, decisionSrc))?.maxRetries;
+	let chosen;
+	try {
+		chosen = await require_decision.resolveDecision(request, { decide }, {
+			maxRetries,
+			canTake: (event) => step.snapshot.can(event)
+		});
+	} catch (error) {
+		if (!(error instanceof require_decision.AgentDecisionExhaustedError)) throw error;
+		const next = require_setup_agent.transitionAgentStep(machine, step, {
+			type: "xstate.error.actor",
+			actorId: request.id,
+			...sessionIdOf(step.snapshot, request.id),
+			error
+		});
+		if (next.snapshot.status === "error") throw error;
+		trail.push({
+			state: next.snapshot.value,
+			rejectedEvents: dequeued
+		});
+		return next;
+	}
+	const next = require_setup_agent.transitionAgentStep(machine, step, chosen);
+	const rejected = dequeued.slice(0, -1);
+	trail.push({
+		state: next.snapshot.value,
+		appliedEvent: chosen,
+		...rejected.length > 0 ? { rejectedEvents: rejected } : {}
+	});
+	return next;
+}
+function findInvokeMetadata(step, id) {
+	for (const action of step.actions) {
+		const metadata = require_setup_agent.getInvokeEffectMetadata(action);
+		if (metadata?.id !== id) continue;
+		return {
+			...typeof metadata.src === "string" ? { src: metadata.src } : {},
+			logic: metadata.logic ?? (typeof metadata.src === "object" ? metadata.src : void 0)
+		};
+	}
+}
+function resolveRegisteredDecisionLogic(machine, src) {
+	const candidate = require_decision.getRegisteredAgentExecutionOptions(machine).actors?.[src] ?? machine.sources?.actors?.[src];
+	return require_decision.isDecisionLogic(candidate) ? candidate : void 0;
+}
+function sessionIdOf(snapshot, id) {
+	const child = snapshot.children[id];
+	return typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {};
+}
 function mapValues(obj, fn) {
 	return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, fn(value)]));
 }
@@ -2241,6 +2354,10 @@ async function explore(machine, options, stopWhen) {
 	const advance = (step) => {
 		let current = step;
 		for (let i = 0; i < MAX_ADVANCE_STEPS; i++) {
+			if (stopWhen?.(current.snapshot)) return {
+				step: current,
+				hit: true
+			};
 			if (current.done) return { step: current };
 			const request = current.requests[0];
 			if (request && request.kind === "text") {
@@ -2273,8 +2390,8 @@ async function explore(machine, options, stopWhen) {
 			hitPathCap = true;
 			return;
 		}
-		const { step: settled, blockedSrc } = advance(step);
-		if (stopWhen?.(settled.snapshot)) {
+		const { step: settled, blockedSrc, hit } = advance(step);
+		if (hit) {
 			witness = path;
 			return;
 		}
@@ -2369,8 +2486,11 @@ async function explorePaths(machine, options = {}) {
 	return (await explore(machine, options)).report;
 }
 /**
-* Answers "can the machine reach `statePath`?" by exploring its branches (a
-* thin wrapper over {@link explorePaths}). Returns
+* Answers "can the machine reach this?" by exploring its branches (a thin
+* wrapper over {@link explorePaths}). The target is either a state path string
+* (`snapshot.matches(...)` semantics) or a snapshot predicate — the predicate
+* form checks any property (a context invariant, a tag, a state+context
+* combination) without reifying a sentinel state for it. Returns
 * `{ reachable: true, witness }` with the event sequence that reaches it, or
 * `{ reachable: false }`.
 *
@@ -2379,11 +2499,21 @@ async function explorePaths(machine, options = {}) {
 * const { reachable, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
 * // reachable → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
 * ```
+*
+* @example Predicate target — a violation property, no sentinel state needed
+* ```ts
+* const violation = await canReach(
+*   refundMachine,
+*   (snapshot) => snapshot.matches('issued') && !snapshot.context.approved,
+*   { input: { amount: 5000 } },
+* );
+* // violation.reachable → false is the safety proof
+* ```
 */
-async function canReach(machine, statePath, options = {}) {
-	const { witness } = await explore(machine, options, (snapshot) => {
+async function canReach(machine, target, options = {}) {
+	const { witness } = await explore(machine, options, typeof target === "function" ? target : (snapshot) => {
 		try {
-			return snapshot.matches(statePath);
+			return snapshot.matches(target);
 		} catch {
 			return false;
 		}
@@ -2715,6 +2845,8 @@ async function runSeam(machine, options) {
 	let calls = 0;
 	let seamMatches = 0;
 	let seamOutput;
+	let seamUsage;
+	const callLog = [];
 	let seamReached = false;
 	let callsBeforeSeam = -1;
 	let seamStateAt = 0;
@@ -2739,6 +2871,15 @@ async function runSeam(machine, options) {
 	const route = async (request, info) => {
 		const callIndex = calls++;
 		const isSeam = request.name === seam.request && seamMatches++ === (seam.occurrence ?? 0);
+		const ledger = (source) => {
+			callLog.push({
+				...request.name !== void 0 ? { name: request.name } : {},
+				model: request.model,
+				key: queueKeyOf(request),
+				source,
+				seam: isSeam
+			});
+		};
 		if (isSeam && candidate) {
 			await takeScriptedSlot(request, info);
 			seamReached = true;
@@ -2747,15 +2888,19 @@ async function runSeam(machine, options) {
 			seamEventAt = liveEvents;
 			const result = await candidate(request, info);
 			seamOutput = await seamOutputOf(result, request);
+			seamUsage = require_decision.getCallUsage(result);
+			ledger("candidate");
 			return result;
 		}
 		const scripted = await scriptedAnswer(request, info);
+		ledger("script");
 		if (!isSeam) return scripted;
 		seamReached = true;
 		callsBeforeSeam = callIndex;
 		seamStateAt = statePath.length;
 		seamEventAt = liveEvents;
 		seamOutput = scripted.output;
+		seamUsage = scripted.usage;
 		return scripted;
 	};
 	const executors = {
@@ -2817,7 +2962,9 @@ async function runSeam(machine, options) {
 	return {
 		result,
 		seamOutput,
+		...seamUsage !== void 0 ? { seamUsage } : {},
 		callsBeforeSeam,
+		calls: callLog,
 		before: {
 			statePath: statePath.slice(0, splitStateAt),
 			events: events.slice(0, splitAt)
@@ -2829,6 +2976,211 @@ async function runSeam(machine, options) {
 	};
 }
 //#endregion
+//#region src/durable.ts
+/**
+* The durable host runner: {@link runDurableAgent} drives an executor-bound
+* agent machine on xstate's `createDurable` execution (`xstate/durable`),
+* with the agent event log as the journal.
+*
+* Where {@link replay} + `getAgentEffects` hand a host an effect list to run
+* itself, `runDurableAgent` owns the whole loop on the durable runtime:
+* invoked actors execute live through xstate's own runtime, every EXTERNAL
+* event (invoke completions included) is appended to the log, and a resume
+* folds the log back through pure transitions — an invoke whose completion is
+* already journaled is never re-started, so recorded model calls are never
+* re-executed. Crash recovery re-runs only the work that was still in flight.
+*
+* @module
+*/
+const DONE_ACTOR_EVENT_TYPE = "xstate.done.actor";
+const ERROR_ACTOR_EVENT_TYPE = "xstate.error.actor";
+function completionActorId(event) {
+	if (event.type !== DONE_ACTOR_EVENT_TYPE && event.type !== ERROR_ACTOR_EVENT_TYPE) return;
+	const actorId = event.actorId;
+	return typeof actorId === "string" ? actorId : void 0;
+}
+/** Thrown by the adapter's `waitForEvent` when nothing can produce an event. */
+const IDLE = Symbol("agent.durable.idle");
+function createMailbox() {
+	const queue = [];
+	const waiters = [];
+	return {
+		push(event) {
+			const waiter = waiters.shift();
+			if (waiter) waiter(event);
+			else queue.push(event);
+		},
+		take() {
+			const next = queue.shift();
+			if (next !== void 0) return Promise.resolve(next);
+			return new Promise((resolve) => waiters.push(resolve));
+		},
+		size: () => queue.length
+	};
+}
+/**
+* Runs an agent machine as a durable execution: journal in, journal out.
+*
+* A fresh call starts from `input` and appends a reserved init entry; a
+* resume call folds `entries` through pure transitions first — invokes whose
+* completions are journaled are suppressed (their recorded results replay
+* instead of re-executing), while work that was in flight at the crash
+* re-executes live. After the journal, an optional `options.event` is
+* delivered. The call settles:
+*
+* - `done` when the machine reaches a final state, with `output`;
+* - `idle` when the frontier needs an external event the host has not
+*   supplied (no live work pending, or `isIdle` says the pending work is a
+*   human wait). Persist `entries` and call again with them later.
+*
+* ```ts
+* const first = await runDurableAgent(machine, { input, executors });
+* // ... persist first.entries; later, in a new process:
+* const next = await runDurableAgent(machine, {
+*   entries: first.entries,
+*   event: { type: "APPROVE" },
+*   executors,
+* });
+* ```
+*
+* @experimental Built on xstate's experimental `xstate/durable` entrypoint.
+*/
+async function runDurableAgent(machine, options = {}) {
+	const bound = options.executors ? provideExecutors(machine, options.executors, {
+		actors: options.actors,
+		onChunk: options.onChunk,
+		onTrace: options.onTrace
+	}) : options.actors ? machine.provide({ actors: options.actors }) : machine;
+	const machineId = machine.config.id ?? machine.id ?? "(machine)";
+	const machineVersion = options.machineVersion ?? require_decision.resolveMachineVersion(machine);
+	const priorEntries = options.entries ?? [];
+	if (priorEntries.length > 0) require_setup_agent.validateReplayEntries(priorEntries, {
+		machineId,
+		machineVersion
+	}, "Durable journal entries");
+	const hasInit = priorEntries[0]?.event.type === require_setup_agent.AGENT_INIT_EVENT_TYPE;
+	const input = hasInit ? priorEntries[0].event.input : options.input;
+	const journal = priorEntries.slice(hasInit ? 1 : 0).map((entry) => entry.event);
+	const journaledCompletions = /* @__PURE__ */ new Map();
+	for (const event of journal) {
+		const actorId = completionActorId(event);
+		if (actorId !== void 0) journaledCompletions.set(actorId, (journaledCompletions.get(actorId) ?? 0) + 1);
+	}
+	const storedExecutionId = hasInit ? priorEntries[0].metadata?.executionId : void 0;
+	const executionId = typeof storedExecutionId === "string" ? storedExecutionId : hasInit ? priorEntries[0].id : crypto.randomUUID();
+	const mailbox = createMailbox();
+	const rootAddress = machineId;
+	const suppressedChildren = /* @__PURE__ */ new WeakSet();
+	const startsSeen = /* @__PURE__ */ new Map();
+	const liveInFlight = /* @__PURE__ */ new Set();
+	const findChildRef = (effect) => {
+		const raw = effect;
+		const candidates = [raw.actor, ...Array.isArray(raw.args) ? raw.args : []];
+		for (const candidate of candidates) {
+			const ref = candidate;
+			if (ref && typeof ref.sessionId === "string" && typeof ref.id === "string") return ref;
+		}
+	};
+	let replaying = journal.length > 0;
+	let liveEventConsumed = false;
+	let latestSnapshot;
+	const execution = (0, xstate_durable.createDurable)(bound, {
+		executionId,
+		sendEvent(source, target, event) {
+			if (target.address === rootAddress) {
+				mailbox.push(event);
+				return;
+			}
+			(0, xstate.deliverEvent)(source, target, event);
+		},
+		runtime(_metadata, effect) {
+			const type = effect.type;
+			if (type === "@xstate.spawn" || type === "@xstate.start") {
+				const child = findChildRef(effect);
+				if (!child) return {};
+				if (type === "@xstate.spawn") {
+					const seen = (startsSeen.get(child.id) ?? 0) + 1;
+					startsSeen.set(child.id, seen);
+					if (seen <= (journaledCompletions.get(child.id) ?? 0)) suppressedChildren.add(child);
+					else liveInFlight.add(child.id);
+				}
+				if (suppressedChildren.has(child)) return {
+					spawnActor() {},
+					startActor() {}
+				};
+			}
+			return {};
+		},
+		executeAction(action) {
+			if (replaying) return;
+			action.exec?.();
+		},
+		async waitForEvent() {
+			if (mailbox.size() > 0) return await mailbox.take();
+			if (liveInFlight.size > 0 && !(options.isIdle?.(latestSnapshot) ?? false)) return await mailbox.take();
+			if (!liveEventConsumed && options.event !== void 0) {
+				liveEventConsumed = true;
+				return options.event;
+			}
+			throw IDLE;
+		}
+	});
+	const entries = [...priorEntries];
+	const entryOptions = {
+		machineVersion,
+		verification: options.verification ?? false
+	};
+	const appendEntry = (event) => {
+		const entry = require_setup_agent.createReplayEntry(machine, entries, event, entryOptions);
+		entries.push(entry);
+		options.onEntry?.(entry);
+	};
+	if (!hasInit) {
+		const entry = require_setup_agent.initEntry(machine, input, {
+			...entryOptions,
+			metadata: { executionId }
+		});
+		entries.push(entry);
+		options.onEntry?.(entry);
+	}
+	let journalIndex = 0;
+	let [snapshot, effects] = execution.initialTransition(input);
+	latestSnapshot = snapshot;
+	for (;;) {
+		await execution.executeEffects(effects);
+		const machineSnapshot = snapshot;
+		if (machineSnapshot.status === "done") return {
+			status: "done",
+			output: machineSnapshot.output,
+			snapshot,
+			entries
+		};
+		if (machineSnapshot.status === "error") throw machineSnapshot.error;
+		let event;
+		let fromJournal = false;
+		if (journalIndex < journal.length) {
+			event = journal[journalIndex];
+			journalIndex++;
+			fromJournal = true;
+			replaying = journalIndex < journal.length;
+		} else try {
+			event = await execution.waitForEvent();
+		} catch (error) {
+			if (error === IDLE) return {
+				status: "idle",
+				snapshot,
+				entries
+			};
+			throw error;
+		}
+		const completedId = completionActorId(event);
+		if (completedId !== void 0) liveInFlight.delete(completedId);
+		if (!fromJournal) appendEntry(event);
+		[snapshot, effects] = execution.transition(snapshot, event);
+		latestSnapshot = snapshot;
+	}
+}
+//#endregion
 exports.AGENT_EVENT_SCHEMA_VERSION = require_event_log_store.AGENT_EVENT_SCHEMA_VERSION;
 exports.AGENT_INIT_EVENT_TYPE = require_setup_agent.AGENT_INIT_EVENT_TYPE;
 exports.AGENT_TRACE_SCHEMA_VERSION = AGENT_TRACE_SCHEMA_VERSION;
@@ -2846,6 +3198,7 @@ exports.AgentSnapshotVersionMismatchError = AgentSnapshotVersionMismatchError;
 exports.NonSerializableAgentEventError = require_event_log_store.NonSerializableAgentEventError;
 exports.appendMessages = require_setup_agent.appendMessages;
 exports.assertAgentLogEntry = require_event_log_store.assertAgentLogEntry;
+exports.assertAgentMachine = assertAgentMachine;
 exports.assertEventLogStoreConformance = require_event_log_store.assertEventLogStoreConformance;
 exports.assertJsonSerializable = require_event_log_store.assertJsonSerializable;
 exports.assistantMessage = require_decision.assistantMessage;
@@ -2890,6 +3243,7 @@ exports.renderDecisionAttempts = require_decision.renderDecisionAttempts;
 exports.replay = require_setup_agent.replay;
 exports.resolveDecision = require_decision.resolveDecision;
 exports.runAgent = runAgent;
+exports.runDurableAgent = runDurableAgent;
 exports.runSeam = runSeam;
 exports.serializeTraceEvent = serializeTraceEvent;
 Object.defineProperty(exports, "setupAgent", {