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

package/dist/{text-logic-f5F5sCdc.cjs → event-log-BZRfBRd7.cjs}

@@ -1,4 +1,3 @@
-require("./validate.cjs");
 let xstate = require("xstate");
 //#region src/errors.ts
 /**
@@ -384,7 +383,7 @@ function getRegisteredAgentExecutionOptions(machine, options) {
 const GENERATE_TEXT_ACTOR = "agent.generateText";
 const STREAM_TEXT_ACTOR = "agent.streamText";
 const DECIDE_ACTOR = "agent.decide";
-const AGENT_FINISH_REASONS = new Set([
+const AGENT_FINISH_REASONS = /* @__PURE__ */ new Set([
 	"stop",
 	"length",
 	"tool-calls",
@@ -578,7 +577,7 @@ function resolveTextLogicValue(value, args) {
 * export const tellJoke = createTextLogic({
 *   mode: 'stream',
 *   schemas: { input: z.object({ topic: z.string() }), output: z.string() },
-*   model: 'openai/gpt-5.4-mini',
+*   model: 'openai/gpt-6-luna',
 *   system: 'You tell short, punchy jokes.',
 *   prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
 * });
@@ -815,6 +814,700 @@ function invalidGeneratorResult(id) {
 	return /* @__PURE__ */ new Error(`Executor for '${id}' returned an invalid result: executors must return { result } (the text string or structured object as \`result\`, plus optional \`messages\`, \`usage\` and other passthrough fields). Wrap a raw SDK result with an adapter such as createAiSdkExecutors.`);
 }
 //#endregion
+//#region src/usage.ts
+/** Reserved event delivered after a model call reports token usage. */
+const AGENT_USAGE_EVENT_TYPE = "@agent.usage";
+//#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 {
+	eventId;
+	index;
+	kind;
+	expected;
+	actual;
+	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 {
+	eventId;
+	index;
+	expected;
+	actual;
+	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 {
+		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.");
+	if (candidate.attempts !== void 0) assertLogAttempts(candidate.attempts);
+}
+function assertLogAttempts(attempts) {
+	if (!Array.isArray(attempts) || !attempts.every((attempt) => attempt !== null && typeof attempt === "object" && typeof attempt.failure === "string" && typeof attempt.reason === "string")) throw new AgentEventLogError("Agent event entry.attempts requires an array of { failure, reason } objects.");
+}
+/**
+* Whether `value` survives the log's JSON rules. Diagnostic fields the runtime
+* records on its own (decision attempts) are dropped rather than failing the
+* entry they explain.
+*/
+function isJsonSerializable(value) {
+	try {
+		assertJsonSerializable(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* The decision-exhausted error's `attempts`, when JSON-safe. Duck-typed on the
+* error code: `decision.ts` imports this module, so importing the class here
+* would be a cycle.
+*/
+const DECISION_EXHAUSTED_CODE = "decision-exhausted";
+function exhaustedAttemptsOf(error) {
+	if (error.code !== DECISION_EXHAUSTED_CODE) return void 0;
+	const attempts = error.attempts;
+	return Array.isArray(attempts) && isJsonSerializable(attempts) ? attempts : void 0;
+}
+/**
+* Replaces `Error` instances with plain `{ name, message, cause? }` objects so
+* an `xstate.error.actor` payload survives the log's JSON round-trip. A
+* decision-exhausted error also keeps its `code` and `attempts`. 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);
+		if (value.code === DECISION_EXHAUSTED_CODE) {
+			normalized.code = DECISION_EXHAUSTED_CODE;
+			const attempts = exhaustedAttemptsOf(value);
+			if (attempts !== void 0) normalized.attempts = structuredClone(attempts);
+		}
+		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 = /* @__PURE__ */ new Set([
+	"sessionId",
+	"_nextTimerId",
+	"_nextActorIds"
+]);
+const CHILD_VOLATILE_KEYS = /* @__PURE__ */ 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;
+}
+function normalizeDoneActorEvent(event) {
+	if (event.type !== DONE_ACTOR_EVENT_TYPE) return event;
+	const { output, ...rest } = event;
+	return output === void 0 ? rest : event;
+}
+/**
+* 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: normalizeDoneActorEvent(normalizeEventErrors(event)),
+		...options.causationId !== void 0 ? { causationId: options.causationId } : {},
+		...options.metadata !== void 0 ? { metadata: options.metadata } : {},
+		...options.attempts !== void 0 && options.attempts.length > 0 ? { attempts: options.attempts } : {}
+	};
+	assertAgentLogEntry(entry);
+	if (entry.attempts !== void 0) entry.attempts = structuredClone(entry.attempts);
+	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
+		});
+	}
+}
+/**
+* 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;
+}
+/**
+* The decision attempts a log recorded but the machine never accepted, in log
+* order — the input for improving a decider from its traces. Two sources:
+*
+* - `entry.attempts`: the failed tries before the entry's event landed.
+* - An `xstate.error.actor.*` entry whose `error` is a decision-exhausted
+*   error (`code: "decision-exhausted"`) that kept its `attempts`: every try
+*   failed. Another actor error's `attempts` field is not read.
+*
+* Entries with neither are skipped.
+*/
+function getDecisionAttempts(entries) {
+	const found = [];
+	for (const entry of entries) {
+		const { type } = entry.event;
+		if (entry.attempts !== void 0 && entry.attempts.length > 0) {
+			found.push({
+				index: entry.index,
+				eventType: type,
+				attempts: entry.attempts
+			});
+			continue;
+		}
+		if (type.startsWith(ERROR_ACTOR_EVENT_TYPE)) {
+			const error = entry.event.error;
+			if (error?.code === DECISION_EXHAUSTED_CODE && Array.isArray(error.attempts) && error.attempts.length > 0) found.push({
+				index: entry.index,
+				eventType: type,
+				attempts: error.attempts
+			});
+		}
+	}
+	return found;
+}
+/**
+* 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 {
+		...event,
+		sessionId
+	};
+}
+function restoreDoneActorOutput(event) {
+	if (event.type !== DONE_ACTOR_EVENT_TYPE || Object.hasOwn(event, "output")) return event;
+	return {
+		...event,
+		output: void 0
+	};
+}
+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 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 = {}) {
+	const fold = foldLog(machine, entries, options);
+	return {
+		snapshot: fold.snapshot,
+		persistedSnapshot: fold.persistedSnapshot
+	};
+}
+/**
+* {@link replay}, returning a {@link LogFold} that further entries can be
+* folded onto in exactly the way `replay` would fold them. A live run records
+* each entry's hash from this fold, never from its own snapshot: a live
+* snapshot also holds what the log cannot reproduce (a sibling child that
+* already settled while its completion waits in the mailbox). @internal
+*/
+function foldLog(machine, entries, options = {}) {
+	validateReplayEntries(entries, {
+		machine,
+		machineVersion: options.machineVersion ?? resolveMachineVersion(machine)
+	});
+	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) : (0, xstate.initialTransition)(machine, initEvent.input)[0];
+	let persisted = machine.getPersistedSnapshot(snapshot);
+	verifyEntry(entries[0], persisted, options.verify);
+	const sessions = /* @__PURE__ */ new Map();
+	const apply = (entry) => {
+		const event = restoreDoneActorOutput(rebindActorSession(entry.event, snapshot, sessions));
+		[snapshot] = (0, xstate.transition)(machine, snapshot, event);
+		persisted = machine.getPersistedSnapshot(snapshot);
+		return persisted;
+	};
+	for (let index = 1; index < entries.length; index++) {
+		const entry = entries[index];
+		verifyEntry(entry, apply(entry), options.verify);
+	}
+	return {
+		get snapshot() {
+			return snapshot;
+		},
+		get persistedSnapshot() {
+			return persisted;
+		},
+		apply
+	};
+}
+/**
+* Records a plain `createActor` run as an event log, with no
+* `createAgentRuntime`: the init entry (the actor's `input`, or the snapshot
+* it was created from), then every event the root machine processed, invoke
+* completions with their outputs inline. Attach it before `actor.start()`.
+*
+* @example
+* ```ts no-check
+* const actor = createActor(machine, { input });
+* const log = recordLog(actor);
+* actor.start();
+* // ...later
+* const { snapshot } = replay(machine, log.entries); // no actor runs
+* ```
+*/
+function recordLog(actor) {
+	if (actor.getSnapshot().status !== "active") throw new AgentEventLogError("recordLog must be attached before actor.start(): the actor has already finished.");
+	const machine = actor.logic;
+	const machineVersion = resolveMachineVersion(machine);
+	const entries = [];
+	let fold;
+	let failure;
+	const record = (event) => {
+		if (fold === void 0) {
+			if (event.type !== "xstate.init") throw new AgentEventLogError("recordLog must be attached before actor.start(): it missed the init event.");
+			const restored = actor.options.snapshot;
+			const init = restored ? { snapshot: restored } : { input: event.input };
+			entries.push(initEntry(machine, init, { machineVersion }));
+			fold = foldLog(machine, entries, {
+				machineVersion,
+				verify: false
+			});
+			return;
+		}
+		const entry = createReplayEntry(machine, entries, event, {
+			machineVersion,
+			verification: false
+		});
+		entry.verification = { stateHash: getSnapshotStateHash(fold.apply(entry)) };
+		entries.push(entry);
+	};
+	const subscription = actor.system.inspect((inspectionEvent) => {
+		if (failure !== void 0 || inspectionEvent.type !== "@xstate.transition" || inspectionEvent.actorRef !== actor) return;
+		try {
+			record(inspectionEvent.event);
+		} catch (error) {
+			failure = error;
+		}
+	});
+	return {
+		get entries() {
+			if (failure !== void 0) throw failure;
+			if (entries.length === 0) throw new AgentEventLogError("recordLog has no init entry: the actor has not started, or recordLog was attached after actor.start().");
+			return [...entries];
+		},
+		stop: () => subscription.unsubscribe()
+	};
+}
+//#endregion
+Object.defineProperty(exports, "AGENT_EVENT_SCHEMA_VERSION", {
+	enumerable: true,
+	get: function() {
+		return AGENT_EVENT_SCHEMA_VERSION;
+	}
+});
+Object.defineProperty(exports, "AGENT_INIT_EVENT_TYPE", {
+	enumerable: true,
+	get: function() {
+		return AGENT_INIT_EVENT_TYPE;
+	}
+});
+Object.defineProperty(exports, "AGENT_USAGE_EVENT_TYPE", {
+	enumerable: true,
+	get: function() {
+		return AGENT_USAGE_EVENT_TYPE;
+	}
+});
 Object.defineProperty(exports, "AGENT_USAGE_TOKEN_FIELDS", {
 	enumerable: true,
 	get: function() {
@@ -827,6 +1520,24 @@ Object.defineProperty(exports, "AgentError", {
 		return AgentError;
 	}
 });
+Object.defineProperty(exports, "AgentEventLogError", {
+	enumerable: true,
+	get: function() {
+		return AgentEventLogError;
+	}
+});
+Object.defineProperty(exports, "AgentMachineVersionMismatchError", {
+	enumerable: true,
+	get: function() {
+		return AgentMachineVersionMismatchError;
+	}
+});
+Object.defineProperty(exports, "AgentReplayDivergenceError", {
+	enumerable: true,
+	get: function() {
+		return AgentReplayDivergenceError;
+	}
+});
 Object.defineProperty(exports, "AgentTruncatedError", {
 	enumerable: true,
 	get: function() {
@@ -845,12 +1556,36 @@ Object.defineProperty(exports, "GENERATE_TEXT_ACTOR", {
 		return GENERATE_TEXT_ACTOR;
 	}
 });
+Object.defineProperty(exports, "NonSerializableAgentEventError", {
+	enumerable: true,
+	get: function() {
+		return NonSerializableAgentEventError;
+	}
+});
 Object.defineProperty(exports, "STREAM_TEXT_ACTOR", {
 	enumerable: true,
 	get: function() {
 		return STREAM_TEXT_ACTOR;
 	}
 });
+Object.defineProperty(exports, "agentCallOccurrence", {
+	enumerable: true,
+	get: function() {
+		return agentCallOccurrence;
+	}
+});
+Object.defineProperty(exports, "assertAgentLogEntry", {
+	enumerable: true,
+	get: function() {
+		return assertAgentLogEntry;
+	}
+});
+Object.defineProperty(exports, "assertJsonSerializable", {
+	enumerable: true,
+	get: function() {
+		return assertJsonSerializable;
+	}
+});
 Object.defineProperty(exports, "assistantMessage", {
 	enumerable: true,
 	get: function() {
@@ -869,16 +1604,22 @@ Object.defineProperty(exports, "builtinTextActors", {
 		return builtinTextActors;
 	}
 });
-Object.defineProperty(exports, "createTextLogic", {
+Object.defineProperty(exports, "canonicalEventJson", {
 	enumerable: true,
 	get: function() {
-		return createTextLogic;
+		return canonicalEventJson;
 	}
 });
-Object.defineProperty(exports, "djb2Hex", {
+Object.defineProperty(exports, "createReplayEntry", {
 	enumerable: true,
 	get: function() {
-		return djb2Hex;
+		return createReplayEntry;
+	}
+});
+Object.defineProperty(exports, "createTextLogic", {
+	enumerable: true,
+	get: function() {
+		return createTextLogic;
 	}
 });
 Object.defineProperty(exports, "executorBoundLogics", {
@@ -893,6 +1634,18 @@ Object.defineProperty(exports, "findNonSerializableContextPaths", {
 		return findNonSerializableContextPaths;
 	}
 });
+Object.defineProperty(exports, "foldLog", {
+	enumerable: true,
+	get: function() {
+		return foldLog;
+	}
+});
+Object.defineProperty(exports, "forkEventLog", {
+	enumerable: true,
+	get: function() {
+		return forkEventLog;
+	}
+});
 Object.defineProperty(exports, "getAgentExecutionOptions", {
 	enumerable: true,
 	get: function() {
@@ -917,6 +1670,12 @@ Object.defineProperty(exports, "getCallUsage", {
 		return getCallUsage;
 	}
 });
+Object.defineProperty(exports, "getDecisionAttempts", {
+	enumerable: true,
+	get: function() {
+		return getDecisionAttempts;
+	}
+});
 Object.defineProperty(exports, "getJsonSchema", {
 	enumerable: true,
 	get: function() {
@@ -929,6 +1688,12 @@ Object.defineProperty(exports, "getJsonSchemaSync", {
 		return getJsonSchemaSync;
 	}
 });
+Object.defineProperty(exports, "getLogExecutionId", {
+	enumerable: true,
+	get: function() {
+		return getLogExecutionId;
+	}
+});
 Object.defineProperty(exports, "getMachineStructuralHash", {
 	enumerable: true,
 	get: function() {
@@ -947,6 +1712,12 @@ Object.defineProperty(exports, "getRegisteredAgentExecutionOptions", {
 		return getRegisteredAgentExecutionOptions;
 	}
 });
+Object.defineProperty(exports, "getSnapshotStateHash", {
+	enumerable: true,
+	get: function() {
+		return getSnapshotStateHash;
+	}
+});
 Object.defineProperty(exports, "getStateMeta", {
 	enumerable: true,
 	get: function() {
@@ -959,6 +1730,18 @@ Object.defineProperty(exports, "getStatePath", {
 		return getStatePath;
 	}
 });
+Object.defineProperty(exports, "getUsageFromEvents", {
+	enumerable: true,
+	get: function() {
+		return getUsageFromEvents;
+	}
+});
+Object.defineProperty(exports, "initEntry", {
+	enumerable: true,
+	get: function() {
+		return initEntry;
+	}
+});
 Object.defineProperty(exports, "isStandardSchema", {
 	enumerable: true,
 	get: function() {
@@ -1007,6 +1790,24 @@ Object.defineProperty(exports, "providerOutputSchema", {
 		return providerOutputSchema;
 	}
 });
+Object.defineProperty(exports, "rebindActorSession", {
+	enumerable: true,
+	get: function() {
+		return rebindActorSession;
+	}
+});
+Object.defineProperty(exports, "recordLog", {
+	enumerable: true,
+	get: function() {
+		return recordLog;
+	}
+});
+Object.defineProperty(exports, "replay", {
+	enumerable: true,
+	get: function() {
+		return replay;
+	}
+});
 Object.defineProperty(exports, "resolveMachineVersion", {
 	enumerable: true,
 	get: function() {
@@ -1049,6 +1850,12 @@ Object.defineProperty(exports, "userMessage", {
 		return userMessage;
 	}
 });
+Object.defineProperty(exports, "validateReplayEntries", {
+	enumerable: true,
+	get: function() {
+		return validateReplayEntries;
+	}
+});
 Object.defineProperty(exports, "validateSchemaSync", {
 	enumerable: true,
 	get: function() {