@statelyai/agent 2.0.0-alpha.22 → 2.0.0-alpha.24

package/dist/setup-agent-CeO2fARv.mjs

@@ -0,0 +1,639 @@
+import { A as userInputActor, L as machineIdlePredicates, N as getAgentExecutionOptions, R as missingActor, b as createTextLogic, et as validateSchemaSync, g as USER_INPUT_ACTOR, n as createDecideActor, nt as agentMessagesEventSchema, p as DECIDE_ACTOR, rt as appendMessages, tt as AGENT_MESSAGES_EVENT_TYPE, y as builtinTextActors, z as setAgentExecutionOptions } from "./decision-BBZ2jMO1.mjs";
+import { createMachineFromConfig, setup } from "xstate";
+//#region src/usage.ts
+/** Reserved event delivered after a model call reports token usage. */
+const AGENT_USAGE_EVENT_TYPE = "@agent.usage";
+//#endregion
+//#region src/workflow-config.ts
+/**
+* The machines-as-data lowering: `setupAgent(...).fromConfig(config, options)`.
+*
+* Takes a serializable `AgentWorkflowConfig` (the JSON form of an agent
+* machine — published schema at `schemas/agent-workflow.json`, docs at
+* docs/machines-as-data.md), compiles its embedded JSON Schemas with the
+* host-provided `compileSchema`, resolves named guards/actions/actors from
+* `options`, and lowers the whole thing to an ordinary XState machine plus its
+* schema pack. This is what makes LLM-generated and stored-as-JSON machines
+* first-class: the config validates against the shipped schema before any
+* model call, and the resulting machine lints, simulates, and runs like a
+* hand-authored one.
+*/
+const DECIDE_SRC = "agent.decide";
+const workflowConfigWholeExpressionPattern = /^\{\{\s*([\s\S]*?)\s*\}\}$/;
+const workflowConfigTemplateExpressionPattern = /\{\{\s*([\s\S]*?)\s*\}\}/g;
+const workflowConfigHasTemplatePattern = /\{\{[\s\S]*?\}\}/;
+function toArray(value) {
+	return Array.isArray(value) ? value : [value];
+}
+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) {
+	const resolver = (value) => value === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(value, { input });
+	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: resolver(request.system),
+		prompt: resolver(request.prompt),
+		messages: resolver(request.messages),
+		tools: request.tools,
+		toolChoice: request.toolChoice,
+		includeReasoning: request.includeReasoning,
+		temperature: resolver(request.temperature),
+		maxOutputTokens: resolver(request.maxOutputTokens),
+		topP: resolver(request.topP),
+		topK: resolver(request.topK),
+		seed: resolver(request.seed),
+		stopSequences: resolver(request.stopSequences),
+		metadata: resolver(request.metadata)
+	}]));
+}
+function createActorPlaceholdersFromWorkflowConfig(config) {
+	return Object.fromEntries(Object.keys(config.actors ?? {}).map((key) => [key, missingActor(key)]));
+}
+const AGENT_EXPRESSION_LANG = "agent-template";
+function containsTemplateExpression(value) {
+	if (typeof value === "string") return workflowConfigHasTemplatePattern.test(value);
+	if (Array.isArray(value)) return value.some(containsTemplateExpression);
+	if (value && typeof value === "object") return Object.values(value).some(containsTemplateExpression);
+	return false;
+}
+function toWorkflowExpression(value) {
+	if (!containsTemplateExpression(value)) return value;
+	return { "@expr": JSON.stringify(value) };
+}
+function createWorkflowConfigEvaluator(contextSchema) {
+	const decoded = /* @__PURE__ */ new Map();
+	const decode = (source) => {
+		if (!decoded.has(source)) decoded.set(source, JSON.parse(source));
+		return decoded.get(source);
+	};
+	return ({ source, slot, scope }) => {
+		const value = decode(source);
+		if (slot === "context") return validateSchemaSync(contextSchema, evaluateWorkflowConfigValue(value, { input: scope.input }));
+		return evaluateWorkflowConfigValue(value, {
+			context: scope.context,
+			event: scope.event,
+			input: scope.input
+		});
+	};
+}
+function translateWorkflowGuard(guard, translation, location) {
+	if (guard === void 0) return;
+	if (typeof guard === "string") {
+		if (workflowConfigHasTemplatePattern.test(guard)) return { "@expr": JSON.stringify(guard) };
+		if (!(guard in translation.guards)) throw new Error(`setupAgent.fromConfig: ${location} references guard '${guard}', which has no implementation. Provide one via fromConfig options: setupAgent.fromConfig(config, { guards: { '${guard}': ({ context, event }) => ... } }).`);
+		return { type: guard };
+	}
+	if (typeof guard === "function") {
+		const name = `__fromConfigGuard${Object.keys(translation.syntheticGuards).length}`;
+		translation.syntheticGuards[name] = guard;
+		return { type: name };
+	}
+	throw new Error(`setupAgent.fromConfig: ${location} has an unsupported guard value. Use a '{{ ... }}' template string, a named guard reference (string), or a function.`);
+}
+function translateWorkflowAction(action, translation, location) {
+	if (action.assign !== void 0) return {
+		type: "@xstate.assign",
+		context: toWorkflowExpression(action.assign)
+	};
+	if (action.emit !== void 0) return {
+		type: "@xstate.emit",
+		event: toWorkflowExpression(action.emit)
+	};
+	if (action.type) {
+		if (!(action.type in translation.actions)) throw new Error(`setupAgent.fromConfig: ${location} uses named action type '${action.type}', which has no implementation. Provide one via fromConfig options: setupAgent.fromConfig(config, { actions: { '${action.type}': (params) => ... } }).`);
+		return {
+			type: action.type,
+			...action.params !== void 0 ? { params: toWorkflowExpression(action.params) } : {}
+		};
+	}
+	throw new Error(`setupAgent.fromConfig: ${location} action must declare 'assign', 'emit', or 'type'.`);
+}
+function translateWorkflowTransition(transitionConfig, translation, location) {
+	const actionConfigs = transitionConfig.actions ? toArray(transitionConfig.actions) : [];
+	const assignConfigs = [...transitionConfig.assign !== void 0 ? [transitionConfig.assign] : [], ...actionConfigs.filter((action) => action.assign !== void 0).map((action) => action.assign)];
+	const contextPatch = assignConfigs.length ? toWorkflowExpression(Object.assign({}, ...assignConfigs)) : void 0;
+	const actions = actionConfigs.filter((action) => action.assign === void 0).map((action) => translateWorkflowAction(action, translation, location));
+	const guard = translateWorkflowGuard(transitionConfig.guard, translation, location);
+	return {
+		...transitionConfig.target !== void 0 ? { target: transitionConfig.target } : {},
+		...guard ? { guard } : {},
+		...contextPatch !== void 0 ? { context: contextPatch } : {},
+		...actions.length ? { actions } : {},
+		...transitionConfig.description !== void 0 ? { description: transitionConfig.description } : {},
+		...transitionConfig.reenter !== void 0 ? { reenter: transitionConfig.reenter } : {},
+		...transitionConfig.meta !== void 0 ? { meta: transitionConfig.meta } : {}
+	};
+}
+function translateWorkflowTransitions(transitionConfig, translation, location) {
+	if (!transitionConfig) return;
+	return Array.isArray(transitionConfig) ? transitionConfig.map((candidate) => translateWorkflowTransition(candidate, translation, location)) : translateWorkflowTransition(transitionConfig, translation, location);
+}
+function addTransitionMatch(transition, matches) {
+	if (Array.isArray(transition)) return transition.map((candidate) => addTransitionMatch(candidate, matches));
+	return transition ? {
+		...transition,
+		matches: {
+			...transition.matches,
+			...matches
+		}
+	} : void 0;
+}
+function translateWorkflowInvoke(invokeConfig, translation, stateKey) {
+	if (invokeConfig.src === DECIDE_SRC && 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).`);
+	const location = `state '${stateKey}'`;
+	return {
+		...invokeConfig.id !== void 0 ? { id: invokeConfig.id } : {},
+		src: invokeConfig.src,
+		...invokeConfig.input !== void 0 ? { input: toWorkflowExpression(invokeConfig.input) } : {},
+		...invokeConfig.onDone !== void 0 ? { onDone: translateWorkflowTransitions(invokeConfig.onDone, translation, location) } : {},
+		...invokeConfig.onError !== void 0 ? { onError: translateWorkflowTransitions(invokeConfig.onError, translation, location) } : {}
+	};
+}
+function assertValidTransitionTargets(stateKey, location, transitionConfig, siblingKeys, declaredTargets) {
+	if (!transitionConfig) return;
+	for (const transition of toArray(transitionConfig)) {
+		const targets = transition.target === void 0 ? [] : toArray(transition.target);
+		for (const target of targets) {
+			if (typeof target !== "string") continue;
+			declaredTargets.push(target);
+			if (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) {
+	const declaredTargets = [];
+	const invokes = stateConfig.invoke ? toArray(stateConfig.invoke) : [];
+	const sources = [
+		...Object.entries(stateConfig.on ?? {}).map(([eventType, transition]) => [`'on.${eventType}'`, transition]),
+		...Object.entries(stateConfig.after ?? {}).map(([delay, transition]) => [`'after.${delay}'`, transition]),
+		["'always'", stateConfig.always],
+		["'onDone'", stateConfig.onDone],
+		["'choice'", stateConfig.choice],
+		...invokes.flatMap((invoke) => [["invoke 'onDone'", invoke.onDone], ["invoke 'onError'", invoke.onError]])
+	];
+	for (const [location, transition] of sources) assertValidTransitionTargets(stateKey, location, transition, siblingKeys, declaredTargets);
+	return declaredTargets;
+}
+function translateWorkflowState(stateKey, stateConfig, siblingKeys, path, translation) {
+	const location = `state '${stateKey}'`;
+	if (stateKey.includes(".")) throw new Error(`setupAgent.fromConfig: state key '${stateKey}' contains a '.', which is reserved as the state-path separator. Rename the state (e.g. '${stateKey.replace(/\./g, "_")}').`);
+	const childKeys = new Set(Object.keys(stateConfig.states ?? {}));
+	const childPath = [...path, stateKey];
+	translation.transitionTargets[childPath.join(".")] = assertStateTransitionTargets(stateKey, stateConfig, siblingKeys);
+	const doneStateId = stateConfig.onDone !== void 0 ? `@state.${childPath.join(".")}` : void 0;
+	const translatedOn = {
+		...Object.fromEntries(Object.entries(stateConfig.on ?? {}).map(([eventType, transitionConfig]) => [eventType, translateWorkflowTransitions(transitionConfig, translation, location)])),
+		...doneStateId ? { "xstate.done.state": addTransitionMatch(translateWorkflowTransitions(stateConfig.onDone, translation, location), { stateId: doneStateId }) } : {}
+	};
+	return {
+		...stateConfig.description !== void 0 ? { description: stateConfig.description } : {},
+		...stateConfig.type !== void 0 ? { type: stateConfig.type } : {},
+		...doneStateId ? { id: doneStateId } : {},
+		...stateConfig.initial !== void 0 ? { initial: stateConfig.initial } : {},
+		...stateConfig.states !== void 0 ? { states: Object.fromEntries(Object.entries(stateConfig.states).map(([key, child]) => [key, translateWorkflowState(key, child, childKeys, childPath, translation)])) } : {},
+		...stateConfig.choice !== void 0 ? { choice: toArray(stateConfig.choice).map((branch) => {
+			if (branch.actions !== void 0) throw new Error(`setupAgent.fromConfig: state '${stateKey}' has a 'choice' branch with 'actions', which is not supported. Use 'assign' on the branch, or move the actions to the target state's 'entry'.`);
+			const when = translateWorkflowGuard(branch.guard, translation, location);
+			return {
+				...when ? { when } : {},
+				target: branch.target,
+				...branch.assign !== void 0 ? { context: toWorkflowExpression(branch.assign) } : {},
+				...branch.description !== void 0 ? { description: branch.description } : {},
+				...branch.reenter !== void 0 ? { reenter: branch.reenter } : {},
+				...branch.meta !== void 0 ? { meta: branch.meta } : {}
+			};
+		}) } : {},
+		...stateConfig.invoke !== void 0 ? { invoke: Array.isArray(stateConfig.invoke) ? stateConfig.invoke.map((invoke) => translateWorkflowInvoke(invoke, translation, stateKey)) : translateWorkflowInvoke(stateConfig.invoke, translation, stateKey) } : {},
+		...Object.keys(translatedOn).length ? { on: translatedOn } : {},
+		...stateConfig.always !== void 0 ? { always: translateWorkflowTransitions(stateConfig.always, translation, location) } : {},
+		...stateConfig.after !== void 0 ? { after: Object.fromEntries(Object.entries(stateConfig.after).map(([delay, transitionConfig]) => [delay, translateWorkflowTransitions(transitionConfig, translation, location)])) } : {},
+		...stateConfig.entry !== void 0 ? { entry: toArray(stateConfig.entry).map((action) => translateWorkflowAction(action, translation, location)) } : {},
+		...stateConfig.exit !== void 0 ? { exit: toArray(stateConfig.exit).map((action) => translateWorkflowAction(action, translation, location)) } : {},
+		...stateConfig.tags !== void 0 ? { tags: stateConfig.tags } : {},
+		...stateConfig.output !== void 0 ? { output: toWorkflowExpression(stateConfig.output) } : {},
+		...stateConfig.meta !== void 0 ? { meta: stateConfig.meta } : {}
+	};
+}
+function collectTranslatedFinalOutputs(states, outputs = []) {
+	for (const state of Object.values(states ?? {})) {
+		if (state?.type === "final" && state.output !== void 0) outputs.push(state.output);
+		collectTranslatedFinalOutputs(state?.states, outputs);
+	}
+	return outputs;
+}
+function translateWorkflowConfig(config, translation) {
+	const rootKeys = new Set(Object.keys(config.states));
+	const states = Object.fromEntries(Object.entries(config.states).map(([key, state]) => [key, translateWorkflowState(key, state, rootKeys, [], translation)]));
+	const json = {
+		"@exprLang": AGENT_EXPRESSION_LANG,
+		...config.id !== void 0 ? { id: config.id } : {},
+		...config.description !== void 0 ? { description: config.description } : {},
+		...config.context !== void 0 ? { context: { "@expr": JSON.stringify(config.context) } } : {},
+		initial: config.initial,
+		states,
+		...config.meta !== void 0 ? { meta: config.meta } : {}
+	};
+	const finalOutputs = collectTranslatedFinalOutputs(states);
+	if (json.output === void 0 && finalOutputs.length === 1) json.output = finalOutputs[0];
+	return json;
+}
+function collectDeclaredStateTags(states, tags = /* @__PURE__ */ new Set()) {
+	for (const state of Object.values(states ?? {})) {
+		for (const tag of state.tags ?? []) tags.add(tag);
+		collectDeclaredStateTags(state.states, tags);
+	}
+	return tags;
+}
+function resolveIdlePredicate(config, options) {
+	if (options.isIdle) return options.isIdle;
+	const idleTags = config.idleTags ?? [];
+	if (!idleTags.length) return;
+	const declaredTags = collectDeclaredStateTags(config.states);
+	const unknown = idleTags.filter((tag) => !declaredTags.has(tag));
+	if (unknown.length) throw new Error(`setupAgent.fromConfig: 'idleTags' lists ${unknown.map((tag) => `'${tag}'`).join(", ")}, which no state declares in its 'tags'. Tag the waiting state(s) — e.g. "tags": ["${unknown[0]}"] — or remove the entry.`);
+	return (snapshot) => idleTags.some((tag) => snapshot.hasTag(tag));
+}
+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));
+	const actors = createAgentActors(createActorPlaceholdersFromWorkflowConfig(config), requestActors);
+	const translation = {
+		guards: options.guards ?? {},
+		actions: options.actions ?? {},
+		syntheticGuards: {},
+		transitionTargets: {}
+	};
+	const machine = createMachineFromConfig(translateWorkflowConfig(config, translation), {
+		guards: Object.fromEntries(Object.entries({
+			...translation.guards,
+			...translation.syntheticGuards
+		}).map(([name, implementation]) => [name, (args) => Boolean(implementation({
+			context: args.context,
+			event: args.event
+		}))])),
+		...options.actions ? { actions: options.actions } : {},
+		actors: Object.fromEntries(Object.keys(actors).map((key) => [key, key])),
+		evaluators: { [AGENT_EXPRESSION_LANG]: createWorkflowConfigEvaluator(schemas.context) }
+	}).provide({ actors });
+	setAgentExecutionOptions(machine, {
+		schemas,
+		actors,
+		models: {}
+	});
+	const isIdle = resolveIdlePredicate(config, options);
+	if (isIdle && machine.config) machineIdlePredicates.set(machine.config, isIdle);
+	return {
+		machine,
+		schemas
+	};
+}
+//#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" }] };
+	}
+} };
+const USAGE_TOKEN_FIELDS = [
+	"inputTokens",
+	"outputTokens",
+	"totalTokens",
+	"reasoningTokens",
+	"cachedInputTokens"
+];
+const USAGE_ATTRIBUTION_FIELDS = [
+	"id",
+	"src",
+	"model",
+	"name"
+];
+const USAGE_KINDS = ["text", "decision"];
+/**
+* Standard Schema for the reserved `'@agent.usage'` payload. Hand-rolled (no
+* validation-library dependency in core) and deliberately permissive about
+* unknown fields, so a newer runtime adding an attribution field cannot fail
+* an older machine's validation.
+*/
+const agentUsageEventSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		const issues = [];
+		if (!value || typeof value !== "object") return { issues: [{ message: "Expected an '@agent.usage' payload object" }] };
+		const event = value;
+		const usage = event.usage;
+		if (!usage || typeof usage !== "object") issues.push({
+			message: "Expected 'usage' to be an object",
+			path: ["usage"]
+		});
+		else for (const field of USAGE_TOKEN_FIELDS) {
+			const token = usage[field];
+			if (token !== void 0 && (typeof token !== "number" || !Number.isFinite(token))) issues.push({
+				message: `Expected a finite number`,
+				path: ["usage", field]
+			});
+		}
+		if (event.kind !== void 0 && !USAGE_KINDS.some((kind) => kind === event.kind)) issues.push({
+			message: `Expected one of ${USAGE_KINDS.join(", ")}`,
+			path: ["kind"]
+		});
+		for (const field of USAGE_ATTRIBUTION_FIELDS) if (event[field] !== void 0 && typeof event[field] !== "string") issues.push({
+			message: "Expected a string",
+			path: [field]
+		});
+		return issues.length > 0 ? { issues } : { value: event };
+	}
+} };
+/**
+* Adds the reserved `'@agent.usage'` schema to an authored event map. A
+* user-declared entry under that key is rejected: the `@agent.*` namespace
+* belongs to the library (same rule as the reserved `agent.*` actor keys), and
+* a custom payload schema would silently disagree with what `runAgent`
+* delivers.
+*/
+function withAgentUsageEventSchema(events) {
+	const declared = events?.[AGENT_USAGE_EVENT_TYPE];
+	if (declared !== void 0 && declared !== agentUsageEventSchema) throw new Error(`setupAgent: event type '${AGENT_USAGE_EVENT_TYPE}' is in the reserved '@agent.' namespace and cannot be declared in 'events' — setupAgent registers it for you with the usage payload schema. Remove it from 'events'; to receive it, declare a transition instead: on: { '${AGENT_USAGE_EVENT_TYPE}': … }.`);
+	const declaredMessages = events?.[AGENT_MESSAGES_EVENT_TYPE];
+	if (declaredMessages !== void 0 && declaredMessages !== agentMessagesEventSchema) throw new Error(`setupAgent: event type '${AGENT_MESSAGES_EVENT_TYPE}' is reserved and cannot be declared in 'events' — setupAgent registers it for you. Add a transition instead: on: { '${AGENT_MESSAGES_EVENT_TYPE}': appendMessages() }.`);
+	return {
+		...events,
+		[AGENT_USAGE_EVENT_TYPE]: agentUsageEventSchema,
+		[AGENT_MESSAGES_EVENT_TYPE]: agentMessagesEventSchema
+	};
+}
+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(withAgentUsageEventSchema(schemas.events)),
+		input: schemas.input,
+		output: schemas.output,
+		meta: schemas.meta,
+		emitted: schemas.emitted
+	};
+}
+/**
+* Schema-first `setup(...)` for agent machines — the standard entry point
+* for authoring a machine (the blueprint) that this library then runs (via
+* {@link runAgent} or the step helpers) against host-supplied model/decision
+* executors. Context, events, machine input, machine output, and
+* state/transition meta are all standard schemas — no `{} as Type` casts —
+* and are retained on `result.schemas` for runtime validation. Also
+* registers the `agent.generateText`/`agent.streamText`/`agent.userInput`/
+* `agent.decide` builtin actors and lowers `requests`/`actors` 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,
+*   actors: { 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) {
+	const schemas = normalizeAgentSchemas(config);
+	const requestActors = createRequestActors(config.requests ?? {});
+	const actors = createAgentActors(config.actors, requestActors);
+	const base = setup({
+		schemas: {
+			context: schemas.context,
+			events: schemas.events,
+			input: schemas.input,
+			output: schemas.output,
+			meta: schemas.meta,
+			...schemas.emitted && Object.keys(schemas.emitted).length > 0 ? { emitted: schemas.emitted } : {}
+		},
+		...config.states ? { states: config.states } : {},
+		actors,
+		actions: config.actions,
+		guards: config.guards,
+		delays: config.delays
+	});
+	const createBaseMachine = base.createMachine.bind(base);
+	const models = config.models ?? {};
+	const machineOptions = {
+		schemas,
+		actors,
+		models
+	};
+	return Object.assign(base, {
+		createMachine(machineConfig) {
+			assertStateSchemaKeysExist(config.states, machineConfig?.states);
+			const machine = createBaseMachine(withRootOutputFromSingleFinal(machineConfig));
+			setAgentExecutionOptions(machine, machineOptions);
+			if (config.isIdle) {
+				const rootConfig = machine.config;
+				if (rootConfig) machineIdlePredicates.set(rootConfig, config.isIdle);
+			}
+			return machine;
+		},
+		schemas,
+		models,
+		requests: requestActors,
+		appendMessages
+	});
+}
+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 = {}));
+/**
+* The schema pack a machine was built with — `setupAgent(...).createMachine`
+* and `setupAgent.fromConfig(...)` both register one, so hosts can read a
+* machine's input/event schemas at runtime without knowing how it was
+* authored. Returns `undefined` for machines not built by either (a plain
+* xstate `createMachine`/`setup` machine).
+*
+* Registration also travels through `machine.provide(...)`: the pack is keyed
+* on the machine's root `config`, which `.provide` shares by reference.
+*/
+function getAgentSchemas(machine) {
+	return getAgentExecutionOptions(machine)?.schemas;
+}
+/** 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,
+		events: normalizeEventSchemas(withAgentUsageEventSchema(config.schemas.events))
+	};
+	const loose = config;
+	return createAgentSchemas({
+		...loose,
+		context: loose.context
+	});
+}
+/**
+* Runtime guard: every key of the `setupAgent({ states })` schema map must
+* name a real state node in the machine config. A typo'd key is otherwise a
+* silent no-op — the narrowing simply never applies — so fail fast at
+* `createMachine` time. Walks nested `states` maps in parallel with the
+* machine config, since narrowing entries nest the same way.
+*/
+function assertStateSchemaKeysExist(stateSchemas, machineStates, path = []) {
+	if (!stateSchemas) return;
+	for (const [key, stateSchema] of Object.entries(stateSchemas)) {
+		const machineState = machineStates?.[key];
+		if (!machineState || typeof machineState !== "object") {
+			const validKeys = Object.keys(machineStates ?? {});
+			const parent = path.length > 0 ? ` of state '${path.join(".")}'` : "";
+			throw new Error(`setupAgent: 'states' key '${[...path, key].join(".")}' does not name a state in the machine config, so its state schema would silently never apply. Valid child states${parent}: ${validKeys.join(", ") || "(none)"}. Fix the key to match a state in createMachine({ states }), or remove it from setupAgent({ states }).`);
+		}
+		if (stateSchema && typeof stateSchema === "object" && "states" in stateSchema && stateSchema.states) assertStateSchemaKeysExist(stateSchema.states, machineState.states, [...path, key]);
+	}
+}
+const RESERVED_AGENT_ACTOR_KEYS = [
+	...Object.keys(builtinTextActors),
+	USER_INPUT_ACTOR,
+	DECIDE_ACTOR
+];
+/**
+* The whole `agent.` actor-source namespace is reserved for the library, not
+* just the shipped builtins: a key starting with this prefix is rejected at
+* setup time so a future builtin can never collide with (or be shadowed by) a
+* user source. Name your own sources without it.
+*/
+const RESERVED_AGENT_KEY_PREFIX = "agent.";
+/**
+* Runtime guards over the user-supplied `actors`/`requests` keys, in one walk
+* of both groups:
+*
+* 1. A key in the reserved `agent.` namespace is rejected — every key with
+*    that prefix, not only today's builtins. Without this, the builtins-first
+*    spread in {@link createAgentActors} lets such a key overwrite the builtin
+*    (`agent.decide`, …) silently, and a builtin added later would start
+*    colliding with user code. Deliberate override of a builtin is still
+*    possible after the machine is created, via
+*    `machine.provide({ actors: { 'agent.decide': ... } })`.
+* 2. A key appearing in BOTH groups 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 assertActorKeys(actors, requests) {
+	const seenIn = /* @__PURE__ */ new Map();
+	const groups = [["actors", actors], ["requests", requests]];
+	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) {
+		if (RESERVED_AGENT_ACTOR_KEYS.some((reserved) => reserved === 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({ actors: { '${key}': ... } }).`);
+		if (key.startsWith(RESERVED_AGENT_KEY_PREFIX)) throw new Error(`setupAgent: '${groupName}' key '${key}' uses the reserved '${RESERVED_AGENT_KEY_PREFIX}' namespace, which belongs to the library (${RESERVED_AGENT_ACTOR_KEYS.join(", ")}, and anything added later). Rename it without the '${RESERVED_AGENT_KEY_PREFIX}' prefix.`);
+		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 'actors' and 'requests'.`);
+		seenIn.set(key, groupName);
+	}
+}
+function createAgentActors(actors, requestActors) {
+	assertActorKeys(actors, requestActors);
+	return {
+		...builtinTextActors,
+		[USER_INPUT_ACTOR]: userInputActor,
+		[DECIDE_ACTOR]: createDecideActor(),
+		...actors,
+		...requestActors
+	};
+}
+//#endregion
+export { AGENT_USAGE_EVENT_TYPE as i, getAgentSchemas as n, setupAgent as r, createAgentSchemas as t };