@statelyai/agent 2.0.0-alpha.22 → 2.0.0-alpha.24

package/dist/index.mjs

@@ -1,194 +1,1368 @@
-import { t as AgentError } from "./errors-CeSXQx0v.mjs";
-import { _ as resolveAgentStep, a as AGENT_USAGE_EVENT_TYPE, b as messagesSchema, c as createReplayEntry, d as initEntry, f as replay, g as initialAgentStep, h as getInvokeEffectMetadata, i as AGENT_INIT_EVENT_TYPE, l as diffEventLogs, m as executeAgentRequest, n as getAgentSchemas, o as AgentReplayDivergenceError, p as validateReplayEntries, r as setupAgent, s as AgentReplayMachineMismatchError, t as createAgentSchemas, u as getAgentEffects, v as transitionAgentStep, y as appendMessages } from "./setup-agent-nSFYrNTP.mjs";
-import { A as getMachineIdlePredicate, B as getAgentMessages, C as normalizeGeneratorResult, E as parseStructuredEnvelope, G as isStandardSchema, H as getJsonSchemaSync, J as toolMessage, K as resolveMachineVersion, L as assistantMessage, M as getRegisteredAgentExecutionOptions, N as isUnboundPlaceholder, S as isTextLogic, T as parseOutput, U as getMachineStructuralHash, V as getJsonSchema, W as getStateMeta, X as validateSchemaSync, Y as userMessage, a as renderDecisionAttempts, b as getAgentOutputMode, c as parseAgentEvent, f as INTERPRET_SOURCE, g as buildEnvelopeSchema, h as bindRequestExecutor, i as isDecisionLogic, j as getMachineStaticTransitionTargets, k as executorBoundLogics, l as AGENT_USAGE_TOKEN_FIELDS, o as resolveDecision, q as systemMessage, r as createDecisionLogic, s as getAcceptedEvents, t as AgentDecisionExhaustedError, v as createTextLogic, w as parseModelRef, x as getCallUsage, z as findNonSerializableContextPaths } from "./decision-DxSTqzgZ.mjs";
-import { a as assertJsonSerializable, i as assertAgentLogEntry, n as AgentEventLogConflictError, o as createInMemoryEventLogStore, r as NonSerializableAgentEventError, s as assertEventLogStoreConformance, t as AGENT_EVENT_SCHEMA_VERSION } from "./event-log-store-DmIDosD6.mjs";
-import { createActor, createAsyncLogic, deliverEvent, getNextTransitions, isMachineSnapshot } from "xstate";
-import { createDurable } from "xstate/durable";
-//#region src/internal/state-request-pass.ts
-async function runTextPhase(stateRequest, baseMessages, deps) {
-	const { model, system } = stateRequest;
-	const id = stateRequest.id ?? deps.nextRequestId();
-	const promptMessage = userMessage(stateRequest.prompt);
-	if (stateRequest.kind === "decision") return {
-		stateRequest,
-		id,
-		output: void 0,
-		appended: [promptMessage]
+import { $ as userMessage, B as assistantMessage, C as getCallFinishReason, D as parseModelRef, E as normalizeGeneratorResult, F as getRegisteredAgentExecutionOptions, G as getMachineStructuralHash, H as findNonSerializableContextPaths, I as isUnboundPlaceholder, J as getStatePath, K as getMessageText, M as executorBoundLogics, N as getAgentExecutionOptions, O as parseOutput, P as getMachineIdlePredicate, Q as toolMessage, S as getAgentOutputMode, T as isTextLogic, U as getJsonSchema, V as djb2Hex, W as getJsonSchemaSync, X as resolveMachineVersion, Y as isStandardSchema, Z as systemMessage, _ as bindRequestExecutor, a as isDecisionLogic, at as messagesSchema, b as createTextLogic, c as AgentInvalidEventPayloadError, d as isRecord, et as validateSchemaSync, f as AGENT_USAGE_TOKEN_FIELDS, i as createDecisionRequest, it as isAgentMessages, j as DEFAULT_AGENT_EXECUTORS, k as parseStructuredEnvelope, l as getAcceptedEvents, o as renderDecisionAttempts, ot as AgentError, q as getStateMeta, r as createDecisionLogic, rt as appendMessages, s as resolveDecision, st as AgentTruncatedError, t as AgentDecisionExhaustedError, tt as AGENT_MESSAGES_EVENT_TYPE, u as parseAgentEvent, v as buildEnvelopeSchema, w as getCallUsage, x as executeAgentTextRequest } from "./decision-BBZ2jMO1.mjs";
+import { i as AGENT_USAGE_EVENT_TYPE, n as getAgentSchemas, r as setupAgent, t as createAgentSchemas } from "./setup-agent-CeO2fARv.mjs";
+import { createActor, createAsyncLogic, getNextTransitions, initialTransition, isMachineSnapshot, transition } from "xstate";
+//#region src/interaction.ts
+function issue(message, path) {
+	return {
+		message,
+		path
+	};
+}
+function validateEventMeta(value, path) {
+	if (typeof value === "string") return [];
+	if (!value || typeof value !== "object" || Array.isArray(value)) return [issue("Expected a label string or an interaction event descriptor", path)];
+	const descriptor = value;
+	const issues = [];
+	if (descriptor["label"] !== void 0 && typeof descriptor["label"] !== "string") issues.push(issue("Expected a string", [...path, "label"]));
+	if (descriptor["style"] !== void 0 && typeof descriptor["style"] !== "string") issues.push(issue("Expected a string", [...path, "style"]));
+	const event = descriptor["event"];
+	if (event !== void 0 && (!event || typeof event !== "object" || Array.isArray(event))) issues.push(issue("Expected an object of fixed event fields", [...path, "event"]));
+	return issues;
+}
+/**
+* A {@link StandardSchemaV1} for the state metadata {@link getInteraction}
+* reads: an object whose optional `interaction` declares a `label` (a string
+* with `{context.path}` interpolation, or a function of the context), an
+* `events` map of choices, and a `textEvent` for free-text answers. Pass it
+* straight to `createAgentSchemas({ meta: interactionMetaSchema })` instead of
+* restating the shape per machine.
+*/
+const interactionMetaSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		if (!value || typeof value !== "object" || Array.isArray(value)) return { issues: [{ message: "Expected a state meta object" }] };
+		const interaction = value["interaction"];
+		if (interaction === void 0) return { value };
+		if (!interaction || typeof interaction !== "object" || Array.isArray(interaction)) return { issues: [issue("Expected an interaction descriptor object", ["interaction"])] };
+		const descriptor = interaction;
+		const issues = [];
+		const label = descriptor["label"];
+		if (label !== void 0 && typeof label !== "string" && typeof label !== "function") issues.push(issue("Expected a string or a (context) => string", ["interaction", "label"]));
+		const events = descriptor["events"];
+		if (events !== void 0) if (!events || typeof events !== "object" || Array.isArray(events)) issues.push(issue("Expected an object keyed by event type", ["interaction", "events"]));
+		else for (const [type, config] of Object.entries(events)) issues.push(...validateEventMeta(config, [
+			"interaction",
+			"events",
+			type
+		]));
+		if (descriptor["textEvent"] !== void 0 && typeof descriptor["textEvent"] !== "string") issues.push(issue("Expected a string", ["interaction", "textEvent"]));
+		return issues.length > 0 ? { issues } : { value };
+	}
+} };
+function readPath(value, path) {
+	return path.split(".").reduce((current, key) => {
+		if (!current || typeof current !== "object") return void 0;
+		return current[key];
+	}, value);
+}
+function interpolate(label, context, preserveWhitespace) {
+	const interpolated = label.replace(/\{([^{}]+)\}/g, (_, path) => {
+		const value = readPath(context, path.trim());
+		return value === void 0 || value === null ? "" : String(value);
+	});
+	return preserveWhitespace ? interpolated : interpolated.replace(/\s+/g, " ").trim();
+}
+/** Reads the active state's interaction metadata and filters it through the
+* events XState currently accepts. Returns `undefined` when none is declared. */
+function getInteraction(snapshot, options = {}) {
+	const interaction = getStateMeta(snapshot).interaction;
+	if (!interaction) return void 0;
+	const preserveWhitespace = options.preserveWhitespace ?? false;
+	const schemas = getAgentExecutionOptions(snapshot.machine)?.schemas;
+	const accepted = new Set(getAcceptedEvents(snapshot).map((event) => event.type));
+	const label = typeof interaction.label === "function" ? interaction.label({ context: snapshot.context }) : interaction.label ?? "";
+	const events = Object.entries(interaction.events ?? {}).filter(([type]) => accepted.has(type)).map(([type, config]) => {
+		return [type, typeof config === "string" ? { label: config } : config];
+	}).filter(([type, descriptor]) => {
+		try {
+			const complete = parseAgentEvent(snapshot, {
+				...descriptor.event,
+				type
+			}, { schemas });
+			return snapshot.can(complete);
+		} catch {
+			return true;
+		}
+	}).map(([type, descriptor]) => {
+		return {
+			type,
+			label: interpolate(descriptor.label ?? type, snapshot.context, preserveWhitespace),
+			...descriptor.style ? { style: descriptor.style } : {},
+			...descriptor.event ? { event: descriptor.event } : {}
+		};
+	});
+	return {
+		label: interpolate(label, snapshot.context, preserveWhitespace),
+		events,
+		...interaction.textEvent && accepted.has(interaction.textEvent) ? { textEvent: interaction.textEvent } : {}
+	};
+}
+/** Converts a rendered interaction choice back into a schema-validated machine
+* event. Fixed fields declared in metadata are merged before user fields. */
+function eventFromInteraction(snapshot, choice) {
+	const interaction = getInteraction(snapshot);
+	if (!interaction) throw new AgentInvalidEventPayloadError("(interaction)", "this state renders no interaction, so there is no choice to convert.");
+	let event;
+	if ("text" in choice) {
+		if (!interaction.textEvent) throw new AgentInvalidEventPayloadError("(text)", `this interaction takes no free text. Choices: ${interaction.events.map(({ type }) => type).join(", ") || "(none)"}.`);
+		event = {
+			type: interaction.textEvent,
+			text: choice.text
+		};
+	} else {
+		const descriptor = interaction.events.find(({ type }) => type === choice.type);
+		if (!descriptor) throw new AgentInvalidEventPayloadError(choice.type, `this interaction does not offer that choice. Choices: ${interaction.events.map(({ type }) => type).join(", ") || "(none)"}.`);
+		event = {
+			...choice,
+			...descriptor.event,
+			type: choice.type
+		};
+	}
+	return parseAgentEvent(snapshot, event);
+}
+//#endregion
+//#region src/steps.ts
+/**
+* The step envelope: an INTERNAL, per-model-call-checkpoint view of an agent
+* machine (`AgentStep` = snapshot + actions + discovered requests + done). It
+* once backed a public step API; the public step path is now the thin
+* effect/replay loop in `./effects.ts` (re-exported from `@statelyai/agent`).
+* These helpers survive as internals that `runAgent`, `verify.ts`, and the
+* effect path build on — the only symbol still on the public surface is
+* {@link executeAgentRequest} (the `text`-effect resolver).
+* @module
+*/
+/** @internal Normalizes current and legacy XState invoke effect shapes. */
+function getInvokeEffectMetadata(action) {
+	if (action.type === "@xstate.spawn") return action;
+	if (action.type === "xstate.spawnChild") {
+		const params = action.params;
+		return params ? {
+			...params,
+			logic: action.logic
+		} : void 0;
+	}
+	if (action.type === "@xstate.start" && typeof action.src === "string") return action;
+}
+/**
+* The invokes a snapshot is still waiting on, lowered to the same spawn-effect
+* shape {@link getAgentRequests} reads. Derived from the snapshot's live
+* children rather than the last transition's actions, so a state that invokes
+* several actors at once (an `invoke: [...]` array, or parallel regions each
+* invoking) keeps reporting the siblings after the first one settles —
+* including when the settled invoke's `onDone` is targetless and starts
+* nothing new.
+*
+* Entries are ordered by invoke id, so a walker that resolves one invoke per
+* step is deterministic.
+*
+* @internal
+*/
+function getPendingInvokes(snapshot) {
+	const children = snapshot.children ?? {};
+	return Object.keys(children).sort().flatMap((id) => {
+		const child = children[id];
+		const childSnapshot = child?.getSnapshot?.();
+		if (!child || childSnapshot?.status !== "active") return [];
+		return [{
+			type: "@xstate.spawn",
+			id,
+			src: child.src,
+			input: childSnapshot.input,
+			logic: child.logic
+		}];
+	});
+}
+/**
+* Scans a set of executable actions (as returned by xstate's `transition`/
+* `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
+* lowers each into an {@link AgentStepRequest}. Pass `options.machine` to
+* pre-fill `schemas`/`actors` from the machine's registered `setupAgent`
+* options instead of passing them by hand.
+* `options.snapshot` is required to resolve a decision's candidate events
+* (intersecting declared `allowedEvents` with what's currently legal) — omit
+* it and decision requests report an empty `events` list.
+*
+* @internal
+*/
+function getAgentRequests(actions, { machine, ...options } = {}) {
+	if (machine) options = {
+		...getRegisteredAgentExecutionOptions(machine),
+		...options
+	};
+	return actions.flatMap((action) => {
+		const params = getInvokeEffectMetadata(action);
+		if (!params || typeof params.src !== "string") return [];
+		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
+		const registeredLogic = isTextLogic(params.logic) || isDecisionLogic(params.logic) ? params.logic : options.actors?.[params.src];
+		if (isDecisionLogic(registeredLogic)) {
+			const decisionRequest = registeredLogic.request(params.input);
+			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
+			const events = options.snapshot ? getAcceptedEvents(options.snapshot, {
+				events: options.events,
+				schemas: options.schemas,
+				eventTypes: allowedEventTypes,
+				eventToolName: options.eventToolName
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = isTextLogic(registeredLogic) ? registeredLogic : void 0;
+		const input = textLogic ? textLogic.request(params.input) : void 0;
+		if (!input) return [];
+		return [{
+			kind: "text",
+			id: params.id,
+			src: params.src,
+			...textLogic ? { mode: textLogic.mode } : {},
+			input,
+			tools: input.tools ?? {},
+			events: []
+		}];
+	});
+}
+/**
+* Builds the canonical `xstate.done.actor` event xstate's `transition()`
+* expects to resolve a spawned invoke — including the child session identity
+* that rejects a stale completion from an earlier incarnation.
+*
+* @internal
+*/
+function doneEvent(snapshot, request, output) {
+	const id = typeof request === "string" ? request : request.id;
+	const child = snapshot.children[id];
+	return {
+		type: "xstate.done.actor",
+		actorId: id,
+		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {},
+		output
 	};
-	if (!deps.generateText) throw new Error("runAgent: a getRequests request needs a 'generateText' executor (or use kind: 'decision').");
-	const request = {
-		model,
-		...system !== void 0 ? { system } : {},
-		messages: [...baseMessages, promptMessage],
-		tools: {}
+}
+/**
+* The `xstate.error.actor` counterpart of {@link doneEvent} — the event a
+* failed invoke delivers, which `onError` transitions observe. Carries the
+* same child session identity, so xstate does not discard it as stale.
+*
+* @internal
+*/
+function errorEvent(snapshot, request, error) {
+	const id = typeof request === "string" ? request : request.id;
+	const child = snapshot.children[id];
+	return {
+		type: "xstate.error.actor",
+		actorId: id,
+		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {},
+		error
 	};
-	const agentRequest = {
+}
+/**
+* Applies a request's `output` as a done event (or, with `outcome: 'error'`,
+* its `output` as the invoke's error) via `transition(...)`, returning the raw
+* `[snapshot, actions]` tuple. Lower-level than {@link resolveAgentStep} /
+* {@link rejectAgentStep} — those helpers wrap this and also run
+* {@link getAgentRequests} to produce the next {@link AgentStep}.
+*
+* @internal
+*/
+function transitionResult(logic, snapshot, request, output, outcome = "output") {
+	const event = outcome === "error" ? errorEvent(snapshot, request, output) : doneEvent(snapshot, request, output);
+	const result = transition(logic, snapshot, event);
+	applyFinalStateOutput(logic, result[0], event);
+	return result;
+}
+/**
+* Starts a machine and returns its first {@link AgentStep} — the step-path
+* equivalent of `initialTransition` plus request discovery. Begins the
+* durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+* (via {@link executeAgentRequest} for `kind: 'text'`, or
+* {@link resolveDecision} for `kind: 'decision'`), then advance with
+* {@link resolveAgentStep} or {@link transitionAgentStep}.
+*/
+function initialAgentStep(machine, input, options) {
+	const [snapshot, actions] = initialTransition(machine, input);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies an externally-sent event (e.g. a decision's chosen event, or a
+* human's reply) and returns the next {@link AgentStep}. Accepts **either**
+* a raw snapshot **or** a prior `AgentStep` as the second argument —
+* `.snapshot` is unwrapped automatically, so callers can thread the whole
+* step object through without manually plucking the snapshot out.
+*/
+function transitionAgentStep(machine, snapshotOrStep, event, options) {
+	const [nextSnapshot, actions] = transition(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, event);
+	return createAgentStep(machine, nextSnapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies a resolved text request's output (a `kind: 'text'`
+* {@link AgentRequest} — not a decision) as a done event and returns the
+* next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+* (which returns a {@link ChosenEvent}) and apply it with
+* {@link transitionAgentStep} instead — a decision has no output value of
+* its own to feed here.
+*/
+function resolveAgentStep(machine, step, request, output, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, output);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Rejects a pending invoke — the failure counterpart of
+* {@link resolveAgentStep}. Delivers `error` as the invoke's
+* `xstate.error.actor` event, so the machine takes that invoke's `onError`
+* transition and returns the next {@link AgentStep}. With no `onError` in
+* scope the returned step's snapshot has `status: 'error'`, exactly as a live
+* run's failed invoke does.
+*
+* A durable host replays a failed call with this: the log says the call
+* failed, so the replay rejects the invoke instead of resolving it. Scripted
+* playthroughs use it too — see `simulateAgent`'s `script.errors`.
+*
+* `error` can be any value. An `Error` instance is the usual one, but a plain
+* object (`{ code: 'truncated' }`) reaches the `onError` transition as
+* `event.error` untouched, so a machine that branches on a failure code is
+* testable without constructing a provider's error class.
+*/
+function rejectAgentStep(machine, step, request, error, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, error, "error");
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+async function executeAgentRequest(requestOrEffect, executors) {
+	if (requestOrEffect.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors, ...) instead.");
+	const request = "requestId" in requestOrEffect ? {
 		kind: "text",
-		id,
-		src: INTERPRET_SOURCE,
-		mode: "generate",
-		input: request,
-		tools: {},
+		id: requestOrEffect.requestId,
+		src: "",
+		mode: requestOrEffect.mode,
+		input: requestOrEffect.request,
+		tools: requestOrEffect.request.tools ?? {},
 		events: []
+	} : requestOrEffect;
+	assertTextExecutor(request, executors);
+	const { output, raw } = await executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
+	return {
+		output: request.input.outputSchema ? validateSchemaSync(request.input.outputSchema, output) : output,
+		raw
 	};
-	deps.consumeModelCall();
-	deps.onTrace?.({
-		type: "request.start",
-		request: agentRequest
-	});
-	let output;
+}
+function assertTextExecutor(request, executors) {
+	const mode = request.mode ?? "generate";
+	const kind = mode === "stream" ? "streamText" : "generateText";
+	if (!(mode === "stream" ? executors.streamText : executors.generateText)) throw new Error(`this step's text request '${request.src}' needs a '${kind}' executor but none was provided.`);
+}
+function createAgentStep(machine, snapshot, actions, options) {
+	applyFinalStateOutput(machine, snapshot);
+	return {
+		snapshot,
+		actions,
+		requests: getAgentRequests(getPendingInvokes(snapshot), {
+			...options,
+			snapshot
+		}),
+		done: snapshot.status === "done"
+	};
+}
+function resolveStateValueConfig(config, value) {
+	if (typeof value === "string") return config.states?.[value];
+	if (!value || typeof value !== "object") return;
+	for (const [key, childValue] of Object.entries(value)) {
+		const childConfig = config.states?.[key];
+		if (!childConfig) continue;
+		if (childConfig.type === "final") return childConfig;
+		const nested = resolveStateValueConfig(childConfig, childValue);
+		if (nested) return nested;
+	}
+}
+function applyFinalStateOutput(logic, snapshot, event) {
+	const machineSnapshot = snapshot;
+	if (machineSnapshot.status !== "done" || machineSnapshot.output !== void 0 || !("config" in logic)) return;
+	const config = logic.config;
+	if (!config) return;
+	const output = resolveStateValueConfig(config, machineSnapshot.value)?.output;
+	if (output === void 0) return;
+	machineSnapshot.output = typeof output === "function" ? output({
+		context: machineSnapshot.context,
+		event
+	}) : output;
+}
+function isAgentStep(value) {
+	return !!value && typeof value === "object" && "snapshot" in value && "actions" in value && "requests" in value;
+}
+//#endregion
+//#region src/event-log.ts
+/**
+* The event log: an append-only journal of the EXTERNAL inputs a machine
+* consumed, and the pure fold ({@link replay}) that turns that journal back
+* into a snapshot without executing anything.
+*
+* A journaled entry is always an external input — an invoke completion
+* (`xstate.done.actor`/`xstate.error.actor` carrying its output inline), a
+* user-sent event, a timer firing, a reserved `@agent.usage` record. Never a
+* raised/internal event: replay re-derives those from the machine's own logic,
+* so journaling them would double-apply them.
+*
+* A log is self-contained: its reserved first entry ({@link initEntry}) carries
+* either the machine `input` (a fresh start) or a persisted snapshot (a
+* continuation across a machine version, or from a log-less legacy snapshot),
+* so {@link replay} needs no side channel.
+* @module
+*/
+/** The durable entry envelope version. */
+const AGENT_EVENT_SCHEMA_VERSION = 1;
+/**
+* The reserved event type of the first entry of every log. It carries the
+* machine `input` (fresh start) or a persisted `snapshot` (continuation), so a
+* log replays with no side channel. Lives in the reserved `@agent.*` namespace
+* so it can never collide with a machine's own vocabulary; it is consumed by
+* {@link replay} and never fed to `transition`.
+*/
+const AGENT_INIT_EVENT_TYPE = "@agent.init";
+/** A malformed or internally inconsistent log. */
+var AgentEventLogError = class extends AgentError {
+	constructor(message) {
+		super("invalid-event-log", message);
+		this.name = "AgentEventLogError";
+	}
+};
+/** A precise failure when an entry would not survive a JSON round-trip. */
+var NonSerializableAgentEventError = class extends AgentError {
+	path;
+	valueType;
+	constructor(path, valueType) {
+		super("non-serializable-event", `Agent event field '${path}' is not JSON-serializable (${valueType}).`);
+		this.name = "NonSerializableAgentEventError";
+		this.path = path;
+		this.valueType = valueType;
+	}
+};
+/** Replay reached a state that does not match the entry's recorded hash. */
+var AgentReplayDivergenceError = class extends AgentError {
+	constructor(eventId, index, kind, expected, actual) {
+		super("replay-diverged", kind === "missing-verification" ? `Replay entry '${eventId}' at index ${index} has no recorded verification hash.` : `Replay diverged after '${eventId}' at index ${index}: expected state hash '${expected}', got '${actual}'.`);
+		this.eventId = eventId;
+		this.index = index;
+		this.kind = kind;
+		this.expected = expected;
+		this.actual = actual;
+		this.name = "AgentReplayDivergenceError";
+	}
+};
+/**
+* An entry was recorded against a different machine (id) or a different
+* machine version than the one replaying it. An init-with-snapshot entry is
+* exempt: that entry IS the bridge from the old version to the new one.
+*/
+var AgentMachineVersionMismatchError = class extends AgentError {
+	constructor(eventId, index, expected, actual) {
+		super("machine-version-mismatch", `Event log entry '${eventId}' at index ${index} targets machine '${actual.machineId}'@'${actual.machineVersion}', expected '${expected.machineId}'@'${expected.machineVersion}'.`);
+		this.eventId = eventId;
+		this.index = index;
+		this.expected = expected;
+		this.actual = actual;
+		this.name = "AgentMachineVersionMismatchError";
+	}
+};
+function assertNoHiddenKeys(value, path, isOwnKey) {
+	const symbols = Object.getOwnPropertySymbols(value);
+	if (symbols.length > 0) throw new NonSerializableAgentEventError(`${path}.[${String(symbols[0])}]`, "symbol key");
+	const hiddenKey = Object.getOwnPropertyNames(value).find((key) => !isOwnKey?.(key) && !Object.getOwnPropertyDescriptor(value, key)?.enumerable);
+	if (hiddenKey !== void 0) throw new NonSerializableAgentEventError(`${path}.${hiddenKey}`, "non-enumerable property");
+}
+const arrayIndexPattern = /^(?:0|[1-9]\d*)$/;
+/**
+* Rejects values JSON would drop or coerce. Unlike `JSON.stringify`, this does
+* not silently erase `undefined`/functions or turn non-finite numbers into
+* `null`; durable entries contain only plain JSON values.
+*/
+function assertJsonSerializable(value, path = "entry", ancestors = /* @__PURE__ */ new WeakSet()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || Object.is(value, -0)) throw new NonSerializableAgentEventError(path, Object.is(value, -0) ? "-0" : String(value));
+		return;
+	}
+	if (typeof value !== "object") throw new NonSerializableAgentEventError(path, typeof value);
+	if (ancestors.has(value)) throw new NonSerializableAgentEventError(path, "circular reference");
+	ancestors.add(value);
 	try {
-		const raw = await deps.generateText(request, { signal: deps.signal });
-		output = await normalizeGeneratorResult(raw, id, { request });
-		const rawReasoning = raw?.reasoning;
-		const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
-		const usage = getCallUsage(raw);
-		if (usage) deps.recordUsage?.(usage);
-		deps.onResult?.(agentRequest, {
-			output,
-			raw
-		});
-		deps.onTrace?.({
-			type: "request.end",
-			request: agentRequest,
-			output,
-			raw,
-			...reasoning !== void 0 ? { reasoning } : {},
-			...usage !== void 0 ? { usage } : {}
-		});
-	} catch (error) {
-		deps.onTrace?.({
-			type: "request.error",
-			request: agentRequest,
-			error
+		if (Array.isArray(value)) {
+			for (let index = 0; index < value.length; index++) {
+				if (!Object.hasOwn(value, index)) throw new NonSerializableAgentEventError(`${path}[${index}]`, "array hole");
+				assertJsonSerializable(value[index], `${path}[${index}]`, ancestors);
+			}
+			const extraKey = Object.keys(value).find((key) => !arrayIndexPattern.test(key) || Number(key) >= value.length);
+			if (extraKey !== void 0) throw new NonSerializableAgentEventError(`${path}.${extraKey}`, "array property");
+			assertNoHiddenKeys(value, path, (key) => key === "length" || arrayIndexPattern.test(key));
+			return;
+		}
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) throw new NonSerializableAgentEventError(path, value.constructor?.name ?? "object");
+		assertNoHiddenKeys(value, path);
+		for (const [key, child] of Object.entries(value)) assertJsonSerializable(child, `${path}.${key}`, ancestors);
+	} finally {
+		ancestors.delete(value);
+	}
+}
+function requireNonEmptyString(value, label, qualifier = "") {
+	if (typeof value !== "string" || !value) throw new AgentEventLogError(`Agent event ${label} must be a non-empty string${qualifier}.`);
+}
+/** Validates the complete durable envelope before append/export/replay. */
+function assertAgentLogEntry(entry) {
+	if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new AgentEventLogError("Agent event entry must be an object.");
+	assertJsonSerializable(entry);
+	const candidate = entry;
+	if (candidate.schemaVersion !== 1) throw new AgentEventLogError(`Unsupported agent event schema version '${String(candidate.schemaVersion)}'; expected '1'.`);
+	if (!Number.isInteger(candidate.index) || candidate.index < 0) throw new AgentEventLogError(`Agent event entry.index must be a non-negative integer; got ${String(candidate.index)}.`);
+	for (const field of [
+		"id",
+		"machineId",
+		"machineVersion"
+	]) requireNonEmptyString(candidate[field], `entry.${field}`);
+	if (typeof candidate.recordedAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(candidate.recordedAt) || Number.isNaN(Date.parse(candidate.recordedAt))) throw new AgentEventLogError(`Agent event entry.recordedAt is not RFC 3339: '${String(candidate.recordedAt)}'.`);
+	if (candidate.event === null || typeof candidate.event !== "object" || Array.isArray(candidate.event) || typeof candidate.event.type !== "string" || !candidate.event.type) throw new AgentEventLogError("Agent event entry.event requires a non-empty string type.");
+	if (candidate.causationId !== void 0) requireNonEmptyString(candidate.causationId, "entry.causationId", " when present");
+	if (candidate.metadata !== void 0 && (candidate.metadata === null || typeof candidate.metadata !== "object" || Array.isArray(candidate.metadata))) throw new AgentEventLogError("Agent event entry.metadata must be an object when present.");
+	if (candidate.verification !== void 0 && (candidate.verification === null || typeof candidate.verification !== "object" || typeof candidate.verification.stateHash !== "string" || !candidate.verification.stateHash)) throw new AgentEventLogError("Agent event entry.verification requires a non-empty stateHash string.");
+}
+/**
+* Replaces `Error` instances with plain `{ name, message, cause? }` objects so
+* an `xstate.error.actor` payload survives the log's JSON round-trip. Cycles
+* are preserved by identity; non-plain objects are left alone (and are then
+* rejected by {@link assertJsonSerializable}).
+*/
+function normalizeEventErrors(value, seen = /* @__PURE__ */ new WeakMap()) {
+	if (value instanceof Error) {
+		const normalized = {
+			name: value.name,
+			message: value.message
+		};
+		seen.set(value, normalized);
+		if (value.cause !== void 0) normalized.cause = normalizeEventErrors(value.cause, seen);
+		return normalized;
+	}
+	if (value === null || typeof value !== "object") return value;
+	const existing = seen.get(value);
+	if (existing !== void 0) return existing;
+	if (Array.isArray(value)) {
+		const result = [];
+		seen.set(value, result);
+		for (const item of value) result.push(normalizeEventErrors(item, seen));
+		return result;
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return value;
+	const result = {};
+	seen.set(value, result);
+	for (const [key, item] of Object.entries(value)) result[key] = normalizeEventErrors(item, seen);
+	return result;
+}
+const SNAPSHOT_VOLATILE_KEYS = new Set([
+	"sessionId",
+	"_nextTimerId",
+	"_nextActorIds"
+]);
+const CHILD_VOLATILE_KEYS = new Set(["sessionId"]);
+function positionOf(parent, key) {
+	if (parent === "snapshot") return key === "children" ? "children" : "data";
+	if (parent === "children") return "child";
+	if (parent === "child") return key === "snapshot" ? "snapshot" : "data";
+	return "data";
+}
+function canonicalizeForHash(value, seen = /* @__PURE__ */ new WeakSet(), position = "snapshot") {
+	if (value === void 0) return "[undefined]";
+	if (typeof value === "function") return "[function]";
+	if (typeof value === "bigint") return `[bigint:${String(value)}]`;
+	if (typeof value === "symbol") return `[symbol:${String(value)}]`;
+	if (value === null || typeof value !== "object") return value;
+	if (value instanceof Date) return `[Date:${value.toISOString()}]`;
+	if (value instanceof Error) {
+		if (seen.has(value)) return "[circular]";
+		seen.add(value);
+		try {
+			return {
+				errorName: value.name,
+				message: value.message,
+				...value.cause !== void 0 ? { cause: canonicalizeForHash(value.cause, seen, "data") } : {}
+			};
+		} finally {
+			seen.delete(value);
+		}
+	}
+	if (seen.has(value)) return "[circular]";
+	seen.add(value);
+	try {
+		if (value instanceof Set) return [...value].map((item) => canonicalizeForHash(item, seen, "data")).sort((a, b) => stableJson(a).localeCompare(stableJson(b)));
+		if (value instanceof Map) return [...value.entries()].map(([key, item]) => [canonicalizeForHash(key, seen, "data"), canonicalizeForHash(item, seen, "data")]).sort(([a], [b]) => stableJson(a).localeCompare(stableJson(b)));
+		if (Array.isArray(value)) return value.map((item) => canonicalizeForHash(item, seen, "data"));
+		const volatileKeys = position === "snapshot" ? SNAPSHOT_VOLATILE_KEYS : position === "child" ? CHILD_VOLATILE_KEYS : void 0;
+		const result = {};
+		for (const key of Object.keys(value).sort()) {
+			if (volatileKeys?.has(key)) continue;
+			const child = value[key];
+			if (child === void 0) continue;
+			result[key] = canonicalizeForHash(child, seen, positionOf(position, key));
+		}
+		return result;
+	} finally {
+		seen.delete(value);
+	}
+}
+/**
+* Key-sorted JSON for comparing two events by content: key insertion order
+* does not count, so an entry read back from storage equals the one that was
+* appended.
+* @internal
+*/
+function canonicalEventJson(event) {
+	return stableJson(canonicalizeForHash(event, /* @__PURE__ */ new Set(), "data"));
+}
+function stableJson(value) {
+	return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+	if (Array.isArray(value)) return value.map(sortJson);
+	if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
+	return value;
+}
+/**
+* The canonical hash of a PERSISTED snapshot (`machine.getPersistedSnapshot()`,
+* or {@link replay}'s `persistedSnapshot`) — the value recorded in an entry's
+* `verification.stateHash`.
+*
+* Stripped before hashing, because they are re-minted on every fold and would
+* otherwise make two identical runs hash differently: `sessionId`,
+* `_nextTimerId` and `_nextActorIds` at the snapshot root, `sessionId` on each
+* `children[*]` entry (recursively, through nested child snapshots), and
+* `undefined`-valued properties (so a snapshot hashes the same before and
+* after a JSON round-trip). Stripping is confined to those structural
+* positions: a `sessionId` inside `context`, `output`, `error` or an event
+* payload is application data and is hashed. Object keys are sorted, so key
+* order is irrelevant.
+*
+* A change detector, not a cryptographic digest.
+*/
+function getSnapshotStateHash(snapshot) {
+	return djb2Hex(stableJson(canonicalizeForHash(snapshot)));
+}
+function machineIdOf(machine) {
+	return machine.config.id ?? machine.id ?? "(machine)";
+}
+function toPersisted(machine, snapshot) {
+	return typeof snapshot.matches === "function" ? machine.getPersistedSnapshot(snapshot) : snapshot;
+}
+/**
+* Creates a JSON-safe, self-describing entry for `event` appended after
+* `entries` (which must be the complete prefix, so `index` and the recorded
+* state hash line up).
+*/
+function createReplayEntry(machine, entries, event, options = {}) {
+	const index = entries.length;
+	const machineVersion = options.machineVersion ?? resolveMachineVersion(machine);
+	const entry = {
+		schemaVersion: 1,
+		id: options.id ?? `evt_${String(index).padStart(8, "0")}`,
+		index,
+		recordedAt: options.recordedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		machineId: machineIdOf(machine),
+		machineVersion,
+		event: normalizeEventErrors(event),
+		...options.causationId !== void 0 ? { causationId: options.causationId } : {},
+		...options.metadata !== void 0 ? { metadata: options.metadata } : {}
+	};
+	assertAgentLogEntry(entry);
+	if (options.verification !== false) entry.verification = { stateHash: getSnapshotStateHash(options.snapshot ? toPersisted(machine, options.snapshot) : replay(machine, [...entries, entry], {
+		machineVersion,
+		verify: false
+	}).persistedSnapshot) };
+	return entry;
+}
+function pruneUndefined(value) {
+	if (Array.isArray(value)) return value.map(pruneUndefined);
+	if (value === null || typeof value !== "object") return value;
+	if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return value;
+	const result = {};
+	for (const [key, child] of Object.entries(value)) {
+		if (child === void 0) continue;
+		result[key] = pruneUndefined(child);
+	}
+	return result;
+}
+/**
+* The reserved first entry of a log. Pass EXACTLY one of:
+*
+* - `{ input }` — a fresh start; replay folds from `initialTransition`.
+* - `{ snapshot }` — a continuation from a persisted snapshot: a version
+*   bridge, or a legacy snapshot that predates the log. Replay restores it
+*   purely (no actors started) and folds the rest of the log onto it.
+*
+* `options.metadata.executionId` names the lineage; this library always sets
+* one, and readers must tolerate its absence in logs written elsewhere.
+*/
+function initEntry(machine, init = {}, options = {}) {
+	const hasSnapshot = init.snapshot !== void 0;
+	if (hasSnapshot && init.input !== void 0) throw new AgentEventLogError("initEntry accepts exactly one of `input` (fresh start) or `snapshot` (continuation).");
+	return createReplayEntry(machine, [], {
+		type: AGENT_INIT_EVENT_TYPE,
+		...hasSnapshot ? { snapshot: pruneUndefined(init.snapshot) } : init.input !== void 0 ? { input: init.input } : {}
+	}, options);
+}
+/** Whether `entry` is the reserved init entry. */
+function isInitEntry(entry) {
+	return entry?.event?.type === AGENT_INIT_EVENT_TYPE;
+}
+/** Whether `entry` is the version-bridging init-with-snapshot entry. */
+function isSnapshotInitEntry(entry) {
+	return isInitEntry(entry) && entry.event.snapshot !== void 0;
+}
+/**
+* The log's execution id: the lineage identity pinned in the init entry's
+* `metadata.executionId`.
+*
+* Minted once per run and inherited verbatim by every resume of that log, so
+* it names one lineage rather than one process. Entry ids cannot serve this
+* role — the built-in ids are index-derived, so every log's init entry is
+* `evt_00000000`. A fork copies the init entry, so it shares its parent's
+* execution id by construction.
+*
+* Returns `undefined` for a log with no init entry and for one written without
+* the field — callers must treat the id as optional.
+*/
+function getLogExecutionId(entries) {
+	const executionId = (entries.find((entry) => isInitEntry(entry))?.metadata)?.executionId;
+	return typeof executionId === "string" ? executionId : void 0;
+}
+/**
+* Validates a log before replay or append: every envelope well-formed, indices
+* contiguous from 0, ids unique, the first entry the reserved init entry, and
+* one consistent machine identity throughout.
+*
+* With `machine`, entries are also checked against that machine's id and
+* resolved version — a mismatch throws {@link AgentMachineVersionMismatchError}.
+* An init-with-snapshot entry is exempt from the version check: that entry is
+* itself the bridge from whatever version produced the snapshot.
+*/
+function validateReplayEntries(entries, options = {}) {
+	if (entries.length === 0) return;
+	const reference = entries.find((entry) => !isSnapshotInitEntry(entry)) ?? entries[0];
+	const expected = options.machine ? {
+		machineId: machineIdOf(options.machine),
+		machineVersion: options.machineVersion ?? resolveMachineVersion(options.machine)
+	} : {
+		machineId: reference.machineId,
+		machineVersion: options.machineVersion ?? reference.machineVersion
+	};
+	const ids = /* @__PURE__ */ new Set();
+	for (let index = 0; index < entries.length; index++) {
+		const entry = entries[index];
+		assertAgentLogEntry(entry);
+		if (entry.index !== index) throw new AgentEventLogError(`Event log must be contiguous from index 0; found entry.index ${entry.index} at position ${index}.`);
+		if (ids.has(entry.id)) throw new AgentEventLogError(`Event log contains duplicate entry id '${entry.id}'.`);
+		ids.add(entry.id);
+		if (index === 0 && !isInitEntry(entry)) throw new AgentEventLogError(`Event log must start with the reserved '${AGENT_INIT_EVENT_TYPE}' entry; found '${entry.event.type}'.`);
+		if (index > 0 && isInitEntry(entry)) throw new AgentEventLogError(`Event log has a second '${AGENT_INIT_EVENT_TYPE}' entry at index ${index}.`);
+		const versionMatches = entry.machineVersion === expected.machineVersion;
+		if (entry.machineId !== expected.machineId || !versionMatches && !isSnapshotInitEntry(entry)) throw new AgentMachineVersionMismatchError(entry.id, entry.index, expected, {
+			machineId: entry.machineId,
+			machineVersion: entry.machineVersion
 		});
-		throw error;
+	}
+}
+/**
+* The prefix `[0, upToIndex)` of a log, as a new log. `upToIndex` is exclusive
+* and must leave the init entry in place, so the fork is still self-contained.
+*/
+function forkEventLog(entries, upToIndex) {
+	if (!Number.isInteger(upToIndex) || upToIndex < 1 || upToIndex > entries.length) throw new AgentEventLogError(`forkEventLog: upToIndex must be an integer in [1, ${entries.length}]; got ${String(upToIndex)}.`);
+	const forked = entries.slice(0, upToIndex);
+	if (!isInitEntry(forked[0])) throw new AgentEventLogError(`forkEventLog: the forked prefix must start with the reserved '${AGENT_INIT_EVENT_TYPE}' entry.`);
+	return forked;
+}
+const DONE_ACTOR_EVENT_TYPE = "xstate.done.actor";
+const ERROR_ACTOR_EVENT_TYPE = "xstate.error.actor";
+/** Normalizes a mixed `EventObject | AgentLogEntry` history into bare events. */
+function toEvents(history) {
+	if (!history) return [];
+	return history.map((item) => {
+		const candidate = item;
+		return candidate?.schemaVersion === 1 && typeof candidate.index === "number" && candidate.event !== null && typeof candidate.event === "object" ? candidate.event : item;
+	});
+}
+/**
+* The 1-based occurrence `n` for the NEXT call at invoke site `siteId`:
+* `1 + completions`, where a completion is a journaled `xstate.done.actor` OR
+* `xstate.error.actor` for that `actorId` (an error is a semantic completion).
+* The one counting rule behind every `${siteId}#${n}` call key, so a live run
+* and a replay derive the same `n` by construction.
+*/
+function agentCallOccurrence(history, siteId) {
+	let count = 0;
+	for (const event of toEvents(history)) if ((event.type === DONE_ACTOR_EVENT_TYPE || event.type === ERROR_ACTOR_EVENT_TYPE) && event.actorId === siteId) count++;
+	return count + 1;
+}
+/**
+* Folds the reserved `@agent.usage` entries of a log into one cumulative usage
+* total. The log is the source of truth, so the totals are a pure projection of
+* it: replay a log, fold it, and you get the numbers the run reported with no
+* host-side accumulator in between.
+*
+* Accepts entries or bare events. Token fields are partial sums: a field stays
+* `undefined` until some entry reports it, and non-finite values are ignored.
+*/
+function getUsageFromEvents(entries) {
+	const totals = {};
+	for (const event of toEvents(entries)) {
+		if (event.type !== "@agent.usage") continue;
+		const usage = event.usage;
+		if (!usage || typeof usage !== "object") continue;
+		for (const field of AGENT_USAGE_TOKEN_FIELDS) {
+			const value = usage[field];
+			if (typeof value === "number" && Number.isFinite(value)) totals[field] = (totals[field] ?? 0) + value;
+		}
+	}
+	return totals;
+}
+/**
+* Rewrites a journaled `xstate.done.actor`/`xstate.error.actor` event's
+* `sessionId` to the session the CURRENT fold minted for that `actorId`.
+*
+* Session ids are re-minted on every fold, and XState drops a completion event
+* whose `sessionId` does not match the live child — silently, as a no-op
+* transition. Rebinding is what makes a journaled completion replayable at all.
+* `sessions` caches the mapping per fold, so a later event referring to the
+* recorded session of an already-stopped child still resolves.
+*/
+function rebindActorSession(event, snapshot, sessions) {
+	const actorEvent = event;
+	if (typeof actorEvent.actorId !== "string" || typeof actorEvent.sessionId !== "string") return event;
+	const key = `${actorEvent.actorId}\0${actorEvent.sessionId}`;
+	let sessionId = sessions.get(key);
+	if (!sessionId) {
+		const child = snapshot.children[actorEvent.actorId];
+		if (typeof child?.sessionId !== "string") return event;
+		sessionId = child.sessionId;
+		sessions.set(key, sessionId);
 	}
 	return {
-		stateRequest,
-		id,
-		output,
-		appended: [promptMessage, assistantMessage(typeof output === "string" ? output : JSON.stringify(output))]
-	};
-}
-async function runAdvancePhase(plan, deps) {
-	const { stateRequest, id, output } = plan;
-	const { model, system } = stateRequest;
-	deps.appendToLog(...plan.appended);
-	if (stateRequest.kind !== "decision" && stateRequest.onDone !== void 0) {
-		const snapshot = deps.getSnapshot();
-		const resolved = typeof stateRequest.onDone === "function" ? stateRequest.onDone({
-			output,
-			snapshot,
-			messages: deps.messages
-		}) : stateRequest.onDone;
-		if (!resolved) return false;
-		const acceptedTypes = getAcceptedEvents(snapshot, { schemas: deps.schemas }).map((descriptor) => descriptor.type);
-		if (!acceptedTypes.includes(resolved.type)) throw new Error(`runAgent: getRequests request '${id}' resolved onDone to event '${resolved.type}', which the current state does not accept. Accepted: ${acceptedTypes.join(", ") || "(none)"}.`);
-		if (!snapshot.can(resolved)) return false;
-		deps.send(resolved);
-		return true;
+		...event,
+		sessionId
+	};
+}
+function verifyEntry(entry, persisted, mode) {
+	if (mode === false) return;
+	if (!entry.verification) {
+		if (mode === "strict") throw new AgentReplayDivergenceError(entry.id, entry.index, "missing-verification");
+		return;
 	}
-	const events = getAcceptedEvents(deps.getSnapshot(), {
-		schemas: deps.schemas,
-		...stateRequest.allowedEvents ? { eventTypes: stateRequest.allowedEvents } : {}
-	});
-	if (events.length === 0) return false;
-	if (!deps.decide) throw new Error(`runAgent: a getRequests request without 'onDone' needs a 'decide' executor to choose between events ${events.map((descriptor) => `'${descriptor.type}'`).join(", ")}. Provide request.onDone for deterministic advancement, or a 'decide' executor.`);
-	const chosen = await resolveDecision({
-		kind: "decision",
-		id,
-		model,
-		...system !== void 0 ? { system } : {},
-		messages: [...deps.messages],
-		events,
-		attempts: []
-	}, { decide: deps.decide }, {
-		signal: deps.signal,
-		canTake: (event) => deps.getSnapshot().can(event)
+	const actual = getSnapshotStateHash(persisted);
+	if (actual !== entry.verification.stateHash) throw new AgentReplayDivergenceError(entry.id, entry.index, "state", entry.verification.stateHash, actual);
+}
+/**
+* Folds a log through XState's pure `initialTransition`/`transition` WITHOUT
+* executing anything: no actor is started, no action runs, no model is called.
+* A journaled `xstate.done.actor` entry carries the completed actor's output
+* inline, so the invoke it belongs to is never re-run. Crash recovery, fork
+* resume, and time travel in one call.
+*
+* The first entry is the reserved {@link initEntry}: `input` folds from
+* `initialTransition`, `snapshot` restores the persisted snapshot purely
+* (`machine.restoreSnapshot`) and folds the rest of the log onto it.
+*/
+function replay(machine, entries, options = {}) {
+	validateReplayEntries(entries, {
+		machine,
+		machineVersion: options.machineVersion ?? resolveMachineVersion(machine)
 	});
-	if (deps.isSettled()) return false;
-	deps.appendToLog(assistantMessage(`[chose: ${chosen.type}]`));
-	deps.send(chosen);
-	return true;
-}
-/**
-* Executes one getRequests pass: all text calls concurrently against the
-* pass-start log, then per-request advancement sequentially in request
-* order. Returns whether ANY request sent an event — the host settles idle
-* when none did (otherwise an unchanged snapshot would re-produce the same
-* pass forever). Stops early (skipping remaining appends/sends) once
-* {@link StateRequestPassDeps.isSettled} reports the run is over. Throws on
-* executor/`onDone` errors — the host maps them to its error settle.
-*/
-async function runStateRequestPass(requests, deps) {
-	const baseMessages = [...deps.messages];
-	const plans = await Promise.all(requests.map((stateRequest) => runTextPhase(stateRequest, baseMessages, deps)));
-	let sentAny = false;
-	for (const plan of plans) {
-		if (deps.isSettled()) break;
-		sentAny = await runAdvancePhase(plan, deps) || sentAny;
+	if (entries.length === 0) throw new AgentEventLogError(`Cannot replay an empty event log; it must start with a '${AGENT_INIT_EVENT_TYPE}' entry.`);
+	const initEvent = entries[0].event;
+	let snapshot = initEvent.snapshot !== void 0 ? machine.restoreSnapshot(initEvent.snapshot) : initialTransition(machine, initEvent.input)[0];
+	let persisted = machine.getPersistedSnapshot(snapshot);
+	verifyEntry(entries[0], persisted, options.verify);
+	const sessions = /* @__PURE__ */ new Map();
+	for (let index = 1; index < entries.length; index++) {
+		const entry = entries[index];
+		const event = rebindActorSession(entry.event, snapshot, sessions);
+		[snapshot] = transition(machine, snapshot, event);
+		persisted = machine.getPersistedSnapshot(snapshot);
+		verifyEntry(entry, persisted, options.verify);
 	}
-	return { sentAny };
+	return {
+		snapshot,
+		persistedSnapshot: persisted
+	};
 }
 //#endregion
-//#region src/run-agent.ts
+//#region src/event-log-store.ts
+/**
+* Durable storage for {@link AgentLogEntry} logs: the one interface a host
+* implements, plus the in-memory reference implementation the conformance
+* suite is written against.
+* @module
+*/
 /**
-* Thrown by {@link runAgent} when resuming with a `snapshot` + `event` whose
-* `type` the restored state cannot accept (a type-level check via
-* {@link getAcceptedEvents}). A programmer/integration error, in the same
-* class as runAgent's bind-time throws — it throws rather than settling an
-* `error` result. A type-legal event a guard rejects is NOT this error (the
-* machine simply takes no transition). Always enforced; there is no opt-out.
-*/
-var AgentIllegalResumeEventError = class extends AgentError {
-	eventType;
-	acceptedTypes;
-	constructor(eventType, acceptedTypes) {
-		super("illegal-resume-event", `runAgent: cannot resume with event '${eventType}' — the restored state does not accept it. Accepted event types: ${acceptedTypes.length > 0 ? acceptedTypes.join(", ") : "(none)"}.`);
-		this.name = "AgentIllegalResumeEventError";
-		this.eventType = eventType;
-		this.acceptedTypes = acceptedTypes;
+* Rejection from {@link AgentEventLogStore.append} when the thread's stored
+* length is not the `expectedIndex` the writer held — a concurrent writer
+* appended first. `actualIndex` is the next index the store would accept.
+*/
+var AgentEventLogConflictError = class extends AgentError {
+	threadId;
+	expectedIndex;
+	actualIndex;
+	constructor(threadId, expectedIndex, actualIndex) {
+		super("event-log-conflict", `AgentEventLogStore.append: index conflict on thread "${threadId}": expected index ${expectedIndex} but found ${actualIndex} — a concurrent writer won.`);
+		this.name = "AgentEventLogConflictError";
+		this.threadId = threadId;
+		this.expectedIndex = expectedIndex;
+		this.actualIndex = actualIndex;
 	}
 };
 /**
-* Thrown by {@link runAgent} when resuming from a `snapshot` whose stamped
-* `agentMeta.version` differs from the current machine's version, under the
-* default `onVersionMismatch: 'throw'` and with no `migrateSnapshot` hook. The
-* structural fingerprint of the machine changed since the snapshot was
-* persisted (a state/transition/invoke was added, removed, or retargeted), so
-* the snapshot may no longer resume cleanly. `from` is the snapshot's version,
-* `to` the current machine's.
-*/
-var AgentSnapshotVersionMismatchError = class extends AgentError {
-	from;
-	to;
-	machineId;
-	constructor(from, to, machineId) {
-		super("snapshot-version-mismatch", `runAgent: cannot resume snapshot stamped with machine version '${from}' against machine '${machineId}' at version '${to}' — the machine's structure changed since the snapshot was persisted. Provide options.migrateSnapshot to adapt it, or set options.onVersionMismatch to 'warn'/'ignore' to proceed anyway.`);
-		this.name = "AgentSnapshotVersionMismatchError";
-		this.from = from;
-		this.to = to;
-		this.machineId = machineId;
+* In-memory reference store, and the baseline the conformance suite runs
+* against. Per-thread entries are held in a contiguous, index-ordered list;
+* append's check-and-push runs synchronously (no `await` between reading the
+* length and writing), so two appends racing on the same `expectedIndex`
+* resolve to exactly one winner. Every stored and returned entry is
+* `structuredClone`d, so a caller can neither mutate stored state through a
+* value it appended nor through a value it read.
+*/
+function createInMemoryEventLogStore() {
+	const threads = /* @__PURE__ */ new Map();
+	const clone = (value) => structuredClone(value);
+	return {
+		async append({ threadId, expectedIndex, entries }) {
+			for (const entry of entries) assertAgentLogEntry(entry);
+			for (let i = 0; i < entries.length; i++) if (entries[i].index !== expectedIndex + i) throw new Error(`AgentEventLogStore.append: entry.index (${entries[i].index}) must be contiguous from expectedIndex (${expectedIndex}); expected ${expectedIndex + i} at position ${i} on thread "${threadId}".`);
+			const list = threads.get(threadId);
+			const length = list ? list.length : 0;
+			if (length !== expectedIndex) throw new AgentEventLogConflictError(threadId, expectedIndex, length);
+			const ids = new Set((list ?? []).map((entry) => entry.id));
+			for (const entry of entries) {
+				if (ids.has(entry.id)) throw new Error(`AgentEventLogStore.append: duplicate event id "${entry.id}" in thread "${threadId}".`);
+				ids.add(entry.id);
+			}
+			const cloned = entries.map((entry) => clone(entry));
+			if (list) for (const entry of cloned) list.push(entry);
+			else threads.set(threadId, cloned);
+		},
+		async read(threadId, options) {
+			const list = threads.get(threadId) ?? [];
+			const from = options?.from ?? 0;
+			return list.slice(from).map((entry) => clone(entry));
+		},
+		async length(threadId) {
+			return threads.get(threadId)?.length ?? 0;
+		},
+		async fork({ threadId, newThreadId, upToIndex }) {
+			if ((threads.get(newThreadId)?.length ?? 0) > 0) throw new Error(`AgentEventLogStore.fork: newThreadId "${newThreadId}" already has entries.`);
+			const source = threads.get(threadId);
+			if (!source) throw new Error(`AgentEventLogStore.fork: unknown source thread "${threadId}".`);
+			const upTo = upToIndex ?? source.length;
+			if (!Number.isInteger(upTo) || upTo < 1 || upTo > source.length) throw new Error(`AgentEventLogStore.fork: upToIndex must be an integer in [1, ${source.length}] on thread "${threadId}"; got ${String(upTo)}.`);
+			threads.set(newThreadId, source.slice(0, upTo).map((entry) => clone(entry)));
+		}
+	};
+}
+//#endregion
+//#region src/event-log-store-conformance.ts
+/**
+* The runner-agnostic conformance suite for {@link AgentEventLogStore}
+* implementations. Split out of `event-log-store.ts` so the store contract and
+* the reference implementation stay readable.
+*
+* Every case throws a descriptive `Error` on the first violation, so any test
+* runner (or a plain script) can drive it against its own store. Pass a
+* `{ describe, it }` harness to register one test per case instead.
+* @module
+*/
+function fail(message) {
+	throw new Error(`event-log-store conformance: ${message}`);
+}
+function entry(index, type, metadata) {
+	return {
+		schemaVersion: 1,
+		id: `evt_${index}`,
+		index,
+		recordedAt: "2026-01-01T00:00:00.000Z",
+		machineId: "conformance",
+		machineVersion: "v1",
+		event: {
+			type,
+			seq: index
+		},
+		...metadata !== void 0 ? { metadata } : {}
+	};
+}
+function entriesFrom(start, count) {
+	return Array.from({ length: count }, (_unused, i) => entry(start + i, `e${start + i}`));
+}
+function assertJsonEqual(actual, expected, message) {
+	const a = JSON.stringify(actual);
+	const b = JSON.stringify(expected);
+	if (a !== b) fail(`${message} (expected ${b}, got ${a})`);
+}
+const cases = [
+	{
+		name: "an unknown thread reads empty and has length 0",
+		async run(create) {
+			const store = await create();
+			assertJsonEqual(await store.read("missing"), [], "read of an unknown thread must be empty");
+			if (await store.length("missing") !== 0) fail("length of an unknown thread must be 0");
+		}
+	},
+	{
+		name: "a single append reads back verbatim",
+		async run(create) {
+			const store = await create();
+			const e = entry(0, "start", { label: "first" });
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: [e]
+			});
+			assertJsonEqual(await store.read("t"), [e], "read must return the appended entry");
+			if (await store.length("t") !== 1) fail("length after a single append must be 1");
+		}
+	},
+	{
+		name: "a second append extends the log in order",
+		async run(create) {
+			const store = await create();
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: entriesFrom(0, 3)
+			});
+			await store.append({
+				threadId: "t",
+				expectedIndex: 3,
+				entries: entriesFrom(3, 2)
+			});
+			if (await store.length("t") !== 5) fail("length after appending 3 then 2 entries must be 5");
+			assertJsonEqual((await store.read("t")).map((e) => e.index), [
+				0,
+				1,
+				2,
+				3,
+				4
+			], "reads must return entries in contiguous log order");
+		}
+	},
+	{
+		name: "a non-contiguous entry.index is misuse, not a race",
+		async run(create) {
+			const store = await create();
+			let caught;
+			try {
+				await store.append({
+					threadId: "t",
+					expectedIndex: 0,
+					entries: [entry(1, "gap")]
+				});
+			} catch (error) {
+				caught = error;
+			}
+			if (!(caught instanceof Error) || caught instanceof AgentEventLogConflictError) fail("a non-contiguous entry.index must throw a plain Error, not a conflict");
+		}
+	},
+	{
+		name: "a stale expectedIndex conflicts with correct fields",
+		async run(create) {
+			const store = await create();
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: [entry(0, "a")]
+			});
+			let caught;
+			try {
+				await store.append({
+					threadId: "t",
+					expectedIndex: 0,
+					entries: [entry(0, "b")]
+				});
+			} catch (error) {
+				caught = error;
+			}
+			if (!(caught instanceof AgentEventLogConflictError)) fail("a stale expectedIndex must throw AgentEventLogConflictError");
+			if (caught.threadId !== "t" || caught.expectedIndex !== 0 || caught.actualIndex !== 1) fail("conflict error must carry threadId, expectedIndex, and the actual index");
+		}
+	},
+	{
+		name: "entry ids are unique within a thread",
+		async run(create) {
+			const store = await create();
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: [entry(0, "a")]
+			});
+			let caught;
+			try {
+				await store.append({
+					threadId: "t",
+					expectedIndex: 1,
+					entries: [{
+						...entry(1, "b"),
+						id: "evt_0"
+					}]
+				});
+			} catch (error) {
+				caught = error;
+			}
+			if (!(caught instanceof Error) || caught instanceof AgentEventLogConflictError) fail("a duplicate event id within a thread must throw a plain Error");
+		}
+	},
+	{
+		name: "concurrent appends at the same index have exactly one winner",
+		async run(create) {
+			const store = await create();
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: [entry(0, "a")]
+			});
+			const results = await Promise.allSettled([store.append({
+				threadId: "t",
+				expectedIndex: 1,
+				entries: [entry(1, "w-a")]
+			}), store.append({
+				threadId: "t",
+				expectedIndex: 1,
+				entries: [entry(1, "w-b")]
+			})]);
+			const winners = results.filter((r) => r.status === "fulfilled");
+			const conflicts = results.filter((r) => r.status === "rejected" && r.reason instanceof AgentEventLogConflictError);
+			if (winners.length !== 1) fail(`exactly one racing append must win, got ${winners.length}`);
+			if (conflicts.length !== 1) fail(`exactly one racing append must reject with a conflict, got ${conflicts.length}`);
+			if (await store.length("t") !== 2) fail("after the race the log length must be 2");
+		}
+	},
+	{
+		name: "read({ from }) is incrementally correct",
+		async run(create) {
+			const store = await create();
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: entriesFrom(0, 5)
+			});
+			assertJsonEqual((await store.read("t", { from: 2 })).map((e) => e.index), [
+				2,
+				3,
+				4
+			], "read({ from }) must skip entries below `from`");
+			assertJsonEqual(await store.read("t", { from: 5 }), [], "read({ from }) at the log length must be empty");
+		}
+	},
+	{
+		name: "threads are isolated and grow independently",
+		async run(create) {
+			const store = await create();
+			await store.append({
+				threadId: "a",
+				expectedIndex: 0,
+				entries: [entry(0, "x")]
+			});
+			if (await store.length("b") !== 0) fail("an append to one thread must not create another");
+			await store.append({
+				threadId: "b",
+				expectedIndex: 0,
+				entries: entriesFrom(0, 2)
+			});
+			if (await store.length("a") !== 1 || await store.length("b") !== 2) fail("threads must grow independently");
+		}
+	},
+	{
+		name: "metadata round-trips verbatim",
+		async run(create) {
+			const store = await create();
+			const metadata = {
+				source: "user",
+				nested: { attempt: 2 },
+				tags: ["x", "y"]
+			};
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: [entry(0, "e", metadata)]
+			});
+			assertJsonEqual((await store.read("t"))[0].metadata, metadata, "metadata must round-trip verbatim");
+		}
+	},
+	{
+		name: "stored entries are isolated from caller mutation",
+		async run(create) {
+			const store = await create();
+			const e = entry(0, "e", { tags: ["a"] });
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: [e]
+			});
+			e.metadata.tags.push("mutated-after-append");
+			e.event.seq = 999;
+			const read = await store.read("t");
+			read[0].metadata.tags.push("mutated-after-read");
+			read[0].event.seq = 888;
+			const reread = await store.read("t");
+			assertJsonEqual(reread[0].metadata, { tags: ["a"] }, "stored entry must be isolated from post-append and post-read mutation");
+			assertJsonEqual(reread[0].event, {
+				type: "e",
+				seq: 0
+			}, "stored event must be isolated from mutation of an appended or read copy");
+		}
+	},
+	{
+		name: "fork copies a prefix and then diverges independently",
+		async run(create) {
+			const store = await create();
+			await store.append({
+				threadId: "src",
+				expectedIndex: 0,
+				entries: entriesFrom(0, 3)
+			});
+			await store.fork({
+				threadId: "src",
+				newThreadId: "fork-full"
+			});
+			if (await store.length("fork-full") !== 3) fail("fork with the default upToIndex must copy the full log");
+			await store.fork({
+				threadId: "src",
+				newThreadId: "fork-1",
+				upToIndex: 1
+			});
+			assertJsonEqual((await store.read("fork-1")).map((e) => e.index), [0], "fork with upToIndex 1 must copy only entry 0");
+			await store.fork({
+				threadId: "src",
+				newThreadId: "fork-2",
+				upToIndex: 2
+			});
+			assertJsonEqual((await store.read("fork-2")).map((e) => e.id), ["evt_0", "evt_1"], "fork with upToIndex 2 must copy entries 0 and 1 only");
+			await store.append({
+				threadId: "fork-1",
+				expectedIndex: 1,
+				entries: [entry(1, "branch")]
+			});
+			assertJsonEqual((await store.read("fork-1")).map((e) => e.event.type), ["e0", "branch"], "a forked thread must append independently from its copied length");
+			if (await store.length("src") !== 3) fail("appending to a fork must not touch the source thread");
+		}
+	},
+	{
+		name: "fork rejects a non-empty target, an unknown source, and an out-of-range cutoff (0 included)",
+		async run(create) {
+			const store = await create();
+			await store.append({
+				threadId: "src",
+				expectedIndex: 0,
+				entries: entriesFrom(0, 3)
+			});
+			await store.fork({
+				threadId: "src",
+				newThreadId: "fork-full"
+			});
+			let caughtExisting;
+			try {
+				await store.fork({
+					threadId: "src",
+					newThreadId: "fork-full"
+				});
+			} catch (error) {
+				caughtExisting = error;
+			}
+			if (!(caughtExisting instanceof Error) || caughtExisting instanceof AgentEventLogConflictError) fail("forking onto a non-empty thread must reject with a plain Error");
+			let caughtUnknown;
+			try {
+				await store.fork({
+					threadId: "nope",
+					newThreadId: "fork-nope"
+				});
+			} catch (error) {
+				caughtUnknown = error;
+			}
+			if (!(caughtUnknown instanceof Error) || caughtUnknown instanceof AgentEventLogConflictError) fail("forking an unknown source thread must reject with a plain Error");
+			let caughtRange;
+			try {
+				await store.fork({
+					threadId: "src",
+					newThreadId: "fork-range",
+					upToIndex: 99
+				});
+			} catch (error) {
+				caughtRange = error;
+			}
+			if (!(caughtRange instanceof Error) || caughtRange instanceof AgentEventLogConflictError) fail("forking past the source length must reject with a plain Error");
+			let caughtZero;
+			try {
+				await store.fork({
+					threadId: "src",
+					newThreadId: "fork-zero",
+					upToIndex: 0
+				});
+			} catch (error) {
+				caughtZero = error;
+			}
+			if (!(caughtZero instanceof Error) || caughtZero instanceof AgentEventLogConflictError) fail("forking with upToIndex 0 must reject with a plain Error");
+			if (await store.length("fork-zero") !== 0) fail("a rejected fork must not create the target thread");
+		}
+	}
+];
+/**
+* Validates a store against the reference's semantics: empty read + zero length
+* for unknown threads; single and multi-entry append; contiguity misuse guard;
+* stale-`expectedIndex` conflict with correct fields; an interleaved concurrent
+* append race (exactly one winner); entry-id uniqueness; `read({ from })`
+* incremental correctness; thread isolation; metadata round-trip; deep-copy
+* isolation on append and read; and the full fork contract.
+*
+* Without a `harness`, every case runs in sequence and the first violation
+* throws. With one, each case is registered as its own test:
+*
+* ```ts
+* import { describe, it } from 'vitest';
+* assertEventLogStoreConformance(createMyStore, { describe, it });
+* ```
+*/
+async function assertEventLogStoreConformance(create, harness) {
+	if (harness) {
+		harness.describe("AgentEventLogStore conformance", () => {
+			for (const testCase of cases) harness.it(testCase.name, () => testCase.run(create));
+		});
+		return;
 	}
-};
+	for (const testCase of cases) await testCase.run(create);
+}
+//#endregion
+//#region src/run-agent.ts
 /**
-* Thrown by {@link generateResult} when the run settles `idle` instead of
-* `done`: the machine paused for external input. Carries the idle `snapshot`
-* and `acceptedTypes` (the event types that could resume it, via
-* {@link getAcceptedEvents}). Use {@link runAgent} directly when idle is an
-* expected outcome you handle.
-*/
-var AgentIdleError = class extends AgentError {
-	snapshot;
-	acceptedTypes;
-	constructor(snapshot, acceptedTypes) {
-		super("agent-idle", `generateResult: the machine paused (idle) instead of completing. Resume it by calling runAgent with one of these events: ${acceptedTypes.length > 0 ? acceptedTypes.join(", ") : "(none)"}.`);
-		this.name = "AgentIdleError";
-		this.snapshot = snapshot;
-		this.acceptedTypes = acceptedTypes;
+* Thrown by {@link runAgent} when a resume is given BOTH an `events` log and a
+* `snapshot` that claims a position in that log (`agentMeta.logIndex`), and the
+* two disagree about the state at that position. The log is the source of
+* truth, so this is a host bug (a snapshot cached from a different lineage, or
+* a snapshot mutated out of band), not a recoverable resume: pass the log
+* alone, or the matching snapshot.
+*/
+var AgentSnapshotDivergedError = class extends AgentError {
+	constructor(expected, actual, logIndex) {
+		super("snapshot-diverged", `runAgent: the resume snapshot disagrees with the event log at index ${logIndex}: the log replays to state hash '${expected}', the snapshot hashes '${actual}'.`);
+		this.expected = expected;
+		this.actual = actual;
+		this.logIndex = logIndex;
+		this.name = "AgentSnapshotDivergedError";
 	}
 };
+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 getSnapshotStateHash(rest);
+	}
+	return getSnapshotStateHash(snapshot);
+}
+function readAgentMeta(snapshot) {
+	const meta = snapshot?.agentMeta;
+	return meta !== null && typeof meta === "object" ? meta : void 0;
+}
 /**
 * The version of the {@link AgentTraceEvent} envelope every trace event carries
 * as `schemaVersion`. Bumped only on a breaking change to the envelope or any
@@ -207,8 +1381,8 @@ const TRACE_ENVELOPE_KEYS = [
 	"type",
 	"status",
 	"cause",
-	"eventId",
 	"reasoning",
+	"finishReason",
 	"chunk"
 ];
 /**
@@ -284,69 +1458,6 @@ function serializeTraceEvent(event, options = {}) {
 	}
 	return out;
 }
-function snapshotNodes(snapshot) {
-	return (snapshot.nodes ?? []).map((raw) => {
-		const node = raw;
-		return {
-			id: node.id ?? "",
-			key: node.key ?? "",
-			...node.description !== void 0 ? { description: node.description } : {},
-			tags: [...node.tags ?? []],
-			...node.meta !== void 0 ? { meta: node.meta } : {},
-			ownEvents: [...node.ownEvents ?? []],
-			leaf: Object.keys(node.states ?? {}).length === 0
-		};
-	});
-}
-/**
-* The active state nodes of a snapshot, as plain {@link AgentSnapshotNode}
-* descriptors. The escape hatch under {@link getSnapshotRequests}: use it when
-* your `getRequests` hook needs to build requests some other way, so host code
-* never touches xstate's private `snapshot._nodes`.
-*/
-function getSnapshotNodes(snapshot) {
-	return snapshotNodes(snapshot);
-}
-/**
-* Builds the {@link AgentStateRequest}s for a snapshot straight from its active
-* state nodes — the prompts-in-descriptions recipe as a function, so a
-* {@link RunAgentOptions.getRequests} hook is one line and never reaches into
-* xstate's private `snapshot._nodes`:
-*
-* ```ts
-* runAgent(machine, {
-*   executors,
-*   getRequests: (snapshot) => getSnapshotRequests(snapshot, { model: 'writer' }),
-* });
-* ```
-*
-* Each described active node becomes one request: `prompt` from the node's
-* `description`, `kind: 'decision'` when it is tagged `'decision'`, `system`
-* from `meta.role` when present, `allowedEvents` scoped to the node's own
-* events, and an explicit `onDone` when the node has exactly one own event
-* (single-outcome states advance deterministically; anything else falls
-* through to a `decide` call). Nodes tagged `'waiting'` produce nothing, so the
-* run settles idle for a human. Override any of it with `filter`/`map`.
-*/
-function getSnapshotRequests(snapshot, options) {
-	const filter = options.filter ?? ((node) => !!node.description && !node.tags.includes("waiting"));
-	const requests = [];
-	for (const node of snapshotNodes(snapshot)) {
-		if (!filter(node)) continue;
-		const system = node.meta?.role;
-		const request = {
-			model: options.model,
-			prompt: node.description ?? "",
-			kind: node.tags.includes("decision") ? "decision" : "text",
-			...system !== void 0 ? { system } : {},
-			...node.ownEvents.length > 0 ? { allowedEvents: node.ownEvents } : {},
-			...node.ownEvents.length === 1 ? { onDone: { type: node.ownEvents[0] } } : {}
-		};
-		const mapped = options.map ? options.map(request, node) : request;
-		if (mapped) requests.push(mapped);
-	}
-	return requests;
-}
 let nextRunAgentTraceId = 1;
 /**
 * Thrown into the invoke that would have made the call once
@@ -571,10 +1682,10 @@ function bindTextLogic(logic, runCtx) {
 	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" ? {
+		const request = {
 			...rawRequest,
-			name: src
-		} : rawRequest;
+			name: rawRequest.name ?? (src !== "" && src !== "agent.generateText" && src !== "agent.streamText" ? src : id || src)
+		};
 		const executor = logic.mode === "stream" ? runCtx.streamText : runCtx.generateText;
 		if (!executor) throw new Error(`No '${logic.mode === "stream" ? "streamText" : "generateText"}' executor provided.`);
 		const requestWithTools = {
@@ -596,6 +1707,8 @@ function bindTextLogic(logic, runCtx) {
 			request: agentRequest
 		}, self);
 		try {
+			const callKey = id !== "" ? runCtx.callKey?.(id, self) : void 0;
+			await runCtx.awaitJournal?.();
 			const raw = await executor(requestWithTools, {
 				onChunk: (chunk) => {
 					runCtx.emitTrace?.({
@@ -606,7 +1719,8 @@ function bindTextLogic(logic, runCtx) {
 				},
 				signal,
 				...runCtx.runId !== void 0 ? { runId: runCtx.runId } : {},
-				...id !== "" ? { requestId: id } : {}
+				...id !== "" ? { requestId: id } : {},
+				...callKey !== void 0 ? { callKey } : {}
 			});
 			const output = await normalizeGeneratorResult(raw, id, {
 				request,
@@ -618,9 +1732,21 @@ function bindTextLogic(logic, runCtx) {
 					}, self);
 				}
 			});
+			const responseMessages = raw?.messages;
+			if (Array.isArray(responseMessages) && responseMessages.length > 0) {
+				const parent = invokingActorOf(self, runCtx);
+				const event = {
+					type: AGENT_MESSAGES_EVENT_TYPE,
+					request: request.name,
+					actorId: id,
+					messages: responseMessages
+				};
+				if ((parent?.getSnapshot())?.can(event)) parent?.send(event);
+			}
 			const rawReasoning = raw?.reasoning;
 			const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
 			const usage = getCallUsage(raw);
+			const finishReason = getCallFinishReason(raw);
 			if (usage) runCtx.recordUsage?.(usage, {
 				kind: "text",
 				...id !== "" ? { id } : {},
@@ -634,7 +1760,8 @@ function bindTextLogic(logic, runCtx) {
 				output,
 				raw,
 				...reasoning !== void 0 ? { reasoning } : {},
-				...usage !== void 0 ? { usage } : {}
+				...usage !== void 0 ? { usage } : {},
+				...finishReason !== void 0 ? { finishReason } : {}
 			}, self);
 			return { output };
 		} catch (error) {
@@ -656,15 +1783,20 @@ function createCountingDecide(runCtx, self) {
 		}, self);
 		try {
 			const { id } = selfIdAndSrc(self);
+			const invokeCallKey = id !== "" ? runCtx.callKey?.(id, self) : void 0;
+			const callKey = invokeCallKey === void 0 ? void 0 : `${invokeCallKey}.${attemptRequest.attempts?.length ?? 0}`;
+			await runCtx.awaitJournal?.();
 			const result = await runCtx.decide(runCtx.runId !== void 0 ? {
 				...attemptRequest,
 				runId: runCtx.runId
 			} : attemptRequest, {
 				...info,
 				...runCtx.runId !== void 0 ? { runId: runCtx.runId } : {},
-				...info?.requestId === void 0 && id !== "" ? { requestId: id } : {}
+				...info?.requestId === void 0 && id !== "" ? { requestId: id } : {},
+				...info?.callKey === void 0 && callKey !== void 0 ? { callKey } : {}
 			});
 			const usage = getCallUsage(result);
+			const finishReason = getCallFinishReason(result);
 			if (usage) {
 				const { src } = selfIdAndSrc(self);
 				runCtx.recordUsage?.(usage, {
@@ -679,7 +1811,8 @@ function createCountingDecide(runCtx, self) {
 				request: attemptRequest,
 				output: result.event,
 				raw: result,
-				...usage !== void 0 ? { usage } : {}
+				...usage !== void 0 ? { usage } : {},
+				...finishReason !== void 0 ? { finishReason } : {}
 			}, self);
 			return result;
 		} catch (error) {
@@ -719,9 +1852,12 @@ function bindDecisionLogic(logic, runCtx) {
 			schemas: runCtx.schemas,
 			eventTypes: declaredEventTypes
 		}) : [];
+		const lowered = logic.request(input);
 		const chosen = await resolveDecision({
-			...logic.request(input),
+			...lowered,
 			id,
+			name: lowered.name ?? id,
+			input,
 			events
 		}, { decide: createCountingDecide(runCtx, self) }, {
 			maxRetries: logic.maxRetries,
@@ -826,19 +1962,26 @@ function provideBindContext(machine, executors, options) {
 		}) : void 0,
 		consumeModelCall: () => {},
 		recordUsage: (usage, source, self) => {
-			deliverUsageEvent(usage, source ?? {}, () => self?._parent);
+			deliverUsageEvent({
+				type: AGENT_USAGE_EVENT_TYPE,
+				...source,
+				usage
+			}, () => self?._parent);
 		},
 		actorHolder: { actorRef: void 0 },
 		schemas: getRegisteredAgentExecutionOptions(machine).schemas
 	};
 }
 /**
-* The single reserved-`@agent.usage` delivery seam, shared by both bind paths:
-* after a bound call settles with reported usage, send the event to the machine
-* actor `resolveActorRef` names — the run's root actor on the `runAgent` path,
+* The single reserved-`@agent.usage` DELIVERY seam, shared by both bind paths:
+* after a bound call settles with reported usage, send the prebuilt `event` to
+* the machine actor `resolveActorRef` names — the run's root actor on the `runAgent` path,
 * the settling request actor's `self._parent` (always the invoking machine
 * under a live `createActor` tree) on the `provideExecutors` path.
 *
+* Journaling is separate and unconditional (see `recordUsage`): a call's tokens
+* are recorded in the event log whether or not the machine reacts to them.
+*
 * Gating is identical on both: the target snapshot must be active, must declare
 * an `'@agent.usage'` transition — explicitly, or through a catch-all
 * `on: { '*' }` (see {@link declaresUsageTransition}) — and must be able to
@@ -851,16 +1994,11 @@ function provideBindContext(machine, executors, options) {
 * here, so an invoked child machine that was not itself passed through
 * `provideExecutors` reports nothing. @internal
 */
-function deliverUsageEvent(usage, source, resolveActorRef, onDropped) {
+function deliverUsageEvent(event, resolveActorRef, onDropped) {
 	const actorRef = resolveActorRef();
 	if (!actorRef) return;
 	const snapshot = actorRef.getSnapshot();
 	if (snapshot?.status !== "active" || !declaresUsageTransition(snapshot)) return;
-	const event = {
-		type: AGENT_USAGE_EVENT_TYPE,
-		...source,
-		usage
-	};
 	if (onDropped?.(event)) return;
 	if (!snapshot.can(event)) return;
 	actorRef.send(event);
@@ -993,47 +2131,47 @@ function rebindChildMachine(childMachine, runCtx, visited, ctxFor) {
 * lives in an adapter — use `createAiSdkExecutors` from '@statelyai/agent/ai-sdk'.
 */
 async function runAgent(machine, options) {
-	return createAgentSession(machine, options, { oneShot: true }).settled();
+	const store = options.store;
+	if (store === void 0) return createAgentSession(machine, options).settled();
+	const threadId = options.threadId;
+	if (threadId === void 0 || threadId === "") throw new AgentError("missing-thread-id", "runAgent: `threadId` is required when `store` is given — it names the log thread to read and append to.");
+	if (options.events !== void 0) {
+		const storedThread = await store.read(threadId);
+		if (storedThread.length !== options.events.length) throw new AgentEventLogConflictError(threadId, options.events.length, storedThread.length);
+		assertThreadMatchesEvents(threadId, storedThread, options.events);
+		return createAgentSession(machine, options).settled();
+	}
+	const stored = await store.read(threadId);
+	return createAgentSession(machine, stored.length > 0 ? {
+		...options,
+		events: stored
+	} : options).settled();
 }
 /**
-* Session mode: {@link runAgent}'s engine with a long-lived actor. Use it when
-* the agent is a *session* fed by external events (chat turns, device or
-* timer events, a socket) rather than a one-shot job — you keep the log,
-* budget, traces, and idle semantics that bare `provideExecutors` +
-* `createActor` would forfeit.
-*
-* ```ts
-* const session = createAgentActor(machine, { input, executors });
-* let result = await session.settled();          // first quiescence
-* while (result.status === "idle") {
-*   session.actor.send(await nextUserEvent(result.snapshot));
-*   result = await session.settled();            // next quiescence, same log
-* }
-* session.stop();
-* ```
-*
-* Accepts the same options as {@link runAgent} (including `snapshot`/`events`
-* resume). Not yet supported in session mode: `getRequests` re-interpretation
-* across cycles behaves per-cycle exactly as in `runAgent`.
+* Entry-by-entry check that the caller's `events` IS the store's thread. Equal
+* lengths prove nothing: a fork, a rolled-back replay, or a concurrent writer
+* that appended and truncated all produce a divergent log of the same size,
+* and appending this run's entries onto it would splice two lineages together.
 */
-function createAgentActor(machine, options) {
-	return createAgentSession(machine, options, { oneShot: false });
+function assertThreadMatchesEvents(threadId, stored, events) {
+	for (let index = 0; index < stored.length; index++) {
+		const storedEntry = stored[index];
+		const givenEntry = events[index];
+		const storedHash = storedEntry.verification?.stateHash;
+		const givenHash = givenEntry.verification?.stateHash;
+		if (!(storedEntry.id === givenEntry.id && storedEntry.index === givenEntry.index && canonicalEventJson(storedEntry.event) === canonicalEventJson(givenEntry.event) && (storedHash === void 0 || givenHash === void 0 || storedHash === givenHash))) throw new AgentError("event-log-conflict", `runAgent: the given \`events\` diverge from thread "${threadId}" at index ${index} (stored entry '${storedEntry.id}', given '${givenEntry.id}') — the log passed in is not this thread's log.`);
+	}
 }
-function createAgentSession(machine, options, lifecycle) {
+function createAgentSession(machine, options) {
 	const maxModelCalls = options.maxModelCalls ?? 100;
 	let modelCallCount = 0;
 	let budgetExceeded = false;
 	let warnedNonSerializable = false;
-	let warnedHeuristicIdle = false;
 	const runId = `run_${nextRunAgentTraceId++}`;
 	let traceSeq = 0;
 	const resolvedInput = resolveMachineInput(machine, options.input);
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
 	const machineVersion = resolveMachineVersion(machine);
-	const agentMeta = {
-		machineId,
-		version: machineVersion
-	};
 	const onTrace = createTraceDispatch({
 		onTrace: (payload) => {
 			options.onTrace?.({
@@ -1058,25 +2196,109 @@ function createAgentSession(machine, options, lifecycle) {
 		}
 		modelCallCount += 1;
 	};
-	const tokenTotals = {};
 	const cycleGate = { isResolved: () => false };
-	const recordUsage = (usage, source = {}) => {
-		for (const field of AGENT_USAGE_TOKEN_FIELDS) {
-			const value = usage[field];
-			if (typeof value === "number" && Number.isFinite(value)) tokenTotals[field] = (tokenTotals[field] ?? 0) + value;
-		}
-		deliverUsageEvent(usage, source, () => actorHolder.actorRef, (event) => {
-			if (!cycleGate.isResolved()) return false;
-			onTrace({
-				type: "usage.dropped",
-				event,
-				reason: "settled"
+	const logEntries = [];
+	const store = options.store;
+	const threadId = options.threadId;
+	if (store !== void 0 && (threadId === void 0 || threadId === "")) throw new AgentError("missing-thread-id", "runAgent: `threadId` is required when `store` is given — it names the log thread to read and append to.");
+	let journalChain = Promise.resolve();
+	let journalPending = 0;
+	let journalError;
+	const journalEntry = (entry) => {
+		if (store === void 0) return;
+		journalPending++;
+		journalChain = journalChain.then(async () => {
+			if (journalError !== void 0) return;
+			await store.append({
+				threadId,
+				expectedIndex: entry.index,
+				entries: [entry]
 			});
-			return true;
+		}).catch((error) => {
+			journalError ??= error;
+			failRunOnJournalError(error);
+		}).finally(() => {
+			journalPending--;
 		});
 	};
+	/**
+	* Every journal write ISSUED SO FAR, including the stragglers appended after
+	* the run settled. Re-reads the chain tail until it stops moving, so a write
+	* queued while an earlier one was in flight is covered too. Never rejects: a
+	* failed write already settled the run with `cause: 'journal'`.
+	*/
+	const drainJournal = async () => {
+		if (store === void 0) return;
+		let tail = journalChain;
+		for (;;) {
+			await tail;
+			if (journalPending === 0 && journalChain === tail) return;
+			tail = journalChain;
+		}
+	};
+	/** The barrier: settle the pending chain, then surface any failure. */
+	const awaitJournal = async () => {
+		if (store === void 0) return;
+		while (journalPending > 0) await journalChain;
+		if (journalError !== void 0) throw journalError;
+	};
+	const failRunOnJournalError = (error) => {
+		if (settled) return;
+		settle({
+			status: "error",
+			cause: "journal",
+			error,
+			snapshot: actor.getSnapshot()
+		});
+	};
+	let resumedLogLength = 0;
+	let logExecutionId;
+	const verificationEnabled = options.verification !== false;
+	let lastRootSnapshot;
+	let logMachine = machine;
+	let loggingEnabled = true;
+	const appendLogEntry = (event, snapshot) => {
+		if (!loggingEnabled) return;
+		const entry = createReplayEntry(logMachine, logEntries, event, {
+			machineVersion,
+			verification: verificationEnabled,
+			...verificationEnabled && snapshot !== void 0 ? { snapshot } : {}
+		});
+		logEntries.push(entry);
+		journalEntry(entry);
+		options.onEvent?.(entry);
+		return entry;
+	};
+	const usageEntrySnapshot = () => {
+		const current = lastRootSnapshot;
+		if (current && (current.status !== "active" || !declaresUsageTransition(current))) return current;
+	};
+	const recordUsage = (usage, source = {}) => {
+		const event = {
+			type: AGENT_USAGE_EVENT_TYPE,
+			...source,
+			usage
+		};
+		const journal = { event };
+		pendingUsageJournal = journal;
+		try {
+			deliverUsageEvent(event, () => actorHolder.actorRef, (dropped) => {
+				if (!cycleGate.isResolved()) return false;
+				onTrace({
+					type: "usage.dropped",
+					event: dropped,
+					reason: "settled"
+				});
+				return true;
+			});
+		} finally {
+			pendingUsageJournal = void 0;
+		}
+		if (journal.entry === void 0) appendLogEntry(event, usageEntrySnapshot());
+	};
+	let pendingUsageJournal;
 	const runUsage = () => ({
-		...tokenTotals,
+		...getUsageFromEvents(logEntries.slice(resumedLogLength)),
 		modelCalls: modelCallCount
 	});
 	const warnNonSerializableContext = (snapshot) => {
@@ -1092,18 +2314,23 @@ function createAgentSession(machine, options, lifecycle) {
 		console.warn(`runAgent: context holds value(s) that will not survive snapshot persist/resume (JSON round-trip): ${offending.join(", ")}. Persist only JSON-serializable context, or convert these before the run settles.`);
 	};
 	const provided = machine.provide({ actors: options.actors });
+	logMachine = provided;
 	const effectiveSources = provided.sources.actors;
-	assertBindable(provided, effectiveSources, options.executors ?? {});
-	if (options.getRequests && !options.executors?.generateText && !options.executors?.decide) throw new Error("runAgent: 'getRequests' requires a 'generateText' and/or 'decide' executor — the returned requests run through them.");
+	const executors = {
+		...getRegisteredAgentExecutionOptions(machine).models?.[DEFAULT_AGENT_EXECUTORS]?.(),
+		...options.executors
+	};
+	assertBindable(provided, effectiveSources, executors);
 	const actorHolder = { actorRef: void 0 };
 	const runCtx = {
-		generateText: options.executors?.generateText,
-		streamText: options.executors?.streamText,
-		decide: options.executors?.decide,
+		generateText: executors.generateText,
+		streamText: executors.streamText,
+		decide: executors.decide,
 		emitTrace: onTrace,
 		consumeModelCall,
 		recordUsage,
 		actorHolder,
+		awaitJournal,
 		runId,
 		schemas: getRegisteredAgentExecutionOptions(machine).schemas
 	};
@@ -1135,103 +2362,178 @@ function createAgentSession(machine, options, lifecycle) {
 		}
 	}
 	const boundMachine = provided.provide({ actors: wrappedSources });
-	const declaredIdlePredicate = options.isIdle ?? getMachineIdlePredicate(machine);
-	const isIdle = declaredIdlePredicate ?? (() => false);
-	const machineDeclaresMigrate = typeof machine.config.migrate === "function";
+	const isIdle = getMachineIdlePredicate(machine) ?? isAgentIdle;
+	const isIntentionalIdle = (snapshot) => isIdle(snapshot) || collectPendingUserInputs(snapshot).length > 0;
+	const resumeEvents = options.events;
 	let effectiveSnapshot = options.snapshot;
-	if (effectiveSnapshot !== void 0) {
-		const from = effectiveSnapshot.agentMeta?.version ?? effectiveSnapshot.version;
-		if (from !== void 0 && from !== machineVersion && !(machineDeclaresMigrate && !options.migrateSnapshot)) {
-			const info = {
-				from,
-				to: machineVersion
-			};
-			if (options.migrateSnapshot) effectiveSnapshot = options.migrateSnapshot(effectiveSnapshot, info);
-			else {
-				const mode = options.onVersionMismatch ?? "throw";
-				if (mode === "throw") throw new AgentSnapshotVersionMismatchError(from, machineVersion, machineId);
-				if (mode === "warn") console.warn(`runAgent: resuming a snapshot stamped with machine version '${from}' against machine '${machineId}' at version '${machineVersion}'. Structural changes may not resume cleanly.`);
+	/** Deferred until after the illegal-resume check, so a rejected resume emits no entries. */
+	let seedInitEntry;
+	const restoredPersistedSnapshot = () => {
+		try {
+			const restored = logMachine.restoreSnapshot(options.snapshot);
+			return logMachine.getPersistedSnapshot(restored);
+		} catch {
+			return;
+		}
+	};
+	/**
+	* Appends the log's reserved first entry, trying each candidate `init` in
+	* turn and, for each, an unverified entry if the hash cannot be computed.
+	* A machine or snapshot that defeats every attempt leaves the run WITHOUT a
+	* log rather than failing it: `runAgent` predates the log, and an exotic
+	* machine that cannot be folded must still run.
+	*/
+	const appendInitEntry = (candidates, metadata) => {
+		for (const init of candidates) for (const verification of verificationEnabled ? [true, false] : [false]) try {
+			const entry = initEntry(logMachine, init, {
+				machineVersion,
+				verification,
+				metadata
+			});
+			logEntries.push(entry);
+			journalEntry(entry);
+			options.onEvent?.(entry);
+			return;
+		} catch {}
+		loggingEnabled = false;
+	};
+	/** Init forms for a snapshot resume, most faithful first. */
+	const snapshotInitCandidates = () => {
+		const restored = restoredPersistedSnapshot();
+		return [...restored !== void 0 ? [{ snapshot: restored }] : [], { snapshot: options.snapshot }];
+	};
+	if (resumeEvents !== void 0 && resumeEvents.length > 0) {
+		validateReplayEntries(resumeEvents);
+		const tail = resumeEvents[resumeEvents.length - 1];
+		const inheritedExecutionId = getLogExecutionId(resumeEvents);
+		if (resumeEvents[0].machineId !== machineId) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
+			machineId,
+			machineVersion
+		}, {
+			machineId: resumeEvents[0].machineId,
+			machineVersion: tail.machineVersion
+		});
+		if (tail.machineVersion === machineVersion) {
+			logEntries.push(...resumeEvents);
+			resumedLogLength = logEntries.length;
+			logExecutionId = inheritedExecutionId;
+			const cachedMeta = readAgentMeta(options.snapshot);
+			const tailStateHash = tail.verification?.stateHash;
+			if (!(options.snapshot !== void 0 && inheritedExecutionId !== void 0 && cachedMeta?.logId === inheritedExecutionId && cachedMeta.logIndex === resumeEvents.length && tailStateHash !== void 0 && hashResumeSnapshot(options.snapshot) === tailStateHash)) {
+				const cachedIndex = cachedMeta?.logIndex;
+				if (options.snapshot !== void 0 && typeof cachedIndex === "number" && cachedIndex >= 1 && cachedIndex <= resumeEvents.length && resumeEvents[cachedIndex - 1].verification?.stateHash !== void 0) {
+					const expected = getSnapshotStateHash(replay(logMachine, resumeEvents.slice(0, cachedIndex), {
+						machineVersion,
+						verify: false
+					}).persistedSnapshot);
+					const actual = hashResumeSnapshot(options.snapshot);
+					if (expected !== actual) throw new AgentSnapshotDivergedError(expected, actual, cachedIndex);
+				}
+				effectiveSnapshot = replay(logMachine, resumeEvents, {
+					machineVersion,
+					verify: true
+				}).persistedSnapshot;
 			}
+		} else {
+			if (options.snapshot === void 0) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
+				machineId,
+				machineVersion
+			}, {
+				machineId: tail.machineId,
+				machineVersion: tail.machineVersion
+			});
+			const bridgeMeta = readAgentMeta(options.snapshot);
+			if (inheritedExecutionId === void 0 || bridgeMeta?.logId !== inheritedExecutionId) throw new AgentMachineVersionMismatchError(tail.id, tail.index, {
+				machineId,
+				machineVersion
+			}, {
+				machineId: tail.machineId,
+				machineVersion: tail.machineVersion
+			});
+			const bridgeTailHash = tail.verification?.stateHash;
+			const bridgeSnapshotHash = hashResumeSnapshot(options.snapshot);
+			if (bridgeMeta.logIndex !== resumeEvents.length) throw new AgentSnapshotDivergedError(bridgeTailHash ?? "(unrecorded)", bridgeSnapshotHash, resumeEvents.length);
+			if (bridgeTailHash !== void 0 && bridgeSnapshotHash !== bridgeTailHash) throw new AgentSnapshotDivergedError(bridgeTailHash, bridgeSnapshotHash, resumeEvents.length);
+			logExecutionId = inheritedExecutionId;
+			const migratedFrom = {
+				machineVersion: tail.machineVersion,
+				logIndex: resumeEvents.length
+			};
+			seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
+				...logExecutionId !== void 0 ? { executionId: logExecutionId } : {},
+				migratedFrom
+			});
 		}
+	} else if (options.snapshot !== void 0) {
+		logExecutionId = crypto.randomUUID();
+		seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), { executionId: logExecutionId });
+	} else {
+		logExecutionId = crypto.randomUUID();
+		seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], { executionId: logExecutionId });
 	}
-	const resumeEvents = options.events;
-	if (effectiveSnapshot === void 0 && options.events !== void 0 && options.events[0]?.event.type === "@agent.init") {
-		const { snapshot: replayedSnapshot } = replay(machine, resumeEvents, { machineVersion });
-		effectiveSnapshot = machine.getPersistedSnapshot(replayedSnapshot);
-	}
-	const machineOwnVersion = machine.version;
-	if (!machineDeclaresMigrate && effectiveSnapshot !== void 0 && effectiveSnapshot.version !== machineOwnVersion) {
-		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 = getAgentMessages(effectiveSnapshot);
-	const messages = typeof options.messages === "function" ? [...options.messages([...priorMessages])] : [...priorMessages, ...options.messages ?? []];
-	const stampSettledSnapshot = (snapshot) => {
-		if (!snapshot || typeof snapshot !== "object") return;
-		snapshot.agentMeta = agentMeta;
-		if (!options.getRequests && !options.messages && messages.length === 0) return;
-		snapshot.messages = [...messages];
-	};
-	if (effectiveSnapshot !== void 0 && options.event !== void 0) {
-		const acceptedTypes = getAcceptedEvents(createActor(boundMachine, { snapshot: effectiveSnapshot }).getSnapshot(), { schemas: runCtx.schemas }).map((descriptor) => descriptor.type);
-		const eventType = options.event.type;
-		if (!acceptedTypes.includes(eventType)) throw new AgentIllegalResumeEventError(eventType, acceptedTypes);
-	}
-	const replayEvents = [...resumeEvents ?? []];
-	validateReplayEntries(replayEvents, {
-		machineId,
-		machineVersion
-	}, "runAgent events");
-	const replayEventIds = new Set(replayEvents.map((entry) => entry.id));
-	const hasCompleteReplayHistory = replayEvents[0]?.event.type === "@agent.init" || effectiveSnapshot === void 0 && replayEvents.length === 0;
-	const appendReplayEvent = (event) => {
-		const entry = createReplayEntry(machine, replayEvents, event, {
-			machineVersion,
-			verification: hasCompleteReplayHistory
-		});
-		if (replayEventIds.has(entry.id)) throw new Error(`runAgent generated duplicate event id '${entry.id}'.`);
-		replayEventIds.add(entry.id);
-		replayEvents.push(entry);
-		options.onEvent?.(entry);
-		return entry;
+	const resumedHistory = [...logEntries];
+	const siteCallCounts = /* @__PURE__ */ new Map();
+	const mintedCallKeys = /* @__PURE__ */ new WeakMap();
+	runCtx.callKey = (siteId, self) => {
+		if (logExecutionId === void 0) return;
+		const memoized = self === void 0 ? void 0 : mintedCallKeys.get(self);
+		if (memoized !== void 0) return memoized;
+		const startedHere = siteCallCounts.get(siteId) ?? 0;
+		siteCallCounts.set(siteId, startedHere + 1);
+		const key = `${logExecutionId}:${siteId}#${agentCallOccurrence(resumedHistory, siteId) + startedHere}`;
+		if (self !== void 0) mintedCallKeys.set(self, key);
+		return key;
 	};
-	if (replayEvents.length === 0 && effectiveSnapshot === void 0) {
-		const entry = initEntry(machine, resolvedInput, { machineVersion });
-		replayEventIds.add(entry.id);
-		replayEvents.push(entry);
-		options.onEvent?.(entry);
-	}
+	const resumeEventToSend = options.event;
+	let ignoredEvent;
+	seedInitEntry?.();
 	let settled = false;
-	let finalized = false;
+	let journalAtSettle;
 	cycleGate.isResolved = () => settled;
 	let lastResult;
 	const waiters = [];
 	let idleTimer;
 	let actor;
-	let deliveringResumeEvent = options.event !== void 0;
+	let actorStarted = false;
+	let deliveringResumeEvent = resumeEventToSend !== void 0;
 	const settle = (outcome) => {
 		if (settled) return;
 		settled = true;
+		let persistedSnapshot;
+		let persistenceError;
+		if (actorStarted && outcome.status !== "done") try {
+			persistedSnapshot = actor.getPersistedSnapshot();
+		} catch (error) {
+			persistenceError = error;
+		}
+		const logIndexAtSettle = logEntries.length;
+		journalAtSettle = journalChain;
+		const persist = () => {
+			if (persistenceError !== void 0) throw persistenceError;
+			persistedSnapshot ??= actor.getPersistedSnapshot();
+			persistedSnapshot.agentMeta = {
+				machineId,
+				version: machineVersion,
+				...logExecutionId !== void 0 ? { logId: logExecutionId } : {},
+				logIndex: logIndexAtSettle
+			};
+			return persistedSnapshot;
+		};
 		const result = {
 			...outcome,
-			events: [...replayEvents],
-			usage: runUsage()
+			events: [...logEntries],
+			persist,
+			drain: drainJournal,
+			usage: runUsage(),
+			...ignoredEvent !== void 0 ? { ignored: ignoredEvent } : {}
 		};
 		if (idleTimer !== void 0) clearTimeout(idleTimer);
-		stampSettledSnapshot(result.snapshot);
-		if ("persistedSnapshot" in result) stampSettledSnapshot(result.persistedSnapshot);
 		onTrace({
 			type: "run.end",
 			...outcome
 		});
-		if (lifecycle.oneShot || result.status !== "idle") {
-			finalized = true;
-			if (options.signal) options.signal.removeEventListener("abort", onAbort);
-			actor.stop();
-		}
+		if (options.signal) options.signal.removeEventListener("abort", onAbort);
+		actor.stop();
 		lastResult = result;
 		for (const resolve of waiters.splice(0)) resolve(result);
 	};
@@ -1245,89 +2547,21 @@ function createAgentSession(machine, options, lifecycle) {
 	};
 	const settleIdle = (current) => {
 		warnNonSerializableContext(current);
-		const pendingUserInputs = userInputIsPlaceholder ? collectPendingUserInputs(current) : [];
-		settle({
-			status: "idle",
-			snapshot: current,
-			persistedSnapshot: actor.getPersistedSnapshot(),
-			...pendingUserInputs.length > 0 ? { pendingUserInputs } : {}
-		});
-	};
-	let interpreting = false;
-	let interpretSeq = 0;
-	const appendToLog = (...items) => {
-		messages.push(...items);
-		if (options.onMessage) {
-			const info = {
-				runId,
-				machineId,
-				machineVersion
-			};
-			for (const item of items) options.onMessage(item, info);
-		}
-	};
-	const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
-	const settleInterpretError = (error) => {
-		settle({
-			status: "error",
-			cause: runErrorCause(error),
-			error,
-			snapshot: actor.getSnapshot()
-		});
-	};
-	const passDeps = {
-		getSnapshot: () => actor.getSnapshot(),
-		send: (event) => actor.send(event),
-		isSettled: () => settled,
-		messages,
-		appendToLog,
-		generateText: runCtx.generateText,
-		decide: runCtx.decide ? createCountingDecide(runCtx, void 0) : void 0,
-		consumeModelCall,
-		recordUsage,
-		nextRequestId: () => `interpret_${++interpretSeq}`,
-		onTrace,
-		schemas: runCtx.schemas,
-		signal: options.signal
-	};
-	const maybeInterpret = (snapshot) => {
-		if (!options.getRequests || settled) return false;
-		if (interpreting) return true;
-		let requested;
-		try {
-			requested = options.getRequests(snapshot, { messages });
-		} catch (error) {
-			settleInterpretError(error);
-			return true;
-		}
-		const requests = (Array.isArray(requested) ? requested : requested ? [requested] : []).filter((stateRequest) => Boolean(stateRequest));
-		if (requests.length === 0) return false;
-		interpreting = true;
-		runStateRequestPass(requests, passDeps).then(({ sentAny }) => {
-			if (settled || sentAny) return;
-			const current = actor.getSnapshot();
-			if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) settleIdle(current);
-		}).catch((error) => settleInterpretError(error)).finally(() => {
-			interpreting = false;
-			if (!settled) scheduleIdleCheck();
+		const pendingUserInputs = userInputIsPlaceholder ? collectPendingUserInputs(current) : [];
+		settle({
+			status: "idle",
+			snapshot: current,
+			...pendingUserInputs.length > 0 ? { pendingUserInputs } : {}
 		});
-		return true;
 	};
+	const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
 	const scheduleIdleCheck = () => {
 		if (idleTimer !== void 0) clearTimeout(idleTimer);
 		idleTimer = setTimeout(() => {
 			idleTimer = void 0;
 			if (settled) return;
 			const current = actor.getSnapshot();
-			if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
-				if (!maybeInterpret(current)) {
-					if (!declaredIdlePredicate && current.status === "active" && !warnedHeuristicIdle && process.env.NODE_ENV !== "production") {
-						warnedHeuristicIdle = true;
-						console.warn("[@statelyai/agent] runAgent settled idle via the timing heuristic (no idle predicate declared). This is best-effort; for deterministic idle detection, declare setupAgent({ isIdle }) or pass runAgent(machine, { isIdle }), e.g. (s) => s.hasTag('waiting').");
-					}
-					settleIdle(current);
-				}
-			}
+			if (isIntentionalIdle(current) && isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) settleIdle(current);
 		}, 0);
 	};
 	actor = createActor(boundMachine, {
@@ -1337,20 +2571,16 @@ function createAgentSession(machine, options, lifecycle) {
 			if (typeof options.inspect === "function") options.inspect(event);
 			else options.inspect?.next?.(event);
 			if (event.type !== "@xstate.transition" || event.actorRef !== actor.ref) return;
-			if (settled) {
-				if (finalized) return;
-				settled = false;
-				lastResult = void 0;
-			}
+			if (settled) return;
 			const snapshot = event.snapshot;
-			let eventId;
-			if (event.event.type !== "@xstate.init" && (event.sourceRef !== event.actorRef || event.event.type === "xstate.timer")) eventId = appendReplayEvent(event.event).id;
-			else if (event.event.type === "@xstate.init") eventId = replayEvents[0]?.event.type === "@agent.init" ? replayEvents[0].id : void 0;
+			lastRootSnapshot = snapshot;
+			if (resumeEventToSend !== void 0 && event.event === resumeEventToSend && event.microsteps.length === 0 && event.actions.length === 0 && event.sent.length === 0) ignoredEvent = resumeEventToSend;
+			if (pendingUsageJournal !== void 0 && event.event === pendingUsageJournal.event) pendingUsageJournal.entry = appendLogEntry(event.event, snapshot);
+			else if (event.event.type !== "@xstate.init" && (event.sourceRef !== event.actorRef || event.event.type === "xstate.timer")) appendLogEntry(event.event, snapshot);
 			onTrace({
 				type: "machine.transition",
 				snapshot,
-				event: event.event,
-				...eventId !== void 0 ? { eventId } : {}
+				event: event.event
 			});
 			if (snapshot.status === "done") {
 				settle({
@@ -1378,13 +2608,12 @@ function createAgentSession(machine, options, lifecycle) {
 				});
 				return;
 			}
-			if (!deliveringResumeEvent && isIdle(snapshot) && isIdleSnapshot(snapshot, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+			if (!deliveringResumeEvent && isIntentionalIdle(snapshot) && isIdleSnapshot(snapshot, { ignoreUserInputChildren: userInputIsPlaceholder })) {
 				queueMicrotask(() => {
 					if (settled) return;
 					const current = actor.getSnapshot();
-					if (isIdle(current) && isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
-						if (!maybeInterpret(current)) settleIdle(current);
-					} else scheduleIdleCheck();
+					if (isIntentionalIdle(current) && isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) settleIdle(current);
+					else scheduleIdleCheck();
 				});
 				return;
 			}
@@ -1400,19 +2629,13 @@ function createAgentSession(machine, options, lifecycle) {
 		});
 	});
 	for (const [type, handler] of Object.entries(options.on ?? {})) if (typeof handler === "function") actor.on(type, handler);
-	const sessionApi = {
-		actor,
-		get events() {
-			return replayEvents;
-		},
-		usage: runUsage,
-		settled: () => settled && lastResult !== void 0 ? Promise.resolve(lastResult) : new Promise((resolve) => {
+	const sessionApi = { settled: async () => {
+		const result = settled && lastResult !== void 0 ? lastResult : await new Promise((resolve) => {
 			waiters.push(resolve);
-		}),
-		stop: () => {
-			actor.stop();
-		}
-	};
+		});
+		await journalAtSettle;
+		return result;
+	} };
 	if (options.signal) {
 		if (options.signal.aborted) {
 			settle({
@@ -1429,47 +2652,38 @@ function createAgentSession(machine, options, lifecycle) {
 		type: "run.start",
 		...resolvedInput !== void 0 ? { input: resolvedInput } : {},
 		...effectiveSnapshot !== void 0 ? { snapshot: effectiveSnapshot } : {},
-		...options.event !== void 0 ? { event: options.event } : {}
+		...resumeEventToSend !== void 0 ? { event: resumeEventToSend } : {}
 	});
+	actorStarted = true;
 	actor.start();
-	if (options.event) {
+	if (!settled) {
+		const startedSnapshot = actor.getSnapshot();
+		lastRootSnapshot ??= startedSnapshot;
+		if (startedSnapshot.status === "done") settle({
+			status: "done",
+			output: startedSnapshot.output,
+			snapshot: startedSnapshot
+		});
+		else if (startedSnapshot.status === "error") settle({
+			status: "error",
+			cause: runErrorCause(startedSnapshot.error),
+			error: startedSnapshot.error,
+			snapshot: startedSnapshot
+		});
+		else if (startedSnapshot.status === "stopped") settle({
+			status: "error",
+			cause: "stopped",
+			error: /* @__PURE__ */ new Error("Actor stopped externally."),
+			snapshot: startedSnapshot
+		});
+	}
+	if (resumeEventToSend && !settled) {
 		deliveringResumeEvent = false;
-		actor.send(options.event);
+		actor.send(resumeEventToSend);
 	}
 	return sessionApi;
 }
 /**
-* Runs an agent machine to a **final state**, for run-to-done flows where an
-* idle pause is unexpected. Wraps {@link runAgent}:
-*
-* - `done` → resolves with the done result: `result.output` (the machine's
-*   `OutputFrom`) plus metadata — `result.snapshot`, the replayable
-*   `result.events`, and the aggregated `result.usage` — the same shape
-*   `generateText` users expect (`text` + call metadata).
-* - `idle` → throws {@link AgentIdleError} carrying the idle snapshot and the
-*   event types that could resume it.
-* - `error` → throws `result.error` when it is an `Error`; otherwise wraps it
-*   in an `Error` whose `.cause` is the {@link RunAgentErrorCause} and whose
-*   `.error` is the raw thrown value.
-*
-* Use {@link runAgent} directly when idle is an expected outcome you handle
-* (human-in-the-loop, resumable flows); use `generateResult` when the
-* machine is meant to run straight through to a final state.
-*/
-async function generateResult(machine, options) {
-	const result = await runAgent(machine, options);
-	if (result.status === "done") return result;
-	if (result.status === "idle") {
-		const acceptedTypes = getAcceptedEvents(result.snapshot, { schemas: getRegisteredAgentExecutionOptions(machine).schemas }).map((descriptor) => descriptor.type);
-		throw new AgentIdleError(result.snapshot, acceptedTypes);
-	}
-	if (result.error instanceof Error) throw result.error;
-	const wrapped = /* @__PURE__ */ new Error(`generateResult: run failed with cause '${result.cause}'.`);
-	wrapped.cause = result.cause;
-	wrapped.error = result.error;
-	throw wrapped;
-}
-/**
 * Wraps a `(snapshot, actorRef) => void` handler into a function usable as
 * {@link RunAgentOptions.inspect}: it filters the raw inspection stream to
 * `@xstate.transition` events and hands the handler the typed
@@ -1531,6 +2745,24 @@ function isIdleSnapshot(snapshot, { ignoreUserInputChildren }) {
 	})) return false;
 	return !getNextTransitions(snapshot).some((transitionDef) => transitionDef.eventType === "" || transitionDef.eventType.startsWith("xstate.after"));
 }
+/**
+* Default machine-owned idle signal used by {@link runAgent}: an active
+* snapshot that accepts an external event anywhere in its active hierarchy,
+* or declares interaction metadata on an active state.
+*
+* Compose this in `setupAgent({ isIdle })` when the application has additional
+* wait states: `isIdle: (snapshot) => isAgentIdle(snapshot) || snapshot.hasTag('waiting')`.
+* Pending work and active invoked children are checked separately by the
+* runner, so this function only answers whether the state is an intentional
+* external wait.
+*/
+function isAgentIdle(snapshot) {
+	if (snapshot.status !== "active") return false;
+	return snapshot.nodes.some((node) => {
+		const meta = node.meta;
+		return typeof meta === "object" && meta !== null && "interaction" in meta;
+	}) || getAcceptedEvents(snapshot).length > 0;
+}
 function collectPendingUserInputs(snapshot) {
 	const pending = [];
 	for (const [id, child] of Object.entries(snapshot.children ?? {})) {
@@ -1644,6 +2876,124 @@ function createAgentRun(machine, options) {
 		result
 	};
 }
+function requestIdentity(request) {
+	const candidate = request;
+	const id = candidate.id ?? candidate.name ?? "agent.request";
+	return {
+		name: candidate.kind === "text" ? candidate.input?.name ?? id : candidate.name ?? id,
+		id
+	};
+}
+/**
+* Streams one {@link runAgent} call as agent-level events. The machine remains
+* the single artifact; this function only projects its requests, chunks,
+* transitions, emitted events, and terminal result into an async iterable.
+*/
+async function* runAgentStream(machine, options) {
+	const run = createAgentRun(machine, options);
+	for await (const event of run.events) switch (event.type) {
+		case "request.start":
+			yield {
+				kind: "request",
+				phase: "start",
+				...requestIdentity(event.request),
+				request: event.request
+			};
+			break;
+		case "request.end":
+			yield {
+				kind: "request",
+				phase: "end",
+				...requestIdentity(event.request),
+				request: event.request,
+				output: event.output,
+				raw: event.raw
+			};
+			break;
+		case "request.error":
+			yield {
+				kind: "request",
+				phase: "error",
+				...requestIdentity(event.request),
+				request: event.request,
+				error: event.error
+			};
+			break;
+		case "stream.chunk":
+			yield {
+				kind: "chunk",
+				...requestIdentity(event.request),
+				delta: event.chunk
+			};
+			break;
+		case "machine.transition":
+			yield {
+				kind: "transition",
+				value: event.snapshot.value,
+				event: event.event
+			};
+			break;
+		case "emit":
+			yield {
+				kind: "emit",
+				event: event.event
+			};
+			break;
+	}
+	const result = await run.result;
+	if (result.status === "done") yield {
+		kind: "done",
+		result
+	};
+	else if (result.status === "idle") yield {
+		kind: "idle",
+		result
+	};
+	else yield {
+		kind: "error",
+		result
+	};
+}
+//#endregion
+//#region src/run-loop.ts
+function addUsage(total, next) {
+	const merged = { ...total };
+	for (const [key, value] of Object.entries(next)) if (typeof value === "number") merged[key] = (merged[key] ?? 0) + value;
+	return merged;
+}
+/** Drives one machine artifact across as many idle/resume turns as the host
+* supplies. XState snapshots remain the continuation; this helper owns no
+* persistence, retry, tool-loop, or storage policy. */
+async function runAgentLoop(machine, options) {
+	const { onIdle, persist, maxTurns = 100, events: initialEvents, ...runOptions } = options;
+	if (!Number.isInteger(maxTurns) || maxTurns < 0) throw new Error("runAgentLoop: maxTurns must be a non-negative integer.");
+	let usage = { modelCalls: 0 };
+	let snapshot;
+	let event;
+	const stored = options.store !== void 0;
+	let events = initialEvents;
+	for (let turn = 0;; turn++) {
+		const result = await runAgent(machine, {
+			...runOptions,
+			...events ? { events } : {},
+			...snapshot ? {
+				snapshot,
+				event
+			} : {}
+		});
+		events = stored ? void 0 : result.events;
+		usage = addUsage(usage, result.usage);
+		const cumulative = {
+			...result,
+			usage
+		};
+		if (result.status !== "idle" || !onIdle || turn >= maxTurns) return cumulative;
+		snapshot = result.persist();
+		await persist?.(snapshot, result);
+		event = await onIdle(result) ?? void 0;
+		if (!event) return cumulative;
+	}
+}
 //#endregion
 //#region src/provide-executors.ts
 /**
@@ -1788,98 +3138,6 @@ function buildStateIndex(rootConfig) {
 	walk(rootConfig.states, "");
 	return index;
 }
-function childrenOf(index, parentPath) {
-	const out = [];
-	for (const node of index.values()) if (node.parentPath === parentPath) out.push(node);
-	return out;
-}
-function collectTransitionTargets(value, fromNode, index, out) {
-	if (value === void 0 || value === null) return;
-	if (Array.isArray(value)) {
-		for (const item of value) collectTransitionTargets(item, fromNode, index, out);
-		return;
-	}
-	if (typeof value === "function") {
-		out.opaque = true;
-		return;
-	}
-	if (typeof value === "string") {
-		resolveTargetString(value, fromNode, index, out);
-		return;
-	}
-	if (typeof value === "object") {
-		const { target, to } = value;
-		if (target !== void 0) {
-			collectTransitionTargets(target, fromNode, index, out);
-			return;
-		}
-		if (to !== void 0) {
-			collectTransitionTargets(to, fromNode, index, out);
-			return;
-		}
-	}
-}
-function resolveTargetString(target, fromNode, index, out) {
-	if (target.startsWith("#")) {
-		out.opaque = true;
-		return;
-	}
-	const resolved = target.startsWith(".") ? `${fromNode.path}.${target.slice(1)}` : fromNode.parentPath ? `${fromNode.parentPath}.${target}` : target;
-	if (index.has(resolved)) out.targets.push(resolved);
-	else out.opaque = true;
-}
-function outgoingTargets(node, index, staticTargets) {
-	const out = {
-		targets: [],
-		opaque: false
-	};
-	const { config } = node;
-	if (staticTargets) {
-		for (const target of staticTargets[node.path] ?? []) resolveTargetString(target, node, index, out);
-		return out;
-	}
-	for (const value of Object.values(config.on ?? {})) collectTransitionTargets(value, node, index, out);
-	collectTransitionTargets(config.always, node, index, out);
-	collectTransitionTargets(config.choice, node, index, out);
-	for (const value of Object.values(config.after ?? {})) collectTransitionTargets(value, node, index, out);
-	collectTransitionTargets(config.onDone, node, index, out);
-	for (const invoke of node.invokes) {
-		collectTransitionTargets(invoke.onDone, node, index, out);
-		collectTransitionTargets(invoke.onError, node, index, out);
-	}
-	return out;
-}
-function computeReachable(rootConfig, index, staticTargets) {
-	const reachable = /* @__PURE__ */ new Set();
-	const queue = [];
-	const markAncestors = (path) => {
-		let parent = index.get(path)?.parentPath ?? "";
-		while (parent) {
-			reachable.add(parent);
-			parent = index.get(parent)?.parentPath ?? "";
-		}
-	};
-	const enter = (path) => {
-		if (reachable.has(path)) return;
-		const node = index.get(path);
-		if (!node) return;
-		reachable.add(path);
-		queue.push(path);
-		markAncestors(path);
-		if (node.isParallel) for (const child of childrenOf(index, path)) enter(child.path);
-		else if (node.isCompound && node.config.initial) enter(`${path}.${node.config.initial}`);
-	};
-	if (rootConfig.type === "parallel") for (const child of childrenOf(index, "")) enter(child.path);
-	else if (rootConfig.initial) enter(rootConfig.initial);
-	while (queue.length > 0) {
-		const node = index.get(queue.shift());
-		if (!node) continue;
-		const { targets, opaque } = outgoingTargets(node, index, staticTargets);
-		for (const target of targets) enter(target);
-		if (opaque) for (const sibling of childrenOf(index, node.parentPath)) enter(sibling.path);
-	}
-	return reachable;
-}
 function ancestorChain(node, index) {
 	const chain = [];
 	let parent = node.parentPath;
@@ -1901,24 +3159,6 @@ function isDecisionInvoke(src, actors) {
 function isAgentLogicNeedingBinding(src) {
 	return (isTextLogic(src) || isDecisionLogic(src)) && !executorBoundLogics.has(src);
 }
-function readJsonSchema(schema) {
-	if (!schema) return;
-	try {
-		return getJsonSchemaSync(schema);
-	} catch {
-		return;
-	}
-}
-function checkUnreachableStates(ctx) {
-	const out = [];
-	for (const node of ctx.index.values()) if (!ctx.reachable.has(node.path)) out.push({
-		code: "unreachable-state",
-		severity: "error",
-		path: node.path,
-		message: `State '${node.path}' is unreachable: no transition, always, onDone, or onError target (from any reachable state) leads to it. Remove it or add a transition.`
-	});
-	return out;
-}
 function checkDecideWithoutEvents(ctx) {
 	const out = [];
 	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
@@ -1937,17 +3177,6 @@ function checkDecideWithoutEvents(ctx) {
 	}
 	return out;
 }
-function checkUnserializableContext(ctx) {
-	const contextSchema = ctx.schemas?.context;
-	if (!contextSchema) return [];
-	if (readJsonSchema(contextSchema)) return [];
-	return [{
-		code: "unserializable-context",
-		severity: "warning",
-		path: "context",
-		message: "The context schema does not expose a JSON schema (e.g. a `z.custom` without a `jsonSchema` extension, such as a messages array), so its fields cannot be statically checked for JSON persist/resume round-tripping. This is expected for message transcripts; verify any other custom-typed context is JSON-serializable."
-	}];
-}
 function checkDirectObjectSrc(ctx) {
 	const out = [];
 	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
@@ -1963,80 +3192,48 @@ function checkDirectObjectSrc(ctx) {
 	}
 	return out;
 }
-function checkFinalWithoutOutput(ctx) {
-	const outputJson = readJsonSchema(ctx.schemas?.output);
-	const properties = outputJson?.properties;
-	const required = outputJson?.required;
-	if (!(outputJson?.type === "object" && !!properties && Object.keys(properties).length > 0 || Array.isArray(required) && required.length > 0)) return [];
-	if (ctx.config.output !== void 0) return [];
-	const out = [];
-	for (const node of ctx.index.values()) {
-		if (node.parentPath !== "" || !node.isFinal) continue;
-		if (node.config.output === void 0) out.push({
-			code: "final-without-output",
-			severity: "error",
-			path: node.path,
-			message: `The machine declares an output schema, but top-level final state '${node.path}' has no 'output'. Its snapshot output will be undefined and fail the schema. Add an 'output' to this final state (or a root 'output').`
-		});
-	}
-	return out;
-}
-function outputFnReadsEvent(fn) {
-	return /\bevent\s*(?:\.|\?\.|\[)/.test(fn.toString());
-}
-function checkFinalOutputReadsEvent(ctx) {
-	const out = [];
-	for (const node of ctx.index.values()) {
-		if (node.parentPath !== "" || !node.isFinal) continue;
-		const output = node.config.output;
-		if (typeof output !== "function") continue;
-		if (!outputFnReadsEvent(output)) continue;
-		out.push({
-			code: "final-output-reads-event",
-			severity: "warning",
-			path: node.path,
-			message: `Final state '${node.path}' has an 'output' function that reads 'event'. Final-state 'output' functions are evaluated more than once with different events (the entering event, then the machine-done computation) under current xstate behavior, so 'event' is unreliable here. Read 'context' only; capture what you need from the entering event into context in the transition that targets this state. (This guard can relax if xstate guarantees a stable entering event across evaluations.)`
-		});
-	}
-	return out;
-}
-function isBuiltinOrWildcardEvent(eventType) {
-	return eventType === "*" || eventType.includes("*") || eventType.startsWith("xstate.") || eventType.startsWith("done.") || eventType.startsWith("error.");
+function handlesActorError(config) {
+	if (config["onError"] !== void 0) return true;
+	return Object.keys(config.on ?? {}).some((type) => type === "*" || type.startsWith("xstate.error"));
 }
-function checkUndeclaredEvents(ctx) {
-	const declared = ctx.schemas?.events;
-	const declaredTypes = new Set(Object.keys(declared ?? {}));
-	if ([...declaredTypes].every((type) => type.startsWith("@agent."))) return [];
+function checkInvokeWithoutOnError(ctx) {
 	const out = [];
-	for (const node of ctx.index.values()) for (const eventType of Object.keys(node.config.on ?? {})) {
-		if (declaredTypes.has(eventType) || isBuiltinOrWildcardEvent(eventType)) continue;
+	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
+		if (invoke.onError !== void 0 || handlesActorError(node.config)) continue;
+		if (handlesActorError(ctx.config) || ancestorChain(node, ctx.index).some((ancestor) => handlesActorError(ancestor.config))) continue;
+		const srcName = typeof invoke.src === "string" ? invoke.src : "(inline logic)";
 		out.push({
-			code: "undeclared-event",
+			code: "invoke-without-on-error",
 			severity: "warning",
 			path: node.path,
-			message: `State '${node.path}' handles event '${eventType}' in 'on:', but it is not declared in schemas.events and is not a builtin/wildcard pattern. If intentional its payload stays unvalidated; otherwise this is likely a typo.`
+			message: `State '${node.path}' invokes '${srcName}' with no 'onError' transition, and no ancestor handles an actor error. A rejected request or actor puts the machine in an error state with no modeled recovery. Add 'onError' (a 'failed' final state, or a bounded retry).`
 		});
 	}
 	return out;
 }
-function checkMissingFinal(ctx) {
-	for (const node of ctx.index.values()) if (node.isFinal && ctx.reachable.has(node.path)) return [];
-	return [{
-		code: "missing-final",
+function checkUnhandledAgentMessages(ctx) {
+	const handlesMessages = (config) => config.on?.["agent.messages"] !== void 0 || config.on?.["*"] !== void 0;
+	if (handlesMessages(ctx.config) || [...ctx.index.values()].some((node) => handlesMessages(node.config))) return [];
+	let contextJsonSchema;
+	try {
+		contextJsonSchema = getJsonSchemaSync(ctx.schemas?.context);
+	} catch {}
+	if (!contextJsonSchema?.properties?.messages) return [];
+	return [...ctx.index.values()].some((node) => node.invokes.some((invoke) => {
+		if (typeof invoke.src !== "string") return false;
+		return invoke.src === "agent.generateText" || invoke.src === "agent.streamText" || isTextLogic(ctx.actors[invoke.src]);
+	})) ? [{
+		code: "unhandled-agent-messages",
 		severity: "warning",
 		path: "(root)",
-		message: "The machine has no reachable final state, so a run can never settle 'done' (only idle/looping). This is legal for agents that only idle, but verify it is intended."
-	}];
+		message: `Text requests may return framework messages, but the machine does not handle '${AGENT_MESSAGES_EVENT_TYPE}'. Add on: { '${AGENT_MESSAGES_EVENT_TYPE}': appendMessages() } when transcript retention is intended, or disable this warning when messages are intentionally ignored.`
+	}] : [];
 }
 const LINT_CHECKS = [
-	checkUnreachableStates,
 	checkDecideWithoutEvents,
-	checkUnserializableContext,
 	checkDirectObjectSrc,
-	checkFinalWithoutOutput,
-	checkFinalOutputReadsEvent,
-	checkUndeclaredEvents,
-	checkMissingFinal
+	checkInvokeWithoutOnError,
+	checkUnhandledAgentMessages
 ];
 /**
 * Runs static structural checks over a built agent machine and returns the
@@ -2046,8 +3243,9 @@ const LINT_CHECKS = [
 * plus the schemas/actor sources the library already retains per machine.
 *
 * No model calls, no API keys — a coding agent that emits an agent machine can
-* call this to catch dead states, undeliverable decisions, un-rebindable
-* invoke srcs, and output-contract gaps before ever running it.
+* call this to catch agent-specific mistakes such as undeliverable decisions,
+* un-rebindable request sources, and an unhandled transcript event. General
+* state-machine lint belongs to XState tooling.
 *
 * Pass `{ throw: true }` for the one-liner form used in tests and generation
 * loops: it returns silently when the machine is clean and throws
@@ -2070,12 +3268,10 @@ const LINT_CHECKS = [
 function lintAgentMachine(machine, options = {}) {
 	const config = machine.config ?? {};
 	const index = buildStateIndex(config);
-	const reachable = computeReachable(config, index, getMachineStaticTransitionTargets(machine));
 	const registered = getRegisteredAgentExecutionOptions(machine);
 	const ctx = {
 		config,
 		index,
-		reachable,
 		schemas: registered.schemas,
 		actors: registered.actors ?? machine.sources?.actors ?? {}
 	};
@@ -2124,13 +3320,10 @@ function assertAgentMachine(machine, options = {}) {
 }
 function pendingInvokes(step) {
 	const out = [];
-	for (const action of step.actions) {
-		const metadata = getInvokeEffectMetadata(action);
-		if (typeof metadata?.src === "string" && typeof metadata.id === "string") out.push({
-			id: metadata.id,
-			src: metadata.src
-		});
-	}
+	for (const metadata of getPendingInvokes(step.snapshot)) if (typeof metadata.src === "string") out.push({
+		id: metadata.id,
+		src: metadata.src
+	});
 	return out;
 }
 function takeFromQueue(channel, src) {
@@ -2184,6 +3377,7 @@ async function simulateAgent(machine, options) {
 		text: mapValues(options.script.text ?? {}, (arr) => [...arr]),
 		decisions: mapValues(options.script.decisions ?? {}, (arr) => [...arr]),
 		invokes: mapValues(options.script.invokes ?? {}, (arr) => [...arr]),
+		errors: mapValues(options.script.errors ?? {}, (arr) => [...arr]),
 		events: [...options.script.events ?? []]
 	};
 	if (options.script.userInput?.length) script.invokes[USER_INPUT_SRC] = [...options.script.userInput, ...script.invokes[USER_INPUT_SRC] ?? []];
@@ -2201,9 +3395,28 @@ async function simulateAgent(machine, options) {
 				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;
+				const errorSrc = queueKey(script.errors, src, request.id);
+				const failure = takeFromQueue(script.errors, errorSrc);
+				if (failure.found) {
+					step = rejectScriptedRequest(machine, step, request.id, failure.value, {
+						kind: "decision",
+						src: errorSrc,
+						trail
+					});
+					continue;
+				}
 				step = await applyScriptedDecision(machine, step, request, decisionSrc, invokeMeta?.logic, script, trail);
 				continue;
 			}
+			const failure = takeFromQueue(script.errors, request.src);
+			if (failure.found) {
+				step = rejectScriptedRequest(machine, step, request, failure.value, {
+					kind: "text",
+					src: request.src,
+					trail
+				});
+				continue;
+			}
 			const taken = takeFromQueue(script.text, request.src);
 			if (!taken.found) throw scriptDryError("text", request.src, request.id);
 			step = resolveAgentStep(machine, step, request, taken.value);
@@ -2212,13 +3425,23 @@ async function simulateAgent(machine, options) {
 				resolvedRequest: {
 					kind: "text",
 					src: request.src,
-					id: request.id
+					id: request.id,
+					outcome: "output"
 				}
 			});
 			continue;
 		}
 		const [invoke] = pendingInvokes(step);
 		if (invoke) {
+			const failure = takeFromQueue(script.errors, invoke.src);
+			if (failure.found) {
+				step = rejectScriptedRequest(machine, step, invoke.id, failure.value, {
+					kind: "userInput",
+					src: invoke.src,
+					trail
+				});
+				continue;
+			}
 			const taken = takeFromQueue(script.invokes, invoke.src);
 			if (!taken.found) throw scriptDryError("userInput", invoke.src, invoke.id);
 			step = resolveAgentStep(machine, step, invoke.id, taken.value);
@@ -2227,7 +3450,8 @@ async function simulateAgent(machine, options) {
 				resolvedRequest: {
 					kind: "userInput",
 					src: invoke.src,
-					id: invoke.id
+					id: invoke.id,
+					outcome: "output"
 				}
 			});
 			continue;
@@ -2256,6 +3480,29 @@ async function simulateAgent(machine, options) {
 		trail
 	};
 }
+function queueKey(channel, src, id) {
+	return channel && !(src in channel) && id in channel ? id : src;
+}
+function rejectScriptedRequest(machine, step, request, error, entry) {
+	const id = typeof request === "string" ? request : request.id;
+	const next = rejectAgentStep(machine, step, request, error);
+	if (next.snapshot.status === "error") throw unhandledScriptedError(error, entry.kind, entry.src, id);
+	entry.trail.push({
+		state: next.snapshot.value,
+		resolvedRequest: {
+			kind: entry.kind,
+			src: entry.src,
+			id,
+			outcome: "error",
+			error
+		}
+	});
+	return next;
+}
+function unhandledScriptedError(error, kind, src, id) {
+	if (error instanceof Error) return error;
+	return new Error(`simulateAgent: the scripted error for the ${kind} request '${src}' (id '${id}') reached no onError transition, so the machine errored. Add an onError to that invoke, or drop the errors['${src}'] entry.`, { cause: error });
+}
 async function applyScriptedDecision(machine, step, request, decisionSrc, invokeLogic, script, trail) {
 	const dequeued = [];
 	const decide = async () => {
@@ -2276,12 +3523,7 @@ async function applyScriptedDecision(machine, step, request, decisionSrc, invoke
 		});
 	} catch (error) {
 		if (!(error instanceof AgentDecisionExhaustedError)) throw error;
-		const next = transitionAgentStep(machine, step, {
-			type: "xstate.error.actor",
-			actorId: request.id,
-			...sessionIdOf(step.snapshot, request.id),
-			error
-		});
+		const next = rejectAgentStep(machine, step, request.id, error);
 		if (next.snapshot.status === "error") throw error;
 		trail.push({
 			state: next.snapshot.value,
@@ -2299,9 +3541,8 @@ async function applyScriptedDecision(machine, step, request, decisionSrc, invoke
 	return next;
 }
 function findInvokeMetadata(step, id) {
-	for (const action of step.actions) {
-		const metadata = getInvokeEffectMetadata(action);
-		if (metadata?.id !== id) continue;
+	for (const metadata of getPendingInvokes(step.snapshot)) {
+		if (metadata.id !== id) continue;
 		return {
 			...typeof metadata.src === "string" ? { src: metadata.src } : {},
 			logic: metadata.logic ?? (typeof metadata.src === "object" ? metadata.src : void 0)
@@ -2312,10 +3553,6 @@ function resolveRegisteredDecisionLogic(machine, src) {
 	const candidate = getRegisteredAgentExecutionOptions(machine).actors?.[src] ?? machine.sources?.actors?.[src];
 	return 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)]));
 }
@@ -2325,12 +3562,25 @@ function scriptDryError(kind, src, id, request) {
 	return /* @__PURE__ */ new Error(`simulateAgent: script ran dry on a pending ${kind} request for src '${src}' (id '${id}'). Add an entry to the script's \`${key}\` queue.${events}`);
 }
 const MAX_ADVANCE_STEPS = 1e3;
+function invokeFork(id, src, outputs) {
+	return src in outputs ? {
+		id,
+		src,
+		hasOutput: true,
+		output: outputs[src]
+	} : {
+		id,
+		src,
+		hasOutput: false
+	};
+}
 async function explore(machine, options, stopWhen) {
 	const maxDepth = options.maxDepth ?? 8;
 	const maxPaths = options.maxPaths ?? 200;
 	const textScript = options.text ?? {};
 	const invokeOutputs = { ...options.invokes ?? {} };
 	if ("userInput" in options) invokeOutputs[USER_INPUT_SRC] = options.userInput;
+	const errorScript = options.errors ?? {};
 	const reachedStates = /* @__PURE__ */ new Set();
 	const reachedValues = [];
 	const terminals = [];
@@ -2359,6 +3609,10 @@ async function explore(machine, options, stopWhen) {
 			if (current.done) return { step: current };
 			const request = current.requests[0];
 			if (request && request.kind === "text") {
+				if (request.src in errorScript) return {
+					step: current,
+					fork: invokeFork(request.id, request.src, textScript)
+				};
 				if (!(request.src in textScript)) return {
 					step: current,
 					blockedSrc: request.src
@@ -2367,9 +3621,25 @@ async function explore(machine, options, stopWhen) {
 				recordState(current.snapshot);
 				continue;
 			}
-			if (request && request.kind === "decision") return { step: current };
+			if (request && request.kind === "decision") {
+				const src = findInvokeMetadata(current, request.id)?.src;
+				const errorSrc = src !== void 0 && src in errorScript ? src : request.id in errorScript ? request.id : void 0;
+				return errorSrc !== void 0 ? {
+					step: current,
+					fork: {
+						id: request.id,
+						src: errorSrc,
+						hasOutput: false,
+						isDecision: true
+					}
+				} : { step: current };
+			}
 			const [invoke] = pendingInvokes(current);
 			if (invoke) {
+				if (invoke.src in errorScript) return {
+					step: current,
+					fork: invokeFork(invoke.id, invoke.src, invokeOutputs)
+				};
 				if (!(invoke.src in invokeOutputs)) return {
 					step: current,
 					blockedSrc: invoke.src
@@ -2382,17 +3652,43 @@ async function explore(machine, options, stopWhen) {
 		}
 		return { step: current };
 	};
-	const visit = async (step, path, depth) => {
+	const visit = async (step, path, startDepth) => {
+		let depth = startDepth;
 		if (witness !== void 0) return;
 		if (pathsExplored >= maxPaths) {
 			hitPathCap = true;
 			return;
 		}
-		const { step: settled, blockedSrc, hit } = advance(step);
+		const { step: settled, blockedSrc, hit, fork } = advance(step);
 		if (hit) {
 			witness = path;
 			return;
 		}
+		if (fork) {
+			if (depth >= maxDepth) {
+				pathsExplored++;
+				terminals.push({
+					status: "max-depth",
+					path,
+					state: settled.snapshot.value
+				});
+				unexplored.push(`max-depth: stopped at path [${path.map((e) => e.type).join(", ")}]`);
+				return;
+			}
+			const failed = rejectAgentStep(machine, settled, fork.id, errorScript[fork.src]);
+			recordState(failed.snapshot);
+			await visit(failed, [...path, { type: `xstate.error.actor.${fork.id}` }], depth + 1);
+			if (!fork.isDecision) {
+				if (fork.hasOutput) {
+					const resolved = resolveAgentStep(machine, settled, fork.id, fork.output);
+					recordState(resolved.snapshot);
+					await visit(resolved, path, depth + 1);
+				}
+				return;
+			}
+			depth += 1;
+			if (witness !== void 0) return;
+		}
 		if (blockedSrc) {
 			pathsExplored++;
 			terminals.push({
@@ -2413,6 +3709,16 @@ async function explore(machine, options, stopWhen) {
 			});
 			return;
 		}
+		if (settled.snapshot.status === "error") {
+			pathsExplored++;
+			terminals.push({
+				status: "error",
+				path,
+				state: settled.snapshot.value,
+				error: settled.snapshot.error
+			});
+			return;
+		}
 		const request = settled.requests[0];
 		const branchEvents = request?.kind === "decision" ? request.events.map((descriptor) => ({ type: descriptor.type })) : getAcceptedEvents(settled.snapshot).map((descriptor) => ({ type: descriptor.type }));
 		if (branchEvents.length === 0) {
@@ -2469,7 +3775,9 @@ async function explore(machine, options, stopWhen) {
 * an idle wait it forks per externally-accepted event. Text requests resolve
 * from `text`, other invokes from `invokes` (or `userInput` for
 * `agent.userInput`) — all by-src canned-output maps, and a missing src halts
-* that branch with a `needs-output` terminal rather than throwing.
+* that branch with a `needs-output` terminal rather than throwing. A src in
+* `errors` forks an extra branch where that invoke is rejected, so states
+* behind an `onError` are explored too.
 *
 * Combinatorics are bounded by `maxDepth` (default 8) and `maxPaths` (default
 * 200, reported via `hitPathCap`).
@@ -2483,6 +3791,24 @@ async function explore(machine, options, stopWhen) {
 async function explorePaths(machine, options = {}) {
 	return (await explore(machine, options)).report;
 }
+/** Thrown when a string reachability target is not a state in the machine. */
+var AgentUnknownStateError = class extends AgentError {
+	target;
+	constructor(machineId, target) {
+		super("unknown-state", `canReach: machine '${machineId}' has no state matching '${target}'.`);
+		this.name = "AgentUnknownStateError";
+		this.target = target;
+	}
+};
+function resolveStateTarget(machine, target) {
+	const stack = [machine.root];
+	while (stack.length > 0) {
+		const node = stack.pop();
+		if (node.id === target.replace(/^#/, "") || node.path.join(".") === target) return node.id;
+		stack.push(...Object.values(node.states));
+	}
+	throw new AgentUnknownStateError(machine.id, target);
+}
 /**
 * Answers "can the machine reach this?" by exploring its branches (a thin
 * wrapper over {@link explorePaths}). The target is either a state path string
@@ -2509,23 +3835,16 @@ async function explorePaths(machine, options = {}) {
 * ```
 */
 async function canReach(machine, target, options = {}) {
-	const { witness } = await explore(machine, options, typeof target === "function" ? target : (snapshot) => {
-		try {
-			return snapshot.matches(target);
-		} catch {
-			return false;
-		}
-	});
+	const resolvedTarget = typeof target === "string" ? resolveStateTarget(machine, target) : void 0;
+	const { witness } = await explore(machine, options, typeof target === "function" ? target : (snapshot) => snapshot.nodes.some((node) => node.id === resolvedTarget));
 	return witness !== void 0 ? {
 		reachable: true,
-		witness
-	} : { reachable: false };
-}
-//#endregion
-//#region src/internal/is-record.ts
-/** True for a plain object-like value (arrays excluded). @internal */
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+		witness,
+		...resolvedTarget ? { target: resolvedTarget } : {}
+	} : {
+		reachable: false,
+		...resolvedTarget ? { target: resolvedTarget } : {}
+	};
 }
 //#endregion
 //#region src/trajectory.ts
@@ -2545,7 +3864,7 @@ function normalize(item) {
 			kind: "event",
 			event: item
 		};
-		if ("value" in item && "status" in item) return {
+		if ("value" in item) return {
 			kind: "state",
 			value: item["value"]
 		};
@@ -2605,8 +3924,8 @@ function matcherFor(expected) {
 /**
 * Matches a run's trajectory against an expected one.
 *
-* Both trajectories may be state values (collected from `onTransition`) or
-* events (`result.events`, whose {@link AgentLogEntry} envelopes are unwrapped);
+* Both trajectories may be state values or events collected from
+* `onTransition`;
 * items are compared by shape, so `['prompting', 'drafting']` scores a state
 * path and `['PROMPT_SUBMITTED', 'SEND']` scores an event log with the same
 * call.
@@ -2626,7 +3945,7 @@ function matcherFor(expected) {
 *
 * const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
 * expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
-* expect(matchesTrajectory(result.events, ['PROMPT_SUBMITTED', 'SEND']).matched).toBe(true);
+* expect(matchesTrajectory(events, ['PROMPT_SUBMITTED', 'SEND']).matched).toBe(true);
 * ```
 *
 * @example Partial credit in an eval scorer
@@ -2637,6 +3956,7 @@ function matcherFor(expected) {
 */
 function matchesTrajectory(actual, expected, options = {}) {
 	const expectedCount = expected.length;
+	if (expectedCount === 0) throw new AgentError("empty-trajectory", "matchesTrajectory: expected trajectory must contain at least one item.");
 	const exact = options.exact === true;
 	let cursor = 0;
 	let matchedCount = 0;
@@ -2677,17 +3997,41 @@ function matchesTrajectory(actual, expected, options = {}) {
 //#endregion
 //#region src/scripted-executors.ts
 /**
-* Scripted executors — a keyless, deterministic stand-in for a model host.
+* Scripted executors — a deterministic stand-in for a model host.
 *
 * `createScriptedExecutors` builds a full `{ generateText, streamText, decide }`
-* set (plus a `userInput` handler) that plays back canned answers from FIFO
-* queues, so `runAgent` (or
-* `provideExecutors`, or a bare `TextLogic.execute`) runs with no API key and no
-* network. It is the fastest way to see a machine run, and the least ceremonial
-* way to test one: same machine, same executor contract, scripted answers.
+* set (plus a `userInput` handler) that plays back canned answers keyed by
+* request name, so `runAgent` (or `provideExecutors`, or a bare
+* `TextLogic.execute`) runs with no API key and no network.
+*
+* One rule: entries for a name are consumed in order, and the last entry
+* repeats forever.
 *
 * @module
 */
+function toQueues(value) {
+	return new Map(Object.entries(value ?? {}).map(([name, entries]) => [name, {
+		entries: Array.isArray(entries) ? [...entries] : [entries],
+		index: 0
+	}]));
+}
+/**
+* Takes the next entry for `name`, holding on the last entry once the list is
+* spent. `undefined` means the script has no route for this name at all.
+* @internal
+*/
+function takeEntry(queues, name) {
+	const queue = queues.get(name) ?? queues.get("*");
+	if (!queue || queue.entries.length === 0) return;
+	const entry = queue.entries[Math.min(queue.index, queue.entries.length - 1)];
+	queue.index++;
+	return entry;
+}
+/** @internal */
+function noAnswer(name, queues) {
+	const known = [...queues.keys()].join(", ") || "(none)";
+	return /* @__PURE__ */ new Error(`No scripted answer for request '${name}'. Known: ${known}`);
+}
 /** The only own keys an executor-result envelope carries. @internal */
 const TEXT_ENVELOPE_KEYS = new Set([
 	"output",
@@ -2730,22 +4074,26 @@ function emitScriptedChunk(result, info) {
 	if (typeof output === "string") info?.onChunk?.(output);
 }
 /**
-* Keyless executors that replay a script instead of calling a model. Every
-* slot is provided, so any machine binds; a request with no entry left throws a
-* descriptive error naming what was pending.
+* Executors that replay a script instead of calling a model. Every slot is
+* provided, so any machine binds.
+*
+* Answers are keyed by the request's resolved name — its authored `name`, else
+* the invoke `id` — and `"*"` serves anything unmatched.
+* Entries for a name are consumed in order and the last one repeats forever, so
+* a looping machine needs no extra option. A request the script has no route
+* for throws an ordinary `Error` from inside the executor, which reaches the
+* machine as an actor error.
 *
-* Queues are consumed FIFO and are copied on creation, so the caller's arrays
-* are never mutated and each call builds a fresh, independent playthrough.
-* Entries may be plain values or functions of the request, which is how one
-* script serves a machine that loops or branches: route on `request.name` (the
-* `setupAgent({ requests })` key) or on the decision's candidate `events`.
+* Queues are copied on creation, so the caller's arrays are never mutated and
+* each call builds a fresh, independent playthrough. Entries may be plain
+* values or functions of the request.
 *
 * @example
 * ```ts
 * const result = await runAgent(moderationMachine, {
 *   input: { comment: 'honestly this update is terrible', trust: 20 },
 *   executors: createScriptedExecutors({
-*     decisions: [{ type: 'FLAG', reason: 'Borderline tone.' }],
+*     decisions: { moderate: [{ type: 'FLAG', reason: 'Borderline tone.' }] },
 *   }),
 * });
 * ```
@@ -2753,8 +4101,8 @@ function emitScriptedChunk(result, info) {
 * @example Dynamic entries
 * ```ts
 * createScriptedExecutors({
-*   text: [(request) => `Draft about ${request.prompt}`],
-*   decisions: [(request) => ({ type: request.events[0]!.type })],
+*   text: { draft: (request) => `Draft about ${request.prompt}` },
+*   decisions: { route: (request) => ({ type: request.events[0]!.type }) },
 * });
 * ```
 *
@@ -2765,30 +4113,72 @@ function emitScriptedChunk(result, info) {
 * ```
 */
 function createScriptedExecutors(script = {}) {
-	const decisions = [...script.decisions ?? []];
-	const text = [...script.text ?? []];
+	const decisions = toQueues(script.decisions);
+	const text = toQueues(script.text);
 	const userInput = [...script.userInput ?? []];
-	const nextText = async (request, info) => {
-		if (text.length === 0) throw new AgentError("scripted-executors-exhausted", `createScriptedExecutors: script ran dry on a pending text request ${describeText(request)}. Add another entry to the script's \`text\` queue.`);
-		return resolveScriptedTextEntry(text.shift(), request, info);
+	let userInputIndex = 0;
+	const calls = [];
+	const withDefaultUsage = (result) => result.usage || !script.usage ? result : {
+		...result,
+		usage: script.usage
+	};
+	const nextText = async (kind, request, info) => {
+		const name = request.name ?? "*";
+		calls.push({
+			kind,
+			name,
+			input: request.input,
+			request
+		});
+		const entry = takeEntry(text, name);
+		if (entry === void 0) throw noAnswer(name, text);
+		return withDefaultUsage(await resolveScriptedTextEntry(entry, request, info));
 	};
 	return {
+		calls,
 		userInput: async (input) => {
-			if (userInput.length === 0) throw new AgentError("scripted-executors-exhausted", `createScriptedExecutors: script ran dry on a pending userInput request (prompt: ${input.prompt ? `'${input.prompt}'` : "(none)"}). Add another entry to the script's \`userInput\` queue.`);
-			const entry = userInput.shift();
+			calls.push({
+				kind: "userInput",
+				name: "agent.userInput",
+				input,
+				request: input
+			});
+			if (userInput.length === 0) throw new Error("No scripted answer for request 'agent.userInput'. Add an entry to the script's `userInput` array.");
+			const entry = userInput[Math.min(userInputIndex++, userInput.length - 1)];
 			return typeof entry === "function" ? await entry(input) : entry;
 		},
-		generateText: nextText,
+		generateText: (request, info) => nextText("generateText", request, info),
 		streamText: async (request, info) => {
-			const result = await nextText(request, info);
+			const name = request.name ?? "*";
+			const streamEntry = script.stream?.[name] ?? script.stream?.["*"];
+			if (streamEntry !== void 0) {
+				calls.push({
+					kind: "streamText",
+					name,
+					input: request.input,
+					request
+				});
+				const resolved = typeof streamEntry === "function" ? await streamEntry(request, info) : streamEntry;
+				const chunks = typeof resolved === "string" ? [resolved] : [...resolved];
+				for (const chunk of chunks) info?.onChunk?.(chunk);
+				return withDefaultUsage({ output: chunks.join("") });
+			}
+			const result = await nextText("streamText", request, info);
 			emitScriptedChunk(result, info);
 			return result;
 		},
 		decide: async (request) => {
-			if (decisions.length === 0) throw new AgentError("scripted-executors-exhausted", `createScriptedExecutors: script ran dry on a pending decision request (id '${request.id}'). Add another entry to the script's \`decisions\` queue. Candidate events: ${request.events.map((event) => event.type).join(", ") || "(none)"}.`);
-			const entry = decisions.shift();
+			const name = request.name ?? request.id;
+			calls.push({
+				kind: "decide",
+				name,
+				input: request.input,
+				request
+			});
+			const entry = takeEntry(decisions, name);
+			if (entry === void 0) throw noAnswer(name, decisions);
 			const value = typeof entry === "function" ? await entry(request) : entry;
-			return isRecord(value) && typeof value["type"] !== "string" && "event" in value ? value : { event: value };
+			return withDefaultUsage(isRecord(value) && typeof value["type"] !== "string" && "event" in value ? value : { event: value });
 		}
 	};
 }
@@ -2819,7 +4209,7 @@ async function seamOutputOf(result, request) {
 * seam's own effect completion (the first `xstate.done.*`/`xstate.error.*`
 * entry appended after the call was made).
 *
-* @example Keyless: the seam is scripted too, so the whole thing runs offline.
+* @example No API key: the seam is scripted too, so the whole thing runs offline.
 * ```ts
 * const run = await runSeam(emailDrafter, {
 *   scripts: { promptEvaluator: [vague, complete], emailDrafter: [draft] },
@@ -2912,27 +4302,22 @@ async function runSeam(machine, options) {
 	};
 	let snapshot;
 	let event;
-	let events = [];
+	const events = [];
 	let result;
 	const maxTurns = options.maxTurns ?? 12;
 	for (let turn = 0; turn <= maxTurns; turn++) {
 		result = await runAgent(machine, {
 			...snapshot ? { snapshot } : { input: options.input },
 			...event ? { event } : {},
-			...options.isIdle ? { isIdle: options.isIdle } : {},
 			...options.actors ? { actors: options.actors } : {},
-			events,
 			executors,
-			onEvent: () => {
-				liveEvents++;
-			},
 			onTransition: (next, causedBy) => {
 				if (turn > 0 && causedBy.type === "@xstate.init") return;
+				events.push(causedBy);
+				liveEvents = events.length;
 				statePath.push(next.value);
 			}
 		});
-		events = result.events;
-		liveEvents = events.length;
 		if (result.status !== "idle" || turn === maxTurns) break;
 		const next = options.respond?.({
 			snapshot: result.snapshot,
@@ -2943,13 +4328,13 @@ async function runSeam(machine, options) {
 		});
 		if (!next) break;
 		event = next;
-		snapshot = result.snapshot;
+		snapshot = result.persist();
 	}
 	let splitAt = events.length;
 	if (seamReached) {
 		splitAt = seamEventAt;
 		for (let index = seamEventAt; index < events.length; index++) {
-			const type = events[index].event.type;
+			const type = events[index].type;
 			if (type.startsWith("xstate.done") || type.startsWith("xstate.error")) {
 				splitAt = index;
 				break;
@@ -2974,209 +4359,4 @@ 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 ?? resolveMachineVersion(machine);
-	const priorEntries = options.entries ?? [];
-	if (priorEntries.length > 0) validateReplayEntries(priorEntries, {
-		machineId,
-		machineVersion
-	}, "Durable journal entries");
-	const hasInit = priorEntries[0]?.event.type === 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 = createDurable(bound, {
-		executionId,
-		sendEvent(source, target, event) {
-			if (target.address === rootAddress) {
-				mailbox.push(event);
-				return;
-			}
-			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 = createReplayEntry(machine, entries, event, entryOptions);
-		entries.push(entry);
-		options.onEntry?.(entry);
-	};
-	if (!hasInit) {
-		const entry = 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
-export { AGENT_EVENT_SCHEMA_VERSION, AGENT_INIT_EVENT_TYPE, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentIdleError, AgentIllegalResumeEventError, AgentLintError, AgentMaxModelCallsExceededError, AgentReplayDivergenceError, AgentReplayMachineMismatchError, AgentSnapshotVersionMismatchError, NonSerializableAgentEventError, appendMessages, assertAgentLogEntry, assertAgentMachine, assertEventLogStoreConformance, assertJsonSerializable, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentActor, createAgentRun, createAgentSchemas, createDecisionLogic, createInMemoryEventLogStore, createReplayEntry, createScriptedExecutors, createTextLogic, diffEventLogs, executeAgentRequest, explorePaths, generateResult, getAcceptedEvents, getAgentEffects, getAgentMessages, getAgentOutputMode, getAgentSchemas, getCallUsage, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getSnapshotNodes, getSnapshotRequests, getStateMeta, initEntry, inspectTransitions, isStandardSchema, lintAgentMachine, matchesTrajectory, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, provideExecutors, renderDecisionAttempts, replay, resolveDecision, runAgent, runDurableAgent, runSeam, serializeTraceEvent, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage };
+export { AGENT_EVENT_SCHEMA_VERSION, AGENT_INIT_EVENT_TYPE, AGENT_MESSAGES_EVENT_TYPE, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentEventLogError, AgentInvalidEventPayloadError, AgentLintError, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, AgentReplayDivergenceError, AgentSnapshotDivergedError, AgentTruncatedError, AgentUnknownStateError, NonSerializableAgentEventError, agentCallOccurrence, appendMessages, assertAgentLogEntry, assertAgentMachine, assertEventLogStoreConformance, assertJsonSerializable, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createDecisionLogic, createDecisionRequest, createInMemoryEventLogStore, createReplayEntry, createScriptedExecutors, createTextLogic, eventFromInteraction, executeAgentRequest, explorePaths, forkEventLog, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getLogExecutionId, getMachineStructuralHash, getMessageText, getSnapshotStateHash, getStateMeta, getStatePath, getUsageFromEvents, initEntry, inspectTransitions, interactionMetaSchema, isAgentIdle, isAgentMessages, isStandardSchema, lintAgentMachine, matchesTrajectory, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, provideExecutors, rebindActorSession, renderDecisionAttempts, replay, resolveDecision, runAgent, runAgentLoop, runAgentStream, runSeam, serializeTraceEvent, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage, validateReplayEntries };