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

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

@@ -1,7 +1,6 @@
-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-2pAFiWuc.mjs";
+import { B as responseMessagesOf, C as AGENT_USAGE_EVENT_TYPE, F as normalizeGeneratorResult, J as findNonSerializableContextPaths, M as getCallFinishReason, N as getCallUsage, P as isTextLogic, S as validateReplayEntries, U as getRegisteredAgentExecutionOptions, V as executorBoundLogics, W as isUnboundPlaceholder, _ as getUsageFromEvents, d as createReplayEntry, f as foldLog, g as getSnapshotStateHash, h as getLogExecutionId, i as AgentMachineVersionMismatchError, l as assertJsonSerializable, nt as resolveMachineVersion, ot as validateSchemaSync, s as agentCallOccurrence, st as AgentError, tt as isStandardSchema, u as canonicalEventJson, v as initEntry, x as replay } from "./event-log-DJCMHek_.mjs";
+import { d as getAcceptedEvents, l as resolveDecision, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-BHkvuImD.mjs";
+import { t as AgentEventLogConflictError } from "./event-log-store-DsP6GCRh.mjs";
 import { createAsyncLogic, getNextTransitions, isMachineSnapshot, stopActor } from "xstate";
 import { createDurable } from "xstate/durable";
 //#region src/run-agent.ts
@@ -14,6 +13,9 @@ import { createDurable } from "xstate/durable";
 * alone, or the matching snapshot.
 */
 var AgentSnapshotDivergedError = class extends 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;
@@ -214,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) {
@@ -263,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
@@ -508,17 +510,53 @@ function bindDecisionLogic(logic, runCtx) {
 			eventTypes: declaredEventTypes
 		}) : [];
 		const lowered = logic.request(input);
-		const chosen = await resolveDecision({
+		const request = {
 			...lowered,
 			id,
 			name: lowered.name ?? id,
 			input,
 			events
-		}, { decide: createCountingDecide(runCtx, self) }, {
-			maxRetries: logic.maxRetries,
+		};
+		const withheld = [];
+		const options = 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 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 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;
@@ -725,7 +763,7 @@ 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 = {};
@@ -746,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
@@ -756,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();) {
@@ -766,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,
@@ -804,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,6 +918,8 @@ function createAgentRuntime(machine, options = {}) {
 	let traceSeq = 0;
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
 	const machineVersion = resolveMachineVersion(machine);
+	if (options.metadata !== void 0) assertJsonSerializable(options.metadata, "metadata");
+	const initMetadata = options.metadata === void 0 ? void 0 : structuredClone(options.metadata);
 	const onTrace = createTraceDispatch({
 		onTrace: (payload) => {
 			options.onTrace?.({
@@ -903,21 +998,29 @@ 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 = createReplayEntry(logMachine, logEntries, event, {
 			machineVersion,
-			verification: verificationEnabled,
-			...verificationEnabled && snapshot !== void 0 ? { snapshot } : {}
+			verification: false,
+			...attempts !== void 0 ? { attempts } : {}
 		});
+		if (verificationEnabled && logFold !== null) try {
+			logFold ??= foldLog(logMachine, logEntries, {
+				machineVersion,
+				verify: false
+			});
+			entry.verification = { stateHash: 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: AGENT_USAGE_EVENT_TYPE,
@@ -934,7 +1037,7 @@ function createAgentRuntime(machine, options = {}) {
 			});
 			return true;
 		});
-		if (!delivered) appendLogEntry(event, usageEntrySnapshot());
+		if (!delivered) appendLogEntry(event);
 	};
 	const runUsage = () => ({
 		...getUsageFromEvents(logEntries.slice(resumedLogLength)),
@@ -975,7 +1078,15 @@ function createAgentRuntime(machine, options = {}) {
 		actorHolder,
 		awaitJournal,
 		runId,
-		schemas: getRegisteredAgentExecutionOptions(machine).schemas
+		schemas: getRegisteredAgentExecutionOptions(machine).schemas,
+		noteDecision: (event, attempts) => {
+			try {
+				assertJsonSerializable(attempts, "attempts");
+			} catch {
+				return;
+			}
+			attemptsByEvent.set(event, attempts);
+		}
 	};
 	const wrappedSources = {};
 	for (const [key, logic] of Object.entries(effectiveSources)) {
@@ -988,7 +1099,7 @@ function createAgentRuntime(machine, options = {}) {
 			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;
 		}
@@ -1013,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,
@@ -1027,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);
@@ -1112,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);
@@ -1126,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);
@@ -1135,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
 		});
@@ -1216,17 +1332,19 @@ 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 = getSnapshotStateHash(replay(logMachine, resumeEvents.slice(0, cachedIndex), {
+							const atCache = replay(logMachine, resumeEvents.slice(0, cachedIndex), {
 								machineVersion,
 								verify: false
-							}).persistedSnapshot);
+							});
+							const expected = getSnapshotStateHash(atCache.persistedSnapshot);
 							const actual = hashResumeSnapshot(init.snapshot);
 							if (expected !== actual) throw new AgentSnapshotDivergedError(expected, actual, cachedIndex);
 						}
-						effectiveSnapshot = replay(logMachine, resumeEvents, {
+						logFold = foldLog(logMachine, resumeEvents, {
 							machineVersion,
 							verify: true
-						}).persistedSnapshot;
+						});
+						effectiveSnapshot = logFold.persistedSnapshot;
 					}
 				} else {
 					if (init.snapshot === void 0) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
@@ -1254,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();
@@ -1286,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 = {
@@ -1322,12 +1449,15 @@ function createAgentRuntime(machine, options = {}) {
 			commit(snapshot, initEvent);
 			return [snapshot, effects];
 		},
-		transition(state, event) {
+		transition(state, event, transitionOptions) {
 			if (finished) throw new 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) 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];
 		},
@@ -1459,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
@@ -1470,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
 		}));
 	};
