@statelyai/agent 2.0.0-alpha.28 → 2.0.0-alpha.30

package/dist/index.mjs

@@ -1,30 +1,30 @@
-import { A as getMessageText, B as AgentTruncatedError, D as getJsonSchema, F as systemMessage, I as toolMessage, L as userMessage, M as getStatePath, N as isStandardSchema, O as getJsonSchemaSync, a as bindRequestExecutor, c as getAgentOutputMode, d as isTextLogic, h as providerOutputSchema, j as getStateMeta, k as getMachineStructuralHash, l as getCallFinishReason, m as parseProviderOutput, p as parseOutput, s as createTextLogic, u as getCallUsage, v as executorBoundLogics, w as assistantMessage, y as getAgentExecutionOptions, z as AgentError } from "./text-logic-CIqHAmBi.mjs";
-import { a as isDecisionLogic, c as AgentInvalidEventPayloadError, i as createDecisionRequest, l as getAcceptedEvents, o as renderDecisionAttempts, r as createDecisionLogic, s as resolveDecision, t as AgentDecisionExhaustedError, u as parseAgentEvent } from "./decision-RQ0iv0oZ.mjs";
-import { t as AGENT_USAGE_EVENT_TYPE } from "./usage-BdEjFuIi.mjs";
-import { n as getAgentSchemas, r as setupAgent, t as createAgentSchemas } from "./setup-agent-BuanDXeh.mjs";
-import { o as AgentMachineVersionMismatchError, t as AgentEventLogConflictError } from "./event-log-store-2pAFiWuc.mjs";
-import { a as bindDecisionForProvide, c as getConfiguredInvokeSrcs, d as isStateMachineLogic, f as runToQuiescence, i as bindChildMachineForProvide, l as inspectTransitions, m as traceTransitions, n as AgentMaxModelCallsExceededError, o as bindTextForProvide, p as serializeTraceEvent, r as AgentSnapshotDivergedError, s as createAgentRuntime, t as AGENT_TRACE_SCHEMA_VERSION, u as isAgentIdle } from "./run-agent-xNTxpt82.mjs";
+import { $ as getStateMeta, A as createTextLogic, C as AGENT_USAGE_EVENT_TYPE, H as getAgentExecutionOptions, I as parseOutput, L as parseProviderOutput, M as getCallFinishReason, N as getCallUsage, O as bindRequestExecutor, P as isTextLogic, Q as getMessageText, R as providerOutputSchema, V as executorBoundLogics, X as getJsonSchemaSync, Y as getJsonSchema, Z as getMachineStructuralHash, at as userMessage, ct as AgentTruncatedError, et as getStatePath, i as AgentMachineVersionMismatchError, it as toolMessage, j as getAgentOutputMode, q as assistantMessage, rt as systemMessage, st as AgentError, tt as isStandardSchema, u as canonicalEventJson } from "./event-log-DJCMHek_.mjs";
+import { a as createDecisionRequest, c as renderDecisionAttempts, d as getAcceptedEvents, f as isEventPattern, i as createDecisionLogic, l as resolveDecision, m as isRecord, p as parseAgentEvent, s as isDecisionLogic, t as AgentDecisionExhaustedError, u as AgentInvalidEventPayloadError } from "./decision-BHkvuImD.mjs";
+import { n as getAgentSchemas, r as setupAgent, t as createAgentSchemas } from "./setup-agent-7rV_cujV.mjs";
+import { t as AgentEventLogConflictError } from "./event-log-store-DsP6GCRh.mjs";
+import { a as bindDecisionForProvide, c as getConfiguredInvokeSrcs, d as isStateMachineLogic, f as runAgent, h as traceTransitions, i as bindChildMachineForProvide, l as inspectTransitions, m as serializeTraceEvent, n as AgentMaxModelCallsExceededError, o as bindTextForProvide, p as runToQuiescence, r as AgentSnapshotDivergedError, s as createAgentRuntime, t as AGENT_TRACE_SCHEMA_VERSION, u as isAgentIdle } from "./run-agent-BpHqkaZw.mjs";
+import { getNextTransitions, machineToJSON, transition } from "xstate";
 //#region src/messages.ts
