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

package/dist/index.cjs

@@ -1,31 +1,31 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_text_logic = require("./text-logic-f5F5sCdc.cjs");
-const require_decision = require("./decision-CmM8-HHz.cjs");
-const require_usage = require("./usage-efOQPdf_.cjs");
-const require_setup_agent = require("./setup-agent-DV4cTou-.cjs");
-const require_event_log_store = require("./event-log-store-C-COhIXP.cjs");
-const require_run_agent = require("./run-agent-Dmf8GV2d.cjs");
+const require_event_log = require("./event-log-Dtb16p1p.cjs");
+const require_decision = require("./decision-oevZnkBe.cjs");
+const require_setup_agent = require("./setup-agent-DTF3NQg3.cjs");
+const require_event_log_store = require("./event-log-store-bCdskPNS.cjs");
+const require_run_agent = require("./run-agent-cToZ3K42.cjs");
+let xstate = require("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);
@@ -39,7 +39,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",
@@ -153,11 +153,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.
@@ -175,13 +186,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 };
 	}
 } };
@@ -198,13 +223,20 @@ function interpolate(label, context, preserveWhitespace) {
 	});
 	return preserveWhitespace ? interpolated : interpolated.replace(/\s+/g, " ").trim();
 }
+function eventSchemasOf(snapshot) {
+	const machine = snapshot.machine;
+	return require_event_log.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 = require_text_logic.getStateMeta(snapshot).interaction;
+	const interaction = require_event_log.getStateMeta(snapshot).interaction;
 	if (!interaction) return void 0;
 	const preserveWhitespace = options.preserveWhitespace ?? false;
-	const schemas = require_text_logic.getAgentExecutionOptions(snapshot.machine)?.schemas;
+	const eventSchemas = eventSchemasOf(snapshot);
 	const accepted = new Set(require_decision.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]) => {
@@ -214,7 +246,7 @@ function getInteraction(snapshot, options = {}) {
 			const complete = require_decision.parseAgentEvent(snapshot, {
 				...descriptor.event,
 				type
-			}, { schemas });
+			}, { events: eventSchemas });
 			return snapshot.can(complete);
 		} catch {
 			return true;
@@ -227,23 +259,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 = require_decision.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 require_decision.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 require_decision.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 require_decision.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 require_decision.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);
@@ -254,7 +324,447 @@ function eventFromInteraction(snapshot, choice) {
 			type: choice.type
 		};
 	}
-	return require_decision.parseAgentEvent(snapshot, event);
+	return require_decision.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. */
+const mayDecline = (code) => /\bundefined\b|\bnull\b|\breturn\s*;|\bif\s*\(|\s\?\s|&&/.test(code);
+/**
+* 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 = require_event_log.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 = require_event_log.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 = (0, xstate.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 = require_decision.getAcceptedEvents(snapshot, {
+		events: schemas,
+		eventTypes: patterns
+	}).filter((event) => !require_decision.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 = require_decision.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 require_decision.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 = (0, xstate.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 require_decision.isRecord(json) && typeof json.description === "string" ? json.description : void 0;
+	} catch {
+		return;
+	}
+}
+function describeEffect(snapshot, event, keys) {
+	const maxLength = 120;
+	let next;
+	try {
+		[next] = (0, xstate.transition)(snapshot.machine, snapshot, event);
+	} catch {
+		return;
+	}
+	const changes = [];
+	if (require_event_log.canonicalEventJson(snapshot.value) !== require_event_log.canonicalEventJson(next.value)) changes.push(`state: ${short(snapshot.value, maxLength)} → ${short(next.value, maxLength)}`);
+	const before = require_decision.isRecord(snapshot.context) ? snapshot.context : {};
+	const after = require_decision.isRecord(next.context) ? next.context : {};
+	for (const key of keys ?? /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])) if (require_event_log.canonicalEventJson(before[key]) !== require_event_log.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
@@ -310,8 +820,8 @@ function provideExecutors(machine, executors, options = {}) {
 	const invokedSrcs = require_run_agent.getConfiguredInvokeSrcs(provided);
 	for (const [key, logic] of Object.entries(effectiveSources)) {
 		if (require_run_agent.isStateMachineLogic(logic)) {
-			if (invokedSrcs.has(key)) assertChildBindable(logic, executors, key, new Set([provided]));
-			const rebound = require_run_agent.bindChildMachineForProvide(logic, executors, bindOptions, new Set([provided]));
+			if (invokedSrcs.has(key)) assertChildBindable(logic, executors, key, /* @__PURE__ */ new Set([provided]));
+			const rebound = require_run_agent.bindChildMachineForProvide(logic, executors, bindOptions, /* @__PURE__ */ new Set([provided]));
 			if (rebound !== logic) wrappedSources[key] = rebound;
 			continue;
 		}
