@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/dist/index.mjs

@@ -1,588 +1,2493 @@
-// src/agent.ts
-import {
-  createActor,
-  fromTransition
-} from "xstate";
-
-// src/planners/simplePlanner.ts
-import { tool } from "ai";
-
-// src/utils.ts
-import hash from "object-hash";
-function getAllTransitions(state) {
-  const nodes = state._nodes;
-  const transitions = nodes.map((node) => [...node.transitions.values()]).map((nodeTransitions) => {
-    return nodeTransitions.map((nodeEventTransitions) => {
-      return nodeEventTransitions.map((transition) => {
-        return {
-          ...transition,
-          guard: typeof transition.guard === "string" ? { type: transition.guard } : transition.guard
-          // TODO: fix
-        };
-      });
-    });
-  }).flat(2);
-  return transitions;
-}
-function getAllMachineTransitions(stateNode) {
-  const transitions = [...stateNode.transitions.values()].map((nodeTransitions) => {
-    return nodeTransitions.map((transition) => {
-      return {
-        ...transition,
-        guard: typeof transition.guard === "string" ? { type: transition.guard } : transition.guard
-        // TODO: fix
-      };
-    });
-  }).flat(2);
-  for (const s of Object.values(stateNode.states)) {
-    const stateTransitions = getAllMachineTransitions(s);
-    transitions.push(...stateTransitions);
-  }
-  return transitions;
-}
-function wrapInXml(tagName, content) {
-  return `<${tagName}>${content}</${tagName}>`;
-}
-function randomId() {
-  const timestamp = Date.now().toString(36);
-  const random = Math.random().toString(36).substring(2, 9);
-  return timestamp + random;
-}
-var machineHashes = /* @__PURE__ */ new WeakMap();
-function getMachineHash(machine) {
-  if (machineHashes.has(machine)) return machineHashes.get(machine);
-  const transitions = getAllMachineTransitions(machine.root);
-  const machineHash = hash(transitions);
-  machineHashes.set(machine, machineHash);
-  return machineHash;
-}
-
-// src/templates/defaultText.ts
-var defaultTextTemplate = (data) => {
-  const preamble = [
-    data.context ? wrapInXml("context", JSON.stringify(data.context)) : void 0
-  ].filter(Boolean).join("\n");
-  return `
-${preamble}
-
-${data.goal}
-  `.trim();
+import { A as assistantMessage, B as toolMessage, C as agentExecutionOptions, D as isUnboundPlaceholder, E as getRegisteredAgentExecutionOptions, F as getMachineStructuralHash, H as validateSchemaSync, I as getStateMeta, M as getAgentMessages, O as machineSuspensionPredicates, P as getJsonSchemaSync, R as persistSnapshot, S as userInputActor, T as getMachineSuspensionPredicate, V as userMessage, _ as isTextLogic, a as sanitizeEventToolName, c as PLAN_ACTOR, f as builtinTextActors, i as parseAgentEvent, j as findNonSerializableContextPaths, k as missingActor, l as USER_INPUT_ACTOR, o as DECIDE_ACTOR, p as createTextLogic, s as INTERPRET_SOURCE, t as getAcceptedEvents, v as normalizeGeneratorResult, w as executorBoundLogics, z as systemMessage } from "./events-JiVPYrct.mjs";
+import { a as createPlanActor, c as isPlanLogic, i as createDecideActor, n as PLAN_DONE_EVENT_TYPE, o as initialPlanLedger, r as advancePlanLedger, s as isDecisionLogic, t as DecisionExhaustedError, u as resolveDecision } from "./decision-C3k4ve51.mjs";
+import { a as resolveAgentRequests, i as initialAgentStep, o as resolveAgentStep, r as getInvokeEffectMetadata, s as transitionAgentStep } from "./steps-CkyyyuHd.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 DECIDE_SRC$1 = "agent.decide";
+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 applyWorkflowTransitionActions(actionConfig, scope, enq) {
+	if (!actionConfig) return;
+	const actions = Array.isArray(actionConfig) ? actionConfig : [actionConfig];
+	let assigned;
+	for (const action of actions) if (action.assign !== void 0) assigned = {
+		...assigned ?? {},
+		...Object.fromEntries(Object.entries(action.assign).map(([key, value]) => [key, evaluateWorkflowConfigValue(value, scope)]))
+	};
+	else if (action.emit !== void 0) enq.emit(evaluateWorkflowConfigValue(action.emit, scope));
+	else if (action.type) throw new Error(`setupAgent.fromConfig: named action type '${action.type}' is not supported in a transition 'actions' entry (config lowering wires no action implementations). Use 'emit' or 'assign', or move it to a state 'entry'/'exit'.`);
+	else throw new Error("setupAgent.fromConfig: a transition action must declare 'emit', 'assign', or 'type'.");
+	return assigned;
+}
+function lowerWorkflowTransitionResult(transitionConfig, scope, enq) {
+	const actionAssign = applyWorkflowTransitionActions(transitionConfig.actions, scope, enq);
+	const configAssign = transitionConfig.assign ? Object.fromEntries(Object.entries(transitionConfig.assign).map(([key, value]) => [key, evaluateWorkflowConfigValue(value, scope)])) : void 0;
+	const context = configAssign || actionAssign ? {
+		...configAssign ?? {},
+		...actionAssign ?? {}
+	} : void 0;
+	return {
+		...transitionConfig.target !== void 0 ? { target: transitionConfig.target } : {},
+		...context ? { context } : {},
+		...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 }, enq) => {
+		const scope = {
+			context,
+			event
+		};
+		if (!workflowTransitionMatches(transitionConfig, scope)) return;
+		return lowerWorkflowTransitionResult(transitionConfig, scope, enq);
+	};
+}
+function lowerWorkflowTransitionOrArray(transitionConfig) {
+	if (!transitionConfig) return;
+	return Array.isArray(transitionConfig) ? ({ context, event }, enq) => {
+		const scope = {
+			context,
+			event
+		};
+		const transition = transitionConfig.find((candidate) => workflowTransitionMatches(candidate, scope));
+		if (!transition) return;
+		return lowerWorkflowTransitionResult(transition, scope, enq);
+	} : lowerWorkflowTransition(transitionConfig);
+}
+function lowerWorkflowInvoke(invokeConfig, stateKey) {
+	if (invokeConfig.src === DECIDE_SRC$1 && invokeConfig.onDone !== void 0) throw new Error(`setupAgent.fromConfig: state '${stateKey}' declares an 'onDone' on its 'agent.decide' invoke, which is always a config error. A decision has no output of its own — the chosen event is delivered automatically and handled by the state's 'on' transitions. Remove the 'onDone' (use 'on' for the chosen event; 'onError' still handles retries exhausted).`);
+	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 assertValidTransitionTargets(stateKey, location, transitionConfig, siblingKeys) {
+	if (!transitionConfig) return;
+	const transitions = Array.isArray(transitionConfig) ? transitionConfig : [transitionConfig];
+	for (const transition of transitions) {
+		const targets = transition.target === void 0 ? [] : Array.isArray(transition.target) ? transition.target : [transition.target];
+		for (const target of targets) {
+			if (typeof target !== "string" || target.startsWith("#") || target.startsWith(".")) continue;
+			const head = target.split(".")[0];
+			if (!siblingKeys.has(head)) throw new Error(`setupAgent.fromConfig: state '${stateKey}' has a ${location} transition targeting '${target}', which is not a state at that level. Valid targets: ${[...siblingKeys].join(", ") || "(none)"}.`);
+		}
+	}
+}
+function assertStateTransitionTargets(stateKey, stateConfig, siblingKeys) {
+	for (const [eventType, transition] of Object.entries(stateConfig.on ?? {})) assertValidTransitionTargets(stateKey, `'on.${eventType}'`, transition, siblingKeys);
+	for (const [delay, transition] of Object.entries(stateConfig.after ?? {})) assertValidTransitionTargets(stateKey, `'after.${delay}'`, transition, siblingKeys);
+	assertValidTransitionTargets(stateKey, "'always'", stateConfig.always, siblingKeys);
+	assertValidTransitionTargets(stateKey, "'onDone'", stateConfig.onDone, siblingKeys);
+	assertValidTransitionTargets(stateKey, "'choice'", stateConfig.choice, siblingKeys);
+	const invokes = stateConfig.invoke ? Array.isArray(stateConfig.invoke) ? stateConfig.invoke : [stateConfig.invoke] : [];
+	for (const invoke of invokes) {
+		assertValidTransitionTargets(stateKey, "invoke 'onDone'", invoke.onDone, siblingKeys);
+		assertValidTransitionTargets(stateKey, "invoke 'onError'", invoke.onError, siblingKeys);
+	}
+}
+function lowerWorkflowState(stateKey, stateConfig, siblingKeys) {
+	assertStateTransitionTargets(stateKey, stateConfig, siblingKeys);
+	const childKeys = new Set(Object.keys(stateConfig.states ?? {}));
+	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(key, child, childKeys)])) } : {},
+		...stateConfig.choice !== void 0 ? { choice: lowerWorkflowTransitionOrArray(stateConfig.choice) } : {},
+		...stateConfig.invoke !== void 0 ? { invoke: Array.isArray(stateConfig.invoke) ? stateConfig.invoke.map((invoke) => lowerWorkflowInvoke(invoke, stateKey)) : lowerWorkflowInvoke(stateConfig.invoke, stateKey) } : {},
+		...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: (() => {
+			const rootKeys = new Set(Object.keys(config.states));
+			return Object.fromEntries(Object.entries(config.states).map(([key, state]) => [key, lowerWorkflowState(key, state, rootKeys)]));
+		})(),
+		...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`/`agent.plan` 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;
+	}
 };
-
-// src/text.ts
-import {
-  fromObservable,
-  fromPromise,
-  toObserver
-} from "xstate";
-async function getMessages(agent, prompt, options) {
-  let messages = [];
-  if (typeof options.messages === "function") {
-    messages = await options.messages(agent);
-  } else if (options.messages) {
-    messages = options.messages;
-  }
-  messages = messages.concat({
-    role: "user",
-    content: prompt
-  });
-  return messages;
-}
-async function agentGenerateText(agent, options) {
-  const resolvedOptions = {
-    ...agent.defaultOptions,
-    ...options,
-    correlationId: options.correlationId ?? randomId()
-  };
-  const template = resolvedOptions.template ?? defaultTextTemplate;
-  const id = randomId();
-  const goal = typeof resolvedOptions.prompt === "string" ? resolvedOptions.prompt : await resolvedOptions.prompt(agent);
-  const promptWithContext = template({
-    goal,
-    context: resolvedOptions.context
-  });
-  const messages = await getMessages(agent, promptWithContext, resolvedOptions);
-  agent.addMessage({
-    id,
-    role: "user",
-    content: promptWithContext,
-    timestamp: Date.now(),
-    correlationId: resolvedOptions.correlationId,
-    parentCorrelationId: resolvedOptions.parentCorrelationId
-  });
-  const result = await agent.adapter.generateText({
-    ...resolvedOptions,
-    prompt: void 0,
-    messages
-  });
-  agent.addMessage({
-    content: result.text,
-    id,
-    role: "assistant",
-    timestamp: Date.now(),
-    responseId: id,
-    result,
-    correlationId: resolvedOptions.correlationId,
-    parentCorrelationId: resolvedOptions.parentCorrelationId
-  });
-  return {
-    ...result,
-    parentCorrelationId: resolvedOptions.parentCorrelationId,
-    correlationId: resolvedOptions.correlationId
-  };
-}
-async function agentStreamText(agent, options) {
-  const resolvedOptions = {
-    ...agent.defaultOptions,
-    ...options,
-    correlationId: options.correlationId ?? randomId()
-  };
-  const template = resolvedOptions.template ?? defaultTextTemplate;
-  const id = randomId();
-  const goal = typeof resolvedOptions.prompt === "string" ? resolvedOptions.prompt : await resolvedOptions.prompt(agent);
-  const promptWithContext = template({
-    goal,
-    context: resolvedOptions.context
-  });
-  const messages = await getMessages(agent, promptWithContext, resolvedOptions);
-  agent.addMessage({
-    role: "user",
-    content: promptWithContext,
-    id,
-    timestamp: Date.now(),
-    correlationId: resolvedOptions.correlationId,
-    parentCorrelationId: resolvedOptions.parentCorrelationId
-  });
-  const result = await agent.adapter.streamText({
-    ...resolvedOptions,
-    prompt: void 0,
-    messages,
-    onFinish: async (res) => {
-      agent.addMessage({
-        role: "assistant",
-        result: {
-          text: res.text,
-          finishReason: res.finishReason,
-          logprobs: void 0,
-          responseMessages: [],
-          toolCalls: [],
-          toolResults: [],
-          usage: res.usage,
-          warnings: res.warnings,
-          rawResponse: res.rawResponse,
-          roundtrips: [],
-          // TODO: how do we get this information?,
-          steps: res.steps,
-          response: res.response,
-          experimental_providerMetadata: res.experimental_providerMetadata
-        },
-        content: res.text,
-        id: randomId(),
-        timestamp: Date.now(),
-        responseId: id,
-        correlationId: resolvedOptions.correlationId,
-        parentCorrelationId: resolvedOptions.parentCorrelationId
-      });
-    }
-  });
-  return {
-    ...result,
-    textStream: result.textStream,
-    fullStream: result.fullStream,
-    parentCorrelationId: resolvedOptions.parentCorrelationId,
-    correlationId: resolvedOptions.correlationId
-  };
-}
-function fromTextStream(agent, defaultOptions) {
-  return fromObservable(({ input }) => {
-    const observers = /* @__PURE__ */ new Set();
-    (async () => {
-      const result = await agentStreamText(agent, {
-        ...defaultOptions,
-        ...input,
-        context: input.context
-      });
-      for await (const part of result.fullStream) {
-        if (part.type === "text-delta") {
-          observers.forEach((observer) => {
-            observer.next?.(part);
-          });
-        }
-      }
-    })();
-    return {
-      subscribe: (...args) => {
-        const observer = toObserver(...args);
-        observers.add(observer);
-        return {
-          unsubscribe: () => {
-            observers.delete(observer);
-          }
-        };
-      }
-    };
-  });
-}
-function fromText(agent, defaultOptions) {
-  return fromPromise(async ({ input }) => {
-    return await agentGenerateText(agent, {
-      ...input,
-      ...defaultOptions,
-      context: input.context
-    });
-  });
-}
-
-// src/planners/simplePlanner.ts
-function getTransitions(state, machine) {
-  if (!machine) {
-    return [];
-  }
-  const resolvedState = machine.resolveState(state);
-  return getAllTransitions(resolvedState);
-}
-var simplePlannerPromptTemplate = (data) => {
-  return `
-${defaultTextTemplate(data)}
-
-Make at most one tool call to achieve the above goal. If the goal cannot be achieved with any tool calls, do not make any tool call.
-  `.trim();
+/**
+* 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;
+	}
 };
-async function simplePlanner(agent, input) {
-  const transitions = input.machine ? getTransitions(input.state, input.machine) : Object.entries(input.events).map(([eventType, { description }]) => ({
-    eventType,
-    description
-  }));
-  const filter = (eventType) => Object.keys(input.events).includes(eventType);
-  const functionNameMapping = {};
-  const toolTransitions = transitions.filter((t) => {
-    return filter(t.eventType);
-  }).map((t) => {
-    const name = t.eventType.replace(/\./g, "_");
-    functionNameMapping[name] = t.eventType;
-    return {
-      type: "function",
-      eventType: t.eventType,
-      description: t.description,
-      name
-    };
-  });
-  const toolMap = {};
-  for (const toolTransitionData of toolTransitions) {
-    const toolZodType = input.events?.[toolTransitionData.eventType];
-    if (!toolZodType) {
-      continue;
-    }
-    toolMap[toolTransitionData.name] = tool({
-      description: toolZodType?.description ?? toolTransitionData.description,
-      parameters: toolZodType,
-      execute: async (params) => {
-        const event = {
-          type: toolTransitionData.eventType,
-          ...params
-        };
-        return event;
-      }
-    });
-  }
-  if (!Object.keys(toolMap).length) {
-    return void 0;
-  }
-  const prompt = simplePlannerPromptTemplate({
-    context: input.state.context,
-    goal: input.goal
-  });
-  const messages = await getMessages(agent, prompt, input);
-  const result = await agent.generateText({
-    toolChoice: "required",
-    ...input,
-    prompt,
-    messages,
-    tools: toolMap
-  });
-  const singleResult = result.toolResults[0];
-  if (!singleResult) {
-    console.warn("No tool call results returned");
-    return void 0;
-  }
-  return {
-    goal: input.goal,
-    state: input.state,
-    execute: async (state) => {
-      if (JSON.stringify(state) === JSON.stringify(input.state)) {
-        return singleResult.result;
-      }
-      return void 0;
-    },
-    nextEvent: singleResult.result,
-    sessionId: agent.sessionId,
-    timestamp: Date.now()
-  };
-}
-
-// src/decision.ts
-import { fromPromise as fromPromise2 } from "xstate";
-async function agentDecide(agent, options) {
-  const resolvedOptions = {
-    ...agent.defaultOptions,
-    ...options
-  };
-  const {
-    planner = simplePlanner,
-    goal,
-    events = agent.events,
-    state,
-    machine,
-    model = agent.model,
-    ...otherPlanInput
-  } = resolvedOptions;
-  const plan = await planner(agent, {
-    model,
-    goal,
-    events,
-    state,
-    machine,
-    ...otherPlanInput
-  });
-  if (plan?.nextEvent) {
-    agent.addPlan(plan);
-    await resolvedOptions.execute?.(plan.nextEvent);
-  }
-  return plan;
-}
-function fromDecision(agent, defaultInput) {
-  return fromPromise2(async ({ input, self }) => {
-    const parentRef = self._parent;
-    if (!parentRef) {
-      return;
-    }
-    const snapshot = parentRef.getSnapshot();
-    const inputObject = typeof input === "string" ? { goal: input } : input;
-    const resolvedInput = {
-      ...defaultInput,
-      ...inputObject
-    };
-    const contextToInclude = resolvedInput.context === true ? (
-      // include entire context
-      parentRef.getSnapshot().context
-    ) : resolvedInput.context;
-    const state = {
-      value: snapshot.value,
-      context: contextToInclude
-    };
-    const plan = await agentDecide(agent, {
-      machine: parentRef.logic,
-      state,
-      execute: async (event) => {
-        parentRef.send(event);
-      },
-      ...resolvedInput
-    });
-    return plan;
-  });
-}
-
-// src/adapters/vercel.ts
-import { generateText, streamText } from "ai";
-var vercelAdapter = {
-  generateText,
-  streamText
+/**
+* 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;
+	}
 };
-
-// src/agent.ts
-var agentLogic = fromTransition(
-  (state, event, { emit }) => {
-    switch (event.type) {
-      case "agent.feedback": {
-        state.feedback.push(event.feedback);
-        emit({
-          type: "feedback",
-          // @ts-ignore TODO: fix types in XState
-          feedback: event.feedback
-        });
-        break;
-      }
-      case "agent.observe": {
-        state.observations.push(event.observation);
-        emit({
-          type: "observation",
-          // @ts-ignore TODO: fix types in XState
-          observation: event.observation
-        });
-        break;
-      }
-      case "agent.message": {
-        state.messages.push(event.message);
-        emit({
-          type: "message",
-          // @ts-ignore TODO: fix types in XState
-          message: event.message
-        });
-        break;
-      }
-      case "agent.plan": {
-        state.plans.push(event.plan);
-        emit({
-          type: "plan",
-          // @ts-ignore TODO: fix types in XState
-          plan: event.plan
-        });
-        break;
-      }
-      default:
-        break;
-    }
-    return state;
-  },
-  () => ({
-    feedback: [],
-    messages: [],
-    observations: [],
-    plans: []
-  })
-);
-function createAgent({
-  name,
-  description,
-  model,
-  events,
-  context,
-  planner = simplePlanner,
-  stringify = JSON.stringify,
-  getMemory,
-  logic = agentLogic,
-  adapter = vercelAdapter,
-  ...generateTextOptions
-}) {
-  const agent = createActor(logic);
-  agent.events = events;
-  agent.model = model;
-  agent.name = name;
-  agent.description = description;
-  agent.adapter = adapter;
-  agent.defaultOptions = { ...generateTextOptions, model };
-  agent.select = (selector) => {
-    return selector(agent.getSnapshot().context);
-  };
-  agent.memory = getMemory ? getMemory(agent) : void 0;
-  agent.onMessage = (callback) => {
-    agent.on("message", (ev) => callback(ev.message));
-  };
-  agent.decide = (opts) => {
-    return agentDecide(agent, opts);
-  };
-  agent.addMessage = (messageInput) => {
-    const message = {
-      ...messageInput,
-      id: messageInput.id ?? randomId(),
-      timestamp: messageInput.timestamp ?? Date.now(),
-      sessionId: agent.sessionId,
-      correlationId: messageInput.correlationId ?? randomId()
-    };
-    agent.send({
-      type: "agent.message",
-      message
-    });
-    return message;
-  };
-  agent.getMessages = () => agent.getSnapshot().context.messages;
-  agent.generateText = (opts) => agentGenerateText(agent, opts);
-  agent.streamText = (opts) => agentStreamText(agent, opts);
-  agent.addFeedback = (feedbackInput) => {
-    const feedback = {
-      ...feedbackInput,
-      attributes: { ...feedbackInput.attributes },
-      reward: feedbackInput.reward ?? 0,
-      timestamp: feedbackInput.timestamp ?? Date.now(),
-      sessionId: agent.sessionId
-    };
-    agent.send({
-      type: "agent.feedback",
-      feedback
-    });
-    return feedback;
-  };
-  agent.getFeedback = () => agent.getSnapshot().context.feedback;
-  agent.addObservation = (observationInput) => {
-    const { prevState, event, state } = observationInput;
-    const observation = {
-      prevState,
-      event,
-      state,
-      id: observationInput.id ?? randomId(),
-      sessionId: agent.sessionId,
-      timestamp: observationInput.timestamp ?? Date.now(),
-      machineHash: observationInput.machine ? getMachineHash(observationInput.machine) : void 0
-    };
-    agent.send({
-      type: "agent.observe",
-      observation
-    });
-    return observation;
-  };
-  agent.getObservations = () => agent.getSnapshot().context.observations;
-  agent.addPlan = (plan) => {
-    agent.send({
-      type: "agent.plan",
-      plan
-    });
-  };
-  agent.getPlans = () => agent.getSnapshot().context.plans;
-  agent.interact = (actorRef, getInput) => {
-    let prevState = void 0;
-    let subscribed = true;
-    async function handleObservation(observationInput) {
-      const observation = agent.addObservation(observationInput);
-      const input = getInput?.(observation);
-      if (input) {
-        await agentDecide(agent, {
-          machine: actorRef.src,
-          state: observation.state,
-          execute: async (event) => {
-            actorRef.send(event);
-          },
-          ...input
-        });
-      }
-      prevState = observationInput.state;
-    }
-    actorRef.system.inspect({
-      next: async (inspEvent) => {
-        if (!subscribed || inspEvent.actorRef !== actorRef || inspEvent.type !== "@xstate.snapshot") {
-          return;
-        }
-        const observationInput = {
-          event: inspEvent.event,
-          prevState,
-          state: inspEvent.snapshot,
-          machine: actorRef.src
-        };
-        await handleObservation(observationInput);
-      }
-    });
-    if (actorRef._processingStatus === 1) {
-      handleObservation({
-        prevState: void 0,
-        event: { type: "" },
-        // TODO: unknown events?
-        state: actorRef.getSnapshot(),
-        machine: actorRef.src
-      });
-    }
-    return {
-      unsubscribe: () => {
-        subscribed = false;
-      }
-      // TODO: make this actually unsubscribe
-    };
-  };
-  agent.types = {};
-  agent.start();
-  return agent;
-}
-export {
-  createAgent,
-  fromDecision,
-  fromText,
-  fromTextStream
+/**
+* The version of the {@link AgentTraceEvent} envelope every trace event carries
+* as `schemaVersion`. Bumped only on a breaking change to the envelope or any
+* payload shape, so a consumer can gate on it. Emitted identically by
+* {@link runAgent}, {@link provideExecutors}' `onTrace`, and
+* {@link traceTransitions}.
+*/
+const AGENT_TRACE_SCHEMA_VERSION = 1;
+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;
+}
+/**
+* The shared text/stream emission helper: binds a {@link TextLogic} to
+* `runCtx`'s executor and constructs the `request.start` / `stream.chunk` /
+* `request.end` (incl. the lifted `reasoning`) / `request.error` trace payloads.
+* Used by both `runAgent` and `provideExecutors` so the two paths produce
+* identical event shapes by construction. @internal
+*/
+function wrapTextLogicForRunAgent(logic, runCtx) {
+	return logic.withExecutor(async ({ request, self, signal }) => {
+		const { id, src } = selfIdAndSrc(self);
+		const executor = logic.mode === "stream" ? runCtx.streamText : runCtx.generateText;
+		if (!executor) throw new Error(`runAgent: no '${logic.mode === "stream" ? "streamText" : "generateText"}' executor provided.`);
+		const requestWithTools = {
+			...request,
+			tools: request.tools ?? {}
+		};
+		const agentRequest = {
+			kind: "text",
+			id,
+			src,
+			mode: logic.mode,
+			input: request,
+			tools: requestWithTools.tools,
+			events: []
+		};
+		runCtx.consumeModelCall();
+		runCtx.onTrace?.({
+			type: "request.start",
+			request: agentRequest
+		}, self);
+		try {
+			const raw = await executor(requestWithTools, {
+				onChunk: (chunk) => {
+					runCtx.onTrace?.({
+						type: "stream.chunk",
+						request: agentRequest,
+						chunk
+					}, self);
+					runCtx.onChunk?.(chunk, { request: agentRequest });
+				},
+				signal
+			});
+			const output = await normalizeGeneratorResult(raw, id, {
+				request,
+				onChunk: (chunk) => {
+					runCtx.onTrace?.({
+						type: "stream.chunk",
+						request: agentRequest,
+						chunk
+					}, self);
+					runCtx.onChunk?.(chunk, { request: agentRequest });
+				}
+			});
+			const rawReasoning = raw?.reasoning;
+			const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
+			runCtx.onResult?.(agentRequest, {
+				output,
+				raw
+			});
+			runCtx.onTrace?.({
+				type: "request.end",
+				request: agentRequest,
+				output,
+				raw,
+				...reasoning !== void 0 ? { reasoning } : {}
+			}, self);
+			return { output };
+		} catch (error) {
+			runCtx.onTrace?.({
+				type: "request.error",
+				request: agentRequest,
+				error
+			}, self);
+			throw error;
+		}
+	});
+}
+function createCountingDecide(runCtx, self) {
+	return async (attemptRequest) => {
+		runCtx.consumeModelCall();
+		runCtx.onTrace?.({
+			type: "request.start",
+			request: attemptRequest
+		}, self);
+		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
+			}, self);
+			return result;
+		} catch (error) {
+			runCtx.onTrace?.({
+				type: "request.error",
+				request: attemptRequest,
+				error
+			}, self);
+			throw error;
+		}
+	};
+}
+/**
+* Builds the decision actor logic runAgent installs in place of a
+* `DecisionLogic`/`agent.decide` source. `DecisionLogic.withExecutor(...)`
+* can only swap the innermost per-attempt executor — the `resolveDecision(...)`
+* call (and its `canTake`) is hardwired inside the original logic's `run`.
+* To supply `canTake` (mode-3, §2.6), runAgent instead builds a fresh async
+* logic here that calls `resolveDecision` itself, reusing `logic.request(...)`
+* to build the request the same way the original logic would have.
+*
+* On success it SENDS the chosen event to the invoking actor (auto-delivery,
+* mirroring {@link createRunAgentPlanLogic}) and then completes with that event
+* as its output — so callers never wire an `onDone` to deliver it. See the
+* send-then-complete note inside `run` for how exit-cancels-invoke interacts
+* with `onDone`.
+*/
+function createRunAgentDecisionLogic(logic, runCtx) {
+	const decisionLogic = createAsyncLogic({ run: async ({ input, signal, self }) => {
+		if (!runCtx.decide) throw new Error("runAgent: no 'decide' executor provided.");
+		const { id } = selfIdAndSrc(self);
+		const declaredEventTypes = logic.allowedEventTypes?.(input);
+		await Promise.resolve();
+		const actorRef = invokingActorOf(self, runCtx);
+		const events = actorRef ? getAcceptedEvents(actorRef.getSnapshot(), {
+			schemas: runCtx.schemas,
+			eventTypes: declaredEventTypes
+		}) : [];
+		const chosen = await resolveDecision({
+			...logic.request(input),
+			id,
+			events
+		}, createCountingDecide(runCtx, self), {
+			maxRetries: logic.maxRetries,
+			signal,
+			canTake: (event) => actorRef ? actorRef.getSnapshot().can(event) : true
+		});
+		actorRef?.send(chosen);
+		await Promise.resolve();
+		return chosen;
+	} });
+	return Object.assign(decisionLogic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries: logic.maxRetries,
+		request: logic.request,
+		withExecutor: (nextExecute) => createRunAgentDecisionLogic(logic.withExecutor(nextExecute), runCtx)
+	});
+}
+/**
+* Builds the plan actor logic runAgent installs in place of the `agent.plan`
+* builtin: iterated {@link resolveDecision}. Each step re-reads the live
+* snapshot (so the candidate set reflects everything applied so far), asks
+* the `decide` executor for one legal event with the same validation/retry
+* loop a decision gets, and sends it to the machine. The loop ends on a
+* `stopOn` event, at `maxSteps`, when no legal candidate remains, or when an
+* applied event exits the invoking state (xstate cancels this invoke — the
+* machine simply moves on and the pending output is discarded).
+*
+* The invoke's `input` is resolved once, so the prompt cannot re-render
+* context between steps; instead the applied trail is appended to the prompt
+* each step so the model can see plan progress.
+*/
+function createRunAgentPlanLogic(logic, runCtx) {
+	const planLogic = createAsyncLogic({ run: async ({ input, signal, self }) => {
+		if (!runCtx.decide) throw new Error("runAgent: no 'decide' executor provided.");
+		const { id } = selfIdAndSrc(self);
+		const stopOn = new Set(input.stopOn ?? []);
+		const countingDecide = createCountingDecide(runCtx, self);
+		const base = logic.request(input);
+		let ledger = initialPlanLedger(logic, input);
+		const end = (stopped) => {
+			ledger = advancePlanLedger(logic, ledger, {
+				type: "plan.ended",
+				stopped
+			});
+			return ledger.output;
+		};
+		await Promise.resolve();
+		const invokingActor = invokingActorOf(self, runCtx);
+		while (ledger.context.stepsRemaining > 0) {
+			const actorRef = invokingActor;
+			if (!actorRef || signal.aborted) break;
+			const machineEvents = getAcceptedEvents(actorRef.getSnapshot(), {
+				schemas: runCtx.schemas,
+				eventTypes: logic.allowedEventTypes(input)
+			});
+			if (machineEvents.length === 0) return end("no-legal-events");
+			const doneDescriptor = {
+				type: PLAN_DONE_EVENT_TYPE,
+				toolName: sanitizeEventToolName(PLAN_DONE_EVENT_TYPE)
+			};
+			const events = machineEvents.some((event) => event.type === "agent.plan.done") ? machineEvents : [...machineEvents, doneDescriptor];
+			const applied = ledger.context.applied;
+			const trail = applied.length === 0 ? "" : `\n\nEvents already applied in this plan, in order:\n${applied.map((step) => JSON.stringify(step)).join("\n")}\nContinue from here; do not repeat applied events.`;
+			const doneHint = `\n\nWhen the request is fully handled (or no action is needed), choose '${PLAN_DONE_EVENT_TYPE}'.`;
+			const chosen = await resolveDecision({
+				...base,
+				id: `${id}[${applied.length}]`,
+				events,
+				prompt: `${base.prompt ?? ""}${trail}${doneHint}`,
+				attempts: []
+			}, countingDecide, {
+				maxRetries: input.maxRetries ?? logic.maxRetries,
+				signal,
+				canTake: (event) => {
+					if (event.type === "agent.plan.done" || stopOn.has(event.type)) return true;
+					return invokingActor ? invokingActor.getSnapshot().can(event) : true;
+				}
+			});
+			if (chosen.type === "agent.plan.done") return end("done");
+			actorRef.send(chosen);
+			ledger = advancePlanLedger(logic, ledger, {
+				type: "plan.applied",
+				event: chosen
+			});
+			await Promise.resolve();
+			if (stopOn.has(chosen.type)) return end("stop-event");
+		}
+		return end("max-steps");
+	} });
+	return Object.assign(planLogic, {
+		kind: "statelyai.planLogic",
+		maxRetries: logic.maxRetries,
+		request: logic.request,
+		allowedEventTypes: logic.allowedEventTypes
+	});
+}
+/**
+* The set of string-keyed actor `src`s the machine's own config invokes
+* (top-level, recursing into child STATES but not into invoked child
+* machines). {@link provideExecutors} uses it to require an executor only for a
+* source the machine actually invokes — the always-registered `agent.*`
+* builtins that go unused must not force their executors to be supplied.
+* @internal
+*/
+function getConfiguredInvokeSrcs(machine) {
+	const invokes = [];
+	collectConfiguredInvokeSrcs(machine.config, machine.config.id ?? "(root)", invokes);
+	const srcs = /* @__PURE__ */ new Set();
+	for (const { src } of invokes) if (typeof src === "string") srcs.add(src);
+	return srcs;
+}
+const rootTraceRegistry = /* @__PURE__ */ new WeakMap();
+let nextProvideRunId = 1;
+/** Walks `self._parent` from an invoked async leaf actor up to its root actor. */
+function rootActorOf(self) {
+	let ref = self;
+	if (!ref) return;
+	while (ref._parent) ref = ref._parent;
+	return ref;
+}
+/** The per-root envelope state, minted on first use (runId `run_<n>`, matching runAgent). */
+function rootTraceState(root) {
+	let state = rootTraceRegistry.get(root);
+	if (!state) {
+		const logic = root.logic;
+		const machineId = (logic?.config)?.id ?? logic?.id ?? "(machine)";
+		const machineVersion = logic ? getMachineStructuralHash(logic) : "";
+		state = {
+			runId: `run_${nextProvideRunId++}`,
+			seq: 0,
+			machineId,
+			machineVersion
+		};
+		rootTraceRegistry.set(root, state);
+	}
+	return state;
+}
+/** Stamps a per-root-actor envelope onto a bare trace payload. */
+function stampRootTrace(root, payload) {
+	const state = rootTraceState(root);
+	return {
+		schemaVersion: 1,
+		runId: state.runId,
+		seq: ++state.seq,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		machineId: state.machineId,
+		machineVersion: state.machineVersion,
+		...payload
+	};
+}
+/** Adapts a public `onTrace` into the payload-level {@link RunAgentBindContext.onTrace} sink used by the shared emission helpers. */
+function provideTraceSink(onTrace) {
+	if (!onTrace) return;
+	return (payload, self) => {
+		const root = rootActorOf(self);
+		if (root) onTrace(stampRootTrace(root, payload));
+	};
+}
+/**
+* A minimal {@link RunAgentBindContext} for `provideExecutors` (uncontrolled
+* `createActor`): the same wrappers runAgent installs, MINUS the run-scoped
+* model-call counter. `consumeModelCall` is a no-op (no budget), and
+* `actorHolder.actorRef` is left undefined — the wrappers read the invoking
+* actor off `self._parent`, always present under a live `createActor` tree.
+* `onTrace` (when given) mints a per-root-actor envelope. `schemas` come from
+* the machine's registered `setupAgent` execution options.
+*/
+function provideBindContext(machine, executors, options) {
+	return {
+		generateText: executors.generateText,
+		streamText: executors.streamText,
+		decide: executors.decide,
+		onChunk: options.onChunk ? (chunk) => options.onChunk(chunk) : void 0,
+		onTrace: provideTraceSink(options.onTrace),
+		consumeModelCall: () => {},
+		actorHolder: { actorRef: void 0 },
+		schemas: getRegisteredAgentExecutionOptions(machine).schemas
+	};
+}
+/**
+* Host-binds one text/stream source for {@link provideExecutors} using the SAME
+* emission helper as `runAgent` ({@link wrapTextLogicForRunAgent}), so a bound
+* text request emits request.start/stream.chunk/request.end/request.error with
+* identical shapes. @internal
+*/
+function bindTextForProvide(machine, logic, executors, options) {
+	return wrapTextLogicForRunAgent(logic, provideBindContext(machine, executors, options));
+}
+/**
+* Host-binds one `DecisionLogic`/`agent.decide` source for
+* {@link provideExecutors}: runAgent's decision wrapper (snapshot-driven
+* candidate events, `canTake`, auto-delivery of the chosen event) with the same
+* request-level tracing runAgent emits, minus run-scoped counting. @internal
+*/
+function bindDecisionForProvide(machine, logic, executors, options) {
+	return createRunAgentDecisionLogic(logic, provideBindContext(machine, executors, options));
+}
+/**
+* Host-binds one `agent.plan` source for {@link provideExecutors}: runAgent's
+* plan wrapper (iterated snapshot-driven decisions, auto-delivery) with the same
+* request-level tracing runAgent emits, minus run-scoped counting. @internal
+*/
+function bindPlanForProvide(machine, logic, executors, options) {
+	return createRunAgentPlanLogic(logic, provideBindContext(machine, executors, options));
+}
+/**
+* Recursively rebinds an invoked child machine's own agent sources with the
+* SAME host-backed wrappers runAgent applies to the top-level machine, so a
+* child's text/stream/decision/plan requests inherit runAgent's executors and
+* participate in maxModelCalls counting, onTrace/onChunk/onResult exactly like
+* parent requests. Returns the child machine to invoke: a `.provide`-rebound
+* copy when any inner source needed wrapping, else the original untouched.
+*
+* Only string-keyed sources are visited — a direct-object invoke src cannot be
+* swapped via `.provide` (assertBindable already rejected an unbound request
+* under one). A source that already carries its own executor
+* (`executorBoundLogics`) is left as-is: explicit binding shadows inheritance.
+* Cycle-safe via `visited` (a machine that invokes itself is returned as-is).
+*/
+function rebindChildMachine(childMachine, runCtx, visited) {
+	if (visited.has(childMachine)) return childMachine;
+	const childVisited = new Set([...visited, childMachine]);
+	const sources = childMachine.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?.({
+			schemaVersion: 1,
+			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) : 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) => {
+				if (typeof options.inspect === "function") options.inspect(event);
+				else options.inspect?.next?.(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);
+	};
+}
+/**
+* An xstate `inspect` handler that emits `machine.transition` trace events onto
+* `onTrace`, sharing the SAME versioned envelope and per-root-actor `seq`
+* registry as {@link provideExecutors}' `onTrace`. Pair the two on one actor to
+* get a single ordered trace stream (request + transition events) for the
+* uncontrolled path:
+*
+* ```ts
+* const bound = provideExecutors(machine, executors, { onTrace });
+* const actor = createActor(bound, { inspect: traceTransitions(onTrace) });
+* ```
+*
+* Only ROOT-actor transitions are traced (matching `runAgent`'s
+* `machine.transition`); child-actor transitions are ignored. Attribute the
+* event via its envelope `runId`.
+*
+* By design this path has NO `run.start`/`run.end` events: `createActor` has no
+* run boundary the way `runAgent` does, so the stream starts at the actor's
+* first transition. It also does NOT emit `emit` trace events: in this xstate
+* build emitted events are delivered through `actor.on(...)`, not the inspection
+* protocol, so they are not observable from an `inspect` handler — subscribe
+* with `actor.on('*', ...)` if you need them.
+*/
+function traceTransitions(onTrace) {
+	return (inspectionEvent) => {
+		if (inspectionEvent.type !== "@xstate.transition") return;
+		const actorRef = inspectionEvent.actorRef;
+		if (actorRef?._parent) return;
+		onTrace(stampRootTrace(actorRef, {
+			type: "machine.transition",
+			snapshot: inspectionEvent.snapshot,
+			event: inspectionEvent.event
+		}));
+	};
+}
+function isIdleSnapshot(snapshot, { ignoreUserInputChildren }) {
+	if (snapshot.status !== "active") return false;
+	if (Object.values(snapshot.children ?? {}).some((child) => {
+		const ref = child;
+		if (ignoreUserInputChildren && ref?.src === "agent.userInput") return false;
+		return ref?.getSnapshot?.()?.status === "active";
+	})) return false;
+	return !getNextTransitions(snapshot).some((transitionDef) => transitionDef.eventType === "" || transitionDef.eventType.startsWith("xstate.after"));
+}
+function collectPendingUserInputs(snapshot) {
+	const pending = [];
+	for (const [id, child] of Object.entries(snapshot.children ?? {})) {
+		const ref = child;
+		if (ref?.src !== "agent.userInput") continue;
+		const childSnapshot = ref.getSnapshot?.();
+		if (childSnapshot?.status !== "active") continue;
+		pending.push({
+			id,
+			input: childSnapshot.input
+		});
+	}
+	return pending;
+}
+//#endregion
+//#region src/provide-executors.ts
+/**
+* Binds a machine's agent actor sources to a set of host `executors` in one
+* call, returning a `machine.provide(...)`-ed copy ready for a plain
+* `createActor(...)` — the uncontrolled-mode counterpart to {@link runAgent}.
+* No run loop, no idle settling: the returned machine drives itself, so
+*
+* ```ts
+* const actor = createActor(provideExecutors(machine, { generateText, decide }), { input });
+* actor.start();
+* ```
+*
+* behaves like a normal XState actor whose agent invokes now reach real models.
+*
+* Binding pass over `machine.implementations.actorSources` (after merging
+* `options.actorSources`):
+* - `mode: 'generate'` text source → `executors.generateText`
+* - `mode: 'stream'` text source → `executors.streamText`
+* - decision / `agent.decide` source → `executors.decide` (snapshot-driven
+*   candidate events, guard `canTake`, and auto-delivery of the chosen event,
+*   mirroring `runAgent` but without its model-call counting)
+* - `agent.plan` source → `executors.decide` (iterated, same semantics)
+*
+* Pass `options.onTrace` to observe request-level trace events (identical in
+* shape to `runAgent`'s); pair it with {@link traceTransitions} on the actor's
+* `inspect` to also capture `machine.transition` events in the same stream.
+*
+* A source that already carries its own executor (`.withExecutor(...)`) is left
+* as-is. `agent.userInput` is left UNBOUND — an uncontrolled host handles idle
+* itself, so supply a handler via `options.actorSources` if the machine uses it.
+* Non-agent actors are untouched.
+*
+* Throws at bind time if a source needs an executor kind that `executors` does
+* not provide.
+*
+* v1 does NOT descend into invoked child state machines: a string-keyed child
+* machine source is left untouched, so a child with its own agent invokes needs
+* its own `provideExecutors(...)` (or `runAgent`, which does rebind children).
+*/
+function provideExecutors(machine, executors, options = {}) {
+	const bindOptions = {
+		onChunk: options.onChunk,
+		onTrace: options.onTrace
+	};
+	const provided = options.actorSources ? machine.provide({ actorSources: options.actorSources }) : machine;
+	const effectiveSources = provided.implementations.actorSources;
+	const wrappedSources = {};
+	const invokedSrcs = getConfiguredInvokeSrcs(provided);
+	for (const [key, logic] of Object.entries(effectiveSources)) {
+		if (key === "agent.userInput") continue;
+		if (isDecisionLogic(logic)) {
+			if (executorBoundLogics.has(logic)) continue;
+			if (!executors.decide) {
+				if (invokedSrcs.has(key)) throw missingExecutorError(key, "decision", "decide");
+				continue;
+			}
+			wrappedSources[key] = bindDecisionForProvide(provided, logic, executors, bindOptions);
+			continue;
+		}
+		if (isPlanLogic(logic)) {
+			if (!executors.decide) {
+				if (invokedSrcs.has(key)) throw missingExecutorError(key, "plan", "decide");
+				continue;
+			}
+			wrappedSources[key] = bindPlanForProvide(provided, logic, executors, bindOptions);
+			continue;
+		}
+		if (isTextLogic(logic)) {
+			if (executorBoundLogics.has(logic)) continue;
+			if (!(logic.mode === "stream" ? executors.streamText : executors.generateText)) {
+				if (invokedSrcs.has(key)) throw logic.mode === "stream" ? missingExecutorError(key, "streaming text", "streamText") : missingExecutorError(key, "text", "generateText");
+				continue;
+			}
+			wrappedSources[key] = bindTextForProvide(provided, logic, executors, bindOptions);
+			continue;
+		}
+	}
+	return provided.provide({ actorSources: wrappedSources });
+}
+function missingExecutorError(src, kind, executor) {
+	return /* @__PURE__ */ new Error(`provideExecutors: actor source '${src}' is a ${kind} source but no '${executor}' executor was provided. Add it to the executors object, or bind the source with its own executor (logic.withExecutor(...)) before calling provideExecutors.`);
+}
+//#endregion
+//#region src/verify.ts
+const DECIDE_SRC = "agent.decide";
+const PLAN_SRC = "agent.plan";
+function normalizeInvokes(invoke) {
+	if (invoke === void 0 || invoke === null) return [];
+	return Array.isArray(invoke) ? invoke : [invoke];
+}
+function buildStateIndex(rootConfig) {
+	const index = /* @__PURE__ */ new Map();
+	const walk = (states, parentPath) => {
+		for (const [name, config] of Object.entries(states ?? {})) {
+			const path = parentPath ? `${parentPath}.${name}` : name;
+			const hasChildren = !!config.states && Object.keys(config.states).length > 0;
+			index.set(path, {
+				path,
+				name,
+				config,
+				parentPath,
+				type: config.type,
+				isFinal: config.type === "final",
+				isParallel: config.type === "parallel",
+				isCompound: hasChildren && config.type !== "parallel",
+				invokes: normalizeInvokes(config.invoke)
+			});
+			if (hasChildren) walk(config.states, path);
+		}
+	};
+	walk(rootConfig.states, "");
+	return index;
+}
+function childrenOf(index, parentPath) {
+	const out = [];
+	for (const node of index.values()) if (node.parentPath === parentPath) out.push(node);
+	return out;
+}
+function collectTransitionTargets(value, fromNode, index, out) {
+	if (value === void 0 || value === null) return;
+	if (Array.isArray(value)) {
+		for (const item of value) collectTransitionTargets(item, fromNode, index, out);
+		return;
+	}
+	if (typeof value === "function") {
+		out.opaque = true;
+		return;
+	}
+	if (typeof value === "string") {
+		resolveTargetString(value, fromNode, index, out);
+		return;
+	}
+	if (typeof value === "object") {
+		const target = 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 isBuiltinOrWildcardEvent(eventType) {
+	return eventType === "*" || eventType.includes("*") || eventType.startsWith("xstate.") || eventType.startsWith("done.") || eventType.startsWith("error.");
+}
+function checkUndeclaredEvents(ctx) {
+	const declared = ctx.schemas?.events;
+	if (!declared || Object.keys(declared).length === 0) return [];
+	const declaredTypes = new Set(Object.keys(declared));
+	const out = [];
+	for (const node of ctx.index.values()) for (const eventType of Object.keys(node.config.on ?? {})) {
+		if (declaredTypes.has(eventType) || isBuiltinOrWildcardEvent(eventType)) continue;
+		out.push({
+			code: "undeclared-event",
+			severity: "warning",
+			path: node.path,
+			message: `State '${node.path}' handles event '${eventType}' in 'on:', but it is not declared in schemas.events and is not a builtin/wildcard pattern. If intentional its payload stays unvalidated; otherwise this is likely a typo.`
+		});
+	}
+	return out;
+}
+function checkMissingFinal(ctx) {
+	for (const node of ctx.index.values()) if (node.isFinal && ctx.reachable.has(node.path)) return [];
+	return [{
+		code: "missing-final",
+		severity: "warning",
+		path: "(root)",
+		message: "The machine has no reachable final state, so a run can never settle 'done' (only idle/looping). This is legal for agents that only idle, but verify it is intended."
+	}];
+}
+const LINT_CHECKS = [
+	checkUnreachableStates,
+	checkDecideWithoutEvents,
+	checkUnserializableContext,
+	checkDirectObjectSrc,
+	checkFinalWithoutOutput,
+	checkFinalOutputReadsEvent,
+	checkUndeclaredEvents,
+	checkMissingFinal
+];
+/**
+* Runs static structural checks over a built agent machine and returns the
+* findings ({@link AgentLintDiagnostic}[], empty when clean). Works for
+* TS-authored (`setupAgent(...).createMachine(...)`) and
+* `setupAgent.fromConfig(...)`-compiled machines alike, reading `machine.config`
+* plus the schemas/actor sources the library already retains per machine.
+*
+* No model calls, no API keys — a coding agent that emits an agent machine can
+* call this to catch dead states, undeliverable decisions, un-rebindable
+* invoke srcs, and output-contract gaps before ever running it.
+*
+* @example
+* ```ts
+* const errors = lintAgentMachine(machine).filter((d) => d.severity === 'error');
+* if (errors.length) throw new Error(errors.map((e) => `${e.path}: ${e.message}`).join('\n'));
+* ```
+*/
+function lintAgentMachine(machine, options = {}) {
+	const config = machine.config ?? {};
+	const index = buildStateIndex(config);
+	const reachable = computeReachable(config, index);
+	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));
+}
+/**
+* Thrown by {@link assertAgentMachine} when lint finds failing diagnostics.
+* `diagnostics` holds the findings; the message lists them one per finding,
+* so a test runner's failure output reads like the CLI's lint report.
+*/
+var AgentLintError = class extends Error {
+	diagnostics;
+	constructor(machineId, diagnostics) {
+		const lines = diagnostics.map((d) => `  ${d.severity === "error" ? "error" : "warn "}  ${d.code}  ${d.path}\n         ${d.message}`);
+		super(`Agent machine '${machineId}' failed lint (${diagnostics.length} finding(s)):\n${lines.join("\n")}`);
+		this.name = "AgentLintError";
+		this.diagnostics = diagnostics;
+	}
 };
+/**
+* Asserts a machine passes {@link lintAgentMachine}: returns silently when
+* clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
+* otherwise. Fails on error-severity findings; set `warnings: true` to fail on
+* warnings too. The one-liner for tests and generation loops:
+*
+* @example
+* ```ts
+* test('agent machine is structurally sound', () => {
+*   assertAgentMachine(machine);
+* });
+* ```
+*/
+function assertAgentMachine(machine, options = {}) {
+	const diagnostics = lintAgentMachine(machine, options);
+	const failing = options.warnings ? diagnostics : diagnostics.filter((d) => d.severity === "error");
+	if (failing.length > 0) throw new AgentLintError(machine.id ?? "(machine)", failing);
+}
+function pendingInvokes(step) {
+	const out = [];
+	for (const action of step.actions) {
+		const metadata = getInvokeEffectMetadata(action);
+		if (typeof metadata?.src === "string" && typeof metadata.id === "string") out.push({
+			id: metadata.id,
+			src: metadata.src
+		});
+	}
+	return out;
+}
+function takeFromQueue(channel, src) {
+	const queue = channel?.[src];
+	if (queue && queue.length > 0) return {
+		found: true,
+		value: queue.shift()
+	};
+	return { found: false };
+}
+/**
+* Deterministically plays a machine through, resolving each request from a
+* {@link SimulationScript} instead of a model — no API keys, no model calls.
+* Runs on the pure step path ({@link initialAgentStep} etc.), so it exercises
+* the real transition logic. Returns the terminal `status`, final `snapshot`,
+* and a `trail` of every step taken.
+*
+* Throws a descriptive error when the script runs dry mid-request, naming the
+* pending request's kind, src, and id so the missing scripted response is
+* obvious.
+*
+* @example
+* ```ts
+* const { status, snapshot } = simulateAgent(machine, {
+*   input: { topic: 'state machines' },
+*   script: { decisions: { 'agent.decide': [{ type: 'END' }] } },
+* });
+* ```
+*/
+async function simulateAgent(machine, options) {
+	const maxSteps = options.maxSteps ?? 100;
+	const script = {
+		text: { ...options.script.text },
+		decisions: mapValues(options.script.decisions ?? {}, (arr) => [...arr]),
+		invokes: mapValues(options.script.invokes ?? {}, (arr) => [...arr])
+	};
+	let step = initialAgentStep(machine, options.input);
+	const trail = [];
+	for (let i = 0; i < maxSteps; i++) {
+		if (step.done) return {
+			status: "done",
+			snapshot: step.snapshot,
+			trail
+		};
+		const request = step.requests[0];
+		if (request) {
+			if (request.kind === "decision") {
+				const decisionSrc = new Map(pendingInvokes(step).map((invoke) => [invoke.id, invoke.src])).get(request.id) ?? request.id;
+				const taken = takeFromQueue(script.decisions, decisionSrc);
+				if (!taken.found) throw scriptDryError("decision", decisionSrc, request.id, request);
+				step = transitionAgentStep(machine, step, taken.value);
+				trail.push({
+					state: step.snapshot.value,
+					appliedEvent: taken.value
+				});
+				continue;
+			}
+			if (request.kind === "plan") {
+				const taken = takeFromQueue(script.decisions, request.src);
+				if (!taken.found) throw scriptDryError("decision", request.src, request.id, request);
+				const event = taken.value;
+				step = await resolveAgentRequests(machine, step, { decide: async () => ({ event }) });
+				trail.push({
+					state: step.snapshot.value,
+					appliedEvent: taken.value
+				});
+				continue;
+			}
+			const taken = takeFromQueue(script.text, request.src);
+			if (!taken.found) throw scriptDryError("text", request.src, request.id);
+			step = resolveAgentStep(machine, step, request, taken.value);
+			trail.push({
+				state: step.snapshot.value,
+				resolvedRequest: {
+					kind: "text",
+					src: request.src,
+					id: request.id
+				}
+			});
+			continue;
+		}
+		const [invoke] = pendingInvokes(step);
+		if (invoke) {
+			const taken = takeFromQueue(script.invokes, invoke.src);
+			if (!taken.found) throw scriptDryError("userInput", invoke.src, invoke.id);
+			step = resolveAgentStep(machine, step, invoke.id, taken.value);
+			trail.push({
+				state: step.snapshot.value,
+				resolvedRequest: {
+					kind: "userInput",
+					src: invoke.src,
+					id: invoke.id
+				}
+			});
+			continue;
+		}
+		return {
+			status: "idle",
+			snapshot: step.snapshot,
+			trail
+		};
+	}
+	return {
+		status: "exhausted",
+		snapshot: step.snapshot,
+		trail
+	};
+}
+function mapValues(obj, fn) {
+	return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, fn(value)]));
+}
+function scriptDryError(kind, src, id, request) {
+	const events = request?.kind === "decision" ? ` Candidate events: ${request.events.map((e) => e.type).join(", ") || "(none)"}.` : "";
+	return /* @__PURE__ */ new Error(`simulateAgent: script ran dry on a pending ${kind} request for src '${src}' (id '${id}'). Add a '${kind}' entry for '${src}' to the script.${events}`);
+}
+async function explore(machine, options, stopWhen) {
+	const maxDepth = options.maxDepth ?? 8;
+	const maxPaths = options.maxPaths ?? 200;
+	const textOutputs = options.textOutputs ?? {};
+	const reachedStates = /* @__PURE__ */ new Set();
+	const reachedValues = [];
+	const terminals = [];
+	const unexplored = [];
+	let prunedByGuard = 0;
+	let pathsExplored = 0;
+	let hitPathCap = false;
+	let witness;
+	const recordState = (snapshot) => {
+		const key = JSON.stringify(snapshot.value);
+		if (!reachedStates.has(key)) {
+			reachedStates.add(key);
+			reachedValues.push(snapshot.value);
+		}
+	};
+	const initial = initialAgentStep(machine, options.input);
+	recordState(initial.snapshot);
+	if (stopWhen?.(initial.snapshot)) witness = [];
+	const advance = (step) => {
+		let current = step;
+		for (let i = 0; i < 1e3; i++) {
+			if (current.done) return { step: current };
+			const request = current.requests[0];
+			if (request && request.kind === "text") {
+				if (!(request.src in textOutputs)) return {
+					step: current,
+					blockedSrc: request.src
+				};
+				current = resolveAgentStep(machine, current, request, textOutputs[request.src]);
+				recordState(current.snapshot);
+				continue;
+			}
+			if (request && (request.kind === "decision" || request.kind === "plan")) return { step: current };
+			const [invoke] = pendingInvokes(current);
+			if (invoke) {
+				if (!(invoke.src in textOutputs)) return {
+					step: current,
+					blockedSrc: invoke.src
+				};
+				current = resolveAgentStep(machine, current, invoke.id, textOutputs[invoke.src]);
+				recordState(current.snapshot);
+				continue;
+			}
+			return { step: current };
+		}
+		return { step: current };
+	};
+	const visit = async (step, path, depth) => {
+		if (witness !== void 0) return;
+		if (pathsExplored >= maxPaths) {
+			hitPathCap = true;
+			return;
+		}
+		const { step: settled, blockedSrc } = advance(step);
+		if (stopWhen?.(settled.snapshot)) {
+			witness = path;
+			return;
+		}
+		if (blockedSrc) {
+			pathsExplored++;
+			terminals.push({
+				status: "needs-output",
+				path,
+				state: settled.snapshot.value,
+				missingSrc: blockedSrc
+			});
+			unexplored.push(`needs-output: no canned output for src '${blockedSrc}' at path [${path.map((e) => e.type).join(", ")}]`);
+			return;
+		}
+		if (settled.done) {
+			pathsExplored++;
+			terminals.push({
+				status: "done",
+				path,
+				state: settled.snapshot.value
+			});
+			return;
+		}
+		const request = settled.requests[0];
+		const isPlan = request?.kind === "plan";
+		const branchEvents = request?.kind === "decision" || request?.kind === "plan" ? request.events.map((descriptor) => ({ type: descriptor.type })) : getAcceptedEvents(settled.snapshot).map((descriptor) => ({ type: descriptor.type }));
+		if (branchEvents.length === 0) {
+			pathsExplored++;
+			terminals.push({
+				status: "idle",
+				path,
+				state: settled.snapshot.value
+			});
+			return;
+		}
+		if (depth >= maxDepth) {
+			pathsExplored++;
+			terminals.push({
+				status: "max-depth",
+				path,
+				state: settled.snapshot.value
+			});
+			unexplored.push(`max-depth: stopped at path [${path.map((e) => e.type).join(", ")}]`);
+			return;
+		}
+		for (const event of branchEvents) {
+			if (witness !== void 0 || pathsExplored >= maxPaths) {
+				if (pathsExplored >= maxPaths) hitPathCap = true;
+				return;
+			}
+			if (!(isPlan && event.type === "agent.plan.done") && !settled.snapshot.can(event)) {
+				prunedByGuard++;
+				continue;
+			}
+			const next = isPlan ? await resolveAgentRequests(machine, settled, { decide: async () => ({ event }) }) : transitionAgentStep(machine, settled, event);
+			recordState(next.snapshot);
+			await visit(next, [...path, event], depth + 1);
+		}
+	};
+	if (witness === void 0) await visit(initial, [], 0);
+	return {
+		report: {
+			reachedStates: reachedValues,
+			terminals,
+			prunedByGuard,
+			unexplored,
+			pathsExplored,
+			hitPathCap
+		},
+		witness
+	};
+}
+/**
+* Enumerates a machine's decision and external-event branches to a bounded
+* depth, model-free, and reports which states are reached and how each path
+* terminates. At each decision request it forks one branch per candidate event
+* (guard-rejected candidates are counted in `prunedByGuard`, not explored); at
+* an idle wait it forks per externally-accepted event. A `agent.plan` request
+* forks the same way — one branch per candidate, including the reserved
+* `agent.plan.done` move — advancing each branch through the real plan protocol
+* (`resolveAgentRequests`), so a plan can consume several depth units. Text/`userInput` invokes
+* are resolved from `textOutputs` (a by-src canned-output map) — a missing src
+* halts that branch with a `needs-output` terminal rather than throwing.
+*
+* Combinatorics are bounded by `maxDepth` (default 8) and `maxPaths` (default
+* 200, reported via `hitPathCap`).
+*
+* @example
+* ```ts
+* const report = await explorePaths(refundMachine, { input: { request: 'x', amount: 5000 } });
+* // report.terminals → both 'refunded' and 'denied'; report.prunedByGuard → 1
+* ```
+*/
+async function explorePaths(machine, options = {}) {
+	return (await explore(machine, options)).report;
+}
+/**
+* Answers "can the machine reach `statePath`?" by exploring its branches (a
+* thin wrapper over {@link explorePaths}). Returns `{ canReach: true, witness }`
+* with the event sequence that reaches it, or `{ canReach: false }`.
+*
+* @example
+* ```ts
+* const { canReach, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
+* // canReach → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
+* ```
+*/
+async function canReach(machine, statePath, options = {}) {
+	const { witness } = await explore(machine, options, (snapshot) => {
+		try {
+			return snapshot.matches(statePath);
+		} catch {
+			return false;
+		}
+	});
+	return witness !== void 0 ? {
+		canReach: true,
+		witness
+	} : { canReach: false };
+}
+//#endregion
+export { AGENT_TRACE_SCHEMA_VERSION, AgentIdleError, AgentLintError, DecisionExhaustedError, IllegalResumeEventError, SnapshotVersionMismatchError, appendMessages, assertAgentMachine, assistantMessage, canReach, createAgentSchemas, createTextLogic, explorePaths, getAcceptedEvents, getAgentMessages, getStateMeta, inspectTransitions, lintAgentMachine, messagesSchema, parseAgentEvent, persistSnapshot, provideExecutors, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage };