@statelyai/agent 2.0.0-alpha.10 → 2.0.0-alpha.12

package/dist/index.mjs

@@ -1,4 +1,2799 @@
-import { a as runAgent, c as setupAgent, i as inspectTransitions, l as appendMessages, n as IllegalResumeEventError, o as runAgentToCompletion, r as SnapshotVersionMismatchError, s as createAgentSchemas, t as AgentIdleError, u as messagesSchema } from "./run-agent-BoAOq_0Z.mjs";
-import { $ as validateSchemaSync, A as parseOutput, C as createTextLogic, E as isStructuredOutputSchema, G as getJsonSchemaSync, J as isStandardSchema, K as getMachineStructuralHash, Q as userMessage, T as getAgentOutputMode, U as getAgentMessages, V as assistantMessage, W as getJsonSchema, X as systemMessage, Y as persistSnapshot, Z as toolMessage, b as bindRequestExecutor, d as EVENT_TOOL_PREFIX, f as getAcceptedEvents, j as parseStructuredEnvelope, k as parseModelRef, l as renderDecisionAttempts, m as parseAgentEvent, n as PLAN_DONE_EVENT_TYPE, p as matchesEventPattern, q as getStateMeta, t as DecisionExhaustedError, u as resolveDecision, x as buildEnvelopeSchema } from "./decision-CQdrKc8k.mjs";
-import { a as lintAgentMachine, c as getAgentRequests, d as resolveAgentStep, f as transitionAgentStep, i as explorePaths, l as initialAgentStep, n as assertAgentMachine, o as simulateAgent, r as canReach, s as executeAgentRequest, t as AgentLintError, u as resolveAgentRequests } from "./src-DUeIFjv-.mjs";
-export { AgentIdleError, AgentLintError, DecisionExhaustedError, EVENT_TOOL_PREFIX, IllegalResumeEventError, PLAN_DONE_EVENT_TYPE, SnapshotVersionMismatchError, appendMessages, assertAgentMachine, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createTextLogic, executeAgentRequest, explorePaths, getAcceptedEvents, getAgentMessages, getAgentOutputMode, getAgentRequests, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initialAgentStep, inspectTransitions, isStandardSchema, isStructuredOutputSchema, lintAgentMachine, matchesEventPattern, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, persistSnapshot, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, transitionAgentStep, userMessage, validateSchemaSync };
+import { t as AgentError } from "./errors-CeSXQx0v.mjs";
+import { _ as resolveAgentRequests, a as AgentReplayDivergenceError, b as appendMessages, c as diffEventLogs, d as initEntry, f as replay, g as initialAgentStep, h as getInvokeEffectMetadata, i as AGENT_USAGE_EVENT_TYPE, l as getAgentEffects, m as executeAgentRequest, n as setupAgent, o as AgentReplayMachineMismatchError, p as verifyReplay, r as AGENT_INIT_EVENT_TYPE, s as createReplayEntry, t as createAgentSchemas, u as getCallUsage, v as resolveAgentStep, x as messagesSchema, y as transitionAgentStep } from "./setup-agent-DAZZSjDS.mjs";
+import { A as parseStructuredEnvelope, D as normalizeGeneratorResult, E as isTextLogic, F as getMachineSuspensionPredicate, G as getJsonSchemaSync, H as findNonSerializableContextPaths, I as getRegisteredAgentExecutionOptions, J as isStandardSchema, K as getMachineStructuralHash, L as isUnboundPlaceholder, N as executorBoundLogics, O as parseModelRef, P as getMachineStaticTransitionTargets, Q as userMessage, S as createTextLogic, T as getAgentOutputMode, U as getAgentMessages, V as assistantMessage, W as getJsonSchema, X as systemMessage, Y as persistSnapshot, Z as toolMessage, b as buildEnvelopeSchema, c as isPlanLogic, d as getAcceptedEvents, f as parseAgentEvent, g as INTERPRET_SOURCE, k as parseOutput, l as renderDecisionAttempts, m as AGENT_USAGE_TOKEN_FIELDS, n as PLAN_DONE_EVENT_TYPE, o as initialPlanLedger, p as sanitizeEventToolName, q as getStateMeta, r as advancePlanLedger, s as isDecisionLogic, t as AgentDecisionExhaustedError, u as resolveDecision, w as extractCallUsage, y as bindRequestExecutor } from "./decision-BezSD_YC.mjs";
+import { a as assertEventLogStoreConformance, i as assertAgentLogEntry, n as AgentEventLogConflictError, o as assertJsonSerializable, r as NonSerializableAgentEventError, s as createInMemoryEventLogStore, t as AGENT_EVENT_SCHEMA_VERSION } from "./event-log-store-D7pWtIhb.mjs";
+import { createActor, createAsyncLogic, getNextTransitions } from "xstate";
+//#region src/internal/state-request-pass.ts
+async function runTextPhase(stateRequest, baseMessages, deps) {
+	const { model, system } = stateRequest;
+	const id = stateRequest.id ?? deps.nextRequestId();
+	const promptMessage = userMessage(stateRequest.prompt);
+	if (stateRequest.kind === "decision") return {
+		stateRequest,
+		id,
+		output: void 0,
+		appended: [promptMessage]
+	};
+	if (!deps.generateText) throw new Error("runAgent: a getRequests request needs a 'generateText' executor (or use kind: 'decision').");
+	const request = {
+		model,
+		...system !== void 0 ? { system } : {},
+		messages: [...baseMessages, promptMessage],
+		tools: {}
+	};
+	const agentRequest = {
+		kind: "text",
+		id,
+		src: INTERPRET_SOURCE,
+		mode: "generate",
+		input: request,
+		tools: {},
+		events: []
+	};
+	deps.consumeModelCall();
+	deps.onTrace?.({
+		type: "request.start",
+		request: agentRequest
+	});
+	let output;
+	try {
+		const raw = await deps.generateText(request, { signal: deps.signal });
+		output = await normalizeGeneratorResult(raw, id, { request });
+		const rawReasoning = raw?.reasoning;
+		const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
+		const usage = extractCallUsage(raw);
+		if (usage) deps.recordUsage?.(usage);
+		deps.onResult?.(agentRequest, {
+			output,
+			raw
+		});
+		deps.onTrace?.({
+			type: "request.end",
+			request: agentRequest,
+			output,
+			raw,
+			...reasoning !== void 0 ? { reasoning } : {},
+			...usage !== void 0 ? { usage } : {}
+		});
+	} catch (error) {
+		deps.onTrace?.({
+			type: "request.error",
+			request: agentRequest,
+			error
+		});
+		throw error;
+	}
+	return {
+		stateRequest,
+		id,
+		output,
+		appended: [promptMessage, assistantMessage(typeof output === "string" ? output : JSON.stringify(output))]
+	};
+}
+async function runAdvancePhase(plan, deps) {
+	const { stateRequest, id, output } = plan;
+	const { model, system } = stateRequest;
+	deps.appendToLog(...plan.appended);
+	if (stateRequest.kind !== "decision" && stateRequest.onDone !== void 0) {
+		const snapshot = deps.getSnapshot();
+		const resolved = typeof stateRequest.onDone === "function" ? stateRequest.onDone({
+			output,
+			snapshot,
+			messages: deps.messages
+		}) : stateRequest.onDone;
+		if (!resolved) return false;
+		const acceptedTypes = getAcceptedEvents(snapshot, { schemas: deps.schemas }).map((descriptor) => descriptor.type);
+		if (!acceptedTypes.includes(resolved.type)) throw new Error(`runAgent: getRequests request '${id}' resolved onDone to event '${resolved.type}', which the current state does not accept. Accepted: ${acceptedTypes.join(", ") || "(none)"}.`);
+		if (!snapshot.can(resolved)) return false;
+		deps.send(resolved);
+		return true;
+	}
+	const events = getAcceptedEvents(deps.getSnapshot(), {
+		schemas: deps.schemas,
+		...stateRequest.allowedEvents ? { eventTypes: stateRequest.allowedEvents } : {}
+	});
+	if (events.length === 0) return false;
+	if (!deps.decide) throw new Error(`runAgent: a getRequests request without 'onDone' needs a 'decide' executor to choose between events ${events.map((descriptor) => `'${descriptor.type}'`).join(", ")}. Provide request.onDone for deterministic advancement, or a 'decide' executor.`);
+	const chosen = await resolveDecision({
+		kind: "decision",
+		id,
+		model,
+		...system !== void 0 ? { system } : {},
+		messages: [...deps.messages],
+		events,
+		attempts: []
+	}, deps.decide, {
+		signal: deps.signal,
+		canTake: (event) => deps.getSnapshot().can(event)
+	});
+	if (deps.isSettled()) return false;
+	deps.appendToLog(assistantMessage(`[chose: ${chosen.type}]`));
+	deps.send(chosen);
+	return true;
+}
+/**
+* Executes one getRequests pass: all text calls concurrently against the
+* pass-start log, then per-request advancement sequentially in request
+* order. Returns whether ANY request sent an event — the host settles idle
+* when none did (otherwise an unchanged snapshot would re-produce the same
+* pass forever). Stops early (skipping remaining appends/sends) once
+* {@link StateRequestPassDeps.isSettled} reports the run is over. Throws on
+* executor/`onDone` errors — the host maps them to its error settle.
+*/
+async function runStateRequestPass(requests, deps) {
+	const baseMessages = [...deps.messages];
+	const plans = await Promise.all(requests.map((stateRequest) => runTextPhase(stateRequest, baseMessages, deps)));
+	let sentAny = false;
+	for (const plan of plans) {
+		if (deps.isSettled()) break;
+		sentAny = await runAdvancePhase(plan, deps) || sentAny;
+	}
+	return { sentAny };
+}
+//#endregion
+//#region src/run-agent.ts
+/**
+* Thrown by {@link runAgent} when resuming with a `snapshot` + `event` whose
+* `type` the restored state cannot accept (a type-level check via
+* {@link getAcceptedEvents}). A programmer/integration error, in the same
+* class as runAgent's bind-time throws — it throws rather than settling an
+* `error` result. A type-legal event a guard rejects is NOT this error (the
+* machine simply takes no transition). Opt out with
+* {@link RunAgentOptions.onIllegalResumeEvent} `'ignore'`.
+*/
+var AgentIllegalResumeEventError = class extends AgentError {
+	eventType;
+	acceptedTypes;
+	constructor(eventType, acceptedTypes) {
+		super("illegal-resume-event", `runAgent: cannot resume with event '${eventType}' — the restored state does not accept it. Accepted event types: ${acceptedTypes.length > 0 ? acceptedTypes.join(", ") : "(none)"}.`);
+		this.name = "AgentIllegalResumeEventError";
+		this.eventType = eventType;
+		this.acceptedTypes = acceptedTypes;
+	}
+};
+/**
+* Thrown by {@link runAgent} when resuming from a `snapshot` whose stamped
+* `agentMeta.version` differs from the current machine's version, under the
+* default `onVersionMismatch: 'throw'` and with no `migrateSnapshot` hook. The
+* structural fingerprint of the machine changed since the snapshot was
+* persisted (a state/transition/invoke was added, removed, or retargeted), so
+* the snapshot may no longer resume cleanly. `from` is the snapshot's version,
+* `to` the current machine's.
+*/
+var AgentSnapshotVersionMismatchError = class extends AgentError {
+	from;
+	to;
+	machineId;
+	constructor(from, to, machineId) {
+		super("snapshot-version-mismatch", `runAgent: cannot resume snapshot stamped with machine version '${from}' against machine '${machineId}' at version '${to}' — the machine's structure changed since the snapshot was persisted. Provide options.migrateSnapshot to adapt it, or set options.onVersionMismatch to 'warn'/'ignore' to proceed anyway.`);
+		this.name = "AgentSnapshotVersionMismatchError";
+		this.from = from;
+		this.to = to;
+		this.machineId = machineId;
+	}
+};
+/**
+* Thrown by {@link generateResult} when the run settles `idle` instead of
+* `done`: the machine paused for external input. Carries the idle `snapshot`
+* and `acceptedTypes` (the event types that could resume it, via
+* {@link getAcceptedEvents}). Use {@link runAgent} directly when idle is an
+* expected outcome you handle.
+*/
+var AgentIdleError = class extends AgentError {
+	snapshot;
+	acceptedTypes;
+	constructor(snapshot, acceptedTypes) {
+		super("agent-idle", `generateResult: the machine paused (idle) instead of completing. Resume it by calling runAgent with one of these events: ${acceptedTypes.length > 0 ? acceptedTypes.join(", ") : "(none)"}.`);
+		this.name = "AgentIdleError";
+		this.snapshot = snapshot;
+		this.acceptedTypes = acceptedTypes;
+	}
+};
+/**
+* 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",
+	"eventId",
+	"reasoning",
+	"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 {@link persistSnapshot}, 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;
+var AgentMaxModelCallsExceededError = class extends AgentError {
+	constructor() {
+		super("max-model-calls-exceeded", "runAgent exceeded maxModelCalls.");
+		this.name = "AgentMaxModelCallsExceededError";
+	}
+};
+function wrapsDecisionExhausted(error) {
+	let current = error;
+	for (let depth = 0; depth < 10 && current != null; depth++) {
+		if (current instanceof 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 isStateMachine(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, options) {
+	assertMachineBindable(machine, effectiveSources, options, {
+		isChild: false,
+		childPath: "",
+		rebindable: true,
+		visited: new Set([machine])
+	});
+}
+function assertMachineBindable(machine, effectiveSources, options, 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 (isStateMachine(src)) {
+				assertChildMachineBindable(src, src, stateName, options, ctx);
+				continue;
+			}
+			if ((isTextLogic(src) || isDecisionLogic(src) || isPlanLogic(src)) && !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 (isStateMachine(logic)) {
+			assertChildMachineBindable(logic, src, stateName, options, ctx);
+			continue;
+		}
+		if (src === "agent.userInput") continue;
+		if (isDecisionLogic(logic)) {
+			if (executorBoundLogics.has(logic)) continue;
+			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, "decision");
+			if (!options.hasDecide) throw new Error(`runAgent: ${where} '${stateName}' invokes decision source '${src}' but no 'decide' executor was provided to runAgent(...).`);
+			continue;
+		}
+		if (isPlanLogic(logic)) {
+			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, "plan");
+			if (!options.hasDecide) throw new Error(`runAgent: ${where} '${stateName}' invokes plan source '${src}' but no 'decide' executor was provided to runAgent(...).`);
+			continue;
+		}
+		if (isTextLogic(logic)) {
+			if (executorBoundLogics.has(logic)) continue;
+			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, logic.mode === "stream" ? "streaming text" : "text");
+			if (logic.mode === "stream" && !options.hasStreamText) throw new Error(`runAgent: ${where} '${stateName}' invokes streaming text source '${src}' but no 'streamText' executor was provided to runAgent(...).`);
+			if (logic.mode !== "stream" && !options.hasGenerateText) throw new Error(`runAgent: ${where} '${stateName}' invokes text source '${src}' but no 'generateText' executor was provided to runAgent(...).`);
+			continue;
+		}
+		if (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, options, 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, options, {
+		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 for the reserved
+* `'@agent.usage'` type EXPLICITLY. A catch-all `on: { '*': … }` deliberately
+* does not count: a wildcard is a machine's own event vocabulary, not an
+* opt-in to a library-reserved event, and `snapshot.can(event)` alone cannot
+* tell the two apart (it answers "would this event be taken?", which a
+* wildcard makes true for everything). Gating delivery on the explicit
+* declaration is what keeps `@agent.usage` opt-in by construction — and keeps
+* a wildcard machine's context and event log byte-identical to a run without
+* the feature. @internal
+*/
+function declaresUsageTransition(snapshot) {
+	return getNextTransitions(snapshot).some((transition) => transition.eventType === AGENT_USAGE_EVENT_TYPE);
+}
+/** Reads the durable invoke id/src off the async actor's own ref (`self`). */
+function selfIdAndSrc(self) {
+	const ref = self;
+	return {
+		id: typeof ref?.id === "string" ? ref.id : "",
+		src: typeof ref?.src === "string" ? ref.src : ""
+	};
+}
+/**
+* The machine actor that INVOKED a decision/plan 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/plan 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 wrapTextLogicForRunAgent(logic, runCtx) {
+	return logic.withExecutor(async ({ request, self, signal }) => {
+		const { id, src } = selfIdAndSrc(self);
+		const executor = logic.mode === "stream" ? runCtx.streamText : runCtx.generateText;
+		if (!executor) throw new Error(`runAgent: 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.onTrace?.({
+			type: "request.start",
+			request: agentRequest
+		}, self);
+		try {
+			const raw = await executor(requestWithTools, {
+				onChunk: (chunk) => {
+					runCtx.onTrace?.({
+						type: "stream.chunk",
+						request: agentRequest,
+						chunk
+					}, self);
+					runCtx.onChunk?.(chunk, { request: agentRequest });
+				},
+				signal,
+				...runCtx.runId !== void 0 ? { runId: runCtx.runId } : {},
+				...id !== "" ? { requestId: id } : {}
+			});
+			const output = await normalizeGeneratorResult(raw, id, {
+				request,
+				onChunk: (chunk) => {
+					runCtx.onTrace?.({
+						type: "stream.chunk",
+						request: agentRequest,
+						chunk
+					}, self);
+					runCtx.onChunk?.(chunk, { request: agentRequest });
+				}
+			});
+			const rawReasoning = raw?.reasoning;
+			const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
+			const usage = extractCallUsage(raw);
+			if (usage) runCtx.recordUsage?.(usage, {
+				kind: "text",
+				...id !== "" ? { id } : {},
+				...src !== "" ? { src } : {},
+				model: request.model,
+				...request.name !== void 0 ? { name: request.name } : {}
+			}, self);
+			runCtx.onResult?.(agentRequest, {
+				output,
+				raw
+			});
+			runCtx.onTrace?.({
+				type: "request.end",
+				request: agentRequest,
+				output,
+				raw,
+				...reasoning !== void 0 ? { reasoning } : {},
+				...usage !== void 0 ? { usage } : {}
+			}, self);
+			return { output };
+		} catch (error) {
+			runCtx.onTrace?.({
+				type: "request.error",
+				request: agentRequest,
+				error
+			}, self);
+			throw error;
+		}
+	});
+}
+function createCountingDecide(runCtx, self, kind = "decision") {
+	return async (attemptRequest) => {
+		runCtx.consumeModelCall();
+		runCtx.onTrace?.({
+			type: "request.start",
+			request: attemptRequest
+		}, self);
+		try {
+			const result = await runCtx.decide(runCtx.runId !== void 0 ? {
+				...attemptRequest,
+				runId: runCtx.runId
+			} : attemptRequest);
+			const usage = extractCallUsage(result);
+			if (usage) {
+				const { src } = selfIdAndSrc(self);
+				runCtx.recordUsage?.(usage, {
+					kind,
+					...attemptRequest.id ? { id: attemptRequest.id } : {},
+					...src !== "" ? { src } : {},
+					model: attemptRequest.model
+				}, self);
+			}
+			runCtx.onResult?.(attemptRequest, {
+				output: result.event,
+				raw: result
+			});
+			runCtx.onTrace?.({
+				type: "request.end",
+				request: attemptRequest,
+				output: result.event,
+				raw: result,
+				...usage !== void 0 ? { usage } : {}
+			}, self);
+			return result;
+		} catch (error) {
+			runCtx.onTrace?.({
+				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,
+* mirroring {@link createRunAgentPlanLogic}) 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 createRunAgentDecisionLogic(logic, runCtx) {
+	const decisionLogic = createAsyncLogic({ run: async ({ input, signal, self }) => {
+		if (!runCtx.decide) throw new Error("runAgent: no 'decide' executor provided.");
+		const { id } = selfIdAndSrc(self);
+		const declaredEventTypes = logic.allowedEventTypes?.(input);
+		await Promise.resolve();
+		const actorRef = invokingActorOf(self, runCtx);
+		const events = actorRef ? getAcceptedEvents(actorRef.getSnapshot(), {
+			schemas: runCtx.schemas,
+			eventTypes: declaredEventTypes
+		}) : [];
+		const chosen = await resolveDecision({
+			...logic.request(input),
+			id,
+			events
+		}, 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) => createRunAgentDecisionLogic(logic.withExecutor(nextExecute), runCtx)
+	});
+}
+/**
+* Builds the plan actor logic runAgent installs in place of the `agent.plan`
+* builtin: iterated {@link resolveDecision}. Each step re-reads the live
+* snapshot (so the candidate set reflects everything applied so far), asks
+* the `decide` executor for one legal event with the same validation/retry
+* loop a decision gets, and sends it to the machine. The loop ends on a
+* `stopOn` event, at `maxSteps`, when no legal candidate remains, or when an
+* applied event exits the invoking state (xstate cancels this invoke — the
+* machine simply moves on and the pending output is discarded).
+*
+* The invoke's `input` is resolved once, so the prompt cannot re-render
+* context between steps; instead the applied trail is appended to the prompt
+* each step so the model can see plan progress.
+*/
+function createRunAgentPlanLogic(logic, runCtx) {
+	const planLogic = createAsyncLogic({ run: async ({ input, signal, self }) => {
+		if (!runCtx.decide) throw new Error("runAgent: no 'decide' executor provided.");
+		const { id } = selfIdAndSrc(self);
+		const stopOn = new Set(input.stopOn ?? []);
+		const countingDecide = createCountingDecide(runCtx, self, "plan");
+		const base = logic.request(input);
+		let ledger = initialPlanLedger(logic, input);
+		const end = (stopped) => {
+			ledger = advancePlanLedger(logic, ledger, {
+				type: "plan.ended",
+				stopped
+			});
+			return ledger.output;
+		};
+		await Promise.resolve();
+		const invokingActor = invokingActorOf(self, runCtx);
+		while (ledger.context.stepsRemaining > 0) {
+			const actorRef = invokingActor;
+			if (!actorRef || signal.aborted) break;
+			const machineEvents = getAcceptedEvents(actorRef.getSnapshot(), {
+				schemas: runCtx.schemas,
+				eventTypes: logic.allowedEventTypes(input)
+			});
+			if (machineEvents.length === 0) return end("no-legal-events");
+			const doneDescriptor = {
+				type: PLAN_DONE_EVENT_TYPE,
+				toolName: sanitizeEventToolName(PLAN_DONE_EVENT_TYPE)
+			};
+			const events = machineEvents.some((event) => event.type === "agent.plan.done") ? machineEvents : [...machineEvents, doneDescriptor];
+			const applied = ledger.context.applied;
+			const trail = applied.length === 0 ? "" : `\n\nEvents already applied in this plan, in order:\n${applied.map((step) => JSON.stringify(step)).join("\n")}\nContinue from here; do not repeat applied events.`;
+			const doneHint = `\n\nWhen the request is fully handled (or no action is needed), choose '${PLAN_DONE_EVENT_TYPE}'.`;
+			const chosen = await resolveDecision({
+				...base,
+				id: `${id}[${applied.length}]`,
+				events,
+				prompt: `${base.prompt ?? ""}${trail}${doneHint}`,
+				attempts: []
+			}, countingDecide, {
+				maxRetries: input.maxRetries ?? logic.maxRetries,
+				signal,
+				canTake: (event) => {
+					if (event.type === "agent.plan.done" || stopOn.has(event.type)) return true;
+					return invokingActor ? invokingActor.getSnapshot().can(event) : true;
+				}
+			});
+			if (chosen.type === "agent.plan.done") return end("done");
+			actorRef.send(chosen);
+			ledger = advancePlanLedger(logic, ledger, {
+				type: "plan.applied",
+				event: chosen
+			});
+			await Promise.resolve();
+			if (stopOn.has(chosen.type)) return end("stop-event");
+		}
+		return end("max-steps");
+	} });
+	return Object.assign(planLogic, {
+		kind: "statelyai.planLogic",
+		maxRetries: logic.maxRetries,
+		request: logic.request,
+		allowedEventTypes: logic.allowedEventTypes
+	});
+}
+/**
+* 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;
+	if (!ref) return;
+	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 ? getMachineStructuralHash(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 {@link RunAgentBindContext.onTrace} sink used by the shared emission helpers. */
+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 deliverUsageToInvokingActor}.
+*/
+function provideBindContext(machine, executors, options) {
+	return {
+		generateText: executors.generateText,
+		streamText: executors.streamText,
+		decide: executors.decide,
+		onChunk: options.onChunk ? (chunk) => options.onChunk(chunk) : void 0,
+		onTrace: provideTraceSink(options.onTrace),
+		consumeModelCall: () => {},
+		recordUsage: (usage, source, self) => {
+			deliverUsageToInvokingActor(usage, source ?? {}, self);
+		},
+		actorHolder: { actorRef: void 0 },
+		schemas: getRegisteredAgentExecutionOptions(machine).schemas
+	};
+}
+/**
+* `provideExecutors`' counterpart to runAgent's `deliverUsageEvent`: after a
+* bound call settles with reported usage, send the reserved
+* `@agent.usage` event to the machine actor that INVOKED the request — read
+* off the settling request actor's `self._parent`, which under a live
+* `createActor` tree is always the invoking machine (there is no run-scoped
+* root actor on this path).
+*
+* Gated identically to runAgent: the invoking snapshot must be active, must
+* declare an `'@agent.usage'` transition EXPLICITLY (see
+* {@link declaresUsageTransition} — a catch-all `on: { '*' }` is not an opt-in),
+* and must be able to take the event. There is no cycle to settle in
+* uncontrolled mode, so there are no dropped stragglers.
+*
+* Delivery follows `provideExecutors`' binding boundary: only sources IT bound
+* report here, so an invoked child machine that was not itself passed through
+* `provideExecutors` reports nothing. @internal
+*/
+function deliverUsageToInvokingActor(usage, source, self) {
+	const actorRef = self?._parent;
+	if (!actorRef) return;
+	const snapshot = actorRef.getSnapshot();
+	if (snapshot?.status !== "active" || !declaresUsageTransition(snapshot)) return;
+	const event = {
+		type: AGENT_USAGE_EVENT_TYPE,
+		...source,
+		usage
+	};
+	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 wrapTextLogicForRunAgent}), 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 wrapTextLogicForRunAgent(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 createRunAgentDecisionLogic(logic, provideBindContext(machine, executors, options));
+}
+/**
+* Host-binds one `agent.plan` source for {@link provideExecutors}: runAgent's
+* plan wrapper (iterated snapshot-driven decisions, auto-delivery) with the same
+* request-level tracing runAgent emits, minus run-scoped counting. @internal
+*/
+function bindPlanForProvide(machine, logic, executors, options) {
+	return createRunAgentPlanLogic(logic, provideBindContext(machine, executors, options));
+}
+/**
+* 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/plan 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) {
+	if (visited.has(childMachine)) return childMachine;
+	const childVisited = new Set([...visited, childMachine]);
+	const sources = childMachine.sources.actors;
+	const wrapped = {};
+	for (const [key, logic] of Object.entries(sources)) {
+		if (isDecisionLogic(logic)) {
+			if (!executorBoundLogics.has(logic)) wrapped[key] = createRunAgentDecisionLogic(logic, runCtx);
+			continue;
+		}
+		if (isPlanLogic(logic)) {
+			wrapped[key] = createRunAgentPlanLogic(logic, runCtx);
+			continue;
+		}
+		if (isTextLogic(logic)) {
+			if (!executorBoundLogics.has(logic)) wrapped[key] = wrapTextLogicForRunAgent(logic, runCtx);
+			continue;
+		}
+		if (isStateMachine(logic)) {
+			const rebound = rebindChildMachine(logic, runCtx, childVisited);
+			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. The one exception
+* is `agent.userInput`: unhandled, it binds as a pending placeholder that
+* settles the run idle (with `pendingUserInputs`) instead of erroring.
+*
+* @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);
+* ```
+*
+* The `executors`' `generateText`/`streamText` accept the raw Vercel AI SDK
+* functions directly (`executors: { generateText, streamText }` with them
+* imported from `ai`) — their `{ text }`/`{ textStream }` results are unwrapped
+* natively. `decide` cannot be a raw AI SDK function: the tool-per-event mapping
+* lives in an adapter — use `createAiSdkExecutors` from '@statelyai/agent/ai-sdk'.
+*/
+async function runAgent(machine, options) {
+	return createAgentSession(machine, options, { oneShot: true }).settled();
+}
+/**
+* Session mode: {@link runAgent}'s engine with a long-lived actor. Use it when
+* the agent is a *session* fed by external events (chat turns, device or
+* timer events, a socket) rather than a one-shot job — you keep the log,
+* budget, traces, and idle semantics that bare `provideExecutors` +
+* `createActor` would forfeit.
+*
+* ```ts
+* const session = createAgentActor(machine, { input, executors });
+* let result = await session.settled();          // first quiescence
+* while (result.status === "idle") {
+*   session.actor.send(await nextUserEvent(result.snapshot));
+*   result = await session.settled();            // next quiescence, same log
+* }
+* session.stop();
+* ```
+*
+* Accepts the same options as {@link runAgent} (including `snapshot`/`events`
+* resume). Not yet supported in session mode: `getRequests` re-interpretation
+* across cycles behaves per-cycle exactly as in `runAgent`.
+*/
+function createAgentActor(machine, options) {
+	return createAgentSession(machine, options, { oneShot: false });
+}
+function createAgentSession(machine, options, lifecycle) {
+	const maxModelCalls = options.maxModelCalls ?? 100;
+	let modelCallCount = 0;
+	let budgetExceeded = false;
+	let warnedNonSerializable = false;
+	let warnedHeuristicIdle = false;
+	const runId = `run_${nextRunAgentTraceId++}`;
+	let traceSeq = 0;
+	const machineId = machine.config.id ?? machine.id ?? "(machine)";
+	const machineVersion = options.machineVersion ?? machine.version ?? getMachineStructuralHash(machine);
+	const agentMeta = {
+		machineId,
+		version: machineVersion
+	};
+	const stampAgentMeta = (snapshot) => {
+		if (snapshot && typeof snapshot === "object") snapshot.agentMeta = agentMeta;
+	};
+	const onTrace = (event) => {
+		options.onTrace?.({
+			schemaVersion: 1,
+			runId,
+			seq: ++traceSeq,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			machineId,
+			machineVersion,
+			...event
+		});
+	};
+	const consumeModelCall = () => {
+		if (budgetExceeded) throw new AgentMaxModelCallsExceededError();
+		if (modelCallCount + 1 > maxModelCalls) {
+			budgetExceeded = true;
+			throw new AgentMaxModelCallsExceededError();
+		}
+		modelCallCount += 1;
+	};
+	const tokenTotals = {};
+	const cycleGate = { isResolved: () => false };
+	const deliverUsageEvent = (usage, source) => {
+		const actorRef = actorHolder.actorRef;
+		if (!actorRef) return;
+		const event = {
+			type: AGENT_USAGE_EVENT_TYPE,
+			...source,
+			usage
+		};
+		const snapshot = actorRef.getSnapshot();
+		if (snapshot?.status !== "active" || !declaresUsageTransition(snapshot)) return;
+		if (cycleGate.isResolved()) {
+			onTrace({
+				type: "usage.dropped",
+				event,
+				reason: "settled"
+			});
+			return;
+		}
+		if (!snapshot.can(event)) return;
+		actorRef.send(event);
+	};
+	const recordUsage = (usage, source = {}) => {
+		for (const field of AGENT_USAGE_TOKEN_FIELDS) {
+			const value = usage[field];
+			if (typeof value === "number" && Number.isFinite(value)) tokenTotals[field] = (tokenTotals[field] ?? 0) + value;
+		}
+		deliverUsageEvent(usage, source);
+	};
+	const runUsage = () => ({
+		...tokenTotals,
+		modelCalls: modelCallCount
+	});
+	const warnNonSerializableContext = (snapshot) => {
+		if (warnedNonSerializable || process.env.NODE_ENV === "production") return;
+		let offending = [];
+		try {
+			offending = 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 });
+	const effectiveSources = provided.sources.actors;
+	assertBindable(provided, effectiveSources, {
+		hasGenerateText: !!options.executors?.generateText,
+		hasDecide: !!options.executors?.decide,
+		hasStreamText: !!options.executors?.streamText
+	});
+	if (options.getRequests && !options.executors?.generateText && !options.executors?.decide) throw new Error("runAgent: 'getRequests' requires a 'generateText' and/or 'decide' executor — the returned requests run through them.");
+	const actorHolder = { actorRef: void 0 };
+	const runCtx = {
+		generateText: options.executors?.generateText,
+		streamText: options.executors?.streamText,
+		decide: options.executors?.decide,
+		onChunk: options.onChunk,
+		onResult: options.onResult,
+		onTrace,
+		consumeModelCall,
+		recordUsage,
+		actorHolder,
+		runId,
+		schemas: getRegisteredAgentExecutionOptions(machine).schemas
+	};
+	let userInputIsPlaceholder = false;
+	const wrappedSources = {};
+	for (const [key, logic] of Object.entries(effectiveSources)) {
+		if (key === "agent.userInput") {
+			if (options.userInput) {
+				const userInput = options.userInput;
+				wrappedSources[key] = createAsyncLogic({ run: async ({ input }) => await userInput(input) });
+			} else if (isUnboundPlaceholder(logic)) {
+				userInputIsPlaceholder = true;
+				wrappedSources[key] = createAsyncLogic({ run: () => new Promise(() => {}) });
+			}
+			continue;
+		}
+		if (isDecisionLogic(logic)) {
+			wrappedSources[key] = createRunAgentDecisionLogic(logic, runCtx);
+			continue;
+		}
+		if (isPlanLogic(logic)) {
+			wrappedSources[key] = createRunAgentPlanLogic(logic, runCtx);
+			continue;
+		}
+		if (isTextLogic(logic)) {
+			if (!executorBoundLogics.has(logic)) wrappedSources[key] = wrapTextLogicForRunAgent(logic, runCtx);
+			continue;
+		}
+		if (isStateMachine(logic)) {
+			const rebound = rebindChildMachine(logic, runCtx, new Set([machine]));
+			if (rebound !== logic) wrappedSources[key] = rebound;
+			continue;
+		}
+	}
+	const boundMachine = provided.provide({ actors: wrappedSources });
+	const declaredSuspensionPredicate = options.isSuspended ?? getMachineSuspensionPredicate(machine);
+	const isSuspended = declaredSuspensionPredicate ?? (() => false);
+	let effectiveSnapshot = options.snapshot;
+	if (effectiveSnapshot !== void 0) {
+		const from = effectiveSnapshot.agentMeta?.version ?? effectiveSnapshot.version;
+		if (from !== void 0 && from !== machineVersion) {
+			const info = {
+				from,
+				to: machineVersion
+			};
+			if (options.migrateSnapshot) effectiveSnapshot = options.migrateSnapshot(effectiveSnapshot, info);
+			else {
+				const mode = options.onVersionMismatch ?? "throw";
+				if (mode === "throw") throw new AgentSnapshotVersionMismatchError(from, machineVersion, machineId);
+				if (mode === "warn") console.warn(`runAgent: resuming a snapshot stamped with machine version '${from}' against machine '${machineId}' at version '${machineVersion}'. Structural changes may not resume cleanly.`);
+			}
+		}
+	}
+	const resumeEvents = options.events;
+	if (effectiveSnapshot === void 0 && options.events !== void 0 && options.events[0]?.event.type === "@agent.init") {
+		const { snapshot: replayedSnapshot } = replay(machine, resumeEvents, { machineVersion });
+		effectiveSnapshot = machine.getPersistedSnapshot(replayedSnapshot);
+	}
+	const machineOwnVersion = machine.version;
+	if (effectiveSnapshot !== void 0 && effectiveSnapshot.version !== machineOwnVersion) {
+		const aligned = Object.assign(Object.create(Object.getPrototypeOf(effectiveSnapshot)), effectiveSnapshot);
+		if (machineOwnVersion === void 0) delete aligned.version;
+		else aligned.version = machineOwnVersion;
+		effectiveSnapshot = aligned;
+	}
+	const priorMessages = getAgentMessages(effectiveSnapshot);
+	const messages = typeof options.messages === "function" ? [...options.messages([...priorMessages])] : [...priorMessages, ...options.messages ?? []];
+	const stampMessages = (snapshot) => {
+		if (!options.getRequests && !options.messages && messages.length === 0) return;
+		if (snapshot && typeof snapshot === "object") snapshot.messages = [...messages];
+	};
+	if (effectiveSnapshot !== void 0 && options.event !== void 0 && (options.onIllegalResumeEvent ?? "throw") === "throw") {
+		const acceptedTypes = getAcceptedEvents(createActor(boundMachine, { snapshot: effectiveSnapshot }).getSnapshot(), { schemas: runCtx.schemas }).map((descriptor) => descriptor.type);
+		const eventType = options.event.type;
+		if (!acceptedTypes.includes(eventType)) throw new AgentIllegalResumeEventError(eventType, acceptedTypes);
+	}
+	const replayEvents = [...resumeEvents ?? []];
+	const replayEventIds = /* @__PURE__ */ new Set();
+	for (let index = 0; index < replayEvents.length; index++) {
+		const entry = replayEvents[index];
+		assertAgentLogEntry(entry);
+		if (entry.index !== index) throw new Error(`runAgent events must be contiguous from index 0; found entry.index ${entry.index} at position ${index}.`);
+		if (entry.machineId !== machineId || entry.machineVersion !== machineVersion) throw new AgentReplayMachineMismatchError(entry.id, entry.index, {
+			machineId,
+			machineVersion
+		}, {
+			machineId: entry.machineId,
+			machineVersion: entry.machineVersion
+		});
+		if (replayEventIds.has(entry.id)) throw new Error(`runAgent events contain duplicate event id '${entry.id}'.`);
+		replayEventIds.add(entry.id);
+	}
+	const hasCompleteReplayHistory = replayEvents[0]?.event.type === "@agent.init" || effectiveSnapshot === void 0 && replayEvents.length === 0;
+	const appendReplayEvent = (event) => {
+		const entry = createReplayEntry(machine, replayEvents, event, {
+			machineVersion,
+			verification: hasCompleteReplayHistory
+		});
+		if (replayEventIds.has(entry.id)) throw new Error(`runAgent generated duplicate event id '${entry.id}'.`);
+		replayEventIds.add(entry.id);
+		replayEvents.push(entry);
+		options.onEvent?.(entry);
+		return entry;
+	};
+	if (replayEvents.length === 0 && effectiveSnapshot === void 0) {
+		const entry = initEntry(machine, options.input, { machineVersion });
+		replayEventIds.add(entry.id);
+		replayEvents.push(entry);
+		options.onEvent?.(entry);
+	}
+	return (() => {
+		let settled = false;
+		let finalized = false;
+		cycleGate.isResolved = () => settled;
+		let lastResult;
+		const waiters = [];
+		let idleTimer;
+		let actor;
+		let deliveringResumeEvent = options.event !== void 0;
+		const settle = (outcome) => {
+			if (settled) return;
+			settled = true;
+			const result = {
+				...outcome,
+				events: [...replayEvents],
+				usage: runUsage()
+			};
+			if (idleTimer !== void 0) clearTimeout(idleTimer);
+			stampAgentMeta(result.snapshot);
+			stampMessages(result.snapshot);
+			if ("persistedSnapshot" in result) {
+				stampAgentMeta(result.persistedSnapshot);
+				stampMessages(result.persistedSnapshot);
+			}
+			onTrace({
+				type: "run.end",
+				...outcome
+			});
+			if (lifecycle.oneShot || result.status !== "idle") {
+				finalized = true;
+				if (options.signal) options.signal.removeEventListener("abort", onAbort);
+				actor.stop();
+			}
+			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);
+			const pendingUserInputs = userInputIsPlaceholder ? collectPendingUserInputs(current) : [];
+			settle({
+				status: "idle",
+				snapshot: current,
+				...pendingUserInputs.length > 0 ? {
+					pendingUserInputs,
+					persistedSnapshot: actor.getPersistedSnapshot()
+				} : {}
+			});
+		};
+		let interpreting = false;
+		let interpretSeq = 0;
+		const appendToLog = (...items) => {
+			messages.push(...items);
+			if (options.onMessage) {
+				const info = {
+					runId,
+					machineId,
+					machineVersion
+				};
+				for (const item of items) options.onMessage(item, info);
+			}
+		};
+		const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
+		const settleInterpretError = (error) => {
+			settle({
+				status: "error",
+				cause: runErrorCause(error),
+				error,
+				snapshot: actor.getSnapshot()
+			});
+		};
+		const passDeps = {
+			getSnapshot: () => actor.getSnapshot(),
+			send: (event) => actor.send(event),
+			isSettled: () => settled,
+			messages,
+			appendToLog,
+			generateText: runCtx.generateText,
+			decide: runCtx.decide ? createCountingDecide(runCtx, void 0) : void 0,
+			consumeModelCall,
+			recordUsage,
+			nextRequestId: () => `interpret_${++interpretSeq}`,
+			onTrace,
+			onResult: runCtx.onResult,
+			schemas: runCtx.schemas,
+			signal: options.signal
+		};
+		const maybeInterpret = (snapshot) => {
+			if (!options.getRequests || settled) return false;
+			if (interpreting) return true;
+			let requested;
+			try {
+				requested = options.getRequests(snapshot, { messages });
+			} catch (error) {
+				settleInterpretError(error);
+				return true;
+			}
+			const requests = (Array.isArray(requested) ? requested : requested ? [requested] : []).filter((stateRequest) => Boolean(stateRequest));
+			if (requests.length === 0) return false;
+			interpreting = true;
+			runStateRequestPass(requests, passDeps).then(({ sentAny }) => {
+				if (settled || sentAny) return;
+				const current = actor.getSnapshot();
+				if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) settleIdle(current);
+			}).catch((error) => settleInterpretError(error)).finally(() => {
+				interpreting = false;
+				if (!settled) scheduleIdleCheck();
+			});
+			return true;
+		};
+		const scheduleIdleCheck = () => {
+			if (idleTimer !== void 0) clearTimeout(idleTimer);
+			idleTimer = setTimeout(() => {
+				idleTimer = void 0;
+				if (settled) return;
+				const current = actor.getSnapshot();
+				if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+					if (!maybeInterpret(current)) {
+						if (!declaredSuspensionPredicate && current.status === "active" && !warnedHeuristicIdle && process.env.NODE_ENV !== "production") {
+							warnedHeuristicIdle = true;
+							console.warn("[@statelyai/agent] runAgent settled idle via the timing heuristic (no suspension predicate declared). This is best-effort; for deterministic idle detection, declare setupAgent({ isSuspended }) or pass runAgent(machine, { isSuspended }), e.g. (s) => s.hasTag('waiting').");
+						}
+						settleIdle(current);
+					}
+				}
+			}, 0);
+		};
+		actor = createActor(boundMachine, {
+			input: options.input,
+			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) {
+					if (finalized) return;
+					settled = false;
+					lastResult = void 0;
+				}
+				const snapshot = event.snapshot;
+				let eventId;
+				if (event.event.type !== "@xstate.init" && (event.sourceRef !== event.actorRef || event.event.type === "xstate.timer")) eventId = appendReplayEvent(event.event).id;
+				else if (event.event.type === "@xstate.init") eventId = replayEvents[0]?.event.type === "@agent.init" ? replayEvents[0].id : void 0;
+				onTrace({
+					type: "machine.transition",
+					snapshot,
+					event: event.event,
+					...eventId !== void 0 ? { eventId } : {}
+				});
+				options.onTransition?.(snapshot, 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 && isSuspended(snapshot) && isIdleSnapshot(snapshot, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+					if (!maybeInterpret(snapshot)) settleIdle(snapshot);
+					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 = {
+			actor,
+			get events() {
+				return replayEvents;
+			},
+			usage: runUsage,
+			settled: () => settled && lastResult !== void 0 ? Promise.resolve(lastResult) : new Promise((resolve) => {
+				waiters.push(resolve);
+			}),
+			stop: () => {
+				actor.stop();
+			}
+		};
+		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",
+			...options.input !== void 0 ? { input: options.input } : {},
+			...effectiveSnapshot !== void 0 ? { snapshot: effectiveSnapshot } : {},
+			...options.event !== void 0 ? { event: options.event } : {}
+		});
+		actor.start();
+		if (options.event) {
+			deliveringResumeEvent = false;
+			actor.send(options.event);
+		}
+		return sessionApi;
+	})();
+}
+/**
+* Runs an agent machine to a **final state**, for run-to-done flows where an
+* idle pause is unexpected. Wraps {@link runAgent}:
+*
+* - `done` → resolves with the done result: `result.output` (the machine's
+*   `OutputFrom`) plus metadata — `result.snapshot`, the replayable
+*   `result.events`, and the aggregated `result.usage` — the same shape
+*   `generateText` users expect (`text` + call metadata).
+* - `idle` → throws {@link AgentIdleError} carrying the idle snapshot and the
+*   event types that could resume it.
+* - `error` → throws `result.error` when it is an `Error`; otherwise wraps it
+*   in an `Error` whose `.cause` is the {@link RunAgentErrorCause} and whose
+*   `.error` is the raw thrown value.
+*
+* Use {@link runAgent} directly when idle is an expected outcome you handle
+* (human-in-the-loop, resumable flows); use `generateResult` when the
+* machine is meant to run straight through to a final state.
+*/
+async function generateResult(machine, options) {
+	const result = await runAgent(machine, options);
+	if (result.status === "done") return result;
+	if (result.status === "idle") {
+		const acceptedTypes = getAcceptedEvents(result.snapshot, { schemas: getRegisteredAgentExecutionOptions(machine).schemas }).map((descriptor) => descriptor.type);
+		throw new AgentIdleError(result.snapshot, acceptedTypes);
+	}
+	if (result.error instanceof Error) throw result.error;
+	const wrapped = /* @__PURE__ */ new Error(`generateResult: run failed with cause '${result.cause}'.`);
+	wrapped.cause = result.cause;
+	wrapped.error = result.error;
+	throw wrapped;
+}
+/**
+* Wraps a `(snapshot, actorRef) => void` handler into a function usable as
+* {@link RunAgentOptions.inspect}: it filters the raw inspection stream to
+* `@xstate.transition` events and hands the handler the typed
+* {@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, { ignoreUserInputChildren }) {
+	if (snapshot.status !== "active") return false;
+	if (Object.values(snapshot.children ?? {}).some((child) => {
+		const ref = child;
+		if (ignoreUserInputChildren && ref?.src === "agent.userInput") return false;
+		return ref?.getSnapshot?.()?.status === "active";
+	})) return false;
+	return !getNextTransitions(snapshot).some((transitionDef) => transitionDef.eventType === "" || transitionDef.eventType.startsWith("xstate.after"));
+}
+function collectPendingUserInputs(snapshot) {
+	const pending = [];
+	for (const [id, child] of Object.entries(snapshot.children ?? {})) {
+		const ref = child;
+		if (ref?.src !== "agent.userInput") continue;
+		const childSnapshot = ref.getSnapshot?.();
+		if (childSnapshot?.status !== "active") continue;
+		pending.push({
+			id,
+			input: childSnapshot.input
+		});
+	}
+	return pending;
+}
+//#endregion
+//#region src/agent-run.ts
+/**
+* Wraps {@link runAgent} in a canonical run-stream handle: the run's trace
+* events as a pull-based {@link AgentRun.events} async iterator, alongside the
+* unchanged {@link AgentRun.result} promise.
+*
+* Semantics:
+*
+* 1. **Starts immediately.** The underlying `runAgent` is invoked on this call,
+*    not on the first `events` iteration — work is already in flight when
+*    `createAgentRun` returns.
+* 2. **Buffer, don't stall.** Events are queued in an unbounded in-memory
+*    buffer as the run emits them; a slow or absent consumer never applies
+*    backpressure to the run. Once `run.end` is delivered, the iterator
+*    completes.
+* 3. **Composes `onTrace`.** If `options.onTrace` is passed, it still fires for
+*    every event — the wrapper adds queue delivery, it does not replace the
+*    caller's sink.
+* 4. **`result` mirrors `runAgent`.** Same resolution and rejection behavior
+*    (see {@link AgentRun.result}). A no-op rejection handler is attached
+*    internally so a caller who reads only `events` never trips an unhandled
+*    rejection on a bind-time throw; the returned promise still rejects for a
+*    caller who awaits it.
+* 5. **Resume is identical.** Options pass straight through, so starting from a
+*    persisted `snapshot` (+ resume `event`) streams that run's events from its
+*    own `run.start`, exactly as `runAgent` would run it.
+* 6. **Early termination does not cancel the run.** Breaking out of a
+*    `for await` (or calling `events.return()`) stops delivery, but the run
+*    keeps going and `result` still settles. Cancelling the run itself is
+*    future work — pass `options.signal` to abort it.
+* 7. **`events` is single-consumer.** See {@link AgentRun.events}.
+*/
+function createAgentRun(machine, options) {
+	const buffer = [];
+	const resolvers = [];
+	let closed = false;
+	let stopped = false;
+	const push = (event) => {
+		if (closed || stopped) return;
+		const resolve = resolvers.shift();
+		if (resolve) resolve({
+			value: event,
+			done: false
+		});
+		else buffer.push(event);
+	};
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		while (resolvers.length > 0) resolvers.shift()({
+			value: void 0,
+			done: true
+		});
+	};
+	const userOnTrace = options.onTrace;
+	const result = runAgent(machine, {
+		...options,
+		onTrace: (event) => {
+			push(event);
+			userOnTrace?.(event);
+			if (event.type === "run.end") close();
+		}
+	});
+	result.then(close, close);
+	return {
+		events: {
+			next() {
+				if (buffer.length > 0) return Promise.resolve({
+					value: buffer.shift(),
+					done: false
+				});
+				if (closed || stopped) return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+				return new Promise((resolve) => {
+					resolvers.push(resolve);
+				});
+			},
+			return() {
+				stopped = true;
+				buffer.length = 0;
+				while (resolvers.length > 0) resolvers.shift()({
+					value: void 0,
+					done: true
+				});
+				return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+			},
+			[Symbol.asyncIterator]() {
+				return this;
+			}
+		},
+		result
+	};
+}
+//#endregion
+//#region src/provide-executors.ts
+/**
+* Binds a machine's agent actor sources to a set of host `executors` in one
+* call, returning a `machine.provide(...)`-ed copy ready for a plain
+* `createActor(...)` — the uncontrolled-mode counterpart to {@link runAgent}.
+* No run loop, no idle settling: the returned machine drives itself, so
+*
+* ```ts
+* const actor = createActor(provideExecutors(machine, { generateText, decide }), { input });
+* actor.start();
+* ```
+*
+* behaves like a normal XState actor whose agent invokes now reach real models.
+*
+* Binding pass over `machine.sources.actors` (after merging
+* `options.actors`):
+* - `mode: 'generate'` text source → `executors.generateText`
+* - `mode: 'stream'` text source → `executors.streamText`
+* - decision / `agent.decide` source → `executors.decide` (snapshot-driven
+*   candidate events, guard `canTake`, and auto-delivery of the chosen event,
+*   mirroring `runAgent` but without its model-call counting)
+* - `agent.plan` source → `executors.decide` (iterated, same semantics)
+*
+* Pass `options.onTrace` to observe request-level trace events (identical in
+* shape to `runAgent`'s); pair it with {@link traceTransitions} on the actor's
+* `inspect` to also capture `machine.transition` events in the same stream.
+*
+* A source that already carries its own executor (`.withExecutor(...)`) is left
+* as-is. `agent.userInput` is left UNBOUND — an uncontrolled host handles idle
+* itself, so supply a handler via `options.actors` if the machine uses it.
+* Non-agent actors are untouched.
+*
+* Throws at bind time if a source needs an executor kind that `executors` does
+* not provide.
+*
+* v1 does NOT descend into invoked child state machines: a string-keyed child
+* machine source is left untouched, so a child with its own agent invokes needs
+* its own `provideExecutors(...)` (or `runAgent`, which does rebind children).
+*/
+function provideExecutors(machine, executors, options = {}) {
+	const bindOptions = {
+		onChunk: options.onChunk,
+		onTrace: options.onTrace
+	};
+	const provided = options.actors ? machine.provide({ actors: options.actors }) : machine;
+	const effectiveSources = provided.sources.actors;
+	const wrappedSources = {};
+	const invokedSrcs = getConfiguredInvokeSrcs(provided);
+	for (const [key, logic] of Object.entries(effectiveSources)) {
+		if (key === "agent.userInput") continue;
+		if (isDecisionLogic(logic)) {
+			if (executorBoundLogics.has(logic)) continue;
+			if (!executors.decide) {
+				if (invokedSrcs.has(key)) throw missingExecutorError(key, "decision", "decide");
+				continue;
+			}
+			wrappedSources[key] = bindDecisionForProvide(provided, logic, executors, bindOptions);
+			continue;
+		}
+		if (isPlanLogic(logic)) {
+			if (!executors.decide) {
+				if (invokedSrcs.has(key)) throw missingExecutorError(key, "plan", "decide");
+				continue;
+			}
+			wrappedSources[key] = bindPlanForProvide(provided, logic, executors, bindOptions);
+			continue;
+		}
+		if (isTextLogic(logic)) {
+			if (executorBoundLogics.has(logic)) continue;
+			if (!(logic.mode === "stream" ? executors.streamText : executors.generateText)) {
+				if (invokedSrcs.has(key)) throw logic.mode === "stream" ? missingExecutorError(key, "streaming text", "streamText") : missingExecutorError(key, "text", "generateText");
+				continue;
+			}
+			wrappedSources[key] = bindTextForProvide(provided, logic, executors, bindOptions);
+			continue;
+		}
+	}
+	return provided.provide({ actors: wrappedSources });
+}
+function missingExecutorError(src, kind, executor) {
+	return /* @__PURE__ */ new Error(`provideExecutors: actor source '${src}' is a ${kind} source but no '${executor}' executor was provided. Add it to the executors object, or bind the source with its own executor (logic.withExecutor(...)) before calling provideExecutors.`);
+}
+//#endregion
+//#region src/verify.ts
+const DECIDE_SRC = "agent.decide";
+const PLAN_SRC = "agent.plan";
+function normalizeInvokes(invoke) {
+	if (invoke === void 0 || invoke === null) return [];
+	return Array.isArray(invoke) ? invoke : [invoke];
+}
+function buildStateIndex(rootConfig) {
+	const index = /* @__PURE__ */ new Map();
+	const walk = (states, parentPath) => {
+		for (const [name, config] of Object.entries(states ?? {})) {
+			const path = parentPath ? `${parentPath}.${name}` : name;
+			const hasChildren = !!config.states && Object.keys(config.states).length > 0;
+			index.set(path, {
+				path,
+				name,
+				config,
+				parentPath,
+				type: config.type,
+				isFinal: config.type === "final",
+				isParallel: config.type === "parallel",
+				isCompound: hasChildren && config.type !== "parallel",
+				invokes: normalizeInvokes(config.invoke)
+			});
+			if (hasChildren) walk(config.states, path);
+		}
+	};
+	walk(rootConfig.states, "");
+	return index;
+}
+function childrenOf(index, parentPath) {
+	const out = [];
+	for (const node of index.values()) if (node.parentPath === parentPath) out.push(node);
+	return out;
+}
+function collectTransitionTargets(value, fromNode, index, out) {
+	if (value === void 0 || value === null) return;
+	if (Array.isArray(value)) {
+		for (const item of value) collectTransitionTargets(item, fromNode, index, out);
+		return;
+	}
+	if (typeof value === "function") {
+		out.opaque = true;
+		return;
+	}
+	if (typeof value === "string") {
+		resolveTargetString(value, fromNode, index, out);
+		return;
+	}
+	if (typeof value === "object") {
+		const { target, to } = value;
+		if (target !== void 0) {
+			collectTransitionTargets(target, fromNode, index, out);
+			return;
+		}
+		if (to !== void 0) {
+			collectTransitionTargets(to, fromNode, index, out);
+			return;
+		}
+	}
+}
+function resolveTargetString(target, fromNode, index, out) {
+	if (target.startsWith("#")) {
+		out.opaque = true;
+		return;
+	}
+	const resolved = target.startsWith(".") ? `${fromNode.path}.${target.slice(1)}` : fromNode.parentPath ? `${fromNode.parentPath}.${target}` : target;
+	if (index.has(resolved)) out.targets.push(resolved);
+	else out.opaque = true;
+}
+function outgoingTargets(node, index, staticTargets) {
+	const out = {
+		targets: [],
+		opaque: false
+	};
+	const { config } = node;
+	if (staticTargets) {
+		for (const target of staticTargets[node.path] ?? []) resolveTargetString(target, node, index, out);
+		return out;
+	}
+	for (const value of Object.values(config.on ?? {})) collectTransitionTargets(value, node, index, out);
+	collectTransitionTargets(config.always, node, index, out);
+	collectTransitionTargets(config.choice, node, index, out);
+	for (const value of Object.values(config.after ?? {})) collectTransitionTargets(value, node, index, out);
+	collectTransitionTargets(config.onDone, node, index, out);
+	for (const invoke of node.invokes) {
+		collectTransitionTargets(invoke.onDone, node, index, out);
+		collectTransitionTargets(invoke.onError, node, index, out);
+	}
+	return out;
+}
+function computeReachable(rootConfig, index, staticTargets) {
+	const reachable = /* @__PURE__ */ new Set();
+	const queue = [];
+	const markAncestors = (path) => {
+		let parent = index.get(path)?.parentPath ?? "";
+		while (parent) {
+			reachable.add(parent);
+			parent = index.get(parent)?.parentPath ?? "";
+		}
+	};
+	const enter = (path) => {
+		if (reachable.has(path)) return;
+		const node = index.get(path);
+		if (!node) return;
+		reachable.add(path);
+		queue.push(path);
+		markAncestors(path);
+		if (node.isParallel) for (const child of childrenOf(index, path)) enter(child.path);
+		else if (node.isCompound && node.config.initial) enter(`${path}.${node.config.initial}`);
+	};
+	if (rootConfig.type === "parallel") for (const child of childrenOf(index, "")) enter(child.path);
+	else if (rootConfig.initial) enter(rootConfig.initial);
+	while (queue.length > 0) {
+		const node = index.get(queue.shift());
+		if (!node) continue;
+		const { targets, opaque } = outgoingTargets(node, index, staticTargets);
+		for (const target of targets) enter(target);
+		if (opaque) for (const sibling of childrenOf(index, node.parentPath)) enter(sibling.path);
+	}
+	return reachable;
+}
+function ancestorChain(node, index) {
+	const chain = [];
+	let parent = node.parentPath;
+	while (parent) {
+		const parentNode = index.get(parent);
+		if (!parentNode) break;
+		chain.push(parentNode);
+		parent = parentNode.parentPath;
+	}
+	return chain;
+}
+function hasNonEmptyOn(config) {
+	return !!config.on && Object.keys(config.on).length > 0;
+}
+function decisionKindOf(src, actors) {
+	if (typeof src === "string") {
+		if (src === DECIDE_SRC) return "decision";
+		if (src === PLAN_SRC) return "plan";
+		const logic = actors[src];
+		if (isDecisionLogic(logic)) return "decision";
+		if (isPlanLogic(logic)) return "plan";
+		return;
+	}
+	if (isDecisionLogic(src)) return "decision";
+	if (isPlanLogic(src)) return "plan";
+}
+function isAgentLogicNeedingBinding(src) {
+	return (isTextLogic(src) || isDecisionLogic(src) || isPlanLogic(src)) && !executorBoundLogics.has(src);
+}
+function schemaExposesJson(schema) {
+	if (!schema) return false;
+	try {
+		return getJsonSchemaSync(schema) !== void 0;
+	} catch {
+		return false;
+	}
+}
+function isDeclaredOutputSchema(schema) {
+	if (!schema) return false;
+	let json;
+	try {
+		json = getJsonSchemaSync(schema);
+	} catch {
+		return false;
+	}
+	if (!json) return false;
+	const properties = json.properties;
+	const required = json.required;
+	return json.type === "object" && !!properties && Object.keys(properties).length > 0 || Array.isArray(required) && required.length > 0;
+}
+function checkUnreachableStates(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) if (!ctx.reachable.has(node.path)) out.push({
+		code: "unreachable-state",
+		severity: "error",
+		path: node.path,
+		message: `State '${node.path}' is unreachable: no transition, always, onDone, or onError target (from any reachable state) leads to it. Remove it or add a transition.`
+	});
+	return out;
+}
+function checkDecideWithoutEvents(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
+		const kind = decisionKindOf(invoke.src, ctx.actors);
+		if (!kind) continue;
+		const selfHandles = hasNonEmptyOn(node.config);
+		const ancestorHandles = ancestorChain(node, ctx.index).some((ancestor) => hasNonEmptyOn(ancestor.config));
+		const invokeObserves = invoke.onDone !== void 0;
+		if (selfHandles || ancestorHandles || invokeObserves) continue;
+		const srcName = typeof invoke.src === "string" ? invoke.src : "(inline logic)";
+		out.push({
+			code: "decide-without-events",
+			severity: "error",
+			path: node.path,
+			message: `State '${node.path}' invokes ${kind} source '${srcName}', but neither it nor any ancestor handles any event (no 'on:'), so the ${kind}'s chosen event can never be delivered. Add an 'on:' handler for the candidate events.`
+		});
+	}
+	return out;
+}
+function checkUnserializableContext(ctx) {
+	const contextSchema = ctx.schemas?.context;
+	if (!contextSchema) return [];
+	if (schemaExposesJson(contextSchema)) return [];
+	return [{
+		code: "unserializable-context",
+		severity: "warning",
+		path: "context",
+		message: "The context schema does not expose a JSON schema (e.g. a `z.custom` without a `jsonSchema` extension, such as a messages array), so its fields cannot be statically checked for JSON persist/resume round-tripping. This is expected for message transcripts; verify any other custom-typed context is JSON-serializable."
+	}];
+}
+function checkDirectObjectSrc(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
+		const src = invoke.src;
+		if (typeof src === "string" || !src || typeof src !== "object") continue;
+		if (!isAgentLogicNeedingBinding(src)) continue;
+		out.push({
+			code: "direct-object-src",
+			severity: "warning",
+			path: node.path,
+			message: `State '${node.path}' invokes a direct-object agent logic. Direct-object invoke srcs cannot be rebound by runAgent, so they inherit no host executors — call '.withExecutor(...)' on the logic, or register it as a string-keyed actor source (machine.provide({ actors: { name: logic } })) and invoke it by name.`
+		});
+	}
+	return out;
+}
+function checkFinalWithoutOutput(ctx) {
+	if (!isDeclaredOutputSchema(ctx.schemas?.output)) return [];
+	if (ctx.config.output !== void 0) return [];
+	const out = [];
+	for (const node of ctx.index.values()) {
+		if (node.parentPath !== "" || !node.isFinal) continue;
+		if (node.config.output === void 0) out.push({
+			code: "final-without-output",
+			severity: "error",
+			path: node.path,
+			message: `The machine declares an output schema, but top-level final state '${node.path}' has no 'output'. Its snapshot output will be undefined and fail the schema. Add an 'output' to this final state (or a root 'output').`
+		});
+	}
+	return out;
+}
+function outputFnReadsEvent(fn) {
+	return /\bevent\s*(?:\.|\?\.|\[)/.test(fn.toString());
+}
+function checkFinalOutputReadsEvent(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) {
+		if (node.parentPath !== "" || !node.isFinal) continue;
+		const output = node.config.output;
+		if (typeof output !== "function") continue;
+		if (!outputFnReadsEvent(output)) continue;
+		out.push({
+			code: "final-output-reads-event",
+			severity: "warning",
+			path: node.path,
+			message: `Final state '${node.path}' has an 'output' function that reads 'event'. Final-state 'output' functions are evaluated more than once with different events (the entering event, then the machine-done computation) under current xstate behavior, so 'event' is unreliable here. Read 'context' only; capture what you need from the entering event into context in the transition that targets this state. (This guard can relax if xstate guarantees a stable entering event across evaluations.)`
+		});
+	}
+	return out;
+}
+function isBuiltinOrWildcardEvent(eventType) {
+	return eventType === "*" || eventType.includes("*") || eventType.startsWith("xstate.") || eventType.startsWith("done.") || eventType.startsWith("error.");
+}
+function checkUndeclaredEvents(ctx) {
+	const declared = ctx.schemas?.events;
+	const declaredTypes = new Set(Object.keys(declared ?? {}));
+	if ([...declaredTypes].every((type) => type.startsWith("@agent."))) return [];
+	const out = [];
+	for (const node of ctx.index.values()) for (const eventType of Object.keys(node.config.on ?? {})) {
+		if (declaredTypes.has(eventType) || isBuiltinOrWildcardEvent(eventType)) continue;
+		out.push({
+			code: "undeclared-event",
+			severity: "warning",
+			path: node.path,
+			message: `State '${node.path}' handles event '${eventType}' in 'on:', but it is not declared in schemas.events and is not a builtin/wildcard pattern. If intentional its payload stays unvalidated; otherwise this is likely a typo.`
+		});
+	}
+	return out;
+}
+function checkMissingFinal(ctx) {
+	for (const node of ctx.index.values()) if (node.isFinal && ctx.reachable.has(node.path)) return [];
+	return [{
+		code: "missing-final",
+		severity: "warning",
+		path: "(root)",
+		message: "The machine has no reachable final state, so a run can never settle 'done' (only idle/looping). This is legal for agents that only idle, but verify it is intended."
+	}];
+}
+const LINT_CHECKS = [
+	checkUnreachableStates,
+	checkDecideWithoutEvents,
+	checkUnserializableContext,
+	checkDirectObjectSrc,
+	checkFinalWithoutOutput,
+	checkFinalOutputReadsEvent,
+	checkUndeclaredEvents,
+	checkMissingFinal
+];
+/**
+* Runs static structural checks over a built agent machine and returns the
+* findings ({@link AgentLintDiagnostic}[], empty when clean). Works for
+* TS-authored (`setupAgent(...).createMachine(...)`) and
+* `setupAgent.fromConfig(...)`-compiled machines alike, reading `machine.config`
+* plus the schemas/actor sources the library already retains per machine.
+*
+* No model calls, no API keys — a coding agent that emits an agent machine can
+* call this to catch dead states, undeliverable decisions, un-rebindable
+* invoke srcs, and output-contract gaps before ever running it.
+*
+* @example
+* ```ts
+* const errors = lintAgentMachine(machine).filter((d) => d.severity === 'error');
+* if (errors.length) throw new Error(errors.map((e) => `${e.path}: ${e.message}`).join('\n'));
+* ```
+*/
+function lintAgentMachine(machine, options = {}) {
+	const config = machine.config ?? {};
+	const index = buildStateIndex(config);
+	const reachable = computeReachable(config, index, getMachineStaticTransitionTargets(machine));
+	const registered = getRegisteredAgentExecutionOptions(machine);
+	const ctx = {
+		machine,
+		config,
+		index,
+		reachable,
+		schemas: registered.schemas,
+		actors: registered.actors ?? machine.sources?.actors ?? {}
+	};
+	const disabled = new Set(options.disable ?? []);
+	return LINT_CHECKS.flatMap((check) => check(ctx)).filter((d) => !disabled.has(d.code));
+}
+/**
+* Thrown by {@link assertAgentMachine} when lint finds failing diagnostics.
+* `diagnostics` holds the findings; the message lists them one per finding,
+* so a test runner's failure output reads like the CLI's lint report.
+*/
+var AgentLintError = class extends AgentError {
+	diagnostics;
+	constructor(machineId, diagnostics) {
+		const lines = diagnostics.map((d) => `  ${d.severity === "error" ? "error" : "warn "}  ${d.code}  ${d.path}\n         ${d.message}`);
+		super("lint-failed", `Agent machine '${machineId}' failed lint (${diagnostics.length} finding(s)):\n${lines.join("\n")}`);
+		this.name = "AgentLintError";
+		this.diagnostics = diagnostics;
+	}
+};
+/**
+* Asserts a machine passes {@link lintAgentMachine}: returns silently when
+* clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
+* otherwise. Fails on error-severity findings; set `warnings: true` to fail on
+* warnings too. The one-liner for tests and generation loops:
+*
+* @example
+* ```ts
+* test('agent machine is structurally sound', () => {
+*   assertAgentMachine(machine);
+* });
+* ```
+*/
+function assertAgentMachine(machine, options = {}) {
+	const diagnostics = lintAgentMachine(machine, options);
+	const failing = options.warnings ? diagnostics : diagnostics.filter((d) => d.severity === "error");
+	if (failing.length > 0) throw new AgentLintError(machine.id ?? "(machine)", failing);
+}
+function pendingInvokes(step) {
+	const out = [];
+	for (const action of step.actions) {
+		const metadata = getInvokeEffectMetadata(action);
+		if (typeof metadata?.src === "string" && typeof metadata.id === "string") out.push({
+			id: metadata.id,
+			src: metadata.src
+		});
+	}
+	return out;
+}
+function takeFromQueue(channel, src) {
+	const queue = channel?.[src];
+	if (queue && queue.length > 0) return {
+		found: true,
+		value: queue.shift()
+	};
+	return { found: false };
+}
+/**
+* Deterministically plays a machine through, resolving each request from a
+* {@link SimulationScript} instead of a model — no API keys, no model calls.
+* Runs on the pure step path ({@link initialAgentStep} etc.), so it exercises
+* the real transition logic. Returns the terminal `status`, final `snapshot`,
+* and a `trail` of every step taken.
+*
+* Throws a descriptive error when the script runs dry mid-request, naming the
+* pending request's kind, src, and id so the missing scripted response is
+* obvious.
+*
+* @example
+* ```ts
+* const { status, snapshot } = simulateAgent(machine, {
+*   input: { topic: 'state machines' },
+*   script: { decisions: { 'agent.decide': [{ type: 'END' }] } },
+* });
+* ```
+*/
+async function simulateAgent(machine, options) {
+	const maxSteps = options.maxSteps ?? 100;
+	const script = {
+		text: { ...options.script.text },
+		decisions: mapValues(options.script.decisions ?? {}, (arr) => [...arr]),
+		invokes: mapValues(options.script.invokes ?? {}, (arr) => [...arr])
+	};
+	let step = initialAgentStep(machine, options.input);
+	const trail = [];
+	for (let i = 0; i < maxSteps; i++) {
+		if (step.done) return {
+			status: "done",
+			snapshot: step.snapshot,
+			trail
+		};
+		const request = step.requests[0];
+		if (request) {
+			if (request.kind === "decision") {
+				const decisionSrc = new Map(pendingInvokes(step).map((invoke) => [invoke.id, invoke.src])).get(request.id) ?? request.id;
+				const taken = takeFromQueue(script.decisions, decisionSrc);
+				if (!taken.found) throw scriptDryError("decision", decisionSrc, request.id, request);
+				step = transitionAgentStep(machine, step, taken.value);
+				trail.push({
+					state: step.snapshot.value,
+					appliedEvent: taken.value
+				});
+				continue;
+			}
+			if (request.kind === "plan") {
+				const taken = takeFromQueue(script.decisions, request.src);
+				if (!taken.found) throw scriptDryError("decision", request.src, request.id, request);
+				const event = taken.value;
+				step = await resolveAgentRequests(machine, step, { decide: async () => ({ event }) });
+				trail.push({
+					state: step.snapshot.value,
+					appliedEvent: taken.value
+				});
+				continue;
+			}
+			const taken = takeFromQueue(script.text, request.src);
+			if (!taken.found) throw scriptDryError("text", request.src, request.id);
+			step = resolveAgentStep(machine, step, request, taken.value);
+			trail.push({
+				state: step.snapshot.value,
+				resolvedRequest: {
+					kind: "text",
+					src: request.src,
+					id: request.id
+				}
+			});
+			continue;
+		}
+		const [invoke] = pendingInvokes(step);
+		if (invoke) {
+			const taken = takeFromQueue(script.invokes, invoke.src);
+			if (!taken.found) throw scriptDryError("userInput", invoke.src, invoke.id);
+			step = resolveAgentStep(machine, step, invoke.id, taken.value);
+			trail.push({
+				state: step.snapshot.value,
+				resolvedRequest: {
+					kind: "userInput",
+					src: invoke.src,
+					id: invoke.id
+				}
+			});
+			continue;
+		}
+		return {
+			status: "idle",
+			snapshot: step.snapshot,
+			trail
+		};
+	}
+	return {
+		status: "exhausted",
+		snapshot: step.snapshot,
+		trail
+	};
+}
+function mapValues(obj, fn) {
+	return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, fn(value)]));
+}
+function scriptDryError(kind, src, id, request) {
+	const events = request?.kind === "decision" ? ` Candidate events: ${request.events.map((e) => e.type).join(", ") || "(none)"}.` : "";
+	return /* @__PURE__ */ new Error(`simulateAgent: script ran dry on a pending ${kind} request for src '${src}' (id '${id}'). Add a '${kind}' entry for '${src}' to the script.${events}`);
+}
+async function explore(machine, options, stopWhen) {
+	const maxDepth = options.maxDepth ?? 8;
+	const maxPaths = options.maxPaths ?? 200;
+	const textOutputs = options.textOutputs ?? {};
+	const reachedStates = /* @__PURE__ */ new Set();
+	const reachedValues = [];
+	const terminals = [];
+	const unexplored = [];
+	let prunedByGuard = 0;
+	let pathsExplored = 0;
+	let hitPathCap = false;
+	let witness;
+	const recordState = (snapshot) => {
+		const key = JSON.stringify(snapshot.value);
+		if (!reachedStates.has(key)) {
+			reachedStates.add(key);
+			reachedValues.push(snapshot.value);
+		}
+	};
+	const initial = initialAgentStep(machine, options.input);
+	recordState(initial.snapshot);
+	if (stopWhen?.(initial.snapshot)) witness = [];
+	const advance = (step) => {
+		let current = step;
+		for (let i = 0; i < 1e3; i++) {
+			if (current.done) return { step: current };
+			const request = current.requests[0];
+			if (request && request.kind === "text") {
+				if (!(request.src in textOutputs)) return {
+					step: current,
+					blockedSrc: request.src
+				};
+				current = resolveAgentStep(machine, current, request, textOutputs[request.src]);
+				recordState(current.snapshot);
+				continue;
+			}
+			if (request && (request.kind === "decision" || request.kind === "plan")) return { step: current };
+			const [invoke] = pendingInvokes(current);
+			if (invoke) {
+				if (!(invoke.src in textOutputs)) return {
+					step: current,
+					blockedSrc: invoke.src
+				};
+				current = resolveAgentStep(machine, current, invoke.id, textOutputs[invoke.src]);
+				recordState(current.snapshot);
+				continue;
+			}
+			return { step: current };
+		}
+		return { step: current };
+	};
+	const visit = async (step, path, depth) => {
+		if (witness !== void 0) return;
+		if (pathsExplored >= maxPaths) {
+			hitPathCap = true;
+			return;
+		}
+		const { step: settled, blockedSrc } = advance(step);
+		if (stopWhen?.(settled.snapshot)) {
+			witness = path;
+			return;
+		}
+		if (blockedSrc) {
+			pathsExplored++;
+			terminals.push({
+				status: "needs-output",
+				path,
+				state: settled.snapshot.value,
+				missingSrc: blockedSrc
+			});
+			unexplored.push(`needs-output: no canned output for src '${blockedSrc}' at path [${path.map((e) => e.type).join(", ")}]`);
+			return;
+		}
+		if (settled.done) {
+			pathsExplored++;
+			terminals.push({
+				status: "done",
+				path,
+				state: settled.snapshot.value
+			});
+			return;
+		}
+		const request = settled.requests[0];
+		const isPlan = request?.kind === "plan";
+		const branchEvents = request?.kind === "decision" || request?.kind === "plan" ? request.events.map((descriptor) => ({ type: descriptor.type })) : getAcceptedEvents(settled.snapshot).map((descriptor) => ({ type: descriptor.type }));
+		if (branchEvents.length === 0) {
+			pathsExplored++;
+			terminals.push({
+				status: "idle",
+				path,
+				state: settled.snapshot.value
+			});
+			return;
+		}
+		if (depth >= maxDepth) {
+			pathsExplored++;
+			terminals.push({
+				status: "max-depth",
+				path,
+				state: settled.snapshot.value
+			});
+			unexplored.push(`max-depth: stopped at path [${path.map((e) => e.type).join(", ")}]`);
+			return;
+		}
+		for (const event of branchEvents) {
+			if (witness !== void 0 || pathsExplored >= maxPaths) {
+				if (pathsExplored >= maxPaths) hitPathCap = true;
+				return;
+			}
+			if (!(isPlan && event.type === "agent.plan.done") && !settled.snapshot.can(event)) {
+				prunedByGuard++;
+				continue;
+			}
+			const next = isPlan ? await resolveAgentRequests(machine, settled, { decide: async () => ({ event }) }) : transitionAgentStep(machine, settled, event);
+			recordState(next.snapshot);
+			await visit(next, [...path, event], depth + 1);
+		}
+	};
+	if (witness === void 0) await visit(initial, [], 0);
+	return {
+		report: {
+			reachedStates: reachedValues,
+			terminals,
+			prunedByGuard,
+			unexplored,
+			pathsExplored,
+			hitPathCap
+		},
+		witness
+	};
+}
+/**
+* Enumerates a machine's decision and external-event branches to a bounded
+* depth, model-free, and reports which states are reached and how each path
+* terminates. At each decision request it forks one branch per candidate event
+* (guard-rejected candidates are counted in `prunedByGuard`, not explored); at
+* an idle wait it forks per externally-accepted event. A `agent.plan` request
+* forks the same way — one branch per candidate, including the reserved
+* `agent.plan.done` move — advancing each branch through the real plan protocol
+* (`resolveAgentRequests`), so a plan can consume several depth units. Text/`userInput` invokes
+* are resolved from `textOutputs` (a by-src canned-output map) — a missing src
+* halts that branch with a `needs-output` terminal rather than throwing.
+*
+* Combinatorics are bounded by `maxDepth` (default 8) and `maxPaths` (default
+* 200, reported via `hitPathCap`).
+*
+* @example
+* ```ts
+* const report = await explorePaths(refundMachine, { input: { request: 'x', amount: 5000 } });
+* // report.terminals → both 'refunded' and 'denied'; report.prunedByGuard → 1
+* ```
+*/
+async function explorePaths(machine, options = {}) {
+	return (await explore(machine, options)).report;
+}
+/**
+* Answers "can the machine reach `statePath`?" by exploring its branches (a
+* thin wrapper over {@link explorePaths}). Returns `{ canReach: true, witness }`
+* with the event sequence that reaches it, or `{ canReach: false }`.
+*
+* @example
+* ```ts
+* const { canReach, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
+* // canReach → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
+* ```
+*/
+async function canReach(machine, statePath, options = {}) {
+	const { witness } = await explore(machine, options, (snapshot) => {
+		try {
+			return snapshot.matches(statePath);
+		} catch {
+			return false;
+		}
+	});
+	return witness !== void 0 ? {
+		canReach: true,
+		witness
+	} : { canReach: false };
+}
+//#endregion
+//#region src/trajectory.ts
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Classifies one item. Event-shaped things (log entries, events) become events;
+* everything else is a state value. A snapshot is unwrapped to its `value`.
+* @internal
+*/
+function normalize(item) {
+	if (isRecord$2(item)) {
+		const nested = item["event"];
+		if (isRecord$2(nested) && typeof nested["type"] === "string") return {
+			kind: "event",
+			event: nested
+		};
+		if (typeof item["type"] === "string") return {
+			kind: "event",
+			event: item
+		};
+		if ("value" in item && "status" in item) return {
+			kind: "state",
+			value: item["value"]
+		};
+	}
+	return {
+		kind: "state",
+		value: item
+	};
+}
+/** Every leaf of a state value as a dot path (`{ review: 'editing' }` → `review.editing`). @internal */
+function statePaths(value) {
+	if (typeof value === "string") return [value];
+	if (!isRecord$2(value)) return [];
+	return Object.entries(value).flatMap(([key, child]) => statePaths(child).map((path) => `${key}.${path}`));
+}
+/**
+* A string expectation matches a state value when it names one of its leaves or
+* an ancestor of one, so `'review'` matches `{ review: 'editing' }`. @internal
+*/
+function stateMatchesPath(path, value) {
+	return statePaths(value).some((leaf) => leaf === path || leaf.startsWith(`${path}.`));
+}
+function deepEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, index) => deepEqual(item, b[index]));
+	if (!isRecord$2(a) || !isRecord$2(b)) return false;
+	const keys = Object.keys(a);
+	return keys.length === Object.keys(b).length && keys.every((key) => deepEqual(a[key], b[key]));
+}
+/**
+* Does one actual item satisfy one expected item?
+*
+* - A string expectation matches an event's `type`, or a state value it names.
+* - An event expectation matches an event with the same `type` whose other
+*   declared keys deep-equal, so payload details are opt-in.
+* - A state-value expectation matches structurally.
+* @internal
+*/
+function matchesItem(expected, actual) {
+	const actualItem = normalize(actual);
+	if (typeof expected === "string") return actualItem.kind === "event" ? actualItem.event.type === expected : stateMatchesPath(expected, actualItem.value);
+	const expectedItem = normalize(expected);
+	if (expectedItem.kind !== actualItem.kind) return false;
+	if (expectedItem.kind === "event" && actualItem.kind === "event") return Object.keys(expectedItem.event).every((key) => deepEqual(expectedItem.event[key], actualItem.event[key]));
+	return deepEqual(expectedItem.value, actualItem.value);
+}
+/**
+* Matches a run's trajectory against an expected one.
+*
+* Both trajectories may be state values (collected from `onTransition`) or
+* events (`result.events`, whose {@link AgentLogEntry} envelopes are unwrapped);
+* items are compared by shape, so `['prompting', 'drafting']` scores a state
+* path and `['PROMPT_SUBMITTED', 'SEND']` scores an event log with the same
+* call.
+*
+* Semantics are an ordered subsequence: every expected item must appear in
+* `actual`, in order, with gaps allowed. Pass `{ exact: true }` to require
+* equality instead.
+*
+* @example Trajectory assertions in a test
+* ```ts
+* const statePath: unknown[] = [];
+* const result = await runAgent(machine, {
+*   input,
+*   executors,
+*   onTransition: (snapshot) => statePath.push(snapshot.value),
+* });
+*
+* const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
+* expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
+* expect(matchesTrajectory(result.events, ['PROMPT_SUBMITTED', 'SEND']).matched).toBe(true);
+* ```
+*
+* @example Partial credit in an eval scorer
+* ```ts
+* const match = matchesTrajectory(output.statePath, expected.statePath);
+* return { name: 'state_path', score: match.score, metadata: { ...match.firstMiss } };
+* ```
+*/
+function matchesTrajectory(actual, expected, options = {}) {
+	const expectedCount = expected.length;
+	if (options.exact) {
+		let matchedCount = 0;
+		let firstMiss;
+		for (let index = 0; index < expectedCount; index++) {
+			if (index < actual.length && matchesItem(expected[index], actual[index])) {
+				matchedCount++;
+				continue;
+			}
+			firstMiss = {
+				index,
+				expected: expected[index],
+				searchedFrom: index
+			};
+			break;
+		}
+		const matched = !firstMiss && actual.length === expectedCount;
+		const denominator = Math.max(expectedCount, actual.length);
+		return {
+			matched,
+			matchedCount,
+			expectedCount,
+			score: matched ? 1 : denominator === 0 ? 1 : matchedCount / denominator,
+			...firstMiss ? { firstMiss } : {}
+		};
+	}
+	let cursor = 0;
+	let matchedCount = 0;
+	for (let index = 0; index < expectedCount; index++) {
+		const want = expected[index];
+		let found = -1;
+		for (let at = cursor; at < actual.length; at++) if (matchesItem(want, actual[at])) {
+			found = at;
+			break;
+		}
+		if (found === -1) return {
+			matched: false,
+			matchedCount,
+			expectedCount,
+			score: matchedCount / expectedCount,
+			firstMiss: {
+				index,
+				expected: want,
+				searchedFrom: cursor
+			}
+		};
+		matchedCount++;
+		cursor = found + 1;
+	}
+	return {
+		matched: true,
+		matchedCount,
+		expectedCount,
+		score: 1
+	};
+}
+//#endregion
+//#region src/scripted-executors.ts
+/**
+* Scripted executors — a keyless, deterministic stand-in for a model host.
+*
+* `createScriptedExecutors` builds a full `{ generateText, streamText, decide }`
+* set that plays back canned answers from FIFO queues, so `runAgent` (or
+* `provideExecutors`, or a bare `TextLogic.execute`) runs with no API key and no
+* network. It is the fastest way to see a machine run, and the least ceremonial
+* way to test one: same machine, same executor contract, scripted answers.
+*/
+/** Thrown when a scripted queue runs dry on a pending request. */
+var ScriptedExecutorsError = class extends AgentError {
+	constructor(message) {
+		super("scripted-executors-exhausted", message);
+		this.name = "ScriptedExecutorsError";
+	}
+};
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The only own keys an executor-result envelope carries. @internal */
+const TEXT_ENVELOPE_KEYS = new Set([
+	"output",
+	"usage",
+	"raw"
+]);
+/**
+* True when a scripted entry is the executor envelope rather than the output
+* value: it owns an `output` key and owns NOTHING outside the envelope's own
+* vocabulary. Bare `'output' in value` would swallow an output object's
+* siblings (`{ output: 'draft', confidence: 0.9 }` would lose `confidence`)
+* and would also match an inherited `output`. @internal
+*/
+function isTextEnvelope(value) {
+	return Object.hasOwn(value, "output") && Object.keys(value).every((key) => TEXT_ENVELOPE_KEYS.has(key));
+}
+/**
+* Resolves ONE scripted text entry to an executor result: a function entry is
+* called with the request, and the value is taken as the raw envelope only when
+* it is one (see {@link isTextEnvelope}). Shared with `runSeam`, whose routed
+* queues follow the same entry conventions. @internal
+*/
+async function resolveScriptedTextEntry(entry, request, info) {
+	const value = typeof entry === "function" ? await entry(request, info) : entry;
+	return isRecord$1(value) && isTextEnvelope(value) ? value : { output: value };
+}
+/**
+* Keyless executors that replay a script instead of calling a model. Every
+* slot is provided, so any machine binds; a request with no entry left throws a
+* descriptive error naming what was pending.
+*
+* Queues are consumed FIFO and are copied on creation, so the caller's arrays
+* are never mutated and each call builds a fresh, independent playthrough.
+* Entries may be plain values or functions of the request, which is how one
+* script serves a machine that loops or branches: route on `request.name` (the
+* `setupAgent({ requests })` key) or on the decision's candidate `events`.
+*
+* @example
+* ```ts
+* const result = await runAgent(moderationMachine, {
+*   input: { comment: 'honestly this update is terrible', trust: 20 },
+*   executors: createScriptedExecutors({
+*     decisions: [{ type: 'FLAG', reason: 'Borderline tone.' }],
+*   }),
+* });
+* ```
+*
+* @example Dynamic entries
+* ```ts
+* createScriptedExecutors({
+*   text: [(request) => `Draft about ${request.prompt}`],
+*   decisions: [(request) => ({ type: request.events[0]!.type })],
+* });
+* ```
+*/
+function createScriptedExecutors(script = {}) {
+	const decisions = [...script.decisions ?? []];
+	const text = [...script.text ?? []];
+	const nextText = async (request, info) => {
+		if (text.length === 0) throw new ScriptedExecutorsError(`createScriptedExecutors: script ran dry on a pending text request ${describeText(request)}. Add another entry to the script's \`text\` queue.`);
+		return resolveScriptedTextEntry(text.shift(), request, info);
+	};
+	return {
+		generateText: nextText,
+		streamText: async (request, info) => {
+			const result = await nextText(request, info);
+			if (typeof result.output === "string") info?.onChunk?.(result.output);
+			return result;
+		},
+		decide: async (request) => {
+			if (decisions.length === 0) throw new ScriptedExecutorsError(`createScriptedExecutors: script ran dry on a pending decision request (id '${request.id}'). Add another entry to the script's \`decisions\` queue. Candidate events: ${request.events.map((event) => event.type).join(", ") || "(none)"}.`);
+			const entry = decisions.shift();
+			const value = typeof entry === "function" ? await entry(request) : entry;
+			return typeof value.type === "string" ? { event: value } : value;
+		}
+	};
+}
+function describeText(request) {
+	return request.name ? `'${request.name}'` : `(model '${request.model}')`;
+}
+//#endregion
+//#region src/seam.ts
+/** Thrown when the call plan runs dry on a request that is not the live seam. */
+var SeamScriptError = class extends AgentError {
+	constructor(message) {
+		super("seam-script-exhausted", message);
+		this.name = "SeamScriptError";
+	}
+};
+function seamKeyOf(seam) {
+	return seam.request ?? seam.model;
+}
+function describeRequest(request) {
+	return request.name ? `'${request.name}' (model '${request.model}')` : `(model '${request.model}')`;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* The seam's own answer, for scoring. Our `{ output }` envelope is read
+* directly; a raw AI SDK `generateText` result contributes its `text`. A raw
+* STREAM result is left alone — the machine consumes that stream, and reading
+* it here would steal the chunks — so `seamOutput` is `undefined` for a
+* streaming candidate that returns one. Score its trajectory instead.
+* @internal
+*/
+async function seamOutputOf(result, request) {
+	if (!isRecord(result)) return;
+	if ("output" in result) return await result["output"];
+	if ("textStream" in result) return;
+	return await normalizeGeneratorResult(result, `seam '${request.name ?? request.model}'`, { request });
+}
+/**
+* Runs a machine end to end with one model call under test, and slices the run
+* at that call.
+*
+* The `before`/`after` slices are the point: `after.statePath` is the branch
+* the seam chose and `after.events` is the same question against the durable
+* log, both ready for `matchesTrajectory`. The state slice splits where the
+* state path stood when the seam answered; the event slice splits at the
+* seam's own effect completion (the first `xstate.done.*`/`xstate.error.*`
+* entry appended after the call was made).
+*
+* @example Keyless: the seam is scripted too, so the whole thing runs offline.
+* ```ts
+* const run = await runSeam(emailDrafter, {
+*   scripts: { promptEvaluator: [vague, complete], emailDrafter: [draft] },
+*   seam: { request: 'evaluatePrompt' },
+*   respond: ({ state }) => (state === 'prompting' ? { type: 'PROMPT_SUBMITTED', prompt } : null),
+* });
+*
+* matchesTrajectory(run.after.statePath, ['needsMoreInfo', 'drafting']);
+* ```
+*
+* @example A candidate prompt at the seam, scored against the same rows.
+* ```ts
+* const { generateText } = createAiSdkExecutors({ models });
+* const run = await runSeam(emailDrafter, { ...row, candidate: generateText });
+* ```
+*/
+async function runSeam(machine, options) {
+	const { seam, candidate } = options;
+	const queues = new Map(Object.entries(options.scripts ?? {}).map(([key, answers]) => [key, [...answers]]));
+	const statePath = [];
+	let calls = 0;
+	let seamMatches = 0;
+	let seamOutput;
+	let seamReached = false;
+	let callsBeforeSeam = -1;
+	let seamStateAt = 0;
+	let seamEventAt = 0;
+	let liveEvents = 0;
+	const scriptedAnswer = async (request, info, optional) => {
+		const key = request.name !== void 0 && queues.has(request.name) ? request.name : request.model;
+		const queue = queues.get(key);
+		if (!queue?.length) {
+			if (optional) return;
+			throw new SeamScriptError(`runSeam: no scripted answer left for request ${describeRequest(request)}. Add an entry to \`scripts.${key}\` — its last entry repeats, so one extra answer covers a longer branch.`);
+		}
+		return resolveScriptedTextEntry(queue.length === 1 ? queue[0] : queue.shift(), request, info);
+	};
+	const route = async (request, info) => {
+		const callIndex = calls++;
+		const isSeam = (seam.request !== void 0 ? request.name === seam.request : request.model === seam.model) && seamMatches++ === (seam.occurrence ?? 0);
+		const scripted = await scriptedAnswer(request, info, isSeam && candidate !== void 0);
+		if (!isSeam) return scripted;
+		seamReached = true;
+		callsBeforeSeam = callIndex;
+		seamStateAt = statePath.length;
+		seamEventAt = liveEvents;
+		if (!candidate) {
+			if (!scripted) throw new SeamScriptError(`runSeam: the seam '${seamKeyOf(seam)}' has no candidate and no scripted answer. Pass \`candidate\`, or script the seam's key.`);
+			seamOutput = scripted.output;
+			return scripted;
+		}
+		const result = await candidate(request, info);
+		seamOutput = await seamOutputOf(result, request);
+		return result;
+	};
+	const executors = {
+		...options.executors,
+		generateText: route,
+		streamText: async (request, info) => {
+			const result = await route(request, info);
+			const output = isRecord(result) ? result["output"] : void 0;
+			if (typeof output === "string") info?.onChunk?.(output);
+			return result;
+		}
+	};
+	let snapshot;
+	let event;
+	let events = [];
+	let result;
+	const maxTurns = options.maxTurns ?? 12;
+	for (let turn = 0; turn <= maxTurns; turn++) {
+		result = await runAgent(machine, {
+			...snapshot ? { snapshot } : { input: options.input },
+			...event ? { event } : {},
+			...options.isSuspended ? { isSuspended: options.isSuspended } : {},
+			...options.actors ? { actors: options.actors } : {},
+			events,
+			executors,
+			onEvent: () => {
+				liveEvents++;
+			},
+			onTransition: (next, causedBy) => {
+				if (turn > 0 && causedBy.type === "@xstate.init") return;
+				statePath.push(next.value);
+			}
+		});
+		events = result.events;
+		liveEvents = events.length;
+		if (result.status !== "idle" || turn === maxTurns) break;
+		const next = options.respond?.({
+			snapshot: result.snapshot,
+			state: result.snapshot.value,
+			meta: getStateMeta(result.snapshot),
+			turn,
+			result
+		});
+		if (!next) break;
+		event = next;
+		snapshot = result.snapshot;
+	}
+	let splitAt = events.length;
+	if (seamReached) {
+		splitAt = seamEventAt;
+		for (let index = seamEventAt; index < events.length; index++) {
+			const type = events[index].event.type;
+			if (type.startsWith("xstate.done") || type.startsWith("xstate.error")) {
+				splitAt = index;
+				break;
+			}
+		}
+	}
+	const splitStateAt = seamReached ? seamStateAt : statePath.length;
+	return {
+		result,
+		seamOutput,
+		callsBeforeSeam,
+		before: {
+			statePath: statePath.slice(0, splitStateAt),
+			events: events.slice(0, splitAt)
+		},
+		after: {
+			statePath: statePath.slice(splitStateAt),
+			events: events.slice(splitAt)
+		}
+	};
+}
+//#endregion
+export { AGENT_EVENT_SCHEMA_VERSION, AGENT_INIT_EVENT_TYPE, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentIdleError, AgentIllegalResumeEventError, AgentLintError, AgentReplayDivergenceError, AgentReplayMachineMismatchError, AgentSnapshotVersionMismatchError, NonSerializableAgentEventError, PLAN_DONE_EVENT_TYPE, appendMessages, assertAgentLogEntry, assertAgentMachine, assertEventLogStoreConformance, assertJsonSerializable, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentActor, createAgentRun, createAgentSchemas, createInMemoryEventLogStore, createReplayEntry, createScriptedExecutors, createTextLogic, diffEventLogs, executeAgentRequest, explorePaths, generateResult, getAcceptedEvents, getAgentEffects, getAgentMessages, getAgentOutputMode, getCallUsage, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initEntry, inspectTransitions, isStandardSchema, lintAgentMachine, matchesTrajectory, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, persistSnapshot, provideExecutors, renderDecisionAttempts, replay, resolveDecision, runAgent, runSeam, serializeTraceEvent, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage, verifyReplay };