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

package/dist/{text-logic-CIqHAmBi.mjs → event-log-GPZO9p7_.mjs}

@@ -1,4 +1,4 @@
-import { createAsyncLogic } from "xstate";
+import { createAsyncLogic, initialTransition, transition } from "xstate";
 //#region src/errors.ts
 /**
 * Base class for every error this package throws. Carries a stable, kebab-case
@@ -383,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",
@@ -814,4 +814,680 @@ 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
-export { getMessageText as A, AgentTruncatedError as B, setAgentExecutionOptions as C, getJsonSchema as D, findNonSerializableContextPaths as E, systemMessage as F, toolMessage as I, userMessage as L, getStatePath as M, isStandardSchema as N, getJsonSchemaSync as O, resolveMachineVersion as P, validateSchemaSync as R, missingActor as S, djb2Hex as T, responseMessagesOf as _, bindRequestExecutor as a, getRegisteredAgentExecutionOptions as b, getAgentOutputMode as c, isTextLogic as d, normalizeGeneratorResult as f, resolveTextLogicValue as g, providerOutputSchema as h, STREAM_TEXT_ACTOR as i, getStateMeta as j, getMachineStructuralHash as k, getCallFinishReason as l, parseProviderOutput as m, DECIDE_ACTOR as n, builtinTextActors as o, parseOutput as p, GENERATE_TEXT_ACTOR as r, createTextLogic as s, AGENT_USAGE_TOKEN_FIELDS as t, getCallUsage as u, executorBoundLogics as v, assistantMessage as w, isUnboundPlaceholder as x, getAgentExecutionOptions as y, AgentError as z };
+//#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) : 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] = 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
+export { getStateMeta as $, createTextLogic as A, responseMessagesOf as B, AGENT_USAGE_EVENT_TYPE as C, STREAM_TEXT_ACTOR as D, GENERATE_TEXT_ACTOR as E, normalizeGeneratorResult as F, missingActor as G, getAgentExecutionOptions as H, parseOutput as I, findNonSerializableContextPaths as J, setAgentExecutionOptions as K, parseProviderOutput as L, getCallFinishReason as M, getCallUsage as N, bindRequestExecutor as O, isTextLogic as P, getMessageText as Q, providerOutputSchema as R, validateReplayEntries as S, DECIDE_ACTOR as T, getRegisteredAgentExecutionOptions as U, executorBoundLogics as V, isUnboundPlaceholder as W, getJsonSchemaSync as X, getJsonSchema as Y, getMachineStructuralHash as Z, getUsageFromEvents as _, AgentReplayDivergenceError as a, userMessage as at, recordLog as b, assertAgentLogEntry as c, AgentTruncatedError as ct, createReplayEntry as d, getStatePath as et, foldLog as f, getSnapshotStateHash as g, getLogExecutionId as h, AgentMachineVersionMismatchError as i, toolMessage as it, getAgentOutputMode as j, builtinTextActors as k, assertJsonSerializable as l, getDecisionAttempts as m, AGENT_INIT_EVENT_TYPE as n, resolveMachineVersion as nt, NonSerializableAgentEventError as o, validateSchemaSync as ot, forkEventLog as p, assistantMessage as q, AgentEventLogError as r, systemMessage as rt, agentCallOccurrence as s, AgentError as st, AGENT_EVENT_SCHEMA_VERSION as t, isStandardSchema as tt, canonicalEventJson as u, initEntry as v, AGENT_USAGE_TOKEN_FIELDS as w, replay as x, rebindActorSession as y, resolveTextLogicValue as z };