@@ -1498,4 +1635,4 @@ function isAgentIdle(snapshot) {
 	}) || getAcceptedEvents(snapshot).length > 0;
 }
 //#endregion
-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 };
+export { bindDecisionForProvide as a, getConfiguredInvokeSrcs as c, isStateMachineLogic as d, runAgent as f, traceTransitions as h, bindChildMachineForProvide as i, inspectTransitions as l, serializeTraceEvent as m, AgentMaxModelCallsExceededError as n, bindTextForProvide as o, runToQuiescence as p, AgentSnapshotDivergedError as r, createAgentRuntime as s, AGENT_TRACE_SCHEMA_VERSION as t, isAgentIdle as u };

package/dist/{run-agent-COXXc0RW.d.mts → run-agent-CAVt5R-r.d.mts}

@@ -1,23 +1,9 @@
-import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-BgNbNKnJ.mjs";
-import { K as AgentRequestSource, M as AgentDecisionRequest, U as AgentEventDescriptor, Z as AgentError, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-D-czVPYp.mjs";
-import { c as AgentLogEntry, n as AgentEventLogStore } from "./event-log-store-BIPOz-di.mjs";
-import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom } from "xstate";
+import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.mjs";
+import { I as DecisionAttempt, N as AgentDecisionRequest, Q as AgentError, W as AgentEventDescriptor, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, q as AgentRequestSource, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BRYOPWvY.mjs";
+import { n as AgentUsageEvent } from "./usage-BkM3z02Y.mjs";
+import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-CIIJohjj.mjs";
+import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
 import { DurableExecution } from "xstate/durable";
-
-//#region src/usage.d.ts
-/** Reserved event delivered after a model call reports token usage. */
-declare const AGENT_USAGE_EVENT_TYPE: "@agent.usage";
-/** Machine-owned usage signal. Handle it with an ordinary XState transition. */
-interface AgentUsageEvent extends EventObject {
-  type: typeof AGENT_USAGE_EVENT_TYPE;
-  usage: AgentCallUsage;
-  kind?: "text" | "decision";
-  id?: string;
-  src?: string;
-  model?: string;
-  name?: string;
-}
-//#endregion
 //#region src/steps.d.ts
 /**
  * A pending text request surfaced by step discovery ({@link getAgentRequests}
@@ -81,11 +67,13 @@ type AgentTransitionHandler<TMachine extends AnyStateMachine> = (snapshot: Snaps
  */
 declare const AGENT_TRACE_SCHEMA_VERSION = 1;
 type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
-  /** The {@link AGENT_TRACE_SCHEMA_VERSION} the event was produced with. */schemaVersion: typeof AGENT_TRACE_SCHEMA_VERSION;
+  /** The {@link AGENT_TRACE_SCHEMA_VERSION} the event was produced with. */
+  schemaVersion: typeof AGENT_TRACE_SCHEMA_VERSION;
   runId: string;
   seq: number;
   timestamp: string;
-  machineId: string; /** The machine's own `version`, else its structural hash. */
+  machineId: string;
+  /** The machine's own `version`, else its structural hash. */
   machineVersion: string;
 } & ({
   type: "run.start";
@@ -122,6 +110,15 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   chunk: string;
 } | {
   type: "machine.transition";
+  /**
+   * Where the event arrived: the state value before this transition. The
+   * first transition of a stream (the init event, or the restore on
+   * resume) has no earlier state, so its `from.value` is its own
+   * `snapshot.value`. An object so more of the prior snapshot can join it.
+   */
+  from: {
+    value: StateValue;
+  };
   snapshot: SnapshotFrom<TMachine>;
   event: EventFromLogic<TMachine>;
 } | {
@@ -132,7 +129,8 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
    * tokens still fold into {@link AgentRunResult.usage}; only the machine
    * event is dropped. */
   type: "usage.dropped";
-  event: AgentUsageEvent; /** `'settled'`: the call settled after the run's cycle had resolved. */
+  event: AgentUsageEvent;
+  /** `'settled'`: the call settled after the run's cycle had resolved. */
   reason: "settled";
 } | ({
   type: "run.end";
@@ -159,7 +157,7 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
  */
 type TraceVerbatimKey = (typeof TRACE_ENVELOPE_KEYS)[number] | "reason";
 /** One trace variant's JSON projection. Homomorphic, so `?` modifiers survive. @internal */
-type JsonProjectedTraceVariant<TEvent> = { [K in keyof TEvent]: K extends TraceVerbatimKey ? TEvent[K] : JsonValue };
+type JsonProjectedTraceVariant<TEvent> = { [K in keyof TEvent]: K extends TraceVerbatimKey ? TEvent[K] : JsonValue; };
 /**
  * `raw` is written only when `includeRaw` was set, so it is optional on the
  * JSON side even though the live trace always carries it. @internal
@@ -178,7 +176,7 @@ type WithOptionalRaw<T> = "raw" extends keyof T ? Omit<T, "raw"> & {
  * miss the JSON side. `src/serialize-trace-event.test.ts` pins the result to
  * the shape this type had when it was hand-maintained.
  */
-type JsonSerializableTraceEvent = AgentTraceEvent extends infer TEvent ? TEvent extends unknown ? WithOptionalRaw<JsonProjectedTraceVariant<TEvent>> : never : never;
+type JsonSerializableTraceEvent = AgentTraceEvent extends (infer TEvent) ? TEvent extends unknown ? WithOptionalRaw<JsonProjectedTraceVariant<TEvent>> : never : never;
 declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "timestamp", "machineId", "machineVersion", "type", "status", "cause", "reasoning", "finishReason", "chunk"];
 /**
  * Projects an {@link AgentTraceEvent} into a guaranteed JSON-safe envelope —
@@ -253,6 +251,14 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
    * the same state. Set `false` for a smaller, unverifiable log.
    */
   verification?: boolean;
+  /**
+   * Host-owned JSON stored on the log's `@agent.init` entry when this run
+   * starts a log: what produced the run, such as a policy version, the model
+   * ids, or the scenario. A resume keeps the stamp of the run that started
+   * the log; a version bridge, which opens a new log segment, takes this
+   * run's. `executionId` and `migratedFrom` are reserved and cannot be set here.
+   */
+  metadata?: Record<string, JsonValue$1>;
   /** Actor source implementations, merged onto the machine before binding — sugar for `machine.provide({ actors })` ahead of the run. */
   actors?: Record<string, AnyActorLogic>;
   /**
@@ -292,7 +298,7 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
    */
   on?: { [TType in EmittedFrom<TMachine>["type"] | "*"]?: (emitted: EmittedFrom<TMachine> & (TType extends "*" ? unknown : {
     type: TType;
-  })) => void };
+  })) => void; };
   /**
    * Raw xstate inspection passthrough: fires for every inspection event in
    * the whole actor system — root machine, invoked child machines, spawned
@@ -549,8 +555,15 @@ interface AgentRunStart<TMachine extends AnyStateMachine> {
 interface AgentRuntime<TMachine extends AnyStateMachine> {
   /** Opens the run: a fresh start from `input`, a resume from `snapshot`, or recovery from a log. */
   start(init?: AgentRunStart<TMachine>): Promise<[SnapshotFrom<TMachine>, AgentEffects]>;
-  /** Applies one event: journals it, traces it, and returns the next state plus its effects. */
-  transition(state: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine> | AgentTimerEvent): [SnapshotFrom<TMachine>, AgentEffects];
+  /**
+   * Applies one event: journals it, traces it, and returns the next state plus
+   * its effects. `options.attempts` records the failed attempts of a decider
+   * the host ran itself (e.g. `decideNext`'s `attempts`) on the event's entry
+   * as `entry.attempts`. Replay ignores them; an empty list is not journaled.
+   */
+  transition(state: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine> | AgentTimerEvent, options?: {
+    attempts?: DecisionAttempt[];
+  }): [SnapshotFrom<TMachine>, AgentEffects];
   /** Starts the effects' work and returns once it is accepted, not once it finishes. */
   execute(effects: AgentEffects): Promise<void>;
   /** The next event that arrived, or `undefined` once the run is quiescent. */
@@ -570,6 +583,12 @@ interface AgentRunInit<TMachine extends AnyStateMachine> extends AgentRunStart<T
    * due is delivered the same way, as an {@link AgentTimerEvent}.
    */
   event?: EventFromLogic<TMachine> | AgentTimerEvent;
+  /**
+   * The failed attempts of the decider the host ran to choose `event` (e.g.
+   * `decideNext`'s `attempts`), journaled on `event`'s entry as
+   * `entry.attempts`. Replay ignores them.
+   */
+  attempts?: DecisionAttempt[];
 }
 /**
  * The blocking host: opens the run, delivers `event` if given, then applies
@@ -578,6 +597,51 @@ interface AgentRunInit<TMachine extends AnyStateMachine> extends AgentRunStart<T
  * own stop policy; this one is for scripts and tests.
  */
 declare function runToQuiescence<TMachine extends AnyStateMachine>(runtime: AgentRuntime<TMachine>, init?: AgentRunInit<TMachine>): Promise<AgentRunResult<TMachine>>;
