@statelyai/agent 1.1.6 → 2.0.0-alpha.5

package/dist/src-CjpHDU8F.mjs

@@ -0,0 +1,2445 @@
+import { A as agentExecutionOptions, C as executeAgentTextRequest, D as normalizeGeneratorResult, E as isTextLogic, F as machineSuspensionPredicates, H as getMachineStructuralHash, I as missingActor, J as userMessage, L as assistantMessage, M as getMachineSuspensionPredicate, N as getRegisteredAgentExecutionOptions, P as isUnboundPlaceholder, R as findNonSerializableContextPaths, S as createTextLogic, V as getJsonSchemaSync, Y as validateSchemaSync, _ as PLAN_ACTOR, a as createPlanActor, c as isPlanLogic, f as getAcceptedEvents, g as DECIDE_ACTOR, h as sanitizeEventToolName, i as createDecideActor, j as executorBoundLogics, k as userInputActor, n as PLAN_DONE_EVENT_TYPE, o as initialPlanLedger, r as advancePlanLedger, s as isDecisionLogic, t as DecisionExhaustedError, u as resolveDecision, v as USER_INPUT_ACTOR, x as builtinTextActors } from "./decision-FTmbqSEe.mjs";
+import { createActor, createAsyncLogic, getNextTransitions, initialTransition, setup, transition } from "xstate";
+//#region src/messages.ts
+function addMessages(resolve) {
+	return (args) => {
+		const resolved = typeof resolve === "function" ? resolve(args) : resolve;
+		return [...args.context.messages, ...Array.isArray(resolved) ? resolved : [resolved]];
+	};
+}
+/**
+* Builds a transition-function result that appends one or more
+* {@link AgentMessage}s to a context's `messages` array. `resolve` is either
+* a message (or array of messages) or a function of `{ context, event }`
+* returning them; the returned function is meant to be used directly as (or
+* composed into) a transition's result, e.g. `on: { USER_REPLIED:
+* agent.appendMessages(({ event }) => userMessage(event.text)) }`. Requires
+* `messages: AgentMessage[]` on context — see {@link messagesSchema} for a
+* ready-made schema for that field.
+*
+* @example
+* ```ts
+* on: {
+*   USER_REPLIED: appendMessages(({ event }) => userMessage(event.text)),
+* }
+* ```
+*/
+function appendMessages(resolve) {
+	return (args) => ({ context: { messages: addMessages(resolve)(args) } });
+}
+const KNOWN_PART_TYPES = new Set([
+	"text",
+	"image",
+	"file",
+	"tool-call",
+	"tool-result"
+]);
+function isKnownPart(part) {
+	return !!part && typeof part === "object" && KNOWN_PART_TYPES.has(part.type);
+}
+function validatePartsArray(content) {
+	if (!Array.isArray(content)) return "Expected content to be a string or an array of parts";
+	for (const part of content) if (!isKnownPart(part)) {
+		const type = part && typeof part === "object" ? part.type : void 0;
+		return `Unknown message part type: ${JSON.stringify(type)}`;
+	}
+}
+/**
+* A {@link StandardSchemaV1} validating an `AgentMessage[]` context field —
+* checks that every message has a known `role` (`system`/`user`/`assistant`/
+* `tool`) and that `content` is either a string (where the role allows it) or
+* an array of parts with a known `type`. Use it directly as a context
+* schema's `messages` field when authoring with `createAgentSchemas`.
+*/
+const messagesSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		if (!Array.isArray(value)) return { issues: [{ message: "Expected an array of agent messages" }] };
+		for (const message of value) {
+			if (!message || typeof message !== "object") return { issues: [{ message: "Expected an array of agent messages" }] };
+			const role = message.role;
+			const content = message.content;
+			if (role !== "system" && role !== "user" && role !== "assistant" && role !== "tool") return { issues: [{ message: `Unknown message role: ${JSON.stringify(role)}` }] };
+			if (role === "system") {
+				if (typeof content !== "string") return { issues: [{ message: "system message content must be a string" }] };
+				continue;
+			}
+			if (role === "tool") {
+				const error = validatePartsArray(content) ?? (content.some((part) => part.type !== "tool-result") ? "tool message content must contain only tool-result parts" : void 0);
+				if (error) return { issues: [{ message: error }] };
+				continue;
+			}
+			if (typeof content === "string") continue;
+			const error = validatePartsArray(content);
+			if (error) return { issues: [{ message: error }] };
+		}
+		return { value };
+	}
+} };
+//#endregion
+//#region src/workflow-config.ts
+const workflowConfigWholeExpressionPattern = /^\{\{\s*([\s\S]*?)\s*\}\}$/;
+const workflowConfigTemplateExpressionPattern = /\{\{\s*([\s\S]*?)\s*\}\}/g;
+function evaluateWorkflowConfigPath(expression, scope) {
+	const parts = expression.trim().split(".").filter(Boolean);
+	let current = scope;
+	for (const part of parts) {
+		if (!current || typeof current !== "object") return;
+		current = current[part];
+	}
+	return current;
+}
+function evaluateWorkflowConfigValue(value, scope) {
+	if (typeof value === "string") {
+		const wholeMatch = value.match(workflowConfigWholeExpressionPattern);
+		if (wholeMatch?.[1]) return evaluateWorkflowConfigPath(wholeMatch[1], scope);
+		return value.replace(workflowConfigTemplateExpressionPattern, (_match, expression) => {
+			const resolved = evaluateWorkflowConfigPath(expression, scope);
+			return resolved === void 0 || resolved === null ? "" : String(resolved);
+		});
+	}
+	if (Array.isArray(value)) return value.map((item) => evaluateWorkflowConfigValue(item, scope));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, evaluateWorkflowConfigValue(item, scope)]));
+	return value;
+}
+function createSchemasFromWorkflowConfig(config, compileSchema) {
+	return createAgentSchemas({
+		context: compileSchema(config.schemas?.context ?? { type: "object" }, "context"),
+		events: Object.fromEntries(Object.entries(config.schemas?.events ?? {}).map(([key, schema]) => [key, compileSchema(schema, `event.${key}`)])),
+		emitted: Object.fromEntries(Object.entries(config.schemas?.emitted ?? {}).map(([key, schema]) => [key, compileSchema(schema, `emitted.${key}`)])),
+		input: compileSchema(config.schemas?.input ?? {}, "input"),
+		output: compileSchema(config.schemas?.output ?? {}, "output"),
+		meta: compileSchema(config.schemas?.meta ?? {}, "meta")
+	});
+}
+function createRequestsFromWorkflowConfig(config, compileSchema) {
+	return Object.fromEntries(Object.entries(config.requests ?? {}).map(([key, request]) => [key, {
+		mode: request.mode,
+		description: request.description,
+		schemas: {
+			input: compileSchema(request.input, `${key}.input`),
+			output: compileSchema(request.output, `${key}.output`)
+		},
+		model: ({ input }) => String(evaluateWorkflowConfigValue(request.model, { input }) ?? ""),
+		system: request.system === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.system, { input }),
+		prompt: request.prompt === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.prompt, { input }),
+		messages: request.messages === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.messages, { input }),
+		tools: request.tools,
+		toolChoice: request.toolChoice,
+		reasoning: request.reasoning,
+		temperature: request.temperature === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.temperature, { input }),
+		maxOutputTokens: request.maxOutputTokens === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.maxOutputTokens, { input }),
+		topP: request.topP === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.topP, { input }),
+		topK: request.topK === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.topK, { input }),
+		seed: request.seed === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.seed, { input }),
+		stopSequences: request.stopSequences === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.stopSequences, { input }),
+		metadata: request.metadata === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.metadata, { input })
+	}]));
+}
+function createActorPlaceholdersFromWorkflowConfig(config) {
+	return Object.fromEntries(Object.keys(config.actors ?? {}).map((key) => [key, missingActor(key)]));
+}
+function createAssignAction(assignConfig) {
+	return ({ context, event }) => ({ context: Object.fromEntries(Object.entries(assignConfig).map(([key, value]) => [key, evaluateWorkflowConfigValue(value, {
+		context,
+		event
+	})])) });
+}
+function lowerWorkflowActions(actionConfig) {
+	if (!actionConfig) return;
+	const lowered = (Array.isArray(actionConfig) ? actionConfig : [actionConfig]).map((action) => {
+		if (action.assign !== void 0) return createAssignAction(action.assign);
+		if (action.emit !== void 0) return ({ context, event }, enq) => {
+			enq.emit(evaluateWorkflowConfigValue(action.emit, {
+				context,
+				event
+			}));
+		};
+		if (!action.type) throw new Error("setupAgent.fromConfig: action must declare 'type', 'assign', or 'emit'.");
+		return {
+			type: action.type,
+			params: ({ context, event }) => evaluateWorkflowConfigValue(action.params, {
+				context,
+				event
+			})
+		};
+	});
+	return Array.isArray(actionConfig) ? lowered : lowered[0];
+}
+function workflowTransitionMatches(transitionConfig, scope) {
+	if (transitionConfig.guard === void 0) return true;
+	if (typeof transitionConfig.guard === "string") return Boolean(evaluateWorkflowConfigValue(transitionConfig.guard, scope));
+	return typeof transitionConfig.guard === "function" ? transitionConfig.guard(scope) : false;
+}
+function lowerWorkflowTransitionResult(transitionConfig, scope) {
+	return {
+		...transitionConfig.target !== void 0 ? { target: transitionConfig.target } : {},
+		...transitionConfig.assign ? { context: Object.fromEntries(Object.entries(transitionConfig.assign).map(([key, value]) => [key, evaluateWorkflowConfigValue(value, scope)])) } : {},
+		...transitionConfig.description !== void 0 ? { description: transitionConfig.description } : {},
+		...transitionConfig.reenter !== void 0 ? { reenter: transitionConfig.reenter } : {},
+		...transitionConfig.meta !== void 0 ? { meta: transitionConfig.meta } : {}
+	};
+}
+function lowerWorkflowTransition(transitionConfig) {
+	return ({ context, event }) => {
+		const scope = {
+			context,
+			event
+		};
+		if (!workflowTransitionMatches(transitionConfig, scope)) return;
+		return lowerWorkflowTransitionResult(transitionConfig, scope);
+	};
+}
+function lowerWorkflowTransitionOrArray(transitionConfig) {
+	if (!transitionConfig) return;
+	return Array.isArray(transitionConfig) ? ({ context, event }) => {
+		const scope = {
+			context,
+			event
+		};
+		const transition = transitionConfig.find((candidate) => workflowTransitionMatches(candidate, scope));
+		if (!transition) return;
+		return lowerWorkflowTransitionResult(transition, scope);
+	} : lowerWorkflowTransition(transitionConfig);
+}
+function lowerWorkflowInvoke(invokeConfig) {
+	return {
+		...invokeConfig.id !== void 0 ? { id: invokeConfig.id } : {},
+		src: invokeConfig.src,
+		...invokeConfig.input !== void 0 ? { input: ({ context, event }) => evaluateWorkflowConfigValue(invokeConfig.input, {
+			context,
+			event
+		}) } : {},
+		...invokeConfig.onDone !== void 0 ? { onDone: lowerWorkflowTransitionOrArray(invokeConfig.onDone) } : {},
+		...invokeConfig.onError !== void 0 ? { onError: lowerWorkflowTransitionOrArray(invokeConfig.onError) } : {},
+		...invokeConfig.meta !== void 0 ? { meta: invokeConfig.meta } : {}
+	};
+}
+function lowerWorkflowState(stateConfig) {
+	return {
+		...stateConfig.description !== void 0 ? { description: stateConfig.description } : {},
+		...stateConfig.type !== void 0 ? { type: stateConfig.type } : {},
+		...stateConfig.initial !== void 0 ? { initial: stateConfig.initial } : {},
+		...stateConfig.states !== void 0 ? { states: Object.fromEntries(Object.entries(stateConfig.states).map(([key, child]) => [key, lowerWorkflowState(child)])) } : {},
+		...stateConfig.choice !== void 0 ? { choice: lowerWorkflowTransitionOrArray(stateConfig.choice) } : {},
+		...stateConfig.invoke !== void 0 ? { invoke: Array.isArray(stateConfig.invoke) ? stateConfig.invoke.map(lowerWorkflowInvoke) : lowerWorkflowInvoke(stateConfig.invoke) } : {},
+		...stateConfig.on !== void 0 ? { on: Object.fromEntries(Object.entries(stateConfig.on).map(([eventType, transitionConfig]) => [eventType, lowerWorkflowTransitionOrArray(transitionConfig)])) } : {},
+		...stateConfig.always !== void 0 ? { always: lowerWorkflowTransitionOrArray(stateConfig.always) } : {},
+		...stateConfig.onDone !== void 0 ? { onDone: lowerWorkflowTransitionOrArray(stateConfig.onDone) } : {},
+		...stateConfig.after !== void 0 ? { after: Object.fromEntries(Object.entries(stateConfig.after).map(([delay, transitionConfig]) => [delay, lowerWorkflowTransitionOrArray(transitionConfig)])) } : {},
+		...stateConfig.entry !== void 0 ? { entry: lowerWorkflowActions(stateConfig.entry) } : {},
+		...stateConfig.exit !== void 0 ? { exit: lowerWorkflowActions(stateConfig.exit) } : {},
+		...stateConfig.tags !== void 0 ? { tags: stateConfig.tags } : {},
+		...stateConfig.output !== void 0 ? { output: ({ context, event }) => evaluateWorkflowConfigValue(stateConfig.output, {
+			context,
+			event
+		}) } : {},
+		...stateConfig.meta !== void 0 ? { meta: stateConfig.meta } : {}
+	};
+}
+function setupAgentFromConfig(config, options) {
+	if (!options || typeof options.compileSchema !== "function") throw new Error("setupAgent.fromConfig(...) requires a 'compileSchema' option: { compileSchema: (jsonSchema, name) => StandardSchemaV1 }. Bring your own JSON Schema engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no JSON Schema engine.");
+	const { compileSchema } = options;
+	const schemas = createSchemasFromWorkflowConfig(config, compileSchema);
+	const requestActors = createRequestActors(createRequestsFromWorkflowConfig(config, compileSchema));
+	return setupAgent({
+		schemas,
+		actorSources: {
+			...createActorPlaceholdersFromWorkflowConfig(config),
+			...requestActors
+		}
+	}).createMachine({
+		...config.id !== void 0 ? { id: config.id } : {},
+		...config.description !== void 0 ? { description: config.description } : {},
+		...config.context !== void 0 ? { context: ({ input }) => validateSchemaSync(schemas.context, evaluateWorkflowConfigValue(config.context, { input })) } : {},
+		initial: config.initial,
+		states: Object.fromEntries(Object.entries(config.states).map(([key, state]) => [key, lowerWorkflowState(state)])),
+		...config.meta !== void 0 ? { meta: config.meta } : {}
+	});
+}
+//#endregion
+//#region src/setup-agent.ts
+/**
+* Builds a machine's {@link AgentSchemaPack} from a partial schema
+* declaration — only `context` is required; `events`/`input`/`output`/`meta`
+* default to empty/unknown schemas when omitted. Pass the result as
+* `setupAgent({ schemas })`'s `schemas` (or spread the individual fields
+* directly into `setupAgent({ context, events, ... })` — both forms are
+* accepted).
+*/
+function createAgentSchemas(schemas) {
+	return {
+		context: schemas.context,
+		events: schemas.events ?? {},
+		input: schemas.input,
+		output: schemas.output,
+		meta: schemas.meta,
+		emitted: schemas.emitted
+	};
+}
+/**
+* Schema-first `setup(...)` for agent machines — the standard entry point
+* for authoring a machine (the blueprint) that this library then runs (via
+* {@link runAgent} or the step helpers) against host-supplied model/decision
+* executors. Context, events, machine input, machine output, and
+* state/transition meta are all standard schemas — no `{} as Type` casts —
+* and are retained on `result.schemas` for runtime validation. Also
+* registers the `agent.generateText`/`agent.streamText`/`agent.userInput`/
+* `agent.decide` builtin actors and lowers `requests`/`actorSources` into the
+* machine's actor sources. The result is the xstate `setup(...)` object with
+* a wrapped `result.createMachine(...)` plus `result.schemas`/`models`/
+* `requests`/`appendMessages` attached. Also has a
+* `setupAgent.fromConfig(...)` namespace member for building a machine from
+* a serializable {@link AgentWorkflowConfig} instead of this TS API.
+*
+* @example
+* ```ts
+* const schemas = createAgentSchemas({
+*   context: z.object({ topic: z.string(), joke: z.string().nullable() }),
+*   input: z.object({ topic: z.string() }),
+*   output: z.object({ joke: z.string() }),
+* });
+*
+* const agent = setupAgent({
+*   schemas,
+*   actorSources: { tellJoke },
+* });
+*
+* const jokeMachine = agent.createMachine({
+*   context: ({ input }) => ({ topic: input.topic, joke: null }),
+*   initial: 'telling',
+*   states: {
+*     telling: {
+*       invoke: {
+*         id: 'joke',
+*         src: 'tellJoke',
+*         input: ({ context }) => ({ topic: context.topic }),
+*         onDone: ({ output }) => ({ target: 'done', context: { joke: output } }),
+*       },
+*     },
+*     done: { type: 'final', output: ({ context }) => ({ joke: context.joke ?? '' }) },
+*   },
+* });
+* ```
+*/
+function setupAgent(config) {
+	return createSetupAgent(config);
+}
+function collectFinalStateOutputs(states, outputs = []) {
+	for (const state of Object.values(states ?? {})) {
+		if (state?.type === "final" && state.output !== void 0) outputs.push(state.output);
+		collectFinalStateOutputs(state?.states, outputs);
+	}
+	return outputs;
+}
+function withRootOutputFromSingleFinal(config) {
+	if (!config || typeof config !== "object" || "output" in config || !("states" in config)) return config;
+	const outputs = collectFinalStateOutputs(config.states);
+	return outputs.length === 1 ? {
+		...config,
+		output: outputs[0]
+	} : config;
+}
+(function(_setupAgent) {
+	function fromConfig(config, options) {
+		return setupAgentFromConfig(config, options);
+	}
+	_setupAgent.fromConfig = fromConfig;
+})(setupAgent || (setupAgent = {}));
+/** Builds one TextLogic actor per `setupAgent({ requests })` entry. @internal */
+function createRequestActors(requests) {
+	return Object.fromEntries(Object.entries(requests).map(([key, request]) => {
+		return [key, createTextLogic({
+			...request,
+			name: key,
+			mode: request.mode ?? "generate"
+		})];
+	}));
+}
+function normalizeAgentSchemas(config) {
+	return "schemas" in config ? config.schemas : createAgentSchemas(config);
+}
+function normalizeAgentRequestInput(requests) {
+	return requests ?? {};
+}
+/**
+* Runtime guard: a key appearing in both `actorSources`/`requests` is almost
+* certainly a mistake (whichever spread applies last would silently win) —
+* fail fast with a clear message rather than let one implementation shadow
+* another.
+*/
+function assertNoActorKeyCollisions(actorSources, requests) {
+	const seenIn = /* @__PURE__ */ new Map();
+	const groups = [["actorSources", actorSources], ["requests", requests]];
+	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) {
+		const existingGroup = seenIn.get(key);
+		if (existingGroup) throw new Error(`setupAgent: key '${key}' is defined in both '${existingGroup}' and '${groupName}'. Each actor source key must be unique across 'actorSources' and 'requests'.`);
+		seenIn.set(key, groupName);
+	}
+}
+const RESERVED_AGENT_ACTOR_KEYS = [
+	...Object.keys(builtinTextActors),
+	USER_INPUT_ACTOR,
+	DECIDE_ACTOR,
+	PLAN_ACTOR
+];
+/**
+* Rejects a user-supplied `actorSources`/`requests` key in the reserved
+* `agent.*` builtin namespace. Without this, the builtins-first spread in
+* {@link createAgentActorSources} lets such a key overwrite the builtin
+* (`agent.decide`, `agent.plan`, …) silently. Deliberate override of a builtin
+* is still possible after the machine is created, via
+* `machine.provide({ actorSources: { 'agent.decide': ... } })`.
+*/
+function assertNoReservedAgentKeys(actorSources, requests) {
+	const groups = [["actorSources", actorSources], ["requests", requests]];
+	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) if (RESERVED_AGENT_ACTOR_KEYS.includes(key)) throw new Error(`setupAgent: '${groupName}' key '${key}' is a reserved builtin agent actor and cannot be redefined here (it would silently clobber the builtin). Reserved keys: ${RESERVED_AGENT_ACTOR_KEYS.join(", ")}. To deliberately override a builtin, do it on the created machine instead: machine.provide({ actorSources: { '${key}': ... } }).`);
+}
+function createAgentActorSources(actorSources, requestActors) {
+	assertNoActorKeyCollisions(actorSources, requestActors);
+	assertNoReservedAgentKeys(actorSources, requestActors);
+	return {
+		...builtinTextActors,
+		[USER_INPUT_ACTOR]: userInputActor,
+		[DECIDE_ACTOR]: createDecideActor(),
+		[PLAN_ACTOR]: createPlanActor(),
+		...actorSources,
+		...requestActors
+	};
+}
+function createAgentSetupConfig(schemas, actorSources, config) {
+	return {
+		schemas: {
+			context: schemas.context,
+			events: schemas.events,
+			input: schemas.input,
+			output: schemas.output,
+			meta: schemas.meta,
+			...schemas.emitted && Object.keys(schemas.emitted).length > 0 ? { emitted: schemas.emitted } : {}
+		},
+		...config.states ? { states: config.states } : {},
+		actorSources,
+		actions: config.actions,
+		guards: config.guards,
+		delays: config.delays
+	};
+}
+function createSetupAgent(config) {
+	const schemas = normalizeAgentSchemas(config);
+	const requestActors = createRequestActors(normalizeAgentRequestInput(config.requests));
+	const actorSources = createAgentActorSources(config.actorSources, requestActors);
+	const base = setup(createAgentSetupConfig(schemas, actorSources, config));
+	const createBaseMachine = base.createMachine.bind(base);
+	const machineOptions = {
+		schemas,
+		actorSources
+	};
+	const models = config.models ?? {};
+	return Object.assign(base, {
+		createMachine(machineConfig) {
+			const machine = createBaseMachine(withRootOutputFromSingleFinal(machineConfig));
+			agentExecutionOptions.set(machine, machineOptions);
+			if (config.isSuspended) {
+				const rootConfig = machine.config;
+				if (rootConfig) machineSuspensionPredicates.set(rootConfig, config.isSuspended);
+			}
+			return machine;
+		},
+		schemas,
+		models,
+		requests: requestActors,
+		appendMessages(resolve) {
+			return appendMessages(resolve);
+		}
+	});
+}
+//#endregion
+//#region src/steps.ts
+/**
+* The step path: durable, per-model-call-checkpoint hosting of an agent
+* machine. Public vocabulary — `initialAgentStep`, `transitionAgentStep`,
+* `resolveAgentStep`, `getAgentRequests`, `executeAgentRequest`,
+* `resolveAgentRequests`.
+* @module
+*/
+/**
+* Scans a set of executable actions (as returned by xstate's `transition`/
+* `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
+* lowers each into an {@link AgentStepRequest}. The hand-passed-schemas
+* implementation detail behind the public {@link getAgentRequests} — it needs
+* `schemas`/`actorSources` passed explicitly, whereas `getAgentRequests`
+* pre-fills them from the machine's registered `setupAgent` options.
+* `options.snapshot` is required to resolve a decision's candidate events
+* (intersecting declared `allowedEvents` with what's currently legal) — omit
+* it and decision requests report an empty `events` list.
+*
+* @internal
+*/
+function getAgentRequestsWith(actions, options = {}) {
+	return [...actions.flatMap((action) => {
+		if (action.type !== "xstate.spawnChild" && action.type !== "@xstate.start") return [];
+		const params = action.type === "@xstate.start" ? action : action.params;
+		if (!params || typeof params.src !== "string") return [];
+		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
+		const registeredLogic = isTextLogic(action.logic) || isDecisionLogic(action.logic) ? action.logic : options.actorSources?.[params.src];
+		if (isDecisionLogic(registeredLogic)) {
+			const decisionRequest = registeredLogic.request(params.input);
+			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
+			const events = options.snapshot ? getAcceptedEvents(options.snapshot, {
+				events: options.events,
+				schemas: options.schemas,
+				eventTypes: allowedEventTypes,
+				eventToolName: options.eventToolName
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = isTextLogic(registeredLogic) ? registeredLogic : void 0;
+		const input = textLogic ? textLogic.request(params.input) : void 0;
+		if (!input) return [];
+		return [{
+			kind: "text",
+			id: params.id,
+			src: params.src,
+			...textLogic ? { mode: textLogic.mode } : {},
+			input,
+			tools: input.tools ?? {},
+			events: []
+		}];
+	}), ...getActivePlanRequests(options)];
+}
+/**
+* Scans the live snapshot's children for active `agent.plan` (plan-logic)
+* invokes and lowers each into an {@link AgentPlanRequest} — the re-surfacing
+* half of plan discovery. Reads the applied-event trail and remaining budget
+* from the child's own ledger `context` ({@link PlanLedgerContext}), recomputes
+* the currently-legal candidates (∩ declared `allowedEvents`) plus the reserved
+* `agent.plan.done` move, and takes `stepsRemaining` from the ledger (falling
+* back to `maxSteps - applied.length` for a snapshot with no context yet).
+* Returns `[]` when no snapshot is available (candidates need a live snapshot).
+*
+* @internal
+*/
+function getActivePlanRequests(options) {
+	const snapshot = options.snapshot;
+	if (!snapshot) return [];
+	const children = snapshot.children;
+	if (!children) return [];
+	const requests = [];
+	for (const [id, child] of Object.entries(children)) {
+		const ref = child;
+		if (typeof ref?.getSnapshot !== "function") continue;
+		const src = typeof ref.src === "string" ? ref.src : void 0;
+		const logic = (src ? options.actorSources?.[src] : void 0) ?? ref.logic;
+		if (!isPlanLogic(logic)) continue;
+		const childSnapshot = ref.getSnapshot();
+		if (childSnapshot?.status !== "active") continue;
+		const input = childSnapshot.input ?? {};
+		const maxSteps = input.maxSteps ?? 8;
+		const ledger = childSnapshot.context ?? {};
+		const applied = ledger.applied ?? [];
+		const stepsRemaining = ledger.stepsRemaining ?? maxSteps - applied.length;
+		const machineEvents = getAcceptedEvents(snapshot, {
+			events: options.events,
+			schemas: options.schemas,
+			eventTypes: logic.allowedEventTypes(input) ?? void 0,
+			eventToolName: options.eventToolName
+		});
+		const events = machineEvents.some((event) => event.type === "agent.plan.done") ? machineEvents : [...machineEvents, {
+			type: PLAN_DONE_EVENT_TYPE,
+			toolName: sanitizeEventToolName(PLAN_DONE_EVENT_TYPE)
+		}];
+		requests.push({
+			kind: "plan",
+			id,
+			src: src ?? "",
+			input,
+			events,
+			applied,
+			stepsRemaining: Math.max(0, stepsRemaining)
+		});
+	}
+	return requests;
+}
+/**
+* Builds the synthetic `xstate.done.actor.<id>` event xstate's `transition()`
+* expects to resolve a spawned invoke — the event {@link resolveAgentStep}
+* applies internally.
+*
+* @internal
+*/
+function doneEvent(request, output) {
+	return {
+		type: `xstate.done.actor.${typeof request === "string" ? request : request.id}`,
+		output
+	};
+}
+/**
+* Applies a request's `output` as a done event via `transition(...)`,
+* returning the raw `[snapshot, actions]` tuple. Lower-level than
+* {@link resolveAgentStep} — that helper wraps this and also runs
+* {@link getAgentRequests} to produce the next {@link AgentStep}.
+*
+* @internal
+*/
+function transitionResult(logic, snapshot, request, output) {
+	const event = doneEvent(request, output);
+	const result = transition(logic, snapshot, event);
+	applyFinalStateOutput(logic, result[0], event);
+	return result;
+}
+/**
+* Starts a machine and returns its first {@link AgentStep} — the step-path
+* equivalent of `initialTransition` plus request discovery. Begins the
+* durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+* (via {@link executeAgentRequest} for `kind: 'text'`, or
+* {@link resolveDecision} for `kind: 'decision'`), then advance with
+* {@link resolveAgentStep} or {@link transitionAgentStep}.
+*/
+function initialAgentStep(machine, input, options) {
+	const [snapshot, actions] = initialTransition(machine, input);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies an externally-sent event (e.g. a decision's chosen event, or a
+* human's reply) and returns the next {@link AgentStep}. Accepts **either**
+* a raw snapshot **or** a prior `AgentStep` as the second argument —
+* `.snapshot` is unwrapped automatically, so callers can thread the whole
+* step object through without manually plucking the snapshot out.
+*/
+function transitionAgentStep(machine, snapshotOrStep, event, options) {
+	const [nextSnapshot, actions] = transition(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, event);
+	return createAgentStep(machine, nextSnapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies a resolved text request's output (a `kind: 'text'`
+* {@link AgentRequest} — not a decision) as a done event and returns the
+* next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+* (which returns a {@link ChosenEvent}) and apply it with
+* {@link transitionAgentStep} instead — a decision has no output value of
+* its own to feed here.
+*/
+function resolveAgentStep(machine, step, request, output, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, output);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Snapshot in, requests out: scans executable actions for spawned agent
+* invokes and lowers each into an {@link AgentStepRequest}, pre-filled with
+* the machine's registered `setupAgent` schemas/actorSources (so callers
+* don't pass them by hand each call) — merged with any `options` passed here,
+* which take precedence. The step path's public discovery primitive;
+* `initialAgentStep`/`transitionAgentStep`/`resolveAgentStep` call it
+* internally to populate `AgentStep.requests`.
+*/
+function getAgentRequests(machine, actions, snapshot, options = {}) {
+	return getAgentRequestsWith(actions, {
+		...getRegisteredAgentExecutionOptions(machine, options),
+		...options,
+		snapshot
+	});
+}
+async function executeAgentRequest(request, executors, options) {
+	if (request.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors.decide, ...) instead.");
+	assertTextExecutor(request, executors);
+	const { output, raw } = await executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
+	const normalizedOutput = request.input.outputSchema ? validateSchemaSync(request.input.outputSchema, output) : output;
+	return options?.verbose ? {
+		output: normalizedOutput,
+		raw
+	} : normalizedOutput;
+}
+/**
+* Resolves the current step's pending requests and returns the next
+* {@link AgentStep} — one iteration of the durable step loop, collapsing the
+* manual `request.kind` dispatch a host would otherwise write by hand.
+*
+* For each pending request, in order: a `kind: 'text'` request is run with
+* {@link executeAgentRequest} then fed back via {@link resolveAgentStep}; a
+* `kind: 'decision'` request is resolved with `resolveDecision` (wiring
+* `canTake` to `step.snapshot.can` so guard-rejected choices retry) then
+* applied with {@link transitionAgentStep}. The **current** step is re-read
+* after each application — the machine may advance and its `requests` change —
+* so this always resolves against the live step, never a stale list.
+*
+* A `kind: 'plan'` request (`agent.plan`) is resolved natively too: one plan
+* step per call. It resolves a single decision from `request.events` (wiring
+* `canTake` to `step.snapshot.can`, exempting the reserved `agent.plan.done`
+* move and `stopOn` events), then either applies the chosen machine event and
+* lets the next step re-surface the plan, or completes the plan (feeding its
+* `{ steps, stopped }` output back) on the done move / a `stopOn` event / an
+* exhausted budget / no legal events. The plan's applied trail is carried in
+* the invoke child's snapshot, so persisting the step between calls resumes the
+* plan identically.
+*
+* Missing the executor a request needs throws a clear error
+* (`generateText`/`streamText` for text, `decide` for decisions and plans).
+*
+* A complete durable host is two lines:
+*
+* ```ts
+* let step = initialAgentStep(machine, input);
+* while (!step.done) step = await resolveAgentRequests(machine, step, executors);
+* ```
+*
+* All pending **text** requests of a step are resolved in parallel
+* (`Promise.all`) — parallel statechart regions are genuinely concurrent, so
+* their model calls run concurrently — then their outputs apply in
+* **request-array order** (deterministic for durable replay regardless of which
+* call finishes first). Decisions and plans stay **one at a time**: applying
+* either changes the set of legal candidates for what follows, so they cannot be
+* resolved against a stale snapshot. A host that instead wants strictly
+* sequential text resolution loops the manual per-request helpers
+* ({@link executeAgentRequest} + {@link resolveAgentStep}) one at a time.
+*/
+async function resolveAgentRequests(machine, step, executors, options) {
+	const [request] = step.requests;
+	if (!request) return step;
+	if (request.kind === "decision") {
+		if (!executors.decide) throw new Error(`this step's decision request '${request.id}' needs a 'decide' executor but none was provided.`);
+		return transitionAgentStep(machine, step, await resolveDecision(request, executors.decide, {
+			canTake: (event) => step.snapshot.can(event),
+			maxRetries: options?.maxRetries
+		}), options);
+	}
+	if (request.kind === "plan") return resolvePlanRequest(machine, step, request, executors, options);
+	const textRequests = step.requests.filter((candidate) => candidate.kind === "text");
+	for (const textRequest of textRequests) assertTextExecutor(textRequest, executors);
+	const outputs = await Promise.all(textRequests.map((textRequest) => executeAgentRequest(textRequest, executors)));
+	let next = step;
+	for (let index = 0; index < textRequests.length; index++) next = resolveAgentStep(machine, next, textRequests[index], outputs[index], options);
+	return next;
+}
+function assertTextExecutor(request, executors) {
+	const mode = request.mode ?? "generate";
+	const kind = mode === "stream" ? "streamText" : "generateText";
+	if (!(mode === "stream" ? executors.streamText : executors.generateText)) throw new Error(`this step's text request '${request.src}' needs a '${kind}' executor but none was provided.`);
+}
+async function resolvePlanRequest(machine, step, request, executors, options) {
+	if (!executors.decide) throw new Error(`this step's plan request '${request.src}' needs a 'decide' executor but none was provided.`);
+	const stopOn = new Set(request.input.stopOn ?? []);
+	if (request.stepsRemaining <= 0) return completePlan(machine, step, request.id, request.applied, "max-steps", options);
+	if (request.events.filter((event) => event.type !== "agent.plan.done").length === 0) return completePlan(machine, step, request.id, request.applied, "no-legal-events", options);
+	const chosen = await resolveDecision(planStepDecisionRequest(request), executors.decide, {
+		maxRetries: options?.maxRetries,
+		canTake: (event) => {
+			if (event.type === "agent.plan.done" || stopOn.has(event.type)) return true;
+			return step.snapshot.can(event);
+		}
+	});
+	if (chosen.type === "agent.plan.done") return completePlan(machine, step, request.id, request.applied, "done", options);
+	const applied = [...request.applied, chosen];
+	advancePlanChildLedger(step.snapshot, request.id, {
+		type: "plan.applied",
+		event: chosen
+	});
+	const next = transitionAgentStep(machine, step, chosen, options);
+	if (stopOn.has(chosen.type)) {
+		if (isPlanActive(next.snapshot, request.id)) return completePlan(machine, next, request.id, applied, "stop-event", options);
+	}
+	return next;
+}
+function completePlan(machine, step, id, steps, stopped, options) {
+	return resolveAgentStep(machine, step, { id }, {
+		steps,
+		stopped
+	}, options);
+}
+function planStepDecisionRequest(request) {
+	const { input, applied, events, id } = request;
+	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}'.`;
+	return {
+		kind: "decision",
+		id: `${id}[${applied.length}]`,
+		model: input.model,
+		system: input.system,
+		prompt: `${input.prompt ?? ""}${trail}${doneHint}`,
+		messages: input.messages,
+		events,
+		attempts: [],
+		temperature: input.temperature,
+		maxOutputTokens: input.maxOutputTokens,
+		topP: input.topP,
+		topK: input.topK,
+		seed: input.seed,
+		stopSequences: input.stopSequences,
+		metadata: input.metadata
+	};
+}
+function advancePlanChildLedger(snapshot, id, event) {
+	const child = snapshot.children?.[id];
+	const childSnapshot = child?.getSnapshot?.();
+	if (!isPlanLogic(child?.logic) || !childSnapshot || typeof childSnapshot !== "object") return;
+	Object.assign(childSnapshot, advancePlanLedger(child.logic, childSnapshot, event));
+}
+function isPlanActive(snapshot, id) {
+	return (snapshot.children?.[id])?.getSnapshot?.()?.status === "active";
+}
+function createAgentStep(machine, snapshot, actions, options) {
+	applyFinalStateOutput(machine, snapshot);
+	return {
+		snapshot,
+		actions,
+		requests: getAgentRequestsWith(actions, {
+			...options,
+			snapshot
+		}),
+		done: snapshot.status === "done"
+	};
+}
+function resolveStateValueConfig(config, value) {
+	if (typeof value === "string") return config.states?.[value];
+	if (!value || typeof value !== "object") return;
+	for (const [key, childValue] of Object.entries(value)) {
+		const childConfig = config.states?.[key];
+		if (!childConfig) continue;
+		if (childConfig.type === "final") return childConfig;
+		const nested = resolveStateValueConfig(childConfig, childValue);
+		if (nested) return nested;
+	}
+}
+function applyFinalStateOutput(logic, snapshot, event) {
+	const machineSnapshot = snapshot;
+	if (machineSnapshot.status !== "done" || machineSnapshot.output !== void 0 || !("config" in logic)) return;
+	const config = logic.config;
+	if (!config) return;
+	const output = resolveStateValueConfig(config, machineSnapshot.value)?.output;
+	if (output === void 0) return;
+	machineSnapshot.output = typeof output === "function" ? output({
+		context: machineSnapshot.context,
+		event
+	}) : output;
+}
+function isAgentStep(value) {
+	return !!value && typeof value === "object" && "snapshot" in value && "actions" in value && "requests" in value;
+}
+//#endregion
+//#region src/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: "agent.interpret",
+		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 });
+		deps.onResult?.(agentRequest, {
+			output,
+			raw
+		});
+		deps.onTrace?.({
+			type: "request.end",
+			request: agentRequest,
+			output,
+			raw
+		});
+	} 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)
+	});
+	deps.appendToLog(assistantMessage(`[chose: ${chosen.type}]`));
+	if (deps.isSettled()) return false;
+	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 IllegalResumeEventError = class extends Error {
+	eventType;
+	acceptedTypes;
+	constructor(eventType, acceptedTypes) {
+		super(`runAgent: cannot resume with event '${eventType}' — the restored state does not accept it. Accepted event types: ${acceptedTypes.length > 0 ? acceptedTypes.join(", ") : "(none)"}.`);
+		this.name = "IllegalResumeEventError";
+		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 SnapshotVersionMismatchError = class extends Error {
+	from;
+	to;
+	machineId;
+	constructor(from, to, machineId) {
+		super(`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 = "SnapshotVersionMismatchError";
+		this.from = from;
+		this.to = to;
+		this.machineId = machineId;
+	}
+};
+/**
+* Thrown by {@link runAgentToCompletion} 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 Error {
+	snapshot;
+	acceptedTypes;
+	constructor(snapshot, acceptedTypes) {
+		super(`runAgentToCompletion: 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;
+	}
+};
+let nextRunAgentTraceId = 1;
+var MaxModelCallsExceededError = class extends Error {
+	constructor() {
+		super("runAgent exceeded maxModelCalls.");
+		this.name = "MaxModelCallsExceededError";
+	}
+};
+function wrapsDecisionExhausted(error) {
+	let current = error;
+	for (let depth = 0; depth < 10 && current != null; depth++) {
+		if (current instanceof DecisionExhaustedError) 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 an `implementations.actorSources` 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.implementations === "object" && !!logic.implementations?.actorSources;
+}
+/**
+* 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({ actorSources: { 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({ actorSources: { '${src}': ... } }) or runAgent(machine, { actorSources: { '${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({ actorSources: { '${src}': ... } }) or runAgent(machine, { actorSources: { '${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.implementations.actorSources;
+	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({ actorSources: { <child>: childMachine } })) and invoke it by name.`);
+}
+/** 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;
+}
+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
+		});
+		try {
+			const raw = await executor(requestWithTools, {
+				onChunk: (chunk) => {
+					runCtx.onTrace?.({
+						type: "stream.chunk",
+						request: agentRequest,
+						chunk
+					});
+					runCtx.onChunk?.(chunk, { request: agentRequest });
+				},
+				signal
+			});
+			const output = await normalizeGeneratorResult(raw, id, {
+				request,
+				onChunk: (chunk) => {
+					runCtx.onTrace?.({
+						type: "stream.chunk",
+						request: agentRequest,
+						chunk
+					});
+					runCtx.onChunk?.(chunk, { request: agentRequest });
+				}
+			});
+			const rawReasoning = raw?.reasoning;
+			const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
+			runCtx.onResult?.(agentRequest, {
+				output,
+				raw
+			});
+			runCtx.onTrace?.({
+				type: "request.end",
+				request: agentRequest,
+				output,
+				raw,
+				...reasoning !== void 0 ? { reasoning } : {}
+			});
+			return { output };
+		} catch (error) {
+			runCtx.onTrace?.({
+				type: "request.error",
+				request: agentRequest,
+				error
+			});
+			throw error;
+		}
+	});
+}
+function createCountingDecide(runCtx) {
+	return async (attemptRequest) => {
+		runCtx.consumeModelCall();
+		runCtx.onTrace?.({
+			type: "request.start",
+			request: attemptRequest
+		});
+		try {
+			const result = await runCtx.decide(attemptRequest);
+			runCtx.onResult?.(attemptRequest, {
+				output: result.event,
+				raw: result
+			});
+			runCtx.onTrace?.({
+				type: "request.end",
+				request: attemptRequest,
+				output: result.event,
+				raw: result
+			});
+			return result;
+		} catch (error) {
+			runCtx.onTrace?.({
+				type: "request.error",
+				request: attemptRequest,
+				error
+			});
+			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), {
+			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);
+		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
+	});
+}
+/**
+* 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.implementations.actorSources;
+	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({ actorSources: 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.actorSources` 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) {
+	const maxModelCalls = options.maxModelCalls ?? 100;
+	let modelCallCount = 0;
+	let budgetExceeded = false;
+	let warnedNonSerializable = false;
+	const runId = `run_${nextRunAgentTraceId++}`;
+	let traceSeq = 0;
+	const machineId = machine.config.id ?? machine.id ?? "(machine)";
+	const machineVersion = options.machineVersion ?? getMachineStructuralHash(machine);
+	const agentMeta = {
+		machineId,
+		version: machineVersion
+	};
+	const stampAgentMeta = (snapshot) => {
+		if (snapshot && typeof snapshot === "object") snapshot.agentMeta = agentMeta;
+	};
+	const onTrace = (event) => {
+		options.onTrace?.({
+			runId,
+			seq: ++traceSeq,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			...event
+		});
+	};
+	const consumeModelCall = () => {
+		if (budgetExceeded) throw new MaxModelCallsExceededError();
+		modelCallCount += 1;
+		if (modelCallCount > maxModelCalls) {
+			budgetExceeded = true;
+			throw new MaxModelCallsExceededError();
+		}
+	};
+	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({ actorSources: options.actorSources });
+	const effectiveSources = provided.implementations.actorSources;
+	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,
+		actorHolder,
+		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({ actorSources: wrappedSources });
+	const isSuspended = options.isSuspended ?? getMachineSuspensionPredicate(machine) ?? (() => false);
+	let effectiveSnapshot = options.snapshot;
+	if (effectiveSnapshot !== void 0) {
+		const from = effectiveSnapshot.agentMeta?.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 SnapshotVersionMismatchError(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 priorMessages = effectiveSnapshot?.messages ?? [];
+	const messages = typeof options.messages === "function" ? [...options.messages([...priorMessages])] : [...priorMessages, ...options.messages ?? []];
+	const stampMessages = (snapshot) => {
+		if (!options.getRequests && !options.messages) 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 IllegalResumeEventError(eventType, acceptedTypes);
+	}
+	return new Promise((resolvePromise) => {
+		let settled = false;
+		let idleTimer;
+		let actor;
+		let deliveringResumeEvent = options.event !== void 0;
+		const settle = (result) => {
+			if (settled) return;
+			settled = true;
+			if (idleTimer !== void 0) clearTimeout(idleTimer);
+			if (options.signal) options.signal.removeEventListener("abort", onAbort);
+			stampAgentMeta(result.snapshot);
+			stampMessages(result.snapshot);
+			if ("persistedSnapshot" in result) {
+				stampAgentMeta(result.persistedSnapshot);
+				stampMessages(result.persistedSnapshot);
+			}
+			onTrace({
+				type: "run.end",
+				...result
+			});
+			actor.stop();
+			resolvePromise(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) for (const item of items) options.onMessage(item);
+		};
+		const settleInterpretError = (error) => {
+			settle({
+				status: "error",
+				cause: budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine",
+				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,
+			consumeModelCall,
+			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(Boolean);
+			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)) settleIdle(current);
+				}
+			}, 0);
+		};
+		actor = createActor(boundMachine, {
+			input: options.input,
+			snapshot: effectiveSnapshot,
+			inspect: (event) => {
+				options.inspect?.(event);
+				if (settled || event.type !== "@xstate.transition" || event.actorRef !== actor.ref) return;
+				const snapshot = event.snapshot;
+				onTrace({
+					type: "machine.transition",
+					snapshot,
+					event: event.event
+				});
+				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: budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(snapshot.error) ? "decision-exhausted" : "machine",
+						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);
+		if (options.signal) {
+			if (options.signal.aborted) {
+				settle({
+					status: "error",
+					cause: "aborted",
+					error: options.signal.reason ?? /* @__PURE__ */ new Error("Aborted"),
+					snapshot: actor.getSnapshot()
+				});
+				return;
+			}
+			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);
+		}
+	});
+}
+/**
+* Runs an agent machine to a **final state** and returns its output, for
+* run-to-done flows where an idle pause is unexpected. Wraps {@link runAgent}:
+*
+* - `done` → resolves with `result.output` (the machine's `OutputFrom`).
+* - `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 `runAgentToCompletion` when the
+* machine is meant to run straight through to a final state.
+*/
+async function runAgentToCompletion(machine, options) {
+	const result = await runAgent(machine, options);
+	if (result.status === "done") return result.output;
+	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(`runAgentToCompletion: 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);
+	};
+}
+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/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 = value.target;
+		if (target !== void 0) collectTransitionTargets(target, fromNode, index, out);
+	}
+}
+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) {
+	const out = {
+		targets: [],
+		opaque: false
+	};
+	const { config } = node;
+	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) {
+	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);
+		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, actorSources) {
+	if (typeof src === "string") {
+		if (src === DECIDE_SRC) return "decision";
+		if (src === PLAN_SRC) return "plan";
+		const logic = actorSources[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.actorSources);
+		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({ actorSources: { 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 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,
+	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);
+	const registered = getRegisteredAgentExecutionOptions(machine);
+	const ctx = {
+		machine,
+		config,
+		index,
+		reachable,
+		schemas: registered.schemas,
+		actorSources: registered.actorSources ?? machine.implementations?.actorSources ?? {}
+	};
+	const disabled = new Set(options.disable ?? []);
+	return LINT_CHECKS.flatMap((check) => check(ctx)).filter((d) => !disabled.has(d.code));
+}
+function pendingInvokes(step) {
+	const out = [];
+	for (const action of step.actions) {
+		const type = action.type;
+		if (type !== "xstate.spawnChild" && type !== "@xstate.start") continue;
+		const params = type === "@xstate.start" ? action : action.params ?? {};
+		if (typeof params.src === "string" && typeof params.id === "string") out.push({
+			id: params.id,
+			src: params.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]),
+		userInput: mapValues(options.script.userInput ?? {}, (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.userInput, 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
+export { createAgentSchemas as _, AgentIdleError as a, messagesSchema as b, inspectTransitions as c, executeAgentRequest as d, getAgentRequests as f, transitionAgentStep as g, resolveAgentStep as h, simulateAgent as i, runAgent as l, resolveAgentRequests as m, explorePaths as n, IllegalResumeEventError as o, initialAgentStep as p, lintAgentMachine as r, SnapshotVersionMismatchError as s, canReach as t, runAgentToCompletion as u, setupAgent as v, appendMessages as y };