@@ -321,7 +831,7 @@ function provideExecutors(machine, executors, options = {}) {
 			...requirement,
 			bind: () => require_decision.isDecisionLogic(logic) ? require_run_agent.bindDecisionForProvide(provided, logic, executors, bindOptions) : require_run_agent.bindTextForProvide(provided, logic, executors, bindOptions)
 		};
-		if (require_text_logic.executorBoundLogics.has(logic)) continue;
+		if (require_event_log.executorBoundLogics.has(logic)) continue;
 		if (!executors[binding.executorKey]) {
 			if (invokedSrcs.has(key)) throw missingExecutorError(key, binding.kind, binding.executorKey);
 			continue;
@@ -336,7 +846,7 @@ function executorRequirementOf(logic) {
 		executorKey: "decide",
 		kind: "decision"
 	};
-	if (require_text_logic.isTextLogic(logic)) return logic.mode === "stream" ? {
+	if (require_event_log.isTextLogic(logic)) return logic.mode === "stream" ? {
 		executorKey: "streamText",
 		kind: "streaming text"
 	} : {
@@ -352,7 +862,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 require_run_agent.getConfiguredInvokeSrcs(childMachine)) {
 		const logic = sources[src];
@@ -362,7 +872,7 @@ function assertChildBindable(childMachine, executors, path, visited) {
 			continue;
 		}
 		const requirement = executorRequirementOf(logic);
-		if (!requirement || require_text_logic.executorBoundLogics.has(logic)) continue;
+		if (!requirement || require_event_log.executorBoundLogics.has(logic)) continue;
 		if (!executors[requirement.executorKey]) throw missingExecutorError(`${path} > ${src}`, requirement.kind, requirement.executorKey);
 	}
 }
@@ -371,48 +881,51 @@ function missingExecutorError(src, kind, executor) {
 }
 //#endregion
 exports.AGENT_TRACE_SCHEMA_VERSION = require_run_agent.AGENT_TRACE_SCHEMA_VERSION;
-exports.AGENT_USAGE_EVENT_TYPE = require_usage.AGENT_USAGE_EVENT_TYPE;
+exports.AGENT_USAGE_EVENT_TYPE = require_event_log.AGENT_USAGE_EVENT_TYPE;
 exports.AgentDecisionExhaustedError = require_decision.AgentDecisionExhaustedError;
-exports.AgentError = require_text_logic.AgentError;
+exports.AgentError = require_event_log.AgentError;
 exports.AgentEventLogConflictError = require_event_log_store.AgentEventLogConflictError;
 exports.AgentInvalidEventPayloadError = require_decision.AgentInvalidEventPayloadError;
-exports.AgentMachineVersionMismatchError = require_event_log_store.AgentMachineVersionMismatchError;
+exports.AgentMachineVersionMismatchError = require_event_log.AgentMachineVersionMismatchError;
 exports.AgentMaxModelCallsExceededError = require_run_agent.AgentMaxModelCallsExceededError;
 exports.AgentSnapshotDivergedError = require_run_agent.AgentSnapshotDivergedError;
-exports.AgentTruncatedError = require_text_logic.AgentTruncatedError;
-exports.assistantMessage = require_text_logic.assistantMessage;
-exports.bindRequestExecutor = require_text_logic.bindRequestExecutor;
+exports.AgentTruncatedError = require_event_log.AgentTruncatedError;
+exports.assistantMessage = require_event_log.assistantMessage;
+exports.bindRequestExecutor = require_event_log.bindRequestExecutor;
 exports.createAgentRuntime = require_run_agent.createAgentRuntime;
 exports.createAgentSchemas = require_setup_agent.createAgentSchemas;
 exports.createDecisionLogic = require_decision.createDecisionLogic;
 exports.createDecisionRequest = require_decision.createDecisionRequest;
-exports.createTextLogic = require_text_logic.createTextLogic;
+exports.createTextLogic = require_event_log.createTextLogic;
+exports.decideNext = decideNext;
+exports.describeMachine = describeMachine;
 exports.eventFromInteraction = eventFromInteraction;
 exports.getAcceptedEvents = require_decision.getAcceptedEvents;
-exports.getAgentOutputMode = require_text_logic.getAgentOutputMode;
+exports.getAgentOutputMode = require_event_log.getAgentOutputMode;
 exports.getAgentSchemas = require_setup_agent.getAgentSchemas;
-exports.getCallFinishReason = require_text_logic.getCallFinishReason;
-exports.getCallUsage = require_text_logic.getCallUsage;
+exports.getCallFinishReason = require_event_log.getCallFinishReason;
+exports.getCallUsage = require_event_log.getCallUsage;
 exports.getInteraction = getInteraction;
-exports.getJsonSchema = require_text_logic.getJsonSchema;
-exports.getJsonSchemaSync = require_text_logic.getJsonSchemaSync;
-exports.getMachineStructuralHash = require_text_logic.getMachineStructuralHash;
-exports.getMessageText = require_text_logic.getMessageText;
-exports.getStateMeta = require_text_logic.getStateMeta;
-exports.getStatePath = require_text_logic.getStatePath;
+exports.getJsonSchema = require_event_log.getJsonSchema;
+exports.getJsonSchemaSync = require_event_log.getJsonSchemaSync;
+exports.getMachineStructuralHash = require_event_log.getMachineStructuralHash;
+exports.getMessageText = require_event_log.getMessageText;
+exports.getStateMeta = require_event_log.getStateMeta;
+exports.getStatePath = require_event_log.getStatePath;
 exports.inspectTransitions = require_run_agent.inspectTransitions;
 exports.interactionMetaSchema = interactionMetaSchema;
 exports.isAgentIdle = require_run_agent.isAgentIdle;
 exports.isAgentMessages = isAgentMessages;
-exports.isStandardSchema = require_text_logic.isStandardSchema;
+exports.isStandardSchema = require_event_log.isStandardSchema;
 exports.messagesSchema = messagesSchema;
 exports.parseAgentEvent = require_decision.parseAgentEvent;
-exports.parseOutput = require_text_logic.parseOutput;
-exports.parseProviderOutput = require_text_logic.parseProviderOutput;
+exports.parseOutput = require_event_log.parseOutput;
+exports.parseProviderOutput = require_event_log.parseProviderOutput;
 exports.provideExecutors = provideExecutors;
-exports.providerOutputSchema = require_text_logic.providerOutputSchema;
+exports.providerOutputSchema = require_event_log.providerOutputSchema;
 exports.renderDecisionAttempts = require_decision.renderDecisionAttempts;
 exports.resolveDecision = require_decision.resolveDecision;
+exports.runAgent = require_run_agent.runAgent;
 exports.runToQuiescence = require_run_agent.runToQuiescence;
 exports.serializeTraceEvent = require_run_agent.serializeTraceEvent;
 Object.defineProperty(exports, "setupAgent", {
@@ -421,7 +934,7 @@ Object.defineProperty(exports, "setupAgent", {
 		return require_setup_agent.setupAgent;
 	}
 });
-exports.systemMessage = require_text_logic.systemMessage;
-exports.toolMessage = require_text_logic.toolMessage;
+exports.systemMessage = require_event_log.systemMessage;
+exports.toolMessage = require_event_log.toolMessage;
 exports.traceTransitions = require_run_agent.traceTransitions;
-exports.userMessage = require_text_logic.userMessage;
+exports.userMessage = require_event_log.userMessage;