-const KNOWN_PART_TYPES = new Set([
+const KNOWN_PART_TYPES = /* @__PURE__ */ new Set([
 	"text",
 	"image",
 	"file",
 	"tool-call",
 	"tool-result"
 ]);
-const USER_PART_TYPES = new Set([
+const USER_PART_TYPES = /* @__PURE__ */ new Set([
 	"text",
 	"image",
 	"file"
 ]);
-const ASSISTANT_PART_TYPES = new Set([
+const ASSISTANT_PART_TYPES = /* @__PURE__ */ new Set([
 	"text",
 	"file",
 	"tool-call",
 	"tool-result"
 ]);
-const TOOL_PART_TYPES = new Set(["tool-result"]);
-const TOOL_RESULT_CONTENT_PART_TYPES = new Set(["text", "image"]);
+const TOOL_PART_TYPES = /* @__PURE__ */ new Set(["tool-result"]);
+const TOOL_RESULT_CONTENT_PART_TYPES = /* @__PURE__ */ new Set(["text", "image"]);
 function isKnownPart(part) {
 	const type = part && typeof part === "object" ? part.type : void 0;
 	return typeof type === "string" && KNOWN_PART_TYPES.has(type);
@@ -38,7 +38,7 @@ function isMediaData(value) {
 function requireMediaData(part, type, field) {
 	return isMediaData(part[field]) ? void 0 : `${type} part requires "${field}" to be a string, Uint8Array, ArrayBuffer, or URL`;
 }
-const TOOL_RESULT_OUTPUT_TYPES = new Set([
+const TOOL_RESULT_OUTPUT_TYPES = /* @__PURE__ */ new Set([
 	"text",
 	"json",
 	"error-text",
@@ -152,11 +152,22 @@ function validateEventMeta(value, path) {
 	if (event !== void 0 && (!event || typeof event !== "object" || Array.isArray(event))) issues.push(issue("Expected an object of fixed event fields", [...path, "event"]));
 	return issues;
 }
+function validateChoice(value, path) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return [issue("Expected a { label, event } choice", path)];
+	const choice = value;
+	const issues = [];
+	if (typeof choice["label"] !== "string") issues.push(issue("Expected a string", [...path, "label"]));
+	if (choice["style"] !== void 0 && typeof choice["style"] !== "string") issues.push(issue("Expected a string", [...path, "style"]));
+	const event = choice["event"];
+	if (!event || typeof event !== "object" || Array.isArray(event) || typeof event.type !== "string") issues.push(issue("Expected an event object with a string `type`", [...path, "event"]));
+	return issues;
+}
 /**
 * A {@link StandardSchemaV1} for the state metadata {@link getInteraction}
 * reads: an object whose optional `interaction` declares a `label` (a string
 * with `{context.path}` interpolation, or a function of the context), an
-* `events` map of choices, and a `textEvent` for free-text answers. This is
+* `events` map of choices, payload `choices` (an array, or a context path to
+* one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers. This is
 * the default `meta` type `setupAgent` gives a machine; pass it to
 * `createAgentSchemas({ meta: interactionMetaSchema })` only when building a
 * schema pack by hand.
@@ -174,13 +185,27 @@ const interactionMetaSchema = { "~standard": {
 		const label = descriptor["label"];
 		if (label !== void 0 && typeof label !== "string" && typeof label !== "function") issues.push(issue("Expected a string or a (context) => string", ["interaction", "label"]));
 		const events = descriptor["events"];
-		if (events !== void 0) if (!events || typeof events !== "object" || Array.isArray(events)) issues.push(issue("Expected an object keyed by event type", ["interaction", "events"]));
-		else for (const [type, config] of Object.entries(events)) issues.push(...validateEventMeta(config, [
-			"interaction",
-			"events",
-			type
-		]));
-		if (descriptor["textEvent"] !== void 0 && typeof descriptor["textEvent"] !== "string") issues.push(issue("Expected a string", ["interaction", "textEvent"]));
+		if (events !== void 0) {
+			if (!events || typeof events !== "object" || Array.isArray(events)) issues.push(issue("Expected an object keyed by event type", ["interaction", "events"]));
+			else for (const [type, config] of Object.entries(events)) issues.push(...validateEventMeta(config, [
+				"interaction",
+				"events",
+				type
+			]));
+		}
+		const choices = descriptor["choices"];
+		if (choices !== void 0 && typeof choices !== "string") {
+			if (!Array.isArray(choices)) issues.push(issue("Expected an array of choices or a context path string", ["interaction", "choices"]));
+			else choices.forEach((choice, index) => {
+				issues.push(...validateChoice(choice, [
+					"interaction",
+					"choices",
+					index
+				]));
+			});
+		}
+		const textEvent = descriptor["textEvent"];
+		if (textEvent !== void 0 && typeof textEvent !== "string" && !(textEvent && typeof textEvent === "object" && typeof textEvent.type === "string" && typeof textEvent.field === "string")) issues.push(issue("Expected a string or { type, field }", ["interaction", "textEvent"]));
 		return issues.length > 0 ? { issues } : { value };
 	}
 } };
@@ -197,13 +222,20 @@ function interpolate(label, context, preserveWhitespace) {
 	});
 	return preserveWhitespace ? interpolated : interpolated.replace(/\s+/g, " ").trim();
 }
+function eventSchemasOf(snapshot) {
+	const machine = snapshot.machine;
+	return getAgentExecutionOptions(machine)?.schemas?.events ?? (machine?.schemas)?.events;
+}
+function isChoice(value) {
+	return validateChoice(value, []).length === 0;
+}
 /** Reads the active state's interaction metadata and filters it through the
 * events XState currently accepts. Returns `undefined` when none is declared. */
 function getInteraction(snapshot, options = {}) {
 	const interaction = getStateMeta(snapshot).interaction;
 	if (!interaction) return void 0;
 	const preserveWhitespace = options.preserveWhitespace ?? false;
-	const schemas = getAgentExecutionOptions(snapshot.machine)?.schemas;
+	const eventSchemas = eventSchemasOf(snapshot);
 	const accepted = new Set(getAcceptedEvents(snapshot).map((event) => event.type));
 	const label = typeof interaction.label === "function" ? interaction.label({ context: snapshot.context }) : interaction.label ?? "";
 	const events = Object.entries(interaction.events ?? {}).filter((entry) => entry[1] !== void 0 && accepted.has(entry[0])).map(([type, config]) => {
@@ -213,7 +245,7 @@ function getInteraction(snapshot, options = {}) {
 			const complete = parseAgentEvent(snapshot, {
 				...descriptor.event,
 				type
-			}, { schemas });
+			}, { events: eventSchemas });
 			return snapshot.can(complete);
 		} catch {
 			return true;
@@ -226,23 +258,61 @@ function getInteraction(snapshot, options = {}) {
 			...descriptor.event ? { event: descriptor.event } : {}
 		};
 	});
+	const declaresChoices = interaction.choices !== void 0;
+	const declared = typeof interaction.choices === "string" ? readPath(snapshot.context, interaction.choices) : interaction.choices;
+	const choices = (Array.isArray(declared) ? declared : []).filter(isChoice).filter((choice) => {
+		try {
+			const event = parseAgentEvent(snapshot, choice.event, { events: eventSchemas });
+			return snapshot.can(event);
+		} catch {
+			return false;
+		}
+	}).map((choice) => ({
+		label: interpolate(choice.label, snapshot.context, preserveWhitespace),
+		event: choice.event,
+		...choice.style ? { style: choice.style } : {}
+	}));
+	const text = typeof interaction.textEvent === "string" ? {
+		type: interaction.textEvent,
+		field: "text"
+	} : interaction.textEvent;
 	return {
 		label: interpolate(label, snapshot.context, preserveWhitespace),
 		events,
-		...interaction.textEvent && accepted.has(interaction.textEvent) ? { textEvent: interaction.textEvent } : {}
+		...declaresChoices ? { choices } : {},
+		...text && accepted.has(text.type) ? {
+			textEvent: text.type,
+			...text.field !== "text" ? { textField: text.field } : {}
+		} : {}
 	};
 }
-/** Converts a rendered interaction choice back into a schema-validated machine
-* event. Fixed fields declared in metadata are merged before user fields. */
+/**
+* Converts a rendered interaction answer back into a schema-validated machine
+* event:
+*
+* - `{ type, ...fields }` — an `events` choice; fixed fields declared in
+*   metadata win over user fields.
+* - `{ text }` — free text, placed in the `textEvent` field.
+* - `{ choice }` — a payload choice, by its index in `getInteraction(snapshot).choices`
+*   or by its label. A label that several choices share throws; pass the index.
+*/
 function eventFromInteraction(snapshot, choice) {
 	const interaction = getInteraction(snapshot);
 	if (!interaction) throw new AgentInvalidEventPayloadError("(interaction)", "this state renders no interaction, so there is no choice to convert.");
 	let event;
-	if ("text" in choice) {
+	if (!("type" in choice) && "choice" in choice) {
+		const choices = interaction.choices ?? [];
+		const key = choice.choice;
+		const labeled = typeof key === "number" ? [] : choices.flatMap((candidate, index) => candidate.label === key ? [index] : []);
+		if (labeled.length > 1) throw new AgentInvalidEventPayloadError("(choice)", `${labeled.length} choices are labeled ${JSON.stringify(key)} (indexes ${labeled.join(", ")}); pass { choice: <index> } to pick one.`);
+		const picked = typeof key === "number" ? choices[key] : choices[labeled[0] ?? -1];
+		if (!picked) throw new AgentInvalidEventPayloadError("(choice)", `this interaction offers no choice ${JSON.stringify(key)}. Choices: ${choices.map(({ label }) => JSON.stringify(label)).join(", ") || "(none)"}.`);
+		event = { ...picked.event };
+	} else if ("text" in choice) {
 		if (!interaction.textEvent) throw new AgentInvalidEventPayloadError("(text)", `this interaction takes no free text. Choices: ${interaction.events.map(({ type }) => type).join(", ") || "(none)"}.`);
 		event = {
 			type: interaction.textEvent,
-			text: choice.text
+			[interaction.textField ?? "text"]: choice.text
 		};
 	} else {
 		const descriptor = interaction.events.find(({ type }) => type === choice.type);
@@ -253,7 +323,452 @@ function eventFromInteraction(snapshot, choice) {
 			type: choice.type
 		};
 	}
-	return parseAgentEvent(snapshot, event);
+	return parseAgentEvent(snapshot, event, { events: eventSchemasOf(snapshot) });
+}
+//#endregion
+//#region src/describe-machine.ts
+/**
+* A machine, described in plain text for a model to read: the prompt for a
+* model that proposes an improved machine, or extra context for a decider.
+*
+* The text is read from the machine's own definition (`machineToJSON`):
+* for a `setupAgent.fromConfig(...)` machine that is the lowered JSON config,
+* so every target, guard and context patch is data; for a TS-authored machine,
+* transitions written as functions are read from their source.
+*
+* @module
+*/
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const toList = (value) => value === void 0 ? [] : Array.isArray(value) ? value : [value];
+const oneLine = (text) => text.replace(/\s+/g, " ").trim();
+/** The source of a function as serialized (`{ "@code" }`) or as a live function. */
+function codeOf(value) {
+	if (typeof value === "function") return String(value);
+	if (isObject(value) && typeof value["@code"] === "string") return value["@code"];
+}
+/** The decoded value of a fromConfig `{ "@expr": "<json>" }` slot, or the value itself. */
+function decodeExpr(value) {
+	if (isObject(value) && typeof value["@expr"] === "string") try {
+		return JSON.parse(value["@expr"]);
+	} catch {
+		return value["@expr"];
+	}
+	return value;
+}
+/** A target as written, resolved from the state the transition leaves: `#id`, `.child`, or a sibling (`sibling.child`). */
+function resolveTarget(source, target) {
+	if (target.startsWith("#")) try {
+		return source.machine.getStateNodeById(target.slice(1));
+	} catch {
+		return;
+	}
+	const [from, path] = target.startsWith(".") ? [source, target.slice(1)] : [source.parent ?? source, target];
+	let node = from;
+	for (const key of path.split(".")) node = node?.states[key];
+	return node;
+}
+/** A target as said from where the transition starts: a sibling by key, else its path below the machine. */
+const nameOf = (source, target) => target.parent === source.parent ? target.key : target.path.join(".");
+/**
+* The keys of the object literal whose `{` is at `open` in `text`, at its top
+* level: `a`, `b` for `{ a: 1, b, ...c }`, and `…c` for a spread, whose keys
+* cannot be read. Strings, templates and nested brackets are skipped over.
+*/
+function objectKeys(text, open) {
+	const keys = [];
+	let depth = 0;
+	let expectKey = false;
+	for (let i = open; i < text.length; i++) {
+		const c = text[i];
+		if (c === "\"" || c === "'" || c === "`") {
+			const end = text.indexOf(c, i + 1);
+			if (end < 0) break;
+			i = end;
+			continue;
+		}
+		if (c === "{" || c === "(" || c === "[") {
+			depth++;
+			if (depth === 1) expectKey = true;
+			continue;
+		}
+		if (c === "}" || c === ")" || c === "]") {
+			if (--depth === 0) break;
+			continue;
+		}
+		if (depth !== 1) continue;
+		if (c === ",") {
+			expectKey = true;
+			continue;
+		}
+		if (expectKey && !/\s/.test(c)) {
+			expectKey = false;
+			if (text.startsWith("...", i)) {
+				const spread = /^\.\.\.\s*([\w$.]+)(\()?/.exec(text.slice(i));
+				keys.push(`…${spread?.[1] ?? ""}${spread?.[2] ? "()" : ""}`);
+				continue;
+			}
+			const key = /^[A-Za-z_$][\w$]*/.exec(text.slice(i))?.[0];
+			if (key) {
+				keys.push(key);
+				i += key.length - 1;
+			}
+		}
+	}
+	return keys;
+}
+/** Every key of each object literal that follows a match of `at` in `code`; `…name` when what follows is not a literal. */
+function keysInSource(code, at, keys) {
+	for (const match of code.matchAll(at)) {
+		const open = match.index + match[0].length - 1;
+		if (code[open] === "{") for (const key of objectKeys(code, open)) keys.add(key);
+		else {
+			const from = /^[\w$.]+(\()?/.exec(code.slice(open));
+			keys.add(from ? `…${from[0]}${from[1] ? ")" : ""}` : "…");
+		}
+	}
+}
+/** What a transition sets in context: a declarative patch's keys, or each `context: { … }` in a function's source. */
+function contextKeys(transition, code) {
+	const keys = /* @__PURE__ */ new Set();
+	if (code) keysInSource(code, /\bcontext\s*:\s*[^\s]/g, keys);
+	if (transition) {
+		const context = decodeExpr(transition.context);
+		const contextCode = codeOf(context);
+		if (contextCode) keysInSource(contextCode, /=>\s*\(\s*\{|\breturn\s*\{/g, keys);
+		else if (isObject(context)) for (const key of Object.keys(context)) keys.add(key);
+		for (const action of toList(transition.actions)) if (isObject(action) && action.type === "@xstate.assign") {
+			const assigned = decodeExpr(action.context);
+			if (isObject(assigned)) for (const key of Object.keys(assigned)) keys.add(key);
+		}
+	}
+	return [...keys];
+}
+/** A guard as said in the text: a template's dotted path, a named guard, or `guarded` when it is code. */
+function guardText(guard) {
+	if (guard === void 0 || guard === null) return void 0;
+	const decoded = decodeExpr(guard);
+	if (typeof decoded === "string") return oneLine(/^\{\{\s*([\s\S]*?)\s*\}\}$/.exec(decoded)?.[1] ?? decoded);
+	if (isObject(decoded) && typeof decoded.type === "string") return decoded.type.startsWith("__fromConfigGuard") ? "guarded" : decoded.type;
+	return "guarded";
+}
+/**
+* True when a transition function's source has a path that returns no
+* transition, so it may not be taken. Matches minified source too: `void 0`
+* for `undefined`, and a ternary `?` with no spaces (but not `?.` or `??`).
+* String and template literals are blanked first, so their text never counts.
+*/
+const mayDecline = (code) => /\bundefined\b|\bnull\b|\bvoid 0\b|\breturn\s*;|\bif\s*\(|(?<!\?)\?(?![.?])|&&/.test(code.replace(/(["'`])(?:\\.|(?!\1)[^\\])*\1/g, "\"\""));
+/**
+* Where a transition written as a function goes: every string literal after a
+* `target:` that names a real state node, `(conditional)` when it may decline
+* or pick among several, `(stays)` when its source has no `target`, `?` when
+* it names none that resolves.
+*/
+function targetsInSource(source, code, choice) {
+	const found = /* @__PURE__ */ new Set();
+	for (const [, expression] of code.matchAll(/\btarget\s*:\s*(\[[^\]]*\]|[^,}\n]+)/g)) for (const [, , literal] of expression.matchAll(/(['"`])([^'"`$]+)\1/g)) {
+		const node = resolveTarget(source, literal);
+		if (node) found.add(node);
+	}
+	const names = [...found].map((node) => nameOf(source, node));
+	if (names.length) {
+		const conditional = names.length > 1 || !choice && mayDecline(code);
+		return `${names.join(", ")}${conditional ? " (conditional)" : ""}`;
+	}
+	return /\btarget\s*:/.test(code) ? "?" : "(stays)";
+}
+/** One transition, as a line: `on GO if context.ready → review; sets draft — description`. */
+function transitionLine(source, head, transition, options = {}) {
+	const code = codeOf(transition);
+	let to;
+	let guard;
+	let description;
+	let sets;
+	if (typeof transition === "string") {
+		const node = resolveTarget(source, transition);
+		to = node ? nameOf(source, node) : `${transition} ?`;
+		sets = [];
+	} else if (code !== void 0) {
+		to = targetsInSource(source, code, options.choice ?? false);
+		sets = contextKeys(void 0, code);
+	} else if (isObject(transition) && !("@expr" in transition)) {
+		const targets = toList(transition.target).filter((t) => typeof t === "string");
+		to = targets.length ? targets.map((target) => {
+			const node = resolveTarget(source, target);
+			return node ? nameOf(source, node) : `${target} ?`;
+		}).join(", ") : "(stays)";
+		guard = guardText(transition[options.guardKey ?? "guard"]);
+		description = typeof transition.description === "string" ? transition.description : void 0;
+		sets = contextKeys(transition, void 0);
+	} else {
+		to = "?";
+		sets = [];
+	}
+	return `${head}${guard ? ` if ${guard}` : ""} → ${to}${sets.length ? `; sets ${sets.join(", ")}` : ""}${description ? ` — ${oneLine(description)}` : ""}`;
+}
+function formatMs(ms) {
+	if (ms < 1e3) return `${ms}ms`;
+	return `${ms / 1e3}s`;
+}
+/** An `after` key as said: `1s`, or a named delay with its duration when it is a number (`slow (5s)`). */
+function delayText(key, delays) {
+	if (/^\d+(\.\d+)?$/.test(key)) return formatMs(Number(key));
+	const delay = delays[key];
+	return typeof delay === "number" ? `${key} (${formatMs(delay)})` : key;
+}
+/** Every transition leaving one state node, as lines at `pad`. */
+function transitionLines(node, json, delays, pad) {
+	const lines = [];
+	const push = (head, value) => {
+		for (const transition of toList(value)) lines.push(`${pad}${transitionLine(node, head, transition)}`);
+	};
+	for (const [event, value] of Object.entries(isObject(json.on) ? json.on : {})) push(event === "xstate.done.state" ? "onDone" : `on ${event}`, value);
+	push("onDone", json.onDone);
+	push("always", json.always);
+	for (const [key, value] of Object.entries(isObject(json.after) ? json.after : {})) push(`after ${delayText(key, delays)}`, value);
+	for (const invoke of toList(json.invoke)) {
+		if (!isObject(invoke)) continue;
+		const src = typeof invoke.src === "string" ? invoke.src : "(inline)";
+		const id = typeof invoke.id === "string" && invoke.id !== src ? ` (${invoke.id})` : "";
+		lines.push(`${pad}invoke ${src}${id}`);
+		push("  done", invoke.onDone);
+		push("  error", invoke.onError);
+	}
+	if (json.choice !== void 0) toList(json.choice).forEach((branch, index) => {
+		const head = isObject(branch) && branch.when !== void 0 || index === 0 ? "choice" : "choice else";
+		lines.push(`${pad}${transitionLine(node, head, branch, {
+			guardKey: "when",
+			choice: true
+		})}`);
+	});
+	return lines;
+}
+/** The state node's line: key, type, tags, interaction label, description. */
+function stateLine(node, json) {
+	let marker = "";
+	if (node.type === "final" || node.type === "choice" || node.type === "parallel") marker = ` (${node.type})`;
+	else if (node.type === "history") marker = json.history === "deep" ? " (history, deep)" : " (history)";
+	else if (node.type === "compound" && typeof json.initial === "string") marker = ` (initial: ${json.initial})`;
+	const tags = node.tags.length ? ` [tags: ${node.tags.join(", ")}]` : "";
+	const interaction = node.meta?.interaction;
+	const label = typeof interaction?.label === "string" ? ` [interaction: "${oneLine(interaction.label)}"]` : "";
+	const description = node.description ? ` — ${oneLine(node.description)}` : "";
+	return `${node.key}${marker}${tags}${label}${description}`;
+}
+/** The machine's events with their schema descriptions and fields, sorted by type. */
+function eventLines(machine) {
+	const schemas = getAgentExecutionOptions(machine)?.schemas?.events ?? machine.schemas?.events ?? {};
+	const lines = [];
+	for (const type of Object.keys(schemas).sort()) {
+		if (type.startsWith("@agent.") || type.startsWith("xstate.")) continue;
+		let schema;
+		try {
+			schema = getJsonSchemaSync(schemas[type]);
+		} catch {
+			schema = void 0;
+		}
+		const direct = schemas[type].description;
+		const description = typeof schema?.description === "string" ? schema.description : typeof direct === "string" ? direct : void 0;
+		lines.push(`  ${type}${description ? ` — ${oneLine(description)}` : ""}`);
+		const properties = isObject(schema?.properties) ? schema.properties : {};
+		const required = new Set(Array.isArray(schema?.required) ? schema.required : []);
+		for (const [field, property] of Object.entries(properties)) {
+			if (!isObject(property)) continue;
+			const fieldType = Array.isArray(property.enum) ? property.enum.map((value) => JSON.stringify(value)).join(" | ") : Array.isArray(property.type) ? property.type.join(" | ") : typeof property.type === "string" ? property.type : void 0;
+			const fieldDescription = typeof property.description === "string" ? ` — ${oneLine(property.description)}` : "";
+			lines.push(`    ${field}${required.has(field) ? "" : "?"}${fieldType ? `: ${fieldType}` : ""}${fieldDescription}`);
+		}
+	}
+	return lines;
+}
+/**
+* Describes a machine in plain text for a model to read. The machine's
+* `description` is its goal, so it leads: `Machine <id>`, then `Goal: …`.
+* Then every state node, indented by depth, with its type, tags, interaction
+* label and description (`*` marks the active ones when `snapshot` is given),
+* and under it every transition leaving it, one per line: `on EVENT`,
+* `always`, `after <delay>`, invoke `done`/`error`, and `choice` branches,
+* each with its guard (`if …`), where it goes (`→ review`), and what it sets
+* in context (`sets draft, attempts`). An `Events` section lists the
+* machine's event schemas with their descriptions and fields.
+*
+* A transition written as a function shows the targets its source names
+* (`→ review (conditional)` when it may decline or pick among several),
+* `(stays)` when its source has no `target`, or `→ ?` when no target can be
+* read. A `setupAgent.fromConfig(...)` machine is read from its config, so
+* its targets, guards and context patches are always known.
+*
+* @example
+* ```ts
+* const prompt = `Propose a better machine for this goal.\n\n${describeMachine(machine)}`;
+* ```
+*/
+function describeMachine(machine, options = {}) {
+	const json = machineToJSON(machine);
+	const delays = isObject(json.delays) ? json.delays : {};
+	const active = new Set(options.snapshot?.nodes.map((node) => node.id) ?? []);
+	const root = machine.root;
+	const lines = [`Machine ${machine.id}`];
+	if (root.description) lines.push(`Goal: ${root.description.trim()}`);
+	const rootTransitions = transitionLines(root, json, delays, "  ");
+	if (rootTransitions.length) lines.push("Any state:", ...rootTransitions);
+	const initial = typeof json.initial === "string" ? ` (initial: ${json.initial})` : "";
+	lines.push(`States${initial}${options.snapshot ? " (* = current)" : ""}:`);
+	const walk = (node, nodeJson, depth) => {
+		const pad = "  ".repeat(depth);
+		const mark = active.has(node.id) ? `${pad.slice(2)}* ` : pad;
+		lines.push(`${mark}${stateLine(node, nodeJson)}`);
+		lines.push(...transitionLines(node, nodeJson, delays, `${pad}    `));
+		const childJson = isObject(nodeJson.states) ? nodeJson.states : {};
+		for (const [key, child] of Object.entries(node.states)) walk(child, isObject(childJson[key]) ? childJson[key] : {}, depth + 1);
+	};
+	const rootStates = isObject(json.states) ? json.states : {};
+	for (const [key, child] of Object.entries(root.states)) walk(child, isObject(rootStates[key]) ? rootStates[key] : {}, 1);
+	const events = eventLines(machine);
+	if (events.length) lines.push("Events:", ...events);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/decide-next.ts
+/**
+* Asks a model to choose the next event for ANY XState snapshot, including a
+* machine built with plain `createMachine`/`setup` that knows nothing about AI.
+* The candidates are the `allowedEvents` an active state handles, one option per
+* payload, kept only where `snapshot.can(event)` is true; the rest come back as
+* `withheld`. Each option is
+* described from the transition's `description`, else the event schema's,
+* plus (with `lookahead`) what it changes. The chosen event must equal one
+* offered option; anything else is retried.
+*
+* It never sends. The host sends the event, re-checking `can` first, because
+* the actor may have moved while the model was thinking. With no options it
+* returns `{ event: null }` without calling the executor. Exhausting retries
+* throws `AgentDecisionExhaustedError`.
+*
+* @example
+* ```ts no-check
+* let busy = false;
+* actor.subscribe(async (snapshot) => {
+*   if (busy || !snapshot.matches('reviewing')) return;
+*   busy = true;
+*   try {
+*     const { event } = await decideNext(snapshot, {
+*       decide,
+*       model: 'quick',
+*       allowedEvents: 'desk.*',
+*       payloads: (s) => ({ 'desk.refund': [{ amount: s.context.requested }] }),
+*       lookahead: true,
+*     });
+*     if (event && actor.getSnapshot().can(event)) actor.send(event);
+*   } finally {
+*     busy = false;
+*   }
+* });
+* ```
+*/
+async function decideNext(snapshot, options) {
+	const patterns = typeof options.allowedEvents === "string" ? [options.allowedEvents] : options.allowedEvents;
+	const schemas = snapshot.machine.schemas?.events;
+	const events = getAcceptedEvents(snapshot, {
+		events: schemas,
+		eventTypes: patterns
+	}).filter((event) => !isEventPattern(event.type));
+	const payloads = options.payloads?.(snapshot) ?? {};
+	const accepted = [];
+	const withheld = [];
+	for (const { type } of events) for (const payload of payloads[type] ?? [{}]) {
+		const event = {
+			...payload,
+			type
+		};
+		(safeCan(snapshot, event) ? accepted : withheld).push(event);
+	}
+	const offered = accepted.map((event) => ({
+		event,
+		description: describeOption(snapshot, event, schemas?.[event.type], options.lookahead)
+	}));
+	const request = createDecisionRequest({
+		name: options.name ?? "decideNext",
+		model: options.model,
+		system: options.system,
+		prompt: options.prompt,
+		input: {
+			value: snapshot.value,
+			context: snapshot.context
+		},
+		events,
+		options: offered,
+		withheld
+	});
+	if (offered.length === 0) return {
+		event: null,
+		attempts: [],
+		request,
+		withheld
+	};
+	let attempts = [];
+	return {
+		event: await resolveDecision(request, { decide: (attemptRequest, info) => {
+			attempts = attemptRequest.attempts;
+			return options.decide(attemptRequest, info);
+		} }, {
+			maxRetries: options.maxRetries,
+			signal: options.signal,
+			canTake: (chosen) => safeCan(snapshot, chosen)
+		}),
+		attempts,
+		request,
+		withheld
+	};
+}
+function safeCan(snapshot, event) {
+	try {
+		return snapshot.can(event);
+	} catch {
+		return false;
+	}
+}
+function describeOption(snapshot, event, schema, lookahead) {
+	const what = getNextTransitions(snapshot).find((candidate) => candidate.eventType === event.type && candidate.description)?.description ?? schemaDescription(schema) ?? event.type;
+	const fields = Object.entries(event).filter(([key]) => key !== "type").map(([key, value]) => `${key}: ${short(value)}`);
+	const base = fields.length ? `${what} (${fields.join("; ")})` : what;
+	const effect = lookahead ? describeEffect(snapshot, event, lookahead === true ? void 0 : lookahead) : void 0;
+	return effect ? `${base}. Then: ${effect}` : base;
+}
+function schemaDescription(schema) {
+	if (!schema) return void 0;
+	const direct = schema.description;
+	if (typeof direct === "string") return direct;
+	try {
+		const json = schema["~standard"].jsonSchema?.input?.({ target: "draft-2020-12" });
+		return isRecord(json) && typeof json.description === "string" ? json.description : void 0;
+	} catch {
+		return;
+	}
+}
+function describeEffect(snapshot, event, keys) {
+	const maxLength = 120;
+	let next;
+	try {
+		[next] = transition(snapshot.machine, snapshot, event);
+	} catch {
+		return;
+	}
+	const changes = [];
+	if (canonicalEventJson(snapshot.value) !== canonicalEventJson(next.value)) changes.push(`state: ${short(snapshot.value, maxLength)} → ${short(next.value, maxLength)}`);
+	const before = isRecord(snapshot.context) ? snapshot.context : {};
+	const after = isRecord(next.context) ? next.context : {};
+	for (const key of keys ?? /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])) if (canonicalEventJson(before[key]) !== canonicalEventJson(after[key])) changes.push(`${key}: ${short(before[key], maxLength)} → ${short(after[key], maxLength)}`);
+	return changes.length ? changes.join("; ") : "nothing changes";
+}
+function short(value, max = 60) {
+	let text;
+	try {
+		text = value === void 0 ? "(none)" : JSON.stringify(value) ?? String(value);
+	} catch {
+		text = String(value);
+	}
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
 }
 //#endregion
 //#region src/provide-executors.ts
@@ -309,8 +824,8 @@ function provideExecutors(machine, executors, options = {}) {
 	const invokedSrcs = getConfiguredInvokeSrcs(provided);
 	for (const [key, logic] of Object.entries(effectiveSources)) {
 		if (isStateMachineLogic(logic)) {
-			if (invokedSrcs.has(key)) assertChildBindable(logic, executors, key, new Set([provided]));
-			const rebound = bindChildMachineForProvide(logic, executors, bindOptions, new Set([provided]));
+			if (invokedSrcs.has(key)) assertChildBindable(logic, executors, key, /* @__PURE__ */ new Set([provided]));
+			const rebound = bindChildMachineForProvide(logic, executors, bindOptions, /* @__PURE__ */ new Set([provided]));
 			if (rebound !== logic) wrappedSources[key] = rebound;
 			continue;
 		}
@@ -351,7 +866,7 @@ function executorRequirementOf(logic) {
 */
 function assertChildBindable(childMachine, executors, path, visited) {
 	if (visited.has(childMachine)) return;
-	const nextVisited = new Set([...visited, childMachine]);
+	const nextVisited = /* @__PURE__ */ new Set([...visited, childMachine]);
 	const sources = childMachine.sources.actors;
 	for (const src of getConfiguredInvokeSrcs(childMachine)) {
 		const logic = sources[src];
@@ -369,4 +884,4 @@ 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
-export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentInvalidEventPayloadError, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, AgentSnapshotDivergedError, AgentTruncatedError, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isAgentMessages, isStandardSchema, messagesSchema, parseAgentEvent, parseOutput, parseProviderOutput, provideExecutors, providerOutputSchema, renderDecisionAttempts, resolveDecision, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
+export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentInvalidEventPayloadError, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, AgentSnapshotDivergedError, AgentTruncatedError, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, decideNext, describeMachine, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isAgentMessages, isStandardSchema, messagesSchema, parseAgentEvent, parseOutput, parseProviderOutput, provideExecutors, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };