@statelyai/agent 1.1.6 → 2.0.0-alpha.5

package/dist/decision-FTmbqSEe.mjs

@@ -0,0 +1,938 @@
+import { createAsyncLogic, createLogic, getNextTransitions } from "xstate";
+//#region src/utils.ts
+/**
+* Deep-clones a snapshot to a plain-JSON value via a `JSON` round-trip, the
+* shape you persist and later feed back to `runAgent({ snapshot })`. Asserts
+* JSON-serializability: functions, `undefined`, and other non-JSON values are
+* dropped or throw exactly as `JSON.stringify`/`JSON.parse` would. Returns a
+* plain-JSON deep clone, not a live snapshot.
+*/
+function persistSnapshot(snapshot) {
+	return JSON.parse(JSON.stringify(snapshot));
+}
+/**
+* Walks a context value and returns the dot-paths of the first few values that
+* would NOT survive a JSON persist/resume round-trip (see {@link persistSnapshot}):
+* `Date`, `Map`, `Set`, `RegExp`, functions, `undefined`, `bigint`, class
+* instances (non-plain objects), and circular references. Plain objects,
+* arrays, and JSON primitives are walked/allowed. Returns `[]` for a
+* fully-JSON-safe value. Cheap and bounded (stops after `limit` findings) —
+* intended for a dev-only warning at the moment persistence matters.
+*/
+function findNonSerializableContextPaths(context, limit = 5) {
+	const paths = [];
+	const seen = /* @__PURE__ */ new WeakSet();
+	const walk = (value, path) => {
+		if (paths.length >= limit) return;
+		if (value === null) return;
+		const type = typeof value;
+		if (type === "string" || type === "number" || type === "boolean") return;
+		if (type === "undefined" || type === "bigint" || type === "function" || type === "symbol") {
+			paths.push(`${path} (${type})`);
+			return;
+		}
+		const obj = value;
+		if (seen.has(obj)) {
+			paths.push(`${path} (circular)`);
+			return;
+		}
+		if (Array.isArray(value)) {
+			seen.add(obj);
+			value.forEach((item, index) => walk(item, `${path}[${index}]`));
+			seen.delete(obj);
+			return;
+		}
+		const proto = Object.getPrototypeOf(value);
+		if (proto === Object.prototype || proto === null) {
+			seen.add(obj);
+			for (const [key, item] of Object.entries(value)) walk(item, `${path}.${key}`);
+			seen.delete(obj);
+			return;
+		}
+		const ctorName = value.constructor?.name ?? "object";
+		paths.push(`${path} (${ctorName})`);
+	};
+	walk(context, "context");
+	return paths;
+}
+/**
+* A stable, dependency-free structural fingerprint of a machine — a short hex
+* `djb2` hash over its **structural** config only: state ids/nesting, transition
+* event types and targets, invoke `src`s, `initial`, and any other serializable
+* config fields. Function values (context/output builders, prompts, inline
+* guards/actions) are excluded entirely, so two machines that differ only in
+* their prompts or executors hash identically; adding/removing/retargeting a
+* state or transition changes the hash.
+*
+* Used by {@link runAgent} to stamp settled snapshots with a `version` and to
+* detect a structurally-edited machine on resume. It is a change detector, not
+* a cryptographic digest — collisions are possible but unlikely for real
+* configs. Pass an explicit `machineVersion` to `runAgent` to override it.
+*/
+function getMachineStructuralHash(machine) {
+	return djb2Hex(stableStructuralString(machine.config));
+}
+function stableStructuralString(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === null) return "null";
+	const type = typeof value;
+	if (type === "function" || type === "undefined" || type === "symbol") return "";
+	if (type === "string") return JSON.stringify(value);
+	if (type === "number" || type === "boolean") return String(value);
+	if (type === "bigint") return `${value}n`;
+	const obj = value;
+	if (seen.has(obj)) return "\"[circular]\"";
+	seen.add(obj);
+	let out;
+	if (Array.isArray(value)) out = `[${value.map((item) => stableStructuralString(item, seen)).join(",")}]`;
+	else {
+		const parts = [];
+		for (const key of Object.keys(obj).sort()) {
+			const child = obj[key];
+			const childType = typeof child;
+			if (childType === "function" || childType === "undefined" || childType === "symbol") continue;
+			parts.push(`${JSON.stringify(key)}:${stableStructuralString(child, seen)}`);
+		}
+		out = `{${parts.join(",")}}`;
+	}
+	seen.delete(obj);
+	return out;
+}
+function djb2Hex(input) {
+	let hash = 5381;
+	for (let i = 0; i < input.length; i++) hash = (hash << 5) + hash + input.charCodeAt(i) | 0;
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/** Builds a {@link UserMessage} from a string or multimodal content parts. */
+function userMessage(content) {
+	return {
+		role: "user",
+		content
+	};
+}
+/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
+function assistantMessage(content) {
+	return {
+		role: "assistant",
+		content
+	};
+}
+/** Builds a {@link SystemMessage}. */
+function systemMessage(content) {
+	return {
+		role: "system",
+		content
+	};
+}
+/** Builds a {@link ToolMessage} from one or more tool-result parts. */
+function toolMessage(content) {
+	return {
+		role: "tool",
+		content
+	};
+}
+/**
+* Returns the merged `meta` of a snapshot's active state(s) — the typed
+* replacement for the `Object.values(snapshot.getMeta())[0]` dance.
+*
+* `snapshot.getMeta()` is keyed by state id; a leaf machine has one active
+* state, but parallel/nested machines can have several. This shallow-merges
+* every active state's meta into one object (later/deeper entries win) and
+* returns `{}` when no active state declares meta.
+*
+* The return type is recovered from the snapshot's own `getMeta()` type, so a
+* schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
+* output type. Pass an explicit `TMeta` to override when the snapshot is
+* untyped (e.g. `AnyMachineSnapshot`).
+*
+* @example HITL: read the current state's interaction protocol off an idle
+* snapshot to render for a human.
+* ```ts
+* const { interaction } = getStateMeta(result.snapshot);
+* ```
+*/
+function getStateMeta(snapshot) {
+	return Object.assign({}, ...Object.values(snapshot.getMeta()).filter((meta) => meta != null));
+}
+/**
+* Reads the run-owned message log off a snapshot settled by a `runAgent` call
+* that used `getRequests` (or `options.messages`) — the typed replacement for
+* the `(snapshot as { messages?: AgentMessage[] }).messages` cast. runAgent
+* stamps the log as a plain enumerable `messages` property (like `agentMeta`),
+* so it survives a JSON persist/resume round-trip; this accessor works on the
+* live settled snapshot and on a JSON-parsed persisted one alike. Returns `[]`
+* when no log was stamped (e.g. a default invoke-driven run).
+*
+* The write path is `runAgent(..., { messages })`: an explicit seed that
+* overrides the resume snapshot's stamped log (fold in a user reply on
+* resume, or start a run with prior history).
+*/
+function getAgentMessages(snapshot) {
+	const stamped = snapshot?.messages;
+	return Array.isArray(stamped) ? stamped : [];
+}
+/**
+* Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
+* the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
+* (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
+* can't read directly — see the `ai-sdk` tool pass-through and `openai-compat`
+* tool serialization.
+*/
+function isStandardSchema(value) {
+	return typeof value === "object" && value !== null && "~standard" in value;
+}
+/**
+* Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
+* `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
+* `z.toJSONSchema`), awaiting it when the producer is async. Returns
+* `undefined` when the schema doesn't expose the extension. Use this to build
+* a provider request's `response_format`/tool `parameters` from a schema.
+*/
+async function getJsonSchema(schema) {
+	const jsonSchemaFn = schema?.["~standard"].jsonSchema?.input;
+	if (!jsonSchemaFn) return;
+	const result = jsonSchemaFn();
+	return result instanceof Promise ? await result : result;
+}
+/**
+* Synchronous variant of {@link getJsonSchema}, for call sites that can't
+* await (building tool/event descriptors inline). An async JSON Schema
+* producer is treated as absent (returns `undefined`) — in practice Zod's
+* `z.toJSONSchema` resolves synchronously.
+*/
+function getJsonSchemaSync(schema) {
+	const jsonSchemaFn = schema?.["~standard"].jsonSchema?.input;
+	if (!jsonSchemaFn) return;
+	const result = jsonSchemaFn();
+	return result instanceof Promise ? void 0 : result;
+}
+/**
+* Validates `value` against a {@link StandardSchemaV1}, synchronously.
+* Throws if the schema's `validate` returns a `Promise` (async validation is
+* not supported anywhere in this library) or if validation reports issues —
+* in which case the thrown `Error.message` joins every issue message with
+* `', '`.
+*/
+function validateSchemaSync(schema, value) {
+	const result = schema["~standard"].validate(value);
+	if (result instanceof Promise) throw new Error("Async schema validation is not supported.");
+	if (result.issues) throw new Error(result.issues.map((issue) => issue.message).join(", "));
+	return result.value;
+}
+//#endregion
+//#region src/internal/registry.ts
+const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
+/**
+* Machine-carried wait-state predicates, keyed on the machine's root `config`
+* object. `config` is shared by reference across `machine.provide(...)` (unlike
+* the machine object itself), so a predicate registered here travels with the
+* machine through `.provide` — which is why it is keyed on `config`, not the
+* machine. Set by `setupAgent({ isSuspended })` in `createMachine`, read by
+* `runAgent` (below the host `options.isSuspended` override, above the timing
+* heuristic).
+*/
+const machineSuspensionPredicates = /* @__PURE__ */ new WeakMap();
+/** Reads the {@link machineSuspensionPredicates} predicate carried by `machine` (via its root `config`), if any. */
+function getMachineSuspensionPredicate(machine) {
+	const config = machine.config;
+	return config ? machineSuspensionPredicates.get(config) : void 0;
+}
+const unboundPlaceholderLogics = /* @__PURE__ */ new WeakSet();
+/** Text/decision logics created WITH their own executor (withExecutor or the
+* factory's second arg) — these are runnable as-is, so runAgent's bind check
+* must not reject them as direct-object invoke srcs. */
+const executorBoundLogics = /* @__PURE__ */ new WeakSet();
+function missingActor(src) {
+	const logic = createAsyncLogic({ run: async () => {
+		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${src}': ... } }).`);
+	} });
+	unboundPlaceholderLogics.add(logic);
+	return logic;
+}
+function isUnboundPlaceholder(logic) {
+	return !!logic && typeof logic === "object" && unboundPlaceholderLogics.has(logic);
+}
+function getRegisteredAgentExecutionOptions(machine, options) {
+	return {
+		...agentExecutionOptions.get(machine),
+		...options
+	};
+}
+//#endregion
+//#region src/text-logic.ts
+const USER_INPUT_ACTOR = "agent.userInput";
+const GENERATE_TEXT_ACTOR = "agent.generateText";
+const STREAM_TEXT_ACTOR = "agent.streamText";
+const DECIDE_ACTOR = "agent.decide";
+const PLAN_ACTOR = "agent.plan";
+const agentTextInputSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return !!value && typeof value === "object" && typeof value.model === "string" ? { value } : { issues: [{ message: "Expected agent text input with a model" }] };
+	}
+} };
+const unknownOutputSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return { value };
+	}
+} };
+const stringOutputSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return typeof value === "string" ? { value } : { issues: [{ message: "Expected string output" }] };
+	}
+} };
+function createBuiltinTextActor(src, mode, outputSchema) {
+	const logic = createAsyncLogic({ run: async () => {
+		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${src}': ... } }) or execute the returned agent request with executeAgentRequest(...).`);
+	} });
+	return Object.assign(logic, {
+		kind: "statelyai.textLogic",
+		mode,
+		schemas: {
+			input: agentTextInputSchema,
+			output: outputSchema
+		},
+		request(input) {
+			return validateSchemaSync(agentTextInputSchema, input);
+		},
+		async execute(input, executors) {
+			const { output } = await executeAgentTextRequest(mode, src, validateSchemaSync(agentTextInputSchema, input), executors);
+			return validateSchemaSync(outputSchema, output);
+		},
+		withExecutor(execute) {
+			return Object.assign(createTextLogic({
+				mode,
+				schemas: {
+					input: agentTextInputSchema,
+					output: outputSchema
+				},
+				name: ({ input }) => input.name,
+				model: ({ input }) => input.model,
+				system: ({ input }) => input.system,
+				prompt: ({ input }) => input.prompt,
+				messages: ({ input }) => input.messages,
+				tools: ({ input }) => input.tools,
+				toolChoice: ({ input }) => input.toolChoice,
+				reasoning: ({ input }) => input.reasoning,
+				temperature: ({ input }) => input.temperature,
+				maxOutputTokens: ({ input }) => input.maxOutputTokens,
+				topP: ({ input }) => input.topP,
+				topK: ({ input }) => input.topK,
+				seed: ({ input }) => input.seed,
+				stopSequences: ({ input }) => input.stopSequences,
+				metadata: ({ input }) => input.metadata
+			}, execute));
+		}
+	});
+}
+/** The unbound `agent.generateText`/`agent.streamText` builtins registered by setupAgent. @internal */
+const builtinTextActors = {
+	[GENERATE_TEXT_ACTOR]: createBuiltinTextActor(GENERATE_TEXT_ACTOR, "generate", unknownOutputSchema),
+	[STREAM_TEXT_ACTOR]: createBuiltinTextActor(STREAM_TEXT_ACTOR, "stream", stringOutputSchema)
+};
+/** The unbound `agent.userInput` builtin registered by setupAgent (an unbound-placeholder logic — see internal/registry.ts). @internal */
+const userInputActor = createAsyncLogic({ run: async () => {
+	throw new Error(`'${USER_INPUT_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${USER_INPUT_ACTOR}': ... } }).`);
+} });
+unboundPlaceholderLogics.add(userInputActor);
+/**
+* Validates a raw model/executor output against `schema`, returning the
+* parsed value. Thin wrapper over {@link validateSchemaSync} for parsing a
+* text request's structured output outside of `TextLogic.execute`/
+* `executeAgentRequest` (e.g. a custom host loop).
+*/
+function parseOutput(schema, output) {
+	return validateSchemaSync(schema, output);
+}
+/** Resolves a `ResolveTextLogicValue` (calls it if it's a function, else returns it as-is). @internal */
+function resolveTextLogicValue(value, args) {
+	return typeof value === "function" ? value(args) : value;
+}
+/**
+* Creates reusable, standalone {@link TextLogic}: an actor that, when run,
+* resolves typed input to typed output via a model call. Register the
+* result under `actorSources:` and invoke it by name (equivalent to what
+* `setupAgent({ requests })` builds internally for each request entry). Pass
+* `execute` here, or bind it later with `.withExecutor(...)`, a runtime
+* adapter's `machine.provide(...)`, or `runAgent`'s `generateText`/
+* `streamText` options.
+*
+* @example
+* ```ts
+* export const tellJoke = createTextLogic({
+*   mode: 'stream',
+*   schemas: { input: z.object({ topic: z.string() }), output: z.string() },
+*   model: 'openai/gpt-5.4-mini',
+*   system: 'You tell short, punchy jokes.',
+*   prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
+* });
+* ```
+*/
+function createTextLogic(config, execute) {
+	const request = (input) => {
+		const args = { input: validateSchemaSync(config.schemas.input, input) };
+		return {
+			name: resolveTextLogicValue(config.name, args),
+			model: resolveTextLogicValue(config.model, args),
+			system: resolveTextLogicValue(config.system, args),
+			prompt: resolveTextLogicValue(config.prompt, args),
+			messages: resolveTextLogicValue(config.messages, args),
+			tools: resolveTextLogicValue(config.tools, args),
+			toolChoice: resolveTextLogicValue(config.toolChoice, args),
+			outputSchema: config.schemas.output,
+			reasoning: resolveTextLogicValue(config.reasoning, args),
+			temperature: resolveTextLogicValue(config.temperature, args),
+			maxOutputTokens: resolveTextLogicValue(config.maxOutputTokens, args),
+			topP: resolveTextLogicValue(config.topP, args),
+			topK: resolveTextLogicValue(config.topK, args),
+			seed: resolveTextLogicValue(config.seed, args),
+			stopSequences: resolveTextLogicValue(config.stopSequences, args),
+			metadata: resolveTextLogicValue(config.metadata, args)
+		};
+	};
+	const logic = createAsyncLogic({ run: async ({ input, signal, system, self }, enq) => {
+		const resolvedRequest = request(input);
+		if (!execute) throw new Error("Text logic has no host execution. Pass an executor as the second argument to createTextLogic(...), provide a runtime adapter, or extract it with getAgentRequests(..., { actorSources }).");
+		const result = await execute({
+			input,
+			request: resolvedRequest,
+			signal,
+			system,
+			self,
+			emit: enq.emit
+		});
+		const selfId = self?.id;
+		const output = await normalizeGeneratorResult(result, typeof selfId === "string" ? selfId : "text logic", { request: resolvedRequest });
+		return validateSchemaSync(config.schemas.output, output);
+	} });
+	const textLogic = Object.assign(logic, {
+		kind: "statelyai.textLogic",
+		mode: config.mode ?? "generate",
+		schemas: config.schemas,
+		request,
+		async execute(input, executors) {
+			const { output } = await executeAgentTextRequest(config.mode ?? "generate", "textLogic", request(input), executors);
+			return validateSchemaSync(config.schemas.output, output);
+		},
+		withExecutor(nextExecute) {
+			return createTextLogic(config, nextExecute);
+		}
+	});
+	if (execute) executorBoundLogics.add(textLogic);
+	return textLogic;
+}
+/**
+* Binds a child machine's {@link TextLogic} to a raw
+* {@link AgentRequestExecutor} (the `generateText`/`streamText` shape hosts
+* implement). Encapsulates the `withExecutor` idiom child agents repeat:
+* default the request's `tools` to `{}`, forward the actor `signal`, call the
+* executor, and return its `{ output }` envelope. Use this to share ONE
+* executor across a parent and its nested children.
+*
+* @example
+* ```ts
+* childMachine.provide({
+*   actorSources: {
+*     researchTopic: bindRequestExecutor(setup.requests.researchTopic, generateText),
+*   },
+* });
+* ```
+*/
+function bindRequestExecutor(logic, executor) {
+	return logic.withExecutor(async ({ request, signal }) => {
+		const { output } = await executor({
+			...request,
+			tools: request.tools ?? {}
+		}, { signal });
+		return { output };
+	});
+}
+/** Type guard: true for any actor logic built by createTextLogic (checks the `kind` marker). @internal */
+function isTextLogic(value) {
+	return !!value && typeof value === "object" && value.kind === "statelyai.textLogic" && typeof value.request === "function";
+}
+/**
+* Classifies a text request's output schema as `'structured'` (its JSON
+* Schema is `type: 'object'`, `type: 'array'`, or a top-level union/
+* composition — `anyOf`/`oneOf`/`allOf`, which a bare `z.union`/
+* `z.discriminatedUnion` emits with no top-level `type`) or `'text'`
+* (anything else, including no schema). Reads the schema's
+* `~standard.jsonSchema.input()` extension — schemas without it are treated
+* as `'text'`.
+*/
+function getAgentOutputMode(schema) {
+	const jsonSchema = getStandardSchemaJson(schema);
+	if (!jsonSchema) return "text";
+	if (jsonSchema.type === "object" || jsonSchema.type === "array") return "structured";
+	if (jsonSchema.type === void 0 && ("anyOf" in jsonSchema || "oneOf" in jsonSchema || "allOf" in jsonSchema)) return "structured";
+	return "text";
+}
+/** True when {@link getAgentOutputMode} classifies `schema` as `'structured'`. */
+function isStructuredOutputSchema(schema) {
+	return getAgentOutputMode(schema) === "structured";
+}
+/**
+* Builds the uniform structured-output envelope schema every structured request
+* is sent to the provider as: a root object `{ result: <inner> }`, plus — when
+* `options.reasoning` is `true` — an optional string `reasoning` property listed
+* BEFORE `result` (property order nudges the model to reason first). This is THE
+* wire contract for structured output: a root object is universally accepted as
+* a provider response schema, unlike a bare union/array root that many providers
+* reject.
+*
+* The returned {@link StandardSchemaV1} validates the `{ reasoning?, result }`
+* envelope (unwrapping `result` through the original schema, capturing a string
+* `reasoning` when present) and exposes the enveloped JSON Schema. Adapters read
+* `.result` off the provider output before the machine validates it — so this is
+* transparent: user-facing output types stay the declared (un-enveloped) schema,
+* and `reasoning` is surfaced only on the raw executor result, never in machine
+* context/output.
+*/
+function buildEnvelopeSchema(inner, options = {}) {
+	const includeReasoning = options.reasoning === true;
+	const buildJson = (innerJson) => ({
+		type: "object",
+		properties: {
+			...includeReasoning ? { reasoning: { type: "string" } } : {},
+			result: innerJson ?? {}
+		},
+		required: ["result"],
+		additionalProperties: false
+	});
+	return { "~standard": {
+		version: 1,
+		vendor: "statelyai-agent",
+		validate(value) {
+			if (!value || typeof value !== "object" || !("result" in value)) return { issues: [{ message: "Expected a { result } envelope object" }] };
+			const innerResult = inner["~standard"].validate(value.result);
+			if (innerResult instanceof Promise) throw new Error("Async schema validation is not supported.");
+			if (innerResult.issues) return innerResult;
+			const envelope = { result: innerResult.value };
+			const reasoning = value.reasoning;
+			if (typeof reasoning === "string") envelope.reasoning = reasoning;
+			return { value: envelope };
+		},
+		jsonSchema: { input: () => {
+			const innerJson = inner["~standard"].jsonSchema?.input?.();
+			return innerJson instanceof Promise ? innerJson.then(buildJson) : buildJson(innerJson);
+		} }
+	} };
+}
+function getStandardSchemaJson(schema) {
+	const jsonSchema = (schema?.["~standard"])?.jsonSchema?.input?.();
+	return jsonSchema && !(jsonSchema instanceof Promise) ? jsonSchema : void 0;
+}
+/**
+* Merges request-declared and call-site `tools`, dispatches to the
+* `mode`-appropriate executor (`generateText`/`streamText`), and normalizes
+* the raw result via {@link normalizeGeneratorResult}. Shared by
+* `TextLogic.execute`, `executeAgentRequest`, and the `agent.generateText`/
+* `agent.streamText` builtins. Throws if no executor is registered for
+* `mode`.
+*
+* @internal
+*/
+async function executeAgentTextRequest(mode, id, input, executors, tools = {}, info) {
+	const request = {
+		...input,
+		tools: {
+			...input.tools,
+			...tools
+		}
+	};
+	const executor = mode === "stream" ? executors.streamText : executors.generateText;
+	if (!executor) throw new Error(`No executor provided for ${mode === "stream" ? "stream" : "generate"} request '${id}'.`);
+	const raw = await executor(request, info);
+	return {
+		output: await normalizeGeneratorResult(raw, id, {
+			request,
+			onChunk: info?.onChunk
+		}),
+		raw
+	};
+}
+function hasTextStream(value) {
+	return "textStream" in value && typeof value.textStream === "object" && !!value.textStream?.[Symbol.asyncIterator];
+}
+function parseRawAiSdkText(text, request, id) {
+	if (!request?.outputSchema) return text;
+	let parsed = text;
+	try {
+		parsed = JSON.parse(text);
+	} catch {}
+	try {
+		return parseOutput(request.outputSchema, parsed);
+	} catch (error) {
+		throw new Error(`Executor for '${id}' returned a raw AI SDK result whose text could not be parsed against the request's outputSchema. Structured-output requests through raw AI SDK generateText/streamText functions are best-effort — for reliable structured output, use createAiSdkExecutors from '@statelyai/agent/ai-sdk'. Cause: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Unwraps an executor result into the request's final output. Accepts three
+* shapes:
+* - `{ output }` (the {@link AgentRequestExecutorResult} envelope) — awaits and
+*   returns `output` (the fast path; unchanged).
+* - a raw AI SDK `streamText` result (`{ textStream }` async iterable) — iterates
+*   `textStream`, forwarding each string chunk to `info.onChunk`, then resolves
+*   the final text from `await result.text` if present else the accumulated chunks.
+* - a raw AI SDK `generateText` result (`{ text }` string or promise) — awaits `text`.
+*
+* For the two raw AI SDK shapes, if `info.request?.outputSchema` is set the final
+* text is parsed through {@link parseOutput} (best-effort); a parse failure throws
+* an error recommending `createAiSdkExecutors` from '@statelyai/agent/ai-sdk'.
+*
+* A value matching none of these is a runtime error naming `id`. This is
+* generator-result unwrapping only — decision results are extracted separately
+* by `resolveDecision`.
+*
+* @internal
+*/
+async function normalizeGeneratorResult(result, id = "text request", info) {
+	const resolved = await result;
+	if (!resolved || typeof resolved !== "object") throw invalidGeneratorResult(id);
+	if ("output" in resolved) return await resolved.output;
+	if (hasTextStream(resolved)) {
+		let accumulated = "";
+		for await (const chunk of resolved.textStream) {
+			accumulated += chunk;
+			info?.onChunk?.(chunk);
+		}
+		const finalText = "text" in resolved && resolved.text !== void 0 ? await resolved.text : accumulated;
+		return parseRawAiSdkText(String(finalText), info?.request, id);
+	}
+	if ("text" in resolved) {
+		const finalText = await resolved.text;
+		return parseRawAiSdkText(String(finalText), info?.request, id);
+	}
+	throw invalidGeneratorResult(id);
+}
+function invalidGeneratorResult(id) {
+	return /* @__PURE__ */ new Error(`Executor for '${id}' returned an invalid result: executors must return { output } (an envelope with the text string or structured object as \`output\`, plus optional passthrough fields). Raw Vercel AI SDK generateText/streamText results ({ text } or { textStream }) are also accepted.`);
+}
+//#endregion
+//#region src/events.ts
+/** Default prefix for the synthetic tool name generated per candidate event (e.g. `send_event_ASK`). Override per-request with {@link AgentEventToolNameResolver}. */
+const EVENT_TOOL_PREFIX = "send_event_";
+function hashString(value) {
+	let hash = 5381;
+	for (let i = 0; i < value.length; i++) hash = hash * 33 ^ value.charCodeAt(i);
+	return (hash >>> 0).toString(36);
+}
+function sanitizeEventToolName(eventType) {
+	const base = `${EVENT_TOOL_PREFIX}${eventType.replace(/[^a-zA-Z0-9_-]/g, "_") || "event"}`;
+	if (base.length <= 64) return base;
+	const hash = hashString(eventType);
+	const prefixLength = 64 - hash.length - 1;
+	return `${base.slice(0, prefixLength)}_${hash}`;
+}
+function disambiguateEventToolName(toolName, eventType, usedToolNames) {
+	if (!usedToolNames.has(toolName)) {
+		usedToolNames.add(toolName);
+		return toolName;
+	}
+	const suffix = `_${hashString(eventType)}`;
+	const uniqueToolName = `${toolName.slice(0, 64 - suffix.length)}${suffix}`;
+	usedToolNames.add(uniqueToolName);
+	return uniqueToolName;
+}
+/**
+* True when an event type matches an `allowedEvents` entry: an exact type,
+* `'*'` (every event), or a `'prefix.*'` wildcard matching any deeper
+* segment (`'todo.*'` matches `'todo.add'` and `'todo.list.clear'`, not
+* `'todo'` itself — mirroring xstate's partial wildcard events).
+*/
+function matchesEventPattern(eventType, pattern) {
+	if (pattern === "*") return true;
+	if (pattern.endsWith(".*")) return eventType.startsWith(`${pattern.slice(0, -1)}`);
+	return eventType === pattern;
+}
+/** True when an `allowedEvents` entry is a wildcard pattern rather than a concrete event type. @internal */
+function isEventPattern(entry) {
+	return entry === "*" || entry.endsWith(".*");
+}
+/**
+* Runtime-validates a dynamically-built `{ type, ...payload }` event against a
+* snapshot's currently-accepted events (via {@link getAcceptedEvents}) and,
+* when one is registered, the event type's payload schema — returning the
+* event typed as the machine's event union (recovered from the snapshot type)
+* so it can be sent to `runAgent({ event })` / `actor.send(...)` without an
+* `as never` cast. For generic, meta-driven hosts that assemble events from
+* user input or a wire message.
+*
+* Throws a descriptive error when `event.type` is not currently accepted
+* (listing the accepted types) or when its payload fails the registered schema.
+* Pass event payload schemas via `options.events`/`options.schemas` (the same
+* shape {@link getAcceptedEvents} takes) — the accepted TYPES always come from
+* the live snapshot; the schemas only add payload validation.
+*
+* @example
+* ```ts
+* const event = parseAgentEvent(result.snapshot, rawEvent, { events: schemas.events });
+* result = await runAgent(machine, { snapshot: result.snapshot, event, executors });
+* ```
+*/
+function parseAgentEvent(snapshot, event, options = {}) {
+	const accepted = getAcceptedEvents(snapshot, options);
+	const descriptor = accepted.find((candidate) => candidate.type === event.type);
+	if (!descriptor) throw new Error(`parseAgentEvent: '${event.type}' is not an accepted event in the current state. Accepted: ${accepted.map((candidate) => candidate.type).join(", ") || "(none)"}.`);
+	if (descriptor.inputSchema) {
+		const { type, ...payload } = event;
+		try {
+			return {
+				...validateSchemaSync(descriptor.inputSchema, payload),
+				type
+			};
+		} catch (error) {
+			throw new Error(`parseAgentEvent: '${event.type}' payload failed validation: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return event;
+}
+function getAcceptedEvents(snapshot, options = {}) {
+	const eventTypes = options.eventTypes;
+	const seen = /* @__PURE__ */ new Set();
+	const usedToolNames = /* @__PURE__ */ new Set();
+	return getNextTransitions(snapshot).flatMap((transitionDefinition) => {
+		const eventType = transitionDefinition.eventType;
+		if (!eventType || eventType === "*" || eventType.startsWith("xstate.") || eventTypes && !eventTypes.some((pattern) => matchesEventPattern(eventType, pattern)) || seen.has(eventType)) return [];
+		seen.add(eventType);
+		const defaultToolName = sanitizeEventToolName(eventType);
+		const toolName = options.eventToolName ? options.eventToolName({
+			eventType,
+			defaultToolName
+		}) : disambiguateEventToolName(defaultToolName, eventType, usedToolNames);
+		const inputSchema = (options.events ?? options.schemas?.events)?.[eventType];
+		return [{
+			type: eventType,
+			toolName,
+			...inputSchema ? { inputSchema } : {}
+		}];
+	});
+}
+//#endregion
+//#region src/decision.ts
+function decideRequestFromInput(input) {
+	const allowedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input) ?? [];
+	return {
+		kind: "decision",
+		id: "",
+		model: input.model,
+		system: input.system,
+		prompt: input.prompt,
+		messages: input.messages,
+		events: allowedEventTypes.filter((type) => !isEventPattern(type)).map((type) => ({
+			type,
+			toolName: sanitizeEventToolName(type)
+		})),
+		attempts: [],
+		temperature: input.temperature,
+		maxOutputTokens: input.maxOutputTokens,
+		topP: input.topP,
+		topK: input.topK,
+		seed: input.seed,
+		stopSequences: input.stopSequences,
+		metadata: input.metadata
+	};
+}
+function decideActorWithExecutor(execute) {
+	const logic = createAsyncLogic({ run: async ({ input, signal }) => {
+		if (!execute) throw new Error(`'${DECIDE_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${DECIDE_ACTOR}': ... } }) or resolve the returned agent request with resolveDecision(...).`);
+		const resolvedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input);
+		if (resolvedEventTypes === void 0) throw new Error(`'${DECIDE_ACTOR}' input has omitted \`allowedEvents\`, which means "all currently-legal events" — but that requires a snapshot-aware host (runAgent or the step path) to resolve. Under a bare createActor(...), declare \`allowedEvents\` explicitly to use this actor here.`);
+		if (resolvedEventTypes.some(isEventPattern)) throw new Error(`'${DECIDE_ACTOR}' input uses wildcard \`allowedEvents\` patterns, which expand against the live snapshot — that requires a snapshot-aware host (runAgent or the step path). Under a bare createActor(...), list event types explicitly.`);
+		return resolveDecision(decideRequestFromInput(input), execute, {
+			maxRetries: input.maxRetries ?? 2,
+			signal
+		});
+	} });
+	return Object.assign(logic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries: 2,
+		request: decideRequestFromInput,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(input.allowedEvents, input),
+		withExecutor: (nextExecute) => decideActorWithExecutor(nextExecute)
+	});
+}
+function createDecideActor() {
+	return decideActorWithExecutor();
+}
+/**
+* Reserved event type the `agent.plan` builtin adds to every step's
+* candidates as the explicit "no further action needed" move. Choosing it
+* ends the plan (`stopped: 'done'`); it is never sent to the machine, so
+* machines need no no-op sentinel event of their own.
+*/
+const PLAN_DONE_EVENT_TYPE = "agent.plan.done";
+function createPlanActor() {
+	const logic = createLogic({
+		context: ({ input }) => ({
+			applied: [],
+			stepsRemaining: input.maxSteps ?? 8,
+			stopped: null
+		}),
+		run: ({ context, event }) => event.type === "plan.applied" ? { context: {
+			...context,
+			applied: [...context.applied, event.event],
+			stepsRemaining: context.stepsRemaining - 1
+		} } : event.type === "plan.ended" ? {
+			context: {
+				...context,
+				stopped: event.stopped
+			},
+			status: "done",
+			output: {
+				steps: context.applied,
+				stopped: event.stopped
+			}
+		} : void 0
+	});
+	return Object.assign(logic, {
+		kind: "statelyai.planLogic",
+		maxRetries: 2,
+		request: decideRequestFromInput,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(input.allowedEvents, input)
+	});
+}
+const PLAN_LEDGER_SCOPE = { emit: () => {} };
+/**
+* Builds a fresh plan ledger snapshot from resolved plan input — the shared
+* starting point for BOTH hosts (the step path reads the invoke child's own
+* initial snapshot; runAgent seeds a local ledger with this). @internal
+*/
+function initialPlanLedger(logic, input) {
+	return logic.getInitialSnapshot(PLAN_LEDGER_SCOPE, input);
+}
+/**
+* Advances a plan ledger by one {@link PlanLedgerEvent}, returning the next
+* snapshot (unwrapping `createLogic`'s `[snapshot, effects]` tuple). Pure — no
+* mutation of the input snapshot. @internal
+*/
+function advancePlanLedger(logic, snapshot, event) {
+	const result = logic.transition(snapshot, event, PLAN_LEDGER_SCOPE);
+	return Array.isArray(result) ? result[0] : result;
+}
+/** Type guard: true for the `agent.plan` builtin logic (checks the `kind` marker). @internal */
+function isPlanLogic(logic) {
+	return !!logic && logic.kind === "statelyai.planLogic";
+}
+function resolveAllowedEventTypes(allowedEvents, input) {
+	if (allowedEvents === void 0) return;
+	const resolved = typeof allowedEvents === "function" ? allowedEvents({ input }) : allowedEvents;
+	return typeof resolved === "string" ? [resolved] : resolved;
+}
+/** Type guard: true for any actor logic built by createDecisionLogic/createDecideActor (checks the `kind` marker). @internal */
+function isDecisionLogic(value) {
+	return !!value && typeof value === "object" && value.kind === "statelyai.decisionLogic" && typeof value.request === "function";
+}
+/**
+* Thrown by {@link resolveDecision} when every attempt (up to
+* `maxRetries + 1` of them) fails one of the three checks recorded in
+* {@link DecisionAttempt.failure}. Carries the full `attempts` list for
+* diagnostics; a machine typically routes this via the decision invoke's
+* `onError`.
+*/
+var DecisionExhaustedError = class extends Error {
+	attempts;
+	constructor(attempts) {
+		super(`Decision exhausted after ${attempts.length} attempt${attempts.length === 1 ? "" : "s"}: ` + attempts.map((attempt) => attempt.reason).join("; "));
+		this.name = "DecisionExhaustedError";
+		this.attempts = attempts;
+	}
+};
+/**
+* Renders a decision request's prior failed `attempts` into feedback messages
+* a host appends to the model call so retries converge — the transport-agnostic
+* "your last choice failed because X, choose again from Y" logic every adapter
+* and raw-SDK host repeats. Returns one `user`-role {@link AgentMessage} per
+* attempt (empty when there are none); adapters map each onto their wire
+* message shape (`attempt.content` is always a string). Core never rewrites the
+* request itself — this only turns the recorded attempts into messages.
+*
+* @example
+* ```ts
+* const messages = [...baseMessages, ...renderDecisionAttempts(request)];
+* ```
+*/
+function renderDecisionAttempts(request) {
+	const types = request.events.map((event) => event.type).join(", ") || "(none)";
+	return request.attempts.map((attempt) => userMessage(`Your previous choice failed: ${attempt.reason}. Choose again from: ${types}`));
+}
+/**
+* Validation + retry core for decisions. No provider mechanics — the
+* `executor` is responsible for making the model choose an event; this
+* function only validates the choice and retries on failure, up to
+* `options.maxRetries` (default 2, i.e. up to 3 attempts total).
+*
+* Each attempt is checked in order and can fail one of three ways (recorded
+* as a {@link DecisionAttempt}): `'unknown-event'` (the chosen `type` is not
+* among `request.events`), `'invalid-payload'` (the payload fails that
+* event's schema), or `'rejected-by-guard'` (passes both checks but
+* `options.canTake` returns `false` — a type/payload-legal event the
+* machine's guard rejects right now; omit `canTake` to skip this check).
+* Every prior failed attempt for this call is fed back to the executor on
+* the next attempt via `request.attempts`, so an adapter can render "your
+* last choice failed because X — try again" into the next model call; core
+* never rewrites the request itself. Exhausting all attempts throws
+* {@link DecisionExhaustedError} with the full attempts list.
+*
+* @example
+* ```ts
+* const event = await resolveDecision(request, decide, {
+*   canTake: (e) => snapshot.can(e),
+* });
+* ```
+*/
+async function resolveDecision(request, executor, options = {}) {
+	const maxRetries = options.maxRetries ?? 2;
+	const attempts = [];
+	const eventsByType = new Map(request.events.map((event) => [event.type, event]));
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		options.signal?.throwIfAborted();
+		const { event } = await executor({
+			...request,
+			attempts: [...attempts],
+			signal: options.signal
+		});
+		const descriptor = eventsByType.get(event.type);
+		if (!descriptor) {
+			attempts.push({
+				event,
+				failure: "unknown-event",
+				reason: `'${event.type}' is not among the currently allowed events: ${request.events.map((candidate) => candidate.type).join(", ") || "(none)"}.`
+			});
+			continue;
+		}
+		let validatedEvent = event;
+		if (descriptor.inputSchema) {
+			const { type, ...payload } = event;
+			try {
+				validatedEvent = {
+					...validateSchemaSync(descriptor.inputSchema, payload),
+					type
+				};
+			} catch (error) {
+				attempts.push({
+					event,
+					failure: "invalid-payload",
+					reason: `'${event.type}' payload failed validation: ${error instanceof Error ? error.message : String(error)}`
+				});
+				continue;
+			}
+		}
+		if (options.canTake?.(validatedEvent) === false) {
+			attempts.push({
+				event: validatedEvent,
+				failure: "rejected-by-guard",
+				reason: `'${validatedEvent.type}' is not currently takeable (guard rejected it).`
+			});
+			continue;
+		}
+		return validatedEvent;
+	}
+	throw new DecisionExhaustedError(attempts);
+}
+//#endregion
+export { agentExecutionOptions as A, getJsonSchema as B, executeAgentTextRequest as C, normalizeGeneratorResult as D, isTextLogic as E, machineSuspensionPredicates as F, persistSnapshot as G, getMachineStructuralHash as H, missingActor as I, userMessage as J, systemMessage as K, assistantMessage as L, getMachineSuspensionPredicate as M, getRegisteredAgentExecutionOptions as N, parseOutput as O, isUnboundPlaceholder as P, findNonSerializableContextPaths as R, createTextLogic as S, isStructuredOutputSchema as T, getStateMeta as U, getJsonSchemaSync as V, isStandardSchema as W, validateSchemaSync as Y, PLAN_ACTOR as _, createPlanActor as a, buildEnvelopeSchema as b, isPlanLogic as c, EVENT_TOOL_PREFIX as d, getAcceptedEvents as f, DECIDE_ACTOR as g, sanitizeEventToolName as h, createDecideActor as i, executorBoundLogics as j, userInputActor as k, renderDecisionAttempts as l, parseAgentEvent as m, PLAN_DONE_EVENT_TYPE as n, initialPlanLedger as o, matchesEventPattern as p, toolMessage as q, advancePlanLedger as r, isDecisionLogic as s, DecisionExhaustedError as t, resolveDecision as u, USER_INPUT_ACTOR as v, getAgentOutputMode as w, builtinTextActors as x, bindRequestExecutor as y, getAgentMessages as z };