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

package/dist/{run-agent-Dmf8GV2d.cjs → run-agent-ctLCvNgL.cjs}

@@ -1,8 +1,6 @@
-const require_text_logic = require("./text-logic-f5F5sCdc.cjs");
-const require_decision = require("./decision-CmM8-HHz.cjs");
-const require_usage = require("./usage-efOQPdf_.cjs");
-const require_event_log_store = require("./event-log-store-C-COhIXP.cjs");
-require("./validate.cjs");
+const require_event_log = require("./event-log-BZRfBRd7.cjs");
+const require_decision = require("./decision-CIb7ddIv.cjs");
+const require_event_log_store = require("./event-log-store-DZR4IIWe.cjs");
 let xstate = require("xstate");
 let xstate_durable = require("xstate/durable");
 //#region src/run-agent.ts
@@ -14,7 +12,10 @@ let xstate_durable = require("xstate/durable");
 * a snapshot mutated out of band), not a recoverable resume: pass the log
 * alone, or the matching snapshot.
 */
-var AgentSnapshotDivergedError = class extends require_text_logic.AgentError {
+var AgentSnapshotDivergedError = class extends require_event_log.AgentError {
+	expected;
+	actual;
+	logIndex;
 	constructor(expected, actual, logIndex) {
 		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;
@@ -27,9 +28,9 @@ function hashResumeSnapshot(snapshot) {
 	if (snapshot !== null && typeof snapshot === "object" && "agentMeta" in snapshot) {
 		const rest = {};
 		for (const [key, value] of Object.entries(snapshot)) if (key !== "agentMeta") rest[key] = value;
-		return require_event_log_store.getSnapshotStateHash(rest);
+		return require_event_log.getSnapshotStateHash(rest);
 	}
-	return require_event_log_store.getSnapshotStateHash(snapshot);
+	return require_event_log.getSnapshotStateHash(snapshot);
 }
 function readAgentMeta(snapshot) {
 	const meta = snapshot?.agentMeta;
@@ -146,7 +147,7 @@ let nextRunAgentTraceId = 1;
 * ]
 * ```
 */
-var AgentMaxModelCallsExceededError = class extends require_text_logic.AgentError {
+var AgentMaxModelCallsExceededError = class extends require_event_log.AgentError {
 	/** The budget that was exceeded (`options.maxModelCalls`). */
 	maxModelCalls;
 	constructor(maxModelCalls) {
@@ -215,7 +216,7 @@ function assertBindable(machine, effectiveSources, executors) {
 		isChild: false,
 		childPath: "",
 		rebindable: true,
-		visited: new Set([machine])
+		visited: /* @__PURE__ */ new Set([machine])
 	});
 }
 function assertMachineBindable(machine, effectiveSources, executors, ctx) {
@@ -228,7 +229,7 @@ function assertMachineBindable(machine, effectiveSources, executors, ctx) {
 				assertChildMachineBindable(src, src, stateName, executors, ctx);
 				continue;
 			}
-			if ((require_text_logic.isTextLogic(src) || require_decision.isDecisionLogic(src)) && !require_text_logic.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.`);
+			if ((require_event_log.isTextLogic(src) || require_decision.isDecisionLogic(src)) && !require_event_log.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];
@@ -238,19 +239,19 @@ function assertMachineBindable(machine, effectiveSources, executors, ctx) {
 			continue;
 		}
 		if (require_decision.isDecisionLogic(logic)) {
-			if (require_text_logic.executorBoundLogics.has(logic)) continue;
+			if (require_event_log.executorBoundLogics.has(logic)) continue;
 			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, "decision");
 			if (!executors.decide) throw new Error(`createAgentRuntime: ${where} '${stateName}' invokes decision source '${src}' but no 'decide' executor was provided to createAgentRuntime(...).`);
 			continue;
 		}
-		if (require_text_logic.isTextLogic(logic)) {
-			if (require_text_logic.executorBoundLogics.has(logic)) continue;
+		if (require_event_log.isTextLogic(logic)) {
+			if (require_event_log.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(`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 (require_text_logic.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}': ... } }).`);
+		if (require_event_log.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
@@ -264,7 +265,7 @@ function assertChildMachineBindable(childMachine, childSrc, stateName, executors
 		isChild: true,
 		childPath,
 		rebindable: ctx.rebindable && typeof childSrc === "string",
-		visited: new Set([...ctx.visited, childMachine])
+		visited: /* @__PURE__ */ new Set([...ctx.visited, childMachine])
 	});
 }
 /** The loud bind-time error for an unbound agent request reached under a
@@ -395,11 +396,11 @@ function bindTextLogic(logic, runCtx) {
 				...id !== "" ? { requestId: id } : {},
 				...callKey !== void 0 ? { callKey } : {}
 			});
-			const output = await require_text_logic.normalizeGeneratorResult(raw, id);
+			const output = await require_event_log.normalizeGeneratorResult(raw, id);
 			const rawReasoning = raw?.reasoning;
 			const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
-			const usage = require_text_logic.getCallUsage(raw);
-			const finishReason = require_text_logic.getCallFinishReason(raw);
+			const usage = require_event_log.getCallUsage(raw);
+			const finishReason = require_event_log.getCallFinishReason(raw);
 			if (usage) runCtx.recordUsage?.(usage, {
 				kind: "text",
 				...id !== "" ? { id } : {},
@@ -418,7 +419,7 @@ function bindTextLogic(logic, runCtx) {
 			}, self);
 			return {
 				result: output,
-				messages: require_text_logic.responseMessagesOf(raw)
+				messages: require_event_log.responseMessagesOf(raw)
 			};
 		} catch (error) {
 			runCtx.emitTrace?.({
@@ -451,8 +452,8 @@ function createCountingDecide(runCtx, self) {
 				...info?.requestId === void 0 && id !== "" ? { requestId: id } : {},
 				...info?.callKey === void 0 && callKey !== void 0 ? { callKey } : {}
 			});
-			const usage = require_text_logic.getCallUsage(result);
-			const finishReason = require_text_logic.getCallFinishReason(result);
+			const usage = require_event_log.getCallUsage(result);
+			const finishReason = require_event_log.getCallFinishReason(result);
 			if (usage) {
 				const { src } = selfIdAndSrc(self);
 				runCtx.recordUsage?.(usage, {
@@ -509,17 +510,53 @@ function bindDecisionLogic(logic, runCtx) {
 			eventTypes: declaredEventTypes
 		}) : [];
 		const lowered = logic.request(input);
-		const chosen = await require_decision.resolveDecision({
+		const request = {
 			...lowered,
 			id,
 			name: lowered.name ?? id,
 			input,
 			events
-		}, { decide: createCountingDecide(runCtx, self) }, {
-			maxRetries: logic.maxRetries,
+		};
+		const withheld = [];
+		const options = require_decision.acceptedDecisionOptions(request, (event) => {
+			let accepted;
+			try {
+				accepted = actorRef ? actorRef.getSnapshot().can(event) : true;
+			} catch {
+				accepted = false;
+			}
+			if (!accepted) withheld.push(event);
+			return accepted;
+		});
+		if (options) {
+			request.options = options;
+			request.withheld = withheld;
+		}
+		if (options?.length === 0) {
+			const error = new require_decision.AgentDecisionExhaustedError([]);
+			error.message = `Decision '${request.name}' has no offered option the current snapshot accepts; no model call was made.`;
+			runCtx.emitTrace?.({
+				type: "request.start",
+				request
+			}, self);
+			runCtx.emitTrace?.({
+				type: "request.error",
+				request,
+				error
+			}, self);
+			throw error;
+		}
+		const decide = createCountingDecide(runCtx, self);
+		let priorAttempts = [];
+		const chosen = await require_decision.resolveDecision(request, { decide: (attemptRequest, info) => {
+			priorAttempts = attemptRequest.attempts;
+			return decide(attemptRequest, info);
+		} }, {
+			maxRetries: lowered.maxRetries ?? logic.maxRetries,
 			signal,
 			canTake: (event) => actorRef ? actorRef.getSnapshot().can(event) : true
 		});
+		if (priorAttempts.length > 0) runCtx.noteDecision?.(chosen, priorAttempts);
 		actorRef?.send(chosen);
 		await Promise.resolve();
 		return chosen;
@@ -560,7 +597,7 @@ function rootTraceState(root) {
 	if (!state) {
 		const logic = root.logic;
 		const machineId = (logic?.config)?.id ?? logic?.id ?? "(machine)";
-		const machineVersion = logic ? require_text_logic.resolveMachineVersion(logic) : "";
+		const machineVersion = logic ? require_event_log.resolveMachineVersion(logic) : "";
 		state = {
 			runId: `run_${nextProvideRunId++}`,
 			seq: 0,
@@ -619,13 +656,13 @@ function provideBindContext(machine, executors, options) {
 		consumeModelCall: () => {},
 		recordUsage: (usage, source, self) => {
 			deliverUsageEvent({
-				type: require_usage.AGENT_USAGE_EVENT_TYPE,
+				type: require_event_log.AGENT_USAGE_EVENT_TYPE,
 				...source,
 				usage
 			}, () => self?._parent);
 		},
 		actorHolder: { actorRef: void 0 },
-		schemas: require_text_logic.getRegisteredAgentExecutionOptions(machine).schemas
+		schemas: require_event_log.getRegisteredAgentExecutionOptions(machine).schemas
 	};
 }
 /**
@@ -702,12 +739,12 @@ function bindChildMachineForProvide(childMachine, executors, options, visited) {
 */
 function resolveMachineInput(machine, input) {
 	if (input === void 0) return input;
-	const schema = require_text_logic.getRegisteredAgentExecutionOptions(machine).schemas?.input;
-	if (!require_text_logic.isStandardSchema(schema)) return input;
+	const schema = require_event_log.getRegisteredAgentExecutionOptions(machine).schemas?.input;
+	if (!require_event_log.isStandardSchema(schema)) return input;
 	try {
-		return require_text_logic.validateSchemaSync(schema, input);
+		return require_event_log.validateSchemaSync(schema, input);
 	} catch (error) {
-		throw new require_text_logic.AgentError("invalid-machine-input", `createAgentRuntime: machine input failed validation against the declared input schema: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		throw new require_event_log.AgentError("invalid-machine-input", `createAgentRuntime: machine input failed validation against the declared input schema: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
 }
 /**
@@ -726,17 +763,17 @@ function resolveMachineInput(machine, input) {
 */
 function rebindChildMachine(childMachine, runCtx, visited, ctxFor) {
 	if (visited.has(childMachine)) return childMachine;
-	const childVisited = new Set([...visited, childMachine]);
+	const childVisited = /* @__PURE__ */ new Set([...visited, childMachine]);
 	runCtx = ctxFor ? ctxFor(childMachine) : runCtx;
 	const sources = childMachine.sources.actors;
 	const wrapped = {};
 	for (const [key, logic] of Object.entries(sources)) {
 		if (require_decision.isDecisionLogic(logic)) {
-			if (!require_text_logic.executorBoundLogics.has(logic)) wrapped[key] = bindDecisionLogic(logic, runCtx);
+			if (!require_event_log.executorBoundLogics.has(logic)) wrapped[key] = bindDecisionLogic(logic, runCtx);
 			continue;
 		}
-		if (require_text_logic.isTextLogic(logic)) {
-			if (!require_text_logic.executorBoundLogics.has(logic)) wrapped[key] = bindTextLogic(logic, runCtx);
+		if (require_event_log.isTextLogic(logic)) {
+			if (!require_event_log.executorBoundLogics.has(logic)) wrapped[key] = bindTextLogic(logic, runCtx);
 			continue;
 		}
 		if (isStateMachineLogic(logic)) {
@@ -747,6 +784,15 @@ function rebindChildMachine(childMachine, runCtx, visited, ctxFor) {
 	}
 	return Object.keys(wrapped).length > 0 ? childMachine.provide({ actors: wrapped }) : childMachine;
 }
+const timerId = (timer) => JSON.stringify(timer);
+function toTimerInput(event) {
+	const id = event.id;
+	if (event.type !== "xstate.timer" || typeof id !== "string" || !id.startsWith("{")) return event;
+	return {
+		type: "xstate.timer",
+		...JSON.parse(id)
+	};
+}
 /**
 * The blocking host: opens the run, delivers `event` if given, then applies
 * every event that arrives until the run is quiescent, and returns the
@@ -757,7 +803,7 @@ 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);
+		[state, effects] = runtime.transition(state, init.event, init.attempts !== void 0 ? { attempts: init.attempts } : void 0);
 		await runtime.execute(effects);
 	}
 	for (let event; event = await runtime.nextEvent();) {
@@ -767,6 +813,52 @@ async function runToQuiescence(runtime, init = {}) {
 	return runtime.finish();
 }
 /**
+* Runs `machine` to quiescence in one call: {@link createAgentRuntime} over
+* `options`, then {@link runToQuiescence} with the same object as its init.
+* One options object carries both halves (`executors`, `store`, callbacks,
+* and `input` | `snapshot` + `event`), and the result is the same
+* {@link AgentRunResult}. With {@link AgentRunOptions.onIdle}, idle states are
+* answered in place and the call returns only `done` or `error`.
+*
+* Reach for {@link createAgentRuntime} directly when the host needs the loop
+* itself: a non-blocking durable host, events pushed mid-run, or a custom stop
+* or checkpoint policy.
+*
+* @example
+* ```ts
+* const result = await runAgent(machine, { input: { topic }, executors });
+* if (result.status === "done") console.log(result.output);
+* ```
+*
+* @example
+* ```ts
+* // Resume a run a request handler left idle.
+* const result = await runAgent(machine, { executors, snapshot, event });
+* ```
+*/
+async function runAgent(machine, options = {}) {
+	const { onIdle, ...rest } = options;
+	let result = await runToQuiescence(createAgentRuntime(machine, rest), rest);
+	if (!onIdle) return result;
+	const maxModelCalls = rest.maxModelCalls ?? 100;
+	let modelCalls = result.usage.modelCalls;
+	const { input: _input, events: _events, attempts: _attempts, ...resumeOptions } = rest;
+	while (result.status === "idle" && result.ignored === void 0) {
+		const event = await onIdle(result.snapshot);
+		result = await runToQuiescence(createAgentRuntime(machine, {
+			...resumeOptions,
+			maxModelCalls: maxModelCalls - modelCalls
+		}), {
+			...resumeOptions,
+			...rest.store === void 0 ? { events: result.events } : {},
+			snapshot: result.persist(),
+			event
+		});
+		modelCalls += result.usage.modelCalls;
+	}
+	return result;
+}
+/**
 * 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,
@@ -778,7 +870,7 @@ function assertThreadMatchesEvents(threadId, stored, events) {
 		const givenEntry = events[index];
 		const storedHash = storedEntry.verification?.stateHash;
 		const givenHash = givenEntry.verification?.stateHash;
-		if (!(storedEntry.id === givenEntry.id && storedEntry.index === givenEntry.index && require_event_log_store.canonicalEventJson(storedEntry.event) === require_event_log_store.canonicalEventJson(givenEntry.event) && (storedHash === void 0 || givenHash === void 0 || storedHash === givenHash))) throw new require_text_logic.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.`);
+		if (!(storedEntry.id === givenEntry.id && storedEntry.index === givenEntry.index && require_event_log.canonicalEventJson(storedEntry.event) === require_event_log.canonicalEventJson(givenEntry.event) && (storedHash === void 0 || givenHash === void 0 || storedHash === givenHash))) throw new require_event_log.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");
@@ -805,7 +897,7 @@ const QUIESCENT = Symbol("quiescent");
 * while (r.status === 'idle') {
 *   const event = await promptUser(getAcceptedEvents(r.snapshot));
 *   r = await runToQuiescence(createAgentRuntime(machine, { executors }), {
-*     snapshot: r.snapshot,
+*     snapshot: r.persist(),
 *     event,
 *   });
 * }
@@ -825,7 +917,9 @@ function createAgentRuntime(machine, options = {}) {
 	const runId = `run_${nextRunAgentTraceId++}`;
 	let traceSeq = 0;
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
-	const machineVersion = require_text_logic.resolveMachineVersion(machine);
+	const machineVersion = require_event_log.resolveMachineVersion(machine);
+	if (options.metadata !== void 0) require_event_log.assertJsonSerializable(options.metadata, "metadata");
+	const initMetadata = options.metadata === void 0 ? void 0 : structuredClone(options.metadata);
 	const onTrace = createTraceDispatch({
 		onTrace: (payload) => {
 			options.onTrace?.({
@@ -853,7 +947,7 @@ function createAgentRuntime(machine, options = {}) {
 	const logEntries = [];
 	const store = options.store;
 	const threadId = options.threadId;
-	if (store !== void 0 && (threadId === void 0 || threadId === "")) throw new require_text_logic.AgentError("missing-thread-id", "createAgentRuntime: `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 require_event_log.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;
@@ -904,24 +998,32 @@ function createAgentRuntime(machine, options = {}) {
 	let current;
 	let logMachine = machine;
 	let loggingEnabled = true;
-	const appendLogEntry = (event, snapshot) => {
+	const attemptsByEvent = /* @__PURE__ */ new WeakMap();
+	let logFold;
+	const appendLogEntry = (event, attempts) => {
 		if (!loggingEnabled) return;
-		const entry = require_event_log_store.createReplayEntry(logMachine, logEntries, event, {
+		const entry = require_event_log.createReplayEntry(logMachine, logEntries, event, {
 			machineVersion,
-			verification: verificationEnabled,
-			...verificationEnabled && snapshot !== void 0 ? { snapshot } : {}
+			verification: false,
+			...attempts !== void 0 ? { attempts } : {}
 		});
+		if (verificationEnabled && logFold !== null) try {
+			logFold ??= require_event_log.foldLog(logMachine, logEntries, {
+				machineVersion,
+				verify: false
+			});
+			entry.verification = { stateHash: require_event_log.getSnapshotStateHash(logFold.apply(entry)) };
+		} catch {
+			logFold = null;
+		}
 		logEntries.push(entry);
 		journalEntry(entry);
 		options.onEvent?.(entry);
 		return entry;
 	};
-	const usageEntrySnapshot = () => {
-		if (current && (current.status !== "active" || !declaresUsageTransition(current))) return current;
-	};
 	const recordUsage = (usage, source = {}) => {
 		const event = {
-			type: require_usage.AGENT_USAGE_EVENT_TYPE,
+			type: require_event_log.AGENT_USAGE_EVENT_TYPE,
 			...source,
 			usage
 		};
@@ -935,17 +1037,17 @@ function createAgentRuntime(machine, options = {}) {
 			});
 			return true;
 		});
-		if (!delivered) appendLogEntry(event, usageEntrySnapshot());
+		if (!delivered) appendLogEntry(event);
 	};
 	const runUsage = () => ({
-		...require_event_log_store.getUsageFromEvents(logEntries.slice(resumedLogLength)),
+		...require_event_log.getUsageFromEvents(logEntries.slice(resumedLogLength)),
 		modelCalls: modelCallCount
 	});
 	const warnNonSerializableContext = (snapshot) => {
 		if (warnedNonSerializable || process.env.NODE_ENV === "production") return;
 		let offending = [];
 		try {
-			offending = require_text_logic.findNonSerializableContextPaths(snapshot.context);
+			offending = require_event_log.findNonSerializableContextPaths(snapshot.context);
 		} catch {
 			return;
 		}
@@ -976,7 +1078,15 @@ function createAgentRuntime(machine, options = {}) {
 		actorHolder,
 		awaitJournal,
 		runId,
-		schemas: require_text_logic.getRegisteredAgentExecutionOptions(machine).schemas
+		schemas: require_event_log.getRegisteredAgentExecutionOptions(machine).schemas,
+		noteDecision: (event, attempts) => {
+			try {
+				require_event_log.assertJsonSerializable(attempts, "attempts");
+			} catch {
+				return;
+			}
+			attemptsByEvent.set(event, attempts);
+		}
 	};
 	const wrappedSources = {};
 	for (const [key, logic] of Object.entries(effectiveSources)) {
@@ -984,12 +1094,12 @@ function createAgentRuntime(machine, options = {}) {
 			wrappedSources[key] = bindDecisionLogic(logic, runCtx);
 			continue;
 		}
-		if (require_text_logic.isTextLogic(logic)) {
-			if (!require_text_logic.executorBoundLogics.has(logic)) wrappedSources[key] = bindTextLogic(logic, runCtx);
+		if (require_event_log.isTextLogic(logic)) {
+			if (!require_event_log.executorBoundLogics.has(logic)) wrappedSources[key] = bindTextLogic(logic, runCtx);
 			continue;
 		}
 		if (isStateMachineLogic(logic)) {
-			const rebound = rebindChildMachine(logic, runCtx, new Set([machine]));
+			const rebound = rebindChildMachine(logic, runCtx, /* @__PURE__ */ new Set([machine]));
 			if (rebound !== logic) wrappedSources[key] = rebound;
 			continue;
 		}
@@ -1014,7 +1124,8 @@ function createAgentRuntime(machine, options = {}) {
 	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) => {
+	const armTimer = (source, isRoot, timer, delay) => {
+		const id = timerId(timer);
 		if (isRoot && !inProcessTimers) {
 			options.timers.schedule({
 				id,
@@ -1028,7 +1139,7 @@ function createAgentRuntime(machine, options = {}) {
 			timerHandles.delete(key);
 			const timerEvent = {
 				type: "xstate.timer",
-				id
+				...timer
 			};
 			if (isRoot) enqueue(timerEvent);
 			else source?.send(timerEvent);
@@ -1113,10 +1224,11 @@ function createAgentRuntime(machine, options = {}) {
 			if (source.address === execution.rootAddress) emitFromRoot(event);
 			else source._emit?.(event);
 		},
-		scheduleTimer: (source, id, delay) => {
-			armTimer(source, source.address === execution.rootAddress, id, delay);
+		scheduleTimer: (source, timer, delay) => {
+			armTimer(source, source.address === execution.rootAddress, timer, delay);
 		},
-		cancelTimer: (source, id) => {
+		cancelTimer: (source, timer) => {
+			const id = timerId(timer);
 			const isRoot = source.address === execution.rootAddress;
 			if (isRoot && !inProcessTimers) {
 				options.timers.cancel(id);
@@ -1127,7 +1239,8 @@ function createAgentRuntime(machine, options = {}) {
 			timerHandles.delete(key);
 		},
 		cancelAllTimers: (source) => {
-			const prefix = timerKey(source.address === execution.rootAddress ? void 0 : source, "");
+			const isRoot = source.address === execution.rootAddress;
+			const prefix = timerKey(isRoot ? void 0 : source, "");
 			for (const [key, handle] of timerHandles) if (key.startsWith(prefix)) {
 				clearTimeout(handle);
 				timerHandles.delete(key);
@@ -1136,9 +1249,11 @@ function createAgentRuntime(machine, options = {}) {
 	}, inspect ? { inspect } : void 0);
 	const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
 	const commit = (snapshot, event) => {
+		const from = { value: (current ?? snapshot).value };
 		current = snapshot;
 		onTrace({
 			type: "machine.transition",
+			from,
 			snapshot,
 			event
 		});
@@ -1151,7 +1266,7 @@ function createAgentRuntime(machine, options = {}) {
 	};
 	return {
 		async start(init = {}) {
-			if (started) throw new require_text_logic.AgentError("runtime-started", "createAgentRuntime: `start` was already called.");
+			if (started) throw new require_event_log.AgentError("runtime-started", "createAgentRuntime: `start` was already called.");
 			started = true;
 			let resumeEvents = init.events;
 			if (store !== void 0) {
@@ -1180,7 +1295,7 @@ function createAgentRuntime(machine, options = {}) {
 			*/
 			const appendInitEntry = (candidates, metadata) => {
 				for (const candidate of candidates) for (const verification of verificationEnabled ? [true, false] : [false]) try {
-					const entry = require_event_log_store.initEntry(logMachine, candidate, {
+					const entry = require_event_log.initEntry(logMachine, candidate, {
 						machineVersion,
 						verification,
 						metadata
@@ -1198,10 +1313,10 @@ function createAgentRuntime(machine, options = {}) {
 				return [...restored !== void 0 ? [{ snapshot: restored }] : [], { snapshot: init.snapshot }];
 			};
 			if (resumeEvents !== void 0 && resumeEvents.length > 0) {
-				require_event_log_store.validateReplayEntries(resumeEvents);
+				require_event_log.validateReplayEntries(resumeEvents);
 				const tail = resumeEvents[resumeEvents.length - 1];
-				const inheritedExecutionId = require_event_log_store.getLogExecutionId(resumeEvents);
-				if (resumeEvents[0].machineId !== machineId) throw new require_event_log_store.AgentMachineVersionMismatchError(tail.id, tail.index, {
+				const inheritedExecutionId = require_event_log.getLogExecutionId(resumeEvents);
+				if (resumeEvents[0].machineId !== machineId) throw new require_event_log.AgentMachineVersionMismatchError(tail.id, tail.index, {
 					machineId,
 					machineVersion
 				}, {
@@ -1217,20 +1332,22 @@ function createAgentRuntime(machine, options = {}) {
 					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 = require_event_log_store.getSnapshotStateHash(require_event_log_store.replay(logMachine, resumeEvents.slice(0, cachedIndex), {
+							const atCache = require_event_log.replay(logMachine, resumeEvents.slice(0, cachedIndex), {
 								machineVersion,
 								verify: false
-							}).persistedSnapshot);
+							});
+							const expected = require_event_log.getSnapshotStateHash(atCache.persistedSnapshot);
 							const actual = hashResumeSnapshot(init.snapshot);
 							if (expected !== actual) throw new AgentSnapshotDivergedError(expected, actual, cachedIndex);
 						}
-						effectiveSnapshot = require_event_log_store.replay(logMachine, resumeEvents, {
+						logFold = require_event_log.foldLog(logMachine, resumeEvents, {
 							machineVersion,
 							verify: true
-						}).persistedSnapshot;
+						});
+						effectiveSnapshot = logFold.persistedSnapshot;
 					}
 				} else {
-					if (init.snapshot === void 0) throw new require_event_log_store.AgentMachineVersionMismatchError(tail.id, tail.index, {
+					if (init.snapshot === void 0) throw new require_event_log.AgentMachineVersionMismatchError(tail.id, tail.index, {
 						machineId,
 						machineVersion
 					}, {
@@ -1238,7 +1355,7 @@ function createAgentRuntime(machine, options = {}) {
 						machineVersion: tail.machineVersion
 					});
 					const bridgeMeta = readAgentMeta(init.snapshot);
-					if (inheritedExecutionId === void 0 || bridgeMeta?.logId !== inheritedExecutionId) throw new require_event_log_store.AgentMachineVersionMismatchError(tail.id, tail.index, {
+					if (inheritedExecutionId === void 0 || bridgeMeta?.logId !== inheritedExecutionId) throw new require_event_log.AgentMachineVersionMismatchError(tail.id, tail.index, {
 						machineId,
 						machineVersion
 					}, {
@@ -1255,16 +1372,23 @@ function createAgentRuntime(machine, options = {}) {
 						logIndex: resumeEvents.length
 					};
 					seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
+						...initMetadata,
 						...logExecutionId !== void 0 ? { executionId: logExecutionId } : {},
 						migratedFrom
 					});
 				}
 			} else if (init.snapshot !== void 0) {
 				logExecutionId = crypto.randomUUID();
-				seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), { executionId: logExecutionId });
+				seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
+					...initMetadata,
+					executionId: logExecutionId
+				});
 			} else {
 				logExecutionId = crypto.randomUUID();
-				seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], { executionId: logExecutionId });
+				seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], {
+					...initMetadata,
+					executionId: logExecutionId
+				});
 			}
 			const resumedHistory = [...logEntries];
 			const siteCallCounts = /* @__PURE__ */ new Map();
@@ -1275,7 +1399,7 @@ function createAgentRuntime(machine, options = {}) {
 				if (memoized !== void 0) return memoized;
 				const startedHere = siteCallCounts.get(siteId) ?? 0;
 				siteCallCounts.set(siteId, startedHere + 1);
-				const key = `${logExecutionId}:${siteId}#${require_event_log_store.agentCallOccurrence(resumedHistory, siteId) + startedHere}`;
+				const key = `${logExecutionId}:${siteId}#${require_event_log.agentCallOccurrence(resumedHistory, siteId) + startedHere}`;
 				if (self !== void 0) mintedCallKeys.set(self, key);
 				return key;
 			};
@@ -1287,11 +1411,13 @@ function createAgentRuntime(machine, options = {}) {
 				...effectiveSnapshot !== void 0 ? { snapshot: effectiveSnapshot } : {},
 				...resumeEvent !== void 0 ? { event: resumeEvent } : {}
 			});
-			if (options.signal) if (options.signal.aborted) stopReason = {
-				cause: "aborted",
-				error: options.signal.reason ?? /* @__PURE__ */ new Error("Aborted")
-			};
-			else options.signal.addEventListener("abort", onAbort);
+			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 = {
@@ -1323,12 +1449,15 @@ function createAgentRuntime(machine, options = {}) {
 			commit(snapshot, initEvent);
 			return [snapshot, effects];
 		},
-		transition(state, event) {
-			if (finished) throw new require_text_logic.AgentError("runtime-finished", "createAgentRuntime: the run has finished; start a new runtime to continue.");
+		transition(state, event, transitionOptions) {
+			if (finished) throw new require_event_log.AgentError("runtime-finished", "createAgentRuntime: the run has finished; start a new runtime to continue.");
 			if (stopReason !== void 0) return [state, []];
+			event = toTimerInput(event);
+			const attempts = transitionOptions?.attempts ?? attemptsByEvent.get(event);
+			if (transitionOptions?.attempts !== void 0) require_event_log.assertJsonSerializable(transitionOptions.attempts, "attempts");
 			const [next, effects] = execution.transition(state, event);
 			if (!fromMailbox.has(event) && next === state && effects.length === 0) ignoredEvent = event;
-			appendLogEntry(event, next);
+			appendLogEntry(event, attempts);
 			commit(next, event);
 			return [next, effects];
 		},
@@ -1354,7 +1483,7 @@ function createAgentRuntime(machine, options = {}) {
 			}
 		},
 		async finish() {
-			if (finished) throw new require_text_logic.AgentError("runtime-finished", "createAgentRuntime: `finish` was already called.");
+			if (finished) throw new require_event_log.AgentError("runtime-finished", "createAgentRuntime: `finish` was already called.");
 			const snapshot = current;
 			let outcome;
 			if (stopReason !== void 0) outcome = {
@@ -1460,7 +1589,8 @@ function inspectTransitions(handler) {
 * ```
 *
 * Only ROOT-actor transitions are traced (matching the runtime's
-* `machine.transition`); child-actor transitions are ignored. Attribute the
+* `machine.transition`); child-actor transitions are ignored. Each event's
+* `from.value` is the root's previous state value, tracked per root actor. Attribute the
 * event via its envelope `runId`.
 *
 * By design this path has NO `run.start`/`run.end` events: `createActor` has no
@@ -1471,13 +1601,19 @@ function inspectTransitions(handler) {
 * with `actor.on('*', ...)` if you need them.
 */
 function traceTransitions(onTrace) {
+	const lastValue = /* @__PURE__ */ new WeakMap();
 	return (inspectionEvent) => {
 		if (inspectionEvent.type !== "@xstate.transition") return;
 		const actorRef = inspectionEvent.actorRef;
 		if (actorRef?._parent) return;
-		onTrace(stampRootTrace(actorRef, {
+		const root = actorRef;
+		const snapshot = inspectionEvent.snapshot;
+		const from = { value: lastValue.get(root) ?? snapshot.value };
+		lastValue.set(root, snapshot.value);
+		onTrace(stampRootTrace(root, {
 			type: "machine.transition",
-			snapshot: inspectionEvent.snapshot,
+			from,
+			snapshot,
 			event: inspectionEvent.event
 		}));
 	};
@@ -1565,6 +1701,12 @@ Object.defineProperty(exports, "isStateMachineLogic", {
 		return isStateMachineLogic;
 	}
 });
+Object.defineProperty(exports, "runAgent", {
+	enumerable: true,
+	get: function() {
+		return runAgent;
+	}
+});
 Object.defineProperty(exports, "runToQuiescence", {
 	enumerable: true,
 	get: function() {