@statelyai/agent 2.0.0-alpha.23 → 2.0.0-alpha.25

package/dist/run-agent-Cb1-LS5P.cjs

@@ -0,0 +1,1783 @@
+const require_text_logic = require("./text-logic-C8xyr6Ag.cjs");
+const require_decision = require("./decision-CM9CYZ6t.cjs");
+const require_usage = require("./usage-efOQPdf_.cjs");
+const require_event_log_store = require("./event-log-store-DQmImLYk.cjs");
+require("./validate.cjs");
+let xstate = require("xstate");
+//#region src/steps.ts
+/**
+* The step API: the pure `(state, event) => (nextState, requests)` view of an
+* agent machine. An {@link AgentStep} is a snapshot plus the model requests
+* the machine is now waiting on; nothing here executes anything. A host
+* resolves each request however it likes ({@link executeAgentRequest},
+* `resolveDecision`, a queue, a durable workflow, a replayed log) and feeds
+* the result back with {@link resolveAgentStep} or {@link rejectAgentStep}.
+* `runAgent` is the in-process host built for the common case.
+* @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 = {
+		...require_text_logic.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 = require_text_logic.isTextLogic(params.logic) || require_decision.isDecisionLogic(params.logic) ? params.logic : options.actors?.[params.src];
+		if (require_decision.isDecisionLogic(registeredLogic)) {
+			const decisionRequest = registeredLogic.request(params.input);
+			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
+			const events = options.snapshot ? require_decision.getAcceptedEvents(options.snapshot, {
+				events: options.events,
+				schemas: options.schemas,
+				eventTypes: allowedEventTypes
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = require_text_logic.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
+	};
+}
+/**
+* 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
+	};
+}
+/**
+* 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 = (0, xstate.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] = (0, xstate.initialTransition)(machine, input);
+	return createAgentStep(machine, snapshot, actions, require_text_logic.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] = (0, xstate.transition)(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, event);
+	return createAgentStep(machine, nextSnapshot, actions, require_text_logic.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, require_text_logic.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, require_text_logic.getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Resolves one **text** request ({@link AgentRequest}, from
+* {@link AgentStep.requests}) against a host's {@link AgentRequestExecutors}
+* — merges the request's tools, dispatches to `generateText`/`streamText`
+* per `mode`, and validates the result against the request's
+* `outputSchema` if present. **Text-only**: passing a `kind: 'decision'`
+* request throws, directing the caller to `resolveDecision(request,
+* executors, ...)` instead. Returns the invoke's output — `{ result,
+* messages }`, ready for {@link resolveAgentStep} — plus the `raw` executor
+* result (tool calls, usage, finish reason).
+*/
+async function executeAgentRequest(request, executors) {
+	if (request.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors, ...) instead.");
+	assertTextExecutor(request, executors);
+	const { result, raw } = await require_text_logic.executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
+	return {
+		result: request.input.outputSchema ? require_text_logic.validateSchemaSync(request.input.outputSchema, result) : result,
+		messages: require_text_logic.responseMessagesOf(raw),
+		raw
+	};
+}
+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/run-agent.ts
+/**
+* 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 require_text_logic.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 require_event_log_store.getSnapshotStateHash(rest);
+	}
+	return require_event_log_store.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
+* payload shape, so a consumer can gate on it. Emitted identically by
+* {@link runAgent}, {@link provideExecutors}' `onTrace`, and
+* {@link traceTransitions}.
+*/
+const AGENT_TRACE_SCHEMA_VERSION = 1;
+const TRACE_ENVELOPE_KEYS = [
+	"schemaVersion",
+	"runId",
+	"seq",
+	"timestamp",
+	"machineId",
+	"machineVersion",
+	"type",
+	"status",
+	"cause",
+	"reasoning",
+	"finishReason",
+	"chunk"
+];
+/**
+* Best-effort JSON projection of an arbitrary value. Never throws: functions,
+* symbols, `undefined`, and cyclic back-references are DROPPED (array holes
+* become `null`), non-finite numbers become `null`, `bigint`s become strings,
+* `Error`s become `{ name, message, stack?, code? }`, and anything with a
+* `toJSON()` (e.g. `Date`) is projected through it — the same losses a
+* `JSON.parse(JSON.stringify(...))` round-trip incurs, minus the throws.
+*/
+function toJsonValue(value, ancestors) {
+	if (value === null) return null;
+	const type = typeof value;
+	if (type === "string" || type === "boolean") return value;
+	if (type === "number") return Number.isFinite(value) ? value : null;
+	if (type === "bigint") return value.toString();
+	if (type !== "object") return;
+	const object = value;
+	if (ancestors.includes(object)) return;
+	const nextAncestors = [...ancestors, object];
+	if (object instanceof Error) {
+		const serialized = {
+			name: object.name,
+			message: object.message
+		};
+		if (typeof object.stack === "string") serialized.stack = object.stack;
+		const code = object.code;
+		if (typeof code === "string") serialized.code = code;
+		const cause = toJsonValue(object.cause, nextAncestors);
+		if (cause !== void 0) serialized.cause = cause;
+		return serialized;
+	}
+	const toJSON = object.toJSON;
+	if (typeof toJSON === "function") return toJsonValue(toJSON.call(object), nextAncestors);
+	if (Array.isArray(object)) return object.map((item) => toJsonValue(item, nextAncestors) ?? null);
+	const out = {};
+	for (const [key, item] of Object.entries(object)) {
+		const serializedItem = toJsonValue(item, nextAncestors);
+		if (serializedItem !== void 0) out[key] = serializedItem;
+	}
+	return out;
+}
+/**
+* Projects an {@link AgentTraceEvent} into a guaranteed JSON-safe envelope —
+* the form the trace stream is actually sold for (one `JSON.stringify` per line
+* in a JSONL file). Live values are sanitized rather than trusted:
+*
+* - Snapshots (`run.start`, `machine.transition`, `run.end`) go through the
+*   same JSON round-trip as `machine.getPersistedSnapshot(...)`, so what lands on disk is
+*   what a resume would see.
+* - `request.end`'s `raw` (a provider SDK object, frequently cyclic) is DROPPED
+*   unless `includeRaw` is set, in which case it is sanitized like everything
+*   else.
+* - Non-serializable values anywhere (functions, symbols, `undefined`, cyclic
+*   back-references) are dropped; `Error`s become `{ name, message, stack?,
+*   code? }` instead of `{}`. Nothing throws.
+*
+* @example
+* ```ts
+* await appendFile('trace.jsonl', JSON.stringify(serializeTraceEvent(event)) + '\n');
+* ```
+*/
+function serializeTraceEvent(event, options = {}) {
+	const out = {};
+	for (const [key, value] of Object.entries(event)) {
+		if (key === "raw" && !options.includeRaw) continue;
+		if (TRACE_ENVELOPE_KEYS.includes(key)) {
+			if (value !== void 0) out[key] = value;
+			continue;
+		}
+		const serialized = toJsonValue(value, []);
+		if (serialized !== void 0) out[key] = serialized;
+	}
+	return out;
+}
+let nextRunAgentTraceId = 1;
+/**
+* Thrown into the invoke that would have made the call once
+* {@link RunAgentOptions.maxModelCalls} is spent. It reaches the machine
+* through the normal error channel, so an invoke's `onError` can branch on it
+* (`error.code === 'max-model-calls'`, the same string the settled result's
+* `cause` uses) and route to a degraded/finish state instead of failing the
+* run. Unhandled, it settles `{ status: 'error', cause: 'max-model-calls' }`.
+*
+* ```ts
+* onError: [
+*   { guard: ({ event }) => event.error?.code === 'max-model-calls', target: 'budgetSpent' },
+*   { target: 'failed' },
+* ]
+* ```
+*/
+var AgentMaxModelCallsExceededError = class extends require_text_logic.AgentError {
+	/** The budget that was exceeded (`options.maxModelCalls`). */
+	maxModelCalls;
+	constructor(maxModelCalls) {
+		super("max-model-calls", `runAgent exceeded maxModelCalls (${maxModelCalls}). Raise the budget, or handle it in the invoke's onError (error.code === 'max-model-calls').`);
+		this.name = "AgentMaxModelCallsExceededError";
+		this.maxModelCalls = maxModelCalls;
+	}
+};
+function wrapsDecisionExhausted(error) {
+	let current = error;
+	for (let depth = 0; depth < 10 && current != null; depth++) {
+		if (current instanceof require_decision.AgentDecisionExhaustedError) return true;
+		current = current.cause;
+	}
+	return false;
+}
+/**
+* Recursively collects every invoke's `src` from raw machine config (spike
+* S6: `machine.config` preserves authored srcs; the built `machine.root`
+* normalizes object srcs to synthetic string ids and loses the distinction
+* this walk needs). Function-valued `src` resolvers are dynamic and are not
+* statically analyzable, so they are skipped (pass-through, like any other
+* non-agent actor).
+*/
+function collectConfiguredInvokeSrcs(stateConfig, stateName, out) {
+	if (!stateConfig) return;
+	const invokes = stateConfig.invoke === void 0 ? [] : Array.isArray(stateConfig.invoke) ? stateConfig.invoke : [stateConfig.invoke];
+	for (const invokeConfig of invokes) {
+		const src = invokeConfig?.src;
+		if (typeof src === "string" || src && typeof src === "object") out.push({
+			stateName,
+			src
+		});
+	}
+	for (const [childName, childConfig] of Object.entries(stateConfig.states ?? {})) collectConfiguredInvokeSrcs(childConfig, `${stateName}.${childName}`, out);
+}
+/**
+* Duck-types a state machine actor logic (an invoked child machine) vs. any
+* other actor logic. xstate's `StateMachine` carries `.config`, `.root`, and
+* a `.provide(...)` method plus a `sources.actors` map — this
+* combination is unique to machines and survives the dual-package/version
+* boundary an `instanceof` check would not. Used to descend the bind-time
+* walk into invoked child machines (their internal agent requests are opaque
+* to the parent-level source walk otherwise).
+*/
+function isStateMachineLogic(logic) {
+	return !!logic && typeof logic === "object" && "config" in logic && "root" in logic && typeof logic.provide === "function" && typeof logic.sources === "object" && !!logic.sources?.actors;
+}
+/**
+* Fails fast (throws) at bind time — before any actor runs — when the
+* machine invokes an agent actor `runAgent` cannot execute. See §3.2 point 2.
+*
+* Recurses into invoked child state machines (arbitrarily deep). A child
+* machine's agent requests reached through string-keyed invoke srcs DO inherit
+* the parent runAgent's `generateText`/`streamText`/`decide` executors —
+* runAgent rebinds them with the same host-backed wrappers (see
+* {@link rebindChildMachine}) — so the only remaining bind-time errors are: a
+* required executor kind missing entirely (naming the invoke chain and src),
+* and an unbound request reached through a direct-object invoke src that can't
+* be rebound ({@link unrebindableChildRequestError}). A request that carries
+* its own executor (`.withExecutor(...)`, tracked in `executorBoundLogics`)
+* always runs itself; explicit binding shadows inheritance.
+*/
+function assertBindable(machine, effectiveSources, executors) {
+	assertMachineBindable(machine, effectiveSources, executors, {
+		isChild: false,
+		childPath: "",
+		rebindable: true,
+		visited: new Set([machine])
+	});
+}
+function assertMachineBindable(machine, effectiveSources, executors, ctx) {
+	const invokes = [];
+	collectConfiguredInvokeSrcs(machine.config, machine.config.id ?? "(root)", invokes);
+	const where = ctx.isChild ? `child machine '${ctx.childPath}' state` : "state";
+	for (const { stateName, src } of invokes) {
+		if (typeof src !== "string") {
+			if (isStateMachineLogic(src)) {
+				assertChildMachineBindable(src, src, stateName, executors, ctx);
+				continue;
+			}
+			if ((require_text_logic.isTextLogic(src) || require_decision.isDecisionLogic(src)) && !require_text_logic.executorBoundLogics.has(src)) throw new Error(`runAgent: ${where} '${stateName}' invokes a direct-object actor logic (kind: '${src.kind}'). Direct-object invoke srcs cannot be rebound by runAgent — either call '.withExecutor(...)' on the logic before invoking it, or register it as a string-keyed actor source instead (machine.provide({ actors: { name: logic } })) and invoke it by name.`);
+			continue;
+		}
+		const logic = effectiveSources[src];
+		if (logic === void 0) throw new Error(`runAgent: ${where} '${stateName}' invokes unregistered actor source '${src}'. Provide it via machine.provide({ actors: { '${src}': ... } }) or runAgent(machine, { actors: { '${src}': ... } }).`);
+		if (isStateMachineLogic(logic)) {
+			assertChildMachineBindable(logic, src, stateName, executors, ctx);
+			continue;
+		}
+		if (require_decision.isDecisionLogic(logic)) {
+			if (require_text_logic.executorBoundLogics.has(logic)) continue;
+			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, "decision");
+			if (!executors.decide) throw new Error(`runAgent: ${where} '${stateName}' invokes decision source '${src}' but no 'decide' executor was provided to runAgent(...).`);
+			continue;
+		}
+		if (require_text_logic.isTextLogic(logic)) {
+			if (require_text_logic.executorBoundLogics.has(logic)) continue;
+			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, logic.mode === "stream" ? "streaming text" : "text");
+			if (logic.mode === "stream" && !executors.streamText) throw new Error(`runAgent: ${where} '${stateName}' invokes streaming text source '${src}' but no 'streamText' executor was provided to runAgent(...).`);
+			if (logic.mode !== "stream" && !executors.generateText) throw new Error(`runAgent: ${where} '${stateName}' invokes text source '${src}' but no 'generateText' executor was provided to runAgent(...).`);
+			continue;
+		}
+		if (require_text_logic.isUnboundPlaceholder(logic)) throw new Error(`runAgent: ${where} '${stateName}' invokes actor source '${src}', which has no host execution. Provide it via machine.provide({ actors: { '${src}': ... } }) or runAgent(machine, { actors: { '${src}': ... } }).`);
+	}
+}
+/** Descends the bind-time walk into an invoked child state machine, guarding
+* against a machine that (transitively) invokes itself. */
+function assertChildMachineBindable(childMachine, childSrc, stateName, executors, ctx) {
+	if (ctx.visited.has(childMachine)) return;
+	const childName = typeof childSrc === "string" ? childSrc : childMachine.config.id ?? "(child machine)";
+	const childPath = ctx.childPath ? `${ctx.childPath} > ${childName}` : childName;
+	const childSources = childMachine.sources.actors;
+	assertMachineBindable(childMachine, childSources, executors, {
+		isChild: true,
+		childPath,
+		rebindable: ctx.rebindable && typeof childSrc === "string",
+		visited: new Set([...ctx.visited, childMachine])
+	});
+}
+/** The loud bind-time error for an unbound agent request reached under a
+* direct-object invoke src, which runAgent cannot rebind (only string-keyed
+* sources can be swapped via `.provide`). Names the invoke chain AND the
+* request src, and spells out the `.withExecutor`/string-keyed remedy. Note:
+* requests reachable through string-keyed srcs at any depth DO inherit
+* runAgent's executors — this error is only for the unrebindable direct-object
+* case. */
+function unrebindableChildRequestError(childPath, stateName, requestSrc, kind) {
+	return /* @__PURE__ */ new Error(`runAgent: child machine '${childPath}' (state '${stateName}') invokes ${kind} source '${requestSrc}', which has no host execution and is reached through a direct-object invoke src that runAgent cannot rebind. Requests reached through string-keyed actor sources inherit runAgent's generateText/streamText/decide executors automatically; a direct-object child machine does not. Either bind the request with its own executor (requestLogic.withExecutor(...)), or register the child as a string-keyed actor source (machine.provide({ actors: { <child>: childMachine } })) and invoke it by name.`);
+}
+/**
+* True when the snapshot's active states declare a transition that would
+* receive the reserved `'@agent.usage'` type — an explicit `on: { '@agent.usage'
+* }` OR a catch-all `on: { '*': … }`. Plain XState semantics apply unmodified:
+* a wildcard matches every event delivered to the machine, reserved ones
+* included. (The MODEL-facing side stays closed: `getAcceptedEvents` drops
+* `@agent.*` before any `allowedEvents` matching, so a wildcard never offers
+* the reserved event as a decision candidate.) @internal
+*/
+function declaresUsageTransition(snapshot) {
+	return (0, xstate.getNextTransitions)(snapshot).some((transition) => transition.eventType === "@agent.usage" || transition.eventType === "*");
+}
+/**
+* Builds the ONE place a trace payload is emitted: it hands the payload to the
+* envelope-stamping trace sink and, from that same payload, invokes the sugar
+* callbacks that are projections of it — {@link RunAgentOptions.onChunk},
+* {@link RunAgentOptions.onResult}, {@link RunAgentOptions.onTransition}. Each
+* keeps its historical position relative to the trace: `onResult` fires just
+* BEFORE its `request.end`, `onChunk`/`onTransition` just AFTER their
+* `stream.chunk`/`machine.transition`. Sugar dispatch never depends on whether
+* a trace sink is present, and the trace sink is never called when it is
+* absent — so an `onTrace`-less run still mints no envelope (and advances no
+* `seq`). @internal
+*/
+function createTraceDispatch(sinks) {
+	return (payload, self) => {
+		switch (payload.type) {
+			case "stream.chunk":
+				sinks.onTrace?.(payload, self);
+				sinks.onChunk?.(payload.chunk, { request: payload.request });
+				return;
+			case "request.end":
+				sinks.onResult?.(payload.request, {
+					result: payload.output,
+					raw: payload.raw
+				});
+				sinks.onTrace?.(payload, self);
+				return;
+			case "machine.transition":
+				sinks.onTrace?.(payload, self);
+				sinks.onTransition?.(payload.snapshot, payload.event);
+				return;
+			default: sinks.onTrace?.(payload, self);
+		}
+	};
+}
+/** Reads the durable invoke id/src off the async actor's own ref (`self`). */
+function selfIdAndSrc(self) {
+	return {
+		id: typeof self?.id === "string" ? self.id : "",
+		src: typeof self?.src === "string" ? self.src : ""
+	};
+}
+/**
+* The machine actor that INVOKED a decision request — the actor whose
+* live snapshot supplies the candidate events and drives `canTake`/`send`.
+* For a top-level request this is the root actor (identity-equal to
+* `runCtx.actorHolder.actorRef`); for a request inside an invoked child
+* machine it is that child's actor, so a child decision reads and drives
+* the CHILD's snapshot — not the root's. Read off `self._parent`, with the
+* root actor as a fallback.
+*/
+function invokingActorOf(self, runCtx) {
+	return self?._parent ?? runCtx.actorHolder.actorRef;
+}
+/**
+* The shared text/stream emission helper: binds a {@link TextLogic} to
+* `runCtx`'s executor and constructs the `request.start` / `stream.chunk` /
+* `request.end` (incl. the lifted `reasoning`) / `request.error` trace payloads.
+* Used by both `runAgent` and `provideExecutors` so the two paths produce
+* identical event shapes by construction. @internal
+*/
+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: 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 = {
+			...request,
+			tools: request.tools ?? {}
+		};
+		const agentRequest = {
+			kind: "text",
+			id,
+			src,
+			mode: logic.mode,
+			input: request,
+			tools: requestWithTools.tools,
+			events: []
+		};
+		runCtx.consumeModelCall();
+		runCtx.emitTrace?.({
+			type: "request.start",
+			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?.({
+						type: "stream.chunk",
+						request: agentRequest,
+						chunk
+					}, self);
+				},
+				signal,
+				...runCtx.runId !== void 0 ? { runId: runCtx.runId } : {},
+				...id !== "" ? { requestId: id } : {},
+				...callKey !== void 0 ? { callKey } : {}
+			});
+			const output = await require_text_logic.normalizeGeneratorResult(raw, id);
+			const rawReasoning = raw?.reasoning;
+			const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
+			const usage = require_text_logic.getCallUsage(raw);
+			const finishReason = require_text_logic.getCallFinishReason(raw);
+			if (usage) runCtx.recordUsage?.(usage, {
+				kind: "text",
+				...id !== "" ? { id } : {},
+				...src !== "" ? { src } : {},
+				model: request.model,
+				...request.name !== void 0 ? { name: request.name } : {}
+			}, self);
+			runCtx.emitTrace?.({
+				type: "request.end",
+				request: agentRequest,
+				output,
+				raw,
+				...reasoning !== void 0 ? { reasoning } : {},
+				...usage !== void 0 ? { usage } : {},
+				...finishReason !== void 0 ? { finishReason } : {}
+			}, self);
+			return {
+				result: output,
+				messages: require_text_logic.responseMessagesOf(raw)
+			};
+		} catch (error) {
+			runCtx.emitTrace?.({
+				type: "request.error",
+				request: agentRequest,
+				error
+			}, self);
+			throw error;
+		}
+	});
+}
+function createCountingDecide(runCtx, self) {
+	return async (attemptRequest, info) => {
+		runCtx.consumeModelCall();
+		runCtx.emitTrace?.({
+			type: "request.start",
+			request: attemptRequest
+		}, 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?.callKey === void 0 && callKey !== void 0 ? { callKey } : {}
+			});
+			const usage = require_text_logic.getCallUsage(result);
+			const finishReason = require_text_logic.getCallFinishReason(result);
+			if (usage) {
+				const { src } = selfIdAndSrc(self);
+				runCtx.recordUsage?.(usage, {
+					kind: "decision",
+					...attemptRequest.id ? { id: attemptRequest.id } : {},
+					...src !== "" ? { src } : {},
+					model: attemptRequest.model
+				}, self);
+			}
+			runCtx.emitTrace?.({
+				type: "request.end",
+				request: attemptRequest,
+				output: result.event,
+				raw: result,
+				...usage !== void 0 ? { usage } : {},
+				...finishReason !== void 0 ? { finishReason } : {}
+			}, self);
+			return result;
+		} catch (error) {
+			runCtx.emitTrace?.({
+				type: "request.error",
+				request: attemptRequest,
+				error
+			}, self);
+			throw error;
+		}
+	};
+}
+/**
+* Builds the decision actor logic runAgent installs in place of a
+* `DecisionLogic`/`agent.decide` source. `DecisionLogic.withExecutor(...)`
+* can only swap the innermost per-attempt executor — the `resolveDecision(...)`
+* call (and its `canTake`) is hardwired inside the original logic's `run`.
+* To supply `canTake` (mode-3, §2.6), runAgent instead builds a fresh async
+* logic here that calls `resolveDecision` itself, reusing `logic.request(...)`
+* to build the request the same way the original logic would have.
+*
+* On success it SENDS the chosen event to the invoking actor (auto-delivery)
+* and then completes with that event
+* as its output — so callers never wire an `onDone` to deliver it. See the
+* send-then-complete note inside `run` for how exit-cancels-invoke interacts
+* with `onDone`.
+*/
+function bindDecisionLogic(logic, runCtx) {
+	const decisionLogic = (0, xstate.createAsyncLogic)({ run: async ({ input, signal, self: selfArg }) => {
+		if (!runCtx.decide) throw new Error("No 'decide' executor provided.");
+		const self = selfArg;
+		const { id } = selfIdAndSrc(self);
+		const declaredEventTypes = logic.allowedEventTypes?.(input);
+		await Promise.resolve();
+		const actorRef = invokingActorOf(self, runCtx);
+		const events = actorRef ? require_decision.getAcceptedEvents(actorRef.getSnapshot(), {
+			schemas: runCtx.schemas,
+			eventTypes: declaredEventTypes
+		}) : [];
+		const lowered = logic.request(input);
+		const chosen = await require_decision.resolveDecision({
+			...lowered,
+			id,
+			name: lowered.name ?? id,
+			input,
+			events
+		}, { decide: createCountingDecide(runCtx, self) }, {
+			maxRetries: logic.maxRetries,
+			signal,
+			canTake: (event) => actorRef ? actorRef.getSnapshot().can(event) : true
+		});
+		actorRef?.send(chosen);
+		await Promise.resolve();
+		return chosen;
+	} });
+	return Object.assign(decisionLogic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries: logic.maxRetries,
+		request: logic.request,
+		withExecutor: (nextExecute) => bindDecisionLogic(logic.withExecutor(nextExecute), runCtx)
+	});
+}
+/**
+* The set of string-keyed actor `src`s the machine's own config invokes
+* (top-level, recursing into child STATES but not into invoked child
+* machines). {@link provideExecutors} uses it to require an executor only for a
+* source the machine actually invokes — the always-registered `agent.*`
+* builtins that go unused must not force their executors to be supplied.
+* @internal
+*/
+function getConfiguredInvokeSrcs(machine) {
+	const invokes = [];
+	collectConfiguredInvokeSrcs(machine.config, machine.config.id ?? "(root)", invokes);
+	const srcs = /* @__PURE__ */ new Set();
+	for (const { src } of invokes) if (typeof src === "string") srcs.add(src);
+	return srcs;
+}
+const rootTraceRegistry = /* @__PURE__ */ new WeakMap();
+let nextProvideRunId = 1;
+/** Walks `self._parent` from an invoked async leaf actor up to its root actor. */
+function rootActorOf(self) {
+	let ref = self;
+	while (ref?._parent) ref = ref._parent;
+	return ref;
+}
+/** The per-root envelope state, minted on first use (runId `run_<n>`, matching runAgent). */
+function rootTraceState(root) {
+	let state = rootTraceRegistry.get(root);
+	if (!state) {
+		const logic = root.logic;
+		const machineId = (logic?.config)?.id ?? logic?.id ?? "(machine)";
+		const machineVersion = logic ? require_text_logic.resolveMachineVersion(logic) : "";
+		state = {
+			runId: `run_${nextProvideRunId++}`,
+			seq: 0,
+			machineId,
+			machineVersion
+		};
+		rootTraceRegistry.set(root, state);
+	}
+	return state;
+}
+/** Stamps a per-root-actor envelope onto a bare trace payload. */
+function stampRootTrace(root, payload) {
+	const state = rootTraceState(root);
+	return {
+		schemaVersion: 1,
+		runId: state.runId,
+		seq: ++state.seq,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		machineId: state.machineId,
+		machineVersion: state.machineVersion,
+		...payload
+	};
+}
+/** Adapts a public `onTrace` into the payload-level trace sink a {@link TraceDispatch} fans out to. */
+function provideTraceSink(onTrace) {
+	if (!onTrace) return;
+	return (payload, self) => {
+		const root = rootActorOf(self);
+		if (root) onTrace(stampRootTrace(root, payload));
+	};
+}
+/**
+* A minimal {@link RunAgentBindContext} for `provideExecutors` (uncontrolled
+* `createActor`): the same wrappers runAgent installs, MINUS the run-scoped
+* model-call counter. `consumeModelCall` is a no-op (no budget), and
+* `actorHolder.actorRef` is left undefined — the wrappers read the invoking
+* actor off `self._parent`, always present under a live `createActor` tree.
+* `onTrace` (when given) mints a per-root-actor envelope. `schemas` come from
+* the machine's registered `setupAgent` execution options.
+*
+* `recordUsage` has no run-level aggregate to fold into here (there is no
+* run), so it does one thing: deliver the reserved `@agent.usage` event, gated
+* exactly like runAgent's — see {@link deliverUsageEvent}.
+*/
+function provideBindContext(machine, executors, options) {
+	const traceSink = provideTraceSink(options.onTrace);
+	const onChunk = options.onChunk;
+	return {
+		generateText: executors.generateText,
+		streamText: executors.streamText,
+		decide: executors.decide,
+		emitTrace: traceSink || onChunk ? createTraceDispatch({
+			onTrace: traceSink,
+			onChunk: onChunk ? (chunk) => onChunk(chunk) : void 0
+		}) : void 0,
+		consumeModelCall: () => {},
+		recordUsage: (usage, source, self) => {
+			deliverUsageEvent({
+				type: require_usage.AGENT_USAGE_EVENT_TYPE,
+				...source,
+				usage
+			}, () => self?._parent);
+		},
+		actorHolder: { actorRef: void 0 },
+		schemas: require_text_logic.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 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
+* take the event. `onDropped` is the run path's straggler gate: it returns `true` for a
+* call that settled after the cycle resolved, which drops the event (traced as
+* `usage.dropped`) rather than delivering it. Uncontrolled mode has no cycle to
+* settle, so it passes no gate and has no dropped stragglers.
+*
+* Delivery follows each path's binding boundary: only sources IT bound report
+* here, so an invoked child machine that was not itself passed through
+* `provideExecutors` reports nothing. @internal
+*/
+function deliverUsageEvent(event, resolveActorRef, onDropped) {
+	const actorRef = resolveActorRef();
+	if (!actorRef) return;
+	const snapshot = actorRef.getSnapshot();
+	if (snapshot?.status !== "active" || !declaresUsageTransition(snapshot)) return;
+	if (onDropped?.(event)) return;
+	if (!snapshot.can(event)) return;
+	actorRef.send(event);
+}
+/**
+* Host-binds one text/stream source for {@link provideExecutors} using the SAME
+* emission helper as `runAgent` ({@link bindTextLogic}), so a bound
+* text request emits request.start/stream.chunk/request.end/request.error with
+* identical shapes. @internal
+*/
+function bindTextForProvide(machine, logic, executors, options) {
+	return bindTextLogic(logic, provideBindContext(machine, executors, options));
+}
+/**
+* Host-binds one `DecisionLogic`/`agent.decide` source for
+* {@link provideExecutors}: runAgent's decision wrapper (snapshot-driven
+* candidate events, `canTake`, auto-delivery of the chosen event) with the same
+* request-level tracing runAgent emits, minus run-scoped counting. @internal
+*/
+function bindDecisionForProvide(machine, logic, executors, options) {
+	return bindDecisionLogic(logic, provideBindContext(machine, executors, options));
+}
+/**
+* Recursively binds an invoked child state machine for {@link provideExecutors},
+* with the same semantics `runAgent` applies ({@link rebindChildMachine}):
+* string-keyed text/decision sources at any depth inherit the host executors,
+* a source that carries its own executor is left alone, and a cycle is
+* returned as-is. Each machine in the tree is bound with its own registered
+* `setupAgent` schemas. Returns the original machine when nothing needed
+* wrapping. @internal
+*/
+function bindChildMachineForProvide(childMachine, executors, options, visited) {
+	const ctxFor = (target) => provideBindContext(target, executors, options);
+	return rebindChildMachine(childMachine, ctxFor(childMachine), visited, ctxFor);
+}
+/**
+* Validates `input` against the machine's registered input schema, returning
+* the schema's output — so defaults are filled and transforms applied before
+* the value reaches `createActor` or the replayable event log.
+*
+* Standard Schema only (no validation library is referenced), so this works for
+* whatever the machine was declared with. Omitted input stays omitted rather
+* than being validated as `{}`: "started with no input" keeps meaning what it
+* has always meant, instead of newly failing schemas with required fields.
+*/
+function resolveMachineInput(machine, input) {
+	if (input === void 0) return input;
+	const schema = require_text_logic.getRegisteredAgentExecutionOptions(machine).schemas?.input;
+	if (!require_text_logic.isStandardSchema(schema)) return input;
+	try {
+		return require_text_logic.validateSchemaSync(schema, input);
+	} catch (error) {
+		throw new require_text_logic.AgentError("invalid-machine-input", `runAgent: machine input failed validation against the declared input schema: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+}
+/**
+* Recursively rebinds an invoked child machine's own agent sources with the
+* SAME host-backed wrappers runAgent applies to the top-level machine, so a
+* child's text/stream/decision requests inherit runAgent's executors and
+* participate in maxModelCalls counting, onTrace/onChunk/onResult exactly like
+* parent requests. Returns the child machine to invoke: a `.provide`-rebound
+* copy when any inner source needed wrapping, else the original untouched.
+*
+* Only string-keyed sources are visited — a direct-object invoke src cannot be
+* swapped via `.provide` (assertBindable already rejected an unbound request
+* under one). A source that already carries its own executor
+* (`executorBoundLogics`) is left as-is: explicit binding shadows inheritance.
+* Cycle-safe via `visited` (a machine that invokes itself is returned as-is).
+*/
+function rebindChildMachine(childMachine, runCtx, visited, ctxFor) {
+	if (visited.has(childMachine)) return childMachine;
+	const childVisited = new Set([...visited, childMachine]);
+	runCtx = ctxFor ? ctxFor(childMachine) : runCtx;
+	const sources = childMachine.sources.actors;
+	const wrapped = {};
+	for (const [key, logic] of Object.entries(sources)) {
+		if (require_decision.isDecisionLogic(logic)) {
+			if (!require_text_logic.executorBoundLogics.has(logic)) wrapped[key] = bindDecisionLogic(logic, runCtx);
+			continue;
+		}
+		if (require_text_logic.isTextLogic(logic)) {
+			if (!require_text_logic.executorBoundLogics.has(logic)) wrapped[key] = bindTextLogic(logic, runCtx);
+			continue;
+		}
+		if (isStateMachineLogic(logic)) {
+			const rebound = rebindChildMachine(logic, runCtx, childVisited, ctxFor);
+			if (rebound !== logic) wrapped[key] = rebound;
+			continue;
+		}
+	}
+	return Object.keys(wrapped).length > 0 ? childMachine.provide({ actors: wrapped }) : childMachine;
+}
+/**
+* Runs an agent machine to completion or idle: a `createActor` host that
+* binds `options`' host executors onto the machine's `agent.*`/`TextLogic`/
+* `DecisionLogic` actor sources, starts (or resumes) the actor, and drives
+* it until it settles — {@link RunAgentResult} `done | idle | error`. Unlike
+* the step helpers ({@link initialAgentStep} etc — a pure
+* transition-at-a-time path for durable hosts), `runAgent` owns a live actor
+* internally; there is no continuation callback, so **idle always settles**
+* and the caller resumes explicitly by passing the settled `{ snapshot,
+* event }` back in. The actor is stopped on every settle path (`done`,
+* `idle`, and `error` alike) — resume is always by snapshot, never by
+* holding a reference to a live actor.
+*
+* Binding happens **before** the actor starts: every invoke the machine
+* could reach is walked and checked against the effective actor sources
+* (`options.actors` merged onto the machine), so a missing
+* `streamText`/`decide` executor or any other unbound actor source throws
+* immediately — a bind-time error, not a mid-run failure.
+*
+* @example
+* ```ts
+* const executors = createAiSdkExecutors({ models });
+* let r = await runAgent(machine, { input, executors });
+* while (r.status === 'idle') {
+*   const event = await promptUser(getAcceptedEvents(r.snapshot));
+*   r = await runAgent(machine, { snapshot: r.snapshot, event, executors });
+* }
+* if (r.status !== 'done') throw new Error(`Run did not complete: ${r.status}`);
+* console.log(r.output);
+* ```
+*
+* Each executor is a plain function returning `{ result }` (plus optional `messages`/`usage`), or
+* an adapter's set: `createAiSdkExecutors` from '@statelyai/agent/ai-sdk' or
+* `createOpenAiExecutors` from '@statelyai/agent/openai' supply all three.
+*/
+async function runAgent(machine, options) {
+	const store = options.store;
+	if (store === void 0) return createAgentSession(machine, options).settled();
+	const threadId = options.threadId;
+	if (threadId === void 0 || threadId === "") throw new require_text_logic.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 require_event_log_store.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();
+}
+/**
+* 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 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 && require_event_log_store.canonicalEventJson(storedEntry.event) === require_event_log_store.canonicalEventJson(givenEntry.event) && (storedHash === void 0 || givenHash === void 0 || storedHash === givenHash))) throw new require_text_logic.AgentError("event-log-conflict", `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) {
+	const maxModelCalls = options.maxModelCalls ?? 100;
+	let modelCallCount = 0;
+	let budgetExceeded = false;
+	let warnedNonSerializable = false;
+	const runId = `run_${nextRunAgentTraceId++}`;
+	let traceSeq = 0;
+	const resolvedInput = resolveMachineInput(machine, options.input);
+	const machineId = machine.config.id ?? machine.id ?? "(machine)";
+	const machineVersion = require_text_logic.resolveMachineVersion(machine);
+	const onTrace = createTraceDispatch({
+		onTrace: (payload) => {
+			options.onTrace?.({
+				schemaVersion: 1,
+				runId,
+				seq: ++traceSeq,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				machineId,
+				machineVersion,
+				...payload
+			});
+		},
+		onChunk: options.onChunk,
+		onResult: options.onResult,
+		onTransition: options.onTransition
+	});
+	const consumeModelCall = () => {
+		if (budgetExceeded) throw new AgentMaxModelCallsExceededError(maxModelCalls);
+		if (modelCallCount + 1 > maxModelCalls) {
+			budgetExceeded = true;
+			throw new AgentMaxModelCallsExceededError(maxModelCalls);
+		}
+		modelCallCount += 1;
+	};
+	const cycleGate = { isResolved: () => false };
+	const logEntries = [];
+	const store = options.store;
+	const threadId = options.threadId;
+	if (store !== void 0 && (threadId === void 0 || threadId === "")) throw new require_text_logic.AgentError("missing-thread-id", "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]
+			});
+		}).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 = require_event_log_store.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: require_usage.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 = () => ({
+		...require_event_log_store.getUsageFromEvents(logEntries.slice(resumedLogLength)),
+		modelCalls: modelCallCount
+	});
+	const warnNonSerializableContext = (snapshot) => {
+		if (warnedNonSerializable || process.env.NODE_ENV === "production") return;
+		let offending = [];
+		try {
+			offending = require_text_logic.findNonSerializableContextPaths(snapshot.context);
+		} catch {
+			return;
+		}
+		if (offending.length === 0) return;
+		warnedNonSerializable = true;
+		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;
+	const executors = { ...options.executors };
+	assertBindable(provided, effectiveSources, executors);
+	const actorHolder = { actorRef: void 0 };
+	const runCtx = {
+		generateText: executors.generateText,
+		streamText: executors.streamText,
+		decide: executors.decide,
+		emitTrace: onTrace,
+		consumeModelCall,
+		recordUsage,
+		actorHolder,
+		awaitJournal,
+		runId,
+		schemas: require_text_logic.getRegisteredAgentExecutionOptions(machine).schemas
+	};
+	const wrappedSources = {};
+	for (const [key, logic] of Object.entries(effectiveSources)) {
+		if (require_decision.isDecisionLogic(logic)) {
+			wrappedSources[key] = bindDecisionLogic(logic, runCtx);
+			continue;
+		}
+		if (require_text_logic.isTextLogic(logic)) {
+			if (!require_text_logic.executorBoundLogics.has(logic)) wrappedSources[key] = bindTextLogic(logic, runCtx);
+			continue;
+		}
+		if (isStateMachineLogic(logic)) {
+			const rebound = rebindChildMachine(logic, runCtx, new Set([machine]));
+			if (rebound !== logic) wrappedSources[key] = rebound;
+			continue;
+		}
+	}
+	const boundMachine = provided.provide({ actors: wrappedSources });
+	const isIdle = require_text_logic.getMachineIdlePredicate(machine) ?? isAgentIdle;
+	const isIntentionalIdle = (snapshot) => isIdle(snapshot);
+	const resumeEvents = options.events;
+	let effectiveSnapshot = options.snapshot;
+	/** 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 = require_event_log_store.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) {
+		require_event_log_store.validateReplayEntries(resumeEvents);
+		const tail = resumeEvents[resumeEvents.length - 1];
+		const inheritedExecutionId = require_event_log_store.getLogExecutionId(resumeEvents);
+		if (resumeEvents[0].machineId !== machineId) throw new require_event_log_store.AgentMachineVersionMismatchError(tail.id, tail.index, {
+			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 = require_event_log_store.getSnapshotStateHash(require_event_log_store.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 = require_event_log_store.replay(logMachine, resumeEvents, {
+					machineVersion,
+					verify: true
+				}).persistedSnapshot;
+			}
+		} else {
+			if (options.snapshot === void 0) throw new require_event_log_store.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 require_event_log_store.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 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}#${require_event_log_store.agentCallOccurrence(resumedHistory, siteId) + startedHere}`;
+		if (self !== void 0) mintedCallKeys.set(self, key);
+		return key;
+	};
+	const resumeEventToSend = options.event;
+	let ignoredEvent;
+	seedInitEntry?.();
+	let settled = false;
+	let journalAtSettle;
+	cycleGate.isResolved = () => settled;
+	let lastResult;
+	const waiters = [];
+	let idleTimer;
+	let actor;
+	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: [...logEntries],
+			persist,
+			drain: drainJournal,
+			usage: runUsage(),
+			...ignoredEvent !== void 0 ? { ignored: ignoredEvent } : {}
+		};
+		if (idleTimer !== void 0) clearTimeout(idleTimer);
+		onTrace({
+			type: "run.end",
+			...outcome
+		});
+		if (options.signal) options.signal.removeEventListener("abort", onAbort);
+		actor.stop();
+		lastResult = result;
+		for (const resolve of waiters.splice(0)) resolve(result);
+	};
+	const onAbort = () => {
+		settle({
+			status: "error",
+			cause: "aborted",
+			error: options.signal?.reason ?? /* @__PURE__ */ new Error("Aborted"),
+			snapshot: actor.getSnapshot()
+		});
+	};
+	const settleIdle = (current) => {
+		warnNonSerializableContext(current);
+		settle({
+			status: "idle",
+			snapshot: current
+		});
+	};
+	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 (isIntentionalIdle(current) && isIdleSnapshot(current)) settleIdle(current);
+		}, 0);
+	};
+	actor = (0, xstate.createActor)(boundMachine, {
+		input: resolvedInput,
+		snapshot: effectiveSnapshot,
+		inspect: (event) => {
+			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) return;
+			const snapshot = event.snapshot;
+			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
+			});
+			if (snapshot.status === "done") {
+				settle({
+					status: "done",
+					output: snapshot.output,
+					snapshot
+				});
+				return;
+			}
+			if (snapshot.status === "error") {
+				settle({
+					status: "error",
+					cause: runErrorCause(snapshot.error),
+					error: snapshot.error,
+					snapshot
+				});
+				return;
+			}
+			if (snapshot.status === "stopped") {
+				settle({
+					status: "error",
+					cause: "stopped",
+					error: /* @__PURE__ */ new Error("Actor stopped externally."),
+					snapshot
+				});
+				return;
+			}
+			if (!deliveringResumeEvent && isIntentionalIdle(snapshot) && isIdleSnapshot(snapshot)) {
+				queueMicrotask(() => {
+					if (settled) return;
+					const current = actor.getSnapshot();
+					if (isIntentionalIdle(current) && isIdleSnapshot(current)) settleIdle(current);
+					else scheduleIdleCheck();
+				});
+				return;
+			}
+			scheduleIdleCheck();
+		}
+	});
+	actorHolder.actorRef = actor;
+	actor.subscribe({ error: () => {} });
+	actor.on("*", (event) => {
+		onTrace({
+			type: "emit",
+			event
+		});
+	});
+	for (const [type, handler] of Object.entries(options.on ?? {})) if (typeof handler === "function") actor.on(type, handler);
+	const sessionApi = { settled: async () => {
+		const result = settled && lastResult !== void 0 ? lastResult : await new Promise((resolve) => {
+			waiters.push(resolve);
+		});
+		await journalAtSettle;
+		return result;
+	} };
+	if (options.signal) {
+		if (options.signal.aborted) {
+			settle({
+				status: "error",
+				cause: "aborted",
+				error: options.signal.reason ?? /* @__PURE__ */ new Error("Aborted"),
+				snapshot: actor.getSnapshot()
+			});
+			return sessionApi;
+		}
+		options.signal.addEventListener("abort", onAbort);
+	}
+	onTrace({
+		type: "run.start",
+		...resolvedInput !== void 0 ? { input: resolvedInput } : {},
+		...effectiveSnapshot !== void 0 ? { snapshot: effectiveSnapshot } : {},
+		...resumeEventToSend !== void 0 ? { event: resumeEventToSend } : {}
+	});
+	actorStarted = true;
+	actor.start();
+	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(resumeEventToSend);
+	}
+	return sessionApi;
+}
+/**
+* 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
+* {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
+* transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
+* the manual `event.type === '@xstate.transition'` filtering and the snapshot/
+* actorRef casts.
+*/
+function inspectTransitions(handler) {
+	return (inspectionEvent) => {
+		if (inspectionEvent.type !== "@xstate.transition") return;
+		handler(inspectionEvent.snapshot, inspectionEvent.actorRef);
+	};
+}
+/**
+* An xstate `inspect` handler that emits `machine.transition` trace events onto
+* `onTrace`, sharing the SAME versioned envelope and per-root-actor `seq`
+* registry as {@link provideExecutors}' `onTrace`. Pair the two on one actor to
+* get a single ordered trace stream (request + transition events) for the
+* uncontrolled path:
+*
+* ```ts
+* const bound = provideExecutors(machine, executors, { onTrace });
+* const actor = createActor(bound, { inspect: traceTransitions(onTrace) });
+* ```
+*
+* Only ROOT-actor transitions are traced (matching `runAgent`'s
+* `machine.transition`); child-actor transitions are ignored. Attribute the
+* event via its envelope `runId`.
+*
+* By design this path has NO `run.start`/`run.end` events: `createActor` has no
+* run boundary the way `runAgent` does, so the stream starts at the actor's
+* first transition. It also does NOT emit `emit` trace events: in this xstate
+* build emitted events are delivered through `actor.on(...)`, not the inspection
+* protocol, so they are not observable from an `inspect` handler — subscribe
+* with `actor.on('*', ...)` if you need them.
+*/
+function traceTransitions(onTrace) {
+	return (inspectionEvent) => {
+		if (inspectionEvent.type !== "@xstate.transition") return;
+		const actorRef = inspectionEvent.actorRef;
+		if (actorRef?._parent) return;
+		onTrace(stampRootTrace(actorRef, {
+			type: "machine.transition",
+			snapshot: inspectionEvent.snapshot,
+			event: inspectionEvent.event
+		}));
+	};
+}
+function isIdleSnapshot(snapshot) {
+	if (snapshot.status !== "active") return false;
+	if (Object.values(snapshot.children ?? {}).some((child) => {
+		const childSnapshot = child?.getSnapshot?.();
+		if (childSnapshot?.status !== "active") return false;
+		if ((0, xstate.isMachineSnapshot)(childSnapshot)) return !isIdleSnapshot(childSnapshot);
+		return true;
+	})) return false;
+	return !(0, xstate.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;
+	}) || require_decision.getAcceptedEvents(snapshot).length > 0;
+}
+//#endregion
+Object.defineProperty(exports, "AGENT_TRACE_SCHEMA_VERSION", {
+	enumerable: true,
+	get: function() {
+		return AGENT_TRACE_SCHEMA_VERSION;
+	}
+});
+Object.defineProperty(exports, "AgentMaxModelCallsExceededError", {
+	enumerable: true,
+	get: function() {
+		return AgentMaxModelCallsExceededError;
+	}
+});
+Object.defineProperty(exports, "AgentSnapshotDivergedError", {
+	enumerable: true,
+	get: function() {
+		return AgentSnapshotDivergedError;
+	}
+});
+Object.defineProperty(exports, "bindChildMachineForProvide", {
+	enumerable: true,
+	get: function() {
+		return bindChildMachineForProvide;
+	}
+});
+Object.defineProperty(exports, "bindDecisionForProvide", {
+	enumerable: true,
+	get: function() {
+		return bindDecisionForProvide;
+	}
+});
+Object.defineProperty(exports, "bindTextForProvide", {
+	enumerable: true,
+	get: function() {
+		return bindTextForProvide;
+	}
+});
+Object.defineProperty(exports, "executeAgentRequest", {
+	enumerable: true,
+	get: function() {
+		return executeAgentRequest;
+	}
+});
+Object.defineProperty(exports, "getConfiguredInvokeSrcs", {
+	enumerable: true,
+	get: function() {
+		return getConfiguredInvokeSrcs;
+	}
+});
+Object.defineProperty(exports, "getPendingInvokes", {
+	enumerable: true,
+	get: function() {
+		return getPendingInvokes;
+	}
+});
+Object.defineProperty(exports, "initialAgentStep", {
+	enumerable: true,
+	get: function() {
+		return initialAgentStep;
+	}
+});
+Object.defineProperty(exports, "inspectTransitions", {
+	enumerable: true,
+	get: function() {
+		return inspectTransitions;
+	}
+});
+Object.defineProperty(exports, "isAgentIdle", {
+	enumerable: true,
+	get: function() {
+		return isAgentIdle;
+	}
+});
+Object.defineProperty(exports, "isStateMachineLogic", {
+	enumerable: true,
+	get: function() {
+		return isStateMachineLogic;
+	}
+});
+Object.defineProperty(exports, "rejectAgentStep", {
+	enumerable: true,
+	get: function() {
+		return rejectAgentStep;
+	}
+});
+Object.defineProperty(exports, "resolveAgentStep", {
+	enumerable: true,
+	get: function() {
+		return resolveAgentStep;
+	}
+});
+Object.defineProperty(exports, "runAgent", {
+	enumerable: true,
+	get: function() {
+		return runAgent;
+	}
+});
+Object.defineProperty(exports, "serializeTraceEvent", {
+	enumerable: true,
+	get: function() {
+		return serializeTraceEvent;
+	}
+});
+Object.defineProperty(exports, "traceTransitions", {
+	enumerable: true,
+	get: function() {
+		return traceTransitions;
+	}
+});
+Object.defineProperty(exports, "transitionAgentStep", {
+	enumerable: true,
+	get: function() {
+		return transitionAgentStep;
+	}
+});