@statelyai/agent 1.1.6 → 2.0.0-alpha.10

package/dist/run-agent-BoAOq_0Z.mjs

@@ -0,0 +1,1540 @@
+import { $ as validateSchemaSync, B as missingActor, C as createTextLogic, D as isTextLogic, F as getMachineSuspensionPredicate, H as findNonSerializableContextPaths, I as getRegisteredAgentExecutionOptions, K as getMachineStructuralHash, M as userInputActor, N as agentExecutionOptions, O as normalizeGeneratorResult, P as executorBoundLogics, Q as userMessage, R as isUnboundPlaceholder, S as builtinTextActors, U as getAgentMessages, V as assistantMessage, _ as INTERPRET_SOURCE, a as createPlanActor, c as isPlanLogic, f as getAcceptedEvents, g as DECIDE_ACTOR, h as sanitizeEventToolName, i as createDecideActor, n as PLAN_DONE_EVENT_TYPE, o as initialPlanLedger, r as advancePlanLedger, s as isDecisionLogic, t as DecisionExhaustedError, u as resolveDecision, v as PLAN_ACTOR, y as USER_INPUT_ACTOR, z as machineSuspensionPredicates } from "./decision-CQdrKc8k.mjs";
+import { createActor, createAsyncLogic, getNextTransitions, setup } 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
+const emptyEventSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return value !== null && typeof value === "object" && Object.keys(value).length === 0 ? { value: {} } : { issues: [{ message: "Expected an empty event payload" }] };
+	}
+} };
+function normalizeEventSchemas(events) {
+	return Object.fromEntries(Object.entries(events).map(([type, schema]) => [type, schema && typeof schema === "object" && "~standard" in schema ? schema : emptyEventSchema]));
+}
+/**
+* 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: normalizeEventSchemas(schemas.events ?? {}),
+		input: schemas.input,
+		output: schemas.output,
+		meta: schemas.meta,
+		emitted: schemas.emitted
+	};
+}
+function mergeContextSchema(base, fields) {
+	return { "~standard": {
+		version: 1,
+		vendor: "statelyai-agent",
+		validate(value) {
+			const baseResult = base["~standard"].validate(value);
+			if (baseResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+			if (baseResult.issues) return baseResult;
+			const merged = { ...baseResult.value };
+			const issues = [];
+			for (const [key, fieldSchema] of Object.entries(fields)) {
+				const fieldResult = fieldSchema["~standard"].validate(value[key]);
+				if (fieldResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+				if (fieldResult.issues) issues.push(...fieldResult.issues.map((issue) => ({
+					...issue,
+					path: [key, ...issue.path ?? []]
+				})));
+				else merged[key] = fieldResult.value;
+			}
+			return issues.length > 0 ? { issues } : { value: merged };
+		}
+	} };
+}
+function resolveAgentStateSchemas(contextSchema, states) {
+	return Object.fromEntries(Object.entries(states).map(([key, state]) => {
+		if (!state || typeof state !== "object") return [key, state];
+		const children = "states" in state && state.states ? resolveAgentStateSchemas(contextSchema, state.states) : void 0;
+		if ("context" in state && state.context) return [key, {
+			schemas: { context: mergeContextSchema(contextSchema, state.context) },
+			...children ? { states: children } : {}
+		}];
+		return [key, children ? {
+			...state,
+			states: children
+		} : state];
+	}));
+}
+/**
+* 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) {
+	if ("schemas" in config && config.schemas) return config.schemas;
+	const loose = config;
+	return createAgentSchemas({
+		...loose,
+		context: loose.context
+	});
+}
+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: resolveAgentStateSchemas(schemas.context, 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 models = config.models ?? {};
+	const machineOptions = {
+		schemas,
+		actorSources,
+		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/internal/state-request-pass.ts
+async function runTextPhase(stateRequest, baseMessages, deps) {
+	const { model, system } = stateRequest;
+	const id = stateRequest.id ?? deps.nextRequestId();
+	const promptMessage = userMessage(stateRequest.prompt);
+	if (stateRequest.kind === "decision") return {
+		stateRequest,
+		id,
+		output: void 0,
+		appended: [promptMessage]
+	};
+	if (!deps.generateText) throw new Error("runAgent: a getRequests request needs a 'generateText' executor (or use kind: 'decision').");
+	const request = {
+		model,
+		...system !== void 0 ? { system } : {},
+		messages: [...baseMessages, promptMessage],
+		tools: {}
+	};
+	const agentRequest = {
+		kind: "text",
+		id,
+		src: INTERPRET_SOURCE,
+		mode: "generate",
+		input: request,
+		tools: {},
+		events: []
+	};
+	deps.consumeModelCall();
+	deps.onTrace?.({
+		type: "request.start",
+		request: agentRequest
+	});
+	let output;
+	try {
+		const raw = await deps.generateText(request, { signal: deps.signal });
+		output = await normalizeGeneratorResult(raw, id, { request });
+		const rawReasoning = raw?.reasoning;
+		const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
+		deps.onResult?.(agentRequest, {
+			output,
+			raw
+		});
+		deps.onTrace?.({
+			type: "request.end",
+			request: agentRequest,
+			output,
+			raw,
+			...reasoning !== void 0 ? { reasoning } : {}
+		});
+	} catch (error) {
+		deps.onTrace?.({
+			type: "request.error",
+			request: agentRequest,
+			error
+		});
+		throw error;
+	}
+	return {
+		stateRequest,
+		id,
+		output,
+		appended: [promptMessage, assistantMessage(typeof output === "string" ? output : JSON.stringify(output))]
+	};
+}
+async function runAdvancePhase(plan, deps) {
+	const { stateRequest, id, output } = plan;
+	const { model, system } = stateRequest;
+	deps.appendToLog(...plan.appended);
+	if (stateRequest.kind !== "decision" && stateRequest.onDone !== void 0) {
+		const snapshot = deps.getSnapshot();
+		const resolved = typeof stateRequest.onDone === "function" ? stateRequest.onDone({
+			output,
+			snapshot,
+			messages: deps.messages
+		}) : stateRequest.onDone;
+		if (!resolved) return false;
+		const acceptedTypes = getAcceptedEvents(snapshot, { schemas: deps.schemas }).map((descriptor) => descriptor.type);
+		if (!acceptedTypes.includes(resolved.type)) throw new Error(`runAgent: getRequests request '${id}' resolved onDone to event '${resolved.type}', which the current state does not accept. Accepted: ${acceptedTypes.join(", ") || "(none)"}.`);
+		if (!snapshot.can(resolved)) return false;
+		deps.send(resolved);
+		return true;
+	}
+	const events = getAcceptedEvents(deps.getSnapshot(), {
+		schemas: deps.schemas,
+		...stateRequest.allowedEvents ? { eventTypes: stateRequest.allowedEvents } : {}
+	});
+	if (events.length === 0) return false;
+	if (!deps.decide) throw new Error(`runAgent: a getRequests request without 'onDone' needs a 'decide' executor to choose between events ${events.map((descriptor) => `'${descriptor.type}'`).join(", ")}. Provide request.onDone for deterministic advancement, or a 'decide' executor.`);
+	const chosen = await resolveDecision({
+		kind: "decision",
+		id,
+		model,
+		...system !== void 0 ? { system } : {},
+		messages: [...deps.messages],
+		events,
+		attempts: []
+	}, deps.decide, {
+		signal: deps.signal,
+		canTake: (event) => deps.getSnapshot().can(event)
+	});
+	if (deps.isSettled()) return false;
+	deps.appendToLog(assistantMessage(`[chose: ${chosen.type}]`));
+	deps.send(chosen);
+	return true;
+}
+/**
+* Executes one getRequests pass: all text calls concurrently against the
+* pass-start log, then per-request advancement sequentially in request
+* order. Returns whether ANY request sent an event — the host settles idle
+* when none did (otherwise an unchanged snapshot would re-produce the same
+* pass forever). Stops early (skipping remaining appends/sends) once
+* {@link StateRequestPassDeps.isSettled} reports the run is over. Throws on
+* executor/`onDone` errors — the host maps them to its error settle.
+*/
+async function runStateRequestPass(requests, deps) {
+	const baseMessages = [...deps.messages];
+	const plans = await Promise.all(requests.map((stateRequest) => runTextPhase(stateRequest, baseMessages, deps)));
+	let sentAny = false;
+	for (const plan of plans) {
+		if (deps.isSettled()) break;
+		sentAny = await runAdvancePhase(plan, deps) || sentAny;
+	}
+	return { sentAny };
+}
+//#endregion
+//#region src/run-agent.ts
+/**
+* Thrown by {@link runAgent} when resuming with a `snapshot` + `event` whose
+* `type` the restored state cannot accept (a type-level check via
+* {@link getAcceptedEvents}). A programmer/integration error, in the same
+* class as runAgent's bind-time throws — it throws rather than settling an
+* `error` result. A type-legal event a guard rejects is NOT this error (the
+* machine simply takes no transition). Opt out with
+* {@link RunAgentOptions.onIllegalResumeEvent} `'ignore'`.
+*/
+var 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(),
+			machineId,
+			machineVersion,
+			...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 = getAgentMessages(effectiveSnapshot);
+	const messages = typeof options.messages === "function" ? [...options.messages([...priorMessages])] : [...priorMessages, ...options.messages ?? []];
+	const stampMessages = (snapshot) => {
+		if (!options.getRequests && !options.messages && messages.length === 0) return;
+		if (snapshot && typeof snapshot === "object") snapshot.messages = [...messages];
+	};
+	if (effectiveSnapshot !== void 0 && options.event !== void 0 && (options.onIllegalResumeEvent ?? "throw") === "throw") {
+		const acceptedTypes = getAcceptedEvents(createActor(boundMachine, { snapshot: effectiveSnapshot }).getSnapshot(), { schemas: runCtx.schemas }).map((descriptor) => descriptor.type);
+		const eventType = options.event.type;
+		if (!acceptedTypes.includes(eventType)) throw new 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) {
+				const info = {
+					runId,
+					machineId,
+					machineVersion
+				};
+				for (const item of items) options.onMessage(item, info);
+			}
+		};
+		const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
+		const settleInterpretError = (error) => {
+			settle({
+				status: "error",
+				cause: runErrorCause(error),
+				error,
+				snapshot: actor.getSnapshot()
+			});
+		};
+		const passDeps = {
+			getSnapshot: () => actor.getSnapshot(),
+			send: (event) => actor.send(event),
+			isSettled: () => settled,
+			messages,
+			appendToLog,
+			generateText: runCtx.generateText,
+			decide: runCtx.decide ? createCountingDecide(runCtx) : void 0,
+			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((stateRequest) => Boolean(stateRequest));
+			if (requests.length === 0) return false;
+			interpreting = true;
+			runStateRequestPass(requests, passDeps).then(({ sentAny }) => {
+				if (settled || sentAny) return;
+				const current = actor.getSnapshot();
+				if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) settleIdle(current);
+			}).catch((error) => settleInterpretError(error)).finally(() => {
+				interpreting = false;
+				if (!settled) scheduleIdleCheck();
+			});
+			return true;
+		};
+		const scheduleIdleCheck = () => {
+			if (idleTimer !== void 0) clearTimeout(idleTimer);
+			idleTimer = setTimeout(() => {
+				idleTimer = void 0;
+				if (settled) return;
+				const current = actor.getSnapshot();
+				if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+					if (!maybeInterpret(current)) 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: runErrorCause(snapshot.error),
+						error: snapshot.error,
+						snapshot
+					});
+					return;
+				}
+				if (snapshot.status === "stopped") {
+					settle({
+						status: "error",
+						cause: "stopped",
+						error: /* @__PURE__ */ new Error("Actor stopped externally."),
+						snapshot
+					});
+					return;
+				}
+				if (!deliveringResumeEvent && isSuspended(snapshot) && isIdleSnapshot(snapshot, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+					if (!maybeInterpret(snapshot)) settleIdle(snapshot);
+					return;
+				}
+				scheduleIdleCheck();
+			}
+		});
+		actorHolder.actorRef = actor;
+		actor.subscribe({ error: () => {} });
+		actor.on("*", (event) => {
+			onTrace({
+				type: "emit",
+				event
+			});
+		});
+		for (const [type, handler] of Object.entries(options.on ?? {})) if (typeof handler === "function") actor.on(type, handler);
+		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
+export { runAgent as a, setupAgent as c, inspectTransitions as i, appendMessages as l, IllegalResumeEventError as n, runAgentToCompletion as o, SnapshotVersionMismatchError as r, createAgentSchemas as s, AgentIdleError as t, messagesSchema as u };