+/** Everything {@link runAgent} takes: the runtime's options plus how to open the run. */
+interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntimeOptions<TMachine>, AgentRunInit<TMachine> {
+  /**
+   * Answers an idle state for a host that can block for it. When given,
+   * {@link runAgent} loops: each time the run settles `idle`, it calls
+   * `onIdle` with the idle snapshot, persists the run, and resumes from that
+   * persisted snapshot with the returned event — until the run is `done` or
+   * `error`. Each pass is a fresh {@link createAgentRuntime} over the same
+   * options, so nothing of the earlier pass is held across the wait; the log
+   * travels with the result (or the store's thread), so the final `events`
+   * replays every pass, and `maxModelCalls` bounds the whole call. An answer
+   * the idle state does not handle ends the loop: the result is `idle` with
+   * {@link AgentRunResult.ignored} set, not another call to `onIdle`.
+   *
+   * A host that cannot block for the answer (a request handler, a durable
+   * object) leaves this out, stores `result.persist()`, and calls
+   * {@link runAgent} again later with `{ snapshot, event }`.
+   */
+  onIdle?: (snapshot: SnapshotFrom<TMachine>) => Promise<EventFromLogic<TMachine>>;
+}
+/**
+ * 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 });
+ * ```
+ */
+declare function runAgent<TMachine extends AnyStateMachine>(machine: TMachine, options?: AgentRunOptions<TMachine>): Promise<AgentRunResult<TMachine>>;
 /**
  * Creates the helpers for one run of `machine`: executors bound to its
  * requests, the write-ahead log, traces, the budget, and a mailbox over
@@ -601,7 +665,7 @@ declare function runToQuiescence<TMachine extends AnyStateMachine>(runtime: Agen
  * while (r.status === 'idle') {
  *   const event = await promptUser(getAcceptedEvents(r.snapshot));
  *   r = await runToQuiescence(createAgentRuntime(machine, { executors }), {
- *     snapshot: r.snapshot,
+ *     snapshot: r.persist(),
  *     event,
  *   });
  * }
@@ -647,7 +711,8 @@ declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, acto
  * ```
  *
  * 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
@@ -669,4 +734,4 @@ declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMac
  */
 declare function isAgentIdle(snapshot: AnyMachineSnapshot): boolean;
 //#endregion
-export { serializeTraceEvent as C, AGENT_USAGE_EVENT_TYPE as D, AgentStepRequest as E, AgentUsageEvent as O, runToQuiescence as S, AgentRequest as T, InspectedActorRef as _, AgentRunErrorCause as a, inspectTransitions as b, AgentRunResult as c, AgentRuntimeOptions as d, AgentSnapshotDivergedError as f, AgentTransitionHandler as g, AgentTraceEvent as h, AgentMaxModelCallsExceededError as i, AgentRunStart as l, AgentTimerScheduler as m, AgentEffects as n, AgentRunInit as o, AgentTimerEvent as p, AgentInputFrom as r, AgentRunMeta as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRuntime as u, JsonSerializableTraceEvent as v, traceTransitions as w, isAgentIdle as x, createAgentRuntime as y };
+export { runAgent as C, AgentRequest as D, traceTransitions as E, AgentStepRequest as O, isAgentIdle as S, serializeTraceEvent as T, AgentTransitionHandler as _, AgentRunErrorCause as a, createAgentRuntime as b, AgentRunOptions as c, AgentRuntime as d, AgentRuntimeOptions as f, AgentTraceEvent as g, AgentTimerScheduler as h, AgentMaxModelCallsExceededError as i, AgentRunResult as l, AgentTimerEvent as m, AgentEffects as n, AgentRunInit as o, AgentSnapshotDivergedError as p, AgentInputFrom as r, AgentRunMeta as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRunStart as u, InspectedActorRef as v, runToQuiescence as w, inspectTransitions as x, JsonSerializableTraceEvent as y };